@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/context/dev-plan.md

@@ -21,45 +21,45 @@
 - Product Spec:
 - PRD-Lite:
 - Page Inventory:
-- State Matrix:
-- Acceptance Criteria:
-- Acceptance Examples:
-- Requirement Interface Matrix:
-- Traceability Matrix:
-- Difficulty Research:
-- Design Brief:
-- 设计稿 / Figma:
+- State Matrix:
+- Acceptance Criteria:
+- Acceptance Examples:
+- Requirement Interface Matrix:
+- Traceability Matrix:
+- Difficulty Research:
+- Design Brief:
+- 设计稿 / Figma:
 - Component Map:
 - Screen States:
 - Design Tokens:
 - AI Image Brief:
 - UI Image Review:
 - Image To Frontend Spec:
-- Visual Parity Review:
-- Contract:
-- Test Matrix:
-- E2E Plan:
-- Test Data Plan:
-- Test Data Matrix:
-- Risk Based Test Plan:
-- Regression Plan:
-- Evidence Protocol:
-- Failure Triage:
-- Coverage Policy:
-- Verify Matrix:
-- Repo map:
+- Visual Parity Review:
+- Contract:
+- Test Matrix:
+- E2E Plan:
+- Test Data Plan:
+- Test Data Matrix:
+- Risk Based Test Plan:
+- Regression Plan:
+- Evidence Protocol:
+- Failure Triage:
+- Coverage Policy:
+- Verify Matrix:
+- Repo map:
 
 ## 4. 阶段闸门
 
-| 阶段 | 进入条件 | 输出 | 未满足时处理 |
-| --- | --- | --- | --- |
-| Product Readiness | 原始需求已澄清，P0/P1 需求已补齐验收标准、验收示例和追溯入口 | `docs/product/*`, `ACCEPTANCE_CRITERIA.md`, `ACCEPTANCE_EXAMPLES.md`, `TRACEABILITY_MATRIX.md` | BLOCKED 或补需求 |
-| Design Readiness | Product Readiness 通过 | `docs/design/*` | BLOCKED 或补设计 |
-| UI Image Readiness | CSS/视觉规范完整，AI 生图已评审 | `ai-image-brief.md`, `ui-image-review.md`, `image-to-frontend-spec.md` | BLOCKED 或重生成/编辑图片 |
-| Visual Parity Readiness | 前端页面已实现并可在浏览器打开 | `artifacts/visual-review/*`, `visual-parity-review.md` | BLOCKED 或修复 UI 后重新截图 |
-| Test Readiness | P0/P1 需求已映射到测试层级、测试数据、affected tests、evidence path 和回归范围 | `test-matrix.md`, `TEST_DATA_MATRIX.md`, `RISK_BASED_TEST_PLAN.md`, `REGRESSION_PLAN.md`, `failure-triage.md` | BLOCKED 或补测试计划 |
-| Contract Readiness | API / 数据变化已明确 | `contracts/openapi.yaml` | BLOCKED 或豁免说明 |
-| Implementation | Product、Design、Plan、Testing 真相源齐全，Requirement IDs 已可追溯 | 代码、测试、trace | 禁止实现 |
+| 阶段 | 进入条件 | 输出 | 未满足时处理 |
+| --- | --- | --- | --- |
+| Product Readiness | 原始需求已澄清，P0/P1 需求已补齐验收标准、验收示例和追溯入口 | `docs/product/*`, `ACCEPTANCE_CRITERIA.md`, `ACCEPTANCE_EXAMPLES.md`, `TRACEABILITY_MATRIX.md` | BLOCKED 或补需求 |
+| Design Readiness | Product Readiness 通过 | `docs/design/*` | BLOCKED 或补设计 |
+| UI Image Readiness | CSS/视觉规范完整，AI 生图已评审 | `ai-image-brief.md`, `ui-image-review.md`, `image-to-frontend-spec.md` | BLOCKED 或重生成/编辑图片 |
+| Visual Parity Readiness | 前端页面已实现并可在浏览器打开 | `artifacts/visual-review/*`, `visual-parity-review.md` | BLOCKED 或修复 UI 后重新截图 |
+| Test Readiness | P0/P1 需求已映射到测试层级、测试数据、affected tests、evidence path 和回归范围；affected tests 与回归范围必须可追溯 | `test-matrix.md`, `TEST_DATA_MATRIX.md`, `RISK_BASED_TEST_PLAN.md`, `REGRESSION_PLAN.md`, `failure-triage.md` | BLOCKED 或补测试计划 |
+| Contract Readiness | API / 数据变化已明确 | `contracts/openapi.yaml` | BLOCKED 或豁免说明 |
+| Implementation | Product、Design、Plan、Testing 真相源齐全，Requirement IDs 已可追溯 | 代码、测试、trace | 禁止实现 |
 
 ## 5. Phase 划分
 
@@ -86,11 +86,12 @@
 
 ## 6. Task 拆分规则
 
-- 每个 Task 只处理一个明确目标。
-- 每个 Task 必须能在 fresh session 中完成。
-- 每个 Task 必须有自己的验证命令。
-- 每个实现 Task 必须声明 Requirement IDs、owned paths、affected tests 和 evidence expectation。
-- 不允许把“实现 + 修所有 bug + 补所有测试”混成一个任务。
+- 每个 Task 只处理一个明确目标。
+- 每个 Task 必须能在 fresh session 中完成。
+- 每个 Task 必须有自己的验证命令。
+- 每个实现 Task 必须声明 Requirement IDs、owned paths、affected tests 和 evidence expectation。
+- 每个实现 Task 还必须写明 evidence path 和回归范围，不能只写测试命令。
+- 不允许把“实现 + 修所有 bug + 补所有测试”混成一个任务。
 
 ## 7. 当前 Task 队列
 
@@ -101,57 +102,62 @@
 ## 8. 评审与修复闭环
 
 ```text
-实现
-  -> Stage 1 review（Spec / 设计稿 / DEV-PLAN 一致性）
-  -> 浏览器截图与设计参考图视觉还原对比
-  -> 修复偏差
-  -> Stage 2 review（代码质量 / 测试 / 风险）
-  -> 修复问题
-  -> verify + fresh evidence
-  -> 才允许完成
-```
-
-## 9. 验证矩阵
-
-- 类型检查:
-- Lint:
-- Acceptance / Examples:
-- Traceability:
-- 单元测试:
-- 组件 / Story 测试:
-- Contract 测试:
-- API integration:
-- 集成测试:
-- E2E:
-- Affected Tests:
-- P0/P1 Regression:
-- Visual regression:
-- Visual parity screenshots:
-- Contract validation:
-- Coverage:
-- Verify matrix:
+实现
+  -> Stage 1 review（Spec / 设计稿 / DEV-PLAN 一致性）
+  -> 浏览器截图与设计参考图视觉还原对比
+  -> 修复偏差
+  -> Stage 2 review（代码质量 / 测试 / 风险）
+  -> 修复问题
+  -> verify + fresh evidence
+  -> 才允许完成
+```
+
+## 9. 验证矩阵
+
+- 类型检查:
+- Lint:
+- Acceptance / Examples:
+- Traceability:
+- 单元测试:
+- 组件 / Story 测试:
+- Contract 测试:
+- API integration:
+- 集成测试:
+- E2E:
+- Affected Tests:
+- P0/P1 Regression:
+- Visual regression:
+- Visual parity screenshots:
+- Contract validation:
+- Coverage:
+- Verify matrix:
+- Backend layering check:
+- 事务 / 幂等验证:
+- 异常处理 / 错误码验证:
 
 ## 10. BLOCKED 条件
 
-- 缺少设计稿或状态矩阵
-- 缺少 PRD-Lite、页面清单或验收标准
-- 缺少可执行验收示例
-- 缺少需求到界面的完整追溯矩阵
-- 缺少 `TRACEABILITY_MATRIX.md` 或 Requirement IDs 无法落到代码/测试
-- 高风险难点没有研究结论
-- 缺少 Design Brief、Component Map、Screen States 或 Design Tokens
-- AI 生成界面图未评审通过
-- 图片未转换成前端可实现规格
-- 前端 UI 缺少真实浏览器截图和设计参考图对比报告
-- Contract 未冻结
-- P0/P1 需求缺少 `test-matrix.md` 映射
-- P0/P1 需求缺少 `TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md` 或 affected tests
-- E2E 缺少 seed 或账号数据
-- 测试失败没有 failure class 和 owner hint
-- 把 Stage 17 当成第一次定义测试范围的入口
-- 依赖任务未完成
-- 关键环境不可用
-- 需要人工决策
+- 缺少设计稿或状态矩阵
+- 缺少 PRD-Lite、页面清单或验收标准
+- 缺少可执行验收示例
+- 缺少需求到界面的完整追溯矩阵
+- 缺少 `TRACEABILITY_MATRIX.md` 或 Requirement IDs 无法落到代码/测试
+- 高风险难点没有研究结论
+- 缺少 Design Brief、Component Map、Screen States 或 Design Tokens
+- AI 生成界面图未评审通过
+- 图片未转换成前端可实现规格
+- 前端 UI 缺少真实浏览器截图和设计参考图对比报告
+- Contract 未冻结
+- Controller / Service / Repository 边界未声明
+- 事务、幂等或异常处理策略未声明
+- P0/P1 需求缺少 `test-matrix.md` 映射
+- P0/P1 需求缺少 `TEST_DATA_MATRIX.md`、`REGRESSION_PLAN.md` 或 affected tests
+- E2E 缺少 seed 或账号数据
+- 测试失败没有 failure class 和 owner hint
+- 把 Stage 17 当成第一次定义测试范围的入口
+- 依赖任务未完成
+- 关键环境不可用
+- 需要人工决策
 
 ## 11. 跨 Session 接续规则
 

package/package-source/docs/codex-harness-engineering/templates/context/feature-pack.md

@@ -1,101 +1,101 @@
-# Feature Pack 模板
-
-## 1. 基本信息
-
-- `feature_id`: `FEAT-000`
-- `title`: `示例：工单筛选与保存视图`
-- `source`: `issue / requirement doc / incident / cron`
-- `owner`: `Hermes / PM / Engineer`
-- `risk_level`: `L1`
-- `auto_merge_allowed`: `false`
-
-## 2. 业务目标
-
-- 这次变更要解决什么问题？
-- 成功后的业务结果如何判断？
-- 本期不解决什么问题？
-- 哪些开放问题会阻塞后续阶段？
-
-## 3. 影响范围
-
-- 页面:
-- 接口:
-- 目录:
-- 数据表:
-- 权限:
-- 外部系统:
-
-## 4. 需求分析真相源
-
-| 产物 | 路径 | 状态 | 备注 |
-| --- | --- | --- | --- |
-| PRD-Lite | `docs/product/prd-lite.md` | Draft / Approved / N/A | |
-| Page Inventory | `docs/product/page-inventory.md` | Draft / Approved / N/A | |
-| State Matrix | `docs/product/state-matrix.yaml` | Draft / Approved / N/A | |
-| Acceptance Criteria | `docs/product/acceptance-criteria.md` | Draft / Approved / N/A | |
-| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Draft / Approved / N/A | |
-| Difficulty Research | `docs/product/difficulty-research.md` | Draft / Approved / N/A | |
-
-## 5. 设计真相源
-
-| 产物 | 路径 | 状态 | 备注 |
-| --- | --- | --- | --- |
-| Design Brief | `docs/design/design-brief.md` | Draft / Approved / N/A | |
-| Component Map | `docs/design/component-map.md` | Draft / Approved / N/A | |
-| Screen States | `docs/design/screen-states.md` | Draft / Approved / N/A | |
-| Design Tokens | `docs/design/design-tokens.json` | Draft / Approved / N/A | |
-| AI Image Brief | `docs/design/ai-image-brief.md` | Draft / Approved / N/A | |
-| UI Image Review | `docs/design/ui-image-review.md` | Draft / Approved / N/A | |
-| Image To Frontend Spec | `docs/design/image-to-frontend-spec.md` | Draft / Approved / N/A | |
-
-## 6. 先决条件
-
-- 已存在的能力:
-- 依赖功能:
-- 环境要求:
-
-## 7. 状态矩阵
-
-- `default`:
-- `empty`:
-- `loading`:
-- `error`:
-- `disabled`:
-- `permission_denied`:
-- `long_content`:
-- `responsive/mobile`:
-
-## 8. 变更边界
-
-- 允许修改:
-- 禁止修改:
-- 生成代码目录:
-- 手写代码目录:
-
-## 9. 验收标准
-
-- [ ] 用户可以完成核心流程
-- [ ] 异常流有明确行为
-- [ ] 文档、contract、代码一致
-
-## 10. 验证命令
-
-```powershell
-pnpm lint
-pnpm typecheck
-pnpm test
-pnpm build
-```
-
-## 11. 输出要求
-
-- 需要更新的文档:
-- 需要补充的测试:
-- 需要生成的 client/types/mock:
-- 需要提交的 PR / issue / trace:
-
-## 12. 升级条件
-
-- 哪些情况必须 BLOCKED:
-- 哪些情况必须人工审批:
-- 哪些情况禁止自动合并:
+# Feature Pack 模板
+
+## 1. 基本信息
+
+- `feature_id`: `FEAT-000`
+- `title`: `示例：工单筛选与保存视图`
+- `source`: `issue / requirement doc / incident / cron`
+- `owner`: `Hermes / PM / Engineer`
+- `risk_level`: `L1`
+- `auto_merge_allowed`: `false`
+
+## 2. 业务目标
+
+- 这次变更要解决什么问题？
+- 成功后的业务结果如何判断？
+- 本期不解决什么问题？
+- 哪些开放问题会阻塞后续阶段？
+
+## 3. 影响范围
+
+- 页面:
+- 接口:
+- 目录:
+- 数据表:
+- 权限:
+- 外部系统:
+
+## 4. 需求分析真相源
+
+| 产物 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| PRD-Lite | `docs/product/prd-lite.md` | Draft / Approved / N/A | |
+| Page Inventory | `docs/product/page-inventory.md` | Draft / Approved / N/A | |
+| State Matrix | `docs/product/state-matrix.yaml` | Draft / Approved / N/A | |
+| Acceptance Criteria | `docs/product/acceptance-criteria.md` | Draft / Approved / N/A | |
+| Requirement Interface Matrix | `docs/product/requirement-interface-matrix.md` | Draft / Approved / N/A | |
+| Difficulty Research | `docs/product/difficulty-research.md` | Draft / Approved / N/A | |
+
+## 5. 设计真相源
+
+| 产物 | 路径 | 状态 | 备注 |
+| --- | --- | --- | --- |
+| Design Brief | `docs/design/design-brief.md` | Draft / Approved / N/A | |
+| Component Map | `docs/design/component-map.md` | Draft / Approved / N/A | |
+| Screen States | `docs/design/screen-states.md` | Draft / Approved / N/A | |
+| Design Tokens | `docs/design/design-tokens.json` | Draft / Approved / N/A | |
+| AI Image Brief | `docs/design/ai-image-brief.md` | Draft / Approved / N/A | |
+| UI Image Review | `docs/design/ui-image-review.md` | Draft / Approved / N/A | |
+| Image To Frontend Spec | `docs/design/image-to-frontend-spec.md` | Draft / Approved / N/A | |
+
+## 6. 先决条件
+
+- 已存在的能力:
+- 依赖功能:
+- 环境要求:
+
+## 7. 状态矩阵
+
+- `default`:
+- `empty`:
+- `loading`:
+- `error`:
+- `disabled`:
+- `permission_denied`:
+- `long_content`:
+- `responsive/mobile`:
+
+## 8. 变更边界
+
+- 允许修改:
+- 禁止修改:
+- 生成代码目录:
+- 手写代码目录:
+
+## 9. 验收标准
+
+- [ ] 用户可以完成核心流程
+- [ ] 异常流有明确行为
+- [ ] 文档、contract、代码一致
+
+## 10. 验证命令
+
+```powershell
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## 11. 输出要求
+
+- 需要更新的文档:
+- 需要补充的测试:
+- 需要生成的 client/types/mock:
+- 需要提交的 PR / issue / trace:
+
+## 12. 升级条件
+
+- 哪些情况必须 BLOCKED:
+- 哪些情况必须人工审批:
+- 哪些情况禁止自动合并:

package/package-source/docs/codex-harness-engineering/templates/context/repo-map.md

@@ -1,78 +1,102 @@
-# Repo Map
-
-更新时间: 2026-05-20
-维护责任: Harness package maintainer
-
-## 1. 仓库目标
-
-- 项目一句话描述: Codex Harness 安装实现包，用于把 AGENTS、driver、rules、prompts、skills、hooks、testing truth source 和 package docs 安装到目标项目。
-- 主要用户: 在 Windows / PowerShell 环境中使用 Codex CLI 的项目维护者和自动化执行 agent。
-- 核心业务域: driver-first 任务执行、安装包分发、规则治理、测试左移、知识沉淀、agent 能力同步。
-
-## 2. 从哪里开始读
-
-- 第一步先读: `AGENTS.md`
-- 第二步再读: `docs/ai/architecture-brief.md`
-- 第三步按任务进入:
-  - 安装链路: `tools/install/install-agent.ps1`, `tools/install/bootstrap-codex-harness.ps1`
-  - driver 链路: `tools/harness/codex-loop.ps1`, `.codex/prompts/*`
-  - 分发同步: `refresh-agent-package.ps1`, `.ai-sync.yml`
-  - 规则治理: `docs/harness/rule-governance.md`
-  - 包文档: `docs/codex-harness-engineering/*`
-
-## 3. 关键目录
-
-| 路径 | 用途 | 可修改性 | 备注 |
-| --- | --- | --- | --- |
-| repo root | 当前安装包包根 | 可改 | 新项目安装时主要来源 |
-| `.agents/` | 当前仓库活跃 package / skills 镜像 | 可改 | skills 以这里为活跃 canonical |
-| `.codex/` | 当前仓库 Codex roles、prompts、rules | 可改 | active role rules 以 `.codex/rules/agents.md` 为 canonical |
-| `docs/harness/` | driver、规则、知识、回归等深文档 | 可改 | root truth source |
-| `docs/testing/` | 测试左移真相源 | 可改 | feature_impl 前置输入 |
-| `docs/ai/` | AI 导航索引和架构摘要 | 可改 | 大型项目导航层 |
-| `docs/codex-harness-engineering/templates/` | 安装模板源 | 可改 | 会影响新项目 bootstrap |
-| `docs/codex-harness-engineering/templates/package-assets/` | 安装到目标 `.agents/` 的能力包 | 可改 | 需同步 `.agents` 镜像 |
-| `scripts/` | 辅助验证和同步脚本 | 谨慎 | 修改后做 PowerShell parser 检查 |
-
-## 4. 关键依赖关系
-
-- root runtime -> `refresh-agent-package.ps1` -> templates / package-assets mirrors。
-- root docs -> `templates/package-assets/docs/codex-harness-engineering/` -> 目标项目 `.agents/docs/...`。
-- `.agents/skills/<name>` -> `docs/codex-harness-engineering/templates/package-assets/skills/<name>` -> package-assets skill mirrors。
-- `tools/install/bootstrap-codex-harness.ps1` -> 目标项目根 runtime、`.codex/`、`docs/harness/`、`docs/testing/`、`docs/ai/`。
-
-## 5. 常用命令
-
-```powershell
-git status --short
-git diff --check
-powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
-```
-
-## 6. 禁改区
-
-- 禁止手工伪造 `task.json` 的 `passes=true`；应让 driver 验证后写回。
-- 禁止跳过 package mirrors：涉及 `.agents/`、templates、package-assets、skills 的改动必须按同步矩阵刷新。
-- 禁止把 token、cookie、私钥、密码写入 docs、trace、prompt 或 package。
-- 禁止在未确认时使用破坏性 Git 命令或递归删除。
-
-## 7. 任务入口
-
-- Feature plan 所在位置: `task.json` 或 `tools/harness/templates/project-task-template.json`
-- Product docs 所在位置: `docs/product/` 或 `docs/requirement-prep-kit/`
-- Design docs 所在位置: `docs/codex-harness-engineering/templates/design/`
-- Contract 所在位置: `docs/codex-harness-engineering/templates/contracts/`
-
-## 8. 子目录规则索引
-
-| 路径 | 本地规则 | 触发场景 |
-| --- | --- | --- |
-| repo root | `AGENTS.md` | 验证安装包入口规则和可分发文件 |
-| `.agents/` | `.agents/AGENTS.md` | 修改活跃 skills / workflows 镜像 |
-
-## 9. 维护规则
-
-- 新增安装时应落地的模板文件时，同时检查 `tools/install/bootstrap-codex-harness.ps1` 和 `.ai-sync.yml`。
-- 新增 package docs 时，同时更新 `docs/codex-harness-engineering/README.md` 和 package-assets 镜像。
-- 更新 skills 时，以 `.agents/skills/<name>` 为 canonical，再同步到 `docs/codex-harness-engineering/templates/package-assets/skills/<name>` 和两套 package-assets。
+# Repo Map
+
+更新时间: 2026-05-20
+维护责任: Harness package maintainer
+
+## 1. 仓库目标
+
+- 项目一句话描述: Codex Harness 安装实现包，用于把 AGENTS、driver、rules、prompts、skills、hooks、testing truth source 和 package docs 安装到目标项目。
+- 主要用户: 在 Windows / PowerShell 环境中使用 Codex CLI 的项目维护者和自动化执行 agent。
+- 核心业务域: driver-first 任务执行、安装包分发、规则治理、测试左移、知识沉淀、agent 能力同步。
+
+## 2. 从哪里开始读
+
+- 第一步先读: `AGENTS.md`
+- 第二步再读: `docs/ai/architecture-brief.md`
+- 第三步按任务进入:
+  - 安装链路: `tools/install/install-agent.ps1`, `tools/install/bootstrap-codex-harness.ps1`
+  - driver 链路: `tools/harness/codex-loop.ps1`, `.codex/prompts/*`
+  - 分发同步: `refresh-agent-package.ps1`, `.ai-sync.yml`
+  - 规则治理: `docs/harness/rule-governance.md`
+  - 包文档: `docs/codex-harness-engineering/*`
+
+## 2.1 上下文索引最小字段
+
+- 代码入口: 关键命令、路由、脚本或页面入口
+- 上游调用方: 谁会触发这个入口
+- 下游依赖: 入口继续调用哪些模块、脚本或接口
+- 类型/契约入口: 类型定义、contract、schema 或导出面
+- 测试入口: 关联测试、验证命令或证据目录
+- 配置入口: `.codex/*`、环境变量、配置文件、manifest
+- 风险入口: 权限、状态流转、安装升级、同步、数据边界
+- 禁改区: 当前任务默认不要碰的区域
+
+## 3. 关键目录
+
+| 路径 | 用途 | 可修改性 | 备注 |
+| --- | --- | --- | --- |
+| repo root | 当前安装包包根 | 可改 | 新项目安装时主要来源 |
+| `.agents/` | 当前仓库活跃 package / skills 镜像 | 可改 | skills 以这里为活跃 canonical |
+| `.codex/` | 当前仓库 Codex roles、prompts、rules | 可改 | active role rules 以 `.codex/rules/agents.md` 为 canonical |
+| `docs/harness/` | driver、规则、知识、回归等深文档 | 可改 | root truth source |
+| `docs/testing/` | 测试左移真相源 | 可改 | feature_impl 前置输入 |
+| `docs/ai/` | AI 导航索引和架构摘要 | 可改 | 大型项目导航层 |
+| `docs/codex-harness-engineering/templates/` | 安装模板源 | 可改 | 会影响新项目 bootstrap |
+| `docs/codex-harness-engineering/templates/package-assets/` | 安装到目标 `.agents/` 的能力包 | 可改 | 需同步 `.agents` 镜像 |
+| `scripts/` | 辅助验证和同步脚本 | 谨慎 | 修改后做 PowerShell parser 检查 |
+
+## 4. 关键依赖关系
+
+- root runtime -> `refresh-agent-package.ps1` -> templates / package-assets mirrors。
+- root docs -> `templates/package-assets/docs/codex-harness-engineering/` -> 目标项目 `.agents/docs/...`。
+- `.agents/skills/<name>` -> `docs/codex-harness-engineering/templates/package-assets/skills/<name>` -> package-assets skill mirrors。
+- `tools/install/bootstrap-codex-harness.ps1` -> 目标项目根 runtime、`.codex/`、`docs/harness/`、`docs/testing/`、`docs/ai/`。
+
+## 5. 常用命令
+
+```powershell
+git status --short
+git diff --check
+powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools/harness/verify.ps1
+```
+
+## 6. 禁改区
+
+- 禁止手工伪造 `task.json` 的 `passes=true`；应让 driver 验证后写回。
+- 禁止跳过 package mirrors：涉及 `.agents/`、templates、package-assets、skills 的改动必须按同步矩阵刷新。
+- 禁止把 token、cookie、私钥、密码写入 docs、trace、prompt 或 package。
+- 禁止在未确认时使用破坏性 Git 命令或递归删除。
+
+## 7. 任务入口
+
+- Feature plan 所在位置: `task.json` 或 `tools/harness/templates/project-task-template.json`
+- Product docs 所在位置: `docs/product/` 或 `docs/requirement-prep-kit/`
+- Design docs 所在位置: `docs/codex-harness-engineering/templates/design/`
+- Contract 所在位置: `docs/codex-harness-engineering/templates/contracts/`
+
+## 7.1 调用链与影响面提示
+
+- 关键调用链:
+  - 安装: `tools/install/*` -> `docs/codex-harness-engineering/templates/*` / `package-assets/*`
+  - driver: `tools/harness/codex-loop.ps1` -> `.codex/prompts/*` -> `task.json` / `docs/testing/*`
+  - 同步: `refresh-agent-package.ps1` -> `.agents/*` / templates / package-assets
+- 影响面分析时至少回答:
+  - 入口在哪里
+  - 上游是谁
+  - 下游是谁
+  - 受影响文件有哪些
+  - 受影响测试和验证命令有哪些
+
+## 8. 子目录规则索引
+
+| 路径 | 本地规则 | 触发场景 |
+| --- | --- | --- |
+| repo root | `AGENTS.md` | 验证安装包入口规则和可分发文件 |
+| `.agents/` | `.agents/AGENTS.md` | 修改活跃 skills / workflows 镜像 |
+
+## 9. 维护规则
+
+- 新增安装时应落地的模板文件时，同时检查 `tools/install/bootstrap-codex-harness.ps1` 和 `.ai-sync.yml`。
+- 新增 package docs 时，同时更新 `docs/codex-harness-engineering/README.md` 和 package-assets 镜像。
+- 更新 skills 时，以 `.agents/skills/<name>` 为 canonical，再同步到 `docs/codex-harness-engineering/templates/package-assets/skills/<name>` 和两套 package-assets。

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

@@ -1,25 +1,25 @@
-version: 1
-status: draft
-usage: "Optional truth source for multi-service, multi-repo, contract, or external-system work. Set status to not_applicable when the project has no cross-service dependency surface."
-services:
-  - service_id: "replace-with-service-or-app-id"
-    repo_path: "replace-with-repo-or-local-path"
-    owner: "replace-with-owner"
-    status: "needs-confirmation"
-    entrypoints:
-      - type: "replace-with-http|grpc|graphql|mq|cli|ui-route|package-api|worker|file-format|none"
-        path: "replace-with-entrypoint"
-    contracts:
-      - type: "replace-with-openapi|protobuf|graphql|typed-api|schema|event|file-format|none"
-        source: "replace-with-contract-path-or-not_applicable"
-        compatibility: "replace-with-backward-compatible|breaking|not_applicable|needs-confirmation"
-    upstream:
-      - "replace-with-caller-or-not_applicable"
-    downstream:
-      - "replace-with-dependency-or-not_applicable"
-    change_gates:
-      - "replace-with-contract-diff-or-api-test"
-      - "replace-with-affected-regression"
-    rollback:
-      strategy: "replace-with-feature-flag|revert|schema-rollback|not_applicable|needs-confirmation"
-      evidence: "replace-with-runbook-or-evidence-path"
+version: 1
+status: draft
+usage: "Optional truth source for multi-service, multi-repo, contract, or external-system work. Set status to not_applicable when the project has no cross-service dependency surface."
+services:
+  - service_id: "replace-with-service-or-app-id"
+    repo_path: "replace-with-repo-or-local-path"
+    owner: "replace-with-owner"
+    status: "needs-confirmation"
+    entrypoints:
+      - type: "replace-with-http|grpc|graphql|mq|cli|ui-route|package-api|worker|file-format|none"
+        path: "replace-with-entrypoint"
+    contracts:
+      - type: "replace-with-openapi|protobuf|graphql|typed-api|schema|event|file-format|none"
+        source: "replace-with-contract-path-or-not_applicable"
+        compatibility: "replace-with-backward-compatible|breaking|not_applicable|needs-confirmation"
+    upstream:
+      - "replace-with-caller-or-not_applicable"
+    downstream:
+      - "replace-with-dependency-or-not_applicable"
+    change_gates:
+      - "replace-with-contract-diff-or-api-test"
+      - "replace-with-affected-regression"
+    rollback:
+      strategy: "replace-with-feature-flag|revert|schema-rollback|not_applicable|needs-confirmation"
+      evidence: "replace-with-runbook-or-evidence-path"