fapony 0.2.1 → 0.3.3

package/README.md

@@ -36,15 +36,16 @@ quietly counted as free.
 
 </details>
 
-That is day one. Past that, fapony measures what coding agents actually do — rounds, pass/fail,
-cost per grade — through 4 MCP tools any agent can call. If you juggle more than one agent, this is
-the point: the numbers come from the same yardstick everywhere, so "which model earns its keep on
-which kind of task" becomes a data question instead of a vibe. On top of measurement it checks
-claims against git facts: handoff conformance, allowlisted evidence, a 6-grade verdict — with
-everything the agent claimed but couldn't prove marked as such.
+That is day one. Past that, fapony keeps what coding agents actually did — the frozen
+ledger of graded runs (rounds, pass/fail, cost per grade, readable via CLI, no new grades)
+plus the live mem log — through 3 MCP tools any agent can call. If you juggle more than
+one agent, this is the point: the numbers come from the same yardstick everywhere, so
+"which model earns its keep on which kind of task" becomes a data question instead of a
+vibe. On top of history it checks claims against git facts: handoff conformance and
+allowlisted evidence — with everything the agent claimed but couldn't prove marked as such.
 
-**What that question looks like answered, from one project's own ledger — the top of the `n≥5`
-frontier (`fapony stats --mode verdict --regime code`):**
+**What that question looks like answered, from one project's own (frozen — reads history,
+no new grades) ledger — the top of the `n≥5` frontier (`fapony stats --mode verdict --regime code`):**
 
 | model | tokens/pass | quality | n |
 |---|---|---|---|
@@ -63,14 +64,15 @@ accumulates is pain.** An agent has no memory of pain across sessions: it writes
 hand-rolled `try/catch` as cheerfully as the first, because every session starts new. Wrappers and
 shared libraries get built by *people* who were hurt by the same thing often enough to remember.
 That is why a codebase written with agents from day one tends not to grow a shared layer — nobody
-in the room remembers. fapony is the part that remembers: graded verdicts and mem rows both carry
-`files[]`, so the zones that keep coming back in failed and re-done work are a query, not a hunch.
+in the room remembers. fapony is the part that remembers: mem rows carry
+`files[]`, so the zones that keep coming back in re-done work are a query, not a hunch
+(the frozen ledger's old graded rows carry them too).
 Paired with `fapony debt`, which tracks how far the codebase has actually moved to a convention you
 already decided on, that is the loop: notice the repeated cost, name the shared thing, watch the
 migration finish. Finding dead code and duplication is *not* part of it — knip and friends already
 do that better, and a convention with a `checker` is deliberately left to the checker.
 
-**The measurement layer underneath it:** Any single client already logs its own session — timing, tokens, tool calls. What none of them see is *across* runs, clients and task shapes: which model earns its keep on which kind of work **in this project**, at what token cost, graded by whoever reviewed it. Every verdict carries a `regime` (`code` / `fix` / `review` / `plan` / `inquiry` / `test`), and runs split by whether there was a plan at all — so "does planning beat diving in, and for which model" is a table, not an argument.
+**The measurement layer underneath it:** Any single client already logs its own session — timing, tokens, tool calls. What none of them see is *across* runs, clients and task shapes: which model earns its keep on which kind of work **in this project**, at what token cost. The frozen ledger still answers that from history — every old verdict carries a `regime` (`code` / `fix` / `review` / `plan` / `inquiry` / `test`), and runs split by whether there was a plan at all — so "does planning beat diving in, and for which model" stays a table, not an argument. New accumulation goes to the mem log instead: decisions, bugs and notes with `files[]`, written by the agents doing the work.
 
 Three tiers, deliberately: **measurement ships today** and needs no per-project setup — raw facts nobody can call unfair. **Verification is the sharper edge** but stays beta until its evidence layer is hardened; fapony doesn't control your agent's flow, so it never promises "verified" as a headline. **Knowledge accumulation is the compounding one** — it's worthless on run 1 and gets more useful every run after, which is exactly why it's the layer competitors can't clone by copying a feature list.
 
@@ -82,15 +84,16 @@ Stated up front, because the gap between these two things is where most tooling
 
 - **It does not run your test suite.** The evidence collector runs an allowlist *you* write in
   `.fapony/evidence.json`, and never a command an agent proposes. No allowlist, no evidence.
-- **It does not judge your code.** `verdict_submit` *stores* a verdict; a human or a reviewing
-  agent supplies it. fapony is the ledger, not the judge.
+- **It does not judge your code.** Mem rows *record* decisions, bugs and notes; a human or
+  a working agent supplies them. fapony is the memory, not the judge. (The frozen
+  ledger's old grades work the same way — *stored*, never computed.)
 - **It checks conformance, not correctness.** What it can verify is that a claim lines up with git
   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/edit/commit hints only annotate.
+  Stop hook, once per turn when a commit lands with no new mem row; 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
+- **Model attribution is inferred, not declared.** A gate in the frozen ledger 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`;
   read it as such.
@@ -122,23 +125,24 @@ 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
+# 4. Turn on the knowledge layer (per project you want it in)
 fapony init /path/to/your-worktree
-#    edit .fapony/evidence.json to your real test/typecheck commands, then commit it
+#    creates .fapony/ — .memory/ (the mem log the 3 MCP tools read and write),
+#    conventions.json for `fapony debt`, plan/spec/done, and evidence.json
+#    conventions.json + evidence.json are shared rules: commit them
 ```
 
-With `.fapony/evidence.json` in place, any graded run can be replayed as a report. This one is
-a CLI command, not an MCP tool — the schemas cost every session of every client and no skill
-called them (see [The 4 tools](#the-4-tools) below). Grade something first;
-`verdict_submit` is what creates the run:
+With `.fapony/evidence.json` in place, any graded run from the frozen ledger can be replayed
+as a report. This one is a CLI command, not an MCP tool — the schemas cost every session of
+every client and no skill called them (see [The 3 tools](#the-3-tools) below). No new runs
+can be created; run ids come from `fapony stats` reading history:
 
 ```bash
 fapony report <run-id>        # run ids come from `fapony stats`
 ```
 
-You get one report: git facts (files, commits, branch), handoff conformance (claims vs. reality), evidence from the allowlisted commands (pass/fail/timeout/unverified), a 6-grade verdict, and cost — with anything the agent claimed but couldn't prove marked as such.
+You get one report: git facts (files, commits, branch), handoff conformance (claims vs. reality), evidence from the allowlisted commands (pass/fail/timeout/unverified), the frozen 6-grade verdict, and cost — with anything the agent claimed but couldn't prove marked as such.
 
 Sections that have nothing to report say so (`not_run`, `unavailable`) rather than disappearing — a report with no evidence must not read like a report that passed.
 
@@ -171,9 +175,9 @@ losing a single number.
 
 | | The ledger | The work side |
 |---|---|---|
-| What it is | 4 MCP tools + a SQLite ledger | plans, skills, read-only seed commands |
+| What it is | 3 MCP tools (mem) + a frozen SQLite ledger (reads history) | plans, skills, read-only seed commands |
 | Needs | an MCP client | nothing — or your own tooling instead |
-| Writes | one graded row per unit of work | nothing |
+| Writes | one mem row per unit of work, into the project's log | nothing |
 | Skip it and | there is no fapony | fapony still answers every question |
 
 ### What runs where
@@ -185,12 +189,12 @@ is `tool.execute.after`. Nothing here is required: skip the hooks and every MCP
 
 | | 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 |
+| MCP tools — `mem_find` `mem_add` `mem_close` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Stop hook — refuse to end a turn with commits but no new mem row | ✅ | — | ✅ | — | ✅ 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 | — | — | — |
+| Commit hint — `git commit` → record-a-mem-row nudge | — | ✅ after | — | — | — |
 | Skills symlinked into `~/.claude/skills` | ✅ | ✅ | — | — | — |
 | Skills symlinked into `~/.agents/skills` | — | — | — | ✅ | ✅ |
 | `usage-scan` reads this client's session log | ✅ | ✅ | — | ✅ | ✅ |
@@ -203,10 +207,10 @@ 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
-optional around that. `verdict_submit` needs no plan file, no skill and no `.fapony/`
-directory — any agent that speaks MCP can call it, and calling it is what turns a pile of
-session logs into an answer.
+One habit feeds it: record a mem row when a unit of work ends. Everything else on this page is
+optional around that. `mem_add` needs no plan file and no skill — any agent that speaks MCP
+can call it, and calling it is what turns a pile of session logs into an answer the next
+session can find.
 
 ### One turn, end to end
 
@@ -215,50 +219,52 @@ sequenceDiagram
     autonumber
     participant A as Any MCP client
     participant F as fapony MCP
-    participant L as ~/.config/fapony/state.db
+    participant M as project mem log (.fapony/.memory)
 
-    Note over A,F: end a turn with a commit and no grade → the Stop hook blocks it once
-    A->>F: verdict_submit (grade + regime + reason_code + note)
-    F->>L: one graded unit of work, stamped with the model that did it
-    opt proof, not just a claim — CLI, once the run exists
+    Note over A,F: end a turn with a commit and no new mem row → the Stop hook blocks it once
+    A->>F: mem_add (kind + files + text)
+    F->>M: one mem row in the project's log, stamped with the model that did it
+    opt proof, not just a claim — CLI, for runs from the frozen ledger
         A->>F: fapony report <run-id>
         F-->>A: git facts + evidence from .fapony/evidence.json, stamped with server_sha
     end
-    Note over A,L: `fapony stats` reads it back — CLI, because you ask it, not the agent
+    Note over A,M: `fapony stats` reads the frozen ledger back — CLI, because you ask it, not the agent
 ```
 
-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 hints only annotate and never
+The Stop hook is the only thing fapony *blocks* — once per turn, when a commit lands with
+no new mem row. It never judges what deserves recording; 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
+`git commit` that left no new mem row. 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
+### The 3 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).
-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.
+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: the three mem tools keep
+their schemas because nobody is going to type them at the right moment. `fapony report <run-id>` prints the full report for a frozen-ledger 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.
 
 Full protocol, adapter examples (bash, Python), and safety rules: [docs/mcp-handcheck.md](https://github.com/kire21b/fapony/blob/main/docs/mcp-handcheck.md).
 
-### Verdict grades
+### Verdict grades (frozen ledger)
 
-Verification produces a quality grade, not just pass/fail:
+No new grades are recorded — the tool that filed them left the MCP surface in 2026-09.
+The old rows stay readable via `fapony stats` and `fapony report`, and this is the scale
+they were filed on. Verification produced a quality grade, not just pass/fail:
 
 | Grade | Meaning |
 |-------|---------|
@@ -272,8 +278,8 @@ Verification produces a quality grade, not just pass/fail:
 ### Why measure from the outside
 
 - **Raw facts are hard to argue with.** Cost, rounds, diff sizes, pass rates — collected from git and session logs, not self-reported. A vendor can dispute a verdict as unfair; they can't dispute their own token count.
-- **Agent platforms grading their own homework is a conflict of interest.** fapony is a separate layer that measures any agent the same way, which is what makes "model X vs. model Y" or "workflow A vs. workflow B" answerable with real data instead of vibes.
-- **Verification stays honest about its limits.** The collector runs only commands listed in `.fapony/evidence.json`; commands proposed by the agent outside the allowlist are reported as *proposed — not executed*, never run. And because fapony doesn't control your agent's flow, verdicts are labeled as one signal — not promised as truth.
+- **Agent platforms grading their own homework is a conflict of interest.** fapony is a separate layer that measured any agent the same way, which is what made "model X vs. model Y" or "workflow A vs. workflow B" answerable with real data instead of vibes. That history is still queryable; new accumulation is mem rows, not grades.
+- **Verification stays honest about its limits.** The collector runs only commands listed in `.fapony/evidence.json`; commands proposed by the agent outside the allowlist are reported as *proposed — not executed*, never run. And because fapony doesn't control your agent's flow, old verdicts are labeled as one signal — not promised as truth.
 
 ## The work side — conveniences, not the contract
 
@@ -304,13 +310,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/review-pony/` | Review as verification, wired to fapony: scope facts before (`review-seed`), a mem row after when findings survive | `/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` |
@@ -329,10 +337,10 @@ flowchart TD
     R -->|findings| W
     R -->|clean| S["/git-ship"]
     S -->|"there was a PLAN.md"| D["/move-to-done"]
-    D -.-> H[(fapony ledger)]
+    D -.-> H[(mem log + frozen ledger)]
     R -.-> H
-    C -.->|"Stop hook: a commit needs a verdict"| H
-    H -.->|"which model for this shape"| Q
+    C -.->|"Stop hook: a commit needs a mem row"| H
+    H -.->|"pain zones + past model×shape"| Q
 
     style H fill:#2d333b,stroke:#768390,color:#adbac7
 ```
@@ -342,19 +350,20 @@ to pick up. Wiring, refactors and UI passes finish in one sitting and the PLAN.m
 unread — so `/plan-with-pony` declines those itself and hands over the two seed commands instead.
 Both arms meet at the same review and the same ledger.
 
-**The dotted edges are the whole point.** Verdicts carry `regime` and `reason_code`, so the
-ledger can answer the one question no single client can: *in this project, which model is worth
-paying for this shape of work.* That is what flows back to the fork — not "this file broke once",
-which fapony measured at a 1–9% base rate and demoted.
+**The dotted edges are the whole point.** Mem rows carry `files[]` and standalone text, so
+the zones that keep hurting are a query, not a hunch — and the frozen ledger still carries
+`regime` on its old rows, so *in this project, which model was worth paying for this shape
+of work* stays answerable from history. That is what flows back to the fork — not "this file
+broke once", which fapony measured at a 1–9% base rate and demoted.
 
 | Moment | Call | What fapony gets out of it |
 |---|---|---|
 | Starting anything | `/plan-with-pony` | decides plan-vs-seed, then reads back how this shape has gone |
 | Before editing an unfamiliar file | `fapony review-seed --files` | nothing; it saves you reading the file |
 | Before committing | `/git-commit` | nothing; it just keeps commits reviewable |
-| Before merging | `/review-pony` | writes a verdict + `reason_code` + `regime` + note |
+| Before merging | `/review-pony` | writes a mem row when findings survive (bug/decision + files) |
 | Merging | `/git-ship` (`pr` / `land` on a team) | nothing; pure git plumbing |
-| After it ships | `/move-to-done` | writes the ship verdict, closes the loop |
+| After it ships | `/move-to-done` | writes a mem note when the ship taught something, closes the loop |
 | Proving a finished run | `fapony report <run-id>` (CLI, not MCP) | git facts + allowlisted evidence, one page |
 
 **Team flow.** `/git-ship pr` stops once the PR is open and hands you the URL; the reviewer does
@@ -363,7 +372,7 @@ 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
@@ -447,7 +456,7 @@ archived one: [examples/](https://github.com/kire21b/fapony/tree/main/examples).
 
 ```bash
 # Verification & reporting
-fapony mcp                               # MCP server (stdio JSON-RPC — 4 tools)
+fapony mcp                               # MCP server (stdio JSON-RPC — 3 tools)
 fapony report <run-id>                   # verification report for a run
 fapony report-web [file]                 # static HTML report page
 fapony usage-scan                        # scan session logs → cache (incremental, progress bar)
@@ -464,10 +473,24 @@ fapony mem close <id> "<msg>"              # close a bug
 fapony mem find "<text>"                   # substring-search every row
 fapony mem kickoff [<plan.md>]             # open a session + a next-up list
 fapony mem where                           # show the resolved mem dir and which step won
-fapony mem now | done | stale              # views
+fapony mem done | stale              # views
 fapony debt [--id <convention>] [--where <path>]   # ไฟล์ไหนยังไม่ย้ายไป convention ที่ประกาศไว้ (live, read-only)
 fapony lint-baseline [--cmd ...] [--diff]  # separate "already red" from "I made it red"
+```
+
+*When* to call `mem add` is your project's call, not fapony's — write it in your own
+`AGENTS.md`/`CLAUDE.md`, not here. A starting point:
 
+```markdown
+## Memory
+- Found a bug while working (not just user-reported)? Log it before fixing:
+  `mem_add { kind: "bug", worktree: "<absolute app dir>", files: [...], text: "..." }`
+- `text` must stand alone — read months later with no chat context: what/where/repro/status.
+- Report the row id back in chat.
+- Don't fold the fix into the same chunk — log first, fix as its own next/chunk if you do.
+```
+
+```bash
 # Setup & maintenance
 fapony init <path>                       # scaffold .fapony/ (plan/spec/memory/evidence)
 fapony init-mem                          # delete .memory/ + warn call sites still referencing it
@@ -496,11 +519,11 @@ Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB locat
 ## Scope
 
 **Supported:**
-- MCP server — 4 tools via stdio JSON-RPC, works with any MCP client
-- Measurement: cross-run KPIs by model/grade/value, per-file risk (graded touches vs. fails) + passive usage (tokens, cost)
-- Model attribution across clients — resolved from the session log that was live when the verdict landed, so a verdict carries a model without the caller declaring one
-- Zero setup beyond install: the two habits fapony depends on ship in the MCP `initialize` response, not in your rules file
-- Verification (beta): handoff conformance, 6-grade verdicts, allowlisted evidence collector (`.fapony/evidence.json`); reports stamped with the producing build's `server_sha`
+- MCP server — 3 mem tools via stdio JSON-RPC, works with any MCP client
+- Measurement: cross-run KPIs by model/grade/value from the frozen ledger, per-file pain zones from mem rows (`files[]`) + passive usage (tokens, cost)
+- Model attribution across clients — resolved from the session log that was live when the old verdict landed, so a frozen row carries a model without the caller having declared one
+- Zero setup beyond install: the mem habit ships in the MCP `initialize` response, not in your rules file
+- Verification reports (frozen): handoff conformance, 6-grade verdicts, allowlisted evidence collector (`.fapony/evidence.json`); reports stamped with the producing build's `server_sha` — replayable, no new graded runs
 - Vendor-neutral executor/reviewer roles — anything that reads stdin
 - 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)

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 { cmdHookEditHint, 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";
@@ -15,10 +20,10 @@ import { cmdLintBaseline } from "./src/lint-baseline.js";
 import { cmdMcp } from "./src/mcp/transport.js";
 import { cmdMem } from "./src/mem/index.js";
 import { initStore } from "./src/mem/store.js";
-import { cmdPlanSeed } from "./src/plan-seed.js";
 import { cmdPriceScan } from "./src/price/index.js";
 import { cmdReport, cmdReportWeb } from "./src/report/index.js";
-import { cmdReviewSeed } from "./src/review-seed.js";
+import { cmdPlanSeed } from "./src/seed/plan-seed.js";
+import { cmdReviewSeed } from "./src/seed/review-seed.js";
 import { cmdSetup } from "./src/setup.js";
 import { cmdStats } from "./src/stats/index.js";
 import { cmdTelemetry } from "./src/telemetry.js";
@@ -87,6 +92,8 @@ if (cmd === "analyze") {
   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") {
@@ -108,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|hook-edit-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,7 +1,7 @@
 {
   "name": "fapony",
-  "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",
+  "version": "0.3.3",
+  "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
   "homepage": "https://github.com/kire21b/fapony#readme",
@@ -24,8 +24,7 @@
     "fapony.ts",
     "src/",
     "templates/",
-    "skill/",
-    "images/"
+    "skill/"
   ],
   "scripts": {
     "lint": "biome check .",
@@ -33,8 +32,10 @@
     "test": "bun fapony.ts test",
     "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
     "test:one": "bun scripts/test-one.ts",
+    "knip": "bunx knip@6 --exclude types,nsTypes || true",
     "check": "bun run lint && bun run typecheck && bun fapony.ts test",
     "prepublishOnly": "bash scripts/smoke-publish.sh",
+    "release": "git checkout main && git pull --ff-only && npm version patch -m 'release v%s' && git push origin main --follow-tags",
     "overview": "bun fapony.ts report-web /tmp/fapony-overview.html && open /tmp/fapony-overview.html"
   },
   "devDependencies": {

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.