flowseeker 0.1.7 → 0.1.9

package/dist/pipeline/solvePacket.js

@@ -38,37 +38,258 @@ exports.renderSolvePacketMarkdown = renderSolvePacketMarkdown;
 const fs = __importStar(require("fs/promises"));
 const fileGroups_1 = require("./fileGroups");
 const contextBlueprint_1 = require("./contextBlueprint");
+const workspaceIndex_1 = require("../index/workspaceIndex");
+const fusionTrace_1 = require("./fusionTrace");
 const maxPrimaryEditFiles = 7;
 const maxReadOnlyFiles = 7;
 const maxVerificationFiles = 6;
 const maxNoiseRiskFiles = 6;
 const maxSnippetChars = 850;
 const minSnippetBudgetChars = 9000;
-async function buildSolvePacket(result, config) {
+async function buildSolvePacket(result, config, workspaceRoot) {
     const groups = (0, fileGroups_1.aggregateEvidenceFiles)(result.units);
     const coverageGroups = selectCoverageGroups(groups, result);
     const primaryEditCandidates = coverageGroups.filter((group) => group.role === "edit_candidate" && group.slot !== "tests" && !group.contrastContext);
-    const verificationTargets = groups.filter((group) => group.slot === "tests" || group.role === "test");
+    const verificationTargets = groups.filter((group) => group.slot === "tests" || group.role === "test" || isTestAdjacent(group));
+    // Fallback: if no test files found, include config/build files that suggest verification capability
+    if (verificationTargets.length === 0) {
+        const fallbackVerify = groups.filter((group) => isVerificationHint(group));
+        verificationTargets.push(...fallbackVerify.slice(0, maxVerificationFiles));
+    }
     const noiseRisk = detectNoiseRisk(groups, result);
+    // Fallback: include low-confidence groups that aren't assigned elsewhere
+    if (noiseRisk.length === 0) {
+        const assigned = new Set([...primaryEditCandidates.map(g => g.relativePath), ...verificationTargets.map(g => g.relativePath)]);
+        const lowConfidence = groups.filter(g => !assigned.has(g.relativePath) && g.tier === "low" && g.score < 50);
+        noiseRisk.push(...lowConfidence.slice(0, maxNoiseRiskFiles));
+    }
     const noisePaths = new Set(noiseRisk.map((group) => group.relativePath));
     const primaryPaths = new Set(primaryEditCandidates.map((group) => group.relativePath));
     const verificationPaths = new Set(verificationTargets.map((group) => group.relativePath));
-    const readOnlyContext = coverageGroups.filter((group) => !primaryPaths.has(group.relativePath) && !verificationPaths.has(group.relativePath) && !noisePaths.has(group.relativePath));
+    let readOnlyContext = coverageGroups.filter((group) => !primaryPaths.has(group.relativePath) && !verificationPaths.has(group.relativePath) && !noisePaths.has(group.relativePath));
+    // Fallback: include any remaining groups with context role or connected files
+    if (readOnlyContext.length === 0) {
+        const assigned = new Set([...primaryPaths, ...verificationPaths, ...noisePaths]);
+        readOnlyContext = groups.filter((group) => !assigned.has(group.relativePath)).slice(0, maxReadOnlyFiles);
+    }
     const snippetBudget = {
         remainingChars: Math.max(minSnippetBudgetChars, config.pipeline.maxContextTokens * 4)
     };
+    // Build packet files
+    const primaryFiles = await toPacketFiles(primaryEditCandidates.slice(0, Math.min(maxPrimaryEditFiles, config.pipeline.maxCandidates)), snippetBudget, "primary", result);
+    const readOnlyFiles = await toPacketFiles(readOnlyContext.slice(0, Math.min(maxReadOnlyFiles, config.pipeline.maxCandidates)), snippetBudget, "context", result);
+    const verificationFiles = await toPacketFiles(verificationTargets.slice(0, Math.min(maxVerificationFiles, config.pipeline.maxCandidates)), snippetBudget, "verification", result);
+    const noiseFiles = await toPacketFiles(noiseRisk.slice(0, Math.min(maxNoiseRiskFiles, config.pipeline.maxCandidates)), snippetBudget, "noise", result);
+    // Chunk scoring (15E, report-only)
+    const allFilePaths = [
+        ...primaryFiles.map((f) => f.relativePath),
+        ...readOnlyFiles.map((f) => f.relativePath),
+    ];
+    const topChunks = (0, workspaceIndex_1.scoreChunksForTask)(allFilePaths, result.profile, workspaceRoot, { maxChunksPerFile: 3, maxTotalChunks: 30 });
+    const chunksByFile = new Map();
+    for (const tc of topChunks) {
+        const existing = chunksByFile.get(tc.filePath) || [];
+        existing.push(tc);
+        chunksByFile.set(tc.filePath, existing);
+    }
+    // Attach top chunks to packet files
+    const attachChunks = (files) => {
+        for (const f of files) {
+            const matches = chunksByFile.get(f.relativePath);
+            if (matches && matches.length > 0)
+                f.topChunks = matches.slice(0, 3);
+        }
+    };
+    attachChunks(primaryFiles);
+    attachChunks(readOnlyFiles);
     return {
         userTask: result.task,
+        taskShape: result.profile.taskShape,
         problemHypothesis: buildHypothesis(result, groups),
         candidateFlow: buildCandidateFlow(coverageGroups, result),
-        primaryEditCandidates: await toPacketFiles(primaryEditCandidates.slice(0, Math.min(maxPrimaryEditFiles, config.pipeline.maxCandidates)), snippetBudget, "primary"),
-        readOnlyContext: await toPacketFiles(readOnlyContext.slice(0, Math.min(maxReadOnlyFiles, config.pipeline.maxCandidates)), snippetBudget, "context"),
-        verificationTargets: await toPacketFiles(verificationTargets.slice(0, Math.min(maxVerificationFiles, config.pipeline.maxCandidates)), snippetBudget, "verification"),
-        noiseRisk: await toPacketFiles(noiseRisk.slice(0, Math.min(maxNoiseRiskFiles, config.pipeline.maxCandidates)), snippetBudget, "noise"),
-        missingLinks: detectMissingLinks(groups, result),
-        agentInstructions: defaultAgentInstructions(result)
+        primaryEditCandidates: primaryFiles,
+        readOnlyContext: readOnlyFiles,
+        verificationTargets: verificationFiles,
+        noiseRisk: noiseFiles,
+        missingLinks: detectMissingLinks(coverageGroups, result),
+        verificationCommands: suggestVerificationCommands(result),
+        retrievalTrace: buildRetrievalTrace(groups),
+        tokenBudgetWarning: snippetBudget.remainingChars <= 0 ? "Solve Packet snippet budget exhausted; inspect listed files directly before editing." : undefined,
+        agentInstructions: defaultAgentInstructions(result),
+        semanticDiagnostic: buildSemanticDiagnostic(result.stats, config),
+        firstThreeFiles: buildFirstThree(primaryEditCandidates, readOnlyContext, verificationTargets, noiseRisk, groups, result),
+        whyTheseFiles: buildWhyTheseFiles(result, groups),
+        doNotEditYet: buildDoNotEditYet(readOnlyContext, noiseRisk, coverageGroups, result),
+        // Chunk-assisted evidence
+        chunkAssistedMode: "file_level_current",
+        topChunksSummary: topChunks.slice(0, 15),
+        // RRF fusion trace (report-only)
+        rrfComparison: (0, fusionTrace_1.computeRrfTrace)(result) ?? undefined,
+        // Role refinement trace (16D-R1)
+        roleRefinementMode: result.stats.roleRefinementMode ?? "off",
+        roleDemotions: result.stats.roleDemotions ?? 0,
+        roleDemotionLog: result.stats.roleDemotionLog ?? [],
     };
 }
+function buildFirstThree(primary, readOnly, verification, noise, allGroups, result) {
+    const isReadOnly = result.profile.taskShape === "investigation" || result.profile.taskShape === "unknown";
+    const editLabel = isReadOnly ? "strongest evidence" : "primary edit candidate";
+    const first = [];
+    const used = new Set();
+    // 1. Top candidate
+    const topEdit = primary.find(g => g.role === "edit_candidate" && !g.contrastContext);
+    if (topEdit) {
+        first.push(`${topEdit.relativePath} — ${editLabel}, score ${topEdit.score.toFixed(0)}, tier ${topEdit.tier}`);
+        used.add(topEdit.relativePath);
+    }
+    // 2. Entry or handler context
+    const ctxCandidate = readOnly.find(g => !used.has(g.relativePath) && (g.slot === "entry" || g.slot === "handler") && !g.contrastContext)
+        ?? allGroups.find(g => !used.has(g.relativePath) && (g.slot === "entry" || g.slot === "handler") && !g.contrastContext);
+    if (ctxCandidate) {
+        const why = ctxCandidate.slot === "entry" ? "route/entry point — confirm change path" : "handler/controller — confirm change surface";
+        first.push(`${ctxCandidate.relativePath} — ${why}, score ${ctxCandidate.score.toFixed(0)}`);
+        used.add(ctxCandidate.relativePath);
+    }
+    // 3. Test, model, or service for verification
+    const verifyCandidate = verification.find(g => !used.has(g.relativePath) && !g.contrastContext)
+        ?? allGroups.find(g => !used.has(g.relativePath) && (g.slot === "tests" || g.slot === "data" || g.slot === "domain") && !g.contrastContext);
+    if (verifyCandidate) {
+        const why = verifyCandidate.slot === "tests" ? "tests/verification — check test coverage"
+            : verifyCandidate.slot === "data" ? "data/model — confirm schema impact"
+                : "service/domain — understand business logic";
+        first.push(`${verifyCandidate.relativePath} — ${why}, score ${verifyCandidate.score.toFixed(0)}`);
+    }
+    // Fallback: fill remaining from primary or read-only
+    const fallback = [...primary, ...readOnly, ...allGroups].filter(g => !used.has(g.relativePath) && !g.contrastContext && !noise.includes(g));
+    while (first.length < 3 && fallback.length > 0) {
+        const g = fallback.shift();
+        if (used.has(g.relativePath))
+            continue;
+        first.push(`${g.relativePath} — supports context, score ${g.score.toFixed(0)}`);
+        used.add(g.relativePath);
+    }
+    return first;
+}
+function buildWhyTheseFiles(result, groups) {
+    const parts = [];
+    const isEdit = !["investigation", "unknown"].includes(result.profile.taskShape);
+    // Task shape and intent
+    parts.push(`Task classified as "${result.profile.taskShape}"${isEdit ? " (edit intended)" : " (read-only investigation)"}, confidence ${(result.profile.intentConfidence * 100).toFixed(0)}%.`);
+    // Exact matches
+    const exactMatches = groups.filter(g => g.units.some(u => u.matchedTerms.length > 0));
+    if (exactMatches.length > 0) {
+        const names = exactMatches.slice(0, 3).map(g => g.relativePath.split("/").pop()).join(", ");
+        parts.push(`${exactMatches.length} file(s) matched task keywords in filename or content (e.g., ${names}).`);
+    }
+    else {
+        parts.push("No lexical keyword matches — files selected by path structure and concept similarity.");
+    }
+    // Flow coverage from retrieval passes
+    const passes = new Set();
+    for (const g of groups.slice(0, 15)) {
+        for (const unit of g.units) {
+            for (const pass of unit.retrievalPasses) {
+                if (pass !== "Seed concepts")
+                    passes.add(pass);
+            }
+        }
+    }
+    if (passes.size > 0) {
+        parts.push(`Candidate flow covers ${passes.size} context slot(s): ${[...passes].slice(0, 6).join(", ")}.`);
+    }
+    // Semantic
+    const s = result.stats.semanticRetrievalStatus;
+    if (s === "active") {
+        const added = result.stats.semanticAddedFileCount ?? 0;
+        const supported = result.stats.semanticSupportedFileCount ?? 0;
+        parts.push(`Semantic retrieval active (${result.stats.semanticProvider || "local"}): ${supported} existing files supported, ${added} new candidate(s) discovered by vector similarity.`);
+    }
+    else if (s === "error_fallback") {
+        parts.push("Semantic retrieval unavailable — deterministic retrieval only.");
+    }
+    // Graph/symbol evidence
+    const graphCount = groups.filter(g => g.units.some(u => (u.graphReasons?.length ?? 0) > 0)).length;
+    const symbolCount = groups.filter(g => g.symbols.length > 0).length;
+    if (graphCount > 0 || symbolCount > 0) {
+        const ev = [];
+        if (graphCount > 0)
+            ev.push(`${graphCount} file(s) with graph/dependency evidence`);
+        if (symbolCount > 0)
+            ev.push(`${symbolCount} file(s) with symbol-name matches`);
+        parts.push(`${ev.join(", ")}.`);
+    }
+    // Noise separation
+    const noiseCount = groups.filter(g => g.contrastContext).length;
+    if (noiseCount > 0) {
+        parts.push(`${noiseCount} file(s) flagged as noise/contrast risk and separated into read-only or noise sections.`);
+    }
+    // Uncertainty
+    if (result.stats.stoppedEarly || result.stats.capped) {
+        const cap = result.stats.capped ? `candidate cap at ${result.stats.maxCandidates}` : "";
+        const early = result.stats.stoppedEarly ? `scan stopped early (${result.stats.stopReason ?? "unknown"})` : "";
+        parts.push(`Uncertainty: ${[cap, early].filter(Boolean).join("; ")}. Lower-ranked files may exist outside scanned window.`);
+    }
+    return parts.join(" ");
+}
+function buildDoNotEditYet(readOnly, noise, allGroups, result) {
+    const items = [];
+    const added = new Set();
+    for (const g of noise.slice(0, 3)) {
+        if (added.has(g.relativePath))
+            continue;
+        added.add(g.relativePath);
+        const reason = g.contrastContext ? "contrast context (matches avoided/previous-behavior terms)"
+            : g.tier === "low" && g.score < 50 ? "low confidence, likely unrelated"
+                : "noise risk — verify relevance before editing";
+        items.push(`${g.relativePath} — ${reason} (score ${g.score.toFixed(0)}, tier ${g.tier})`);
+    }
+    for (const g of readOnly.slice(0, 3)) {
+        if (added.has(g.relativePath))
+            continue;
+        added.add(g.relativePath);
+        const slot = g.slot ? (0, contextBlueprint_1.contextSlotLabel)(g.slot) : "context";
+        const reason = g.slot === "entry" ? "route/entry files — read for change path, edit elsewhere"
+            : g.slot === "ui" ? "UI/template files — read for display context, edit in handler/service"
+                : g.slot === "config" ? "config files — read for settings context, edit in domain files"
+                    : g.role === "read_context" ? `read-only ${slot} context — useful for understanding, not the change surface`
+                        : `read-only ${slot} — confirms context, risky as edit surface without more evidence`;
+        items.push(`${g.relativePath} — ${reason} (score ${g.score.toFixed(0)}, tier ${g.tier})`);
+    }
+    if (items.length === 0) {
+        items.push("All selected files appear relevant and safe for consideration. No files flagged as noise or read-only risk.");
+    }
+    return items;
+}
+function buildSemanticDiagnostic(stats, config) {
+    const s = stats.semanticRetrievalStatus;
+    if (!s || s === "disabled")
+        return "Semantic: disabled — deterministic/no-embedding retrieval only";
+    const provider = stats.semanticProvider || "unknown";
+    if (s === "active") {
+        const embedded = stats.semanticEmbeddedFiles ?? stats.semanticCacheHits ?? "?";
+        const hits = stats.semanticHitCount ?? "?";
+        const added = stats.semanticAddedFileCount ?? "?";
+        const supported = stats.semanticSupportedFileCount ?? "?";
+        const cacheHits = stats.semanticCacheHits ?? "?";
+        const cacheMisses = stats.semanticCacheMisses ?? "?";
+        if (provider === "local") {
+            const dims = config.index.semanticDimensions;
+            const dimStr = dims && dims > 0 ? `, ${dims}d` : "";
+            const cacheStr = (cacheHits !== "?" || cacheMisses !== "?") ? `, cache hits=${cacheHits}, cache misses=${cacheMisses}` : "";
+            return `Semantic: active (local bundled model${dimStr}, embedded=${embedded}${cacheStr}, vector hits=${hits}, semantic candidates=${added}, files with semantic support=${supported})`;
+        }
+        const model = stats.semanticModel || "unknown";
+        return `Semantic: active (${provider}, model=${model}, embedded=${embedded}, vector hits=${hits}, semantic candidates=${added}, files with semantic support=${supported})`;
+    }
+    if (s === "error_fallback") {
+        const err = stats.semanticErrorType || "unknown";
+        const msg = stats.semanticErrorMessage || "";
+        return `Semantic: error_fallback (${provider}, ${err}${msg ? ": " + msg.substring(0, 100) : ""}) — deterministic retrieval used as fallback`;
+    }
+    if (s === "skipped_no_key")
+        return `Semantic: skipped (no API key configured) — deterministic retrieval used`;
+    return `Semantic: ${s}`;
+}
 function renderSolvePacketMarkdown(packet) {
     const lines = [
         "# FlowSeeker Solve Packet",
@@ -85,24 +306,114 @@ function renderSolvePacketMarkdown(packet) {
         "## User Task",
         packet.userTask,
         "",
+        "## Retrieval Mode",
+        packet.semanticDiagnostic || "Semantic: disabled",
+        "",
         "## Problem Hypothesis",
         packet.problemHypothesis
     ];
+    // First 3 files to open
+    if (packet.firstThreeFiles.length > 0) {
+        lines.push("", "## First 3 Files To Open");
+        for (const file of packet.firstThreeFiles) {
+            lines.push(`- ${file}`);
+        }
+        lines.push("");
+    }
+    // Why these files
+    if (packet.whyTheseFiles) {
+        lines.push("", "## Why These Files", packet.whyTheseFiles, "");
+    }
     if (packet.candidateFlow.length > 0) {
-        lines.push("", "## Candidate Flow Coverage");
-        for (const step of packet.candidateFlow) {
-            lines.push(`### ${sectionLabel(step.section)}`, ...step.files.map((file) => `- ${file}`), "");
+        lines.push("", "## Candidate Flow", "Ordered path target: route -> controller -> service/job/export/import -> model/data -> view/template -> test.");
+        for (let i = 0; i < packet.candidateFlow.length; i++) {
+            const step = packet.candidateFlow[i];
+            lines.push(`### ${i + 1}. ${step.label}${step.purpose ? ` — ${step.purpose}` : ""}`);
+            for (const file of step.files) {
+                lines.push(`- ${file}`);
+            }
+            if (step.retrievalTrace && step.retrievalTrace.length > 0) {
+                lines.push(`  Reasons: ${step.retrievalTrace.join("; ")}`);
+            }
+            if (step.hint) {
+                lines.push(`  ${step.hint}`);
+            }
+            lines.push("");
         }
     }
-    lines.push("## Primary Edit Candidates", ...renderPacketFiles(packet.primaryEditCandidates));
-    lines.push("## Read-Only Context", ...renderPacketFiles(packet.readOnlyContext));
-    lines.push("## Tests / Verification", ...renderPacketFiles(packet.verificationTargets));
-    if (packet.noiseRisk.length > 0) {
-        lines.push("## Noise Risk", ...renderPacketFiles(packet.noiseRisk));
+    const isReadOnly = packet.taskShape === "investigation" || packet.taskShape === "unknown";
+    const primaryTitle = isReadOnly ? "## Primary Context Candidates" : "## Primary Edit Candidates";
+    lines.push(primaryTitle, ...renderPacketFiles(packet.primaryEditCandidates, isReadOnly));
+    lines.push("## Read-Only Context", ...renderPacketFiles(packet.readOnlyContext, isReadOnly, "No additional read-only context was selected beyond primary edit candidates and verification targets."));
+    lines.push("## Tests / Verification", ...renderPacketFiles(packet.verificationTargets, isReadOnly, "No concrete test or verification config file was selected. Use Verification Command Hints below for suggested test commands."));
+    lines.push("## Noise Risk", ...renderPacketFiles(packet.noiseRisk, isReadOnly, "No obvious noise-risk files were selected. All ranked candidates passed relevance filters."));
+    if (packet.doNotEditYet.length > 0) {
+        lines.push("## Do Not Edit Yet", ...packet.doNotEditYet.map((item) => `- ${item}`), "");
     }
     if (packet.missingLinks.length > 0) {
         lines.push("## Missing Links", ...packet.missingLinks.map((link) => `- ${link}`), "");
     }
+    if (packet.retrievalTrace.length > 0) {
+        lines.push("## Retrieval Trace", ...packet.retrievalTrace.map((trace) => `- ${trace}`), "");
+    }
+    if (packet.verificationCommands.length > 0) {
+        lines.push("## Verification Command Hints");
+        for (const vc of packet.verificationCommands) {
+            lines.push(`- \`${vc.command}\``);
+            lines.push(`  Evidence: ${vc.evidence} (${vc.confidence}) — ${vc.reason}`);
+        }
+        lines.push("");
+    }
+    // Role Decision Trace (16D-R1)
+    var rMode = packet.roleRefinementMode || "off";
+    var demotions = packet.roleDemotions || 0;
+    var demotionLog = packet.roleDemotionLog || [];
+    lines.push("## Role Decision Trace", "", `Role refinement: ${rMode}` + (rMode !== "conservative" ? " (opt-in conservative available via config pipeline.roleRefinementMode)" : ""), "");
+    // Edit candidates
+    for (var ed = 0; ed < Math.min(packet.primaryEditCandidates.length, 5); ed++) {
+        var f = packet.primaryEditCandidates[ed];
+        var topChunks = f.topChunks || [];
+        var chunkInfo = topChunks.length > 0 ? " chunks=" + topChunks.slice(0, 2).map(function (c) { return c.kind + "@L" + c.startLine; }).join(",") : "";
+        lines.push(`  edit: ${f.relativePath} score=${f.score.toFixed(0)} role=${f.role} tier=${f.tier}${chunkInfo}`);
+    }
+    // Demoted files (conservative mode)
+    if (rMode === "conservative" && demotions > 0) {
+        lines.push("", "  Demoted (not edit targets in conservative mode):");
+        for (var dm = 0; dm < Math.min(demotionLog.length, 5); dm++) {
+            var d = demotionLog[dm];
+            lines.push(`    ${d.beforeRole}→${d.afterRole}: ${d.filePath} rule=${d.ruleId} confidence=${d.confidence} reason="${d.reason}"`);
+        }
+        if (demotionLog.length > 5)
+            lines.push(`    ... and ${demotionLog.length - 5} more demotions`);
+    }
+    // Read-only context
+    if (packet.readOnlyContext.length > 0) {
+        lines.push("", "  Read-only context:");
+        for (var rc = 0; rc < Math.min(packet.readOnlyContext.length, 3); rc++) {
+            var rcf = packet.readOnlyContext[rc];
+            lines.push(`    read: ${rcf.relativePath} role=${rcf.role}`);
+        }
+    }
+    lines.push("");
+    if (rMode !== "conservative") {
+        lines.push("  Caution: role refinement is off/opt-in. AI agents should validate edit candidates before editing.", "");
+    }
+    lines.push(`  Default role decisions are from the current ranker.${packet.primaryEditCandidates.length > 0 ? " Verify relevance of each edit candidate." : ""}`, "");
+    if (packet.tokenBudgetWarning) {
+        lines.push("## Token Budget Warning", packet.tokenBudgetWarning, "");
+    }
+    // RRF Fusion Trace (15G-R1, report-only)
+    if (packet.rrfComparison) {
+        const r = packet.rrfComparison;
+        lines.push("## RRF Fusion Trace", "", `Mode: report-only | Default ranking changed: ${r.defaultRankingChanged} | k: ${r.k}`, `Overlap: @3=${r.overlapAt3}/${Math.min(3, r.currentTopFiles.length, r.rrfTopFiles.length)} @5=${r.overlapAt5}/${Math.min(5, r.currentTopFiles.length, r.rrfTopFiles.length)} @10=${r.overlapAt10}/${Math.min(10, r.currentTopFiles.length, r.rrfTopFiles.length)}`, `Active channels: ${r.channelTraces.filter((c) => c.active).map((c) => c.channel).join(", ") || "none"}`, `Inactive channels: ${r.channelTraces.filter((c) => !c.active).map((c) => c.channel).join(", ") || "none"}`, "", `Current top files (${r.currentTopFiles.length}): ${r.currentTopFiles.slice(0, 8).join(", ")}`, `RRF top files (${r.rrfTopFiles.length}): ${r.rrfTopFiles.slice(0, 8).join(", ")}`, ...(r.promotedByRrf.length > 0 ? [`Promoted by RRF: ${r.promotedByRrf.join(", ")}`] : ["Promoted by RRF: none"]), ...(r.demotedByRrf.length > 0 ? [`Demoted by RRF: ${r.demotedByRrf.join(", ")}`] : ["Demoted by RRF: none"]), "", "Top RRF channel contributions:");
+        for (const entry of r.topRrfEntries.slice(0, 5)) {
+            const contribs = Object.entries(entry.channelContributions)
+                .map(([ch, val]) => `${ch}=${val.toFixed(4)}`)
+                .join(", ");
+            lines.push(`  ${entry.relativePath} rrfScore=${entry.rrfScore.toFixed(4)} [${contribs}]`);
+        }
+        lines.push("");
+    }
     lines.push("## Agent Instructions", ...packet.agentInstructions.map((instruction, index) => `${index + 1}. ${instruction}`), "");
     return lines.join("\n");
 }
@@ -148,40 +459,126 @@ function bestGroupForSlot(groups, slot, selected) {
 }
 function buildCandidateFlow(groups, result) {
     const flow = [];
-    const orderedSlots = (0, contextBlueprint_1.sortSlots)([...result.profile.blueprint.requiredSlots, ...result.profile.blueprint.optionalSlots, "unknown"]);
+    const orderedSlots = ["entry", "handler", "domain", "side_effect", "validation", "data", "ui", "tests"];
+    const isEdit = isEditIntendedTask(result);
+    const required = new Set(result.profile.blueprint.requiredSlots);
+    const optional = new Set(result.profile.blueprint.optionalSlots);
     for (const slot of orderedSlots) {
-        const files = groups.filter((group) => group.slot === slot).map((group) => formatFlowFile(group, result));
-        if (files.length > 0) {
+        if (!required.has(slot) && !optional.has(slot))
+            continue;
+        const slotGroups = groups.filter((group) => group.slot === slot);
+        if (slotGroups.length === 0) {
             flow.push({
                 section: slot,
                 label: sectionLabel(slot),
-                files: files.slice(0, 4)
+                files: [`Missing ${(0, contextBlueprint_1.contextSlotLabel)(slot)} evidence`],
+                purpose: "missing link to verify before relying on packet",
+                hint: `Search hint: ${slotSearchHints(slot, result)}`
             });
+            continue;
         }
+        const files = slotGroups.map((group) => formatFlowFile(group, result));
+        const topGroup = slotGroups[0];
+        const purpose = flowPurpose(slot, isEdit, topGroup);
+        const hint = isEdit && (slot === "entry" || slot === "handler" || slot === "domain") ? "Inspect before editing — confirm this is the correct change surface." : undefined;
+        flow.push({
+            section: slot,
+            label: flowStepLabel(slot),
+            files: files.slice(0, 3),
+            retrievalTrace: slotGroups.flatMap((group) => group.reasons).slice(0, 2),
+            purpose,
+            hint
+        });
     }
     return flow;
 }
-function formatFlowFile(group, result) {
-    const required = (0, contextBlueprint_1.isRequiredSlot)(result.profile, group.slot) ? "required-slot" : "optional";
-    return `${group.relativePath} [${group.role}; ${required}; score ${group.score.toFixed(1)}]`;
+function flowStepLabel(slot) {
+    const labels = {
+        entry: "Route / entry",
+        handler: "Controller / handler",
+        domain: "Service / domain",
+        side_effect: "Job / export / import",
+        validation: "Request / validation",
+        data: "Model / data",
+        ui: "View / template",
+        tests: "Test / verification"
+    };
+    return labels[slot] ?? sectionLabel(slot);
+}
+function flowPurpose(slot, isEdit, group) {
+    const base = slotPurposeLabel(slot);
+    if (isEdit) {
+        if (slot === "entry" || slot === "handler")
+            return `${base}: start here to trace the change path`;
+        if (slot === "domain" || slot === "data")
+            return `${base}: likely change surface`;
+        if (slot === "tests")
+            return `${base}: update after changes`;
+        return `${base}: review for impact`;
+    }
+    return `${base}: read for context`;
 }
-function renderPacketFiles(files) {
+function slotPurposeLabel(slot) {
+    const labels = {
+        entry: "Request entry point",
+        handler: "Request handler / controller",
+        domain: "Business logic / domain",
+        data: "Data model / persistence",
+        validation: "Input validation",
+        permission: "Authorization / permissions",
+        config: "Configuration",
+        side_effect: "Side effects / events",
+        ui: "UI / presentation",
+        tests: "Tests / verification",
+        docs: "Documentation",
+        unknown: "Matched context"
+    };
+    return labels[slot] ?? "Context";
+}
+function formatFlowFile(group, _result) {
+    return `${group.relativePath} [${group.tier}; score ${group.score.toFixed(0)}]`;
+}
+function renderPacketFiles(files, isReadOnly, placeholderText) {
     if (files.length === 0) {
-        return ["- None identified.", ""];
-    }
-    return files.flatMap((file) => [
-        `- ${file.relativePath}`,
-        `  Slot: ${file.slot ? (0, contextBlueprint_1.contextSlotLabel)(file.slot) : "Unknown"}; Role: ${file.role}; Kind: ${file.kind}; Score: ${file.score.toFixed(1)}; Tier: ${file.tier}`,
-        ...(file.contextMode ? [`  Context: ${contextModeLabel(file.contextMode)}${file.contextRange ? `, lines ${file.contextRange.startLine}-${file.contextRange.endLine}` : ""}`] : []),
-        ...(file.reasons.length > 0 ? [`  Reasons: ${file.reasons.join("; ")}`] : []),
-        ...(file.snippet ? ["", "```", file.snippet, "```"] : []),
-        ""
-    ]);
+        return placeholderText ? [`- ${placeholderText}`, ""] : ["- None identified.", ""];
+    }
+    return files.flatMap((file) => {
+        const roleLabel = isReadOnly && file.role === "edit_candidate" ? "context_candidate" : file.role;
+        const connectedLabel = isReadOnly ? "Related context to inspect" : "Read before editing";
+        return [
+            `- ${file.relativePath}`,
+            `  Slot: ${file.slot ? (0, contextBlueprint_1.contextSlotLabel)(file.slot) : "Unknown"}; Role: ${roleLabel}; Kind: ${file.kind}; Score: ${file.score.toFixed(1)}; Tier: ${file.tier}`,
+            ...(file.contextMode ? [`  Context: ${contextModeLabel(file.contextMode)}${file.contextRange ? `, lines ${file.contextRange.startLine}-${file.contextRange.endLine}` : ""}`] : []),
+            ...(file.expectedChangeSurface ? [`  Expected change surface: ${file.expectedChangeSurface}`] : []),
+            ...(file.riskLevel ? [`  Risk: ${file.riskLevel}`] : []),
+            ...(file.connectedContext && file.connectedContext.length > 0 ? [`  ${connectedLabel}: ${file.connectedContext.join(", ")}`] : []),
+            ...(file.retrievalTrace && file.retrievalTrace.length > 0 ? [`  Selected by: ${file.retrievalTrace.join("; ")}`] : []),
+            ...(file.reasons.length > 0 ? [`  Reasons: ${file.reasons.join("; ")}`] : []),
+            ...(file.topChunks && file.topChunks.length > 0 ? renderTopChunks(file.topChunks) : []),
+            ...(file.snippet ? ["", "```", file.snippet, "```"] : []),
+            ""
+        ];
+    });
+}
+function renderTopChunks(chunks) {
+    if (!chunks || chunks.length === 0)
+        return [];
+    const lines = ["  Top Chunks:"];
+    for (const tc of chunks) {
+        const preview = (tc.contentPreview || "").slice(0, 120).replace(/\n/g, "\\n");
+        const symbol = tc.symbolName ? ` symbol=${tc.symbolName}` : "";
+        lines.push(`    L${tc.startLine}-${tc.endLine} ${tc.kind}/${tc.slot} score=${tc.score}${symbol}`);
+        lines.push(`    → ${tc.reasons.join(", ")}`);
+        if (preview)
+            lines.push(`    \`${preview}\``);
+    }
+    return lines;
 }
 function sectionLabel(section) {
     return (0, contextBlueprint_1.contextSlotLabel)(section);
 }
-async function toPacketFiles(groups, budget, purpose) {
+async function toPacketFiles(groups, budget, purpose, result) {
+    const isReadOnly = result.profile.taskShape === "investigation" || result.profile.taskShape === "unknown";
     const files = [];
     for (const [index, group] of groups.entries()) {
         const snippetContext = await buildSnippetContext(group, budget, maxCharsForPurpose(purpose, index));
@@ -192,6 +589,10 @@ async function toPacketFiles(groups, budget, purpose) {
             slot: group.slot,
             contextMode: snippetContext.mode,
             contextRange: snippetContext.range,
+            expectedChangeSurface: isReadOnly ? undefined : expectedChangeSurface(group, purpose),
+            riskLevel: riskLevel(group, purpose),
+            connectedContext: connectedContext(group, groups),
+            retrievalTrace: retrievalTraceForGroup(group),
             score: group.score,
             confidence: group.confidence,
             tier: group.tier,
@@ -201,6 +602,115 @@ async function toPacketFiles(groups, budget, purpose) {
     }
     return files;
 }
+function expectedChangeSurface(group, purpose) {
+    if (purpose !== "primary") {
+        return undefined;
+    }
+    const slot = group.slot ? (0, contextBlueprint_1.contextSlotLabel)(group.slot).toLowerCase() : "matched code";
+    return `Smallest change likely belongs in this ${slot} surface after validating connected context.`;
+}
+function riskLevel(group, purpose) {
+    if (purpose === "noise") {
+        return "high";
+    }
+    if (purpose === "context" || group.contrastContext) {
+        return "medium";
+    }
+    return group.tier === "high" ? "low" : "medium";
+}
+function connectedContext(group, groups) {
+    const groupTrace = new Set(retrievalTraceForGroup(group));
+    return groups
+        .filter((candidate) => candidate.relativePath !== group.relativePath)
+        .filter((candidate) => candidate.subsystem && group.subsystem ? candidate.subsystem === group.subsystem : candidate.slot && candidate.slot !== group.slot)
+        .filter((candidate) => {
+        const trace = retrievalTraceForGroup(candidate);
+        return trace.some((item) => groupTrace.has(item)) || candidate.subsystem === group.subsystem || isAdjacentSlot(group.slot, candidate.slot);
+    })
+        .slice(0, 3)
+        .map((candidate) => candidate.relativePath);
+}
+function isTestAdjacent(group) {
+    const normalized = group.relativePath.replace(/\\/g, "/").toLowerCase();
+    return /\b(test|spec|__tests__|e2e|cypress|playwright)\b/.test(normalized) ||
+        /\b(test|spec)\.(ts|tsx|js|jsx|php|py|rb|go|java)$/.test(normalized);
+}
+function isVerificationHint(group) {
+    const normalized = group.relativePath.replace(/\\/g, "/").toLowerCase();
+    return /\b(composer\.json|package\.json|phpunit\.xml|phpunit\.xml\.dist|jest\.config|vitest\.config|Makefile|docker-compose|\.env\.example)\b/.test(normalized) ||
+        /\.(yml|yaml|toml|xml\.dist)$/.test(normalized);
+}
+function isAdjacentSlot(left, right) {
+    const adjacent = new Set([
+        "entry:handler",
+        "handler:domain",
+        "domain:data",
+        "domain:config",
+        "domain:side_effect",
+        "handler:permission",
+        "ui:handler",
+        "tests:domain",
+        "tests:handler"
+    ]);
+    return adjacent.has(`${left}:${right}`) || adjacent.has(`${right}:${left}`);
+}
+function retrievalTraceForGroup(group) {
+    return group.units
+        .flatMap((unit) => [
+        ...unit.retrievalPasses.map((pass) => `pass:${pass}`),
+        ...(unit.retrievalTrace ?? []),
+        ...(unit.channelHits ?? []).map((hit) => `${hit.channel}:${hit.reason}`),
+        ...(unit.graphReasons ?? []).map((reason) => `graph:${reason}`),
+        ...(unit.frameworkEdgeReason ? [`graph:${unit.frameworkEdgeReason}`] : [])
+    ])
+        .filter((trace, index, traces) => traces.indexOf(trace) === index)
+        .slice(0, 4);
+}
+function buildRetrievalTrace(groups) {
+    return groups
+        .slice(0, 10)
+        .flatMap((group) => retrievalTraceForGroup(group).map((trace) => `${group.relativePath}: ${trace}`))
+        .slice(0, 20);
+}
+function suggestVerificationCommands(result) {
+    const paths = result.units.map((unit) => unit.relativePath.replace(/\\/g, "/"));
+    const commands = [];
+    const added = new Set();
+    function add(cmd, evidence, confidence, reason) {
+        if (added.has(cmd))
+            return;
+        added.add(cmd);
+        commands.push({ command: cmd, evidence, confidence, reason, runnable: true });
+    }
+    const hasComposer = paths.some((p) => p === "composer.json");
+    const hasLaravel = paths.some((p) => p === "artisan" || /(^|\/)(routes|app\/Http|app\/Models|app\/Console|resources\/views)\//.test(p));
+    const hasPHP = hasLaravel || hasComposer || paths.some((p) => p.endsWith(".php"));
+    const hasPackageJson = paths.some((p) => p === "package.json" || p.endsWith("/package.json"));
+    const hasJS = hasPackageJson || paths.some((p) => /(^|\/)src\//.test(p) || /\.(ts|tsx|js|jsx)$/.test(p));
+    const hasPython = paths.some((p) => /(^|\/)tests?\/.*\.py$/.test(p) || p.endsWith(".py"));
+    const hasGo = paths.some((p) => /\.go$/.test(p));
+    if (hasLaravel || hasPHP) {
+        const trigger = paths.find((p) => p.startsWith("routes/")) ?? paths.find((p) => p.endsWith(".php")) ?? "Laravel/PHP files";
+        add("php artisan route:list", trigger, "detected", "Laravel/PHP route context detected; verify route/controller mapping before edits");
+        add("php artisan test", trigger, "detected", "Laravel/PHP app file detected; run framework tests after edits");
+        add("composer test", hasComposer ? "composer.json" : trigger, hasComposer ? "detected" : "inferred", "Run Composer test script when composer.json defines one");
+    }
+    if (hasJS) {
+        const trigger = paths.find((p) => p.endsWith("package.json")) ?? "JS/TS source";
+        add("npm run compile --silent", trigger, hasPackageJson ? "detected" : "inferred", "JavaScript/TypeScript project detected; run type-check before verifying edits");
+        add("npm run test:smoke", trigger, hasPackageJson ? "detected" : "inferred", "JavaScript/TypeScript project detected; run available package test/smoke script");
+    }
+    if (hasPython) {
+        const trigger = paths.find((p) => p.endsWith(".py")) ?? "tests/";
+        add("pytest", trigger, "detected", "Python test file detected; run pytest to verify changes");
+    }
+    if (hasGo) {
+        const trigger = paths.find((p) => /\.go$/.test(p)) ?? "*.go";
+        add("go test ./...", trigger, "detected", "Go source file detected; run Go test suite");
+    }
+    add("Run the smallest focused check for the edited file(s)", "generic fallback", "inferred", "Always run the narrowest available verification if framework commands are absent or too broad");
+    return commands.slice(0, 6);
+}
 function compactSnippet(snippet) {
     if (!snippet) {
         return undefined;
@@ -335,22 +845,125 @@ function isNoiseGroup(group, neededSlots) {
     }
     return false;
 }
+function missingSlotMessage(slot, groups, result, coveredSlots) {
+    const slotLabel = (0, contextBlueprint_1.contextSlotLabel)(slot);
+    const hints = slotSearchHints(slot, result);
+    const currentlyCovered = Array.from(coveredSlots).filter(s => s !== "unknown").map(contextBlueprint_1.contextSlotLabel).join(", ") || "no clear slots";
+    const uncertainty = result.stats.stoppedEarly
+        ? ` Scan stopped early (${result.stats.stopReason ?? "unknown reason"}) — lower-ranked context may exist; do not convert scan-cap uncertainty into a missing-slot claim.`
+        : ` ${capUncertainty(result)}`;
+    return `Missing ${slotLabel} — search hint: ${hints}. Currently covered slots: ${currentlyCovered}.${uncertainty} Pause editing until this slot is found or confirmed not needed.`;
+}
+function slotSearchHints(slot, result) {
+    const concepts = result.profile.concepts.slice(0, 4).join(", ") || result.profile.keywords.slice(0, 4).join(", ") || result.task;
+    const keywords = result.profile.keywords.slice(0, 6).join(" ");
+    const hintMap = {
+        entry: `search paths matching routes, controllers, or entry points near ${concepts}; try "${keywords}" as grep terms`,
+        handler: `search for handler/controller/service files containing ${concepts}; look in src/, app/, or server/ directories`,
+        domain: `search for service/domain/logic files with ${concepts}; check for interfaces, use-cases, or business logic modules`,
+        data: `search for model/entity/schema files related to ${concepts}; check database migrations, ORM models, or API schemas`,
+        validation: `search for validation/request/schema files; try "validate", "sanitize", "schema", or "${concepts}"`,
+        permission: `search for auth/guard/policy files; try "can", "authorize", "policy", "role", or "${concepts}"`,
+        config: `search for config/env/settings files; check .env, config/, or app config for ${concepts}`,
+        side_effect: `search for event/job/mail/queue files; try "dispatch", "emit", "fire", "send", or "${concepts}"`,
+        ui: `search for view/template/component files; check resources/, views/, or components/ for ${concepts}`,
+        tests: `search for test/spec files; try "test", "spec", "it(", "describe(" near ${concepts}`,
+        docs: `search for README/CONTRIBUTING/docs files; check docs/ or project root for ${concepts}`,
+        unknown: `search broadly for ${concepts} across all project files`
+    };
+    return hintMap[slot] || hintMap.unknown;
+}
+function capUncertainty(result) {
+    const stats = result.stats;
+    const parts = [];
+    if (stats.capped)
+        parts.push(`candidate cap hit (ranked=${stats.rankedEvidenceCount}, max=${stats.maxCandidates})`);
+    if (stats.stoppedEarly)
+        parts.push(`scan stopped early (${stats.stopReason ?? "unknown reason"})`);
+    if (stats.candidateFiles && stats.maxCandidates && stats.candidateFiles >= stats.maxCandidates)
+        parts.push(`candidate file cap may hide lower-ranked matches (candidateFiles=${stats.candidateFiles})`);
+    return parts.length > 0 ? parts.join("; ") : "no scan/candidate cap signal reported";
+}
 function detectMissingLinks(groups, result) {
     const missing = [];
-    const foundSlots = new Set(groups.map((group) => group.slot));
+    const isEdit = isEditIntendedTask(result);
+    const coveredSlots = computeCoveredSlots(groups, result);
     for (const slot of result.profile.blueprint.requiredSlots) {
-        if (!foundSlots.has(slot)) {
-            missing.push(`No ${(0, contextBlueprint_1.contextSlotLabel)(slot)} file was identified for this ${result.profile.taskShape} task.`);
+        if (!coveredSlots.has(slot)) {
+            missing.push(missingSlotMessage(slot, groups, result, coveredSlots));
         }
     }
-    if (isEditIntendedTask(result) && !groups.some((group) => group.role === "edit_candidate")) {
-        missing.push("No edit_candidate files were ranked with sufficient confidence. Broaden the search or relax minConfidence.");
+    if (isEdit && !groups.some((group) => group.role === "edit_candidate")) {
+        const topPaths = groups.slice(0, 3).map(g => g.relativePath).join(", ");
+        missing.push(`No edit_candidate files were ranked with sufficient confidence. Try broadening search with additional keywords or lowering minConfidence. Nearest candidates: ${topPaths || "none"}.`);
+    }
+    const uncertainty = capUncertainty(result);
+    const stoppedEarly = result.stats.stoppedEarly;
+    if (missing.length === 0) {
+        const coveredLabels = Array.from(coveredSlots).filter(s => s !== "unknown").map(contextBlueprint_1.contextSlotLabel).join(", ");
+        const allRequired = result.profile.blueprint.requiredSlots.every(s => coveredSlots.has(s));
+        const topFile = groups[0]?.relativePath ?? "top-ranked file";
+        const uncertaintyNote = stoppedEarly
+            ? ` Scan stopped early — lower-ranked context may exist outside the scan window.`
+            : "";
+        const capNote = stoppedEarly
+            ? ` Uncertainty: ${uncertainty}. Before editing, verify: (1) read ${topFile} to confirm it is the correct change surface; (2) check Connected Context on primary candidates for additional files; (3) confirm no test coverage gap exists in Verification Targets.${uncertaintyNote}`
+            : ` Uncertainty: ${uncertainty}. Before editing, verify: (1) read ${topFile} to confirm it is the correct change surface; (2) check Connected Context on primary candidates for additional files; (3) confirm no test coverage gap exists in Verification Targets.`;
+        if (isEdit) {
+            missing.push(`All required context slots covered: ${coveredLabels || "none identified"}. Search hint if context feels thin: inspect adjacent files from Candidate Flow and Connected Context.${capNote}`);
+        }
+        else {
+            missing.push(`All required context slots covered: ${coveredLabels || "none identified"}. Search hint if context feels thin: inspect adjacent files from Candidate Flow and Connected Context. Uncertainty: ${uncertainty}. Verify: read ${topFile} to confirm relevance; cross-check Candidate Flow ordering against your understanding of the codebase.`);
+        }
     }
-    if (result.stats.stoppedEarly) {
-        missing.push(`Scan stopped early: ${result.stats.stopReason ?? "budget limit reached"}. Treat coverage as partial.`);
+    else {
+        if (stoppedEarly) {
+            missing.push(`Scan stopped early (${result.stats.stopReason ?? "unknown reason"}). Lower-ranked context may exist outside the scan window. Do not convert this scan-cap uncertainty into a missing-slot claim — only the slots listed above are verified missing from the scanned evidence.`);
+        }
+    }
+    // Append framework-specific hints when slots are missing and framework hints exist
+    if (missing.length > 0 && result.profile.blueprint.frameworkHints?.length) {
+        for (const hint of result.profile.blueprint.frameworkHints) {
+            missing.push(hint);
+        }
     }
     return missing;
 }
+function computeCoveredSlots(groups, result) {
+    const covered = new Set();
+    // Source 1: group.slot values
+    for (const group of groups) {
+        if (group.slot && group.slot !== "unknown") {
+            covered.add(group.slot);
+        }
+    }
+    // Source 2: retrieval passes — parse "pass:Entry / Routes coverage" patterns
+    const slotLabelToKey = new Map();
+    for (const slot of (0, contextBlueprint_1.allContextSlots)(result.profile.blueprint)) {
+        slotLabelToKey.set((0, contextBlueprint_1.contextSlotLabel)(slot).toLowerCase(), slot);
+    }
+    // Also add abbreviated forms
+    slotLabelToKey.set("seed concepts", "unknown");
+    for (const group of groups) {
+        for (const unit of group.units) {
+            for (const pass of unit.retrievalPasses) {
+                const normalized = pass.toLowerCase().replace(/\s+coverage$/, "").trim();
+                if (slotLabelToKey.has(normalized)) {
+                    covered.add(slotLabelToKey.get(normalized));
+                }
+            }
+        }
+    }
+    // Source 3: evidence units that have a specific slot assigned
+    for (const group of groups) {
+        for (const unit of group.units) {
+            if (unit.slot && unit.slot !== "unknown") {
+                covered.add(unit.slot);
+            }
+        }
+    }
+    return covered;
+}
 function isEditIntendedTask(result) {
     return !["investigation", "unknown"].includes(result.profile.taskShape);
 }