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

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);
 }
@@ -222,7 +331,19 @@ export async function prepareTaskSource(input) {
             constraintsPath: contractPaths.constraintsPath,
         });
         if (projection.ok) {
-            baseDraft = projection.draft;
+            baseDraft = input.intent.replaceManagedRequirement
+                ? {
+                    ...projection.draft,
+                    requirement: {
+                        objective: "",
+                        scope: [],
+                        nonGoals: [],
+                        acceptanceCriteria: [],
+                    },
+                    openQuestions: [],
+                    assumptions: [],
+                }
+                : projection.draft;
         }
         else {
             managedProjectionError = projection.message;
@@ -287,7 +408,30 @@ export async function prepareTaskSource(input) {
                 taskId,
                 requireParseableRequirement: false,
             });
-            hasImportedPrd = true;
+            const requestedPaths = new Set((input.intent.importedPrdPaths ?? [])
+                .map((value) => value.replace(/\\/g, "/").trim())
+                .filter(Boolean));
+            if (requestedPaths.size > 0) {
+                const selectedDocuments = sourceIntegrity.documents.filter((document) => requestedPaths.has(document.materializedPath.replace(/\\/g, "/")));
+                const selectedPaths = new Set(selectedDocuments.map((document) => document.materializedPath.replace(/\\/g, "/")));
+                for (const requestedPath of requestedPaths) {
+                    if (selectedPaths.has(requestedPath))
+                        continue;
+                    sourceIntegrity.issues.push({
+                        code: "REFERENCE_NOT_IN_MANIFEST",
+                        level: "blocking",
+                        message: `current import batch reference not found in source-manifest: ${requestedPath}`,
+                        path: requestedPath,
+                    });
+                    sourceIntegrity.ok = false;
+                }
+                sourceIntegrity = {
+                    ...sourceIntegrity,
+                    documents: selectedDocuments,
+                    parseableDocuments: selectedDocuments.filter((document) => document.parseable),
+                };
+            }
+            hasImportedPrd = sourceIntegrity.documents.length > 0;
             if (sourceIntegrity.ok) {
                 references = draftReferencesFromManifest(sourceIntegrity.documents);
                 let acStart = 1;
@@ -389,13 +533,48 @@ 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));
+        const hasEmptyAcceptance = gaps.some((gap) => gap.code === "EMPTY_ACCEPTANCE");
         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;
+            }
+            // Soft-intake path: completeness already has EMPTY_ACCEPTANCE (soft).
+            // Do not add a hard DRAFT_VALIDATION twin that flips softIntake=false
+            // and blocks one-shot Semantic Intake for free-form PRDs.
+            if (hasEmptyAcceptance && isAcceptanceSchema) {
+                gaps.push({
+                    code: "DRAFT_VALIDATION",
+                    level: "warning",
+                    message: `${message} (soft intake; EMPTY_ACCEPTANCE primary)`,
+                });
+                continue;
+            }
             gaps.push({
                 code: "DRAFT_VALIDATION",
                 level: "blocking",
@@ -428,13 +607,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 +650,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 +688,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 +706,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({