docguard-cli 0.26.0 → 0.28.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 (17)"]
     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 **17 commands** (the "Daily 5" + 12 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,9 @@ 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 |
+| `verify --semantic` | Extract documented numbers/limits/enums (retention days, rate limits, GSI/role counts, status enums) as a task list for an agent to check against code — the semantic-drift class regex/AST can't see |
+| `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
@@ -110,13 +111,14 @@ const EXPLAINERS = {
   },
   freshness: {
     title: 'Freshness — docs updated alongside code',
-    what: 'For each canonical doc, counts code commits since the doc\'s last commit. >10 commits = stale.',
+    what: 'For each canonical doc it picks a "last updated" date by PRECEDENCE, then counts code commits since (>10 = stale): (1) an explicit `<!-- docguard:last-reviewed YYYY-MM-DD -->` marker — a human review signal git cannot see, so it WINS; (2) `<!-- docguard:status approved -->`; (3) the git commit date; (4) for an uncommitted file with no marker, it asks you to commit OR add a marker. CHANGELOG.md follows the SAME precedence — a marker satisfies it before any commit, which matters in a pre-commit edit/review loop. `docguard init` now stamps a `last-reviewed` marker into every canonical doc so freshness is marker-based and consistent from day one.',
     why:  'Docs drift silently. This validator surfaces the drift before it becomes invisible.',
     triggers: [
-      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose for accuracy.'],
+      ['code commits since last doc update', 'Run `docguard sync --write` to refresh code-truth sections, then review the prose and update (or add) the `<!-- docguard:last-reviewed YYYY-MM-DD -->` marker.'],
+      ['not yet committed to git', 'A canonical doc has no git history and no marker. Commit it, or add `<!-- docguard:last-reviewed YYYY-MM-DD -->` (or `<!-- docguard:status approved -->`) so freshness is satisfiable before the commit.'],
       ['DRIFT-LOG.md may be stale', 'DRIFT comments in code outpaced log entries. Add the entries.'],
     ],
-    example: 'ARCHITECTURE.md last committed within 10 code commits',
+    example: 'ARCHITECTURE.md carries `<!-- docguard:last-reviewed 2026-06-19 -->` (or was committed within 10 code commits)',
     standard: 'CDD principle: docs and code commit together',
   },
   traceability: {
@@ -133,12 +135,13 @@ const EXPLAINERS = {
     standard: 'ISO/IEC/IEEE 29148 (requirements traceability)',
   },
   apiSurface: {
-    title: 'API-Surface — endpoints in code match API-REFERENCE.md',
-    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs.',
-    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible.',
+    title: 'API-Surface — endpoints in code match API-REFERENCE.md (and the spec matches the routes)',
+    what: 'Compares routes scanned from code (Express, Next, FastAPI, Spring, etc.) against endpoints listed in API-REFERENCE.md and OpenAPI specs. When an OpenAPI spec exists it is the authoritative surface — so it ALSO diffs the spec against the actually-registered code routes, catching a spec that declares a phantom endpoint (the doc reconciles clean against a wrong spec otherwise). That spec-vs-route check is conservative: it only runs when code routes are actually scannable.',
+    why:  'Documented but missing endpoints are dead links. Endpoints in code that aren\'t documented are invisible. And a spec nobody implements is a lie the doc check can\'t see.',
     triggers: [
       ['documented but absent', 'API-REFERENCE.md lists an endpoint that scanRoutes() can\'t find. Remove or fix the doc; `fix --write` removes when marked.'],
       ['present but undocumented', 'A route exists in code but API-REFERENCE.md doesn\'t list it. Add it.'],
+      ['declares', 'The OpenAPI spec declares an endpoint that no Express/Fastify/etc. route registers in code — i.e. "declares METHOD /path but no route registers it". Either implement the route or remove the phantom endpoint from the spec (the API-REFERENCE doc reconciles clean against the spec, so this is the only check that catches it).'],
     ],
     example: 'GET /api/users in src/routes/users.ts AND in API-REFERENCE.md\'s Endpoints table',
     standard: 'OpenAPI 3.1',
@@ -292,7 +295,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 +422,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.
@@ -429,12 +462,17 @@ export function runGuard(projectDir, config, flags) {
 
   // ── JSON output ──
   if (flags.format === 'json') {
-    console.log(JSON.stringify(data, null, 2));
     // Use severity-aware effective counts for exit code; raw counts stay in the JSON
     // for display tools that want to show the full picture.
-    if (data.effectiveErrors > 0) process.exit(1);
-    if (data.effectiveWarnings > 0) process.exit(2);
-    process.exit(0);
+    const code = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
+    // v0.28: set exitCode + return instead of process.exit(). A large JSON
+    // payload (>~8 KB) written to a PIPE flushes asynchronously; an immediate
+    // process.exit() truncates it mid-string, so a CI consumer parsing stdout
+    // gets "Unterminated string in JSON" on exactly the big reports that matter.
+    // Returning lets Node drain stdout and exit naturally with process.exitCode.
+    process.exitCode = code;
+    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    return;
   }
 
   // ── Text output ──
@@ -473,14 +511,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 +564,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
@@ -645,7 +712,8 @@ export function runGuard(projectDir, config, flags) {
   }
 
   // v0.5: severity-aware exit codes (see runGuardInternal for the rollup).
-  if (data.effectiveErrors > 0) process.exit(1);
-  if (data.effectiveWarnings > 0) process.exit(2);
-  process.exit(0);
+  // v0.28: exitCode + return (not process.exit) so the buffered text output
+  // flushes to a pipe before the process exits — same truncation fix as the
+  // JSON path above.
+  process.exitCode = data.effectiveErrors > 0 ? 1 : data.effectiveWarnings > 0 ? 2 : 0;
 }

package/cli/commands/init.mjs

@@ -78,6 +78,20 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const TEMPLATES_DIR = resolve(__dirname, '../../templates');
 
+/**
+ * v0.28 (field report #11): inject a `<!-- docguard:last-reviewed DATE -->`
+ * marker right after the first H1, so a canonical doc has a freshness signal the
+ * Freshness validator reads directly (not git mtime). No-op if one is present.
+ */
+function stampLastReviewed(content, date) {
+  const marker = `<!-- docguard:last-reviewed ${date} -->`;
+  const lines = content.split('\n');
+  const h1 = lines.findIndex(l => /^#\s/.test(l));
+  if (h1 === -1) return `${marker}\n\n${content}`;
+  lines.splice(h1 + 1, 0, '', marker);
+  return lines.join('\n');
+}
+
 // ── Readline helper ──────────────────────────────────────────────────────
 
 function askQuestion(prompt) {
@@ -263,7 +277,15 @@ export async function runInit(projectDir, config, flags) {
     if (existsSync(templatePath)) {
       const content = readFileSync(templatePath, 'utf-8');
       const today = new Date().toISOString().split('T')[0];
-      const processed = content.replace(/YYYY-MM-DD/g, today);
+      let processed = content.replace(/YYYY-MM-DD/g, today);
+      // v0.28 (field report #11): every canonical doc must ship with a freshness
+      // marker so the Freshness validator is marker-based (consistent across docs,
+      // and satisfiable in a pre-commit review loop) rather than silently falling
+      // back to git mtime. Templates now all carry one; this is the belt-and-
+      // suspenders guarantee for any future template that forgets.
+      if (mapping.dest.startsWith('docs-canonical/') && !/docguard:last-reviewed/.test(processed)) {
+        processed = stampLastReviewed(processed, today);
+      }
       writeFileSync(destPath, processed, 'utf-8');
       created.push(mapping.dest);
       console.log(`  ${c.green}✅${c.reset} Created: ${c.cyan}${mapping.dest}${c.reset}`);

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) ──