@nerviq/cli 1.26.0 → 1.27.1

package/src/audit/layers.js

@@ -1,179 +1,180 @@
-/**
- * CTO-08 — 5-layer scope clarity.
- *
- * Every check in the NERVIQ audit is tagged with exactly one layer so
- * customers and evaluators get an explicit map of what NERVIQ covers and
- * what it does not. The 4 positive layers below intentionally exclude any
- * "deep-review" / general-security-scanning lane: NERVIQ is an
- * agent-configuration audit tool, not a code-review tool.
- *
- * Taxonomy (canonical — mirrored in docs/integration-contracts.md §8):
- *
- *   governance   — Agent configuration posture: presence, content, and
- *                  quality of agent-instruction files and platform
- *                  settings. Answers "does my agent know X?".
- *
- *   drift        — Cross-platform consistency: do multiple platform
- *                  configs agree? Does the declared state match the
- *                  repo reality? Answers "do two places agree on X?".
- *
- *   hygiene      — Repo-level cleanliness and operational basics
- *                  adjacent to agents (gitignore, CHANGELOG, SECURITY.md,
- *                  CI, Dependabot, license, editorconfig, Node version
- *                  pinning, etc.). Answers "does the repo have standard
- *                  engineering hygiene that makes the agent's job
- *                  easier?".
- *
- *   shallow-risk — Reserved for CTO-06. No checks currently live in
- *                  this layer; the constant exists so formatters and
- *                  types know about it.
- *
- * Disambiguation rule-of-thumb when a check could plausibly belong to
- * more than one layer: prefer the most specific layer (drift > hygiene
- * > governance). If in doubt, default to hygiene — a mild
- * misclassification is recoverable; a missing tag breaks the coverage
- * test.
- */
-
-'use strict';
-
-const LAYERS = Object.freeze({
-  GOVERNANCE: 'governance',
-  DRIFT: 'drift',
-  HYGIENE: 'hygiene',
-  SHALLOW_RISK: 'shallow-risk',
-});
-
-const LAYER_DEFINITIONS = Object.freeze({
-  [LAYERS.GOVERNANCE]: 'Agent configuration posture: presence, content, and quality of agent-instruction files and platform settings.',
-  [LAYERS.DRIFT]: 'Cross-platform consistency: do multiple platform configs agree, and does the declared state match repo reality?',
-  [LAYERS.HYGIENE]: 'Repo-level cleanliness and operational basics adjacent to agents (gitignore, CHANGELOG, SECURITY.md, CI, license, etc.).',
-  [LAYERS.SHALLOW_RISK]: 'Reserved for shallow-risk boundary checks (CTO-06). No checks currently populate this layer.',
-});
-
-const VALID_LAYER_VALUES = new Set(Object.values(LAYERS));
-
-function isValidLayer(value) {
-  return typeof value === 'string' && VALID_LAYER_VALUES.has(value);
-}
-
-/**
- * Name/id patterns that strongly indicate a drift check. Applied only as
- * a heuristic when tagging existing check bags (see assignLayers).
- */
-const DRIFT_PATTERNS = [
-  /drift/i,
-  /harmony/i,
-  /\bpropagation\b/i,
-  /consisten(t|cy)/i,
-  /cross[- ]?platform/i,
-  /across (surfaces|platforms|all .* surfaces)/i,
-  /\bpacks are consistent\b/i,
-  /propagation (checklist|completeness|delay)/i,
-];
-
-/**
- * Hygiene name patterns — used to upgrade a check from a default
- * governance bag into hygiene when the check is clearly about repo
- * engineering hygiene rather than agent config.
- */
-const HYGIENE_PATTERNS = [
-  /\.gitignore/i,
-  /\bCHANGELOG\b/i,
-  /\bCONTRIBUTING\b/i,
-  /\bLICENSE\b/i,
-  /\.editorconfig/i,
-  /\bEditorConfig\b/i,
-  /\bSECURITY\.md\b/i,
-  /\bCODE_OF_CONDUCT\b/i,
-  /\bDependabot\b/i,
-  /\bNode version pinned\b/i,
-  /\bREADME\b.*\b(install|usage|contributing|sections|section)\b/i,
-  /\blockfile\b/i,
-  /\bcargo-audit\b/i,
-  /\bDockerfile\b/i,
-  /\bCI (is configured|configured|pipeline|workflow)/i,
-  /\bGitHub Actions\b/i,
-  /\b\.github\/workflows\b/i,
-  /\bpre-commit\b/i,
-  /\b(poetry|uv|pipenv|npm|pnpm|yarn|bun)\.lock/i,
-  /\brenovate\b/i,
-  /\bsemver\b/i,
-  /\brelease automation\b/i,
-];
-
-/**
- * Check categories that strongly indicate repo-hygiene rather than
- * agent-configuration. These cover the stack-specific engineering
- * baselines (Python lockfile, Rust target/ in .gitignore, etc.) that
- * ship via the stacks checks.
- */
-const HYGIENE_CATEGORIES = new Set([
-  'dependency-management', 'supply-chain', 'release-freshness',
-  'docker', 'ci', 'ci-cd',
-  'git', // the cross-platform hygiene.js checks live here
-]);
-
-function inferLayerForCheck(check, defaultLayer) {
-  const probe = `${check.name || ''} ${check.id || ''} ${check.key || ''}`;
-  if (DRIFT_PATTERNS.some((re) => re.test(probe))) return LAYERS.DRIFT;
-  if (defaultLayer === LAYERS.GOVERNANCE) {
-    if (HYGIENE_PATTERNS.some((re) => re.test(probe))) return LAYERS.HYGIENE;
-    if (check.category && HYGIENE_CATEGORIES.has(check.category)) return LAYERS.HYGIENE;
-  }
-  return defaultLayer;
-}
-
-/**
- * Mutates `bag` (a technique dictionary of { key: { name, id, ... } })
- * so every entry has a `layer` field. Existing `layer` values on
- * individual checks are respected.
- *
- * @param {Object} bag            technique dictionary
- * @param {string} defaultLayer   one of LAYERS.*, used when heuristics don't fire
- * @returns {Object} the same bag, for chaining
- */
-function assignLayers(bag, defaultLayer = LAYERS.GOVERNANCE) {
-  if (!bag || typeof bag !== 'object') return bag;
-  if (!isValidLayer(defaultLayer)) {
-    throw new Error(`assignLayers: invalid defaultLayer "${defaultLayer}"`);
-  }
-  for (const [key, check] of Object.entries(bag)) {
-    if (!check || typeof check !== 'object') continue;
-    if (isValidLayer(check.layer)) continue;
-    const withKey = { ...check, key };
-    check.layer = inferLayerForCheck(withKey, defaultLayer);
-  }
-  return bag;
-}
-
-/**
- * Summary helper — counts checks per layer in a results array. Used by
- * the audit text renderer and by the coverage test.
- */
-function summarizeLayers(results) {
-  const summary = {
-    [LAYERS.GOVERNANCE]: { total: 0, passed: 0, failed: 0, skipped: 0 },
-    [LAYERS.DRIFT]: { total: 0, passed: 0, failed: 0, skipped: 0 },
-    [LAYERS.HYGIENE]: { total: 0, passed: 0, failed: 0, skipped: 0 },
-    [LAYERS.SHALLOW_RISK]: { total: 0, passed: 0, failed: 0, skipped: 0 },
-  };
-  for (const r of results || []) {
-    const layer = isValidLayer(r.layer) ? r.layer : LAYERS.HYGIENE;
-    const bucket = summary[layer];
-    bucket.total += 1;
-    if (r.passed === true) bucket.passed += 1;
-    else if (r.passed === false) bucket.failed += 1;
-    else bucket.skipped += 1;
-  }
-  return summary;
-}
-
-module.exports = {
-  LAYERS,
-  LAYER_DEFINITIONS,
-  isValidLayer,
-  assignLayers,
-  summarizeLayers,
-  inferLayerForCheck,
-};
+/**
+ * CTO-08 — 5-layer scope clarity.
+ *
+ * Every check in the NERVIQ audit is tagged with exactly one layer so
+ * customers and evaluators get an explicit map of what NERVIQ covers and
+ * what it does not. The 4 positive layers below intentionally exclude any
+ * "deep-review" / general-security-scanning lane: NERVIQ is an
+ * agent-configuration audit tool, not a code-review tool.
+ *
+ * Taxonomy (canonical — mirrored in docs/integration-contracts.md §8):
+ *
+ *   governance   — Agent configuration posture: presence, content, and
+ *                  quality of agent-instruction files and platform
+ *                  settings. Answers "does my agent know X?".
+ *
+ *   drift        — Cross-platform consistency: do multiple platform
+ *                  configs agree? Does the declared state match the
+ *                  repo reality? Answers "do two places agree on X?".
+ *
+ *   hygiene      — Repo-level cleanliness and operational basics
+ *                  adjacent to agents (gitignore, CHANGELOG, SECURITY.md,
+ *                  CI, Dependabot, license, editorconfig, Node version
+ *                  pinning, etc.). Answers "does the repo have standard
+ *                  engineering hygiene that makes the agent's job
+ *                  easier?".
+ *
+ *   shallow-risk — Parallel, opt-in boundary checks that sit at the
+ *                  agent-config <-> codebase edge. Findings are emitted
+ *                  through `auditResult.shallowRiskHints[]` and are not
+ *                  folded into governance scoring.
+ *
+ * Disambiguation rule-of-thumb when a check could plausibly belong to
+ * more than one layer: prefer the most specific layer (drift > hygiene
+ * > governance). If in doubt, default to hygiene — a mild
+ * misclassification is recoverable; a missing tag breaks the coverage
+ * test.
+ */
+
+'use strict';
+
+const LAYERS = Object.freeze({
+  GOVERNANCE: 'governance',
+  DRIFT: 'drift',
+  HYGIENE: 'hygiene',
+  SHALLOW_RISK: 'shallow-risk',
+});
+
+const LAYER_DEFINITIONS = Object.freeze({
+  [LAYERS.GOVERNANCE]: 'Agent configuration posture: presence, content, and quality of agent-instruction files and platform settings.',
+  [LAYERS.DRIFT]: 'Cross-platform consistency: do multiple platform configs agree, and does the declared state match repo reality?',
+  [LAYERS.HYGIENE]: 'Repo-level cleanliness and operational basics adjacent to agents (gitignore, CHANGELOG, SECURITY.md, CI, license, etc.).',
+  [LAYERS.SHALLOW_RISK]: 'Parallel, opt-in boundary checks emitted via auditResult.shallowRiskHints[]; shown separately and excluded from governance scoring.',
+});
+
+const VALID_LAYER_VALUES = new Set(Object.values(LAYERS));
+
+function isValidLayer(value) {
+  return typeof value === 'string' && VALID_LAYER_VALUES.has(value);
+}
+
+/**
+ * Name/id patterns that strongly indicate a drift check. Applied only as
+ * a heuristic when tagging existing check bags (see assignLayers).
+ */
+const DRIFT_PATTERNS = [
+  /drift/i,
+  /harmony/i,
+  /\bpropagation\b/i,
+  /consisten(t|cy)/i,
+  /cross[- ]?platform/i,
+  /across (surfaces|platforms|all .* surfaces)/i,
+  /\bpacks are consistent\b/i,
+  /propagation (checklist|completeness|delay)/i,
+];
+
+/**
+ * Hygiene name patterns — used to upgrade a check from a default
+ * governance bag into hygiene when the check is clearly about repo
+ * engineering hygiene rather than agent config.
+ */
+const HYGIENE_PATTERNS = [
+  /\.gitignore/i,
+  /\bCHANGELOG\b/i,
+  /\bCONTRIBUTING\b/i,
+  /\bLICENSE\b/i,
+  /\.editorconfig/i,
+  /\bEditorConfig\b/i,
+  /\bSECURITY\.md\b/i,
+  /\bCODE_OF_CONDUCT\b/i,
+  /\bDependabot\b/i,
+  /\bNode version pinned\b/i,
+  /\bREADME\b.*\b(install|usage|contributing|sections|section)\b/i,
+  /\blockfile\b/i,
+  /\bcargo-audit\b/i,
+  /\bDockerfile\b/i,
+  /\bCI (is configured|configured|pipeline|workflow)/i,
+  /\bGitHub Actions\b/i,
+  /\b\.github\/workflows\b/i,
+  /\bpre-commit\b/i,
+  /\b(poetry|uv|pipenv|npm|pnpm|yarn|bun)\.lock/i,
+  /\brenovate\b/i,
+  /\bsemver\b/i,
+  /\brelease automation\b/i,
+];
+
+/**
+ * Check categories that strongly indicate repo-hygiene rather than
+ * agent-configuration. These cover the stack-specific engineering
+ * baselines (Python lockfile, Rust target/ in .gitignore, etc.) that
+ * ship via the stacks checks.
+ */
+const HYGIENE_CATEGORIES = new Set([
+  'dependency-management', 'supply-chain', 'release-freshness',
+  'docker', 'ci', 'ci-cd',
+  'git', // the cross-platform hygiene.js checks live here
+]);
+
+function inferLayerForCheck(check, defaultLayer) {
+  const probe = `${check.name || ''} ${check.id || ''} ${check.key || ''}`;
+  if (DRIFT_PATTERNS.some((re) => re.test(probe))) return LAYERS.DRIFT;
+  if (defaultLayer === LAYERS.GOVERNANCE) {
+    if (HYGIENE_PATTERNS.some((re) => re.test(probe))) return LAYERS.HYGIENE;
+    if (check.category && HYGIENE_CATEGORIES.has(check.category)) return LAYERS.HYGIENE;
+  }
+  return defaultLayer;
+}
+
+/**
+ * Mutates `bag` (a technique dictionary of { key: { name, id, ... } })
+ * so every entry has a `layer` field. Existing `layer` values on
+ * individual checks are respected.
+ *
+ * @param {Object} bag            technique dictionary
+ * @param {string} defaultLayer   one of LAYERS.*, used when heuristics don't fire
+ * @returns {Object} the same bag, for chaining
+ */
+function assignLayers(bag, defaultLayer = LAYERS.GOVERNANCE) {
+  if (!bag || typeof bag !== 'object') return bag;
+  if (!isValidLayer(defaultLayer)) {
+    throw new Error(`assignLayers: invalid defaultLayer "${defaultLayer}"`);
+  }
+  for (const [key, check] of Object.entries(bag)) {
+    if (!check || typeof check !== 'object') continue;
+    if (isValidLayer(check.layer)) continue;
+    const withKey = { ...check, key };
+    check.layer = inferLayerForCheck(withKey, defaultLayer);
+  }
+  return bag;
+}
+
+/**
+ * Summary helper — counts checks per layer in a results array. Used by
+ * the audit text renderer and by the coverage test.
+ */
+function summarizeLayers(results) {
+  const summary = {
+    [LAYERS.GOVERNANCE]: { total: 0, passed: 0, failed: 0, skipped: 0 },
+    [LAYERS.DRIFT]: { total: 0, passed: 0, failed: 0, skipped: 0 },
+    [LAYERS.HYGIENE]: { total: 0, passed: 0, failed: 0, skipped: 0 },
+    [LAYERS.SHALLOW_RISK]: { total: 0, passed: 0, failed: 0, skipped: 0 },
+  };
+  for (const r of results || []) {
+    const layer = isValidLayer(r.layer) ? r.layer : LAYERS.HYGIENE;
+    const bucket = summary[layer];
+    bucket.total += 1;
+    if (r.passed === true) bucket.passed += 1;
+    else if (r.passed === false) bucket.failed += 1;
+    else bucket.skipped += 1;
+  }
+  return summary;
+}
+
+module.exports = {
+  LAYERS,
+  LAYER_DEFINITIONS,
+  isValidLayer,
+  assignLayers,
+  summarizeLayers,
+  inferLayerForCheck,
+};

package/src/audit.js

@@ -37,6 +37,7 @@ const { detectDeprecationWarnings } = require('./deprecation');
 const { buildWorkspaceHint, formatCount, guardSkippedInstructionFiles, inspectInstructionFiles } = require('./audit/instruction-files');
 const { resolveEvidence } = require('./audit/evidence');
 const { LAYERS, summarizeLayers } = require('./audit/layers');
+const { runShallowRisk, SHALLOW_RISK_BANNER_LINES } = require('./shallow-risk');
 const {
   WEIGHTS,
   buildScoreCoaching,
@@ -78,6 +79,54 @@ function formatLocation(file, line) {
   return line ? `${file}:${line}` : file;
 }
 
+function hasShallowRiskData(result) {
+  return Boolean(result) && Object.prototype.hasOwnProperty.call(result, 'shallowRiskHints');
+}
+
+function printShallowRiskSection(result) {
+  if (!hasShallowRiskData(result)) return;
+
+  const hints = Array.isArray(result.shallowRiskHints) ? result.shallowRiskHints : [];
+  console.log(colorize('  Shallow Risk Hints (experimental, opt-in)', 'yellow'));
+  for (const line of SHALLOW_RISK_BANNER_LINES) {
+    console.log(colorize(`     ${line}`, 'dim'));
+  }
+  console.log('');
+
+  if (hints.length === 0) {
+    console.log(colorize('     No shallow-risk hints found.', 'green'));
+    console.log('');
+    return;
+  }
+
+  for (const hint of hints) {
+    const severity = (hint.severity || 'medium').toUpperCase();
+    console.log(`     ${colorize(`[${severity}]`, 'bold')} ${hint.name}`);
+    if (hint.file) {
+      console.log(colorize(`     at ${formatLocation(hint.file, hint.line)}`, 'dim'));
+    }
+    if (hint.fix) {
+      console.log(colorize(`     -> ${hint.fix}`, 'dim'));
+    }
+  }
+  console.log('');
+}
+
+function printShallowRiskOnly(result, dir) {
+  console.log('');
+  console.log(colorize('  Nerviq Shallow Risk', 'bold'));
+  console.log(colorize('  ═══════════════════════════════════════', 'dim'));
+  console.log(colorize(`  ${t('audit.scanning', { dir })}`, 'dim'));
+  console.log('');
+  if (result.detectedConfigFiles && result.detectedConfigFiles.length > 0) {
+    console.log(colorize(`  Found: ${result.detectedConfigFiles.join(', ')}`, 'dim'));
+    console.log('');
+  }
+  printShallowRiskSection(result);
+  console.log(`  Next: ${colorize('nerviq audit --shallow-risk --full', 'bold')}`);
+  console.log('');
+}
+
 function getAuditSpec(platform = 'claude') {
   if (platform === 'codex') {
     return {
@@ -299,6 +348,7 @@ function printLiteAudit(result, dir) {
   if (result.failed === 0) {
     const platformLabel = result.platform === 'codex' ? 'Codex' : 'Claude';
     console.log(colorize(`  Your ${platformLabel} setup looks solid.`, 'green'));
+    printShallowRiskSection(result);
     console.log(`  Next: ${colorize(result.suggestedNextCommand, 'bold')}`);
     if (result.platform === 'codex') {
       console.log(colorize('  Note: Codex now supports no-write advisory flows via augment and suggest-only before setup/apply.', 'dim'));
@@ -333,6 +383,7 @@ function printLiteAudit(result, dir) {
     console.log(colorize(`     ${item.fix}`, 'dim'));
   });
   console.log('');
+  printShallowRiskSection(result);
   const liteTerminology = formatTerminologyLines(collectAuditTerminology(result));
   if (liteTerminology.length > 0) {
     liteTerminology.forEach((line) => {
@@ -365,8 +416,12 @@ async function audit(options) {
   const spec = getAuditSpec(options.platform || 'claude');
   const silent = options.silent || false;
   const ctx = new spec.ContextClass(options.dir);
-  const largeInstructionFiles = inspectInstructionFiles(spec, ctx);
-  guardSkippedInstructionFiles(ctx, largeInstructionFiles);
+  const shallowRiskEnabled = Boolean(options.shallowRisk) && process.env.NERVIQ_SHALLOW_RISK !== 'off';
+  const shallowRiskOnly = Boolean(options.shallowRiskOnly) && shallowRiskEnabled;
+  const largeInstructionFiles = shallowRiskOnly ? [] : inspectInstructionFiles(spec, ctx);
+  if (!shallowRiskOnly) {
+    guardSkippedInstructionFiles(ctx, largeInstructionFiles);
+  }
   const stacks = ctx.detectStacks(STACKS);
   const results = [];
   const outcomeSummary = getRecommendationOutcomeSummary(options.dir);
@@ -397,46 +452,48 @@ async function audit(options) {
   const includeGenericQuality = options.verbose;
 
   // Run all technique checks
-  for (const [key, technique] of Object.entries(techniques)) {
-    // Skip entire stack category if the stack is not detected at a core location
-    // Skip generic quality categories unless --verbose is set
-    const cat = technique.category;
-    if ((!includeGenericQuality && GENERIC_QUALITY_CATEGORIES.has(cat)) ||
-        (STACK_CATEGORY_DETECTORS[cat] && !activeStackCategories.has(cat))) {
+  if (!shallowRiskOnly) {
+    for (const [key, technique] of Object.entries(techniques)) {
+      // Skip entire stack category if the stack is not detected at a core location
+      // Skip generic quality categories unless --verbose is set
+      const cat = technique.category;
+      if ((!includeGenericQuality && GENERIC_QUALITY_CATEGORIES.has(cat)) ||
+          (STACK_CATEGORY_DETECTORS[cat] && !activeStackCategories.has(cat))) {
+        results.push({
+          key,
+          ...technique,
+          file: null,
+          line: null,
+          passed: null, // not applicable
+        });
+        continue;
+      }
+
+      const passed = technique.check(ctx);
+      let file = typeof technique.file === 'function' ? (technique.file(ctx) ?? null) : (technique.file ?? null);
+      let line = typeof technique.line === 'function' ? (technique.line(ctx) ?? null) : (technique.line ?? null);
+      let snippet = null;
+      // CTO-04: only compute evidence on failed checks (cheap, and only where it adds trust).
+      if (passed === false) {
+        const evidence = resolveEvidence(key, ctx, { file, line });
+        if (evidence) {
+          file = evidence.file;
+          line = evidence.line;
+          snippet = evidence.snippet;
+        }
+      }
       results.push({
         key,
         ...technique,
-        file: null,
-        line: null,
-        passed: null, // not applicable
+        file,
+        line: Number.isFinite(line) ? line : null,
+        snippet,
+        passed,
       });
-      continue;
     }
-
-    const passed = technique.check(ctx);
-    let file = typeof technique.file === 'function' ? (technique.file(ctx) ?? null) : (technique.file ?? null);
-    let line = typeof technique.line === 'function' ? (technique.line(ctx) ?? null) : (technique.line ?? null);
-    let snippet = null;
-    // CTO-04: only compute evidence on failed checks (cheap, and only where it adds trust).
-    if (passed === false) {
-      const evidence = resolveEvidence(key, ctx, { file, line });
-      if (evidence) {
-        file = evidence.file;
-        line = evidence.line;
-        snippet = evidence.snippet;
-      }
-    }
-    results.push({
-      key,
-      ...technique,
-      file,
-      line: Number.isFinite(line) ? line : null,
-      snippet,
-      passed,
-    });
   }
 
-  if (largeInstructionFiles.length > 0) {
+  if (!shallowRiskOnly && largeInstructionFiles.length > 0) {
     results.push({
       key: 'largeInstructionFile',
       id: null,
@@ -505,8 +562,10 @@ async function audit(options) {
   const scaffoldedPassed = passed.filter(r => scaffoldedKeys.has(r.key));
   const organicEarned = organicPassed.reduce((sum, r) => sum + (WEIGHTS[r.impact] || 5), 0);
   const organicScore = maxScore > 0 ? Math.round((organicEarned / maxScore) * 100) : 0;
-  const quickWins = getQuickWins(failed, { platform: spec.platform });
-  const topNextActions = buildTopNextActions(failed, 5, outcomeSummary.byKey, { platform: spec.platform, fpFeedbackByKey: fpFeedback.byKey });
+  const quickWins = shallowRiskOnly ? [] : getQuickWins(failed, { platform: spec.platform });
+  const topNextActions = shallowRiskOnly
+    ? []
+    : buildTopNextActions(failed, 5, outcomeSummary.byKey, { platform: spec.platform, fpFeedbackByKey: fpFeedback.byKey });
 
   // CTO-04: enrich top actions with file/line/snippet from the corresponding
   // result record (evidence was resolved above during the check loop).
@@ -536,10 +595,10 @@ async function audit(options) {
       action.projectedOrganicScoreDelta = 0;
     }
   }
-  const categoryScores = computeCategoryScores(applicable, passed);
-  const platformScopeNote = getPlatformScopeNote(spec, ctx);
-  const platformCaveats = getPlatformCaveats(spec, ctx);
-  const deprecationWarnings = detectDeprecationWarnings(failed, packageVersion);
+  const categoryScores = shallowRiskOnly ? {} : computeCategoryScores(applicable, passed);
+  const platformScopeNote = shallowRiskOnly ? null : getPlatformScopeNote(spec, ctx);
+  const platformCaveats = shallowRiskOnly ? [] : getPlatformCaveats(spec, ctx);
+  const deprecationWarnings = shallowRiskOnly ? [] : detectDeprecationWarnings(failed, packageVersion);
   const warnings = [
     ...largeInstructionFiles.map((item) => ({
       kind: 'large-instruction-file',
@@ -557,7 +616,7 @@ async function audit(options) {
       ...item,
     })),
   ];
-  const recommendedDomainPacks = spec.platform === 'codex'
+  const recommendedDomainPacks = !shallowRiskOnly && spec.platform === 'codex'
     ? detectCodexDomainPacks(ctx, stacks, getCodexDomainPackSignals(ctx))
     : [];
 
@@ -568,7 +627,7 @@ async function audit(options) {
     stackKeys.has('nextjs') || stackKeys.has('angular') || stackKeys.has('svelte') ||
     stackKeys.has('nestjs') || stackKeys.has('remix') || stackKeys.has('astro') ||
     stackKeys.has('typescript') || stackKeys.has('deno') || stackKeys.has('bun');
-  if (!hasNodeStack) {
+  if (!shallowRiskOnly && !hasNodeStack) {
     let preferredTest = null;
     let preferredInstall = null;
     if (stackKeys.has('python') || stackKeys.has('django') || stackKeys.has('fastapi')) {
@@ -620,7 +679,7 @@ async function audit(options) {
       sunsetDate: r.sunsetDate || null,
     })),
     categoryScores,
-    scoreCoaching: buildScoreCoaching({
+    scoreCoaching: shallowRiskOnly ? null : buildScoreCoaching({
       score,
       earnedPoints: earnedScore,
       maxPoints: maxScore,
@@ -645,6 +704,9 @@ async function audit(options) {
     // CTO-08: per-layer coverage summary (governance/drift/hygiene/shallow-risk).
     layerSummary: summarizeLayers(activeResults),
   };
+  if (shallowRiskEnabled) {
+    result.shallowRiskHints = runShallowRisk(ctx);
+  }
   // Detect which AI config files are present
   const configFiles = [];
   const configChecks = [
@@ -661,7 +723,9 @@ async function audit(options) {
   }
   result.detectedConfigFiles = configFiles;
 
-  result.suggestedNextCommand = inferSuggestedNextCommand(result);
+  result.suggestedNextCommand = shallowRiskOnly
+    ? 'nerviq audit --shallow-risk --full'
+    : inferSuggestedNextCommand(result);
   result.liteSummary = {
     topNextActions: topNextActions.slice(0, 3),
     nextCommand: result.suggestedNextCommand,
@@ -710,6 +774,11 @@ async function audit(options) {
     return result;
   }
 
+  if (shallowRiskOnly) {
+    printShallowRiskOnly(result, options.dir);
+    return result;
+  }
+
   if (options.lite) {
     printLiteAudit(result, options.dir);
     sendInsights(result);
@@ -798,9 +867,8 @@ async function audit(options) {
   const layerOrder = [LAYERS.GOVERNANCE, LAYERS.DRIFT, LAYERS.HYGIENE, LAYERS.SHALLOW_RISK];
   for (const layer of layerOrder) {
     const b = layerSummary[layer] || { total: 0, passed: 0, failed: 0, skipped: 0 };
-    const reservedNote = layer === LAYERS.SHALLOW_RISK && b.total === 0
-      ? ' (reserved for --shallow-risk)' : '';
-    console.log(colorize(`     ${layer}: ${b.total} checks (${b.passed} passed, ${b.failed} failed)${reservedNote}`, 'dim'));
+    const layerNote = layer === LAYERS.SHALLOW_RISK ? ' (parallel, opt-in, not scored)' : '';
+    console.log(colorize(`     ${layer}: ${b.total} checks (${b.passed} passed, ${b.failed} failed)${layerNote}`, 'dim'));
   }
   console.log('');
 
@@ -895,6 +963,8 @@ async function audit(options) {
     console.log('');
   }
 
+  printShallowRiskSection(result);
+
   const terminology = formatTerminologyLines(collectAuditTerminology(result));
   if (terminology.length > 0) {
     terminology.forEach((line) => {