AGENTS.md 角色路由重构 + IR 挂靠产品仓（ADR-0095） - #387
Merged
Merged
Conversation
- 新增 docs/agent/ROLE-{IR,SPEC,IMPLEMENT,ACCEPT}.md 四角色指引
- AGENTS.md：入口协议块 v2（第 0 步按意图定角色）+ 角色路由节（仍 60 行）
- NAVIGATION/PLAYBOOK/profile：feature IR 一律开在对应产品仓，废止 IR 挂 .github 规定；
spec PR 测试设计逐类讨论+holdout 必备；弱模型 3 次熔断 PM 接手
- scripts/ghcb accept 支持 [repo] 参数；REPOS.yaml entry_protocol 扩展到全部活跃仓
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (10)
📝 WalkthroughWalkthrough本次变更将入口协议升级为 v2，新增 IR、spec、实现和验收角色指南，更新产品仓与治理仓路由，登记多个仓库，并扩展 Changes协议与角色流程
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Co-authored-by: traeagent <traeagent@users.noreply.github.com>
PR Summary by QodoRoute agent roles and anchor feature IRs in product repositories
AI Description
Diagram
High-Level Assessment
Files changed (37)
|
Code Review by Qodo
1. Completed cards block T9
|
| 1. **盘点**：`bash ghcb board`（逐活跃仓）列出全部 `state:*` 的卡与 `type:intent` | ||
| 的 IR——不只看 ready；对每张卡 / 每条 IR 判定「是否真的完成」： | ||
| - 卡：T8 判据=存在 body 含 `Card: <repo>#<n>` 且**已合并**的 PR（合并事实即 | ||
| 全 gate 绿的载体）；`gh pr list --state merged` / issue 评论可核对。 |
There was a problem hiding this comment.
1. Direct gh bypasses app token 📘 Rule violation ⛨ Security
The new acceptance guide tells resident agents to execute gh pr list directly, without obtaining a single-repository, short-lived cloudbrid-agent token through scripts/ghcb. This can cause acceptance checks to run under a user's PAT or other ambient gh credential.
Agent Prompt
## Issue description
The acceptance instructions invoke `gh pr list` with ambient authentication instead of a repository-scoped `cloudbrid-agent` token.
## Issue Context
PR Compliance ID 2778539 requires resident-agent GitHub operations to authenticate through `scripts/ghcb`, with single-repository scope and a maximum one-hour expiry.
## Fix Focus Areas
- docs/agent/ROLE-ACCEPT.md[18-18]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+19
to
+20
| - IR：T9 判据=全部子卡 `state:done` + `specs/<IR-NNNN>/acceptance.md` 存在 | ||
| （子卡=body 含 `父意图: #<n>` 的 issue）。 |
There was a problem hiding this comment.
3. Completed cards block t9 🐞 Bug ≡ Correctness
ROLE-ACCEPT says child cards only need state:done, but T9 rejects every open child card regardless of labels, while T8 only swaps the state label and never closes the issue. Following the new role instructions therefore leaves normal completed cards open and makes IR acceptance fail indefinitely.
Agent Prompt
## Issue description
T9 treats completed but open child cards as pending, although the documented completion contract only requires `state:done` and T8 does not close cards.
## Issue Context
Either T9 must inspect child-card state labels, or T8 must close completed card issues and the role instructions must explicitly require that behavior.
## Fix Focus Areas
- docs/agent/ROLE-ACCEPT.md[15-27]
- governance/transitions.yaml[99-116]
- .github/workflows/conductor.yml[442-468]
- .github/workflows/conductor.yml[512-516]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+23
to
+25
| 1. **编号**：标题以 `IR-NNNN` 前缀开头，编号全局唯一——开立前用 | ||
| `bash ghcb board`（各活跃仓轮查）核对已用编号，避免撞号。机器侧（conductor / | ||
| ghcb）从标题提取编号；无前缀时会退化为 issue 号兜底，勿依赖兜底。 |
There was a problem hiding this comment.
4. Ir duplicate check is local 🐞 Bug ≡ Correctness
The new global IR-number rule tells agents to use ghcb board, but that command queries only one repository and only open issues. It therefore misses IDs in every other repository and all closed historical IRs, allowing duplicate IR-NNNN identifiers despite the claimed global uniqueness.
Agent Prompt
## Issue description
`ghcb board` cannot prove that an IR number is globally unused because it searches one repository and open issues only.
## Issue Context
Global uniqueness requires an organization-wide, history-inclusive lookup or a centralized allocator/registry; documentation should not claim the current command provides this guarantee.
## Fix Focus Areas
- docs/agent/ROLE-IR.md[21-25]
- docs/pm/PLAYBOOK.md[48-51]
- scripts/ghcb[95-105]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+43
to
+45
| 封存验收场景条目，经验证者 APP 注册到 holdout 仓（注册入口 | ||
| `scripts/holdout-register.sh`，由 verifier-app 令牌调用；**cloudbrid-agent 严禁 | ||
| 挂载 holdout**，DECISION-02 隔离不变量）。spec/卡/PR 对 holdout 只能引用 |
There was a problem hiding this comment.
5. Holdout registration path is broken 🐞 Bug ≡ Correctness
The new mandatory holdout step directs agents to scripts/holdout-register.sh, but that script resolves the governance root two levels above scripts/ and then searches another level up for CI-Workflows. In a normal sibling checkout it cannot find holdout_registry.py and exits 2, so spec authors cannot complete the required registration.
Agent Prompt
## Issue description
The mandatory holdout registration script computes both its repository root and the sibling CI-Workflows path incorrectly.
## Issue Context
From `<parent>/.github/scripts`, the repository root is `scripts/..`, and the sibling workflow repository is then `<repo-root>/../CI-Workflows`.
## Fix Focus Areas
- docs/agent/ROLE-SPEC.md[42-46]
- scripts/holdout-register.sh[26-35]
- scripts/holdout-register.sh[71-80]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
|
|
||
| - **Feature 流（签署前置）**：[intent 表单](https://github.com/Cloudbird-Software/.github/issues/new?template=intent.yml)提交 IR → owner 签署 → spec（PM 自著或 spec-author 快速通道）→ 红队审计 → 开卡 → 实现（CNB 默认）→ 验收。规格与波次计划见 [`specs/`](https://github.com/Cloudbird-Software/.github/tree/main/specs)。 | ||
| - **Bug 流（复现前置，签署点后移——ADR-0064）**：[bug 表单](https://github.com/Cloudbird-Software/.github/issues/new?template=bug.yml)提交即机器复现，三值判定（reproduced / cannot-reproduce / inconclusive），reproduced 后修复合入自动回写状态。 | ||
| - **Feature 流（签署前置）**：feature IR 开在**对应产品仓**的 issue（[intent 表单](https://github.com/Cloudbird-Software/.github/issues/new?template=intent.yml)经 org 级继承，各仓可用；ADR-0095）→ owner 签署 → spec（PM 自著或 spec-author 快速通道；spec PR 必带测试设计逐类讨论+holdout，红队审计，开 spec 的 agent 不得直接实现）→ 开卡 → 实现（弱模型优先：子 agent / CNB 池默认，3 次熔断 PM 接手）→ 验收。治理意图 IR 开 [.github 仓](https://github.com/Cloudbird-Software/.github/issues/new?template=intent.yml)。规格与波次计划见 [`specs/`](https://github.com/Cloudbird-Software/.github/tree/main/specs)；按角色选路的指引见 [docs/agent/](https://github.com/Cloudbird-Software/.github/tree/main/docs/agent)（ADR-0095）。 |
There was a problem hiding this comment.
6. Feature form targets governance 🐞 Bug ≡ Correctness
The profile's Feature-flow link is hard-coded to Cloudbird-Software/.github/issues/new, so clicking it creates the IR in the governance repository even though the same sentence requires feature IRs in the corresponding product repository. This directly steers users into the location ADR-0095 is intended to retire.
Agent Prompt
## Issue description
The Feature-flow hyperlink opens the `.github` repository's form instead of the selected product repository's form.
## Issue Context
A static organization-profile link cannot infer the intended product repository; route users through repository selection/instructions rather than a fixed `.github/issues/new` URL.
## Fix Focus Areas
- profile/README.md[32-35]
- docs/agent/ROLE-IR.md[11-19]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
|
|
||
| 1. **自带子 agent**：你自己的子 agent / 任务拆分工具（若有）。 | ||
| 2. **CNB 免费算力池**（组织默认实现引擎）： | ||
| - 派单：`bash ghcb dispatch <卡#> [repo] [--tier light|std] [--account <alias>]` |
There was a problem hiding this comment.
8. Ghcb dispatch [repo] breaks with options 🐞 Bug ≡ Correctness
ROLE-IMPLEMENT.md documents bash ghcb dispatch <卡#> [repo] [--tier light|std] [--account <alias>]
implying [repo] can be omitted while options are supplied, but scripts/ghcb unconditionally consumes
argv[3] as REPO_ARG via REPO_ARG="${3:-$(origin_repo)}"; shift 3. Calling `ghcb dispatch 123
--tier std` (omitting repo) makes REPO_ARG="--tier", producing a malformed repo
Cloudbird-Software/--tier and silently dropping the intended std tier back to default light.
Agent Prompt
## Issue description
Docs (docs/agent/ROLE-IMPLEMENT.md line 17) show `ghcb dispatch <卡#> [repo] [--tier ...] [--account ...]` implying repo is optional even when flags follow, but scripts/ghcb's `dispatch` subcommand blindly assigns argv[3] to REPO_ARG and shifts 3 positional args before parsing flags, so `ghcb dispatch 123 --tier std` treats `--tier` as the repo name and drops `std`.
## Issue Context
The PR changed dispatch's sibling `accept` subcommand to add an optional trailing `[repo]` argument (ADR-0095) and updated ROLE-IMPLEMENT.md to document the same optional-repo pattern for `dispatch`, but did not update the `dispatch` argument-parsing logic to handle a flag appearing in position 3.
## Fix Focus Areas
- scripts/ghcb[109-118]
- docs/agent/ROLE-IMPLEMENT.md[17]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
+13
to
+19
| - **产品/feature 意图** → 开在**对应的产品仓**（如 `Cloudbird-Software/<产品仓>`）。 | ||
| issue 模板 `intent.yml` 经 org 级 `.github/ISSUE_TEMPLATE` 自动被 org 内全部仓继承—— | ||
| 在产品仓 New issue 即可选用；若模板/`type:intent` 标签在本仓缺失，属治理漂移， | ||
| 报 owner（apply.sh §7 同步治理标签），不要手工绕过。 | ||
| - **治理意图**（改治理面：governance/ 政策、门禁、流程本身）→ 开在 `.github` 治理仓。 | ||
| - 历史先例：`Viral_Radar#1`（产品仓 IR）。废止的旧规定「IR 一律在 .github 仓开」 | ||
| 已由 ADR-0095 移除——不要把 feature IR 开到治理仓。 |
There was a problem hiding this comment.
9. Ir routing docs overclaim product-repo automation 🐞 Bug ≡ Correctness
ROLE-IR.md and ROLE-ACCEPT.md now direct feature IR creation and ghcb accept to product repositories and describe their lifecycle as using the same mechanically enforced owner-label and conductor T7/T8/T9 state machine as governance IRs, but conductor's route job runs only for Cloudbird-Software/.github, so product-repository events never reach it. Consequently, state transitions require manual owner labeling and T9 acceptance is not enforced on the primary feature-IR path introduced by this PR.
Agent Prompt
## Issue description
Feature IRs are now opened and accepted in product repositories, but the conductor workflow implementing owner-label transitions and T7/T8/T9 predicates only runs when `github.repository == 'Cloudbird-Software/.github'`. Ensure product-repository IR events execute the promised state machine and T9 acceptance predicate rather than requiring manual state changes.
## Issue Context
ADR-0095, the new role documentation, and the `ghcb accept` repository argument move the primary feature-IR path from `.github` into product repositories while describing the lifecycle as mechanically enforced. The existing workflow remains repository-local, and its T9 implementation checks the locally checked-out `.github/specs` tree even though it reads the event repository, so forwarding events alone without checking out the target repository is insufficient.
## Fix Focus Areas
- docs/agent/ROLE-IR.md[13-19]
- docs/agent/ROLE-IR.md[34-36]
- docs/agent/ROLE-ACCEPT.md[16-27]
- scripts/ghcb[127-142]
- .github/workflows/conductor.yml[2-35]
- .github/workflows/conductor.yml[442-468]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
This was referenced Aug 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Card: 无（治理面 C1 变更——PR 引用 ADR-0095，archive#32）
变更
1. 四角色指引（新增 docs/agent/）
ROLE-IR.md：开 IR——issue 即 IR，feature 意图开在对应产品仓（无需 PR），治理意图开 .github；编号 IR-NNNN 全局唯一；不代签ROLE-SPEC.md：IR→spec——spec PR 流程：测试设计逐类讨论（testing.yaml 清单 adopt-or-reject：差分/属性/模糊/蜕变/变异…）+ holdout 测试设计（verifier-app 注册，引用仅 id@sha8）+ 红队攻击测试设置合理性；spec agent 不得直接实现ROLE-IMPLEMENT.md：实现（PM 职责）——弱模型优先（自带子 agent / CNB 池ghcb dispatch）；fan-out=工具非流程（PM 裁量、append-only）；边做边推 PR、全 CI/review 清零才合并；弱模型 3 次不过 PM 自己接手；holdout 失败=修实现不修试卷（quarantine/needs-human）ROLE-ACCEPT.md：验收与 bug 修复——人类让处理 issues 走此路：卡/IR 完成度检查（未完成开 bug issue 修复关闭）；bug/incident 复现三值判定（无法复现关闭/能复现修复→PR→合并→关闭）2. AGENTS.md 重构（仍 60 行）
3. IR 挂靠规则修改（废止「IR 一律在 .github 仓开」）
docs/NAVIGATION.md：§0/§1/§2 改为按意图路由 + IR 开在产品仓；锚点全保留docs/pm/PLAYBOOK.md§2/§4/§5：开 IR=产品仓 issue；spec PR 增加测试设计逐类讨论与 holdout 必备条款；角色文件引用；锚点全保留profile/README.md：意图→交付链路改为产品仓 IR + 角色路由入口4. 机器面
scripts/ghcbaccept 子命令支持[repo]参数（feature IR 在产品仓，缺省 .github 兼容治理 IR）governance/REPOS.yaml：entry_protocol: true 扩展到全部 15 活跃仓（协议块 v2 全仓对账）本地验证
make gates-pr全绿（test-navigation 35/35，AGENTS.md 60 行，协议块标记完整，断链零）合并顺序（强依赖）
ADR-0095
Summary by CodeRabbit
新功能
ghcb accept支持指定仓库，未指定时默认查询治理仓库。文档