fapony 0.4.0 → 0.6.0

package/src/seed/plan-seed.ts

@@ -1,4 +1,4 @@
-// src/seed/plan-seed.ts — `fapony plan-seed <name> [--spec] [--scope <path>]...`
+// src/seed/plan-seed.ts — `fapony plan-seed <name> [--spec] [--scope <path>[,<path>]]...`
 //
 // Writes PLAN + SPEC straight into planDir/specDir. What it pre-fills is the
 // structure (frontmatter, the 8 sections, prior art, ledger context) — the
@@ -34,7 +34,11 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, join, relative, resolve, sep } from "node:path";
-import { collectSourceFiles, isSkippedDir, SCAN_EXTS } from "../analyze.js";
+import {
+  collectSourceFiles,
+  isSkippedDir,
+  SCAN_EXTS,
+} from "../analyze/index.js";
 import {
   CONFIG_FILENAME,
   type Config,
@@ -43,8 +47,9 @@ import {
   planDir,
   specDir,
 } from "../core/config.js";
+import { MEM_TEXT_MAX } from "../core/mem-log.js";
 import { extractExports } from "../map.js";
-import { readRecentMemDecisions } from "../memory.js";
+import { readMemLog, readRecentMemDecisions } from "../memory.js";
 import { capLines, execGit, SIG_MAX } from "./primitives.js";
 
 // One chunk = one module's signatures — past ~40 lines a module is its own
@@ -220,7 +225,7 @@ function renderExistingInScope(
     } catch {
       continue;
     }
-    const scan = extractExports(source);
+    const scan = extractExports(source, undefined, rel);
     if (scan.error || scan.symbols.length === 0) continue;
     // Re-export-only files scan as one `*` per line — dedupe to a single `*`.
     const names = [
@@ -301,6 +306,7 @@ One step = one chunk = one session: finish it, close it, **stop** — starting t
 1. _(agent fills in — each step must be verifiable)_
 
 **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).
+- [ ] handoff: the mem note is the handoff — this box only opts the plan into the Stop-hook check
 
 ## 7. Examples
 ${
@@ -345,7 +351,7 @@ function fileLines(absFile: string): string[] {
   } catch {
     return ["_(unreadable)_"];
   }
-  const scan = extractExports(source);
+  const scan = extractExports(source, undefined, absFile);
   if (scan.error) return [`⚠ ${scan.error} — symbols not extractable`];
   if (scan.symbols.length === 0) return ["_(no exports)_"];
   let srcLines: string[] = [];
@@ -507,6 +513,7 @@ function specTemplate(
   name: string,
   chunks: Chunk[],
   scopeEcho: string | null,
+  traps: string[],
 ): string {
   const index = chunks.map((c) => `- [${c.title}](#${c.slug})`).join("\n");
   // The index is one string with a newline per chunk; budgeting it as one line
@@ -534,12 +541,18 @@ function specTemplate(
   const tail = [
     "## (agent fills in — wireframes / edge cases / API shapes the plan references)",
   ];
-  const bodyLines = chunks.flatMap((c) => [
-    `## <a id="${c.slug}"></a>${c.title}`,
-    "",
-    ...c.body.split("\n"),
-    "",
-  ]);
+  const bodyLines = [
+    // Known traps sit after the index, before the first chunk body — budgeted
+    // with the bodies so the whole-SPEC cap still cuts from the tail and the
+    // count line above survives (a silent section would teach skipping it).
+    ...(traps.length > 0 ? [...traps, ""] : []),
+    ...chunks.flatMap((c) => [
+      `## <a id="${c.slug}"></a>${c.title}`,
+      "",
+      ...c.body.split("\n"),
+      "",
+    ]),
+  ];
   // Whole-file cap runs last and the agent section survives it, same way
   // review-seed reserves its disclaimer: reserve the tail, cut the middle,
   // say how much was dropped.
@@ -552,10 +565,107 @@ function specTemplate(
   return `${[...head, ...cappedBody, ...tail].join("\n")}\n`;
 }
 
+// --- Known traps (PLAN-active-pain chunk 2): mem rows on this scope ---
+//
+// The one place a seed is allowed to be opinionated: past pain about exactly
+// these files. bug rows first, then decision (note carries no "this hurt"
+// signal), newest first within a kind. Match mirrors mem_find: files[] first;
+// the text/spec fallback runs ONLY for rows with no files[] at all — a row
+// that named files already spoke, its text may quote any path.
+//
+// Measured base rate on this repo before building (rule 2, 2026-09-23):
+// 248 rows total; scope src/seed → 5 matched (3 bug/2 decision, 0 lacked) ·
+// src/mem → 12 (4/8, 0) · src/adapters/hooks → 6 (2/4, 0) · whole repo → 61
+// (20/41, 0). The "M lacked files[]" fallback layer fired 0/4 scopes here —
+// kept because a pre-files[] repo (vela's 2,672 rows) depends on it.
+const MAX_TRAP_ROWS = 5;
+
+interface TrapHit {
+  row: {
+    ts: string;
+    kind: string;
+    text: string;
+    files?: string[];
+    spec?: string;
+  };
+  /** First in-scope file[] entry that matched — null for the text fallback. */
+  file: string | null;
+  viaText: boolean;
+}
+
+export function renderKnownTraps(
+  worktree: string,
+  cwd: string,
+  roots: string[],
+  scoped: boolean,
+): { lines: string[]; matched: number; lacked: number } {
+  const empty = { lines: [], matched: 0, lacked: 0 };
+  try {
+    const { rows, filesFound } = readMemLog(worktree);
+    if (filesFound === 0 || rows.length === 0) return empty;
+
+    const scopeFiles = new Set<string>();
+    for (const r of roots)
+      for (const f of scopeSourceFiles(r)) scopeFiles.add(relative(cwd, f));
+    if (scopeFiles.size === 0) return empty;
+    const scopeKeys = roots
+      .map((r) => relative(cwd, r))
+      .filter((k) => k !== "" && k !== ".");
+
+    const hits: TrapHit[] = [];
+    for (const row of rows) {
+      if (row.kind !== "bug" && row.kind !== "decision") continue;
+      const files = row.files ?? [];
+      const inScope = files.find((f) => scopeFiles.has(f));
+      if (inScope) {
+        hits.push({ row, file: inScope, viaText: false });
+        continue;
+      }
+      // Fallback: only a row with NO files[] — see comment above.
+      if (files.length === 0 && scoped) {
+        const hay = `${row.text}\n${row.spec ?? ""}`;
+        if (scopeKeys.some((k) => hay.includes(k))) {
+          hits.push({ row, file: null, viaText: true });
+        }
+      }
+    }
+    if (hits.length === 0) return empty;
+
+    // Stable sort: bug before decision, recency preserved inside each kind.
+    hits.sort((a, b) =>
+      a.row.kind === b.row.kind ? 0 : a.row.kind === "bug" ? -1 : 1,
+    );
+    const lacked = hits.filter((h) => h.viaText).length;
+    const lines = [
+      "## Known traps (fapony mem)",
+      "",
+      `- ${hits.length} relevant row(s) on this scope (${lacked} lacked files[]${lacked > 0 ? " — matched via text" : ""})`,
+    ];
+    for (const h of hits.slice(0, MAX_TRAP_ROWS)) {
+      const text =
+        h.row.text.length > MEM_TEXT_MAX
+          ? `${h.row.text.slice(0, MEM_TEXT_MAX - 1)}…`
+          : h.row.text;
+      lines.push(
+        `- ${h.row.ts.slice(0, 10)} ${h.row.kind} — ${text}${h.file ? ` (${h.file})` : ""}`,
+      );
+    }
+    if (hits.length > MAX_TRAP_ROWS) {
+      lines.push(
+        `- … +${hits.length - MAX_TRAP_ROWS} more at cap ${MAX_TRAP_ROWS} (bug first, then decision)`,
+      );
+    }
+    return { lines, matched: hits.length, lacked };
+  } catch {
+    return empty; // no mem log / unreadable = a seed with no traps, never an error
+  }
+}
+
 // --- CLI entry ---
 
 export function cmdPlanSeed(args: string[]): void {
-  const usage = "usage: fapony plan-seed <name> [--spec] [--scope <path>]...";
+  const usage =
+    "usage: fapony plan-seed <name> [--spec] [--scope <path>[,<path>]]...";
   // Positional parse, not args.find(!startsWith("--")) — a --scope VALUE is
   // a non-flag argument and must never be mistaken for the plan name.
   let name: string | undefined;
@@ -571,7 +681,20 @@ export function cmdPlanSeed(args: string[]): void {
         console.error(`plan-seed: --scope needs a path\n${usage}`);
         process.exit(1);
       }
-      scopeArgs.push(v);
+      // Agents expect `--scope a,b,c` — same comma shape as `--files` — so a
+      // comma list is split here instead of failing on a path that never is.
+      // A real repo dir can't contain a literal ",x" tail; any comma splits.
+      // Trim each segment too: `a, b` is the same habit as `a,b`, and the
+      // space must not become part of the path (PLAN-comma-x).
+      const syms = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (syms.length === 0) {
+        console.error(`plan-seed: --scope needs a path\n${usage}`);
+        process.exit(1);
+      }
+      scopeArgs.push(...syms);
       i++;
     } else if (a.startsWith("--")) {
       console.error(`plan-seed: unknown flag "${a}"\n${usage}`);
@@ -643,6 +766,7 @@ export function cmdPlanSeed(args: string[]): void {
   );
 
   let specLink: string | null = null;
+  let traps = { lines: [] as string[], matched: 0, lacked: 0 };
   if (withSpec) {
     const specDirAbs = join(cwd, specDir());
     const specPath = join(specDirAbs, `SPEC-${name}.md`);
@@ -652,6 +776,7 @@ export function cmdPlanSeed(args: string[]): void {
       );
       process.exit(1);
     }
+    traps = renderKnownTraps(worktree, cwd, roots, scoped);
     const chunks = buildChunks(roots, cwd);
     mkdirSync(specDirAbs, { recursive: true });
     writeFileSync(
@@ -662,6 +787,7 @@ export function cmdPlanSeed(args: string[]): void {
         requested.length > 0
           ? roots.map((r) => relative(cwd, r) || ".").join(", ")
           : null,
+        traps.lines,
       ),
     );
     specLink = `../${specDir().split("/").pop()}/SPEC-${name}.md`;
@@ -691,6 +817,13 @@ export function cmdPlanSeed(args: string[]): void {
   }
   writeFileSync(planPath, planBody);
   console.log(`wrote ${planPath}${specLink ? ` + SPEC-${name}.md` : ""}`);
+  // Measurement surface (plan §3): a silent section is indistinguishable from
+  // "no mem log" — say what was injected so a week of seeds is countable.
+  if (traps.matched > 0) {
+    console.log(
+      `Known traps: ${traps.matched} row(s) injected (${traps.lacked} lacked files[])`,
+    );
+  }
   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 { isAbsolute, join, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 import {
   buildGraph,
   collectSourceFiles,
@@ -29,7 +29,7 @@ import {
   isTestedThroughBarrels,
   isTestFile,
   SCAN_EXTS,
-} from "../analyze.js";
+} from "../analyze/index.js";
 import { extractBody, extractExports } from "../map.js";
 import { assertSafe } from "../safety.js";
 import { execGit, gitOk, gitValue, SeedError, SIG_MAX } from "./primitives.js";
@@ -61,7 +61,7 @@ const LOOKUP_OUTPUT_CAP = 120;
 const DISCLAIMER =
   "static graph only — seed is where to enter, not what is verified";
 const USAGE =
-  "usage: fapony review-seed [--staged | --commit <sha> | --range <a...b> | --files f1,f2,dir | --plan <PLAN.md>] [--body sym[,sym]] [--callers sym]";
+  "usage: fapony review-seed [--staged | --commit <sha> | --range <a...b> | --files f1,f2,dir | --plan <PLAN.md>] [--body sym[,sym]] [--callers sym[,sym]]";
 // --body / --callers are the executor's lookup, not the reviewer's seed: when
 // either is present the output is only those sections (plus worktree line and
 // disclaimer) — the standard sections would be a wall around the one answer.
@@ -82,13 +82,13 @@ type Scope =
 interface LookupFlags {
   /** --body sym[,sym] — declaration slices from the named file(s). */
   body: string[];
-  /** --callers sym — symbol→symbol grep over importer files. */
-  callers: string | null;
+  /** --callers sym[,sym] — symbol→symbol grep over importer files. */
+  callers: string[];
 }
 
 function parseLookup(args: string[]): LookupFlags {
   const body: string[] = [];
-  let callers: string | null = null;
+  const callers: string[] = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--body" || a === "--callers") {
@@ -97,29 +97,21 @@ function parseLookup(args: string[]): LookupFlags {
         throw new SeedError(`review-seed: ${a} needs a value\n${USAGE}`);
       }
       i++;
-      if (a === "--body") {
-        for (const s of v
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean)) {
-          if (!/^[A-Za-z_$][\w$]*$/.test(s)) {
-            throw new SeedError(`review-seed: invalid symbol: ${s}`);
-          }
-          body.push(s);
-        }
-        if (body.length === 0) {
-          throw new SeedError(`review-seed: --body needs a symbol\n${USAGE}`);
-        }
-      } else {
-        if (!/^[A-Za-z_$][\w$]*$/.test(v)) {
-          throw new SeedError(`review-seed: invalid symbol: ${v}`);
-        }
-        if (callers) {
-          throw new SeedError(
-            `review-seed: --callers takes one symbol\n${USAGE}`,
-          );
+      // Both flags take the same comma shape --files takes: split, trim,
+      // drop empties, validate each symbol (PLAN-comma-x).
+      const syms = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (syms.length === 0) {
+        throw new SeedError(`review-seed: ${a} needs a symbol\n${USAGE}`);
+      }
+      for (const s of syms) {
+        if (!/^[A-Za-z_$][\w$]*$/.test(s)) {
+          throw new SeedError(`review-seed: invalid symbol: ${s}`);
         }
-        callers = v;
+        if (a === "--body") body.push(s);
+        else callers.push(s);
       }
     }
   }
@@ -176,12 +168,32 @@ function parseScope(args: string[]): Scope {
     }
   }
   if (flags.length === 0) return { kind: "default" };
-  if (flags.length > 1) {
+  // Repeats of the SAME kind: --files occurrences merge into one scope list
+  // (an agent splitting a lookup across two --files tokens is the same shape
+  // as the comma list it already accepts); an identical scalar repeat is
+  // idempotent; a scalar repeated with a DIFFERENT value is ambiguous and
+  // errors — never last-wins (PLAN-comma-x chunk 2). The mixed-scope guard
+  // below counts distinct kinds, not occurrences, so `--files a --files b`
+  // is one scope, not "files, files".
+  const merged = new Map<string, Scope>();
+  for (const f of flags) {
+    const prev = merged.get(f.kind);
+    if (prev === undefined) {
+      merged.set(f.kind, f);
+    } else if (f.kind === "files" && prev.kind === "files") {
+      prev.list = [...new Set([...prev.list, ...f.list])];
+    } else if (JSON.stringify(prev) !== JSON.stringify(f)) {
+      throw new SeedError(
+        `review-seed: --${f.kind} given twice with different values\n${USAGE}`,
+      );
+    }
+  }
+  if (merged.size > 1) {
     throw new SeedError(
-      `review-seed: one scope flag at a time (got ${flags.map((f) => f.kind).join(", ")})\n${USAGE}`,
+      `review-seed: one scope flag at a time (got ${[...merged.keys()].join(", ")})\n${USAGE}`,
     );
   }
-  return flags[0];
+  return [...merged.values()][0];
 }
 
 // --- Scope resolution: one flag = one declared git call ---
@@ -376,6 +388,57 @@ function resolvePlanPath(arg: string, cwd: string, worktree: string): string {
   throw new SeedError(`review-seed: plan file not found: ${arg}`);
 }
 
+// Fallback commit resolution for --plan without files[] frontmatter.
+// Tries two sources in order:
+//   1. `> **Commits:** sha1 sha2 …` line in the plan header
+//   2. `git log --grep <PLAN-filename> --format=%h`
+// Returns the first source that yields commits, with metadata for the label.
+function isCommitObject(sha: string, cwd: string): boolean {
+  return execGit(`git cat-file -e ${sha}^{commit}`, cwd).ok;
+}
+
+function planFallbackCommits(
+  planText: string,
+  planBase: string,
+  cwd: string,
+): { sha: string; short: string; source: "header" | "git log grep" }[] {
+  // Source 1: > **Commits:** line in the plan header (first 2048 bytes)
+  const head = planText.slice(0, 2048);
+  const commitsLine = />\s*\*?\*?Commits:?\*?\*?\s+(.+)/i.exec(head);
+  if (commitsLine) {
+    const shas = commitsLine[1]
+      .match(/\b[0-9a-f]{7,12}\b/g)
+      ?.filter((s) => isCommitObject(s, cwd))
+      .map((s) => ({
+        sha: s,
+        short: s,
+        source: "header" as const,
+      }));
+    if (shas && shas.length > 0) return shas;
+  }
+  // Source 2: git log --grep for the plan name. Chunk commits cite the plan
+  // as "(PLAN-x chunk N)" — never with the .md suffix — so grep the stem:
+  // it still matches messages that do carry the suffix (substring).
+  const stem = planBase.replace(/\.md$/, "");
+  const logResult = execGit(
+    `git log --grep=${stem} --format=%h --max-count=10`,
+    cwd,
+  );
+  if (logResult.ok && logResult.output.trim()) {
+    const shas = logResult.output
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((s) => ({
+        sha: s,
+        short: s,
+        source: "git log grep" as const,
+      }));
+    if (shas.length > 0) return shas;
+  }
+  return [];
+}
+
 function resolveScope(
   scope: Scope,
   cwd: string,
@@ -394,15 +457,33 @@ function resolveScope(
   }
   if (scope.kind === "plan") {
     const planPath = resolvePlanPath(scope.path, cwd, worktree);
-    const planFiles = planFrontFiles(readFileSync(planPath, "utf-8"));
+    const planText = readFileSync(planPath, "utf-8");
+    const planFiles = planFrontFiles(planText);
     if (planFiles === null) {
-      // No files[] to scope from — fall back to the default diff, say so.
+      // No files[] — try fallback commit sources before default diff.
+      const planBase = basename(planPath);
+      const fallbackCommits = planFallbackCommits(planText, planBase, cwd);
+      if (fallbackCommits.length > 0) {
+        // Use the fallback commits as the scope: get the files touched by those commits.
+        const shaList = fallbackCommits.map((c) => c.sha).join(" ");
+        const entries = parseNumstat(
+          execGit(`git diff-tree --no-commit-id --numstat -r ${shaList}`, cwd)
+            .output,
+        );
+        const source = fallbackCommits[0].source;
+        return {
+          label: `--plan ${scope.path} (commits via ${source}: ${fallbackCommits.map((c) => c.short).join(", ")})`,
+          entries,
+        };
+      }
+      // No commits found either — fall back to the default diff, say so.
       const entries = [
         ...parseNumstat(execGit("git diff HEAD --numstat -M", cwd).output),
         ...untrackedFiles(execGit("git status --porcelain -uall", cwd).output),
       ];
       return {
-        label: "--plan (no files: frontmatter) — diff HEAD + untracked",
+        label:
+          "--plan (no files: frontmatter, no commits found) — diff HEAD + untracked",
         entries,
       };
     }
@@ -597,7 +678,7 @@ function renderLookup(
   lines.push(`worktree: ${worktree} (${lookupLabel(flags)})`);
 
   let resolved: ResolvedScope | null = null;
-  if (flags.callers) {
+  if (flags.callers.length > 0) {
     resolved = resolveScope(scope, cwd, worktree);
   }
 
@@ -626,7 +707,7 @@ function renderLookup(
       } catch {
         continue;
       }
-      const scan = extractExports(source);
+      const scan = extractExports(source, undefined, path);
       if (scan.error) continue;
       for (const sym of scan.symbols) {
         if (!flags.body.includes(sym.name)) continue;
@@ -651,30 +732,34 @@ function renderLookup(
     }
   }
 
-  if (flags.callers) {
+  if (flags.callers.length > 0) {
     const graph = buildGraph(worktree);
     const targets = (resolved?.entries ?? [])
       .map((e) => e.path)
       .filter(hasGraph);
-    const found = findCallers(flags.callers, targets, graph, worktree);
-    if (targets.length === 0) {
-      lines.push(`callers of ${flags.callers}: no source files in scope`);
-    } else if (found.rows.length === 0) {
-      lines.push(
-        `callers of ${flags.callers}: none found in static importers (dynamic or non-importing use is out of reach)`,
-      );
-    } else {
-      lines.push(
-        `callers of ${flags.callers} (textual hits, may be comments/strings):`,
-      );
-      for (const f of found.rows) {
-        const more = f.more > 0 ? ` (+${f.more} more hits)` : "";
-        lines.push(`  ${f.file}:${f.hits.join(",")}${more}`);
-      }
-      if (found.filesCapped) {
+    // One section per symbol — a merged any-of scan would lose which
+    // symbol hit, and a single symbol's output stays byte-identical.
+    for (const sym of flags.callers) {
+      const found = findCallers(sym, targets, graph, worktree);
+      if (targets.length === 0) {
+        lines.push(`callers of ${sym}: no source files in scope`);
+      } else if (found.rows.length === 0) {
         lines.push(
-          `  ⚠ more importer files matched — capped at ${MAX_CALLER_FILES}`,
+          `callers of ${sym}: none found in static importers (dynamic or non-importing use is out of reach)`,
         );
+      } else {
+        lines.push(
+          `callers of ${sym} (textual hits, may be comments/strings):`,
+        );
+        for (const f of found.rows) {
+          const more = f.more > 0 ? ` (+${f.more} more hits)` : "";
+          lines.push(`  ${f.file}:${f.hits.join(",")}${more}`);
+        }
+        if (found.filesCapped) {
+          lines.push(
+            `  ⚠ more importer files matched — capped at ${MAX_CALLER_FILES}`,
+          );
+        }
       }
     }
   }
@@ -686,7 +771,9 @@ function renderLookup(
 function lookupLabel(flags: LookupFlags): string {
   const parts: string[] = [];
   if (flags.body.length > 0) parts.push(`--body ${flags.body.join(",")}`);
-  if (flags.callers) parts.push(`--callers ${flags.callers}`);
+  if (flags.callers.length > 0) {
+    parts.push(`--callers ${flags.callers.join(",")}`);
+  }
   return parts.join(" ");
 }
 
@@ -709,7 +796,7 @@ export function renderSeed(args: string[], cwd: string): string {
   // feeds --callers its targets), but the standard sections are suppressed —
   // the caller asked for one answer, not the review seed around it.
   const lookup = parseLookup(args);
-  if (lookup.body.length > 0 || lookup.callers) {
+  if (lookup.body.length > 0 || lookup.callers.length > 0) {
     return renderLookup(lookup, scope, cwd, worktree);
   }
 
@@ -815,7 +902,7 @@ export function renderSeed(args: string[], cwd: string): string {
       } catch {
         continue;
       }
-      const scan = extractExports(source);
+      const scan = extractExports(source, undefined, e.path);
       if (scan.error) {
         sigLines.push(`  ${e.path} — ⚠ ${scan.error}`);
         continue;

package/templates/PLAN.md

@@ -51,6 +51,7 @@ Table with 3–5 rows: risk | likelihood | impact | escape hatch
 1. **<Step 1>** — has a clear deliverable
 2. **<Step 2>** — ...
 Each step must be verifiable before moving to the next
+A step needing state the system doesn't store yet must say where it lives, who writes it, who reads it
 
 ## 7. Examples (make it concrete)
 bash examples: before / after — **link into spec/, don't paste it.**