docguard-cli 0.9.10__tar.gz → 0.10.0__tar.gz

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

@@ -78,7 +78,8 @@ Classify every non-passing check using this priority matrix:
 
 **HIGH (fix before commit)**:
 - Doc Sections failures (missing required sections)
-- Drift detection (undocumented code deviations)
+- Drift-Comments (a `// DRIFT:` comment without a DRIFT-LOG.md entry)
+- API-Surface (API-REFERENCE.md documents an endpoint that no longer exists in code)
 - Changelog gaps
 - Traceability breaks
 
@@ -138,7 +139,7 @@ For each finding, provide a **specific, actionable fix** — not "fix the issue"
 
 Based on the triage results:
 
-- **If all PASS**: "All 19 validators passed. Project is CDD-compliant. Ready to commit."
+- **If all PASS**: "All 20 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.10.0/.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+      semver-minor-days: 3
+      semver-patch-days: 3
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    cooldown:
+      default-days: 7
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

docguard_cli-0.10.0/.github/workflows/supply-chain.yml

@@ -0,0 +1,23 @@
+name: Supply-Chain Security
+
+on:
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '30 12 * * 1'  # Mondays at 12:30 UTC
+  push:
+    branches: [main]
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  osv-scan-pr:
+    if: github.event_name == 'pull_request'
+    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@v2.3.8"
+
+  osv-scan-scheduled:
+    if: github.event_name != 'pull_request'
+    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v2.3.8"

{docguard_cli-0.9.10 → docguard_cli-0.10.0}/.github/workflows/sync-speckit-catalog.yml

@@ -112,6 +112,7 @@ jobs:
         run: |
           VERSION="${{ steps.meta.outputs.version }}"
           BRANCH="update-docguard"
+          PR_TITLE="chore: update DocGuard extension to v${VERSION}"
 
           # Build PR body
           cat > /tmp/pr-body.md << 'HEADER'
@@ -133,30 +134,46 @@ jobs:
           echo "---" >> /tmp/pr-body.md
           echo "*This PR was automatically generated by the DocGuard release pipeline.*" >> /tmp/pr-body.md
 
-          # Try to create PR first — if it already exists, edit it instead
-          PR_URL=$(gh pr create \
+          # Check if PR already exists using multiple detection methods
+          EXISTING_PR=""
+
+          # Method 1: gh pr list with --head filter
+          EXISTING_PR=$(gh pr list \
             --repo github/spec-kit \
             --head "raccioly:${BRANCH}" \
-            --base main \
-            --title "chore: update DocGuard extension to v${VERSION}" \
-            --body-file /tmp/pr-body.md 2>&1) && {
-            echo "✅ Created new PR: $PR_URL"
-          } || {
-            echo "PR already exists — updating title and body..."
-            # Find the existing PR number
+            --state open \
+            --json number \
+            --jq '.[0].number' 2>/dev/null || echo "")
+
+          # Method 2: search by branch name if method 1 failed
+          if [ -z "$EXISTING_PR" ] || [ "$EXISTING_PR" = "null" ]; then
             EXISTING_PR=$(gh pr list \
               --repo github/spec-kit \
-              --head "raccioly:${BRANCH}" \
               --state open \
+              --search "head:raccioly:${BRANCH}" \
               --json number \
               --jq '.[0].number' 2>/dev/null || echo "")
-            if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
-              gh pr edit "$EXISTING_PR" \
-                --repo github/spec-kit \
-                --title "chore: update DocGuard extension to v${VERSION}" \
-                --body-file /tmp/pr-body.md
-              echo "✅ Updated existing PR #${EXISTING_PR}"
-            else
-              echo "✅ Branch force-pushed — PR content is updated via the branch"
-            fi
-          }
+          fi
+
+          if [ -n "$EXISTING_PR" ] && [ "$EXISTING_PR" != "null" ]; then
+            # PR exists — update title and body to match new version
+            echo "Found existing PR #${EXISTING_PR} — updating title and body..."
+            gh pr edit "$EXISTING_PR" \
+              --repo github/spec-kit \
+              --title "$PR_TITLE" \
+              --body-file /tmp/pr-body.md
+            echo "✅ Updated existing PR #${EXISTING_PR} to v${VERSION}"
+          else
+            # Try to create new PR
+            PR_URL=$(gh pr create \
+              --repo github/spec-kit \
+              --head "raccioly:${BRANCH}" \
+              --base main \
+              --title "$PR_TITLE" \
+              --body-file /tmp/pr-body.md 2>&1) && {
+              echo "✅ Created new PR: $PR_URL"
+            } || {
+              echo "⚠️ Could not create or find PR — branch was force-pushed with v${VERSION} content"
+            }
+          fi
+

docguard_cli-0.10.0/.jules/bolt.md

@@ -0,0 +1,7 @@
+## 2024-05-18 - [Optimization]
+**Learning:** Found string.includes early return could speed up checkUntrackedTodos in cli/validators/todo-tracking.mjs.
+**Action:** Implement fast early return with includes check before doing expensive splitting or matching.
+
+## 2024-05-18 - [O(N*M) String Overhead]
+**Learning:** To prevent N^2 performance bottlenecks in nested loops (such as comparing a list of items against multiple documents), precomputing expensive operations like `.toLowerCase()` during the initial file load or mapping phase avoids redundant $O(N \times M)$ overhead.
+**Action:** Precompute expensive string operations and property lookups (like `.toLowerCase()` and `.substring()`) outside of inner loops and during file load mapping phases to improve scaling.

docguard_cli-0.10.0/.jules/palette.md

@@ -0,0 +1,7 @@
+## 2024-04-16 - Web UI Components Constraint
+**Learning:** The docguard repository consists entirely of a Node.js CLI tool and a VS Code extension; it lacks web UI components (e.g., HTML, CSS, React, Vue), meaning traditional web-focused micro-UX enhancements do not apply.
+**Action:** Do not attempt traditional web-based UX enhancements here. Focus on CLI paradigms or skip UX enhancement requests if web-centric.
+
+## 2024-04-16 - Context-Aware Status Bar Tooltips
+**Learning:** VS Code extension status bar items can display multiple forms of feedback, but static tooltips fail to explain state changes. Providing context-aware tooltip text (e.g., explaining why a threshold warning icon appears) greatly improves the usability for developers monitoring CLI outputs inline.
+**Action:** Always map status bar dynamic properties (icon, text, backgroundColor) to corresponding informative tooltips that explain what the visual change means.

docguard_cli-0.10.0/.jules/sentinel.md

@@ -0,0 +1,4 @@
+## 2025-05-18 - [Command Injection via execSync]
+**Vulnerability:** Found multiple instances where user-controlled inputs (`projectDir`, `filePath`) were interpolated directly into shell commands via `execSync` (e.g., `execSync(\`node "\${cliPath}" init --dir "\${projectDir}"\`)`).
+**Learning:** This is a classic command injection vulnerability. If `projectDir` contains shell metacharacters like `;`, `&&`, or `||`, it allows arbitrary command execution.
+**Prevention:** Always use `execFileSync` (or `execFile` for async) instead of `execSync` when executing commands with dynamic inputs. Pass arguments as an array to ensure they are passed directly to the executable without shell interpolation.

docguard_cli-0.10.0/.npmrc

@@ -0,0 +1,7 @@
+# Supply-Chain Security Hardening
+# Applied: 2026-05-14T14:19:27Z
+# Blocks install scripts from untrusted packages.
+# Requires 7-day maturity for all versions.
+ignore-scripts=true
+min-release-age=7d
+audit-level=moderate

{docguard_cli-0.9.10 → docguard_cli-0.10.0}/AGENTS.md

@@ -41,7 +41,7 @@
 | Command | Purpose |
 |---------|---------|
 | `diagnose` | **Primary** — identify issues + generate AI fix prompts |
-| `guard` | Validate project (CI gate) — 19 validators |
+| `guard` | Validate project (CI gate) — 20 validators |
 | `generate` | Reverse-engineer docs from code |
 | `fix --doc <name>` | AI prompt for specific document |
 | `score` | CDD maturity score (0-100) |
@@ -102,3 +102,17 @@ extensions/spec-kit-docguard/
 - Test requirements in TEST-SPEC.md must be met
 - Run `docguard guard` before pushing — all checks must pass
 - All file writes use `safeWrite()` — backups before overwrite
+
+
+## Agent Rules
+
+### Dependencies
+- Never add a package without first verifying it exists on the official registry (npm/PyPI).
+- Always pin to exact versions in package.json/requirements.txt. No ^, ~, or >= ranges.
+- Prefer packages with >10k weekly downloads and >1 maintainer.
+- If you suggest a package, confirm its first-publish date is older than 30 days.
+- Never modify .npmrc, pnpm-workspace.yaml, or dependabot.yml without explicit user confirmation.
+
+### CI/CD
+- Never write a workflow using `pull_request_target` with checkout of PR-controlled refs.
+- Always pin third-party GitHub Actions to commit SHA, not @v1 or @main.

{docguard_cli-0.9.10 → docguard_cli-0.10.0}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-05-22
+
+### Added
+- **API-Surface validator** (`cli/validators/api-surface.mjs`) — compares endpoints documented in `docs-canonical/API-REFERENCE.md` against the project's real API surface (OpenAPI spec, monorepo-aware code route scan). Flags documented-but-deleted endpoints (HIGH/error when confirmed by a spec; warning on heuristic code-scan) and present-but-undocumented endpoints (warning). Brings the validator count to **20**.
+- **`N/A` result state** in `guard` — a validator that finds nothing to check now renders a neutral `➖ [N/A]` with a reason instead of a misleading green ✅. "Nothing to check" is no longer indistinguishable from "checked and clean". Exposed via `classifyResult()`; surfaced in text, `--format json`, `diagnose`, and `ci`.
+- **`cli/shared-source.mjs`** — monorepo-aware source resolution honoring `config.sourceRoot`, npm `workspaces`, and `pnpm-workspace.yaml`: `resolveSourceRoots()`, `collectPackageJsons()`, `detectDocker()`, `grepEnvUsage()`.
+- **`cli/scanners/api-doc.mjs`** — robust API-REFERENCE.md parser (headings + table rows) with path normalization (`:id ≡ {id}`, strips backticks/pipes/trailing slashes) and exact-match endpoint comparison.
+- **`docguard fix --doc api-reference`** — generates an AI prompt to reconcile API-REFERENCE.md with the real API surface.
+- **39 new tests** (api-doc, api-surface, shared-source, monorepo-scanning, guard-classify). Total: **214**.
+
+### Changed
+- **Monorepo awareness across validators** — `schema-sync`, `docs-coverage`, `docs-sync`, `test-spec`, `metadata-sync`, and test-file discovery now honor `config.sourceRoot`/workspaces instead of hardcoded root-relative paths. Previously these silently passed on monorepos whose code lives under e.g. `backend/src`.
+- **Environment validator now checks code truth** — compares documented env vars against actual `process.env` / `import.meta.env` usage (`.env.example` counts as documentation), replacing the prior section-heading-presence heuristic.
+- **Test-Spec verifies files, not glyphs** — a Source-to-Test/Journey row passes only if the referenced test file actually exists; the author-typed ✅ is no longer trusted as proof of coverage.
+- **Changelog validator** now implements the documented staged-change check: warns when staged code files exist but `CHANGELOG.md` is not staged (git-aware; N/A otherwise).
+- **`Drift` validator renamed to `Drift-Comments`** to clarify it checks `// DRIFT:` comment ↔ DRIFT-LOG.md bookkeeping, not doc/code drift. Config key (`drift`) is unchanged.
+- **Doc Sections** uses anchored heading matching instead of substring (no longer satisfied by a table-of-contents link or code block).
+
+### Fixed
+- **`guard` no longer reports a confident green ✅ for checks that validated nothing** — removed hand-rolled `passed=1/total=1` auto-passes in `drift`, `architecture`, `test-spec`, and `security` (empty scan).
+- **Eliminated false positives** that previously masked real drift: tech-stack/env-var "documented but not found" on monorepos, parser-garbage "data entities" (`table`, `index`, `foreign`), the greedy route regex emitting `/api/` + stray backticks, and the test-file path/basename and glob-pattern mismatches ("N documented but not found"). Documented endpoints/tests that genuinely no longer exist are now reported as real drift.
+- **Security scan** anchored to a scanned-file count — an empty scan now warns ("no source files were scanned") instead of reporting a false "no secrets" pass.
+
+## [0.9.11] - 2026-03-18
+
+### Added
+- **`globMatch()` in `shared-ignore.mjs`** — Purpose-built positive file matching with hardcoded `node_modules` exclusion at any depth. Distinct from `buildIgnoreFilter()` (which is for ignore/skip filtering).
+- **6 new tests** — `globMatch` node_modules rejection (2), valid path matching (1), multi-pattern (1), CI detection (1), function load (1). Total tests: 46.
+
+### Fixed
+- **Docs-Diff no longer scans `node_modules` for test files** — `getTestFilesFromPatterns()` now uses `globMatch()` instead of repurposing `buildIgnoreFilter()`. The `**` glob no longer matches through `node_modules/` directories.
+- **CI detection supports enterprise systems** — `calcTestingScore()` now recognizes `buildspec.yml`, `amplify.yml`, `Jenkinsfile`, `.circleci/config.yml`, `.gitlab-ci.yml`, `.travis.yml`, and `turbo.json` with a `"test"` task.
+- **Multi-pattern test resolution works correctly** — `testPatterns` array resolves files from all patterns with proper deduplication via Set.
+
 ## [0.9.10] - 2026-03-18
 
 ### Added — Unified Ignore System & Scorer Alignment
@@ -363,3 +397,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Zero dependencies — pure Node.js
 - GitHub CI workflow (Node 18/20/22 matrix)
 - MIT license
+
+### Fixed
+- Added missing tests for the `watch` CLI command to verify it runs and reacts properly.

{docguard_cli-0.9.10 → docguard_cli-0.10.0}/DRIFT-LOG.md

@@ -9,3 +9,4 @@
 | 2026-03-13 | `cli/commands/generate.mjs` | ARCHITECTURE.md | DRIFT-LOG.md template includes `// DRIFT: reason` as placeholder text. | Info | By design — template content |
 | 2026-03-13 | `cli/commands/agents.mjs` | ARCHITECTURE.md | Agent config generators include `// DRIFT: reason` as instruction text for AI agents. 3 occurrences across Windsurf, Cursor, and generic agent configs. | Info | By design — instruction content |
 | 2026-03-13 | `cli/validators/drift.mjs` | ARCHITECTURE.md | Drift validator references `// DRIFT:` pattern in JSDoc and regex. | Info | By design — validator implementation |
+| 2026-05-12 | `tests/drift.test.mjs` | ARCHITECTURE.md | Drift validator tests use `// DRIFT:` comments to simulate project files having drift comments. | Info | By design — test implementation |

{docguard_cli-0.9.10 → docguard_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.9.10
+Version: 0.10.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
@@ -275,7 +275,7 @@ DocGuard runs **19 automated validators** on every `guard` check:
 | 1 | **Structure** | Required CDD files exist | ✅ On |
 | 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
 | 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
-| 4 | **Drift** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
+| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
 | 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
@@ -291,6 +291,7 @@ DocGuard runs **19 automated validators** on every `guard` check:
 | 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
+| 20 | **API-Surface** | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes); flags documented-but-deleted endpoints | ✅ On |
 
 ---
 
@@ -344,7 +345,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 19 validators |
+| `/docguard.guard` | Run quality validation — check all 20 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.9.10 → docguard_cli-0.10.0}/README.md

@@ -251,7 +251,7 @@ DocGuard runs **19 automated validators** on every `guard` check:
 | 1 | **Structure** | Required CDD files exist | ✅ On |
 | 2 | **Doc Sections** | Canonical docs have required sections | ✅ On |
 | 3 | **Docs-Sync** | Routes/services referenced in docs + OpenAPI cross-check | ✅ On |
-| 4 | **Drift** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
+| 4 | **Drift-Comments** | `// DRIFT:` comments logged in DRIFT-LOG.md | ✅ On |
 | 5 | **Changelog** | CHANGELOG.md has [Unreleased] section | ✅ On |
 | 6 | **Test-Spec** | Tests exist per TEST-SPEC.md rules | ✅ On |
 | 7 | **Environment** | Env vars documented, .env.example exists | ✅ On |
@@ -267,6 +267,7 @@ DocGuard runs **19 automated validators** on every `guard` check:
 | 17 | **TODO-Tracking** | Untracked TODOs/FIXMEs and skipped tests | ✅ On |
 | 18 | **Schema-Sync** | Database models documented in DATA-MODEL.md | ✅ On |
 | 19 | **Spec-Kit** | Spec quality validation (FR-IDs, mandatory sections, phased tasks) | ✅ On |
+| 20 | **API-Surface** | API-REFERENCE.md endpoints match the real API surface (OpenAPI spec / routes); flags documented-but-deleted endpoints | ✅ On |
 
 ---
 
@@ -320,7 +321,7 @@ DocGuard provides AI agent slash commands for integrated workflows. Installed au
 
 | Command | What It Does |
 |:--------|:-------------|
-| `/docguard.guard` | Run quality validation — check all 19 validators |
+| `/docguard.guard` | Run quality validation — check all 20 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.10.0/SUPPLY-CHAIN-AUDIT.md

@@ -0,0 +1,84 @@
+# Supply-Chain Security Audit
+
+> **Purpose:** Recurring read-only audit of this repository for npm/PyPI supply-chain risks.
+> Designed to run unattended in Jules Scheduled Tasks.
+
+## ⚠️ Critical Safety Rule
+
+**Do NOT run** `npm install`, `pip install`, `npm audit fix`, or any state-changing command.
+This is a **read-only** audit.
+
+---
+
+## Audit Phases
+
+### Phase 1: Known-Bad Packages
+
+Scan all lockfiles (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements*.txt`, `poetry.lock`, `pyproject.toml`) for known-malicious packages:
+
+**May 2026 — TanStack/Mini Shai-Hulud (CVE-2026-45321):**
+- `@tanstack/router` 1.121.4–1.121.6
+- `@tanstack/start`, `@tanstack/react-router`, `@tanstack/vue-router`, `@tanstack/solid-router`
+
+**May 2026 — TeamPCP/Mistral:**
+- `@mistralai/mistralai` 1.5.0 (npm) / `mistralai` 2.4.6 (PyPI)
+- `intercom-client` 6.4.0, `@ctrl/tinycolor` 4.2.0
+- `guardrails-ai` 0.10.1, `litellm` 1.82.8, `lightning` 2.6.2–2.6.3
+
+### Phase 2: IOCs on Disk
+
+Search for:
+- Worm loaders: `router_init.js`, `router_runtime.js`, `setup.mjs` in `node_modules/`
+- C2 domains: `filev2.getsession.org`, `git-tanstack.com`, `api.masscan.cloud`, `83.142.209.194`
+- Persistence: `~/Library/LaunchAgents/com.user.gh-token-monitor.plist` (macOS), `~/.config/systemd/user/gh-token-monitor.service` (Linux)
+- Git artifacts: remotes containing `shai-hulud`, commits by `claude <claude@users.noreply.github.com>`
+
+### Phase 3: Slopsquatting
+
+For every direct dependency:
+- Flag packages with <1,000 weekly downloads named like a popular package
+- Flag packages added in AI-authored commits
+- Check for phantom imports (imported but not declared in package.json)
+
+### Phase 4: Freshness Violations
+
+- CRITICAL: package published <48 hours ago
+- HIGH: package published <7 days ago
+- MEDIUM: package published <30 days ago
+- Flag any floating version ranges (`^`, `~`, `>=`, `*`, `latest`)
+
+### Phase 5: Install-Script Exposure
+
+- Check for `preinstall`/`postinstall` hooks in package.json
+- Verify `.npmrc` has `ignore-scripts=true`
+- Count packages with `hasInstallScript` in lockfile
+
+### Phase 6: CI/CD Attack Surface
+
+For each `.github/workflows/*.yml`:
+- `pull_request_target` + checkout of PR code = CRITICAL
+- Third-party actions not pinned to commit SHA = HIGH
+- `secrets.*` exposed in PR workflows = HIGH
+- Missing `permissions:` block = MEDIUM
+
+---
+
+## Output
+
+Save findings to `./reports/SUPPLY-CHAIN-AUDIT-YYYY-MM-DD.md`.
+
+If CRITICAL or HIGH findings exist, open a PR with title:
+`[supply-chain] Audit findings for YYYY-MM-DD`
+
+---
+
+## Remediation
+
+If Phase 1 or 2 hits:
+> ⚠️ DO NOT revoke GitHub tokens first. Remove persistence daemon first, then rotate credentials.
+
+If Phase 4 hits:
+> Pin all versions to exact in package.json. Add `min-release-age=7d` to .npmrc.
+
+If Phase 6 hits:
+> Pin third-party actions to 40-char commit SHA. Replace `pull_request_target` with `pull_request`.

{docguard_cli-0.9.10 → docguard_cli-0.10.0}/cli/commands/diagnose.mjs

@@ -20,20 +20,21 @@ import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 
 // Map validator failures to the right fix --doc target
 const VALIDATOR_TO_DOC = {
-  'Structure':     null,       // structural — needs init, not doc fix
-  'Doc Sections':  null,       // section-level — maps to specific doc
-  'Docs-Sync':     null,       // cross-reference — needs manual review
-  'Drift':         null,       // drift log maintenance
-  'Changelog':     null,       // changelog maintenance
-  'Test-Spec':     'test-spec',
-  'Environment':   'environment',
-  'Security':      'security',
-  'Architecture':  'architecture',
-  'Freshness':     null,       // freshness — maps to stale doc
+  'Structure':       null,       // structural — needs init, not doc fix
+  'Doc Sections':    null,       // section-level — maps to specific doc
+  'Docs-Sync':       null,       // cross-reference — needs manual review
+  'Drift-Comments':  null,       // drift log maintenance
+  'Changelog':       null,       // changelog maintenance
+  'API-Surface':     'api-reference',
+  'Test-Spec':       'test-spec',
+  'Environment':     'environment',
+  'Security':        'security',
+  'Architecture':    'architecture',
+  'Freshness':       null,       // freshness — maps to stale doc
 };
 
 // Actionable fix instructions per validator (LLM-first: includes both skill and CLI commands)
@@ -59,9 +60,16 @@ const FIX_INSTRUCTIONS = {
     description: 'Documentation references are out of sync with code. Review and update component maps.',
     autoFixable: false,
   },
-  'Drift': {
+  'Drift-Comments': {
     action: 'Update DRIFT-LOG.md',
-    description: 'Code deviates from canonical docs without logged reasons. Add DRIFT entries or update the canonical docs.',
+    description: 'A // DRIFT: code comment has no matching DRIFT-LOG.md entry. Add the entry or remove the comment.',
+    autoFixable: false,
+  },
+  'API-Surface': {
+    action: 'Reconcile API-REFERENCE.md with the actual API surface',
+    command: 'docguard fix --doc api-reference',
+    llmCommand: '/docguard.fix --doc api-reference',
+    description: 'docs-canonical/API-REFERENCE.md documents endpoints that no longer exist in code (or omits real ones). Remove deleted endpoints and add missing ones to match the OpenAPI spec / route definitions, then log the change in CHANGELOG.md and DRIFT-LOG.md.',
     autoFixable: false,
   },
   'Changelog': {
@@ -127,7 +135,7 @@ export function runDiagnose(projectDir, config, flags) {
       // Run init to create missing files
       try {
         const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
-        execSync(`node "${cliPath}" init --dir "${projectDir}"`, {
+        execFileSync(process.execPath, [cliPath, 'init', '--dir', projectDir], {
           encoding: 'utf-8',
           stdio: 'pipe',
         });
@@ -136,7 +144,7 @@ export function runDiagnose(projectDir, config, flags) {
       // Run generate to fill in MISSING content only (never --force, which would overwrite existing docs)
       try {
         const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'docguard.mjs');
-        execSync(`node "${cliPath}" generate --dir "${projectDir}"`, {
+        execFileSync(process.execPath, [cliPath, 'generate', '--dir', projectDir], {
           encoding: 'utf-8',
           stdio: 'pipe',
         });