runlist 0.97.0 → 0.98.1

package/README.md

@@ -71,8 +71,8 @@ controls are experimental; live retrieval depends on a compatible external
 provider. Local chat and push are deferred.
 
 <!-- runlist:release:start -->
-CLI and desktop release version: **0.97.0**.
-[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.97.0).
+CLI and desktop release version: **0.98.1**.
+[Mac installer and release notes](https://github.com/reowens/runlist/releases/tag/desktop-v0.98.1).
 Normal product releases publish both components; an installed Mac app is updated with rollback after it has quit.
 <!-- runlist:release:end -->
 
@@ -105,11 +105,14 @@ Host source, cache and registry copies are labelled separately; a cache entry
 alone does not prove which copy a running host has loaded. No package manager or
 host command runs to produce the `doctor --project` installation report.
 
-**0.96.1 is published and installed locally**, including the desktop usability,
-draft recovery, handoff and failed-status-preview confirmation fixes. The Mac
-installer is signed, notarized and verified; installation retained the previous
-app for rollback. Open it with `rl desktop`. See the
-[release validation](desktop/VALIDATION.md#current-mac-release--2026-10-21)
+**0.98.0 is published and installed locally.** `runlist show` briefs a plan
+(outline, open boxes and `--section` reads with line numbers), marks each
+phase's tally and the active phase, and groups open boxes by phase;
+`runlist use <doc>` briefs a doc over 500 lines. The agent workflow says to
+read plans that way. The desktop app's own code is unchanged from 0.96.1; it
+bundles the 0.98.0 engine. The Mac installer is signed, notarized and verified; installation
+retained the previous app for rollback. Open it with `rl desktop`. See the
+[release validation](desktop/VALIDATION.md#current-mac-release--2026-10-22)
 for checks and evidence. Full-app dialog accessibility remains an open finding;
 fresh/minimum-host and controlled whole-app performance qualification remain
 follow-up work.

package/bin/runlist.mjs

@@ -263,6 +263,7 @@ View & Query:
   plans                             Live plans (excludes archived; --include-archived for all)
   app [document] [--port 5173]      Local Markdown document library with reviewed saves and draft recovery
   use [<file-or-slug>]              Open a doc by type: prompt → consume, plan → start, doc → read
+                                    (a doc over 500 lines prints its brief; --full prints it whole)
   baton [<plan>|<slug>] @<draft>     Save a resume prompt; releases the plan + prints the commit when one is in-session
   prompts [list|show|archive|new] Prompt admin (list / peek / archive / save). Use \`runlist use\` to consume.
   stale                             Stale docs (preset)
@@ -1593,6 +1594,15 @@ substring; other matches are named. A section read stops at 500 lines or
 60 KB and prints the command that continues it. Headings and boxes inside code
 fences are ignored. Several files at once get a shorter outline each.
 
+A phase heading shows its own boxes as [done/total], → marks the active phase
+(the one \`use\` would point at), and a marker its boxes contradict is named
+(marked shipped with boxes open, or todo with every box checked). Open boxes
+are grouped by phase, and the last line is the --section call for the active
+phase.
+
+\`runlist use <doc>\` prints this brief for a doc over 500 lines or 60 KB;
+\`use <doc> --full\` prints the whole body.
+
 A file is a path, filename or slug, as for \`use\`, and any Markdown file in
 the repo works. Nothing is claimed or written. With --json a file that is not
 found is { path, error } rather than an exit; a heading that matches nothing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runlist",
-  "version": "0.97.0",
+  "version": "0.98.1",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

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

@@ -1,6 +1,6 @@
 {
   "name": "runlist-codex",
-  "version": "0.97.0",
+  "version": "0.98.1",
   "description": "Runlist workflow skill, session orientation, and tool guard for Codex",
   "author": {
     "name": "Reo Owens"

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

@@ -12,6 +12,7 @@ Use this skill in repositories with `runlist.config.mjs` or `dotmd.config.mjs`.
 **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.
+- Read a plan or long doc with `runlist show <file>` (card, outline and open boxes with line numbers, the active phase), then `runlist show <file> --section "<heading>"` one section at a time; never read a plan whole.
 - 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`.

package/src/brief.mjs

@@ -1,5 +1,5 @@
 import { extractFrontmatter, normalizeEol } from './frontmatter.mjs';
-import { walkSections, matchSections, walkChecklist } from './section.mjs';
+import { detectMarker, findActivePhase, isPhaseHeading, matchSections, phaseMarkerConflict, phaseTally, walkChecklist, walkSections } from './section.mjs';
 
 // A document in a few KB, for an agent to read in place of the whole file: a
 // heading outline and the open checklist boxes, both with file line numbers,
@@ -16,7 +16,7 @@ export const LIMITS = {
 };
 
 // Several files at once is a survey; each one gets less.
-export const SURVEY_LIMITS = { ...LIMITS, outline: 20, boxes: 10 };
+export const SURVEY_LIMITS = { ...LIMITS, outline: 20, boxes: 10, listItems: 4 };
 
 export const cut = (text, width = LIMITS.width) =>
   text.length > width ? `${text.slice(0, width - 3)}...` : text;
@@ -30,13 +30,39 @@ function fileLines(text) {
 
 // Headings with file coordinates: `line` is the heading, `end` the last line of
 // its section (the line before the next heading at the same or a higher level).
+// A phase heading also carries `phase`: its marker, its own checklist tally,
+// whether it is the active phase (the rule the `use` pickup card applies), and
+// a contradiction between marker and boxes when there is one.
 function headingsOf(body, bodyLineOffset, lastLine) {
-  return walkSections(body).map(s => ({
-    line: s.lineStart + bodyLineOffset,
-    end: Math.min(s.lineEnd + bodyLineOffset, lastLine),
-    level: s.level,
-    heading: s.heading,
-  }));
+  const sections = walkSections(body);
+  const active = findActivePhase(sections);
+  return sections.map(s => {
+    const h = {
+      line: s.lineStart + bodyLineOffset,
+      end: Math.min(s.lineEnd + bodyLineOffset, lastLine),
+      level: s.level,
+      heading: s.heading,
+    };
+    if (isPhaseHeading(s)) {
+      const tally = phaseTally(s);
+      const conflict = phaseMarkerConflict(s);
+      h.phase = {
+        marker: detectMarker(s.heading),
+        done: tally.checked,
+        total: tally.total,
+        active: s === active,
+        conflict: conflict ? { declared: conflict.declared, implied: conflict.implied } : null,
+      };
+    }
+    return h;
+  });
+}
+
+// The phase heading a body line sits under, if any.
+function phaseAt(headings, line) {
+  let found = null;
+  for (const h of headings) if (h.phase && h.line <= line && line <= h.end) found = h;
+  return found;
 }
 
 // Drop the deepest heading levels until the outline fits, then cut the tail.
@@ -91,7 +117,9 @@ export function buildBrief(raw, { all = false, limits = LIMITS } = {}) {
   const headings = headingsOf(body, bodyLineOffset, lines.length);
   const { shown, omitted } = boundOutline(headings, limits.outline);
   const boxes = walkChecklist(body).map(b => ({ ...b, line: b.line + bodyLineOffset }));
-  const open = boxes.filter(b => b.open).map(({ line, text: t }) => ({ line, text: t }));
+  const open = boxes.filter(b => b.open)
+    .map(({ line, text: t }) => ({ line, text: t, phase: phaseAt(headings, line)?.heading ?? null }));
+  const active = headings.find(h => h.phase?.active) ?? null;
   const listed = all ? open : open.slice(0, limits.boxes);
   return {
     lines: lines.length,
@@ -99,6 +127,7 @@ export function buildBrief(raw, { all = false, limits = LIMITS } = {}) {
     frontmatterLines: frontmatter ? bodyLineOffset : 0,
     outline: shown,
     outlineOmitted: omitted,
+    activePhase: active ? { line: active.line, heading: active.heading } : null,
     boxes: { open: open.length, done: boxes.length - open.length },
     open: listed,
     openOmitted: open.length - listed.length,

package/src/show.mjs

@@ -79,6 +79,9 @@ export function showDoc(abs, config) {
   };
 }
 
+// A long next step is cut in the brief, as the pickup card cuts it.
+const NEXT_STEP_WIDTH = 300;
+
 // Fields the text card prints. Everything else non-empty is named on one line
 // so a reader knows it is there without printing the frontmatter.
 const CARD_FIELDS = new Set(['title', 'status', 'next_step', 'blockers']);
@@ -150,18 +153,45 @@ function runSection(target, opts, config) {
   process.stdout.write(out.join('\n') + '\n');
 }
 
+// `[3/7]` for a phase with boxes, and the contradiction between its marker and
+// its boxes when there is one.
+function phaseNote(phase) {
+  if (!phase) return '';
+  let note = phase.total ? `  [${phase.done}/${phase.total}]` : '';
+  if (phase.conflict) {
+    note += phase.conflict.declared === 'shipped'
+      ? `  (marked shipped; ${phase.total - phase.done} open)`
+      : '  (marked todo; every box checked)';
+  }
+  return note;
+}
+
+// A heading as a --section query: trailing markers dropped, which the matcher
+// ignores anyway, so the suggested command reads cleanly.
+const sectionQuery = heading => heading.replace(/[^\w\s]+$/u, '').trim() || heading;
+
 function renderBrief(card, brief) {
   const out = [];
   const width = String(brief.lines).length;
   const kb = Math.max(1, Math.round(brief.bytes / 1024));
   out.push('', `Outline: ${brief.lines.toLocaleString('en-US')} lines, ${kb} KB (line, heading)`);
   if (!brief.outline.length) out.push('  (no headings)');
-  for (const h of brief.outline) out.push(`  ${pad(h.line, width)}  ${cut(`${'#'.repeat(h.level)} ${h.heading}`)}`);
+  for (const h of brief.outline) {
+    const gutter = h.phase?.active ? '→ ' : '  ';
+    out.push(`${gutter}${pad(h.line, width)}  ${cut(`${'#'.repeat(h.level)} ${h.heading}`)}${phaseNote(h.phase)}`);
+  }
   if (brief.outlineOmitted) out.push(`  (+${brief.outlineOmitted} deeper headings not shown; a --section read shows them)`);
   const total = brief.boxes.open + brief.boxes.done;
   if (total) {
     out.push(`Open boxes: ${brief.boxes.open} of ${total} (line, text)`);
-    for (const b of brief.open) out.push(`  ${pad(b.line, width)}  ${cut(b.text)}`);
+    // Grouped under the phase each box sits in, so the list reads as what is
+    // left, phase by phase.
+    let group;
+    for (const b of brief.open) {
+      if (b.phase !== group && (b.phase || group)) out.push(`  ${b.phase ? cut(b.phase) : '(not in a phase)'}`);
+      group = b.phase;
+      out.push(`${group ? '    ' : '  '}${pad(b.line, width)}  ${cut(b.text)}`);
+    }
     if (brief.openOmitted) out.push(`  (+${brief.openOmitted} more: add --all)`);
   }
   if (brief.frontmatter) {
@@ -201,17 +231,33 @@ export function runShow(args, config) {
   cards.forEach((c, n) => {
     if (n) process.stdout.write('\n');
     const out = [`${c.title}  (${c.status ?? 'no status'})`, c.path];
-    if (c.nextStep) out.push(`Next: ${c.nextStep}`);
+    if (c.nextStep) out.push(`Next: ${c.brief ? cut(c.nextStep, NEXT_STEP_WIDTH) : c.nextStep}`);
     for (const b of c.blockers) out.push(`Blocker: ${b}`);
     // The brief's open-box line carries the same count, read outside code fences.
     if (c.checklist?.total && !c.brief) out.push(`Checklist: ${c.checklist.completed} of ${c.checklist.total} done`);
-    for (const r of c.related) out.push(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}`);
-    if (c.links.length) out.push(`Linked from the body: ${c.links.map(l => l.path).join(', ')}`);
+    // With the brief, each related field and the body links show their first
+    // few entries and a count: a hub's dozens of related plans outweighed the
+    // brief itself. --card and --json list every one.
+    const cap = c.brief ? limits.listItems : Infinity;
+    const perField = new Map();
+    for (const r of c.related) {
+      const n = (perField.get(r.field) ?? 0) + 1;
+      perField.set(r.field, n);
+      if (n <= cap) out.push(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}`);
+    }
+    for (const [field, n] of perField) if (n > cap) out.push(`${field}: +${n - cap} more (--card lists all)`);
+    if (c.links.length) {
+      const shown = c.links.slice(0, cap).map(l => l.path).join(', ');
+      out.push(`Linked from the body: ${shown}${c.links.length > cap ? ` (+${c.links.length - cap} more)` : ''}`);
+    }
     if (c.brief) out.push(...renderBrief(c, c.brief));
     process.stdout.write(out.join('\n') + '\n');
   });
   if (!opts.card) {
+    const active = cards.length === 1 ? cards[0].brief?.activePhase : null;
     const file = cards.length === 1 ? shellQuote(cards[0].path) : '<file>';
-    process.stdout.write(`\nOne section: runlist show ${file} --section "<heading>"\n`);
+    process.stdout.write(active
+      ? `\nNext: runlist show ${file} --section ${shellQuote(sectionQuery(active.heading))}\n`
+      : `\nOne section: runlist show ${file} --section "<heading>"\n`);
   }
 }

package/src/use.mjs

@@ -5,13 +5,15 @@ import { asString, die, resolveDocPath, toRepoPath } from './util.mjs';
 import { consumePrompt, pendingPromptsOldestFirst, resolvePromptInput } from './prompts.mjs';
 import { startPlan } from './lifecycle.mjs';
 import { resolveDocArg } from './index.mjs';
+import { LIMITS } from './brief.mjs';
+import { runShow } from './show.mjs';
 
 // Top-level `runlist use [file]` — the single "start engaging with this doc"
 // verb. Dispatches by the target doc's `type:` so agents don't have to know
 // the verb-per-type rule:
 //   - prompt → print body + archive (one-shot consume)
 //   - plan   → set status in-session + print the plan card
-//   - doc    → print body (read-only)
+//   - doc    → print body (read-only); a long doc prints its brief, --full the body
 // With no argument, consumes the oldest pending prompt.
 export async function runUse(argv, config, opts = {}) {
   const positional = argv.find(a => !a.startsWith('-'));
@@ -51,8 +53,17 @@ export async function runUse(argv, config, opts = {}) {
   }
   // Anything else (doc, untyped, custom): print the body. The frontmatter
   // already names everything an agent needs to know about lifecycle for that
-  // type, so the verb stays a no-op read for non-actionable types.
+  // type, so the verb stays a no-op read for non-actionable types. A doc past
+  // the section-read caps prints its brief instead: printing a 2,000-line spec
+  // whole is the read `runlist show` exists to replace.
+  const rel = toRepoPath(filePath, config.repoRoot);
+  const lines = raw.split('\n').length - (raw.endsWith('\n') ? 1 : 0);
+  if (!argv.includes('--full') && (lines > LIMITS.sectionLines || Buffer.byteLength(raw) > LIMITS.sectionBytes)) {
+    runShow([rel], config);
+    process.stderr.write(`${rel} (${type ?? 'untyped'}) is ${lines} lines, so this is its brief. \`runlist use ${rel} --full\` prints it whole.\n`);
+    return;
+  }
   process.stdout.write(raw);
   if (!raw.endsWith('\n')) process.stdout.write('\n');
-  process.stderr.write(`${toRepoPath(filePath, config.repoRoot)} (${type ?? 'untyped'})\n`);
+  process.stderr.write(`${rel} (${type ?? 'untyped'})\n`);
 }