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-cicd.md)。
- 服务总览规格：[spec-v01-services.md](spec-v01-services.md)。
- Postgres durable store 规格：[spec-v01-postgres.md](spec-v01-postgres.md)。
- Secret/provider credential 分发规格：[spec-v01-secret-distribution.md](spec-v01-secret-distribution.md)。
- AipodSpec 声明式装配规格：[spec-v01-aipod-spec.md](spec-v01-aipod-spec.md)。
- Queue 吸收规格：[spec-v01-queue.md](spec-v01-queue.md)。
- 验证模型规格：[spec-v01-validation.md](spec-v01-validation.md)。
- Manager 服务规格：[spec-v01-agentrun-mgr.md](spec-v01-agentrun-mgr.md)。
- Runner 服务规格：[spec-v01-agentrun-runner.md](spec-v01-agentrun-runner.md)。
- Backend adapter 规格：[spec-v01-backend-adapter.md](spec-v01-backend-adapter.md)。
- Codex stdio backend/profile 规格：[spec-v01-backend-codex.md](spec-v01-backend-codex.md)。
- CLI 规格：[spec-v01-cli.md](spec-v01-cli.md)。
- Scheduler deferred 规格：[spec-v01-scheduler.md](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-*`，再修改代码和测试。