@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/auto-docs.mjs

@@ -7,7 +7,7 @@
  *   <!-- /AUTO:region-name -->
  *
  * Running regenerateDocs() is idempotent. With check:true it returns whether
- * anything would change without writing files, used by CI to detect drift.
+ * anything would change without writing files — the mode CI uses to detect drift.
  *
  * buildSite() writes site/docs/ from the same sources feeding the AUTO regions
  * so the GitHub Pages site never drifts from the in-repo markdown.
@@ -65,24 +65,30 @@ function buildCoreDocsContract() {
     '',
     '| File | Purpose | Update when |',
     '|---|---|---|',
+    '| `AGENTS.md` | Canonical agent operating contract | Workflow rules, tracker hierarchy, or repo-wide guardrails change |',
     '| `.cx/context.md` | Human-readable resumable project context | Active work, decisions, architecture assumptions, or open questions change |',
     '| `.cx/context.json` | Machine-readable resumable context | Context state needs to stay in sync with `.cx/context.md` |',
-    '| `.cx/workflow.json` | Canonical workflow/task state | Non-trivial work starts, changes phase, or completes |',
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
-    '| `docs/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
+    '| `docs/concepts/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
-    'All LLMs working in the repo, including Construct, must read these as project state and keep them current when work changes project reality.',
+    '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed — durable work belongs in the tracker (Beads or external).',
+    '',
+    'Tracker hierarchy: external tracker (prefer Beads) for durable work, `plan.md` for the local working plan, and cass-memory via MCP `memory` for cross-session recall.',
+    '',
+    '`AGENTS.md` is the canonical agent instruction file. On case-sensitive filesystems you may also add a lowercase `agents.md` shim for tools that require it.',
+    'All LLMs working in the repo, including Construct, must read these as project state, keep them current when work changes project reality, and prune stale sections instead of letting managed docs drift.',
   ].join('\n');
 }
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
+  apps: 'User-facing apps shipped from this repo (e.g., apps/docs/ — Fumadocs docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
   codex: 'GitHub Copilot / Codex integration',
   docs: 'Architecture notes, runbooks, and documentation contract',
-  langfuse: 'Langfuse trace backend for agent observability',
+  telemetry: 'Telemetry backend for agent observability',
   lib: 'Core runtime: CLI, hooks, MCP, status, sync, workflow',
   opencode: 'OpenCode integration config',
   personas: 'Persona prompt definitions',
@@ -166,7 +172,7 @@ function buildAgentsTable(rootDir) {
 // --- public API ---
 
 /**
- * Regenerate all AUTO regions in README.md and docs/README.md/docs/architecture.md.
+ * Regenerate all AUTO regions in README.md, docs/README.md, and docs/concepts/architecture.md.
  * Returns { changed: string[], checked: boolean }.
  * With check:true writes nothing and sets changed to files that would differ.
  */
@@ -184,7 +190,7 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
       },
     },
     {
-      file: path.join(rootDir, 'docs', 'architecture.md'),
+      file: path.join(rootDir, 'docs', 'concepts', 'architecture.md'),
       regions: {
         agents: buildAgentsTable(rootDir),
       },
@@ -223,71 +229,245 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
 }
 
 /**
- * Write site/docs/ from the same generators feeding the AUTO regions.
- * Invoked by `construct docs:site` before `mkdocs build`.
+ * Check CLI command coverage against how-to links in docs/README.md.
+ *
+ * Returns an object with:
+ *   - covered: string[]    commands that have a linked how-to
+ *   - uncovered: string[]  commands with no how-to link in docs/README.md
+ *   - total: number
+ *
+ * A command is considered covered if its name appears in any markdown link
+ * inside the how-to guides section of docs/README.md.
  */
-export async function buildSite({ rootDir } = {}) {
+export function checkDocsCoverage({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
-  const siteDocsDir = path.join(rootDir, 'site', 'docs');
-  fs.mkdirSync(siteDocsDir, { recursive: true });
-  fs.mkdirSync(path.join(siteDocsDir, 'templates'), { recursive: true });
-
-  const readOrEmpty = (p) => readFile(p) ?? '';
-  const writeTransformed = (src, dest, transform = (content) => content) => {
-    const content = readFile(src);
-    if (content) fs.writeFileSync(path.join(siteDocsDir, dest), transform(content));
-  };
-
-  // index.md — strip the "For contributors" section onwards for a user-facing landing
-  const readme = readOrEmpty(path.join(rootDir, 'README.md'));
-  const cutAt = readme.indexOf('## For contributors');
-  const index = cutAt > 0 ? readme.slice(0, cutAt).trimEnd() + '\n' : readme;
-  fs.writeFileSync(path.join(siteDocsDir, 'index.md'), index);
-
-  // commands.md — full CLI reference
-  const cmdLines = [
-    '<!--\nsite/docs/commands.md — full CLI reference, generated by construct docs:site.\nSource: lib/cli-commands.mjs\n-->\n',
-    '# Command reference\n',
-    buildCommandsTable(),
-  ];
-  fs.writeFileSync(path.join(siteDocsDir, 'commands.md'), cmdLines.join('\n'));
+  const docsReadme = readFile(path.join(rootDir, 'docs', 'README.md')) ?? '';
+
+  // Extract all href targets from markdown links in docs/README.md
+  const linkTargets = [...docsReadme.matchAll(/\[.*?\]\((.*?)\)/g)].map(m => m[1]);
+
+  // Build a combined corpus: docs/README.md + every linked how-to file
+  const howToDir = path.join(rootDir, 'docs', 'how-to');
+  let corpus = docsReadme;
+  for (const target of linkTargets) {
+    if (!target.startsWith('./how-to/')) continue;
+    const filePath = path.join(rootDir, 'docs', target.replace(/^\.\//, ''));
+    const content = readFile(filePath);
+    if (content) corpus += '\n' + content;
+  }
+
+  // Capture command mentions from both inline code (`construct cmd`) and code blocks (bare lines)
+  const mentionedCmds = new Set([
+    ...corpus.matchAll(/`construct\s+([\w:_-]+)`/g),
+    ...corpus.matchAll(/^construct\s+([\w:_-]+)/gm),
+  ].map(m => m[1]));
+
+  // Collect all command names from the registry
+  const allCommands = [];
+  for (const cmds of Object.values(CLI_COMMANDS_BY_CATEGORY)) {
+    for (const cmd of cmds) allCommands.push(cmd.name);
+  }
+
+  // Skip internal / plumbing commands and simple commands covered by getting-started.md
+  const skipList = new Set([
+    'version', 'diff', 'validate', 'docs:update', 'docs:site', 'docs:check', 'sync',
+    'list', 'setup', 'show', 'hosts', 'plugin', 'mcp', 'evals',
+    'telemetry-backfill', 'lint:comments', 'lint:research',
+    // short commands documented in getting-started.md
+    'up', 'down', 'status', 'serve', 'init', 'update', 'doctor',
+    // team sub-commands — covered as part of review how-to
+    'team',
+    // covered in getting-started.md under Memory Layer section
+    'bootstrap', 'memory',
+    // niche overlay command — documented in registry description
+    'headhunt',
+  ]);
+
+  const covered = [];
+  const uncovered = [];
+
+  for (const name of allCommands) {
+    if (skipList.has(name)) continue;
+    const slug = name.replace(':', '-');
+    const isCovered =
+      linkTargets.some(t => t.includes(slug) || t.includes(name)) ||
+      mentionedCmds.has(name);
+    if (isCovered) covered.push(name);
+    else uncovered.push(name);
+  }
+
+  return { covered, uncovered, total: covered.length + uncovered.length };
+}
+
+// Categories surfaced in the Fumadocs reference. Internal commands (e.g.,
+// `construct hook <name>`) are not user-facing reference material.
+const REFERENCE_CATEGORIES = [
+  'Services',
+  'Agents & Sync',
+  'Work',
+  'Embed',
+  'Models & Integrations',
+  'Providers',
+  'Observability',
+  'Docs',
+  'Diagnostics',
+];
+
+function slugify(category) {
+  return category.toLowerCase()
+    .replace(/&/g, 'and')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
 
-  // hooks.md
-  const hooksLines = [
-    '<!--\nsite/docs/hooks.md — hook reference, generated by construct docs:site.\nSource: lib/hooks/\n-->\n',
-    '# Hooks reference\n',
-    'Hooks run in every Claude Code session. They are registered in `claude/settings.template.json`.\n',
+function renderCommandPage(category, commands) {
+  const lines = [];
+  lines.push('---');
+  lines.push(`title: ${category}`);
+  lines.push(`description: ${category} commands for Construct.`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`# ${category}`);
+  lines.push('');
+  lines.push('| Command | What it does |');
+  lines.push('|---|---|');
+  for (const cmd of commands) {
+    lines.push(`| \`construct ${cmd.name}\` | ${cmd.description} |`);
+  }
+  lines.push('');
+  for (const cmd of commands) {
+    lines.push(`## construct ${cmd.name}`);
+    lines.push('');
+    lines.push(cmd.description);
+    lines.push('');
+    if (cmd.usage) {
+      lines.push('**Usage**');
+      lines.push('');
+      lines.push('```bash');
+      lines.push(cmd.usage);
+      lines.push('```');
+      lines.push('');
+    }
+    if (cmd.subcommands && cmd.subcommands.length) {
+      lines.push('**Subcommands**');
+      lines.push('');
+      for (const sub of cmd.subcommands) {
+        lines.push(`- \`${sub}\``);
+      }
+      lines.push('');
+    }
+    if (cmd.options && cmd.options.length) {
+      lines.push('**Options**');
+      lines.push('');
+      lines.push('| Flag | Description |');
+      lines.push('|---|---|');
+      for (const opt of cmd.options) {
+        lines.push(`| \`${opt.flag}\` | ${opt.desc} |`);
+      }
+      lines.push('');
+    }
+  }
+  return lines.join('\n');
+}
+
+function renderHooksPage(rootDir) {
+  return [
+    '---',
+    'title: Hooks',
+    'description: Hooks fire during Claude Code sessions, on file edits, commits, pushes, and prompts. Generated from lib/hooks/.',
+    '---',
+    '',
+    '> Generated from `lib/hooks/`. Re-run `construct docs:site` to refresh.',
+    '',
+    'Hooks are wired in `platforms/claude/settings.template.json` and execute as child processes during Claude Code sessions. Each hook reads JSON on stdin, performs its check or transform, and exits with a status that signals whether the surrounding tool call should proceed.',
+    '',
     buildHooksTable(rootDir),
-  ];
-  fs.writeFileSync(path.join(siteDocsDir, 'hooks.md'), hooksLines.join('\n'));
-
-  // agents.md
-  const agentsTable = buildAgentsTable(rootDir);
-  if (agentsTable) {
-    const agentLines = [
-      '<!--\nsite/docs/agents.md — agent reference, generated by construct docs:site.\nSource: agents/registry.json\n-->\n',
-      '# Agent reference\n',
-      agentsTable,
-    ];
-    fs.writeFileSync(path.join(siteDocsDir, 'agents.md'), agentLines.join('\n'));
+    '',
+  ].join('\n');
+}
+
+function renderAgentsPage(rootDir) {
+  const table = buildAgentsTable(rootDir);
+  if (!table) return null;
+  return [
+    '---',
+    'title: Agents',
+    'description: The 28 cx-* specialists plus the construct persona. Generated from agents/registry.json.',
+    '---',
+    '',
+    '> Generated from `agents/registry.json`. Re-run `construct docs:site` to refresh.',
+    '',
+    'Construct ships one persona (`construct`) plus 28 specialists. Each specialist has a role, model tier, and prompt that defines its decision authority. Specialists are addressable directly when you want a focused conversation; for everyday work, address `@construct` and let it route.',
+    '',
+    table,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Emit MDX reference pages into docs/reference/ for the Fumadocs site.
+ * Mirrors the data sources behind AUTO regions and buildSite() but writes
+ * Markdown files Fumadocs can render directly (no MkDocs intermediate).
+ */
+export function buildFumadocsReference({ rootDir } = {}) {
+  rootDir = rootDir ?? process.cwd();
+  const refDir = path.join(rootDir, 'docs', 'reference');
+  const cliDir = path.join(refDir, 'cli');
+  fs.mkdirSync(cliDir, { recursive: true });
+
+  const written = [];
+
+  const cliPages = [];
+  for (const category of REFERENCE_CATEGORIES) {
+    const commands = CLI_COMMANDS_BY_CATEGORY[category] ?? [];
+    if (!commands.length) continue;
+    const slug = slugify(category);
+    const out = path.join(cliDir, `${slug}.md`);
+    if (writeIfChanged(out, renderCommandPage(category, commands))) {
+      written.push(path.relative(rootDir, out));
+    }
+    cliPages.push(slug);
   }
 
-  // copy static docs
-  for (const [src, dest] of [
-    [path.join(rootDir, 'docs', 'architecture.md'), 'architecture.md'],
-    [path.join(rootDir, 'CONTRIBUTING.md'), 'contributing.md'],
-    [path.join(rootDir, 'CLAUDE.md'), 'claude.md'],
-  ]) {
-    const content = readFile(src);
-    if (!content) continue;
-    const transformed = dest === 'contributing.md'
-      ? content.replaceAll('[CLAUDE.md](CLAUDE.md)', '[CLAUDE.md](claude.md)')
-      : dest === 'claude.md'
-        ? content.replaceAll('[docs/templates/README.md](docs/templates/README.md)', '[docs/templates/README.md](templates/README.md)')
-        : content;
-    fs.writeFileSync(path.join(siteDocsDir, dest), transformed);
+  const cliMeta = path.join(cliDir, 'meta.json');
+  const cliMetaContent = JSON.stringify({ title: 'CLI', pages: ['index', ...cliPages] }, null, 2) + '\n';
+  if (writeIfChanged(cliMeta, cliMetaContent)) written.push(path.relative(rootDir, cliMeta));
+
+  const cliIndexContent = [
+    '---',
+    'title: CLI',
+    'description: Every construct command, grouped by category. Generated from lib/cli-commands.mjs.',
+    '---',
+    '',
+    '> Generated from `lib/cli-commands.mjs`. Re-run `construct docs:site` to refresh.',
+    '',
+    'Commands are grouped by what they do. Pick a category below.',
+    '',
+    ...REFERENCE_CATEGORIES.map((cat) => {
+      const slug = slugify(cat);
+      const commands = CLI_COMMANDS_BY_CATEGORY[cat] ?? [];
+      if (!commands.length) return null;
+      return `- [${cat}](/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
+    }).filter(Boolean),
+    '',
+  ].join('\n');
+  if (writeIfChanged(path.join(cliDir, 'index.md'), cliIndexContent)) {
+    written.push(path.relative(rootDir, path.join(cliDir, 'index.md')));
   }
 
-  writeTransformed(path.join(rootDir, 'docs', 'templates', 'README.md'), path.join('templates', 'README.md'));
+  const hooksPage = path.join(refDir, 'hooks.md');
+  if (writeIfChanged(hooksPage, renderHooksPage(rootDir))) {
+    written.push(path.relative(rootDir, hooksPage));
+  }
 
+  const agentsContent = renderAgentsPage(rootDir);
+  if (agentsContent) {
+    const agentsPage = path.join(refDir, 'agents.md');
+    if (writeIfChanged(agentsPage, agentsContent)) {
+      written.push(path.relative(rootDir, agentsPage));
+    }
+  }
+
+  return { written };
 }
+

package/lib/beads/auto-close.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/beads-auto-close.mjs — auto-close beads on merge.
+ *
+ * Scans the commit messages on the just-merged range for any
+ * `closes construct-xxx` / `fixes construct-xxx` / `resolves construct-xxx`
+ * references (case-insensitive). For each unique bead id found, runs
+ * `bd close <id> --reason="Auto-closed on merge <sha>: <subject>"` so
+ * the tracker matches reality without manual intervention.
+ *
+ * Invocation: the `.beads/hooks/post-merge` git hook shim runs this,
+ * or `--range=<git-range>` triggers a standalone backfill.
+ *
+ * Exit codes:
+ *   0   no closes referenced, or all closes succeeded
+ *   1   one or more bd close calls failed
+ *   2   could not parse git range / no bd CLI
+ *
+ * Idempotent: closing an already-closed bead is a no-op so re-running
+ * the hook after a merge is safe.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const CLOSES_RE = /\b(?:closes?|close|fix(?:es)?|fixed|resolves?|resolved)\s+(construct-[a-z0-9]+)/gi;
+
+export function parseClosesFromMessage(message) {
+  if (!message) return [];
+  const found = new Set();
+  let match;
+  CLOSES_RE.lastIndex = 0;
+  while ((match = CLOSES_RE.exec(message)) !== null) {
+    found.add(match[1].toLowerCase());
+  }
+  return [...found];
+}
+
+export function listCommitsInRange(range, { runner = spawnSync } = {}) {
+  const result = runner('git', ['log', range, '--pretty=format:%H%x09%s%x09%B%x00'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) return [];
+  return result.stdout
+    .split('\x00')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [sha, subject, ...rest] = entry.split('\t');
+      return { sha, subject, body: rest.join('\t') };
+    });
+}
+
+export function collectAutoCloses(commits) {
+  const closesById = new Map();
+  for (const commit of commits) {
+    const ids = parseClosesFromMessage(`${commit.subject}\n${commit.body}`);
+    for (const id of ids) {
+      if (!closesById.has(id)) closesById.set(id, []);
+      closesById.get(id).push({ sha: commit.sha, subject: commit.subject });
+    }
+  }
+  return closesById;
+}
+
+export function buildAutoCloseReason(commits) {
+  const first = commits[0];
+  if (!first) return 'Auto-closed on merge';
+  const shortSha = first.sha.slice(0, 12);
+  return `Auto-closed on merge ${shortSha}: ${first.subject}`;
+}
+
+/**
+ * Drive the auto-close: list commits in the range, parse closes, invoke
+ * `bd close` for each. Returns a summary the caller can log or test.
+ */
+export async function runAutoClose({ range, runner = spawnSync } = {}) {
+  if (!range) return { ok: false, reason: 'no range', closed: [], failed: [] };
+
+  const commits = listCommitsInRange(range, { runner });
+  if (commits.length === 0) return { ok: true, closed: [], failed: [], commits: 0 };
+
+  const closesById = collectAutoCloses(commits);
+  if (closesById.size === 0) return { ok: true, closed: [], failed: [], commits: commits.length };
+
+  const closed = [];
+  const failed = [];
+  for (const [id, refs] of closesById) {
+    const reason = buildAutoCloseReason(refs);
+    const result = runner('bd', ['close', id, `--reason=${reason}`], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status === 0) {
+      closed.push({ id, sha: refs[0]?.sha, subject: refs[0]?.subject });
+    } else {
+      failed.push({
+        id,
+        exitCode: result.status,
+        stderr: (result.stderr || '').slice(0, 500),
+      });
+    }
+  }
+  return { ok: failed.length === 0, closed, failed, commits: commits.length };
+}
+
+// CLI entry: read --range, run, print summary.
+const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const rangeArg = args.find((a) => a.startsWith('--range='));
+  // Default: every commit unique to the current branch that landed via the
+  // current HEAD's range (post-merge sees ORIG_HEAD..HEAD typically).
+  const range = rangeArg ? rangeArg.split('=')[1] : (process.env.BEADS_AUTO_CLOSE_RANGE || 'ORIG_HEAD..HEAD');
+  const summary = await runAutoClose({ range });
+  if (summary.closed.length > 0) {
+    process.stdout.write(`[beads-auto-close] closed ${summary.closed.length} bead(s): ${summary.closed.map((c) => c.id).join(', ')}\n`);
+  }
+  if (summary.failed.length > 0) {
+    for (const f of summary.failed) {
+      process.stderr.write(`[beads-auto-close] failed ${f.id} (exit ${f.exitCode}): ${f.stderr}\n`);
+    }
+    process.exit(1);
+  }
+  process.exit(0);
+}

package/lib/beads/drift.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/beads-drift.mjs — beads hygiene drift detection.
+ *
+ * Three checks that surface stale tracker state before it accumulates:
+ *
+ *   1. Stale-open: open beads whose updatedAt is older than the staleness
+ *      window (default 14 days). Stale-open isn't a bug by itself but
+ *      means nobody has reviewed the bead in two weeks — likely irrelevant.
+ *
+ *   2. Stuck-in-progress: in_progress beads whose updatedAt is older than
+ *      the stuck window (default 3 days). A bead in_progress is supposed
+ *      to be claimed by an active session; 3+ days untouched means the
+ *      session that claimed it didn't follow through.
+ *
+ *   3. Merge-drift: open beads whose title or description appears verbatim
+ *      in a commit subject from the last N commits (default 50). Cross-
+ *      checks tracker state against recently merged work to catch beads
+ *      that should have been closed in the merge.
+ *
+ * The module exposes `detectBeadsDrift({...})` as a pure function so
+ * `construct doctor` and the pre-push gate can both consume it. CLI
+ * entry writes a human-readable report (and machine-readable JSON via
+ * `--json`) and exits non-zero when any check exceeds its threshold.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+const DEFAULT_STALE_OPEN_DAYS = 14;
+const DEFAULT_STUCK_IN_PROGRESS_DAYS = 3;
+const DEFAULT_MERGE_LOOKBACK = 50;
+
+function daysAgo(value) {
+  if (!value) return Infinity;
+  const ts = value instanceof Date ? value.getTime() : Date.parse(value);
+  if (!Number.isFinite(ts)) return Infinity;
+  return (Date.now() - ts) / (24 * 60 * 60 * 1000);
+}
+
+function listBeadsJson({ status, runner = spawnSync } = {}) {
+  const args = ['list', '--json'];
+  if (status) args.push(`--status=${status}`);
+  const result = runner('bd', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (result.status !== 0) return [];
+  try {
+    const parsed = JSON.parse(result.stdout);
+    if (Array.isArray(parsed)) return parsed;
+    if (Array.isArray(parsed?.issues)) return parsed.issues;
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+function recentCommitSubjects(limit, { runner = spawnSync } = {}) {
+  const result = runner('git', ['log', '-n', String(limit), '--pretty=format:%s'], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status !== 0) return [];
+  return result.stdout.split('\n').filter(Boolean);
+}
+
+function tokenize(text) {
+  return String(text || '').toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 4);
+}
+
+function titleAppearsInSubject(beadTitle, commitSubject) {
+  // Normalize both sides, then check that the bead's first significant
+  // tokens are present in the commit subject. Strict enough to avoid
+  // false positives, lax enough to catch reasonable matches.
+  const beadTokens = tokenize(beadTitle).slice(0, 5);
+  if (beadTokens.length < 3) return false;
+  const lowerSubject = String(commitSubject || '').toLowerCase();
+  let hits = 0;
+  for (const token of beadTokens) {
+    if (lowerSubject.includes(token)) hits += 1;
+  }
+  return hits >= 3;
+}
+
+/**
+ * Run the three drift checks against the live tracker + git state.
+ * Pure-ish — accepts a runner injection for tests.
+ */
+export function detectBeadsDrift({
+  staleOpenDays = DEFAULT_STALE_OPEN_DAYS,
+  stuckInProgressDays = DEFAULT_STUCK_IN_PROGRESS_DAYS,
+  mergeLookback = DEFAULT_MERGE_LOOKBACK,
+  runner = spawnSync,
+} = {}) {
+  const open = listBeadsJson({ status: 'open', runner });
+  const inProgress = listBeadsJson({ status: 'in_progress', runner });
+  const commits = recentCommitSubjects(mergeLookback, { runner });
+
+  const staleOpen = open.filter((b) => daysAgo(b.updated || b.updatedAt) > staleOpenDays);
+  const stuckInProgress = inProgress.filter((b) => daysAgo(b.updated || b.updatedAt) > stuckInProgressDays);
+
+  const mergeDrift = [];
+  for (const bead of open) {
+    for (const subject of commits) {
+      if (titleAppearsInSubject(bead.title, subject)) {
+        mergeDrift.push({ id: bead.id, title: bead.title, matchedSubject: subject });
+        break;
+      }
+    }
+  }
+
+  return {
+    staleOpen: staleOpen.map((b) => ({ id: b.id, title: b.title, ageDays: Math.round(daysAgo(b.updated || b.updatedAt)) })),
+    stuckInProgress: stuckInProgress.map((b) => ({ id: b.id, title: b.title, ageDays: Math.round(daysAgo(b.updated || b.updatedAt)) })),
+    mergeDrift,
+    thresholds: { staleOpenDays, stuckInProgressDays, mergeLookback },
+    counts: {
+      staleOpen: staleOpen.length,
+      stuckInProgress: stuckInProgress.length,
+      mergeDrift: mergeDrift.length,
+    },
+  };
+}
+
+export function formatDriftReport(report) {
+  const lines = [];
+  lines.push(`Beads hygiene drift report — checked against last ${report.thresholds.mergeLookback} commits`);
+  lines.push('');
+  if (report.counts.staleOpen === 0 && report.counts.stuckInProgress === 0 && report.counts.mergeDrift === 0) {
+    lines.push('✓ no drift detected');
+    return lines.join('\n') + '\n';
+  }
+  if (report.counts.stuckInProgress > 0) {
+    lines.push(`Stuck in_progress (> ${report.thresholds.stuckInProgressDays}d untouched):`);
+    for (const b of report.stuckInProgress) lines.push(`  ${b.id} · ${b.ageDays}d · ${b.title}`);
+    lines.push('');
+  }
+  if (report.counts.staleOpen > 0) {
+    lines.push(`Stale open (> ${report.thresholds.staleOpenDays}d untouched):`);
+    for (const b of report.staleOpen) lines.push(`  ${b.id} · ${b.ageDays}d · ${b.title}`);
+    lines.push('');
+  }
+  if (report.counts.mergeDrift > 0) {
+    lines.push(`Possible merge drift (open bead title overlaps a recent commit subject):`);
+    for (const b of report.mergeDrift) lines.push(`  ${b.id} · ${b.title}\n    matched: ${b.matchedSubject}`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+// CLI: print report, exit non-zero when thresholds breached unless --report-only.
+const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const reportOnly = args.includes('--report-only');
+  const opts = {};
+  for (const arg of args) {
+    const m = arg.match(/^--([a-z-]+)=(\d+)$/);
+    if (!m) continue;
+    if (m[1] === 'stale-open-days') opts.staleOpenDays = Number(m[2]);
+    if (m[1] === 'stuck-in-progress-days') opts.stuckInProgressDays = Number(m[2]);
+    if (m[1] === 'merge-lookback') opts.mergeLookback = Number(m[2]);
+  }
+  const report = detectBeadsDrift(opts);
+  if (json) {
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatDriftReport(report));
+  }
+  if (!reportOnly && (report.counts.stuckInProgress > 0 || report.counts.mergeDrift > 0)) {
+    process.exit(2);
+  }
+  process.exit(0);
+}