fapony 0.2.1 → 0.3.3

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

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

package/skill/review-pony/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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 surviving findings to the project's mem log 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
@@ -83,10 +83,10 @@ Write down every place the walk surprises you. Surprises outrank style; chase th
 - `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.
+- `max` — also grep every changed file for second-degree callers, 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"
+Whatever level stopped you, say so in the one-line coverage note (see Report) — "walked to 1 hop"
 is honest, "walked" alone at `low` is not.
 
 ## Pass 3 — A finding needs a failing input
@@ -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:`
@@ -155,56 +161,25 @@ 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.
+check on the new state before calling it done, but don't re-run the whole review. Record
+what you found, not the post-fix state (the row's text can say the fix was applied).
+
+## After: record what the next session needs (fapony)
+
+If a blocker/major CONFIRMED finding survived, or the verdict is rework/reject,
+call `mem_add` once, after the report is shown. Don't block the report on it,
+and don't let it change the report's content. Clean reviews (ship, nit-only
+findings) record nothing — there is nothing the next session needs to find.
+
+kind is `bug` when a finding survived (something is broken), `decision` when
+the verdict turns on scope alone (rework/reject from pass 1 — the review locks
+a direction). text is the report's verdict line, standalone — what broke or was
+decided, not that a review happened. files are the repo-relative paths actually
+walked — required, a row without them is unfindable. worktree is the absolute
+path (`git rev-parse --show-toplevel`), never a bare name. Only record into a
+project that already has a mem log — never create one uninvited.
+If `mem_add` errors, say so in one line and move on — never re-run a review
+because storage failed.
 
 ---
 
@@ -214,9 +189,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
@@ -224,10 +201,10 @@ The four passes are the rules. These three are what they fail on in practice:
 ```
 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")
+post. mem_add(kind="bug",
+        text="incremental scan replaces cached history with a delta — cache holds 500, truth 1500",
+        files=["cache.ts", "claude-code.ts"],
+        worktree="/Users/you/Project/fapony/wt-fapony")
 ```
 
 A report in budget — same review that, narrated, ran five paragraphs:

package/src/analyze.ts

@@ -147,7 +147,7 @@ export const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx"]);
 // 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(").
+// named calls elsewhere in the repo, e.g. "cmdDone() instead of done(").
 const SKIP_DIRS = new Set([
   "node_modules",
   "dist",

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";

package/src/debt/load.ts

@@ -0,0 +1,92 @@
+// src/debt/load.ts — conventions.json resolution + parsing.
+//
+// The convention definition lives in the measured repo
+// (<repo>/.fapony/conventions.json — via the same resolver as the mem log).
+// Missing file = empty + no error.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  CONVENTIONS_FILE,
+  CONVENTIONS_FILENAME,
+  FAPONY_DIR,
+} from "../db/defaults.js";
+import { resolveMemDir } from "../memory.js";
+import type { Convention, LoadedConventions } from "./types.js";
+
+export function resolveConventionsPath(worktree: string): string | null {
+  // Conventions live in the same .fapony/ dir as the mem log — derive from
+  // the resolved mem dir so both resolvers cannot drift apart.
+  const memDir = resolveMemDir(worktree);
+  const base = memDir ? join(memDir, "..") : join(worktree, FAPONY_DIR);
+  const app = join(base, CONVENTIONS_FILENAME);
+  if (existsSync(app)) return app;
+  // Monorepo where the app has not scaffolded .fapony/ yet, and single repos
+  // that ran `fapony init` at the root — the root file still scopes fine
+  // because every `where` is repo-relative.
+  const root = join(worktree, CONVENTIONS_FILE);
+  return existsSync(root) ? root : null;
+}
+
+function asString(v: unknown): string | undefined {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+/** Parses .fapony/conventions.json. Missing file = empty + no error (SPEC §6). */
+export function loadConventions(worktree: string): LoadedConventions {
+  const path = resolveConventionsPath(worktree);
+  if (!path) return { path: null, convs: [], warnings: [] };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return {
+      path,
+      convs: [],
+      warnings: [`conventions.json unreadable: ${path}`],
+    };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      path,
+      convs: [],
+      warnings: [
+        `conventions.json is not valid JSON — ${
+          e instanceof Error ? e.message.split("\n")[0] : "parse error"
+        }`,
+      ],
+    };
+  }
+  const rows: unknown[] = Array.isArray(parsed)
+    ? parsed
+    : Array.isArray((parsed as { conventions?: unknown }).conventions)
+      ? (parsed as { conventions: unknown[] }).conventions
+      : [];
+  const convs: Convention[] = [];
+  const warnings: string[] = [];
+  rows.forEach((r, i) => {
+    const o = r as Record<string, unknown>;
+    const id = asString(o.id);
+    const rule = asString(o.rule);
+    if (!id || !rule) {
+      warnings.push(
+        `conventions[${i}]: id and rule are required — row dropped`,
+      );
+      return;
+    }
+    convs.push({
+      id,
+      rule,
+      where: asString(o.where) ?? ".",
+      stale: asString(o.stale) ?? null,
+      ok: asString(o.ok),
+      guard: asString(o.guard),
+      checker: asString(o.checker) ?? null,
+      decided: o.decided === "no-checker" ? "no-checker" : null,
+    });
+  });
+  return { path, convs, warnings };
+}