docguard-cli 0.25.1 → 0.26.0

package/README.md

@@ -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
@@ -270,6 +272,7 @@ 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) |
+| `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 |
 | `memory` | Per-domain accuracy headline (endpoints / entities / env / tech) |
 | `memory --diff` | Drill into which specific claims don't match code |

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

@@ -12,11 +12,16 @@ import { existsSync, readFileSync } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { c, PROFILES, SEVERITY_LEVELS } from './shared.mjs';
 import { mergeIgnoreFile } from './shared-ignore.mjs';
+import { detectProjectName } from './scanners/project-type.mjs';
 
 export function loadConfig(projectDir) {
   const configPath = resolve(projectDir, '.docguard.json');
   const defaults = {
-    projectName: basename(projectDir),
+    // v0.26 (Bug #4): read the declared name from the root manifest
+    // (pyproject/package.json/Cargo/composer/go.mod) before falling back to the
+    // dir basename — otherwise a git-worktree slug becomes the project name.
+    // An explicit `projectName` in .docguard.json still wins via deepMerge.
+    projectName: detectProjectName(projectDir),
     // Legacy/unversioned fallback ONLY — the value a config is ASSUMED to be
     // when its file has no `version` field. NOT the current schema version
     // (that's CURRENT_SCHEMA_VERSION in shared.mjs, written by `init`). Kept low

package/cli/docguard.mjs

@@ -45,6 +45,7 @@ import { runImpact } from './commands/impact.mjs';
 import { runExplain } from './commands/explain.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
+import { runAgent } from './commands/agent.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -83,6 +84,7 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}diagnose${c.reset}   AI orchestrator — guard → emit fix prompts in one command
   ${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}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)
@@ -192,6 +194,15 @@ const COMMAND_HELP = {
     ],
     examples: ['docguard generate', 'docguard generate --plan', 'docguard generate --plan --write', 'docguard generate --plan --format json'],
   },
+  agent: {
+    summary: 'One-shot agent task graph: ordered, dependency-aware, with pre-filled code-truth + per-task verify.',
+    usage: 'docguard agent [--profile <name>] [--format json]',
+    flags: [
+      ['--format json', 'Machine-readable task graph (the agent-executable artifact)'],
+      ['--profile <name>', 'Preview a profile (cli/library/standard/…) without running init first'],
+    ],
+    examples: ['docguard agent', 'docguard agent --format json', 'docguard agent --profile cli --format json'],
+  },
   guard: {
     summary: 'Validate code against canonical docs (all validators).',
     usage: 'docguard guard [--format json] [--changed-only] [--fail-on-warning]',
@@ -474,16 +485,39 @@ async function main() {
   // .agent/.specify writes, which were a surprising side effect of a bare
   // `generate --plan` (and were already suppressed for `--plan --write`).
   const jsonMode = flags.format === 'json';
-  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan;
+  // `agent` emits a machine task graph (JSON by default) — it must be banner-
+  // free and side-effect-free like the other read-only commands.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent';
 
   if (!headless) printBanner();
 
   const config = loadConfig(projectDir);
 
+  // Commands that only READ and REPORT — they must never mutate the working
+  // tree. Scaffolding (ensureSkills → .agent/.specify, spawning `specify`)
+  // belongs to setup/init/generate and the `init --with` family, where the
+  // user is establishing or expanding their setup, not auditing it.
+  //
+  // v0.26 (field report Bug #3): a bare `docguard guard` used to run
+  // ensureSkills → auto-init Spec Kit → spawn `specify` and write ~9 files into
+  // the tree BEFORE printing results. Surprising for a *validate* command, and
+  // fatal for a read-only CI audit or a clean-tree precondition check. These
+  // commands are now exempt regardless of flags. (`audit` is the guard alias;
+  // `diff`/`impact` only read; `demo` runs against a throwaway fixture.)
+  const READ_ONLY_COMMANDS = new Set([
+    'guard', 'audit', 'score', 'diff', 'impact',
+    'diagnose', 'trace', 'explain', 'memory', 'demo', 'agent',
+  ]);
+
   // Silent auto-check: install skills/commands if missing. Skip entirely in
-  // headless modes where the user wants deterministic, parseable output and
-  // doesn't expect side effects on their AI-agent skill directories.
-  if (command !== 'setup' && command !== 'init' && !headless) {
+  // headless modes (deterministic, parseable output; no side effects expected)
+  // and for read-only commands (see above).
+  if (
+    command !== 'setup' &&
+    command !== 'init' &&
+    !READ_ONLY_COMMANDS.has(command) &&
+    !headless
+  ) {
     ensureSkills(projectDir, flags);
   }
 
@@ -566,6 +600,11 @@ async function main() {
     case 'generate':
       runGenerate(projectDir, config, flags);
       break;
+    case 'agent':
+      // v0.26 (field report §2): one-shot, dependency-ordered task graph with
+      // pre-filled code-truth + per-task verify. Read-only; JSON by default.
+      runAgent(projectDir, config, flags);
+      break;
     case 'hooks':
       await runInit(projectDir, config, { ...flags, with: ['hooks'], skipPrompts: true });
       break;

package/cli/scanners/inventory.mjs

@@ -0,0 +1,140 @@
+/**
+ * Inventory scanners — code-truth the generator PRE-FILLS instead of leaving
+ * empty placeholders.
+ *
+ * Field report §2/§5: `generate` markets "reverse-engineer docs from code" but
+ * shipped empty templates, so the agent hand-greps the structure that was right
+ * there in the code. These two extractors populate the `source:"code"` sections
+ * so the agent is left with only the genuine prose (the *why*):
+ *   - scanComponents:    top-level source modules → ARCHITECTURE Component Map
+ *   - scanTestInventory: test files + per-file case counts → TEST-SPEC inventory
+ *
+ * Language-agnostic, best-effort, zero NPM deps.
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { resolve, join, relative, extname } from 'node:path';
+import { resolveSourceRoots, readScannable } from '../shared-source.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, isNonProductDir } from '../shared-ignore.mjs';
+
+const CODE_EXT = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.rb', '.php', '.java', '.kt']);
+const toPosix = (p) => p.split(/[\\/]/).join('/');
+
+// ── Component map ─────────────────────────────────────────────────────────────
+
+// Descend through single-package wrappers (src/ → src/<pkg>/) so we list the
+// REAL modules, not just the wrapper folder. A wrapper is a dir whose only
+// non-ignored child is another dir (e.g. a Python `src/<pkg>/` layout).
+function componentRoot(root, config) {
+  let cur = root;
+  for (let depth = 0; depth < 3; depth++) {
+    let entries;
+    try { entries = readdirSync(cur, { withFileTypes: true }); } catch { break; }
+    const dirs = entries.filter(e => e.isDirectory() && !e.name.startsWith('.')
+      && !IGNORE_DIRS.has(e.name) && !isNonProductDir(e.name, config));
+    const codeFiles = entries.filter(e => e.isFile() && CODE_EXT.has(extname(e.name))
+      && !/^(index|main|mod|lib|__init__|__main__)\./.test(e.name));
+    if (dirs.length === 1 && codeFiles.length === 0) { cur = join(cur, dirs[0].name); continue; }
+    break;
+  }
+  return cur;
+}
+
+/**
+ * Top-level source modules under the project's (de-wrapped) source root(s).
+ * Each is a directory (a module) or a significant source file directly under
+ * the root. Non-product dirs (tests/fixtures/examples) and barrel/entry files
+ * are excluded. Capped to keep the table readable.
+ * @returns {Array<{ name: string, kind: 'module'|'file', path: string }>}
+ */
+export function scanComponents(projectDir, config = {}, limit = 30) {
+  const out = [];
+  const seen = new Set();
+  for (const root of resolveSourceRoots(projectDir, config)) {
+    const croot = componentRoot(root, config);
+    let entries;
+    try { entries = readdirSync(croot, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      let kind;
+      if (e.isDirectory()) {
+        if (IGNORE_DIRS.has(e.name) || isNonProductDir(e.name, config)) continue;
+        kind = 'module';
+      } else if (e.isFile() && CODE_EXT.has(extname(e.name))) {
+        if (/^(index|__init__)\./.test(e.name)) continue; // barrels/entry-init aren't components
+        kind = 'file';
+      } else continue;
+      const rel = toPosix(relative(projectDir, join(croot, e.name)));
+      if (seen.has(rel)) continue;
+      seen.add(rel);
+      out.push({ name: e.name, kind, path: rel });
+    }
+  }
+  out.sort((a, b) => (a.kind === b.kind ? a.path.localeCompare(b.path) : (a.kind === 'module' ? -1 : 1)));
+  return out.slice(0, limit);
+}
+
+// ── Test inventory ────────────────────────────────────────────────────────────
+
+// Test FILE conventions across ecosystems: JS *.test/*.spec, Python test_*.py /
+// *_test.py, Go *_test.go, Ruby *_spec.rb / *_test.rb.
+const TEST_FILE_RE = /(?:\.(?:test|spec)\.[cm]?[jt]sx?|(?:^|\/)test_[^/]*\.py|_test\.(?:py|go)|_spec\.rb|(?:^|\/)[^/]*_test\.rb)$/i;
+// Fixture/mock subdirs that sit INSIDE a test dir but aren't themselves tests.
+const FIXTURE_DIRS = new Set(['fixtures', '__fixtures__', 'testdata', 'test-fixtures', 'testfixtures', 'mocks', '__mocks__', 'snapshots', '__snapshots__']);
+const TEST_DIRS = ['tests', 'test', '__tests__', 'spec', 'e2e'];
+
+function countCases(content, ext) {
+  let re;
+  if (['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'].includes(ext)) re = /\b(?:it|test)\s*\(/g;
+  else if (ext === '.py') re = /^[ \t]*(?:async[ \t]+)?def[ \t]+test_/gm;
+  else if (ext === '.go') re = /^[ \t]*func[ \t]+Test[A-Z]/gm;
+  else if (ext === '.rs') re = /#\[(?:test|tokio::test)\]/g;
+  else if (ext === '.rb') re = /^[ \t]*(?:it|test|specify)\b/gm;
+  else return 0;
+  let n = 0;
+  while (re.exec(content) !== null) n++;
+  return n;
+}
+
+function walkTestFiles(dir, projectDir, acc) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || IGNORE_DIRS.has(e.name)) continue;
+    if (e.isDirectory()) {
+      if (FIXTURE_DIRS.has(e.name)) continue; // fixtures/mocks inside a test dir aren't tests
+      walkTestFiles(join(dir, e.name), projectDir, acc);
+    } else if (e.isFile() && CODE_EXT.has(extname(e.name))) {
+      const rel = toPosix(relative(projectDir, join(dir, e.name)));
+      if (TEST_FILE_RE.test(rel)) acc.add(rel);
+    }
+  }
+}
+
+/**
+ * Test files + per-file case counts. Walks the conventional test dirs (tests/,
+ * test/, __tests__, spec/, e2e/) plus each source root (co-located tests),
+ * skipping fixture/mock subdirs. Case counts are per-language (it()/test(),
+ * `def test_`, `func Test`, `#[test]`, …).
+ * @returns {{ files: Array<{file:string,cases:number}>, totalCases:number, totalFiles:number }}
+ */
+export function scanTestInventory(projectDir, config = {}) {
+  const root = resolve(projectDir);
+  const acc = new Set();
+  for (const td of TEST_DIRS) {
+    const d = join(root, td);
+    if (existsSync(d)) walkTestFiles(d, root, acc);
+  }
+  for (const sr of resolveSourceRoots(projectDir, config)) walkTestFiles(sr, root, acc);
+
+  const files = [];
+  let totalCases = 0;
+  for (const rel of acc) {
+    const content = readScannable(join(root, rel));
+    const cases = content === null ? 0 : countCases(content, extname(rel));
+    files.push({ file: rel, cases });
+    totalCases += cases;
+  }
+  files.sort((a, b) => b.cases - a.cases || a.file.localeCompare(b.file));
+  return { files, totalCases, totalFiles: files.length };
+}

package/cli/scanners/memory-plan.mjs

@@ -19,6 +19,8 @@ import { scanSchemasDeep } from './schemas.mjs';
 import { scanFrontend } from './frontend.mjs';
 import { grepEnvUsage } from '../shared-source.mjs';
 import { detectIntegrations } from './integrations.mjs';
+import { PROFILES } from '../shared.mjs';
+import { scanComponents, scanTestInventory } from './inventory.mjs';
 
 const md = {
   table(headers, rows) {
@@ -209,6 +211,9 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
         framework: null, stateLib: null, dataLib: null };
   const envVars = [...grepEnvUsage(projectDir, config)].sort();
   const integrations = detectIntegrations(projectDir, config);
+  // Pre-filled code-truth (field report §5): real source modules + test inventory.
+  const modules = scanComponents(projectDir, config);
+  const tests = scanTestInventory(projectDir, config);
 
   const surface = {
     profile,
@@ -224,8 +229,35 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     apiCalls: fe.apiCalls,
     i18n: fe.i18n,
     frontend: { framework: fe.framework, stateLib: fe.stateLib, dataLib: fe.dataLib },
+    modules,   // top-level source modules → ARCHITECTURE Component Map (pre-filled)
+    tests,     // { files:[{file,cases}], totalCases, totalFiles } → TEST-SPEC inventory
   };
 
+  // ── Profile gate (Bug #5) ──
+  // generate must respect the active COMPLIANCE profile, not just surface
+  // counts. For non-web profiles (cli/library) we only emit an optional
+  // web/UI/DB-shaped canonical doc when the profile explicitly requires it — so
+  // a CLI never gets API-REFERENCE/INTEGRATIONS just because the surface scan
+  // tripped on a stray HTTP call or SDK string. Other profiles
+  // (standard/enterprise/…) stay surface-driven.
+  const profileName = config.profile || 'standard';
+  const allowedCanonical = new Set(PROFILES[profileName]?.requiredFiles?.canonical || []);
+  const constrainedProfile = profileName === 'cli' || profileName === 'library';
+  const profileAllows = (docPath) => !constrainedProfile || allowedCanonical.has(docPath);
+
+  // Anti-false-green: when the profile suppresses a doc the surface WOULD have
+  // produced, say so — a web app mislabeled with the wrong --profile is still
+  // recoverable instead of silently under-documented.
+  const notes = [];
+  if (constrainedProfile) {
+    if (surface.endpoints.length > 0 && !allowedCanonical.has('docs-canonical/API-REFERENCE.md')) {
+      notes.push(`Detected ${surface.endpoints.length} endpoint(s) but the '${profileName}' profile omits API-REFERENCE.md — not generated. If this project genuinely exposes an HTTP API, re-run with --profile standard.`);
+    }
+    if (surface.integrations.length > 0 && !allowedCanonical.has('docs-canonical/INTEGRATIONS.md')) {
+      notes.push(`Detected ${surface.integrations.length} integration(s) but the '${profileName}' profile omits INTEGRATIONS.md — not generated.`);
+    }
+  }
+
   // ── Compose documents + sections (language/kind-aware) ──
   const docs = [];
   const agentTasks = [];
@@ -248,9 +280,24 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     sections.push(addTask('docs-canonical/ARCHITECTURE.md', 'overview',
       'Write a 2-3 sentence System Overview: what this project does and who uses it.',
       { languages: profile.languages, frameworks: profile.frameworks, kind: profile.kind }));
-    sections.push(addTask('docs-canonical/ARCHITECTURE.md', 'components',
-      'Describe the major components/modules and their responsibilities, using the real directories below.',
-      { ecosystems: profile.ecosystems.map(e => ({ dir: e.dir, language: e.language, framework: e.framework })) }));
+
+    // Component Map — PRE-FILLED from the real source layout (field report §5):
+    // the agent gets the module list for free and only annotates responsibilities.
+    if (surface.modules.length > 0) {
+      sections.push({
+        id: 'component-map',
+        source: 'code',
+        body: md.table(['Module', 'Kind', 'Responsibility'],
+          surface.modules.map(m => [`\`${m.path}\``, m.kind, '<!-- one-line responsibility -->'])),
+      });
+      sections.push(addTask('docs-canonical/ARCHITECTURE.md', 'components',
+        'Fill in a one-line responsibility for each module in the Component Map above (replace each `<!-- one-line responsibility -->`). Group related modules into layers if it aids understanding.',
+        { modules: surface.modules.map(m => m.path) }));
+    } else {
+      sections.push(addTask('docs-canonical/ARCHITECTURE.md', 'components',
+        'Describe the major components/modules and their responsibilities, using the real directories below.',
+        { ecosystems: profile.ecosystems.map(e => ({ dir: e.dir, language: e.language, framework: e.framework })) }));
+    }
 
     // Frontend modules (stores/hooks/contexts) — code-truth section when present.
     const feCounts = surface.stores.length + surface.hooks.length + surface.contexts.length;
@@ -269,8 +316,31 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     docs.push({ path: 'docs-canonical/ARCHITECTURE.md', sections });
   }
 
-  // API-REFERENCE — only if there's an API surface.
-  if (surface.endpoints.length > 0) {
+  // TEST-SPEC — always (a required canonical doc in every profile). The test
+  // INVENTORY is pre-filled from the real test files (field report §5); the
+  // agent writes only the coverage rules + the service→test mapping.
+  {
+    const ti = surface.tests;
+    const sections = [];
+    if (ti.totalFiles > 0) {
+      const header = `**${ti.totalFiles} test file(s)${ti.totalCases > 0 ? `, ${ti.totalCases} test case(s)` : ''}**`;
+      const rows = ti.files.map(t => [`\`${t.file}\``, t.cases > 0 ? String(t.cases) : '—']);
+      sections.push({
+        id: 'test-inventory',
+        source: 'code',
+        body: `${header}\n\n${md.table(['Test file', 'Cases'], rows)}`,
+      });
+    }
+    sections.push(addTask('docs-canonical/TEST-SPEC.md', 'coverage',
+      ti.totalFiles > 0
+        ? 'Document the test categories (unit / integration / e2e), the coverage rules, and the service→test mapping. The detected test files + case counts are listed above.'
+        : 'No test files were detected. Document the intended test strategy: categories, coverage targets, and where tests will live.',
+      { totalFiles: ti.totalFiles, totalCases: ti.totalCases }));
+    docs.push({ path: 'docs-canonical/TEST-SPEC.md', sections });
+  }
+
+  // API-REFERENCE — only if there's an API surface AND the profile allows it.
+  if (surface.endpoints.length > 0 && profileAllows('docs-canonical/API-REFERENCE.md')) {
     const rows = surface.endpoints.map(e => [`\`${e.method}\``, `\`${e.path}\``, e.auth ? '🔒' : '🔓']);
     const sections = [{
       id: 'endpoints',
@@ -283,8 +353,8 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     docs.push({ path: 'docs-canonical/API-REFERENCE.md', sections });
   }
 
-  // DATA-MODEL — only if entities detected.
-  if (surface.entities.length > 0) {
+  // DATA-MODEL — only if entities detected AND the profile allows it.
+  if (surface.entities.length > 0 && profileAllows('docs-canonical/DATA-MODEL.md')) {
     const rows = surface.entities.map(e => [`\`${e.name}\``, String((e.fields || []).length)]);
     const sections = [{
       id: 'entities',
@@ -297,8 +367,8 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     docs.push({ path: 'docs-canonical/DATA-MODEL.md', sections });
   }
 
-  // SCREENS — only for web frontends with screens.
-  if (surface.screens.length > 0) {
+  // SCREENS — only for web frontends with screens AND if the profile allows it.
+  if (surface.screens.length > 0 && profileAllows('docs-canonical/SCREENS.md')) {
     const rows = surface.screens.map(s => [`\`${s.path}\``, s.component || '—']);
     const sections = [{
       id: 'screens',
@@ -311,8 +381,8 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     docs.push({ path: 'docs-canonical/SCREENS.md', sections });
   }
 
-  // INTEGRATIONS — external services / SDKs detected from deps.
-  if (surface.integrations.length > 0) {
+  // INTEGRATIONS — external services / SDKs detected from deps (profile-gated).
+  if (surface.integrations.length > 0 && profileAllows('docs-canonical/INTEGRATIONS.md')) {
     const rows = surface.integrations.map(i => [i.category, `**${i.name}**`, i.evidence.slice(0, 3).join(', ')]);
     const sections = [{
       id: 'integrations',
@@ -325,8 +395,8 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     docs.push({ path: 'docs-canonical/INTEGRATIONS.md', sections });
   }
 
-  // FEATURES — derived from screens + endpoints when there's a UI surface.
-  if (surface.screens.length > 0) {
+  // FEATURES — derived from screens + endpoints when there's a UI surface (profile-gated).
+  if (surface.screens.length > 0 && profileAllows('docs-canonical/FEATURES.md')) {
     const groups = {};
     for (const s of surface.screens) {
       const seg = (s.path.split('/').filter(Boolean)[0] || 'root');
@@ -395,5 +465,5 @@ function _buildMemoryPlanUncached(projectDir, config = {}) {
     ],
   });
 
-  return { profile, surface, docs, agentTasks };
+  return { profile, surface, docs, agentTasks, notes };
 }

package/cli/scanners/project-type.mjs

@@ -15,7 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, dirname, basename } from 'node:path';
-import { shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { shouldIgnore, relPosix, isNonProductDir } from '../shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build', 'coverage', 'target',
@@ -53,9 +53,12 @@ function findManifests(projectDir, maxDepth = 4, config = {}) {
     for (const e of entries) {
       if (e.isDirectory()) {
         if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
-        // Honor config.ignore / .docguardignore: a user who excludes tests/ or
-        // base-research/ must not have those dirs' manifests (e.g. a fixture
-        // package.json declaring express) misclassify the project's stack.
+        // v0.26 (Bug #1): skip non-product dirs (tests/fixtures/examples/…) by
+        // DEFAULT. A fixture `package.json` declaring express or a `py_app`
+        // requirements.txt with flask must never set the PROJECT's stack/kind.
+        // This is the first-run fix — it needs no `.docguardignore`.
+        if (isNonProductDir(e.name, config)) continue;
+        // Also honor explicit config.ignore / .docguardignore patterns.
         if (shouldIgnore(relPosix(root, join(dir, e.name)), config)) continue;
         walk(join(dir, e.name), depth + 1);
       } else if (e.isFile()) {
@@ -315,3 +318,56 @@ export function detectProjectProfile(projectDir, config = {}) {
     kind: primary?.kind || 'unknown',
   };
 }
+
+/**
+ * Find a `name = "..."` entry inside a TOML `[section]` (e.g. `[project]`,
+ * `[package]`, `[tool.poetry]`). Header match is exact on the bracket content.
+ */
+function tomlSectionName(content, section) {
+  if (!content) return null;
+  let inSection = false;
+  for (const line of content.split(/\r?\n/)) {
+    const header = line.match(/^\s*\[([^\]]+)\]/);
+    if (header) { inSection = header[1].trim() === section; continue; }
+    if (inSection) {
+      const m = line.match(/^\s*name\s*=\s*['"]([^'"]+)['"]/);
+      if (m) return m[1].trim();
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the project's declared NAME from its ROOT manifest, falling back to
+ * the directory basename.
+ *
+ * Fixes Bug #4: inside a git worktree the directory is an auto-generated slug
+ * (e.g. `compassionate-chaplygin-c91f47`), but the real name lives in
+ * `pyproject.toml [project].name` / `package.json` name / `Cargo.toml [package]
+ * name` / `composer.json` name / `go.mod` module. Reads only root manifests —
+ * cheap, no tree walk — so it's safe to call at config-load time.
+ */
+export function detectProjectName(projectDir) {
+  const root = resolve(projectDir);
+
+  const pkg = readJson(join(root, 'package.json'));
+  if (pkg && typeof pkg.name === 'string' && pkg.name.trim()) return pkg.name.trim();
+
+  const py = tomlSectionName(readSafe(join(root, 'pyproject.toml')), 'project')
+    || tomlSectionName(readSafe(join(root, 'pyproject.toml')), 'tool.poetry');
+  if (py) return py;
+
+  const cargo = tomlSectionName(readSafe(join(root, 'Cargo.toml')), 'package');
+  if (cargo) return cargo;
+
+  const composer = readJson(join(root, 'composer.json'));
+  if (composer && typeof composer.name === 'string' && composer.name.trim()) {
+    const n = composer.name.trim();
+    return n.includes('/') ? n.slice(n.lastIndexOf('/') + 1) : n; // vendor/name → name
+  }
+
+  const goMod = readSafe(join(root, 'go.mod')).match(/^\s*module\s+(\S+)/m);
+  if (goMod) return basename(goMod[1].replace(/\/+$/, ''));
+
+  return basename(root);
+}

package/cli/scanners/routes.mjs

@@ -9,7 +9,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, relative, basename, extname, dirname } from 'node:path';
 import { resolveSourceRoots, readScannable } from '../shared-source.mjs';
-import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix } from '../shared-ignore.mjs';
+import { DEFAULT_IGNORE_DIRS as IGNORE_DIRS, shouldIgnore, relPosix, isNonProductPath } from '../shared-ignore.mjs';
 import { extractJsRouteCalls, extractJsRouteObjects, extractJsMountsAndImports } from './js-ast.mjs';
 import { extractPythonFiles } from './py-ast.mjs';
 
@@ -78,16 +78,22 @@ export function scanRoutesDeep(dir, stack, docTools, opts = {}) {
     routes.push(...scanFastAPIRoutes(dir));
   }
 
-  // Deduplicate by method+path, and honor .docguardignore / config.ignore so a
-  // fixtures dir with fake routes doesn't pollute the API surface. Filtering the
-  // RESULTS (route.file → project-relative) keeps the per-framework walkers as-is.
+  // Deduplicate by method+path, and drop routes that live in non-product dirs
+  // (tests/fixtures/examples) so a fixtures dir with fake routes doesn't pollute
+  // the API surface. Filtering the RESULTS (route.file → project-relative) keeps
+  // the per-framework walkers as-is. v0.26 (Bug #1): isNonProductPath applies by
+  // DEFAULT (no .docguardignore needed); shouldIgnore honors explicit config.
   const cfg = opts.config || {};
   const seen = new Set();
   return routes.filter(r => {
     const key = `${r.method}:${r.path}`;
     if (seen.has(key)) return false;
     seen.add(key);
-    if (r.file && shouldIgnore(relPosix(dir, resolve(dir, r.file)), cfg)) return false;
+    if (r.file) {
+      const rel = relPosix(dir, resolve(dir, r.file));
+      if (isNonProductPath(rel, cfg)) return false;
+      if (shouldIgnore(rel, cfg)) return false;
+    }
     return true;
   });
 }

package/cli/shared-ignore.mjs

@@ -40,6 +40,46 @@ export const DEFAULT_IGNORE_DIRS = new Set([
 const ALWAYS_REJECT_PATH_RE =
   /(?:^|[/\\])(?:node_modules|\.claude[/\\]worktrees|\.git[/\\]worktrees|\.jj)(?:[/\\]|$)/;
 
+/**
+ * Directory names that hold NON-PRODUCT code — test fixtures, sample apps,
+ * example projects, mocks. Excluded from SURFACE DETECTION (framework / route /
+ * integration / env-var inference) BY DEFAULT, with no `.docguardignore`
+ * required.
+ *
+ * Why this exists (v0.26, field report Bug #1): a tool's own test fixtures —
+ * e.g. a deliberately-vulnerable Express sample under `tests/fixtures/` — were
+ * being read as the PRODUCT's architecture, so a pure-Python CLI got documented
+ * as an Express/Flask web app. Honoring `config.ignore` (added v0.25) wasn't
+ * enough: the realistic first run has no `.docguardignore` yet.
+ *
+ * SCOPE: detection/generate scanners ONLY — deliberately NOT guard's structural
+ * validators. A user's real `examples/` dir still counts toward docs coverage.
+ * Anti-false-green: when a surface signal appears ONLY under these dirs, callers
+ * SHOULD surface a low-confidence "confirm these are fixtures" note rather than
+ * silently drop it. Override via `config.detection.includeNonProduct = true`.
+ */
+export const DEFAULT_DETECTION_IGNORE_DIRS = new Set([
+  'fixtures', '__fixtures__', 'test-fixtures', 'testfixtures', 'testdata',
+  'test', 'tests', '__tests__', 'spec', 'specs', '__mocks__', 'mocks',
+  'examples', 'example', 'sample', 'samples',
+]);
+
+/** True if `dirName` is a non-product dir detection should skip by default. */
+export function isNonProductDir(dirName, config = {}) {
+  if (config?.detection?.includeNonProduct) return false;
+  return DEFAULT_DETECTION_IGNORE_DIRS.has(dirName);
+}
+
+/**
+ * True if ANY path segment of `relPath` (POSIX, project-relative) is a
+ * non-product detection dir — for filtering file-level detection results.
+ */
+export function isNonProductPath(relPath, config = {}) {
+  if (config?.detection?.includeNonProduct) return false;
+  if (!relPath) return false;
+  return relPath.split('/').some(seg => DEFAULT_DETECTION_IGNORE_DIRS.has(seg));
+}
+
 /**
  * Read `.docguardignore` from a project directory and return its patterns.
  *

package/cli/shared-source.mjs

@@ -15,7 +15,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, relative, extname } from 'node:path';
-import { shouldIgnore } from './shared-ignore.mjs';
+import { shouldIgnore, isNonProductDir, isNonProductPath } from './shared-ignore.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', '.nuxt', 'dist', 'build', 'out',
@@ -232,6 +232,63 @@ export function detectDocker(projectDir, config = {}) {
   return false;
 }
 
+const HASH_COMMENT_EXTS = new Set(['.py', '.rb', '.php', '.sh']);
+const SLASH_COMMENT_EXTS = new Set(['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.go', '.rs', '.java', '.php', '.kt', '.scala']);
+
+/**
+ * Classify every character of `content` as code (0), string-literal (1), or
+ * comment (2) with a single-pass, dependency-free lexer. Used by env detection
+ * (Bug #7) so a variable is counted only when actually READ in code — not when
+ * merely mentioned inside a string literal (e.g. a detection signature like
+ * `r"os.environ.get('JWT_SECRET')"`) or a comment. Handles ' " ` quotes,
+ * Python triple-quotes, `#` and `//` line comments, and `/_ _/` block comments.
+ * Best-effort: on an unterminated single-line string it bails at the newline so
+ * it never swallows the rest of the file (errs toward marking code, so a real
+ * read is never dropped).
+ */
+function classifyChars(content, ext) {
+  const n = content.length;
+  const kind = new Uint8Array(n); // 0 = code, 1 = string, 2 = comment
+  const hashC = HASH_COMMENT_EXTS.has(ext);
+  const slashC = SLASH_COMMENT_EXTS.has(ext);
+  const triple = ext === '.py';
+  let i = 0;
+  while (i < n) {
+    const ch = content[i];
+    if (hashC && ch === '#') { while (i < n && content[i] !== '\n') kind[i++] = 2; continue; }
+    if (slashC && ch === '/' && content[i + 1] === '/') { while (i < n && content[i] !== '\n') kind[i++] = 2; continue; }
+    if (slashC && ch === '/' && content[i + 1] === '*') {
+      kind[i++] = 2; if (i < n) kind[i++] = 2;
+      while (i < n && !(content[i] === '*' && content[i + 1] === '/')) kind[i++] = 2;
+      if (i < n) { kind[i++] = 2; if (i < n) kind[i++] = 2; }
+      continue;
+    }
+    if (triple && (ch === '"' || ch === "'") && content[i + 1] === ch && content[i + 2] === ch) {
+      const q = ch;
+      kind[i++] = 1; kind[i++] = 1; kind[i++] = 1;
+      while (i < n && !(content[i] === q && content[i + 1] === q && content[i + 2] === q)) {
+        if (content[i] === '\\') { kind[i++] = 1; if (i < n) kind[i++] = 1; continue; }
+        kind[i++] = 1;
+      }
+      if (i < n) { kind[i++] = 1; if (i < n) kind[i++] = 1; if (i < n) kind[i++] = 1; }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const q = ch;
+      kind[i++] = 1; // opening quote
+      while (i < n && content[i] !== q) {
+        if (content[i] === '\\') { kind[i++] = 1; if (i < n) kind[i++] = 1; continue; }
+        if (content[i] === '\n' && q !== '`') break; // unterminated single-line string — bail
+        kind[i++] = 1;
+      }
+      if (i < n && content[i] === q) kind[i++] = 1; // closing quote
+      continue;
+    }
+    kind[i++] = 0;
+  }
+  return kind;
+}
+
 /**
  * Grep source files under the resolved source roots for environment variable
  * usage in both the Node (process dot env) and Vite (import meta env) styles,
@@ -269,9 +326,18 @@ export function grepEnvUsage(projectDir, config = {}) {
     if (!CODE_EXTENSIONS.has(extname(filePath))) return;
     const rel = relative(projectDir, filePath);
     if (shouldIgnore(rel, config)) return;
+    // v0.26 (Bug #7): a token that appears only in a test/fixture file is not a
+    // product env read. Skip non-product paths by default (no .docguardignore).
+    if (isNonProductPath(rel.replace(/\\/g, '/'), config)) return;
     const content = readScannable(filePath);
     if (content === null) return; // unreadable, generated, or too large to scan
     if (!content.includes('env')) return;
+    // v0.26 (Bug #7): classify chars so we count env vars actually READ in code,
+    // not ones MENTIONED inside a string literal (a detection signature like
+    // `r"os.environ.get('JWT_SECRET')"`) or a comment. We test the position of
+    // the access KEYWORD (process/os/import) — for a real read the keyword is
+    // code while only the argument 'X' is a string, so the name is still caught.
+    const kind = classifyChars(content, extname(filePath));
     // patterns[2] is the import.meta.env one — its matches are Vite-injected
     // when the name is an intrinsic, and must not be reported as user env vars.
     for (let i = 0; i < patterns.length; i++) {
@@ -279,6 +345,7 @@ export function grepEnvUsage(projectDir, config = {}) {
       const rx = new RegExp(patterns[i].source, 'g');
       const isViteSource = i === 2;
       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;
         names.add(m[1]);
       }
@@ -314,6 +381,7 @@ export function grepEnvUsage(projectDir, config = {}) {
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const e of entries) {
       if (IGNORE_DIRS.has(e.name) || e.name.startsWith('.')) continue;
+      if (e.isDirectory() && isNonProductDir(e.name, config)) continue; // v0.26: skip test/fixture dirs in env detection
       const full = join(dir, e.name);
       if (e.isDirectory()) walk(full);
       else if (e.isFile()) visit(full);

package/cli/validators/freshness.mjs

@@ -61,6 +61,22 @@ export function readLastReviewedDate(absPath) {
   }
 }
 
+/**
+ * Read the `<!-- docguard:status <value> -->` marker (draft | review | approved
+ * | living). Returns the lowercased value, or null. Used by the uncommitted-doc
+ * check (Bug #6): a doc the agent generated this session and marked `approved`
+ * has an explicit currency signal even before it's committed.
+ */
+function readDocStatus(absPath) {
+  try {
+    const content = readFileSync(absPath, 'utf-8');
+    const m = content.match(/<!--\s*docguard:status\s+([a-z]+)\s*-->/i);
+    return m ? m[1].toLowerCase() : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Get the last git commit date for a file.
  * Returns null if the file isn't tracked or git isn't available.
@@ -213,10 +229,23 @@ export function validateFreshness(dir, config) {
     const reviewedDate = readLastReviewedDate(docPath);
     const docDate = reviewedDate || getLastGitDate(docFile, dir);
     if (!docDate) {
-      // File exists but isn't tracked in git yet
+      // File exists but has no freshness signal (not in git, no last-reviewed).
+      // Bug #6: an agent that generated the doc THIS session and stamped it
+      // `<!-- docguard:status approved -->` has signaled it's intentionally
+      // current. In the generate-then-fill flow the human hasn't committed yet,
+      // so the "uncommitted" warning is noise — suppress it for approved docs.
+      if (readDocStatus(docPath) === 'approved') {
+        results.push({
+          status: 'pass',
+          message: `${docFile} is marked approved (not yet committed — fine mid-session)`,
+        });
+        continue;
+      }
+      // State BOTH satisfiers — the warning used to mention only committing, so
+      // an agent that can stamp a marker but not commit was left guessing.
       results.push({
         status: 'warn',
-        message: `${docFile} exists but is not yet committed to git`,
+        message: `${docFile} exists but is not yet committed to git — commit it, or add a <!-- docguard:last-reviewed YYYY-MM-DD --> marker (or <!-- docguard:status approved -->).`,
       });
       continue;
     }

package/cli/validators/metrics-consistency.mjs

@@ -93,6 +93,11 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
       // "19" on line 50 are two distinct drifts.
       const distinctFoundInFile = new Set();
       while ((match = regex.exec(content)) !== null) {
+        // Bug #2 (subject-binding): only validate a number BOUND to DocGuard.
+        // An unbound "N checks" (a proof harness, a CI job, a third-party tool)
+        // describes a DIFFERENT subject — comparing it to DocGuard's own count
+        // is a false positive, and auto-fixing it overwrites a correct number.
+        if (!isDocguardBound(content, match.index)) continue;
         distinctFoundInFile.add(parseInt(match[1], 10));
       }
       if (distinctFoundInFile.size === 0) continue;
@@ -104,9 +109,12 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
           reportedDrift.add(driftKey);
           total++;
           warnings.push(
-            `${relPath} says "${found} ${label}" but actual count is ${actuals[key]}. Fix with \`docguard fix --write\``
+            `${relPath} says "${found} ${label}" but DocGuard's own ${label} count is ${actuals[key]}. Fix with \`docguard fix --write\``
           );
-          fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key] });
+          // actualSource records WHAT the actual count describes, so the applier
+          // (and a human) can confirm both sides are the same subject before any
+          // overwrite. Without it the fix is refused (fail-closed). See Bug #2.
+          fixes.push({ type: 'replace-count', file: relPath, label, found, actual: actuals[key], actualSource: `docguard.guard.${key}` });
         } else {
           // Matches the actual count — one pass per (file, label), not per occurrence.
           const passKey = `${relPath}|${label}`;
@@ -124,6 +132,22 @@ export function validateMetricsConsistency(projectDir, config, guardResults) {
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
+/**
+ * Bug #2 — subject binding. A "N checks/validators" claim is DocGuard's to
+ * govern ONLY if it's bound to DocGuard: the line containing the number must
+ * reference "docguard" (case-insensitive), which also covers an explicit
+ * `<!-- docguard:metric ... -->` marker on that line. Numbers describing
+ * anything else (a proof harness, a CI pipeline, a competitor's tool) are out
+ * of scope — validating them is a false positive and auto-fixing them corrupts
+ * a correct number with DocGuard's unrelated count.
+ */
+function isDocguardBound(content, index) {
+  const lineStart = content.lastIndexOf('\n', index) + 1;
+  let lineEnd = content.indexOf('\n', index);
+  if (lineEnd === -1) lineEnd = content.length;
+  return /docguard/i.test(content.slice(lineStart, lineEnd));
+}
+
 function findTestFiles(dir) {
   const tests = [];
   const testDirs = ['tests', 'test', '__tests__', 'spec', 'e2e'];

package/cli/writers/mechanical.mjs

@@ -47,15 +47,33 @@ const esc = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 function applyReplaceCount(projectDir, fix) {
   const full = resolve(projectDir, fix.file);
   if (!existsSync(full)) return { applied: false };
+  // Bug #2 (fail-closed): NEVER overwrite a number without provenance proving
+  // the "actual" describes the SAME subject. The Metrics-Consistency validator
+  // stamps `actualSource` (e.g. "docguard.guard.checks") only for claims it
+  // verified are bound to DocGuard. A fix lacking it is refused rather than risk
+  // corrupting a correct, unrelated number.
+  if (!fix.actualSource) {
+    return { applied: false, detail: `${fix.file}: skipped "${fix.found} ${fix.label}" → "${fix.actual}" — no provenance (actualSource) to prove same subject` };
+  }
   const content = readFileSync(full, 'utf-8');
   // v0.15.2 hotfix: case-insensitive label match. Mirrors the validator's
   // detection regex (which is `gi`). Without `i` here, the applier would
   // skip "21 Validators" (capitalized) even though Metrics-Consistency
   // detected it — leaving the user with a warning they couldn't auto-fix.
-  // The /docguard.diagnose run on canonical-spec-kit surfaced this.
   const re = new RegExp(`\\b${esc(fix.found)}(\\s+(?:automated\\s+)?${esc(fix.label)}\\b)`, 'gi');
-  const next = content.replace(re, `${fix.actual}$1`);
-  if (next === content) return { applied: false };
+  // Only rewrite occurrences on a DocGuard-bound line (same predicate as the
+  // validator's subject-binding) so a stray "<found> <label>" elsewhere in the
+  // file is never collateral-damaged by the global replace.
+  let changed = false;
+  const next = content.replace(re, (m, tail, offset, str) => {
+    const lineStart = str.lastIndexOf('\n', offset) + 1;
+    let lineEnd = str.indexOf('\n', offset);
+    if (lineEnd === -1) lineEnd = str.length;
+    if (!/docguard/i.test(str.slice(lineStart, lineEnd))) return m; // not bound → leave untouched
+    changed = true;
+    return `${fix.actual}${tail}`;
+  });
+  if (!changed || next === content) return { applied: false };
   writeFileSync(full, next, 'utf-8');
   return { applied: true, detail: `${fix.file}: "${fix.found} ${fix.label}" → "${fix.actual} ${fix.label}"` };
 }

package/package.json

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