@pzy560117/codex-harness 0.1.2 → 0.1.4

package/package-source/docs/codex-harness-engineering/templates/runtime/AGENTS.md

@@ -1,50 +1,66 @@
-# AGENTS.md
-
-本文件只保留每次会话都必须知道的 Harness 入口规则。细节按需读取下方深文档，不把长期协议全部塞进入口文件。
-
-## 核心入口
-
-- 本仓库默认采用 `driver-first`：真实任务进入 `task.json`，由 `tools/harness/codex-loop.ps1` 逐个执行。
-- `single task` 是当前唯一自动执行模式；每轮 driver 只处理一个 `passes: false` 且依赖已通过的任务。
-- 交互开发模式只负责需求收敛、分析、规划和任务输入；方案确认后，默认回到 `task.json -> tools/harness/codex-loop.ps1`。
-- 主控会话不直接维护仓库状态文件；`task.json`、`progress.txt`、`traces/` 和 Git 提交由 runtime 链路推进。
-- 需要理解代码结构或安装包边界时，先读 `docs/ai/repo-map.md`，再进入具体目录或深文档。
-- 需要落盘规则、任务、文档、前端、后端或测试内容时，先确认 truth source，再委派匹配的 writer 子代理或进入 driver 任务。
-
-## 硬约束
-
-- 启动前 Git 工作区必须干净，除非用户明确说明哪些改动属于本任务；可再生运行产物只能通过 `runtime.git.non_blocking_dirty_paths` 列白名单。
-- 不要伪造完成状态：不得手工把未验证任务标记为 `passes: true`，不得绕过 `test_command`、review gate 或 commit gate。
-- 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
-- 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
-- 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
-- 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
-- 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
-- `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。
-- Stage 1 Review 先审声明的架构约束符合性，再审业务规格；仅当任务要求架构门禁且约束缺失或实现冲突时 FAIL。
-- 阻塞时追加 `progress.txt`，输出 `BLOCKED - 需要人工介入`，然后停止。
-
-## 阶段更新规则
-
-- Stage 01 初始化：更新 `task.json`、`AGENTS.md`、项目路径和验证命令。
-- Stage 02 需求收敛：更新 `docs/product/`、Requirement IDs、验收标准和可执行验收示例。
-- Stage 03 追溯与架构约束：更新架构约束 truth source、测试追溯矩阵和证据协议。
-- Stage 09 DEV-PLAN / 任务拆分：把架构约束、禁止实现和验证命令写入每个相关 `feature_impl`。
-- Stage 10-14 实现与集成：只更新任务 owned paths 内的实现、测试和证据。
-- Stage 15-16 Review：保持只读审查，输出 findings、证据和 repair queue。
-- Stage 17 Verify / Regression：刷新验证证据，不在本阶段第一次补需求或测试范围。
-- Archive：更新 `docs/knowledge/`、索引和可复用经验，不升级一次性结论为全局规则。
-
-## 必读索引
-
-- Harness 架构：`docs/harness/architecture.md`
-- 代码地图：`docs/ai/repo-map.md`
-- 架构摘要：`docs/ai/architecture-brief.md`
-- 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
-- 新项目使用：`docs/harness/new-project-usage.md`
-- Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
-- 规则治理与 AGENTS.md 分层：`docs/harness/rule-governance.md`
-- 回归与验证策略：`docs/harness/regression-rules.md`
-- Trace 格式：`docs/harness/trace-format.md`
-- 权限策略：`docs/harness/sandbox-policy.md`
-- Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`
+# AGENTS.md
+
+本文件只保留每次会话都必须知道的 Harness 入口规则。细节按需读取下方深文档，不把长期协议全部塞进入口文件。
+
+## 模板源目录说明
+
+- 当你在模板源仓库维护 `templates/runtime/` 时，本文件也同时代表该目录的本地索引。
+- 当前目录主要包含：
+  - `AGENTS.md`：安装到目标项目根目录的入口规则模板
+  - `codex-loop.ps1` / `doctor.ps1` / `verify.ps1`：driver 与运行时脚本模板
+  - `project-task-template.json` / `smoke-task.json` / `task.json` / `progress.txt`：任务与运行状态模板
+  - `task-run-profile.json`：运行策略模板
+  - `scripts/`：runtime 自检和队列校验脚本
+- 维护该目录时，优先确认这些文件是“安装后运行面”，不要把只适用于模板仓库的局部说明大量混入这里。
+
+## 核心入口
+
+- 本仓库默认采用 `driver-first`：真实任务进入 `task.json`，由 `tools/harness/codex-loop.ps1` 逐个执行。
+- `single task` 是当前唯一自动执行模式；每轮 driver 只处理一个 `passes: false` 且依赖已通过的任务。
+- 交互开发模式只负责需求收敛、分析、规划和任务输入；方案确认后，默认回到 `task.json -> tools/harness/codex-loop.ps1`。
+- 主控会话不直接维护仓库状态文件；`task.json`、`progress.txt`、`traces/` 和 Git 提交由 runtime 链路推进。
+- 长会话续跑前，先重读 `docs/ai/CURRENT_TASK.md`、`docs/ai/repo-map.md` 和相关 truth source；不要只靠聊天记忆继续实现。
+- 需要理解代码结构或安装包边界时，先读 `docs/ai/repo-map.md`，再进入具体目录或深文档。
+- 需要落盘规则、任务、文档、前端、后端或测试内容时，先确认 truth source，再委派匹配的 writer 子代理或进入 driver 任务。
+
+## 硬约束
+
+- 启动前 Git 工作区必须干净，除非用户明确说明哪些改动属于本任务；可再生运行产物只能通过 `runtime.git.non_blocking_dirty_paths` 列白名单。
+- 不要伪造完成状态：不得手工把未验证任务标记为 `passes: true`，不得绕过 `test_command`、review gate 或 commit gate。
+- 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
+- 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
+- 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
+- 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
+- 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
+- `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。
+- Stage 1 Review 先审声明的架构约束符合性，再审业务规格；仅当任务要求架构门禁且约束缺失或实现冲突时 FAIL。
+- 多 Agent 协作时，禁止多个 Agent 同时修改同一文件或同一组可写路径；必须先按任务、目录、文件组、分支或 PR 隔离。
+- 当前轮次结束前必须刷新 `docs/ai/CURRENT_TASK.md` 中的已完成内容、未完成内容、修改文件、测试结果和下一步。
+- 阻塞时追加 `progress.txt`，输出 `BLOCKED - 需要人工介入`，然后停止。
+
+## 阶段更新规则
+
+- Stage 01 初始化：更新 `task.json`、`AGENTS.md`、项目路径和验证命令。
+- Stage 02 需求收敛：更新 `docs/product/`、Requirement IDs、验收标准和可执行验收示例。
+- Stage 03 追溯与架构约束：更新架构约束 truth source、测试追溯矩阵和证据协议。
+- Stage 09 DEV-PLAN / 任务拆分：把架构约束、禁止实现和验证命令写入每个相关 `feature_impl`。
+- Stage 10-14 实现与集成：只更新任务 owned paths 内的实现、测试和证据。
+- Stage 15-16 Review：保持只读审查，输出 findings、证据和 repair queue。
+- Stage 17 Verify / Regression：刷新验证证据，不在本阶段第一次补需求或测试范围。
+- Archive：更新 `docs/knowledge/`、索引和可复用经验，不升级一次性结论为全局规则。
+
+## 必读索引
+
+如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下查同路径文件。
+
+- Harness 架构：`docs/harness/architecture.md`
+- 代码地图：`docs/ai/repo-map.md`
+- 架构摘要：`docs/ai/architecture-brief.md`
+- 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
+- 新项目使用：`docs/harness/new-project-usage.md`
+- Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
+- 规则治理与 AGENTS.md 分层：`docs/harness/rule-governance.md`
+- 回归与验证策略：`docs/harness/regression-rules.md`
+- Trace 格式：`docs/harness/trace-format.md`
+- 权限策略：`docs/harness/sandbox-policy.md`
+- Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`