@tea-agent/loop-agent 0.22.0 → 0.23.1

package/docs/architecture/system-overview.md

@@ -64,7 +64,7 @@ workflow runtime（调度 Pi / shell / static 节点）
 - `agent-worker console serve|doctor` 提供 loopback Operator Console（默认 `127.0.0.1:8790`）；Happy Path / Interview 策略面、Task Contract 落地与 recovery CTA 已随 **0.17.0–0.17.2** 发布。
 - canonical mutation 只经 sibling 已发布 `loop-agent`（`LoopAgentClient`），不 in-process 跑 DAG kernel。
 - Observe 保持**独立**只读进程（默认 `8787`）；Console 通过 versioned Observe `/api/health`（`schemaVersion`、`repoFingerprint`、route capabilities）做深链 fail-closed，**不** mount / proxy。
-- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
+- openCode 等主会话仍是 Compatibility / Operator Assist，与 Official Console **不等同**。设计锚点：ADR 0005、`docs/design/active/local-operator-console-from-pi-web.md`；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`。
 
 ## 外部边界
 

package/docs/architecture/worker-and-feature.md

@@ -2,7 +2,7 @@
 
 本页说明 `agent-worker` 如何通过冻结的已发布 `loop-agent` 子进程执行 DAG（不 in-process import runtime kernel），以及其上的产品线 read model：TaskSpec、Task Pool、Feature 与统一 Operator Console（Operate + Inspect）。边界契约权威是 `runtime-boundaries.md` §Worker adapter。
 
-**维护校准：2026-07-22 / `@tea-agent/loop-agent@0.18.0`** — 统一 Operator Console（Operate + Inspect）已落地；细节以 `CHANGELOG.md` 与 active unify plan 为准。
+**维护校准：2026-07-25 / `@tea-agent/loop-agent@0.23.1`** — 统一 Operator Console（Operate + Inspect）、恢复操作面与自适应 liveness 已落地；细节以 `CHANGELOG.md` 与对应 active/completed plan 为准。
 
 ## 核心事实：子进程，非 in-process
 
@@ -25,7 +25,7 @@
 - 显式 `worker.timeout_ms` → hard kill（可 capped），观察到 exit 后可报 `timedOut`。
 - 客户端 `onHeartbeat` 仍是监管心跳，不等于 Pi meaningful progress。
 
-设计真源：`docs/design/dag-adaptive-liveness-and-supervision.md`。
+设计真源：`docs/design/active/dag-adaptive-liveness-and-supervision.md`。
 
 ## controller identity（冻结的已发布 controller）
 
@@ -62,7 +62,7 @@ controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨
 - schema/validate：`src/worker/task-spec/{schema,validate}.ts`。
 - 校验验收条件、依赖、验证命令；`agent-worker task validate-feature` 等用之。
 - **0.16.0+**：可选 `execution.workflow` 映射到 loop-agent `taskKind`（如 agent-dag / frontend-implementation / backend-test / frontend-test）；typed Task Outcome 与 artifact-aware Ready 门禁见 completed `2026-07-19-taskspec-workflow-routing.md`。
-- 文档映射镜像：`docs/design/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
+- 文档映射镜像：`docs/design/active/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
 
 ### Task Pool
 

package/docs/governance/README.md

@@ -0,0 +1,15 @@
+# 工程治理
+
+这里放的是“怎么推进一次工作”的长期规则。开始实现前先读工作流，需要选择验证命令时再看验证矩阵；三份方法论文档用于测试、完成声明和故障排查。
+
+## 入口
+
+- [`development-principles.md`](development-principles.md)：工程原则与完成纪律。
+- [`feature-workflow.md`](feature-workflow.md)：会话治理、taskKind、profile 与 Agent DAG 路径。
+- [`verification-matrix.md`](verification-matrix.md)：按变更类型选择验证命令。
+- [`harness-methodology-tdd.md`](harness-methodology-tdd.md)：测试先行的方法与边界。
+- [`harness-methodology-verification.md`](harness-methodology-verification.md)：如何用新鲜命令结果支持完成声明。
+- [`harness-methodology-debugging.md`](harness-methodology-debugging.md)：系统化定位故障，不用猜测代替证据。
+- [`document-review-policy.md`](document-review-policy.md)：文档 freshness、`reviewTier` 与 `lastReviewed` 更新边界。
+
+架构事实见 [`../architecture/README.md`](../architecture/README.md)，运行手册见 [`../runtime/README.md`](../runtime/README.md)，日常维护操作见 [`../operations/README.md`](../operations/README.md)。

package/docs/{harness-methodology-debugging.md → governance/harness-methodology-debugging.md}

@@ -10,6 +10,27 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 没有完成 Phase 1（根因调查），就不能提出任何修复方案。修症状 = 失败。
 
+## 前置：构建反馈回路（Phase 1 的地基）
+
+在读代码猜原因、列假设或动手修复之前，先建立一条**快速、确定性、Agent 可运行**的 pass/fail 信号。后续复现、假设、插桩和修复都消费这条回路，而不是依赖聊天里的印象。
+
+按优先级选用（能用更靠前的就不要降级）：
+
+1. 失败测试（已有或最小新增）
+2. HTTP / API 脚本（固定输入 → 断言状态码或响应）
+3. CLI fixture / snapshot
+4. 浏览器脚本（确定性交互 + 断言）
+5. Trace / log replay
+6. 一次性本地 harness（最小复现命令）
+7. Property / fuzz（非确定性边界）
+8. `git bisect run`（回归定位）
+9. 新旧版本 differential
+10. 结构化 HITL 脚本（仅当自动化回路不可得，且人工步骤可重复）
+
+把回路本身当作产品优化：更快、更锋利、更确定性。间歇性问题先提高复现率，再进入根因调查。
+
+**不能建立回路时：停下。** 请求缺失的环境、artifact、凭据或临时插桩许可；不要在没有 pass/fail 信号时继续猜。
+
 ## 何时使用
 
 适用于任何技术问题：
@@ -28,7 +49,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 ## 四阶段流程
 
-每个阶段必须完成才能进入下一个。
+每个阶段必须完成才能进入下一个。反馈回路是 Phase 1 的地基，不是第五阶段。
 
 ### Phase 1：根因调查
 
@@ -113,6 +134,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 ## Red Flags：停止并回到 Phase 1
 
 如果你发现自己这样想：
+- "没有 pass/fail 回路，先读代码猜原因"
 - "先快速修一下，后面再调查"
 - "试试改 X 看看行不行"
 - "一次改多个东西然后跑测试"
@@ -121,13 +143,14 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 - "不太确定但可能有用"
 - "再试一个修复"（已经试了 2+ 次）
 
-**以上任何一种 → 停止。回到 Phase 1。**
+**以上任何一种 → 停止。回到反馈回路 / Phase 1。**
 
 ## 和 Harness 工作流的对齐
 
 | 调试阶段 | Harness 步骤 |
 |---------|-------------|
-| Phase 1：根因调查 | Baseline：先验证当前基线，确认 bug 是可复现的 |
+| 反馈回路 | Baseline / Reproduction evidence：先有可重复的 pass/fail 信号 |
+| Phase 1：根因调查 | Baseline：确认 bug 可复现，并收集证据 |
 | Phase 2：模式分析 | Orient：读相关代码、文档、测试，找参考 |
 | Phase 3：假设测试 | Contract：写清修复假设和验证方法 |
 | Phase 4：实现 | Implement → Verify（TDD：先写失败测试） |
@@ -137,6 +160,7 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 | 阶段 | 关键活动 | 成功标准 |
 |------|---------|---------|
+| 0. 反馈回路 | 建立快速确定性 pass/fail 信号 | 有可重复命令与退出码 |
 | 1. 根因 | 读错误、复现、查变更、收集证据 | 理解 WHAT 和 WHY |
 | 2. 模式 | 找工作中的例子、对比 | 识别差异 |
 | 3. 假设 | 形成理论、最小测试 | 确认或新假设 |

package/docs/init-surface.manifest.json

@@ -8,10 +8,10 @@
     "harness.json",
     "bin/loop-agent.js",
     "docs/README.md",
-    "docs/harness-methodology-tdd.md",
-    "docs/harness-methodology-verification.md",
-    "docs/harness-methodology-debugging.md",
-    "docs/local-development-environment.md",
+    "docs/governance/harness-methodology-tdd.md",
+    "docs/governance/harness-methodology-verification.md",
+    "docs/governance/harness-methodology-debugging.md",
+    "docs/operations/local-development-environment.md",
     "docs/init-surface.manifest.json",
     "docs/architecture/runtime-boundaries.md",
     "docs/architecture/README.md",
@@ -22,6 +22,7 @@
     "docs/architecture/evolution.md",
     "docs/skills/README.md",
     "docs/skills/vetted-skill-registry.md",
+    "docs/templates/README.md",
     "docs/templates/init-evolution-review.md",
     "docs/templates/exec-plan.md",
     "docs/templates/production-readiness-checklist.md",
@@ -63,6 +64,9 @@
     "skills/test-driven-development/SKILL.md",
     "skills/code-review-core/SKILL.md",
     "skills/init-capability-evolution/SKILL.md",
+    "skills/grill-with-docs/SKILL.md",
+    "skills/grill-with-docs/context-format.md",
+    "skills/grill-with-docs/adr-format.md",
     "skills/webapp-testing/SKILL.md",
     "skills/playwright-cli/SKILL.md",
     "skills/playwright-cli-case-generator/SKILL.md",
@@ -91,6 +95,10 @@
     "docs/feature-workflow.md",
     "docs/verification-matrix.md",
     "docs/loop-agent-harness.md",
+    "docs/harness-methodology-tdd.md",
+    "docs/harness-methodology-verification.md",
+    "docs/harness-methodology-debugging.md",
+    "docs/templates/README.md",
     "docs/templates/init-evolution-review.md",
     "docs/templates/production-readiness-checklist.md",
     "docs/templates/frontend-task-requirement.md",
@@ -133,6 +141,9 @@
     ".agents/skills/test-driven-development/SKILL.md",
     ".agents/skills/code-review-core/SKILL.md",
     ".agents/skills/init-capability-evolution/SKILL.md",
+    ".agents/skills/grill-with-docs/SKILL.md",
+    ".agents/skills/grill-with-docs/context-format.md",
+    ".agents/skills/grill-with-docs/adr-format.md",
     ".agents/skills/webapp-testing/SKILL.md",
     ".agents/skills/playwright-cli/SKILL.md",
     ".agents/skills/playwright-cli-case-generator/SKILL.md",
@@ -161,6 +172,10 @@
     "docs/feature-workflow.md": "generated",
     "docs/verification-matrix.md": "generated",
     "docs/loop-agent-harness.md": "generated",
+    "docs/harness-methodology-tdd.md": "copied",
+    "docs/harness-methodology-verification.md": "copied",
+    "docs/harness-methodology-debugging.md": "copied",
+    "docs/templates/README.md": "copied",
     "docs/templates/init-evolution-review.md": "copied",
     "docs/templates/production-readiness-checklist.md": "copied",
     "docs/templates/frontend-task-requirement.md": "copied",
@@ -204,6 +219,9 @@
     ".agents/skills/test-driven-development/SKILL.md": "copied",
     ".agents/skills/code-review-core/SKILL.md": "copied",
     ".agents/skills/init-capability-evolution/SKILL.md": "copied",
+    ".agents/skills/grill-with-docs/SKILL.md": "copied",
+    ".agents/skills/grill-with-docs/context-format.md": "copied",
+    ".agents/skills/grill-with-docs/adr-format.md": "copied",
     ".agents/skills/webapp-testing/SKILL.md": "copied",
     ".agents/skills/playwright-cli/SKILL.md": "copied",
     ".agents/skills/playwright-cli-case-generator/SKILL.md": "copied",

package/docs/operations/README.md

@@ -0,0 +1,12 @@
+# 维护与协作
+
+这里收录维护仓库时会直接照着执行的操作手册。
+
+## 入口
+
+- [`local-development-environment.md`](local-development-environment.md)：本地环境、Windows 差异和常见排障。
+- [`branch-merge-guideline.md`](branch-merge-guideline.md)：按风险选择合并模式并留下 source-SHA 证据。
+- [`github-collaboration.md`](github-collaboration.md)：仓库内 GitHub 协作约定。
+- [`production-readiness.md`](production-readiness.md)：交付前的生产就绪判断。
+
+验证命令仍以 [`../governance/verification-matrix.md`](../governance/verification-matrix.md) 为准。

package/docs/{local-development-environment.md → operations/local-development-environment.md}

@@ -1,6 +1,6 @@
 # 本地开发环境排障
 
-本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](verification-matrix.md) 为准。
+本文记录仅与特定开发环境有关、但可能反复影响验证结果的问题。它不是通用工程规则；标准验证命令仍以 [`verification-matrix.md`](../governance/verification-matrix.md) 为准。
 
 ## Cursor Cloud
 

package/docs/skills/vetted-skill-registry.md

@@ -7,23 +7,43 @@ The entries below are local wrappers or existing local skills. They are not whol
 | Skill | Source / Inspiration | Local Path | Supported Roles | Default Use | Risk Notes |
 |---|---|---|---|---|---|
 | `ai-engineering-context` | local existing | `skills/ai-engineering-context/SKILL.md` | scout, default context | default/scout | Read-only engineering context; not a private platform memory skill. |
-| `loop-agent` | local existing | `skills/loop-agent/SKILL.md` | planner, supervisor, closeout | planner/closeout | Long references may be resolved by strict audit with expanded budget; executor behavior unchanged. |
+| `loop-agent` | local existing | `skills/loop-agent/SKILL.md` | planner, supervisor, closeout | planner/closeout | Entry 紧凑在 `perSkillMaxChars=3000` 以内；3 个 required refs 在默认 baseline-v1 budget 下完整 resolved。`command-reference.md` 降级为按需 reference（路由表仍列出），不默认常驻每个 DAG node。 |
 | `agent-worker` | local operator skill | `skills/agent-worker/SKILL.md` | outer-loop operator only | never a default DAG role | Routes Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canary, and failure recovery. Must not launch recursively from DAG leaves or duplicate executor/kernel behavior. |
 | `verification-before-completion` | local wrapper inspired by verification discipline | `skills/verification-before-completion/SKILL.md` | implementer, verifier, closeout | implementer/verifier/closeout | Requires shell evidence before completion claims. |
-| `systematic-debugging` | local wrapper inspired by systematic debugging discipline | `skills/systematic-debugging/SKILL.md` | implementer, verifier | verifier | Advisory prompt guidance only; does not run tools by itself. |
+| `systematic-debugging` | local wrapper inspired by systematic debugging discipline + feedback-loop-first gate | `skills/systematic-debugging/SKILL.md` | implementer, verifier | verifier | Advisory prompt guidance only; does not run tools by itself. Requires pass/fail loop before root-cause guessing; verifier must not cross writer boundaries. |
 | `requesting-code-review` | local existing | `skills/requesting-code-review/SKILL.md` | reviewer | reviewer | Review prompt guidance only. |
-| `test-driven-development` | local wrapper inspired by TDD practice | `skills/test-driven-development/SKILL.md` | implementer | implementer | Does not force tests in mechanical-only docs changes; implementer still follows task contract. |
+| `test-driven-development` | local wrapper inspired by TDD practice + vertical one-test-one-impl cycle | `skills/test-driven-development/SKILL.md` | implementer | implementer | Does not force tests in mechanical-only docs changes; implementer still follows task contract. Forbids batch-all-RED-then-all-GREEN. |
 | `code-review-core` | local wrapper inspired by code review practice | `skills/code-review-core/SKILL.md` | reviewer | reviewer | No external tools or network by default. |
 | `codebase-scout` | local wrapper | `skills/codebase-scout/SKILL.md` | scout | scout | Read-only reconnaissance guidance. |
 | `init-capability-evolution` | local wrapper | `skills/init-capability-evolution/SKILL.md` | supervisor, maintenance | optional | Used only when changes may affect target-project initialization, package surface, or init projection rules. |
+| `grill-with-docs` | local operator skill adapted from domain grilling + ADR/glossary discipline | `skills/grill-with-docs/SKILL.md` | explicit interactive operator only | never a default DAG role | Resolves decisions via `harness.json.governanceRoot`; required refs `context-format.md` / `adr-format.md`; respects writeSet; not in `DEFAULT_SKILLS_BY_ROLE`. |
 | `webapp-testing` | local wrapper inspired by frontend/browser testing practice | `skills/webapp-testing/SKILL.md` | verifier, reviewer | optional | Only applies when task explicitly involves browser-rendered behavior; no default Playwright/Semgrep execution. |
 | `playwright-cli` | repo-local Playwright CLI instructions | `skills/playwright-cli/SKILL.md` | FE-test case executor | FE-test only | Direct browser commands require isolated test environments, per-case evidence paths, and explicit credential/data handling. |
 | `playwright-cli-case-generator` | adapted from the repo-local playwright CLI case-generator contract | `skills/playwright-cli-case-generator/SKILL.md` | FE-test case generator | FE-test only | Generates Markdown cases and a compact manifest from RAG facts; does not execute browsers, create test code, or invent API/data constraints. |
 
+## Verification placement taxonomy
+
+Authoring vocabulary for where a check or verification skill should live. Prefer deterministic placement over model soft-chaining. Do **not** add free-text placement comments to every `SKILL.md`, and do **not** extend frontmatter schema until a runtime/checker consumer exists.
+
+| placement | 本项目映射 | 何时选用 |
+|---|---|---|
+| **standalone** | 显式 operator skill / 独立只读检查（如 `loop-agent doctor`、`docs audit`、`stats context`） | 跨任务聚合、repo/runtime 健康、不绑定单一 DAG 节点 |
+| **embedded** | DAG 节点自带 shell gate、role skill 或节点内 verify | 节点完成条件可本地判定；失败应阻断该节点 |
+| **chained** | 可 `dag validate` 的 DAG dependencies / ranks；不用模型软调用串联 | 多步顺序或分叉必须可机读、可恢复 |
+| **PR-bound** | CI / GitHub workflow（`scripts/ci.sh`、repo checks） | 合并前门禁；仅在团队流程稳定后启用 |
+
+约束：
+
+- Skill 软 chaining **不是**主流程；验证循环优先进入 DAG topology、shell gates、review nodes 与 CI。
+- Registry / authoring guide 使用本表做决策说明即可；placement 不是 runtime 字段。
+
 ## Vetting Rules
 
 - Default role mappings may reference only repo-local skills that resolve cleanly under `dag validate --strict-skills`.
 - `agent-worker` is explicitly outside default role mappings. Its trigger description must cover `agent-worker`, Feature Packet, TaskSpec, Task Pool, self-host/candidate and the `loop-agent` routing boundary; `scripts/check-skill-entry.sh` enforces this public entry contract.
+- `grill-with-docs` is an explicit interactive operator skill only; it must stay outside `DEFAULT_SKILLS_BY_ROLE`.
 - Optional/security/web skills remain task- or profile-specific until their tool, network, credential, and write behavior is reviewed.
 - This registry records source inspiration, not license clearance for vendored third-party content. Vendoring requires a separate license/security review.
 - `SKILL.md` is the entry point. References must be declared in frontmatter and stay within the skill directory.
+- External engineering methodologies may inspire local skill text, but must follow ADR 0006: fuse into existing docs/skills/templates/checks/DAG; do not create parallel governance trees.
+- When choosing where a verification lives, use the placement taxonomy above; do not invent a parallel checklist tree.

package/docs/templates/README.md

@@ -0,0 +1,55 @@
+# 模板库
+
+本目录保存可复用的执行计划、报告、DAG、schema、评测与产品线初始化模板。这里的文件是“可以拿来使用的起点”，不是某次任务的执行证据。
+
+`docs/templates/README.md` 随 npm 包发布，并由 full init 复制到目标治理根；旧项目可通过 `init check-update` / `init update --apply-safe` 追踪缺失的模板入口和受管模板。源仓专用的文档治理脚本不会默认复制到目标项目。
+
+## 通用任务、报告与治理
+
+- `project-start-checklist.md` — 开工检查。
+- `feature-spec.md`、`sprint-contract.md` — 功能规格与短周期合同。
+- `exec-plan.md`、`progress-log.md`、`qa-report.md` — 执行计划、交接与验证报告。
+- `adr.md` — 架构决策记录。
+- `branch-merge-report.md` — source-SHA 分支合并报告。
+- `init-evolution-review.md` — 初始化能力演化审查。
+- `production-readiness-checklist.md` — Production Readiness 检查。
+- `worker-dogfood-setup.md`、`worker-dogfood-evidence.md` — 已发布控制器下的 Worker dogfood 设置与证据。
+- `interactive-ui-round2-experiment.md` — 交互式 UI 对照实验。
+
+## Agent DAG
+
+- `agent-dag.base.json`、`agent-dag.supervised-implementation.json`、`agent-dag.final-verification.json` — 通用 DAG 拓扑。
+- `agent-dag.schema.json`、`agent-dag-report.schema.json`、`agent-dag-decision-envelope.schema.json` — DAG、报告和决策 envelope schema。
+- `hybrid-dag.json` — hybrid DAG 示例。
+- `agent-dag-authority-surface-audit.prompt.md` — 权威面审查提示。
+- `agent-dag-decision-gate.prompt.md`、`agent-dag-decision-gate-dogfood-report.md` — 决策门与 dogfood 报告。
+- `agent-dag-process-supervisor.prompt.md` — 过程监督提示。
+- `agent-dag-review-verdict.prompt.md` — review verdict 提示。
+
+## Backend-test
+
+- `backend-test-dag.json` — backend-test DAG 模板。
+- `backend-test-dag.classify.prompt.md`、`backend-test-dag.generate-pytest.prompt.md`、`backend-test-dag.review-cases.prompt.md`、`backend-test-dag.retrospect.prompt.md` — 分类、生成、审查和复盘提示。
+- `backend-test-analysis.schema.json`、`backend-test-execution.schema.json`、`backend-test-result.schema.json`、`backend-test-case-manifest.schema.json` — 分析、执行、结果与用例清单 schema。
+
+## Frontend
+
+- `frontend-task-requirement.md`、`frontend-task-constraints.md`、`frontend-design-contract.md` — 前端任务输入与设计合同。
+- `frontend-implementation-contract.schema.json` — 前端实现合同 schema。
+- `frontend-test-dag.json` — frontend-test DAG 模板。
+- `frontend-test-dag.retrieve-context.prompt.md`、`frontend-test-dag.generate-cases.prompt.md`、`frontend-test-dag.review-cases.prompt.md`、`frontend-test-dag.review-execution.prompt.md`、`frontend-test-dag.retrospect.prompt.md` — 上下文、用例、审查、执行审查和复盘提示。
+- `frontend-test-case-checklist.md` — 前端测试用例检查清单。
+
+## 知识同步与配置
+
+- `knowledge-sync-dag.json`、`knowledge-graph-bootstrap-dag.json` — 知识同步与图谱初始化 DAG。
+- `knowledge-sync-draft.schema.json` — 知识同步草稿 schema。
+- `harness.schema.json` — `harness.json` 的 IDE JSON Schema。
+
+## 子目录
+
+- `product-line/README.md` — Feature、Task、Acceptance、Graph、Closeout 等产品线骨架。
+- `evaluation/` — 通用评测模板与 schema。
+- `frontend-eval/` — 前端评测模板、功能样例和失败 fixture。
+
+新增、删除或重命名模板时，应同步本页、`docs/init-surface.manifest.json` 和相关 init/package 测试；完整性由 `scripts/check-doc-governance.mjs` 枚举校验。

package/docs/templates/evaluation/agents-map-slim-v1.candidate.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "candidateKind": "prompt",
+  "variant": "slim-v1",
+  "bodyPath": "docs/templates/evaluation/agents-map-slim-v1.md",
+  "bodySha256": "0101b0f85d1a78532d9f226f42ca1d3192d3bd421c82310621915b7f00b16968",
+  "lineCount": 87,
+  "purpose": "Eval Lab context-engineering AGENTS map A/B companion body; JSON contentRef avoids private-verifier token leak"
+}

package/docs/templates/evaluation/agents-map-slim-v1.md

@@ -0,0 +1,87 @@
+<!-- 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（`implement-pi` / `repair-pi`）；`cursor-prompt` 仅为显式手工 one-shot sidecar。
+- DAG 标准路径：Contract → Scout → Plan → Implement → Verify → Closeout/Handoff。
+- 机器校验契约真源：`docs/init-surface.manifest.json`、`docs/architecture/runtime-boundaries.md`、`src/cli/command-definitions.ts`、`skills/loop-agent/`、`scripts/check-*.sh`；本文件只指路。
+- 本仓库既是源项目也是 init 默认模板；新增能力必须判断 npm 内置 vs `loop-agent init` 投影。
+- 委托写入前必须结构化 `task.json.allowedPaths` / `forbiddenPaths`，并审查 DAG writer `writeSet`。
+- Shell 搜索优先 `rg`，按名找文件优先 `fd`；脚本用 Git Bash / 兼容 Bash。
+- 用 loop-agent 迭代本仓库时，控制器必须来自已发布 npm 包（记录实际版本）；启动后不要中途升级；不要用工作区 `npm link` / `npm run dev` 控制可能改 CLI/runtime/package 的任务。
+- 反复出现的约束固化为文档、脚本、检查、测试或模板；禁止占位实现（除非 contract 标明脚手架）。
+- 非微小实现：`exec-plan` 不能替代 Agent DAG；除非用户要求 one-shot 或计划记录 escape hatch，否则改实现前完成 `new-task`、结构化路径、`dag run-task`、`dag validate` 与 writeSet 审查。
+- 不要自行引入外部 SDD/spec-first 等强制平行治理树；以本文件与 `docs/` 为准（ADR 0006）。
+
+## 开始顺序
+
+改文件前必须先完成：
+
+1. `pwd` → 读 `README.md`、`harness.json`、`docs/README.md`；有 `CONTEXT.md` 则读术语表。
+2. 实现类工作继续读：`docs/governance/development-principles.md`、`docs/governance/feature-workflow.md`、`docs/governance/verification-matrix.md`。
+3. 涉及命令/executor/init/skills/发布包/治理检查时继续读：`docs/architecture/runtime-boundaries.md`、`docs/runtime/loop-agent-harness.md`。
+4. 涉及测试纪律/验证声明/调试时继续读：`docs/harness-methodology-*.md`。
+5. 查看最近提交、相关 plan/progress/report；`git status --short --branch`；跑最小基线验证。
+6. 后端/接口/pytest → `taskKind: "backend-test"`（不是 `--profile`）；知识回写 `knowledge-sync`；图谱开荒 `knowledge-graph-bootstrap`。`--profile` 仅 `auto|minimal|standard|reviewed|supervised`。
+7. 看板/observe → `agent-worker console serve --repo . --port 8790`（`/inspect/` 只读）；`observe serve` 仅为兼容入口。
+8. 分支合并 → 先读 `docs/operations/branch-merge-guideline.md`。
+
+## 会话协议
+
+1. Orient → 2. Select（一块）→ 3. Contract → 4. Implement → 5. Verify → 6. Converge Docs → 7. Handoff。
+
+这不是 DAG 节点序列。复杂实现默认 Agent DAG；主 agent 拆任务、写 contract、结构化路径、审查 DAG/writeSet/profile/shell verification。微小任务可用 one-shot escape hatch 并记录边界与验证证据。
+
+## 项目地图
+
+- `CONTEXT.md`：术语表
+- `src/`：运行时；`test/`：Vitest；`bin/loop-agent.js`：CLI
+- `skills/`：源仓库/npm 内置 skills；目标项目只生成 `.agents/skills/`
+- `.harness/`：运行态（tasks/dag-runs/runs 等；init 会 gitignore 运行事实，保留 prompts 与占位）
+- `docs/`：治理；`website/`：用户文档站；`scripts/`：检查与 CI
+
+## 工作规则（增量约束）
+
+- 保留无关用户改动；优先沿用现有 helper/目录边界。
+- 长期决策写入 `docs/`；面向用户变更更新 `CHANGELOG.md`（结果导向中文）。
+- init/投影变更必须同步目标项目生成物与 package assets；init evolution 按 `docs/init-surface.manifest.json` 分级。
+- CLI/skill entry/runtime boundary/发布包变更同步 catalog、脚本与测试。
+- 没有新鲜验证证据时不声明完成；新债写入 plan/progress/report。
+
+## 验证
+
+权威源：`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
+```
+
+文档站变更：`npm run docs:build`。init / architecture / skill entry / pack 定向验证见 verification-matrix。
+
+## 交接
+
+记录：改了什么、为什么、验证命令与结果、契约/文档/测试影响、剩余风险、后续工作。
+
+## 禁止事项
+
+- 未读相关文档就大改；一次混合无关重构/新功能/文档大迁移。
+- 把对话约束当长期知识；缺验证宣称完成；假设系统没有某能力（先搜索）。
+- stub/假数据通路替代交付；把本机绝对路径写入仓库级 AGENTS/README/模板/发布包。
+- 只更新本仓库体验而遗漏目标项目 init 体验。

package/docs/templates/evaluation/agents-map-verbose-v0.candidate.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "candidateKind": "prompt",
+  "variant": "verbose-v0",
+  "bodyPath": "docs/templates/evaluation/agents-map-verbose-v0.md",
+  "bodySha256": "50af8ea3c7058071f249f9b45bd8c05fb1b1aa257ec6b2667aa91346c106cf81",
+  "lineCount": 153,
+  "purpose": "Eval Lab context-engineering AGENTS map A/B companion body; JSON contentRef avoids private-verifier token leak"
+}

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 与理由，否则在改动实现文件前必须完成 `new-task`、结构化 `allowedPaths` / `forbiddenPaths`、`dag run-task` 和 `dag validate`；随后按已校验的 DAG 执行并审查 writer `writeSet`。
+- 禁止占位实现；除非 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"` 再 `dag run-task`；不要用 `--profile backend-test`（CLI 不接受该值，专用模板只走 taskKind）。知识回写用 `taskKind: "knowledge-sync"`（须 `featureId`），图谱开荒用 `taskKind: "knowledge-graph-bootstrap"`。`--profile` 仅表示治理强度：`auto|minimal|standard|reviewed|supervised`。
+13. 如果用户提到"看板"、"observe"、"监控面板"、"启动看板"，使用 `agent-worker console serve --repo . --port 8790` 启动统一 Operator Console；`/inspect/` 提供只读检视。`agent-worker observe serve --repo . --port 8787` 仅为兼容入口。
+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` 的可选值；`dag run-task` 继续使用 `--profile auto` 选择治理等级。仅说“自动化测试”且前后端不明时，先根据任务源和项目技术栈判断，禁止无条件路由。
+- 本地 Operator Console：`agent-worker console serve --repo . --port 8790`，访问 `http://127.0.0.1:8790/`；其中 `/inspect/` 为只读运行检视。默认绑定本机 `127.0.0.1`；可用 `--host 0.0.0.0` / `--debug`，不要直接暴露到公开网络。
+- 面向使用者的新增、修改、删除或修复，应同步更新根目录 `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/hybrid-dag.json

@@ -76,7 +76,7 @@
         "artifacts/**"
       ],
       "outputContract": "Plain Markdown implementation contract summary; no file writes.",
-      "subtask_prompt": "阅读 ./README.md 与 docs/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
+      "subtask_prompt": "阅读 ./README.md 与 docs/runtime/agent-dag-runner.md，返回 10 行以内的实现契约摘要（只读分析 + 文档建议，不改代码/文档/artifacts）。指出是否适合并行 scout 与窄 writeSet。"
     },
     {
       "id": "scout-src",