@ngockhoale/ukit 3.0.3 → 3.0.5

package/scripts/skill/audit-skill.mjs

@@ -1,32 +1,54 @@
 #!/usr/bin/env node
 import { initSkillAudit, recordAuditEntry, statusSkillAudit } from '../../src/skill/auditSkill.js';
 
-const [command, skillName] = process.argv.slice(2);
-const rootDir = process.cwd();
+const USAGE = 'Usage: yarn skill:audit <init|status|record> <skill-name>';
 
-if (!command || !skillName) {
-  console.error('Usage: yarn skill:audit <init|status|record> <skill-name>');
-  process.exitCode = 1;
-} else if (command === 'init') {
-  const result = await initSkillAudit({ rootDir, skillName });
-  console.log(`[skill:audit init] ${skillName}`);
-  console.log(`dir: ${result.auditDir}`);
-  console.log(`copied: ${result.copied.join(', ') || 'none'}`);
-  console.log(`skipped (already present): ${result.skipped.join(', ') || 'none'}`);
-} else if (command === 'status') {
-  const result = await statusSkillAudit({ rootDir, skillName });
-  console.log(`[skill:audit status] ${skillName}`);
-  console.log(`entries: ${result.entryCount}`);
-  console.log(`latest: ${result.latest ? JSON.stringify(result.latest) : 'none'}`);
-  console.log(`open rationalizations: ${result.openRationalizations.length}`);
-} else if (command === 'record') {
-  const stdinRaw = await readStdin();
-  const entry = JSON.parse(stdinRaw);
-  const record = await recordAuditEntry({ rootDir, skillName, entry });
-  console.log(`[skill:audit record] ${skillName}`);
-  console.log(JSON.stringify(record, null, 2));
-} else {
-  console.error(`Unknown command: ${command}. Usage: yarn skill:audit <init|status|record> <skill-name>`);
+async function main() {
+  const [command, skillName, ...extra] = process.argv.slice(2);
+  const rootDir = process.cwd();
+
+  if (!command || !skillName) {
+    console.error(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  if (extra.length > 0) {
+    throw new Error(`unexpected argument: ${extra[0]}. ${USAGE}`);
+  }
+
+  if (command === 'init') {
+    const result = await initSkillAudit({ rootDir, skillName });
+    console.log(`[skill:audit init] ${skillName}`);
+    console.log(`dir: ${result.auditDir}`);
+    console.log(`copied: ${result.copied.join(', ') || 'none'}`);
+    console.log(`skipped (already present): ${result.skipped.join(', ') || 'none'}`);
+    return;
+  }
+
+  if (command === 'status') {
+    const result = await statusSkillAudit({ rootDir, skillName });
+    console.log(`[skill:audit status] ${skillName}`);
+    console.log(`entries: ${result.entryCount}`);
+    console.log(`latest: ${result.latest ? JSON.stringify(result.latest) : 'none'}`);
+    console.log(`open rationalizations: ${result.openRationalizations.length}`);
+    return;
+  }
+
+  if (command === 'record') {
+    const stdinRaw = await readStdin();
+    let entry;
+    try {
+      entry = JSON.parse(stdinRaw);
+    } catch (error) {
+      throw new Error(`skill:audit record expects a JSON entry on stdin: ${error.message}`);
+    }
+    const record = await recordAuditEntry({ rootDir, skillName, entry });
+    console.log(`[skill:audit record] ${skillName}`);
+    console.log(JSON.stringify(record, null, 2));
+    return;
+  }
+
+  console.error(`Unknown command: ${command}. ${USAGE}`);
   process.exitCode = 1;
 }
 
@@ -37,3 +59,10 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString('utf8');
 }
+
+try {
+  await main();
+} catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}

package/src/bug/triageBug.js

@@ -2,6 +2,7 @@ import { queryCodeIndex } from '../index/queryIndex.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { detectPackageManager } from '../core/packageManager.js';
+import { readJsonIfExists } from '../core/fileOps.js';
 import { inferRelatedTestsFromArtifacts, loadRelatedTestArtifacts } from '../index/relatedTests.js';
 
 const DEEP_KEYWORDS = ['race', 'flaky', 'intermittent', 'timeout', 'deadlock'];
@@ -28,10 +29,9 @@ export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
   const directRecommendedTestFile = prioritizedResults
     .flatMap((item) => item.tests ?? [])
     .find(Boolean);
-  const shouldLoadRelatedArtifacts = Boolean(topResult) || !directRecommendedTestFile;
-  const relatedArtifacts = shouldLoadRelatedArtifacts
-    ? await loadRelatedTestArtifacts({ rootDir })
-    : null;
+  // `Boolean(topResult) || !directRecommendedTestFile` is always true (no
+  // topResult ⇒ no tests ⇒ no direct file), so artifacts load unconditionally.
+  const relatedArtifacts = await loadRelatedTestArtifacts({ rootDir });
   const inferredRecommendedTests = directRecommendedTestFile
     ? []
     : inferRelatedTestsFromArtifacts({
@@ -70,9 +70,12 @@ export async function triageBug({ rootDir = process.cwd(), signature } = {}) {
     ],
   };
 }
-
 async function buildTestCommand(rootDir, testFile) {
-  const packageManager = await detectPackageManager(rootDir);
+  // Pass the parsed package.json so a declared `packageManager` field wins over
+  // lockfile/npm defaults — detectPackageManager(rootDir) alone ignored it.
+  const packageJson = await readJsonIfExists(path.join(rootDir, 'package.json')).catch(() => null);
+  const packageManager = await detectPackageManager(rootDir, packageJson);
+
 
   if (packageManager === 'pnpm') {
     return `pnpm test ${testFile}`;

package/src/cli/adapters.js

@@ -105,6 +105,12 @@ export function resolveOptionalToolKeys(toolsArg) {
 
   const normalized = toolsArg.trim().toLowerCase();
 
+  if (!normalized) {
+    // `--tools=` / `--tools ""` used to fall through to an empty selection —
+    // silently deselecting every optional adapter. Treat it as a missing value.
+    throw new Error(`Missing value for --tools. Use --tools=${TOOLS_FLAG_HELP}`);
+  }
+
   if (normalized === 'all') {
     return [...DEFAULT_OPTIONAL_TOOL_KEYS];
   }

package/src/cli/commands/code.js

@@ -12,8 +12,14 @@ const SUBCOMMANDS = new Set(['peek', 'search', 'context', 'impact']);
 function extractFlag(args, flag) {
   const index = args.indexOf(flag);
   if (index < 0) return { value: null, rest: args };
+  const value = args[index + 1];
+  // A missing value — or the next flag swallowed as the value — used to pass
+  // silently (e.g. `--mode --budget 5` set mode='--budget' and dropped --budget).
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
   return {
-    value: args[index + 1] ?? null,
+    value,
     rest: [...args.slice(0, index), ...args.slice(index + 2)],
   };
 }

package/src/cli/commands/indexArgs.js

@@ -36,8 +36,10 @@ export function parseIndexArgs(argv, flagDefinitions) {
       continue;
     }
 
-    const hasEquals = arg.includes('=');
-    const [flag, valueFromEquals = null] = hasEquals ? arg.split('=', 2) : [arg, null];
+    const equalsIndex = arg.indexOf('=');
+    const [flag, valueFromEquals = null] = equalsIndex >= 0
+      ? [arg.slice(0, equalsIndex), arg.slice(equalsIndex + 1)]
+      : [arg, null];
     const definition = flagDefinitions.get(flag);
     if (!definition) {
       throw new Error(`Unknown option: ${flag}`);

package/src/cli/commands/indexTools.js

@@ -192,7 +192,14 @@ export async function runIndexTools({ projectRoot, argv = [] }) {
     const taskType = flags.get('--type') ?? null;
     const commandText = flags.get('--tool-command') ?? '';
     const lastExplicitUserPromptText = flags.get('--last-prompt') ?? '';
-    const adapter = flags.get('--adapter') ?? 'claude';
+    const rawAdapter = flags.get('--adapter') ?? 'claude';
+    // Same posture as the shipped route-task.mjs helper: unknown adapters warn
+    // and fall back to claude instead of silently picking a namespace.
+    const KNOWN_ROUTE_ADAPTERS = new Set(['claude', 'codex']);
+    const adapter = KNOWN_ROUTE_ADAPTERS.has(rawAdapter) ? rawAdapter : 'claude';
+    if (adapter !== rawAdapter) {
+      console.error(`[UKit] unknown --adapter "${rawAdapter}" — falling back to claude`);
+    }
     const commandNamespace = adapter === 'codex' ? '.codex' : '.claude';
 
     if (!promptText && !commandText && !targetFile) {

package/src/cli/commands/install.js

@@ -10,6 +10,7 @@ import { removeTrackedPathsFromMetadata } from '../../core/metadata.js';
 import {
   ADAPTER_BY_KEY,
   DEFAULT_OPTIONAL_TOOL_KEYS,
+  TOOLS_FLAG_HELP,
   parseToolsArg,
   resolveOptionalToolKeys,
   toSelectedAdapterItemIds,
@@ -245,6 +246,18 @@ export async function pruneDeselectedAdapters({
 }
 
 export async function runInstall({ packageRoot, projectRoot, packageVersion, argv = [] }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: ukit install [options]');
+    console.log('');
+    console.log('Install/update UKit assets into the current project (default command).');
+    console.log('');
+    console.log('Options:');
+    console.log(`  --tools=<list>     Adapters to enable (default: all). Values: ${TOOLS_FLAG_HELP}`);
+    console.log('  --with-codegraph   Enable CodeGraph MCP integration in CLAUDE.md');
+    console.log('  --help, -h         Show this help message');
+    return;
+  }
+
   // parseToolsArg owns only --tools and throws on anything else, so hand it the argv with
   // the flags consumed here (--with-codegraph) already removed — order-dependent parsing
   // used to make the documented `ukit install --with-codegraph` fail 100% of the time.

package/src/cli/commands/memory.js

@@ -18,9 +18,8 @@ import {
 import {
   addUserRecord,
   getUserRecord,
-  loadUserRecords,
   queryUserRecords,
-  saveUserRecords,
+  removeUserRecord,
   updateUserRecord,
   userMemoryStats,
 } from '../../core/memory/userMemory.js';
@@ -40,8 +39,14 @@ const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 function extractFlag(args, flag) {
   const index = args.indexOf(flag);
   if (index < 0) return { value: null, rest: args };
+  const value = args[index + 1];
+  // A missing value — or the next flag swallowed as the value — used to pass
+  // silently (e.g. `--project --category bug` set projectId='--category').
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}.`);
+  }
   return {
-    value: args[index + 1] ?? null,
+    value,
     rest: [...args.slice(0, index), ...args.slice(index + 2)],
   };
 }
@@ -291,12 +296,10 @@ async function runUserMemory(homeDir, args) {
     if (!id) {
       throw new Error('Missing record id. Usage: ukit memory --user forget <id>');
     }
-    const records = await loadUserRecords({ homeDir });
-    const remaining = records.filter((r) => r.id !== id);
-    if (remaining.length === records.length) {
+    const removed = await removeUserRecord(id, { homeDir });
+    if (!removed) {
       throw new Error(`User memory record not found: ${id}`);
     }
-    await saveUserRecords(remaining, { homeDir });
     console.log(`[UKit] Forgot user record ${id}.`);
     return;
   }
@@ -437,8 +440,9 @@ function episodeText(ledger, sessionId) {
     ? 'not-run'
     : ledger.verificationSucceeded === true ? 'ok' : 'fail';
   const receipts = Array.isArray(ledger.receipts) ? ledger.receipts : [];
-  const lastCommand = receipts.length > 0
-    ? String(receipts[receipts.length - 1].command ?? '').split('\n')[0].trim() || 'n/a'
+  const lastReceipt = receipts.length > 0 ? receipts[receipts.length - 1] : null;
+  const lastCommand = lastReceipt
+    ? String(lastReceipt?.command ?? '').split('\n')[0].trim() || 'n/a'
     : 'n/a';
   const text = `Session ${sessionId}: ${write}, verify=${verify}, `
     + `${receipts.length} receipts, last command ${lastCommand}`;

package/src/cli/commands/status.js

@@ -1,6 +1,22 @@
 import { buildStatusReport, formatStatusReport } from '../../core/status.js';
 
-export async function runStatus({ projectRoot }) {
+const KNOWN_STATUS_FLAGS = new Set(['--help', '-h']);
+
+export async function runStatus({ projectRoot, argv = [] }) {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log('Usage: ukit status');
+    console.log('');
+    console.log('Show UKit runtime status for the current project.');
+    return;
+  }
+
+  const unknownArgs = argv.filter((a) => !KNOWN_STATUS_FLAGS.has(a));
+  if (unknownArgs.length > 0) {
+    throw new Error(
+      `Unknown option(s): ${unknownArgs.join(', ')}. Run \`ukit status --help\` for usage.`,
+    );
+  }
+
   const report = await buildStatusReport(projectRoot);
   for (const line of formatStatusReport(report)) {
     console.log(line);

package/src/cli/commands/update.js

@@ -20,6 +20,13 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
     );
   }
 
+  const positionalArgs = argv.filter((a) => !a.startsWith('-'));
+  if (positionalArgs.length > 0) {
+    throw new Error(
+      `Unexpected argument(s): ${positionalArgs.join(', ')}. Run \`ukit update --help\` for usage.`,
+    );
+  }
+
   console.log(`[UKit] Current version: ${packageVersion}`);
   console.log(`[UKit] Running: npm install -g ${UKIT_PACKAGE_NAME}`);
 

package/src/context/detectProjectContext.js

@@ -12,7 +12,9 @@ function inferProjectName(projectRoot, packageJson) {
 
 export async function detectProjectContext(projectRoot) {
   const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageJson = await readJsonIfExists(packageJsonPath);
+  // A corrupt package.json must degrade to basename naming, not crash the
+  // status/memory CLIs with a raw SyntaxError.
+  const packageJson = await readJsonIfExists(packageJsonPath).catch(() => null);
 
   return {
     project: {

package/src/core/codeintel/analogy.js

@@ -190,7 +190,7 @@ export async function findAnalogies(projectRoot, query, { limit = DEFAULT_LIMIT
   }
 
   analogies.sort((a, b) => b.score - a.score || a.ref.localeCompare(b.ref));
-  if (analogies.length === 0 && !memory.why && filesArtifact && symbolsArtifact) {
+  if (analogies.length === 0 && (memory.records !== null || filesArtifact || symbolsArtifact)) {
     omitted.push({ what: 'analogy-lane', why: 'no-match' });
   }
   return { analogies: analogies.slice(0, effectiveLimit), omitted };

package/src/core/codeintel/diagnostics.js

@@ -12,15 +12,18 @@ const SYNTAX_EXTENSIONS = new Set(['.js', '.mjs', '.cjs']);
 const MAX_DIAGNOSTICS = 50;
 
 function parseCheckLine(stderr) {
-  const line = String(stderr ?? '')
+  const lines = String(stderr ?? '')
     .split('\n')
     .map((l) => l.trim())
-    .find((l) => l.length > 0);
-  if (!line) return { message: 'syntax check failed', line: null };
-  const match = line.match(/:(\d+)\s*$/);
+    .filter((l) => l.length > 0);
+  if (lines.length === 0) return { message: 'syntax check failed', line: null };
+  // `node --check` stderr opens with `<file>:<line>` then the offending source
+  // line and a caret; the real error is the first *Error line below that.
+  const errorLine = lines.find((l) => /\b\w*Error\b/.test(l));
+  const lineMatch = lines[0].match(/:(\d+)\s*$/);
   return {
-    message: line,
-    line: match ? Number.parseInt(match[1], 10) : null,
+    message: errorLine ?? lines[0],
+    line: lineMatch ? Number.parseInt(lineMatch[1], 10) : null,
   };
 }
 

package/src/core/codeintel/graph.js

@@ -96,8 +96,8 @@ export async function buildGraphArtifact(projectRoot) {
     }
     return id;
   };
-  const addEdge = (edge, dedupeExtra = '') => {
-    const key = `${edge.from}»${edge.to}»${edge.kind}»${dedupeExtra}`;
+  const addEdge = (edge) => {
+    const key = `${edge.from}»${edge.to}»${edge.kind}`;
     if (!edges.has(key)) edges.set(key, edge);
   };
 
@@ -132,16 +132,18 @@ export async function buildGraphArtifact(projectRoot) {
     for (const name of call.calls ?? []) {
       const target = symbolToFile.get(name);
       if (!target || target === call.filePath) continue;
+      // The callee file is a graph node even when it has no calls.json row of
+      // its own — an edge must never point at a non-existent node.
+      addFileNode(target);
       addEdge(createEdge({
         from: call.filePath,
         to: target,
         kind: 'call',
         provider: 'json-graph',
         evidence: INDEX_ARTIFACTS.calls,
-      }), name);
+      }));
     }
   }
-
   // co-change edges: pair endpoints become file nodes; count feeds confidence.
   for (const pair of cochangeArtifact?.pairs ?? []) {
     if (!pair?.a || !pair?.b) continue;
@@ -155,7 +157,7 @@ export async function buildGraphArtifact(projectRoot) {
       confidence,
       provider: 'json-graph',
       evidence: INDEX_ARTIFACTS.cochange,
-    }), String(pair.count ?? ''));
+    }));
     addEdge(createEdge({
       from: pair.b,
       to: pair.a,
@@ -163,7 +165,7 @@ export async function buildGraphArtifact(projectRoot) {
       confidence,
       provider: 'json-graph',
       evidence: INDEX_ARTIFACTS.cochange,
-    }), String(pair.count ?? ''));
+    }));
   }
 
   const artifact = {
@@ -205,11 +207,15 @@ export class JsonGraphStore {
   capabilities() {
     return { nodes: true, edges: true, queries: true };
   }
-
   async _load() {
     if (!this._artifactPromise) {
       this._artifactPromise = (async () => {
-        const artifact = await readJsonIfExists(getArtifactPath(this.rootDir, INDEX_ARTIFACTS.codegraph));
+        let artifact = null;
+        try {
+          artifact = await readJsonIfExists(getArtifactPath(this.rootDir, INDEX_ARTIFACTS.codegraph));
+        } catch {
+          return null; // corrupt JSON → empty results, never throws
+        }
         if (!artifact || typeof artifact !== 'object') return null;
         if (artifact.schemaVersion !== GRAPH_SCHEMA_VERSION) return null;
         if (!Array.isArray(artifact.nodes) || !Array.isArray(artifact.edges)) return null;

package/src/core/codeintel/impact.js

@@ -98,7 +98,6 @@ export async function impactSet(projectRoot, seeds, {
   const nodeCap = clampInt(maxNodes ?? defaults.maxNodes, 1, Number.MAX_SAFE_INTEGER);
   const requestedDepth = typeof depth === 'number' ? depth : defaults.defaultDepth;
   const depthLimit = clampInt(requestedDepth, 1, maxDepthCap);
-  const depthClamped = requestedDepth > depthLimit;
 
   const seedList = Array.isArray(seeds) ? seeds.filter((s) => typeof s === 'string' && s.length > 0) : [];
   if (seedList.length === 0) {

package/src/core/codeintel/invalidation.js

@@ -140,15 +140,17 @@ export async function readDirty(projectRoot) {
 
 /**
  * Return the accumulated dirty set and clear the file (index-refresh lane).
- * @returns {Promise<string[]>} sorted paths, `[]` on missing/corrupt.
+ * `saturated` is surfaced so callers can treat a saturated set as full
+ * invalidation — a saturated drain with few/no paths is NOT a clean state.
+ * @returns {Promise<{ paths: string[], saturated: boolean }>}
  */
 export async function drainDirty(projectRoot) {
   const { paths, saturated } = await readDirtyData(projectRoot);
-  if (paths.length === 0 && !saturated) return [];
+  if (paths.length === 0 && !saturated) return { paths: [], saturated: false };
   try {
     await writeDirtyData(projectRoot, [], false);
   } catch {
     // never throw — drained set is still returned
   }
-  return [...paths].sort();
+  return { paths: [...paths].sort(), saturated };
 }

package/src/core/codeintel/packet.js

@@ -125,6 +125,17 @@ export function packetToText(packet) {
   for (const t of packet.tests ?? []) lines.push(`- ${t}`);
   if ((packet.tests ?? []).length === 0) lines.push('(none)');
 
+  lines.push('');
+  lines.push('## Memory');
+  for (const m of packet.memory ?? []) {
+    if (m && typeof m === 'object') {
+      lines.push(`- ${m.id ?? m.ref ?? ''}${typeof m.score === 'number' ? ` (score ${m.score})` : ''}`);
+    } else {
+      lines.push(`- ${m}`);
+    }
+  }
+  if ((packet.memory ?? []).length === 0) lines.push('(none)');
+
   lines.push('');
   lines.push('## Omitted');
   for (const o of packet.omitted ?? []) lines.push(`- ${o.what ?? ''} — ${o.why ?? ''}`);

package/src/core/codeintel/router.js

@@ -36,7 +36,21 @@ const ERROR_RE = /\b(error|exception|stack ?trace|bug|crash|failing|fails|failur
 const EXPLORE_RE = /\b(where|how does|how do|find|explore|understand|what does|which file|locate|handled)\b/i;
 const DEEP_FLOW_RE = /\b(refactor|migrate|migration|flow|end[- ]?to[- ]?end|trace|across|pipeline|lifecycle)\b/i;
 const ANALOGY_RE = /\b(similar to|analogy|like\b|same as|pattern|equivalent)\b/i;
-const PATH_RE = /(?:[\w.-]+\/)+[\w.-]+|[\w.-]+\.(?:js|ts|mjs|cjs|jsx|tsx|py|rb|go|rs|java|md|json|yml|yaml|css|html|sh)\b/i;
+const PATH_RE = /(?:[\w.-]+\/)+[\w.-]+|[\w.-]+\.(?:js|ts|mjs|cjs|jsx|tsx|py|rb|go|rs|java|md|json|yml|yaml|css|html|sh)\b/gi;
+
+// English slash-words that look like paths to PATH_RE but never are —
+// "and/or", "n/a" etc. must not trigger the explicit-target rule.
+const SLASH_WORD_STOPLIST = new Set([
+  'and/or', 'n/a', 'yes/no', 'true/false', 'on/off', 'either/or', 'w/o', 'w/', 'b/c',
+]);
+
+function hasPathMention(prompt) {
+  const text = String(prompt ?? '');
+  for (const match of text.matchAll(PATH_RE)) {
+    if (!SLASH_WORD_STOPLIST.has(match[0].toLowerCase())) return true;
+  }
+  return false;
+}
 
 function resolveBudgets(options) {
   const configured = options?.config?.codeIntel?.budgets ?? options?.budgets;
@@ -63,7 +77,7 @@ function decide(prompt, { hasError = false, filesHinted } = {}) {
   }
 
   // Rule 3 — explicit path/symbol mention, clear scope, no error.
-  const hasExplicitTarget = hintedFiles.length > 0 || PATH_RE.test(prompt);
+  const hasExplicitTarget = hintedFiles.length > 0 || hasPathMention(prompt);
   const errorSignalled = hasError || ERROR_RE.test(prompt);
   if (!errorSignalled && hasExplicitTarget) {
     reasons.push('explicit path or symbol mention with clear scope');
@@ -95,7 +109,7 @@ function decide(prompt, { hasError = false, filesHinted } = {}) {
   }
 
   // Rule 8 — fallback: single-file verb (single hinted file or lone path mention).
-  if (hintedFiles.length === 1 || PATH_RE.test(prompt)) {
+  if (hintedFiles.length === 1 || hasPathMention(prompt)) {
     reasons.push('fallback: single-file hint');
     return { mode: 'peek', reasons };
   }

package/src/core/codeintel/semanticProvider.js

@@ -87,7 +87,7 @@ export class TypeScriptSemanticProvider {
     try {
       const filesPath = getArtifactPath(this.projectRoot, INDEX_ARTIFACTS.files);
       const raw = JSON.parse(fs.readFileSync(filesPath, 'utf8'));
-      const list = Array.isArray(raw) ? raw : (raw.files ?? []);
+      const list = Array.isArray(raw) ? raw : (raw.items ?? raw.files ?? []);
       return list
         .map((entry) => (typeof entry === 'string' ? entry : entry?.filePath ?? entry?.path))
         .filter(isSemanticFile)

package/src/core/codeintel/summaries.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { getSyntaxProvider } from './providers.js';
+import { getSyntaxProvider, IndexFileSyntaxProvider } from './providers.js';
 import { resolveProjectRelativePath } from '../fileOps.js';
 
 // Deterministic extractive summaries (SPEC §7/§8, CI-304) — the L3 detail tier.
@@ -118,12 +118,16 @@ function scanDeclarations(lines, maxSymbols) {
 
 async function symbolNames(rootDir, relPath, lines, maxSymbols) {
   try {
-    const provider = getSyntaxProvider(relPath);
-    if (provider) {
-      const syms = await provider.symbols(relPath);
-      if (Array.isArray(syms) && syms.length > 0) {
-        return syms.slice(0, maxSymbols).map((s) => s.name).filter(Boolean);
-      }
+    let provider = getSyntaxProvider(relPath);
+    // The registry's built-in 'index-file' provider is bound to process.cwd()
+    // at ensureBuiltins() time — rebind it to this call's rootDir so summaries
+    // read the project index even when cwd differs (or supports() failed).
+    if (!provider || provider.name === 'index-file') {
+      provider = new IndexFileSyntaxProvider({ rootDir });
+    }
+    const syms = await provider.symbols(relPath);
+    if (Array.isArray(syms) && syms.length > 0) {
+      return syms.slice(0, maxSymbols).map((s) => s.name).filter(Boolean);
     }
   } catch {
     // provider failure falls through to the regex lane — never throws

package/src/core/compact/contextBudget.js

@@ -27,6 +27,31 @@ export function deriveAutoCompactWindow(hardCapTokens, ratio) {
   return Math.round(hardCapTokens * safeRatio);
 }
 
+// A malformed hard cap must fall back to a safe ceiling, never collapse to a
+// non-positive or fractional cap that would brick every Edit/Write/Bash call or
+// invert the autoCompactWindow < hardCapTokens invariant — same operator
+// contract as positiveInteger() in compact/threshold.js.
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
+// Pure normalization of a raw `compact` config object into the budget triple.
+// Exported so the fallback rules are testable without touching the shipped file.
+export function deriveCompactBudget(compact = {}) {
+  const source = compact && typeof compact === 'object' ? compact : {};
+  const tokenThreshold = Number.isFinite(source.tokenThreshold)
+    ? source.tokenThreshold
+    : EMERGENCY_BUDGET.tokenThreshold;
+  const hardCapTokens = positiveInteger(source.hardCapTokens, EMERGENCY_BUDGET.hardCapTokens);
+  return {
+    tokenThreshold,
+    hardCapTokens,
+    autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, source.autoCompactWindowRatio),
+  };
+}
+
 let cachedBudget = null;
 
 export function loadShippedCompactBudget() {
@@ -41,17 +66,6 @@ export function loadShippedCompactBudget() {
     compact = EMERGENCY_BUDGET;
   }
 
-  const tokenThreshold = Number.isFinite(compact.tokenThreshold)
-    ? compact.tokenThreshold
-    : EMERGENCY_BUDGET.tokenThreshold;
-  const hardCapTokens = Number.isFinite(compact.hardCapTokens)
-    ? compact.hardCapTokens
-    : EMERGENCY_BUDGET.hardCapTokens;
-
-  cachedBudget = {
-    tokenThreshold,
-    hardCapTokens,
-    autoCompactWindow: deriveAutoCompactWindow(hardCapTokens, compact.autoCompactWindowRatio),
-  };
+  cachedBudget = deriveCompactBudget(compact);
   return cachedBudget;
 }