fapony 0.1.3 → 0.2.1

package/src/plan-seed.ts

@@ -38,6 +38,7 @@ 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";
@@ -97,7 +98,7 @@ function renderPriorArt(cwd: string, config: Config, roots: string[]): string {
   if (keys.length === 0) return placeholder;
 
   const hits: { shipped: string; line: string }[] = [];
-  for (const dir of [doneDir(config), specDir(config)]) {
+  for (const dir of [doneDir(config), specDir()]) {
     const abs = join(cwd, dir);
     let names: string[];
     try {
@@ -181,6 +182,7 @@ function planTemplate(
   priorArt: string,
   contextFapony: string,
   specLink: string | null,
+  planRel: string,
 ): string {
   return `---
 kind: unit
@@ -216,8 +218,20 @@ _(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.
+
 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:
+
+\`\`\`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).
+
 ## 7. Examples
 ${
   specLink
@@ -511,7 +525,7 @@ export function cmdPlanSeed(args: string[]): void {
     process.exit(1);
   }
   const cwd = process.cwd();
-  const config = loadConfig(join(cwd, "fapony.config.json"));
+  const config = loadConfig(join(cwd, CONFIG_FILENAME));
   // Resolve the git worktree root so mem/ledger queries hit the same key
   // state.db uses (git rev-parse --show-toplevel). Running from a subdir
   // would otherwise mismatch: stats return empty, Context (fapony) always
@@ -555,7 +569,7 @@ export function cmdPlanSeed(args: string[]): void {
     );
   }
 
-  const planDirAbs = join(cwd, planDir(config));
+  const planDirAbs = join(cwd, planDir());
   const planPath = join(planDirAbs, `PLAN-${name}.md`);
   if (existsSync(planPath)) {
     console.error(
@@ -569,7 +583,7 @@ export function cmdPlanSeed(args: string[]): void {
 
   let specLink: string | null = null;
   if (withSpec) {
-    const specDirAbs = join(cwd, specDir(config));
+    const specDirAbs = join(cwd, specDir());
     const specPath = join(specDirAbs, `SPEC-${name}.md`);
     if (existsSync(specPath)) {
       console.error(
@@ -589,13 +603,19 @@ export function cmdPlanSeed(args: string[]): void {
           : null,
       ),
     );
-    specLink = `../${specDir(config).split("/").pop()}/SPEC-${name}.md`;
+    specLink = `../${specDir().split("/").pop()}/SPEC-${name}.md`;
   }
 
   mkdirSync(planDirAbs, { recursive: true });
   writeFileSync(
     planPath,
-    planTemplate(name, priorArt, contextFapony, specLink),
+    planTemplate(
+      name,
+      priorArt,
+      contextFapony,
+      specLink,
+      `${planDir()}/PLAN-${name}.md`,
+    ),
   );
   console.log(`wrote ${planPath}${specLink ? ` + SPEC-${name}.md` : ""}`);
 }

package/src/review-seed.ts

@@ -270,6 +270,10 @@ function expandFilesScope(
   const notFound: string[] = [];
   const emptyDirs: string[] = [];
   const dirs: string[] = [];
+  // Per-dir top-level subdir counts, gathered while walking — cheap because
+  // it reuses `rels` already collected below; only printed if the cap cuts
+  // something, so a scope that fits never pays for it in the output.
+  const breakdowns: string[] = [];
   let dirExpanded = false;
   let cutNamed = 0;
   let cutExpanded = 0;
@@ -310,6 +314,20 @@ function expandFilesScope(
     dirExpanded = true;
     const rels = collectSourceFiles(join(worktree, p));
     if (rels.length === 0) emptyDirs.push(p);
+    if (rels.length > MAX_CHANGED_FILES) {
+      const counts = new Map<string, number>();
+      for (const r of rels) {
+        const top = r.includes("/") ? r.slice(0, r.indexOf("/")) : "(root)";
+        counts.set(top, (counts.get(top) ?? 0) + 1);
+      }
+      const list = [...counts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(
+          ([name, count]) => `${p === "." ? name : `${p}/${name}`} (${count})`,
+        )
+        .join(" · ");
+      breakdowns.push(`${p} (${rels.length} files) → ${list}`);
+    }
     for (const r of rels) add(p === "." ? r : `${p}/${r}`, true);
   }
   if (notFound.length > 0) {
@@ -329,6 +347,7 @@ function expandFilesScope(
     notes.push(
       `… +${cutExpanded} more file(s) under the expanded dirs — capped at ${MAX_CHANGED_FILES}, narrow the scope`,
     );
+    for (const b of breakdowns) notes.push(`  ${b}`);
   }
   return { files, notes, dirExpanded };
 }

package/src/setup.ts

@@ -6,7 +6,7 @@ import { existsSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { seedConventionsFile } from "./conventions-seed.js";
-import { DEFAULT_MEMORY_ENTRY } from "./db/index.js";
+import { CONFIG_FILENAME, FAPONY_DIR } from "./db/index.js";
 import { initProject } from "./init.js";
 import { isAffirmative } from "./util.js";
 
@@ -78,12 +78,11 @@ export function buildSetupConfig(a: SetupAnswers): Record<string, unknown> {
   };
 
   if (a.enableMemory) {
-    const memEntry = DEFAULT_MEMORY_ENTRY;
     config.memory = {
-      claim: ["bun", memEntry, "claim", "{id}"],
-      close: ["bun", memEntry, "close", "{id}", "{msg}"],
-      add: ["bun", memEntry, "add", "{kind}", "{text}"],
-      kickoff: ["bun", memEntry, "kickoff"],
+      claim: ["fapony", "mem", "claim", "{id}"],
+      close: ["fapony", "mem", "close", "{id}", "{msg}"],
+      add: ["fapony", "mem", "add", "{kind}", "{text}"],
+      kickoff: ["fapony", "mem", "kickoff"],
     };
   }
 
@@ -183,7 +182,7 @@ export async function cmdSetup(deps: SetupDeps = {}): Promise<void> {
       enableMemory,
     });
 
-    const configPath = join(process.cwd(), "fapony.config.json");
+    const configPath = join(process.cwd(), CONFIG_FILENAME);
     if (existsSync(configPath)) {
       const overwrite = await askFn(
         "⚠  fapony.config.json already exists. Overwrite? (y/n)",
@@ -199,7 +198,7 @@ export async function cmdSetup(deps: SetupDeps = {}): Promise<void> {
     console.log(`\n  ✓  Wrote ${configPath}`);
 
     // --- scaffold worktree ---
-    const faponyDir = join(worktreePath, ".fapony");
+    const faponyDir = join(worktreePath, FAPONY_DIR);
     if (!existsSync(faponyDir)) {
       try {
         initProject(worktreePath);

package/src/stats/data.ts

@@ -1,9 +1,8 @@
 // src/stats/data.ts — StatsData shape + getStatsData()
 
-import { readdirSync, readFileSync } from "node:fs";
+import { readdirSync } from "node:fs";
 import { join } from "node:path";
-
-import { type Event, openDb, type Run } from "../db/index.js";
+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";
@@ -89,9 +88,7 @@ function enrichGates(
 /**
  * Count un-shipped plan files in a worktree's planDir.
  *
- * Reads the *target repo's own* fapony.config.json for `paths.planDir` — the
- * central config's worktrees map is optional and usually absent, and each repo
- * picks its own plan dir (vela uses apps/vela/plan, not .fapony/plan).
+ * planDir is hardcoded to .fapony/plan — not configurable (gitignored = private).
  *
  * Returns null — never 0 — when the path isn't a readable directory, so a
  * sentinel row like "mcp-external" renders as "—" instead of claiming
@@ -99,19 +96,10 @@ function enrichGates(
  */
 export function countPendingPlans(worktree: string): number | null {
   if (!worktree.startsWith("/")) return null;
-  let planDir = ".fapony/plan";
   try {
-    const cfg = JSON.parse(
-      readFileSync(join(worktree, "fapony.config.json"), "utf8"),
-    ) as { paths?: { planDir?: unknown } };
-    if (typeof cfg.paths?.planDir === "string" && cfg.paths.planDir)
-      planDir = cfg.paths.planDir;
-  } catch {
-    // no config (or unreadable/malformed) — fall back to the scaffold default
-  }
-  try {
-    return readdirSync(join(worktree, planDir)).filter((f) => f.endsWith(".md"))
-      .length;
+    return readdirSync(join(worktree, PLAN_DIR)).filter((f) =>
+      f.endsWith(".md"),
+    ).length;
   } catch {
     return null;
   }
@@ -397,72 +385,6 @@ export function getPlanBreakdown(
     .sort((a, b) => b.runs - a.runs);
 }
 
-export interface PlanLastVerdict {
-  plan: string;
-  runs: number;
-  lastVerdict: string;
-  /** null for a pass-family last verdict (gateReason only flags non-pass). */
-  lastReasonCode: string | null;
-  escalated: boolean;
-}
-
-/**
- * Most recent gate verdict per plan string, for `plan_list` (mcp/tools/plans.ts)
- * to join filesystem plan files against real run history — "2 runs, last:
- * fail(spec_gap)" instead of a bare directory listing.
- */
-export function getLastVerdictByPlan(
-  runs: Run[],
-  events: Event[],
-  maxRounds: number,
-): PlanLastVerdict[] {
-  const runById = new Map(runs.map((r) => [r.id, r]));
-  const runCounts = new Map<string, number>();
-  const escalatedPlans = new Set<string>();
-  for (const r of runs) {
-    if (!r.plan) continue;
-    runCounts.set(r.plan, (runCounts.get(r.plan) ?? 0) + 1);
-    if (r.round > maxRounds) escalatedPlans.add(r.plan);
-  }
-
-  const lastGateByPlan = new Map<
-    string,
-    { ts: string; verdict: string; reason: string | null }
-  >();
-  for (const e of events) {
-    if (e.kind !== "gate" || !e.data) continue;
-    const plan = runById.get(e.run_id)?.plan;
-    if (!plan) continue;
-    let verdict: string | null = null;
-    try {
-      const d = JSON.parse(e.data) as { verdict?: unknown };
-      if (typeof d.verdict === "string") verdict = d.verdict;
-    } catch {
-      continue;
-    }
-    if (!verdict) continue;
-    const prev = lastGateByPlan.get(plan);
-    if (!prev || e.ts >= prev.ts) {
-      lastGateByPlan.set(plan, {
-        ts: e.ts,
-        verdict,
-        reason: gateReason(e.data),
-      });
-    }
-  }
-
-  return [...runCounts.keys()].map((plan) => {
-    const last = lastGateByPlan.get(plan);
-    return {
-      plan,
-      runs: runCounts.get(plan) ?? 0,
-      lastVerdict: last?.verdict ?? "(no gate yet)",
-      lastReasonCode: last?.reason ?? null,
-      escalated: escalatedPlans.has(plan),
-    };
-  });
-}
-
 /** Runs past the round cap — plan-quality signal, not code (CLAUDE.md #2). */
 function getEscalatedRuns(runs: Run[], maxRounds: number): EscalatedRun[] {
   return runs
@@ -600,25 +522,35 @@ export interface StatsData {
 }
 
 /**
- * Charge a session's token totals to a bucket exactly once.
+ * Charge a gate its share of its session's token total: 1/N, N = that
+ * session's gate count.
  *
- * Tokens are a per-session total, and one session routinely produces several
- * gates (measured here: 35 sessions behind 58 gates, up to 5 gates in one).
- * Summing per gate would multiply that session's tokens by its gate count —
- * unevenly across models, so the ranking itself would be wrong.
+ * Tokens are a per-session total and one session routinely produces several
+ * gates (measured here: 35 sessions behind 58 gates, up to 5 in one), so
+ * summing the full total per gate would multiply it by the gate count.
+ * Charging it once per bucket instead — what this did until 2026-09-19 — is
+ * right within one table and wrong across tables: a session spanning several
+ * regimes charged its whole total to every regime it touched. Measured then,
+ * claude-opus-5 totalled 218.5M input in by-model while its five by-regime
+ * rows summed to 847M (3.9x), and the inflation scaled with how many regimes
+ * a model was used in — so `--mode verdict` ranked the broadly-used models as
+ * the expensive ones. Shares sum back to the session total in every table,
+ * which is why by-model is unchanged by this: one session is one model, so
+ * its N shares land in a single bucket.
  */
-function addSessionTokens(
-  bucket: { seen: Set<string>; tokensInput: number; tokensOutput: number },
+function addGateTokenShare(
+  bucket: { tokensInput: number; tokensOutput: number },
   g: {
     sessionId: string | null;
     tokensInput: number | null;
     tokensOutput: number | null;
   },
+  gatesPerSession: Map<string, number>,
 ): void {
-  if (!g.sessionId || bucket.seen.has(g.sessionId)) return;
-  bucket.seen.add(g.sessionId);
-  if (g.tokensInput !== null) bucket.tokensInput += g.tokensInput;
-  if (g.tokensOutput !== null) bucket.tokensOutput += g.tokensOutput;
+  if (!g.sessionId) return;
+  const n = gatesPerSession.get(g.sessionId) ?? 1;
+  bucket.tokensInput += (g.tokensInput ?? 0) / n;
+  bucket.tokensOutput += (g.tokensOutput ?? 0) / n;
 }
 
 /**
@@ -733,6 +665,16 @@ export function getStatsData(worktree?: string): StatsData {
     // --- Gate enrichment ---
     const wtByRun = new Map(runs.map((r) => [r.id, r.worktree]));
     const enriched = enrichGates(events, wtByRun);
+    // Denominator for the per-gate token share — see addGateTokenShare.
+    const gatesPerSession = new Map<string, number>();
+    for (const g of enriched) {
+      if (g.sessionId) {
+        gatesPerSession.set(
+          g.sessionId,
+          (gatesPerSession.get(g.sessionId) ?? 0) + 1,
+        );
+      }
+    }
 
     // Group by worktree+client+provider+model+agent — the same model name on two
     // providers is two different things. Unknown dimension → "—" (never ""
@@ -749,7 +691,6 @@ export function getStatsData(worktree?: string): StatsData {
         fails: number;
         passes: number;
         qualities: number[];
-        seen: Set<string>;
         tokensInput: number;
         tokensOutput: number;
       }
@@ -771,7 +712,6 @@ export function getStatsData(worktree?: string): StatsData {
         fails: 0,
         passes: 0,
         qualities: [],
-        seen: new Set(),
         tokensInput: 0,
         tokensOutput: 0,
       });
@@ -780,7 +720,7 @@ export function getStatsData(worktree?: string): StatsData {
       if (g.verdict && isPassFamily(g.verdict)) bucket.passes++;
       const grade = g.verdict as VerdictGrade;
       if (VERDICT_GRADES.has(grade)) bucket.qualities.push(qualityScore(grade));
-      addSessionTokens(bucket, g);
+      addGateTokenShare(bucket, g, gatesPerSession);
     }
     const byModel = Object.values(modelMap)
       .map((b) => ({
@@ -846,7 +786,6 @@ export function getStatsData(worktree?: string): StatsData {
         fails: number;
         passes: number;
         qualities: number[];
-        seen: Set<string>;
         tokensInput: number;
         tokensOutput: number;
       }
@@ -864,7 +803,6 @@ export function getStatsData(worktree?: string): StatsData {
         fails: 0,
         passes: 0,
         qualities: [],
-        seen: new Set<string>(),
         tokensInput: 0,
         tokensOutput: 0,
       });
@@ -873,7 +811,7 @@ export function getStatsData(worktree?: string): StatsData {
       if (g.verdict && isPassFamily(g.verdict)) bucket.passes++;
       const grade = g.verdict as VerdictGrade;
       if (VERDICT_GRADES.has(grade)) bucket.qualities.push(qualityScore(grade));
-      addSessionTokens(bucket, g);
+      addGateTokenShare(bucket, g, gatesPerSession);
     }
     const byPlanMode = Object.values(planModeMap)
       .map((b) => ({
@@ -919,7 +857,6 @@ export function getStatsData(worktree?: string): StatsData {
         fails: number;
         passes: number;
         qualities: number[];
-        seen: Set<string>;
         tokensInput: number;
         tokensOutput: number;
       }
@@ -937,7 +874,6 @@ export function getStatsData(worktree?: string): StatsData {
         fails: 0,
         passes: 0,
         qualities: [],
-        seen: new Set<string>(),
         tokensInput: 0,
         tokensOutput: 0,
       });
@@ -946,7 +882,7 @@ export function getStatsData(worktree?: string): StatsData {
       if (g.verdict && isPassFamily(g.verdict)) bucket.passes++;
       const grade = g.verdict as VerdictGrade;
       if (VERDICT_GRADES.has(grade)) bucket.qualities.push(qualityScore(grade));
-      addSessionTokens(bucket, g);
+      addGateTokenShare(bucket, g, gatesPerSession);
     }
     const byRegime = Object.values(regimeMap)
       .map((b) => ({

package/src/stats/format.ts

@@ -192,28 +192,27 @@ export function formatStatsText(data: StatsData): string {
     }
   }
 
+  // No token columns here: cost per regime is what `--mode verdict` ranks on,
+  // and printing it twice invited reading this table as the cost answer when
+  // it is the coverage one. Quality and fails are what this table adds.
   if (data.byRegime.length > 0) {
     const showWt = !data.scope;
     lines.push("\nby regime:");
     if (showWt) {
       lines.push(
-        "  project | regime | model | gates | fails | failRate | tokens/pass | avgQuality | tokens/session",
+        "  project | regime | model | gates | fails | failRate | avgQuality",
       );
       lines.push(
-        "  ---------|--------|-------|-------|-------|----------|-------------|------------|----------------",
+        "  ---------|--------|-------|-------|-------|----------|------------",
       );
     } else {
-      lines.push(
-        "  regime | model | gates | fails | failRate | tokens/pass | avgQuality | tokens/session",
-      );
-      lines.push(
-        "  --------|-------|-------|-------|-------|----------|-------------|------------|----------------",
-      );
+      lines.push("  regime | model | gates | fails | failRate | avgQuality");
+      lines.push("  --------|-------|-------|-------|----------|------------");
     }
     for (const r of data.byRegime) {
       const wt = showWt ? `${shortWt(r.worktree).padEnd(9)} | ` : "";
       lines.push(
-        `  ${wt}${r.regime.padEnd(7)} | ${r.model.padEnd(5)} | ${String(r.gates).padStart(5)} | ${String(r.fails).padStart(5)} | ${fmtRate(r.failRate).padStart(8)} | ${fmtTokens(r.tokensPerPass).padStart(11)} | ${r.avgQuality.toFixed(1).padStart(10)} | ${fmtTokens(r.tokensInput).padStart(7)} in / ${fmtTokens(r.tokensOutput).padStart(7)} out`,
+        `  ${wt}${r.regime.padEnd(7)} | ${r.model.padEnd(5)} | ${String(r.gates).padStart(5)} | ${String(r.fails).padStart(5)} | ${fmtRate(r.failRate).padStart(8)} | ${r.avgQuality.toFixed(1).padStart(10)}`,
       );
     }
   }

package/src/stats/index.ts

@@ -3,7 +3,6 @@
 export { cmdStats, currentWorktree } from "./cli.js";
 export {
   countPendingPlans,
-  getLastVerdictByPlan,
   getPlanBreakdown,
   getStatsData,
   type PlanBreakdown,

package/templates/PLAN.md

@@ -11,6 +11,7 @@ blocked_by: <plan or sentence>    # required when status: blocked
 blocks: PLAN-<other>.md           # plans that cannot start until this one lands (comma-separated)
 superseded_by: PLAN-<other>.md    # required when status: superseded
 spec: SPEC-<feature>.md           # if any
+priority: high                    # optional: high = appears first in kickoff · omit = normal
 ---
 
 # PLAN-<feature>.md — <short name>

package/src/mcp/tools/context.ts

@@ -1,66 +0,0 @@
-// src/mcp/tools/context.ts — project_health_context tool
-//
-// Single call, any caller: returns the paste-ready "known patterns" block built
-// from real run history, keyed by files[] (no raw dump, ~15 lines max). Not a
-// pre-edit reflex — most files have no history (see CLAUDE.md rule 8); it earns
-// its call on a file that does. `plan-with-pony` is one caller, not the only one.
-//
-// It also surfaces project decisions from the mem log — that read is the only
-// I/O here; `buildProjectHealthContext` stays pure and just renders.
-
-import { blastRadiusForWorktree } from "../../analyze.js";
-import {
-  buildProjectHealthContext,
-  HUB_DEPENDENTS_MIN,
-  type HubEntry,
-} from "../../context/index.js";
-import { readRecentMemDecisions } from "../../memory.js";
-import { getStatsData } from "../../stats/index.js";
-import type { ToolResult } from "../types.js";
-
-export function toolProjectHealthContext(
-  args: Record<string, unknown>,
-): ToolResult {
-  const worktree =
-    typeof args.worktree === "string" && args.worktree
-      ? args.worktree
-      : undefined;
-  const files =
-    Array.isArray(args.files) && args.files.length > 0
-      ? args.files.filter(
-          (f): f is string => typeof f === "string" && f.length > 0,
-        )
-      : undefined;
-
-  // No worktree (or no log) → no decisions line, block still returns.
-  const memDecisions = worktree
-    ? readRecentMemDecisions(worktree, 3, files).map((r) => ({
-        text: r.text,
-        spec: r.spec,
-      }))
-    : [];
-
-  // Hub detection needs both worktree (graph root) and files[] (what to map).
-  // Same live-graph cost handoff_check already pays; null/unreadable graph →
-  // no hub line, never a throw (PLAN-hub-signal §3).
-  const hubs: HubEntry[] =
-    worktree && files
-      ? Object.entries(blastRadiusForWorktree(worktree, files) ?? {})
-          .filter(([, b]) => b.dependents >= HUB_DEPENDENTS_MIN)
-          .sort((a, b) => b[1].dependents - a[1].dependents)
-          .map(([file, b]) => ({
-            file,
-            dependents: b.dependents,
-            tested: b.tested,
-            transitive: b.transitive,
-          }))
-      : [];
-
-  const block = buildProjectHealthContext(getStatsData(), {
-    worktree,
-    files,
-    memDecisions,
-    hubs,
-  });
-  return { content: [{ type: "text", text: block }] };
-}