docguard-cli 0.35.0 → 0.36.0

package/cli/commands/score.mjs

@@ -1,3 +1,4 @@
+import { applyDocRoles, remapDocPath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Score Command — Calculate CDD maturity score (0-100)
  * Shows category breakdown with weighted scoring.
@@ -146,6 +147,7 @@ const WEIGHTS = {
 };
 
 export function runScore(projectDir, config, flags) {
+  config = applyDocRoles(projectDir, config);
   // v0.33: `--trend` renders the local score history recorded by `docguard
   // ci` (.docguard/history.jsonl) instead of recomputing a score.
   if (flags.trend) return runTrend(projectDir, config, flags);
@@ -162,9 +164,9 @@ export function runScore(projectDir, config, flags) {
 
   const { scores, totalScore, grade, details } = calcAllScores(projectDir, config);
 
-  // ── "Memory" framing: split signals into Completeness vs Accuracy ──
-  // Completeness = "is the memory whole?"  Accuracy = "does it match code?"
-  // No weight changes — just a derived view of the existing per-category scores.
+  // Structural signals are useful proxies, not a measurement of factual truth.
+  // Preserve threshold arithmetic while making the evidence boundary explicit.
+  const assurance = buildScoreAssurance(projectDir, config);
   const COMPLETENESS = new Set(['structure', 'docQuality']);
   const memory = (() => {
     let cW = 0, cP = 0, aW = 0, aP = 0;
@@ -175,7 +177,8 @@ export function runScore(projectDir, config, flags) {
     }
     return {
       completeness: cW ? Math.round(cP / cW) : 0,
-      accuracy: aW ? Math.round(aP / aW) : 0,
+      structuralAlignment: aW ? Math.round(aP / aW) : 0,
+      accuracy: null,
     };
   })();
 
@@ -185,6 +188,8 @@ export function runScore(projectDir, config, flags) {
       project: config.projectName,
       score: totalScore,
       grade,
+      scoreKind: 'structural-maturity',
+      assurance,
       memory,
       categories: {},
     };
@@ -193,7 +198,7 @@ export function runScore(projectDir, config, flags) {
         score,
         weight: WEIGHTS[cat],
         weighted: Math.round((score / 100) * WEIGHTS[cat]),
-        axis: COMPLETENESS.has(cat) ? 'completeness' : 'accuracy',
+        axis: COMPLETENESS.has(cat) ? 'completeness' : 'structuralAlignment',
       };
     }
     console.log(JSON.stringify(result, null, 2));
@@ -217,11 +222,11 @@ export function runScore(projectDir, config, flags) {
   console.log(`  ${gradeColor}${c.bold}CDD Maturity Score: ${totalScore}/100 (${grade})${c.reset}`);
   // Memory framing: is the documentation memory COMPLETE and ACCURATE?
   const memColor = (s) => s >= 80 ? c.green : s >= 60 ? c.yellow : c.red;
-  console.log(`  ${c.dim}Memory:${c.reset} ${memColor(memory.completeness)}Completeness ${memory.completeness}%${c.reset} ${c.dim}·${c.reset} ${memColor(memory.accuracy)}Accuracy ${memory.accuracy}%${c.reset}`);
+  console.log(`  ${c.dim}Memory:${c.reset} ${memColor(memory.completeness)}Completeness ${memory.completeness}%${c.reset} ${c.dim}·${c.reset} ${c.cyan}Factual accuracy: unverified${c.reset}`);
 
   // Grade description
   const descriptions = {
-    'A+': 'Excellent — CDD fully adopted',
+    'A+': 'Excellent structural maturity — factual claims still require verification',
     'A': 'Great — Strong CDD compliance',
     'B': 'Good — Most CDD practices in place',
     'C': 'Fair — Partial CDD adoption',
@@ -229,6 +234,7 @@ export function runScore(projectDir, config, flags) {
     'F': 'Not Started — Run `docguard init` first',
   };
   console.log(`  ${c.dim}${descriptions[grade]}${c.reset}\n`);
+  console.log(`  ${c.dim}${assurance.unverifiedClaims ?? 'Unknown number of'} extracted claim(s) await verification. No extracted claims does not prove correctness.${c.reset}\n`);
 
   // Suggestions
   const weakest = Object.entries(scores)
@@ -401,8 +407,21 @@ function runTrend(projectDir, config, flags) {
  * Used by badge, ci, and other commands that need the score.
  */
 export function runScoreInternal(projectDir, config) {
+  config = applyDocRoles(projectDir, config);
   const { scores, totalScore, grade } = calcAllScores(projectDir, config);
-  return { score: totalScore, grade, categories: scores };
+  return { score: totalScore, grade, categories: scores, scoreKind: 'structural-maturity', assurance: buildScoreAssurance(projectDir, config) };
+}
+
+/** Evidence boundary shared by human, CI, report, and MCP score consumers. */
+export function buildScoreAssurance(projectDir, config) {
+  let unverifiedClaims = null;
+  try { unverifiedClaims = extractSemanticClaims(projectDir, config).length; } catch { /* unknown, never zero on failure */ }
+  return {
+    status: 'unverified',
+    factualAccuracy: null,
+    unverifiedClaims,
+    limitation: 'Structural maturity is not factual accuracy. Claim discovery is heuristic; uncaptured prose remains unverified.',
+  };
 }
 
 /**
@@ -528,11 +547,11 @@ export function computeAlcoaCompliance(projectDir, config, scores) {
   } else {
     attributes.push({
       name: 'Accurate',
-      met: true,
-      status: 'met',
-      evidence: `Drift: ${scores.drift}%, doc quality: ${scores.docQuality}%, no unverified factual claims`,
-      gap: null,
-      fix: null,
+      met: false,
+      status: 'unverified',
+      evidence: null,
+      gap: 'No candidate claims extracted; factual accuracy of the prose has not been established',
+      fix: 'Review material claims against source evidence and approved requirements',
     });
   }
 
@@ -657,7 +676,8 @@ function calcDocQualityScore(dir, config) {
   let total = 0;
   const failures = []; // Track specific failures for actionable suggestions
 
-  for (const [file, sections] of Object.entries(checks)) {
+  for (const [defaultFile, sections] of Object.entries(checks)) {
+    const file = remapDocPath(config, defaultFile);
     const fullPath = resolve(dir, file);
     if (!existsSync(fullPath)) {
       failures.push({ file, issue: 'file missing' });
@@ -761,7 +781,7 @@ function calcTestingScore(dir, config) {
   else failures.push({ issue: 'no test files found (looked in tests/, src/**/__tests__, and configured testPatterns)' });
 
   // ── Check 2: TEST-SPEC.md exists (30 pts) ──
-  if (existsSync(resolve(dir, 'docs-canonical/TEST-SPEC.md'))) score += 30;
+  if (existsSync(resolveDocRole(dir, config, 'testSpec'))) score += 30;
   else failures.push({ issue: 'TEST-SPEC.md missing', fixCmd: 'docguard fix --doc test-spec' });
 
   // ── Check 3: Test config or built-in runner (15 pts) ──
@@ -853,7 +873,7 @@ function calcSecurityScore(dir, config) {
   const failures = [];
 
   // SECURITY.md exists (25 pts)
-  if (existsSync(resolve(dir, 'docs-canonical/SECURITY.md'))) score += 25;
+  if (existsSync(resolveDocRole(dir, config, 'security'))) score += 25;
   else failures.push({ issue: 'SECURITY.md missing', fixCmd: 'docguard fix --doc security' });
 
   // .gitignore exists and includes .env (15 + 15 pts)
@@ -908,7 +928,7 @@ function calcEnvironmentScore(dir, config) {
   const ptc = config.projectTypeConfig || {};
   const failures = [];
 
-  if (existsSync(resolve(dir, 'docs-canonical/ENVIRONMENT.md'))) score += 40;
+  if (existsSync(resolveDocRole(dir, config, 'environment'))) score += 40;
   else failures.push({ issue: 'ENVIRONMENT.md missing', fixCmd: 'docguard fix --doc environment' });
 
   // .env.example — only check if project needs env vars
@@ -978,8 +998,8 @@ function calcChangelogScore(dir, config) {
   return { score: Math.min(100, score), failures };
 }
 
-function calcArchitectureScore(dir) {
-  const archPath = resolve(dir, 'docs-canonical/ARCHITECTURE.md');
+function calcArchitectureScore(dir, config) {
+  const archPath = resolveDocRole(dir, config, 'architecture');
   if (!existsSync(archPath)) {
     return { score: 0, failures: [{ issue: 'ARCHITECTURE.md missing', fixCmd: 'docguard fix --doc architecture' }] };
   }

package/cli/commands/sync.mjs

@@ -1,3 +1,4 @@
+import { assertDefaultDocWrites } from '../shared-doc-roles.mjs';
 /**
  * Sync Command — keep the documentation memory ALWAYS UP TO DATE.
  *
@@ -78,6 +79,7 @@ function sectionTouchedByChanges(sectionId, changedFiles) {
 }
 
 export function runSync(projectDir, config, flags) {
+  if (flags.write) assertDefaultDocWrites(config);
   // v0.28 (field report #10): `--tests` reconciles the hand-maintained TEST-SPEC
   // Source-to-Test Map from disk (ghost-source removal + new co-located pairs) —
   // a distinct path from the generated code-truth section refresh below.

package/cli/commands/watch.mjs

@@ -7,21 +7,23 @@
  * --auto-fix: When guard finds issues, output AI fix prompts automatically.
  */
 
-import { watch as fsWatch, existsSync, readdirSync, statSync } from 'node:fs';
-import { resolve, relative, extname } from 'node:path';
+import { watch as fsWatch, readdirSync, lstatSync } from 'node:fs';
+import { resolve, extname } from 'node:path';
 import { c } from '../shared.mjs';
 import { runGuardInternal } from './guard.mjs';
+import { clearMemoryPlanCache } from '../scanners/memory-plan.mjs';
+import { buildIgnoreFilter, loadDocguardIgnore, DEFAULT_IGNORE_DIRS, relPosix } from '../shared-ignore.mjs';
 
 const DEBOUNCE_MS = 500;
-const IGNORE_DIRS = new Set([
-  'node_modules', '.git', '.next', 'dist', 'build', 'coverage',
-  '.cache', '__pycache__', '.venv', 'vendor', '.turbo',
-]);
 const WATCH_EXTS = new Set([
-  '.md', '.json', '.mjs', '.js', '.ts', '.tsx', '.jsx', '.py',
+  '.md', '.json', '.mjs', '.cjs', '.js', '.ts', '.tsx', '.jsx', '.mts', '.cts', '.py',
+  '.java', '.go', '.rs', '.rb', '.php', '.yaml', '.yml', '.toml',
 ]);
 
-export function runWatch(projectDir, config, flags) {
+export function runWatch(projectDir, config, flags = {}, runtime = {}) {
+  const watch = runtime.watch || fsWatch;
+  const guard = runtime.guard || runGuardInternal;
+  const clearCache = runtime.clearCache || clearMemoryPlanCache;
   console.log(`${c.bold}👁️  DocGuard Watch — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   Directory: ${projectDir}${c.reset}`);
   if (flags.autoFix) {
@@ -29,53 +31,104 @@ export function runWatch(projectDir, config, flags) {
   }
   console.log(`${c.dim}   Watching for changes... (Ctrl+C to stop)${c.reset}\n`);
 
-  // Run guard immediately on start
-  runGuardQuiet(projectDir, config, flags);
-
-  // Collect directories to watch
-  const watchDirs = collectWatchDirs(projectDir);
-  console.log(`${c.dim}   Watching ${watchDirs.length} directories${c.reset}\n`);
-
+  let ignored = buildIgnoreFilter([...(config.ignore || []), ...loadDocguardIgnore(projectDir)]);
+  const skip = path => path.split('/').some(part => part === '.local' || DEFAULT_IGNORE_DIRS.has(part)) || ignored(path);
+  const watchers = new Map();
   let debounceTimer = null;
-  let lastChange = '';
-
-  for (const dir of watchDirs) {
+  let running = false;
+  let pending = false;
+  let stopped = false;
+  const changes = new Set();
+
+  function stop() {
+    if (stopped) return;
+    stopped = true;
+    clearTimeout(debounceTimer);
+    for (const watcher of watchers.values()) watcher.close();
+    watchers.clear();
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+  function onSignal() {
+    stop();
+    console.log(`\n${c.dim}   Watch stopped.${c.reset}\n`);
+  }
+  function failed(err, dir) {
+    if (stopped) return;
+    console.error(`${c.red}   Watch failed for ${relPosix(projectDir, dir) || '.'}: ${err.code || err.message}. Watch stopped; resolve the error and restart.${c.reset}`);
+    process.exitCode = 1;
+    stop();
+  }
+  async function check() {
+    if (stopped) return;
+    if (running) { pending = true; return; }
+    running = true;
+    pending = false;
+    const changed = [...changes];
+    changes.clear();
+    if (changed.length) console.log(`\n${c.dim}   Changed: ${c.cyan}${changed.join(', ')}${c.reset}`);
     try {
-      fsWatch(dir, { persistent: true }, (eventType, filename) => {
-        if (!filename) return;
-        const ext = extname(filename);
-        if (!WATCH_EXTS.has(ext)) return;
-
-        const changePath = relative(projectDir, resolve(dir, filename));
-        if (changePath === lastChange) return; // skip duplicates
-        lastChange = changePath;
-
-        // Debounce — wait for rapid saves to settle
-        if (debounceTimer) clearTimeout(debounceTimer);
-        debounceTimer = setTimeout(() => {
-          console.log(`\n${c.dim}   Changed: ${c.cyan}${changePath}${c.reset}`);
-          runGuardQuiet(projectDir, config, flags);
-          lastChange = '';
-        }, DEBOUNCE_MS);
-      });
-    } catch {
-      // Some directories may not be watchable
+      clearCache();
+      await runGuardQuiet(projectDir, config, flags, guard);
+    } catch (err) {
+      console.error(`${c.red}   Guard failed: ${err.message}${c.reset}`);
+    } finally {
+      running = false;
+      // If saves are still arriving, let their debounce expire first.
+      if (pending && !debounceTimer && !stopped) void check();
     }
   }
-
-  // Keep process alive
-  process.on('SIGINT', () => {
-    console.log(`\n${c.dim}   Watch stopped.${c.reset}\n`);
-    process.exit(0);
-  });
+  function changed(dir, filename) {
+    if (stopped) return;
+    const name = filename == null ? null : String(filename);
+    const path = name == null ? relPosix(projectDir, dir) : relPosix(projectDir, resolve(dir, name));
+    if (skip(path) || path.startsWith('../')) return;
+    if (name && name.startsWith('.') && !['.docguard.json', '.docguardignore', '.env.example'].includes(name)) return;
+    // Rename events include directory creation/removal. Reconcile subscriptions
+    // after the burst settles so new subdirectories are watched too.
+    if (name && extname(name) && !WATCH_EXTS.has(extname(name).toLowerCase()) && name !== '.docguardignore' && name !== '.env.example') return;
+    changes.add(path || '(unknown path)');
+    clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      reconcile();
+      void check();
+    }, DEBOUNCE_MS);
+  }
+  function reconcile() {
+    if (stopped) return;
+    ignored = buildIgnoreFilter([...(config.ignore || []), ...loadDocguardIgnore(projectDir)]);
+    const dirs = collectWatchDirs(projectDir, skip, failed);
+    if (stopped) return;
+    const wanted = new Set(dirs);
+    for (const [dir, watcher] of watchers) {
+      if (!wanted.has(dir)) { watcher.close(); watchers.delete(dir); }
+    }
+    for (const dir of dirs) {
+      if (watchers.has(dir)) continue;
+      try {
+        const watcher = watch(dir, { persistent: true }, (_event, filename) => changed(dir, filename));
+        watchers.set(dir, watcher);
+        watcher.on('error', err => failed(err, dir));
+      } catch (err) { failed(err, dir); break; }
+    }
+  }
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  reconcile();
+  if (!stopped) {
+    void check();
+    console.log(`${c.dim}   Watching ${watchers.size} directories${c.reset}\n`);
+  }
+  return { close: stop };
 }
 
-function runGuardQuiet(projectDir, config, flags) {
+async function runGuardQuiet(projectDir, config, flags, guard) {
   const timestamp = new Date().toLocaleTimeString();
   console.log(`${c.dim}   [${timestamp}] Running guard...${c.reset}`);
 
   try {
-    const data = runGuardInternal(projectDir, config);
+    const data = await guard(projectDir, config);
 
     if (data.status === 'PASS') {
       console.log(`  ${c.green}✅ PASS${c.reset} — ${data.passed}/${data.total} checks passed`);
@@ -110,34 +163,24 @@ function runGuardQuiet(projectDir, config, flags) {
   }
 }
 
-function collectWatchDirs(rootDir) {
-  const dirs = [rootDir];
-
+function collectWatchDirs(rootDir, skip, onError) {
+  const dirs = [];
   function walk(dir) {
-    try {
-      const entries = readdirSync(dir);
-      for (const entry of entries) {
-        if (IGNORE_DIRS.has(entry)) continue;
-        if (entry.startsWith('.')) continue;
-
-        const fullPath = resolve(dir, entry);
-        try {
-          const stat = statSync(fullPath);
-          if (stat.isDirectory()) {
-            dirs.push(fullPath);
-            walk(fullPath);
-          }
-        } catch { /* skip unreadable */ }
+    dirs.push(dir);
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); }
+    catch (err) { onError(err, dir); return; }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = resolve(dir, entry.name);
+      if (skip(relPosix(rootDir, full)) || entry.isSymbolicLink()) continue;
+      try {
+        if (lstatSync(full).isDirectory()) walk(full);
+      } catch (err) {
+        if (err.code !== 'ENOENT') onError(err, full);
       }
-    } catch { /* skip unreadable */ }
-  }
-
-  // Always watch docs-canonical explicitly
-  const docsDir = resolve(rootDir, 'docs-canonical');
-  if (existsSync(docsDir) && !dirs.includes(docsDir)) {
-    dirs.push(docsDir);
+    }
   }
-
   walk(rootDir);
   return dirs;
 }

package/cli/config.mjs

@@ -1,3 +1,5 @@
+import { hasWorkerConfig } from './shared-source.mjs';
+import { applyDocRoles } from './shared-doc-roles.mjs';
 /**
  * DocGuard — configuration loading.
  *
@@ -78,9 +80,9 @@ export function loadConfig(projectDir) {
       environment: true,
       freshness: true,
       // v0.31.0 — all three default ON. Soft (confidence:low, never break CI),
-      // precise (zero false positives across the 6-repo corpus), and quiet when
+      // heuristic (field cases require ongoing precision checks), and quiet when
       // not applicable (no diff / no API-reference doc). api-doc-smells is
-      // low-yield but zero-FP, so on-by-default beats a self-counting split.
+      // Detection yield and false positives must be measured per supported syntax.
       diffSuspicion: true,
       referenceExistence: true,
       apiDocSmells: true,
@@ -139,7 +141,7 @@ export function loadConfig(projectDir) {
       // Merge .docguardignore patterns into config.ignore so every validator
       // honors them without having to know about the file.
       mergeIgnoreFile(projectDir, merged);
-      return merged;
+      return applyDocRoles(projectDir, merged);
     } catch (e) {
       console.error(`${c.red}Error parsing .docguard.json: ${e.message}${c.reset}`);
       process.exit(1);
@@ -162,6 +164,7 @@ export function loadConfig(projectDir) {
  * Returns: 'cli' | 'library' | 'webapp' | 'api' | 'unknown'
  */
 function autoDetectProjectType(dir) {
+  if (hasWorkerConfig(dir)) return 'api';
   const pkgPath = resolve(dir, 'package.json');
   if (existsSync(pkgPath)) {
     try {

package/cli/docguard.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { assertDefaultDocWrites } from './shared-doc-roles.mjs';
 
 /**
  * DocGuard CLI — The enforcement tool for Canonical-Driven Development (CDD)
@@ -292,10 +293,10 @@ const COMMAND_HELP = {
     examples: ['docguard memory', 'docguard memory --diff'],
   },
   feedback: {
-    summary: 'Report likely false positives back to DocGuard. Collects the low-confidence findings of a guard run, saves a full local record under .docguard/feedback/, and prints a one-click, prefilled, redacted GitHub issue URL (zero typing, no source code or secret values).',
-    usage: 'docguard feedback [--format json]',
-    flags: [['--format json', 'Machine-readable list of reportable findings + URLs']],
-    examples: ['docguard feedback'],
+    summary: 'Review detection feedback locally. Select any finding with --code or --all, check duplicates, and prepare a metadata-only issue URL. Nothing is submitted automatically.',
+    usage: 'docguard feedback [--code <CODE> | --all] [--preview] [--format json]',
+    flags: [['--code <CODE>', 'Select a finding regardless of confidence'], ['--all', 'Select every active finding'], ['--preview', 'Skip local feedback-record writes'], ['--format json', 'Machine-readable selected findings and issue/search URLs']],
+    examples: ['docguard feedback', 'docguard feedback --code TRC005 --preview', 'docguard feedback --all --format json'],
   },
   verify: {
     summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
@@ -537,6 +538,12 @@ async function main() {
       // mcp --transport http: HTTP mount path (default /mcp).
       flags.path = args[i + 1];
       i++;
+    } else if (args[i] === '--code') {
+      flags.code = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : '';
+    } else if (args[i] === '--all') {
+      flags.all = true;
+    } else if (args[i] === '--preview') {
+      flags.preview = true;
     } else if (args[i] === '--signals') {
       flags.signals = true;
     } else if (args[i] === '--debate') {
@@ -597,6 +604,7 @@ async function main() {
   if (!headless) printBanner();
 
   const config = loadConfig(projectDir);
+  if (['init', 'setup', 'generate'].includes(command) && !(command === 'generate' && flags.plan && !flags.write) || ['sync', 'fix'].includes(command) && flags.write || command === 'diagnose' && flags.auto) assertDefaultDocWrites(config);
 
   // `--no-baseline` disables the committed adoption baseline for this run —
   // threaded through config so guard, ci, report, and mcp all honor it the

package/cli/findings.mjs

@@ -140,32 +140,32 @@ export const CODES = {
   },
   FRS001: {
     validator: 'freshness',
-    title: 'Doc has no freshness signal',
-    help: 'The doc exists but is not committed to git and carries no review marker, so its currency cannot be assessed. Commit it, or stamp it with `<!-- docguard:last-reviewed YYYY-MM-DD -->` (or `<!-- docguard:status approved -->` for a doc generated this session).',
-    suppress: '<!-- docguard:status approved -->',
+    title: 'Document review signal unavailable',
+    help: 'No committed update or dated review signal was found. Review the document’s intended behavior and implementation before recording a review date. An approved status is an author signal, not semantic verification.',
+    suppress: null,
   },
   FRS002: {
     validator: 'freshness',
-    title: 'Code moved on since the doc was last updated',
-    help: '10+ code commits landed after the doc\'s last update/review — its code-truth sections are likely stale. Run `docguard sync --write` to refresh them in one pass, or review and stamp `<!-- docguard:last-reviewed YYYY-MM-DD -->` if it is still accurate.',
+    title: 'Document review due after repository activity',
+    help: 'At least 10 code commits followed the document update or review. This repository-wide heuristic does not prove the document is stale. Review its purpose, intended behavior and relevant code before deciding which side needs a change.',
     suppress: null,
   },
   FRS003: {
     validator: 'freshness',
-    title: 'Doc predates the latest code change by 30+ days',
-    help: 'The doc\'s last update is more than 30 days older than the newest code commit. Review it against the current code, then update it or stamp it reviewed.',
+    title: 'Document review due after elapsed repository history',
+    help: 'The document update or review predates the latest code change by more than 30 days. This repository-wide heuristic does not establish drift. Review relevance and intent before changing documentation or code.',
     suppress: null,
   },
   FRS004: {
     validator: 'freshness',
-    title: 'CHANGELOG lagging behind code changes',
-    help: 'Code changed but CHANGELOG.md has not been updated in over a week. Add the missing entries under [Unreleased].',
+    title: 'Release-note review due',
+    help: 'The changelog update predates the latest code change by more than a week. Review whether these changes need release notes; timing alone does not prove entries are missing.',
     suppress: null,
   },
   FRS005: {
     validator: 'freshness',
-    title: 'DRIFT-LOG possibly stale',
-    help: 'Recent commits added `DRIFT:` comments but DRIFT-LOG.md has not kept pace. Log the new deviations (each DRIFT comment needs a DRIFT-LOG entry) or remove resolved markers.',
+    title: 'Deviation-log review due',
+    help: 'Recent code commits added DRIFT comment lines. Review whether the deviations are already recorded or resolved; history alone does not prove the log is incomplete.',
     suppress: null,
   },
   DSY001: {
@@ -350,8 +350,8 @@ export const CODES = {
   },
   TRC004: {
     validator: 'traceability',
-    title: 'Requirement ID without test coverage',
-    help: 'A requirement ID found in the docs (REQ-/FR-/SC-/T-style) has no matching reference in any test file. Add an `@req <ID>` comment to the test that verifies it. Requirement traceability is opt-in: it only activates once IDs appear in your docs.',
+    title: 'Requirement ID without a recognized test annotation or label',
+    help: 'A documented requirement has no recognized annotation or test label in the scanned tests. This is a traceability gap, not proof of missing behavioral coverage. Review existing tests and add an `@req <ID>` annotation or ID test label only where the requirement is verified. Write a test only if coverage is actually missing.',
     suppress: null,
   },
   TRC005: {