@codeledger/selector 0.1.1 → 0.2.0

package/dist/blast-radius.d.ts

@@ -0,0 +1,7 @@
+import type { BlastRadiusEntry, BundleFile, DepGraph, TestMapping } from '@codeledger/types';
+/**
+ * Compute blast radius for each non-stub, non-exemplar file in the bundle.
+ * Returns entries sorted by total impact (direct + transitive count).
+ */
+export declare function computeBlastRadius(files: BundleFile[], depGraph: DepGraph, testMap: TestMapping[]): BlastRadiusEntry[];
+//# sourceMappingURL=blast-radius.d.ts.map

package/dist/blast-radius.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blast-radius.d.ts","sourceRoot":"","sources":["../src/blast-radius.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAqB7F;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,UAAU,EAAE,EACnB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,WAAW,EAAE,GACrB,gBAAgB,EAAE,CAgEpB"}

package/dist/blast-radius.js

@@ -0,0 +1,105 @@
+/**
+ * Blast Radius Annotation
+ *
+ * For each selected file in the bundle, computes the set of files that would
+ * be affected if that file changes:
+ *   - Direct dependents (files that import it)
+ *   - Transitive dependents (full dependency chain up to a configurable depth)
+ *   - Impacted tests (test files mapped to affected source files)
+ *
+ * This is a safety annotation — it helps agents understand the ripple effects
+ * of their changes without altering the scoring algorithm.
+ */
+/** Maximum depth for transitive dependent traversal */
+const MAX_TRANSITIVE_DEPTH = 3;
+/** Maximum number of transitive dependents to track per file */
+const MAX_TRANSITIVE_PER_FILE = 20;
+/**
+ * Compute blast radius for each non-stub, non-exemplar file in the bundle.
+ * Returns entries sorted by total impact (direct + transitive count).
+ */
+export function computeBlastRadius(files, depGraph, testMap) {
+    const entries = [];
+    const selectedPaths = new Set(files.map((f) => f.path));
+    // Build reverse test map: source_file → test_files
+    const sourceToTests = new Map();
+    for (const mapping of testMap) {
+        const tests = sourceToTests.get(mapping.source_file) ?? [];
+        tests.push(mapping.test_file);
+        sourceToTests.set(mapping.source_file, tests);
+    }
+    for (const file of files) {
+        if (file.is_stub || file.is_exemplar)
+            continue;
+        const directDeps = (depGraph.dependents[file.path] ?? [])
+            .filter((d) => !selectedPaths.has(d));
+        const transitiveDeps = computeTransitiveDependents(file.path, depGraph, selectedPaths);
+        // Impacted tests: tests for the file itself + tests for its direct dependents
+        const impactedTests = new Set();
+        // Tests for this file
+        const ownTests = sourceToTests.get(file.path) ?? [];
+        for (const t of ownTests)
+            impactedTests.add(t);
+        // Tests for direct dependents
+        for (const dep of directDeps) {
+            const depTests = sourceToTests.get(dep) ?? [];
+            for (const t of depTests)
+                impactedTests.add(t);
+        }
+        // Tests for transitive dependents
+        for (const dep of transitiveDeps) {
+            const depTests = sourceToTests.get(dep) ?? [];
+            for (const t of depTests)
+                impactedTests.add(t);
+        }
+        // Only include if there's meaningful blast radius
+        if (directDeps.length === 0 && transitiveDeps.length === 0 && impactedTests.size === 0) {
+            continue;
+        }
+        entries.push({
+            path: file.path,
+            direct_dependents: directDeps,
+            transitive_dependents: transitiveDeps,
+            impacted_tests: [...impactedTests],
+        });
+    }
+    // Sort by total impact descending
+    entries.sort((a, b) => {
+        const aTotal = a.direct_dependents.length + a.transitive_dependents.length + a.impacted_tests.length;
+        const bTotal = b.direct_dependents.length + b.transitive_dependents.length + b.impacted_tests.length;
+        return bTotal - aTotal;
+    });
+    return entries;
+}
+/**
+ * BFS to find transitive dependents up to MAX_TRANSITIVE_DEPTH.
+ * Excludes already-selected files (they're in the bundle, so the agent
+ * will handle them directly).
+ */
+function computeTransitiveDependents(startPath, depGraph, excludePaths) {
+    const visited = new Set([startPath]);
+    const result = [];
+    let frontier = [startPath];
+    for (let depth = 0; depth < MAX_TRANSITIVE_DEPTH; depth++) {
+        const nextFrontier = [];
+        for (const path of frontier) {
+            const deps = depGraph.dependents[path] ?? [];
+            for (const dep of deps) {
+                if (visited.has(dep))
+                    continue;
+                visited.add(dep);
+                if (!excludePaths.has(dep)) {
+                    result.push(dep);
+                    if (result.length >= MAX_TRANSITIVE_PER_FILE)
+                        return result;
+                }
+                nextFrontier.push(dep);
+            }
+        }
+        frontier = nextFrontier;
+        if (frontier.length === 0)
+            break;
+    }
+    return result;
+}
+//# sourceMappingURL=blast-radius.js.map

package/dist/blast-radius.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blast-radius.js","sourceRoot":"","sources":["../src/blast-radius.ts"],"names":[],"mappings":"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"}

package/dist/bundle.d.ts

@@ -9,6 +9,16 @@ export interface BuildBundleOptions {
     ledgerStats?: LedgerStats;
     /** When true, include per-file scoring breakdown in the bundle */
     explain?: boolean;
+    /** Scope restriction: only consider files under these path prefixes */
+    scope?: string[];
+    /** Files changed on the current branch (for work-in-progress scoring boost) */
+    branchChangedFiles?: Set<string>;
+    /** When true, include near-miss files in the bundle output */
+    includeNearMisses?: boolean;
+    /** When true, compute blast radius for each selected file */
+    includeBlastRadius?: boolean;
+    /** When true, sort bundle files by architectural layer instead of score */
+    layerOrder?: boolean;
 }
 export declare function buildBundle(opts: BuildBundleOptions): ContextBundle;
 //# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EAEN,aAAa,EAEb,SAAS,EACT,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAOnE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,aAAa,CAoLnE"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,MAAM,EAEN,aAAa,EAGb,SAAS,EACT,cAAc,EACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAenE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,aAAa,CAiRnE"}

package/dist/bundle.js

@@ -1,18 +1,33 @@
 import { randomUUID } from 'node:crypto';
 import { generateCandidates, tokenizeTask } from './candidates.js';
 import { scoreAllCandidates } from './scorer.js';
-import { shouldStop, estimateTokens } from './stop-rule.js';
+import { shouldStop } from './stop-rule.js';
 import { extractExcerpt } from './excerpt.js';
 import { assessConfidence } from './confidence.js';
 import { generateInterfaceStubs } from './stubs.js';
 import { scanDeprecations } from './deprecation.js';
+import { generateExemplars } from './exemplars.js';
+import { validateBundle } from './validation.js';
+import { computeNearMisses } from './near-miss.js';
+import { computeBlastRadius } from './blast-radius.js';
+import { inferTaskType, applyTaskTypeWeights } from './task-type.js';
+import { sortByLayer } from './layer-ordering.js';
+import { estimateTokensByExtension } from './token-calibration.js';
+import { scanTodos } from './todo-scan.js';
 export function buildBundle(opts) {
-    const { taskText, repoIndex, selectorConfig, budget = selectorConfig.default_budget, sufficiencyThreshold = selectorConfig.sufficiency_threshold, ledgerStats, explain = false, } = opts;
+    const { taskText, repoIndex, selectorConfig, budget = selectorConfig.default_budget, sufficiencyThreshold = selectorConfig.sufficiency_threshold, ledgerStats, explain = false, scope, branchChangedFiles, includeNearMisses = false, includeBlastRadius = false, layerOrder = false, } = opts;
+    // Auto-infer task type and apply weight adjustments
+    const taskType = inferTaskType(taskText);
+    const typeAdjustedWeights = applyTaskTypeWeights(selectorConfig.weights, taskType);
+    // Enable branch_changed weight when branch files are provided
+    const effectiveWeights = branchChangedFiles && branchChangedFiles.size > 0
+        ? { ...typeAdjustedWeights, branch_changed: typeAdjustedWeights.branch_changed ?? 0.15 }
+        : typeAdjustedWeights;
     const keywords = tokenizeTask(taskText);
-    // Step 1: Generate candidates (includes IDF token weights + fan-out)
-    const { candidates: candidateSet, tokenWeights, fanoutFiles } = generateCandidates(taskText, repoIndex, selectorConfig);
-    // Step 2: Score all candidates (with IDF weights + fan-out bonus)
-    const scored = scoreAllCandidates(candidateSet, keywords, repoIndex, selectorConfig.weights, ledgerStats, tokenWeights, fanoutFiles);
+    // Step 1: Generate candidates (includes IDF token weights + fan-out + surfaces)
+    const { candidates: candidateSet, tokenWeights, fanoutFiles, surfaceFiles } = generateCandidates(taskText, repoIndex, selectorConfig, scope);
+    // Step 2: Score all candidates (with IDF weights + fan-out bonus + branch awareness)
+    const scored = scoreAllCandidates(candidateSet, keywords, repoIndex, effectiveWeights, ledgerStats, tokenWeights, fanoutFiles, branchChangedFiles, surfaceFiles);
     // Step 3: Compute max cumulative score for threshold
     const maxCumulative = scored.reduce((sum, f) => sum + Math.max(0, f.score), 0);
     // Step 3.5: Reserve slots for test pairing under tight budgets.
@@ -22,7 +37,9 @@ export function buildBundle(opts) {
     const reservedTestSlots = tightBudget ? 2 : 0;
     const mainBudget = {
         ...budget,
-        max_files: budget.max_files ? budget.max_files - reservedTestSlots : undefined,
+        max_files: budget.max_files
+            ? Math.max(1, budget.max_files - reservedTestSlots)
+            : undefined,
     };
     // Step 4: Iterate with stop rule (using reduced budget to leave test slots)
     const state = {
@@ -38,7 +55,11 @@ export function buildBundle(opts) {
         }
         // Extract excerpt
         const excerpt = extractExcerpt(repoIndex.root, scoredFile.path, keywords, selectorConfig.excerpt_full_file_max_lines, selectorConfig.excerpt_window_lines);
-        const tokenEst = estimateTokens(excerpt.lineCount);
+        // Language-aware token estimation (Feature 17)
+        const fileExt = scoredFile.path.includes('.')
+            ? '.' + scoredFile.path.split('.').pop()
+            : '';
+        const tokenEst = estimateTokensByExtension(excerpt.lineCount, fileExt);
         // Check if adding this file would blow the budget
         if (budget.tokens && state.totalTokens + tokenEst > budget.tokens * 1.1) {
             // Allow 10% overshoot, then stop
@@ -47,6 +68,8 @@ export function buildBundle(opts) {
         }
         // Scan for deprecated API patterns
         const deprecationWarnings = scanDeprecations(excerpt.content, selectorConfig.deprecation_rules);
+        // Scan for TODO/FIXME markers (Feature 14)
+        const todoResult = scanTodos(excerpt.content);
         const bundleFile = {
             path: scoredFile.path,
             score: Math.round(scoredFile.score * 1000) / 1000,
@@ -55,6 +78,7 @@ export function buildBundle(opts) {
             content: excerpt.content,
             token_estimate: tokenEst,
             deprecation_warnings: deprecationWarnings.length > 0 ? deprecationWarnings : undefined,
+            todo_count: todoResult.count > 0 ? todoResult.count : undefined,
         };
         state.files.push(bundleFile);
         state.totalTokens += tokenEst;
@@ -84,7 +108,8 @@ export function buildBundle(opts) {
         if (budget.max_files && state.files.length >= budget.max_files)
             break;
         const excerpt = extractExcerpt(repoIndex.root, testPath, keywords, selectorConfig.excerpt_full_file_max_lines, selectorConfig.excerpt_window_lines);
-        const tokenEst = estimateTokens(excerpt.lineCount);
+        const testExt = testPath.includes('.') ? '.' + testPath.split('.').pop() : '';
+        const tokenEst = estimateTokensByExtension(excerpt.lineCount, testExt);
         if (budget.tokens && state.totalTokens + tokenEst > budget.tokens * 1.1)
             continue;
         // Find the scored entry if it exists, otherwise create a minimal one
@@ -115,6 +140,51 @@ export function buildBundle(opts) {
     }
     // Step 7: Assess bundle confidence
     const confidence = assessConfidence(state.files, state.cumulativeScore, keywords.length);
+    // Step 8: Build file relationship map from dep_graph edges between selected files
+    const allSelectedPaths = new Set(state.files.map((f) => f.path));
+    const fileRelationships = [];
+    for (const filePath of allSelectedPaths) {
+        const imports = repoIndex.dep_graph.imports[filePath] ?? [];
+        for (const imp of imports) {
+            if (allSelectedPaths.has(imp)) {
+                fileRelationships.push({ from: filePath, to: imp });
+            }
+        }
+    }
+    // Step 9: Pattern exemplars — include structural siblings for "add new" tasks
+    const exemplarBudget = (budget.tokens ?? Infinity) - state.totalTokens;
+    const maxExemplars = Math.max(0, (budget.max_files ?? 25) - state.files.length);
+    if (maxExemplars > 0 && exemplarBudget > 0) {
+        const exemplars = generateExemplars(repoIndex.root, state.files, repoIndex, keywords, Math.min(maxExemplars, 2), // cap at 2 exemplars
+        Math.min(exemplarBudget, 2000));
+        for (const ex of exemplars) {
+            state.files.push(ex);
+            state.totalTokens += ex.token_estimate;
+        }
+    }
+    // Step 10: Layer ordering — optionally sort files by architectural layer
+    if (layerOrder) {
+        // Separate stubs/exemplars, sort main files by layer, recombine
+        const mainFiles = state.files.filter((f) => !f.is_stub && !f.is_exemplar);
+        const otherFiles = state.files.filter((f) => f.is_stub || f.is_exemplar);
+        const sorted = sortByLayer(mainFiles);
+        state.files = [...sorted, ...otherFiles];
+    }
+    // Step 11: Bundle validation — pre-flight warnings
+    const warnings = validateBundle(state.files, keywords, scored, taskText);
+    // Step 12: Near-miss explanation
+    const nearMisses = includeNearMisses
+        ? (() => {
+            // Build line count map from repo index so near-miss estimation
+            // uses actual line counts (avoids size_penalty cap at 1000 lines).
+            const fileLineCounts = new Map(repoIndex.files.map((f) => [f.path, f.lines]));
+            return computeNearMisses(scored, state.files, state.totalTokens, budget.tokens, undefined, fileLineCounts);
+        })()
+        : undefined;
+    // Step 13: Blast radius annotation
+    const blastRadius = includeBlastRadius
+        ? computeBlastRadius(state.files, repoIndex.dep_graph, repoIndex.test_map)
+        : undefined;
     return {
         bundle_id: `bnd_${randomUUID().slice(0, 12)}`,
         task: taskText,
@@ -126,6 +196,10 @@ export function buildBundle(opts) {
         generated_at: new Date().toISOString(),
         confidence,
         explain: explain ? explainData : undefined,
+        file_relationships: fileRelationships.length > 0 ? fileRelationships : undefined,
+        warnings: warnings.length > 0 ? warnings : undefined,
+        near_misses: nearMisses && nearMisses.length > 0 ? nearMisses : undefined,
+        blast_radius: blastRadius && blastRadius.length > 0 ? blastRadius : undefined,
     };
 }
 //# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/candidates.d.ts

@@ -3,8 +3,19 @@ export interface CandidateResult {
     candidates: Set<string>;
     tokenWeights: Map<string, number>;
     fanoutFiles: Set<string>;
+    /** Files injected via surface-aware auto-inclusion (low-priority, reason: surface_auto_include) */
+    surfaceFiles: Set<string>;
 }
 export declare function tokenizeTask(taskText: string): string[];
+/**
+ * Split a compound task into independent clauses for separate keyword extraction.
+ *
+ * "Fix auth middleware and add payment tests" →
+ *   [["auth", "middleware"], ["payment", "tests"]]
+ *
+ * Falls back to a single clause (identical to tokenizeTask) for simple tasks.
+ */
+export declare function decomposeTask(taskText: string): string[][];
 /**
  * Compute IDF-like token weights based on how many files each keyword matches.
  *
@@ -16,5 +27,5 @@ export declare function tokenizeTask(taskText: string): string[];
  *    "service" appear everywhere and shouldn't dominate scoring.
  */
 export declare function computeTokenWeights(keywords: string[], repoIndex: RepoIndex, hotZoneCount: number): Map<string, number>;
-export declare function generateCandidates(taskText: string, repoIndex: RepoIndex, config: SelectorConfig): CandidateResult;
+export declare function generateCandidates(taskText: string, repoIndex: RepoIndex, config: SelectorConfig, scope?: string[]): CandidateResult;
 //# sourceMappingURL=candidates.d.ts.map

package/dist/candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../src/candidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,SAAS,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAoE7E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAcvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,MAAM,GACnB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCrB;AAyCD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,cAAc,GACrB,eAAe,CAoHjB"}
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../src/candidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAY,SAAS,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAkG7E,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,mGAAmG;IACnG,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAcvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,CAkB1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAAE,EAClB,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,MAAM,GACnB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCrB;AAyCD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,cAAc,EACtB,KAAK,CAAC,EAAE,MAAM,EAAE,GACf,eAAe,CAkMjB"}

package/dist/candidates.js

@@ -57,6 +57,30 @@ const DEFAULT_CONTRACT_PATTERNS = [
 const CONTRACT_PATH_INDICATORS = [
     'openapi', 'swagger', 'schema', 'migrations',
 ];
+/** Keyword sets for surface-aware auto-inclusion */
+const CONFIG_SURFACE_KEYWORDS = new Set([
+    'config', 'configuration', 'script', 'dependency', 'dependencies', 'setup',
+    'package', 'tsconfig', 'eslint', 'prettier', 'webpack', 'vite', 'rollup',
+]);
+const ACCEPTANCE_SURFACE_KEYWORDS = new Set([
+    'test', 'tests', 'testing', 'ci', 'pipeline', 'failing', 'pass', 'coverage',
+    'jest', 'vitest', 'mocha', 'cypress', 'playwright',
+]);
+const CONTRACT_SURFACE_KEYWORDS = new Set([
+    'schema', 'api', 'endpoint', 'migration', 'contract', 'proto', 'graphql',
+    'openapi', 'swagger', 'prisma', 'database',
+]);
+/** Path patterns for surface-aware auto-inclusion */
+const CONFIG_SURFACE_PATTERNS = [
+    'package.json', 'tsconfig', 'pnpm-workspace', '.env.example',
+    'eslint', 'prettier', 'webpack.config', 'vite.config', 'rollup.config',
+];
+const ACCEPTANCE_SURFACE_PATTERNS = [
+    'vitest.config', 'jest.config', '.github/workflows', 'ci.yml', 'ci.yaml',
+    'test-setup', 'test-helper', 'test-utils',
+];
+/** Conjunction / separator patterns for task decomposition */
+const CLAUSE_SPLITTERS = /\b(?:and then|and also|and|then|also|plus)\b|[;,]/i;
 export function tokenizeTask(taskText) {
     const lower = taskText.toLowerCase();
     const isBroadTask = BROAD_TASK_PHRASES.some((re) => re.test(lower));
@@ -69,6 +93,30 @@ export function tokenizeTask(taskText) {
         .filter((w) => w.length > 1 && !effectiveStopWords.has(w));
     return [...new Set(words)];
 }
+/**
+ * Split a compound task into independent clauses for separate keyword extraction.
+ *
+ * "Fix auth middleware and add payment tests" →
+ *   [["auth", "middleware"], ["payment", "tests"]]
+ *
+ * Falls back to a single clause (identical to tokenizeTask) for simple tasks.
+ */
+export function decomposeTask(taskText) {
+    const clauses = taskText.split(CLAUSE_SPLITTERS)
+        .map((c) => c.trim())
+        .filter((c) => c.length > 0);
+    if (clauses.length <= 1) {
+        return [tokenizeTask(taskText)];
+    }
+    const result = [];
+    for (const clause of clauses) {
+        const keywords = tokenizeTask(clause);
+        if (keywords.length > 0) {
+            result.push(keywords);
+        }
+    }
+    return result.length > 0 ? result : [tokenizeTask(taskText)];
+}
 /**
  * Compute IDF-like token weights based on how many files each keyword matches.
  *
@@ -144,24 +192,39 @@ function findStrongTargets(keywords, repoIndex) {
     }
     return targets;
 }
-export function generateCandidates(taskText, repoIndex, config) {
+export function generateCandidates(taskText, repoIndex, config, scope) {
     const candidates = new Set();
     const fanoutFiles = new Set();
-    const keywords = tokenizeTask(taskText);
+    const surfaceFiles = new Set();
+    // Resolve effective scope: CLI flag > config default > no scope
+    const effectiveScope = scope ?? config.default_scope;
+    // Task decomposition: split compound tasks into clauses
+    const clauses = decomposeTask(taskText);
+    // Flat keyword list for IDF + backward compat (union of all clauses)
+    const keywords = [...new Set(clauses.flat())];
     // Compute IDF token weights
     const tokenWeights = computeTokenWeights(keywords, repoIndex, config.hot_zone_count);
-    // 1. Keyword match: file paths + names + content keywords
-    for (const file of repoIndex.files) {
-        const pathLower = file.path.toLowerCase();
-        for (const kw of keywords) {
-            if (pathLower.includes(kw)) {
-                candidates.add(file.path);
-                break;
-            }
-            // Content-aware matching: check identifiers extracted during scanning
-            if (file.content_keywords?.some((ck) => ck === kw || ck === kw + 's' || kw === ck + 's')) {
-                candidates.add(file.path);
-                break;
+    // Build scope-filtered file list
+    const scopedFiles = effectiveScope
+        ? repoIndex.files.filter((f) => effectiveScope.some((s) => f.path.startsWith(s)))
+        : repoIndex.files;
+    // 1. Keyword match: run per-clause to preserve clause-specific file discovery,
+    //    then union the results. A file matching any clause's keywords is included.
+    for (const clauseKeywords of clauses) {
+        for (const file of scopedFiles) {
+            if (candidates.has(file.path))
+                continue;
+            const pathLower = file.path.toLowerCase();
+            for (const kw of clauseKeywords) {
+                if (pathLower.includes(kw)) {
+                    candidates.add(file.path);
+                    break;
+                }
+                // Content-aware matching: check identifiers extracted during scanning
+                if (file.content_keywords?.some((ck) => ck === kw || ck === kw + 's' || kw === ck + 's')) {
+                    candidates.add(file.path);
+                    break;
+                }
             }
         }
     }
@@ -170,18 +233,21 @@ export function generateCandidates(taskText, repoIndex, config) {
     //    because churn-heavy files crowd out task-specific ones. In that case
     //    hot-zone only contributes files that already have a keyword hit.
     const tightMode = (config.default_budget.max_files ?? Infinity) <= 15;
+    const scopedPathSet = new Set(scopedFiles.map((f) => f.path));
     const hotZone = repoIndex.churn.slice(0, config.hot_zone_count);
     for (const churnEntry of hotZone) {
-        if (!repoIndex.files.some((f) => f.path === churnEntry.path))
+        if (!scopedPathSet.has(churnEntry.path))
             continue;
         if (tightMode && !candidates.has(churnEntry.path))
             continue;
         candidates.add(churnEntry.path);
     }
     // 3. Dependency neighborhood: expand from keyword-matched files
+    //    Scope-aware: only add dependencies that fall within the effective scope.
+    const scopedPathSet2 = effectiveScope ? scopedPathSet : undefined;
     const keywordMatched = [...candidates];
     for (const seed of keywordMatched) {
-        expandDependencies(seed, repoIndex, candidates, config.dependency_depth, config.dependency_cap_per_seed);
+        expandDependencies(seed, repoIndex, candidates, config.dependency_depth, config.dependency_cap_per_seed, scopedPathSet2);
     }
     // 4. Fan-out expansion: when task describes a cross-cutting change AND a
     //    strong target file is identified, expand ALL direct dependents (depth=1)
@@ -193,11 +259,13 @@ export function generateCandidates(taskText, repoIndex, config) {
                 break;
             // Depth 1: all direct dependents — always mark as fanout even if
             // already discovered by normal dependency expansion, so they receive
-            // the fan-out scoring bonus.
+            // the fan-out scoring bonus. Scope-aware: skip out-of-scope deps.
             const dependents = repoIndex.dep_graph.dependents[target] ?? [];
             for (const dep of dependents) {
                 if (candidates.size >= FANOUT_CEILING)
                     break;
+                if (scopedPathSet2 && !scopedPathSet2.has(dep))
+                    continue;
                 candidates.add(dep);
                 fanoutFiles.add(dep);
             }
@@ -206,10 +274,14 @@ export function generateCandidates(taskText, repoIndex, config) {
                 for (const dep of dependents) {
                     if (candidates.size >= FANOUT_CEILING)
                         break;
+                    if (scopedPathSet2 && !scopedPathSet2.has(dep))
+                        continue;
                     const depth2Deps = repoIndex.dep_graph.dependents[dep] ?? [];
                     for (const dep2 of depth2Deps) {
                         if (candidates.size >= FANOUT_CEILING)
                             break;
+                        if (scopedPathSet2 && !scopedPathSet2.has(dep2))
+                            continue;
                         candidates.add(dep2);
                         fanoutFiles.add(dep2);
                     }
@@ -217,14 +289,18 @@ export function generateCandidates(taskText, repoIndex, config) {
             }
         }
     }
-    // 5. Test neighborhood: add test files mapped to candidates
+    // 5. Test neighborhood: add test files mapped to candidates (scope-aware)
     const currentCandidates = [...candidates];
     for (const mapping of repoIndex.test_map) {
         if (currentCandidates.includes(mapping.source_file)) {
-            candidates.add(mapping.test_file);
+            if (!scopedPathSet2 || scopedPathSet2.has(mapping.test_file)) {
+                candidates.add(mapping.test_file);
+            }
         }
         if (currentCandidates.includes(mapping.test_file)) {
-            candidates.add(mapping.source_file);
+            if (!scopedPathSet2 || scopedPathSet2.has(mapping.source_file)) {
+                candidates.add(mapping.source_file);
+            }
         }
     }
     // 6. Contract/schema auto-inclusion: when the bundle touches DB models,
@@ -246,7 +322,52 @@ export function generateCandidates(taskText, repoIndex, config) {
             }
         }
     }
-    return { candidates, tokenWeights, fanoutFiles };
+    // 7. Surface-aware auto-inclusion: detect task intent and include
+    //    config, acceptance, or contract surface files that wouldn't be found
+    //    by keyword matching (rarely edited, rarely named in tasks).
+    const taskWords = new Set(keywords);
+    const wantsConfig = [...CONFIG_SURFACE_KEYWORDS].some((k) => taskWords.has(k));
+    const wantsAcceptance = [...ACCEPTANCE_SURFACE_KEYWORDS].some((k) => taskWords.has(k));
+    const wantsContract = [...CONTRACT_SURFACE_KEYWORDS].some((k) => taskWords.has(k));
+    if (wantsConfig || wantsAcceptance || wantsContract) {
+        // For contract surfaces, reuse the directory-proximity check from step 6
+        // to avoid pulling in unrelated contract files from distant directories.
+        const candidateDirsForSurface = wantsContract
+            ? new Set([...candidates].map((p) => p.split('/').slice(0, -1).join('/')))
+            : undefined;
+        for (const file of scopedFiles) {
+            if (candidates.has(file.path))
+                continue;
+            const pathLower = file.path.toLowerCase();
+            if (wantsConfig && CONFIG_SURFACE_PATTERNS.some((p) => pathLower.includes(p))) {
+                candidates.add(file.path);
+                surfaceFiles.add(file.path);
+                continue;
+            }
+            if (wantsAcceptance && ACCEPTANCE_SURFACE_PATTERNS.some((p) => pathLower.includes(p))) {
+                candidates.add(file.path);
+                surfaceFiles.add(file.path);
+                continue;
+            }
+            if (wantsContract && candidateDirsForSurface) {
+                const ext = file.extension.toLowerCase();
+                const basename = pathLower.split('/').pop() ?? '';
+                const isContract = DEFAULT_CONTRACT_PATTERNS.includes(ext) ||
+                    CONTRACT_PATH_INDICATORS.some((ind) => basename.startsWith(ind));
+                if (isContract) {
+                    // Only include if the contract shares a directory with an existing candidate
+                    const cfDir = file.path.split('/').slice(0, -1).join('/');
+                    const isRelated = candidateDirsForSurface.has(cfDir) ||
+                        [...candidateDirsForSurface].some((d) => d.startsWith(cfDir + '/') || cfDir.startsWith(d + '/'));
+                    if (isRelated) {
+                        candidates.add(file.path);
+                        surfaceFiles.add(file.path);
+                    }
+                }
+            }
+        }
+    }
+    return { candidates, tokenWeights, fanoutFiles, surfaceFiles };
 }
 /**
  * Identify contract/schema files in the repo based on extension and path patterns.
@@ -274,7 +395,7 @@ function findContractFiles(files, customPatterns) {
     }
     return results;
 }
-function expandDependencies(seed, repoIndex, candidates, maxDepth, capPerSeed) {
+function expandDependencies(seed, repoIndex, candidates, maxDepth, capPerSeed, scopedPaths) {
     let frontier = [seed];
     let added = 0;
     for (let depth = 0; depth < maxDepth && added < capPerSeed; depth++) {
@@ -283,6 +404,8 @@ function expandDependencies(seed, repoIndex, candidates, maxDepth, capPerSeed) {
             // Add imports
             const imports = repoIndex.dep_graph.imports[file] ?? [];
             for (const dep of imports) {
+                if (scopedPaths && !scopedPaths.has(dep))
+                    continue;
                 if (!candidates.has(dep) && added < capPerSeed) {
                     candidates.add(dep);
                     nextFrontier.push(dep);
@@ -292,6 +415,8 @@ function expandDependencies(seed, repoIndex, candidates, maxDepth, capPerSeed) {
             // Add dependents (reverse)
             const dependents = repoIndex.dep_graph.dependents[file] ?? [];
             for (const dep of dependents) {
+                if (scopedPaths && !scopedPaths.has(dep))
+                    continue;
                 if (!candidates.has(dep) && added < capPerSeed) {
                     candidates.add(dep);
                     nextFrontier.push(dep);