@pzy560117/codex-harness 0.1.3 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/root/install-agent-here.ps1

@@ -1,57 +1,57 @@
-param(
-  [ValidateSet("full")]
-  [string]$Mode = "full",
-  [switch]$Force,
-  [switch]$InitSmoke,
-  [switch]$CommitBaseline,
-  [switch]$SkipBaselineCommit,
-  [switch]$InitGitIfNeeded
-)
-
-Set-StrictMode -Version Latest
-$ErrorActionPreference = "Stop"
-
-$packageRoot = $PSScriptRoot
-$projectRoot = Split-Path -Parent $packageRoot
-$installScript = Join-Path $packageRoot "tools/install/install-agent.ps1"
-
-if (-not (Test-Path -LiteralPath $installScript)) {
-  throw "找不到 tools/install/install-agent.ps1: $installScript"
-}
-
-if ([System.IO.Path]::GetFileName($packageRoot) -eq ".agents") {
-  throw "当前脚本位于已安装的 .agents 根目录，不是可移植 agent 包目录。请从独立的 agent/ 包目录运行，或直接调用 tools/install/install-agent.ps1 并显式传入 -ProjectRoot。"
-}
-
-if ([System.IO.Path]::GetFileName($projectRoot) -eq ".agents") {
-  throw "当前脚本位于 .agents/agent 下，这是源包目录，不是目标项目根目录。请改用 tools/install/install-agent.ps1 并显式传入 -ProjectRoot。"
-}
-
-Write-Host "[install-agent-here] Target project root: $projectRoot"
-
-$arguments = @{
-  ProjectRoot = $projectRoot
-  Mode = $Mode
-}
-
-if ($Force.IsPresent) {
-  $arguments["Force"] = $true
-}
-
-if ($InitSmoke.IsPresent) {
-  $arguments["InitSmoke"] = $true
-}
-
-if ($CommitBaseline.IsPresent) {
-  $arguments["CommitBaseline"] = $true
-}
-
-if ($SkipBaselineCommit.IsPresent) {
-  $arguments["SkipBaselineCommit"] = $true
-}
-
-if ($InitGitIfNeeded.IsPresent) {
-  $arguments["InitGitIfNeeded"] = $true
-}
-
-& $installScript @arguments
+param(
+  [ValidateSet("full")]
+  [string]$Mode = "full",
+  [switch]$Force,
+  [switch]$InitSmoke,
+  [switch]$CommitBaseline,
+  [switch]$SkipBaselineCommit,
+  [switch]$InitGitIfNeeded
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$packageRoot = $PSScriptRoot
+$projectRoot = Split-Path -Parent $packageRoot
+$installScript = Join-Path $packageRoot "tools/install/install-agent.ps1"
+
+if (-not (Test-Path -LiteralPath $installScript)) {
+  throw "找不到 tools/install/install-agent.ps1: $installScript"
+}
+
+if ([System.IO.Path]::GetFileName($packageRoot) -eq ".agents") {
+  throw "当前脚本位于已安装的 .agents 根目录，不是可移植 agent 包目录。请从独立的 agent/ 包目录运行，或直接调用 tools/install/install-agent.ps1 并显式传入 -ProjectRoot。"
+}
+
+if ([System.IO.Path]::GetFileName($projectRoot) -eq ".agents") {
+  throw "当前脚本位于 .agents/agent 下，这是源包目录，不是目标项目根目录。请改用 tools/install/install-agent.ps1 并显式传入 -ProjectRoot。"
+}
+
+Write-Host "[install-agent-here] Target project root: $projectRoot"
+
+$arguments = @{
+  ProjectRoot = $projectRoot
+  Mode = $Mode
+}
+
+if ($Force.IsPresent) {
+  $arguments["Force"] = $true
+}
+
+if ($InitSmoke.IsPresent) {
+  $arguments["InitSmoke"] = $true
+}
+
+if ($CommitBaseline.IsPresent) {
+  $arguments["CommitBaseline"] = $true
+}
+
+if ($SkipBaselineCommit.IsPresent) {
+  $arguments["SkipBaselineCommit"] = $true
+}
+
+if ($InitGitIfNeeded.IsPresent) {
+  $arguments["InitGitIfNeeded"] = $true
+}
+
+& $installScript @arguments

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

@@ -1,115 +1,115 @@
----
-trigger: always_on
----
-
-# 通用 Agent 编排规则
-
-## 作用范围
-
-本文件定义跨项目可复用的 agent 角色、阶段映射和派发规则。这里的 `agent` 是职责角色，不一定要求每个角色都有独立进程；主控可以通过以下三种方式执行角色：
-
-- 通过 `.codex/agents/*.toml` 调起只读辅助子代理或 scoped writer 子代理。
-- 复用现有 skill，例如 `prd-writer`、`architect`、`frontend-design`、`api-design`、`tdd-guide`、`code-reviewer`。
-- 在当前主控会话中按该角色的规则完成窄范围分析，但主控会话只做分析和路由，不直接写仓库文件。
-
-如果某个阶段没有项目专属 agent，按本文的“阶段到默认 Agent 映射”选择默认角色。
-
-## 角色清单
-
-| Agent Role | 主要职责 | 推荐技能 / Prompt | 何时使用 |
-| --- | --- | --- | --- |
-| `controller` | 主控、阶段推进、任务排序、合并决策 | `controller-loop.md` | 全流程常驻，不直接写仓库文件 |
-| `bootstrap-operator` | 新项目接入、模板复制、smoke、环境检查 | `project-setup`, `tools/install/bootstrap-codex-harness.ps1` | Stage 01 初始化 |
-| `product-analyst` | 需求分析、PRD、用户角色、业务规则、验收标准和可执行验收示例 | `prd-writer`, `business-rule-spec`, `requirements-design-template` | Stage 02 需求收敛 |
-| `requirements-trace-analyst` | 需求到页面、状态、字段、接口、测试的追溯 | `consistency-checklist`, `spec-review` | Stage 03 追溯矩阵和缺口分析 |
-| `architect` | 架构边界、数据流、模块拆分、技术风险 | `architect`, `api-design`, `data-flow-spec` | 架构、契约、跨模块影响和高风险决策 |
-| `design-lead` | 设计规范、信息架构、组件规则、视觉 token | `frontend-design`, `ui-ux-pro-max`, `brand-design-md` | Stage 04 设计规范和复杂 UI 决策 |
-| `image-prompt-writer` | AI 生图 brief、页面状态、禁止事项、参考图要求 | `ai-ui-prompts` | Stage 05 生图输入 |
-| `ui-image-reviewer` | 设计图是否满足 PRD 和 Design Brief | `frontend-design`, `spec-based-review` | Stage 07 UI Image Review |
-| `frontend-spec-writer` | 把设计图翻译成组件、状态源、状态分支、事件、测试选择器和视觉断言 | `frontend-first-workflow`, `page-spec-template` | Stage 08 Image To Frontend Spec |
-| `planner` | DEV-PLAN、任务拆分、依赖、验证顺序 | `planner`, `plan` | 实施计划和任务拆解 |
-| `harness-writer` | `AGENTS.md`、任务队列、控制面配置、hook、prompt、harness 文档等编排资产写入 | `harness-writer.md` | 主控遇到非 driver 编排写入时 |
-| `frontend-worker` | 前端页面、组件、样式、stories、前端测试 | `frontend-patterns`, `typescript`, `vue-arco` 或项目栈技能 | 前端实现 |
-| `visual-reviewer` | 浏览器截图和设计图对比、视觉还原报告 | `browser-e2e-testing`, `midscene-fix-review` | Visual Parity |
-| `contract-designer` | OpenAPI、mock、client 生成、字段和错误码契约 | `api-contract-template`, `api-design` | Contract First |
-| `backend-worker` | API、数据库、权限、异常流、后端测试 | `backend-patterns`, `database`, 项目后端技能 | 后端实现 |
-| `integration-worker` | 前后端联调、mock 切真实服务、主流程 E2E | `api-integration`, `fullstack-workflow` | Integration |
-| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划和证据路径 | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
-| `test-runner` | 运行确定性验证、汇总失败、写测试报告 | `e2e-runner`, `qa-e2e-runner`, `verify` | Verify / Regression |
-| `stage1-reviewer` | 产品、设计、计划一致性审查 | `spec-based-review`, `spec-review` | Stage 1 Review |
-| `stage2-reviewer` | 代码质量、测试覆盖、回归风险审查 | `code-reviewer`, `security-reviewer` | Stage 2 Review |
-| `failure-triage` | 失败归因、owner 分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
-| `repair-worker` | 按 finding 定点修复并复验 | 原开发 agent + `repair-one-finding.md` | 修复闭环 |
-| `docs-worker` | 文档、索引、使用指南、模板同步 | `doc-updater`, `update-docs` | 文档更新和交付归档 |
-| `security-reviewer` | 权限、认证、支付、密钥、敏感数据和 sandbox 风险 | `security-reviewer`, `security-review` | 高风险功能 |
-| `release-manager` | diff 检查、验证证据、提交、push、最终报告 | `auto-commit`, `git-workflow` | 合并、提交和交付 |
-
-## 阶段到默认 Agent 映射
-
-| 阶段 | 主责 Agent | 协作 Agent | 说明 |
-| --- | --- | --- | --- |
-| 01 初始化 | `bootstrap-operator` | `docs-worker` | 接入模板、检查 Git、跑 smoke |
-| 02 需求收敛 | `product-analyst` | `requirements-trace-analyst`, `test-planner` | 把聊天需求转成 PRD、页面清单、状态矩阵、验收标准和可执行验收示例；所有 P0/P1 需求必须通过需求可测试性检查 |
-| 03 追溯与难点预研 | `requirements-trace-analyst` | `test-planner`, `architect` | 建立需求到 UI/API/数据/状态/测试/证据的追溯矩阵，识别高风险路径和测试数据缺口 |
-| 04 Design Brief | `design-lead` | `product-analyst` | 把主观审美变成可编码设计规则 |
-| 05 AI Image Brief | `image-prompt-writer` | `design-lead` | 生成稳定的 AI 生图输入 |
-| 06 UI 设计图 | `design-lead` | `image-prompt-writer` | 生成或编辑页面多状态参考图 |
-| 07 UI Image Review | `ui-image-reviewer` | `product-analyst`, `design-lead` | 设计图不通过时回到上一步 |
-| 08 Image To Frontend Spec | `frontend-spec-writer` | `frontend-worker`, `test-planner`, `visual-reviewer` | 把图片元素映射到组件、数据、事件、状态源、渲染分支、测试选择器、视觉断言和 E2E 场景 |
-| 09 DEV-PLAN / 任务拆分 | `planner` | `controller`, `architect`, `test-planner` | 生成依赖、owned paths、验证顺序和真实任务；每个任务都要携带测试层级、验证命令和证据路径 |
-| 10 Frontend Build | `frontend-worker` | `test-planner` | 先对照验收示例和前端测试规格实现；每个 UI 状态必须有代码状态源、渲染分支和复验入口，不能用界面说明文案冒充状态实现 |
-| 11 Visual Parity | `visual-reviewer` | `frontend-worker` | 除视觉还原外，还检查状态覆盖和关键交互可用性；失败后由原 frontend worker 修 |
-| 12 Contract First | `contract-designer` | `architect`, `backend-worker`, `frontend-worker`, `test-planner` | 先定义 OpenAPI、错误码、mock 和契约测试，再进入后端实现 |
-| 13 Backend / API | `backend-worker` | `contract-designer`, `test-planner` | 按契约实现 API、数据和权限 |
-| 14 Integration | `integration-worker` | `frontend-worker`, `backend-worker`, `test-runner` | mock 切真实接口，跑主流程 |
-| 15 Stage 1 Review | `stage1-reviewer` | `product-analyst`, `design-lead` | 审实现是否符合产品、设计和计划 |
-| 16 Stage 2 Review | `stage2-reviewer` | `security-reviewer`, `test-planner` | 审代码质量、测试缺口和风险 |
-| 17 Verify / Regression | `test-runner` | `controller`, `test-planner` | 运行 fresh evidence、affected tests、P0 regression 和契约验证；不得在本阶段第一次补齐需求测试范围 |
-| 18 修复闭环 | `failure-triage` | `repair-worker`, 原 reviewer/tester | 归因、派修、复验 |
-| 19 合并 / 提交 / Push | `release-manager` | `controller`, `docs-worker` | 只合并本任务改动，提交前检查 diff 和证据 |
-
-## 路由规则
-
-1. 需求分析阶段默认使用 `product-analyst`，不是 `frontend-worker`、`backend-worker` 或 `test-runner`。
-2. 需求追溯阶段默认使用 `requirements-trace-analyst`，测试映射由 `test-planner` 协作。
-3. 架构、契约、数据流、权限、支付、安全、迁移等高风险问题必须加入 `architect` 或 `security-reviewer`。
-4. UI 相关链路按 `design-lead -> image-prompt-writer -> ui-image-reviewer -> frontend-spec-writer -> frontend-worker -> visual-reviewer` 顺序推进。
-5. 实现失败由原实现 agent 修复；评审或测试失败由提出 finding 的原 reviewer/tester 复验。
-6. 前端状态是行为和数据分支，不是说明文字；任何把 `loading / empty / error / disabled / permission / mobile` 只写成页面文案而没有真实状态源、触发路径和渲染分支的实现，必须路由回 `frontend-worker` 修复。
-
-## 并行规则
-
-- Stage 02-08 以真相源稳定为主，可以并行调研，但不能让多个 agent 同时改同一份 PRD、Design Brief 或视觉规格。
-- 同一时刻不要让多个角色写同一组可写路径。
-- 任何并行结论都必须回到 `task.json`、验证命令和证据路径上，不接收口头“已完成”。
-
-## 子代理前置读取规则
-
-- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md` 和本文件。
-- 子代理必须再读取该角色对应的 `.agents/skills/*/SKILL.md`（如存在）、项目 truth source 和必要的深文档，再输出结论。
-- 如果当前轮次是被 stop hook / continuation gate 强制继续后的续跑，先重新阅读上面这些文档，再决定是否真的需要子代理。
-- 只读辅助子代理默认只读，不直接写业务代码，不修改 `task.json`、`progress.txt`、`traces/`。
-- writer 子代理只能修改父会话明确分配的路径；主控会话自身不直接写仓库文件。
-- `progress.txt`、`traces/` 和 Git 状态默认仍由 runtime 脚本处理；除这些脚本产物外，仓库写入必须通过匹配的 writer 子代理落盘。
-
-## 模型和思考深度
-
-- `product-analyst`、`requirements-trace-analyst`、`architect`、`design-lead`、`visual-reviewer`、`stage1-reviewer`、`stage2-reviewer` 默认使用更强模型和较高思考深度。
-- `frontend-worker`、`backend-worker`、`integration-worker` 默认使用工作型模型，中高思考深度。
-- `docs-worker`、`test-runner` 可以使用较低成本模型，但失败归因和最终验收不得只靠低强度判断。
-
-## 交接格式
-
-```markdown
-Verdict: PASS | FAIL | BLOCKED
-Role: <agent-role>
-Stage: <stage-id>
-Report: <relative/path/to/report.md>
-Changed paths:
-- <path>
-Verification:
-- <command> -> PASS | FAIL | NOT_RUN
-Open issues:
-- <issue or none>
-Next recommended stage: <stage-id>
-```
+---
+trigger: always_on
+---
+
+# 通用 Agent 编排规则
+
+## 作用范围
+
+本文件定义跨项目可复用的 agent 角色、阶段映射和派发规则。这里的 `agent` 是职责角色，不一定要求每个角色都有独立进程；主控可以通过以下三种方式执行角色：
+
+- 通过 `.codex/agents/*.toml` 调起只读辅助子代理或 scoped writer 子代理。
+- 复用现有 skill，例如 `prd-writer`、`architect`、`frontend-design`、`api-design`、`tdd-guide`、`code-reviewer`。
+- 在当前主控会话中按该角色的规则完成窄范围分析，但主控会话只做分析和路由，不直接写仓库文件。
+
+如果某个阶段没有项目专属 agent，按本文的“阶段到默认 Agent 映射”选择默认角色。
+
+## 角色清单
+
+| Agent Role | 主要职责 | 推荐技能 / Prompt | 何时使用 |
+| --- | --- | --- | --- |
+| `controller` | 主控、阶段推进、任务排序、合并决策 | `controller-loop.md` | 全流程常驻，不直接写仓库文件 |
+| `bootstrap-operator` | 新项目接入、模板复制、smoke、环境检查 | `project-setup`, `tools/install/bootstrap-codex-harness.ps1` | Stage 01 初始化 |
+| `product-analyst` | 需求分析、PRD、用户角色、业务规则、验收标准和可执行验收示例 | `prd-writer`, `business-rule-spec`, `requirements-design-template` | Stage 02 需求收敛 |
+| `requirements-trace-analyst` | 需求到页面、状态、字段、接口、测试的追溯 | `consistency-checklist`, `spec-review` | Stage 03 追溯矩阵和缺口分析 |
+| `architect` | 架构边界、数据流、模块拆分、技术风险 | `architect`, `api-design`, `data-flow-spec` | 架构、契约、跨模块影响和高风险决策 |
+| `design-lead` | 设计规范、信息架构、组件规则、视觉 token | `frontend-design`, `ui-ux-pro-max`, `brand-design-md` | Stage 04 设计规范和复杂 UI 决策 |
+| `image-prompt-writer` | AI 生图 brief、页面状态、禁止事项、参考图要求 | `ai-ui-prompts` | Stage 05 生图输入 |
+| `ui-image-reviewer` | 设计图是否满足 PRD 和 Design Brief | `frontend-design`, `spec-based-review` | Stage 07 UI Image Review |
+| `frontend-spec-writer` | 把设计图翻译成组件、状态源、状态分支、事件、测试选择器和视觉断言 | `frontend-first-workflow`, `page-spec-template` | Stage 08 Image To Frontend Spec |
+| `planner` | DEV-PLAN、任务拆分、依赖、验证顺序 | `planner`, `plan` | 实施计划和任务拆解 |
+| `harness-writer` | `AGENTS.md`、任务队列、控制面配置、hook、prompt、harness 文档等编排资产写入 | `harness-writer.md` | 主控遇到非 driver 编排写入时 |
+| `frontend-worker` | 前端页面、组件、样式、stories、前端测试 | `frontend-patterns`, `typescript`, `vue-arco` 或项目栈技能 | 前端实现 |
+| `visual-reviewer` | 浏览器截图和设计图对比、视觉还原报告 | `browser-e2e-testing`, `midscene-fix-review` | Visual Parity |
+| `contract-designer` | OpenAPI、mock、client 生成、字段和错误码契约 | `api-contract-template`, `api-design` | Contract First |
+| `backend-worker` | API、数据库、权限、异常流、后端测试 | `backend-patterns`, `database`, 项目后端技能 | 后端实现 |
+| `integration-worker` | 前后端联调、mock 切真实服务、主流程 E2E | `api-integration`, `fullstack-workflow` | Integration |
+| `test-planner` | 从需求阶段开始定义可测试需求、验收示例、追溯矩阵、测试数据、分层测试计划和证据路径 | `qa-e2e-planner`, `test-coverage`, `tdd` | 测试设计与测试左移 |
+| `test-runner` | 运行确定性验证、汇总失败、写测试报告 | `e2e-runner`, `qa-e2e-runner`, `verify` | Verify / Regression |
+| `stage1-reviewer` | 产品、设计、计划一致性审查 | `spec-based-review`, `spec-review` | Stage 1 Review |
+| `stage2-reviewer` | 代码质量、测试覆盖、回归风险审查 | `code-reviewer`, `security-reviewer` | Stage 2 Review |
+| `failure-triage` | 失败归因、owner 分类、Repair Queue | `build-error-resolver`, `failure-triage.md` | 测试、构建、视觉或 review 失败后 |
+| `repair-worker` | 按 finding 定点修复并复验 | 原开发 agent + `repair-one-finding.md` | 修复闭环 |
+| `docs-worker` | 文档、索引、使用指南、模板同步 | `doc-updater`, `update-docs` | 文档更新和交付归档 |
+| `security-reviewer` | 权限、认证、支付、密钥、敏感数据和 sandbox 风险 | `security-reviewer`, `security-review` | 高风险功能 |
+| `release-manager` | diff 检查、验证证据、提交、push、最终报告 | `auto-commit`, `git-workflow` | 合并、提交和交付 |
+
+## 阶段到默认 Agent 映射
+
+| 阶段 | 主责 Agent | 协作 Agent | 说明 |
+| --- | --- | --- | --- |
+| 01 初始化 | `bootstrap-operator` | `docs-worker` | 接入模板、检查 Git、跑 smoke |
+| 02 需求收敛 | `product-analyst` | `requirements-trace-analyst`, `test-planner` | 把聊天需求转成 PRD、页面清单、状态矩阵、验收标准和可执行验收示例；所有 P0/P1 需求必须通过需求可测试性检查 |
+| 03 追溯与难点预研 | `requirements-trace-analyst` | `test-planner`, `architect` | 建立需求到 UI/API/数据/状态/测试/证据的追溯矩阵，识别高风险路径和测试数据缺口 |
+| 04 Design Brief | `design-lead` | `product-analyst` | 把主观审美变成可编码设计规则 |
+| 05 AI Image Brief | `image-prompt-writer` | `design-lead` | 生成稳定的 AI 生图输入 |
+| 06 UI 设计图 | `design-lead` | `image-prompt-writer` | 生成或编辑页面多状态参考图 |
+| 07 UI Image Review | `ui-image-reviewer` | `product-analyst`, `design-lead` | 设计图不通过时回到上一步 |
+| 08 Image To Frontend Spec | `frontend-spec-writer` | `frontend-worker`, `test-planner`, `visual-reviewer` | 把图片元素映射到组件、数据、事件、状态源、渲染分支、测试选择器、视觉断言和 E2E 场景 |
+| 09 DEV-PLAN / 任务拆分 | `planner` | `controller`, `architect`, `test-planner` | 生成依赖、owned paths、验证顺序和真实任务；每个任务都要携带测试层级、验证命令和证据路径 |
+| 10 Frontend Build | `frontend-worker` | `test-planner` | 先对照验收示例和前端测试规格实现；每个 UI 状态必须有代码状态源、渲染分支和复验入口，不能用界面说明文案冒充状态实现 |
+| 11 Visual Parity | `visual-reviewer` | `frontend-worker` | 除视觉还原外，还检查状态覆盖和关键交互可用性；失败后由原 frontend worker 修 |
+| 12 Contract First | `contract-designer` | `architect`, `backend-worker`, `frontend-worker`, `test-planner` | 先定义 OpenAPI、错误码、mock 和契约测试，再进入后端实现 |
+| 13 Backend / API | `backend-worker` | `contract-designer`, `test-planner` | 按契约实现 API、数据和权限 |
+| 14 Integration | `integration-worker` | `frontend-worker`, `backend-worker`, `test-runner` | mock 切真实接口，跑主流程 |
+| 15 Stage 1 Review | `stage1-reviewer` | `product-analyst`, `design-lead` | 审实现是否符合产品、设计和计划 |
+| 16 Stage 2 Review | `stage2-reviewer` | `security-reviewer`, `test-planner` | 审代码质量、测试缺口和风险 |
+| 17 Verify / Regression | `test-runner` | `controller`, `test-planner` | 运行 fresh evidence、affected tests、P0 regression 和契约验证；不得在本阶段第一次补齐需求测试范围 |
+| 18 修复闭环 | `failure-triage` | `repair-worker`, 原 reviewer/tester | 归因、派修、复验 |
+| 19 合并 / 提交 / Push | `release-manager` | `controller`, `docs-worker` | 只合并本任务改动，提交前检查 diff 和证据 |
+
+## 路由规则
+
+1. 需求分析阶段默认使用 `product-analyst`，不是 `frontend-worker`、`backend-worker` 或 `test-runner`。
+2. 需求追溯阶段默认使用 `requirements-trace-analyst`，测试映射由 `test-planner` 协作。
+3. 架构、契约、数据流、权限、支付、安全、迁移等高风险问题必须加入 `architect` 或 `security-reviewer`。
+4. UI 相关链路按 `design-lead -> image-prompt-writer -> ui-image-reviewer -> frontend-spec-writer -> frontend-worker -> visual-reviewer` 顺序推进。
+5. 实现失败由原实现 agent 修复；评审或测试失败由提出 finding 的原 reviewer/tester 复验。
+6. 前端状态是行为和数据分支，不是说明文字；任何把 `loading / empty / error / disabled / permission / mobile` 只写成页面文案而没有真实状态源、触发路径和渲染分支的实现，必须路由回 `frontend-worker` 修复。
+
+## 并行规则
+
+- Stage 02-08 以真相源稳定为主，可以并行调研，但不能让多个 agent 同时改同一份 PRD、Design Brief 或视觉规格。
+- 同一时刻不要让多个角色写同一组可写路径。
+- 任何并行结论都必须回到 `task.json`、验证命令和证据路径上，不接收口头“已完成”。
+
+## 子代理前置读取规则
+
+- 任何只读辅助子代理或 writer 子代理在开始判断前，必须先读 `AGENTS.md`、`docs/harness/task-session-strategy.md` 和本文件。
+- 子代理必须再读取该角色对应的 `.agents/skills/*/SKILL.md`（如存在）、项目 truth source 和必要的深文档，再输出结论。
+- 如果当前轮次是被 stop hook / continuation gate 强制继续后的续跑，先重新阅读上面这些文档，再决定是否真的需要子代理。
+- 只读辅助子代理默认只读，不直接写业务代码，不修改 `task.json`、`progress.txt`、`traces/`。
+- writer 子代理只能修改父会话明确分配的路径；主控会话自身不直接写仓库文件。
+- `progress.txt`、`traces/` 和 Git 状态默认仍由 runtime 脚本处理；除这些脚本产物外，仓库写入必须通过匹配的 writer 子代理落盘。
+
+## 模型和思考深度
+
+- `product-analyst`、`requirements-trace-analyst`、`architect`、`design-lead`、`visual-reviewer`、`stage1-reviewer`、`stage2-reviewer` 默认使用更强模型和较高思考深度。
+- `frontend-worker`、`backend-worker`、`integration-worker` 默认使用工作型模型，中高思考深度。
+- `docs-worker`、`test-runner` 可以使用较低成本模型，但失败归因和最终验收不得只靠低强度判断。
+
+## 交接格式
+
+```markdown
+Verdict: PASS | FAIL | BLOCKED
+Role: <agent-role>
+Stage: <stage-id>
+Report: <relative/path/to/report.md>
+Changed paths:
+- <path>
+Verification:
+- <command> -> PASS | FAIL | NOT_RUN
+Open issues:
+- <issue or none>
+Next recommended stage: <stage-id>
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/rules/coding-style.md

@@ -1,74 +1,57 @@
----
-trigger: always_on
----
-
-# Coding Style
-
-## Immutability (CRITICAL)
-
-ALWAYS create new objects, NEVER mutate:
-
-```javascript
-// WRONG: Mutation
-function updateUser(user, name) {
-  user.name = name  // MUTATION!
-  return user
-}
-
-// CORRECT: Immutability
-function updateUser(user, name) {
-  return {
-    ...user,
-    name
-  }
-}
-```
-
-## File Organization
-
-MANY SMALL FILES > FEW LARGE FILES:
-- High cohesion, low coupling
-- 200-400 lines typical, 800 max
-- Extract utilities from large components
-- Organize by feature/domain, not by type
-
-## Error Handling
-
-ALWAYS handle errors comprehensively:
-
-```typescript
-try {
-  const result = await riskyOperation()
-  return result
-} catch (error) {
-  console.error('Operation failed:', error)
-  throw new Error('Detailed user-friendly message')
-}
-```
-
-## Input Validation
-
-ALWAYS validate user input:
-
-```typescript
-import { z } from 'zod'
-
-const schema = z.object({
-  email: z.string().email(),
-  age: z.number().int().min(0).max(150)
-})
-
-const validated = schema.parse(input)
-```
-
-## Code Quality Checklist
-
-Before marking work complete:
-- [ ] Code is readable and well-named
-- [ ] Functions are small (<50 lines)
-- [ ] Files are focused (<800 lines)
-- [ ] No deep nesting (>4 levels)
-- [ ] Proper error handling
-- [ ] No console.log statements
-- [ ] No hardcoded values
-- [ ] No mutation (immutable patterns used)
+---
+trigger: always_on
+---
+
+# Coding Style
+
+## 规则分层
+
+- 这里写跨项目稳定不变、需要默认自动加载的规则。
+- `docs/harness/code-style-and-naming.md` 只补项目特有的业务词典、目录例外和类型边界表，不重复这里的固定规则。
+
+## 不可变性
+
+- 默认使用不可变更新，不直接修改输入对象。
+- 状态更新、缓存更新、测试夹具都遵守同一原则。
+
+## 固定命名规则
+
+- 一个业务概念只用一个主名词，不在同一任务里混用多个同义词。
+- 发现历史别名时，先判断它是独立概念还是遗留脏别名，再决定兼容方式。
+- 项目专属业务词典、别名白名单和历史兼容说明写到 `docs/harness/code-style-and-naming.md`。
+
+## 固定文件命名规则
+
+- 同一层目录只使用一套命名风格。
+- 新文件先跟随同目录已有约定，不自行切换成另一套大小写风格。
+- 测试文件跟随被测对象命名，不用 `test1`、`temp`、`new` 这类临时名。
+
+## 固定函数命名规则
+
+- 函数名使用“动词 + 对象”或明确状态判断。
+- 禁止使用 `doAction`、`processData`、`dealData`、`getInfo`、`check`、`handler` 这类模糊名。
+- 事件处理统一使用 `handleXxx`，布尔判断统一使用 `is/has/can` 前缀。
+
+## 固定类型命名规则
+
+- 类型后缀必须有边界语义，`Entity`、`DTO`、`Response`、`FormValues`、`ViewModel` 不混用。
+- 输入模型、持久化模型、展示模型和接口模型不要共用一个泛名。
+- 如果项目禁用某类后缀，具体禁用表和替代方案写到 `docs/harness/code-style-and-naming.md`。
+
+## 文件组织
+
+- 高内聚、低耦合；按 feature / domain 组织，避免大而杂的工具箱文件。
+- 常规文件建议 200-400 行，超过 800 行应先评估是否拆分。
+
+## 错误处理与输入校验
+
+- 错误处理要保留上下文，不吞异常。
+- 外部输入统一走 schema / validator / contract，不靠隐式假设。
+
+## 完成前检查
+
+- [ ] 命名是否与项目业务词典一致
+- [ ] 同层文件是否遵守同一命名风格
+- [ ] 新函数名是否避开模糊万能词
+- [ ] 新类型名是否符合边界语义
+- [ ] 无 `console.log`、无硬编码临时名、无直接对象突变

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

@@ -79,7 +79,7 @@ Rationale for version bump (MAJOR):
 
 - 主控 agent 负责任务拆解、上下文分发、路径所有权、闸门判断、结果合并和最终交付。
 - Worker agent 必须拥有清晰的职责边界，例如前端、后端、测试、文档、评审、修复或发布。
-- 并发执行时，不同 agent 应使用独立目录或明确互斥的写入路径。
+- 并发执行时，不同 agent 应使用独立目录或明确互斥的写入路径。
 - Worker 结束时必须报告变更文件、验证命令、证据路径、未解决问题和需要主控合并的事项。
 - 主控不得盲目合并并行结果；必须检查冲突、重复实现、接口不一致和测试缺口。
 
@@ -181,7 +181,7 @@ Rationale for version bump (MAJOR):
 
 - 改变行为、接口、目录、命令、部署、测试或工作流时，必须同步更新相关文档。
 - 文档应说明当前事实、操作命令、验证方式和已知限制，避免只写愿景。
-- 长文档放 `docs/`，项目规则放项目根 `AGENTS.md`，跨项目语义规则放 `.codex/rules/*.md` 或全局规则；`.codex/rules/*.rules` 只放 Codex 命令执行策略。
+- 长文档放 `docs/`，项目规则放项目根 `AGENTS.md`，跨项目语义规则放 `.codex/rules/*.md` 或全局规则；`.codex/rules/*.rules` 只放 Codex 命令执行策略。
 - 文档改动至少运行格式或空白检查，例如 `git diff --check`。
 
 **理由**:
@@ -193,7 +193,7 @@ Rationale for version bump (MAJOR):
 
 **原则声明**:
 
-- Dirty workspace 默认视为风险，必须区分当前任务改动和用户已有改动。
+- Dirty workspace 默认视为风险，必须区分当前任务改动和用户已有改动。
 - 禁止未经确认回滚、覆盖、重置或删除用户改动。
 - 提交前必须查看 diff，并运行与交付声明直接相关的验证。
 - 提交应保持主题清晰，避免把无关文件混入同一提交。
@@ -259,7 +259,7 @@ Git 是多 agent 协作的事实边界。清晰提交和保守操作可以保护
 1. 用户当前明确指令
 2. 项目根 `AGENTS.md`
 3. 项目 `docs/`、`specs/`、`.specify/` 中的已批准规则
-4. 本宪章和 `.codex/rules/*.md`
+4. 本宪章和 `.codex/rules/*.md`
 5. 通用默认实践
 
 ### 修订程序

package/package-source/docs/codex-harness-engineering/templates/package-assets/rules/git.rules

@@ -1,41 +1,41 @@
-prefix_rule(
-    pattern = ["git", "status"],
-    decision = "allow",
-    justification = "Read-only git status is required for harness workspace checks.",
-)
-
-prefix_rule(
-    pattern = ["git", "diff"],
-    decision = "allow",
-    justification = "Read-only diff inspection is required before verification and delivery.",
-)
-
-prefix_rule(
-    pattern = ["git", "log"],
-    decision = "allow",
-    justification = "Read-only commit history inspection is safe for context gathering.",
-)
-
-prefix_rule(
-    pattern = ["git", "show"],
-    decision = "allow",
-    justification = "Read-only object inspection is safe for review and evidence gathering.",
-)
-
-prefix_rule(
-    pattern = ["git", "add"],
-    decision = "prompt",
-    justification = "Staging changes must be scoped to the current harness task.",
-)
-
-prefix_rule(
-    pattern = ["git", "commit"],
-    decision = "prompt",
-    justification = "Commits require fresh verification and ownership checks.",
-)
-
-prefix_rule(
-    pattern = ["git", "push"],
-    decision = "prompt",
-    justification = "Pushing changes affects a remote repository and requires explicit intent.",
-)
+prefix_rule(
+    pattern = ["git", "status"],
+    decision = "allow",
+    justification = "Read-only git status is required for harness workspace checks.",
+)
+
+prefix_rule(
+    pattern = ["git", "diff"],
+    decision = "allow",
+    justification = "Read-only diff inspection is required before verification and delivery.",
+)
+
+prefix_rule(
+    pattern = ["git", "log"],
+    decision = "allow",
+    justification = "Read-only commit history inspection is safe for context gathering.",
+)
+
+prefix_rule(
+    pattern = ["git", "show"],
+    decision = "allow",
+    justification = "Read-only object inspection is safe for review and evidence gathering.",
+)
+
+prefix_rule(
+    pattern = ["git", "add"],
+    decision = "prompt",
+    justification = "Staging changes must be scoped to the current harness task.",
+)
+
+prefix_rule(
+    pattern = ["git", "commit"],
+    decision = "prompt",
+    justification = "Commits require fresh verification and ownership checks.",
+)
+
+prefix_rule(
+    pattern = ["git", "push"],
+    decision = "prompt",
+    justification = "Pushing changes affects a remote repository and requires explicit intent.",
+)