docguard-cli 0.26.0 → 0.27.0

package/README.md

@@ -63,7 +63,7 @@ DocGuard is an official [GitHub Spec Kit](https://github.com/github/spec-kit) co
 
 ```mermaid
 graph TD
-    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (14)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (16)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -250,7 +250,7 @@ This installs DocGuard's slash commands (`/docguard.init`, `/docguard.guard`, `/
 
 ## Usage
 
-DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including the zero-install `demo`). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
+DocGuard ships **16 commands** (the "Daily 5" + 11 situational tools, including the zero-install `demo`). Six additional one-shot scaffolders are accessed via `docguard init --with <name>`. Eight v0.19 commands continue to work as deprecation aliases through v0.20.x — see [MIGRATION-v0.20.md](docs-implementation/MIGRATION-v0.20.md).
 
 **The Daily 5** — what you'll reach for 95% of the time:
 
@@ -273,7 +273,8 @@ DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including t
 | `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
 | `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
 | `agent` | One-shot agent task graph — ordered, pre-filled code-truth, per-task verify (`--format json`) |
-| `explain <warning>` | Paste any warning — get the validator's docstring + fix path |
+| `explain <warning\|CODE>` | Paste any warning — or a finding code like `SEC001` — to get the validator's docstring, fix path, and how to suppress |
+| `feedback` | Report likely false positives back to DocGuard — local-first record + a 1-click prefilled, redacted GitHub issue (zero typing) |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |
 | `score --diff` | Drill into which checks pulled each category down |

package/cli/commands/explain.mjs

@@ -17,6 +17,7 @@
  */
 
 import { c } from '../shared.mjs';
+import { CODES } from '../findings.mjs';
 
 /**
  * Validator-key → human-readable explainer. Keyed by the same key DocGuard
@@ -292,7 +293,7 @@ const EXPLAINERS = {
     why:  'Vague, passive, negation-heavy docs are hard for both humans and AI agents to act on. Metrics inspired by IEEE 830 / ISO 29148.',
     triggers: [
       ['High negation load', 'Rephrase in positive terms ("must not fail" → "must succeed"). If the negation is intentional (security/operational docs legitimately use "never"/"must not"), add the per-doc override: `<!-- docguard:quality negation-load off — your reason -->`, or set a custom bar with `<!-- docguard:quality negation-load 0.35 — reason -->`. Project-wide default: `docQuality.negationLoadThreshold` in .docguard.json.'],
-      ['High passive voice ratio', 'Use active voice: "the config is read by the loader" → "the loader reads the config".'],
+      ['High passive voice ratio', 'Use active voice: "the config is read by the loader" → "the loader reads the config". If the doc is legitimately passive (a sequence/flow doc), add the per-doc override: `<!-- docguard:quality passive-voice off — your reason -->`, or set a custom bar with `<!-- docguard:quality passive-voice 0.4 — reason -->`. Project-wide default: `docQuality.passiveVoiceThreshold` in .docguard.json.'],
       ['High ambiguous pronoun ratio', 'Replace "it/this/that/they" with the specific noun.'],
       ['Low atomicity', 'Split compound sentences so each states one verifiable fact (IEEE 830 §4.1).'],
       ['Reading level too high', 'Aim for grade 12–16 for technical docs — shorter sentences, simpler words.'],
@@ -419,6 +420,27 @@ export function runExplain(projectDir, _config, flags) {
     return;
   }
 
+  // v0.27: finding-code lookup — `docguard explain SEC001`. Codes are the stable,
+  // LLM-addressable handles that guard prints next to each finding and that
+  // inline `// docguard:ignore <CODE>` keys off.
+  const codeKey = query.toUpperCase();
+  if (CODES[codeKey]) {
+    const cd = CODES[codeKey];
+    if (isJson) {
+      console.log(JSON.stringify({ query, code: codeKey, ...cd }, null, 2));
+      return;
+    }
+    console.log(`${c.bold}🧭 ${codeKey} — ${cd.title}${c.reset}`);
+    console.log(`${c.dim}   validator: ${cd.validator}${c.reset}\n`);
+    console.log(`${c.bold}What it means:${c.reset}\n  ${cd.help}\n`);
+    if (cd.suppress) {
+      console.log(`${c.bold}Suppress inline${c.reset} ${c.dim}(only if it's a confirmed false positive):${c.reset}`);
+      console.log(`  ${c.cyan}${cd.suppress}${c.reset}\n`);
+    }
+    console.log(`${c.bold}Got it wrong?${c.reset} ${c.dim}Send a redacted report so a future release stops flagging it: ${c.cyan}docguard feedback${c.reset}`);
+    return;
+  }
+
   const match = matchWarning(query);
   if (!match) {
     if (isJson) {

package/cli/commands/feedback.mjs

@@ -0,0 +1,163 @@
+/**
+ * Feedback Command — close the loop with the tool's maintainers (v0.27).
+ *
+ * DocGuard is a tool for LLMs: when it gets something wrong, the cheapest way to
+ * make the NEXT release better is to capture that signal. This command turns the
+ * low-confidence findings of a guard run (candidate false positives — and any
+ * other finding DocGuard itself flagged as uncertain) into:
+ *
+ *   1. a LOCAL-FIRST record under .docguard/feedback/<code>-<id>.json (full,
+ *      reviewable, never sent anywhere automatically), and
+ *   2. a one-click, PREFILLED GitHub issue URL that needs zero typing.
+ *
+ * Hard constraints (learned the hard way — see commit 3b600fd, where an
+ * oversized prefilled URL overflowed GitHub's ~8 KB limit and silently failed):
+ *   - The URL is CAPPED well under the limit; bulk lives in the local file.
+ *   - It is REDACTED: no source code, no secret values — only a basename, a line
+ *     number, and the safe `redactedContext` the validator built.
+ *   - It is OPT-IN: nothing is filed automatically; the human clicks (or not).
+ *
+ * Not read-only in the strict sense — it writes its own .docguard/feedback/ —
+ * but it never scaffolds skills and never touches the user's source tree.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { c } from '../shared.mjs';
+import { runGuardInternal } from './guard.mjs';
+
+const _PKG = JSON.parse(
+  readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8')
+);
+const CLI_VERSION = _PKG.version;
+const ISSUES_BASE = (_PKG.bugs && _PKG.bugs.url) || 'https://github.com/raccioly/docguard/issues';
+
+// Keep the prefilled URL comfortably under GitHub's ~8 KB request-URL limit.
+const URL_CAP = 1800;
+
+/** Deterministic short id from a string — avoids Date.now()/Math.random(). */
+function shortId(str) {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) h = ((h << 5) + h + str.charCodeAt(i)) >>> 0;
+  return h.toString(36).slice(0, 6);
+}
+
+/** Redact a finding location for the SHARED url: basename + line only. */
+function safeLocation(location) {
+  if (!location) return '(unknown)';
+  const [path, line] = String(location).split(/:(?=\d+$)/);
+  return line ? `${basename(path)}:${line}` : basename(path);
+}
+
+/**
+ * Build a prefilled, capped issue URL. Drops optional body lines (longest-value
+ * first) until under the cap; title + code + location always survive.
+ */
+function buildIssueUrl(finding) {
+  const code = finding.code || 'FINDING';
+  const validator = finding.validator || 'unknown';
+  const shortMsg = (finding.message || '').replace(/\s+/g, ' ').slice(0, 70);
+  const title = `[feedback] ${code} (${validator}): ${shortMsg}`;
+
+  // Optional lines are ordered most→least droppable.
+  const required = [
+    `DocGuard v${CLI_VERSION} flagged this and it may be a false positive (or other feedback).`,
+    '',
+    `- Code: ${code}`,
+    `- Validator: ${validator}`,
+    `- Location: ${safeLocation(finding.location)}`,
+    `- Confidence: ${finding.confidence}`,
+  ];
+  const optional = [];
+  if (finding.redactedContext) optional.push(`- Context: ${finding.redactedContext}`);
+  if (finding.suggestion && finding.suggestion.text) optional.push(`- Suggestion shown: ${finding.suggestion.text}`);
+  const footer = ['', 'Generated by `docguard feedback` — no source code or secret values are included.'];
+
+  const compose = (opt) => `${ISSUES_BASE}/new?labels=${encodeURIComponent('docguard-feedback')}` +
+    `&title=${encodeURIComponent(title)}` +
+    `&body=${encodeURIComponent([...required, ...opt, ...footer].join('\n'))}`;
+
+  let opt = [...optional];
+  let url = compose(opt);
+  while (url.length > URL_CAP && opt.length > 0) {
+    opt = opt.slice(0, -1);
+    url = compose(opt);
+  }
+  if (url.length > URL_CAP) {
+    // Even the required body is too long (pathological) — collapse to a stub.
+    url = `${ISSUES_BASE}/new?labels=${encodeURIComponent('docguard-feedback')}` +
+      `&title=${encodeURIComponent(title)}` +
+      `&body=${encodeURIComponent(`DocGuard v${CLI_VERSION} — ${code} (${validator}). Full details saved locally; please attach.`)}`;
+  }
+  return { url, title };
+}
+
+export function runFeedback(projectDir, config, flags) {
+  const data = runGuardInternal(projectDir, config);
+  const reportable = (data.findings || []).filter((f) => f.reportable);
+  const isJson = flags.format === 'json';
+
+  if (reportable.length === 0) {
+    if (isJson) {
+      console.log(JSON.stringify({ reportable: [], message: 'no uncertain findings' }, null, 2));
+      return;
+    }
+    console.log(`${c.bold}📮 DocGuard Feedback${c.reset}`);
+    console.log(`${c.green}✅ Nothing to report — DocGuard is confident about everything it flagged.${c.reset}`);
+    console.log(`${c.dim}   (Feedback collects low-confidence findings, i.e. likely false positives.)${c.reset}\n`);
+    return;
+  }
+
+  // Capture each reportable finding locally (full, reviewable) + build its URL.
+  const feedbackDir = resolve(projectDir, '.docguard', 'feedback');
+  const items = reportable.map((f) => {
+    const id = shortId(`${f.code}|${f.location || f.message}`);
+    const { url, title } = buildIssueUrl(f);
+    const fileName = `${(f.code || 'finding').toLowerCase()}-${id}.json`;
+    const filePath = resolve(feedbackDir, fileName);
+    return { finding: f, id, url, title, fileName, filePath };
+  });
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      version: CLI_VERSION,
+      reportable: items.map((it) => ({ code: it.finding.code, location: it.finding.location, url: it.url, file: `.docguard/feedback/${it.fileName}` })),
+    }, null, 2));
+    // Still write the local records so the JSON path is not a dead end.
+  }
+
+  let wrote = 0;
+  for (const it of items) {
+    try {
+      if (!existsSync(feedbackDir)) mkdirSync(feedbackDir, { recursive: true });
+      writeFileSync(it.filePath, JSON.stringify({
+        capturedBy: `docguard feedback (v${CLI_VERSION})`,
+        finding: it.finding,
+        issueUrl: it.url,
+      }, null, 2) + '\n', 'utf-8');
+      wrote++;
+    } catch { /* best-effort local capture */ }
+  }
+
+  if (isJson) return;
+
+  console.log(`${c.bold}📮 DocGuard Feedback${c.reset}`);
+  console.log(`${c.dim}   ${items.length} uncertain finding(s) — likely false positives. Saved locally to ${c.cyan}.docguard/feedback/${c.reset}\n`);
+
+  for (const it of items) {
+    const f = it.finding;
+    console.log(`  ${c.yellow}[${f.code}]${c.reset} ${f.message}`);
+    if (f.suggestion && f.suggestion.pragma) {
+      console.log(`     ${c.dim}Suppress locally instead: ${f.suggestion.pragma}${c.reset}`);
+    }
+    console.log(`     ${c.dim}Report (1 click, prefilled, redacted):${c.reset}`);
+    console.log(`     ${c.cyan}${it.url}${c.reset}`);
+    console.log(`     ${c.dim}Local copy: .docguard/feedback/${it.fileName}${c.reset}\n`);
+  }
+
+  console.log(`${c.dim}These reports help DocGuard stop flagging the same false positive in a future release.${c.reset}`);
+  console.log(`${c.dim}Nothing is sent automatically — open a link only if you want to.${c.reset}\n`);
+}

package/cli/commands/guard.mjs

@@ -180,6 +180,27 @@ export function classifyResult(result) {
   return { status, quality };
 }
 
+/**
+ * v0.27: the list of issues to render for a validator. Prefers structured
+ * findings (code + confidence + suggestion) when present; otherwise maps the
+ * legacy error/warning strings into the same shape so the renderer is uniform.
+ */
+function renderableItems(v) {
+  if (Array.isArray(v.findings) && v.findings.length > 0) {
+    return v.findings.map((f) => ({
+      severity: f.severity,
+      message: f.message,
+      code: f.code,
+      confidence: f.confidence,
+      suggestion: f.suggestion,
+    }));
+  }
+  return [
+    ...(v.errors || []).map((m) => ({ severity: 'error', message: m })),
+    ...(v.warnings || []).map((m) => ({ severity: 'warn', message: m })),
+  ];
+}
+
 export function runGuardInternal(projectDir, config) {
   const validators = config.validators || {};
   const results = [];
@@ -323,6 +344,15 @@ export function runGuardInternal(projectDir, config) {
   // what the user reads is what CI does.
   const overallStatus = effectiveErrors > 0 ? 'FAIL' : effectiveWarnings > 0 ? 'WARN' : 'PASS';
 
+  // v0.27: stable, LLM-addressable contract. `findings` is the flattened,
+  // structured view (those validators that emit it); `reportable` are the
+  // low-confidence ones the feedback loop offers to report; `nextStep` is the
+  // single machine hint so an agent in a hook never has to parse prose.
+  const allFindings = activeResults.flatMap((r) => (Array.isArray(r.findings) ? r.findings : []));
+  const reportable = allFindings.filter((f) => f.reportable);
+  const nextStep =
+    overallStatus === 'PASS' ? null : 'docguard diagnose';
+
   return {
     project: config.projectName,
     profile: config.profile || 'standard',
@@ -331,6 +361,9 @@ export function runGuardInternal(projectDir, config) {
     total: totalChecks,
     errors: totalErrors,
     warnings: totalWarnings,
+    findings: allFindings,
+    reportable,
+    nextStep,
     // v0.5: severity-aware counts for exit-code logic. The display still uses
     // the raw counts above so users see every warning, but CI only fails on
     // things they've marked as high-severity.
@@ -473,14 +506,26 @@ export function runGuard(projectDir, config, flags) {
     // overall validator status — useful when a validator passes overall
     // (passed < total) without surfacing the specific failing checks.
     const show = flags.verbose || flags.showFailing;
-    if (show || v.status === 'fail') {
-      for (const err of v.errors) {
-        console.log(`     ${c.red}✗ ${err}${c.reset}`);
-      }
-    }
-    if (show || v.status === 'warn') {
-      for (const warn of v.warnings) {
-        console.log(`     ${c.yellow}⚠ ${warn}${c.reset}`);
+    const showErr = show || v.status === 'fail';
+    const showWarn = show || v.status === 'warn';
+    // v0.27: render from structured findings when the validator emits them
+    // (each issue carries a code, confidence, and a `→ suggestion`); otherwise
+    // fall back to the legacy error/warning strings. Identical gating.
+    for (const item of renderableItems(v)) {
+      if (item.severity === 'error' && !showErr) continue;
+      if (item.severity === 'warn' && !showWarn) continue;
+      const mark = item.severity === 'error' ? `${c.red}✗` : `${c.yellow}⚠`;
+      const codeTag = item.code ? `${c.dim}[${item.code}]${c.reset} ` : '';
+      const conf = item.confidence === 'low'
+        ? ` ${c.dim}(low confidence — possible false positive)${c.reset}` : '';
+      console.log(`     ${mark} ${codeTag}${item.message}${c.reset}${conf}`);
+      if (item.suggestion) {
+        console.log(`       ${c.cyan}→${c.reset} ${c.dim}${item.suggestion.text}${c.reset}`);
+        if (item.suggestion.command) {
+          console.log(`         ${c.cyan}${item.suggestion.command}${c.reset}`);
+        } else if (item.suggestion.pragma) {
+          console.log(`         ${c.dim}${item.suggestion.pragma}${c.reset}`);
+        }
       }
     }
     // If a validator reports passed < total but has no errors/warnings, surface
@@ -514,14 +559,31 @@ export function runGuard(projectDir, config, flags) {
     console.log(`  ${c.red}${c.bold}❌ FAIL${c.reset} ${c.red}— ${data.passed}/${data.total} passed, ${data.effectiveErrors} blocking issue(s)${warnSuffix}${c.reset}`);
   }
 
-  // Next step hint — always point to diagnose when issues exist
+  // ── Next steps — every run ends with a suggested action (v0.27) ──
+  // The field-report principle: whenever DocGuard calls out an issue it must
+  // suggest what to do next; on a clean run it points at the next workflow step
+  // rather than nagging. JSON consumers read this off the `nextStep`/`reportable`
+  // contract fields instead of this prose.
+  const agentMode = detectAgentMode(projectDir);
+  const skill = (name) => (agentMode === 'llm' ? `/docguard.${name}` : `docguard ${name}`);
+
   if (data.status !== 'PASS') {
-    const agentMode = detectAgentMode(projectDir);
-    if (agentMode === 'llm') {
-      console.log(`  ${c.dim}Use ${c.cyan}/docguard.diagnose${c.dim} to get AI fix prompts.${c.reset}`);
-    } else {
-      console.log(`  ${c.dim}Run ${c.cyan}docguard diagnose${c.dim} to get AI fix prompts.${c.reset}`);
-    }
+    console.log(`  ${c.dim}Next: run ${c.cyan}${skill('diagnose')}${c.dim} to get AI fix prompts that resolve the issues above.${c.reset}`);
+  } else {
+    console.log(`  ${c.dim}Next: ${c.cyan}${skill('score')}${c.dim} for your CDD maturity score, or commit with confidence.${c.reset}`);
+  }
+
+  // Low-confidence findings (possible false positives) → offer the local-first
+  // feedback path. Broader than secrets: anything DocGuard flagged uncertainly.
+  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}`);
+  }
+
+  // Read-only skills nudge (never writes — that's `init`'s job). If the agent
+  // has no /docguard.* commands installed yet, say how to get them.
+  if (agentMode === 'llm' && !existsSync(resolvePath(projectDir, '.agent', 'skills', 'docguard-guard'))) {
+    console.log(`  ${c.dim}💡 Install ${c.cyan}/docguard.*${c.dim} commands for your agent: ${c.cyan}docguard init${c.reset}`);
   }
 
   // Badge snippet

package/cli/commands/score.mjs

@@ -10,6 +10,70 @@ import { c, docHasSection } from '../shared.mjs';
 import { validateSecurity } from '../validators/security.mjs';
 import { runGuardInternal } from './guard.mjs';
 
+/**
+ * Detect whether the project configures a test runner (the "Check 3" of the
+ * testing score). Extracted as an exported seam so it's unit-testable without
+ * the full score pipeline.
+ *
+ * Recognises, in order: standalone config files; pytest config inside
+ * pyproject.toml / tox.ini; node:test via projectTypeConfig or scripts.test;
+ * a `scripts.test` that invokes a known runner; Vitest configured INSIDE
+ * vite.config.* (field report #3 — `vitest/config` import or a `test:` block);
+ * and runner configs in common workspace subdirs.
+ *
+ * @param {string} dir
+ * @param {object} config
+ * @returns {boolean}
+ */
+export function detectTestRunner(dir, config = {}) {
+  const testConfigFiles = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
+  if (testConfigFiles.some((f) => existsSync(resolve(dir, f)))) return true;
+
+  // Python: pytest config usually lives inside pyproject.toml ([tool.pytest.ini_options])
+  // or tox.ini ([pytest]) — not a standalone file.
+  for (const [file, marker] of [['pyproject.toml', /\[tool\.pytest/], ['tox.ini', /\[pytest\]/]]) {
+    const p = resolve(dir, file);
+    if (!existsSync(p)) continue;
+    try { if (marker.test(readFileSync(p, 'utf-8'))) return true; } catch { /* skip */ }
+  }
+
+  // node:test has no config file — recognize it via projectTypeConfig or package.json.
+  const ptc = config.projectTypeConfig || {};
+  if (ptc.testFramework === 'node:test') return true;
+  const pkgPath = resolve(dir, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      const testScript = pkg.scripts?.test || '';
+      if (testScript.includes('node --test') || testScript.includes('node:test')) return true;
+      // v0.27 (field report #3): a `scripts.test` that runs a known runner IS a
+      // configured test runner, even without a standalone config file.
+      if (/\b(vitest|jest|mocha|ava|playwright|cypress|pytest)\b/.test(testScript)) return true;
+    } catch { /* skip */ }
+  }
+
+  // v0.27 (field report #3): Vitest configured INSIDE vite.config.* rather than a
+  // standalone vitest.config (`vitest/config` import + a `test:` block).
+  for (const f of ['vite.config.ts', 'vite.config.js', 'vite.config.mts', 'vite.config.mjs']) {
+    const p = resolve(dir, f);
+    if (!existsSync(p)) continue;
+    try {
+      const src = readFileSync(p, 'utf-8');
+      if (/vitest\/config/.test(src) || /^\s*test\s*:/m.test(src)) return true;
+    } catch { /* skip */ }
+  }
+
+  // Workspace subdirs: a runner config one level down still configures the project.
+  const subConfigs = ['vitest.config.ts', 'vitest.config.js', 'jest.config.ts', 'jest.config.js', 'vite.config.ts'];
+  for (const sub of ['backend', 'frontend', 'server', 'client', 'app', 'web', 'api']) {
+    for (const f of subConfigs) {
+      if (existsSync(resolve(dir, sub, f))) return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * v0.18-P3: map score categories to the validator keys that contribute.
  * One category can roll up multiple validators (e.g. "environment" pulls
@@ -585,38 +649,7 @@ function calcTestingScore(dir, config) {
   else failures.push({ issue: 'TEST-SPEC.md missing', fixCmd: 'docguard fix --doc test-spec' });
 
   // ── Check 3: Test config or built-in runner (15 pts) ──
-  const testConfigFiles = ['jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js', 'pytest.ini', 'setup.cfg', '.mocharc.yml'];
-  let hasTestRunner = testConfigFiles.some(f => existsSync(resolve(dir, f)));
-
-  // Python: pytest config usually lives inside pyproject.toml ([tool.pytest.ini_options])
-  // or tox.ini ([pytest]) — not a standalone file. Detect those too, so a uv/pytest
-  // project isn't told to "add a test runner" it already configured (field report, Issue B).
-  if (!hasTestRunner) {
-    for (const [file, marker] of [['pyproject.toml', /\[tool\.pytest/], ['tox.ini', /\[pytest\]/]]) {
-      const p = resolve(dir, file);
-      if (!existsSync(p)) continue;
-      try { if (marker.test(readFileSync(p, 'utf-8'))) { hasTestRunner = true; break; } } catch { /* skip */ }
-    }
-  }
-
-  // node:test has no config file — recognize it via projectTypeConfig or package.json.
-  if (!hasTestRunner) {
-    const ptc = config.projectTypeConfig || {};
-    if (ptc.testFramework === 'node:test') {
-      hasTestRunner = true;
-    } else {
-      const pkgPath = resolve(dir, 'package.json');
-      if (existsSync(pkgPath)) {
-        try {
-          const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-          const testScript = pkg.scripts?.test || '';
-          if (testScript.includes('node --test') || testScript.includes('node:test')) hasTestRunner = true;
-        } catch { /* skip */ }
-      }
-    }
-  }
-
-  if (hasTestRunner) score += 15;
+  if (detectTestRunner(dir, config)) score += 15;
   else failures.push({ issue: 'no test runner config detected (jest/vitest/pytest/node:test)' });
 
   // ── Check 4: CI test step (15 pts) ──

package/cli/docguard.mjs

@@ -43,6 +43,7 @@ import { runSetup } from './commands/setup.mjs';
 import { runUpgrade } from './commands/upgrade.mjs';
 import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
+import { runFeedback } from './commands/feedback.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
@@ -85,7 +86,8 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}fix${c.reset}        Generate AI fix instructions for specific docs
   ${c.green}generate${c.reset}   Reverse-engineer canonical docs from existing code (${c.cyan}--plan${c.reset} for AI scan)
   ${c.green}agent${c.reset}      One-shot agent task graph — ordered tasks, pre-filled code-truth, per-task verify (${c.cyan}--format json${c.reset})
-  ${c.green}explain${c.reset}    Explain a validator key or warning text
+  ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
+  ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
   ${c.green}memory${c.reset}     Show what DocGuard remembers (${c.cyan}--diff${c.reset} drills into drift)
   ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
@@ -279,6 +281,12 @@ const COMMAND_HELP = {
     flags: [['--diff', 'Drill into drift between memory and code']],
     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'],
+  },
 };
 
 function printCommandHelp(command) {
@@ -507,6 +515,9 @@ async function main() {
   const READ_ONLY_COMMANDS = new Set([
     'guard', 'audit', 'score', 'diff', 'impact',
     'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent',
+    // feedback only writes its own .docguard/feedback/ — it must NOT scaffold
+    // skills or touch source, so it's gated out of ensureSkills like the rest.
+    'feedback',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -646,6 +657,12 @@ async function main() {
     case 'explain':
       runExplain(projectDir, config, flags);
       break;
+    case 'feedback':
+      // v0.27 (field report #3 / LLM feedback loop): collect low-confidence
+      // findings (likely false positives) → local record + 1-click prefilled,
+      // redacted, capped GitHub issue URL. Opt-in; nothing filed automatically.
+      runFeedback(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;

package/cli/findings.mjs

@@ -0,0 +1,194 @@
+/**
+ * Findings — the structured, LLM-addressable result unit (v0.27).
+ *
+ * Background (LLM field report #3): DocGuard's whole job is to tell an agent
+ * what to do NEXT. A free-text `errors`/`warnings` string can't carry a stable
+ * code (for `explain <CODE>` + inline suppression), a confidence (the signal
+ * the false-positive feedback loop runs on), or a machine-readable suggested
+ * action. A Finding carries all three.
+ *
+ * The migration is INCREMENTAL and BACKWARD-COMPATIBLE. A validator that opts in
+ * builds `Finding[]` and returns `resultFromFindings(...)`, which still emits the
+ * exact `{ errors, warnings, passed, total }` shape every existing consumer
+ * (guard counts + exit code, diagnose, score, ci, `--format json`) already reads
+ * — PLUS a `findings` array that guard renders richly (each issue gets its
+ * `→ suggestion`). Validators that haven't migrated keep returning their
+ * hand-built results and render exactly as before. Nothing regresses.
+ *
+ * Zero npm dependencies — pure Node.js built-ins.
+ *
+ * @typedef {Object} Suggestion
+ * @property {'fix'|'suppress'|'review'|'report'} kind
+ * @property {string}  text             One concise line: what to do next.
+ * @property {string} [command]         Optional CLI/skill command to run.
+ * @property {string} [pragma]          Optional inline suppression snippet.
+ *
+ * @typedef {Object} Finding
+ * @property {string}      code          Stable code, e.g. 'SEC001' (see CODES).
+ * @property {string}      validator     Owning validator key.
+ * @property {'error'|'warn'} severity
+ * @property {'high'|'low'} confidence   'low' = candidate false positive.
+ * @property {string}      message       Concise, NO ansi colour.
+ * @property {string|null} location      'path:line' or 'path'.
+ * @property {Suggestion|null} suggestion
+ * @property {boolean}     reportable    Surface in `docguard feedback`.
+ * @property {string|null} redactedContext  Safe-to-share context for a report.
+ */
+
+/**
+ * Stable finding-code registry. `docguard explain <CODE>` reads this, and
+ * inline `// docguard:ignore <CODE>` keys off it. Keep codes append-only — a
+ * published code is a public surface we don't renumber.
+ */
+export const CODES = {
+  SEC001: {
+    validator: 'security',
+    title: 'Hardcoded password',
+    help: 'A `password`/`passwd`/`pwd` assignment with a quoted literal value (8+ chars). If the value is natural-language UI copy or a validation message — not a credential — this is a false positive: DocGuard now flags those low-confidence, but you can suppress inline.',
+    suppress: '// docguard:ignore SEC001 — UI copy, not a credential',
+  },
+  SEC002: {
+    validator: 'security',
+    title: 'Hardcoded API key',
+    help: 'An `api_key`/`apikey` assignment with a quoted literal value (16+ chars). Move it to an environment variable and read it via `process.env`.',
+    suppress: '// docguard:ignore SEC002 — sample value in fixture',
+  },
+  SEC003: {
+    validator: 'security',
+    title: 'Hardcoded secret key',
+    help: 'A `secret_key`/`secretkey` assignment with a quoted literal value (16+ chars). Move it to an environment variable.',
+    suppress: '// docguard:ignore SEC003 — reason',
+  },
+  SEC004: {
+    validator: 'security',
+    title: 'Hardcoded access token',
+    help: 'An `access_token`/`accesstoken` assignment with a quoted literal value (16+ chars). Move it to an environment variable.',
+    suppress: '// docguard:ignore SEC004 — reason',
+  },
+  SEC005: {
+    validator: 'security',
+    title: 'AWS Access Key ID',
+    help: 'A string matching the AWS Access Key ID format (AKIA…). Rotate it immediately if real, and move credentials to the AWS credential chain / environment.',
+    suppress: '// docguard:ignore SEC005 — documented example key',
+  },
+  SEC006: {
+    validator: 'security',
+    title: 'API secret key (Stripe/OpenAI pattern)',
+    help: 'A string matching a live/test secret-key format (sk-…, sk_live_…). Rotate it if real and move it to an environment variable.',
+    suppress: '// docguard:ignore SEC006 — reason',
+  },
+  SEC010: {
+    validator: 'security',
+    title: '.env not in .gitignore',
+    help: 'No `.env` entry was found in .gitignore, so a local `.env` could be committed. Add `.env` (and `.env.local`) to .gitignore.',
+    suppress: null,
+  },
+  SEC011: {
+    validator: 'security',
+    title: 'No source files scanned for secrets',
+    help: 'The secret scan matched zero source files — usually a too-broad ignore config or a wrong sourceRoot. A scan that checks nothing is a dangerous false ✅.',
+    suppress: null,
+  },
+};
+
+/**
+ * Build a Finding with sane defaults. `reportable` defaults to true for
+ * low-confidence findings — low confidence IS the feedback signal.
+ *
+ * @param {Partial<Finding>} f
+ * @returns {Finding}
+ */
+export function mkFinding(f) {
+  const severity = f.severity === 'error' ? 'error' : 'warn';
+  const confidence = f.confidence === 'low' ? 'low' : 'high';
+  return {
+    code: f.code || null,
+    validator: f.validator || null,
+    severity,
+    confidence,
+    message: f.message || '',
+    location: f.location || null,
+    suggestion: f.suggestion || null,
+    reportable: f.reportable === true || confidence === 'low',
+    redactedContext: f.redactedContext || null,
+  };
+}
+
+/**
+ * Derive the legacy `{ errors, warnings, passed, total }` result from a list of
+ * findings, keeping `findings` attached for the rich renderer. ONE source of
+ * truth — the strings guard counts and the findings guard renders can never
+ * disagree because they're computed from the same array.
+ *
+ * @param {Finding[]} findings
+ * @param {{passed?:number, total?:number, applicable?:boolean}} [opts]
+ */
+export function resultFromFindings(findings, opts = {}) {
+  const errors = [];
+  const warnings = [];
+  for (const f of findings) {
+    if (f.severity === 'error') errors.push(f.message);
+    else warnings.push(f.message);
+  }
+  const res = {
+    errors,
+    warnings,
+    passed: opts.passed || 0,
+    total: opts.total != null ? opts.total : 0,
+    findings,
+  };
+  if (opts.applicable !== undefined) res.applicable = opts.applicable;
+  return res;
+}
+
+/**
+ * Does an inline `docguard:ignore` pragma in `text` suppress finding `code`?
+ *
+ * Accepted forms (mirrors the ergonomics of eslint-disable / ruff `# noqa`):
+ *   docguard:ignore                 → suppresses ANY code on the line
+ *   docguard:ignore SEC001          → suppresses exactly SEC001
+ *   docguard:ignore SEC001,DQ002    → comma list
+ *   docguard:ignore SEC*            → prefix wildcard
+ *   docguard:ignore all             → suppresses any code
+ *   docguard:ignore-secret          → convenience alias for any SEC* code
+ *
+ * @param {string} text
+ * @param {string} code
+ * @returns {boolean}
+ */
+export function suppressesCode(text, code) {
+  if (!text || !code) return false;
+  const m = text.match(/docguard:ignore(-secret)?\b[ \t]*([A-Za-z0-9_,*-]+)?/i);
+  if (!m) return false;
+  if (m[1]) return /^SEC/i.test(code);            // ignore-secret alias
+  const arg = (m[2] || '').trim();
+  if (!arg) return true;                           // bare ignore → any code
+  return arg.split(',').map((s) => s.trim()).some((tok) => {
+    if (!tok) return false;
+    if (tok.toLowerCase() === 'all') return true;
+    if (tok.endsWith('*')) return code.toUpperCase().startsWith(tok.slice(0, -1).toUpperCase());
+    return tok.toUpperCase() === code.toUpperCase();
+  });
+}
+
+/**
+ * Source-line suppression: an ignore pragma counts if it's on the flagged line
+ * OR the line directly above it (so a comment can sit above the offending
+ * statement, the common style for non-trailing-comment languages).
+ */
+export function lineSuppresses(code, line, prevLine = '') {
+  return suppressesCode(line, code) || suppressesCode(prevLine, code);
+}
+
+/**
+ * Flatten a one-line, colour-free rendering of a suggestion — used by JSON
+ * consumers, diagnose, and the feedback body. Guard does its own coloured
+ * rendering and does not use this.
+ */
+export function suggestionLine(s) {
+  if (!s) return '';
+  let out = s.text || '';
+  if (s.command) out += `  →  ${s.command}`;
+  else if (s.pragma) out += `  →  ${s.pragma}`;
+  return out;
+}

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/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.27.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.27.0
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.25.0 -->
+<!-- docguard:version: 0.27.0 -->
 
 # DocGuard Fix Skill
 

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

@@ -7,10 +7,10 @@ description: Run DocGuard guard validation against Canonical-Driven Development
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.25.0
+  version: 0.27.0
   source: extensions/spec-kit-docguard/skills/docguard-guard
 ---
-<!-- docguard:version: 0.25.0 -->
+<!-- docguard:version: 0.27.0 -->
 
 # DocGuard Guard Skill
 

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

@@ -6,10 +6,10 @@ description: Cross-document consistency analysis and quality assessment. Perform
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.25.0
+  version: 0.27.0
   source: extensions/spec-kit-docguard/skills/docguard-review
 ---
-<!-- docguard:version: 0.25.0 -->
+<!-- docguard:version: 0.27.0 -->
 
 # DocGuard Review Skill
 

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

@@ -6,10 +6,10 @@ description: CDD maturity assessment with category-aware improvement roadmap. Ru
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.25.0
+  version: 0.27.0
   source: extensions/spec-kit-docguard/skills/docguard-score
 ---
-<!-- docguard:version: 0.25.0 -->
+<!-- docguard:version: 0.27.0 -->
 
 # DocGuard Score Skill
 

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

@@ -4,10 +4,10 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.25.0
+  version: 0.27.0
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
-<!-- docguard:version: 0.25.0 -->
+<!-- docguard:version: 0.27.0 -->
 
 # DocGuard Sync Skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docguard-cli",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "The enforcement tool for Canonical-Driven Development (CDD). Audit, generate, and guard your project documentation.",
   "type": "module",
   "bin": {