fapony 0.3.0 → 0.3.4

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.
@@ -123,21 +126,23 @@ fapony price-scan                         # fetch the OpenRouter price table →
 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
 
-# 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.
 
@@ -170,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
@@ -184,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` `mem_close` `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 | ✅ | ✅ | — | ✅ | ✅ |
@@ -202,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
 
@@ -214,32 +219,32 @@ 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 |
 |------|------|---------|
-| `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 |
@@ -250,14 +255,16 @@ every client whether or not it is used, while a CLI command costs nothing until
 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.
+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 |
 |-------|---------|
@@ -271,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
 
@@ -309,7 +316,7 @@ 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` |
@@ -330,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
 ```
@@ -343,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
@@ -448,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)
@@ -465,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
@@ -497,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

@@ -1,121 +1,8 @@
 #!/usr/bin/env bun
 
 // fapony — measure/verify MCP server for coding agents
-// CLI dispatch: all logic lives in src/
+// CLI dispatch lives in src/adapters/cli.ts
 
-import { existsSync } from "node:fs";
-import { cmdAnalyze } from "./src/analyze.js";
-import { cmdDebt } from "./src/debt/cli.js";
-import { cmdDigest } from "./src/digest/cli.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";
-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 { cmdSetup } from "./src/setup.js";
-import { cmdStats } from "./src/stats/index.js";
-import { cmdTelemetry } from "./src/telemetry.js";
-import { cmdUpdate } from "./src/update.js";
-import { cmdUsageScan, cmdUsageWeb } from "./src/usage/index.js";
+import { cliMain } from "./src/adapters/cli.js";
 
-const [cmd, ...a] = process.argv.slice(2);
-
-if (cmd === "analyze") {
-  cmdAnalyze(a);
-} else if (cmd === "debt") {
-  cmdDebt(a);
-} else if (cmd === "lint-baseline") {
-  cmdLintBaseline(a);
-} else if (cmd === "plan-seed") {
-  cmdPlanSeed(a);
-} else if (cmd === "review-seed") {
-  cmdReviewSeed(a);
-} else if (cmd === "digest") {
-  await cmdDigest(a);
-} else if (cmd === "stats") {
-  cmdStats(a);
-} else if (cmd === "telemetry") {
-  await cmdTelemetry(a);
-} else if (cmd === "init-mem") {
-  cmdInitMem(a);
-} else if (cmd === "mem") {
-  // `--mem-dir <path>` is global to `mem` and must reach both the writer
-  // (initStore) and the resolver behind `mem where` — parse it once and thread
-  // it through, never strip it and forget.
-  const memDirIdx = a.indexOf("--mem-dir");
-  let overrideMemDir: string | undefined;
-  let rest = a;
-  if (memDirIdx !== -1) {
-    overrideMemDir = a[memDirIdx + 1];
-    if (!overrideMemDir || overrideMemDir.startsWith("--")) {
-      console.error("fapony mem: --mem-dir needs a value");
-      process.exit(1);
-    }
-    if (!existsSync(overrideMemDir)) {
-      console.error(
-        `fapony mem: --mem-dir path does not exist: ${overrideMemDir}`,
-      );
-      process.exit(1);
-    }
-    rest = a.filter((_, i) => i !== memDirIdx && i !== memDirIdx + 1);
-  }
-  initStore(process.cwd(), overrideMemDir);
-  try {
-    await cmdMem(rest, overrideMemDir);
-  } catch (e) {
-    console.error(`fapony mem: ${e instanceof Error ? e.message : String(e)}`);
-    process.exit(1);
-  }
-} else if (cmd === "init") {
-  await cmdInit(a);
-} else if (cmd === "install") {
-  await cmdInstall(a);
-} else if (cmd === "setup") {
-  await cmdSetup();
-} else if (cmd === "update") {
-  await cmdUpdate();
-} else if (cmd === "hook-stop") {
-  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") {
-  cmdReport(a);
-} else if (cmd === "report-web") {
-  cmdReportWeb(a);
-} else if (cmd === "usage-scan") {
-  cmdUsageScan(a);
-} else if (cmd === "price-scan") {
-  await cmdPriceScan(a);
-} else if (cmd === "usage-web") {
-  cmdUsageWeb(a);
-} else if (cmd === "test") {
-  // dynamic: src/test.js re-exports test/index.js, which the npm package
-  // doesn't ship (repo self-check only, not a published command) — a static
-  // import here would fail module load for every command, not just this one
-  const { cmdTest } = await import("./src/test.js");
-  await cmdTest();
-} 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|hook-session-start|test> [args]",
-  );
-  process.exit(1);
-}
+cliMain();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fapony",
-  "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",
+  "version": "0.3.4",
+  "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",
@@ -18,14 +18,13 @@
     "coding-agent"
   ],
   "bin": {
-    "fapony": "./fapony.ts"
+    "fapony": "fapony.ts"
   },
   "files": [
     "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/move-to-done/SKILL.md

@@ -31,7 +31,7 @@ You are about to move a PLAN that has been shipped to the archive.
    status: superseded
    superseded_by: PLAN-bar.md
    ```
-   Then skip step 5 — no work shipped, so there is no verdict to record. Never archive a plan as
+   Then skip step 5 — no work shipped, so there is nothing to record. Never archive a plan as
    superseded on your own reading; the user says which plan replaced it.
 
    A plan that is merely *waiting* (on a person, a customer, a decision) is **not** dead and does
@@ -40,8 +40,9 @@ You are about to move a PLAN that has been shipped to the archive.
    of `done/`, which is what `plan-sweep` and `kickoff` go by.
 
 2. **Run `plan-sweep --apply`** — this does the `git mv`, rewrites markdown links inside the
-   file and inbound links from other plan files, warns about plain-text mentions, and logs
-   a decision row — all in one call:
+   file and inbound links from every `.md` under `.fapony/` (`plan/`, `done/`, `spec/`),
+   warns about plain-text mentions and about tracked files outside `.fapony/` that still
+   name the file (both detect-only), and logs a decision row — all in one call:
    ```bash
    fapony mem plan-sweep <PLAN-foo.md> --apply
    ```
@@ -60,29 +61,19 @@ You are about to move a PLAN that has been shipped to the archive.
    chore(plan): archive PLAN-foo.md (shipped <hash>)
    ```
 
-5. **Record the verdict** — call the `verdict_submit` MCP tool (fapony) so this ship counts
-   toward what this project knows about the model that did the work. No `run_id` needed:
-   - `verdict`: `pass` (adjust if the ship had known rough edges — see VERDICT_GRADES)
-   - `regime`: **required** — the shape of the work that shipped: `code` for a feature or
-     refactor, `fix` for a bug fix, `plan` when what shipped was the plan or spec itself
-   - `reason_code`: **`none` when the ship was clean** — not `other`. `other` means "a real
-     problem none of the buckets name", so a clean ship filed there shows up in the
-     recurring-fail-reasons list and crowds out the reasons that mean something. Otherwise
-     `missing_test` / `scope_mismatch` / `unsafe_command` / `spec_gap` / `incomplete`, and
-     `other` (with a `note`, which it requires) only when a real finding fits none of them
-   - `note`: **omit it on a clean ship.** A verdict with no note still counts toward the plan
-     history future drafts read ("passed round 1 before"), but only notes carry prose forward — so
-     "clean ship" evicts a note that would have taught the next session something. Write one only when this plan hit something a
-     reader could not get from the diff: what the symptom looked like, where the cause actually
-     was, and the rule that follows. Standalone prose — it is read months later with no access
-     to this conversation.
-   - `worktree`: **absolute path** to this repo/worktree (`git rev-parse --show-toplevel`) —
-     every other fapony tool and query scopes by
-     absolute path too; a bare repo name won't match them
-   - `plan`: the archived plan's path (post-move, e.g. `.fapony/done/PLAN-foo.md`)
-   - `files`: repo-relative paths this plan touched (`git diff --name-only <base>..HEAD`) —
-     the only input to per-file risk history; without it the verdict says something happened
-     but not where
+5. **Leave a note when the ship taught something** — `plan-sweep --apply` (step 2)
+   already logged the ship itself as a decision row, so a clean ship needs nothing
+   more. When the plan hit something a reader could not get from the diff, call the
+   `mem_add` MCP tool (fapony) once:
+   - `kind`: `note`
+   - `text`: what the symptom looked like, where the cause actually was, and the
+     rule that follows. Standalone prose — it is read months later with no access
+     to this conversation. Write one only then — "clean ship" files nothing, and a
+     note that repeats the diff teaches the next session nothing
+   - `files`: repo-relative paths this plan touched (`git diff --name-only <base>..HEAD`)
+   - `spec`: the archived plan's path (post-move, e.g. `.fapony/done/PLAN-foo.md`)
+   - `worktree`: **absolute path** (`git rev-parse --show-toplevel`) — every other
+     fapony tool scopes by absolute path too; a bare repo name won't match them
    Skip only if fapony's MCP tools aren't available in this session — don't block the archive on it.
 
 ## Example
@@ -95,17 +86,16 @@ Steps:
    → moved, links rewritten, decision logged
 3. spec: untouched, stays in .fapony/spec/
 4. commit
-5. verdict_submit(verdict="pass", reason_code="none", regime="code", worktree="/Users/you/Project/fapony/wt-fapony", plan=".fapony/done/PLAN-kickoff.md", files=["src/kickoff.ts"])
-   — clean ship, so no note
+5. (clean ship — plan-sweep's decision row already recorded it, nothing more to file)
 ```
 
 A ship worth a note looks like this instead:
 
 ```
-5. verdict_submit(verdict="pass-adequate", reason_code="spec_gap", regime="fix",
-     note="sheet scroll reset on open, not close — the restore hook was on the wrong side; the router's own scrollRestoration resets on every navigate(). Check the router option before writing a restore hook.",
-     worktree="/Users/you/Project/vela", plan=".fapony/done/PLAN-quick-nav.md",
-     files=["src/routes/expenses/index.tsx"])
+5. mem_add(kind="note",
+     text="sheet scroll reset on open, not close — the restore hook was on the wrong side; the router's own scrollRestoration resets on every navigate(). Check the router option before writing a restore hook.",
+     files=["src/routes/expenses/index.tsx"], spec=".fapony/done/PLAN-quick-nav.md",
+     worktree="/Users/you/Project/vela")
 ```
 
 ## If fail