@pzy560117/codex-harness 0.1.3 → 0.1.4

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

@@ -1,307 +0,0 @@
-# Install Manifest 治理标准
-
-本文定义 Codex Harness 安装包 manifest 的治理边界。目标是让安装器、doctor、包刷新脚本和项目锁对同一份安装清单形成一致理解，避免安装输出继续依赖脚本内硬编码列表。
-
-## 适用文件
-
-| 文件 | 职责 |
-| --- | --- |
-| `install-manifest.json` | 当前包的安装模式、安装条目和目标位置声明 |
-| `install-manifest.schema.json` | manifest 静态字段、路径形状和安装模式全集约束 |
-| `.codex-harness/state/config.json` | 目标项目锁定的 package 版本、packageRoot、installScope 和 vendor 状态 |
-| `.codex-harness/locks/package.lock.json` | 目标项目安装后的包名、lockVersion、installMode 和 vendor 状态 |
-| `.codex-harness/manifests/install-manifest.json` | 安装时 manifest 快照，用于审计当次输出，不作为用户可编辑真源 |
-| `tools/harness/doctor.ps1` | 对目标项目中 manifest、lock、Spec 包和 runtime 文件做只读检查 |
-
-`docs/参考/` 是人工评审和方案沉淀用的本地参考资料，不属于安装包治理面，默认不进入 PR。参考资料不能进入 `install-manifest.json`、不能安装到目标项目，也不能作为运行时 truth source；需要沉淀时，应先转写为 `docs/agent-package-redesign/` 或 `docs/harness/` 中的结论文档。
-
-## 安装模式
-
-| 模式 | scope | 输出位置 | 用途 |
-| --- | --- | --- | --- |
-| `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 |
-
-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 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` 元数据。
-
-## Entry 规则
-
-每个 `entries[]` 条目必须满足：
-
-- `source` 是包内相对路径，只使用 `/`，不能是 rooted path，不能包含 `..`。
-- `destination` 对 `project` 和 `vendor` 必须是项目内相对路径，只使用 `/`，不能写入 `%USERPROFILE%`。
-- `destination` 对 `user` 必须以 `%USERPROFILE%/` 开头，只使用 `/`，不能包含 `..`。
-- 同一 `scope` 下不能出现重复 `destination`。
-- `source` 指向目录时，`source` 和 `destination` 都必须以 `/` 结尾。
-- `source` 指向文件时，`source` 和 `destination` 都不能以 `/` 结尾。
-- `kind` 使用小写 kebab-case，用于后续 drift check、升级报告和卸载策略分组。
-
-## Doctor Gate
-
-`tools/harness/doctor.ps1` 对 manifest 做只读 gate：
-
-- 缺失或非法 JSON 是 error。
-- 缺少 schema 是 warning，schema JSON 非法是 error。
-- install mode 重复、缺失、未知是 error。
-- entry scope/path/source/destination 不符合规则是 error。
-- 必要安装覆盖缺失是 warning，用于提示包面不完整但不阻断已有项目运行。
-
-doctor 不会修改目标项目，也不会自动删除 legacy `.agents/` 内容。需要迁移时应由独立迁移命令生成报告，并在用户确认后处理。
-
-`installScope=project` 项目会额外执行 thin 输出 gate：`.codex-harness/state/config.json`、`.codex-harness/locks/package.lock.json`、`docs/ai/`、`docs/architecture/constraints.md` 和 `docs/spec/01..14` 缺失会作为错误；`.codex-harness/manifests/install-manifest.json` 缺失是 warning，snapshot JSON 非法或缺少 `package/version/installModes/entries` 是 error；`.agents/`、`docs/harness/`、`docs/testing/`、`docs/knowledge/`、`docs/requirement-prep-kit/` 只作为 legacy/vendor 残留 warning，不阻断旧项目。
-
-在 Phase 7 切换门禁中，doctor 还必须输出 readiness gate 汇总，用于区分可直接切换和需要人工处理的项目形态：
-
-- `Readiness gate: PASS|WARN|FAIL`
-- `ProjectShape: thin-project|thin-project-missing-user-package|thin-project-with-legacy-residue|legacy-full-project|vendor-project|not-installed`
-- `ReadinessChecks: read-only`
-- `FixCommand: <command>`
-
-readiness gate 只能读取项目文件。它不得自动执行安装、迁移、删除、覆盖或 lock 写入。`thin-project` 没有阻断项时输出 `FixCommand: none`；缺少用户级 package 时必须给出 `-Scope user`；legacy full 或 legacy residue 必须给出 `-MigratePlan`，并在 legacy full 中同时提示确认式 `-MigrateApply -Confirm`；vendor 项目必须继续使用 vendor lock/drift 检查，并给出 `-Scope vendor` 或重新运行 doctor 的命令；未安装项目必须给出 `-Scope project`。
-
-## Package Lock Drift
-
-项目初始化后，`.codex-harness/locks/package.lock.json` 必须记录当前安装模式和不可变文件快照：
-
-```json
-{
-  "lockVersion": "0.1",
-  "package": "codex-harness",
-  "version": "0.1.0",
-  "sourceCommit": "<git-sha>",
-  "installMode": "project",
-  "vendor": false,
-  "managedFiles": [
-    {
-      "path": "tools/harness/codex-loop.ps1",
-      "source": "templates/runtime/codex-loop.ps1",
-      "scope": "project",
-      "kind": "runtime-script",
-      "mutable": false,
-      "sha256": "<installed-file-sha256>"
-    }
-  ]
-}
-```
-
-lock 会对 `mutable=false` 条目写入 hash。文件条目按目标文件记录；目录条目按目录内实际安装文件展开为逐文件记录，例如 `.agents/workflows/speckit.specify.md`。`generated-lock` 和 `.codex-harness/locks/package.lock.json` 自身不写入 `managedFiles`，避免自引用 hash。
-
-doctor 对 `managedFiles` 执行只读检查：
-
-- `path` 必须是项目内相对路径，不能是 rooted path，不能包含 `..`。
-- `sha256` 不能为空。
-- 文件缺失是 error。
-- 文件内容 hash 和 lock 不一致是 error。
-- 旧 lock 缺少 `managedFiles` 是 warning，用于兼容已安装项目。
-
-`.codex-harness/state/config.json` 记录项目当前绑定的 package：
-
-```json
-{
-  "package": "codex-harness",
-  "version": "0.1.0",
-  "packageRoot": "%USERPROFILE%\\.codex\\packages\\codex-harness\\0.1.0",
-  "installScope": "project",
-  "vendor": false
-}
-```
-
-`installScope=project` 时，项目默认不要求存在 `.agents/`；`installScope=vendor` 时，`packageRoot` 指向项目内 `.agents/`。`.codex-harness/manifests/install-manifest.json` 是安装时快照，来源于 package 的 `install-manifest.json`，用于审计和排查，不作为后续编辑入口。snapshot 缺失会提示 warning，JSON 非法或缺少 `package/version/installModes/entries` 会作为 doctor error。
-
-迁移计划与执行边界：
-
-- `-MigratePlan` 仍然只读，不能写 lock、不能删文件、不能把 legacy docs 归类为可删除内容。
-- `-MigrateApply` 只能消费迁移分类报告，不能跳过 `blocked-user-drift`、`unknown-legacy-file`、`manual-review` 直接写入。
-- `missing-vendor-file` 只保留缺失记录，不得写入 `managedFiles`。
-- `adopt-vendor-managed` 只有在显式 `-Confirm` 后才允许写入 lock / metadata。
-
-## 升级策略
-
-安装器提供升级计划和安全执行入口：
-
-```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
-```
-
-`-UpgradePlan` 只读取当前包 manifest 和目标项目 `.codex-harness/locks/package.lock.json`，不会写入、覆盖或删除文件。计划输出会按 entry 标记：
-
-- `keep`：不可变文件和当前包一致。
-- `update-immutable`：不可变文件未被用户改动，可由后续升级执行命令覆盖。
-- `blocked-user-drift`：目标文件已偏离 lock，需要人工确认。
-- `manual-review`：`mutable=true` 文件，只提示不覆盖。
-- `install-missing` / `no-lock-entry`：目标缺失或旧 lock 信息不足。
-
-`-Upgrade` 会按以下顺序执行：
-
-1. 读取目标项目 `.codex-harness/locks/package.lock.json`。
-2. 读取当前包 `install-manifest.json` 和 schema。
-3. 对比 lock 中的 `installMode`、`vendor` 和当前 manifest entries。
-4. 如发现任意 `blocked-user-drift`，停止执行并返回非 0。
-5. 只覆盖 `mutable=false` 且未发生用户改动的 `update-immutable` / `install-missing` 文件。
-6. 跳过 `mutable=true`、`manual-review` 和 `no-lock-entry` 项。
-7. 刷新 `.codex-harness/locks/package.lock.json` 中的逐文件 hash。
-
-执行命令仍保持保守：旧 lock 缺少逐文件记录时不会猜测覆盖，必须先人工确认或重新安装形成新的 lock。
-
-## 升级操作手册
-
-对已安装项目升级时，先在目标项目中运行只读计划：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UpgradePlan
-```
-
-按计划输出处理：
-
-- 只有 `keep` 时，不需要执行升级。
-- 出现 `update-immutable` 或 `install-missing`，且没有 `blocked-user-drift` 时，可以运行 `-Upgrade`。
-- 出现 `manual-review` 时，说明该文件是用户可编辑面，安装器不会覆盖；需要人工判断是否参考新包内容合并。
-- 出现 `no-lock-entry` 时，说明旧 lock 信息不足；安装器不会猜测覆盖，应先人工确认来源，必要时重新安装以生成新 lock。
-- 出现 `blocked-user-drift` 时，说明目标文件已被用户或本地流程改动。先对比目标文件、lock 记录和当前包内容，决定保留用户改动、手工合并，或回退该文件后再升级。
-
-只有计划中没有 `blocked-user-drift` 时才执行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Upgrade
-```
-
-`-Upgrade` 成功后会刷新 `.codex-harness/locks/package.lock.json`。升级后建议立即运行 `tools/harness/doctor.ps1` 验证 drift 状态。
-
-## 卸载策略
-
-安装器提供卸载计划和保守执行入口：
-
-```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
-```
-
-`-UninstallPlan` 默认保留 `project` scope 内容，避免误删 `task.json`、`progress.txt`、`docs/spec/`、`docs/architecture/` 和项目 truth source；legacy 项目中的 `docs/testing/` 也不会由卸载命令主动清理。`vendor` scope 会标记为可删除候选，`user` scope 会标记为需要逐项人工确认。
-
-`-Uninstall` 采用保守策略：
-
-- 必须先读取 `.codex-harness/locks/package.lock.json`；缺少 lock 时拒绝执行。
-- 默认只删除 lock 中 `scope=vendor` 的 `managedFiles`，不按当前 manifest 猜测删除。
-- 删除前会校验 vendor 文件 hash；如发现 `blocked-user-drift`，停止执行并返回非 0。
-- `project` scope 默认保留，避免删除 `task.json`、`progress.txt`、`docs/spec/` 等 truth source。
-- `user` scope 不由项目卸载命令自动清理，需要人工逐项处理。
-- 删除完成后刷新 lock，并把 `vendor` 标记为 `false`。
-
-## 卸载操作手册
-
-卸载前先运行只读计划：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -UninstallPlan
-```
-
-计划输出中：
-
-- `project` scope 默认保留，避免删除项目 runtime、任务和文档 truth source。
-- `vendor` scope 是可删除候选，但执行时仍以 lock 中的逐文件记录为准。
-- `user` scope 只提示人工清理，不由项目卸载命令处理。
-
-确认只移除 vendor 包后执行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\\install/install-agent.ps1 -ProjectRoot . -Uninstall
-```
-
-如果卸载输出 `blocked-user-drift`，说明 `.agents/` 下至少一个 vendor 文件和 lock hash 不一致。此时不要强删整个 `.agents/`，应先确认这些文件是否包含本地修改；需要保留时手工迁出，需要放弃时先恢复到 lock 对应内容或重新安装后再卸载。
-
-## 迁移计划
-
-旧项目从完整 `.agents/` vendor 输出迁移到 thin project 前，先运行只读迁移计划：
-
-```powershell
-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/`，并按以下动作归类：
-
-- `adopt-vendor-managed`：目标 vendor 文件与当前 package 一致，可在后续人工确认后纳入 managedFiles。
-- `blocked-user-drift`：目标 vendor 文件与当前 package 不一致，需要人工确认或手工合并。
-- `missing-vendor-file`：当前 manifest 声明 vendor 文件，但目标项目缺失，仅报告。
-- `unknown-legacy-file`：`.agents/` 中存在当前 manifest 未声明的文件，仅报告。
-- `manual-review`：legacy 文档目录或残留内容需要人工判断，迁移计划不会自动清理。
-
-如果项目没有 `.agents/`，迁移计划输出 `Status: no-legacy-vendor`。后续自动落锁和自动清理 vendor 内容必须由独立命令实现，并继续以用户确认和 drift 检查为前提。
-
-## 迁移执行契约
-
-Phase 5 只冻结确认式迁移执行，不切换默认 `full`，也不改变 `-MigratePlan` 的只读语义。执行入口统一为：
-
-本契约对应 Requirement ID `PKG-LAYER-P5-MIGRATE-CONTRACT`，与 `docs/agent-package-redesign/migration-plan.md` 的 Phase 5 章节共同作为后续实现任务的规格来源。当前阶段只定义命令、参数、状态、输出字段、失败条件和允许写入范围，不实现递归清理，不切换默认安装模式。
-
-实现任务 `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
-```
-
-`-MigrateApply` 必须遵守以下边界：
-
-- 输入语义来源是 `-MigratePlan` 的分类报告；不得绕过 `adopt-vendor-managed`、`blocked-user-drift`、`missing-vendor-file`、`unknown-legacy-file`、`manual-review` 分类直接写 lock、删除文件或推断缺失内容。
-- 默认 dry-run；未提供显式确认开关 `-Confirm` 时，只输出计划动作，不写入任何文件。
-- 默认写入面只允许 `.codex-harness/locks/package.lock.json` 和必要 `.codex-harness` config/install metadata。
-- 不自动删除 `.agents`。
-- 不覆盖用户文档。
-- 不处理 legacy docs 自动删除。
-
-分类执行规则：
-
-- `adopt-vendor-managed`：只有显式确认后才可写入 `managedFiles`，且只能写与 package 一致且已分类的 vendor 文件。
-- `missing-vendor-file`：只记录缺失并保留报告，不凭空安装、不自动删除、不补写为已安装。
-- `blocked-user-drift`：必须阻断自动执行。
-- `unknown-legacy-file`：必须阻断自动执行。
-- `manual-review`：必须阻断自动执行。
-
-除非后续任务引入逐项确认机制并补齐测试覆盖，否则阻断分类不允许进入自动写入路径。
-
-`-MigrateApply` 输出格式至少包含：
-
-- `status`
-- `summaryCounts`
-- `actions`
-- `blockedReasons`
-- `plannedWrites`
-- `actualWrites`
-- `nextSteps`
-
-其中 `plannedWrites` 用于 dry-run 和确认前审计，`actualWrites` 只记录真实发生的 lock / metadata 写入；dry-run 时必须为空。`summaryCounts` 至少要能表达分类结果和写入计数，`actions` 需要列出计划执行或实际执行的迁移动作，`blockedReasons` 需要对应阻断分类或安全边界。
-
-状态和失败语义必须保持稳定：
-
-- `status=dry-run`：只解析 `-MigratePlan` 分类并输出计划动作，不写文件，`actualWrites` 必须为空。
-- `status=confirmed-write`：收到 `-Confirm`，且仅写入 `.codex-harness/locks/package.lock.json` 和必要 `.codex-harness` config/install metadata。
-- `status=blocked`：存在 `blocked-user-drift`、`unknown-legacy-file`、`manual-review` 或其他安全边界阻断；命令必须返回非 0，`actualWrites` 必须为空。
-- `status=no-op`：没有可执行写入项或计划结果不需要变更。
-- dry-run 阶段出现非空 `actualWrites` 时，调用方必须按失败处理并回到 `-MigratePlan` 排查。
-
-`-MigrateApply` 的参数语义也必须显式冻结：
-
-- `ProjectRoot`：目标项目根目录，作为 `-MigratePlan` 和 `-MigrateApply` 的共同输入。
-- `MigrateApply`：确认式迁移执行开关，对应只读计划之后的应用阶段。
-- `Confirm`：显式写入确认开关，没有它就只能 dry-run，不能修改 lock 或 metadata。
-- `Confirm` 在本契约中是迁移写入授权语义，不是交互式提示替代；非交互 driver 运行 `-MigrateApply` 时不得因为 PowerShell 默认确认机制而产生写入。
-
-`-MigrateApply` 的执行必须建立在 `-MigratePlan` 的 drift 分类结果之上，不能跳过计划阶段直接执行写入，也不能把 `blocked-user-drift`、`unknown-legacy-file`、`manual-review` 自动降级成可执行项。
-
-## 验证命令
-
-```powershell
-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
-```

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

@@ -1,219 +0,0 @@
-# Harness Knowledge Architecture
-
-本文定义 Codex Harness 的项目知识层。Harness 不只负责把任务跑完，还要把执行中被证明有用的经验沉淀成可检索、可追踪、可维护的项目资产。
-
-## 目标
-
-- 让任务执行前能按需读取项目经验，而不是每次从零推导。
-- 让任务执行后能把架构决策、风险、流程和坏例归档。
-- 让 trace 记录知识引用，支持后续成熟度提升、衰减和冲突治理。
-- 控制上下文预算，避免把大量完整知识一次性塞进每个 Codex 会话。
-
-## 存储层
-
-当前仓库先落地项目级知识层：
-
-```text
-docs/knowledge/
-  knowledge-catalog.md      # 全景入口，约 50-120 行
-  catalog.md                # 当前项目全部知识条目的一行摘要索引
-  models/                   # 实体、数据结构、关系
-  decisions/                # 架构决策和技术选型
-  guidelines/               # 推荐做法和禁止做法
-  pitfalls/                 # 已知风险、失败模式、排查路径
-  processes/                # 工作流、业务流、操作步骤
-  archive/                  # 过时或低置信条目
-```
-
-跨项目团队知识库暂不直接耦合到 runtime。后续如引入独立 Git 知识仓库，应通过同步任务把稳定条目提升出去，而不是让 driver 直接依赖外部仓库可用性。
-
-可选团队知识库建议使用独立 Git 仓库，而不是寄生在某个业务项目中：
-
-```text
-team-knowledge/
-  knowledge-catalog.md        # 团队级全景入口
-  .knowledge-config.yaml      # 成员、角色、同步和冲突策略
-  log.md                      # 只追加的知识变更日志
-  team-conventions/           # Layer 0-T: 团队约定
-  tech-wiki/                  # Layer 1: 跨项目技术知识
-  biz-wiki/<domain>/          # Layer 2: 领域业务知识
-  project-profiles/           # 项目画像和知识源映射
-  contributions/
-    pending/                  # 待合并贡献
-    conflicts/                # 内容矛盾和人工裁决项
-```
-
-团队知识库是可选上层能力。项目 driver 必须能在没有外部知识仓库的情况下继续执行；外部知识同步失败时只能降级为缺少可复用上下文，不应阻断本地验证。
-
-团队知识库的完整同步协议见 `docs/harness/team-knowledge-sync.md`。本文件只定义项目知识层和提升边界；团队知识库的成员角色、贡献暂存、冲突裁决和追加日志由同步协议约束。
-
-## 知识层级
-
-| 层级 | 范围 | 存放建议 | 进入方式 |
-| --- | --- | --- | --- |
-| Layer 0-P | 个人偏好 | 用户本地配置，不提交项目 | 人工维护 |
-| Layer 0-T | 团队约定 | `team-conventions/` | 团队维护 |
-| Layer 1 | 跨项目技术知识 | `tech-wiki/` | verified / proven 技术条目提升 |
-| Layer 2 | 业务领域知识 | `biz-wiki/<domain>/` | verified / proven 业务条目提升 |
-| Layer 3 | 项目知识 | `docs/knowledge/` | `ARCHIVE-*` 或 `KNOWLEDGE-IMPORT-*` 写入 |
-
-提升方向默认从 Layer 3 开始。只有当条目不再是项目特有经验，并且 evidence 显示可跨任务或跨项目复用时，才建议提升到 Layer 1 或 Layer 2。
-
-## 知识类型
-
-| 类型 | 用途 | 示例 |
-| --- | --- | --- |
-| `model` | 描述实体、结构和关系 | task、trace、truth source 的关系 |
-| `decision` | 记录技术选择及原因 | driver-first 优先于聊天内手工实现 |
-| `guideline` | 记录推荐或禁止做法 | 禁止只写禁令而不给替代方案 |
-| `pitfall` | 记录已知风险和排查步骤 | smoke 占位任务被误带入真实项目 |
-| `process` | 记录可重复流程 | ARCHIVE 从 trace 提取知识 |
-
-## 成熟度
-
-| 成熟度 | 定义 | 默认处理 |
-| --- | --- | --- |
-| `draft` | 单次任务、单一来源提取 | 可引用，但不能作为强约束 |
-| `verified` | 至少在一个真实任务中被复用并通过验证 | 可作为 reviewer 的参考依据 |
-| `proven` | 至少两个不同任务或项目复用并保持有效 | 可提升为规则、模板或 prompt |
-
-成熟度提升必须基于 evidence，不接受口头判断。长期未引用或被发现过时的条目应降级或移入 `docs/knowledge/archive/`。
-
-`verified -> proven` 不应由单个任务静默完成。默认需要两个不同任务或项目的证据；如果只有一个项目内证据，必须有 maintainer 在归档报告或团队知识同步记录中明确审批。
-
-## 提升、衰减和冲突
-
-| 事件 | 默认处理 |
-| --- | --- |
-| draft 条目在一个真实任务中被引用并通过验证 | 可提升为 `verified` |
-| verified 条目在两个不同任务或项目中被引用并保持有效 | 可提升为 `proven` |
-| proven 条目 12 个月未被引用 | 建议降级为 `verified` 或标记复核 |
-| verified 条目 6 个月未被引用 | 建议降级为 `draft` 或标记复核 |
-| draft 条目长期未引用且 lint 标记无入口 | 移入 `docs/knowledge/archive/` |
-| 同一主题出现相反结论 | 保留较低成熟度，写入 conflict candidate，等待人工裁决 |
-| 仅追加 evidence、last_referenced 或 contributors | 可自动合并 |
-
-自动化只能产生候选，不应静默提升到 `proven` 或删除知识条目。成熟度变更必须在 trace 的 `archive_summary.maturity_changes` 或归档报告中留下证据。
-
-团队知识库引入后，角色边界如下：
-
-| 角色 | 项目知识权限 | 团队知识权限 |
-| --- | --- | --- |
-| `maintainer` | 可审批归档、衰减和冲突裁决 | 可审批 proven、合并冲突和维护 `log.md` |
-| `contributor` | 可新增 draft、追加 evidence、输出候选 | 可写入 `contributions/pending/` |
-| `reader` | 可读取并引用知识 | 只读，不写团队仓库 |
-
-## 条目格式
-
-每条知识使用 Markdown 文件，文件名推荐：
-
-```text
-<TYPE>-<AREA>-<NNN>.md
-```
-
-条目头部使用 YAML frontmatter：
-
-```markdown
----
-id: GUIDELINE-HARNESS-001
-type: guideline
-maturity: draft
-tags: [harness, rules, context]
-applicable_phases: [analysis, plan, implement, archive]
-source_references:
-  - traces/<task-id>-<timestamp>.json
-last_referenced:
-contributors:
-  - codex
-evidence:
-  contributors:
-    - name: codex
-      source_ref: traces/<task-id>-<timestamp>.json
-  validated_projects: []
-  contradictions: []
----
-
-# 标题
-
-## Context
-
-这条知识成立的背景。
-
-## Guidance
-
-可执行的规则、判断或流程。
-
-## Evidence
-
-验证命令、trace、review finding 或失败记录。
-```
-
-## 渐进式查询
-
-Codex 会话按三层读取：
-
-1. 读 `docs/knowledge/knowledge-catalog.md`，判断有哪些分类和阶段推荐入口。
-2. 读 `docs/knowledge/catalog.md`，按 `tags`、`type`、`applicable_phases` 过滤候选条目。
-3. 只读取和当前任务直接相关的完整条目。
-
-任务可通过 `knowledge_query_budget` 限制读取量：
-
-```json
-{
-  "knowledge_query_budget": {
-    "catalogs": 2,
-    "entries": 5
-  }
-}
-```
-
-## Trace 集成
-
-任务使用知识后，应在最终报告或 trace 中留下：
-
-```json
-{
-  "knowledge_references": [
-    {
-      "id": "GUIDELINE-HARNESS-001",
-      "title": "规则必须配替代方案",
-      "used_in": "Stage 1 review"
-    }
-  ]
-}
-```
-
-归档任务读取 `knowledge_references` 后，可以更新 `last_referenced`、提升成熟度，或标记冲突。
-
-归档任务还应输出以下候选清单，供维护者或后续 lint 任务处理：
-
-- promotion candidates：可提升成熟度或提升到团队知识库的条目。
-- decay candidates：长期未引用、上下文疑似过时的条目。
-- conflict candidates：同一主题存在相反结论或适用条件冲突。
-- merge candidates：重复或高度相似条目。
-
-## 归档策略
-
-`ARCHIVE-*` 任务只做知识沉淀和索引维护，不重新定义需求范围。归档输入包括：
-
-- 当前任务 trace
-- `progress.txt`
-- Stage 1 / Stage 2 review 输出
-- failure triage
-- changed files
-- 验证命令输出
-
-归档输出包括：
-
-- 新增或更新的知识条目
-- 更新后的 `knowledge-catalog.md`
-- 更新后的 `catalog.md`
-- trace 中的 `archive_summary`
-
-归档阶段缺失不应阻塞代码验证，但会降低后续任务复用历史经验的能力。
-
-## 相关流程
-
-- 冷启动导入：`docs/harness/knowledge-import.md`
-- 知识健康检查：`docs/harness/knowledge-lint.md`
-- 团队知识同步：`docs/harness/team-knowledge-sync.md`

package/package-source/docs/codex-harness-engineering/templates/docs/knowledge-import.md

@@ -1,108 +0,0 @@
-# Knowledge Import
-
-本文定义历史项目或既有项目接入 Harness 时的知识冷启动流程。目标是把散落在代码、文档、issue、review 和口头经验里的隐性知识转成 `docs/knowledge/` 的 draft 条目。
-
-## 原则
-
-- 不追求一次导入完美；冷启动条目默认 `maturity: draft`。
-- 优先提取会影响后续实现决策的知识，而不是搬运完整文档。
-- 每条知识都必须有 `source_references`，可以追溯到代码路径、文档、issue、review 或人工访谈记录。
-- 单次导入建议控制在 5-13 条高价值条目，避免知识库第一天就膨胀。
-- 导入阶段只建立候选知识，不把规则直接升级到 `AGENTS.md`。
-
-## 输入来源
-
-| 来源 | 可提取内容 |
-| --- | --- |
-| README / docs | 项目边界、运行方式、架构说明、业务流程 |
-| 代码结构 | 模块边界、核心实体、数据流、依赖关系 |
-| 测试与 CI | 验证入口、风险路径、质量门禁 |
-| issue / PR / review | 反复出现的 pitfall、约束和决策原因 |
-| trace / failure triage | 已验证失败模式和排查路径 |
-| 团队访谈 | AI 无法从代码推断的私域经验 |
-
-## 三段式导入
-
-1. `doc-collector`：收集已有文档、README、测试说明、CI、issue 或人工访谈摘要。
-2. `codebase-profiler`：扫描代码结构、技术栈、模块边界、入口命令和关键依赖。
-3. `knowledge-builder`：按 `model / decision / guideline / pitfall / process` 标准化条目，写入 `docs/knowledge/` 并更新索引。
-
-## 输出要求
-
-- `docs/knowledge/catalog.md` 增加一行摘要。
-- 新条目写入对应目录，初始 `maturity: draft`。
-- 每条条目包含 `source_references` 和 `contributors`。
-- 导入报告说明未处理来源、低置信条目和后续验证建议。
-
-## 断点恢复
-
-冷启动导入可能跨多轮扫描。导入任务应在 `docs/knowledge/import-state.json` 或导入报告中记录可恢复状态，避免中断后重复处理同一批来源。
-
-推荐最小结构：
-
-```json
-{
-  "schema_version": "1",
-  "started_at": "2026-05-12T00:00:00+08:00",
-  "updated_at": "2026-05-12T00:00:00+08:00",
-  "sources": {
-    "processed": [],
-    "pending": [],
-    "skipped": [],
-    "low_confidence": []
-  },
-  "resume_cursor": {
-    "source": "",
-    "path": "",
-    "position": ""
-  },
-  "generated_entries": [],
-  "follow_up_verification": []
-}
-```
-
-`import-state.json` 只描述导入进度，不替代知识条目的 `source_references`。如果项目不希望长期保留该文件，可在导入完成后把同等信息写入导入报告，但必须保留未处理来源和低置信候选。
-
-## 任务模板片段
-
-需要加入 `task.json` 时，可复制并按项目裁剪：
-
-```json
-{
-  "id": "KNOWLEDGE-IMPORT-001",
-  "description": "从既有代码、文档和历史记录冷启动 docs/knowledge 项目知识库",
-  "task_kind": "archive",
-  "phase": "archive",
-  "gate_profile": "lightweight",
-  "required_truth_sources": ["repo_context"],
-  "priority": 5,
-  "dependencies": ["INIT-001"],
-  "passes": false,
-  "context_files": [
-    "AGENTS.md",
-    "README.md",
-    "docs/harness/knowledge-architecture.md",
-    "docs/harness/knowledge-import.md"
-  ],
-  "owned_paths": ["docs/knowledge/"],
-  "execution": { "mode": "single" },
-  "knowledge_query_budget": {
-    "catalogs": 2,
-    "entries": 5
-  },
-  "steps": [
-    "扫描 README、docs、测试入口、CI 和核心代码结构",
-    "维护 import-state.json 或导入报告，记录 processed/pending/skipped/low_confidence 来源和 resume_cursor",
-    "提取 5-13 条高价值 draft 知识，按 model/decision/guideline/pitfall/process 分类",
-    "更新 knowledge-catalog.md 和 catalog.md",
-    "输出导入报告，列出低置信来源和后续验证建议"
-  ],
-  "test_command": "git diff --check",
-  "acceptance": [
-    "新增条目均为 draft 且带 source_references",
-    "catalog 与新增条目一致",
-    "导入状态或报告能支持断点恢复，未处理来源没有丢失",
-    "没有把冷启动条目直接升级为 AGENTS.md 规则"
-  ]
-}
-```