@pzy560117/codex-harness 0.1.0 → 0.1.2

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

@@ -0,0 +1,98 @@
+# Knowledge Lint
+
+本文定义 `docs/knowledge/` 的健康检查规则。目标是让知识库保持可检索、可追踪、不过期，而不是只进不出。
+
+## 触发时机
+
+- 每完成 10 个 driver 任务后建议运行一次。
+- 连续 30 天未运行 knowledge lint 时，下次 `ARCHIVE-*` 或项目维护任务应提醒补跑。
+- 每次较大 harness、规则、prompt 或模板改造后运行一次。
+- `ARCHIVE-*` 发现重复、矛盾、长期未引用条目时运行一次。
+- 手动维护知识库前后运行一次。
+
+## 检查项
+
+| 检查 | 规则 | 处理 |
+| --- | --- | --- |
+| 索引一致 | `knowledge-catalog.md`、`catalog.md` 必须覆盖实际条目 | 修复索引 |
+| 孤儿条目 | 条目不在任何 catalog 中出现 | 加入索引或移入 archive |
+| 路径失效 | catalog 指向不存在文件 | 修复路径或删除索引行 |
+| 重复条目 | 标题、tags、source_references 高度重叠 | 标记 merge candidate |
+| 矛盾条目 | 同主题出现相反指导 | 标记 conflict candidate |
+| 长期未引用 | `last_referenced` 为空或超过衰减窗口 | 标记 decay candidate |
+| 成熟度越权 | 单次来源直接为 `proven` | 降级并补 evidence |
+| 团队同步候选 | verified/proven 条目具备跨项目价值 | 输出 team sync candidate |
+| 团队冲突候选 | 项目事实与团队知识相反 | 输出 team conflict candidate |
+| frontmatter 缺失 | 缺少 `id/type/maturity/tags/applicable_phases/source_references` | 补齐元数据 |
+
+## 最小执行流程
+
+1. 读取 `docs/harness/knowledge-architecture.md`。
+2. 枚举 `docs/knowledge/` 下除 `archive/` 外的条目。
+3. 对照 `docs/knowledge/catalog.md` 检查索引完整性。
+4. 检查每条 frontmatter、路径、成熟度和引用信息。
+5. 输出 lint report，列出 `fix_now`、`promotion_candidates`、`decay_candidates`、`conflict_candidates`、`merge_candidates`、`team_sync_candidates`。
+6. 只自动修复索引、路径和明显元数据缺口；成熟度提升、冲突裁决、团队知识合并和删除归档必须保留人工确认或独立任务证据。
+
+## 报告格式
+
+```markdown
+# Knowledge Lint Report
+
+## Summary
+- Entries scanned:
+- Catalog mismatches:
+- Fixes applied:
+- Candidates:
+
+## Fix Now
+- ...
+
+## Promotion Candidates
+- ...
+
+## Decay Candidates
+- ...
+
+## Conflict Candidates
+- ...
+
+## Merge Candidates
+- ...
+
+## Team Sync Candidates
+- ...
+```
+
+## 任务模板片段
+
+需要加入 `task.json` 时，可复制并按项目裁剪：
+
+```json
+{
+  "id": "KNOWLEDGE-LINT-001",
+  "description": "检查 docs/knowledge 索引、重复、冲突、成熟度和长期未引用条目",
+  "task_kind": "archive",
+  "phase": "archive",
+  "gate_profile": "lightweight",
+  "required_truth_sources": ["knowledge"],
+  "priority": 95,
+  "dependencies": ["ARCHIVE-001"],
+  "passes": false,
+  "context_files": [
+    "docs/harness/knowledge-architecture.md",
+    "docs/harness/knowledge-lint.md",
+    "docs/harness/team-knowledge-sync.md",
+    "docs/knowledge/knowledge-catalog.md",
+    "docs/knowledge/catalog.md"
+  ],
+  "owned_paths": ["docs/knowledge/"],
+  "execution": { "mode": "single" },
+  "test_command": "git diff --check",
+  "acceptance": [
+    "输出 knowledge lint report",
+    "catalog 与实际条目一致",
+    "成熟度、冲突、团队同步和衰减只产出候选，不静默越权处理"
+  ]
+}
+```

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

@@ -0,0 +1,7 @@
+# 新项目接入检查清单
+
+- [ ] 已执行 `tools/install/bootstrap-codex-harness.ps1`
+- [ ] 已生成真实 `task.json`
+- [ ] 已确认 `.codex/task-run-profile.json`
+- [ ] 已提交 bootstrap 基线
+- [ ] 已验证 `tools/harness/codex-loop.ps1` 与 `tools/harness/verify.ps1`

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

@@ -0,0 +1,152 @@
+# 新项目 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。
+
+```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\\harness/doctor.ps1
+```
+
+## 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/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/`；该同步失败只能降级为候选报告，不能阻塞本地实现验证。
+
+## 4. UI 项目要求
+
+- 保存设计参考图。
+- 保存真实浏览器截图。
+- 输出视觉对比报告。

package/package-source/docs/codex-harness-engineering/templates/docs/project-agents-template.md

@@ -0,0 +1,154 @@
+# Project AGENTS.md Template
+
+本文是生成项目根 `AGENTS.md` 的通用模板，不应原样复制后长期保留占位符。生成时先分析项目事实，再按项目类型裁剪章节。
+
+## 使用原则
+
+- `AGENTS.md` 是给编码 Agent 的入口规则，不是 README 的复刻。
+- 只写会改变 Agent 行为的项目特定信息；通用工程常识、formatter/linter 已覆盖的内容不要写。
+- 根 `AGENTS.md` 保持短入口，建议 60-120 行；细节放到 `docs/`、`rules/`、`specs/` 或测试文档，并在入口索引引用。
+- 每条禁令必须给替代方案；不能说明替代方案的内容先写成风险或待确认项。
+- 可以自动检查的规则优先进入 lint、schema、hook、CI、verify 脚本，不只依赖文字提醒。
+- 规则从 Bad Case 迭代：重复 review 问题、线上事故、新人必踩坑、Agent 反复犯错，才升级为入口规则。
+- `project_doc_fallback_filenames` 只在目录缺少 `AGENTS.md` 时生效；生成了根 `AGENTS.md` 的项目，不要再依赖 fallback 文件作为额外入口。
+- 不用 `developer_instructions` 或 `model_instructions_file` 承载普通项目规则；这些是 config 层上下文入口，默认应保持为空。
+
+## 生成前事实扫描
+
+先收集这些事实，再填模板：
+
+| 事实 | 来源 |
+| --- | --- |
+| 项目类型 | README、目录结构、启动脚本、部署文件 |
+| 技术栈 | `package.json`、`pyproject.toml`、`go.mod`、`pom.xml`、Dockerfile |
+| 常用命令 | scripts、Makefile、CI、现有 docs |
+| 架构边界 | `src/`、`apps/`、`packages/`、`services/`、`docs/architecture*` |
+| 代码地图 | `docs/ai/repo-map.md`、`codemaps/*`、架构索引或模块清单 |
+| 测试入口 | test scripts、`tests/`、Playwright/Cypress/Pytest/Vitest 配置 |
+| 自动化检查 | linter、formatter、typecheck、CI、hooks |
+| 私域知识 | 内部组件库、私有 API、特殊目录、历史迁移约束 |
+| Bad Case | 近期 review、bug 标签、trace、失败复盘、团队反复纠正事项 |
+
+## 根 AGENTS.md 模板
+
+```markdown
+# AGENTS.md
+
+本文件只保留当前项目中每次编码会话都必须知道的规则。更详细的背景、接口、测试和部署说明见下方索引。
+
+## 项目边界
+
+- 项目类型：<应用 / 库 / monorepo / harness / 模板 / 服务端 / 前端 / 全栈>
+- 主要技术栈：<只列非默认且会影响实现选择的技术>
+- 真实入口：<启动、构建、测试、driver 或任务系统入口>
+- 代码地图：`<docs/ai/repo-map.md 或同类导航文件>`；需要理解模块位置时先读它，再进入具体目录。
+- 不要把 README 的业务介绍复制到这里；README 回答“项目是什么”，本文件回答“Agent 怎么改”。
+
+## 常用命令
+
+| 场景 | 命令 | 说明 |
+| --- | --- | --- |
+| 安装 | `<command>` | <必要前提或包管理器> |
+| 开发 | `<command>` | <端口 / 环境变量 / mock 说明> |
+| 测试 | `<command>` | <默认测试范围> |
+| 类型 / lint | `<command>` | <失败时处理方式> |
+| 构建 | `<command>` | <产物路径或限制> |
+
+## 架构与目录规则
+
+| 场景 | 应使用 | 不要使用 |
+| --- | --- | --- |
+| <例如 API 入口> | `<path/helper>` | <禁止路径或绕路方式> |
+| <例如状态管理> | `<existing-pattern>` | <不要引入的新库> |
+| <例如数据访问> | `<repository/service>` | <不要跨层调用> |
+
+## 项目硬约束
+
+- <CRITICAL 规则 1>；替代方案：<明确可执行做法>。
+- <CRITICAL 规则 2>；替代方案：<明确可执行做法>。
+- <安全 / 数据 / 权限 / 迁移 / 发布红线>；替代方案：<明确可执行做法>。
+
+## 测试与完成定义
+
+- 修改 <模块/路径> 后至少运行 `<command>`。
+- 涉及 <API/业务流/权限/支付/外部系统> 时，必须补充 <单元/集成/E2E/契约/真实环境 smoke> 证据。
+- 完成声明必须包含实际运行过的命令和结果；不要只说“应该可以”。
+
+## 工作区与提交
+
+- 开始前检查 `git status --short`；不要覆盖用户未说明的改动。
+- 只修改与当前任务相关的文件。
+- 禁止使用破坏性 Git 命令，除非用户明确要求。
+- 提交前运行与改动匹配的验证命令。
+
+## 深文档索引
+
+- 架构：`<docs/architecture.md>`
+- 代码地图：`<docs/ai/repo-map.md>`
+- API / 契约：`<docs/api.md>`
+- 测试策略：`<docs/testing.md>`
+- 部署 / 运维：`<docs/deploy.md>`
+- 历史坑 / 项目知识：`<docs/knowledge/>`
+```
+
+## 子目录 AGENTS.md 模板
+
+只有 monorepo 或目录规则明显不同时才添加子目录 `AGENTS.md`。子目录规则应比根规则更具体。
+
+````markdown
+# <path> AGENTS.md
+
+## 作用范围
+
+- 本文件只适用于 `<path>/` 下的改动。
+- 根 `AGENTS.md` 仍然有效；本文件只补充或收紧本目录规则。
+
+## 本目录约束
+
+- 技术栈 / 框架：<目录特定信息>
+- 入口文件：<真实入口>
+- 测试命令：<目录级验证命令>
+
+## 决策表
+
+| 场景 | 应使用 | 不要使用 |
+| --- | --- | --- |
+| <场景> | <本目录模式> | <禁止做法> |
+
+## 代码示例
+
+```<language>
+// 3-10 行真实项目代码，展示应该复用的模式
+```
+````
+
+## CLAUDE.md 组合模板
+
+仅当团队主要使用 Claude Code 且需要 Claude 专属能力时添加。通用规则仍放 `AGENTS.md`。
+
+```markdown
+# CLAUDE.md
+
+@AGENTS.md
+
+## Claude Code 专属规则
+
+- 使用 hooks / commands / memory 的项目约定：<只写 Claude Code 独有内容>。
+- 个人本地偏好放 `CLAUDE.local.md`，不要提交。
+- 不要在这里重复 `AGENTS.md` 已有规则。
+```
+
+## 裁剪检查
+
+生成后逐条检查：
+
+| 检查项 | 处理 |
+| --- | --- |
+| 是否超过 120 行 | 下沉细节到深文档，只保留索引 |
+| 是否复制 README 项目介绍 | 删除，改为 README 链接 |
+| 是否包含通用编码常识 | 删除 |
+| 是否缺少代码地图入口 | 新增 `docs/ai/repo-map.md` 或说明为什么项目太小不需要 |
+| 禁令是否没有替代方案 | 补替代方案或降级为风险 |
+| 是否引用不存在的命令或路径 | 修正或删除 |
+| 自动化可检查的内容是否只写文字 | 补充脚本 / hook / CI / verify 入口 |
+| 深文档是否无法从入口发现 | 加入索引 |

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

@@ -0,0 +1,89 @@
+# Prompt Knowledge Integration
+
+本文定义 `.codex/prompts/*` 如何消费 `docs/harness/*` 和 `docs/knowledge/*`，确保知识沉淀不只停留在文档里，而是进入实现、审查、修复和归档链路。
+
+## 目标
+
+- 每个执行角色都知道何时读取知识目录。
+- 每个输出角色都能记录 `knowledge_references` 和 `knowledge_outputs`。
+- review 能检查知识是否被使用、是否被误用。
+- failure triage、repair 和 visual review 能把坏例转成可归档建议。
+- harness writer 和 docs worker 能按规则治理协议决定内容写到哪里。
+
+## Prompt 覆盖矩阵
+
+| Prompt | 知识消费 | 知识产出 |
+| --- | --- | --- |
+| `controller-loop.md` | 判断任务是否需要注入 `docs/knowledge/` 和规则治理上下文 | 决定是否进入 `ARCHIVE-*` |
+| `implement-one-task.md` | 按阶段读取 knowledge catalog 和相关条目 | 输出 `Knowledge References` / `Knowledge Outputs` |
+| `review-stage1-spec.md` | 检查 `knowledge` truth source、archive 阶段和规则误升级 | 输出 `knowledge_gap` finding |
+| `review-stage2-quality.md` | 检查代码或文档决策是否引用知识 | 输出 `knowledge_gap` finding |
+| `failure-triage.md` | 读取历史坑辅助归因 | 输出 `knowledgeOutputSuggestions` |
+| `repair-one-finding.md` | 读取相关知识，避免重复踩坑 | 输出修复后的知识建议 |
+| `visual-evaluator.md` | 使用设计和视觉相关经验 | 输出视觉 pitfall / guideline 建议 |
+| `harness-audit.md` | 审计 prompt、trace、archive 和 catalog 覆盖 | 输出 Knowledge Gaps |
+| `worker-role/harness-writer.md` | 读取知识架构和规则治理 | 同步 prompt/docs/knowledge mirrors |
+| `worker-role/docs-worker.md` | 判断长期文档与临时讨论边界 | 把可复用经验写入 `docs/knowledge/` |
+| `worker-role/frontend-worker.md` | 读取 UI/视觉/组件经验 | 输出前端知识引用和新坑建议 |
+| `worker-role/backend-worker.md` | 读取架构、安全、API 风险经验 | 输出后端知识引用和新坑建议 |
+| `worker-role/test-runner.md` | 读取历史测试/环境坑 | 输出失败模式归档建议 |
+
+## 阶段查询矩阵
+
+实现会话不应一次性读取全部知识。先读 `knowledge-catalog.md`，再按阶段和任务类型选择 catalog 与少量完整条目。
+
+| 阶段 | 查询重点 | 优先知识类型 | 默认用途 |
+| --- | --- | --- | --- |
+| `analysis` / 产品分析 | 业务实体、历史需求、流程和已知坑 | `model`、`process`、`pitfall` | 补齐需求边界、异常流和术语 |
+| `plan` / 技术分析 | 既有架构决策、禁止做法、失败模式 | `decision`、`guideline(avoid)`、`pitfall` | 避免重复推导和重复踩坑 |
+| `design` / 架构设计 | 实体关系、模块边界、历史决策 | `model`、`decision` | 保持设计与已有约束一致 |
+| `implement` | 编码实践、团队约定、风险路径 | `guideline`、`pitfall` | 指导实现细节和边界处理 |
+| `verify` / release | 回归风险、环境坑、禁止做法 | `pitfall`、`guideline(avoid)` | 选择 affected tests 和失败排查路径 |
+| `archive` | 本轮引用、产出、冲突和可提升条目 | 全部类型 | 更新 `last_referenced`、输出 promotion/decay/conflict/merge candidates |
+
+每个阶段只读取和当前任务直接相关的条目。`draft` 条目可以启发分析，但不能成为阻塞性 review 依据；`proven` 条目才适合升级为规则、模板或 prompt。
+
+## 输出字段约定
+
+实现、修复和 worker handoff 应尽量使用以下 Markdown 字段：
+
+```markdown
+## Knowledge References
+- `id`: title - used_in - `path`
+
+## Knowledge Outputs
+- `suggested-id`: type - title - action - `target-path`
+```
+
+失败归因 JSON 使用：
+
+```json
+{
+  "knowledgeReferences": [],
+  "knowledgeOutputSuggestions": []
+}
+```
+
+driver trace 使用 `docs/harness/trace.schema.json` 中的：
+
+- `knowledge_references`
+- `knowledge_outputs`
+- `archive_summary`
+
+## 使用边界
+
+- `draft` 知识只能作为参考，不应作为阻塞性 review 依据。
+- `verified` 知识可以作为 reviewer 的辅助依据。
+- `proven` 知识才适合升级为规则、模板或 prompt。
+- 单次任务经验不得直接写入 `AGENTS.md`，应先进入 `docs/knowledge/`。
+- prompt 改动后必须同步 `agent/.codex/prompts/`、`docs/codex-harness-engineering/templates/prompts/` 和 `.agents/docs/codex-harness-engineering/templates/prompts/`。
+
+## 维护检查
+
+每次改动 `docs/harness/knowledge-architecture.md`、`docs/harness/rule-governance.md`、`docs/harness/trace.schema.json` 或 `tools/harness/templates/project-task-template.json` 后，检查：
+
+1. `implement-one-task.md` 是否仍要求输出知识引用和知识产出。
+2. Stage 1 / Stage 2 review 是否能检查知识缺口。
+3. failure / repair / visual prompts 是否能把坏例转成归档建议。
+4. worker-role prompts 是否要求读取对应知识文档。
+5. `refresh-agent-package.ps1 -CheckOnly` 是否通过。

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

@@ -0,0 +1,45 @@
+# 回归规则
+
+| 风险 | 约束 |
+| --- | --- |
+| 误改文件 | Git 工作区清洁检查、task 边界、owned paths |
+| 漏测 | 每个任务必须运行 `test_command` |
+| 伪完成 | `passes=true` 必须建立在 fresh evidence 上 |
+| 文档漂移 | 规则、模板、命令改动后同步更新对应文档 |
+
+## 基本要求
+
+- 文档改动至少运行 `git diff --check`。
+- 代码改动必须运行与任务风险匹配的验证命令。
+- 不允许在未验证的情况下手工把任务标记为通过。
+
+## 需求到验证的左移规则
+
+- 测试从需求收敛阶段开始介入，不允许等代码完成后才第一次补测试范围。
+- 任何 P0/P1 需求进入实现前，至少要有 Requirement ID、业务规则、正向示例、异常示例、测试层级映射、测试数据说明和证据路径。
+- 任何 P0/P1 或高风险测试进入脚本实现前，必须先定义测试意图和 Oracle；写操作、权限、状态机、异步链路必须包含副作用或无副作用验证。
+- 创建或重建 `task.json` 时必须一次性补齐完整 QA 合约；后续不得依赖人工逐项补 `requirement_ids`、测试数据、Oracle、开发验证、最终验收验证、证据路径或整链路验证。
+- `docs/testing/TRACEABILITY_MATRIX.md`、验收示例和验证矩阵属于实现前 truth source；缺失时应优先补齐，而不是继续猜测实现。
+- 修改业务代码时必须同时检查测试影响；相关测试缺失时，先补测试骨架或测试计划，再继续实现。
+- Stage 2 必须拦截假测试，包括只断言 200 / truthy、只测 happy path、mock 被测逻辑、缺少业务断言、缺少执行证据或缺少来源绑定的测试。
+
+## 完成定义
+
+- 对外部系统、既定开源栈、第三方平台或真实环境的集成型需求，完成定义至少包含：真实依赖接上、真实请求走通、成功态证据、失败态证据。
+- 页面能打开、本地接口能返回、单元测试通过，都不足以声称正式 `FR-*` 已完成。
+- 每个 `feature_impl` 必须同时具备两段证据：编码过程中的 `development_validation`，以及代码写完后从用户 / 业务闭环视角重新运行的 `acceptance_validation`。
+- 每个 `feature_impl` 至少需要故事级完整链路验收证据；只跑单元测试、局部 smoke、affected tests、静态检查或 `git diff --check` 不足以完成任务。
+- 如果当前只是原型 / spike / exploratory 路径，不要把演示性交付直接标成正式 `FR-*` 完成；应改用 `PROTO-*`、`SPIKE-*`、`INTEGRATION-*` 等单独标识，或在 spec / plan 中显式记录该 FR 仍处于未完成集成态。
+- 单元测试只能证明本地逻辑；集成型需求还必须补环境 smoke、E2E、真实下游连通性验证和验收证据 note。
+- Release 完成必须有发布候选级跨故事整链路、P0/P1 回归、契约/API、E2E/视觉或等价系统级验证；不得把各子任务局部测试简单相加当作整测。
+- Stage 17 只负责 fresh evidence、affected tests 和 P0/P1 回归确认，不负责第一次定义需求测试范围。
+
+## 技术栈验证基线
+
+| 改动类型 | 最小验证 |
+| --- | --- |
+| 文档 | `git diff --check` |
+| JSON | `ConvertFrom-Json` |
+| PowerShell | Parser 语法检查 |
+| TypeScript / 前端 | lint、typecheck、build |
+| API 或业务流程 | 单元测试、集成测试或 E2E，按风险选择 |

package/package-source/docs/codex-harness-engineering/templates/docs/requirement-prep-kit/README.md

@@ -0,0 +1,3 @@
+# Requirement Prep Kit
+
+本目录预留给需求收敛前的访谈、输入清洗、范围确认和验收准备模板。当前默认包不强制使用本目录；项目需要时可以在这里补充团队自己的需求准备表、访谈提纲或任务入口检查表。

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

@@ -0,0 +1,98 @@
+# Harness Rule Governance
+
+本文定义规则如何进入 `AGENTS.md`、深文档、prompt、task template 和自动化检查。目标是控制指令预算，同时让关键约束可执行、可验证、可演进。
+
+## `docs/doc/1.md` 落地结论
+
+`docs/doc/1.md` 的核心价值不是把模板原样搬进本仓库，而是约束规则系统的形态：
+
+- `AGENTS.md` 做短入口，保留每次会话必须遵守的少量硬约束和深文档索引。
+- AI 可以从代码、schema、lint 或脚本推断 / 检查的内容，不进入 `AGENTS.md`。
+- 禁令必须带替代方案；例如不要伪造 `passes=true`，替代方案是让 `tools/harness/codex-loop.ps1` 在验证、review 和 commit gate 通过后写回状态。
+- Bad Case 先进入知识、prompt、role rules 或自动化检查；只有所有会话都必须知道时，才升级到 `AGENTS.md`。
+- 能自动检查的规则应进入 `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema、hook 或同步脚本，不长期只靠文字提醒。
+- 重要深文档必须被 `AGENTS.md` 引用，避免成为孤立文档。
+
+本仓库实践选择：入口文件控制在“读完即可开工”的长度；任务、验证、知识、prompt 和镜像同步细节分别落到 `docs/harness/*`、`.codex/rules/*.md`、`.codex/prompts/*` 和 `agent/` package mirrors。官方自动加载的 `.codex/rules/*.rules` 只承载命令执行策略。
+
+## 分层原则
+
+| 层级 | 放什么 | 不放什么 |
+| --- | --- | --- |
+| `AGENTS.md` | 每次会话都必须遵守的少量硬约束、入口索引 | 长模板、通用编码常识、会频繁变动的细节 |
+| `docs/harness/*` | driver、任务、验证、知识、治理等工程协议 | 具体业务需求 |
+| `.codex/rules/*.rules` | Codex 官方 execpolicy：命令 allow / prompt / forbidden | agent 编排、测试原则、编码风格、项目 instruction |
+| `.codex/rules/*.md` | agent 角色、阶段路由、协作边界等 Harness 语义规则 | 单个功能的临时计划；也不要误写成官方 execpolicy |
+| `.codex/prompts/*` | driver 注入给实现、review、repair 的执行提示 | 人类阅读优先的长说明 |
+| `task.json` | 当前真实任务队列和验证命令 | 模板示例、过期 smoke 占位 |
+
+## 规则进入标准
+
+只有满足以下至少一项，才应新增规则：
+
+- 同类问题在 review、trace 或失败记录中重复出现。
+- 违反后会造成安全、数据、提交、验证或上下文污染风险。
+- AI 无法从代码和现有文档自然推断。
+- 新人或新会话必须知道，否则会走错执行链路。
+
+以下内容默认不写进规则：
+
+- formatter、linter 已经确定性检查的风格细节。
+- “写清晰代码”这类无法改变行为的泛化建议。
+- README 面向人类读者的项目介绍。
+- 没有验证方式的一次性偏好。
+
+## 禁令写法
+
+禁令必须同时给替代方案：
+
+```text
+不要直接改 task.json 来伪造完成状态；应让 tools/harness/codex-loop.ps1 在验证、review 和 commit gate 通过后写回 passes=true。
+```
+
+如果无法给替代方案，先不要写成硬规则，改写成待确认风险或知识条目。
+
+## Bad Case 闭环
+
+每次出现 AI 错误，先判断应该落到哪里：
+
+| 错误类型 | 处理位置 |
+| --- | --- |
+| 单次任务失败 | `progress.txt`、trace、failure triage |
+| 可复用经验 | `docs/knowledge/pitfalls/` 或 `guidelines/` |
+| 会反复影响 driver 行为 | `.codex/prompts/*` 或 `.codex/rules/*.md` |
+| 可确定为命令权限边界 | `.codex/rules/*.rules` |
+| 所有会话必须知道 | `AGENTS.md` |
+| 可以自动检查 | `tools/harness/verify.ps1`、`tools/harness/doctor.ps1`、JSON schema 或 hook |
+
+## 变更流程
+
+1. 先确认触发来源：trace、review finding、失败日志、用户明确要求或文档分析。
+2. 选择最小生效层级，不把深文档内容直接搬进 `AGENTS.md`。
+3. 如果改动影响模板或镜像，按 `harness-surface-sync` 同步 canonical source 和 mirrors。
+4. 运行最小验证：文档至少 `git diff --check`，JSON 需要 `ConvertFrom-Json`，PowerShell 需要 parser 检查。
+5. 提交前确认没有把 token、cookie、私钥、密码写入规则或 trace。
+
+## 定期治理
+
+建议每 10 个 driver 任务或每次较大 harness 改造后执行一次规则治理检查：
+
+- `AGENTS.md` 是否仍保持短入口。
+- 深文档是否有孤立规则没有被入口引用。
+- prompt 是否与 `AGENTS.md`、`.codex/rules/agents.md` 冲突。
+- `.codex/rules/*.rules` 是否仍只包含执行策略，且能通过 `codex execpolicy check`。
+- task template 是否还包含 smoke、示例领域或占位路径。
+- 知识条目是否有重复、过时、矛盾或长期未引用内容。
+
+## AGENTS.md 压缩检查表
+
+调整 `AGENTS.md` 时逐条检查：
+
+| 问题 | 处理 |
+| --- | --- |
+| 这条规则是否每次会话都必须知道？ | 是则保留，否则下沉到深文档 |
+| 这条规则是否已有脚本、schema、lint 或 hook 检查？ | 链接自动化位置，不重复写长说明 |
+| 这条规则是否只是通用工程常识？ | 删除 |
+| 这条规则是否只有禁止项？ | 补充替代方案，否则降级为风险说明 |
+| 这条规则是否源自单次失败？ | 先进入 `docs/knowledge/` 或 trace，不直接升级入口 |
+| 深文档是否在入口可发现？ | 在 `AGENTS.md` 索引补链接 |