fapony 0.1.3 → 0.2.0

package/src/mcp/tools/index.ts

@@ -1,12 +1,15 @@
 // src/mcp/tools/index.ts — barrel + TOOLS array
+//
+// Every schema here is paid as input tokens in *every* session of *every*
+// client that connects, whether or not the tool is called. Adding one is
+// buying attention with a standing charge; earning it back means the tool
+// saves more than it costs (see CLAUDE.md "จ่าย token อย่างฉลาด"). Keep
+// descriptions imperative — say what to send, not why it matters.
 
 import { VERDICT_GRADES } from "../../parse.js";
 import { REASON_CODES, REGIME_CODES } from "../types.js";
 
-export { toolProjectHealthContext } from "./context.js";
-export { toolMemFind } from "./mem.js";
-export { toolPlanList } from "./plans.js";
-export { toolFaponyStats } from "./stats.js";
+export { toolMemAdd, toolMemFind } from "./mem.js";
 export { toolPassiveUsage } from "./usage.js";
 export { toolVerdictSubmit } from "./verdict.js";
 
@@ -16,24 +19,18 @@ export const TOOLS = [
   {
     name: "verdict_submit",
     description:
-      "Grade a finished unit of work. " +
-      "WHEN: every unit that ends, including work that went right the first " +
-      "time — this is a grade on the work, not a confession, and a model's " +
-      "record is only worth the number of graded units behind it. " +
-      "If a first attempt was wrong, submit 'fail' the moment you realize it, " +
-      "then a pass-family verdict once the fix is verified. " +
-      "Never leave a run open — one stuck at running/fixing " +
-      "absorbs later unrelated verdicts for that worktree. " +
-      "Without run_id, binds to the latest still-open run for the same " +
-      "worktree+plan (round keeps counting toward review.maxRounds); " +
-      "creates a new run entry only when none is open.",
+      "Grade a finished unit of work — every unit that ends, including work " +
+      "that went right the first time. Submit 'fail' the moment a first " +
+      "attempt turns out wrong, then a pass-family verdict once the fix is " +
+      "verified. Never leave a run open: one stuck at running/fixing absorbs " +
+      "later unrelated verdicts for that worktree. Without run_id, binds to " +
+      "the latest open run for the same worktree+plan, else creates one.",
     inputSchema: {
       type: "object" as const,
       properties: {
         run_id: {
           type: "number",
-          description:
-            "Optional run ID from fapony. If omitted, a new run is created automatically.",
+          description: "Existing run to attach to. Omitted = bind or create.",
         },
         verdict: {
           type: "string",
@@ -44,114 +41,141 @@ export const TOOLS = [
           type: "string",
           enum: [...REASON_CODES],
           description:
-            "Standardized failure reason code. Use 'none' for clean passes (not 'other').",
+            "Failure reason. Clean passes take 'none', never 'other'.",
         },
         regime: {
           type: "string",
           enum: [...REGIME_CODES],
           description:
-            "Task shape: code=new feature/refactor, fix=debugging an existing defect, " +
-            "review=reviewing someone else's work/diff, plan=producing a plan or spec, " +
-            "inquiry=asking questions without editing files, test=writing or editing tests as primary work",
+            "Task shape: code=feature/refactor, fix=debugging a defect, " +
+            "review=reviewing a diff, plan=producing a plan or spec, " +
+            "inquiry=questions without editing files, test=writing tests",
         },
         note: {
           type: "string",
-          description: "Optional note (required when reason_code = 'other')",
+          description:
+            "Standalone note — read months later with no access to this " +
+            "conversation. Required when reason_code = 'other'.",
         },
         worktree: {
           type: "string",
           description:
-            "Absolute path of the repo/worktree (git rev-parse --show-toplevel), used when run_id is omitted. " +
-            "Send it: every fapony query scopes by absolute path, so a bare repo name lands in a bucket no " +
-            'query reads, and omitting it files the verdict under "mcp-external" instead of the project. ' +
-            "Neither case errors.",
+            "Absolute repo path (git rev-parse --show-toplevel). Every query " +
+            "scopes by it, so a bare name or an omission files the verdict " +
+            "where nothing reads it. Neither case errors.",
         },
         plan: {
           type: "string",
-          description:
-            "Optional plan file path for a new run (used only when run_id is omitted)",
+          description: "Plan file path, for a new run",
         },
         session_id: {
           type: "string",
           description:
-            "The client session id — Claude Code/Codex: the transcript .jsonl path; " +
-            "OpenCode/ZCode: the session id. It is what attributes this verdict to a model; " +
-            "without it fapony infers the model from whichever session is running, which is a " +
-            "guess. Send it whenever the client exposes it. Cannot find it → omit, never invent one.",
+            "Client session id (Claude Code/Codex: the transcript .jsonl " +
+            "path; OpenCode/ZCode: the session id) — this is what attributes " +
+            "the verdict to a model. Cannot find it → omit, never invent one.",
         },
         files: {
           type: "array",
           items: { type: "string" },
           description:
-            "Repo-relative paths of the files this work unit touched. Technically " +
-            "optional, but always send them: this is the only input to per-file " +
-            "risk history — a verdict with no files[] teaches the next session " +
-            "nothing about where the risk was.",
+            "Repo-relative paths this unit touched. Optional, but always " +
+            "send them: nothing else records where the work landed.",
         },
       },
       required: ["verdict", "reason_code", "regime"],
     },
   },
   {
-    name: "fapony_stats",
+    name: "mem_find",
     description:
-      "Query accumulated run statistics: pass/stall rates, quality scores, " +
-      "breakdown by model/grade/worktree. Returns StatsData shape. " +
-      "With mode='verdict', returns the model to pay for each regime — the " +
-      "Pareto frontier of quality vs tokens/pass, one line per regime (or the " +
-      "full frontier/dominated/candidates breakdown for one regime). This is " +
-      "the answer the ledger exists to give; call it before assuming which " +
-      "model fits a task. With group_by='reason_code'|'plan'|'file', returns " +
-      "top-N rows for that grouping (recurring failure signatures / per-plan " +
-      "totals / per-file gate-vs-fail counts) instead of the full shape.",
+      "Search the project's mem log (.fapony/.memory/log*.jsonl — decisions, " +
+      "bugs, notes, and bookkeeping kinds alike; NO default kind filter). " +
+      "Read-only. Answer 'what was ever decided about this file?' in one call " +
+      "BEFORE editing: pass files[] (repo-relative). Matches the row's stored " +
+      "files[], falling back to a substring of text/spec/ref for rows written " +
+      "without it — a row that names the file nowhere cannot be found. " +
+      "memDir shows which log dir was resolved (walked up from the given " +
+      "worktree — in a monorepo pass the app directory to read its log). " +
+      "Returns {rows, total, filesFound, " +
+      "skipped, memDir}: memDir:null = no mem at all, not 'nothing matched'.",
     inputSchema: {
       type: "object" as const,
       properties: {
-        mode: {
+        worktree: {
           type: "string",
-          enum: ["verdict"],
           description:
-            "'verdict' ranks models by quality vs tokens/pass instead of listing " +
-            "raw counts — the leaderboard, not the ledger dump. Models below " +
-            "n=5 are shown separately and never picked as the answer; a model " +
-            "tried once at top quality does not get to define the frontier.",
+            "Absolute path (git rev-parse --show-toplevel) — required; " +
+            "scope of the mem log to read",
         },
-        regime: {
-          type: "string",
-          enum: ["code", "fix", "review", "plan", "inquiry", "test"],
+        files: {
+          type: "array",
+          items: { type: "string" },
           description:
-            "With mode='verdict', narrows to one regime's full frontier " +
-            "(dominated models + candidates too). Omitted = one summary line " +
-            "per regime.",
+            "Repo-relative paths — matched against the row's files[], else its text",
         },
-        json: {
-          type: "boolean",
+        text: {
+          type: "string",
+          description: "Substring, case-insensitive",
+        },
+        kind: {
+          type: "array",
+          items: { type: "string" },
           description:
-            "If true, return raw JSON StatsData. If false (default), return human-readable text. Ignored when mode='verdict' (always text).",
+            "Filter by kind (decision/note/bug/close/…). Omit = every kind — " +
+            "no default filter",
         },
-        group_by: {
+        since: {
           type: "string",
-          enum: ["reason_code", "plan", "file"],
-          description:
-            "Optional grouping: top-N reason_code counts, per-plan totals, or " +
-            "per-file risk (graded touches vs fails) from real gate events.",
+          description: "ISO date — only rows at or after this time",
         },
-        top: {
+        limit: {
           type: "number",
-          description: "Max rows returned with group_by (default 10).",
+          description:
+            "Max rows returned (default 20) — total still counts all matches",
         },
+      },
+      required: ["worktree"],
+    },
+  },
+  {
+    name: "mem_add",
+    description:
+      "Append a mem row (decision/bug/note/next/hold) with files[]. files is " +
+      "required — a row that does not name the file is unfindable when you " +
+      "touch that file. Returns the row's id, kind, files, and timestamp.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
         worktree: {
           type: "string",
           description:
-            "Scope a query (verdict mode, group_by, or the default view) to one worktree path (absolute). Defaults to the repo the server is running in.",
+            "Absolute path (git rev-parse --show-toplevel) — required",
         },
-        all: {
-          type: "boolean",
+        kind: {
+          type: "string",
+          enum: ["next", "bug", "decision", "note", "hold"],
+          description:
+            "Row kind: decision=locked choice, bug=broken thing, note=state " +
+            "next session needs, next=pending work, hold=blocked on spec",
+        },
+        text: {
+          type: "string",
           description:
-            "Ignore the default worktree scope and report every project at once. Off by default: averaging several projects reads as 'in this project' while being no such thing, and it is the largest payload this tool returns.",
+            "Standalone text — read months later, no conversation context",
+        },
+        files: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Repo-relative paths this row is about — required, non-empty",
+        },
+        spec: {
+          type: "string",
+          description: "Optional spec/plan .md path",
         },
       },
-      required: [],
+      required: ["worktree", "kind", "text", "files"],
     },
   },
   {
@@ -194,116 +218,4 @@ export const TOOLS = [
       required: [],
     },
   },
-  {
-    name: "project_health_context",
-    description:
-      "Known-patterns block for files[]: recurring fail reasons, escalated runs, " +
-      "and round-1-pass shapes from real run history. Worth a call when you are " +
-      "about to touch a file that has history — a long-lived file, one you have " +
-      "not seen before, or one a previous attempt already failed on. The unit is " +
-      "touched files, not a plan; a bug fix with no plan file still qualifies. " +
-      "Returns nothing when there is no history (most files); short plain-text " +
-      "block, framed as watch-fors, not constraints.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        worktree: {
-          type: "string",
-          description:
-            "Scope to one worktree path (absolute). Global across worktrees when omitted.",
-        },
-        files: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Filter findings to only those related to these files. " +
-            "Matches against stored gate event files and note text.",
-        },
-      },
-      required: [],
-    },
-  },
-  {
-    name: "mem_find",
-    description:
-      "Search the project's mem log (.fapony/.memory/log*.jsonl — decisions, " +
-      "bugs, notes, and bookkeeping kinds alike; NO default kind filter). " +
-      "Read-only. Answer 'what was ever decided about this file?' in one call " +
-      "BEFORE editing: pass files[] (repo-relative) to match rows mentioning " +
-      "them. mem never stored files[], so match is substring over text/spec/ref " +
-      "— a row that never names the file cannot be found (limit of the data, " +
-      "not the query). In a monorepo only the log of the app guessed from the " +
-      "worktree name is read; memDir in the result shows which one. Returns " +
-      "{rows, total, filesFound, skipped, memDir}: total is the match count " +
-      "before limit, memDir:null means no mem at all (not 'nothing matched').",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        worktree: {
-          type: "string",
-          description:
-            "Absolute path (git rev-parse --show-toplevel) — required; " +
-            "scope of the mem log to read",
-        },
-        files: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Repo-relative paths — match rows whose text/spec/ref mentions them (substring)",
-        },
-        text: {
-          type: "string",
-          description: "Substring, case-insensitive",
-        },
-        kind: {
-          type: "array",
-          items: { type: "string" },
-          description:
-            "Filter by kind (decision/note/bug/close/…). Omit = every kind — " +
-            "no default filter",
-        },
-        since: {
-          type: "string",
-          description: "ISO date — only rows at or after this time",
-        },
-        limit: {
-          type: "number",
-          description:
-            "Max rows returned (default 20) — total still counts all matches",
-        },
-      },
-      required: ["worktree"],
-    },
-  },
-  {
-    name: "plan_list",
-    description:
-      "List pending plan files grouped by state — active / blocked / " +
-      "untouched / superseded / trackers — each with title and last-run " +
-      "status joined from fapony run history, plus a count of archived " +
-      "ones. Not a raw directory listing: answers 'what is left, what is " +
-      "waiting on what, what should come next'. State comes from optional " +
-      "plan frontmatter (kind: tracker | status: active|blocked|superseded " +
-      "| blocked_by: | blocks: | superseded_by:); a plan without " +
-      "frontmatter is grouped by run history alone (attempted = active, " +
-      "never attempted = untouched). Within active, whatever unblocks the " +
-      "most other plans is listed first.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        worktree: {
-          type: "string",
-          description: "Absolute path to the project's git worktree",
-        },
-        format: {
-          type: "string",
-          enum: ["json", "markdown"],
-          description:
-            "'markdown' renders the groups as a checklist to paste or read; " +
-            "default 'json'.",
-        },
-      },
-      required: ["worktree"],
-    },
-  },
 ];

package/src/mcp/tools/mem.ts

@@ -1,13 +1,20 @@
-// src/mcp/tools/mem.ts — mem_find: read-only search over the project's mem log
+// src/mcp/tools/mem.ts — mem_find (read) + mem_add (write)
 //
-// "writable ≠ readable back" — the write side works from the CLI with no MCP
-// (vela: 2,920 rows / 49 days); what was missing is "which rows are about the
-// files I am about to touch". Read-only over readMemLog (PLAN-mem-mcp chunk 2).
-//
-// No default kind filter — chunk 0 chose A: every kind is still live, so
-// filtering `synced`/`next`/`claim` by default would be enforcing prose that
-// was already retracted.
+// "writable ≠ readable back" — the write side was CLI-only until now; what was
+// missing is letting an agent append a mem row mid-session without spawning a
+// shell.  files[] is required on the write side: a row that does not name the
+// file is unfindable when you touch that file (fill rate 26% CLI-flag vs 88%
+// MCP-required — schema wins over prose every time, see CLAUDE.md rule 9).
 
+import { openRows } from "../../mem/selectors.js";
+import {
+  initStore,
+  KINDS,
+  nextId,
+  put,
+  rows,
+  type WorkKind,
+} from "../../mem/store.js";
 import { type MemRow, readMemLog, resolveMemDir } from "../../memory.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
 
@@ -39,11 +46,15 @@ export function memFind(args: {
     rows = rows.filter((r) => r.text.toLowerCase().includes(needle));
   }
   if (args.files && args.files.length > 0) {
-    // mem never stored files[] — match is substring over text/spec/ref.
-    // Low recall by nature (spec §5.4): a row that never names the file
-    // cannot be found — a limit of the data, not of the query.
+    // Rows written by `mem add --files` carry files[] — match that first.
+    // Older rows (and any row whose author skipped --files) have none, so the
+    // text/spec/ref substring stays as the fallback: low recall by nature,
+    // a limit of the data rather than of the query (spec §5.4).
     const paths = args.files.map((f) => f.toLowerCase());
     rows = rows.filter((r) => {
+      const stored = (r.files ?? []).map((f) => f.toLowerCase());
+      if (stored.some((f) => paths.some((p) => f === p || f.endsWith(`/${p}`))))
+        return true;
       const hay = `${r.text}\n${r.spec ?? ""}\n${r.ref ?? ""}`.toLowerCase();
       return paths.some((p) => hay.includes(p));
     });
@@ -93,3 +104,134 @@ export function toolMemFind(args: Record<string, unknown>): ToolResult {
 
   return jsonResult(memFind({ worktree, files, text, kind, since, limit }));
 }
+
+// --- mem_add ---
+
+export interface MemAddResult {
+  id: string;
+  kind: string;
+  text: string;
+  files: string[];
+  spec?: string;
+  ts: string;
+}
+
+const CAP_NEXT = 15;
+const CAP_HOLD = 10;
+
+export function memAdd(args: {
+  worktree: string;
+  kind: string;
+  text: string;
+  files: string[];
+  spec?: string;
+}): MemAddResult {
+  if (!KINDS.includes(args.kind as WorkKind)) {
+    throw new Error(
+      `kind must be one of ${KINDS.join("|")} — got "${args.kind}"`,
+    );
+  }
+  if (args.files.length === 0) {
+    throw new Error("files must contain at least one path");
+  }
+  if (!args.text.trim()) {
+    throw new Error("text is required and must not be empty");
+  }
+  // CLI cmdAdd rejects hold without a spec (write.ts) — keep the two writers
+  // in lockstep: without a spec a hold can never be resolved by rotate.
+  if (args.kind === "hold" && !args.spec) {
+    throw new Error("hold requires a spec — pass spec: <path/to/SPEC.md>");
+  }
+
+  initStore(args.worktree);
+  const all = rows();
+
+  // Cap check — matches CLI cmdAdd behaviour
+  if (args.kind === "next" && !process.env.MEM_FORCE) {
+    const openNext = openRows(all).filter((r) => r.kind === "next").length;
+    if (openNext >= CAP_NEXT) {
+      throw new Error(
+        `open next ${openNext}/${CAP_NEXT} is full — close an old one first`,
+      );
+    }
+  }
+  if (args.kind === "hold" && !process.env.MEM_FORCE) {
+    const openHold = openRows(all).filter((r) => r.kind === "hold").length;
+    if (openHold >= CAP_HOLD) {
+      throw new Error(
+        `open hold ${openHold}/${CAP_HOLD} is full — close/release an old one first`,
+      );
+    }
+  }
+
+  const id = nextId(all);
+  const ts = new Date().toISOString();
+  put({
+    id,
+    kind: args.kind as WorkKind,
+    text: args.text,
+    spec: args.spec,
+    files: args.files,
+  });
+
+  return {
+    id,
+    kind: args.kind,
+    text: args.text,
+    files: args.files,
+    spec: args.spec,
+    ts,
+  };
+}
+
+export function toolMemAdd(args: Record<string, unknown>): ToolResult {
+  const worktree =
+    typeof args.worktree === "string" ? args.worktree.trim() : "";
+  if (!worktree) {
+    return errorResult(
+      "worktree is required and must be an absolute path " +
+        "(git rev-parse --show-toplevel)",
+    );
+  }
+  if (!worktree.startsWith("/")) {
+    return errorResult(`worktree must be an absolute path, got: ${worktree}`);
+  }
+
+  const kind = typeof args.kind === "string" ? args.kind.trim() : "";
+  if (!kind) {
+    return errorResult(`kind is required — one of ${KINDS.join("|")}`);
+  }
+  if (!KINDS.includes(kind as WorkKind)) {
+    return errorResult(
+      `kind must be one of ${KINDS.join("|")} — got "${kind}"`,
+    );
+  }
+
+  const text = typeof args.text === "string" ? args.text.trim() : "";
+  if (!text) {
+    return errorResult("text is required and must not be empty");
+  }
+
+  const files = Array.isArray(args.files)
+    ? args.files
+        .filter((f): f is string => typeof f === "string" && f.length > 0)
+        .map((f) => f.trim().replace(/^\.\//, ""))
+    : [];
+  if (files.length === 0) {
+    return errorResult(
+      "files is required and must contain at least one repo-relative path",
+    );
+  }
+
+  const spec =
+    typeof args.spec === "string" && args.spec.trim().endsWith(".md")
+      ? args.spec.trim()
+      : undefined;
+
+  try {
+    const result = memAdd({ worktree, kind, text, files, spec });
+    return jsonResult(result);
+  } catch (e) {
+    return errorResult(e instanceof Error ? e.message : String(e));
+  }
+}

package/src/mcp/transport.ts

@@ -8,11 +8,9 @@ import { mergeBytesByTool, type UsageDetail } from "../session/index.js";
 import { getServerSha } from "./primitives.js";
 import {
   TOOLS,
-  toolFaponyStats,
+  toolMemAdd,
   toolMemFind,
   toolPassiveUsage,
-  toolPlanList,
-  toolProjectHealthContext,
   toolVerdictSubmit,
 } from "./tools/index.js";
 import { errorResult, type ToolResult } from "./types.js";
@@ -112,7 +110,7 @@ function writeStatuslineCache(toolResult: ToolResult): void {
 
 const MCP_PROTOCOL_VERSION = "2025-03-26";
 const SERVER_NAME = "fapony-handcheck";
-const SERVER_VERSION = "0.1.3";
+const SERVER_VERSION = "0.2.0";
 
 // --- JSON-RPC dispatch ---
 
@@ -154,21 +152,15 @@ function dispatchToolCall(params: {
     case "verdict_submit":
       result = toolVerdictSubmit(args);
       break;
-    case "fapony_stats":
-      result = toolFaponyStats(args);
-      break;
     case "fapony_usage":
       result = toolPassiveUsage(args);
       break;
-    case "project_health_context":
-      result = toolProjectHealthContext(args);
-      break;
-    case "plan_list":
-      result = toolPlanList(args);
-      break;
     case "mem_find":
       result = toolMemFind(args);
       break;
+    case "mem_add":
+      result = toolMemAdd(args);
+      break;
     default:
       return errorResult(`unknown tool: ${params.name}`);
   }