fapony 0.3.4 → 0.3.5

package/README.md

@@ -476,6 +476,13 @@ fapony mem where                           # show the resolved mem dir and which
 fapony mem done | stale              # views
 fapony debt [--id <convention>] [--where <path>]   # ไฟล์ไหนยังไม่ย้ายไป convention ที่ประกาศไว้ (live, read-only)
 fapony lint-baseline [--cmd ...] [--diff]  # separate "already red" from "I made it red"
+
+# Hooks (wired by `fapony install`, not run by hand)
+fapony hook-stop                        # Stop hook: block turns with commits but no mem row
+fapony hook-read-hint                   # read/re-read annotations
+fapony hook-edit-hint                   # importer count before editing shape
+fapony hook-mv-guard                    # deny raw git mv of plan files into done/
+fapony hook-session-start               # SessionStart: kickoff into context
 ```
 
 *When* to call `mem add` is your project's call, not fapony's — write it in your own
@@ -501,7 +508,6 @@ fapony install --dry-run                  # show what would happen without writi
 fapony setup                             # interactive wizard: config + scaffold in one step
 fapony update                            # self-update via git pull
 fapony telemetry show|send               # opt-in only, default off — see https://github.com/kire21b/fapony/blob/main/TELEMETRY.md
-fapony test                              # self-check
 ```
 
 ## Config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
@@ -29,11 +29,10 @@
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
-    "test": "bun fapony.ts test",
-    "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
-    "test:one": "bun scripts/test-one.ts",
+    "test": "bun test --timeout 20000 --parallel",
+    "test:changed": "bun test --timeout 20000 --changed",
     "knip": "bunx knip@6 --exclude types,nsTypes || true",
-    "check": "bun run lint && bun run typecheck && bun fapony.ts test",
+    "check": "bun run lint && bun run typecheck && bun test --timeout 20000 --parallel",
     "prepublishOnly": "bash scripts/smoke-publish.sh",
     "release": "git checkout main && git pull --ff-only && npm version patch -m 'release v%s' && git push origin main --follow-tags",
     "overview": "bun fapony.ts report-web /tmp/fapony-overview.html && open /tmp/fapony-overview.html"

package/src/adapters/cli.ts

@@ -6,13 +6,14 @@
 
 import { existsSync } from "node:fs";
 import { cmdAnalyze } from "../analyze.js";
+import { renderUsage, suggestCommand } from "../commands.js";
 import { cmdDebt } from "../debt/cli.js";
 import { cmdDigest } from "../digest/cli.js";
 import { cmdInit } from "../init.js";
 import { cmdInitMem } from "../init-mem.js";
 import { cmdInstall } from "../install.js";
 import { cmdLintBaseline } from "../lint-baseline.js";
-import { cmdMem } from "../mem/index.js";
+import { cmdMem, MEM_SUBCOMMANDS } from "../mem/index.js";
 import { initStore } from "../mem/store.js";
 import { cmdPriceScan } from "../price/index.js";
 import { cmdReport, cmdReportWeb } from "../report/index.js";
@@ -35,6 +36,11 @@ import { cmdMcp } from "./mcp/transport.js";
 export async function cliMain(): Promise<void> {
   const [cmd, ...a] = process.argv.slice(2);
 
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    console.log(renderUsage());
+    return;
+  }
+
   if (cmd === "analyze") {
     cmdAnalyze(a);
   } else if (cmd === "debt") {
@@ -110,14 +116,13 @@ export async function cliMain(): Promise<void> {
     await cmdPriceScan(a);
   } else if (cmd === "usage-web") {
     cmdUsageWeb(a);
-  } else if (cmd === "test") {
-    const { cmdTest } = await import("../test.js");
-    await cmdTest();
   } else {
     console.error(`fapony: unknown command "${cmd ?? ""}"`);
-    console.error(
-      "usage: fapony <setup|update|stats|telemetry|init|init-mem|mem|install|report|report-web|usage-scan|usage-web|price-scan|analyze|debt|lint-baseline|plan-seed|review-seed|digest|mcp|hook-stop|hook-read-hint|hook-edit-hint|hook-mv-guard|hook-session-start|test> [args]",
-    );
+    const hints = suggestCommand(cmd ?? "", MEM_SUBCOMMANDS);
+    if (hints.length > 0) {
+      console.error(`did you mean ${hints.map((h) => `"${h}"`).join(" or ")}?`);
+    }
+    console.error(`usage: fapony <command> [args] — see "fapony --help"`);
     process.exit(1);
   }
 }

package/src/adapters/hooks/index.ts

@@ -64,6 +64,7 @@ export {
   sessionStartContext,
 } from "./session-start.js";
 export {
+  bugSignalFromTranscript,
   cmdHookStop,
   cursorTranscriptPath,
   decideStop,

package/src/adapters/hooks/stop.ts

@@ -120,7 +120,8 @@ export function normalizeStopInput(
 
 /**
  * Pure decision: block when this session produced commits but no mem row
- * newer than session start exists.
+ * newer than session start exists, or when the agent announced a bug but
+ * filed no kind:bug row.
  */
 export function decideStop(opts: {
   stopHookActive: boolean;
@@ -130,9 +131,23 @@ export function decideStop(opts: {
   commitList?: string[];
   memLastTs?: string | null;
   memCandidates?: string[];
+  bugSignal?: string | null;
+  bugRowSinceStart?: boolean;
 }): string | null {
   if (opts.stopHookActive) return null;
   if (!opts.worktree) return null;
+
+  // --- Bug-signal block (independent of commits) ---
+  if (opts.bugSignal && !opts.bugRowSinceStart) {
+    return [
+      `This turn reported a bug ("${opts.bugSignal}") but no mem row with kind:bug exists for this session.`,
+      `A bug described in chat is lost when the room closes — a decision row does not surface it.`,
+      `  fapony mem add bug "<what is broken>" --files <files>`,
+      `Already filed elsewhere, or not a bug? End the turn again — this fires once per session.`,
+    ].join("\n");
+  }
+
+  // --- Commit block (original) ---
   if (opts.commits < 1) return null;
   if (!opts.memLastTs && !opts.memCandidates?.length) return null;
   if (opts.since && opts.memLastTs) {
@@ -164,6 +179,11 @@ export function decideStop(opts: {
       `${opts.worktree}/.fapony/plan/PLAN.md (or the relevant plan). ` +
       `files[] is required — a row without it is unfindable when you touch that file next session.`,
   );
+  if (opts.bugSignal) {
+    lines.push(
+      `This turn announced a bug ("${opts.bugSignal}") — use kind:bug, not decision.`,
+    );
+  }
   return lines.join("\n");
 }
 
@@ -182,6 +202,7 @@ const STOP_BLOCK_DIR = "stop-block";
 interface StopBlockRow {
   ts: string;
   worktree: string;
+  kind?: string;
 }
 
 /** Absolute path of a session's block log — may not exist. */
@@ -192,12 +213,16 @@ export function stopBlockPath(session: string): string {
 }
 
 /**
- * True when this session already blocked for this worktree — the caller then
- * lets the turn end. Records the block when it has not.
+ * True when this session already blocked for this worktree + kind — the caller
+ * then lets the turn end. Records the block when it has not.
+ *
+ * `kind` defaults to `"commit"` for backwards compatibility. Bug blocks use
+ * `"bug"` so they don't consume the commit block's quota.
  */
 export function stopBlockedBefore(
   session: string | null,
   worktree: string,
+  kind: string = "commit",
 ): boolean {
   if (!session) return false;
   const path = stopBlockPath(session);
@@ -206,7 +231,8 @@ export function stopBlockedBefore(
       for (const line of readFileSync(path, "utf-8").split("\n")) {
         if (!line) continue;
         try {
-          if ((JSON.parse(line) as StopBlockRow).worktree === worktree) {
+          const row = JSON.parse(line) as StopBlockRow;
+          if (row.worktree === worktree && (row.kind ?? "commit") === kind) {
             return true;
           }
         } catch {
@@ -216,7 +242,7 @@ export function stopBlockedBefore(
     }
     const dir = join(path, "..");
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    const row: StopBlockRow = { ts: new Date().toISOString(), worktree };
+    const row: StopBlockRow = { ts: new Date().toISOString(), worktree, kind };
     appendFileSync(path, `${JSON.stringify(row)}\n`, "utf-8");
   } catch {
     return false;
@@ -224,6 +250,96 @@ export function stopBlockedBefore(
   return false;
 }
 
+// --- Bug-signal detection ---
+
+/** Announcement words that indicate the agent found a bug — not symptom words. */
+const BUG_MARKERS: RegExp[] = [/เจอบั๊ก/];
+
+/**
+ * Scan assistant text from a Claude transcript for bug markers. Reads only
+ * the tail of the file (last 200KB) to avoid parsing the full transcript.
+ * Returns the first matched marker word, or null.
+ */
+export function bugSignalFromTranscript(
+  transcriptPath: string,
+  sinceMs: number,
+): string | null {
+  try {
+    const stat = statSync(transcriptPath);
+    // Cap at 10MB — hook must not stall turn-end
+    if (stat.size > 10 * 1024 * 1024) return null;
+
+    // Read tail to avoid parsing the full transcript
+    const tailBytes = Math.min(stat.size, 200 * 1024);
+    const fd = require("node:fs").openSync(transcriptPath, "r");
+    const buf = Buffer.alloc(tailBytes);
+    require("node:fs").readSync(
+      fd,
+      buf,
+      0,
+      tailBytes,
+      Math.max(0, stat.size - tailBytes),
+    );
+    require("node:fs").closeSync(fd);
+
+    const tail = buf.toString("utf-8");
+    // When reading from the middle of a large file, the first line is partial
+    const readingMidFile = tailBytes < stat.size;
+    const startIdx = readingMidFile ? tail.indexOf("\n") : -1;
+    const lines =
+      startIdx >= 0 ? tail.slice(startIdx + 1).split("\n") : tail.split("\n");
+
+    for (const line of lines) {
+      if (!line) continue;
+      // Transcript tail: untyped JSONL — the structural type below names only
+      // the fields this scan reads (biome noExplicitAny: no `any` annotation).
+      let o: {
+        message?: {
+          role?: string;
+          content?: Array<{ type?: string; text?: string }>;
+          created_at?: string;
+        };
+      };
+      try {
+        o = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const m = o.message;
+      if (m?.role !== "assistant" || !Array.isArray(m.content)) continue;
+      // Skip messages older than session start
+      if (m.created_at) {
+        const msgMs = new Date(m.created_at).getTime();
+        if (!Number.isNaN(msgMs) && msgMs < sinceMs) continue;
+      }
+      for (const b of m.content) {
+        if (b.type !== "text" || typeof b.text !== "string") continue;
+        for (const re of BUG_MARKERS) {
+          if (re.test(b.text)) {
+            const match = b.text.match(re);
+            return match?.[0] ?? null;
+          }
+        }
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+/**
+ * True when the mem log has at least one kind:bug row with ts >= since.
+ */
+function hasBugRowSince(worktree: string, since: string): boolean {
+  try {
+    const { rows } = readMemLog(worktree, since);
+    return rows.some((r) => r.kind === "bug");
+  } catch {
+    return false;
+  }
+}
+
 function git(args: string[], cwd: string): string | null {
   try {
     const p = Bun.spawnSync(["git", ...args], {
@@ -262,6 +378,8 @@ export async function cmdHookStop(): Promise<void> {
     let commitList: string[] = [];
     let memLastTs: string | null = null;
     let memCandidates: string[] = [];
+    let bugSignal: string | null = null;
+    let bugRowSinceStart = false;
     if (worktree && since) {
       const log = git(
         ["log", "--since", `${since} +0000`, "--format=%h %s"],
@@ -276,6 +394,14 @@ export async function cmdHookStop(): Promise<void> {
       } catch {
         memLastTs = null;
       }
+      // Bug-signal detection (independent of commits)
+      if (norm.transcriptPath && process.env.FAPONY_NO_BUG_BLOCK !== "1") {
+        const sinceMs = hookTsMs(since);
+        if (!Number.isNaN(sinceMs)) {
+          bugSignal = bugSignalFromTranscript(norm.transcriptPath, sinceMs);
+          if (bugSignal) bugRowSinceStart = hasBugRowSince(worktree, since);
+        }
+      }
     }
 
     reason = decideStop({
@@ -286,11 +412,17 @@ export async function cmdHookStop(): Promise<void> {
       commitList,
       memLastTs,
       memCandidates,
+      bugSignal,
+      bugRowSinceStart,
     });
     if (
       reason &&
       worktree &&
-      stopBlockedBefore(norm.transcriptPath, worktree)
+      stopBlockedBefore(
+        norm.transcriptPath,
+        worktree,
+        bugSignal ? "bug" : "commit",
+      )
     ) {
       reason = null;
     }

package/src/commands.ts

@@ -0,0 +1,180 @@
+// src/commands.ts — the single source of truth for top-level command names.
+//
+// Dispatch stays an if-chain in src/adapters/cli.ts (rule 1: this is a data
+// table, not a framework — no registry class, no plugin hooks). This table
+// owns name + group + one-line summary; `fapony --help` renders from it and
+// test/docs.test.ts fails when a name here is missing from the docs, so the
+// four copies (if-chain, usage, CLAUDE.md, README) cannot drift silently.
+// Zero imports — cli.ts loads this on every startup (≤ ~100ms budget).
+
+export type CommandGroup =
+  | "core"
+  | "usage"
+  | "lookup"
+  | "hooks"
+  | "setup"
+  | "frozen";
+
+export interface CommandInfo {
+  name: string;
+  group: CommandGroup;
+  summary: string;
+}
+
+const GROUP_ORDER: CommandGroup[] = [
+  "core",
+  "usage",
+  "lookup",
+  "hooks",
+  "setup",
+  "frozen",
+];
+
+export const COMMANDS: CommandInfo[] = [
+  {
+    name: "mem",
+    group: "core",
+    summary: "project pain memory: decisions, bugs, notes",
+  },
+  {
+    name: "debt",
+    group: "core",
+    summary: "which files haven't migrated to a declared convention",
+  },
+  {
+    name: "lint-baseline",
+    group: "core",
+    summary: 'separate "already red" from "I made it red"',
+  },
+  { name: "init-mem", group: "core", summary: "delete legacy .memory/ dirs" },
+  {
+    name: "digest",
+    group: "core",
+    summary: "single-page summary from what's on disk",
+  },
+  {
+    name: "usage-scan",
+    group: "usage",
+    summary: "scan session logs into the cache",
+  },
+  { name: "usage-web", group: "usage", summary: "usage dashboard from cache" },
+  {
+    name: "price-scan",
+    group: "usage",
+    summary: "refresh the model price table",
+  },
+  {
+    name: "analyze",
+    group: "lookup",
+    summary: "live repo graph: hubs, orphans, cycles",
+  },
+  {
+    name: "review-seed",
+    group: "lookup",
+    summary: "read-only scope facts for a review",
+  },
+  {
+    name: "plan-seed",
+    group: "lookup",
+    summary: "write PLAN (+SPEC) with capped sections",
+  },
+  {
+    name: "mcp",
+    group: "hooks",
+    summary: "MCP server (stdio JSON-RPC, 3 tools)",
+  },
+  {
+    name: "hook-stop",
+    group: "hooks",
+    summary: "Stop hook: block turns with commits but no mem row",
+  },
+  {
+    name: "hook-read-hint",
+    group: "hooks",
+    summary: "read/re-read annotations",
+  },
+  {
+    name: "hook-edit-hint",
+    group: "hooks",
+    summary: "importer count before editing shape",
+  },
+  {
+    name: "hook-mv-guard",
+    group: "hooks",
+    summary: "deny raw git mv of plan files into done/",
+  },
+  {
+    name: "hook-session-start",
+    group: "hooks",
+    summary: "SessionStart: kickoff into context",
+  },
+  { name: "init", group: "setup", summary: "scaffold .fapony/ in a worktree" },
+  {
+    name: "install",
+    group: "setup",
+    summary: "wire MCP + skills into clients",
+  },
+  { name: "setup", group: "setup", summary: "interactive wizard" },
+  { name: "update", group: "setup", summary: "self-update via git pull" },
+  { name: "telemetry", group: "setup", summary: "opt-in telemetry show/send" },
+  {
+    name: "stats",
+    group: "frozen",
+    summary: "frozen-ledger KPIs (reads history only)",
+  },
+  { name: "report", group: "frozen", summary: "verification report for a run" },
+  { name: "report-web", group: "frozen", summary: "static HTML report page" },
+];
+
+// Grouped names only — the shape PLAN-seed-and-surface §7 picked. Starts with
+// a `usage: fapony` line: scripts/smoke-publish.sh greps for it on a no-arg run.
+export const renderUsage = (): string => {
+  const lines = [
+    "fapony — project pain memory for agent-written code",
+    "usage: fapony <command> [args]",
+    "",
+  ];
+  for (const g of GROUP_ORDER) {
+    const names = COMMANDS.filter((c) => c.group === g).map((c) => c.name);
+    lines.push(`  ${g.padEnd(8)}${names.join("  ")}`);
+  }
+  lines.push(
+    "",
+    "  fapony mem <sub> --help     per-subcommand details (only mem has --help)",
+  );
+  return lines.join("\n");
+};
+
+// Classic two-row Levenshtein — the did-you-mean behind unknown-command errors.
+export const levenshtein = (a: string, b: string): number => {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(
+        prev[j] + 1,
+        cur[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = cur;
+  }
+  return prev[b.length];
+};
+
+// Up to 3 suggestions within distance ≤ 2, against top-level names and mem
+// subs (so `fapony plan-check` offers `fapony mem plan-check`). Sorted by
+// distance, then alphabetically — deterministic for tests.
+export const suggestCommand = (cmd: string, memSubs: string[]): string[] => {
+  const scored: Array<{ text: string; d: number }> = [];
+  for (const c of COMMANDS) {
+    const d = levenshtein(cmd, c.name);
+    if (d <= 2) scored.push({ text: `fapony ${c.name}`, d });
+  }
+  for (const s of memSubs) {
+    const d = levenshtein(cmd, s);
+    if (d <= 2) scored.push({ text: `fapony mem ${s}`, d });
+  }
+  scored.sort((x, y) => x.d - y.d || (x.text < y.text ? -1 : 1));
+  return scored.slice(0, 3).map((s) => s.text);
+};

package/src/hook.ts

@@ -6,6 +6,7 @@
 // from this path.
 
 export {
+  bugSignalFromTranscript,
   COMMIT_HINT_MIN_COMMITS,
   type CommitHintInput,
   type ContextLineData,

package/src/mem/commands/plan.ts

@@ -323,7 +323,93 @@ export const cmdPlanSweep = (a: string[]) => {
 };
 
 // plan-check — list active PLANs + detect shipped-not-moved + broken links
+// + verify the commits ticked chunks cite (chunk 8, PLAN-seed-and-surface)
 // exit 0 = clean, 1 = issues found
+
+// A ticked chunk cites the commit that closed it — a sha git cannot find on
+// this HEAD means the "done" mark proves nothing. git is the judge, not the
+// regex: a 7-hex word that is no object at all (deadbee) is a plain word,
+// never an issue. A sha that IS an object but not a commit (blob/tree)
+// counts as missing — "no such commit" is literally true for it.
+// Standalone short shas only — lookarounds (not \b) so a 40-char sha never
+// matches on its tail: git resolves leading prefixes, a trailing slice would
+// false-positive as missing.
+export const SHA_RE = /(?<![0-9a-f])[0-9a-f]{7,12}(?![0-9a-f])/g;
+
+export const extractShas = (line: string): string[] => line.match(SHA_RE) ?? [];
+
+const gitOk = (args: string[], cwd: string): boolean => {
+  try {
+    return (
+      Bun.spawnSync(["git", ...args], {
+        cwd,
+        stdout: "ignore",
+        stderr: "ignore",
+      }).exitCode === 0
+    );
+  } catch {
+    return false;
+  }
+};
+
+export const isCommitObject = (sha: string, cwd: string): boolean =>
+  gitOk(["cat-file", "-e", `${sha}^{commit}`], cwd);
+
+const isAnyObject = (sha: string, cwd: string): boolean =>
+  gitOk(["cat-file", "-e", sha], cwd);
+
+export const isAncestorOfHead = (sha: string, cwd: string): boolean =>
+  gitOk(["merge-base", "--is-ancestor", sha, "HEAD"], cwd);
+
+// Per ticked line: which cited shas fail, plus how many shas the line cites
+// at all (cited). A hex word git never heard of is a plain word (deadbee,
+// the "feedbac" inside "feedback") — UNLESS it sits in a paren group with a
+// sha git knows, in which case the author cited it as a commit: the fixture
+// is (e898877 + e307fe6), where e898877 resolves to no object at all yet is
+// unmistakably a citation, not prose.
+export const checkTickedLine = (
+  line: string,
+  cwd: string,
+): { missing: string[]; diverged: string[]; cited: number } => {
+  const missing: string[] = [];
+  const diverged: string[] = [];
+  const status = new Map<string, "commit" | "object" | "word">();
+  for (const sha of extractShas(line)) {
+    if (!status.has(sha)) {
+      status.set(
+        sha,
+        isCommitObject(sha, cwd)
+          ? "commit"
+          : isAnyObject(sha, cwd)
+            ? "object"
+            : "word",
+      );
+    }
+  }
+  const known = new Set(
+    [...status].filter(([, s]) => s !== "word").map(([k]) => k),
+  );
+  const citedInGroup = new Set<string>();
+  for (const g of line.match(/\([^)]*\)/g) ?? []) {
+    const gs = extractShas(g);
+    if (gs.some((s) => known.has(s))) for (const s of gs) citedInGroup.add(s);
+  }
+  let cited = 0;
+  for (const [sha, st] of status) {
+    if (st === "commit") {
+      cited++;
+      if (!isAncestorOfHead(sha, cwd)) diverged.push(sha);
+    } else if (st === "object") {
+      cited++;
+      missing.push(sha);
+    } else if (citedInGroup.has(sha)) {
+      cited++;
+      missing.push(sha);
+    }
+    // else: a plain word that happens to be hex — skip
+  }
+  return { missing, diverged, cited };
+};
 export const cmdPlanCheck = (a: string[]) => {
   const quiet = a.includes("--quiet");
   const dir = planDir;
@@ -375,6 +461,47 @@ export const cmdPlanCheck = (a: string[]) => {
     }
   }
 
+  // 4) Ticked-chunk sha check — a ticked chunk that cites a commit must cite
+  //    one git finds on this HEAD. Scans plan/ AND done/: done/ files are the
+  //    shipped record, and the known-stale shas all live there — active-only
+  //    would see zero. No sha = no check (chunks that close with "defer" have
+  //    no commit); the summary line reports the ratio instead of flagging.
+  let closed = 0;
+  let citing = 0;
+  let verified = 0;
+  const shaFiles = [
+    ...new Set([...active, ...(existsSync(doneDir) ? mdFiles(doneDir) : [])]),
+  ];
+  for (const f of shaFiles) {
+    const relPath = relative(planBase, f);
+    const lines = readFileSync(f, "utf8").split("\n");
+    lines.forEach((line, i) => {
+      if (!/^\s*-\s\[x\]/.test(line)) return;
+      closed++;
+      const { missing, diverged, cited } = checkTickedLine(line, root);
+      if (cited > 0) {
+        citing++;
+        if (!missing.length && !diverged.length) verified++;
+      }
+      for (const sha of missing) {
+        issues.push(
+          `${relPath}:${i + 1} — ticked chunk cites ${sha} but git has no such commit\n   fix: correct the sha or leave the chunk unticked`,
+        );
+      }
+      for (const sha of diverged) {
+        issues.push(
+          `${relPath}:${i + 1} — ticked chunk cites ${sha} which is not an ancestor of HEAD (rebased away?)\n   fix: point at the surviving commit or leave the chunk unticked`,
+        );
+      }
+    });
+  }
+
+  if (!quiet) {
+    console.log(
+      `closed chunks: ${closed} · citing a commit: ${citing} · verified: ${verified}`,
+    );
+  }
+
   if (issues.length === 0) {
     if (!quiet) console.log("✅ clean");
     process.exit(0);

package/src/mem/commands/read.ts

@@ -7,7 +7,7 @@ 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 { checkTickedLine, 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. */
@@ -93,30 +93,56 @@ export const cmdFind = (a: string[]) => {
   if (!hits.length) console.log("(no matches)");
 };
 
-/** Read a plan file and extract unchecked checkboxes from the TL;DR section. */
-const readPlanCheckboxes = (planPath: string): string[] => {
+/** Read a plan file and extract checked + unchecked items from the first ## section. */
+const readPlanSectionItems = (
+  planPath: string,
+): { checked: string[]; unchecked: string[] } => {
   try {
     const text = readFileSync(planPath, "utf8");
     // Skip frontmatter
     const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
     // Find the first ## section (TL;DR)
     const start = body.search(/^##\s+/m);
-    if (start < 0) return [];
+    if (start < 0) return { checked: [], unchecked: [] };
     const rest = body.slice(start);
     const next = rest.slice(3).search(/^##\s+/m);
     const block = next < 0 ? rest : rest.slice(0, next + 3);
-    // Extract unchecked checkboxes
-    const items: string[] = [];
+    // Extract checkboxes — ticked and unticked
+    const checked: string[] = [];
+    const unchecked: string[] = [];
     for (const line of block.split("\n")) {
-      const m = /^\s*[-*]\s+\[\s\]\s+(.+)$/.exec(line);
-      if (m) items.push(m[1].trim());
+      let m = /^\s*[-*]\s+\[\s\]\s+(.+)$/.exec(line);
+      if (m) {
+        unchecked.push(m[1].trim());
+        continue;
+      }
+      m = /^\s*[-*]\s+\[[xX]\]\s+(.+)$/.exec(line);
+      if (m) checked.push(m[1].trim());
     }
-    return items;
+    return { checked, unchecked };
   } catch {
-    return [];
+    return { checked: [], unchecked: [] };
   }
 };
 
+// Chunk 9 (PLAN-seed-and-surface): one line under the next-chunk display
+// saying whether the last ticked chunk actually closed. Verified shas stay
+// silent; only the newest ticked chunk is ever mentioned — one line per
+// kickoff, never a list (else vela's 64/72 sha-less chunks become noise).
+const closureHint = (checked: string[]): string | null => {
+  const last = checked[checked.length - 1];
+  if (!last) return null;
+  const { missing, diverged, cited } = checkTickedLine(last, root);
+  const label = /chunk\s+([^\s—–-]+)/i.exec(last)?.[1] ?? "latest";
+  if (missing.length)
+    return `⚠ chunk ${label} is ticked but ${missing[0]} is not in git — nothing proves it closed`;
+  if (diverged.length)
+    return `⚠ chunk ${label} is ticked but ${diverged[0]} is not on HEAD (rebased away?)`;
+  if (!cited)
+    return `⚠ chunk ${label} is ticked but cites no commit — nothing to verify it closed`;
+  return null;
+};
+
 /** Check if a plan has `priority: high` in its frontmatter. */
 const hasHighPriority = (planPath: string): boolean => {
   try {
@@ -200,6 +226,7 @@ export const cmdKickoff = (a: string[]) => {
   // If no arg or arg didn't match an id/spec, check if it's a plan file
   let planFile: string | null = null;
   let planCheckboxes: string[] = [];
+  let planChecked: string[] = [];
 
   if (arg && !resolvedSpec && !target) {
     if (matches.length === 1) {
@@ -233,14 +260,18 @@ export const cmdKickoff = (a: string[]) => {
 
   // Read plan file if we found one (or if a .md arg matched a spec)
   if (planFile) {
-    planCheckboxes = readPlanCheckboxes(planFile);
+    const items = readPlanSectionItems(planFile);
+    planCheckboxes = items.unchecked;
+    planChecked = items.checked;
   } else if (arg && resolvedSpec && arg.endsWith(".md")) {
     // The spec resolved from the log might be a plan file — try to read it
     const dir = planDir;
     const byName = join(dir, basename(arg));
     if (existsSync(byName)) {
       planFile = byName;
-      planCheckboxes = readPlanCheckboxes(planFile);
+      const items = readPlanSectionItems(planFile);
+      planCheckboxes = items.unchecked;
+      planChecked = items.checked;
     }
   }
 
@@ -466,6 +497,12 @@ export const cmdKickoff = (a: string[]) => {
     if (!specRows.length && !specDecisions.length && !specCloses.length) {
       console.log("(no entries for this spec)");
     }
+    // The spec is also a plan file on disk — say whether the last ticked
+    // chunk actually closed (chunk 9). Silent when it verifies.
+    if (planFile) {
+      const hint = closureHint(planChecked);
+      if (hint) console.log(`\n${hint}`);
+    }
   } else if (target) {
     // id = a brief for that task
     const claims = claimsOf(all);
@@ -525,6 +562,10 @@ export const cmdKickoff = (a: string[]) => {
     } else {
       console.log(`\n(all chunks checked — ready to ship or archive)`);
     }
+    // Whether the last ticked chunk actually closed (chunk 9) — one line,
+    // silent when its sha verifies.
+    const hint = closureHint(planChecked);
+    if (hint) console.log(hint);
   } else if (arg) {
     console.error(`no id "${arg}" in the log`);
     process.exit(1);

package/src/mem/index.ts

@@ -3,6 +3,9 @@
 // Moved from templates/mem/mem.ts (2026-09-19) as part of PLAN-agent-one-call chunk 1.
 // Now an export function called by fapony.ts, not a standalone script.
 
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { levenshtein } from "../commands.js";
 import { cmdPlanCheck, cmdPlanSweep } from "./commands/plan.js";
 import { cmdDone, cmdFind, cmdKickoff, cmdStale } from "./commands/read.js";
 import { cmdRotate } from "./commands/rotate.js";
@@ -15,6 +18,7 @@ import {
   cmdRelease,
   cmdSynced,
 } from "./commands/write.js";
+import { doneDir, planDir } from "./store.js";
 
 const MEM_HELP = `usage: fapony mem [--mem-dir <path>] <sub> [args]
 
@@ -86,6 +90,42 @@ reads the Stop-hook payload on stdin — installed by fapony, not run by hand
 example: (installed hook only)`,
 };
 
+// Subcommand names for top-level did-you-mean (src/commands.ts) — derived
+// from HELP keys so the list cannot drift from the dispatch below.
+export const MEM_SUBCOMMANDS: string[] = Object.keys(HELP);
+
+// Chunk 7 (PLAN-seed-and-surface, bug muc85pml): `fapony mem now` used to fall
+// through to kickoff and print an overview ("N entries") instead of an error —
+// a typo that looks like success. Three rules, in order:
+//   1. a known subcommand → dispatch (unchanged)
+//   2. looks like a plan path (.md suffix, a slash, or a file with that name
+//      in planDir/doneDir) → kickoff — this is `fapony mem PLAN-x.md`, which
+//      must keep working without the `kickoff` word
+//   3. anything else → error, exit 1 (a typo is never a kickoff)
+//
+// `exists` is injectable so tests hit this directly without a store on disk —
+// production passes nothing and reads planDir/doneDir live.
+export function classifyMemArg(
+  arg: string,
+  exists?: (name: string) => boolean,
+): "subcommand" | "plan" | "unknown" {
+  // hasOwn, not `in` or indexing — prototype props ("toString") are not
+  // subcommands.
+  if (Object.hasOwn(HELP, arg)) return "subcommand";
+  if (arg.endsWith(".md") || arg.includes("/")) return "plan";
+  const has =
+    exists ??
+    ((name: string): boolean => {
+      const base = basename(name);
+      const candidates = [name, base, `${name}.md`, `${base}.md`];
+      return candidates.some(
+        (c) => existsSync(join(planDir, c)) || existsSync(join(doneDir, c)),
+      );
+    });
+  if (has(arg)) return "plan";
+  return "unknown";
+}
+
 export async function cmdMem(a: string[], memDir?: string): Promise<void> {
   const [cmd, ...rest] = a;
 
@@ -128,8 +168,27 @@ export async function cmdMem(a: string[], memDir?: string): Promise<void> {
     cmdPlanCheck(rest);
   } else if (cmd === "rotate") {
     cmdRotate(rest);
-  } else {
+  } else if (cmd === undefined) {
     // bare `fapony mem` → kickoff (ranked session overview)
     cmdKickoff(rest);
+  } else if (classifyMemArg(cmd) === "plan") {
+    // `fapony mem PLAN-x.md` — the plan arg rides along (the old else-branch
+    // dropped it and printed the no-arg overview instead).
+    cmdKickoff([cmd, ...rest]);
+  } else {
+    console.error(`fapony mem: unknown subcommand "${cmd}"`);
+    const scored = MEM_SUBCOMMANDS.map((s) => ({
+      s,
+      d: levenshtein(cmd, s),
+    }))
+      .filter((x) => x.d <= 2)
+      .sort((x, y) => x.d - y.d || (x.s < y.s ? -1 : 1))
+      .slice(0, 3)
+      .map((x) => `"fapony mem ${x.s}"`);
+    if (scored.length > 0) {
+      console.error(`did you mean ${scored.join(" or ")}?`);
+    }
+    console.error(`subcommands: ${MEM_SUBCOMMANDS.join(" ")}`);
+    process.exit(1);
   }
 }

package/src/memory.ts

@@ -74,6 +74,7 @@ export function claimMemory(
   config: Config,
   worktree: string,
   memId: string,
+  timeoutMs = 15_000,
 ): boolean {
   const mem = resolveMemoryConfig(config, worktree);
   if (!mem) return false;
@@ -83,7 +84,7 @@ export function claimMemory(
     execSync(cmd.join(" "), {
       cwd: worktree,
       stdio: ["pipe", "pipe", "pipe"],
-      timeout: 15_000,
+      timeout: timeoutMs,
     });
     return true;
   } catch {

package/src/seed/plan-seed.ts

@@ -35,7 +35,6 @@ import {
 } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { collectSourceFiles, isSkippedDir, SCAN_EXTS } from "../analyze.js";
-import { computeModelFit } from "../context/projectHealth.js";
 import {
   CONFIG_FILENAME,
   type Config,
@@ -46,7 +45,6 @@ import {
 } from "../core/config.js";
 import { extractExports } from "../map.js";
 import { readRecentMemDecisions } from "../memory.js";
-import { getStatsData } from "../stats/data.js";
 import { capLines, execGit, SIG_MAX } from "./primitives.js";
 
 // One chunk = one module's signatures — past ~40 lines a module is its own
@@ -60,6 +58,14 @@ const SCOPE_WARN_FILES = 300;
 // Shipped plans/specs that already touched this scope. Capped low on purpose:
 // this is a "go read that first" pointer, not a bibliography.
 const MAX_PRIOR_ART = 5;
+// Chunk 4 (PLAN-seed-and-surface): the PLAN names what is already in scope —
+// one line per scope file with its export names. SPEC-only seeds never gave
+// PLAN-only readers this pointer, so agents re-derived what export-lines.ts
+// already knew. Capped low: a pointer, not a signature dump.
+const MAX_EXISTING_IN_SCOPE = 15;
+// The PLAN ≤ ~60 contract (§3.1) predates this block — the block yields to it,
+// never grows it. Effective block cap = min(block cap, remaining budget).
+const MAX_PLAN_LINES = 60;
 // Anchor-safe slug: lowercase, non-alphanumerics → dash.
 const slug = (s: string): string =>
   s
@@ -149,7 +155,84 @@ function renderPriorArt(cwd: string, config: Config, roots: string[]): string {
   return shown.join("\n");
 }
 
-// --- Context (fapony): mem decisions + model fit ---
+// Chunk 5 (PLAN-seed-and-surface): stdout ends with the plans that already
+// exist — the seed that lands next to a shipped decision without knowing it
+// is the expensive mistake (§8 prior art guards the file, this guards the
+// glance). Active plans first (the ones a new seed must not duplicate),
+// then shipped; capped like every other list here.
+const MAX_PLAN_LIST = 10;
+
+function listExistingPlans(
+  cwd: string,
+  config: Config,
+  exclude: string,
+): string[] {
+  const items: string[] = [];
+  for (const [dir, where] of [
+    [planDir(), "plan"],
+    [doneDir(config), "done"],
+  ] as const) {
+    let names: string[];
+    try {
+      names = readdirSync(join(cwd, dir))
+        .filter((n) => n.endsWith(".md"))
+        .sort();
+    } catch {
+      continue; // dir missing — nothing seeded yet
+    }
+    for (const n of names) {
+      if (n === exclude) continue; // the file just written, not "existing"
+      items.push(`- ${n} (${where})`);
+    }
+  }
+  if (items.length === 0) return ["- (none yet)"];
+  return capLines(items, MAX_PLAN_LIST, "plans");
+}
+
+// --- Context (fapony): mem decisions + existing in scope ---
+//
+// No ledger-ranking line here (PLAN-seed-and-surface chunk 6): the ledger is
+// frozen and Positioning rule 2 forbids cross-model ranking claims, so a
+// seeded pointer at it teaches the reader to cite what cannot be cited.
+// computeModelFit() itself stays — `fapony stats` reads it.
+
+// One line per scope file naming its exports — `src/debt/scan.ts —
+// scanDebt() · DebtHit`. Files with no exports (or unreadable) are skipped:
+// a pointer lists what is there, not what is not. Sorted for determinism.
+function renderExistingInScope(
+  roots: string[],
+  cwd: string,
+  scoped: boolean,
+  cap: number,
+): string[] {
+  // No --scope means every file in the repo matches — a list of everything
+  // points at nothing (§8 prior art goes quiet for the same reason).
+  if (!scoped)
+    return ["- _(no --scope — re-seed with --scope <dir> to list exports)_"];
+  const abs: string[] = [];
+  for (const r of roots) for (const f of scopeSourceFiles(r)) abs.push(f);
+  const rels = [...new Set(abs.map((f) => relative(cwd, f) || "."))].sort();
+  const lines: string[] = [];
+  for (const rel of rels) {
+    let source: string;
+    try {
+      source = readFileSync(join(cwd, rel), "utf-8");
+    } catch {
+      continue;
+    }
+    const scan = extractExports(source);
+    if (scan.error || scan.symbols.length === 0) continue;
+    // Re-export-only files scan as one `*` per line — dedupe to a single `*`.
+    const names = [
+      ...new Set(
+        scan.symbols.map((s) => (s.kind === "fn" ? `${s.name}()` : s.name)),
+      ),
+    ];
+    lines.push(`- ${rel} — ${names.join(" · ")}`);
+  }
+  if (lines.length === 0) return ["- _(no exports in scope)_"];
+  return capLines(lines, cap, "files in scope (narrow with --scope <path>)");
+}
 
 function renderContextFapony(worktree: string): string {
   const lines: string[] = [];
@@ -164,17 +247,6 @@ function renderContextFapony(worktree: string): string {
           .join(" · ")}`
       : "- Decisions on record (mem): _(none — no mem log or empty)_",
   );
-  const fits = computeModelFit(getStatsData().byRegime, worktree);
-  lines.push(
-    fits.length > 0
-      ? `- Model fit (ledger, min N=5): ${fits
-          .map(
-            (f) =>
-              `${f.regime} → ${f.model} (N=${f.gates}, fail ${(f.failRate * 100).toFixed(0)}%)`,
-          )
-          .join(" · ")}`
-      : "- Model fit: _(not enough graded history yet)_",
-  );
   return lines.join("\n");
 }
 
@@ -184,6 +256,7 @@ function planTemplate(
   name: string,
   priorArt: string,
   contextFapony: string,
+  existingScope: string[],
   specLink: string | null,
   planRel: string,
 ): string {
@@ -204,6 +277,8 @@ status: active
 
 ## Context (fapony)
 ${contextFapony}
+### Existing in scope
+${existingScope.join("\n")}
 
 ## 1. Goal (why)
 _(agent fills in)_
@@ -221,19 +296,11 @@ _(agent fills in)_
 _(agent fills in)_
 
 ## 6. Steps (what in which order)
-One step = one chunk = one session: finish it, close it, **stop** — starting the
-next step in the same session is what rule 9 forbids.
+One step = one chunk = one session: finish it, close it, **stop** — starting the next step in the same session is what rule 9 forbids.
 
 1. _(agent fills in — each step must be verifiable)_
 
-**Closing a step:** tick its TL;DR box with the sha · \`git commit\` this step's
-files only · then hand off:
-
-\`\`\`bash
-fapony mem add note "<what chunk N+1 must know>" --files <f1,f2> ${planRel}
-\`\`\`
-
-Next session opens with \`kickoff ${planRel}\` (or \`kickoff ${basename(planRel)}\` — kickoff resolves by filename too, so no need to retype the path).
+**Closing a step:** tick TL;DR with sha · \`git commit\` files only · \`fapony mem add note "<what chunk N+1 must know>" --files <f1,f2> ${planRel}\` · next opens with \`kickoff ${planRel}\` (or \`kickoff PLAN-${name}.md\` — kickoff resolves by filename too).
 
 ## 7. Examples
 ${
@@ -566,6 +633,14 @@ export function cmdPlanSeed(args: string[]): void {
 
   const priorArt = renderPriorArt(cwd, config, roots);
   const contextFapony = renderContextFapony(worktree);
+  const scoped = requested.length > 0;
+  // First pass at the block cap — the total-cap check below may shrink it.
+  let existingScope = renderExistingInScope(
+    roots,
+    cwd,
+    scoped,
+    MAX_EXISTING_IN_SCOPE,
+  );
 
   let specLink: string | null = null;
   if (withSpec) {
@@ -593,15 +668,30 @@ export function cmdPlanSeed(args: string[]): void {
   }
 
   mkdirSync(planDirAbs, { recursive: true });
-  writeFileSync(
-    planPath,
+  const buildPlan = (existing: string[]): string =>
     planTemplate(
       name,
       priorArt,
       contextFapony,
+      existing,
       specLink,
       `${planDir()}/PLAN-${name}.md`,
-    ),
-  );
+    );
+  let planBody = buildPlan(existingScope);
+  // The ≤ ~60 contract predates the §4 block — shrink the block (never the
+  // judgment sections) until the file fits. Each item is one line, so cutting
+  // `over` items fixes exactly; the re-render recounts the cut honestly.
+  const planLines = (b: string): number =>
+    b.replace(/\n$/, "").split("\n").length;
+  const over = planLines(planBody) - MAX_PLAN_LINES;
+  if (over > 0) {
+    const budget = Math.max(existingScope.length - over, 1);
+    existingScope = renderExistingInScope(roots, cwd, scoped, budget);
+    planBody = buildPlan(existingScope);
+  }
+  writeFileSync(planPath, planBody);
   console.log(`wrote ${planPath}${specLink ? ` + SPEC-${name}.md` : ""}`);
+  console.log("Existing plans:");
+  for (const l of listExistingPlans(cwd, config, `PLAN-${name}.md`))
+    console.log(l);
 }

package/src/update.ts

@@ -206,7 +206,7 @@ export async function cmdUpdate(deps: UpdateDeps = {}): Promise<void> {
   │  Update complete!                        │
   │                                          │
   │  Version: ${newVersion.padEnd(31)}│
-  │  Run "fapony test" to verify.            │
+  │  Run "bun run test" to verify.           │
   └──────────────────────────────────────────┘
 `);
 }

package/src/test.ts

@@ -1,2 +0,0 @@
-// src/test.ts — thin CLI wrapper. Actual tests live in test/.
-export { cmdTest } from "../test/index.js";