docguard-cli 0.41.5__tar.gz → 0.41.7__tar.gz

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

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

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

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

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/.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.41.5
+  version: 0.41.7
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.41.5 -->
+<!-- docguard:version: 0.41.7 -->
 
 # DocGuard Sync Skill
 

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/.gitignore

@@ -46,3 +46,4 @@ websec-out/
 # OpenWolf private session memory (machine-local, not shared)
 .claude/openwolf-memory/
 .wolf/
+.testguard/

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/AGENTS.md

@@ -187,6 +187,30 @@ extensions/spec-kit-docguard/
 - Never write a workflow using `pull_request_target` with checkout of PR-controlled refs.
 - Always pin third-party GitHub Actions to commit SHA, not @v1 or @main.
 
+## Claim probing (TestGuard)
+
+`testguard.claims.json` states what this codebase guarantees, as claims with
+mechanical faults. `testguard probe` injects each fault and reports the ones the
+suite fails to detect — a test that pins a *defect* stays green under coverage,
+so this is the check that catches it.
+
+This suite runs on `node --test`, which ships no `json` reporter, while TestGuard
+reads Jest-shape JSON. `tools/node-test-json-reporter.mjs` translates between
+them:
+
+```bash
+npx testguard-cli probe --confirm 3 --serial \
+  --node-modules "$PWD/node_modules" \
+  --runner-cmd "node --test --test-reporter=$PWD/tools/node-test-json-reporter.mjs --test-reporter-destination={out} {files}"
+```
+
+Pass an absolute reporter path: the probe runs in a scratch worktree built from
+a commit, so a relative path resolves there and untracked files do not exist.
+
+`testguard gate --changed origin/main` reports changed source files that carry no
+claim. It does not find bugs; it refuses to let a change land without stating
+what must be true, which is the step that surfaces them.
+
 ## Evidence and contributions
 
 A structural score is a maturity proxy. Preserve `assurance` and nullable factual accuracy in automation; a clean guard does not establish arbitrary prose correctness. Review human intent separately from generated code facts. To challenge any finding, run `docguard feedback --code <CODE> --preview`, inspect the metadata-only public draft, and check the supplied search link for existing open and closed work. Contribute a synthetic failing example paired with a neighboring valid case. Submission remains opt-in.

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/CHANGELOG.md

@@ -7,6 +7,100 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.41.7] - 2026-09-18
+
+Automated weekly release — batches everything merged since `v0.41.6`.
+
+### Changed
+
+- feat: detect documents by name across the codebase, not by exact path (#418)
+
+
+### Added
+
+- Find the documents a project already has, instead of assuming where they are.
+  `init` now looks for canonical role filenames across the repository before
+  creating anything, reports what it found, and offers to adopt that location —
+  writing both `docs.roles` and a matching `requiredFiles.canonical`. Detection
+  recognises real-world spellings rather than one exact filename: separators and
+  case are ignored (`data_model.md`, `Data Model.md`), `.markdown` and `.mdx`
+  count, and each role has known aliases (`system-design.md`, `testing.md`,
+  `env.md`, `api.md`, `PRD.md`). A directory must hold at least two roles before
+  it qualifies, so a lone root `SECURITY.md` — GitHub's policy file — never
+  triggers relocation, and the conventional directory wins any tie.
+
+### Fixed
+
+- Judge the same repository the same way on every platform. Three detectors
+  probed for literal filenames — `existsSync(resolve(dir, 'ROADMAP.md'))` — which
+  matches `roadmap.md` on a case-insensitive filesystem (macOS) and not on a
+  case-sensitive one (Linux). CI and a laptop could therefore disagree about
+  whether the same TODO was tracked. Matching is now explicitly case- and
+  separator-insensitive, decided by DocGuard rather than by the filesystem.
+- Recognise work-tracking documents by name rather than by exact path. A TODO
+  recorded in `docs/ROADMAP.md`, `PLAN.md` or `TASKS.md` was reported as
+  untracked because only ten literal paths were consulted. Tracking documents
+  are now found by alias across the conventional documentation directories;
+  `README.md` and `NOTES.md` still do not count as work lists.
+- Recognise test directories beyond four exact names. `testing/`, `e2e/`,
+  `integration/`, `specs/` and `Tests/` now satisfy the same signal as `tests/`.
+- Stop scaffolding a second canonical directory next to an existing one.
+  A project keeping its documents in `docs/canonical/` read as empty, because
+  the first-run check only walked `docs-canonical/`. `init` then reported "no
+  canonical docs", offered to reverse-engineer them from code, and created a
+  duplicate set beside the real documents. Reported as #326.
+
+
+## [0.41.6] - 2026-09-18
+
+Automated weekly release — batches everything merged since `v0.41.5`.
+
+### Changed
+
+- test: make this suite probeable by TestGuard, and close the gap it found (#415)
+- fix: do not block projects that never adopted DocGuard; protect hook backups (#414)
+- chore: complete the pass to generic project references (#413)
+
+
+### Added
+
+- TestGuard claim probing for this repository: `testguard.claims.json` plus
+  `tools/node-test-json-reporter.mjs`, which translates `node --test` output into
+  the Jest-shape JSON TestGuard reads (node:test ships no `json` reporter). The
+  first claim covers `backupFile`; probing it found a real gap — one guard was
+  masked by another, so its fault survived while every test stayed green — and
+  the missing case is now covered.
+
+### Changed
+
+- Completed the pass to generic project references: the earlier sweep matched a
+  narrower pattern than the one used to find them, so sixteen mentions survived
+  in source comments, tests and changelog prose. Two references are deliberately
+  kept: `.docguard-archive.json` records an archived spec path plus the
+  `git restore` command that recovers it, and renaming that string would point
+  the restore at a path that never existed.
+
+### Fixed
+
+- Stop blocking commits in projects that never adopted DocGuard. A Git hook
+  lives in the common `.git/hooks` and governs every linked worktree, while
+  `.docguard.json` is a branch-local tracked file — during adoption the two
+  cannot be consistent, so a hook installed on one branch blocked commits on
+  every other branch and worktree, where `guard` exited 1 for missing canonical
+  docs. `guard` now exits **3** ("not initialised") instead of 1 when there is
+  no `.docguard.json`, and the generated hooks skip enforcement and allow the
+  operation. Exit 3 is still non-zero, so a CI gate that fails on any non-zero
+  status is unchanged, and an adopted project with real findings still exits 1
+  and still blocks. Existing installed hooks do not self-heal — re-run
+  `docguard hooks` to pick this up.
+- Stop spending the single backup slot on a no-op. Re-installing a byte-identical
+  managed hook wrote a redundant `.bak`; with `--force` a second install
+  overwrote the backup holding the user's own original hook, which is
+  unrecoverable because a `.git/hooks` file is not in version control. Identical
+  writes are now skipped, and a `.bak` DocGuard did not write is preserved
+  alongside a timestamped copy rather than replaced.
+
+
 ## [0.41.5] - 2026-09-17
 
 Automated weekly release — batches everything merged since `v0.41.4`.
@@ -1809,7 +1903,7 @@ Python, and AWS/AppSync projects.
   longer scans `commands/docguard.*.md` (DocGuard's slash-command docs, which it
   installs into the project) for count claims. A stale "N validators" baked into
   those shipped docs was being reported as the *user's* drift in every project
-  that had them (field test: quick-recon-tool, hugocross). A user's own
+  that had them (field test: a downstream project, a downstream project). A user's own
   `commands/<name>.md` is unaffected.
 - **Dogfooding closure** — Canonical-Sync now scans **AGENTS.md** in addition to
   README for "ships N commands"/"N validators" surface claims (it only checked

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.41.5
+Version: 0.41.7
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. No Python dependencies (requires Node.js 18+).
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/cli/commands/guard.mjs

@@ -664,12 +664,23 @@ export function runGuard(projectDir, config, flags) {
 
   const data = runGuardInternal(projectDir, config);
 
+  // A project with no .docguard.json has not adopted DocGuard. Its "failures"
+  // are missing canonical docs, which is not the same fact as "this project
+  // failed its checks" — and consumers need to tell them apart. Exit 3 says
+  // "not initialised": still non-zero, so a CI gate that fails on any non-zero
+  // status is unchanged, but the generated Git hook can let the commit through
+  // instead of blocking a project that never adopted the tool.
+  const uninitialised = !existsSync(resolvePath(projectDir, '.docguard.json'));
+  const exitFor = d => (d.effectiveErrors > 0
+    ? (uninitialised ? 3 : 1)
+    : d.effectiveWarnings > 0 ? 2 : 0);
+
   // ── SARIF output (2.1.0) ──
   // Same flush discipline as the JSON branch below (bug-105): set exitCode and
   // write+return so a piped consumer never gets a truncated payload.
   if (flags.format === 'sarif') {
     const sarif = toSarif(data, { projectDir });
-    process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    process.exitCode = exitFor(data);
     process.stdout.write(JSON.stringify(sarif, null, 2) + '\n');
     return;
   }
@@ -680,7 +691,7 @@ export function runGuard(projectDir, config, flags) {
   // Exit-code semantics identical to sarif/json.
   if (flags.format === 'junit') {
     const xml = toJUnit(data);
-    process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    process.exitCode = exitFor(data);
     process.stdout.write(xml + '\n');
     return;
   }
@@ -689,7 +700,7 @@ export function runGuard(projectDir, config, flags) {
   if (flags.format === 'json') {
     // Use severity-aware effective counts for exit code; raw counts stay in the JSON
     // for display tools that want to show the full picture.
-    const code = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    const code = exitFor(data);
     // v0.28: set exitCode + return instead of process.exit(). A large JSON
     // payload (>~8 KB) written to a PIPE flushes asynchronously; an immediate
     // process.exit() truncates it mid-string, so a CI consumer parsing stdout
@@ -991,5 +1002,5 @@ export function runGuard(projectDir, config, flags) {
   // v0.28: exitCode + return (not process.exit) so the buffered text output
   // flushes to a pipe before the process exits — same truncation fix as the
   // JSON path above.
-  process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+  process.exitCode = exitFor(data);
 }

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/cli/commands/hooks.mjs

@@ -105,6 +105,17 @@ import { listCanonicalDocs } from '../shared-ignore.mjs';
 
 // Git enforcement is offline and fail-closed; agent nudges stay best-effort.
 const ENFORCEMENT_RUNTIME = `
+# A Git hook is repo-wide (it lives in the common .git/hooks and is shared by
+# every linked worktree), but .docguard.json is a branch-local tracked file.
+# During adoption the two cannot be consistent: the hook is already active
+# everywhere while the config exists on one branch only. A project that has not
+# adopted DocGuard must not be blocked by a hook installed from another branch.
+if [ ! -f ".docguard.json" ]; then
+  echo "DocGuard: not initialised here (no .docguard.json) — skipping."
+  echo "          Adopt it with: docguard init"
+  exit 0
+fi
+
 if ! command -v node >/dev/null 2>&1; then
   echo "❌ Node.js runtime not found — operation blocked" >&2
   exit 1
@@ -136,7 +147,10 @@ ${ENFORCEMENT_RUNTIME}
 "$DOCGUARD" guard
 EXIT_CODE=$?
 
-if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
+if [ "$EXIT_CODE" -eq 3 ]; then
+  echo ""
+  echo "DocGuard: project not initialised — commit allowed"
+elif [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
   echo ""
   echo "❌ DocGuard guard FAILED — commit blocked"
   echo "   Fix the errors above, then try again."
@@ -265,7 +279,10 @@ fi
 "$DOCGUARD" guard
 EXIT_CODE=$?
 
-if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
+if [ "$EXIT_CODE" -eq 3 ]; then
+  echo ""
+  echo "DocGuard: project not initialised — commit allowed"
+elif [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
   echo ""
   echo "❌ DocGuard guard FAILED — commit blocked."
   echo "   Remaining issues need an AI agent (content rewrites, not mechanical):"

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/cli/commands/init.mjs

@@ -17,6 +17,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
 import { c, PROFILES, CURRENT_SCHEMA_VERSION } from '../shared.mjs';
+import { detectCanonicalLayout, applyDocRoles } from '../shared-doc-roles.mjs';
 import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent, safeSpawnSpecify } from '../ensure-skills.mjs';
 import { safeWrite } from '../writers/generate-io.mjs';
 
@@ -144,8 +145,68 @@ function askQuestion(prompt) {
   });
 }
 
+/**
+ * Confirm where a project actually keeps its canonical documents.
+ *
+ * Runs before init creates anything. If the role filenames already exist
+ * somewhere other than the directory the config points at, say so and offer to
+ * adopt that location, instead of reporting "no canonical docs" and scaffolding
+ * a second copy next to the real one.
+ *
+ * Writes `docs.roles` (the mechanism every validator already resolves through)
+ * plus a matching `requiredFiles.canonical`. Declaring only the latter leaves
+ * the content validators walking the conventional directory, where they find
+ * nothing and report "no matches" — checks disappear without anyone saying so.
+ *
+ * @returns {Promise<Record<string,string>|null>} adopted roles, or null
+ */
+async function confirmCanonicalLocation(projectDir, flags) {
+  const configPath = resolve(projectDir, '.docguard.json');
+  let existing = {};
+  if (existsSync(configPath)) {
+    try { existing = JSON.parse(readFileSync(configPath, 'utf-8')); } catch { return false; }
+  }
+  // An explicit mapping is the user's answer already; do not second-guess it.
+  if (existing.docs?.roles) return null;
+
+  const hits = detectCanonicalLayout(projectDir).filter(h => h.count >= 2);
+  if (hits.length === 0) return null;
+  const best = hits[0];
+  if (best.dir === 'docs-canonical') return null; // already conventional
+
+  console.log(`\n${c.bold}📁 Found existing canonical documents${c.reset}`);
+  console.log(`${c.dim}   DocGuard defaults to docs-canonical/, but ${Object.keys(best.roles).length} of its documents${c.reset}`);
+  console.log(`${c.dim}   already live in ${c.reset}${c.cyan}${best.dir}/${c.reset}${c.dim}:${c.reset}`);
+  for (const [role, path] of Object.entries(best.roles)) {
+    console.log(`     ${c.green}•${c.reset} ${path} ${c.dim}(${role})${c.reset}`);
+  }
+
+  if (!flags.skipPrompts && !flags.force) {
+    const answer = (await askQuestion(`\n   Use ${best.dir}/ as the canonical location? [Y/n] `)).trim().toLowerCase();
+    if (answer === 'n' || answer === 'no') {
+      console.log(`${c.dim}   Keeping docs-canonical/. Map them later with docs.roles in .docguard.json.${c.reset}\n`);
+      return null;
+    }
+  } else {
+    // Non-interactive: adopting what is on disk is the safe default, because
+    // the alternative is scaffolding a duplicate the user never asked for.
+    console.log(`${c.dim}   Adopting ${best.dir}/ (non-interactive).${c.reset}`);
+  }
+
+  const next = { ...existing };
+  next.docs = { ...(next.docs || {}), roles: { ...best.roles } };
+  next.requiredFiles = {
+    ...(next.requiredFiles || {}),
+    canonical: Object.values(best.roles).sort(),
+  };
+  writeFileSync(configPath, JSON.stringify(next, null, 2) + '\n');
+  console.log(`  ${c.green}✅${c.reset} .docguard.json now points at ${c.cyan}${best.dir}/${c.reset}\n`);
+  return best.roles;
+}
+
 // ── Init Command ─────────────────────────────────────────────────────────
 
+
 /**
  * v0.21 — Smart first-run detection.
  *
@@ -179,6 +240,13 @@ function shouldRunGenerate(projectDir, flags) {
   // detected as already-initialized, or the wizard re-triggers on every run.
   if (listCanonicalDocs(projectDir).length > 0) return false;
 
+  // listCanonicalDocs only walks the directories the config points at, so a
+  // project keeping the same documents somewhere else (docs/canonical/) read as
+  // EMPTY. Init then offered to reverse-engineer docs from code and would
+  // scaffold a second canonical directory beside the real one. Look for the
+  // role filenames anywhere before concluding a project has no documentation.
+  if (detectCanonicalLayout(projectDir).some(hit => hit.count >= 2)) return false;
+
   // Existing-code signals: any of cli/, src/, lib/, app/ as a directory.
   const codeDirs = ['cli', 'src', 'lib', 'app'];
   for (const d of codeDirs) {
@@ -198,7 +266,8 @@ function shouldRunGenerate(projectDir, flags) {
   return false;
 }
 
-export async function runInit(projectDir, config, flags) {
+export async function runInit(projectDir, configArg, flags) {
+  let config = configArg;
   // `--list` is read-only inventory owned by the hooks scaffolder. Routing it
   // through normal init can start prompts or create documentation before the
   // requested inventory is shown, which violates the command's read-only intent.
@@ -211,6 +280,19 @@ export async function runInit(projectDir, config, flags) {
     const { runHooks } = await import('./hooks.mjs');
     return runHooks(projectDir, config, flags);
   }
+  // Ask where the documents live before creating any. The adopted mapping has
+  // to reach the in-memory config as well: the skeleton path below reads it,
+  // and would otherwise create a second canonical directory it was just told
+  // not to use.
+  const adoptedRoles = await confirmCanonicalLocation(projectDir, flags);
+  if (adoptedRoles) {
+    config.docs = { ...(config.docs || {}), roles: { ...adoptedRoles } };
+    config.requiredFiles = {
+      ...(config.requiredFiles || {}),
+      canonical: Object.values(adoptedRoles).sort(),
+    };
+    config = applyDocRoles(projectDir, config);
+  }
   if (true) assertDefaultDocWrites(config);
   // v0.20: `--wizard` dispatches to the full interactive onboarding (formerly
   // `docguard setup`). Done before profile validation so the wizard can ask

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/cli/commands/trace.mjs

@@ -26,7 +26,7 @@ const CODE_EXTENSIONS = new Set([
 
 // v0.16-P2: language-aware patterns. The original JS/TS-only sets created
 // false-negative warnings on Python/Rust/Go/Java projects (reported by the
-// quick-recon-tool Python user: TEST-SPEC.md was flagged unlinked even
+// a downstream project Python user: TEST-SPEC.md was flagged unlinked even
 // though Python tests existed because `.test.mjs` didn't match `test_*.py`).
 import { TEST_PATTERNS, TRACE_MAP, isTraceableSource } from '../shared-trace-patterns.mjs';
 

{docguard_cli-0.41.5 → docguard_cli-0.41.7}/cli/scanners/api-doc.mjs

@@ -32,7 +32,7 @@ const HTTP_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', '
  *   optional c-all  `/shop/[[...filters]]`  → `/shop/{}`
  * Without the bracket rule, a doc written in Next.js `[id]` syntax never matched
  * the code-scan's `:id`, so every dynamic route double-fired as both
- * "documented-but-absent" and "undocumented" (field test: hugocross_revamp).
+ * "documented-but-absent" and "undocumented" (field test: a downstream project).
  * @param {string} raw
  * @returns {string} normalized path (e.g. "/api/users/{}") or '' if not a path
  */