@tea-agent/loop-agent 0.25.0 → 0.25.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [0.25.1] - 2026-07-30
+
+### 重点更新
+
+- 后端测试 DAG 节点新增 JaCoCo 覆盖率收集能力，支持在 L-5 dashboard 展示 Java 后端的代码行与分支覆盖率
+- 规范任务 DAG 草稿的默认输出路径，统一指向 `.harness/tasks/<task-id>/dag.json`
+- 修复 loop-agent 技能条目因注入预算超限被截断的问题，确保默认 DAG 下技能完整解析
+
+### 新增
+
+- backend-test DAG 节点 7 支持可选的 JaCoCo 覆盖率收集：通过跨网络 TCP dump JaCoCo tcpserver 数据，经 jacococli.jar 转换并解析为 code-coverage-v1 合约，供 L-5 dashboard 使用
+- task shell 配置新增 `jacocoCoverage` 字段，支持配置 endpoint、cliJarPath、includes 和 connectTimeoutMs
+- 新增面向开发与运维的 JaCoCo 覆盖率部署指南，涵盖 tcpserver agent 挂载、端口放行、cli 预装及安全提醒
+
+### 改进
+
+- `dag run-task` 与 `dag init-hybrid` 的默认输出路径改为 `.harness/tasks/<task-id>/dag.json`，不再写入系统临时目录
+- agent-worker 在 strict validate 成功后，将校验通过的草稿原子同步到 task 根 `dag.json`
+- task read-model、delegate worktree 提示及各文档示例统一指向规范化的任务草稿路径
+- skills 补充 `source-and-plan-practice.md`，明确 `import-prd` 与 `plan create` 的决策表与推荐顺序，不强制微小任务
+
+### 修复
+
+- 压缩 SKILL.md 及 required-reference 体积，修复默认 DAG 技能注入预算超限导致 loop-agent 条目被截断的问题
+
 ## [0.25.0] - 2026-07-30
 
 ### 重点更新
@@ -14,6 +39,7 @@
 
 ### 新增
 
+- backend-test DAG 节点 7 支持可选的 JaCoCo 覆盖率收集（Java 服务）：task shell 配置新增 `jacocoCoverage`（endpoint + cliJarPath + includes + connectTimeoutMs）；节点 7 在 pytest 后跨网络 TCP dump JaCoCo tcpserver 执行数据，用 jacococli.jar 转为 jacoco.xml，确定性解析为 `contracts/code-coverage-v1.json` 并喂给 L-5 dashboard 的 line/branch 指标；全程失败安全（endpoint 不通 / cli 缺失 / 解析失败 → 覆盖率降级 unavailable，不阻断测试与 L-5）
 - 提供 agent-worker Feature Packet 脚手架，内置 backend-only、frontend-only 和 fe-with-api 模板，支持原子批量写入与 validate-feature 预检
 - 新增 agent-worker feature advance 命令，编排 verify-final、delivery 到 closeout 的完整交付路径
 - 新增 agent-worker feature doctor 命令，提供只读的交付就绪诊断（覆盖证据、Pool 状态与工作区改动）

package/README.md

@@ -64,19 +64,19 @@ loop-agent new-task example-task "实现一个有明确验收标准的小功能"
 loop-agent dag run-task example-task \
   --profile auto \
   --strict-models \
-  --output <temp-dir>/example-task-dag.json
+  --output .harness/tasks/example-task/dag.json
 
 loop-agent dag validate \
-  --dag <temp-dir>/example-task-dag.json \
+  --dag .harness/tasks/example-task/dag.json \
   --strict-models \
   --strict-governance
 
 loop-agent run-dag \
-  --dag <temp-dir>/example-task-dag.json \
+  --dag .harness/tasks/example-task/dag.json \
   --cwd .
 ```
 
-`<temp-dir>` 应使用当前平台的原生临时目录。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
+省略 `--output` 时默认写入 `.harness/tasks/<task-id>/dag.json`。详细步骤见[第一次运行](website/docs/quick-start/first-run.md)和 [Agent DAG 工作流](website/docs/guides/agent-dag.md)。
 
 ## 查看执行状态
 

package/dist/application/dag/generate-task-dag.js

@@ -7,10 +7,10 @@ import { parseDagSpec } from "../../workflows/dag/types.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
 import { loadHarnessManifest } from "../../governance/harness.js";
 import { assertExecPlanIndexConsistent } from "../../governance/exec-plans.js";
-import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
+import { initHybridDagFromTask, } from "../../workflows/dag/init-hybrid.js";
 import { validateDagUseCase } from "./validate-dag.js";
 import { runDagUseCase } from "./run-dag.js";
-import { loadTaskConfig } from "../../task/runtime.js";
+import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { writeTaskConfig } from "../../infrastructure/harness/task-store.js";
 const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
 function buildValidateInput(repoRoot, dagPath, parsed) {
@@ -41,7 +41,15 @@ function isUnsafeWriteSetEntry(entry) {
     return normalized.includes(PLACEHOLDER_WRITESET_MARKER);
 }
 export async function assertSafeForExecution(dagPath) {
-    const raw = JSON.parse(await readFile(dagPath, "utf-8"));
+    let raw;
+    try {
+        const content = await readFile(dagPath, "utf-8");
+        raw = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to read valid DAG JSON at ${dagPath}: ${message}`);
+    }
     const unsafe = [];
     for (const task of raw.tasks ?? []) {
         if (task.writePolicy !== "exclusive")
@@ -126,7 +134,16 @@ function resolveReviewPacketShellCommands(task) {
     return resolveShellCommands(task.shell);
 }
 async function buildReviewPacket(input) {
-    const spec = parseDagSpec(JSON.parse(await readFile(input.dagPath, "utf-8")));
+    let raw;
+    try {
+        const content = await readFile(input.dagPath, "utf-8");
+        raw = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to read valid DAG JSON at ${input.dagPath}: ${message}`);
+    }
+    const spec = parseDagSpec(raw);
     const writers = collectWriterTasksForPacket(spec).map((task) => {
         const writeSet = task.writeSet ?? [];
         return {
@@ -247,8 +264,7 @@ export async function generateTaskDagUseCase(input) {
             : "task-source";
         profileRouting.routingReasons = candidateResult.templateSelection.reasons;
         if (parsed.profile === "auto") {
-            profileRouting.selectedByProfile =
-                resolveAutoRoutingProfile(profileRouting.candidateProfile);
+            profileRouting.selectedByProfile = resolveAutoRoutingProfile(profileRouting.candidateProfile);
         }
         else if (parsed.profileExplicit) {
             profileRouting.selectedByProfile = parsed.profile;
@@ -256,7 +272,8 @@ export async function generateTaskDagUseCase(input) {
     }
     // Persist the automatic business workflow route while preserving the
     // governance profile as a separate routing dimension.
-    if (hasAutomaticTaskSourceRoute && candidateResult.template === "frontend-implementation") {
+    if (hasAutomaticTaskSourceRoute &&
+        candidateResult.template === "frontend-implementation") {
         const taskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
         if (!taskConfig.taskKind || taskConfig.taskKind === "standard") {
             await writeTaskConfig(repoRoot, parsed.taskId, {
@@ -297,7 +314,7 @@ export async function generateTaskDagUseCase(input) {
             ok: true,
             taskId: initResult.taskId,
             outputPath,
-            defaultOutputPath: defaultHybridDagOutputPath(parsed.taskId),
+            defaultOutputPath: getTaskPaths(repoRoot, parsed.taskId).dagDraftPath,
             taskCount: initResult.taskCount,
             nodeIds: initResult.nodeIds,
             title: validateSummary.title,

package/dist/commands/dag-init-hybrid.js

@@ -1,5 +1,6 @@
 import path from "node:path";
-import { defaultHybridDagOutputPath, initHybridDagFromTask, } from "../workflows/dag/init-hybrid.js";
+import { initHybridDagFromTask } from "../workflows/dag/init-hybrid.js";
+import { getTaskPaths } from "../task/runtime.js";
 export function parseDagInitHybridArgs(args) {
     if (args.length === 0) {
         throw new Error("usage: dag init-hybrid <task-id> [--output <path>]");
@@ -44,7 +45,7 @@ export async function runDagInitHybrid(repoRoot, rawArgs) {
         ok: true,
         taskId: result.taskId,
         outputPath: result.outputPath,
-        defaultOutputPath: defaultHybridDagOutputPath(parsed.taskId),
+        defaultOutputPath: getTaskPaths(repoRoot, parsed.taskId).dagDraftPath,
         taskCount: result.taskCount,
         nodeIds: result.nodeIds,
         next: [

package/dist/commands/delegate.js

@@ -1,10 +1,9 @@
-import os from "node:os";
-import path from "node:path";
 import { delegateTask } from "../task/delegate.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 import { generateTaskDagUseCase } from "../application/dag/generate-task-dag.js";
 import { validateDagUseCase } from "../application/dag/validate-dag.js";
 import { runDagUseCase } from "../application/dag/run-dag.js";
+import { getTaskPaths } from "../task/runtime.js";
 const DELEGATE_USAGE = "usage: delegate <taskId> [--base <branch>] [--branch <name>] [--no-symlink] [--auto-run]";
 export function parseDelegateArgs(args) {
     if (args.length === 0) {
@@ -59,12 +58,13 @@ export function parseDelegateArgs(args) {
     return { taskId, base, branch, symlinkNodeModules, autoRun };
 }
 export function printDelegateNextSteps(taskId, result) {
-    const dagPath = path.join(os.tmpdir(), `${taskId}-dag.json`);
+    const dagPath = getTaskPaths(result.worktreePath, taskId).dagDraftPath;
     const lines = [
         `[delegate] worktree ready (Pi-only).`,
         `  worktree: ${result.worktreePath}`,
         `  Next — generate, validate, and run DAG in the worktree:`,
-        `    loop-agent dag run-task ${taskId} --profile auto --strict-models --output ${JSON.stringify(dagPath)}`,
+        `    cd ${JSON.stringify(result.worktreePath)}`,
+        `    loop-agent --repo-root ${JSON.stringify(result.worktreePath)} dag run-task ${taskId} --profile auto --strict-models`,
         `    loop-agent dag validate --dag ${JSON.stringify(dagPath)} --strict-models --strict-governance`,
         `    loop-agent run-dag --dag ${JSON.stringify(dagPath)} --cwd ${JSON.stringify(result.worktreePath)}`,
         `  Or: loop-agent delegate ${taskId} --auto-run`,
@@ -89,30 +89,30 @@ export async function runDelegate(repoRoot, rawArgs, dependencies = DEFAULT_RUN_
         symlinkNodeModules: parsed.symlinkNodeModules,
     });
     if (parsed.autoRun) {
-        const dagPath = path.join(os.tmpdir(), `${parsed.taskId}-delegate-dag.json`);
+        const worktreeRoot = result.worktreePath;
+        const dagPath = getTaskPaths(worktreeRoot, parsed.taskId).dagDraftPath;
         await dependencies.generateTaskDag({
-            repoRoot,
+            repoRoot: worktreeRoot,
             taskId: parsed.taskId,
-            outputPath: dagPath,
             strictModels: true,
             execute: false,
             initOnly: false,
             dryRun: false,
-            cwd: result.worktreePath,
+            cwd: worktreeRoot,
             profile: "auto",
             profileExplicit: false,
         });
         await dependencies.validateDag({
-            repoRoot,
+            repoRoot: worktreeRoot,
             dagPath,
             strictModelMatrix: true,
             strictGovernance: true,
             forbidExecutors: [],
         });
         const runSummary = await dependencies.runDag({
-            repoRoot,
+            repoRoot: worktreeRoot,
             dagPath,
-            cwd: result.worktreePath,
+            cwd: worktreeRoot,
             initOnly: false,
             dryRun: false,
         });

package/dist/commands/init.js

@@ -345,7 +345,7 @@ check_ts_import_boundary() {
   local label="$3"
   [[ -d "\${from_dir}" && -d "\${forbidden_dir}" ]] || return 0
   while IFS= read -r -d '' file; do
-    if grep -Eq "from ['\\\"][^'\\\"]*\${forbidden_dir}/|import\\(['\\\"][^'\\\"]*\${forbidden_dir}/|require\\(['\\\"][^'\\\"]*\${forbidden_dir}/" "\${file}"; then
+    if grep -Eq "from ['\\"][^'\\"]*\${forbidden_dir}/|import\\(['\\"][^'\\"]*\${forbidden_dir}/|require\\(['\\"][^'\\"]*\${forbidden_dir}/" "\${file}"; then
       violations+=("\${label}: \${file} imports \${forbidden_dir}")
     fi
   done < <(find "\${from_dir}" -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.mjs' -o -name '*.cjs' \\) -print0)
@@ -412,7 +412,8 @@ check_skill "loop-agent" \\
   "references/harness-policy.md" \\
   "references/hybrid-dag.md" \\
   "references/verification-and-failure-handling.md" \\
-  "references/command-reference.md"
+  "references/command-reference.md" \\
+  "references/source-and-plan-practice.md"
 check_skill "agent-worker" "references/agent-worker-operator.md"
 
 # loop-agent description is a YAML folded block (>-); grep ^description: only
@@ -856,9 +857,9 @@ function buildManagedAgentsBlock(input) {
         "loop-agent new-task <task-id> \"任务标题\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "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 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 .",
         "```",
         "",
         "`source/需求.md` 与 `source/执行约束.md` 必需；写入前同步 `task.json.allowedPaths` / `task.json.forbiddenPaths` 并审查 writer `writeSet`。",
@@ -1818,9 +1819,9 @@ function buildManagedReadmeBlock(input) {
         "loop-agent new-task <task-id> \"任务标题\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "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 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 .",
         "```",
         "",
         `详细工作流见 \`${input.governanceRoot}/feature-workflow.md\`；验证矩阵见 \`${input.governanceRoot}/verification-matrix.md\`。任务 source 是必需项：\`source/需求.md\` 写目标、范围、非目标、验收标准和相关链接，\`source/执行约束.md\` 写允许路径、禁止路径、受保护变更、不变量、预期验证和失败条件。`,
@@ -2050,9 +2051,9 @@ function buildTargetFeatureWorkflow(input) {
         "loop-agent new-task <task-id> \"Task title\"",
         "# write .harness/tasks/<task-id>/source/需求.md",
         "# write .harness/tasks/<task-id>/source/执行约束.md",
-        "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 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 .",
         "```",
         "",
         DAG_HARD_GATE_TRIGGER,
@@ -2674,7 +2675,7 @@ async function applySafeAction(input) {
         if (!isRecord(harness) || !isRecord(harness.executors) || !isRecord(harness.executors.pi)) {
             return false;
         }
-        if (!Object.prototype.hasOwnProperty.call(harness.executors.pi, "requiresApiKey")) {
+        if (!Object.hasOwn(harness.executors.pi, "requiresApiKey")) {
             return false;
         }
         const nextPi = { ...harness.executors.pi };

package/dist/commands/instructions.js

@@ -1,7 +1,6 @@
 import { access, readdir } from "node:fs/promises";
 import path from "node:path";
 import { getArtifactPath, getArtifactRelativePath, } from "../shared/artifacts-core.js";
-import { defaultHybridDagOutputPath } from "../workflows/dag/init-hybrid.js";
 import { getTaskDir, getTaskPaths, loadTaskConfig } from "../task/runtime.js";
 const STAGES = new Set([
     "source",
@@ -96,7 +95,7 @@ export async function buildInstructions(repoRoot, stage, taskId) {
     if (stage === "dag-draft") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
-            outputPath: defaultHybridDagOutputPath(taskId),
+            outputPath: paths.dagDraftPath,
             dependencies: [
                 paths.taskConfigPath,
                 path.join(paths.sourceDir, "需求.md"),

package/dist/executors/shell-executor.js

@@ -19,7 +19,7 @@ import { materializeFrontendLintAssessment, materializeFrontendLintBaseline, } f
 import { formatTraceabilityGateStdout, materializeBackendTestCaseManifest, runBackendTestTraceabilityGate, } from "../workflows/dag/backend-test-case-manifest.js";
 import { materializeBackendTestExecutionContract } from "../workflows/dag/backend-test-execution-contract.js";
 import { materializeBackendTestResultFromPytestHtml, materializeBackendTestResultFromRunDir, parsePytestHtmlReport } from "../workflows/dag/backend-test-result-contract.js";
-import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
+import { collectBackendTestHumanCaseCatalog, collectBackendTestMappedPytestScripts, collectJacocoCoverage, hasBlockingBackendMarkdownSafetyFindings, inspectBackendTestEnvironment, requiredBackendMarkdownCaseAcIds, renderBackendTestFacts, renderBackendTestHtml, renderBackendTestL5Dashboard, redactBackendTestOutput, validateBackendMarkdownCases, validateBackendMarkdownTraceability, writeRunReport, } from "../workflows/dag/backend-test-markdown-workflow.js";
 import { computeL5ReportMetrics } from "../workflows/dag/l5-report-metrics.js";
 import { buildBackendTestCanonicalResultFromInitialShellSnippet, materializeBackendTestClassification, } from "../workflows/dag/backend-test-classification-contract.js";
 import { backendTestSemanticReviewSchema, materializeBackendTestSemanticReview, } from "../workflows/dag/backend-test-semantic-review-contract.js";
@@ -629,10 +629,40 @@ async function executeBackendTestPipeline(input, meta) {
             catch {
                 // manifest missing: L5 AC/automation metrics degrade to unavailable.
             }
+            // Optional JaCoCo coverage collection (Java services). When jacocoCoverage
+            // is configured on the shell node, dump exec data over TCP from the
+            // JaCoCo tcpserver agent, convert via jacococli.jar, and parse into a
+            // code-coverage-v1 contract. Failure-safe: any error → coverage stays
+            // null and the L-5 dashboard degrades line/branch to unavailable.
+            let coverageContract = null;
+            const jacocoCfg = input.task.shell?.jacocoCoverage;
+            if (jacocoCfg) {
+                const sourceBinding = meta.spec.sourceBinding;
+                const requirementIds = sourceBinding?.requirementIds ?? [];
+                try {
+                    coverageContract = await collectJacocoCoverage({
+                        endpoint: jacocoCfg.endpoint,
+                        cliJarPath: jacocoCfg.cliJarPath,
+                        includes: jacocoCfg.includes ?? "*",
+                        connectTimeoutMs: jacocoCfg.connectTimeoutMs ?? 5000,
+                        workDir: reportsDir,
+                        sourceScope: { requirementIds, paths: [] },
+                        commitSha: null,
+                    });
+                }
+                catch {
+                    // coverage unavailable: JaCoCo endpoint unreachable or parse failed.
+                }
+                if (coverageContract) {
+                    const contractsDir = path.join(meta.runDir, "contracts");
+                    await mkdir(contractsDir, { recursive: true });
+                    await writeFile(path.join(contractsDir, "code-coverage-v1.json"), JSON.stringify(coverageContract, null, 2), "utf8");
+                }
+            }
             const l5Metrics = computeL5ReportMetrics({
                 result: { passed: parsed.passed, failed: parsed.failed, error: parsed.errors, skipped: parsed.skipped },
                 manifest: manifestForL5,
-                coverage: null,
+                coverage: coverageContract,
                 criticalRiskCount: parsed.failed + parsed.errors > 0 ? 1 : 0,
             });
             const failureSummaries = parsed.cases

package/dist/task/read-model.js

@@ -1,8 +1,7 @@
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { queryCursorRuns } from "../records/one-shot-runs.js";
-import { defaultHybridDagOutputPath } from "../workflows/dag/init-hybrid.js";
-import { listAllDagRunEntries, readDagRunSpec } from "../workflows/dag/lifecycle.js";
+import { listAllDagRunEntries, readDagRunSpec, } from "../workflows/dag/lifecycle.js";
 import { getTaskDir, getTaskPaths, getTaskStatus } from "./runtime.js";
 async function exists(filePath) {
     try {
@@ -28,9 +27,6 @@ async function listRelatedDagRuns(repoRoot, taskId) {
     }
     return related;
 }
-function defaultDagDraftPath(taskId) {
-    return defaultHybridDagOutputPath(taskId);
-}
 function closeoutPath(repoRoot, taskId) {
     return path.join(repoRoot, "docs", "progress", `${taskId}.md`);
 }
@@ -43,7 +39,7 @@ function deriveNextAction(input) {
     }
     if (!input.dagDraftExists && !input.latestDagRun) {
         return {
-            command: `npm run dev -- dag run-task ${input.taskId} --profile auto --strict-models --output ${input.dagDraftPath}`,
+            command: `npm run dev -- dag run-task ${input.taskId} --profile auto --strict-models`,
             reason: "source ready; DAG draft/run evidence not found",
         };
     }
@@ -86,7 +82,7 @@ export async function buildTaskReadModel(repoRoot, taskId) {
     if (!(await exists(requirementPath)))
         missing.push(requirementPath);
     const sourceReady = missing.length === 0;
-    const dagDraftPath = defaultDagDraftPath(taskId);
+    const dagDraftPath = paths.dagDraftPath;
     const dagDraftExists = await exists(dagDraftPath);
     const dagRuns = await listRelatedDagRuns(repoRoot, taskId);
     const latestDagRun = dagRuns.at(-1) ?? null;

package/dist/task/runtime.js

@@ -68,6 +68,8 @@ export function getTaskPaths(repoRoot, taskId) {
         contractPath: path.join(taskDir, 'contract.json'),
         /** Journaled contract transactions directory. */
         transactionsDir: path.join(taskDir, '.transactions'),
+        /** Canonical current DAG draft input for validate / run-dag. */
+        dagDraftPath: path.join(taskDir, 'dag.json'),
     };
 }
 export async function createTask(repoRoot, taskId, title) {
@@ -177,8 +179,15 @@ export async function getTaskStatus(repoRoot, taskId) {
     return loadWorkflowState(getTaskPaths(repoRoot, taskId).statePath);
 }
 export async function loadTaskConfig(repoRoot, taskId) {
-    const raw = await readFile(getTaskPaths(repoRoot, taskId).taskConfigPath, 'utf-8');
-    return parseTaskConfigForRuntime(JSON.parse(raw));
+    const configPath = getTaskPaths(repoRoot, taskId).taskConfigPath;
+    const raw = await readFile(configPath, 'utf-8');
+    try {
+        return parseTaskConfigForRuntime(JSON.parse(raw));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid task config at ${configPath}: ${message}`);
+    }
 }
 export function parseTaskConfigForRuntime(rawConfig) {
     const parsed = taskConfigSchema.parse(rawConfig);
@@ -292,7 +301,7 @@ export function getSupportedNextCommand(step, taskId, status, options) {
         return `npm run dev -- loop status ${taskId}`;
     }
     if (step === 'analyze' || step === 'plan' || step === 'spec' || step === 'implement' || step === 'verify' || step === 'retrospective') {
-        return `npm run dev -- dag run-task ${taskId} --profile auto --strict-models --output /tmp/${taskId}-dag.json`;
+        return `npm run dev -- dag run-task ${taskId} --profile auto --strict-models`;
     }
     return `${step} step not yet implemented in this prototype; human intervention required`;
 }

package/dist/worker/run-task/run-task.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { getTaskPaths } from "../../task/runtime.js";
 import { formatDuration, noopProgressReporter } from "../progress-reporter.js";
 import { redactForPreview, truncatePreview } from "../observability/events.js";
 import { controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
@@ -104,6 +106,13 @@ export async function runTaskSpec(options) {
         ], true, undefined, eventCtx);
     });
     progress.step(`dag validated in ${formatDuration(Date.now() - validateStartedAt)}`);
+    const canonicalDraftPath = getTaskPaths(options.repoRoot, materializeManifest.harnessTaskId).dagDraftPath;
+    await runObservedStep(eventCtx, "publish-canonical-dag-draft", async () => {
+        const dagBytes = await readFile(dagPath, "utf-8");
+        await writeTextAtomic(canonicalDraftPath, dagBytes, {
+            repoRoot: options.repoRoot,
+        });
+    });
     const runDagStep = "run-dag";
     const runDagStartedAt = Date.now();
     const dagEventsPath = path.join(getTaskPoolRoot(options.repoRoot), "observability", "runs", workerRunId, "dag-events.jsonl");
@@ -330,7 +339,7 @@ export function buildWorkerRunId(businessId, now) {
         .slice(0, 6);
     return `wr-${date}-${businessId}-${hash}`;
 }
-async function runRequiredCommand(repoRoot, client, artifactName, args, expectJson = true, timeoutMs, eventCtx) {
+async function runRequiredCommand(repoRoot, client, artifactName, args, expectJson = true, timeoutMs, _eventCtx) {
     const result = await client.run(args, {
         cwd: repoRoot,
         artifactName,
@@ -743,7 +752,14 @@ function strictModelsArgs(piModel) {
  */
 export async function applyPiModelOverride(dagPath, piModel) {
     const raw = await readFile(dagPath, "utf-8");
-    const spec = JSON.parse(raw);
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid generated DAG JSON at ${dagPath}: ${message}`);
+    }
     spec.executorModels = {
         pi: {
             LOW: piModel,

package/dist/workflows/dag/backend-test-markdown-workflow.js

@@ -1,6 +1,12 @@
 import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { connect } from "node:net";
 import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createWriteStream } from "node:fs";
 import path from "node:path";
+import { promisify } from "node:util";
+import { parseJacocoXml, } from "./backend-test-coverage-contract.js";
+const execFileAsync = promisify(execFile);
 const CASE_ID = /\bBE-[A-Z0-9]+(?:-[A-Z0-9]+)*-\d{3}\b/g;
 const AC_ID = /\bAC-[A-Z0-9]+(?:-[A-Z0-9]+)*\b/g;
 const SECRET = /(?:password|passwd|secret|token|api[_-]?key|private[_-]?key|authorization)\s*[:=]\s*\S+/i;
@@ -1079,6 +1085,98 @@ function renderQualityCard(title, summary) {
     const label = summary.status === "Unavailable" ? "不可用" : summary.status;
     return `<div style="padding:12px 14px;border:1px solid #e3e8ef;border-radius:10px;background:#fbfcfe"><div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:6px"><strong style="color:#17365d;font-size:0.88rem">${escapeHtml(title)}</strong><span style="display:inline-block;padding:2px 9px;border-radius:999px;font-weight:700;font-size:0.72rem;color:${colors.fg};background:${colors.bg}">${label}</span></div><div style="color:#667085;font-size:0.78rem">Findings：${summary.findings ?? "不可用"}</div><div style="color:#475467;font-size:0.8rem;margin-top:2px">${escapeHtml(summary.firstFinding)}</div></div>`;
 }
+/**
+ * Dump JaCoCo execution data over TCP from a JaCoCo tcpserver agent, convert
+ * .exec → jacoco.xml via jacococli.jar, then parse into a code-coverage-v1
+ * contract. Designed for Java services started with
+ * `-javaagent:jacocoagent.jar=output=tcpserver,port=6300,append=false`.
+ *
+ * Failure-safe: any transport/conversion/parse error returns null so the L-5
+ * dashboard degrades coverage to unavailable instead of blocking the run.
+ */
+export async function collectJacocoCoverage(input) {
+    const [host, portStr] = input.endpoint.split(":");
+    const port = Number(portStr);
+    if (!host || !Number.isInteger(port) || port <= 0 || port > 65535) {
+        return null;
+    }
+    const execPath = path.join(input.workDir, "jacoco.exec");
+    const xmlPath = path.join(input.workDir, "jacoco.xml");
+    // Step 1: TCP dump of JaCoCo execution data. The protocol is JaCoCo's
+    // binary "dump" command: a magic header + command byte. We send the dump
+    // request and stream the response into jacoco.exec.
+    try {
+        await dumpJacocoExec(host, port, execPath, input.connectTimeoutMs);
+    }
+    catch {
+        return null;
+    }
+    // Step 2: jacococli.jar report .exec → jacoco.xml
+    try {
+        await execFileAsync("java", [
+            "-jar", input.cliJarPath,
+            "report", execPath,
+            "--xml", xmlPath,
+            "--includes", input.includes,
+        ], { timeout: 60000, windowsHide: true });
+    }
+    catch {
+        return null;
+    }
+    // Step 3: parse jacoco.xml into a code-coverage-v1 contract.
+    try {
+        const xml = await readFile(xmlPath, "utf8");
+        const artifactSha256 = createHash("sha256").update(xml).digest("hex");
+        return parseJacocoXml(xml, {
+            sourceScope: input.sourceScope,
+            commitSha: input.commitSha,
+            artifactPath: "reports/jacoco.xml",
+            artifactSha256,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Send a JaCoCo TCP dump command and stream the response into destPath.
+ * JaCoCo tcpserver protocol: connect, send dump command header, read until close.
+ */
+function dumpJacocoExec(host, port, destPath, connectTimeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = connect({ host, port });
+        const writeStream = createWriteStream(destPath);
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error("jacoco-tcp-connect-timeout"));
+        }, connectTimeoutMs);
+        socket.on("connect", () => {
+            // JaCoCo TCP "dump" command: magic 0xC0FFEE + cmd=0x40 (dump)
+            // Format: <magic 3 bytes><cmd id 1 byte>
+            // The server responds with the exec data and closes.
+            const magic = Buffer.from([0xC0, 0xFF, 0xEE]);
+            const dumpCmd = Buffer.from([0x40]);
+            socket.end(Buffer.concat([magic, dumpCmd]));
+        });
+        socket.on("error", (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        socket.on("close", () => {
+            clearTimeout(timer);
+            writeStream.end(() => {
+                // Verify we got non-empty exec data.
+                readFile(destPath).then((buf) => {
+                    if (buf.length === 0)
+                        reject(new Error("jacoco-dump-empty"));
+                    else
+                        resolve();
+                }).catch(reject);
+            });
+        });
+        socket.pipe(writeStream);
+    });
+}
 function inferModuleScript(classname) {
     // classname like "test_process_definition_list.py::TestX::test_a" → take the file stem.
     const first = classname.split("::")[0] ?? classname;

package/dist/workflows/dag/init-hybrid.js

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
-import { access, readdir, readFile, realpath, writeFile, } from "node:fs/promises";
+import { access, readdir, readFile, realpath, } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { assertValidDagSpec } from "./validate.js";
 import { DAG_AGENT_RUNTIME_PI_ONLY, DAG_REPAIR_WRITER_PROTOCOL_EXPLICIT_NODE_V1, DAG_RUNTIME_CONTRACT_SCHEMA_VERSION, DEFAULT_DAG_OUTPUT_LANGUAGE, DEFAULT_DAG_EXECUTOR_MODELS, parseDagSpec, } from "./types.js";
 import { planMavenVerification, } from "../../verification/maven/index.js";
@@ -3515,7 +3515,7 @@ async function buildBackendTestHybridDag(sources) {
         'mkdir -p "${HARNESS_DAG_RUN_DIR}/reports"',
         'echo "pytest targets are resolved at runtime from final Markdown 自动化映射"',
     ].join("; ");
-    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.", "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, and a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON); exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
+    const execute = shellNode("execute-backend-pytest-and-html-report-shell", [traceability.id], "markdown-execute-html", "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.", "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON), and an optional contracts/code-coverage-v1.json when jacocoCoverage is configured (JaCoCo TCP dump → jacoco.xml → parsed; failure-safe); exit 0/1 with valid evidence continues.", [pytestCommand], 300000);
     if (execute.shell) {
         execute.shell.envAllowlist = collectBackendTestShellEnvAllowlist(sources);
     }
@@ -5741,9 +5741,6 @@ function buildSupervisedHybridDag(standard, sources) {
     assertValidDagSpec(spec);
     return spec;
 }
-export function defaultHybridDagOutputPath(taskId) {
-    return path.join(os.tmpdir(), `${taskId}-hybrid-dag.json`);
-}
 export async function writeHybridDagDraft(sources, outputPath, options = {}) {
     const routingProjectCapability = sources.taskConfig.taskKind === "standard" &&
         (options.template === undefined || options.template === "standard-dag")
@@ -5774,7 +5771,7 @@ export async function writeHybridDagDraft(sources, outputPath, options = {}) {
             taskId: preparedSources.taskId,
         });
     }
-    await writeFile(outputPath, `${JSON.stringify(spec, null, 2)}\n`, "utf-8");
+    await writeJsonAtomic(outputPath, spec, { repoRoot: sources.repoRoot });
     return {
         taskId: sources.taskId,
         outputPath,
@@ -5787,7 +5784,7 @@ export async function writeHybridDagDraft(sources, outputPath, options = {}) {
 export async function initHybridDagFromTask(repoRoot, taskId, options = {}) {
     const sources = await loadTaskHybridSources(repoRoot, taskId);
     assertTaskAllowedPathsPreflight(sources.taskConfig);
-    const outputPath = options.outputPath ?? defaultHybridDagOutputPath(taskId);
+    const outputPath = options.outputPath ?? getTaskPaths(repoRoot, taskId).dagDraftPath;
     return writeHybridDagDraft(sources, outputPath, {
         template: options.template,
     });

package/dist/workflows/dag/types.js

@@ -326,6 +326,17 @@ export const dagShellConfigSchema = z.object({
     frontendReviewContext: dagFrontendReviewContextSchema.optional(),
     frontendTestEvidenceValidation: dagFrontendTestEvidenceValidationSchema.optional(),
     backendTestPipeline: dagBackendTestPipelineSchema.optional(),
+    /** JaCoCo coverage collection for backend-test (Java services). When set, node 7 dumps coverage over TCP from a JaCoCo tcpserver agent and feeds it to the L-5 dashboard. */
+    jacocoCoverage: z.object({
+        /** JaCoCo tcpserver endpoint, e.g. "host:6300". */
+        endpoint: z.string().min(1),
+        /** Absolute path to jacococli.jar on this machine, used to convert .exec → jacoco.xml. */
+        cliJarPath: z.string().min(1),
+        /** Business package filter passed to JaCoCo includes, e.g. "com.example.*". Defaults to "*". */
+        includes: z.string().min(1).optional().default("*"),
+        /** TCP connect timeout in ms. Defaults to 5000. */
+        connectTimeoutMs: z.number().int().positive().optional().default(5000),
+    }).strict().optional(),
     verifyEvidence: dagShellVerifyEvidenceSchema.optional(),
     repairArtifactGate: dagRepairArtifactGateSchema.optional(),
     /** fail (default): any nonzero command fails the node. record: finish node FINISHED with failure facts for downstream assess/repair. */

package/dist/workflows/loop/actions/dag-action.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { mkdir } from "node:fs/promises";
 import { writeLoopDagRecord } from "../../../infrastructure/harness/loop-action-store.js";
+import { getTaskPaths } from "../../../task/runtime.js";
 import { getLoopPaths } from "../paths.js";
 import { appendLoopRound } from "../rounds.js";
 import { rewriteLoopContext } from "../context.js";
@@ -26,7 +27,7 @@ export async function runLoopDagAction(repoRoot, taskId, options = {}) {
     await mkdir(dagEvidenceDir, { recursive: true });
     const dagPath = options.dagPath
         ? path.resolve(repoRoot, options.dagPath)
-        : path.join(dagEvidenceDir, `round-${round}.dag.json`);
+        : getTaskPaths(repoRoot, taskId).dagDraftPath;
     const runner = options.runner ?? resolveDefaultRunner(repoRoot);
     let generated = {};
     if (!options.dagPath) {

package/docs/init-surface.manifest.json

@@ -55,6 +55,7 @@
     "skills/agent-worker/references/agent-worker-operator.md",
     "skills/loop-agent/SKILL.md",
     "skills/loop-agent/references/command-reference.md",
+    "skills/loop-agent/references/source-and-plan-practice.md",
     "skills/loop-agent/references/docs-converge.md",
     "skills/ai-engineering-context/SKILL.md",
     "skills/verification-before-completion/SKILL.md",
@@ -133,6 +134,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md",
     ".agents/skills/loop-agent/SKILL.md",
     ".agents/skills/loop-agent/references/command-reference.md",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md",
     ".agents/skills/loop-agent/references/docs-converge.md",
     ".agents/skills/ai-engineering-context/SKILL.md",
     ".agents/skills/verification-before-completion/SKILL.md",
@@ -212,6 +214,7 @@
     ".agents/skills/agent-worker/references/agent-worker-operator.md": "copied",
     ".agents/skills/loop-agent/SKILL.md": "copied",
     ".agents/skills/loop-agent/references/command-reference.md": "copied",
+    ".agents/skills/loop-agent/references/source-and-plan-practice.md": "copied",
     ".agents/skills/loop-agent/references/docs-converge.md": "copied",
     ".agents/skills/ai-engineering-context/SKILL.md": "copied",
     ".agents/skills/verification-before-completion/SKILL.md": "copied",

package/docs/templates/backend-test-dag.json

@@ -250,7 +250,7 @@
         ".harness/dag-runs/**",
         "artifacts/**"
       ],
-      "outputContract": "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, and a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON); exit 0/1 with valid evidence continues.",
+      "outputContract": "One scoped pytest execution over Markdown-mapped scripts producing a valid pytest-html report with per-case captured output, self-contained reports/backend-test.html, reports/backend-test.md, reports/backend-test-facts.md, a deterministic self-contained reports/backend-test-l5-dashboard.html (machine-computed L-5 metrics, no JSON), and an optional contracts/code-coverage-v1.json when jacocoCoverage is configured (JaCoCo TCP dump → jacoco.xml → parsed; failure-safe); exit 0/1 with valid evidence continues.",
       "subtask_prompt": "Resolve the final Markdown Automation Notes/自动化映射 to a unique, safe set of testcase/**/test_*.py targets and execute only those scripts exactly once. Prefer the deterministic module one-to-one path when a mapped script is missing but the module stem file exists. Generate a native pytest-html self-contained report, then render the primary self-contained Chinese HTML report from the same pytest-html plus final Markdown case metadata without rerun. Keep 测试结论, quality status, failure overview, and a polished per-case result card with concise scenario, automation test name, result, duration, and redacted bounded HTTP request parameters/response results for both passed and failed cases. Do not render a technical/execution evidence section in HTML; retain auditable paths and hashes in facts.",
       "shell": {
         "commands": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",

package/skills/loop-agent/SKILL.md

@@ -27,10 +27,12 @@ Entry: routing and hard rules. Required details come from frontmatter references
 
 ```bash
 loop-agent new-task <task-id> "Title"
-# Prefer immutable PRD: loop-agent import-prd <task-id> --file <path>
-loop-agent dag run-task <task-id> --profile auto --strict-models --output <dag.json>
-loop-agent dag validate --dag <dag.json> --strict-models --strict-governance
-loop-agent run-dag --dag <dag.json> --cwd <repo-root>
+# Prefer import-prd when a PRD exists; plan create for non-trivial work
+# (see references/source-and-plan-practice.md)
+loop-agent dag run-task <task-id> --profile auto --strict-models
+# default draft: .harness/tasks/<task-id>/dag.json
+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>
 ```
 
 执行前审阅 `profileRouting`、`governanceProfile`、writer `writeSet`、`forbiddenPaths`、decision gate mode。
@@ -44,10 +46,6 @@ loop-agent run-dag --dag <dag.json> --cwd <repo-root>
 | Operator commands、`agent-worker` | `references/command-reference.md` |
 | 独立验证、failure handling、closeout | `references/verification-and-failure-handling.md` |
 
-## Source Layout
-
-CLI `src/cli/`；DAG `src/workflows/dag/`；loop `src/workflows/loop/`；executors `src/executors/`；worker `src/worker/`；governance `src/governance/`。不新增平行兼容入口。
-
 ## Hard Rules
 
 1. Use vertical tracer bullets across real integration layers；each needs independent acceptance and verification.

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