# 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`
