fapony 0.2.0 → 0.3.0

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`;
@@ -122,7 +122,6 @@ fapony usage-scan                         # scan the session logs already on dis
 fapony price-scan                         # fetch the OpenRouter price table → ~/.config/fapony/prices.json
 fapony usage-web                          # dashboard; re-run the scans to refresh
 #    both scans are manual by design — nothing fetches or re-reads session logs behind your back
-#    ask your agent: "Run fapony_usage — what has it cost me, per model?"
 
 # 4. Verify (optional, per project) — scaffold the evidence allowlist
 fapony init /path/to/your-worktree
@@ -157,6 +156,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 +175,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` `mem_close` `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,26 +227,29 @@ 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
 
 | Tool | Tier | Purpose |
 |------|------|---------|
-| `fapony_usage` | measure | Passive usage from OpenCode, ZCode, Claude Code, and Codex sessions (tokens, cost, by-model; `detail:true` adds per-step timing) |
 | `verdict_submit` | verify | Store a 6-grade verdict (pass-excellent → uncertain) with a required `regime` — the task shape the grade applies to |
 | `mem_find` | recall | Search the project's mem log read-only — decisions/bugs/notes matched on the row's `files[]` (text substring for rows written without it), `text`, `kind` (no default filter), `since`. "What was ever decided about this file?" in one call before editing |
 | `mem_add` | recall | Append a mem row (decision/bug/note/next/hold) with `files[]` required and rejected when empty — the write half of `mem_find`, so the row is findable when you next touch that file |
+| `mem_close` | recall | Close a mem row by id with a tombstone message — a separate tool (not `kind:"close"`) because a close row carries no `files[]`, so sharing `mem_add`'s schema would make required fields depend on another field's value |
 
 **A tool earns its schema by being called mid-task without being asked.** Everything you invoke
 deliberately is a CLI command instead: the schema is paid as input tokens in every session of
 every client whether or not it is used, while a CLI command costs nothing until it runs. That is
-why the handoff/report family is CLI-only, and why `fapony_stats`, `project_health_context` and
-`plan_list` left the MCP surface in 2026-09 (`fapony stats` answers the first, `fapony mem
-kickoff` the third; the second had no caller).
+why the handoff/report family is CLI-only, and why `fapony_stats`, `project_health_context`,
+`plan_list` and `fapony_usage` left the MCP surface in 2026-09 (`fapony stats` answers the first, `fapony mem
+kickoff` the third, `fapony usage-web` the fourth; the second had no caller).
 Cutting is not the goal — spending where it pays back is: `mem_find` and `verdict_submit` keep
 their schemas because nobody is going to type them at the right moment. `fapony report <run-id>` prints the full report for a run (facts + handoff conformance + evidence + verdict); `fapony report-web [file]` renders it as a static HTML page (overwrites `file` on every call — safe to reuse the same path). Run `bun run overview` for a one-shot shortcut that writes it to `/tmp/fapony-overview.html` and opens it. `fapony usage-scan` scans session logs and writes a cache file; `fapony usage-web [port]` serves a static HTML dashboard from that cache (no live scanning). Run `fapony usage-scan` periodically to keep data fresh.
 
@@ -275,13 +303,15 @@ That is the whole trick; there is no model in the middle.
 
 ### Skills
 
-fapony ships five portable skills, each as `skill/<name>/SKILL.md` — the layout Claude
+fapony ships seven portable skills, each as `skill/<name>/SKILL.md` — the layout Claude
 Code expects, so a client can symlink the directory rather than copy the file:
 
 | Skill | Purpose | Trigger |
 |-------|---------|---------|
 | `skill/plan-with-pony/` | Draft plan + spec from "what's in your head" via conversation | `/plan-with-pony` |
 | `skill/review-pony/` | Review as verification, wired to fapony: scope facts before (`review-seed`), verdict after | `/review-pony` |
+| `skill/lookup-before-edit/` | Look up unfamiliar files (`review-seed --files` + mem + debt) before reading/editing them | `/lookup-before-edit` |
+| `skill/define-convention/` | Turn a not-yet-migrated pattern into a tracked convention (interview + dry-run `debt`) | `/define-convention` |
 | `skill/move-to-done/` | Archive a shipped PLAN into .fapony/done/ | `/move-to-done` |
 | `skill/git-commit-conventional/` | Commit split by concern + conventional message | `/git-commit` |
 | `skill/git-ship/` | Push branch, open PR with drafted title/body, merge, reset branch onto base | `/ship`, `/pr` |
@@ -334,13 +364,14 @@ plain `/git-ship` detects that and behaves like `pr` on its own.
 
 **What this is not.** It doesn't reduce your token bill — an agent that plans against known
 failure patterns tends to spend fewer rounds getting there, but fapony measures that, it doesn't
-cause it. Use `fapony_usage` to find out whether it actually happened for you rather than taking
+cause it. Use `fapony usage-web` to find out whether it actually happened for you rather than taking
 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 +506,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

@@ -5,9 +5,14 @@
 
 import { existsSync } from "node:fs";
 import { cmdAnalyze } from "./src/analyze.js";
-import { cmdDebt } from "./src/debt.js";
+import { cmdDebt } from "./src/debt/cli.js";
 import { cmdDigest } from "./src/digest/cli.js";
-import { cmdHookReadHint, cmdHookStop } from "./src/hook.js";
+import {
+  cmdHookEditHint,
+  cmdHookReadHint,
+  cmdHookSessionStart,
+  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 +90,10 @@ if (cmd === "analyze") {
   await cmdHookStop();
 } else if (cmd === "hook-read-hint") {
   await cmdHookReadHint();
+} else if (cmd === "hook-edit-hint") {
+  await cmdHookEditHint();
+} else if (cmd === "hook-session-start") {
+  await cmdHookSessionStart();
 } else if (cmd === "mcp") {
   cmdMcp();
 } else if (cmd === "report") {
@@ -106,7 +115,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|hook-session-start|test> [args]",
   );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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/skill/define-convention/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: define-convention
+description: Turn "files that haven't migrated yet" into a tracked convention — one question, a draft built from real examples, then dry-run fapony debt until the counts hold. Trigger on /define-convention and when the user wants migration tracking or fapony debt shows declared rows with no regex.
+---
+
+# Define Convention — from pain to a counted migration
+
+One convention = the pattern to use (`ok`) + the pattern meaning not-yet-migrated
+(`stale`) + scope (`where`) + an optional file condition (`guard`). The output is
+one row in `<worktree>/.fapony/conventions.json` (`{"conventions": [...]}`), in the
+same `.fapony/` dir as the mem log — run `fapony mem where`, go up one level, that
+is where the file lives (app-scoped in a monorepo). No file there yet = create it;
+a file with rows = append only, never rewrite other rows.
+
+## Phase 1 — One question, then the checker question
+
+Ask this, and nothing else:
+
+> "What should stop appearing, and what does the migrated code look like? Which
+> directory is it in?"
+
+Then the iron-rule question (one line, always asked — a convention eslint already
+flags is one fapony must stay silent on):
+
+> "Does an eslint rule or script already flag the old pattern? If yes, name it —
+> fapony will record it as `checker` and never report this debt."
+
+## Phase 2 — Real examples before regex
+
+Never invent the regex from prose — regex from prose is how entries get dropped.
+`grep` the `where` dir for 2–3 hits of the old pattern and 1–2 of the new one. No
+hits on either side = stop and say so; there is no migration to track yet, only
+an opinion.
+
+## Phase 3 — Draft the row, show it, append it
+
+```json
+{"id": "raw-throw", "rule": "throw failWith, not raw Error",
+ "where": "src", "stale": "throw new Error", "ok": "failWith"}
+```
+
+- `id` short, kebab; `rule` one human line; `where` a repo-relative dir that
+  exists (`"."` = whole repo).
+- `guard` only when `stale` alone is too broad (the file must ALSO match, e.g.
+  `"extends Base"`).
+- `checker` set from Phase 1 = silent by design; verify it with eslint, not fapony.
+- `stale: null` ships a `declared` placeholder — fill it or delete it, never keep it.
+- The shown draft is the confirmation (rule 6c). Append, don't rewrite.
+
+## Phase 4 — Dry-run until the counts hold
+
+```bash
+fapony debt --id <new-id>
+```
+
+Read it literally — every outcome names its fix:
+
+- `debt N · moved M` with N > 0 → the convention now counts. Report id, N, moved%
+  back in chat.
+- `debt 0 · moved M — clean` → the migration is already done; nothing left to
+  track. Report it and change nothing.
+- `debt 0` with no moved → `stale` matches nothing you care about; widen it or
+  fix `where`.
+- `⚠ <id>: ... too broad` → narrow `stale`, shrink `where`, or add `guard` (the
+  match was capped past 250 files, so the entry was dropped).
+- `⚠ <id>: stale regex broken` / `where: <dir> does not exist` → fix syntax / path.
+- A row prints `declared, no checker, stale not filled in` → `stale` is null; see
+  Phase 3.
+- `0 convention(s)` after `--id` → that id does not exist (misspelling — a dropped
+  row still prints its `⚠`). Only `no conventions.json in <dir>` means you wrote
+  to the wrong `.fapony/` (re-check `mem where`).
+
+## Later
+
+A convention whose fix recurs ≥3 times makes `fapony debt` ask "time for a
+checker?" — that promotion answers to a human, never to this skill. `no-checker`
+means "never ask again": say it only deliberately.

package/skill/lookup-before-edit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lookup-before-edit
+description: Look up unfamiliar files before reading or editing them — exports, line numbers, and importers without reading the whole file. Trigger on /lookup-before-edit and proactively whenever you are about to read, edit, or refactor a file you do not already know.
+---
+
+# Lookup Before Edit — scope first, read second
+
+You are about to touch files you do not know. Do not `Read` them whole — look them up first.
+A full-file read on a 500-line module costs ~35k tokens of output; a lookup costs under 1k.
+
+## The one command
+
+```bash
+fapony review-seed --files <f1,f2,dir> [--body <sym>] [--callers <sym>]
+```
+
+What it returns: every export with its line number (uncapped), plus the importers — first 12
+per file, the rest as `(+N)`, so the total is still readable. That is your entry map — then
+`Read` only the line ranges you actually need.
+
+## Narrow it
+
+- `--body <sym>[,<sym>]` — declaration slice of those exports (truncated at 80 lines each):
+  "what does this do" without the file.
+- `--callers <sym>` — symbol→symbol scan across the importers the static graph sees.
+- Directories expand to the source files under them (cap 40, stated when cut). Paths that do
+  not exist are dropped with a notice, not counted silently.
+
+## Limits (do not work around them)
+
+- **Exports only.** A non-exported function answers "no export named X in scope" — that is
+  the correct answer, not a failure. Read the file for internals.
+- **Static only.** Dynamic use is invisible to the graph; an empty caller list means "not
+  seen statically", never "unused".
+- **120 lines total.** Past that the tail is cut (`… (+N lines truncated)`) — and the tail is
+  the later files' signatures. Many files at once → split the call, don't trust a cut list.
+- No `fapony` CLI or the call errors → read the file normally and carry on. A hint, not a gate.
+
+## History + debt (same paths, two calls)
+
+- `mem_find` with `files: [<same paths>]` — "what was ever decided about this file" (MCP, no CLI spawn).
+- `fapony debt --where <dir|file>` — conventions this path still violates; empty until `conventions.json` exists.
+
+## After the lookup
+
+1. Pick line ranges from the export list, `Read` those slices only.
+2. Before changing a shape, sum shown + `(+N)` importers — that is your blast radius.
+3. Do not re-read a file whose mtime has not moved; `grep` it instead.

package/skill/review-pony/SKILL.md

@@ -117,10 +117,15 @@ them is how a review launders an assumption into a fact.
 
 The reader has the diff and is deciding what to do next. Nothing else belongs here.
 
-**Verdict first, then at most 3 findings, at most 4 lines each, then one deferred line.**
+**Verdict first, then at most 10 findings, at most 4 lines each, then one deferred line.**
 Severity order: blocker → major → nit, and cut the nits entirely when anything structural
 survived — they dilute the only thing worth reading.
 
+**A capped report must not read as a complete one.** When more findings survived pass 3 than
+the cap allows, the report ends with one line naming how many were held back and the worst
+severity among them (`+ 4 more (major) — ask`) — never a silent stop at 10. A reader who
+cannot tell "that's all" from "that's the cap" has been told a lie by omission.
+
 ```
 <ship | fix-then-ship | rework | reject> — the single biggest reason, one sentence.
 
@@ -130,6 +135,7 @@ survived — they dilute the only thing worth reading.
    fix: <the minimal change>
 
 deferred: <thing> (<where it was specified>) · <thing>
++ <N> more (<worst severity>)   ← required only when findings exceeded the cap
 ```
 
 Four lines is a ceiling, not a quota — a finding that fits in two ships in two. Drop `repro:`
@@ -214,9 +220,11 @@ The four passes are the rules. These three are what they fail on in practice:
 
 - **Order is not optional.** No line-by-line notes before pass 1, no finding before passes 2-3
   earned it, nothing stated as fact that pass 4 cannot cite.
-- **The budget is binding.** Verdict, ≤3 findings, ≤4 lines each, one deferred line. Over budget
+- **The budget is binding.** Verdict, ≤10 findings, ≤4 lines each, one deferred line. Over budget
   means you are reporting process. "LGTM" is not an output either — finding nothing ships as the
-  verdict line plus one line naming what you walked.
+  verdict line plus one line naming what you walked. When the cap bites, say how much it bit:
+  a `+ N more (<severity>)` line is required — a silent stop at 10 is the same lie as a silent
+  stop at 3.
 - **Forget who wrote it.** The author's reasoning is context, never evidence.
 
 ## Example

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 {