@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/config/rules/constitution.md

@@ -79,7 +79,7 @@ Rationale for version bump (MAJOR):
 
 - 主控 agent 负责任务拆解、上下文分发、路径所有权、闸门判断、结果合并和最终交付。
 - Worker agent 必须拥有清晰的职责边界，例如前端、后端、测试、文档、评审、修复或发布。
-- 并发执行时，不同 agent 应使用独立目录或明确互斥的写入路径。
+- 并发执行时，不同 agent 应使用独立目录或明确互斥的写入路径。
 - Worker 结束时必须报告变更文件、验证命令、证据路径、未解决问题和需要主控合并的事项。
 - 主控不得盲目合并并行结果；必须检查冲突、重复实现、接口不一致和测试缺口。
 
@@ -181,7 +181,7 @@ Rationale for version bump (MAJOR):
 
 - 改变行为、接口、目录、命令、部署、测试或工作流时，必须同步更新相关文档。
 - 文档应说明当前事实、操作命令、验证方式和已知限制，避免只写愿景。
-- 长文档放 `docs/`，项目规则放项目根 `AGENTS.md`，跨项目语义规则放 `.codex/rules/*.md` 或全局规则；`.codex/rules/*.rules` 只放 Codex 命令执行策略。
+- 长文档放 `docs/`，项目规则放项目根 `AGENTS.md`，跨项目语义规则放 `.codex/rules/*.md` 或全局规则；`.codex/rules/*.rules` 只放 Codex 命令执行策略。
 - 文档改动至少运行格式或空白检查，例如 `git diff --check`。
 
 **理由**:
@@ -193,7 +193,7 @@ Rationale for version bump (MAJOR):
 
 **原则声明**:
 
-- Dirty workspace 默认视为风险，必须区分当前任务改动和用户已有改动。
+- Dirty workspace 默认视为风险，必须区分当前任务改动和用户已有改动。
 - 禁止未经确认回滚、覆盖、重置或删除用户改动。
 - 提交前必须查看 diff，并运行与交付声明直接相关的验证。
 - 提交应保持主题清晰，避免把无关文件混入同一提交。
@@ -259,7 +259,7 @@ Git 是多 agent 协作的事实边界。清晰提交和保守操作可以保护
 1. 用户当前明确指令
 2. 项目根 `AGENTS.md`
 3. 项目 `docs/`、`specs/`、`.specify/` 中的已批准规则
-4. 本宪章和 `.codex/rules/*.md`
+4. 本宪章和 `.codex/rules/*.md`
 5. 通用默认实践
 
 ### 修订程序

package/package-source/docs/codex-harness-engineering/templates/config/rules/git.rules

@@ -1,41 +1,41 @@
-prefix_rule(
-    pattern = ["git", "status"],
-    decision = "allow",
-    justification = "Read-only git status is required for harness workspace checks.",
-)
-
-prefix_rule(
-    pattern = ["git", "diff"],
-    decision = "allow",
-    justification = "Read-only diff inspection is required before verification and delivery.",
-)
-
-prefix_rule(
-    pattern = ["git", "log"],
-    decision = "allow",
-    justification = "Read-only commit history inspection is safe for context gathering.",
-)
-
-prefix_rule(
-    pattern = ["git", "show"],
-    decision = "allow",
-    justification = "Read-only object inspection is safe for review and evidence gathering.",
-)
-
-prefix_rule(
-    pattern = ["git", "add"],
-    decision = "prompt",
-    justification = "Staging changes must be scoped to the current harness task.",
-)
-
-prefix_rule(
-    pattern = ["git", "commit"],
-    decision = "prompt",
-    justification = "Commits require fresh verification and ownership checks.",
-)
-
-prefix_rule(
-    pattern = ["git", "push"],
-    decision = "prompt",
-    justification = "Pushing changes affects a remote repository and requires explicit intent.",
-)
+prefix_rule(
+    pattern = ["git", "status"],
+    decision = "allow",
+    justification = "Read-only git status is required for harness workspace checks.",
+)
+
+prefix_rule(
+    pattern = ["git", "diff"],
+    decision = "allow",
+    justification = "Read-only diff inspection is required before verification and delivery.",
+)
+
+prefix_rule(
+    pattern = ["git", "log"],
+    decision = "allow",
+    justification = "Read-only commit history inspection is safe for context gathering.",
+)
+
+prefix_rule(
+    pattern = ["git", "show"],
+    decision = "allow",
+    justification = "Read-only object inspection is safe for review and evidence gathering.",
+)
+
+prefix_rule(
+    pattern = ["git", "add"],
+    decision = "prompt",
+    justification = "Staging changes must be scoped to the current harness task.",
+)
+
+prefix_rule(
+    pattern = ["git", "commit"],
+    decision = "prompt",
+    justification = "Commits require fresh verification and ownership checks.",
+)
+
+prefix_rule(
+    pattern = ["git", "push"],
+    decision = "prompt",
+    justification = "Pushing changes affects a remote repository and requires explicit intent.",
+)

package/package-source/docs/codex-harness-engineering/templates/config/rules/harness.rules

@@ -1,29 +1,29 @@
-prefix_rule(
-    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\verify.ps1"],
-    decision = "allow",
-    justification = "verify.ps1 is the project harness verification entrypoint.",
-)
-
-prefix_rule(
-    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\env-check.ps1"],
-    decision = "allow",
-    justification = "env-check.ps1 is a harness environment readiness check.",
-)
-
-prefix_rule(
-    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\codex-loop.ps1"],
-    decision = "prompt",
-    justification = "codex-loop.ps1 may edit files, update task state, write traces, and commit.",
-)
-
-prefix_rule(
-    pattern = ["pwsh", "-NoProfile", "-Command"],
-    decision = "prompt",
-    justification = "Inline PowerShell can hide arbitrary operations; require review unless a narrower rule matches first.",
-)
-
-prefix_rule(
-    pattern = ["powershell", "-NoProfile", "-Command"],
-    decision = "prompt",
-    justification = "Inline PowerShell can hide arbitrary operations; require review unless a narrower rule matches first.",
-)
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\verify.ps1"],
+    decision = "allow",
+    justification = "verify.ps1 is the project harness verification entrypoint.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\env-check.ps1"],
+    decision = "allow",
+    justification = "env-check.ps1 is a harness environment readiness check.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", ".\\codex-loop.ps1"],
+    decision = "prompt",
+    justification = "codex-loop.ps1 may edit files, update task state, write traces, and commit.",
+)
+
+prefix_rule(
+    pattern = ["pwsh", "-NoProfile", "-Command"],
+    decision = "prompt",
+    justification = "Inline PowerShell can hide arbitrary operations; require review unless a narrower rule matches first.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-Command"],
+    decision = "prompt",
+    justification = "Inline PowerShell can hide arbitrary operations; require review unless a narrower rule matches first.",
+)

package/package-source/docs/codex-harness-engineering/templates/config/rules/safety.rules

@@ -1,35 +1,35 @@
-prefix_rule(
-    pattern = ["git", "reset", "--hard"],
-    decision = "forbidden",
-    justification = "Never discard user or agent work without explicit human direction outside automation.",
-)
-
-prefix_rule(
-    pattern = ["git", "checkout", "--"],
-    decision = "forbidden",
-    justification = "Destructive checkout can overwrite user work and is not allowed in harness automation.",
-)
-
-prefix_rule(
-    pattern = ["git", "clean"],
-    decision = "forbidden",
-    justification = "Git clean can delete untracked user files and generated evidence.",
-)
-
-prefix_rule(
-    pattern = ["rm", "-rf"],
-    decision = "forbidden",
-    justification = "Recursive deletion is not allowed from agent automation.",
-)
-
-prefix_rule(
-    pattern = ["Remove-Item", "-Recurse"],
-    decision = "forbidden",
-    justification = "Recursive deletion must not run from broad agent automation.",
-)
-
-prefix_rule(
-    pattern = ["powershell", "-NoProfile", "-Command", "Remove-Item"],
-    decision = "prompt",
-    justification = "PowerShell deletion must be reviewed because inline commands can be broad or destructive.",
-)
+prefix_rule(
+    pattern = ["git", "reset", "--hard"],
+    decision = "forbidden",
+    justification = "Never discard user or agent work without explicit human direction outside automation.",
+)
+
+prefix_rule(
+    pattern = ["git", "checkout", "--"],
+    decision = "forbidden",
+    justification = "Destructive checkout can overwrite user work and is not allowed in harness automation.",
+)
+
+prefix_rule(
+    pattern = ["git", "clean"],
+    decision = "forbidden",
+    justification = "Git clean can delete untracked user files and generated evidence.",
+)
+
+prefix_rule(
+    pattern = ["rm", "-rf"],
+    decision = "forbidden",
+    justification = "Recursive deletion is not allowed from agent automation.",
+)
+
+prefix_rule(
+    pattern = ["Remove-Item", "-Recurse"],
+    decision = "forbidden",
+    justification = "Recursive deletion must not run from broad agent automation.",
+)
+
+prefix_rule(
+    pattern = ["powershell", "-NoProfile", "-Command", "Remove-Item"],
+    decision = "prompt",
+    justification = "PowerShell deletion must be reviewed because inline commands can be broad or destructive.",
+)

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

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+## 目录作用
+
+- 存放项目导航层和当前任务 / 计划上下文模板，对应安装后项目的 `docs/ai/*`。
+
+## 结构索引
+
+- `repo-map.md`：代码地图和规则索引。
+- `architecture-brief.md`：架构摘要。
+- `CURRENT_TASK.md`：当前任务最小事实。
+- `PROJECT_CONTEXT.md` / `DECISIONS.md` / `KNOWN_ISSUES.md`：扩展上下文。
+- `API_MAP.md` / `DB_SCHEMA.md`：接口与数据面索引。
+- `dev-plan.md` / `feature-pack.md`：计划和跨会话语义包。
+
+## 修改规则
+
+- 保持“短事实、可导航、可续跑”，不要把长篇 PRD 或实现细节堆进 context 模板。
+- 与 `docs/`、`product/`、`spec/`、`testing/` 的 truth source 分工必须清楚。

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

@@ -0,0 +1,18 @@
+# API_MAP
+
+记录当前项目的接口面。没有真实业务 API 时，也可以先记录命令入口、路由入口、合同文件和 SDK/client 生成位置。
+
+## 建议结构
+
+| 接口 | 位置 | 作用 | 上游 | 下游 |
+| --- | --- | --- | --- | --- |
+
+## 建议补充
+
+- 认证方式
+- 错误模型
+- contract 位置
+- mock / prism / SDK 生成位置
+- 统一请求入口（例如 `apiClient` / generated client）
+- 分页字段约定（例如 `page/pageSize`）
+- 统一响应包装（例如 `code/message/data`）

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

@@ -0,0 +1,11 @@
+# CHANGELOG_AI
+
+记录会影响 agent 阅读顺序、导航方式、安装输出面或治理规则的摘要变更。
+
+## 建议结构
+
+### YYYY-MM-DD
+
+- 变更:
+- 影响面:
+- 相关真相源:

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

@@ -0,0 +1,114 @@
+# CURRENT_TASK
+
+记录当前任务的最小必要事实，不要把完整 PRD 或长篇讨论直接堆进这里。
+
+## 建议填写项
+
+- 任务目标:
+- 任务性质（bugfix / feature / refactor / chore）:
+- 验收标准:
+- 当前阶段:
+- owned paths:
+- 这个功能属于哪个模块:
+- 项目里有没有类似实现:
+- 类似页面:
+- 类似接口:
+- 类似组件:
+- 类似状态管理:
+- 当前状态分层决策（URL / remote cache / global store / local state / form）:
+- 哪些状态禁止重复存放:
+- 缓存失效或刷新规则:
+- 设计系统 / token 约束:
+- 移动端安全区 / 键盘遮挡处理:
+- 表单校验与提交流程策略:
+- Controller / Handler 边界:
+- Service 边界:
+- Repository / DAO 边界:
+- 事务 / 幂等策略:
+- 异常处理与错误码策略:
+- 权限校验边界（角色 / 资源 / 本人 / 租户）:
+- 输入校验边界（类型 / 长度 / 枚举 / 金额 / 日期 / 文件）:
+- 敏感信息脱敏策略（响应 / 日志 / trace / 审计）:
+- 风控 / 限流策略:
+- 类似测试:
+- 本轮 development_validation:
+- 本轮 acceptance_validation:
+- 未运行测试 / 豁免及原因:
+- 假测试风险提示:
+- 复用决定:
+- 不复用理由:
+- 如果修改公共组件，组件名称:
+- 如果修改公共组件，受影响页面 / 模块:
+- 如果修改公共组件，props 兼容性影响:
+- 如果修改公共组件，样式 / 交互回归风险:
+- 如果修改公共组件，需要补哪些组件测试 / E2E:
+- 是否新增目录:
+- 新目录名称:
+- 为什么现有目录不能放:
+- 新目录未来会放什么:
+- 是否符合当前目录结构:
+- 是否需要补子目录 `AGENTS.md`:
+- 需要改哪些文件:
+- 本任务涉及的业务名词统一叫法:
+- 禁止混用的同义词:
+- 新增 / 修改文件命名模式:
+- 新增函数 / hook / handler 命名约定:
+- 新增类型命名边界（Entity / DTO / Response / FormValues / ViewModel 等）:
+- 行为不变约束（接口 / 用户路径 / 数据结构 / 兼容逻辑）:
+- 允许清理的死代码 / 临时代码:
+- 不允许删除的兼容逻辑 / 历史入口:
+- 可能影响哪些调用方:
+- 直接影响:
+- 间接影响:
+- 相关接口 / 契约:
+- 相关页面 / 路由:
+- 回归范围:
+- 前端性能预算:
+- 后端性能策略（索引 / 缓存 / 分页 / N+1）:
+- 弱网 / 离线 / 大数据量策略:
+- 日志 / trace 字段要求:
+- 观测指标 / 告警策略:
+- 需要跑哪些测试:
+- 风险点:
+- 依赖的真相源:
+- 关键验证命令:
+- 必需环境变量 / Secret:
+- 受影响配置文件（.env / package.json / Dockerfile / CI / nginx / k8s / config）:
+- 构建 / 部署影响:
+- 回滚配置策略:
+- 需要同步更新的文档:
+- schema / migration 是否变更:
+- migration 文件 / 目录:
+- 历史数据兼容 / 回填策略:
+- 第三方服务 / SDK 依赖:
+- 第三方回调 / Webhook / 验签策略:
+- 凭据 / Secret 注入位置:
+- 上传约束（大小 / 类型 / 扫描 / 权限 / CDN）:
+- 平台差异（iOS / Android / H5 / 小程序）:
+- 权限申请与拒绝回退:
+- 生命周期 / 中断恢复策略:
+- 设备 / 系统版本验证矩阵:
+- 交付验收报告路径:
+- 逐条需求完成情况:
+- 本轮已完成内容:
+- 本轮未完成内容 / 剩余问题:
+- 本轮修改文件:
+- 为什么这样改 / 关键决策:
+- 已通过测试与证据:
+- 未运行测试与原因:
+- 下一个 Agent 建议起点:
+- 本轮避免并行修改的文件 / 目录:
+- 暂时不要动的区域:
+- 当前入口文件 / 页面 / 命令:
+- 相关类型 / 契约入口:
+- 相关配置 / 环境变量入口:
+
+## 使用规则
+
+- 新任务开始时更新。
+- 任务切换时清空旧事实。
+- 长会话续跑前先确认这里是否仍与当前任务一致。
+- 每轮会话结束前至少刷新“已完成内容 / 未完成内容 / 修改文件 / 测试结果 / 下一步”。
+- 下一个 Agent 续跑前先核对这里记录的修改文件、未跑测试和禁止并行修改路径。
+- 多 Agent 协作时，用这里声明文件边界；不要让多个 Agent 同时写同一组文件。
+- 可复用经验进入 `docs/knowledge/*`，不要长期堆在这里。

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

@@ -0,0 +1,14 @@
+# DB_SCHEMA
+
+记录当前项目的重要数据结构。没有数据库时，也可以先记录关键 JSON、状态文件、缓存结构或 trace 结构。
+
+## 建议结构
+
+| 实体 / 文件 | 位置 | 关键字段 | 约束 | 风险 |
+| --- | --- | --- | --- | --- |
+
+## 建议补充
+
+- 主外键或关联关系
+- 状态字段
+- 高风险一致性约束

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

@@ -0,0 +1,12 @@
+# DECISIONS
+
+用于记录项目级决策摘要。长期稳定、可复用且需要成熟度管理的决策，建议同步沉淀到 `docs/knowledge/decisions/*`。
+
+## 建议结构
+
+### D-001 标题
+
+- 结论:
+- 原因:
+- 影响:
+- 相关真相源:

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

@@ -0,0 +1,12 @@
+# KNOWN_ISSUES
+
+记录值得优先提醒 agent 的已知问题、高风险区域和容易误判的边界。
+
+## 建议结构
+
+### K-001 标题
+
+- 风险:
+- 触发条件:
+- 规避方式:
+- 相关真相源:

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

@@ -0,0 +1,14 @@
+# PROJECT_CONTEXT
+
+用一句话说明目标项目是什么，再补充系统边界、核心业务域和默认协作口径。
+
+## 建议结构
+
+- 项目定位:
+- 主要用户:
+- 核心业务域:
+- 系统边界:
+- 不负责的范围:
+- 关键目录:
+- 默认运行链路:
+- 关键真相源:

package/package-source/docs/codex-harness-engineering/templates/context/architecture-brief.md

@@ -1,58 +1,58 @@
-# Architecture Brief
-
-## 1. 系统概览
-
-- 系统边界: 本仓库维护 Codex Harness 安装包和当前仓库运行时，不承载具体业务应用。
-- 核心服务: `tools/harness/codex-loop.ps1` driver、`tools/install/bootstrap-codex-harness.ps1` 安装初始化、`refresh-agent-package.ps1` 包同步、`.codex/prompts/*` 执行提示、`.agents/skills/*` 可复用技能。
-- 主要数据流: `task.json` -> driver -> `codex exec` -> 验证命令 -> `progress.txt` / trace -> Git commit。
-
-## 2. 分层职责
-
-| 层 | 职责 | 主要目录 |
-| --- | --- | --- |
-| Runtime 层 | 任务选择、执行、验证、trace、提交 | `tools/harness/codex-loop.ps1`, `task.json`, `.codex/` |
-| Package 层 | 当前仓库包根与可分发 package-assets | repo root |
-| Template 层 | 新项目 bootstrap 模板 | `docs/codex-harness-engineering/templates/` |
-| Knowledge 层 | 深文档、规则治理、测试真相源、知识沉淀 | `docs/harness/`, `docs/testing/`, `docs/knowledge/` |
-| Skill 层 | 可复用流程和专用能力 | `.agents/skills/`, `docs/codex-harness-engineering/templates/package-assets/skills/` |
-
-## 3. 真相源
-
-- 产品真相源: `docs/requirement-prep-kit/` 或任务声明。
-- 设计真相源: `docs/codex-harness-engineering/templates/design/`。
-- Contract 真相源: `docs/codex-harness-engineering/templates/contracts/`。
-- 类型真相源: PowerShell scripts、JSON schema、task template。
-- 测试真相源: `docs/testing/*`。
-
-## 4. 关键模块
-
-| 模块 | 责任 | 上游 | 下游 | 风险 |
-| --- | --- | --- | --- | --- |
-| `tools/harness/codex-loop.ps1` | driver-first 自动执行 | `task.json`, `.codex/prompts/*` | trace、progress、commit | 状态伪造、验证缺失 |
-| `tools/install/bootstrap-codex-harness.ps1` | 初始化目标项目 runtime/docs/config | templates | 目标项目根目录 | 漏装关键 truth source |
-| `refresh-agent-package.ps1` | 刷新当前仓库 package 面和 manifest | root truth source | templates / ai-sync | 镜像漂移 |
-| `.agents/skills/` | 活跃技能 canonical | skill authors | `docs/codex-harness-engineering/templates/package-assets/skills`, package-assets | 只改一处导致分发缺失 |
-| `docs/codex-harness-engineering/` | 安装包方法论和模板 | root docs / package docs | package-assets docs | 文档和安装行为不一致 |
-
-## 5. 关键约束
-
-- 修改安装行为时，先改 root runtime 或模板 canonical，再同步 `.agents/`、templates 和 package-assets。
-- 修改 skills 时，以 `.agents/skills/<name>` 为 canonical。
-- 修改 active role rules 时，以 `.codex/rules/agents.md` 为 canonical。
-- 文档改动至少运行 `git diff --check`；脚本改动还要做 PowerShell parser 检查。
-
-## 6. 高风险区域
-
-- `task.json` 状态写回。
-- Git dirty workspace 检查。
-- package mirrors 和 manifest / lock。
-- hooks 与 driver 职责边界。
-- 外部 MCP、token、cookie、私钥、密码。
-
-## 7. 建议阅读顺序
-
-1. `AGENTS.md`
-2. `docs/ai/repo-map.md`
-3. `docs/harness/architecture.md`
-4. `docs/harness/rule-governance.md`
-5. `docs/codex-harness-engineering/README.md`
+# Architecture Brief
+
+## 1. 系统概览
+
+- 系统边界: 本仓库维护 Codex Harness 安装包和当前仓库运行时，不承载具体业务应用。
+- 核心服务: `tools/harness/codex-loop.ps1` driver、`tools/install/bootstrap-codex-harness.ps1` 安装初始化、`refresh-agent-package.ps1` 包同步、`.codex/prompts/*` 执行提示、`.agents/skills/*` 可复用技能。
+- 主要数据流: `task.json` -> driver -> `codex exec` -> 验证命令 -> `progress.txt` / trace -> Git commit。
+
+## 2. 分层职责
+
+| 层 | 职责 | 主要目录 |
+| --- | --- | --- |
+| Runtime 层 | 任务选择、执行、验证、trace、提交 | `tools/harness/codex-loop.ps1`, `task.json`, `.codex/` |
+| Package 层 | 当前仓库包根与可分发 package-assets | repo root |
+| Template 层 | 新项目 bootstrap 模板 | `docs/codex-harness-engineering/templates/` |
+| Knowledge 层 | 深文档、规则治理、测试真相源、知识沉淀 | `docs/harness/`, `docs/testing/`, `docs/knowledge/` |
+| Skill 层 | 可复用流程和专用能力 | `.agents/skills/`, `docs/codex-harness-engineering/templates/package-assets/skills/` |
+
+## 3. 真相源
+
+- 产品真相源: `docs/requirement-prep-kit/` 或任务声明。
+- 设计真相源: `docs/codex-harness-engineering/templates/design/`。
+- Contract 真相源: `docs/codex-harness-engineering/templates/contracts/`。
+- 类型真相源: PowerShell scripts、JSON schema、task template。
+- 测试真相源: `docs/testing/*`。
+
+## 4. 关键模块
+
+| 模块 | 责任 | 上游 | 下游 | 风险 |
+| --- | --- | --- | --- | --- |
+| `tools/harness/codex-loop.ps1` | driver-first 自动执行 | `task.json`, `.codex/prompts/*` | trace、progress、commit | 状态伪造、验证缺失 |
+| `tools/install/bootstrap-codex-harness.ps1` | 初始化目标项目 runtime/docs/config | templates | 目标项目根目录 | 漏装关键 truth source |
+| `refresh-agent-package.ps1` | 刷新当前仓库 package 面和 manifest | root truth source | templates / ai-sync | 镜像漂移 |
+| `.agents/skills/` | 活跃技能 canonical | skill authors | `docs/codex-harness-engineering/templates/package-assets/skills`, package-assets | 只改一处导致分发缺失 |
+| `docs/codex-harness-engineering/` | 安装包方法论和模板 | root docs / package docs | package-assets docs | 文档和安装行为不一致 |
+
+## 5. 关键约束
+
+- 修改安装行为时，先改 root runtime 或模板 canonical，再同步 `.agents/`、templates 和 package-assets。
+- 修改 skills 时，以 `.agents/skills/<name>` 为 canonical。
+- 修改 active role rules 时，以 `.codex/rules/agents.md` 为 canonical。
+- 文档改动至少运行 `git diff --check`；脚本改动还要做 PowerShell parser 检查。
+
+## 6. 高风险区域
+
+- `task.json` 状态写回。
+- Git dirty workspace 检查。
+- package mirrors 和 manifest / lock。
+- hooks 与 driver 职责边界。
+- 外部 MCP、token、cookie、私钥、密码。
+
+## 7. 建议阅读顺序
+
+1. `AGENTS.md`
+2. `docs/ai/repo-map.md`
+3. `docs/harness/architecture.md`
+4. `docs/harness/rule-governance.md`
+5. `docs/codex-harness-engineering/README.md`