scai 0.1.178 → 1.0.1

package/dist/agent/policy/loopReview.js

@@ -0,0 +1,778 @@
+/**
+ * Derives one structured review packet for every action-choice turn.
+ *
+ * Why this file exists:
+ * - loop review should stay separate from loop execution and step evaluation
+ * - grounded reads and unread candidates need one shared comparison owner
+ * - action-choice should reason from stable review signals instead of raw state dumps
+ * - wrapper files and follow-up references should be judged from code shape, not names
+ */
+import fs from "fs";
+import path from "path";
+import { classifyFileRulePath } from "../../fileRules/searchPathClassification.js";
+import { extractQuotedFragments } from "../search/searchContext.js";
+const MAX_REVIEW_CANDIDATES = 5;
+const OWNER_LIKE_LAYERS = new Set(["owner", "registration", "router", "config"]);
+const PURE_REEXPORT_PATTERN = /^export\s+(?:\*|\{[^}]+\})\s+from\s+["'][^"']+["'];?$/;
+const THIN_BRIDGE_PATTERN = /\b(re-exports?|legacy path|bridge|compat)\b/;
+function normalizePath(filePath) {
+    return String(filePath ?? "").replace(/\\/g, "/");
+}
+function getCandidatePriority(memory, filePath) {
+    const metadata = memory.evidence.candidateMetadata?.[filePath];
+    return metadata?.readPriority ?? metadata?.triageScore ?? metadata?.searchScore ?? 0;
+}
+function buildLayerHints(parts) {
+    return parts.filter(Boolean).join(" ").toLowerCase();
+}
+function collectGroundingCode(read) {
+    const excerptCode = (read.excerpts ?? []).map((excerpt) => excerpt.code).join("\n");
+    const snippetCode = (read.snippets ?? []).join("\n");
+    return [excerptCode, snippetCode].filter(Boolean).join("\n");
+}
+function collectNonCommentCodeLines(content) {
+    return content
+        .split("\n")
+        .map((line) => line.replace(/^\s*\d+:\s*/, "").trim())
+        .filter(Boolean)
+        .filter((line) => line !== "/**" && line !== "*/" && !line.startsWith("*") && !line.startsWith("//"));
+}
+function uniqueStrings(values) {
+    return Array.from(new Set(values.filter((value) => typeof value === "string" && value.trim().length > 0)));
+}
+function summarizeReadFact(read) {
+    const purpose = read.relevantContext.find((context) => context.kind === "purpose")?.text;
+    const summary = purpose ?? read.summary ?? read.relevanceExplanation ?? "";
+    const normalized = summary.replace(/\s+/g, " ").trim();
+    return `${path.basename(read.filePath)}: ${normalized || "grounded read recorded."}`;
+}
+function collectReadFactTokens(read) {
+    return uniqueStrings([
+        ...(read.keySymbols ?? []).map((symbol) => `symbol:${symbol}`),
+        read.summary ? `summary:${read.summary.trim()}` : undefined,
+        read.relevanceExplanation ? `why:${read.relevanceExplanation.trim()}` : undefined,
+        ...(read.relevantContext ?? []).map((context) => `${context.kind}:${context.text.trim()}`),
+    ]);
+}
+function extractQuotedRefs(code) {
+    const refs = [];
+    const patterns = [
+        [/\bexport\s+(?:\*|\{[^}]+\})\s+from\s+["']([^"']+)["']/g, "reexport"],
+        [/\bimport\s+[^"']+\s+from\s+["']([^"']+)["']/g, "import"],
+        [/\brequire\(\s*["']([^"']+)["']\s*\)/g, "import"],
+    ];
+    for (const [pattern, relation] of patterns) {
+        let match;
+        while ((match = pattern.exec(code)) !== null) {
+            refs.push({
+                relation,
+                specifier: match[1],
+            });
+        }
+    }
+    return refs;
+}
+/**
+ * Resolves local code references from TS import specifiers to real repo files.
+ * Example: `../agent/runtime/runAgentLoop.js` can resolve to `runAgentLoop.ts`.
+ */
+function resolveLocalRefCandidates(sourceFilePath, specifier) {
+    if (!specifier.startsWith(".")) {
+        return [];
+    }
+    const sourceDir = path.dirname(sourceFilePath);
+    const resolved = path.resolve(sourceDir, specifier);
+    const candidates = new Set([resolved]);
+    if (/\.(?:js|mjs|cjs)$/i.test(resolved)) {
+        candidates.add(resolved.replace(/\.(?:js|mjs|cjs)$/i, ".ts"));
+        candidates.add(resolved.replace(/\.(?:js|mjs|cjs)$/i, ".tsx"));
+    }
+    else if (!path.extname(resolved)) {
+        candidates.add(`${resolved}.ts`);
+        candidates.add(`${resolved}.tsx`);
+        candidates.add(`${resolved}.js`);
+        candidates.add(path.join(resolved, "index.ts"));
+        candidates.add(path.join(resolved, "index.tsx"));
+        candidates.add(path.join(resolved, "index.js"));
+    }
+    return Array.from(candidates).filter((candidate) => fs.existsSync(candidate));
+}
+function classifyGroundingDepth(read) {
+    const codeLines = collectNonCommentCodeLines(collectGroundingCode(read));
+    const relevantText = `${read.summary ?? ""} ${read.relevanceExplanation ?? ""}`.toLowerCase();
+    const hasAnyReexportBody = codeLines.some((line) => PURE_REEXPORT_PATTERN.test(line));
+    const hasPureReexportBody = codeLines.length > 0 && codeLines.every((line) => PURE_REEXPORT_PATTERN.test(line));
+    const hasThinBridgeComment = THIN_BRIDGE_PATTERN.test(relevantText);
+    const hasRealBody = codeLines.some((line) => /\bexport\s+(?:async\s+)?function\b/.test(line))
+        || codeLines.some((line) => /\bexport\s+(?:const|let|var|class|interface|type|enum)\b/.test(line))
+        || codeLines.some((line) => /\bmodule\.exports\b/.test(line))
+        || normalizePath(read.filePath).toLowerCase().endsWith("/package.json");
+    if (hasPureReexportBody && !hasRealBody) {
+        return {
+            groundingDepth: "wrapper",
+            signals: {
+                nonCommentCodeLineCount: codeLines.length,
+                hasPureReexportBody,
+                hasThinBridgeComment,
+                hasRealBody,
+            },
+        };
+    }
+    if ((hasAnyReexportBody || hasThinBridgeComment) && hasRealBody) {
+        return {
+            groundingDepth: "mixed",
+            signals: {
+                nonCommentCodeLineCount: codeLines.length,
+                hasPureReexportBody,
+                hasThinBridgeComment,
+                hasRealBody,
+            },
+        };
+    }
+    if (!hasRealBody && hasThinBridgeComment && codeLines.length <= 3) {
+        return {
+            groundingDepth: "wrapper",
+            signals: {
+                nonCommentCodeLineCount: codeLines.length,
+                hasPureReexportBody,
+                hasThinBridgeComment,
+                hasRealBody,
+            },
+        };
+    }
+    return {
+        groundingDepth: "direct",
+        signals: {
+            nonCommentCodeLineCount: codeLines.length,
+            hasPureReexportBody,
+            hasThinBridgeComment,
+            hasRealBody,
+        },
+    };
+}
+function classifyLayer(filePath, hints, read) {
+    const normalizedPath = normalizePath(filePath).toLowerCase();
+    const compactHints = hints.replace(/\s+/g, "");
+    const code = read ? collectGroundingCode(read) : "";
+    const codeLines = collectNonCommentCodeLines(code);
+    const hasCommandRegistration = /\.command\(\s*["'`]/.test(code) || /\.action\(\s*\(/.test(code);
+    const hasConfigObject = /\bprocess\.env\b/.test(code) || normalizedPath.endsWith("/package.json");
+    const hasRealImplementationBody = codeLines.some((line) => /\bexport\s+(?:async\s+)?function\b/.test(line))
+        || codeLines.some((line) => /\bexport\s+(?:const|let|var|class|interface|type|enum)\b/.test(line));
+    const hasPureReexportBody = codeLines.length > 0 && codeLines.every((line) => PURE_REEXPORT_PATTERN.test(line));
+    if (normalizedPath.includes("/__tests__/")
+        || normalizedPath.endsWith(".test.ts")
+        || normalizedPath.endsWith(".spec.ts")
+        || /\b(test harness|fixture|expected|snapshot)\b/.test(hints)) {
+        return "test-harness";
+    }
+    if (hasCommandRegistration) {
+        return "registration";
+    }
+    if (hasConfigObject) {
+        return "config";
+    }
+    if (hasPureReexportBody && !hasRealImplementationBody) {
+        return "unknown";
+    }
+    if (/register[a-z0-9]*command/i.test(normalizedPath)
+        || /register[a-z0-9]*command/i.test(compactHints)
+        || /\b(command|commands|entrypoint|entrypoints|test-run|integration-run)\b/.test(hints)) {
+        return "registration";
+    }
+    if (/\.config\./.test(normalizedPath)
+        || /\b(config|configuration|configured|default|defaults|setting|settings)\b/.test(hints)) {
+        return "config";
+    }
+    if (/\b(router|route|routing|dispatch|handler|orchestrator|state machine|pipeline)\b/.test(hints)) {
+        return "router";
+    }
+    if (hasRealImplementationBody
+        || /\b(owner|owns|define|defines|defined|definition|primary|main|source of truth|entry point)\b/.test(hints)
+        || /(^|\/)(index|main)\.[a-z0-9]+$/i.test(normalizedPath)) {
+        return "owner";
+    }
+    return "unknown";
+}
+function resolveQueryShape(memory) {
+    if (extractQuotedFragments(memory.task.initialQuery).length > 0) {
+        return "snippet";
+    }
+    const combined = `${memory.task.normalizedQuery} ${memory.task.primaryIntent}`.toLowerCase();
+    if (/\b(entrypoint|entrypoints|configured|configuration|where\b.*\b(set|register|configured)|how\b.*\bwire|how\b.*\brun tests?)\b/.test(combined)) {
+        return "config-entrypoint";
+    }
+    if (memory.task.queryScope === "broad-repo") {
+        return "broad-repo";
+    }
+    if (memory.task.queryScope === "multi-file"
+        || /\b(compare|between|versus|vs|divide responsibilities|responsibilit(?:y|ies)|architecture)\b/.test(combined)) {
+        return "multi-file";
+    }
+    return "targeted";
+}
+function isDistinctOwnerLayer(layer) {
+    return OWNER_LIKE_LAYERS.has(layer);
+}
+function classifyRelationToGrounded(filePath, layer, groundedLayers) {
+    const normalizedPath = normalizePath(filePath).toLowerCase();
+    if (layer === "test-harness") {
+        return "duplicate";
+    }
+    if (isDistinctOwnerLayer(layer) && groundedLayers.some((groundedLayer) => groundedLayer === "registration" || groundedLayer === "router")) {
+        return "parent-owner";
+    }
+    if (isDistinctOwnerLayer(layer) && groundedLayers.some((groundedLayer) => groundedLayer === layer)) {
+        return "sibling-owner";
+    }
+    if (groundedLayers.length > 0 && (normalizedPath.includes("/src/") || normalizedPath.endsWith(".ts"))) {
+        return "supporting";
+    }
+    return "unknown";
+}
+function resolveGroundedOwnerCount(groundedFiles, queryShape) {
+    return groundedFiles.filter((file) => {
+        if (!isDistinctOwnerLayer(file.looksLikeLayer)) {
+            return false;
+        }
+        if ((queryShape === "multi-file" || queryShape === "config-entrypoint") && file.groundingDepth === "wrapper") {
+            return false;
+        }
+        return true;
+    }).length;
+}
+function buildTargetCoverageSummary(explicitTargetPaths, groundedReads) {
+    const explicitTargetSet = new Set(explicitTargetPaths);
+    const groundedExplicitTargets = uniqueStrings(groundedReads
+        .map((read) => read.filePath)
+        .filter((filePath) => explicitTargetSet.has(filePath)));
+    const missingExplicitTargets = explicitTargetPaths.filter((filePath) => !groundedExplicitTargets.includes(filePath));
+    return {
+        explicitTargetCount: explicitTargetPaths.length,
+        groundedExplicitTargetCount: groundedExplicitTargets.length,
+        groundedExplicitTargets,
+        missingExplicitTargets,
+        allExplicitTargetsGrounded: explicitTargetPaths.length > 0 && missingExplicitTargets.length === 0,
+    };
+}
+function buildDiscoveredSoFarSummary(groundedReads, targetCoverage) {
+    const explicitTargetSet = new Set(targetCoverage.groundedExplicitTargets);
+    const targetFacts = groundedReads
+        .filter((read) => explicitTargetSet.has(read.filePath))
+        .slice(0, 3)
+        .map((read) => summarizeReadFact(read));
+    const supportingFacts = groundedReads
+        .filter((read) => !explicitTargetSet.has(read.filePath))
+        .slice(0, 2)
+        .map((read) => summarizeReadFact(read));
+    const missingGaps = targetCoverage.missingExplicitTargets.length > 0
+        ? targetCoverage.missingExplicitTargets.map((filePath) => `Need a grounded read for ${path.basename(filePath)}.`)
+        : [];
+    return {
+        targetFacts,
+        supportingFacts,
+        missingGaps,
+    };
+}
+function buildTargetFollowupSourceSet(explicitTargetPaths, groundedReads, queryShape, candidateFiles) {
+    const explicitTargetSet = new Set(explicitTargetPaths);
+    const linkedPaths = new Set(explicitTargetPaths);
+    for (const read of groundedReads) {
+        if (!explicitTargetSet.has(read.filePath)) {
+            continue;
+        }
+        for (const candidate of deriveFollowupReferenceCandidates(read, queryShape, candidateFiles)) {
+            linkedPaths.add(candidate.filePath);
+        }
+    }
+    return linkedPaths;
+}
+function buildRecentProgressSummary(groundedReads, targetCoverage, targetFollowupPaths) {
+    const recentReads = [...groundedReads]
+        .sort((left, right) => Date.parse(right.recordedAt) - Date.parse(left.recordedAt))
+        .slice(0, 3);
+    const olderFactTokens = new Set(groundedReads
+        .filter((read) => !recentReads.includes(read))
+        .flatMap((read) => collectReadFactTokens(read)));
+    const targetLinkedReadCount = recentReads.filter((read) => targetFollowupPaths.has(read.filePath)).length;
+    const newTargetLinkedFactCount = recentReads.reduce((count, read) => {
+        if (!targetFollowupPaths.has(read.filePath)) {
+            return count;
+        }
+        const hasNewFact = collectReadFactTokens(read).some((token) => !olderFactTokens.has(token));
+        return count + (hasNewFact ? 1 : 0);
+    }, 0);
+    const recentNonTargetStreak = recentReads
+        .slice(0, 2)
+        .every((read) => !targetFollowupPaths.has(read.filePath));
+    const stalled = targetCoverage.allExplicitTargetsGrounded &&
+        recentReads.length >= 2 &&
+        (recentNonTargetStreak || targetLinkedReadCount === 0 || newTargetLinkedFactCount === 0);
+    const reason = targetCoverage.allExplicitTargetsGrounded
+        ? stalled
+            ? "Recent reads did not add new target-linked facts after target coverage was complete."
+            : newTargetLinkedFactCount > 0
+                ? "Recent reads still added target-linked facts after the requested files were covered."
+                : "Requested files are covered and no recent follow-up reads were needed."
+        : targetCoverage.missingExplicitTargets.length > 0
+            ? "Recent work is still focused on covering the remaining requested files."
+            : "Recent reads still add grounded facts.";
+    return {
+        recentReadCount: recentReads.length,
+        targetLinkedReadCount,
+        newTargetLinkedFactCount,
+        stalled,
+        reason,
+    };
+}
+function scoreUnreadCandidateForReview(candidate, args) {
+    let score = candidate.followupScore ?? candidate.readPriority ?? candidate.triageScore ?? candidate.searchScore ?? 0;
+    const derivedFromExplicitTarget = candidate.derivedFromFilePath != null && args.explicitTargetSet.has(candidate.derivedFromFilePath);
+    if (derivedFromExplicitTarget) {
+        score += 100;
+    }
+    if (candidate.followupRelation === "reexport") {
+        score += 35;
+    }
+    else if (candidate.followupRelation === "import") {
+        score += 12;
+    }
+    if (args.queryShape === "config-entrypoint" &&
+        candidate.relationToGrounded === "parent-owner" &&
+        (candidate.looksLikeLayer === "owner" || candidate.looksLikeLayer === "config")) {
+        score += 18;
+    }
+    if (args.targetCoverage.allExplicitTargetsGrounded &&
+        candidate.followupRelation === "unknown" &&
+        candidate.relationToGrounded === "parent-owner") {
+        score -= 80;
+    }
+    if (args.targetCoverage.allExplicitTargetsGrounded &&
+        candidate.followupRelation === "unknown" &&
+        candidate.looksLikeLayer === "owner") {
+        score -= 40;
+    }
+    return score;
+}
+function buildExpansionAssessment(queryShape, topUnreadCandidates, targetCoverage, groundedFiles) {
+    const bestCandidate = topUnreadCandidates[0];
+    if (!bestCandidate) {
+        return {
+            shouldExpand: false,
+            reason: "No unread follow-up candidate is strong enough to justify another read.",
+        };
+    }
+    const groundedTargetSet = new Set(targetCoverage.groundedExplicitTargets);
+    const sourceGroundedSet = groundedTargetSet.size > 0
+        ? groundedTargetSet
+        : new Set(groundedFiles.map((file) => file.filePath));
+    const derivedFromGroundedTarget = bestCandidate.derivedFromFilePath != null && sourceGroundedSet.has(bestCandidate.derivedFromFilePath);
+    const hasGroundedWiringLayer = groundedFiles.some((file) => sourceGroundedSet.has(file.filePath) &&
+        (file.looksLikeLayer === "registration" || file.looksLikeLayer === "router"));
+    const configHandoffFollowup = queryShape === "config-entrypoint" &&
+        hasGroundedWiringLayer &&
+        (bestCandidate.relationToGrounded === "parent-owner" || bestCandidate.relationToGrounded === "sibling-owner") &&
+        (bestCandidate.looksLikeLayer === "owner"
+            || bestCandidate.looksLikeLayer === "config"
+            || bestCandidate.looksLikeLayer === "registration");
+    if (derivedFromGroundedTarget) {
+        const gap = bestCandidate.followupRelation === "reexport"
+            ? "Resolve the grounded target wrapper into its implementation."
+            : "Follow a direct target-linked reference into the next implementation file.";
+        return {
+            shouldExpand: true,
+            bestCandidatePath: bestCandidate.filePath,
+            gap,
+            relation: bestCandidate.followupRelation,
+            reason: `${path.basename(bestCandidate.filePath)} directly follows from a grounded requested file.`,
+        };
+    }
+    if (configHandoffFollowup) {
+        return {
+            shouldExpand: true,
+            bestCandidatePath: bestCandidate.filePath,
+            gap: "Follow the grounded wiring layer into the owner or config implementation.",
+            relation: bestCandidate.relationToGrounded,
+            reason: `${path.basename(bestCandidate.filePath)} closes a config or runtime handoff gap for the query.`,
+        };
+    }
+    return {
+        shouldExpand: false,
+        bestCandidatePath: bestCandidate.filePath,
+        relation: bestCandidate.followupRelation !== "unknown" ? bestCandidate.followupRelation : bestCandidate.relationToGrounded,
+        reason: `${path.basename(bestCandidate.filePath)} is not strongly linked to the requested target coverage.`,
+    };
+}
+function buildDriftAssessment(targetCoverage, recentProgress, expansionAssessment, topUnreadCandidates) {
+    const bestCandidate = topUnreadCandidates[0];
+    if (!targetCoverage.allExplicitTargetsGrounded) {
+        return {
+            status: "on-track",
+            blocksExpansion: false,
+            reason: "Requested target coverage is still incomplete.",
+        };
+    }
+    if (expansionAssessment.shouldExpand) {
+        return {
+            status: "on-track",
+            blocksExpansion: false,
+            reason: expansionAssessment.reason,
+        };
+    }
+    if (bestCandidate &&
+        recentProgress.stalled &&
+        bestCandidate.followupRelation === "unknown" &&
+        (bestCandidate.relationToGrounded === "parent-owner" || bestCandidate.looksLikeLayer === "owner")) {
+        return {
+            status: "hard-drift",
+            blocksExpansion: true,
+            reason: "Recent reads stalled after target coverage, and the next candidate is only a generic owner follow-up.",
+        };
+    }
+    if (bestCandidate) {
+        return {
+            status: "weak-drift",
+            blocksExpansion: false,
+            reason: `${path.basename(bestCandidate.filePath)} is a weak follow-up now that the requested files are already covered.`,
+        };
+    }
+    return {
+        status: "on-track",
+        blocksExpansion: false,
+        reason: "No unread follow-up remains.",
+    };
+}
+function buildFollowupSignals(args) {
+    const signals = [];
+    if (args.groundedCoverageCount < args.requiredGroundedCoverage) {
+        signals.push("Grounded coverage is still below the required threshold for this query.");
+    }
+    if (args.groundedLayers.some((layer) => layer === "registration" || layer === "router")
+        && args.topUnreadCandidates.some((candidate) => candidate.relationToGrounded === "parent-owner")) {
+        signals.push("A grounded wiring layer exists, but a likely owner or parent layer is still unread.");
+    }
+    if ((args.queryShape === "multi-file" || args.queryShape === "snippet" || args.queryShape === "config-entrypoint")
+        && args.hasUnreadDistinctOwner) {
+        signals.push("The query needs multiple grounded owners, and at least one distinct unread owner remains.");
+    }
+    if (args.queryShape === "config-entrypoint"
+        && args.topUnreadCandidates.some((candidate) => candidate.looksLikeLayer === "config" || candidate.looksLikeLayer === "owner")) {
+        signals.push("This looks like a configuration or entrypoint question, and a stronger owner-like unread candidate remains.");
+    }
+    if (args.topUnreadCandidates.some((candidate) => candidate.followupRelation === "reexport")) {
+        signals.push("A grounded wrapper points at a local implementation file that still has not been read.");
+    }
+    return signals;
+}
+function resolveStopAssessment(args) {
+    if (args.hasUnresolvedHardFileRequirement) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: "A required explicit target still has not resolved inside the repo.",
+        };
+    }
+    if (args.hasStructuredTargetRequirement && args.hasUnreadStructuredTargets) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: "A required explicit file or folder target still needs grounded reads.",
+        };
+    }
+    if (args.groundedCoverageCount === 0) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: "No grounded file evidence exists yet.",
+        };
+    }
+    const broadEnough = args.groundedCoverageCount >= Math.min(args.requiredGroundedCoverage, 2);
+    if (args.queryShape === "broad-repo") {
+        if (broadEnough && !args.hasUnreadDistinctOwner && !args.referenceFollowupNeeded) {
+            return {
+                canStop: true,
+                stopRisk: "low",
+                reason: "Representative grounded coverage exists for the broad repo question.",
+            };
+        }
+        return {
+            canStop: false,
+            stopRisk: args.hasUnreadDistinctOwner || args.referenceFollowupNeeded ? "medium" : "high",
+            reason: "Broad repo coverage is still missing a representative grounded owner.",
+        };
+    }
+    if (args.expansionAssessment.shouldExpand) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: args.expansionAssessment.reason,
+        };
+    }
+    if (args.targetCoverage.explicitTargetCount > 0 &&
+        !args.targetCoverage.allExplicitTargetsGrounded &&
+        (args.referenceFollowupNeeded || args.hasUnreadDistinctOwner)) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: "Unread distinct-owner candidates still make the answer incomplete.",
+        };
+    }
+    if (args.fullReadCoverageCount < args.requiredFullReadCoverage) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: "The answer still needs more grounded full reads.",
+        };
+    }
+    if (args.groundedCoverageCount < args.requiredGroundedCoverage) {
+        return {
+            canStop: false,
+            stopRisk: "high",
+            reason: "Grounded coverage is still below the required threshold.",
+        };
+    }
+    return {
+        canStop: true,
+        stopRisk: "low",
+        reason: "Grounded coverage is complete enough to stop.",
+    };
+}
+function scoreFollowupReferenceCandidate(args) {
+    const pathClass = classifyFileRulePath(args.filePath);
+    if (pathClass.isArtifact || pathClass.isGeneratedBuild || pathClass.isSourceMap || pathClass.isHarnessLike) {
+        return null;
+    }
+    let score = 0;
+    const reasons = [];
+    if (args.relation === "reexport") {
+        score += 5;
+        reasons.push("reexport-path");
+    }
+    else if (args.relation === "config-link") {
+        score += 4;
+        reasons.push("config-link");
+    }
+    else if (args.relation === "registration-call") {
+        score += 3;
+        reasons.push("registration-link");
+    }
+    else if (args.relation === "import") {
+        score += 1;
+        reasons.push("import-path");
+    }
+    if (args.queryShape === "multi-file" || args.queryShape === "config-entrypoint") {
+        score += 2;
+        reasons.push("query-shape-match");
+    }
+    if (args.candidateFiles.includes(args.filePath)) {
+        score += 2;
+        reasons.push("candidate-frontier");
+    }
+    return score >= 4
+        ? {
+            filePath: args.filePath,
+            relation: args.relation,
+            score,
+            reasons,
+            derivedFromFilePath: args.derivedFromFilePath,
+        }
+        : null;
+}
+function deriveFollowupReferenceCandidates(read, queryShape, candidateFiles) {
+    const code = collectGroundingCode(read);
+    const refs = extractQuotedRefs(code);
+    const candidates = [];
+    for (const ref of refs) {
+        for (const filePath of resolveLocalRefCandidates(read.filePath, ref.specifier)) {
+            const candidate = scoreFollowupReferenceCandidate({
+                filePath,
+                relation: ref.relation,
+                derivedFromFilePath: read.filePath,
+                queryShape,
+                candidateFiles,
+            });
+            if (candidate) {
+                candidates.push(candidate);
+            }
+        }
+    }
+    return candidates.sort((left, right) => right.score - left.score);
+}
+export function buildLoopReviewPacket(memory, coverage) {
+    const queryShape = resolveQueryShape(memory);
+    const groundedReads = Object.values(memory.evidence.fileReads)
+        .sort((left, right) => getCandidatePriority(memory, right.filePath) - getCandidatePriority(memory, left.filePath));
+    const explicitTargetPaths = uniqueStrings([
+        ...coverage.hardFileTargets,
+        ...coverage.requiredFolderTargets,
+    ]);
+    const explicitTargetSet = new Set(explicitTargetPaths);
+    const targetCoverage = buildTargetCoverageSummary(explicitTargetPaths, groundedReads);
+    const discoveredSoFar = buildDiscoveredSoFarSummary(groundedReads, targetCoverage);
+    const targetFollowupPaths = buildTargetFollowupSourceSet(explicitTargetPaths, groundedReads, queryShape, memory.evidence.candidateFiles);
+    const recentProgress = buildRecentProgressSummary(groundedReads, targetCoverage, targetFollowupPaths);
+    const groundedFiles = groundedReads.map((read) => {
+        const hints = buildLayerHints([
+            read.summary,
+            read.relevanceExplanation,
+            ...(read.relevantContext ?? []).map((context) => context.text),
+            ...(read.keySymbols ?? []),
+        ]);
+        const { groundingDepth } = classifyGroundingDepth(read);
+        return {
+            filePath: read.filePath,
+            role: read.role ?? "contextual",
+            readMode: read.readMode ?? "full",
+            keySymbols: read.keySymbols ?? [],
+            matchedTerms: read.matchedTerms ?? [],
+            relevantContext: (read.relevantContext ?? []).map((context) => context.text),
+            looksLikeLayer: classifyLayer(read.filePath, hints, read),
+            groundingDepth,
+        };
+    });
+    const groundedLayers = groundedFiles.map((file) => file.looksLikeLayer);
+    const fullReadCoverageCount = groundedFiles
+        .filter((file) => file.readMode === "full" && file.groundingDepth !== "wrapper")
+        .length;
+    const baseUnreadCandidates = memory.evidence.candidateFiles
+        .filter((filePath) => !memory.evidence.fileReads[filePath])
+        .sort((left, right) => getCandidatePriority(memory, right) - getCandidatePriority(memory, left))
+        .map((filePath) => {
+        const metadata = memory.evidence.candidateMetadata?.[filePath];
+        const hints = buildLayerHints([
+            path.basename(filePath),
+            ...(metadata?.searchReasons ?? []),
+            ...(metadata?.searchMatches ?? []).flatMap((match) => match.reasons ?? []),
+        ]);
+        const looksLikeLayer = classifyLayer(filePath, hints);
+        return {
+            filePath,
+            searchScore: metadata?.searchScore,
+            triageScore: metadata?.triageScore,
+            readPriority: metadata?.readPriority,
+            searchReasons: metadata?.searchReasons,
+            looksLikeLayer,
+            relationToGrounded: classifyRelationToGrounded(filePath, looksLikeLayer, groundedLayers),
+            followupRelation: "unknown",
+            followupScore: undefined,
+            derivedFromFilePath: undefined,
+        };
+    });
+    const followupByPath = new Map();
+    for (const read of groundedReads) {
+        for (const candidate of deriveFollowupReferenceCandidates(read, queryShape, memory.evidence.candidateFiles)) {
+            if (memory.evidence.fileReads[candidate.filePath]) {
+                continue;
+            }
+            const previous = followupByPath.get(candidate.filePath);
+            if (!previous || candidate.score > previous.score) {
+                followupByPath.set(candidate.filePath, candidate);
+            }
+        }
+    }
+    const unreadCandidates = Array.from(new Set([
+        ...baseUnreadCandidates.map((candidate) => candidate.filePath),
+        ...Array.from(followupByPath.keys()),
+    ]))
+        .map((filePath) => {
+        const baseCandidate = baseUnreadCandidates.find((candidate) => candidate.filePath === filePath);
+        const metadata = memory.evidence.candidateMetadata?.[filePath];
+        const followup = followupByPath.get(filePath);
+        const hints = buildLayerHints([
+            path.basename(filePath),
+            ...(metadata?.searchReasons ?? []),
+            ...(followup?.reasons ?? []),
+        ]);
+        const looksLikeLayer = baseCandidate?.looksLikeLayer ?? classifyLayer(filePath, hints);
+        return {
+            filePath,
+            searchScore: metadata?.searchScore ?? baseCandidate?.searchScore,
+            triageScore: metadata?.triageScore ?? baseCandidate?.triageScore,
+            readPriority: metadata?.readPriority ?? baseCandidate?.readPriority ?? followup?.score,
+            searchReasons: metadata?.searchReasons ?? baseCandidate?.searchReasons ?? followup?.reasons,
+            looksLikeLayer,
+            relationToGrounded: baseCandidate?.relationToGrounded ?? classifyRelationToGrounded(filePath, looksLikeLayer, groundedLayers),
+            followupRelation: followup?.relation ?? "unknown",
+            followupScore: followup?.score,
+            derivedFromFilePath: followup?.derivedFromFilePath,
+        };
+    })
+        .sort((left, right) => {
+        const rightScore = scoreUnreadCandidateForReview(right, {
+            queryShape,
+            targetCoverage,
+            explicitTargetSet,
+        });
+        const leftScore = scoreUnreadCandidateForReview(left, {
+            queryShape,
+            targetCoverage,
+            explicitTargetSet,
+        });
+        if (rightScore !== leftScore) {
+            return rightScore - leftScore;
+        }
+        return getCandidatePriority(memory, right.filePath) - getCandidatePriority(memory, left.filePath);
+    })
+        .slice(0, MAX_REVIEW_CANDIDATES);
+    const groundedOwnerCount = resolveGroundedOwnerCount(groundedFiles, queryShape);
+    const hasUnreadDistinctOwner = unreadCandidates.some((candidate) => candidate.followupRelation === "reexport"
+        || candidate.relationToGrounded === "parent-owner"
+        || candidate.relationToGrounded === "sibling-owner"
+        || ((queryShape === "multi-file" || queryShape === "snippet" || queryShape === "config-entrypoint")
+            && candidate.relationToGrounded !== "duplicate"
+            && candidate.looksLikeLayer !== "test-harness"));
+    const followupSignals = buildFollowupSignals({
+        queryShape,
+        groundedCoverageCount: groundedFiles.filter((file) => file.groundingDepth !== "wrapper").length,
+        requiredGroundedCoverage: coverage.requiredGroundedCoverage,
+        groundedLayers,
+        topUnreadCandidates: unreadCandidates,
+        hasUnreadDistinctOwner,
+    });
+    const expansionAssessment = buildExpansionAssessment(queryShape, unreadCandidates, targetCoverage, groundedFiles);
+    const driftAssessment = buildDriftAssessment(targetCoverage, recentProgress, expansionAssessment, unreadCandidates);
+    if (expansionAssessment.shouldExpand && expansionAssessment.gap) {
+        discoveredSoFar.missingGaps.push(expansionAssessment.gap);
+    }
+    const referenceFollowupNeeded = expansionAssessment.shouldExpand;
+    const stopAssessment = resolveStopAssessment({
+        queryShape,
+        groundedCoverageCount: groundedFiles.filter((file) => file.groundingDepth !== "wrapper").length,
+        requiredGroundedCoverage: coverage.requiredGroundedCoverage,
+        fullReadCoverageCount,
+        requiredFullReadCoverage: coverage.requiredFullReadCoverage,
+        hasUnreadDistinctOwner,
+        referenceFollowupNeeded,
+        targetCoverage,
+        expansionAssessment,
+        hasStructuredTargetRequirement: coverage.hasStructuredTargetRequirement,
+        hasUnreadStructuredTargets: coverage.unreadHardFileTargets.length > 0,
+        hasUnresolvedHardFileRequirement: coverage.hasUnresolvedHardFileRequirement,
+    });
+    return {
+        groundingStatus: stopAssessment.canStop
+            ? "solid"
+            : groundedFiles.length > 0
+                ? "partial"
+                : "weak",
+        queryShape,
+        requiredGroundedCoverage: coverage.requiredGroundedCoverage,
+        groundedCoverageCount: groundedFiles.length,
+        targetCoverage,
+        groundedFiles,
+        discoveredSoFar,
+        topUnreadCandidates: unreadCandidates,
+        followupSignals,
+        recentProgress,
+        expansionAssessment,
+        driftAssessment,
+        multiFileStatus: {
+            required: queryShape === "multi-file" || queryShape === "snippet" || queryShape === "config-entrypoint",
+            groundedOwnerCount,
+            hasUnreadDistinctOwner,
+        },
+        stopAssessment,
+        referenceFollowupNeeded,
+    };
+}
+//# sourceMappingURL=loopReview.js.map