pikasTech-agentrun/docs/reference/spec-v01-documentation-governance.md

v0.1 文档治理规格

本文是 AgentRun v0.1 文档体系的长期规格。它定义仓库入口、长期规格位置、计划和过程材料的承载方式，以及旧 dev/prod 口径迁移规则。

设计目标

• AGENTS.md 是 agent、指挥官和 runner 进入 AgentRun 仓库的唯一顶级入口。
• docs/reference/spec-v01-*.md 是 v0.1 微服务、CI/CD、CLI、运行面和系统能力的权威规格。
• docs/reference/ 只保存长期稳定、可复用的规格、边界、入口、判定标准和稳定 runbook。
• 计划、阶段拆解、一次性排障、临时报告和执行证据进入 GitHub issue 或 PR 评论，不直接沉淀为仓库长期文档。
• SPEC 和长期参考文档变更不创建 PR。修改 AGENTS.md 或 docs/reference/*.md 时，必须在目标 branch 对应 worktree 完成审查后直接提交并推送到目标分支；GitHub issue 评论区用于记录计划、过程和证据，不能用文档 PR 作为落库路径。
• docs/ 根目录不得堆放 Markdown 报告或 JSON dump；机器可消费契约应放入未来的 protocol/、deploy/ 或源码相邻目录，临时输出放 /tmp、.state 或 CI artifact。
• 不维护独立 TEST.md；人工测试和验收场景必须作为对应 spec-v01-*.md 的“测试规格”子项维护。
• 旧 dev/prod 管理说法不再作为当前规格；AgentRun 从 v0.1 开始按 v0.1、v0.2、v0.3 版本 lane 滚动。

允许的文档形态

位置	允许内容	不允许内容
AGENTS.md	顶级入口、一句话 P0 规则、长期参考链接	详细设计、阶段计划全文、临时结论、过程流水账
docs/reference/*.md	长期规格、稳定边界、判定标准、可复用 runbook、对应规格的测试规格	日期化报告、一次性排障全文、临时 evidence、旧规格副本、独立测试入口
docs/reference/spec-v01-*.md	v0.1 当前权威规格	与 v0.1 无关的 v0.2+ 计划全文、未蒸馏过程材料
GitHub issue/PR	计划、里程碑、过程记录、执行证据、实现任务	替代 docs/reference 成为长期唯一权威
/tmp / .state / CI artifact	临时输出、trace、日志、报告、截图	需要长期复用的规格或入口

Spec 命名规则

• spec-v01-documentation-governance.md：文档治理和旧口径迁移。
• spec-v01-services.md：服务总览、保留和 deferred 对象。
• spec-v01-cicd.md：版本 lane、GitOps、namespace、registry 和发布验收。
• spec-v01-postgres.md：Postgres durable store、schema migration 和 DB SecretRef。
• spec-v01-secret-distribution.md：Code Agent provider credential、Postgres DSN 和运行时 Secret 分发。
• spec-v01-runtime-assembly.md：runner/backend 启动前的四要素 RuntimeAssembly 装配模型；其他 spec 只交叉引用，不重复定义四要素字段。
• spec-v01-aipod-spec.md：声明式 AipodSpec YAML、Artificer 默认规格、git mirror、tool credential projection、manager API 和 --aipod CLI。
• spec-v01-queue.md：AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 分层和验收规格。
• spec-v01-validation.md：两层验证模型、自测试和综合联调验收。
• spec-v01-agentrun-mgr.md：manager REST API、tenant boundary、runner claim、event/status authority。
• spec-v01-agentrun-runner.md：短生命周期 runner、claim/poll/report、日志和 failureKind。
• spec-v01-backend-adapter.md：backend adapter 合同、event normalization、failure mapping 和 redaction。
• spec-v01-backend-codex.md：第一真实 Codex app-server stdio backend、codex/deepseek/minimax-m3 profile、~/.codex 测试凭据 Secret projection 和真实 turn 验收。
• spec-v01-cli.md：AgentRun CLI 命令族、JSON 输出、短返回、日志可见和测试规格。
• spec-v01-scheduler.md：自动 scheduler 的 deferred 边界。
• 未来新增单服务规格必须使用 spec-v01-<service-or-capability>.md。
• v0.2 或更高版本的规格不得写入 spec-v01-*；只能在对应版本 lane 中创建自己的 spec-v02-*、spec-v03-*。
• 每个可实现规格应包含“测试规格”小节；测试编号写在对应 spec 内，不创建或恢复根目录 TEST.md。

迁移规则

1. 发现 README.md、docs/*.md、docs/*.json 或计划文档时，先判断是否有长期价值。
2. 有长期价值的，只把稳定结论吸收到对应 docs/reference/spec-v01-*.md；不要整篇搬入 reference。
3. 属于计划、里程碑、阶段迁移、报告、一次性排障或历史验收的，全文迁入 GitHub issue 或 PR 评论，再删除源文件。
4. 与 v0.1 规格冲突的旧 dev/prod、/root/agentrun 默认 source 目录、agentrun_dev、agentrun_prod 说法必须删除或改为历史背景。
5. 发现独立 TEST.md 或测试计划文档时，先把仍有效的测试场景蒸馏到对应 spec-v01-*.md 的“测试规格”小节，再删除源文件。
6. 未实现规格必须在对应 spec 的“规格的实现情况”中明确写成 未实现 或 未完全实现，不要用散落 TODO 代替。
7. SPEC 或长期参考文档完成修改后，直接提交并推送目标分支；若误建文档 PR，必须关闭 PR，并把同一变更直接落入目标分支。

v0.1 当前权威入口

• Source branch：v0.1。
• Source worktree：G14:/root/agentrun-v01。
• Worktree 根：G14:/root/agentrun-v01/.worktree/{task}。
• Runtime namespace：agentrun-v01。
• 发布和验收规格：spec-v01-cicd.md。
• 服务总览规格：spec-v01-services.md。
• Postgres durable store 规格：spec-v01-postgres.md。
• Secret/provider credential 分发规格：spec-v01-secret-distribution.md。
• AipodSpec 声明式装配规格：spec-v01-aipod-spec.md。
• Queue 吸收规格：spec-v01-queue.md。
• 验证模型规格：spec-v01-validation.md。
• Manager 服务规格：spec-v01-agentrun-mgr.md。
• Runner 服务规格：spec-v01-agentrun-runner.md。
• Backend adapter 规格：spec-v01-backend-adapter.md。
• Codex stdio backend/profile 规格：spec-v01-backend-codex.md。
• CLI 规格：spec-v01-cli.md。
• Scheduler deferred 规格：spec-v01-scheduler.md。

验收标准

• AGENTS.md 索引本文和其他 spec-v01-* 规格。
• docs/reference/ 中存在 spec-v01-documentation-governance.md、spec-v01-services.md、spec-v01-cicd.md、spec-v01-postgres.md、spec-v01-secret-distribution.md、spec-v01-runtime-assembly.md、spec-v01-aipod-spec.md、spec-v01-queue.md、spec-v01-validation.md、spec-v01-agentrun-mgr.md、spec-v01-agentrun-runner.md、spec-v01-backend-adapter.md、spec-v01-backend-codex.md、spec-v01-cli.md 和 spec-v01-scheduler.md。
• AGENTS.md 和 docs/reference/ 不得把旧 agentrun_dev、agentrun_prod、G14:/root/agentrun 或 /root/agentrun 写成当前 source worktree、namespace、发布目标或验收目标；只允许在废弃说明和历史背景中提及。
• docs/ 根目录不新增临时 Markdown 报告或 JSON dump。
• 仓库根目录不存在 TEST.md；测试场景维护在对应 spec-v01-*.md 的“测试规格”小节。
• 后续实现任务先更新或引用对应 spec-v01-*，再修改代码和测试。