@nerviq/cli 1.23.0 → 1.25.0

package/README.md

@@ -70,6 +70,17 @@ When your repo has 2+ platforms configured, `nerviq audit` leads with the Harmon
 
 Single-platform repos still work the same way — the Harmony Score only appears when 2+ platforms are detected. Use `--no-harmony-first` to suppress it even on multi-platform repos.
 
+### Scope — the 4 layers
+
+Every Nerviq check is tagged with one of four explicit layers so you know exactly what the tool claims (and does not claim) to cover:
+
+- **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).
+
+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).
+
 ## Quick Start
 
 ```bash
@@ -223,8 +234,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.23.0",
-    "timestamp": "2026-04-15T02:00:00.000Z"
+    "version": "1.25.0",
+    "timestamp": "2026-04-15T10:00:00.000Z"
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.23.0",
+  "version": "1.25.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/aider/techniques.js

@@ -3456,6 +3456,10 @@ Object.assign(AIDER_TECHNIQUES, buildStackChecks({
 
 attachSourceUrls('aider', AIDER_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: AIDER_LAYERS, assignLayers: aiderAssignLayers } = require('../audit/layers');
+aiderAssignLayers(AIDER_TECHNIQUES, AIDER_LAYERS.GOVERNANCE);
+
 module.exports = {
   AIDER_TECHNIQUES,
 };

package/src/audit/layers.js

@@ -0,0 +1,179 @@
+/**
+ * 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,
+};

package/src/audit/recommendations.js

@@ -346,7 +346,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
       return scoreB - scoreA;
     })
     .slice(0, limit)
-    .map(({ key, id, name, impact, fix, category, sourceUrl }) => {
+    .map(({ key, id, name, impact, fix, category, sourceUrl, layer }) => {
       const feedback = outcomeSummaryByKey[key] || null;
       const rankingAdjustment = getRecommendationAdjustment(outcomeSummaryByKey, key);
       const signals = [
@@ -376,6 +376,7 @@ function buildTopNextActions(failed, limit = 5, outcomeSummaryByKey = {}, option
         name,
         impact,
         category,
+        layer, // CTO-08: surface scope layer on every next-action
         sourceUrl,
         module: CATEGORY_MODULES[category] || category,
         fix,

package/src/audit.js

@@ -36,6 +36,7 @@ const { loadPlugins, mergePluginChecks } = require('./plugins');
 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 {
   WEIGHTS,
   buildScoreCoaching,
@@ -441,6 +442,7 @@ async function audit(options) {
       id: null,
       name: 'Large instruction file warning',
       category: 'performance',
+      layer: LAYERS.GOVERNANCE,
       impact: 'medium',
       rating: null,
       fix: 'Split oversized instruction files so they stay under ~12,000 tokens, and keep any single instruction file below ~240,000 tokens.',
@@ -640,6 +642,8 @@ async function audit(options) {
     platformScopeNote,
     platformCaveats,
     recommendedDomainPacks,
+    // CTO-08: per-layer coverage summary (governance/drift/hygiene/shallow-risk).
+    layerSummary: summarizeLayers(activeResults),
   };
   // Detect which AI config files are present
   const configFiles = [];
@@ -788,6 +792,18 @@ async function audit(options) {
   }
   console.log('');
 
+  // CTO-08: Coverage by layer — explicit map of what NERVIQ covers.
+  const layerSummary = result.layerSummary || summarizeLayers(activeResults);
+  console.log(colorize('  Coverage by layer:', 'bold'));
+  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'));
+  }
+  console.log('');
+
   // Passed
   if (passed.length > 0) {
     console.log(colorize('  ✅ Passing', 'green'));
@@ -813,7 +829,8 @@ async function audit(options) {
     console.log(colorize('  🔴 Critical (fix immediately)', 'red'));
     for (const r of critical) {
       const conf = r.confidence ? ` [${confidenceLabel(r.confidence)}]` : '';
-      console.log(`     ${colorize(r.name, 'bold')}${colorize(conf, 'dim')}`);
+      const layerPrefix = r.layer ? colorize(`[${r.layer}] `, 'dim') : '';
+      console.log(`     ${layerPrefix}${colorize(r.name, 'bold')}${colorize(conf, 'dim')}`);
       if (r.file) {
         console.log(colorize(`     at ${formatLocation(r.file, r.line)}`, 'dim'));
       }
@@ -826,7 +843,8 @@ async function audit(options) {
     console.log(colorize('  🟡 High Impact', 'yellow'));
     for (const r of high) {
       const conf = r.confidence ? ` [${confidenceLabel(r.confidence)}]` : '';
-      console.log(`     ${colorize(r.name, 'bold')}${colorize(conf, 'dim')}`);
+      const layerPrefix = r.layer ? colorize(`[${r.layer}] `, 'dim') : '';
+      console.log(`     ${layerPrefix}${colorize(r.name, 'bold')}${colorize(conf, 'dim')}`);
       if (r.file) {
         console.log(colorize(`     at ${formatLocation(r.file, r.line)}`, 'dim'));
       }
@@ -839,7 +857,8 @@ async function audit(options) {
     console.log(colorize('  🔵 Recommended', 'blue'));
     for (const r of medium) {
       const conf = r.confidence ? ` [${confidenceLabel(r.confidence)}]` : '';
-      console.log(`     ${colorize(r.name, 'bold')}${colorize(conf, 'dim')}`);
+      const layerPrefix = r.layer ? colorize(`[${r.layer}] `, 'dim') : '';
+      console.log(`     ${layerPrefix}${colorize(r.name, 'bold')}${colorize(conf, 'dim')}`);
       if (r.file) {
         console.log(colorize(`     at ${formatLocation(r.file, r.line)}`, 'dim'));
       }

package/src/codex/techniques.js

@@ -4886,6 +4886,10 @@ Object.assign(CODEX_TECHNIQUES, buildSupplementalChecks({
 
 attachSourceUrls('codex', CODEX_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: CODEX_LAYERS, assignLayers: codexAssignLayers } = require('../audit/layers');
+codexAssignLayers(CODEX_TECHNIQUES, CODEX_LAYERS.GOVERNANCE);
+
 module.exports = {
   CODEX_TECHNIQUES,
 };

package/src/copilot/techniques.js

@@ -3569,6 +3569,10 @@ Object.assign(COPILOT_TECHNIQUES, buildStackChecks({
 
 attachSourceUrls('copilot', COPILOT_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: COPILOT_LAYERS, assignLayers: copilotAssignLayers } = require('../audit/layers');
+copilotAssignLayers(COPILOT_TECHNIQUES, COPILOT_LAYERS.GOVERNANCE);
+
 module.exports = {
   COPILOT_TECHNIQUES,
 };

package/src/cursor/techniques.js

@@ -3726,6 +3726,10 @@ Object.assign(CURSOR_TECHNIQUES, buildStackChecks({
 
 attachSourceUrls('cursor', CURSOR_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: CURSOR_LAYERS, assignLayers: cursorAssignLayers } = require('../audit/layers');
+cursorAssignLayers(CURSOR_TECHNIQUES, CURSOR_LAYERS.GOVERNANCE);
+
 module.exports = {
   CURSOR_TECHNIQUES,
 };

package/src/formatters/csv.js

@@ -2,7 +2,10 @@
  * CSV Formatter (RFC 4180)
  *
  * One row per check in a nerviq audit result.
- * Columns: key,id,name,category,rating,severity,passed,file,line,sourceUrl,fix
+ * Columns: key,id,name,category,layer,rating,severity,passed,file,line,sourceUrl,fix
+ *
+ * The `layer` column (added in CTO-08) is one of 'governance',
+ * 'drift', 'hygiene', or 'shallow-risk' — see docs/integration-contracts.md §8.
  *
  * Quoting rules (RFC 4180):
  *   - Fields containing comma, double-quote, CR, or LF are wrapped in
@@ -21,6 +24,7 @@ const COLUMNS = [
   'id',
   'name',
   'category',
+  'layer',
   'rating',
   'severity',
   'passed',
@@ -49,6 +53,7 @@ function rowFor(r, projections = null) {
     r.id ?? '',
     r.name ?? '',
     r.category ?? '',
+    r.layer ?? '',
     r.rating ?? '',
     severity,
     r.passed === null || r.passed === undefined ? '' : String(r.passed),

package/src/formatters/junit.js

@@ -70,6 +70,9 @@ function formatJUnit(auditResult) {
     for (const r of checks) {
       const classname = escapeXml(r.category || 'uncategorized');
       const name = escapeXml(r.key || r.id || r.name || 'unknown');
+      // CTO-08: surface scope layer as a testcase attribute so JUnit
+      // consumers (GitHub Actions, Jenkins, GitLab) can filter/group.
+      const layerAttr = r.layer ? ` layer="${escapeXml(r.layer)}"` : '';
       if (r.passed === false) {
         const msg = escapeXml(r.fix || r.name || r.key || 'check failed');
         const type = escapeXml(severityFor(r));
@@ -77,15 +80,15 @@ function formatJUnit(auditResult) {
         if (r.file) body += ` at ${r.file}${r.line ? ':' + r.line : ''}`;
         if (r.sourceUrl) body += ` (${r.sourceUrl})`;
         if (r.snippet) body += `\n---\n${r.snippet}`;
-        lines.push(`    <testcase classname="${classname}" name="${name}" time="0">`);
+        lines.push(`    <testcase classname="${classname}" name="${name}"${layerAttr} time="0">`);
         lines.push(`      <failure message="${msg}" type="${type}">${escapeXml(body)}</failure>`);
         lines.push(`    </testcase>`);
       } else if (r.passed === null || r.skipped === true) {
-        lines.push(`    <testcase classname="${classname}" name="${name}" time="0">`);
+        lines.push(`    <testcase classname="${classname}" name="${name}"${layerAttr} time="0">`);
         lines.push(`      <skipped/>`);
         lines.push(`    </testcase>`);
       } else {
-        lines.push(`    <testcase classname="${classname}" name="${name}" time="0"/>`);
+        lines.push(`    <testcase classname="${classname}" name="${name}"${layerAttr} time="0"/>`);
       }
     }
 

package/src/formatters/markdown.js

@@ -78,7 +78,10 @@ function formatMarkdown(auditResult, options = {}) {
       if (Number.isFinite(item.projectedScoreDelta) && item.projectedScoreDelta > 0) {
         delta = ` (+${item.projectedScoreDelta} pts → ${item.projectedScoreAfter}/100)`;
       }
-      lines.push(`- [ ] **[${sev}] ${title}** (\`${key}\`)${loc}${delta}`);
+      // CTO-08: include scope layer as a small suffix after the key so
+      // evaluators see which layer each next-action belongs to.
+      const layerSuffix = item.layer ? ` · _layer: ${escapeInline(item.layer)}_` : '';
+      lines.push(`- [ ] **[${sev}] ${title}** (\`${key}\`)${loc}${delta}${layerSuffix}`);
       const hint = item.fix || item.hint || '';
       if (hint) {
         lines.push(`  - ${escapeInline(hint)}`);
@@ -103,13 +106,15 @@ function formatMarkdown(auditResult, options = {}) {
     lines.push('<details>');
     lines.push(`<summary>All failed checks (${failedResults.length})</summary>`);
     lines.push('');
-    lines.push('| key | name | category | rating | file | line |');
-    lines.push('| --- | --- | --- | --- | --- | --- |');
+    // CTO-08: add layer column between category and rating.
+    lines.push('| key | name | category | layer | rating | file | line |');
+    lines.push('| --- | --- | --- | --- | --- | --- | --- |');
     for (const r of failedResults) {
       const row = [
         escapeCell(r.key),
         escapeCell(r.name),
         escapeCell(r.category),
+        escapeCell(r.layer || ''),
         escapeCell(r.rating ?? ''),
         escapeCell(r.file || ''),
         escapeCell(r.line || ''),

package/src/gemini/techniques.js

@@ -3802,6 +3802,10 @@ Object.assign(GEMINI_TECHNIQUES, buildStackChecks({
 
 attachSourceUrls('gemini', GEMINI_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: GEMINI_LAYERS, assignLayers: geminiAssignLayers } = require('../audit/layers');
+geminiAssignLayers(GEMINI_TECHNIQUES, GEMINI_LAYERS.GOVERNANCE);
+
 module.exports = {
   GEMINI_TECHNIQUES,
 };

package/src/opencode/techniques.js

@@ -21,13 +21,13 @@
  */
 
 const os = require('os');
-const path = require('path');
-const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
-const { attachSourceUrls } = require('../source-urls');
-const { buildStackChecks } = require('../stack-checks');
-const { isApiProject, isDatabaseProject, isAuthProject, isMonitoringRelevant } = require('../supplemental-checks');
-const { hasCostBudgetOrUsageTracking } = require('../cost-tracking');
-const { resolveProjectStateReadPath } = require('../state-paths');
+const path = require('path');
+const { EMBEDDED_SECRET_PATTERNS, containsEmbeddedSecret } = require('../secret-patterns');
+const { attachSourceUrls } = require('../source-urls');
+const { buildStackChecks } = require('../stack-checks');
+const { isApiProject, isDatabaseProject, isAuthProject, isMonitoringRelevant } = require('../supplemental-checks');
+const { hasCostBudgetOrUsageTracking } = require('../cost-tracking');
+const { resolveProjectStateReadPath } = require('../state-paths');
 
 const DEFAULT_PROJECT_DOC_MAX_BYTES = 32768;
 
@@ -1460,15 +1460,15 @@ const OPENCODE_TECHNIQUES = {
     line: () => null,
   },
 
-  opencodePilotEvidence: {
-    id: 'OC-M03',
-    name: 'OpenCode setup has been audited at least once',
-    check: (ctx) => {
-      // Check for nerviq activity artifacts
-      const fs = require('fs');
-      const hasArtifacts = fs.existsSync(resolveProjectStateReadPath(ctx.dir));
-      return hasArtifacts ? true : null;
-    },
+  opencodePilotEvidence: {
+    id: 'OC-M03',
+    name: 'OpenCode setup has been audited at least once',
+    check: (ctx) => {
+      // Check for nerviq activity artifacts
+      const fs = require('fs');
+      const hasArtifacts = fs.existsSync(resolveProjectStateReadPath(ctx.dir));
+      return hasArtifacts ? true : null;
+    },
     impact: 'low',
     rating: 2,
     category: 'governance',
@@ -2017,17 +2017,17 @@ const OPENCODE_TECHNIQUES = {
     fix: 'Document prompt caching in opencode.json or AGENTS.md.',
     template: null, file: () => 'opencode.json', line: () => null,
   },
-  ocCostBudgetDefined: {
-    id: 'OC-T48', name: 'AI cost budget or per-run usage tracking documented',
-    check: (ctx) => {
-      const docs = docsBundle(ctx) + (ctx.fileContent('README.md') || '');
-      if (!docs.trim() && !hasCostBudgetOrUsageTracking('', ctx)) return null;
-      return hasCostBudgetOrUsageTracking(docs, ctx);
-    },
-    impact: 'low', rating: 2, category: 'cost-optimization',
-    fix: 'Document AI cost guardrails or per-run usage tracking so OpenCode usage is measurable over time.',
-    template: null, file: () => 'README.md', line: () => null,
-  },
+  ocCostBudgetDefined: {
+    id: 'OC-T48', name: 'AI cost budget or per-run usage tracking documented',
+    check: (ctx) => {
+      const docs = docsBundle(ctx) + (ctx.fileContent('README.md') || '');
+      if (!docs.trim() && !hasCostBudgetOrUsageTracking('', ctx)) return null;
+      return hasCostBudgetOrUsageTracking(docs, ctx);
+    },
+    impact: 'low', rating: 2, category: 'cost-optimization',
+    fix: 'Document AI cost guardrails or per-run usage tracking so OpenCode usage is measurable over time.',
+    template: null, file: () => 'README.md', line: () => null,
+  },
 
   // ============================================================
   // === PYTHON STACK CHECKS (category: 'python') ===============
@@ -3503,6 +3503,10 @@ Object.assign(OPENCODE_TECHNIQUES, buildStackChecks({
 
 attachSourceUrls('opencode', OPENCODE_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: OC_LAYERS, assignLayers: ocAssignLayers } = require('../audit/layers');
+ocAssignLayers(OPENCODE_TECHNIQUES, OC_LAYERS.GOVERNANCE);
+
 module.exports = {
   OPENCODE_TECHNIQUES,
 };

package/src/plugins.js

@@ -90,6 +90,7 @@ function loadPlugins(dir) {
  * Returns a new merged techniques object (does not mutate the original).
  */
 function mergePluginChecks(techniques, plugins) {
+  const { LAYERS, assignLayers } = require('./audit/layers');
   const merged = { ...techniques };
 
   for (const plugin of plugins) {
@@ -104,6 +105,10 @@ function mergePluginChecks(techniques, plugins) {
     }
   }
 
+  // CTO-08 — plugins may not set a layer. Default their checks to
+  // governance (drift/hygiene heuristics still apply via name).
+  assignLayers(merged, LAYERS.GOVERNANCE);
+
   return merged;
 }
 

package/src/techniques/automation.js

@@ -8,6 +8,27 @@ const {
   readProjectFiles,
 } = require('./shared');
 
+// PP-06 recalibration helpers: opt-in signals. Repos with no infra/hooks
+// signal at all get N/A instead of a hard fail on opt-in advisories.
+function _repoHasInfraSignal(ctx) {
+  return ctx.files.some(f => /^Dockerfile/i.test(f))
+    || ctx.files.some(f => /^docker-compose\.(yml|yaml)$/i.test(f))
+    || ctx.files.some(f => /\.tf$/.test(f))
+    || ctx.files.includes('main.tf')
+    || ctx.hasDir('k8s')
+    || ctx.hasDir('kubernetes')
+    || ctx.hasDir('infra')
+    || ctx.hasDir('terraform')
+    || ctx.hasDir('deploy');
+}
+
+function _repoHasHooksBlock(ctx) {
+  const shared = ctx.jsonFile('.claude/settings.json') || {};
+  const local = ctx.jsonFile('.claude/settings.local.json') || {};
+  return !!((shared.hooks && Object.keys(shared.hooks).length > 0)
+    || (local.hooks && Object.keys(local.hooks).length > 0));
+}
+
 module.exports = {
   hooks: {
       id: 19,
@@ -91,7 +112,11 @@ module.exports = {
   dockerfile: {
       id: 399,
       name: 'Has Dockerfile',
-      check: (ctx) => ctx.files.some(f => /^Dockerfile/i.test(f)),
+      check: (ctx) => {
+        if (ctx.files.some(f => /^Dockerfile/i.test(f))) return true;
+        // PP-06 recalibration: N/A on repos with no infra signal at all.
+        return _repoHasInfraSignal(ctx) ? false : null;
+      },
       impact: 'medium',
       rating: 3,
       category: 'devops',
@@ -102,7 +127,11 @@ module.exports = {
   dockerCompose: {
       id: 39901,
       name: 'Has docker-compose.yml',
-      check: (ctx) => ctx.files.some(f => /^docker-compose\.(yml|yaml)$/i.test(f)),
+      check: (ctx) => {
+        if (ctx.files.some(f => /^docker-compose\.(yml|yaml)$/i.test(f))) return true;
+        // PP-06 recalibration: N/A on repos with no infra signal at all.
+        return _repoHasInfraSignal(ctx) ? false : null;
+      },
       impact: 'medium',
       rating: 3,
       category: 'devops',
@@ -126,7 +155,11 @@ module.exports = {
   terraformFiles: {
       id: 397,
       name: 'Infrastructure as Code (Terraform)',
-      check: (ctx) => ctx.files.some(f => /\.tf$/.test(f)) || ctx.files.includes('main.tf'),
+      check: (ctx) => {
+        if (ctx.files.some(f => /\.tf$/.test(f)) || ctx.files.includes('main.tf')) return true;
+        // PP-06 recalibration: N/A on repos with no infra signal at all.
+        return _repoHasInfraSignal(ctx) ? false : null;
+      },
       impact: 'medium',
       rating: 3,
       category: 'devops',
@@ -290,7 +323,9 @@ module.exports = {
       check: (ctx) => {
         const shared = ctx.jsonFile('.claude/settings.json') || {};
         const local = ctx.jsonFile('.claude/settings.local.json') || {};
-        return !!(shared.hooks?.Notification || local.hooks?.Notification);
+        if (shared.hooks?.Notification || local.hooks?.Notification) return true;
+        // PP-06 recalibration: N/A unless settings define a hooks block at all.
+        return _repoHasHooksBlock(ctx) ? false : null;
       },
       impact: 'low',
       rating: 2,
@@ -305,7 +340,9 @@ module.exports = {
       check: (ctx) => {
         const shared = ctx.jsonFile('.claude/settings.json') || {};
         const local = ctx.jsonFile('.claude/settings.local.json') || {};
-        return !!(shared.hooks?.SubagentStop || local.hooks?.SubagentStop);
+        if (shared.hooks?.SubagentStop || local.hooks?.SubagentStop) return true;
+        // PP-06 recalibration: N/A unless settings define a hooks block at all.
+        return _repoHasHooksBlock(ctx) ? false : null;
       },
       impact: 'low',
       rating: 2,

package/src/techniques/instructions.js

@@ -50,8 +50,17 @@ module.exports = {
       name: 'CLAUDE.md uses @path imports for modularity',
       check: (ctx) => {
         const md = ctx.claudeMdContent() || '';
-        // Current syntax is @path/to/file (no "import" keyword)
-        return /@\S+\.(md|txt|json|yml|yaml|toml)/i.test(md) || /@\w+\//.test(md);
+        // Positive-signal check (PP-06 recalibration): N/A when no CLAUDE.md
+        // surface exists, so we don't fail every repo that happens to have a
+        // short CLAUDE.md. Only fire as an advisory on long CLAUDE.md files
+        // where modular @-imports would genuinely help.
+        if (!md) return null;
+        const hasImport = /@\S+\.(md|txt|json|yml|yaml|toml)/i.test(md) || /@\w+\//.test(md);
+        if (hasImport) return true;
+        // Only advise splitting when the CLAUDE.md is long enough to warrant it.
+        const lineCount = md.split('\n').length;
+        if (lineCount < 80) return null;
+        return false;
       },
       impact: 'medium',
       rating: 4,
@@ -140,8 +149,17 @@ module.exports = {
       id: 2002,
       name: 'CLAUDE.local.md for personal overrides',
       check: (ctx) => {
-        // CLAUDE.local.md is for personal, non-committed overrides
-        return ctx.files.includes('CLAUDE.local.md') || ctx.files.includes('.claude/CLAUDE.local.md');
+        // CLAUDE.local.md is for personal, non-committed overrides.
+        const hasLocal = ctx.files.includes('CLAUDE.local.md') || ctx.files.includes('.claude/CLAUDE.local.md');
+        if (hasLocal) return true;
+        // PP-06 recalibration: N/A when the repo has no personal-overrides
+        // convention at all. Only advise creating CLAUDE.local.md when the
+        // repo explicitly opts in to that convention (references it in
+        // .gitignore or in CLAUDE.md).
+        const gitignore = ctx.fileContent('.gitignore') || '';
+        const md = ctx.claudeMdContent() || '';
+        const mentioned = /CLAUDE\.local\.md/i.test(gitignore) || /CLAUDE\.local\.md/i.test(md);
+        return mentioned ? false : null;
       },
       impact: 'low',
       rating: 2,
@@ -155,7 +173,12 @@ module.exports = {
       name: 'Auto-memory or memory management mentioned',
       check: (ctx) => {
         const md = ctx.claudeMdContent() || '';
-        return /auto.?memory|memory.*manage|remember|persistent.*context/i.test(md);
+        if (/auto.?memory|memory.*manage|remember|persistent.*context/i.test(md)) return true;
+        // PP-06 recalibration: N/A on repos that don't use Claude Code memory
+        // at all. Only fire the advisory when the repo opts in (mentions memory
+        // or has a memory directory under .claude/).
+        const opts_in = /\bmemory\b/i.test(md) || ctx.hasDir('.claude/memory');
+        return opts_in ? false : null;
       },
       impact: 'low', rating: 3, category: 'memory',
       fix: 'Claude Code supports auto-memory for cross-session learning. Mention your memory strategy if relevant.',

package/src/techniques/tools.js

@@ -6,6 +6,20 @@
 const {
 } = require('./shared');
 
+// PP-06 recalibration: opt-in signal for MCP. A repo "opts in" to MCP checks if
+// it has any MCP file (even empty/partial) or mentions MCP in its Claude
+// instructions. Repos with no MCP signal at all get N/A on MCP advisories
+// instead of a hard fail.
+function _repoOptsInToMcp(ctx) {
+  if (ctx.files.includes('.mcp.json')) return true;
+  const shared = ctx.jsonFile('.claude/settings.json') || {};
+  const local = ctx.jsonFile('.claude/settings.local.json') || {};
+  if (shared.mcpServers || local.mcpServers) return true;
+  const md = ctx.claudeMdContent() || '';
+  if (/\bMCP\b|mcpServers|model[\s-]?context[\s-]?protocol/i.test(md)) return true;
+  return false;
+}
+
 module.exports = {
   mcpServers: {
       id: 18,
@@ -16,7 +30,9 @@ module.exports = {
         if (mcpJson && mcpJson.mcpServers && Object.keys(mcpJson.mcpServers).length > 0) return true;
         // Fallback: check settings for legacy format
         const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-        return !!(settings && settings.mcpServers && Object.keys(settings.mcpServers).length > 0);
+        if (settings && settings.mcpServers && Object.keys(settings.mcpServers).length > 0) return true;
+        // PP-06 recalibration: N/A on repos that don't reference MCP at all.
+        return _repoOptsInToMcp(ctx) ? false : null;
       },
       impact: 'medium',
       rating: 3,
@@ -34,7 +50,9 @@ module.exports = {
         if (mcpJson && mcpJson.mcpServers) count += Object.keys(mcpJson.mcpServers).length;
         const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
         if (settings && settings.mcpServers) count += Object.keys(settings.mcpServers).length;
-        return count >= 2;
+        if (count >= 2) return true;
+        // PP-06 recalibration: N/A on repos that don't reference MCP at all.
+        return _repoOptsInToMcp(ctx) ? false : null;
       },
       impact: 'medium',
       rating: 4,
@@ -51,7 +69,10 @@ module.exports = {
         const local = ctx.jsonFile('.claude/settings.local.json') || {};
         const mcp = ctx.jsonFile('.mcp.json') || {};
         const all = { ...(shared.mcpServers || {}), ...(local.mcpServers || {}), ...(mcp.mcpServers || {}) };
-        if (Object.keys(all).length === 0) return false;
+        if (Object.keys(all).length === 0) {
+          // PP-06 recalibration: N/A on repos that don't reference MCP at all.
+          return _repoOptsInToMcp(ctx) ? false : null;
+        }
         return Object.keys(all).some(k => /context7/i.test(k));
       },
       impact: 'medium',

package/src/techniques.js

@@ -5,6 +5,7 @@
  */
 
 const { attachSourceUrls, buildSupplementalChecks, CLAUDE_SUPPLEMENTAL_SOURCE_URLS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret } = require('./techniques/shared');
+const { LAYERS, assignLayers } = require('./audit/layers');
 const instructionTechniques = require('./techniques/instructions');
 const qualityTechniques = require('./techniques/quality');
 const apiTechniques = require('./techniques/api');
@@ -18,6 +19,24 @@ const complianceTechniques = require('./techniques/compliance');
 const optimizationTechniques = require('./techniques/optimization');
 const stackTechniques = require('./techniques/stacks');
 
+// CTO-08 — tag every check with a layer. Source-file-level defaults map
+// directly onto the taxonomy: hygiene.js → hygiene; everything else →
+// governance. The assignLayers helper then upgrades drift-like checks
+// (Harmony, propagation, cross-platform consistency) to the drift layer
+// regardless of their source bag.
+assignLayers(instructionTechniques, LAYERS.GOVERNANCE);
+assignLayers(qualityTechniques, LAYERS.GOVERNANCE);
+assignLayers(apiTechniques, LAYERS.GOVERNANCE);
+assignLayers(automationTechniques, LAYERS.GOVERNANCE);
+assignLayers(hygieneTechniques, LAYERS.HYGIENE);
+assignLayers(observabilityTechniques, LAYERS.GOVERNANCE);
+assignLayers(workflowTechniques, LAYERS.GOVERNANCE);
+assignLayers(toolTechniques, LAYERS.GOVERNANCE);
+assignLayers(securityTechniques, LAYERS.GOVERNANCE);
+assignLayers(complianceTechniques, LAYERS.GOVERNANCE);
+assignLayers(optimizationTechniques, LAYERS.GOVERNANCE);
+assignLayers(stackTechniques, LAYERS.GOVERNANCE);
+
 const TECHNIQUES = Object.assign({},
   instructionTechniques,
   qualityTechniques,
@@ -78,4 +97,8 @@ const STACKS = {
 
 attachSourceUrls('claude', TECHNIQUES);
 
+// CTO-08 — final sweep so supplemental checks added via buildSupplementalChecks
+// also carry a layer tag (defaults to governance; drift heuristic still runs).
+assignLayers(TECHNIQUES, LAYERS.GOVERNANCE);
+
 module.exports = { TECHNIQUES, STACKS, STACK_CATEGORY_DETECTORS, containsEmbeddedSecret };

package/src/windsurf/techniques.js

@@ -3770,6 +3770,10 @@ Object.assign(WINDSURF_TECHNIQUES, buildStackChecks({
 
 attachSourceUrls('windsurf', WINDSURF_TECHNIQUES);
 
+// CTO-08 — tag every check with a scope layer.
+const { LAYERS: WS_LAYERS, assignLayers: wsAssignLayers } = require('../audit/layers');
+wsAssignLayers(WINDSURF_TECHNIQUES, WS_LAYERS.GOVERNANCE);
+
 module.exports = {
   WINDSURF_TECHNIQUES,
 };