@tea-agent/loop-agent 0.26.0 → 0.26.2

package/README.md

@@ -56,11 +56,16 @@ loop-agent init reconcile --repo-root .
 
 ```bash
 loop-agent new-task example-task "实现一个有明确验收标准的小功能"
-```
 
-完善 `.harness/tasks/example-task/source/需求.md` 和 `task.json` 中的结构化写入边界，然后执行：
+# 推荐：先有详细 PRD，再归档并确定性派生执行契约（无需手写两个 source 文件）
+# loop-agent import-prd example-task --file path/to/prd.md --json
+loop-agent task source prepare example-task \
+  --use-imported-prd \
+  --allowed-path "src/**" \
+  --forbidden-path ".harness/**" \
+  --verify "typecheck:npm run typecheck" \
+  --apply --json
 
-```bash
 loop-agent dag run-task example-task \
   --profile auto \
   --strict-models \

package/bin/loop-agent.js

@@ -1,21 +1,21 @@
-#!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const cliEntry = join(packageRoot, "dist", "cli.js");
-
-if (!existsSync(cliEntry)) {
-  console.error(
-    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
-  );
-  process.exit(1);
-}
-
-try {
-  await import(pathToFileURL(cliEntry).href);
-} catch (error) {
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const cliEntry = join(packageRoot, "dist", "cli.js");
+
+if (!existsSync(cliEntry)) {
+  console.error(
+    `loop-agent: cannot find built CLI at ${cliEntry}. Run \`npm run build\` before using the package bin.`,
+  );
+  process.exit(1);
+}
+
+try {
+  await import(pathToFileURL(cliEntry).href);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

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

@@ -12,6 +12,9 @@ import { validateDagUseCase } from "./validate-dag.js";
 import { runDagUseCase } from "./run-dag.js";
 import { getTaskPaths, loadTaskConfig } from "../../task/runtime.js";
 import { writeTaskConfig } from "../../infrastructure/harness/task-store.js";
+import { runFrontendPreflight } from "../../task/frontend-preflight.js";
+import { observeTaskContract } from "../../task/contract/observe.js";
+import { adoptTaskContract } from "../../task/contract/adopt.js";
 const PLACEHOLDER_WRITESET_MARKER = "REPLACE/WITH";
 function buildValidateInput(repoRoot, dagPath, parsed) {
     return {
@@ -243,6 +246,36 @@ export async function generateTaskDagUseCase(input) {
     // before any expensive DAG generation or execution. Empty/consistent
     // repos stay compatible so the default DAG flow is unblocked.
     await assertExecPlanIndexConsistent(repoRoot);
+    const preflightTaskConfig = await loadTaskConfig(repoRoot, parsed.taskId);
+    const frontendScope = await runFrontendPreflight({
+        repoRoot,
+        taskId: parsed.taskId,
+        taskConfig: preflightTaskConfig,
+    });
+    if (frontendScope) {
+        await writeTaskConfig(repoRoot, parsed.taskId, {
+            ...preflightTaskConfig,
+            allowedPaths: [
+                ...new Set([
+                    frontendScope.entrypoint,
+                    ...frontendScope.implementationPaths,
+                    ...frontendScope.testPaths,
+                ]),
+            ],
+        });
+        const state = await observeTaskContract({ repoRoot, taskId: parsed.taskId });
+        if (!state.ref || !state.observedCanonicalHash) {
+            throw new Error("frontend preflight could not reconcile the managed Task Contract");
+        }
+        await adoptTaskContract({
+            repoRoot,
+            taskId: parsed.taskId,
+            expectedRevision: state.ref.revision,
+            expectedObservedHash: state.observedCanonicalHash,
+            requestId: `frontend-preflight-${parsed.taskId}-${randomUUID()}`,
+            requestPayloadSha256: randomUUID().replaceAll("-", "").padEnd(64, "0"),
+        });
+    }
     const candidateResult = await initHybridDagFromTask(repoRoot, parsed.taskId, {
         outputPath: parsed.outputPath,
         template: "standard-dag",

package/dist/cli/command-definitions.js

@@ -12,6 +12,7 @@ import { runInstructions } from "../commands/instructions.js";
 import { runNewTask } from "../commands/new-task.js";
 import { runImportPrd } from "../commands/import-prd.js";
 import { runTaskContract } from "../commands/task-contract.js";
+import { runTaskSourcePrepare } from "../commands/task-source-prepare.js";
 import { runOperator } from "../commands/operator.js";
 import { runPlanList } from "../commands/plan-list.js";
 import { runPlanCheck, runPlanComplete, runPlanCreate, } from "../commands/plan.js";
@@ -139,7 +140,7 @@ const DAG_SUBCOMMANDS = [
     "final-verification",
     "decision",
 ];
-const TASK_SUBCOMMANDS = ["contract"];
+const TASK_SUBCOMMANDS = ["contract", "source"];
 const TASK_CONTRACT_SUBCOMMANDS = [
     "show",
     "validate",
@@ -149,6 +150,7 @@ const TASK_CONTRACT_SUBCOMMANDS = [
     "doctor",
     "recover",
 ];
+const TASK_SOURCE_SUBCOMMANDS = ["prepare"];
 const OPERATOR_SUBCOMMANDS = ["capabilities"];
 const WORKFLOW_SUBCOMMANDS = [
     "list",
@@ -271,19 +273,32 @@ export const COMMAND_DEFINITIONS = [
         name: "task",
         adapter: "required",
         tier: "primary",
-        intent: "Task Contract application boundary: show/validate/diff/apply/adopt/doctor/recover managed contract facts.",
-        usage: "task contract <show|validate|diff|apply|adopt|doctor|recover> ...",
+        intent: "Task Contract and source intake: contract show/validate/diff/apply/adopt/doctor/recover; source prepare (PRD-first Draft projection).",
+        usage: "task <contract|source> ...  (contract <show|validate|diff|apply|adopt|doctor|recover>; source prepare ...)",
         subcommands: [...TASK_SUBCOMMANDS],
         handler: async ({ repoRoot, subcommand, rest }) => {
-            if (subcommand !== "contract") {
-                throw new Error(formatSubcommandUsageError("task", TASK_SUBCOMMANDS));
+            if (subcommand === "contract") {
+                const [contractSub, ...contractRest] = rest;
+                if (!contractSub ||
+                    !TASK_CONTRACT_SUBCOMMANDS.includes(contractSub)) {
+                    throw new Error(`usage: task contract <${TASK_CONTRACT_SUBCOMMANDS.join("|")}> ...`);
+                }
+                await runTaskContract(repoRoot, [contractSub, ...contractRest]);
+                return;
             }
-            const [contractSub, ...contractRest] = rest;
-            if (!contractSub ||
-                !TASK_CONTRACT_SUBCOMMANDS.includes(contractSub)) {
-                throw new Error(`usage: task contract <${TASK_CONTRACT_SUBCOMMANDS.join("|")}> ...`);
+            if (subcommand === "source") {
+                const [sourceSub, ...sourceRest] = rest;
+                if (!sourceSub ||
+                    !TASK_SOURCE_SUBCOMMANDS.includes(sourceSub)) {
+                    throw new Error(`usage: task source <${TASK_SOURCE_SUBCOMMANDS.join("|")}> ...`);
+                }
+                if (sourceSub === "prepare") {
+                    await runTaskSourcePrepare(repoRoot, sourceRest);
+                    return;
+                }
+                throw new Error(`usage: task source <${TASK_SOURCE_SUBCOMMANDS.join("|")}> ...`);
             }
-            await runTaskContract(repoRoot, [contractSub, ...contractRest]);
+            throw new Error(formatSubcommandUsageError("task", TASK_SUBCOMMANDS));
         },
     },
     {

package/dist/cli/help.js

@@ -24,9 +24,10 @@ export function formatCommandTierSummary(manifest = CODE_AGENT_COMMAND_MANIFEST)
     return [
         "Recommended DAG path:",
         "  1. new-task <task-id> [title]",
-        "  2. import-prd <task-id> --file <original-prd>   # optional but recommended",
-        "  3. dag run-task <task-id> --profile auto --strict-models",
-        "  4. run-dag --dag <path> --cwd <repo-root>",
+        "  2. import-prd <task-id> --file <detailed-prd>   # PRD-first recommended",
+        "  3. task source prepare <task-id> --use-imported-prd --allowed-path <glob> --apply",
+        "  4. dag run-task <task-id> --profile auto --strict-models",
+        "  5. run-dag --dag <path> --cwd <repo-root>",
         "Operator recovery/closeout: dag status/report/doctor/closeout-draft",
         `Primary commands: ${primary}`,
         `Operator commands: ${operator}`,

package/dist/cli/program.js

@@ -41,6 +41,7 @@ import { runLoopBenchmark } from "../commands/loop-benchmark.js";
 import { runNewTask } from "../commands/new-task.js";
 import { runImportPrd } from "../commands/import-prd.js";
 import { runTaskContract } from "../commands/task-contract.js";
+import { runTaskSourcePrepare } from "../commands/task-source-prepare.js";
 import { runOperator } from "../commands/operator.js";
 import { runPiReuseBenchmark } from "../commands/pi-reuse-benchmark.js";
 import { parsePiPromptArgs, printPiPromptUsage, runPiPrompt, } from "../commands/pi-prompt.js";
@@ -137,25 +138,33 @@ async function runCommanderAction(ctx, command, subcommand, rest) {
             await runImportPrd(ctx.repoRoot, compactArgs([subcommand, ...rest]));
             return;
         case "task": {
-            if (subcommand !== "contract") {
-                throw new Error("usage: task <contract> ...");
+            if (subcommand === "contract") {
+                const [contractSub, ...contractRest] = rest;
+                const allowed = [
+                    "show",
+                    "validate",
+                    "diff",
+                    "apply",
+                    "adopt",
+                    "doctor",
+                    "recover",
+                ];
+                if (!contractSub ||
+                    !allowed.includes(contractSub)) {
+                    throw new Error(`usage: task contract <${allowed.join("|")}> ...`);
+                }
+                await runTaskContract(ctx.repoRoot, [contractSub, ...contractRest]);
+                return;
             }
-            const [contractSub, ...contractRest] = rest;
-            const allowed = [
-                "show",
-                "validate",
-                "diff",
-                "apply",
-                "adopt",
-                "doctor",
-                "recover",
-            ];
-            if (!contractSub ||
-                !allowed.includes(contractSub)) {
-                throw new Error(`usage: task contract <${allowed.join("|")}> ...`);
+            if (subcommand === "source") {
+                const [sourceSub, ...sourceRest] = rest;
+                if (sourceSub !== "prepare") {
+                    throw new Error("usage: task source <prepare> ...");
+                }
+                await runTaskSourcePrepare(ctx.repoRoot, sourceRest);
+                return;
             }
-            await runTaskContract(ctx.repoRoot, [contractSub, ...contractRest]);
-            return;
+            throw new Error("usage: task <contract|source> ...");
         }
         case "operator":
             await runOperator(ctx.repoRoot, compactArgs([subcommand, ...rest]));
@@ -437,6 +446,14 @@ function addStandaloneSubcommands(parent, subcommands, handler) {
         });
     }
 }
+function configureTaskSourcePrepare(command) {
+    command
+        .description("Prepare deterministic task source files from a PRD or draft")
+        .usage("<task-id> [options]")
+        .option("--from-draft <path>", "TaskContractDraftV1 JSON path")
+        .option("--use-imported-prd", "use the task's imported PRD reference")
+        .option("--force-overwrite-source", "replace existing managed source files");
+}
 function configureDagValidate(command) {
     command
         .description("Validate an Agent DAG spec")
@@ -662,6 +679,15 @@ export function buildLoopAgentProgram(options) {
         }
         if (entry.subcommands)
             addRawSubcommands(command, entry.subcommands, options.defaultRepoRoot);
+        if (entry.name === "task") {
+            const source = command.commands.find((child) => child.name() === "source");
+            if (source) {
+                const prepare = createRawArgsCommand("prepare", "Prepare deterministic task source files", options.defaultRepoRoot);
+                configureTaskSourcePrepare(prepare);
+                replaceActionWithOptionAwareDispatch(prepare, options.defaultRepoRoot);
+                source.addCommand(prepare);
+            }
+        }
         program.addCommand(command);
     }
     return program;

package/dist/commands/cursor-prompt.js

@@ -141,7 +141,7 @@ async function runCursorPromptBatch(task, cwd, model, timeoutMs) {
 }
 async function runCursorPromptStreaming(task, cwd, model, timeoutMs) {
     const startedAt = Date.now();
-    process.stderr.write(`[cursor-prompt] streaming (model=${model}, cwd=${cwd})
+    process.stderr.write(`[cursor-prompt] streaming (model=${model}, cwd=${cwd})
 `);
     const runDir = (await computeRunDir(cwd, task)) ?? undefined;
     const result = await executeCursorPromptStream({
@@ -164,15 +164,15 @@ async function runCursorPromptStreaming(task, cwd, model, timeoutMs) {
     });
     const elapsed = ((Date.now() - startedAt) / 1000).toFixed(1);
     if (result.ok) {
-        process.stderr.write(`
-[cursor-prompt] done in ${elapsed}s, status=${result.status}
+        process.stderr.write(`
+[cursor-prompt] done in ${elapsed}s, status=${result.status}
 `);
     }
     else {
         const stderr = result.stderr || "(no output)";
-        process.stderr.write(`
-[cursor-prompt] FAILED in ${elapsed}s (${result.failureCategory}):
-${stderr}
+        process.stderr.write(`
+[cursor-prompt] FAILED in ${elapsed}s (${result.failureCategory}):
+${stderr}
 `);
         process.exit(1);
     }

package/dist/commands/import-prd.js

@@ -61,7 +61,11 @@ export async function runImportPrd(repoRoot, args) {
                 .split(path.sep)
                 .join("/"),
             referenceDocs: result.referenceDocs,
-            message: "Imported PRD as an immutable source reference. Derive source/需求.md from it; do not rewrite the reference copy.",
+            message: "Imported PRD as an immutable source reference. Next: task source prepare --use-imported-prd (plus engineering --allowed-path/--verify) then --apply. Do not rewrite source/references/*.",
+            next: [
+                `loop-agent task source prepare ${result.taskId} --use-imported-prd --allowed-path <glob> --verify "typecheck:npm run typecheck" --json`,
+                `loop-agent task source prepare ${result.taskId} --use-imported-prd --allowed-path <glob> --apply --json`,
+            ],
         }, null, 2));
         return;
     }
@@ -71,6 +75,7 @@ export async function runImportPrd(repoRoot, args) {
         `  materialized: ${result.materializedRelativePath}`,
         `  sha256: ${result.sha256}`,
         `  manifest: ${path.relative(repoRoot, result.manifestPath).split(path.sep).join("/")}`,
-        "Next: write source/需求.md as a derived execution contract with REQ/AC ids that map back to the original PRD. Do not edit source/references/*.",
+        "Next: loop-agent task source prepare <task-id> --use-imported-prd --allowed-path <glob> [--verify label:cmd] --apply --json",
+        "Do not hand-write source/需求.md or source/执行约束.md on the default path; do not edit source/references/*.",
     ].join("\n"));
 }

package/dist/commands/init.js

@@ -1811,14 +1811,15 @@ function buildManagedReadmeBlock(input) {
         "",
         "```bash",
         'loop-agent new-task <task-id> "任务标题"',
-        "# write .harness/tasks/<task-id>/source/需求.md",
-        "# write .harness/tasks/<task-id>/source/执行约束.md",
+        "# 推荐：详细 PRD → import-prd → task source prepare --apply（无需手写两 source）",
+        "# loop-agent import-prd <task-id> --file <prd.md>",
+        'loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --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 .",
         "```",
         "",
-        `详细工作流见 \`${input.governanceRoot}/feature-workflow.md\`；验证矩阵见 \`${input.governanceRoot}/verification-matrix.md\`。任务 source 是必需项：\`source/需求.md\` 写目标、范围、非目标、验收标准和相关链接，\`source/执行约束.md\` 写允许路径、禁止路径、受保护变更、不变量、预期验证和失败条件。`,
+        `详细工作流见 \`${input.governanceRoot}/feature-workflow.md\`；验证矩阵见 \`${input.governanceRoot}/verification-matrix.md\`。任务 source 仍必需（\`source/需求.md\` / \`source/执行约束.md\`），默认由 \`task source prepare --apply\` 从详细 PRD 确定性派生，而不是主会话手写或 LLM 写 md。`,
         "",
         "执行后使用 `loop-agent dag report --run-id <run-id> --markdown` 和 `loop-agent dag doctor --run-id <run-id> --markdown` 读取事实与诊断失败。失败 run 不做成功式 closeout；使用 `loop-agent dag closeout-draft --run-id <run-id>` 生成 failure handoff。",
         "",
@@ -2043,8 +2044,9 @@ function buildTargetFeatureWorkflow(input) {
         "",
         "```bash",
         'loop-agent new-task <task-id> "Task title"',
-        "# write .harness/tasks/<task-id>/source/需求.md",
-        "# write .harness/tasks/<task-id>/source/执行约束.md",
+        "# Preferred: detailed PRD → import-prd → task source prepare --apply",
+        "# loop-agent import-prd <task-id> --file <prd.md>",
+        'loop-agent task source prepare <task-id> --use-imported-prd --allowed-path "<glob>" --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 .",

package/dist/commands/loop-benchmark.js

@@ -37,17 +37,17 @@ export function parseLoopBenchmarkArgs(args) {
     return { json, markdown, outputPath };
 }
 export function printLoopBenchmarkUsage() {
-    console.log(`usage: loop-benchmark [options]
-
-Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
-
-Options:
-  --json              Emit JSON (default when no format flag is set)
-  --markdown          Emit Markdown report
-  --output <path>     Write Markdown report to a repo-relative or absolute path
-  -h, --help          Show this help
-
-Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
+    console.log(`usage: loop-benchmark [options]
+
+Deterministic loop-agent loop benchmark baseline (no live Pi/Cursor calls).
+
+Options:
+  --json              Emit JSON (default when no format flag is set)
+  --markdown          Emit Markdown report
+  --output <path>     Write Markdown report to a repo-relative or absolute path
+  -h, --help          Show this help
+
+Control groups: single-repair, 3-pass-convergence, 3-pass-convergence+quota.
 Recommendation never changes convergence.enabled default.`);
 }
 export async function runLoopBenchmark(repoRoot, rawArgs) {

package/dist/commands/pi-reuse-benchmark.js

@@ -106,22 +106,22 @@ export function parsePiReuseBenchmarkArgs(args) {
     };
 }
 export function printPiReuseBenchmarkUsage() {
-    console.log(`usage: pi-reuse-benchmark [options]
-
-Deterministic Pi runtime reuse benchmark/decision summary (no live Pi calls).
-
-Options:
-  --report <path>         Benchmark report markdown (approval status)
-  --approval <path>       Explicit approval JSON artifact
-  --off-executor <path>   Baseline executor.jsonl (reuse off)
-  --on-executor <path>    Treatment executor.jsonl (reuse on)
-  --off-task <task-id>    Resolve baseline from .harness/tasks/<id>/logs/executor.jsonl
-  --on-task <task-id>     Resolve treatment from .harness/tasks/<id>/logs/executor.jsonl
-  --json                  Emit JSON (default when no format flag is set)
-  --markdown              Emit Markdown summary
-  -h, --help              Show this help
-
-Recommendations: defer | maintain-opt-in | eligible-for-human-review
+    console.log(`usage: pi-reuse-benchmark [options]
+
+Deterministic Pi runtime reuse benchmark/decision summary (no live Pi calls).
+
+Options:
+  --report <path>         Benchmark report markdown (approval status)
+  --approval <path>       Explicit approval JSON artifact
+  --off-executor <path>   Baseline executor.jsonl (reuse off)
+  --on-executor <path>    Treatment executor.jsonl (reuse on)
+  --off-task <task-id>    Resolve baseline from .harness/tasks/<id>/logs/executor.jsonl
+  --on-task <task-id>     Resolve treatment from .harness/tasks/<id>/logs/executor.jsonl
+  --json                  Emit JSON (default when no format flag is set)
+  --markdown              Emit Markdown summary
+  -h, --help              Show this help
+
+Recommendations: defer | maintain-opt-in | eligible-for-human-review
 Never changes CODE_AGENT_PI_REUSE_RUNTIME default (off).`);
 }
 function resolveRepoRelative(repoRoot, filePath) {