dotmd-cli 0.69.0 → 0.70.0

package/src/hud.mjs

@@ -1,14 +1,15 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, currentSessionId } from './util.mjs';
+import { currentSessionId, isArchivedPath } from './util.mjs';
 import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
-import { refreshStaleSlashCommands } from './claude-commands.mjs';
 import { readJournalEntries, journalFilePath, readMisuseEntries } from './journal.mjs';
 import { compareVersions } from './update.mjs';
 import { findOwnedPlan } from './baton.mjs';
+import { actionablePromptStatuses, comparePromptDocs, resolveStatusMetadata } from './status-metadata.mjs';
+
+export { actionablePromptStatuses } from './status-metadata.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -45,51 +46,14 @@ export function detectVersionDrift(env = process.env) {
 // for stripped-down configs). This means a user who customizes
 // types.prompt.statuses to add e.g. `urgent: { context: 'expanded' }` gets that
 // status surfaced too, without needing a code change.
-export function actionablePromptStatuses(config) {
-  const promptCtx = config.typeContextConfig?.get('prompt');
-  const expanded = promptCtx?.expanded;
-  if (Array.isArray(expanded) && expanded.length > 0) return new Set(expanded);
-  return new Set(['pending']);
-}
-
 // Returns repo paths, oldest-created first — the same order no-arg `dotmd use`
 // consumes them, so prompts[0] is always "the one you'd pick up next".
-function findActionablePrompts(config) {
-  const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
-  const archiveDir = config.archiveDir || 'archived';
+function findActionablePrompts(config, index) {
   const actionable = actionablePromptStatuses(config);
-  const found = [];
-  const seen = new Set();
-
-  for (const root of roots) {
-    // A root may either contain a prompts/ subdir (the common case, e.g. root=docs)
-    // or be the prompts/ dir itself (e.g. root=docs/prompts — see #6).
-    const dir = path.basename(root) === 'prompts' ? root : path.join(root, 'prompts');
-    if (seen.has(dir)) continue;
-    seen.add(dir);
-    if (!existsSync(dir)) continue;
-    let entries;
-    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
-    for (const entry of entries) {
-      if (entry.isDirectory()) continue;
-      if (!entry.name.endsWith('.md')) continue;
-      const filePath = path.join(dir, entry.name);
-      // Skip any nested archived/ collisions just in case
-      if (filePath.includes(`/${archiveDir}/`)) continue;
-      let raw;
-      try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
-      const { frontmatter } = extractFrontmatter(raw);
-      if (!frontmatter) continue;
-      const fm = parseSimpleFrontmatter(frontmatter);
-      if (asString(fm.type) !== 'prompt') continue;
-      if (!actionable.has(asString(fm.status))) continue;
-      found.push({ path: toRepoPath(filePath, config.repoRoot), created: asString(fm.created) ?? '' });
-    }
-  }
-
-  return found
-    .sort((a, b) => a.created.localeCompare(b.created) || a.path.localeCompare(b.path))
-    .map(p => p.path);
+  return index.docs
+    .filter(doc => doc.type === 'prompt' && actionable.has(doc.status) && !isArchivedPath(doc.path, config))
+    .sort(comparePromptDocs)
+    .map(doc => doc.path);
 }
 
 // F17b: hud reads journal. Three additive sections, gated on
@@ -230,27 +194,30 @@ export function buildMisuseRecap(config, now = Date.now()) {
 }
 
 export function buildHud(config) {
-  const prompts = findActionablePrompts(config);
+  let prompts = [];
+  const skippedValidationHooks = ['validate', 'transformDoc', 'formatSnapshot']
+    .filter(name => typeof config.hooks?.[name] === 'function');
 
   // Validation error count — hud's "silent when clean" contract should treat
   // `check` errors as not-clean. Without this, a SessionStart hook firing hud
   // can leave the agent with no visible signal that a check is failing.
   // `errorsOnly: true` skips warning-only cross-doc passes (git staleness,
-  // bidirectional refs, claude-commands) that hud never reads — ~6× faster on
-  // SessionStart for platform-scale corpora. Per-file validation + checkIndex
-  // still run, so the error count matches `dotmd check`'s.
-  let errors = 0;
+  // bidirectional refs, claude-commands) that hud never reads. Built-in
+  // per-file validation + checkIndex still run; user hooks are deliberately
+  // suppressed because SessionStart is passive.
+  let builtInErrors = 0;
   // `owned` answers "which plan is THIS session's?" for programmatic callers
-  // (the baton flow reads it) — derived from the journal, falling back to the
-  // only in-session plan. Null when there's no defensible answer.
+  // (the baton flow reads it) — derived only from a valid durable ownership
+  // record. Null when ownership is absent, stale, corrupt, or ambiguous.
   let owned = null;
   try {
-    // `autoHealIndex: true` mirrors `dotmd check` — drift from non-regen
-    // mutation paths (`lint --fix`, direct file edits, etc.) heals silently
-    // at SessionStart so the agent doesn't open every session with a
-    // spurious "Run `dotmd index`" error in the hud error count.
-    const index = buildIndex(config, { errorsOnly: true, autoHealIndex: true });
-    errors = index.errors.length;
+    const index = buildIndex(config, {
+      errorsOnly: true,
+      autoHealIndex: false,
+      invokeHooks: false,
+    });
+    prompts = findActionablePrompts(config, index);
+    builtInErrors = index.errors.length;
     const o = findOwnedPlan(config, index);
     if (o.plan) owned = { path: o.plan.path, title: o.plan.title ?? null, via: o.via };
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
@@ -258,7 +225,20 @@ export function buildHud(config) {
   const { previousSelf, fleet, recentRejections } = buildJournalSections(config);
   const misuseRecap = buildMisuseRecap(config);
 
-  return { owned, prompts, errors, previousSelf, fleet, recentRejections, misuseRecap };
+  const validationComplete = skippedValidationHooks.length === 0;
+  return {
+    owned,
+    prompts,
+    errors: validationComplete ? builtInErrors : null,
+    ...(validationComplete ? {} : {
+      builtInErrors,
+      validationPreview: { status: 'built-in-only', skippedHooks: skippedValidationHooks },
+    }),
+    previousSelf,
+    fleet,
+    recentRejections,
+    misuseRecap,
+  };
 }
 
 // Subagent primer: a spawned subagent (Explore, Plan, general-purpose) starts
@@ -270,10 +250,29 @@ export function buildHud(config) {
 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);',
+  'Do NOT: cat/read a docs/prompts/*.md (use `dotmd use <file>` — archive/claim commits before at-most-once output);',
   'git add/commit a prompt (they are session-local, often gitignored); hand-edit a `status:` field (use `dotmd set`).',
 ].join('\n');
 
+export function buildPlanStatusPrimer(config, { maxChars = 220 } = {}) {
+  const statuses = (resolveStatusMetadata(config).byType.plan ?? []).map(item => item.name);
+  const fallback = 'run `dotmd statuses list --type plan`';
+  if (statuses.length === 0) return `Plan statuses unavailable; ${fallback}.`;
+  const prefix = 'Plan statuses: ';
+  const full = `${prefix}${statuses.join(', ')}`;
+  if (full.length <= maxChars) return full;
+
+  const shown = [];
+  for (const status of statuses) {
+    const omitted = statuses.length - shown.length - 1;
+    const candidate = `${prefix}${[...shown, status].join(', ')}, ... (+${omitted}; ${fallback})`;
+    if (candidate.length > maxChars) break;
+    shown.push(status);
+  }
+  const omitted = statuses.length - shown.length;
+  return `${prefix}${shown.join(', ')}${shown.length ? ', ' : ''}... (+${omitted}; ${fallback})`;
+}
+
 // The plugin's SessionStart/SubagentStart hooks fire in EVERY repo (it's enabled
 // globally), but the primer only helps where dotmd is actually used. Gate on a
 // discovered config: `dotmd init` writes dotmd.config.mjs, so "has a config" is
@@ -296,6 +295,7 @@ export function runHud(argv, config) {
   if (argv.includes('--subagent')) {
     if (!dotmdRepo) return; // silent in repos that don't use dotmd
     process.stdout.write(dim(SUBAGENT_PRIMER) + '\n');
+    process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
     if (drift) process.stdout.write(yellow(drift) + '\n');
     return;
   }
@@ -306,17 +306,6 @@ export function runHud(argv, config) {
 
   const hud = buildHud(config);
 
-  // Clean up retired generated slash-command files (the plugin skill replaces
-  // them). Banner-gated, so hand-authored commands survive. Wrapped: teardown
-  // must never kill the SessionStart hook (would block every session). Runs for
-  // its side effect only — nothing is announced in stdout (see the primer-only
-  // contract below). Skipped in --json mode to keep the structured shape stable
-  // for programmatic callers.
-  if (!json) {
-    try { refreshStaleSlashCommands(config); }
-    catch { /* swallow — see comment above */ }
-  }
-
   if (json) {
     process.stdout.write(JSON.stringify({ ...hud, drift: drift ?? null }, null, 2) + '\n');
     return;
@@ -332,14 +321,14 @@ export function runHud(argv, config) {
   // next session ever picked up):
   //   - pending prompts: the previous session queued work for THIS one;
   //     consuming it is the very next action.
-  //   - an in-session plan attributed to this sid via the journal: this
+  //   - an in-session plan attributed to this sid via durable ownership: this
   //     session (pre-compaction) owns it and should continue or hand it off.
-  //     The single-in-session fallback is deliberately NOT printed — at
-  //     SessionStart that plan likely belongs to another live session.
+  //     Global in-session counts never provide a fallback.
   // The misuse recap stays for the same reason: a repeat-offense rule means
   // the primer alone isn't landing, so name the habit to break.
   process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  baton [<slug>] <@draft|-> (save a resume prompt; releases the in-session plan if any)  (use [no-arg] → oldest pending prompt)') + '\n');
-  if (hud.owned && hud.owned.via === 'journal') {
+  process.stdout.write(dim(buildPlanStatusPrimer(config)) + '\n');
+  if (hud.owned && hud.owned.via === 'ownership') {
     process.stdout.write(yellow(`[dotmd] in-session (yours): ${hud.owned.path} — continue it; hand off with \`dotmd baton @/tmp/draft.md\` before stopping.`) + '\n');
   }
   if (hud.prompts.length > 0) {

package/src/index-file.mjs

@@ -1,10 +1,11 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { capitalize, escapeTable } from './util.mjs';
 import { formatSnapshot } from './render.mjs';
+import { authorizeRepoGeneratedPath } from './managed-path.mjs';
+import { mutateFile } from './atomic-mutation.mjs';
 
-export function renderIndexFile(index, config) {
-  const current = readFileSync(config.indexPath, 'utf8');
+export function renderIndexFile(index, config, current = readFileSync(config.indexPath, 'utf8')) {
   const start = current.indexOf(config.indexStartMarker);
   const end = current.indexOf(config.indexEndMarker);
 
@@ -86,8 +87,12 @@ function renderIndexSnapshot(doc, config, snapshotMode) {
   return capitalize(doc.status ?? 'unknown');
 }
 
-export function writeIndex(content, config) {
-  writeFileSync(config.indexPath, content, 'utf8');
+export function writeRenderedIndex(indexOrFactory, config, options = {}) {
+  authorizeRepoGeneratedPath(config.indexPath, config, { kind: 'Generated index destination' });
+  mutateFile(config.indexPath, { repoRoot: config.repoRoot, ...options }, current => {
+    const index = typeof indexOrFactory === 'function' ? indexOrFactory() : indexOrFactory;
+    return renderIndexFile(index, config, current);
+  });
 }
 
 // `autoHeal: true` rewrites the index in place when drift is detected and
@@ -102,12 +107,28 @@ export function writeIndex(content, config) {
 // filtered/synthetic docs list omit it to keep the old error semantics —
 // auto-overwriting from a partial doc list would clobber valid content.
 export function checkIndex(docs, config, opts = {}) {
-  const { autoHeal = false } = opts;
+  const { autoHeal = false, rebuildDocs = null, testHooks = null } = opts;
   const warnings = [];
   const errors = [];
 
   if (!config.indexPath) return { warnings, errors };
 
+  if (autoHeal) {
+    try {
+      authorizeRepoGeneratedPath(config.indexPath, config, { kind: 'Generated index destination' });
+      const result = mutateFile(config.indexPath, { repoRoot: config.repoRoot, testHooks }, currentContent => {
+        const currentDocs = rebuildDocs ? rebuildDocs() : docs;
+        return renderIndexFile({ docs: currentDocs }, config, currentContent);
+      });
+      if (result.changed) {
+        warnings.push({ path: config.indexPath, level: 'warning', message: 'Auto-regenerated stale index block.' });
+      }
+    } catch (err) {
+      errors.push({ path: config.indexPath, level: 'error', message: `Could not auto-regenerate stale index block: ${err.message}` });
+    }
+    return { warnings, errors };
+  }
+
   const current = readFileSync(config.indexPath, 'utf8');
   const start = current.indexOf(config.indexStartMarker);
   const end = current.indexOf(config.indexEndMarker);
@@ -120,16 +141,7 @@ export function checkIndex(docs, config, opts = {}) {
   const index = { docs };
   const expected = renderIndexFile(index, config);
   if (expected !== current) {
-    if (autoHeal) {
-      try {
-        writeFileSync(config.indexPath, expected, 'utf8');
-        warnings.push({ path: config.indexPath, level: 'warning', message: 'Auto-regenerated stale index block.' });
-      } catch (err) {
-        errors.push({ path: config.indexPath, level: 'error', message: `Could not auto-regenerate stale index block: ${err.message}` });
-      }
-    } else {
-      errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
-    }
+    errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
   }
 
   return { warnings, errors };

package/src/index.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn, die, resolveDocPath, suggestCandidates } from './util.mjs';
+import { findLexicalDocsRoot } from './managed-path.mjs';
 import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, checkRunlistBackPointers, checkCoordinationHubExecutionMode, checkRoadmapHubExecutionMode, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate, enrichRefErrorSuggestions } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
@@ -16,14 +17,15 @@ import { checkSkillDrift } from './skill-drift.mjs';
 // `dotmd check`). Saves the full-repo `git log` scan in `checkGitStaleness`
 // plus the bidirectional ref walk + claude-commands check.
 //
-// `errorsOnly: true` runs every error-producing pass (per-file `validateDoc`,
-// `checkIndex`, the `validate` hook) but skips the warning-only cross-doc
+// `errorsOnly: true` runs every built-in error-producing pass (per-file
+// `validateDoc`, `checkIndex`) but skips the warning-only cross-doc
 // passes (bidirectional refs, runlist back-pointers, git staleness, claude
 // commands). Use it from `dotmd hud` — the SessionStart hook only renders the
 // error COUNT, so the warning-only passes are pure overhead there. Preserves
-// the invariant that hud's "✗ N validation errors" line matches `dotmd check`.
+// the built-in invariant that HUD's error count matches `dotmd check`.
 export function buildIndex(config, opts = {}) {
   const { fast = false, errorsOnly = false, autoHealIndex = false } = opts;
+  const invokeHooks = opts.invokeHooks ?? !config._execution?.suppressSideEffects;
   const skipWarningOnlyChecks = fast || errorsOnly;
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
   if (!fast) {
@@ -42,7 +44,7 @@ export function buildIndex(config, opts = {}) {
     errors.push(...doc.errors);
   }
 
-  if (!fast && config.hooks.validate) {
+  if (!fast && invokeHooks && config.hooks.validate) {
     const ctx = { config, allDocs: docs, repoRoot: config.repoRoot };
     for (const doc of docs) {
       try {
@@ -63,7 +65,7 @@ export function buildIndex(config, opts = {}) {
     }
   }
 
-  const transformedDocs = config.hooks.transformDoc
+  const transformedDocs = invokeHooks && config.hooks.transformDoc
     ? docs.map(d => {
         try { return config.hooks.transformDoc(d) ?? d; }
         catch (err) {
@@ -97,15 +99,19 @@ export function buildIndex(config, opts = {}) {
   }
 
   if (!fast && config.indexPath) {
-    // `autoHealIndex` is opt-in from the caller (currently `dotmd check` and
-    // `dotmd hud`). When true, drift triggers an in-place rewrite and a
+    // `autoHealIndex` is opt-in from the caller (currently `dotmd check`).
+    // When true, drift triggers an in-place rewrite and a
     // warning instead of the old "Run `dotmd index`" error — closing the
     // class of nags produced by mutation paths that skip `regenIndex`
     // (`lint --fix`, direct file edits, etc). `transformedDocs` here is
     // always the canonical full set; CLI-level `--root`/`--type` filtering
     // runs after `buildIndex` returns, so a rewrite is safe. Off by default
     // so dry-run / print modes never mutate disk as a side effect.
-    const indexCheck = checkIndex(transformedDocs, config, { autoHeal: autoHealIndex });
+    const indexCheck = checkIndex(transformedDocs, config, {
+      autoHeal: autoHealIndex,
+      rebuildDocs: autoHealIndex ? () => buildIndex(config, { fast: true }).docs : null,
+      testHooks: opts.testHooks,
+    });
     warnings.push(...indexCheck.warnings);
     errors.push(...indexCheck.errors);
   }
@@ -135,7 +141,7 @@ export function buildIndex(config, opts = {}) {
       if (hub) hub.warnings.push(w);
     }
 
-    const gitWarnings = checkGitStaleness(transformedDocs, config);
+    const gitWarnings = checkGitStaleness(transformedDocs, config, opts.gitMetadataOptions);
     warnings.push(...gitWarnings);
 
     const claudeWarnings = checkClaudeCommands(config.repoRoot);
@@ -326,8 +332,7 @@ export function parseDocFile(filePath, config, opts = {}) {
   }
 
   // Tag doc with its root
-  const roots = config.docsRoots || [config.docsRoot];
-  const docRoot = roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
+  const docRoot = findLexicalDocsRoot(filePath, config) ?? config.docsRoot;
   const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
 
   const docType = asString(parsedFrontmatter.type) ?? null;
@@ -365,7 +370,7 @@ export function parseDocFile(filePath, config, opts = {}) {
     hasNextStep: Boolean(nextStep),
     hasBlockers: blockers.length > 0,
     daysSinceUpdate: computeDaysSinceUpdate(asString(parsedFrontmatter.updated) ?? null),
-    isStale: computeIsStale(asString(parsedFrontmatter.status), asString(parsedFrontmatter.updated) ?? null, config),
+    isStale: computeIsStale(asString(parsedFrontmatter.status), asString(parsedFrontmatter.updated) ?? null, config, docType),
     warnings: [],
     errors: [],
   };

package/src/init.mjs

@@ -313,7 +313,7 @@ export async function runInit(cwd, config, opts = {}) {
     process.stdout.write(`                 export const root = [${subs.map(s => `'${s}'`).join(', ')}];\n`);
   }
 
-  // .gitignore: ensure .dotmd/ is ignored (session leases live there)
+  // .gitignore: ensure .dotmd/ is ignored (session ownership records live there)
   const gitignorePath = path.join(cwd, '.gitignore');
   const ignoreLine = '.dotmd/';
   if (existsSync(gitignorePath)) {