@tea-agent/loop-agent 0.25.0 → 0.25.2

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
@@ -233,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 复制）。
@@ -291,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

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`：
 

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`、以及实现/验证证据。