fapony 0.1.0

package/skill/review-pony/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: review-pony
+description: Review a plan, PR, diff, or design doc as a verification rather than an opinion — scope first, walk the real path, break it on paper, cite everything. Takes optional effort (low|medium|high|max, widens the walk only, never skips a pass) and --fix (apply CONFIRMED blocker/major findings after the report). Records the verdict to fapony after the report. Trigger on /review-pony and proactively whenever the user asks to review, audit, scrutinize, sanity-check, or get a second opinion on a plan, PR, diff, design doc, or proposed code change.
+---
+
+# Review Pony
+
+**A review is a verification, not an opinion.** Anything you cannot trace, run, or cite is
+something you feel about the code — and feelings are what make reviews long and useless.
+
+Four passes. Run them in order. Each one is allowed to end the review early.
+
+**Args:** `effort` (`low|medium|high|max`, default `medium`) — widens or narrows pass 2's walk
+only. Passes 1, 3, and 4 run in full at every level; effort never skips verification, it only
+changes how far you walk before writing findings down. There is no `ultra` here — that's
+multi-agent cloud review; point the user at `/code-review ultra` instead.
+`--fix` — after the report, apply every `blocker`/`major` `CONFIRMED` fix (never nits, never
+`PLAUSIBLE`) — details in the `--fix` section below. `--comment` is not supported — PR-posting
+is another tool's job.
+
+## The four passes
+
+1. **Scope is a finding.** Does this need to exist, and does it need to be this big?
+2. **Claims are not facts.** Walk the real path. Run what can be run.
+3. **A finding needs a failing input.** Cannot write one? Not a finding.
+4. **Facts carry a citation.** `file:line`, output, or trace step — or it doesn't ship.
+
+Carry them. Do not post them, and do not narrate them — the reader wants what you found, not
+proof that you looked. Start at pass 1.
+
+---
+
+## Before: scope facts (fapony, optional)
+
+Run `fapony review-seed` with the scope flag matching what you're reviewing (default = uncommitted,
+`--commit <sha>`, `--range <a...b>`, `--files f1,f2,dir`, `--plan <PLAN.md>`). The output is where to
+enter, never coverage — walk it, run it, kill your findings as normal. No fapony CLI or the call
+errors → skip silently and review anyway — a hint, not a gate. Mid-walk, `--files <f> --body <sym>
+--callers <sym>` answers "what does this do / who calls it" without reading the file.
+
+**`--plan` on an already-shipped plan comes back "nothing in this scope" — that's the wrong scope,
+not no scope.** A shipped plan has nothing left in the working tree to diff. If its header cites
+commit shas (`> Status: shipped ... Commits: <sha1> ... <shaN>`), re-run against those — one
+`--range <first-sha>^...<last-sha>` covering them, or `--commit <sha>` per commit — and walk that
+instead. Only treat the plan as prose-only, no code to walk, when its header cites no commits.
+
+## Pass 1 — Scope is a finding
+
+Say what the change is for in one sentence, in your own words. If you can't, the artifact is
+underspecified. That is the review. Report it and stop.
+
+Then take one pass down the ladder, and stop at the first rung that reaches the same goal:
+
+1. **Nothing.** Is the problem load-bearing, or is this a fix for a hypothetical?
+2. **What's already here.** A function, a flag, a stdlib call the author didn't know about.
+3. **A native mechanism.** A DB constraint over app logic, config over code, build over runtime.
+4. **90% for 10%.** The narrow change that solves the real case and drops the exotic ones.
+
+If a rung holds, name it **before** any line-by-line notes. A scope finding is worth more than
+every other finding combined, and it is worth nothing once the author has already rewritten the
+code to answer your nits.
+
+Mandatory even on small changes. Skip only if the user says "don't question scope".
+
+## Pass 2 — Claims are not facts
+
+The diff is where you enter, not what you review.
+
+- **Walk the path end-to-end**: entry point → call sites → branches taken → state mutated → exit
+  or side effect. Read the *unchanged* code on both sides. A diff is correct in isolation far
+  more often than it is correct in place.
+- **Read who calls this.** A signature change is fine until the third caller passes the old shape.
+- **Run what can be run.** Reading cannot see a command that exits 0 without doing anything, a
+  timeout budget no real suite fits, or a server still serving last week's build. A green result
+  you produced outranks a green result you inferred, every time.
+- **For a plan or design doc**, walk the proposed flow against the system that exists — where
+  does it touch reality, and what does it assume that isn't true today?
+
+Write down every place the walk surprises you. Surprises outrank style; chase them first.
+
+**Effort controls how far this walk goes, nothing else:**
+
+- `low` — direct callers only, one hop. No test reading unless the diff touches a test file.
+- `medium` (default) — as written above: full path, callers, tests on the path.
+- `high` — also second-degree callers, and read the tests that exercise them, not just the path.
+- `max` — also run `get_impact_radius_tool` (or grep if the graph isn't wired) on every changed
+  file and re-open every `deferred` line from the last review of this scope, if fapony has one.
+
+Whatever level stopped you, say so in the one-line coverage note (rule below) — "walked to 1 hop"
+is honest, "walked" alone at `low` is not.
+
+## Pass 3 — A finding needs a failing input
+
+Before a finding reaches the report, try to kill it yourself.
+
+- **Write the failure scenario**: concrete inputs or state → the wrong output, crash, or
+  corruption. Can't write that sentence? You have a preference. Drop it.
+- **Look again for the guard you missed.** This is where most findings deserve to die: the
+  validation lives in the caller, the branch is unreachable, the type already excludes it.
+- **Label what survives.** `CONFIRMED` — you traced or ran it. `PLAUSIBLE` — the mechanism is
+  real but you could not reach the failing state. Never let the second wear the first's clothes.
+- **Don't flag by pattern.** "Should use dependency injection" is taste. "Calls `fetch` in a loop
+  whose length comes from user input" is a finding.
+
+## Pass 4 — Facts carry a citation
+
+Every claim points at a `file:line`, a command's output, or the step in the walk that exposed it.
+No citation, no report line.
+
+Keep the claim and the verification in separate sentences. "The PR says it retries twice" and
+"I traced it to `client.ts:88` and the retry is unreachable" are different statements; merging
+them is how a review launders an assumption into a fact.
+
+---
+
+## Report
+
+The reader has the diff and is deciding what to do next. Nothing else belongs here.
+
+**Verdict first, then at most 3 findings, at most 4 lines each, then one deferred line.**
+Severity order: blocker → major → nit, and cut the nits entirely when anything structural
+survived — they dilute the only thing worth reading.
+
+```
+<ship | fix-then-ship | rework | reject> — the single biggest reason, one sentence.
+
+1. <blocker|major|nit> <CONFIRMED|PLAUSIBLE> — what breaks, one line
+   <file:line> — the mechanism, one line
+   repro: <input or state> ⇒ <wrong result vs. right one>
+   fix: <the minimal change>
+
+deferred: <thing> (<where it was specified>) · <thing>
+```
+
+Four lines is a ceiling, not a quota — a finding that fits in two ships in two. Drop `repro:`
+only when the finding is the absence of something (no test, no guard); never drop the citation.
+
+**Cut on sight:** the four passes as headings or prose · what you walked, ran, or ruled out ·
+anything restating the diff, the plan, or the author's reasoning · a nit riding along under a
+blocker · hedging that does not change the verdict.
+
+Finding nothing is a valid result. Then the whole report is the verdict line plus one line
+naming what you walked, so the reader can judge the coverage — not a tour of it.
+
+## --fix (optional)
+
+Only with the `--fix` arg, only after the report is shown. For each `blocker`/`major` finding
+labeled `CONFIRMED`: apply the `fix:` line to the working tree. Skip every nit and every
+`PLAUSIBLE` — a fix you weren't sure was a bug is a bug you're introducing on purpose.
+
+Report what happened in one line per finding, no more:
+
+```
+fixed: 1, 2 · skipped: 3 (PLAUSIBLE — could not reach the failing state)
+```
+
+Fixing changes what actually shipped, not what the review found — re-run pass 4's citation
+check on the new state before calling it done, but don't re-run the whole review. Submit the
+verdict on what you found, not on the post-fix state (`verdict_submit`'s `note` can say the fix
+was applied).
+
+## After: record the verdict (fapony)
+
+Call `verdict_submit` once, after the report is shown. Don't block the report on it, and don't
+let it change the report's content. Pass `regime="review"` — required, and a review is what this
+was; it is what puts this run in the `regime × model` table.
+
+| Report verdict | `verdict` |
+|---|---|
+| ship, 0 findings | `pass-excellent` |
+| ship, nit-only findings | `pass-good` |
+| fix-then-ship | `pass-adequate` |
+| rework / reject | `fail` |
+| could not walk enough to have a verdict | `uncertain` |
+
+`uncertain` is not a softer `fail`. It is the honest answer when the walk never
+reached the thing under review — the branch wouldn't build, the path is behind a
+service you cannot run, every finding came out `PLAUSIBLE`. Say so in the report
+too. Guessing `pass` there is the one outcome that makes the ledger lie.
+
+`reason_code` — the *lead* (most severe) finding, not a generic bucket:
+
+- **0 findings, or a clean pass → `none`** — never `other`. `other` means "a real
+  finding that none of these buckets name", so filing clean passes there puts them
+  in the recurring-fail-reasons list, where they crowd out the reasons that mean
+  something. It is the one value in this table that costs other people accuracy.
+- missing or weak test coverage on the path you walked → `missing_test`
+- change is narrower or wider than the plan / PR description claims → `scope_mismatch`
+- a shell/eval/deploy command runs without the guard it needs → `unsafe_command`
+- the plan or spec didn't cover a case the walk exposed → `spec_gap`
+- the change stops short of what it set out to do → `incomplete`
+- a real finding none of the above names → `other`, and then `note` is **required**
+
+Always attach a one-line `note` — the only field a later review can act on. Say what broke or
+was walked, not that a review happened.
+
+Args: `verdict`, `reason_code`, `note`, `regime`, `worktree` — **absolute path** via
+`git rev-parse --show-toplevel`, never a bare name (`runs.worktree` is free text; a bare name
+writes where no query reads it and every fapony tool misses the run), `plan` (the PLAN file
+path under review, omitted for a bare PR/diff), and `files` — the repo-relative paths you
+actually walked. **Always send `files`.** It is the only input to per-file risk history; a
+verdict without it tells the next session that something failed but not where. No `run_id` —
+fapony reuses the latest still-open run for the same worktree+plan (so round 2+ counts toward
+the round cap), creating a row only when none is open. `session_id` (optional) — the client
+session id, only if the client exposes it; attribute the model, never block the submit on it.
+If `verdict_submit` errors, say so in one line and move on — never re-run a review because
+storage failed.
+
+---
+
+## Rules
+
+The four passes are the rules. These three are what they fail on in practice:
+
+- **Order is not optional.** No line-by-line notes before pass 1, no finding before passes 2-3
+  earned it, nothing stated as fact that pass 4 cannot cite.
+- **The budget is binding.** Verdict, ≤3 findings, ≤4 lines each, one deferred line. Over budget
+  means you are reporting process. "LGTM" is not an output either — finding nothing ships as the
+  verdict line plus one line naming what you walked.
+- **Forget who wrote it.** The author's reasoning is context, never evidence.
+
+## Example
+
+```
+1-4.  scope holds; walked the new gate branch; ran the evidence command — it exits 0
+      without running the suite (CONFIRMED: `bun test` with no test dir exits 0)
+post. verdict_submit(verdict="pass-adequate", reason_code="other", regime="review",
+        note="evidence entry `bun test` exits 0 while running zero tests — real entry is `bun run test`",
+        worktree="/Users/you/Project/fapony/wt-fapony",
+        plan=".fapony/plan/PLAN-verdict-notes.md")
+```
+
+A report in budget — same review that, narrated, ran five paragraphs:
+
+```
+rework — Finding 1 corrupts the ledger this feature exists to keep.
+
+1. blocker CONFIRMED — incremental scan replaces cached history with a delta
+   cache.ts:81 overwrites by client; claude-code.ts:191 returns only new lines
+   repro: line(1000 tok) → scan → +line(500) → scan ⇒ cache 500, truth 1500
+   fix: merge per session_id (plan §5), or drop incremental and always full-scan
+
+2. major CONFIRMED — usage-scan crashes on a machine with no state dir (day 1)
+   cache.ts:68 writes the tmp file; writeCache never mkdirs, store.ts does
+   repro: FAPONY_STATE_DIR=/tmp/nonexistent bun fapony.ts usage-scan ⇒ ENOENT
+   fix: mkdirSync(faponyDir(config), { recursive: true }) before the write
+
+3. major CONFIRMED — SQLite `since` compares seconds to ms, so it never filters
+   helpers.ts:46 — max(time_created)=1789144099203 vs now_s=1789145895
+   repro: opencode all-time 1494 sessions == cached 1494; the filter cannot bite
+   fix: pass since*1000 — but only after 1, or these two clients corrupt too
+
+deferred: bytes_by_tool (plan step 7) · per-client watermark (plan §6.3)
+```