fapony 0.1.3 → 0.2.1

package/README.md

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

package/fapony.ts

@@ -3,15 +3,18 @@
 // 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";
-import { cmdHookReadHint, cmdHookStop } from "./src/hook.js";
+import { cmdHookEditHint, cmdHookReadHint, cmdHookStop } from "./src/hook.js";
 import { cmdInit } from "./src/init.js";
 import { cmdInitMem } from "./src/init-mem.js";
 import { cmdInstall } from "./src/install.js";
 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") {
@@ -54,6 +85,8 @@ if (cmd === "analyze") {
   await cmdHookStop();
 } else if (cmd === "hook-read-hint") {
   await cmdHookReadHint();
+} else if (cmd === "hook-edit-hint") {
+  await cmdHookEditHint();
 } else if (cmd === "mcp") {
   cmdMcp();
 } else if (cmd === "report") {
@@ -75,7 +108,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|hook-edit-hint|test> [args]",
   );
   process.exit(1);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fapony",
-  "version": "0.1.3",
-  "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.1",
+  "description": "Measurement layer for coding agents \u2014 measure what agents do, verify what they claim. 4 MCP tools, any agent, no loop required",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
   "homepage": "https://github.com/kire21b/fapony#readme",
@@ -32,6 +32,7 @@
     "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.