dotmd-cli 0.49.5 → 0.50.1

package/README.md

@@ -879,9 +879,15 @@ export const index = {
   path: 'docs/docs.md',
   startMarker: '<!-- GENERATED:dotmd:start -->',
   endMarker: '<!-- GENERATED:dotmd:end -->',
+  snapshot: 'status', // default; use 'state' to include live current_state text
 };
 ```
 
+Generated indexes default to status-only rows for live sections so README files
+do not become stale mirrors of volatile `current_state` text. Set
+`snapshot: 'state'` if you want the older `Status Snapshot` table for live
+sections too. Archived highlights still include their historical snapshots.
+
 All exports are optional. Additional options: `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
 
 Config discovery walks up from cwd looking for `dotmd.config.mjs` or `.dotmd.config.mjs`.

package/dotmd.config.example.mjs

@@ -144,6 +144,7 @@ export const index = {
   path: 'docs/docs.md',
   startMarker: '<!-- GENERATED:dotmd:start -->',
   endMarker: '<!-- GENERATED:dotmd:end -->',
+  snapshot: 'status', // default; use 'state' to include live current_state text
   archivedLimit: 8,
 };
 

package/package.json

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

package/src/claude-commands.mjs

@@ -133,7 +133,7 @@ function generateDocsCommand(config, version) {
 
   lines.push('Commands for working with docs:');
   lines.push('- `dotmd context` — LLM-oriented briefing across all types');
-  lines.push('- `dotmd doctor` — auto-fix everything in one pass (refs, lint, dates, index)');
+  lines.push('- `dotmd doctor --apply` — auto-fix everything in one pass (refs, lint, dates, index; bare `dotmd doctor` previews only)');
   lines.push('- `dotmd query [filters]` — search by status, keyword, module, surface, type, staleness');
   lines.push('- `dotmd health` — plan pipeline, velocity, aging');
   lines.push('- `dotmd stats` — doc health dashboard (completeness, checklists, audit coverage)');

package/src/config.mjs

@@ -316,6 +316,10 @@ function validateConfig(userConfig, config, validStatuses, indexPath) {
     warnings.push(`Config: index path does not exist: ${indexPath}`);
   }
 
+  if (config.index?.snapshot !== undefined && !['status', 'state'].includes(config.index.snapshot)) {
+    warnings.push("Config: index.snapshot must be 'status' or 'state'.");
+  }
+
   // Unknown top-level user config keys
   for (const key of Object.keys(userConfig)) {
     if (!VALID_CONFIG_KEYS.has(key)) {
@@ -512,6 +516,7 @@ export async function resolveConfig(cwd, explicitConfigPath) {
     indexPath,
     indexStartMarker: config.index?.startMarker ?? '<!-- GENERATED:dotmd:start -->',
     indexEndMarker: config.index?.endMarker ?? '<!-- GENERATED:dotmd:end -->',
+    indexSnapshot: config.index?.snapshot ?? 'status',
     archivedHighlightLimit: config.index?.archivedLimit ?? 8,
 
     context: config.context,

package/src/hud.mjs

@@ -4,21 +4,11 @@ import { readLeases, findStaleLeases, currentSessionId, isLeaseStale, STALE_LEAS
 import { scrubStaleSilently } from './lease-scrub.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
-import { dim, yellow } from './color.mjs';
+import { dim } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
 import { readJournalEntries, journalFilePath } from './journal.mjs';
 
-const MAX_PREVIEW = 5;
-
-function slug(repoPath) { return path.basename(repoPath, '.md'); }
-
-function previewList(items, max = MAX_PREVIEW) {
-  const slugs = items.slice(0, max).map(slug);
-  const more = items.length > max ? `, +${items.length - max} more` : '';
-  return slugs.join(', ') + more;
-}
-
 // Statuses that count as "actionable" for a prompt are derived from config:
 // types.prompt.context.expanded (the statuses the user wants prominently shown).
 // Falls back to ['pending'] when no prompt type is configured (defensive default
@@ -223,11 +213,12 @@ export function runHud(argv, config) {
   const hud = buildHud(config);
 
   // Self-heal stale slash-command files. Wrapped: a broken scaffolder must
-  // never kill the SessionStart hook (would block every session). Skipped in
-  // --json mode to keep the structured shape stable for programmatic callers.
-  let refreshed = [];
+  // never kill the SessionStart hook (would block every session). Runs for its
+  // side effect only — the refresh is no longer 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 { refreshed = refreshStaleSlashCommands(config); }
+    try { refreshStaleSlashCommands(config); }
     catch { /* swallow — see comment above */ }
   }
 
@@ -236,58 +227,15 @@ export function runHud(argv, config) {
     return;
   }
 
-  const lines = [];
-
-  // Always-on command primer. Replaces the prior plan-state / prompts /
-  // stuck-leases / validation-errors lines — those signals belong inside
-  // their own commands (`plans`, `prompts`), not in the SessionStart hook.
-  // hud's job is purely to remind the agent which verbs exist, since that's
-  // the one thing the agent reaches for `--help` to recover. Keep it tight:
-  // one line, the minimum verb set.
-  lines.push(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)'));
-
-  const state = [];
-  if (hud.owned?.length) state.push(`held: ${hud.owned.length} (${previewList(hud.owned)})`);
-  if (hud.prompts?.length) state.push(`prompts: ${hud.prompts.length} (${previewList(hud.prompts)})`);
-  if (hud.stale?.length) state.push(`stuck: ${hud.stale.length} (${previewList(hud.stale)})`);
-  if (hud.errors > 0) state.push(`errors: ${hud.errors} (run dotmd check)`);
-  if (state.length) lines.push(yellow(state.join(' · ')));
-
-  if (refreshed.length > 0) {
-    const from = refreshed[0].from;
-    const to = refreshed[0].to;
-    const names = refreshed.map(r => r.name).join(', ');
-    lines.push(dim(`↻ slash commands refreshed (v${from} → v${to}): ${names}`));
-  }
-
-  // F17b: three journal-aware sections. Silent-when-clean: each block emits
-  // only when it has entries.
-  if (hud.previousSelf?.length) {
-    lines.push(dim('— previous self —'));
-    for (const e of hud.previousSelf) {
-      const cmd = (e.argv ?? []).join(' ');
-      const exitTag = e.exit === 0 ? '' : `, exit ${e.exit}`;
-      lines.push(dim(`  ${cmd} (${e.ago}${exitTag})`));
-    }
-  }
-
-  if (hud.fleet?.length) {
-    lines.push(dim('— fleet (last 24h) —'));
-    for (const f of hud.fleet) {
-      const heldTag = f.holding?.length
-        ? ` · holding ${f.holding.map(p => path.basename(p, '.md')).join(', ')}`
-        : '';
-      const staleTag = f.stale ? yellow(' [stale]') : '';
-      lines.push(dim(`  session ${f.sid} · ${f.cmds} cmds · last ${f.lastAgo}${heldTag}`) + staleTag);
-    }
-  }
-
-  if (hud.recentRejections?.length) {
-    lines.push(dim('— recent rejections (last 1h) —'));
-    for (const r of hud.recentRejections) {
-      lines.push(dim(`  ${r.count}× "${r.cls}" on \`${r.cmd}\``));
-    }
-  }
-
-  process.stdout.write(lines.join('\n') + '\n');
+  // SessionStart contract: emit ONLY the command primer — the verb cheat-sheet
+  // that tells the agent which dotmd verbs exist. Everything else hud used to
+  // print (held/prompts/stuck/errors state, slash-command refresh notices, and
+  // the journal-aware previous-self / fleet / recent-rejections sections) is
+  // deliberately suppressed here: those signals nudged agents into phantom
+  // follow-up work — e.g. "errors: 1 (run dotmd check)" prompting a check run
+  // for state that belongs inside its own command. Each of those signals lives
+  // in its proper command (`plans`, `prompts`, `check`) and stays available via
+  // `dotmd hud --json` for programmatic callers. The hook's job is purely to
+  // teach the verbs, never to report status.
+  process.stdout.write(dim('dotmd: plans|briefing  set <status> [<file>]  new <type> <slug>  use [<file>]  archive <file>  (use [no-arg] → oldest pending prompt)') + '\n');
 }

package/src/index-file.mjs

@@ -21,6 +21,7 @@ export function renderIndexFile(index, config) {
 function renderGeneratedBlock(index, config) {
   const lines = [];
   const indexDir = config.indexPath ? path.dirname(path.relative(config.repoRoot, config.indexPath)).split(path.sep).join('/') : '';
+  const snapshotMode = config.indexSnapshot ?? 'status';
 
   for (const status of config.statusOrder) {
     const docs = index.docs.filter(doc => doc.status === status);
@@ -34,10 +35,9 @@ function renderGeneratedBlock(index, config) {
 
     lines.push(`## ${capitalize(status)}`);
     lines.push('');
-    lines.push('| Doc | Status Snapshot |');
-    lines.push('|-----|-----------------|');
+    lines.push(...snapshotHeader(snapshotMode));
     for (const doc of docs) {
-      const snapshot = formatSnapshot(doc, config);
+      const snapshot = renderIndexSnapshot(doc, config, snapshotMode);
       const linkPath = indexDir ? path.relative(indexDir, doc.path).split(path.sep).join('/') : doc.path;
       lines.push(`| [${escapeTable(doc.title)}](${linkPath}) | ${escapeTable(snapshot)} |`);
     }
@@ -76,6 +76,16 @@ function renderArchivedSection(docs, config, status) {
   return lines;
 }
 
+function snapshotHeader(snapshotMode) {
+  if (snapshotMode === 'state') return ['| Doc | Status Snapshot |', '|-----|-----------------|'];
+  return ['| Doc | Status |', '|-----|--------|'];
+}
+
+function renderIndexSnapshot(doc, config, snapshotMode) {
+  if (snapshotMode === 'state') return formatSnapshot(doc, config);
+  return capitalize(doc.status ?? 'unknown');
+}
+
 export function writeIndex(content, config) {
   writeFileSync(config.indexPath, content, 'utf8');
 }

package/src/init.mjs

@@ -189,6 +189,7 @@ function generateDetectedConfig(scan, rootPath) {
   lines.push(`  path: '${rootPath}/docs.md',`);
   lines.push(`  startMarker: '<!-- GENERATED:dotmd:start -->',`);
   lines.push(`  endMarker: '<!-- GENERATED:dotmd:end -->',`);
+  lines.push(`  snapshot: 'status',`);
   lines.push('};');
   lines.push('');
 

package/src/render.mjs

@@ -493,7 +493,7 @@ function _renderCheck(index, opts = {}) {
       }
       lines.push('');
     } else {
-      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail. \`dotmd doctor\` auto-fixes supported issues; remaining issues need the suggested manual command.`));
+      lines.push(dim(`Run \`dotmd check --verbose\` for per-doc detail. \`dotmd doctor --apply\` auto-fixes supported issues (bare \`dotmd doctor\` previews only); remaining issues need the suggested manual command.`));
       lines.push('');
     }
   }

package/src/validate.mjs

@@ -416,7 +416,10 @@ export function checkBidirectionalReferences(docs, config) {
 // rendering), so divergence almost always means the agent forgot the back-link.
 // Warning fires on the CHILD (that's the file that needs the edit). Skips
 // terminal/archive statuses on either side — runlists referencing closed work
-// are a normal history pattern.
+// are a normal history pattern. A `>`-prefixed (one-way) runlist entry opts
+// that child out of the back-pointer requirement — the same per-ref escape
+// hatch the bidirectional reciprocity check honors (A4) — so a hub can order a
+// child it doesn't own without nagging the child to add `parent_plan:`.
 export function checkRunlistBackPointers(docs, config) {
   const warnings = [];
   const skipStatuses = new Set([
@@ -428,10 +431,13 @@ export function checkRunlistBackPointers(docs, config) {
   for (const hub of docs) {
     if (skipStatuses.has(hub.status)) continue;
     const runlistRefs = hub.refFields?.runlist ?? [];
+    const runlistDirs = hub.refFieldDirections?.runlist ?? [];
     if (runlistRefs.length === 0) continue;
     const hubDir = path.dirname(path.join(config.repoRoot, hub.path));
 
-    for (const ref of runlistRefs) {
+    for (let i = 0; i < runlistRefs.length; i++) {
+      const ref = runlistRefs[i];
+      if (runlistDirs[i] === 'one-way') continue; // `> child.md` → ordered but no back-pointer expected
       const resolved = resolveRefPath(ref, hubDir, config.repoRoot);
       if (!resolved) continue; // unresolved refs already get their own existence error
       const childPath = toRepoPath(resolved, config.repoRoot);