@tea-agent/loop-agent 0.33.5 → 0.33.6

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,
                 },
             },
         };

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

@@ -5,7 +5,16 @@ import { getTaskPaths } from "../runtime.js";
 import { readSourceManifest, } from "../source-references.js";
 import { PREPARE_MAX_FILE_BYTES, PREPARE_MAX_PARSE_DOCS, PREPARE_MAX_TOTAL_BYTES, } from "./types.js";
 const PARSEABLE_EXTENSIONS = new Set([".md", ".markdown", ".txt"]);
+/** Roles that contribute requirement facts (objective/AC/scope). */
 const PARSEABLE_ROLES = new Set(["requirement", "acceptance"]);
+/** Roles whose body is loaded for artifact meta / diagnostics (not fact extraction). */
+const CONTENT_LOAD_ROLES = new Set([
+    "requirement",
+    "acceptance",
+    "analysis",
+    "clarification",
+    "design",
+]);
 function isSafeRelativeReferencePath(materializedPath) {
     const normalized = materializedPath.replace(/\\/g, "/").trim();
     if (!normalized)
@@ -52,6 +61,12 @@ function isParseableDoc(doc) {
         return false;
     return PARSEABLE_ROLES.has(doc.role);
 }
+function shouldLoadContent(doc) {
+    const ext = path.extname(doc.materializedPath).toLowerCase();
+    if (!PARSEABLE_EXTENSIONS.has(ext))
+        return false;
+    return CONTENT_LOAD_ROLES.has(doc.role) || PARSEABLE_ROLES.has(doc.role);
+}
 /**
  * Validate source-manifest + reference files before deriving a draft.
  * Fail-closed on taskId/path/hash/symlink/size issues.
@@ -170,6 +185,7 @@ export async function validateImportedPrdReferences(input) {
             continue;
         }
         const parseable = isParseableDoc(doc);
+        const loadContent = shouldLoadContent(doc);
         if (parseable) {
             parseableCount += 1;
             if (parseableCount > PREPARE_MAX_PARSE_DOCS) {
@@ -183,7 +199,7 @@ export async function validateImportedPrdReferences(input) {
         }
         let hashResult;
         try {
-            hashResult = await streamSha256AndBytes(absolutePath, parseable ? PREPARE_MAX_FILE_BYTES : undefined);
+            hashResult = await streamSha256AndBytes(absolutePath, loadContent ? PREPARE_MAX_FILE_BYTES : undefined);
         }
         catch (error) {
             if (error &&
@@ -223,7 +239,7 @@ export async function validateImportedPrdReferences(input) {
             });
         }
         let content;
-        if (parseable) {
+        if (loadContent) {
             totalParseBytes += hashResult.bytes;
             if (totalParseBytes > PREPARE_MAX_TOTAL_BYTES) {
                 issues.push({