docguard-cli 0.27.0__tar.gz → 0.28.0__tar.gz

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

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

{docguard_cli-0.27.0 → docguard_cli-0.28.0}/.agent/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.0 -->
 
 # DocGuard Guard Skill
 

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

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

{docguard_cli-0.27.0/extensions/spec-kit-docguard → docguard_cli-0.28.0/.agent}/skills/docguard-score/SKILL.md

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

{docguard_cli-0.27.0/extensions/spec-kit-docguard → docguard_cli-0.28.0/.agent}/skills/docguard-sync/SKILL.md

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.27.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.27.0 -->
+<!-- docguard:version: 0.28.0 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.27.0 → docguard_cli-0.28.0}/.docguard.json

@@ -49,7 +49,7 @@
         "extract": "basename-no-ext",
         "ignore": [
           "agents", "hooks", "ci", "badge", "llms", "publish",
-          "setup", "impact"
+          "setup", "impact", "sync-tests"
         ],
         "docs": ["README.md"],
         "section": "Usage"

{docguard_cli-0.27.0 → docguard_cli-0.28.0}/.wolf/anatomy.md

@@ -1,7 +1,7 @@
 # anatomy.md
 
-> Auto-maintained by OpenWolf. Last scanned: 2026-06-19T19:17:33.183Z
-> Files: 589 tracked | Anatomy hits: 0 | Misses: 0
+> Auto-maintained by OpenWolf. Last scanned: 2026-06-22T23:13:16.336Z
+> Files: 601 tracked | Anatomy hits: 0 | Misses: 0
 
 ## ../../../../../../../tmp/
 
@@ -9,7 +9,7 @@
 
 ## ./
 
-- `.docguard.json` (~522 tok)
+- `.docguard.json` (~526 tok)
 - `.docguardignore` — # Python distribution artifacts (~199 tok)
 - `.DS_Store` (~3818 tok)
 - `.gitignore` — Git ignore rules (~167 tok)
@@ -18,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 (~40407 tok)
+- `CHANGELOG.md` — Changelog (~41180 tok)
 - `CLAUDE.md` — OpenWolf (~57 tok)
 - `CODE_OF_CONDUCT.md` — Contributor Covenant Code of Conduct (~532 tok)
 - `COMPARISONS.md` — Comparisons & Honest Limitations (~3053 tok)
@@ -32,8 +32,8 @@
 - `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 (~7411 tok)
-- `ROADMAP.md` — DocGuard Roadmap (~2193 tok)
+- `README.md` — Project documentation (~7467 tok)
+- `ROADMAP.md` — DocGuard Roadmap (~2349 tok)
 - `SECURITY.md` — Security Policy (~357 tok)
 - `STANDARD.md` — DocGuard Standard v0.1 (~6435 tok)
 - `SUPPLY-CHAIN-AUDIT.md` — Supply-Chain Security Audit (~726 tok)
@@ -942,7 +942,7 @@
 ## cli/
 
 - `config.mjs` — DocGuard — configuration loading. (~3265 tok)
-- `docguard.mjs` — DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD) (~8443 tok)
+- `docguard.mjs` — DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD) (~8995 tok)
 - `findings.mjs` — Findings — the structured, LLM-addressable result unit (v0.27). (~2174 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. (~4655 tok)
@@ -950,11 +950,15 @@
 ## cli/commands/
 
 - `agent.mjs` — `docguard agent` — the one-shot agent task graph. (~1644 tok)
-- `explain.mjs` — Explain Command — v0.16-P6. (~9022 tok)
+- `explain.mjs` — Explain Command — v0.16-P6. (~9474 tok)
 - `feedback.mjs` — Feedback Command — close the loop with the tool's maintainers (v0.27). (~1920 tok)
 - `generate.mjs` — Generate Command — Reverse-engineer canonical docs from an existing codebase (~15364 tok)
-- `guard.mjs` — Guard Command — Validate project against its canonical documentation (~9556 tok)
+- `guard.mjs` — Guard Command — Validate project against its canonical documentation (~9705 tok)
+- `init.mjs` — Init Command — Initialize CDD documentation from templates (~7278 tok)
 - `score.mjs` — Score Command — Calculate CDD maturity score (0-100) (~11214 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)
+- `verify.mjs` — Verify Command — `docguard verify --semantic` (LLM field report #5). (~833 tok)
 
 ## cli/scanners/
 
@@ -962,9 +966,12 @@
 - `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)
+- `semantic-claims.mjs` — Semantic claim extractor (LLM field report #5). (~1794 tok)
 
 ## cli/validators/
 
+- `api-surface.mjs` — API-Surface Validator — Detects drift between the documented API surface (~4095 tok)
+- `architecture.mjs` — Architecture Validator — Enhanced with automatic import analysis (~3558 tok)
 - `doc-quality.mjs` — Doc Quality Validator — Measures documentation writing quality (~6349 tok)
 - `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)
@@ -979,11 +986,19 @@
 
 - `extension.yml` (~1026 tok)
 
+## templates/
+
+- `ENVIRONMENT.md.template` — Environment & Configuration (~394 tok)
+- `REQUIREMENTS.md.template` — Requirements (~632 tok)
+- `SECURITY.md.template` — Security (~342 tok)
+- `TEST-SPEC.md.template` — /*.ts --> | <!-- e.g. tests/unit/**/*.test.ts --> | Unit | (~771 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)
+- `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)
 - `inventory.test.mjs` — Declares make (~1048 tok)

{docguard_cli-0.27.0 → docguard_cli-0.28.0}/.wolf/buglog.json

@@ -1429,8 +1429,15 @@
       "file": "cli/validators/security.mjs",
       "root_cause": "The SEC password regex matches any quoted value 8+ chars after a password/passwd/pwd key, regardless of whether the value is natural-language copy vs an actual credential.",
       "fix": "Added looksLikeProse(value): a multi-word natural-language value downgrades the finding to a LOW-confidence, suppressible, reportable warning (not a blocking error). Still surfaced — no false-green. Implemented on the new findings architecture (cli/findings.mjs) with stable code SEC001.",
-      "tags": ["security", "false-positive", "findings", "field-report-3"],
-      "related_bugs": ["bug-087"],
+      "tags": [
+        "security",
+        "false-positive",
+        "findings",
+        "field-report-3"
+      ],
+      "related_bugs": [
+        "bug-087"
+      ],
       "occurrences": 1,
       "last_seen": "2026-06-19T20:05:00.000Z"
     },
@@ -1441,10 +1448,313 @@
       "file": "cli/validators/security.mjs",
       "root_cause": "First cut of looksLikeProse treated ANY value ending in .!? as prose. Strong passwords commonly end in '!' — so a one-word secret was misclassified as natural language.",
       "fix": "Terminal punctuation alone no longer reclassifies a value: prose now requires >=3 words, OR a 2-word fragment ending in .!?. A single token like 'SuperSecretPassword!' stays a blocking error. The existing security test caught it.",
-      "tags": ["security", "heuristic", "regression", "self-caught"],
-      "related_bugs": ["bug-086"],
+      "tags": [
+        "security",
+        "heuristic",
+        "regression",
+        "self-caught"
+      ],
+      "related_bugs": [
+        "bug-086"
+      ],
       "occurrences": 1,
       "last_seen": "2026-06-19T20:06:00.000Z"
+    },
+    {
+      "id": "bug-088",
+      "timestamp": "2026-06-22T21:27:36.030Z",
+      "error_message": "Missing await",
+      "file": "cli/validators/architecture.mjs",
+      "root_cause": "Async call without await — returned Promise instead of value",
+      "fix": "Added await to async call",
+      "tags": [
+        "auto-detected",
+        "async-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:27:36.030Z"
+    },
+    {
+      "id": "bug-089",
+      "timestamp": "2026-06-22T21:27:51.814Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/validators/architecture.mjs",
+      "root_cause": "6 lines replaced/restructured",
+      "fix": "Rewrote 24→31 lines (6 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:27:51.814Z"
+    },
+    {
+      "id": "bug-090",
+      "timestamp": "2026-06-22T21:28:15.213Z",
+      "error_message": "Wrong condition in logic",
+      "file": "cli/validators/architecture.mjs",
+      "root_cause": "Condition was: if (!imp.startsWith('.')",
+      "fix": "Changed to: if (!spec.startsWith('.')",
+      "tags": [
+        "auto-detected",
+        "logic-fix",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:28:15.213Z"
+    },
+    {
+      "id": "bug-091",
+      "timestamp": "2026-06-22T21:32:49.288Z",
+      "error_message": "Missing guard clause",
+      "file": "cli/commands/init.mjs",
+      "root_cause": "No early return/throw for edge case: h1 === -1",
+      "fix": "Added guard clause: if (h1 === -1)",
+      "tags": [
+        "auto-detected",
+        "guard-clause",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:32:49.288Z"
+    },
+    {
+      "id": "bug-092",
+      "timestamp": "2026-06-22T21:33:09.031Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/commands/explain.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 11→12 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:33:09.031Z"
+    },
+    {
+      "id": "bug-093",
+      "timestamp": "2026-06-22T21:36:02.265Z",
+      "error_message": "Missing error handling in computeSpecVsRouteDrift",
+      "file": "cli/validators/api-surface.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-22T21:36:02.265Z"
+    },
+    {
+      "id": "bug-094",
+      "timestamp": "2026-06-22T21:36:20.504Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/validators/api-surface.mjs",
+      "root_cause": "7 lines replaced/restructured",
+      "fix": "Rewrote 13→33 lines (7 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:36:20.504Z"
+    },
+    {
+      "id": "bug-095",
+      "timestamp": "2026-06-22T21:38:26.085Z",
+      "error_message": "Missing error handling in unknown",
+      "file": "cli/commands/explain.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-22T21:38:26.085Z"
+    },
+    {
+      "id": "bug-096",
+      "timestamp": "2026-06-22T21:42:14.555Z",
+      "error_message": "Missing guard clause",
+      "file": "cli/commands/sync.mjs",
+      "root_cause": "No early return/throw for edge case: flags.tests",
+      "fix": "Added guard clause: if (flags.tests)",
+      "tags": [
+        "auto-detected",
+        "guard-clause",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:42:14.555Z"
+    },
+    {
+      "id": "bug-097",
+      "timestamp": "2026-06-22T21:43:13.482Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/docguard.mjs",
+      "root_cause": "3 lines replaced/restructured",
+      "fix": "Rewrote 8→9 lines (3 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:43:13.482Z"
+    },
+    {
+      "id": "bug-098",
+      "timestamp": "2026-06-22T21:48:51.090Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/scanners/semantic-claims.mjs",
+      "root_cause": "2 lines replaced/restructured",
+      "fix": "Rewrote 3→5 lines (2 removed)",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T21:48:51.090Z"
+    },
+    {
+      "id": "bug-099",
+      "timestamp": "2026-06-22T21:57:40.130Z",
+      "error_message": "Significant refactor of ",
+      "file": "cli/commands/guard.mjs",
+      "root_cause": "4 lines replaced/restructured",
+      "fix": "Rewrote 9→14 lines (4 removed) | Also: if (data.effectiveErrors > 0) process.exit(1);; if (data.effectiveWarnings > 0) process.exit(2);",
+      "tags": [
+        "auto-detected",
+        "refactor",
+        "mjs"
+      ],
+      "related_bugs": [],
+      "occurrences": 2,
+      "last_seen": "2026-06-22T21:57:52.074Z"
+    },
+    {
+      "id": "bug-100",
+      "timestamp": "2026-06-22T23:12:27.938Z",
+      "error_message": "Incorrect value in code",
+      "file": "README.md",
+      "root_cause": "Had \"Commands (16)\"",
+      "fix": "Changed to \"Commands (17)\"",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "md"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:12:27.938Z"
+    },
+    {
+      "id": "bug-101",
+      "timestamp": "2026-06-22T23:12:41.080Z",
+      "error_message": "Incorrect value in code",
+      "file": "package.json",
+      "root_cause": "Had \"0.27.0\"",
+      "fix": "Changed to \"0.28.0\"",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "json"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:12:41.080Z"
+    },
+    {
+      "id": "bug-102",
+      "timestamp": "2026-06-22T23:12:44.341Z",
+      "error_message": "Incorrect value in code",
+      "file": "pyproject.toml",
+      "root_cause": "Had \"0.27.0\"",
+      "fix": "Changed to \"0.28.0\"",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "toml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:12:44.341Z"
+    },
+    {
+      "id": "bug-103",
+      "timestamp": "2026-06-22T23:12:47.998Z",
+      "error_message": "Incorrect value in code",
+      "file": "extensions/spec-kit-docguard/extension.yml",
+      "root_cause": "Had \"0.27.0\"",
+      "fix": "Changed to \"0.28.0\"",
+      "tags": [
+        "auto-detected",
+        "wrong-value",
+        "yml"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:12:47.998Z"
+    },
+    {
+      "id": "bug-104",
+      "timestamp": "2026-06-22T23:13:08.031Z",
+      "error_message": "Missing await",
+      "file": "CHANGELOG.md",
+      "root_cause": "Async call without await — returned Promise instead of value",
+      "fix": "Added await to async call",
+      "tags": [
+        "auto-detected",
+        "async-fix",
+        "md"
+      ],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:13:08.031Z"
+    },
+    {
+      "id": "bug-105",
+      "timestamp": "2026-06-22T23:40:00.000Z",
+      "error_message": "Tests field-report-2-cli #1 and explain-coverage hook failed with 'Unterminated string in JSON at position 8178' when JSON.parse-ing `docguard guard --format json` stdout.",
+      "file": "cli/commands/guard.mjs",
+      "root_cause": "runGuard's JSON path did `console.log(JSON.stringify(data)) ; process.exit(code)`. A payload over ~8 KB written to a PIPE flushes asynchronously, so the immediate process.exit() truncated it mid-string. The repo's own report (7.3 KB) stayed under the boundary; a fixture's report (8.2 KB) crossed it. v0.28 additions to the guard JSON tipped this fixture over the edge, exposing the latent race. Writing to a FILE (synchronous) never reproduced it.",
+      "fix": "Set `process.exitCode = code` and `process.stdout.write(json + '\\n')` then RETURN, instead of process.exit(). Node drains stdout and exits naturally with the code. Applied to both the JSON branch and the final text-path exit. Real CI-correctness bug: a >8 KB --format json report would be silently truncated for any pipe consumer.",
+      "tags": ["guard", "json", "process-exit", "flush-race", "ci-correctness", "field-report-3"],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:40:00.000Z"
+    },
+    {
+      "id": "bug-106",
+      "timestamp": "2026-06-22T23:41:00.000Z",
+      "error_message": "Architecture validator flagged a circular dependency that is broken at runtime by `await import()` (field report #2).",
+      "file": "cli/validators/architecture.mjs",
+      "root_cause": "extractImports lumped ES import, dynamic import(), and require() into one list feeding both graph.edges (layer checks) and graph.fileMap (cycle DFS). A dynamic import is NOT a load-time edge — it's the canonical cycle break — but was counted as one.",
+      "fix": "extractImports now returns { spec, dynamic }. buildImportGraph records the dynamic flag on graph.edges but only pushes STATIC edges into fileMap (cycle adjacency). Cycle detection no longer sees dynamic edges; layer-boundary checks still do.",
+      "tags": ["architecture", "import-cycle", "dynamic-import", "false-positive", "field-report-3"],
+      "related_bugs": [],
+      "occurrences": 1,
+      "last_seen": "2026-06-22T23:41:00.000Z"
     }
   ]
 }

{docguard_cli-0.27.0 → docguard_cli-0.28.0}/.wolf/cerebrum.md

@@ -25,8 +25,17 @@
 - **`docguard feedback` (v0.27).** Local-first: writes `.docguard/feedback/<code>-<id>.json` (deterministic id via djb2 hash — no Date/random) + prints a prefilled GitHub issue URL CAPPED at 1800 chars and REDACTED (basename:line only, no literal values — security builds `redactedContext` that omits the matched value). Reuses the commit-3b600fd lesson (oversized URL overflows GitHub's ~8 KB limit). It's in `READ_ONLY_COMMANDS` (so it never scaffolds skills) even though it writes its own feedback dir.
 - **`score.mjs` can't be unit-tested with `{}`** — `runScoreInternal({})` throws (`calcStructureScore` reads `config.requiredFiles.canonical`). Extract testable seams instead: the test-runner detection is now `export function detectTestRunner(dir, config)` (recognizes vitest-in-vite.config via `vitest/config` import or a `test:` block, `scripts.test` runner names, and workspace-subdir configs). Pattern for future score tests: pull the unit out, don't feed the whole pipeline a half-config.
 
+- **`verify --semantic` design (v0.28, `cli/scanners/semantic-claims.mjs` + `cli/commands/verify.mjs`).** DocGuard is zero-dependency and NEVER calls an LLM itself. So the semantic-drift check (field report #5 — documented numbers/enums vs code) is an EXTRACTOR, not an LLM call: `extractSemanticClaims` finds documented numbers-with-units (days/ms/req-s/GSIs/roles via `NUMBER_PATTERNS`) + enum lists (2+ UPPER_SNAKE in a status/state context) + the nearest cited code path (±1 line window), and `buildSemanticVerifyTasks` emits an agent task list. The agent running docguard does the comparison. Same division of labour as `docguard agent`. Precision-first: code-fenced numbers, version strings, and dates are excluded by design.
+- **`sync --tests` safety scope (v0.28, `cli/commands/sync-tests.mjs`).** The TEST-SPEC Source-to-Test Map is HAND-maintained, so the reconciler does only two non-destructive ops: remove rows whose SOURCE file is gone, append co-located (`same dir` or sibling `__tests__/`) source↔test pairs absent from the table. Ghost TEST refs (source exists, test gone) are REPORTED, never auto-edited — blanking a curated status/notes cell is too destructive (the Test-Spec validator already warns). Pairing is co-located-only to avoid cross-directory basename collisions polluting the table.
+- **Dynamic-import cycle handling (v0.28).** `architecture.mjs extractImports` now returns `{spec, dynamic}`. `graph.fileMap` (cycle DFS adjacency) gets STATIC edges only; `graph.edges` (layer checks) keeps all. A runtime `await import()` is the canonical cycle BREAK, not a load-time edge.
+- **API-Surface spec-vs-route (v0.28).** When an OpenAPI spec exists it's the authoritative surface, so the API-REFERENCE doc reconciles against the SPEC — a phantom spec endpoint sails through. `computeSpecVsRouteDrift` diffs spec endpoints against `scanRoutesDeep` results (reusing `compareEndpoints` for method/path normalization), but ONLY when routes are scannable (`routes.length > 0`) — else it can't tell "no route" from "scanner blind" and would false-positive every endpoint.
+
 ## Do-Not-Repeat
 
+- **2026-06-22** — A CLI command that emits machine output and exits must NOT `console.log(payload); process.exit(code)`. To a PIPE, a payload over ~8 KB flushes asynchronously and process.exit() truncates it mid-write → a consumer gets "Unterminated string in JSON". Use `process.exitCode = code` + `process.stdout.write(payload)` then `return` (Node drains stdout, exits naturally). Writing to a FILE is synchronous so it NEVER reproduces — you must test through a real pipe (spawnSync captures stdout via a pipe; that's why the test caught it and the manual file-redirect repro didn't). Fixed in guard.mjs; audit other `--format json` exits if touched.
+- **2026-06-22** — When adding a new internal module under `cli/commands/` that is NOT a registered command (e.g. `sync-tests.mjs` backing `sync --tests`), add it to `.docguard.json` surfaceSync `commands.ignore` — else Surface-Sync flags it as "in code but missing from README" and Canonical-Sync miscounts "ships N commands". Real commands go in the README table + bump the count + the mermaid `Commands (N)`.
+
+
 - **2026-06-19** — A "prose vs secret" heuristic must NOT treat terminal punctuation alone as a prose signal. First cut of `looksLikeProse` flagged any value ending in `.!?` as natural language; strong passwords routinely end in `!` (`"SuperSecretPassword!"`), so a real one-token secret got downgraded to a low-confidence warning — the existing `security.test.mjs` caught it (2 errors → 1). Rule that works: prose = ≥3 words, OR a 2-word fragment ending in `.!?`. When adding a downgrade heuristic to a SECURITY check, bias toward keeping the error (a false-negative hides a secret) and write the test against a single-token-secret control.
 - **2026-06-19** — When adding a new `docguard` command, the repo guards ITSELF: Surface-Sync flags it missing from the README commands table and Canonical-Sync flags the "ships N commands" count + the architecture mermaid `Commands (N)`. Update all three (README prose count, README table, mermaid) in the same change or DocGuard's own guard fails. `feedback` made it 14 → 16 (there was a pre-existing 1-off; real count was already 15).
 

docguard_cli-0.28.0/.wolf/hooks/_session.json

@@ -0,0 +1,81 @@
+{
+  "session_id": "session-2026-06-22-1910",
+  "started": "2026-06-22T23:10:53.651Z",
+  "files_read": {
+    "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/.docguard.json": {
+      "count": 1,
+      "tokens": 522,
+      "first_read": "2026-06-22T23:12:09.566Z"
+    }
+  },
+  "files_written": [
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/.docguard.json",
+      "action": "edit",
+      "tokens": 56,
+      "at": "2026-06-22T23:12:16.721Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/README.md",
+      "action": "edit",
+      "tokens": 96,
+      "at": "2026-06-22T23:12:23.723Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/README.md",
+      "action": "edit",
+      "tokens": 20,
+      "at": "2026-06-22T23:12:27.937Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/README.md",
+      "action": "edit",
+      "tokens": 148,
+      "at": "2026-06-22T23:12:34.633Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/package.json",
+      "action": "edit",
+      "tokens": 7,
+      "at": "2026-06-22T23:12:41.079Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/pyproject.toml",
+      "action": "edit",
+      "tokens": 6,
+      "at": "2026-06-22T23:12:44.340Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/extensions/spec-kit-docguard/extension.yml",
+      "action": "edit",
+      "tokens": 6,
+      "at": "2026-06-22T23:12:47.997Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/CHANGELOG.md",
+      "action": "edit",
+      "tokens": 896,
+      "at": "2026-06-22T23:13:08.029Z"
+    },
+    {
+      "file": "/Users/ricardoaccioly/Repo_claude/canonical-spec-kit/.claude/worktrees/crazy-hofstadter-94c5a8/ROADMAP.md",
+      "action": "edit",
+      "tokens": 217,
+      "at": "2026-06-22T23:13:16.353Z"
+    }
+  ],
+  "edit_counts": {
+    ".docguard.json": 1,
+    "README.md": 3,
+    "package.json": 1,
+    "pyproject.toml": 1,
+    "extensions/spec-kit-docguard/extension.yml": 1,
+    "CHANGELOG.md": 1,
+    "ROADMAP.md": 1
+  },
+  "anatomy_hits": 1,
+  "anatomy_misses": 0,
+  "repeated_reads_warned": 0,
+  "cerebrum_warnings": 0,
+  "stop_count": 2
+}