dotmd-cli 0.50.2 → 0.52.0

package/src/claude-commands.mjs

@@ -21,7 +21,6 @@ function markerFor(version) { return `<!-- dotmd-generated: ${version} -->`; }
 const SLASH_DESCRIPTIONS = {
   plans: "dotmd-managed plan briefing for this repo. Use when the user asks what's on the plate, references a plan slug, queues work, or wants to start / close / archive a plan.",
   docs: "dotmd-managed docs briefing for this repo. Use when the user asks to list, scaffold, query, validate, archive, or rename non-plan docs (reference docs, ADRs, RFCs, design notes), or asks how the dotmd doc lifecycle works here.",
-  baton: "Save a resume prompt for the active plan and close it out — the minimum handoff. Use when the user says hand off / save a resume / wrap up, or when context is getting tight.",
 };
 
 const VOCAB_TRUNCATE_AT = 12;
@@ -63,21 +62,20 @@ function generatePlansCommand(config, version) {
   lines.push('');
   lines.push('Plan-specific commands:');
   lines.push('- `dotmd context` — briefing with active/paused/ready plans, age tags, next steps');
-  lines.push('- `dotmd set <status> [<file>]` — single status verb. Use this to start, transition, or close any plan:');
-  lines.push('    - `dotmd set in-session <file>` — start work on a plan (marks in-session + prints body)');
-  lines.push('    - `dotmd set <status> [<file>]` — transition to any other status; closes out the in-session marker automatically');
+  lines.push('- `dotmd set <status> <file>` — single status verb. Writes the new status to the plan\'s frontmatter. Use it to transition or close any plan:');
+  lines.push('    - `dotmd set in-session <file>` — mark a plan in-session (just a frontmatter status; use `dotmd use <file>` to also print the body)');
   lines.push('    - `dotmd set archived <file>` — close out (same as `dotmd archive`)');
   lines.push('- `dotmd archive <file>` — explicit archive with ref-fixing (equivalent to `set archived`)');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
   lines.push('- `dotmd new plan <name>` — scaffold with full phase structure');
   lines.push('- `dotmd new prompt <name>` — save a resume-prompt to docs/prompts/ (pipe stdin or @path for body)');
   lines.push('- `dotmd use` — consume oldest pending prompt (prints body, auto-archives)');
-  lines.push('- `dotmd use <file>` — open any doc by type: prompt → consume, plan → start work, doc → read');
+  lines.push('- `dotmd use <file>` — open any doc by type: prompt → consume, plan → mark in-session + print card, doc → read');
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd actionable` — ready plans with next steps (what to promote)');
   lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
-  lines.push('- `dotmd runlist <hub>` — show ordered children of a runlist hub (→ marks next pickup)');
-  lines.push('- `dotmd runlist next <hub>` — pick up the next non-archived child of a runlist hub');
+  lines.push('- `dotmd runlist <hub>` — show ordered children of a runlist hub (→ marks next)');
+  lines.push('- `dotmd runlist next <hub>` — open the next non-archived child of a runlist hub');
 
   if (config.raw?.glossary) {
     lines.push('- `dotmd glossary <term>` — domain term lookup with related plans');
@@ -96,26 +94,6 @@ function generatePlansCommand(config, version) {
   return lines.join('\n');
 }
 
-function generateBatonCommand(config, version) {
-  const lines = [...frontmatterFor('baton', config), markerFor(version), ''];
-  lines.push('Wrap this session. Two commands:');
-  lines.push('');
-  lines.push('1. **Save the resume prompt.** `dotmd new prompt resume-<plan-slug>` — pipe stdin or pass `@path`. 10-20 line body: the next concrete decision plus any gotchas. NOT a recap of the plan body. The saved prompt IS the handoff — never print it into chat for copy-paste. Treat `docs/prompts/` as local session state: it is often gitignored and should not be committed just because you created a handoff prompt.');
-  lines.push('');
-  lines.push('2. **Close out via `dotmd set <status>`.** Pick the status that matches reality:');
-  lines.push('    - `dotmd set active <file>` — work continues, return the plan to the active queue');
-  lines.push('    - `dotmd set archived <file>` — fully shipped (also: `dotmd archive <file>`)');
-  lines.push('    - `dotmd set paused <file>` / `awaiting <file>` / `partial <file>` / `blocked <file>` — when the status really changed');
-  lines.push('  `set` clears the in-session marker automatically when transitioning to any other status.');
-  lines.push('');
-  lines.push('If you don\'t already know which plan you have in-session: `dotmd hud --json` and read `.owned`. Do NOT use `dotmd plans --status in-session` — that lists every session\'s in-session plans, not just yours.');
-  lines.push('');
-  lines.push('The next session\'s `dotmd hud` (SessionStart hook) surfaces the pending prompt automatically.');
-  lines.push('');
-
-  return lines.join('\n');
-}
-
 function generateDocsCommand(config, version) {
   const roots = Array.isArray(config.raw?.root) ? config.raw.root : [config.raw?.root ?? 'docs'];
   const rootCount = roots.length;
@@ -188,7 +166,6 @@ export function scaffoldClaudeCommands(cwd, config, opts = {}) {
   const files = [
     { name: 'plans.md', generate: () => generatePlansCommand(config, version) },
     { name: 'docs.md', generate: () => generateDocsCommand(config, version) },
-    { name: 'baton.md', generate: () => generateBatonCommand(config, version) },
   ];
 
   for (const { name, generate } of files) {

package/src/commands.mjs

@@ -4,9 +4,10 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'agent-context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
   '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/completions.mjs

@@ -2,7 +2,7 @@ import { die } from './util.mjs';
 
 const COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'unblocks', 'health', 'glossary', 'briefing', 'context', 'focus', 'query',
-  'plans', 'stale', 'actionable', 'index', 'pickup', 'unpickup', 'release', 'finish', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
+  'plans', 'stale', 'actionable', 'index', 'status', 'set', 'archive', 'bulk', 'touch', 'doctor', 'lint', 'rename', 'migrate',
   'fix-refs', 'notion', 'export', 'summary', 'watch', 'diff', 'init', 'new', 'completions', 'journal',
 ];
 
@@ -33,10 +33,6 @@ const COMMAND_FLAGS = {
   stale: ['--json', '--sort', '--limit', '--all'],
   actionable: ['--json', '--sort', '--limit', '--all'],
   briefing: ['--json'],
-  pickup: ['--json', '--takeover'],
-  unpickup: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
-  release: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
-  finish: ['--json', '--all', '--stale', '--to', '--force', '--no-index', '--show-files'],
   status: [],
   archive: [],
   doctor: [],

package/src/doctor.mjs

@@ -146,7 +146,7 @@ function findDeprecatedCommandMentions(config) {
   for (const filePath of docs) {
     let raw = '';
     try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
-    if (/\bdotmd status\b/.test(raw) || /\bdotmd pickup\b/.test(raw)) {
+    if (/\bdotmd status\b/.test(raw) || /\bdotmd (pickup|unpickup|release|finish)\b/.test(raw)) {
       matches.push(toRepoPath(filePath, config.repoRoot));
     }
   }

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/hints.mjs

@@ -1,6 +1,6 @@
 import { existsSync } from 'node:fs';
 import { readJournalEntries, isJournalEnabled, journalFilePath } from './journal.mjs';
-import { currentSessionId } from './lease.mjs';
+import { currentSessionId } from './util.mjs';
 
 // F17c: repeat-failure hints. When an agent runs the same broken invocation
 // twice in the same session within HINT_WINDOW_MS, the second die() output is
@@ -38,11 +38,6 @@ const TEMPLATES = [
     hint: ({ count, argv }) =>
       `${count}× pointing at a path that doesn't exist. Confirm the file with \`dotmd query\` or \`dotmd plans\` — paths resolve relative to repo root or doc roots, not the cwd.`,
   },
-  {
-    match: /Lease conflict|in-session|held by/i,
-    hint: ({ count }) =>
-      `${count}× lease conflict in this session. Run \`dotmd plans --status in-session\` to see what's held; pass \`--takeover\` if the holder is stale, or close the other session first.`,
-  },
   {
     match: /Unknown status|Unknown surface/i,
     hint: ({ count }) =>

package/src/hud.mjs

@@ -1,9 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { readLeases, findStaleLeases, currentSessionId, isLeaseStale, STALE_LEASE_AGE_MS } from './lease.mjs';
-import { scrubStaleSilently } from './lease-scrub.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath } from './util.mjs';
+import { asString, toRepoPath, currentSessionId } from './util.mjs';
 import { dim } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
@@ -105,13 +103,6 @@ export function buildJournalSections(config, now = Date.now()) {
   if (!entries.length) return { previousSelf: [], fleet: [], recentRejections: [] };
 
   const sid = currentSessionId();
-  const leases = readLeases(config);
-  const leaseBySession = new Map();
-  for (const lease of Object.values(leases)) {
-    if (!lease?.session) continue;
-    if (!leaseBySession.has(lease.session)) leaseBySession.set(lease.session, []);
-    leaseBySession.get(lease.session).push(lease);
-  }
 
   // 1. Previous self: this sid's last N entries (excluding the current
   // invocation, which is recorded only at process exit so it isn't in the
@@ -140,14 +131,10 @@ export function buildJournalSections(config, now = Date.now()) {
     if (t > row.lastTs) row.lastTs = t;
   }
   const fleet = [...bySid.entries()].map(([otherSid, row]) => {
-    const myLeases = leaseBySession.get(otherSid) ?? [];
-    const stalest = myLeases.find(isLeaseStale);
     return {
       sid: otherSid,
       cmds: row.count,
       lastAgo: relTime(new Date(row.lastTs).toISOString(), now),
-      holding: myLeases.map(l => l.path),
-      stale: Boolean(stalest),
     };
   }).sort((a, b) => b.cmds - a.cmds).slice(0, FLEET_CAP);
 
@@ -174,16 +161,6 @@ export function buildJournalSections(config, now = Date.now()) {
 }
 
 export function buildHud(config) {
-  // Drop stale lease entries (and flip their plan frontmatter back to
-  // oldStatus) before reading anything. Without this, hud would surface
-  // zombie in-session plans from crashed sessions as "you hold N plans" if
-  // the SessionStart hook sees its own (now-stale) lease from a previous
-  // session that shared the same env-supplied session id.
-  try { scrubStaleSilently(config); } catch { /* hot-path: never break hud */ }
-  const session = currentSessionId();
-  const leases = readLeases(config);
-  const owned = Object.values(leases).filter(l => l.session === session).map(l => l.path);
-  const stale = findStaleLeases(config).map(l => l.path);
   const prompts = findActionablePrompts(config);
 
   // Validation error count — hud's "silent when clean" contract should treat
@@ -205,11 +182,33 @@ export function buildHud(config) {
 
   const { previousSelf, fleet, recentRejections } = buildJournalSections(config);
 
-  return { owned, stale, prompts, errors, previousSelf, fleet, recentRejections };
+  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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { currentSessionId } from './lease.mjs';
+import { currentSessionId } from './util.mjs';
 
 const JOURNAL_DIR = '.dotmd';
 const JOURNAL_FILE = 'journal.jsonl';
@@ -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;
+}