docguard-cli 0.25.1__tar.gz → 0.26.0__tar.gz

{docguard_cli-0.25.1 → docguard_cli-0.26.0}/.wolf/anatomy.md

@@ -1,7 +1,11 @@
 # anatomy.md
 
-> Auto-maintained by OpenWolf. Last scanned: 2026-06-09T15:38:05.147Z
-> Files: 554 tracked | Anatomy hits: 0 | Misses: 0
+> Auto-maintained by OpenWolf. Last scanned: 2026-06-10T21:09:50.636Z
+> Files: 579 tracked | Anatomy hits: 0 | Misses: 0
+
+## ../../../../../../../tmp/
+
+- `append-buglog.mjs` — Declares path (~1335 tok)
 
 ## ./
 
@@ -14,7 +18,7 @@
 - `.npmrc` — Supply-Chain Security Hardening (~59 tok)
 - `action.yml` — CI: 'DocGuard — CDD Compliance' (~4322 tok)
 - `AGENTS.md` — AI Agent Instructions — DocGuard (~1275 tok)
-- `CHANGELOG.md` — Changelog (~38458 tok)
+- `CHANGELOG.md` — Changelog (~39309 tok)
 - `CLAUDE.md` — OpenWolf (~57 tok)
 - `CODE_OF_CONDUCT.md` — Contributor Covenant Code of Conduct (~532 tok)
 - `COMPARISONS.md` — Comparisons & Honest Limitations (~3053 tok)
@@ -28,7 +32,7 @@
 - `PHILOSOPHY.md` — The Philosophy of Canonical-Driven Development (~1757 tok)
 - `pr_description.md` (~260 tok)
 - `pyproject.toml` — The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project (~351 tok)
-- `README.md` — Project documentation (~7230 tok)
+- `README.md` — Project documentation (~7359 tok)
 - `ROADMAP.md` — DocGuard Roadmap (~1494 tok)
 - `SECURITY.md` — Security Policy (~357 tok)
 - `STANDARD.md` — DocGuard Standard v0.1 (~6435 tok)
@@ -931,6 +935,48 @@
 - `release.yml` — CI: Auto Release — Tag, GitHub Release, npm, PyPI (~3386 tok)
 - `sync-speckit-catalog.yml` — CI: Prepare Spec Kit Catalog Submission (Manual) (~1385 tok)
 
+## cli/
+
+- `config.mjs` — DocGuard — configuration loading. (~3265 tok)
+- `docguard.mjs` — DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD) (~8124 tok)
+- `shared-ignore.mjs` — Shared Ignore Utility — Unified file filtering for all validators. (~2780 tok)
+- `shared-source.mjs` — Shared Source Resolution — Monorepo-aware source discovery. (~4357 tok)
+
+## cli/commands/
+
+- `agent.mjs` — `docguard agent` — the one-shot agent task graph. (~1644 tok)
+- `generate.mjs` — Generate Command — Reverse-engineer canonical docs from an existing codebase (~15364 tok)
+
+## cli/scanners/
+
+- `inventory.mjs` — Inventory scanners — code-truth the generator PRE-FILLS instead of leaving (~1699 tok)
+- `memory-plan.mjs` — Memory Plan — the orchestration artifact behind AI-powered Generate. (~5744 tok)
+- `project-type.mjs` — Project-Type Detection — the language-agnostic spine. (~4190 tok)
+- `routes.mjs` — Deep Route Scanner (~7712 tok)
+
+## cli/validators/
+
+- `freshness.mjs` — Freshness Validator — Check if documentation is stale relative to code changes. (~3462 tok)
+- `metrics-consistency.mjs` — Metrics Consistency Validator — Detects stale hardcoded numbers in docs. (~2714 tok)
+
+## cli/writers/
+
+- `mechanical.mjs` — Mechanical Fix Registry — applies deterministic, no-LLM fixes in place. (~3290 tok)
+
 ## extensions/spec-kit-docguard/
 
 - `extension.yml` (~1026 tok)
+
+## tests/
+
+- `agent.test.mjs` — Exports x (~1138 tok)
+- `commands.test.mjs` — DocGuard CLI Tests — Tests all commands and flags (~10304 tok)
+- `ensure-skills-idempotent.test.mjs` — v0.24 — Skill install is idempotent (field report, Issue D). (~1133 tok)
+- `freshness.test.mjs` — runGit: commitOldCode (~3536 tok)
+- `inventory.test.mjs` — Declares make (~1048 tok)
+- `mechanical.test.mjs` — Declares write (~1161 tok)
+- `memory-plan.test.mjs` — Exports u, Button (~1834 tok)
+- `metrics-consistency.test.mjs` — Declares guardResults (~1986 tok)
+- `metrics-dedup.test.mjs` — v0.14.1-N1 — Metrics-Consistency dedup. (~1450 tok)
+- `project-type.test.mjs` — Declares make (~2140 tok)
+- `shared-source.test.mjs` — API routes: GET (4 endpoints) (~1714 tok)

{docguard_cli-0.25.1 → docguard_cli-0.26.0}/.wolf/buglog.json

@@ -673,6 +673,530 @@
       "related_bugs": [],
       "occurrences": 1,
       "last_seen": "2026-06-09T15:38:05.160Z"
+    },
+    {
+      "id": "bug-040",
+      "timestamp": "2026-06-10T20:12:59.147Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/docguard.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 8→29 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:12:59.147Z"
+    },
+    {
+      "id": "bug-041",
+      "timestamp": "2026-06-10T20:13:36.017Z",
+      "error_message": "Missing error handling in unknown",
+      "file": "tests/commands.test.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:13:36.017Z"
+    },
+    {
+      "id": "bug-042",
+      "timestamp": "2026-06-10T20:17:07.836Z",
+      "error_message": "Null/undefined access in ",
+      "file": "cli/shared-ignore.mjs",
+      "root_cause": "Property access on potentially null/undefined value",
+      "fix": "Added null safety (optional chaining or null check)",
+      "tags": [
+        "auto-detected",
+        "null-safety",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:17:07.836Z"
+    },
+    {
+      "id": "bug-043",
+      "timestamp": "2026-06-10T20:17:45.779Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/scanners/project-type.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 7→10 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:17:45.779Z"
+    },
+    {
+      "id": "bug-044",
+      "timestamp": "2026-06-10T20:18:02.621Z",
+      "error_message": "Missing guard clause",
+      "file": "cli/scanners/project-type.mjs",
+      "root_cause": "No early return/throw for edge case: !content",
+      "fix": "Added guard clause: if (!content)",
+      "tags": [
+        "auto-detected",
+        "guard-clause",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:18:02.621Z"
+    },
+    {
+      "id": "bug-045",
+      "timestamp": "2026-06-10T20:18:48.686Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/scanners/routes.mjs",
+      "root_cause": "4 lines replaced/restructured",
+      "fix": "Rewrote 12→18 lines (4 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:18:48.686Z"
+    },
+    {
+      "id": "bug-046",
+      "timestamp": "2026-06-10T20:19:58.491Z",
+      "error_message": "Missing guard clause",
+      "file": "cli/shared-source.mjs",
+      "root_cause": "No early return/throw for edge case: hashC && ch === '#'",
+      "fix": "Added guard clause: if (hashC && ch === '#')",
+      "tags": [
+        "auto-detected",
+        "guard-clause",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:19:58.491Z"
+    },
+    {
+      "id": "bug-047",
+      "timestamp": "2026-06-10T20:24:10.717Z",
+      "error_message": "Significant refactor of ",
+      "file": "tests/ensure-skills-idempotent.test.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 13→17 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:24:10.717Z"
+    },
+    {
+      "id": "bug-048",
+      "timestamp": "2026-06-10T20:24:16.092Z",
+      "error_message": "Wrong return value",
+      "file": "tests/ensure-skills-idempotent.test.mjs",
+      "root_cause": "Was returning: spawnSync('node', [CLI, 'explain', 'freshness', '-",
+      "fix": "Now returns: spawnSync('node', [CLI, 'generate', '--dir', dir],",
+      "tags": [
+        "auto-detected",
+        "return-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:24:16.092Z"
+    },
+    {
+      "id": "bug-049",
+      "timestamp": "2026-06-10T20:24:20.798Z",
+      "error_message": "Incorrect value in code",
+      "file": "tests/ensure-skills-idempotent.test.mjs",
+      "root_cause": "Had 'SKILL.md mtimes must be unchanged across repeated",
+      "fix": "Changed to 'SKILL.md mtimes must be unchanged across repeated",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:24:20.798Z"
+    },
+    {
+      "id": "bug-050",
+      "timestamp": "2026-06-10T20:24:54.147Z",
+      "error_message": "Significant refactor of ",
+      "file": "tests/project-type.test.mjs",
+      "root_cause": "9 lines replaced/restructured",
+      "fix": "Rewrote 21→28 lines (9 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:24:54.147Z"
+    },
+    {
+      "id": "bug-051",
+      "timestamp": "2026-06-10T20:30:05.176Z",
+      "error_message": "Null/undefined access in ",
+      "file": "cli/scanners/memory-plan.mjs",
+      "root_cause": "Property access on potentially null/undefined value",
+      "fix": "Added null safety (optional chaining or null check)",
+      "tags": [
+        "auto-detected",
+        "null-safety",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:30:05.176Z"
+    },
+    {
+      "id": "bug-052",
+      "timestamp": "2026-06-10T20:30:09.623Z",
+      "error_message": "Wrong condition in logic",
+      "file": "cli/scanners/memory-plan.mjs",
+      "root_cause": "Condition was: if (surface.endpoints.length > 0)",
+      "fix": "Changed to: if (surface.endpoints.length > 0 && profileAllows('doc)",
+      "tags": [
+        "auto-detected",
+        "logic-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 5,
+      "last_seen": "2026-06-10T20:30:27.124Z"
+    },
+    {
+      "id": "bug-053",
+      "timestamp": "2026-06-10T20:30:31.498Z",
+      "error_message": "Wrong return value",
+      "file": "cli/scanners/memory-plan.mjs",
+      "root_cause": "Was returning: { profile, surface, docs, agentTasks };",
+      "fix": "Now returns: { profile, surface, docs, agentTasks, notes };",
+      "tags": [
+        "auto-detected",
+        "return-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:30:31.498Z"
+    },
+    {
+      "id": "bug-054",
+      "timestamp": "2026-06-10T20:34:18.552Z",
+      "error_message": "Wrong condition in logic",
+      "file": "cli/validators/metrics-consistency.mjs",
+      "root_cause": "Condition was: if (distinctFoundInFile.size === 0)",
+      "fix": "Changed to: if (!isDocguardBound(content, match.index)",
+      "tags": [
+        "auto-detected",
+        "logic-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:34:18.552Z"
+    },
+    {
+      "id": "bug-055",
+      "timestamp": "2026-06-10T20:34:25.902Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/validators/metrics-consistency.mjs",
+      "root_cause": "2 lines replaced/restructured",
+      "fix": "Rewrote 5→8 lines (2 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:34:25.902Z"
+    },
+    {
+      "id": "bug-056",
+      "timestamp": "2026-06-10T20:34:49.649Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/writers/mechanical.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 16→34 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:34:49.649Z"
+    },
+    {
+      "id": "bug-057",
+      "timestamp": "2026-06-10T20:37:04.053Z",
+      "error_message": "Incorrect value in code",
+      "file": "tests/metrics-dedup.test.mjs",
+      "root_cause": "Had '## Reference\\n\\nSee the [21 validators table](#ta",
+      "fix": "Changed to '## Reference\\n\\nSee the DocGuard [21 validators t",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 4,
+      "last_seen": "2026-06-10T20:37:17.491Z"
+    },
+    {
+      "id": "bug-058",
+      "timestamp": "2026-06-10T20:39:20.505Z",
+      "error_message": "Missing error handling in readDocStatus",
+      "file": "cli/validators/freshness.mjs",
+      "root_cause": "Code path had no error handling — exceptions would propagate uncaught",
+      "fix": "Added try/catch block",
+      "tags": [
+        "auto-detected",
+        "error-handling",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:39:20.505Z"
+    },
+    {
+      "id": "bug-059",
+      "timestamp": "2026-06-10T20:39:29.494Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/validators/freshness.mjs",
+      "root_cause": "2 lines replaced/restructured",
+      "fix": "Rewrote 10→23 lines (2 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:39:29.494Z"
+    },
+    {
+      "id": "bug-060",
+      "timestamp": "2026-06-10T20:56:11.176Z",
+      "error_message": "Incorrect value in code",
+      "file": "cli/commands/generate.mjs",
+      "root_cause": "Had `  ${c.bold}Code-truth surface:${c.reset} ${plan.s",
+      "fix": "Changed to `  ${c.bold}Code-truth surface:${c.reset} ${plan.s",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T20:56:11.176Z"
+    },
+    {
+      "id": "bug-061",
+      "timestamp": "2026-06-10T21:02:20.532Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/commands/agent.mjs",
+      "root_cause": "2 lines replaced/restructured",
+      "fix": "Rewrote 3→5 lines (2 removed) | Also: console.log(`\\n  ${c.dim}Run without --format text; return; | Also: const plan = buildMemoryPlan(projectDir, config);; const graph = buildAgentTaskGraph(projectDir, conf",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 3,
+      "last_seen": "2026-06-10T21:05:16.597Z"
+    },
+    {
+      "id": "bug-062",
+      "timestamp": "2026-06-10T21:02:26.215Z",
+      "error_message": "Wrong condition in logic",
+      "file": "cli/commands/agent.mjs",
+      "root_cause": "Condition was: if (flags.format === 'text')",
+      "fix": "Changed to: if (flags.format === 'json')",
+      "tags": [
+        "auto-detected",
+        "logic-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T21:02:26.215Z"
+    },
+    {
+      "id": "bug-063",
+      "timestamp": "2026-06-10T21:02:59.818Z",
+      "error_message": "Incorrect value in code",
+      "file": "tests/agent.test.mjs",
+      "root_cause": "Had `node ${CLI} agent`",
+      "fix": "Changed to `node ${CLI} agent --format json`",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T21:02:59.818Z"
+    },
+    {
+      "id": "bug-064",
+      "timestamp": "2026-06-10T21:09:03.096Z",
+      "error_message": "Incorrect value in code",
+      "file": "README.md",
+      "root_cause": "Had `explain <warning>`",
+      "fix": "Changed to `agent`",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "md"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10T21:09:03.096Z"
+    },
+    {
+      "id": "bug-065",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #3: `docguard guard` mutated the working tree (auto-init Spec Kit, spawn `specify`, write .agent/.specify) before printing results.",
+      "file": "cli/docguard.mjs",
+      "root_cause": "ensureSkills ran for every non-headless command; the v0.25.0 fix only added --plan to the headless set, not the read-only commands. guard/score/diff are not headless.",
+      "fix": "Added READ_ONLY_COMMANDS set (guard/audit/score/diff/impact/diagnose/trace/explain/memory/demo/agent); ensureSkills is gated to skip them. + test.",
+      "tags": [
+        "side-effects",
+        "guard",
+        "ensure-skills",
+        "field-report-2",
+        "read-only"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
+    },
+    {
+      "id": "bug-066",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #1: a stdlib Python CLI was detected as Express/Flask/AWS because surface scanners ingested tests/fixtures/ on the FIRST run (no .docguardignore).",
+      "file": "cli/shared-ignore.mjs, cli/scanners/project-type.mjs, cli/scanners/routes.mjs, cli/shared-source.mjs",
+      "root_cause": "v0.25.0 made scanners honor config.ignore but added NO default exclusion; the realistic first run has no .docguardignore. A test even codified the leak as expected.",
+      "fix": "Added DEFAULT_DETECTION_IGNORE_DIRS + isNonProductDir/isNonProductPath, applied in manifest/route/env detection by default (overridable via detection.includeNonProduct; not applied to guard structural checks). Rewrote the codifying test.",
+      "tags": [
+        "detection",
+        "fixtures",
+        "contamination",
+        "false-positive",
+        "field-report-2"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
+    },
+    {
+      "id": "bug-067",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #2: Metrics-Consistency flagged \"10 checks\" (a proof harness) vs DocGuard's own 86, and `fix --write` would overwrite the correct 10 with 86 (data corruption).",
+      "file": "cli/validators/metrics-consistency.mjs, cli/writers/mechanical.mjs",
+      "root_cause": "The validator matched any \"N checks/validators\" with no subject binding; \"actual\" was DocGuard's own count; the applier did a blind global replace with no provenance.",
+      "fix": "Subject-binding (number must be on a DocGuard-referencing line) + actualSource provenance in fixes[] + fail-closed applier (refuses without provenance; only rewrites bound lines). Updated codifying tests.",
+      "tags": [
+        "metrics",
+        "data-corruption",
+        "auto-fix",
+        "provenance",
+        "fail-closed",
+        "field-report-2"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
+    },
+    {
+      "id": "bug-068",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #4: project named after the git-worktree dir slug (compassionate-chaplygin-c91f47) instead of the manifest name.",
+      "file": "cli/scanners/project-type.mjs, cli/config.mjs",
+      "root_cause": "config.projectName was hardcoded to basename(projectDir); the manifest name was never read.",
+      "fix": "Added detectProjectName() (package.json/pyproject [project|tool.poetry]/Cargo/composer/go.mod → basename fallback), wired as the config default. + tests.",
+      "tags": [
+        "project-name",
+        "manifest",
+        "worktree",
+        "field-report-2"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
+    },
+    {
+      "id": "bug-069",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #5: init --profile cli required 4 docs but generate proposed API-REFERENCE/INTEGRATIONS; the two disagreed on the doc set.",
+      "file": "cli/scanners/memory-plan.mjs, cli/commands/generate.mjs",
+      "root_cause": "generate keyed doc emission purely off surface counts, never the active compliance profile; the B7 fix widened requiredFiles to match generate (symptom fix, wrong direction).",
+      "fix": "gate optional web/DB/UI docs on the active profile (cli/library) + emit a recoverable note when a surface is suppressed. + test.",
+      "tags": [
+        "generate",
+        "profile",
+        "consistency",
+        "field-report-2"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
+    },
+    {
+      "id": "bug-070",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #6: a fresh, uncommitted AGENTS.md warned \"not yet committed to git\" but mentioned only committing, not the last-reviewed marker; no same-session suppression.",
+      "file": "cli/validators/freshness.mjs",
+      "root_cause": "The warning text listed only one of the two satisfiers; there was no status:approved suppression for the generate-then-fill flow.",
+      "fix": "Warning now states both remedies (commit OR last-reviewed marker); suppressed for docs carrying <!-- docguard:status approved -->. + tests.",
+      "tags": [
+        "freshness",
+        "warning",
+        "noise",
+        "field-report-2"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
+    },
+    {
+      "id": "bug-071",
+      "timestamp": "2026-06-10",
+      "error_message": "Field report #2 Bug #7: `diff` reported JWT_SECRET \"in code, not documented\" though it appears only as a detection signature in a string literal (the tool never reads it).",
+      "file": "cli/shared-source.mjs",
+      "root_cause": "grepEnvUsage matched raw content with no comment/string-literal stripping and no test-dir exclusion, counting mentions as reads.",
+      "fix": "Added a single-pass char classifier (code/string/comment); env access counts only when the keyword is in code position; skip non-product dirs. + tests.",
+      "tags": [
+        "env-vars",
+        "detection",
+        "mentions-vs-reads",
+        "lexer",
+        "field-report-2"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-10"
     }
   ]
-}
+}

{docguard_cli-0.25.1 → docguard_cli-0.26.0}/.wolf/cerebrum.md

@@ -12,6 +12,12 @@
 - **Ignore wiring map (as of fcc7264):** all `shared-ignore` consumers — incl. `routes.mjs:90` and `todo-tracking.mjs:307,383` — call `shouldIgnore`. `project-type.mjs` did NOT until the B1b fix (2026-06-02): its `walk()` in `findManifests` now honors config.ignore (prunes dirs + skips manifest files via shouldIgnore). It detects frameworks from **dependency manifests** (`has(deps,'express'/'flask')`), so before the fix it ingested fixture `package.json`/`requirements.txt`. Two different mechanisms: glob filtering on results vs. `DEFAULT_IGNORE_DIRS` (bare dir-name Set) during walks.
 - **`globToRegex` (shared-ignore.mjs:115) silently mishandles trailing-slash dir patterns.** Verified by execution: `buildIgnoreFilter(['tests/'])('tests/fixtures/x.js')` → `false`; `['tests']` and `['tests/**']` → `true`. Gitignore-style `dir/` (the natural form) matches nothing. This makes ignore look wired-but-broken across every consumer. (Fixed 2026-06-02 by stripping the trailing slash.)
 - **The dispatcher (docguard.mjs) installs DocGuard's own agent tooling as a side effect.** `ensureSkills()` runs on every command except `setup`/`init` and except when `headless` (= jsonMode||write||checkOnly||changedOnly||quiet||plan after the B4 fix). It writes `.agent/skills` + `.agent/commands` and can spawn the `specify` CLI (→ `.specify/` + pip/npm). So read-shaped commands must be added to the `headless` set to stay side-effect-free. `headless` is consumed in exactly two places: the banner and this ensureSkills gate.
+- **Repo/package name mismatch trips Claude's auto-mode typosquat classifier.** Repo is `raccioly/docguard`; published package is `docguard-cli` (npm + PyPI); bin/command is `docguard`. When an agent autonomously runs `npm i -g docguard-cli` after the user only named `raccioly/docguard`, the `-cli` suffix reads as a typosquat and the install is denied. This is NOT a bug — provenance is fully wired (`repository`/`homepage`/`bugs` → the repo) and the package runs **no install scripts** (only `prepublishOnly`). Resolutions, cheapest first: install from local checkout (`npm i -g .`), add `--ignore-scripts`, a `Bash(npm i -g docguard-cli*)` permission rule, or just approve. Do NOT rename the repo/package to "fix" this — blast radius hits the spec-kit catalog, badges, and external links. Mitigation shipped 2026-06-10: a Quick Start note in README.md stating the repo↔package↔command relationship explicitly.
+- **Detection-ignore vs structural-ignore are SEPARATE concerns.** `shared-ignore.mjs` now has `DEFAULT_DETECTION_IGNORE_DIRS` + `isNonProductDir`/`isNonProductPath` (fixtures/tests/examples/testdata/samples) applied ONLY to surface-detection scanners (`project-type.findManifests`, `routes.mjs` result filter, `shared-source.grepEnvUsage`) — NEVER to guard's structural validators (a user's real `examples/` still counts for coverage). Default-on, overridable via `config.detection.includeNonProduct`. This is the first-run fix for fixture contamination; honoring `config.ignore` alone (v0.25) wasn't enough because a first run has no `.docguardignore`.
+- **`ensureSkills` (scaffolding) must only run for setup/init/generate + `init --with`.** Read-only commands are listed in `READ_ONLY_COMMANDS` in `docguard.mjs` and are gated out (plus the headless flags). A validate/report command writing `.agent/.specify` is a P0 trust break. When adding a new read/report command, add it to that set.
+- **Metrics-Consistency is subject-bound + fail-closed.** It validates a "N checks/validators" number ONLY when the containing line references "docguard" (`isDocguardBound`), stamps `actualSource` provenance on every fix, and `applyReplaceCount` REFUSES to write without `actualSource` and only rewrites DocGuard-bound lines. Never loosen this — an unbound auto-overwrite corrupts correct numbers (proof-harness "10 checks" → DocGuard's "86").
+- **`flags.format` defaults to `'text'` globally (docguard.mjs:~302).** So plan/agent commands can't distinguish "unset" from "explicit text". Convention: text summary is the default, `--format json` is the machine artifact (matches every other command). `generate --plan` and the new `agent` command are headless (own header, no global banner, no ensureSkills).
+- **Pre-filled code-truth + `docguard agent`.** `cli/scanners/inventory.mjs` (`scanComponents` = top-level source modules with single-package-wrapper descent; `scanTestInventory` = per-file test-case counts, multi-language) feed pre-filled ARCHITECTURE Component Map + a TEST-SPEC inventory section (generate previously never emitted TEST-SPEC). `cli/commands/agent.mjs` (`buildAgentTaskGraph`, pure) emits an ordered task graph (config→canonical-docs→verify) with kind code-truth|human-judgment, prefilled content, grounding, per-task `acceptance.verify`, and confidence. `--profile` overrides config to preview without `init`.
 
 ## Do-Not-Repeat
 
@@ -20,6 +26,7 @@
 
 
 - **2026-06-02** — Don't trust a bug report's stated root cause. The websec B1 report blamed "scanners/validators skip the ignore file"; the real defect was the trailing-slash glob (above). Fixing per the report ("centralize ignore handling") would have changed nothing AND left a false-green — the exact failure mode this tool exists to prevent.
+- **2026-06-10** — A "fix" that patches the reported REPRO but not the general CLASS is a false-green: the v0.25.0 work claimed all of field-report-1 B1–B7 "fixed + tested", yet field-report-2 hit the same issues on v0.25.1 because (a) fixture-ignore only worked WITH a `.docguardignore` (first run has none), (b) the side-effect fix only covered `generate --plan`, not `guard`, (c) B7 silenced guard by widening requiredFiles instead of making generate respect the profile. Worse, **two tests CODIFIED the bugs** (`project-type.test.mjs` asserted fixtures SHOULD leak with no ignore; `metrics-consistency.test.mjs` asserted subject-blind matching). Lesson: when fixing, fix the class, write the regression test against the AGENT'S ACTUAL SCENARIO (first run, no config), and audit whether an existing green test is actually encoding the bug.
 - **2026-06-02** — Don't assume a documented CLI flag is wired. `--fix` is documented (`docguard.mjs:111` "Auto-create missing files from templates") and set (`:186`) but read **nowhere** — `init.mjs` never consumes `flags.fix`. `grep` the flag's *consumption*, not just its declaration.
 - **2026-06-05** — Release CI gotchas (cost a failed v0.25.0 publish, then fixed): (1) `.github/workflows/release.yml`'s `test` job was MISSING `npm ci`, so `@babel/parser` (a regular dep) was absent and all 20 AST tests failed. It stayed latent because `detect-version` skips the job unless a release is due — so the job had literally never run. (2) `release.yml` is `paths`-filtered to `package.json`, so a workflow-only fix commit does NOT re-trigger it — use `gh workflow run release.yml --ref main` (the `workflow_dispatch` recovery trigger). (3) The `docguard watch` and `auto-fix prompts` CLI-spawn tests are CI-FLAKY (failed once on a2684e4, passed on identical-code re-run + locally) — a re-run, not a real failure.