@tea-agent/loop-agent 0.25.6 → 0.26.1

package/dist/workflows/dag/lifecycle.js

@@ -1,4 +1,4 @@
-import { access, mkdir, readFile, readdir, rename, } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, rename } from "node:fs/promises";
 import path from "node:path";
 import { hostname as localHostname } from "node:os";
 import { writeJsonAtomic, } from "../../infrastructure/harness/atomic-write.js";
@@ -170,20 +170,22 @@ export function assessDagRunLiveness(input) {
         return { status: "unknown" };
     if (runner.hostname !== (input.hostname ?? localHostname()))
         return { status: "unknown-host" };
-    const isAlive = input.isProcessAlive ?? ((pid) => {
-        try {
-            process.kill(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    });
+    const isAlive = input.isProcessAlive ??
+        ((pid) => {
+            try {
+                process.kill(pid, 0);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
     if (!isAlive(runner.pid))
         return { status: "orphaned", runnerAlive: false };
     const heartbeatMs = Date.parse(runner.heartbeatAt);
     const nowMs = (input.now ?? new Date()).getTime();
-    if (!Number.isNaN(heartbeatMs) && nowMs - heartbeatMs > (input.staleThresholdMs ?? 90_000)) {
+    if (!Number.isNaN(heartbeatMs) &&
+        nowMs - heartbeatMs > (input.staleThresholdMs ?? 90_000)) {
         return { status: "stale", runnerAlive: true };
     }
     const activeNode = Object.values(input.state.nodes).find((node) => node.status === "RUNNING");
@@ -193,20 +195,20 @@ export function assessDagRunLiveness(input) {
     if (activeNode.livenessStatus === "needs-attention") {
         return { status: "needs-attention", runnerAlive: true };
     }
-    if (activeNode.livenessStatus === "suspected-stall"
-        || activeNode.livenessStatus === "probing") {
+    if (activeNode.livenessStatus === "suspected-stall" ||
+        activeNode.livenessStatus === "probing") {
         return { status: "suspected-stall", runnerAlive: true };
     }
     if (activeNode.livenessStatus === "quiet") {
         return { status: "node-quiet", runnerAlive: true };
     }
     // Fall back to meaningful progress clocks (never use runner lease as progress).
-    const meaningfulAt = activeNode.lastMeaningfulProgressAt
-        ?? activeNode.lastProviderActivityAt
-        ?? activeNode.lastToolActivityAt
-        ?? activeNode.lastOutputActivityAt
-        ?? activeNode.lastActivityAt
-        ?? activeNode.startedAt;
+    const meaningfulAt = activeNode.lastMeaningfulProgressAt ??
+        activeNode.lastProviderActivityAt ??
+        activeNode.lastToolActivityAt ??
+        activeNode.lastOutputActivityAt ??
+        activeNode.lastActivityAt ??
+        activeNode.startedAt;
     const nodeActivityMs = Date.parse(meaningfulAt ?? "");
     if (!Number.isNaN(nodeActivityMs)) {
         const idleMs = nowMs - nodeActivityMs;
@@ -229,12 +231,12 @@ export function deriveDagRunEffectiveStatus(input) {
     if (input.lifecycle === "paused")
         return "paused";
     if (input.lifecycle === "completed") {
-        return input.state.status === "finished" ? "finished" : "failed";
+        return mapTerminalDagRunEffectiveStatus(input.state.status);
     }
     if (input.state.status === "pending")
         return "pending";
     if (isTerminalDagRunStatus(input.state.status)) {
-        return input.state.status === "finished" ? "finished" : "failed";
+        return mapTerminalDagRunEffectiveStatus(input.state.status);
     }
     if (input.liveness === "orphaned" || input.liveness === "stale")
         return "interrupted";
@@ -252,19 +254,20 @@ export function deriveDagRunEffectiveStatus(input) {
 }
 export function assessDagRunRecoveryEligibility(input) {
     const reasons = [];
-    const canResume = input.lifecycle === "active"
-        && input.state.status === "running"
-        && Boolean(input.state.humanDecisionNodeId)
-        && Boolean(input.hasHumanApproval);
+    const canResume = input.lifecycle === "active" &&
+        input.state.status === "running" &&
+        Boolean(input.state.humanDecisionNodeId) &&
+        Boolean(input.hasHumanApproval);
     if (!canResume)
         reasons.push("standard-resume-preconditions-not-met");
     let canReconcile = true;
-    if (input.lifecycle === "completed" || isTerminalDagRunStatus(input.state.status)) {
+    if (input.lifecycle === "completed" ||
+        isTerminalDagRunStatus(input.state.status)) {
         canReconcile = false;
         reasons.push("run-already-terminal");
     }
-    if (input.lifecycle === "active"
-        && [
+    if (input.lifecycle === "active" &&
+        [
             "active",
             "node-quiet",
             "suspected-stall",
@@ -298,6 +301,13 @@ export const TERMINAL_RUN_STATUSES = new Set([
 export function isTerminalDagRunStatus(status) {
     return TERMINAL_RUN_STATUSES.has(status);
 }
+function mapTerminalDagRunEffectiveStatus(status) {
+    if (status === "finished")
+        return "finished";
+    if (status === "partial_failed")
+        return "partial_failed";
+    return "failed";
+}
 function listPendingNodeIds(state) {
     return Object.values(state.nodes)
         .filter((node) => node.status === "PENDING")
@@ -477,8 +487,8 @@ export async function listAllDagRunEntries(repoRoot) {
         located.push(...(await listRunsInLifecycleDir(repoRoot, lifecycle)));
     }
     return located.sort((left, right) => {
-        const lifecycleCompare = DAG_LIFECYCLE_SCAN_ORDER.indexOf(left.lifecycle)
-            - DAG_LIFECYCLE_SCAN_ORDER.indexOf(right.lifecycle);
+        const lifecycleCompare = DAG_LIFECYCLE_SCAN_ORDER.indexOf(left.lifecycle) -
+            DAG_LIFECYCLE_SCAN_ORDER.indexOf(right.lifecycle);
         if (lifecycleCompare !== 0)
             return lifecycleCompare;
         return left.runId.localeCompare(right.runId);

package/dist/workflows/dag/node-execution.js

@@ -16,6 +16,8 @@ import { assertSkillSnapshotCoversSpec, buildNodePromptFromSnapshot, isDagSkillS
 import { resolveDagSkillInstructions, skillInstructionMetadata, } from "./skill-instructions.js";
 import { parseRepairArtifactFromText, resolveRepairTaskForGate, validateRepairArtifactScope, } from "./repair-artifact.js";
 import { resolveModelForTask, } from "./types.js";
+import { loadHarnessManifest } from "../../governance/harness.js";
+import { resolveExecutorThinkingMatrix } from "../../executors/model-routing.js";
 export function buildNodePrompt(spec, task, upstream, options) {
     const policy = resolveContextPolicy(spec);
     return buildDagNodePromptEnvelope({
@@ -359,6 +361,16 @@ export async function executeDagNode(input) {
     node.resolvedSkills = resolvedSkills;
     await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
     const model = resolveModelForTask(task, spec.executorModels);
+    let thinking;
+    if (task.executor === "pi") {
+        try {
+            const manifest = await loadHarnessManifest(cwd);
+            thinking = resolveExecutorThinkingMatrix(manifest.executors?.pi)[task.complexity];
+        }
+        catch {
+            // Invalid or missing harness preserves the previous no-override behavior.
+        }
+    }
     const retryPolicy = task.retryPolicy && isSafeReadOnlyPiRetryCandidate(task)
         ? task.retryPolicy
         : undefined;
@@ -418,6 +430,7 @@ export async function executeDagNode(input) {
                 task,
                 cwd,
                 model,
+                ...(thinking ? { thinking } : {}),
                 prompt: buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason),
                 attempt: attemptNumber,
                 reportActivity,

package/dist/workflows/dag/types.js

@@ -74,7 +74,9 @@ export const dagVerdictGateSchema = z.object({
      * Prefer listing the post-revision / final reviewer first when both may exist.
      */
     fallbackFromNodeIds: z
-        .array(z.string().regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
+        .array(z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, "fallbackFromNodeIds must be kebab-case"))
         .optional(),
     accept: z.array(z.string().min(1)).min(1),
     lineMode: z.enum(["first-non-empty", "first-verdict-line"]).optional(),
@@ -130,15 +132,20 @@ export const dagFrontendPrewriteGateSchema = z.object({
     planFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
     reviewFromNodeId: dagFrontendNodeIdSchema,
     reviewFallbackFromNodeIds: z.array(dagFrontendNodeIdSchema).default([]),
-    requiredRequirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)).default([]),
-    allowedMockStrategies: z.array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"])).min(1),
+    requiredRequirementIds: z
+        .array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/))
+        .default([]),
+    allowedMockStrategies: z
+        .array(z.enum(["native", "browser-intercept", "request-adapter", "not-needed"]))
+        .min(1),
     artifactName: z.string().regex(/^[a-z0-9][a-z0-9._-]*\.json$/),
     outputDir: z.string().regex(/^[a-z0-9][a-z0-9._-]*$/),
     requireSourceFreshness: z.literal(true),
     implementationWriteSet: z.array(z.string().min(1)).min(1).optional(),
     openspecCandidatePaths: z
-        .array(z.string().refine((candidate) => !candidate.includes("\\") &&
-        isOpenspecSpecFilePath(candidate), "openspec candidate must be a repo-relative supported file under openspec/schemas/ or openspec/project-specs/"))
+        .array(z
+        .string()
+        .refine((candidate) => !candidate.includes("\\") && isOpenspecSpecFilePath(candidate), "openspec candidate must be a repo-relative supported file under openspec/schemas/ or openspec/project-specs/"))
         .default([]),
 });
 export const dagFrontendLintBaselineSchema = z
@@ -148,7 +155,8 @@ export const dagFrontendLintBaselineSchema = z
     lintEvidence: dagShellVerifyEvidenceSchema,
 })
     .strict();
-export const dagFrontendVerificationBundleSchema = z.object({
+export const dagFrontendVerificationBundleSchema = z
+    .object({
     schemaVersion: z.literal(1),
     mockCommands: z.array(z.string()).default([]),
     lintCommands: z.array(z.string().min(1)).optional(),
@@ -161,7 +169,8 @@ export const dagFrontendVerificationBundleSchema = z.object({
     lintBaselineNodeId: dagFrontendNodeIdSchema.optional(),
     writerNodeIds: z.array(dagFrontendNodeIdSchema).optional(),
     mode: z.enum(["initial", "repair"]),
-}).superRefine((bundle, context) => {
+})
+    .superRefine((bundle, context) => {
     const groups = [
         ["mock", bundle.mockCommands, bundle.mockEvidence],
         ["lint", bundle.lintCommands ?? [], bundle.lintEvidence],
@@ -169,23 +178,48 @@ export const dagFrontendVerificationBundleSchema = z.object({
         ["behavior", bundle.behaviorCommands, bundle.behaviorEvidence],
     ];
     for (const [name, commands, evidence] of groups) {
-        if ((name === "mock" || name === "lint") && commands.length === 0 && !evidence)
+        if ((name === "mock" || name === "lint") &&
+            commands.length === 0 &&
+            !evidence)
             continue;
         if (!evidence) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`], message: `${name} evidence is required when commands are configured` });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`],
+                message: `${name} evidence is required when commands are configured`,
+            });
             continue;
         }
         if (evidence.commandCount !== commands.length) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandCount"], message: `${name} commandCount must match commands` });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandCount"],
+                message: `${name} commandCount must match commands`,
+            });
         }
         if (evidence.commandLabels.length !== commands.length) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandLabels"], message: `${name} commandLabels must match commands` });
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandLabels"],
+                message: `${name} commandLabels must match commands`,
+            });
         }
-        if (evidence.commandTexts.length !== commands.length || evidence.commandTexts.some((command, index) => command !== commands[index])) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandTexts"], message: `${name} commandTexts must exactly match commands` });
+        if (evidence.commandTexts.length !== commands.length ||
+            evidence.commandTexts.some((command, index) => command !== commands[index])) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandTexts"],
+                message: `${name} commandTexts must exactly match commands`,
+            });
         }
-        if (new Set(evidence.commandLabels).size !== evidence.commandLabels.length || evidence.commandLabels.some((label) => !label.trim())) {
-            context.addIssue({ code: z.ZodIssueCode.custom, path: [`${name}Evidence`, "commandLabels"], message: `${name} commandLabels must be non-empty and unique` });
+        if (new Set(evidence.commandLabels).size !==
+            evidence.commandLabels.length ||
+            evidence.commandLabels.some((label) => !label.trim())) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: [`${name}Evidence`, "commandLabels"],
+                message: `${name} commandLabels must be non-empty and unique`,
+            });
         }
     }
     if ((bundle.lintCommands?.length ?? 0) > 0) {
@@ -318,9 +352,12 @@ export const dagShellConfigSchema = z.object({
     commands: z.array(z.string()).default([]),
     preset: dagShellPresetSchema.optional(),
     verdictGate: dagVerdictGateSchema.optional(),
-    projectGovernanceGate: z.object({
+    projectGovernanceGate: z
+        .object({
         contextPath: z.literal(".runtime/project-governance-context.json"),
-    }).strict().optional(),
+    })
+        .strict()
+        .optional(),
     requirementCoverageGate: dagRequirementCoverageGateSchema.optional(),
     jsonArtifactGate: dagJsonArtifactGateSchema.optional(),
     frontendPrewriteGate: dagFrontendPrewriteGateSchema.optional(),
@@ -333,7 +370,8 @@ export const dagShellConfigSchema = z.object({
     frontendTestHtmlReport: dagFrontendTestHtmlReportSchema.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({
+    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. */
@@ -342,7 +380,9 @@ export const dagShellConfigSchema = z.object({
         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(),
+    })
+        .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/docs/templates/harness.schema.json

@@ -187,10 +187,32 @@
       "enum": ["standard-dag", "review-gated-dag", "supervised-implementation"],
       "description": "某个治理 profile 选择的 DAG 生成模板。"
     },
+    "executorTierModel": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["model"],
+          "properties": {
+            "model": {
+              "type": "string",
+              "minLength": 1,
+              "description": "模型 id 或 provider/model 限定引用。"
+            },
+            "thinking": {
+              "type": "string",
+              "description": "可选 Pi thinking level（如 max/low）。省略时不强制覆盖 Pi 默认。"
+            }
+          }
+        }
+      ],
+      "description": "executor 复杂度档模型：字符串 model id，或 { model, thinking? }。字面值 default 表示不覆盖。"
+    },
     "executor": {
       "type": "object",
       "additionalProperties": false,
-      "description": "executor 设置。DAG 模型选择优先读取 LOW/MED/HIGH，其次读取 defaultModel，最后回退到 loop-agent runtime 默认矩阵。字面值 default 表示不覆盖。",
+      "description": "executor 设置。DAG 模型选择优先读取 LOW/MED/HIGH，其次读取 defaultModel，最后回退到 loop-agent runtime 默认矩阵。字面值 default 表示不覆盖。LOW/MED/HIGH 可为字符串或 { model, thinking? } 对象。",
       "properties": {
         "description": { "type": "string" },
         "enabled": { "type": "boolean" },
@@ -200,16 +222,16 @@
           "default": "default"
         },
         "LOW": {
-          "type": "string",
-          "description": "LOW 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。"
+          "$ref": "#/$defs/executorTierModel",
+          "description": "LOW 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。可为模型字符串，或 { model, thinking? } 对象。"
         },
         "MED": {
-          "type": "string",
-          "description": "MED 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。"
+          "$ref": "#/$defs/executorTierModel",
+          "description": "MED 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。可为模型字符串，或 { model, thinking? } 对象。"
         },
         "HIGH": {
-          "type": "string",
-          "description": "HIGH 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。"
+          "$ref": "#/$defs/executorTierModel",
+          "description": "HIGH 复杂度 DAG task 的模型覆盖值，优先级高于 defaultModel。可为模型字符串，或 { model, thinking? } 对象。"
         },
         "requiresApiKey": {
           "type": "string",

package/docs/templates/init-managed-agents.md

@@ -86,19 +86,24 @@ pwd → `README.md` → `harness.json` → `__LOOP_AGENT_GOVERNANCE_ROOT__/READM
 
 ```bash
 loop-agent new-task <task-id> "任务标题"
-# 有原始 PRD 时（推荐）：loop-agent import-prd <task-id> --file <path-to-prd.md>
+# 推荐默认：详细 PRD → import → prepare（无需手写两个 source；默认无 LLM 写 source）
+loop-agent import-prd <task-id> --file <path-to-prd.md>
 # 非微小或跨会话任务（推荐）：loop-agent plan create <plan-id> "<title>"
-# write .harness/tasks/<task-id>/source/需求.md
-# write .harness/tasks/<task-id>/source/执行约束.md
+loop-agent task source prepare <task-id> \
+  --use-imported-prd \
+  --allowed-path "<glob>" \
+  --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" \
+  --apply --json
 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 .
 # 有 plan 时收尾：loop-agent plan complete <plan-id> --summary "..."
 ```
 
-`source/需求.md` 与 `source/执行约束.md` 必需；有原始 PRD 时优先用 `import-prd` 原样归档。`import-prd` / `plan create` 不是 `dag run-task` 的硬依赖。写入前同步 `task.json.allowedPaths` / `task.json.forbiddenPaths` 并审查 writer `writeSet`。
+`source/需求.md` 与 `source/执行约束.md` 仍必需（M8/M9），但默认由 `task source prepare --apply` 投影生成，而不是主会话手写。有原始 PRD 时优先 `import-prd` 原样归档。`import-prd` / `plan create` 不是 `dag run-task` 的硬依赖。写入前同步 `task.json.allowedPaths` / `task.json.forbiddenPaths` 并审查 writer `writeSet`。
 
-凡是影响项目公共契约、执行入口、交付流水线、自动化/治理、数据模型、安全或权限模型、跨模块行为、用户可见工作流的改动，都必须在编辑实现文件前先创建任务、写好两个 source 文件、生成 DAG，并审查 DAG/writeSet。
+凡是影响项目公共契约、执行入口、交付流水线、自动化/治理、数据模型、安全或权限模型、跨模块行为、用户可见工作流的改动，都必须在编辑实现文件前先创建任务、完成 source prepare（或等价 managed contract）、生成 DAG，并审查 DAG/writeSet。
 
 ### 任务类型路由（taskKind）
 

package/harness.json

@@ -58,9 +58,8 @@
   "executors": {
     "pi": {
       "description": "Pi planning, review, diagnosis, and bounded writing when DAG toolProfile=write",
-      "defaultModel": "minimax-m3",
       "LOW": "minimax-m3",
-      "MED": "gpt-5.5",
+      "MED": {"model": "deepseek/deepseek-v4-flash","thinking": "max"},
       "HIGH": "gpt-5.6-sol"
     }
   }

package/package.json

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

package/skills/loop-agent/SKILL.md

@@ -27,8 +27,11 @@ Entry: routing and hard rules. Required details come from frontmatter references
 
 ```bash
 loop-agent new-task <task-id> "Title"
-# Prefer import-prd when a PRD exists; plan create for non-trivial work
-# (see references/source-and-plan-practice.md)
+# PRD-first default: detailed PRD → import-prd → task source prepare --apply
+# no hand-written/LLM source by default
+loop-agent import-prd <task-id> --file <prd.md>
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
+# 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

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

@@ -37,9 +37,14 @@ loop-agent doctor
 
    ```bash
    loop-agent new-task <task-id> "Task Title"
-   # 有原始 PRD 文件时（推荐默认）：
-   # loop-agent import-prd <task-id> --file <path-to-prd.md>
-   # 写 source/需求.md、执行约束.md，并同步 task.json 路径边界
+   # 推荐默认：详细 PRD → import → prepare（无需手写两 source；默认无 LLM 写 source）
+   loop-agent import-prd <task-id> --file <path-to-prd.md>
+   loop-agent task source prepare <task-id> \
+     --use-imported-prd \
+     --allowed-path "<glob>" \
+     --forbidden-path ".harness/**" \
+     --verify "typecheck:npm run typecheck" \
+     --apply --json
    # 非微小 / 跨会话（推荐默认）：
    # loop-agent plan create <plan-id> "<title>"
    loop-agent dag run-task <task-id> --profile auto --strict-models
@@ -168,7 +173,7 @@ loop-agent new-task <task-id> "Task Title"
 loop-agent import-prd <task-id> --file ai_workspace/loop-agent/path/to-prd.md [--name requirement] [--json]
 ```
 
-把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后再写派生的 `source/需求.md` 执行契约；冲突时以 `source/references/*` 为准。
+把用户原始 PRD **原样复制** 到 `.harness/tasks/<task-id>/source/references/`，并写入 `source/source-manifest.json`（含 SHA-256）与 `task.json.referenceDocs`。此步骤不调用模型、不改写内容。随后用 `task source prepare --use-imported-prd --apply` 派生 managed `source/需求.md` / `执行约束.md`；冲突时以 `source/references/*` 为准。
 
 `referenceDocs` 是 `{ path, name? }[]` 对象数组，不是路径字符串数组；`import-prd` 会确定性写入正确结构。
 
@@ -213,22 +218,19 @@ one-shot run evidence 位于 `.harness/runs/{active,completed,failed}/<run-id>/`
 
 ### 运行任何 step 前：准备 source materials
 
-`new-task` 之后，先归档原始 PRD，再写派生执行契约：
+`new-task` 之后，先归档原始 PRD，再 `task source prepare` 派生执行契约：
 
 ```bash
 loop-agent import-prd <task-id> --file <path-to-original-prd.md>
-# then write derived contract:
-mkdir -p <repo-root>/.harness/tasks/<task-id>/source
-cat > <repo-root>/.harness/tasks/<task-id>/source/需求.md
+loop-agent task source prepare <task-id> \
+  --use-imported-prd \
+  --allowed-path "<glob>" \
+  --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" \
+  --apply --json
 ```
 
-`需求.md` 写目标、范围、非目标与验收标准，并映射回 `source/references/*`；不要让 AI 直接改写原始 PRD。
-
-若 task 有硬约束（仅允许特定文件、禁止改动），另加：
-
-```bash
-cat > <repo-root>/.harness/tasks/<task-id>/source/执行约束.md
-```
+默认无 LLM 写 source；工程边界用 flags 显式给出。不要让 AI 直接改写 `source/references/*`。高级用户仍可手工编辑后 `task contract adopt`。
 
 ### Feature-study workflow（参考代码 → 轻量实现）
 

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

@@ -54,10 +54,9 @@ Minimum governed path：
 
 ```bash
 loop-agent new-task <task-id> "Task Title" [--repo-root <target-repo>]
-# 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
+# PRD-first: import-prd → task source prepare --apply
+loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--repo-root <target-repo>]
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json [--repo-root <target-repo>]
 
 loop-agent dag run-task <task-id> \
   --profile auto \

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

@@ -67,7 +67,7 @@ loop-agent run-dag --dag <temp-dir>/hybrid-dag.json --init-only --canvas-path <t
 
 - **常规 validation**：`dag validate --dag <path>` 做 schema/topology/ranks。JSON 输出含 `governanceProfile`（确定性 `minimal|standard|reviewed|supervised` 推断，含 `process` / `delivery` / `codeChange` signal 与 `reasons`），及 model-matrix drift、governance lint（如 read-only artifact-boundary drift 或 DAG 内 `check-repo.sh` shell env drift）的 warnings。手写临时 DAG spec 执行前用 `dag validate --dag <path> --strict-models`；governance warning 应 fail fast 时加 `--strict-governance`。含 `executor: "cursor"` 的旧 DAG 会在 schema 校验失败；默认生成 DAG 使用 `pi` read-only / Pi write profile / shell。仅当有意在 `.harness/dag-runs/active/` 要 active run snapshot 时用 `run-dag --dry-run`。
 - **Governance profile 推断与 routing（code vs skill 分工）**：`./src/workflows/dag/governance-profile.ts` 从 DAG 结构与 write scope 做 **硬确定性推断**。JSON 输出 **报告** `process` / `delivery` / `codeChange` signal 与人类可读 `reasons`；`profile` tier（`minimal|standard|reviewed|supervised`）仅由该模块 code rule 选择（如多个 exclusive writer、repair node、review-gate topology、`loop-agent-runtime-paths`、`scripts-ci-harness-paths`、weak post-implementation shell verification、supervised topology）。baseline `forbiddenPaths`（`.harness/**`、`.harness/dag-runs/**`、`artifacts/**`）是默认 governance，**本身不是** process-risk signal。skill prompt 与本 reference **解释** tier 并摘要 profile 选择原因；不替代 code 推断。`dag run-task` 转发 embedded validate step 的同一 candidate `governanceProfile`。`dag run-task --profile auto` 先将 candidate profile 经 `harness.json.workflowPolicy.dag.profileRouting` 映射，再在 candidate delivery signal 含 `loop-agent-runtime-paths`、`scripts-ci-harness-paths` 或 `public-contract-paths` 时应用 M4 `supervised-quality-gate` promotion；`profileRouting.routingReasons` 记录确定性 reason。无 profile `dag run-task <task-id>` 仍为 standard-compatible；显式 `--profile minimal|standard|reviewed|supervised` 与自动 promotion 记录治理强度，已识别的前端业务 workflow 仍使用前端专用模板。高风险 task 应用 `--profile auto` 或显式 `--profile supervised`，而非显式 `--profile reviewed`。
-- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖 model 名；不选 provider。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`gpt-5.5`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
+- **Executor model routing**：DAG spec 选 `executor` 与 `complexity`，可通过 `executorModels.pi` 覆盖模型。值写成 `provider/model` 时显式选择 Pi provider（只分割第一个 `/`）；裸模型名继续走内置映射或默认 `wizard-local`。默认 routing：Pi LOW=`gpt-5.3-codex-spark`、MED=`gpt-5.5`、HIGH=`gpt-5.5`。`shell` 不用 model，忽略 `executorModels`。
 - **Active visibility**：真实 `run-dag` execution 在 run/node 转换时写 active `state.json`，归档前 core runner 暴露 isolated `DagRunObserver` hook 供 derived view。`.harness/dag-runs/completed/<run-id>/` / `paused/<run-id>/` 仍是 source of truth；observer 输出非 canonical。
 - **可选 Canvas**：传 `--canvas-path <abs-path>` 或 `--canvas <name>` 输出 derived `.canvas.tsx` live view。省略 flag 行为不变。`--init-only` + Canvas 无需 `CURSOR_API_KEY`。
 
@@ -232,7 +232,7 @@ review-heavy DAG 中长 shell stdout 可能掩盖 proof 时，用 **evidence-sum
 | --- | ------- | -------- |
 | 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 与 HIGH 当前都使用 `gpt-5.5`，切换 complexity 不会切换模型；provider 临时不可用时仅使用有记录、有限范围的 worker `--pi-model` smoke override，勿 mutate canonical model matrix |
+| 3 | Model routing | 用 node `complexity` + `executorModels`；需要固定 provider 时写 `provider/model`，裸模型名保持兼容；Pi MED 与 HIGH 默认都使用 `gpt-5.5`，切换 complexity 不会切换默认模型；provider 临时不可用时仅使用有记录、有限范围的 worker `--pi-model` smoke override，勿 mutate canonical model matrix |
 | 4 | Read-only output | read-only / Pi node 在 **node output** 返回发现；runner 归档于 `.harness/dag-runs/<run-id>/<node-id>/` |
 | 5 | Root `artifacts/**` | 非 read-only handoff target；持久记录去 `ai_workspace/loop-agent/reports/`、`ai_workspace/loop-agent/progress/`，或 narrow exclusive `writeSet` 写 legacy 摘要并记录迁移计划 |
 | 6 | DAG Cursor artifacts | 写入 `.harness/dag-runs/<state>/<run-id>/artifacts/<node-id>/`；不得写入 `./artifacts/**` |

package/skills/loop-agent/references/model-routing.md

@@ -17,6 +17,8 @@
 
 Agent DAG node 的模型来自 DAG JSON 中的 `executorModels`，并由 `dag validate --strict-models` 检查 canonical matrix 漂移。若变更模型配置，须同步更新 `harness.json`、相关测试、repo docs 与本 skill。
 
+`executorModels.pi` 的每档值支持两种形式：裸模型名继续走内置映射或默认 `wizard-local`；`provider/model` 限定引用则显式选择 Pi provider，只在第一个 `/` 处分割并保留模型 ID 的剩余部分。provider 定义与凭证仍归 Pi 的 `~/.pi/agent/models.json` 和环境配置所有。例如不同档可分别写 `wizard-local/glm-5.2` 与 `deepseek/deepseek-v4-flash`。
+
 `pi-prompt` 是独立 one-shot helper，不使用 `harness.json.models` 或 DAG `executorModels`。当前默认是 `wizard-local/glm-5.2`；高复杂度 one-shot 显式传 `--model gpt-5.5`。Agent DAG `pi` executor 的 canonical matrix 保持；读写 profile 共用同一矩阵：
 
 ```json

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

@@ -27,7 +27,7 @@ DAG run、promotion、closeout 和最终验证完成后：
 
 ```
 1. new-task <id>
-2. 有 PRD 文件：import-prd；再写 source/需求.md + source/执行约束.md
+2. 有 PRD 文件：import-prd → task source prepare --use-imported-prd --apply（默认不手写两 source）
 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

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

@@ -11,7 +11,7 @@ Task 目录布局：`task-workflow.md`。
 | 层 | 命令 / 路径 | 作用 | 主路径 DAG 是否强制 |
 | --- | --- | --- | --- |
 | Source 事实 | `import-prd` → `source/references/*` + `source-manifest.json` | 原始 PRD **不可变**归档 | 否（有 PRD 文件时**强烈推荐**） |
-| Source 契约 | 手写 `source/需求.md`、`执行约束.md` + `task.json` 路径边界 | DAG 生成与验收真源 | **是**（至少 `需求.md`） |
+| Source 契约 | `task source prepare --apply` 投影 `source/需求.md`、`执行约束.md` + managed paths | DAG 生成与验收真源 | **是**（至少 `需求.md`；默认不手写） |
 | Exec-plan | `plan create` / `plan complete` / `plan check` | 仓库级计划索引与交接 | 否（**非微小**推荐） |
 | DAG 运行时 | `dag run-task` → `dag validate` → `run-dag` | 可执行编排 | **是**（常规实现） |
 
@@ -47,7 +47,8 @@ Task 目录布局：`task-workflow.md`。
 ```bash
 loop-agent new-task <task-id> "简短标题"
 loop-agent import-prd <task-id> --file <path-to-original-prd.md> [--json]
-# 再写派生契约（映射 REQ/AC 或原文锚点）
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
+# 默认无 LLM 写 source；工程边界用 flags 显式给出
 #   .harness/tasks/<task-id>/source/需求.md
 #   .harness/tasks/<task-id>/source/执行约束.md
 # 同步 task.json.allowedPaths / forbiddenPaths

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

@@ -8,7 +8,9 @@
 
 ```bash
 loop-agent new-task <task-id> "Task Title"
-# 有原始 PRD：loop-agent import-prd <task-id> --file <prd>
+# 推荐：详细 PRD → import → prepare（无需手写两 source）
+loop-agent import-prd <task-id> --file <prd>
+loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --apply --json
 # 非微小：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
@@ -35,10 +37,10 @@ loop-agent run-dag --dag .harness/tasks/<task-id>/dag.json --cwd <repo-root>
   task.json
 ```
 
-- 用户原始 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。
+- 用户原始 PRD 用 `loop-agent import-prd <task-id> --file <prd>` 归档到 `source/references/`，禁止 AI 改写。**有文件就 import**。
+- 默认用 `task source prepare --use-imported-prd --apply` 投影 `需求.md` / `执行约束.md` 与 managed paths；**不要**默认让 LLM/主会话手写两 source。
+- 无独立 PRD 的微小任务可用 `task source prepare --from-text ... --apply` escape hatch（见 `source-and-plan-practice.md`）。
+- 若 `ai_workspace/loop-agent/` 已有权威 plan/spec/PRD，优先 `import-prd` 复制，再 prepare 派生薄契约；避免把长 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`、以及实现/验证证据。