docguard-cli 0.22.1 → 0.23.0

package/README.md

@@ -106,9 +106,9 @@ Recent highlights across the v0.16 → v0.19 line:
   two commits. Pinpoints regressions without re-running the full suite by hand.
 - **`docguard upgrade --apply --pr`** — when the config schema bumps, DocGuard migrates
   `.docguard.json` for you and (optionally) opens a PR with the change.
-- **Language-aware `docguard trace`** — the standalone `trace` command understands Python, Rust, Go,
-  Java, Ruby, and PHP layouts in addition to JS/TS. (The guard-time Traceability validator is JS/TS-first
-  today; broader language parity is on the v0.23 roadmap.)
+- **Language-aware traceability** — both `docguard trace` *and* the guard-time Traceability validator
+  understand Python, Rust, Go, Java, Ruby, and PHP layouts in addition to JS/TS, via a shared pattern
+  set (`cli/shared-trace-patterns.mjs`) so the two never drift apart.
 - **Per-validator severity overrides** — escalate `freshness` to `high` for production repos,
   demote `doc-quality` to `low` for prototypes. Configurable per-project.
 - **JSON Schema for `.docguard.json`** — IDE autocomplete, in-line docs, and validation via

package/cli/commands/demo.mjs

@@ -25,7 +25,7 @@ import { spawnSync } from 'node:child_process';
 import { c } from '../shared.mjs';
 import { runGuardInternal, classifyResult } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
-import { loadConfig } from '../docguard.mjs';
+import { loadConfig } from '../config.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);

package/cli/commands/diff.mjs

@@ -347,22 +347,33 @@ function diffTests(dir, config = {}) {
 
   // Glob-aware matching (documented entries are often patterns or basenames).
   const codeArr = [...codeTests];
-  const docArr = [...docTests];
-  const matches = (docEntry, codeRel) => {
+
+  // PERFORMANCE OPTIMIZATION: Pre-compile regular expressions to avoid O(N*M)
+  // instantiation bottlenecks inside the nested .filter and .some loops below.
+  const docMatchers = [...docTests].map(docEntry => {
     const entry = String(docEntry).trim();
     const hasSlash = entry.includes('/');
     const target = hasSlash ? entry : basename(entry);
-    const subject = hasSlash ? codeRel : basename(codeRel);
     const rx = new RegExp('^' + target.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*+/g, '.*') + '$');
-    return rx.test(subject);
+
+    return {
+      original: docEntry,
+      hasSlash,
+      rx
+    };
+  });
+
+  const matches = (matcher, codeRel) => {
+    const subject = matcher.hasSlash ? codeRel : basename(codeRel);
+    return matcher.rx.test(subject);
   };
 
   return {
     title: 'Test Files',
     icon: '🧪',
-    onlyInDocs: docArr.filter(d => !codeArr.some(c => matches(d, c))),
-    onlyInCode: codeArr.filter(c => !docArr.some(d => matches(d, c))),
-    matched: docArr.filter(d => codeArr.some(c => matches(d, c))),
+    onlyInDocs: docMatchers.filter(m => !codeArr.some(c => matches(m, c))).map(m => m.original),
+    onlyInCode: codeArr.filter(c => !docMatchers.some(m => matches(m, c))),
+    matched: docMatchers.filter(m => codeArr.some(c => matches(m, c))).map(m => m.original),
   };
 }
 

package/cli/commands/trace.mjs

@@ -25,106 +25,8 @@ const CODE_EXTENSIONS = new Set([
 // false-negative warnings on Python/Rust/Go/Java projects (reported by the
 // quick-recon-tool Python user: TEST-SPEC.md was flagged unlinked even
 // though Python tests existed because `.test.mjs` didn't match `test_*.py`).
-// Each `glob` is now a single regex that ALSO matches the equivalent
-// patterns in other ecosystems we care about.
-const TEST_PATTERNS = [
-  // JS/TS
-  /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.test\.(mjs|cjs)$/,
-  // Python — pytest conventions
-  /(^|\/)test_[^/]+\.py$/, /[^/]+_test\.py$/, /(^|\/)tests?\/[^/]+\.py$/,
-  // Go
-  /_test\.go$/,
-  // Java/Kotlin — JUnit/TestNG conventions
-  /(?:Test|Tests|Spec|IT)\.(?:java|kt)$/,
-  // Rust — tests live in tests/ or as #[cfg(test)] modules; pattern below covers integration tests
-  /(^|\/)tests\/[^/]+\.rs$/,
-  // Ruby/RSpec
-  /_spec\.rb$/, /_test\.rb$/,
-  // PHP/PHPUnit
-  /Test\.php$/, /(^|\/)tests?\/[^/]+\.php$/,
-];
+import { TEST_PATTERNS, TRACE_MAP } from '../shared-trace-patterns.mjs';
 
-/**
- * Mapping of canonical documents to the code/config artifacts they trace to.
- * Each entry defines what source patterns prove coverage of that canonical doc.
- *
- * v0.16-P2: every glob is now multi-language. JS/TS patterns are preserved
- * (the most common case); Python/Rust/Go/Java/Ruby/PHP equivalents are
- * appended so non-JS projects don't false-negative.
- */
-const TRACE_MAP = {
-  'ARCHITECTURE.md': {
-    standard: 'arc42 / C4 Model',
-    sourcePatterns: [
-      // Entry points: JS (index/main/app/server.[jt]sx?), Python (__main__.py, main.py, app.py, cli.py),
-      // Go (main.go, cmd/), Rust (main.rs, lib.rs), Java (Application.java, Main.java)
-      { label: 'Entry points', glob: /(?:^|\/)(?:index|main|app|server|cli|__main__|Application|Main)\.(?:[jt]sx?|mjs|cjs|py|go|rs|java|kt|rb)$|(?:^|\/)cmd\// },
-      // Config files: JS (package.json/tsconfig/next.config/vite.config), Python (pyproject.toml/setup.py/setup.cfg),
-      // Rust (Cargo.toml), Go (go.mod), Java/Kotlin (pom.xml/build.gradle), Ruby (Gemfile), PHP (composer.json)
-      { label: 'Config files', glob: /(?:^|\/)(?:package\.json|tsconfig|next\.config|vite\.config|pyproject\.toml|setup\.(?:py|cfg)|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json)/ },
-      // Route handlers + module dirs
-      { label: 'Route handlers / modules', glob: /(?:^|\/)(?:routes?|api|pages|app|controllers?|handlers?|views?|services?)\// },
-    ],
-  },
-  'DATA-MODEL.md': {
-    standard: 'C4 Component / ER (Chen)',
-    sourcePatterns: [
-      // Schema/model files: JS (schema/model/entity/migration/prisma), Python (models.py/schema.py/Pydantic/SQLAlchemy),
-      // Go (models/), Rust (struct definitions in models/), Java (entities/)
-      { label: 'Schema definitions', glob: /(?:schema|model|entity|migration|prisma)/i },
-      // Type definitions: JS types.ts, Python types.py, Rust types.rs
-      { label: 'Type definitions', glob: /(?:^|\/)types?\.(?:[jt]sx?|mjs|py|rs|go|java|kt)$/ },
-      // ORM/database libs (any language)
-      { label: 'Database configs', glob: /(?:drizzle|knex|sequelize|typeorm|sqlalchemy|alembic|django|diesel|sqlx|gorm|hibernate|active.?record)/i },
-    ],
-  },
-  'TEST-SPEC.md': {
-    standard: 'ISO/IEC/IEEE 29119-3',
-    sourcePatterns: [
-      // Test files in any ecosystem (mirrors TEST_PATTERNS above)
-      { label: 'Test files', glob: /\.(?:test|spec)\.(?:mjs|cjs|[jt]sx?)$|(?:^|\/)test_[^/]+\.py$|[^/]+_test\.py$|_test\.go$|(?:Test|Spec|IT)\.(?:java|kt)$|(?:^|\/)tests?\/[^/]+\.(?:rs|py|rb|php)$|_(?:spec|test)\.rb$|Test\.php$/ },
-      // Test runner configs: JS (jest/vitest/playwright/cypress), Python (pytest.ini/tox.ini), Rust (Cargo.toml has [[test]]),
-      // Java (pom.xml/build.gradle), Go (no config file typically)
-      { label: 'Test config', glob: /(?:jest|vitest|playwright|cypress|pytest|tox|phpunit)\.config|(?:^|\/)pytest\.ini$|(?:^|\/)tox\.ini$|(?:^|\/)phpunit\.xml$/ },
-      { label: 'E2E / integration tests', glob: /(?:^|\/)(?:e2e|integration|tests?\/integration)\// },
-    ],
-  },
-  'SECURITY.md': {
-    standard: 'OWASP ASVS v4.0',
-    sourcePatterns: [
-      // Auth modules — semantic, language-agnostic
-      { label: 'Auth modules', glob: /(?:auth|login|session|jwt|oauth|middleware|guard|csrf|cors|permissions?|policy)/i },
-      // Secret configs — .env family + secrets.* / keyring patterns
-      { label: 'Secret configs', glob: /\.env(?:\.|$)|(?:^|\/)secrets?\.(?:py|js|ts|yaml|yml|json)$|keyring/i },
-      // Gitignore + ignore files
-      { label: 'Ignore files', glob: /^\.(?:git|docker|npm)ignore$/ },
-    ],
-  },
-  'ENVIRONMENT.md': {
-    standard: '12-Factor App',
-    sourcePatterns: [
-      // .env family across all ecosystems
-      { label: 'Env files', glob: /\.env(?:\.|$)|(?:^|\/)\.envrc$/ },
-      // Containerization
-      { label: 'Container configs', glob: /(?:^|\/)(?:Dockerfile|docker-compose|\.dockerignore|Containerfile)/ },
-      // Python venv / requirements / lock files
-      { label: 'Python env', glob: /(?:^|\/)(?:requirements[^/]*\.txt|Pipfile|poetry\.lock|uv\.lock|pyproject\.toml)$/ },
-      // CI/CD configs
-      { label: 'CI/CD configs', glob: /(?:^|\/)\.(?:github|gitlab-ci|circleci|drone|gitea)/ },
-    ],
-  },
-  'API-REFERENCE.md': {
-    standard: 'OpenAPI 3.1',
-    sourcePatterns: [
-      // Route handlers + Python views/urls + Java/Spring controllers
-      { label: 'Route handlers', glob: /(?:^|\/)(?:routes?|controllers?|handlers?|views?|urls?\.py)/ },
-      // OpenAPI / API specs
-      { label: 'API spec', glob: /(?:openapi|swagger|asyncapi)\.(?:json|ya?ml)/ },
-      // Middleware / decorators
-      { label: 'API middleware', glob: /(?:^|\/)middleware\/|decorators?\.py$/ },
-    ],
-  },
-};
 
 /**
  * L-2 / S-3 — Reverse trace: given a code file, find which canonical doc

package/cli/config.mjs

@@ -0,0 +1,228 @@
+/**
+ * DocGuard — configuration loading.
+ *
+ * Extracted from docguard.mjs (v0.23.0) to break the demo.mjs → docguard.mjs
+ * import cycle. demo.mjs runs guard/score against a temp fixture and needs
+ * loadConfig, but docguard.mjs statically imports every command (including
+ * demo). Importing loadConfig from here — which only pulls shared.mjs and
+ * shared-ignore.mjs, never a command module — keeps the import graph acyclic.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+import { c, PROFILES } from './shared.mjs';
+import { mergeIgnoreFile } from './shared-ignore.mjs';
+
+export function loadConfig(projectDir) {
+  const configPath = resolve(projectDir, '.docguard.json');
+  const defaults = {
+    projectName: basename(projectDir),
+    version: '0.2',
+    profile: 'standard',
+    requiredFiles: {
+      canonical: [
+        'docs-canonical/ARCHITECTURE.md',
+        'docs-canonical/DATA-MODEL.md',
+        'docs-canonical/SECURITY.md',
+        'docs-canonical/TEST-SPEC.md',
+        'docs-canonical/ENVIRONMENT.md',
+      ],
+      agentFile: ['AGENTS.md', 'CLAUDE.md'],
+      changelog: 'CHANGELOG.md',
+      driftLog: 'DRIFT-LOG.md',
+    },
+    // All CDD document types — required vs optional
+    documentTypes: {
+      // Canonical (design intent) — required by default
+      'docs-canonical/ARCHITECTURE.md':  { required: true,  category: 'canonical',      description: 'System design, components, layer boundaries' },
+      'docs-canonical/DATA-MODEL.md':    { required: true,  category: 'canonical',      description: 'Database schemas, entities, relationships' },
+      'docs-canonical/SECURITY.md':      { required: true,  category: 'canonical',      description: 'Authentication, authorization, secrets management' },
+      'docs-canonical/TEST-SPEC.md':     { required: true,  category: 'canonical',      description: 'Test categories, coverage rules, service-to-test map' },
+      'docs-canonical/ENVIRONMENT.md':   { required: true,  category: 'canonical',      description: 'Environment variables, setup steps, prerequisites' },
+      'docs-canonical/DEPLOYMENT.md':    { required: false, category: 'canonical',      description: 'Infrastructure, CI/CD pipeline, DNS, monitoring' },
+      'docs-canonical/ADR.md':           { required: false, category: 'canonical',      description: 'Architecture Decision Records with rationale' },
+      // Implementation (current state) — optional by default
+      'docs-implementation/KNOWN-GOTCHAS.md':    { required: false, category: 'implementation', description: 'Lessons learned — symptom/gotcha/fix format' },
+      'docs-implementation/TROUBLESHOOTING.md':   { required: false, category: 'implementation', description: 'Error diagnosis guides by category' },
+      'docs-implementation/RUNBOOKS.md':          { required: false, category: 'implementation', description: 'Operational procedures (deploy, rollback, backup)' },
+      'docs-implementation/CURRENT-STATE.md':     { required: false, category: 'implementation', description: 'Deployment status, feature completion, tech debt' },
+      'docs-implementation/VENDOR-BUGS.md':       { required: false, category: 'implementation', description: 'Third-party bug tracker with workarounds' },
+      // Root files
+      'AGENTS.md':     { required: true,  category: 'agent',    description: 'AI agent behavior rules and project context' },
+      'CHANGELOG.md':  { required: true,  category: 'tracking', description: 'All notable changes per Keep a Changelog format' },
+      'DRIFT-LOG.md':  { required: true,  category: 'tracking', description: 'Documented deviations from canonical docs' },
+      'ROADMAP.md':    { required: false, category: 'tracking', description: 'Project phases, feature tracking, vision' },
+    },
+    sourcePatterns: {
+      services: 'src/services/**/*.{ts,js,py,java}',
+      routes: 'src/routes/**/*.{ts,js,py,java}',
+      tests: 'tests/**/*.test.{ts,js,py,java}',
+    },
+    validators: {
+      structure: true,
+      docsSync: true,
+      drift: true,
+      changelog: true,
+      architecture: false,
+      testSpec: true,
+      security: false,
+      environment: true,
+      freshness: true,
+    },
+  };
+
+  if (existsSync(configPath)) {
+    try {
+      const userConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
+
+      // Apply profile presets BEFORE merging user config
+      // Profile sets the baseline, user config can override anything
+      const profileName = userConfig.profile || defaults.profile;
+      const profilePreset = PROFILES[profileName];
+      const withProfile = profilePreset
+        ? deepMerge(defaults, profilePreset)
+        : defaults;
+
+      // v0.17-P4: normalize validator/severity keys before merging so the
+      // user can write either kebab-case (`test-spec`) or camelCase (`testSpec`)
+      // and the internal lookups (always camelCase) still hit.
+      const merged = deepMerge(withProfile, normalizeConfig(userConfig));
+      merged.profile = profileName;
+
+      // Auto-detect project type if not set
+      if (!merged.projectType) {
+        merged.projectType = autoDetectProjectType(projectDir);
+      }
+      // Ensure projectTypeConfig has sensible defaults based on type
+      merged.projectTypeConfig = {
+        ...getProjectTypeDefaults(merged.projectType),
+        ...(merged.projectTypeConfig || {}),
+      };
+      // Normalize testPattern (string) → testPatterns (array) for backward compat
+      if (merged.testPattern && !merged.testPatterns) {
+        merged.testPatterns = [merged.testPattern];
+      } else if (merged.testPattern && merged.testPatterns) {
+        // Both set — merge, deduplicate
+        if (!merged.testPatterns.includes(merged.testPattern)) {
+          merged.testPatterns.push(merged.testPattern);
+        }
+      }
+      // Merge .docguardignore patterns into config.ignore so every validator
+      // honors them without having to know about the file.
+      mergeIgnoreFile(projectDir, merged);
+      return merged;
+    } catch (e) {
+      console.error(`${c.red}Error parsing .docguard.json: ${e.message}${c.reset}`);
+      process.exit(1);
+    }
+  }
+
+  // No config file — auto-detect everything
+  defaults.projectType = autoDetectProjectType(projectDir);
+  defaults.projectTypeConfig = getProjectTypeDefaults(defaults.projectType);
+  // .docguardignore is read even when no .docguard.json exists — keeps
+  // ignore-only projects (no config but want to skip paths) working.
+  mergeIgnoreFile(projectDir, defaults);
+  return defaults;
+}
+
+// PROFILES is exported from shared.mjs (re-exported at line 43)
+
+/**
+ * Auto-detect project type from package.json and file structure.
+ * Returns: 'cli' | 'library' | 'webapp' | 'api' | 'unknown'
+ */
+function autoDetectProjectType(dir) {
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+      // CLI tool: has "bin" field
+      if (pkg.bin) return 'cli';
+
+      // Web app: has a frontend framework
+      if (allDeps.next || allDeps.react || allDeps.vue || allDeps['@angular/core'] ||
+          allDeps.svelte || allDeps.nuxt || allDeps['@sveltejs/kit']) return 'webapp';
+
+      // API: has a server framework but no frontend
+      if (allDeps.express || allDeps.fastify || allDeps.hono || allDeps.koa) return 'api';
+
+      // Library: has "main" or "exports" and no framework
+      if (pkg.main || pkg.exports || pkg.module) return 'library';
+    } catch { /* fall through */ }
+  }
+
+  // Python project
+  if (existsSync(resolve(dir, 'manage.py'))) return 'webapp';
+  if (existsSync(resolve(dir, 'setup.py')) || existsSync(resolve(dir, 'pyproject.toml'))) return 'library';
+
+  return 'unknown';
+}
+
+/**
+ * Get default projectTypeConfig for a given project type.
+ */
+function getProjectTypeDefaults(type) {
+  const defaults = {
+    cli:     { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false, testFramework: 'node:test', runCommand: null },
+    library: { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false, testFramework: 'vitest',    runCommand: null },
+    webapp:  { needsEnvVars: true,  needsEnvExample: true,  needsE2E: true,  needsDatabase: true,  testFramework: 'vitest',    runCommand: 'npm run dev' },
+    api:     { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true,  testFramework: 'vitest',    runCommand: 'npm run dev' },
+    unknown: { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true,  testFramework: null,        runCommand: null },
+  };
+  return defaults[type] || defaults.unknown;
+}
+
+/**
+ * v0.17-P4: normalize validator-key naming so users can write either
+ * `validators: { "test-spec": true }` (kebab-case, matches CLI display)
+ * or `validators: { testSpec: true }` (camelCase, matches JSON internals)
+ * in `.docguard.json`. We normalize the WHOLE config tree's known validator
+ * keys to camelCase before merging. Same treatment applied to `severity`.
+ *
+ * Non-validator keys are left alone. Unknown keys (forward-compat) are
+ * normalized blindly: kebab-case→camelCase always.
+ */
+const _KNOWN_VALIDATORS = [
+  'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
+  'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
+  'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
+  'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
+  'canonicalSync', 'surfaceSync', 'metricsConsistency',
+];
+
+function _kebabToCamel(k) {
+  return k.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+
+function _normalizeValidatorKeys(map) {
+  if (!map || typeof map !== 'object' || Array.isArray(map)) return map;
+  const out = {};
+  for (const [k, v] of Object.entries(map)) {
+    const normalized = k.includes('-') ? _kebabToCamel(k) : k;
+    out[normalized] = v;
+  }
+  return out;
+}
+
+function normalizeConfig(cfg) {
+  if (!cfg || typeof cfg !== 'object') return cfg;
+  const out = { ...cfg };
+  if (out.validators) out.validators = _normalizeValidatorKeys(out.validators);
+  if (out.severity)   out.severity   = _normalizeValidatorKeys(out.severity);
+  return out;
+}
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      result[key] = deepMerge(target[key] || {}, source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}

package/cli/docguard.mjs

@@ -49,224 +49,9 @@ import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
 import { c, PROFILES } from './shared.mjs';
-import { mergeIgnoreFile } from './shared-ignore.mjs';
+import { loadConfig } from './config.mjs';
 export { c, PROFILES };
 
-// ── Config Loading ─────────────────────────────────────────────────────────
-export function loadConfig(projectDir) {
-  const configPath = resolve(projectDir, '.docguard.json');
-  const defaults = {
-    projectName: basename(projectDir),
-    version: '0.2',
-    profile: 'standard',
-    requiredFiles: {
-      canonical: [
-        'docs-canonical/ARCHITECTURE.md',
-        'docs-canonical/DATA-MODEL.md',
-        'docs-canonical/SECURITY.md',
-        'docs-canonical/TEST-SPEC.md',
-        'docs-canonical/ENVIRONMENT.md',
-      ],
-      agentFile: ['AGENTS.md', 'CLAUDE.md'],
-      changelog: 'CHANGELOG.md',
-      driftLog: 'DRIFT-LOG.md',
-    },
-    // All CDD document types — required vs optional
-    documentTypes: {
-      // Canonical (design intent) — required by default
-      'docs-canonical/ARCHITECTURE.md':  { required: true,  category: 'canonical',      description: 'System design, components, layer boundaries' },
-      'docs-canonical/DATA-MODEL.md':    { required: true,  category: 'canonical',      description: 'Database schemas, entities, relationships' },
-      'docs-canonical/SECURITY.md':      { required: true,  category: 'canonical',      description: 'Authentication, authorization, secrets management' },
-      'docs-canonical/TEST-SPEC.md':     { required: true,  category: 'canonical',      description: 'Test categories, coverage rules, service-to-test map' },
-      'docs-canonical/ENVIRONMENT.md':   { required: true,  category: 'canonical',      description: 'Environment variables, setup steps, prerequisites' },
-      'docs-canonical/DEPLOYMENT.md':    { required: false, category: 'canonical',      description: 'Infrastructure, CI/CD pipeline, DNS, monitoring' },
-      'docs-canonical/ADR.md':           { required: false, category: 'canonical',      description: 'Architecture Decision Records with rationale' },
-      // Implementation (current state) — optional by default
-      'docs-implementation/KNOWN-GOTCHAS.md':    { required: false, category: 'implementation', description: 'Lessons learned — symptom/gotcha/fix format' },
-      'docs-implementation/TROUBLESHOOTING.md':   { required: false, category: 'implementation', description: 'Error diagnosis guides by category' },
-      'docs-implementation/RUNBOOKS.md':          { required: false, category: 'implementation', description: 'Operational procedures (deploy, rollback, backup)' },
-      'docs-implementation/CURRENT-STATE.md':     { required: false, category: 'implementation', description: 'Deployment status, feature completion, tech debt' },
-      'docs-implementation/VENDOR-BUGS.md':       { required: false, category: 'implementation', description: 'Third-party bug tracker with workarounds' },
-      // Root files
-      'AGENTS.md':     { required: true,  category: 'agent',    description: 'AI agent behavior rules and project context' },
-      'CHANGELOG.md':  { required: true,  category: 'tracking', description: 'All notable changes per Keep a Changelog format' },
-      'DRIFT-LOG.md':  { required: true,  category: 'tracking', description: 'Documented deviations from canonical docs' },
-      'ROADMAP.md':    { required: false, category: 'tracking', description: 'Project phases, feature tracking, vision' },
-    },
-    sourcePatterns: {
-      services: 'src/services/**/*.{ts,js,py,java}',
-      routes: 'src/routes/**/*.{ts,js,py,java}',
-      tests: 'tests/**/*.test.{ts,js,py,java}',
-    },
-    validators: {
-      structure: true,
-      docsSync: true,
-      drift: true,
-      changelog: true,
-      architecture: false,
-      testSpec: true,
-      security: false,
-      environment: true,
-      freshness: true,
-    },
-  };
-
-  if (existsSync(configPath)) {
-    try {
-      const userConfig = JSON.parse(readFileSync(configPath, 'utf-8'));
-
-      // Apply profile presets BEFORE merging user config
-      // Profile sets the baseline, user config can override anything
-      const profileName = userConfig.profile || defaults.profile;
-      const profilePreset = PROFILES[profileName];
-      const withProfile = profilePreset
-        ? deepMerge(defaults, profilePreset)
-        : defaults;
-
-      // v0.17-P4: normalize validator/severity keys before merging so the
-      // user can write either kebab-case (`test-spec`) or camelCase (`testSpec`)
-      // and the internal lookups (always camelCase) still hit.
-      const merged = deepMerge(withProfile, normalizeConfig(userConfig));
-      merged.profile = profileName;
-
-      // Auto-detect project type if not set
-      if (!merged.projectType) {
-        merged.projectType = autoDetectProjectType(projectDir);
-      }
-      // Ensure projectTypeConfig has sensible defaults based on type
-      merged.projectTypeConfig = {
-        ...getProjectTypeDefaults(merged.projectType),
-        ...(merged.projectTypeConfig || {}),
-      };
-      // Normalize testPattern (string) → testPatterns (array) for backward compat
-      if (merged.testPattern && !merged.testPatterns) {
-        merged.testPatterns = [merged.testPattern];
-      } else if (merged.testPattern && merged.testPatterns) {
-        // Both set — merge, deduplicate
-        if (!merged.testPatterns.includes(merged.testPattern)) {
-          merged.testPatterns.push(merged.testPattern);
-        }
-      }
-      // Merge .docguardignore patterns into config.ignore so every validator
-      // honors them without having to know about the file.
-      mergeIgnoreFile(projectDir, merged);
-      return merged;
-    } catch (e) {
-      console.error(`${c.red}Error parsing .docguard.json: ${e.message}${c.reset}`);
-      process.exit(1);
-    }
-  }
-
-  // No config file — auto-detect everything
-  defaults.projectType = autoDetectProjectType(projectDir);
-  defaults.projectTypeConfig = getProjectTypeDefaults(defaults.projectType);
-  // .docguardignore is read even when no .docguard.json exists — keeps
-  // ignore-only projects (no config but want to skip paths) working.
-  mergeIgnoreFile(projectDir, defaults);
-  return defaults;
-}
-
-// PROFILES is exported from shared.mjs (re-exported at line 43)
-
-/**
- * Auto-detect project type from package.json and file structure.
- * Returns: 'cli' | 'library' | 'webapp' | 'api' | 'unknown'
- */
-function autoDetectProjectType(dir) {
-  const pkgPath = resolve(dir, 'package.json');
-  if (existsSync(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-      const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
-
-      // CLI tool: has "bin" field
-      if (pkg.bin) return 'cli';
-
-      // Web app: has a frontend framework
-      if (allDeps.next || allDeps.react || allDeps.vue || allDeps['@angular/core'] ||
-          allDeps.svelte || allDeps.nuxt || allDeps['@sveltejs/kit']) return 'webapp';
-
-      // API: has a server framework but no frontend
-      if (allDeps.express || allDeps.fastify || allDeps.hono || allDeps.koa) return 'api';
-
-      // Library: has "main" or "exports" and no framework
-      if (pkg.main || pkg.exports || pkg.module) return 'library';
-    } catch { /* fall through */ }
-  }
-
-  // Python project
-  if (existsSync(resolve(dir, 'manage.py'))) return 'webapp';
-  if (existsSync(resolve(dir, 'setup.py')) || existsSync(resolve(dir, 'pyproject.toml'))) return 'library';
-
-  return 'unknown';
-}
-
-/**
- * Get default projectTypeConfig for a given project type.
- */
-function getProjectTypeDefaults(type) {
-  const defaults = {
-    cli:     { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false, testFramework: 'node:test', runCommand: null },
-    library: { needsEnvVars: false, needsEnvExample: false, needsE2E: false, needsDatabase: false, testFramework: 'vitest',    runCommand: null },
-    webapp:  { needsEnvVars: true,  needsEnvExample: true,  needsE2E: true,  needsDatabase: true,  testFramework: 'vitest',    runCommand: 'npm run dev' },
-    api:     { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true,  testFramework: 'vitest',    runCommand: 'npm run dev' },
-    unknown: { needsEnvVars: true,  needsEnvExample: true,  needsE2E: false, needsDatabase: true,  testFramework: null,        runCommand: null },
-  };
-  return defaults[type] || defaults.unknown;
-}
-
-/**
- * v0.17-P4: normalize validator-key naming so users can write either
- * `validators: { "test-spec": true }` (kebab-case, matches CLI display)
- * or `validators: { testSpec: true }` (camelCase, matches JSON internals)
- * in `.docguard.json`. We normalize the WHOLE config tree's known validator
- * keys to camelCase before merging. Same treatment applied to `severity`.
- *
- * Non-validator keys are left alone. Unknown keys (forward-compat) are
- * normalized blindly: kebab-case→camelCase always.
- */
-const _KNOWN_VALIDATORS = [
-  'structure', 'docsSync', 'drift', 'changelog', 'testSpec', 'environment',
-  'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
-  'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
-  'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
-  'canonicalSync', 'surfaceSync', 'metricsConsistency',
-];
-
-function _kebabToCamel(k) {
-  return k.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
-}
-
-function _normalizeValidatorKeys(map) {
-  if (!map || typeof map !== 'object' || Array.isArray(map)) return map;
-  const out = {};
-  for (const [k, v] of Object.entries(map)) {
-    const normalized = k.includes('-') ? _kebabToCamel(k) : k;
-    out[normalized] = v;
-  }
-  return out;
-}
-
-function normalizeConfig(cfg) {
-  if (!cfg || typeof cfg !== 'object') return cfg;
-  const out = { ...cfg };
-  if (out.validators) out.validators = _normalizeValidatorKeys(out.validators);
-  if (out.severity)   out.severity   = _normalizeValidatorKeys(out.severity);
-  return out;
-}
-
-function deepMerge(target, source) {
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
-      result[key] = deepMerge(target[key] || {}, source[key]);
-    } else {
-      result[key] = source[key];
-    }
-  }
-  return result;
-}
-
 // ── Banner ─────────────────────────────────────────────────────────────────
 function printBanner() {
   console.log(`
@@ -288,7 +73,7 @@ ${c.bold}First-time? Try the demo (no install, no setup):${c.reset}
 
 ${c.bold}The Daily 5${c.reset} ${c.dim}— what you'll reach for 95% of the time${c.reset}
   ${c.green}init${c.reset}       Bootstrap a project — auto-detects existing code and scans (${c.cyan}--skeleton${c.reset} for blank templates, ${c.cyan}--wizard${c.reset} for guided, ${c.cyan}--with <name>${c.reset} for scaffolders)
-  ${c.green}guard${c.reset}      Validate against canonical docs (23 validators)
+  ${c.green}guard${c.reset}      Validate against canonical docs (all validators)
   ${c.green}diff${c.reset}       Show gaps between docs and code (add ${c.cyan}--since <ref>${c.reset} for changed-file impact)
   ${c.green}sync${c.reset}       Refresh code-truth doc sections — keeps memory always up to date
   ${c.green}score${c.reset}      CDD maturity score (0-100; ${c.cyan}--diff${c.reset} for delta between refs)

package/cli/scanners/speckit.mjs

@@ -221,6 +221,20 @@ function validateSpecQuality(specPath) {
   const issues = [];
   const content = readFileSync(specPath, 'utf-8');
 
+  // Bugfix / lightweight specs document a defect (symptom → root cause → fix),
+  // not a feature (User Scenarios / Requirements / Success Criteria with FR/SC
+  // IDs). The full feature template doesn't fit them — forcing it produces
+  // ceremony, not clarity. Opt in with `<!-- docguard:spec-type bugfix -->`
+  // and we validate the bugfix-appropriate shape instead: the spec must still
+  // state a Root Cause and a Fix, so it's a narrower check, not a free pass.
+  if (/<!--\s*docguard:spec-type\s+(?:bugfix|lightweight|patch)\b/i.test(content)) {
+    const { missing } = checkSections(content, ['Root Cause', 'Fix']);
+    for (const section of missing) {
+      issues.push(`Bugfix spec missing "${section}" — a defect spec must state its root cause and fix`);
+    }
+    return issues;
+  }
+
   // Check mandatory sections
   const { missing } = checkSections(content, SPEC_MANDATORY_SECTIONS);
   for (const section of missing) {

package/cli/shared-trace-patterns.mjs

@@ -0,0 +1,105 @@
+/**
+ * Shared trace patterns — the single source of truth for doc→code traceability,
+ * used by BOTH the `docguard trace` command (cli/commands/trace.mjs) and the
+ * guard-time Traceability validator (cli/validators/traceability.mjs).
+ *
+ * Previously each file had its own copy: trace.mjs was multilingual (v0.16-P2)
+ * while the validator stayed JS/TS-only, so the README's "language-aware trace
+ * mapping" claim was false for the `guard` path. Sharing here makes the claim
+ * true and prevents the two from drifting again (field-report Issue 3).
+ *
+ * The API-REFERENCE entry additionally carries the explicit Next.js App Router
+ * pattern (app/api, pages/api) preserved from the v0.22.0 #195 fix.
+ */
+
+export const TEST_PATTERNS = [
+  // JS/TS
+  /\.test\.[jt]sx?$/, /\.spec\.[jt]sx?$/, /\.test\.(mjs|cjs)$/,
+  // Python — pytest conventions
+  /(^|\/)test_[^/]+\.py$/, /[^/]+_test\.py$/, /(^|\/)tests?\/[^/]+\.py$/,
+  // Go
+  /_test\.go$/,
+  // Java/Kotlin — JUnit/TestNG conventions
+  /(?:Test|Tests|Spec|IT)\.(?:java|kt)$/,
+  // Rust — tests live in tests/ or as #[cfg(test)] modules; pattern below covers integration tests
+  /(^|\/)tests\/[^/]+\.rs$/,
+  // Ruby/RSpec
+  /_spec\.rb$/, /_test\.rb$/,
+  // PHP/PHPUnit
+  /Test\.php$/, /(^|\/)tests?\/[^/]+\.php$/,
+];
+
+export const TRACE_MAP = {
+  'ARCHITECTURE.md': {
+    standard: 'arc42 / C4 Model',
+    sourcePatterns: [
+      // Entry points: JS (index/main/app/server.[jt]sx?), Python (__main__.py, main.py, app.py, cli.py),
+      // Go (main.go, cmd/), Rust (main.rs, lib.rs), Java (Application.java, Main.java)
+      { label: 'Entry points', glob: /(?:^|\/)(?:index|main|app|server|cli|__main__|Application|Main)\.(?:[jt]sx?|mjs|cjs|py|go|rs|java|kt|rb)$|(?:^|\/)cmd\// },
+      // Config files: JS (package.json/tsconfig/next.config/vite.config), Python (pyproject.toml/setup.py/setup.cfg),
+      // Rust (Cargo.toml), Go (go.mod), Java/Kotlin (pom.xml/build.gradle), Ruby (Gemfile), PHP (composer.json)
+      { label: 'Config files', glob: /(?:^|\/)(?:package\.json|tsconfig|next\.config|vite\.config|pyproject\.toml|setup\.(?:py|cfg)|Cargo\.toml|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json)/ },
+      // Route handlers + module dirs
+      { label: 'Route handlers / modules', glob: /(?:^|\/)(?:routes?|api|pages|app|controllers?|handlers?|views?|services?)\// },
+    ],
+  },
+  'DATA-MODEL.md': {
+    standard: 'C4 Component / ER (Chen)',
+    sourcePatterns: [
+      // Schema/model files: JS (schema/model/entity/migration/prisma), Python (models.py/schema.py/Pydantic/SQLAlchemy),
+      // Go (models/), Rust (struct definitions in models/), Java (entities/)
+      { label: 'Schema definitions', glob: /(?:schema|model|entity|migration|prisma)/i },
+      // Type definitions: JS types.ts, Python types.py, Rust types.rs
+      { label: 'Type definitions', glob: /(?:^|\/)types?\.(?:[jt]sx?|mjs|py|rs|go|java|kt)$/ },
+      // ORM/database libs (any language)
+      { label: 'Database configs', glob: /(?:drizzle|knex|sequelize|typeorm|sqlalchemy|alembic|django|diesel|sqlx|gorm|hibernate|active.?record)/i },
+    ],
+  },
+  'TEST-SPEC.md': {
+    standard: 'ISO/IEC/IEEE 29119-3',
+    sourcePatterns: [
+      // Test files in any ecosystem (mirrors TEST_PATTERNS above)
+      { label: 'Test files', glob: /\.(?:test|spec)\.(?:mjs|cjs|[jt]sx?)$|(?:^|\/)test_[^/]+\.py$|[^/]+_test\.py$|_test\.go$|(?:Test|Spec|IT)\.(?:java|kt)$|(?:^|\/)tests?\/[^/]+\.(?:rs|py|rb|php)$|_(?:spec|test)\.rb$|Test\.php$/ },
+      // Test runner configs: JS (jest/vitest/playwright/cypress), Python (pytest.ini/tox.ini), Rust (Cargo.toml has [[test]]),
+      // Java (pom.xml/build.gradle), Go (no config file typically)
+      { label: 'Test config', glob: /(?:jest|vitest|playwright|cypress|pytest|tox|phpunit)\.config|(?:^|\/)pytest\.ini$|(?:^|\/)tox\.ini$|(?:^|\/)phpunit\.xml$/ },
+      { label: 'E2E / integration tests', glob: /(?:^|\/)(?:e2e|integration|tests?\/integration)\// },
+    ],
+  },
+  'SECURITY.md': {
+    standard: 'OWASP ASVS v4.0',
+    sourcePatterns: [
+      // Auth modules — semantic, language-agnostic
+      { label: 'Auth modules', glob: /(?:auth|login|session|jwt|oauth|middleware|guard|csrf|cors|permissions?|policy)/i },
+      // Secret configs — .env family + secrets.* / keyring patterns
+      { label: 'Secret configs', glob: /\.env(?:\.|$)|(?:^|\/)secrets?\.(?:py|js|ts|yaml|yml|json)$|keyring/i },
+      // Gitignore + ignore files
+      { label: 'Ignore files', glob: /^\.(?:git|docker|npm)ignore$/ },
+    ],
+  },
+  'ENVIRONMENT.md': {
+    standard: '12-Factor App',
+    sourcePatterns: [
+      // .env family across all ecosystems
+      { label: 'Env files', glob: /\.env(?:\.|$)|(?:^|\/)\.envrc$/ },
+      // Containerization
+      { label: 'Container configs', glob: /(?:^|\/)(?:Dockerfile|docker-compose|\.dockerignore|Containerfile)/ },
+      // Python venv / requirements / lock files
+      { label: 'Python env', glob: /(?:^|\/)(?:requirements[^/]*\.txt|Pipfile|poetry\.lock|uv\.lock|pyproject\.toml)$/ },
+      // CI/CD configs
+      { label: 'CI/CD configs', glob: /(?:^|\/)\.(?:github|gitlab-ci|circleci|drone|gitea)/ },
+    ],
+  },
+  'API-REFERENCE.md': {
+    standard: 'OpenAPI 3.1',
+    sourcePatterns: [
+      // Route handlers + Python views/urls + Java/Spring controllers
+      { label: 'Route handlers', glob: /(?:^|\/)(?:routes?|controllers?|handlers?|views?|urls?\.py)/ },
+      { label: 'Next.js API routes', glob: /(^|\/)(app|pages)\/api\// },
+      // OpenAPI / API specs
+      { label: 'API spec', glob: /(?:openapi|swagger|asyncapi)\.(?:json|ya?ml)/ },
+      // Middleware / decorators
+      { label: 'API middleware', glob: /(?:^|\/)middleware\/|decorators?\.py$/ },
+    ],
+  },
+};

package/cli/validators/doc-quality.mjs

@@ -516,6 +516,21 @@ function getCanonicalDocs(projectDir) {
  * paragraphs are scored. Documents that are mostly tables/code/reference
  * material are skipped for readability (they'd score 0/100 unfairly).
  */
+/**
+ * Parse a per-doc quality-rule override marker, e.g.
+ *   <!-- docguard:quality negation-load off — security doc, prohibitive language is precise -->
+ *   <!-- docguard:quality negation-load 0.35 — operational doc -->
+ * Returns { off: true } | { threshold: <number> } | null. A required reason
+ * after the value is encouraged (and self-documenting) but not enforced here.
+ */
+function parseQualityOverride(content, rule) {
+  const re = new RegExp('<!--\\s*docguard:quality\\s+' + rule + '\\s+(off|\\d*\\.?\\d+)\\b', 'i');
+  const m = content.match(re);
+  if (!m) return null;
+  const v = m[1].toLowerCase();
+  return v === 'off' ? { off: true } : { threshold: parseFloat(v) };
+}
+
 function analyzeDocument(doc) {
   const content = readFileSync(doc.path, 'utf-8');
   const proseText = extractProse(content);
@@ -554,6 +569,7 @@ function analyzeDocument(doc) {
       conditionalLoad: conditional.ratio,
     },
     details: { passive, ambiguous, atomicity, negation, conditional },
+    overrides: { negationLoad: parseQualityOverride(content, 'negation-load') },
   };
 }
 
@@ -650,13 +666,20 @@ export function validateDocQuality(projectDir, config) {
     }
 
     // ── Check 7: Negation Load ──
+    // Per-doc override (security/operational docs legitimately use "never",
+    // "must not", "cannot") and a project-wide config threshold both honored.
     results.total++;
-    if (m.negationLoad <= THRESHOLDS.negationLoad.warn) {
+    const negOv = analysis.overrides?.negationLoad;
+    const negThreshold = negOv?.threshold
+      ?? config.docQuality?.negationLoadThreshold
+      ?? THRESHOLDS.negationLoad.warn;
+    if (negOv?.off || m.negationLoad <= negThreshold) {
       results.passed++;
     } else {
       results.warnings.push(
         `${doc.name}: High negation load (${(m.negationLoad * 100).toFixed(0)}% of sentences use negation). ` +
-        `Rephrase in positive terms: "must not fail" → "must succeed" (IEEE 830 §4.3)`
+        `Rephrase in positive terms: "must not fail" → "must succeed" (IEEE 830 §4.3). ` +
+        `If the negation is intentional, add: <!-- docguard:quality negation-load off — your reason -->`
       );
     }
 

package/cli/validators/docs-diff.mjs

@@ -169,24 +169,34 @@ function diffTests(dir, config) {
   // match it against code test paths (or basenames when the entry has no slash).
   // Exact-string comparison produced the false "N documented but not found".
   const codeArr = [...codeTests];
-  const docArr = [...docTests];
 
-  const matches = (docEntry, codeRel) => {
+  // PERFORMANCE OPTIMIZATION: Pre-compile regular expressions to avoid O(N*M)
+  // instantiation bottlenecks inside the nested .filter and .some loops below.
+  const docMatchers = [...docTests].map(docEntry => {
     const entry = String(docEntry).trim();
     const hasSlash = entry.includes('/');
     const target = hasSlash ? entry : basename(entry);
-    const subject = hasSlash ? codeRel : basename(codeRel);
     // Glob -> regex: escape regex specials, then any run of '*' becomes '.*'.
     const rx = new RegExp('^' + target
       .replace(/[.+^${}()|[\]\\]/g, '\\$&')
       .replace(/\*+/g, '.*') + '$');
-    return rx.test(subject);
+
+    return {
+      original: docEntry,
+      hasSlash,
+      rx
+    };
+  });
+
+  const matches = (matcher, codeRel) => {
+    const subject = matcher.hasSlash ? codeRel : basename(codeRel);
+    return matcher.rx.test(subject);
   };
 
   return {
     title: 'Test Files',
-    onlyInDocs: docArr.filter(d => !codeArr.some(c => matches(d, c))),
-    onlyInCode: codeArr.filter(c => !docArr.some(d => matches(d, c))),
+    onlyInDocs: docMatchers.filter(m => !codeArr.some(c => matches(m, c))).map(m => m.original),
+    onlyInCode: codeArr.filter(c => !docMatchers.some(m => matches(m, c))),
   };
 }
 

package/cli/validators/traceability.mjs

@@ -15,6 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
+import { TRACE_MAP, TEST_PATTERNS } from '../shared-trace-patterns.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
@@ -22,57 +23,6 @@ const IGNORE_DIRS = new Set([
   '.amplify-hosting', '.serverless',
 ]);
 
-/**
- * Mapping of canonical docs to source code patterns they should trace to.
- */
-const TRACE_MAP = {
-  'ARCHITECTURE.md': {
-    sourcePatterns: [
-      { label: 'Entry points', glob: /^(index|main|app|server)\.[jt]sx?$/ },
-      { label: 'Config files', glob: /^(package\.json|tsconfig.*|next\.config|vite\.config)/ },
-      { label: 'Route handlers', glob: /(routes?|api|pages|app)\// },
-    ],
-  },
-  'DATA-MODEL.md': {
-    sourcePatterns: [
-      { label: 'Schema definitions', glob: /(schema|model|entity|migration|prisma)/i },
-      { label: 'Type definitions', glob: /types?\.[jt]sx?$/ },
-      { label: 'Database configs', glob: /(drizzle|knex|sequelize|typeorm)/i },
-    ],
-  },
-  'TEST-SPEC.md': {
-    sourcePatterns: [
-      { label: 'Test files', glob: /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/ },
-      { label: 'Test config', glob: /(jest|vitest|playwright|cypress)\.config/ },
-      { label: 'E2E tests', glob: /(e2e|integration)\// },
-    ],
-  },
-  'SECURITY.md': {
-    sourcePatterns: [
-      { label: 'Auth modules', glob: /(auth|login|session|jwt|oauth|middleware)/i },
-      { label: 'Secret configs', glob: /\.(env|env\.example|env\.local)$/ },
-      { label: 'Gitignore', glob: /^\.gitignore$/ },
-    ],
-  },
-  'ENVIRONMENT.md': {
-    sourcePatterns: [
-      { label: 'Env files', glob: /\.env/ },
-      { label: 'Docker configs', glob: /(Dockerfile|docker-compose|\.dockerignore)/ },
-      { label: 'CI/CD configs', glob: /\.(github|gitlab-ci|circleci)/ },
-    ],
-  },
-  'API-REFERENCE.md': {
-    sourcePatterns: [
-      { label: 'Route handlers', glob: /(routes?|controllers?|handlers?)\// },
-      // Next.js App Router (and Pages Router) — `app/api/`, `src/app/api/`,
-      // `pages/api/`, `src/pages/api/`. Without this, a perfectly-populated
-      // Next.js API tree gets reported as "API-REFERENCE.md — unlinked doc".
-      { label: 'Next.js API routes', glob: /(^|\/)(app|pages)\/api\// },
-      { label: 'OpenAPI spec', glob: /(openapi|swagger)\.(json|ya?ml)/ },
-      { label: 'API middleware', glob: /middleware\// },
-    ],
-  },
-};
 
 // ──── Default requirement ID patterns ────
 // Users can override via config.traceability.requirementPattern
@@ -285,7 +235,7 @@ function collectRequirementIds(projectDir, config, patterns) {
 
 function scanTestFilesForReferences(projectDir, projectFiles, patterns) {
   const testFiles = projectFiles.filter(f =>
-    /\.(test|spec)\.(mjs|cjs|[jt]sx?)$/.test(f) ||
+    TEST_PATTERNS.some(p => p.test(f)) ||   // multilingual: JS/TS, Python, Go, Rust, Java/Kotlin, Ruby, PHP
     /__tests__\//.test(f) ||
     /tests?\//.test(f)
   );

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.22.1"
+  version: "0.23.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/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.22.1
+  version: 0.23.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.23.0 -->
 
 # DocGuard Fix Skill
 

package/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.22.1
+  version: 0.23.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.23.0 -->
 
 # DocGuard Guard Skill
 

package/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.22.1
+  version: 0.23.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.23.0 -->
 
 # DocGuard Review Skill
 

package/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.22.1
+  version: 0.23.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.22.1 -->
+<!-- docguard:version: 0.23.0 -->
 
 # DocGuard Score Skill
 

package/extensions/spec-kit-docguard/skills/docguard-sync/SKILL.md

@@ -4,7 +4,7 @@ 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.22.1
+  version: 0.23.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {