fapony 0.3.0 → 0.3.3

package/src/mem/index.ts

@@ -4,13 +4,7 @@
 // Now an export function called by fapony.ts, not a standalone script.
 
 import { cmdPlanCheck, cmdPlanSweep } from "./commands/plan.js";
-import {
-  cmdDone,
-  cmdFind,
-  cmdKickoff,
-  cmdNow,
-  cmdStale,
-} from "./commands/read.js";
+import { cmdDone, cmdFind, cmdKickoff, cmdStale } from "./commands/read.js";
 import { cmdRotate } from "./commands/rotate.js";
 import { cmdWhere } from "./commands/where.js";
 import {
@@ -30,7 +24,7 @@ subcommands:
   add <kind> "<text>" --files f1,f2 [spec.md]
   close <id> "<msg>"          close a bug
   find "<text>"               substring-search every row
-  now | done | stale          views
+  done | stale              views
   claim <id> | release <id> | synced   bookkeeping
   plan-sweep [<plan.md> [--apply]]     move shipped plans + fix links
   plan-check <plan.md>        validate a plan's frontmatter/sections
@@ -62,9 +56,6 @@ 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"`,
-  now: `usage: fapony mem now
-next + bug + hold still open (decision/note are search-only — use find)
-example: fapony mem now`,
   done: `usage: fapony mem done
 closed rows with their tombstone message
 example: fapony mem done`,
@@ -138,7 +129,7 @@ export async function cmdMem(a: string[], memDir?: string): Promise<void> {
   } else if (cmd === "rotate") {
     cmdRotate(rest);
   } else {
-    // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
-    cmdNow();
+    // bare `fapony mem` → kickoff (ranked session overview)
+    cmdKickoff(rest);
   }
 }

package/src/{plan-seed.ts → seed/plan-seed.ts}

@@ -1,4 +1,4 @@
-// src/plan-seed.ts — `fapony plan-seed <name> [--spec] [--scope <path>]...`
+// src/seed/plan-seed.ts — `fapony plan-seed <name> [--spec] [--scope <path>]...`
 //
 // Writes PLAN + SPEC straight into planDir/specDir. What it pre-fills is the
 // structure (frontmatter, the 8 sections, prior art, ledger context) — the
@@ -25,7 +25,6 @@
 //
 // Composes existing producers — no new parsing, no new table, no MCP tool.
 
-import { execSync } from "node:child_process";
 import {
   existsSync,
   mkdirSync,
@@ -35,15 +34,16 @@ import {
   writeFileSync,
 } 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 { doneDir, planDir, specDir } from "./db/getters.js";
-import { CONFIG_FILENAME } from "./db/index.js";
-import { loadConfig } from "./db/load.js";
-import type { Config } from "./db/types.js";
-import { extractExports } from "./map.js";
-import { readRecentMemDecisions } from "./memory.js";
-import { getStatsData } from "./stats/data.js";
+import { collectSourceFiles, isSkippedDir, SCAN_EXTS } from "../analyze.js";
+import { computeModelFit } from "../context/projectHealth.js";
+import { doneDir, planDir, specDir } from "../db/getters.js";
+import { CONFIG_FILENAME } from "../db/index.js";
+import { loadConfig } from "../db/load.js";
+import type { Config } from "../db/types.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
 // reading task, and the whole-SPEC cap below does the final trim.
@@ -56,7 +56,6 @@ 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;
-const SIG_MAX = 90;
 // Anchor-safe slug: lowercase, non-alphanumerics → dash.
 const slug = (s: string): string =>
   s
@@ -224,7 +223,7 @@ 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 · \`verdict_submit\` (MCP) with this step's \`regime\` · then hand off:
+files only · then hand off:
 
 \`\`\`bash
 fapony mem add note "<what chunk N+1 must know>" --files <f1,f2> ${planRel}
@@ -257,16 +256,6 @@ interface Chunk {
   body: string;
 }
 
-// review-seed's cap shape: keep the head, always say how much was cut — a
-// silent cut is indistinguishable from "that was everything".
-function capLines(lines: string[], cap: number, what: string): string[] {
-  if (lines.length <= cap) return lines;
-  const rest = lines.length - (cap - 1);
-  const kept = lines.slice(0, cap - 1);
-  kept.push(`… +${rest} more ${what}`);
-  return kept;
-}
-
 function capChunk(c: Chunk): Chunk {
   return {
     ...c,
@@ -530,15 +519,8 @@ export function cmdPlanSeed(args: string[]): void {
   // state.db uses (git rev-parse --show-toplevel). Running from a subdir
   // would otherwise mismatch: stats return empty, Context (fapony) always
   // prints "(not enough graded history yet)".
-  let worktree: string;
-  try {
-    worktree = execSync("git rev-parse --show-toplevel", {
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim();
-  } catch {
-    worktree = cwd;
-  }
+  const root = execGit("git rev-parse --show-toplevel", cwd);
+  const worktree = root.ok ? root.output.split("\n")[0] : cwd;
 
   // Scope: explicit paths win; default is the cwd. Resolved absolutes,
   // deduped — the same path twice is one scope. Nested roots are pruned:

package/src/seed/primitives.ts

@@ -0,0 +1,66 @@
+// src/seed/primitives.ts — shared helpers for plan-seed + review-seed
+//
+// Git execution, output capping, signature formatting — the pieces both
+// commands need. §0 rule: add-only — never remove or rename exported symbols.
+
+import { execSync } from "node:child_process";
+
+// --- Error class ---
+
+export class SeedError extends Error {}
+
+// --- Git helpers ---
+
+export function execGit(
+  cmd: string,
+  cwd: string,
+): { ok: boolean; output: string; error?: string } {
+  try {
+    const output = execSync(cmd, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 15_000,
+    });
+    return { ok: true, output: output.trim() };
+  } catch (e: unknown) {
+    const err = e as { stderr?: string; message?: string };
+    return {
+      ok: false,
+      output: "",
+      error: (err.stderr ?? err.message ?? "").trim(),
+    };
+  }
+}
+
+export function gitOk(r: { ok: boolean; error?: string }, cmd: string): void {
+  if (!r.ok)
+    throw new SeedError(`git failed: ${cmd}\n${r.error ?? "unknown error"}`);
+}
+
+// Values interpolated into a git command line must be plain refs/paths —
+// blocks shell metacharacters before execSync ever sees them.
+const GIT_VALUE_RE = /^[A-Za-z0-9._/{}^~+-]+$/;
+
+export function gitValue(kind: string, value: string): string {
+  if (!GIT_VALUE_RE.test(value)) {
+    throw new SeedError(`invalid ${kind}: ${value}`);
+  }
+  return value;
+}
+
+// --- Output capping ---
+
+// Keep the head, always say how much was cut — a silent cut is
+// indistinguishable from "that was everything".
+export function capLines(lines: string[], cap: number, what: string): string[] {
+  if (lines.length <= cap) return lines;
+  const rest = lines.length - (cap - 1);
+  const kept = lines.slice(0, cap - 1);
+  kept.push(`… +${rest} more ${what}`);
+  return kept;
+}
+
+// --- Signature formatting ---
+
+export const SIG_MAX = 90;

package/src/{review-seed.ts → seed/review-seed.ts}

@@ -1,4 +1,4 @@
-// src/review-seed.ts — `fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]`
+// src/seed/review-seed.ts — `fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]`
 //
 // Seeds a code review with the deterministic facts of the scope the agent
 // asked about: which files changed (per the exact git expression, echoed),
@@ -12,14 +12,13 @@
 // cite rule 5 "never write into a target worktree", dropped 2026-09-17 because
 // four commands broke it; being read-only was always a property of this
 // command, never of that rule. Facts only: nothing here says broken/fixed
-// — judgment lives in the reviewer and the ledger (verdict_submit), never in
+// — judgment lives in the reviewer and mem log, never in
 // this output. Deterministic: same input, same bytes, no LLM.
 //
 // Composes existing producers — buildGraph (analyze.ts) for importers/untested,
 // extractExports (map.ts) for signatures. One flag = one declared git call;
 // no magic parsing.
 
-import { execSync } from "node:child_process";
 import type { Stats } from "node:fs";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -30,9 +29,10 @@ import {
   isTestedThroughBarrels,
   isTestFile,
   SCAN_EXTS,
-} from "./analyze.js";
-import { extractBody, extractExports } from "./map.js";
-import { assertSafe } from "./safety.js";
+} from "../analyze.js";
+import { extractBody, extractExports } from "../map.js";
+import { assertSafe } from "../safety.js";
+import { execGit, gitOk, gitValue, SeedError, SIG_MAX } from "./primitives.js";
 
 const WRAP_WIDTH = 88;
 // The changed list is the review's scope boundary, not context: a file hidden
@@ -58,7 +58,6 @@ const LOOKUP_OUTPUT_CAP = 120;
 // files is already past "this component area" into "the whole tree" — cut
 // there and say so, a folder-shaped wall is not an answer either.
 // Signature text cap per symbol (same trim as map.ts's file view).
-const SIG_MAX = 90;
 const DISCLAIMER =
   "static graph only — seed is where to enter, not what is verified";
 const USAGE =
@@ -70,52 +69,6 @@ const MAX_BODY_LINES = 80;
 const MAX_CALLER_FILES = 12;
 const MAX_CALLER_HITS = 20;
 
-export class SeedError extends Error {}
-
-// --- Git helpers (same shape as collect.ts execGitSafe) ---
-
-function execGit(
-  cmd: string,
-  cwd: string,
-): { ok: boolean; output: string; error?: string } {
-  try {
-    const output = execSync(cmd, {
-      cwd,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 15_000,
-    });
-    return { ok: true, output: output.trim() };
-  } catch (e: unknown) {
-    const err = e as { stderr?: string; message?: string };
-    return {
-      ok: false,
-      output: "",
-      error: (err.stderr ?? err.message ?? "").trim(),
-    };
-  }
-}
-
-// A scope's primary git call failing must never masquerade as "nothing
-// changed" — surface it. merge-base failures are tolerated (label fallback).
-function gitOk(r: { ok: boolean; error?: string }, cmd: string): void {
-  if (!r.ok)
-    throw new SeedError(
-      `review-seed: git failed: ${cmd}\n${r.error ?? "unknown error"}`,
-    );
-}
-
-// Values interpolated into a git command line must be plain refs/paths —
-// blocks shell metacharacters before execSync ever sees them.
-const GIT_VALUE_RE = /^[A-Za-z0-9._/{}^~+-]+$/;
-
-function gitValue(kind: string, value: string): string {
-  if (!GIT_VALUE_RE.test(value)) {
-    throw new SeedError(`review-seed: invalid ${kind}: ${value}`);
-  }
-  return value;
-}
-
 // --- Scope flags: exactly one source of scope ---
 
 type Scope =
@@ -233,7 +186,7 @@ function parseScope(args: string[]): Scope {
 
 // --- Scope resolution: one flag = one declared git call ---
 
-interface FileEntry {
+export interface FileEntry {
   path: string;
   ins: number | null;
   del: number | null;

package/src/stats/data.ts

@@ -5,7 +5,6 @@ import { join } from "node:path";
 import { type Event, openDb, PLAN_DIR, type Run } from "../db/index.js";
 import { loadConfig } from "../db/load.js";
 import { enrichGateWindows } from "../gates.js";
-import { avg, minutesBetween } from "../math.js";
 import { REASON_CODES, REGIME_CODES } from "../mcp/types.js";
 import {
   isPassFamily,
@@ -20,6 +19,7 @@ import {
   readPassiveUsage,
   readZcodeUsage,
 } from "../session/index.js";
+import { avg, minutesBetween } from "../util.js";
 
 // Walks events per run in order and pairs up spawn→route (executor time)
 // and route→gate (review turnaround) per round, since one run row can span

package/src/telemetry.ts

@@ -17,8 +17,8 @@ import {
   type Run,
 } from "./db/index.js";
 import { enrichGateWindows } from "./gates.js";
-import { avg, minutesBetween } from "./math.js";
 import { readPassiveUsage } from "./session/index.js";
+import { avg, minutesBetween } from "./util.js";
 
 // ─── Schema version ────────────────────────────────────────────────────
 

package/src/util.ts

@@ -25,8 +25,69 @@ export function fillPrompt(
   return out;
 }
 
+/** Minutes between two ISO-like timestamps (space separator, UTC assumed). */
+export function minutesBetween(a: string, b: string): number {
+  const t0 = new Date(`${a.replace(" ", "T")}Z`).getTime();
+  const t1 = new Date(`${b.replace(" ", "T")}Z`).getTime();
+  return (t1 - t0) / 60000;
+}
+
+/** Arithmetic mean of a numeric array. 0 for empty arrays. */
+export function avg(xs: number[]): number {
+  return xs.length ? xs.reduce((s, x) => s + x, 0) / xs.length : 0;
+}
+
 /** True for "y"/"yes" (case-insensitive, trimmed) — the only affirmative answers. */
 export function isAffirmative(answer: string): boolean {
   const normalized = answer.trim().toLowerCase();
   return normalized === "y" || normalized === "yes";
 }
+
+// --- Recursive directory walker ---
+
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WalkDirOpts {
+  /** Max recursion depth (default 4). */
+  depth?: number;
+  /** Skip node_modules (default true). */
+  skipNodeModules?: boolean;
+  /** Dot-directories to descend into (default []). Others starting with . are skipped. */
+  includeDotDirs?: string[];
+  /** Extra filter: return true to collect this dir. Omit to collect all reached dirs. */
+  predicate?: (dirPath: string) => boolean;
+}
+
+/**
+ * Recursively walk directories under `root`.
+ * Returns absolute paths of dirs for which `predicate` returned true (or all
+ * reached dirs when no predicate is given). Skips node_modules by default.
+ */
+export function walkDir(root: string, opts?: WalkDirOpts): string[] {
+  const maxDepth = opts?.depth ?? 4;
+  const skipNm = opts?.skipNodeModules ?? true;
+  const includeDot = new Set(opts?.includeDotDirs ?? []);
+  const pred = opts?.predicate;
+  const result: string[] = [];
+
+  const walk = (dir: string, depth: number): void => {
+    if (depth > maxDepth) return;
+    if (!pred || pred(dir)) result.push(dir);
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        if (entry.isSymbolicLink()) continue;
+        if (skipNm && entry.name === "node_modules") continue;
+        if (entry.name.startsWith(".") && !includeDot.has(entry.name)) {
+          continue;
+        }
+        walk(join(dir, entry.name), depth + 1);
+      }
+    } catch {
+      // ignore unreadable dirs
+    }
+  };
+  walk(root, 0);
+  return result;
+}

package/templates/SPEC.md

@@ -14,11 +14,18 @@
 
 ---
 
+## Non-goals
+What this explicitly does **not** do, one line of why each. Widening scope is an
+agent's default; a spec that only says what to build never stopped anything.
+
 ## Shape (data / API / schema)
 Concrete types, request/response bodies, DB columns — whatever the code needs.
 
 ## Edge cases
-Table or bullets: input → expected behavior.
+Three columns: input → expected → **verify** (a command that actually runs).
+An edge case with no check after it is an opinion, not a requirement — and a
+verify built from a substring of the prose is not a verify (real case: `grep "sed"`
+matched "superseded", so the check passed while the work was missing).
 
 ## Examples
 Before / after, request / response, sample payloads — as long as it needs to be.

package/src/math.ts

@@ -1,13 +0,0 @@
-// src/math.ts — pure numeric helpers shared across modules
-
-/** Minutes between two ISO-like timestamps (space separator, UTC assumed). */
-export function minutesBetween(a: string, b: string): number {
-  const t0 = new Date(`${a.replace(" ", "T")}Z`).getTime();
-  const t1 = new Date(`${b.replace(" ", "T")}Z`).getTime();
-  return (t1 - t0) / 60000;
-}
-
-/** Arithmetic mean of a numeric array. 0 for empty arrays. */
-export function avg(xs: number[]): number {
-  return xs.length ? xs.reduce((s, x) => s + x, 0) / xs.length : 0;
-}

package/src/mcp/tools/verdict.ts

@@ -1,161 +0,0 @@
-// src/mcp/tools/verdict.ts — verdict_submit tool
-
-import {
-  findOpenRun,
-  findOpenRunWithNullPlan,
-  getRun,
-  newRun,
-  openDb,
-  patchLastGateEvent,
-} from "../../db/index.js";
-import { gateOnce } from "../../gate.js";
-import { VERDICT_GRADES, type VerdictGrade } from "../../parse.js";
-import {
-  errorResult,
-  jsonResult,
-  REASON_CODES,
-  REGIME_CODES,
-  type ReasonCode,
-  type RegimeCode,
-  type ToolResult,
-} from "../types.js";
-import { resolveWorktreeArg } from "../worktree.js";
-
-// --- Tool implementation ---
-
-export function toolVerdictSubmit(args: Record<string, unknown>): ToolResult {
-  const {
-    run_id,
-    verdict,
-    reason_code,
-    regime,
-    note,
-    worktree,
-    plan,
-    session_id,
-    files,
-  } = args;
-
-  if (typeof verdict !== "string" || !VERDICT_GRADES.has(verdict)) {
-    return errorResult(
-      `verdict must be one of: ${[...VERDICT_GRADES].join(", ")}`,
-    );
-  }
-  const grade = verdict as VerdictGrade;
-  if (!REASON_CODES.includes(reason_code as ReasonCode)) {
-    return errorResult(
-      `reason_code must be one of: ${REASON_CODES.join(", ")}`,
-    );
-  }
-  if (reason_code === "other" && (!note || typeof note !== "string")) {
-    return errorResult("reason_code 'other' requires a note");
-  }
-  if (!REGIME_CODES.includes(regime as RegimeCode)) {
-    return errorResult(`regime must be one of: ${REGIME_CODES.join(", ")}`);
-  }
-  const regimeCode = regime as RegimeCode;
-
-  const db = openDb();
-
-  // Resolve or create run_id
-  let resolvedRunId: number;
-  if (typeof run_id === "number" && Number.isInteger(run_id)) {
-    const run = getRun(db, run_id);
-    if (!run) {
-      return jsonResult({ stored: false, error: "run not found" });
-    }
-    resolvedRunId = run_id;
-  } else {
-    // Bind to the latest still-open run for the same worktree+plan so a
-    // round-2+ verdict lands on the original row (round keeps counting and
-    // review.maxRounds can actually trigger). Only when no open run matches
-    // is a fresh row created. plan=null always opens a new run (no guess).
-    // Free-text plans are normalized (trim+lowercase) so "Fix Login" and
-    // "fix login" bind to the same run. When no exact match exists, falls
-    // back to any open run with plan=null (the "no PLAN file" flow).
-    const resolvedWorktree =
-      typeof worktree === "string" && worktree
-        ? resolveWorktreeArg(worktree)
-        : "mcp-external";
-    const resolvedPlan =
-      typeof plan === "string" && plan ? plan.trim().toLowerCase() : null;
-    // BEGIN IMMEDIATE makes the find-then-create below atomic across
-    // concurrent MCP processes: without it, two agents closing the same
-    // worktree+plan at once can both see "no open run" and each insert a
-    // row. The write lock taken here blocks (busy_timeout, not throws) the
-    // second caller until the first commits, so it re-reads and finds the
-    // row already there instead of duplicating it.
-    db.run("BEGIN IMMEDIATE");
-    try {
-      let open = resolvedPlan
-        ? findOpenRun(db, resolvedWorktree, resolvedPlan)
-        : null;
-      // Fallback: if no exact match and plan is non-null, try any open run with
-      // plan=null.  This lets a verdict with free-text intent bind to a run that
-      // was created without a plan (the common "no PLAN file" flow).
-      if (!open && resolvedPlan) {
-        open = findOpenRunWithNullPlan(db, resolvedWorktree);
-      }
-      if (open) {
-        resolvedRunId = open.id;
-      } else {
-        // worktree/plan let callers (e.g. move-to-done) attribute the verdict
-        // so byReasonCode/bestPassing aggregate correctly instead of collapsing
-        // into "mcp-external".
-        resolvedRunId = newRun(db, resolvedWorktree, resolvedPlan, null, "mcp");
-      }
-      db.run("COMMIT");
-    } catch (e) {
-      db.run("ROLLBACK");
-      throw e;
-    }
-  }
-
-  // Normalize files: must be a non-empty array of strings.
-  const resolvedFiles =
-    Array.isArray(files) && files.length > 0
-      ? files.filter((f): f is string => typeof f === "string" && f.length > 0)
-      : undefined;
-
-  // Route through gateOnce for consistent status/round/memory handling.
-  const mcpNote =
-    typeof note === "string" && note
-      ? `[${reason_code}] ${note}`
-      : `[${reason_code}]`;
-  const result = gateOnce(resolvedRunId, grade, mcpNote, resolvedFiles);
-
-  if (result.error) {
-    return jsonResult({
-      stored: false,
-      error: result.error,
-      run_id: resolvedRunId,
-      status: result.status,
-      round: result.round,
-    });
-  }
-
-  // Patch the gate event with MCP-specific fields (reason_code, source).
-  // session_id lets gates.ts resolve model from client session logs when the
-  // window has no spawn events (the old execute→review loop that wrote spawns
-  // is gone). Optional — agents that can't expose it just omit it.
-  const patch: Record<string, unknown> = {
-    reason_code,
-    regime: regimeCode,
-    source: "mcp",
-  };
-  if (typeof session_id === "string" && session_id) {
-    patch.session_id = session_id;
-  }
-  patchLastGateEvent(db, resolvedRunId, patch);
-
-  return jsonResult({
-    stored: true,
-    run_id: resolvedRunId,
-    verdict: grade,
-    reason_code,
-    regime: regimeCode,
-    status: result.status,
-    round: result.round,
-    ...(resolvedFiles ? { files: resolvedFiles } : {}),
-  });
-}