docguard-cli 0.34.9 → 0.36.0

package/cli/commands/guard.mjs

@@ -1,3 +1,5 @@
+import { describeCheckCoverage, summarizeCheckCoverage } from '../validator-coverage.mjs';
+import { applyDocRoles } from '../shared-doc-roles.mjs';
 /**
  * Guard Command — Validate project against its canonical documentation
  * Runs all enabled validators and reports results.
@@ -8,7 +10,7 @@
  */
 
 import { c, resolveSeverity, loadIgnorePatterns, resolveDocDirs } from '../shared.mjs';
-import { walkFiles } from '../shared-ignore.mjs';
+import { walkFiles, buildIgnoreFilter } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { loadValidatorSuppressions } from '../validator-markers.mjs';
 import { detectAgentMode, isSpecKitInitialized } from '../ensure-skills.mjs';
@@ -239,28 +241,29 @@ function collectMarkdown(projectDir) {
 /**
  * Classify every discoverable Markdown file into a validation tier:
  *   canonical    — in requiredFiles.canonical (structure + review-gated)
- *   tracked      — under a doc home or root-level (claim/freshness checks reach it)
+ *   tracked      — inventoried under a doc home or at root; individual detector scopes differ
  *   ignored      — matched by .docguardignore
  *   unclassified — under NO tier; drift here is invisible (the Gap-1 trap)
  */
 function computeDocCoverage(projectDir, config) {
-  const isIgnored = loadIgnorePatterns(projectDir);
+  const fileIgnored = loadIgnorePatterns(projectDir);
+  const configIgnored = buildIgnoreFilter(config.ignore || []);
+  const isIgnored = path => fileIgnored(path) || configIgnored(path);
   const canonical = new Set(
     ((config.requiredFiles && config.requiredFiles.canonical) || []).map(p => p.replace(/\\/g, '/'))
   );
   // Any path declared in documentTypes is a KNOWN doc (even if optional) — not
   // "untracked." This keeps the warning specific to genuinely-unenrolled files.
   const known = new Set(Object.keys(config.documentTypes || {}).map(p => p.replace(/\\/g, '/')));
-  // Same doc-home set the claim scanner uses — so "tracked" provably means
-  // "actually scanned," never a label the scanner ignores. With trailing slash
-  // for prefix matching.
+  // This is a document inventory, not a claim that every detector checks
+  // each tracked file. Keep individual check coverage separate.
   const docHomePrefixes = resolveDocDirs(projectDir, config).map(d => d.replace(/\/?$/, '/'));
   const all = collectMarkdown(projectDir);
   let canonicalCount = 0, tracked = 0, ignored = 0;
   const unclassified = [];
   for (const rel of all) {
-    if (canonical.has(rel)) { canonicalCount++; continue; }
     if (isIgnored(rel) || DOCGUARD_OWN_DOC_RE.test(rel)) { ignored++; continue; }
+    if (canonical.has(rel)) { canonicalCount++; continue; }
     const inHome = docHomePrefixes.some(h => rel.startsWith(h));
     const atRoot = !rel.includes('/');
     if (inHome || atRoot || known.has(rel)) { tracked++; continue; }
@@ -270,6 +273,7 @@ function computeDocCoverage(projectDir, config) {
 }
 
 export function runGuardInternal(projectDir, config) {
+  config = applyDocRoles(projectDir, config);
   const validators = config.validators || {};
   const results = [];
 
@@ -286,8 +290,7 @@ export function runGuardInternal(projectDir, config) {
     { key: 'freshness', name: 'Freshness', fn: () => {
       // v0.29: adapter now emits structured findings (FRS001–FRS005). The
       // validator keeps its array-of-{status, code, doc, message} contract;
-      // messages are byte-identical (the sweep-needed nudge below regex-matches
-      // them), so counts/exit codes are unchanged.
+      // messages describe review signals rather than asserting semantic drift.
       const freshnessResults = validateFreshness(projectDir, config);
       const findings = [];
       let passed = 0;
@@ -298,14 +301,14 @@ export function runGuardInternal(projectDir, config) {
           code: r.code || null,
           validator: 'freshness',
           severity: r.status === 'fail' ? 'error' : 'warn',
+          confidence: r.confidence || 'low',
           message: r.message,
           location: r.doc || null,
-          suggestion: r.code === 'FRS001'
-            ? { kind: 'fix', text: 'Commit the doc, or stamp it reviewed', pragma: '<!-- docguard:last-reviewed YYYY-MM-DD -->' }
-            : { kind: 'fix', text: 'Refresh the stale code-truth sections', command: 'docguard sync --write' },
+          suggestion: r.suggestion || { kind: 'review', text: 'Review the document against its intended scope. A history signal does not establish which side should change.' },
         }));
       }
-      return resultFromFindings(findings, { passed, total: passed + findings.length });
+      const skipped = freshnessResults.filter(r => r.status === 'skip');
+      return { ...resultFromFindings(findings, { passed, total: passed + findings.length }), ...(passed + findings.length === 0 && skipped.length ? { applicability: { status: 'no-matches', reason: skipped.map(r => r.message).join('; ') } } : {}) };
     }},
     { key: 'traceability', name: 'Traceability', fn: () => validateTraceability(projectDir, config) },
     { key: 'docsDiff', name: 'Docs-Diff', fn: () => validateDocsDiff(projectDir, config) },
@@ -358,7 +361,7 @@ export function runGuardInternal(projectDir, config) {
       results.push({ ...result, name, key, durationMs, ...classifyResult(result) });
     } catch (err) {
       const durationMs = Math.round((performance.now() - start) * 100) / 100;
-      results.push({ name, key, status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
+      results.push({ name, key, status: 'fail', quality: 'LOW', applicability: { status: 'error', reason: 'Validator could not complete: ' + err.message }, errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
@@ -376,7 +379,7 @@ export function runGuardInternal(projectDir, config) {
       results.push({ ...result, name: 'Canonical-Sync', key: 'canonicalSync', durationMs, ...classifyResult(result) });
     } catch (err) {
       const durationMs = Math.round((performance.now() - start) * 100) / 100;
-      results.push({ name: 'Canonical-Sync', key: 'canonicalSync', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
+      results.push({ name: 'Canonical-Sync', key: 'canonicalSync', status: 'fail', quality: 'LOW', applicability: { status: 'error', reason: 'Validator could not complete: ' + err.message }, errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
@@ -391,7 +394,7 @@ export function runGuardInternal(projectDir, config) {
       results.push({ ...result, name: 'Metrics-Consistency', key: 'metricsConsistency', durationMs, ...classifyResult(result) });
     } catch (err) {
       const durationMs = Math.round((performance.now() - start) * 100) / 100;
-      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
+      results.push({ name: 'Metrics-Consistency', key: 'metricsConsistency', status: 'fail', quality: 'LOW', applicability: { status: 'error', reason: 'Validator could not complete: ' + err.message }, errors: [err.message], warnings: [], passed: 0, total: 1, durationMs });
     }
   }
 
@@ -431,6 +434,11 @@ export function runGuardInternal(projectDir, config) {
     }
   }
 
+  for (const key of ['canonicalSync', 'metricsConsistency']) {
+    if (validators[key] === false && !results.some(r => r.key === key)) results.push({ key, name: key === 'canonicalSync' ? 'Canonical-Sync' : 'Metrics-Consistency', status: 'skipped', quality: null, errors: [], warnings: [], passed: 0, total: 0, durationMs: 0 });
+  }
+  for (const result of results) result.applicability = describeCheckCoverage(projectDir, config, result);
+  const checkCoverage = summarizeCheckCoverage(results);
   const activeResults = results.filter(r => r.status !== 'skipped');
   const totalErrors = activeResults.reduce((sum, r) => sum + r.errors.length, 0);
   const totalWarnings = activeResults.reduce((sum, r) => sum + r.warnings.length, 0);
@@ -504,6 +512,7 @@ export function runGuardInternal(projectDir, config) {
     effectiveWarnings,
     baselineSuppressed,
     coverage,
+    checkCoverage,
     semanticClaims,
     validators: results,
     // Unknown keys in `docguard:validator … n/a` markers — typo protection so
@@ -671,8 +680,9 @@ export function runGuard(projectDir, config, flags) {
     // Not applicable — nothing to validate. Render neutrally (NOT a green pass)
     // so the reader can tell "checked and clean" apart from "nothing checked".
     if (v.status === 'na') {
-      const reason = v.note ? ` ${c.dim}(${v.note})${c.reset}` : ` ${c.dim}(nothing to validate)${c.reset}`;
-      console.log(`  ${c.dim}➖ ${v.name}${c.reset} ${c.dim}[N/A]${c.reset}${reason}`);
+      const showReason = flags.verbose || ['unsupported', 'partial', 'missing-prerequisite', 'error'].includes(v.applicability.status);
+      const reason = showReason ? ` ${c.dim}(${v.applicability.reason})${c.reset}` : '';
+      console.log(`  ${c.dim}➖ ${v.name}${c.reset} ${c.dim}[${v.applicability.status}]${c.reset}${reason}`);
       continue;
     }
 
@@ -770,6 +780,8 @@ export function runGuard(projectDir, config, flags) {
   if (Array.isArray(data.reportable) && data.reportable.length > 0) {
     const n = data.reportable.length;
     console.log(`  ${c.dim}↪ ${n} finding(s) look uncertain (possible false positives). Review or report: ${c.cyan}${skill('feedback')}${c.reset}`);
+  } else if (Array.isArray(data.findings) && data.findings.length > 0) {
+    console.log(`  ${c.dim}Disagree with a finding? Review a contribution: ${c.cyan}docguard feedback --code <CODE> --preview${c.reset}`);
   }
 
   // Read-only skills nudge (never writes — that's `init`'s job). If the agent
@@ -801,9 +813,14 @@ export function runGuard(projectDir, config, flags) {
       }
     }
   }
+  if (data.checkCoverage) {
+    const counts = data.checkCoverage.counts;
+    console.log('  Check coverage: ' + Object.entries(counts).filter(([, count]) => count > 0).map(([status, count]) => count + ' ' + status.replaceAll('-', ' ')).join(' · '));
+    console.log('  Document inventory and passing checks do not establish factual accuracy.');
+  }
   if (data.semanticClaims && data.semanticClaims.count > 0) {
     console.log(`\n  ${c.cyan}🔍 ${data.semanticClaims.count} documented claim(s) (counts/limits/enums) are unverified against code.${c.reset}`);
-    console.log(`     ${c.dim}A green guard means the structure is sound — NOT that these values still match the code.${c.reset}`);
+    console.log(`     ${c.dim}A passing guard means configured gates passed; these values remain unverified.${c.reset}`);
     console.log(`     ${c.dim}Confirm them: ${c.cyan}${skill('verify')} --semantic${c.reset}`);
   }
 
@@ -873,7 +890,7 @@ export function runGuard(projectDir, config, flags) {
     if (freshness && freshness.warnings) {
       const staleDocs = freshness.warnings.filter(w => /\d+ code commits since/.test(w));
       if (staleDocs.length >= 2) {
-        console.log(`\n  ${c.yellow}↻ ${staleDocs.length} docs are stale (10+ commits since last update). Run ${c.cyan}docguard sync --write${c.yellow} to refresh code-truth sections in one pass.${c.reset}`);
+        console.log(`\n  ${c.yellow}↻ ${staleDocs.length} documents have repository-history review signals. Review their scope and intended behavior before changing documentation or code.${c.reset}`);
       }
     }
   }

package/cli/commands/hooks.mjs

@@ -3,7 +3,7 @@
  * Creates git hooks that run guard/score before commits.
  */
 
-import { existsSync, writeFileSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
 
 // v0.16-P3: managed-block markers. Letting users extend the hook with their
 // own commands (data-file guards, lint checks, etc.) without us clobbering
@@ -56,9 +56,28 @@ function spliceManagedBlock(existing, newBody) {
 }
 import { resolve, relative, basename } from 'node:path';
 import { c } from '../shared.mjs';
+import { safeWrite } from '../writers/generate-io.mjs';
 import { getHooksDir } from '../shared-git.mjs';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
 
+// Git enforcement is offline and fail-closed; agent nudges stay best-effort.
+const ENFORCEMENT_RUNTIME = `
+if ! command -v node >/dev/null 2>&1; then
+  echo "❌ Node.js runtime not found — operation blocked" >&2
+  exit 1
+fi
+
+# Git runs these hooks from the worktree root. Prefer its installed version.
+if [ -x "./node_modules/.bin/docguard" ]; then
+  DOCGUARD="./node_modules/.bin/docguard"
+elif command -v docguard >/dev/null 2>&1; then
+  DOCGUARD="docguard"
+else
+  echo "❌ DocGuard not found locally or on PATH — operation blocked" >&2
+  exit 1
+fi
+`;
+
 const HOOKS = {
   'pre-commit': {
     description: 'Run docguard guard before every commit',
@@ -70,20 +89,11 @@ const HOOKS = {
 
 echo "🛡️  Running DocGuard guard..."
 
-# Check if docguard is available
-if command -v npx &> /dev/null; then
-  npx docguard-cli guard
-  EXIT_CODE=$?
-elif command -v docguard &> /dev/null; then
-  docguard guard
-  EXIT_CODE=$?
-else
-  echo "⚠️  DocGuard not found. Skipping guard check."
-  echo "   Install: npm install -g docguard"
-  exit 0
-fi
+${ENFORCEMENT_RUNTIME}
+"$DOCGUARD" guard
+EXIT_CODE=$?
 
-if [ $EXIT_CODE -eq 1 ]; then
+if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
   echo ""
   echo "❌ DocGuard guard FAILED — commit blocked"
   echo "   Fix the errors above, then try again."
@@ -110,22 +120,28 @@ MIN_SCORE=60
 
 echo "📊 Running DocGuard score check (minimum: $MIN_SCORE)..."
 
-# Get score as JSON
-if command -v npx &> /dev/null; then
-  RESULT=$(npx docguard-cli score --format json 2>/dev/null)
-elif command -v docguard &> /dev/null; then
-  RESULT=$(docguard score --format json 2>/dev/null)
-else
-  echo "⚠️  DocGuard not found. Skipping score check."
-  exit 0
-fi
+${ENFORCEMENT_RUNTIME}
 
-# Parse score from JSON
-SCORE=$(echo "$RESULT" | grep -o '"score":[0-9]*' | head -1 | cut -d: -f2)
+# Score has no warning exit status: any command failure blocks the push.
+RESULT=$("$DOCGUARD" score --format json)
+EXIT_CODE=$?
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "❌ DocGuard score failed (exit $EXIT_CODE) — push blocked" >&2
+  exit 1
+fi
 
-if [ -z "$SCORE" ]; then
-  echo "⚠️  Could not determine CDD score. Push allowed."
-  exit 0
+# Parse the complete JSON document, never a substring or a nested score.
+SCORE=$(printf '%s' "$RESULT" | node -e '
+  try {
+    const result = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
+    if (!result || Array.isArray(result) || !Number.isInteger(result.score) ||
+        result.score < 0 || result.score > 100) process.exit(1);
+    process.stdout.write(String(result.score));
+  } catch { process.exit(1); }
+')
+if [ "$?" -ne 0 ] || [ -z "$SCORE" ]; then
+  echo "❌ Could not determine a valid CDD score — push blocked" >&2
+  exit 1
 fi
 
 echo "   CDD Score: $SCORE/100"
@@ -188,24 +204,29 @@ const PRE_COMMIT_AUTOFIX = `#!/bin/sh
 # Install: docguard hooks --type pre-commit --auto-fix
 # Remove: rm .git/hooks/pre-commit
 
-RUN="npx docguard-cli"
-if command -v docguard >/dev/null 2>&1; then RUN="docguard"; fi
+${ENFORCEMENT_RUNTIME}
 
 echo "🛡️  DocGuard: applying mechanical fixes…"
 # 1. Deterministically remove stale documented endpoints (safe, no AI).
-$RUN fix --write
+if ! "$DOCGUARD" fix --write; then
+  echo "❌ DocGuard fix failed — commit blocked" >&2
+  exit 1
+fi
 # 2. Re-stage anything DocGuard rewrote so the fix is part of THIS commit.
-git add docs-canonical/ 2>/dev/null
+if ! git add docs-canonical/; then
+  echo "❌ Could not stage DocGuard fixes — commit blocked" >&2
+  exit 1
+fi
 
 # 3. Validate.
-$RUN guard
+"$DOCGUARD" guard
 EXIT_CODE=$?
 
-if [ $EXIT_CODE -eq 1 ]; then
+if [ "$EXIT_CODE" -ne 0 ] && [ "$EXIT_CODE" -ne 2 ]; then
   echo ""
   echo "❌ DocGuard guard FAILED — commit blocked."
   echo "   Remaining issues need an AI agent (content rewrites, not mechanical):"
-  echo "   Run: $RUN diagnose   (emits ready-to-paste agent fix prompts)"
+  echo "   Run: $DOCGUARD diagnose   (emits ready-to-paste agent fix prompts)"
   echo "   To skip: git commit --no-verify"
   exit 1
 elif [ $EXIT_CODE -eq 2 ]; then
@@ -306,7 +327,7 @@ export function runHooks(projectDir, config, flags) {
       // re-install.
       const spliced = spliceManagedBlock(existing, newContent);
       if (spliced !== null) {
-        writeFileSync(hookPath, spliced, 'utf-8');
+        safeWrite(hookPath, spliced);
         chmodSync(hookPath, 0o755);
         console.log(`  ${c.green}↻ ${name}${c.reset}: updated DocGuard managed block (preserved user content around it)`);
         installed++;
@@ -330,7 +351,7 @@ export function runHooks(projectDir, config, flags) {
       // --force path: write fresh managed-block version
     }
 
-    writeFileSync(hookPath, newContent, 'utf-8');
+    safeWrite(hookPath, newContent);
     chmodSync(hookPath, 0o755);
     console.log(`  ${c.green}✅ ${name}${c.reset}: ${desc}`);
     installed++;
@@ -402,7 +423,7 @@ export function installClaudeNudge(projectDir, { remove = false } = {}) {
     settings.hooks.PostToolUse = groups.filter(g => !isOurNudgeGroup(g));
     if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
     if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    safeWrite(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     console.log(`  ${c.yellow}🗑️  Removed the DocGuard nudge hook from .claude/settings.json${c.reset} ${c.dim}(everything else preserved)${c.reset}\n`);
     return;
   }
@@ -420,7 +441,7 @@ export function installClaudeNudge(projectDir, { remove = false } = {}) {
   });
 
   if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  safeWrite(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   console.log(`  ${c.green}✅ Installed the DocGuard nudge hook${c.reset} → .claude/settings.json (PostToolUse)`);
   console.log(`  ${c.dim}After an agent edits a canonical doc (or code the docs reference), it is${c.reset}`);
   console.log(`  ${c.dim}nudged toward docguard guard --changed-only / docguard impact.${c.reset}`);
@@ -472,7 +493,7 @@ export function runNudgeHook(projectDir) {
     state[rel] = now;
     try {
       mkdirSync(resolve(projectDir, '.docguard'), { recursive: true });
-      writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+      safeWrite(statePath, JSON.stringify(state, null, 2) + '\n');
     } catch { /* state is best-effort; still nudge */ }
 
     process.stdout.write(JSON.stringify({ decision: 'block', reason }) + '\n');

package/cli/commands/init.mjs

@@ -1,3 +1,4 @@
+import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
 /**
  * Init Command — Initialize CDD documentation from templates
  *
@@ -9,7 +10,7 @@
  * with a warning suggesting spec-kit installation.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, lstatSync, realpathSync, copyFileSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { listCanonicalDocs } from '../shared-ignore.mjs';
 import { fileURLToPath } from 'node:url';
@@ -17,14 +18,15 @@ import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
 import { c, PROFILES, CURRENT_SCHEMA_VERSION } from '../shared.mjs';
 import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent, safeSpawnSpecify } from '../ensure-skills.mjs';
+import { safeWrite } from '../writers/generate-io.mjs';
 
 // v0.20: scaffolder names that can be passed via `init --with <name>` and
-// dispatched to the corresponding standalone runner. Each name maps to its
-// canonical command module. Keep in sync with cli/docguard.mjs router.
+// dispatched to their writers. CI scaffolding is distinct from the standalone
+// `ci` validation gate; it copies the maintained workflow starter.
 const SCAFFOLDER_DISPATCH = {
   agents:  async (dir, cfg, flags) => (await import('./agents.mjs')).runAgents(dir, cfg, flags),
   hooks:   async (dir, cfg, flags) => (await import('./hooks.mjs')).runHooks(dir, cfg, flags),
-  ci:      async (dir, cfg, flags) => (await import('./ci.mjs')).runCI(dir, cfg, flags),
+  ci:      (dir, cfg, flags) => scaffoldCI(dir, flags),
   badge:   async (dir, cfg, flags) => (await import('./badge.mjs')).runBadge(dir, cfg, flags),
   llms:    async (dir, cfg, flags) => (await import('./llms.mjs')).runLlms(dir, cfg, flags),
   publish: async (dir, cfg, flags) => (await import('./publish.mjs')).runPublish(dir, cfg, flags),
@@ -79,6 +81,43 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = resolve(__dirname, '../../templates');
 
+function scaffoldCI(projectDir, flags) {
+  // Resolve the user's root once (e.g. macOS /tmp), then refuse symlinks in
+  // every destination component, including the backup safeWrite will use.
+  const root = realpathSync(projectDir);
+  const target = resolve(root, '.github/workflows/docguard.yml');
+  let existing;
+  for (const [path, directory] of [
+    [resolve(root, '.github'), true],
+    [dirname(target), true],
+    [target, false],
+    [target + '.bak', false],
+  ]) {
+    let stat;
+    try { stat = lstatSync(path); } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw err;
+    }
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile())) {
+      throw new Error(`Unsafe CI scaffold path: ${path} (expected a real ${directory ? 'directory' : 'file'}, not a symlink)`);
+    }
+    if (!directory && stat.nlink > 1) throw new Error(`Unsafe CI scaffold path: ${path} (hard-linked file)`);
+    if (path === target) existing = stat;
+  }
+  if (existing && !flags.force) {
+    console.log(`  ${c.dim}⏭️  .github/workflows/docguard.yml exists; use --force to overwrite${c.reset}`);
+    return;
+  }
+  // Copy literally: the starter's fixed package pin is release-tested, and
+  // GitHub expressions must not go through canonical-doc interpolation.
+  const content = readFileSync(resolve(TEMPLATES_DIR, 'ci/github-actions.yml'), 'utf-8');
+  // safeWrite's generic backup is best-effort and skips empty files. Here a
+  // forced replacement requires a successful backup, including empty files.
+  if (existing) copyFileSync(target, target + '.bak');
+  safeWrite(target, content);
+  console.log(`  ${c.green}✅ .github/workflows/docguard.yml ${existing ? 'replaced (backup: docguard.yml.bak)' : 'created'}${c.reset}`);
+}
+
 /**
  * v0.28 (field report #11): inject a `<!-- docguard:last-reviewed DATE -->`
  * marker right after the first H1, so a canonical doc has a freshness signal the
@@ -160,6 +199,7 @@ function shouldRunGenerate(projectDir, flags) {
 }
 
 export async function runInit(projectDir, config, flags) {
+  if (true) assertDefaultDocWrites(config);
   // v0.20: `--wizard` dispatches to the full interactive onboarding (formerly
   // `docguard setup`). Done before profile validation so the wizard can ask
   // for the profile itself if needed.
@@ -178,7 +218,13 @@ export async function runInit(projectDir, config, flags) {
     console.log(`${c.dim}   canonical docs from your code instead of dumping a blank skeleton.${c.reset}`);
     console.log(`${c.dim}   (Opt out: ${c.cyan}docguard init --skeleton${c.dim} for the blank-template path.)${c.reset}\n`);
     const { runGenerate } = await import('./generate.mjs');
-    return runGenerate(projectDir, config, { ...flags, plan: true });
+    const result = await runGenerate(projectDir, config, { ...flags, plan: true });
+    // Smart init still honors explicit workflow/scaffolder requests after the
+    // plan, with the same ordering and stop-on-failure semantics as skeletons.
+    if (Array.isArray(flags.with) && flags.with.length > 0) {
+      await runScaffolders(projectDir, config, flags, flags.with);
+    }
+    return result;
   }
 
   const profileName = flags.profile || 'standard';

package/cli/commands/memory.mjs

@@ -21,10 +21,12 @@
  * Zero NPM dependencies. Pure orchestration of existing diff helpers.
  */
 
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { c } from '../shared.mjs';
-import { listCanonicalDocs } from '../shared-ignore.mjs';
+import { createEvidenceReader, evidenceDocs, extractSemanticClaims, contentHash, gitEvidence, SEMANTIC_COVERAGE_LIMITATION } from '../scanners/semantic-claims.mjs';
+import { safeWrite } from '../writers/generate-io.mjs';
+import { buildScoreAssurance } from './score.mjs';
 import { diffRoutes, diffEntities, diffEnvVars, diffTechStack } from './diff.mjs';
 import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
 import { runGuardInternal } from './guard.mjs';
@@ -75,13 +77,17 @@ function extractConventions(agentsMd, capLines = 60) {
 
 /**
  * `docguard memory --pack` — write .docguard/context-pack.md: a compact,
- * code-truth-stamped session-start context for an AI agent. Everything in it
- * is derived from scanners (buildMemoryPlan) and guard — numbers, not prose —
- * so it can't hallucinate and is always regenerable.
+ * session-start snapshot for an AI agent. Scanner output and copied prose
+ * remain unverified; hashes identify captured inputs, not factual accuracy.
  */
 function runMemoryPack(projectDir, config, flags) {
-  const plan = buildMemoryPlan(projectDir, config);
+  const plan = buildMemoryPlan(projectDir, { ...config, diskCache: false });
   const guard = runGuardInternal(projectDir, config);
+  const read = createEvidenceReader(projectDir);
+  const git = gitEvidence(projectDir);
+  const assurance = buildScoreAssurance(projectDir, config);
+  let claims = null;
+  try { claims = extractSemanticClaims(projectDir, config, read); } catch { /* unknown, not an empty verified set */ }
   const lines = [];
 
   lines.push(`# Context Pack — ${config.projectName}`);
@@ -91,6 +97,15 @@ function runMemoryPack(projectDir, config, flags) {
   lines.push(`**Guard:** ${guard.status} — ${guard.passed}/${guard.total} checks (${guard.errors} error(s), ${guard.warnings} warning(s))`);
   lines.push('');
 
+  lines.push('**Provenance:** snapshot only — not reviewed or verified');
+  lines.push(`- Git revision: ${git.revision ?? 'unknown'} · dirty: ${git.dirty ?? 'unknown'}`);
+  lines.push(`- Assurance: structural-only · factual accuracy: unknown · status: ${assurance.status}`);
+  lines.push(`- Unverified claims: ${assurance.unverifiedClaims ?? 'unknown'} extracted candidates (heuristic and capped; zero does not establish prose correctness)`);
+  lines.push(`- Claim evidence fingerprint: ${claims ? contentHash(JSON.stringify(claims.map(c => [c.stableId, c.evidence.snapshotHash]).sort())) : 'unknown'}`);
+  lines.push(`- Coverage limitation: ${SEMANTIC_COVERAGE_LIMITATION}`);
+  lines.push('Hashes capture current document and cited-source content. Regenerate after changes; timestamps and last-reviewed labels do not establish accuracy.');
+  lines.push('');
+
   lines.push('## Code-truth surface');
   lines.push('');
   lines.push(`- Stack: ${plan.profile.languages.join(', ') || 'unknown'}${plan.profile.frameworks.length ? ` · ${plan.profile.frameworks.join(', ')}` : ''} · kind: ${plan.profile.kind}`);
@@ -98,17 +113,18 @@ function runMemoryPack(projectDir, config, flags) {
   lines.push(`- Tests: ${plan.surface.tests.totalFiles} files, ${plan.surface.tests.totalCases} cases`);
   lines.push('');
 
-  const canonicalDocs = listCanonicalDocs(projectDir);
+  const canonicalDocs = evidenceDocs(projectDir, config);
   if (canonicalDocs.length > 0) {
     lines.push('## Canonical docs');
     lines.push('');
     for (const doc of canonicalDocs) {
       let reviewed = '';
       try {
-        const m = readFileSync(doc.abs, 'utf-8').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
+        const m = (read(doc).content || '').match(/docguard:last-reviewed\s+(\d{4}-\d{2}-\d{2})/);
         if (m) reviewed = ` (last-reviewed ${m[1]})`;
       } catch { /* ignore */ }
-      lines.push(`- ${doc.rel}${reviewed}`);
+      const evidence = read(doc).evidence;
+      lines.push(`- ${doc}${reviewed} — content: ${evidence.hash ?? `unknown (${evidence.reason})`}`);
     }
     lines.push('');
   }
@@ -116,7 +132,7 @@ function runMemoryPack(projectDir, config, flags) {
   const agentsPath = resolve(projectDir, 'AGENTS.md');
   if (existsSync(agentsPath)) {
     let conventions = [];
-    try { conventions = extractConventions(readFileSync(agentsPath, 'utf-8')); } catch { /* ignore */ }
+    try { conventions = extractConventions(read('AGENTS.md').content || ''); } catch { /* ignore */ }
     if (conventions.length > 0) {
       lines.push('## Project rules (from AGENTS.md)');
       lines.push('');
@@ -128,7 +144,7 @@ function runMemoryPack(projectDir, config, flags) {
   const driftPath = resolve(projectDir, 'DRIFT-LOG.md');
   if (existsSync(driftPath)) {
     try {
-      const drift = readFileSync(driftPath, 'utf-8');
+      const drift = read('DRIFT-LOG.md').content || '';
       const entries = drift.match(/^##\s+.+$/gm) || [];
       if (entries.length > 0) {
         lines.push('## Known drift');
@@ -148,10 +164,8 @@ function runMemoryPack(projectDir, config, flags) {
     console.log(content);
     return;
   }
-  const outDir = resolve(projectDir, '.docguard');
-  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
-  const outPath = resolve(outDir, 'context-pack.md');
-  writeFileSync(outPath, content, 'utf-8');
+  const outPath = resolve(projectDir, '.docguard/context-pack.md');
+  safeWrite(outPath, content);
   console.log(`${c.bold}🧠 DocGuard Context Pack${c.reset}`);
   console.log(`${c.green}✅ Wrote ${outPath}${c.reset} ${c.dim}(${lines.length} lines — load at agent session start)${c.reset}`);
   console.log('');

package/cli/commands/report.mjs

@@ -74,22 +74,25 @@ export function buildReport(projectDir, config) {
       // Audit-critical (H3): evidence must disclose what a committed baseline
       // is suppressing — "no findings" with a hidden baseline is false green.
       baselineSuppressed: guardData.baselineSuppressed || 0,
+        checkCoverage: guardData.checkCoverage,
       validators: (guardData.validators || [])
         .filter(v => v.status !== 'skipped')
-        .map(v => ({ name: v.name, status: v.status })),
+        .map(v => ({ name: v.name, status: v.status, applicability: v.applicability })),
     },
     findings: findingsSummary,
     score: {
       score: scoreData.score,
       grade: scoreData.grade,
       categories: scoreData.categories,
+      scoreKind: scoreData.scoreKind,
+      assurance: scoreData.assurance,
     },
     alcoa: {
       score: alcoa.score,
       met: alcoa.met,
       total: alcoa.total,
       attributes: alcoa.attributes.map(a => ({
-        name: a.name, met: a.met, evidence: a.evidence, gap: a.gap,
+        name: a.name, met: a.met, status: a.status || (a.met ? 'met' : 'unmet'), evidence: a.evidence, gap: a.gap,
       })),
     },
     fixHistory: {
@@ -109,7 +112,7 @@ export function buildReport(projectDir, config) {
   return { ...payload, generatedAt: new Date().toISOString(), integrity };
 }
 
-function toMarkdown(r) {
+export function toMarkdown(r) {
   const lines = [];
   const gitLine = r.git
     ? `commit \`${r.git.commit.slice(0, 12)}\`${r.git.branch ? ` (${r.git.branch})` : ' (detached HEAD)'}${r.git.dirty ? ' — **uncommitted changes present**' : ''}`
@@ -123,7 +126,8 @@ function toMarkdown(r) {
   lines.push('');
   lines.push('| Metric | Value |');
   lines.push('|--------|-------|');
-  lines.push(`| CDD Score | ${r.score.score}/100 (${r.score.grade}) |`);
+  lines.push(`| CDD Score (structural maturity) | ${r.score.score}/100 (${r.score.grade}) |`);
+  lines.push(`| Factual accuracy | Unverified — ${r.score.assurance.unverifiedClaims ?? 'unknown number of'} extracted claim(s); discovery is heuristic |`);
   lines.push(`| Guard | ${r.guard.status.toUpperCase()} — ${r.guard.passed}/${r.guard.total} checks, ${r.guard.errors} error(s), ${r.guard.warnings} warning(s) |`);
   if (r.guard.baselineSuppressed > 0) {
     lines.push(`| Baseline | ⚠️ ${r.guard.baselineSuppressed} pre-existing finding(s) suppressed by \`.docguard.baseline.json\` — not reflected in the counts above |`);
@@ -147,7 +151,7 @@ function toMarkdown(r) {
   if (r.findings.length === 0) {
     lines.push(r.guard.baselineSuppressed > 0
       ? `No new findings beyond the ${r.guard.baselineSuppressed} suppressed by the committed baseline (run \`docguard guard --no-baseline\` for the full picture).`
-      : 'No findings — documentation matches the implementation at this commit.');
+      : 'No findings were emitted by the configured checks. Factual accuracy remains unverified.');
   } else {
     lines.push('| Code | Severity | Count | Example |');
     lines.push('|------|----------|------:|---------|');
@@ -159,10 +163,11 @@ function toMarkdown(r) {
 
   lines.push('## ALCOA+ Attributes');
   lines.push('');
-  lines.push('| Attribute | Met | Evidence / Gap |');
+  lines.push('| Attribute | Status | Evidence / Gap |');
   lines.push('|-----------|-----|----------------|');
   for (const a of r.alcoa.attributes) {
-    lines.push(`| ${a.name} | ${a.met ? '✅' : '❌'} | ${(a.met ? a.evidence : a.gap) || '—'} |`);
+    const status = a.status === 'unverified' ? '🔍 unverified' : a.met ? '✅ met' : '❌ unmet';
+    lines.push(`| ${a.name} | ${status} | ${(a.met ? a.evidence : a.gap) || '—'} |`);
   }
   lines.push('');