dotmd-cli 0.51.0 → 0.52.0

package/bin/dotmd.mjs

@@ -34,7 +34,9 @@ const FLAG_SPECS = {
   briefing: { flags: new Set(['--json']), values: new Set() },
   context: { flags: new Set(['--json', '--compact', '--summarize', '--model']), values: new Set(['--model']) },
   'agent-context': { flags: new Set(['--json']), values: new Set() },
-  hud: { flags: new Set(['--json']), values: new Set() },
+  hud: { flags: new Set(['--json', '--subagent']), values: new Set() },
+  guard: { flags: new Set(), values: new Set() },
+  misuse: { flags: new Set(['--json', '--tail', '--by-rule', '--repo']), values: new Set(['--tail', '--repo']) },
   check: { flags: new Set(['--fix', '--errors-only', '--no-collapse', '--json', '--verbose']), values: new Set() },
   doctor: { flags: new Set(['--apply', '--yes', '--dry-run', '-n', '--statuses', '--migrate-template', '--migrate-prompts', '--frontmatter-fix', '--project', '--json', '--include-archived']), values: new Set() },
   runlist: { flags: new Set(['--json', '--full', '--no-index', '--show-files']), values: new Set(), subcommands: new Set(['next']) },
@@ -139,6 +141,32 @@ More help:
 
 Global flags: --config <path>  --root <name>  --type <t,…>  --dry-run/-n  --verbose  --version`,
 
+  guard: `dotmd guard — PreToolUse hook handler (reads the tool-call JSON on stdin)
+
+Wire it into Claude Code as a PreToolUse hook to intercept the wrong-moves
+sessions keep making, and to log every one for audit:
+
+  {"matcher":"Bash|Read|Edit|Write","hooks":[{"type":"command","command":"dotmd guard"}]}
+
+Rules:
+  commit-prompt  deny  git add/commit of a (often gitignored) saved prompt
+  cat-prompt     warn  cat/less/head of a docs/prompts/*.md (use \`dotmd use\`)
+  read-prompt    warn  Read tool on a saved prompt (use \`dotmd use\`)
+  edit-status    warn  hand-edit of a \`status:\` field (use \`dotmd set\`)
+
+Every catch is appended to the cross-repo misuse log. Disable with DOTMD_GUARD=0.
+Read the log with \`dotmd misuse\`.`,
+
+  misuse: `dotmd misuse — read the cross-repo guard log (~/.claude/logs/dotmd-misuse.log)
+
+  dotmd misuse                last 20 intercepted wrong-moves
+  dotmd misuse --tail 50      last N
+  dotmd misuse --by-rule      counts per rule (deny/warn split)
+  dotmd misuse --repo <name>  filter by repo
+  dotmd misuse --json         machine-readable
+
+Populated by the \`dotmd guard\` PreToolUse hook — see \`dotmd help guard\`.`,
+
   // Full command list — opt-in via \`dotmd help all\`. Kept exhaustive so the
   // top-level \`--help\` can stay terse without losing discoverability. When you
   // add a new command, add it here too.
@@ -1276,6 +1304,8 @@ async function main() {
 
   // Lifecycle commands
   if (command === 'hud') { const { runHud } = await import('../src/hud.mjs'); runHud(restArgs, config); return; }
+  if (command === 'guard') { const { runGuard } = await import('../src/guard.mjs'); await runGuard(restArgs, config); return; }
+  if (command === 'misuse') { const { runMisuse } = await import('../src/misuse-read.mjs'); runMisuse(restArgs, config); return; }
   if (command === 'journal') { const { runJournal } = await import('../src/journal-read.mjs'); runJournal(restArgs, config); return; }
   if (command === 'pickup' || command === 'unpickup' || command === 'release' || command === 'finish') {
     die(`\`dotmd ${command}\` was removed — dotmd no longer checks plans in/out. Status is just frontmatter:\n  dotmd use <file>          # mark in-session + print the plan\n  dotmd set <status> <file> # change status\n  dotmd archive <file>      # close out`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/commands.mjs

@@ -8,5 +8,6 @@ export const KNOWN_COMMANDS = [
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',
+  'guard', 'misuse',
   'ship', 'self-check',
 ];

package/src/git.mjs

@@ -2,6 +2,25 @@ import { spawnSync } from 'node:child_process';
 import { renameSync } from 'node:fs';
 import path from 'node:path';
 
+// Best-effort `git check-ignore` for a path. Returns true only when git
+// definitively reports the path is ignored; any failure (not a repo, git
+// missing, path outside the tree) returns false so callers never block on a
+// false positive. Used by the guard hook and `dotmd new` to warn that a
+// freshly-created doc lives under a gitignored path (the "agent tries to
+// commit a session-local prompt" confusion).
+export function isGitIgnored(absPath, repoRoot) {
+  try {
+    const result = spawnSync('git', ['check-ignore', '-q', '--', absPath], {
+      cwd: repoRoot || process.cwd(),
+      encoding: 'utf8',
+    });
+    // exit 0 → ignored, 1 → not ignored, 128 → not a git repo / other error.
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
 let gitChecked = false;
 function ensureGit() {
   if (gitChecked) return;

package/src/guard.mjs

@@ -0,0 +1,202 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isGitIgnored } from './git.mjs';
+import { recordGuardEvent } from './journal.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+// `dotmd guard` is the PreToolUse hook handler. Claude Code pipes the tool-call
+// payload on stdin; we evaluate it against a small set of "wrong-move" rules and
+// reply with a PreToolUse hook-output JSON object. Every catch is also recorded
+// to the cross-repo misuse log so the operator can audit *every* incorrect usage
+// — these mistakes never invoke dotmd directly, so the guard is the only place
+// they become visible.
+//
+// Two decision levels:
+//   'deny' — block the call and feed the reason back to the model. Reserved for
+//            moves that are guaranteed-wrong (committing a gitignored prompt — it
+//            would fail anyway).
+//   'warn' — let the call proceed but inject teaching context so the agent learns
+//            the dotmd-native command. Used for soft mistakes (cat/Read of a
+//            prompt, hand-editing a status field) where a human might legitimately
+//            do it; we nudge rather than block.
+
+const SHELL_READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'view', 'open']);
+
+// A path that ends in .md and sits under a `prompts/` directory is a saved
+// prompt regardless of which doc root it belongs to — robust across repos
+// without needing the resolved config.
+function isPromptPath(p) {
+  return typeof p === 'string' && p.endsWith('.md') && /(^|\/)prompts\//.test(p);
+}
+
+// Loose "is this a dotmd-managed doc" test: a .md file under one of the
+// configured doc roots (default `docs/`). Used for the status-edit guard.
+function isManagedDoc(p, config) {
+  if (typeof p !== 'string' || !p.endsWith('.md')) return false;
+  const roots = config?.docsRoots || (config?.docsRoot ? [config.docsRoot] : ['docs']);
+  return roots.some(r => {
+    const base = path.basename(r);
+    return p.includes(`/${base}/`) || p.startsWith(`${base}/`) || p.includes(r);
+  });
+}
+
+// Pull bare path-looking tokens out of a shell command. Good enough to spot the
+// prompt file in `git add docs/prompts/foo.md` or `cat docs/prompts/foo.md`.
+function shellTokens(command) {
+  if (typeof command !== 'string') return [];
+  return command.split(/\s+/).map(t => t.replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+
+function evalBash(command, config, isIgnored) {
+  const tokens = shellTokens(command);
+  const promptTokens = tokens.filter(isPromptPath);
+
+  // Rule A — committing/adding a gitignored prompt. The exact failure the guard
+  // exists for: an agent reflexively `git add`s a session-local prompt that
+  // lives under a gitignored path, and the commit dies confusingly.
+  if (/\bgit\s+(add|commit|stage)\b/.test(command) && promptTokens.length) {
+    const ignored = promptTokens.filter(p => isIgnored(p));
+    const targets = ignored.length ? ignored : promptTokens;
+    const ignoredNote = ignored.length
+      ? ` ${ignored.join(', ')} is gitignored — it cannot be committed.`
+      : '';
+    return {
+      decision: 'deny',
+      rule: 'commit-prompt',
+      detail: command,
+      reason:
+        `Saved prompts (${targets.join(', ')}) are session-local dotmd artifacts, not source to commit.${ignoredNote} ` +
+        `Don't git add/commit them. The next session consumes a prompt with \`dotmd use <file>\` (or \`dotmd use\` for the oldest pending), which prints the body and archives it atomically.`,
+    };
+  }
+
+  // Rule B — reading a prompt through the shell instead of consuming it.
+  if (tokens.length) {
+    const cmd0 = path.basename(tokens[0]);
+    if (SHELL_READERS.has(cmd0) && promptTokens.length) {
+      return {
+        decision: 'warn',
+        rule: 'cat-prompt',
+        detail: command,
+        reason:
+          `${promptTokens.join(', ')} is a saved dotmd prompt. Don't \`${cmd0}\` it — run \`dotmd use ${promptTokens[0]}\` ` +
+          `to print the body and archive it in one atomic step (prevents the same prompt being consumed twice). Use \`dotmd use\` with no arg for the oldest pending prompt.`,
+      };
+    }
+  }
+
+  return null;
+}
+
+function evalRead(filePath) {
+  if (!isPromptPath(filePath)) return null;
+  return {
+    decision: 'warn',
+    rule: 'read-prompt',
+    detail: filePath,
+    reason:
+      `${filePath} is a saved dotmd prompt. Prefer \`dotmd use ${filePath}\` over reading it directly — it prints the body and archives the prompt atomically so it can't be double-consumed.`,
+  };
+}
+
+const STATUS_LINE = /^\s*status\s*:/m;
+
+function evalEdit(input, config) {
+  const filePath = input?.file_path;
+  if (!isManagedDoc(filePath, config)) return null;
+  // Only fire when the edit actually touches a `status:` frontmatter line.
+  const candidates = [input?.new_string, input?.content, input?.new_str]
+    .filter(s => typeof s === 'string');
+  if (!candidates.some(s => STATUS_LINE.test(s))) return null;
+  return {
+    decision: 'warn',
+    rule: 'edit-status',
+    detail: filePath,
+    reason:
+      `Looks like a hand-edit of the \`status:\` field in ${filePath}. Use \`dotmd set <status> ${filePath}\` instead — ` +
+      `it validates the status against this doc's type, runs lifecycle hooks, fixes refs, and keeps the index in sync. Direct edits skip all of that.`,
+  };
+}
+
+// Pure evaluation — `deps.isIgnored(path) -> bool` is injected so tests don't
+// need a real git tree. Returns null (no opinion) or a result object.
+export function evaluateGuard(payload, config, deps = {}) {
+  if (process.env.DOTMD_GUARD === '0') return null;
+  const tool = payload?.tool_name;
+  const input = payload?.tool_input || {};
+  const isIgnored = deps.isIgnored || ((p) => isGitIgnored(p, config?.repoRoot));
+
+  if (tool === 'Bash') return evalBash(input.command || '', config, isIgnored);
+  if (tool === 'Read') return evalRead(input.file_path || '');
+  if (tool === 'Edit' || tool === 'Write' || tool === 'MultiEdit') return evalEdit(input, config);
+  return null;
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    try {
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (c) => { data += c; });
+      process.stdin.on('end', () => resolve(data));
+      process.stdin.on('error', () => resolve(data));
+      // Don't hang the tool dispatch if stdin never closes.
+      setTimeout(() => resolve(data), 2000);
+    } catch {
+      resolve(data);
+    }
+  });
+}
+
+function emit(result) {
+  if (!result) {
+    // No opinion — stay silent, let the tool run.
+    process.stdout.write('{}\n');
+    return;
+  }
+  const hookSpecificOutput = { hookEventName: 'PreToolUse' };
+  if (result.decision === 'deny') {
+    hookSpecificOutput.permissionDecision = 'deny';
+    hookSpecificOutput.permissionDecisionReason = result.reason;
+  } else {
+    // warn — allow the call but teach the agent the dotmd-native path.
+    hookSpecificOutput.additionalContext = `[dotmd] ${result.reason}`;
+  }
+  process.stdout.write(JSON.stringify({ hookSpecificOutput }) + '\n');
+}
+
+export async function runGuard(argv, config) {
+  let payload = {};
+  try {
+    const raw = await readStdin();
+    if (raw && raw.trim()) payload = JSON.parse(raw);
+  } catch {
+    payload = {};
+  }
+
+  let result = null;
+  try {
+    result = evaluateGuard(payload, config);
+  } catch {
+    result = null;
+  }
+
+  if (result) {
+    recordGuardEvent({
+      repo: config?.repoRoot,
+      tool: payload?.tool_name,
+      rule: result.rule,
+      decision: result.decision,
+      detail: result.detail,
+      version: pkg.version,
+    });
+  }
+
+  emit(result);
+  // A guard must never fail the tool dispatch; always exit 0 and let the JSON
+  // carry the decision.
+  process.exitCode = 0;
+}

package/src/hud.mjs

@@ -185,8 +185,30 @@ export function buildHud(config) {
   return { prompts, errors, previousSelf, fleet, recentRejections };
 }
 
+// Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
+// with ZERO project context and no SessionStart history — it has never seen the
+// command sheet the top-level session got. Without this, subagents reflexively
+// grep/cat/commit managed docs instead of using dotmd. Keep it to a few dense
+// lines: the verbs + the three wrong-moves the guard exists to stop, so the
+// subagent self-corrects before the guard ever has to fire.
+const SUBAGENT_PRIMER = [
+  'dotmd manages this repo\'s plans/docs/prompts (markdown + YAML frontmatter).',
+  'Verbs: plans|briefing | query <filters> | use [<file>] | set <status> <file> | new <type> <slug> | archive <file>.',
+  'Do NOT: cat/read a docs/prompts/*.md (use `dotmd use <file>` — it prints + archives atomically);',
+  'git add/commit a prompt (they are session-local, often gitignored); hand-edit a `status:` field (use `dotmd set`).',
+].join('\n');
+
 export function runHud(argv, config) {
   const json = argv.includes('--json');
+
+  // SubagentStart hook entry point — emit the compact primer and return. No
+  // index build, no journal read, no slash-command heal: a subagent doesn't
+  // need the operator-facing machinery, just the verbs and the guardrails.
+  if (argv.includes('--subagent')) {
+    process.stdout.write(dim(SUBAGENT_PRIMER) + '\n');
+    return;
+  }
+
   const hud = buildHud(config);
 
   // Self-heal stale slash-command files. Wrapped: a broken scaffolder must

package/src/journal.mjs

@@ -13,6 +13,9 @@ const BACKUP_RETENTION_MS = ROTATE_AGE_MS;
 const ERROR_LOG_FILE = 'dotmd-errors.log';
 const ERROR_LOG_BACKUP = 'dotmd-errors.log.1';
 
+const MISUSE_LOG_FILE = 'dotmd-misuse.log';
+const MISUSE_LOG_BACKUP = 'dotmd-misuse.log.1';
+
 export function isJournalEnabled(config) {
   if (process.env.DOTMD_JOURNAL === '1') return true;
   if (process.env.DOTMD_JOURNAL === '0') return false;
@@ -181,3 +184,57 @@ export function recordGlobalError({ config, startMs, args, err, version }) {
     // Logging must never break exit.
   }
 }
+
+// Misuse log: always-on, cross-repo, append-only record of every wrong-move the
+// PreToolUse guard intercepts (committing a gitignored prompt, `cat`-ing a
+// prompt instead of `dotmd use`, hand-editing a `status:` field, …). This is
+// the ONLY place those mistakes become visible — they never invoke dotmd, so
+// neither the per-repo journal nor the global error log would otherwise see
+// them. Shares the error log's directory and rotation so `~/.claude/logs` is
+// the single home for "what went wrong." Read it with `dotmd misuse`.
+export function globalMisuseLogPath() {
+  return path.join(globalErrorLogDir(), MISUSE_LOG_FILE);
+}
+
+export function globalMisuseLogBackupPath() {
+  return path.join(globalErrorLogDir(), MISUSE_LOG_BACKUP);
+}
+
+export function recordGuardEvent(event) {
+  if (!event) return;
+  const entry = {
+    ts: new Date().toISOString(),
+    repo: event.repo || process.cwd(),
+    sid: currentSessionId(),
+    pid: process.pid,
+    tool: event.tool ?? null,
+    rule: event.rule ?? null,
+    decision: event.decision ?? null,
+    detail: typeof event.detail === 'string'
+      ? (event.detail.length > 300 ? event.detail.slice(0, 297) + '...' : event.detail)
+      : null,
+    v: event.version ?? null,
+  };
+  try {
+    const dir = globalErrorLogDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const file = globalMisuseLogPath();
+    maybeRotate(file, globalMisuseLogBackupPath());
+    appendFileSync(file, JSON.stringify(entry) + '\n', { flag: 'a' });
+  } catch {
+    // Logging must never break the hook.
+  }
+}
+
+export function readMisuseEntries() {
+  const file = globalMisuseLogPath();
+  if (!existsSync(file)) return [];
+  let raw;
+  try { raw = readFileSync(file, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}

package/src/misuse-read.mjs

@@ -0,0 +1,62 @@
+import { existsSync } from 'node:fs';
+import { readMisuseEntries, globalMisuseLogPath } from './journal.mjs';
+import { dim, red, yellow } from './color.mjs';
+
+// `dotmd misuse` — read the cross-repo guard log. Every wrong-move the
+// PreToolUse guard intercepts lands here; this is the operator's window into
+// "what are sessions getting wrong, and how often."
+function parseArgs(argv) {
+  const opts = { tail: null, byRule: false, asJson: false, repo: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--tail') { const n = parseInt(argv[++i], 10); opts.tail = Number.isFinite(n) && n > 0 ? n : 20; }
+    else if (a === '--by-rule') opts.byRule = true;
+    else if (a === '--json') opts.asJson = true;
+    else if (a === '--repo' && argv[i + 1]) opts.repo = argv[++i];
+  }
+  if (opts.tail === null && !opts.byRule) opts.tail = 20;
+  return opts;
+}
+
+export function runMisuse(argv, _config) {
+  const file = globalMisuseLogPath();
+  if (!existsSync(file)) {
+    process.stderr.write(
+      'No misuse log yet. The PreToolUse guard (`dotmd guard`) writes here when it intercepts a wrong move.\n' +
+      'Wire it up: add a PreToolUse hook that runs `dotmd guard` (see `dotmd help guard`).\n',
+    );
+    return;
+  }
+
+  const opts = parseArgs(argv);
+  let entries = readMisuseEntries();
+  if (opts.repo) entries = entries.filter(e => (e.repo || '').includes(opts.repo));
+
+  if (opts.byRule) {
+    const groups = new Map();
+    for (const e of entries) {
+      const key = e.rule || '(unknown)';
+      if (!groups.has(key)) groups.set(key, { rule: key, count: 0, deny: 0, warn: 0 });
+      const g = groups.get(key);
+      g.count++;
+      if (e.decision === 'deny') g.deny++; else if (e.decision === 'warn') g.warn++;
+    }
+    const rows = [...groups.values()].sort((a, b) => b.count - a.count);
+    if (opts.asJson) { process.stdout.write(JSON.stringify(rows, null, 2) + '\n'); return; }
+    if (!rows.length) { process.stdout.write('No misuse events recorded.\n'); return; }
+    for (const r of rows) {
+      process.stdout.write(`${r.rule.padEnd(16)} ${String(r.count).padStart(4)}×  ${red(`${r.deny} deny`)} / ${yellow(`${r.warn} warn`)}\n`);
+    }
+    return;
+  }
+
+  if (opts.tail) entries = entries.slice(-opts.tail);
+  if (opts.asJson) { process.stdout.write(JSON.stringify(entries, null, 2) + '\n'); return; }
+  if (!entries.length) { process.stdout.write('No misuse events recorded.\n'); return; }
+
+  for (const e of entries) {
+    const tag = e.decision === 'deny' ? red('DENY') : yellow('warn');
+    const repo = e.repo ? dim(` ${e.repo.split('/').pop()}`) : '';
+    process.stdout.write(`[${e.ts}] ${tag} ${e.rule || '?'}${repo} ${dim(e.detail || '')}\n`);
+  }
+}

package/src/new.mjs

@@ -539,6 +539,22 @@ export async function runNew(argv, config, opts = {}) {
   process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
   if (rootHint) process.stdout.write(dim(rootHint));
 
+  // Post-create guidance. Prompts are the classic confusion point: agents
+  // reflexively `git add && commit` a freshly-created file, but saved prompts
+  // are session-local handoff artifacts — the next session consumes them via
+  // `dotmd use`, and the prompts dir is often gitignored (the commit then fails
+  // confusingly). Tell the agent the next step explicitly, and flag a gitignored
+  // target for any type so "why won't this commit" never happens silently.
+  if (typeName === 'prompt') {
+    process.stdout.write(dim('Session-local — no need to commit. The next session runs `dotmd use` (or `dotmd use ' + repoPath + '`) to consume it.\n'));
+  }
+  try {
+    const { isGitIgnored } = await import('./git.mjs');
+    if (isGitIgnored(filePath, config.repoRoot)) {
+      process.stdout.write(dim(`Note: ${repoPath} is gitignored — don't try to git add/commit it.\n`));
+    }
+  } catch { /* git absent / not a repo — skip the note */ }
+
   regenIndex(config);
 
   if (showFiles) {