dotmd-cli 0.77.0 → 0.77.2

package/README.md

@@ -20,6 +20,10 @@ npm install -D dotmd-cli    # project scripts via node_modules/.bin
 npx dotmd-cli init          # try it without installing
 ```
 
+`runlist` is the canonical executable, `rl` is its short convenience alias, and
+`dotmd` remains supported during the compatibility window. All three invoke the
+same CLI; examples below retain `dotmd` while the public package identity does.
+
 Maintainer release automation is POSIX-only because it uses Bash and POSIX
 command-line tools. The published Node.js CLI remains cross-platform.
 
@@ -36,6 +40,8 @@ dotmd doctor --session    # what identity dotmd sees here, and from where
 ```
 
 Both are one-time and global; `dotmd update` keeps them in step with the CLI.
+Codex needs no install for identity: it exports `CODEX_THREAD_ID` to every tool
+shell, and dotmd reads it as a per-session identity automatically.
 
 ### Claude Code Plugin
 
@@ -159,7 +165,7 @@ readable for compatibility and can be migrated with `dotmd lint --fix`.
 |---|---|---|
 | `plan` | Executable work | `in-session`, `active`, `planned`, `blocked`, `partial`, `paused`, `awaiting`, `queued-after`, `archived` |
 | `doc` | Specs, ADRs, audits, and reference material | `draft`, `active`, `review`, `reference`, `deprecated`, `archived` |
-| `prompt` | Saved future-session instructions | `pending`, `held`, `shelved`, `claimed`, `archived` |
+| `prompt` | Saved future-session instructions | `pending`, `archived` |
 
 Status definitions can be customized per type. Rich status objects co-locate
 display, staleness, validation, terminal, and archive behavior in one place.

package/bin/dotmd.mjs

@@ -103,7 +103,7 @@ const HELP = {
 
 Common commands:
   plans                 Live plans (excludes archived)
-  prompts               Prompt queue/admin (list, next, archive, new, hold)
+  prompts               Prompt queue/admin (list, next, archive, new)
   briefing              Full briefing with plan counts + next steps
   agent-context         Compact bounded JSON context for agents
   set <status> [file]   Transition status (start work, finish, archive — all via target status)
@@ -219,7 +219,7 @@ View & Query:
   plans                             Live plans (excludes archived; --include-archived for all)
   use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
   baton [<plan>|<slug>] <@<file>|->  Save a resume prompt; releases the plan + prints the commit when one is in-session
-  prompts [list|show|archive|new|hold] Prompt admin (list / peek / archive / save / hold). Use \`dotmd use\` to consume.
+  prompts [list|show|archive|new] Prompt admin (list / peek / archive / save). Use \`dotmd use\` to consume.
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
 
@@ -359,21 +359,21 @@ doc statuses
 ────────────────────────────────────────────────────────────────────
 prompt statuses
 
+  A prompt has two states and no third.
+
   pending        Ready for the next session to consume.
                  \`dotmd prompts use <file>\` prints body + archives atomically.
                  \`dotmd prompts next\` does the same for the oldest pending.
 
-  held           Saved under prompts/held/ and hidden from \`hud\` /
-                 \`briefing\` / \`prompts next\`.
-                 Still listed by \`dotmd prompts list\`.
-                 \`dotmd prompts unhold <file>\` → pending.
-
-  shelved        Legacy spelling for held prompts. \`dotmd prompts shelve\`
-                 now writes \`status: held\`.
-
-  claimed        Legacy intermediate state (atomic use → archived now).
+  archived       Consumed prompt; body preserved in the archive directory,
+                 which is the only directory a prompt ever moves into.
 
-  archived       Consumed prompt; body preserved in archive directory.
+  \`held\`, \`shelved\` and \`claimed\` were removed 2026-08-30, along with
+  \`prompts hold\` / \`unhold\` / \`shelve\` / \`unshelve\` and the
+  prompts/held/ bucket. A prompt directs work, so parking one instead of
+  archiving it left work state outside the plan that owns it, fighting with
+  that plan's own status. If a prompt should not be consumed, lift its content
+  into the plan and archive the prompt.
 
 ────────────────────────────────────────────────────────────────────
 Related commands:
@@ -504,9 +504,10 @@ another session's work.
 a unique bare slug / basename across the doc roots (\`set paused auth-revamp\`).
 Ambiguous slugs error with the candidate list instead of guessing.
 When the path is omitted, exactly one plan must be owned by this session.
-Claude Code session IDs are recognized automatically, as is OpenCode (via
-OPENCODE_PID — per OpenCode process, not per session). Other hosts must set
-RUNLIST_SESSION_ID; anonymous ownership mutations fail closed.
+Claude Code and Codex session IDs are recognized automatically (Codex exports
+CODEX_THREAD_ID to every tool shell), as is OpenCode (via OPENCODE_PID — per
+OpenCode process, not per session). Other hosts must set RUNLIST_SESSION_ID;
+anonymous ownership mutations fail closed.
 Pickup hooks use at-least-once delivery with a stable operationId; hook side
 effects must deduplicate that ID.
 
@@ -995,7 +996,7 @@ Other options:
 
 For plans, the default status vocabulary is: in-session, active, planned,
 blocked, partial, paused, awaiting, queued-after, archived.
-For prompts: pending (default), held, shelved, claimed, archived.
+For prompts: pending (default), archived.
 
 Use --dry-run (-n) to preview without creating the file.`,
 
@@ -1132,11 +1133,6 @@ Subcommands:
   show <file-or-slug>        Read-only peek: print the body WITHOUT consuming
                              (triage). \`peek\` is an alias.
   archive <file-or-slug>     Archive a prompt without printing its body
-  hold <file-or-slug>        Park a prompt (status → held) under prompts/held/:
-                             kept in list, hidden from hud/briefing pending
-                             surfaces, skipped by \`prompts next\`.
-  unhold <file-or-slug>      Move a held prompt back to pending.
-  shelve / unshelve          Legacy aliases for hold / unhold.
   new <slug> [body]          Create a new prompt (alias for
                              \`dotmd new prompt <slug> [body]\`)
 
@@ -1144,7 +1140,7 @@ Subcommands:
 slug matching a prompt basename, or a unique substring of a prompt
 path. Ambiguous substrings error with the candidate list.
 
-Default prompt statuses: pending, held, shelved, claimed, archived.
+Default prompt statuses: pending, archived.
 
 Examples:
   dotmd prompts                        # pending prompts (default)

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "dotmd-cli",
-  "version": "0.77.0",
+  "version": "0.77.2",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",
   "bin": {
     "runlist": "bin/runlist.mjs",
+    "rl": "bin/runlist.mjs",
     "dotmd": "bin/dotmd.mjs"
   },
   "exports": {

package/src/completions.mjs

@@ -39,7 +39,7 @@ ${Object.entries(COMMAND_WORDS).map(([command, words]) =>
     *) COMPREPLY=( $(compgen -W "${GLOBAL_FLAGS.join(' ')}" -- "$cur") ) ;;
   esac
 }
-complete -F _runlist runlist dotmd`;
+complete -F _runlist runlist rl dotmd`;
 }
 
 function zshCompletion() {
@@ -81,7 +81,7 @@ ${Object.entries(COMMAND_WORDS).map(([command, words]) =>
 
   _describe 'flag' global_flags
 }
-compdef _runlist runlist dotmd`;
+compdef _runlist runlist rl dotmd`;
 }
 
 export function runCompletions(argv) {

package/src/config.mjs

@@ -37,9 +37,17 @@ const DEFAULTS = {
       context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
       staleDays: { draft: 30, active: 14, review: 14 },
     },
+    // A prompt has two states and no third. It is pending — the next session
+    // should consume it — or it is archived, consumed, body kept under the
+    // archive directory. `held`, `shelved` and `claimed` were removed 2026-08-30:
+    // a prompt directs work, so parking one instead of archiving it leaves work
+    // state sitting outside the plan that owns it, where it fights with the
+    // plan's own status and neither one is the truth. If a prompt should not be
+    // consumed, its content belongs in the plan and the prompt should be
+    // archived. See lifecycle.filedStatuses — prompts file nowhere.
     prompt: {
-      statuses: ['pending', 'held', 'shelved', 'claimed', 'archived'],
-      context: { expanded: ['pending'], listed: ['held', 'shelved'], counted: ['claimed', 'archived'] },
+      statuses: ['pending', 'archived'],
+      context: { expanded: ['pending'], counted: ['archived'] },
       staleDays: { pending: 30 },
     },
   },
@@ -64,7 +72,11 @@ const DEFAULTS = {
     // F15: per-status filing buckets (status → dirName). Built-in held/paused
     // statuses file under the owning type folder; archive remains a separate
     // primitive untouched.
-    filedStatuses: { held: 'held', shelved: 'held', paused: 'held' },
+    // Plans only. A paused plan files under <plansDir>/held/ so the live plan
+    // list stays readable. Prompts were removed from this map 2026-08-30 along
+    // with their held/shelved statuses — `archived` is the only directory a
+    // prompt ever moves into.
+    filedStatuses: { paused: 'held' },
     // Types whose archive nests under their own type dir (<typeDir>/<archiveDir>,
     // e.g. docs/prompts/archived/) instead of the shared <root>/<archiveDir>.
     // Prompts are session-local churn — keeping their archive out of the shared

package/src/prompts.mjs

@@ -4,7 +4,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, resolveDocPath, resolveRefPath, isArchivedPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
-import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive, runStatus } from './lifecycle.mjs';
+import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim, yellow } from './color.mjs';
 import { authorizeManagedSource } from './managed-path.mjs';
@@ -21,11 +21,23 @@ import { LEGACY_STATE_DIR, STATE_DIR } from './naming.mjs';
 // `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.
-const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new', 'hold', 'unhold', 'shelve', 'unshelve']);
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'resume', 'show', 'peek', 'archive', 'new']);
+
+// Removed 2026-08-30 with the `held`/`shelved` statuses. Named rather than left
+// to fall through to the list filter below, which would silently answer a
+// removed command with an empty list — the caller needs to be told the state is
+// gone and what replaced it.
+const REMOVED_SUBCOMMANDS = new Set(['hold', 'unhold', 'shelve', 'unshelve']);
 
 export async function runPrompts(argv, config, opts = {}) {
   const sub = argv[0];
 
+  if (sub && REMOVED_SUBCOMMANDS.has(sub)) {
+    die(`\`dotmd prompts ${sub}\` was removed — a prompt is pending or archived, and nothing else.\n`
+      + 'A prompt directs work, so parking one instead of archiving it leaves work state outside the\n'
+      + 'plan that owns it. Lift its content into that plan, then `dotmd prompts archive <file>`.');
+  }
+
   if (!sub || !SUBCOMMANDS.has(sub)) {
     return runPromptsList(argv, config, opts);
   }
@@ -40,10 +52,6 @@ export async function runPrompts(argv, config, opts = {}) {
     case 'peek':     return runPromptsShow(rest, config);
     case 'archive':  return runPromptsArchive(rest, config, opts);
     case 'new':      return runPromptsNew(rest, config, opts);
-    case 'hold':     return runPromptsHold(rest, config, opts);
-    case 'unhold':   return runPromptsUnhold(rest, config, opts);
-    case 'shelve':   return runPromptsHold(rest, config, opts);
-    case 'unshelve': return runPromptsUnhold(rest, config, opts);
   }
 }
 
@@ -562,16 +570,3 @@ async function runPromptsNew(argv, config, opts = {}) {
   return runNew(['prompt', ...argv], config, opts);
 }
 
-async function runPromptsHold(argv, config, opts = {}) {
-  const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts hold <file-or-slug>');
-  const filePath = resolvePromptInput(input, config);
-  return runStatus([filePath, 'held'], config, opts);
-}
-
-async function runPromptsUnhold(argv, config, opts = {}) {
-  const input = argv.find(a => !a.startsWith('-'));
-  if (!input) die('Usage: dotmd prompts unhold <file-or-slug>');
-  const filePath = resolvePromptInput(input, config);
-  return runStatus([filePath, 'pending'], config, opts);
-}

package/src/util.mjs

@@ -26,6 +26,15 @@ const SESSION_ID_SOURCES = [
   { variable: 'DOTMD_SESSION_ID', prefix: null, scope: 'session', host: 'explicit override' },
   { variable: 'CLAUDE_CODE_SESSION_ID', prefix: null, scope: 'session', host: 'Claude Code' },
   { variable: 'CLAUDE_SESSION_ID', prefix: null, scope: 'session', host: 'Claude Code' },
+  // Verified against codex-cli 0.153.4 (2026-09-07): `codex exec` ran
+  // `env | grep ^CODEX` in a tool shell and printed both variables, each equal
+  // to the "session id:" line Codex prints in its own header, so they name one
+  // Codex thread (session), not the Codex process. THREAD_ID is what the exec
+  // path (core/src/exec.rs) sets first; SESSION_ID is its older twin. No
+  // CODEX_PID exists, so a Codex claim records no owning process and reads as
+  // 'unverifiable' — a takeover stays an explicit --force.
+  { variable: 'CODEX_THREAD_ID', prefix: null, scope: 'session', host: 'Codex' },
+  { variable: 'CODEX_SESSION_ID', prefix: null, scope: 'session', host: 'Codex' },
   { variable: 'OPENCODE_SESSION_ID', prefix: null, scope: 'session', host: 'OpenCode' },
   { variable: 'OPENCODE_SESSION', prefix: null, scope: 'session', host: 'OpenCode' },
   { variable: 'OPENCODE_PID', prefix: 'opencode', scope: 'process', host: 'OpenCode' },