导航收口：全入口路由表 + 断链机械检测（#363；ADR-0055/0085/0064） #364
There are no files selected for viewing
Binary file not shown.
Binary file not shown.
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,67 @@ | ||
| # NAVIGATION —— 全入口路由（从哪进来 → 该做什么 → 怎么做） | ||
|
|
||
| > 目的：任何 agent / 人从任意入口（org 首页、任意仓、issue 表单、Actions）落地后， | ||
| > 30 秒内定位「该做什么、怎么做」。这是 #362 治理可达性审计（32 次 PM 模拟运行， | ||
| > 置信度 4.8/10）的收口件之一。 | ||
| > 依据：ADR-0055（统一入口协议）· ADR-0085（PM 优先范式）· ADR-0064（Bug 流）。 | ||
| > 维护契约：新增入口面（仓 / 模板 / 表单 / 工作流）须同步本表；本表引用的本仓文件 | ||
| > 必须真实存在——断链由 `governance/tests/test-navigation.sh` 机械检测（gate 每 PR 跑）。 | ||
|
|
||
| ## §0 三句话版本 | ||
|
|
||
| 1. **在产品/支撑仓干活** → 唯一工作凭证是卡：`bash ghcb next <owner/repo>` 找 | ||
| `state:ready` 卡 → `bash ghcb claim <n>` 认领 → 实现 → PR body 带 `Card: <owner>/<repo>#<n>` 行。 | ||
| 2. **要改治理面**（governance/ standards/ scripts/ .github/ specs/ profile/ CODEOWNERS， | ||
| 以及按 AGENTS.md 硬规则视同 C1 的 docs/ 与 Makefile）→ **不需要卡**：直接开 PR + | ||
|
Comment on lines
+12
to
+15
There was a problem hiding this comment. 1. Missing card: metadata line The PR description does not include a required Card: <owner>/<repo>#<n> metadata line, so downstream tooling cannot reliably parse the work item linkage. This violates the compliance requirement for PR body card metadata. Agent Prompt
|
||
| 引用 ADR-NNNN + owner review（C1 流程，见 §2）。 | ||
| 3. **带全局职责进来（PM）** → [AGENTS.md](../AGENTS.md)「PM 优先」节 + | ||
| [docs/pm/PLAYBOOK.md](pm/PLAYBOOK.md) 全文 + archive 仓 `runs/` 最近 4 周运行报告。 | ||
|
|
||
| ## §1 入口矩阵 | ||
|
|
||
| | 你在哪 / 你是谁 | 先读 | 然后 | | ||
| |---|---|---| | ||
| | org 首页（profile/README.md） | 本表 §0 | 按角色下钻；仓库全量真源 [governance/REPOS.yaml](../governance/REPOS.yaml) | | ||
| | 产品仓（AI_Web_School / mutual / QW_Arena1 …） | 该仓根部 AGENTS.md 的入口协议块 | 取 ghcb（AGENTS.md 内钉 SHA 命令）→ `ghcb next <owner/repo>` 找卡；无卡不开工，新想法走 intent 表单 | | ||
| | 治理仓 .github | [AGENTS.md](../AGENTS.md)（本仓契约） | 治理变更走 C1（§2，无需卡）；卡工作照入口协议块 | | ||
| | 治理仓 CI-Workflows | 该仓 AGENTS.md | workflow/pipeline 变更=C1 面（.github/ 路径）：PR 引 ADR + owner review | | ||
| | 治理仓 archive | `runs/README.md` | 运行报告只追加（append-only）；ADR 落 `adr/` + 更新 INDEX.yaml | | ||
| | 支撑仓 cnb-bridge | 仓内 `REMOVAL.md` + `accounts.yaml` | 池运维 owner 面；派单一律经 .github 仓 `cnb-dispatch` 工作流（key 不入上下文） | | ||
| | 支撑仓 arbiter / holdout | —（owner 直管） | 你不直接调用（见 §2「conductor/arbiter」）；holdout 对 agent 只读 | | ||
| | 发现 bug | [.github/ISSUE_TEMPLATE/bug.yml](../.github/ISSUE_TEMPLATE/bug.yml) | 提交即机器复现（B1–B5，ADR-0064）：reproduced → 修复合入 → fixed → done | | ||
| | 有新意图（feature/治理意图） | [.github/ISSUE_TEMPLATE/intent.yml](../.github/ISSUE_TEMPLATE/intent.yml) | IR 流：owner 签署 → spec（自著合法）→ 红队 → 开卡（PLAYBOOK §2–§3） | | ||
| | 想看全局进度 | `bash ghcb board` | 全状态流水线（ir-draft…done 的 IR 与卡，非只 ready 卡） | | ||
|
|
||
| ## §2 高频困惑（#362 实测断裂点，逐条落点） | ||
|
|
||
| - **spec 放哪**：治理 specs 在 `.github/specs/IR-XXXX/`；产品 feature specs 落产品仓 | ||
| 本仓 `specs/<IR-NNNN>/`（IR 一律在 .github 仓开，编号全局唯一；spec 与 suite 随实现仓走， | ||
| suite 门 T-14/T5 按所在仓生效）。 | ||
| - **治理变更要不要开卡**：不要。卡流程（T7→T8）只承载 spec 派生的实现工作； | ||
| 治理变更走 C1：PR + 引用 ADR-NNNN（新建或引既有）+ owner-only review + merge。 | ||
| 同一 PR 不混两种性质。 | ||
| - **C1 的「drift-check 本地预检」跑不了**：drift-check 需 org admin PAT（owner/CI 专属面）。 | ||
| agent 侧等价预检 = `make gates-pr`（.github 仓）；owner 可 `make drift-check`。 | ||
| 治理漂移的最终判定是每日 CI drift（GOVERNANCE_TOKEN），不靠你本地。 | ||
| - **g060 拦截了你的 suite 变更**：不是故障，是设计。`specs/*/suite/**` 被锁定 | ||
| （ADR-0061/0081），授权身份仅 owner 与 verifier-app；你的 spec PR 含 suite 变更会被 | ||
| g060 拦下（exit 2）并自动开裁决 issue，owner 以 `/g060-adopt <证据>` 采纳或 | ||
| `/g060-reject` 驳回（TTL 72h）。首次创建 suite 同样走此路径——无豁免通道是刻意的。 | ||
| - **conductor / arbiter 怎么触发**：不用也无法手动调用。conductor 监听 issue 事件 | ||
| （`state:*` 标签、评论 `/start` `/claim` `/retry`），arbiter 由 conductor 转介执行 | ||
| CAS 租约。你只管评论与打标签，状态换签是机器的事。 | ||
| - **测试先行 vs gate 要绿**：红测试不进 main。spec PR 的 suite 断言制度/结构不变量， | ||
| 合入时必须绿；修 bug 的失败复现测试走 bug 流（B2 reproduced 锚定 base 红， | ||
| fix PR 合入时转绿）。 | ||
| - **PM 能不能改 .github/workflows/**：能提 PR——但这是 C1 面：引用 ADR、owner-only | ||
| review；PM 的自主性在生成侧，判定与合并归 owner 与 gate（PLAYBOOK §0 红线）。 | ||
| - **根目录文件归属（C1 还是 C3）**：GOVERNANCE.yaml `flows.governance_change` 的 | ||
| classes 是分类真源；AGENTS.md 硬规则把 docs/ 与 Makefile 一并视同 C1（宁严勿松）。 | ||
| 拿不准就按 C1 走：多引一个 ADR 的成本远低于走错流程的返工。 | ||
|
|
||
| ## §3 机器护栏 | ||
|
|
||
| 本文件的断链由 [governance/tests/test-navigation.sh](../governance/tests/test-navigation.sh) | ||
| 机械检测（随 gate 与 `make gates-pr` 每次运行）：入口引用的本仓文件必须存在、 | ||
| AGENTS.md 行数 ≤ 60（治理仓豁免上限）、入口协议块标记完整、本表必须保留 g060/C1/ | ||
| drift-check 等高频困惑锚点。 | ||
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| #!/usr/bin/env bash | ||
| # ghcb —— cloudbrid-agent 便捷入口（ADR-0044 令牌 + ADR-0051 找活协议 + ADR-0055 front-desk 扩展） | ||
| # | ||
| # 用法: | ||
| # GH_TOKEN=$(ghcb <repo> [--refresh]) # 铸 App 单仓安装令牌（ADR-0044，原用法不变） | ||
| # ghcb next [repo] # 找活：列出 <repo>（缺省=origin 所在仓）state:ready 的卡 | ||
| # ghcb claim <n> [repo] # 认领：在卡 #n 评论 /claim——conductor 校验先到先得并置 | ||
| # # state:in-progress（ADR-0049 T3）；ghcb 不持有状态写权 | ||
| # ghcb release <n> [repo] # 释放：评论 /release——conductor 转介 arbiter 删租约 | ||
| # # （仅 holder 本人或 owner 可成，ADR-0054 §4） | ||
| # ghcb status <n> [repo] # 只读：卡标签态（真相源）+ arbiter 租约持有者/到期 | ||
| # ghcb card-meta <n> [repo] # 输出 PR body 应贴的卡元数据行（Card: <org>/<repo>#<n>） | ||
| # | ||
| # next/claim/release 用调用方自己的 gh 凭据（gh auth login）；认领合法性单一真源=conductor guard | ||
| # + arbiter CAS（ADR-0055 转介）。status 读 arbiter 仓 refs/leases/*（只读，无写权要求）。 | ||
| set -euo pipefail | ||
|
|
||
| origin_repo() { # 从 origin 远端推断 owner/name；非 git 仓则空 | ||
| git remote get-url origin 2>/dev/null | sed -E 's#.*github\.com[:/]##; s#\.git$##' || true | ||
| } | ||
|
|
||
| ORG="Cloudbird-Software" # 本 CLI 是组织内部入口（org 段固定，仓段可省略） | ||
| LEAS_REPO="$ORG/arbiter" # 租约宿主仓（arbiter，ADR-0054） | ||
|
|
||
| norm_repo() { # 'repo' | 'owner/repo' → 'owner/repo'（org 段缺省补全） | ||
| local r="${1:?}" | ||
| [[ "$r" == */* ]] || r="$ORG/$r" | ||
| printf '%s' "$r" | ||
| } | ||
|
|
||
| CMD="${1:-}" | ||
| case "$CMD" in | ||
| next) | ||
| REPO_ARG="${2:-$(origin_repo)}" | ||
| [[ -n "$REPO_ARG" ]] || { echo "错误：不在 git 仓内且未指定仓（用法: ghcb next [repo]）" >&2; exit 2; } | ||
| gh issue list --repo "$REPO_ARG" --label state:ready --state open --json number,title --jq '.[] | "#\(.number) \(.title)"' || { echo "查询失败：检查 gh 凭据（gh auth login）与仓权限" >&2; exit 2; } | ||
| ;; | ||
| claim) | ||
| # 参数序 <issue#> [repo]（首版误把 $1 当 repo，PR#157 修正） | ||
| N="${2:?用法: ghcb claim <issue#> [repo]}" | ||
| REPO_ARG="${3:-$(origin_repo)}" | ||
| [[ -n "$REPO_ARG" ]] || { echo "错误：不在 git 仓内且未指定仓" >&2; exit 2; } | ||
| # MSYS 路径转换豁免：Git Bash 会把以 / 开头的参数改写成 Windows 路径 | ||
| # （实测 "/claim"→"D:/development/Git/claim"，conductor 白名单不认）； | ||
| # 非 MSYS 环境该 env 为无害空设 | ||
| MSYS2_ARG_CONV_EXCL='/claim' MSYS_NO_PATHCONV=1 gh issue comment "$N" --repo "$REPO_ARG" --body "/claim" >/dev/null | ||
| echo "已评论 /claim（#$N @$REPO_ARG）——conductor 转介 arbiter CAS 裁决并置 state:in-progress；确认：ghcb status $N" | ||
| ;; | ||
| release) | ||
| # 释放租约（ADR-0055）：/release 评论由 conductor 转介 arbiter——非 holder/无租约=deny | ||
| N="${2:?用法: ghcb release <issue#> [repo]}" | ||
| REPO_ARG="${3:-$(origin_repo)}" | ||
| [[ -n "$REPO_ARG" ]] || { echo "错误：不在 git 仓内且未指定仓" >&2; exit 2; } | ||
| MSYS2_ARG_CONV_EXCL='/release' MSYS_NO_PATHCONV=1 gh issue comment "$N" --repo "$REPO_ARG" --body "/release" >/dev/null | ||
| echo "已评论 /release（#$N @$REPO_ARG）——conductor 转介 arbiter 释放租约（仅 holder/owner）；确认：ghcb status $N" | ||
| ;; | ||
| status) | ||
| # 只读：标签态（宪法 §12 真相源）+ 租约视图（arbiter refs/leases/<org>__<repo>__<n>） | ||
| N="${2:?用法: ghcb status <issue#> [repo]}" | ||
| REPO_ARG="${3:-$(origin_repo)}" | ||
| [[ -n "$REPO_ARG" ]] || { echo "错误：不在 git 仓内且未指定仓" >&2; exit 2; } | ||
| FULL="$(norm_repo "$REPO_ARG")"; NAME="${FULL##*/}" | ||
| gh issue view "$N" --repo "$FULL" --json number,title,state,labels,assignees \ | ||
| --jq '"#\(.number) \(.title)\n 状态: \(.state) | 标签: \([.labels[].name] | join(", ")) | assignee: \([.assignees[].login] | join(", "))"' \ | ||
| || { echo "查询失败：检查 gh 凭据与仓权限" >&2; exit 2; } | ||
| REF="refs/leases/${ORG}__${NAME}__${N}" | ||
| if SHA=$(gh api "repos/$LEAS_REPO/git/ref/$REF" --jq '.object.sha' 2>/dev/null); then | ||
| MSG=$(gh api "repos/$LEAS_REPO/git/commits/$SHA" --jq '.message' 2>/dev/null || true) | ||
| HOLDER=$(grep -o '"holder": *"[^"]*"' <<<"$MSG" | head -1 | sed 's/.*"holder": *"//; s/"$//' || true) | ||
| EXP=$(grep -o '"expires_at": *"[^"]*"' <<<"$MSG" | head -1 | sed 's/.*"expires_at": *"//; s/"$//' || true) | ||
| echo " 租约: holder=${HOLDER:-?} expires_at=${EXP:-?}（ref $REF）" | ||
| else | ||
| echo " 租约: 无活跃租约（ref $REF 不存在）" | ||
| fi | ||
| ;; | ||
| card-meta) | ||
| # 输出 PR body 必贴的卡元数据行（ADR-0055 决策 1：缺失=后续关卡 exit 3） | ||
| N="${2:?用法: ghcb card-meta <issue#> [repo]}" | ||
| REPO_ARG="${3:-$(origin_repo)}" | ||
| [[ -n "$REPO_ARG" ]] || { echo "错误：不在 git 仓内且未指定仓" >&2; exit 2; } | ||
| echo "Card: $(norm_repo "$REPO_ARG")#$N" | ||
| echo "提示：把上面一行原样贴进 PR body（缺失=后续关卡 exit 3）" >&2 | ||
| ;; | ||
| *) | ||
| export REPO="${1:?用法: GH_TOKEN=$(ghcb <repo> [--refresh]) | ghcb next [repo] | ghcb claim <n> [repo] | ghcb release <n> [repo] | ghcb status <n> [repo] | ghcb card-meta <n> [repo]}" | ||
| shift || true | ||
| DIR="$(cd "$(dirname "$0")" && pwd)" | ||
| exec bash "$DIR/gh-app-token.sh" "$@" | ||
| ;; | ||
| esac |
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
2. C1 gate漏判docs/makefile
🐞 Bug≡ CorrectnessAgent Prompt
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools