dotmd-cli 0.67.0 → 0.69.0

package/bin/dotmd.mjs

@@ -1078,9 +1078,10 @@ Examples:
 The "save a resume prompt" verb. Works mid-anything:
 
 Plan mode (a plan is in-session, or you pass one):
-  1. Saves a resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …).
-     The prompt is session-local — the next session's hud surfaces it; never
-     paste resume text into chat.
+  1. Saves a resume prompt named resume-<plan-slug> (collision-safe: -2, -3, …),
+     stamped with a plan: link so consuming it re-claims the plan (see \`dotmd
+     use\`). The prompt is session-local — the next session's hud surfaces it;
+     never paste resume text into chat.
   2. Releases the plan: one status flip, in-session → active by default
      (--status to override, --note to record why in ## Version History).
   3. Prints the exact \`git commit\` for the plan's frontmatter change — the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.67.0",
+  "version": "0.69.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -48,7 +48,7 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "@notionhq/client": "^5.13.0",
     "notion-to-md": "^3.1.9"
   }

package/src/baton.mjs

@@ -5,7 +5,8 @@ import { asString, toRepoPath, die, warn, currentSessionId } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { readJournalEntries } from './journal.mjs';
 import { runNew, readBodyInput } from './new.mjs';
-import { runSet } from './lifecycle.mjs';
+import { runSet, updateFrontmatter } from './lifecycle.mjs';
+import { resolvePromptInput } from './prompts.mjs';
 import { green, dim } from './color.mjs';
 
 // `dotmd baton` is the one-command handoff: save the resume prompt AND release
@@ -31,9 +32,9 @@ function matchesDocRef(doc, ref) {
 // or lock — in-session is just frontmatter — so ownership is reconstructed
 // from the per-repo journal: the last `use <plan>` / `set in-session <plan>`
 // this sid ran whose target is still in-session. Falls back to "the only
-// in-session plan" when the journal can't answer (disabled, or another tool
-// flipped the status). Returns { plan, via, inSession }; plan is null when
-// there's no defensible answer (caller decides how to ask).
+// in-session plan" when the journal is *silent* for this session (disabled, or
+// another tool flipped the status). Returns { plan, via, inSession }; plan is
+// null when there's no defensible answer (caller decides how to ask).
 export function findOwnedPlan(config, index = null) {
   const idx = index ?? buildIndex(config);
   const inSession = idx.docs.filter(d => d.type === 'plan' && d.status === 'in-session');
@@ -42,6 +43,13 @@ export function findOwnedPlan(config, index = null) {
   const sid = currentSessionId();
   let entries = [];
   try { entries = readJournalEntries(config); } catch { entries = []; }
+  // Did THIS session issue any ownership command at all (`use` / `set in-session`
+  // / `status … in-session`)? If it did but none matched an in-session plan, this
+  // session's work lives elsewhere (e.g. it consumed a `use <prompt>`, or worked
+  // a plan that's since been released) — so the lone in-session plan is
+  // presumptively *another* session's, and auto-selecting it would flip a
+  // stranger's status. Track that to gate the single-in-session fast path below.
+  let sawOwnershipRef = false;
   for (let i = entries.length - 1; i >= 0; i--) {
     const e = entries[i];
     if (e?.sid !== sid || !Array.isArray(e.argv) || (e.exit ?? 0) !== 0) continue;
@@ -51,11 +59,19 @@ export function findOwnedPlan(config, index = null) {
     else if (a[0] === 'set' && a[1] === 'in-session') ref = a.slice(2).find(x => typeof x === 'string' && !x.startsWith('-'));
     else if (a[0] === 'status' && a.includes('in-session')) ref = a.slice(1).find(x => typeof x === 'string' && !x.startsWith('-') && x !== 'in-session');
     if (!ref) continue;
+    sawOwnershipRef = true;
     const doc = inSession.find(d => matchesDocRef(d, ref));
     if (doc) return { plan: doc, via: 'journal', inSession };
   }
 
-  if (inSession.length === 1) return { plan: inSession[0], via: 'single-in-session', inSession };
+  // Single-in-session fast path — ONLY when the journal is silent about this
+  // session's ownership intent. If this sid *did* run an ownership command that
+  // pointed somewhere other than the lone in-session plan, refuse and let the
+  // caller demand an explicit slug/plan rather than hand off a plan this session
+  // never touched (the cross-session baton misfire).
+  if (inSession.length === 1 && !sawOwnershipRef) {
+    return { plan: inSession[0], via: 'single-in-session', inSession };
+  }
   return { plan: null, via: null, inSession };
 }
 
@@ -193,6 +209,17 @@ export async function runBaton(argv, config, opts = {}) {
   }
   if (!createdSlug) die(`Could not find a free prompt slug for ${slugBase} (tried ${slugBase}-2 … ${slugBase}-9).`);
 
+  // Link the prompt back to its plan so the next session's `dotmd use` re-claims
+  // it (consume = claim). The resume-<slug> filename is a lossy link under -N
+  // suffixing / plan renames; the explicit `plan:` field is the durable one.
+  // Best-effort: a resolve/write hiccup must never fail an otherwise-good handoff.
+  if (planPath && !dryRun) {
+    try {
+      const promptPath = resolvePromptInput(createdSlug, config, { dieOnMiss: false });
+      if (promptPath) updateFrontmatter(promptPath, { plan: repoPath });
+    } catch { /* stamping is best-effort */ }
+  }
+
   // 2. Release the plan — exactly one status flip. Skipped entirely in slug
   // mode: with no plan involved there is nothing to release.
   let archiveResult = null;
@@ -203,7 +230,9 @@ export async function runBaton(argv, config, opts = {}) {
     } else {
       const setArgs = [status, planPath];
       if (note) setArgs.push('--note', note);
-      archiveResult = await runSet(setArgs, config, { dryRun });
+      // viaBaton: this release IS the handoff — don't let runSet nudge "leave a
+      // baton" on top of the baton we're in the middle of.
+      archiveResult = await runSet(setArgs, config, { dryRun, viaBaton: true });
       statusChanged = true;
     }
   }

package/src/lifecycle.mjs

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter, normalizeEol } from './frontmatter.mjs';
-import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath } from './util.mjs';
+import { asString, toRepoPath, die, warn, resolveDocPath, resolveRefPath, escapeRegex, nowIso, suggestCandidates, emitFilesFooter, isArchivedPath, currentSessionId } from './util.mjs';
+import { readJournalEntries } from './journal.mjs';
 import { gitMv, getGitLastModifiedBatch } from './git.mjs';
 import { buildIndex, collectDocFiles, resolveDocArg } from './index.mjs';
 import { renderIndexFile, writeIndex } from './index-file.mjs';
@@ -598,6 +599,24 @@ export function runArchive(argv, config, opts = {}) {
 // `dotmd set in-session <path>` is refused — acquiring a lease is asymmetric
 // enough to deserve its own verb (`dotmd pickup`), and silently routing here
 // would skip the lease-acquisition path entirely.
+
+// Did THIS session already hand off via `dotmd baton`? The journal records the
+// top-level argv of every invocation; a successful `baton …` means a resume
+// prompt was saved this session, so the closure nudge would be redundant. Best
+// effort — a disabled journal degrades to "might nudge," which is harmless for
+// an advisory line. (baton's own internal `runSet` is suppressed by `viaBaton`,
+// since its journal entry isn't written until the process exits.)
+function batonSavedThisSession(config) {
+  const sid = currentSessionId();
+  let entries = [];
+  try { entries = readJournalEntries(config); } catch { return false; }
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const e = entries[i];
+    if (e?.sid === sid && (e.exit ?? 0) === 0 && Array.isArray(e.argv) && e.argv[0] === 'baton') return true;
+  }
+  return false;
+}
+
 export async function runSet(argv, config, opts = {}) {
   const { dryRun } = opts;
   const noIndex = argv.includes('--no-index');
@@ -631,26 +650,56 @@ export async function runSet(argv, config, opts = {}) {
     return runArchive(archiveArgs, config, { dryRun, note, archiveStatus: newStatus });
   }
 
-  // `partial` promises a successor tracking the deferred tail. When neither a
-  // --note nor any doc reference exists to point at it, remind — advisory
-  // only, computed before the transition (filing may move the file).
+  // Two advisory reminders, both computed from one pre-transition frontmatter
+  // read (a non-archive `set` never moves the file, so the path stays valid).
+  // Advisory only — never block the transition.
   let partialReminder = false;
-  if (newStatus === 'partial' && !note) {
-    try {
-      const { frontmatter: fmRaw, body } = extractFrontmatter(readFileSync(filePath, 'utf8'));
-      const related = parseSimpleFrontmatter(fmRaw).related_plans;
+  let batonNudge = false;
+  try {
+    const { frontmatter: fmRaw, body } = extractFrontmatter(readFileSync(filePath, 'utf8'));
+    const fm = parseSimpleFrontmatter(fmRaw);
+
+    // `partial` promises a successor tracking the deferred tail. When neither a
+    // --note nor any doc reference exists to point at it, remind.
+    if (newStatus === 'partial' && !note) {
+      const related = fm.related_plans;
       const hasRelated = Array.isArray(related) ? related.length > 0 : Boolean(asString(related)?.trim());
       partialReminder = !hasRelated && !/[\w./-]+\.md\b/.test(body);
-    } catch { /* advisory only */ }
-  }
+    }
+
+    // Baton-on-exit backstop (the one core-loop step with no other mechanical
+    // catch). Fire ONLY on the baton-less in-session release: a plan you were
+    // actively working (old status `in-session`) is being parked at a
+    // non-terminal stop status while a known next pickup (`next_step`) remains,
+    // and no baton was saved this session. `archived` never reaches here (routed
+    // to runArchive above), so this can't fire on a fully-done close. Gating on
+    // `in-session` keeps it off pure triage of never-started plans — where no
+    // session work is owed a handoff — which is how the nag-fatigue risk is
+    // managed. Suppressed for baton's own internal release via `opts.viaBaton`.
+    if (!opts.viaBaton) {
+      const docType = asString(fm.type) ?? 'plan';
+      const oldStatus = asString(fm.status);
+      const nextStep = asString(fm.next_step)?.trim();
+      batonNudge = docType === 'plan'
+        && oldStatus === 'in-session'
+        && newStatus !== 'in-session'
+        && Boolean(nextStep)
+        && !batonSavedThisSession(config);
+    }
+  } catch { /* advisory only */ }
 
   const statusArgs = [filePath, newStatus];
   if (noIndex) statusArgs.push('--no-index');
   if (showFiles) statusArgs.push('--show-files');
   await runStatus(statusArgs, config, { dryRun, suppressDeprecation: true, note });
 
-  if (partialReminder && !dryRun) {
-    warn('partial usually references the successor plan tracking the tail — add a link to the body, or rerun with --note "tail tracked in <plan>".');
+  if (!dryRun) {
+    if (partialReminder) {
+      warn('partial usually references the successor plan tracking the tail — add a link to the body, or rerun with --note "tail tracked in <plan>".');
+    }
+    if (batonNudge) {
+      warn(`wrapping up? leave a baton so the next session picks up cleanly — \`dotmd baton ${path.basename(filePath, '.md')} @draft\` saves a resume prompt (no copy-paste into chat).`);
+    }
   }
 }
 

package/src/lint.mjs

@@ -73,12 +73,26 @@ export function runLint(argv, config, opts = {}) {
     // existing plural array happens at apply-time so the message reflects
     // just what's being introduced from the singular form.
     for (const { singular, plural } of [{ singular: 'module', plural: 'modules' }, { singular: 'surface', plural: 'surfaces' }]) {
-      const val = asString(parsed[singular]);
-      if (!val) continue;
-      const values = val.includes(',')
-        ? val.split(',').map(s => s.trim()).filter(Boolean)
-        : [val];
-      fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+      const rawVal = parsed[singular];
+      const val = asString(rawVal);
+      if (val) {
+        // Inline value (`surface: foo`) → migrate into the plural array.
+        const values = val.includes(',')
+          ? val.split(',').map(s => s.trim()).filter(Boolean)
+          : [val];
+        fixes.push({ field: singular, oldValue: val, newValue: values, pluralKey: plural, type: 'singular-to-plural' });
+      } else if (singular in parsed && (!Array.isArray(rawVal) || rawVal.length === 0)) {
+        // Empty deprecated key (`surface:` with nothing after it, which the
+        // parser yields as `[]`) — usually sitting right above a populated
+        // `surfaces:`. There's no value to migrate; the deprecation warning
+        // just wants the dead line gone. `validate` treats the empty `[]` as
+        // present (so it warns), while the old `asString` gate here saw it as
+        // absent and skipped — the exact no-op reported in issue #17. Emit a
+        // drop fix so `lint --fix` does what the warning advertises. A
+        // populated block-form singular (rawVal.length > 0) is left untouched:
+        // too rare to risk mis-editing.
+        fixes.push({ field: singular, pluralKey: plural, type: 'drop-singular' });
+      }
     }
 
     // Trailing whitespace in values
@@ -102,8 +116,22 @@ export function runLint(argv, config, opts = {}) {
   // Also get non-fixable issues from index, excluding issues we can already fix
   const index = buildIndex(config);
   const fixablePaths = new Set(fixable.map(f => f.repoPath));
+  // Singular-key deprecation warnings whose fix `lint --fix` will actually make.
+  // Without this, those warnings landed in BOTH the "fixable" preview and the
+  // "non-fixable" list, so the header claimed "N non-fixable" while every line
+  // told you to run `lint --fix` (issue #17, item 8).
+  const fixableSingularKeys = new Set();
+  for (const { repoPath, fixes } of fixable) {
+    for (const f of fixes) {
+      if (f.type === 'singular-to-plural' || f.type === 'drop-singular') {
+        fixableSingularKeys.add(`${repoPath}::${f.field}`);
+      }
+    }
+  }
   const nonFixable = [...index.errors, ...index.warnings].filter(issue => {
     if (issue.message.includes('Missing frontmatter `status`') && fixablePaths.has(issue.path)) return false;
+    const dep = issue.message.match(/^`(module|surface):` \(singular\) is deprecated/);
+    if (dep && fixableSingularKeys.has(`${issue.path}::${dep[1]}`)) return false;
     return true;
   });
 
@@ -120,6 +148,8 @@ export function runLint(argv, config, opts = {}) {
             process.stdout.write(dim(`    missing status (fixable via AI)\n`));
           } else if (f.type === 'singular-to-plural') {
             process.stdout.write(dim(`    ${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]\n`));
+          } else if (f.type === 'drop-singular') {
+            process.stdout.write(dim(`    remove deprecated \`${f.field}:\` (empty; \`${f.pluralKey}:\` is the live key)\n`));
           } else if (f.type === 'eof') {
             process.stdout.write(dim(`    missing newline at end of file\n`));
           } else if (f.type === 'add') {
@@ -155,6 +185,7 @@ export function runLint(argv, config, opts = {}) {
     let needsEofFix = false;
     const trimFixes = [];
     const singularToPlural = [];
+    const dropSingular = [];
 
     for (const f of fixes) {
       if (f.type === 'rename-key') {
@@ -165,6 +196,8 @@ export function runLint(argv, config, opts = {}) {
         trimFixes.push(f);
       } else if (f.type === 'singular-to-plural') {
         singularToPlural.push(f);
+      } else if (f.type === 'drop-singular') {
+        dropSingular.push(f);
       } else {
         updates[f.field] = f.newValue;
       }
@@ -212,6 +245,19 @@ export function runLint(argv, config, opts = {}) {
         writeFileSync(filePath, raw, 'utf8');
       }
 
+      // Drop empty deprecated singular keys. The value is known-empty (the fix
+      // is only emitted for `[]`/`''`), so this matches the bare `key:` line
+      // exactly — never a line carrying content — and removes it.
+      for (const ds of dropSingular) {
+        let raw = readFileSync(filePath, 'utf8');
+        const { frontmatter: fm } = extractFrontmatter(raw);
+        const newFm = fm
+          .replace(new RegExp(`^${escapeRegex(ds.field)}:[ \\t]*$`, 'm'), '')
+          .replace(/\n{2,}/g, '\n');
+        raw = replaceFrontmatter(raw, newFm.trim());
+        writeFileSync(filePath, raw, 'utf8');
+      }
+
       // Apply key renames and trim fixes via raw string manipulation
       if (keyRenames.length > 0 || trimFixes.length > 0) {
         let raw = readFileSync(filePath, 'utf8');
@@ -259,6 +305,8 @@ export function runLint(argv, config, opts = {}) {
         }
       } else if (f.type === 'singular-to-plural') {
         process.stdout.write(`${prefix}  ${dim(`${f.field}: "${f.oldValue}" → ${f.pluralKey}: [${f.newValue.join(', ')}]`)}\n`);
+      } else if (f.type === 'drop-singular') {
+        process.stdout.write(`${prefix}  ${dim(`removed deprecated \`${f.field}:\` (empty)`)}\n`);
       } else if (f.type === 'add') {
         process.stdout.write(`${prefix}  ${dim(`add ${f.field}: ${f.newValue}`)}\n`);
       } else {

package/src/notion.mjs

@@ -16,7 +16,7 @@ async function loadDeps() {
     notionClient = Client;
     notionToMd = NotionToMarkdown;
   } catch {
-    die('Notion dependencies not installed. Run: npm install @notionhq/client notion-to-md');
+    die('Notion integration needs its optional dependencies. Run: npm install @notionhq/client notion-to-md\n(These ship as optionalDependencies — a plain `npm i -g dotmd-cli` installs them unless you passed `--omit=optional`.)');
   }
 }
 

package/src/prompts.mjs

@@ -1,13 +1,18 @@
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync, statSync, existsSync } from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath, isArchivedPath } from './util.mjs';
-import { buildIndex } from './index.mjs';
+import { asString, toRepoPath, die, resolveDocPath, isArchivedPath, currentSessionId } from './util.mjs';
+import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
-import { runArchive, runStatus } from './lifecycle.mjs';
+import { runArchive, runStatus, updateFrontmatter } from './lifecycle.mjs';
+import { appendJournalEntry } from './journal.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
 
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
 // canonical output ("Consumed: …") is unchanged.
@@ -283,6 +288,48 @@ export function consumePrompt(filePath, config, opts) {
 
   const consumedPath = archiveResult?.newRepoPath ?? repoPath;
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
+
+  // Consume = claim: a baton-created resume prompt carries `plan: <path>`.
+  // Adopt that plan for THIS session so the next `dotmd baton` (with no arg)
+  // hands it off — closing the cross-session ownership loop that otherwise dies
+  // at the prompt boundary.
+  claimPromptPlan(asString(parsed.plan), config);
+}
+
+// Flip the resume prompt's linked plan to in-session for this session and
+// record the ownership in the journal. The journal entry matters: baton's
+// `findOwnedPlan` reconstructs ownership from journaled `set in-session <plan>`
+// commands, and the outer `use <prompt>` argv can't tie a prompt ref to a plan
+// — so without this synthetic entry the claim would be invisible to baton (and,
+// with the misfire gate, would even make the next baton refuse).
+function claimPromptPlan(planRef, config) {
+  if (!planRef) return;
+  let planPath = null;
+  try { planPath = resolveDocPath(planRef, config) ?? resolveDocArg(planRef, config, { dieOnMiss: false }); }
+  catch { planPath = null; }
+  if (!planPath || !existsSync(planPath)) return; // link went stale (plan renamed/removed) — the resume body already printed, so stay quiet
+
+  let planFm;
+  try { planFm = parseSimpleFrontmatter(extractFrontmatter(readFileSync(planPath, 'utf8')).frontmatter); }
+  catch { return; }
+  const cur = asString(planFm.status);
+  // Only claim a startable plan. Already in-session → someone's on it (don't
+  // steal); archived/terminal → the link is stale. Either way, leave it be.
+  if (!cur || cur === 'in-session' || cur === 'archived') return;
+
+  const repoPath = toRepoPath(planPath, config.repoRoot);
+  try { updateFrontmatter(planPath, { status: 'in-session' }); }
+  catch { return; }
+  try {
+    // `v` MUST be the real CLI version: the journal rotates when a new entry's
+    // version differs from the file's first entry, so a sentinel here would shove
+    // our just-written claim into the backup file where findOwnedPlan can't see it.
+    appendJournalEntry(config, {
+      ts: new Date().toISOString(), sid: currentSessionId(), pid: process.pid,
+      argv: ['set', 'in-session', repoPath], exit: 0, ms: 0, v: pkg.version,
+    });
+  } catch { /* journal is best-effort — the status flip already landed */ }
+  process.stderr.write(`${green('→ Claimed')}: ${repoPath} (in-session)\n`);
 }
 
 // Read-only peek: print the body WITHOUT consuming. The sanctioned triage path