docguard-cli 0.26.0 → 0.28.0

package/cli/scanners/semantic-claims.mjs

@@ -0,0 +1,154 @@
+/**
+ * Semantic claim extractor (LLM field report #5).
+ *
+ * The highest-value class of doc bug is SEMANTIC: a documented number/enum/limit
+ * that no longer matches the code — DLP retention "30 days" vs code 730, a status
+ * enum "PENDING/IDLE" vs "WAITING", "100/min" vs "500 req/s", "29+ roles" vs 44,
+ * "4 GSIs" vs 6. Regex/AST can't judge these (the doc value and the code value
+ * are both just numbers), so they slip through every deterministic validator.
+ *
+ * DocGuard is zero-dependency and does NOT call an LLM itself. So this is an
+ * EXTRACTOR: it surfaces the verifiable claims — value, unit, doc:line, section,
+ * and the nearest cited code path — as a structured task list. The agent running
+ * `docguard verify --semantic` does the actual comparison against the code. This
+ * mirrors the `docguard agent` task-graph: deterministic discovery, LLM judgment.
+ *
+ * Precision over recall: a number is only a claim when it carries a recognized
+ * unit (days/ms/req-s/GSIs/roles/…); an enum only when it's a list of 2+
+ * UPPER_SNAKE tokens in a status/state/enum context. Bare version strings, dates,
+ * and prose numbers are ignored.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+// Numbers are only claims when adjacent to a recognized unit.
+const NUMBER_PATTERNS = [
+  { kind: 'duration', re: /\b(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|secs?|minutes?|mins?|hours?|hrs?|days?|weeks?|months?|years?)\b/gi },
+  { kind: 'rate',     re: /\b(\d+)\s*(?:\/|\bper\b|\breq(?:uests?)?\s*\/?)\s*(s|sec|seconds?|min|minutes?|hours?|h)\b/gi },
+  { kind: 'count',    re: /\b(\d+)\s*\+?\s*(GSIs?|LSIs?|indexes|indices|roles?|permissions?|scopes?|tables?|queues?|topics?|buckets?|endpoints?|routes?|validators?|columns?|fields?|shards?|partitions?|replicas?|retries|workers?|threads?|connections?)\b/gi },
+];
+
+// A list of 2+ UPPER_SNAKE tokens separated by / , | or "or" — an enum claim,
+// but only when the line or its heading reads like a status/state/enum context.
+const ENUM_LIST_RE = /\b[A-Z][A-Z0-9_]{2,}(?:\s*(?:\/|,|\||\bor\b)\s*[A-Z][A-Z0-9_]{2,}){1,}\b/g;
+const ENUM_CONTEXT_RE = /\b(status|state|enum|values?|one of|phase|stage|transitions?)\b/i;
+
+// A code path mentioned in or near the claim — the agent's starting point.
+const CITED_CODE_RE = /`?([\w./-]+\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json))`?(?::(\d+))?/;
+
+const MAX_CLAIMS = 80;
+
+/** Canonical docs + the root docs where limits/counts commonly live. */
+function claimSourceDocs(projectDir) {
+  const docs = [];
+  const canonical = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonical)) {
+    try {
+      for (const f of readdirSync(canonical)) {
+        if (f.toLowerCase().endsWith('.md')) docs.push(`docs-canonical/${f}`);
+      }
+    } catch { /* ignore */ }
+  }
+  for (const root of ['README.md', 'AGENTS.md']) {
+    if (existsSync(resolve(projectDir, root))) docs.push(root);
+  }
+  return docs;
+}
+
+/** True if a line is inside a fenced code block (toggled by the caller). */
+function findCitedCode(lines, idx) {
+  // Search the claim line first, then the immediately adjacent lines. A tight
+  // window avoids cross-attributing a path from an unrelated nearby claim (e.g.
+  // a rate limit grabbing the retention doc's cited file three lines up).
+  for (let d = 0; d <= 1; d++) {
+    for (const j of d === 0 ? [idx] : [idx - d, idx + d]) {
+      if (j < 0 || j >= lines.length) continue;
+      const m = CITED_CODE_RE.exec(lines[j]);
+      if (m) return m[2] ? `${m[1]}:${m[2]}` : m[1];
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract semantic claims from a project's canonical docs.
+ * @returns {Array<{ doc, line, section, kind, subkind, value, unit, text, citedCode }>}
+ */
+export function extractSemanticClaims(projectDir, config = {}) {
+  const claims = [];
+  const seen = new Set();
+
+  for (const doc of claimSourceDocs(projectDir)) {
+    let content;
+    try { content = readFileSync(resolve(projectDir, doc), 'utf-8'); } catch { continue; }
+    const lines = content.split('\n');
+    let section = '';
+    let inFence = false;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (/^\s*```/.test(line)) { inFence = !inFence; continue; }
+      if (inFence) continue; // numbers in code samples are examples, not claims
+      const h = line.match(/^#{1,6}\s+(.*)$/);
+      if (h) { section = h[1].trim(); continue; }
+
+      const lineNo = i + 1;
+      const push = (claim) => {
+        const key = `${doc}:${lineNo}:${claim.kind}:${claim.value}:${claim.unit || ''}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        claims.push({ doc, line: lineNo, section, citedCode: findCitedCode(lines, i), text: line.trim().slice(0, 200), ...claim });
+      };
+
+      for (const { kind, re } of NUMBER_PATTERNS) {
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(line)) !== null) {
+          push({ kind: 'number', subkind: kind, value: m[1], unit: m[2].toLowerCase() });
+        }
+      }
+
+      if (ENUM_CONTEXT_RE.test(line) || ENUM_CONTEXT_RE.test(section)) {
+        ENUM_LIST_RE.lastIndex = 0;
+        let m;
+        while ((m = ENUM_LIST_RE.exec(line)) !== null) {
+          // Skip all-caps acronym runs joined by slash that are really one token.
+          const values = m[0].split(/\s*(?:\/|,|\||\bor\b)\s*/).filter(Boolean);
+          if (values.length >= 2) push({ kind: 'enum', subkind: 'enum-list', value: values.join('/'), unit: null });
+        }
+      }
+
+      if (claims.length >= MAX_CLAIMS) return claims;
+    }
+  }
+  return claims;
+}
+
+/**
+ * Turn extracted claims into agent-executable verification tasks (one per claim).
+ * Pure — reused by the command and any task-graph consumer.
+ */
+export function buildSemanticVerifyTasks(claims) {
+  return claims.map((c, i) => {
+    const where = c.citedCode ? ` Start at the cited code: ${c.citedCode}.` : ' No code path is cited nearby — grep the codebase for the relevant constant/config.';
+    const what = c.kind === 'enum'
+      ? `the enum/status set "${c.value}"`
+      : `the ${c.subkind} value ${c.value}${c.unit ? ` ${c.unit}` : ''}`;
+    return {
+      id: `verify.semantic.${i + 1}`,
+      doc: c.doc,
+      line: c.line,
+      section: c.section,
+      kind: c.kind,
+      value: c.value,
+      unit: c.unit,
+      citedCode: c.citedCode,
+      claim: c.text,
+      instruction: `Verify ${what} documented in ${c.doc}:${c.line}${c.section ? ` (section "${c.section}")` : ''} against the code.${where} If the code disagrees, the doc (or the code) is wrong — report the mismatch with both values.`,
+      confidence: 'requires-human',
+    };
+  });
+}

package/cli/shared-source.mjs

@@ -295,6 +295,27 @@ function classifyChars(content, ext) {
  * including bracket access.
  * @returns {Set<string>} variable names referenced in code
  */
+/**
+ * v0.27 (field report #7): env vars injected by the test runner / CI / cloud
+ * SDK are READ in code (e.g. `if (process.env.VITEST)` as a test guard) but no
+ * application documents them as config — flagging them "undocumented" is a
+ * false positive. This is the env equivalent of the SYSTEM allowlist already
+ * applied on the docs side in environment.mjs.
+ *
+ * Deliberately conservative — NODE_ENV is intentionally NOT here: this project
+ * already decided NODE_ENV is legitimate app config (see environment.mjs).
+ */
+const RUNNER_ENV_VARS = new Set([
+  'VITEST', 'CI', 'JEST_WORKER_ID', 'AWS_SESSION_TOKEN', 'AWS_EXECUTION_ENV',
+]);
+const RUNNER_ENV_PREFIXES = ['GITHUB_', 'RUNNER_', 'VITEST_', 'JEST_', 'CIRCLE_', 'GITLAB_CI'];
+
+/** True when `name` is a runner/CI/SDK-injected var, not product config. */
+export function isRunnerEnvVar(name) {
+  if (RUNNER_ENV_VARS.has(name)) return true;
+  return RUNNER_ENV_PREFIXES.some((p) => name.startsWith(p));
+}
+
 export function grepEnvUsage(projectDir, config = {}) {
   const names = new Set();
   const roots = resolveSourceRoots(projectDir, config);
@@ -347,6 +368,7 @@ export function grepEnvUsage(projectDir, config = {}) {
       while ((m = rx.exec(content)) !== null) {
         if (kind[m.index] !== 0) continue; // keyword inside a string/comment → a mention, not a read
         if (isViteSource && VITE_INTRINSICS.has(m[1])) continue;
+        if (isRunnerEnvVar(m[1])) continue; // v0.27 (#7): runner/CI/SDK var, not product config
         names.add(m[1]);
       }
     }
@@ -366,12 +388,12 @@ export function grepEnvUsage(projectDir, config = {}) {
       // camelCase keys, so requiring UPPER_SNAKE keeps this env-specific.
       const keyRe = /^\s*['"]?([A-Z][A-Z0-9_]*[A-Z0-9])['"]?\s*:/gm;
       while ((km = keyRe.exec(content)) !== null) {
-        if (km[1].length >= 3 && !VITE_INTRINSICS.has(km[1])) names.add(km[1]);
+        if (km[1].length >= 3 && !VITE_INTRINSICS.has(km[1]) && !isRunnerEnvVar(km[1])) names.add(km[1]);
       }
       // convict: the env var name is the `env:` property value, not the key.
       const convictRe = /\benv\s*:\s*['"]([A-Z][A-Z0-9_]*[A-Z0-9])['"]/g;
       while ((km = convictRe.exec(content)) !== null) {
-        if (km[1].length >= 3) names.add(km[1]);
+        if (km[1].length >= 3 && !isRunnerEnvVar(km[1])) names.add(km[1]);
       }
     }
   };

package/cli/validators/api-surface.mjs

@@ -208,10 +208,56 @@ export function computeApiSurfaceDrift(projectDir, config) {
   };
 }
 
+/**
+ * v0.28 (field report #4): diff the OpenAPI spec against the routes actually
+ * REGISTERED in code. When a spec exists, resolveApiSurface treats it as ground
+ * truth and the API-REFERENCE doc reconciles against it — so a spec that declares
+ * a phantom endpoint (no Express/Fastify route registers it) passes doc-vs-spec
+ * clean while the spec itself is wrong. This catches that.
+ *
+ * Conservative on purpose: only runs when code routes are actually scannable.
+ * If the scanner finds zero routes (unsupported framework, dynamically-registered
+ * routes), we can't tell "no route" from "scanner blind", so we skip rather than
+ * flag every spec endpoint as phantom. Reuses compareEndpoints so path-param /
+ * mount-prefix normalization matches the rest of the validator.
+ *
+ * @returns {{ applicable:boolean, specPath:string|null, routeCount:number,
+ *             matched:object[], specDeclaredNoRoute:object[], reason?:string }}
+ */
+export function computeSpecVsRouteDrift(projectDir, config) {
+  const specs = findAllOpenApiSpecs(projectDir, config);
+  if (specs.length === 0) {
+    return { applicable: false, specPath: null, routeCount: 0, matched: [], specDeclaredNoRoute: [], reason: 'no openapi spec' };
+  }
+  const spec = specs[0]; // authoritative (sourceRoot first, root last)
+  const framework = detectFramework(projectDir, config);
+  const routes = scanRoutesDeep(projectDir, { framework }, { openapi: { found: false } }, { config });
+  if (routes.length === 0) {
+    return { applicable: false, specPath: spec.relPath, routeCount: 0, matched: [], specDeclaredNoRoute: [], reason: 'no routes scannable' };
+  }
+  // documentedButAbsent = in the SPEC (first arg) but absent from the ROUTES
+  // (second arg) = spec-declares-but-no-route.
+  const cmp = compareEndpoints(
+    spec.endpoints.map(e => ({ method: e.method, path: e.path })),
+    routes.map(r => ({ method: r.method, path: r.path }))
+  );
+  return {
+    applicable: true,
+    specPath: spec.relPath,
+    routeCount: routes.length,
+    matched: cmp.matched,
+    specDeclaredNoRoute: cmp.documentedButAbsent,
+  };
+}
+
 export function validateApiSurface(projectDir, config) {
   const errors = [];
   const warnings = [];
   const fixes = [];
+  const trim = (arr) => {
+    const shown = arr.slice(0, MAX_REPORTED);
+    return { shown, extra: arr.length - shown.length };
+  };
 
   // v0.14-P2: when --changed-only scoping is active and NONE of the changed
   // files look like route/spec/controller files, this validator has nothing
@@ -256,19 +302,39 @@ export function validateApiSurface(projectDir, config) {
     );
   }
 
+  // ── #4: spec declares an endpoint with no registered route ──
+  // Independent of the API-REFERENCE doc — it checks the spec against code, so it
+  // runs even when no doc exists. Conservative (only when routes are scannable).
+  const specRoute = computeSpecVsRouteDrift(projectDir, config);
+  let specRouteTotal = 0;
+  let specRoutePassed = 0;
+  if (specRoute.applicable) {
+    specRouteTotal = specRoute.matched.length + specRoute.specDeclaredNoRoute.length;
+    specRoutePassed = specRoute.matched.length;
+    if (specRoute.specDeclaredNoRoute.length) {
+      const { shown, extra } = trim(specRoute.specDeclaredNoRoute);
+      for (const e of shown) {
+        warnings.push(
+          `OpenAPI spec (${specRoute.specPath}) declares ${e.method} ${e.path} but no route registers it in code — ` +
+          `the spec may be wrong, and the API-REFERENCE doc reconciles clean against it, hiding the gap.`
+        );
+      }
+      if (extra > 0) warnings.push(`…and ${extra} more spec-declared endpoint(s) with no registered route`);
+    }
+  }
+
   if (!drift.applicable) {
-    // Nothing to validate against the API-REFERENCE doc.
-    return { errors, warnings, passed: 0, total: 0, fixes, authoritativeSpec: drift.source };
+    // Nothing to validate against the API-REFERENCE doc — but the spec-vs-route
+    // check above may still have produced findings.
+    return {
+      errors, warnings, passed: specRoutePassed, total: specRouteTotal, fixes,
+      authoritativeSpec: drift.source || specRoute.specPath,
+    };
   }
 
   const { documentedButAbsent, presentButUndocumented, matched, confidence, source } = drift;
-  const total = matched.length + documentedButAbsent.length + presentButUndocumented.length;
-  const passed = matched.length;
-
-  const trim = (arr) => {
-    const shown = arr.slice(0, MAX_REPORTED);
-    return { shown, extra: arr.length - shown.length };
-  };
+  const total = matched.length + documentedButAbsent.length + presentButUndocumented.length + specRouteTotal;
+  const passed = matched.length + specRoutePassed;
 
   // documented-but-absent → deterministic remove-endpoint fixes
   if (documentedButAbsent.length) {

package/cli/validators/architecture.mjs

@@ -97,11 +97,11 @@ function validateConfigLayers(projectDir, config, layers, results) {
       const relPath = relative(projectDir, file);
       const imports = extractImports(content);
 
-      for (const imp of imports) {
-        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+      for (const { spec } of imports) {
+        if (!spec.startsWith('.') && !spec.startsWith('/')) continue;
 
         for (const forbiddenDir of layer.forbidden) {
-          if (imp.includes(forbiddenDir) || imp.includes(`/${forbiddenDir}/`)) {
+          if (spec.includes(forbiddenDir) || spec.includes(`/${forbiddenDir}/`)) {
             results.total++;
             results.errors.push(
               `${relPath}: ${layer.name} layer imports from forbidden layer (${forbiddenDir})`
@@ -135,14 +135,19 @@ function buildImportGraph(projectDir, config) {
 
       const resolvedImports = [];
       for (const imp of imports) {
-        if (!imp.startsWith('.') && !imp.startsWith('/')) continue;
+        if (!imp.spec.startsWith('.') && !imp.spec.startsWith('/')) continue;
 
         // Resolve relative imports
         const fromDir = dirname(file);
-        const resolved = resolveImport(fromDir, imp, projectDir);
+        const resolved = resolveImport(fromDir, imp.spec, projectDir);
         if (resolved) {
-          resolvedImports.push(resolved);
-          graph.edges.push({ from: relPath, to: resolved });
+          graph.edges.push({ from: relPath, to: resolved, dynamic: imp.dynamic });
+          // v0.28 (field report #2): a dynamic `await import()` does NOT create a
+          // load-time edge — it's the canonical way to BREAK an import cycle. So
+          // it's excluded from the cycle-detection adjacency (fileMap) while still
+          // recorded in graph.edges for layer-boundary checks (an import is still
+          // an import for layering).
+          if (!imp.dynamic) resolvedImports.push(resolved);
         }
       }
 
@@ -153,26 +158,33 @@ function buildImportGraph(projectDir, config) {
   return graph;
 }
 
+/**
+ * Extract a file's imports as `{ spec, dynamic }`. `dynamic:true` marks a
+ * runtime `import('…')` — which does NOT create a load-time dependency edge and
+ * is the canonical way to break an import cycle (field report #2). ES `import …
+ * from` and CommonJS `require()` are load-time (static).
+ */
 function extractImports(content) {
   const imports = [];
 
-  // ES module imports
+  // ES module imports (static, load-time). `import\s+` requires whitespace after
+  // `import`, so it never matches a dynamic `import(` call.
   const esImportRegex = /import\s+(?:.*?\s+from\s+)?['"]([^'"]+)['"]/g;
   let match;
   while ((match = esImportRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: false });
   }
 
-  // Dynamic imports
+  // Dynamic imports (runtime — NOT a load-time cycle edge)
   const dynamicRegex = /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
   while ((match = dynamicRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: true });
   }
 
-  // CommonJS require
+  // CommonJS require (static, load-time)
   const requireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
   while ((match = requireRegex.exec(content)) !== null) {
-    imports.push(match[1]);
+    imports.push({ spec: match[1], dynamic: false });
   }
 
   return imports;

package/cli/validators/doc-quality.mjs

@@ -533,7 +533,13 @@ function analyzeDocument(doc) {
       conditionalLoad: conditional.ratio,
     },
     details: { passive, ambiguous, atomicity, negation, conditional },
-    overrides: { negationLoad: parseQualityOverride(content, 'negation-load') },
+    overrides: {
+      negationLoad: parseQualityOverride(content, 'negation-load'),
+      // v0.27 (#9): parity with negation-load. Sequence/flow docs (MESSAGE-FLOWS,
+      // INTEGRATIONS) are legitimately passive; let them opt out per-doc instead
+      // of warning unconditionally.
+      passiveVoice: parseQualityOverride(content, 'passive-voice'),
+    },
   };
 }
 
@@ -561,12 +567,17 @@ export function validateDocQuality(projectDir, config) {
 
     // ── Check 1: Passive Voice ──
     results.total++;
-    if (m.passiveVoiceRatio <= THRESHOLDS.passiveVoiceRatio.warn) {
+    const passiveOv = analysis.overrides?.passiveVoice;
+    const passiveThreshold = passiveOv?.threshold
+      ?? config.docQuality?.passiveVoiceThreshold
+      ?? THRESHOLDS.passiveVoiceRatio.warn;
+    if (passiveOv?.off || m.passiveVoiceRatio <= passiveThreshold) {
       results.passed++;
     } else {
       results.warnings.push(
         `${doc.name}: High passive voice ratio (${(m.passiveVoiceRatio * 100).toFixed(0)}% of sentences). ` +
-        `Use active voice for clarity. Found ${analysis.details.passive.count}/${analysis.details.passive.total} passive sentences`
+        `Use active voice for clarity. Found ${analysis.details.passive.count}/${analysis.details.passive.total} passive sentences. ` +
+        `If the passive voice is intentional (sequence/flow doc), add: <!-- docguard:quality passive-voice off — your reason -->`
       );
     }
 

package/cli/validators/security.mjs

@@ -8,6 +8,18 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, extname } from 'node:path';
 import { shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { mkFinding, resultFromFindings, lineSuppresses } from '../findings.mjs';
+
+// Each secret pattern maps to a stable finding code (see cli/findings.mjs CODES)
+// so it is `explain`-able and inline-suppressible (`// docguard:ignore SEC00x`).
+const LABEL_TO_CODE = {
+  'hardcoded password': 'SEC001',
+  'hardcoded API key': 'SEC002',
+  'hardcoded secret key': 'SEC003',
+  'hardcoded access token': 'SEC004',
+  'AWS Access Key ID': 'SEC005',
+  'API secret key (Stripe/OpenAI pattern)': 'SEC006',
+};
 
 const CODE_EXTENSIONS = new Set([
   '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx',
@@ -54,11 +66,46 @@ function isSafePlaceholder(line, matchStr) {
   return SAFE_PATTERNS.some(p => p.test(line));
 }
 
-export function validateSecurity(projectDir, config) {
-  const results = { name: 'security', errors: [], warnings: [], passed: 0, total: 0 };
+/**
+ * v0.27 (field report #1): a password-style key whose VALUE is natural
+ * language — an error message, validation copy, UI string — is almost never a
+ * credential. e.g. a "New password must differ from recent passwords"
+ * validation message assigned to such a key.
+ *
+ * We don't drop these (a real secret that happens to read like prose must still
+ * surface — false-green is the failure mode this tool exists to prevent); we
+ * downgrade them to a LOW-CONFIDENCE warning the agent can suppress inline,
+ * instead of a blocking error. Heuristic per the field report: ≥3 words, OR
+ * ≥2 internal spaces, OR ends in sentence punctuation.
+ *
+ * @param {string} value - the literal inside the quotes
+ */
+function looksLikeProse(value) {
+  if (!value) return false;
+  const v = value.trim();
+  const words = v.split(/\s+/).filter(Boolean);
+  // Multi-word natural language (validation messages, UI copy, sentences).
+  if (words.length >= 3) return true;
+  // A 2-word sentence fragment ending in terminal punctuation — but NOT a
+  // single token like "SuperSecretPassword!" (strong passwords end in !/? too,
+  // so terminal punctuation ALONE must never reclassify a one-word value).
+  if (words.length >= 2 && /[.!?]$/.test(v)) return true;
+  return false;
+}
+
+/** Pull the first quoted literal out of a matched secret expression. */
+function quotedValue(matchStr) {
+  const m = matchStr.match(/['"]([^'"]*)['"]/);
+  return m ? m[1] : '';
+}
 
+export function validateSecurity(projectDir, config) {
+  /** @type {import('../findings.mjs').Finding[]} */
   const findings = [];
+  let passed = 0;
+  let total = 0;
   let scanned = 0;
+  let realSecretCount = 0;
 
   walkDir(projectDir, (filePath) => {
     const ext = extname(filePath);
@@ -89,25 +136,58 @@ export function validateSecurity(projectDir, config) {
         // Lazily initialize lines only when a match is found
         if (!lines) lines = content.split('\n');
 
-        // Find the line containing this match for context-aware filtering
-        const matchPos = match.index;
-        let charCount = 0;
-        let matchLine = '';
-        for (const line of lines) {
-          charCount += line.length + 1; // +1 for newline
-          if (charCount > matchPos) {
-            matchLine = line;
-            break;
-          }
-        }
+        // 1-based line number + the line above (for inline-pragma suppression).
+        const lineNo = content.slice(0, match.index).split('\n').length;
+        const matchLine = lines[lineNo - 1] || '';
+        const prevLine = lines[lineNo - 2] || '';
 
         // Skip known-safe placeholder/example values, but keep scanning for a
         // real one further down the file.
         if (isSafePlaceholder(matchLine, match[0])) continue;
 
-        findings.push({ file: relPath, label, match: match[0].substring(0, 30) + '...' });
+        const code = LABEL_TO_CODE[label];
+
+        // v0.27 (#8): honour an inline `// docguard:ignore SEC00x` pragma on the
+        // line or the line above — per-line suppression instead of blinding the
+        // whole file via `securityIgnore`.
+        if (code && lineSuppresses(code, matchLine, prevLine)) break;
+
+        const location = `${relPath}:${lineNo}`;
+        const value = quotedValue(match[0]);
+        const isProse = looksLikeProse(value);
+
+        if (isProse) {
+          // v0.27 (#1): natural-language value → low-confidence warning, not a
+          // blocking error. Still surfaced (no false-green), still suppressible,
+          // and now reportable via `docguard feedback`.
+          findings.push(mkFinding({
+            code, validator: 'security', severity: 'warn', confidence: 'low',
+            message: `${location}: possible ${label} — but the value reads like natural-language text (likely UI copy / a validation message, not a credential)`,
+            location,
+            suggestion: {
+              kind: 'suppress',
+              text: 'If this is UI copy or a message and not a real secret, suppress it inline.',
+              pragma: `// docguard:ignore ${code} — UI copy, not a credential`,
+            },
+            reportable: true,
+            redactedContext: `${label} pattern fired on a value that is natural-language text (~${value.trim().split(/\s+/).filter(Boolean).length} words). Literal omitted.`,
+          }));
+        } else {
+          realSecretCount++;
+          findings.push(mkFinding({
+            code, validator: 'security', severity: 'error', confidence: 'high',
+            message: `${location}: possible ${label} found`,
+            location,
+            suggestion: {
+              kind: 'fix',
+              text: 'Move the secret to an environment variable and read it via process.env / the platform secret store. Never commit credentials.',
+              command: code ? `docguard explain ${code}` : undefined,
+              pragma: code ? `// docguard:ignore ${code} — reason (only if a confirmed false positive)` : undefined,
+            },
+          }));
+        }
         // One finding per (file, label) is enough — the reported message is
-        // identical for repeats and we've already proven a real secret exists.
+        // identical for repeats and we've already proven a match exists.
         break;
       }
     }
@@ -116,35 +196,41 @@ export function validateSecurity(projectDir, config) {
   // Only count the secret scan as a passed check if we actually scanned files.
   // An empty scan that reports "no secrets" is a dangerous false ✅ — surface it.
   if (scanned > 0) {
-    results.total++;
-    if (findings.length === 0) {
-      results.passed++;
-    } else {
-      for (const f of findings) {
-        results.errors.push(`${f.file}: possible ${f.label} found`);
-      }
-    }
+    total++;
+    // Low-confidence (prose) findings do not fail the check — only real secrets do.
+    if (realSecretCount === 0) passed++;
   } else {
-    results.warnings.push(
-      'No source files were scanned for secrets — check config.sourceRoot / ignore patterns'
-    );
+    findings.push(mkFinding({
+      code: 'SEC011', validator: 'security', severity: 'warn', confidence: 'high',
+      message: 'No source files were scanned for secrets — check config.sourceRoot / ignore patterns',
+      suggestion: { kind: 'review', text: 'Verify config.sourceRoot and ignore patterns actually include your source tree.' },
+    }));
   }
 
   // Check .gitignore includes .env
-  results.total++;
+  total++;
   const gitignorePath = resolve(projectDir, '.gitignore');
   if (existsSync(gitignorePath)) {
     const gitignore = readFileSync(gitignorePath, 'utf-8');
     if (gitignore.includes('.env') || gitignore.includes('.env.local')) {
-      results.passed++;
+      passed++;
     } else {
-      results.warnings.push('.gitignore does not include .env — secrets may be committed');
+      findings.push(mkFinding({
+        code: 'SEC010', validator: 'security', severity: 'warn', confidence: 'high',
+        message: '.gitignore does not include .env — secrets may be committed',
+        location: '.gitignore',
+        suggestion: { kind: 'fix', text: 'Add `.env` and `.env.local` to .gitignore.' },
+      }));
     }
   } else {
-    results.warnings.push('No .gitignore found — secrets may be committed');
+    findings.push(mkFinding({
+      code: 'SEC010', validator: 'security', severity: 'warn', confidence: 'high',
+      message: 'No .gitignore found — secrets may be committed',
+      suggestion: { kind: 'fix', text: 'Create a .gitignore that excludes `.env` and `.env.local`.' },
+    }));
   }
 
-  return results;
+  return resultFromFindings(findings, { passed, total });
 }
 
 function walkDir(dir, callback) {

package/cli/validators/todo-tracking.mjs

@@ -262,6 +262,10 @@ function loadTrackingDocs(projectDir, config) {
   const trackingFiles = [
     'ROADMAP.md', 'CURRENT-STATE.md', 'TODO.md', 'BACKLOG.md',
     'docs-canonical/ARCHITECTURE.md', 'CHANGELOG.md',
+    // v0.27 (field report #6): many projects keep the roadmap/backlog under
+    // docs-canonical/ — a TODO tracked there was wrongly read as "untracked".
+    'docs-canonical/ROADMAP.md', 'docs-canonical/CURRENT-STATE.md',
+    'docs-canonical/BACKLOG.md', 'docs-canonical/TODO.md',
     ...(config.todoTracking?.trackingFiles || []),
   ];
 

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

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.25.1"
+  version: "0.28.0"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. One pinned runtime dependency (@babel/parser); pure Node.js otherwise."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

package/extensions/spec-kit-docguard/skills/docguard-fix/SKILL.md

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.25.0
+  version: 0.28.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.25.0 -->
+<!-- docguard:version: 0.28.0 -->
 
 # DocGuard Fix Skill