docguard-cli 0.28.0 → 0.30.0

package/cli/commands/verify.mjs

@@ -1,22 +1,38 @@
 /**
- * Verify Command — `docguard verify --semantic` (LLM field report #5).
+ * Verify Command — `docguard verify` (LLM field reports #5, #11).
  *
- * Surfaces the semantic claims in the canonical docs (documented numbers, limits,
- * and enums) as a structured verification task list for the agent to check
- * against the code. DocGuard does the deterministic discovery; the LLM does the
- * judgment — the same division of labour as `docguard agent`.
+ * Two modes, same division of labour (DocGuard does the deterministic
+ * discovery; the LLM does the judgment — like `docguard agent`):
+ *
+ *   --semantic (default)  Surface the semantic claims in the canonical docs
+ *                         (documented numbers, limits, enums) as a verification
+ *                         task list for the agent to check against the code.
+ *
+ *   --instructions        Audit the agent instruction files themselves
+ *                         (AGENTS.md, CLAUDE.md) for drift: duplicate rules,
+ *                         direct never/always contradictions, stale file
+ *                         pointers, and unknown docguard commands are found
+ *                         deterministically; topically-clustered rule pairs
+ *                         become agent tasks ("do these contradict in
+ *                         practice?"). Inspired by spec-kit's MemoryLint.
  *
  * Read-only. JSON is the machine artifact (the agent-executable task list);
  * text is the human summary.
  *
- *   docguard verify [--semantic] [--format json]
+ *   docguard verify [--semantic | --instructions] [--format json]
  */
 
 import { c } from '../shared.mjs';
 import { detectAgentMode } from '../ensure-skills.mjs';
 import { extractSemanticClaims, buildSemanticVerifyTasks } from '../scanners/semantic-claims.mjs';
+import { auditInstructions } from '../scanners/instruction-audit.mjs';
 
 export function runVerify(projectDir, config, flags) {
+  if (flags.instructions) {
+    runInstructionAudit(projectDir, config, flags);
+    return;
+  }
+
   const isJson = flags.format === 'json';
   const claims = extractSemanticClaims(projectDir, config);
   const tasks = buildSemanticVerifyTasks(claims);
@@ -65,3 +81,74 @@ export function runVerify(projectDir, config, flags) {
   console.log(`  ${c.dim}This is the highest-value bug class and DocGuard can't judge it — an agent must.${c.reset}`);
   console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then read each cited file and confirm the value.${c.reset}\n`);
 }
+
+// ── verify --instructions: agent-instruction drift/conflict audit ───────────
+
+function runInstructionAudit(projectDir, config, flags) {
+  const isJson = flags.format === 'json';
+  const { rules, deterministic, tasks } = auditInstructions(projectDir, config);
+  const { duplicates, negations, stalePointers, staleCommands } = deterministic;
+  const findingCount = duplicates.length + negations.length + stalePointers.length + staleCommands.length;
+
+  if (isJson) {
+    console.log(JSON.stringify({
+      command: 'verify --instructions',
+      project: config.projectName,
+      ruleCount: rules.length,
+      findingCount,
+      findings: deterministic,
+      taskCount: tasks.length,
+      // How to act on this: findings are proven; tasks need judgment.
+      howToVerify: 'The findings are deterministic — fix them directly (delete the duplicate copy, resolve the negation in favour of one rule, repoint or remove stale paths/commands). For each task, read both rules in context and judge whether they contradict in practice; if so, report which should win, why, and which file to edit. DocGuard cannot judge the tasks — they require understanding intent.',
+      tasks,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`${c.bold}🔬 DocGuard Verify — instruction audit${c.reset}`);
+  console.log(`${c.dim}   ${config.projectName} · duplicate / contradictory / stale rules in AGENTS.md + CLAUDE.md${c.reset}\n`);
+
+  if (rules.length === 0) {
+    console.log(`  ${c.green}✅ No instruction rules found (no AGENTS.md/CLAUDE.md, or nothing imperative in them).${c.reset}\n`);
+    return;
+  }
+
+  console.log(`  ${c.dim}${rules.length} rule(s) extracted from ${[...new Set(rules.map(r => r.file))].join(' + ')}${c.reset}\n`);
+
+  if (findingCount === 0) {
+    console.log(`  ${c.green}✅ No duplicate, directly-contradictory, or stale rules found.${c.reset}\n`);
+  } else {
+    console.log(`  ${c.yellow}${findingCount} deterministic finding(s):${c.reset}\n`);
+    for (const d of duplicates) {
+      const where = d.rules.map(r => `${r.file}:${r.line}`).join(` ${c.dim}≡${c.reset} `);
+      console.log(`    ${c.yellow}⚠${c.reset} duplicate rule — ${where}: ${c.dim}"${d.rules[0].text}"${c.reset}`);
+    }
+    for (const n of negations) {
+      console.log(`    ${c.yellow}⚠${c.reset} negation conflict — ${n.a.file}:${n.a.line} ${c.dim}⇄${c.reset} ${n.b.file}:${n.b.line}: ${c.dim}"${n.a.text}" vs "${n.b.text}"${c.reset}`);
+    }
+    for (const s of stalePointers) {
+      console.log(`    ${c.yellow}⚠${c.reset} stale pointer — ${s.file}:${s.line}: ${c.cyan}${s.path}${c.reset} does not exist`);
+    }
+    for (const s of staleCommands) {
+      console.log(`    ${c.yellow}⚠${c.reset} stale command — ${s.file}:${s.line}: ${c.cyan}docguard ${s.command}${c.reset} is not a docguard command`);
+    }
+    console.log('');
+  }
+
+  if (tasks.length > 0) {
+    console.log(`  ${c.yellow}${tasks.length} rule pair(s) for the agent to judge:${c.reset}\n`);
+    for (const t of tasks) {
+      console.log(`  ${c.bold}${t.a.file}:${t.a.line} ↔ ${t.b.file}:${t.b.line}${c.reset} ${c.dim}(shared: ${t.sharedTerms.join(', ')})${c.reset}`);
+      console.log(`    ${c.yellow}A${c.reset} ${c.dim}${t.a.section ? `[${t.a.section}] ` : ''}${c.reset}"${t.a.text}"`);
+      console.log(`    ${c.yellow}B${c.reset} ${c.dim}${t.b.section ? `[${t.b.section}] ` : ''}${c.reset}"${t.b.text}"`);
+      console.log('');
+    }
+
+    const mode = detectAgentMode(projectDir);
+    const cmd = mode === 'llm' ? '/docguard.verify' : 'docguard verify --instructions --format json';
+    console.log(`  ${c.dim}Whether clustered rules contradict in practice is judgment DocGuard can't make — an agent must.${c.reset}`);
+    console.log(`  ${c.dim}Get the machine task list: ${c.cyan}${cmd}${c.dim}, then judge each pair and report which rule should win.${c.reset}\n`);
+  } else if (findingCount === 0) {
+    console.log(`  ${c.dim}(Looks for duplicate/negated rules, dead file pointers, unknown docguard commands, and topically-clustered rule pairs.)${c.reset}\n`);
+  }
+}

package/cli/docguard.mjs

@@ -48,6 +48,7 @@ import { runVerify } from './commands/verify.mjs';
 import { runMemory } from './commands/memory.mjs';
 import { runDemo } from './commands/demo.mjs';
 import { runAgent } from './commands/agent.mjs';
+import { runMcp } from './commands/mcp.mjs';
 import { ensureSkills } from './ensure-skills.mjs';
 
 // ── Shared constants (imported to break circular dependencies) ──────────
@@ -90,8 +91,9 @@ ${c.bold}Tools (situational, but day-to-day useful)${c.reset}
   ${c.green}explain${c.reset}    Explain a validator key, warning text, or finding code (${c.cyan}docguard explain SEC001${c.reset})
   ${c.green}verify${c.reset}     Extract documented numbers/limits/enums for an agent to check vs code (${c.cyan}--semantic${c.reset})
   ${c.green}feedback${c.reset}   Report likely false positives back to DocGuard (local-first + 1-click prefilled issue)
+  ${c.green}mcp${c.reset}        MCP server over stdio — guard/score/explain/verify/diagnose as agent tools
   ${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)
+  ${c.green}trace${c.reset}      Requirements traceability matrix (${c.cyan}--reverse${c.reset} for code→doc map, ${c.cyan}--features${c.reset} for per-feature adherence)
   ${c.green}upgrade${c.reset}    Migrate ${c.cyan}.docguard.json${c.reset} schema + CLI (${c.cyan}--apply --pr${c.reset} for team-wide PR)
   ${c.green}watch${c.reset}      Live mode: re-run guard on file changes
 
@@ -256,7 +258,7 @@ const COMMAND_HELP = {
   },
   trace: {
     summary: 'Requirements traceability matrix.',
-    usage: 'docguard trace [--reverse]',
+    usage: 'docguard trace [--reverse] [--features]',
     flags: [['--reverse', 'Code→doc map instead of doc→code']],
     examples: ['docguard trace', 'docguard trace --reverse'],
   },
@@ -292,9 +294,10 @@ const COMMAND_HELP = {
   },
   verify: {
     summary: 'Extract the semantic claims in your canonical docs — documented numbers, limits, and enums (retention days, rate limits, GSI/role counts, status enums) — as a verification task list the agent checks against the code. This is the highest-value bug class (a doc value that drifted from code) and the one regex/AST cannot judge. DocGuard finds the claims; the LLM confirms them.',
-    usage: 'docguard verify [--semantic] [--format json]',
+    usage: 'docguard verify [--semantic|--instructions] [--format json]',
     flags: [
       ['--semantic', 'Extract documented numbers/limits/enums to verify against code (the current — and default — mode)'],
+      ['--instructions', 'Audit AGENTS.md/CLAUDE.md for duplicate, contradictory, and stale-pointer rules (deterministic findings + agent conflict tasks)'],
       ['--format json', 'Machine-readable task list (the agent-executable artifact)'],
     ],
     examples: ['docguard verify --semantic', 'docguard verify --semantic --format json'],
@@ -375,6 +378,27 @@ async function main() {
       // v0.28 (field report #5): `docguard verify --semantic` extracts
       // documented numbers/enums/limits for the agent to check against code.
       flags.semantic = true;
+    } else if (args[i] === '--instructions') {
+      // v0.30: `docguard verify --instructions` audits AGENTS.md/CLAUDE.md for
+      // duplicate/contradictory/stale rules (MemoryLint-inspired).
+      flags.instructions = true;
+    } else if (args[i] === '--full') {
+      // v0.29: `docguard llms --full` emits llms-full.txt (inline doc bodies,
+      // the Mintlify-popularized companion to the llms.txt index).
+      flags.full = true;
+    } else if (args[i] === '--pack') {
+      // v0.29: `docguard memory --pack` writes .docguard/context-pack.md — a
+      // compact code-truth-stamped session-start context for AI agents.
+      flags.pack = true;
+    } else if (args[i] === '--sync') {
+      // v0.29: `docguard agents --sync` regenerates the agent-file family
+      // (CLAUDE.md, GEMINI.md, copilot-instructions, .cursor rules) from
+      // AGENTS.md — the canonical source. Kills hand-duplication drift.
+      flags.sync = true;
+    } else if (args[i] === '--check') {
+      // v0.29: `docguard agents --check` — CI staleness gate for the synced
+      // agent-file family (exit 2 when a variant is missing or stale).
+      flags.check = true;
     } else if (args[i] === '--plan') {
       flags.plan = true;
     } else if (args[i] === '--since' && args[i + 1]) {
@@ -390,6 +414,9 @@ async function main() {
       flags.changedOnly = true;
     } else if (args[i] === '--reverse') {
       flags.reverse = true;
+    } else if (args[i] === '--features') {
+      // v0.30: `docguard trace --features` — per-feature spec-adherence report.
+      flags.features = true;
     } else if (args[i] === '--history') {
       flags.history = true;
     } else if (args[i] === '--force-redo') {
@@ -512,10 +539,13 @@ async function main() {
   // touch" — so it joins the club to suppress the banner AND ensureSkills'
   // .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';
+  // v0.29: 'sarif' joins 'json' — any machine format where stdout IS the
+  // artifact belongs here, or the banner corrupts the payload.
+  const jsonMode = flags.format === 'json' || flags.format === 'sarif';
   // `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';
+  // `mcp`: stdout IS the JSON-RPC transport — any banner byte corrupts the stream.
+  const headless = jsonMode || flags.write || flags.checkOnly || flags.changedOnly || flags.quiet || flags.plan || command === 'agent' || command === 'mcp';
 
   if (!headless) printBanner();
 
@@ -540,6 +570,8 @@ async function main() {
     'feedback',
     // verify only reads docs and emits a task list — pure report.
     'verify',
+    // mcp serves read-only tools over stdio — scaffolding writes are off-limits.
+    'mcp',
   ]);
 
   // Silent auto-check: install skills/commands if missing. Skip entirely in
@@ -691,6 +723,11 @@ async function main() {
       // drift — the class regex/AST can't see). Read-only.
       runVerify(projectDir, config, flags);
       break;
+    case 'mcp':
+      // MCP stdio server — guard/score/explain/verify-claims/diagnose as tools
+      // for MCP clients. Long-lived; resolves when stdin closes.
+      await runMcp(projectDir, config, flags);
+      break;
     case 'memory':
       runMemory(projectDir, config, flags);
       break;