@pzy560117/codex-harness 0.1.4 → 0.1.6

package/package-source/docs/codex-harness-engineering/templates/docs/regression-rules.md

@@ -0,0 +1,47 @@
+# 回归规则
+
+| 风险 | 约束 |
+| --- | --- |
+| 误改文件 | Git 工作区清洁检查、task 边界、owned paths |
+| 漏测 | 每个任务必须运行 `test_command` |
+| 伪完成 | `passes=true` 必须建立在 fresh evidence 上 |
+| 文档漂移 | 规则、模板、命令改动后同步更新对应文档 |
+
+## 基本要求
+
+- 文档改动至少运行 `git diff --check`。
+- 代码改动必须运行与任务风险匹配的验证命令。
+- 不允许在未验证的情况下手工把任务标记为通过。
+
+## 需求到验证的左移规则
+
+- 测试从需求收敛阶段开始介入，不允许等代码完成后才第一次补测试范围。
+- 任何 P0/P1 需求进入实现前，至少要有 Requirement ID、业务规则、正向示例、异常示例、测试层级映射、测试数据说明和证据路径。
+- 任何 P0/P1 或高风险测试进入脚本实现前，必须先定义测试意图和 Oracle；写操作、权限、状态机、异步链路必须包含副作用或无副作用验证。
+- 创建或重建 `task.json` 时必须一次性补齐完整 QA 合约；后续不得依赖人工逐项补 `requirement_ids`、测试数据、Oracle、开发验证、最终验收验证、证据路径或整链路验证。
+- `docs/testing/TRACEABILITY_MATRIX.md`、验收示例和验证矩阵属于实现前 truth source；缺失时应优先补齐，而不是继续猜测实现。
+- 修改业务代码时必须同时检查测试影响；相关测试缺失时，先补测试骨架或测试计划，再继续实现。
+- Stage 2 必须拦截假测试，包括只断言 200 / truthy、只测 happy path、mock 被测逻辑、缺少业务断言、缺少执行证据或缺少来源绑定的测试。
+
+## 完成定义
+
+- 对外部系统、既定开源栈、第三方平台或真实环境的集成型需求，完成定义至少包含：真实依赖接上、真实请求走通、成功态证据、失败态证据。
+- 页面能打开、本地接口能返回、单元测试通过，都不足以声称正式 `FR-*` 已完成。
+- 每个 `feature_impl` 必须同时具备两段证据：编码过程中的 `development_validation`，以及代码写完后从用户 / 业务闭环视角重新运行的 `acceptance_validation`。
+- 每个 `feature_impl` 至少需要故事级完整链路验收证据；只跑单元测试、局部 smoke、affected tests、静态检查或 `git diff --check` 不足以完成任务。
+- 如果当前只是原型 / spike / exploratory 路径，不要把演示性交付直接标成正式 `FR-*` 完成；应改用 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 等单独标识，或在 spec / plan 中显式记录该 FR 仍处于未完成集成态。
+- 单元测试只能证明本地逻辑；集成型需求还必须补环境 smoke、E2E、真实下游连通性验证和验收证据 note。
+- Release 完成必须有发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证；不得把各子任务局部测试简单相加当作整测。
+- Stage 17 只负责 fresh evidence、affected tests 和 P0/P1 回归确认，不负责第一次定义需求测试范围。
+- 重构任务必须显式声明行为不变约束；接口、用户路径、数据结构和兼容逻辑不能在未说明时被顺手改变。
+- 重构结束前应按声明范围清理无用变量、无用函数、无用组件、无用类型、无用 import、临时代码和过期注释。
+
+## 技术栈验证基线
+
+| 改动类型 | 最小验证 |
+| --- | --- |
+| 文档 | `git diff --check` |
+| JSON | `ConvertFrom-Json` |
+| PowerShell | Parser 语法检查 |
+| TypeScript / 前端 | lint、typecheck、build |
+| API 或业务流程 | 单元测试、集成测试或 E2E，按风险选择 |

package/package-source/docs/codex-harness-engineering/templates/docs/requirement-prep-kit/README.md

@@ -0,0 +1,3 @@
+# Requirement Prep Kit
+
+本目录预留给需求收敛前的访谈、输入清洗、范围确认和验收准备模板。当前默认包不强制使用本目录；项目需要时可以在这里补充团队自己的需求准备表、访谈提纲或任务入口检查表。

package/package-source/docs/codex-harness-engineering/templates/docs/rule-governance.md

@@ -0,0 +1,98 @@
+# Harness Rule Governance
+
+本文定义规则如何进入 `AGENTS.md`、深文档、prompt、task template 和自动化检查。目标是控制指令预算，同时让关键约束可执行、可验证、可演进。
+
+## `docs/doc/1.md` 落地结论
+
+`docs/doc/1.md` 的核心价值不是把模板原样搬进本仓库，而是约束规则系统的形态：
+
+- `AGENTS.md` 做短入口，保留每次会话必须遵守的少量硬约束和深文档索引。
+- AI 可以从代码、schema、lint 或脚本推断 / 检查的内容，不进入 `AGENTS.md`。
+- 禁令必须带替代方案；例如不要伪造 `passes=true`，替代方案是让 `tools/harness/codex-loop.ps1` 在验证、review 和 commit gate 通过后写回状态。
+- Bad Case 先进入知识、prompt、role rules 或自动化检查；只有所有会话都必须知道时，才升级到 `AGENTS.md`。
+- 能自动检查的规则应进入 `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema、hook 或同步脚本，不长期只靠文字提醒。
+- 重要深文档必须被 `AGENTS.md` 引用，避免成为孤立文档。
+
+本仓库实践选择：入口文件控制在“读完即可开工”的长度；任务、验证、知识、prompt 和镜像同步细节分别落到 `docs/harness/*`、`.codex/rules/*.md`、`.codex/prompts/*` 和 `agent/` package mirrors。官方自动加载的 `.codex/rules/*.rules` 只承载命令执行策略。
+
+## 分层原则
+
+| 层级 | 放什么 | 不放什么 |
+| --- | --- | --- |
+| `AGENTS.md` | 每次会话都必须遵守的少量硬约束、入口索引 | 长模板、通用编码常识、会频繁变动的细节 |
+| `docs/harness/*` | driver、任务、验证、知识、治理等工程协议 | 具体业务需求 |
+| `.codex/rules/*.rules` | Codex 官方 execpolicy：命令 allow / prompt / forbidden | agent 编排、测试原则、编码风格、项目 instruction |
+| `.codex/rules/*.md` | agent 角色、阶段路由、协作边界等 Harness 语义规则 | 单个功能的临时计划；也不要误写成官方 execpolicy |
+| `.codex/prompts/*` | driver 注入给实现、review、repair 的执行提示 | 人类阅读优先的长说明 |
+| `task.json` | 当前真实任务队列和验证命令 | 模板示例、过期 smoke 占位 |
+
+## 规则进入标准
+
+只有满足以下至少一项，才应新增规则：
+
+- 同类问题在 review、trace 或失败记录中重复出现。
+- 违反后会造成安全、数据、提交、验证或上下文污染风险。
+- AI 无法从代码和现有文档自然推断。
+- 新人或新会话必须知道，否则会走错执行链路。
+
+以下内容默认不写进规则：
+
+- formatter、linter 已经确定性检查的风格细节。
+- “写清晰代码”这类无法改变行为的泛化建议。
+- README 面向人类读者的项目介绍。
+- 没有验证方式的一次性偏好。
+
+## 禁令写法
+
+禁令必须同时给替代方案：
+
+```text
+不要直接改 task.json 来伪造完成状态；应让 tools/harness/codex-loop.ps1 在验证、review 和 commit gate 通过后写回 passes=true。
+```
+
+如果无法给替代方案，先不要写成硬规则，改写成待确认风险或知识条目。
+
+## Bad Case 闭环
+
+每次出现 AI 错误，先判断应该落到哪里：
+
+| 错误类型 | 处理位置 |
+| --- | --- |
+| 单次任务失败 | `progress.txt`、trace、failure triage |
+| 可复用经验 | `docs/knowledge/pitfalls/` 或 `guidelines/` |
+| 会反复影响 driver 行为 | `.codex/prompts/*` 或 `.codex/rules/*.md` |
+| 可确定为命令权限边界 | `.codex/rules/*.rules` |
+| 所有会话必须知道 | `AGENTS.md` |
+| 可以自动检查 | `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema 或 hook |
+
+## 变更流程
+
+1. 先确认触发来源：trace、review finding、失败日志、用户明确要求或文档分析。
+2. 选择最小生效层级，不把深文档内容直接搬进 `AGENTS.md`。
+3. 如果改动影响模板或镜像，按 `harness-surface-sync` 同步 canonical source 和 mirrors。
+4. 运行最小验证：文档至少 `git diff --check`，JSON 需要 `ConvertFrom-Json`，PowerShell 需要 parser 检查。
+5. 提交前确认没有把 token、cookie、私钥、密码写入规则或 trace。
+
+## 定期治理
+
+建议每 10 个 driver 任务或每次较大 harness 改造后执行一次规则治理检查：
+
+- `AGENTS.md` 是否仍保持短入口。
+- 深文档是否有孤立规则没有被入口引用。
+- prompt 是否与 `AGENTS.md`、`.codex/rules/agents.md` 冲突。
+- `.codex/rules/*.rules` 是否仍只包含执行策略，且能通过 `codex execpolicy check`。
+- task template 是否还包含 smoke、示例领域或占位路径。
+- 知识条目是否有重复、过时、矛盾或长期未引用内容。
+
+## AGENTS.md 压缩检查表
+
+调整 `AGENTS.md` 时逐条检查：
+
+| 问题 | 处理 |
+| --- | --- |
+| 这条规则是否每次会话都必须知道？ | 是则保留，否则下沉到深文档 |
+| 这条规则是否已有脚本、schema、lint 或 hook 检查？ | 链接自动化位置，不重复写长说明 |
+| 这条规则是否只是通用工程常识？ | 删除 |
+| 这条规则是否只有禁止项？ | 补充替代方案，否则降级为风险说明 |
+| 这条规则是否源自单次失败？ | 先进入 `docs/knowledge/` 或 trace，不直接升级入口 |
+| 深文档是否在入口可发现？ | 在 `AGENTS.md` 索引补链接 |

package/package-source/docs/codex-harness-engineering/templates/docs/service-dependency-matrix.md

@@ -0,0 +1,70 @@
+# Service Dependency Matrix
+
+本文件说明 `.service-matrix/dependencies.yaml` 的维护口径。它是多服务、多仓库、IDL / API 契约或外部系统集成项目的可选 truth source；单体、小型前端或一次性脚本可以标记为 `not_applicable`。
+
+## 适用条件
+
+满足任一条件时，应启用服务依赖矩阵：
+
+- 一个需求会修改或影响多个服务、包、仓库、worker、前端应用或脚本入口。
+- 涉及 OpenAPI、protobuf、GraphQL schema、数据库 schema、消息事件、文件格式或第三方 API 契约。
+- 需要确认上游调用方、下游依赖方、灰度、回滚、兼容性或分支一致性。
+- 过去出现过“AI 只改了局部代码但漏掉调用链 / 契约 / 下游影响”的返工。
+
+## 维护原则
+
+- 矩阵只记录稳定拓扑和契约事实，不记录一次性任务过程。
+- 不把矩阵写成项目百科；每条依赖必须能回答“谁依赖谁、通过什么契约、变更时检查什么”。
+- 如果依赖需要人工确认，写 `status: needs-confirmation`，不得让实现任务继续猜。
+- 如果某个项目不需要矩阵，在 `docs/architecture/constraints.md` 中写明 `service_matrix: not_applicable`。
+
+## 最小字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `service_id` | 稳定服务、应用、包、worker 或集成名 |
+| `repo_path` | 当前仓库内路径或外部仓库标识 |
+| `entrypoints` | HTTP route、CLI command、worker、UI route、package export 等公开入口 |
+| `contracts` | OpenAPI、protobuf、GraphQL、typed API、schema、event、file format 或 `none` |
+| `upstream` | 调用本服务 / 包 / 入口的上游 |
+| `downstream` | 本服务 / 包 / 入口调用的下游 |
+| `change_gates` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
+| `callback_webhook` | 回调、Webhook、验签入口或 `none` |
+| `credential_source` | 凭据 / Secret 注入位置或 `none` |
+| `retry_idempotency` | 外部调用的重试、幂等、去重策略 |
+| `rate_limit_or_quota` | 第三方频率限制、配额或防刷规则 |
+| `failure_fallback` | 超时、失败、降级、补偿或人工介入策略 |
+| `owner` | 维护 owner 或确认人 |
+| `status` | `active` / `draft` / `needs-confirmation` / `deprecated` / `not_applicable` |
+
+## Driver 使用方式
+
+- `ANALYSIS` 阶段识别本轮需求是否需要服务矩阵；需要时补齐 `.service-matrix/dependencies.yaml`。
+- `PLAN` 阶段把受影响服务、契约和 change gates 映射到每个 `feature_impl` 的 `context_files`、`architecture_constraints`、`qa_contract` 和 `test_command`。
+- `feature_impl` 阶段不得新增未声明的跨服务影响；发现矩阵缺失或不可信时输出 `BLOCKED`。
+- `release` 阶段必须验证跨服务主链路、契约/API、失败态和回写证据。
+
+## 第三方服务专项
+
+如果依赖项属于支付、短信、邮件、推送、对象存储、上传扫描、OCR、AI API 或其他外部平台，矩阵至少补齐：
+
+- 回调 / Webhook / 验签入口
+- 凭据来源与注入位置
+- 幂等 / 重试 / 超时 / 降级策略
+- 频率限制、配额或防刷边界
+- 失败时的人工介入、补偿或对账路径
+
+## Review 口径
+
+Stage 1 先检查矩阵是否足以支撑实现计划：
+
+- 受影响服务是否都已列出。
+- 上下游、契约、分支或版本约束是否明确。
+- 是否有未确认依赖被实现任务当成已确认事实。
+- 验证命令是否覆盖矩阵中的 change gates。
+
+Stage 2 再检查代码是否真的遵守矩阵：
+
+- 公开入口、契约、实现、测试和证据是否一致。
+- 是否漏改下游调用、mock、生成代码、schema 或配置。
+- 失败、回滚、兼容性和灰度路径是否有证据。

package/package-source/docs/codex-harness-engineering/templates/docs/spec-to-ui-to-code-workflow.md

@@ -0,0 +1,196 @@
+# Spec To UI To Code Workflow 模板
+
+## 1. 工作流目标
+
+- 当前 feature:
+- 当前设计来源:
+- 当前 contract 来源:
+- 当前需要打通的主流程:
+
+## 2. 顺序
+
+```text
+Product Skeleton
+  -> page-inventory draft + requirement-interface-matrix draft + page-rules-draft
+  -> early-ai-image-brief
+  -> AI 生成 / 编辑第一轮界面方向图
+  -> early-ui-review
+  -> PRD / 页面 / 状态 / 字段 / 验收反哺
+  -> Product Spec
+  -> acceptance-criteria + acceptance-examples
+  -> requirement-interface-matrix + traceability-matrix + difficulty-research
+  -> test-matrix + risk-based-test-plan + regression-plan + test-data-plan + test-data-matrix
+  -> Design Brief
+  -> Frontend Quality Rules + Frontend Architecture
+  -> CSS / tokens / component / motion / responsive rules
+  -> AI image brief
+  -> AI 生成 / 编辑前端界面图
+  -> UI image review
+  -> image-to-frontend-spec
+  -> component-map + screen-states + design-tokens
+  -> frontend stories / components / pages
+  -> browser screenshot + visual parity review
+  -> OpenAPI contract
+  -> generated client + mock server
+  -> integration + e2e + visual regression
+  -> failure triage + repair/retest loop
+  -> knowledge archive + catalog update
+```
+
+## 3. 真相源
+
+- Product Spec:
+- Product Skeleton:
+- Page Rules Draft:
+- Early AI Image Brief:
+- Early UI Review:
+- Acceptance Criteria:
+- Acceptance Examples:
+- Traceability Matrix:
+- Test Strategy:
+- Risk Based Test Plan:
+- Regression Plan:
+- Evidence Protocol:
+- Design Brief:
+- Frontend Quality Rules:
+- Frontend Architecture:
+- 设计稿:
+- Component Map:
+- Screen States:
+- Design Tokens:
+- DEV-PLAN:
+- OpenAPI:
+- Verify Matrix:
+- Knowledge Catalog:
+
+## 4. 每阶段交付物
+
+### Phase 1A: Product Skeleton
+
+- [ ] `prd-lite.md` 初稿，至少包含目标、非目标、范围边界和角色。
+- [ ] `page-inventory.md` 初稿，至少覆盖所有 P0 页面。
+- [ ] `requirement-interface-matrix.md` 轻量版，至少把每条 P0/P1 需求映射到页面、区域、字段、操作和状态。
+- [ ] `docs/design/page-rules-draft.md`，写清页面类型、信息密度、基础视觉方向、关键组件、状态要求和禁止事项。
+- [ ] P0 页面已有主任务、核心字段、主要操作和异常/空/加载/权限状态草案。
+
+### Phase 1B: Early AI Image Direction
+
+- [ ] `docs/design/early-ai-image-brief.md`。
+- [ ] 第一轮 AI 生成 / 编辑的界面方向图，保存到 `artifacts/ai-images/early/`。
+- [ ] `docs/design/early-ui-review.md`。
+- [ ] `early-ui-review.md` 已检查：每条 P0/P1 需求是否能在图中找到界面证据，图片是否暴露页面数量、字段过载、路径过长、后台表格密度、移动端状态和权限视图问题。
+- [ ] `early-ui-review.md` 的结论已回填到 `prd-lite.md`、`page-inventory.md`、`state-matrix.yaml` 和 `requirement-interface-matrix.md`。
+
+### Phase 1C: Product Spec Completion
+
+- [ ] `prd-lite.md`
+- [ ] `page-inventory.md`
+- [ ] `state-matrix.yaml`
+- [ ] `acceptance-criteria.md`
+- [ ] `ACCEPTANCE_CRITERIA.md`
+- [ ] `ACCEPTANCE_EXAMPLES.md`
+- [ ] `requirement-interface-matrix.md`
+- [ ] `TRACEABILITY_MATRIX.md`
+- [ ] `difficulty-research.md`
+- [ ] `TEST_STRATEGY.md`
+- [ ] `test-matrix.md`
+- [ ] `RISK_BASED_TEST_PLAN.md`
+- [ ] `REGRESSION_PLAN.md`
+- [ ] `test-data-plan.md`
+- [ ] `TEST_DATA_MATRIX.md`
+- [ ] `EVIDENCE_PROTOCOL.md`
+- [ ] `failure-triage.md`
+- [ ] 目标、非目标、范围边界
+- [ ] 角色与权限矩阵
+- [ ] 异常流程、风险、假设、待确认点
+- [ ] 每条 P0/P1 需求都映射到界面、状态、字段、接口和验收
+- [ ] 每条 P0/P1 需求都映射到测试层级、测试数据、owner 和 evidence path
+- [ ] 每条 P0/P1 需求都映射到 affected tests 和回归范围
+- [ ] 每条 P0/P1 需求至少包含一个正向验收示例和一个异常示例
+- [ ] 高风险难点已有前置研究结论
+- [ ] 完整 Product Spec 没有绕过 Phase 1B 的早期视觉方向图和反哺记录
+
+### Phase 2: Design Brief
+
+- [ ] `design-brief.md`
+- [ ] `docs/harness/frontend-quality-rules.md` 已读取，目标质量等级已声明
+- [ ] `frontend-architecture.md` 或等价架构说明
+- [ ] 信息架构
+- [ ] 布局、交互、响应式、动效和可访问性规则
+- [ ] CSS / token 要求
+- [ ] 审美反模式和禁止事项
+- [ ] UX writing、空态、错误态、权限文案规则
+- [ ] 性能预算和复杂列表 / 表格处理策略
+- [ ] 默认态、加载态、空态、错误态、权限态、极端数据态、移动端状态
+
+### Phase 3: Final AI Image Maker
+
+- [ ] `ai-image-brief.md`
+- [ ] 基于 `early-ui-review.md` 和 Design Brief 生成 / 编辑的多状态前端界面图
+- [ ] `ui-image-review.md`
+
+### Phase 4: Image To Frontend Spec
+
+- [ ] `component-map.md`
+- [ ] `screen-states.md`
+- [ ] `design-tokens.json`
+- [ ] `frontend-architecture.md`
+- [ ] `image-to-frontend-spec.md`
+- [ ] `visual-parity-review.md` 截图矩阵已定义
+- [ ] stories / interaction / e2e / visual / a11y / performance 映射
+- [ ] 稳定测试选择器和关键视觉断言
+- [ ] 每个关键状态都写清状态源、渲染分支、触发路径和复验证据，禁止用页面说明文案冒充状态实现
+- [ ] desktop / tablet / mobile 响应式行为已写成可验证规格
+- [ ] 动效和 reduced motion 规则已写成可验证规格
+
+### Phase 5: Frontend
+
+- [ ] 组件实现
+- [ ] 页面实现
+- [ ] stories
+- [ ] 相关测试已新增或更新
+- [ ] 真实浏览器截图保存到 `artifacts/visual-review/`
+- [ ] 设计参考图与浏览器实拍图对比 PASS
+
+### Phase 6: Contract First
+
+- [ ] `contracts/openapi.yaml`
+- [ ] generated client
+- [ ] mock server
+- [ ] contract / schema / negative examples
+
+### Phase 7: Regression
+
+- [ ] Stage 1 review
+- [ ] Stage 2 review
+- [ ] verify
+- [ ] affected tests 与 P0/P1 regression 已运行
+- [ ] 契约验证、回归计划和 evidence protocol 已按本次变更刷新
+- [ ] `verify-matrix.md` 中必需项都有 fresh evidence
+- [ ] 若测试失败，`failure-findings.json` 已生成并进入 repair/retest loop
+
+### Phase 8: Knowledge Archive
+
+- [ ] `docs/knowledge/knowledge-catalog.md` 已存在
+- [ ] `docs/knowledge/catalog.md` 已按新增或更新条目刷新
+- [ ] 可复用 decision / guideline / pitfall / process / model 已归档
+- [ ] trace 或最终报告中的 `knowledge_references` 已被处理
+- [ ] 新增条目默认 maturity 为 `draft`，不得把单次经验直接提升为 `proven`
+
+## 5. 闸门
+
+- 不能完成 Product Skeleton: 缺 P0 页面清单、需求-界面轻量映射或 `docs/design/page-rules-draft.md`。
+- 不能完成 Product Spec: 缺第一轮 AI 界面方向图、`docs/design/early-ui-review.md`，或 early review 结论未反哺到 PRD、页面清单、状态矩阵和需求-界面追溯矩阵。
+- 不能进入 Design Brief: Product Spec 缺目标、非目标、范围、角色、页面、可执行验收示例、TRACEABILITY_MATRIX、需求-界面追溯矩阵或早期视觉评审结论。
+- 不能进入 AI Image Maker: Design Brief 缺视觉、CSS/tokens、布局、交互、响应式、动效、可访问性、文案或质量等级规则；高风险难点未研究。
+- 不能进入 Image To Frontend Spec: UI 图片未评审通过。
+- 不能进入前端实现: 缺 `image-to-frontend-spec.md`、`component-map.md`、`screen-states.md`、`design-tokens.json`、`frontend-architecture.md`、稳定测试选择器、响应式规格、动效规格或关键视觉断言。
+- 不能通过前端实现: 缺浏览器截图、缺移动端截图、缺设计参考图对比报告、缺 a11y smoke 结论，或 `visual-parity-review.md` Verdict 不是 PASS。
+- 不能通过前端实现: `loading / empty / error / disabled / permission / mobile` 等状态只作为界面说明文案出现，缺少真实状态源、渲染分支、触发路径或复验证据。
+- 不能进入联调: API / 数据变化没有 contract 或明确豁免。
+- 不能结束任务: 缺 Stage 1、Stage 2、verify、affected tests、P0/P1 regression 或 P0/P1 test matrix 的 fresh evidence。
+- 不能完成归档: 知识索引与条目不一致，或把一次性结论升级成全局规则却没有 evidence。
+
+## 6. 前端质量参考
+
+前端任务默认读取 `docs/harness/frontend-quality-rules.md`。如项目已有更具体的品牌、设计系统或平台规范，以项目规范为准，但不得低于本流程的状态覆盖、响应式、可访问性、证据和完成声明要求。

package/package-source/docs/codex-harness-engineering/templates/docs/task-session-strategy.md

@@ -0,0 +1,133 @@
+# 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。
+- 任务进入 driver 前必须冻结交付语义：`scope`、`non_goals`、`entrypoints`、`inputs_outputs`、`failure_policy`、`rollback_strategy`、`state_surface`、`writeback_targets`。不适用字段必须写 `not_applicable`，不能留给实现会话猜。
+- 进入实现前，`docs/ai/CURRENT_TASK.md` 必须能回答本轮已完成内容、剩余问题、修改文件、测试结果、风险点和下一步，不允许只靠聊天记忆续跑。
+- 创建或重建任务队列时必须一次性补齐每个任务的完整交接字段：`requirement_ids`、`owned_paths`、`context_files`、`produces_artifacts`、`test_command`、`acceptance`、自然语言测试用例、测试数据、开发验证、最终验收验证、证据路径和 `qa_contract`。不得创建“先跑起来、后面再补测试/证据/整链路”的实现任务。
+- 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`；缺少自然语言用例来源时不得进入实现阶段。
+- 不适合作为 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 角色处理。
+- 实现阶段可以使用子代理并行加速，但必须按 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`。