docguard-cli 0.15.3__tar.gz → 0.16.0__tar.gz

{docguard_cli-0.15.3/extensions/spec-kit-docguard → docguard_cli-0.16.0/.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.15.3
+  version: 0.16.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.0 -->
 
 # DocGuard Fix Skill
 

{docguard_cli-0.15.3/extensions/spec-kit-docguard → docguard_cli-0.16.0/.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.15.3
+  version: 0.16.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.0 -->
 
 # DocGuard Guard Skill
 

{docguard_cli-0.15.3/extensions/spec-kit-docguard → docguard_cli-0.16.0/.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.15.3
+  version: 0.16.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.0 -->
 
 # DocGuard Review Skill
 

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/.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.15.3
+  version: 0.16.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.15.3 -->
+<!-- docguard:version: 0.16.0 -->
 
 # DocGuard Score Skill
 

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/.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.15.3
+  version: 0.16.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/CHANGELOG.md

@@ -7,6 +7,47 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-05-26
+
+Feature release driven entirely by feedback from a real Python project running
+DocGuard for the first time. **8 user-reported items shipped, 519 tests** (was
+497, +22). 22 validators. The Python user's top two asks (language-aware
+TRACE_MAP, hook-overwrite protection) are both in.
+
+### Fixed
+
+- **P1 — JSON+ANSI bleed in `score`/`trace`/`diff` `--format json`.** Critical CI bug. The v0.12 headless-mode fix only covered `guard` and (later) `diagnose`; three other commands leaked colored banners before the JSON body, breaking `jq` / `python -c "json.loads(...)"` pipelines. All five JSON-emitting commands now produce clean parseable output.
+- **P4 — `docguard diff` false positive on system env vars.** Backticked mentions of `PATH`, `HOME`, `USER`, `SHELL`, etc. inside ENVIRONMENT.md prose ("the venv `PATH`") were flagged as documented-but-not-implemented user env vars. Added a `SYSTEM_ENV_VARS` denylist to both `diff` and the `Environment` validator. The 30-name list covers OS/shell/CI vars; user-app names (`DATABASE_URL`, `API_KEY`, etc.) still count as documented.
+
+### Added
+
+- **P2 — Language-aware `TRACE_MAP`** (top user ask). The original JS/TS-only patterns false-negatived on Python (`test_*.py`), Rust (`tests/*.rs`), Go (`*_test.go`), Java (`*Test.java`), Ruby (`*_spec.rb`), and PHP test layouts. Every `TRACE_MAP` entry — Test files, Entry points, Config files, Schemas, Env files — now matches the equivalent patterns across ecosystems. New `tests/trace-multilang.test.mjs` (16 tests) locks the cross-language matching in.
+- **P3 — Hook overwrite protection** (2nd user ask). `docguard hooks --type pre-commit` previously clobbered user customizations on re-install. Now wraps DocGuard's content in `# BEGIN DOCGUARD MANAGED — do not edit between these markers` / `# END DOCGUARD MANAGED` markers and **splices only the managed block** on re-install, preserving everything around it. Legacy pre-v0.16 hooks (no markers) prompt the user to re-run with `--force` to upgrade. Third-party pre-existing hooks refuse to clobber without `--force`.
+- **P5 — `--quiet` / `-q` flag.** Suppresses the banner + ensureSkills decorative line. Useful inside git hooks and CI loops where the 5-line banner becomes 30 lines of noise. Doesn't affect validator output itself.
+- **P6 — `docguard explain <warning>` command** (user wishlist). Paste any warning text and get back: which validator emitted it, what triggered it, how to fix, a passing example, and the standard it references. Cuts source-spelunking time from 5-10 minutes to seconds. Covers all 16 validators. Also accepts a validator key directly (`docguard explain freshness`). JSON mode for tooling.
+- **P7 — N/A markers for required doc sections.** A project that legitimately has no auth (CLI, library, internal tool) can now declare it via `<!-- docguard:section authentication n/a — CLI tool, no user accounts -->` instead of writing "Absent by design" boilerplate. The marker requires a reason (non-empty after the dash) so it can't be a silent opt-out. Doc-Sections counts the marked section as passed.
+- **P8 — `--no-spec-kit` flag for `init`.** Default-on stays for discoverability, but minimalist library projects can now skip the `.specify/`, `.agent/`, `commands/` scaffolding entirely with `docguard init --no-spec-kit`.
+
+### Internal
+
+- **3 new test files**: `tests/trace-multilang.test.mjs` (16), `tests/section-na-markers.test.mjs` (5), plus expanded `tests/hooks.test.mjs` (+2 for managed-block). **Total: 497 → 519 tests (+22 new).**
+- New top-level command: `cli/commands/explain.mjs` with a 16-validator explainer table.
+- New helpers in `cli/commands/hooks.mjs`: `wrapManaged()`, `spliceManagedBlock()`, `BEGIN_MARKER`, `END_MARKER`.
+- New `SYSTEM_ENV_VARS` constant exported from `cli/commands/diff.mjs` (mirrored in `cli/validators/environment.mjs`).
+- Headless-mode flag check (`flags.quiet`) added to the main dispatcher.
+- No new NPM deps.
+
+### Out of scope (deferred to v0.17)
+
+User feedback items NOT addressed in this release:
+
+- **F6 — Score "Top improvements" cache** (low repro confidence — user cleared on the next run, may have been observer effect).
+- **F7 — Validator count drift in tool's own scaffolding** (philosophical: counts ARE accurate per-run; the issue is that DocGuard's OWN docs mention the count and naturally drift as validators are added. Could compute at runtime; defer for now.)
+- **F8 — Version pin in `.docguard.json`** (CDD reproducibility — record the DocGuard version that last passed). Medium effort, real value.
+- **F10 — Memory accuracy drill-down** (`docguard memory --diff` to show which claims don't match code). Bigger feature.
+- **N1 — Validator naming consistency** (`testSpec` JSON key / `test-spec` CLI flag / `Test-Spec` display). Breaking change; needs migration story.
+- **N3 — `--tax` fold** (philosophical: `--tax` does add information, just not enough to feel different).
+
 ## [0.15.3] - 2026-05-26
 
 Repo hygiene release — scrubbed a client-specific project name from public artifacts.

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.15.3
+Version: 0.16.0
 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

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/cli/commands/diff.mjs

@@ -25,8 +25,12 @@ const CODE_EXTENSIONS = new Set([
 ]);
 
 export function runDiff(projectDir, config, flags) {
-  console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  // v0.16-P1: headless mode for JSON output (matches guard/score/trace fix).
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}🔍 DocGuard Diff — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  }
 
   const results = [];
 
@@ -196,6 +200,25 @@ function diffEntities(dir, config = {}) {
   };
 }
 
+// v0.16-P4: common system environment variables that get backticked in
+// prose ("the venv `PATH`", "your `HOME` directory") but are NEVER user-set
+// application env vars. Excluding them from the docVars set kills the
+// false-positive class reported by the Python user where `PATH` was flagged
+// as "documented-but-not-implemented".
+//
+// Conservative list — only the names that are unambiguously OS/shell vars.
+// Application names like `DATABASE_URL`, `API_KEY` etc. still count.
+const SYSTEM_ENV_VARS = new Set([
+  'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD', 'TMPDIR', 'TEMP', 'TMP',
+  'LANG', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES', 'TZ',
+  'EDITOR', 'VISUAL', 'PAGER', 'TERM', 'COLORTERM',
+  'DISPLAY', 'SSH_AUTH_SOCK', 'SSH_CONNECTION', 'SSH_TTY',
+  'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_RUNTIME_DIR',
+  // CI/build platform vars (set by the platform, not by the app)
+  'CI', 'GITHUB_TOKEN', 'GITHUB_ACTIONS', 'GITHUB_REF', 'GITHUB_SHA',
+  'NODE_ENV', // could be app-set but more often platform-set; conservative skip
+]);
+
 function diffEnvVars(dir, config = {}) {
   const envDocPath = resolve(dir, 'docs-canonical/ENVIRONMENT.md');
   if (!existsSync(envDocPath)) return null;
@@ -208,6 +231,9 @@ function diffEnvVars(dir, config = {}) {
   const varRegex = /`([A-Z][A-Z0-9_]*[A-Z0-9])`/g;
   let match;
   while ((match = varRegex.exec(content)) !== null) {
+    // v0.16-P4: skip backticked system vars that appear in prose. They're
+    // never user-set application env vars; flagging them produces noise.
+    if (SYSTEM_ENV_VARS.has(match[1])) continue;
     docVars.add(match[1]);
   }
 

docguard_cli-0.16.0/cli/commands/explain.mjs

@@ -0,0 +1,286 @@
+/**
+ * Explain Command — v0.16-P6.
+ *
+ * Asked for by a user who'd spent 5-10 minutes per warning spelunking
+ * through validators/*.mjs source to understand what the validator wanted.
+ * `docguard explain "<warning text>"` matches the warning back to its
+ * validator and prints:
+ *   - Which validator emitted it
+ *   - What pattern triggered it
+ *   - A passing example
+ *   - The doc / spec / standard it's checking against
+ *
+ * Also supports `docguard explain <validator-key>` to show the whole
+ * validator's purpose without needing a specific warning.
+ *
+ * Zero NPM dependencies. Pure lookup table.
+ */
+
+import { c } from '../shared.mjs';
+
+/**
+ * Validator-key → human-readable explainer. Keyed by the same key DocGuard
+ * uses internally for severity overrides + lite-mode selection.
+ *
+ * Each entry has:
+ *   - title:    one-line summary
+ *   - what:     what the validator checks (declarative)
+ *   - why:      why it matters (motivation)
+ *   - triggers: array of common warning fragments and what each means
+ *   - example:  a tiny passing snippet
+ *   - standard: the spec/practice the validator references
+ */
+const EXPLAINERS = {
+  structure: {
+    title: 'Structure — required CDD files exist',
+    what: 'Verifies the canonical files declared in .docguard.json `requiredFiles.canonical` are present, plus AGENTS.md/CLAUDE.md, CHANGELOG.md, DRIFT-LOG.md.',
+    why:  'A documentation memory needs known anchor points. Missing files = broken memory.',
+    triggers: [
+      ['Missing required file', 'A canonical doc declared in your config doesn\'t exist on disk. Create it or remove it from `requiredFiles.canonical`.'],
+      ['Missing agent file', 'No AGENTS.md or CLAUDE.md found. Create one — even a stub establishes the agent contract.'],
+    ],
+    example: 'docs-canonical/ARCHITECTURE.md, AGENTS.md, CHANGELOG.md all present',
+    standard: 'CDD STANDARD (this project\'s STANDARD.md)',
+  },
+  docsSync: {
+    title: 'Docs-Sync — code files are referenced in canonical docs',
+    what: 'Walks route/service files in your source tree. For each, checks that the file path or basename appears in any canonical doc.',
+    why:  'Code that exists but isn\'t mentioned in any doc is invisible to future contributors and AI agents.',
+    triggers: [
+      ['not referenced in any canonical doc', 'A route or service file has no mention anywhere in docs-canonical/. Add a one-line reference (path or filename) to ARCHITECTURE.md or DATA-MODEL.md.'],
+    ],
+    example: '`src/services/auth.ts` mentioned in ARCHITECTURE.md\'s Components table',
+    standard: 'arc42 Component Map',
+  },
+  drift: {
+    title: 'Drift-Comments — every `// DRIFT:` has a DRIFT-LOG entry',
+    what: 'Scans code for `// DRIFT: reason` comments (also # / /* / -- variants). Each must have a row in DRIFT-LOG.md.',
+    why:  'DRIFT comments document conscious deviations from canonical specs. Without log entries, the deviation is invisible.',
+    triggers: [
+      ['DRIFT comment but DRIFT-LOG.md doesn\'t exist', 'Create DRIFT-LOG.md or remove the DRIFT comment.'],
+      ['no matching DRIFT-LOG.md entry', 'Add a row to DRIFT-LOG.md documenting the deviation, OR remove the // DRIFT: comment if the deviation is no longer current.'],
+    ],
+    example: '// DRIFT: using S3 SDK v2 here for compatibility — DRIFT-LOG.md has a row dated and explaining why',
+    standard: 'CDD principle: log every intentional deviation',
+  },
+  changelog: {
+    title: 'Changelog — Keep a Changelog format',
+    what: 'CHANGELOG.md must have a top-level `# Changelog` heading and an `## [Unreleased]` section.',
+    why:  'Standard format makes changelogs machine-readable. The Unreleased section is where new work accumulates between releases.',
+    triggers: [
+      ['Missing # Changelog heading', 'Start CHANGELOG.md with `# Changelog`.'],
+      ['Missing ## [Unreleased] section', 'Add `## [Unreleased]` between `# Changelog` and your first dated release.'],
+    ],
+    example: '# Changelog\\n\\n## [Unreleased]\\n\\n## [1.0.0] - 2026-01-01',
+    standard: 'Keep a Changelog v1.1.0 (https://keepachangelog.com)',
+  },
+  testSpec: {
+    title: 'Test-Spec — declared tests exist',
+    what: 'Reads TEST-SPEC.md\'s test mapping (rows linking sources to test files) and verifies each referenced test file exists.',
+    why:  'A spec that claims test coverage for X but the test file is missing is a stale promise.',
+    triggers: [
+      ['no service-to-test mappings', 'TEST-SPEC.md has no recognized mapping table. Add a table with `| Source | Test file | Status |` columns.'],
+      ['referenced test file does not exist', 'A path in TEST-SPEC.md\'s mapping doesn\'t exist. Update the path or remove the row.'],
+    ],
+    example: '| `src/auth.ts` | `tests/auth.test.ts` | ✅ |',
+    standard: 'ISO/IEC/IEEE 29119-3 (test specification)',
+  },
+  environment: {
+    title: 'Environment — env vars used in code are documented',
+    what: 'Greps `process.env.X` and `import.meta.env.X` (plus `os.environ` for Python) across source. Each name must appear in ENVIRONMENT.md or .env.example/.env.template.',
+    why:  'Undocumented env vars are runtime surprises waiting to happen.',
+    triggers: [
+      ['used but not documented', 'Code reads an env var that ENVIRONMENT.md doesn\'t list. Add it to the table.'],
+      ['VITE_API_URL or similar prefix', 'Naked prefixes like `VITE_` (no suffix) get filtered out — they\'re convention markers, not real var names.'],
+    ],
+    example: '`DATABASE_URL` listed in ENVIRONMENT.md\'s Environment Variables table AND read via `process.env.DATABASE_URL` in code',
+    standard: '12-Factor App III. Config',
+  },
+  security: {
+    title: 'Security — secrets handling + auth presence',
+    what: 'Checks SECURITY.md for required sections, and scans code for committed secrets / unsafe patterns.',
+    why:  'OWASP ASVS baseline.',
+    triggers: [
+      ['Missing "Authentication" section', 'Add `## Authentication` to SECURITY.md. If the project genuinely has no auth (CLI, library), use the v0.16-P7 N/A marker: `<!-- docguard:section authentication n/a — reason -->`.'],
+      ['Possible secret', 'A pattern matching common secret formats (API keys, JWT secrets) was found in committed code. Move to env var or .env.example.'],
+    ],
+    example: 'SECURITY.md has `## Authentication` describing JWT flow; no `sk_live_*` strings in code',
+    standard: 'OWASP ASVS v4.0',
+  },
+  freshness: {
+    title: 'Freshness — docs updated alongside code',
+    what: 'For each canonical doc, counts code commits since the doc\'s last commit. >10 commits = stale.',
+    why:  'Docs drift silently. This validator surfaces the drift before it becomes invisible.',
+    triggers: [
+      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose for accuracy.'],
+      ['DRIFT-LOG.md may be stale', 'DRIFT comments in code outpaced log entries. Add the entries.'],
+    ],
+    example: 'ARCHITECTURE.md last committed within 10 code commits',
+    standard: 'CDD principle: docs and code commit together',
+  },
+  traceability: {
+    title: 'Traceability — every FR/SC ID has test coverage',
+    what: 'Scans specs/ for FR-### and SC-### requirement IDs. Each must appear in a test file as `@req FR-###`.',
+    why:  'Untraceable requirements drift from implementation.',
+    triggers: [
+      ['has no test coverage', 'Add `// @req FR-012` (or similar) as a comment in the test that verifies the requirement.'],
+      ['orphaned test reference', 'A `@req` comment references an ID that doesn\'t exist in any spec. Update the ID or remove the marker.'],
+    ],
+    example: 'spec.md defines `**FR-012**: ...` and test file has `// @req FR-012` near the test that verifies it',
+    standard: 'ISO/IEC/IEEE 29148 (requirements traceability)',
+  },
+  apiSurface: {
+    title: 'API-Surface — endpoints in code match API-REFERENCE.md',
+    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs.',
+    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible.',
+    triggers: [
+      ['documented but absent', 'API-REFERENCE.md lists an endpoint that scanRoutes() can\'t find. Remove or fix the doc; `fix --write` removes when marked.'],
+      ['present but undocumented', 'A route exists in code but API-REFERENCE.md doesn\'t list it. Add it.'],
+    ],
+    example: 'GET /api/users in src/routes/users.ts AND in API-REFERENCE.md\'s Endpoints table',
+    standard: 'OpenAPI 3.1',
+  },
+  metricsConsistency: {
+    title: 'Metrics-Consistency — quoted numbers match reality',
+    what: 'Greps canonical + root docs for "N validators" / "N checks" claims and compares against the actual runtime count.',
+    why:  'Stale numeric claims ("19 validators" when it\'s now 22) erode credibility.',
+    triggers: [
+      ['says "N validators" but actual count is M', 'Run `docguard fix --write` — this is auto-fixable.'],
+    ],
+    example: 'AGENTS.md says "22 validators" and `docguard guard` shows 22 active validators',
+    standard: 'CDD principle: documented metrics match reality',
+  },
+  crossReference: {
+    title: 'Cross-Reference — internal markdown links resolve',
+    what: 'Scans canonical docs for `[text](./OTHER.md#anchor)` and `#anchor` links. Verifies the target file exists and the anchor matches a heading.',
+    why:  'Broken doc-to-doc links are the most-clicked dead ends in onboarding.',
+    triggers: [
+      ['broken link: target file not found', 'The file path doesn\'t exist. Fix the path or remove the link.'],
+      ['broken anchor', 'Anchor doesn\'t match any heading. Hint: `(did you mean #X?)` is appended for near-misses; if marked `[auto-fixable]`, run `docguard fix --write`.'],
+    ],
+    example: '`[Setup](#prerequisites)` in ENVIRONMENT.md AND `## Prerequisites` heading present',
+    standard: 'GitHub Flavored Markdown anchor rules',
+  },
+  generatedStaleness: {
+    title: 'Generated-Staleness — source=code sections match scanner output',
+    what: 'For each `<!-- docguard:section source=code -->` block, re-runs the memory plan scanner and compares against on-disk content. Also flags status: draft docs unmodified for > 14 days.',
+    why:  'Code-truth sections must reflect what the code actually says. Forgotten drafts rot.',
+    triggers: [
+      ['is stale', 'A code-truth section drifted. Run `docguard sync --write` (or `docguard fix --write` since v0.14-P3 — the validator now emits a regenerate-section fix).'],
+      ['status: draft for', 'A doc has been in draft for too long. Promote to `status: current` or remove. Threshold via `config.draftStalenessDays`.'],
+    ],
+    example: 'All source=code sections match what the scanner would produce right now',
+    standard: 'CDD principle: code-truth sections are machine-owned',
+  },
+  todoTracking: {
+    title: 'TODO-Tracking — TODOs are tracked + skipped tests explained',
+    what: 'Finds TODO/FIXME/HACK comments in source. Each must be referenced in tracking docs (ROADMAP.md, GitHub issues, etc.). Also flags `it.skip()` / `test.skip()` without an adjacent `// REASON:` comment.',
+    why:  'TODOs in code that no one tracks are silent debt.',
+    triggers: [
+      ['Skipped test without explanation', 'Add `// REASON: <why>` immediately above the skip.'],
+      ['Untracked TODO', 'Reference the TODO from ROADMAP.md by file:line, OR add it to a GitHub issue and link the issue ID in the comment.'],
+    ],
+    example: '// REASON: waiting on upstream fix in libfoo v2.5\\ntest.skip("foo", () => {})',
+    standard: 'Pragmatic Programmer (debt visibility)',
+  },
+  specKit: {
+    title: 'Spec-Kit — spec.md/plan.md/tasks.md have required sections',
+    what: 'For projects using Spec Kit, validates each spec/*.md against the spec-kit-template required sections.',
+    why:  'Spec Kit\'s value comes from consistent shape across specs.',
+    triggers: [
+      ['Missing mandatory section', 'Add the section listed in the warning. Reference the template at .specify/templates/'],
+    ],
+    example: 'plan.md has Summary, Technical Context, Constitution Check, Project Structure',
+    standard: 'GitHub Spec Kit',
+  },
+};
+
+/**
+ * Match a warning text fragment against the explainer table. Returns the
+ * matching entry's key + the trigger entry that best matches, or null when
+ * no match is confident enough.
+ */
+function matchWarning(query) {
+  const q = query.toLowerCase();
+
+  // Exact validator-key lookup (e.g. `docguard explain freshness`)
+  if (EXPLAINERS[query]) return { key: query, trigger: null };
+  // Also try kebab-case (e.g. `cross-reference` → `crossReference`)
+  const camelized = query.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+  if (EXPLAINERS[camelized]) return { key: camelized, trigger: null };
+
+  // Search trigger phrases
+  let best = null;
+  let bestScore = 0;
+  for (const [key, e] of Object.entries(EXPLAINERS)) {
+    for (const [phrase, _hint] of e.triggers) {
+      if (q.includes(phrase.toLowerCase())) {
+        const score = phrase.length; // prefer the more-specific phrase
+        if (score > bestScore) {
+          best = { key, trigger: [phrase, _hint] };
+          bestScore = score;
+        }
+      }
+    }
+  }
+  return best;
+}
+
+export function runExplain(projectDir, _config, flags) {
+  const query = (flags.args || []).join(' ').trim();
+  const isJson = flags.format === 'json';
+
+  if (!query) {
+    if (isJson) {
+      console.log(JSON.stringify({ validators: Object.keys(EXPLAINERS) }, null, 2));
+      return;
+    }
+    console.log(`${c.bold}🧭 docguard explain${c.reset} ${c.dim}— usage:${c.reset}`);
+    console.log(`  ${c.cyan}docguard explain <validator-key>${c.reset}    e.g. docguard explain freshness`);
+    console.log(`  ${c.cyan}docguard explain "<warning text>"${c.reset}   e.g. docguard explain "no service-to-test mappings"`);
+    console.log(`\n${c.dim}Known validators:${c.reset}`);
+    for (const [k, e] of Object.entries(EXPLAINERS)) {
+      console.log(`  ${c.cyan}${k.padEnd(22)}${c.reset} ${c.dim}${e.title}${c.reset}`);
+    }
+    return;
+  }
+
+  const match = matchWarning(query);
+  if (!match) {
+    if (isJson) {
+      console.log(JSON.stringify({ query, match: null }, null, 2));
+      return;
+    }
+    console.log(`${c.yellow}No matching validator or warning found for: "${query}"${c.reset}`);
+    console.log(`${c.dim}Try: ${c.cyan}docguard explain${c.dim} (no args) to list all validators.${c.reset}`);
+    process.exit(1);
+  }
+
+  const e = EXPLAINERS[match.key];
+  if (isJson) {
+    console.log(JSON.stringify({ query, match: { key: match.key, ...e, matchedTrigger: match.trigger } }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🧭 ${e.title}${c.reset}`);
+  console.log(`${c.dim}   validator key: ${match.key}${c.reset}\n`);
+
+  console.log(`${c.bold}What it checks:${c.reset}\n  ${e.what}\n`);
+  console.log(`${c.bold}Why:${c.reset}\n  ${e.why}\n`);
+
+  if (match.trigger) {
+    console.log(`${c.bold}Your warning ("${query}") matches:${c.reset}`);
+    console.log(`  ${c.yellow}${match.trigger[0]}${c.reset}`);
+    console.log(`  ${match.trigger[1]}\n`);
+  } else {
+    console.log(`${c.bold}Common warnings:${c.reset}`);
+    for (const [phrase, hint] of e.triggers) {
+      console.log(`  ${c.yellow}${phrase}${c.reset}`);
+      console.log(`    ${c.dim}${hint}${c.reset}`);
+    }
+    console.log('');
+  }
+
+  console.log(`${c.bold}Passing example:${c.reset}\n  ${c.dim}${e.example}${c.reset}\n`);
+  console.log(`${c.bold}Standard:${c.reset} ${c.dim}${e.standard}${c.reset}`);
+}

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/cli/commands/hooks.mjs

@@ -4,6 +4,56 @@
  */
 
 import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+
+// v0.16-P3: managed-block markers. Letting users extend the hook with their
+// own commands (data-file guards, lint checks, etc.) without us clobbering
+// them on re-install. Format:
+//
+//   #!/bin/sh
+//   # ... user's prelude ...
+//
+//   # BEGIN DOCGUARD MANAGED — do not edit between these markers
+//   ... DocGuard's content ...
+//   # END DOCGUARD MANAGED
+//
+//   # ... user's postlude ...
+//
+// On re-install, we splice ONLY the content between the markers, preserving
+// everything else verbatim. Without markers (legacy hooks or third-party
+// pre-existing hooks), behavior falls back to the existing --force flow.
+const BEGIN_MARKER = '# BEGIN DOCGUARD MANAGED — do not edit between these markers';
+const END_MARKER   = '# END DOCGUARD MANAGED';
+
+/**
+ * Wrap a hook body in BEGIN/END markers so future re-installs can splice
+ * just the managed portion. The shebang stays at the top, outside the block.
+ */
+function wrapManaged(body) {
+  // Pull shebang off the front if present so it stays at the top.
+  const lines = body.split('\n');
+  let shebang = '';
+  if (lines[0] && lines[0].startsWith('#!')) {
+    shebang = lines.shift() + '\n';
+  }
+  return `${shebang}${BEGIN_MARKER}\n${lines.join('\n').replace(/\n+$/, '')}\n${END_MARKER}\n`;
+}
+
+/**
+ * Splice DocGuard's managed content into an existing hook file that has
+ * the BEGIN/END markers. Returns the new file content (string) or null
+ * when the markers aren't found (caller falls back to legacy behavior).
+ */
+function spliceManagedBlock(existing, newBody) {
+  const startIdx = existing.indexOf(BEGIN_MARKER);
+  const endIdx   = existing.indexOf(END_MARKER);
+  if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) return null;
+  const before = existing.slice(0, startIdx);
+  const after  = existing.slice(endIdx + END_MARKER.length);
+  // newBody has its own shebang — strip it since we're splicing into the
+  // middle of an existing file (which already has one).
+  const bodyNoShebang = newBody.replace(/^#!.*\n/, '');
+  return `${before}${BEGIN_MARKER}\n${bodyNoShebang.replace(/\n+$/, '')}\n${END_MARKER}${after}`;
+}
 import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
 
@@ -228,26 +278,45 @@ export function runHooks(projectDir, config, flags) {
 
   for (const name of hookTypes) {
     const hookPath = resolve(hooksDir, name);
+    const useAutofix = name === 'pre-commit' && flags.autoFix;
+    const newContent = wrapManaged(useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content);
+    const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
 
-    if (existsSync(hookPath) && !flags.force) {
-      // Check if it's already a DocGuard hook
+    if (existsSync(hookPath)) {
       const existing = readFileSync(hookPath, 'utf-8');
-      if (existing.includes('DocGuard')) {
-        console.log(`  ${c.dim}⏭️  ${name} (DocGuard hook already installed)${c.reset}`);
+
+      // v0.16-P3: managed-block path — splice just the DocGuard portion,
+      // preserve everything outside it. The user can extend the hook with
+      // their own commands above/below the markers without losing them on
+      // re-install.
+      const spliced = spliceManagedBlock(existing, newContent);
+      if (spliced !== null) {
+        writeFileSync(hookPath, spliced, 'utf-8');
+        chmodSync(hookPath, 0o755);
+        console.log(`  ${c.green}↻ ${name}${c.reset}: updated DocGuard managed block (preserved user content around it)`);
+        installed++;
+        continue;
+      }
+
+      // No markers found. Two sub-cases:
+      //   (a) Legacy DocGuard hook (pre-v0.16, no markers, contains "DocGuard")
+      //       → upgrade in place when --force is set
+      //   (b) Third-party hook the user wrote themselves
+      //       → refuse without --force; warn about clobber risk
+      if (!flags.force) {
+        if (existing.includes('DocGuard')) {
+          console.log(`  ${c.yellow}⚠️  ${name}: legacy DocGuard hook (pre-v0.16) without managed markers. Re-run with --force to upgrade it to the managed-block format.${c.reset}`);
+        } else {
+          console.log(`  ${c.yellow}⚠️  ${name}: an existing hook is present and has no DocGuard markers. Re-run with --force to overwrite (your hook will be replaced — back it up first!).${c.reset}`);
+        }
         skipped++;
         continue;
       }
-      console.log(`  ${c.yellow}⚠️  ${name}: existing hook found (use --force to overwrite)${c.reset}`);
-      skipped++;
-      continue;
+      // --force path: write fresh managed-block version
     }
 
-    // pre-commit supports an auto-fix variant (applies mechanical fixes first).
-    const useAutofix = name === 'pre-commit' && flags.autoFix;
-    const content = useAutofix ? PRE_COMMIT_AUTOFIX : HOOKS[name].content;
-    writeFileSync(hookPath, content, 'utf-8');
-    chmodSync(hookPath, 0o755); // Make executable
-    const desc = useAutofix ? 'Apply mechanical fixes (fix --write) then guard' : HOOKS[name].description;
+    writeFileSync(hookPath, newContent, 'utf-8');
+    chmodSync(hookPath, 0o755);
     console.log(`  ${c.green}✅ ${name}${c.reset}: ${desc}`);
     installed++;
   }

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/cli/commands/init.mjs

@@ -253,10 +253,14 @@ poetry.lock
 
   // ── Spec-Kit Integration (Extension-First) ────────────────────────────
   // Delegate LLM/IDE detection and spec-kit skill install to `specify init`
+  // v0.16-P8: --no-spec-kit lets users skip the .specify/.agent/commands
+  // scaffolding (minimalist library projects, CI containers, etc.).
   const specKitAvailable = isSpecKitAvailable();
   const specKitInitialized = isSpecKitInitialized(projectDir);
 
-  if (specKitAvailable && !specKitInitialized) {
+  if (flags.noSpecKit) {
+    console.log(`\n  ${c.dim}⏭️  Spec Kit init skipped (--no-spec-kit).${c.reset}`);
+  } else if (specKitAvailable && !specKitInitialized) {
     console.log(`\n  ${c.bold}🌱 Spec Kit Integration${c.reset}`);
 
     // Detect which AI agent is in use (matches spec-kit's --ai flag)

{docguard_cli-0.15.3 → docguard_cli-0.16.0}/cli/commands/score.mjs

@@ -21,8 +21,15 @@ const WEIGHTS = {
 };
 
 export function runScore(projectDir, config, flags) {
-  console.log(`${c.bold}📊 DocGuard Score — ${config.projectName}${c.reset}`);
-  console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  // v0.16-P1: suppress banner in JSON mode so stdout stays parseable.
+  // Was already fixed for guard/diagnose in v0.12; score/trace/diff missed
+  // the pattern. Reported on a Python project where `score --format json`
+  // mixed ANSI escapes with JSON.
+  const isJson = flags.format === 'json';
+  if (!isJson) {
+    console.log(`${c.bold}📊 DocGuard Score — ${config.projectName}${c.reset}`);
+    console.log(`${c.dim}   Directory: ${projectDir}${c.reset}\n`);
+  }
 
   const { scores, totalScore, grade, details } = calcAllScores(projectDir, config);