@nerviq/cli 1.22.0 → 1.23.0

package/README.md

@@ -223,8 +223,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.22.0",
-    "timestamp": "2026-04-14T22:00:00.000Z"
+    "version": "1.23.0",
+    "timestamp": "2026-04-15T02:00:00.000Z"
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nerviq/cli",
-  "version": "1.22.0",
+  "version": "1.23.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/evidence.js

@@ -0,0 +1,270 @@
+/**
+ * Evidence resolver — CTO-04 trust-recovery depth.
+ *
+ * Given a failed check key and a ProjectContext, returns
+ * `{ file, line, snippet }` when the finding lives at a specific
+ * file location in the repo, or `null` when the check is genuinely
+ * not file-level (e.g. "absence of a file" or meta-property).
+ *
+ * This is a post-hoc resolver: many technique definitions do not
+ * declare `file`/`line` themselves, so we fill evidence in from here
+ * using the cached file content already loaded by ProjectContext.
+ * No extra filesystem scans are performed.
+ *
+ * Snippet is a 2-5 line excerpt centered on `line`, length-capped
+ * at 300 chars, using `\n` as line separator.
+ */
+
+'use strict';
+
+const SNIPPET_RADIUS = 2; // 2 lines before + match + 2 lines after = up to 5 lines
+const SNIPPET_MAX_CHARS = 300;
+
+function sliceSnippet(content, line) {
+  if (!content || !Number.isFinite(line) || line < 1) return null;
+  const lines = content.split(/\r?\n/);
+  const start = Math.max(0, line - 1 - SNIPPET_RADIUS);
+  const end = Math.min(lines.length, line + SNIPPET_RADIUS);
+  let snippet = lines.slice(start, end).join('\n');
+  if (snippet.length > SNIPPET_MAX_CHARS) {
+    snippet = snippet.slice(0, SNIPPET_MAX_CHARS - 3) + '...';
+  }
+  return snippet || null;
+}
+
+function buildEvidence(ctx, file, line) {
+  if (!file) return null;
+  const content = typeof ctx.fileContent === 'function' ? ctx.fileContent(file) : null;
+  if (!content) return { file, line: line || null, snippet: null };
+  const resolvedLine = Number.isFinite(line) && line >= 1 ? line : 1;
+  const snippet = sliceSnippet(content, resolvedLine);
+  return { file, line: resolvedLine, snippet };
+}
+
+// Locate the best-match CLAUDE.md file (root or .claude/).
+function claudeMdPath(ctx) {
+  if (typeof ctx.fileContent !== 'function') return null;
+  if (ctx.fileContent('CLAUDE.md') !== null) return 'CLAUDE.md';
+  if (ctx.fileContent('.claude/CLAUDE.md') !== null) return '.claude/CLAUDE.md';
+  return null;
+}
+
+function agentsMdPath(ctx) {
+  if (typeof ctx.fileContent !== 'function') return null;
+  if (ctx.fileContent('AGENTS.md') !== null) return 'AGENTS.md';
+  return null;
+}
+
+// Resolvers return { file, line } or null (category c).
+// `file` MUST be a real path that exists; otherwise return null so we do not
+// produce misleading evidence.
+const RESOLVERS = {
+  // --- CLAUDE.md content checks (backport: file=CLAUDE.md, line=1) ---
+  claudeMd: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null; // absent → null (category c)
+  },
+  importSyntax: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  roleDefinition: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  mermaidArchitecture: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  underlines200: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  xmlTags: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  fewShotExamples: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  outputStyleGuidance: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  constraintBlocks: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+
+  // CLAUDE.local.md — genuinely absent → null
+  claudeLocalMd: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    return ctx.fileContent('CLAUDE.local.md') !== null
+      ? { file: 'CLAUDE.local.md', line: 1 }
+      : null;
+  },
+
+  // --- .claude/settings.json shape checks ---
+  settingsPermissions: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    const line = typeof ctx.lineNumber === 'function'
+      ? (ctx.lineNumber('.claude/settings.json', /"permissions"/) || 1)
+      : 1;
+    return { file: '.claude/settings.json', line };
+  },
+  permissionDeny: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    const line = typeof ctx.lineNumber === 'function'
+      ? (ctx.lineNumber('.claude/settings.json', /"deny"/) || 1)
+      : 1;
+    return { file: '.claude/settings.json', line };
+  },
+  noBypassPermissions: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    const line = typeof ctx.lineNumber === 'function'
+      ? (ctx.lineNumber('.claude/settings.json', /bypassPermissions|permissionMode/) || 1)
+      : 1;
+    return { file: '.claude/settings.json', line };
+  },
+  secretsProtection: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    return { file: '.claude/settings.json', line: 1 };
+  },
+
+  // --- Hooks files ---
+  hooks: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    const line = typeof ctx.lineNumber === 'function'
+      ? (ctx.lineNumber('.claude/settings.json', /"hooks"/) || 1)
+      : 1;
+    return { file: '.claude/settings.json', line };
+  },
+  stopFailureHook: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    return { file: '.claude/settings.json', line: 1 };
+  },
+  hooksNotificationEvent: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    return { file: '.claude/settings.json', line: 1 };
+  },
+  subagentStopHook: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.claude/settings.json') === null) return null;
+    return { file: '.claude/settings.json', line: 1 };
+  },
+
+  // --- AGENTS.md (Codex surface) ---
+  codexAgentsMd: (ctx) => {
+    const p = agentsMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  codexAgentsMdSubstantive: (ctx) => {
+    const p = agentsMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  codexAgentsVerificationCommands: (ctx) => {
+    const p = agentsMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  codexAgentsArchitecture: (ctx) => {
+    const p = agentsMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+
+  // --- Auto-memory / governance ---
+  autoMemoryAwareness: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  loopSafetyBoundaries: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+
+  // --- CLAUDE.md content-awareness checks (backport ~10 more keys) ---
+  compactionAwareness: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  contextManagement: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  effortLevelConfigured: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  channelsAwareness: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  worktreeAwareness: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  instinctToSkillProgression: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  sandboxAwareness: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+  gitAttributionDecision: (ctx) => {
+    const p = claudeMdPath(ctx);
+    return p ? { file: p, line: 1 } : null;
+  },
+
+  // --- MCP ---
+  mcpHasEnvConfig: (ctx) => {
+    if (typeof ctx.fileContent !== 'function') return null;
+    if (ctx.fileContent('.mcp.json') !== null) return { file: '.mcp.json', line: 1 };
+    if (ctx.fileContent('.claude/settings.json') !== null) {
+      const line = typeof ctx.lineNumber === 'function'
+        ? (ctx.lineNumber('.claude/settings.json', /"mcpServers"|"mcp"/) || 1)
+        : 1;
+      return { file: '.claude/settings.json', line };
+    }
+    return null;
+  },
+};
+
+/**
+ * Resolve file/line/snippet evidence for a failed check.
+ *
+ * @param {string} key  Check key (e.g. 'importSyntax').
+ * @param {Object} ctx  ProjectContext instance.
+ * @param {Object} [existing]  Pre-existing { file, line } from the check itself.
+ * @returns {{file:string, line:number|null, snippet:string|null}|null}
+ */
+function resolveEvidence(key, ctx, existing = null) {
+  // If the check already emitted a real file, enrich with snippet only.
+  if (existing && existing.file) {
+    return buildEvidence(ctx, existing.file, existing.line);
+  }
+  const resolver = RESOLVERS[key];
+  if (!resolver) return null;
+  let guess = null;
+  try {
+    guess = resolver(ctx);
+  } catch {
+    return null;
+  }
+  if (!guess || !guess.file) return null;
+  return buildEvidence(ctx, guess.file, guess.line);
+}
+
+module.exports = {
+  resolveEvidence,
+  sliceSnippet,
+  SNIPPET_MAX_CHARS,
+  EVIDENCE_RESOLVER_KEYS: Object.keys(RESOLVERS),
+};

package/src/audit.js

@@ -35,6 +35,7 @@ const { collectAuditTerminology, formatTerminologyLines } = require('./terminolo
 const { loadPlugins, mergePluginChecks } = require('./plugins');
 const { detectDeprecationWarnings } = require('./deprecation');
 const { buildWorkspaceHint, formatCount, guardSkippedInstructionFiles, inspectInstructionFiles } = require('./audit/instruction-files');
+const { resolveEvidence } = require('./audit/evidence');
 const {
   WEIGHTS,
   buildScoreCoaching,
@@ -412,13 +413,24 @@ async function audit(options) {
     }
 
     const passed = technique.check(ctx);
-    const file = typeof technique.file === 'function' ? (technique.file(ctx) ?? null) : (technique.file ?? null);
-    const line = typeof technique.line === 'function' ? (technique.line(ctx) ?? null) : (technique.line ?? null);
+    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,
     });
   }
@@ -493,6 +505,35 @@ async function audit(options) {
   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 });
+
+  // CTO-04: enrich top actions with file/line/snippet from the corresponding
+  // result record (evidence was resolved above during the check loop).
+  // CTO-05: project score-after-fix per action.
+  const resultByKey = new Map(results.map((r) => [r.key, r]));
+  for (const action of topNextActions) {
+    const source = resultByKey.get(action.key);
+    if (source) {
+      if (source.file && !action.file) action.file = source.file;
+      if (source.line && !action.line) action.line = source.line;
+      if (source.snippet) action.snippet = source.snippet;
+    }
+    // Projected score delta: if this single failed check flipped to passed.
+    const weight = WEIGHTS[action.impact] || 0;
+    if (maxScore > 0 && weight > 0) {
+      const projectedScoreAfter = Math.round(((earnedScore + weight) / maxScore) * 100);
+      action.projectedScoreDelta = projectedScoreAfter - score;
+      action.projectedScoreAfter = projectedScoreAfter;
+      const isScaffolded = scaffoldedKeys.has(action.key);
+      const projectedOrganicAfter = isScaffolded
+        ? organicScore
+        : Math.round(((organicEarned + weight) / maxScore) * 100);
+      action.projectedOrganicScoreDelta = projectedOrganicAfter - organicScore;
+    } else {
+      action.projectedScoreDelta = 0;
+      action.projectedScoreAfter = score;
+      action.projectedOrganicScoreDelta = 0;
+    }
+  }
   const categoryScores = computeCategoryScores(applicable, passed);
   const platformScopeNote = getPlatformScopeNote(spec, ctx);
   const platformCaveats = getPlatformCaveats(spec, ctx);
@@ -815,7 +856,10 @@ async function audit(options) {
     console.log(colorize('  ⚡ Top 5 Next Actions', 'magenta'));
     for (let i = 0; i < topNextActions.length; i++) {
       const item = topNextActions[i];
-      console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}`);
+      const delta = Number.isFinite(item.projectedScoreDelta) && item.projectedScoreDelta > 0
+        ? colorize(` (+${item.projectedScoreDelta} pts → ${item.projectedScoreAfter}/100)`, 'green')
+        : '';
+      console.log(`     ${i + 1}. ${colorize(item.name, 'bold')}${delta}`);
       console.log(colorize(`        Why: ${item.why}`, 'dim'));
       console.log(colorize(`        Trace: ${item.signals.join(' | ')}`, 'dim'));
       console.log(colorize(`        Risk: ${item.risk} | Confidence: ${item.confidence}`, 'dim'));

package/src/formatters/csv.js

@@ -28,6 +28,8 @@ const COLUMNS = [
   'line',
   'sourceUrl',
   'fix',
+  'projectedScoreDelta',
+  'projectedScoreAfter',
 ];
 
 function csvEscape(value) {
@@ -39,8 +41,9 @@ function csvEscape(value) {
   return s;
 }
 
-function rowFor(r) {
+function rowFor(r, projections = null) {
   const severity = r.severity || r.impact || '';
+  const proj = projections && projections.get(r.key);
   const cells = [
     r.key ?? '',
     r.id ?? '',
@@ -53,15 +56,23 @@ function rowFor(r) {
     r.line ?? '',
     r.sourceUrl ?? '',
     r.fix ?? '',
+    proj && Number.isFinite(proj.projectedScoreDelta) ? String(proj.projectedScoreDelta) : '',
+    proj && Number.isFinite(proj.projectedScoreAfter) ? String(proj.projectedScoreAfter) : '',
   ];
   return cells.map(csvEscape).join(',');
 }
 
 function formatCsv(auditResult) {
   const results = Array.isArray(auditResult.results) ? auditResult.results : [];
+  const projections = new Map();
+  if (Array.isArray(auditResult.topNextActions)) {
+    for (const item of auditResult.topNextActions) {
+      if (item && item.key) projections.set(item.key, item);
+    }
+  }
   const lines = [COLUMNS.join(',')];
   for (const r of results) {
-    lines.push(rowFor(r));
+    lines.push(rowFor(r, projections));
   }
   return lines.join('\n');
 }

package/src/formatters/junit.js

@@ -76,6 +76,7 @@ function formatJUnit(auditResult) {
         let body = `${r.name || ''}`;
         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(`      <failure message="${msg}" type="${type}">${escapeXml(body)}</failure>`);
         lines.push(`    </testcase>`);

package/src/formatters/markdown.js

@@ -74,11 +74,23 @@ function formatMarkdown(auditResult, options = {}) {
       if (item.file) {
         loc = ` — \`${escapeInline(item.file)}${item.line ? ':' + item.line : ''}\``;
       }
-      lines.push(`- [ ] **[${sev}] ${title}** (\`${key}\`)${loc}`);
+      let delta = '';
+      if (Number.isFinite(item.projectedScoreDelta) && item.projectedScoreDelta > 0) {
+        delta = ` (+${item.projectedScoreDelta} pts → ${item.projectedScoreAfter}/100)`;
+      }
+      lines.push(`- [ ] **[${sev}] ${title}** (\`${key}\`)${loc}${delta}`);
       const hint = item.fix || item.hint || '';
       if (hint) {
         lines.push(`  - ${escapeInline(hint)}`);
       }
+      if (item.snippet) {
+        lines.push('');
+        lines.push('  ```');
+        for (const snipLine of String(item.snippet).split(/\r?\n/)) {
+          lines.push(`  ${snipLine}`);
+        }
+        lines.push('  ```');
+      }
     }
     lines.push('');
   }