runlist 0.0.0 → 0.94.1

package/src/health.mjs

@@ -0,0 +1,212 @@
+import path from 'node:path';
+import { buildIndex } from './index.mjs';
+import { bold, dim, green, yellow, red } from './color.mjs';
+import { buildCoordinationIndex, buildRoadmapIndex, isRoadmapHub, hubLabel } from './runlist.mjs';
+import { isArchivedPath } from './util.mjs';
+
+export function runHealth(argv, config) {
+  const json = argv.includes('--json');
+  const index = buildIndex(config);
+
+  // Only plans (type: plan or untyped docs in plans root)
+  const allPlans = index.docs.filter(d => d.type === 'plan' || (!d.type && d.root?.includes('plan')));
+  // Coordination hubs (prose-first runlists) are navigation maps, not execution
+  // units — they carry no checklist and skew active-plan aging — so lift the
+  // LIVE ones out of the pipeline + active set into a dedicated Runlists tally,
+  // mirroring `runlist plans` / `runlist runlists`. Archived hubs stay in `plans` so
+  // the archived/velocity counts are unchanged. No coordination hubs → `plans`
+  // equals the full set and every count below is identical to before.
+  const coordination = buildCoordinationIndex(index, config);
+  const closedStatuses = new Set([
+    ...(config.lifecycle?.archiveStatuses ?? []),
+    ...(config.lifecycle?.terminalStatuses ?? []),
+  ]);
+  const isLiveHub = (d) => coordination.has(d.path) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
+  const isLiveRoadmap = (d) => isRoadmapHub(d) && !closedStatuses.has(d.status) && !isArchivedPath(d.path, config);
+  const byAgeDesc = (a, b) => (b.daysSinceUpdate ?? -1) - (a.daysSinceUpdate ?? -1);
+  // Roadmaps (tier-3) get their own tally above Runlists — held out of the
+  // pipeline like coordination hubs, but pointed at via `runlist roadmaps`.
+  const roadmapHubs = allPlans.filter(isLiveRoadmap).sort(byAgeDesc);
+  const roadmapIndex = roadmapHubs.length > 0 ? buildRoadmapIndex(index, config, { coordination }) : new Map();
+  const runlistHubs = allPlans.filter(d => isLiveHub(d) && !isRoadmapHub(d))
+    // Most stale first — health is an aging lens, and it matches `runlist runlists`'
+    // default. Unknown-age hubs sort last so they never top the list.
+    .sort(byAgeDesc);
+  const plans = allPlans.filter(d => !isLiveHub(d));
+  const now = Date.now();
+
+  // Status distribution
+  const byStatus = {};
+  for (const doc of plans) {
+    const s = doc.status ?? 'unknown';
+    byStatus[s] = (byStatus[s] || 0) + 1;
+  }
+
+  // Active plan aging (days since created)
+  const activePlans = plans.filter(d => d.status === 'active');
+  const activeAges = activePlans.map(d => {
+    const created = d.created ? new Date(d.created).getTime() : null;
+    return created ? Math.floor((now - created) / 86400000) : null;
+  }).filter(a => a !== null);
+
+  // Recently archived (last 30 days by updated date)
+  const recentlyArchived = plans
+    .filter(d => d.status === 'archived' && d.updated)
+    .filter(d => {
+      const updated = new Date(d.updated).getTime();
+      return (now - updated) < 30 * 86400000;
+    });
+
+  // Paused plan aging
+  const pausedPlans = plans.filter(d => d.status === 'paused');
+  const pausedAges = pausedPlans.map(d => {
+    const updated = d.updated ? new Date(d.updated).getTime() : null;
+    return updated ? Math.floor((now - updated) / 86400000) : null;
+  }).filter(a => a !== null);
+
+  // Blocked plan count + aging
+  const blockedPlans = plans.filter(d => d.status === 'blocked');
+
+  // Checklist progress on active plans
+  const activeWithChecklists = activePlans.filter(d => d.checklist?.total > 0);
+  const avgCompletion = activeWithChecklists.length > 0
+    ? activeWithChecklists.reduce((sum, d) => sum + (d.checklist.completed / d.checklist.total), 0) / activeWithChecklists.length
+    : null;
+
+  // Plans with deferred items (search body — not available here, use checklist proxy)
+  const readyPlans = plans.filter(d => d.status === 'ready');
+  const plannedPlans = plans.filter(d => d.status === 'planned');
+
+  if (json) {
+    process.stdout.write(JSON.stringify({
+      totalPlans: plans.length,
+      byStatus,
+      active: {
+        count: activePlans.length,
+        ages: activeAges,
+        avgAge: activeAges.length > 0 ? Math.round(activeAges.reduce((a, b) => a + b, 0) / activeAges.length) : null,
+        maxAge: activeAges.length > 0 ? Math.max(...activeAges) : null,
+        avgChecklistCompletion: avgCompletion ? Math.round(avgCompletion * 100) : null,
+      },
+      paused: { count: pausedPlans.length, ages: pausedAges },
+      blocked: { count: blockedPlans.length },
+      ready: { count: readyPlans.length },
+      planned: { count: plannedPlans.length },
+      recentlyArchived: { count: recentlyArchived.length, last30d: recentlyArchived.map(d => path.basename(d.path, '.md')) },
+      runlists: { count: runlistHubs.length, hubs: runlistHubs.map(d => { const info = coordination.get(d.path); return { path: d.path, title: d.title, status: d.status, childCount: info?.childCount ?? 0, total: info?.total ?? 0, doneCount: info?.doneCount ?? 0, parkedCount: info?.parkedCount ?? 0, nextPickup: info?.nextPickup ?? null }; }) },
+      roadmaps: { count: roadmapHubs.length, hubs: roadmapHubs.map(d => { const info = roadmapIndex.get(d.path); return { path: d.path, title: d.title, status: d.status, childCount: info?.childCount ?? 0, grandTotal: info?.grandTotal ?? 0, grandDone: info?.grandDone ?? 0, grandParked: info?.grandParked ?? 0 }; }) },
+    }, null, 2) + '\n');
+    return;
+  }
+
+  process.stdout.write(bold('Plan Health') + '\n\n');
+
+  // Pipeline — ordered by the configured status vocab, then any present-but-
+  // unconfigured statuses (custom ones a repo defines, by count). Deriving from
+  // the live status set means in-session/partial/awaiting/etc. all show, and a
+  // dead status never leaves an empty row — unlike the old hand-kept list that
+  // drifted out of sync with the vocabulary.
+  process.stdout.write(bold('Pipeline:') + '\n');
+  const statusOrder = config.statusOrder ?? [];
+  const present = Object.keys(byStatus).filter(s => byStatus[s] > 0);
+  const ordered = [
+    ...statusOrder.filter(s => present.includes(s)),
+    ...present.filter(s => !statusOrder.includes(s)).sort((a, b) => byStatus[b] - byStatus[a]),
+  ];
+  const pad = Math.max(10, ...ordered.map(s => s.length));
+  for (const s of ordered) {
+    const count = byStatus[s];
+    const bar = '█'.repeat(Math.min(count, 40));
+    process.stdout.write(`  ${s.padEnd(pad)} ${String(count).padStart(4)}  ${dim(bar)}\n`);
+  }
+  process.stdout.write('\n');
+
+  // Roadmaps (tier-3) — pinned above Runlists with the recursive grand total.
+  if (roadmapHubs.length > 0) {
+    process.stdout.write(`${bold('Roadmaps:')} ${roadmapHubs.length}  ${dim('· runlist roadmap')}\n`);
+    for (const doc of roadmapHubs.slice(0, 8)) {
+      const slug = hubLabel(doc).padEnd(28);
+      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
+      const info = roadmapIndex.get(doc.path);
+      const rollStr = info ? `  ${dim(`${info.grandDone}/${info.grandTotal}`)}` : '';
+      const kidStr = info ? `  ${dim(`${info.childCount} runlists`)}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${rollStr}${kidStr}\n`);
+    }
+    if (roadmapHubs.length > 8) {
+      process.stdout.write(`  ${dim(`...and ${roadmapHubs.length - 8} more`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Runlists (coordination hubs) — held out of the leaf-plan pipeline above and
+  // surfaced as their own tally so they don't inflate the active count. Newest
+  // first, mirroring `runlist runlists`; capped with a "more" footer.
+  if (runlistHubs.length > 0) {
+    process.stdout.write(`${bold('Runlists:')} ${runlistHubs.length}  ${dim('· runlist runlists')}\n`);
+    for (const doc of runlistHubs.slice(0, 8)) {
+      const slug = hubLabel(doc).padEnd(28);
+      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '?d';
+      const info = coordination.get(doc.path);
+      const relStr = info?.total ? `  ${dim(`${info.doneCount}/${info.total}`)}` : '';
+      const nextStr = info?.nextPickup ? `  ${green('→')} ${info.nextPickup.label}` : '';
+      process.stdout.write(`  ${slug} ${dim(age.padStart(4))}${relStr}${nextStr}\n`);
+    }
+    if (runlistHubs.length > 8) {
+      process.stdout.write(`  ${dim(`...and ${runlistHubs.length - 8} more`)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Active plan health
+  if (activePlans.length > 0) {
+    process.stdout.write(bold('Active plans:') + '\n');
+    const avgAge = activeAges.length > 0 ? Math.round(activeAges.reduce((a, b) => a + b, 0) / activeAges.length) : 0;
+    const maxAge = activeAges.length > 0 ? Math.max(...activeAges) : 0;
+    process.stdout.write(`  Count: ${activePlans.length}  Avg age: ${avgAge}d  Max age: ${maxAge}d\n`);
+    if (avgCompletion !== null) {
+      process.stdout.write(`  Avg checklist: ${Math.round(avgCompletion * 100)}%\n`);
+    }
+    for (const doc of activePlans) {
+      const age = doc.created ? Math.floor((now - new Date(doc.created).getTime()) / 86400000) : '?';
+      const slug = path.basename(doc.path, '.md').padEnd(28);
+      const pct = doc.checklist?.total > 0 ? `${Math.round(doc.checklist.completed / doc.checklist.total * 100)}%` : '-';
+      const ageColor = age > 30 ? red(age + 'd') : age > 14 ? yellow(age + 'd') : dim(age + 'd');
+      process.stdout.write(`  ${slug} ${ageColor}  checklist: ${pct}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Paused
+  if (pausedPlans.length > 0) {
+    process.stdout.write(bold('Paused:') + '\n');
+    for (const doc of pausedPlans) {
+      const slug = path.basename(doc.path, '.md').padEnd(28);
+      const age = doc.updated ? Math.floor((now - new Date(doc.updated).getTime()) / 86400000) + 'd paused' : '';
+      process.stdout.write(`  ${slug} ${dim(age)}\n`);
+    }
+    process.stdout.write('\n');
+  }
+
+  // Velocity
+  process.stdout.write(bold('Velocity (last 30d):') + '\n');
+  process.stdout.write(`  Archived: ${green(String(recentlyArchived.length))} plans\n`);
+  if (recentlyArchived.length > 0) {
+    for (const doc of recentlyArchived.slice(0, 8)) {
+      process.stdout.write(`    ${dim(path.basename(doc.path, '.md'))}\n`);
+    }
+    if (recentlyArchived.length > 8) {
+      process.stdout.write(`    ${dim(`...and ${recentlyArchived.length - 8} more`)}\n`);
+    }
+  }
+  process.stdout.write('\n');
+
+  // Blocked summary
+  if (blockedPlans.length > 0) {
+    process.stdout.write(`${bold('Blocked:')} ${blockedPlans.length} plans\n\n`);
+  }
+
+  // Ready to promote
+  if (readyPlans.length > 0) {
+    process.stdout.write(`${bold('Ready to promote:')} ${readyPlans.length} plans\n\n`);
+  }
+}

package/src/hints.mjs

@@ -0,0 +1,129 @@
+import { existsSync } from 'node:fs';
+import { readJournalEntries, isJournalEnabled, journalFilePath } from './journal.mjs';
+import { currentSessionId } from './util.mjs';
+import { readEnv } from './naming.mjs';
+
+// F17c: repeat-failure hints. When an agent runs the same broken invocation
+// twice in the same session within HINT_WINDOW_MS, the second die() output is
+// suffixed with a Tip: paragraph informed by the prior failure's recorded
+// stderr. First failures stay terse — don't punish humans typing a command
+// for the first time. The lookup is skipped cleanly when the journal is
+// disabled or RUNLIST_NO_HINTS=1, so this costs nothing for non-opt-in users.
+
+const HINT_WINDOW_MS = 10 * 60 * 1000;
+const OVERLAP_THRESHOLD = 0.75;
+
+const TEMPLATES = [
+  {
+    match: /Too many arguments|Usage:/i,
+    hint: ({ count, argv }) =>
+      `${count}× the same shape on \`${argv[0]} ${argv[1] ?? ''}\` in this session. Run \`runlist ${argv[0]} --help\` for the expected positional args.`,
+  },
+  {
+    match: /Already (consumed|archived)/i,
+    hint: ({ count, argv }) =>
+      `${count}× attempts to use a path that is already archived. Use \`runlist prompts list\` to see what is actually pending, or \`runlist next\` for the oldest live prompt.`,
+  },
+  {
+    match: /No pending prompts/i,
+    hint: ({ count }) =>
+      `${count}× \`runlist next\` with no pending prompts in the queue. Either queue one with \`runlist new prompt <slug> "..."\` or pass an explicit prompt file to \`runlist use\`.`,
+  },
+  {
+    match: /Unknown command/i,
+    hint: ({ count }) =>
+      `${count}× the same unknown command. Run \`runlist --help\` to list available commands; the dispatch already prints a did-you-mean for close misses.`,
+  },
+  {
+    match: /File not found|does not resolve/i,
+    hint: ({ count, argv }) =>
+      `${count}× pointing at a path that doesn't exist. Confirm the file with \`runlist query\` or \`runlist plans\` — paths resolve relative to repo root or doc roots, not the cwd.`,
+  },
+  {
+    match: /Unknown status|Unknown surface/i,
+    hint: ({ count }) =>
+      `${count}× rejected by the taxonomy validator. Run \`runlist statuses list\` or \`runlist surfaces\` to print the valid values for this project.`,
+  },
+];
+
+// Global value-consuming flags must be skipped together with the token that
+// follows them — otherwise `--config /tmp/foo` injects the tempdir path as
+// "positional" and dilutes Jaccard overlap below threshold. Keep this list
+// aligned with the global flag-strip list in bin/runlist.mjs (SCRUB_*).
+const VALUE_FLAGS = new Set([
+  '--config', '--root', '--type', '--limit', '--sort', '--group',
+  '--status', '--owner', '--module', '--surface', '--domain',
+  '--audience', '--execution-mode', '--updated-since',
+  '--summarize-limit', '--model',
+]);
+
+function nonFlagSet(argv) {
+  const out = new Set();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (typeof a !== 'string') continue;
+    if (a.startsWith('-')) {
+      if (VALUE_FLAGS.has(a)) i++;
+      continue;
+    }
+    out.add(a);
+  }
+  return out;
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  const aArr = [...a];
+  const inter = aArr.filter(x => b.has(x)).length;
+  const union = new Set([...a, ...b]).size;
+  return union === 0 ? 0 : inter / union;
+}
+
+// Returns a hint string (no `Tip:` prefix) or null. The caller is responsible
+// for formatting. Failures inside this function are swallowed — a malformed
+// journal must never break the error-reporting path.
+export function findRepeatFailureHint(failingArgv, config) {
+  try {
+    if (readEnv('NO_HINTS') === '1') return null;
+    if (!config) return null;
+    if (!isJournalEnabled(config)) return null;
+    if (!existsSync(journalFilePath(config))) return null;
+    if (!Array.isArray(failingArgv) || failingArgv.length === 0) return null;
+
+    const sid = currentSessionId();
+    const now = Date.now();
+    const cutoff = now - HINT_WINDOW_MS;
+    const failingShape = nonFlagSet(failingArgv);
+
+    const entries = readJournalEntries(config);
+    const matches = [];
+    for (const entry of entries) {
+      if (!entry || entry.sid !== sid) continue;
+      if (!Array.isArray(entry.argv) || entry.argv.length === 0) continue;
+      if (entry.argv[0] !== failingArgv[0]) continue;
+      if ((entry.exit ?? 0) === 0) continue;
+      const ts = new Date(entry.ts).getTime();
+      if (Number.isNaN(ts) || ts < cutoff) continue;
+      const priorShape = nonFlagSet(entry.argv);
+      if (jaccard(failingShape, priorShape) < OVERLAP_THRESHOLD) continue;
+      matches.push({ entry, ts });
+    }
+
+    if (matches.length === 0) return null;
+    matches.sort((a, b) => b.ts - a.ts);
+    const last = matches[0].entry;
+    const count = matches.length + 1;
+    const prevErr = last.err ?? '';
+    const ageMin = Math.max(1, Math.round((now - matches[0].ts) / 60000));
+
+    for (const tmpl of TEMPLATES) {
+      if (tmpl.match.test(prevErr)) {
+        return tmpl.hint({ count, argv: failingArgv, prev: last, ageMin });
+      }
+    }
+
+    return `${count}× the same failing shape on \`${failingArgv[0]}\` in this session (last attempt ${ageMin}m ago). Check the args — \`runlist ${failingArgv[0]} --help\` shows what's expected.`;
+  } catch {
+    return null;
+  }
+}