fapony 0.1.2 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@
 
 # fapony
 
+[![npm](https://img.shields.io/npm/v/fapony.svg)](https://www.npmjs.com/package/fapony)
+
 **Where did your tokens go?** fapony reads the session logs Claude Code, Codex, OpenCode and ZCode
 already write, and puts them all on one yardstick — tokens, cost and time per model, per client,
 per workflow. Nothing to instrument, no per-project setup, no waiting for data to accumulate: it
@@ -35,14 +37,14 @@ 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 6 MCP tools any agent can call. If you juggle more than one agent, this is
+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.
 
-**What that question looks like answered, from one project's own ledger (52 graded `code`-regime
-runs, `fapony stats --mode verdict --regime code`):**
+**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`):**
 
 | model | tokens/pass | quality | n |
 |---|---|---|---|
@@ -56,7 +58,19 @@ on you to hold: work isn't randomly assigned to models, so a gap this size is a
 controlled trial — you likely route easy tasks to the cheap model already. `n≥5` is fapony's own
 floor before a model counts toward the frontier at all; below that it's a data point, not a pick.
 
-**The reason to keep it running is the third layer: knowledge accumulation.** 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. Session logs have the tokens but no grades; benchmarks have grades but not your codebase. fapony is the one layer that holds both, because it's the one every client reports into.
+**The reason to keep it running is the third layer: knowledge accumulation — and the thing it
+accumulates is pain.** An agent has no memory of pain across sessions: it writes the 37th
+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.
+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.
 
 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.
 
@@ -67,29 +81,29 @@ Adopting it doesn't change your workflow. There is no loop to join and no framew
 Stated up front, because the gap between these two things is where most tooling oversells:
 
 - **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 — and
-  the report says `not_run` rather than staying quiet.
+  `.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.
-- **`handoff_check` checks conformance, not correctness.** It verifies that what the agent claimed
-  lines up with git facts and that it declared its uncertainty — not that the code works. Those are
-  different guarantees and fapony only offers the first.
-- **Nothing blocks.** There is no gate, no hook, no CI failure. Forget to call it and you are back
-  to exactly the workflow you had.
+- **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 hint only annotates. Skip the
+  install of both 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`;
   read it as such.
 - **The knowledge layer is empty on run 1.** It is worth something around run 5 and more every run
-  after. That is the trade for it being the layer nobody can clone from a feature list.
+  after.
 
 ## Quick start (MCP)
 
 ```bash
 # 1. Install (needs Bun — https://bun.sh)
-git clone https://github.com/kire21b/fapony.git && cd fapony
-bun install
-bun link            # puts `fapony` on your PATH; or run via `bun fapony.ts`
+npm install -g fapony       # or: bun add -g fapony
+#    from source instead:
+#    git clone https://github.com/kire21b/fapony.git && cd fapony && bun install && bun link
 #    note: `bun link` claims the global `fapony` bin by package name, not path — running it
 #    from a second checkout silently repoints the command there. Re-run it in the one you want.
 
@@ -108,23 +122,16 @@ 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_stats and fapony_usage — what has it cost me, per model?"
+#    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
-#    .fapony/evidence.json lists the commands the evidence collector may run —
-#    edit the placeholder cmds to your real test/typecheck commands
-#    commit it: the allowlist is a security boundary your whole team shares.
-#    If your .gitignore ignores .fapony/ wholesale, re-include it (dir before file):
-#      **/.fapony/*
-#      !**/.fapony/evidence.json
-#    Monorepo: give an app its own apps/<app>/.fapony/evidence.json and reports whose
-#    changed files all sit under that app use it; anything else uses the root one.
+#    edit .fapony/evidence.json to your real test/typecheck commands, then commit it
 ```
 
 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 6 tools](#the-6-tools) below). Grade something first;
+called them (see [The 4 tools](#the-4-tools) below). Grade something first;
 `verdict_submit` is what creates the run:
 
 ```bash
@@ -135,6 +142,8 @@ You get one report: git facts (files, commits, branch), handoff conformance (cla
 
 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.
 
+Two details for the allowlist once it is under version control. If your `.gitignore` ignores `.fapony/` wholesale, re-include the file (dir before file): `**/.fapony/*`, then `!**/.fapony/evidence.json`. In a monorepo, give an app its own `apps/<app>/.fapony/evidence.json` — reports whose changed files all sit under that app use it; anything else uses the root one.
+
 Two things worth knowing about the report header and budget:
 
 - **`server_sha`** — every report is stamped with the git SHA of the fapony code that produced it, read once at server start. MCP servers are long-lived: after you edit fapony and don't restart the client, reports keep coming from the old build. Compare the stamp against `git log -1` in the fapony repo; if they differ, reconnect the server before trusting the result.
@@ -151,7 +160,7 @@ flowchart LR
     F --> G[git facts + session logs]
     G --> S[stats / usage]
     G --> V[verification report]
-    G --> P[project_health - optional]
+    G --> M[mem log - what was decided here]
 ```
 
 fapony never drives the agent. It sits on two sides of your work that never touch each
@@ -161,7 +170,7 @@ losing a single number.
 
 | | The ledger | The work side |
 |---|---|---|
-| What it is | 6 MCP tools + a SQLite ledger | plans, skills, read-only seed commands |
+| What it is | 4 MCP tools + a SQLite ledger | 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 |
 | Skip it and | there is no fapony | fapony still answers every question |
@@ -189,36 +198,34 @@ sequenceDiagram
         A->>F: fapony report <run-id>
         F-->>A: git facts + evidence from .fapony/evidence.json, stamped with server_sha
     end
-    A->>F: fapony_stats
-    F->>L: read across every run, client and project
-    L-->>A: model x regime x quality — which model to pay for this shape
+    Note over A,L: `fapony stats` reads it back — CLI, because you ask it, not the agent
 ```
 
-The Stop hook is the only thing fapony does *to* you — once per turn, when a commit ends
-ungraded. It never picks the grade; it cannot see whether the work held up.
-
-### The 6 tools
+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.
 
-```
-discover: plan_list (plans grouped by state, joined with their run history)
-measure:  fapony_stats ── fapony_usage
-verify:   verdict_submit
-recall:   project_health_context (what failed in these files before — optional, never required)
-          mem_find (what was ever decided about these files — reads the project's mem log)
-```
+### The 4 tools
 
 | Tool | Tier | Purpose |
 |------|------|---------|
-| `plan_list` | discover | Plan files grouped by state — active / blocked / untouched / superseded / trackers — with a progress tally and each one's run history. Not a raw `ls`; see [Plans your agent can answer questions about](#plans-your-agent-can-answer-questions-about) |
-| `fapony_stats` | measure | KPIs across runs: by-model (gates, fail rate, quality, tokens), by-grade, planned vs dove-in, regime x model, per-file risk; `group_by: reason_code\|plan\|file` for top-N slices; `mode: verdict` ranks models by quality vs tokens/pass instead of listing raw counts |
 | `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 |
-| `project_health_context` | recall | Known-patterns block for the files you are about to touch. Useful when a file does have history; measured across real repos, most do not (1-9% of shipped files come back under a `fix:` within two weeks), so it is optional — never a precondition for editing |
-| `mem_find` | recall | Search the project's mem log read-only — decisions/bugs/notes keyed by `files[]`, `text`, `kind` (no default filter), `since`. "What was ever decided about this file?" in one call before editing |
+| `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 |
 
-The handoff/report family is CLI-only — the schemas cost every session of every client and no skill called them. `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.
+**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.
 
-Full protocol, adapter examples (bash, Python), and safety rules: [docs/mcp-handcheck.md](docs/mcp-handcheck.md).
+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
 
@@ -304,9 +311,7 @@ flowchart TD
 **The fork at the top is load-bearing.** A plan file is an artifact for work the next session has
 to pick up. Wiring, refactors and UI passes finish in one sitting and the PLAN.md gets archived
 unread — so `/plan-with-pony` declines those itself and hands over the two seed commands instead.
-`fapony review-seed --files` takes a directory as well as file names, and answers "what is in
-here, who imports it, what is untested" for about a thirtieth of the tokens reading those files
-costs. Both arms meet at the same review and the same ledger.
+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
@@ -345,7 +350,7 @@ cat skill/plan-with-pony/SKILL.md | opencode run  # OpenCode
 cat skill/plan-with-pony/SKILL.md | <your-agent>  # anything that reads stdin
 ```
 
-Example plans produced by it live in [examples/](examples/).
+Example plans produced by it live in [examples/](https://github.com/kire21b/fapony/tree/main/examples).
 
 ### Plans your agent can answer questions about
 
@@ -368,29 +373,31 @@ blocks: PLAN-export.md         # ordering, stated once instead of buried in pros
 - [ ] chunk 2 — move overdue out
 ```
 
-Then ask your agent *"what's left, and what's blocked?"* — `plan_list` answers from the
-frontmatter and from fapony's own run history, without reading a single 100KB plan body into
-context (`format: "markdown"`):
+Then open the next session with `fapony mem kickoff` — it reads the folder and the mem log and
+prints what is next (priority plans, the first unchecked chunk of each, open bugs) without
+reading a single 100KB plan body into context:
 
 ```
-## active — in order (2)
-- [ ] PLAN-calendar — 1/3 · unblocks PLAN-export
-- [ ] PLAN-export — never attempted
-## blocked (1)
-- [ ] PLAN-attendance — waiting: PLAN-documents.md
-## untouched (14) · trackers (3)
-done: 63 archived
+## next up
+  [1] chunk 2 — move overdue out (PLAN-calendar.md)
+  [2] bug #mu8t5qve — money drifts in the month grid…
+      → fapony mem close mu8t5qve "<msg>"
+  [3] last touched: src/quick/month.tsx, src/lib/money.ts
 ```
 
-**Plans with no frontmatter still work** — they are grouped by run history alone (attempted =
-active, never attempted = untouched), so an existing folder of plans is queryable before anyone
-annotates anything. Two details that keep it honest over years:
+**Plans with no frontmatter still work** — the unchecked checkboxes are enough, so an existing
+folder of plans is usable before anyone annotates anything. Two details that keep it honest over
+years:
 
 - The progress tally counts checkboxes in the **first `##` section only**, anchored by position
   rather than by the word "TL;DR" — so it works in any language, and a step list deeper in the
   file stays detail instead of becoming status.
-- **There is no `MASTER.md`.** Every line of the list above is derived from frontmatter and
-  checkboxes, so it cannot drift; a hand-kept master file always does.
+- **There is no `MASTER.md`.** Every line above is derived from the plan files themselves, so it
+  cannot drift; a hand-kept master file always does.
+
+`status` / `blocked_by` / `blocks` / `superseded_by` are read by people, not by a tool — the one
+that read them, `plan_list`, was removed in 2026-09 once `mem kickoff` answered the same
+question from the CLI, where a schema costs nothing until it runs.
 
 The layout, and why archiving is a plain `git mv`:
 
@@ -404,13 +411,13 @@ The layout, and why archiving is a plain `git mv`:
 Ship dates live in the plan's own header (`> ✅ **shipped 2026-09-13** (a1b2c3)`), not in the
 filename — `grep -h shipped .fapony/done/*.md | sort` answers "what landed when" without paying
 to rewrite every inbound link on every ship. Example plans, including an un-annotated one and an
-archived one: [examples/](examples/).
+archived one: [examples/](https://github.com/kire21b/fapony/tree/main/examples).
 
 ## CLI
 
 ```bash
 # Verification & reporting
-fapony mcp                               # MCP server (stdio JSON-RPC — 6 tools)
+fapony mcp                               # MCP server (stdio JSON-RPC — 4 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)
@@ -421,42 +428,52 @@ fapony digest [--since 7d|YYYY-MM-DD] [--format text|html] [--json] [--out FILE]
 fapony plan-seed <name> [--spec] [--scope <path>]...  # write PLAN (+SPEC): frontmatter, 8 empty sections, prior-art list, ledger context; SPEC chunks carry signatures, every section capped — the agent fills the judgment
 fapony review-seed [--staged|--commit <sha>|--range <a...b>|--files f1,f2,dir|--plan <PLAN.md>]  # read-only scope facts for a review (changed files, importers, untested, signatures, plan cross-check)
 
+# Memory & convention debt
+fapony mem add <kind> "<text>" --files f1,f2 [spec.md]   # append a mem row (decision/bug/note/next/hold)
+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 debt [--id <convention>] [--where <path>]   # ไฟล์ไหนยังไม่ย้ายไป convention ที่ประกาศไว้ (live, read-only)
+fapony lint-baseline [--cmd ...] [--diff]  # separate "already red" from "I made it red"
+
 # Setup & maintenance
 fapony init <path>                       # scaffold .fapony/ (plan/spec/memory/evidence)
-fapony init-mem [--update]               # refresh the memory scaffold from the template
+fapony init-mem                          # delete .memory/ + warn call sites still referencing it
 fapony install                            # detect installed clients, prompt to wire each
 fapony install --all                      # wire all detected clients without prompting
 fapony install --platform <name>          # force a specific client (bypasses detection)
 fapony install --dry-run                  # show what would happen without writing files
 fapony setup                             # interactive wizard: config + scaffold in one step
 fapony update                            # self-update via git pull
-fapony telemetry show|send               # opt-in only, default off — see TELEMETRY.md
+fapony telemetry show|send               # opt-in only, default off — see https://github.com/kire21b/fapony/blob/main/TELEMETRY.md
 fapony test                              # self-check
 ```
 
 ## Config
 
-`fapony.config.json` lives in the fapony checkout and is gitignored (it's per-machine). Copy [fapony.config.example.json](fapony.config.example.json) for a complete working reference; every section is optional with sane defaults. Key fields:
+`fapony.config.json` lives in the fapony checkout and is gitignored (it's per-machine). Copy [fapony.config.example.json](https://github.com/kire21b/fapony/blob/main/fapony.config.example.json) for a complete working reference; every section is optional with sane defaults. Key fields:
 
 - `worktrees` — name → absolute path mapping
 - `review.maxRounds` — round cap enforced by the gate
-- `memory` — shell commands for claim/close/add/kickoff, or `null` to default-wire when `.fapony/.memory/mem.ts` exists
-- `paths` (`planDir`/`doneDir`/`specDir`/`memoryEntry`/`stateDir`) / `safety` — directory layout and the dangerous-command deny-list
+- `memory` — shell commands for claim/close/add/kickoff, or `null` to default-wire when a `.fapony/.memory/` dir exists
+- `paths` (`planDir`/`doneDir`/`specDir`/`memDir`/`stateDir`) / `safety` — directory layout and the dangerous-command deny-list
 - `usageWeb` — optional `{ port, hostname }` for `fapony usage-web` server defaults. Run `fapony usage-scan` first to populate the cache.
 
-Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB location; default `~/.config/fapony/`). Full schema, design decisions, and edge cases are documented in [CLAUDE.md](CLAUDE.md) — this README intentionally doesn't duplicate them.
+Env overrides: `FAPONY_CONFIG` (config file), `FAPONY_STATE_DIR` (state DB location; default `~/.config/fapony/`), `FAPONY_NO_REREAD_HINT=1` (turn the re-read hint off). Full schema, design decisions, and edge cases live with the code in the repo — this README intentionally doesn't duplicate them.
 
 ## Scope
 
 **Supported:**
-- MCP server — 6 tools via stdio JSON-RPC, works with any MCP client
+- 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` — agent-proposed commands are never executed); reports stamped with the producing build's `server_sha`
+- Verification (beta): handoff conformance, 6-grade verdicts, allowlisted evidence collector (`.fapony/evidence.json`); reports stamped with the producing build's `server_sha`
 - 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](TELEMETRY.md) lists exactly what leaves the machine)
+- 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)
 
 **Not supported (yet):**

package/fapony.ts

@@ -3,6 +3,7 @@
 // fapony — measure/verify MCP server for coding agents
 // CLI dispatch: all logic lives in src/
 
+import { existsSync } from "node:fs";
 import { cmdAnalyze } from "./src/analyze.js";
 import { cmdDebt } from "./src/debt.js";
 import { cmdDigest } from "./src/digest/cli.js";
@@ -12,6 +13,8 @@ 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";
@@ -42,6 +45,34 @@ if (cmd === "analyze") {
   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") {
@@ -75,7 +106,7 @@ if (cmd === "analyze") {
 } else {
   console.error(`fapony: unknown command "${cmd ?? ""}"`);
   console.error(
-    "usage: fapony <setup|update|stats|telemetry|init|init-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|test> [args]",
   );
   process.exit(1);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fapony",
-  "version": "0.1.2",
-  "description": "Measurement layer for coding agents — measure what agents do, verify what they claim. 6 MCP tools, any agent, no loop required",
+  "version": "0.2.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)",
   "homepage": "https://github.com/kire21b/fapony#readme",
@@ -24,13 +24,15 @@
     "fapony.ts",
     "src/",
     "templates/",
-    "skill/"
+    "skill/",
+    "images/"
   ],
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
     "test": "bun fapony.ts test",
     "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
+    "test:one": "bun scripts/test-one.ts",
     "check": "bun run lint && bun run typecheck && bun fapony.ts test",
     "prepublishOnly": "bash scripts/smoke-publish.sh",
     "overview": "bun fapony.ts report-web /tmp/fapony-overview.html && open /tmp/fapony-overview.html"

package/skill/move-to-done/SKILL.md

@@ -36,28 +36,19 @@ You are about to move a PLAN that has been shipped to the archive.
 
    A plan that is merely *waiting* (on a person, a customer, a decision) is **not** dead and does
    not move — mark it `status: blocked` + `blocked_by: <what you are waiting for>` and leave it in
-   `plan/`, where `plan_list` will report it as blocked instead of as backlog.
+   `plan/` — the frontmatter is for the next person reading the folder, and the plan stays out
+   of `done/`, which is what `plan-sweep` and `kickoff` go by.
 
-2. **Check inbound links, then `git mv`** — `.fapony/done/` sits *beside* `.fapony/plan/`, at the
-   same depth, so every relative link *inside* the plan (`../spec/SPEC-x.md`, `../../src/...`)
-   keeps working untouched. Nothing to normalize. What does change is how *other plans* reach
-   this one — a sibling reference becomes a `done/` one:
+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:
    ```bash
-   grep -rln 'PLAN-foo.md' .fapony/plan/ .fapony/spec/ docs/   # who points at it
-   git mv .fapony/plan/PLAN-foo.md .fapony/done/PLAN-foo.md    # same name, same depth
-   #  in .fapony/plan/*.md:  (PLAN-foo.md)  ->  (../done/PLAN-foo.md)
+   fapony mem plan-sweep <PLAN-foo.md> --apply
    ```
-   Fewer than 5 inbound files → fix them yourself · more → report the list.
-
-   **The filename gets no date prefix.** The ship date is already in the header (step 1), and
-   duplicating it into the name buys a sortable `ls` at the price of rewriting every inbound link
-   on every ship, forever. "What shipped on which day" is a question to derive, not to store:
-   ```bash
-   grep -h 'shipped' .fapony/done/*.md | sort
-   ```
-   If git refuses ("not under version control" — `.fapony/` is gitignored in
-   this repo), plain `mv` instead; there's nothing to commit for an untracked path, so skip
-   step 4 in that case.
+   It refuses if the file lacks a shipped header or has open mem rows (next/bug/hold/decision/note).
+   If git refuses ("not under version control" — `.fapony/` is gitignored in this repo), plain
+   `mv` instead; there's nothing to commit for an untracked path, so skip step 4 in that case.
+   The filename gets no date prefix — the ship date is already in the header (step 1).
 
 3. **Leave the spec where it is** — `.fapony/spec/` is a reference library, not a queue. A spec
    answers "how does this work", which is asked long after the plan that ordered it shipped, and
@@ -80,15 +71,14 @@ You are about to move a PLAN that has been shipped to the archive.
      `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 reach the three
-     free-text slots `project_health_context` shows — so "clean ship" evicts a note that would
-     have taught the next session something. Write one only when this plan hit something a
+     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 (`fapony_usage`, `fapony_stats`, `project_health_context`)
-     scopes by absolute path too; a bare repo name won't match those queries
+     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
@@ -101,8 +91,8 @@ You are about to move a PLAN that has been shipped to the archive.
 Input: .fapony/plan/PLAN-kickoff.md, no shipped header yet
 Steps:
 1. stamp header: > ✅ **shipped 2026-09-13** (a1b2c3)
-2. inbound: README.md, .fapony/plan/PLAN-loop.md → (PLAN-kickoff.md) becomes (../done/PLAN-kickoff.md)
-   git mv .fapony/plan/PLAN-kickoff.md .fapony/done/PLAN-kickoff.md
+2. fapony mem plan-sweep .fapony/plan/PLAN-kickoff.md --apply
+   → 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"])
@@ -122,5 +112,5 @@ A ship worth a note looks like this instead:
 
 - No git repo / no commits (can't derive a shipped hash) → tell user: "Add header > ✅ **shipped** (<hash>) first"
 - Stamped the header yourself → always say which hash you used
-- Link normalize fails → report which paths normalized wrong
-- Too many inbound links → report full list, don't fix yourself
+- plan-sweep refuses (open mem rows) → close them or use `MEM_FORCE=1`
+- Too many inbound links → plan-sweep reports them; too many to fix → report the list

package/skill/plan-with-pony/SKILL.md

@@ -106,6 +106,11 @@ So the seed buys you structure; the draft budget goes on judgment:
 - **Run the Phase −1 commands for facts** when the idea needs them, and put the numbers in the
   section they answer — a number you measured beats a number the seed guessed at.
 - **Signatures live in the SPEC chunks only.** Never paste them into plan §7 — link to the spec.
+- **Does this zone already owe a convention?** If the feature touches a directory, run
+  `fapony debt` once and read only the entries whose files overlap it. An open migration
+  ("36 files still throw raw errors") is a constraint for §4, not a side quest — a plan that
+  adds the 37th is how the debt got there. Nothing overlaps, or no `conventions.json`? Say
+  nothing and move on.
 - If the CLI is missing, skip silently and draft from scratch (Phase 2 as written) — never block
   on a missing tool.
 
@@ -140,8 +145,8 @@ normal — writing to the default there scatters plans into a directory nobody r
 by hand, this check is yours.)
 
 **Editing a plan someone is executing right now is a different job from drafting one.** Ask the
-dev, or call `plan_list` — it joins plan files against run history, so a plan with an open run is
-one an agent is working from this minute. When that is the case:
+dev, or run `fapony mem kickoff` — it reads the same plan files and names the first unchecked
+chunk, so a plan already in flight is the one you are about to edit under someone. When that is the case:
 
 - **Anything you add is an instruction, not a note.** A measured fact parked under "don't do"
   still reads as a to-do to an agent mid-execution — the numbers are what make it tempting.
@@ -180,7 +185,7 @@ only place that ordering stays true.
 
 **The TL;DR is 15 lines, hard cap, and is the only part that changes while the work is in flight**
 (tick a box, stamp a short sha). Everything below it is the agreement. A TL;DR allowed to grow
-becomes a second copy of the plan, and then neither copy can be trusted. `plan_list` tallies the
+becomes a second copy of the plan, and then neither copy can be trusted. `fapony mem kickoff` reads the
 checkboxes in the **first `##` section only**, so section 6 stays detail rather than status.
 
 Section 6 — every step must be verifiable. Section 8 — must link back to anything it came from.

package/src/analyze.ts

@@ -132,7 +132,19 @@ export function isTestedThroughBarrels(
 export const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
 
 // Always skipped, hardcoded — no config (per plan: no .faponyignore in v1).
-const SKIP_DIRS = new Set(["node_modules", "dist", "build", ".git"]);
+// "templates" for the same reason knip.json ignores templates/**: those files
+// ship as a template copied into other repos by `fapony init-mem` and never
+// have real importers here — scanning them produces false wrapper/orphan
+// signals (measured: conventions-seed flagged 8 "wrappers" that were all
+// src/mem/commands/*.ts helpers matched against unrelated identically-
+// named calls elsewhere in the repo, e.g. "cmdNow() instead of now(").
+const SKIP_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  ".git",
+  "templates",
+]);
 
 // A nested checkout (clone or `git worktree add`) is a different project that
 // happens to live inside this one — walking it doubles the graph and makes every

package/src/conventions-seed.ts

@@ -190,7 +190,6 @@ async function eslintRows(
   const rows: SeedRow[] = [];
   const configs: string[] = [];
   const skipped: string[] = [];
-  const seen = new Set<string>();
   for (const abs of findConfigFiles(root)) {
     let raw: string;
     try {

package/src/db/defaults.ts

@@ -11,7 +11,7 @@ export const DEFAULT_SPEC_DIR = ".fapony/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_MEMORY_ENTRY = ".fapony/.memory/mem.ts";
+export const DEFAULT_MEM_DIR = ".fapony/.memory";
 export const DEFAULT_EVIDENCE_FILE = ".fapony/evidence.json";
 
 export const DEFAULT_CONFIG: Config = {