runlist 0.0.0 → 0.94.1

package/src/section.mjs

@@ -0,0 +1,225 @@
+// Pure markdown section walker. Regex-walks H1-H6 headings respecting fenced
+// code blocks (``` and ~~~). Returns flat list of sections with body content
+// and body-relative line numbers (1-indexed). Callers with stripped frontmatter
+// add extractFrontmatter().bodyLineOffset before exposing file coordinates.
+
+export function walkSections(body) {
+  const lines = body.split('\n');
+  const fenceRe = /^(`{3,}|~{3,})/;
+  const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
+  const sections = [];
+  let fenceChar = null;
+  let h2Ancestor = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = line.match(fenceRe);
+    if (fence) {
+      const tok = fence[1][0]; // ` or ~
+      if (fenceChar === null) fenceChar = tok;
+      else if (fenceChar === tok) fenceChar = null;
+      continue;
+    }
+    if (fenceChar !== null) continue;
+    const h = line.match(headingRe);
+    if (!h) continue;
+    const level = h[1].length;
+    const heading = h[2];
+    if (level === 1) h2Ancestor = null;
+    sections.push({
+      level,
+      heading,
+      h2Ancestor: level > 2 ? h2Ancestor : null,
+      lineStart: i + 1, // 1-indexed
+      lineEnd: lines.length, // patched below
+      bodyLineStart: i + 2,
+    });
+    if (level === 2) h2Ancestor = heading;
+  }
+
+  for (let i = 0; i < sections.length; i++) {
+    const next = sections.find((s, j) => j > i && s.level <= sections[i].level);
+    sections[i].lineEnd = next ? next.lineStart - 1 : lines.length;
+  }
+
+  for (const s of sections) {
+    s.body = lines.slice(s.bodyLineStart - 1, s.lineEnd).join('\n').trim();
+  }
+
+  return sections;
+}
+
+// Find a section by heading text, case-insensitive, trims trailing markers.
+// Returns the matching section or null.
+export function findSection(sections, name) {
+  const norm = (s) => s.toLowerCase().replace(/[^\w\s]+$/, '').trim();
+  const target = norm(name);
+  return sections.find(s => norm(s.heading) === target) ?? null;
+}
+
+// Status marker detection for phase headings. Returns one of:
+//   'shipped' | 'skipped' | 'in-progress' | 'blocked' | 'todo' | null
+// Glyphs are checked BEFORE prose, not interleaved with it. A glyph is a
+// deliberate mark; a prose word is often about something else in the sentence:
+//
+//   ⬜ Phase 4: Retry budget rework (scoping COMPLETE)              ← the SCOPING completed
+//   Phase 2 — schema migrated ⬜ todo (column rename half DONE)     ← half a RENAME is done
+//   Phase 3 (original scope) — ⏭ superseded by the shipped Phase 3  ← a DIFFERENT phase shipped
+//
+// Interleaved, first-match-wins order called all three shipped, so
+// findActivePhase skipped a phase the author had explicitly marked unstarted.
+// Within each tier the order is still priority order, which decides a heading
+// carrying more than one mark.
+const GLYPH_PATTERNS = [
+  { kind: 'shipped',     re: /(✅|☑|✔|✓)/ },
+  { kind: 'skipped',     re: /(⏭)/ },
+  { kind: 'in-progress', re: /(🟡|🔄)/ },
+  { kind: 'blocked',     re: /(🚧|🔴)/ },
+  { kind: 'todo',        re: /(⬜|⬛|◻|☐)/ },
+];
+
+const PROSE_PATTERNS = [
+  // A qualifier inverts the word it modifies, and these run BEFORE the plain
+  // `shipped` pattern so the qualifier wins. Otherwise `mostly done` and
+  // `(partially complete)` both read as shipped, and findActivePhase skips a
+  // phase whose own checklist still has open boxes.
+  { kind: 'todo',        re: /\b(?:not|never)[\s-]+(?:complete(?:d)?|done|shipped|started)\b/i },
+  { kind: 'in-progress', re: /\b(?:partially|partly|mostly|nearly|almost|half)[\s-]*(?:complete(?:d)?|done|shipped)\b/i },
+  { kind: 'shipped',     re: /(\bshipped\b|\bdone\b|\bcomplete\b)/i },
+  { kind: 'skipped',     re: /(\bskip(?:ped)?\b)/i },
+  { kind: 'in-progress', re: /(\bin[-_ ]?(?:progress|flight)\b|\bwip\b)/i },
+  { kind: 'blocked',     re: /(\bblocked\b)/i },
+  { kind: 'todo',        re: /(\btodo\b|\bnot[-_ ]?started\b)/i },
+];
+
+export function detectMarker(heading) {
+  for (const { kind, re } of GLYPH_PATTERNS) {
+    if (re.test(heading)) return kind;
+  }
+  for (const { kind, re } of PROSE_PATTERNS) {
+    if (re.test(heading)) return kind;
+  }
+  return null;
+}
+
+// Leading decoration a phase heading may carry before the word "Phase":
+// emphasis punctuation and any run of status markers. `detectMarker` already
+// reads a marker wherever it sits, but this test was anchored at `^phase`, so
+// a plan that writes `### ⬜ Phase 2 — …` had NO phases at all — not a
+// miscount, an empty phase set, which drops the pickup card to its
+// "no ## Phases section" fallback.
+// Several of these glyphs are commonly typed in emoji-presentation form
+// (the base codepoint plus a variation selector): the skip mark, the ballot
+// box, the check mark. `detectMarker` is a substring test so it never
+// noticed. This is a character CLASS, and the selector sits between the glyph
+// and the space, is not \s, and ends the run — so a heading led by the
+// emoji-presentation form was not a phase heading at all, while the bare
+// codepoint was. Reported by the owner, 2026-08-16.
+const PHASE_DECORATION = String.raw`[\s>*_~\`#-]*(?:[✅🚧⬜🟡⏭☑✔✓◻☐⬛🔴🔄][︎️]?\s*)*`;
+const PHASE_LEAD = new RegExp(`^${PHASE_DECORATION}phase\\b`, 'i');
+const FILES_MANIFEST_ANCESTOR = new RegExp(`^${PHASE_DECORATION}files\\b`, 'i');
+
+// "Phase 3 outcome" is commentary ABOUT a phase, not a phase. Counting it
+// inflates the phase set, and because `findActivePhase` ranks blocked above
+// todo, a heading like "Phase 3 smoke findings — BLOCKER" gets picked as the
+// plan's active phase over a real unstarted one.
+//
+// The noun list is deliberately tight. Wrongly excluding a real phase hides
+// work; wrongly including commentary only miscounts — so this errs toward
+// counting, and a word is added here only once the corpus shows it standing
+// for a retrospective rather than a phase.
+const PHASE_COMMENTARY = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+(outcome|progress|notes?|findings?|smoke|retro|review|recap|summary)\\b`,
+  'i',
+);
+
+// Compound commentary shapes covered by regression fixtures. Keep
+// these anchored immediately after the phase identifier: the individual nouns
+// all collide with genuine work. In particular, do not add bare `status`,
+// `audit`, `design`, `shape`, `plan`, `pre-plan`, or `gap-check`; the corpus has
+// executable phases with each of those names. The dated gap-check form below is
+// a status report, while `Phase N — gap-check fixes` remains a real phase.
+const PHASE_COMPOUND_COMMENTARY = new RegExp(
+  `^${PHASE_DECORATION}phase\\s+\\S+\\s+(?:` +
+    `execution\\s+status|` +
+    `status\\s+snapshot|` +
+    `gap[- ]check\\s+\\d{4}-\\d{2}-\\d{2}|` +
+    `audit\\s+results?|` +
+    `inventory\\s+findings?|` +
+    `deviations\\s*(?:\\+|&|and)\\s*(?:open\\s+questions|notes?)|` +
+    `design\\s+[-—:]\\s*researched|` +
+    `shape\\s+[-—:]\\s*worked\\s+out|` +
+    `sub[- ]phases` +
+  `)\\b`,
+  'i',
+);
+
+export function isPhaseHeading(section) {
+  if (section.level !== 3) return false;
+  if (FILES_MANIFEST_ANCESTOR.test(section.h2Ancestor ?? '')) return false;
+  return PHASE_LEAD.test(section.heading)
+    && !PHASE_COMMENTARY.test(section.heading)
+    && !PHASE_COMPOUND_COMMENTARY.test(section.heading);
+}
+
+// A phase's OWN checklist — the boxes directly under its heading, stopping at
+// the next heading of any level so a sub-section's checklist is never counted
+// as the parent phase's evidence.
+export function phaseTally(section) {
+  let checked = 0, unchecked = 0;
+  for (const line of String(section?.body ?? '').split('\n')) {
+    if (/^#{1,6}\s/.test(line)) break;
+    if (/^\s*[-*]\s*\[x\]/i.test(line)) checked++;
+    else if (/^\s*[-*]\s*\[ \]/.test(line)) unchecked++;
+  }
+  return { checked, unchecked, total: checked + unchecked };
+}
+
+/**
+ * A phase whose declared marker its own checklist contradicts.
+ *
+ * Only two disagreements are reported, because only two are unambiguous:
+ *
+ *   shipped + an open box  — the plan's own checklist says otherwise
+ *   todo    + every box checked — the work is done, the marker says unstarted
+ *
+ * `blocked` and `skipped` are judgements a tally cannot refute (blocked at 0/7
+ * is perfectly coherent), and `in-progress` with everything checked usually
+ * means work the checklist does not enumerate. These ambiguous cases are
+ * excluded because checklist counts alone cannot establish a conflict.
+ *
+ * Returns null when there is no conflict, no marker, or no checklist.
+ */
+export function phaseMarkerConflict(section) {
+  const declared = detectMarker(section?.heading ?? '');
+  if (declared !== 'shipped' && declared !== 'todo') return null;
+  const tally = phaseTally(section);
+  if (tally.total === 0) return null;
+  if (declared === 'shipped' && tally.unchecked > 0) return { declared, implied: 'in progress', ...tally };
+  if (declared === 'todo' && tally.unchecked === 0) return { declared, implied: 'shipped', ...tally };
+  return null;
+}
+
+// Summarize a phase set: { 'shipped': 2, 'in-progress': 1, 'todo': 2 }
+export function summarizePhases(sections) {
+  const phases = sections.filter(isPhaseHeading);
+  const counts = {};
+  for (const p of phases) {
+    const k = detectMarker(p.heading) ?? 'todo';
+    counts[k] = (counts[k] ?? 0) + 1;
+  }
+  return { total: phases.length, counts, phases };
+}
+
+// Active phase = first phase whose marker is NOT shipped/skipped.
+// Priority within active: in-progress > blocked > todo.
+export function findActivePhase(sections) {
+  const phases = sections.filter(isPhaseHeading);
+  const active = phases.filter(p => {
+    const m = detectMarker(p.heading);
+    return m !== 'shipped' && m !== 'skipped';
+  });
+  if (active.length === 0) return null;
+  const rank = (m) => ({ 'in-progress': 0, 'blocked': 1, 'todo': 2, [null]: 3 })[m] ?? 3;
+  return active.sort((a, b) => rank(detectMarker(a.heading)) - rank(detectMarker(b.heading)))[0];
+}

package/src/semantic-search-client.mjs

@@ -0,0 +1,58 @@
+import {spawn} from 'node:child_process';
+import {StringDecoder} from 'node:string_decoder';
+import path from 'node:path';
+
+export class SemanticSearchError extends Error {
+  constructor(code){super(code);this.code=code;}
+}
+export function semanticEnvironment(nodePath,base=process.env){
+  const env={};for(const key of ['HOME','USERPROFILE','APPDATA','LOCALAPPDATA','SystemRoot','WINDIR','TEMP','TMP','TMPDIR','LANG','LC_ALL','XDG_CONFIG_HOME','XDG_DATA_HOME','XDG_CACHE_HOME'])if(base[key])env[key]=base[key];
+  env.PATH=path.dirname(nodePath);env.GMAX_NO_AUTOSTART='1';env.GMAX_NO_STALE_HINT='1';return env;
+}
+// Small stdio MCP client: no SDK, gmax library, index or model dependency in Runlist.
+export async function withSemanticClient(installation,checkout,signal,work,{spawnChild=spawn}={}){
+  signal.throwIfAborted();
+  const child=spawnChild(installation.nodePath,[installation.entryPath,'mcp','--existing-index-only'],{cwd:checkout,env:semanticEnvironment(installation.nodePath),stdio:['pipe','pipe','pipe'],windowsHide:true,shell:false});
+  const pending=new Map(),decoder=new StringDecoder('utf8');let nextId=1,carry='',frameBytes=0,ended=false,outputBytes=0;
+  const fail=code=>{if(ended)return;ended=true;for(const entry of pending.values())entry.reject(new SemanticSearchError(code));pending.clear();child.kill();};
+  child.on('error',()=>fail('tool_unavailable'));child.on('exit',()=>fail('tool_unavailable'));
+  child.stdin.on('error',()=>fail('tool_unavailable'));
+  // Drain diagnostics without retaining paths, queries, snippets or stderr in UI/logs.
+  child.stderr.on('data',()=>{});
+  child.stdout.on('data',chunk=>{
+    outputBytes+=chunk.length;frameBytes+=chunk.length;
+    if(outputBytes>4*1024*1024||frameBytes>1024*1024){fail('response_too_large');return;}
+    carry+=decoder.write(chunk);
+    for(;;){const nl=carry.indexOf('\n');if(nl<0)break;const line=carry.slice(0,nl);carry=carry.slice(nl+1);frameBytes=Buffer.byteLength(carry);let message;
+      try{message=JSON.parse(line);}catch{fail('invalid_response');return;}
+      if(!message||message.jsonrpc!=='2.0'){fail('invalid_response');return;}
+      if(message.id!==undefined){const entry=pending.get(message.id);if(!entry){fail('invalid_response');return;}pending.delete(message.id);if(message.error)entry.reject(new SemanticSearchError('unsupported_tool'));else entry.resolve(message.result);}
+      else if(message.method&&!message.method.startsWith('notifications/')){fail('invalid_response');return;}
+    }
+  });
+  function call(method,params){if(ended||signal.aborted)return Promise.reject(new SemanticSearchError('cancelled'));const id=nextId++,wire=JSON.stringify({jsonrpc:'2.0',id,method,params})+'\n';if(Buffer.byteLength(wire)>1024*1024)return Promise.reject(new SemanticSearchError('response_too_large'));return new Promise((resolve,reject)=>{pending.set(id,{resolve,reject});child.stdin.write(wire);});}
+  const abort=()=>{for(const id of pending.keys())if(child.stdin.writable)child.stdin.write(JSON.stringify({jsonrpc:'2.0',method:'notifications/cancelled',params:{requestId:id,reason:'Cancelled'}})+'\n');fail('cancelled');};
+  signal.addEventListener('abort',abort,{once:true});
+  if(signal.aborted)abort();
+  try{
+    const hello=await call('initialize',{protocolVersion:'2025-06-18',capabilities:{},clientInfo:{name:'Runlist',version:'1'}});
+    if(hello?.protocolVersion!=='2025-06-18'||hello.serverInfo?.name!=='gmax-document-search')throw new SemanticSearchError('unsupported_tool');
+    child.stdin.write(JSON.stringify({jsonrpc:'2.0',method:'notifications/initialized'})+'\n');
+    const tool=async(name,args)=>{const reply=await call('tools/call',{name,arguments:args});const data=reply?.structuredContent;
+      if(reply?.isError||!data||data.contractVersion!==1||data.capabilities?.existingIndexOnly!==1||data.capabilities.queryLogging!==false||data.capabilities.watch!==false||data.capabilities.runtimeStartup!==false)throw new SemanticSearchError('unsupported_tool');
+      if(data.state==='ready'&&(!Number.isSafeInteger(data.generation)||data.generation<1))throw new SemanticSearchError('embedding_mismatch');
+      return data;
+    };
+    return await work({tool});
+  }finally{
+    signal.removeEventListener('abort',abort);ended=true;for(const entry of pending.values())entry.reject(new SemanticSearchError('cancelled'));pending.clear();
+    child.stdin.end();child.kill();
+    // Reap only this owned bridge. The shared daemon/embedding runtime is untouched.
+    if(child.exitCode===null&&child.signalCode===null)await new Promise(resolve=>{
+      const kill=setTimeout(()=>child.kill('SIGKILL'),500),deadline=setTimeout(done,1000);
+      function done(){clearTimeout(kill);clearTimeout(deadline);child.removeListener('exit',done);resolve();}
+      child.once('exit',done);
+      if(child.exitCode!==null||child.signalCode!==null)done();
+    });
+  }
+}

package/src/ship.mjs

@@ -0,0 +1,166 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { die, warn, toRepoPath } from './util.mjs';
+import { assertGitIndex } from './git.mjs';
+import { green, dim, yellow } from './color.mjs';
+
+// Files runlist ship will auto-stage when they're dirty. Anything outside this
+// allowlist stays in the working tree — user has to `git add` it explicitly,
+// so secrets / .env / sibling-session WIP never get bundled into a release.
+const ALLOWLIST_PATTERNS = [
+  /^src\//,
+  /^test\//,
+  /^bin\//,
+  /^docs\//,
+  // Plugin artifacts ship in lockstep with the CLI (the plugin-based workflow
+  // is canonical), so a dirty SKILL.md / command / hook / manifest is a release
+  // change. `.claude/commands/` stays for repos that still hand-author slash
+  // commands — harmless, and dropping it would un-stage their edits.
+  /^plugins\//,
+  /^\.claude-plugin\//,
+  /^\.claude\/commands\//,
+  /^runlist\.config\.example\.mjs$/,
+  /^runlist\.config\.mjs$/,
+  /^dotmd\.config\.example\.mjs$/,
+  /^dotmd\.config\.mjs$/,
+  /^package(?:-lock)?\.json$/,
+  /^README\.md$/,
+  /^CLAUDE\.md$/,
+  /^CHANGELOG\.md$/,
+  /^\.gitignore$/,
+];
+
+export function bumpVersion(current, bump) {
+  const parts = current.split('.').map(Number);
+  if (parts.length !== 3 || parts.some(Number.isNaN)) {
+    die(`Cannot parse current version: ${current}`);
+  }
+  const [maj, min, pat] = parts;
+  if (bump === 'major') return `${maj + 1}.0.0`;
+  if (bump === 'minor') return `${maj}.${min + 1}.0`;
+  if (bump === 'patch') return `${maj}.${min}.${pat + 1}`;
+  die(`Invalid bump: ${bump}. Use patch | minor | major.`);
+}
+
+export function isAllowed(repoPath) {
+  return ALLOWLIST_PATTERNS.some(re => re.test(repoPath));
+}
+
+export function listDirtyFiles(repoRoot) {
+  const result = spawnSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  });
+  if (result.status !== 0) die(`git status failed: ${result.stderr}`);
+  const fields = result.stdout.split('\0');
+  const files = [];
+  for (let i = 0; i < fields.length; i++) {
+    const record = fields[i];
+    if (!record) continue;
+    const status = record.slice(0, 2);
+    const destination = record.slice(3);
+    files.push({ status, path: destination });
+    if (status.includes('R')) {
+      const source = fields[++i];
+      if (source) files.push({ status, path: source });
+    } else if (status.includes('C')) {
+      i++; // Porcelain -z includes the unchanged copy source as a second field.
+    }
+  }
+  return files;
+}
+
+export async function runShip(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const positional = argv.filter(a => !a.startsWith('-'));
+  const bump = positional[0] ?? 'patch';
+  if (!['patch', 'minor', 'major'].includes(bump)) {
+    die(`Invalid bump: ${bump}. Usage: runlist ship [patch|minor|major]`);
+  }
+
+  const pkgPath = path.join(config.repoRoot, 'package.json');
+  if (!existsSync(pkgPath)) die(`No package.json at ${toRepoPath(pkgPath, config.repoRoot)}`);
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  const current = pkg.version;
+  const target = bumpVersion(current, bump);
+
+  process.stdout.write(`${green('→')} Shipping ${current} → ${target} (${bump})\n`);
+
+  try {
+    assertGitIndex(config.repoRoot);
+  } catch (err) {
+    die(`Refusing to ship with inherited staged files. ${err.message}`);
+  }
+
+  // Per-repo slash-command scaffolding is retired (the runlist plugin's SKILL.md
+  // is canonical now), so there is nothing to regenerate at ship time. Any
+  // stale generated files are swept by `runlist hud` / `runlist doctor`.
+
+  // Identify dirty tracked files. Anything matching the allowlist gets
+  //    staged; everything else is left dirty so the user can handle it.
+  const dirty = listDirtyFiles(config.repoRoot);
+  const untracked = dirty.filter(d => d.status === '??');
+  const tracked = dirty.filter(d => d.status !== '??');
+
+  const toStage = tracked.filter(d => isAllowed(d.path)).map(d => d.path);
+  const skipped = tracked.filter(d => !isAllowed(d.path)).map(d => d.path);
+
+  // Untracked files matching the allowlist (e.g. a fresh new plan) are also
+  // safe to add — that's the common case of "scaffolded a plan, now shipping."
+  const newAllowed = untracked.filter(d => isAllowed(d.path)).map(d => d.path);
+  const newSkipped = untracked.filter(d => !isAllowed(d.path)).map(d => d.path);
+
+  const allToStage = [...toStage, ...newAllowed];
+  const allSkipped = [...skipped, ...newSkipped];
+
+  if (allSkipped.length > 0) {
+    process.stderr.write(`${dim(`Not staging (outside allowlist): ${allSkipped.join(', ')}`)}\n`);
+  }
+
+  if (dryRun) {
+    process.stdout.write(`${dim('[dry-run]')} Would stage ${allToStage.length} file(s):\n`);
+    for (const p of allToStage) process.stdout.write(`  ${p}\n`);
+    process.stdout.write(`${dim('[dry-run]')} Would commit and run \`npm version ${bump}\`\n`);
+    return;
+  }
+
+  if (allSkipped.length > 0) {
+    die('Refusing to create a release preparation commit while skipped files are dirty. Commit, stash, or remove them first.');
+  }
+
+  if (allToStage.length > 0) {
+    const add = spawnSync('git', ['add', '--', ...allToStage], { cwd: config.repoRoot, encoding: 'utf8' });
+    if (add.status !== 0) die(`git add failed: ${add.stderr}`);
+
+    try {
+      assertGitIndex(config.repoRoot, allToStage);
+    } catch (err) {
+      die(`Refusing to commit an unexpected Git index. ${err.message}`);
+    }
+
+    const subject = `chore: release ${target}`;
+    const body = `Auto-staged by \`runlist ship\`:\n${allToStage.map(p => `- ${p}`).join('\n')}`;
+    const commitMsg = `${subject}\n\n${body}`;
+    const commit = spawnSync('git', ['commit', '-m', commitMsg], { cwd: config.repoRoot, encoding: 'utf8' });
+    if (commit.status !== 0) die(`git commit failed: ${commit.stderr || commit.stdout}`);
+    process.stdout.write(`${green('→')} Committed: ${subject}\n`);
+  } else {
+    process.stdout.write(`${dim('→ Nothing to commit before bump.')}\n`);
+  }
+
+  // 3. npm version <bump> — handles package.json bump, tag, push, GH release,
+  //    npm publish, and local reinstall via the existing pre/postversion
+  //    scripts. We stream its output so the user sees CI progress live.
+  process.stdout.write(`${green('→')} Running \`npm version ${bump}\`…\n`);
+  const npmResult = spawnSync('npm', ['version', bump], {
+    cwd: config.repoRoot,
+    stdio: 'inherit',
+  });
+  if (npmResult.status !== 0) {
+    warn('`npm version` failed. If the target tag exists, run `npm run release:resume`; otherwise follow the rollback/rerun guidance from the version lifecycle.');
+    process.exit(npmResult.status ?? 1);
+  }
+
+  process.stdout.write(`${green('✓')} Shipped ${target}\n`);
+}

package/src/show.mjs

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { parseDocFile, resolveDocArg } from './index.mjs';
+import { resolveBodyLinkTarget } from './body-link.mjs';
+import { die, normalizeStringList, resolveRefPath, toRepoPath } from './util.mjs';
+
+// `runlist show <file...>` — one document's card as data: its title, status,
+// next step, blockers and checklist, the plans and docs its frontmatter names,
+// and the documents its body links to. Read-only; nothing is claimed.
+
+// Frontmatter lists that name other documents. The configured reference fields
+// are read too; `related_docs` is read whether or not a repo configures it.
+const RELATED = ['related_plans', 'related_docs', 'supports_plans', 'parent_plan', 'runlist'];
+
+function relatedFields(config) {
+  const configured = [...(config.referenceFields?.bidirectional ?? []), ...(config.referenceFields?.unidirectional ?? [])];
+  return [...new Set([...RELATED, ...configured])];
+}
+
+function brief(abs, config) {
+  try {
+    const d = parseDocFile(abs, config, { fast: true });
+    return { title: d.title, status: d.status, type: d.type };
+  } catch {
+    return { title: null, status: null, type: null };
+  }
+}
+
+/** The card for one document, by absolute path. */
+export function showDoc(abs, config) {
+  const doc = parseDocFile(abs, config, { fast: true });
+  const raw = readFileSync(abs, 'utf8');
+  const fm = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter ?? '', []);
+  const dir = path.dirname(abs);
+  const seen = new Set([doc.path]);
+
+  const related = [];
+  for (const field of relatedFields(config)) {
+    for (const entry of normalizeStringList(fm[field])) {
+      const ref = String(entry).replace(/^>\s*/, '').replace(/#.*$/, '').trim();
+      if (!ref) continue;
+      const target = resolveRefPath(ref, dir, config.repoRoot);
+      const rel = target ? toRepoPath(target, config.repoRoot) : null;
+      if (rel && seen.has(`${field}:${rel}`)) continue;
+      if (rel) seen.add(`${field}:${rel}`);
+      related.push({ field, ref, path: rel, exists: Boolean(target), ...(target ? brief(target, config) : { title: null, status: null, type: null }) });
+    }
+  }
+
+  const named = new Set(related.map(r => r.path).filter(Boolean));
+  const links = [];
+  for (const link of doc.bodyLinks ?? []) {
+    if (link.targetKind !== 'document') continue;
+    const target = resolveBodyLinkTarget(link.href, dir, config.repoRoot);
+    if (!target.ok) continue;
+    const rel = toRepoPath(target.path, config.repoRoot);
+    if (seen.has(rel) || named.has(rel)) continue;
+    seen.add(rel);
+    links.push({ path: rel, ...brief(target.path, config) });
+  }
+
+  return {
+    path: doc.path,
+    type: doc.type,
+    title: doc.title,
+    status: doc.status,
+    summary: doc.summary,
+    currentState: doc.currentState === 'No current_state set' ? null : doc.currentState,
+    nextStep: doc.nextStep,
+    blockers: doc.blockers,
+    checklist: doc.checklist,
+    updated: doc.updated,
+    related,
+    links,
+  };
+}
+
+export function runShow(args, config) {
+  const json = args.includes('--json');
+  const targets = args.filter(a => !a.startsWith('-'));
+  if (!targets.length) die('Usage: runlist show <file...> [--json]');
+  const cards = [];
+  for (const t of targets) {
+    const abs = resolveDocArg(t, config, { dieOnMiss: !json });
+    cards.push(abs ? showDoc(abs, config) : { path: t, error: 'not found' });
+  }
+  if (json) {
+    process.stdout.write(`${JSON.stringify(cards, null, 2)}\n`);
+    return;
+  }
+  cards.forEach((c, n) => {
+    if (n) process.stdout.write('\n');
+    process.stdout.write(`${c.title}  (${c.status ?? 'no status'})\n${c.path}\n`);
+    if (c.nextStep) process.stdout.write(`Next: ${c.nextStep}\n`);
+    for (const b of c.blockers) process.stdout.write(`Blocker: ${b}\n`);
+    if (c.checklist?.total) process.stdout.write(`Checklist: ${c.checklist.completed} of ${c.checklist.total} done\n`);
+    for (const r of c.related) process.stdout.write(`${r.field}: ${r.path ?? `${r.ref} (missing)`}${r.status ? `  (${r.status})` : ''}\n`);
+    if (c.links.length) process.stdout.write(`Linked from the body: ${c.links.map(l => l.path).join(', ')}\n`);
+  });
+}

package/src/skill-drift.mjs

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+// runlist is a drift- and staleness-catcher that didn't, until now, catch drift
+// in its OWN plugin surface. Two canonical workflow-doc surfaces are kept in
+// lockstep by hand: the repo's CLAUDE.md (its own instructions) and the plugin
+// SKILL.md (what every OTHER repo's session learns the workflow from). CLAUDE.md
+// literally says "keep it in sync with the guidance below" — this guard makes
+// that lockstep mechanical instead of manual.
+//
+// The comparison unit is a marked block (not a fuzzy phrase heuristic):
+// deterministic, robust, and zero false positives. Each surface wraps the
+// irreducible workflow contract between the markers below; the guard extracts
+// both and compares them whitespace-tolerantly. Editing the contract in one
+// surface and forgetting the other is exactly what this catches.
+
+export const CANONICAL_MARKERS = {
+  start: '<!-- runlist:canonical-workflow:start -->',
+  end: '<!-- runlist:canonical-workflow:end -->',
+};
+
+// The spelling used through dotmd-cli 0.78.0. Still read, so a copy of either
+// surface that predates the rename keeps participating in the lockstep instead
+// of silently dropping out of it. A block must open and close with the same
+// spelling; the current spelling is tried first.
+export const LEGACY_CANONICAL_MARKERS = {
+  start: '<!-- dotmd:canonical-workflow:start -->',
+  end: '<!-- dotmd:canonical-workflow:end -->',
+};
+const MARKER_SETS = [CANONICAL_MARKERS, LEGACY_CANONICAL_MARKERS];
+
+const CLAUDE_MD = 'CLAUDE.md';
+const SKILL_MD = path.join('plugins', 'runlist', 'skills', 'runlist', 'SKILL.md');
+
+// Pull the inner text between the canonical markers. Returns null when the
+// markers are absent or malformed — callers treat null as "this surface doesn't
+// participate in the lockstep block", which is what keeps a user repo that has
+// its own CLAUDE.md (but never adopted the block) from ever tripping the guard.
+export function extractCanonicalBlock(text) {
+  if (typeof text !== 'string') return null;
+  for (const markers of MARKER_SETS) {
+    const startIdx = text.indexOf(markers.start);
+    if (startIdx === -1) continue;
+    const afterStart = startIdx + markers.start.length;
+    const endIdx = text.indexOf(markers.end, afterStart);
+    if (endIdx === -1 || endIdx < afterStart) continue;
+    return text.slice(afterStart, endIdx);
+  }
+  return null;
+}
+
+// Whitespace-tolerant so a CRLF vs LF or a stray trailing space between the two
+// files isn't reported as drift — only meaningful content divergence is.
+function normalizeBlock(block) {
+  return block
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(line => line.replace(/\s+$/, ''))
+    .join('\n')
+    .trim();
+}
+
+function readIfPresent(filePath) {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+// Guard: the canonical workflow block must stay identical across CLAUDE.md and
+// the plugin SKILL.md. Returns [] unless BOTH files exist AND BOTH carry the
+// block — so it only fires in a repo that has adopted the lockstep convention
+// (i.e. the runlist repo itself), never in a user repo that merely has its own
+// CLAUDE.md. That strict gate is the price of zero false positives; the
+// trade-off is that deleting the markers from one surface silently disables the
+// guard rather than warning (a deliberate, visible act, unlike a content edit).
+export function checkSkillDrift(config) {
+  const repoRoot = config?.repoRoot;
+  if (!repoRoot) return [];
+
+  const claudeText = readIfPresent(path.join(repoRoot, CLAUDE_MD));
+  const skillText = readIfPresent(path.join(repoRoot, SKILL_MD));
+  if (claudeText === null || skillText === null) return [];
+
+  const claudeBlock = extractCanonicalBlock(claudeText);
+  const skillBlock = extractCanonicalBlock(skillText);
+  if (claudeBlock === null || skillBlock === null) return [];
+
+  if (normalizeBlock(claudeBlock) === normalizeBlock(skillBlock)) return [];
+
+  return [{
+    path: SKILL_MD,
+    level: 'warning',
+    message: `canonical workflow block drifted from \`${CLAUDE_MD}\`. The block between \`${CANONICAL_MARKERS.start}\` and \`${CANONICAL_MARKERS.end}\` must stay identical in both files — reconcile them so the plugin skill and the repo instructions teach the same workflow.`,
+  }];
+}