flowseeker 0.1.8 → 0.1.9

package/dist/pipeline/contextBlueprint.js

@@ -9,6 +9,7 @@ exports.isRequiredSlot = isRequiredSlot;
 exports.computeContextCoverage = computeContextCoverage;
 exports.sortSlots = sortSlots;
 const text_1 = require("../utils/text");
+const laravel_1 = require("../framework/laravel");
 const slotOrder = ["entry", "handler", "domain", "data", "validation", "permission", "config", "side_effect", "ui", "tests", "docs", "unknown"];
 const slotTerms = {
     entry: ["route", "routes", "router", "endpoint", "api", "page", "screen", "loader", "action"],
@@ -58,7 +59,7 @@ const taskBlueprints = {
         optionalSlots: ["domain", "data", "validation", "permission", "config", "side_effect", "ui", "tests", "docs"]
     }
 };
-function buildTaskBlueprint(input) {
+async function buildTaskBlueprint(input) {
     const baseShape = input.intent === "unknown" && isReviewLike(input.normalizedTask) ? "investigation" : input.intent;
     const template = taskBlueprints[baseShape];
     const required = new Set(template.requiredSlots);
@@ -67,6 +68,17 @@ function buildTaskBlueprint(input) {
     const normalized = input.normalizedTask;
     promoteSlots(required, optional, detectTargetedSlots(normalized, terms));
     adaptSlotsToTaskSurface(required, optional, normalized, terms);
+    // Apply Laravel template if workspace root is available
+    let frameworkHints;
+    if (input.workspaceRoot) {
+        const laravelResult = await (0, laravel_1.applyLaravelTemplate)(input.workspaceRoot, normalized, Array.from(required));
+        if (laravelResult.detected) {
+            for (const slot of laravelResult.suggestedRequiredSlots) {
+                required.add(slot);
+            }
+            frameworkHints = laravelResult.missingLinkHints;
+        }
+    }
     return {
         shape: baseShape,
         confidence: input.confidence,
@@ -74,7 +86,8 @@ function buildTaskBlueprint(input) {
         negativeTerms: input.negativeTerms ?? [],
         requiredSlots: sortSlots(Array.from(required)),
         optionalSlots: sortSlots(Array.from(optional).filter((slot) => !required.has(slot))),
-        expansionHints: buildExpansionHints(required)
+        expansionHints: buildExpansionHints(required),
+        frameworkHints,
     };
 }
 function slotSearchTerms(slot) {

package/dist/pipeline/fileScanner.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGuardReasons = getGuardReasons;
+exports.clearGuardReasons = clearGuardReasons;
 exports.scanTextFile = scanTextFile;
 exports.getWeightedTerms = getWeightedTerms;
 const path = __importStar(require("path"));
@@ -48,12 +50,20 @@ const MAX_CHUNK_LINES = 120;
 const MAX_SEARCHABLE_LINE_CHARS = 12000;
 const MAX_STRUCTURED_MATCHED_LINES = 80;
 const MAX_STRUCTURED_SCAN_BYTES = 220000;
+const guardReasons = new Map();
+function getGuardReasons() {
+    return guardReasons;
+}
+function clearGuardReasons() {
+    guardReasons.clear();
+}
 function scanTextFile(input) {
     if (input.content.includes("\u0000")) {
         return [];
     }
     const weightedTerms = getWeightedTerms(input.profile);
-    const pathScore = scorePath(input.relativePath, weightedTerms);
+    const slotBoostEnabled = process.env.FLOWSEEKER_ENABLE_SLOT_BOOST !== "0";
+    const pathScore = scorePath(input.relativePath, weightedTerms) + (slotBoostEnabled ? scorePathSlotBoost(input.relativePath, input.profile) : 0);
     const matchedLines = findMatchedLines(input.content, weightedTerms, MAX_MATCHED_LINES_PER_FILE);
     const hasOversizedLine = containsLineLongerThan(input.content, MAX_SEARCHABLE_LINE_CHARS);
     const headContent = input.content.slice(0, 200000);
@@ -155,6 +165,44 @@ function scorePath(relativePath, terms) {
     }
     return score;
 }
+function scorePathSlotBoost(relativePath, profile) {
+    const requiredSlots = profile.blueprint.requiredSlots;
+    if (!requiredSlots || requiredSlots.length === 0)
+        return 0;
+    const fp = relativePath.replace(/\\/g, "/").toLowerCase();
+    const normalizedText = (0, text_1.normalizeText)(relativePath);
+    const keywords = profile.keywords.map(text_1.normalizeText);
+    const slotTerms = {
+        entry: ["route", "routes", "router", "endpoint", "api"],
+        handler: ["controller", "handler", "command"],
+        domain: ["service", "usecase", "repository", "manager", "processor", "store", "hook"],
+        data: ["model", "schema", "migration", "entity", "query", "prisma"],
+        validation: ["request", "validator", "validation", "dto", "formrequest"],
+        permission: ["policy", "permission", "role", "guard", "middleware", "auth"],
+        config: ["config", "env", "setting", "yaml", "json"],
+        side_effect: ["event", "listener", "job", "queue", "mail", "email", "notification", "webhook", "dispatch"],
+        tests: ["test", "spec", "expect", "assert"],
+        ui: ["component", "page", "view", "template", "form"],
+    };
+    let maxBoost = 0;
+    for (const slot of requiredSlots) {
+        const slotKeywords = slotTerms[slot] ?? [];
+        for (const sk of slotKeywords) {
+            if (!fp.includes(sk))
+                continue;
+            // File path matches a required slot keyword — check if it also has task keyword overlap
+            for (const kw of keywords) {
+                if (normalizedText.includes(kw)) {
+                    // File matches both a required slot keyword AND a task keyword — higher boost
+                    maxBoost = Math.max(maxBoost, 12);
+                }
+            }
+            // Pure slot match (no task keyword overlap) gets a smaller boost
+            maxBoost = Math.max(maxBoost, 5);
+        }
+    }
+    return maxBoost;
+}
 function findMatchedLines(content, terms, maxMatches) {
     const lines = content.split(/\r?\n/);
     const matches = new Map();
@@ -275,6 +323,7 @@ function detectKind(relativePath, snippet) {
 function detectRole(kind, score, profile, relativePath, snippet) {
     const normalizedPath = (0, text_1.normalizeText)(relativePath);
     const normalizedSnippet = (0, text_1.normalizeText)(snippet);
+    const fp = relativePath.toLowerCase().replace(/\\/g, "/");
     if (kind === "test") {
         return "test";
     }
@@ -321,6 +370,23 @@ function detectRole(kind, score, profile, relativePath, snippet) {
     if (isFrontendStatePath(normalizedPath) && isPrimaryFlowPath(normalizedPath, normalizedSnippet, profile) && score >= 10) {
         return "edit_candidate";
     }
+    // Must-not guard: demote helper/command/feed/cross-domain files from edit_candidate.
+    // Runs before the runtime-flow check so high-scoring guard-pattern files are intercepted.
+    const mustNotGuardEnabled = process.env.FLOWSEEKER_ENABLE_MUST_NOT_GUARD !== "0";
+    if (mustNotGuardEnabled && score >= 5) {
+        const taskMentionsCmd = /\b(command|console|cli|cron|artisan)\b/.test(profile.normalizedTask || "");
+        const isCommand = /\b(console\/commands?|commands?\/console|management\/commands?)\b/.test(fp) && !taskMentionsCmd;
+        const taskMentionsFeed = /\b(feed|digest|sitemap|seo|rss|atom)\b/.test(profile.normalizedTask || "");
+        const isFeedLike = /\b(feed|digest|sitemap|seo|rss|atom)\b/.test(fp) && !taskMentionsFeed;
+        const isHelper = /\b(helpers?|utils?|vendor)\b/.test(fp) && !/\b(helpers?|utils?|vendor)\b/.test(profile.normalizedTask || "");
+        const taskConceptsLower = profile.concepts.map(c => (0, text_1.normalizeText)(c));
+        const isCrossDomainService = /\bservices?\b/.test(fp) && !taskConceptsLower.some(c => fp.includes(c)) && !/\bservices?\b/.test(profile.normalizedTask || "");
+        if (isHelper || isCommand || isFeedLike || isCrossDomainService) {
+            const cat = isHelper ? "helper_like" : isCommand ? "command_like" : isFeedLike ? "feed_like" : "cross_domain_service_like";
+            guardReasons.set(relativePath, cat);
+            return "read_context";
+        }
+    }
     if (isRuntimeFlowPath(normalizedPath, normalizedSnippet) && isPrimaryFlowPath(normalizedPath, normalizedSnippet, profile) && score >= 10) {
         return "edit_candidate";
     }
@@ -356,6 +422,7 @@ function kindBonus(relativePath, snippet) {
 function pathIntentModifier(relativePath, snippet, profile) {
     const normalizedPath = (0, text_1.normalizeText)(relativePath);
     const normalizedSnippet = (0, text_1.normalizeText)(snippet);
+    const editRecallBoost = process.env.FLOWSEEKER_ENABLE_EDIT_RECALL_BOOST !== "0";
     let modifier = 0;
     const pathTermHits = countTaskTermHits(normalizedPath, profile.concepts);
     const snippetTermHits = countTaskTermHits(normalizedSnippet, profile.concepts);
@@ -371,6 +438,29 @@ function pathIntentModifier(relativePath, snippet, profile) {
     if (entityPathHits > 0) {
         modifier += 28 + Math.min(28, entityPathHits * 10);
     }
+    // Filename keyword hit: task keyword appears as a filename token
+    // Uses token matching so "order" matches "order_controller" but "data" doesn't match "database"
+    const fpSegments = normalizedPath.replace(/\\/g, "/").split("/");
+    const fileName = fpSegments[fpSegments.length - 1] || "";
+    if (editRecallBoost) {
+        const fileTokens = (0, text_1.splitIdentifier)(fileName);
+        const fileNameKeywordWeight = profile.keywords
+            .map(text_1.normalizeText)
+            .filter(k => k.length >= 3 && !genericPathTerms.has(k) && fileTokens.includes(k))
+            .reduce((sum, k) => sum + Math.min(k.length, 12), 0);
+        if (fileNameKeywordWeight > 0 && !isGenericUtilityPath(normalizedPath) && !isConfigPath(normalizedPath)) {
+            modifier += 22 + Math.min(38, fileNameKeywordWeight * 5);
+        }
+        // Directory segment keyword match: directory names matching task keywords
+        // Gives a small domain signal boost (e.g. "auth/" dir matching "auth" keyword)
+        const commonDirs = new Set(["src", "app", "lib", "test", "tests", "dist", "build", "node_modules", "public", "assets"]);
+        const dirSegments = fpSegments.slice(0, -1);
+        const dirKeywords = profile.keywords.map(text_1.normalizeText).filter(k => k.length >= 3 && !genericPathTerms.has(k));
+        const dirKeywordHits = dirSegments.filter(s => s.length >= 3 && !commonDirs.has(s) && dirKeywords.some(k => s.includes(k))).length;
+        if (dirKeywordHits > 0 && !isConfigPath(normalizedPath)) {
+            modifier += 5 + Math.min(15, dirKeywordHits * 5);
+        }
+    }
     if (taskTargetsUi(profile) && isUiSurfacePath(normalizedPath)) {
         const focusedSnippetHits = countTaskTermHits(normalizedSnippet, focusedPathTerms(profile));
         modifier += 8;
@@ -405,6 +495,31 @@ function pathIntentModifier(relativePath, snippet, profile) {
             }
         }
     }
+    // Framework convention boost: penalize common/shared paths for auth/security tasks
+    // to prefer framework-local paths (src/auth/, app/Auth/) over generic (src/common/)
+    var frameworkConvBoostEnabled = process.env.FLOWSEEKER_ENABLE_FRAMEWORK_CONVENTION_BOOST !== "0";
+    if (frameworkConvBoostEnabled) {
+        var isAuthTask = /\b(auth|jwt|token|authentication|login|permission|guard|strategy|policy)\b/i.test(profile.normalizedTask || "");
+        var isCommonOrSharedPath = /(^|\/)(common|shared)(\/|$)/.test(relativePath.toLowerCase().replace(/\\/g, "/"));
+        if (isAuthTask && isCommonOrSharedPath) {
+            modifier -= 12;
+        }
+    }
+    // Role intent boost: penalize files whose role conflicts with task intent
+    // e.g. event handlers demoted for endpoint tasks, consumers demoted for notify tasks
+    var roleIntentEnabled = process.env.FLOWSEEKER_ENABLE_ROLE_INTENT_BOOST !== "0";
+    if (roleIntentEnabled) {
+        var taskLower = profile.normalizedTask || "";
+        var isEndpointTask = /\b(endpoint|route|api|controller|request handler)\b/i.test(taskLower);
+        var isNotifyTask = /\b(notification|email|alert|send|notify|approved)\b/i.test(taskLower);
+        var fpForward = relativePath.toLowerCase().replace(/\\/g, "/");
+        var isEventHandler = /\bevents?\//.test(fpForward) && /\.(handler|listener)\./.test(fpForward);
+        var isConsumer = /\bconsumer\b/.test(fpForward);
+        if (isEndpointTask && isEventHandler)
+            modifier -= 10;
+        if (isNotifyTask && isConsumer)
+            modifier -= 10;
+    }
     if (isFrontendStatePath(normalizedPath) && focusedPathHits > 0) {
         modifier += 18 + Math.min(24, focusedPathHits * 8);
     }

package/dist/pipeline/fusionTrace.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RRF_CHANNELS = void 0;
+exports.computeRrfTrace = computeRrfTrace;
+// ── Channel definitions ──────────────────────────────────────────────────────
+exports.RRF_CHANNELS = [
+    "lexical",
+    "path",
+    "filename",
+    "symbol",
+    "chunk",
+    "graph",
+    "framework_slot",
+    "semantic",
+    "test_adjacency",
+    "avoid_terms",
+    "noise_penalty",
+];
+const RRF_K = 60;
+// Map evidence channel hits to RRF channels
+function mapToRrfChannel(channel) {
+    const m = {
+        lexical_content: "lexical",
+        exact_literal: "lexical",
+        path: "path",
+        symbol: "symbol",
+        graph: "graph",
+        dependency: "graph",
+        semantic_vector: "semantic",
+        editor_context: "test_adjacency",
+    };
+    return m[channel] ?? null;
+}
+function computeRrfTrace(result) {
+    const units = result.units;
+    if (units.length === 0)
+        return null;
+    // Collect channel hits from all units
+    const channelHits = new Map();
+    for (const unit of units) {
+        const hits = unit.channelHits ?? [];
+        for (const hit of hits) {
+            const rrfCh = mapToRrfChannel(hit.channel);
+            if (!rrfCh)
+                continue;
+            const existing = channelHits.get(rrfCh) ?? [];
+            existing.push(hit);
+            channelHits.set(rrfCh, existing);
+        }
+    }
+    // Build per-channel rankings (by score, then rank)
+    const channelRankings = new Map();
+    for (const ch of exports.RRF_CHANNELS) {
+        const hits = channelHits.get(ch) ?? [];
+        const sorted = [...hits].sort((a, b) => (b.score - a.score) || ((a.rank ?? 99) - (b.rank ?? 99)));
+        const rankMap = new Map();
+        let rank = 1;
+        for (const hit of sorted) {
+            if (!rankMap.has(hit.relativePath)) {
+                rankMap.set(hit.relativePath, rank++);
+            }
+        }
+        channelRankings.set(ch, rankMap);
+    }
+    // Compute RRF scores per file
+    const fileScores = new Map();
+    for (const ch of exports.RRF_CHANNELS) {
+        const chWeight = channelWeight(ch);
+        const ranking = channelRankings.get(ch);
+        if (!ranking || ranking.size === 0)
+            continue;
+        for (const [path, rank] of ranking) {
+            const contribution = chWeight / (RRF_K + rank);
+            const existing = fileScores.get(path) ?? { score: 0, contributions: {} };
+            existing.score += contribution;
+            existing.contributions[ch] = contribution;
+            fileScores.set(path, existing);
+        }
+    }
+    // Build RRF-sorted file list
+    const rrfEntries = [];
+    for (const [path, data] of fileScores) {
+        // Find original rank from unit ordering
+        const origIdx = units.findIndex((u) => u.relativePath === path);
+        rrfEntries.push({
+            relativePath: path,
+            rrfScore: data.score,
+            channelContributions: data.contributions,
+            originalRank: origIdx >= 0 ? origIdx + 1 : 99,
+        });
+    }
+    rrfEntries.sort((a, b) => b.rrfScore - a.rrfScore);
+    // Current ranking (from unit ordering)
+    const seenPaths = new Set();
+    const currentTopFiles = [];
+    for (const unit of units) {
+        if (!seenPaths.has(unit.relativePath)) {
+            seenPaths.add(unit.relativePath);
+            currentTopFiles.push(unit.relativePath);
+        }
+    }
+    const rrfTopFiles = rrfEntries.map((e) => e.relativePath);
+    // Overlap computation
+    const overlapAt = (k) => {
+        const curSet = new Set(currentTopFiles.slice(0, k));
+        return rrfTopFiles.slice(0, k).filter((f) => curSet.has(f)).length;
+    };
+    // Promoted/demoted
+    const curTop10 = new Set(currentTopFiles.slice(0, 10));
+    const rrfTop10 = new Set(rrfTopFiles.slice(0, 10));
+    const promotedByRrf = rrfTopFiles.slice(0, 10).filter((f) => !curTop10.has(f));
+    const demotedByRrf = currentTopFiles.slice(0, 10).filter((f) => !rrfTop10.has(f));
+    // Channel traces
+    const channelTraces = exports.RRF_CHANNELS.map((ch) => ({
+        channel: ch,
+        active: (channelHits.get(ch)?.length ?? 0) > 0,
+        candidates: channelHits.get(ch)?.length ?? 0,
+    }));
+    return {
+        enabled: true,
+        k: RRF_K,
+        currentTopFiles,
+        rrfTopFiles,
+        overlapAt3: overlapAt(3),
+        overlapAt5: overlapAt(5),
+        overlapAt10: overlapAt(10),
+        promotedByRrf,
+        demotedByRrf,
+        defaultRankingChanged: false, // RRF is report-only
+        channelTraces,
+        topRrfEntries: rrfEntries.slice(0, 10),
+    };
+}
+function channelWeight(ch) {
+    const weights = {
+        lexical: 1.0,
+        path: 0.8,
+        symbol: 1.0,
+        chunk: 0.7,
+        graph: 0.9,
+        framework_slot: 0.6,
+        semantic: 0.5,
+        test_adjacency: 0.4,
+        avoid_terms: -0.3,
+        noise_penalty: -0.5,
+    };
+    return weights[ch] ?? 0.5;
+}
+//# sourceMappingURL=fusionTrace.js.map

package/dist/pipeline/nodeScan.js

@@ -138,7 +138,12 @@ async function nodeScanWorkspace(workspacePath, profile, config, options = {}) {
             semanticFallbackUsed: discovery.semanticRetrievalStatus === "error_fallback",
             deepCandidateDiscoveryCandidates: discovery.deepCandidateDiscoveryCandidates ?? 0,
             deepCandidateDiscoveryAdded: discovery.deepCandidateDiscoveryAdded ?? 0,
-            deepCandidateDiscoveryAvoidBlocked: discovery.deepCandidateDiscoveryAvoidBlocked ?? 0
+            deepCandidateDiscoveryAvoidBlocked: discovery.deepCandidateDiscoveryAvoidBlocked ?? 0,
+            // Chunk stats (15D)
+            totalChunks: discovery.totalChunks ?? 0,
+            chunksByKind: discovery.chunksByKind ?? {},
+            filesWithChunks: discovery.filesWithChunks ?? 0,
+            parserKindCounts: discovery.parserKindCounts ?? {},
         }
     };
 }
@@ -174,6 +179,7 @@ async function discoverScanFiles(rootPath, profile, config, startedAt, options)
     const files = candidates.length > 0
         ? candidates
         : fallbackIndexCandidates(rootPath, indexed.index.files, config.index.maxIndexedCandidateFiles);
+    const chunkStats = (0, workspaceIndex_1.computeChunkStats)(indexed.index);
     return {
         files,
         stopReason: indexed.stopReason,
@@ -199,7 +205,12 @@ async function discoverScanFiles(rootPath, profile, config, startedAt, options)
         semanticSupportedFileCount: selection.semanticSupportedFileCount ?? 0,
         deepCandidateDiscoveryCandidates: deepCands,
         deepCandidateDiscoveryAdded: deepAdded,
-        deepCandidateDiscoveryAvoidBlocked: deepBlocked
+        deepCandidateDiscoveryAvoidBlocked: deepBlocked,
+        // Chunk stats (15D)
+        totalChunks: chunkStats.totalChunks,
+        chunksByKind: chunkStats.chunksByKind,
+        filesWithChunks: chunkStats.filesWithChunks,
+        parserKindCounts: chunkStats.parserKindCounts,
     };
 }
 function fallbackIndexCandidates(rootPath, files, maxFiles) {

package/dist/pipeline/roleRefinement.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyRoleRefinement = applyRoleRefinement;
+function applyRoleRefinement(units, profile, config) {
+    const mode = config.pipeline.roleRefinementMode ?? "off";
+    if (mode !== "conservative")
+        return { units, demotions: [] };
+    const taskLower = profile.normalizedTask || "";
+    const taskShape = profile.taskShape || "unknown";
+    const taskExplicitlyTargetsTests = /\b(test|spec|verify|assert)\b/i.test(taskLower);
+    const taskTargetsRouteConfig = /\b(route|router|endpoint|url|config|env|setting)\b/i.test(taskLower);
+    const taskTargetsViewUI = /\b(view|page|layout|render|blade|template|ui|frontend|modal|component)\b/i.test(taskLower);
+    const taskNeedsSideEffects = /\b(job|queue|event|listener|notify|notification|email|mail|dispatch|async|webhook|cron|command|console)\b/i.test(taskLower);
+    const taskNamedFiles = extractNamedFiles(taskLower);
+    const demotions = [];
+    const refined = units.map((unit) => {
+        if (unit.role !== "edit_candidate")
+            return unit;
+        const fp = (unit.relativePath || "").toLowerCase().replace(/\\/g, "/");
+        const taskMentionsFile = taskNamedFiles.some((n) => fp.includes(n));
+        // Rule 1: tests/specs → test
+        if (!taskExplicitlyTargetsTests && /(^|\/)(tests?|specs?|__tests__)(\/|$)/.test(fp)) {
+            demotions.push({ filePath: unit.relativePath, beforeRole: "edit_candidate", afterRole: "test", reason: "test path demoted — task does not target tests", ruleId: "demote_test", confidence: "high", taskShape });
+            return { ...unit, role: "test" };
+        }
+        // Rule 2: routes/config/views → read_context
+        if (!taskTargetsRouteConfig && /(^|\/)(routes?|router|config)(\/|$)/.test(fp)) {
+            demotions.push({ filePath: unit.relativePath, beforeRole: "edit_candidate", afterRole: "read_context", reason: "route/config demoted to read_context — task does not target routing/config", ruleId: "demote_route_config", confidence: "high", taskShape });
+            return { ...unit, role: "read_context" };
+        }
+        if (!taskTargetsViewUI && /(^|\/)resources\/views(\/|$)/.test(fp)) {
+            demotions.push({ filePath: unit.relativePath, beforeRole: "edit_candidate", afterRole: "read_context", reason: "view demoted to read_context — task does not target UI/view", ruleId: "demote_view", confidence: "high", taskShape });
+            return { ...unit, role: "read_context" };
+        }
+        // Rule 3: helpers/utilities → read_context
+        if (!taskMentionsFile && /(^|\/)(helpers?|utils?)(\/|$)/i.test(fp)) {
+            demotions.push({ filePath: unit.relativePath, beforeRole: "edit_candidate", afterRole: "read_context", reason: "helper/utility demoted to read_context — not directly named by task", ruleId: "demote_helper", confidence: "medium", taskShape });
+            return { ...unit, role: "read_context" };
+        }
+        // Rule 4: side effects → read_context unless task needs them (includes Console/Commands)
+        if (!taskNeedsSideEffects && /(^|\/)(Jobs|Events|Listeners|Mail|Notifications|Console\/Commands)(\/|$)/i.test(fp)) {
+            demotions.push({ filePath: unit.relativePath, beforeRole: "edit_candidate", afterRole: "read_context", reason: "side_effect file demoted to read_context — task does not need side effects", ruleId: "demote_side_effect", confidence: "high", taskShape });
+            return { ...unit, role: "read_context" };
+        }
+        // Rule 5: contrast/avoid → read_context
+        if (unit.contrastContext || unit.taskAvoidGuardFlag === "demoted" || unit.taskAvoidGuardFlag === "blocked_slot") {
+            demotions.push({ filePath: unit.relativePath, beforeRole: "edit_candidate", afterRole: "read_context", reason: "contrast/avoid file demoted — flagged by guard", ruleId: "demote_contrast_avoid", confidence: "high", taskShape });
+            return { ...unit, role: "read_context" };
+        }
+        return unit;
+    });
+    return { units: refined, demotions };
+}
+function extractNamedFiles(taskLower) {
+    const names = [];
+    const m = taskLower.match(/['"]?([\w./-]+\.(?:php|ts|js|py|java|rb|go|cs|kt|rs|dart))['"]?/g);
+    if (m)
+        for (const n of m)
+            names.push(n.replace(/['"]/g, "").toLowerCase());
+    return names;
+}
+//# sourceMappingURL=roleRefinement.js.map

package/dist/pipeline/runHeadless.js

@@ -7,14 +7,16 @@ const evidenceGraph_1 = require("./evidenceGraph");
 const contextBlueprint_1 = require("./contextBlueprint");
 const nodeScan_1 = require("./nodeScan");
 const ranker_1 = require("./ranker");
+const roleRefinement_1 = require("./roleRefinement");
 const solvePacket_1 = require("./solvePacket");
 const taskUnderstanding_1 = require("./taskUnderstanding");
 const tokenSavings_1 = require("./tokenSavings");
+const semanticChunkIndex_1 = require("../index/semanticChunkIndex");
 async function runFlowSeekerHeadless(workspacePath, task, config, options = {}) {
     const log = (stage, detail) => options.onStage?.(stage, detail);
     log("task", task);
     const tTaskStart = performance.now();
-    const profile = (0, taskUnderstanding_1.understandTask)(task, config);
+    const profile = await (0, taskUnderstanding_1.understandTask)(task, config, workspacePath);
     const taskDurationMs = Math.round(performance.now() - tTaskStart);
     log("scan", `${profile.intent} | ${profile.keywords.length} keywords`);
     const tScanStart = performance.now();
@@ -47,27 +49,45 @@ async function runFlowSeekerHeadless(workspacePath, task, config, options = {})
     const tRank2Start = performance.now();
     const finalUnits = (0, ranker_1.rankEvidence)(graphBoosted, config, profile);
     const rankFinalPassDurationMs = Math.round(performance.now() - tRank2Start);
+    // Conservative role demotion (16B, config-gated, default off)
+    const refinement = (0, roleRefinement_1.applyRoleRefinement)(finalUnits, profile, config);
+    const refinedUnits = refinement.units;
     const tCtxStart = performance.now();
-    const contextPack = (0, contextPack_1.createContextPack)(task, finalUnits, config);
+    const contextPack = (0, contextPack_1.createContextPack)(task, refinedUnits, config);
     const contextPackDurationMs = Math.round(performance.now() - tCtxStart);
     const result = {
         task,
         profile,
-        units: finalUnits,
+        units: refinedUnits,
         contextPack,
         stats: {
             ...scan.stats,
             rankedEvidenceCount: finalUnits.length,
             maxCandidates: config.pipeline.maxCandidates,
-            capped: scan.stats.rawEvidenceCount > finalUnits.length
+            capped: scan.stats.rawEvidenceCount > finalUnits.length,
+            // Role refinement telemetry (16B/16D-R1) — needed before buildSolvePacket
+            roleRefinementMode: config.pipeline.roleRefinementMode ?? "off",
+            roleDemotions: refinement.demotions.length,
+            roleDemotionLog: refinement.demotions.slice(0, 100),
         }
     };
     const tSolveStart = performance.now();
-    result.solvePacket = await (0, solvePacket_1.buildSolvePacket)(result, config);
+    result.solvePacket = await (0, solvePacket_1.buildSolvePacket)(result, config, workspacePath);
     const solvePacketDurationMs = Math.round(performance.now() - tSolveStart);
     const tPostStart = performance.now();
     result.contextCoverage = (0, contextBlueprint_1.computeContextCoverage)(profile, finalUnits);
     result.tokenSavings = (0, tokenSavings_1.computeTokenSavings)(result);
+    // Semantic chunk diagnostics (18A — report-only, disabled by default)
+    result.stats = {
+        ...result.stats,
+        semanticChunkDiagnostic: (0, semanticChunkIndex_1.buildSemanticChunkDiagnostic)(config, {
+            chunksConsidered: 0, cacheHits: 0, cacheMisses: 0,
+            candidatesFound: 0, candidatesAccepted: 0, candidatesRejected: 0,
+            topK: 0, providerReady: false,
+            contributionReport: (0, semanticChunkIndex_1.buildContributionReport)(false, false, 0, 0),
+            hybridPromotionReport: (0, semanticChunkIndex_1.buildHybridPromotionReport)(false, false, [], [], []),
+        }),
+    };
     const postProcessDurationMs = Math.round(performance.now() - tPostStart);
     const totalDurationMs = taskDurationMs + scanLoopDurationMs + rankFirstPassDurationMs + graphBuildDurationMs + frameworkExpansionDurationMs + graphBoostDurationMs + rankFinalPassDurationMs + contextPackDurationMs + solvePacketDurationMs + postProcessDurationMs;
     result.stats = {

package/dist/pipeline/runPipeline.js

@@ -47,7 +47,7 @@ const tokenSavings_1 = require("./tokenSavings");
 const universalScan_1 = require("./universalScan");
 async function runFlowSeeker(task, options = {}) {
     const config = await (0, loadConfig_1.loadConfig)();
-    const profile = (0, taskUnderstanding_1.understandTask)(task, config);
+    const profile = await (0, taskUnderstanding_1.understandTask)(task, config, process.cwd());
     // Collect editor context for ranking bias (only in VS Code; null in headless).
     const editorContext = options.editorContext ?? collectEditorContext();
     options.progress?.report({ message: `Scanning workspace for "${task.slice(0, 60)}..."` });
@@ -85,7 +85,7 @@ async function runFlowSeeker(task, options = {}) {
             capped: scan.stats.rawEvidenceCount > finalUnits.length
         }
     };
-    result.solvePacket = await (0, solvePacket_1.buildSolvePacket)(result, config);
+    result.solvePacket = await (0, solvePacket_1.buildSolvePacket)(result, config, process.cwd());
     result.contextCoverage = (0, contextBlueprint_1.computeContextCoverage)(profile, finalUnits);
     result.tokenSavings = (0, tokenSavings_1.computeTokenSavings)(result);
     return result;