@tea-agent/loop-agent 0.33.7-beta.0 → 0.34.0

package/dist/shared/resilient-git.js

@@ -0,0 +1,133 @@
+import { spawn } from "node:child_process";
+import { access, constants } from "node:fs/promises";
+import path from "node:path";
+/** Thrown only for spawn/infrastructure failures or exhausted eligible startup retries. */
+export class ResilientGitCommandError extends Error {
+    diagnostics;
+    constructor(input) {
+        const last = input.attempts.at(-1);
+        super(`git ${input.command} unavailable after ${input.attempts.length} attempts (exit code=${last?.exitCode ?? "unavailable"}, exit code hex=${last?.exitCodeHex ?? "unavailable"}, signal=${last?.signal ?? "unavailable"}, cwd=${path.resolve(input.cwd)}): ${last?.detail ?? "unknown infrastructure error"}`);
+        this.name = "ResilientGitCommandError";
+        this.diagnostics = { schemaVersion: 1, ...input };
+    }
+}
+export function isResilientGitCommandError(error) {
+    return error instanceof ResilientGitCommandError;
+}
+export function formatWindowsExitCode(exitCode) {
+    return exitCode === undefined
+        ? undefined
+        : `0x${(exitCode >>> 0).toString(16).padStart(8, "0").toUpperCase()}`;
+}
+export function isWindowsDllInitializationFailure(platform, exitCode) {
+    return platform === "win32" && exitCode !== undefined && (exitCode >>> 0) === 0xc0000142;
+}
+/** Only returns the original executable and its sibling within the same Git installation. */
+export function deriveSameInstallationGitCandidates(primary) {
+    const normalized = path.win32.normalize(primary);
+    const lower = normalized.toLowerCase();
+    let sibling;
+    if (lower.endsWith("\\mingw64\\bin\\git.exe")) {
+        const root = path.win32.resolve(path.win32.dirname(normalized), "..", "..");
+        sibling = path.win32.join(root, "cmd", "git.exe");
+    }
+    else if (lower.endsWith("\\cmd\\git.exe")) {
+        const root = path.win32.resolve(path.win32.dirname(normalized), "..");
+        sibling = path.win32.join(root, "mingw64", "bin", "git.exe");
+    }
+    return [...new Set([normalized, ...(sibling ? [sibling] : [])])];
+}
+const windowsCandidateCache = new Map();
+export async function resolveGitExecutableCandidates(platform, env) {
+    if (platform !== "win32")
+        return ["git"];
+    const pathValue = env.PATH ?? env.Path ?? "";
+    const cached = windowsCandidateCache.get(pathValue);
+    if (cached)
+        return cached;
+    const resolved = resolveWindowsGitExecutableCandidates(pathValue);
+    windowsCandidateCache.set(pathValue, resolved);
+    return resolved;
+}
+async function resolveWindowsGitExecutableCandidates(pathValue) {
+    for (const raw of pathValue.split(path.delimiter)) {
+        const entry = raw.trim().replace(/^"|"$/g, "");
+        if (!entry)
+            continue;
+        const candidate = path.win32.join(entry, "git.exe");
+        try {
+            await access(candidate, constants.X_OK);
+            const candidates = [];
+            for (const executable of deriveSameInstallationGitCandidates(candidate)) {
+                try {
+                    await access(executable, constants.X_OK);
+                    candidates.push(executable);
+                }
+                catch { /* optional sibling */ }
+            }
+            if (candidates.length)
+                return candidates;
+        }
+        catch { /* continue PATH search */ }
+    }
+    return ["git"];
+}
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+const bounded = (text) => text.length <= 1000 ? text : `${text.slice(0, 1000)}...[truncated]`;
+/**
+ * Execute a read-only Git command with bounded recovery for Windows startup failures.
+ * Completed non-zero commands are deliberately returned to preserve caller semantics.
+ */
+export async function runResilientGitCommand(options, dependencies = {}) {
+    const platform = dependencies.platform ?? process.platform;
+    const env = { ...(dependencies.env ?? process.env), GIT_OPTIONAL_LOCKS: "0" };
+    const candidates = await (dependencies.resolveExecutableCandidates ?? resolveGitExecutableCandidates)(platform, env);
+    const executables = candidates.length ? candidates : ["git"];
+    const maxAttempts = Math.max(1, options.attempts ?? 3);
+    const delay = Math.max(0, options.retryDelayMs ?? 250);
+    const execute = dependencies.runAttempt ?? spawnGitAttempt;
+    const sleep = dependencies.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const now = dependencies.now ?? Date.now;
+    const attemptDiagnostics = [];
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        const executable = executables[(attempt - 1) % executables.length];
+        const startedAt = now();
+        try {
+            const result = await execute({ executable, args: options.args, cwd: options.cwd, env, windowsHide: true, maxBuffer: options.maxBuffer ?? DEFAULT_MAX_BUFFER });
+            if (result.code === 0)
+                return result;
+            const dllFailure = isWindowsDllInitializationFailure(platform, result.code);
+            const emptyStartupFailure = result.stdout.length === 0 && result.stderr.length === 0;
+            const eligible = platform === "win32" && (dllFailure || emptyStartupFailure);
+            if (!eligible)
+                return result;
+            attemptDiagnostics.push({
+                attempt, executable, exitCode: result.code, ...(formatWindowsExitCode(result.code) ? { exitCodeHex: formatWindowsExitCode(result.code) } : {}), signal: result.signal,
+                durationMs: Math.max(0, now() - startedAt), detail: bounded("no stdout/stderr"),
+                transientKind: dllFailure ? "windows-dll-init-failed" : "empty-output-startup-failure",
+            });
+        }
+        catch (error) {
+            const detail = bounded(error instanceof Error ? error.message : String(error));
+            attemptDiagnostics.push({ attempt, executable, signal: null, durationMs: Math.max(0, now() - startedAt), detail });
+        }
+        if (attempt < maxAttempts && delay > 0)
+            await sleep(Math.min(4_000, delay * 2 ** (attempt - 1)));
+    }
+    throw new ResilientGitCommandError({ cwd: options.cwd, command: options.args.join(" "), platform, executableCandidates: executables, attempts: attemptDiagnostics });
+}
+function spawnGitAttempt(input) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(input.executable, input.args, { cwd: input.cwd, env: input.env, windowsHide: input.windowsHide, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        const append = (current, chunk) => {
+            const next = current + String(chunk);
+            return next.length > input.maxBuffer ? next.slice(0, input.maxBuffer) : next;
+        };
+        child.stdout.on("data", (chunk) => { stdout = append(stdout, chunk); });
+        child.stderr.on("data", (chunk) => { stderr = append(stderr, chunk); });
+        child.on("error", reject);
+        child.on("close", (code, signal) => resolve({ code: code ?? 1, signal, stdout, stderr }));
+    });
+}

package/dist/task/source-prepare/artifact-meta.js

@@ -0,0 +1,137 @@
+/**
+ * Product Analysis / Product Requirement artifact frontmatter detection.
+ * Deterministic; no LLM. Used to route intake errors and parseable roles.
+ */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u;
+function parseYamlishScalar(raw) {
+    const trimmed = raw.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+        return trimmed.slice(1, -1).trim();
+    }
+    return trimmed;
+}
+function parseSimpleFrontmatter(block) {
+    const out = {};
+    for (const line of block.split(/\r?\n/)) {
+        const match = /^([A-Za-z0-9_-]+)\s*:\s*(.+?)\s*$/u.exec(line);
+        if (!match)
+            continue;
+        out[match[1]] = parseYamlishScalar(match[2]);
+    }
+    return out;
+}
+function normalizeArtifactType(raw) {
+    if (!raw)
+        return "unknown";
+    const value = raw.trim().toLowerCase();
+    if (value === "product-requirement" || value === "product_requirement") {
+        return "product-requirement";
+    }
+    if (value === "product-analysis" || value === "product_analysis") {
+        return "product-analysis";
+    }
+    if (value === "requirement-clarification" ||
+        value === "requirement_clarification" ||
+        value === "product-clarification") {
+        return "requirement-clarification";
+    }
+    return "unknown";
+}
+/**
+ * Detect Product Analysis V3/V4 style artifact metadata from markdown body.
+ */
+export function detectProductArtifactMeta(markdown) {
+    const match = FRONTMATTER_RE.exec(markdown);
+    if (!match) {
+        return { artifactType: "unknown", recognized: false };
+    }
+    const fields = parseSimpleFrontmatter(match[1]);
+    const artifactType = normalizeArtifactType(fields.artifact_type);
+    const recognized = artifactType !== "unknown" || Boolean(fields.artifact_version);
+    return {
+        artifactType,
+        ...(fields.artifact_version
+            ? { artifactVersion: fields.artifact_version }
+            : {}),
+        ...(fields.requirement_status
+            ? { requirementStatus: fields.requirement_status }
+            : {}),
+        ...(fields.analysis_status
+            ? { analysisStatus: fields.analysis_status }
+            : {}),
+        ...(fields.requirement_id ? { requirementId: fields.requirement_id } : {}),
+        ...(fields.analysis_scope ? { analysisScope: fields.analysis_scope } : {}),
+        recognized,
+    };
+}
+/**
+ * Infer import role from file path basename when --role is omitted.
+ */
+export function inferPrdImportRoleFromPath(filePath) {
+    const base = filePath
+        .replace(/\\/g, "/")
+        .split("/")
+        .pop()
+        ?.toLowerCase()
+        .replace(/\.(md|markdown|txt)$/u, "") ?? "";
+    if (base === "product-analysis" ||
+        base.endsWith("-product-analysis") ||
+        base.includes("product-analysis")) {
+        return "analysis";
+    }
+    if (base === "requirement-clarification" ||
+        base.endsWith("-requirement-clarification") ||
+        base.includes("requirement-clarification") ||
+        base.includes("clarification")) {
+        return "clarification";
+    }
+    if (base === "product-requirement" ||
+        base.endsWith("-product-requirement") ||
+        base.includes("product-requirement")) {
+        return "requirement";
+    }
+    if (base.includes("acceptance"))
+        return "acceptance";
+    return "requirement";
+}
+/**
+ * Prefer path inference; if markdown frontmatter is available and more specific, use it.
+ */
+export function resolvePrdImportRole(input) {
+    if (input.explicitRole?.trim())
+        return input.explicitRole.trim();
+    if (input.markdown) {
+        const meta = detectProductArtifactMeta(input.markdown);
+        if (meta.artifactType === "product-analysis")
+            return "analysis";
+        if (meta.artifactType === "requirement-clarification") {
+            return "clarification";
+        }
+        if (meta.artifactType === "product-requirement")
+            return "requirement";
+    }
+    return inferPrdImportRoleFromPath(input.filePath);
+}
+/** Roles that may contribute requirement facts (objective/AC/scope). */
+export const REQUIREMENT_FACT_ROLES = new Set(["requirement", "acceptance"]);
+/** Roles that are archival references only (not fact sources). */
+export const REFERENCE_ONLY_ROLES = new Set(["analysis", "clarification", "design"]);
+export function isIntakeSoftGapCode(code) {
+    return (code === "EMPTY_ACCEPTANCE" ||
+        code === "EMPTY_OBJECTIVE" ||
+        code === "EMPTY_ALLOWED_PATHS" ||
+        code === "EMPTY_TASK_KIND" ||
+        code === "NO_PARSEABLE_REQUIREMENT" ||
+        code === "PRODUCT_ANALYSIS_NOT_EXECUTABLE" ||
+        code === "PRODUCT_REQUIREMENT_PENDING" ||
+        code === "PRODUCT_CLARIFICATION_NOT_EXECUTABLE" ||
+        code === "PRODUCT_ARTIFACT_NOT_EXECUTABLE" ||
+        code === "MISSING_FEATURE_ID" ||
+        code === "SEMANTIC_INTAKE_RECOMMENDED" ||
+        code === "SEMANTIC_INTAKE_FAILED" ||
+        code === "SEMANTIC_INTAKE_INVALID_OUTPUT" ||
+        code === "SEMANTIC_INTAKE_PI_FAILED" ||
+        code === "SEMANTIC_INTAKE_NO_DOCUMENTS" ||
+        code === "SEMANTIC_INTAKE_REFUSED_NON_EXECUTABLE");
+}

package/dist/task/source-prepare/index.js

@@ -1,6 +1,8 @@
 export * from "./types.js";
 export * from "./path-policy.js";
 export * from "./parse-intent.js";
+export * from "./artifact-meta.js";
+export * from "./semantic-intake.js";
 export * from "./reference-integrity.js";
 export * from "./completeness.js";
 export * from "./build-draft.js";

package/dist/task/source-prepare/parse-intent.js

@@ -1,6 +1,19 @@
 const HEADING_ALIASES = {
-    objective: new Set(["目标", "objective", "问题与目标"]),
-    scope: new Set(["范围", "scope", "in scope"]),
+    objective: new Set([
+        "目标",
+        "objective",
+        "问题与目标",
+        "业务目标",
+        "需求概述",
+    ]),
+    scope: new Set([
+        "范围",
+        "scope",
+        "in scope",
+        "需求范围",
+        "已确认范围",
+        "已确认需求",
+    ]),
     nonGoals: new Set(["非目标", "out of scope", "non-goals", "non goals"]),
     acceptance: new Set(["验收标准", "acceptance criteria", "acceptance"]),
     constraints: new Set(["约束", "constraints", "不变式", "invariants"]),
@@ -8,6 +21,8 @@ const HEADING_ALIASES = {
     assumptions: new Set(["假设", "assumptions"]),
 };
 const OBJECTIVE_MAX_CHARS = 1200;
+/** Product Requirement V3/V4 style embedded AC heading, e.g. AC-FE-001 / AC-BE-12 / AC-001. */
+const EMBEDDED_AC_HEADING = /^(AC(?:[-_](?:FE|BE|UI|API))?[-_]?\d+(?:[-_]\d+)?)\s*[:：]?\s*(.*)$/iu;
 function stripFencedAndComments(text) {
     // Remove fenced code blocks and HTML comments so headings inside them are ignored.
     return text
@@ -18,10 +33,28 @@ function stripFencedAndComments(text) {
 function normalizeHeadingText(raw) {
     return raw
         .trim()
+        // Strip leading section numbers: "2. 业务目标" / "3.1 已确认范围" / "3.2、非目标"
+        .replace(/^(?:\d+(?:\.\d+)*[.．、]?\s*)+/u, "")
         .toLowerCase()
         .replace(/[:：]\s*$/u, "")
         .replace(/\s+/g, " ");
 }
+function normalizeAcceptanceId(raw) {
+    return raw
+        .trim()
+        .toUpperCase()
+        .replace(/_/g, "-")
+        .replace(/^(AC)(FE|BE|UI|API)(?=-|\d)/u, "$1-$2");
+}
+function parseEmbeddedAcHeading(headingText) {
+    const normalized = headingText.trim().replace(/^(?:\d+(?:\.\d+)*[.．、]?\s*)+/u, "");
+    const match = EMBEDDED_AC_HEADING.exec(normalized);
+    if (!match)
+        return null;
+    const id = normalizeAcceptanceId(match[1]);
+    const text = match[2]?.trim() || id;
+    return { id, text };
+}
 function classifyHeading(text) {
     const normalized = normalizeHeadingText(text);
     for (const [key, aliases] of Object.entries(HEADING_ALIASES)) {
@@ -48,14 +81,17 @@ function parseAcceptanceLine(line, nextId) {
     const body = (checklist?.[1] ?? bullet?.[1] ?? line.trim()).trim();
     if (!body)
         return null;
+    const embedded = parseEmbeddedAcHeading(body);
+    if (embedded)
+        return embedded;
     const withId = /^(AC[-_]?\d+)\s*[:：]\s*(.+)$/iu.exec(body);
     if (withId) {
-        return { id: withId[1].toUpperCase().replace("_", "-"), text: withId[2].trim() };
+        return { id: normalizeAcceptanceId(withId[1]), text: withId[2].trim() };
     }
     const bareAc = /^(AC[-_]?\d+)\s+(.+)$/iu.exec(body);
     if (bareAc) {
         return {
-            id: bareAc[1].toUpperCase().replace("_", "-"),
+            id: normalizeAcceptanceId(bareAc[1]),
             text: bareAc[2].trim(),
         };
     }
@@ -114,9 +150,27 @@ export function extractRequirementFactsFromMarkdown(markdown, options) {
     const sections = [];
     let current = { key: "other", lines: [] };
     sections.push(current);
+    let acCounter = options?.acCounterStart ?? 1;
+    const nextId = () => {
+        const id = `AC-${String(acCounter).padStart(3, "0")}`;
+        acCounter += 1;
+        return id;
+    };
     for (const line of lines) {
         const heading = isAtxHeading(line);
         if (heading) {
+            // Product Requirement V3/V4 embeds formal AC as headings (#### AC-FE-001 ...).
+            // Capture the heading as a single AC; GWT body lists under it stay non-AC.
+            const embeddedAc = parseEmbeddedAcHeading(heading.text);
+            if (embeddedAc) {
+                sections.push({
+                    key: "acceptance",
+                    lines: [`- ${embeddedAc.id}: ${embeddedAc.text}`],
+                });
+                current = { key: "other", lines: [] };
+                sections.push(current);
+                continue;
+            }
             const key = classifyHeading(heading.text);
             current = { key, lines: [] };
             sections.push(current);
@@ -124,12 +178,6 @@ export function extractRequirementFactsFromMarkdown(markdown, options) {
         }
         current.lines.push(line);
     }
-    let acCounter = options?.acCounterStart ?? 1;
-    const nextId = () => {
-        const id = `AC-${String(acCounter).padStart(3, "0")}`;
-        acCounter += 1;
-        return id;
-    };
     let objective;
     const scope = [];
     const nonGoals = [];

package/dist/task/source-prepare/prepare.js

@@ -6,6 +6,7 @@ import { getTaskContractPaths } from "../contract/paths.js";
 import { loadTaskConfig } from "../runtime.js";
 import { buildPrepareDraft } from "./build-draft.js";
 import { hasBlockingGaps, hasBlockingRisks, isFreshLegacyUnversioned, listPrepareGaps, } from "./completeness.js";
+import { detectProductArtifactMeta, isIntakeSoftGapCode, } from "./artifact-meta.js";
 import { extractRequirementFactsFromMarkdown, fillMissingRequirementFacts, mergeRequirementFacts, } from "./parse-intent.js";
 import { draftReferencesFromManifest, validateImportedPrdReferences, } from "./reference-integrity.js";
 import { readSourceManifest } from "../source-references.js";
@@ -131,31 +132,139 @@ function mutationOutcome(code) {
 }
 function buildNextSteps(input) {
     const next = [];
+    const codes = new Set(input.gaps.map((g) => g.code));
     if (!input.hasImportedPrd) {
-        next.push(`loop-agent import-prd ${input.taskId} --file <prd.md> --role requirement`);
+        next.push(`loop-agent task advance ${input.taskId} --prd <product-requirement.md> --allowed-path <glob> --json`);
     }
-    if (input.gaps.some((g) => g.code === "EMPTY_ALLOWED_PATHS")) {
-        next.push("补 --allowed-path <glob>");
+    if (codes.has("PRODUCT_ANALYSIS_NOT_EXECUTABLE")) {
+        next.push("使用同目录 product-requirement.md 作为 --prd（role=requirement）；product-analysis.md 仅作引用（--role analysis）");
+        next.push("禁止改写原始 product-analysis / product-requirement 产物，禁止在原 PRD 目录生成兼容 Markdown 或 reviewed-draft.json");
     }
-    if (input.gaps.some((g) => g.code === "EMPTY_ACCEPTANCE")) {
-        next.push("补 --ac <id:text> 或完善 PRD 验收标准章节");
+    if (codes.has("PRODUCT_CLARIFICATION_NOT_EXECUTABLE")) {
+        next.push("requirement-clarification.md 是决策追溯，不是可执行 PRD；请导入 complete 的 product-requirement.md");
+    }
+    if (codes.has("PRODUCT_REQUIREMENT_PENDING")) {
+        next.push("先完成 analyze-product-requirements 澄清并将 product-requirement.md 标为 complete，再 task advance --prd");
+    }
+    if (codes.has("EMPTY_ALLOWED_PATHS")) {
+        next.push("补 --allowed-path <glob>（工程边界必须显式给出）");
+    }
+    if (codes.has("EMPTY_ACCEPTANCE") || codes.has("EMPTY_OBJECTIVE")) {
+        next.push("PRD 真缺验收标准/目标时：补完整 product-requirement（Given/When/Then 或 AC 标题），或显式 --from-text；不要自动生成 sidecar draft JSON");
+    }
+    if (codes.has("SEMANTIC_INTAKE_RECOMMENDED")) {
+        next.push("文档语义完整但结构非标准：整理为 product-requirement 或标准「目标/范围/非目标/验收标准」Markdown；不要在原 PRD 目录生成兼容 md/json");
+    }
+    if (codes.has("SEMANTIC_INTAKE_FAILED") || codes.has("SEMANTIC_INTAKE_INVALID_OUTPUT")) {
+        next.push("semantic intake 未能产出可接受 draft：补全 product-requirement 或标准验收标准后重试；禁止在原 PRD 目录生成 sidecar JSON");
     }
     if (input.mode === "dry-run" && input.ok) {
-        next.push(`loop-agent task source prepare ${input.taskId} --use-imported-prd ... --apply --json`);
+        next.push(`loop-agent task advance ${input.taskId} --allowed-path <glob> --json`);
     }
     if (input.ok && input.mode === "apply") {
         next.push(`loop-agent task status ${input.taskId} --json`);
         next.push(`loop-agent task advance ${input.taskId} --profile auto --json`);
         next.push("审查 DAG writeSet 后再 task advance --approve-gate ...");
     }
-    if (input.gaps.some((g) => g.code === "DIRTY_SOURCE" || g.code === "MANAGED_PROJECTION_INCOMPLETE")) {
-        next.push(`loop-agent task advance ${input.taskId} --from-draft <reviewed-draft.json> --json`);
+    if (codes.has("DIRTY_SOURCE") ||
+        codes.has("MANAGED_PROJECTION_INCOMPLETE")) {
+        next.push(`高级恢复（仅人工 reviewed draft）：loop-agent task advance ${input.taskId} --from-draft <reviewed-draft.json> --json`);
+        next.push("--from-draft 不是 EMPTY_ACCEPTANCE 的默认恢复路径；禁止在原 PRD 目录自动生成 draft JSON");
     }
-    if (input.gaps.some((g) => g.code === "TRANSACTION_INCOMPLETE")) {
+    if (codes.has("TRANSACTION_INCOMPLETE")) {
         next.push(`loop-agent task advance ${input.taskId} --json`);
     }
     return next;
 }
+function appendProductArtifactGaps(input) {
+    if (!input.sourceIntegrity)
+        return;
+    const docs = input.sourceIntegrity.documents.filter((d) => d.content);
+    if (docs.length === 0)
+        return;
+    let sawAnalysisOnly = false;
+    let sawClarificationOnly = false;
+    let sawPendingRequirement = false;
+    let sawExecutableRequirement = false;
+    let sawUnknownNarrative = false;
+    for (const doc of docs) {
+        const meta = detectProductArtifactMeta(doc.content);
+        if (meta.artifactType === "product-analysis") {
+            sawAnalysisOnly = true;
+            continue;
+        }
+        if (meta.artifactType === "requirement-clarification") {
+            sawClarificationOnly = true;
+            continue;
+        }
+        if (meta.artifactType === "product-requirement") {
+            if (meta.requirementStatus &&
+                meta.requirementStatus.trim().toLowerCase() === "pending") {
+                sawPendingRequirement = true;
+            }
+            else {
+                sawExecutableRequirement = true;
+            }
+            continue;
+        }
+        if (doc.role === "requirement" &&
+            meta.artifactType === "unknown" &&
+            !input.hasAcceptance) {
+            sawUnknownNarrative = true;
+        }
+    }
+    const hasRequirementRole = input.sourceIntegrity.parseableDocuments.some((d) => d.role === "requirement" || d.role === "acceptance");
+    if (!hasRequirementRole && sawAnalysisOnly) {
+        input.gaps.push({
+            code: "PRODUCT_ANALYSIS_NOT_EXECUTABLE",
+            level: "blocking",
+            field: "acceptanceCriteria",
+            message: "imported document is product-analysis (no formal AC by design); use product-requirement.md as --prd requirement",
+        });
+    }
+    if (!hasRequirementRole &&
+        sawClarificationOnly &&
+        !sawExecutableRequirement) {
+        input.gaps.push({
+            code: "PRODUCT_CLARIFICATION_NOT_EXECUTABLE",
+            level: "blocking",
+            field: "acceptanceCriteria",
+            message: "imported document is requirement-clarification (decision log only); use complete product-requirement.md",
+        });
+    }
+    if (sawPendingRequirement && !input.hasAcceptance) {
+        input.gaps.push({
+            code: "PRODUCT_REQUIREMENT_PENDING",
+            level: "blocking",
+            field: "acceptanceCriteria",
+            message: "product-requirement is still pending clarification; complete analyze-product-requirements before task advance",
+        });
+    }
+    if (sawUnknownNarrative &&
+        !input.hasAcceptance &&
+        !sawPendingRequirement &&
+        !sawAnalysisOnly) {
+        input.gaps.push({
+            code: "SEMANTIC_INTAKE_RECOMMENDED",
+            level: "warning",
+            message: "requirement body lacks structured AC headings; use product-requirement or standard Markdown sections — do not auto-write sidecar drafts",
+        });
+    }
+    const precise = new Set([
+        "PRODUCT_ANALYSIS_NOT_EXECUTABLE",
+        "PRODUCT_CLARIFICATION_NOT_EXECUTABLE",
+        "PRODUCT_REQUIREMENT_PENDING",
+    ]);
+    if (input.gaps.some((g) => precise.has(g.code))) {
+        for (const gap of input.gaps) {
+            if (gap.code === "EMPTY_ACCEPTANCE") {
+                gap.level = "warning";
+                gap.message =
+                    "acceptance criteria empty (superseded by product-artifact diagnostic)";
+            }
+        }
+    }
+}
 function emptyObservedHashPlaceholder() {
     return "0".repeat(64);
 }
@@ -389,13 +498,36 @@ export async function prepareTaskSource(input) {
             message: "no parseable requirement document and no --ac / supplemental text; import a requirement-role PRD or pass flags",
         });
     }
+    // Product Analysis / pending Product Requirement diagnostics (precise gaps).
+    if (input.intent.kind === "facts" && input.intent.useImportedPrd) {
+        appendProductArtifactGaps({
+            gaps,
+            sourceIntegrity,
+            hasAcceptance: built.draft.requirement.acceptanceCriteria.length > 0,
+        });
+    }
     const validation = await validateDraftForTask({
         repoRoot,
         taskId,
         draft: built.draft,
     });
     if (!validation.ok) {
+        const productArtifactBlocking = gaps.some((gap) => [
+            "PRODUCT_ANALYSIS_NOT_EXECUTABLE",
+            "PRODUCT_CLARIFICATION_NOT_EXECUTABLE",
+            "PRODUCT_REQUIREMENT_PENDING",
+        ].includes(gap.code));
         for (const message of validation.errors) {
+            const isAcceptanceSchema = /acceptance criterion|acceptanceCriteria/i.test(message);
+            // Prefer product-artifact diagnostics over generic schema AC errors.
+            if (productArtifactBlocking && isAcceptanceSchema) {
+                gaps.push({
+                    code: "DRAFT_VALIDATION",
+                    level: "warning",
+                    message: `${message} (superseded by product-artifact diagnostic)`,
+                });
+                continue;
+            }
             gaps.push({
                 code: "DRAFT_VALIDATION",
                 level: "blocking",
@@ -428,13 +560,32 @@ export async function prepareTaskSource(input) {
         .filter((gap) => gap.level === "blocking")
         .map((gap) => gap.code);
     const transactionIncomplete = blockingCodes.includes("TRANSACTION_INCOMPLETE");
+    const productArtifactCodes = [
+        "PRODUCT_ANALYSIS_NOT_EXECUTABLE",
+        "PRODUCT_CLARIFICATION_NOT_EXECUTABLE",
+        "PRODUCT_REQUIREMENT_PENDING",
+        "PRODUCT_ARTIFACT_NOT_EXECUTABLE",
+    ];
+    const primaryBlockingCode = blockingCodes.find((code) => productArtifactCodes.includes(code)) ??
+        blockingCodes.find((code) => code !== "EMPTY_ACCEPTANCE") ??
+        blockingCodes[0] ??
+        "INVALID_INPUT";
+    // Soft intake only when PRD was imported (or product-artifact diagnostics apply).
+    // Bare missing flags without import stay hard-invalid.
+    const softIntakeOnly = blocking &&
+        blockingCodes.length > 0 &&
+        blockingCodes.every((code) => isIntakeSoftGapCode(code)) &&
+        (hasImportedPrd ||
+            blockingCodes.some((code) => productArtifactCodes.includes(code)));
     if (input.mode !== "apply") {
         return {
             ok: !blocking,
             outcome: blocking
                 ? transactionIncomplete
                     ? "needs-reconcile"
-                    : "invalid"
+                    : softIntakeOnly
+                        ? "blocked"
+                        : "invalid"
                 : "succeeded",
             mode: "dry-run",
             taskId,
@@ -452,9 +603,13 @@ export async function prepareTaskSource(input) {
                     error: {
                         code: transactionIncomplete
                             ? "TRANSACTION_INCOMPLETE"
-                            : "INVALID_INPUT",
-                        message: "task source draft has blocking gaps",
-                        details: { gaps: blockingCodes },
+                            : softIntakeOnly
+                                ? primaryBlockingCode
+                                : "INVALID_INPUT",
+                        message: softIntakeOnly
+                            ? "PRD imported or facts present but intake incomplete; DAG not generated"
+                            : "task source draft has blocking gaps",
+                        details: { gaps: blockingCodes, softIntake: softIntakeOnly },
                     },
                 }
                 : {}),
@@ -486,7 +641,9 @@ export async function prepareTaskSource(input) {
     if (blocking) {
         const outcome = blockingCodes.includes("DIRTY_SOURCE")
             ? "blocked"
-            : "invalid";
+            : softIntakeOnly
+                ? "blocked"
+                : "invalid";
         return {
             ok: false,
             outcome,
@@ -502,10 +659,17 @@ export async function prepareTaskSource(input) {
             contractStatus: state.effectiveStatus,
             warnings,
             error: {
-                code: outcome === "blocked" ? "DIRTY_SOURCE" : "INVALID_INPUT",
-                message: "task source draft has blocking gaps",
+                code: blockingCodes.includes("DIRTY_SOURCE")
+                    ? "DIRTY_SOURCE"
+                    : softIntakeOnly
+                        ? primaryBlockingCode
+                        : "INVALID_INPUT",
+                message: softIntakeOnly
+                    ? "PRD imported or facts present but intake incomplete; DAG not generated"
+                    : "task source draft has blocking gaps",
                 details: {
                     gaps: blockingCodes,
+                    softIntake: softIntakeOnly,
                 },
             },
         };