@pzy560117/codex-harness 0.1.3 → 0.1.5

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

@@ -1,55 +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 或配置。
-- 失败、回滚、兼容性和灰度路径是否有证据。
+# 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/package-assets/docs/harness/speckit-requirements-gate.md

@@ -8,13 +8,13 @@
 
 ## 2. 触发条件
 
-满足任一条件即触发：
-
-- 用户只给出一句高层需求，例如“做一个跨端宠物商城 App”。
-- 平台、技术约束、MVP 范围、用户角色、核心流程、数据源或验收标准缺失。
-- 存在多个合理方向，且不同选择会影响页面、架构、测试或任务拆分。
-- 用户没有明确说明这是“先做原型 / spike / demo”，还是要按既定系统、既定开源栈和真实环境做正式集成。
-- 用户表达“先看看方案”“帮我规划”“需求还没想清楚”等探索意图。
+满足任一条件即触发：
+
+- 用户只给出一句高层需求，例如“做一个跨端宠物商城 App”。
+- 平台、技术约束、MVP 范围、用户角色、核心流程、数据源或验收标准缺失。
+- 存在多个合理方向，且不同选择会影响页面、架构、测试或任务拆分。
+- 用户没有明确说明这是“先做原型 / spike / demo”，还是要按既定系统、既定开源栈和真实环境做正式集成。
+- 用户表达“先看看方案”“帮我规划”“需求还没想清楚”等探索意图。
 
 ## 3. 清晰度分级
 
@@ -45,21 +45,21 @@ Speckit 产物和项目 Harness 产物必须分层：
 
 ## 6. 允许与禁止
 
-允许：
-
-- 输出澄清选项。
-- 给出推荐选项及理由。
-- 维护临时草案或明确标注 `[NEEDS CLARIFICATION]` 的 spec。
-- 在用户回答后更新 spec 草案。
-- 在进入 `/speckit.plan` 前，先锁定当前 feature 的交付模式：`prototype` / `spike` / `integration` / `production`。
-
-禁止：
-
-- 在用户确认前创建 `docs/product/*`、`docs/design/*`、`docs/context/*` 作为正式真相源。
-- 在用户确认前把测试矩阵填成具体业务需求。
-- 在用户确认前新增 `task.json` 代码实现任务。
-- 把技术栈、页面范围、支付方式、后端模式等主观推测伪装成用户已确认需求。
-- 当需求里明确提到既定开源栈、外部系统或真实环境时，未获用户明确降级前，不得把本地 mock / sample adapter / 假数据方案当成正式集成默认值。
+允许：
+
+- 输出澄清选项。
+- 给出推荐选项及理由。
+- 维护临时草案或明确标注 `[NEEDS CLARIFICATION]` 的 spec。
+- 在用户回答后更新 spec 草案。
+- 在进入 `/speckit.plan` 前，先锁定当前 feature 的交付模式：`prototype` / `spike` / `integration` / `production`。
+
+禁止：
+
+- 在用户确认前创建 `docs/product/*`、`docs/design/*`、`docs/context/*` 作为正式真相源。
+- 在用户确认前把测试矩阵填成具体业务需求。
+- 在用户确认前新增 `task.json` 代码实现任务。
+- 把技术栈、页面范围、支付方式、后端模式等主观推测伪装成用户已确认需求。
+- 当需求里明确提到既定开源栈、外部系统或真实环境时，未获用户明确降级前，不得把本地 mock / sample adapter / 假数据方案当成正式集成默认值。
 
 ## 7. 标准交互格式
 
@@ -96,26 +96,26 @@ Speckit 产物和项目 Harness 产物必须分层：
 - “再完善下”
 - “还有没有问题”
 
-如果确认语义不明确，主会话只允许继续完善 spec / plan，不得生成 `task.json` 实现任务。
-
-## 9. 交付模式锁定
-
-在 `/speckit.plan` 之前，必须把当前 feature 明确归入以下其中一种模式，并写入 `spec.md`：
-
-- `prototype`: 目标是本地原型或可演示界面，不承诺真实外部依赖已接通。
-- `spike`: 目标是探索性验证，用来缩小不确定性，不承诺正式需求完成。
-- `integration`: 目标是按既定开源栈、既定平台或真实下游完成集成。
-- `production`: 目标是正式交付，除真实集成外，还要满足生产级验证、证据和回归要求。
-
-锁定规则：
-
-- 只要用户明确提到既定开源栈、既有平台、第三方系统、真实 endpoint、RBAC、dashboard/panel、报警链路或环境接入，默认按 `integration` 理解，除非用户明确说“先只做原型 / demo / exploratory”。
-- `prototype` / `spike` 路径可以创建 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 类交付，不得直接冒充正式 `FR-*` 完成。
-- `integration` / `production` 路径必须在 `plan.md` 里补齐开源项目复用矩阵、connector 边界、前置阻塞 `TBD-*`、证据文件路径和验证分层，缺一不可。
-
-## 10. Spec 确认后的自动补齐规则
-
-用户确认 spec 后，后续问题默认不再回问用户。主控必须自动查找最佳实践、官方文档、项目约束和现有代码，补齐技术计划、设计细节、测试矩阵和任务拆分。
+如果确认语义不明确，主会话只允许继续完善 spec / plan，不得生成 `task.json` 实现任务。
+
+## 9. 交付模式锁定
+
+在 `/speckit.plan` 之前，必须把当前 feature 明确归入以下其中一种模式，并写入 `spec.md`：
+
+- `prototype`: 目标是本地原型或可演示界面，不承诺真实外部依赖已接通。
+- `spike`: 目标是探索性验证，用来缩小不确定性，不承诺正式需求完成。
+- `integration`: 目标是按既定开源栈、既定平台或真实下游完成集成。
+- `production`: 目标是正式交付，除真实集成外，还要满足生产级验证、证据和回归要求。
+
+锁定规则：
+
+- 只要用户明确提到既定开源栈、既有平台、第三方系统、真实 endpoint、RBAC、dashboard/panel、报警链路或环境接入，默认按 `integration` 理解，除非用户明确说“先只做原型 / demo / exploratory”。
+- `prototype` / `spike` 路径可以创建 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 类交付，不得直接冒充正式 `FR-*` 完成。
+- `integration` / `production` 路径必须在 `plan.md` 里补齐开源项目复用矩阵、connector 边界、前置阻塞 `TBD-*`、证据文件路径和验证分层，缺一不可。
+
+## 10. Spec 确认后的自动补齐规则
+
+用户确认 spec 后，后续问题默认不再回问用户。主控必须自动查找最佳实践、官方文档、项目约束和现有代码，补齐技术计划、设计细节、测试矩阵和任务拆分。
 
 为节省主控上下文，自动补齐不得默认由主控单线程完成。主控必须把 research、技术选型比较、测试规划、设计细化、审查和失败归因等上下文密集工作委派给子代理或拆成 driver 任务；主控只接收结构化摘要、决策依据、文件路径和验证命令。
 
@@ -123,7 +123,7 @@ Speckit 产物和项目 Harness 产物必须分层：
 
 1. 已确认的 `specs/<feature>/spec.md`。
 2. 用户在 Clarifications 中给出的答案。
-3. 项目规则：`AGENTS.md`、`docs/harness/*`、`.codex/task-run-profile.json`。
+3. 项目规则：`AGENTS.md`、`docs/harness/*`、`.codex/task-run-profile.json`。
 4. 已存在代码、配置和测试约定。
 5. 官方文档、框架最佳实践和安全/可访问性通用规范。
 
@@ -134,51 +134,51 @@ Speckit 产物和项目 Harness 产物必须分层：
 - 用户之前确认的 spec 与后续新增要求发生冲突。
 - 自动查到的最佳实践之间存在重大取舍，且取舍会影响用户业务目标。
 
-如果只是技术实现细节、目录结构、测试工具、默认 UI 状态、错误处理策略或工程最佳实践，主控应自行决策并在 `research.md` / `plan.md` 中记录依据。
-
-## 10.1 需求增强与缺口阻塞
-
-`speckit-specify` 生成初稿后，进入 `speckit-plan` 或写入真实 `task.json` 前，必须执行一次需求增强扫描。该扫描不是可选润色，而是阻止“需求给到了但细节没补全”的硬门禁。
-
-需求增强扫描必须把需求分成三类：
-
-- `Explicit`: 用户原文明确写出的需求，不得改写含义。
-- `Inferred`: 可由业务上下文、工程最佳实践、平台常规行为或现有项目约束合理推出的隐式需求，必须写入 `Assumptions`、NFR、验收标准或测试矩阵。
-- `Decision Required`: 会改变业务范围、收费、合规、品牌承诺、真实外部依赖或用户体验主路径的缺口，必须写入 `[NEEDS CLARIFICATION]`、`Open Questions` 或 `TBD-*`，不得假装已确认。
-
-自动补齐至少覆盖：
-
-- 功能细节：角色、主流程、失败流、边界条件、空态、重复提交、取消/回退、权限拒绝、非法状态和副作用/无副作用。
-- UI 细节：default、loading、empty、error、permission_denied、disabled、long_content、mobile，以及截图或视觉验收证据。
-- API / 后端细节：参数校验、错误码、权限、幂等、数据生命周期、状态机、审计日志和异步任务可观测性。
-- 非功能需求：性能、安全、隐私、可访问性、兼容性、可用性、可观测性、数据一致性、备份/恢复、部署和运维约束；不适用时必须写明原因。
-- 测试与证据：正向、失败、边界、权限、状态流转、测试数据、可观察 Oracle、证据路径和 release impact。
-
-允许自动决策的内容：
-
-- 技术实现细节、目录结构、测试工具选择、错误展示默认策略、常见 UI 状态、通用安全基线和工程最佳实践。
-- 自动决策必须记录为 `Assumption`，并带有验证方式和“假设错误时影响”。
-
-必须回问或阻塞的内容：
-
-- 业务范围裁决、付费/结算/合规承诺、真实凭据/账号/密钥、第三方授权、品牌/法务口径、用户明确要求的外部系统行为。
-- 对 `integration` / `production` 模式，如果缺少真实 endpoint、RBAC、fixture、dashboard/panel、webhook 或证据环境，相关需求不得标记为 `Ready`。
-
-需求增强必须产出或更新 `specs/<feature>/requirements-enrichment.md`，最少包含：
-
-- `显式需求清单`
-- `自动推导需求清单`
-- `自动补齐的 NFR`
-- `Assumptions`
-- `Decision Required / Open Questions`
-- `Blocked Items`
-- `P0/P1 可测试性状态表`
-
-如果任一 P0/P1 需求缺少验收标准、测试数据、Oracle、证据路径或可执行验证方式，状态必须是 `Needs Clarification` 或 `Blocked`，不得进入 `feature_impl`。
-
-推荐委派边界：
-
-- `readonly-research`: 官方文档、框架最佳实践、安全/可访问性通用规范。
+如果只是技术实现细节、目录结构、测试工具、默认 UI 状态、错误处理策略或工程最佳实践，主控应自行决策并在 `research.md` / `plan.md` 中记录依据。
+
+## 10.1 需求增强与缺口阻塞
+
+`speckit-specify` 生成初稿后，进入 `speckit-plan` 或写入真实 `task.json` 前，必须执行一次需求增强扫描。该扫描不是可选润色，而是阻止“需求给到了但细节没补全”的硬门禁。
+
+需求增强扫描必须把需求分成三类：
+
+- `Explicit`: 用户原文明确写出的需求，不得改写含义。
+- `Inferred`: 可由业务上下文、工程最佳实践、平台常规行为或现有项目约束合理推出的隐式需求，必须写入 `Assumptions`、NFR、验收标准或测试矩阵。
+- `Decision Required`: 会改变业务范围、收费、合规、品牌承诺、真实外部依赖或用户体验主路径的缺口，必须写入 `[NEEDS CLARIFICATION]`、`Open Questions` 或 `TBD-*`，不得假装已确认。
+
+自动补齐至少覆盖：
+
+- 功能细节：角色、主流程、失败流、边界条件、空态、重复提交、取消/回退、权限拒绝、非法状态和副作用/无副作用。
+- UI 细节：default、loading、empty、error、permission_denied、disabled、long_content、mobile，以及截图或视觉验收证据。
+- API / 后端细节：参数校验、错误码、权限、幂等、数据生命周期、状态机、审计日志和异步任务可观测性。
+- 非功能需求：性能、安全、隐私、可访问性、兼容性、可用性、可观测性、数据一致性、备份/恢复、部署和运维约束；不适用时必须写明原因。
+- 测试与证据：正向、失败、边界、权限、状态流转、测试数据、可观察 Oracle、证据路径和 release impact。
+
+允许自动决策的内容：
+
+- 技术实现细节、目录结构、测试工具选择、错误展示默认策略、常见 UI 状态、通用安全基线和工程最佳实践。
+- 自动决策必须记录为 `Assumption`，并带有验证方式和“假设错误时影响”。
+
+必须回问或阻塞的内容：
+
+- 业务范围裁决、付费/结算/合规承诺、真实凭据/账号/密钥、第三方授权、品牌/法务口径、用户明确要求的外部系统行为。
+- 对 `integration` / `production` 模式，如果缺少真实 endpoint、RBAC、fixture、dashboard/panel、webhook 或证据环境，相关需求不得标记为 `Ready`。
+
+需求增强必须产出或更新 `specs/<feature>/requirements-enrichment.md`，最少包含：
+
+- `显式需求清单`
+- `自动推导需求清单`
+- `自动补齐的 NFR`
+- `Assumptions`
+- `Decision Required / Open Questions`
+- `Blocked Items`
+- `P0/P1 可测试性状态表`
+
+如果任一 P0/P1 需求缺少验收标准、测试数据、Oracle、证据路径或可执行验证方式，状态必须是 `Needs Clarification` 或 `Blocked`，不得进入 `feature_impl`。
+
+推荐委派边界：
+
+- `readonly-research`: 官方文档、框架最佳实践、安全/可访问性通用规范。
 - `requirements-trace-analyst`: spec 到页面、状态、数据、验收的追溯。
 - `test-runner` / `test-planner`: test matrix、E2E plan、seed data、failure triage。
 - `visual-reviewer` / `design-lead`: design brief、component map、screen states、visual parity plan。
@@ -186,7 +186,7 @@ Speckit 产物和项目 Harness 产物必须分层：
 
 子代理只返回高密度结果，不返回完整阅读材料。主控不得把子代理的完整 transcript 重新塞回主上下文。
 
-## 11. 跳过澄清与原型例外
+## 11. 跳过澄清与原型例外
 
 如果用户要求跳过澄清，必须在回复和 spec 中记录：
 
@@ -194,16 +194,16 @@ Speckit 产物和项目 Harness 产物必须分层：
 - 哪些高影响问题仍未确认。
 - 后续实现可能返工的范围。
 
-跳过澄清后只能创建 `spike` / `prototype` / `exploratory` 类任务，不能创建 production-ready 实现任务，除非用户明确接受范围不稳定和返工风险。
-
-如果用户明确说“直接做原型 / 先出 demo / 不要问”，允许进入原型路径，但任务必须标注：
-
-- `task_kind`: `prototype` 或 `spike`
-- `gate_profile`: `exploratory`
-- acceptance 中明确“不代表生产范围已确认”
-- 不得把演示型 deliverable 直接记为正式 `FR-*` 完成；要么改成 `PROTO-*` / `SPIKE-*` / `INTEGRATION-*`，要么明确记录哪些 `FR-*` 仍处于未完成集成态
+跳过澄清后只能创建 `spike` / `prototype` / `exploratory` 类任务，不能创建 production-ready 实现任务，除非用户明确接受范围不稳定和返工风险。
 
-## 12. Demo-first 默认路径
+如果用户明确说“直接做原型 / 先出 demo / 不要问”，允许进入原型路径，但任务必须标注：
+
+- `task_kind`: `prototype` 或 `spike`
+- `gate_profile`: `exploratory`
+- acceptance 中明确“不代表生产范围已确认”
+- 不得把演示型 deliverable 直接记为正式 `FR-*` 完成；要么改成 `PROTO-*` / `SPIKE-*` / `INTEGRATION-*`，要么明确记录哪些 `FR-*` 仍处于未完成集成态
+
+## 12. Demo-first 默认路径
 
 对有界面、流程或客户演示价值的产品，用户确认 spec / plan 后默认走 Demo-first 路径：
 
@@ -213,9 +213,9 @@ Speckit 产物和项目 Harness 产物必须分层：
 4. `DEMO-001` 用 mock 数据跑通可点击体验，记录启动命令、访问地址、已知问题和不接真实环境的边界。
 5. 正式 foundation / domain / verify 任务必须依赖 `DEMO-001`，不能跳过 Demo 直接进入后端、支付、推送、真实登录或生产级部署。
 
-`DEMO-001` 通过不代表生产就绪。它只证明核心流程能被用户体验和评审；真实接口、真实支付、真实设备、上架审核、安全合规仍要在后续正式任务中验证。
-
-## 13. 写入 task.json 前检查
+`DEMO-001` 通过不代表生产就绪。它只证明核心流程能被用户体验和评审；真实接口、真实支付、真实设备、上架审核、安全合规仍要在后续正式任务中验证。
+
+## 13. 写入 task.json 前检查
 
 生成真实实现任务前必须全部满足：
 
@@ -223,38 +223,38 @@ Speckit 产物和项目 Harness 产物必须分层：
 - spec 中无会影响范围、架构、测试或 UX 的未解决 `[NEEDS CLARIFICATION]`。
 - 用户确认语义明确，或已记录跳过澄清的风险和原型降级。
 - `speckit-plan` 已生成 plan / research，或项目 docs 中已有等价技术计划。
-- 正式项目真相源已从确认后的 spec / plan 同步。
-- P0/P1 需求已映射到页面、状态、数据、验收和测试。
-- 对既定开源栈或外部系统的需求，已明确锁定 `prototype` / `spike` / `integration` / `production` 模式。
-- 若模式为 `integration` / `production`，`plan.md` 已包含开源项目复用矩阵、前置阻塞 `TBD-*`、connector 分层和证据路径。
-- `task.json` 新任务只引用确认后的 truth sources。
-- 对 UI / App / Web / 小程序 / 客户演示类项目，任务队列包含 `DEMO-001`，且正式实现任务依赖它。
-
-## 14. 状态流转
+- 正式项目真相源已从确认后的 spec / plan 同步。
+- P0/P1 需求已映射到页面、状态、数据、验收和测试。
+- 对既定开源栈或外部系统的需求，已明确锁定 `prototype` / `spike` / `integration` / `production` 模式。
+- 若模式为 `integration` / `production`，`plan.md` 已包含开源项目复用矩阵、前置阻塞 `TBD-*`、connector 分层和证据路径。
+- `task.json` 新任务只引用确认后的 truth sources。
+- 对 UI / App / Web / 小程序 / 客户演示类项目，任务队列包含 `DEMO-001`，且正式实现任务依赖它。
+
+## 14. 状态流转
 
 ```text
 模糊需求
   -> 读取 speckit-specify / speckit-clarify skill
   -> 判定 CLEAR / PARTIAL / AMBIGUOUS / CONFLICTING
-  -> 识别缺口与高影响决策
-  -> 若涉及既定 OSS / 外部系统，先锁定 prototype vs real integration
-  -> 一次一个问题收集用户选择
-  -> 更新 specs/<feature>/spec.md 与 Clarifications
-  -> 用户确认 spec
+  -> 识别缺口与高影响决策
+  -> 若涉及既定 OSS / 外部系统，先锁定 prototype vs real integration
+  -> 一次一个问题收集用户选择
+  -> 更新 specs/<feature>/spec.md 与 Clarifications
+  -> 用户确认 spec
   -> 主控委派子代理查找最佳实践并执行 speckit-plan
   -> 从确认后的 spec / plan 同步项目设计与测试文档
   -> 先写入 Demo-first 队列并跑通 DEMO-001
-  -> 写入 task.json
-  -> tools/harness/codex-loop.ps1
-```
-
-## 15. 完成标准
+  -> 写入 task.json
+  -> tools/harness/codex-loop.ps1
+```
+
+## 15. 完成标准
 
 进入 `task.json` 前必须满足：
 
 - spec 中没有会影响范围、架构、测试或用户体验的未解决 `[NEEDS CLARIFICATION]`。
-- 用户已明确确认 spec 或明确接受跳过澄清的返工风险。
-- P0/P1 需求能映射到页面、状态、数据、验收和测试。
-- plan 已说明技术栈、验证命令、依赖和任务边界。
-- 若需求涉及既定开源栈或真实外部系统，spec 已锁定交付模式，plan 已补齐复用矩阵、阻塞项和证据路径。
-- 若项目有界面或客户演示价值，任务队列已明确 Demo-first 依赖：`DESIGN-ASSET-001` -> `PLAN-001` -> `DEMO-001` -> 正式实现。
+- 用户已明确确认 spec 或明确接受跳过澄清的返工风险。
+- P0/P1 需求能映射到页面、状态、数据、验收和测试。
+- plan 已说明技术栈、验证命令、依赖和任务边界。
+- 若需求涉及既定开源栈或真实外部系统，spec 已锁定交付模式，plan 已补齐复用矩阵、阻塞项和证据路径。
+- 若项目有界面或客户演示价值，任务队列已明确 Demo-first 依赖：`DESIGN-ASSET-001` -> `PLAN-001` -> `DEMO-001` -> 正式实现。

package/package-source/docs/codex-harness-engineering/templates/package-assets/root/PACKAGE.md

@@ -2,12 +2,12 @@
 
 ## Mode Policy
 
-当前包默认使用 thin project 安装语义：无 `-Mode` / `-Scope` 时，`tools/install/install-agent.ps1 -ProjectRoot .` 等价于 `-Scope project`，初始化项目运行必需的 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/` 和 `tools/`。
+当前包默认使用 thin project 安装语义：无 `-Mode` / `-Scope` 时，`tools/install/install-agent.ps1 -ProjectRoot .` 等价于 `-Scope project`，初始化项目运行必需的 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/` 和 `tools/`。
 
 保留的入口：
 
-- `-Scope project`：新默认 thin project 入口，保留瘦的项目级 `.agents/skills/`、`.agents/workflows/`，不复制完整 vendor 镜像、legacy docs 或 package template source。
-- `-Scope user`：只安装用户级 codex-harness package source 和用户级 package lock，不暴露全局 `.agents/skills/` / `.agents/workflows/`。
+- `-Scope project`：新默认 thin project 入口，保留瘦的项目级 `.agents/skills/`、`.agents/workflows/`，不复制完整 vendor 镜像、legacy docs 或 package template source。
+- `-Scope user`：只安装用户级 codex-harness package source 和用户级 package lock，不暴露全局 `.agents/skills/` / `.agents/workflows/`。
 - `-Scope vendor`：显式 vendor 入口，只复制项目内 `.agents/` vendor 包，适合离线或强隔离项目。
 - `-Mode full`：显式 legacy full 兼容入口，同时输出项目 runtime、完整 `.agents/` vendor 包和 legacy docs。
 - `-Mode project|vendor|user`：保留旧兼容入口；新项目优先使用 `-Scope user|project|vendor`。
@@ -19,25 +19,25 @@
 新项目默认安装：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
 ```
 
 显式 thin project：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope project
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope project
 ```
 
 显式 legacy full：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
 ```
 
 显式 vendor：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
 ```
 
 ## Smoke

package/package-source/docs/codex-harness-engineering/templates/package-assets/root/README.md

@@ -1,52 +1,52 @@
-# Codex Harness Agent Package
-
-本包默认使用方案 A 的极简根目录布局。安装后目标项目使用 `task.json + tools/harness/codex-loop.ps1` 作为自动执行入口，driver 负责选择任务、运行验证、写 trace、更新进度和提交结果。
-
-SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。
-
-## 安装
-
-从包含 当前仓库包根目录的项目父目录运行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
-```
-
-从已安装的 `.agents/` 自更新：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
-```
-
-## 安装产物
-
-- 项目根 `AGENTS.md`
-- `tools/harness/` 下的 `tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`
-- `tools/install/` 下的 `tools/install/bootstrap-codex-harness.ps1`、`tools/install/env-check.ps1`、安装脚本
-- 项目根 `task.json`、`progress.txt`
-- `tools/harness/templates/` 下的 `smoke-task.json`、`tools/harness/templates/project-task-template.json`
-- `docs/harness/trace.schema.json`
-- 项目根 `.codex/`
-- 项目根 `docs/harness/`、`docs/testing/`
-- 项目根 `.agents/` 完整能力包，包括 rules、skills、workflows、`.specify/` 和模板复制源
-
-## 使用顺序
-
-1. 读取项目根 `AGENTS.md`。
-2. 用 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*` 收敛项目上下文。
-3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
-4. 将确认后的任务写入 `task.json`。
-5. 运行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/verify.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1
-```
-
-## 验证安装包
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
-```
-
-该脚本现在只验证 full 安装形状。
+# Codex Harness Agent Package
+
+本包默认使用方案 A 的极简根目录布局。安装后目标项目使用 `task.json + tools/harness/codex-loop.ps1` 作为自动执行入口，driver 负责选择任务、运行验证、写 trace、更新进度和提交结果。
+
+SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。
+
+## 安装
+
+从包含 当前仓库包根目录的项目父目录运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+```
+
+从已安装的 `.agents/` 自更新：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Mode full -Force
+```
+
+## 安装产物
+
+- 项目根 `AGENTS.md`
+- `tools/harness/` 下的 `tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`
+- `tools/install/` 下的 `tools/install/bootstrap-codex-harness.ps1`、`tools/install/env-check.ps1`、安装脚本
+- 项目根 `task.json`、`progress.txt`
+- `tools/harness/templates/` 下的 `smoke-task.json`、`tools/harness/templates/project-task-template.json`
+- `docs/harness/trace.schema.json`
+- 项目根 `.codex/`
+- 项目根 `docs/harness/`、`docs/testing/`
+- 项目根 `.agents/` 完整能力包，包括 rules、skills、workflows、`.specify/` 和模板复制源
+
+## 使用顺序
+
+1. 读取项目根 `AGENTS.md`。
+2. 用 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*` 收敛项目上下文。
+3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
+4. 将确认后的任务写入 `task.json`。
+5. 运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/verify.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1
+```
+
+## 验证安装包
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
+```
+
+该脚本现在只验证 full 安装形状。