docguard-cli 0.40.4 → 0.41.0

package/cli/shared.mjs

@@ -2,6 +2,8 @@
  * Shared constants for DocGuard CLI — colors, profiles, version.
  * Extracted from docguard.mjs to break circular dependencies.
  * All commands import from here instead of docguard.mjs.
+ * @implements docguard.adoption-workflow-integrity#FR-007
+ * @implements docguard.adoption-workflow-integrity#FR-008
  */
 
 /**
@@ -13,7 +15,7 @@
  * `.docguard.json.version` is BEHIND this constant — pointing users at
  * `docguard upgrade` to migrate.
  */
-export const CURRENT_SCHEMA_VERSION = '0.5';
+export const CURRENT_SCHEMA_VERSION = '0.6';
 
 /**
  * Allowed severity values for per-validator `severity` overrides in
@@ -39,6 +41,33 @@ export function resolveSeverity(config, validatorKey) {
   return 'medium';
 }
 
+/**
+ * Resolve the enforcement level for one structured finding. Exact finding-code
+ * policy wins over validator policy. Without an exact override, intrinsic
+ * errors remain blocking and validator severity only reweights warnings.
+ */
+export function resolveFindingEnforcement(config, finding, validatorKey) {
+  const code = typeof finding?.code === 'string' ? finding.code.toUpperCase() : null;
+  const exact = code && config?.findingSeverity?.[code];
+  const normalizedExact = typeof exact === 'string' ? exact.toLowerCase() : null;
+  if (normalizedExact && SEVERITY_LEVELS.has(normalizedExact)) {
+    return {
+      level: normalizedExact === 'high' ? 'error' : normalizedExact === 'medium' ? 'warn' : 'info',
+      source: 'finding',
+      key: code,
+    };
+  }
+  if (finding?.severity === 'error') {
+    return { level: 'error', source: 'intrinsic', key: code };
+  }
+  const validatorSeverity = resolveSeverity(config, validatorKey);
+  return {
+    level: validatorSeverity === 'high' ? 'error' : validatorSeverity === 'low' ? 'info' : 'warn',
+    source: 'validator',
+    key: validatorKey,
+  };
+}
+
 // ── Canonical section heading matching ─────────────────────────────────────
 /**
  * Required canonical sections used to be matched by literal substring, so an

package/cli/validators/api-doc-smells.mjs

@@ -122,7 +122,7 @@ export function validateApiDocSmells(projectDir, config = {}) {
           confidence: 'low',
           message: `${f}: "${u.heading.slice(0, 60)}" is documented in name only (${prose} words of explanation) — Lazy API doc.`,
           location: { file: f, line: u.line },
-          suggestion: { summary: `Describe what "${u.heading.slice(0, 40)}" does, its params, return, and errors — not just its signature.` },
+          suggestion: { kind: 'review', text: `Describe what "${u.heading.slice(0, 40)}" does, its params, return, and errors — not just its signature.` },
         }));
       } else if (total >= bloatedMin) {
         findings.push(mkFinding({
@@ -132,7 +132,7 @@ export function validateApiDocSmells(projectDir, config = {}) {
           confidence: 'low',
           message: `${f}: "${u.heading.slice(0, 60)}" is ${total} words for one unit — Bloated API doc; trim to the essential contract.`,
           location: { file: f, line: u.line },
-          suggestion: { summary: `Split or trim "${u.heading.slice(0, 40)}" — move examples/edge-cases elsewhere and keep the core contract.` },
+          suggestion: { kind: 'review', text: `Split or trim "${u.heading.slice(0, 40)}" — move examples/edge-cases elsewhere and keep the core contract.` },
         }));
       }
     }

package/cli/validators/api-surface.mjs

@@ -405,9 +405,7 @@ export function validateApiSurface(projectDir, config) {
           confidence: 'high', // certain contract omission, NOT certain code absence
           message: `Documented endpoint missing from OpenAPI contract (${source}): ${e.method} ${e.path} (${API_DOC}). ${codeDescription}`,
           location: API_DOC,
-          suggestion: e.codeEvidence.status === 'not-found'
-            ? { kind: 'fix', text: 'Remove the endpoint omitted from the contract and not found by the code scan; verify scanner coverage before applying', command: 'docguard fix --write' }
-            : { kind: 'review', text: e.codeEvidence.status === 'present'
+          suggestion: { kind: 'review', text: e.codeEvidence.status === 'present'
             ? 'Reconcile the implementation with the intended contract; update OpenAPI if the route is intended. Preserve the documented endpoint during review.'
             : 'Reconcile the contract and documentation with the intended API. Verify implementation coverage and whether the endpoint was removed before editing documentation.' },
         }),
@@ -424,12 +422,9 @@ export function validateApiSurface(projectDir, config) {
     }
   }
 
-  // Only the contract-and-code corroborated subset reaches mechanical writes.
-  if (confidence === 'spec') {
-    for (const e of documentedButAbsent) {
-      fixes.push({ type: 'remove-endpoint', method: e.method, path: e.path, doc: API_DOC });
-    }
-  }
+  // A route scanner can prove presence, but unsupported syntax means it cannot
+  // prove absence. Contract omissions therefore remain review-only and never
+  // become mechanical deletion candidates, even when no route was extracted.
 
   // Without a spec, a negative scan remains a low-confidence review candidate.
   if (confidence !== 'spec' && documentedButAbsent.length) {

package/cli/validators/diff-suspicion.mjs

@@ -185,7 +185,8 @@ export function validateDiffSuspicion(projectDir, config = {}) {
         message: `${docName} describes ${h.path} (${h.kind} ref), and overlaps old-side diff tokens: ${h.shared.slice(0, 5).join(', ')}${h.shared.length > 5 ? '…' : ''} or removed declaration names (${ref}..HEAD) — possible drift; review whether the documentation is affected.`,
         location: { file: docName },
         suggestion: {
-          summary: `Re-read ${docName} against the current ${h.path}; the old-side tokens (${h.shared.slice(0, 8).join(', ')}) do not establish a semantic contradiction.`,
+          kind: 'review',
+          text: `Re-read ${docName} against the current ${h.path}; the old-side tokens (${h.shared.slice(0, 8).join(', ')}) do not establish a semantic contradiction.`,
         },
       }));
     }
@@ -197,7 +198,7 @@ export function validateDiffSuspicion(projectDir, config = {}) {
         confidence: 'low',
         message: `${docName} references ${hits.length - maxPerDoc} more changed file(s) with old-side token overlap (${ref}..HEAD) — a broad change; review ${docName} as a whole.`,
         location: { file: docName },
-        suggestion: { summary: `${docName} looks broadly affected by this change set — review it end-to-end rather than line by line.` },
+        suggestion: { kind: 'review', text: `${docName} looks broadly affected by this change set — review it end-to-end rather than line by line.` },
       }));
     }
   }

package/cli/validators/docs-sync.mjs

@@ -12,6 +12,7 @@ import { resolve, join, extname, basename } from 'node:path';
 import { resolveSourceRoots } from '../shared-source.mjs';
 import { relPosix, walkFiles as sharedWalkFiles, listCanonicalDocs } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
+import { findAllOpenApiSpecs } from './api-surface.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
@@ -46,6 +47,38 @@ function isValidRouteFile(relPath) {
   return true;
 }
 
+/**
+ * `src/lib` is a generic utility convention in frontend and full-stack repos,
+ * not evidence that every file beneath it is an architectural service. Keep
+ * explicit service directories exhaustive; require a service-shaped filename
+ * for the ambiguous `src/lib` fallback.
+ */
+function isServiceCandidate(file, serviceDir) {
+  const normalizedDir = serviceDir.replace(/\\/g, '/').replace(/\/$/, '');
+  if (!normalizedDir.endsWith('/src/lib')) return true;
+
+  const name = basename(file, extname(file));
+  return /(?:^|[-_.])services?$/i.test(name) || /Service$/i.test(name);
+}
+
+function normalizeApiPath(path) {
+  const normalized = String(path || '')
+    .trim()
+    .toLowerCase()
+    .replace(/:[a-z_][a-z0-9_]*/gi, '{}')
+    .replace(/\{[^/{}]+\}/g, '{}')
+    .replace(/\/+$/g, '');
+  return normalized || '/';
+}
+
+function routeMatchesOpenApi(routePath, specPaths) {
+  const route = normalizeApiPath(routePath);
+  return specPaths.some(specPath => {
+    const spec = normalizeApiPath(specPath);
+    return spec === route || (route !== '/' && spec.endsWith(route));
+  });
+}
+
 /**
  * Expand sub-path patterns (e.g. 'routes', 'src/routes') against the project
  * root AND every configured source root, returning de-duplicated existing dirs.
@@ -146,6 +179,7 @@ export function validateDocsSync(projectDir, config) {
 
       const relPath = relPosix(projectDir, file);
       if (isTestFile(relPath)) continue;
+      if (!isServiceCandidate(file, serviceDir)) continue;
       // N-1: skip files outside the --changed-only scope.
       if (!inScope(relPath)) continue;
 
@@ -169,27 +203,11 @@ export function validateDocsSync(projectDir, config) {
 
   // ── Cross-check route files against OpenAPI spec ──
   // If an OpenAPI spec exists AND route files exist, verify routes have matching paths
-  const openapiPatterns = [
-    'openapi.yaml', 'openapi.yml', 'openapi.json',
-    'swagger.yaml', 'swagger.yml', 'swagger.json',
-    'api/openapi.yaml', 'api/openapi.yml', 'api/openapi.json',
-    'docs/openapi.yaml', 'docs/openapi.yml',
-  ];
-
-  let openapiContent = '';
-  let openapiFile = null;
-  for (const pattern of openapiPatterns) {
-    const specPath = resolve(projectDir, pattern);
-    if (existsSync(specPath)) {
-      try {
-        openapiContent = readFileSync(specPath, 'utf-8').toLowerCase();
-        openapiFile = pattern;
-      } catch { /* ignore */ }
-      break;
-    }
-  }
+  const authoritativeSpec = findAllOpenApiSpecs(projectDir, config)[0] || null;
+  const openapiPaths = authoritativeSpec?.endpoints.map(endpoint => endpoint.path) || [];
+  const openapiFile = authoritativeSpec?.relPath || null;
 
-  if (openapiContent && openapiFile) {
+  if (openapiPaths.length > 0 && openapiFile) {
     // Check that route files have corresponding paths in OpenAPI spec (monorepo-aware)
     for (const routeDir of expandDirs(projectDir, config, ['src/routes', 'src/app/api', 'routes', 'app/api'])) {
       const files = getFilesRecursive(routeDir);
@@ -222,12 +240,11 @@ export function validateDocsSync(projectDir, config) {
         let matched = false;
 
         if (actualRoutes.length > 0) {
-          // Check if ANY of the actual route paths appear in the OpenAPI spec
-          matched = actualRoutes.some(route => {
-            // Normalize: /api/conversations/:id → /api/conversations
-            const basePath = route.replace(/\/:[^/]+/g, '').replace(/\/{[^}]+}/g, '');
-            return openapiContent.includes(basePath) || openapiContent.includes(route);
-          });
+          // Express :param and OpenAPI {param} are equivalent. Compare whole
+          // path segments so `/users` cannot accidentally match `/superusers`.
+          // A route-local path may omit an application mount prefix, so an
+          // exact segment suffix is also accepted.
+          matched = actualRoutes.some(route => routeMatchesOpenApi(route, openapiPaths));
         } else {
           // Strategy 2 (fallback): Strip common suffixes and check filename
           // userRoutes.ts → 'user', conversationRoutes.ts → 'conversation'
@@ -238,9 +255,8 @@ export function validateDocsSync(projectDir, config) {
             .replace(/router$/i, '');
 
           if (cleanName.length > 0) {
-            matched = openapiContent.includes(`/${cleanName}`) ||
-                      openapiContent.includes(`"${cleanName}"`) ||
-                      openapiContent.includes(`'${cleanName}'`);
+            matched = openapiPaths.some(path =>
+              normalizeApiPath(path).split('/').some(segment => segment === cleanName));
           }
         }
 

package/cli/validators/environment.mjs

@@ -14,11 +14,71 @@ import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
  * existing tests are unaffected; guard just renders richer output.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
-import { grepEnvUsage } from '../shared-source.mjs';
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { grepEnvUsage, resolveSourceRoots } from '../shared-source.mjs';
+import { shouldIgnore } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 
+const ENV_TEMPLATE_NAMES = ['.env.example', '.env.template'];
+
+function isWithin(projectRoot, path) {
+  const rel = relative(projectRoot, path);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+/**
+ * Discover repository-owned env templates at the root and package boundaries.
+ * Source roots may point inside a package (for example `backend/src`), so every
+ * ancestor up to the repository root is considered. `resolveSourceRoots()` also
+ * contributes declared npm/pnpm workspace packages. Candidates are de-duplicated
+ * before reading and rejected when ignored, outside the repository, or reached
+ * through a symlink.
+ */
+function discoverEnvTemplates(projectDir, config) {
+  const projectRoot = resolve(projectDir);
+  const candidateDirs = new Set([projectRoot]);
+
+  for (const sourceRoot of resolveSourceRoots(projectRoot, config)) {
+    let current = resolve(sourceRoot);
+    while (isWithin(projectRoot, current)) {
+      candidateDirs.add(current);
+      if (current === projectRoot) break;
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+
+  const templates = new Set();
+  for (const dir of candidateDirs) {
+    for (const name of ENV_TEMPLATE_NAMES) {
+      const abs = resolve(dir, name);
+      const rel = relative(projectRoot, abs);
+      if (!rel || !isWithin(projectRoot, abs)) continue;
+      const relPosix = rel.split(sep).join('/');
+      if (shouldIgnore(relPosix, config)) continue;
+
+      let current = projectRoot;
+      let safe = true;
+      for (const segment of rel.split(sep)) {
+        current = resolve(current, segment);
+        try {
+          const stat = lstatSync(current);
+          if (stat.isSymbolicLink()) { safe = false; break; }
+          if (current === abs && !stat.isFile()) { safe = false; break; }
+        } catch {
+          safe = false;
+          break;
+        }
+      }
+      if (safe) templates.add(abs);
+    }
+  }
+
+  return [...templates].sort();
+}
+
 export function validateEnvironment(projectDir, config) {
   const findings = [];
   let passed = 0;
@@ -109,9 +169,7 @@ export function validateEnvironment(projectDir, config) {
       if (SYSTEM.has(m[1])) continue;
       documented.add(m[1]);
     }
-    for (const envFile of ['.env.example', '.env.template']) {
-      const p = resolve(projectDir, envFile);
-      if (!existsSync(p)) continue;
+    for (const p of discoverEnvTemplates(projectDir, config)) {
       const re = /^([A-Z][A-Z0-9_]*[A-Z0-9])\s*=/gm;
       const ex = readFileSync(p, 'utf-8');
       let em;

package/cli/validators/metrics-consistency.mjs

@@ -131,7 +131,7 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
       // then emit ONE warning per distinct value. A file that says "20" on
       // line 5 and "20" on line 50 is the same drift; "20" on line 5 and
       // "19" on line 50 are two distinct drifts.
-      const distinctFoundInFile = new Set();
+      const occurrencesByValue = new Map();
       while ((match = regex.exec(content)) !== null) {
         // Bug #2 (subject-binding): for the built-in meta-counts, only validate a
         // number BOUND to DocGuard. An unbound "N checks" (a proof harness, a CI
@@ -140,11 +140,17 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
         // correct number. Project-declared collections (requireBind:false) skip
         // this: naming the noun in `config.collections` IS the explicit binding.
         if (requireBind && !isDocguardBound(content, match.index)) continue;
-        distinctFoundInFile.add(parseInt(match[1], 10));
+        const found = parseInt(match[1], 10);
+        const occurrences = occurrencesByValue.get(found) || { current: 0, historical: 0 };
+        occurrences[isHistoricalMetricContext(content, match.index) ? 'historical' : 'current']++;
+        occurrencesByValue.set(found, occurrences);
       }
-      if (distinctFoundInFile.size === 0) continue;
+      if (occurrencesByValue.size === 0) continue;
 
-      for (const found of distinctFoundInFile) {
+      for (const [found, occurrences] of occurrencesByValue) {
+        // Historical transitions are evidence about an earlier release, not an
+        // assertion of the current count. Rewriting them would falsify history.
+        if (occurrences.current === 0) continue;
         if (found > 0 && found !== actuals[key]) {
           const driftKey = `${relPath}|${label}|${found}`;
           if (reportedDrift.has(driftKey)) continue;
@@ -153,24 +159,33 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
           const phrase = isCollection
             ? `the code has ${actuals[key]} (${glob})`
             : `${subject} ${label} count is ${actuals[key]}`;
+          const safeToRewrite = occurrences.historical === 0;
           findings.push(mkFinding({
             code: isCollection ? 'MET002' : 'MET001',
             validator: 'metricsConsistency',
             severity: 'warn',
-            message: `${relPath} says "${found} ${label}" but ${phrase}. Fix with \`docguard fix --write\``,
+            confidence: safeToRewrite ? 'high' : 'low',
+            reportable: !safeToRewrite,
+            message: `${relPath} says "${found} ${label}" but ${phrase}. ${safeToRewrite
+              ? 'Fix with `docguard fix --write`'
+              : 'Review manually because the same count also appears in historical context'}`,
             location: relPath,
             suggestion: {
-              kind: 'fix',
-              text: isCollection
-                ? `Confirm which side is right, then rewrite the stale count (${found} → ${actuals[key]})`
-                : `Rewrite the stale docguard-bound count (${found} → ${actuals[key]})`,
-              command: 'docguard fix --write',
+              kind: safeToRewrite ? 'fix' : 'review',
+              text: safeToRewrite
+                ? (isCollection
+                  ? `Confirm which side is right, then rewrite the stale count (${found} → ${actuals[key]})`
+                  : `Rewrite the stale docguard-bound count (${found} → ${actuals[key]})`)
+                : `Review the current assertion without changing historical ${found} ${label} statements`,
+              ...(safeToRewrite ? { command: 'docguard fix --write' } : {}),
             },
           }));
           // actualSource records WHAT the actual count describes, so the applier
           // (and a human) can confirm both sides are the same subject before any
           // overwrite. Without it the fix is refused (fail-closed). See Bug #2.
-          fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key], actualSource });
+          if (safeToRewrite) {
+            fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key], actualSource });
+          }
         } else {
           // Matches the actual count — one pass per (file, label), not per occurrence.
           const passKey = `${relPath}|${label}`;
@@ -204,6 +219,32 @@ function isDocguardBound(content, index) {
   return /docguard/i.test(content.slice(lineStart, lineEnd));
 }
 
+/**
+ * Return true when a metric occurrence describes history rather than current
+ * state. The classifier deliberately recognizes only explicit historical
+ * evidence: transition arrows/from-to wording, historical metadata, and
+ * release-history headings. Ambiguous prose remains visible, but a count that
+ * appears in both contexts is never handed to the mechanical replace-all fix.
+ */
+function isHistoricalMetricContext(content, index) {
+  const lineStart = content.lastIndexOf('\n', index) + 1;
+  let lineEnd = content.indexOf('\n', index);
+  if (lineEnd === -1) lineEnd = content.length;
+  const line = content.slice(lineStart, lineEnd);
+
+  if (/\d[\d,]*\s*(?:→|->|=>)\s*\d[\d,]*/.test(line)) return true;
+  if (/\b(?:increased|grew|rose|decreased|dropped|fell|expanded|reduced|changed|moved|went|bumped|upgraded)\s+from\s+\d[\d,]*\s+to\s+\d[\d,]*/i.test(line)) return true;
+  if (/\b(?:previously|formerly|historically|back then|at launch|in (?:release|version|v)\s*\d|during (?:the )?(?:release|upgrade|migration))\b/i.test(line)) return true;
+
+  const before = content.slice(0, lineStart);
+  const headings = [...before.matchAll(/^#{1,6}\s+(.+)$/gm)];
+  const heading = headings.at(-1)?.[1] || '';
+  if (/\b(?:change\s*log|release (?:notes|history)|version history|migration history|what changed)\b/i.test(heading)) return true;
+
+  const prefix = content.slice(0, Math.min(content.length, 4096));
+  return /<!--\s*docguard:status\s+(?:historical|superseded|deprecated|archived)\s*-->/i.test(prefix);
+}
+
 function findTestFiles(dir) {
   const tests = [];
   const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];

package/cli/validators/reference-existence.mjs

@@ -252,7 +252,8 @@ export function validateReferenceExistence(projectDir, config = {}) {
         message: `${doc.name} references \`${sym}\`, which existed in the code when the doc was last updated but has ZERO matches at HEAD — likely renamed or removed.`,
         location: { file: doc.name },
         suggestion: {
-          summary: `Update or remove the \`${sym}\` reference in ${doc.name} (or suppress if it is a still-relevant user-facing name).`,
+          kind: 'review',
+          text: `Update or remove the \`${sym}\` reference in ${doc.name} (or suppress if it is a still-relevant user-facing name).`,
         },
       }));
     }
@@ -287,7 +288,8 @@ export function validateReferenceExistence(projectDir, config = {}) {
         message,
         location: { file: first.file, line: first.line },
         suggestion: {
-          summary: known.size > 0
+          kind: 'review',
+          text: known.size > 0
             ? `Fix the number or write the missing ADR entry (or suppress with // docguard:ignore REF002 on the citation line).`
             : `Create an ADR doc (docguard init writes templates/ADR.md) or suppress with // docguard:ignore REF002.`,
         },

package/cli/validators/security.mjs

@@ -98,16 +98,21 @@ function quotedValue(matchStr) {
  * are insufficient. Provider key signatures remain independently scanned.
  * Unknown syntax/parser failure supplies no exemptions.
  */
-function fixturePasswordRanges(content, filename) {
+function fixturePasswordEvidence(content, filename) {
   if (!/(?:^|\/)__tests?__\/|\.(?:test|spec)\.[cm]?[jt]sx?$/.test(filename)) return [];
   const { ast, ok } = parseJsTs(content, filename);
   if (!ok || ast.errors?.length) return [];
-  const ranges = [];
+  const evidence = [];
+  const literalCounts = new Map();
+  walk(ast, node => {
+    if (node.type !== 'StringLiteral') return;
+    literalCounts.set(node.value, (literalCounts.get(node.value) || 0) + 1);
+  });
   walk(ast, node => {
     if (node.type !== 'CallExpression') return;
     const callee = node.callee;
     if (callee.type !== 'MemberExpression' || callee.computed ||
-        !/^(?:toHaveBeenCalledWith|toHaveBeenLastCalledWith|toHaveBeenNthCalledWith)$/.test(callee.property.name)) return;
+        !/^(?:toHaveBeenCalledWith|toHaveBeenLastCalledWith|toHaveBeenNthCalledWith|toMatchObject|toEqual|toStrictEqual)$/.test(callee.property.name)) return;
     const expectation = callee.object;
     if (expectation.type !== 'CallExpression' || expectation.callee.type !== 'Identifier' ||
         expectation.callee.name !== 'expect') return;
@@ -119,13 +124,17 @@ function fixturePasswordRanges(content, filename) {
         if (prop.type !== 'ObjectProperty' || prop.computed ||
             !/^(?:password|passwd|pwd)$/i.test(prop.key.name || prop.key.value || '') ||
             prop.value.type !== 'StringLiteral') continue;
-        if (/^(?:test|mock|dummy|fixture)[_-]?(?:password|passwd|pwd)[0-9!@#$%_*.-]*$/i.test(prop.value.value)) {
-          ranges.push([prop.start, prop.end]);
-        }
+        const explicitSynthetic = /^(?:test|mock|dummy|fixture)[_-]?(?:password|passwd|pwd)[0-9!@#$%_*.-]*$/i.test(prop.value.value);
+        const repeatedFixtureValue = (literalCounts.get(prop.value.value) || 0) > 1;
+        if (explicitSynthetic || repeatedFixtureValue) evidence.push({
+          start: prop.start,
+          end: prop.end,
+          classification: explicitSynthetic ? 'safe' : 'probable',
+        });
       }
     }
   });
-  return ranges;
+  return evidence;
 }
 
 export function validateSecurity(projectDir, config) {
@@ -153,7 +162,7 @@ export function validateSecurity(projectDir, config) {
     scanned++;
     const content = readFileSync(filePath, 'utf-8');
     let lines = null;
-    let fixtureRanges = null;
+    let passwordFixtureEvidence = null;
 
     for (const { pattern, label } of SECRET_PATTERNS) {
       pattern.lastIndex = 0;
@@ -176,10 +185,27 @@ export function validateSecurity(projectDir, config) {
         if (isSafePlaceholder(matchLine, match[0], label)) continue;
 
         const code = LABEL_TO_CODE[label];
+        const location = `${relPath}:${lineNo}`;
         if (code === 'SEC001') {
-          fixtureRanges ??= fixturePasswordRanges(content, relPath);
-          if (fixtureRanges.some(([start, end]) => match.index >= start &&
-              match.index + match[0].length <= end)) continue;
+          passwordFixtureEvidence ??= fixturePasswordEvidence(content, relPath);
+          const fixture = passwordFixtureEvidence.find(({ start, end }) => match.index >= start &&
+              match.index + match[0].length <= end);
+          if (fixture?.classification === 'safe') continue;
+          if (fixture?.classification === 'probable') {
+            findings.push(mkFinding({
+              code, validator: 'security', severity: 'warn', confidence: 'low',
+              message: `${location}: possible ${label}, but the same redacted value is used as test input and expected output`,
+              location,
+              suggestion: {
+                kind: 'review',
+                text: 'Confirm this repeated test value is synthetic. Use a clearly named fixture password or suppress this line with a reason.',
+                pragma: `// docguard:ignore ${code} — repeated synthetic test fixture`,
+              },
+              reportable: true,
+              redactedContext: `${label} pattern fired inside a test assertion and the same literal appears elsewhere in the test. Literal omitted.`,
+            }));
+            continue;
+          }
         }
 
         // v0.27 (#8): honour an inline `// docguard:ignore SEC00x` pragma on the
@@ -187,7 +213,6 @@ export function validateSecurity(projectDir, config) {
         // whole file via `securityIgnore`.
         if (code && lineSuppresses(code, matchLine, prevLine)) continue;
 
-        const location = `${relPath}:${lineNo}`;
         const value = quotedValue(match[0]);
         const isProse = looksLikeProse(value);
 

package/cli/validators/spec-registry.mjs

@@ -13,13 +13,16 @@ export function validateSpecRegistry(projectDir, config = {}) {
     confidence: 'high',
     message: issue.message,
     location: issue.path,
-    suggestion: {
-      kind: 'review',
-      text: issue.code === 'SPR002'
-        ? 'Assign a unique immutable Spec ID in the authoritative spec metadata.'
-        : 'Resolve the lifecycle or registry integrity conflict, then refresh the registry.',
-      command: 'docguard specs --write',
-    },
+    suggestion: issue.code === 'SPR002'
+      ? {
+          kind: 'review',
+          text: 'Add a unique immutable Spec ID to the authoritative spec using the `**Spec ID**: <unique-id>` or `<!-- docguard:spec-id <unique-id> -->` form; then run `docguard specs --write`.',
+        }
+      : {
+          kind: 'review',
+          text: 'Resolve the lifecycle or registry integrity conflict, then refresh the registry.',
+          command: 'docguard specs --write',
+        },
   }));
   if (!projection.current && projection.issues.length === 0) {
     findings.push(mkFinding({

package/cli/validators/todo-tracking.mjs

@@ -74,21 +74,38 @@ const SKIP_PATTERNS = [
   /\bit\.todo\s*\(/,
 ];
 
-// Reasons must contain text and belong to this call, not a neighboring test.
-const SKIP_REASON_PATTERN = /(?:REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:\s*\S/i;
+function hasReasonText(value) {
+  return /(?:REASON|SKIP|TODO|FIXME|NOTE|WHY)\s*:[\s\S]*\S/i.test(value);
+}
 
 function hasAdjacentReason(content, call, comments) {
-  return comments.some(comment => {
-    if (!SKIP_REASON_PATTERN.test(comment.value)) return false;
+  const ordered = [...comments].sort((a, b) => a.start - b.start);
+  return ordered.some((comment, index) => {
     if (comment.end <= call.start) {
       // A trailing comment belongs to the preceding statement.
       const lineStart = content.lastIndexOf('\n', comment.start - 1) + 1;
       if (!/^\s*$/.test(content.slice(lineStart, comment.start))) return false;
       const gap = content.slice(comment.end, call.start);
-      return call.loc.start.line - comment.loc.end.line <= 3 && /^\s*$/.test(gap);
+      if (call.loc.start.line - comment.loc.end.line !== 1 || !/^\s*$/.test(gap)) return false;
+
+      // Babel represents adjacent // lines as separate comments. Walk backward
+      // across only contiguous, full-line comments so `// REASON:` can introduce
+      // a multiline explanation without borrowing a disconnected annotation.
+      let first = index;
+      while (first > 0) {
+        const previous = ordered[first - 1];
+        const current = ordered[first];
+        if (previous.type !== 'CommentLine' || current.type !== 'CommentLine') break;
+        if (current.loc.start.line - previous.loc.end.line !== 1) break;
+        const previousLineStart = content.lastIndexOf('\n', previous.start - 1) + 1;
+        if (!/^\s*$/.test(content.slice(previousLineStart, previous.start))) break;
+        if (!/^\s*$/.test(content.slice(previous.end, current.start))) break;
+        first--;
+      }
+      return hasReasonText(ordered.slice(first, index + 1).map(item => item.value).join('\n'));
     }
     if (comment.start >= call.end && comment.loc.start.line === call.loc.end.line) {
-      return /^[\s;]*$/.test(content.slice(call.end, comment.start));
+      return hasReasonText(comment.value) && /^[\s;]*$/.test(content.slice(call.end, comment.start));
     }
     return false;
   });
@@ -123,10 +140,13 @@ function fallbackSkippedCalls(content) {
   const calls = [];
   for (let i = 0; i < codeLines.length; i++) {
     if (!SKIP_PATTERNS.some(p => p.test(codeLines[i]))) continue;
-    // Only a directly preceding comment is unambiguous without a parser.
-    const previous = lines[i - 1] || '';
-    calls.push({ line: i + 1, hasReason: /^\s*\/\//.test(previous) &&
-      SKIP_REASON_PATTERN.test(previous) });
+    // Only a contiguous block of directly preceding line comments is
+    // unambiguous without a parser. Blank lines and code sever ownership.
+    const commentBlock = [];
+    for (let cursor = i - 1; cursor >= 0 && /^\s*\/\//.test(lines[cursor] || ''); cursor--) {
+      commentBlock.unshift(lines[cursor].replace(/^\s*\/\//, ''));
+    }
+    calls.push({ line: i + 1, hasReason: hasReasonText(commentBlock.join('\n')) });
   }
   return calls;
 }
@@ -251,7 +271,7 @@ function checkSkippedTests(projectDir, config) {
           location: `${relPath}:${line}`,
           suggestion: {
             kind: 'fix',
-            text: 'Add a // REASON: comment on or up to 3 lines above the skip explaining why',
+            text: 'Add a // REASON: comment immediately above the skip explaining why',
             pragma: '// REASON: <why this test is skipped>',
           },
         }));