docguard-cli 0.20.0 → 0.21.1

package/README.md

@@ -12,6 +12,14 @@
 
 ---
 
+> **✨ See what DocGuard catches in 30 seconds — no install, no setup:**
+> ```bash
+> npx docguard-cli demo
+> ```
+> Runs against a baked-in sample project with intentional drift and shows you the findings + a clear path to fixing them.
+
+---
+
 ## Table of Contents
 
 - [What is DocGuard?](#what-is-docguard)
@@ -51,7 +59,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 (13)"]
+    CLI["CLI Entry<br/>docguard.mjs"] --> Commands["Commands (14)"]
     Commands --> guard["guard"]
     Commands --> generate["generate"]
     Commands --> score["score"]
@@ -235,7 +243,7 @@ This installs DocGuard's slash commands (`/docguard.guard`, `/docguard.review`,
 
 ## Usage
 
-DocGuard ships **13 commands** (the "Daily 5" + 8 situational tools). 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 **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).
 
 **The Daily 5** — what you'll reach for 95% of the time:
 

package/cli/commands/demo.mjs

@@ -0,0 +1,241 @@
+/**
+ * Demo Command — v0.21.
+ *
+ * The 30-second "ah-ha" experience for devs shopping for doc tools.
+ *
+ *   npx docguard-cli demo
+ *
+ * Spins up a baked-in fixture project (`templates/demo-fixture/`) — a 4-service
+ * payments API with INTENTIONAL doc drift — runs guard against it, and prints
+ * a curated narrative with real-world-impact annotations + a clear install CTA.
+ *
+ * Zero install required, zero damage to the user's environment: the fixture
+ * is copied to a temp directory, git-initialized there, and cleaned up on exit.
+ *
+ * Why this exists: per SURFACE-AUDIT v0.21 plan, the #2 friction point for
+ * adoption was "no demo path — devs have to install, init, write docs, run
+ * guard just to see what we do." This command compresses that to 30 seconds.
+ */
+
+import { mkdtempSync, rmSync, cpSync, existsSync, writeFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { c } from '../shared.mjs';
+import { runGuardInternal, classifyResult } from './guard.mjs';
+import { runScoreInternal } from './score.mjs';
+import { loadConfig } from '../docguard.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const FIXTURE_SRC = resolve(__dirname, '../../templates/demo-fixture');
+
+/**
+ * Each warning pattern gets a 1-2 line "real-world impact" gloss. Keyed by
+ * a regex on the warning text; the first match wins. Falls back to the
+ * generic gloss for unrecognized warnings (so this dictionary stays
+ * resilient as validators evolve).
+ *
+ * The point: turn validator-speak ("Missing 'Setup Steps' section") into
+ * adopter-speak ("New devs spend an hour figuring out how to run this").
+ */
+const IMPACT_GLOSS = [
+  {
+    re: /env var.*not documented|missing.*Environment Variables/i,
+    impact: 'New devs hit cryptic "X is undefined" runtime errors at boot. CI bypasses the missing var entirely.',
+  },
+  {
+    re: /[Aa]rchitecture|service.*not (in|mentioned)|not in [Aa]rchitecture/,
+    impact: 'Your AI agent reads the architecture doc and gives wrong answers about how the system works.',
+  },
+  {
+    re: /missing.*Usage|missing.*License|README/,
+    impact: 'First-time visitors bounce. The README is the storefront — empty sections = lost trust.',
+  },
+  {
+    re: /endpoint|route|API-REFERENCE/i,
+    impact: 'Clients call a documented endpoint that no longer exists, or worse — miss a new endpoint entirely.',
+  },
+  {
+    re: /Test-Spec|test.*directory|test files/,
+    impact: 'Your TEST-SPEC doesn\'t reflect reality. New tests get written in the wrong place.',
+  },
+  {
+    re: /Unreleased.*section|Changelog/,
+    impact: 'Release automation can\'t auto-detect what\'s pending. Versioning becomes manual guesswork.',
+  },
+  {
+    re: /Spec.?Kit/i,
+    impact: 'Specs aren\'t structured for AI agents to use. You miss the multiplier on spec-driven development.',
+  },
+  {
+    re: /Config file.*not mentioned/,
+    impact: 'Devs see an unknown config file and don\'t know if it\'s safe to delete or required.',
+  },
+  {
+    re: /unlinked doc|not in your requiredFiles/,
+    impact: 'Doc lives in canonical/ but isn\'t in the manifest — guard skips it, drift accumulates silently.',
+  },
+];
+
+function getImpact(warning) {
+  for (const { re, impact } of IMPACT_GLOSS) {
+    if (re.test(warning)) return impact;
+  }
+  return null;
+}
+
+/**
+ * Set up a temp copy of the fixture, git-init it, return the path.
+ */
+function setupFixture() {
+  const dir = mkdtempSync(join(tmpdir(), 'docguard-demo-'));
+  cpSync(FIXTURE_SRC, dir, { recursive: true });
+  // Initialize git so any history-aware validators (Freshness, Drift-Comments)
+  // can run without erroring. Identity is set locally so commit succeeds on
+  // CI runners that have no global git identity.
+  const opts = { cwd: dir, stdio: 'ignore' };
+  spawnSync('git', ['init', '-q', '-b', 'main'], opts);
+  spawnSync('git', ['config', 'user.email', 'demo@docguard.dev'], opts);
+  spawnSync('git', ['config', 'user.name', 'docguard-demo'], opts);
+  spawnSync('git', ['add', '-A'], opts);
+  spawnSync('git', ['commit', '-q', '-m', 'fixture'], opts);
+  return dir;
+}
+
+/**
+ * Pretty-print a curated guard run.
+ */
+function presentResults(guardData, scoreData) {
+  const allWarnings = [];
+  for (const v of guardData.validators) {
+    for (const w of (v.warnings || [])) {
+      allWarnings.push({ validator: v.name, message: w, severity: v.severity });
+    }
+  }
+
+  console.log(`\n${c.bold}🔍 What DocGuard found in your fixture:${c.reset}`);
+  console.log(`${c.dim}   Validators run: ${guardData.validators.length}   ·   Warnings: ${allWarnings.length}   ·   Time: ~0.5s${c.reset}\n`);
+
+  // Pick up to 5 warnings showing VARIETY across validators (not 5 from the
+  // same one). Dedupe by validator name; within each validator group, pick
+  // the highest-severity warning. Then rank the picks by severity.
+  const sev = { high: 0, medium: 1, low: 2 };
+  const byValidator = new Map();
+  for (const w of allWarnings) {
+    const prev = byValidator.get(w.validator);
+    if (!prev || (sev[w.severity] ?? 1) < (sev[prev.severity] ?? 1)) {
+      byValidator.set(w.validator, w);
+    }
+  }
+  const ranked = [...byValidator.values()].sort((a, b) => {
+    return (sev[a.severity] ?? 1) - (sev[b.severity] ?? 1);
+  });
+  const top = ranked.slice(0, 5);
+
+  for (let i = 0; i < top.length; i++) {
+    const w = top[i];
+    const sev = w.severity === 'high' ? `${c.red}[HIGH]${c.reset}`
+              : w.severity === 'low'  ? `${c.dim}[LOW]${c.reset}`
+              : `${c.yellow}[MED]${c.reset}`;
+    console.log(`   ${c.bold}${i + 1}.${c.reset} ${sev} ${c.cyan}${w.validator}${c.reset}`);
+    console.log(`      ${c.dim}${w.message}${c.reset}`);
+    const impact = getImpact(w.message);
+    if (impact) {
+      console.log(`      ${c.green}→${c.reset} ${impact}`);
+    }
+    console.log('');
+  }
+
+  if (allWarnings.length > top.length) {
+    console.log(`   ${c.dim}... and ${allWarnings.length - top.length} more. Run \`docguard guard\` in your repo to see everything.${c.reset}\n`);
+  }
+
+  // Score line
+  if (scoreData && typeof scoreData.score === 'number') {
+    const grade = scoreData.score >= 90 ? 'A' : scoreData.score >= 80 ? 'B' : scoreData.score >= 70 ? 'C' : scoreData.score >= 60 ? 'D' : 'F';
+    const color = scoreData.score >= 80 ? c.green : scoreData.score >= 60 ? c.yellow : c.red;
+    console.log(`${c.bold}📊 CDD Maturity Score:${c.reset} ${color}${scoreData.score}/100 (${grade})${c.reset}`);
+    console.log(`${c.dim}   ↑ This is the fixture's score. Yours will hopefully be higher.${c.reset}\n`);
+  }
+}
+
+function printCTA() {
+  console.log(`${c.bold}🛠️  Fixing drift like this:${c.reset}`);
+  console.log(`   ${c.cyan}docguard fix --write${c.reset}      ${c.dim}— patches the mechanical stuff (version refs, counts, anchors)${c.reset}`);
+  console.log(`   ${c.cyan}docguard sync --write${c.reset}     ${c.dim}— refreshes code-truth sections to match the codebase${c.reset}`);
+  console.log(`   ${c.cyan}docguard diagnose${c.reset}         ${c.dim}— generates an AI prompt for the prose drift (Claude/GPT/Cursor)${c.reset}\n`);
+
+  console.log(`${c.bold}🚀 Try it on YOUR project:${c.reset}`);
+  console.log(`   ${c.green}npm install -g docguard-cli${c.reset}`);
+  console.log(`   ${c.green}cd your-project${c.reset}`);
+  console.log(`   ${c.green}docguard init${c.reset}              ${c.dim}— scans existing code and proposes canonical docs${c.reset}`);
+  console.log(`   ${c.green}docguard guard${c.reset}             ${c.dim}— see what we catch${c.reset}\n`);
+
+  console.log(`${c.dim}Or stay zero-install:${c.reset}`);
+  console.log(`   ${c.green}npx docguard-cli init${c.reset}`);
+  console.log(`   ${c.green}npx docguard-cli guard${c.reset}\n`);
+
+  console.log(`${c.bold}📚 Learn more:${c.reset} ${c.cyan}https://github.com/raccioly/docguard${c.reset}`);
+}
+
+/**
+ * Public entry point — `docguard demo`.
+ *
+ * @param {string} _projectDir — ignored; demo uses its own temp fixture
+ * @param {object} _config — ignored
+ * @param {object} flags — supports --quiet (skip banner) and --keep (don't cleanup fixture)
+ */
+export function runDemo(_projectDir, _config, flags = {}) {
+  if (!flags.quiet) {
+    console.log(`\n${c.bold}🎬 DocGuard Demo${c.reset} ${c.dim}— see what we catch in 30 seconds${c.reset}`);
+    console.log(`${c.dim}   No install. No setup. We're running against a sample 4-service payments API${c.reset}`);
+    console.log(`${c.dim}   with intentional drift between code and docs.${c.reset}\n`);
+  }
+
+  if (!existsSync(FIXTURE_SRC)) {
+    console.error(`${c.red}Demo fixture not found at ${FIXTURE_SRC}.${c.reset}`);
+    console.error(`${c.dim}If this is a packaging bug, please file an issue.${c.reset}`);
+    process.exit(1);
+  }
+
+  let fixture;
+  try {
+    fixture = setupFixture();
+    if (!flags.quiet) console.log(`${c.dim}   Fixture ready at ${fixture}${c.reset}\n`);
+  } catch (err) {
+    if (fixture) rmSync(fixture, { recursive: true, force: true });
+    console.error(`${c.red}Failed to set up demo fixture: ${err.message}${c.reset}`);
+    process.exit(1);
+  }
+
+  // Run guard + score against the fixture
+  let guardData, scoreData;
+  try {
+    // Load full config (defaults + fixture's .docguard.json) — same path the
+    // real `docguard guard` uses. The fixture ships its own .docguard.json
+    // so this hydrates the right project name + profile.
+    const config = loadConfig(fixture);
+    guardData = runGuardInternal(fixture, config);
+    scoreData = runScoreInternal(fixture, config);
+  } catch (err) {
+    rmSync(fixture, { recursive: true, force: true });
+    console.error(`${c.red}Demo guard run failed: ${err.message}${c.reset}`);
+    process.exit(1);
+  }
+
+  presentResults(guardData, scoreData);
+  printCTA();
+
+  // Cleanup unless --keep
+  if (!flags.keep) {
+    rmSync(fixture, { recursive: true, force: true });
+    if (!flags.quiet) console.log(`${c.dim}   Fixture cleaned up.${c.reset}`);
+  } else {
+    console.log(`${c.dim}   Fixture kept at ${fixture} (--keep)${c.reset}`);
+  }
+
+  // Always exit 0 — the demo is informational, never a failure
+  process.exit(0);
+}

package/cli/commands/init.mjs

@@ -15,7 +15,7 @@ import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
 import { execSync } from 'node:child_process';
 import { c, PROFILES } from '../shared.mjs';
-import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent } from '../ensure-skills.mjs';
+import { ensureSkills, detectAgentMode, detectAIAgent, isSpecKitAvailable, isSpecKitInitialized, getDetectedAgent, safeSpawnSpecify } from '../ensure-skills.mjs';
 
 // v0.20: scaffolder names that can be passed via `init --with <name>` and
 // dispatched to the corresponding standalone runner. Each name maps to its
@@ -92,6 +92,61 @@ function askQuestion(prompt) {
 
 // ── Init Command ─────────────────────────────────────────────────────────
 
+/**
+ * v0.21 — Smart first-run detection.
+ *
+ * Heuristic: if the user is running `docguard init` against a project that
+ * already has substantial source code (cli/, src/, lib/, app/, or 10+ source
+ * files at depth 1-2) AND has no docs-canonical/ yet, switch from the
+ * skeleton-first path to the "scan and propose" path — i.e. dispatch to
+ * `docguard generate --plan` which reverse-engineers canonical docs from
+ * existing code.
+ *
+ * Rationale: blank skeletons feel useless for existing projects (the dev
+ * has to write everything from scratch). The scan path delivers immediate
+ * value: "here's what your project actually does, mapped to canonical doc
+ * shape." That's a 30-second wow for the 80% of adopters who arrive with
+ * an existing codebase.
+ *
+ * Opt out: `docguard init --skeleton` forces the blank-template path
+ * (preserves the v0.20 behavior for greenfield projects and CI flows).
+ *
+ * @returns {boolean} true if smart-detection fired and dispatched
+ */
+function shouldRunGenerate(projectDir, flags) {
+  if (flags.skeleton)        return false; // explicit opt-out
+  if (flags.skipPrompts)     return false; // non-interactive (CI) keeps deterministic skeleton path
+  if (flags.wizard)          return false; // wizard has its own scan step
+  if (flags.profile)         return false; // explicit profile = user knows what they want
+
+  // If canonical docs already exist, this is a re-init, not a first-run.
+  const canonicalDir = resolve(projectDir, 'docs-canonical');
+  if (existsSync(canonicalDir)) {
+    try {
+      const entries = readdirSync(canonicalDir).filter(f => f.endsWith('.md'));
+      if (entries.length > 0) return false;
+    } catch { /* fall through */ }
+  }
+
+  // Existing-code signals: any of cli/, src/, lib/, app/ as a directory.
+  const codeDirs = ['cli', 'src', 'lib', 'app'];
+  for (const d of codeDirs) {
+    if (existsSync(resolve(projectDir, d))) return true;
+  }
+
+  // Fallback: count source files at top level (Python / Rust / Go projects
+  // often don't use src/ — files live at the root).
+  try {
+    const exts = ['.py', '.rs', '.go', '.java', '.rb', '.ts', '.tsx', '.mjs', '.js'];
+    const topLevel = readdirSync(projectDir).filter(f => {
+      return exts.some(e => f.endsWith(e));
+    });
+    if (topLevel.length >= 10) return true;
+  } catch { /* fall through */ }
+
+  return false;
+}
+
 export async function runInit(projectDir, config, flags) {
   // v0.20: `--wizard` dispatches to the full interactive onboarding (formerly
   // `docguard setup`). Done before profile validation so the wizard can ask
@@ -101,6 +156,19 @@ export async function runInit(projectDir, config, flags) {
     return runSetup(projectDir, config, flags);
   }
 
+  // v0.21: smart first-run — for existing projects without canonical docs,
+  // dispatch to `generate --plan` (the "scan and propose" path). Opt out
+  // with --skeleton or by setting --profile/--skip-prompts/--wizard explicitly.
+  if (shouldRunGenerate(projectDir, flags)) {
+    console.log(`${c.bold}🔍 DocGuard Init — Smart Mode${c.reset}`);
+    console.log(`${c.dim}   Detected existing project with code but no canonical docs.${c.reset}`);
+    console.log(`${c.dim}   Switching to "scan and propose" mode — DocGuard will reverse-engineer${c.reset}`);
+    console.log(`${c.dim}   canonical docs from your code instead of dumping a blank skeleton.${c.reset}`);
+    console.log(`${c.dim}   (Opt out: ${c.cyan}docguard init --skeleton${c.dim} for the blank-template path.)${c.reset}\n`);
+    const { runGenerate } = await import('./generate.mjs');
+    return runGenerate(projectDir, config, { ...flags, plan: true });
+  }
+
   const profileName = flags.profile || 'standard';
   const profile = PROFILES[profileName];
 
@@ -310,17 +378,22 @@ poetry.lock
   } else if (specKitAvailable && !specKitInitialized) {
     console.log(`\n  ${c.bold}🌱 Spec Kit Integration${c.reset}`);
 
-    // Detect which AI agent is in use (matches spec-kit's --ai flag)
+    // Detect which AI agent is in use (matches spec-kit's --ai flag).
+    // v0.21.1 (issue #190): the returned value is allowlist-validated inside
+    // getDetectedAgent, so an attacker-controlled `.specify/init-options.json`
+    // can no longer inject shell metacharacters here.
     const detectedAgent = detectAIAgent(projectDir);
-    const aiFlag = detectedAgent
-      ? `--ai ${detectedAgent}`
-      : '--ai generic --ai-commands-dir .agent/commands/';
+    const aiArgs = detectedAgent
+      ? ['--ai', detectedAgent]
+      : ['--ai', 'generic', '--ai-commands-dir', '.agent/commands/'];
 
     console.log(`  ${c.dim}Running specify init (agent: ${detectedAgent || 'generic'})...${c.reset}`);
     try {
-      const scriptFlag = process.platform === 'win32' ? '--script ps' : '--script sh';
-      execSync(
-        `specify init --here --force ${aiFlag} --ai-skills --ignore-agent-tools --no-git ${scriptFlag}`,
+      // v0.21.1 (issue #190): execFileSync via safeSpawnSpecify — args pass
+      // through as an array, no shell interpolation.
+      const scriptArgs = process.platform === 'win32' ? ['--script', 'ps'] : ['--script', 'sh'];
+      safeSpawnSpecify(
+        ['init', '--here', '--force', ...aiArgs, '--ai-skills', '--ignore-agent-tools', '--no-git', ...scriptArgs],
         { cwd: projectDir, encoding: 'utf-8', stdio: 'pipe', timeout: 30000 }
       );
       console.log(`  ${c.green}✅${c.reset} Spec Kit initialized ${c.dim}(.specify/, spec-kit skills, agent: ${detectedAgent || 'generic'})${c.reset}`);

package/cli/docguard.mjs

@@ -44,6 +44,7 @@ import { runUpgrade } from './commands/upgrade.mjs';
 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 { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -282,14 +283,18 @@ function printHelp() {
   console.log(`${c.bold}Usage:${c.reset}
   docguard <command> [options]
 
+${c.bold}First-time? Try the demo (no install, no setup):${c.reset}
+  ${c.green}npx docguard-cli demo${c.reset}    ${c.dim}— 30-second tour against a sample project${c.reset}
+
 ${c.bold}The Daily 5${c.reset} ${c.dim}— what you'll reach for 95% of the time${c.reset}
-  ${c.green}init${c.reset}       Bootstrap a project (use ${c.cyan}--wizard${c.reset} for guided / ${c.cyan}--with <name>${c.reset} for scaffolders)
+  ${c.green}init${c.reset}       Bootstrap a project — auto-detects existing code and scans (${c.cyan}--skeleton${c.reset} for blank templates, ${c.cyan}--wizard${c.reset} for guided, ${c.cyan}--with <name>${c.reset} for scaffolders)
   ${c.green}guard${c.reset}      Validate against canonical docs (23 validators)
   ${c.green}diff${c.reset}       Show gaps between docs and code (add ${c.cyan}--since <ref>${c.reset} for changed-file impact)
   ${c.green}sync${c.reset}       Refresh code-truth doc sections — keeps memory always up to date
   ${c.green}score${c.reset}      CDD maturity score (0-100; ${c.cyan}--diff${c.reset} for delta between refs)
 
 ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
+  ${c.green}demo${c.reset}       Zero-install tour: see what DocGuard catches against a sample project in 30s
   ${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)
@@ -471,6 +476,15 @@ async function main() {
       // onboarding flow (previously `docguard setup`). `setup` keeps
       // working as a deprecation alias.
       flags.wizard = true;
+    } else if (args[i] === '--skeleton') {
+      // v0.21: `docguard init --skeleton` opts out of smart "scan and propose"
+      // detection and forces the blank-template path. Useful for greenfield
+      // projects and CI flows that want deterministic output.
+      flags.skeleton = true;
+    } else if (args[i] === '--keep') {
+      // v0.21: `docguard demo --keep` doesn't delete the temp fixture after
+      // running (useful for poking around what DocGuard set up).
+      flags.keep = true;
     } else if (!args[i].startsWith('--') && i > 0) {
       // Positional args go into flags.args for commands that take them (e.g.
       // `docguard trace --reverse <path>`). Skip the command itself (i === 0).
@@ -657,6 +671,13 @@ async function main() {
     case 'memory':
       runMemory(projectDir, config, flags);
       break;
+    case 'demo':
+      // v0.21: zero-install "ah-ha" moment — runs guard against a baked-in
+      // fixture (templates/demo-fixture/) and prints curated drift findings
+      // with real-world-impact annotations. No state changes outside the
+      // temp fixture dir, which is cleaned up on exit.
+      runDemo(projectDir, config, flags);
+      break;
     default:
       console.error(`${c.red}Unknown command: ${command}${c.reset}`);
       console.log(`Run ${c.cyan}docguard --help${c.reset} for usage.`);

package/cli/ensure-skills.mjs

@@ -13,9 +13,32 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { c } from './shared.mjs';
 
+/**
+ * v0.21.1 (security): cross-platform safe spawn for the `specify` CLI.
+ *
+ * On POSIX, runs the `specify` binary directly with argv passed as an array
+ * — no shell interpolation possible. On Windows, the equivalent is via
+ * `cmd.exe /c specify.cmd ...` since `specify` is shipped as a .cmd shim by
+ * `pip install`. Args are still passed as an array so cmd.exe doesn't
+ * re-parse them.
+ *
+ * Replaces the pre-v0.21.1 pattern of `execSync(\`specify init ... \${flag} ...\`)`
+ * which was shell-interpolated and vulnerable to command injection via
+ * `.specify/init-options.json`'s `ai` field (issue #190).
+ */
+export function safeSpawnSpecify(args, opts) {
+  if (!Array.isArray(args)) {
+    throw new TypeError('safeSpawnSpecify(args, opts): args must be an array');
+  }
+  if (process.platform === 'win32') {
+    return execFileSync('cmd.exe', ['/c', 'specify.cmd', ...args], opts);
+  }
+  return execFileSync('specify', args, opts);
+}
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
@@ -77,12 +100,27 @@ export function detectAgentMode(projectDir) {
  * @param {string} projectDir - The project root directory
  * @returns {string | null}
  */
+// v0.21.1 (security): allowlist for the spec-kit --ai flag value. Source
+// values come from `.specify/init-options.json` which is attacker-writable
+// in any compromised project. Without this filter, a value like
+// `"claude; touch /tmp/pwned;"` would shell-execute on every `docguard init`.
+//
+// Set conservatively from spec-kit's published agent list. New agents
+// require a code change to be accepted — by design.
+const VALID_AI_AGENT = /^[a-zA-Z0-9_-]{1,32}$/;
+
 export function getDetectedAgent(projectDir) {
   const initOptions = resolve(projectDir, '.specify', 'init-options.json');
   if (existsSync(initOptions)) {
     try {
       const opts = JSON.parse(readFileSync(initOptions, 'utf-8'));
-      return opts.ai || null;
+      const ai = opts.ai;
+      if (typeof ai !== 'string') return null;
+      // v0.21.1 (issue #190): reject anything outside the allowlist. Without
+      // this, a malicious `.specify/init-options.json` could inject shell
+      // metacharacters through to the `specify init` exec call.
+      if (!VALID_AI_AGENT.test(ai)) return null;
+      return ai;
     } catch { /* ignore */ }
   }
   return null;
@@ -193,13 +231,17 @@ export function ensureSpecKit(projectDir, flags = {}) {
       console.log(`  ${c.cyan}🌱 Spec Kit detected — auto-initializing SDD workflow...${c.reset}`);
     }
     try {
+      // v0.21.1 (issue #190): switched from shell-interpolated execSync to
+      // execFileSync via safeSpawnSpecify. detectAIAgent now also enforces
+      // the [a-zA-Z0-9_-]{1,32} allowlist on values read from .specify/
+      // init-options.json — defense in depth.
       const detectedAgent = detectAIAgent(projectDir);
-      const aiFlag = detectedAgent
-        ? `--ai ${detectedAgent}`
-        : '--ai generic --ai-commands-dir .agent/commands/';
-      const scriptFlag = process.platform === 'win32' ? '--script ps' : '--script sh';
-      execSync(
-        `specify init --here --force ${aiFlag} --ai-skills --ignore-agent-tools --no-git ${scriptFlag}`,
+      const aiArgs = detectedAgent
+        ? ['--ai', detectedAgent]
+        : ['--ai', 'generic', '--ai-commands-dir', '.agent/commands/'];
+      const scriptArgs = process.platform === 'win32' ? ['--script', 'ps'] : ['--script', 'sh'];
+      safeSpawnSpecify(
+        ['init', '--here', '--force', ...aiArgs, '--ai-skills', '--ignore-agent-tools', '--no-git', ...scriptArgs],
         { cwd: projectDir, encoding: 'utf-8', stdio: 'pipe', timeout: 30000 }
       );
       if (!silent) {

package/extensions/spec-kit-docguard/extension.yml

@@ -3,7 +3,7 @@ schema_version: "1.0"
 extension:
   id: "docguard"
   name: "DocGuard — CDD Enforcement"
-  version: "0.20.0"
+  version: "0.21.1"
   description: "Canonical-Driven Development enforcement as a true spec-kit extension. LLM-first design with 19 automated validators, 4 AI behavior skills, spec-kit skill chaining, and workflow hooks. Zero NPM runtime dependencies."
   author: "Ricardo Accioly"
   repository: "https://github.com/raccioly/docguard"

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

@@ -6,10 +6,10 @@ description: AI-driven documentation repair with structured research workflow, t
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-fix
 ---
-<!-- docguard:version: 0.20.0 -->
+<!-- docguard:version: 0.21.1 -->
 
 # DocGuard Fix Skill
 

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

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

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

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

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

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

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

@@ -4,7 +4,7 @@ description: Keep canonical documentation ALWAYS UP TO DATE. Refreshes code-trut
 compatibility: Requires DocGuard CLI installed (npm i -g docguard-cli or npx docguard-cli)
 metadata:
   author: docguard
-  version: 0.20.0
+  version: 0.21.1
   source: extensions/spec-kit-docguard/skills/docguard-sync
 ---
 

package/package.json

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

package/templates/demo-fixture/.docguard.json

@@ -0,0 +1,8 @@
+{
+  "projectName": "acme-payments",
+  "version": "0.5",
+  "profile": "standard",
+  "sourcePatterns": {
+    "routes": "src/**/*.mjs"
+  }
+}

package/templates/demo-fixture/.env.example

@@ -0,0 +1,5 @@
+# Required at boot — see docs-canonical/ENVIRONMENT.md for context.
+DATABASE_URL=postgres://acme:devpass@localhost:5432/payments
+STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxx
+# Intentional drift: JWT_SECRET is used in code but NOT documented in ENVIRONMENT.md
+JWT_SECRET=change-me-in-prod

package/templates/demo-fixture/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md — Acme Payments
+
+> Rules for AI agents working in this repo.
+
+## Project context
+Acme Payments is a payments microservice. Money is involved — assume every change needs a test.
+
+## Architecture
+Three services: API, Worker, Scheduler. See `docs-canonical/ARCHITECTURE.md` for the canonical map.
+
+## Style
+- ES modules (`.mjs`)
+- Async/await throughout, no callbacks
+- Throw `PaymentError` for domain errors

package/templates/demo-fixture/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+> Note: This demo CHANGELOG is intentionally missing an `[Unreleased]` section
+> so DocGuard's Changelog validator has something to flag.
+
+## [1.4.0] - 2026-04-12
+
+- Add scheduled retry for failed charges
+- Bump Stripe SDK to v15
+
+## [1.3.0] - 2026-03-28
+
+- Initial public release

package/templates/demo-fixture/DRIFT-LOG.md

@@ -0,0 +1,3 @@
+# DRIFT-LOG
+
+> Track intentional deviations from `docs-canonical/`. Every `// DRIFT:` comment in code needs a row here.

package/templates/demo-fixture/README.md

@@ -0,0 +1,17 @@
+# Acme Payments
+
+A payments microservice. Handles charges, refunds, balance lookups.
+
+## Stack
+- Node.js (ES modules)
+- PostgreSQL
+- Stripe for card processing
+
+## Quick start
+
+```bash
+npm install
+npm start
+```
+
+See `docs-canonical/` for the system specs.

package/templates/demo-fixture/docs-canonical/API-REFERENCE.md

@@ -0,0 +1,36 @@
+# API Reference
+
+> All requests require `Authorization: Bearer <jwt>` unless noted.
+
+## Charges
+
+### POST /charge
+Create a new charge.
+
+**Request body**
+```json
+{ "amount_cents": 1000, "currency": "USD", "customer_id": "cus_..." }
+```
+
+**Response** — `201 Created` with the charge object.
+
+### POST /refund
+Refund a previous charge.
+
+**Request body**
+```json
+{ "charge_id": "ch_...", "amount_cents": 1000 }
+```
+
+## Balance
+
+### GET /balance/:customer_id
+Look up a customer's current balance.
+
+**Response**
+```json
+{ "customer_id": "cus_...", "available_cents": 12345 }
+```
+
+<!-- Demo drift: code also exposes POST /webhooks (Stripe callbacks) but it's
+     missing from this reference. DocGuard's API-Surface validator catches it. -->

package/templates/demo-fixture/docs-canonical/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# ARCHITECTURE — Acme Payments
+
+> The system has **3 services**. (Demo drift: code actually has 4 — see `src/`.)
+
+## Components
+
+```
+┌───────────┐   queue   ┌──────────┐   cron   ┌────────────┐
+│   API     │ ────────> │  Worker  │ <─────── │ Scheduler  │
+│ (HTTP)    │           │ (jobs)   │          │ (timers)   │
+└───────────┘           └──────────┘          └────────────┘
+```
+
+### API
+Handles HTTP requests. Routes live in `src/api.mjs`.
+
+### Worker
+Consumes the job queue. Long-running tasks (capture, refund settlement).
+
+### Scheduler
+Cron-style triggers for retries and reconciliation.
+
+## Data flow
+1. Client POSTs to `/charge` → API validates → enqueues `process_charge` job
+2. Worker dequeues → calls Stripe → writes result to DB
+3. Scheduler reruns failed charges hourly
+
+## See also
+- `DATA-MODEL.md` for the persistence layer
+- `SECURITY.md` for auth + secrets handling

package/templates/demo-fixture/docs-canonical/DATA-MODEL.md

@@ -0,0 +1,30 @@
+# Data Model
+
+## charges
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | `uuid` (PK) | |
+| `customer_id` | `text` | |
+| `amount_cents` | `bigint` | |
+| `currency` | `text` | ISO-4217 |
+| `status` | `text` | `pending` / `succeeded` / `failed` |
+| `stripe_id` | `text` | nullable |
+| `created_at` | `timestamptz` | default now() |
+
+## refunds
+
+| Column | Type |
+|--------|------|
+| `id` | `uuid` (PK) |
+| `charge_id` | `uuid` (FK → charges) |
+| `amount_cents` | `bigint` |
+| `created_at` | `timestamptz` |
+
+## customers
+
+| Column | Type |
+|--------|------|
+| `id` | `text` (PK, `cus_...`) |
+| `email` | `text` |
+| `created_at` | `timestamptz` |

package/templates/demo-fixture/docs-canonical/ENVIRONMENT.md

@@ -0,0 +1,20 @@
+# Environment
+
+Required environment variables.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DATABASE_URL` | Yes | Postgres connection string |
+| `STRIPE_SECRET_KEY` | Yes | Stripe API key (server-side) |
+| `REDIS_URL` | Yes | Redis URL for the job queue |
+
+<!-- Demo drift: REDIS_URL is documented here but missing from .env.example.
+     Also, JWT_SECRET is in .env.example + used in code, but not listed here.
+     DocGuard's Environment validator catches both. -->
+
+## Local development
+
+```bash
+cp .env.example .env
+# Fill in the values above
+```

package/templates/demo-fixture/docs-canonical/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+## Authentication
+HTTP API requires `Authorization: Bearer <jwt>`. Tokens are signed with `JWT_SECRET`.
+
+## Secrets
+- `STRIPE_SECRET_KEY` — never logged
+- `JWT_SECRET` — rotated quarterly
+
+## Threat model
+- Card data is never stored locally — Stripe-tokenized only
+- `JWT_SECRET` rotation invalidates outstanding sessions (acceptable for an internal API)
+
+## Audit log
+Every charge / refund writes to the `audit_events` table.

package/templates/demo-fixture/docs-canonical/TEST-SPEC.md

@@ -0,0 +1,10 @@
+# Test Spec
+
+## Coverage rules
+- Every route in `src/api.mjs` must have an integration test in `tests/api/`
+- Every worker job must have a unit test in `tests/worker/`
+
+## Layers
+- **Unit** — pure logic, no I/O
+- **Integration** — hits a local Postgres + Stripe in test mode
+- **E2E** — against a staging stack (rare; only for release candidates)

package/templates/demo-fixture/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "acme-payments",
+  "version": "1.4.0",
+  "description": "Demo project for DocGuard — a 4-service payments API with intentional doc drift.",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node src/api.mjs"
+  }
+}

package/templates/demo-fixture/src/api.mjs

@@ -0,0 +1,18 @@
+// API service — handles HTTP routes.
+import { createServer } from 'node:http';
+
+// Routes intentionally include /webhooks (not in API-REFERENCE.md — demo drift)
+const ROUTES = {
+  'POST /charge':            createCharge,
+  'POST /refund':            createRefund,
+  'GET /balance/:customer':  getBalance,
+  'POST /webhooks':          handleStripeWebhook,   // ← undocumented
+};
+
+async function createCharge(req)  { /* ... */ }
+async function createRefund(req)  { /* ... */ }
+async function getBalance(req)    { /* ... */ }
+async function handleStripeWebhook(req) { /* ... */ }
+
+const PORT = process.env.PORT || 3000;
+createServer((req, res) => { /* router */ }).listen(PORT);

package/templates/demo-fixture/src/notifier.mjs

@@ -0,0 +1,23 @@
+// Notifier service — emails / Slack alerts on big charges or failures.
+// ⚠️ Demo drift: ARCHITECTURE.md only mentions 3 services (API, Worker, Scheduler).
+//    This fourth one (Notifier) is in code but missing from the architecture doc.
+//    DocGuard's Docs-Diff + Docs-Coverage validators surface this.
+
+import { Stripe } from './lib/stripe.mjs';
+
+export async function notifyLargeCharge(charge) {
+  if (charge.amount_cents > 100000) {
+    await sendSlack(`💰 Large charge: $${charge.amount_cents / 100}`);
+  }
+}
+
+export async function notifyFailure(charge, error) {
+  await sendEmail({
+    to: 'oncall@acme.dev',
+    subject: `Charge failed: ${charge.id}`,
+    body: error.message,
+  });
+}
+
+async function sendSlack(text) { /* ... */ }
+async function sendEmail(opts) { /* ... */ }

package/templates/demo-fixture/src/scheduler.mjs

@@ -0,0 +1,8 @@
+// Scheduler service — cron-style triggers.
+import { enqueue } from './queue.mjs';
+
+// Retry failed charges hourly
+setInterval(async () => {
+  const failed = await db.query('SELECT id FROM charges WHERE status = $1', ['failed']);
+  for (const row of failed.rows) await enqueue({ type: 'process_charge', charge_id: row.id });
+}, 60 * 60 * 1000);

package/templates/demo-fixture/src/worker.mjs

@@ -0,0 +1,15 @@
+// Worker service — consumes job queue.
+import { connect } from './queue.mjs';
+
+const handlers = {
+  process_charge: async (job)   => { /* call Stripe */ },
+  process_refund: async (job)   => { /* call Stripe refund API */ },
+  settle_refund:  async (job)   => { /* mark refund as settled */ },
+};
+
+const queue = await connect(process.env.REDIS_URL);
+queue.consume(async (job) => {
+  const handler = handlers[job.type];
+  if (!handler) throw new Error(`Unknown job: ${job.type}`);
+  await handler(job);
+});