runlist 0.0.0 → 0.94.2

package/package.json

@@ -1,10 +1,57 @@
 {
   "name": "runlist",
-  "version": "0.0.0",
-  "description": "Plan lifecycle, ranked work queues and session handoff for markdown corpora. Placeholder — the tool currently ships as dotmd-cli and is being renamed here.",
-  "keywords": ["markdown", "plans", "frontmatter", "cli", "documentation"],
-  "license": "MIT",
-  "author": "Robert Owens",
+  "version": "0.94.2",
+  "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
-  "files": ["README.md"]
+  "license": "MIT",
+  "bin": {
+    "runlist": "bin/runlist.mjs",
+    "rl": "bin/runlist.mjs",
+    "dotmd": "bin/dotmd.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "assets/",
+    "plugins/runlist-codex/",
+    "scripts/postinstall.mjs",
+    "runlist.config.example.mjs"
+  ],
+  "keywords": [
+    "markdown",
+    "frontmatter",
+    "cli",
+    "docs",
+    "plans",
+    "adr",
+    "rfc",
+    "document-management",
+    "yaml",
+    "graph",
+    "export",
+    "ai-summary",
+    "validation",
+    "lifecycle"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reowens/runlist.git"
+  },
+  "homepage": "https://github.com/reowens/runlist#readme",
+  "scripts": {
+    "check:public": "node scripts/check-public.mjs",
+    "prepack": "node scripts/check-public.mjs",
+    "test": "node --import ./test/setup-env.mjs --test --test-concurrency=4 test/*.test.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "preversion": "node scripts/release-preflight.mjs && npm test",
+    "version": "node scripts/prepare-version-commit.mjs",
+    "postversion": "bash scripts/postversion.sh",
+    "release:resume": "node scripts/recover-local-release.mjs && bash scripts/postversion.sh"
+  },
+  "engines": {
+    "node": ">=20"
+  }
 }

package/plugins/runlist-codex/.codex-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "runlist-codex",
+  "version": "0.94.2",
+  "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
+  "author": {
+    "name": "Reo Owens"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Runlist Codex",
+    "shortDescription": "Plan, handoff, and document workflow for Codex.",
+    "longDescription": "Adds a concise runlist skill, session primer, and prompt/status guard hooks for managed Markdown repositories.",
+    "developerName": "Reo Owens",
+    "category": "Productivity",
+    "capabilities": [],
+    "defaultPrompt": "Show my runlist plans and pending handoffs."
+  }
+}

package/plugins/runlist-codex/bin/runlist-hook

@@ -0,0 +1,86 @@
+#!/bin/sh
+# runlist Codex plugin hook wrapper.
+#
+# The plugin's hooks drive the whole workflow through the PATH `runlist` binary
+# (`runlist hud`, `runlist guard`), falling back to the legacy `runlist` alias. If a user enables the plugin but hasn't run
+# `npm i -g runlist`, the binary is missing, the hook errors `command not
+# found`, and the session is primed with *silent nothing* — no signal that the
+# whole workflow is one install away. runlist can't warn about its own absence
+# (it's the thing that's missing), so the check lives here, outside the binary.
+#
+# Usage: runlist-hook [--hint] <runlist-subcommand> [args...]
+#   --hint  emit a one-line install hint to stdout when no CLI is on PATH.
+#           Only SessionStart passes this, so the hint surfaces once per hook
+#           invocation (stdout becomes session context), never on a tool call.
+#
+# When the CLI is missing we always exit 0 with no further output: hooks must
+# stay non-blocking, and the PreToolUse guard in particular must never deny a
+# tool just because the optional CLI isn't installed.
+hint=0
+if [ "$1" = "--hint" ]; then
+  hint=1
+  shift
+fi
+
+if command -v runlist >/dev/null 2>&1; then
+  CLI=runlist
+elif command -v dotmd >/dev/null 2>&1; then
+  CLI=dotmd
+else
+  if [ "$hint" = "1" ]; then
+    echo "runlist plugin: neither \`runlist\` nor \`dotmd\` is on PATH, so its hooks are no-ops. Enable the workflow with: npm i -g runlist"
+  fi
+  exit 0
+fi
+
+# PreToolUse fast path: the guard fires on matched Bash, apply_patch, and MCP
+# read calls, and
+# a full Node boot (~100ms: CLI startup + config discovery) is pure overhead for
+# the vast majority of payloads no guard rule can possibly match. Every rule
+# needs a `.md` path AND either a prompts/ path (commit/cat/read-prompt) or the
+# word `status` (edit-status) somewhere in the payload — a cheap shell glob
+# decides that without leaving sh. Anything else gets the no-opinion reply
+# (`{}`) directly. False positives here just pay the old cost (Node runs and
+# returns {}); false negatives are impossible because the globs are strictly
+# weaker than the rules they gate.
+if [ "$1" = "guard" ]; then
+  payload=$(cat)
+  # Broad Git forms do not name a .md file in the payload; Node inspects the
+  # actual eligible/staged path set before deciding whether a live prompt is
+  # included. Always route those forms through the guard.
+  case "$payload" in
+    *git*add*|*git*stage*|*git*commit*)
+      printf '%s' "$payload" | "$CLI" "$@"
+      exit $?
+      ;;
+  esac
+  case "$payload" in
+    *.md*)
+      case "$payload" in
+        *prompts/*|*prompts\\*|*status*)
+          printf '%s' "$payload" | "$CLI" "$@"
+          exit $?
+          ;;
+      esac
+      ;;
+  esac
+  printf '{}\n'
+  exit 0
+fi
+
+# UserPromptSubmit fast path is retained for compatibility with the Claude
+# wrapper; Codex does not register that hook here. It would fire on every
+# message that asks for a handoff gets an answer. The glob is strictly weaker
+# than the Node-side match, so a skipped payload could never have matched.
+if [ "$1" = "hud" ] && [ "$2" = "--prompt-submit" ]; then
+  payload=$(cat)
+  case "$payload" in
+    *[Bb][Aa][Tt][Oo][Nn]*|*[Hh][Aa][Nn][Dd]*[Oo][Ff][Ff]*|*[Rr][Ee][Ss][Uu][Mm][Ee]*|*[Pp][Ii][Cc][Kk]*[Uu][Pp]*)
+      printf '%s' "$payload" | "$CLI" "$@"
+      exit 0
+      ;;
+  esac
+  exit 0
+fi
+
+exec "$CLI" "$@"

package/plugins/runlist-codex/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" --hint hud", "timeout": 5 }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch|mcp__.*__(read_file|read_text_file|read_media_file|read_multiple_files)",
+        "hooks": [{ "type": "command", "command": "sh \"${PLUGIN_ROOT}/bin/runlist-hook\" guard", "timeout": 5 }]
+      }
+    ]
+  }
+}

package/plugins/runlist-codex/skills/runlist/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: runlist
+description: Manage a repository's plans, docs, decisions, and saved prompts with the runlist CLI. Use when starting or closing plan work, checking the plan queue, or creating or consuming a handoff.
+---
+
+# Runlist workflow
+
+Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`. The CLI is `runlist` (from the `runlist` package; `dotmd` remains an alias). The session hook prints a short live orientation. `CODEX_THREAD_ID` is the session identity used for plan claims; do not replace it with a process ID.
+
+**Document model:** a hub organizes related plans and supporting docs. Older docs and filenames call hubs *runlists*; this is the same document, not another level below a hub. A hub can be a coordination map or hold ordered plans in its `runlist:` array. A roadmap is an optional hub collecting other hubs and rolling up progress, with direct plan children also supported. Hubs currently use `type: plan` with hub metadata. Stage describes when a plan should ship, while status describes progress; neither adds a document level. Existing `runlist` commands, fields and output labels remain unchanged. See the repository README's “Hubs, Ordered Plans, And Roadmaps” section for examples.
+
+**Optional filing policy:** with `export const filing = true` (or `{ categoryDepth: 3 }`), `check` warns on missing/multiple/uncategorized homes, while `coverage` lists direct/inherited homes and hub:line evidence. A home is a status-bearing table row whose first cell links the plan; mentions and order lists are references. A child without its own row can inherit a home through explicit `parent_plan:` ancestors. Categories come from headings or the containing hub's filing category. Scoping retains full evidence; incomplete scans suppress absence findings. Neither command assigns homes or repairs rows. Enable the policy or retire an older custom check only with repository authorization. Available in CLI 0.93.0.
+
+- Orient with `runlist plans`. Use `runlist agent-context` for structured state; `runlist briefing` is the comprehensive view and can be large.
+- Start plan work with `runlist use <plan-file>`. It claims the plan, marks it `in-session`, and prints the card.
+- Change status with `runlist set <status> <file> [--note "why"]`; this runs validation, lifecycle hooks, ref repairs, and index updates. Never hand-edit a `status:` field.
+- Close a shipped plan with `runlist archive <file>`; use `partial`, `active`, `awaiting`, or `blocked` when those match the actual state. Valid statuses are repository and type specific: `runlist statuses list --type plan`.
+- For a handoff, write a concrete resume draft, then run `runlist baton [<plan-or-slug>] @<draft-file>`. An owned plan is released in the same operation. If a handoff for that work is pending, inspect it with `runlist prompts show <file>`; keep it if current or pass `--replace` with the new draft. Replacement archives the old text and refreshes exactly one pending prompt.
+- Consume a saved prompt with `runlist use <prompt-file>` (or bare `runlist use` for the oldest). This archives and claims before printing the body. For read-only triage, use `runlist prompts show <file>` or `runlist prompts show --all`; never open pending prompts with a file reader or `cat`.
+- Pending prompts are session-local. Commit the tracked plan or source files named by baton, not `docs/prompts/*.md`.
+- Create a document with `runlist new <type> <name> @<draft-file>`. A draft starting with frontmatter can supply scaffold fields; `type` is fixed by the command.
+- Record a decision with `runlist new decision <plan> --question "…" @<record-file>`; configured registers may also require `--answers`.
+- If a lifecycle mutation reports an abandoned transaction, inspect `runlist doctor --transactions` before retrying. Use `--apply` only for cases the doctor identifies as recoverable.
+
+The `PreToolUse` hook warns on direct pending-prompt reads and denies hand-edited status transitions or Git operations that would include a live prompt. A repo can opt into blocking direct reads of existing pending prompts with `guard: { promptReads: 'deny' }`. Archived prompts and `runlist prompts show` remain readable. Codex requires explicit trust of a plugin's hooks before they run.

package/runlist.config.example.mjs

@@ -0,0 +1,370 @@
+// runlist.config.mjs — document management configuration
+// All exports are optional. Omitted values use built-in defaults.
+// Place this file at the root of your project.
+
+// ─── Static Config ───────────────────────────────────────────────────────────
+
+// Directory containing your markdown docs (relative to this config file)
+export const root = 'docs';
+
+// Optional owner-written product goal. Read its Markdown body beside a plan's
+// delivers: field with `runlist yardstick show <plan>` or on pickup cards.
+// Explicit mark/close/fold commands record owner choices; no fit is inferred.
+// Closing/folding uses the existing archive workflow. Leave unset to disable.
+// export const yardstick = 'docs/product-yardstick.md';
+
+// Optional plan-home policy. A home is a status-bearing hub table row whose
+// first cell links the plan; prose/commentary links do not count. A child can
+// inherit its parent's home through parent_plan:. Closed plans/hubs are excluded.
+// Categories come from ### headings, or from a category where the containing
+// hub is itself rowed. Use categoryDepth: 2..6 for another heading level.
+// check reports warnings; coverage lists homes and locations. Neither chooses
+// homes or rewrites documents. Leave unset/false to disable this policy.
+// export const filing = true;
+// export const filing = { categoryDepth: 3 };
+
+// GUI native flag/decision creation can use explicit persisted identity/settings.
+// Otherwise the first reviewed creation writes runlist.records.json with a
+// generated (or uniquely existing) repo ID, a managed records root and shared:false.
+// Replace the placeholder with a UUID v4. The root must be inside document roots.
+// shared:true requires a working Git checkout and a non-ignored destination.
+// If the JSON settings file also exists, these four values must agree with it.
+// export const records = { schema: 1, repositoryId: 'repo:<UUID-v4>', root: 'docs/records', shared: false };
+
+// Subdirectory for archived docs (used by `runlist archive` and `runlist status`)
+export const archiveDir = 'archived';
+
+// Directories to skip when scanning
+export const excludeDirs = ['evidence'];
+
+// Agent-host tool guard: direct reads of existing pending prompts warn by
+// default. Set promptReads to 'deny' to block those reads before execution;
+// `runlist prompts show` and archived prompt reads remain available.
+// export const guard = { promptReads: 'deny' };
+
+// Floor under the scan surface. `runlist check` fails when it scans fewer docs than
+// this, so a broken root or an over-eager exclude can't read as a clean estate —
+// zero errors and zero docs look identical otherwise. Off when unset. Set it well
+// below your real count (round down hard); raise it as the corpus grows.
+// Override for one run with `runlist check --min-docs <n>`; skipped for path-scoped
+// checks, which are deliberate subsets.
+// export const minDocs = 500;
+
+// ─── Code references (`runlist refs`) ────────────────────────────────────────
+//
+// Archive and rename repair every reference inside the doc roots. These four
+// keys extend that to source files that cite a document by its repo-relative
+// path in a comment, a docstring or a string literal. With no `codeRoots` the
+// scan never runs and nothing changes.
+//
+// `runlist refs <old> <new>` reports, `--fix` writes; `runlist refs repair`
+// does the same for every archived document still cited at its previous path.
+// Archive and rename print the count afterwards and take `--fix-refs`.
+//
+// Only the full repo-relative path matches, never a bare basename — a corpus
+// cites slugs as words, and matching one is how a rename corrupts an
+// unrelated line. Only the path segment is replaced, so a trailing `§` or `#`
+// anchor, a backtick or a quote is kept as written.
+
+// Repo-relative directories scanned for path-shaped citations. Empty = off.
+// export const codeRoots = ['packages', 'scripts', 'services'];
+
+// File kinds considered. An entry with no leading dot is an exact basename,
+// which is how a file with no extension opts in. Unset = the built-in list.
+// export const codeExtensions = ['.ts', '.tsx', '.mjs', '.swift', '.sql', '.py', '.sh', 'Dockerfile'];
+
+// Never scanned. Vendored trees and generated output, where a rewrite is
+// undone by the next codegen run and the citation belongs upstream.
+// Unset = node_modules, dist/build, and the usual generated-output shapes.
+// export const codeExcludes = ['**/node_modules/**', '**/*.generated.*', '**/__generated__/**'];
+
+// Files whose content is data keyed on document paths — a guard baseline
+// whose keys are plan paths, for instance. Reported, never written.
+// export const codeRefsUntouched = ['scripts/guards/plan-baseline.json'];
+
+// Document types — each type has its own status vocabulary and context layout.
+// Defaults: plan, doc, prompt. Override to customize statuses per type, or add new types.
+//
+// Statuses can be defined as an array (names only) or as an object (rich form).
+// The object form co-locates all behavioral properties with each status,
+// eliminating the need for separate lifecycle, staleDays, context, and taxonomy sections.
+
+// ─── Rich status definitions (recommended) ──────────────────────────────────
+// Each status is an object with optional properties:
+//   context:        'expanded' | 'listed' | 'counted' (default: 'counted')
+//   staleDays:      number | null — stale threshold (default: null = never stale)
+//   requiresModule: boolean — require `module` frontmatter (default: false)
+//   archive:        boolean — auto-move to archiveDir on transition (default: false)
+//   terminal:       boolean — closed state; excluded from active-work stats/coverage scope (default: false)
+//   skipStale:      boolean — exempt from stale checks (default: false)
+//   skipWarnings:   boolean — exempt from validation warnings (default: false)
+//   quiet:          boolean — sugar for `skipStale: true, skipWarnings: true`. Use for visible-but-quiet
+//                   statuses (e.g. `partial`) where you want no nagging but DO want them in scope.
+//                   Setting `skipStale: false` or `skipWarnings: false` explicitly overrides the sugar.
+//
+// `terminal` and `quiet` are orthogonal. Mark a status `terminal` only when it represents closure
+// (excluded from active-work scope). Use `quiet` for noise suppression without closure semantics.
+//
+// Contradiction check (since 0.36.2): runlist `warn()`s at config-load when a status combines
+// `skipStale: true` with a `staleDays` value (the number is silently ignored) or
+// `skipWarnings: true` with `requiresModule: true` (the module requirement can never fire).
+// The same check applies via the `quiet: true` sugar. Drop one of the conflicting fields to silence.
+//
+// Each plan stop-status maps to a distinct unstuck-action — the test for whether
+// the vocabulary earns its weight. blocked = monitor (external arrival on its own
+// schedule), awaiting = ask (chase the human/decision), queued-after = check the
+// predecessor, paused = re-evaluate, partial = spawn successor plans for the
+// deferred tail.
+//
+// export const types = {
+//   plan: {
+//     statuses: {
+//       'in-session':   { context: 'expanded', staleDays: 1, requiresModule: true },
+//       'active':       { context: 'expanded', staleDays: 14, requiresModule: true },
+//       'planned':      { context: 'listed', staleDays: 30, requiresModule: true },
+//       'blocked':      { context: 'listed', staleDays: 30, requiresModule: true },
+//       'partial':      { context: 'expanded', requiresModule: true, quiet: true },     // shipped + deferred tail; visible, no nagging
+//       'paused':       { context: 'listed', staleDays: 3, requiresModule: true },      // stopped mid-work, near-term review — loud (short stale threshold)
+//       'awaiting':     { context: 'listed', staleDays: 14, requiresModule: true },     // human input/decision wait — NOT quiet (pings get forgotten)
+//       'queued-after': { context: 'counted', requiresModule: true, quiet: true },      // sequenced behind another plan
+//       'archived':     { context: 'counted', archive: true, terminal: true, quiet: true },
+//     },
+//   },
+//   doc: {
+//     statuses: {
+//       'draft':      { context: 'listed', staleDays: 30 },
+//       'active':     { context: 'expanded', staleDays: 14 },
+//       'review':     { context: 'listed', staleDays: 14 },
+//       'reference':  { context: 'counted', skipStale: true },
+//       'deprecated': { context: 'counted', terminal: true, skipStale: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, quiet: true },
+//     },
+//   },
+//   prompt: {
+//     // Saved prompts that seed future Claude sessions. `runlist hud` surfaces
+//     // pending prompts on session start; `runlist prompts next` claims the oldest.
+//     statuses: {
+//       'pending':  { context: 'expanded', staleDays: 30 },
+//       'held':     { context: 'counted', quiet: true },   // saved but not next: hidden from hud/briefing, skipped by no-arg `use`
+//       'shelved':  { context: 'counted', quiet: true },   // legacy alias for held
+//       'claimed':  { context: 'counted', quiet: true },
+//       'archived': { context: 'counted', archive: true, terminal: true, quiet: true },
+//     },
+//   },
+// };
+
+// ─── Array form (also supported) ────────────────────────────────────────────
+// When using array form, define behavior in separate statuses/lifecycle/taxonomy sections.
+// export const types = {
+//   plan: {
+//     statuses: ['in-session', 'active', 'planned', 'blocked', 'partial', 'paused', 'awaiting', 'queued-after', 'archived'],
+//     context: {
+//       expanded: ['in-session', 'active', 'partial'],
+//       listed: ['planned', 'blocked', 'paused', 'awaiting'],
+//       counted: ['queued-after', 'archived'],
+//     },
+//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30, awaiting: 14 },
+//   },
+// };
+
+// Status workflow — fallback for docs without a type field. Order determines display grouping.
+// When using rich status definitions, statuses.order and staleDays are derived automatically.
+export const statuses = {
+  order: ['active', 'ready', 'planned', 'scoping', 'blocked', 'reference', 'archived'],
+  // Additional statuses valid only in specific roots (merged with order)
+  // Useful when different doc areas track different things (e.g. plans vs module docs)
+  // rootStatuses: {
+  //   'docs/modules': ['implemented', 'partial', 'draft', 'deprecated'],
+  //   'docs/core':    ['implemented', 'partial'],
+  // },
+  // Days after which a doc is considered stale (null = never stale)
+  staleDays: {
+    active: 14,
+    ready: 14,
+    planned: 30,
+    blocked: 30,
+    scoping: 30,
+  },
+};
+
+// Lifecycle behavior — which statuses trigger special handling.
+//
+// IMPORTANT: only enable this block if you're using ARRAY-form types (above) or
+// no `types` definition. With rich-form types, the runtime derives these from
+// per-status `terminal` / `archive` / `skipStale` / `skipWarnings` / `quiet`
+// flags. An explicit `lifecycle` export sitting alongside rich-form types will
+// SILENTLY OVERRIDE the per-status flags — `runlist statuses` will warn you
+// before writing into a config in that state.
+//
+// export const lifecycle = {
+//   archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
+//   skipStaleFor: ['archived'],         // skip staleness checks
+//   skipWarningsFor: ['archived'],      // skip validation warnings (summary, etc.)
+//   terminalStatuses: ['archived', 'deprecated', 'reference'],  // skip current_state/next_step warnings, exclude from stats scope
+//   archiveNestedTypes: ['prompt'],     // types that archive under <typeDir>/<archiveDir>
+//                                       // (e.g. docs/prompts/archived/) instead of the
+//                                       // shared <root>/<archiveDir>; set [] to disable
+// };
+
+// Taxonomy validation — set fields to null to skip validation.
+// moduleRequiredFor is derived from requiresModule when using rich status definitions.
+export const taxonomy = {
+  // Ordered stages are repository-defined; status still tracks work progress.
+  // Existing string lists remain supported: milestones: ['Launch', 'Later'].
+  // Omit milestones (or use null) to allow any ships value. Missing ships is Unset.
+  milestones: [
+    { word: 'Launch', meaning: 'Work intended for the next release.' },
+    { word: 'Later', meaning: 'Work deliberately deferred beyond that release.' },
+  ],
+  surfaces: ['web', 'ios', 'android', 'mobile', 'full-stack', 'frontend', 'backend', 'api', 'docs', 'ops', 'platform', 'infra', 'design'],
+  moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
+};
+
+// Index file generation — remove this section to disable
+export const index = {
+  path: 'docs/docs.md',
+  startMarker: '<!-- GENERATED:runlist:start -->',
+  endMarker: '<!-- GENERATED:runlist:end -->',
+  snapshot: 'status', // default; use 'state' to include live current_state text
+  archivedLimit: 8,
+};
+
+// Context briefing layout (`runlist context`)
+export const context = {
+  expanded: ['active'],
+  listed: ['ready', 'planned'],
+  counted: ['blocked', 'scoping', 'reference', 'archived'],
+  recentDays: 3,
+  recentStatuses: ['active', 'ready', 'planned'],
+  recentLimit: 10,
+  truncateNextStep: 80,
+  // Cap on slugs shown in the "Stale: …" tail before "…and N more (run `runlist stale`)"
+  // takes over (since 0.36.2). Raise on wide terminals; lower for tighter briefings.
+  staleTailLimit: 8,
+};
+
+// Display settings
+export const display = {
+  lineWidth: 0,         // 0 = auto-detect terminal width
+  truncateTitle: 30,
+  truncateNextStep: 80,
+};
+
+// Reference fields for bidirectional link checking
+export const referenceFields = {
+  bidirectional: ['related_docs'],    // warn if A→B but B↛A
+  unidirectional: ['supports'],       // one-way, no symmetry check
+};
+
+// Query presets — expand to filter args when used as commands
+// Built-in: plans, stale, actionable. Add your own here:
+export const presets = {
+  // plans: ['--type', 'plan', '--sort', 'status', '--all'],           // built-in
+  // stale: ['--status', '...', '--stale', '--sort', 'updated', '--all'], // built-in
+  // actionable: ['--status', 'active,ready', '--has-next-step', ...],   // built-in
+  mine: ['--owner', 'robert', '--status', 'active', '--all'],
+};
+
+// ─── Templates ───────────────────────────────────────────────────────────────
+// Define new types or override builtins. `runlist new <type> <name>` looks here first.
+//
+// Properties:
+//   description:    string — shown in `runlist new --list-types`
+//   defaultStatus:  string — initial status if `--status` not passed
+//   acceptsBody:    boolean — allow body input (inline / --body / @file / piped stdin).
+//                   REQUIRED if you want `cat draft.md | runlist new <type> <slug>` (or @path,
+//                   --body, heredoc) to work. Your `body` fn must also interpolate the input,
+//                   e.g. `${ctx?.bodyInput?.trim() ?? ''}`. See the body-acceptance guard below.
+//   requiresBody:   boolean — error if no body input (implies acceptsBody; see `prompt` builtin)
+//   targetRoot:     string — name (basename or suffix) of the root this type lives in.
+//                   In flat-array `root` configs (e.g. ['docs/plans', 'docs/prompts']),
+//                   the new doc lands in the matching root. Falls back to `config.docsRoot`
+//                   if no root matches. The `--root` CLI flag still overrides.
+//   dir:            string — subdirectory under `docsRoot` to use when `targetRoot` doesn't
+//                   match anything. Builtin `plan` and `prompt` set both for portability:
+//                   under `docsRoot='docs'`, `dir` puts files in `docs/plans/` and `docs/prompts/`;
+//                   under flat-array roots, `targetRoot` routes directly to the type-specific root.
+//   frontmatter:    (status, isoTime, ctx) => string
+//   body:           (title, ctx) => string — slot user-supplied body via `ctx.bodyInput`
+//
+// Body-acceptance guard (the #1 custom-template gotcha):
+//   When you override a builtin and supply your OWN `body` fn that NEVER references
+//   `bodyInput`, runlist assumes the fn would silently discard piped input — so it strips
+//   the inherited `acceptsBody`/`requiresBody` and rejects body input with a fail-fast
+//   error. Two ways to keep piped/@path/heredoc bodies working in a custom template:
+//     1. interpolate `${ctx?.bodyInput?.trim() ?? ''}` somewhere in your `body` fn, OR
+//     2. set `acceptsBody: true` explicitly (do BOTH if you want the input to actually land).
+//   A `body: (t) =>` that ignores `ctx` is the classic trap — it scaffolds fine but
+//   `runlist new <type> <slug> < draft.md` errors until you wire in `bodyInput`.
+//
+// Custom type example — adds a `spike` type that lives in the `spikes` root (or
+// under `docs/spikes/` in single-root layouts):
+// export const templates = {
+//   spike: {
+//     description: 'Timeboxed investigation',
+//     defaultStatus: 'active',
+//     targetRoot: 'spikes',  // for flat-array root configs
+//     dir: 'spikes',          // for single-root configs
+//     frontmatter: (s, d) => `type: spike\nstatus: ${s}\ncreated: ${d}\ntimebox: 2d`,
+//     body: (t) => `\n# ${t}\n\n## Hypothesis\n\n\n\n## Findings\n\n`,
+//   },
+//
+//   // Override a builtin (e.g. project-specific prompt frontmatter shape).
+//   // Overrides shallow-merge OVER the builtin: any property you omit is inherited
+//   // (`targetRoot`, `dir`, `defaultStatus`, `requiresBody`, …), and anything you declare
+//   // wins. EXCEPTION: if you supply your own `body` fn that doesn't reference `bodyInput`,
+//   // the inherited `acceptsBody`/`requiresBody` are dropped (see the guard above) — so
+//   // re-declare `acceptsBody: true` and wire in `ctx.bodyInput` if you want piped bodies.
+//   // prompt: {
+//   //   description: 'Project resume prompt',
+//   //   defaultStatus: 'pending',
+//   //   requiresBody: true,
+//   //   targetRoot: 'prompts',
+//   //   dir: 'prompts',
+//   //   frontmatter: (s, d, ctx) => `type: prompt\nstatus: ${s}\nproject_field: yes`,
+//   //   body: (t, ctx) => `\n${ctx?.bodyInput ?? ''}\n`,
+//   // },
+// };
+
+// ─── Function Hooks ──────────────────────────────────────────────────────────
+// Hooks are optional. Each receives a default implementation it can wrap or replace.
+
+// Custom validation — called after built-in validation for each doc.
+// Return { errors: [], warnings: [] } to add issues.
+// export function validate(doc, ctx) {
+//   const warnings = [];
+//   if (doc.status === 'active' && !doc.owner) {
+//     warnings.push({ path: doc.path, level: 'warning', message: 'Active docs should have an owner.' });
+//   }
+//   return { errors: [], warnings };
+// }
+
+// Render hooks — override any renderer by wrapping the default.
+// export function renderContext(index, defaultRenderer) { return defaultRenderer(index); }
+// export function renderCompactList(index, defaultRenderer) { return defaultRenderer(index); }
+// export function renderCheck(index, defaultRenderer) { return defaultRenderer(index); }
+// export function renderStats(stats, defaultRenderer) { return defaultRenderer(stats); }
+// export function renderGraph(graph, defaultRenderer) { return defaultRenderer(graph); }
+// export function formatSnapshot(doc, defaultFormatter) { return defaultFormatter(doc); }
+
+// Post-parse doc transformation — add computed fields.
+// export function transformDoc(doc) {
+//   return doc;
+// }
+
+// Lifecycle callbacks — fire after the operation completes.
+// export function onArchive(doc, { oldPath, newPath }) {}
+// export function onStatusChange(doc, { oldStatus, newStatus, path }) {}
+// export function onTouch(doc, { path, date }) {}
+// export function onNew({ path, status, title, template }) {}
+// export function onRename({ oldPath, newPath, referencesUpdated }) {}
+// export function onLint({ path, fixes }) {}
+// Pickup hooks are delivered at least once. A retry reuses operationId, so any
+// external side effect must deduplicate by that stable ID. Delivery uses a
+// persisted process-identity lease; live/unverifiable owners are not reclaimed
+// by age, and an expired lease retries only when its owner is demonstrably dead.
+// export function onPickup({ path, oldStatus, newStatus, operationId }) {}
+
+// AI hooks — override summarization (replaces the local model server; see `runlist model`).
+// export function summarizeDoc(body, meta) { return 'Custom summary'; }
+// export function summarizeDiff(diffOutput, filePath) { return 'Custom diff summary'; }

package/scripts/postinstall.mjs

@@ -0,0 +1,56 @@
+// Runs after `npm install runlist`. Because the Claude Code plugin is a
+// separate artifact from this CLI, upgrading the CLI alone leaves the plugin
+// (hooks/skill/commands) on its old version. This script bridges that — but
+// conservatively:
+//
+//   - Only on GLOBAL installs (`npm i -g`). A project devDep / CI / Docker
+//     install must never touch a user's Claude Code state.
+//   - Default: just print a one-line nudge. A CLI install silently mutating the
+//     agent's plugin cache is surprising; opt in with RUNLIST_AUTO_PLUGIN_UPDATE=1
+//     to actually run the refresh.
+//   - NEVER fail the install: everything is swallowed and we always exit 0. A
+//     nonzero postinstall would break `npm i -g runlist`.
+//   - Skipped entirely under `npm install --ignore-scripts`.
+import { spawnSync } from 'node:child_process';
+
+try {
+  // Lifecycle env: npm sets this to "true" for global installs.
+  if (process.env.npm_config_global !== 'true') process.exit(0);
+
+  const hasClaude = (() => {
+    try {
+      const cmd = process.platform === 'win32' ? 'where' : 'which';
+      return spawnSync(cmd, ['claude'], { encoding: 'utf8' }).status === 0;
+    } catch { return false; }
+  })();
+
+  // OpenCode's integration is a file runlist writes, and nothing else would ever
+  // mention it — an OpenCode user who installs only the CLI gets no primer and
+  // a process-scoped session identity, silently. One line, never an install.
+  const hasOpencode = (() => {
+    try {
+      const cmd = process.platform === 'win32' ? 'where' : 'which';
+      return spawnSync(cmd, ['opencode'], { encoding: 'utf8' }).status === 0;
+    } catch { return false; }
+  })();
+
+  if ((process.env.RUNLIST_AUTO_PLUGIN_UPDATE ?? process.env.DOTMD_AUTO_PLUGIN_UPDATE) === '1' && hasClaude) {
+    const updated = spawnSync('claude', ['plugin', 'update', 'runlist@runlist'], { stdio: 'ignore', timeout: 60000 });
+    process.stdout.write(updated.status === 0
+      ? 'runlist: refreshed the Claude Code plugin — restart your session (or /reload-plugins) to apply.\n'
+      : 'runlist: install the renamed Claude Code plugin with `runlist install claude`.\n');
+  } else {
+    // The CLI just installed fresh, so only the plugin can be stale — point at
+    // the targeted refresh rather than the full `runlist update` (CLI + plugin).
+    const nudge = hasClaude
+      ? 'runlist CLI installed. Using the Claude Code plugin? Run `runlist update --plugin-only` to refresh it, then restart.'
+      : 'runlist CLI installed.';
+    process.stdout.write(`${nudge}\n`);
+  }
+  if (hasOpencode) {
+    process.stdout.write('runlist: OpenCode detected — run `runlist install opencode` for per-session plan ownership and a session-start briefing.\n');
+  }
+} catch {
+  // Best effort only — never break the install.
+}
+process.exit(0);