docguard-cli 0.12.0__tar.gz → 0.13.1__tar.gz

{docguard_cli-0.12.0/extensions/spec-kit-docguard → docguard_cli-0.13.1/.agent}/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.12.0/extensions/spec-kit-docguard → docguard_cli-0.13.1/.agent}/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # DocGuard Guard Skill
 
@@ -139,7 +139,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All 21 validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All 22 validators passed. Project is CDD-compliant. Ready to commit."
 - **If only MEDIUM/LOW warnings**: "Non-blocking warnings found. Safe to commit, but consider running `/docguard.fix` for automated remediation."
 - **If HIGH or CRITICAL failures**: "Blocking issues found. Fix these before committing. Suggest running `/docguard.fix --doc [most impactful doc]` next."
 

{docguard_cli-0.12.0/extensions/spec-kit-docguard → docguard_cli-0.13.1/.agent}/skills/docguard-review/SKILL.md

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/.agent/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.12.0 -->
+<!-- docguard:version: 0.13.1 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/.agent/skills/docguard-sync/SKILL.md

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.12.0
+  version: 0.13.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/AGENTS.md

@@ -41,7 +41,7 @@
 | Command | Purpose |
 |---------|---------|
 | `diagnose` | **Primary** — identify issues + generate AI fix prompts |
-| `guard` | Validate project (CI gate) — 21 validators |
+| `guard` | Validate project (CI gate) — 22 validators |
 | `generate` | Reverse-engineer docs from code |
 | `fix --doc <name>` | AI prompt for specific document |
 | `score` | CDD maturity score (0-100) |

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/CHANGELOG.md

@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-05-26
+
+Patch + small feature release responding to the wu-whatsappinbox v0.12/v0.13
+feedback. Fixes 2 bugs (B-5, B-6), ships 3 new features (S-7, S-11, S-12),
+and adds a cross-cutting "no validator throws" safety net. **22 validators,
+448 tests (was 434, +14 new).** New `docguard impact` command.
+
+### Fixed
+
+- **B-5: Freshness validator crashed with `getLastCommitDate is not defined`.** A wu-whatsappinbox install of v0.13.0 produced this ReferenceError despite all the imports being correct in source — we couldn't reproduce locally, but the user's report was clear. Fix: defensive dynamic import in `freshness.mjs` that falls back to the pre-v0.13 inline implementation if `../shared-git.mjs` ever fails to load. Worst-case behavior is now "rename detection silently disabled" instead of "validator crashes with useless message". Also added an inline fallback for the same defensive layering. Reported by wu-whatsappinbox.
+- **B-6: Cross-Reference didn't URL-decode link target paths.** A markdown link like `[name](../WU%20Documentation/foo.md)` (where the directory has a space) was looked up with `existsSync('../WU%20Documentation/foo.md')` literally — the filesystem stores the decoded form. Now: `resolveTarget` tries BOTH the literal path (for paths that legitimately contain `%`) and the URL-decoded form. **Effect on wu-whatsappinbox: Cross-Reference went from 28/28 to 101/101 checks — 73 previously-broken refs now resolve correctly.** Reported by wu-whatsappinbox.
+- **Cross-cutting safety net**: new `tests/guard-no-throw.test.mjs` runs guard against a fixture repo and asserts no validator leaks a ReferenceError / TypeError / "is not defined" / "is not a function" / "Cannot read properties of undefined" pattern into user-facing output. Found a *second* lurking bug while writing the test: Structure validator threw `Cannot read properties of undefined (reading 'some')` when `config.requiredFiles.agentFile` was missing — fixed with defensive array-or-string coercion + skip-when-missing for `changelog` too. This safety net runs in CI, catching the entire class of developer-error-leaks before release.
+
+### Added
+
+- **S-12: Cross-Reference suggests the closest anchor on near-miss.** When the validator flags a broken anchor, it now appends `(did you mean #athena-setup-aws-only?)` when a heading in the target doc is a close match. Two-pass matcher: (1) substring containment with ≥4-char minimum and ≥50% overlap to avoid spurious matches, (2) Levenshtein edit distance within a `max(3, len/5)` budget. **Three of the five wu user-fixes in v0.12.0 were "heading renamed, link not updated" — now deterministic-fixable from the warning text.** Reported by wu-whatsappinbox.
+- **S-7: Draft-staleness check in Generated-Doc Staleness validator.** A `docguard:generated` doc with `status: draft` (either YAML frontmatter or `<!-- status: draft -->` inline marker) that hasn't been modified in `> draftStalenessDays` days (default 14) now warns. Catches forgotten skeletons that stall before the AI fills them in. Threshold configurable via `config.draftStalenessDays`. Validator returns N/A only when there's NOTHING to check (no source=code sections AND no draft docs). Reported by wu-whatsappinbox.
+- **S-11: New `docguard impact` command.** After a commit (or before a PR), runs `git diff --name-only --since=<ref>` and shows which canonical doc sections reference any of the changed code files. Three match strategies (direct path / basename / backticked module name — same as L-2 trace --reverse). Highlights orphaned files (code that changed but no doc references it) so reviewers know what's undocumented. JSON mode emits `{ since, changedFiles, ignoredFiles, affectedDocs }` for CI bots. Designed as a post-commit hook companion to K-1's auto-fix Action. Reported by wu-whatsappinbox.
+
+### Internal
+
+- **+3 new test files**: `tests/guard-no-throw.test.mjs` (2 — cross-cutting safety), `tests/impact.test.mjs` (5 — S-11), plus 5 new test cases in `cross-reference.test.mjs` (S-12 + B-6) and `generated-staleness.test.mjs` (S-7). **Total: 434 → 448 tests (+14 new).**
+- **New module**: `cli/commands/impact.mjs` (~140 lines).
+- **Hardened**: `cli/validators/freshness.mjs` (defensive shared-git import), `cli/validators/structure.mjs` (defensive config-shape handling), `cli/validators/cross-reference.mjs` (URL-decode + anchor suggestion).
+- **Dry-run on wu-whatsappinbox before push** (read-only): 670/674 PASS in 1.8s with all 22 validators. Cross-Reference jumped from 28/28 to **101/101 checks** — B-6 fix unlocked 73 previously-broken refs.
+- No new NPM deps.
+
+### Note on wu's v0.12 feedback
+
+Several "still open" suggestions from the wu-whatsappinbox v0.12 feedback were already shipped:
+
+- **S-2 (sweep-needed nudge)** → shipped in v0.12.0 as K-6.
+- **S-3 (trace --reverse)** → shipped in v0.13.0 as L-2.
+- **S-4 (`git log --follow`)** → shipped in v0.13.0 as L-3.
+- **S-5 (.docguardignore at init)** → shipped in v0.12.0 as K-3.
+- **S-6 (per-validator severity)** → shipped in v0.12.0 as K-4.
+- **S-9 (pre-commit lite)** → shipped in v0.12.0 as K-5.
+- **S-10 (`.docguard/fixed.json`)** → shipped in v0.13.0 as M-2.
+
+Upgrade with `docguard upgrade --apply` (or `npm i -g docguard-cli@latest`) to get all of these. **The wu report header said v0.12.0 but the B-5 error pattern indicates an in-flight v0.13.0 install** — either way, this patch makes both versions resilient to the regression.
+
+## [0.13.0] - 2026-05-26
+
+Feature release — full backlog cleanup. **Phase L** (sync intelligence: 3 features), **Phase M** (bigger validators: 2 features), **Phase N** (polish: 2 fixes), and a new `shared-git.mjs` module that gives every git-touching validator rename-aware history. **22 validators total** (was 21). 434 tests, +34 from v0.12.
+
+### Added
+
+- **L-1 / S-1: `sync --since <ref>` surgical refresh.** `sync` now uses the git diff against the given ref to decide which code-truth doc sections actually need refreshing. Sections whose underlying source files weren't in the diff are explicitly skipped (with a `skipped` entry naming the section). When the diff contains no code files at all (e.g. PRs that touch only markdown), sync is a fast no-op. Saves wall-clock time on large monorepos.
+- **L-2 / S-3: `trace --reverse <code-path>`.** Mirror of the forward trace — given a code file path, finds every canonical doc that references it. Three match strategies (direct path, basename, backticked module name) with a per-doc summary in text mode or full match list in JSON mode. Surfaces "is this file documented anywhere?" in one command.
+- **L-3 / S-4: Rename detection via `git log --follow`.** New `cli/shared-git.mjs` module centralises every git-log call. All file-scoped queries now pass `--follow` so a `git mv` no longer resets the file's history. Freshness, Test-Spec, Traceability — anything that asks git "when was this file last touched?" — now answers correctly across renames.
+- **M-1 / S-7: Generated-Doc Staleness validator** (22nd validator). New validator re-runs the memory-plan scanner and compares each `source=code` section's expected body against on-disk content. Flags sections where the doc and the scanner disagree — i.e. either code changed without `sync --write` running, or someone hand-edited a machine-owned section. Warning includes a "first drift at line N" hint that names the diff site.
+- **M-2 / S-10: `.docguard/fixed.json` fix-history audit log.** Every mechanical fix `fix --write` applies is appended to a small JSON log under `.docguard/`. Entries are fingerprinted by `type+file+summary` and deduped (re-applying the same fix updates the timestamp instead of growing the file). Rolls over at 500 entries. New `docguard fix --history` command pretty-prints the log grouped by day. Also recorded: `appliedBy` (so K-1's `docguard-bot` auto-commits are distinguishable from human runs).
+- **N-1: Per-file scoping of `--changed-only`.** The `--changed-only` lite mode now computes the actually-changed files (`git diff --name-only HEAD~1 HEAD`, configurable with `--since`) and passes them as `config.changedFiles` to validators that opt in. Docs-Sync is the first opt-in: routes and services outside the changed set are skipped entirely. On wu-whatsappinbox the Docs-Sync check count went from 101 → 21 in `--changed-only` mode.
+- **N-2: 4 broken README anchors fixed** (caught by K-7's Cross-Reference validator). `[Commands](#-commands)` → `[Usage](#usage)`. `CONTRIBUTING.md` added to the validator's standard-docs lookup list (along with CODE_OF_CONDUCT.md, SECURITY.md, PHILOSOPHY.md, STANDARD.md, COMPARISONS.md) so cross-doc refs to those resolve.
+
+### Changed
+
+- **22 validators total** (was 21). Auto-fix bumped 6 doc references from "21 validators" → "22 validators" during the version bump.
+- **Trace command** (existing) now honors `--reverse` to switch to the new reverse mode; the forward mode is unchanged.
+- **`docguard guard` JSON output** for `--format json` no longer prints the banner or `ensureSkills` line — same headless fix as v0.12, extended to `trace --reverse --format json` and other JSON-mode commands.
+
+### Internal
+
+- **6 new test files**: `tests/shared-git.test.mjs` (11), `tests/sync-since.test.mjs` (3), `tests/trace-reverse.test.mjs` (5), `tests/generated-staleness.test.mjs` (4), `tests/fix-memory.test.mjs` (11), plus updates to `tests/changed-only.test.mjs`. **Total: 434 tests passing (was 400, +34 new).**
+- **New modules**: `cli/shared-git.mjs` (centralized git plumbing with --follow), `cli/validators/generated-staleness.mjs` (M-1), `cli/writers/fix-memory.mjs` (M-2). New helpers exported from sync.mjs: section→file matcher table for surgical refresh.
+- **Action / CLI dual-fix from v0.12** is now coordinated: K-1's auto-fix Action records to `.docguard/fixed.json` via `appliedBy: 'docguard-bot'`, giving teams a permanent record of which fixes the bot applied without diving into git history.
+- **Dry-run on wu-whatsappinbox before push** (read-only): 670/674 PASS in 1.82s with all 22 validators. 4 warnings are stale "21 validators" references in wu's local docguard skill files — those auto-fix on the next `fix --write`.
+- Bumped extension files via auto-fix (6 files: extension.yml + 5 SKILL.md).
+- No new NPM dependencies. Still zero deps.
+
+### Out of scope (deferred to v0.14)
+
+- **Fix-history suppression**: M-2 currently records but doesn't suppress. v0.14 will let `fix --write` skip fixes that were applied + reverted (avoiding ping-pong loops).
+- **More validators opt-into `config.changedFiles`**: N-1 only wires Docs-Sync. Environment and API-Surface could also benefit from path-level scoping.
+- **`generate-staleness` per-section auto-fix**: M-1 only warns; a future enhancement could emit structured fixes that `sync --write` consumes.
+- **`docguard upgrade --apply` for cross-machine teams**: currently in-place; could grow a "team-wide" mode that opens a PR.
+
 ## [0.12.0] - 2026-05-26
 
 Feature release — Phase K (7 features). Schema bump to **0.5**. Adds the

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.12.0
+Version: 0.13.1
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
 - [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)
@@ -367,7 +367,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 21 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 |

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/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 21 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 |

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/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) {

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/cli/commands/guard.mjs

@@ -10,6 +10,7 @@
 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';
@@ -27,6 +28,7 @@ import { validateMetricsConsistency } from '../validators/metrics-consistency.mj
 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';
@@ -103,6 +105,7 @@ export function runGuardInternal(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)
   ];
 
@@ -197,7 +200,7 @@ function liteValidatorsConfig() {
     'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
     'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
     'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
-    'schemaSync', 'specKit', 'crossReference', 'metricsConsistency',
+    'schemaSync', 'specKit', 'crossReference', 'generatedStaleness', 'metricsConsistency',
   ];
   const out = {};
   for (const k of all) out[k] = CHANGED_ONLY_VALIDATORS.includes(k);
@@ -212,8 +215,22 @@ export function runGuard(projectDir, config, flags) {
   // fast subset (Docs-Sync, Environment, API-Surface). Designed for husky/
   // lefthook hooks; expects to finish in under 2 seconds.
   if (flags.changedOnly) {
-    config = { ...config, validators: liteValidatorsConfig() };
-    console.log(`${c.cyan}⚡ docguard guard --changed-only${c.reset} ${c.dim}(running ${CHANGED_ONLY_VALIDATORS.length} fast validators only — pre-commit lite mode)${c.reset}\n`);
+    // 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);

docguard_cli-0.13.1/cli/commands/impact.mjs

@@ -0,0 +1,169 @@
+/**
+ * Impact Command — S-11
+ *
+ * After a commit (or before opening a PR), shows which canonical doc
+ * sections reference any file that changed since `--since` (default HEAD~1).
+ * Combines the L-2 reverse-trace logic with the changed-files diff so you
+ * get "you should re-read these doc sections" in one command.
+ *
+ * Use cases:
+ *   - Post-commit hook: `docguard impact --since HEAD~1` runs after each
+ *     commit and reminds the developer which docs to update.
+ *   - PR prep: `docguard impact --since main` shows the doc surface area
+ *     touched by the whole branch.
+ *
+ * JSON mode emits a structured `{ changedFiles, affectedDocs }` payload
+ * for CI integrations and PR-comment bots.
+ *
+ * @req SC-S11-001 — impact reports per-file → doc mappings
+ * @req SC-S11-002 — files with no doc references are listed as "no impact"
+ * @req SC-S11-003 — --format json emits parseable structured output
+ * @req SC-S11-004 — non-code files (.md, .json, etc.) are skipped from impact analysis
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+import { c } from '../shared.mjs';
+import { changedFilesSince, isGitRepo } from '../shared-git.mjs';
+
+/**
+ * File extensions we consider "code" for the purposes of impact analysis.
+ * Match the set used by other validators (Docs-Sync, Freshness).
+ */
+const CODE_EXTENSIONS = /\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|rb|php|cs|swift)$/;
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Find canonical doc references for a single file. Reuses the same three
+ * match strategies as trace --reverse for consistency: direct path,
+ * basename, backticked module name.
+ */
+function findReferences(file, docs) {
+  const refs = [];
+  const normalized = file.replace(/^\.\//, '');
+  const base = basename(normalized);
+  const stem = base.replace(/\.[^.]+$/, '');
+  const stemRe = new RegExp(`\`${escapeRegex(stem)}\``);
+  for (const [docName, lines] of docs) {
+    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 (stemRe.test(line)) kind = 'module';
+      if (kind) {
+        refs.push({ doc: docName, line: i + 1, kind });
+      }
+    }
+  }
+  return refs;
+}
+
+export function runImpact(projectDir, _config, flags) {
+  const isJson = flags.format === 'json';
+  const since = flags.since || 'HEAD~1';
+
+  if (!isGitRepo(projectDir)) {
+    if (isJson) {
+      console.log(JSON.stringify({ since, error: 'not a git repository', changedFiles: [], affectedDocs: [] }, null, 2));
+    } else {
+      console.error(`${c.red}Not a git repository — impact requires git history.${c.reset}`);
+    }
+    process.exit(1);
+  }
+
+  const changed = changedFilesSince(projectDir, since);
+  // Filter to code files only — markdown/json/yaml changes don't have "doc
+  // impact" in the same sense; they ARE the docs (or config).
+  const codeChanged = changed.filter(f => CODE_EXTENSIONS.test(f));
+
+  // Index canonical docs once
+  const docsDir = resolve(projectDir, 'docs-canonical');
+  const docsIndex = new Map(); // docName → lines[]
+  if (existsSync(docsDir)) {
+    try {
+      for (const f of readdirSync(docsDir)) {
+        if (!f.endsWith('.md')) continue;
+        try {
+          const content = readFileSync(resolve(docsDir, f), 'utf-8');
+          docsIndex.set(f, content.split('\n'));
+        } catch { /* skip unreadable */ }
+      }
+    } catch { /* skip if dir unreadable */ }
+  }
+
+  // Compute per-file references
+  const fileImpact = []; // { file, references: [{doc, line, kind}] }
+  for (const f of codeChanged) {
+    fileImpact.push({ file: f, references: findReferences(f, docsIndex) });
+  }
+
+  // Roll up: which docs are affected, with all source files
+  const docMap = new Map(); // doc → Set<file>
+  for (const { file, references } of fileImpact) {
+    for (const r of references) {
+      if (!docMap.has(r.doc)) docMap.set(r.doc, new Set());
+      docMap.get(r.doc).add(file);
+    }
+  }
+  const affectedDocs = Array.from(docMap.entries()).map(([doc, files]) => ({
+    doc,
+    files: Array.from(files),
+  }));
+
+  // ── JSON output ──
+  if (isJson) {
+    console.log(JSON.stringify({
+      since,
+      changedFiles: codeChanged,
+      ignoredFiles: changed.filter(f => !CODE_EXTENSIONS.test(f)),
+      affectedDocs,
+      timestamp: new Date().toISOString(),
+    }, null, 2));
+    return;
+  }
+
+  // ── Text output ──
+  console.log(`${c.bold}📊 DocGuard Impact${c.reset} ${c.dim}(since ${since})${c.reset}\n`);
+
+  if (changed.length === 0) {
+    console.log(`  ${c.green}✅ No file changes since ${since}.${c.reset}`);
+    return;
+  }
+  if (codeChanged.length === 0) {
+    console.log(`  ${c.dim}No code files changed (${changed.length} non-code files: ${changed.slice(0, 3).join(', ')}${changed.length > 3 ? '…' : ''}).${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.cyan}${codeChanged.length}${c.reset} code file(s) changed.\n`);
+
+  if (affectedDocs.length === 0) {
+    console.log(`  ${c.yellow}⚠ No canonical docs reference any of the changed files.${c.reset}`);
+    console.log(`  ${c.dim}This often means the changed code is undocumented. Consider:${c.reset}`);
+    console.log(`  ${c.dim}  - Running ${c.cyan}docguard generate --plan${c.dim} to add doc skeletons${c.reset}`);
+    console.log(`  ${c.dim}  - Reviewing whether the change belongs in an existing doc${c.reset}`);
+    return;
+  }
+
+  console.log(`  ${c.green}${affectedDocs.length}${c.reset} canonical doc(s) reference the changed files:\n`);
+  for (const { doc, files } of affectedDocs) {
+    console.log(`  ${c.cyan}${doc}${c.reset} ${c.dim}(${files.length} file${files.length > 1 ? 's' : ''})${c.reset}`);
+    for (const f of files.slice(0, 5)) {
+      console.log(`     ${c.dim}via${c.reset} ${f}`);
+    }
+    if (files.length > 5) console.log(`     ${c.dim}... ${files.length - 5} more${c.reset}`);
+  }
+
+  // List code files with NO doc references — these may need new docs
+  const orphaned = fileImpact.filter(fi => fi.references.length === 0).map(fi => fi.file);
+  if (orphaned.length > 0) {
+    console.log(`\n  ${c.yellow}${orphaned.length} changed file(s) have NO canonical doc reference:${c.reset}`);
+    for (const f of orphaned.slice(0, 5)) console.log(`     ${c.dim}• ${f}${c.reset}`);
+    if (orphaned.length > 5) console.log(`     ${c.dim}... ${orphaned.length - 5} more${c.reset}`);
+    console.log(`  ${c.dim}These may be undocumented — review whether they belong in an existing doc.${c.reset}`);
+  }
+}

{docguard_cli-0.12.0 → docguard_cli-0.13.1}/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; }