@jaimevalasek/aioson 1.28.1 → 1.30.0

package/src/cli.js

@@ -14,6 +14,8 @@ const { runAgentsList, runAgentPrompt } = require('./commands/agents');
 const { runContextValidate } = require('./commands/context-validate');
 const { runContextPack } = require('./commands/context-pack');
 const { runContextSelect } = require('./commands/context-select');
+const { runContextBrief } = require('./commands/context-brief');
+const { runRulesLint } = require('./commands/rules-lint');
 const { runContextLoad } = require('./commands/context-load');
 const { runChainAudit } = require('./commands/chain-audit');
 const { runMemorySearch } = require('./commands/memory-search');
@@ -147,15 +149,17 @@ const { runBackupLocal } = require('./commands/backup-local-cmd');
 const { runRecoveryGenerate, runRecoveryShow } = require('./commands/recovery');
 const { runContextMonitor } = require('./commands/context-monitor');
 const { runContextSearch, runContextSearchIndex } = require('./commands/context-search');
+const { runContextGuard } = require('./commands/context-guard');
 const { runContextCacheList, runContextCacheSave, runContextCacheRestore, runContextCacheCleanup } = require('./commands/context-cache');
 const { runSandboxExec } = require('./commands/sandbox');
 const { runAgentLoad, runAgentShardIndex } = require('./commands/agent-loader');
 const { runLearningEvolve, runLearningApply } = require('./commands/learning-evolve');
 const { runLearningRollback } = require('./commands/learning-rollback');
-const { runToolRegistry } = require('./commands/tool-registry-cmd');
-const { runHealth } = require('./commands/health');
-const { runContextHealth } = require('./commands/context-health');
-const { runContextTrim } = require('./commands/context-trim');
+const { runToolRegistry } = require('./commands/tool-registry-cmd');
+const { runHealth } = require('./commands/health');
+const { runContextHealth } = require('./commands/context-health');
+const { runHygieneScan } = require('./commands/hygiene-scan');
+const { runContextTrim } = require('./commands/context-trim');
 const { runHooksEmit } = require('./commands/hooks-emit');
 const { runHooksInstall, runHooksUninstall } = require('./commands/hooks-install');
 const { runSessionGuard } = require('./commands/session-guard');
@@ -197,12 +201,15 @@ const { runOpMigrate } = require('./commands/op-migrate');
 const { runFeatureClose } = require('./commands/feature-close');
 const { runFeatureArchive, runFeatureSweep } = require('./commands/feature-archive');
 const { runFeatureExport } = require('./commands/feature-export');
+const { runFeatureCurrent } = require('./commands/feature-current');
 const { runDossierInit, runDossierShow, runDossierAddFinding, runDossierAddCodemap, runDossierLinkRule, runDossierCompact } = require('./commands/dossier');
 const { runDossierAddResearch } = require('./commands/dossier-add-research');
 const { runDossierAudit } = require('./commands/dossier-audit');
 const { runDevResumeData } = require('./commands/dev-resume');
-const { runRevisionOpen, runRevisionList, runRevisionResolve } = require('./commands/revision');
-const { runGateCheck } = require('./commands/gate-check');
+const { runRevisionOpen, runRevisionList, runRevisionResolve } = require('./commands/revision');
+const { runAcTestAudit } = require('./commands/ac-test-audit');
+const { runSddBenchmark } = require('./commands/sdd-benchmark');
+const { runGateCheck } = require('./commands/gate-check');
 const { runGateApprove } = require('./commands/gate-approve');
 const { runArtifactValidate } = require('./commands/artifact-validate');
 const { runWorkflowExecute } = require('./commands/workflow-execute');
@@ -257,6 +264,12 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'context-pack',
   'context:select',
   'context-select',
+  'context:brief',
+  'context-brief',
+  'context:guard',
+  'context-guard',
+  'rules:lint',
+  'rules-lint',
   'context:load',
   'context-load',
   'chain:audit',
@@ -275,6 +288,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'workflow-next',
   'workflow:status',
   'workflow-status',
+  'feature:current',
+  'feature-current',
   'harness:retro',
   'harness-retro',
   'harness:preview',
@@ -596,12 +611,16 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'recovery-show',
   'context:monitor',
   'context-monitor',
-  'context:health',
-  'context-health',
-  'context:trim',
+  'context:health',
+  'context-health',
+  'hygiene:scan',
+  'hygiene-scan',
+  'context:trim',
   'context-trim',
   'context:search',
   'context-search',
+  'context:index',
+  'context-index',
   'context:search:index',
   'context-search-index',
   'context:cache',
@@ -666,6 +685,8 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'feature-sweep',
   'feature:export',
   'feature-export',
+  'feature:current',
+  'feature-current',
   'dossier:init',
   'dossier-init',
   'dossier:show',
@@ -688,9 +709,13 @@ const JSON_SUPPORTED_COMMANDS = new Set([
   'revision-open',
   'revision:list',
   'revision-list',
-  'revision:resolve',
-  'revision-resolve',
-  'gate:check',
+  'revision:resolve',
+  'revision-resolve',
+  'ac:test-audit',
+  'ac-test-audit',
+  'sdd:benchmark',
+  'sdd-benchmark',
+  'gate:check',
   'gate-check',
   'gate:approve',
   'gate-approve',
@@ -807,9 +832,10 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_install');
   logHelpLine(t, logger, 'cli.help_setup');
   logHelpLine(t, logger, 'cli.help_update');
-  logHelpLine(t, logger, 'cli.help_info');
-  logHelpLine(t, logger, 'cli.help_doctor');
-  logHelpLine(t, logger, 'cli.help_i18n_add');
+  logHelpLine(t, logger, 'cli.help_info');
+  logHelpLine(t, logger, 'cli.help_doctor');
+  logHelpLine(t, logger, 'cli.help_hygiene_scan');
+  logHelpLine(t, logger, 'cli.help_i18n_add');
   logHelpLine(t, logger, 'cli.help_agents');
   logHelpLine(t, logger, 'cli.help_agent_prompt');
   logHelpLine(t, logger, 'cli.help_agent_help');
@@ -817,7 +843,10 @@ function printHelp(t, logger) {
   logHelpLine(t, logger, 'cli.help_agent_epilogue');
   logHelpLine(t, logger, 'cli.help_context_validate');
   logHelpLine(t, logger, 'cli.help_context_pack');
+  logHelpLine(t, logger, 'cli.help_context_search');
   logHelpLine(t, logger, 'cli.help_context_select');
+  logHelpLine(t, logger, 'cli.help_context_brief');
+  logHelpLine(t, logger, 'cli.help_context_guard');
   logHelpLine(t, logger, 'cli.help_context_load');
   logHelpLine(t, logger, 'cli.help_memory_status');
   logHelpLine(t, logger, 'cli.help_memory_summary');
@@ -1105,6 +1134,12 @@ async function main() {
       result = await runContextPack({ args, options, logger: commandLogger, t });
     } else if (command === 'context:select' || command === 'context-select') {
       result = await runContextSelect({ args, options, logger: commandLogger, t });
+    } else if (command === 'context:brief' || command === 'context-brief') {
+      result = await runContextBrief({ args, options, logger: commandLogger, t });
+    } else if (command === 'context:guard' || command === 'context-guard') {
+      result = await runContextGuard({ args, options, logger: commandLogger, t });
+    } else if (command === 'rules:lint' || command === 'rules-lint') {
+      result = await runRulesLint({ args, options, logger: commandLogger, t });
     } else if (command === 'context:load' || command === 'context-load') {
       result = await runContextLoad({ args, options, logger: commandLogger, t });
     } else if (command === 'chain:audit' || command === 'chain-audit') {
@@ -1505,13 +1540,20 @@ async function main() {
       result = await runRecoveryShow({ args, options, logger: commandLogger, t });
     } else if (command === 'context:monitor' || command === 'context-monitor') {
       result = await runContextMonitor({ args, options, logger: commandLogger, t });
-    } else if (command === 'context:health' || command === 'context-health') {
-      result = await runContextHealth({ args, options, logger: commandLogger });
-    } else if (command === 'context:trim' || command === 'context-trim') {
-      result = await runContextTrim({ args, options, logger: commandLogger });
+    } else if (command === 'context:health' || command === 'context-health') {
+      result = await runContextHealth({ args, options, logger: commandLogger });
+    } else if (command === 'hygiene:scan' || command === 'hygiene-scan') {
+      result = await runHygieneScan({ args, options, logger: commandLogger });
+    } else if (command === 'context:trim' || command === 'context-trim') {
+      result = await runContextTrim({ args, options, logger: commandLogger });
     } else if (command === 'context:search' || command === 'context-search') {
       result = await runContextSearch({ args, options, logger: commandLogger, t });
-    } else if (command === 'context:search:index' || command === 'context-search-index') {
+    } else if (
+      command === 'context:index' ||
+      command === 'context-index' ||
+      command === 'context:search:index' ||
+      command === 'context-search-index'
+    ) {
       result = await runContextSearchIndex({ args, options, logger: commandLogger, t });
     } else if (command === 'context:cache' || command === 'context-cache') {
       result = await runContextCacheList({ args, options, logger: commandLogger, t });
@@ -1591,6 +1633,8 @@ async function main() {
       result = await runFeatureSweep({ args, options, logger: commandLogger });
     } else if (command === 'feature:export' || command === 'feature-export') {
       result = await runFeatureExport({ args, options, logger: commandLogger });
+    } else if (command === 'feature:current' || command === 'feature-current') {
+      result = await runFeatureCurrent({ args, options, logger: commandLogger });
     } else if (command === 'dossier:init' || command === 'dossier-init') {
       result = await runDossierInit({ args, options, logger: commandLogger });
     } else if (command === 'dossier:show' || command === 'dossier-show') {
@@ -1613,10 +1657,14 @@ async function main() {
       result = await runRevisionOpen({ args, options, logger: commandLogger });
     } else if (command === 'revision:list' || command === 'revision-list') {
       result = await runRevisionList({ args, options, logger: commandLogger });
-    } else if (command === 'revision:resolve' || command === 'revision-resolve') {
-      result = await runRevisionResolve({ args, options, logger: commandLogger });
-    } else if (command === 'gate:check' || command === 'gate-check') {
-      result = await runGateCheck({ args, options, logger: commandLogger });
+    } else if (command === 'revision:resolve' || command === 'revision-resolve') {
+      result = await runRevisionResolve({ args, options, logger: commandLogger });
+    } else if (command === 'ac:test-audit' || command === 'ac-test-audit') {
+      result = await runAcTestAudit({ args, options, logger: commandLogger });
+    } else if (command === 'sdd:benchmark' || command === 'sdd-benchmark') {
+      result = await runSddBenchmark({ args, options, logger: commandLogger });
+    } else if (command === 'gate:check' || command === 'gate-check') {
+      result = await runGateCheck({ args, options, logger: commandLogger });
     } else if (command === 'gate:approve' || command === 'gate-approve') {
       result = await runGateApprove({ args, options, logger: commandLogger });
     } else if (command === 'artifact:validate' || command === 'artifact-validate') {

package/src/commands/ac-test-audit.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const path = require('node:path');
+const { auditAcceptanceCriteriaTests } = require('../lib/ac-test-audit');
+
+async function runAcTestAudit({ args, options = {}, logger }) {
+  const targetDir = path.resolve(process.cwd(), args?.[0] || '.');
+  const slug = String(options.feature || options.slug || '').trim();
+
+  if (!slug) {
+    if (options.json) return { ok: false, error: 'missing_feature' };
+    logger.error('--feature=<slug> is required.');
+    return { ok: false, error: 'missing_feature' };
+  }
+
+  const report = await auditAcceptanceCriteriaTests(targetDir, slug);
+
+  if (options.json) {
+    logger.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  logger.log('');
+  logger.log(`AC test audit — ${slug}`);
+  logger.log('━'.repeat(45));
+  logger.log(`ACs: ${report.summary.covered}/${report.summary.acs_total} covered; tests scanned: ${report.summary.test_files_scanned}`);
+
+  if (report.summary.acs_total === 0) {
+    logger.log('No acceptance criteria IDs found in requirements, PRD, or conformance artifacts.');
+  } else {
+    for (const item of report.items) {
+      const mark = item.status === 'covered' ? '✓' : '✗';
+      const evidence = item.evidence.length
+        ? ` — ${item.evidence.map((e) => e.file).join(', ')}`
+        : '';
+      logger.log(`  ${mark} ${item.ac}: ${item.status}${evidence}`);
+    }
+  }
+
+  logger.log('');
+  logger.log(report.ok ? 'Result: PASS' : `Result: BLOCKED — missing tests for ${report.missing.join(', ')}`);
+  return report;
+}
+
+module.exports = { runAcTestAudit };

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