@nerviq/cli 1.9.0 → 1.10.0

package/src/dashboard.js

@@ -68,7 +68,7 @@ function buildScoreOverTimeSvg(history) {
 
   return `
   <div class="card">
-    <h2>Score Over Time</h2>
+    <h2>Audit Snapshot Score Over Time</h2>
     <svg viewBox="0 0 ${w} ${h}" width="100%" style="max-width:${w}px">
       ${yLabels}
       <polyline points="${polyline}" fill="none" stroke="${COLORS.blue}" stroke-width="2"/>
@@ -119,11 +119,28 @@ function buildCategoryBreakdownSvg(results) {
   </div>`;
 }
 
+function getDashboardScoreMeta(history) {
+  if (history && history.length > 0) {
+    return {
+      label: 'Latest audit snapshot score',
+      note: 'Dashboard is anchored to the most recent saved audit snapshot. Trend and drift sections use audit snapshots only.',
+      consoleSource: 'latest audit snapshot',
+    };
+  }
+
+  return {
+    label: 'Live audit score',
+    note: 'No saved audit snapshots found, so this dashboard ran a live audit of the current repo. Run `nerviq audit --snapshot` to build history.',
+    consoleSource: 'live audit (no snapshots yet)',
+  };
+}
+
 function buildHtml(projectName, auditPayload, history) {
   const score = auditPayload.score ?? 0;
   const platform = auditPayload.platform || 'unknown';
   const results = auditPayload.results || [];
   const timestamp = new Date().toISOString();
+  const scoreMeta = getDashboardScoreMeta(history);
 
   // Top 5 failed checks sorted by impact severity
   const impactOrder = { critical: 0, high: 1, medium: 2, low: 3 };
@@ -184,7 +201,8 @@ function buildHtml(projectName, auditPayload, history) {
 
   <div class="card score-card">
     <div class="score-number" style="color:${scoreColor(score)}">${score}</div>
-    <div class="score-label">out of 100</div>
+    <div class="score-label">${escapeHtml(scoreMeta.label)}</div>
+    <div style="color:${COLORS.textDim};font-size:.85rem;margin-top:.75rem;max-width:520px;margin-left:auto;margin-right:auto">${escapeHtml(scoreMeta.note)}</div>
   </div>
 
   <div class="card">
@@ -238,6 +256,7 @@ async function generateDashboard(dir, flags = {}) {
     auditPayload = await audit({ dir, silent: true, platform: flags.platform || 'claude' });
   }
 
+  const scoreMeta = getDashboardScoreMeta(history);
   const html = buildHtml(projectName, auditPayload, history);
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
   fs.writeFileSync(outputPath, html, 'utf8');
@@ -247,8 +266,9 @@ async function generateDashboard(dir, flags = {}) {
     console.log('');
     console.log('  nerviq dashboard');
     console.log('  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550');
-    console.log(`  Score: ${auditPayload.score ?? '?'}/100`);
-    console.log(`  Snapshots: ${history.length}`);
+    console.log(`  Dashboard score: ${auditPayload.score ?? '?'}/100`);
+    console.log(`  Score source: ${scoreMeta.consoleSource}`);
+    console.log(`  Audit snapshots: ${history.length}`);
     console.log(`  Output: ${relPath}`);
     console.log('');
   }
@@ -261,7 +281,7 @@ async function generateDashboard(dir, flags = {}) {
     exec(cmd);
   }
 
-  return { outputPath, relativePath: relPath, score: auditPayload.score };
+  return { outputPath, relativePath: relPath, score: auditPayload.score, scoreSource: scoreMeta.consoleSource };
 }
 
 /**
@@ -274,13 +294,15 @@ function detectDrifts(history, threshold = 5) {
   for (let i = 0; i < history.length - 1; i++) {
     const current = history[i];
     const previous = history[i + 1];
-    if (current.score != null && previous.score != null) {
-      const delta = current.score - previous.score;
+    const currentScore = current.summary?.score;
+    const previousScore = previous.summary?.score;
+    if (currentScore != null && previousScore != null) {
+      const delta = currentScore - previousScore;
       if (Math.abs(delta) >= threshold) {
         drifts.push({
-          date: current.date || current.timestamp,
-          from: previous.score,
-          to: current.score,
+          date: current.createdAt || current.date || current.timestamp,
+          from: previousScore,
+          to: currentScore,
           delta,
         });
       }
@@ -307,8 +329,8 @@ function buildDriftAlertsHtml(drifts) {
 
   return `
     <div style="margin-top:32px">
-      <h2 style="color:${COLORS.text};font-size:18px;margin-bottom:12px">⚠ Score Drift Alerts</h2>
-      <p style="color:${COLORS.textDim};font-size:13px;margin-bottom:12px">Changes of 5+ points between consecutive snapshots</p>
+      <h2 style="color:${COLORS.text};font-size:18px;margin-bottom:12px">⚠ Audit Snapshot Drift Alerts</h2>
+      <p style="color:${COLORS.textDim};font-size:13px;margin-bottom:12px">Changes of 5+ points between consecutive audit snapshots</p>
       <table style="width:100%;border-collapse:collapse;background:${COLORS.surface};border-radius:8px;overflow:hidden">
         <thead><tr style="background:${COLORS.border}">
           <th style="padding:8px 12px;text-align:left;color:${COLORS.textDim};font-size:12px">Date</th>
@@ -375,7 +397,7 @@ function buildPortfolioHtml(repoResults) {
 
   <div class="card score-card">
     <div class="score-number" style="color:${scoreColor(avgScore)}">${avgScore}</div>
-    <div class="score-label">average score across ${repoResults.length} repos</div>
+    <div class="score-label">average live audit score across ${repoResults.length} repos</div>
   </div>
 
   <div class="highlights">
@@ -452,7 +474,7 @@ async function generatePortfolioDashboard(repoPaths, flags = {}) {
     console.log('  nerviq portfolio dashboard');
     console.log('  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550');
     console.log(`  Repos: ${repoResults.length}`);
-    console.log(`  Average score: ${avgScore}/100`);
+    console.log(`  Average live audit score: ${avgScore}/100`);
     console.log(`  Output: ${outputPath}`);
     console.log('');
   }

package/src/instruction-surfaces.js

@@ -0,0 +1,185 @@
+const path = require('path');
+
+const TEST_COMMAND_PATTERNS = [
+  /\b(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test\b/i,
+  /\b(?:python\s+-m\s+)?pytest\b/i,
+  /\bpython\s+manage\.py\s+test\b/i,
+  /\bdjango-admin\s+test\b/i,
+  /\bpython\s+-m\s+unittest\b/i,
+  /\bgo\s+test(?:\s|$)/i,
+  /\bcargo\s+test\b/i,
+  /\bmake\s+test\b/i,
+  /\bmix\s+test\b/i,
+  /\bbundle\s+exec\s+rspec\b/i,
+  /\brspec\b/i,
+  /\bphpunit\b/i,
+  /\bdotnet\s+test(?:\s|$)/i,
+  /\bflutter\s+test\b/i,
+  /\bswift\s+test\b/i,
+  /\bxcodebuild\b[^\n\r`]{0,200}\btest\b/i,
+  /\bgradlew?\s+test\b/i,
+  /\bmvn(?:w)?\s+test\b/i,
+  /\bplaywright\s+test\b/i,
+  /\bcypress\s+run\b/i,
+];
+
+const LINT_COMMAND_PATTERNS = [
+  /\b(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+lint\b/i,
+  /\beslint\b/i,
+  /\bprettier\b/i,
+  /\bruff(?:\s+(?:check|format))?\b/i,
+  /\bblack\b/i,
+  /\bflake8\b/i,
+  /\bpylint\b/i,
+  /\bmypy\b/i,
+  /\bpyright\b/i,
+  /\bgo\s+vet\b/i,
+  /\bgofmt\b/i,
+  /\bgofumpt\b/i,
+  /\bstaticcheck\b/i,
+  /\bgolangci-lint\b/i,
+  /\bcargo\s+clippy\b/i,
+  /\bflutter\s+analyze\b/i,
+  /\bdart\s+analyze\b/i,
+  /\bswiftlint\b/i,
+  /\bswift(?:-|\s+)format\b/i,
+  /\bdotnet\s+format(?:\s|$)/i,
+  /\bgradlew?\s+lint\b/i,
+  /\bmvn(?:w)?\s+(?:checkstyle:check|spotbugs:check|verify)\b/i,
+];
+
+const BUILD_COMMAND_PATTERNS = [
+  /\b(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+build\b/i,
+  /\btsc(?:\s|$)/i,
+  /\bgo\s+build(?:\s|$)/i,
+  /\bcargo\s+(?:build|check)\b/i,
+  /\bmake\s+build\b/i,
+  /\bdotnet\s+(?:build|publish)(?:\s|$)/i,
+  /\bmsbuild\b/i,
+  /\bflutter\s+build(?:\s|$)/i,
+  /\bswift\s+build\b/i,
+  /\bxcodebuild\b/i,
+  /\bgradlew?\s+(?:build|assemble)\b/i,
+  /\bmvn(?:w)?\s+(?:compile|package|verify|install)\b/i,
+  /\bpython\s+-m\s+build\b/i,
+  /\bpoetry\s+build\b/i,
+];
+
+function normalizePath(filePath) {
+  return String(filePath || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function addSurface(ctx, surfaces, seen, filePath) {
+  const normalized = normalizePath(filePath);
+  if (!normalized || seen.has(normalized)) return;
+  const content = typeof ctx.fileContent === 'function' ? (ctx.fileContent(normalized) || '') : '';
+  if (!content.trim()) return;
+  seen.add(normalized);
+  surfaces.push({ path: normalized, content });
+}
+
+function addDirSurfaces(ctx, surfaces, seen, dirPath, filter) {
+  if (typeof ctx.dirFiles !== 'function') return;
+  for (const entry of ctx.dirFiles(dirPath) || []) {
+    if (filter && !filter.test(entry)) continue;
+    addSurface(ctx, surfaces, seen, path.join(dirPath, entry));
+  }
+}
+
+function buildSurfaceList(ctx, scope) {
+  const surfaces = [];
+  const seen = new Set();
+  const includeReadme = scope === 'repo';
+
+  addSurface(ctx, surfaces, seen, 'CLAUDE.md');
+  addSurface(ctx, surfaces, seen, '.claude/CLAUDE.md');
+  addDirSurfaces(ctx, surfaces, seen, '.claude/rules', /\.md$/i);
+  addDirSurfaces(ctx, surfaces, seen, '.claude/commands', /\.md$/i);
+  addDirSurfaces(ctx, surfaces, seen, '.claude/agents', /\.md$/i);
+
+  if (scope === 'repo') {
+    addSurface(ctx, surfaces, seen, 'AGENTS.md');
+    addSurface(ctx, surfaces, seen, 'AGENTS.override.md');
+    addSurface(ctx, surfaces, seen, '.cursorrules');
+    addSurface(ctx, surfaces, seen, '.windsurfrules');
+    addSurface(ctx, surfaces, seen, 'GEMINI.md');
+    addSurface(ctx, surfaces, seen, '.gemini/GEMINI.md');
+    addSurface(ctx, surfaces, seen, '.github/copilot-instructions.md');
+    addDirSurfaces(ctx, surfaces, seen, '.cursor/rules', /\.(md|mdc)$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.cursor/commands', /\.md$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.windsurf/rules', /\.md$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.windsurf/workflows', /\.md$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.github/instructions', /\.instructions\.md$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.github/prompts', /\.prompt\.md$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.opencode/commands', /\.(md|markdown|ya?ml)$/i);
+    addDirSurfaces(ctx, surfaces, seen, '.gemini/agents', /\.md$/i);
+  }
+
+  if (includeReadme) {
+    addSurface(ctx, surfaces, seen, 'README.md');
+    addSurface(ctx, surfaces, seen, 'CONTRIBUTING.md');
+  }
+
+  return surfaces;
+}
+
+function getSurfaceBundle(ctx, scope) {
+  const cacheKey = scope === 'repo' ? '__nerviqRepoInstructionBundle' : '__nerviqClaudeInstructionBundle';
+  if (ctx && ctx[cacheKey] !== undefined) return ctx[cacheKey];
+  const bundle = buildSurfaceList(ctx, scope)
+    .map((surface) => surface.content)
+    .join('\n\n');
+  if (ctx) ctx[cacheKey] = bundle;
+  return bundle;
+}
+
+function matchesAny(text, patterns) {
+  const normalized = String(text || '');
+  return patterns.some((pattern) => {
+    pattern.lastIndex = 0;
+    return pattern.test(normalized);
+  });
+}
+
+function hasDocumentedTestCommand(text) {
+  return matchesAny(text, TEST_COMMAND_PATTERNS);
+}
+
+function hasDocumentedLintCommand(text) {
+  return matchesAny(text, LINT_COMMAND_PATTERNS);
+}
+
+function hasDocumentedBuildCommand(text) {
+  return matchesAny(text, BUILD_COMMAND_PATTERNS);
+}
+
+function hasDocumentedVerificationGuidance(text) {
+  const normalized = String(text || '');
+  if (!normalized.trim()) return false;
+  return hasDocumentedTestCommand(normalized) ||
+    hasDocumentedLintCommand(normalized) ||
+    hasDocumentedBuildCommand(normalized) ||
+    (/\b(?:verification|verify|self-check|quality gate)\b/i.test(normalized) &&
+      matchesAny(normalized, [
+        ...TEST_COMMAND_PATTERNS,
+        ...LINT_COMMAND_PATTERNS,
+        ...BUILD_COMMAND_PATTERNS,
+      ]));
+}
+
+function getClaudeInstructionBundle(ctx) {
+  return getSurfaceBundle(ctx, 'claude');
+}
+
+function getRepoInstructionBundle(ctx) {
+  return getSurfaceBundle(ctx, 'repo');
+}
+
+module.exports = {
+  getClaudeInstructionBundle,
+  getRepoInstructionBundle,
+  hasDocumentedVerificationGuidance,
+  hasDocumentedTestCommand,
+  hasDocumentedLintCommand,
+  hasDocumentedBuildCommand,
+};

package/src/locales/en.json

@@ -7,7 +7,7 @@
   "audit.platform": "Platform: {platform} ({version})",
   "audit.domainPacks": "Domain packs: {packs}",
   "audit.scope": "Scope: {message}",
-  "audit.score": "Score: {score}/100  ({passed}/{total} checks passing)",
+  "audit.score": "Live audit score: {score}  ({passed}/{total} checks passing)",
   "audit.found": "Found: {files}",
   "audit.excellent": "Excellent setup — production-ready governance",
   "audit.strong": "Strong setup — {count} critical items to address",

package/src/locales/es.json

@@ -7,7 +7,7 @@
   "audit.platform": "Plataforma: {platform} ({version})",
   "audit.domainPacks": "Paquetes de dominio: {packs}",
   "audit.scope": "Alcance: {message}",
-  "audit.score": "Puntuación: {score}/100  ({passed}/{total} verificaciones aprobadas)",
+  "audit.score": "Puntuación de auditoría en vivo: {score}  ({passed}/{total} verificaciones aprobadas)",
   "audit.found": "Encontrado: {files}",
   "audit.excellent": "Configuración excelente — gobernanza lista para producción",
   "audit.strong": "Configuración sólida — {count} elementos críticos por resolver",

package/src/stack-checks.js

@@ -358,7 +358,7 @@ function buildStackChecks({ platform, objectPrefix, idPrefix, docs }) {
       impact: 'high',
       fix: 'Document the XCTest or `xcodebuild test` workflow so iOS verification is part of the default path.',
       check: (ctx) => hasSwiftSurface(ctx)
-        ? /xctest|swift test|xcodebuild test|test target/i.test(projectText(ctx, docs)) ||
+        ? /xctest|swift test|xcodebuild[^\n\r]{0,200}\btest\b|test target/i.test(projectText(ctx, docs)) ||
           hasMatchingFile(ctx, /(^|[\\/])Tests([\\/]|$)|XCTestCase/i)
         : null,
     }),

package/src/synergy/report.js

@@ -54,6 +54,7 @@ function formatSynergyReport(options) {
   lines.push(c('  ║     SYNERGY DASHBOARD [EXPERIMENTAL]             ║', 'blue'));
   lines.push(c('  ╚══════════════════════════════════════════════════╝', 'blue'));
   lines.push(c('  Static routing rules. Learned routing planned for v2.0.', 'dim'));
+  lines.push(c('  Harmony is the GA cross-platform surface. Treat Synergy as advisory research output.', 'dim'));
   lines.push('');
 
   // Compound audit

package/src/techniques.js

@@ -4,8 +4,15 @@
  * Each technique includes: what to check, how to fix, impact level.
  */
 
-const fs = require('fs');
-const path = require('path');
+const fs = require('fs');
+const path = require('path');
+const {
+  getClaudeInstructionBundle,
+  hasDocumentedVerificationGuidance,
+  hasDocumentedTestCommand,
+  hasDocumentedLintCommand,
+  hasDocumentedBuildCommand,
+} = require('./instruction-surfaces');
 
 function hasFrontendSignals(ctx) {
   const pkg = ctx.fileContent('package.json') || '';
@@ -444,62 +451,58 @@ const TECHNIQUES = {
   // === QUALITY & TESTING (category: 'quality') ================
   // ============================================================
 
-  verificationLoop: {
-    id: 93,
-    name: 'Verification criteria in CLAUDE.md',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /\b(npm test|yarn test|pnpm test|pytest|go test|make test|npm run lint|yarn lint|npx |ruff |eslint)\b/i.test(md) ||
-        /\b(test command|lint command|build command|verify|run tests|run lint)\b/i.test(md);
-    },
-    impact: 'critical',
-    rating: 5,
-    category: 'quality',
-    fix: 'Add test/lint/build commands to CLAUDE.md so Claude can verify its own work.',
-    template: null
-  },
-
-  testCommand: {
-    id: 93001,
-    name: 'CLAUDE.md contains a test command',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /npm test|pytest|jest|vitest|cargo test|go test|mix test|rspec/.test(md);
-    },
-    impact: 'high',
-    rating: 5,
-    category: 'quality',
-    fix: 'Add an explicit test command to CLAUDE.md (e.g. "Run `npm test` before committing").',
-    template: null
-  },
-
-  lintCommand: {
-    id: 93002,
-    name: 'CLAUDE.md contains a lint command',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /eslint|prettier|ruff|black|clippy|golangci-lint|rubocop|npm run lint|yarn lint|pnpm lint|bun lint/.test(md);
-    },
-    impact: 'high',
-    rating: 4,
-    category: 'quality',
-    fix: 'Add a lint command to CLAUDE.md so Claude auto-formats and checks code style.',
-    template: null
-  },
-
-  buildCommand: {
-    id: 93003,
-    name: 'CLAUDE.md contains a build command',
-    check: (ctx) => {
-      const md = ctx.claudeMdContent() || '';
-      return /npm run build|cargo build|go build|make|tsc|gradle build|mvn compile/.test(md);
-    },
-    impact: 'medium',
-    rating: 4,
-    category: 'quality',
-    fix: 'Add a build command to CLAUDE.md so Claude can verify compilation before committing.',
-    template: null
-  },
+  verificationLoop: {
+    id: 93,
+    name: 'Claude instruction surfaces include verification criteria',
+    check: (ctx) => {
+      const docs = getClaudeInstructionBundle(ctx);
+      return hasDocumentedVerificationGuidance(docs);
+    },
+    impact: 'critical',
+    rating: 5,
+    category: 'quality',
+    fix: 'Add canonical test/lint/build commands to your Claude instruction surfaces (CLAUDE.md, imported docs, or .claude/commands) so Claude can verify its own work.',
+    template: null
+  },
+
+  testCommand: {
+    id: 93001,
+    name: 'Claude instruction surfaces include a test command',
+    check: (ctx) => {
+      return hasDocumentedTestCommand(getClaudeInstructionBundle(ctx));
+    },
+    impact: 'high',
+    rating: 5,
+    category: 'quality',
+    fix: 'Add an explicit test command to your Claude instruction surfaces (for example "Run `npm test` before committing").',
+    template: null
+  },
+
+  lintCommand: {
+    id: 93002,
+    name: 'Claude instruction surfaces include a lint command',
+    check: (ctx) => {
+      return hasDocumentedLintCommand(getClaudeInstructionBundle(ctx));
+    },
+    impact: 'high',
+    rating: 4,
+    category: 'quality',
+    fix: 'Add a lint command to your Claude instruction surfaces so Claude can check style and static quality automatically.',
+    template: null
+  },
+
+  buildCommand: {
+    id: 93003,
+    name: 'Claude instruction surfaces include a build command',
+    check: (ctx) => {
+      return hasDocumentedBuildCommand(getClaudeInstructionBundle(ctx));
+    },
+    impact: 'medium',
+    rating: 4,
+    category: 'quality',
+    fix: 'Add a build command to your Claude instruction surfaces so Claude can verify compilation before committing.',
+    template: null
+  },
 
   // ============================================================
   // === GIT SAFETY (category: 'git') ===========================

package/src/workspace.js

@@ -166,6 +166,17 @@ function parseWorkspaceSelection(value) {
   return unique(String(value).split(',').map((item) => item.trim()).filter(Boolean));
 }
 
+function summarizeAuditResult(result, scoreType, scope) {
+  return {
+    scope,
+    scoreType,
+    score: typeof result?.score === 'number' ? result.score : null,
+    passed: typeof result?.passed === 'number' ? result.passed : 0,
+    total: typeof result?.checkCount === 'number' ? result.checkCount : 0,
+    topAction: result?.topNextActions?.[0]?.name || null,
+  };
+}
+
 async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
   const { audit } = require('./audit');
   const rootDir = path.resolve(dir);
@@ -175,6 +186,22 @@ async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
     ? expandWorkspacePatterns(rootDir, selectedPatterns)
     : detectWorkspaces(rootDir);
   const results = [];
+  let rootGovernance;
+
+  try {
+    const rootResult = await audit({ dir: rootDir, platform, silent: true });
+    rootGovernance = summarizeAuditResult(rootResult, 'root-live-audit', 'root-governance');
+  } catch (error) {
+    rootGovernance = {
+      scope: 'root-governance',
+      scoreType: 'root-live-audit',
+      score: null,
+      passed: 0,
+      total: 0,
+      topAction: null,
+      error: error.message,
+    };
+  }
 
   for (const workspacePath of workspacePaths) {
     const absPath = path.join(rootDir, workspacePath);
@@ -185,10 +212,7 @@ async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
         workspace: workspacePath,
         dir: absPath,
         platform,
-        score: result.score,
-        passed: result.passed,
-        total: result.checkCount,
-        topAction: result.topNextActions?.[0]?.name || null,
+        ...summarizeAuditResult(result, 'workspace-live-audit', 'workspace-package'),
         result,
       });
     } catch (error) {
@@ -197,6 +221,8 @@ async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
         workspace: workspacePath,
         dir: absPath,
         platform,
+        scope: 'workspace-package',
+        scoreType: 'workspace-live-audit',
         score: null,
         passed: 0,
         total: 0,
@@ -210,17 +236,36 @@ async function auditWorkspaces(dir, workspaceGlobs, platform = 'claude') {
   const averageScore = validScores.length > 0
     ? Math.round(validScores.reduce((sum, value) => sum + value, 0) / validScores.length)
     : 0;
+  const maxScore = validScores.length > 0 ? Math.max(...validScores) : 0;
+  const minScore = validScores.length > 0 ? Math.min(...validScores) : 0;
 
   return {
+    summaryType: 'monorepo-workspace-audit',
     rootDir,
     platform,
+    selectionMode: selectedPatterns.length > 0 ? 'explicit-patterns' : 'detected-workspaces',
     patterns: sourcePatterns,
+    rootGovernance,
+    workspaceAggregate: {
+      scope: 'workspace-aggregate',
+      scoreType: 'workspace-average-live-audit',
+      score: averageScore,
+      workspaceCount: workspacePaths.length,
+      maxScore,
+      minScore,
+    },
+    scoreSemantics: {
+      rootGovernance: 'Root repo live audit for shared instructions, hooks, permissions, and top-level governance files.',
+      workspaceAggregate: 'Average of the selected workspace live audit scores. This is a package coverage rollup, not the root repo score.',
+      workspaceEntries: 'Each workspace row is a package-level live audit. Package scores can differ from the root governance score for legitimate reasons.',
+    },
     workspaces: results,
     detectedWorkspaces: workspacePaths,
     workspaceCount: workspacePaths.length,
+    averageScoreType: 'workspace-average-live-audit',
     averageScore,
-    maxScore: validScores.length > 0 ? Math.max(...validScores) : 0,
-    minScore: validScores.length > 0 ? Math.min(...validScores) : 0,
+    maxScore,
+    minScore,
   };
 }