fapony 0.2.1 → 0.3.0

package/README.md

@@ -122,7 +122,6 @@ fapony usage-scan                         # scan the session logs already on dis
 fapony price-scan                         # fetch the OpenRouter price table → ~/.config/fapony/prices.json
 fapony usage-web                          # dashboard; re-run the scans to refresh
 #    both scans are manual by design — nothing fetches or re-reads session logs behind your back
-#    ask your agent: "Run fapony_usage — what has it cost me, per model?"
 
 # 4. Verify (optional, per project) — scaffold the evidence allowlist
 fapony init /path/to/your-worktree
@@ -185,7 +184,7 @@ is `tool.execute.after`. Nothing here is required: skip the hooks and every MCP
 
 | | Claude Code | OpenCode | Cursor | ZCode | Codex |
 |---|---|---|---|---|---|
-| MCP tools — `mem_find` `mem_add` `fapony_usage` `verdict_submit` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| MCP tools — `mem_find` `mem_add` `mem_close` `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 | — | — | — |
@@ -240,17 +239,17 @@ count, once per session, before you change its shape; OpenCode's **commit** hook
 
 | Tool | Tier | Purpose |
 |------|------|---------|
-| `fapony_usage` | measure | Passive usage from OpenCode, ZCode, Claude Code, and Codex sessions (tokens, cost, by-model; `detail:true` adds per-step timing) |
 | `verdict_submit` | verify | Store a 6-grade verdict (pass-excellent → uncertain) with a required `regime` — the task shape the grade applies to |
 | `mem_find` | recall | Search the project's mem log read-only — decisions/bugs/notes matched on the row's `files[]` (text substring for rows written without it), `text`, `kind` (no default filter), `since`. "What was ever decided about this file?" in one call before editing |
 | `mem_add` | recall | Append a mem row (decision/bug/note/next/hold) with `files[]` required and rejected when empty — the write half of `mem_find`, so the row is findable when you next touch that file |
+| `mem_close` | recall | Close a mem row by id with a tombstone message — a separate tool (not `kind:"close"`) because a close row carries no `files[]`, so sharing `mem_add`'s schema would make required fields depend on another field's value |
 
 **A tool earns its schema by being called mid-task without being asked.** Everything you invoke
 deliberately is a CLI command instead: the schema is paid as input tokens in every session of
 every client whether or not it is used, while a CLI command costs nothing until it runs. That is
-why the handoff/report family is CLI-only, and why `fapony_stats`, `project_health_context` and
-`plan_list` left the MCP surface in 2026-09 (`fapony stats` answers the first, `fapony mem
-kickoff` the third; the second had no caller).
+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.
 
@@ -304,13 +303,15 @@ That is the whole trick; there is no model in the middle.
 
 ### Skills
 
-fapony ships five portable skills, each as `skill/<name>/SKILL.md` — the layout Claude
+fapony ships seven portable skills, each as `skill/<name>/SKILL.md` — the layout Claude
 Code expects, so a client can symlink the directory rather than copy the file:
 
 | Skill | Purpose | Trigger |
 |-------|---------|---------|
 | `skill/plan-with-pony/` | Draft plan + spec from "what's in your head" via conversation | `/plan-with-pony` |
 | `skill/review-pony/` | Review as verification, wired to fapony: scope facts before (`review-seed`), verdict after | `/review-pony` |
+| `skill/lookup-before-edit/` | Look up unfamiliar files (`review-seed --files` + mem + debt) before reading/editing them | `/lookup-before-edit` |
+| `skill/define-convention/` | Turn a not-yet-migrated pattern into a tracked convention (interview + dry-run `debt`) | `/define-convention` |
 | `skill/move-to-done/` | Archive a shipped PLAN into .fapony/done/ | `/move-to-done` |
 | `skill/git-commit-conventional/` | Commit split by concern + conventional message | `/git-commit` |
 | `skill/git-ship/` | Push branch, open PR with drafted title/body, merge, reset branch onto base | `/ship`, `/pr` |
@@ -363,7 +364,7 @@ plain `/git-ship` detects that and behaves like `pr` on its own.
 
 **What this is not.** It doesn't reduce your token bill — an agent that plans against known
 failure patterns tends to spend fewer rounds getting there, but fapony measures that, it doesn't
-cause it. Use `fapony_usage` to find out whether it actually happened for you rather than taking
+cause it. Use `fapony usage-web` to find out whether it actually happened for you rather than taking
 the claim on faith.
 
 `fapony install --platform claude` (or `opencode`) symlinks these directories into

package/fapony.ts

@@ -5,9 +5,14 @@
 
 import { existsSync } from "node:fs";
 import { cmdAnalyze } from "./src/analyze.js";
-import { cmdDebt } from "./src/debt.js";
+import { cmdDebt } from "./src/debt/cli.js";
 import { cmdDigest } from "./src/digest/cli.js";
-import { cmdHookEditHint, cmdHookReadHint, cmdHookStop } from "./src/hook.js";
+import {
+  cmdHookEditHint,
+  cmdHookReadHint,
+  cmdHookSessionStart,
+  cmdHookStop,
+} from "./src/hook.js";
 import { cmdInit } from "./src/init.js";
 import { cmdInitMem } from "./src/init-mem.js";
 import { cmdInstall } from "./src/install.js";
@@ -87,6 +92,8 @@ if (cmd === "analyze") {
   await cmdHookReadHint();
 } else if (cmd === "hook-edit-hint") {
   await cmdHookEditHint();
+} else if (cmd === "hook-session-start") {
+  await cmdHookSessionStart();
 } else if (cmd === "mcp") {
   cmdMcp();
 } else if (cmd === "report") {
@@ -108,7 +115,7 @@ if (cmd === "analyze") {
 } else {
   console.error(`fapony: unknown command "${cmd ?? ""}"`);
   console.error(
-    "usage: fapony <setup|update|stats|telemetry|init|init-mem|mem|install|report|report-web|usage-scan|usage-web|price-scan|analyze|debt|lint-baseline|plan-seed|review-seed|digest|mcp|hook-stop|hook-read-hint|hook-edit-hint|test> [args]",
+    "usage: fapony <setup|update|stats|telemetry|init|init-mem|mem|install|report|report-web|usage-scan|usage-web|price-scan|analyze|debt|lint-baseline|plan-seed|review-seed|digest|mcp|hook-stop|hook-read-hint|hook-edit-hint|hook-session-start|test> [args]",
   );
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.2.1",
+  "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",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",

package/skill/define-convention/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: define-convention
+description: Turn "files that haven't migrated yet" into a tracked convention — one question, a draft built from real examples, then dry-run fapony debt until the counts hold. Trigger on /define-convention and when the user wants migration tracking or fapony debt shows declared rows with no regex.
+---
+
+# Define Convention — from pain to a counted migration
+
+One convention = the pattern to use (`ok`) + the pattern meaning not-yet-migrated
+(`stale`) + scope (`where`) + an optional file condition (`guard`). The output is
+one row in `<worktree>/.fapony/conventions.json` (`{"conventions": [...]}`), in the
+same `.fapony/` dir as the mem log — run `fapony mem where`, go up one level, that
+is where the file lives (app-scoped in a monorepo). No file there yet = create it;
+a file with rows = append only, never rewrite other rows.
+
+## Phase 1 — One question, then the checker question
+
+Ask this, and nothing else:
+
+> "What should stop appearing, and what does the migrated code look like? Which
+> directory is it in?"
+
+Then the iron-rule question (one line, always asked — a convention eslint already
+flags is one fapony must stay silent on):
+
+> "Does an eslint rule or script already flag the old pattern? If yes, name it —
+> fapony will record it as `checker` and never report this debt."
+
+## Phase 2 — Real examples before regex
+
+Never invent the regex from prose — regex from prose is how entries get dropped.
+`grep` the `where` dir for 2–3 hits of the old pattern and 1–2 of the new one. No
+hits on either side = stop and say so; there is no migration to track yet, only
+an opinion.
+
+## Phase 3 — Draft the row, show it, append it
+
+```json
+{"id": "raw-throw", "rule": "throw failWith, not raw Error",
+ "where": "src", "stale": "throw new Error", "ok": "failWith"}
+```
+
+- `id` short, kebab; `rule` one human line; `where` a repo-relative dir that
+  exists (`"."` = whole repo).
+- `guard` only when `stale` alone is too broad (the file must ALSO match, e.g.
+  `"extends Base"`).
+- `checker` set from Phase 1 = silent by design; verify it with eslint, not fapony.
+- `stale: null` ships a `declared` placeholder — fill it or delete it, never keep it.
+- The shown draft is the confirmation (rule 6c). Append, don't rewrite.
+
+## Phase 4 — Dry-run until the counts hold
+
+```bash
+fapony debt --id <new-id>
+```
+
+Read it literally — every outcome names its fix:
+
+- `debt N · moved M` with N > 0 → the convention now counts. Report id, N, moved%
+  back in chat.
+- `debt 0 · moved M — clean` → the migration is already done; nothing left to
+  track. Report it and change nothing.
+- `debt 0` with no moved → `stale` matches nothing you care about; widen it or
+  fix `where`.
+- `⚠ <id>: ... too broad` → narrow `stale`, shrink `where`, or add `guard` (the
+  match was capped past 250 files, so the entry was dropped).
+- `⚠ <id>: stale regex broken` / `where: <dir> does not exist` → fix syntax / path.
+- A row prints `declared, no checker, stale not filled in` → `stale` is null; see
+  Phase 3.
+- `0 convention(s)` after `--id` → that id does not exist (misspelling — a dropped
+  row still prints its `⚠`). Only `no conventions.json in <dir>` means you wrote
+  to the wrong `.fapony/` (re-check `mem where`).
+
+## Later
+
+A convention whose fix recurs ≥3 times makes `fapony debt` ask "time for a
+checker?" — that promotion answers to a human, never to this skill. `no-checker`
+means "never ask again": say it only deliberately.

package/skill/lookup-before-edit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lookup-before-edit
+description: Look up unfamiliar files before reading or editing them — exports, line numbers, and importers without reading the whole file. Trigger on /lookup-before-edit and proactively whenever you are about to read, edit, or refactor a file you do not already know.
+---
+
+# Lookup Before Edit — scope first, read second
+
+You are about to touch files you do not know. Do not `Read` them whole — look them up first.
+A full-file read on a 500-line module costs ~35k tokens of output; a lookup costs under 1k.
+
+## The one command
+
+```bash
+fapony review-seed --files <f1,f2,dir> [--body <sym>] [--callers <sym>]
+```
+
+What it returns: every export with its line number (uncapped), plus the importers — first 12
+per file, the rest as `(+N)`, so the total is still readable. That is your entry map — then
+`Read` only the line ranges you actually need.
+
+## Narrow it
+
+- `--body <sym>[,<sym>]` — declaration slice of those exports (truncated at 80 lines each):
+  "what does this do" without the file.
+- `--callers <sym>` — symbol→symbol scan across the importers the static graph sees.
+- Directories expand to the source files under them (cap 40, stated when cut). Paths that do
+  not exist are dropped with a notice, not counted silently.
+
+## Limits (do not work around them)
+
+- **Exports only.** A non-exported function answers "no export named X in scope" — that is
+  the correct answer, not a failure. Read the file for internals.
+- **Static only.** Dynamic use is invisible to the graph; an empty caller list means "not
+  seen statically", never "unused".
+- **120 lines total.** Past that the tail is cut (`… (+N lines truncated)`) — and the tail is
+  the later files' signatures. Many files at once → split the call, don't trust a cut list.
+- No `fapony` CLI or the call errors → read the file normally and carry on. A hint, not a gate.
+
+## History + debt (same paths, two calls)
+
+- `mem_find` with `files: [<same paths>]` — "what was ever decided about this file" (MCP, no CLI spawn).
+- `fapony debt --where <dir|file>` — conventions this path still violates; empty until `conventions.json` exists.
+
+## After the lookup
+
+1. Pick line ranges from the export list, `Read` those slices only.
+2. Before changing a shape, sum shown + `(+N)` importers — that is your blast radius.
+3. Do not re-read a file whose mtime has not moved; `grep` it instead.

package/skill/review-pony/SKILL.md

@@ -117,10 +117,15 @@ them is how a review launders an assumption into a fact.
 
 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.**
+**Verdict first, then at most 10 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.
 
+**A capped report must not read as a complete one.** When more findings survived pass 3 than
+the cap allows, the report ends with one line naming how many were held back and the worst
+severity among them (`+ 4 more (major) — ask`) — never a silent stop at 10. A reader who
+cannot tell "that's all" from "that's the cap" has been told a lie by omission.
+
 ```
 <ship | fix-then-ship | rework | reject> — the single biggest reason, one sentence.
 
@@ -130,6 +135,7 @@ survived — they dilute the only thing worth reading.
    fix: <the minimal change>
 
 deferred: <thing> (<where it was specified>) · <thing>
++ <N> more (<worst severity>)   ← required only when findings exceeded the cap
 ```
 
 Four lines is a ceiling, not a quota — a finding that fits in two ships in two. Drop `repro:`
@@ -214,9 +220,11 @@ 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
+- **The budget is binding.** Verdict, ≤10 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.
+  verdict line plus one line naming what you walked. When the cap bites, say how much it bit:
+  a `+ N more (<severity>)` line is required — a silent stop at 10 is the same lie as a silent
+  stop at 3.
 - **Forget who wrote it.** The author's reasoning is context, never evidence.
 
 ## Example

package/src/debt/cli.ts

@@ -0,0 +1,193 @@
+// src/debt/cli.ts — `fapony debt` CLI: arg parsing + worktree resolution.
+//
+// Read-only stdout: no file writes, no state.db, no cache (rule 5b).
+
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { CONVENTIONS_FILE } from "../db/defaults.js";
+import { formatDebt } from "./format.js";
+import { loadConventions } from "./load.js";
+import { findPromotions, formatPromotions } from "./promotion.js";
+import { debtForFile, debtScan } from "./scan.js";
+import { ZONE_CAP } from "./types.js";
+
+const USAGE = `usage: fapony debt [path] [options]
+  --files f1,f2     check specific files instead of scanning
+  --id <conv>       show only this convention
+  --where <path>    narrow scope to files under this path
+  --all             show all zones (default: cap at ${ZONE_CAP})
+  --json            output raw JSON
+  -h, --help        this help`;
+
+/**
+ * The dir `debt` measures: the nearest ancestor of `arg` (or cwd) that holds
+ * `.fapony/conventions.json`, bounded by the git root.
+ *
+ * Jumping straight to the git root was the bug: in a monorepo the root has no
+ * conventions.json and two apps have one each, so the mem resolver went
+ * ambiguous and `debt` said "nothing tracked yet" while
+ * apps/<x>/.fapony/conventions.json sat right there — and the positional path
+ * argument was silently ignored. Falling back to the git root keeps single
+ * repos run from a subdir scanning the whole repo.
+ */
+export function worktreeOf(arg: string | undefined): string {
+  const base = resolve(arg ?? ".");
+  let gitRoot: string | null = null;
+  try {
+    const p = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+      cwd: base,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (p.exitCode === 0) gitRoot = p.stdout.toString().trim() || null;
+  } catch {
+    // not a repo — base is all we have
+  }
+  // `git rev-parse` returns a physical path (/var → /private/var on macOS),
+  // so the boundary check compares realpaths, same as the mem resolver.
+  const real = (d: string): string => {
+    try {
+      return realpathSync(d);
+    } catch {
+      return d;
+    }
+  };
+  const boundary = gitRoot ? real(gitRoot) : null;
+  let dir = base;
+  while (true) {
+    if (existsSync(join(dir, CONVENTIONS_FILE))) return dir;
+    if (boundary && real(dir) === boundary) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return gitRoot ?? base;
+}
+
+export function cmdDebt(args: string[]): void {
+  let path: string | undefined;
+  let filesMode: string[] | null = null;
+  let json = false;
+  let filterId: string | undefined;
+  let wherePath: string | undefined;
+  let showAll = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--files") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony debt: --files needs a value\n${USAGE}`);
+        process.exit(1);
+      }
+      i++;
+      filesMode = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (filesMode.length === 0) {
+        console.error(`fapony debt: --files needs at least one path\n${USAGE}`);
+        process.exit(1);
+      }
+    } else if (a === "--id") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony debt: --id needs a convention id\n${USAGE}`);
+        process.exit(1);
+      }
+      i++;
+      filterId = v;
+    } else if (a === "--where") {
+      const v = args[i + 1];
+      if (!v || v.startsWith("--")) {
+        console.error(`fapony debt: --where needs a path\n${USAGE}`);
+        process.exit(1);
+      }
+      i++;
+      wherePath = v;
+    } else if (a === "--all") {
+      showAll = true;
+    } else if (a === "--json") {
+      json = true;
+    } else if (a === "-h" || a === "--help") {
+      console.log(USAGE);
+      return;
+    } else if (!a.startsWith("--")) {
+      path = a;
+    } else {
+      console.error(`fapony debt: unknown argument "${a}"\n${USAGE}`);
+      process.exit(1);
+    }
+  }
+
+  const worktree = worktreeOf(path);
+  const loaded = loadConventions(worktree);
+
+  if (filesMode) {
+    const out = filesMode.map((f) => {
+      const abs = isAbsolute(f) ? f : resolve(worktree, f);
+      if (!existsSync(abs) || !statSync(abs).isFile()) {
+        return { file: f, debt: [], note: "not found" as const };
+      }
+      return { file: f, debt: debtForFile(worktree, abs, loaded) };
+    });
+    if (json) {
+      console.log(JSON.stringify({ worktree, files: out }, null, 2));
+      return;
+    }
+    let any = false;
+    for (const r of out) {
+      for (const c of r.debt) {
+        any = true;
+        console.log(`${r.file} — ${c.id}: ${c.rule}`);
+      }
+      if ("note" in r) console.log(`${r.file} — ${r.note}`);
+    }
+    if (!any && out.every((r) => r.debt.length === 0)) {
+      console.log("no convention debt in the given file(s)");
+    }
+    return;
+  }
+
+  if (loaded.path === null) {
+    // SPEC §6: no conventions.json = completely silent, no error, no prompt to create one
+    console.log(
+      `fapony debt — no conventions.json in ${worktree} (nothing tracked yet)`,
+    );
+    return;
+  }
+  const report = debtScan(worktree, loaded);
+
+  // --id filter: keep only the named convention
+  if (filterId) {
+    report.entries = report.entries.filter((e) => e.conv.id === filterId);
+    report.declared = report.declared.filter((c) => c.id === filterId);
+    report.checkedCount = 0; // not relevant when filtering
+    report.dropped = report.dropped.filter((d) => d.id === filterId);
+  }
+
+  // --where filter: narrow file lists to paths under the given prefix
+  if (wherePath) {
+    const prefix = wherePath.replace(/\/+$/, "");
+    for (const e of report.entries) {
+      e.files = e.files.filter(
+        (f) => f === prefix || f.startsWith(`${prefix}/`),
+      );
+    }
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { ...report, promotions: findPromotions(worktree, report) },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+  console.log(formatDebt(report, showAll));
+  for (const w of loaded.warnings) console.log(`⚠ ${w}`);
+  for (const l of formatPromotions(findPromotions(worktree, report))) {
+    console.log(l);
+  }
+}

package/src/debt/format.ts

@@ -0,0 +1,107 @@
+// src/debt/format.ts — report rendering: zone grouping + text output.
+
+import { dirname } from "node:path";
+import { type DebtReport, ZONE_CAP, ZONE_DEPTH } from "./types.js";
+
+/** The zone of a file: its directory path, capped at `depth` segments. */
+function zoneOf(file: string, depth: number): string {
+  const parts = dirname(file)
+    .split("/")
+    .filter((p) => p && p !== ".");
+  return parts.slice(0, depth).join("/") || ".";
+}
+
+/** Group files by their directory zone (see `zoneOf`). */
+function groupFilesByZone(
+  files: string[],
+  depth: number,
+): Map<string, string[]> {
+  const zones = new Map<string, string[]>();
+  for (const f of files) {
+    const zone = zoneOf(f, depth);
+    const cur = zones.get(zone) ?? [];
+    cur.push(f);
+    zones.set(zone, cur);
+  }
+  // Sort zones by file count descending, then alphabetically
+  return new Map(
+    [...zones.entries()].sort((a, b) => {
+      const d = b[1].length - a[1].length;
+      return d !== 0 ? d : a[0].localeCompare(b[0]);
+    }),
+  );
+}
+
+/** Escape a regex source for use in a shell grep command. */
+function shellEscapeRe(src: string): string {
+  return src.replace(/'/g, "'\\''");
+}
+
+export function formatDebt(report: DebtReport, showAll = false): string {
+  const lines: string[] = [];
+  lines.push(
+    `fapony debt — ${report.entries.length + report.declared.length + report.checkedCount} convention(s), ` +
+      `${report.scannedFiles} files scanned, ${report.ms}ms — derived fresh, not stored`,
+  );
+  for (const e of report.entries) {
+    const moved =
+      e.movedCount !== null && e.files.length > 0
+        ? ` · moved ${e.movedCount} (${Math.round((e.movedCount / (e.files.length + e.movedCount)) * 100)}%)`
+        : e.movedCount !== null
+          ? ` · moved ${e.movedCount}`
+          : "";
+    lines.push(`\n${e.conv.id} — ${e.conv.rule}`);
+    // Show the patterns actually used
+    const patterns: string[] = [];
+    if (e.conv.stale) patterns.push(`stale: ${e.conv.stale}`);
+    if (e.conv.ok) patterns.push(`ok: ${e.conv.ok}`);
+    if (e.conv.guard) patterns.push(`guard: ${e.conv.guard}`);
+    patterns.push(`where ${e.conv.where}`);
+    lines.push(`  ${patterns.join("  ·  ")}`);
+    if (e.files.length === 0) {
+      lines.push(`  debt 0${moved} — clean`);
+      continue;
+    }
+    lines.push(`  debt ${e.files.length}${moved}`);
+    // Verify command derived from stale
+    if (e.conv.stale) {
+      lines.push(`  verify: grep -rn '${shellEscapeRe(e.conv.stale)}' <zone>`);
+    }
+    // Zone grouping
+    const zones = groupFilesByZone(e.files, ZONE_DEPTH);
+    const zoneEntries = [...zones.entries()];
+    const cap = showAll
+      ? zoneEntries.length
+      : Math.min(zoneEntries.length, ZONE_CAP);
+    let totalCapped = 0;
+    for (let i = 0; i < cap; i++) {
+      const [zone, zoneFiles] = zoneEntries[i];
+      const pad = " ".repeat(Math.max(0, 42 - zone.length));
+      lines.push(`\n  ${zone}${pad}${zoneFiles.length} ไฟล์`);
+      lines.push(`    ${zoneFiles.map((f) => f.split("/").pop()).join(" · ")}`);
+      totalCapped += zoneFiles.length;
+    }
+    if (zoneEntries.length > cap) {
+      const remaining = e.files.length - totalCapped;
+      const remainingZones = zoneEntries.length - cap;
+      lines.push(
+        `\n  … อีก ${remainingZones} โซน (${remaining} ไฟล์) — fapony debt --id ${e.conv.id} --all`,
+      );
+    }
+  }
+  for (const c of report.declared) {
+    lines.push(`\n${c.id} — ${c.rule} (where ${c.where})`);
+    lines.push(
+      `  declared, no checker, stale not filled in — fill "stale" in conventions.json`,
+    );
+  }
+  if (report.checkedCount > 0) {
+    lines.push(
+      `\n${report.checkedCount} convention(s) have a checker — fapony stays silent, the checker reports`,
+    );
+  }
+  for (const d of report.dropped) {
+    lines.push(`⚠ ${d.id}: ${d.reason}`);
+  }
+  return lines.join("\n");
+}

package/src/debt/index.ts

@@ -0,0 +1,19 @@
+// src/debt/index.ts — barrel for `fapony debt`: which files have not moved
+// to a shipped convention yet.
+//
+// The question nobody can answer: "which files have not moved" — rules files
+// (CLAUDE.md, Cursor rules) can only say "what the rule is" (layer 2) and
+// "which files were copied" (layer 1) — where the debt is (layer 3) lives in
+// the owner's head and vanishes when forgotten (SPEC-convention-debt §1)
+//
+// The convention definition lives in the measured repo — fapony does not know
+// React or Hono and must not. Layout mirrors src/mcp/: types + one file per
+// concern, CLI entry in cli.ts (fapony.ts imports that directly, same as
+// digest/cli.ts).
+
+export * from "./cli.js";
+export * from "./format.js";
+export * from "./load.js";
+export * from "./promotion.js";
+export * from "./scan.js";
+export * from "./types.js";