docguard-cli 0.28.0 → 0.30.0

package/cli/commands/memory.mjs

@@ -21,8 +21,12 @@
  * Zero NPM dependencies. Pure orchestration of existing diff helpers.
  */
 
+import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
 import { diffRoutes, diffEntities, diffEnvVars, diffTechStack } from './diff.mjs';
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { runGuardInternal } from './guard.mjs';
 
 /**
  * Compute an accuracy score for a single domain. Returns:
@@ -47,7 +51,118 @@ function _domainAccuracy(d) {
   };
 }
 
+// ── Context pack (v0.29) ─────────────────────────────────────────────────────
+
+/** H2 sections of AGENTS.md whose heading reads like rules/conventions/workflow. */
+function extractConventions(agentsMd, capLines = 60) {
+  const out = [];
+  const lines = agentsMd.split('\n');
+  let taking = false;
+  for (const line of lines) {
+    const h2 = line.match(/^##\s+(.+)$/);
+    if (h2) taking = /rules|conventions|workflow/i.test(h2[1]);
+    if (taking) {
+      out.push(line);
+      if (out.length >= capLines) {
+        out.push('<!-- truncated — read AGENTS.md for the full rules -->');
+        break;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * `docguard memory --pack` — write .docguard/context-pack.md: a compact,
+ * code-truth-stamped session-start context for an AI agent. Everything in it
+ * is derived from scanners (buildMemoryPlan) and guard — numbers, not prose —
+ * so it can't hallucinate and is always regenerable.
+ */
+function runMemoryPack(projectDir, config, flags) {
+  const plan = buildMemoryPlan(projectDir, config);
+  const guard = runGuardInternal(projectDir, config);
+  const lines = [];
+
+  lines.push(`# Context Pack — ${config.projectName}`);
+  lines.push('');
+  lines.push(`<!-- Generated by \`docguard memory --pack\` ${new Date().toISOString()} — regenerate, don't edit -->`);
+  lines.push('');
+  lines.push(`**Guard:** ${guard.status} — ${guard.passed}/${guard.total} checks (${guard.errors} error(s), ${guard.warnings} warning(s))`);
+  lines.push('');
+
+  lines.push('## Code-truth surface');
+  lines.push('');
+  lines.push(`- Stack: ${plan.profile.languages.join(', ') || 'unknown'}${plan.profile.frameworks.length ? ` · ${plan.profile.frameworks.join(', ')}` : ''} · kind: ${plan.profile.kind}`);
+  lines.push(`- Modules: ${plan.surface.modules.length} · Endpoints: ${plan.surface.endpoints.length} · Entities: ${plan.surface.entities.length} · Env vars: ${plan.surface.envVars.length}`);
+  lines.push(`- Tests: ${plan.surface.tests.totalFiles} files, ${plan.surface.tests.totalCases} cases`);
+  lines.push('');
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(docsDir)) {
+    lines.push('## Canonical docs');
+    lines.push('');
+    let entries = [];
+    try { entries = readdirSync(docsDir).filter(f => f.endsWith('.md')).sort(); } catch { /* ignore */ }
+    for (const doc of entries) {
+      let reviewed = '';
+      try {
+        const m = readFileSync(resolve(docsDir, doc), 'utf-8').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
+        if (m) reviewed = ` (last-reviewed ${m[1]})`;
+      } catch { /* ignore */ }
+      lines.push(`- docs-canonical/${doc}${reviewed}`);
+    }
+    lines.push('');
+  }
+
+  const agentsPath = resolve(projectDir, 'AGENTS.md');
+  if (existsSync(agentsPath)) {
+    let conventions = [];
+    try { conventions = extractConventions(readFileSync(agentsPath, 'utf-8')); } catch { /* ignore */ }
+    if (conventions.length > 0) {
+      lines.push('## Project rules (from AGENTS.md)');
+      lines.push('');
+      lines.push(...conventions);
+      lines.push('');
+    }
+  }
+
+  const driftPath = resolve(projectDir, 'DRIFT-LOG.md');
+  if (existsSync(driftPath)) {
+    try {
+      const drift = readFileSync(driftPath, 'utf-8');
+      const entries = drift.match(/^##\s+.+$/gm) || [];
+      if (entries.length > 0) {
+        lines.push('## Known drift');
+        lines.push('');
+        lines.push(`- ${entries.length} logged deviation(s); latest: ${entries[entries.length - 1].replace(/^##\s+/, '')}`);
+        lines.push('');
+      }
+    } catch { /* ignore */ }
+  }
+
+  lines.push('---');
+  lines.push('Verify claims: `docguard verify --semantic` · Full docs: `llms-full.txt`');
+  lines.push('');
+  const content = lines.join('\n');
+
+  if (flags.stdout) {
+    console.log(content);
+    return;
+  }
+  const outDir = resolve(projectDir, '.docguard');
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  const outPath = resolve(outDir, 'context-pack.md');
+  writeFileSync(outPath, content, 'utf-8');
+  console.log(`${c.bold}🧠 DocGuard Context Pack${c.reset}`);
+  console.log(`${c.green}✅ Wrote ${outPath}${c.reset} ${c.dim}(${lines.length} lines — load at agent session start)${c.reset}`);
+  console.log('');
+}
+
 export function runMemory(projectDir, config, flags) {
+  // v0.29: --pack writes the agent context pack and exits — a separate output
+  // artifact, not a display mode of the accuracy drill-down below.
+  if (flags.pack) return runMemoryPack(projectDir, config, flags);
+
   const isJson = flags.format === 'json';
   const wantsDiff = flags.diff || (flags.args || []).includes('--diff');
 

package/cli/commands/score.mjs

@@ -9,6 +9,8 @@ import { execSync } from 'node:child_process';
 import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
+import { extractSemanticClaims } from '../scanners/semantic-claims.mjs';
+import { assessAgentReadability } from '../scanners/agent-readability.mjs';
 
 /**
  * Detect whether the project configures a test runner (the "Check 3" of the
@@ -299,11 +301,17 @@ export function runScore(projectDir, config, flags) {
   console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
 
   for (const attr of alcoa.attributes) {
-    const icon = attr.met ? `${c.green}✅` : `${c.yellow}⚠️`;
-    const status = attr.met ? `${c.green}${attr.evidence}` : `${c.yellow}${attr.gap}`;
-    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${status}${c.reset}`);
+    // `unverified` is a third state: not a green pass, but not a red gap either —
+    // "checked the structure, can't confirm the facts." Render it neutrally (🔍,
+    // cyan) so it reads as a to-do, not a failure.
+    const unverified = attr.status === 'unverified';
+    const icon = attr.met ? `${c.green}✅` : unverified ? `${c.cyan}🔍` : `${c.yellow}⚠️`;
+    const tone = attr.met ? c.green : unverified ? c.cyan : c.yellow;
+    const body = attr.met ? attr.evidence : attr.gap;
+    console.log(`  ${icon} ${attr.name.padEnd(16)}${c.reset} — ${tone}${body}${c.reset}`);
     if (!attr.met && attr.fix) {
-      console.log(`  ${c.dim}     Fix: ${attr.fix}${c.reset}`);
+      const verb = unverified ? 'Verify' : 'Fix';
+      console.log(`  ${c.dim}     ${verb}: ${attr.fix}${c.reset}`);
     }
   }
 
@@ -314,6 +322,22 @@ export function runScore(projectDir, config, flags) {
   }
   console.log('');
 
+  // ── Agent Readability (v0.29) ──
+  // Display-only, like ALCOA+ — never feeds the gating CDD grade. Answers the
+  // 2026 question: can an AI consumer FIND, QUOTE, and TRUST these docs?
+  const agentRead = assessAgentReadability(projectDir, config);
+  console.log(`  ${c.bold}🤖 Agent Readability${c.reset} ${c.dim}(how well AI consumers can read this repo)${c.reset}`);
+  console.log(`  ${c.dim}─────────────────────────────────${c.reset}`);
+  for (const m of agentRead.metrics) {
+    const icon = m.score >= 60 ? `${c.green}✅` : `${c.yellow}⚠️`;
+    const tone = m.score >= 60 ? c.green : c.yellow;
+    console.log(`  ${icon} ${m.label.padEnd(28)}${c.reset} — ${tone}${m.detail}${c.reset}`);
+    if (m.fix) console.log(`  ${c.dim}     Fix: ${m.fix}${c.reset}`);
+  }
+  const arColor = agentRead.score >= 75 ? c.green : agentRead.score >= 40 ? c.yellow : c.red;
+  console.log(`\n  ${arColor}${c.bold}Agent Readability: ${agentRead.score}% (${agentRead.grade})${c.reset}`);
+  console.log('');
+
   // Badge snippet
   const bColor = totalScore >= 90 ? 'brightgreen' : totalScore >= 80 ? 'green' : totalScore >= 70 ? 'yellowgreen' : totalScore >= 60 ? 'yellow' : totalScore >= 50 ? 'orange' : 'red';
   const badgeUrl = `https://img.shields.io/badge/CDD_Score-${totalScore}%2F100_(${grade})-${bColor}`;
@@ -411,14 +435,54 @@ function computeAlcoaCompliance(projectDir, config, scores) {
   });
 
   // 5. Accurate — Do docs match the code?
-  const accurate = scores.drift >= 80 && scores.docQuality >= 50;
-  attributes.push({
-    name: 'Accurate',
-    met: accurate,
-    evidence: accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%` : null,
-    gap: !accurate ? `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate` : null,
-    fix: !accurate ? 'Run docguard diagnose to find doc/code mismatches' : null,
-  });
+  //
+  // Field report #6: this attribute used to read `met` purely from structural
+  // signals (drift markers + prose quality). That let it show ✅ "100%" while a
+  // watched doc stated a factually wrong number — the confidence-inverting false
+  // negative the field report is about. Structure passing is necessary but NOT
+  // sufficient for "accurate"; the factual claims (counts/limits/enums) have to be
+  // verified against code, and DocGuard's deterministic core can't do that — only
+  // an agent via `verify --semantic` can. So we add a third, honest state:
+  //   met        — structure sound AND no unverified factual claims exist
+  //   unverified — structure sound BUT documented claims remain unchecked vs code
+  //   unmet      — structural drift/quality below bar
+  // `unverified` counts as not-met for the ALCOA percentage (so the score stops
+  // overclaiming), but renders as a neutral 🔍 (not a ⚠️ failure) — "I haven't
+  // confirmed this," not "this is wrong." This is display-only: it never touches
+  // the gating CDD grade (totalScore), which CI thresholds read.
+  const structurallyAccurate = scores.drift >= 80 && scores.docQuality >= 50;
+  let unverifiedClaims = 0;
+  if (structurallyAccurate) {
+    try { unverifiedClaims = extractSemanticClaims(projectDir, config).length; } catch { /* extractor best-effort */ }
+  }
+  if (!structurallyAccurate) {
+    attributes.push({
+      name: 'Accurate',
+      met: false,
+      status: 'unmet',
+      evidence: null,
+      gap: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}% — docs may be inaccurate`,
+      fix: 'Run docguard diagnose to find doc/code mismatches',
+    });
+  } else if (unverifiedClaims > 0) {
+    attributes.push({
+      name: 'Accurate',
+      met: false,
+      status: 'unverified',
+      evidence: null,
+      gap: `Structure sound (drift ${scores.drift}%, quality ${scores.docQuality}%), but ${unverifiedClaims} documented claim(s) (counts/limits/enums) are unverified against code`,
+      fix: 'Run docguard verify --semantic to check the documented values against the code',
+    });
+  } else {
+    attributes.push({
+      name: 'Accurate',
+      met: true,
+      status: 'met',
+      evidence: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%, no unverified factual claims`,
+      gap: null,
+      fix: null,
+    });
+  }
 
   // 6. Complete — Are all required docs present?
   const complete = scores.structure >= 80;

package/cli/commands/trace.mjs

@@ -7,8 +7,9 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { resolve, join, extname, basename, relative } from 'node:path';
+import { resolve, join, extname, basename, relative, dirname } from 'node:path';
 import { c } from '../shared.mjs';
+import { detectSpecKit } from '../scanners/speckit.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -134,6 +135,11 @@ export function runTrace(projectDir, config, flags) {
     return runTraceReverse(projectDir, config, flags);
   }
 
+  // Per-feature spec-kit adherence scoring when --features is set.
+  if (flags.features) {
+    return runTraceFeatures(projectDir, config, flags);
+  }
+
   // v0.16-P1: same headless-mode pattern as guard/score. Reported by Python
   // user — trace --format json was leaking ANSI escapes before the body.
   const isJson = flags.format === 'json';
@@ -366,6 +372,363 @@ function scanDir(rootDir, dir, files) {
   }
 }
 
+// ── Per-feature spec adherence (trace --features) ───────────────────────────
+//
+// Scores each detected spec-kit feature's implementation adherence
+// individually (inspired by spec-kit-retrospective), instead of only the
+// repo-wide scores that `docguard score` produces. Deterministic signals only —
+// no LLM judgment:
+//
+//   reqCoverage          40%  FR-/SC- IDs in spec.md referenced by any test file
+//   taskCompletion       25%  checked/total `- [x]` tasks in tasks.md
+//   taskEvidence         20%  checked tasks whose line names an existing file
+//   artifactCompleteness 15%  spec.md (40%) + plan.md (30%) + tasks.md (30%)
+//
+// A signal that cannot be measured (no tasks.md, no requirement IDs, no
+// checked task names a parseable path) is NEUTRAL: excluded from the weighted
+// sum and its weight redistributed across the measurable signals. This mirrors
+// the traceability validator's "no requirement IDs → silently pass" stance —
+// absence of a convention is not evidence of low adherence (missing artifacts
+// are already priced in by artifactCompleteness).
+
+const FEATURE_SIGNAL_WEIGHTS = {
+  reqCoverage: 0.40,
+  taskCompletion: 0.25,
+  taskEvidence: 0.20,
+  artifactCompleteness: 0.15,
+};
+
+// Grade bands mirrored from cli/scanners/agent-readability.mjs GRADES.
+// Display-only — never feeds the gating CDD grade that CI thresholds read.
+const FEATURE_GRADES = [[90, 'A'], [75, 'B'], [60, 'C'], [40, 'D']];
+
+function featureGrade(score) {
+  for (const [min, g] of FEATURE_GRADES) if (score >= min) return g;
+  return 'F';
+}
+
+// Spec-kit requirement IDs scored per feature. Subset of the traceability
+// validator's DEFAULT_REQ_PATTERNS (cli/validators/traceability.mjs) — the two
+// ID families spec-kit's spec-template.md mandates.
+const FEATURE_REQ_RE = /\b(?:FR|SC)-\d{2,4}\b/g;
+
+// Path-token heuristic mirrored from cli/scanners/semantic-claims.mjs
+// CITED_CODE_RE: a backticked or bare path-like token with a code extension.
+const TASK_PATH_RE = /`?([\w./-]+\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json))`?/g;
+
+// 20-char bar mirrored from cli/commands/score.mjs renderBar (not exported
+// there; score.mjs is display-conventions-only for this feature).
+function featureBar(score) {
+  const filled = Math.round(score / 5);
+  const empty = 20 - filled;
+  const color = score >= 80 ? c.green : score >= 60 ? c.yellow : c.red;
+  return `${color}${'█'.repeat(filled)}${c.dim}${'░'.repeat(empty)}${c.reset}`;
+}
+
+/**
+ * Collect every FR-/SC- ID referenced anywhere in a test file, once for the
+ * whole project. Test-file discovery mirrors the traceability validator's
+ * scanTestFilesForReferences(): TEST_PATTERNS ∪ __tests__/ ∪ tests?/ dirs, and
+ * any occurrence of the ID in file content counts (not just @req lines).
+ */
+function collectTestReferencedIds(projectDir) {
+  const projectFiles = [];
+  scanDir(projectDir, projectDir, projectFiles);
+  const testFiles = projectFiles.filter(f =>
+    TEST_PATTERNS.some(p => p.test(f)) || /__tests__\//.test(f) || /tests?\//.test(f)
+  );
+
+  const ids = new Set();
+  for (const rel of testFiles) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, rel), 'utf-8'); } catch { continue; }
+    FEATURE_REQ_RE.lastIndex = 0;
+    let m;
+    while ((m = FEATURE_REQ_RE.exec(content)) !== null) ids.add(m[0]);
+  }
+  return ids;
+}
+
+/**
+ * Compute the four adherence signals for one detected spec-kit feature.
+ * Each signal: { applicable, value (0..1 | null), ...n/m detail fields }.
+ */
+function computeFeatureSignals(projectDir, feature, testRefIds) {
+  // ── artifactCompleteness — always measurable ──
+  const artifactValue = (feature.hasSpec ? 0.4 : 0)
+    + (feature.hasPlan ? 0.3 : 0)
+    + (feature.hasTasks ? 0.3 : 0);
+
+  // ── taskCompletion + taskEvidence — parse tasks.md checklist lines ──
+  let totalTasks = 0, checkedTasks = 0, evidenced = 0, considered = 0;
+  if (feature.hasTasks && feature.tasksPath) {
+    let content = null;
+    try { content = readFileSync(feature.tasksPath, 'utf-8'); } catch { /* unreadable → no tasks */ }
+    if (content !== null) {
+      for (const line of content.split('\n')) {
+        const box = /^\s*[-*]\s*\[([ xX])\]/.exec(line);
+        if (!box) continue;
+        totalTasks++;
+        if (box[1] === ' ') continue;
+        checkedTasks++;
+        // Evidence: any named path on the line that exists in the project.
+        // Checked tasks with no parseable path are neutral (skip denominator).
+        TASK_PATH_RE.lastIndex = 0;
+        let tok, sawToken = false, exists = false;
+        while ((tok = TASK_PATH_RE.exec(line)) !== null) {
+          sawToken = true;
+          if (existsSync(resolve(projectDir, tok[1].replace(/^\.\//, '')))) { exists = true; break; }
+        }
+        if (sawToken) { considered++; if (exists) evidenced++; }
+      }
+    }
+  }
+
+  // ── reqCoverage — spec.md IDs that appear in ANY test file ──
+  const specIds = [];
+  if (feature.hasSpec && feature.specPath) {
+    try {
+      const spec = readFileSync(feature.specPath, 'utf-8');
+      const seen = new Set();
+      FEATURE_REQ_RE.lastIndex = 0;
+      let m;
+      while ((m = FEATURE_REQ_RE.exec(spec)) !== null) {
+        if (!seen.has(m[0])) { seen.add(m[0]); specIds.push(m[0]); }
+      }
+    } catch { /* unreadable spec → no IDs */ }
+  }
+  const covered = specIds.filter(id => testRefIds.has(id));
+  const uncovered = specIds.filter(id => !testRefIds.has(id));
+
+  return {
+    reqCoverage: {
+      applicable: specIds.length > 0,
+      value: specIds.length > 0 ? covered.length / specIds.length : null,
+      covered: covered.length,
+      total: specIds.length,
+      uncovered,
+    },
+    taskCompletion: {
+      applicable: totalTasks > 0,
+      value: totalTasks > 0 ? checkedTasks / totalTasks : null,
+      checked: checkedTasks,
+      total: totalTasks,
+    },
+    taskEvidence: {
+      applicable: considered > 0,
+      value: considered > 0 ? evidenced / considered : null,
+      evidenced,
+      considered,
+    },
+    artifactCompleteness: {
+      applicable: true,
+      value: artifactValue,
+      spec: feature.hasSpec,
+      plan: feature.hasPlan,
+      tasks: feature.hasTasks,
+    },
+  };
+}
+
+/** Weighted 0–100 score over the applicable signals (weights renormalized). */
+function scoreFromSignals(signals) {
+  let weighted = 0, weightTotal = 0;
+  for (const [key, weight] of Object.entries(FEATURE_SIGNAL_WEIGHTS)) {
+    const s = signals[key];
+    if (!s.applicable) continue;
+    weighted += weight * s.value;
+    weightTotal += weight;
+  }
+  return weightTotal > 0 ? Math.round((weighted / weightTotal) * 100) : 0;
+}
+
+/**
+ * The lowest-valued applicable signal. Iteration order is descending weight,
+ * and replacement is strict-less-than, so ties resolve to the highest-impact
+ * signal — the one worth fixing first.
+ */
+function weakestSignal(signals) {
+  let worstKey = null;
+  for (const key of Object.keys(FEATURE_SIGNAL_WEIGHTS)) {
+    const s = signals[key];
+    if (!s.applicable) continue;
+    if (worstKey === null || s.value < signals[worstKey].value) worstKey = key;
+  }
+  return worstKey;
+}
+
+function fixHintFor(key, s, feature) {
+  switch (key) {
+    case 'reqCoverage':
+      return `Cover the untested spec IDs (e.g. ${s.uncovered[0]}) — reference them from tests via @req annotations`;
+    case 'taskCompletion':
+      return `Complete (or prune) the ${s.total - s.checked} unchecked task(s) in tasks.md`;
+    case 'taskEvidence':
+      return `${s.considered - s.evidenced} checked task(s) name files that don't exist — fix stale paths or uncheck them`;
+    case 'artifactCompleteness': {
+      const missing = [
+        feature.hasSpec ? null : 'spec.md',
+        feature.hasPlan ? null : 'plan.md',
+        feature.hasTasks ? null : 'tasks.md',
+      ].filter(Boolean);
+      return `Add ${missing.join(', ')} to complete the artifact set`;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * `docguard trace --features` — per-feature spec-kit adherence report.
+ * Reuses detectSpecKit() for feature discovery (no re-implementation).
+ */
+export function runTraceFeatures(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🎯 DocGuard Trace (features) — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Scoring per-feature spec adherence (spec-kit)...${c.reset}\n`);
+  }
+
+  const speckit = detectSpecKit(projectDir);
+  if (!speckit.detected || speckit.specs.length === 0) {
+    // Same empty-state contract as trace --reverse: JSON stays parseable with
+    // an `error` field; text gets an actionable pointer.
+    if (isJson) {
+      console.log(JSON.stringify({
+        features: [],
+        summary: { features: 0, avgScore: null, worst: null },
+        error: 'no spec-kit features detected',
+        timestamp: new Date().toISOString(),
+      }, null, 2));
+    } else {
+      console.log(`  ${c.yellow}No spec-kit features detected.${c.reset}`);
+      console.log(`  ${c.dim}Feature scoring needs .specify/specs/** or specs/** (spec.md/plan.md/tasks.md). Run \`specify init\` to start.${c.reset}`);
+    }
+    return;
+  }
+
+  const testRefIds = collectTestReferencedIds(projectDir);
+
+  const features = speckit.specs.map(f => {
+    const signals = computeFeatureSignals(projectDir, f, testRefIds);
+    const score = scoreFromSignals(signals);
+    const weakest = weakestSignal(signals);
+    const needsFix = weakest !== null && signals[weakest].value < 1;
+    return {
+      name: f.name,
+      dir: relative(projectDir, dirname(f.specPath || f.planPath || f.tasksPath)),
+      score,
+      grade: featureGrade(score),
+      signals,
+      weakest,
+      fixHint: needsFix ? fixHintFor(weakest, signals[weakest], f) : null,
+    };
+  });
+
+  // Worst-first — act on the weakest feature. Name tie-break for determinism.
+  features.sort((a, b) => a.score - b.score || a.name.localeCompare(b.name));
+
+  const avgScore = Math.round(features.reduce((sum, f) => sum + f.score, 0) / features.length);
+  const summary = {
+    features: features.length,
+    avgScore,
+    worst: { name: features[0].name, score: features[0].score },
+  };
+
+  if (isJson) {
+    outputFeaturesJSON(features, summary);
+  } else {
+    outputFeaturesText(features, summary);
+  }
+}
+
+function pctOrNull(signal) {
+  return signal.applicable ? Math.round(signal.value * 100) : null;
+}
+
+function outputFeaturesJSON(features, summary) {
+  console.log(JSON.stringify({
+    features: features.map(f => ({
+      name: f.name,
+      dir: f.dir,
+      score: f.score,
+      grade: f.grade,
+      signals: {
+        reqCoverage: {
+          pct: pctOrNull(f.signals.reqCoverage),
+          covered: f.signals.reqCoverage.covered,
+          total: f.signals.reqCoverage.total,
+          uncovered: f.signals.reqCoverage.uncovered,
+        },
+        taskCompletion: {
+          pct: pctOrNull(f.signals.taskCompletion),
+          checked: f.signals.taskCompletion.checked,
+          total: f.signals.taskCompletion.total,
+        },
+        taskEvidence: {
+          pct: pctOrNull(f.signals.taskEvidence),
+          evidenced: f.signals.taskEvidence.evidenced,
+          considered: f.signals.taskEvidence.considered,
+        },
+        artifactCompleteness: {
+          pct: pctOrNull(f.signals.artifactCompleteness),
+          spec: f.signals.artifactCompleteness.spec,
+          plan: f.signals.artifactCompleteness.plan,
+          tasks: f.signals.artifactCompleteness.tasks,
+        },
+      },
+      weakest: f.weakest,
+      fixHint: f.fixHint,
+    })),
+    summary,
+    timestamp: new Date().toISOString(),
+  }, null, 2));
+}
+
+function outputFeaturesText(features, summary) {
+  console.log(`  ${c.bold}Feature Adherence${c.reset} ${c.dim}(worst first)${c.reset}\n`);
+
+  for (const f of features) {
+    const gradeColor = f.score >= 80 ? c.green : f.score >= 60 ? c.yellow : c.red;
+    console.log(`  📦 ${c.bold}${f.name}${c.reset} — ${gradeColor}${f.score}/100 (${f.grade})${c.reset} ${featureBar(f.score)}`);
+    console.log(`     ${c.dim}${f.dir}${c.reset}`);
+
+    const sig = f.signals;
+    const line = (label, weightPct, s, detail) => {
+      const pct = s.applicable ? `${Math.round(s.value * 100)}%`.padEnd(4) : 'n/a ';
+      const color = !s.applicable ? c.dim : s.value >= 0.8 ? c.green : s.value >= 0.5 ? c.yellow : c.red;
+      console.log(`     ${color}${pct}${c.reset} ${label.padEnd(22)} ${c.dim}${detail} · weight ${weightPct}%${c.reset}`);
+    };
+
+    line('Requirement coverage', 40, sig.reqCoverage,
+      sig.reqCoverage.applicable
+        ? `${sig.reqCoverage.covered}/${sig.reqCoverage.total} spec IDs referenced by tests`
+        : 'no FR-/SC- IDs in spec.md');
+    line('Task completion', 25, sig.taskCompletion,
+      sig.taskCompletion.applicable
+        ? `${sig.taskCompletion.checked}/${sig.taskCompletion.total} tasks checked`
+        : 'no tasks.md checklist');
+    line('Task evidence', 20, sig.taskEvidence,
+      sig.taskEvidence.applicable
+        ? `${sig.taskEvidence.evidenced}/${sig.taskEvidence.considered} checked tasks name existing files`
+        : 'no checked task names a file path');
+    line('Artifacts', 15, sig.artifactCompleteness,
+      `${[sig.artifactCompleteness.spec, sig.artifactCompleteness.plan, sig.artifactCompleteness.tasks].filter(Boolean).length}/3 ` +
+      `(spec ${sig.artifactCompleteness.spec ? '✓' : '✗'} · plan ${sig.artifactCompleteness.plan ? '✓' : '✗'} · tasks ${sig.artifactCompleteness.tasks ? '✓' : '✗'})`);
+
+    if (f.fixHint) {
+      console.log(`     ${c.yellow}⚠ Fix first:${c.reset} ${f.fixHint}`);
+    } else {
+      console.log(`     ${c.green}✓ No weak signal — all applicable signals at 100%${c.reset}`);
+    }
+    console.log('');
+  }
+
+  console.log(`  ${c.bold}─────────────────────────────────────${c.reset}`);
+  console.log(`  ${summary.features} feature(s) · avg ${summary.avgScore}/100 · worst: ${c.red}${summary.worst.name} (${summary.worst.score}/100)${c.reset}`);
+  console.log(`\n  ${c.dim}Signals are deterministic (checklist, ID-to-test references, file existence) — adherence of intent, not correctness.${c.reset}\n`);
+}
+
 function findRelatedTests(projectFiles, sourcePatterns) {
   // Find test files that might cover the source patterns
   const testFiles = projectFiles.filter(f => TEST_PATTERNS.some(p => p.test(f)));