@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/AGENTS.md

@@ -1,57 +1,48 @@
-# AGENTS.md
-
-本文件只保留每次会话都必须知道的 Harness 入口规则。细节按需读取下方深文档，不把长期协议全部塞进入口文件。
-
-## 核心入口
-
-- 本仓库默认采用 `driver-first`：真实任务进入 `task.json`，由 `tools/harness/codex-loop.ps1` 逐个执行。
-- `single task` 是当前唯一自动执行模式；每轮 driver 只处理一个 `passes: false` 且依赖已通过的任务。
-- 交互开发模式只负责需求收敛、分析、规划和任务输入；方案确认后，默认回到 `task.json -> tools/harness/codex-loop.ps1`。
-- 主控会话不直接维护仓库状态文件；`task.json`、`progress.txt`、`traces/` 和 Git 提交由 runtime 链路推进。
-- 需要落盘规则、任务、文档、前端、后端或测试内容时，先确认 truth source，再委派匹配的 writer 子代理或进入 driver 任务。
-
-## 硬约束
-
-- 启动前 Git 工作区必须干净，除非用户明确说明哪些改动属于本任务；可再生运行产物只能通过 `runtime.git.non_blocking_dirty_paths` 列白名单。
-- 不要伪造完成状态：不得手工把未验证任务标记为 `passes: true`，不得绕过 `test_command`、review gate 或 commit gate。
-- 不要删除或改写已有任务描述，除非用户明确要求替换模板示例或重建任务队列。
-- 修改后必须运行与改动直接对应的验证；文档改动至少运行 `git diff --check`。
-- 测试范围从需求收敛阶段开始定义；P0/P1 需求进入实现前必须有可追溯验收、测试数据和证据路径。
-- 外部系统、开源栈、第三方平台或真实环境集成需求，完成声明必须包含真实依赖接入、成功态证据和失败态证据。
-- 进入实现前必须有当前项目声明的架构约束 truth source，默认路径为 `docs/architecture/constraints.md`，也可由 `task.json.runtime.handoff.truth_sources.architecture` 指向其他路径。
-- `feature_impl` 任务必须携带可执行的 `architecture_constraints`、`forbidden_implementations` 和对应验证命令；禁止用测试替身、local-only adapter 或领域原型冒充任务声明的交付路径。
-- Stage 1 Review 先审声明的架构约束符合性，再审业务规格；仅当任务要求架构门禁且约束缺失或实现冲突时 FAIL。
-- 阻塞时追加 `progress.txt`，输出 `BLOCKED - 需要人工介入`，然后停止。
-
-## 阶段更新规则
-
-- Stage 01 初始化：更新 `task.json`、`AGENTS.md`、项目路径和验证命令。
-- Stage 02 需求收敛：更新 `docs/product/`、Requirement IDs、验收标准和可执行验收示例。
-- Stage 03 追溯与架构约束：更新架构约束 truth source、测试追溯矩阵和证据协议。
-- Stage 09 DEV-PLAN / 任务拆分：把架构约束、禁止实现和验证命令写入每个相关 `feature_impl`。
-- Stage 10-14 实现与集成：只更新任务 owned paths 内的实现、测试和证据。
-- Stage 15-16 Review：保持只读审查，输出 findings、证据和 repair queue。
-- Stage 17 Verify / Regression：刷新验证证据，不在本阶段第一次补需求或测试范围。
-- Archive：更新 `docs/knowledge/`、索引和可复用经验，不升级一次性结论为全局规则。
-
-## 必读索引
-
-- Harness 分层分析索引：`harness-analysis/README.md`
-- Codex Harness Engineering 总览：`docs/codex-harness-engineering/README.md`
-- Codex 宿主自动加载机制：`docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
-- Codex 自动加载优化清单：`harness-analysis/10-codex-autoload-optimization-checklist.md`
-- Harness 架构：`docs/harness/architecture.md`
-- 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
-- 新项目使用：`docs/harness/new-project-usage.md`
-- Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
-- 规则治理与 AGENTS.md 分层：`docs/harness/rule-governance.md`
-- 回归与验证策略：`docs/harness/regression-rules.md`
-- Trace 格式：`docs/harness/trace-format.md`
-- 权限策略：`docs/harness/sandbox-policy.md`
-- Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`
-
-## 当前在做的事情
-
-- 正在持续分析当前仓库里的 Codex 宿主层、Harness 控制层、安装工程和桥接层。
-- 当前重点是把“哪些内容会被 Codex 自动加载到上下文、哪些只是运行配置、哪些是 Harness runtime 二次读取”彻底拆清。
-- 所有新增分析文档统一落在 `harness-analysis/`，方法论和模板级说明补充到 `docs/codex-harness-engineering/`。
+## 模板优先
+
+- 需要影响新项目 bootstrap、生成物结构、默认导航层、默认 prompt、默认规则、默认技能、默认上下文模板时，先修改模板 canonical：
+  - `docs/codex-harness-engineering/templates/`
+  - `tools/harness/templates/`
+  - `docs/codex-harness-engineering/templates/package-assets/`
+- 当前仓库根目录下的活跃文档或脚本，只在它本身就是 canonical，或为了验证模板落地效果、保持当前仓库可运行时再同步修改。
+- 如果一次改动同时涉及根目录活跃文件和模板文件，优先说明哪一份是 canonical，避免只修当前仓库、不修模板源。
+
+## 目录级规则
+
+- 当某个目录满足以下任一条件时，应优先考虑新增或更新该目录下的 `AGENTS.md`，而不是继续扩充根入口：
+  - 目录有独立模块职责或技术栈
+  - 目录存在与全仓不同的架构边界
+  - 目录有独立入口文件、测试命令或验证方式
+  - 目录反复出现相同 review 问题、坑点或禁止事项
+- 子目录 `AGENTS.md` 应重点写：
+  - 该目录负责什么 / 不负责什么
+  - 入口文件和核心文件
+  - 修改前必须先看的文件
+  - 本目录的局部架构规则和复用模式
+  - 测试 / 构建 / 验证命令
+  - 常见坑和禁止事项
+- `docs/ai/repo-map.md` 及模板中的 repo-map 应维护“子目录规则索引”，明确哪些路径已有本地规则、适用于什么场景。
+
+## 必读索引
+
+如果当前仓库是 thin install 项目，而下面列出的 `docs/harness/*` 或 `docs/knowledge/*` 不在项目根，先读取 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下查同路径文件。
+
+- Harness 分层分析索引：`harness-analysis/README.md`
+- Codex Harness Engineering 总览：`docs/codex-harness-engineering/README.md`
+- Codex 宿主自动加载机制：`docs/codex-harness-engineering/codex-host-runtime-and-autoload.md`
+- Codex 自动加载优化清单：`harness-analysis/10-codex-autoload-optimization-checklist.md`
+- Harness 架构：`docs/harness/architecture.md`
+- 架构约束包：`docs/architecture/constraints.md` 或 `task.json.runtime.handoff.truth_sources.architecture`
+- 新项目使用：`docs/harness/new-project-usage.md`
+- Task 会话与 `task.json` 细则：`docs/harness/task-session-strategy.md`
+- 规则治理与 AGENTS.md 分层：`docs/harness/rule-governance.md`
+- 回归与验证策略：`docs/harness/regression-rules.md`
+- Trace 格式：`docs/harness/trace-format.md`
+- 权限策略：`docs/harness/sandbox-policy.md`
+- Prompt 与知识集成：`docs/harness/prompt-knowledge-integration.md`
+
+## 当前在做的事情
+
+- 正在持续分析当前仓库里的 Codex 宿主层、Harness 控制层、安装工程和桥接层。
+- 当前重点是把“哪些内容会被 Codex 自动加载到上下文、哪些只是运行配置、哪些是 Harness runtime 二次读取”彻底拆清。
+- 所有新增分析文档统一落在 `harness-analysis/`，方法论和模板级说明补充到 `docs/codex-harness-engineering/`。

package/package-source/PACKAGE.md

@@ -2,12 +2,12 @@
 
 ## Mode Policy
 
-当前包默认使用 thin project 安装语义：无 `-Mode` / `-Scope` 时，`tools/install/install-agent.ps1 -ProjectRoot .` 等价于 `-Scope project`，初始化项目运行必需的 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/` 和 `tools/`。
+当前包默认使用 thin project 安装语义：无 `-Mode` / `-Scope` 时，`tools/install/install-agent.ps1 -ProjectRoot .` 等价于 `-Scope project`，初始化项目运行必需的 runtime、项目级 `.agents/` active surface、`.codex/`、`.codex-harness/`、`docs/ai/`、`docs/architecture/`、`docs/spec/` 和 `tools/`。
 
 保留的入口：
 
-- `-Scope project`：新默认 thin project 入口，保留瘦的项目级 `.agents/skills/`、`.agents/workflows/`，不复制完整 vendor 镜像、legacy docs 或 package template source。
-- `-Scope user`：只安装用户级 codex-harness package source 和用户级 package lock，不暴露全局 `.agents/skills/` / `.agents/workflows/`。
+- `-Scope project`：新默认 thin project 入口，保留瘦的项目级 `.agents/skills/`、`.agents/workflows/`，不复制完整 vendor 镜像、legacy docs 或 package template source。
+- `-Scope user`：只安装用户级 codex-harness package source 和用户级 package lock，不暴露全局 `.agents/skills/` / `.agents/workflows/`。
 - `-Scope vendor`：显式 vendor 入口，只复制项目内 `.agents/` vendor 包，适合离线或强隔离项目。
 - `-Mode full`：显式 legacy full 兼容入口，同时输出项目 runtime、完整 `.agents/` vendor 包和 legacy docs。
 - `-Mode project|vendor|user`：保留旧兼容入口；新项目优先使用 `-Scope user|project|vendor`。
@@ -19,25 +19,25 @@
 新项目默认安装：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
 ```
 
 显式 thin project：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope project
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope project
 ```
 
 显式 legacy full：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
 ```
 
 显式 vendor：
 
 ```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope vendor
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Scope vendor
 ```
 
 ## Smoke

package/package-source/README.md

@@ -1,81 +1,85 @@
-# Codex Harness Agent Package
-
-本包默认使用方案 A 的极简根目录布局。安装后目标项目使用 `task.json + tools/harness/codex-loop.ps1` 作为自动执行入口，driver 负责选择任务、运行验证、写 trace、更新进度和提交结果。
-
-SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。
-
-## 云端 CLI 安装
-
-全局安装：
-
-```powershell
-npm install -g @pzy560117/codex-harness
-```
-
-一次性使用：
-
-```powershell
-npx @pzy560117/codex-harness init
-```
-
-项目内常用命令：
-
-```powershell
-harness init
-harness doctor
-harness verify
-harness run
-```
-
-`harness init` 优先使用 npm 包内置的 `package-source/` 完成初始化；只有在 npm 包未携带内置 source 时，才回退到 GitHub Release 下载 package source 到 `%USERPROFILE%\.codex\packages\codex-harness\<version>\`。项目级 `.agents/skills/` 与 `.agents/workflows/` 仍只安装到当前项目，不会提升成全局 active surface。
-
-## 本地源码安装
-
-从包含 `agent/` 包目录的项目父目录运行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
-```
-
-从已安装的 `.agents/` 自更新：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
-```
-
-## 安装产物
-
-- 项目根 `AGENTS.md`
-- `tools/harness/` 下的 `codex-loop.ps1`、`doctor.ps1`、`verify.ps1`
-- `tools/install/` 下的 `bootstrap-codex-harness.ps1`、`env-check.ps1`、安装脚本
-- 项目根 `task.json`、`progress.txt`
-- `tools/harness/templates/` 下的 `smoke-task.json`、`project-task-template.json`
-- `docs/harness/trace.schema.json`
-- 项目根 `.codex/`
-- 项目根 `docs/harness/`、`docs/testing/`
-- 项目根 `.agents/` 完整能力包，包括 rules、skills、workflows、`.specify/` 和模板复制源
-
-## 使用顺序
-
-1. 读取项目根 `AGENTS.md`。
-2. 用 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*` 收敛项目上下文。
-3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
-4. 将确认后的任务写入 `task.json`。
-5. 运行：
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1
-```
-
-## 验证安装包
-
-```powershell
-powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1
-```
-
-发布产物会输出到 `dist/release/<version>/`，包含：
-
-- `codex-harness-<version>-win.zip`
-- `codex-harness-<version>-win.sha256`
-- `release-manifest.json`
+# Codex Harness Agent Package
+
+本包默认使用方案 A 的极简根目录布局。安装后目标项目使用 `task.json + tools/harness/codex-loop.ps1` 作为自动执行入口，driver 负责选择任务、运行验证、写 trace、更新进度和提交结果。
+
+SpecKit 相关 `.specify/`、`workflows/speckit.*` 和 `speckit-*` skills 仍随 full 包安装，但它们用于需求、计划和任务输入生成；方案确认后应转入 `task.json`，再交给 full driver 执行。
+
+## 云端 CLI 安装
+
+全局安装：
+
+```powershell
+npm install -g @pzy560117/codex-harness
+```
+
+一次性使用：
+
+```powershell
+npx @pzy560117/codex-harness init
+```
+
+项目内常用命令：
+
+```powershell
+harness init
+harness doctor
+harness verify
+harness run
+```
+
+`harness init` 优先使用 npm 包内置的 `package-source/` 完成初始化；只有在 npm 包未携带内置 source 时，才回退到 GitHub Release 下载 package source 到 `%USERPROFILE%\.codex\packages\codex-harness\<version>\`。项目级 `.agents/skills/` 与 `.agents/workflows/` 仍只安装到当前项目，不会提升成全局 active surface。
+
+## 本地源码安装
+
+从包含 `agent/` 包目录的项目父目录运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent-here.ps1 -InitGitIfNeeded
+```
+
+从已安装的 `.agents/` 自更新：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\install\install-agent.ps1 -ProjectRoot . -Mode full -Force
+```
+
+## 安装产物
+
+- 项目根 `AGENTS.md`
+- `tools/harness/` 下的 `codex-loop.ps1`、`doctor.ps1`、`verify.ps1`
+- `tools/install/` 下的 `bootstrap-codex-harness.ps1`、`env-check.ps1`、安装脚本
+- 项目根 `task.json`、`progress.txt`
+- `tools/harness/templates/` 下的 `smoke-task.json`、`project-task-template.json`
+- `docs/harness/trace.schema.json`
+- 项目根 `.codex/`
+- 项目根 `.agents/` active surface，包括 skills、workflows 和安装后需要的运行辅助面
+
+说明：
+
+- 默认 `thin project` 安装不会把 `docs/harness/`、`docs/testing/`、`docs/knowledge/` 整包复制到项目根。
+- 这些深文档默认位于 `.codex-harness/state/config.json` 里的 `packageRoot` 下；只有显式 `-Mode full` / legacy full 场景才会在项目根保留完整副本。
+
+## 使用顺序
+
+1. 读取项目根 `AGENTS.md`。
+2. 如果项目根存在 `docs/harness/new-project-usage.md`、`docs/harness/architecture.md` 和 `docs/testing/*`，直接读取；若是 thin project 且这些文件缺失，则先读 `.codex-harness/state/config.json`，再到其中 `packageRoot` 下读取同路径文件。
+3. 必要时使用 SpecKit workflow 生成 spec / plan / tasks 输入。
+4. 将确认后的任务写入 `task.json`。
+5. 运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\verify.ps1
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\harness\codex-loop.ps1
+```
+
+## 验证安装包
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\release\build-release.ps1
+```
+
+发布产物会输出到 `dist/release/<version>/`，包含：
+
+- `codex-harness-<version>-win.zip`
+- `codex-harness-<version>-win.sha256`
+- `release-manifest.json`

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

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+## 作用范围
+
+- 本文件适用于 `docs/codex-harness-engineering/templates/` 整个模板树。
+- 进入子目录后，继续读取该子目录自己的 `AGENTS.md`。
+
+## 目录作用
+
+- 这里是当前仓库最重要的模板 canonical 源。
+- 影响 bootstrap、driver、docs、rules、prompt、truth source、package-assets 的改动，默认都先发生在这里。
+
+## 结构索引
+
+- `README.md`：模板目录总览。
+- `bootstrap-codex-harness.ps1`：模板安装 / 复制主入口。
+- `ci/`：CI 工作流模板。
+- `config/`：配置示例、rules、agent 定义。
+- `context/`：`docs/ai/*` 和计划上下文模板。
+- `contracts/`：契约优先模板。
+- `design/`：前端设计与图转前端规格模板。
+- `docs/`：会复制到 `docs/harness/` 的说明文档模板。
+- `governance/`：治理策略、风险分级、保护清单。
+- `hooks/`：hook 模板。
+- `knowledge/`：知识层模板。
+- `package-assets/`：镜像到目标项目 `.agents/` 或相关文档面的资产。
+- `product/`：产品预研 / 测试左移素材模板。
+- `prompts/`：driver、review、worker prompt 模板。
+- `runtime/`：driver、task、verify、doctor 等运行面模板。
+- `scripts/`：辅助脚本模板。
+- `spec/`：默认 `docs/spec/*` 规格模板。
+- `testing/`：测试真相源模板。
+- `tools/`：内容门禁脚本模板。
+- `trace/`：trace schema 和样例。
+
+## 特殊说明
+
+- `runtime/AGENTS.md` 已经是“安装到目标项目根目录的 AGENTS 模板内容”，不要把它改造成目录级导航文件。
+- `config/global-AGENTS.md` 是全局规则示例，不是本目录本地规则。
+
+## 修改前先看
+
+- `README.md`
+- `bootstrap-codex-harness.ps1`
+- `../doc-update-map.md`
+
+## 修改规则
+
+- 改动模板时，优先确认是否还需要同步当前仓库活跃副本、`tools/install/bootstrap-codex-harness.ps1`、`docs/harness/*` 或 package-assets 镜像。
+- 不要只修某个镜像副本而漏掉模板 canonical。
+- 如果一个目录已经有交付用同名文件（例如 `runtime/AGENTS.md`），目录规则写在上级 `AGENTS.md`，不要覆写交付模板。

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

@@ -1,20 +1,21 @@
-# Templates README
-
-当前模板集只保留单工作区、单 driver 的最小闭环。
-
-## 主要目录
-
-- `runtime/`: 项目根运行入口、driver、doctor、任务队列、运行策略、验证脚本
-- `config/`: 全局与项目级配置示例
-- `docs/`: 会复制到项目 `docs/harness/` 的文档模板，也包含 `project-agents-template.md` 这种按项目事实生成 `AGENTS.md` 的通用规则模板
-- `design/`: 前端先行链路的设计 brief、图转前端规格、组件映射、状态矩阵、视觉评审、前端架构和 design tokens 模板
-- `testing/`: 测试左移模板，包含验收标准、验收示例、追溯矩阵、测试数据、回归计划、失败归因和 verify 矩阵
-- `prompts/`: driver、review、visual、failure、repair 使用的提示词模板
-- `trace/`: trace 与 schema 示例
-- `package-assets/`: 会复制到目标项目 `.agents/` 的能力包与安装入口镜像
-
-已移除：
-
-- 额外执行工作区脚本
-- 外部 worker 编排模板
-- 控制面状态模板
+# Templates README
+
+当前模板集只保留单工作区、单 driver 的最小闭环。
+
+## 主要目录
+
+- `runtime/`: 项目根运行入口、driver、doctor、任务队列、运行策略、验证脚本
+- `config/`: 全局与项目级配置示例
+- `docs/`: 会复制到项目 `docs/harness/` 的文档模板，也包含 `project-agents-template.md` 这种按项目事实生成 `AGENTS.md` 的通用规则模板
+- `tools/`: 会复制到项目 `tools/harness/` 的内容级门禁脚本模板，例如 spec/context/architecture/directory/style/session/docs/data/integration/mobile/acceptance lint
+- `design/`: 前端先行链路的设计 brief、图转前端规格、组件映射、状态矩阵、视觉评审、前端架构和 design tokens 模板
+- `testing/`: 测试左移模板，包含验收标准、验收示例、追溯矩阵、测试数据、回归计划、失败归因和 verify 矩阵
+- `prompts/`: driver、review、visual、failure、repair 使用的提示词模板
+- `trace/`: trace 与 schema 示例
+- `package-assets/`: 会复制到目标项目 `.agents/` 的能力包与安装入口镜像
+
+已移除：
+
+- 额外执行工作区脚本
+- 外部 worker 编排模板
+- 控制面状态模板