@tea-agent/loop-agent 0.13.0-beta.0 → 0.13.0

package/docs/loop-agent-harness.md

@@ -1,142 +1,142 @@
-# loop-agent Harness
-
-loop-agent 提供结构化 agent 工作的本地 harness。
-
-## Runtime 区域
-
-- `.harness/tasks/` — task source、约束、state、loop facts
-- `.harness/dag-runs/` — DAG run state 与 artifacts
-- `.harness/runs/` — one-shot tool run 证据
-- `.harness/cache/` — 本地 runtime 缓存
-- `.harness/live/` — 瞬态 live-session 文件
-- `.harness/task-pool/` — `agent-worker` 的 Task Pool state、batch artifacts、failure handoffs 与 Observe events；它是 `.harness/` 内的独立 Worker runtime root，默认不提交
-- `.harness/task-pool/states/<featureId>/<taskId>.json` — Task Pool schema v2 的 canonical state（ADR 0004）；复合身份 `TaskPoolTaskRef = { featureId, taskId }`。扁平 `states/<taskId>.json` 为 legacy，不得静默解释
-- `.harness/dag-runs/<lifecycle>/<run-id>/contracts/backend-test-analysis.json` — `backend-test` 的 run-owned 结构化分析契约；由 deterministic schema gate 从只读 analyze 输出生成，节点记录 path/hash/schema，随 lifecycle 目录迁移且不进入 Git writeSet
-- `.harness/dag-runs/<lifecycle>/<run-id>/.runtime/skill-snapshot.json` — 该 run 实际使用的 resolved skill profile snapshot；由 state 中相对 ref 与原始 bytes SHA-256 锚定，随 lifecycle 目录整体迁移
-
-## Skill 指令
-
-- `skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
-- `skills/agent-worker/` — Feature Packet、TaskSpec、Task Pool、controller pinning、自举 candidate canary 与 Worker recovery 的可选 outer-loop operator skill；不是 DAG node skill
-- `.agents/skills/<skill-name>/` — 目标项目 repo-local skill 副本；`skills/<skill-name>/` 仍是 loop-agent 源仓库和 npm 包内置回退路径
-- 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
-
-目标项目若在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，hybrid DAG 生成器会按节点追加对应 skill。该增强只复用 repo-local 知识与方法：loop-agent 仍拥有流程与状态控制权，embedded-mode 约束禁止 SDD 状态推进、确认门禁和归档；初始化/扫描类 SDD skill 不会自动执行。未命中时不会改变默认 DAG。命中的节点 skill 继续由同一 resolved instruction 和 run-owned snapshot 机制冻结，没有第二套 loader 或旁路。
-
-## Package 资产
-
-npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`skills/`（包括 `loop-agent` 与 `agent-worker`）、顶层 `docs/*.md`、`docs/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
-
-生成或历史的 task facts 不是 package 资产。`docs/progress/`、`docs/reports/`、`docs/exec-plans/`、`docs/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
-
-从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标项目 `.agents/skills/` 解析（若存在），再回退到包内 `skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或根 `skills/` 目录即可使用默认 DAG 工作流。
-
-`scripts/self-host-canary.mjs` 是源码仓库维护脚本，不进入 npm package `files`；安装后的 package 不把它作为用户命令 surface。
-
-## harness.json Schema
-
-`docs/templates/harness.schema.json` 是面向 IDE 的 `harness.json` JSON Schema。它用于补全字段、提示枚举值、解释 executor/model routing 配置，并尽早暴露拼写错误。
-
-运行时事实源仍是 `src/governance/manifest-types.ts` 中的 Zod `harnessManifestSchema`；CLI 读取 `harness.json` 时继续通过 `loadHarnessManifest()` 解析。JSON Schema 不替代运行时校验，只服务编辑体验。
-
-`loop-agent init --profile full --merge` 会把 schema 投影到目标项目，并在生成的 `harness.json` 写入与 `governanceRoot` 匹配的 `$schema`。旧初始化项目可通过 `loop-agent init check-update` 查看缺失项，并用 `loop-agent init update --apply-safe` 安全补齐 schema 文件和 `$schema` 引用；该安全更新只允许修改 `$schema`，不会重写用户已有 harness 配置。
-
-DAG run state 会记录 runner PID、hostname 和定期 heartbeat，并为节点记录最近活动时间。`loop-agent dag status` 和 `loop-agent dag doctor --run-id <run-id> --markdown` 会将同主机且 PID 已消失的运行识别为 `orphaned`，将进程仍在但 heartbeat 过期的运行识别为 `stale`，将 runner 存活但当前节点超过 5 分钟没有状态活动标记为 `node-quiet`；跨主机运行只标记为 `unknown-host`，不会据此判断远端进程死亡。Observe 使用同一组字段过滤活跃 DAG，并在详情中显示 lifecycle 与 liveness；`node-quiet` 仍视为活跃，只提示操作者检查 session events 和 executor logs。
-
-Observe 和 `dag status` 还会给出 `effectiveStatus`、`stateConsistent` 与 `recoveryEligibility`。主状态以 lifecycle + canonical status + liveness 的综合判定为准，原始 `state.status` 只作为诊断事实展示。遇到历史 `paused/` 目录仍记录 `status=running`、或 active runner 已明确 `orphaned` 时，先运行只读检查：
-
-```bash
-loop-agent dag reconcile-run --run-id <run-id>
-```
-
-确认不应继续后，必须显式选择收口含义并填写原因：
-
-```bash
-loop-agent dag reconcile-run --run-id <run-id> --action supersede --reason "implementation completed elsewhere"
-loop-agent dag reconcile-run --run-id <run-id> --action abandon --reason "operator cancelled obsolete work"
-```
-
-收口会保存 `reconciliation.json` 原始快照，将仍为 RUNNING 的节点标为 ERROR，并把 run 归档到 `completed/`；不会把未执行节点伪造成成功。同机 runner 仍存活、仅 `node-quiet`、heartbeat stale 但 PID 仍存在、跨主机或无法证明停止时都会拒绝收口。
-
-DAG 节点的模型由 `executorModels[executor][complexity]` 路由。新 run 会将解析后的 Pi/Cursor 模型写入节点 state；Observe 读取历史 run 时会从 `run.json` 补算缺失模型。Shell 和 Static 节点不使用模型，因此模型列保持 `-`。
-
-DAG agent 节点的输出语言由 `harness.json.workflowPolicy.dag.outputLanguage` 控制，支持 `zh-CN` 和 `en`。未配置时默认 `zh-CN`；`dag run-task` 会把配置写入生成的 DagSpec，手写 DagSpec 缺少该字段时 prompt envelope 同样默认中文。语言规则只约束说明、分析、报告、总结和文档正文，不翻译代码、命令、路径、标识符、JSON 字段、VERDICT 行及其他精确协议字面量。
-
-新 DAG run（包括 dry-run 与 init-only）会在首次 state write 前冻结所有初始 Pi task、dynamic map child template 与 loop body template 的 resolved skill profiles。profile id 包含 ordered skills、learned-pattern mode 和两个 instruction budgets；后续节点只从 snapshot 建 prompt。snapshot/hash/binding/profile 不一致时节点进入 `ERROR` / `skill-snapshot-integrity`，executor 不调用，也不回退实时 skill。旧 run 只有在 ref 与 artifact 都不存在时，才可在 resume 前创建 `legacy-resume-backfill`，且该 mode 只证明剩余节点被固定。
-
-## Command Surface
-
-- `new-task`、`status`、`inspect`、`doctor`
-- `dag run-task`、`dag validate`、`run-dag`、`dag report`、`dag resume`、`dag reconcile-run`
-- `plan list`、`plan create`、`plan complete`、`plan check`、`docs audit`、`docs archive`
-- `delegate`、`harvest`、`promote-run`、`closeout`
-- `loop init`、`loop run`、`loop status`、`loop closeout`
-- `pi-prompt`、`cursor-prompt`
-- `handoff check`、`spine audit`、`knowledge curate`
-- `agent-worker feature review|run|verify-final|delivery|closeout|approve-followup`、`agent-worker task validate|explain-profile|retry|draft-followup`、`agent-worker batch run-ready`、`agent-worker pool doctor|migrate-state`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
-
-`dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `docs/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `docs/templates/exec-plan.md`，`plan create`/`plan complete` 的多文件写入均有回滚保护；`new-task` 不自动绑定 exec-plan。
-
-## Feature Review
-
-`agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>` 是只读的 Feature 级决策入口。它复用 Feature Packet validation、task graph 和 `.harness/task-pool/` 事实，派生 `Draft`、`Ready`、`Running`、`NeedsAction`、`AwaitingQA`、`Deliverable`、`Closed`，同时展示 required AC 覆盖、阻塞、证据和唯一主行动。
-
-默认输出按结果、原因、下一步、证据组织；`--json` 输出 schemaVersion 1 JSON。缺失或损坏的 Packet、state、JSONL 或 closeout 会暴露 validation error / projection warning，不会被误判为无数据、可交付或已关闭。该命令不写 Feature Packet、Task Pool 或 Git。
-
-`agent-worker feature run --feature-dir <feature-dir> --repo <target-repo>` 是薄编排入口：先执行 Feature validation 和一次目标仓库 preflight，再复用 `runReadyTasks()` 推进 Ready Task，最后刷新 morning report、`.harness/task-pool/observability/snapshot.json` 与 Feature review。`--dry-run` 只读取 Packet/Task Pool 并列出 Ready IDs、步骤和预期产物。默认无 Git 授权时单次最多执行一个 Ready 写任务；checkpoint 模式可按 `--limit` 串行推进，并在每个 Task 后建立 clean boundary。
-
-写入型 Worker 命令可传 `--expected-controller-version` 与 `--expected-controller-fingerprint`。`LoopAgentClient` 先把请求的 bin/PATH/npm shim 解析成冻结的绝对 launch spec，再校验 package name/version、binary SHA-256 和 portable package fingerprint；expected gate 在 materialize、Task Pool `Running` 或目标仓库写入前完成。预检后的命令使用该 launch spec，不会因 PATH、symlink 或安装内容变化而静默切换 controller。
-
-`agent-worker feature verify-final` 在 clean Delivery HEAD 上以已完成的 `qa-execute` TaskSpec 运行独立最终 DAG，跳过 promotion/task closeout，避免 repo write 或 HEAD 移动，并原子生成 canonical QA aggregate 与 HEAD-bound final verification。`agent-worker feature delivery` 从同一 Git transaction 和 Task Pool facts 生成带 hash 的 manifest、Acceptance Coverage 与稳定 `PR.md`，拒绝 dirty/wrong branch、历史或 trailer 漂移、缺失 run/QA/final verification 和 required AC 缺口。`agent-worker feature closeout` 默认只读预览 gates；显式 `--apply --owner` 才原子写回 Closeout，并在 stale facts、写入或 post-validation 失败时恢复原状态。
-
-Morning report 顶部和 Observe 首页直接消费共享 Feature read model，固定从 Status、Next Action、Why、Evidence 开始。`agent-worker report metrics --month YYYY-MM` 写入 `.harness/task-pool/artifacts/metrics/monthly-YYYY-MM.json|md`，每项指标保留分母、样本量、窗口和 missingData。
-
-显式 `--git-mode checkpoint` 会在 clean preflight 后创建或复用受 transaction record 管理的 `agent/<feature-id>` 本地分支。成功任务只有在 changed/untracked/sensitive 与 TaskSpec allowed/forbidden audit 通过后才 commit；失败任务的 patch、inventory、untracked content 与 boundary audit 写入 `.harness/task-pool/artifacts/features/<feature-id>/git/failures/`，随后 reset/clean 到最近 checkpoint 并再次验证 clean。默认模式不触碰 Git；`--keep-failed-diff` 只保留现场并停止，不允许继续下一个写任务。任何模式都不授权 stash、push、remote PR 或 merge。
-
-业务 Task 失败不会跳过报告与最终 review，但命令返回 `needs-action` 和非零退出码；`noReadyReason` 用于区分 Closed、Deliverable、AwaitingQA、NeedsAction、dependency blocked 与 empty。
-
-## Versioned Self-hosting Canary
-
-源码仓库使用下面的 repo-maintainer 命令验证隔离 candidate package 的确定性接棒：
-
-```bash
-npm run self-host:canary -- --deterministic --output <evidence.json>
-npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
-```
-
-canary 会记录 tarball SHA-256、slot containment、两个 bin identity、由维护脚本独立计算并与候选实现交叉核对的 package fingerprint、每个 required check、skill mirror hashes、Feature dry-run、static/shell DAG run/report 以及 PATH trap。所有子进程都有硬超时；它删除 `HARNESS_ALLOW_ACTIVE_DAG_RUNS`，并要求 trap 中没有 `loop-agent`、`agent-worker` 或 `pi` 调用。`--live` 当前明确失败；deterministic canary 不包含 Pi/model/provider/cost 证明。
-
-## Follow-up 决策与批准
-
-`agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>` 从失败 run、TaskSpec 和 task graph 生成 `FU-<parent>-NN` 决策产物。ProductBug/TestBug/FlakyTest/DependencyFailure 生成可批准 TaskDraft；连续两次 EnvFailure 生成 `ENV-CHECK-*`，单次只建议 retry；SpecUnclear/ContractMismatch/RiskyChange/NeedsHuman/Unknown 生成人工行动卡。产物与 evidence/index 位于 `.harness/task-pool/artifacts/features/<feature-id>/follow-ups/`；生成过程受 Feature lock 和 dedupe key 保护，不写 Feature Packet、Ready state 或原失败事实。新 run 会 supersede 同 parent 的旧 unresolved 产物，但不会删除历史。
-
-人工批准只接受 TaskDraft；行动卡不能批准或进入 Ready。批准会校验 draft/evidence hash、repo/path containment、Feature baseline 和冲突，在 staging validation 后写 TaskSpec、graph、Ready、approval/index 与 event。rename、state、approval、index、event 五个故障点均有注入回滚测试；重复批准幂等复用首次结果。`--dry-run` 零写入，`--json` 失败保持 stdout JSON、stderr 无噪声和非零退出码。
-
-## Worker Retry
-
-失败 Task Pool task 必须显式 retry，不能删除 `.harness/task-pool/runs.jsonl` 或复用失败的 `workerRunId`。canonical 命令必须携带 Feature：
-
-```bash
-agent-worker task retry <task-id> --feature-id <feature-id> --repo <target-repo> --reason "provider configuration corrected"
-agent-worker batch run-ready --feature-dir <feature-dir> --repo <target-repo>
-```
-
-`task retry` 只接受指定 Feature 下的 `Failed` state，保留旧 run 和 failure handoff，并写入 `retryOfWorkerRunId`。跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。下一次 `run-ready` 生成新的 `workerRunId`；`Blocked`、`Done` 或无 state 的 task 必须先由 operator 处理根因，不能盲目重试。
-
-## Task Pool Doctor 与 State 迁移
-
-```bash
-agent-worker pool doctor --repo <target-repo> --json
-agent-worker pool migrate-state --repo <target-repo>            # dry-run 默认
-agent-worker pool migrate-state --repo <target-repo> --apply --owner <owner> --reason <reason>
-```
-
-`pool doctor` 只读扫描 v2 / legacy inventory 与映射证据，exit 0 也可带 findings。`pool migrate-state` 默认零写入；apply 需要 `--owner` 与 `--reason`，保留 bytes/hash 审计 artifact，失败全回滚，且不改写 `runs.jsonl` / `events.jsonl`。
-
-## 验证 Preset
-
-Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
-
-```bash
-bash scripts/ci.sh
-```
+# loop-agent Harness
+
+loop-agent 提供结构化 agent 工作的本地 harness。
+
+## Runtime 区域
+
+- `.harness/tasks/` — task source、约束、state、loop facts
+- `.harness/dag-runs/` — DAG run state 与 artifacts
+- `.harness/runs/` — one-shot tool run 证据
+- `.harness/cache/` — 本地 runtime 缓存
+- `.harness/live/` — 瞬态 live-session 文件
+- `.harness/task-pool/` — `agent-worker` 的 Task Pool state、batch artifacts、failure handoffs 与 Observe events；它是 `.harness/` 内的独立 Worker runtime root，默认不提交
+- `.harness/task-pool/states/<featureId>/<taskId>.json` — Task Pool schema v2 的 canonical state（ADR 0004）；复合身份 `TaskPoolTaskRef = { featureId, taskId }`。扁平 `states/<taskId>.json` 为 legacy，不得静默解释
+- `.harness/dag-runs/<lifecycle>/<run-id>/contracts/backend-test-analysis.json` — `backend-test` 的 run-owned 结构化分析契约；由 deterministic schema gate 从只读 analyze 输出生成，节点记录 path/hash/schema，随 lifecycle 目录迁移且不进入 Git writeSet
+- `.harness/dag-runs/<lifecycle>/<run-id>/.runtime/skill-snapshot.json` — 该 run 实际使用的 resolved skill profile snapshot；由 state 中相对 ref 与原始 bytes SHA-256 锚定，随 lifecycle 目录整体迁移
+
+## Skill 指令
+
+- `.agents/skills/loop-agent/` — loop-agent 仓库自有的 skill 指令与参考资料
+- `.agents/skills/agent-worker/` — Feature Packet、TaskSpec、Task Pool、controller pinning、自举 candidate canary 与 Worker recovery 的可选 outer-loop operator skill；不是 DAG node skill
+- `.agents/skills/<skill-name>/` — 目标项目 repo-local skill 副本；`.agents/skills/<skill-name>/` 仍是 loop-agent 源仓库和 npm 包内置回退路径
+- 历史 `skill/` 不再是必需仓库路径；runtime 查找仅为 `loop-agent` 保留兼容 fallback
+
+目标项目若在 `.agents/skills/` 中提供 `SDD-requirement-analysis`、`SDD-design-analysis`、`SDD-implementation-test-review`，hybrid DAG 生成器会按节点追加对应 skill。该增强只复用 repo-local 知识与方法：loop-agent 仍拥有流程与状态控制权，embedded-mode 约束禁止 SDD 状态推进、确认门禁和归档；初始化/扫描类 SDD skill 不会自动执行。未命中时不会改变默认 DAG。命中的节点 skill 继续由同一 resolved instruction 和 run-owned snapshot 机制冻结，没有第二套 loader 或旁路。
+
+## Package 资产
+
+npm 包包含运行与说明 harness 所需的静态能力资产：`bin/`、`dist/`、`.agents/skills/`（包括 `loop-agent` 与 `agent-worker`）、顶层 `ai_workspace/loop-agent/*.md`、`ai_workspace/loop-agent/templates/`、`examples/`、`harness.json`、`AGENTS.md`、`README.md`、`CHANGELOG.md`。
+
+生成或历史的 task facts 不是 package 资产。`ai_workspace/loop-agent/progress/`、`ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/exec-plans/`、`ai_workspace/loop-agent/decisions/` 下现有文件属于目标仓库历史；包只携带这些目录的 README。
+
+从 npm 安装 `loop-agent` 并在其他项目使用时，DAG skill 指令按配置、用户或目标项目 `.agents/skills/` 解析（若存在），再回退到包内 `.agents/skills/`。目标项目可添加本地 skills，但不必复制 loop-agent 源码历史或根 `.agents/skills/` 目录即可使用默认 DAG 工作流。
+
+`scripts/self-host-canary.mjs` 是源码仓库维护脚本，不进入 npm package `files`；安装后的 package 不把它作为用户命令 surface。
+
+## harness.json Schema
+
+`ai_workspace/loop-agent/templates/harness.schema.json` 是面向 IDE 的 `harness.json` JSON Schema。它用于补全字段、提示枚举值、解释 executor/model routing 配置，并尽早暴露拼写错误。
+
+运行时事实源仍是 `src/governance/manifest-types.ts` 中的 Zod `harnessManifestSchema`；CLI 读取 `harness.json` 时继续通过 `loadHarnessManifest()` 解析。JSON Schema 不替代运行时校验，只服务编辑体验。
+
+`loop-agent init --profile full --merge` 会把 schema 投影到目标项目，并在生成的 `harness.json` 写入与 `governanceRoot` 匹配的 `$schema`。旧初始化项目可通过 `loop-agent init check-update` 查看缺失项，并用 `loop-agent init update --apply-safe` 安全补齐 schema 文件和 `$schema` 引用；该安全更新只允许修改 `$schema`，不会重写用户已有 harness 配置。
+
+DAG run state 会记录 runner PID、hostname 和定期 heartbeat，并为节点记录最近活动时间。`loop-agent dag status` 和 `loop-agent dag doctor --run-id <run-id> --markdown` 会将同主机且 PID 已消失的运行识别为 `orphaned`，将进程仍在但 heartbeat 过期的运行识别为 `stale`，将 runner 存活但当前节点超过 5 分钟没有状态活动标记为 `node-quiet`；跨主机运行只标记为 `unknown-host`，不会据此判断远端进程死亡。Observe 使用同一组字段过滤活跃 DAG，并在详情中显示 lifecycle 与 liveness；`node-quiet` 仍视为活跃，只提示操作者检查 session events 和 executor logs。
+
+Observe 和 `dag status` 还会给出 `effectiveStatus`、`stateConsistent` 与 `recoveryEligibility`。主状态以 lifecycle + canonical status + liveness 的综合判定为准，原始 `state.status` 只作为诊断事实展示。遇到历史 `paused/` 目录仍记录 `status=running`、或 active runner 已明确 `orphaned` 时，先运行只读检查：
+
+```bash
+loop-agent dag reconcile-run --run-id <run-id>
+```
+
+确认不应继续后，必须显式选择收口含义并填写原因：
+
+```bash
+loop-agent dag reconcile-run --run-id <run-id> --action supersede --reason "implementation completed elsewhere"
+loop-agent dag reconcile-run --run-id <run-id> --action abandon --reason "operator cancelled obsolete work"
+```
+
+收口会保存 `reconciliation.json` 原始快照，将仍为 RUNNING 的节点标为 ERROR，并把 run 归档到 `completed/`；不会把未执行节点伪造成成功。同机 runner 仍存活、仅 `node-quiet`、heartbeat stale 但 PID 仍存在、跨主机或无法证明停止时都会拒绝收口。
+
+DAG 节点的模型由 `executorModels[executor][complexity]` 路由。新 run 会将解析后的 Pi/Cursor 模型写入节点 state；Observe 读取历史 run 时会从 `run.json` 补算缺失模型。Shell 和 Static 节点不使用模型，因此模型列保持 `-`。
+
+DAG agent 节点的输出语言由 `harness.json.workflowPolicy.dag.outputLanguage` 控制，支持 `zh-CN` 和 `en`。未配置时默认 `zh-CN`；`dag run-task` 会把配置写入生成的 DagSpec，手写 DagSpec 缺少该字段时 prompt envelope 同样默认中文。语言规则只约束说明、分析、报告、总结和文档正文，不翻译代码、命令、路径、标识符、JSON 字段、VERDICT 行及其他精确协议字面量。
+
+新 DAG run（包括 dry-run 与 init-only）会在首次 state write 前冻结所有初始 Pi task、dynamic map child template 与 loop body template 的 resolved skill profiles。profile id 包含 ordered skills、learned-pattern mode 和两个 instruction budgets；后续节点只从 snapshot 建 prompt。snapshot/hash/binding/profile 不一致时节点进入 `ERROR` / `skill-snapshot-integrity`，executor 不调用，也不回退实时 skill。旧 run 只有在 ref 与 artifact 都不存在时，才可在 resume 前创建 `legacy-resume-backfill`，且该 mode 只证明剩余节点被固定。
+
+## Command Surface
+
+- `new-task`、`status`、`inspect`、`doctor`
+- `dag run-task`、`dag validate`、`run-dag`、`dag report`、`dag resume`、`dag reconcile-run`
+- `plan list`、`plan create`、`plan complete`、`plan check`、`docs audit`、`docs archive`
+- `delegate`、`harvest`、`promote-run`、`closeout`
+- `loop init`、`loop run`、`loop status`、`loop closeout`
+- `pi-prompt`、`cursor-prompt`
+- `handoff check`、`spine audit`、`knowledge curate`
+- `agent-worker feature review|run|verify-final|delivery|closeout|approve-followup`、`agent-worker task validate|explain-profile|retry|draft-followup`、`agent-worker batch run-ready`、`agent-worker pool doctor|migrate-state`、`agent-worker report morning|metrics`、`agent-worker observe serve|snapshot`
+
+`dag run-task` 在生成 DAG 草稿前会运行与 `plan check` 同源的 exec-plan 索引校验；active plan 与 `ai_workspace/loop-agent/exec-plans/active/README.md` 索引不一致时立即失败，避免运行昂贵节点后才在末端 shell verify 发现。`plan create` 优先复用目标项目模板并回退到发布包内置 `ai_workspace/loop-agent/templates/exec-plan.md`，`plan create`/`plan complete` 的多文件写入均有回滚保护；`new-task` 不自动绑定 exec-plan。
+
+## Feature Review
+
+`agent-worker feature review --feature-dir <feature-dir> --repo <target-repo>` 是只读的 Feature 级决策入口。它复用 Feature Packet validation、task graph 和 `.harness/task-pool/` 事实，派生 `Draft`、`Ready`、`Running`、`NeedsAction`、`AwaitingQA`、`Deliverable`、`Closed`，同时展示 required AC 覆盖、阻塞、证据和唯一主行动。
+
+默认输出按结果、原因、下一步、证据组织；`--json` 输出 schemaVersion 1 JSON。缺失或损坏的 Packet、state、JSONL 或 closeout 会暴露 validation error / projection warning，不会被误判为无数据、可交付或已关闭。该命令不写 Feature Packet、Task Pool 或 Git。
+
+`agent-worker feature run --feature-dir <feature-dir> --repo <target-repo>` 是薄编排入口：先执行 Feature validation 和一次目标仓库 preflight，再复用 `runReadyTasks()` 推进 Ready Task，最后刷新 morning report、`.harness/task-pool/observability/snapshot.json` 与 Feature review。`--dry-run` 只读取 Packet/Task Pool 并列出 Ready IDs、步骤和预期产物。默认无 Git 授权时单次最多执行一个 Ready 写任务；checkpoint 模式可按 `--limit` 串行推进，并在每个 Task 后建立 clean boundary。
+
+写入型 Worker 命令可传 `--expected-controller-version` 与 `--expected-controller-fingerprint`。`LoopAgentClient` 先把请求的 bin/PATH/npm shim 解析成冻结的绝对 launch spec，再校验 package name/version、binary SHA-256 和 portable package fingerprint；expected gate 在 materialize、Task Pool `Running` 或目标仓库写入前完成。预检后的命令使用该 launch spec，不会因 PATH、symlink 或安装内容变化而静默切换 controller。
+
+`agent-worker feature verify-final` 在 clean Delivery HEAD 上以已完成的 `qa-execute` TaskSpec 运行独立最终 DAG，跳过 promotion/task closeout，避免 repo write 或 HEAD 移动，并原子生成 canonical QA aggregate 与 HEAD-bound final verification。`agent-worker feature delivery` 从同一 Git transaction 和 Task Pool facts 生成带 hash 的 manifest、Acceptance Coverage 与稳定 `PR.md`，拒绝 dirty/wrong branch、历史或 trailer 漂移、缺失 run/QA/final verification 和 required AC 缺口。`agent-worker feature closeout` 默认只读预览 gates；显式 `--apply --owner` 才原子写回 Closeout，并在 stale facts、写入或 post-validation 失败时恢复原状态。
+
+Morning report 顶部和 Observe 首页直接消费共享 Feature read model，固定从 Status、Next Action、Why、Evidence 开始。`agent-worker report metrics --month YYYY-MM` 写入 `.harness/task-pool/artifacts/metrics/monthly-YYYY-MM.json|md`，每项指标保留分母、样本量、窗口和 missingData。
+
+显式 `--git-mode checkpoint` 会在 clean preflight 后创建或复用受 transaction record 管理的 `agent/<feature-id>` 本地分支。成功任务只有在 changed/untracked/sensitive 与 TaskSpec allowed/forbidden audit 通过后才 commit；失败任务的 patch、inventory、untracked content 与 boundary audit 写入 `.harness/task-pool/artifacts/features/<feature-id>/git/failures/`，随后 reset/clean 到最近 checkpoint 并再次验证 clean。默认模式不触碰 Git；`--keep-failed-diff` 只保留现场并停止，不允许继续下一个写任务。任何模式都不授权 stash、push、remote PR 或 merge。
+
+业务 Task 失败不会跳过报告与最终 review，但命令返回 `needs-action` 和非零退出码；`noReadyReason` 用于区分 Closed、Deliverable、AwaitingQA、NeedsAction、dependency blocked 与 empty。
+
+## Versioned Self-hosting Canary
+
+源码仓库使用下面的 repo-maintainer 命令验证隔离 candidate package 的确定性接棒：
+
+```bash
+npm run self-host:canary -- --deterministic --output <evidence.json>
+npm run self-host:canary -- --deterministic --tarball <candidate.tgz> --output <evidence.json>
+```
+
+canary 会记录 tarball SHA-256、slot containment、两个 bin identity、由维护脚本独立计算并与候选实现交叉核对的 package fingerprint、每个 required check、skill mirror hashes、Feature dry-run、static/shell DAG run/report 以及 PATH trap。所有子进程都有硬超时；它删除 `HARNESS_ALLOW_ACTIVE_DAG_RUNS`，并要求 trap 中没有 `loop-agent`、`agent-worker` 或 `pi` 调用。`--live` 当前明确失败；deterministic canary 不包含 Pi/model/provider/cost 证明。
+
+## Follow-up 决策与批准
+
+`agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <target-repo>` 从失败 run、TaskSpec 和 task graph 生成 `FU-<parent>-NN` 决策产物。ProductBug/TestBug/FlakyTest/DependencyFailure 生成可批准 TaskDraft；连续两次 EnvFailure 生成 `ENV-CHECK-*`，单次只建议 retry；SpecUnclear/ContractMismatch/RiskyChange/NeedsHuman/Unknown 生成人工行动卡。产物与 evidence/index 位于 `.harness/task-pool/artifacts/features/<feature-id>/follow-ups/`；生成过程受 Feature lock 和 dedupe key 保护，不写 Feature Packet、Ready state 或原失败事实。新 run 会 supersede 同 parent 的旧 unresolved 产物，但不会删除历史。
+
+人工批准只接受 TaskDraft；行动卡不能批准或进入 Ready。批准会校验 draft/evidence hash、repo/path containment、Feature baseline 和冲突，在 staging validation 后写 TaskSpec、graph、Ready、approval/index 与 event。rename、state、approval、index、event 五个故障点均有注入回滚测试；重复批准幂等复用首次结果。`--dry-run` 零写入，`--json` 失败保持 stdout JSON、stderr 无噪声和非零退出码。
+
+## Worker Retry
+
+失败 Task Pool task 必须显式 retry，不能删除 `.harness/task-pool/runs.jsonl` 或复用失败的 `workerRunId`。canonical 命令必须携带 Feature：
+
+```bash
+agent-worker task retry <task-id> --feature-id <feature-id> --repo <target-repo> --reason "provider configuration corrected"
+agent-worker batch run-ready --feature-dir <feature-dir> --repo <target-repo>
+```
+
+`task retry` 只接受指定 Feature 下的 `Failed` state，保留旧 run 和 failure handoff，并写入 `retryOfWorkerRunId`。跨 Feature 同名 Task 时省略 `--feature-id` 必须 fail-closed。下一次 `run-ready` 生成新的 `workerRunId`；`Blocked`、`Done` 或无 state 的 task 必须先由 operator 处理根因，不能盲目重试。
+
+## Task Pool Doctor 与 State 迁移
+
+```bash
+agent-worker pool doctor --repo <target-repo> --json
+agent-worker pool migrate-state --repo <target-repo>            # dry-run 默认
+agent-worker pool migrate-state --repo <target-repo> --apply --owner <owner> --reason <reason>
+```
+
+`pool doctor` 只读扫描 v2 / legacy inventory 与映射证据，exit 0 也可带 findings。`pool migrate-state` 默认零写入；apply 需要 `--owner` 与 `--reason`，保留 bytes/hash 审计 artifact，失败全回滚，且不改写 `runs.jsonl` / `events.jsonl`。
+
+## 验证 Preset
+
+Shell preset `loop-agent-standard-verify` 跑 typecheck 与聚焦 DAG 测试。完整交付仍应使用：
+
+```bash
+bash scripts/ci.sh
+```

package/docs/production-readiness.md

@@ -1,96 +1,96 @@
-# Production Readiness v0.1
-
-本文档冻结 2026-07-06 至 2026-07-12 hardening sprint 的单任务 production readiness 标准。
-
-`loop-agent` production readiness v0.1 指：低/中风险的仓库本地 DAG 任务能以稳定、可解释、可验证、可恢复的方式运行。这不是组织级平台 readiness 声明。
-
-## 支持范围
-
-- 单仓库
-- 单任务或小范围有边界任务
-- 低/中风险的代码与文档变更
-- 显式 task source
-- 显式 `allowedPaths`、`forbiddenPaths`、`writeSet`
-- shell 验证命令
-- 通过 `dag report`、`dag doctor`、`promote-run`、`closeout` 交接
-
-## 非目标
-
-- 自动 merge
-- 自动 release
-- 生产 secrets
-- 生产数据库访问
-- 高风险 migration
-- 在线 Worker Pool
-- 多仓库 feature 编排
-- 可写的 Dynamic Workflow sharded migration
-- DAG runtime 之外的第二套 runner
-
-## 必需证据
-
-每个 production-ready v0.1 任务必须保留或产出以下证据：
-
-| 证据 | 要求 |
-|---|---|
-| DAG spec path | 生成的 DAG JSON 路径记录在 CLI 输出、report 或 task artifacts 中 |
-| DAG validation result | `dag validate --strict-models --strict-governance` 有新鲜输出 |
-| Run id | `run-dag` 打印或记录 run id |
-| Shell verification output | 完成声明引用新鲜命令输出，而非 model 自报 |
-| Failure category | 失败 run 在可用时具备 raw、normalized、product-line 与 recommended follow-up 字段 |
-| Closeout 或 failure handoff | 成功 run 可 promote 并 closeout；失败 run 产出 failure handoff 证据而非成功 closeout |
-
-## 必需命令
-
-标准任务路径：
-
-```bash
-loop-agent new-task <task-id> "Task title"
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
-loop-agent dag report --run-id <run-id> --markdown
-loop-agent dag doctor --run-id <run-id>
-loop-agent promote-run <task-id> --run-id <run-id>
-loop-agent closeout task <task-id>
-```
-
-`<temp-dir>` 使用平台原生临时目录。
-
-## 必需标准
-
-| ID | 标准 | 验收 |
-|---|---|---|
-| PRD-01 | 新任务仅推荐 DAG 路径 | README、docs、website、skills 不把已移除的 Level 1 顺序命令当作 fallback |
-| PRD-02 | 写任务有显式边界 | strict DAG governance 在需要时拒绝缺失 `allowedPaths`、`forbiddenPaths` 或 `writeSet` |
-| PRD-03 | 每次 DAG run 有可读 report | `loop-agent dag report --latest --markdown` 显示 status、failure summary 与 next step |
-| PRD-04 | 失败 run 可诊断 | `loop-agent dag doctor` 报告 category 与 recommended follow-up |
-| PRD-05 | Shell 验证是完成权威 | closeout 不接受 model 自报替代新鲜命令输出 |
-| PRD-06 | Failure category 覆盖失败 fixture | validation、write guard、shell、timeout、auth、unknown fixture 均有映射 |
-| PRD-07 | 已完成 DAG facts 不可变 | completed facts guard 仍由测试覆盖 |
-| PRD-08 | CLI 主路径输出指引下一步 | `dag run-task`、`dag validate`、`run-dag`、`dag report` 打印 operator next commands |
-| PRD-09 | 文档面一致 | doc 更新后 `bash scripts/check-repo.sh` 与 `npm run docs:build` 通过 |
-| PRD-10 | sprint 完成前完整本地门禁通过 | 最终 hardening closeout 时 `bash scripts/ci.sh` 通过 |
-
-## Failure Routing
-
-Failure category 是路由字段，不是主任务状态。保留 raw DAG facts，仅在 report、doctor 输出、closeout draft、task artifacts 或后续 Task Pool 记录中追加派生字段。
-
-四层结构：
-
-```text
-raw_failure_category
-dag_normalized_failure_category
-product_line_failure_category
-recommended_follow_up
-```
-
-Product-line category 事实源：`docs/design/state-and-failure-taxonomy.md`。
-
-## Sprint Gate
-
-2026-07-06 sprint 仅在 active execution plan 记录以下内容时视为完成：
-
-- M1–M4 最终状态
-- 必需验证门禁的命令输出
-- 成功、write-guard、shell-failure 场景的 dogfood 证据
-- 剩余风险与后续工作
+# Production Readiness v0.1
+
+本文档冻结 2026-07-06 至 2026-07-12 hardening sprint 的单任务 production readiness 标准。
+
+`loop-agent` production readiness v0.1 指：低/中风险的仓库本地 DAG 任务能以稳定、可解释、可验证、可恢复的方式运行。这不是组织级平台 readiness 声明。
+
+## 支持范围
+
+- 单仓库
+- 单任务或小范围有边界任务
+- 低/中风险的代码与文档变更
+- 显式 task source
+- 显式 `allowedPaths`、`forbiddenPaths`、`writeSet`
+- shell 验证命令
+- 通过 `dag report`、`dag doctor`、`promote-run`、`closeout` 交接
+
+## 非目标
+
+- 自动 merge
+- 自动 release
+- 生产 secrets
+- 生产数据库访问
+- 高风险 migration
+- 在线 Worker Pool
+- 多仓库 feature 编排
+- 可写的 Dynamic Workflow sharded migration
+- DAG runtime 之外的第二套 runner
+
+## 必需证据
+
+每个 production-ready v0.1 任务必须保留或产出以下证据：
+
+| 证据 | 要求 |
+|---|---|
+| DAG spec path | 生成的 DAG JSON 路径记录在 CLI 输出、report 或 task artifacts 中 |
+| DAG validation result | `dag validate --strict-models --strict-governance` 有新鲜输出 |
+| Run id | `run-dag` 打印或记录 run id |
+| Shell verification output | 完成声明引用新鲜命令输出，而非 model 自报 |
+| Failure category | 失败 run 在可用时具备 raw、normalized、product-line 与 recommended follow-up 字段 |
+| Closeout 或 failure handoff | 成功 run 可 promote 并 closeout；失败 run 产出 failure handoff 证据而非成功 closeout |
+
+## 必需命令
+
+标准任务路径：
+
+```bash
+loop-agent new-task <task-id> "Task title"
+loop-agent dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
+loop-agent dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
+loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd .
+loop-agent dag report --run-id <run-id> --markdown
+loop-agent dag doctor --run-id <run-id>
+loop-agent promote-run <task-id> --run-id <run-id>
+loop-agent closeout task <task-id>
+```
+
+`<temp-dir>` 使用平台原生临时目录。
+
+## 必需标准
+
+| ID | 标准 | 验收 |
+|---|---|---|
+| PRD-01 | 新任务仅推荐 DAG 路径 | README、docs、website、skills 不把已移除的 Level 1 顺序命令当作 fallback |
+| PRD-02 | 写任务有显式边界 | strict DAG governance 在需要时拒绝缺失 `allowedPaths`、`forbiddenPaths` 或 `writeSet` |
+| PRD-03 | 每次 DAG run 有可读 report | `loop-agent dag report --latest --markdown` 显示 status、failure summary 与 next step |
+| PRD-04 | 失败 run 可诊断 | `loop-agent dag doctor` 报告 category 与 recommended follow-up |
+| PRD-05 | Shell 验证是完成权威 | closeout 不接受 model 自报替代新鲜命令输出 |
+| PRD-06 | Failure category 覆盖失败 fixture | validation、write guard、shell、timeout、auth、unknown fixture 均有映射 |
+| PRD-07 | 已完成 DAG facts 不可变 | completed facts guard 仍由测试覆盖 |
+| PRD-08 | CLI 主路径输出指引下一步 | `dag run-task`、`dag validate`、`run-dag`、`dag report` 打印 operator next commands |
+| PRD-09 | 文档面一致 | doc 更新后 `bash scripts/check-repo.sh` 与 `npm run docs:build` 通过 |
+| PRD-10 | sprint 完成前完整本地门禁通过 | 最终 hardening closeout 时 `bash scripts/ci.sh` 通过 |
+
+## Failure Routing
+
+Failure category 是路由字段，不是主任务状态。保留 raw DAG facts，仅在 report、doctor 输出、closeout draft、task artifacts 或后续 Task Pool 记录中追加派生字段。
+
+四层结构：
+
+```text
+raw_failure_category
+dag_normalized_failure_category
+product_line_failure_category
+recommended_follow_up
+```
+
+Product-line category 事实源：`ai_workspace/loop-agent/design/state-and-failure-taxonomy.md`。
+
+## Sprint Gate
+
+2026-07-06 sprint 仅在 active execution plan 记录以下内容时视为完成：
+
+- M1–M4 最终状态
+- 必需验证门禁的命令输出
+- 成功、write-guard、shell-failure 场景的 dogfood 证据
+- 剩余风险与后续工作