Agent-System-Dev/docs/superpowers/plans/2026-10-16-development-governance-v2-master.md

development-governance-v2 统一治理主记录

本文件是治理大任务跨仓状态的唯一汇总。每行状态只取以下值之一，不用笼统的“完成”： PLANNED / IMPLEMENTED / LOCALLY_VERIFIED / PR_OPEN / REVIEWED / GATE_PASS / MERGED / ADOPTED_ACTIVE / RELEASED / CLOSED。 通过类结论须带来源（GATE / REPLAY / SELF）与对象 SHA；历史对象证据不得充当当前 HEAD 证据。

全局任务只有在全部正式仓达到 ADOPTED_ACTIVE、新项目入口启用、主 PR 全部合入并完成清理后才能标记 CLOSED。

全局状态

CLOSED（2026-10-17；生效条件：本收尾 PR #604 合入，且本任务 worktree/分支经 task-finish 回收）：Phase 0–7 全部合入；17 个正式仓全部 ADOPTED_ACTIVE（合入提交与 main 上 CI 见矩阵，GATE）；新项目入口（Phase 7 governance init|check）见 DM #18–#20。各仓采纳卡已随各自 PR 归档；Dev 收尾卡 feature-governance-v2-closeout 与本收尾卡随本 PR 闭合归档。其他仓采纳 worktree/分支回收状态本记录未取证 [未经证实]，以各仓清理记录为准。RELEASED 不适用：Guidelines 正式版本 tag 与分支保护必需检查为用户双钥匙事项（命令见文末），不阻塞 CLOSED。

交付主线

Phase	内容	仓库 / 分支	PR	状态	依赖
0	纠正候选状态、建立本主记录	Dev feature/development-governance-v2	#585	MERGED	—
1	Guidelines 合同加固	Guidelines contract-hardening child → initiative → main	#8、#7	MERGED（Guidelines main 2688fd2）	—
2	Dev triage 与两级生命周期整改	Dev child triage-hardening / target-integrity → initiative	#595、#596	MERGED（进入 initiative）	1
3	真实两级 PR 演练	Dev child PR → initiative → #585 → main	#595、#596 → #585	MERGED（证据见 Dev 归档卡 feature-development-governance-v2）	2
4	Guidelines 合入 → Dev gitlink → Review → 三项 CI → 合入 #585 → 收口	Guidelines / Dev	#7 / #585 / #597	CLOSED（Dev main aee351a；卡片归档 682a4e8）	1–3
5	DM 共享执行器 agent-exec；Dev 薄入口切换与 Python 退役	DM #16、#17；Dev feature/dev-shared-executor-switch	#16、#17、Dev #600	MERGED（DM 183e764、9c38345；Dev #600 合入 a5829c2：薄入口切换与 Python 退役，卡片闭合 #601；Dev 现经 scripts/agent-exec 运行固定 DM 版本）	4
6	存量仓逐仓采纳	各仓 feature/governance-adoption；Dev feature/governance-v2-closeout	见下方采纳矩阵	ADOPTED_ACTIVE（17/17：全部已合入且 main 上 CI 通过）	5、7
7	新项目治理初始化与 CI 准入	DM feature/governance-kit（K1 triage、K2 start/pr-check、K3 governance init/check）及后续修复	#18、#19、#20	MERGED（#18 42e675f；#19 钩子环境修复；#20 governance check --guidelines-self，DM main 0552b73；均经独立 Review 与 CI GATE）	5

历史候选对象与证据（Phase 4 时点；当前 main 对象见采纳矩阵）

仓库	分支	对象	证据	说明
Development-Guidelines	main	2688fd2	PR #7 合入（Review REPLAY + 平台合入）	draft.12 合同与两个 Schema
Agent-System-Dev	main	aee351a	run 3509 三项 CI（GATE，head d648826）+ PI Review（REPLAY）	两级分支、强制 triage、PR base 门禁
Development-Manager	main	183e764	DM CI（GATE）+ PI Review（REPLAY）	dm-server agent-exec

已确认阻塞缺陷（整改前）

1. Dev task-triage 按接纳中 initiative 数量直接给出 JOIN，不做适配判断（违反 KTD1）。
2. Dev task-triage 只扫描当前检出的 .task/，看不到只存在于远端分支的 initiative（违反 KTD2）。
3. task-start KIND=child 依赖本机已有父分支，未校验父 initiative 仍开放、接纳需求（违反 KTD3）。
4. task-start 不要求 triage 收据；无 PR base 门禁；闭合记录与证据未贯穿 immediate_target。
5. Guidelines 缺 terminal receipt 机器 Schema；配置 Schema 未覆盖 transport/admission/豁免/清理；all-unavailable 未与新项目准入隔离；triage 合同仍为数量判定。
6. 原 U4 实施方式为 host 预写补丁交 CLI 应用，后续单元须由 CLI 自主实施。

正式仓库清单与采纳矩阵

来源：Gitea /user/repos（2026-10-16 实测）。排除：Agent-System（冻结参考仓，不再开发）、SMDF-Agent-System（空仓）、 governance-drill-2026-09 与 merge-queue-admission-fixture-20261014（演练夹具）。本机 *-wt-*、备份与组合目录不计入。

批次	仓库	Guidelines 固定版本	AGENT-EXECUTION.md	共享执行器入口	采纳 PR	合入提交	main 上 CI（GATE）	状态
A	Development-Guidelines	自身（规范源）	有（active）	scripts/agent-exec → DM 0552b73	#9	6c8e6cd	governance success	ADOPTED_ACTIVE
A	Agent-System-Dev	deps/development-guidelines 2688fd2	有（active）	scripts/agent-exec → DM 0552b73	#602	f563ed6	ci / test、test-pg、svc-realcombo success（run 3687）；governance check 位于必需检查 ci / test	ADOPTED_ACTIVE
A	Development-Manager	development/guidelines 2688fd2	有（active）	实现方：scripts/agent-exec 构建已提交 HEAD	#21（证据日志补入 #22）	c261cdd	ci / build-test success（含 agent-exec validate 与 governance check --implementer）	ADOPTED_ACTIVE
B	Agent-System-Core	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#35	5cae3a6	governance success	ADOPTED_ACTIVE
B	Agent-System-Backend	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#208	cac60c0	governance success；ci / vet-and-test 首次因既有不稳定测试 TestProjectEventsSharedProofAndPrivatePagination 失败（与 PR 头同树，PR 头通过），对象 cac60c0 重跑 success（run 3570 job 5779）	ADOPTED_ACTIVE
B	Agent-System-RDM	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#431	7476a04	governance、ci / build-and-test success	ADOPTED_ACTIVE
C	Agent-System-Frontend	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#105	0f31f91	governance success	ADOPTED_ACTIVE
C	Agent-System-UI	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#58	a313d45	governance、ci / test success	ADOPTED_ACTIVE
C	Agent-System-Documents	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#110	6c04eb2	governance success	ADOPTED_ACTIVE
C	Agent-System-Releases	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#2	99c89b6	governance success	ADOPTED_ACTIVE
D	Agent-Command	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#8	00e0875	governance success	ADOPTED_ACTIVE
D	Agent-Intent	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#12	651a2e1	governance、ci 两项 success	ADOPTED_ACTIVE
D	Agent-Native	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#47	14d4869	governance、ci 两项 success	ADOPTED_ACTIVE
D	Agent-Squad	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#54	9ded893	governance、ci 两项 success（deps/agent-native、deps/agent-intent 同步到两者采纳后 main，submodule-consistency 全 ok）	ADOPTED_ACTIVE
E	Error-Code-System	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#4	3d4d5e6	governance、ci 两项 success	ADOPTED_ACTIVE
E	Logging-System	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#4	1758e2c	governance、ci 两项 success	ADOPTED_ACTIVE
E	Agent-Document-Renderer	2688fd2	有（active）	scripts/agent-exec → DM bd3a7de	#6	770d886	governance success	ADOPTED_ACTIVE

每仓采纳均按同一 10 步：固定 Guidelines、AGENT-EXECUTION.md、薄入口（scripts/dm/scripts/agent-exec/scripts/task）、四条路由、任务卡模板与分支元数据、CI 中 schema 校验与 governance check、一次真实正例单元（agent-per-unit，经 agent-exec apply 集成）、负例（bad-receipt、out-of-scope-path、unknown-side-effect、admit 拒绝；冻结脚本 evidence/governance-adopt-cases.py）、独立 Review（全新只读会话，闭合重审只围绕阻塞项）与 PR 头 CI、采纳状态 active。每仓的收据、证据与 Review 结论在该仓归档任务卡 .task/archive/feature-governance-adoption.md（Guidelines 按其 CONTRIBUTING.md 记录在本目录 2026-10-17-guidelines-governance-adoption.md）。

Owner 决策记录

日期	决策	影响
2026-10-16	cursor 服务端故障期间临时让 agy 成为首选；实际以不含 cursor 包装脚本的 PATH 启动执行器实现（停用 cursor profile 会使 Dev 参考解析器拒绝配置），cursor 冒烟恢复后回到正常 PATH	无配置改动；收据中 cursor 如实记为 unavailable
2026-10-17	共享执行器分发：各正式仓像 Guidelines 一样固定 Development-Manager gitlink（deps/development-manager），薄入口 scripts/agent-exec 构建/运行该固定版本的 dm-server agent-exec；CI 用同一固定版本运行 agent-exec validate	Phase 6 每仓增加 DM gitlink 与薄入口；Dev Python 实现退役后同样切到该入口
2026-10-17	CI 读取私有 Guidelines/DM 子模块所需的 SUBMODULE_TOKEN：owner 授权智能体以 ~/.secrets/gitea 的 API token 作为该 secret 值（只记录来源，不记录值）	已为 Development-Manager 配置；Phase 6 按需为其他仓配置
2026-10-17	Phase 6/7 共享入口：存量仓与新项目没有 Dev 的 task.sh，通用 triage/start/pr-check 与 `governance init	check` 放入 DM（治理套件），各仓经薄入口调用，不复制实现；先完成 Phase 7 套件再用其推进 Phase 6
2026-10-17	DM CI 自 2026-09-30 起从未成功（runner 无法拉取 github.com 上的 actions/checkout）；按 Dev 已审阅的内联检出模式改为自包含 CI（DM-U6）	Phase 6 中使用 uses: 的仓（Error-Code-System、Logging-System）同样需要检查
2026-10-17	存量仓 CI 无法访问 github.com：Error-Code-System、Logging-System 的 uses: actions/checkout 改为与 governance.yml 相同的内联检出（凭据经 GIT_CONFIG_* 环境变量，checkout -f + clean -ffdxq 保持 clean 语义）	两仓既有 CI 恢复可运行
2026-10-17	Guidelines 冲突裁定（contrib_exception）：CONTRIBUTING.md 增加一句窄例外，允许本库自身治理文件入库；过程记录仍不入库；规范正文与 VERSION 不变	Guidelines #9
2026-10-17	DM #21 保留新增回归测试 cmd/dm-server/implementer_entry_test.go（approve_test），豁免原“不改 Go 代码”表述；生产 Go 代码不变	DM #21
2026-10-17	codex/pi Review 额度受限（429）期间，独立 Review 改由全新只读 Cursor CLI 会话（--mode ask，session id not-observable）执行；评审只接收目标、base/head、diff 与证据	各仓 Review 记录标注 fresh_session 与 not-observable

停止条件

无法获取权威远端 initiative；triage 收据与需求或候选 HEAD 不一致；child PR base 错误；Guidelines gitlink 未指向真实已合入版本； CLI 终态无效或副作用未知；Review、CI 或平台准入缺失；主干在最终 CI 后继续前进；存量仓无共享执行器却启用强制规则； 需要发布规范 tag 而用户尚未执行双钥匙操作。出现任一项即停止对应交付窗口。

用户双钥匙事项

• Development-Guidelines 正式版本 tag：Agent 只准备命令，由用户执行。
• 分支保护：把 governance 检查设为各仓 main 的必需状态检查。以下命令由用户确认后亲手执行（token 只从 ~/.secrets/gitea 读取，不回显）。 PATCH 会整体替换 status_check_contexts：执行前先 GET 核对（2026-10-17 只读核对：除 Dev 外各仓 main 规则均未启用状态检查、contexts 为空）。已有 main 规则的仓用 PATCH；Agent-System-Releases、Agent-Document-Renderer 尚无规则，用 POST 新建。Dev 的 governance check 位于既有必需检查 ci / test 中，无需改动。

API=https://git-home.u1680832.nyat.app:30319/api/v1
HDR=$(umask 077; mktemp)   # token 只进 0600 临时头文件，不进命令行参数
printf 'Authorization: token %s\n' "$(sed -n 's/.*ACCESS_TOKEN=//p' ~/.secrets/gitea)" > "$HDR"
protect() {  # protect <repo> <PATCH|POST> <context>...
  repo=$1 method=$2; shift 2
  ctx=$(printf '%s\n' "$@" | python3 -c 'import json,sys;print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))')
  if [ "$method" = PATCH ]; then url=$API/repos/weichen/$repo/branch_protections/main
    body="{\"enable_status_check\":true,\"status_check_contexts\":$ctx}"
  else url=$API/repos/weichen/$repo/branch_protections
    body="{\"rule_name\":\"main\",\"enable_status_check\":true,\"status_check_contexts\":$ctx}"
  fi
  curl -sS -o /dev/null -w "$repo %{http_code}\n" -X "$method" -H @"$HDR" -H 'Content-Type: application/json' "$url" -d "$body"
}
GOV='governance / governance (pull_request)'
protect Development-Guidelines PATCH "$GOV"
protect Development-Manager PATCH 'ci / build-test (pull_request)'
protect Agent-System-Core PATCH "$GOV"
protect Agent-System-Backend PATCH "$GOV" 'ci / vet-and-test (pull_request)'
protect Agent-System-RDM PATCH "$GOV" 'ci / build-and-test (pull_request)'
protect Agent-System-Frontend PATCH "$GOV"
protect Agent-System-UI PATCH "$GOV" 'ci / test (pull_request)'
protect Agent-System-Documents PATCH "$GOV"
protect Agent-System-Releases POST "$GOV"
protect Agent-Command PATCH "$GOV"
for r in Agent-Intent Agent-Native Agent-Squad Error-Code-System Logging-System; do
  protect "$r" PATCH "$GOV" 'ci / vet-and-test (pull_request)' 'ci / docker-checkout-hostgateway (pull_request)'
done
protect Agent-Document-Renderer POST "$GOV"
rm -f "$HDR"

设为必需检查并补一次被阻断的负例 PR 后，各仓采纳记录中 agent-execution 行才可由 advisory 登记为 enforced。

非阻塞遗留项（不阻塞本次交付，建议独立增量）

1. 各仓 AGENT-EXECUTION.md 说明文字仍有 kit 模板句“下例的 CLI 名称、命令与路径均为占位”（Agent-Intent 已改写）；应修 DM kit 模板后统一刷新。
2. Agent-System-Backend、Agent-System-Frontend 归档卡内少量证据相对链接未随归档调整。
3. Agent-System-Backend 既有 CI 把 token 写入全局 git config（insteadOf）；建议改为 URL 限定的 extraheader 环境变量方式。
4. DM agent-exec 的 host 豁免路径（.task/** 等）为硬编码；可改为读取 AGENT-EXECUTION.md。
5. 候选 PR 可修改自身 governance.yml（工作流取自 PR 头）；单人仓风险可接受，多人协作前改为基线工作流或必需检查来源固定。
6. 各仓 governance.yml 从镜像下载 Go 未做 sha256 校验。
7. Agent-System-Backend 既有不稳定测试 TestProjectEventsSharedProofAndPrivatePagination。
8. 旧 feature/card-close-* 远端分支待清点。
9. Dev 组合 CI 中的不稳定测试 TestToolCallDeltaBeforeExecution（Dev PR #602 run 3685 首次失败、重跑通过；所属模块与根因 [未经证实]）。
10. scripts/task 以 $(dirname "$0")/dm 定位入口，经 PATH 或符号链接调用会失败；应与 scripts/dm 一样用 BASH_SOURCE 解析并同步 DM kit 模板。
11. 分支保护命令片段未设 trap，异常退出时临时头文件不会删除（0600、用户手动执行，低风险）。