fapony 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Measurement layer for coding agents — measure what agents do, verify what they claim. 6 MCP tools, any agent, no loop required",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",
@@ -26,17 +26,18 @@
     "templates/",
     "skill/"
   ],
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.12",
-    "bun-types": "^1.4.0",
-    "typescript": "^5.9.3"
-  },
   "scripts": {
     "lint": "biome check .",
     "typecheck": "tsc --noEmit",
     "test": "bun fapony.ts test",
     "test:fast": "SKIP_SLOW=1 bun fapony.ts test",
     "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"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "bun-types": "^1.4.0",
+    "typescript": "^5.9.3"
   }
-}
+}

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

@@ -102,7 +102,7 @@ the real scope instead.
 So the seed buys you structure; the draft budget goes on judgment:
 
 - **Read the Context block, then skip to filling** — everything else is the empty template.
-- **Fill every section yourself** — §1–§6 and the TL;DR start as `_agent เติม_` slots.
+- **Fill every section yourself** — §1–§6 and the TL;DR start as `_agent fills in_` slots.
 - **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.

package/src/analyze.ts

@@ -376,7 +376,7 @@ export function diagnose(
     findings.push({
       kind: "cycle",
       file: cycle.join(" ↔ "),
-      detail: "import วนกลับหากัน — refactor ฝั่งไหนก่อนก็พังอีกฝั่ง",
+      detail: "circular imports — refactoring either side breaks the other",
       evidence: [...cycle, cycle[0]].join(" → "),
     });
   }
@@ -389,7 +389,8 @@ export function diagnose(
         findings.push({
           kind: "orphan",
           file: f,
-          detail: "ไม่มีใคร import และไม่ใช่ entry point — dead code candidate",
+          detail:
+            "no one imports it and it is not an entry point — dead code candidate",
           evidence: "0 dependents",
         });
       }
@@ -405,8 +406,8 @@ export function diagnose(
     findings.push({
       kind: "hub-untested",
       file,
-      detail: `${n} ไฟล์พึ่งอยู่ ไม่มีเทสไหน import มันเลย — แก้ตรงนี้ไม่มีอะไรจับตอนพัง`,
-      evidence: `พึ่งอยู่: ${shown}${rest}`,
+      detail: `${n} files depend on it; no test imports it — edit here and nothing catches the break`,
+      evidence: `dependents: ${shown}${rest}`,
     });
   }
 
@@ -417,10 +418,10 @@ export function diagnose(
       findings.push({
         kind: "changed-untested",
         file: c,
-        detail: `เพิ่งแก้แต่ไม่มีเทสไหนพึ่งอยู่ (${deps.size} dependent) — พังแล้วไม่มีอะไรจับ`,
+        detail: `recently changed but no test depends on it (${deps.size} dependent) — nothing catches it if it breaks`,
         evidence:
           deps.size > 0
-            ? `พึ่งอยู่: ${[...deps].sort().join(", ")}`
+            ? `dependents: ${[...deps].sort().join(", ")}`
             : "0 dependents",
       });
     }
@@ -475,7 +476,7 @@ export function formatAnalyze(graph: ImportGraph, findings: Finding[]): string {
   lines.push("");
 
   if (findings.length === 0) {
-    lines.push("no findings — โครงสร้างไม่มีอะไรน่าห่วง");
+    lines.push("no findings — structure looks healthy");
   } else {
     for (const f of findings.slice(0, 5)) {
       const icon = f.kind === "orphan" ? "·" : "⚠";
@@ -488,7 +489,7 @@ export function formatAnalyze(graph: ImportGraph, findings: Finding[]): string {
     if (rest > 0) lines.push(`… and ${rest} more`);
     lines.push(
       graph.unresolved > 0
-        ? `${findings.length} findings. ${graph.unresolved} unresolved imports (path alias / package name) — ตัวเลข dependent อาจต่ำกว่าจริง`
+        ? `${findings.length} findings. ${graph.unresolved} unresolved imports (path alias / package name) — dependent counts may be lower than reality`
         : `${findings.length} findings.`,
     );
   }

package/src/conventions-seed.ts

@@ -1,15 +1,15 @@
 // src/conventions-seed.ts — `fapony init` fill-signal (PLAN-convention-debt chunk 2).
 //
-// คำถาม: "การ fill signal ตอน init ทำได้แค่ไหน" (SPEC-convention-debt §2.2) —
-// วัดสองรอบ คำตอบรอบแรกผิด: eslint คือของที่ทีมส่วนใหญ่ปล่อย default ตอนติดตั้ง,
-// pair-mining พังกับ commit ก้อนใหญ่และ cap ผ่อนไม่ได้ (วัดแล้ว) — ของที่**ทุกรีโปมี**
-// คือโค้ดตัวเอง ฐานจึงเป็น wrapper detector (อ่าน snapshot อย่างเดียว ไม่แตะ history),
-// eslint เป็น bonus เมื่อมี, pair-mining ยังไม่ทำ (chunk 7 วัด precision ก่อน)
+// Question: "how far can signal-filling at init go" (SPEC-convention-debt §2.2) —
+// Measured twice; the first answer was wrong: eslint is what most teams leave at default on install,
+// pair-mining breaks on large commits and the cap cannot be relaxed (measured) — what **every repo has**
+// is its own code, so the base is a wrapper detector (reads the snapshot only, never touches history),
+// eslint is a bonus when present, pair-mining is not done yet (chunk 7 measures precision first)
 //
-// เขียนได้ที่เดียว: <target>/.fapony/conventions.json — นิยาม convention อยู่ในรีโปที่
-// ถูกวัด (SPEC §2.1), commit ได้เพราะทุก field เป็น repo-relative · มีอยู่แล้ว = ไม่แตะ
-// (rule 5c) · fapony ไม่เดา convention ที่ไม่มีร่องรอย — อันที่ยังไม่เคย migrate และ
-// ไม่มี wrapper ไม่มีร่องรอยทั้งใน snapshot และ history ช่องนั้นเหลือให้คนเติม (stale)
+// Written to one place: <target>/.fapony/conventions.json — the convention definition lives in the repo being
+// measured (SPEC §2.1), committable because every field is repo-relative · already exists = leave untouched
+// (rule 5c) · fapony does not guess a convention with no trace — one never migrated and
+// with no wrapper has no trace in either snapshot or history, that slot is left for a human to fill (stale)
 
 import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
@@ -108,7 +108,7 @@ function rowsFromBlock(block: Block, whereBase: string): SeedRow[] {
     whereGlob && whereGlob !== "." ? `${dir}${whereGlob}` : whereBase || ".";
   const push = (message: unknown, stale: string | null, ruleId: string) => {
     const text = flatText(message);
-    if (!text) return; // checker โดยไม่มีข้อความ = ไม่รู้ว่ากฎคืออะไร
+    if (!text) return; // a checker without a message = the rule is unknown
     out.push({ id: "", rule: text, where, stale, checker: ruleId });
   };
   for (const [ruleId, value] of Object.entries(block.rules ?? {})) {

package/src/db/index.ts

@@ -1,4 +1,4 @@
-// barrel — re-export ทุกอย่างจาก db/* ให้ import เดิมจาก "./db/index.js" ใช้ได้
+// barrel — re-export everything from db/* so existing imports from "./db/index.js" keep working
 
 export * from "./defaults.js";
 export * from "./getters.js";

package/src/db/store.ts

@@ -80,7 +80,11 @@ export function openDb(config?: Config): Database {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
   const db = new Database(`${dir}/state.db`);
+  // bun default busy_timeout=0 = no retry on SQLITE_BUSY; multiple agent
+  // processes share this db, so concurrent writers throw immediately without this.
+  db.run("PRAGMA busy_timeout=5000");
   db.run("PRAGMA journal_mode=WAL");
+  db.run("PRAGMA synchronous=NORMAL");
 
   migrateDb(db);
 

package/src/debt.ts

@@ -1,18 +1,20 @@
 // src/debt.ts — `fapony debt`: which files have not moved to a shipped convention yet.
 //
-// คำถามที่ไม่มีใครตอบได้: "ไฟล์ไหนยังไม่ย้าย" — rules files (CLAUDE.md, Cursor rules)
-// บอกได้แค่ว่า "กฎคืออะไร" (ชั้น 2) และ "ก๊อปไฟล์ไหน" (ชั้น 1) — ตำแหน่งของหนี้
-// (ชั้น 3) อยู่ในหัวเจ้าของ และหายเมื่อลืม (SPEC-convention-debt §1)
+// 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)
 //
-// นิยามของ convention อยู่ในรีโปที่ถูกวัด (<repo>/.fapony/conventions.json — ผ่าน
-// resolver เดียวกับ mem log, SPEC §2.1) — fapony ไม่รู้จัก React หรือ Hono และ
-// ต้องไม่รู้จัก · หนึ่ง convention = pattern ที่ควรใช้ (ok) + pattern ที่แปลว่า
-// ยังไม่ย้าย (stale) + ขอบเขต (where) + เงื่อนไขของไฟล์ (guard, เช่น extends Base)
+// The convention definition lives in the measured repo (<repo>/.fapony/conventions.json
+// — via the same resolver as the mem log, SPEC §2.1) — fapony does not know React
+// or Hono and must not · one convention = pattern to use (ok) + pattern meaning
+// not-yet-migrated (stale) + scope (where) + file condition (guard, e.g. extends Base)
 //
-// หนี้ถูกคำนวณสดทุกครั้ง ไม่เขียนลงที่ใดเลย (แบบเดียวกับ analyze: cache คือหนี้ล้วน —
-// ลิสต์ที่ freeze ไว้ตกรุ่นเงียบ ๆ เหมือน MASTER.md) · กฎเหล็ก: checker ไม่ null =
-// fapony ไม่รายงานหนี้ข้อนั้น — การรายงานซ้ำกับ eslint คือ abstraction ที่มี
-// implementation เดียว (กฎ 1) และสอนให้ agent ข้ามทั้งคู่ (SPEC §2)
+// Debt is computed live every time, never written anywhere (same as analyze:
+// a cache is pure debt — a frozen list goes stale silently like MASTER.md) ·
+// Iron rule: checker not null = fapony does not report that debt item — reporting
+// twice with eslint is an abstraction with one implementation (rule 1) and
+// teaches the agent to skip both (SPEC §2)
 //
 // Read-only stdout: no file writes, no state.db, no cache (rule 5b).
 
@@ -242,12 +244,12 @@ export function debtScan(
   const compiled: Compiled[] = [];
   for (const conv of loaded.convs) {
     if (conv.checker) {
-      // กฎเหล็ก — fapony เงียบ ปล่อยให้ checker ทำงาน (SPEC §2)
+      // Iron rule — fapony stays silent, leave it to the checker (SPEC §2)
       checkedCount++;
       continue;
     }
     if (!conv.stale) {
-      // ช่องเดียวที่คนเติม (SPEC §2.2) — โชว์ว่าค้าง ไม่เดาแทน
+      // The one slot a human fills (SPEC §2.2) — show it as pending, don't guess
       declared.push(conv);
       continue;
     }
@@ -352,16 +354,18 @@ export function debtForFile(
   return out;
 }
 
-// --- Promotion signal (chunk 5) — "เรื่องนี้ซ้ำครั้งที่ N แล้ว ทำ checker ไหม" ---
+// --- Promotion signal (chunk 5) — "this recurred N times, time for a checker?" ---
 //
-// "ผมจะทำ eslint ตอนที่คิดได้" — จังหวะ "คิดได้" คือสิ่งที่หายไป (SPEC §3) fapony
-// เห็นประวัติข้าม session (mem + verdicts) จึงนับได้ว่าเรื่องเดียวกันถูกแก้ซ้ำกี่ครั้ง
-// แล้วยื่นคำถามให้คนตัดสิน — ไม่ตัดสินเอง ไม่เขียน eslint rule เอง (SPEC §6 fail list)
+// "I'll write eslint when I think of it" — the "think of it" moment is what goes
+// missing (SPEC §3) · fapony sees history across sessions (mem + verdicts), so it
+// can count how often the same thing was fixed, then put the question to a human —
+// it does not decide, does not write the eslint rule itself (SPEC §6 fail list)
 //
-// การ match "เรื่องเดียวกัน" — แม่นยำเท่าที่ข้อมูลให้ (SPEC §7: แถวเก่าไม่มี files[]
-// ยังไม่ตัดสิน): แถวที่มี files[] ต้อง intersect กับ debt list · ข้อความต้องเอ่ยถึง
-// สัญลักษณ์ของ convention (ok เช่น fmtMoney, หรือ identifier ≥ 6 ตัวจาก stale เช่น
-// toLocaleString/useMutation — "throw"/"Error" สั้นเกินจึงไม่นับ กัน over-match)
+// Matching "the same thing" — only as precise as the data allows (SPEC §7: old rows
+// lack files[], still undecided): a row with files[] must intersect the debt list ·
+// the text must mention a convention symbol (ok such as fmtMoney, or an identifier
+// ≥ 6 chars from stale such as toLocaleString/useMutation — "throw"/"Error" are too
+// short and don't count, to avoid over-matching)
 
 export const PROMOTION_THRESHOLD = 3;
 const PROMOTION_MAX = 3;
@@ -642,7 +646,7 @@ export function cmdDebt(args: string[]): void {
   }
 
   if (loaded.path === null) {
-    // SPEC §6: ไม่มี conventions.json = เงียบสนิท ไม่ error ไม่ชวนสร้าง
+    // 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)`,
     );

package/src/digest/collect.ts

@@ -1,6 +1,6 @@
-// src/digest/collect.ts — รวมข้อมูลจาก 4 แหล่งเป็น DigestData ก้อนเดียว
+// src/digest/collect.ts — merge data from 4 sources into a single DigestData
 //
-// ไม่ render อะไรเลย — แค่อ่าน + จัดรูป struct
+// Renders nothing — just reads + shapes into structs
 
 import { execSync } from "node:child_process";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
@@ -144,7 +144,7 @@ function parseFrontmatter(text: string): { status?: string; kind?: string } {
 }
 
 function countCheckboxes(text: string): { done: number; total: number } {
-  // นับ checkbox ใน section ## แรกเท่านั้น (same logic as plans.ts)
+  // Count checkboxes in the first ## section only (same logic as plans.ts)
   const body = text.replace(/^---\r?\n[\s\S]*?\r?\n---/, "");
   const start = body.search(/^##\s+/m);
   if (start < 0) return { done: 0, total: 0 };
@@ -216,7 +216,7 @@ function readUsageAndCost(_worktree: string): {
   detail: string;
 } {
   const cache = readCache();
-  // หา global entry (worktree=null) หรือรวมทุก entry
+  // Find a global entry (worktree=null), otherwise merge every entry
   const globalEntries = cache.filter((e) => !e.worktree);
   if (globalEntries.length === 0 && cache.length === 0) {
     return {
@@ -232,11 +232,11 @@ function readUsageAndCost(_worktree: string): {
     };
   }
 
-  // ใช้ global entries ถ้ามี ไม่งั้นรวมทุก entry
+  // Use global entries if present, otherwise merge every entry
   const entries = globalEntries.length > 0 ? globalEntries : cache;
   const usage = entriesToUsage(entries);
 
-  // คำนวณราคา
+  // Compute the price
   const prices = loadPrices();
   if (!prices) {
     return {
@@ -271,7 +271,7 @@ function readUsageAndCost(_worktree: string): {
     imputed: m.imputed_cost,
   }));
 
-  // เพิ่ม cost จริงจาก cache
+  // Attach the real cost from the cache
   const cacheByKey = new Map(
     entries.flatMap((e) =>
       e.by_model.map((m) => [`${m.provider}\0${m.model}`, m]),

package/src/digest/html.ts

@@ -1,7 +1,7 @@
 // src/digest/html.ts — render digest as a single HTML page
 //
-// คอลัมน์เดียว max-width: 68rem · ไม่มี tab ไม่มีปุ่มพับ ไม่มี JS
-// ใช้ DARK_THEME_CSS + TABLE_CSS จาก src/web/html.ts
+// single column max-width: 68rem · no tabs, no collapse buttons, no JS
+// uses DARK_THEME_CSS + TABLE_CSS from src/web/html.ts
 
 import { DARK_THEME_CSS, esc, TABLE_CSS } from "../web/html.js";
 import type {

package/src/digest/text.ts

@@ -1,6 +1,6 @@
 // src/digest/text.ts — render digest as terminal text
 //
-// ลำดับ section ตาม SPEC §3 (เล่าเรื่อง ไม่ใช่ dashboard)
+// Section order per SPEC §3 (tells a story, not a dashboard)
 
 import type { CostRow, DigestData, MemRow, PlanRow } from "./collect.js";
 

package/src/gate.ts

@@ -53,9 +53,9 @@ export function gateOnce(
   }
 
   const config = loadConfig();
-  // runs.worktree เก็บ absolute path (SERVER_INSTRUCTIONS บังคับ) — ไม่ใช่ key ของ config.worktrees
-  // การ lookup จึงพลาดเสมอ และ fallback เดิม "." ทำให้คำสั่ง memory ของโปรเจกต์ไปรันใน cwd ของ
-  // MCP server แทนที่จะเป็นโปรเจกต์นั้น · lookup ยังอยู่เผื่อ row เก่าที่เคยเก็บเป็น key
+  // runs.worktree stores an absolute path (SERVER_INSTRUCTIONS mandates it) — not a key in config.worktrees
+  // so the lookup always misses, and the old "." fallback ran the project's memory commands in the cwd of
+  // the MCP server instead of that project · the lookup stays in case an old row was stored as a key
   const worktree = config.worktrees[run.worktree] ?? run.worktree;
 
   // --- pass family (4 grades) ---

package/src/hook.ts

@@ -1,17 +1,20 @@
 // src/hook.ts — Claude Code / Cursor Stop hook: refuse to end a turn that produced
 // commits but no verdict.
 //
-// ทำไมต้องเป็น hook ไม่ใช่ข้อความ: SERVER_INSTRUCTIONS เป็นการ *ขอ* ให้ agent จำ
-// วัดแล้วว่าไม่พอ · hook ไม่ได้ตัดสินเกรดแทน (ตัดสินไม่ได้ — มันไม่เห็นว่างานผ่านหรือพัง)
-// มันแค่ไม่ให้จบเทิร์นจนกว่า agent จะตัดสินเอง แยก "ใครตัดสิน" ออกจาก "ใครบังคับให้ตัดสิน"
+// Why a hook and not a message: SERVER_INSTRUCTIONS is a *request* that the
+// agent remember, and it measured as not enough · the hook does not grade in
+// the agent's place (it cannot — it does not see whether the work passed or
+// broke) it merely won't let the turn end until the agent grades itself,
+// separating "who judges" from "who forces judgment"
 //
-// สัญญาณคือ commit ไม่ใช่ dirty tree — dirty = กำลังทำอยู่, commit = หน่วยงานจบแล้ว
-// ตรงกับนิยาม "1 run = 1 หน่วยงานที่วัดได้" (กฎ 7)
+// The signal is a commit, not a dirty tree — dirty = still working, commit =
+// the unit of work is done, matching the definition "1 run = 1 measurable
+// unit of work" (rule 7)
 //
-// สอง payload หนึ่งการตัดสิน — field-mapping เท่านั้น:
+// Two payloads, one decision — field-mapping only:
 //   claude  {cwd, transcript_path, stop_hook_active} → {"decision":"block"}
 //   cursor  {workspace_roots, conversation_id, loop_count, status} → {"followup_message"}
-//   (cursor: loop_count ≥ 1 = hook เคยยิงแล้ว, status ≠ completed = ปล่อยผ่าน)
+//   (cursor: loop_count ≥ 1 = the hook already fired, status ≠ completed = allow)
 
 import { readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
@@ -54,7 +57,7 @@ export function utcStamp(d: Date): string {
  *
  * PLAN-mem-mcp chunk 3: the block message now carries the commit list and the
  * mem-log status (last row date). Both are *information*, never conditions —
- * the block condition stays verdict-only (กฎ 7: the hook does not judge, it
+ * the block condition stays verdict-only (rule 7: the hook does not judge, it
  * reports what is pending so the agent decides what deserves recording).
  */
 export function decideStop(opts: {
@@ -224,7 +227,7 @@ export async function cmdHookStop(): Promise<void> {
           .get(worktree, since) as { n: number } | null;
         verdicts = row?.n ?? 0;
         // Informational only — read-only, degrade silently (mem status never
-        // becomes a block condition, กฎ 7).
+        // becomes a block condition, rule 7).
         try {
           const mem = readMemLog(worktree);
           memLastTs = mem.rows[0]?.ts ?? null;
@@ -251,15 +254,17 @@ export async function cmdHookStop(): Promise<void> {
 
 // --- Read hint (PreToolUse annotate — never block, never dedupe) ---
 //
-// การอ่านไฟล์ใหญ่ทั้งไฟล์เป็นจุดที่ agent จ่าย token โดยไม่รู้ตัว — เสียงเตือน
-// ใน skill ไม่เคยพอ (หลักเดียวกับ Stop hook: พูดตอนมันกำลังจ่าย) แต่ hook นี้
-// **annotate เท่านั้น**: ไม่มี permissionDecision, ไม่มี "อ่านไปแล้ว" dedupe —
-// context compaction ทำให้ "อ่านไปแล้ว" กลายเป็นเท็จ และ hook ที่เดาผิดแล้วขัง
-// agent แย่กว่าไม่มี hook (กฎของ hook.ts เดิม) — annotate ขังไม่ได้ด้วย
-// construction, ต้นทุนพลาดสูงสุดคือบรรทัดเดียวที่ไม่จำเป็น
+// Reading a large file in full is where an agent spends tokens without
+// noticing — warnings in a skill were never enough (same principle as the
+// Stop hook: speak while it is spending). But this hook **annotates only**:
+// no permissionDecision, no "already read" dedupe — context compaction makes
+// "already read" false, and a hook that guesses wrong and traps the agent is
+// worse than no hook (the rule from the original hook.ts) — annotate cannot
+// trap by construction, the worst cost of a miss is one unnecessary line
 //
-// ข้อความเป็น fact ล้วน (จำนวนบรรทัด + คำสั่ง + ค่าที่วัดครั้งเดียว) ไม่ใช่
-// estimate ต่อไฟล์ — เดา token เป็นการแต่งตัวเป็นข้อมูล ขัด "facts only"
+// The text is facts only (line count + command + a one-time measurement), not
+// a per-file estimate — guessing tokens is dressing up as data, against
+// "facts only"
 
 /** Below this size a full read is already cheap — stay silent. */
 export const READ_HINT_MIN_BYTES = 24_000;
@@ -314,6 +319,98 @@ export function readHintFor(opts: ReadHintInput): string | null {
   }
 }
 
+// --- Commit hint (tool.execute.after — annotate only, never block) ---
+//
+// OpenCode has no Stop hook (Cursor does — see cursor.ts hook-stop wiring)
+// so it cannot block a turn; instead it appends an annotate to the bash tool
+// output whenever there is a git commit with no verdict pending. It is the
+// same kind of nudge as the read hint: no block, no dedupe, every unknown →
+// silent · called from the opencode plugin by direct import (like
+// readHintFor), no CLI subcommand because no client needs it as a subprocess
+// (Cursor uses its own hook-stop instead)
+//
+// The text is facts only (commit list + verdict status), not an estimate
+
+/** Below this number of commits, the hint is unnecessary noise. */
+export const COMMIT_HINT_MIN_COMMITS = 1;
+/** Cap commits shown in the hint message. */
+const COMMIT_HINT_MAX_LIST = 5;
+
+export interface CommitHintInput {
+  command: unknown;
+  cwd: string;
+}
+
+/**
+ * Nudge for bash commands containing `git commit` that produced
+ * ungraded commits. Returns a one-to-two line hint string, or null
+ * when there is nothing to nudge about (already graded, no commits,
+ * not a git commit command, not a git repo, any failure).
+ *
+ * Every unknown resolves to null — a hint must never fire on a
+ * guess. The work is cheap: one git rev-parse + one git log + one
+ * SQLite count.
+ */
+export function commitHintFor(opts: CommitHintInput): string | null {
+  try {
+    if (typeof opts.command !== "string" || opts.command === "") return null;
+    // Only fire on git commit commands — not `git push`, `git pull`, etc.
+    if (!/\bgit\s+commit\b/.test(opts.command)) return null;
+
+    const worktree = git(["rev-parse", "--show-toplevel"], opts.cwd);
+    if (!worktree) return null;
+
+    // Window = commits since the worktree's last verdict, not "does a
+    // verdict exist anywhere in its history" — a worktree that earned one
+    // verdict months ago must still nudge on every commit made since, the
+    // same way cmdHookStop windows on `e.ts >= since` (session start) rather
+    // than "any verdict this worktree has ever had".
+    const db = openDb();
+    const lastVerdict = db
+      .query(
+        `SELECT MAX(e.ts) AS ts FROM events e JOIN runs r ON r.id = e.run_id
+         WHERE e.kind = 'gate' AND r.worktree = ?`,
+      )
+      .get(worktree) as { ts: string | null } | null;
+    // git's --since is inclusive to the second, and the commit a verdict
+    // just graded often lands in the same UTC second as the verdict itself
+    // (verdict_submit runs right after the commit) — bump by 1s so that
+    // commit isn't re-flagged as ungraded because of its own grade.
+    const since = lastVerdict?.ts
+      ? utcStamp(
+          new Date(
+            new Date(`${lastVerdict.ts.replace(" ", "T")}Z`).getTime() + 1000,
+          ),
+        )
+      : null;
+
+    const log = since
+      ? git(["log", "--since", `${since} +0000`, "--format=%h %s"], worktree)
+      : git(["log", "--format=%h %s"], worktree);
+    const commitList = log ? log.split("\n").filter(Boolean) : [];
+    if (commitList.length < COMMIT_HINT_MIN_COMMITS) return null;
+
+    const reason = decideStop({
+      stopHookActive: false, // annotate-only: never "already blocked"
+      worktree,
+      commits: commitList.length,
+      verdicts: 0, // every commit left in the window is, by construction, ungraded
+      commitList: commitList.slice(0, COMMIT_HINT_MAX_LIST),
+    });
+    if (!reason) return null;
+
+    // Prefix each line with "fapony:" so it's visually distinct
+    // from normal bash output in the agent's context.
+    const prefixed = reason
+      .split("\n")
+      .map((l) => `fapony: ${l}`)
+      .join("\n");
+    return prefixed;
+  } catch {
+    return null; // any failure = no hint
+  }
+}
+
 /** Claude Code PreToolUse (matcher Read): stdin JSON in, additionalContext out.
  *  No permissionDecision ever — the tool call always proceeds. */
 export async function cmdHookReadHint(): Promise<void> {
@@ -355,10 +452,11 @@ export async function cmdHookReadHint(): Promise<void> {
 
 // --- Debt + mem context (PLAN-convention-debt chunk 4) ---
 //
-// จังหวะเดียวที่การแก้หนี้คุ้ม token คือตอนที่เปิดไฟล์นั้นอยู่แล้ว — hook-read-hint
-// จึงแนบสองอย่างต่อท้าย size hint: convention ที่ไฟล์ยังค้าง (debt detector, คำนวณสด)
-// และแถว mem ที่เอ่ยถึงไฟล์นั้น (ข้าม session) · **annotate เท่านั้น** เหมือนเดิม —
-// ไม่ block, ไม่ dedupe, ทุก unknown → เงียบ · cap รวม 5 บรรทัด (หนี้ 3 · mem 2)
+// The one moment paying down debt is worth tokens is when the file is already
+// open — so hook-read-hint appends two things after the size hint: conventions
+// the file still violates (debt detector, computed live) and mem rows that
+// mention the file (across sessions) · **annotate only**, as before — no
+// block, no dedupe, every unknown → silent · combined cap 5 lines (debt 3 · mem 2)
 
 const DEBT_HINT_MAX = 3;
 const MEM_HINT_MAX = 2;

package/src/init-mem.ts

@@ -31,9 +31,9 @@ export function cmdInitMem(args: string[]): void {
   const worktreeKey = args.find((x) => !x.startsWith("-"));
   const config = loadConfig();
 
-  // ไม่ระบุ key = repo ที่ยืนอยู่ตอนนี้ — ทำให้ `fapony init-mem --update` รันในโปรเจกต์ของใครก็ได้
-  // โดยไม่ต้องลงทะเบียน worktree ก่อน (loadConfig อ่าน fapony.config.json ของ cwd อยู่แล้ว
-  // จึงได้ paths.memoryEntry ของโปรเจกต์นั้นมาเอง)
+  // no key given = the repo you are standing in — so `fapony init-mem --update` runs in anyone's project
+  // without registering the worktree first (loadConfig already reads the cwd's fapony.config.json,
+  // so it picks up that project's paths.memoryEntry by itself)
   const worktree = worktreeKey ? config.worktrees[worktreeKey] : process.cwd();
   if (!worktree) {
     console.error(`unknown worktree key: ${worktreeKey}`);