@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,55 +0,0 @@
-# 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

@@ -1,196 +0,0 @@
-# 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

@@ -1,116 +0,0 @@
-# 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

@@ -1,187 +0,0 @@
-# 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

@@ -1,74 +0,0 @@
-# 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 执行。