@tea-agent/loop-agent 0.1.0-fe-test.0

package/docs/templates/evaluation/agents-map-verbose-v0.md

@@ -0,0 +1,153 @@
+<!-- CODEGRAPH_START -->
+## CodeGraph
+
+如果仓库根目录存在 `.codegraph/`，在理解或定位代码前优先使用 CodeGraph，再考虑 rg/fd 或手动读文件。
+<!-- CODEGRAPH_END -->
+
+# AGENTS.md
+
+本仓库采用“人类掌舵，智能体执行”的工程方式。目标不是一次性写完所有代码，而是在一个可持续演进、可交接、可验证的系统里做小步增量。
+
+`AGENTS.md` 是地图，不是百科。顶层只保留开工协议、会话协议与文档导航；长期知识、方法论、决策、计划、报告和模板应进入 `docs/`。
+
+## 默认立场
+
+- 仓库是记录系统：决策、契约、计划、测试、报告优先落到仓库，而不是停留在聊天里。
+- 一次只推进一个清晰工作块；主会话按 Orient → Select → Contract → Implement → Verify → Handoff 治理，runtime 真实流程以 `src/workflows/` 为准。
+- 先验证基线，再叠加改动；如果当前基线已坏，优先定位基线问题。
+- Do not consider backward compatibility. Ignore legacy code/libraries.
+- 完成定义必须可验证；不能靠删测试、降标准或模糊描述制造“完成”。
+- 搜索先于实现；先查现有代码、文档、脚本、测试，避免重复造轮子或误判系统能力。
+- 受治理 Agent runtime 只有 Pi：DAG writer 固定为 `implement-pi` / `repair-pi`；`cursor-prompt` 仅是显式手工 one-shot sidecar，不进入 Loop auto-execute 或 Delegate 自动写入。
+- 在 DAG runtime 中，搜索/侦察是显式节点：标准路径是 Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
+- init surface、runtime 边界、command registry、skill entry 和架构 import 方向是可机器校验的治理契约；相关细节以 `docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/` 和 `scripts/check-*.sh` 为准，顶层 `AGENTS.md` 只指路，不重复维护事实源。
+- 本仓库既是 loop-agent 源项目，也是目标项目初始化体验的默认模板；任何新增命令、脚本、文档、skill、模板或发布包内容，都要判断它应由 npm 包内置提供，还是由 `loop-agent init` 投影到目标项目，避免出现“本项目能用、初始化项目缺能力”。
+- 委托模型写入前，必须把写入边界写成结构化 `task.json.allowedPaths` / `task.json.forbiddenPaths`，再审查生成 DAG 的 writer `writeSet`；不要只依赖 `source/执行约束.md` 的自然语言约束。
+- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本确为 Bash 脚本时使用 Git Bash 或已配置的兼容 Bash，不要求 Windows 环境适配 POSIX 路径。
+- 用 loop-agent 迭代本仓库时，控制器必须来自已发布的 npm 安装包；首次安装或有意升级可用 `@tea-agent/loop-agent@latest`，但一次自举任务启动后不要中途升级控制器，并记录 `npm list -g @tea-agent/loop-agent --depth=0` 显示的实际版本。不要用当前工作区的 `npm link` 或 `npm run dev` 控制可能改动 CLI、DAG runtime、executor、package metadata 或 build output 的任务。
+- 反复出现的约束要固化为文档、脚本、检查项、测试或模板。
+- 除非用户明确要求，不要自行引入外部 SDD、spec-first、brainstorming 等方法论的强制设计文档、审批门或专用目录；本仓库的工作流程以本文件和 `docs/` 中的治理规则为准。
+- 对非微小的实现或修复，`exec-plan` 只负责记录 Contract、进度和验证证据，不能替代 Agent DAG。除非用户明确要求 one-shot，或在计划中记录了适用的 escape hatch 与理由，否则在改动实现文件前必须完成 `task advance`（含结构化 `allowedPaths` / `forbiddenPaths` 与 writeSet 审查）；随后 `--approve-gate` 长跑，不得主会话直接改实现。
+- 禁止占位实现；除非 contract 明确约定为脚手架且标出后续闭环。
+
+## 开始顺序
+
+改文件前必须先完成：
+
+1. 运行 `pwd`。
+2. 阅读 `README.md`。
+3. 阅读 `harness.json`。
+4. 阅读 `docs/README.md`。
+5. 如果存在 `CONTEXT.md`，阅读项目术语表，避免混用任务源、执行约束、契约、计划等领域概念。
+6. 如果是实现类工作，继续阅读：
+   - `docs/governance/development-principles.md`
+   - `docs/governance/feature-workflow.md`
+   - `docs/governance/verification-matrix.md`
+7. 如果任务涉及命令入口、执行流程、executor、初始化投影、skills、脚本矩阵、发布包范围或治理检查，继续阅读：
+   - `docs/architecture/runtime-boundaries.md`
+   - `docs/runtime/loop-agent-harness.md`
+8. 如果任务涉及测试纪律、验证声明或调试，继续阅读：
+   - `docs/governance/harness-methodology-tdd.md`
+   - `docs/governance/harness-methodology-verification.md`
+   - `docs/governance/harness-methodology-debugging.md`
+9. 查看最近提交、相关执行计划、progress/report，确认当前上下文。
+10. 检查 `git status --short --branch`。
+11. 运行本次任务相关的最小基线验证。
+12. 如果用户提到"后端测试"、"接口测试"、"pytest"、"自动化测试"，在任务 `task.json` 中设置 `taskKind: "backend-test"` 再 `task advance`；不要用 `--profile backend-test`（CLI 不接受该值，专用模板只走 taskKind）。知识回写用 `taskKind: "knowledge-sync"`（须 `featureId`），图谱开荒用 `taskKind: "knowledge-graph-bootstrap"`。`--profile` 仅表示治理强度：`auto|minimal|standard|reviewed|supervised`。
+13. 如果用户提到"看板"、"observe"、"监控面板"、"启动看板"，使用 `agent-worker console` 启动统一 Operator Console（默认 repo=当前目录、port=8790；本地图形环境默认打开浏览器，`--no-open` 禁止）；`/inspect/` 提供只读检视。`agent-worker observe serve` 已下线（REMOVED / exit 2）。
+14. 如果用户要求“合并 `<source>` 到 `<target>`”或“合并 origin/main 到当前分支”，先阅读 `docs/operations/branch-merge-guideline.md`，按影响自动选择快速、标准或深度模式；始终冻结 source SHA、审查双方功能、运行 merge-tree、生成 source-SHA 合并报告，并在提交前再次 fetch 防止主干前进。
+
+## 会话协议
+
+1. Orient：读入口文档、相关专题、最近变更和现有实现。
+2. Select：只选一个清晰工作块；避免把重构、新功能、文档迁移混在一轮里。
+3. Contract：写清本轮交付物、非目标、完成标准、验证方法和失败条件。
+4. Implement：做最小增量实现，同步维护必要文档、脚本和测试。
+5. Verify：优先跑快速反馈，再跑必要的真实路径验证。
+6. Converge Docs：检查 README、AGENTS.md、CHANGELOG.md、docs/README.md、相关治理文档、skills references、website docs、初始化模板和脚本说明是否仍与实际行为一致；只更新与本次变更相关的内容，不做顺手文档迁移。
+7. Handoff：更新 progress/report/plan 中有长期价值的信息，写清风险、剩余项和下一步。
+
+这套会话协议不是 DAG runtime 的节点序列。复杂实现默认采用 Agent DAG；具体节点拓扑、profile routing、writer 选择和 runner 行为以 `docs/governance/feature-workflow.md` 与 `src/workflows/` 为准。主 agent 负责拆任务、写 contract、把允许/禁止路径写入结构化 task config、审查 DAG/writeSet/profile/shell verification、盯验证与 handoff。微小任务或 DAG runtime 自身修复也应优先使用 DAG，或使用 one-shot `pi-prompt` / `cursor-prompt` escape hatch 并记录边界与验证证据。
+
+## 项目地图
+
+- `CONTEXT.md`：项目术语表，定义 loop-agent、任务源、执行约束等领域语言
+- `src/`：loop-agent 运行时代码
+- `test/`：Vitest 测试套件
+- `bin/loop-agent.js`：CLI 可执行入口
+- `skills/`：loop-agent 源仓库和 npm 包内置 skill 指令与参考资料；目标项目初始化后只生成 `.agents/skills/`，不再生成根 `skills/`。初始化还会向目标项目 `.gitignore` 合并 loop-agent managed block，忽略 `.harness/tasks/*`、`.harness/dag-runs/*`、`.harness/runs/*`、`.harness/evaluation/`、`.harness/dogfood-evidence/`、`.harness/init-surface.json`、`.harness/task-pool/*`、`.task-pool/`、`.worktrees/` 等运行态事实，但保留 `.harness/prompts/` 和目录占位可共享，不会整目录忽略 `.harness/`。
+- `.harness/`：任务、DAG、run、cache 和 live state 等运行态目录
+- `docs/`：治理文档、计划、报告和模板
+- `website/`：Docusaurus 用户文档站
+- `scripts/`：验证和维护脚本
+
+## 工作规则
+
+- 每次任务只推进一个清晰、有边界的工作块。
+- 保留无关的用户改动，不要回退自己没有做的修改。
+- 优先沿用现有 helper、目录边界和局部模式，再考虑新增抽象。
+- 长期决策写入 `docs/`，不要只留在聊天里。
+- 分支合并遵循 `docs/operations/branch-merge-guideline.md`；快速模式只用于可证明的低风险/no-op 合并，涉及冲突、init/package/runtime/release/public API 时必须升级为标准或深度模式。
+- 后端测试、接口/API 测试、pytest 或明确的后端自动化测试，必须把 `.harness/tasks/<task-id>/task.json` 的 `taskKind` 设置为 `"backend-test"`，不得保留默认 `standard`。`backend-test` 是 `taskKind`，不是 `--profile` 的可选值；`task advance` 继续使用 `--profile auto` 选择治理等级。仅说“自动化测试”且前后端不明时，先根据任务源和项目技术栈判断，禁止无条件路由。
+- 本地 Operator Console：`agent-worker console`（默认 repo=当前目录、port=8790；`--no-open` 可禁止自动打开浏览器），访问 `http://127.0.0.1:8790/`；其中 `/inspect/` 为只读运行检视。默认绑定本机 `127.0.0.1`；可用 `--host 0.0.0.0` / `--debug`，不要直接暴露到公开网络。端口被占用时不会自动更换，请用 `--port <port>` 显式指定。
+- 面向使用者的新增、修改、删除或修复，应同步更新根目录 `CHANGELOG.md`；保持版本级摘要即可，不写过细技术细节。
+- 面向用户的中文更新日志、README 和说明文档应使用自然、结果导向的表达：先说明用户能获得什么或问题如何改善，保留必要的命令和产品术语，避免逐字翻译、内部实现细节和无意义的中英混杂。
+- 涉及 `loop-agent init` 或目标项目投影的改动，必须同步考虑目标项目生成物：`AGENTS.md`、`README.md`、`harness.json`、`ai_workspace/loop-agent/`、`scripts/`、`.agents/skills/`、`.harness/prompts`、`.gitignore`（loop-agent runtime managed block）和 npm 包内置 assets；目标项目根 `docs/` 和根 `skills/` 的旧投影需要由 `init update --apply-safe` 安全迁移或退役。
+- 涉及初始化能力演化时，按 `docs/init-surface.manifest.json` 与 `scripts/check-init-evolution-needed.sh` 分级处理：小改 advisory，中等 surface-check，高影响才需要模型审查；不要把所有小改动升级成重流程。
+- 通用脚本、skill 和模板可以复制或投影；项目相关 README、验证命令、发布/维护脚本必须基于模板和目标项目真实文件生成，不假定目标项目是 TypeScript、Node、前端、后端或工具项目。
+- 涉及 CLI command、skill entry、runtime boundary、import 方向或发布包范围时，同步更新对应文档、catalog/definition、治理脚本和测试，避免 README、skill reference、CLI help、npm 包内容互相漂移。
+- 完成相关更新后必须做文档收敛：如果 README、AGENTS.md、CHANGELOG.md、docs、skills、website、初始化生成模板或脚本说明不需要更新，应在交接里写明理由。
+- 不提交占位实现。
+- 没有新鲜验证证据时，不声明工作完成。
+- 发现新 bug、技术债或契约漂移时，写回当前 plan、progress 或 report，而不是只在对话里提一句。
+- 涉及 harness 流程变化时，优先把变化落到 `harness.json`、模板、脚本或治理文档，而不是只改提示词。
+
+## 验证
+
+用 `docs/governance/verification-matrix.md` 选择命令。常用门禁：
+
+```bash
+npm run typecheck
+npm test
+npm run build
+node bin/loop-agent.js --help
+bash scripts/check-repo.sh
+bash scripts/ci.sh
+```
+
+Windows 上运行 `scripts/*.sh` 时使用 Git Bash 或已配置的兼容 Bash。CLI、Node 代码、模板和提示词里的实际文件路径必须兼容 macOS 与 Windows：优先使用平台原生临时目录和 `path`/`os.tmpdir()`；仅在 repo 引用、JSON/Markdown 证据引用和 glob 约定中使用 `/` 作为稳定分隔符。
+
+文档站相关变更还需要按范围运行：
+
+```bash
+npm run docs:build
+```
+
+按变更类型补充定向验证：
+
+- 初始化能力或目标项目投影：运行 `test/init-command.test.ts`，并在临时目标项目执行 `loop-agent init --profile full --merge`、`loop-agent init doctor`、`loop-agent inspect`、`loop-agent docs audit` 和目标项目 `bash scripts/check-repo.sh`。
+- init surface 或初始化能力演化：运行 `bash scripts/check-init-evolution-needed.sh` 和 `bash scripts/check-init-surface.sh`；高影响或发布前按需使用 `--strict` 并参考 `skills/init-capability-evolution/` 与 `docs/templates/init-evolution-review.md`。
+- runtime boundary / command registry / skill entry：运行 `bash scripts/check-architecture-boundaries.sh`、`bash scripts/check-command-registry-drift.sh`、`bash scripts/check-skill-entry.sh`，并确保 `bash scripts/check-repo.sh` 覆盖这些检查。
+- 发布包范围：运行 `npm run build`、`node bin/loop-agent.js --help` 和 `npm pack --dry-run`，确认初始化所需静态资料在 package files 中。
+
+## 交接
+
+较大的工作结束时记录：
+
+- 改了什么
+- 为什么这样改
+- 执行过哪些验证命令以及结果
+- 是否影响契约、文档、测试或脚本
+- 剩余风险
+- 后续工作
+
+## 禁止事项
+
+- 不要在未读相关文档的前提下直接大改。
+- 不要一次混合重构、新功能和文档大迁移而没有清晰边界。
+- 不要把仅存在于对话里的约束当作长期知识。
+- 不要在缺少验证的情况下宣称完成。
+- 不要假设系统没有某个能力；先搜索再判断。
+- 不要用 stub、假数据通路或注释承诺替代真正交付。
+- 不要把个人机器的绝对路径写入仓库级 `AGENTS.md`、README、模板或发布包资料；个人工具配置应留在用户级配置或本机会话上下文。
+- 不要只更新 loop-agent 本仓库体验而遗漏目标项目初始化体验；新增能力如果不能通过 npm 内置资料或 `loop-agent init` 到达目标项目，必须写清原因和替代入口。

package/docs/templates/evaluation/campaign-budget-v1.json

@@ -0,0 +1,12 @@
+{
+	"schemaVersion": 1,
+	"mode": "hard",
+	"limits": {
+		"maxTokens": 2000000,
+		"maxWallTimeMs": 86400000,
+		"maxExecutorCalls": 500,
+		"maxRepairPasses": 50,
+		"maxConcurrency": 2,
+		"maxContextChars": 120000
+	}
+}

package/docs/templates/evaluation/campaign-dogfood-v0.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "campaignId": "camp-dogfood-context-policy-ab",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "status": "prepared",
+  "policyVersion": "promotion-policy-v1",
+  "incumbentCandidateId": "REPLACE_INCUMBENT_CANDIDATE_ID",
+  "challengerCandidateIds": ["REPLACE_CHALLENGER_CANDIDATE_ID"],
+  "corpusId": "corpus-dogfood-v0",
+  "corpusHash": "REPLACE_AFTER_CORPUS_REGISTER",
+  "privateVerifierId": "pv-dogfood-v0",
+  "privateVerifierManifestHash": "REPLACE_AFTER_PRIVATE_VERIFIER_REGISTER",
+  "budget": {
+    "schemaVersion": 1,
+    "mode": "hard",
+    "limits": {
+      "maxExecutorCalls": 500,
+      "maxWallTimeMs": 86400000,
+      "maxRepairPasses": 50,
+      "maxConcurrency": 2
+    }
+  },
+  "notes": "M4 dogfood: single-variable Context Policy A/B. Replace candidate/corpus/privateVerifier hashes after register. held_out cells are promotion_gate_only."
+}

package/docs/templates/evaluation/campaign-evidence-v1.json

@@ -0,0 +1,44 @@
+{
+  "schemaVersion": 1,
+  "campaignId": "campaign-dogfood-v0",
+  "challengerCandidateId": "cand-challenger-example",
+  "cells": [
+    {
+      "candidateId": "cand-baseline-example",
+      "taskRef": "synthetic/private-1",
+      "seed": 1,
+      "split": "private",
+      "verifyPassed": false
+    },
+    {
+      "candidateId": "cand-challenger-example",
+      "taskRef": "synthetic/private-1",
+      "seed": 1,
+      "split": "private",
+      "verifyPassed": true
+    },
+    {
+      "candidateId": "cand-baseline-example",
+      "taskRef": "synthetic/heldout-1",
+      "seed": 1,
+      "split": "held_out",
+      "verifyPassed": true
+    },
+    {
+      "candidateId": "cand-challenger-example",
+      "taskRef": "synthetic/heldout-1",
+      "seed": 1,
+      "split": "held_out",
+      "verifyPassed": true
+    }
+  ],
+  "diffs": [],
+  "verifyCommands": {
+    "incumbent": ["npm test", "npm run typecheck"],
+    "challenger": ["npm test", "npm run typecheck"]
+  },
+  "budgetStatus": {
+    "incumbent": "ok",
+    "challenger": "ok"
+  }
+}

package/docs/templates/evaluation/context-policy-baseline-v1.json

@@ -0,0 +1,17 @@
+{
+  "schemaVersion": 1,
+  "policyId": "baseline-v1",
+  "description": "Current DAG context assembly: shared upstream char budget, role skill defaults, learned patterns only for implementer.",
+  "knobs": {
+    "maxUpstreamCharsByRole": {
+      "default": 2000
+    },
+    "includeLearnedPatternsRoles": ["implementer"],
+    "perSkillMaxCharsByRole": {
+      "default": 3000
+    },
+    "totalMaxCharsByRole": {
+      "default": 12000
+    }
+  }
+}

package/docs/templates/evaluation/context-policy-role-specialized-v1.json

@@ -0,0 +1,28 @@
+{
+  "schemaVersion": 1,
+  "policyId": "role-specialized-v1",
+  "description": "Role-specialized upstream and skill-instruction budgets; skill names still resolve via baseline merge order.",
+  "knobs": {
+    "maxUpstreamCharsByRole": {
+      "default": 2000,
+      "scout": 1200,
+      "reviewer": 1200,
+      "implementer": 3000,
+      "verifier": 1600,
+      "closeout": 1600,
+      "planner": 2000,
+      "supervisor": 2000
+    },
+    "includeLearnedPatternsRoles": ["implementer", "closeout"],
+    "perSkillMaxCharsByRole": {
+      "default": 3000,
+      "scout": 2500,
+      "implementer": 3500
+    },
+    "totalMaxCharsByRole": {
+      "default": 12000,
+      "scout": 10000,
+      "implementer": 14000
+    }
+  }
+}

package/docs/templates/evaluation/corpus-dogfood-v0.manifest.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": 1,
+  "corpusId": "corpus-dogfood-v0",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "description": "W1.5 initial dogfood corpus contract: 15 heterogeneous tasks with public/private/held_out splits. Contract-only; not live campaign evidence.",
+  "tasks": [
+    {
+      "taskRef": "features/F-2026-001/login-flow",
+      "class": "fullstack",
+      "split": "public",
+      "seeds": [1, 2, 3],
+      "featureId": "F-2026-001",
+      "description": "Dogfood login Feature packet (public feedback allowed)."
+    },
+    {
+      "taskRef": "features/F-2026-002/profile-filter",
+      "class": "implement",
+      "split": "public",
+      "seeds": [1, 2],
+      "featureId": "F-2026-002",
+      "description": "Profile filter implementation path."
+    },
+    {
+      "taskRef": "features/F-2026-005/welcome-banner",
+      "class": "fullstack",
+      "split": "public",
+      "seeds": [1, 2, 3],
+      "featureId": "F-2026-005",
+      "description": "fullstack-v1 welcome sample (public)."
+    },
+    {
+      "taskRef": "synthetic/docs-agents-converge",
+      "class": "docs",
+      "split": "public",
+      "seeds": [1, 2],
+      "description": "Docs/AGENTS converge style task (synthetic contract slot)."
+    },
+    {
+      "taskRef": "synthetic/docs-changelog-summary",
+      "class": "docs",
+      "split": "public",
+      "seeds": [1, 2, 3],
+      "description": "Changelog-style documentation task."
+    },
+    {
+      "taskRef": "synthetic/frontend-welcome-render",
+      "class": "frontend",
+      "split": "public",
+      "seeds": [1, 2],
+      "description": "Frontend render/accessibility contract slot."
+    },
+    {
+      "taskRef": "features/F-2026-003/empty-profile-regression",
+      "class": "bugfix",
+      "split": "private",
+      "seeds": [1, 2, 3],
+      "featureId": "F-2026-003",
+      "description": "Empty profile id/displayName regression (private selection)."
+    },
+    {
+      "taskRef": "features/F-2026-004/versioned-bootstrap",
+      "class": "bootstrap",
+      "split": "private",
+      "seeds": [1, 2],
+      "featureId": "F-2026-004",
+      "description": "Versioned self-host bootstrap canary (private)."
+    },
+    {
+      "taskRef": "synthetic/backend-test-welcome-api",
+      "class": "backend-test",
+      "split": "private",
+      "seeds": [1, 2, 3],
+      "description": "Backend API test workflow contract slot."
+    },
+    {
+      "taskRef": "synthetic/refactor-outcome-tokens",
+      "class": "refactor",
+      "split": "private",
+      "seeds": [1, 2],
+      "description": "Bounded refactor around evidence token naming."
+    },
+    {
+      "taskRef": "synthetic/implement-ready-planner-gate",
+      "class": "implement",
+      "split": "private",
+      "seeds": [1, 2, 3],
+      "description": "Ready Planner artifact-gate implementation slot."
+    },
+    {
+      "taskRef": "synthetic/heldout-docs-handoff",
+      "class": "docs",
+      "split": "held_out",
+      "seeds": [1, 2],
+      "description": "Held-out docs/handoff generalization slot; never used for candidate generation."
+    },
+    {
+      "taskRef": "synthetic/heldout-bugfix-gate",
+      "class": "bugfix",
+      "split": "held_out",
+      "seeds": [1, 2, 3],
+      "description": "Held-out bugfix gate; promotion-only signal."
+    },
+    {
+      "taskRef": "synthetic/heldout-fullstack-smoke",
+      "class": "fullstack",
+      "split": "held_out",
+      "seeds": [1, 2],
+      "description": "Held-out fullstack smoke; not for public feedback."
+    },
+    {
+      "taskRef": "synthetic/heldout-bootstrap-slot",
+      "class": "bootstrap",
+      "split": "held_out",
+      "seeds": [1, 2, 3],
+      "description": "Held-out bootstrap identity/slot discipline."
+    }
+  ]
+}

package/docs/templates/evaluation/matrix-dag-dry-run-v1.json

@@ -0,0 +1,21 @@
+{
+  "version": 3,
+  "title": "eval-matrix-cell-dry-run",
+  "runtimeContract": {
+    "schemaVersion": 1,
+    "agentRuntime": "pi-only",
+    "repairWriterProtocol": "explicit-node-v1"
+  },
+  "tasks": [
+    {
+      "id": "matrix-cell-static",
+      "depends_on": [],
+      "complexity": "LOW",
+      "executor": "static",
+      "subtask_prompt": "Matrix cell placeholder; evaluation binding is injected by campaign matrix.",
+      "static": {
+        "resultMarkdown": "matrix cell dry-run placeholder"
+      }
+    }
+  ]
+}

package/docs/templates/evaluation/matrix-fixture-v1.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "defaultVerifyPassed": false,
+  "results": [
+    {
+      "split": "public",
+      "verifyPassed": true
+    }
+  ]
+}

package/docs/templates/evaluation/private-verifier-dogfood-v0.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "privateVerifierId": "pv-dogfood-v0",
+  "createdAt": "2026-07-19T00:00:00.000Z",
+  "description": "M4 dogfood private verifier. Controller-only; never enter candidate contentRefs/prompts/skill snapshots.",
+  "checks": [
+    {
+      "checkId": "node-version-ok",
+      "kind": "shell",
+      "command": ["node", "-e", "process.exit(process.versions.node ? 0 : 1)"],
+      "cwd": ".",
+      "timeoutMs": 15000,
+      "expectedExitCode": 0
+    }
+  ]
+}

package/docs/templates/exec-plan.md

@@ -0,0 +1,66 @@
+# 执行计划模板
+
+> 进行中：`docs/exec-plans/active/YYYY-MM-DD-<topic>.md`。完成后原名移入 `docs/exec-plans/completed/`，并更新两边 README；handoff 写 `docs/progress/`，验证证据写 `docs/reports/`。
+
+## 标题
+
+## 状态
+
+- draft / active / blocked / completed
+
+## 背景
+
+- 当前问题或机会是什么：
+- 为什么值得现在做：
+
+## 目标（Objective）
+
+- 本计划希望达成什么结果：
+
+## 范围（Scope）
+
+- 包含：
+- 不包含：
+
+## 约束（Constraints）
+
+- 架构/契约约束：
+- 时间/风险约束：
+- 验证约束：
+
+## 里程碑（Milestones）
+
+| ID | Milestone | Status | Exit Criteria |
+|----|-----------|--------|---------------|
+| M1 |           | todo   |               |
+
+## 工作分解（Work Breakdown）
+
+| ID | Work Item | Status | Notes |
+|----|-----------|--------|-------|
+| W1 |           | todo   |       |
+
+## 验证关口（Verification Gates）
+
+- [ ] 文档/契约已同步
+- [ ] 最低必要测试已通过
+- [ ] 关键路径已验证
+- [ ] 风险与未覆盖项已记录
+
+## 风险 / 阻塞项
+
+- 风险：
+- 阻塞：
+
+## 回退 / 恢复（Rollback / Recovery）
+
+- 如何回退：
+- 回退后如何恢复基线：
+
+## Open Questions
+
+- 
+
+## 推荐下一步
+
+- 

package/docs/templates/feature-spec.md

@@ -0,0 +1,53 @@
+# Feature Spec 模板
+
+## 标题
+
+## 状态
+
+- draft / active / completed
+
+## 背景（Background）
+
+- 问题背景：
+- 用户/协作者痛点：
+- 与现有系统的关系：
+
+## 目标（Goal）
+
+- 本 feature 要实现什么：
+
+## 非目标（Non-goals）
+
+- 明确本轮不做什么：
+
+## 关键场景 / 用户路径
+
+1. 
+2. 
+3. 
+
+## Feature List
+
+| ID | Feature | Priority | Status | Acceptance | Notes |
+|----|---------|----------|--------|------------|-------|
+| F1 |         | High     | todo   |            |       |
+
+## 依赖（Dependencies）
+
+- 上游依赖：
+- 下游影响：
+- 文档/契约依赖：
+
+## 风险（Risks）
+
+- 
+
+## 验证说明（Verification Notes）
+
+- 最低建议验证：
+- 加强验证：
+- 关键手工路径：
+
+## Open Questions
+
+- 

package/docs/templates/frontend-design-contract.md

@@ -0,0 +1,68 @@
+# 前端设计契约模板
+
+本模板只承载**通用编写协议 + 三要素 + fail-closed 规则**，不包含任何具体业务组件名、项目专属路径或项目专属命令。设计契约在进入实现前由 `frontend-plan-pi` 落入结构化 implementation contract，`frontend-design-review-pi` 按本模板逐节审查；每一节都要给出「**要写什么** / **DAG 如何消费** / **缺失/冲突时 fail-closed**」三要素。
+
+## 页面目标
+
+- **要写什么**：写清每个目标页面的职责、用户到达该页面的目的与成功结果，逐页列出，与需求.md 的用户目标/目标页面一一对应。
+- **DAG 如何消费**：`frontend-plan-pi` 据它确定 `targets.routes` 与每页的实现步骤，`frontend-design-review-pi` 据它核对范围与需求一致性。
+- **缺失/冲突时 fail-closed**：页面目标与需求不一致、缺页或目标含糊（无成功结果）时阻塞，不得自行补页或改目标。
+
+## 信息结构
+
+- **要写什么**：写清每页展示的信息层级与数据来源（字段、分组、优先级、空/错误占位），接口数据与静态文案分开写。
+- **DAG 如何消费**：`frontend-plan-pi` 据它安排组件数据流与状态展示，`frontend-design-review-pi` 据它核对接口字段映射。
+- **缺失/冲突时 fail-closed**：信息层级缺失、数据来源不可追溯、与接口字段冲突时阻塞，不得臆造字段或层级。
+
+## 组件拆分
+
+- **要写什么**：把页面拆成组件树，逐组件写职责、复用边界、props/状态归属与可替换点；复用现有设计系统组件时引用其来源路径。
+- **DAG 如何消费**：`frontend-plan-pi` 据它确定 `targets.files` 与实现顺序，`frontend-design-review-pi` 据它审查拆分是否越界/重复。
+- **缺失/冲突时 fail-closed**：组件边界不清、同一职责被拆到多处、或与设计规范冲突时阻塞，不得按邻近代码自行决定复用。
+
+## 交互规则
+
+- **要写什么**：逐条写清每个交互的触发、预期行为、状态变化与可恢复性（对应需求.md 的交互要求）。
+- **DAG 如何消费**：`frontend-plan-pi` 据它填充 `interactions[]`（`trigger` + `expectedBehavior`），verify 用行为命令断言。
+- **缺失/冲突时 fail-closed**：交互无预期行为、与 UI 状态冲突、或不可自动化断言时阻塞。
+
+## UI 状态
+
+- **要写什么**：逐状态（loading/empty/error/success/disabled）写清触发条件、展示内容与转移；不适用状态写 `N/A` + 非空理由。
+- **DAG 如何消费**：进入 implementation contract 的 `uiStates[]`，verify 逐状态断言，`frontend-review-pi` 据它核对实现是否遗漏状态。
+- **缺失/冲突时 fail-closed**：适用状态缺失预期、N/A 无理由、或状态展示与交互/接口状态冲突时阻塞。
+
+## Mock / API 策略
+
+策略枚举固定为 `native | browser-intercept | request-adapter | not-needed | blocked`，与 runtime Mock 语义一致：`blocked` 永远不通过（缺少/冲突接口契约、路径或依赖未授权、无法证明生产默认关闭、固定验证入口无法覆盖、或唯一方案是注释真实请求时必须选它）；`not-needed` 必须有后端可用或任务不涉及远程接口的真实/无远程证据，且固定 behavior 入口能覆盖相应行为；显式 `policy=required` 不接受 `not-needed`。契约只接受当前 policy 允许的非 `blocked` 首行。
+
+- **接口文档或 schema — 要写什么**：引用接口文档/schema 路径与版本，作为 fixture 与字段映射的唯一来源。**DAG 如何消费**：`frontend-plan-pi` 据它冻结 endpoint/fixture 映射，prewrite gate 校验 fixture 可追溯。**缺失/冲突时 fail-closed**：无文档/schema、字段冲突时选 `blocked`，不得自行发明接口。
+- **策略**：只写枚举中的一个值：`native | browser-intercept | request-adapter | not-needed | blocked`。
+- **endpoint / fixture / UI 状态映射 — 要写什么**：逐 endpoint 列 method、path、fixture 路径与消费组件，并映射到 UI 状态。**DAG 如何消费**：写入 `mockApi.endpoints[]`（method/path/fixture/consumer），非 `not-needed` 策略要求每个 endpoint 都有 fixture 与 consumer。**缺失/冲突时 fail-closed**：非 `not-needed` 却缺 fixture/consumer、endpoint 与 UI 状态映射不一致时阻塞。
+- **显式启用方式与 production 默认关闭边界 — 要写什么**：写清真实请求为默认路径、Mock 仅通过显式开关（环境变量/构建开关）启用的具体边界。**DAG 如何消费**：`productionDefaultOff` 恒为 `true`，`frontend-review-pi` 检查是否注释真实请求或默认开启 Mock。**缺失/冲突时 fail-closed**：无法证明生产默认关闭、或 Mock 会进入生产入口时选 `blocked`。
+- **DAG 已固化的验证入口 — 要写什么**：引用 DAG 生成时已冻结的 static/behavior/Mock 命令 label，不发明新命令。**DAG 如何消费**：`verificationTarget.commandLabel` 必须逐字落在冻结命令集合内，否则 contract 物化 `invalid-output`。**缺失/冲突时 fail-closed**：策略需要 Mock 验证命令却没有冻结命令时生成期 fail-closed（`no authorized Mock verification commands`）。
+- **Real Integration Gap 与后端就绪后的复验 — 要写什么**：写清当前未联通的真实集成缺口，以及后端就绪后的复验路径。**DAG 如何消费**：进入 `evidenceGaps[]`，closeout 报告 `Real integration: pending`，复验任务 `<task-id>-real-api-integration-verify` 由操作者显式触发。**缺失/冲突时 fail-closed**：把 Mock 证据当真实联调证据时 review 拒绝。
+
+## 样式与设计系统映射
+
+- **要写什么**：写清页面用到的主题/Token、设计系统组件与样式来源（引用具体来源路径），自定义样式与复用样式的边界。
+- **DAG 如何消费**：`frontend-plan-pi` 据它安排样式实现，`frontend-design-review-pi` 据它核对是否与设计系统冲突。
+- **缺失/冲突时 fail-closed**：样式来源缺失、Token/组件冲突、或自定义样式会破坏设计系统时阻塞。
+
+## 响应式范围
+
+- **要写什么**：写清支持的视口范围（desktop/mobile/tablet）与断点、每个断点下的布局差异。
+- **DAG 如何消费**：进入 contract 的 target runtime environment，`frontend-plan-pi` 据它决定响应式策略。
+- **缺失/冲突时 fail-closed**：视口范围与需求运行环境不一致、或断点未覆盖声明环境时阻塞。
+
+## 风险与非目标
+
+- **要写什么**：写清设计上的已知风险、依赖缺口与明确不做/排除的设计范围。
+- **DAG 如何消费**：进入 `evidenceGaps[]` 与 Non-goals，`frontend-review-pi`/closeout 据它保留风险与后续项。
+- **缺失/冲突时 fail-closed**：范围与需求非目标冲突、或风险被隐藏时阻塞。
+
+## OpenSpec 引用块（openspec-citations）
+
+- **要写什么**：在 fenced `json` 契约块之后追加**恰好一个** fenced `openspec-citations` 块，每行一个 JSON `{"path","section","line"}`（`section` 可空串、`line` 为 int 或 null），逐条列出本计划实际读取并应用的每个 openspec 规范文件。
+- **DAG 如何消费**：`frontend-prewrite-gate-shell` 按 fence 语言标签解析该块，并与生效 plan/review 节点的成功 read 事件核验；`cited` 模式下候选未引用 → `openspec-not-cited`，引用无 read 背书 → `openspec-citation-not-read`，块缺失/不可解析 → `openspec-citation-block-unparseable`。
+- **缺失/冲突时 fail-closed**：候选非空而引用块缺失/不可解析、候选未引用、或引用未真实读取时，prewrite gate 以 `retryable-invalid` fail-closed；不要引用未读取的路径，也不要遗漏已读取的 openspec 文件。