@jaimevalasek/aioson 1.28.1 → 1.30.0

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;
 }
 

package/src/commands/feature-archive.js

@@ -126,13 +126,26 @@ async function findSlugFiles(ctxDir, slug, otherSlugs = []) {
     .filter((name) => !belongsToOtherSlug(name, slug, otherSlugs));
 }
 
-async function findArchivedFiles(archiveDir) {
-  const entries = await readDirSafe(archiveDir);
-  return entries.filter((e) => e.isFile()).map((e) => e.name);
-}
-
-/**
- * Enumerate every artefact that belongs to a feature slug — the exact surface
+async function findArchivedFiles(archiveDir) {
+  const entries = await readDirSafe(archiveDir);
+  return entries.filter((e) => e.isFile()).map((e) => e.name);
+}
+
+async function removeEmptyDirBestEffort(dir) {
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    try {
+      await fs.rmdir(dir);
+      return;
+    } catch (err) {
+      if (!err || err.code === 'ENOENT' || err.code === 'ENOTEMPTY') return;
+      if (attempt === 3) return;
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+}
+
+/**
+ * Enumerate every artefact that belongs to a feature slug — the exact surface
  * `feature:archive` would move — but as a pure read-only discovery, for
  * non-destructive consumers (e.g. `feature:export`). Never mutates the tree.
  *
@@ -552,11 +565,7 @@ async function runRestore({ slug, ctxDir, archiveDir, manifestPath, dryRun, json
     dossierRestored = path.relative(ctxDir, dossierSourceDir);
   }
 
-  try {
-    await fs.rmdir(archiveDir);
-  } catch {
-    // Directory not empty (manual files) — leave it alone.
-  }
+  await removeEmptyDirBestEffort(archiveDir);
 
   await updateManifest(manifestPath, { slug }, 'remove');
 

package/src/commands/feature-current.js

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * aioson feature:current — resolve the active feature slug deterministically.
+ *
+ * Single source of truth for "which feature is active right now", so every spec
+ * agent (product, sheldon, analyst, ux-ui, scope-check, discovery-design-doc)
+ * resolves the SAME {slug} instead of re-guessing and colliding on bare paths
+ * (design-doc.md, readiness.md, scope-check.md, ui-spec.md, sheldon-enrichment.md).
+ *
+ * Resolution order:
+ *   1. project-pulse.md `active_feature` (when set and not the `(none)` sentinel)
+ *   2. the single `in_progress` row in features.md (unambiguous fallback)
+ *   3. empty — genuine project-level work, no active feature
+ *
+ * When more than one feature is `in_progress`, the result is `ambiguous`: no slug
+ * is guessed, and the caller must disambiguate (ask the user) rather than
+ * silently overwrite another feature's artifact.
+ *
+ * Usage:
+ *   aioson feature:current .            # prints the slug (or nothing) to stdout
+ *   aioson feature:current . --json     # { ok, slug, source, ambiguous, candidates }
+ */
+
+const path = require('node:path');
+const { readProjectPulse, parseFeaturesMap, readFileSafe, contextDir } = require('../preflight-engine');
+
+// Values that mean "no active feature" rather than a real slug.
+const NONE_SENTINELS = new Set(['', '(none)', 'none', 'null', '-', 'n/a']);
+
+function normalizeSlug(value) {
+  return String(value == null ? '' : value).trim();
+}
+
+function isNone(value) {
+  return NONE_SENTINELS.has(normalizeSlug(value).toLowerCase());
+}
+
+async function resolveActiveFeature(targetDir) {
+  // 1. project-pulse.md active_feature — the single source of truth maintained
+  //    by pulse:update and reset by feature:close.
+  const pulse = await readProjectPulse(targetDir);
+  if (pulse && pulse.exists && !isNone(pulse.active_feature)) {
+    return { slug: normalizeSlug(pulse.active_feature), source: 'pulse', ambiguous: false, candidates: [] };
+  }
+
+  // 2. features.md — fall back to the unique in_progress row.
+  const featuresContent = await readFileSafe(path.join(contextDir(targetDir), 'features.md'));
+  const map = parseFeaturesMap(featuresContent);
+  const inProgress = [];
+  for (const [slug, status] of map.entries()) {
+    if (normalizeSlug(status).toLowerCase() === 'in_progress' && !inProgress.includes(slug)) {
+      inProgress.push(slug);
+    }
+  }
+  if (inProgress.length === 1) {
+    return { slug: inProgress[0], source: 'features.md', ambiguous: false, candidates: [] };
+  }
+  if (inProgress.length > 1) {
+    // Ambiguous: more than one feature is open. The caller must disambiguate
+    // (ask the user) rather than silently colliding on a guessed slug.
+    return { slug: '', source: 'features.md', ambiguous: true, candidates: inProgress };
+  }
+
+  // 3. No active feature — genuine project-level work.
+  return { slug: '', source: 'none', ambiguous: false, candidates: [] };
+}
+
+async function runFeatureCurrent({ args = [], options = {}, logger = console } = {}) {
+  const targetDir = args[0] || options.dir || '.';
+  const resolved = await resolveActiveFeature(targetDir);
+  const payload = { ok: true, ...resolved };
+
+  if (!options.json) {
+    // Plain mode prints ONLY the slug so `$(aioson feature:current .)` is
+    // directly usable in shell substitution; ambiguous/none print nothing.
+    if (resolved.slug) logger.log(resolved.slug);
+  }
+  return payload;
+}
+
+module.exports = { runFeatureCurrent, resolveActiveFeature };

package/src/commands/gate-check.js

@@ -12,8 +12,9 @@
  *   aioson gate:check . --feature=checkout --gate=C --json
  */
 
-const path = require('node:path');
-const {
+const path = require('node:path');
+const { auditAcceptanceCriteriaTests } = require('../lib/ac-test-audit');
+const {
   contextDir,
   readFileSafe,
   fileExists,
@@ -104,7 +105,7 @@ async function checkGate(targetDir, slug, gateLetter) {
   }
 
   // Gate D: check for QA sign-off in spec
-  if (gateLetter === 'D') {
+  if (gateLetter === 'D') {
     if (specContent && specContent.includes('## QA Sign-off')) {
       // Check verdict
       const passMatch = specContent.match(/\*\*Verdict:\*\*\s*(PASS|FAIL)/i);
@@ -130,12 +131,23 @@ async function checkGate(targetDir, slug, gateLetter) {
     }
 
     // Also check spec version for explicit gate_execution
-    if (gates.execution && gates.execution !== 'pending') {
-      const gateD = gates.execution;
-      evidence.push({ type: 'gate_field', field: 'gate_execution', value: gateD, ok: gateD === 'approved' });
-      if (gateD !== 'approved') missing.push(`gate_execution: ${gateD}`);
-    }
-  }
+    if (gates.execution && gates.execution !== 'pending') {
+      const gateD = gates.execution;
+      evidence.push({ type: 'gate_field', field: 'gate_execution', value: gateD, ok: gateD === 'approved' });
+      if (gateD !== 'approved') missing.push(`gate_execution: ${gateD}`);
+    }
+
+    const acAudit = await auditAcceptanceCriteriaTests(targetDir, slug);
+    evidence.push({
+      type: 'ac_test_audit',
+      ok: acAudit.ok,
+      summary: acAudit.summary,
+      missing: acAudit.missing
+    });
+    if (!acAudit.ok) {
+      missing.push(`AC test audit failed: missing tests for ${acAudit.missing.join(', ')}`);
+    }
+  }
 
   const allOk = missing.length === 0;
   const result = allOk ? 'PASS' : 'BLOCKED';
@@ -231,15 +243,20 @@ async function runGateCheck({ args, options = {}, logger }) {
     }
   }
 
-  const qaEvidence = check.evidence.filter((e) => e.type === 'qa_signoff' || e.type === 'checkpoint' || e.type === 'gate_field');
+  const qaEvidence = check.evidence.filter((e) => e.type === 'qa_signoff' || e.type === 'checkpoint' || e.type === 'gate_field' || e.type === 'ac_test_audit');
   if (qaEvidence.length > 0) {
     for (const q of qaEvidence) {
       const icon = q.ok ? '  ✓' : '  ✗';
-      if (q.type === 'qa_signoff') logger.log(`${icon} QA sign-off: ${q.exists === false ? 'missing' : `verdict ${q.verdict || 'unclear'}`}`);
-      if (q.type === 'checkpoint') logger.log(`  ✓ last_checkpoint: "${q.value}"`);
-      if (q.type === 'gate_field') logger.log(`${icon} gate_execution: ${q.value}`);
-    }
-  }
+      if (q.type === 'qa_signoff') logger.log(`${icon} QA sign-off: ${q.exists === false ? 'missing' : `verdict ${q.verdict || 'unclear'}`}`);
+      if (q.type === 'checkpoint') logger.log(`  ✓ last_checkpoint: "${q.value}"`);
+      if (q.type === 'gate_field') logger.log(`${icon} gate_execution: ${q.value}`);
+      if (q.type === 'ac_test_audit') {
+        const s = q.summary || {};
+        const missing = q.missing && q.missing.length ? ` (missing: ${q.missing.join(', ')})` : '';
+        logger.log(`${icon} AC test audit: ${s.covered || 0}/${s.acs_total || 0} covered${missing}`);
+      }
+    }
+  }
 
   logger.log('');
   const resultIcon = check.result === 'PASS' ? '✓' : '✗';

package/src/commands/harness-check.js

@@ -97,6 +97,17 @@ async function runHarnessCheck({ args, options = {}, logger, t }) {
     (c) => c && typeof c.verification === 'string' && c.verification.trim()
   );
   const skipped = criteria.length - executable.length;
+  const strict = Boolean(options.strict);
+  const binaryWithoutVerification = criteria.filter(
+    (c) => c && c.binary === true && !(typeof c.verification === 'string' && c.verification.trim())
+  );
+  const strictErrors = [];
+  if (strict && criteria.length > 0 && executable.length === 0) {
+    strictErrors.push('strict mode requires at least one executable verification criterion');
+  }
+  if (strict && binaryWithoutVerification.length > 0) {
+    strictErrors.push(`strict mode requires verification for binary criteria: ${binaryWithoutVerification.map((c) => c.id).join(', ')}`);
+  }
 
   const checks = await runCriteria({ criteria, cwd: targetDir, timeoutMs });
   const failed = checks.filter((c) => !c.ok);
@@ -111,14 +122,16 @@ async function runHarnessCheck({ args, options = {}, logger, t }) {
   }
 
   const report = {
-    ok: failed.length === 0,
+    ok: failed.length === 0 && strictErrors.length === 0,
     slug,
     checked_at: new Date().toISOString(),
+    strict,
     criteria_total: criteria.length,
     executable_total: executable.length,
     passed: checks.length - failed.length,
     failed: failed.length,
     skipped_no_verification: skipped,
+    strict_errors: strictErrors,
     checks
   };
 
@@ -140,6 +153,9 @@ async function runHarnessCheck({ args, options = {}, logger, t }) {
   }
 
   logger.log(t('harness.check_header', { slug }) || `Harness check — ${slug}`);
+  for (const error of strictErrors) {
+    logger.log(`  ✗ ${error}`);
+  }
   if (executable.length === 0) {
     logger.log(t('harness.check_no_executable', { total: criteria.length }) || `  No criteria with verification commands (${criteria.length} criteria total). @validator judges them all.`);
     return report;