@tea-agent/loop-agent 0.24.11-beta.0 → 0.25.1

package/skills/loop-agent/references/command-reference.md

@@ -37,12 +37,20 @@ loop-agent doctor
 
    ```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 <repo-root>
+   # 有原始 PRD 文件时（推荐默认）：
+   # loop-agent import-prd <task-id> --file <path-to-prd.md>
+   # 写 source/需求.md、执行约束.md，并同步 task.json 路径边界
+   # 非微小 / 跨会话（推荐默认）：
+   # loop-agent plan create <plan-id> "<title>"
+   loop-agent dag run-task <task-id> --profile auto --strict-models
+   loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
+   loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
+   # 有 plan 时收尾：loop-agent plan complete <plan-id> --summary "..."
    ```
 
-   `<temp-dir>` 表示平台原生临时目录；也可以省略 `--output`，再使用命令 JSON 输出里的 `outputPath`。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
+   省略 `--output` 时默认写入 `.harness/tasks/<task-id>/dag.json`（CLI JSON 的 `outputPath` / `defaultOutputPath` 为解析后的绝对路径）。显式 `--output` 仍可指向 temp 或任意路径（兼容旧脚本）。主路径 JSON 输出含稳定 summary：`dag run-task` 的 `message` 为 `DAG draft created`，`dag validate` 的 `message` 为 `DAG validation passed` 且含 `checks.writeSets` / `checks.decisionGates`，`run-dag` 的 `message` 为 `DAG run finished`。
+
+   **`import-prd` / `plan create` 不是 `dag run-task` 的硬依赖**，但有 PRD 文件或非微小实现时应默认使用；决策表、反模式与案例见 `source-and-plan-practice.md`。
 2. **Operator 工具**，用于 recovery、诊断、评测重放与 closeout：
 
    ```bash
@@ -162,6 +170,8 @@ loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [-
 
 把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
 
+`referenceDocs` 是 `{ path, name? }[]` 对象数组，不是路径字符串数组；`import-prd` 会确定性写入正确结构。
+
 ### Task Contract / operator machine surface
 
 ```bash
@@ -231,9 +241,9 @@ loop-agent --repo-root /path/to/target-repo study init <task-id> "Title" \
   --reference-glob "codex-rs/**/goal*.rs"
 
 # 编辑 source/需求.md + source/执行约束.md，然后走 DAG 路径：
-loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output <temp-dir>/<task-id>-dag.json
-loop-agent --repo-root <target-repo> dag validate --dag <temp-dir>/<task-id>-dag.json --strict-models --strict-governance
-loop-agent --repo-root <target-repo> run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <target-repo>
+loop-agent --repo-root <target-repo> dag run-task <task-id> --profile auto --strict-models --output .harness/tasks/<task-id>/dag.json
+loop-agent --repo-root <target-repo> dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
+loop-agent --repo-root <target-repo> run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <target-repo>
 ```
 
 目标 repo 需有 `.harness/prompts/feature-study-analyze.md` 与 `feature-study-plan.md`（缺失时从 loop-agent 复制）。
@@ -289,9 +299,10 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 bash scripts/run-dag-safe.sh --dag <temp-dir>/hybrid-dag.json --cwd <repo-root> [--timeout-secs 7200]  # 后台运行 + 轮询，避免外层 bash timeout 杀进程（见 agent-dag-runner.md §Adaptive liveness）
 loop-agent dag init-hybrid <task-id>                     # 生成可审阅的 DAG draft
 loop-agent dag run-task <task-id>                        # generate + validate（安全默认；无 dag-runs；standard-compatible）
-loop-agent dag workflow-plan <task-id> --profile pr-review --output <temp-dir>/<task-id>.workflow.json
-loop-agent dag workflow-validate --workflow <temp-dir>/<task-id>.workflow.json --strict-governance
-loop-agent dag workflow-compile --workflow <temp-dir>/<task-id>.workflow.json --output <temp-dir>/<task-id>-dag.json --manifest <temp-dir>/<task-id>-compile-manifest.json
+loop-agent dag workflow-plan <task-id> --profile pr-review --output .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json
+loop-agent dag workflow-validate --workflow .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json --strict-governance
+loop-agent dag workflow-compile --workflow .harness/tasks/<task-id>/workflows/planned/<name>.workflow.json --output .harness/tasks/<task-id>/workflows/compiled/<name>.dag.json --manifest .harness/tasks/<task-id>/workflows/compiled/<name>.compile-manifest.json
+# compiled workflow DAGs stay explicit; they do not implicitly replace task root dag.json
 loop-agent dag run-task <task-id> --profile auto         # 推断 governanceProfile，经 workflowPolicy.dag.profileRouting 路由
 loop-agent dag run-task <task-id> --profile minimal      # 选择 minimal 通用路由；standard 前端任务仍可自动使用前端 DAG
 loop-agent dag run-task <task-id> --profile standard     # 选择 standard 通用路由；standard 前端任务仍可自动使用前端 DAG
@@ -514,10 +525,17 @@ loop-agent knowledge query --mode search --text "keyword" --json
 agent-worker task validate <task.yaml>            # 三层校验 TaskSpec，输出 JSON
 agent-worker task explain-profile <task.yaml>     # 解释业务 type/risk -> DAG governance profile 映射
 agent-worker task validate-feature <feature-dir>  # 校验完整 feature packet 的验收、依赖、TaskSpec 和验证命令
+agent-worker feature scaffold --repo <repo-root> --template <backend-only|frontend-only|fe-with-api> \
+  --feature-id F-YYYY-NNN --title "..." \
+  [--be-path <pattern> ...] [--fe-path <pattern> ...] [--contract-path <path>] \
+  --verify-command <cmd> [--verify-command <cmd> ...] \
+  [--batch <yaml-or-json>] [--dry-run] [--json]
 agent-worker feature review --feature-dir <feature-dir> --repo <repo-root> [--json]
 agent-worker feature run --feature-dir <feature-dir> --repo <repo-root> [--dry-run] [--git-mode checkpoint] [--keep-failed-diff] [--json]
+agent-worker feature doctor --feature-dir <feature-dir> --repo <repo-root> [--json]
+agent-worker feature advance --feature-dir <feature-dir> --repo <repo-root> [--task-id <FINAL-VERIFY-id>] [--loop-agent-bin loop-agent] [--dry-run] [--apply --owner <owner>] [--json]
 agent-worker feature verify-final --feature-dir <feature-dir> --repo <repo-root> --task-id <qa-execute-id> [--json]
-agent-worker feature delivery --feature-dir <feature-dir> --repo <repo-root> --qa-evidence <path> --final-verification <path> [--waivers <path>] [--dry-run] [--json]
+agent-worker feature delivery --feature-dir <feature-dir> --repo <repo-root> [--qa-evidence <path>] [--final-verification <path>] [--waivers <path>] [--dry-run] [--json]
 agent-worker feature closeout --feature-dir <feature-dir> --repo <repo-root> [--apply --owner <owner>] [--json]
 agent-worker report metrics --repo <repo-root> --month <YYYY-MM> [--json]
 agent-worker task draft-followup <task-id> --worker-run-id <id> --feature-dir <feature-dir> --repo <repo-root> [--json]
@@ -552,12 +570,15 @@ agent-worker observe snapshot --repo <repo-root>  # 输出 GlobalSnapshot JSON
 - Worker runtime state 落在目标 repo 的 `.harness/task-pool/`（artifacts、JSONL/state、晨报、failure handoffs）。自 0.8.0 起该目录是唯一受支持的 Task Pool runtime root；旧路径不读取、不迁移、不合并、不重映射。
 - preflight 在 `new-task` 前跑 `loop-agent --version`、`inspect`、`docs-audit`、`git status --short --branch`，可选 `--check-repo`。一次夜间批处理期间不升级控制器，记录实际 `loop-agent` 版本。
 - `batch run-ready` 默认在 stderr 输出人类可读进度（批次起止、每个 task 的阶段与耗时、report 决策），stdout 只保留最终 JSON，便于管道取用；加 `--quiet` 可关闭进度。
+- `feature scaffold` 确定性生成 Feature Packet（`backend-only` / `frontend-only` / `fe-with-api`），默认 `profile: generic`，输出到 `<repo>/features/<feature-id>`；写盘前同源 `validate-feature`；`--batch` 全有或全无；不调用模型、不碰 `.harness/**`。
 - `feature review` 只读派生 Feature 状态、required AC 覆盖、阻塞、证据和唯一下一步。默认输出简洁的人类摘要，`--json` 输出 schemaVersion 1 JSON；损坏事实会显式降级，不会写 Feature Packet 或 Task Pool。
 - `feature run` 薄编排 validation、preflight、现有 run-ready、morning report、Observe snapshot 和最终 review。`--dry-run` 零写入；Git checkpoint 可用前单次最多推进一个 Ready 写任务。
 - `feature run` 遇到业务 Task 失败时仍刷新证据，但返回 `needs-action` 和非零退出码；无 Ready 是正常结果，并通过 `noReadyReason` 说明 Closed、Deliverable、AwaitingQA、NeedsAction、依赖阻塞或空 Feature。
 - `feature run --git-mode checkpoint` 是唯一 checkpoint 授权：要求 clean repo，在本地 `agent/<feature-id>` 分支按成功 Task commit；失败先保存 patch/untracked/boundary audit 再恢复 clean。默认不 commit；从不 stash/push/merge/创建远程 PR。`--keep-failed-diff` 会停止 Feature，不继续后续 Task。
+- `feature doctor` 只读诊断 Feature 交付就绪：Task Pool 状态、dirty worktree、canonical evidence / Delivery manifest 是否存在，并给出下一步命令建议（不自动修复）。
+- `feature advance`（ADR 0007）编排 `verify-final → delivery → closeout preview[/apply]`：默认 evidence 路径取自 verify-final；`--dry-run` 时 Delivery 不写盘且不 apply closeout；`--apply --owner` 在 closeout preview ready 后原子 apply。不执行实现链 Ready tasks（仍用 `feature run`）。
 - `feature verify-final` 在 clean Delivery HEAD 上复用已完成的 `qa-execute` TaskSpec 运行独立 DAG，跳过 promotion/closeout，原子生成 canonical QA aggregate 和 HEAD-bound final verification；相同 HEAD 的 canonical 成功 run 可幂等复用。
-- `feature delivery` 复用 transaction record，校验 Git history/trailers/changed files、成功 run、canonical QA/final verification 和 required AC，原子生成 manifest、coverage 与 `PR.md`；`--dry-run` 零写入。`feature closeout` 默认只读复验全部 gates，显式 `--apply --owner` 才原子写回，stale facts 或 post-validation 失败会整体回滚。
+- `feature delivery` 复用 transaction record，校验 Git history/trailers/changed files、成功 run、canonical QA/final verification 和 required AC，原子生成 manifest、coverage 与 `PR.md`；省略 evidence 路径时默认 `.harness/task-pool/evidence/<featureId>/{qa-pass,final-verification}.json`；`--dry-run` 零写入。`feature closeout` 默认只读复验全部 gates，显式 `--apply --owner` 才原子写回，stale facts 或 post-validation 失败会整体回滚。
 - `report metrics` 按 UTC 月去重投影 Feature/Failure/Follow-up/Delivery/AC/decision/recovery/boundary 指标，同时写 JSON 与 Markdown；每项保留 numerator、denominator、sampleSize 和 missingData。
 - `task draft-followup` 会按全部 failure category 生成 TaskDraft 或人工行动卡：ProductBug/TestBug/FlakyTest/DependencyFailure 可批准；EnvFailure 连续两次后才生成 ENV-CHECK；Spec/Contract/Risk/Human/Unknown 只给行动卡。人工以 `feature approve-followup --dry-run` 预览，再带非空 `--owner` 批准 TaskDraft；行动卡不能批准。批准在 staging validation 后写 TaskSpec、graph、Ready/approval/event，原失败事实不改写，并有 rename/state/approval/index/event 回滚门禁。
 - `task retry` 是失败 Task 的唯一重试入口。它会保留原有运行记录和 failure handoff，并让下一次 `batch run-ready` 使用新的 `workerRunId`；不要删除运行态文件或手动修改状态来重试。

package/skills/loop-agent/references/harness-policy.md

@@ -15,7 +15,7 @@
 ## Command surface tiers
 
 | Tier | Default purpose | Commands |
-|---|---|---|
+| --- | --- | --- |
 | Primary | Normal autonomous implementation（经 CLI） | `new-task` -> `dag run-task --profile auto` -> `dag validate --strict-models --strict-governance` -> `run-dag` |
 | Operator | Diagnose, recover, close out, inspect facts | `status`, `instructions`, `dag status`, `dag doctor`, `dag report`, `dag reconcile-run`, `dag closeout-draft`, `dag reconcile-tasks`, `dag final-verification`, `inspect`, `doctor`, `spine audit`, `knowledge curate`, `docs audit`, `handoff check`, `loop-benchmark`；Inspect：`agent-worker console serve`（`/inspect/`）与兼容 `observe serve\|snapshot` |
 | Compatibility (CLI helpers) | Legacy task metadata and feature-study helpers | `goal`, `reference`, `study` |
@@ -54,7 +54,7 @@ Minimum governed path：
 
 ```bash
 loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
-# optional but recommended for user PRDs:
+# Prefer import-prd for PRD files; plan create for non-trivial work (source-and-plan-practice.md)
 # loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--repo-root <target-repo>]
 # write derived <target-repo>/.harness/tasks/<task-id>/source/需求.md
 # write <target-repo>/.harness/tasks/<task-id>/source/执行约束.md
@@ -62,16 +62,16 @@ loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
 loop-agent dag run-task <task-id> \
   --profile auto \
   --strict-models \
-  --output <temp-dir>/<task-id>-dag.json \
+  --output .harness/tasks/<task-id>/dag.json \
   [--repo-root <target-repo>]
 
 loop-agent dag validate \
-  --dag <temp-dir>/<task-id>-dag.json \
+  --dag .harness/tasks/<task-id>/dag.json \
   --strict-models \
   --strict-governance
 
 loop-agent run-dag \
-  --dag <temp-dir>/<task-id>-dag.json \
+  --dag .harness/tasks/<task-id>/dag.json \
   --cwd <target-repo>
 ```
 
@@ -81,7 +81,7 @@ The npm package carries static capability assets: `skills/` (bundled in-package,
 
 For arbitrary target repositories, DAG skill instructions must not depend on loop-agent source history being copied into the target repo. Resolve configured, user, or target-local skills when present, then fall back to the package-bundled `skills/` (mirrored as `.agents/skills/` in the target project) as the stable default capability set.
 
-`<temp-dir>` means the platform-native temp directory. Use native paths for actual `--output`, `--dag`, and `--cwd` values on macOS and Windows; use `/` only for stable repo refs, JSON/Markdown evidence refs, and glob conventions.
+Default DAG draft: `.harness/tasks/<task-id>/dag.json`. Explicit `--output` to temp remains an escape hatch.
 
 Execution 前 review `dag run-task` JSON / `reviewPacket`：
 
@@ -124,6 +124,28 @@ On Windows, run Bash scripts through Git Bash or a configured compatible Bash. D
 
 若 `spec`、`plan` 或 DAG generation 后 source materials 变更，implementation 前 regenerate 或 revalidate plan/DAG。
 
+`task.json` 中以下字段必须是结构化对象数组，不能写成字符串数组：
+
+```json
+{
+  "referenceDocs": [
+    {
+      "name": "requirement",
+      "path": "docs/requirement.md"
+    }
+  ],
+  "verifyCommands": [
+    {
+      "label": "tests",
+      "command": "npm test",
+      "timeoutMs": 120000
+    }
+  ]
+}
+```
+
+`referenceDocs` 每项至少包含 `path`，可选 `name`；`verifyCommands` 每项至少包含 `label` 与 `command`，可选正整数 `timeoutMs`。持久化入口会在写盘前校验完整 TaskConfig，格式错误不会留下部分 `task.json`。
+
 ## Long-running loop policy
 
 `loop` 用于 long-running outer task memory：objective/context projection、round records、signals、derived events、verification summaries、closeout draft。它不是 Agent DAG 的 substitute。

package/skills/loop-agent/references/hybrid-dag.md

@@ -18,7 +18,6 @@
 
 前端专用链保留独立 contract/scout；plan 同时选择 Mock/API 策略并输出结构化 implementation contract。design initial pass 直接使用原计划，只有 request-revision 才运行 revision/final review；small-risk 只执行一次 design review。`frontend-prewrite-gate-shell` 合并生效 verdict、REQ/BR/AC 覆盖、Mock policy 和 contract 物化，是唯一写入授权。实现后 `frontend-verify-assess-shell` 合并 Mock/static/behavior/trace/assessment；只有 `eligible=true` 才运行同 writeSet 的 repair 和 `frontend-reverify-shell`。`frontend-review-context-shell` 绑定真实 diff 与有效验证证据后再 review/closeout。standard/high-risk 为 15 个顶层节点，small-risk 为 13；绿色路径执行 11 个节点、7 次 Pi。生成期 blocked Mock 只生成一个确定性阻塞节点且没有 writer。
 
-
 > Backend-test Markdown-first：先由确定性环境 Shell 检查 clean env 中 Python/pytest、常见配置、conftest/fixture、test root、server entry 和 HTML renderer，失败时不消耗模型调用。随后 Pi 生成中文 README 索引与模块用例卡片并独立 Review `testcase/md/**`。第 4 节点只把前置条件、操作步骤、预期结果作为必选章节，并检查 Case ID、业务 AC、步骤/预期和占位措辞；不校验需求来源引用有效性或 Markdown sensitive-shaped 内容。pytest writer 为每次真实接口调用记录脱敏、有界的请求 method/URL/参数摘要和响应 status/body 摘要。第 6 节点只扫描每条 Case 明确映射的 pytest 脚本，同时支持模块级函数和 pytest class 方法，并把缺少请求/响应日志、递归脱敏或有界截断证据记录为 advisory。第 4/6 节点均写 PASS/FAIL findings 而不阻断后续；pytest 仍只运行一次，生成 JUnit，并把 Markdown 名称/场景/脚本映射与同一 JUnit 合成为按测试概览、质量校验、失败概览、用例执行明细和技术证据组织的中文 self-contained HTML 与 Markdown facts。最终 Pi 按固定简洁结构汇总 advisory 状态、执行事实和 L-5 结论。active 流程不要求模型生成 backend-test 业务 JSON。
 
 显式专用 `taskKind` 保持兼容并优先于任务源分类。`backend-test` 选择固定 **8 个真实顶层节点**的 Markdown-first DAG：环境硬门、Markdown cases、独立 Review/修订、第 4 节点 advisory Markdown 校验、pytest 转换、第 6 节点 scoped advisory traceability、单次 pytest + JUnit/HTML/facts、最终 Markdown 报告与 L-5。历史 JSON contract/materializer 可继续读取旧 DAG，但新 runtime/template 不再生成模型业务 JSON。`knowledge-sync` 与 `knowledge-graph-bootstrap` 继续通过各自显式 taskKind 选择知识回写/图谱开荒 DAG。治理等级仍由 `minimal|standard|reviewed|supervised` 推断。
@@ -106,7 +105,7 @@ contract-pi → scout-src ∥ scout-tests → plan-pi → write-set-audit-pi
 ```
 
 | Stage | 减少 operator 中途介入的方式 |
-|-------|------------------------------|
+| ------- | ------------------------------ |
 | `write-set-audit-pi` | implement 前捕获 missing/overlapping writeSet owner；第一条非空行必须是 canonical verdict |
 | `write-set-audit-format-repair-pi` / `final-write-set-audit-format-repair-pi` | 初审和终审各有一次只读格式恢复；只补 canonical verdict/结构并保留 findings，结论不明确时返回 `request-revision`，不得从一般正文猜 pass |
 | `write-set-format-gate-shell` | 接受格式有效的 pass/request-revision，让有界计划修订继续；本 gate 不授权写入 |
@@ -133,8 +132,8 @@ Prompt invariant：`ai_workspace/loop-agent/templates/agent-dag-process-supervis
 ### Level 3 task-to-DAG（`dag init-hybrid` / `dag run-task`）
 
 ```bash
-loop-agent dag init-hybrid <task-id> [--output <temp-dir>/<task-id>-hybrid-dag.json]
-loop-agent dag run-task <task-id> [--output <temp-dir>/<task-id>-hybrid-dag.json]   # 安全默认：仅 generate + validate，standard-compatible
+loop-agent dag init-hybrid <task-id> [--output .harness/tasks/<task-id>/dag.json]
+loop-agent dag run-task <task-id> [--output .harness/tasks/<task-id>/dag.json]   # 安全默认：仅 generate + validate，standard-compatible
 loop-agent dag run-task <task-id> --profile auto                                # 推断 candidate governanceProfile，再经 workflowPolicy 路由
 loop-agent dag run-task <task-id> --profile minimal                             # 选择 minimal 通用路由；standard 前端任务可自动使用前端 DAG
 loop-agent dag run-task <task-id> --profile standard                            # 选择 standard 通用路由；standard 前端任务可自动使用前端 DAG
@@ -152,7 +151,9 @@ loop-agent dag run-task <task-id> --init-only --cwd <repo-root>
 
 ### DAG 与 artifacts source-of-truth 规则
 
-- 临时 DAG input spec 放平台原生临时目录（例如 `<temp-dir>/<topic>-dag.json`）；可复用 template 放 `examples/` 或 `ai_workspace/loop-agent/templates/`。
+- Canonical task DAG draft: `.harness/tasks/<task-id>/dag.json` (`dag run-task` / `init-hybrid` default).
+- Worker per-run snapshot: `artifacts/<workerRunId>-dag.json`; compiled workflows stay under `workflows/compiled/` and need explicit `--dag`.
+- Platform temp is only an explicit `--output` escape hatch. Reusable templates live in `examples/` or `ai_workspace/loop-agent/templates/`.
 - **不要**在 `.harness/dag-runs/active/` root 保留手写 DAG input 副本。
 - **不要**把 `.harness/dag-runs/` 内容 commit 到 git。
 - canonical per-run DAG 历史是 `.harness/dag-runs/completed/<run-id>/run.json` 及该 run 目录的 `state.json`、`executor.jsonl`、node artifacts；新建 run directory 使用 `YYYYMMDD-<slug>`。
@@ -168,7 +169,7 @@ loop-agent dag run-task <task-id> --init-only --cwd <repo-root>
 Pi reviewer node 设 `decisionGate.enabled: true` 时，runner 从 persisted `assistantText`（优先）或 `result.summary.md`（fallback）解析 **恰好一个** info string 为 `DECISION_ENVELOPE_JSON` 的 fenced block。Schema：`ai_workspace/loop-agent/templates/agent-dag-decision-envelope.schema.json`。Prompt：`ai_workspace/loop-agent/templates/agent-dag-decision-gate.prompt.md`（含 §Recovery Recommendation Consumption 与 schema-adherence 硬规则：勿发明 envelope schema、勿用 `decision: accept`、勿加 extra root key、`audit.runId` 须绑定当前 run id，并填 `audit.nodeId` / `audit.model`）。Playbook：`ai_workspace/loop-agent/agent-dag-recovery-playbook.md`。示例 DAG：`examples/decision-gate-agent-dag.json`。
 
 | Milestone | `decisionGate.mode` | 行为 |
-|-----------|---------------------|----------|
+| ----------- | --------------------- | ---------- |
 | **M3 record-only** | `record-only`（默认） | 写 `<node-id>/decision.envelope.json` + node record summary；**不 pause**，**不** branch 于 `decision`/`nextAction` |
 | **M4 pause-on-human** | `pause-on-human` | parse OK 且 `requiresHuman=true`：run `status=paused`，移入 `.harness/dag-runs/paused/<run-id>/`，写 `human-escalation.json` / `.md`；downstream node 保持 `PENDING` |
 | **M5 CLI** | （M4 pause 后） | 确定性 human decision — **无 LLM**，**无** `executor: human` / `executor: decision` |
@@ -228,7 +229,7 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 > 与 `ai_workspace/loop-agent/agent-dag-runner.md` §「Agent DAG authoring checklist」相同。Calibration reports：`ai_workspace/loop-agent/reports/2026-06-08-agent-dag-practice-p1-evidence-summary-docs.md` … `p5-handoff-closeout-20260608.md`。
 
 | # | Check | Expect |
-|---|-------|--------|
+| --- | ------- | -------- |
 | 1 | Topology | 优先 same-rank parallel read-only scout/review；仅 output 真正需要时加 `depends_on` |
 | 2 | Executor | 每个 task 显式声明 `executor`；`defaults.executor` 是 schema metadata，非 runtime fallback |
 | 3 | Model routing | 用 node `complexity` + `executorModels`；Pi MED（`glm-5.2`）quota 耗尽时提高 Pi node 到 `complexity: HIGH`（`gpt-5.5`）— 勿 mutate canonical model matrix |

package/skills/loop-agent/references/post-implementation-and-patterns.md

@@ -5,6 +5,7 @@
 ## 实现后处理
 
 DAG run、promotion、closeout 和最终验证完成后：
+
 1. 检查 git diff 确认预期变更
 2. 用 git commit 并 push
 3. 用户说「继续」时，跑 `status` 看 task 是否 `completed`，再创建下一个 task
@@ -12,32 +13,41 @@ DAG run、promotion、closeout 和最终验证完成后：
 ## 常见模式
 
 ### 处理多 item PRD
+
 ```
-1. new-task <id>-r1  → 准备 source → dag run-task → dag validate → run-dag → promote/closeout
-2. new-task <id>-r2  → 重复
-3. ...
+0. plan create <feature-plan> "…"（整份 PRD 一个 plan，多 task 共用）
+1. new-task <id>-r1 → import-prd（同一 PRD 或切片说明）→ 派生 需求.md → dag … → promote/closeout
+2. new-task <id>-r2 → 重复
+3. plan complete <feature-plan> --summary "…"
 ```
 
+详见 `source-and-plan-practice.md` 案例 A/C。
+
 ### Bounded task 路径
+
 ```
 1. new-task <id>
-2. 写 source/需求.md + source/执行约束.md
-3. dag run-task <id> --profile auto --strict-models --output <temp-dir>/<id>-dag.json
-4. dag validate --dag <temp-dir>/<id>-dag.json --strict-models --strict-governance
-5. run-dag --dag <temp-dir>/<id>-dag.json --cwd <repo-root>
-6. promote-run / closeout / final verification
+2. 有 PRD 文件：import-prd；再写 source/需求.md + source/执行约束.md
+3. 非微小：plan create（或挂到已有 active plan）
+4. dag run-task <id> --profile auto --strict-models
+5. dag validate --dag .harness/tasks/<id>/dag.json --strict-models --strict-governance
+6. run-dag --dag .harness/tasks/<id>/dag.json --cwd <repo-root>
+7. promote-run / closeout / final verification
+8. 有 plan：plan complete
 ```
 
-`<temp-dir>` 表示平台原生临时目录；实际命令中使用 macOS/Windows 本机路径。
+默认 DAG 草稿：`.harness/tasks/<id>/dag.json`。何时可跳过 import/plan：见 `source-and-plan-practice.md`。
 
 **关键**：实现 work 由 DAG node 和 executor 执行；main session 负责审 DAG、审 writeSet、跑验证和 handoff。
 
 ### 跨所有 task 快速 status
+
 ```bash
 loop-agent stats
 ```
 
 ### 处理 pi timeout
+
 - 默认每 step timeout 现为 30 分钟 — 通常足够
 - pi step 仍 timeout 时，用 `stats` 看 duration 分布
 - Bash tool call 应用宽松 timeout：analyze/plan 300s，implement 480s+，verify/retrospective 240s+

package/skills/loop-agent/references/source-and-plan-practice.md

@@ -0,0 +1,161 @@
+# Source 与 Exec-plan 最佳实践
+
+很多用户只跑「主路径 DAG」四步，**漏掉** `import-prd` 与 `plan create`。二者**不是** `dag run-task` 的硬依赖，但在「有原始 PRD / 非微小实现」场景下应成为默认纪律。本文给出**何时用、何时可跳、命令顺序与案例**。
+
+相关命令细节：`command-reference.md`（import-prd / plan / status）。  
+Task 目录布局：`task-workflow.md`。  
+仓库治理全文：目标仓 `governanceRoot` 下 `feature-workflow.md`（若有）。
+
+## 先分清三层
+
+| 层 | 命令 / 路径 | 作用 | 主路径 DAG 是否强制 |
+| --- | --- | --- | --- |
+| Source 事实 | `import-prd` → `source/references/*` + `source-manifest.json` | 原始 PRD **不可变**归档 | 否（有 PRD 文件时**强烈推荐**） |
+| Source 契约 | 手写 `source/需求.md`、`执行约束.md` + `task.json` 路径边界 | DAG 生成与验收真源 | **是**（至少 `需求.md`） |
+| Exec-plan | `plan create` / `plan complete` / `plan check` | 仓库级计划索引与交接 | 否（**非微小**推荐） |
+| DAG 运行时 | `dag run-task` → `dag validate` → `run-dag` | 可执行编排 | **是**（常规实现） |
+
+规则记忆：
+
+1. **`new-task` 不自动 import-prd，也不自动绑 plan。**
+2. **`dag run-task` 主要消费派生 `需求.md`**；会校验 plan **索引一致性**，但不要求当前 task 已有 active plan。
+3. 冲突时：**`source/references/*`（原始）> 派生 `需求.md` > 聊天口述。**
+
+## 决策：何时 `import-prd`
+
+### 应该用（默认「有就 import」）
+
+- 用户给了独立 PRD / 需求文档 / 设计说明文件（`.md` / 导出稿）。
+- 多轮对话已把需求定稿，且希望 **hash 可追溯**（避免模型把原文改成「唯一 source」）。
+- Worker / 多人协作：后续 review 必须三方对照 references + 需求.md + 实现。
+- 目标仓 `ai_workspace/loop-agent/` 或 `docs/` 里已有权威 PRD/spec，任务只是执行切片。
+
+### 可以跳过 import-prd
+
+- 真正微小：单文件 typo、一行配置、纯脚本命令说明，**没有**独立需求文档。
+- 用户只在聊天里给了 3～5 条验收点，且你当场写入 `需求.md` 并标明「来源：会话 YYYY-MM-DD」（仍建议短小、可验证）。
+- 已有 task 的 `source/references/` 与 manifest 完好，本次只是 re-run DAG。
+
+### 反模式
+
+- 把用户 PRD **整篇改写**进 `需求.md` 后删掉原文路径。
+- AI 直接 edit `source/references/*`。
+- 只把 PRD 路径写在聊天里，不落盘到 task 容器。
+
+### 推荐顺序（有 PRD 时）
+
+```bash
+loop-agent new-task <task-id> "简短标题"
+loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--json]
+# 再写派生契约（映射 REQ/AC 或原文锚点）
+#   .harness/tasks/<task-id>/source/需求.md
+#   .harness/tasks/<task-id>/source/执行约束.md
+# 同步 task.json.allowedPaths / forbiddenPaths
+loop-agent dag run-task <task-id> --profile auto --strict-models
+loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
+loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
+```
+
+`import-prd` 后用 `status` / `instructions source` 确认 source readiness，再生成 DAG。
+
+## 决策：何时 `plan create`
+
+### 应该用（默认「非微小就 create」）
+
+- 跨多文件 / 多模块、需要 **Contract → 分块 → 验证 → 交接** 的实现。
+- 预计超过一次会话，或要交给其他 agent / 人继续。
+- 会改 CLI、runtime、init 投影、发布面、治理脚本等 **高 blast-radius** 区域。
+- 团队要求 active plan 进 `docs/exec-plans/`（或目标仓 `governanceRoot/exec-plans/`）索引。
+- 本仓库 `AGENTS.md` 对「非微小实现」要求 plan + DAG 时。
+
+### 可以跳过 plan create
+
+- 真正 one-shot：路径已知、验收一条命令、无长期决策要记。
+- 纯 operator 维护：改一个 README 链接、修索引笔误（仍应验证，但不必开 plan）。
+- 已有 **进行中** active plan 覆盖同一工作块：更新该 plan，而不是平行再开一个同题 plan。
+
+### 与 task 的关系
+
+- **一个 plan 可覆盖多个 task**；**一个 task 也不强制 1:1 plan**。
+- plan id 建议 `YYYY-MM-DD-<slug>`；task id 可更短（业务切片名）。
+- 完成后：`plan complete <plan-id> --summary "..."`（或目标仓等价流程），不要只关 task 忘了 plan 索引。
+
+### 推荐顺序（非微小 + 有 PRD）
+
+```bash
+loop-agent plan create <plan-id> "<title>"
+# 在 plan 中写清范围、非目标、验证、允许路径（人类/agent 共读）
+loop-agent new-task <task-id> "切片标题"
+loop-agent import-prd <task-id> --file <prd>
+# 写 需求.md / 执行约束.md / task.json 边界
+loop-agent dag run-task <task-id> --profile auto --strict-models
+# … validate → run-dag → promote-run → closeout …
+loop-agent plan complete <plan-id> --summary "结果导向摘要 + 验证证据"
+```
+
+微小 escape hatch（须在 handoff / plan 或 task 备注写明边界）：
+
+```bash
+loop-agent new-task <task-id> "微小修复"
+# 直接 需求.md（可选 import-prd）
+loop-agent dag run-task <task-id> --profile auto --strict-models
+# …
+```
+
+## 实践案例
+
+### 案例 A — 用户丢来一份 PRD 文件（默认完整路径）
+
+**信号**：`帮我按这个 PRD 实现…` + 附件/路径。  
+**做法**：非微小则先 `plan create`（或复用 active plan）→ `new-task` → **`import-prd`** → 派生 `需求.md`（目标/非目标/AC，锚回 references）→ 路径边界 → DAG。  
+**验收**：`source/references/` 有原文；manifest hash 在；review 能三方对照。
+
+### 案例 B — 聊天里三句话小需求（可跳过 import + plan）
+
+**信号**：`把 X 按钮文案改成 Y`，单文件。  
+**做法**：`new-task` → 短 `需求.md`（写清唯一验收）→ `dag run-task`…  
+**不要**：为了「流程完整」空跑 `import-prd`（无文件）或堆一个空洞 plan。
+
+### 案例 C — 源仓改 CLI 默认行为（必须 plan，PRD 视情况）
+
+**信号**：行为变更、CHANGELOG、skills/init 多表面。  
+**做法**：**`plan create`** 先冻结契约与工作块 → 按块 `new-task` → 有设计文档则 import → DAG → 定向验证 → `plan complete`。  
+**验收**：active/completed 索引与 plan 正文一致；`plan check` / `dag run-task` 索引 preflight 不红。
+
+### 案例 D — agent-worker / Feature 已 materialize source_docs
+
+**信号**：TaskSpec 已把 `source_docs` 拷进 `source/references/`。  
+**做法**：通常 **不必再 import-prd** 同一文件；检查 references + 派生 `需求.md` 顶部「冲突以 references 为准」→ 补边界 → DAG。  
+**仍建议**：产品线级大功能在 Feature / 仓库层有 plan 或 Feature Packet 记录。
+
+### 案例 E — 用户说「loop-agent 帮我完成 XXX」无附件
+
+**信号**：强路由进 DAG，但无 PRD 路径。  
+**做法**：主会话 **先问清**是否有 PRD 文件；有则 import；无则把会话共识写入 `需求.md` 并标来源 → 判断微小 vs 非微小决定是否 `plan create` → 再 `dag run-task`。  
+**禁止**：主会话直接写业务代码代替 DAG。
+
+## 宿主 agent 检查清单（编排时）
+
+在第一次 `dag run-task` 前快速自问：
+
+1. 是否存在用户/仓库原始需求文件？→ **有则 `import-prd`**。
+2. `source/需求.md` 是否含目标、非目标、可验证验收？→ **无则先写**。
+3. `allowedPaths` / `forbiddenPaths` 是否已结构化？→ **无则先写**。
+4. 是否非微小 / 跨会话 / 高 blast-radius？→ **`plan create` 或更新已有 active plan**。
+5. 是否仅聊天约束？→ **落盘到 source 或 plan**，不要只留在对话。
+
+## 与「主路径 DAG」文档的关系
+
+`SKILL.md` / `command-reference.md` 的 **主路径 DAG** 仍是最短 runtime 闭环（便于抄命令）。  
+**系统化默认**应读作：
+
+```text
+[非微小?] plan create（或复用 active plan）
+new-task
+[有 PRD?] import-prd
+派生 需求.md / 执行约束.md / task.json 路径边界
+dag run-task → validate → run-dag → promote/closeout
+[有 plan?] plan complete
+```
+
+不要把 `import-prd` / `plan create` 伪造成「无文件也必须执行」的假步骤；用本节决策表选择，而不是一律省略。

package/skills/loop-agent/references/task-workflow.md

@@ -8,12 +8,14 @@
 
 ```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 <repo-root>
+# 有原始 PRD：loop-agent import-prd <task-id> --file <prd>
+# 非微小：loop-agent plan create <plan-id> "<title>"（可与 task 解耦，见 source-and-plan-practice.md）
+loop-agent dag run-task <task-id> --profile auto --strict-models
+loop-agent dag validate --dag .harness/tasks/<task-id>/dag.json --strict-models --strict-governance
+loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
 ```
 
-`<temp-dir>` 表示平台原生临时目录。实际文件路径必须兼容 macOS 和 Windows；只有 repo refs、JSON/Markdown 证据 refs 和 glob 约定默认使用 `/`。
+默认 DAG 草稿为 `.harness/tasks/<task-id>/dag.json`。repo-relative 示例用 `/`；Windows 由 Node 解析本地路径。何时必须 `import-prd` / `plan create`：见 `source-and-plan-practice.md`。
 
 当目标仓库是 loop-agent 本仓库时，`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 的任务；源码开发和 focused debugging 才使用 `npm run dev -- <args>`。
 
@@ -33,10 +35,11 @@ loop-agent run-dag --dag <temp-dir>/<task-id>-dag.json --cwd <repo-root>
   task.json
 ```
 
-- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。
+- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就 import**；无独立文件才允许只写 `需求.md`（见 `source-and-plan-practice.md` 决策表）。
 - `需求.md` 是派生执行契约：写清目标、验收标准、非目标，并用 REQ/AC 或原文锚点映射回 references。
 - `执行约束.md` 写清允许文件、禁止改动、硬约束和验证命令。
 - 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再在 `需求.md` 引用；避免把长 PRD 直接改写成唯一 source。
+- 仓库级 exec-plan（`plan create`）与 harness task **解耦**：非微小实现应有 plan 或复用 active plan；微小任务可不建 plan。
 - Worker / TaskSpec materialize 路径会把 `source_docs` 复制到 `source/references/`，并在派生 `需求.md` 顶部声明“冲突以 references 为准”；`acceptance_refs` 应展开为短摘要而不只写 ID。
 - review 节点必须三方对照：`source/references/*`（尤其 requirement/acceptance）、派生 `需求.md`、以及实现/验证证据。
 
@@ -75,6 +78,11 @@ loop-agent --repo-root /path/to/target-repo <command>
 - `verifyCommands` / adapter verification settings
 - `dagFallbackReason`，仅用于记录为何某个长期 loop 缺少 DAG round evidence
 
+结构化数组字段：
+
+- `referenceDocs` 必须是 `{ path, name? }[]`，不能是路径字符串数组。
+- `verifyCommands` 必须是 `{ label, command, timeoutMs? }[]`，不能是命令字符串数组。
+
 切片形状：每个 task 应是可独立验证的垂直 tracer bullet，而不是某一层的水平批处理。Autonomy（AFK/HITL）与 governance profile（`minimal`/`standard`/`reviewed`/`supervised`）分开声明；默认 `--profile auto`。
 
 ## Verification