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

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

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

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

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

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

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

@@ -7,6 +7,50 @@ 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`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docguard-cli
-Version: 0.41.6
+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.6 → 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.7/cli/shared-doc-roles.mjs

@@ -0,0 +1,246 @@
+/** Explicit document roles let existing repository layouts serve as canonical input. */
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, isAbsolute, join } from 'node:path';
+export const DOC_ROLES = Object.freeze({
+  architecture: 'docs-canonical/ARCHITECTURE.md', dataModel: 'docs-canonical/DATA-MODEL.md',
+  security: 'docs-canonical/SECURITY.md', testSpec: 'docs-canonical/TEST-SPEC.md',
+  environment: 'docs-canonical/ENVIRONMENT.md', apiReference: 'docs-canonical/API-REFERENCE.md',
+  requirements: 'docs-canonical/REQUIREMENTS.md',
+});
+export function docRolePath(config = {}, role) {
+  if (!Object.hasOwn(DOC_ROLES, role)) throw new Error('Unknown document role: ' + role);
+  const value = config.docs?.roles?.[role] ?? DOC_ROLES[role];
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0')) throw new Error('Invalid document path for role: ' + role);
+  const path = value.replace(/\\/g, '/');
+  if (config.docs?.roles?.[role] !== undefined && !path.toLowerCase().endsWith('.md')) throw new Error('Mapped document roles currently require Markdown (.md): ' + role);
+  if (isAbsolute(path) || /^[A-Za-z]:/.test(path) || path.split('/').some(p => p === '..' || p.toLowerCase() === '.local' || p.toLowerCase() === '.git')) throw new Error('Document role path must stay within the project: ' + role);
+  return path.startsWith('./') ? path.slice(2) : path;
+}
+export function resolveDocRole(projectDir, config, role) {
+  const rel = docRolePath(config, role);
+  // Opt-in mappings must not follow links into another repository/private data.
+  if (config.docs?.roles?.[role] !== undefined) {
+    let current = resolve(projectDir);
+    for (const part of rel.split('/')) {
+      current = join(current, part);
+      try { if (lstatSync(current).isSymbolicLink()) throw new Error('Document role path contains a symlink: ' + role); }
+      catch (e) { if (e.code !== 'ENOENT') throw e; }
+    }
+  }
+  return resolve(projectDir, rel);
+}
+export function applyDocRoles(projectDir, config) {
+  const roles = config.docs?.roles;
+  if (roles === undefined) return config;
+  if (!roles || typeof roles !== 'object' || Array.isArray(roles)) throw new Error('docs.roles must be an object');
+  const replacements = new Map();
+  for (const role of Object.keys(roles)) {
+    resolveDocRole(projectDir, config, role);
+    replacements.set(DOC_ROLES[role], docRolePath(config, role));
+  }
+  const requiredFiles = { ...config.requiredFiles, canonical: [...new Set([...(config.requiredFiles?.canonical || []).map(p => replacements.get(p) || p), ...replacements.values()])] };
+  const documentTypes = { ...config.documentTypes };
+  for (const [oldPath, newPath] of replacements) {
+    const old = documentTypes[oldPath] || {};
+    if (oldPath !== newPath) delete documentTypes[oldPath];
+    documentTypes[newPath] = { ...old, ...documentTypes[newPath], required: true, category: 'canonical' };
+  }
+  return { ...config, requiredFiles, documentTypes };
+}
+export function remapDocPath(config, path) {
+  const role = Object.keys(DOC_ROLES).find(key => DOC_ROLES[key] === path);
+  return role ? docRolePath(config, role) : path;
+}
+
+export function mappedRolesForPath(config = {}, path) {
+  const target = String(path).replace(/\\/g, '/').replace(/^\.\//, '');
+  return Object.keys(DOC_ROLES).filter(role => {
+    const configured = config.docs?.roles?.[role];
+    return configured !== undefined && docRolePath(config, role) === target && target !== DOC_ROLES[role];
+  });
+}
+
+export function isMappedDocPath(config = {}, path) {
+  return mappedRolesForPath(config, path).length > 0;
+}
+
+/**
+ * Authorize a whole-document write to custom role targets. New files are safe;
+ * existing files must explicitly grant full ownership and one file cannot be
+ * the whole-document target of several roles.
+ * @implements docguard.language-repository-coverage#FR-010
+ * @implements docguard.language-repository-coverage#FR-011
+ */
+export function assertMappedFullDocumentWrites(projectDir, config = {}, roles = Object.keys(DOC_ROLES)) {
+  const selected = roles.filter(role => Object.hasOwn(DOC_ROLES, role) && config.docs?.roles?.[role] !== undefined
+    && docRolePath(config, role) !== DOC_ROLES[role]);
+  const paths = new Map();
+  for (const role of selected) {
+    const rel = docRolePath(config, role);
+    if (!paths.has(rel)) paths.set(rel, []);
+    paths.get(rel).push(role);
+  }
+  for (const [rel, owners] of paths) {
+    const allOwners = mappedRolesForPath(config, rel);
+    if (allOwners.length > 1) {
+      throw new Error(`Mapped document ${rel} serves multiple roles (${allOwners.join(', ')}); whole-document generation is unavailable. Use unique source=code sections instead.`);
+    }
+    const role = owners[0];
+    const full = resolveDocRole(projectDir, config, role);
+    if (!existsSync(full)) continue;
+    const content = readFileSync(full, 'utf8');
+    if (!/^[ \t]*<!--\s*docguard:generated\s+true\s*-->[ \t]*$/mi.test(content)) {
+      throw new Error(`Mapped document ${rel} is not fully owned by DocGuard. Add unique source=code sections for bounded writes; --force cannot overwrite its prose.`);
+    }
+  }
+}
+
+export function assertDefaultDocWrites(config) {
+  if (Object.entries(config.docs?.roles || {}).some(([role, path]) => path !== DOC_ROLES[role])) {
+    throw new Error('Custom docs.roles currently support validation and read-only planning. Automatic document generation/repair is unavailable for mapped layouts; review and edit the existing documents directly.');
+  }
+}
+
+/** Markdown extensions a canonical document realistically uses. */
+const DOC_EXTENSIONS = new Set(['.md', '.markdown', '.mdx']);
+
+/**
+ * Names a role is known by in the wild, normalised.
+ *
+ * Matching the exact default filename only (`DATA-MODEL.md`) missed every real
+ * project: the same document ships as `data_model.md`, `datamodel.md`,
+ * `Data Model.md`, or `API.md` instead of `API-REFERENCE.md`. Separators, case
+ * and extension are all noise, so names are normalised to letters and digits
+ * before comparison and every plausible spelling collapses to one key.
+ *
+ * Kept deliberately tight. A directory has to hold at least two roles before it
+ * counts as canonical, so a lone root-level `SECURITY.md` — GitHub's security
+ * policy, not a design document — never triggers a match on its own.
+ */
+const ROLE_SYNONYMS = Object.freeze({
+  architecture: ['architecture', 'arch', 'systemdesign', 'design', 'systemarchitecture', 'technicaldesign', 'hld'],
+  dataModel:    ['datamodel', 'data', 'schema', 'dataschema', 'entities', 'erd', 'domainmodel', 'database'],
+  security:     ['security', 'threatmodel', 'securitymodel', 'securitydesign'],
+  testSpec:     ['testspec', 'tests', 'testing', 'testplan', 'teststrategy', 'qa', 'testcases'],
+  environment:  ['environment', 'env', 'setup', 'configuration', 'config', 'installation', 'install'],
+  apiReference: ['apireference', 'api', 'apidocs', 'apispec', 'endpoints', 'rest', 'openapi'],
+  requirements: ['requirements', 'reqs', 'prd', 'spec', 'functionalrequirements', 'userstories'],
+});
+
+const NORMALISED_ROLE = new Map();
+for (const [role, names] of Object.entries(ROLE_SYNONYMS)) {
+  for (const name of names) {
+    // First writer wins, so an earlier role keeps an ambiguous name.
+    if (!NORMALISED_ROLE.has(name)) NORMALISED_ROLE.set(name, role);
+  }
+}
+
+/** Normalise a filename to comparable letters and digits, or null if not a doc. */
+export function normaliseDocName(filename) {
+  const dot = filename.lastIndexOf('.');
+  if (dot <= 0) return null;
+  if (!DOC_EXTENSIONS.has(filename.slice(dot).toLowerCase())) return null;
+  const stem = filename.slice(0, dot).toLowerCase().replace(/[^a-z0-9]/g, '');
+  return stem || null;
+}
+
+/** The canonical role a filename denotes, or null. */
+export function roleForFilename(filename) {
+  const stem = normaliseDocName(filename);
+  return stem ? (NORMALISED_ROLE.get(stem) ?? null) : null;
+}
+
+/**
+ * Resolve a set of known document names to the files that actually exist.
+ *
+ * The literal-path approach — `existsSync(resolve(dir, 'ROADMAP.md'))` for each
+ * name — fails two ways. It misses every spelling not in the list (`PLAN.md`,
+ * `TASKS.md`, `docs/ROADMAP.md`), and it is only case-insensitive by accident:
+ * on macOS the probe matches `roadmap.md`, on Linux it does not, so the same
+ * repository is judged differently by platform.
+ *
+ * Reading each directory and normalising what is there fixes both: matching is
+ * explicitly case- and separator-insensitive everywhere, and one alias table
+ * covers the spellings people use.
+ *
+ * @param {string} projectDir
+ * @param {string[]} aliases  normalised names to accept (see normaliseDocName)
+ * @param {string[]} dirs     project-relative directories to search ('' = root)
+ * @returns {string[]} project-relative POSIX paths, de-duplicated, existing
+ */
+export function findDocsByName(projectDir, aliases, dirs) {
+  const want = new Set(aliases);
+  const out = [];
+  for (const dir of dirs) {
+    const abs = dir ? resolve(projectDir, dir) : resolve(projectDir);
+    let entries;
+    try { entries = readdirSync(abs, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      const stem = normaliseDocName(entry.name);
+      if (!stem || !want.has(stem)) continue;
+      const rel = dir ? `${dir}/${entry.name}` : entry.name;
+      if (!out.includes(rel)) out.push(rel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Find directories that already hold canonical documents.
+ *
+ * DocGuard assumed `docs-canonical/` and asked afterwards. A project keeping the
+ * same documents in `docs/canonical/` therefore looked EMPTY: `init` reported
+ * "no canonical docs", offered to reverse-engineer them from code, and would
+ * scaffold a second canonical directory beside the real one. The documents were
+ * there the whole time; nothing ever looked.
+ *
+ * Detection is by role BASENAME, because the filenames are the convention that
+ * survives relocation — the directory is the part people change.
+ *
+ * Returns candidates ranked by how many roles each directory holds, so a caller
+ * can confirm the strongest one rather than guess. Never throws: an unreadable
+ * subtree simply contributes nothing.
+ *
+ * @param {string} projectDir
+ * @param {{maxDepth?: number, skip?: Set<string>}} [opts]
+ * @returns {Array<{dir: string, roles: Record<string,string>, count: number}>}
+ */
+export function detectCanonicalLayout(projectDir, opts = {}) {
+  const maxDepth = opts.maxDepth ?? 4;
+  const skip = opts.skip ?? new Set([
+    'node_modules', '.git', '.local', 'dist', 'build', 'coverage',
+    'vendor', '__pycache__', '.venv', 'venv', '.next', 'target', '.testguard',
+  ]);
+
+  const byBasename = roleForFilename;
+
+  const found = new Map(); // dir -> { role -> relative path }
+
+  const walk = (absDir, relDir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const name = entry.name;
+      if (entry.isDirectory()) {
+        if (skip.has(name) || name.startsWith('.')) continue;
+        walk(join(absDir, name), relDir ? `${relDir}/${name}` : name, depth + 1);
+        continue;
+      }
+      const role = byBasename(name);
+      if (!role) continue;
+      const key = relDir || '.';
+      if (!found.has(key)) found.set(key, {});
+      found.get(key)[role] = relDir ? `${relDir}/${name}` : name;
+    }
+  };
+  walk(resolve(projectDir), '', 0);
+
+  return [...found.entries()]
+    .map(([dir, roles]) => ({ dir, roles, count: Object.keys(roles).length }))
+    // Strongest first; the conventional directory wins an exact tie so an
+    // already-conventional project is never told to "relocate" to itself.
+    .sort((a, b) => b.count - a.count
+      || (a.dir === 'docs-canonical' ? -1 : b.dir === 'docs-canonical' ? 1 : a.dir.localeCompare(b.dir)));
+}

{docguard_cli-0.41.6 → docguard_cli-0.41.7}/cli/validators/test-spec.mjs

@@ -226,10 +226,20 @@ export function validateTestSpec(projectDir, config) {
   // somewhere — that rendered a confident green ✅ for a doc that mapped nothing.
   if (total === 0) {
     // 1. Check top-level test dirs
-    const commonTestDirs = ['tests', 'test', '__tests__', 'spec'];
-    const hasTestDir = commonTestDirs.some(d =>
-      existsSync(resolve(projectDir, d))
-    );
+    // Match by normalised name rather than exact spelling: `Tests/`, `testing/`,
+    // `e2e/` and `integration/` are the same signal as `tests/`, and probing for
+    // literal names was case-insensitive only by accident (it matched on macOS
+    // and not on Linux, so CI and a laptop disagreed).
+    const TEST_DIR_NAMES = new Set([
+      'tests', 'test', 'spec', 'specs', 'testing',
+      'e2e', 'integration', 'unit', 'acceptance',
+    ]);
+    const normaliseDir = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+    let hasTestDir = false;
+    try {
+      hasTestDir = readdirSync(projectDir, { withFileTypes: true })
+        .some(e => e.isDirectory() && TEST_DIR_NAMES.has(normaliseDir(e.name)));
+    } catch { /* unreadable root: fall through to the other signals */ }
 
     // 2. Check co-located tests (honors config.sourceRoot + workspaces)
     let hasColocated = false;

{docguard_cli-0.41.6 → docguard_cli-0.41.7}/cli/validators/todo-tracking.mjs

@@ -20,6 +20,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, extname } from 'node:path';
 import { shouldIgnore, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { findDocsByName } from '../shared-doc-roles.mjs';
 import { parseJsTs, walk } from '../scanners/js-ast.mjs';
 
 const IGNORE_DIRS = new Set([
@@ -391,13 +392,22 @@ function checkUntrackedTodos(projectDir, config) {
  */
 function loadTrackingDocs(projectDir, config) {
   const docs = [];
+  // Where a project tracks work, by name rather than by exact path. Probing for
+  // literal paths missed `docs/ROADMAP.md`, `PLAN.md` and `TASKS.md`, and was
+  // case-insensitive only by accident — `existsSync('ROADMAP.md')` matches
+  // `roadmap.md` on macOS but not on Linux, so CI and a laptop disagreed about
+  // whether the same TODO was tracked.
+  const TRACKING_ALIASES = [
+    'roadmap', 'currentstate', 'todo', 'todos', 'backlog',
+    'plan', 'plans', 'tasks', 'milestones', 'worklog', 'changelog',
+  ];
+  const TRACKING_DIRS = ['', 'docs', 'doc', 'documentation', 'docs-canonical', 'docs-implementation'];
+
   const trackingFiles = [
-    'ROADMAP.md', 'CURRENT-STATE.md', 'TODO.md', 'BACKLOG.md',
-    'docs-canonical/ARCHITECTURE.md', 'CHANGELOG.md',
-    // v0.27 (field report #6): many projects keep the roadmap/backlog under
-    // docs-canonical/ — a TODO tracked there was wrongly read as "untracked".
-    'docs-canonical/ROADMAP.md', 'docs-canonical/CURRENT-STATE.md',
-    'docs-canonical/BACKLOG.md', 'docs-canonical/TODO.md',
+    ...findDocsByName(projectDir, TRACKING_ALIASES, TRACKING_DIRS),
+    // ARCHITECTURE is a tracking home only in the canonical sense; it is not a
+    // work list, so it stays an explicit entry rather than joining the aliases.
+    'docs-canonical/ARCHITECTURE.md',
     ...(config.todoTracking?.trackingFiles || []),
   ];
 

{docguard_cli-0.41.6 → docguard_cli-0.41.7}/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.41.6"
+  version: "0.41.7"
   description: "Documentation integrity for AI-assisted repositories: lifecycle registry, drift validation, traceability, safe archival, SARIF/JUnit, MCP, GitHub Actions, and Spec Kit hooks."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

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

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

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

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

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

{docguard_cli-0.41.6 → docguard_cli-0.41.7}/extensions/spec-kit-docguard/templates/github-workflows/docguard-autofix.yml

@@ -44,7 +44,7 @@ jobs:
           fetch-depth: 0
 
       - name: Run DocGuard fix --write + auto-commit + PR comment
-        uses: raccioly/docguard@v0.41.6
+        uses: raccioly/docguard@v0.41.7
         with:
           command: fix
           auto-commit: 'true'