docguard-cli 0.40.4 → 0.41.0

package/cli/validators/traceability.mjs

@@ -18,6 +18,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname } from 'node:path';
 import { TRACE_MAP, isTraceableSource } from '../shared-trace-patterns.mjs';
 import { walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
+/** @implements docguard.adoption-workflow-integrity#FR-006 */
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { tokenize } from '../shared-diff.mjs';
 import { rankBySimilarity } from '../shared-ir.mjs';
@@ -32,7 +33,7 @@ import {
   requirementPatterns,
 } from '../shared-requirements.mjs';
 import { readRetirementManifest } from '../scanners/retirement-manifest.mjs';
-import { parseSpecId } from '../scanners/spec-registry.mjs';
+import { parseSpecId, trustedSpecLifecycleIndex } from '../scanners/spec-registry.mjs';
 
 /**
  * Optional graphify interop (github.com/Graphify-Labs/graphify, MIT).
@@ -250,7 +251,9 @@ export function validateTraceability(projectDir, config) {
   passed += reqResult.passed;
   total += reqResult.total;
 
-  return resultFromFindings(findings, { passed, total });
+  const result = resultFromFindings(findings, { passed, total });
+  result.requirementCoverage = reqResult.requirementCoverage;
+  return result;
 }
 
 // ──── Requirement ID Traceability ────────────────────────────────────────────
@@ -274,6 +277,7 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   // ── Step 1: Collect requirement IDs from documentation ──
   const reqIds = collectRequirementIds(projectDir, config, patterns);
   const retiredReqIds = loadRetiredRequirementIds(projectDir);
+  const lifecycleIndex = trustedSpecLifecycleIndex(projectDir);
 
   // ── Step 2: Scan test files for requirement ID references ──
   const testRefs = scanTestFilesForReferences(projectDir, projectFiles, patterns);
@@ -295,9 +299,18 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
   const softThreshold = config.traceability?.irSoftThreshold ?? 0.10;
   let testCorpus = null;
 
-  // Check each documented requirement has at least one test reference
+  let deferred = 0;
+  let lifecycleUnknown = 0;
+  // Planned specs are intent awaiting implementation. Only committed,
+  // digest-current reviewed lifecycle can defer their test linkage.
   for (const [key, location] of reqIds) {
     const reqId = location.id;
+    const lifecycle = location.specId ? lifecycleIndex.get(`${location.specId}\0${location.file}`) : null;
+    if (lifecycle?.delivery === 'planned') {
+      deferred++;
+      continue;
+    }
+    if (location.specId && !lifecycle) lifecycleUnknown++;
     total++;
     if (resolvedRefs.has(key)) {
       passed++;
@@ -326,6 +339,8 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
       }));
     }
   }
+  const applicableRequirements = total;
+  const tracedRequirements = passed;
 
   // Check for orphaned test refs (tests referencing non-existent requirements)
   for (const [reqId, refs] of testRefs) {
@@ -346,7 +361,17 @@ function validateRequirementTraceability(projectDir, config, projectFiles) {
     }
   }
 
-  return { findings, passed, total };
+  return {
+    findings, passed, total,
+    requirementCoverage: {
+      discovered: reqIds.size,
+      applicable: applicableRequirements,
+      traced: tracedRequirements,
+      missing: findings.filter(finding => finding.code === 'TRC004').length,
+      deferred,
+      lifecycleUnknown,
+    },
+  };
 }
 
 /**

package/cli/writers/junit.mjs

@@ -48,8 +48,8 @@ export function toJUnit(data) {
     const vFindings = Array.isArray(v.findings)
       ? v.findings
       : (data.findings || []).filter(f => f.validator === v.key || f.validator === v.name);
-    const errors = vFindings.filter(f => f.severity === 'error');
-    const warns = vFindings.filter(f => f.severity !== 'error');
+    const errors = vFindings.filter(f => (f.effectiveSeverity || f.severity) === 'error');
+    const warns = vFindings.filter(f => (f.effectiveSeverity || f.severity) !== 'error');
     const attrs = `name="${esc(v.name)}" classname="docguard.guard"`;
 
     if (v.status === 'skipped' || v.status === 'na') {
@@ -63,7 +63,7 @@ export function toJUnit(data) {
         `      <failure message="${esc(errors[0].message)}" type="${esc(errors[0].code || 'docguard')}">${esc(body)}</failure>\n` +
         `    </testcase>`
       );
-    } else if (v.status === 'fail') {
+    } else if (v.status === 'fail' && vFindings.length === 0) {
       // A validator that failed WITHOUT structured error findings — the
       // crash path (guard catches the throw and records string errors only).
       // This must go red in CI, not render as a passing testcase (M1).

package/cli/writers/sarif.mjs

@@ -25,9 +25,9 @@ function pkgInfo() {
   }
 }
 
-/** severity 'error' → SARIF 'error'; everything else (warn) → 'warning'. */
+/** Effective severity → SARIF level. */
 function toLevel(severity) {
-  return severity === 'error' ? 'error' : 'warning';
+  return severity === 'error' ? 'error' : severity === 'info' ? 'note' : 'warning';
 }
 
 /**
@@ -62,10 +62,11 @@ export function toSarif(guardData, opts = {}) {
     if (v.status === 'skipped' || v.status === 'na') continue;
     if (Array.isArray(v.findings) && v.findings.length > 0) continue;
     for (const msg of v.errors || []) {
-      synthetic.push({ code: `DOCGUARD-${String(v.key || v.name || 'unknown').toUpperCase()}`, severity: 'error', message: msg, location: null, suggestion: null });
+      synthetic.push({ code: `DOCGUARD-${String(v.key || v.name || 'unknown').toUpperCase()}`, severity: 'error', effectiveSeverity: 'error', message: msg, location: null, suggestion: null });
     }
     for (const msg of v.warnings || []) {
-      synthetic.push({ code: `DOCGUARD-${String(v.key || v.name || 'unknown').toUpperCase()}`, severity: 'warn', message: msg, location: null, suggestion: null });
+      const effectiveSeverity = v.severity === 'high' ? 'error' : v.severity === 'low' ? 'info' : 'warn';
+      synthetic.push({ code: `DOCGUARD-${String(v.key || v.name || 'unknown').toUpperCase()}`, severity: 'warn', effectiveSeverity, message: msg, location: null, suggestion: null });
     }
   }
   const all = [...findings, ...synthetic];
@@ -83,7 +84,7 @@ export function toSarif(guardData, opts = {}) {
       rule.fullDescription = { text: meta.help };
     }
     rule.helpUri = HELP_URI;
-    rule.defaultConfiguration = { level: toLevel(f.severity) };
+    rule.defaultConfiguration = { level: toLevel(f.effectiveSeverity || f.severity) };
     ruleIndexByCode.set(f.code, rules.length);
     rules.push(rule);
   }
@@ -92,7 +93,7 @@ export function toSarif(guardData, opts = {}) {
     const result = {
       ruleId: f.code,
       ruleIndex: ruleIndexByCode.get(f.code),
-      level: toLevel(f.severity),
+      level: toLevel(f.effectiveSeverity || f.severity),
       message: { text: f.suggestion && f.suggestion.text ? `${f.message}\n→ ${f.suggestion.text}` : f.message },
     };
     const loc = parseLocation(f.location);
@@ -101,9 +102,12 @@ export function toSarif(guardData, opts = {}) {
       if (loc.line) physicalLocation.region = { startLine: loc.line };
       result.locations = [{ physicalLocation }];
     }
-    if (f.confidence === 'low') {
-      result.properties = { confidence: 'low', reportable: !!f.reportable };
-    }
+    result.properties = {
+      originalSeverity: f.severity,
+      effectiveSeverity: f.effectiveSeverity || f.severity,
+      ...(f.enforcement ? { enforcement: f.enforcement } : {}),
+      ...(f.confidence === 'low' ? { confidence: 'low', reportable: !!f.reportable } : {}),
+    };
     return result;
   });
 

package/docs/configuration.md

@@ -7,7 +7,7 @@ DocGuard is configured via `.docguard.json` in the project root. If no config fi
 ```json
 {
   "projectName": "my-project",
-  "version": "0.5",
+  "version": "0.6",
   "profile": "standard",
   "projectType": "webapp",
 
@@ -57,6 +57,10 @@ DocGuard is configured via `.docguard.json` in the project root. If no config fi
 
   "docs": {
     "dirs": ["reference", "website/docs"]
+  },
+  "findingSeverity": {
+    "TRC004": "low",
+    "SEC001": "high"
   }
 }
 ```
@@ -94,6 +98,13 @@ anything from display: `"high"` promotes its warnings to blocking (CI fails),
 `"low"` demotes them (shown, but never fail the build). Valid values:
 `high | medium | low`. To silence a validator entirely, use `validators.<key>: false`.
 
+`findingSeverity.<CODE>` applies the same enforcement levels to one stable
+finding code and takes precedence over the validator setting. This is the
+preferred control for a noisy rule because neighboring findings retain their
+policy. Intrinsic errors remain blocking unless their exact code is configured.
+Machine outputs preserve `severity` and add `effectiveSeverity` plus the
+enforcement source so audit consumers can distinguish detection from policy.
+
 ## Collections — verify documented counts against code
 
 `collections` binds a documentation noun to a glob whose **file count is the

package/extensions/spec-kit-docguard/README.md

@@ -45,12 +45,15 @@ docguard score
 
 | Command | Alias | Purpose |
 |---------|-------|---------|
+| `speckit.docguard.init` | `docguard.init` | Initialize CDD in a project |
 | `speckit.docguard.guard` | `docguard.guard` | Run configurable quality gate with severity triage |
 | `speckit.docguard.fix` | `docguard.fix` | AI-driven documentation repair with codebase research |
 | `speckit.docguard.review` | `docguard.review` | Cross-document semantic consistency analysis (read-only) |
 | `speckit.docguard.score` | `docguard.score` | CDD maturity score with ROI improvement roadmap |
 | `speckit.docguard.diagnose` | — | Diagnose issues + generate multi-perspective AI prompts |
 | `speckit.docguard.generate` | — | Reverse-engineer canonical docs from codebase |
+| `speckit.docguard.sync` | — | Refresh code-truth sections and flag prose for review |
+| `speckit.docguard.trace` | — | Generate requirements traceability matrix |
 | `speckit.docguard.brief` | — | Load current spec intent before specification |
 | `speckit.docguard.preflight` | — | Gate the generated spec before task generation |
 | `speckit.docguard.complete` | — | Plan reviewed completion and regenerate active context after verification |

package/extensions/spec-kit-docguard/commands/review.md

@@ -0,0 +1,50 @@
+---
+description: "Review documentation against code without modifying the repository"
+allowed-tools: Bash, Read
+handoffs:
+  - label: Fix Reviewed Issues
+    agent: docguard.fix
+    prompt: Fix the documentation issues confirmed by the review
+  - label: Run Guard
+    agent: docguard.guard
+    prompt: Validate all checks after approved fixes
+---
+
+# DocGuard Review
+
+Perform a read-only semantic review of canonical documentation against the
+repository. Report evidence and recommendations; do not edit files.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding when it is not empty.
+
+## Execution
+
+1. Run the deterministic inventory and quality checks:
+
+```bash
+npx --yes docguard-cli@latest diagnose $ARGUMENTS
+npx --yes docguard-cli@latest diff $ARGUMENTS
+npx --yes docguard-cli@latest score $ARGUMENTS
+npx --yes docguard-cli@latest verify --evidence --format json $ARGUMENTS
+npx --yes docguard-cli@latest verify --semantic $ARGUMENTS
+```
+
+2. Read the canonical documents and their cited code. Check architecture,
+   schemas, security claims, test coverage, terminology, and cross-references.
+3. For every contradiction, identify whether approved documentation or current
+   code owns the intended behavior. A mismatch can be a code regression.
+4. Return a severity-ranked report with exact file paths, evidence, confidence,
+   and a proposed next action. Keep unsupported claims explicitly unverified.
+
+## Constraints
+
+- Do not modify files or treat a clean structural guard as proof that prose is
+  factually correct.
+- Do not rewrite canonical intent to match code until ownership is resolved.
+- Cap the report at 50 findings and aggregate lower-priority overflow.

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

@@ -3,8 +3,8 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.40.4"
-  description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 5 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
+  version: "0.41.0"
+  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"
   license: "MIT"
@@ -25,16 +25,20 @@ requires:
 
 provides:
   commands:
+    - name: "speckit.docguard.init"
+      file: "commands/init.md"
+      description: "Initialize Canonical-Driven Development in a project"
+
     - name: "speckit.docguard.guard"
       file: "commands/guard.md"
       description: "Run configurable quality gate with severity triage and remediation plan"
 
     - name: "speckit.docguard.fix"
-      file: "commands/generate.md"
+      file: "commands/fix.md"
       description: "AI-driven documentation repair with codebase research and validation loops"
 
     - name: "speckit.docguard.review"
-      file: "commands/diagnose.md"
+      file: "commands/review.md"
       description: "Cross-document semantic consistency analysis (read-only)"
 
     - name: "speckit.docguard.score"
@@ -49,6 +53,14 @@ provides:
       file: "commands/generate.md"
       description: "Reverse-engineer canonical docs from existing codebase"
 
+    - name: "speckit.docguard.sync"
+      file: "commands/sync.md"
+      description: "Refresh generated code-truth sections while preserving human prose"
+
+    - name: "speckit.docguard.trace"
+      file: "commands/trace.md"
+      description: "Generate the requirements traceability matrix"
+
     - name: "speckit.docguard.brief"
       file: "commands/brief.md"
       description: "Brief prior spec intent and lifecycle before creating a new specification"

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.40.4
+  version: 0.41.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.40.4 -->
+<!-- docguard:version: 0.41.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.40.4
+  version: 0.41.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.40.4 -->
+<!-- docguard:version: 0.41.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.40.4
+  version: 0.41.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.40.4 -->
+<!-- docguard:version: 0.41.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.40.4
+  version: 0.41.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.40.4 -->
+<!-- docguard:version: 0.41.0 -->
 
 # DocGuard Score Skill
 

package/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.40.4
+  version: 0.41.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.40.4 -->
+<!-- docguard:version: 0.41.0 -->
 
 # DocGuard Sync Skill
 

package/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.40.4
+        uses: raccioly/docguard@v0.41.0
         with:
           command: fix
           auto-commit: 'true'

package/extensions/spec-kit-docguard/templates/github-workflows/docguard-guard.yml

@@ -35,7 +35,7 @@ jobs:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.40.4
+        run: npm install --global --ignore-scripts docguard-cli@0.41.0
 
       - name: Run DocGuard
         shell: bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.40.4",
+  "version": "0.41.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {
@@ -61,6 +61,7 @@
     "STANDARD.md",
     "PRIVACY.md",
     "PHILOSOPHY.md",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ]

package/schemas/docguard-config.schema.json

@@ -11,7 +11,7 @@
     },
     "version": {
       "type": "string",
-      "description": "Schema version (0.1, 0.2, ... 0.5). Bumped when fields are added or behavior changes. Migrate with `docguard upgrade --apply`.",
+      "description": "Schema version (0.1, 0.2, ... 0.6). Bumped when fields are added or behavior changes. Migrate with `docguard upgrade --apply`.",
       "pattern": "^\\d+\\.\\d+(\\.\\d+)?$"
     },
     "projectName": {
@@ -112,6 +112,9 @@
         "generatedStaleness":{ "type": "boolean" },
         "canonicalSync":     { "type": "boolean" },
         "surfaceSync":       { "type": "boolean" },
+        "diffSuspicion":     { "type": "boolean" },
+        "referenceExistence":{ "type": "boolean" },
+        "apiDocSmells":      { "type": "boolean" },
         "metricsConsistency":{ "type": "boolean" }
       },
       "additionalProperties": false
@@ -124,6 +127,17 @@
         "enum": ["high", "medium", "low"]
       }
     },
+    "findingSeverity": {
+      "type": "object",
+      "description": "Per-finding-code enforcement overrides. Exact codes take precedence over validator severity. high = blocking error, medium = warning, low = informational. Intrinsic errors can only be demoted with an explicit code entry.",
+      "patternProperties": {
+        "^[A-Z]{3}[0-9]{3}$": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        }
+      },
+      "additionalProperties": false
+    },
     "draftStalenessDays": {
       "type": "integer",
       "minimum": 1,

package/schemas/docguard-evidence.schema.json

@@ -48,6 +48,7 @@
           "oneOf": [
             { "$ref": "#/$defs/jsonSource" },
             { "$ref": "#/$defs/collectionSource" },
+            { "$ref": "#/$defs/pythonLiteralSource" },
             { "$ref": "#/$defs/oasdiffSource" },
             { "$ref": "#/$defs/bufSource" }
           ]
@@ -82,6 +83,17 @@
         "allowEmpty": { "type": "boolean" }
       }
     },
+    "pythonLiteralSource": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["adapter", "path", "symbol", "allowEmpty"],
+      "properties": {
+        "adapter": { "const": "python-literal-count" },
+        "path": { "allOf": [{ "$ref": "#/$defs/safePath" }, { "pattern": "\\.py$" }] },
+        "symbol": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,127}$" },
+        "allowEmpty": { "type": "boolean" }
+      }
+    },
     "input": {
       "type": "object",
       "additionalProperties": false,

package/templates/ci/github-actions.yml

@@ -31,7 +31,7 @@ jobs:
           node-version: '20'
 
       - name: Install DocGuard
-        run: npm install --global --ignore-scripts docguard-cli@0.40.4
+        run: npm install --global --ignore-scripts docguard-cli@0.41.0
 
       - name: Run DocGuard
         shell: bash

package/templates/evidence-manifest.json

@@ -16,6 +16,22 @@
         "pointer": "/retentionDays"
       },
       "predicate": { "kind": "equals", "valueType": "number" }
+    },
+    {
+      "id": "surface.python-scanners",
+      "applicability": { "mode": "always" },
+      "target": {
+        "document": "docs-canonical/ARCHITECTURE.md",
+        "heading": "Scanner registry",
+        "statement": "The registry contains {{value}} scanners."
+      },
+      "source": {
+        "adapter": "python-literal-count",
+        "path": "src/package/scanners.py",
+        "symbol": "SCANNERS",
+        "allowEmpty": false
+      },
+      "predicate": { "kind": "count-equals" }
     }
   ]
 }