@tea-agent/loop-agent 0.4.0 → 0.6.0

package/dist/commands/init.js

@@ -6,6 +6,8 @@ import { copyDir } from "../shared/copy-dir.js";
 import { loadHarnessManifest } from "../governance/harness.js";
 const MANAGED_BLOCK_START = "<!-- LOOP_AGENT_INIT_START -->";
 const MANAGED_BLOCK_END = "<!-- LOOP_AGENT_INIT_END -->";
+const GITIGNORE_BLOCK_START = "# LOOP_AGENT_INIT_START";
+const GITIGNORE_BLOCK_END = "# LOOP_AGENT_INIT_END";
 const INIT_SURFACE_STATE_PATH = ".harness/init-surface.json";
 const CORE_DOC_FILES = [
     "README.md",
@@ -720,17 +722,88 @@ function mergeManagedBlock(existing, block) {
     }
     return `${existing.trimEnd()}\n\n${block}\n`;
 }
+function mergeGitignoreManagedBlock(existing, block) {
+    const start = existing.indexOf(GITIGNORE_BLOCK_START);
+    const end = existing.indexOf(GITIGNORE_BLOCK_END);
+    if (start >= 0 && end > start) {
+        return `${existing.slice(0, start).trimEnd()}\n\n${block}\n${existing.slice(end + GITIGNORE_BLOCK_END.length).trimStart()}`.trimEnd() + "\n";
+    }
+    if (!existing.trim())
+        return `${block}\n`;
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+/** Shared ignore rules for loop-agent runtime facts; keep prompts/ and directory structure shareable. */
+export function buildManagedGitignoreBlock() {
+    return [
+        GITIGNORE_BLOCK_START,
+        "# loop-agent runtime: ignore personal/session facts; keep prompts and directory placeholders shareable",
+        "",
+        "# tasks (source + runtime state per developer/session)",
+        ".harness/tasks/*",
+        "!.harness/tasks/.gitkeep",
+        "",
+        "# DAG runs",
+        ".harness/dag-runs/active/*",
+        "!.harness/dag-runs/active/.gitkeep",
+        ".harness/dag-runs/completed/*",
+        "!.harness/dag-runs/completed/.gitkeep",
+        ".harness/dag-runs/paused/*",
+        "!.harness/dag-runs/paused/.gitkeep",
+        "",
+        "# one-shot executor runs",
+        ".harness/runs/*",
+        "!.harness/runs/.gitkeep",
+        "",
+        "# session / cache / logs / recomputable surface state",
+        ".harness/live/",
+        ".harness/cache/",
+        ".harness/*.log",
+        ".harness/init-surface.json",
+        "",
+        "# worker task pool",
+        ".task-pool/",
+        "",
+        "# multi-worktree parallel mode",
+        ".worktrees/",
+        GITIGNORE_BLOCK_END,
+    ].join("\n");
+}
+function extractGitignoreManagedBlock(content) {
+    const start = content.indexOf(GITIGNORE_BLOCK_START);
+    const end = content.indexOf(GITIGNORE_BLOCK_END);
+    if (start < 0 || end <= start)
+        return undefined;
+    return content.slice(start, end + GITIGNORE_BLOCK_END.length);
+}
 function buildHarness(input) {
-    const modelOverride = input.provider || input.model
-        ? {
-            analyze: { provider: input.provider, model: input.model },
-            plan: { provider: input.provider, model: input.model },
-            implement: { provider: input.provider, model: input.model },
-            verify: { provider: input.provider, model: input.model },
-            retrospective: { provider: input.provider, model: input.model },
-        }
-        : undefined;
-    return {
+    const templateExecutors = isRecord(input.template.executors)
+        ? { ...input.template.executors }
+        : {};
+    const existingExecutors = isRecord(input.existing.executors)
+        ? input.existing.executors
+        : {};
+    // Cursor executor is opt-in for package developers; do not project it to target apps.
+    // Keep it only when the target already configured executors.cursor.
+    if (!isRecord(existingExecutors.cursor)) {
+        delete templateExecutors.cursor;
+    }
+    const mergedExecutors = mergeRecord(templateExecutors, existingExecutors);
+    // requiresApiKey is Cursor-facing only; never project it on pi.
+    if (isRecord(mergedExecutors.pi) && "requiresApiKey" in mergedExecutors.pi) {
+        const pi = { ...mergedExecutors.pi };
+        delete pi.requiresApiKey;
+        mergedExecutors.pi = pi;
+    }
+    // Prefer DAG-facing executors.*.defaultModel over legacy top-level models.*.
+    // --provider/--model still apply as a convenience override for pi defaultModel.
+    if (input.provider || input.model) {
+        const piExisting = isRecord(mergedExecutors.pi) ? mergedExecutors.pi : {};
+        mergedExecutors.pi = {
+            ...piExisting,
+            ...(input.model ? { defaultModel: input.model } : {}),
+        };
+    }
+    const harness = {
         ...input.existing,
         version: 1,
         project: input.projectName,
@@ -753,6 +826,7 @@ function buildHarness(input) {
             progressDir: `${input.governanceRoot}/progress`,
             reportsDir: `${input.governanceRoot}/reports`,
             decisionsDir: `${input.governanceRoot}/decisions`,
+            taskPoolDir: ".task-pool",
         }),
         scripts: mergeRecord(input.existing.scripts, {
             checkEngineeringStructure: "scripts/check-engineering-structure.sh",
@@ -771,11 +845,30 @@ function buildHarness(input) {
             standardVerify: "bash scripts/ci-governance.sh",
             fullVerify: "bash scripts/ci.sh",
         }),
-        models: modelOverride ?? input.existing.models ?? input.template.models ?? {},
-        modelProfiles: input.existing.modelProfiles ?? input.template.modelProfiles ?? {},
-        modelRouting: input.existing.modelRouting ?? input.template.modelRouting ?? {},
-        executors: mergeRecord(input.template.executors, input.existing.executors),
+        executors: mergedExecutors,
     };
+    // Do not project legacy step-routing models / modelProfiles / modelRouting into
+    // new or refreshed harness.json. Keep them only when the target already has them
+    // so old files remain loadable until the user migrates.
+    if (isRecord(input.existing.models) && Object.keys(input.existing.models).length > 0) {
+        harness.models = input.existing.models;
+    }
+    else {
+        delete harness.models;
+    }
+    if (isRecord(input.existing.modelProfiles) && Object.keys(input.existing.modelProfiles).length > 0) {
+        harness.modelProfiles = input.existing.modelProfiles;
+    }
+    else {
+        delete harness.modelProfiles;
+    }
+    if (isRecord(input.existing.modelRouting) && Object.keys(input.existing.modelRouting).length > 0) {
+        harness.modelRouting = input.existing.modelRouting;
+    }
+    else {
+        delete harness.modelRouting;
+    }
+    return harness;
 }
 async function writeTextIfMissing(input) {
     const target = path.join(input.repoRoot, input.relativePath);
@@ -899,8 +992,11 @@ function inferInitSurfaceMode(relativePath) {
         relativePath.endsWith("/")) {
         return "directory";
     }
-    if (relativePath === "README.md" || relativePath === "AGENTS.md")
+    if (relativePath === "README.md" ||
+        relativePath === "AGENTS.md" ||
+        relativePath === ".gitignore") {
         return "managed-block";
+    }
     if (relativePath === "harness.json" ||
         relativePath.startsWith("scripts/") ||
         relativePath.startsWith(".harness/prompts/") ||
@@ -934,6 +1030,9 @@ async function buildDesiredSurfaceContent(input) {
             }),
         };
     }
+    if (manifestPath === ".gitignore") {
+        return { content: buildManagedGitignoreBlock() };
+    }
     if (manifestPath === "harness.json") {
         const template = await readJsonIfExists(path.join(input.assetRoot, "harness.json"));
         return {
@@ -953,6 +1052,16 @@ async function buildDesiredSurfaceContent(input) {
         const name = path.basename(manifestPath);
         return { content: COMPAT_PROMPTS[name] };
     }
+    // `.agents/skills/...` is a target-only mirror of the bundled `skills/...`
+    // directory; the package ships `skills/`, never `.agents/skills/`.
+    if (manifestPath.startsWith(".agents/skills/")) {
+        const sourceManifestPath = manifestPath.slice(".agents/".length);
+        const mirrorSourcePath = path.join(input.assetRoot, sourceManifestPath);
+        if (await exists(mirrorSourcePath)) {
+            return { content: await readFile(mirrorSourcePath, "utf-8"), sourcePath: mirrorSourcePath };
+        }
+        return {};
+    }
     if (manifestPath.startsWith("docs/")) {
         const doc = manifestPath.slice("docs/".length);
         const generated = buildGeneratedCoreDoc({
@@ -1031,7 +1140,10 @@ async function buildCurrentSurfaceState(input) {
         const current = await readFile(targetPath);
         const currentSha256 = sha256Buffer(current);
         if (entry.mode === "managed-block") {
-            const currentBlock = extractManagedBlock(current.toString("utf-8"));
+            const text = current.toString("utf-8");
+            const currentBlock = entry.path === ".gitignore" || targetRelativePath === ".gitignore"
+                ? extractGitignoreManagedBlock(text)
+                : extractManagedBlock(text);
             files[targetRelativePath] = {
                 ...base,
                 currentSha256,
@@ -1194,6 +1306,8 @@ function buildTargetDocsReadme(input) {
         "- `decisions/README.md` - 架构决策 / architecture decisions",
         "- `templates/` - 可复用的计划、报告与 DAG 模板 / reusable planning, reporting, and DAG templates",
         "- `templates/production-readiness-checklist.md` - 低/中风险单仓库 DAG 任务的 production readiness 检查清单 / production readiness checklist for low/medium-risk single-repo DAG work",
+        "- `templates/worker-dogfood-setup.md` - 发布控制器下的真实 Worker sample setup / real Worker sample setup with a published controller",
+        "- `templates/worker-dogfood-evidence.md` - Worker sample、Observe、morning report 与 QA coverage evidence / Worker evidence template",
         "",
         "## 验证 / Verification",
         "",
@@ -1228,6 +1342,9 @@ function buildTargetRuntimeBoundaries(input) {
         "Executors / Integrations layer",
         "  └─ 外部工具、SDK、数据库、消息队列、浏览器、模型或 shell 适配",
         "",
+        "Worker adapter layer (optional)",
+        "  └─ 产品线 TaskSpec / Task Pool / local Observe 适配；通过已发布 loop-agent CLI 执行，不在进程内耦合 target command 或 application 层",
+        "",
         "Infrastructure / Store layer",
         "  └─ 文件系统、数据库、缓存、运行事实、原子写入和生命周期副作用",
         "",
@@ -1241,6 +1358,7 @@ function buildTargetRuntimeBoundaries(input) {
         "- Application / Use-case layer 可以依赖 Domain / Workflow、Infrastructure 和 Integrations。",
         "- Domain / Workflow layer 不应依赖 Entry layer 的格式化、argv、HTTP/UI 细节。",
         "- Executors / Integrations 不应依赖 Entry layer 的输出格式。",
+        "- Worker adapter 应把 `.task-pool/` 作为独立运行事实区；它通过 CLI/subprocess contract 调用 loop-agent，不能复制或直接耦合 target command/application 实现。",
         "- Infrastructure / Store 应集中副作用，不把 raw path mutation 或持久化细节扩散给上层。",
         "",
         "## 目标项目适配",
@@ -1382,6 +1500,7 @@ function buildTargetLoopAgentHarness(input) {
         "- `.harness/tasks/` stores task state and source materials.",
         "- `.harness/dag-runs/` stores DAG run facts.",
         "- `.harness/runs/` stores one-shot executor facts.",
+        "- `.task-pool/` stores optional agent-worker Task Pool state, batch artifacts, failure handoffs, and local Observe events; it is runtime state and normally ignored by Git.",
         "- `docs/` stores durable governance, plans, reports, progress, and decisions.",
         "- `skills/` stores repo-local skill instructions; the CLI can fall back to bundled skills when needed.",
         "",
@@ -1395,6 +1514,8 @@ function buildTargetLoopAgentHarness(input) {
         "",
         "Use `docs/templates/production-readiness-checklist.md` when claiming Production Readiness v0.1 for low/medium-risk single-repo DAG work.",
         "",
+        "For real product-line Worker samples, use `docs/templates/worker-dogfood-setup.md` and `docs/templates/worker-dogfood-evidence.md`. Explicit failed-task retries must preserve prior evidence and use a new worker run id.",
+        "",
         "## Script Matrix",
         "",
         "`scripts/check-repo.sh` verifies loop-agent governance. `scripts/ci-tests.sh` handles target project verification through conservative language/toolchain detection and should be adapted after reading the project.",
@@ -1462,7 +1583,8 @@ export function buildInitInstructions(input) {
         "- After deterministic initialization, inspect README/config/build files (for example package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, Gradle files, Makefile, .sln/.csproj, or project-specific scripts) and adapt `scripts/ci-tests.sh` plus the verification matrix to the real project.",
         "- Enrich the root `README.md`: keep the deterministic project title and the loop-agent managed block intact, and fill the human-authored sections (项目概览, 技术栈与目录结构, 开发与验证) from the target project's actual files. The root README must serve both as a human-first project entry and as an agent work entry; replace the initialization-model supplement comments when the project files provide the information.",
         "- Populate `docs/verification-matrix.md` with the target project's actual quick, standard, and full verification commands derived from its real language and toolchain, keeping the governance rows intact.",
-        "- Copy repo-local skills by default so the target repo has auditable skill instructions.",
+        "- Copy repo-local skills by default so the target repo has auditable skill instructions; full profile also mirrors skills into `.agents/skills/` for external agents.",
+        "- Merge a loop-agent managed block into `.gitignore` that ignores harness runtime facts (tasks, dag-runs, runs, live, cache, init-surface.json, .task-pool) while keeping prompts and directory placeholders shareable.",
         "- Do not copy examples by default; examples stay bundled in the tool and are available through `loop-agent examples`.",
         "- Add or update a loop-agent managed block in AGENTS.md.",
         "- The generated AGENTS.md must include documentation convergence and structured DAG write-boundary rules so target projects keep the same working discipline as this repository.",
@@ -1556,6 +1678,18 @@ export async function initializeLoopAgentProject(options) {
         written,
         skipped,
     });
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const existingGitignore = (await exists(gitignorePath))
+        ? await readFile(gitignorePath, "utf-8")
+        : "";
+    await writeText({
+        repoRoot,
+        relativePath: ".gitignore",
+        content: mergeGitignoreManagedBlock(existingGitignore, buildManagedGitignoreBlock()),
+        merge: true,
+        written,
+        skipped,
+    });
     for (const doc of CORE_DOC_FILES) {
         const generated = buildGeneratedCoreDoc({ doc, projectName, governanceRoot });
         if (generated) {
@@ -1604,9 +1738,21 @@ export async function initializeLoopAgentProject(options) {
             targetRelativePath: "skills",
             written,
         });
+        // Mirror bundled skills into the agent-compatible `.agents/skills/` path so
+        // external agents (e.g. OpenCode) that auto-discover `.agents/skills/<name>/SKILL.md`
+        // share the same skill content as loop-agent's primary `skills/` path.
+        // The package still ships only `skills/`; `.agents/skills` is a target projection.
+        await copyDirMerge({
+            assetRoot,
+            repoRoot,
+            sourceRelativePath: "skills",
+            targetRelativePath: ".agents/skills",
+            written,
+        });
     }
     else {
         skipped.push("skills/");
+        skipped.push(".agents/skills/");
     }
     skipped.push("examples/");
     for (const [relativePath, content] of Object.entries(buildInitScriptFiles(governanceRoot))) {
@@ -1736,6 +1882,27 @@ export async function checkInitUpdate(input) {
             }
         }
     }
+    // Safe harness hygiene: strip obsolete pi.requiresApiKey without full harness rewrite.
+    // Cursor requiresApiKey is intentionally kept when present.
+    const harnessPath = path.join(repoRoot, "harness.json");
+    if (await exists(harnessPath)) {
+        try {
+            const harness = JSON.parse(await readFile(harnessPath, "utf-8"));
+            if (isRecord(harness) &&
+                isRecord(harness.executors) &&
+                isRecord(harness.executors.pi) &&
+                Object.prototype.hasOwnProperty.call(harness.executors.pi, "requiresApiKey")) {
+                deterministicActions.push({
+                    type: "strip-pi-requires-api-key",
+                    path: "harness.json",
+                    reason: "executors.pi.requiresApiKey is unused; strip it while keeping user model config and cursor.requiresApiKey",
+                });
+            }
+        }
+        catch {
+            // leave malformed harness for model merge / doctor
+        }
+    }
     const partial = {
         repoRoot,
         controllerVersion: currentState.controllerVersion,
@@ -1759,6 +1926,29 @@ export async function checkInitUpdate(input) {
     };
 }
 async function applySafeAction(input) {
+    if (input.action.type === "strip-pi-requires-api-key") {
+        const target = path.join(input.repoRoot, "harness.json");
+        if (!(await exists(target)))
+            return false;
+        const harness = JSON.parse(await readFile(target, "utf-8"));
+        if (!isRecord(harness) || !isRecord(harness.executors) || !isRecord(harness.executors.pi)) {
+            return false;
+        }
+        if (!Object.prototype.hasOwnProperty.call(harness.executors.pi, "requiresApiKey")) {
+            return false;
+        }
+        const nextPi = { ...harness.executors.pi };
+        delete nextPi.requiresApiKey;
+        const next = {
+            ...harness,
+            executors: {
+                ...harness.executors,
+                pi: nextPi,
+            },
+        };
+        await writeFile(target, `${JSON.stringify(next, null, 2)}\n`, "utf-8");
+        return true;
+    }
     const assetRoot = await findPackageRoot();
     const entry = {
         path: input.action.path,
@@ -1789,11 +1979,13 @@ async function applySafeAction(input) {
     await mkdir(path.dirname(target), { recursive: true });
     if (input.action.type === "refresh-managed-block") {
         const existing = (await exists(target)) ? await readFile(target, "utf-8") : "";
-        const next = input.action.path === "README.md" && existing.trim().length === 0
-            ? buildTargetReadme({ projectName: input.projectName, governanceRoot: input.governanceRoot })
-            : input.action.path === "AGENTS.md" && existing.trim().length === 0
-                ? `# AGENTS.md\n\n${desired.content}\n`
-                : mergeManagedBlock(existing, desired.content);
+        const next = input.action.path === ".gitignore"
+            ? mergeGitignoreManagedBlock(existing, desired.content)
+            : input.action.path === "README.md" && existing.trim().length === 0
+                ? buildTargetReadme({ projectName: input.projectName, governanceRoot: input.governanceRoot })
+                : input.action.path === "AGENTS.md" && existing.trim().length === 0
+                    ? `# AGENTS.md\n\n${desired.content}\n`
+                    : mergeManagedBlock(existing, desired.content);
         await writeFile(target, next, "utf-8");
         return true;
     }
@@ -1826,16 +2018,18 @@ export async function applyInitUpdate(input) {
                 skipped.push(action);
                 continue;
             }
-            const currentState = await buildCurrentSurfaceState({
-                repoRoot,
-                projectName,
-                governanceRoot,
-                stateKind: "inferred-baseline",
-            });
-            const relationship = currentState.files[action.path]?.relationship;
-            if (relationship === "local-existing-unknown") {
-                skipped.push(action);
-                continue;
+            if (action.type !== "strip-pi-requires-api-key") {
+                const currentState = await buildCurrentSurfaceState({
+                    repoRoot,
+                    projectName,
+                    governanceRoot,
+                    stateKind: "inferred-baseline",
+                });
+                const relationship = currentState.files[action.path]?.relationship;
+                if (relationship === "local-existing-unknown") {
+                    skipped.push(action);
+                    continue;
+                }
             }
             if (await applySafeAction({ repoRoot, projectName, governanceRoot, action }))
                 applied.push(action);
@@ -1909,6 +2103,10 @@ export async function runInitDoctor(input) {
     const readme = path.join(repoRoot, "README.md");
     add("README loop-agent block", (await exists(readme)) && (await readFile(readme, "utf-8")).includes(MANAGED_BLOCK_START), "managed block present");
     add("repo-local skills", await exists(path.join(repoRoot, "skills", "loop-agent", "SKILL.md")), "skills/loop-agent/SKILL.md");
+    add("agent-compatible skills mirror", await exists(path.join(repoRoot, ".agents", "skills", "loop-agent", "SKILL.md")), ".agents/skills/loop-agent/SKILL.md");
+    const gitignorePath = path.join(repoRoot, ".gitignore");
+    const gitignoreContent = (await exists(gitignorePath)) ? await readFile(gitignorePath, "utf-8") : "";
+    add("gitignore loop-agent block", gitignoreContent.includes(GITIGNORE_BLOCK_START) && gitignoreContent.includes(".harness/tasks/*"), ".gitignore managed runtime ignores");
     const requiredScripts = Object.keys(INIT_SCRIPT_FILES);
     const missingScripts = [];
     for (const script of requiredScripts) {

package/dist/commands/instructions.js

@@ -1,42 +1,42 @@
-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';
+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',
-    'dag-draft',
-    'task-artifacts',
-    'promotion',
-    'closeout',
+    "source",
+    "dag-draft",
+    "task-artifacts",
+    "promotion",
+    "closeout",
 ]);
 export function parseInstructionsArgs(args) {
     const [stageRaw, ...rest] = args;
     if (!stageRaw || !STAGES.has(stageRaw)) {
-        throw new Error('usage: instructions <source|dag-draft|task-artifacts|promotion|closeout> --task <task-id> [--json]');
+        throw new Error("usage: instructions <source|dag-draft|task-artifacts|promotion|closeout> --task <task-id> [--json]");
     }
     let taskId;
     let json = false;
     for (let i = 0; i < rest.length; i += 1) {
         const arg = rest[i];
-        if (arg === '--task') {
+        if (arg === "--task") {
             taskId = rest[++i];
             if (!taskId)
-                throw new Error('instructions --task requires a task id');
+                throw new Error("instructions --task requires a task id");
             continue;
         }
-        if (arg.startsWith('--task=')) {
-            taskId = arg.slice('--task='.length);
+        if (arg.startsWith("--task=")) {
+            taskId = arg.slice("--task=".length);
             continue;
         }
-        if (arg === '--json') {
+        if (arg === "--json") {
             json = true;
             continue;
         }
         throw new Error(`unknown instructions flag: ${arg}`);
     }
     if (!taskId)
-        throw new Error('instructions requires --task <task-id>');
+        throw new Error("instructions requires --task <task-id>");
     return { stage: stageRaw, taskId, json };
 }
 export async function runInstructions(repoRoot, args) {
@@ -54,13 +54,13 @@ export async function buildInstructions(repoRoot, stage, taskId) {
     const taskConfig = await loadTaskConfig(repoRoot, taskId);
     const allowedEditRoots = taskConfig.allowedPaths.length > 0
         ? taskConfig.allowedPaths
-        : [path.relative(repoRoot, taskDir).replace(/\\/g, '/')];
+        : [path.relative(repoRoot, taskDir).replace(/\\/g, "/")];
     const writePolicy = {
-        mode: stage === 'promotion'
-            ? 'run-evidence-read-only'
-            : stage === 'closeout'
-                ? 'docs-progress'
-                : 'task-owned',
+        mode: stage === "promotion"
+            ? "run-evidence-read-only"
+            : stage === "closeout"
+                ? "docs-progress"
+                : "task-owned",
         allowedEditRoots,
         forbiddenPaths: taskConfig.forbiddenPaths,
     };
@@ -70,74 +70,106 @@ export async function buildInstructions(repoRoot, stage, taskId) {
         existingFiles: await listExistingFiles(taskDir),
         writePolicy,
     };
-    if (stage === 'source') {
+    if (stage === "source") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
             outputPath: paths.sourceDir,
             dependencies: [paths.taskConfigPath],
-            template: { requiredHeadings: ['# 需求', '# 执行约束'] },
+            template: {
+                requiredHeadings: [
+                    "# 需求",
+                    "# 执行约束",
+                    "## 目标",
+                    "## 验收标准",
+                    "## 非目标",
+                ],
+            },
             completionCriteria: [
-                'source/需求.md exists with concrete requirements',
-                'source/执行约束.md exists when path or behavioral constraints matter',
+                "source/references/ holds the immutable original PRD (via import-prd or materialize); do not let AI rewrite it",
+                "source/需求.md is a derived execution contract with objective, scope, non-goals, and acceptance criteria mapped back to the original PRD",
+                "source/需求.md uses stable REQ/AC ids or explicit source anchors when the original PRD is long",
+                "source/执行约束.md exists when path or behavioral constraints matter",
+                "AI assumptions that are not in the original PRD stay under open questions, never as fake requirements",
             ],
         }));
     }
-    if (stage === 'dag-draft') {
+    if (stage === "dag-draft") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
             outputPath: defaultHybridDagOutputPath(taskId),
             dependencies: [
                 paths.taskConfigPath,
-                path.join(paths.sourceDir, '需求.md'),
+                path.join(paths.sourceDir, "需求.md"),
             ],
-            template: { requiredHeadings: ['version', 'title', 'objective', 'tasks', 'executorModels'] },
+            template: {
+                requiredHeadings: [
+                    "version",
+                    "title",
+                    "objective",
+                    "tasks",
+                    "executorModels",
+                ],
+            },
             completionCriteria: [
-                'dag draft validates with dag validate --strict-models --strict-governance',
-                'writeSet is narrow and matches task constraints',
+                "dag draft validates with dag validate --strict-models --strict-governance",
+                "writeSet is narrow and matches task constraints",
             ],
         }));
     }
-    if (stage === 'promotion') {
+    if (stage === "promotion") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
-            outputPath: path.join(taskDir, 'artifacts'),
+            outputPath: path.join(taskDir, "artifacts"),
             dependencies: [
-                path.join(repoRoot, '.harness', 'dag-runs', 'completed'),
-                path.join(repoRoot, '.harness', 'runs', 'completed'),
+                path.join(repoRoot, ".harness", "dag-runs", "completed"),
+                path.join(repoRoot, ".harness", "runs", "completed"),
             ],
-            template: { requiredHeadings: ['# 修改记录', '# 验证结果'] },
+            template: { requiredHeadings: ["# 修改记录", "# 验证结果"] },
             completionCriteria: [
-                'completed run facts remain read-only',
-                'task artifacts summarize real run evidence without inventing verification',
+                "completed run facts remain read-only",
+                "task artifacts summarize real run evidence without inventing verification",
             ],
         }));
     }
-    if (stage === 'closeout') {
+    if (stage === "closeout") {
         return refreshInstructionBlockers(withMissingDependencies({
             ...base,
-            outputPath: path.join(repoRoot, 'docs', 'progress', `${taskId}.md`),
+            outputPath: path.join(repoRoot, "docs", "progress", `${taskId}.md`),
             dependencies: [
-                getArtifactPath(taskDir, 'implement'),
-                getArtifactPath(taskDir, 'verify'),
+                getArtifactPath(taskDir, "implement"),
+                getArtifactPath(taskDir, "verify"),
             ],
-            template: { requiredHeadings: ['# Progress', '## Summary', '## Verification', '## Remaining Risk'] },
+            template: {
+                requiredHeadings: [
+                    "# Progress",
+                    "## Summary",
+                    "## Verification",
+                    "## Remaining Risk",
+                ],
+            },
             completionCriteria: [
-                'records commands actually run and their outcome',
-                'links remaining risks or follow-up tasks',
+                "records commands actually run and their outcome",
+                "links remaining risks or follow-up tasks",
             ],
         }));
     }
-    const artifactSteps = ['analyze', 'plan', 'implement', 'verify', 'retrospective'];
+    const artifactSteps = [
+        "analyze",
+        "plan",
+        "implement",
+        "verify",
+        "retrospective",
+    ];
     return refreshInstructionBlockers(withMissingDependencies({
         ...base,
-        outputPath: path.join(taskDir, 'artifacts'),
+        outputPath: path.join(taskDir, "artifacts"),
         dependencies: [paths.taskConfigPath, paths.statePath],
         template: {
             requiredHeadings: artifactSteps.map((step) => getArtifactRelativePath(step)),
         },
         completionCriteria: [
-            'artifact content is substantive and not the new-task template',
-            'verification artifact names exact commands and pass/fail results',
+            "artifact content is substantive and not the new-task template",
+            "verification artifact names exact commands and pass/fail results",
         ],
     }));
 }
@@ -153,7 +185,7 @@ async function listExistingFiles(root) {
         const names = await readdir(root, { recursive: true });
         return names
             .map((name) => String(name))
-            .filter((name) => !name.includes('/logs/'))
+            .filter((name) => !name.includes("/logs/"))
             .sort();
     }
     catch {
@@ -179,17 +211,17 @@ export async function refreshInstructionBlockers(doc) {
 function formatInstructionsMarkdown(doc) {
     const lines = [
         `# Instructions: ${doc.artifactId}`,
-        '',
+        "",
         `- task: \`${doc.taskId}\``,
         `- output: \`${doc.outputPath}\``,
         `- write policy: \`${doc.writePolicy.mode}\``,
-        `- blocked: ${doc.blocked ? 'yes' : 'no'}`,
-        '',
-        '## Dependencies',
+        `- blocked: ${doc.blocked ? "yes" : "no"}`,
+        "",
+        "## Dependencies",
         ...doc.dependencies.map((dep) => `- \`${dep}\``),
-        '',
-        '## Completion Criteria',
+        "",
+        "## Completion Criteria",
         ...doc.completionCriteria.map((criterion) => `- ${criterion}`),
     ];
-    return `${lines.join('\n')}\n`;
+    return `${lines.join("\n")}\n`;
 }