docguard-cli 0.30.0__tar.gz → 0.30.1__tar.gz

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.github/workflows/ci.yml

@@ -12,10 +12,15 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18, 20, 22]
+        # 24 ships npm 11 — keep it in the matrix so `npm ci` exercises the newer
+        # npm that older Nodes (18/20/22 → npm 10) do NOT. This is what catches
+        # config/install incompatibilities that npm 10 silently accepts but npm 11
+        # treats as fatal (e.g. bug-198: `.npmrc` min-release-age broke the Glama
+        # build on npm 11 while all local/CI installs passed). Do not drop 24.
+        node-version: [18, 20, 22, 24]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # Full git history for freshness validator
 
@@ -97,7 +102,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/v')
     needs: test
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-node@v6
         with:
           node-version: 20

docguard_cli-0.30.1/.github/workflows/jules-triage.yml

@@ -0,0 +1,85 @@
+name: Jules PR Triage
+
+# Auto-triage PRs opened by the Google Jules agents (Sentinel/Bolt/Palette).
+# Keeps Jules ON (it stays useful for genuinely-new work) while automatically
+# clearing the duplicate/already-resolved noise it tends to produce, and giving
+# it per-PR feedback (a comment mentioning @jules) so it learns.
+#
+# SECURITY: uses pull_request_target (needs write to comment/close/label on the
+# PR), but reads only PR METADATA (title, author) via the API and NEVER checks
+# out or runs the PR's code — so the elevated token is never exposed to
+# PR-controlled content. (Matches the AGENTS.md CI rule.)
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  pull-requests: write
+  issues: write
+  contents: read
+
+jobs:
+  triage:
+    # Only act on the Jules bot's PRs; everything else is untouched.
+    if: github.event.pull_request.user.login == 'google-labs-jules[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Triage the Jules PR
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const num = pr.number;
+            const title = pr.title || '';
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            // Known-noise classes for THIS repo (see .jules/*.md RESOLVED markers).
+            const NOISE = [
+              /command injection|exec(File)?Sync/i,                                   // Sentinel — fixed v0.21.1 + #296
+              /performance|optimi[sz]e|precompute|pre-?compile|O\(N|single-pass|\bset\b.*comparison|tolowercase|basenames?/i, // Bolt — applied + refactored
+              /no (web )?ui|no changes? (needed|required)|no ux|no-op/i,               // Palette — no UI in this repo
+            ];
+            const isNoise = NOISE.some((re) => re.test(title));
+
+            // Duplicate detection: another OPEN Jules PR with an equivalent title.
+            const norm = (s) => (s || '')
+              .toLowerCase()
+              .replace(/[^a-z0-9]+/g, ' ')
+              .replace(/\b(sentinel|bolt|palette|critical|high|medium|low|fix|the|a|an|via|in|of|for|to|and)\b/g, ' ')
+              .replace(/\s+/g, ' ')
+              .trim();
+            const mine = norm(title);
+            const { data: open } = await github.rest.pulls.list({ owner, repo, state: 'open', per_page: 100 });
+            const dup = mine && open.find((p) => p.number !== num && norm(p.title) === mine);
+
+            const addLabel = async (name) => {
+              try {
+                await github.rest.issues.addLabels({ owner, repo, issue_number: num, labels: [name] });
+              } catch (e) { core.info(`label "${name}" skipped: ${e.message}`); }
+            };
+
+            if (isNoise || dup) {
+              const reason = dup
+                ? `a duplicate of #${dup.number}`
+                : 'a class already resolved or not applicable in this repo';
+              await github.rest.issues.createComment({
+                owner, repo, issue_number: num,
+                body:
+                  `🤖 **Auto-triaged as stale** — ${reason}.\n\n` +
+                  `@jules please stop opening PRs for this topic: it is covered by the RESOLVED markers in \`.jules/sentinel.md\` / \`.jules/bolt.md\` / \`.jules/palette.md\` and the **Automated agents** rule in \`AGENTS.md\` (search open **and** closed PRs first; never duplicate; only open a new PR for a genuinely-new finding with evidence — an exploit/failing test for security, or a >20% real-workload benchmark for performance). Closing to keep the queue clean.`,
+              });
+              await addLabel('jules-autoclosed');
+              await github.rest.pulls.update({ owner, repo, pull_number: num, state: 'closed' });
+              core.notice(`Closed #${num} (${reason}).`);
+            } else {
+              await addLabel('jules-review');
+              await github.rest.issues.createComment({
+                owner, repo, issue_number: num,
+                body:
+                  `🔎 **Flagged for human review** — this looks like a *new, non-duplicate* change from @jules. ` +
+                  `A maintainer should verify it against \`docguard guard\` + the test suite before merge.`,
+              });
+              core.notice(`#${num} flagged for human review.`);
+            }

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
       version: ${{ steps.check.outputs.version }}
       changed: ${{ steps.check.outputs.changed }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 1 # only need HEAD's package.json; the tag check hits the remote
 
@@ -52,9 +52,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [18, 20, 22]
+        # 24 = npm 11 coverage (18/20/22 ship npm 10). Gates releases on the
+        # newer npm so a version-incompatible .npmrc / install can't ship (bug-198).
+        node-version: [18, 20, 22, 24]
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
       - uses: actions/setup-node@v6
@@ -75,7 +77,7 @@ jobs:
     outputs:
       tag: v${{ needs.detect-version.outputs.version }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # Fetch all history + tags for reliable tag detection
 
@@ -132,7 +134,7 @@ jobs:
     needs: [detect-version, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Build extension ZIP
         run: |
@@ -157,7 +159,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-node@v6
         with:
           node-version: 20
@@ -173,7 +175,7 @@ jobs:
     needs: [detect-version, test, create-release]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
       - uses: actions/setup-python@v6
         with:
           python-version: '3.12'
@@ -215,7 +217,7 @@ jobs:
       issues: write # reminder issue in THIS repo only — never github/spec-kit
     steps:
       - name: Checkout docguard repo
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Get version and metadata
         id: meta

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.github/workflows/sync-speckit-catalog.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Checkout docguard repo
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Get version and metadata
         id: meta

docguard_cli-0.30.1/.jules/bolt.md

@@ -0,0 +1,24 @@
+# Bolt — performance learnings
+
+> ⛔ **STOP / DO-NOT-DUPLICATE.** Before opening ANY PR, search existing **open
+> AND closed** PRs. Dozens of duplicate "optimize diffTests / Set cross-compare
+> / precompute toLowerCase / pre-compile RegExp" PRs were closed as noise.
+> **Do NOT open another micro-optimization PR** unless you include a **benchmark
+> showing >20% wall-clock improvement on a realistic workload** (a real repo,
+> not a synthetic loop). A theoretical Big-O note is NOT sufficient justification.
+
+## ✅ APPLIED / EVALUATED — the recurring diff & scan optimizations (do NOT re-open)
+
+The learnings below have already been applied where they helped, and the
+affected code (`cli/commands/diff.mjs`, `cli/validators/*`, the scanners) was
+substantially **refactored in v0.29–v0.30** — PRs written against the old shape
+no longer apply and just create merge noise.
+
+- **Early-return in `checkUntrackedTodos`** — already in place.
+- **Precompute `.toLowerCase()` / `.substring()` outside loops** — applied where
+  it mattered; the remaining cases are not hot paths.
+- **Pre-compile `RegExp` outside nested loops** — applied in the scanners.
+
+These are recorded as historical context, **not** as standing mandates to
+re-scan for on every run. The DocGuard test suite (898 tests) and CI already
+guard against regressions here.

docguard_cli-0.30.1/.jules/palette.md

@@ -0,0 +1,11 @@
+# Palette — UX learnings
+
+> ⛔ **STOP.** This repository has **no user-facing UI**: it is a Node.js CLI
+> plus config/docs. There is **no web frontend** (no HTML/CSS/React/Vue) and
+> **no VS Code extension** (it was removed). Palette therefore has nothing to
+> act on here. **Do NOT open UX PRs** — the past "No web UI components" /
+> "No changes required" no-op PRs were closed as noise. Skip this repo.
+
+Historical note: earlier learnings referenced a VS Code extension (status-bar
+tooltips, loading spinners). That extension no longer exists in this repo, so
+those notes are obsolete and must not be acted on.

docguard_cli-0.30.1/.jules/sentinel.md

@@ -0,0 +1,24 @@
+# Sentinel — security learnings
+
+> ⛔ **STOP / DO-NOT-DUPLICATE.** Before opening ANY PR, search existing **open
+> AND closed** PRs and issues. If the topic below is already covered, do NOT
+> open another PR — dozens of duplicate command-injection PRs were closed as
+> noise. Only open a PR for a **new, unaddressed** finding, with a concrete
+> exploit path or failing test as evidence.
+
+## ✅ RESOLVED — Command Injection via execSync (do NOT re-open)
+
+**Status: FIXED and CLOSED. Do not open further PRs about `execSync` / command injection.**
+
+- The real vulnerability (issue #190) was fixed in **v0.21.1** by switching the
+  `specify`-spawning path to `execFileSync` (arguments as an array — no shell
+  interpolation).
+- The last shell-interpolated `execSync` (dead code in `setup.mjs`'s unused
+  `isCliAvailable`) was removed in **PR #296**.
+- Every remaining `execSync` in `cli/` uses a **static string literal**
+  (`git rev-parse …`, `git rev-list --count HEAD`, `git log … | wc -l`) with
+  **no variable interpolation** — not injectable. Leave them as-is; do not "fix" them.
+
+Historical note (kept for context, not for re-application): interpolating
+`projectDir`/`filePath` into a shell string allowed `;`/`&&`/`||` injection;
+`execFileSync` with an args array prevents it. Lesson recorded — already applied.

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.jules-setup.sh

@@ -19,9 +19,12 @@ export OPENAI_API_KEY="dummy-openai-key"
 # 2. Ecosystem-Specific Dependency Installation
 # ------------------------------------------
 echo "📦 === Installing Dependencies ==="
-# Note: DocGuard has zero production dependencies, but we run npm install
-# in case devDependencies are added in the future.
-npm install
+# DocGuard has one exact-pinned runtime dep (@babel/parser). Use `npm ci`, NOT
+# `npm install`: `npm ci` installs strictly from package-lock.json and never
+# rewrites it, so it leaves the working tree clean. `npm install` can re-resolve
+# and rewrite package-lock.json, which dirties the tree and makes Jules abort
+# with "Working tree is dirty" after setup.
+npm ci
 
 # ------------------------------------------
 # 3. Ecosystem-Specific Tests & Build Checks
@@ -31,11 +34,21 @@ echo "🧪 === Running Initial Test & Validation ==="
 npm test || echo "⚠️ Tests failed, but continuing..."
 
 echo "🏗️ === Verifying Build Integrity ==="
-# Test the primary CLI entrypoint to ensure it is executable
+# Test the primary CLI entrypoint to ensure it is executable.
+# Note: `--version` triggers ensureSkills, which regenerates the tracked
+# `.agent/skills/*.md` files (their `version:` frontmatter tracks the release),
+# so the tree is expected to be dirty right after this — the reset below
+# discards that regeneration.
 node cli/docguard.mjs --version
 
 echo "🧹 === Enforcing Git Tree Integrity ==="
-# Jules requires the working directory to be clean after this script runs
+# Jules requires the working directory to be clean after this script runs, and
+# ignores any changes setup makes. `git clean -fd` alone is INSUFFICIENT — it
+# only removes UNTRACKED files, but our churn is in TRACKED files (regenerated
+# .agent/skills). Hard-reset discards tracked modifications; clean -fd sweeps
+# any stray untracked files. `-fd` respects .gitignore, so node_modules (which
+# we just installed) is preserved.
+git reset --hard HEAD
 git clean -fd || true
 
 echo "✅ Jules VM Local Environment is Ready!"

docguard_cli-0.30.1/.npmrc

@@ -0,0 +1,13 @@
+# Supply-Chain Security Hardening
+# Applied: 2026-05-14T14:19:27Z
+# ignore-scripts: never run a dependency's install/postinstall scripts (the main
+#   supply-chain attack vector). Universally supported across npm versions.
+# audit-level: surface moderate-and-above advisories.
+#
+# NOTE: `min-release-age=7d` was removed 2026-07-06 — newer npm (Node 22+/npm 11+,
+# as used by the Glama MCP build image) rejects the "7d" value ("must be numeric")
+# and HARD-FAILS `npm install` in clean environments (Glama, CI, fresh clones).
+# DocGuard's single runtime dependency is exact-pinned, so the maturity window
+# added little; the exact pin + ignore-scripts + audit-level remain the controls.
+ignore-scripts=true
+audit-level=moderate

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.wolf/anatomy.md

@@ -1,7 +1,7 @@
 # anatomy.md
 
-> Auto-maintained by OpenWolf. Last scanned: 2026-07-05T16:10:27.214Z
-> Files: 662 tracked | Anatomy hits: 0 | Misses: 0
+> Auto-maintained by OpenWolf. Last scanned: 2026-07-06T14:46:58.012Z
+> Files: 670 tracked | Anatomy hits: 0 | Misses: 0
 
 ## ../../../../../../../tmp/
 
@@ -17,12 +17,12 @@
 - `.docguardignore` — # Python distribution artifacts (~199 tok)
 - `.DS_Store` (~3818 tok)
 - `.gitignore` — Git ignore rules (~167 tok)
-- `.jules-setup.sh` — Google Jules Environment Startup Script (~429 tok)
+- `.jules-setup.sh` — ========================================== (~631 tok)
 - `.npmignore` — Development (~76 tok)
 - `.npmrc` — Supply-Chain Security Hardening (~59 tok)
 - `.pre-commit-hooks.yaml` — DocGuard hooks for the pre-commit framework (https://pre-commit.com). (~490 tok)
 - `action.yml` — Declares fs (~7591 tok)
-- `AGENTS.md` — AI Agent Instructions — DocGuard (~1584 tok)
+- `AGENTS.md` — AI Agent Instructions — DocGuard (~1827 tok)
 - `CHANGELOG.md` — Changelog (~45081 tok)
 - `CLAUDE.md` — OpenWolf (~57 tok)
 - `CODE_OF_CONDUCT.md` — Contributor Covenant Code of Conduct (~532 tok)
@@ -32,6 +32,7 @@
 - `docguard-cli-0.23.0.tgz` (~81238 tok)
 - `Dockerfile` — Docker container definition (~204 tok)
 - `DRIFT-LOG.md` — Drift Log (~802 tok)
+- `glama.json` (~29 tok)
 - `LICENSE` — Project license (~286 tok)
 - `package-lock.json` — npm lock file (~617 tok)
 - `package.json` — Node.js package manifest (~459 tok)
@@ -39,7 +40,7 @@
 - `pr_description.md` (~260 tok)
 - `pyproject.toml` — The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project (~358 tok)
 - `README.es.md` — 🛡️ DocGuard (~1098 tok)
-- `README.md` — Project documentation (~8376 tok)
+- `README.md` — Project documentation (~8436 tok)
 - `README.pt-BR.md` — 🛡️ DocGuard (~1075 tok)
 - `ROADMAP.md` — DocGuard Roadmap (~2432 tok)
 - `SECURITY.md` — Security Policy (~357 tok)
@@ -950,14 +951,22 @@
 
 ## .github/workflows/
 
-- `release.yml` — CI: Auto Release — Tag, GitHub Release, npm, PyPI (~3386 tok)
+- `ci.yml` — CI: DocGuard CI (~1041 tok)
+- `release.yml` — CI: Auto Release — Tag, GitHub Release, npm, PyPI (~3434 tok)
 - `sync-speckit-catalog.yml` — CI: Prepare Spec Kit Catalog Submission (Manual) (~1385 tok)
 
+## .jules/
+
+- `bolt.md` — Bolt — performance learnings (~333 tok)
+- `palette.md` — Palette — UX learnings (~153 tok)
+- `sentinel.md` — Sentinel — security learnings (~329 tok)
+
 ## cli/
 
 - `config.mjs` — DocGuard — configuration loading. (~3265 tok)
 - `docguard.mjs` — DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD) (~9606 tok)
 - `findings.mjs` — Findings — the structured, LLM-addressable result unit (v0.27). (~9698 tok)
+- `shared-git.mjs` — Shared Git Utilities — single source of truth for `git log` plumbing (~1851 tok)
 - `shared-ignore.mjs` — Shared Ignore Utility — Unified file filtering for all validators. (~4132 tok)
 - `shared-source.mjs` — Shared Source Resolution — Monorepo-aware source discovery. (~4655 tok)
 - `shared.mjs` — Shared constants for DocGuard CLI — colors, profiles, version. (~3496 tok)
@@ -973,9 +982,10 @@
 - `guard.mjs` — Guard Command — Validate project against its canonical documentation (~11608 tok)
 - `init.mjs` — Init Command — Initialize CDD documentation from templates (~7278 tok)
 - `llms.mjs` — llms Command — Generate llms.txt from canonical documentation (~2137 tok)
-- `mcp.mjs` — MCP Command — DocGuard as a Model Context Protocol server (stdio). (~2902 tok)
+- `mcp.mjs` — MCP Command — DocGuard as a Model Context Protocol server (stdio). (~3098 tok)
 - `memory.mjs` — Memory Command — v0.17-P2. (~2957 tok)
-- `score.mjs` — Score Command — Calculate CDD maturity score (0-100) (~12136 tok)
+- `score.mjs` — Score Command — Calculate CDD maturity score (0-100) (~12221 tok)
+- `setup.mjs` — Setup Command — Interactive onboarding wizard for DocGuard (~5280 tok)
 - `sync-tests.mjs` — `docguard sync --tests` — reconcile the TEST-SPEC Source-to-Test Map from disk. (~3191 tok)
 - `sync.mjs` — Sync Command — keep the documentation memory ALWAYS UP TO DATE. (~2371 tok)
 - `trace.mjs` — Trace Command — Generate a requirements traceability matrix (~7746 tok)
@@ -1025,7 +1035,7 @@
 
 ## docs-canonical/
 
-- `ARCHITECTURE.md` — Architecture (~2967 tok)
+- `ARCHITECTURE.md` — Architecture (~3029 tok)
 - `DATA-MODEL.md` — Data Model (~1668 tok)
 - `REQUIREMENTS.md` — Requirements (~673 tok)
 - `SURFACE-AUDIT.md` — DocGuard Surface Audit (~5703 tok)
@@ -1083,6 +1093,7 @@
 - `field-report-3-deferred.test.mjs` — v0.28 — the detection-gap items deferred from LLM field report #3. (~3122 tok)
 - `field-report-3.test.mjs` — v0.27 — LLM field report #3. (~3315 tok)
 - `freshness.test.mjs` — runGit: commitOldCode (~3536 tok)
+- `hooks.test.mjs` — Declares afterFirst (~2420 tok)
 - `instruction-audit.test.mjs` — Instruction Audit scanner tests (field report #11 — MemoryLint-inspired). (~2387 tok)
 - `inventory.test.mjs` — Declares make (~1048 tok)
 - `llms-full-pack.test.mjs` — CLI: run (~1304 tok)

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.wolf/buglog.json

@@ -3203,6 +3203,97 @@
       "related_bugs": [],
       "occurrences": 2,
       "last_seen": "2026-07-03T21:55:57.551Z"
+    },
+    {
+      "id": "bug-196",
+      "timestamp": "2026-07-05T00:00:00.000Z",
+      "error_message": "awesome-mcp-servers PR #9185 added a line containing the literal word 'undefined' to README instead of the DocGuard entry; bot flagged missing-glama, gh pr diff showed '+undefined', grep found no 'docguard'",
+      "file": "(scratchpad node -e insertion script; result pushed to raccioly/awesome-mcp-servers add-docguard)",
+      "root_cause": "Shell env-var vs argv error: `node -e \"...process.env.LINE...\" LINE=\"$LINE\"` passes LINE as a positional ARGV to node, NOT as an environment variable (env assignments must precede the command: `LINE=\"$LINE\" node -e`). So process.env.LINE was undefined and the script inserted the literal string 'undefined'. The invocation exited 0, so the `|| fallback` never ran, and it was committed+pushed unverified.",
+      "fix": "Rebuilt the branch: gh repo sync the fork to upstream, fresh clone, wrote the entry to a FILE (/tmp/dg-entry.txt) and inserted via a python heredoc (no shell-var interpolation), VERIFIED with grep for both the entry and the badge before committing, then force-pushed to the same PR branch (repairs the PR in place — keeps #9185, its thread, history). Lesson: for env→node, put the assignment before the command; and ALWAYS grep-verify a generated file insertion before commit+push.",
+      "tags": [
+        "shell",
+        "env-var",
+        "node",
+        "awesome-mcp-servers",
+        "distribution",
+        "verify-before-push"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-05T00:00:00.000Z"
+    },
+    {
+      "id": "bug-197",
+      "timestamp": "2026-07-06T00:51:03.784Z",
+      "error_message": "Incorrect value in code",
+      "file": "cli/commands/setup.mjs",
+      "root_cause": "Had 'node:child_process'",
+      "fix": "Changed to '../shared.mjs'",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-06T00:51:03.784Z"
+    },
+    {
+      "id": "bug-198",
+      "timestamp": "2026-07-06T01:30:00.000Z",
+      "error_message": "npm install fails on newer npm (Node 22+/npm 11, Glama MCP build image): 'invalid config min-release-age=\"7d\" ... Must be one of: null, numeric value' -> exit 1. Glama Docker build for the MCP server listing failed at RUN npm install.",
+      "file": ".npmrc",
+      "root_cause": "The committed .npmrc set min-release-age=7d (supply-chain hardening). npm 10.x (local dev) accepts the '7d' duration string, but npm 11+ requires a NUMERIC value and treats the invalid config as fatal, so npm install exits 1 in any clean environment on modern npm (Glama build, CI, fresh contributor clones).",
+      "fix": "Removed min-release-age from .npmrc; kept ignore-scripts=true + audit-level=moderate (universally valid). The one runtime dep is exact-pinned so the maturity window added little. Verified a fresh `git archive | npm install` exits 0. Glama re-Build now succeeds against latest main.",
+      "tags": [
+        "npmrc",
+        "npm",
+        "supply-chain",
+        "build",
+        "glama",
+        "docker",
+        "cross-version"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-06T01:30:00.000Z"
+    },
+    {
+      "id": "bug-199",
+      "timestamp": "2026-07-06T01:44:39.966Z",
+      "error_message": "Missing error handling in unknown",
+      "file": ".github/workflows/ci.yml",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "yml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-06T01:44:39.966Z"
+    },
+    {
+      "id": "bug-200",
+      "timestamp": "2026-07-06T14:40:55.317Z",
+      "error_message": "ENOTDIR: not a directory, open '/dev/null/pre-commit' — docguard hooks / init --with hooks crashes when git core.hooksPath is /dev/null (Google Jules sandbox VM sets this; also any user who disables hooks that way)",
+      "file": "cli/shared-git.mjs",
+      "root_cause": "getHooksDir() ran `git rev-parse --git-path hooks`, which returns the literal '/dev/null' when core.hooksPath=/dev/null. The code did `if (out) return resolve(dir, out)` — resolving '/dev/null' verbatim as the hooks dir. Callers then wrote `<hooksDir>/pre-commit` = '/dev/null/pre-commit', which is ENOTDIR because /dev/null is a device file, not a directory.",
+      "fix": "Guard the /dev/null pseudo-path: `if (out && out !== '/dev/null') return resolve(dir, out)`. When core.hooksPath is /dev/null we fall through to the existing `.git/hooks` directory check, so hook install/list works normally. Added a regression test in tests/hooks.test.mjs (real git repo + `git config core.hooksPath /dev/null`) asserting getHooksDir falls back to .git/hooks and runHooks writes the hook without ENOTDIR. Independently found by Google Jules (PR #307) — adopted the fix cleanly without the PR's auto-generated .agent/skills noise.",
+      "tags": [
+        "hooks",
+        "git",
+        "dev-null",
+        "core.hooksPath",
+        "ENOTDIR",
+        "jules",
+        "shared-git"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-07-06T14:40:55.317Z"
     }
   ]
 }

{docguard_cli-0.30.0 → docguard_cli-0.30.1}/.wolf/cerebrum.md

@@ -36,6 +36,7 @@
 - **Findings migration 24/24 COMPLETE + generate split (2026-07-03, "nothing left behind" batch):** CODES registry = 91 codes / 21 prefixes (STR,CHG,MET,FRS,ENV,TSP,DRF,DSY,DDF,DCV,MDS,TRC,TDO,SCH,ARC,CSY,SPK,XRF,GST,SSY,API,DQ + SEC). Executed via 4 parallel subagents on DISJOINT validator files with findings.mjs (the shared CODES file) reserved to the orchestrator — zero edit collisions; each agent returned code definitions as JSON for central append. Gotchas encoded: (1) several tests strict-deepEqual whole result objects on N/A/early-return paths — those paths must keep the LITERAL legacy shape (no findings/fixes keys); real validation paths return via resultFromFindings. (2) spec-kit's validator file is a re-export SHIM — the implementation (and migration) lives in cli/scanners/speckit.mjs. (3) `generateFromSpecKit` in speckit.mjs has a `results.errors.push` that is NOT a validator contract (generator result {generated,skipped,errors}) — do not "migrate" it. (4) api-surface/doc-quality were fully legacy despite the "partial" label in the review. (5) freshness keeps its array-of-{status,code,doc,message} contract; guard's adapter builds the findings (FRS001–005). generate.mjs split: 1530→559 + writers/generate-io.mjs (142) + writers/doc-generators.mjs (853), pure code motion, generateERDiagram import moved with generateDataModel. Watch-test flake root cause was a fixed 2s poll cap vs CLI startup — fixed with a 15s waitFor deadline, NOT retries. Full suite 835/835 after everything.
 - **v0.29 consolidation executed (2026-07-03):** the review's P0/P1 items are DONE, not pending. `shared-ignore.mjs` now owns the ONE recursive walker (`walkFiles(dir, cb, {ignoreDirs, keepDot, skipDotEntries, onError})` — returns a completeness boolean) and the ONE anchored glob compiler (`compileGlob`: `**\/`, `**`, `*`, `?`, `{a,b}`; `globMatch` and `countGlobFiles` build on it). 16 call sites migrated as thin wrappers preserving exact semantics (13 validators + guard coverage + diff + generate); ignore-side `globToRegex` deliberately left separate (unanchored substring contract, own bug history). `countGlobFiles` returns -1 on incomplete walks (fail-safe; bug-147). Findings tranche 2: structure/doc-sections (STR001–003), changelog (CHG001–003), metrics-consistency (MET001–002) → 7 of 24 validators on findings; messages kept byte-identical so tests pass unchanged (one strict deepEqual updated to expect the additive `findings: []`). CONTRIBUTING now carries the surface rule + findings rule. Full suite 835/835 including the 20 AST tests.
 - **Project-review findings (2026-07-02 sweep — durable facts for future work):** (1) DUPLICATION MAP: three glob→regex implementations exist (`shared-ignore.mjs:155` globToRegex, `shared-ignore.mjs:224` globToMatchRegex, `metrics-consistency.mjs` globToRegExp/countGlob — the third added 2026-06-23 for collections; consolidation candidate) and ~13 validators each carry their own recursive dir-walker + local IGNORE_DIRS copy — a shared `walkFiles` in shared-ignore.mjs is the fix. (2) FINDINGS MIGRATION: only security.mjs fully emits `Finding[]`; api-surface + doc-quality partial; ~20 validators still legacy strings — guard's rich rendering (suggestions/codes/confidence) only benefits 3 validators. (3) `docs-canonical/SURFACE-AUDIT.md` is a HISTORICAL point-in-time audit (2026-05-26, v0.18.1); its recommendations SHIPPED (canonical-sync in v0.19, consolidation in v0.20) — do NOT treat its counts as current truth; README counts are machine-governed by Canonical-Sync since v0.19. It needs a "historical — resolved" banner. (4) STANDARD.md §8 lists 8 validators vs 24 actually run — stale spec section. (5) Size hotspots: generate.mjs 1551 lines, score.mjs 1063, fix.mjs 835, guard.mjs 829 (guard's separation judged reasonable; generate is the split candidate). (6) Packaging/CI is clean: 1 pinned dep (@babel/parser, graceful regex fallback via astTierAvailable), clean tarball, node 18/20/22 matrix, versions auto-synced npm→PyPI; only blemishes are pyproject.toml:8 "Zero dependencies" wording and tracked scratch files test-draft.js/test-metrics.js at root.
+- **Google Jules sandbox VM specifics (2026-07-06, bug-200).** (1) The Jules VM sets `git config core.hooksPath /dev/null` to disable hooks. Any code that resolves the git hooks dir via `git rev-parse --git-path hooks` gets back the literal `/dev/null`; `resolve(dir,'/dev/null')` + `<hooksDir>/pre-commit` = `ENOTDIR`. `getHooksDir` (shared-git.mjs) now guards `out !== '/dev/null'` and falls through to the `.git/hooks` check. Regression test lives in tests/hooks.test.mjs (real repo + `git config core.hooksPath /dev/null`). (2) `.jules-setup.sh` (pasted into Jules dashboard → Repo → Configuration → Initial Setup) MUST leave the working tree clean or Jules aborts "Working tree is dirty" AFTER setup. Two traps: `npm install` re-resolves and rewrites package-lock.json → use `npm ci`; and `docguard --version` runs ensureSkills which regenerates the **tracked** `.agent/skills/*.md` (version-frontmatter churn), so `git clean -fd` (untracked-only) is INSUFFICIENT — end the script with `git reset --hard HEAD && git clean -fd` (`-fd` respects .gitignore so node_modules survives). (3) `.agent/skills/*.md` being tracked-yet-regenerated is the root cause of BOTH the dirty-tree failures and the recurring Jules-PR `.agent` noise — a future option is to gitignore + `git rm --cached` them, but the setup-script reset handles the symptom robustly.
 - **Doc-home resolution is now ONE source of truth: `resolveDocDirs(projectDir, config)` in shared.mjs (Unreleased).** Both the claim scanner (`metrics-consistency.findMarkdownFiles`) and guard's coverage map call it, so "tracked" provably means "actually scanned" — previously the two used different hardcoded dir lists and could disagree (a `docs-implementation/` file showed "tracked" but wasn't scanned). It auto-detects conventional doc-home NAMES that exist (`DEFAULT_DOC_DIRS`: docs/doc/documentation/guides/guide/handbook/manual/wiki/docs-canonical/docs-implementation/extensions + Docusaurus `website/docs`); `config.docs.dirs` EXTENDS (never replaces) that set; `.docguardignore` is how you EXCLUDE a conventional dir. KEY DISTINCTION (reconciles with the wu-whatsappinbox scoping fix): auto-tracking a folder literally named `documentation/` is NOT the same as the arbitrary-subdir walk that was removed — `security/wolf-archive/**/memory.md` is still never scanned. The existing test only asserted arbitrary-subdir exclusion + CONFIGURED-doc inclusion; nothing asserted an unconfigured `documentation/` must be ignored, so auto-detection is consistent with intent, not a reversal.
 
 ## Do-Not-Repeat
@@ -66,6 +67,10 @@
 
 ## Decision Log
 
+- **2026-07-06 (Jules PR triage policy — established)** — How to handle the Google Jules bot's auto-PRs, applied to a batch of 5 (#299 #300 #305 #306 #307). Rule: judge each on merit against the persona's own evidence bar, adopt real fixes CLEANLY (re-apply in our own commit without Jules's auto-generated `.agent/skills` churn), close the rest with a specific technical reason so the bot/human learns the bar. Verdicts recorded: (a) **#307 hooks /dev/null fix = genuinely correct** (one-line getHooksDir guard + a reproducing test) → adopted cleanly in #308, closed as superseded. (b) **#300 "CRITICAL command injection" = FALSE positive** — every flagged `execSync` target is a static string literal (`which specify`, `git log --since=...`) with no user-input interpolation, so no injection surface; also on a stale base (setup.mjs isCliAvailable already removed in #296). Closed — but harvested the ONE real nugget (score.mjs `git log | wc -l` shell pipe → `execFileSync`, Windows-portable). (c) **#299 Bolt regex hoisting = no benchmark, negative-value** — `new RegExp()` runs once per file (O(files)), never inside the match loop, so the claimed "O(N·M) bottleneck" is fiction; hoisting to a shared stateful `g`-regex + manual `.lastIndex=0` is a footgun for zero measured gain. Closed per Bolt's own ">20% measured benchmark" rule. (d) **#305/#306 = +0/-0 status reports** ("babel up to date", "no flaky tests") — well-behaved (no spurious diff) but shouldn't be PRs; closed with thanks. Meta-lesson: the persona files (.jules/*.md) + AGENTS.md bot rules + the jules-triage.yml workflow set the bar; enforcing it consistently in close-comments is what actually trains the bot down from duplicate-PR floods. Two of five carried real value — Jules is worth keeping, not silencing.
+- **2026-07-05 (distribution flywheel — v0.30.0)** — Executed the full external-distribution push. Durable facts: (1) **Official MCP Registry** publish needs THREE things aligned: `server.json` at repo root (2025-12-11 camelCase schema, name `io.github.raccioly/docguard`), `mcpName` in the PUBLISHED npm package (registry validates the referenced package carries it — so a release must SHIP after adding mcpName; adding it to main isn't enough), and `mcp-publisher login github && mcp-publisher publish` run FROM THE REPO ROLE on the user's Mac (I can't run it — sandbox ≠ their terminal; their GitHub device-auth token is local). Registry is IMMUTABLE per version → "400 duplicate version" means it ALREADY published (success, not failure). Verify via `curl https://registry.modelcontextprotocol.io/v0/servers?search=docguard`. (2) **Glama** listing: submitted via their web form (browser); the quality Score has code-fixable items — `glama.json` (root, `{$schema, maintainers:[gh-user]}`) fixes "No glama.json"; read-only MCP tool `annotations` (readOnlyHint/openWorldHint:false) + `title` serve the tool-def-quality/safety scans; a `Dockerfile` running `docguard mcp` enables their build-based "Glama release" (the big score driver, but the Make-Release clicks are the user's). (3) **awesome-mcp-servers** requires the server live on Glama first (bot label missing-glama→has-glama on re-check after a `synchronize`/force-push); entry format = `[owner/repo](url) [![badge](glama .../badges/score.svg)](glama url) 📇 🏠 🍎 🪟 🐧 - desc \`npx cmd\`` (badge AFTER repo link per file convention, NOT after description as the bot template says). (4) **Homebrew tap**: separate public repo `raccioly/homebrew-tap` with `Formula/docguard.rb`; formula url = npm tarball, sha256 must be recomputed per version (`curl -sL <tgz>|shasum -a256`). Bump the tap formula each release. (5) **spec-kit catalog**: one OPEN submission issue at a time (latest version), close superseded ones — established pattern. (6) **PATH shadowing gotcha**: a stale `npm i -g docguard-cli` shadows Homebrew's copy; `docguard --version` shows the FIRST-in-PATH one → `npm i -g docguard-cli@latest` to reconcile.
+
+
 - **2026-07-03 (competitive scan, post-v0.29)** — Spec-kit catalog now 200+ extensions, ~45 doc/validation-adjacent; presentation is alphabetical with NO ranking — the description field + linked README are the only differentiation. Most entries are thin prompt-packs (SKILL.md workflows); DocGuard is one of few with a real engine (CLI, tests, npm/PyPI, MCP, SARIF, Action). Direct drift-competitors in-catalog: Spec Sync (bgervin), Reconcile (stn1slv), CI Guard (Quratulain-bilal), Coding Standards Drift Control, Golden Demo (behavioral drift), Retrospective (per-feature adherence scoring). IDEAS WORTH ADOPTING: (1) phantom-completion detection à la Verify Tasks ([X] in tasks.md with no implementation evidence — deterministic, fits spec-kit validator); (2) MemoryLint-style agent-instruction drift audit (contradictory/redundant rules WITHIN AGENTS.md/CLAUDE.md — fits extractor+LLM-judgment pattern); (3) per-feature spec-adherence scoring (Retrospective); (4) reviewer TLDR briefing (partially covered by Action pr-comment); (5) we already HAVE Mermaid ER generation (generateERDiagram) but never market it — surface in README. Outside competition unchanged: Mintlify llms.txt-at-scale and Swimm MCP matched by v0.29; hackathon-stage "DriftGuard" clones validate the direction. Catalog description should lead with MCP+SARIF+standalone engine — edit release.yml sync-catalog prefill for future releases; user can edit #286's description field in-form before submitting.
 
 - **2026-07-03 (integration roadmap approved — "do it all")** — After the production-readiness batch, user asked "what's missing vs competition (Swimm/Mintlify/Context7/DeepWiki)?" Analysis: detection core is the moat ("green = docs verifiably match code"); the gap is INTEGRATION SURFACE — the tool assumes a human terminal or an agent that shells out. User approved all six: (1) **MCP server** `docguard mcp` — JSON-RPC 2.0 over stdio, pure Node, tools = guard/diagnose/explain/verify_claims/score, MUST be in READ_ONLY_COMMANDS (no ensureSkills side effects); (2) **SARIF 2.1.0** `guard --format sarif` — 1:1 from findings[] codes/locations → GitHub Code Scanning; (3) **Action PR annotations** — ::warning per finding + sticky doc-impact comment via diff --since; (4) **agent-file sync** `docguard agents --sync` — AGENTS.md canonical → CLAUDE.md/.cursor/rules/copilot-instructions/GEMINI.md generated variants with markers (drift-proofing the agent-file family); (5) **llms-full.txt + context pack** (`llms --full`, `memory --pack`); (6) **agent-readability score axis** — display-only (grades stay stable), deterministic metrics (token budget, anchor addressability, marker density). Explicitly REJECTED: LLM calls in core (trust anchor), hosted docs platform, auto-generated wikis. Execution: 6 parallel agents on disjoint files; README/AGENTS/CHANGELOG + docguard.mjs flag wiring reserved to orchestrator (same pattern as the 24-validator migration).