@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/implementation-flow.md

@@ -213,10 +213,11 @@ Stop hook
 `harness-governance-check.ps1` 负责检查：
 
 - `AGENTS.md`、`.codex/`、`docs/harness/`、`docs/codex-harness-engineering/` 是否有 merge marker。
-- `.codex/hooks.json` 是否引用缺失的 `tools/harness/hook-stop-verify.ps1`。
-- `.codex/rules/` 是否缺少官方 `*.rules` 执行策略。
-- `.codex/config.toml` 是否保留无实体 fallback。
-- 最新 trace 是否失败，失败原因应沉淀到哪个治理或测试文档。
+- `.codex/hooks.json` 是否引用缺失的 `tools/harness/hook-stop-verify.ps1`。
+- `.codex/rules/` 是否缺少官方 `*.rules` 执行策略。
+- `.codex/config.toml` 是否保留无实体 fallback。
+- changed paths 命中的模块目录是否需要刷新子 `AGENTS.md` 的自动维护区块。
+- 最新 trace 是否失败，失败原因应沉淀到哪个治理或测试文档。
 
 失败经验不会直接升级为硬规则。Stop hook 只把 failed trace 摘要去重写入 `docs/harness/governance-auto-repair.md`，并在 continuation JSON 中要求下一轮先读：
 
@@ -225,7 +226,8 @@ Stop hook
 - `docs/harness/rule-governance.md`
 - `.codex/rules/agents.md`
 
-后续由 `harness-writer` 或 driver 修复对应路径。只有经过复验且可复用的经验，才允许提升到 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或测试文档。
+后续由 `harness-writer` 或 driver 修复对应路径。只有经过复验且可复用的经验，才允许提升到 `AGENTS.md`、`.codex/rules/*.md`、`.codex/rules/*.rules`、prompt 或测试文档。
+对子目录 `AGENTS.md` 的自动更新只维护受控区块，不重写整份文档；手写目录规则应保留在受控区块外。
 
 ## 9. 知识闭环
 

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/implementation-guide.md

@@ -1,25 +1,25 @@
-# 实施指南
-
-## 目标
-
-把当前包接入新项目，并跑通单工作区的 driver-first 闭环。
-
-## 步骤
-
-1. 运行 `tools/install/bootstrap-codex-harness.ps1`。
-2. 提交 bootstrap 基线，确保 Git 工作区干净。
-3. 先用 `tools/harness/templates/smoke-task.json` 做首次自检，确认 driver、trace、progress 和验证入口正常。
-4. 补齐 `docs/product/`、`docs/design/`、`docs/context/dev-plan.md`。
-5. 在生成真实 `task.json` 之前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md`、`TEST_STRATEGY.md`、`TEST_DATA_MATRIX.md`、`RISK_BASED_TEST_PLAN.md`、`REGRESSION_PLAN.md`、`EVIDENCE_PROTOCOL.md`、`test-matrix.md`、`verify-matrix.md`。
-6. 用 `tools/harness/templates/project-task-template.json` 生成真实 `task.json`。
-7. 如需在 Codex app 中启用长期目标模式，确认 `.codex/config.toml` 已开启 `features.goals = true`，并先阅读 `docs/codex-harness-engineering/goal-harness-integration-guide.md` 和 `docs/codex-harness-engineering/examples/goal-templates.md`。
-8. 运行 `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`tools/harness/codex-loop.ps1 -RunUntilDone`。
-
-## 原则
-
-- 不在未提交的混合改动上启动 driver。
-- 不保留额外执行工作区和外部 worker 说明。
-- 正式任务队列建立前，先让 testing truth source 成为实现前 gate。
-- `/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook`。
-- Stage 17 只做 fresh evidence、affected tests 和回归确认，不承担第一次补测试范围。
-- 所有完成声明都必须回到 `progress.txt`、`traces/` 和验证命令。
+# 实施指南
+
+## 目标
+
+把当前包接入新项目，并跑通单工作区的 driver-first 闭环。
+
+## 步骤
+
+1. 运行 `tools/install/bootstrap-codex-harness.ps1`。
+2. 提交 bootstrap 基线，确保 Git 工作区干净。
+3. 先用 `tools/harness/templates/smoke-task.json` 做首次自检，确认 driver、trace、progress 和验证入口正常。
+4. 补齐 `docs/product/`、`docs/design/`、`docs/context/dev-plan.md`。
+5. 在生成真实 `task.json` 之前，先补齐 `docs/testing/ACCEPTANCE_CRITERIA.md`、`ACCEPTANCE_EXAMPLES.md`、`TRACEABILITY_MATRIX.md`、`TEST_STRATEGY.md`、`TEST_DATA_MATRIX.md`、`RISK_BASED_TEST_PLAN.md`、`REGRESSION_PLAN.md`、`EVIDENCE_PROTOCOL.md`、`test-matrix.md`、`verify-matrix.md`。
+6. 用 `tools/harness/templates/project-task-template.json` 生成真实 `task.json`。
+7. 如需在 Codex app 中启用长期目标模式，确认 `.codex/config.toml` 已开启 `features.goals = true`，并先阅读 `docs/codex-harness-engineering/goal-harness-integration-guide.md` 和 `docs/codex-harness-engineering/examples/goal-templates.md`。
+8. 运行 `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`tools/harness/codex-loop.ps1 -RunUntilDone`。
+
+## 原则
+
+- 不在未提交的混合改动上启动 driver。
+- 不保留额外执行工作区和外部 worker 说明。
+- 正式任务队列建立前，先让 testing truth source 成为实现前 gate。
+- `/goal` 只作为外层长期目标控制面，不替代 `task.json + codex-loop.ps1 + stop hook`。
+- Stage 17 只做 fresh evidence、affected tests 和回归确认，不承担第一次补测试范围。
+- 所有完成声明都必须回到 `progress.txt`、`traces/` 和验证命令。

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/knowledge-surface-map.md

@@ -0,0 +1,186 @@
+# Harness 知识面分层图
+
+本文把当前 Harness 工程里和“知识、上下文、检索、自动加载”相关的文件面一次拆清，回答四个问题：
+
+- 什么会直接进入 Codex 上下文。
+- 什么只是运行配置，不应误判为知识真相源。
+- 什么属于项目内知识，应提交到仓库。
+- 什么属于外部或个人知识，只应查询，不应直接升级为项目规则。
+
+## 1. 总图
+
+```text
+用户个人知识 / 本地 KB / Obsidian / 外部文档
+  -> 通过 MCP / 本地检索 / 代码语义工具按需查询
+
+Codex 宿主自动加载面
+  -> AGENTS 链
+  -> developer/system instructions
+  -> 被触发的 Skills
+  -> hooks additionalContext
+  -> IDE / 工具采集上下文
+
+项目导航层 docs/ai/
+  -> repo-map
+  -> architecture-brief
+  -> current-task
+  -> project-context
+  -> API / DB / decisions / known issues / changelog
+
+项目治理层 docs/harness/ + docs/testing/
+  -> driver 协议
+  -> prompt / knowledge / rule 集成
+  -> MCP / 代码语义 / 回归 / 证据治理
+
+项目知识层 docs/knowledge/
+  -> catalog
+  -> decisions / guidelines / pitfalls / processes / models
+
+分发与模板层
+  -> docs/codex-harness-engineering/templates/*
+  -> templates/package-assets/*
+```
+
+## 2. 六类知识面
+
+### A. 宿主自动加载面
+
+这是“Codex 在启动或运行时有机会自动带进上下文”的部分。
+
+- `AGENTS.md`
+- `.codex/prompts/*`
+- `.codex/rules/*`
+- `.codex/agents/*`
+- 被触发的 `.agents/skills/*/SKILL.md`
+- hooks 的 `additionalContext`
+
+这层的核心职责是：
+
+- 定义行为约束
+- 定义执行角色
+- 控制什么时候查什么
+- 告诉模型哪些文件是真相源
+
+这层不适合塞大量长期知识原文。它负责“路由和约束”，不负责“承载全部项目知识正文”。
+
+## B. 项目导航层
+
+这是 `docs/ai/`，作用是让 agent 在不爆上下文的前提下快速理解当前项目。
+
+建议至少包含：
+
+- `repo-map.md`
+- `architecture-brief.md`
+- `CURRENT_TASK.md`
+- `PROJECT_CONTEXT.md`
+- `DECISIONS.md`
+- `API_MAP.md`
+- `DB_SCHEMA.md`
+- `KNOWN_ISSUES.md`
+- `CHANGELOG_AI.md`
+
+这层的核心职责是：
+
+- 提供最短阅读路径
+- 提供项目结构导航
+- 为代码语义检索和文档检索提供入口
+- 把“当前任务事实”和“长期知识条目”分开
+
+## C. 项目治理层
+
+这是 `docs/harness/` 和 `docs/testing/`。
+
+它们不是普通说明文档，而是 driver、review、verify、archive 等流程会引用的治理真相源。
+
+典型内容：
+
+- `docs/harness/architecture.md`
+- `docs/harness/prompt-knowledge-integration.md`
+- `docs/harness/knowledge-architecture.md`
+- `docs/harness/mcp-knowledge-governance.md`
+- `docs/harness/code-semantics-and-navigation.md`
+- `docs/testing/*`
+
+这层的核心职责是：
+
+- 规定知识如何被查询、引用、升级、归档
+- 规定测试与证据如何左移
+- 规定外部知识和项目知识的边界
+
+## D. 项目知识层
+
+这是 `docs/knowledge/`。
+
+这层只放已经值得复用、且应留在仓库中的项目经验：
+
+- 架构决策
+- 推荐做法
+- 禁止做法与替代方案
+- 已知坑
+- 过程化经验
+
+这层应通过 `knowledge-catalog.md -> catalog.md -> 具体条目` 的方式渐进读取，而不是整库灌入上下文。
+
+## E. 外部知识层
+
+这是项目外部但与当前实现有关的知识面：
+
+- 官方文档
+- 第三方平台文档
+- 公共 GitHub 仓库
+- 团队共享知识库
+- 行业规范
+
+这层通常通过 MCP 或搜索工具访问。默认不直接成为项目真相源，除非被明确转录、验证并沉淀到项目文档或知识条目中。
+
+## F. 个人知识层
+
+这是用户自己的长期经验：
+
+- 本地 Markdown
+- Obsidian
+- 私有备忘
+- 本地脚本说明
+- 个人常见问题清单
+
+这层默认不进入仓库，不应被当作团队或项目公共真相源。适合通过本地 KB MCP 查询，或在确认后提炼成项目知识条目。
+
+## 3. 默认查询顺序
+
+推荐执行顺序如下：
+
+1. `AGENTS.md`
+2. `docs/ai/repo-map.md`
+3. `docs/ai/architecture-brief.md`
+4. `docs/ai/CURRENT_TASK.md`
+5. 需要时读取 `docs/ai/PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`、`KNOWN_ISSUES.md`
+6. 进入 `docs/harness/*` 治理真相源
+7. 进入 `docs/knowledge/knowledge-catalog.md`
+8. 仅在需要时查询 MCP、外部知识或个人知识
+
+## 4. 升级边界
+
+不同知识面之间的升级边界如下：
+
+- 单次任务经验：先写 `docs/ai/CURRENT_TASK.md` 或归档报告，不直接写 `AGENTS.md`
+- 可复用项目经验：进入 `docs/knowledge/*`
+- 稳定治理规则：进入 `docs/harness/*`、`.codex/prompts/*`、`.codex/rules/*`
+- 可安装模板：进入 `docs/codex-harness-engineering/templates/*`
+- 可分发镜像：进入 `templates/package-assets/*`
+
+## 5. 常见误区
+
+- 把 `config.toml` 当成知识正文。它主要是运行配置，不是项目知识库。
+- 把 `AGENTS.md` 写成超长百科。它应该更像入口规则和导航路由。
+- 把外部文档查询结果直接当作项目真相源。需要先验证，再落到仓库。
+- 把个人笔记直接升格为团队规则。必须先走项目知识沉淀和证据链。
+- 只有文档概念，没有安装模板。这样新项目初始化后会缺文件面。
+
+## 6. 相关文档
+
+- `docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
+- `docs/harness/knowledge-architecture.md`
+- `docs/harness/prompt-knowledge-integration.md`
+- `docs/harness/mcp-knowledge-governance.md`
+- `docs/harness/code-semantics-and-navigation.md`
+- `docs/codex-harness-engineering/doc-update-map.md`

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

@@ -1,57 +1,57 @@
-# Harness Mode Matrix
-
-## 1. Summary
-
-当前安装体系同时保留 `user`、`project`、`vendor`、`full` 四种模式，但它们暴露的是不同层能力，不应混成一个概念：
-
-| 模式 | 主要定位 |
-| --- | --- |
-| `user` | 用户级共享能力层，更适合全局技能、规则和类似 `/goal` 的外层长期目标控制习惯 |
-| `project` | 项目根 runtime + truth source，适合 driver-first、stop hook、trace、verify 闭环 |
-| `vendor` | 离线 / 隔离环境下的完整 package 镜像复制 |
-| `full` | `project` runtime + 完整 `.agents/` package assets，适合长期驻留的完整 Harness 项目 |
-
-其中：
-
-- **外层目标控制** 更适合放在 `user` 层使用。
-- **仓库级持续执行与治理** 更适合放在 `project` / `full` 层使用。
-
-| 字段 | user | project | vendor | full |
-| --- | --- | --- | --- | --- |
-| 适用场景 | 全局规则、共享技能、外层长期目标控制 | 目标项目最小 driver-first 闭环 | 离线 / 隔离复制完整包 | 长期业务项目的完整 Harness 工程 |
-| 状态源 | 用户环境 | `task.json` | 以复制的 package 为主 | `task.json` |
-| 执行入口 | 用户级 Codex / CLI / App | `tools/harness/codex-loop.ps1` | 按目标环境决定 | `tools/harness/codex-loop.ps1` |
-| 提交责任 | 不负责项目提交 | driver | 不默认承担项目提交 | driver |
-| trace 责任 | 无项目级 trace 保证 | driver 写 `traces/*.json` | 取决于目标环境 | driver 写 `traces/*.json` |
-| 验证入口 | 用户自定义 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` | 取决于目标环境 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` |
-| 持续运行定位 | 可承载 `/goal` 这类外层长期目标控制 | stop hook + driver continuation | 取决于复制后的目标环境 | 同时具备 `project` 执行面和 `.agents/` 能力包 |
-| 禁区 | 不应假装拥有项目级 gate | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 | 不应误当作项目执行协议本身 | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 |
-
-## 2. Installation Outputs
-
-| 模式 | 必备安装产物 |
-| --- | --- |
-| user | 共享 package assets、全局规则/技能入口，不要求目标项目先具备完整 runtime |
-| project | `AGENTS.md`、`tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`task.json`、`.codex/*`、`docs/harness/*`、`docs/testing/*`、`docs/ai/*` |
-| vendor | `.agents/` 下的完整 package 镜像、模板和 skills/workflows |
-| full | `project` runtime 产物 + `.agents/workflows/*`、`.agents/.specify/*`、`.agents/skills/*` 等完整能力包 |
-
-## 3. Ownership Rules
-
-| 字段 | project / full |
-| --- | --- |
-| 当前任务边界 | `task.json` 当前 task 的 `owned_paths`、`dependencies`、`test_command` |
-| 提交者 | `tools/harness/codex-loop.ps1` 或任务收尾流程 |
-| 失败记录 | `progress.txt` + `traces/*.json` |
-| 允许的运行产物 | `task.json`、`progress.txt`、`traces/`、显式 `non_blocking_dirty_paths` |
-
-`user` 和 `vendor` 模式本身不应宣称拥有上述项目级 ownership gate；它们更多提供共享控制面或分发面。
-
-## 4. SpecKit Usage
-
-SpecKit 仍用于生成或完善 `spec.md`、`plan.md`、testing truth sources 和任务拆解输入。方案确认后，应把结果转成 `tools/harness/templates/project-task-template.json` / `task.json`，再交给 `tools/harness/codex-loop.ps1` 执行。
-
-如果未来要把 Codex `/goal` 纳入长期运行体验，推荐分层是：
-
-- `user` 层承载 `/goal` 这类长期目标控制习惯
-- `project` / `full` 层承载 driver-first 的仓库执行协议
+# Harness Mode Matrix
+
+## 1. Summary
+
+当前安装体系同时保留 `user`、`project`、`vendor`、`full` 四种模式，但它们暴露的是不同层能力，不应混成一个概念：
+
+| 模式 | 主要定位 |
+| --- | --- |
+| `user` | 用户级共享能力层，更适合全局技能、规则和类似 `/goal` 的外层长期目标控制习惯 |
+| `project` | 项目根 runtime + truth source，适合 driver-first、stop hook、trace、verify 闭环 |
+| `vendor` | 离线 / 隔离环境下的完整 package 镜像复制 |
+| `full` | `project` runtime + 完整 `.agents/` package assets，适合长期驻留的完整 Harness 项目 |
+
+其中：
+
+- **外层目标控制** 更适合放在 `user` 层使用。
+- **仓库级持续执行与治理** 更适合放在 `project` / `full` 层使用。
+
+| 字段 | user | project | vendor | full |
+| --- | --- | --- | --- | --- |
+| 适用场景 | 全局规则、共享技能、外层长期目标控制 | 目标项目最小 driver-first 闭环 | 离线 / 隔离复制完整包 | 长期业务项目的完整 Harness 工程 |
+| 状态源 | 用户环境 | `task.json` | 以复制的 package 为主 | `task.json` |
+| 执行入口 | 用户级 Codex / CLI / App | `tools/harness/codex-loop.ps1` | 按目标环境决定 | `tools/harness/codex-loop.ps1` |
+| 提交责任 | 不负责项目提交 | driver | 不默认承担项目提交 | driver |
+| trace 责任 | 无项目级 trace 保证 | driver 写 `traces/*.json` | 取决于目标环境 | driver 写 `traces/*.json` |
+| 验证入口 | 用户自定义 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` | 取决于目标环境 | `tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、task `test_command` |
+| 持续运行定位 | 可承载 `/goal` 这类外层长期目标控制 | stop hook + driver continuation | 取决于复制后的目标环境 | 同时具备 `project` 执行面和 `.agents/` 能力包 |
+| 禁区 | 不应假装拥有项目级 gate | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 | 不应误当作项目执行协议本身 | 不手改 `task.json`、`progress.txt`、`traces/`；不绕过任务依赖和验证命令 |
+
+## 2. Installation Outputs
+
+| 模式 | 必备安装产物 |
+| --- | --- |
+| user | 共享 package assets、全局规则/技能入口，不要求目标项目先具备完整 runtime |
+| project | `AGENTS.md`、`tools/harness/codex-loop.ps1`、`tools/harness/doctor.ps1`、`tools/harness/verify.ps1`、`task.json`、`.codex/*`、`docs/harness/*`、`docs/testing/*`、`docs/ai/*` |
+| vendor | `.agents/` 下的完整 package 镜像、模板和 skills/workflows |
+| full | `project` runtime 产物 + `.agents/workflows/*`、`.agents/.specify/*`、`.agents/skills/*` 等完整能力包 |
+
+## 3. Ownership Rules
+
+| 字段 | project / full |
+| --- | --- |
+| 当前任务边界 | `task.json` 当前 task 的 `owned_paths`、`dependencies`、`test_command` |
+| 提交者 | `tools/harness/codex-loop.ps1` 或任务收尾流程 |
+| 失败记录 | `progress.txt` + `traces/*.json` |
+| 允许的运行产物 | `task.json`、`progress.txt`、`traces/`、显式 `non_blocking_dirty_paths` |
+
+`user` 和 `vendor` 模式本身不应宣称拥有上述项目级 ownership gate；它们更多提供共享控制面或分发面。
+
+## 4. SpecKit Usage
+
+SpecKit 仍用于生成或完善 `spec.md`、`plan.md`、testing truth sources 和任务拆解输入。方案确认后，应把结果转成 `tools/harness/templates/project-task-template.json` / `task.json`，再交给 `tools/harness/codex-loop.ps1` 执行。
+
+如果未来要把 Codex `/goal` 纳入长期运行体验，推荐分层是：
+
+- `user` 层承载 `/goal` 这类长期目标控制习惯
+- `project` / `full` 层承载 driver-first 的仓库执行协议

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/codex-harness-engineering/new-project-usage.md

@@ -0,0 +1,176 @@
+# 新项目 Codex Harness 使用指南
+
+本文面向刚创建或刚接入 Harness 的项目。当前版本先跑通单 driver 闭环，不再提供额外执行工作区或外部 worker 编排流程；主控会话负责判断和派发，不直接写仓库文件，需要落盘时转给包内匹配的 writer 子代理。
+
+## 使用路线总览
+
+| 场景 | 推荐入口 | 说明 |
+| --- | --- | --- |
+| 第一次接入 Harness | `tools\\install/init-project.ps1` | thin 初始化 `AGENTS.md`、`tools/harness/*`、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/` 和 `docs/spec/` |
+| spec / plan 已确认，准备切主控 | `tools/harness/templates/project-task-template.json` -> `task.json` -> `tools/harness/codex-loop.ps1 -RunUntilDone` | 交互模式在这里结束，后续默认由 driver 接管 |
+| 单个需求串行实现 | `tools/harness/codex-loop.ps1 -RunUntilDone` | 一个 Git 工作区里按 `task.json` 优先级逐个完成任务 |
+| 需要沉淀项目经验 | `docs/knowledge/knowledge-catalog.md` -> `ARCHIVE-001` | 任务结束后把可复用经验归档为知识条目 |
+| 既有项目冷启动知识库 | `docs/harness/knowledge-import.md` | 从 README、docs、代码结构、issue/review 中提取 draft 条目 |
+| 维护知识库健康 | `docs/harness/knowledge-lint.md` | 检查索引、孤儿条目、重复、冲突、成熟度和长期未引用条目 |
+| 连接团队知识库 | `docs/harness/team-knowledge-sync.md` | 把 verified/proven 跨项目候选输出到独立团队知识库的贡献暂存区 |
+
+## 安装模式
+
+安装包由 `install-manifest.json` 声明输出面，治理规则见 `docs/harness/install-manifest-governance.md`。
+
+| 模式 | 命令入口 | 输出内容 |
+| --- | --- | --- |
+| `project` | `tools\\install/init-project.ps1` / `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project` | 新默认 thin project 入口，只输出项目运行必需内容 |
+| `full` | `tools\\install/install-agent.ps1 -Mode full` | 显式 legacy full 入口，同时安装项目 runtime、`.agents/` vendor 包和共享资源 |
+| `vendor` | `tools\\install/install-agent.ps1 -Mode vendor` / `tools\\install/install-agent.ps1 -Scope vendor` | 只复制 `.agents/` vendor 包，适合离线或强隔离场景 |
+| `user` | `tools\\install/install-user.ps1` / `tools\\install/install-agent.ps1 -Scope user` | 只写入 `%USERPROFILE%/.codex/packages/codex-harness/` 下的 package source 和 user lock |
+
+`full` 行为作为显式 legacy 兼容入口保留。当前包已经提供 package lock、只读升级/卸载计划、安全 `-Upgrade` 和 vendor `-Uninstall`。新分层入口优先使用 wrapper 或等价 `-Scope user|project|vendor` 命令：`tools\\install/install-user.ps1` 等价于 `tools\\install/install-agent.ps1 -Scope user`，`tools\\install/init-project.ps1` 等价于 `tools\\install/install-agent.ps1 -ProjectRoot . -Scope project`。当前不提供 `harness install-user` 子命令。当前不提供 `harness init-project` 子命令。Windows PowerShell 主链路请直接运行这两个 wrapper，避免误以为存在独立 CLI。`-Scope project` 与无参数 `tools\\install/install-agent.ps1 -ProjectRoot .` 等价，都是新项目默认 thin 输出，只生成项目运行必需 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`.codex-harness/manifests/install-manifest.json`、`docs/ai/`、`docs/architecture/constraints.md`、`docs/spec/01..14` 和 `tools/`，不复制完整 vendor 镜像、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/`。`-Scope user` 只安装用户级 package source 并写入用户级 lock。
+
+## `docs/ai/` 导航层
+
+- `repo-map.md`
+- `architecture-brief.md`
+- `CURRENT_TASK.md`
+- `PROJECT_CONTEXT.md`
+- `DECISIONS.md`
+- `API_MAP.md`
+- `DB_SCHEMA.md`
+- `KNOWN_ISSUES.md`
+- `CHANGELOG_AI.md`
+
+推荐顺序：
+
+1. 先裁剪 `repo-map.md` 和 `architecture-brief.md`
+2. 再补 `CURRENT_TASK.md`
+3. 复杂项目再补 `PROJECT_CONTEXT.md`、`DECISIONS.md`、`API_MAP.md`、`DB_SCHEMA.md`
+4. 把长期可复用经验沉淀到 `docs/knowledge/*`
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-user.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor
+```
+
+直接运行 `tools\\install/bootstrap-codex-harness.ps1` 或旧 `-Mode project` 仍使用 legacy profile，适合需要保留完整 harness 文档包的旧项目；新项目默认使用 `tools\\install/init-project.ps1` 或等价 `-ProjectRoot . -Scope project`。
+
+`tools/harness/doctor.ps1` 会按 `installScope=project` 检查 thin 输出：缺少 `.codex-harness/manifests/install-manifest.json` 会提示 warning，snapshot JSON 非法、`docs/architecture/constraints.md` 或 `docs/spec/01..14` 缺失会失败；发现 `.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/` 或 `docs/requirement-prep-kit/` 时只提示 legacy 残留 warning，不会自动删除。
+
+Phase 7 切换门禁先看 doctor 的 readiness 汇总：
+
+- `Readiness gate: PASS` 且 `ProjectShape: thin-project`：项目已满足 thin 前置条件。
+- `ProjectShape: thin-project-missing-user-package`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-user.ps1`，再重新运行 `tools/harness/doctor.ps1`。
+- `ProjectShape: thin-project-with-legacy-residue` 或 `legacy-full-project`：先运行 `-MigratePlan` 查看分类，再按报告决定是否运行 `-MigrateApply -Confirm`。
+- `ProjectShape: vendor-project`：保留 vendor 模式时运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Scope vendor` 或重新运行 `tools/harness/doctor.ps1` 复核 drift。
+- `ProjectShape: not-installed`：先运行 `powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1`。
+
+readiness gate 只读；它只报告阻断项和 `FixCommand`，不会自动安装、迁移、删除或覆盖项目文件。
+
+已有 legacy `.agents/` 项目不要直接清理目录。先运行只读迁移计划：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -MigratePlan
+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
+```
+
+操作顺序固定为：
+
+- 先跑 `-MigratePlan`，拿到 `adopt-vendor-managed`、`blocked-user-drift`、`missing-vendor-file`、`unknown-legacy-file`、`manual-review` 分类报告。
+- 再跑 `-MigrateApply` 做 dry-run，确认计划写入和阻断原因；此时 `actualWrites` 必须为空。
+- 只有确认没有阻断项且接受计划写入时，才用显式确认开关执行 `-MigrateApply -Confirm`。
+
+迁移执行默认只允许写 `.codex-harness/locks/package.lock.json` 和必要 `.codex-harness` config/install metadata，不会自动删除 `.agents`，不会覆盖用户文档，也不会处理 legacy docs 自动删除。`adopt-vendor-managed` 只有在确认后才会写入 `managedFiles`；`missing-vendor-file` 只记录缺失，不会凭空安装或删除；`blocked-user-drift`、`unknown-legacy-file`、`manual-review` 都会阻断自动执行。确认结果后再选择保留 `-Scope vendor`，或重新以 `-Scope project` 初始化 thin 输出并手工迁出需要保留的内容。
+
+`-MigratePlan` 和 `-MigrateApply` 的职责要分开理解：前者只做只读分类和报告，后者只做确认式应用。不要把 `-MigrateApply` 当成默认 full 迁移，也不要在没有 `-Confirm` 的情况下期待它写 lock。
+
+如果 `-MigrateApply` 输出 `status=blocked`，先按 `blockedReasons` 处理，再重新跑 `-MigratePlan` 复核分类是否变化。不要把阻断项当成临时 warning 忽略，也不要直接改写 `.agents/` 来规避 drift 分类。
+
+默认安装已在 Phase 7 切到 thin project；迁移执行仍然只处理确认式落锁，不会自动清理 `.agents` 或 legacy docs。后续扩展迁移能力时，必须继续以 `-MigratePlan` 分类结果作为输入语义来源。
+
+## 升级和卸载
+
+已安装项目先用只读计划判断风险：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
+```
+
+计划中没有 `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 . -Uninstall
+```
+
+`-Upgrade` 只覆盖 lock 记录中未发生用户 drift 的不可变文件，并刷新 `.codex-harness/locks/package.lock.json`。`-Uninstall` 只删除 lock 中 `scope=vendor` 的 managed files，保留 project scope 和 user scope。
+
+如果输出 `blocked-user-drift`，先人工对比目标文件、lock hash 和当前包内容；需要保留的修改应手工合并或迁出，需要放弃的修改应恢复后再重新执行计划。
+
+## 迁移失败处理
+
+`-MigratePlan` 或 `-MigrateApply` 只要出现以下情况，就按失败处理并暂停自动执行：
+
+- `blocked-user-drift`
+- `unknown-legacy-file`
+- `manual-review`
+- `status=blocked`
+- `actualWrites` 在 dry-run 阶段非空
+
+处理顺序建议如下：
+
+1. 先看 `blockedReasons` 和 `summaryCounts`，确认阻断来自哪类文件或哪类 drift。
+2. 如果是用户改动，先人工迁出或合并，再重新跑 `-MigratePlan`。
+3. 如果是 legacy 未分类文件，保留现状，等后续独立任务补逐项确认机制。
+4. 如果 dry-run 出现非空 `actualWrites`，说明执行边界异常，停止继续操作并回退到计划阶段排查。
+
+## 1. 初始化
+
+```powershell
+git status --short
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/init-project.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/env-check.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/doctor.ps1
+```
+
+如果项目存在 `build`、`lint`、`test`、`typecheck`、`docker build` 或 CI workflow，首次接入时应同时把这些命令和环境变量依赖补到 `docs/harness/env-and-deployment-template.md`，不要只留在 `package.json` 或 CI 配置里。
+
+## 2. 创建任务
+
+```powershell
+Copy-Item .\tools\harness\templates\tools/harness/templates/project-task-template.json .\task.json
+```
+
+建议 `runtime.git` 使用：
+
+```json
+{
+  "require_clean_workspace": true,
+  "non_blocking_dirty_paths": []
+}
+```
+
+## 3. 运行 Driver
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\harness/codex-loop.ps1 -RunUntilDone
+```
+
+- `.codex/agents/*.toml` 同时提供只读辅助子代理和写入型 worker 子代理。
+- 这些子代理开始前必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md`、`.codex/rules/agents.md` 和对应 `.agents/skills/*/SKILL.md`（如存在）。
+- 如果是被 stop hook 拦下后继续执行的下一轮，也先按上面这组文档重读一遍，再决定是否启用子代理。
+- 如果主控需要更新 `task.json`、`AGENTS.md`、`.codex/*`、`.codex/rules/*`、`docs/harness/*`、prompt 或其他非 driver 内容，必须委派 `harness-writer`、`docs-worker` 或匹配的实现 worker，不能由主控会话自己写。
+- 目标项目的 `.agents/` 默认不再复制项目运行时用的 `.codex/` 或 `docs/harness/`；这些内容直接安装到项目根。为了支持安装后的再次 bootstrap，`.agents/docs/codex-harness-engineering/templates/` 会保留模板复制源。
+- `docs/ai/` 是项目导航层；默认先读 `repo-map.md`、`architecture-brief.md`、`CURRENT_TASK.md`。
+- `docs/knowledge/` 是项目级知识层；实现会话按 `knowledge-catalog.md`、`catalog.md`、具体条目的顺序按需读取，归档任务负责更新索引。
+- 已有项目接入时，可先按 `docs/harness/knowledge-import.md` 冷启动 5-13 条 draft 知识；导入过程用 `import-state.json` 或导入报告记录 processed/pending/skipped/low_confidence 来源和 resume cursor，后续任务通过引用和验证逐步提升成熟度。
+- 每隔一段任务后，按 `docs/harness/knowledge-lint.md` 检查索引一致、重复、冲突和长期未引用条目。
+- 如果团队维护独立知识库，按 `docs/harness/team-knowledge-sync.md` 把跨项目候选写入 `contributions/pending/`；该同步失败只能降级为候选报告，不能阻塞本地实现验证。
+- 如果需要接入 MCP、外部文档或代码语义工具，先读 `docs/harness/mcp-knowledge-governance.md` 和 `docs/harness/code-semantics-and-navigation.md`。
+
+## 4. UI 项目要求
+
+- 保存设计参考图。
+- 保存真实浏览器截图。
+- 输出视觉对比报告。