docguard-cli 0.11.2 → 0.13.0

package/README.md

@@ -17,7 +17,7 @@
 - [What is DocGuard?](#what-is-docguard)
 - [Quick Start](#-quick-start)
 - [Spec Kit Integration](#-spec-kit-integration)
-- [Commands](#-commands)
+- [Usage](#usage)
 - [Validators](#-validators)
 - [Templates](#-templates)
 - [AI Agent Support](#-ai-agent-support)
@@ -343,7 +343,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 20 validators |
+| `/docguard.guard` | Run quality validation — check all 22 validators |
 | `/docguard.review` | Analyze doc quality and suggest improvements |
 | `/docguard.fix` | Generate targeted fix prompts for specific issues |
 | `/docguard.score` | Show CDD maturity score with category breakdown |
@@ -433,20 +433,42 @@ DocGuard runs its own `guard`, `score`, `diff`, `diagnose`, and `badge` commands
 
 ## ⚙️ CI/CD Integration
 
-### GitHub Actions
+> **Full recipes:** see [`docs-canonical/CI-RECIPES.md`](./docs-canonical/CI-RECIPES.md) for guard, auto-fix (commits mechanical fixes back to PRs), nightly sync, score-on-PR, and pre-commit configs.
+
+### GitHub Actions — Guard (most common)
 
 ```yaml
-name: DocGuard CDD Check
-on: [pull_request]
+name: DocGuard Guard
+on: [pull_request, push]
 jobs:
   docguard:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '20' }
-      - run: npx docguard-cli guard
-      - run: npx docguard-cli score --format json
+        with: { fetch-depth: 0 }
+      - uses: raccioly/docguard@v0.12.0
+        with:
+          command: guard
+```
+
+### GitHub Actions — Auto-Fix (commits mechanical fixes back)
+
+```yaml
+name: DocGuard Auto-Fix
+on: { pull_request: { types: [opened, synchronize, reopened] } }
+permissions: { contents: write, pull-requests: write }
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+      - uses: raccioly/docguard@v0.12.0
+        with: { command: fix, auto-commit: 'true', comment-on-pr: 'true' }
 ```
 
 ### Pre-commit Hook
@@ -455,14 +477,11 @@ jobs:
 npx docguard-cli hooks --type pre-commit
 ```
 
-### GitHub Marketplace
+### Workflow starters (copy directly)
 
-```yaml
-- uses: raccioly/docguard@v0.9.7
-  with:
-    command: guard
-    fail-on-warning: true
-```
+Two ready-to-use templates ship with the Spec Kit extension and as standalone files:
+- `extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml` — mandatory CI gate
+- `extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml` — PR auto-fix
 
 ---
 

package/cli/commands/fix.mjs

@@ -21,6 +21,7 @@ import { c } from '../shared.mjs';
 import { computeApiSurfaceDrift } from '../validators/api-surface.mjs';
 import { removeEndpoints, hasGeneratedMarker } from '../writers/api-reference.mjs';
 import { applyMechanicalFixes } from '../writers/mechanical.mjs';
+import { loadFixMemory } from '../writers/fix-memory.mjs';
 import { runGuardInternal } from './guard.mjs';
 
 const API_DOC = 'docs-canonical/API-REFERENCE.md';
@@ -281,6 +282,55 @@ export function applyAllMechanicalFixes(projectDir, config, { force = false } =
   return { applied, skipped, total: fixes.length };
 }
 
+/**
+ * M-2 — `docguard fix --history` shows the audit log of mechanical fixes
+ * that have been applied to this project. Reads `.docguard/fixed.json`
+ * and pretty-prints (or emits JSON when --format json).
+ */
+function runHistoryMode(projectDir, flags) {
+  const mem = loadFixMemory(projectDir);
+  const isJson = flags.format === 'json';
+
+  if (isJson) {
+    console.log(JSON.stringify(mem, null, 2));
+    return;
+  }
+
+  if (mem.entries.length === 0) {
+    console.log(`${c.bold}🗂  DocGuard Fix History${c.reset}`);
+    console.log(`${c.dim}   No fixes recorded yet. Run \`docguard fix --write\` to start the audit log.${c.reset}`);
+    return;
+  }
+
+  console.log(`${c.bold}🗂  DocGuard Fix History${c.reset} ${c.dim}(${mem.entries.length} entries, newest first)${c.reset}\n`);
+
+  // Group by date for readability
+  const byDate = new Map();
+  for (const e of mem.entries) {
+    const day = (e.appliedAt || '').slice(0, 10);
+    if (!byDate.has(day)) byDate.set(day, []);
+    byDate.get(day).push(e);
+  }
+
+  // Show the most recent N days (cap output at 20 entries)
+  let printed = 0;
+  for (const [day, dayEntries] of byDate) {
+    if (printed >= 20) break;
+    console.log(`  ${c.cyan}${day}${c.reset} ${c.dim}(${dayEntries.length} fix${dayEntries.length > 1 ? 'es' : ''})${c.reset}`);
+    for (const e of dayEntries.slice(0, 5)) {
+      if (printed >= 20) break;
+      const time = (e.appliedAt || '').slice(11, 16);
+      console.log(`     ${c.dim}${time}${c.reset} ${e.type} → ${c.cyan}${e.file}${c.reset} ${c.dim}${e.summary || ''}${c.reset}`);
+      printed++;
+    }
+    if (dayEntries.length > 5) console.log(`     ${c.dim}... ${dayEntries.length - 5} more on this day${c.reset}`);
+  }
+
+  if (mem.entries.length > 20) {
+    console.log(`\n  ${c.dim}... ${mem.entries.length - 20} older entries. Use ${c.cyan}--format json${c.dim} for the full log.${c.reset}`);
+  }
+}
+
 function runWriteMode(projectDir, config, flags) {
   const isJson = flags.format === 'json';
   const { applied, skipped, total } = applyAllMechanicalFixes(projectDir, config, { force: flags.force });
@@ -321,6 +371,11 @@ export function runFix(projectDir, config, flags) {
   const autoFix = flags.auto || false;
   const specificDoc = flags.doc || null;
 
+  // M-2: --history shows the audit trail of past mechanical fixes.
+  if (flags.history) {
+    return runHistoryMode(projectDir, flags);
+  }
+
   // --write: deterministically APPLY mechanical fixes (no LLM). Currently:
   // remove API-REFERENCE.md endpoints the OpenAPI spec confirms no longer exist.
   if (flags.write) {

package/cli/commands/guard.mjs

@@ -7,8 +7,10 @@
  *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
  */
 
-import { c } from '../shared.mjs';
+import { c, resolveSeverity } from '../shared.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
+import { checkUpgradeStatus } from './upgrade.mjs';
+import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
 import { validateStructure, validateDocSections } from '../validators/structure.mjs';
 import { validateDrift } from '../validators/drift.mjs';
 import { validateChangelog } from '../validators/changelog.mjs';
@@ -25,6 +27,8 @@ import { validateMetadataSync } from '../validators/metadata-sync.mjs';
 import { validateMetricsConsistency } from '../validators/metrics-consistency.mjs';
 import { validateDocsCoverage } from '../validators/docs-coverage.mjs';
 import { validateDocQuality } from '../validators/doc-quality.mjs';
+import { validateCrossReferences } from '../validators/cross-reference.mjs';
+import { validateGeneratedStaleness } from '../validators/generated-staleness.mjs';
 import { validateTodoTracking } from '../validators/todo-tracking.mjs';
 import { validateSchemaSync } from '../validators/schema-sync.mjs';
 import { validateSpecKitIntegration } from '../scanners/speckit.mjs';
@@ -100,6 +104,8 @@ export function runGuardInternal(projectDir, config) {
     { key: 'todoTracking', name: 'TODO-Tracking', fn: () => validateTodoTracking(projectDir, config) },
     { key: 'schemaSync', name: 'Schema-Sync', fn: () => validateSchemaSync(projectDir, config) },
     { key: 'specKit', name: 'Spec-Kit', fn: () => validateSpecKitIntegration(projectDir, config) },
+    { key: 'crossReference', name: 'Cross-Reference', fn: () => validateCrossReferences(projectDir, config) },
+    { key: 'generatedStaleness', name: 'Generated-Staleness', fn: () => validateGeneratedStaleness(projectDir, config) },
     // Metrics-Consistency runs post-loop (needs guard results)
   ];
 
@@ -133,6 +139,25 @@ export function runGuardInternal(projectDir, config) {
   const totalPassed = activeResults.reduce((sum, r) => sum + r.passed, 0);
   const totalChecks = activeResults.reduce((sum, r) => sum + r.total, 0);
 
+  // Per-validator severity overrides (v0.5 schema). Affects EXIT-CODE only,
+  // not display. Annotate each validator with its resolved severity and roll
+  // up effective error/warning counts:
+  //   - high  → validator's warnings get promoted to "effective errors"
+  //   - low   → validator's warnings are demoted (ignored for exit code)
+  //   - medium (default) → warnings stay as-is
+  for (const v of activeResults) {
+    v.severity = resolveSeverity(config, v.key);
+  }
+  let effectiveErrors = totalErrors;
+  let effectiveWarnings = 0;
+  for (const v of activeResults) {
+    const wCount = v.warnings.length;
+    if (wCount === 0) continue;
+    if (v.severity === 'high') effectiveErrors += wCount;
+    else if (v.severity === 'low') { /* ignored for exit */ }
+    else effectiveWarnings += wCount;
+  }
+
   const overallStatus = totalErrors > 0 ? 'FAIL' : totalWarnings > 0 ? 'WARN' : 'PASS';
 
   return {
@@ -143,22 +168,80 @@ export function runGuardInternal(projectDir, config) {
     total: totalChecks,
     errors: totalErrors,
     warnings: totalWarnings,
+    // v0.5: severity-aware counts for exit-code logic. The display still uses
+    // the raw counts above so users see every warning, but CI only fails on
+    // things they've marked as high-severity.
+    effectiveErrors,
+    effectiveWarnings,
     validators: results,
     timestamp: new Date().toISOString(),
   };
 }
 
+/**
+ * The "pre-commit lite" validator set — fast checks suitable for running
+ * on every commit/save. Tuned for <2s wall-clock on average repos.
+ *
+ * The list is intentionally short: validators that catch >80% of the
+ * common doc drift that developers introduce mid-feature (route added but
+ * not documented, env var renamed but not updated in ENVIRONMENT.md,
+ * endpoint deleted but still in API-REFERENCE.md). Heavy validators —
+ * Freshness (git log), Traceability (REQ scan), Doc-Quality (prose lint) —
+ * stay off for speed.
+ */
+export const CHANGED_ONLY_VALIDATORS = ['docsSync', 'environment', 'apiSurface'];
+
+/**
+ * Build a validators map that enables only the pre-commit-lite set.
+ * Used by `docguard guard --changed-only`.
+ */
+function liteValidatorsConfig() {
+  const all = [
+    'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
+    'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
+    'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
+    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness', 'metricsConsistency',
+  ];
+  const out = {};
+  for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);
+  return out;
+}
+
 /**
  * Public guard — prints results and exits.
  */
 export function runGuard(projectDir, config, flags) {
+  // --changed-only: pre-commit lite mode. Overrides the validator set to a
+  // fast subset (Docs-Sync, Environment, API-Surface). Designed for husky/
+  // lefthook hooks; expects to finish in under 2 seconds.
+  if (flags.changedOnly) {
+    // Compute the set of changed files since the given ref (default HEAD~1 —
+    // the pre-commit common case: "files changed in this commit vs the last
+    // committed state"). Validators that opt into `config.changedFiles` can
+    // scope to this list; others run normally over the whole tree.
+    const ref = flags.since || 'HEAD~1';
+    const changed = isGitRepo(projectDir) ? changedFilesSince(projectDir, ref) : [];
+    config = {
+      ...config,
+      validators: liteValidatorsConfig(),
+      changedFiles: changed,
+      changedSinceRef: ref,
+    };
+    const label = changed.length > 0
+      ? `${changed.length} file(s) changed since ${ref}`
+      : `no changes since ${ref} — running all ${CHANGED_ONLY_VALIDATORS.length} lite validators on full tree`;
+    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(${label})${c.reset}\n`);
+  }
+
   const data = runGuardInternal(projectDir, config);
 
   // ── JSON output ──
   if (flags.format === 'json') {
     console.log(JSON.stringify(data, null, 2));
-    if (data.errors > 0) process.exit(1);
-    if (data.warnings > 0) process.exit(2);
+    // Use severity-aware effective counts for exit code; raw counts stay in the JSON
+    // for display tools that want to show the full picture.
+    if (data.effectiveErrors > 0) process.exit(1);
+    if (data.effectiveWarnings > 0) process.exit(2);
     process.exit(0);
   }
 
@@ -243,14 +326,55 @@ export function runGuard(projectDir, config, flags) {
   const badgeUrl = `https://img.shields.io/badge/CDD_Guard-${data.passed}%2F${data.total}_passed-${bColor}`;
   console.log(`\n  ${c.dim}📎 Badge: ![CDD Guard](${badgeUrl})${c.reset}`);
 
+  // Schema upgrade nudge — fires when the project's .docguard.json schema is
+  // behind the CLI's CURRENT_SCHEMA_VERSION. Cheap, file-local check; no
+  // network access. Suppressed in JSON output to keep machine consumers clean.
+  if (!flags || flags.format !== 'json') {
+    const upgradeHint = checkUpgradeStatus(projectDir);
+    if (upgradeHint) {
+      console.log(`\n  ${c.yellow}↑ ${upgradeHint}${c.reset}`);
+    }
+
+    // K-6 / S-2: sweep-needed nudge. Aggregates freshness warnings — if 2+
+    // canonical docs are stale (matching the "X code commits since last doc
+    // update" pattern), suggest a single `docguard sync --write` pass that
+    // refreshes every code-truth section in one shot. Individual freshness
+    // warnings already named the docs; this nudge just turns "5 warnings"
+    // into one actionable recommendation.
+    const freshness = data.validators.find(v => v.key === 'freshness');
+    if (freshness && freshness.warnings) {
+      const staleDocs = freshness.warnings.filter(w => /\d+ code commits since/.test(w));
+      if (staleDocs.length >= 2) {
+        console.log(`\n  ${c.yellow}↻ ${staleDocs.length} docs are stale (10+ commits since last update). Run ${c.cyan}docguard sync --write${c.yellow} to refresh code-truth sections in one pass.${c.reset}`);
+      }
+    }
+  }
+
   // Spec-kit reminder — persistent nudge if not initialized
   if (!isSpecKitInitialized(projectDir)) {
     console.log(`\n  ${c.yellow}💡${c.reset} ${c.dim}Enhance DocGuard with Spec Kit: ${c.cyan}uv tool install specify-cli --from git+https://github.com/github/spec-kit.git${c.reset}`);
   }
 
+  // When severity overrides demoted warnings to "low" (or promoted them to
+  // "high"), show a one-line note so the user knows the exit code may not
+  // match what they expected from reading the warning count.
+  const severityShifted =
+    data.effectiveErrors !== data.errors || data.effectiveWarnings !== data.warnings;
+  if (severityShifted) {
+    const upgraded = data.effectiveErrors - data.errors;
+    const ignored = data.warnings - data.effectiveWarnings - upgraded;
+    const parts = [];
+    if (upgraded > 0) parts.push(`${upgraded} warning(s) escalated to fail (severity=high)`);
+    if (ignored > 0) parts.push(`${ignored} warning(s) ignored for exit code (severity=low)`);
+    if (parts.length > 0) {
+      console.log(`\n  ${c.dim}Severity override: ${parts.join('; ')}.${c.reset}`);
+    }
+  }
+
   console.log('');
 
-  if (data.errors > 0) process.exit(1);
-  if (data.warnings > 0) process.exit(2);
+  // v0.5: severity-aware exit codes (see runGuardInternal for the rollup).
+  if (data.effectiveErrors > 0) process.exit(1);
+  if (data.effectiveWarnings > 0) process.exit(2);
   process.exit(0);
 }

package/cli/commands/init.mjs

@@ -168,7 +168,7 @@ export async function runInit(projectDir, config, flags) {
 
     const defaultConfig = {
       projectName: config.projectName,
-      version: '0.4',
+      version: '0.5',
       profile: profileName,
       projectType: detectedType,
       projectTypeConfig: ptc,
@@ -186,6 +186,13 @@ export async function runInit(projectDir, config, flags) {
         environment: true,
         freshness: true,
       },
+      // Per-validator severity overrides (v0.5+).
+      //   'high':   warnings from this validator fail CI (exit 1)
+      //   'medium': default — warnings exit 2 (informational)
+      //   'low':    warnings ignored for exit code (exit 0)
+      // Empty by default — every validator uses 'medium'. Add entries to dial
+      // strictness up (CI-critical checks) or down (experimental validators).
+      severity: {},
     };
 
     writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n', 'utf-8');
@@ -196,6 +203,50 @@ export async function runInit(projectDir, config, flags) {
     console.log(`  ${c.yellow}⏭️${c.reset}  .docguard.json ${c.dim}(already exists)${c.reset}`);
   }
 
+  // ── Create .docguardignore ────────────────────────────────────────────
+  // Starter ignore file with gitignore-style syntax. Patterns here are merged
+  // into config.ignore at load time so every validator honors them.
+  const ignorePath = resolve(projectDir, '.docguardignore');
+  if (!existsSync(ignorePath)) {
+    const ignoreContent = `# .docguardignore — paths to exclude from DocGuard validation.
+# Gitignore-style syntax: one pattern per line, # for comments.
+# Merged into config.ignore (in .docguard.json) at runtime.
+#
+# Common examples:
+#   build/                   # exclude a directory
+#   **/__generated__/**      # exclude anything in any __generated__ dir
+#   vendor/legacy.ts         # exclude a single file
+#   **/*.snap                # exclude all files matching a glob
+#
+# Build outputs, vendored libs, generated code are good candidates here.
+
+# Vendored / generated code that's not yours to document
+**/__generated__/**
+**/generated/**
+**/*.generated.*
+
+# Migrations and lock files
+**/migrations/**
+**/*.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+Cargo.lock
+poetry.lock
+
+# Common build artifacts (defaults also cover these, but listing here is clearer)
+# dist/
+# build/
+# coverage/
+`;
+    writeFileSync(ignorePath, ignoreContent, 'utf-8');
+    created.push('.docguardignore');
+    console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}.docguardignore${c.reset} ${c.dim}(gitignore-style exclusions)${c.reset}`);
+  } else {
+    skipped.push('.docguardignore');
+    console.log(`  ${c.yellow}⏭️${c.reset}  .docguardignore ${c.dim}(already exists)${c.reset}`);
+  }
+
   // ── Spec-Kit Integration (Extension-First) ────────────────────────────
   // Delegate LLM/IDE detection and spec-kit skill install to `specify init`
   const specKitAvailable = isSpecKitAvailable();

package/cli/commands/sync.mjs

@@ -34,6 +34,48 @@ function gitChangedFiles(projectDir, since) {
   return [...new Set([...committed, ...working])];
 }
 
+/**
+ * L-1: Map each `source: 'code'` section ID to a predicate that returns true
+ * when one of the changed file paths could plausibly affect it. Conservative
+ * by design — when in doubt we run the section's sync, never skip it.
+ *
+ * The predicates are matched against project-relative POSIX paths (the form
+ * `git diff --name-only` returns).
+ */
+const SECTION_FILE_MATCHERS = {
+  'tech-stack':        (p) => /package\.json$|pyproject\.toml$|Cargo\.toml$|go\.mod$|pom\.xml$|Gemfile$/.test(p),
+  'frontend-modules':  (p) => /(^|\/)(src\/)?(stores|hooks|contexts|features)\//.test(p),
+  'endpoints-table':   (p) => /(^|\/)(routes|controllers|handlers|app\/api)\//.test(p)
+                              || /\.(yaml|yml|json)$/i.test(p) && /openapi|swagger/i.test(p),
+  'entities-table':    (p) => /(^|\/)(models|schemas|entities)\//.test(p)
+                              || /\.prisma$/.test(p),
+  'relationships':     (p) => /(^|\/)(models|schemas|entities)\//.test(p)
+                              || /\.prisma$/.test(p),
+  'screens-table':     (p) => /(^|\/)(screens|pages|app)\//.test(p)
+                              || /\.(tsx|jsx)$/.test(p),
+  'flows':             (p) => /(^|\/)(screens|pages|app|routes)\//.test(p),
+  'integrations-table':(p) => /package\.json$|pyproject\.toml$|requirements.*\.txt$|Cargo\.toml$/.test(p),
+  'features-table':    (p) => /(^|\/)(features|domains)\//.test(p),
+  'features':          (p) => /(^|\/)(features|domains)\//.test(p),
+  'env-vars-table':    (p) => /\.env(\..+)?$|(^|\/)config\//.test(p)
+                              || /\.(ts|tsx|js|jsx|mjs|py|go|rs|java|kt|rb)$/.test(p), // any code may use env
+  'setup':             (p) => /\.env(\..+)?$|(^|\/)config\//.test(p),
+};
+
+/**
+ * Decide whether a given code-truth section should be re-synced based on the
+ * set of changed files. Returns true when:
+ *   - changedFiles is null/empty (no scope info → sync everything), OR
+ *   - any changed file matches the section's known source patterns, OR
+ *   - the section has no matcher registered (unknown → conservative: sync)
+ */
+function sectionTouchedByChanges(sectionId, changedFiles) {
+  if (!changedFiles || changedFiles.length === 0) return true;
+  const matcher = SECTION_FILE_MATCHERS[sectionId];
+  if (!matcher) return true; // unknown section → don't accidentally skip it
+  return changedFiles.some(matcher);
+}
+
 export function runSync(projectDir, config, flags) {
   const plan = buildMemoryPlan(projectDir, config);
   const apply = !!flags.write;
@@ -63,6 +105,14 @@ export function runSync(projectDir, config, flags) {
       const existing = getSection(content, sec.id);
       if (!existing) continue; // sync refreshes sections that already exist
       if (existing.body.trim() === String(sec.body).trim()) continue; // already current
+      // L-1: when --since is provided, only update sections whose underlying
+      // source files appear in the changed set. Avoids spurious updates when
+      // the section's CONTENT would naturally drift (e.g. timestamp-driven
+      // counters) but no real source file changed.
+      if (changed !== null && !sectionTouchedByChanges(sec.id, changed)) {
+        skipped.push({ doc: doc.path, reason: `section ${sec.id} unchanged since ${flags.since} (no underlying source files in diff)` });
+        continue;
+      }
       codeSectionChanged = true;
       updates.push({ doc: doc.path, section: sec.id, status: apply ? 'updated' : 'stale' });
       if (apply) { content = replaceSection(content, sec.id, sec.body).content; docChanged = true; }

package/cli/commands/trace.mjs

@@ -84,7 +84,112 @@ const TRACE_MAP = {
   },
 };
 
+/**
+ * L-2 / S-3 — Reverse trace: given a code file, find which canonical doc
+ * sections mention it. Mirror of the forward trace (doc → code).
+ *
+ * Match strategies (each yields a hit):
+ *   1. Direct path match: full project-relative path appears in doc text.
+ *   2. Basename match: e.g. `users.ts` appears (covers cases where the doc
+ *      refers to the file by name without the full path).
+ *   3. Module name match: file stem (e.g. `users`) appears as a fenced
+ *      `code` reference. Tighter than 2 — avoids matching common nouns.
+ *
+ * Output: one line per (doc, match-line) pair, with the surrounding context.
+ */
+export function runTraceReverse(projectDir, config, flags) {
+  const target = flags.args && flags.args[0];
+  if (!target) {
+    console.error(`${c.red}Error: trace --reverse requires a target path${c.reset}`);
+    console.log(`Usage: ${c.cyan}docguard trace --reverse <code-path>${c.reset}`);
+    console.log(`Example: ${c.cyan}docguard trace --reverse src/routes/users.ts${c.reset}`);
+    process.exit(1);
+  }
+
+  // Suppress chrome in JSON mode so stdout stays parseable.
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🔄 DocGuard Trace (reverse) — ${target}${c.reset}`);
+    console.log(`${c.dim}   Finding canonical doc sections that reference this file...${c.reset}\n`);
+  }
+
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  if (!existsSync(docsDir)) {
+    if (isJson) {
+      console.log(JSON.stringify({ target, matches: [], error: 'no docs-canonical/ directory' }, null, 2));
+    } else {
+      console.log(`  ${c.yellow}No docs-canonical/ directory found.${c.reset}`);
+    }
+    return;
+  }
+
+  // Normalize the target path: strip leading ./
+  const normalized = target.replace(/^\.\//, '');
+  const base = basename(normalized);
+  const stem = base.replace(/\.[^.]+$/, '');
+
+  const matches = []; // { doc, line, content, kind }
+  for (const f of readdirSync(docsDir)) {
+    if (!f.endsWith('.md')) continue;
+    const docPath = resolve(docsDir, f);
+    let content;
+    try { content = readFileSync(docPath, 'utf-8'); } catch { continue; }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      let kind = null;
+      if (line.includes(normalized)) kind = 'path';
+      else if (line.includes(base)) kind = 'basename';
+      else if (new RegExp(`\`${escapeRegex(stem)}\``).test(line)) kind = 'module';
+      if (kind) {
+        matches.push({ doc: f, line: i + 1, content: line.trim(), kind });
+      }
+    }
+  }
+
+  if (flags.format === 'json') {
+    console.log(JSON.stringify({
+      target: normalized,
+      matches,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  if (matches.length === 0) {
+    console.log(`  ${c.yellow}⚠️  No canonical doc references "${normalized}"${c.reset}`);
+    console.log(`  ${c.dim}Consider documenting this file in docs-canonical/ARCHITECTURE.md or DATA-MODEL.md${c.reset}`);
+    return;
+  }
+
+  // Group by doc for readable output
+  const byDoc = new Map();
+  for (const m of matches) {
+    if (!byDoc.has(m.doc)) byDoc.set(m.doc, []);
+    byDoc.get(m.doc).push(m);
+  }
+
+  console.log(`  ${c.green}✅ ${matches.length} reference(s) across ${byDoc.size} doc(s):${c.reset}\n`);
+  for (const [doc, hits] of byDoc) {
+    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${hits.length} hit${hits.length > 1 ? 's' : ''})${c.reset}`);
+    for (const h of hits.slice(0, 5)) {
+      const trimmed = h.content.length > 80 ? h.content.slice(0, 77) + '…' : h.content;
+      console.log(`     ${c.dim}L${h.line} [${h.kind}]${c.reset} ${trimmed}`);
+    }
+    if (hits.length > 5) console.log(`     ${c.dim}... ${hits.length - 5} more${c.reset}`);
+  }
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 export function runTrace(projectDir, config, flags) {
+  // L-2: dispatch to reverse mode when --reverse is set.
+  if (flags.reverse) {
+    return runTraceReverse(projectDir, config, flags);
+  }
+
   console.log(`${c.bold}🔗 DocGuard Trace — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   console.log(`${c.dim}   Generating requirements traceability matrix...${c.reset}\n`);