docguard-cli 0.25.1 → 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"]
@@ -128,6 +128,8 @@ See [CHANGELOG.md](CHANGELOG.md) for the full history.
 
 ## ⚡ Quick Start
 
+> **Package naming:** this repo is `raccioly/docguard`; the published package is **`docguard-cli`** on both [npm](https://www.npmjs.com/package/docguard-cli) and [PyPI](https://pypi.org/project/docguard-cli/); the installed command is `docguard`. Same project — the `-cli` suffix is just the registry name. The package runs **no install scripts**, so `npm i -g docguard-cli --ignore-scripts` is equivalent.
+
 ### Node.js (npm)
 
 ```bash
@@ -248,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:
 
@@ -270,7 +272,9 @@ DocGuard ships **14 commands** (the "Daily 5" + 9 situational tools, including t
 | `fix --write` | Apply deterministic fixes (no AI — version bumps, counts, anchors, sections) |
 | `fix --history` | Audit log of every mechanical fix applied (from `.docguard/fixed.json`) |
 | `generate` | Reverse-engineer docs from existing codebase (`--plan` for AI scan) |
-| `explain <warning>` | Paste any warning — get the validator's docstring + fix path |
+| `agent` | One-shot agent task graph — ordered, pre-filled code-truth, per-task verify (`--format json`) |
+| `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/agent.mjs

@@ -0,0 +1,135 @@
+/**
+ * `docguard agent` — the one-shot agent task graph.
+ *
+ * Field report §2: an LLM told "run docguard and fix the docs" had to drive ~10
+ * manual round-trips (guard → init → config → generate → hand-write 7 docs →
+ * guard → fix FPs → …). This command collapses that into a SINGLE ordered,
+ * dependency-aware, self-contained task stream an agent executes without extra
+ * discovery:
+ *   - code-truth tasks ship PRE-FILLED content (insert as-is; only `<!-- … -->`
+ *     placeholders need values),
+ *   - human-judgment tasks carry the instruction + grounding facts,
+ *   - every task has an acceptance/verify command so the agent self-checks in
+ *     isolation instead of re-running the whole suite and diffing,
+ *   - phases impose order: config → canonical-docs → verify,
+ *   - confidence is propagated (code-truth = high; prose = requires-human), and
+ *     anything the profile suppressed surfaces as a note, never a committed guess.
+ *
+ * Read-only: it emits the plan, it never writes. A compact human summary by
+ * default; `--format json` emits the full machine task graph (the agent-
+ * executable artifact) — mirroring `generate --plan` / `generate --plan
+ * --format json`.
+ */
+
+import { buildMemoryPlan } from '../scanners/memory-plan.mjs';
+import { c } from '../shared.mjs';
+
+const PHASES = ['config', 'canonical-docs', 'verify'];
+
+function docSlug(path) {
+  return path.replace(/^docs-(?:canonical|implementation)\//, '').replace(/\.md$/, '').toLowerCase();
+}
+
+/**
+ * Transform a memory plan into the ordered agent task graph. Pure — no I/O — so
+ * it is unit-testable and reused by both the command and `generate`.
+ */
+export function buildAgentTaskGraph(projectDir, config, plan) {
+  const profileName = config.profile || 'standard';
+  const tasks = [];
+
+  // Phase 1 — config: make the project model explicit BEFORE any doc is written.
+  // (The agent learned this ordering by trial in the field report; encode it.)
+  tasks.push({
+    id: 'config.setup',
+    phase: 'config',
+    file: '.docguard.json',
+    kind: 'human-judgment',
+    instruction: `Ensure .docguard.json exists and is correct: run \`docguard init --profile ${profileName}\` if it is absent. Confirm projectName is "${config.projectName}" and profile is "${profileName}".`,
+    grounding: { projectName: config.projectName, profile: profileName, kind: plan.profile.kind, languages: plan.profile.languages },
+    prefilled: null,
+    acceptance: { verify: 'docguard guard --format json', expect: '.docguard.json present and the config validator passes' },
+    confidence: 'high',
+  });
+
+  // Phase 2 — canonical-docs: one task per section. Section order from the plan
+  // already puts code-truth before prose within each doc, so insert-then-write.
+  for (const doc of plan.docs) {
+    const slug = docSlug(doc.path);
+    for (const sec of doc.sections) {
+      const isCode = sec.source === 'code';
+      tasks.push({
+        id: `${slug}.${sec.id}`,
+        phase: 'canonical-docs',
+        file: doc.path,
+        section: sec.id,
+        kind: isCode ? 'code-truth' : 'human-judgment',
+        prefilled: isCode ? sec.body : null,
+        instruction: isCode
+          ? `Insert the pre-filled "${sec.id}" content into ${doc.path} verbatim — it is extracted from your code. Only fill any \`<!-- … -->\` placeholders.`
+          : sec.task,
+        grounding: sec.grounding || null,
+        acceptance: { verify: 'docguard guard --format json', expect: `no missing/stale finding for ${doc.path}` },
+        confidence: isCode ? 'high' : 'requires-human',
+      });
+    }
+  }
+
+  // Phase 3 — verify: the agent's own gate. Self-check, don't assume.
+  tasks.push({
+    id: 'verify.guard',
+    phase: 'verify',
+    file: null,
+    kind: 'verify',
+    instruction: 'Run `docguard guard --format json`. Resolve every error and warning, then re-run until clean. Run `docguard score` to confirm the maturity grade.',
+    prefilled: null,
+    grounding: null,
+    acceptance: { verify: 'docguard guard --format json', expect: '0 errors' },
+    confidence: 'high',
+  });
+
+  return {
+    project: config.projectName,
+    profile: { name: profileName, kind: plan.profile.kind, languages: plan.profile.languages, frameworks: plan.profile.frameworks },
+    order: PHASES,
+    counts: {
+      tasks: tasks.length,
+      codeTruth: tasks.filter(t => t.kind === 'code-truth').length,
+      humanJudgment: tasks.filter(t => t.kind === 'human-judgment').length,
+    },
+    tasks,
+    notes: plan.notes || [],
+  };
+}
+
+export function runAgent(projectDir, config, flags) {
+  // Allow `--profile <name>` to preview a profile's plan without having to run
+  // `init` first (the field-report agent had no config yet on its first call).
+  const cfg = flags.profile ? { ...config, profile: flags.profile } : config;
+  const plan = buildMemoryPlan(projectDir, cfg);
+  const graph = buildAgentTaskGraph(projectDir, cfg, plan);
+
+  if (flags.format === 'json') {
+    // The agent-executable artifact.
+    console.log(JSON.stringify({ ...graph, timestamp: new Date().toISOString() }, null, 2));
+    return;
+  }
+
+  // Default: a compact human summary of the same graph.
+  {
+    console.log(`${c.bold}🤖 DocGuard Agent Task Graph — ${graph.project}${c.reset}`);
+    console.log(`${c.dim}   profile: ${graph.profile.name} · kind: ${graph.profile.kind} · ${graph.counts.tasks} tasks (${graph.counts.codeTruth} code-truth, ${graph.counts.humanJudgment} human)${c.reset}\n`);
+    for (const phase of graph.order) {
+      const inPhase = graph.tasks.filter(t => t.phase === phase);
+      if (!inPhase.length) continue;
+      console.log(`  ${c.bold}▸ ${phase}${c.reset}`);
+      for (const t of inPhase) {
+        const tag = t.kind === 'code-truth' ? `${c.green}[code]${c.reset} `
+          : t.kind === 'verify' ? `${c.cyan}[verify]${c.reset}` : `${c.yellow}[human]${c.reset}`;
+        console.log(`    ${tag} ${c.bold}${t.id}${c.reset}${t.file ? ` ${c.dim}→ ${t.file}${c.reset}` : ''}`);
+      }
+    }
+    for (const note of graph.notes) console.log(`  ${c.yellow}ℹ️  ${note}${c.reset}`);
+    console.log(`\n  ${c.dim}Run with --format json for the full machine-readable task stream.${c.reset}`);
+  }
+}

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/generate.mjs

@@ -164,6 +164,8 @@ function surfaceConfidence(kind) {
  * inserted as agent-task placeholders), respecting human prose via markers.
  */
 export function runGeneratePlan(projectDir, config, flags) {
+  // `--profile <name>` previews a profile's doc set without needing `init` first.
+  if (flags.profile) config = { ...config, profile: flags.profile };
   const plan = buildMemoryPlan(projectDir, config);
 
   if (flags.format === 'json') {
@@ -181,6 +183,8 @@ export function runGeneratePlan(projectDir, config, flags) {
         entities: plan.surface.entities.length,
         screens: plan.surface.screens.length,
         components: plan.surface.components.length,
+        modules: plan.surface.modules.length,
+        tests: { files: plan.surface.tests.totalFiles, cases: plan.surface.tests.totalCases },
         envVars: plan.surface.envVars.length,
         confidence: surfaceConfidence(plan.profile.kind),
       },
@@ -191,6 +195,7 @@ export function runGeneratePlan(projectDir, config, flags) {
           : { id: s.id, source: 'human', task: s.task, grounding: s.grounding }),
       })),
       agentTasks: plan.agentTasks,
+      notes: plan.notes || [],
       timestamp: new Date().toISOString(),
     }, null, 2));
     return;
@@ -225,6 +230,9 @@ export function runGeneratePlan(projectDir, config, flags) {
     if (registered > 0) {
       console.log(`  ${c.dim}Registered ${registered} canonical doc(s) in .docguard.json requiredFiles.${c.reset}`);
     }
+    for (const note of plan.notes || []) {
+      console.log(`  ${c.yellow}ℹ️  ${note}${c.reset}`);
+    }
     console.log(`  ${c.dim}Now run your AI agent (/docguard.fix) to write the prose sections, then ${c.cyan}docguard guard${c.dim}.${c.reset}\n`);
     return;
   }
@@ -232,7 +240,7 @@ export function runGeneratePlan(projectDir, config, flags) {
   // Text summary.
   console.log(`${c.bold}🔮 DocGuard Generate Plan — ${config.projectName}${c.reset}`);
   console.log(`${c.dim}   ${plan.profile.polyglot ? 'Polyglot' : 'Single-language'}: ${plan.profile.languages.join(', ')} | frameworks: ${plan.profile.frameworks.join(', ') || '—'} | kind: ${plan.profile.kind}${c.reset}\n`);
-  console.log(`  ${c.bold}Code-truth surface:${c.reset} ${plan.surface.endpoints.length} endpoints · ${plan.surface.entities.length} entities · ${plan.surface.screens.length} screens · ${plan.surface.components.length} components · ${plan.surface.envVars.length} env vars\n`);
+  console.log(`  ${c.bold}Code-truth surface:${c.reset} ${plan.surface.modules.length} modules · ${plan.surface.tests.totalFiles} test files (${plan.surface.tests.totalCases} cases) · ${plan.surface.endpoints.length} endpoints · ${plan.surface.entities.length} entities · ${plan.surface.screens.length} screens · ${plan.surface.envVars.length} env vars\n`);
   const webSurface = plan.surface.endpoints.length + plan.surface.entities.length + plan.surface.screens.length + plan.surface.components.length;
   if (surfaceConfidence(plan.profile.kind) === 'low' && webSurface > 0) {
     console.log(`  ${c.yellow}⚠️  Low-confidence surface:${c.reset} ${c.dim}this looks like a ${plan.profile.kind} (not a web app), so the HTTP/SDK/route surface above may be pattern-matches in your OWN source — not real usage. Verify before documenting; pin any corrected code section with ${c.cyan}pinned="reason"${c.dim}.${c.reset}\n`);
@@ -243,6 +251,9 @@ export function runGeneratePlan(projectDir, config, flags) {
     const prose = d.sections.filter(s => s.source === 'human').length;
     console.log(`    ${c.cyan}${d.path}${c.reset} ${c.dim}(${code} code section(s), ${prose} agent task(s))${c.reset}`);
   }
+  for (const note of plan.notes || []) {
+    console.log(`  ${c.yellow}ℹ️  ${note}${c.reset}`);
+  }
   console.log(`\n  ${c.bold}🤖 Agent tasks (${plan.agentTasks.length}):${c.reset} ${c.dim}prose the AI must write, grounded in scanned facts.${c.reset}`);
   for (const t of plan.agentTasks) {
     console.log(`    ${c.dim}• [${t.doc} → ${t.sectionId}] ${t.instruction}${c.reset}`);

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