@nerviq/cli 1.26.0 → 1.27.0

package/README.md

@@ -77,9 +77,9 @@ Every Nerviq check is tagged with one of four explicit layers so you know exactl
 - **governance** — agent configuration posture: presence, content, and quality of agent-instruction files and platform settings.
 - **drift** — cross-platform consistency: do your configured platforms agree, and does declared state match repo reality?
 - **hygiene** — repo-level cleanliness adjacent to agents (gitignore, CHANGELOG, SECURITY.md, LICENSE, Node version pinning, etc.).
-- **shallow-risk** — reserved for obvious agent-config ↔ codebase boundary issues (CTO-06, not yet populated).
+- **shallow-risk** — obvious agent-config ↔ codebase boundary issues emitted through the experimental `--shallow-risk` lane.
 
-There is deliberately no "deep-review" or general-security-scanning layer — Nerviq is an agent-configuration audit tool, not a code-review tool. The full taxonomy and disambiguation rules live in `docs/integration-contracts.md §8`, and the `layer` field is surfaced in every output format (JSON, CSV, JUnit, Markdown, text).
+There is deliberately no "deep-review" or general-security-scanning layer — Nerviq is an agent-configuration audit tool, not a code-review tool. The experimental `nerviq audit --shallow-risk` pass now adds an opt-in, non-scoring boundary scan on top of the four-layer model. The full taxonomy and disambiguation rules live in `docs/integration-contracts.md §8`, and the `layer` field is surfaced in every output format (JSON, CSV, JUnit, Markdown, text).
 
 ## Quick Start
 
@@ -234,8 +234,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.26.0",
-    "timestamp": "2026-04-15T14:00:00.000Z"
+    "version": "1.27.0",
+    "timestamp": "2026-04-15T18:00:00.000Z"
   }
 }
 ```

package/bin/cli.js

@@ -579,6 +579,8 @@ const HELP = `
 
   DISCOVER
     nerviq audit                  Quick scan: score + top 3 gaps (Harmony-first when 2+ platforms detected)
+    nerviq audit --shallow-risk   Opt-in boundary scan for agent-config <-> codebase red flags (experimental)
+    nerviq audit --shallow-risk-only  Fast precommit shallow-risk pass without the full governance audit
     nerviq audit --fix            Audit, apply fixable critical fixes, then re-audit
     nerviq audit --fix --dry-run  Show proposed autofix diff without writing
     nerviq audit --no-harmony-first   Skip the cross-platform Harmony header
@@ -709,6 +711,8 @@ const HELP = `
     --tag LABEL       Tag the saved snapshot (use with --snapshot; repeat or comma-separate for more)
     --milestone NAME  Snapshot lifecycle milestone: baseline | post-fix | pre-upgrade | release
     --campaign A,B    Limit plan/apply to named upgrade campaigns
+    --shallow-risk    Enable experimental shallow-risk hints (parallel, not scored)
+    --shallow-risk-only Run only shallow-risk hints and skip the full governance audit
     --full            Show full audit output (all checks, weakest areas, badge)
     --lite            Short top-3 scan (default behavior since v1.5.2)
     --dry-run         Preview changes without writing files
@@ -740,6 +744,7 @@ const HELP = `
     npx nerviq --lite
     npx nerviq --platform cursor
     npx nerviq audit --workspace packages/*
+    npx nerviq audit --shallow-risk
     npx nerviq baseline init
     npx nerviq audit --diff-only --drift-mode ci
     npx nerviq --platform codex augment
@@ -819,11 +824,16 @@ async function main() {
     process.exit(0);
   }
 
+  const shallowRiskRequested = (flags.includes('--shallow-risk') || flags.includes('--shallow-risk-only')) &&
+    process.env.NERVIQ_SHALLOW_RISK !== 'off';
+  const shallowRiskOnlyRequested = flags.includes('--shallow-risk-only') &&
+    process.env.NERVIQ_SHALLOW_RISK !== 'off';
+
   const options = {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
-    lite: flags.includes('--full') || flags.includes('--verbose') ? false : true,
+    lite: flags.includes('--full') || flags.includes('--verbose') || shallowRiskRequested ? false : true,
     full: flags.includes('--full'),
     showDeprecated: flags.includes('--show-deprecated'),
     snapshot: flags.includes('--snapshot'),
@@ -860,6 +870,8 @@ async function main() {
     compareView: flags.includes('--compare'),
     diffOnly: flags.includes('--diff-only'),
     noHarmonyFirst: flags.includes('--no-harmony-first'),
+    shallowRisk: shallowRiskRequested,
+    shallowRiskOnly: shallowRiskOnlyRequested,
     diffBase: parsed.diffBase || null,
     diffHead: parsed.diffHead || null,
     driftMode: parsed.driftMode || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "The intelligent nervous system for AI coding agents — 2,441 checks (8 platforms × ~300 governance rules), 10 languages, 62 domain packs. Audit, align, and amplify.",
   "main": "src/index.js",
   "bin": {

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