# Task 会话策略

## 默认策略

- 每个任务默认使用 fresh process。
- 默认采用“一任务一会话”；任务完成、阻塞或切换目标后，下一轮优先新开 session，而不是在旧会话里继续叠加上下文。
- 子代理默认采用 guided 模式；实现阶段可以用子代理加速开发，但必须先拆 ownership、角色和验收输出。
- 当前版本只支持单任务 driver，不提供额外执行工作区。
- runtime 脚本会继续负责 `progress.txt`、`traces/` 和 Git 状态推进；除此之外的仓库写入由匹配的 writer 子代理执行。

## 运行模式边界

| 模式 | 触发方式 | 边界 |
| --- | --- | --- |
| driver 自动执行模式 | `tools/harness/codex-loop.ps1` 从 `task.json` 选择任务 | 外层 runtime 负责任务推进、验证、trace 和 commit |
| single task | 内层 `codex exec` 处理当前任务 | 只处理当前任务直接要求的代码或文档改动；可在该任务 owned paths 内使用子代理加速 |
| 交互开发模式 | 人工要求分析、规划、创建任务或实现功能 | 负责收敛输入；需要落盘时委派 writer 或转成 driver 任务 |

交互开发模式在 spec / plan 明确后，默认下一步是初始化真实 `task.json` 并运行 `tools/harness/codex-loop.ps1`。除非用户明确要求继续在当前会话直接开发，否则不要长期停留在聊天推进阶段。

如果 spec 和 architecture 已完成，应先让合适的 writer 子代理同步项目规则文件，再初始化任务队列，避免后续 driver 建立在过期的 `AGENTS.md`、`docs/harness/*` 或 `docs/context/*` 之上。

## 任务文件规则

- `task.json` 使用 `{ "runtime": {...}, "tasks": [...] }` 结构；新任务默认 `passes: false`。
- 标准交接入口是 `tools/harness/templates/project-task-template.json`，首个任务固定为 `INIT-001`，用于锁定 spec 输入、任务依赖、验证矩阵、`execution.mode` 和 owned paths。
- 如果 `task.json` 为空文件，先初始化为合法 JSON；如果仍是 smoke 模板或示例任务，先替换为当前项目真实任务。
- 交互开发模式可以决定新增或更新哪些待办任务，但实际写入必须委派给 `harness-writer` 等匹配 writer。
- 未经用户明确同意，不得把标准模板 phase 压缩成更少任务；正式任务队列至少保留 `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001`。
- 创建或重建任务队列时，必须根据 `owned_paths`、`docs/ai/repo-map.md` 和模块职责判断哪些目录需要局部规则；命中独立模块目录却缺少子目录 `AGENTS.md` 时，不得把该任务队列视为正式完成。
- 目录级 `AGENTS.md` 的最佳落盘时机，不是项目初始化时盲写，也不是实现结束后补写；而是在架构设计、实施计划或任务拆分已经明确该目录职责、边界、入口和验证方式之后，进入实现前立刻固化。
- 任务进入 driver 前必须冻结交付语义：`scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`。不适用字段必须写 `not_applicable`，不能留给实现会话猜。
- 进入实现前，`docs/ai/CURRENT_TASK.md` 必须能回答本轮已完成内容、剩余问题、修改文件、测试结果、风险点和下一步，不允许只靠聊天记忆续跑。
- `ANALYSIS-001`、`TESTCASE-001`、`PLAN-001` 的 testing truth source 产物必须在生成最终 `task.json` 前补齐：`docs/testing/ACCEPTANCE_CRITERIA.md`、`docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`docs/testing/TRACEABILITY_MATRIX.md`、`docs/testing/TEST_DATA_MATRIX.md`、`docs/testing/REGRESSION_PLAN.md`、`docs/testing/verify-matrix.md`。缺任一项都不得进入正式任务队列。
- 创建或重建任务队列时必须一次性补齐每个任务的完整交接字段：`requirement_ids`、`owned_paths`、`context_files`、`produces_artifacts`、`test_command`、`acceptance`、自然语言测试用例、测试数据、开发验证、最终验收验证、证据路径和 `qa_contract`。不得创建“先跑起来、后面再补测试/证据/整链路”的实现任务。
- 自动刷新出来的 `AUTO-MODULE-FACTS` 只能证明目录事实被收集，不代表目录级规则完整；如果模块目录只有托管 facts 而没有职责、边界、入口、测试或禁止事项等手写规则，应继续标记为待补齐，而不是当作完成态。
- PRD / 需求文档完成后、进入实现前必须有自然语言测试用例阶段；每条 P0/P1 需求必须按 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 的需求类型覆盖矩阵满足最小用例数，并回溯到 Requirement ID、PRD 来源、Oracle、测试数据、证据路径和 TDD RED 预期失败。
- 每个 `feature_impl` 任务必须声明两段验证：`development_validation` 用于编码过程中的 affected tests、单元 / 组件、局部 API、契约、类型检查或 lint；`acceptance_validation` 用于代码写完后从用户故事入口重新跑完整链路。
- 每个 `feature_impl.qa_contract.tdd_contract.red.source_case_ids` 必须能回溯到 `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`；缺少自然语言用例来源时不得进入实现阶段。
- 每个 `feature_impl.qa_contract.required_layers` 必须至少包含 `unit_or_component`、`contract_or_api`、`story_full_chain`、`affected_regression`；`tdd_contract` 必须同时包含 `red`、`green`、`refactor_guard`，且 `source_case_ids` 不得为空。
- 单个 `feature_impl` 默认不得覆盖超过 3 条主需求；订单、支付、库存、RBAC 必须拆成独立任务；前端和后端不得长期混在同一个 story，除非这是明确的 `release` 任务。只有用户明确批准时，才允许在任务中增加 `decomposition_exemption` 记录例外原因。
- 不适合作为 TDD RED 的自然语言用例必须通过 `story_full_chain.source_case_ids`、`acceptance_validation.source_case_ids`、回归计划或 `verify-matrix` 进入验收链路；不得只保留在 PRD 或测试设计文档中。
- 每个 `feature_impl` 的验收链路必须包含入口、动作、Oracle、副作用/无副作用证据、测试数据、失败态证据和 release 影响。单元测试、小范围 smoke、静态检查或 `git diff --check` 只能作为开发验证的一层，不能替代最终验收链路。
- 后端、CLI、worker、数据同步和外部集成类 `feature_impl` 必须按 `static`、`unit`、`chain`、`failure`、`writeback` 五层声明验证；没有 UI 可见结果时，链路验证和失败验证不能省略。
- 前端 `feature_impl` 必须声明 `state_surface`：关键状态进入 story、route、fixture、mock scenario、query 参数、viewport 或 E2E 入口中的哪一种。只冻结视觉稿、不暴露可运行状态，不得进入实现。
- 每个 `release` 任务必须声明发布候选级跨故事整链路验证、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证，以及失败归因证据路径。
- 不得删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
- `spec` 定义做什么，`plan` 定义怎么拆，`task.json` 是主控唯一执行入口。

### 内容门禁分层

- 默认 `runtime.content_gates.default_mode = core`，只阻塞最小闭环门禁：`spec / context / session / architecture / testing / impact`。
- 如果任务需要更严格的实现前约束，可在 `task.json.runtime.content_gates.default_mode` 或单个 task 的 `content_gate_mode` 中切到 `recommended` 或 `full`。
- `recommended` 适合希望默认启用目录、命名、组件复用、业务规则、状态、UI、性能、文档和验收模板门禁的项目。
- `risk_tags` 只在高风险任务上启用专项门禁，例如：`security`、`backend`、`data`、`integration`、`mobile`、`config`、`observability`、`refactor`。
- 不要把所有项目都默认切到 `full`；先用 `core` 跑通，再按项目类型补 `content_gate_mode` 或 `risk_tags`。

## 状态文件压缩规则

- `task.json` 是 active queue，不是历史数据库；它只保留未完成任务、依赖判断所需的状态和最近少量已完成任务。
- `progress.txt` 是近期人类摘要，不是完整审计日志；完整过程证据以 `traces/`、`archive/tasks/`、`progress/archive/` 和 Git commit 为准。
- `tools/harness/codex-loop.ps1` 在任务成功、写入 trace 之后、提交之前自动执行 `runtime.state_compaction`。
- 已完成任务超过 `completed_task_retention` 后，旧任务体归档到 `archive/tasks/*.json`，并重建 `archive/tasks/index.json`；`task.json.runtime.state_archive.completed_task_ids` 只保留依赖判断所需的已完成 ID。
- `progress.txt` 超过 `progress_max_lines` 后，旧行轮转到 `progress/archive/progress-*.log`，当前文件只保留最近窗口和归档指针。
- AI 会话和子代理不得直接压缩、重写或整理 `task.json` / `progress.txt`；如发现状态膨胀、格式损坏或归档漂移，应让 driver 或 stop hook 治理链路修复。
- 归档文件属于 runtime 产物，允许随当前任务 commit 一起提交；不要把归档目录加入普通任务的 `owned_paths`。

## 本轮语义约束包

复杂任务开始前，必须把容易在长会话或 compact 后丢失的语义约束写进稳定 truth source，不能只停留在聊天口头说明里。

最小语义约束包应覆盖：

- 当前迭代目标：本轮要交付的用户故事、版本、入口或关键对象。
- 禁止修改范围：已上线、只读、外部系统、兼容性敏感或本轮不应触碰的路径 / 数据 / 接口。
- 关键口径：金额单位、状态含义、字段来源、时间分区、权限范围、容差、业务 Oracle。
- 待确认问题：未确认前不得实现或只能按明确豁免推进的问题清单。
- 验收映射：每条 P0/P1 口径对应的自然语言测试用例、测试数据和证据路径。

推荐落点：

- 跨任务稳定约束：`docs/context/feature-pack.md`、`docs/context/architecture-brief.md`、`docs/architecture/constraints.md`。
- 需求与口径：`docs/product/`、`docs/testing/NATURAL_LANGUAGE_TEST_CASES.md`、`docs/testing/TRACEABILITY_MATRIX.md`。
- 单任务约束：当前 task 的 `context_files`、`architecture_constraints`、`forbidden_implementations`、`qa_contract`。
- 临时阻塞和待确认项：对应 product / testing truth source 或 failed trace；不要写入根 `AGENTS.md`。

验收标准：如果一个约束会导致实现结果不同，它必须能从 Driver Context 指向的文件或 task 字段中找到；否则实现会话应输出 BLOCKED，而不是依赖聊天记忆。

## 自动任务规则

- 每次只处理一个 `passes: false` 的任务。
- 优先级数字越小越先执行。
- 所有依赖任务必须已经通过。
- `execution.mode` 缺省为 `single`，当前只允许 `single`。
- 修改后必须运行当前任务的 `test_command`。
- `feature_impl` 的 `test_command` 必须覆盖任务声明的开发验证和代码写完后的故事级验收链路；如果只能运行局部测试，任务必须 BLOCKED 或在 `qa_contract.exemptions` 中给出 owner 批准的替代证据。
- `release` 的 `test_command` 必须覆盖发布候选级跨故事整链路、P0/P1 回归和必要契约/E2E/视觉验证；不得只重复各子任务的单元测试。
- 测试失败时禁止提交，禁止把 `passes` 改为 `true`。
- 阻塞时必须追加 `progress.txt`，输出 `BLOCKED - 需要人工介入`，然后停止。

## 多轮协作与交接

- 会话结束时，至少把 `CURRENT_TASK.md` 中的已完成内容、未完成内容、修改文件、为什么这样改、已通过测试、未运行测试和下一步补齐。
- 下一个 Agent 续跑前，先重新读取 `AGENTS.md`、本文件、`.codex/rules/agents.md`、相关 truth source 和 `CURRENT_TASK.md`，再决定是否继续写代码。
- 多 Agent 协作必须按 `owned_paths`、目录边界、分支或 PR 拆开；不要让多个 Agent 同时改同一文件或同一组可写路径。
- 如果发现上一个 Agent 的修改范围、目标或测试状态不清楚，先补交接文档，再继续实现。

## 轻量与完整 Harness 边界

| 模式 | 可用条件 | 不可省略 |
| --- | --- | --- |
| lightweight | 小范围、低风险、无跨服务/契约/数据迁移/权限影响，验证命令直接明确 | `owned_paths`、`test_command`、验收、trace、Git gate |
| full | 有明确交付目标、多人协作、跨模块、状态复杂、测试或文档可复用 | truth source、计划冻结字段、qa_contract、review gate、archive |
| enterprise | 多服务、多仓库、契约、外部系统、灰度、回滚、数据一致性 | 服务依赖矩阵、契约 gate、失败/回滚验证、多维 review |

如果任务从 lightweight 扩大到 full 或 enterprise，当前任务应先 BLOCKED 或拆分任务，不要在实现中临时扩大范围。

## 工作区规则

- 启动前 Git 工作区必须干净，除非用户明确说明哪些改动属于本任务。
- 如需忽略 smoke 残留、历史 trace 或其他已声明的运行产物，只允许通过 `runtime.git.non_blocking_dirty_paths` 明确列白名单。
- `non_blocking_dirty_paths` 只允许包含可再生运行产物，例如 `progress.txt`、`SMOKE-RESULT.md`、`traces/`、`artifacts/`；不要把源码、配置或业务文档加入白名单。
- 不要修改与当前任务无关的文件。
- 所有任务相关变更必须和 `task.json`、`progress.txt` 同一个 commit。

## 推荐做法

- 先收敛 truth source，再进入实现。
- 大任务先拆成多个 `single` 任务，再交给 driver 顺序执行。
- 当主控遇到文档、规则、任务队列、前端、后端或测试相关写入时，分别委派 `docs-worker`、`harness-writer`、`frontend-worker`、`backend-worker`、`test-runner` 等 writer 角色处理。
- 目录级规则变化优先落到最接近该目录的子目录 `AGENTS.md`；根 `AGENTS.md` 只保留全局入口规则。
- 如果某个实现任务已经锁定了 `owned_paths`，且这些路径属于已完成架构设计的独立模块目录，那么该目录的子目录 `AGENTS.md` 应在第一轮实现前就存在；缺失时先补规则，再写代码。
- 实现阶段可以使用子代理并行加速，但必须按 owned paths 或明确文件组拆分；如需并行写入，不允许多个角色同时写同一路径。
- 每个 writer 子代理启动前必须声明允许修改、禁止修改、验收输出和验证命令；只读子代理只能返回结构化结论。
- 子代理不得修改 `task.json`、`progress.txt`、`traces/` 或 Git 状态；主实现会话必须整合子代理输出并运行当前任务 `test_command`。
- 任何子代理在开始前，先读 `AGENTS.md`、本文件、`.codex/rules/agents.md`、当前 truth source 和对应 `.agents/skills/*/SKILL.md`（如存在）。
- 如果当前轮次是被 stop hook 强制继续后的续跑，先重新阅读上述文档，再决定是否真的需要子代理。

## 模型策略

- 默认模型和思考强度定义在 `.codex/task-run-profile.json`。
- 如需任务级覆盖，使用 `task.execution.modelPolicy`。
