@jaimevalasek/aioson 1.29.1 → 1.30.1

package/src/commands/artifact-validate.js

@@ -19,23 +19,25 @@ const {
   parseFrontmatter,
   contextDir
 } = require('../preflight-engine');
+const { AC_ID_RE } = require('../lib/ac-test-audit');
 
 const BAR = '━'.repeat(45);
+const REQ_ID_RE = /\bREQ(?:-[A-Za-z0-9]+)+\b/g;
 
-function gateDisplay(gates) {
-  const letters = { requirements: 'A', design: 'B', plan: 'C', execution: 'D' };
+function gateDisplay(gates) {
+  const letters = { requirements: 'A', design: 'B', plan: 'C', execution: 'D' };
   return Object.entries(letters).map(([name, letter]) => {
     const status = gates[name];
     return status === 'approved' ? `${letter}✓` : `${letter}○`;
-  }).join(' ');
-}
-
-function artifactDisplayName(artifact, fallbackName) {
-  if (artifact && artifact.exists && artifact.path) return path.basename(artifact.path);
-  return fallbackName;
-}
-
-async function runArtifactValidate({ args, options = {}, logger }) {
+  }).join(' ');
+}
+
+function artifactDisplayName(artifact, fallbackName) {
+  if (artifact && artifact.exists && artifact.path) return path.basename(artifact.path);
+  return fallbackName;
+}
+
+async function runArtifactValidate({ args, options = {}, logger }) {
   const targetDir = path.resolve(process.cwd(), args[0] || '.');
   const slug = options.feature ? String(options.feature) : null;
 
@@ -60,6 +62,9 @@ async function runArtifactValidate({ args, options = {}, logger }) {
   const sheldonReady = artifacts.sheldon_enrichment.exists
     ? (artifacts.sheldon_enrichment.frontmatter.readiness === 'ready_for_downstream' ? 'ready_for_downstream' : 'present')
     : null;
+  const sheldonValidationReady = artifacts.sheldon_validation.exists
+    ? (artifacts.sheldon_validation.frontmatter.verdict || artifacts.sheldon_validation.frontmatter.readiness || 'present')
+    : null;
 
   // Implementation plan status
   const planStatus = artifacts.implementation_plan.exists
@@ -70,19 +75,19 @@ async function runArtifactValidate({ args, options = {}, logger }) {
   // (REQ-SDLC-01), because feature contracts use slugged identifiers.
   let reqCount = null;
   if (artifacts.requirements.exists && artifacts.requirements.content) {
-    const reqs = artifacts.requirements.content.match(/\bREQ(?:-[A-Z0-9]+)+\b/g) || [];
-    const acs = artifacts.requirements.content.match(/\bAC(?:-[A-Z0-9]+)+\b/g) || [];
+    const reqs = artifacts.requirements.content.match(REQ_ID_RE) || [];
+    const acs = artifacts.requirements.content.match(AC_ID_RE) || [];
     reqCount = `${new Set(reqs).size} REQs, ${new Set(acs).size} ACs`;
   }
 
-  // Conformance required?
-  const conformanceRequired = classification === 'MEDIUM';
-  const designDocRequired = classification === 'SMALL' || classification === 'MEDIUM';
-  const designDocName = artifactDisplayName(artifacts.design_doc, `design-doc-${slug}.md`);
-  const readinessName = artifactDisplayName(artifacts.readiness, `readiness-${slug}.md`);
-
-  // Build chain items
-  const chain = [
+  // Conformance required?
+  const conformanceRequired = classification === 'MEDIUM';
+  const designDocRequired = classification === 'SMALL' || classification === 'MEDIUM';
+  const designDocName = artifactDisplayName(artifacts.design_doc, `design-doc-${slug}.md`);
+  const readinessName = artifactDisplayName(artifacts.readiness, `readiness-${slug}.md`);
+
+  // Build chain items
+  const chain = [
     {
       name: 'project.context.md',
       exists: artifacts.project_context.exists,
@@ -104,6 +109,13 @@ async function runArtifactValidate({ args, options = {}, logger }) {
       required: false,
       indent: 1
     },
+    {
+      name: `sheldon-validation-${slug}.md`,
+      exists: artifacts.sheldon_validation.exists,
+      detail: sheldonValidationReady ? `verdict: ${sheldonValidationReady}` : 'MEDIUM readiness verdict when @sheldon runs',
+      required: false,
+      indent: 1
+    },
     {
       name: `requirements-${slug}.md`,
       exists: artifacts.requirements.exists,
@@ -118,29 +130,29 @@ async function runArtifactValidate({ args, options = {}, logger }) {
       required: true,
       indent: 1
     },
-    {
-      name: 'architecture.md',
-      exists: artifacts.architecture.exists,
-      detail: null,
-      required: true,
-      indent: 1
-    },
-    {
-      name: designDocName,
-      exists: artifacts.design_doc.exists,
-      detail: designDocRequired ? 'pre-dev design governance contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
-      required: designDocRequired,
-      indent: 1
-    },
-    {
-      name: readinessName,
-      exists: artifacts.readiness.exists,
-      detail: designDocRequired ? 'pre-dev readiness contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
-      required: designDocRequired,
-      indent: 1
-    },
-    {
-      name: `implementation-plan-${slug}.md`,
+    {
+      name: 'architecture.md',
+      exists: artifacts.architecture.exists,
+      detail: null,
+      required: true,
+      indent: 1
+    },
+    {
+      name: designDocName,
+      exists: artifacts.design_doc.exists,
+      detail: designDocRequired ? 'pre-dev design governance contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
+      required: designDocRequired,
+      indent: 1
+    },
+    {
+      name: readinessName,
+      exists: artifacts.readiness.exists,
+      detail: designDocRequired ? 'pre-dev readiness contract' : `SMALL/MEDIUM only — NOT required for ${classification || 'MICRO'}`,
+      required: designDocRequired,
+      indent: 1
+    },
+    {
+      name: `implementation-plan-${slug}.md`,
       exists: artifacts.implementation_plan.exists,
       detail: planStatus ? `status: ${planStatus}` : null,
       required: true,
@@ -164,12 +176,12 @@ async function runArtifactValidate({ args, options = {}, logger }) {
   // Determine next_missing and next_agent (AC-SDLC-22)
   const ARTIFACT_OWNER_MAP = {
     'project.context.md': { agent: '@setup', reason: 'setup not complete' },
-    [`prd-${slug}.md`]: { agent: '@product', reason: 'PRD not produced yet' },
-    [`requirements-${slug}.md`]: { agent: '@analyst', reason: 'requirements not produced yet (Gate A)' },
-    'architecture.md': { agent: '@architect', reason: 'architecture not produced yet (Gate B)' },
-    [designDocName]: { agent: '@discovery-design-doc', reason: 'design governance contract not produced yet' },
-    [readinessName]: { agent: '@discovery-design-doc', reason: 'readiness contract not produced yet' },
-    [`implementation-plan-${slug}.md`]: { agent: '@pm', reason: 'implementation plan not produced yet (Gate C)' },
+    [`prd-${slug}.md`]: { agent: '@product', reason: 'PRD not produced yet' },
+    [`requirements-${slug}.md`]: { agent: '@analyst', reason: 'requirements not produced yet (Gate A)' },
+    'architecture.md': { agent: '@architect', reason: 'architecture not produced yet (Gate B)' },
+    [designDocName]: { agent: '@discovery-design-doc', reason: 'design governance contract not produced yet' },
+    [readinessName]: { agent: '@discovery-design-doc', reason: 'readiness contract not produced yet' },
+    [`implementation-plan-${slug}.md`]: { agent: '@pm', reason: 'implementation plan not produced yet (Gate C)' },
     [`spec-${slug}.md`]: { agent: '@analyst', reason: 'spec not produced yet — @analyst seeds the feature memory' },
     [`conformance-${slug}.yaml`]: { agent: '@analyst', reason: 'conformance contract missing — @analyst creates it for MEDIUM features' }
   };

package/src/commands/classify.js

@@ -116,6 +116,60 @@ const COMPLEXITY_SOME_PATTERNS = [
   /\b(notification|trigger|event)\b/gi
 ];
 
+// Sensitive-surface floor (Gap 3B): a feature touching any of these surfaces is
+// never MICRO. Mirrors the secure-tdd sensitive list in @dev. The floor can only
+// RAISE the tier (MICRO -> SMALL); it never lowers it. Keep patterns tight — a
+// false positive needlessly costs the SMALL chain. Tune as the project learns.
+const SENSITIVE_SURFACE_PATTERNS = [
+  { surface: 'money', re: /\b(money|stripe|paypal|braintree|square|payments?|payouts?|refunds?|subscriptions?|billing|invoices?|credit card)\b/i },
+  { surface: 'auth', re: /\b(oauth|jwt|saml|sso|auth0|firebase auth|log[- ]?in|sign[- ]?in|sign[- ]?up|passwords?|authenticat\w*|2fa|mfa)\b/i },
+  { surface: 'authz', re: /\b(authoriz\w*|access control|role[- ]based|rbac|ownership|owner[- ]only|only the owner)\b/i },
+  { surface: 'uploads', re: /\b(file uploads?|uploads?|attachments?)\b/i },
+  { surface: 'external_url', re: /\b(webhooks?|callback urls?|ssrf|user[- ]?supplied urls?)\b/i },
+  { surface: 'secrets', re: /\b(secrets?|api keys?|credentials?|private key|access tokens?)\b/i },
+  { surface: 'sensitive_storage', re: /\b(pii|personal data|ssn|sensitive (data|storage|information))\b/i }
+];
+
+function detectSensitiveSurfaces(content) {
+  const found = [];
+  for (const { surface, re } of SENSITIVE_SURFACE_PATTERNS) {
+    if (re.test(content)) found.push(surface);
+  }
+  return found;
+}
+
+// Explicit `sensitive_surfaces:` frontmatter override — additive, can only force
+// the floor when content detection misses. Supports inline (`[a, b]` / `a, b`)
+// and YAML block list forms.
+function parseSensitiveSurfacesOverride(content) {
+  const fm = String(content || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!fm) return [];
+  const body = fm[1];
+  const items = [];
+  const inline = body.match(/^sensitive_surfaces:[ \t]*(.+)$/m);
+  if (inline) {
+    inline[1].trim().replace(/^\[|\]$/g, '').split(',').forEach((s) => {
+      const v = s.trim().replace(/^["']|["']$/g, '');
+      if (v) items.push(v);
+    });
+  }
+  const block = body.match(/^sensitive_surfaces:[ \t]*\r?\n((?:[ \t]*-[ \t]*.+\r?\n?)+)/m);
+  if (block) {
+    block[1].split(/\r?\n/).forEach((line) => {
+      const m = line.match(/^[ \t]*-[ \t]*(.+)$/);
+      if (m) {
+        const v = m[1].trim().replace(/^["']|["']$/g, '');
+        if (v) items.push(v);
+      }
+    });
+  }
+  return items;
+}
+
+function applySensitiveFloor(classification) {
+  return classification === 'MICRO' ? 'SMALL' : classification;
+}
+
 function analyzeContent(content) {
   // Count unique user types
   const userTypeSet = new Set();
@@ -185,6 +239,7 @@ async function runClassify({ args, options = {}, logger }) {
 
   let userTypeCount, integrationCount, complexityLevel;
   let sourceFile = null;
+  let content = null;
 
   if (interactive) {
     ({ userTypeCount, integrationCount, complexityLevel } = await runInteractive(logger));
@@ -199,7 +254,6 @@ async function runClassify({ args, options = {}, logger }) {
         ]
       : [path.join(dir, 'requirements.md'), path.join(dir, 'prd.md')];
 
-    let content = null;
     for (const candidate of candidates) {
       content = await readFileSafe(candidate);
       if (content) { sourceFile = path.relative(targetDir, candidate); break; }
@@ -218,7 +272,19 @@ async function runClassify({ args, options = {}, logger }) {
   const intScore = scoreIntegrations(integrationCount);
   const cxScore = scoreComplexity(complexityLevel);
   const totalScore = utScore + intScore + cxScore;
-  const classification = scoreToClassification(totalScore);
+  let classification = scoreToClassification(totalScore);
+
+  // Gap 3B — sensitive-surface floor (deterministic; raises MICRO -> SMALL only).
+  const detectedSurfaces = content ? detectSensitiveSurfaces(content) : [];
+  const declaredSurfaces = content ? parseSensitiveSurfacesOverride(content) : [];
+  const sensitiveSurfaces = [...new Set([...detectedSurfaces, ...declaredSurfaces])];
+  let floored = false;
+  if (sensitiveSurfaces.length > 0) {
+    const scored = classification;
+    classification = applySensitiveFloor(classification);
+    floored = classification !== scored;
+  }
+
   const phaseDepth = classificationToPhaseDepth(classification);
 
   const result = {
@@ -228,6 +294,8 @@ async function runClassify({ args, options = {}, logger }) {
     inputs: { user_types: userTypeCount, external_integrations: integrationCount, rule_complexity: complexityLevel },
     scores: { user_types: utScore, integrations: intScore, complexity: cxScore, total: totalScore },
     classification,
+    sensitive_surfaces: sensitiveSurfaces,
+    floored,
     phase_depth: phaseDepth
   };
 
@@ -243,6 +311,9 @@ async function runClassify({ args, options = {}, logger }) {
   logger.log(`Business rule complexity: ${complexityLevel} → +${cxScore}`);
   logger.log(BAR);
   logger.log(`Score: ${totalScore} → ${classification}`);
+  if (sensitiveSurfaces.length > 0) {
+    logger.log(`Sensitive surfaces: ${sensitiveSurfaces.join(', ')}${floored ? ' → floored to SMALL' : ''}`);
+  }
   logger.log('');
   logger.log('Phase depth:');
   for (const [phase, desc] of Object.entries(phaseDepth)) {

package/src/commands/context-brief.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const path = require('node:path');
+const { buildContextBrief } = require('../context-brief');
+
+async function runContextBrief({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const result = await buildContextBrief(targetDir, {
+    agent: options.agent || options.a || 'dev',
+    mode: options.mode || 'planning',
+    task: options.task || options.goal || '',
+    paths: options.paths || options.path || '',
+    feature: options.feature || options.slug || '',
+    semantic: options.semantic,
+    noSemantic: options.noSemantic || options['no-semantic'],
+    recall: !(options['no-recall'] || options.recall === false)
+  });
+
+  if (options.json) return result;
+
+  logger.log(`Context brief for @${result.agent} (${result.mode})`);
+  if (result.task) logger.log(`Task: ${result.task}`);
+  logger.log(`Intent: ${result.intent.operation}${result.intent.stack ? ` / ${result.intent.stack}` : ''}`);
+  if (result.intent.concerns.length > 0) logger.log(`Concerns: ${result.intent.concerns.join(', ')}`);
+  logger.log(`Confidence: ${result.confidence}`);
+
+  if (result.must_load.length > 0) {
+    logger.log('Must load:');
+    for (const item of result.must_load) logger.log(`- ${item.path} [${item.surface}] ${item.reason}`);
+  }
+  if (result.should_load.length > 0) {
+    logger.log('Should load when needed:');
+    for (const item of result.should_load) logger.log(`- ${item.path} [${item.surface}] ${item.reason}`);
+  }
+  if (result.constraints.length > 0) {
+    logger.log('Constraints:');
+    for (const item of result.constraints.slice(0, 8)) logger.log(`- ${item}`);
+  }
+  if (result.forbidden_patterns.length > 0) {
+    logger.log('Forbidden patterns:');
+    for (const item of result.forbidden_patterns.slice(0, 8)) logger.log(`- ${item}`);
+  }
+  if (result.verification_hints.length > 0) {
+    logger.log('Verification hints:');
+    for (const item of result.verification_hints.slice(0, 8)) logger.log(`- ${item}`);
+  }
+  if (result.gaps.length > 0) {
+    logger.log('Gaps:');
+    for (const gap of result.gaps) logger.log(`- ${gap.code}: ${gap.message}`);
+  }
+  if (result.related && result.related.length > 0) {
+    logger.log('Related (recall — history/archive select cannot see):');
+    for (const item of result.related) logger.log(`- ${item.path} [${item.source_type}] ${item.reason || ''}`);
+  }
+
+  return result;
+}
+
+module.exports = { runContextBrief };

package/src/commands/context-guard.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { buildGuardResponse } = require('../context-guard');
+
+// `aioson context:guard [path] --tool=claude [--json]`
+//
+// Reference adapter for the operational retrieval loop. A harness hook pipes the
+// pending tool event on stdin; the guard answers with a harness-shaped injection
+// payload (or an empty object when no project rule is salient). Always exits 0 —
+// it is advisory and must never block the host harness.
+async function runContextGuard({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args[0] || '.');
+  const event = await resolveEvent(args, options);
+
+  let response;
+  try {
+    response = await buildGuardResponse(event || {}, targetDir, {
+      tool: options.tool || 'claude',
+      agent: options.agent || options.a || 'dev'
+    });
+  } catch {
+    // The guard is advisory and runs on the PreToolUse hot path. Any internal
+    // failure must surface as an empty injection ({}), never a non-hook envelope
+    // ({"ok":false,...}) on the hook's stdout channel.
+    response = {};
+  }
+
+  const guard = response && response._guard;
+
+  if (options.json) {
+    // Keep the wire payload pristine — strip the internal observability field.
+    const { _guard, ...wire } = response;
+    return wire;
+  }
+
+  if (guard && guard.injected) {
+    logger.log(`context:guard injected ${guard.rules.length} rule(s): ${guard.rules.join(', ')} (confidence ${guard.confidence})`);
+  } else {
+    logger.log('context:guard: no salient project rule for this change');
+  }
+
+  return response;
+}
+
+async function resolveEvent(args, options) {
+  if (typeof options.event === 'string') return safeParse(options.event);
+  if (typeof options['event-file'] === 'string') {
+    try {
+      const raw = fs.readFileSync(path.resolve(process.cwd(), options['event-file']), 'utf8');
+      return safeParse(raw);
+    } catch {
+      return null;
+    }
+  }
+  return readStdinEvent();
+}
+
+function safeParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function readStdinEvent() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      resolve(null);
+      return;
+    }
+    let data = '';
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => settle(safeParse(data)));
+    process.stdin.on('error', () => settle(null));
+  });
+}
+
+module.exports = { runContextGuard };

package/src/commands/context-monitor.js

@@ -87,7 +87,7 @@ async function runContextMonitor({ args, options, logger }) {
       if (!options.json) {
         logger.log(`  ${icon} Context: ${tokens.toLocaleString()} tokens (${pct}%) — ${zone.toUpperCase()}`);
         if (zone === 'warning') {
-          logger.log(`  Suggestion: /clear before next agent activation`);
+          logger.log(`  Suggestion: /compact before next agent activation; use /clear only for a hard reset`);
         } else if (zone === 'critical' || zone === 'overflow') {
           logger.log(`  Run: aioson context:health . for reduction options`);
         }

package/src/commands/context-search.js

@@ -1,50 +1,61 @@
-'use strict';
-
-const path = require('node:path');
-const { withIndex } = require('../context-search');
-
-async function runContextSearch({ args, options, logger }) {
-  const query = args[0] || options.query || '';
-  const cwd = path.resolve(process.cwd(), options.cwd || '.');
-  const limit = Number(options.limit) || 10;
-
-  if (!query) {
-    logger.log('Usage: aioson context:search <query> [--limit=10] [--cwd=.]');
-    return { ok: false, error: 'missing_query' };
-  }
-
-  const results = await withIndex(async (idx) => {
-    return idx.search(query, { limit, projectDir: cwd });
-  });
-
-  if (options.json) {
-    return { ok: true, results };
-  }
-
-  if (results.length === 0) {
-    logger.log(`No results for: ${query}`);
-    return { ok: true, results: [] };
-  }
-
-  logger.log(`\n  Search results for: "${query}"\n`);
-  for (let i = 0; i < results.length; i++) {
-    const r = results[i];
-    logger.log(`  ${i + 1}. ${r.title}`);
-    logger.log(`     ${r.relPath}`);
-    if (r.snippet) {
-      logger.log(`     ${r.snippet.replace(/\n/g, ' ')}`);
-    }
-    logger.log('');
-  }
-
-  return { ok: true, results };
-}
-
-async function runContextSearchIndex({ args, options, logger }) {
-  const cwd = path.resolve(process.cwd(), args[0] || '.');
-  const force = Boolean(options.force);
-
-  logger.log(`Indexing: ${cwd} ...`);
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { withIndex } = require('../context-search');
+
+async function runContextSearch({ args, options, logger }) {
+  const { query, cwd } = resolveSearchTarget(args, options);
+  const limit = Number(options.limit) || 10;
+
+  if (!query) {
+    logger.log('Usage: aioson context:search [path] --query="<text>" [--agent=dev] [--mode=executing] [--task="<text>"] [--paths=src/**] [--intent=memory|feature|rules] [--limit=10]');
+    return { ok: false, error: 'missing_query' };
+  }
+
+  const result = await withIndex(async (idx) => {
+    let index = null;
+    if (!options['no-index']) {
+      index = await idx.indexDirectory(cwd, {
+        force: Boolean(options.force || options.refresh)
+      });
+    }
+    const search = idx.searchPackage(query, {
+      limit,
+      projectDir: cwd,
+      agent: options.agent,
+      mode: options.mode,
+      task: options.task || options.goal,
+      paths: options.paths || options.path,
+      intent: options.intent || options.intents,
+      source: options.source || options.sourceType || options['source-type']
+    });
+    return { ...search, index };
+  });
+
+  if (options.json) {
+    return { ok: true, ...result };
+  }
+
+  const results = result.results || [];
+  if (results.length === 0) {
+    logger.log(`No results for: ${query}`);
+    return { ok: true, ...result };
+  }
+
+  logger.log(`\n  Context search for: "${query}"\n`);
+  printBucket(logger, 'Must read', result.package.must_read);
+  printBucket(logger, 'Should read', result.package.should_read);
+  printBucket(logger, 'Maybe', result.package.maybe);
+
+  return { ok: true, ...result };
+}
+
+async function runContextSearchIndex({ args, options, logger }) {
+  const cwd = path.resolve(process.cwd(), args[0] || options.cwd || '.');
+  const force = Boolean(options.force);
+
+  logger.log(`Indexing: ${cwd} ...`);
 
   const result = await withIndex(async (idx) => {
     const r = await idx.indexDirectory(cwd, { force });
@@ -59,8 +70,46 @@ async function runContextSearchIndex({ args, options, logger }) {
   logger.log(`  Indexed: ${result.indexed} files`);
   logger.log(`  Skipped: ${result.skipped} files (already indexed)`);
   logger.log(`  Total in index: ${result.stats.totalDocs} docs`);
-
-  return { ok: true, ...result };
-}
-
-module.exports = { runContextSearch, runContextSearchIndex };
+
+  return { ok: true, ...result };
+}
+
+function resolveSearchTarget(args, options = {}) {
+  let cwd = path.resolve(process.cwd(), options.cwd || '.');
+  let query = String(options.query || options.q || '').trim();
+
+  if (args.length > 0 && query) {
+    cwd = path.resolve(process.cwd(), args[0]);
+  } else if (args.length > 1 && pathExists(path.resolve(process.cwd(), args[0]))) {
+    cwd = path.resolve(process.cwd(), args[0]);
+    query = args.slice(1).join(' ').trim();
+  } else if (!query) {
+    query = args.join(' ').trim();
+  }
+
+  return { cwd, query };
+}
+
+function pathExists(targetPath) {
+  try {
+    fs.accessSync(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function printBucket(logger, title, items) {
+  if (!items || items.length === 0) return;
+  logger.log(`  ${title}:`);
+  for (let i = 0; i < items.length; i++) {
+    const item = items[i];
+    logger.log(`  ${i + 1}. ${item.title} (${item.source_type}, ${item.confidence})`);
+    logger.log(`     ${item.relPath}`);
+    if (item.reason) logger.log(`     reason: ${item.reason}`);
+    if (item.snippet) logger.log(`     ${item.snippet.replace(/\n/g, ' ')}`);
+    logger.log('');
+  }
+}
+
+module.exports = { runContextSearch, runContextSearchIndex, resolveSearchTarget };

package/src/commands/context-select.js

@@ -10,7 +10,9 @@ async function runContextSelect({ args, options = {}, logger }) {
     mode: options.mode || 'planning',
     task: options.task || options.goal || '',
     paths: options.paths || options.path || '',
-    feature: options.feature || options.slug || ''
+    feature: options.feature || options.slug || '',
+    semantic: options.semantic,
+    noSemantic: options.noSemantic || options['no-semantic']
   });
 
   if (options.json) return result;
@@ -19,7 +21,7 @@ async function runContextSelect({ args, options = {}, logger }) {
   if (result.task) logger.log(`Task: ${result.task}`);
   if (result.paths.length > 0) logger.log(`Paths: ${result.paths.join(', ')}`);
   logger.log('Boundary: load only the selected files until the task, mode, feature, or touched paths change.');
-  if (result.selected.length === 0) {
+  if (result.selected.length === 0 && (!result.memory || result.memory.length === 0)) {
     logger.log('No context files selected.');
     return result;
   }
@@ -28,6 +30,13 @@ async function runContextSelect({ args, options = {}, logger }) {
     logger.log(`- ${item.path} [${item.surface}; ${item.load_tier}] ${item.reason}`);
   }
 
+  if (result.memory && result.memory.length > 0) {
+    logger.log('Memory matches:');
+    for (const item of result.memory) {
+      logger.log(`- [${item.target_type}] ${item.target_id} ${item.reason}`);
+    }
+  }
+
   return result;
 }