@nerviq/cli 1.21.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.21.0",
-    "timestamp": "2026-04-14T18:00:00.000Z"
+    "version": "1.23.0",
+    "timestamp": "2026-04-15T02:00:00.000Z"
   }
 }
 ```
@@ -385,10 +385,28 @@ Levels:
 | `--auto` | Apply without prompts |
 | `--only A,B` | Limit apply to selected proposal IDs |
 | `--format sarif` | SARIF output for code scanning |
+| `--format markdown` | GitHub-flavoured PR-comment report |
+| `--format junit` | JUnit XML for CI test reporters (GitHub Actions, Jenkins, GitLab) |
+| `--format csv` | RFC 4180 CSV, one row per check |
 | `--platform NAME` | Target platform (claude, codex, gemini, copilot, cursor, windsurf, aider, opencode) |
 | `--workspace GLOB` | Audit workspaces separately as package-level live audits with summary-only JSON rows (e.g. packages/*) |
 | `--external PATH` | Benchmark an external repo |
 
+### CI output formats
+
+Pipe audit output straight into the standard CI surfaces:
+
+```bash
+# PR comment (GitHub-flavoured markdown)
+npx @nerviq/cli audit --format=markdown --out audit.md
+
+# CI test report (JUnit XML — Jenkins, GitLab, GitHub Actions reporter)
+npx @nerviq/cli audit --format=junit --out junit.xml
+
+# Spreadsheet / dashboard ingestion (RFC 4180 CSV)
+npx @nerviq/cli audit --format=csv --out audit.csv
+```
+
 Webhook delivery automatically retries transient failures twice by default. For authenticated internal endpoints, you can add custom headers such as:
 
 ```bash

package/bin/cli.js

@@ -694,7 +694,7 @@ const HELP = `
     --team-profile N  Load a saved team profile for audit (overrides threshold/platform)
     --mcp-pack A,B    Merge MCP packs into setup (live tool connectors; e.g. context7-docs,next-devtools)
     --check-version V Pin catalog to a specific version (warn on mismatch)
-    --format NAME     Output format: json | sarif | otel
+    --format NAME     Output format: json | sarif | otel | markdown | junit | csv
     --webhook URL     Send audit results to a webhook (Slack/Discord/generic JSON)
     --webhook-header H Add a custom webhook header (repeat; format: Name: Value)
     --webhook-retries N Retry transient webhook failures N times (default: 2)
@@ -956,8 +956,8 @@ async function main() {
     process.exit(1);
   }
 
-  if (options.format !== null && !['json', 'sarif', 'otel'].includes(options.format)) {
-    console.error(`\n  Error: Unsupported format '${options.format}'. Use 'json', 'sarif', or 'otel'.\n`);
+  if (options.format !== null && !['json', 'sarif', 'otel', 'markdown', 'junit', 'csv'].includes(options.format)) {
+    console.error(`\n  Error: Unsupported format '${options.format}'. Use 'json', 'sarif', 'otel', 'markdown', 'junit', or 'csv'.\n`);
     process.exit(1);
   }
 

package/package.json

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

@@ -28,10 +28,14 @@ const { getRecommendationOutcomeSummary } = require('./activity');
 const { getFeedbackSummary } = require('./feedback');
 const { formatSarif } = require('./formatters/sarif');
 const { formatOtelMetrics } = require('./formatters/otel');
+const { formatMarkdown } = require('./formatters/markdown');
+const { formatJUnit } = require('./formatters/junit');
+const { formatCsv } = require('./formatters/csv');
 const { collectAuditTerminology, formatTerminologyLines } = require('./terminology');
 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,
@@ -409,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,
     });
   }
@@ -490,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);
@@ -645,6 +689,23 @@ async function audit(options) {
     return result;
   }
 
+  if (options.format === 'markdown') {
+    const enriched = { version: packageVersion, timestamp: new Date().toISOString(), ...result };
+    console.log(formatMarkdown(enriched, { dir: options.dir }));
+    return result;
+  }
+
+  if (options.format === 'junit') {
+    const enriched = { version: packageVersion, timestamp: new Date().toISOString(), ...result };
+    console.log(formatJUnit(enriched));
+    return result;
+  }
+
+  if (options.format === 'csv') {
+    console.log(formatCsv(result));
+    return result;
+  }
+
   if (options.lite) {
     printLiteAudit(result, options.dir);
     sendInsights(result);
@@ -795,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

@@ -0,0 +1,80 @@
+/**
+ * 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
+ *
+ * Quoting rules (RFC 4180):
+ *   - Fields containing comma, double-quote, CR, or LF are wrapped in
+ *     double-quotes.
+ *   - Internal double-quotes are escaped by doubling them.
+ *   - Header row is emitted first.
+ *   - No UTF-8 BOM (some consumers mishandle it).
+ *   - Line separator: LF (consumers accept LF; JUnit/XLSX/csv parsers
+ *     normalize both).
+ */
+
+'use strict';
+
+const COLUMNS = [
+  'key',
+  'id',
+  'name',
+  'category',
+  'rating',
+  'severity',
+  'passed',
+  'file',
+  'line',
+  'sourceUrl',
+  'fix',
+  'projectedScoreDelta',
+  'projectedScoreAfter',
+];
+
+function csvEscape(value) {
+  if (value === null || value === undefined) return '';
+  const s = String(value);
+  if (/[",\r\n]/.test(s)) {
+    return `"${s.replace(/"/g, '""')}"`;
+  }
+  return s;
+}
+
+function rowFor(r, projections = null) {
+  const severity = r.severity || r.impact || '';
+  const proj = projections && projections.get(r.key);
+  const cells = [
+    r.key ?? '',
+    r.id ?? '',
+    r.name ?? '',
+    r.category ?? '',
+    r.rating ?? '',
+    severity,
+    r.passed === null || r.passed === undefined ? '' : String(r.passed),
+    r.file ?? '',
+    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, projections));
+  }
+  return lines.join('\n');
+}
+
+module.exports = { formatCsv, CSV_COLUMNS: COLUMNS };

package/src/formatters/junit.js

@@ -0,0 +1,100 @@
+/**
+ * JUnit XML Formatter
+ *
+ * Converts a nerviq audit result into Jenkins-compatible JUnit XML.
+ * Schema: <testsuites><testsuite><testcase><failure/></testcase></testsuite></testsuites>
+ *
+ *   - One <testsuite> per check category.
+ *   - Each check becomes a <testcase> (classname = category, name = key).
+ *   - Failed checks emit a <failure message="..." type="..."/> where:
+ *       - message = check.fix || check.name
+ *       - type    = severity (check.severity || check.impact)
+ *   - Skipped checks emit <skipped/>.
+ *
+ * Parses with any standard JUnit XML consumer (GitHub Actions test
+ * reporter, Jenkins, GitLab CI, CircleCI).
+ */
+
+'use strict';
+
+const { version: nerviqVersion } = require('../../package.json');
+
+function escapeXml(value) {
+  if (value === null || value === undefined) return '';
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function severityFor(r) {
+  return r.severity || r.impact || 'medium';
+}
+
+function groupByCategory(results) {
+  const map = new Map();
+  for (const r of results) {
+    const cat = r.category || 'uncategorized';
+    if (!map.has(cat)) map.set(cat, []);
+    map.get(cat).push(r);
+  }
+  return map;
+}
+
+function formatJUnit(auditResult) {
+  const allResults = Array.isArray(auditResult.results) ? auditResult.results : [];
+  const timestamp = auditResult.timestamp || new Date().toISOString();
+  const platform = auditResult.platform || 'claude';
+
+  const totalTests = allResults.length;
+  const totalFailures = allResults.filter((r) => r.passed === false).length;
+  const totalSkipped = allResults.filter((r) => r.passed === null || r.skipped === true).length;
+
+  const byCategory = groupByCategory(allResults);
+
+  const lines = [];
+  lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+  lines.push(
+    `<testsuites name="nerviq" tests="${totalTests}" failures="${totalFailures}" skipped="${totalSkipped}" time="0">`,
+  );
+
+  for (const [category, checks] of byCategory) {
+    const suiteFailures = checks.filter((r) => r.passed === false).length;
+    const suiteSkipped = checks.filter((r) => r.passed === null || r.skipped === true).length;
+    lines.push(
+      `  <testsuite name="${escapeXml(category)}" tests="${checks.length}" failures="${suiteFailures}" skipped="${suiteSkipped}" time="0" timestamp="${escapeXml(timestamp)}" package="nerviq.${escapeXml(platform)}">`,
+    );
+
+    for (const r of checks) {
+      const classname = escapeXml(r.category || 'uncategorized');
+      const name = escapeXml(r.key || r.id || r.name || 'unknown');
+      if (r.passed === false) {
+        const msg = escapeXml(r.fix || r.name || r.key || 'check failed');
+        const type = escapeXml(severityFor(r));
+        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>`);
+      } else if (r.passed === null || r.skipped === true) {
+        lines.push(`    <testcase classname="${classname}" name="${name}" time="0">`);
+        lines.push(`      <skipped/>`);
+        lines.push(`    </testcase>`);
+      } else {
+        lines.push(`    <testcase classname="${classname}" name="${name}" time="0"/>`);
+      }
+    }
+
+    lines.push('  </testsuite>');
+  }
+
+  lines.push('</testsuites>');
+  lines.push(`<!-- nerviq v${escapeXml(auditResult.version || nerviqVersion)} -->`);
+  return lines.join('\n');
+}
+
+module.exports = { formatJUnit };

package/src/formatters/markdown.js

@@ -0,0 +1,130 @@
+/**
+ * Markdown Formatter
+ *
+ * Converts a nerviq audit result into GitHub-flavoured markdown suitable
+ * for posting as a PR comment. Structure:
+ *
+ *   - Header with score badge and pass/fail/skip counts
+ *   - Top 5 topNextActions as a GitHub task-list checklist
+ *   - Collapsible <details> block with the full failed-checks table
+ *   - Footer with Nerviq link, version, timestamp
+ *
+ * Output is plain GitHub-flavoured markdown. The only HTML used is
+ * <details>/<summary>, which GitHub renders natively.
+ */
+
+'use strict';
+
+const { version: nerviqVersion } = require('../../package.json');
+
+function escapeCell(value) {
+  if (value === null || value === undefined) return '';
+  return String(value)
+    .replace(/\r?\n/g, ' ')
+    .replace(/\|/g, '\\|');
+}
+
+function escapeInline(value) {
+  if (value === null || value === undefined) return '';
+  return String(value).replace(/\r?\n/g, ' ');
+}
+
+function scoreBadge(score) {
+  const s = Number.isFinite(score) ? Math.round(score) : 0;
+  let color;
+  if (s >= 80) color = 'brightgreen';
+  else if (s >= 60) color = 'yellow';
+  else color = 'red';
+  return `![score](https://img.shields.io/badge/nerviq_score-${s}%2F100-${color})`;
+}
+
+function severityFor(item) {
+  return item.severity || item.impact || 'medium';
+}
+
+function formatMarkdown(auditResult, options = {}) {
+  const platformLabel = auditResult.platformLabel || auditResult.platform || 'claude';
+  const score = auditResult.score ?? 0;
+  const passed = auditResult.passed ?? 0;
+  const failed = auditResult.failed ?? 0;
+  const skipped = auditResult.skipped ?? 0;
+  const version = auditResult.version || nerviqVersion;
+  const timestamp = auditResult.timestamp || new Date().toISOString();
+
+  const lines = [];
+
+  lines.push(`## Score: ${score}/100 ${scoreBadge(score)}`);
+  lines.push('');
+  lines.push(`**Platform:** ${platformLabel}  `);
+  lines.push(`**Checks:** ${passed} passed, ${failed} failed, ${skipped} skipped`);
+  lines.push('');
+
+  const top = Array.isArray(auditResult.topNextActions)
+    ? auditResult.topNextActions.slice(0, 5)
+    : [];
+
+  if (top.length > 0) {
+    lines.push('### Top next actions');
+    lines.push('');
+    for (const item of top) {
+      const sev = severityFor(item).toString().toUpperCase();
+      const title = escapeInline(item.name || item.title || item.key);
+      const key = escapeInline(item.key || item.id || '');
+      let loc = '';
+      if (item.file) {
+        loc = ` — \`${escapeInline(item.file)}${item.line ? ':' + item.line : ''}\``;
+      }
+      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('');
+  }
+
+  const failedResults = Array.isArray(auditResult.results)
+    ? auditResult.results.filter((r) => r.passed === false)
+    : [];
+
+  if (failedResults.length > 0) {
+    lines.push('<details>');
+    lines.push(`<summary>All failed checks (${failedResults.length})</summary>`);
+    lines.push('');
+    lines.push('| key | name | category | rating | file | line |');
+    lines.push('| --- | --- | --- | --- | --- | --- |');
+    for (const r of failedResults) {
+      const row = [
+        escapeCell(r.key),
+        escapeCell(r.name),
+        escapeCell(r.category),
+        escapeCell(r.rating ?? ''),
+        escapeCell(r.file || ''),
+        escapeCell(r.line || ''),
+      ];
+      lines.push(`| ${row.join(' | ')} |`);
+    }
+    lines.push('');
+    lines.push('</details>');
+    lines.push('');
+  }
+
+  lines.push(`---`);
+  lines.push(`Generated by [Nerviq](https://nerviq.net) v${version} · ${timestamp}`);
+
+  return lines.join('\n');
+}
+
+module.exports = { formatMarkdown };