@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/docs/governance-auto-repair.md

@@ -1,80 +1,82 @@
-# Governance Auto Repair
-
-本文件记录 Stop hook 治理检查在会话结束时发现的 Harness 漂移、失败 trace 和可复用修复经验。它是自动化经验暂存区，不是硬规则入口。
-
-## 写入来源
-
-Stop hook 会调用：
-
-```powershell
-scripts/harness/harness-governance-check.ps1 -WriteExperience
-```
-
-该脚本只做两类写入：
-
-- 为新的 failed trace 追加一条去重后的 `Stop Hook Experience`。
-- 创建本文件的基础结构。
-
-它不会直接改 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或 task queue。
-
-## 经验提升规则
-
-每条自动记录的经验都必须经过复验后再提升：
-
-| 情况 | 提升目标 |
-| --- | --- |
-| 重复出现的规则分层、fallback、autoload、hook 漂移 | `docs/harness/rule-governance.md` 或 `.codex/rules/*.md` |
-| 命令权限、危险操作、sandbox 误用 | `.codex/rules/*.rules` 或 `docs/harness/sandbox-policy.md` |
-| Stage 1 产品/设计/计划不一致 | 对应 product/design/plan truth source |
-| Stage 2 代码质量、测试缺口、回归风险 | `docs/testing/failure-triage.md` 或测试矩阵 |
-| driver、trace、progress、commit gate 闭环缺口 | `docs/harness/task-session-strategy.md` 或 `trace-format.md` |
-
-## 失败经验分类
-
-Stop hook 写入 failed trace 摘要时，应尽量归入下面的分类，方便后续判断是补 truth source、补 hook、补子代理边界，还是只保留为一次性 trace。
-
-| 分类 | 典型信号 | 优先处理 |
-| --- | --- | --- |
-| `semantic_constraint_lost` | 字段口径、单位、禁止修改范围、兼容性约束只出现在聊天里，后续实现忘记 | 补 product/context/testing truth source 或 task 语义约束包 |
-| `truth_source_missing` | task 声明了需求、架构、测试或数据证据，但对应文件不存在或内容不足 | BLOCKED，先补 truth source |
-| `hook_gap` | 问题可被确定性检查发现，但当前 hook / `.rules` / verify 没拦住 | 补 hook、`.rules` 或 `tools/harness/verify.ps1` 检查 |
-| `subagent_context_overflow` | 主会话读取了大量日志、依赖树、数据样本、完整 Skill 流程，导致上下文污染 | 改为子代理读取并只返回摘要 |
-| `state_file_bloat` | `task.json` / `progress.txt` 过大、格式漂移或被 AI 手工整理 | 交给 `runtime.state_compaction` 或治理修复，不允许手工重排 |
-| `review_gate_gap` | Stage 1 / Stage 2 未覆盖的产品、设计、测试可信度或维护性问题 | 补 review prompt、测试矩阵或 qa contract |
-| `domain_rule_candidate` | 多次出现同类领域规范违规，但还不是通用项目硬规则 | 先沉淀到 domain docs / skill，再决定是否提升 |
-| `service_topology_gap` | 跨服务、契约、IDL、schema、上下游或外部系统影响面靠 AI 搜索和猜测 | 补 `.service-matrix/dependencies.yaml` 或等价拓扑 truth source |
-
-提升前必须回答：
-
-- 这是一次性任务问题，还是会跨任务重复？
-- 能否用 deterministic check 发现？
-- 是否需要进入 instruction chain，还是应下沉到 docs / skill / hook / `.rules`？
-- 是否有复验证据证明修复后不再复现？
-
-## 修复流程
-
-1. Stop hook 发现治理失败或 failed trace。
-2. `harness-governance-check.ps1` 输出 JSON findings，并把 failed trace 摘要写入本文件。
-3. Stop hook 返回 continuation JSON，阻断停止。
-4. 下一轮先读 `AGENTS.md`、本文件、`docs/harness/rule-governance.md`、`.codex/rules/agents.md`。
-5. 由 `harness-writer` 或 driver 修复对应路径。
-6. 运行 `tools/harness/verify.ps1` 和直接相关验证。
-7. 只有复验成立且可复用时，才把经验提升到对应正式文档。
-
-## Self-Refinement 提升路径
-
-Stop hook、review、用户纠正或 failed trace 发现的问题，不应只停留在本轮对话。按下面路径处理：
-
-| 信号 | 首选落点 | 何时升级 |
-| --- | --- | --- |
-| 一次性任务事实 | 当前 trace、`progress.txt`、任务相关 product / testing 文档 | 不升级 |
-| 可复用项目经验 | `docs/knowledge/experience/` 或 `docs/knowledge/guidelines/` | 复验后进入 `ARCHIVE-001` |
-| 反复出现的领域口径 | domain docs、service matrix、project skill | 多次任务引用且有证据 |
-| 可机械化检查 | hook、`.rules`、`tools/harness/verify.ps1`、CI、lint、contract test | 已有确定性失败样本和通过样本 |
-| 每次会话都必须遵守的硬规则 | `AGENTS.md` 或子目录 `AGENTS.md` | proven 级别或 maintainer 明确要求 |
-
-提升前必须保留原始证据路径、复验命令和失败样本。不能把单次用户偏好、一次性修复或未复验猜测直接提升为全局规则。
-
-## 自动记录区
-
-新的 Stop hook 经验会追加在此节之后。
+# Governance Auto Repair
+
+本文件记录 Stop hook 治理检查在会话结束时发现的 Harness 漂移、失败 trace 和可复用修复经验。它是自动化经验暂存区，不是硬规则入口。
+
+## 写入来源
+
+Stop hook 会调用：
+
+```powershell
+scripts/harness/harness-governance-check.ps1 -WriteExperience
+```
+
+该脚本只做两类写入：
+
+- 为新的 failed trace 追加一条去重后的 `Stop Hook Experience`。
+- 创建本文件的基础结构。
+- 对受影响目录的子 `AGENTS.md` 刷新自动维护区块，补齐 changed paths、候选入口和验证命令。
+
+它不会直接改 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或 task queue。
+它也不会重写整份子 `AGENTS.md`；自动化只维护受控区块，手写目录规则必须放在区块外。
+
+## 经验提升规则
+
+每条自动记录的经验都必须经过复验后再提升：
+
+| 情况 | 提升目标 |
+| --- | --- |
+| 重复出现的规则分层、fallback、autoload、hook 漂移 | `docs/harness/rule-governance.md` 或 `.codex/rules/*.md` |
+| 命令权限、危险操作、sandbox 误用 | `.codex/rules/*.rules` 或 `docs/harness/sandbox-policy.md` |
+| Stage 1 产品/设计/计划不一致 | 对应 product/design/plan truth source |
+| Stage 2 代码质量、测试缺口、回归风险 | `docs/testing/failure-triage.md` 或测试矩阵 |
+| driver、trace、progress、commit gate 闭环缺口 | `docs/harness/task-session-strategy.md` 或 `trace-format.md` |
+
+## 失败经验分类
+
+Stop hook 写入 failed trace 摘要时，应尽量归入下面的分类，方便后续判断是补 truth source、补 hook、补子代理边界，还是只保留为一次性 trace。
+
+| 分类 | 典型信号 | 优先处理 |
+| --- | --- | --- |
+| `semantic_constraint_lost` | 字段口径、单位、禁止修改范围、兼容性约束只出现在聊天里，后续实现忘记 | 补 product/context/testing truth source 或 task 语义约束包 |
+| `truth_source_missing` | task 声明了需求、架构、测试或数据证据，但对应文件不存在或内容不足 | BLOCKED，先补 truth source |
+| `hook_gap` | 问题可被确定性检查发现，但当前 hook / `.rules` / verify 没拦住 | 补 hook、`.rules` 或 `tools/harness/verify.ps1` 检查 |
+| `subagent_context_overflow` | 主会话读取了大量日志、依赖树、数据样本、完整 Skill 流程，导致上下文污染 | 改为子代理读取并只返回摘要 |
+| `state_file_bloat` | `task.json` / `progress.txt` 过大、格式漂移或被 AI 手工整理 | 交给 `runtime.state_compaction` 或治理修复，不允许手工重排 |
+| `review_gate_gap` | Stage 1 / Stage 2 未覆盖的产品、设计、测试可信度或维护性问题 | 补 review prompt、测试矩阵或 qa contract |
+| `domain_rule_candidate` | 多次出现同类领域规范违规，但还不是通用项目硬规则 | 先沉淀到 domain docs / skill，再决定是否提升 |
+| `service_topology_gap` | 跨服务、契约、IDL、schema、上下游或外部系统影响面靠 AI 搜索和猜测 | 补 `.service-matrix/dependencies.yaml` 或等价拓扑 truth source |
+
+提升前必须回答：
+
+- 这是一次性任务问题，还是会跨任务重复？
+- 能否用 deterministic check 发现？
+- 是否需要进入 instruction chain，还是应下沉到 docs / skill / hook / `.rules`？
+- 是否有复验证据证明修复后不再复现？
+
+## 修复流程
+
+1. Stop hook 发现治理失败或 failed trace。
+2. `harness-governance-check.ps1` 输出 JSON findings，并把 failed trace 摘要写入本文件。
+3. Stop hook 返回 continuation JSON，阻断停止。
+4. 下一轮先读 `AGENTS.md`、本文件、`docs/harness/rule-governance.md`、`.codex/rules/agents.md`。
+5. 由 `harness-writer` 或 driver 修复对应路径。
+6. 运行 `tools/harness/verify.ps1` 和直接相关验证。
+7. 只有复验成立且可复用时，才把经验提升到对应正式文档。
+
+## Self-Refinement 提升路径
+
+Stop hook、review、用户纠正或 failed trace 发现的问题，不应只停留在本轮对话。按下面路径处理：
+
+| 信号 | 首选落点 | 何时升级 |
+| --- | --- | --- |
+| 一次性任务事实 | 当前 trace、`progress.txt`、任务相关 product / testing 文档 | 不升级 |
+| 可复用项目经验 | `docs/knowledge/experience/` 或 `docs/knowledge/guidelines/` | 复验后进入 `ARCHIVE-001` |
+| 反复出现的领域口径 | domain docs、service matrix、project skill | 多次任务引用且有证据 |
+| 可机械化检查 | hook、`.rules`、`tools/harness/verify.ps1`、CI、lint、contract test | 已有确定性失败样本和通过样本 |
+| 每次会话都必须遵守的硬规则 | `AGENTS.md` 或子目录 `AGENTS.md` | proven 级别或 maintainer 明确要求 |
+
+提升前必须保留原始证据路径、复验命令和失败样本。不能把单次用户偏好、一次性修复或未复验猜测直接提升为全局规则。
+
+## 自动记录区
+
+新的 Stop hook 经验会追加在此节之后。

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

@@ -1,78 +1,78 @@
-# Harness 架构
-
-## 目标
-
-Harness 的目标是把 Codex 的执行过程固定成可重复、可验证、可追踪、可沉淀知识的工程闭环。
-
-## 核心链路
-
-```text
-task.json
-  -> tools/harness/codex-loop.ps1
-  -> codex exec
-  -> verify / lint / build / test
-  -> progress.txt + traces/*.json
-  -> docs/knowledge/ 引用与归档
-  -> task.json passes=true
-  -> git commit
-```
-
-## 分层
-
-- 规则层：`AGENTS.md`
-- 任务层：`task.json`
-- 执行层：`tools/harness/codex-loop.ps1`
-- 配置层：`.codex/task-run-profile.json`
-- 证据层：`progress.txt`、`traces/`
-- 验证层：`tools/harness/verify.ps1` 与任务内 `test_command`
-- 知识层：`docs/knowledge/knowledge-catalog.md`、分类索引和知识条目
-- 治理层：`docs/harness/rule-governance.md`、`docs/harness/knowledge-architecture.md`、`docs/harness/knowledge-import.md`、`docs/harness/knowledge-lint.md`、`docs/harness/team-knowledge-sync.md`
-- 拓扑层：`.service-matrix/dependencies.yaml` 与 `docs/harness/service-dependency-matrix.md`，仅在多服务、多仓库、契约或外部系统项目启用。
-
-## 原则
-
-- 任何完成声明都必须有验证证据。
-- 任何任务推进都必须回到可验证的 `task.json`、`progress.txt` 或 `traces/` 证据链上。
-- 任何复用过的项目经验都应在 trace 中留下 `knowledge_references`，避免知识只停留在对话上下文。
-- 任何可复用的新经验都应在归档任务中沉淀到 `docs/knowledge/`，初始成熟度默认是 `draft`。
-- 任何会影响服务拓扑、公开契约、上游 / 下游调用、IDL、schema 或外部系统的任务，都必须先能从 `.service-matrix/dependencies.yaml` 或等价 truth source 找到影响面；找不到时先 BLOCKED。
-- 既有项目接入时，知识冷启动只生成 draft 条目；成熟度提升必须来自后续引用和验证证据。
-- 知识库需要定期 lint，检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目。
-- 团队知识库是可选上层能力，只同步 verified/proven 级别的跨项目候选；外部知识库不可用时不应阻塞本地 driver。
-- `progress.txt`、`traces/` 和 Git 状态由 runtime 脚本落盘；其他需要新增或修改的仓库内容必须委派给匹配的 writer 子代理，主控会话自身不直接写文件。
-- 默认只在当前 Git 工作区内执行，不创建额外执行目录。
-
-## 任务控制面
-
-Harness 不要求所有任务都走相同重量。判断标准是影响面和复用价值：
-
-| 类型 | 适用场景 | 最小要求 |
-| --- | --- | --- |
-| 轻量任务 | 单文件、小修、验证明确、无跨模块影响 | `task.json` 中明确 scope、owned paths、test_command 和验收；允许 `gate_profile: lightweight` |
-| 标准任务 | 有真实交付、测试、文档或评审要求 | 完整 plan、truth source、qa_contract、trace 和 commit |
-| 企业级任务 | 多服务、多仓库、契约、数据迁移、权限、外部系统 | 额外启用服务依赖矩阵、契约 gate、失败/回滚验证和多维 review |
-
-轻量任务可以少写文档，但不能绕过验证、trace、owned paths 和完成证据。
-
-## 多维 Review
-
-Stage 2 默认可以由单个 reviewer 执行；当任务满足企业级任务条件时，应拆成多个只读审查维度并聚合：
-
-| 维度 | 检查重点 |
-| --- | --- |
-| 设计一致性 | 实现是否符合 spec、design、architecture truth source |
-| 复杂度 | 是否过度抽象、职责混杂、文件过大或难以维护 |
-| 并发与状态 | 锁、幂等、竞态、异步边界、前端状态源是否正确 |
-| 错误处理 | 失败路径、重试、回滚、用户反馈、日志和恢复策略 |
-| 安全 | 权限、输入、secrets、外部调用、危险命令和数据泄露 |
-| 契约一致性 | API / IDL / schema / event / generated code 是否同步 |
-| 追溯性 | Requirement ID、测试用例、证据和改动路径是否可追踪 |
-| 辅助检查 | lint、类型、格式、构建、脚本、hook 和 runtime 漂移 |
-
-多维 review 是可选强化，不是第二套状态机。所有结论仍回到当前 task 的 trace、review gate 和修复队列。
-
-## 外层控制台集成
-
-- Multica 可作为 Harness 的外层任务控制台，但 Harness 的完成状态仍以 `tools/harness/codex-loop.ps1`、`test_command`、review gate、trace 和 commit gate 为准。
-- 当前项目优先使用 Multica Docker 自部署版做集成试验；桌面版仅适合快速体验和个人使用。
-- 详细决策见 `docs/harness/multica-integration.md`。
+# Harness 架构
+
+## 目标
+
+Harness 的目标是把 Codex 的执行过程固定成可重复、可验证、可追踪、可沉淀知识的工程闭环。
+
+## 核心链路
+
+```text
+task.json
+  -> tools/harness/codex-loop.ps1
+  -> codex exec
+  -> verify / lint / build / test
+  -> progress.txt + traces/*.json
+  -> docs/knowledge/ 引用与归档
+  -> task.json passes=true
+  -> git commit
+```
+
+## 分层
+
+- 规则层：`AGENTS.md`
+- 任务层：`task.json`
+- 执行层：`tools/harness/codex-loop.ps1`
+- 配置层：`.codex/task-run-profile.json`
+- 证据层：`progress.txt`、`traces/`
+- 验证层：`tools/harness/verify.ps1` 与任务内 `test_command`
+- 知识层：`docs/knowledge/knowledge-catalog.md`、分类索引和知识条目
+- 治理层：`docs/harness/rule-governance.md`、`docs/harness/knowledge-architecture.md`、`docs/harness/knowledge-import.md`、`docs/harness/knowledge-lint.md`、`docs/harness/team-knowledge-sync.md`
+- 拓扑层：`.service-matrix/dependencies.yaml` 与 `docs/harness/service-dependency-matrix.md`，仅在多服务、多仓库、契约或外部系统项目启用。
+
+## 原则
+
+- 任何完成声明都必须有验证证据。
+- 任何任务推进都必须回到可验证的 `task.json`、`progress.txt` 或 `traces/` 证据链上。
+- 任何复用过的项目经验都应在 trace 中留下 `knowledge_references`，避免知识只停留在对话上下文。
+- 任何可复用的新经验都应在归档任务中沉淀到 `docs/knowledge/`，初始成熟度默认是 `draft`。
+- 任何会影响服务拓扑、公开契约、上游 / 下游调用、IDL、schema 或外部系统的任务，都必须先能从 `.service-matrix/dependencies.yaml` 或等价 truth source 找到影响面；找不到时先 BLOCKED。
+- 既有项目接入时，知识冷启动只生成 draft 条目；成熟度提升必须来自后续引用和验证证据。
+- 知识库需要定期 lint，检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目。
+- 团队知识库是可选上层能力，只同步 verified/proven 级别的跨项目候选；外部知识库不可用时不应阻塞本地 driver。
+- `progress.txt`、`traces/` 和 Git 状态由 runtime 脚本落盘；其他需要新增或修改的仓库内容必须委派给匹配的 writer 子代理，主控会话自身不直接写文件。
+- 默认只在当前 Git 工作区内执行，不创建额外执行目录。
+
+## 任务控制面
+
+Harness 不要求所有任务都走相同重量。判断标准是影响面和复用价值：
+
+| 类型 | 适用场景 | 最小要求 |
+| --- | --- | --- |
+| 轻量任务 | 单文件、小修、验证明确、无跨模块影响 | `task.json` 中明确 scope、owned paths、test_command 和验收；允许 `gate_profile: lightweight` |
+| 标准任务 | 有真实交付、测试、文档或评审要求 | 完整 plan、truth source、qa_contract、trace 和 commit |
+| 企业级任务 | 多服务、多仓库、契约、数据迁移、权限、外部系统 | 额外启用服务依赖矩阵、契约 gate、失败/回滚验证和多维 review |
+
+轻量任务可以少写文档，但不能绕过验证、trace、owned paths 和完成证据。
+
+## 多维 Review
+
+Stage 2 默认可以由单个 reviewer 执行；当任务满足企业级任务条件时，应拆成多个只读审查维度并聚合：
+
+| 维度 | 检查重点 |
+| --- | --- |
+| 设计一致性 | 实现是否符合 spec、design、architecture truth source |
+| 复杂度 | 是否过度抽象、职责混杂、文件过大或难以维护 |
+| 并发与状态 | 锁、幂等、竞态、异步边界、前端状态源是否正确 |
+| 错误处理 | 失败路径、重试、回滚、用户反馈、日志和恢复策略 |
+| 安全 | 权限、输入、secrets、外部调用、危险命令和数据泄露 |
+| 契约一致性 | API / IDL / schema / event / generated code 是否同步 |
+| 追溯性 | Requirement ID、测试用例、证据和改动路径是否可追踪 |
+| 辅助检查 | lint、类型、格式、构建、脚本、hook 和 runtime 漂移 |
+
+多维 review 是可选强化，不是第二套状态机。所有结论仍回到当前 task 的 trace、review gate 和修复队列。
+
+## 外层控制台集成
+
+- Multica 可作为 Harness 的外层任务控制台，但 Harness 的完成状态仍以 `tools/harness/codex-loop.ps1`、`test_command`、review gate、trace 和 commit gate 为准。
+- 当前项目优先使用 Multica Docker 自部署版做集成试验；桌面版仅适合快速体验和个人使用。
+- 详细决策见 `docs/harness/multica-integration.md`。

package/package-source/docs/codex-harness-engineering/templates/docs/install-manifest-governance.md

@@ -19,16 +19,16 @@
 
 | 模式 | scope | 输出位置 | 用途 |
 | --- | --- | --- | --- |
-| `project` | `project` | 目标项目根、`.agents/`、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/`、`tools/` | 新默认 thin project，初始化项目 runtime、active surface 和 truth sources |
+| `project` | `project` | 目标项目根、`.agents/`、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/`、`tools/` | 新默认 thin project，初始化项目 runtime、active surface 和 truth sources |
 | `full` | `project` + `vendor` + `user` | 目标项目根、`.agents/`、用户目录 | 显式 legacy full 入口，安装完整项目 runtime 和 vendor 包 |
 | `vendor` | `vendor` | 目标项目 `.agents/` | 离线或强隔离场景复制完整包资产 |
-| `user` | `user` | `%USERPROFILE%/.codex/packages/codex-harness/` | 只安装共享 package source 和用户级 package lock，不暴露全局 active surface |
+| `user` | `user` | `%USERPROFILE%/.codex/packages/codex-harness/` | 只安装共享 package source 和用户级 package lock，不暴露全局 active surface |
 
 manifest 必须声明且只声明以上 4 个模式。`full` 是组合模式，不作为 entry 的 `scope`；entry 的 `scope` 只能是 `project`、`vendor` 或 `user`。
 
-新分层入口使用 `-Scope user|project|vendor`。`-Mode full|user|project|vendor` 继续保留为兼容入口；同一次调用不能同时传 `-Scope` 和 `-Mode`。其中 `-Scope project` 与无参数 `tools\\install/install-agent.ps1 -ProjectRoot .` 等价，都是新项目默认 thin 入口；`-Mode full` 则保留为显式 legacy full 入口。
+新分层入口使用 `-Scope user|project|vendor`。`-Mode full|user|project|vendor` 继续保留为兼容入口；同一次调用不能同时传 `-Scope` 和 `-Mode`。其中 `-Scope project` 与无参数 `tools\\install/install-agent.ps1 -ProjectRoot .` 等价，都是新项目默认 thin 入口；`-Mode full` 则保留为显式 legacy full 入口。
 
-`-Scope project` 使用 thin 输出，保留瘦的 `.agents/skills/`、`.agents/workflows/`，同时不默认复制完整 vendor 镜像、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。这些 legacy 文档包仍由旧 `-Mode project`、显式 `-Mode full` 或直接 bootstrap legacy profile 保留。
+`-Scope project` 使用 thin 输出，保留瘦的 `.agents/skills/`、`.agents/workflows/`，同时不默认复制完整 vendor 镜像、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。这些 legacy 文档包仍由旧 `-Mode project`、显式 `-Mode full` 或直接 bootstrap legacy profile 保留。
 
 `-MigratePlan` 和 `-MigrateApply` 不属于 install-manifest 的普通安装模式集合：前者只读分类，后者是确认式迁移执行入口。`-MigrateApply` 的默认行为不是写完整包，也不是默认 full 切换；它只能在 `-Confirm` 存在时，按 `-MigratePlan` 的分类结果更新 `.codex-harness/locks/package.lock.json` 和必要 `.codex-harness` 元数据。
 
@@ -128,8 +128,8 @@ doctor 对 `managedFiles` 执行只读检查：
 安装器提供升级计划和安全执行入口：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
 ```
 
 `-UpgradePlan` 只读取当前包 manifest 和目标项目 `.codex-harness/locks/package.lock.json`，不会写入、覆盖或删除文件。计划输出会按 entry 标记：
@@ -157,7 +157,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 对已安装项目升级时，先在目标项目中运行只读计划：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
 ```
 
 按计划输出处理：
@@ -171,7 +171,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 只有计划中没有 `blocked-user-drift` 时才执行：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
 ```
 
 `-Upgrade` 成功后会刷新 `.codex-harness/locks/package.lock.json`。升级后建议立即运行 `tools/harness/doctor.ps1` 验证 drift 状态。
@@ -181,8 +181,8 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 安装器提供卸载计划和保守执行入口：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
 ```
 
 `-UninstallPlan` 默认保留 `project` scope 内容，避免误删 `task.json`、`progress.txt`、`docs/spec/`、`docs/architecture/` 和项目 truth source；legacy 项目中的 `docs/testing/` 也不会由卸载命令主动清理。`vendor` scope 会标记为可删除候选，`user` scope 会标记为需要逐项人工确认。
@@ -201,7 +201,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 卸载前先运行只读计划：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
 ```
 
 计划输出中：
@@ -213,7 +213,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 确认只移除 vendor 包后执行：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
 ```
 
 如果卸载输出 `blocked-user-drift`，说明 `.agents/` 下至少一个 vendor 文件和 lock hash 不一致。此时不要强删整个 `.agents/`，应先确认这些文件是否包含本地修改；需要保留时手工迁出，需要放弃时先恢复到 lock 对应内容或重新安装后再卸载。
@@ -223,7 +223,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 旧项目从完整 `.agents/` vendor 输出迁移到 thin project 前，先运行只读迁移计划：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigratePlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigratePlan
 ```
 
 `-MigratePlan` 只输出报告，不写入 `.codex-harness/locks/package.lock.json`，不删除 `.agents/`，也不覆盖项目文档。报告会扫描 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 和 `docs/requirement-prep-kit/`，并按以下动作归类：
@@ -245,8 +245,8 @@ Phase 5 只冻结确认式迁移执行，不切换默认 `full`，也不改变 `
 实现任务 `LAYERING-P5-APPLY-001` 已将该入口落到 `tools/install/install-agent.ps1 -MigrateApply [-Confirm]`：默认 dry-run，`-Confirm` 后只把 `adopt-vendor-managed` 分类中 hash 一致的 vendor 文件写入 `.codex-harness/locks/package.lock.json`，并在 `blocked-user-drift`、`unknown-legacy-file` 或 `manual-review` 存在时返回 `status=blocked` 且不写入。
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply -Confirm
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigrateApply -Confirm
 ```
 
 `-MigrateApply` 必须遵守以下边界：
@@ -300,7 +300,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-age
 ## 验证命令
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/doctor.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/doctor.ps1
 powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\harness\test-install-modes.ps1
 powershell -NoProfile -ExecutionPolicy Bypass -File .\refresh-agent-package.ps1 -RepoRoot . -PackageRoot agent -Surface all -CheckOnly
 git diff --check