fapony 0.3.4 → 0.3.6

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]
 
@@ -23,7 +27,8 @@ subcommands:
   kickoff [<plan.md>] [--pick <n>]   open a session + a next-up list
   add <kind> "<text>" --files f1,f2 [spec.md]
   close <id> "<msg>"          close a bug
-  find "<text>"               substring-search every row
+  find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n]
+                          substring-search every row (archives included)
   done | stale              views
   claim <id> | release <id> | synced   bookkeeping
   plan-sweep [<plan.md> [--apply]]     move shipped plans + fix links
@@ -53,9 +58,13 @@ example: fapony mem add decision "chose X because Y" --files src/a.ts,src/b.ts`,
 tombstone a bug so it stops showing as open work
   --stdin         read the message from stdin
 example: fapony mem close mt14 "fixed in a2c6beb"`,
-  find: `usage: fapony mem find "<text>"
-substring search over every row's text/spec/ref — all kinds, no default filter
-example: fapony mem find "usage-web"`,
+  find: `usage: fapony mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n]
+substring search over every row's text/spec/ref (rotated archives included) — bookkeeping kinds (close/synced/claim/release) hidden unless --kind names them
+  --kind a,b    include only these kinds (overrides the bookkeeping default)
+  --files f1,f2 rows about these paths (stored files[] first, text/spec/ref fallback)
+  --since 7d    only rows at or after this time (<N>d or YYYY-MM-DD)
+  --limit n     max rows returned (default 20, newest first)
+example: fapony mem find "usage-web" --kind bug,decision --limit 5`,
   done: `usage: fapony mem done
 closed rows with their tombstone message
 example: fapony mem done`,
@@ -86,6 +95,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 +173,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/seed/review-seed.ts

@@ -21,7 +21,7 @@
 
 import type { Stats } from "node:fs";
 import { existsSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import {
   buildGraph,
   collectSourceFiles,
@@ -357,9 +357,35 @@ function shortSha(cwd: string, ref: string): string | null {
   return r.ok ? r.output.split("\n")[0] : null;
 }
 
-function resolveScope(scope: Scope, cwd: string): ResolvedScope {
+// --plan paths arrive in three shapes: absolute, relative to the invocation
+// cwd (e.g. ../../.fapony/plan/X.md from a subdir), or relative to the
+// worktree root (e.g. .fapony/plan/X.md from anywhere). join(worktree, arg)
+// answers only the third — an absolute arg becomes worktree+abs garbage
+// (join, unlike resolve, does not reset on an absolute segment), and a
+// cwd-relative arg with .. escapes above the root. So: absolute as-is,
+// otherwise first-existing-wins between cwd and worktree (bug mucm1own).
+function resolvePlanPath(arg: string, cwd: string, worktree: string): string {
+  if (isAbsolute(arg)) {
+    if (existsSync(arg)) return arg;
+    throw new SeedError(`review-seed: plan file not found: ${arg}`);
+  }
+  const candidates = [resolve(cwd, arg), join(worktree, arg)];
+  for (const p of new Set(candidates)) {
+    if (existsSync(p)) return p;
+  }
+  throw new SeedError(`review-seed: plan file not found: ${arg}`);
+}
+
+function resolveScope(
+  scope: Scope,
+  cwd: string,
+  worktree: string,
+): ResolvedScope {
   if (scope.kind === "files") {
-    const { files, notes, dirExpanded } = expandFilesScope(scope.list, cwd);
+    const { files, notes, dirExpanded } = expandFilesScope(
+      scope.list,
+      worktree,
+    );
     return {
       label: dirExpanded ? "--files (dir-expanded)" : "--files (as given)",
       entries: files,
@@ -367,10 +393,7 @@ function resolveScope(scope: Scope, cwd: string): ResolvedScope {
     };
   }
   if (scope.kind === "plan") {
-    const planPath = join(cwd, scope.path);
-    if (!existsSync(planPath)) {
-      throw new SeedError(`review-seed: plan file not found: ${scope.path}`);
-    }
+    const planPath = resolvePlanPath(scope.path, cwd, worktree);
     const planFiles = planFrontFiles(readFileSync(planPath, "utf-8"));
     if (planFiles === null) {
       // No files[] to scope from — fall back to the default diff, say so.
@@ -567,6 +590,7 @@ function findCallers(
 function renderLookup(
   flags: LookupFlags,
   scope: Scope,
+  cwd: string,
   worktree: string,
 ): string {
   const lines: string[] = [];
@@ -574,7 +598,7 @@ function renderLookup(
 
   let resolved: ResolvedScope | null = null;
   if (flags.callers) {
-    resolved = resolveScope(scope, worktree);
+    resolved = resolveScope(scope, cwd, worktree);
   }
 
   const hasGraph = (f: string): boolean => {
@@ -686,10 +710,10 @@ export function renderSeed(args: string[], cwd: string): string {
   // the caller asked for one answer, not the review seed around it.
   const lookup = parseLookup(args);
   if (lookup.body.length > 0 || lookup.callers) {
-    return renderLookup(lookup, scope, worktree);
+    return renderLookup(lookup, scope, cwd, worktree);
   }
 
-  const resolved = resolveScope(scope, worktree);
+  const resolved = resolveScope(scope, cwd, worktree);
   const entries = [...resolved.entries].sort((a, b) =>
     a.path < b.path ? -1 : 1,
   );

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";