@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/REGRESSION_PLAN.md

@@ -0,0 +1,28 @@
+# 回归计划
+
+**功能 / 发布版本**:
+**最后更新**:
+**负责人**:
+
+## 受影响测试
+
+-
+
+## 影响面
+
+- 直接影响:
+- 间接影响:
+- 相关接口 / 契约:
+- 相关页面 / 路由:
+- 潜在风险:
+
+## P0 回归集合
+
+-
+
+## 发布证据
+
+- verify 摘要:
+- 契约验证:
+- e2e smoke:
+- 视觉一致性:

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/TEST_STRATEGY.md

@@ -0,0 +1,98 @@
+# 测试策略
+
+**功能 / 项目**:
+**最后更新**:
+**负责人**:
+
+## 测试层级
+
+- 单元:
+- 组件:
+- API / 契约:
+- 集成:
+- E2E:
+- 视觉:
+
+## 开发验证与验收验证分层
+
+Harness 把实现过程中的快速反馈和交付前的完整验收拆成两个独立闸门:
+
+| 闸门 | 目的 | 典型验证 | 完成条件 |
+| --- | --- | --- | --- |
+| 自然语言测试用例 | 把 PRD 每条需求转成可审查、可追溯、可转脚本的测试用例 | `NATURAL_LANGUAGE_TEST_CASES.md`、需求类型覆盖矩阵、Gherkin/步骤化用例、Oracle、测试数据、证据路径、TDD RED 预期失败 | 每条需求都要分类；P0/P1 按需求类型满足最小用例数；P2 需写用例或豁免原因；TDD 候选用例可被 `tdd_contract.red.source_case_ids` 引用 |
+| TDD RED | 在生产代码变更前证明新增或变更行为当前缺失 | 聚焦单元、组件、契约或 API 测试；必须先失败且失败原因匹配预期 | 作为 `tdd_contract.red` 证据进入任务；失败原因不是目标行为缺失时不得进入实现 |
+| TDD GREEN / REFACTOR | 用最小实现让同一聚焦测试通过，并在重构后保持相关验证绿色 | 同一 focused test、affected tests、coverage、lint 或类型检查 | 作为 `tdd_contract.green` 和 `tdd_contract.refactor_guard` 证据进入任务；不能替代最终验收 |
+| 开发验证 | 支撑编码过程中的快速反馈，证明局部改动没有破坏直接相关行为 | 单元、组件、局部 API、契约检查、affected tests、静态检查、类型检查、lint | 作为实现过程证据进入 `development_validation`，但不能单独声明任务完成 |
+| 验收验证 | 从用户、业务闭环或发布候选视角证明当前交付可被验收 | 用户故事完整链路、跨故事主流程、真实入口 E2E、数据副作用、失败态、P0/P1 回归、视觉/可访问性确认 | 作为完成前 fresh evidence 进入 `acceptance_validation`，缺失时任务必须 BLOCKED 或有 owner 批准的 exemption |
+
+开发验证通过只说明局部实现可继续推进，不等于用户验收通过。PRD 完成后、进入实现前必须先生成自然语言测试用例；每个 `feature_impl` 默认要求 TDD：从自然语言用例选择 TDD 候选，先写聚焦测试并确认 RED 失败，再写最小实现确认 GREEN，通过后才允许重构。每个 `feature_impl` 完成前必须在代码写完后重新运行故事级验收链路；每个 `release` 完成前必须运行发布候选级跨故事验收链路。验收验证不得直接复用编码中途的旧日志，除非证据协议明确证明其仍是当前变更集的 fresh evidence。
+
+## 自然语言用例规模规则
+
+自然语言测试用例不是每条需求固定写 1 条，而是先判定需求类型，再按 `NATURAL_LANGUAGE_TEST_CASES.md` 的覆盖矩阵取最小用例数。基础原则:
+
+- P0 需求默认不少于 5 条，P1 需求默认不少于 3 条，P2 可为 1-2 条并说明不进入 TDD 候选的原因。
+- 低于默认数量必须写明豁免原因、替代证据和 owner 批准人。
+- 只读查询至少覆盖正常、空数据和无权限；列表类还要覆盖筛选、分页、排序或组合条件。
+- 新增、编辑、删除等写操作至少覆盖成功副作用、输入失败、权限失败无副作用、非法状态或并发冲突。
+- 权限、状态机、异步链路、外部系统、金额库存、文件处理和安全需求必须按风险路径加量，不能只写 happy path。
+- 一个需求跨多个类型时，按风险最高类型取基准，再补齐其他类型的必需路径。
+- TESTCASE 阶段必须在覆盖检查表中写明“需求类型、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数、加量理由”，不足时不得进入 `feature_impl`。
+- 非 TDD 自然语言用例必须映射到 `story_full_chain`、`acceptance_validation`、回归或 `verify-matrix`，不能因为不适合作为 RED 种子就从验收链路消失。
+- 业务规则如果会影响状态流转、副作用、金额/库存、权限或幂等，必须至少有一条异常路径或无副作用路径用例。
+
+## QA Harness 最小闭环
+
+测试设计按下面顺序推进，不允许直接从需求跳到测试脚本:
+
+1. 资料输入: 读取需求、代码、API 契约、UI、数据模型、权限规则和历史缺陷。
+2. 风险建模: 输出业务实体、状态、角色权限、接口、数据副作用和外部依赖风险。
+3. 自然语言用例: 按 PRD / Requirement ID 识别需求类型和风险因子，按覆盖矩阵写出目标、来源、前置条件、动作、预期结果、Oracle、测试数据、证据路径和 TDD RED 预期失败。
+4. 测试意图: 将自然语言用例映射到测试层级、风险、数据和可执行验证命令。
+5. Oracle 审查: 通过后才生成或修改测试脚本。
+6. TDD RED: `feature_impl` 从 `NATURAL_LANGUAGE_TEST_CASES.md` 的 TDD 候选用例生成聚焦测试，运行 `tdd_contract.red.command`，确认失败原因匹配目标行为缺失并记录证据。
+7. TDD GREEN: 写最小实现后运行 `tdd_contract.green.command`，确认同一聚焦测试通过。
+8. TDD REFACTOR: 重构后运行 `tdd_contract.refactor_guard.command` 和必要覆盖率命令，确认相关验证仍通过。
+9. 开发验证: 编码过程中运行 affected tests、局部契约、类型检查、lint 或单元 / 组件测试，记录 `development_validation` 证据。
+10. 验收验证: 代码写完后从用户、业务闭环或发布候选视角运行完整链路，记录 `acceptance_validation` fresh evidence。
+11. 证据归档: 把命令、退出码、日志、截图、DB diff、事件、Trace 等写入证据路径。
+12. 失败归因: 区分产品缺陷、测试缺陷、环境问题和数据问题。
+13. 回归沉淀: 真实缺陷修复后补充回归用例或知识候选。
+
+## Oracle 优先规则
+
+每个测试用例必须在写脚本前定义至少一个业务 Oracle。写接口、状态流转、权限和数据一致性场景通常需要多个 Oracle 组合:
+
+| Oracle 类型 | 适用场景 | 最小要求 |
+| --- | --- | --- |
+| 返回值 | API、服务、UI 动作 | 状态码、错误码、关键字段和业务语义 |
+| Schema / Contract | API、事件、文件 | 字段类型、必填、枚举、版本兼容 |
+| 数据库副作用 | POST / PUT / PATCH / DELETE、批处理 | before / after diff、目标字段变化、非目标字段不变 |
+| 缓存 | 读写缓存、权限缓存、多租户 | key 维度、TTL、失效、跨用户隔离 |
+| 事件 / 队列 | 异步链路、Webhook、消息消费 | event type、payload、重试、幂等、DLQ |
+| 审计 | 登录、权限、资金、删除、审批 | actor、action、object、result、time |
+| 权限 | 水平越权、垂直越权、字段级权限 | 允许 / 拒绝符合权限矩阵，拒绝时无副作用 |
+| 状态机 | 订单、审批、发布、退款等状态流转 | 合法转移成功，非法转移失败且无污染 |
+| 不变量 | 金额、库存、次数、唯一性 | 余额 / 库存不为负，总额守恒，唯一业务结果 |
+| Trace / 证据 | E2E、集成、跨服务 | 命中预期链路、日志或 coverage 可证明目标路径 |
+
+## 假测试拦截规则
+
+Stage 2 必须拦截下列测试:
+
+- 只断言 `200`、`truthy`、元素存在或 snapshot，没有业务断言。
+- 写操作没有 DB、缓存、事件、审计、文件或通知等副作用断言。
+- 权限失败只断言 `403`，没有验证目标数据未变化、响应未泄露和缓存未污染。
+- mock 了当前被测 service、权限判断、状态机、数据库写入或核心业务路径。
+- 没有绑定 Requirement ID、代码分支、API 契约、安全风险、状态机转移或历史缺陷来源。
+- 没有执行证据，或证据不是当前变更集产生的 fresh evidence。
+- 测试名称覆盖多个路径，但实际只跑 happy path。
+
+## 阻塞性失败
+
+-
+
+## Fresh Evidence 策略
+
+- Stage 17 只确认 fresh evidence 和回归状态。
+- 缺少验收示例或需求追溯属于实现前缺口，不是 Stage 17 的任务。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/TRACEABILITY_MATRIX.md

@@ -0,0 +1,23 @@
+# 需求追溯矩阵
+
+**功能**:
+**最后更新**:
+**负责人**:
+
+| Req ID | 业务规则 | 页面 / 组件 | 状态 | API / 契约 | 数据 / 副作用 | Oracle | 测试层级 | 测试文件 / 计划 | 证据路径 | 风险 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| REQ-001 | | | 默认 | | | response + db | unit / component / api / e2e | | | P0 |
+| PKG-LAYER-P5-MIGRATE-APPLY | `-MigrateApply` 必须 plan-first、默认 dry-run、`-Confirm` 后只采纳 hash 一致 vendor 文件；drift/unknown/manual-review 阻断写入。 | CLI / PowerShell installer | legacy full / drift / unknown / missing / manual-review / thin no-op | `docs/agent-package-redesign/migration-plan.md`, `docs/harness/install-manifest-governance.md` | `.codex-harness/locks/package.lock.json`, `.agents/`, legacy docs；失败态 lock 不变且不删除文件 | command output + lock hash/managedFiles + no-side-effect filesystem evidence | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P5-APPLY-001..006` | `traces/`, test-install-modes 输出, doctor 输出, refresh CheckOnly 输出 | P1 |
+| PKG-LAYER-P6-READINESS | doctor readiness gate 必须只读区分 thin、legacy、vendor 和未安装项目并给出修复建议。 | CLI / doctor | thin clean / legacy residue / missing user package / vendor / no config | `docs/architecture/constraints.md`, `docs/harness/install-manifest-governance.md` | 文件系统只读；不得自动安装、迁移或删除 | doctor output + unchanged files + readiness fix command | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P6-READINESS-001..005`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/LAYERING-P6-READINESS-001/`, doctor 输出, smoke 输出 | P1 |
+| PKG-LAYER-P7-DEFAULT-THIN | 默认无参数安装必须输出 thin project，同时保留显式 legacy full/vendor/user 入口，并保证公开 plan 与实际输出一致。 | CLI / installer | default thin / explicit legacy full / vendor / user/project scope / thin plan / legacy plan | `docs/agent-package-redesign/target-layering-standard.md`, `docs/harness/new-project-usage.md` | `.codex-harness/`, `.codex/`, docs/spec；默认不得复制完整 `.agents`；plan 命令只读 | required/forbidden path assertions + plan output + package lock/config + doctor output | integration | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出, doctor 输出, verify 输出 | P1 |
+| PKG-LAYER-P8-CLI-ALIAS | 首选 install-user/init-project 入口必须调用现有 install-agent scope 语义或明确文档化等价入口，不得出现第二套安装逻辑。 | CLI / docs | wrapper path / documented equivalent / no double implementation | `docs/harness/new-project-usage.md`, `docs/agent-package-redesign/target-layering-standard.md` | 输出与 `-Scope user/project` 一致；manifest/lock/doctor 不被绕过 | command output or doc assertion + smoke equivalence | integration / doc check | `tools/harness/tests/test-install-modes.ps1`; `TC-PKG-LAYER-P8-CLI-ALIAS-001..003`; `docs/testing/TEST_DATA_MATRIX.md` | `traces/`, new-project-usage.md, refresh CheckOnly 输出 | P1 |
+
+## 规则
+
+- 每条 P0/P1 需求都必须恰好出现一次，或被明确拆分。
+- 每一行都必须指向至少一个测试层级和一个证据路径。
+- UI 行必须包含所需状态或明确豁免。
+- API / 数据行必须包含契约或 schema 校验证据。
+- 写操作、权限失败、非法状态流转和异步链路必须包含副作用或无副作用 Oracle。
+- 每条 P0/P1 业务规则至少要在矩阵中出现一次，并绑定页面状态、Oracle 和测试层级。
+- 缺少 Oracle 或证据路径的 P0/P1 行不能进入实现。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/templates/testing/verify-matrix.md

@@ -0,0 +1,51 @@
+# 验证矩阵
+
+**功能**:
+**任务 ID**:
+**生成时间**:
+
+| 检查项 | 命令 / 证据 | 必需 | 退出码 / 结论 | 报告路径 |
+| --- | --- | --- | --- | --- |
+| 验收 / 示例 | `ACCEPTANCE_EXAMPLES.md` + `ACCEPTANCE_CRITERIA.md` | P0/P1 必需 | | |
+| 追溯 | `TRACEABILITY_MATRIX.md` | P0/P1 必需 | | |
+| 静态检查 | `git diff --check` | 必需 | | |
+| 类型检查 | | 项目相关 | | |
+| Lint | | 项目相关 | | |
+| 开发验证 | affected tests / unit / component / local contract / typecheck / lint | 代码变更时必需 | | |
+| 单元 | | 代码变更时必需 | | |
+| 组件 | | UI 变更时必需 | | |
+| 契约 | | API / 数据变更时必需 | | |
+| API 集成 | | 后端变更时必需 | | |
+| Oracle 审查 | `TEST_STRATEGY.md` + `test-matrix.md` | P0/P1 / 高风险必需 | | |
+| 副作用断言 | DB diff / cache / event / audit / file evidence | 写操作、状态流转、异步必需 | | |
+| 状态唯一来源检查 | `frontend-architecture.md` 状态表 + CURRENT_TASK 状态决策 | UI / 表单 / 查询状态变更时必需 | | |
+| 缓存失效检查 | cache key / invalidate 证据 / refetch 结果 | 远程数据、列表、详情、统计变更时必需 | | |
+| 权限无副作用 | denied response + unchanged data + no leak | 权限 / 多租户必需 | | |
+| 输入校验检查 | schema / validator + invalid payload response | API / 表单 / 文件上传时必需 | | |
+| 敏感信息脱敏检查 | response/log/trace redaction evidence | 涉及账号、支付、PII、密钥时必需 | | |
+| 风控 / 限流检查 | rate limit / captcha / idempotency evidence | 登录、注册、验证码、支付、上传等高风险入口必需 | | |
+| 假测试检测 | Stage 2 review | 测试改动时必需 | | |
+| 受影响测试 | changed-code-related tests | 业务逻辑变更时必需 | | |
+| 用户验收链路 | story entry + action + business Oracle + side effect / no-side-effect evidence | feature_impl 完成前必需 | | |
+| E2E | | P0/P1 主流程变更时必需 | | |
+| P0 回归 | 核心 P0 场景 | 发布前必需 | | |
+| 发布候选验证 | cross-story flow + P0/P1 regression + contract/API + E2E/visual as applicable | release 完成前必需 | | |
+| 失败态验收 | negative path / denied path / invalid state / downstream failure evidence | P0/P1 / 高风险必需 | | |
+| 视觉一致性 | `visual-parity-review.md` | UI 变更时必需 | | |
+| 覆盖率 | `coverage-summary.json` | 如策略适用 | | |
+| PKG-LAYER-P5-MIGRATE-APPLY 自然语言用例 | `docs/testing/NATURAL_LANGUAGE_TEST_CASES.md` 中 `TC-PKG-LAYER-P5-APPLY-001..006` | P1 必需 | planned | `traces/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P5-MIGRATE-APPLY TDD RED/GREEN/REFACTOR | `tools/harness/tests/test-install-modes.ps1` 先补迁移执行失败断言，再实现通过 | P1 必需 | planned | `traces/` |
+| PKG-LAYER-P5-MIGRATE-APPLY 验收链路 | clean legacy full、drift、unknown、missing vendor、manual-review、thin no-op smoke | P1 必需 | planned | `traces/`, doctor 输出, refresh CheckOnly 输出 |
+| PKG-LAYER-P6-READINESS 自然语言用例 | `TC-PKG-LAYER-P6-READINESS-001..005` 覆盖 thin clean、missing user package、legacy residue、vendor、no config | P1 必需 | verified | `traces/LAYERING-P6-READINESS-001/`, doctor/test-install-modes 输出 |
+| PKG-LAYER-P6-READINESS 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `readiness-thin-clean`、`readiness-missing-user-package`、`readiness-legacy-residue`、`readiness-vendor-lock`、`readiness-no-config` | P1 必需 | verified | `traces/LAYERING-P6-READINESS-001/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P7-DEFAULT-THIN 自然语言用例 | `TC-PKG-LAYER-P7-DEFAULT-THIN-001..006` 覆盖默认 thin、显式 legacy full、project/vendor/user scope、thin plan 和 legacy plan | P1 必需 | verified | `traces/LAYERING-P7-DEFAULT-THIN-001/`, test-install-modes 输出 |
+| PKG-LAYER-P7-DEFAULT-THIN 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `p7-default-thin-install`、`p7-legacy-full-install`、`p7-scope-project-install`、`p7-scope-vendor-install`、`p7-scope-user-install`、`p7-install-plan-profiles` | P1 必需 | verified | `traces/LAYERING-P7-DEFAULT-THIN-001/`, `tools/harness/tests/test-install-modes.ps1` |
+| PKG-LAYER-P8-CLI-ALIAS 自然语言用例 | `TC-PKG-LAYER-P8-CLI-ALIAS-001..003` 覆盖等价入口、install-user wrapper、init-project wrapper 和 no-double-implementation 风险 | P1 必需 | planned | `traces/LAYERING-P8-CLI-ALIAS-001/`, docs/harness/new-project-usage.md |
+| PKG-LAYER-P8-CLI-ALIAS 测试数据矩阵 | `docs/testing/TEST_DATA_MATRIX.md` 中 `p8-install-user-wrapper`、`p8-init-project-wrapper`、`p8-wrapper-no-double-implementation` | P1 必需 | planned | `traces/LAYERING-P8-CLI-ALIAS-001/`, `tools/harness/tests/test-install-modes.ps1` |
+
+## 最终规则
+
+最终交付要求每一行必需项都有 fresh evidence，或提供明确的 BLOCKED / exemption 记录并获得 owner 批准。
+开发验证和验收验证是两类独立证据：单元、组件、局部 smoke、类型检查、lint 或 affected tests 不能替代用户验收链路；各子任务局部测试通过也不能替代发布候选验证。
+用户验收链路、发布候选验证和失败态验收必须在实现完成后以当前变更集重新运行，证据需要能回溯到 Requirement ID、入口、测试数据、Oracle 和证据路径。
+Stage 17 只应确认新鲜度与回归状态；缺失的验收示例或首次测试范围定义不应在这里补写。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/README.md

@@ -1055,16 +1055,16 @@ Codex macOS 应用：
 | eval-harness | 评估驱动的开发 |
 | strategic-compact | 上下文管理 |
 | api-design | REST API 设计模式 |
-| verification-loop | 构建、测试、代码检查、类型检查、安全 |
-
-### Harness / Codex 项目补充
-
-如果你把 ECC / Codex 用在带 `AGENTS.md`、`docs/ai/repo-map.md`、`docs/testing/*` 的工程中，建议额外遵守两条：
-
-1. 涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环时，先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构，再进入具体实现。
-2. 这类高风险任务在进入实现或 E2E 代码生成前，先补齐 `docs/testing/e2e-plan.md`；测试失败后先做 `TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY` 一级分类，再决定修复路径。
-
-### 关键限制
+| verification-loop | 构建、测试、代码检查、类型检查、安全 |
+
+### Harness / Codex 项目补充
+
+如果你把 ECC / Codex 用在带 `AGENTS.md`、`docs/ai/repo-map.md`、`docs/testing/*` 的工程中，建议额外遵守两条：
+
+1. 涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环时，先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构，再进入具体实现。
+2. 这类高风险任务在进入实现或 E2E 代码生成前，先补齐 `docs/testing/e2e-plan.md`；测试失败后先做 `TEST_CODE_ISSUE / PRODUCT_BUG / REQUIREMENT_CHANGE / ENV_OR_DATA_ISSUE / FLAKY` 一级分类，再决定修复路径。
+
+### 关键限制
 
 Codex **尚未提供与 Claude 风格同等的钩子执行功能**。ECC 在该平台上的强制执行是通过 `AGENTS.md`、可选的 `model_instructions_file` 覆盖以及沙箱/批准设置以指令方式实现的。
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/e2e.md

@@ -24,19 +24,19 @@ description: 使用 Playwright 生成并运行端到端测试。创建测试旅
 * 验证前端和后端之间的集成
 * 为生产部署做准备
 
-## 工作原理
-
-e2e-runner 代理将：
-
-1. **分析用户流程**并识别测试场景
-2. **优先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构**，再补局部页面、接口和测试入口
-3. **使用页面对象模型模式生成 Playwright 测试**
-4. **跨多个浏览器（Chrome、Firefox、Safari）运行测试**
-5. **捕获失败**，包括截图、视频和跟踪
-6. **生成包含结果和工件的报告**
-7. **识别不稳定测试**并推荐修复方法
-
-如果仓库已经采用 Harness testing truth sources，建议先补齐 `docs/testing/e2e-plan.md`，再让 `/e2e` 落测试代码。对于只读研究阶段，应先通过 `repo-map`、验收示例、追溯矩阵和验证矩阵确定范围，而不是直接全仓扫描。
+## 工作原理
+
+e2e-runner 代理将：
+
+1. **分析用户流程**并识别测试场景
+2. **优先从 `docs/ai/repo-map.md` 或等价代码地图进入代码结构**，再补局部页面、接口和测试入口
+3. **使用页面对象模型模式生成 Playwright 测试**
+4. **跨多个浏览器（Chrome、Firefox、Safari）运行测试**
+5. **捕获失败**，包括截图、视频和跟踪
+6. **生成包含结果和工件的报告**
+7. **识别不稳定测试**并推荐修复方法
+
+如果仓库已经采用 Harness testing truth sources，建议先补齐 `docs/testing/e2e-plan.md`，再让 `/e2e` 落测试代码。对于只读研究阶段，应先通过 `repo-map`、验收示例、追溯矩阵和验证矩阵确定范围，而不是直接全仓扫描。
 
 ## 使用示例
 
@@ -236,9 +236,9 @@ open artifacts/search-results.png
 
 ````
 
-## 不稳定测试检测
-
-如果测试间歇性失败：
+## 不稳定测试检测
+
+如果测试间歇性失败：
 
 ```
 WARNING:  FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
@@ -254,20 +254,20 @@ WARNING:  FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
 3. 检查组件中的竞争条件
 4. 确认元素未被动画遮挡
 
-隔离建议: 在修复前标记为 test.fixme()
-```
-
-## 失败处理顺序
-
-不要在失败后第一时间弱化断言或跳过测试。先分类：
-
-1. `TEST_CODE_ISSUE`
-2. `PRODUCT_BUG`
-3. `REQUIREMENT_CHANGE`
-4. `ENV_OR_DATA_ISSUE`
-5. `FLAKY`
-
-然后再进入 owner 级归因和修复动作。对于 Harness 项目，建议把分类结果同步到 `docs/testing/failure-triage.md`。
+隔离建议: 在修复前标记为 test.fixme()
+```
+
+## 失败处理顺序
+
+不要在失败后第一时间弱化断言或跳过测试。先分类：
+
+1. `TEST_CODE_ISSUE`
+2. `PRODUCT_BUG`
+3. `REQUIREMENT_CHANGE`
+4. `ENV_OR_DATA_ISSUE`
+5. `FLAKY`
+
+然后再进入 owner 级归因和修复动作。对于 Harness 项目，建议把分类结果同步到 `docs/testing/failure-triage.md`。
 
 ## 浏览器配置
 

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

@@ -1,60 +1,60 @@
-# 外挂总知识库研究
-
-本目录研究 Codex Harness 的外挂总知识库。它不是当前项目的 `docs/knowledge/` 替代品，也不是泛技术百科，而是跨项目复用的 AI 软件工程质量知识库项目。
-
-## 目标
-
-- 在新项目启动前提供稳定的质量管理、软件工程和 Agent 工作流知识。
-- 把多个项目沉淀出来的 verified/proven 经验提升为团队资产。
-- 避免把一次性经验直接写进 `AGENTS.md`、prompt 或项目模板。
-- 在外部知识不可用时，本地 driver 仍能完成实现、验证和提交。
-- 优先解决 AI 编程中的需求未收敛、任务边界不清、假验证、伪实现、review 缺口和知识无法复用等痛点。
-
-## 目录
-
-| 文件 | 用途 |
-| --- | --- |
-| `architecture.md` | `team-wiki` 完整项目架构、模块、数据模型、质量门禁和同步协议 |
-| `initial-content.md` | 初始必须设定好的内容类型、目录和种子条目 |
-| `integration-roadmap.md` | 从文档方案到配置、脚本、任务模板和后续 RAG 的落地路线 |
-| `common/catalog.md` | 通用 AI Coding 生产控制知识入口 |
-| `common/AI_Coding_Production_Control_Framework_AI写完的代码如何不失控.md` | AI 生成代码不失控的架构、模式、实现、Review 和 Release Gate 通用框架 |
-| `app/catalog.md` | 移动端和全平台 App 生产可上线知识入口 |
-| `app/Mobile_App_Production_Readiness_Framework_移动端全平台生产可上线规范.md` | 移动端全平台生产可上线规范与宠物商城行业案例 |
-
-## 核心判断
-
-外挂总知识库应该先做成独立 `team-wiki` Git 项目和 Markdown catalog 体系，而不是一开始上向量库。原因是：
-
-- Git 能保留审计、review、回滚和冲突处理。
-- Markdown frontmatter 足够表达 maturity、source、tags 和适用阶段。
-- Catalog-first 查询能控制上下文，不会把大量知识塞进每轮 Codex。
-- 后续需要语义检索时，可以从同一批 Markdown 条目构建向量索引。
-
-## 领域扩展
-
-当前已新增 `common/` 通用扩展和 `app/` 领域扩展。
-
-`common/` 用于沉淀跨技术栈的 AI Coding 生产控制知识，例如架构边界、模式约束、任务拆分、Review Gate 和 Release Gate。使用时先读 `common/catalog.md`，只有任务命中 AI 生成代码治理、任务边界、架构/契约/安全风险或生产控制时才读取完整规范。
-
-`app/` 用于沉淀移动端和全平台 App 的生产可上线规范。该领域服务于 App PRD、移动端开发、QA、安全、隐私合规、商店审核和 Release Gate，不替代项目自身 PRD、架构约束、测试矩阵或法务合规结论。
-
-使用原则：
-
-1. 先读对应领域的 catalog。
-2. 只有任务明确命中 catalog 的触发条件时，才读取完整规范。
-3. 完整规范是长文档，不进入默认上下文源。
-
-## 与现有知识层关系
-
-```text
-外挂总知识库 team-wiki/            # 跨项目补充，非阻塞依赖
-  -> 项目接入时按需读取
-  -> 项目归档后接收候选贡献
-
-项目知识 docs/knowledge/           # 当前项目事实和本项目经验
-  -> 本地 driver 直接读取
-  -> 项目事实优先于外挂知识
-```
-
-项目事实、架构约束、PRD、测试矩阵始终高于外挂知识。外挂知识只能补充判断，不能覆盖当前项目 truth source。
+# 外挂总知识库研究
+
+本目录研究 Codex Harness 的外挂总知识库。它不是当前项目的 `docs/knowledge/` 替代品，也不是泛技术百科，而是跨项目复用的 AI 软件工程质量知识库项目。
+
+## 目标
+
+- 在新项目启动前提供稳定的质量管理、软件工程和 Agent 工作流知识。
+- 把多个项目沉淀出来的 verified/proven 经验提升为团队资产。
+- 避免把一次性经验直接写进 `AGENTS.md`、prompt 或项目模板。
+- 在外部知识不可用时，本地 driver 仍能完成实现、验证和提交。
+- 优先解决 AI 编程中的需求未收敛、任务边界不清、假验证、伪实现、review 缺口和知识无法复用等痛点。
+
+## 目录
+
+| 文件 | 用途 |
+| --- | --- |
+| `architecture.md` | `team-wiki` 完整项目架构、模块、数据模型、质量门禁和同步协议 |
+| `initial-content.md` | 初始必须设定好的内容类型、目录和种子条目 |
+| `integration-roadmap.md` | 从文档方案到配置、脚本、任务模板和后续 RAG 的落地路线 |
+| `common/catalog.md` | 通用 AI Coding 生产控制知识入口 |
+| `common/AI_Coding_Production_Control_Framework_AI写完的代码如何不失控.md` | AI 生成代码不失控的架构、模式、实现、Review 和 Release Gate 通用框架 |
+| `app/catalog.md` | 移动端和全平台 App 生产可上线知识入口 |
+| `app/Mobile_App_Production_Readiness_Framework_移动端全平台生产可上线规范.md` | 移动端全平台生产可上线规范与宠物商城行业案例 |
+
+## 核心判断
+
+外挂总知识库应该先做成独立 `team-wiki` Git 项目和 Markdown catalog 体系，而不是一开始上向量库。原因是：
+
+- Git 能保留审计、review、回滚和冲突处理。
+- Markdown frontmatter 足够表达 maturity、source、tags 和适用阶段。
+- Catalog-first 查询能控制上下文，不会把大量知识塞进每轮 Codex。
+- 后续需要语义检索时，可以从同一批 Markdown 条目构建向量索引。
+
+## 领域扩展
+
+当前已新增 `common/` 通用扩展和 `app/` 领域扩展。
+
+`common/` 用于沉淀跨技术栈的 AI Coding 生产控制知识，例如架构边界、模式约束、任务拆分、Review Gate 和 Release Gate。使用时先读 `common/catalog.md`，只有任务命中 AI 生成代码治理、任务边界、架构/契约/安全风险或生产控制时才读取完整规范。
+
+`app/` 用于沉淀移动端和全平台 App 的生产可上线规范。该领域服务于 App PRD、移动端开发、QA、安全、隐私合规、商店审核和 Release Gate，不替代项目自身 PRD、架构约束、测试矩阵或法务合规结论。
+
+使用原则：
+
+1. 先读对应领域的 catalog。
+2. 只有任务明确命中 catalog 的触发条件时，才读取完整规范。
+3. 完整规范是长文档，不进入默认上下文源。
+
+## 与现有知识层关系
+
+```text
+外挂总知识库 team-wiki/            # 跨项目补充，非阻塞依赖
+  -> 项目接入时按需读取
+  -> 项目归档后接收候选贡献
+
+项目知识 docs/knowledge/           # 当前项目事实和本项目经验
+  -> 本地 driver 直接读取
+  -> 项目事实优先于外挂知识
+```
+
+项目事实、架构约束、PRD、测试矩阵始终高于外挂知识。外挂知识只能补充判断，不能覆盖当前项目 truth source。