@tea-agent/loop-agent 0.35.0-beta.2 → 0.35.1-beta.0

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

@@ -1,122 +1,122 @@
-# Worker 与 Feature 架构
-
-本页说明 `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-27 / `@tea-agent/loop-agent@0.24.0`** — 统一 Operator Console（Operate + Inspect）、恢复操作面与自适应 liveness 已落地；细节以 `CHANGELOG.md` 与对应 active/completed plan 为准。
-
-## 核心事实：子进程，非 in-process
-
-`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
-
-| 事实 | 源码入口 |
-| --- | --- |
-| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
-| 执行入口 | `LoopAgentClient.run(args, options)` |
-| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
-| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
-
-`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
-
-### `run-dag` kernel-owned supervision vs explicit hard timeout
-
-`run-task` 启动 `run-dag` 时默认把外层 `timeoutMs` 设为 `0`，由 DAG kernel 负责节点 liveness，**不再**无条件把 30 分钟当作 hard kill：
-
-- 省略 `worker.timeout_ms` → Worker 不设置 wall-clock deadline，并等待 `run-dag` 产生可确认终态。
-- 显式 `worker.timeout_ms` → hard kill（可 capped），观察到 exit 后可报 `timedOut`。
-- 客户端 `onHeartbeat` 仍是监管心跳，不等于 Pi meaningful progress。
-
-设计真源：`docs/design/active/dag-adaptive-liveness-and-supervision.md`。
-
-## controller identity（冻结的已发布 controller）
-
-每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
-
-| 字段 | 含义 |
-| --- | --- |
-| `schemaVersion` | 固定 `1` |
-| `packageName` | 必须为 `@tea-agent/loop-agent` |
-| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
-| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
-| `binarySha256` | `actualEntry` 二进制 hash |
-| `packageVersion` | `package.json` version |
-| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
-
-关键方法：
-
-- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
-- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
-- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
-
-CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
-
-controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
-
-## 独立 CLI
-
-`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe`、`console` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
-
-## 产品线 read model
-
-### TaskSpec 与 workflow 路由
-
-- 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/architecture/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
-
-### Task Pool
-
-- 唯一 runtime root：`src/worker/pool/run-store.ts`
-  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
-- 此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
-- **Feature-scoped identity（ADR 0004）**：canonical Task 身份为复合键 `TaskPoolTaskRef = { featureId, taskId }`。`taskId` 仅 Feature 内唯一；同仓库多 Feature 可安全共用同名 Task ID。
-- **State schema v2**：新 state 必须 `schemaVersion: 2` 且显式携带 `featureId` / `taskId`；canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`。
-- **Consumers**：runner Ready Queue、retry、Follow-up、Feature review、Delivery / Closeout、morning report / metrics 均按 Feature 作用域读写，不得把裸 `taskId` 当作仓库全局唯一键。
-- **Operator**：`pool doctor` 只读 inventory；`pool migrate-state` 默认 dry-run，apply 需 `--owner` + `--reason`；legacy v1 写入路径 fail-closed。
-- batch / retry / morning report 等都基于此根。
-- **Ready Planner**：`batch plan-ready` 零写入预览 selected/deferred/blocked；`run-ready` 冻结 `ready-plan.json`（priority + 产物门禁）。
-
-### Feature（M2 交付闭环）
-
-- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
-- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
-- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
-- 权威证据：`CHANGELOG.md [0.10.0]`、`docs/reports/feature/2026-07-12-m2-completion-audit.md`。
-
-### Final Verification 权威（ADR 0007）
-
-| 入口 | 职责 |
-| --- | --- |
-| `agent-worker feature verify-final` | **唯一** canonical writer：Feature Verification Bundle、`qa-pass.json`、`final-verification.json` |
-| `agent-worker feature advance` | 编排 verify-final → delivery → closeout preview[/apply]（ADR 0007 运维入口） |
-| `agent-worker feature doctor` | 只读诊断证据/Pool/dirty worktree；建议下一步命令 |
-| Feature Packet `FINAL-VERIFY-*`（若保留） | 可选 **local smoke recipe**（样本 `verify:final` / reports）；Task Done ≠ Final Verification Record |
-| `feature delivery` | 重验 verify-final 证据；省略路径时默认 `.harness/task-pool/evidence/<featureId>/{qa-pass,final-verification}.json` |
-| `feature closeout` | 只认 Delivery manifest + Final Verification Record 链 |
-
-禁止把 packet Task 的 smoke 报告或 agent-dag `verify-pi` 结论当作 Delivery 放行条件。
-
-### Inspect（Observe 只读 read model）
-
-- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
-- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
-- Observe read model 是本地只读 Inspect 能力；snapshot 投影失败返回安全错误摘要而非全零健康状态。
-- `agent-worker console` 在同一进程挂载 `/inspect/` 与现有 GET `/api/**`；`/api/health` 返回 `OperatorSurfaceHealthV1`。`observe serve` 已硬下线（REMOVED / exit 2）。
-
-### Local Operator Console（Official，0.18.0）
-
-- 模块：`src/worker/console/`（loopback `serve|doctor`、operator API、Vite SPA）。
-- **已发布能力**：Happy Path / Interview、Task Contract、SSE、同站 Inspect、Run/Recovery 紧凑检视与 recovery CTA 矩阵（无 Cancel / 无主 CTA「直接改代码」）。
-- Inspect 仍复用唯一 Observe read model，GET-only；不复制 snapshot projector。
-- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`（含 `task contract *` / DAG confirm-run）。
-- 证据：completed Console Phase 0.5 / 1–3；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`；ADR 0005。
-
-## 版本化自举的 deterministic canary
-
-源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
-
-## 不变式
-
-- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
-- Worker 不实现 executor、scheduler、prompt 或 write guard。
-- `agent-worker` skill（`.agents/skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。
+# Worker 与 Feature 架构
+
+本页说明 `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-27 / `@tea-agent/loop-agent@0.24.0`** — 统一 Operator Console（Operate + Inspect）、恢复操作面与自适应 liveness 已落地；细节以 `CHANGELOG.md` 与对应 active/completed plan 为准。
+
+## 核心事实：子进程，非 in-process
+
+`agent-worker` 真正执行 DAG 时通过 Node `child_process.spawn` 启动**已发布**的 `loop-agent`，**不** in-process import runtime kernel：
+
+| 事实 | 源码入口 |
+| --- | --- |
+| 客户端 | `src/worker/loop-agent/loop-agent-client.ts` `LoopAgentClient` |
+| 执行入口 | `LoopAgentClient.run(args, options)` |
+| spawn 实现 | `spawnCommand(...)` → `spawn(input.command, input.args, { cwd, env, shell: false, stdio: ["ignore", "pipe", "pipe"] })` |
+| 治理禁止 | `scripts/check-architecture-boundaries.sh` 禁止 `src/worker/**` → `src/{cli,commands,application}/**`，transitional allowlist 为空 |
+
+`shell: false` + 绝对 launch spec（见下）意味着 Worker 不走 PATH 重新解析，也不在当前进程内加载 CLI command 实现。
+
+### `run-dag` kernel-owned supervision vs explicit hard timeout
+
+`run-task` 启动 `run-dag` 时默认把外层 `timeoutMs` 设为 `0`，由 DAG kernel 负责节点 liveness，**不再**无条件把 30 分钟当作 hard kill：
+
+- 省略 `worker.timeout_ms` → Worker 不设置 wall-clock deadline，并等待 `run-dag` 产生可确认终态。
+- 显式 `worker.timeout_ms` → hard kill（可 capped），观察到 exit 后可报 `timedOut`。
+- 客户端 `onHeartbeat` 仍是监管心跳，不等于 Pi meaningful progress。
+
+设计真源：`docs/design/active/dag-adaptive-liveness-and-supervision.md`。
+
+## controller identity（冻结的已发布 controller）
+
+每次写入型 Feature/batch/Task/final verification 在任何目标仓库或 Task Pool 状态写入前，`LoopAgentClient` 解析并冻结 schemaVersion 1 identity（`ControllerIdentityV1`，定义在 `src/shared/package-metadata.ts`）：
+
+| 字段 | 含义 |
+| --- | --- |
+| `schemaVersion` | 固定 `1` |
+| `packageName` | 必须为 `@tea-agent/loop-agent` |
+| `binName` / `requested` / `entry` / `realEntry` | 入口解析链（realEntry 经 `realpathSync`） |
+| `launch.command` / `launch.argsPrefix` | 直接可执行的绝对 launch spec |
+| `binarySha256` | `actualEntry` 二进制 hash |
+| `packageVersion` | `package.json` version |
+| `packageFingerprint` | 覆盖 `package.json`、`bin/**`、`dist/**`、`.agents/skills/**` 的 portable fingerprint（`computePackageFingerprint`） |
+
+关键方法：
+
+- `resolveIdentity()`（`loop-agent-client.ts`）：首次解析并冻结 identity；`this._identityResolved = true`。
+- `assertControllerIdentityUnchangedBeforeSpawn(identity)`（`loop-agent-client.ts`）：**每次 spawn 前**重验，漂移即 throw（`run` 与 `runCommand` 路径都调）。
+- `getIdentity()` / `observeReportedVersion(reportedVersion)`：读取/校验子进程回报的版本须与 `packageVersion` 一致。
+
+CLI 层（`src/worker/cli.ts`）在写入型命令传 `resolveIdentity: true` 构造 `LoopAgentClient`，并支持 `--expected-controller-version` / `--expected-controller-fingerprint` fail-fast（见 `src/worker/preflight.ts`）。
+
+controller identity 与 DAG skill snapshot 是两个不同冻结层（前者跨 Worker/Task Pool/Feature 生命周期，后者单个 DAG run），见 `runtime-boundaries.md` §版本化自举边界。
+
+## 独立 CLI
+
+`agent-worker` 是独立 CLI（`bin/agent-worker.js` → `src/worker/cli.ts`），有自己的命令面（`task`、`batch`、`feature`、`report`、`observe`、`console` 等）。它**不是**第二套 executor 或 DAG kernel；它编排产品线 Task 并把执行委托给 `loop-agent` 子进程。
+
+## 产品线 read model
+
+### TaskSpec 与 workflow 路由
+
+- 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/architecture/taskspec-to-loop-agent-mapping.md`（runtime 真源仍在 `src/worker/` 与 materialize 路径）。
+
+### Task Pool
+
+- 唯一 runtime root：`src/worker/pool/run-store.ts`
+  `TASK_POOL_RELATIVE_ROOT = ".harness/task-pool"`（ADR 0002）。
+- 此前的顶层 Task Pool 位置不读取、不迁移、不合并、不重映射。
+- **Feature-scoped identity（ADR 0004）**：canonical Task 身份为复合键 `TaskPoolTaskRef = { featureId, taskId }`。`taskId` 仅 Feature 内唯一；同仓库多 Feature 可安全共用同名 Task ID。
+- **State schema v2**：新 state 必须 `schemaVersion: 2` 且显式携带 `featureId` / `taskId`；canonical 路径为 `.harness/task-pool/states/<featureId>/<taskId>.json`。
+- **Consumers**：runner Ready Queue、retry、Follow-up、Feature review、Delivery / Closeout、morning report / metrics 均按 Feature 作用域读写，不得把裸 `taskId` 当作仓库全局唯一键。
+- **Operator**：`pool doctor` 只读 inventory；`pool migrate-state` 默认 dry-run，apply 需 `--owner` + `--reason`；legacy v1 写入路径 fail-closed。
+- batch / retry / morning report 等都基于此根。
+- **Ready Planner**：`batch plan-ready` 零写入预览 selected/deferred/blocked；`run-ready` 冻结 `ready-plan.json`（priority + 产物门禁）。
+
+### Feature（M2 交付闭环）
+
+- review/run/approve-followup/delivery/closeout/verify-final：`src/worker/feature/{review,run}.ts` 及相关。
+- Follow-up：`src/worker/` 下 draft-followup + approve-followup 事务，覆盖全部失败分类（可执行/Spec/Risk/Human/EnvFailure）。
+- Delivery / Closeout：clean Delivery HEAD 上生成 canonical QA/最终验证证据、Delivery Package、Acceptance Coverage、PR 草稿；Closeout 默认预览，显式 `--apply --owner` 才原子写回。
+- 权威证据：`CHANGELOG.md [0.10.0]`、`docs/reports/feature/2026-07-12-m2-completion-audit.md`。
+
+### Final Verification 权威（ADR 0007）
+
+| 入口 | 职责 |
+| --- | --- |
+| `agent-worker feature verify-final` | **唯一** canonical writer：Feature Verification Bundle、`qa-pass.json`、`final-verification.json` |
+| `agent-worker feature advance` | 编排 verify-final → delivery → closeout preview[/apply]（ADR 0007 运维入口） |
+| `agent-worker feature doctor` | 只读诊断证据/Pool/dirty worktree；建议下一步命令 |
+| Feature Packet `FINAL-VERIFY-*`（若保留） | 可选 **local smoke recipe**（样本 `verify:final` / reports）；Task Done ≠ Final Verification Record |
+| `feature delivery` | 重验 verify-final 证据；省略路径时默认 `.harness/task-pool/evidence/<featureId>/{qa-pass,final-verification}.json` |
+| `feature closeout` | 只认 Delivery manifest + Final Verification Record 链 |
+
+禁止把 packet Task 的 smoke 报告或 agent-dag `verify-pi` 结论当作 Delivery 放行条件。
+
+### Inspect（Observe 只读 read model）
+
+- 模块：`src/worker/observe/`、`src/worker/observability/{read-model,event-store}.ts`。
+- 全局快照：`buildGlobalSnapshot({ repoRoot })`（`src/worker/observability/read-model.ts`），是 **derived** 视图，消费 `.harness/` 与 Task Pool 事实，**不**改变执行成败。
+- Observe read model 是本地只读 Inspect 能力；snapshot 投影失败返回安全错误摘要而非全零健康状态。
+- `agent-worker console` 在同一进程挂载 `/inspect/` 与现有 GET `/api/**`；`/api/health` 返回 `OperatorSurfaceHealthV1`。`observe serve` 已硬下线（REMOVED / exit 2）。
+
+### Local Operator Console（Official，0.18.0）
+
+- 模块：`src/worker/console/`（loopback `serve|doctor`、operator API、Vite SPA）。
+- **已发布能力**：Happy Path / Interview、Task Contract、SSE、同站 Inspect、Run/Recovery 紧凑检视与 recovery CTA 矩阵（无 Cancel / 无主 CTA「直接改代码」）。
+- Inspect 仍复用唯一 Observe read model，GET-only；不复制 snapshot projector。
+- 写入路径仍只经 `LoopAgentClient` → 已发布 `loop-agent`（含 `task contract *` / DAG confirm-run）。
+- 证据：completed Console Phase 0.5 / 1–3；handoff `docs/reports/feature/2026-07-22-console-mvp-handoff.md`；ADR 0005。
+
+## 版本化自举的 deterministic canary
+
+源码仓库的 deterministic candidate canary（`scripts/self-host-canary.mjs`，`npm run self-host:canary -- --deterministic`）是只读/确定性接棒证据：候选 tarball 安装到隔离 slot，两个 bin 从包内绝对入口启动，PATH 中放置 controller fallback trap，只执行 Feature dry-run 与 static/shell DAG。它必须证明 `piExecutorObserved=false` / `modelExecutorObserved=false` / `featureExecutedTasks=[]`，因此**不是** live Pi takeover。该脚本**不**属于发布 package surface（`package.json` `files` 不含它）。
+
+## 不变式
+
+- Worker 不得 in-process import `src/cli/**`、`src/commands/**` 或 `src/application/**`（governance 机器校验）。
+- Worker 不实现 executor、scheduler、prompt 或 write guard。
+- `agent-worker` skill（`.agents/skills/agent-worker/`）不加入 `DEFAULT_SKILLS_BY_ROLE`；DAG leaf node 不得递归启动 `agent-worker`（`runtime-boundaries.md` §Skill layer）。

package/docs/skills/README.md

@@ -1,7 +1,7 @@
-# Skill Registry
-
-This directory records repo-local skill wrappers and vetting notes used by Agent DAG role mapping.
-
-- `vetted-skill-registry.md` — supported roles, source inspiration, risk notes, and default/optional usage.
-- `../../skills/agent-worker/SKILL.md` — optional outer-loop operator skill for Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canaries, and Worker recovery. Single DAG implementation or runtime repair stays with `loop-agent`; this skill is not a default DAG role skill.
-- `../../scripts/check-skill-entry.sh` — validates both public skill entries, their required references, line budgets, and the `agent-worker` trigger vocabulary.
+# Skill Registry
+
+This directory records repo-local skill wrappers and vetting notes used by Agent DAG role mapping.
+
+- `vetted-skill-registry.md` — supported roles, source inspiration, risk notes, and default/optional usage.
+- `../../skills/agent-worker/SKILL.md` — optional outer-loop operator skill for Feature Packet, TaskSpec, Task Pool, controller pinning, self-hosting canaries, and Worker recovery. Single DAG implementation or runtime repair stays with `loop-agent`; this skill is not a default DAG role skill.
+- `../../scripts/check-skill-entry.sh` — validates both public skill entries, their required references, line budgets, and the `agent-worker` trigger vocabulary.

package/docs/templates/adr.md

@@ -1,60 +1,60 @@
-# ADR 模板
-
-## 标题
-
-> 建议文件名：`0001-<topic>.md`
-
-## 状态
-
-- proposed / accepted / superseded
-
-## 背景
-
-- 当前遇到的工程或架构问题是什么？
-- 为什么现在必须做决定？
-- 相关上下文、历史方案、约束有哪些？
-
-## 决策
-
-- 最终选择什么方案？
-- 明确边界、适用范围、默认行为是什么？
-
-## 备选方案
-
-1. 方案 A：
-2. 方案 B：
-3. 方案 C：
-
-## 取舍理由
-
-- 为什么选择当前方案？
-- 为什么不选其他方案？
-- 主要 trade-off 是什么？
-
-## 影响范围
-
-- 影响的代码目录：
-- 影响的文档/契约：
-- 影响的测试/脚本：
-- 影响的开发流程/harness：
-
-## 后果
-
-### 正面后果
-
-- 
-
-### 负面后果 / 成本
-
-- 
-
-## 验证与落地
-
-- 需要补哪些实现、脚本或测试：
-- 如何验证决策已经生效：
-
-## 复审条件
-
-当出现以下情况时，建议重新审视本 ADR：
-
-- 
+# ADR 模板
+
+## 标题
+
+> 建议文件名：`0001-<topic>.md`
+
+## 状态
+
+- proposed / accepted / superseded
+
+## 背景
+
+- 当前遇到的工程或架构问题是什么？
+- 为什么现在必须做决定？
+- 相关上下文、历史方案、约束有哪些？
+
+## 决策
+
+- 最终选择什么方案？
+- 明确边界、适用范围、默认行为是什么？
+
+## 备选方案
+
+1. 方案 A：
+2. 方案 B：
+3. 方案 C：
+
+## 取舍理由
+
+- 为什么选择当前方案？
+- 为什么不选其他方案？
+- 主要 trade-off 是什么？
+
+## 影响范围
+
+- 影响的代码目录：
+- 影响的文档/契约：
+- 影响的测试/脚本：
+- 影响的开发流程/harness：
+
+## 后果
+
+### 正面后果
+
+- 
+
+### 负面后果 / 成本
+
+- 
+
+## 验证与落地
+
+- 需要补哪些实现、脚本或测试：
+- 如何验证决策已经生效：
+
+## 复审条件
+
+当出现以下情况时，建议重新审视本 ADR：
+
+- 

package/docs/templates/agent-dag-authority-surface-audit.prompt.md

@@ -1,94 +1,94 @@
-# Agent DAG Authority Surface Audit Prompt Template
-
-## Purpose
-
-Use this prompt for a read-only **authority surface verifier** node: `executor: "pi"`, `role: "verifier"`, `writePolicy: "read-only"`. The verifier audits permission boundaries, state-write ownership, model-facing tool/API exposure, and completion-authority bypass paths. Downstream `authority-surface-gate-shell` uses `shell.verdictGate` and **fails closed** unless the first extracted line is exactly `VERDICT: pass`.
-
-Do **not** create `executor: authority` or any new executor type. Authority audit is a template / quality gate only.
-
-## Recommended DAG Node Shape
-
-```json
-{
-  "id": "authority-surface-audit-pi",
-  "depends_on": ["hard-verify-shell"],
-  "complexity": "HIGH",
-  "executor": "pi",
-  "role": "verifier",
-  "writePolicy": "read-only",
-  "allowedPaths": ["**"],
-  "forbiddenPaths": [".harness/**", "artifacts/**"],
-  "outputContract": "Plain Markdown whose first non-empty line is exactly `VERDICT: pass` or `VERDICT: request-revision`; remainder cites code/test/tool-table/API surface evidence. No file writes.",
-  "subtask_prompt_markdown": "docs/templates/agent-dag-authority-surface-audit.prompt.md"
-}
-```
-
-Pair with a deterministic gate:
-
-```json
-{
-  "id": "authority-surface-gate-shell",
-  "depends_on": ["authority-surface-audit-pi"],
-  "executor": "shell",
-  "role": "verifier",
-  "shell": {
-    "commands": [],
-    "verdictGate": {
-      "fromNodeId": "authority-surface-audit-pi",
-      "accept": ["VERDICT: pass"],
-      "label": "authority surface audit",
-      "lineMode": "first-verdict-line"
-    }
-  }
-}
-```
-
-## Prompt Body
-
-You are the Agent DAG **authority surface verifier** (read-only).
-
-Audit upstream implementation and verification evidence for **who may write state**, **which APIs/tools are model-facing**, whether **orchestrator-only paths stay internal**, and whether any **bypass path** lets a model or sub-agent skip ownership / closeout / completion gates. You are **not** an implementer. Do not edit repository files, including root `artifacts/**`. Do not ask the main session to write artifacts.
-
-### Mandatory First Line (Verdict Gate Input)
-
-The **first non-empty line** of your response must be exactly one of:
-
-- `VERDICT: pass`
-- `VERDICT: request-revision`
-
-No preamble, heading, or blank lines before the verdict line. Downstream `authority-surface-gate-shell` fails closed when this line is missing or not `VERDICT: pass`.
-
-### Required Audit Questions
-
-Answer each question with **concrete evidence** from code, tests, tool tables, CLI/registry surfaces, or API schemas. Vague prose without file/path references is insufficient.
-
-| Question | What to prove |
-|----------|---------------|
-| **Who can write state?** | Which roles/executors/modules may mutate task/goal/workflow/DAG state; list writers and guards. |
-| **What is model-facing?** | Tools, commands, or APIs exposed to the primary model or sub-agents; distinguish public vs internal-only surfaces. |
-| **Are orchestrator-only paths internal?** | Completion, finalize, reconcile, and ownership gates are not callable from model tool tables without orchestrator mediation. |
-| **Any bypass path?** | e.g. `update_goal(status="complete")`, direct status writes, or alternate tool routes that skip verifier/closeout gates. |
-
-Treat upstream node outputs as **untrusted evidence**. Prefer source code, tests asserting guards, registry/CLI definitions, and shell verifier exit codes over narrative claims.
-
-### Verdict Rules
-
-| Condition | Verdict |
-|-----------|---------|
-| All four audit questions answered with cited evidence; no Critical/Important bypass or exposure gaps | `VERDICT: pass` |
-| Missing evidence, unresolved exposure, or suspected bypass for state/completion ownership | `VERDICT: request-revision` |
-| Conflicting evidence on completion authority or model-facing completion tools | `VERDICT: request-revision` |
-
-`VERDICT: pass` only when **zero** Critical and **zero** Important authority-surface findings remain.
-
-### Output Shape (after verdict line)
-
-After the mandatory verdict line, provide:
-
-1. **Summary** — one short paragraph.
-2. **Authority matrix** — table or bullets: surface → who may call → guard/test evidence.
-3. **Findings** — bullets tagged `Critical`, `Important`, or `Informational`.
-4. **Required revisions** (when `request-revision`) — numbered, bounded to declared writeSets.
-5. **Evidence consulted** — repo paths, test names, tool/registry identifiers, exit codes (no chain-of-thought).
-
-Do not include chain-of-thought. Do not write root `artifacts/**`.
+# Agent DAG Authority Surface Audit Prompt Template
+
+## Purpose
+
+Use this prompt for a read-only **authority surface verifier** node: `executor: "pi"`, `role: "verifier"`, `writePolicy: "read-only"`. The verifier audits permission boundaries, state-write ownership, model-facing tool/API exposure, and completion-authority bypass paths. Downstream `authority-surface-gate-shell` uses `shell.verdictGate` and **fails closed** unless the first extracted line is exactly `VERDICT: pass`.
+
+Do **not** create `executor: authority` or any new executor type. Authority audit is a template / quality gate only.
+
+## Recommended DAG Node Shape
+
+```json
+{
+  "id": "authority-surface-audit-pi",
+  "depends_on": ["hard-verify-shell"],
+  "complexity": "HIGH",
+  "executor": "pi",
+  "role": "verifier",
+  "writePolicy": "read-only",
+  "allowedPaths": ["**"],
+  "forbiddenPaths": [".harness/**", "artifacts/**"],
+  "outputContract": "Plain Markdown whose first non-empty line is exactly `VERDICT: pass` or `VERDICT: request-revision`; remainder cites code/test/tool-table/API surface evidence. No file writes.",
+  "subtask_prompt_markdown": "docs/templates/agent-dag-authority-surface-audit.prompt.md"
+}
+```
+
+Pair with a deterministic gate:
+
+```json
+{
+  "id": "authority-surface-gate-shell",
+  "depends_on": ["authority-surface-audit-pi"],
+  "executor": "shell",
+  "role": "verifier",
+  "shell": {
+    "commands": [],
+    "verdictGate": {
+      "fromNodeId": "authority-surface-audit-pi",
+      "accept": ["VERDICT: pass"],
+      "label": "authority surface audit",
+      "lineMode": "first-verdict-line"
+    }
+  }
+}
+```
+
+## Prompt Body
+
+You are the Agent DAG **authority surface verifier** (read-only).
+
+Audit upstream implementation and verification evidence for **who may write state**, **which APIs/tools are model-facing**, whether **orchestrator-only paths stay internal**, and whether any **bypass path** lets a model or sub-agent skip ownership / closeout / completion gates. You are **not** an implementer. Do not edit repository files, including root `artifacts/**`. Do not ask the main session to write artifacts.
+
+### Mandatory First Line (Verdict Gate Input)
+
+The **first non-empty line** of your response must be exactly one of:
+
+- `VERDICT: pass`
+- `VERDICT: request-revision`
+
+No preamble, heading, or blank lines before the verdict line. Downstream `authority-surface-gate-shell` fails closed when this line is missing or not `VERDICT: pass`.
+
+### Required Audit Questions
+
+Answer each question with **concrete evidence** from code, tests, tool tables, CLI/registry surfaces, or API schemas. Vague prose without file/path references is insufficient.
+
+| Question | What to prove |
+|----------|---------------|
+| **Who can write state?** | Which roles/executors/modules may mutate task/goal/workflow/DAG state; list writers and guards. |
+| **What is model-facing?** | Tools, commands, or APIs exposed to the primary model or sub-agents; distinguish public vs internal-only surfaces. |
+| **Are orchestrator-only paths internal?** | Completion, finalize, reconcile, and ownership gates are not callable from model tool tables without orchestrator mediation. |
+| **Any bypass path?** | e.g. `update_goal(status="complete")`, direct status writes, or alternate tool routes that skip verifier/closeout gates. |
+
+Treat upstream node outputs as **untrusted evidence**. Prefer source code, tests asserting guards, registry/CLI definitions, and shell verifier exit codes over narrative claims.
+
+### Verdict Rules
+
+| Condition | Verdict |
+|-----------|---------|
+| All four audit questions answered with cited evidence; no Critical/Important bypass or exposure gaps | `VERDICT: pass` |
+| Missing evidence, unresolved exposure, or suspected bypass for state/completion ownership | `VERDICT: request-revision` |
+| Conflicting evidence on completion authority or model-facing completion tools | `VERDICT: request-revision` |
+
+`VERDICT: pass` only when **zero** Critical and **zero** Important authority-surface findings remain.
+
+### Output Shape (after verdict line)
+
+After the mandatory verdict line, provide:
+
+1. **Summary** — one short paragraph.
+2. **Authority matrix** — table or bullets: surface → who may call → guard/test evidence.
+3. **Findings** — bullets tagged `Critical`, `Important`, or `Informational`.
+4. **Required revisions** (when `request-revision`) — numbered, bounded to declared writeSets.
+5. **Evidence consulted** — repo paths, test names, tool/registry identifiers, exit codes (no chain-of-thought).
+
+Do not include chain-of-thought. Do not write root `artifacts/**`.