fapony 0.1.1 → 0.1.3

package/templates/mem/commands/plan.ts

@@ -1,9 +1,9 @@
-// commands/plan.ts — plan-sweep: หา PLAN-*.md ที่ header บอก shipped แล้วแต่ยังไม่ย้ายเข้า done/
-// เหตุผล: ย้ายมือ = ต้องไล่แก้ relative link เอง (ในไฟล์ + ไฟล์อื่นที่ลิงก์มา) → ข้ามขั้นตอนบ่อย
-// ไม่มี arg = report เฉยๆ (ปลอดภัย โชว์ทุก kickoff/stale run ได้)
-// <file.md> = เช็คไฟล์เดียวว่าพร้อมย้ายไหม
-// <file.md> --apply = git mv + แก้ markdown link ในไฟล์เอง + แก้ inbound link จากไฟล์อื่นใน plan/
-//                      + แจ้ง warning plain-text mention (detect-only, ไม่ auto-fix)
+// commands/plan.ts — plan-sweep: find PLAN-*.md whose header says shipped but not yet moved into done/
+// rationale: moving by hand = chasing relative links yourself (in the file + files that link to it) → the step gets skipped often
+// no arg = report only (safe, shows every kickoff/stale run)
+// <file.md> = check a single file, is it ready to move
+// <file.md> --apply = git mv + fix markdown links inside the file + fix inbound links from other files in plan/
+//                      + warn about plain-text mentions (detect-only, no auto-fix)
 
 import {
   existsSync,
@@ -21,13 +21,13 @@ const SHIPPED = /^>\s*✅/m;
 const FRONT = /^---\r?\n([\s\S]*?)\r?\n---/;
 const HELD = /^status:\s*(blocked|superseded)\b/m;
 
-// header ✅ shipped ไม่ได้อยู่บรรทัดแรกอีกแล้ว — plan format ปัจจุบันขึ้นต้นด้วย frontmatter
-// แล้วตามด้วย `# title` (ดู templates/PLAN.md) เช็กหัวไฟล์แทนที่จะเช็กบรรทัดแรกบรรทัดเดียว
+// the ✅ shipped header is no longer on the first line — the current plan format starts with frontmatter
+// then `# title` (see templates/PLAN.md); check the file's head rather than a single first line
 //
-// frontmatter ชนะ header ✅ เสมอ: plan ที่ ship ไปบาง chunk แล้วติดรอของข้างนอก (VPS, คนใช้,
-// การตัดสินใจ) เขียน `status: blocked` ไว้ = ตั้งใจให้อยู่ใน plan/ ต่อ ไม่ใช่ของที่ลืมย้าย
-// ถ้าไม่ดูตรงนี้ plan แบบนั้นจะขึ้น "shipped but never archived" ทุกครั้งไปตลอด แล้วคนก็เลิกอ่าน
-// รายการนี้ทั้งรายการ — ซึ่งเป็นอาการเดียวกับที่ทำให้ done/ ไม่เคยขยับตั้งแต่แรก
+// frontmatter always beats the ✅ header: a plan that shipped some chunks and is waiting on externals (VPS, users,
+// a decision) writes `status: blocked` = it is meant to stay in plan/, not forgotten to move
+// if this is not checked, such plans show "shipped but never archived" forever, and people stop reading
+// the whole list — the same symptom that kept done/ from ever moving in the first place
 export const hasShippedHeader = (file: string): boolean => {
   const head = readFileSync(file, "utf8").slice(0, 2048);
   if (!SHIPPED.test(head)) return false;
@@ -49,10 +49,10 @@ const mdFiles = (dir: string): string[] =>
 
 const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
-// ไฟล์ย้าย dir แล้ว (เนื้อหาเดิม) — markdown link เดิมหมายถึง path เดิมเมื่ออิง oldDir, ต้อง re-relativize ผ่าน newDir
-// resolve จาก newDir (ที่ไฟล์อยู่ตอนนี้) — ถ้า target ก็ย้ายมา same dir → ได้ชื่อไฟล์ล้วน,
-// ถ้า target ยังอยู่ oldDir → ได้ ../target (ถูกทั้งสองทาง)
-// pass 1 only — แก้เฉพาะ [text](target) markdown links, ไม่แตะ plain text
+// the file moved dir (same content) — an old markdown link meant the old path relative to oldDir, must re-relativize via newDir
+// resolve from newDir (where the file is now) — if the target also moved to the same dir → plain filename,
+// if the target stayed in oldDir → ../target (both correct)
+// pass 1 only — fix only [text](target) markdown links, do not touch plain text
 export const rewriteMovedFileLinks = (
   file: string,
   oldDir: string,
@@ -76,8 +76,8 @@ export const rewriteMovedFileLinks = (
   return n;
 };
 
-// ไฟล์อื่นที่ลิงก์ชี้มาที่ path เดิม (oldAbs) → แก้ให้ชี้ path ใหม่ (newAbs) แทน
-// pass 1 only — แก้เฉพาะ [text](target) markdown links, ไม่แตะ plain text
+// other files whose links point at the old path (oldAbs) → repoint them at the new path (newAbs)
+// pass 1 only — fix only [text](target) markdown links, do not touch plain text
 export const rewriteMarkdownLinks = (
   file: string,
   oldAbs: string,
@@ -99,18 +99,18 @@ export const rewriteMarkdownLinks = (
   return n;
 };
 
-// นับ plain-text mention ของ target filename ในไฟล์ (detect-only, ไม่เขียนไฟล์)
-// regex: ไม่ใช่ markdown link [text](url) — จับทั้งแบบมี/ไม่มี .md extension
-// ครอบคลุม: prose, backtick code span, code fence — ทุก context ที่ไม่ใช่ markdown link
+// count plain-text mentions of the target filename in a file (detect-only, writes nothing)
+// regex: not a markdown link [text](url) — catches both with/without the .md extension
+// covers: prose, backtick code span, code fence — every context that is not a markdown link
 //
-// Fix (2026-09-02): ตัด markdown link ทั้งก้อน [text](target) ออกก่อน (ทั้ง display text และ
-// target — ไม่ใช่แค่ target) แล้วค่อยรัน plain-text regex บน string ที่เหลือ โดยไม่ต้องพึ่ง
-// lookbehind แล้ว — lookbehind เดิม `(?<![/\[(])` ตั้งใจกัน false-positive จาก markdown link
-// แต่ผลข้างเคียงคือ exclude ทุก mention ที่มี `/` นำหน้าไปด้วย (เช่น `done/PLAN-x.md` หรือ
-// `apps/vela/plan/PLAN-x.md`) — false-negative ตัวจริงที่พลาดใน 6e411042
-// Fix รอบแรก (ตัดแค่ `](target)`) พลาด — เหลือ `[display-text]` ไว้ไม่ได้ตัด ทำให้ link ที่ถูกต้อง
-// อยู่แล้วอย่าง `[PLAN-x.md](../done/PLAN-x.md)` (pattern จริงในไฟล์นี้ทั้งหมด) โดน count ซ้ำเป็น
-// plain-text mention — ต้องตัดทั้งก้อน [..](..)  ไม่ใช่แค่ส่วน (..)
+// Fix (2026-09-02): strip the whole markdown link [text](target) first (both display text and
+// target — not just target), then run the plain-text regex on the remainder, no longer needing
+// lookbehind — the old lookbehind `(?<![/\[(])` was meant to stop markdown-link false-positives
+// but its side effect was excluding every mention with a leading `/` too (e.g. `done/PLAN-x.md` or
+// `apps/vela/plan/PLAN-x.md`) — the real false-negative that slipped through in 6e411042
+// The first fix (stripping only `](target)`) missed — it left `[display-text]` unwrapped, making an already
+// valid link like `[PLAN-x.md](../done/PLAN-x.md)` (the actual pattern throughout this file) get double-counted as a
+// plain-text mention — strip the whole [..](..) block, not just the (..) part
 export const countPlainTextMentions = (
   file: string,
   target: string,
@@ -128,7 +128,7 @@ export const countPlainTextMentions = (
   return count;
 };
 
-// ใช้ร่วมกับ dashboard (now/kickoff) — ไฟล์ plan/ ที่มี header shipped แต่ยังไม่ย้ายเข้า done/
+// shared with the dashboard (now/kickoff) — plan/ files with a shipped header but not yet moved into done/
 export const shippedNotMoved = (): string[] => {
   const dir = planDir;
   if (!existsSync(dir)) return [];
@@ -187,8 +187,8 @@ export const cmdPlanSweep = (a: string[]) => {
     return;
   }
 
-  // ponytail: --apply เดิม (ก่อนหน้านี้) ไม่บังคับ 2 เงื่อนไขนี้เลย — ผ่าน dry-run message ได้ก็จริง
-  // แต่รัน --apply ตรง ๆ ข้ามได้หมด → เสี่ยงเวลา agent ship เองอัตโนมัติไม่มีคนเช็ค แก้เป็น hard block
+  // ponytail: the old --apply enforced neither of these two conditions — you could pass the dry-run message
+  // but then run --apply directly and skip everything → risky when an agent ships automatically with no human check, so hard block
   if (!shipped && !process.env.MEM_FORCE) {
     console.error(
       `${target}: no ✅ shipped header at the top — refusing to move (MEM_FORCE=1 to override)`,
@@ -211,8 +211,8 @@ export const cmdPlanSweep = (a: string[]) => {
     process.exit(1);
   }
 
-  // ponytail: ไฟล์ที่เพิ่งเขียนในรอบนี้อาจยังไม่ git add — `git mv` fail แบบเงียบ (exit 128, ไม่ throw)
-  // แล้วโค้ดต่อไปพัง ENOENT ตอนอ่าน dst ที่ไม่มีจริง — stage ก่อนเสมอ (no-op ถ้า track อยู่แล้ว)
+  // ponytail: a file just written this round may not be git add'ed yet — `git mv` fails silently (exit 128, no throw)
+  // then the next code hits ENOENT reading a dst that does not exist — always stage first (no-op if already tracked)
   mkdirSync(doneDir, { recursive: true });
   Bun.spawnSync(["git", "add", src]);
   const mv = Bun.spawnSync(["git", "mv", src, dst]);
@@ -221,8 +221,8 @@ export const cmdPlanSweep = (a: string[]) => {
     process.exit(1);
   }
 
-  // done/ เป็นพี่น้องกับ plan/ = ลึกเท่าเดิม ลิงก์ในไฟล์ยังชี้ถูกทุกเส้น ไม่ต้องแตะ
-  // layout เก่า (plan/done/) ลึกขึ้น 1 ชั้น ถึงจะต้อง re-relativize
+  // done/ is a sibling of plan/ = same depth, links in the file still resolve, no need to touch
+  // the old layout (plan/done/) is one level deeper, so it does need re-relativizing
   const nested = dirname(doneDir) !== dirname(dir);
   const ownLinks = nested ? rewriteMovedFileLinks(dst, dir, doneDir) : 0;
 
@@ -247,7 +247,7 @@ export const cmdPlanSweep = (a: string[]) => {
     `inbound links rewritten: ${inbound} in ${inboundFiles} file(s) (scanned ${rel(dir)}/** only)`,
   );
 
-  // log decision — record ship event (reuse existing kind, ไม่ต้อง schema ใหม่)
+  // log decision — record ship event (reuse existing kind, no new schema)
   const doneSpec = `${rel(dst)}`;
   put({
     id: nextId(rows()),
@@ -255,11 +255,11 @@ export const cmdPlanSweep = (a: string[]) => {
     text: `${target} shipped → ${rel(dst)}`,
     spec: doneSpec,
   });
-  // ponytail: decision นี้ *คือ* การย้ายเอง ไม่มีอะไรต้องเขียนกลับเข้า spec อีก — ไม่ mark synced
-  // ทันที staleReport จะขึ้น "decision ยังไม่เข้า spec" ทุกครั้งที่ ship (เห็นจริงใน kickoff 2026-09-02)
+  // ponytail: this decision *is* the move itself, nothing to write back into the spec — do not mark synced
+  // immediately or staleReport shows "decision never made it into the spec" on every ship (seen in kickoff 2026-09-02)
   put({ kind: "synced", spec: doneSpec });
 
-  // plain-text mention detection (detect-only, ไม่ auto-fix)
+  // plain-text mention detection (detect-only, no auto-fix)
   let plainTextTotal = 0;
   const plainTextFiles: string[] = [];
   for (const f of mdFiles(dir)) {
@@ -275,14 +275,14 @@ export const cmdPlanSweep = (a: string[]) => {
     );
   }
 
-  // ไฟล์นอก plan/ ที่ mention target — detect-only
+  // files outside plan/ that mention the target — detect-only
   const grep = Bun.spawnSync([
     "git",
     "grep",
     "-l",
     target,
     "--",
-    // ขอบเขต "ไฟล์นอก plan/" = โฟลเดอร์ที่ plan/ อยู่ใต้มัน (apps/vela, .fapony, …)
+    // the "files outside plan/" scope = the folder plan/ lives under (apps/vela, .fapony, …)
     rel(dirname(planDir)),
     `:!${rel(dir)}`,
   ])
@@ -324,8 +324,8 @@ export const cmdPlanCheck = (a: string[]) => {
   //    only check active files (not done/) — done/ files are historical snapshots with external refs
   const linkRe = /\]\(([^)]+)\)/g;
   for (const f of active) {
-    // ตัด fenced block + inline code ทิ้งก่อน (แทนที่ด้วย spaces เพื่อคง line offset) —
-    // ตัวอย่าง link ใน code (เช่น spec ของเครื่องมือนี้เอง) ต้องไม่ถูกนับเป็น link จริง
+    // strip fenced blocks + inline code first (replace with spaces to preserve line offset) —
+    // example links in code (e.g. this tool's own spec) must not be counted as real links
     const src = readFileSync(f, "utf8")
       .replace(/```[\s\S]*?```/g, (b) => b.replace(/[^\n]/g, " "))
       .replace(/`[^`\n]*`/g, (b) => " ".repeat(b.length));

package/templates/mem/commands/read.ts

@@ -22,7 +22,7 @@ const planSweepLine = () => {
 };
 
 export const cmdNow = () => {
-  // mem now (default) — next+bug+hold. decision/note ไม่ใช่งานค้าง → ค้นด้วย find แทน
+  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
   const all = rows();
   console.log(`# ${app} — ${all.length} entries`);
   printOpenRows(all, { showHold: true });
@@ -53,7 +53,7 @@ export const cmdStale = () => {
 };
 
 export const cmdFind = (a: string[]) => {
-  // mem find <คำ> — grep text/spec ไม่สนตัวพิมพ์เล็กใหญ่, ล่าสุดก่อน, จำกัด 20 แถว
+  // mem find <word> — grep text/spec case-insensitively, newest first, capped at 20 rows
   const q = a.join(" ").toLowerCase();
   if (!q) {
     console.error(`usage: ${memCmd} find <word>`);
@@ -86,7 +86,7 @@ export const cmdKickoff = (a: string[]) => {
   const arg = a[0] ?? "";
 
   if (!arg) {
-    // ไม่มี args = now + section "ล่าสุด" = closes 10 รายการล่าสุด
+    // no args = now + a "recent" section = the last 10 closes
     console.log(`# ${app} — ${all.length} entries`);
     printOpenRows(all, { showHold: true });
     console.log(`\n## recent\n${doneLines(all, 10).join("\n")}`);
@@ -101,7 +101,7 @@ export const cmdKickoff = (a: string[]) => {
     const rotate = rotateLine(all.length);
     if (rotate) console.log(rotate);
   } else if (arg.endsWith(".md")) {
-    // spec.md = brief ของ spec นั้น
+    // spec.md = a brief for that spec
     const workAll = all.filter((r): r is WorkRow => "id" in r);
     const byId = new Map(workAll.map((r) => [r.id, r] as const));
     const open = openRows(all);
@@ -135,7 +135,7 @@ export const cmdKickoff = (a: string[]) => {
       console.log("(no entries for this spec)");
     }
   } else {
-    // id = brief ของงานนั้น
+    // id = a brief for that task
     const workAll = all.filter((r): r is WorkRow => "id" in r);
     const byId = new Map(workAll.map((r) => [r.id, r] as const));
     const target = byId.get(arg);

package/templates/mem/commands/rotate.ts

@@ -1,15 +1,15 @@
 // commands/rotate.ts — compact log.jsonl once it grows past a row-count threshold
-// เก็บ open work rows + active claim ไว้ ที่เหลือ (close/release/synced ของ ref ที่ปิดแล้ว)
-// git mv ไปไฟล์ archive แยก (ไม่ลบ) — ประวัติเก่ายังอยู่ ค้นย้อนหลังได้ผ่าน git log/git show
+// keep open work rows + active claims; the rest (close/release/synced of already-closed refs)
+// is git mv'd to a separate archive file (not deleted) — old history remains, searchable via git log/git show
 
 import { existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { rotateKeep } from "../selectors.js";
 import { appendRaw, dir, LOG, rows } from "../store.js";
 
-// ponytail: threshold = จำนวนแถวทั้งหมด ไม่ใช่แค่ open — ที่กลัวคือไฟล์บวม/grep ช้าตอนหลายคนใช้พร้อมกัน
-// (view อ่านไม่รู้เรื่องเป็นปัญหาคนละอันที่ CAP ใน write.ts จัดการอยู่แล้ว)
-// 3000 กะจาก solo 1 สัปดาห์ = ~2k แถว — ปรับได้ด้วย MEM_ROTATE_THRESHOLD ถ้า pace ต่างจากนี้มาก
+// ponytail: threshold = total row count, not just open — the fear is a bloated file / slow grep when many people use it at once
+// (the view being unreadable is a separate problem the CAP in write.ts already handles)
+// 3000 estimated from one solo week = ~2k rows — tune with MEM_ROTATE_THRESHOLD if the pace differs a lot from this
 export const THRESHOLD = Number(process.env.MEM_ROTATE_THRESHOLD) || 3000;
 
 export const cmdRotate = (a: string[]) => {
@@ -40,7 +40,7 @@ export const cmdRotate = (a: string[]) => {
     process.exit(1);
   }
 
-  // เหมือน plan-sweep: stage ก่อนกัน git mv fail เงียบถ้าไฟล์ยังไม่ track (exit 128)
+  // like plan-sweep: stage first to stop git mv failing silently if the file is untracked (exit 128)
   Bun.spawnSync(["git", "add", LOG]);
   const mv = Bun.spawnSync(["git", "mv", LOG, archived]);
   if (mv.exitCode !== 0) {

package/templates/mem/commands/selftest.ts

@@ -37,7 +37,7 @@ const runSelectorTests = () => {
     { id: "a2", kind: "next", text: "work B", ts: "", agent: "" },
     { kind: "close", ref: "a2", text: "done", ts: "", agent: "" },
     { kind: "claim", ref: "a1", ts: "2026-01-01T00:00:00Z", agent: "agent-1" },
-    // (1) claim เดียว → active
+    // (1) single claim → active
     { id: "a3", kind: "bug", text: "work C", ts: "", agent: "" },
     { kind: "claim", ref: "a3", ts: "2026-01-01T01:00:00Z", agent: "agent-1" },
     {
@@ -55,7 +55,7 @@ const runSelectorTests = () => {
     { id: "a5", kind: "next", text: "work E", ts: "", agent: "" },
     { kind: "claim", ref: "a5", ts: "2026-01-01T04:00:00Z", agent: "agent-1" },
     { kind: "claim", ref: "a5", ts: "2026-01-01T05:00:00Z", agent: "agent-3" },
-    // (4) double claim → หลังชนะ (agent-3)
+    // (4) double claim → the later one wins (agent-3)
   ];
 
   const claims = claimsOf(t);
@@ -70,12 +70,12 @@ const runSelectorTests = () => {
   assert(!claims.has("a3"), "release did not void the claim");
   // (3) a4 close → inactive
   assert(!claims.has("a4"), "close void claim");
-  // (4) a5 double claim → agent-3 ชนะ
+  // (4) a5 double claim → agent-3 wins
   assert(
     claims.has("a5") && claims.get("a5")?.agent === "agent-3",
     "double claim after the winner",
   );
-  // a2 closed → ไม่ควรอยู่ใน open
+  // a2 closed → should not appear in open
   assert(!open.some((r) => r.id === "a2"), "tombstone broken");
   // open = a1, a3 (released but still open), a5
   assert(
@@ -91,12 +91,12 @@ const runRotateTests = () => {
   const t: LogRow[] = [
     { id: "r1", kind: "next", text: "keep me", ts: "", agent: "" },
     { kind: "claim", ref: "r1", ts: "2026-01-01T00:00:00Z", agent: "agent-1" },
-    // r1: open + claimed → work row + claim row ต้องเก็บทั้งคู่
+    // r1: open + claimed → both the work row and the claim row must be kept
 
     { id: "r2", kind: "bug", text: "closed already", ts: "", agent: "" },
     { kind: "claim", ref: "r2", ts: "2026-01-01T00:00:00Z", agent: "agent-1" },
     { kind: "close", ref: "r2", text: "shipped", ts: "", agent: "" },
-    // r2: ปิดแล้ว → work row, claim row, close tombstone ทิ้งหมด
+    // r2: closed → work row, claim row, close tombstone all dropped
 
     {
       id: "r3",
@@ -112,7 +112,7 @@ const runRotateTests = () => {
       ts: "2026-01-02T00:00:00Z",
       agent: "",
     },
-    // r3: spec synced *หลัง* decision นี้ → resolved แล้ว archive ได้
+    // r3: spec synced *after* this decision → resolved, can be archived
 
     {
       id: "r4",
@@ -122,10 +122,10 @@ const runRotateTests = () => {
       agent: "",
       spec: "PLAN-a.md",
     },
-    // r4: decision ใหม่กว่า synced ล่าสุด → ยังไม่ resolved เก็บไว้
+    // r4: decision newer than the latest synced → not resolved yet, keep it
 
     { id: "r5", kind: "note", text: "note no spec", ts: "", agent: "" },
-    // r5: note ไม่มี spec → ไม่มีทางรู้ resolved หรือยัง เก็บไว้เสมอ
+    // r5: a note with no spec → no way to know if resolved, always kept
   ];
 
   const kept = rotateKeep(t);
@@ -167,17 +167,17 @@ const runPlanSweepTests = () => {
   const tmpDir = mkdtempSync(join(tmpdir(), "mem-test-"));
   try {
     // === Case A: rewriteMarkdownLinks + countPlainTextMentions ===
-    // สร้าง fixture: ไฟล์ที่ reference ไปที่ plan/PLAN-page-style.md หลายแบบ
+    // build fixture: a file that references plan/PLAN-page-style.md several ways
     const planDir = join(tmpDir, "plan");
     const doneDir = join(tmpDir, "plan", "done");
     mkdirSync(planDir, { recursive: true });
     mkdirSync(doneDir, { recursive: true });
 
-    // "old" file — จำลอง apps/vela/plan/PLAN-page-style.md (touch only)
+    // "old" file — simulates apps/vela/plan/PLAN-page-style.md (touch only)
     const oldFile = join(planDir, "PLAN-page-style.md");
     writeFileSync(oldFile, "# PLAN-page-style\n");
 
-    // inbound file — จำลอง apps/vela/plan/PLAN-people-style.md
+    // inbound file — simulates apps/vela/plan/PLAN-people-style.md
     const inbound = [
       "# PLAN-people-style — refs",
       "",
@@ -361,13 +361,13 @@ const runPlanCheckTests = () => {
     );
     writeFileSync(join(planDir, "PLAN-active.md"), "# active plan\n");
 
-    // plan ที่เขียนด้วย format ปัจจุบัน: frontmatter + title มาก่อน header ✅ shipped
+    // a plan in the current format: frontmatter + title come before the ✅ shipped header
     writeFileSync(
       join(planDir, "PLAN-frontmatter.md"),
       "---\nkind: unit\n---\n\n# shipped with frontmatter\n\n> ✅ **shipped 2026-09-13** (abc1234)\n",
     );
 
-    // ship ไปบาง chunk แล้วติดรอของข้างนอก — frontmatter บอกว่าตั้งใจให้อยู่ต่อ ห้ามนับว่าลืมย้าย
+    // shipped some chunks and waiting on externals — frontmatter says it is meant to stay, do not count as forgotten
     writeFileSync(
       join(planDir, "PLAN-blocked.md"),
       "---\nstatus: blocked\nblocked_by: VPS#2\n---\n\n# partly shipped\n\n> ✅ **chunk 1 shipped 2026-09-13** (abc1234)\n",

package/templates/mem/commands/write.ts

@@ -7,17 +7,17 @@ import { KINDS, memCmd, nextId, put, root, rows } from "../store.js";
 export const cmdAdd = async (a: string[]) => {
   // mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [path/to/SPEC.md]
   // mem add <kind> --stdin --files f1,f2 [spec.md]  ← read text from stdin (avoids shell metachar issues)
-  // ponytail: kind ผิด = แถวนั้นหายจาก view เงียบๆ — ตายตั้งแต่ตรงนี้ดีกว่า
+  // ponytail: a wrong kind = that row silently vanishes from the view — better to die right here
   if (!KINDS.includes(a[0] as WorkKind)) {
     console.error(
       `kind must be one of ${KINDS.join("|")} — got "${a[0] ?? ""}"`,
     );
     process.exit(1);
   }
-  // hold บังคับ spec — ตรวจหลัง parse (spec อยู่ก่อน --files ได้)
-  // PLAN-convention-debt chunk 3: files[] เป็น required — optional field ที่วัดแล้ว
-  // fill rate = 0 (required+enum = 50/50) และ recall ของ log เก่าที่ไม่มี files[] จับได้แค่
-  // 48.1% — แก้ที่ขาเขียน ไม่ใช่ขาอ่าน: แถวไหนไม่บอกไฟล์ = ค้นไม่เจอตอนแตะไฟล์นั้น
+  // hold requires a spec — checked after parse (the spec may come before --files)
+  // PLAN-convention-debt chunk 3: files[] is required — a measured optional field
+  // had fill rate 0 (required+enum = 50/50) and recall on old logs without files[] caught only
+  // 48.1% — fix the write side, not the read side: a row that does not name the file = unfindable when you touch that file
   const filesFlagIdx = a.indexOf("--files");
   const filesVal = filesFlagIdx >= 0 ? a[filesFlagIdx + 1] : undefined;
   if (!filesVal || filesVal.startsWith("--")) {
@@ -56,7 +56,7 @@ export const cmdAdd = async (a: string[]) => {
       process.exit(1);
     }
   } else {
-    // ต้องมีข้อความ
+    // text is required
     if (!filtered.length || (filtered.length === 0 && !spec)) {
       console.error(
         `text is required — usage: ${memCmd} add <kind> "<text>" --files f1,f2 [spec.md]`,
@@ -67,7 +67,7 @@ export const cmdAdd = async (a: string[]) => {
   }
   // read once — cap check + id collision
   const all = rows();
-  // ponytail: เพดาน open next/hold กันสะสมไม่มีที่สิ้นสุด — บังคับ triage ของเก่าก่อนเปิดใหม่
+  // ponytail: a cap on open next/hold stops endless accumulation — forces triage of the old before opening new
   const CAP = 15;
   const CAP_HOLD = 10;
   if (a[0] === "next" && !process.env.MEM_FORCE) {
@@ -88,14 +88,14 @@ export const cmdAdd = async (a: string[]) => {
       process.exit(1);
     }
   }
-  // ponytail: กัน id ชน — logic รวมไว้ที่ nextId (store.ts)
+  // ponytail: prevent id collisions — logic centralized in nextId (store.ts)
   const id = nextId(all);
   put({ id, kind: a[0] as WorkKind, text, spec, files });
   console.log(id);
 };
 
 export const cmdClose = async (a: string[]) => {
-  // mem close <id> "<ทำอะไร / commit>" — tombstone ทำให้ claim void เอง
+  // mem close <id> "<what was done / commit>" — the tombstone voids the claim by itself
   // mem close <id> --stdin ← read text from stdin
   if (!a[0]) {
     console.error(`id is required — usage: ${memCmd} close <id> "<text>"`);
@@ -117,7 +117,7 @@ export const cmdClose = async (a: string[]) => {
 };
 
 export const cmdClaim = (a: string[]) => {
-  // mem claim <id> — ต้องมี id จริง, open, kind=next|bug, ไม่มี active claim ค้าง
+  // mem claim <id> — id must be real, open, kind=next|bug, with no active claim pending
   if (!a[0]) {
     console.error(`id is required — usage: ${memCmd} claim <id>`);
     process.exit(1);
@@ -153,7 +153,7 @@ export const cmdClaim = (a: string[]) => {
 };
 
 export const cmdRelease = async (a: string[]) => {
-  // mem release <id> "<เหตุผล>?"
+  // mem release <id> "<reason>?"
   // mem release <id> --stdin ← read text from stdin
   if (!a[0]) {
     console.error(`id is required — usage: ${memCmd} release <id> [reason]`);
@@ -179,7 +179,7 @@ export const cmdRelease = async (a: string[]) => {
 };
 
 export const cmdSynced = (a: string[]) => {
-  // mem synced [path.md ...] — ประกาศว่า spec ตรงกับ log แล้ว (ไม่ระบุ = ทุก spec ที่ log อ้างถึง)
+  // mem synced [path.md ...] — declare the spec now matches the log (none given = every spec the log mentions)
   const specs = a.length
     ? a
     : [
@@ -195,7 +195,7 @@ export const cmdSynced = (a: string[]) => {
 };
 
 export const cmdHook = async () => {
-  // PostToolUse: stdin = {tool_input:{file_path}} → แก้ spec ของ app นี้เสร็จ = synced ให้เอง
+  // PostToolUse: stdin = {tool_input:{file_path}} → editing this app's spec is done = mark synced automatically
   const j = (await Bun.stdin.json().catch(() => null)) as Record<
     string,
     unknown

package/templates/mem/mem.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
 
-// append-only memory log. ห้ามแก้บรรทัดเก่า — ปิดงาน = close (tombstone), git = ประวัติ
-// log อยู่ข้างไฟล์นี้เสมอเมื่อถูกวางโดย `fapony init` (<project>/.fapony/.memory/log.jsonl);
-// สำเนากลางใน monorepo (โค้ดชุดเดียวที่ root) ยังแยก log ราย app: apps/<app>/.fapony/.memory/log.jsonl
-// (repo ที่ยังไม่ย้ายซึ่งมี log เก่าที่ apps/<app>/.memory/log.jsonl จะอ่านที่เดิมต่อ)
+// append-only memory log. Never edit old lines — close a task = close (tombstone), git = history
+// the log always sits beside this file when placed by `fapony init` (<project>/.fapony/.memory/log.jsonl);
+// the central copy in a monorepo (single code copy at the root) still splits logs per app: apps/<app>/.fapony/.memory/log.jsonl
+// (a repo not yet migrated with an old log at apps/<app>/.memory/log.jsonl keeps reading that location)
 //
 // CLI entry point — all logic lives in:
 //   store.ts       (types + config + rows/put)
@@ -63,6 +63,6 @@ if (cmd === "add") {
 } else if (cmd === "rotate") {
   cmdRotate(a);
 } else {
-  // mem now (default) — next+bug+hold. decision/note ไม่ใช่งานค้าง → ค้นด้วย find แทน
+  // mem now (default) — next+bug+hold. decision/note is not pending work → search with find instead
   cmdNow();
 }

package/templates/mem/selectors.ts

@@ -8,8 +8,8 @@ import type {
   WorkRow,
 } from "./store.js";
 
-// ponytail: reducer = filter + tombstone set. 50k บรรทัด = 9.6MB/26ms — ไฟล์ไม่ใช่คอขวด
-// เพดานจริง = แถวที่ยังเปิดเยอะจน view อ่านไม่รู้เรื่อง → ตอนนั้นค่อย rotate: git mv + append openRows(เก่า) ลงไฟล์ใหม่
+// ponytail: reducer = filter + tombstone set. 50k lines = 9.6MB/26ms — the file is not the bottleneck
+// the real ceiling = too many open rows for the view to make sense → rotate then: git mv + append openRows(old) into a new file
 export const openRows = (all: LogRow[]): WorkRow[] => {
   const dead = new Set(
     all.filter((r): r is CloseRow => r.kind === "close").map((r) => r.ref),
@@ -25,8 +25,8 @@ export const openRows = (all: LogRow[]): WorkRow[] => {
   );
 };
 
-// C) claimsOf: คืน Map ref → latest claim row ที่ยัง active
-// active = แถวล่าสุดของ claim|release เป็น claim และ ref ไม่อยู่ใน dead (close)
+// C) claimsOf: returns Map ref → latest claim row still active
+// active = the latest claim|release row is a claim and ref is not in dead (close)
 export const claimsOf = (all: LogRow[]): Map<string, ClaimRow> => {
   const dead = new Set(
     all.filter((r): r is CloseRow => r.kind === "close").map((r) => r.ref),
@@ -46,9 +46,9 @@ export const claimsOf = (all: LogRow[]): Map<string, ClaimRow> => {
   return active;
 };
 
-// decision ที่ใหม่กว่าทั้ง commit ล่าสุดของ spec และ synced marker = spec ยังไม่ได้อัปเดตตาม
-// + next/hold ที่มี spec ถูกแก้หลังสร้าง = อาจปิดไปแล้วแต่ไม่มีใคร close — เคสจริง: msbnndmt
-// + active claim ที่อายุเกิน 4 ชม. = agent อาจตายกลางงาน
+// a decision newer than both the spec's latest commit and the synced marker = spec not updated to match
+// + next/hold whose spec was edited after creation = may be done already but nobody closed it — real case: msbnndmt
+// + an active claim older than 4h = the agent may have died mid-task
 export const staleReport = (all: LogRow[]): string[] => {
   const out: string[] = [];
   const mark: Record<string, number> = {};
@@ -67,7 +67,7 @@ export const staleReport = (all: LogRow[]): string[] => {
   }
   const gitDates = new Map<string, number>();
   for (const spec of specPaths) {
-    // --follow: spec path ที่ถูก git mv (เช่น ย้ายเข้า plan/done/) ยังตามประวัติต่อได้
+    // --follow: a spec path that was git mv'd (e.g. moved into plan/done/) can still follow its history
     const git = Bun.spawnSync([
       "git",
       "log",
@@ -94,9 +94,9 @@ export const staleReport = (all: LogRow[]): string[] => {
   for (const r of openRows(all)) {
     if ((r.kind === "next" || r.kind === "hold") && r.spec) {
       const gitDate = gitDates.get(r.spec);
-      // ponytail: grace 24 ชม. — "log next แล้วเขียน/commit plan ต่อในวันเดียวกัน" คือ workflow ปกติ
-      // ไม่ใช่สัญญาณว่างานจบแล้วลืมปิด (เคสจริงที่ต้องจับอย่าง msbnndmt ห่างกันเป็นวัน) —
-      // ไม่มี grace = SUSPECT ขึ้นทุกแผนที่เพิ่งเขียน แล้วทุกคนเรียนรู้ที่จะเลื่อนผ่าน stale ทั้งบล็อก
+      // ponytail: 24h grace — "log next then write/commit the plan the same day" is normal workflow
+      // not a signal that the work finished and was forgotten (the real case to catch, msbnndmt, is days apart) —
+      // without grace = SUSPECT fires on every freshly written plan, and everyone learns to skim past the whole stale block
       if (gitDate && gitDate > Date.parse(r.ts) + 86_400_000)
         out.push(
           `SUSPECT [${r.id}] ${r.spec} changed after this ${r.kind} (${r.ts.slice(0, 10)}) — check whether it is already done`,
@@ -115,13 +115,13 @@ export const staleReport = (all: LogRow[]): string[] => {
   return out;
 };
 
-// rotate: แถวที่ต้องแบกต่อในไฟล์ log ใหม่หลัง archive
-// - next/bug/hold ที่ยังเปิด + claim ที่ยัง active อยู่บนแถวนั้น (close/claim ของ ref ที่ปิดแล้ว = ทิ้งได้)
-// - decision/note ยังไม่มี "close" ของตัวเอง (ประวัติถาวรตามดีไซน์) แต่ resolved ได้ทางอ้อมผ่าน synced:
-//   spec ถูก synced *หลัง* แถวนี้แล้ว = ข้อมูลเข้า spec แล้วจริง เก็บใน archive (git) พอ ไม่ต้องแบกในไฟล์ hot
-//   (logic เดียวกับ staleReport's decision check — ไม่มี spec หรือยังไม่ synced ทันแถวนี้ = ยังถือว่า relevant, เก็บไว้)
-// ponytail: decision/note ที่ไม่มี spec ไม่มีทางรู้ว่า resolved แล้วหรือยัง — เก็บไว้ตลอด (เพดานจริงคือ
-// ต้อง attach spec ตั้งแต่ log ถ้าอยากให้ rotate ออกได้ในอนาคต ไม่ใช่ปัญหาของ rotate เอง)
+// rotate: rows that must carry over into the new log file after archiving
+// - open next/bug/hold + still-active claims on those rows (close/claim of already-closed refs = discardable)
+// - decision/note has no "close" of its own (permanent history by design) but resolves indirectly via synced:
+//   spec was synced *after* this row = the info really made it into the spec, archive (git) is enough, no need to carry it in the hot file
+//   (same logic as staleReport's decision check — no spec or not yet synced by this row = still considered relevant, keep it)
+// ponytail: a decision/note with no spec gives no way to know if it is resolved — keep it forever (the real ceiling is
+// attaching a spec at log time if you want rotate to be able to drop it later, not rotate's own problem)
 export const rotateKeep = (all: LogRow[]): LogRow[] => {
   const open = openRows(all);
   const workOpen = open.filter(