docguard-cli 0.40.5 → 0.41.0

package/README.md

@@ -24,7 +24,7 @@
 > ```
 > Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.
 
-![DocGuard demo](assets/demo.gif)
+![DocGuard demo](https://raw.githubusercontent.com/raccioly/docguard/main/assets/demo.gif)
 
 ---
 
@@ -63,7 +63,7 @@ DocGuard enforces **Canonical-Driven Development (CDD)** — a methodology where
 
 DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) community extension. It validates the artifacts that Spec Kit creates, ensuring your specs stay high-quality throughout the development lifecycle.
 
-📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](COMPARISONS.md)** · 🔬 **[Validation](VALIDATION.md)** · 🗺️ **[Roadmap](ROADMAP.md)**
+📖 **[Philosophy](PHILOSOPHY.md)** · 📋 **[CDD Standard](STANDARD.md)** · ⚖️ **[Comparisons](https://github.com/raccioly/docguard/blob/main/COMPARISONS.md)** · 🔬 **[Validation](https://github.com/raccioly/docguard/blob/main/VALIDATION.md)** · 🗺️ **[Roadmap](https://github.com/raccioly/docguard/blob/main/ROADMAP.md)**
 
 ### Architecture
 
@@ -108,7 +108,7 @@ A guard result describes the checks performed. The CDD grade measures structural
 
 Research motivates evaluation of this approach. A 2026 study found that repository context files did not generally improve task success and increased inference cost in its evaluated settings. It also found agents generally followed the instructions. These results support testing concise, relevant context and measuring actual task outcomes; they do not establish DocGuard's effectiveness. [Evaluating AGENTS.md, revised June 2026](https://arxiv.org/abs/2602.11988v2).
 
-The [current roadmap](ROADMAP.md) prioritizes accurate detection, reproducible evidence, document lifecycle management, and contributor-supplied regression cases. Released plans and superseded specifications are removed from active AI context and remain recoverable from Git.
+The [current roadmap](https://github.com/raccioly/docguard/blob/main/ROADMAP.md) prioritizes accurate detection, reproducible evidence, document lifecycle management, and contributor-supplied regression cases. Released plans and superseded specifications are removed from active AI context and remain recoverable from Git.
 
 ---
 
@@ -166,7 +166,7 @@ The server is **read-only** — it never writes to the mounted project.
   ```
 - **MCP** (Claude, Cursor, any MCP client) — `claude mcp add docguard -- npx -y docguard-cli mcp`; 5 read-only tools (guard, score, explain, verify-claims, diagnose). Registry manifest ships in-repo (`server.json`, Smithery-ready).
 - **GitLab CI** — component staged at [`templates/ci/gitlab-component.yml`](templates/ci/gitlab-component.yml) (guard/score/ci job with a SARIF artifact).
-- **Homebrew** — `brew install raccioly/tap/docguard` (formula in [`packaging/homebrew/`](packaging/homebrew/)).
+- **Homebrew** — `brew install raccioly/tap/docguard` (formula in [`packaging/homebrew/`](https://github.com/raccioly/docguard/tree/main/packaging/homebrew)).
 
 ### Core Workflow
 
@@ -278,7 +278,7 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | `guard` | Validate against canonical docs — 30 validators |
 | `diff`  | Show gaps between docs and code (`--since <ref>` for impact mode) |
 | `sync`  | Refresh code-truth doc sections — keeps memory always up to date |
-| `score` | CDD maturity score (0-100; `--diff` for delta between refs) |
+| `score` | Structural CDD maturity score (0-100; not a guard verdict; `--diff` for delta between refs) |
 
 **Tools (situational, but day-to-day useful):**
 
@@ -302,8 +302,8 @@ DocGuard ships **23 commands** (the "Daily 5" + 18 situational tools, including
 | `specs --check` / `specs --write` | Validate or refresh `.docguard-specs.json`, the byte-stable index of immutable spec IDs, reviewed lifecycle/lineage/scope, artifact digests, task state, explicitly scoped test evidence, and archive tombstones. Refreshes preserve the reviewed block. |
 | `specs preflight [--path <spec>]` | Before specification, print current spec lifecycle and evidence. Before planning, check the generated draft for structural blockers and report semantic overlap as review-only evidence. |
 | `mcp` | MCP server — exposes guard/score/explain/verify/report/diagnose as native tools for Claude, Cursor, and any MCP client. Stdio: `claude mcp add docguard -- npx docguard-cli mcp`. Team-shared HTTP: `docguard mcp --transport http --port 8585` (loopback by default; non-loopback binds require `--api-key`) |
-| `report` | Compliance-evidence bundle for audits — guard verdict + CDD score + ALCOA+ attributes + fix history, stamped with git commit and a tamper-evident sha256 integrity hash (`--format json`, `--out <file>`). Evidence, not a gate: always exits 0 |
-| `ci` | Pipeline gate: guard + score in one command — never scaffolds or touches source; its only write is its own `.docguard/history.jsonl` (opt out: `--no-history`). `--threshold <n>` fails below a score, `--fail-on-warning` for strict mode, `--format json` for parsers |
+| `report` | Compliance-evidence bundle for audits — combined readiness, guard verdict, structural maturity, ALCOA+ attributes, and fix history, stamped with git commit and a tamper-evident sha256 integrity hash (`--format json`, `--out <file>`). Evidence, not a gate: always exits 0 |
+| `ci` | Pipeline gate: guard + structural maturity in one command with READY/ATTENTION/BLOCKED assessment — never scaffolds or touches source; its only write is its own `.docguard/history.jsonl` (opt out: `--no-history`). `--threshold <n>` fails below a score, `--fail-on-warning` for strict mode, `--format json` for parsers |
 | `score --trend` | Score trajectory from recorded `ci` runs — sparkline, delta, and the last 10 runs with commit stamps |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |
@@ -456,10 +456,19 @@ DocGuard runs **30 automated validators** on every `guard` check. Source-facing
   "severity": {
     "todoTracking": "high",             // warnings fail CI
     "freshness": "low"                  // warnings ignored for exit code
+  },
+  "findingSeverity": {
+    "TRC004": "low",                    // only this finding becomes informational
+    "SEC001": "high"                    // this exact code always blocks
   }
 }
 ```
 
+Exact `findingSeverity` entries take precedence over validator severity. Guard
+JSON, SARIF, and JUnit retain the detector's intrinsic severity and add the
+effective severity plus the policy source. Intrinsic errors stay blocking unless
+their exact stable code is explicitly configured.
+
 ---
 
 ## 📄 Templates
@@ -591,11 +600,11 @@ Three real-world projects to see DocGuard in action:
 
 | Example | Scenario | What You'll See |
 |---------|----------|----------------|
-| [01-express-api](examples/01-express-api/) | Node.js API with **zero docs** | Cold-start: `generate` → instant coverage |
-| [02-python-flask](examples/02-python-flask/) | Python app with **drifted docs** | Drift detection: catch when docs lie |
-| [03-spec-kit-project](examples/03-spec-kit-project/) | Full CDD + Spec Kit | Gold standard: what maturity looks like |
+| [01-express-api](https://github.com/raccioly/docguard/tree/main/examples/01-express-api) | Node.js API with **zero docs** | Cold-start: `generate` → instant coverage |
+| [02-python-flask](https://github.com/raccioly/docguard/tree/main/examples/02-python-flask) | Python app with **drifted docs** | Drift detection: catch when docs lie |
+| [03-spec-kit-project](https://github.com/raccioly/docguard/tree/main/examples/03-spec-kit-project) | Full CDD + Spec Kit | Gold standard: what maturity looks like |
 
-See [examples/README.md](examples/README.md) for step-by-step instructions.
+See [examples/README.md](https://github.com/raccioly/docguard/blob/main/examples/README.md) for step-by-step instructions.
 
 ---
 
@@ -639,7 +648,7 @@ The pieces that matter at company scale:
 
 ## ⚙️ CI/CD Integration
 
-> **Full recipes:** see [`docs-canonical/CI-RECIPES.md`](./docs-canonical/CI-RECIPES.md) for guard, auto-fix (commits mechanical fixes back to PRs), nightly sync, score-on-PR, and pre-commit configs.
+> **Full recipes:** see [`docs-canonical/CI-RECIPES.md`](https://github.com/raccioly/docguard/blob/main/docs-canonical/CI-RECIPES.md) for guard, auto-fix (commits mechanical fixes back to PRs), nightly sync, score-on-PR, and pre-commit configs.
 
 ### GitHub Actions — Guard (most common)
 
@@ -705,7 +714,7 @@ Two ready-to-use templates ship with the Spec Kit extension and as standalone fi
 
 ## ✨ What's New
 
-Highlights of the current line (v0.29 → v0.33):
+Highlights through the current v0.40 release line:
 
 - **Adoption baseline** — `guard --update-baseline` freezes a legacy repo's existing findings
   into a committed `.docguard.baseline.json`; guard/ci then gate only NEW drift, with suppression
@@ -805,12 +814,12 @@ See [Configuration Guide](docs/configuration.md) for all options.
 
 DocGuard's quality evaluation and documentation generation patterns are informed by peer-reviewed research from the University of Arizona and the Joint Interoperability Test Command (JITC), U.S. Department of Defense:
 
-- **AITPG** — AI-driven Test Plan Generator using Multi-Agent Debate and RAG ([Lopez et al., IEEE TSE 2026](Research/AITPG.pdf))
-- **TRACE** — Telecom Root Cause Analysis through Calibrated Explainability ([Lopez et al., IEEE TMLCN 2026](Research/TRACE.pdf))
+- **AITPG** — AI-driven Test Plan Generator using Multi-Agent Debate and RAG ([Lopez et al., IEEE TSE 2026](https://github.com/raccioly/docguard/blob/main/Research/AITPG.pdf))
+- **TRACE** — Telecom Root Cause Analysis through Calibrated Explainability ([Lopez et al., IEEE TMLCN 2026](https://github.com/raccioly/docguard/blob/main/Research/TRACE.pdf))
 
 Lead researcher: **[Martin Manuel Lopez](https://github.com/martinmanuel9)** · [ORCID 0009-0002-7652-2385](https://orcid.org/0009-0002-7652-2385)
 
-See [CONTRIBUTING.md](CONTRIBUTING.md#research--academic-credits) for full citations.
+See [CONTRIBUTING.md](https://github.com/raccioly/docguard/blob/main/CONTRIBUTING.md#research--academic-credits) for full citations.
 
 ---
 

package/cli/assessment.mjs

@@ -0,0 +1,94 @@
+/**
+ * Combine the guard verdict and optional CI policy into one readiness result.
+ * @implements docguard.adoption-workflow-integrity#FR-009
+ *
+ * Structural maturity remains an independent 0-100 measure. It can explain
+ * the quality of the documentation system, but it cannot override a failed
+ * guard check or a configured CI gate.
+ */
+export function buildReadinessAssessment(guardData, scoreData, options = {}) {
+  const blockingFindings = finiteCount(guardData?.effectiveErrors, guardData?.errors);
+  const advisoryFindings = finiteCount(guardData?.effectiveWarnings, guardData?.warnings);
+  const guardStatus = normalizeGuardStatus(guardData?.status, blockingFindings, advisoryFindings);
+
+  const threshold = Number.isFinite(options.threshold) ? options.threshold : null;
+  const thresholdConfigured = options.thresholdConfigured ?? (threshold !== null && threshold > 0);
+  const thresholdMet = thresholdConfigured
+    ? Boolean(options.thresholdMet ?? (threshold !== null && scoreData.score >= threshold))
+    : true;
+  const warningsBlockCI = Boolean(options.failOnWarning) && guardStatus === 'WARN';
+
+  const reasons = [];
+  if (guardStatus === 'FAIL') reasons.push('GUARD_FAILED');
+  if (guardStatus === 'UNKNOWN') reasons.push('GUARD_STATUS_UNKNOWN');
+  if (!thresholdMet) reasons.push('CI_THRESHOLD_NOT_MET');
+  if (warningsBlockCI) reasons.push('CI_WARNINGS_BLOCKED');
+  else if (guardStatus === 'WARN') reasons.push('GUARD_WARNINGS');
+
+  let status;
+  if (guardStatus === 'FAIL' || guardStatus === 'UNKNOWN' || !thresholdMet || warningsBlockCI) status = 'BLOCKED';
+  else if (guardStatus === 'WARN') status = 'ATTENTION';
+  else status = 'READY';
+
+  const assessment = {
+    status,
+    reasons,
+    guardStatus,
+    blockingFindings,
+    advisoryFindings,
+    structuralMaturity: {
+      score: scoreData.score,
+      grade: scoreData.grade,
+      scoreKind: scoreData.scoreKind || 'structural-maturity',
+    },
+    threshold: {
+      configured: thresholdConfigured,
+      value: thresholdConfigured ? threshold : null,
+      met: thresholdMet,
+    },
+  };
+
+  return { ...assessment, summary: summarizeAssessment(assessment) };
+}
+
+function finiteCount(primary, fallback) {
+  if (Number.isFinite(primary)) return primary;
+  return Number.isFinite(fallback) ? fallback : 0;
+}
+
+function normalizeGuardStatus(value, blockingFindings, advisoryFindings) {
+  const status = typeof value === 'string' ? value.toUpperCase() : '';
+  if (status === 'FAIL' || blockingFindings > 0) return 'FAIL';
+  if (status === 'WARN' || advisoryFindings > 0) return 'WARN';
+  if (status === 'PASS') return 'PASS';
+  return 'UNKNOWN';
+}
+
+function summarizeAssessment(assessment) {
+  const clauses = [];
+
+  if (assessment.guardStatus === 'FAIL') {
+    clauses.push(`guard failed with ${formatCount(assessment.blockingFindings, 'blocking finding')}`);
+  } else if (assessment.guardStatus === 'UNKNOWN') {
+    clauses.push('guard status is unavailable');
+  } else if (assessment.reasons.includes('CI_WARNINGS_BLOCKED')) {
+    clauses.push(`${formatCount(assessment.advisoryFindings, 'guard warning')} configured to block CI`);
+  } else if (assessment.guardStatus === 'WARN') {
+    clauses.push(`guard reported ${formatCount(assessment.advisoryFindings, 'advisory warning')}`);
+  } else {
+    clauses.push('guard passed');
+  }
+
+  if (assessment.reasons.includes('CI_THRESHOLD_NOT_MET')) {
+    const threshold = assessment.threshold.value === null ? 'the configured value' : assessment.threshold.value;
+    clauses.push(`Structural Maturity ${assessment.structuralMaturity.score}/100 is below CI threshold ${threshold}`);
+  } else {
+    clauses.push(`Structural Maturity is ${assessment.structuralMaturity.score}/100 (${assessment.structuralMaturity.grade})`);
+  }
+
+  return clauses.join('; ') + '.';
+}
+
+function formatCount(count, noun) {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}

package/cli/commands/ci.mjs

@@ -18,6 +18,7 @@ import { runGuardInternal } from './guard.mjs';
 import { runScoreInternal } from './score.mjs';
 import { appendHistory } from '../writers/history.mjs';
 import { getHeadInfo, isGitRepo } from '../shared-git.mjs';
+import { buildReadinessAssessment } from '../assessment.mjs';
 
 export function runCI(projectDir, config, flags) {
   const threshold = parseInt(flags.threshold || '0', 10);
@@ -46,10 +47,14 @@ export function runCI(projectDir, config, flags) {
   // --fail-on-warning failure exits 1 and must not be recorded as PASS in
   // history or the JSON consumers parse.
   const thresholdMet = threshold <= 0 || scoreData.score >= threshold;
-  const status =
-    hasErrors || !thresholdMet || (failOnWarning && hasWarnings) ? 'FAIL'
-    : hasWarnings ? 'WARN'
-    : 'PASS';
+  const assessment = buildReadinessAssessment(guardData, scoreData, {
+    threshold,
+    thresholdMet,
+    failOnWarning,
+  });
+  const status = assessment.status === 'BLOCKED'
+    ? 'FAIL'
+    : assessment.status === 'ATTENTION' ? 'WARN' : 'PASS';
 
   // ── Record history (unless opted out) ──
   if (!flags.noHistory) {
@@ -89,6 +94,7 @@ export function runCI(projectDir, config, flags) {
       threshold,
       thresholdMet,
       status,
+      assessment,
       timestamp: new Date().toISOString(),
     };
     // Machine output must survive a pipe: stdout.write + natural exit, never
@@ -107,12 +113,16 @@ export function runCI(projectDir, config, flags) {
     if (guardData.baselineSuppressed > 0) {
       console.log(`  ${c.dim}📋 ${guardData.baselineSuppressed} pre-existing finding(s) suppressed by the committed baseline${c.reset}`);
     }
-    console.log(`  ${c.bold}Score:${c.reset}  ${scoreData.score}/100 (${scoreData.grade})`);
+    console.log(`  ${c.bold}Structural Maturity:${c.reset}  ${scoreData.score}/100 (${scoreData.grade})`);
 
     if (threshold > 0) {
       console.log(`  ${c.bold}Threshold:${c.reset}  ${thresholdMet ? `${c.green}✅ ≥${threshold}` : `${c.red}❌ <${threshold}`}${c.reset}`);
     }
 
+    const readinessColor = assessment.status === 'READY' ? c.green : assessment.status === 'ATTENTION' ? c.yellow : c.red;
+    console.log(`  ${c.bold}Readiness:${c.reset}  ${readinessColor}${c.bold}${assessment.status}${c.reset}`);
+    console.log(`  ${c.dim}${assessment.summary}${c.reset}`);
+
     console.log('');
   }
 

package/cli/commands/diagnose.mjs

@@ -23,6 +23,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync, execFileSync } from 'node:child_process';
 import { applyAllMechanicalFixes } from './fix.mjs';
+import { buildReadinessAssessment } from '../assessment.mjs';
 
 // Map validator failures to the right fix --doc target
 const VALIDATOR_TO_DOC = {
@@ -186,7 +187,7 @@ export function runDiagnose(projectDir, config, flags) {
 
   // ── Step 1: Run guard internally ──
   let guardData = runGuardInternal(projectDir, config);
-  const scoreData = runScoreInternal(projectDir, config);
+  let scoreData = runScoreInternal(projectDir, config);
 
   // ── Step 2: Collect issues ──
   let issues = collectIssues(guardData);
@@ -223,6 +224,7 @@ export function runDiagnose(projectDir, config, flags) {
 
       // Re-run guard to see what's still broken
       guardData = runGuardInternal(projectDir, config);
+      scoreData = runScoreInternal(projectDir, config);
       issues = collectIssues(guardData);
 
       if (!flags.format || flags.format === 'text') {
@@ -256,12 +258,13 @@ export function runDiagnose(projectDir, config, flags) {
   }
 
   // ── Step 4: Output ──
+  const assessment = buildReadinessAssessment(guardData, scoreData);
   if (flags.format === 'json') {
-    outputJSON(guardData, scoreData, issues);
+    outputJSON(guardData, scoreData, issues, assessment);
   } else if (flags.format === 'prompt') {
-    outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode);
+    outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode, assessment);
   } else {
-    outputText(projectDir, guardData, scoreData, issues, flags, agentMode);
+    outputText(projectDir, guardData, scoreData, issues, flags, agentMode, assessment);
   }
 }
 
@@ -315,7 +318,7 @@ function collectIssues(guardData) {
   return issues;
 }
 
-function outputJSON(guardData, scoreData, issues) {
+function outputJSON(guardData, scoreData, issues, assessment) {
   // Structured, deterministic fix actions an agent or `--write` can apply directly.
   const mechanicalFixes = [];
   for (const v of guardData.validators) {
@@ -332,6 +335,7 @@ function outputJSON(guardData, scoreData, issues) {
     grade: scoreData.grade,
     scoreKind: scoreData.scoreKind,
     assurance: scoreData.assurance,
+    assessment,
     checkCoverage: guardData.checkCoverage,
     issueCount: issues.length,
     issues: issues.map(i => ({
@@ -354,10 +358,12 @@ function outputJSON(guardData, scoreData, issues) {
   console.log(JSON.stringify(result, null, 2));
 }
 
-function outputText(projectDir, guardData, scoreData, issues, flags, agentMode = 'llm') {
+function outputText(projectDir, guardData, scoreData, issues, flags, agentMode = 'llm', assessment) {
   console.log(`${c.bold}🔍 DocGuard Diagnose — ${guardData.project}${c.reset}`);
-  console.log(`${c.dim}   Profile: ${guardData.profile} | Score: ${scoreData.score}/100 (${scoreData.grade}) | Mode: ${agentMode.toUpperCase()}${c.reset}`);
+  console.log(`${c.dim}   Profile: ${guardData.profile} | Structural Maturity: ${scoreData.score}/100 (${scoreData.grade}) | Mode: ${agentMode.toUpperCase()}${c.reset}`);
   console.log(`${c.dim}   Guard:   ${guardData.passed}/${guardData.total} passed | Status: ${guardData.status}${c.reset}\n`);
+  const readinessColor = assessment.status === 'READY' ? c.green : assessment.status === 'ATTENTION' ? c.yellow : c.red;
+  console.log(`  ${c.bold}Readiness:${c.reset} ${readinessColor}${c.bold}${assessment.status}${c.reset} ${c.dim}— ${assessment.summary}${c.reset}\n`);
 
   if (issues.length === 0) {
     console.log(`  ${c.green}${c.bold}✅ All clear!${c.reset} No issues found.\n`);
@@ -410,15 +416,15 @@ function outputText(projectDir, guardData, scoreData, issues, flags, agentMode =
     // Multi-perspective debate prompts (AITPG/TRACE-inspired)
     console.log(`  ${c.bold}🤖 Multi-Perspective AI Debate Prompt:${c.reset}`);
     console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
-    outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode);
+    outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode, assessment);
   } else {
     console.log(`  ${c.bold}🤖 AI-Ready Prompt:${c.reset}`);
     console.log(`  ${c.dim}Copy everything below and paste to your AI agent:${c.reset}\n`);
-    outputPrompt(undefined, guardData, scoreData, issues, flags, agentMode);
+    outputPrompt(undefined, guardData, scoreData, issues, flags, agentMode, assessment);
   }
 }
 
-function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode = 'llm') {
+function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode = 'llm', assessment) {
   if (issues.length === 0) {
     console.log('No issues to fix. Documentation is healthy.');
     return;
@@ -429,7 +435,8 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode
 
   const lines = [];
   lines.push(`TASK: Fix ${issues.length} documentation issue(s) in project "${guardData.project}"`);
-  lines.push(`Profile: ${guardData.profile} | Score: ${scoreData.score}/100 | Guard: ${guardData.status}`);
+  lines.push(`Readiness: ${assessment.status} | Guard: ${guardData.status} | Structural Maturity: ${scoreData.score}/100 (${scoreData.grade})`);
+  lines.push(assessment.summary);
   lines.push('');
   lines.push('ISSUES FOUND:');
 
@@ -507,12 +514,12 @@ function outputPrompt(projectDir, guardData, scoreData, issues, flags, agentMode
  * and TRACE adversarial debate (Advocate/Challenger/Mediator/Explainer).
  * Lopez et al., IEEE TSE/TMLCN 2026.
  */
-function outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode = 'llm') {
+function outputDebatePrompt(projectDir, guardData, scoreData, issues, agentMode = 'llm', assessment) {
   const lines = [];
 
   lines.push('═══════════════════════════════════════════════════════');
   lines.push('MULTI-PERSPECTIVE DOCUMENTATION ANALYSIS');
-  lines.push(`Project: "${guardData.project}" | Score: ${scoreData.score}/100 | Issues: ${issues.length}`);
+  lines.push(`Project: "${guardData.project}" | Readiness: ${assessment.status} | Guard: ${guardData.status} | Structural Maturity: ${scoreData.score}/100 (${scoreData.grade}) | Issues: ${issues.length}`);
   lines.push('Methodology: Multi-agent debate (Lopez et al., AITPG/TRACE, IEEE 2026)');
   lines.push('═══════════════════════════════════════════════════════');
   lines.push('');

package/cli/commands/fix.mjs

@@ -2,7 +2,6 @@
  * @implements docguard.language-repository-coverage#FR-010
  * @implements docguard.language-repository-coverage#FR-011
  */
-import { assertMappedFullDocumentWrites, docRolePath, isMappedDocPath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Fix Command — The AI Orchestrator
  * 
@@ -24,61 +23,31 @@ import { execSync, execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { c } from '../shared.mjs';
 import { computeApiSurfaceDrift } from '../validators/api-surface.mjs';
-import { removeEndpoints, hasGeneratedMarker } from '../writers/api-reference.mjs';
 import { applyMechanicalFixes } from '../writers/mechanical.mjs';
 import { loadFixMemory } from '../writers/fix-memory.mjs';
 import { safeWrite } from '../writers/generate-io.mjs';
 import { runGuardInternal } from './guard.mjs';
 
 /**
- * Apply DETERMINISTIC, no-LLM API-surface fixes: remove endpoints documented in
- * API-REFERENCE.md that the OpenAPI spec confirms no longer exist. Removes the
- * summary-table row and the detail block. Never rewrites prose.
+ * Compatibility entry point for the former API deletion writer.
  *
- * Safety: only edits a doc carrying the `<!-- docguard:generated true -->`
- * marker, unless `force` is set. Idempotent.
+ * OpenAPI can prove a contract omission, while bounded route discovery cannot
+ * prove runtime absence and canonical documentation may represent intended
+ * behavior. Contract mismatches therefore require review and this entry point
+ * is deliberately read-only, including under `--force`.
  *
  * @returns {{ applied: boolean, removed: Array<{method,path}>, skipped?: string }}
  */
-export function applyApiSurfaceWrites(projectDir, config, { force = false } = {}) {
+export function applyApiSurfaceWrites(projectDir, config) {
   const drift = computeApiSurfaceDrift(projectDir, config);
-  // Only spec-confirmed absences are safe to delete deterministically.
-  const removable = drift.confidence === 'spec' ? drift.documentedButAbsent : [];
-  if (removable.length === 0) return { applied: false, removed: [] };
-
-  const apiDoc = docRolePath(config, 'apiReference');
-  const apiDocPath = resolveDocRole(projectDir, config, 'apiReference');
-  if (!existsSync(apiDocPath)) return { applied: false, removed: [] };
-
-  const content = readFileSync(apiDocPath, 'utf-8');
-  if (!hasGeneratedMarker(content) && !force) {
-    return {
-      applied: false,
-      removed: [],
-      skipped: `${apiDoc} is not marked '<!-- docguard:generated true -->'. ` +
-        `Re-run with --force to edit it, or fix it via an AI agent (/docguard.fix --doc api-reference).`,
-    };
-  }
-  if (isMappedDocPath(config, apiDoc)) assertMappedFullDocumentWrites(projectDir, config, ['apiReference']);
-
-  const { content: newContent, removed } = removeEndpoints(content, removable);
-  if (removed.length === 0 || newContent === content) {
-    return { applied: false, removed: [] }; // idempotent no-op
-  }
-
-  safeWrite(apiDocPath, newContent);
-  // Map removed keys back to {method,path} for reporting.
-  const removedEndpoints = removable.filter(e => removed.includes(`${e.method.toUpperCase()} ${normalizeForKey(e.path)}`));
-  return { applied: true, removed: removedEndpoints.length ? removedEndpoints : removable };
-}
-
-// Local mirror of api-doc normalizePath for matching removed keys (avoids an
-// extra import cycle); only used for display reconciliation.
-function normalizeForKey(p) {
-  let s = String(p).trim().replace(/^[|`'"\s]+/, '').replace(/[|`'"\s]+$/, '').split(/[?#]/)[0];
-  s = s.replace(/\{[^}/]+\}/g, '{}').replace(/:[^/]+/g, '{}');
-  if (s.length > 1) s = s.replace(/\/+$/, '');
-  return s;
+  const reviewCount = drift.confidence === 'spec' ? drift.contractMismatches.length : 0;
+  return {
+    applied: false,
+    removed: [],
+    ...(reviewCount > 0 ? {
+      skipped: `${reviewCount} endpoint contract mismatch(es) require review; negative route-scan evidence cannot authorize documentation deletion.`,
+    } : {}),
+  };
 }
 
 // ── Document Quality Definitions ───────────────────────────────────────────

package/cli/commands/guard.mjs

@@ -10,9 +10,9 @@ import { applyDocRoles } from '../shared-doc-roles.mjs';
  *   runGuardInternal() → returns data, no side effects (for diagnose, ci)
  */
 
-import { c, resolveSeverity, loadIgnorePatterns, resolveDocDirs } from '../shared.mjs';
+import { c, resolveSeverity, resolveFindingEnforcement, loadIgnorePatterns, resolveDocDirs } from '../shared.mjs';
 import { walkFiles, buildIgnoreFilter } from '../shared-ignore.mjs';
-import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { CODES, mkFinding, resultFromFindings } from '../findings.mjs';
 import { loadValidatorSuppressions } from '../validator-markers.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
 import { checkUpgradeStatus } from './upgrade.mjs';
@@ -206,6 +206,7 @@ function renderableItems(v) {
   if (Array.isArray(v.findings) && v.findings.length > 0) {
     return v.findings.map((f) => ({
       severity: f.severity,
+      effectiveSeverity: f.effectiveSeverity || f.severity,
       message: f.message,
       code: f.code,
       confidence: f.confidence,
@@ -453,24 +454,35 @@ export function runGuardInternal(projectDir, config) {
   const totalPassed = activeResults.reduce((sum, r) => sum + r.passed, 0);
   const totalChecks = activeResults.reduce((sum, r) => sum + r.total, 0);
 
-  // Per-validator severity overrides (v0.5 schema). Affects EXIT-CODE only,
-  // not display. Annotate each validator with its resolved severity and roll
-  // up effective error/warning counts:
-  //   - high  → validator's warnings get promoted to "effective errors"
-  //   - low   → validator's warnings are demoted (ignored for exit code)
-  //   - medium (default) → warnings stay as-is
+  // Compute enforcement after baseline suppression. Structured findings can
+  // be reweighted by exact stable code; legacy validators retain the existing
+  // per-validator behavior. Preserve intrinsic severity for auditability.
   for (const v of activeResults) {
     v.severity = resolveSeverity(config, v.key);
+    let errors = 0, warnings = 0, infos = 0;
+    if (Array.isArray(v.findings) && v.findings.length > 0) {
+      for (const finding of v.findings) {
+        const enforcement = resolveFindingEnforcement(config, finding, v.key);
+        finding.effectiveSeverity = enforcement.level;
+        finding.enforcement = enforcement;
+        if (enforcement.level === 'error') errors++;
+        else if (enforcement.level === 'warn') warnings++;
+        else infos++;
+      }
+    } else {
+      errors = v.errors.length;
+      if (v.severity === 'high') errors += v.warnings.length;
+      else if (v.severity === 'medium') warnings = v.warnings.length;
+      else infos = v.warnings.length;
+    }
+    v.effectiveErrors = errors;
+    v.effectiveWarnings = warnings;
+    v.effectiveInfos = infos;
+    v.effectiveStatus = errors > 0 ? 'fail' : warnings > 0 ? 'warn' : v.status === 'na' ? 'na' : 'pass';
   }
-  let effectiveErrors = totalErrors;
-  let effectiveWarnings = 0;
-  for (const v of activeResults) {
-    const wCount = v.warnings.length;
-    if (wCount === 0) continue;
-    if (v.severity === 'high') effectiveErrors += wCount;
-    else if (v.severity === 'low') { /* ignored for exit */ }
-    else effectiveWarnings += wCount;
-  }
+  const effectiveErrors = activeResults.reduce((sum, v) => sum + v.effectiveErrors, 0);
+  const effectiveWarnings = activeResults.reduce((sum, v) => sum + v.effectiveWarnings, 0);
+  const effectiveInfos = activeResults.reduce((sum, v) => sum + v.effectiveInfos, 0);
 
   // The headline status word MUST agree with the exit code, which is
   // severity-aware (effectiveErrors/effectiveWarnings, computed above).
@@ -523,6 +535,7 @@ export function runGuardInternal(projectDir, config) {
     // things they've marked as high-severity.
     effectiveErrors,
     effectiveWarnings,
+    effectiveInfos,
     baselineSuppressed,
     coverage,
     checkCoverage,
@@ -569,14 +582,21 @@ export function liteValidatorsConfig(config = {}) {
     'security', 'architecture', 'freshness', 'traceability', 'docsDiff',
     'apiSurface', 'metadataSync', 'docsCoverage', 'docQuality', 'todoTracking',
     'schemaSync', 'specKit', 'crossReference', 'generatedStaleness',
-    'canonicalSync', 'metricsConsistency',
+    'canonicalSync', 'surfaceSync', 'metricsConsistency', 'documentLifecycle',
+    'specRegistry', 'diffSuspicion', 'referenceExistence', 'apiDocSmells',
     'evidence',
   ];
   const userValidators = (config && config.validators) || {};
+  const exactHighValidators = new Set(
+    Object.entries(config.findingSeverity || {})
+      .filter(([, level]) => typeof level === 'string' && level.toLowerCase() === 'high')
+      .map(([code]) => CODES[code.toUpperCase()]?.validator)
+      .filter(Boolean)
+  );
   const out = {};
   for (const k of all) {
     let enabled = CHANGED_ONLY_VALIDATORS.includes(k);
-    if (!enabled && resolveSeverity(config, k) === 'high' && userValidators[k] !== false) {
+    if (!enabled && (resolveSeverity(config, k) === 'high' || exactHighValidators.has(k)) && userValidators[k] !== false) {
       enabled = true;
     }
     out[k] = enabled;
@@ -712,6 +732,9 @@ export function runGuard(projectDir, config, flags) {
     } else {
       console.log(`  ${c.yellow}⚠️  ${v.name}${c.reset} ${qBadge}${c.dim}  ${v.passed}/${v.total} checks passed${c.reset}`);
     }
+    if (v.requirementCoverage?.deferred > 0) {
+      console.log(`     ${c.dim}${v.requirementCoverage.deferred} planned requirement(s) deferred by reviewed lifecycle${c.reset}`);
+    }
 
     // --show-failing forces enumeration of every error/warning regardless of
     // overall validator status — useful when a validator passes overall
@@ -725,12 +748,13 @@ export function runGuard(projectDir, config, flags) {
     for (const item of renderableItems(v)) {
       if (item.severity === 'error' && !showErr) continue;
       if (item.severity === 'warn' && !showWarn) continue;
-      const mark = item.severity === 'error' ? `${c.red}✗` : `${c.yellow}⚠`;
+      const effective = item.effectiveSeverity || item.severity;
+      const mark = effective === 'error' ? `${c.red}✗` : effective === 'info' ? `${c.cyan}•` : `${c.yellow}⚠`;
       const codeTag = item.code ? `${c.dim}[${item.code}]${c.reset} ` : '';
       const conf = item.confidence === 'low'
         ? ` ${c.dim}(low confidence — possible false positive)${c.reset}` : '';
       console.log(`     ${mark} ${codeTag}${item.message}${c.reset}${conf}`);
-      if (item.suggestion) {
+      if (item.suggestion?.text) {
         console.log(`       ${c.cyan}→${c.reset} ${c.dim}${item.suggestion.text}${c.reset}`);
         if (item.suggestion.command) {
           console.log(`         ${c.cyan}${item.suggestion.command}${c.reset}`);
@@ -927,13 +951,17 @@ export function runGuard(projectDir, config, flags) {
   // "high"), show a one-line note so the user knows the exit code may not
   // match what they expected from reading the warning count.
   const severityShifted =
-    data.effectiveErrors !== data.errors || data.effectiveWarnings !== data.warnings;
+    data.effectiveErrors !== data.errors || data.effectiveWarnings !== data.warnings || data.effectiveInfos > 0;
   if (severityShifted) {
-    const upgraded = data.effectiveErrors - data.errors;
-    const ignored = data.warnings - data.effectiveWarnings - upgraded;
+    const upgraded = data.findings.filter(f => f.severity === 'warn' && f.effectiveSeverity === 'error').length
+      + data.validators.filter(v => !Array.isArray(v.findings) || v.findings.length === 0)
+        .reduce((sum, v) => sum + (v.severity === 'high' ? v.warnings.length : 0), 0);
+    const demotedErrors = data.findings.filter(f => f.severity === 'error' && f.effectiveSeverity !== 'error').length;
+    const informational = data.effectiveInfos;
     const parts = [];
     if (upgraded > 0) parts.push(`${upgraded} warning(s) escalated to fail (severity=high)`);
-    if (ignored > 0) parts.push(`${ignored} warning(s) ignored for exit code (severity=low)`);
+    if (demotedErrors > 0) parts.push(`${demotedErrors} intrinsic error(s) explicitly demoted by finding code`);
+    if (informational > 0) parts.push(`${informational} finding(s) informational for exit code (severity=low)`);
     if (parts.length > 0) {
       console.log(`\n  ${c.dim}Severity override: ${parts.join('; ')}.${c.reset}`);
     }