@tea-agent/loop-agent 0.40.0-next.2 → 0.40.0-next.4

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

@@ -6,11 +6,15 @@ import { TASK_CONTRACT_DRAFT_SCHEMA_VERSION } from "../contract/constants.js";
 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 { hasBlockingGaps, hasBlockingRisks, isFreshLegacyUnversioned, listPrepareGaps, appendLedgerGaps, } 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";
+import { buildRequirementLedger, classifyLedgerGate, effectiveSourceResolutions, summarizeLedger, validateRequirementLedger, } from "./ledger.js";
+import { defaultLedgerReviewer, LEDGER_REVIEW_DEFAULT_BUDGET_CHARS, ledgerReviewItemsFromRecords, reviewLedgerFragments, } from "./ledger-review.js";
+import { buildFragmentInventory } from "./fragment-inventory.js";
+import { sha256Utf8 } from "../contract/hash.js";
 import { PREPARE_MAX_FILE_BYTES } from "./types.js";
 async function fileNonEmpty(filePath) {
     try {
@@ -67,6 +71,81 @@ function isProjectedSourceResolutionsSection(sectionBody) {
         return true;
     return lines.every((line) => entryRe.test(line));
 }
+/**
+ * Typed parse of one canonical Source Resolutions line (project.ts L63-68):
+ * `- ${sourceRef}: ${conflict} → ${decision} (${reason}; decidedBy=${decidedBy})`.
+ * Tail-anchor strategy (AC-008 / AC-HARD-002, exact inverse of the projector's
+ * left-to-right concatenation): sourceRef ends at the first `: `, conflict ends
+ * at the first ` → `, and the reason group is reversed from the tail — the line
+ * must close with `)`, the REAL `; decidedBy=` separator is the LAST occurrence
+ * (reason may itself contain `; decidedBy=`), and the reason group opener is the
+ * LAST ` (` before that anchor (decision may itself contain ` (`). decision/reason
+ * round-trip byte-exact, including spaces and ASCII parentheses — no truncation
+ * at the first ` (`. Any missing field or shape mismatch returns null — the
+ * caller must reject the whole section (fail-closed), never partially accept.
+ * decidedBy is additionally enforced to be exactly "human" here
+ * (schema z.enum(['human'])); model/system/hand-edited values are treated as
+ * hand-edited/model-decided and block with MANAGED_PROJECTION_INCOMPLETE (AC-004b).
+ */
+function parseSourceResolutionLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("- "))
+        return null;
+    const rest = trimmed.slice(2);
+    const sourceRefEnd = rest.indexOf(": ");
+    if (sourceRefEnd <= 0)
+        return null;
+    const sourceRef = rest.slice(0, sourceRefEnd);
+    const afterSourceRef = rest.slice(sourceRefEnd + 2);
+    const arrow = afterSourceRef.indexOf(" → ");
+    if (arrow <= 0)
+        return null;
+    const conflict = afterSourceRef.slice(0, arrow);
+    const afterArrow = afterSourceRef.slice(arrow + 3);
+    // 尾部锚点：行必须以 `)` 收尾，真实分隔符取最后一次 `; decidedBy=`
+    // （reason 可能内嵌 ASCII `; decidedBy=`，首个锚点会截断 reason）。
+    if (!afterArrow.endsWith(")"))
+        return null;
+    const decidedByAnchor = "; decidedBy=";
+    const decidedIdx = afterArrow.lastIndexOf(decidedByAnchor);
+    if (decidedIdx < 0)
+        return null;
+    const decidedBy = afterArrow.slice(decidedIdx + decidedByAnchor.length, -1);
+    if (decidedBy !== "human")
+        return null;
+    // reason 起始：锚点之前最后一个 ` (`（decision 可能内嵌 ASCII ` (`，首个 ` (`
+    // 会截断 decision）。decision/reason 逐字节保留。
+    const reasonRegion = afterArrow.slice(0, decidedIdx);
+    const paren = reasonRegion.lastIndexOf(" (");
+    if (paren <= 0)
+        return null;
+    const decision = reasonRegion.slice(0, paren);
+    const reason = reasonRegion.slice(paren + 2);
+    if (!conflict.trim() || !decision.trim() || !reason.trim())
+        return null;
+    return { sourceRef, conflict, decision, reason, decidedBy };
+}
+/**
+ * Parse the whole `## Source Resolutions` section body into typed resolutions.
+ * Returns null when any line fails — the section is rejected as a whole, never
+ * partially accepted or silently downgraded (AC-004). Empty sections yield an
+ * empty array (kept semantics: isProjectedSourceResolutionsSection accepts
+ * empty sections).
+ */
+function parseSourceResolutionsSection(sectionBody) {
+    const lines = sectionBody
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const resolutions = [];
+    for (const line of lines) {
+        const parsed = parseSourceResolutionLine(line);
+        if (!parsed)
+            return null;
+        resolutions.push(parsed);
+    }
+    return resolutions;
+}
 /** Section titles the read-back validator may inspect (static whitelist). */
 const MANAGED_PROJECTION_SECTION_TITLES = [
     "References",
@@ -135,6 +214,22 @@ async function loadManagedProjectionDraft(input) {
                     " --from-draft <reviewed-draft.json> --json",
             };
         }
+        // Typed read-back (2026-08-24 L1): the shape regex above accepts any
+        // decidedBy value; the typed parser is the projector's exact inverse and
+        // additionally enforces decidedBy === 'human' (schema z.enum(['human'])).
+        // A regex-valid but non-canonical line (decidedBy=model/system/hand-edited)
+        // or any free-form line fails the whole section — never partial accept.
+        const parsedSourceResolutions = sourceResolutionsBody !== null
+            ? parseSourceResolutionsSection(sourceResolutionsBody)
+            : null;
+        if (sourceResolutionsBody !== null && parsedSourceResolutions === null) {
+            return {
+                ok: false,
+                message: "managed requirement projection contains hand-edited or model-decided Source Resolutions entries (only canonical decidedBy=human lines are accepted); use loop-agent task advance " +
+                    input.taskId +
+                    " --from-draft <reviewed-draft.json> --json",
+            };
+        }
         const requirementFacts = extractRequirementFactsFromMarkdown(requirementRaw);
         const constraintFacts = extractRequirementFactsFromMarkdown(constraints);
         if (!requirementFacts.objective?.trim()) {
@@ -184,6 +279,9 @@ async function loadManagedProjectionDraft(input) {
                 ...(requirementFacts.assumptions.length > 0
                     ? { assumptions: requirementFacts.assumptions }
                     : {}),
+                ...(parsedSourceResolutions && parsedSourceResolutions.length > 0
+                    ? { sourceResolutions: parsedSourceResolutions }
+                    : {}),
                 hardConstraints: config.hardConstraints,
             },
         };
@@ -601,6 +699,161 @@ export async function prepareTaskSource(input) {
         sourceFilesPresent,
         forceOverwriteSource: input.forceOverwriteSource,
     });
+    // -------------------------------------------------------------------
+    // Source fidelity ledger (20260824-frontend-source-fidelity-ledger-v1)
+    // 在 buildPrepareDraft/listPrepareGaps 与 applyTaskContract 之间编排
+    // fragment-inventory + ledger 构建。原始 requirement/acceptance 文档保持语义
+    // 权威；派生 需求.md 仅作导航视图。reconciliation 失败返回稳定错误并停止，
+    // 不回退摘要。
+    // -------------------------------------------------------------------
+    let ledger;
+    let ledgerSummary;
+    if (hasImportedPrd &&
+        sourceIntegrity &&
+        sourceIntegrity.parseableDocuments.some((doc) => doc.role === "requirement" || doc.role === "acceptance")) {
+        try {
+            const authoritativeDocs = sourceIntegrity.parseableDocuments.filter((doc) => (doc.role === "requirement" || doc.role === "acceptance") &&
+                typeof doc.content === "string" &&
+                doc.content.trim().length > 0);
+            const sourceDocuments = authoritativeDocs.map((doc) => {
+                // Canonical source identity 单一边界（AC-001 / AC-FIDELITY-REPAIR-001）：
+                // ledger sourceDocuments[].path 与 DAG 侧 serializeDagTaskSourcePath /
+                // resolveDagTaskSourcePath 一致（repo-root relative POSIX），路径转换只
+                // 发生在该边界，不再二次转换进入 digest 计算。
+                const absolute = path.resolve(contractPaths.sourceDir, doc.materializedPath);
+                return {
+                    path: path
+                        .relative(repoRoot, absolute)
+                        .split(path.sep)
+                        .join("/"),
+                    content: doc.content,
+                };
+            });
+            if (sourceDocuments.length > 0) {
+                const requirementProjection = projectRequirementMarkdown(built.draft);
+                ledger = await buildRequirementLedger({
+                    taskId,
+                    requirementSha256: sha256Utf8(requirementProjection),
+                    sourceDocuments,
+                    canonicalRequirements: built.draft.requirement.acceptanceCriteria,
+                    sourceResolutions: (built.draft.sourceResolutions ?? []).map((res) => ({
+                        sourceRef: res.sourceRef,
+                        conflict: res.conflict,
+                        decision: res.decision,
+                        reason: res.reason,
+                        decidedBy: res.decidedBy,
+                    })),
+                    ...(input.sourceFidelity?.reconcile
+                        ? { reconcile: input.sourceFidelity.reconcile }
+                        : {}),
+                });
+                const classification = classifyLedgerGate(ledger, {
+                    expectedInputDigest: ledger.inputDigest,
+                });
+                const ledgerErrors = classification.ok ? [] : [
+                    { code: classification.code, message: classification.message },
+                ];
+                if (!classification.ok &&
+                    classification.code !== "SOURCE_FIDELITY_LEDGER_STALE") {
+                    ledgerErrors.push(...validateRequirementLedger(ledger).filter((error) => error.code !== classification.code));
+                }
+                // 独立 reviewer（AC-007 / AC-FIDELITY-REPAIR-007）：context-only /
+                // duplicate / conflict 进入独立审核阶段（与 reconciler 分离）；低风险
+                // context-only 仅 reviewer pass 放行，高风险 context-only 始终阻断。
+                // review 条目携带按 budgetChars 有界截断的原始片段文本与精确 fragment id
+                // （AC-004 / AC-HARD-004）；canonicalRequirements 采用 ledger 物化后的
+                // canonicalRequirements（含 REQ-SRC-*，不再仅取 draft acceptance）。
+                const review = await reviewLedgerFragments({
+                    fragments: ledgerReviewItemsFromRecords(ledger.fragments, {
+                        fragments: buildFragmentInventory({
+                            documents: sourceDocuments,
+                            canonicalRequirements: built.draft.requirement.acceptanceCriteria,
+                        }).fragments,
+                        budgetChars: LEDGER_REVIEW_DEFAULT_BUDGET_CHARS,
+                    }),
+                    canonicalRequirements: ledger.canonicalRequirements.map((requirement) => ({
+                        id: requirement.id,
+                        text: requirement.text,
+                    })),
+                    reviewer: input.sourceFidelity?.reviewer ?? defaultLedgerReviewer,
+                    conflictIds: new Set(ledger.conflicts.map((entry) => entry.id)),
+                    resolvedConflictIds: effectiveSourceResolutions(ledger),
+                });
+                // 独立 reviewer 拒绝 → 全码透传：低风险 context-only / 高风险 context-only /
+                // duplicate / conflict 均以精确稳定码进入 ledgerErrors；review.code===null
+                // 时防御性回退 SOURCE_FIDELITY_RECONCILIATION_FAILED（fail-closed）。message
+                // 取有界 review.reasons.join("; ")。追加前跳过与既有 ledgerErrors 中 code 与
+                // message 均完全一致的条目（不得按 code 单独去重：同码不同 message 必须保留）。
+                const reviewRejectedCodes = [];
+                if (!review.approved) {
+                    const code = review.code ?? "SOURCE_FIDELITY_RECONCILIATION_FAILED";
+                    const message = review.reasons.join("; ");
+                    const alreadyPresent = ledgerErrors.some((error) => error.code === code && error.message === message);
+                    if (!alreadyPresent) {
+                        ledgerErrors.push({ code, message });
+                        reviewRejectedCodes.push(code);
+                    }
+                }
+                ledgerSummary = summarizeLedger(ledger, {
+                    gateStatus: ledgerErrors.length > 0 ? "fail" : "pass",
+                    failureCode: ledgerErrors[0]?.code ?? null,
+                });
+                appendLedgerGaps({
+                    gaps,
+                    risks,
+                    ledgerSummary,
+                    ledgerErrors,
+                    taskKind: built.draft.taskKind,
+                });
+                // appendLedgerGaps 只消费 LEDGER_MISSING / CONTEXT_ONLY_UNREVIEWED 与摘要派生码
+                // （UNRESOLVED / CONFLICT / HIGH_RISK_UNCOVERED）；reviewer 派生且未被消费的码
+                // （如 duplicate → SOURCE_FIDELITY_RECONCILIATION_FAILED）内联补 gap+risk，镜像
+                // catch 块 L917–L925 模式，保证 hasBlockingGaps(gaps) 对 frontend-implementation
+                // 触发、prepare/apply 真正 fail closed。追加前检查 gaps 中尚不存在同码同级别 gap
+                // （appendLedgerGaps 或 catch 块可能已产生），避免双条目。
+                const reviewerBlocking = built.draft.taskKind === "frontend-implementation";
+                const reviewerGapLevel = reviewerBlocking
+                    ? "blocking"
+                    : "warning";
+                for (const code of reviewRejectedCodes) {
+                    if (gaps.some((gap) => gap.code === code &&
+                        gap.level === reviewerGapLevel)) {
+                        continue;
+                    }
+                    const message = ledgerErrors.find((error) => error.code === code)
+                        ?.message ??
+                        `independent reviewer rejected (${code})`;
+                    gaps.push({
+                        code,
+                        level: reviewerGapLevel,
+                        message,
+                    });
+                    risks.push({
+                        code,
+                        level: reviewerBlocking ? "blocking" : "elevated",
+                        message,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            gaps.push({
+                code: "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+                level: "blocking",
+                message: `requirement ledger reconciliation failed: ${message}（不回退摘要）`,
+            });
+            risks.push({
+                code: "SOURCE_FIDELITY_RECONCILIATION_FAILED",
+                level: "blocking",
+                message: `requirement ledger reconciliation failed: ${message}`,
+            });
+        }
+    }
+    const ledgerResult = {
+        ...(ledger ? { ledger } : {}),
+        ...(ledgerSummary ? { ledgerSummary } : {}),
+    };
     if (managedProjectionError) {
         gaps.push({
             code: "MANAGED_PROJECTION_INCOMPLETE",
@@ -742,6 +995,7 @@ export async function prepareTaskSource(input) {
             next,
             contractStatus: state.effectiveStatus,
             warnings,
+            ...ledgerResult,
             ...(blocking
                 ? {
                     error: {
@@ -776,6 +1030,7 @@ export async function prepareTaskSource(input) {
             next: [`loop-agent task advance ${taskId} --json`],
             contractStatus: state.effectiveStatus,
             warnings,
+            ...ledgerResult,
             error: {
                 code: "TRANSACTION_INCOMPLETE",
                 message: "unfinished transaction; re-run task advance (auto recover-contract)",
@@ -802,6 +1057,7 @@ export async function prepareTaskSource(input) {
             next,
             contractStatus: state.effectiveStatus,
             warnings,
+            ...ledgerResult,
             error: {
                 code: blockingCodes.includes("DIRTY_SOURCE")
                     ? "DIRTY_SOURCE"
@@ -832,6 +1088,7 @@ export async function prepareTaskSource(input) {
             risks,
             projected,
             next: [`loop-agent task status ${taskId} --details --json`],
+            ...ledgerResult,
             error: {
                 code: "OBSERVED_HASH_CONFLICT",
                 message: "unable to determine expectedObservedHash",
@@ -852,6 +1109,7 @@ export async function prepareTaskSource(input) {
             requestId,
             requestPayloadSha256,
             payloadSha256Trusted: true,
+            ...(ledger ? { requirementLedger: ledger } : {}),
         });
         return {
             ok: true,
@@ -874,6 +1132,7 @@ export async function prepareTaskSource(input) {
             }),
             contractStatus: "managed",
             warnings,
+            ...ledgerResult,
         };
     }
     catch (error) {
@@ -894,6 +1153,7 @@ export async function prepareTaskSource(input) {
                     `loop-agent task status ${taskId} --json`,
                     `loop-agent task status ${taskId} --details --json`,
                 ],
+                ...ledgerResult,
                 error: {
                     code: error.code,
                     message: error.message,
@@ -911,6 +1171,7 @@ export async function prepareTaskSource(input) {
             risks,
             projected,
             next: [],
+            ...ledgerResult,
             error: {
                 code: "INTERNAL_ERROR",
                 message: error instanceof Error ? error.message : String(error),

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

@@ -411,6 +411,24 @@ export async function buildRepoHint(repoRoot) {
     }
     return lines.join("\n");
 }
+/**
+ * 在 maxChars 附近回退到最近的标题边界再截断（AC-005 / AC-FIDELITY-REPAIR-005
+ * 回归点移除）：避免把可执行项/列表项从中间切开吞掉。仅用于模型提示词预算；
+ * ledger fragment inventory 始终消费完整原文，不经过此裁剪。
+ */
+function clipAtSectionBoundary(content, maxChars) {
+    if (content.length <= maxChars)
+        return content;
+    const prefix = content.slice(0, maxChars);
+    const headingRe = /^(?:#{1,6})\s+.+$/gm;
+    let boundary = prefix.length;
+    let match;
+    while ((match = headingRe.exec(prefix)) !== null) {
+        if (match.index >= maxChars * 0.4)
+            boundary = match.index;
+    }
+    return `${content.slice(0, boundary)}\n\n[truncated at section boundary]`;
+}
 async function buildPrompt(input) {
     const bodies = input.documents
         .map((doc, index) => {
@@ -418,9 +436,7 @@ async function buildPrompt(input) {
         const metaLine = meta.recognized
             ? `artifact_type=${meta.artifactType} status=${meta.requirementStatus ?? meta.analysisStatus ?? "n/a"}`
             : "artifact_type=unknown";
-        const clipped = doc.content.length > 24_000
-            ? `${doc.content.slice(0, 24_000)}\n\n[truncated]`
-            : doc.content;
+        const clipped = clipAtSectionBoundary(doc.content, 24_000);
         return [
             `### Document ${index + 1}`,
             `role: ${doc.role}`,