dotmd-cli 0.49.0 → 0.49.2

package/README.md

@@ -188,7 +188,7 @@ dotmd actionable             List docs with next steps
 dotmd index [--print]        Generate/update docs.md index block
 dotmd hud                    Actionable triage (silent when clean — ideal SessionStart hook)
 dotmd pickup <file>          Pick up a plan (in-session + print body)
-dotmd release [<file>]       Release in-session lease (alias: unpickup)
+dotmd release [<file>]       Release in-session lease (aliases: unpickup, finish)
 dotmd status <file> <status> Transition document status
 dotmd archive <file>         Archive (status + move + update refs)
 dotmd bulk archive <files>   Archive multiple files at once
@@ -335,8 +335,10 @@ Each invocation appends one JSON line:
 `{ts, sid, pid, argv, exit, ms, v, err?}`. Writes are atomic via
 `O_APPEND` (entries are well under `PIPE_BUF`), so concurrent sessions
 interleave cleanly without locking. Lazy rotation to
-`.dotmd/journal.jsonl.1` at >5MB or oldest entry >30 days; one backup
-retained.
+`.dotmd/journal.jsonl.1` on version change, at >5MB, or when the oldest
+entry is >30 days; one backup retained and pruned after 30 days.
+Version-change rotation keeps agent-facing journal summaries focused on the
+currently installed dotmd.
 
 Read it back with `dotmd journal`:
 
@@ -583,7 +585,9 @@ dotmd status docs/plans/my-plan.md partial   # shipped + tail deferred (referenc
 dotmd status docs/plans/my-plan.md awaiting  # stuck on a human decision
 ```
 
-`finish` is a legacy command that defaults to `status: done`, which is no longer in the default plan vocabulary as of 0.16. Use `archive` (fully shipped) or `release` + `status` (anything else). If you need it back, add `done` to `types.plan.statuses` in your config.
+`finish` is an alias for `release`, kept for older agent instructions that use
+that verb for closeout. To fully close shipped work, archive it. To keep working
+later, release it back to the prior status or use `dotmd set <status> <file>`.
 
 ### Session leases & release
 
@@ -596,8 +600,8 @@ distinct outcomes when a plan is already `in-session`:
   re-prints the body. No conflict.
 - **Cross-session conflict.** If another live session holds the plan,
   pickup refuses with `Held by <host>/<session> (pid <pid>) since <time>`.
-- **Stale lease.** If the holder's pid is dead (or the lease is >24h old),
-  pickup refuses but suggests `--takeover`.
+- **Reclaimable lease.** If the holder's same-host pid is dead, or the lease is
+  older than 4 hours, pickup can reclaim it without `--takeover`.
 
 Releasing leases (both names work; `release` is the recommended verb):
 
@@ -605,13 +609,13 @@ Releasing leases (both names work; `release` is the recommended verb):
 dotmd release                     # release every lease owned by current session
 dotmd release docs/plans/foo.md   # release that one (refuses cross-session)
 dotmd release --to planned        # override target status (default: lease.oldStatus)
-dotmd release --stale             # release leases with dead pid or >24h old
+dotmd release --stale             # release leases with dead same-host pid or >4h old
 dotmd release --all               # release every lease (administrative)
 dotmd release --json              # { released: [...], skipped: [...] }
 ```
 
-`finish`, `archive`, and `rename` auto-release / migrate the lease, so the
-common closeout paths are covered without ceremony.
+`finish` is the same as `release`. `archive` and `rename` auto-release or
+migrate the lease, so the common closeout paths are covered without ceremony.
 
 **Session id resolution** (in order, first wins):
 
@@ -666,7 +670,7 @@ either is silent.
 
 `dotmd check` also catches the symmetric failure mode: a plan whose
 frontmatter claims `status: in-session` but whose lease either doesn't
-exist (last session crashed before releasing) or is stale (>24h since
+exist (last session crashed before releasing) or is stale (>4h since
 pickup). Each warning names the exact unstuck command
 (`dotmd release <plan>` or `dotmd status <plan> active`), so plans
 don't sit stuck in-session indefinitely. Always-on — legit concurrent

package/bin/dotmd.mjs

@@ -283,8 +283,10 @@ Reader options:
   --json              Emit selected entries as a JSON array
 
 Storage:
-  Rotates to .dotmd/journal.jsonl.1 at >5MB or oldest entry >30 days.
-  Single backup retained; older history is dropped on rotation.
+  Rotates to .dotmd/journal.jsonl.1 on dotmd version change, at >5MB,
+  or when the oldest entry is >30 days.
+  Single backup retained for up to 30 days; older history is dropped on
+  rotation or pruned after the retention window.
 
 Examples:
   DOTMD_JOURNAL=1 dotmd plans

package/package.json

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

package/src/journal.mjs

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync } from 'node:fs';
+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';
@@ -8,6 +8,7 @@ const JOURNAL_FILE = 'journal.jsonl';
 const JOURNAL_BACKUP = 'journal.jsonl.1';
 const ROTATE_SIZE_BYTES = 5 * 1024 * 1024;
 const ROTATE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const BACKUP_RETENTION_MS = ROTATE_AGE_MS;
 
 const ERROR_LOG_FILE = 'dotmd-errors.log';
 const ERROR_LOG_BACKUP = 'dotmd-errors.log.1';
@@ -26,10 +27,31 @@ export function journalBackupPath(config) {
   return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_BACKUP);
 }
 
-function maybeRotate(file, backup) {
+function firstEntryVersion(file) {
+  try {
+    const sample = readFileSync(file, 'utf8');
+    const nl = sample.indexOf('\n');
+    const first = nl >= 0 ? sample.slice(0, nl) : sample;
+    if (!first.trim()) return null;
+    const obj = JSON.parse(first);
+    return obj?.v == null ? null : String(obj.v);
+  } catch {
+    return null;
+  }
+}
+
+function maybeRotate(file, backup, nextEntry = null) {
+  pruneStaleBackup(backup);
   if (!existsSync(file)) return;
   let st;
   try { st = statSync(file); } catch { return; }
+  if (nextEntry?.v) {
+    const existingVersion = firstEntryVersion(file);
+    if (existingVersion !== String(nextEntry.v)) {
+      try { renameSync(file, backup); } catch {}
+      return;
+    }
+  }
   if (st.size > ROTATE_SIZE_BYTES) {
     try { renameSync(file, backup); } catch {}
     return;
@@ -50,6 +72,16 @@ function maybeRotate(file, backup) {
   } catch {}
 }
 
+function pruneStaleBackup(backup) {
+  if (!existsSync(backup)) return;
+  try {
+    const st = statSync(backup);
+    if ((Date.now() - st.mtimeMs) > BACKUP_RETENTION_MS) {
+      try { unlinkSync(backup); } catch {}
+    }
+  } catch {}
+}
+
 export function appendJournalEntry(config, entry) {
   if (!isJournalEnabled(config)) return;
   if (!config?.repoRoot) return;
@@ -57,7 +89,7 @@ export function appendJournalEntry(config, entry) {
     const dir = path.join(config.repoRoot, JOURNAL_DIR);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = journalFilePath(config);
-    maybeRotate(file, journalBackupPath(config));
+    maybeRotate(file, journalBackupPath(config), entry);
     // O_APPEND is atomic for writes under PIPE_BUF (4KB on Linux, 512B on
     // macOS). Entries are well under either threshold, so concurrent CLI
     // invocations interleave cleanly without locking.
@@ -143,7 +175,7 @@ export function recordGlobalError({ config, startMs, args, err, version }) {
     const dir = globalErrorLogDir();
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = globalErrorLogPath();
-    maybeRotate(file, globalErrorLogBackupPath());
+    maybeRotate(file, globalErrorLogBackupPath(), entry);
     appendFileSync(file, JSON.stringify(entry) + '\n', { flag: 'a' });
   } catch {
     // Logging must never break exit.

package/src/new.mjs

@@ -271,6 +271,16 @@ function readBodyInput(source) {
 export async function runNew(argv, config, opts = {}) {
   const { dryRun } = opts;
 
+  const knownTypes = new Set(Object.keys(BUILTIN_TEMPLATES));
+  // Also include any custom templates from config
+  for (const k of Object.keys(config.raw?.templates ?? {})) knownTypes.add(k);
+
+  const hasNameForBody = args => {
+    if (args.length >= 2 && knownTypes.has(args[0])) return true;
+    if (args.length >= 1 && !knownTypes.has(args[0])) return true;
+    return false;
+  };
+
   // Parse args. Pull out flags first.
   const positional = [];
   let status = null;
@@ -296,17 +306,16 @@ export async function runNew(argv, config, opts = {}) {
       return;
     }
     // Treat `-` alone (stdin marker) as a positional, not a flag.
-    if (!argv[i].startsWith('-') || argv[i] === '-') positional.push(argv[i]);
+    // Once the type/name have been collected, a positional body may itself
+    // start with `---` frontmatter. Preserve it instead of dropping it as an
+    // unknown flag; the leading frontmatter merge below will handle it.
+    if (!argv[i].startsWith('-') || argv[i] === '-' || hasNameForBody(positional)) positional.push(argv[i]);
   }
 
   // Resolve type vs name:
   //   `dotmd new plan auth-revamp`     → type=plan, name=auth-revamp
   //   `dotmd new auth-revamp`          → type=doc (default), name=auth-revamp
   //   `dotmd new prompt foo "body"`    → type=prompt, name=foo, bodyArg="body"
-  const knownTypes = new Set(Object.keys(BUILTIN_TEMPLATES));
-  // Also include any custom templates from config
-  for (const k of Object.keys(config.raw?.templates ?? {})) knownTypes.add(k);
-
   let typeName, name, bodyArg = null;
   if (positional.length >= 1 && knownTypes.has(positional[0])) {
     typeName = positional[0];

package/src/ship.mjs

@@ -20,6 +20,7 @@ const ALLOWLIST_PATTERNS = [
   /^package(?:-lock)?\.json$/,
   /^README\.md$/,
   /^CLAUDE\.md$/,
+  /^CHANGELOG\.md$/,
   /^\.gitignore$/,
 ];