docguard-cli 0.22.1__tar.gz → 0.23.0__tar.gz

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

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.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
 

{docguard_cli-0.22.1/extensions/spec-kit-docguard → docguard_cli-0.23.0/.agent}/skills/docguard-guard/SKILL.md

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.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
 

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

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.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
 

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/.agent/skills/docguard-score/SKILL.md

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.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
 

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/.agent/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
 ---
 

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/.gitignore

@@ -1,8 +1,9 @@
 # Dependencies
 node_modules/
 
-# Build artifacts (npm pack output — never commit)
+# Build artifacts (npm pack / vsce package output — never commit)
 *.tgz
+*.vsix
 
 # Internal research (not part of the public package)
 Research/

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/.jules/bolt.md

@@ -5,3 +5,6 @@
 ## 2024-05-18 - [O(N*M) String Overhead]
 **Learning:** To prevent N^2 performance bottlenecks in nested loops (such as comparing a list of items against multiple documents), precomputing expensive operations like `.toLowerCase()` during the initial file load or mapping phase avoids redundant $O(N \times M)$ overhead.
 **Action:** Precompute expensive string operations and property lookups (like `.toLowerCase()` and `.substring()`) outside of inner loops and during file load mapping phases to improve scaling.
+## 2024-05-24 - Pre-compile RegExp in nested loops
+**Learning:** Instantiating `new RegExp()` inside nested array methods like `.filter` and `.some` creates a severe O(N*M) performance bottleneck, especially when matching two large lists (e.g., documented tests vs. actual test files).
+**Action:** Always pre-compile regular expressions and derived strings into an array of "matcher" objects outside of the loop before iterating, which shifts the instantiation cost from O(N*M) to O(N).

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/CHANGELOG.md

@@ -7,6 +7,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-05-29
+
+Validator-hardening minor release, driven by external field feedback and a full
+self-audit. Theme: make the validators **fit real projects** and **tell the
+truth**, rather than forcing ceremony or over-claiming. Honest fixes only — no
+doc-gaming. Self-audit guard warnings went 20 → 0-of-ours (the only remaining
+warning is a parallel session's untracked file).
+
+### Added
+- **Language-aware guard Traceability** (field Issue 3) — the guard-time
+  Traceability validator now understands Python, Go, Rust, Java/Kotlin, Ruby,
+  and PHP layouts, not just JS/TS. The multilingual `TEST_PATTERNS` + `TRACE_MAP`
+  live in one shared module (`cli/shared-trace-patterns.mjs`) consumed by both
+  `docguard trace` and the validator, so they can't drift apart. (The README
+  previously claimed this but only the standalone `trace` command delivered it.)
+- **Per-doc negation-load override** (field Issue 14) — `<!-- docguard:quality
+  negation-load off — reason -->` (or a numeric threshold), plus a project-wide
+  `docQuality.negationLoadThreshold` config. Security/operational/audit docs
+  legitimately use "never"/"must not"/"cannot"; this stops false flags without
+  weakening the check for tutorials.
+- **Bugfix/lightweight spec type** — `<!-- docguard:spec-type bugfix -->` makes
+  the Spec-Kit validator check a defect spec for Root Cause + Fix instead of the
+  full feature template (User Scenarios + FR/SC IDs). Narrower check, not a free
+  pass.
+- **`docguard explain canonical-sync`** — the count-level companion validator
+  was missing from the explainer (field Issue 10).
+
+### Changed
+- **`loadConfig` extracted to `cli/config.mjs`** — breaks the demo↔docguard
+  import cycle the Architecture validator flagged (byte-for-byte move, no logic
+  change). New modules import config from there, not the CLI entry point.
+- **Docs-Diff** test-file drift now recognises the documented glob convention
+  (`tests/*.test.mjs`) instead of demanding every test file be enumerated.
+- **Diff loops pre-compile their regexes** (community PR) — O(N·M) → O(N) on the
+  test-file comparison.
+- **Test-Spec** "no mappings" note now points to the expected table format and
+  `docguard explain` (field Issue 4).
+- **Canonical docs refreshed** — ARCHITECTURE (config.mjs, 24 validators, 11
+  scanners, shared-trace-patterns), SECURITY (real `execFileSync`+allowlist
+  subprocess posture), ROADMAP (Phase 4.5 hardening). Genuine review, not
+  date-stamping.
+
+### Related (shipped separately)
+- VS Code extension `DocGuard.docguard-vscode` published to the Marketplace
+  (v0.4.1), including a command-injection fix in `execSpecguard` (#207).
+
 ## [0.22.1] - 2026-05-29
 
 Self-audit + field-feedback patch. Honest fixes only — no doc-gaming. The

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docguard-cli
-Version: 0.22.1
+Version: 0.23.0
 Summary: The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation. Zero dependencies.
 Project-URL: Homepage, https://github.com/raccioly/docguard
 Project-URL: Documentation, https://github.com/raccioly/docguard#readme
@@ -130,9 +130,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

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/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

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/ROADMAP.md

@@ -1,8 +1,8 @@
 # DocGuard Roadmap
 
-<!-- docguard:version 0.4.0 -->
+<!-- docguard:version 0.5.0 -->
 <!-- docguard:status living -->
-<!-- docguard:last-reviewed 2026-05-26 -->
+<!-- docguard:last-reviewed 2026-05-29 -->
 <!-- docguard:owner @raccioly -->
 
 > The planned evolution of DocGuard and Canonical-Driven Development (CDD).
@@ -10,8 +10,8 @@
 | Metadata | Value |
 |----------|-------|
 | **Status** | ![Status](https://img.shields.io/badge/status-active-brightgreen) |
-| **Version** | `0.4.0` |
-| **Last Updated** | 2026-03-12 |
+| **Version** | `0.5.0` |
+| **Last Updated** | 2026-05-29 |
 | **Owner** | [@raccioly](https://github.com/raccioly) |
 
 ---
@@ -31,8 +31,20 @@ Make **Canonical-Driven Development** the industry standard for AI-age software
 | 2 | Polish & Adoption | ✅ Complete | Mar 2026 |
 | 3 | AI Generate Mode | ✅ Complete | Mar 2026 |
 | 4 | Integrations | ✅ Complete | Mar 2026 |
+| 4.5 | Continuous Hardening | 🔄 Ongoing | Mar–May 2026 |
 | 5 | Dashboard (SaaS) | 💭 Future | Q4 2026 |
 
+### Phase 4.5: Continuous Hardening (v0.11 → v0.23) 🔄
+
+Sustained, feedback-driven maturation since the March milestones:
+
+- **Validators grew 9 → 24** — added Canonical-Sync, Surface-Sync, Metrics-Consistency, Doc-Quality, Traceability, Cross-Reference, Generated-Staleness, and more.
+- **Language-aware** test/trace discovery (Python, Go, Rust, Java/Kotlin, Ruby, PHP) shared between `docguard trace` and the guard-time Traceability validator.
+- **Per-doc/per-rule overrides** — `docguard:section … n/a`, `docguard:quality negation-load off`, `docguard:spec-type bugfix` — so the validators fit real projects instead of forcing ceremony.
+- **Security** — closed command-injection vectors in CLI `init` (#190) and the VS Code extension (#207); subprocesses now use `execFileSync` + allowlist validation.
+- **Published the VS Code extension** (`DocGuard.docguard-vscode`) to the Marketplace.
+- **Distribution** — npm + PyPI + GitHub Action + Spec Kit community-catalog auto-sync.
+
 ---
 
 ## Phase 0: Research & Standard ✅

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/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);

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/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),
   };
 }
 

{docguard_cli-0.22.1 → docguard_cli-0.23.0}/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

docguard_cli-0.23.0/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;
+}