fapony 0.3.0 → 0.3.4

package/src/mem/commands/plan.ts

@@ -2,8 +2,9 @@
 // rationale: moving by hand = chasing relative links yourself (in the file + files that link to it) → the step gets skipped often
 // no arg = report only (safe, shows every kickoff/stale run)
 // <file.md> = check a single file, is it ready to move
-// <file.md> --apply = git mv + fix markdown links inside the file + fix inbound links from other files in plan/
-//                      + warn about plain-text mentions (detect-only, no auto-fix)
+// <file.md> --apply = git mv + fix markdown links inside the file + fix inbound links from every .md under .fapony/
+//                      (plan/ + done/ + spec/) + warn about plain-text mentions (detect-only, no auto-fix)
+//                      + warn about tracked files outside .fapony/ that mention the filename (detect-only)
 
 import {
   existsSync,
@@ -12,10 +13,20 @@ import {
   readFileSync,
   writeFileSync,
 } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 
 import { openRows } from "../selectors.js";
-import { doneDir, memCmd, nextId, planDir, put, rel, rows } from "../store.js";
+import {
+  doneDir,
+  memCmd,
+  nextId,
+  planBase,
+  planDir,
+  put,
+  rel,
+  root,
+  rows,
+} from "../store.js";
 
 const SHIPPED = /^>\s*✅/m;
 const FRONT = /^---\r?\n([\s\S]*?)\r?\n---/;
@@ -52,6 +63,11 @@ const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 // the file moved dir (same content) — an old markdown link meant the old path relative to oldDir, must re-relativize via newDir
 // resolve from newDir (where the file is now) — if the target also moved to the same dir → plain filename,
 // if the target stayed in oldDir → ../target (both correct)
+//
+// Runs on EVERY move, including the standard sibling layout (plan/ → done/ beside
+// it): same depth is not the same directory, so a sibling link like
+// [other](PLAN-other.md) breaks unless rewritten to ../plan/PLAN-other.md.
+// Skipping this pass left exactly that dangling (mtjn3ldk).
 // pass 1 only — fix only [text](target) markdown links, do not touch plain text
 export const rewriteMovedFileLinks = (
   file: string,
@@ -65,11 +81,17 @@ export const rewriteMovedFileLinks = (
     const [target, anchor] = t.split("#");
     if (!target || /^(https?:|mailto:|\/)/.test(target)) return m;
     // resolve from where the file IS now (newDir); if target doesn't exist
-    // there, fall back to oldDir (target stayed in original location)
+    // there, fall back to oldDir (target stayed in original location).
+    // If it exists in neither, the link is already broken — leave it for
+    // plan-check instead of fabricating a new broken path.
     const inNew = resolve(newDir, target);
-    const abs = existsSync(inNew) ? inNew : resolve(oldDir, target);
+    const inOld = resolve(oldDir, target);
+    const abs = existsSync(inNew) ? inNew : existsSync(inOld) ? inOld : null;
+    if (!abs) return m;
+    const next = `](${relative(newDir, abs) || "."}${anchor ? `#${anchor}` : ""})`;
+    if (next === m) return m;
     n++;
-    return `](${relative(newDir, abs) || "."}${anchor ? `#${anchor}` : ""})`;
+    return next;
   });
 
   if (n) writeFileSync(file, out);
@@ -172,11 +194,20 @@ export const cmdPlanSweep = (a: string[]) => {
     return;
   }
 
-  const src = join(dir, target);
-  if (!existsSync(src)) {
-    console.error(`${rel(src)} not found`);
+  // target arrives as a bare name (PLAN-x.md, the SKILL form) or a repo-relative
+  // path (.fapony/plan/PLAN-x.md, the example form) — both must resolve, so try
+  // planDir first, then the repo root, then the bare basename as a last resort.
+  const src = [
+    join(dir, target),
+    join(root, target),
+    join(dir, basename(target)),
+  ].find((p) => existsSync(p));
+  if (!src) {
+    console.error(`${target} not found (looked in ${rel(dir)}/ and repo root)`);
     process.exit(1);
   }
+  const name = basename(src);
+  const srcDir = dirname(src);
   const shipped = hasShippedHeader(src);
   if (!apply) {
     console.log(
@@ -191,21 +222,21 @@ export const cmdPlanSweep = (a: string[]) => {
   // but then run --apply directly and skip everything → risky when an agent ships automatically with no human check, so hard block
   if (!shipped && !process.env.MEM_FORCE) {
     console.error(
-      `${target}: no ✅ shipped header at the top — refusing to move (MEM_FORCE=1 to override)`,
+      `${name}: no ✅ shipped header at the top — refusing to move (MEM_FORCE=1 to override)`,
     );
     process.exit(1);
   }
-  const openSpec = `${rel(dir)}/${target}`;
+  const openSpec = rel(src);
   const openN = openRows(rows()).filter((r) => r.spec === openSpec);
   if (openN.length && !process.env.MEM_FORCE) {
     console.error(
-      `${target}: still has ${openN.length} open row(s) (next/bug/hold/decision/note) — close them or move the spec first (MEM_FORCE=1 to override):\n` +
+      `${name}: still has ${openN.length} open row(s) (next/bug/hold/decision/note) — close them or move the spec first (MEM_FORCE=1 to override):\n` +
         openN.map((r) => `  [${r.id}] ${r.kind} ${r.text}`).join("\n"),
     );
     process.exit(1);
   }
 
-  const dst = join(doneDir, target);
+  const dst = join(doneDir, name);
   if (existsSync(dst)) {
     console.error(`${rel(dst)} already exists`);
     process.exit(1);
@@ -221,14 +252,17 @@ export const cmdPlanSweep = (a: string[]) => {
     process.exit(1);
   }
 
-  // done/ is a sibling of plan/ = same depth, links in the file still resolve, no need to touch
-  // the old layout (plan/done/) is one level deeper, so it does need re-relativizing
-  const nested = dirname(doneDir) !== dirname(dir);
-  const ownLinks = nested ? rewriteMovedFileLinks(dst, dir, doneDir) : 0;
+  // own links always need re-relativizing — the file changed directory even in
+  // the sibling layout (plan/ → done/ beside it), so sibling links dangle
+  // unless rewritten (see rewriteMovedFileLinks).
+  const ownLinks = rewriteMovedFileLinks(dst, srcDir, doneDir);
 
+  // inbound: every .md under .fapony/ can link here — other active plans,
+  // shipped plans in done/ (they reference each other), and specs. Scanning
+  // plan/ only left done/+spec/ links dangling (mtl15q4y).
   let inbound = 0;
   let inboundFiles = 0;
-  for (const f of mdFiles(dir)) {
+  for (const f of mdFiles(planBase)) {
     if (f === dst) continue;
     const n = rewriteMarkdownLinks(f, src, dst);
     if (n) {
@@ -238,13 +272,9 @@ export const cmdPlanSweep = (a: string[]) => {
   }
 
   console.log(`moved ${rel(src)} → ${rel(dst)}`);
+  console.log(`links rewritten inside the file: ${ownLinks}`);
   console.log(
-    nested
-      ? `links rewritten inside the file: ${ownLinks}`
-      : `links rewritten inside the file: 0 (same depth, existing links still resolve)`,
-  );
-  console.log(
-    `inbound links rewritten: ${inbound} in ${inboundFiles} file(s) (scanned ${rel(dir)}/** only)`,
+    `inbound links rewritten: ${inbound} in ${inboundFiles} file(s) (scanned ${rel(planBase)}/**)`,
   );
 
   // log decision — record ship event (reuse existing kind, no new schema)
@@ -252,7 +282,7 @@ export const cmdPlanSweep = (a: string[]) => {
   put({
     id: nextId(rows()),
     kind: "decision",
-    text: `${target} shipped → ${rel(dst)}`,
+    text: `${name} shipped → ${rel(dst)}`,
     spec: doneSpec,
   });
   // ponytail: this decision *is* the move itself, nothing to write back into the spec — do not mark synced
@@ -262,35 +292,33 @@ export const cmdPlanSweep = (a: string[]) => {
   // plain-text mention detection (detect-only, no auto-fix)
   let plainTextTotal = 0;
   const plainTextFiles: string[] = [];
-  for (const f of mdFiles(dir)) {
-    const n = countPlainTextMentions(f, target);
+  for (const f of mdFiles(planBase)) {
+    if (f === dst) continue;
+    const n = countPlainTextMentions(f, name);
     if (n) {
       plainTextTotal += n;
-      plainTextFiles.push(f.replace(`${dir}/`, ""));
+      plainTextFiles.push(f.replace(`${planBase}/`, ""));
     }
   }
   if (plainTextTotal > 0) {
     console.log(
-      `⚠ ${plainTextTotal} plain-text mention(s) in ${plainTextFiles.length} file(s) under ${rel(dir)}/ — grep and update the paths yourself:\n${plainTextFiles.join("\n")}`,
+      `⚠ ${plainTextTotal} plain-text mention(s) in ${plainTextFiles.length} file(s) under ${rel(planBase)}/ — grep and update the paths yourself:\n${plainTextFiles.join("\n")}`,
     );
   }
 
-  // files outside plan/ that mention the target — detect-only
-  const grep = Bun.spawnSync([
-    "git",
-    "grep",
-    "-l",
-    target,
-    "--",
-    // the "files outside plan/" scope = the folder plan/ lives under (apps/vela, .fapony, …)
-    rel(dirname(planDir)),
-    `:!${rel(dir)}`,
-  ])
+  // files outside .fapony/ that mention the filename — detect-only.
+  // Everything under planBase/ was auto-fixed above, so what remains is repo
+  // docs and prose (README, docs/, CLAUDE.md) with hand-written paths.
+  // cwd: root — the pathspecs are root-relative no matter where fapony runs from.
+  const grep = Bun.spawnSync(
+    ["git", "grep", "-l", name, "--", ".", `:!${rel(planBase)}`],
+    { cwd: root },
+  )
     .stdout.toString()
     .trim();
   if (grep)
     console.log(
-      `⚠ files outside ${rel(dir)}/ still mention "${target}" — check them yourself (not auto-fixed):\n${grep}`,
+      `⚠ files outside ${rel(planBase)}/ still mention "${name}" — check them yourself (not auto-fixed):\n${grep}`,
     );
 };
 

package/src/mem/commands/read.ts

@@ -3,13 +3,28 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { baselinePath, readEvidenceLintCmd } from "../../lint-baseline.js";
-import { doneLines, fmtClose, fmtRow, printOpenRows } from "../render.js";
+import { doneLines, fmtClose, fmtRow } from "../render.js";
 import { claimsOf, openRows, staleReport } from "../selectors.js";
 import type { CloseRow, WorkRow } from "../store.js";
 import { allRows, app, memCmd, planDir, root, rows } from "../store.js";
 import { planSweepCmd, shippedNotMoved } from "./plan.js";
 import { THRESHOLD } from "./rotate.js";
 
+/** Files changed on this branch vs dev — empty set when dev is missing or diff fails. */
+function getBranchDiffFiles(cwd: string): Set<string> {
+  try {
+    const p = Bun.spawnSync(["git", "diff", "--name-only", "dev...HEAD"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (p.exitCode !== 0) return new Set();
+    return new Set(p.stdout.toString().trim().split("\n").filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
 const rotateLine = (n: number) =>
   n >= THRESHOLD
     ? `\n## 🗜 log ${n} rows (≥ ${THRESHOLD}) — run: ${memCmd} rotate --apply`
@@ -24,26 +39,20 @@ const planSweepLine = () => {
     : "";
 };
 
-export const cmdNow = () => {
-  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
-  const all = rows();
-  console.log(`# ${app} — ${all.length} entries`);
-  printOpenRows(all, { showHold: true });
-  const decisionN = openRows(all).filter((r) => r.kind === "decision").length;
-  const noteN = openRows(all).filter((r) => r.kind === "note").length;
-  console.log(
-    `\n## decision ${decisionN} · note ${noteN} — search: ${memCmd} find <word>`,
-  );
-  const stale = staleReport(all);
-  if (stale.length)
-    console.log(
-      `\n## ⚠ stale (${stale.length})\n` +
-        stale.map((l) => `- ${l}`).join("\n"),
-    );
-  const sweep = planSweepLine();
-  if (sweep) console.log(sweep);
-  const rotate = rotateLine(all.length);
-  if (rotate) console.log(rotate);
+// Row-list caps: no row-list section exceeds 10 (same budget as ## recent,
+// which takes doneLines(all, 10)). Per-row text is cut at a word boundary —
+// a kickoff line points at the row (mem find has the full text), it must not
+// reprint it.
+const BUGS_LIMIT = 10;
+const BRANCH_LIMIT = 10;
+const RECENT_OPEN_LIMIT = 10;
+const RECENT_OPEN_TEXT = 160;
+
+const shortText = (text: string, max = RECENT_OPEN_TEXT): string => {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const lastSpace = cut.lastIndexOf(" ");
+  return `${lastSpace > max / 2 ? cut.slice(0, lastSpace) : cut}…`;
 };
 
 export const cmdDone = () => {
@@ -235,118 +244,12 @@ export const cmdKickoff = (a: string[]) => {
     }
   }
 
-  // --- main output (unchanged behavior) ---
-
-  if (!arg && !planFile) {
-    // no args = now + a "recent" section = the last 10 closes
-    console.log(`# ${app} — ${all.length} entries`);
-    printOpenRows(all, { showHold: true });
-    console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
-    const stale = staleReport(all);
-    if (stale.length)
-      console.log(
-        `\n## ⚠ stale (${stale.length})\n` +
-          stale.map((l) => `- ${l}`).join("\n"),
-      );
-    const sweep = planSweepLine();
-    if (sweep) console.log(sweep);
-    const rotate = rotateLine(all.length);
-    if (rotate) console.log(rotate);
-  } else if (resolvedSpec) {
-    // spec.md = a brief for that spec
-    const open = openRows(all);
-    const specRows = open.filter((r) => r.spec === resolvedSpec);
-    const specDecisions = all
-      .filter(
-        (r): r is WorkRow => r.kind === "decision" && r.spec === resolvedSpec,
-      )
-      .slice(-5);
-    const specCloses = all
-      .filter((r): r is CloseRow => r.kind === "close")
-      .filter((r) => byId.get(r.ref)?.spec === resolvedSpec)
-      .slice(-3);
-
-    console.log(`# ${resolvedSpec} — ${specRows.length} open rows`);
-    if (specRows.length) {
-      console.log(`\n## open\n${specRows.map((r) => fmtRow(r)).join("\n")}`);
-    }
-    if (specDecisions.length) {
-      console.log(
-        `\n## decisions\n` +
-          specDecisions
-            .map((r) => `- ${r.ts.slice(0, 10)} ${r.text}`)
-            .join("\n"),
-      );
-    }
-    if (specCloses.length) {
-      console.log(
-        `\n## closes\n${specCloses.map((c) => fmtClose(c, byId)).join("\n")}`,
-      );
-    }
-    if (!specRows.length && !specDecisions.length && !specCloses.length) {
-      console.log("(no entries for this spec)");
-    }
-  } else if (target) {
-    // id = a brief for that task
-    const claims = claimsOf(all);
-    const claimInfo = claims.has(arg)
-      ? `\nClaimed by: ${claims.get(arg)?.agent} (${claims.get(arg)?.ts.slice(0, 10)})`
-      : "";
-
-    const spec = target.spec;
-    const open = spec
-      ? openRows(all).filter((r) => r.spec === spec && r.id !== arg)
-      : [];
-    const specDecisions = spec
-      ? all
-          .filter((r): r is WorkRow => r.kind === "decision" && r.spec === spec)
-          .slice(-5)
-      : [];
-    const specNotes = spec
-      ? all
-          .filter((r): r is WorkRow => r.kind === "note" && r.spec === spec)
-          .slice(-5)
-      : [];
-    const specCloses = spec
-      ? all
-          .filter((r): r is CloseRow => r.kind === "close")
-          .filter((r) => byId.get(r.ref)?.spec === spec)
-          .slice(-3)
-      : [];
-
-    console.log(
-      `# [${target.id}] ${target.kind} — ${target.text}${target.spec ? ` → ${target.spec}` : ""}${claimInfo}`,
-    );
-    if (open.length) {
-      console.log(
-        `\n## open (same spec)\n` +
-          open.map((r) => fmtRow(r, claims)).join("\n"),
-      );
-    }
-    if (specDecisions.length || specNotes.length) {
-      console.log(`\n## decisions & notes (spec)\n`);
-      for (const r of [...specDecisions, ...specNotes]) {
-        console.log(`- ${r.ts.slice(0, 10)} ${r.kind} ${r.text}`);
-      }
-    }
-    if (specCloses.length) {
-      console.log(
-        `\n## closes (spec)\n` +
-          specCloses.map((c) => fmtClose(c, byId)).join("\n"),
-      );
-    }
-  } else if (arg) {
-    console.error(`no id "${arg}" in the log`);
-    process.exit(1);
-  }
-
-  // --- next up section (chunk 3) ---
+  // --- suggestions (generated early so the no-args path can print next up
+  //     before the recency tier, keeping it inside the 4KB cap) ---
 
-  // A suggestion may carry a fully-runnable command. `manual` marks a command
-  // that is a template with a placeholder (bug close) — show it, never auto-run it.
   type Suggestion = { text: string; run?: string; manual?: boolean };
   const suggestions: Suggestion[] = [];
-  const GROUP_CAP = 3; // SPEC §3: at most 3 groups, at most 3 lines each
+  const GROUP_CAP = 3;
 
   const truncate = (s: string, n = 80) =>
     s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
@@ -358,7 +261,6 @@ export const cmdKickoff = (a: string[]) => {
     for (const file of files) {
       if (planLines.length >= GROUP_CAP) break;
       const fullPath = join(planDir, file);
-      // Skip the plan we already showed
       if (planFile && fullPath === planFile) continue;
       if (hasHighPriority(fullPath)) {
         const title = readPlanTitle(fullPath);
@@ -369,19 +271,16 @@ export const cmdKickoff = (a: string[]) => {
       }
     }
   }
-  // Only the first unchecked chunk (SPEC §3) — the body of the plan is the plan's job.
-  // There is no per-chunk command, so this line is context, not a runnable item.
   if (planLines.length < GROUP_CAP && planCheckboxes.length) {
     const planName = planFile ? basename(planFile) : "plan";
     planLines.push({ text: `${planCheckboxes[0]} (${planName})` });
   }
   suggestions.push(...planLines);
 
-  // group 2 — open bugs, oldest first. openRows excludes tombstoned refs; the
-  // old bug filter forgot that and offered already-closed bugs as work.
-  const claims = claimsOf(all);
+  // group 2 — open bugs, oldest first
+  const suggClaims = claimsOf(all);
   const openBugs = openRows(all)
-    .filter((r) => r.kind === "bug" && !claims.has(r.id))
+    .filter((r) => r.kind === "bug" && !suggClaims.has(r.id))
     .slice(0, GROUP_CAP);
   for (const b of openBugs) {
     suggestions.push({
@@ -407,11 +306,7 @@ export const cmdKickoff = (a: string[]) => {
     });
   }
 
-  // group 4 — the lint baseline. "Is this red mine or was it already red" is
-  // already answered by `lint-baseline`, but only if it was captured before
-  // the work started — and nobody remembers at session open, which is what
-  // kickoff is. Only offered when the repo declared a lint command; without
-  // one the capture would just fail.
+  // group 4 — the lint baseline
   try {
     if (readEvidenceLintCmd(root) && !existsSync(baselinePath(root))) {
       suggestions.push({
@@ -423,15 +318,14 @@ export const cmdKickoff = (a: string[]) => {
     // state dir unreadable — the baseline line is a convenience, never a gate
   }
 
-  // Print and optionally execute. Only a suggestion with a complete command is
-  // runnable — a plan item is context, a bug's close is a template needing a message.
-  if (suggestions.length) {
+  /** Print ## next up and handle --pick. */
+  const printNextUp = () => {
+    if (!suggestions.length) return;
     console.log(`\n## next up`);
     for (let i = 0; i < suggestions.length; i++) {
       console.log(`  [${i + 1}] ${suggestions[i].text}`);
       if (suggestions[i].run) console.log(`      → ${suggestions[i].run}`);
     }
-
     if (pickIdx !== null) {
       if (pickIdx > suggestions.length) {
         console.error(
@@ -461,5 +355,184 @@ export const cmdKickoff = (a: string[]) => {
         process.exit(1);
       }
     }
+  };
+
+  // --- main output ---
+
+  // Deferred output for the no-args path — recent closes, plan sweep, rotate
+  let kickoffExtras: (() => void) | null = null;
+
+  if (!arg && !planFile) {
+    // no args = ranked open rows + next up + recent closes
+    console.log(`# ${app} — ${all.length} entries`);
+
+    const open = openRows(all);
+    const claims = claimsOf(all);
+    const diffFiles = getBranchDiffFiles(root);
+
+    // Tier 1: unclaimed bugs (always first, no matter how old) — capped: a
+    // backlog of unclosable bugs must not push the rest of the ranking out.
+    const bugs = open.filter((r) => r.kind === "bug" && !claims.has(r.id));
+    if (bugs.length) {
+      console.log(`\n## bugs`);
+      for (const r of bugs.slice(0, BUGS_LIMIT)) console.log(fmtRow(r));
+      if (bugs.length > BUGS_LIMIT)
+        console.log(
+          `… +${bugs.length - BUGS_LIMIT} more unclosed bugs — \`fapony mem find <word>\` for the rest`,
+        );
+    }
+
+    // next up BEFORE the branch/recency tiers so no row-list section can
+    // push it out — order is by actionability, never by "this tier is short".
+    printNextUp();
+
+    // Tier 2: rows whose files[] overlap with git diff --name-only dev...HEAD
+    // — capped like every other row-list section (≤10 + overflow, pointer
+    // lines via shortText): the branch diff is unbounded and mem clusters on
+    // files every real branch touches, so uncapped this reprints the log.
+    const bugIds = new Set(bugs.map((r) => r.id));
+    const diffMatched = open.filter((r) => {
+      if (bugIds.has(r.id)) return false;
+      if (diffFiles.size === 0) return false;
+      return (r.files ?? []).some((f) => diffFiles.has(f));
+    });
+    if (diffMatched.length) {
+      console.log(`\n## on this branch`);
+      for (const r of diffMatched.slice(0, BRANCH_LIMIT))
+        console.log(fmtRow({ ...r, text: shortText(r.text) }, claims));
+      if (diffMatched.length > BRANCH_LIMIT)
+        console.log(
+          `… +${diffMatched.length - BRANCH_LIMIT} more — \`fapony mem find <word>\` for the rest`,
+        );
+    }
+
+    // Tier 3: rest by recency (newest first) — tie-breaker only, capped like
+    // ## recent (doneLines takes 10): decision/note can never close, so an
+    // uncapped tier reprints the whole log. Lines are pointers, not prose —
+    // cut at a word boundary and point at mem find for the rest.
+    const shown = new Set([...bugIds, ...diffMatched.map((r) => r.id)]);
+    const rest = open
+      .filter((r) => !shown.has(r.id))
+      .sort((a, b) => b.ts.localeCompare(a.ts));
+    if (rest.length) {
+      console.log(`\n## recent open`);
+      for (const r of rest.slice(0, RECENT_OPEN_LIMIT))
+        console.log(fmtRow({ ...r, text: shortText(r.text) }, claims));
+      if (rest.length > RECENT_OPEN_LIMIT)
+        console.log(
+          `… +${rest.length - RECENT_OPEN_LIMIT} more — \`fapony mem find <word>\` for the rest`,
+        );
+    }
+
+    // recent closes, plan sweep, rotate — after next up
+    kickoffExtras = () => {
+      console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
+      const sweep = planSweepLine();
+      if (sweep) console.log(sweep);
+      const rotate = rotateLine(all.length);
+      if (rotate) console.log(rotate);
+    };
+  } else if (resolvedSpec) {
+    // spec.md = a brief for that spec
+    const open = openRows(all);
+    const specRows = open.filter((r) => r.spec === resolvedSpec);
+    const specDecisions = all
+      .filter(
+        (r): r is WorkRow => r.kind === "decision" && r.spec === resolvedSpec,
+      )
+      .slice(-5);
+    const specCloses = all
+      .filter((r): r is CloseRow => r.kind === "close")
+      .filter((r) => byId.get(r.ref)?.spec === resolvedSpec)
+      .slice(-3);
+
+    console.log(`# ${resolvedSpec} — ${specRows.length} open rows`);
+    if (specRows.length) {
+      console.log(`\n## open\n${specRows.map((r) => fmtRow(r)).join("\n")}`);
+    }
+    if (specDecisions.length) {
+      console.log(
+        `\n## decisions\n` +
+          specDecisions
+            .map((r) => `- ${r.ts.slice(0, 10)} ${r.text}`)
+            .join("\n"),
+      );
+    }
+    if (specCloses.length) {
+      console.log(
+        `\n## closes\n${specCloses.map((c) => fmtClose(c, byId)).join("\n")}`,
+      );
+    }
+    if (!specRows.length && !specDecisions.length && !specCloses.length) {
+      console.log("(no entries for this spec)");
+    }
+  } else if (target) {
+    // id = a brief for that task
+    const claims = claimsOf(all);
+    const claimInfo = claims.has(arg)
+      ? `\nClaimed by: ${claims.get(arg)?.agent} (${claims.get(arg)?.ts.slice(0, 10)})`
+      : "";
+
+    const spec = target.spec;
+    const open = spec
+      ? openRows(all).filter((r) => r.spec === spec && r.id !== arg)
+      : [];
+    const specDecisions = spec
+      ? all
+          .filter((r): r is WorkRow => r.kind === "decision" && r.spec === spec)
+          .slice(-5)
+      : [];
+    const specNotes = spec
+      ? all
+          .filter((r): r is WorkRow => r.kind === "note" && r.spec === spec)
+          .slice(-5)
+      : [];
+    const specCloses = spec
+      ? all
+          .filter((r): r is CloseRow => r.kind === "close")
+          .filter((r) => byId.get(r.ref)?.spec === spec)
+          .slice(-3)
+      : [];
+
+    console.log(
+      `# [${target.id}] ${target.kind} — ${target.text}${target.spec ? ` → ${target.spec}` : ""}${claimInfo}`,
+    );
+    if (open.length) {
+      console.log(
+        `\n## open (same spec)\n` +
+          open.map((r) => fmtRow(r, claims)).join("\n"),
+      );
+    }
+    if (specDecisions.length || specNotes.length) {
+      console.log(`\n## decisions & notes (spec)\n`);
+      for (const r of [...specDecisions, ...specNotes]) {
+        console.log(`- ${r.ts.slice(0, 10)} ${r.kind} ${r.text}`);
+      }
+    }
+    if (specCloses.length) {
+      console.log(
+        `\n## closes (spec)\n` +
+          specCloses.map((c) => fmtClose(c, byId)).join("\n"),
+      );
+    }
+  } else if (planFile) {
+    const title = readPlanTitle(planFile);
+    console.log(`# ${title || basename(planFile)} — plan`);
+    if (planCheckboxes.length) {
+      console.log(
+        `\n## unchecked\n${planCheckboxes.map((c) => `- [ ] ${c}`).join("\n")}`,
+      );
+    } else {
+      console.log(`\n(all chunks checked — ready to ship or archive)`);
+    }
+  } else if (arg) {
+    console.error(`no id "${arg}" in the log`);
+    process.exit(1);
   }
+
+  // For non-no-args paths, print next up at the end
+  if (arg || planFile) printNextUp();
+
+  // Deferred output from no-args path (recent closes, plan sweep, rotate)
+  kickoffExtras?.();
 };