@pzy560117/codex-harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,55 @@
+# 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` | 变更前必须通过的契约、分支、兼容性、灰度或回归检查 |
+| `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、失败态和回写证据。
+
+## 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,116 @@
+# Task 会话策略
+
+## 默认策略
+
+- 每个任务默认使用 fresh process。
+- 子代理默认采用 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`，不能留给实现会话猜。
+- 创建或重建任务队列时必须一次性补齐每个任务的完整交接字段：`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` 是主控唯一执行入口。
+
+## 状态文件压缩规则
+
+- `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 - 需要人工介入`，然后停止。
+
+## 轻量与完整 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`。

package/package-source/docs/codex-harness-engineering/templates/docs/team-knowledge-sync.md

@@ -0,0 +1,187 @@
+# Team Knowledge Sync
+
+本文定义项目级 `docs/knowledge/` 与可选团队知识库之间的同步协议。团队知识库是知识复利层，不是 driver 的运行依赖；没有外部知识库时，本地任务仍必须可以完成、验证和提交。
+
+## 目标
+
+- 把项目中已经验证的通用经验提升为团队资产。
+- 让多个项目共享同一套技术知识、业务知识和团队约定。
+- 用 Git、Markdown 和追加日志保留知识来源、贡献者、验证证据和冲突处理记录。
+- 避免把未验证的单次经验直接升级为全局规则或团队规范。
+
+## 推荐仓库结构
+
+团队知识库建议独立成 Git 仓库，不寄生在任何业务项目中：
+
+```text
+team-knowledge/
+  knowledge-catalog.md        # 团队级全景入口
+  .knowledge-config.yaml      # 成员、角色、同步和冲突策略
+  log.md                      # 只追加的知识变更日志
+  team-conventions/           # Layer 0-T: 团队约定
+  tech-wiki/                  # Layer 1: 跨项目技术知识
+    catalog.md
+  biz-wiki/<domain>/          # Layer 2: 领域业务知识
+    catalog.md
+  project-profiles/           # 项目画像和知识源映射
+  contributions/
+    pending/                  # 待合并贡献
+    conflicts/                # 内容矛盾和人工裁决项
+```
+
+项目仓库只保存 Layer 3 项目知识：
+
+```text
+docs/knowledge/
+  knowledge-catalog.md
+  catalog.md
+  models/
+  decisions/
+  guidelines/
+  pitfalls/
+  processes/
+  archive/
+```
+
+## 角色
+
+| 角色 | 权限 | 典型职责 |
+| --- | --- | --- |
+| `maintainer` | 审批 proven、裁决冲突、维护目录和成员 | 决定团队知识是否升级为约定、规则或模板 |
+| `contributor` | 提交新条目、追加 evidence、标记冲突 | 从项目归档中输出 `contributions/pending/` |
+| `reader` | 读取知识，不写入团队仓库 | 新成员、外部协作方、只读自动化 |
+
+角色只影响团队知识库写入权限，不影响项目本地 `docs/knowledge/` 的归档任务。
+
+## 配置建议
+
+`.knowledge-config.yaml` 可使用以下最小形状：
+
+```yaml
+team:
+  name: example-team
+  default_role: reader
+roles:
+  maintainers: []
+  contributors: []
+sync:
+  accept_layers: [tech-wiki, biz-wiki]
+  default_domain:
+  require_maintainer_for_proven: true
+conflicts:
+  on_content_conflict: stage_to_conflicts
+  on_maturity_conflict: keep_lower_and_mark_contradiction
+```
+
+项目 driver 不应依赖该配置存在。缺少配置时，只输出候选报告，不直接写外部仓库。
+
+## 贡献流程
+
+1. `ARCHIVE-*` 从本轮 trace、review、failure triage 和 `progress.txt` 中提取项目知识。
+2. 条目先进入项目 `docs/knowledge/`，新增条目默认 `maturity: draft`。
+3. `KNOWLEDGE-TEAM-SYNC-*` 只挑选具备跨项目价值的 `verified` 或 `proven` 候选。
+4. 候选写入团队仓库 `contributions/pending/`，保留项目来源、贡献者、验证证据和建议目标层。
+5. maintainer 审核后合入 `tech-wiki/`、`biz-wiki/<domain>/` 或 `team-conventions/`。
+6. 合入时追加 `log.md`，记录日期、动作、贡献者、来源项目、条目 ID 和 evidence。
+
+## 自动合并与冲突策略
+
+| 情况 | 默认处理 |
+| --- | --- |
+| 不同 ID 的纯新增条目 | 可自动进入 `contributions/pending/` |
+| 同一条目追加 `evidence`、`last_referenced` 或 `contributors` | 可自动合并并去重 |
+| `draft -> verified` | 需要至少一个真实任务引用并有验证证据 |
+| `verified -> proven` | 需要两个不同任务或项目的证据，或 maintainer 明确审批 |
+| 内容结论相反 | 写入 `contributions/conflicts/`，等待 maintainer 裁决 |
+| 一方提升成熟度、一方降级成熟度 | 保留较低成熟度并标记 `contradiction` |
+| 删除或归档团队知识 | 必须有人类审批和 `log.md` 记录 |
+
+自动化只能生成候选、追加 evidence、修复索引；不得静默删除团队知识或把单次经验提升为 `proven`。
+
+## 追加日志
+
+`log.md` 只追加，不重写历史。推荐格式：
+
+```markdown
+## [2026-05-12] promote | <contributor> | <source-project> | +1 guideline | #<trace-or-commit>
+- GUIDELINE-API-001: 分页接口必须声明稳定排序字段 (verified -> proven)
+```
+
+每次团队知识变更至少记录：
+
+- action: `ingest`、`verify`、`promote`、`decay`、`conflict`、`archive`
+- contributor
+- source project
+- source trace、commit、review finding 或文档路径
+- affected knowledge IDs
+
+## 条目元数据补充
+
+团队知识条目除项目知识的基本 frontmatter 外，建议补充：
+
+```yaml
+evidence:
+  contributors:
+    - name: codex
+      source_project: example-project
+      source_ref: traces/TASK-001-20260512.json
+  last_referenced:
+  validated_projects: []
+  contradictions: []
+```
+
+如果项目知识仍使用简化 frontmatter，也应在同步候选里补齐 evidence，而不是丢失来源。
+
+## 降级与失败处理
+
+- 团队知识仓库不可用时，任务只能记录 `blocked_external_knowledge_sync` 或输出候选报告，不应阻塞本地实现验证。
+- 外部仓库 push 失败时，不要伪造已同步状态；把候选保留在项目报告或本地 pending 文件里。
+- 外部知识和项目事实冲突时，以当前项目可验证事实为准，并输出 conflict candidate。
+- 衰减和归档必须先形成候选，再由 maintainer 或独立任务确认。
+
+## 任务模板片段
+
+需要把团队知识同步加入 `task.json` 时，可按项目裁剪以下任务。该任务是可选上层能力，不应成为所有项目的默认阻塞任务。
+
+```json
+{
+  "id": "KNOWLEDGE-TEAM-SYNC-001",
+  "description": "把项目知识中的跨项目候选输出到团队知识库贡献暂存区",
+  "task_kind": "archive",
+  "phase": "archive",
+  "gate_profile": "lightweight",
+  "required_truth_sources": ["knowledge"],
+  "priority": 95,
+  "dependencies": ["ARCHIVE-001"],
+  "passes": false,
+  "context_files": [
+    "docs/harness/knowledge-architecture.md",
+    "docs/harness/team-knowledge-sync.md",
+    "docs/knowledge/knowledge-catalog.md",
+    "docs/knowledge/catalog.md"
+  ],
+  "owned_paths": [
+    "docs/knowledge/"
+  ],
+  "execution": { "mode": "single" },
+  "steps": [
+    "读取 promotion candidates，筛选具备跨项目价值的 verified/proven 条目",
+    "如果团队知识库可用，输出 contributions/pending 候选并追加同步报告",
+    "如果团队知识库不可用，仅在项目内记录候选、缺失配置和后续人工步骤",
+    "内容冲突写入 conflict candidate，不直接覆盖团队知识"
+  ],
+  "test_command": "git diff --check",
+  "acceptance": [
+    "同步结果或候选报告可追溯到项目知识条目和 evidence",
+    "没有把 draft 或单次经验直接升级为团队 proven 知识",
+    "外部团队知识库不可用时没有阻塞本地 driver 验证"
+  ]
+}
+```
+
+## 相关文档
+
+- 项目知识架构：`docs/harness/knowledge-architecture.md`
+- 冷启动导入：`docs/harness/knowledge-import.md`
+- 知识健康检查：`docs/harness/knowledge-lint.md`
+- Prompt 知识集成：`docs/harness/prompt-knowledge-integration.md`

package/package-source/docs/codex-harness-engineering/templates/docs/trace-format.md

@@ -0,0 +1,74 @@
+# Trace Format 模板
+
+## 1. 文件命名
+
+```text
+traces/<task-id>-<yyyyMMdd-HHmmss>.json
+```
+
+## 2. 必需字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `task_id` | string | 当前任务 id |
+| `agent` | string | 执行代理，如 `codex` |
+| `started_at` | string | ISO 8601 开始时间 |
+| `ended_at` | string | ISO 8601 结束时间 |
+| `status` | enum | `passed`、`failed`、`blocked` |
+| `commands` | array | 执行命令和退出码 |
+| `stage1_review` | object | Stage 1 审查 verdict、退出码和摘要 |
+| `stage2_review` | object | Stage 2 审查 verdict、退出码和摘要 |
+
+## 3. 推荐字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `task_session_id` | string | 当前 task 的 fresh session id |
+| `task_kind` | string | 任务类型，例如 `harness`、`smoke`、`feature_impl` |
+| `gate_profile` | string | 本任务启用的 gate 强度 |
+| `schema_version` | string | trace schema 版本 |
+| `session_dir` | string | 当前 task session 的持久日志目录 |
+| `events_file` | string/null | implementation 阶段主 Codex JSONL 事件流文件；review JSONL 如有保留，仍记录在 `log_files` / `logs` |
+| `log_files` | array | implementation / review / test output 等日志文件路径 |
+| `evidence_files` | array | 与当前任务关联的额外证据附件 |
+| `role` | string | 当前 Agent 的角色，例如 `frontend`、`backend`、`reviewer` |
+| `model` | string | 实际使用的模型 |
+| `reasoning_effort` | enum | 实际使用的思考深度: `none`、`low`、`medium`、`high`、`xhigh` |
+| `model_policy` | object | 模型策略来源，例如 policy 文件和 role 覆盖路径 |
+| `required_truth_sources` | array | 本任务必须满足的 truth source 类型 |
+| `files_changed` | array | Git 检测到的文件 |
+| `blocked_reason` | string/null | 阻塞原因 |
+| `final_message` | string | Codex 最终消息摘要 |
+| `test_command` | string | 当前任务验证命令 |
+| `qa_evidence` | object/null | 测试用例、Oracle、证据文件、副作用断言、假测试检测和失败复现摘要 |
+| `failed_stage` | string/null | 失败发生在哪个 gate |
+| `unexpected_paths` | array | commit path ownership gate 阻断时记录超出 `owned_paths` / runtime allowlist 的路径 |
+| `review_context` | object | Stage 1 / Stage 2 对照的真相源文件集合 |
+| `truth_source_state` | array | truth source 满足情况、已找到路径和缺失项 |
+| `knowledge_references` | array | 当前任务读取并实际使用的知识条目 |
+| `knowledge_outputs` | array | 当前任务新增、更新或建议归档的知识条目 |
+| `archive_summary` | object/null | 归档阶段对知识引用、知识产出和成熟度变化的摘要 |
+| `logs` | object | implementation / stage review / test output 的日志文件路径 |
+
+## 3.1 `qa_evidence` 推荐结构
+
+```json
+{
+  "case_ids": ["TC-ORDER-CANCEL-007"],
+  "requirement_ids": ["REQ-ORDER-003"],
+  "oracles": ["response", "database", "event", "audit", "no_side_effect"],
+  "evidence_files": ["artifacts/tests/order-cancel-007.json"],
+  "side_effect_checks": ["db_snapshot_before_after", "event_not_emitted"],
+  "anti_fake_checks": {
+    "has_semantic_assertion": true,
+    "verifies_side_effect": true,
+    "source_bound": true,
+    "target_path_proven": true
+  },
+  "failure_repro": null
+}
+```
+
+## 4. 校验
+
+使用 `docs/harness/trace.schema.json` 校验 trace。CI 中可以用任意 JSON Schema validator 执行。