fapony 0.2.0 → 0.2.1

package/README.md

@@ -88,8 +88,8 @@ Stated up front, because the gap between these two things is where most tooling
   facts and that uncertainty was declared — not that the code works. Those are different
   guarantees and fapony only offers the first.
 - **Almost nothing blocks.** No CI failure, no gate on your own commands. The one exception is the
-  Stop hook, once per turn when a commit ends ungraded; the read hint only annotates. Skip the
-  install of both and you are back to exactly the workflow you had.
+  Stop hook, once per turn when a commit ends ungraded; the read/edit/commit hints only annotate.
+  Skip the install of all of them and you are back to exactly the workflow you had.
 - **Model attribution is inferred, not declared.** A gate is attributed to whichever client
   session was live in that worktree at that moment. When one model writes the code and another
   reviews and files the verdict, the grade lands on the reviewer. Reports label it `inferred`;
@@ -157,6 +157,7 @@ flowchart LR
     B[OpenCode] --> F
     C[ZCode] --> F
     D[Codex] --> F
+    E[Cursor] --> F
     F --> G[git facts + session logs]
     G --> S[stats / usage]
     G --> V[verification report]
@@ -175,6 +176,31 @@ losing a single number.
 | Writes | one graded row per unit of work | nothing |
 | Skip it and | there is no fapony | fapony still answers every question |
 
+### What runs where
+
+`fapony install` wires five clients (Claude Code, OpenCode, Cursor, ZCode, Codex). MCP is the only
+piece all of them get — the hooks and in-process hints are per-client, and the read/edit hints
+arrive **before** the call on Claude Code but **after** it on OpenCode, whose only annotate channel
+is `tool.execute.after`. Nothing here is required: skip the hooks and every MCP tool still answers.
+
+| | Claude Code | OpenCode | Cursor | ZCode | Codex |
+|---|---|---|---|---|---|
+| MCP tools — `mem_find` `mem_add` `fapony_usage` `verdict_submit` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Stop hook — refuse to end a turn with ungraded commits | ✅ | — | ✅ | — | ✅ after trust |
+| Read hint — big-file pointer + debt/mem lines | ✅ before | ✅ after | — | — | — |
+| Re-read hint — unchanged repeat read | ✅ before | ✅ after | — | — | — |
+| Edit hint — importer count before a shape change | ✅ before | ✅ after | — | — | — |
+| Commit hint — `git commit` → ungraded-run nudge | — | ✅ after | — | — | — |
+| Skills symlinked into `~/.claude/skills` | ✅ | ✅ | — | — | — |
+| Skills symlinked into `~/.agents/skills` | — | — | — | ✅ | ✅ |
+| `usage-scan` reads this client's session log | ✅ | ✅ | — | ✅ | ✅ |
+
+`—` means not wired, not impossible: Cursor has no PreToolUse hook, and ZCode/Codex expose no
+in-process hook surface for read/edit hints yet (Codex's `apply_patch` sends patch text, not
+resolved file paths). Codex hooks require trust via `/hooks` before they run — `fapony install`
+tells you when. The hints live on hooks rather than MCP on purpose — they must fire mid-turn
+without the agent deciding to call anything ([why](#when-to-call-what)).
+
 ## The ledger — this is the product
 
 One habit feeds it: grade a unit of work when it ends. Everything else on this page is
@@ -202,10 +228,13 @@ sequenceDiagram
 ```
 
 The Stop hook is the only thing fapony *blocks* — once per turn, when a commit ends ungraded.
-It never picks the grade; it cannot see whether the work held up. The Read hook only annotates:
-one factual line when a read is large enough to be cheaper as `review-seed`, or when the same
-file is read again in a session and its mtime has not moved. The read always proceeds, and
-`FAPONY_NO_REREAD_HINT=1` turns the re-read line off.
+It never picks the grade; it cannot see whether the work held up. The hints only annotate and never
+block: the **Read** hook adds one factual line when a read is large enough to be cheaper as
+`review-seed`, or when the same file is read again in a session and its mtime has not moved
+(`FAPONY_NO_REREAD_HINT=1` turns the re-read line off); the **Edit** hook names a file's importer
+count, once per session, before you change its shape; OpenCode's **commit** hook nudges after a
+`git commit` that left the run ungraded. Claude Code receives read/edit *before* the call, OpenCode
+*after* it — [What runs where](#what-runs-where) has the full client matrix.
 
 ### The 4 tools
 
@@ -339,8 +368,9 @@ the claim on faith.
 
 `fapony install --platform claude` (or `opencode`) symlinks these directories into
 `~/.claude/skills` rather than copying them, so `fapony update` refreshes every client
-at once. A destination that already exists and isn't a fapony link is reported and left
-alone — replace it by hand if you want fapony's version.
+at once. ZCode and Codex get the same skills linked into `~/.agents/skills`. A destination
+that already exists and isn't a fapony link is reported and left alone — replace it by hand
+if you want fapony's version.
 
 `plan-with-pony` is vendor-neutral — the SKILL.md *is* the prompt, so pipe it to any agent:
 
@@ -475,8 +505,12 @@ Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB locat
 - Memory integration via shell adapter, per project (configurable or default-wired)
 - Opt-in telemetry, off by default ([TELEMETRY.md](https://github.com/kire21b/fapony/blob/main/TELEMETRY.md) lists exactly what leaves the machine)
 - Bun-only; run state in SQLite via `bun:sqlite` (WAL mode)
+- Per-client hooks alongside MCP: Stop hook on Claude Code + Cursor · read/re-read/Edit hints on
+  Claude Code + OpenCode · commit hint on OpenCode — [What runs where](#what-runs-where)
 
 **Not supported (yet):**
+- PreToolUse hints on Cursor, ZCode or Codex — Cursor has no such hook and the other two expose no
+  in-process hook surface for read/edit hints (Codex's `apply_patch` sends patch text, not file paths)
 - A hosted or shared ledger for a team — `runs.worktree` is the only sharing key today, and it's a
   path, not an identity. If you want to try pointing two machines at the same ledger anyway,
   `FAPONY_STATE_DIR` can be set to a synced folder (Syncthing, a shared drive) — but SQLite's WAL

package/fapony.ts

@@ -7,7 +7,7 @@ import { existsSync } from "node:fs";
 import { cmdAnalyze } from "./src/analyze.js";
 import { cmdDebt } from "./src/debt.js";
 import { cmdDigest } from "./src/digest/cli.js";
-import { cmdHookReadHint, cmdHookStop } from "./src/hook.js";
+import { cmdHookEditHint, cmdHookReadHint, cmdHookStop } from "./src/hook.js";
 import { cmdInit } from "./src/init.js";
 import { cmdInitMem } from "./src/init-mem.js";
 import { cmdInstall } from "./src/install.js";
@@ -85,6 +85,8 @@ if (cmd === "analyze") {
   await cmdHookStop();
 } else if (cmd === "hook-read-hint") {
   await cmdHookReadHint();
+} else if (cmd === "hook-edit-hint") {
+  await cmdHookEditHint();
 } else if (cmd === "mcp") {
   cmdMcp();
 } else if (cmd === "report") {
@@ -106,7 +108,7 @@ if (cmd === "analyze") {
 } 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|test> [args]",
+    "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|test> [args]",
   );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Measurement layer for coding agents \u2014 measure what agents do, verify what they claim. 4 MCP tools, any agent, no loop required",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",

package/src/analyze.ts

@@ -1,15 +1,24 @@
 // src/analyze.ts — `fapony analyze`: structural health diagnosis for a TS/JS project.
 //
 // One file on purpose (plan cap: ≤1 new file in src/). Computes a file-level
-// import graph live with Bun.Transpiler.scan() — never persisted, no new table.
-// Read-only: never writes
-// into the analyzed directory.
+// import graph live with Bun.Transpiler.scan() — no new table. Read-only: never
+// writes into the analyzed directory. buildGraphCached additionally mirrors the
+// derived graph to the state dir (outside the worktree) as a best-effort cache
+// for callers that run as repeated short-lived processes (hooks) — see below.
 //
 // Same module also serves handoff_check / verification_report: blastRadius()
 // turns facts.files[] into per-file { dependents, tested } facts.
 
 import type { Dirent } from "node:fs";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import {
   dirname as posixDirname,
@@ -17,6 +26,7 @@ import {
   normalize as posixNormalize,
 } from "node:path/posix";
 
+import { faponyDir } from "./db/load.js";
 import { extractExports } from "./map.js";
 
 // --- Types (mirror SPEC-analyze-checkup.md) ---
@@ -334,6 +344,154 @@ export function buildGraph(dir: string): ImportGraph {
   return { files, deps, dependents, unresolved, external, barrels };
 }
 
+// --- Session-scoped graph cache ---
+//
+// buildGraph is cheap on this repo (~50ms/150 files) but the Edit hint calls it
+// on every Edit — and a Claude Code PreToolUse hook is a *fresh process per
+// tool call*, so an in-process cache alone never survives to the next edit. The
+// graph is therefore mirrored to <faponyDir>/graph-cache/<key>.json:
+//   - auto-build: every build is written through, best-effort (never blocks)
+//   - auto-invalidate: a fingerprint over the source-file set (rel path + size
+//     + mtimeMs) is stored beside the graph; a mismatch means rebuild
+//   - cost: the cache file is only stat-ed when there is one to validate, so a
+//     first-ever call pays build + write; later calls pay a walk + stat + parse,
+//     well under a rebuild on any repo large enough for this to matter
+// Everything here is derived state — an unreadable, corrupt, stale or
+// unwritable cache falls back to a live build and no code path trusts it.
+
+const GRAPH_CACHE_VERSION = 1;
+const GRAPH_CACHE_DIR = "graph-cache";
+
+interface SerializedGraph {
+  v: number;
+  fp: string;
+  files: string[];
+  deps: Record<string, string[]>;
+  dependents: Record<string, string[]>;
+  unresolved: number;
+  external: number;
+  barrels: string[];
+}
+
+let _graphCache: { dir: string; fp: string; graph: ImportGraph } | null = null;
+
+/** Drop the in-process graph cache (tests simulate a fresh hook process). */
+export function resetGraphCache(): void {
+  _graphCache = null;
+}
+
+/** Absolute path of a worktree's graph-cache file — may not exist. */
+export function graphCachePath(dir: string): string {
+  const abs = resolve(dir);
+  const slug = abs.replace(/[^A-Za-z0-9]+/g, "-").slice(0, 60);
+  return join(
+    faponyDir(),
+    GRAPH_CACHE_DIR,
+    `${slug}-${Bun.hash(abs).toString(36)}.json`,
+  );
+}
+
+// The graph changes only when the set of source files or their bytes change —
+// size/mtime/ctime catch that without reading any file. ctime rides the same
+// stat call for free and cannot be forged like mtime can (only the system
+// moves it), so an mtime-preserving rewrite still invalidates.
+function graphFingerprint(absDir: string): string {
+  const parts: string[] = [];
+  for (const rel of collectSourceFiles(absDir)) {
+    try {
+      const st = statSync(join(absDir, rel));
+      parts.push(
+        `${rel}\u0000${st.size}\u0000${st.mtimeMs}\u0000${st.ctimeMs}`,
+      );
+    } catch {
+      parts.push(`${rel}\u0000?\u0000?\u0000?`);
+    }
+  }
+  return Bun.hash(parts.join("\n")).toString(36);
+}
+
+function serializeGraph(graph: ImportGraph, fp: string): SerializedGraph {
+  const rec = (m: Map<string, Set<string>>): Record<string, string[]> => {
+    const out: Record<string, string[]> = {};
+    for (const [k, v] of m) out[k] = [...v];
+    return out;
+  };
+  return {
+    v: GRAPH_CACHE_VERSION,
+    fp,
+    files: graph.files,
+    deps: rec(graph.deps),
+    dependents: rec(graph.dependents),
+    unresolved: graph.unresolved,
+    external: graph.external,
+    barrels: [...graph.barrels],
+  };
+}
+
+function hydrateGraph(c: SerializedGraph): ImportGraph {
+  const toMap = (r: Record<string, string[]>): Map<string, Set<string>> => {
+    const m = new Map<string, Set<string>>();
+    for (const [k, v] of Object.entries(r)) m.set(k, new Set(v));
+    return m;
+  };
+  return {
+    files: c.files,
+    deps: toMap(c.deps),
+    dependents: toMap(c.dependents),
+    unresolved: c.unresolved,
+    external: c.external,
+    barrels: new Set(c.barrels),
+  };
+}
+
+function readCachedGraph(path: string, fp: string): ImportGraph | null {
+  try {
+    const cached = JSON.parse(readFileSync(path, "utf-8")) as SerializedGraph;
+    if (cached.v !== GRAPH_CACHE_VERSION || cached.fp !== fp) return null;
+    return hydrateGraph(cached);
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedGraph(path: string, graph: ImportGraph, fp: string): void {
+  try {
+    if (!existsSync(join(faponyDir(), GRAPH_CACHE_DIR))) {
+      mkdirSync(join(faponyDir(), GRAPH_CACHE_DIR), { recursive: true });
+    }
+    // pid-suffixed temp + rename: a reader never sees a half-written file even
+    // when two hook processes race.
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(serializeGraph(graph, fp)), "utf-8");
+    renameSync(tmp, path);
+  } catch {
+    // best-effort — a cache that cannot be written must not break the caller
+  }
+}
+
+export function buildGraphCached(dir: string): ImportGraph {
+  const abs = resolve(dir);
+  // One walk per call: the fingerprint doubles as the in-process validity
+  // check, so a same-process second call after an edit rebuilds instead of
+  // serving the stale graph. A drift between this fp and the built graph
+  // self-heals — the next call recomputes and rebuilds again.
+  const fp = graphFingerprint(abs);
+  if (_graphCache?.dir === abs && _graphCache.fp === fp)
+    return _graphCache.graph;
+  const path = graphCachePath(abs);
+  if (existsSync(path)) {
+    const cached = readCachedGraph(path, fp);
+    if (cached) {
+      _graphCache = { dir: abs, fp, graph: cached };
+      return cached;
+    }
+  }
+  const graph = buildGraph(abs);
+  _graphCache = { dir: abs, fp, graph };
+  writeCachedGraph(path, graph, fp);
+  return graph;
+}
+
 // --- Diagnosis ---
 
 function findCycles(graph: ImportGraph): string[][] {

package/src/conventions-seed.ts

@@ -15,6 +15,7 @@ import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { collectSourceFiles, isSkippedDir, isTestFile } from "./analyze.js";
+import { CONVENTIONS_FILE, FAPONY_DIR } from "./db/index.js";
 import { extractBody, extractExports } from "./map.js";
 
 const RESTRICTED_RULES = new Set([
@@ -376,7 +377,7 @@ function detectWrappers(root: string): SeedRow[] {
 // --- entry ---
 
 export async function seedConventionsFile(target: string): Promise<SeedResult> {
-  const file = join(target, ".fapony", "conventions.json");
+  const file = join(target, CONVENTIONS_FILE);
   const base: SeedResult = {
     file,
     eslintRows: 0,
@@ -407,7 +408,7 @@ export async function seedConventionsFile(target: string): Promise<SeedResult> {
     // a wrapper scan failure is not an init failure
   }
   const payload = `${JSON.stringify({ conventions: rows }, null, 2)}\n`;
-  mkdirSync(join(target, ".fapony"), { recursive: true });
+  mkdirSync(join(target, FAPONY_DIR), { recursive: true });
   writeFileSync(file, payload);
   return {
     file,

package/src/db/defaults.ts

@@ -6,13 +6,21 @@ export const DEFAULT_SAFETY_DENY = [
   "checkout\\s+--\\s",
   "git\\s+stash",
 ];
-export const DEFAULT_PLAN_DIR = ".fapony/plan";
-export const DEFAULT_SPEC_DIR = ".fapony/spec";
+// --- .fapony/ layout (single source of truth — do not hardcode ".fapony" elsewhere) ---
+// plan/spec live in .fapony/ — not configurable (gitignored = private).
+export const FAPONY_DIR = ".fapony";
+export const CONFIG_FILENAME = "fapony.config.json";
+export const CONVENTIONS_FILENAME = "conventions.json";
+export const EVIDENCE_FILENAME = "evidence.json";
+export const CONVENTIONS_FILE = `${FAPONY_DIR}/${CONVENTIONS_FILENAME}`;
+// plan/spec live in .fapony/ — not configurable (gitignored = private).
+export const PLAN_DIR = `${FAPONY_DIR}/plan`;
+export const SPEC_DIR = `${FAPONY_DIR}/spec`;
 // Archive sits beside plan/, not inside it, so archiving never changes a file's
 // depth and its relative links survive the move untouched.
-export const DEFAULT_DONE_DIR = ".fapony/done";
-export const DEFAULT_MEM_DIR = ".fapony/.memory";
-export const DEFAULT_EVIDENCE_FILE = ".fapony/evidence.json";
+export const DEFAULT_DONE_DIR = `${FAPONY_DIR}/done`;
+export const DEFAULT_MEM_DIR = `${FAPONY_DIR}/.memory`;
+export const DEFAULT_EVIDENCE_FILE = `${FAPONY_DIR}/${EVIDENCE_FILENAME}`;
 
 export const DEFAULT_CONFIG: Config = {
   worktrees: {},

package/src/db/getters.ts

@@ -2,9 +2,9 @@ import {
   DEFAULT_DONE_DIR,
   DEFAULT_EVIDENCE_FILE,
   DEFAULT_MEM_DIR,
-  DEFAULT_PLAN_DIR,
   DEFAULT_SAFETY_DENY,
-  DEFAULT_SPEC_DIR,
+  PLAN_DIR,
+  SPEC_DIR,
 } from "./defaults.js";
 import type { Config } from "./types.js";
 
@@ -12,12 +12,14 @@ export function safetyDeny(config?: Config): string[] {
   return config?.safety?.deny ?? DEFAULT_SAFETY_DENY;
 }
 
-export function planDir(config?: Config): string {
-  return config?.paths?.planDir ?? DEFAULT_PLAN_DIR;
+/** Hardcoded — plan/spec live in .fapony/ (gitignored = private). */
+export function planDir(): string {
+  return PLAN_DIR;
 }
 
-export function specDir(config?: Config): string {
-  return config?.paths?.specDir ?? DEFAULT_SPEC_DIR;
+/** Hardcoded — plan/spec live in .fapony/ (gitignored = private). */
+export function specDir(): string {
+  return SPEC_DIR;
 }
 
 export function doneDir(config?: Config): string {

package/src/db/load.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { DEFAULT_CONFIG } from "./defaults.js";
+import { CONFIG_FILENAME, DEFAULT_CONFIG } from "./defaults.js";
 import type { Config } from "./types.js";
 
 // XDG Base Directory convention (macOS ignores Apple's ~/Library/Application Support
@@ -20,7 +20,7 @@ function _dbPath(config?: Config): string {
 
 export function configFilePath(): string {
   if (process.env.FAPONY_CONFIG) return process.env.FAPONY_CONFIG;
-  return join(process.cwd(), "fapony.config.json");
+  return join(process.cwd(), CONFIG_FILENAME);
 }
 
 function freshDefaultConfig(): Config {

package/src/db/types.ts

@@ -55,9 +55,7 @@ export interface Config {
     // state dir override (default: $XDG_CONFIG_HOME/fapony or ~/.config/fapony).
     // $FAPONY_STATE_DIR env wins over this when set.
     stateDir?: string;
-    // plan/spec/memory layout inside each worktree (relative to worktree root).
-    planDir?: string;
-    specDir?: string;
+    // plan/spec live in .fapony/{plan,spec} — not configurable (gitignored = private).
     doneDir?: string;
     memDir?: string;
     evidenceFile?: string;

package/src/debt.ts

@@ -21,6 +21,11 @@
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { collectSourceFiles } from "./analyze.js";
+import {
+  CONVENTIONS_FILE,
+  CONVENTIONS_FILENAME,
+  FAPONY_DIR,
+} from "./db/defaults.js";
 import { openDb } from "./db/index.js";
 import { readMemLog, resolveMemDir } from "./memory.js";
 
@@ -52,13 +57,13 @@ export function resolveConventionsPath(worktree: string): string | null {
   // Conventions live in the same .fapony/ dir as the mem log — derive from
   // the resolved mem dir so both resolvers cannot drift apart.
   const memDir = resolveMemDir(worktree);
-  const base = memDir ? join(memDir, "..") : join(worktree, ".fapony");
-  const app = join(base, "conventions.json");
+  const base = memDir ? join(memDir, "..") : join(worktree, FAPONY_DIR);
+  const app = join(base, CONVENTIONS_FILENAME);
   if (existsSync(app)) return app;
   // Monorepo where the app has not scaffolded .fapony/ yet, and single repos
   // that ran `fapony init` at the root — the root file still scopes fine
   // because every `where` is repo-relative.
-  const root = join(worktree, ".fapony", "conventions.json");
+  const root = join(worktree, CONVENTIONS_FILE);
   return existsSync(root) ? root : null;
 }
 
@@ -668,7 +673,7 @@ export function worktreeOf(arg: string | undefined): string {
   const boundary = gitRoot ? real(gitRoot) : null;
   let dir = base;
   while (true) {
-    if (existsSync(join(dir, ".fapony", "conventions.json"))) return dir;
+    if (existsSync(join(dir, CONVENTIONS_FILE))) return dir;
     if (boundary && real(dir) === boundary) break;
     const parent = dirname(dir);
     if (parent === dir) break;

package/src/digest/collect.ts

@@ -6,6 +6,7 @@ import { execSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
+  CONFIG_FILENAME,
   doneDir,
   type Event,
   loadConfig,
@@ -165,8 +166,8 @@ function readPlans(worktree: string): {
   ok: boolean;
   detail: string;
 } {
-  const config = loadConfig(join(worktree, "fapony.config.json"));
-  const pDir = join(worktree, planDir(config));
+  const config = loadConfig(join(worktree, CONFIG_FILENAME));
+  const pDir = join(worktree, planDir());
   const dDir = join(worktree, doneDir(config));
 
   if (!existsSync(pDir)) {