dotmd-cli 0.77.3 → 0.79.0

package/README.md

@@ -1,8 +1,8 @@
-# dotmd
+# runlist
 
 CLI for managing Markdown documents with YAML frontmatter.
 
-dotmd indexes, queries, validates, graphs, exports, and lifecycle-manages plans,
+runlist (formerly dotmd) indexes, queries, validates, graphs, exports, and lifecycle-manages plans,
 ADRs, RFCs, design docs, and other structured Markdown. It is built for
 AI-assisted development workflows where documents need to remain current and
 safe to mutate.
@@ -22,7 +22,9 @@ 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.
+same CLI. The package is still published as `dotmd-cli`, and the Claude Code
+plugin is still `dotmd@dotmd`; those names change in a later release. Legacy
+`dotmd.config.*` files, `DOTMD_*` variables and `.dotmd/` state keep working.
 
 Maintainer release automation is POSIX-only because it uses Bash and POSIX
 command-line tools. The published Node.js CLI remains cross-platform.
@@ -33,19 +35,19 @@ The CLI alone gives an agent no orientation and no session identity. Install the
 integration for whichever host you run:
 
 ```bash
-dotmd install             # what's installed for each host
-dotmd install claude      # Claude Code plugin (marketplace + plugin)
-dotmd install opencode    # OpenCode plugin (one auto-discovered file)
-dotmd doctor --session    # what identity dotmd sees here, and from where
+runlist install             # what's installed for each host
+runlist install claude      # Claude Code plugin (marketplace + plugin)
+runlist install opencode    # OpenCode plugin (one auto-discovered file)
+runlist doctor --session    # what identity runlist sees here, and from where
 ```
 
-Both are one-time and global; `dotmd update` keeps them in step with the CLI.
+Both are one-time and global; `runlist 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.
+shell, and runlist reads it as a per-session identity automatically.
 
 ### Claude Code Plugin
 
-`dotmd install claude` runs the two steps below for you. From inside a session:
+`runlist install claude` runs the two steps below for you. From inside a session:
 
 ```text
 /plugin marketplace add reowens/dotmd
@@ -58,32 +60,33 @@ guard, the canonical workflow skill, and `/plans`, `/docs`, `/prompts`, and
 
 ### OpenCode Plugin
 
-`dotmd install opencode` writes one plugin file into OpenCode's global config
+`runlist install opencode` writes one plugin file into OpenCode's global config
 directory, where OpenCode auto-discovers it — no `opencode.json` edit. It
 supplies the two things the CLI cannot get on its own:
 
 - **Per-session plan ownership.** OpenCode exports no session id to a tool
-  shell. Without the plugin, dotmd falls back to `OPENCODE_PID`, which names the
+  shell. Without the plugin, runlist falls back to `OPENCODE_PID`, which names the
   OpenCode *process* — so every session in one OpenCode instance shares an
   identity and can release the others' in-session plans.
 - **A session-start briefing**, the equivalent of Claude Code's SessionStart
   hook. OpenCode's Claude Code compatibility covers skills and the system
-  prompt, not hooks, so nothing else runs `dotmd hud`.
+  prompt, not hooks, so nothing else runs `runlist hud`.
 
-Restart OpenCode after installing. The file is version-stamped; a `dotmd.js`
-without that stamp is treated as hand-authored and is never overwritten.
+Restart OpenCode after installing. The file is version-stamped (`runlist-generated:`, or
+`dotmd-generated:` from older releases); a `dotmd.js` without either stamp is
+treated as hand-authored and is never overwritten.
 
-The plugin requires a global CLI install because its hooks resolve `dotmd` from
+The plugin requires a global CLI install because its hooks resolve `runlist` (or `dotmd`) from
 `PATH`. A project devDependency is useful for npm scripts but does not put the
 CLI on the hook's `PATH`.
 
 Keep the CLI and plugin aligned with:
 
 ```bash
-dotmd update
-dotmd update --check
-dotmd update --cli-only
-dotmd update --plugin-only
+runlist update
+runlist update --check
+runlist update --cli-only
+runlist update --plugin-only
 ```
 
 Restart Claude Code, or run `/reload-plugins`, after a plugin update.
@@ -91,29 +94,29 @@ Restart Claude Code, or run `/reload-plugins`, after a plugin update.
 ## Quick Start
 
 ```bash
-dotmd init                    # create config, docs/, and the generated index
-dotmd new plan auth-refresh  # scaffold a typed document
-dotmd briefing               # compact active-work orientation
-dotmd plans                  # live plan dashboard
-dotmd check                  # validate schema, references, and lifecycle shape
-dotmd doctor                 # preview repairs; add --apply to write
+runlist init                    # create config, docs/, and the generated index
+runlist new plan auth-refresh  # scaffold a typed document
+runlist briefing               # compact active-work orientation
+runlist plans                  # live plan dashboard
+runlist check                  # validate schema, references, and lifecycle shape
+runlist doctor                 # preview repairs; add --apply to write
 ```
 
-`dotmd briefing` is the compact orientation view. `dotmd context` is the fuller
-human/LLM briefing, while `dotmd agent-context` emits bounded structured JSON for
+`runlist briefing` is the compact orientation view. `runlist context` is the fuller
+human/LLM briefing, while `runlist agent-context` emits bounded structured JSON for
 agent integrations.
 
 ## Core Workflow
 
 ```bash
-dotmd briefing
-dotmd use docs/plans/auth-refresh.md
-dotmd set awaiting docs/plans/auth-refresh.md --note "Need API owner decision"
-dotmd set active docs/plans/auth-refresh.md --note "Decision received"
-dotmd archive docs/plans/auth-refresh.md --note "Shipped and verified"
+runlist briefing
+runlist use docs/plans/auth-refresh.md
+runlist set awaiting docs/plans/auth-refresh.md --note "Need API owner decision"
+runlist set active docs/plans/auth-refresh.md --note "Decision received"
+runlist archive docs/plans/auth-refresh.md --note "Shipped and verified"
 ```
 
-Use `dotmd set <status> [<file>]` for lifecycle changes rather than editing a
+Use `runlist set <status> [<file>]` for lifecycle changes rather than editing a
 `status:` line. It validates the status for the document type, updates history,
 runs lifecycle hooks, repairs references after moves, and synchronizes the
 index.
@@ -122,11 +125,18 @@ For unfinished session work, save the handoff and release the owned plan in one
 operation:
 
 ```bash
-dotmd baton @/tmp/resume.md
+runlist baton @/tmp/resume.md
 ```
 
-Saved prompts are local session state. Consume them with `dotmd use`; inspect
-without consuming via `dotmd prompts show`.
+Baton refuses when a handoff for the same work is already pending, so one piece
+of work never has two resume prompts.
+
+Saved prompts are local session state. Consume them with `runlist use`; inspect
+without consuming via `runlist prompts show`. Consuming a baton prompt also claims
+its plan; `runlist use --no-claim` reads and archives it without starting the plan.
+
+New plans are created `planned`; `runlist use` starts one, and
+`runlist new plan <name> --status <status>` sets a different starting status.
 
 ## Document Format
 
@@ -153,11 +163,11 @@ related_docs:
 
 `status` is the only universally required field. A `type` enables type-specific
 statuses, validation, templates, and briefing behavior. Explicit frontmatter
-wins, but dotmd can also derive titles, summaries, state, next steps, checklist
+wins, but runlist can also derive titles, summaries, state, next steps, checklist
 progress, and Markdown links from the body.
 
 Use plural `modules:` and `surfaces:` arrays. The old singular keys remain
-readable for compatibility and can be migrated with `dotmd lint --fix`.
+readable for compatibility and can be migrated with `runlist lint --fix`.
 
 ### Built-In Types
 
@@ -176,19 +186,19 @@ A sprint runlist is an ordered `runlist:` array on a hub plan. Scaffold a hub
 and children together:
 
 ```bash
-dotmd new plan auth-revamp --runlist extract,rewrite,cleanup
-dotmd runlist auth-revamp
-dotmd runlist next auth-revamp
+runlist new plan auth-revamp --runlist extract,rewrite,cleanup
+runlist runlist auth-revamp
+runlist runlist next auth-revamp
 ```
 
 Mutate the structure through the CLI so the array, child `parent_plan` refs, and
 body order list remain synchronized:
 
 ```bash
-dotmd runlist add auth-revamp docs/plans/existing-plan.md
-dotmd runlist add auth-revamp follow-up
-dotmd runlist reorder auth-revamp follow-up --before cleanup
-dotmd runlist remove auth-revamp extract --clear-parent
+runlist runlist add auth-revamp docs/plans/existing-plan.md
+runlist runlist add auth-revamp follow-up
+runlist runlist reorder auth-revamp follow-up --before cleanup
+runlist runlist remove auth-revamp extract --clear-parent
 ```
 
 Archived children count as complete. Parked children (`blocked`, `partial`,
@@ -198,16 +208,16 @@ pickup but do not count as done.
 For a larger prose-first domain map, create a coordination runlist:
 
 ```bash
-dotmd new plan platform-work --coordination
-dotmd runlists
+runlist new plan platform-work --coordination
+runlist runlists
 ```
 
 For progress across several runlists, create a roadmap:
 
 ```bash
-dotmd new plan platform-roadmap --roadmap
-dotmd roadmap platform-roadmap
-dotmd roadmap platform-roadmap next
+runlist new plan platform-roadmap --roadmap
+runlist roadmap platform-roadmap
+runlist roadmap platform-roadmap next
 ```
 
 Roadmaps roll up progress recursively and choose the first startable plan across
@@ -229,17 +239,17 @@ counts so dashboards do not double-count their children.
 The CLI is the source of truth for command syntax and options:
 
 ```bash
-dotmd --help
-dotmd help all
-dotmd help statuses
-dotmd <command> --help
+runlist --help
+runlist help all
+runlist help statuses
+runlist <command> --help
 ```
 
 Shell completion is generated from the same command registry:
 
 ```bash
-eval "$(dotmd completions bash)"
-eval "$(dotmd completions zsh)"
+eval "$(runlist completions bash)"
+eval "$(runlist completions zsh)"
 ```
 
 This README intentionally documents onboarding and concepts instead of
@@ -247,7 +257,7 @@ duplicating the complete command catalog.
 
 ## Configuration
 
-Run `dotmd init` to create `dotmd.config.mjs`. A minimal typed configuration:
+Run `runlist init` to create `runlist.config.mjs` (a legacy `dotmd.config.mjs` is still read). A minimal typed configuration:
 
 ```js
 export const root = 'docs';
@@ -273,12 +283,12 @@ export const types = {
 
 Configuration supports multiple roots, custom types and templates, taxonomy,
 reference fields, presets, rendering, lifecycle hooks, validation hooks, and
-AI summarization hooks. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs)
+AI summarization hooks. See [`runlist.config.example.mjs`](runlist.config.example.mjs)
 for the complete annotated reference.
 
 ## Hooks
 
-Functions exported from `dotmd.config.mjs` are detected as hooks. They can add
+Functions exported from `runlist.config.mjs` are detected as hooks. They can add
 validation, customize rendering and summaries, or react to lifecycle events.
 Hooks receive the resolved config and command context; mutation hooks participate
 in the command's dry-run and failure contracts.

package/assets/opencode/plugin.js

@@ -1,4 +1,4 @@
-// dotmd's OpenCode integration. Installed by `dotmd install opencode`, which
+// runlist's OpenCode integration. Installed by `runlist install opencode`, which
 // copies this file (with a version banner prepended) to the OpenCode plugin
 // directory, where OpenCode auto-discovers it — it globs
 // `{plugin,plugins}/*.{ts,js}` under `.opencode/` and the global config dir, so
@@ -13,7 +13,7 @@
 //
 //  2. NO HOOK MAY THROW. OpenCode awaits hook callbacks inside the request it
 //     is serving; a rejected promise fails the user's chat turn. Every hook
-//     body is wrapped, and a failure degrades to "dotmd does nothing here"
+//     body is wrapped, and a failure degrades to "runlist does nothing here"
 //     rather than to a broken session.
 //
 // Runs under Bun inside the OpenCode process. Node builtins only, no deps.
@@ -32,7 +32,9 @@ function cliExecutables() {
   return process.platform === 'win32' ? ['runlist.cmd', 'dotmd.cmd'] : ['runlist', 'dotmd'];
 }
 
-function runHud(directory) {
+// Runs the CLI and resolves its trimmed stdout, or '' on any failure. `input`,
+// when given, is written to the child's stdin.
+function runCli(directory, args, input = null) {
   return new Promise(resolve => {
     let settled = false;
     const done = value => { if (!settled) { settled = true; resolve(value); } };
@@ -40,7 +42,7 @@ function runHud(directory) {
     const attempt = index => {
       if (index >= candidates.length) { done(''); return; }
       try {
-        execFile(candidates[index], ['hud'], {
+        const child = execFile(candidates[index], args, {
           cwd: directory,
           timeout: PRIMER_TIMEOUT_MS,
           windowsHide: true,
@@ -49,12 +51,33 @@ function runHud(directory) {
           if (error?.code === 'ENOENT') attempt(index + 1);
           else done(error ? '' : (stdout ?? '').trim());
         });
+        child.stdin?.on('error', () => {});
+        if (input !== null) child.stdin?.end(input);
+        else child.stdin?.end();
       } catch { attempt(index + 1); }
     };
     attempt(0);
   });
 }
 
+// OpenCode runs no Claude Code hooks, so `runlist guard` never sees its tool
+// calls, and sessions opened pending prompts with the read tool, which prints a
+// prompt without archiving it. The guard's answer for a prompt read is a
+// warning, not a block, so it is applied after the call: the teaching text is
+// appended to what the agent sees. Only calls that name a prompt file reach
+// the CLI; everything else costs a regex.
+const PROMPT_FILE = /(^|[\\/])prompts[\\/]\S*\.md\b/;
+
+function guardPayload(tool, args) {
+  if (tool === 'read' && typeof args?.filePath === 'string' && PROMPT_FILE.test(args.filePath)) {
+    return { tool_name: 'Read', tool_input: { file_path: args.filePath } };
+  }
+  if (tool === 'bash' && typeof args?.command === 'string' && PROMPT_FILE.test(args.command)) {
+    return { tool_name: 'Bash', tool_input: { command: args.command } };
+  }
+  return null;
+}
+
 export default async function dotmdOpencodePlugin({ directory }) {
   // Keyed by session so a subagent session primes independently, the way
   // SubagentStart does under Claude Code.
@@ -68,14 +91,14 @@ export default async function dotmdOpencodePlugin({ directory }) {
     // only the first request — and a never-refreshed one would keep announcing
     // a pending prompt this session already consumed.
     if (cached && Date.now() - cached.at < PRIMER_TTL_MS) return cached.text;
-    const text = await runHud(directory);
+    const text = await runCli(directory, ['hud']);
     primers.set(key, { text, at: Date.now() });
     return text;
   }
 
   return {
     // Ownership identity. OpenCode sets no session-id variable of its own, and
-    // `OPENCODE_PID` — what dotmd falls back to without this plugin — names the
+    // `OPENCODE_PID` — what runlist falls back to without this plugin — names the
     // OpenCode *process*, so every session in one TUI shares it and can release
     // the others' plans. This is the only place the real session id is
     // available to a tool shell.
@@ -83,18 +106,32 @@ export default async function dotmdOpencodePlugin({ directory }) {
       try {
         if (input?.sessionID) {
           output.env.RUNLIST_SESSION_ID = `opencode:${input.sessionID}`;
+          // Legacy name, kept for an older CLI (before 0.77.0) still on PATH.
           output.env.DOTMD_SESSION_ID = `opencode:${input.sessionID}`;
         }
         // The OpenCode server process hosts the session and outlives every tool
         // shell, so it is the process whose liveness answers "is this claim's
-        // owner still there?" — `dotmd doctor --claims` probes exactly this.
+        // owner still there?" — `runlist doctor --claims` probes exactly this.
         output.env.RUNLIST_SESSION_PID = String(process.pid);
         output.env.DOTMD_SESSION_PID = String(process.pid);
       } catch { /* never break a shell over this */ }
     },
 
+    // The guard's warnings, appended after the call ran. A `deny` from the
+    // guard is ignored here: the call has already happened, so there is
+    // nothing left to refuse.
+    'tool.execute.after': async (input, output) => {
+      try {
+        const payload = guardPayload(input?.tool, input?.args);
+        if (!payload || typeof output?.output !== 'string') return;
+        const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
+        const note = raw ? JSON.parse(raw)?.hookSpecificOutput?.additionalContext : null;
+        if (typeof note === 'string' && note) output.output += `\n\n${note}`;
+      } catch { /* a guard failure never touches the tool result */ }
+    },
+
     // Session priming — the equivalent of the SessionStart hook that runs
-    // `dotmd hud` under Claude Code. Silent outside a dotmd repo (hud prints
+    // `runlist hud` under Claude Code. Silent outside a runlist repo (hud prints
     // nothing and exits 0), so this is inert in unrelated projects.
     'experimental.chat.system.transform': async (input, output) => {
       try {