docguard-cli 0.25.1 → 0.27.0

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

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

package/cli/validators/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'];