deuk-agent-rule 2.5.13 → 3.3.2

package/scripts/cli.mjs

@@ -2,18 +2,18 @@
 import { existsSync, rmSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { parseArgs, parseTicketArgs } from "./cli-args.mjs";
+import { parseArgs, parseTicketArgs, parseSkillArgs, parseTelemetryArgs } from "./cli-args.mjs";
 import { runInit, runMerge } from "./cli-init-commands.mjs";
-import { runTicketCreate, runTicketList, runTicketUse, runTicketClose, runTicketArchive, runTicketReports, runTicketMeta, runTicketConnect } from "./cli-ticket-commands.mjs";
-import { performUpgradeMigration } from "./cli-ticket-logic.mjs";
-import { loadInitConfig, writeInitConfig, checkUpdateNotifier } from "./cli-utils.mjs";
+import { runTicketCreate, runTicketList, runTicketUse, runTicketClose, runTicketArchive, runTicketReports, runTicketMeta, runTicketConnect, runTicketRebuild, runTicketReportAttach, runTicketMove, runTicketNext, runTicketHotfix, runTicketStatus, runTicketHandoff, runTicketEvidenceCheck, runTicketEvidenceReport } from "./cli-ticket-commands.mjs";
+import { runTelemetry } from "./cli-telemetry-commands.mjs";
+import { performUpgradeMigration } from "./cli-ticket-migration.mjs";
+import { loadInitConfig, writeInitConfig, checkUpdateNotifier, normalizeWorkflowMode, WORKFLOW_MODE_EXECUTE, AGENT_ROOT_DIR, resolveWorkflowMode, LEGACY_TEMPLATE_DIR, LEGACY_CONFIG_FILE } from "./cli-utils.mjs";
 import { runInteractive } from "./cli-prompts.mjs";
 
 const updatePromise = checkUpdateNotifier();
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgRoot = join(__dirname, "..");
-const bundleRoot = join(pkgRoot, "bundle");
 async function main() {
   const argv = process.argv.slice(2);
   const sub = argv[0];
@@ -30,11 +30,29 @@ async function main() {
     if (action === "create") await runTicketCreate(opts);
     else if (action === "list") await runTicketList(opts);
     else if (action === "use") await runTicketUse(opts);
+    else if (action === "next") await runTicketNext(opts);
+    else if (action === "evidence") await runTicketEvidenceCheck(opts);
     else if (action === "close") await runTicketClose(opts);
     else if (action === "archive") await runTicketArchive(opts);
     else if (action === "reports") await runTicketReports(opts);
     else if (action === "meta") await runTicketMeta(opts);
     else if (action === "connect") await runTicketConnect(opts);
+    else if (action === "rebuild") await runTicketRebuild(opts);
+    else if (action === "move" || action === "step") await runTicketMove(opts);
+    else if (action === "hotfix") await runTicketHotfix(opts);
+    else if (action === "status") await runTicketStatus(opts);
+    else if (action === "handoff" || action === "continue") await runTicketHandoff(opts);
+    else if (action === "report") {
+      const subAction = rest[1];
+      if (subAction === "attach") {
+        const attachOpts = parseTicketArgs(rest.slice(2));
+        await runTicketReportAttach(attachOpts);
+      } else if (opts.claim) {
+        await runTicketEvidenceReport(opts);
+      } else {
+        await runTicketReports(opts);
+      }
+    }
     else if (action === "upgrade" || action === "migrate") {
       const count = performUpgradeMigration(opts.cwd, opts);
       console.log(`Migration complete: ${count} tickets upgraded.`);
@@ -46,6 +64,39 @@ async function main() {
     return;
   }
 
+  if (sub === "telemetry") {
+    const opts = parseTelemetryArgs(rest);
+    await runTelemetry(opts);
+    return;
+  }
+
+  if (sub === "skill") {
+    const action = rest[0];
+    const opts = parseSkillArgs(rest.slice(1));
+    const { runSkill } = await import("./cli-skill-commands.mjs");
+    await runSkill(action, opts);
+    return;
+  }
+
+  if (sub === "lint:md" || sub === "lint-md") {
+    const { runMarkdownLint } = await import("./lint-md.mjs");
+    runMarkdownLint(rest);
+    return;
+  }
+
+  if (sub === "rules") {
+    const action = rest[0];
+    const opts = parseArgs(rest.slice(1));
+    if (action === "audit") {
+      const { runRulesAudit } = await import("./lint-rules.mjs");
+      runRulesAudit(opts);
+      return;
+    }
+    console.error("Unknown rules action: " + action);
+    printHelp();
+    return;
+  }
+
   if (sub === "init" || sub === "merge") {
     const opts = parseArgs(rest);
     if (opts.help) {
@@ -59,13 +110,13 @@ async function main() {
       for (const key in saved) {
         if (opts[key] === undefined) opts[key] = saved[key];
       }
-      console.log(`Using saved config from .deuk-agent-rule.config.json (CLI overrides applied)`);
+      console.log(`Using saved config from ${AGENT_ROOT_DIR}/config.json (CLI overrides applied)`);
     }
 
     if (sub === "init") {
-      await handleInit(opts);
+      await handleInit(opts, saved);
     } else {
-      runMerge(opts, bundleRoot);
+      runMerge(opts, pkgRoot);
     }
     return;
   }
@@ -76,24 +127,31 @@ async function main() {
 
 // Removed legacy migration runTicketMigrate
 
-async function handleInit(opts) {
+async function handleInit(opts, saved) {
   if (opts.clean && !opts.dryRun) {
     console.log(`[CLEAN] Removing legacy templates and config...`);
-    const templatesDir = join(opts.cwd, ".deuk-agent-templates");
-    const configFile = join(opts.cwd, ".deuk-agent-rule.config.json");
+    const templatesDir = join(opts.cwd, LEGACY_TEMPLATE_DIR);
+    const configFile = join(opts.cwd, LEGACY_CONFIG_FILE);
     if (existsSync(templatesDir)) rmSync(templatesDir, { recursive: true, force: true });
     if (existsSync(configFile)) rmSync(configFile, { force: true });
   }
 
-  if (!opts.interactive && !opts.nonInteractive && !loadInitConfig(opts.cwd)) {
+  if (!opts.interactive && !opts.nonInteractive && !saved) {
     // If no config and not interactive, prompt unless non-interactive
     await runInteractive(opts);
-    if (!opts.dryRun) writeInitConfig(opts.cwd, opts);
   } else if (opts.interactive) {
     await runInteractive(opts);
-    if (!opts.dryRun) writeInitConfig(opts.cwd, opts);
   }
-  await runInit(opts, bundleRoot);
+
+  if (!opts.dryRun) writeInitConfig(opts.cwd, opts);
+
+  const workflowMode = resolveWorkflowMode(opts, saved);
+  if (!opts.dryRun && workflowMode !== WORKFLOW_MODE_EXECUTE) {
+    console.log(`[WORKFLOW] Plan mode active. Re-run with --workflow execute or --approval approved to apply file mutations.`);
+    return;
+  }
+
+  await runInit(opts, pkgRoot);
 }
 
 function printHelp() {
@@ -102,7 +160,11 @@ function printHelp() {
 Usage:
   npx deuk-agent-rule init   [options]
   npx deuk-agent-rule merge  [options]
-  npx deuk-agent-rule ticket <create|list|use|close|archive|reports|migrate|upgrade|meta|connect> [options]
+  npx deuk-agent-rule lint:md [--cwd <path>] [files...]
+  npx deuk-agent-rule rules audit [--compact|--json]
+  npx deuk-agent-rule skill <list|add|expose|lint> [options]
+  npx deuk-agent-rule ticket <create|evidence|list|status|handoff|continue|use|close|archive|reports|migrate|upgrade|meta|connect|move> [options]
+  npx deuk-agent-rule telemetry <log|sync|summary|migrate> [options]
 
 Options:
   --cwd <path>          Target repo root
@@ -110,19 +172,37 @@ Options:
   --non-interactive     CI/scripts mode: no prompts
   --tag <id>            Custom marker ID (default: deuk-agent-rule)
   --agents <mode>       inject | skip | overwrite
-  --rules <mode>        prefix | skip | overwrite
   --cursorrules <mode>  inject | skip | overwrite
+  --workflow <mode>     plan | execute
+  --approval <state>    pending | approved (alias for workflow)
+  --docs-language <lang> auto | ko | en
   --json                Output result in JSON format
   --remote <url>        Temporary pipeline URL
   --sync                Force enable remote sync
   --no-sync             Force disable remote sync
 
+Skill Options:
+  --skill, --id <name>  Skill ID (safe-refactor|generated-file-guard|context-recall)
+  --platform <name>     Exposure target (claude|cursor)
+
 Ticket Options:
-  --topic <name>        Ticket topic slug
+  --topic, --id <name>  Ticket topic slug or ID
   --group <name>        Ticket group (sub|main|discussion)
   --project <name>      Project filter (DeukUI|DeukAgentRules)
   --submodule <name>    Submodule filter (DeukPack|DeukUI)
-  --latest              Use most recent ticket (default if no topic)
+  --docs-language <lang> auto | ko | en
+  --evidence <text>     Provide Phase 0 RAG evidence summary
+  --claim <text>        Validate or report only from ticket evidence matching this claim
+  --skip-phase0         Bypass Phase 0 RAG validation
+  --plan-body <text>    Create ticket with filled Phase 1 markdown body
+  --require-filled      Enforce non-placeholder APC and compact plan content before create succeeds
+  --allow-placeholder   Opt out of strict create guard (legacy behavior)
+  --compact             Prefer one-line ticket outputs in automation flows
+  --status-detail       Include detailed reasons in ticket status output
+  --handoff             Emit compact handoff output for session continuation
+  --phase <number>      Explicitly set the phase number (e.g., --phase 2)
+  --next                Move to the next phase
+  --latest, -l          Use most recent ticket (default if no topic)
   --path-only           Print only the file path
   --json                Output result in JSON format
 `);

package/scripts/lint-md.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, relative, dirname, resolve } from "path";
+import { spawnSync } from "child_process";
+import YAML from "yaml";
+import { AGENT_ROOT_DIR, TICKET_DIR_NAME } from "./cli-utils.mjs";
+
+const ignoredDirs = new Set([".git", "node_modules"]);
+
+export function collectChangedFiles(repoRoot) {
+  const changed = new Set();
+
+  const gitArgs = ["-C", repoRoot, "diff", "--name-only", "--diff-filter=ACMRTUXB"];
+  const gitDiff = spawnSync("git", gitArgs, { encoding: "utf8" });
+  if (gitDiff.status === 0) {
+    gitDiff.stdout
+      .split("\n")
+      .map(s => s.trim())
+      .filter(Boolean)
+      .forEach(f => changed.add(f));
+  }
+
+  const gitUntracked = spawnSync("git", ["-C", repoRoot, "ls-files", "--others", "--exclude-standard"], { encoding: "utf8" });
+  if (gitUntracked.status === 0) {
+    gitUntracked.stdout
+      .split("\n")
+      .map(s => s.trim())
+      .filter(Boolean)
+      .forEach(f => changed.add(f));
+  }
+
+  return Array.from(changed).sort();
+}
+
+export function collectChangedMarkdownFiles(repoRoot) {
+  return collectChangedFiles(repoRoot).filter(isMarkdownFile);
+}
+
+function isMarkdownFile(filePath) {
+  const lower = filePath.toLowerCase();
+  return lower.endsWith(".md") || lower.endsWith(".mdx") || lower.endsWith(".markdown");
+}
+
+function isPlanReport(relPath) {
+  return relPath.includes(`${AGENT_ROOT_DIR}/docs/plan/`) && relPath.endsWith("-report.md");
+}
+
+const LEGACY_ARCHIVED_TEMPLATE_NAMES = new Set([
+  "module-rule-template.md",
+  "ticket-list-template.md",
+  "ticket-template-ko.md",
+  "ticket-template.md"
+]);
+
+function isLegacyArchivedTemplateArtifact(relPath, content) {
+  const normalized = relPath.replace(/\\/g, "/");
+  if (!normalized.includes(`${TICKET_DIR_NAME}/archive/`)) return false;
+  if (!LEGACY_ARCHIVED_TEMPLATE_NAMES.has(normalized.split("/").pop())) return false;
+
+  const src = String(content || "");
+  return src.includes("<%=") || src.includes("<%-") || /^id:\s*(module-rule-template|ticket-list-template|ticket-template-ko|ticket-template)\s*$/m.test(src);
+}
+
+function lintWalkthroughReportStructure(relPath, content) {
+  const errors = [];
+  const hasSummary = /##\s+(Summary|요약)(?:\s|$)/i.test(content);
+  const hasVerification = /##\s+(Verification|검증)(?:\s|$)/i.test(content);
+  const hasOutcome = /##\s+(Verification Outcome|Verification Results|검증 결과)(?:\s|$)/i.test(content);
+
+  if (!hasSummary) {
+    errors.push(`${relPath}: report missing Summary/요약 section`);
+  }
+  if (!hasVerification) {
+    errors.push(`${relPath}: report missing Verification/검증 section`);
+  }
+  if (!hasOutcome) {
+    errors.push(`${relPath}: report missing Verification Outcome/Verification Results/검증 결과 section`);
+  }
+
+  return errors;
+}
+
+function walkMarkdownFiles(rootDir, out = []) {
+  for (const entry of readdirSync(rootDir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (ignoredDirs.has(entry.name)) continue;
+      walkMarkdownFiles(join(rootDir, entry.name), out);
+      continue;
+    }
+    const filePath = join(rootDir, entry.name);
+    if (isMarkdownFile(filePath)) out.push(filePath);
+  }
+  return out;
+}
+
+function lintFile(absPath, repoRoot) {
+  const rel = relative(repoRoot, absPath);
+  const content = readFileSync(absPath, "utf8");
+  const errors = [];
+
+  if (isLegacyArchivedTemplateArtifact(rel, content)) {
+    return errors;
+  }
+
+  const lines = content.split(/\r?\n/);
+  lines.forEach((line, idx) => {
+    if (/\s+$/.test(line)) {
+      errors.push(`${rel}:${idx + 1}: trailing whitespace`);
+    }
+  });
+
+  const fenceCount = lines.filter(line => /^```/.test(line.trim())).length;
+  if (fenceCount % 2 !== 0) {
+    errors.push(`${rel}: unmatched fenced code block`);
+  }
+
+  if (content.startsWith("---\n") || content.startsWith("---\r\n")) {
+    const match = content.match(/^---\r?\n([\s\S]+?)\r?\n---\r?\n?/);
+    if (!match) {
+      const afterOpeningRule = content.replace(/^---\r?\n/, "");
+      if (!/^\s*\r?\n#{1,6}\s/.test(afterOpeningRule)) {
+        errors.push(`${rel}: invalid or unterminated frontmatter`);
+      }
+    } else {
+      try {
+        const parsed = YAML.parse(match[1]);
+        const isDeukAgentDoc = rel.includes(`${AGENT_ROOT_DIR}/docs/`) || rel.includes(`${AGENT_ROOT_DIR}/tickets/`);
+        const isArchive = rel.includes("archive/");
+        const isTemplate = rel.includes("templates/");
+        if (isDeukAgentDoc && !isArchive && !isTemplate) {
+          const requiredKeys = ["summary", "status", "priority", "tags"];
+          for (const key of requiredKeys) {
+            if (!parsed || parsed[key] === undefined || parsed[key] === null || parsed[key] === "") {
+              errors.push(`${rel}: missing required frontmatter key: ${key}`);
+            }
+          }
+        }
+      } catch (err) {
+        errors.push(`${rel}: invalid frontmatter YAML (${err.message})`);
+      }
+    }
+  } else {
+    const isDeukAgentDoc = rel.includes(`${AGENT_ROOT_DIR}/docs/`) || rel.includes(`${AGENT_ROOT_DIR}/tickets/`);
+    const isArchive = rel.includes("archive/");
+    const isTemplate = rel.includes("templates/");
+    if (isDeukAgentDoc && !isArchive && !isTemplate) {
+      errors.push(`${rel}: missing required frontmatter`);
+    }
+  }
+
+  const linkPattern = /!?\[[^\]]+\]\(([^)]+)\)/g;
+  let match;
+  while ((match = linkPattern.exec(content)) !== null) {
+    const target = String(match[1] || "").trim();
+    if (!target || target.startsWith("#") || /^[a-z]+:\/\//i.test(target) || target.startsWith("mailto:")) {
+      continue;
+    }
+    const pathOnly = target.split("#")[0].split("?")[0];
+    if (!pathOnly) continue;
+    const resolved = join(dirname(absPath), pathOnly);
+    if (!statExists(resolved)) {
+      errors.push(`${rel}: broken relative link -> ${target}`);
+    }
+  }
+
+  if (isPlanReport(rel)) {
+    errors.push(...lintWalkthroughReportStructure(rel, content));
+  }
+
+  return errors;
+}
+
+function statExists(absPath) {
+  try {
+    return statSync(absPath).isFile() || statSync(absPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function resolveMarkdownLintTargets(repoRoot, explicitPaths = []) {
+  const files = explicitPaths.length > 0
+    ? explicitPaths.map(p => resolve(repoRoot, p)).filter(statExists).filter(isMarkdownFile)
+    : collectChangedMarkdownFiles(repoRoot).map(p => join(repoRoot, p));
+
+  const targets = files.length > 0 ? files : walkMarkdownFiles(repoRoot);
+  return Array.from(new Set(targets));
+}
+
+function parseLintArgs(argv) {
+  const out = { cwd: process.cwd(), paths: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--cwd") {
+      out.cwd = argv[++i] || out.cwd;
+    } else if (arg.startsWith("--cwd=")) {
+      out.cwd = arg.slice("--cwd=".length);
+    } else if (!arg.startsWith("-")) {
+      out.paths.push(arg);
+    }
+  }
+  return out;
+}
+
+export function lintMarkdownPaths(paths, cwd = process.cwd()) {
+  const repoRoot = resolve(cwd);
+  const targets = Array.from(new Set(
+    (Array.isArray(paths) ? paths : [])
+      .map(p => resolve(repoRoot, p))
+      .filter(statExists)
+      .filter(isMarkdownFile)
+  ));
+  const errors = [];
+  for (const filePath of targets) {
+    errors.push(...lintFile(filePath, repoRoot));
+  }
+  return { repoRoot, targets, errors };
+}
+
+export function runMarkdownLint(argv = process.argv.slice(2)) {
+  const opts = parseLintArgs(argv);
+  const repoRoot = resolve(opts.cwd);
+  const targets = opts.paths.length > 0
+    ? lintMarkdownPaths(opts.paths, opts.cwd).targets
+    : resolveMarkdownLintTargets(repoRoot);
+  const errors = [];
+  for (const filePath of targets) {
+    errors.push(...lintFile(filePath, repoRoot));
+  }
+
+  if (targets.length === 0) {
+    console.log("lint:md: no markdown files found");
+    return;
+  }
+
+  if (errors.length > 0) {
+    console.error("lint:md failed");
+    for (const err of errors) console.error(`- ${err}`);
+    process.exit(1);
+  }
+
+  console.log(`lint:md passed (${targets.length} file${targets.length === 1 ? "" : "s"})`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runMarkdownLint();
+}

package/scripts/lint-rules.mjs

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+
+const RULE_CHECKS = [
+  {
+    code: "DR-KERNEL-01",
+    message: "Compact kernel must keep ticket-first and tool-contract invariants at the top of the core rules.",
+    test: (rules) => /## Compact Kernel/i.test(rules)
+      && /Tools own detail/i.test(rules)
+      && /No ticket, no writes/i.test(rules)
+      && /Every phase must request and satisfy the tool-provided contract/i.test(rules)
+      && /Phase state has two records/i.test(rules)
+      && /Verification is mandatory/i.test(rules)
+      && /never bypass ticket, scope, generated-file, or verification gates/i.test(rules)
+  },
+  {
+    code: "DR-TOKEN-01",
+    message: "Low-token mode must stay quiet and compact.",
+    test: (rules) => /Silent-by-default is mandatory/i.test(rules)
+      && /Keep chat compact/i.test(rules)
+      && /Final answers must be short but complete enough/i.test(rules)
+      && /짧게|매우 짧게|한 줄로|간단히/i.test(rules)
+      && /one-sentence or bullet-only/i.test(rules)
+      && /avoid repeating them in chat/i.test(rules)
+  },
+  {
+    code: "DR-PRIORITY-01",
+    message: "Rules must define pointer/core/project instruction precedence.",
+    test: (rules) => /## 0\. Priority/i.test(rules)
+      && /Global DeukAgentRules pointer/i.test(rules)
+      && /Local generated pointer\/spoke/i.test(rules)
+      && /core-rules\/AGENTS\.md/i.test(rules)
+      && /PROJECT_RULE\.md/i.test(rules)
+  },
+  {
+    code: "DR-BOOT-01",
+    message: "Boot sequence must load core rules, project rules, and ticket context.",
+    test: (rules) => /Boot Sequence \(run once\)/i.test(rules)
+      && /Read this file \(AGENTS\.md\)/i.test(rules)
+      && /Read `PROJECT_RULE\.md`/i.test(rules)
+      && /set_workflow_context\(project, ticket_id, phase\)/i.test(rules)
+      && /clickable ticket-start line/i.test(rules)
+  },
+  {
+    code: "DR-TICKET-01",
+    message: "First-turn and discovery behavior must stay ticket-first.",
+    test: (rules) => /First-Turn Invariant/i.test(rules)
+      && /Ticket Discovery \(1-CALL RULE\)/i.test(rules)
+      && /create the ticket first/i.test(rules)
+      && /Do not use `ticket list` for discovery/i.test(rules)
+  },
+  {
+    code: "DR-CHANGE-01",
+    message: "Phase contract must require tool-provided requirements and block shortcuts.",
+    test: (rules) => /Phase Contract/i.test(rules)
+      && /complete requirement bundle/i.test(rules)
+      && /Required ticket fields\/tasks/i.test(rules)
+      && /Scope boundaries, generated\/source mapping/i.test(rules)
+      && /Do not invent a shortcut/i.test(rules)
+  },
+  {
+    code: "DR-LIFECYCLE-01",
+    message: "Lifecycle must cover phases, durable records, and compact chat.",
+    test: (rules) => /Ticket Lifecycle/i.test(rules)
+      && /Phase 0/i.test(rules)
+      && /Phase 4/i.test(rules)
+      && /findings, hypotheses, scope, compact plan, and phase contract/i.test(rules)
+      && /affected files, and residual risk/i.test(rules)
+      && /Keep chat compact once the ticket carries the durable record/i.test(rules)
+  },
+  {
+    code: "DR-GATE-01",
+    message: "Hard stops must block missing contracts, unsafe scope, and premature execution.",
+    test: (rules) => /Hard Stops/i.test(rules)
+      && /missing phase contract/i.test(rules)
+      && /generated\/source uncertainty/i.test(rules)
+      && /shared-interface changes/i.test(rules)
+      && /read-only until the ticket records findings/i.test(rules)
+  },
+  {
+    code: "DR-HALT-01",
+    message: "Kernel must still define halt conditions and file guards.",
+    test: (rules) => /Hard Stops/i.test(rules)
+      && /generated\/source uncertainty/i.test(rules)
+      && /missing tests/i.test(rules)
+  },
+  {
+    code: "DR-CHURN-01",
+    message: "Repeated symptom fixes must trigger stabilization instead of ticket churn.",
+    test: (rules) => /Hard Stops/i.test(rules)
+      && /stabilization or root-cause ticket/i.test(rules)
+      && /same failure family/i.test(rules)
+  },
+  {
+    code: "DR-CLI-01",
+    message: "Tool delegation and CLI ownership must stay explicit.",
+    test: (rules) => /Tool Delegation/i.test(rules)
+      && /Use `rg`\/`rg --files` first/i.test(rules)
+      && /Use MCP\/RAG only when local evidence is insufficient/i.test(rules)
+      && /Let CLI own lifecycle enforcement, claim checks, reports, and audits/i.test(rules)
+      && /rules audit/i.test(rules)
+  }
+];
+
+export function auditRules(cwd = process.cwd()) {
+  const rulesPath = join(cwd, "core-rules", "AGENTS.md");
+  if (!existsSync(rulesPath)) {
+    return {
+      ok: false,
+      path: rulesPath,
+      violations: [{ code: "DR-RULES-00", message: "core-rules/AGENTS.md not found" }]
+    };
+  }
+
+  const rules = readFileSync(rulesPath, "utf8");
+  const violations = RULE_CHECKS
+    .filter((check) => !check.test(rules))
+    .map(({ code, message }) => ({ code, message }));
+
+  return { ok: violations.length === 0, path: rulesPath, violations };
+}
+
+export function runRulesAudit(opts = {}) {
+  const result = auditRules(opts.cwd || process.cwd());
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (opts.compact) {
+    console.log(result.ok ? "rules:audit ok" : `rules:audit failed ${result.violations.length}`);
+  } else if (result.ok) {
+    console.log("rules:audit ok");
+  } else {
+    console.error("rules:audit failed");
+    for (const violation of result.violations) {
+      console.error(`${violation.code}: ${violation.message}`);
+    }
+  }
+
+  if (!result.ok) {
+    throw new Error(`rules audit failed: ${result.violations.map((v) => v.code).join(", ")}`);
+  }
+
+  return result;
+}