fapony 0.4.0 → 0.5.0

package/src/adapters/mcp/tools/mem.ts

@@ -23,6 +23,8 @@ export interface MemFindResult {
   filesFound: number;
   skipped: number;
   memDir: string | null;
+  /** Present only when a key query missed — every distinct key in the log. */
+  knownKeys?: string[];
 }
 
 export function memFind(args: {
@@ -33,6 +35,7 @@ export function memFind(args: {
   since?: string;
   limit?: number;
   open?: boolean;
+  key?: string;
 }): MemFindResult {
   // Query logic lives in the shared engine (src/mem/engine.ts) — this wrapper
   // owns only the read (readMemLog sees live + rotated archives via its loose
@@ -40,22 +43,24 @@ export function memFind(args: {
   // omitting kind returns every kind (locked by test). CLI cmdFind calls the
   // same engine with its own bookkeeping exclude.
   const read = readMemLog(args.worktree);
-  const { rows: matched, total } = engineFind(read.rows, {
+  const found = engineFind(read.rows, {
     text: args.text,
     files: args.files,
     kind: args.kind,
     sinceIso: args.since,
+    key: args.key,
     limit: args.limit,
     open: args.open,
   });
   return {
-    rows: matched,
-    total,
+    rows: found.rows,
+    total: found.total,
     filesFound: read.filesFound,
     skipped: read.skipped,
     // memDir separates "no mem at all" from "nothing matched" (spec §3) and
     // makes the monorepo single-log limit visible (spec §5.1).
     memDir: resolveMemDir(args.worktree),
+    ...(found.knownKeys ? { knownKeys: found.knownKeys } : {}),
   };
 }
 
@@ -93,9 +98,18 @@ export function toolMemFind(args: Record<string, unknown>): ToolResult {
   }
   const limit = typeof args.limit === "number" ? args.limit : undefined;
   const open = typeof args.open === "boolean" ? args.open : undefined;
+  // Shape gate like mem_add — a non-string key must not coerce to undefined
+  // (silent drop = reject-without-saying). Pattern is NOT checked here: find
+  // answers a wrong-pattern key with knownKeys, not a reject (SPEC fail example).
+  if (args.key !== undefined && typeof args.key !== "string") {
+    return errorResult(
+      'key must be a string matching [a-z0-9-]{3,40} — e.g. "fix-stop-dedupe"',
+    );
+  }
+  const key = typeof args.key === "string" ? args.key : undefined;
 
   return jsonResult(
-    memFind({ worktree, files, text, kind, since, limit, open }),
+    memFind({ worktree, files, text, kind, since, limit, open, key }),
   );
 }
 
@@ -112,6 +126,7 @@ export function memAdd(args: {
   text: string;
   files: string[];
   spec?: string;
+  key?: string;
 }): MemAddResult {
   initStore(args.worktree);
   return engineAdd({
@@ -119,6 +134,7 @@ export function memAdd(args: {
     text: args.text,
     files: args.files,
     spec: args.spec,
+    key: args.key,
   });
 }
 
@@ -166,8 +182,17 @@ export function toolMemAdd(args: Record<string, unknown>): ToolResult {
       ? args.spec.trim()
       : undefined;
 
+  // Shape gate here, pattern check in engineAdd — a non-string key must not
+  // slip through as undefined (silent drop = reject-without-saying, SPEC §Validation).
+  if (args.key !== undefined && typeof args.key !== "string") {
+    return errorResult(
+      'key must be a string matching [a-z0-9-]{3,40} — e.g. "fix-stop-dedupe"',
+    );
+  }
+  const key = typeof args.key === "string" ? args.key : undefined;
+
   try {
-    const result = memAdd({ worktree, kind, text, files, spec });
+    const result = memAdd({ worktree, kind, text, files, spec, key });
     return jsonResult(result);
   } catch (e) {
     return errorResult(e instanceof Error ? e.message : String(e));

package/src/adapters/mcp/transport.ts

@@ -19,7 +19,7 @@ import { errorResult, type ToolResult } from "./types.js";
 
 const SERVER_INSTRUCTIONS = `fapony records decisions, bugs, and notes about this project so the next session (or the next agent) knows what happened and what to watch out for.
 
-When you finish a unit of work, record a mem row: fapony mem add <decision|bug|note> "what happened" --files <files> <path/to/PLAN.md>. files[] is required — a row without it is unfindable when you touch that file next session.
+When you finish a unit of work, record a mem row: fapony mem add <decision|bug|note> "what happened" --files <files> <path/to/PLAN.md>. files[] is required — a row without it is unfindable when you touch that file next session. Name a known problem with --key <a-z0-9-id> and recall every row for it via mem_find key.
 
 worktree must be the absolute path (git rev-parse --show-toplevel): every query scopes by it, so a bare name or none files the row where nothing reads it, and nothing errors to say so. Write the note standalone — it is read months later with no access to this conversation.
 

package/src/core/hint-log.ts

@@ -30,7 +30,17 @@ export function hintLogPath(worktree: string): string {
 export interface HintFireRow {
   ts: string;
   worktree: string;
-  surface: "read" | "debt" | "mem" | "commit" | "edit";
+  surface:
+    | "read"
+    | "debt"
+    | "mem"
+    | "commit"
+    | "edit"
+    | "open-bug"
+    | "handoff-would-block"
+    | "handoff-pass"
+    | "commit-block"
+    | "bug-block";
   file: string | null;
   count: number;
   ids?: string[];
@@ -62,6 +72,11 @@ export interface HintImpact {
     mem: number;
     commit: number;
     edit: number;
+    "open-bug": number;
+    "handoff-would-block": number;
+    "handoff-pass": number;
+    "commit-block": number;
+    "bug-block": number;
   };
   debt: { shown: number; resolved: number; unknown: number };
   window: string | null;

package/src/core/mem-log.ts

@@ -22,8 +22,22 @@ export interface MemRow {
   ref?: string;
   /** Files the row is about — written by `mem add --files` (PLAN-convention-debt chunk 3). */
   files?: string[];
+  /** Problem identity, distinct from kind (action) and files[] (place) — written by `mem add --key` (PLAN-mem-keys chunk 1). */
+  key?: string;
+  /** Row schema version: 2 = may carry `key`; absent = v:1 legacy row, read as-is. */
+  v?: number;
 }
 
+/** One mem-row text budget for any hint/seed surface that shows a row (was context-data's private const). */
+export const MEM_TEXT_MAX = 120;
+
+/**
+ * The only accepted shape of a mem row `key` — problem identity, not action
+ * (kind) and not place (files[]). Lives here in core so CLI and MCP validate
+ * through one regex (PLAN-unify-mem-engine: one engine, both surfaces).
+ */
+export const KEY_RE = /^[a-z0-9-]{3,40}$/;
+
 interface RawMemRow {
   ts?: string;
   agent?: string;
@@ -33,6 +47,8 @@ interface RawMemRow {
   id?: string;
   ref?: string;
   files?: unknown;
+  key?: unknown;
+  v?: unknown;
 }
 
 /**
@@ -319,6 +335,8 @@ export function readMemLog(
         ...(Array.isArray(parsed.files)
           ? { files: parsed.files.filter((f) => typeof f === "string") }
           : {}),
+        ...(typeof parsed.key === "string" ? { key: parsed.key } : {}),
+        ...(typeof parsed.v === "number" ? { v: parsed.v } : {}),
       });
     }
   }

package/src/debt/cli.ts

@@ -13,7 +13,7 @@ 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
+  --id a,b          show only these conventions
   --where <path>    narrow scope to files under this path
   --all             show all zones (default: cap at ${ZONE_CAP})
   --json            output raw JSON
@@ -68,7 +68,7 @@ export function cmdDebt(args: string[]): void {
   let path: string | undefined;
   let filesMode: string[] | null = null;
   let json = false;
-  let filterId: string | undefined;
+  let filterIds: string[] = [];
   let wherePath: string | undefined;
   let showAll = false;
   for (let i = 0; i < args.length; i++) {
@@ -80,14 +80,17 @@ export function cmdDebt(args: string[]): void {
         process.exit(1);
       }
       i++;
-      filesMode = v
+      // Accumulate, never reassign: a repeated --files grows the set
+      // (PLAN-comma-x chunk 2 — last-wins was silent data loss).
+      const parts = v
         .split(",")
         .map((s) => s.trim())
         .filter(Boolean);
-      if (filesMode.length === 0) {
+      if (parts.length === 0) {
         console.error(`fapony debt: --files needs at least one path\n${USAGE}`);
         process.exit(1);
       }
+      filesMode = [...(filesMode ?? []), ...parts];
     } else if (a === "--id") {
       const v = args[i + 1];
       if (!v || v.startsWith("--")) {
@@ -95,7 +98,17 @@ export function cmdDebt(args: string[]): void {
         process.exit(1);
       }
       i++;
-      filterId = v;
+      // Comma list, same shape as --files: ids are slugs, an id can't hold
+      // a comma, so any comma splits (PLAN-comma-x). Repeats accumulate too.
+      const parts = v
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      if (parts.length === 0) {
+        console.error(`fapony debt: --id needs a convention id\n${USAGE}`);
+        process.exit(1);
+      }
+      filterIds = [...filterIds, ...parts];
     } else if (a === "--where") {
       const v = args[i + 1];
       if (!v || v.startsWith("--")) {
@@ -171,12 +184,14 @@ export function cmdDebt(args: string[]): void {
   }
   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);
+  // --id filter: keep only the named conventions (comma list allowed)
+  if (filterIds.length > 0) {
+    report.entries = report.entries.filter((e) =>
+      filterIds.includes(e.conv.id),
+    );
+    report.declared = report.declared.filter((c) => filterIds.includes(c.id));
     report.checkedCount = 0; // not relevant when filtering
-    report.dropped = report.dropped.filter((d) => d.id === filterId);
+    report.dropped = report.dropped.filter((d) => filterIds.includes(d.id));
   }
 
   // --where filter: narrow file lists to paths under the given prefix

package/src/hook.ts

@@ -7,6 +7,7 @@
 
 export {
   BUG_MARKERS,
+  bugDedupeKey,
   bugSignalFromTranscript,
   COMMIT_HINT_MIN_COMMITS,
   type CommitHintInput,
@@ -19,12 +20,15 @@ export {
   cmdHookStop,
   commitHintFor,
   computeHintImpact,
+  countTicks,
   cursorTranscriptPath,
+  decideHandoff,
   decideStop,
   type EditHintInput,
   type EditTrackRow,
   editHintFor,
   editTrackPath,
+  fileAtRevision,
   GIT_AUTONOMY_COMMIT_POLICY,
   GIT_AUTONOMY_PLUGIN_FILE,
   GIT_AUTONOMY_PLUGIN_NAME,
@@ -35,15 +39,24 @@ export {
   type GitAutonomyStatus,
   type GitAutonomyToolRewrite,
   gitAutonomyStatus,
+  type HandoffDecision,
+  type HandoffPlanFile,
   type HintFireRow,
   type HintImpact,
+  handoffBaseSha,
+  handoffBlockMessage,
+  handoffDedupeKey,
   hasBugMarker,
+  hasHandoffLiteral,
   hintLogDir,
   hintLogPath,
   hookTsMs,
   isBugfixCommit,
   isCodexPayload,
   isCursorPayload,
+  isPlanPath,
+  memHasHandoffForPlan,
+  mergeStopReasons,
   mvGuardDecision,
   type NormalizedStopInput,
   normalizeStopInput,
@@ -64,9 +77,11 @@ export {
   SESSION_START_MAX_CHARS,
   type StopClient,
   sessionKey,
+  sessionPlanFiles,
   sessionStartContext,
   stopBlockedBefore,
   stopBlockPath,
+  stopBlockSurface,
   stopOutput,
   utcStamp,
   worktreeKey,

package/src/install/antigravity.ts

@@ -5,9 +5,10 @@
 // Skills path). No hooks in the first phase — Antigravity's hook surface is
 // still evolving.
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { defaultCheckCmd } from "../setup.js";
 import { agentsSkillsDir, linkSkills, reportSkills } from "./skills.js";
 import {
   CURSOR_MCP_ENTRY,
@@ -49,14 +50,20 @@ export function cmdInstallAntigravity(
 ): void {
   const exitFn = deps.exit ?? defaultExit;
   const getHome = deps.homedir ?? homedir;
-  const geminiDir = findGeminiDir(getHome);
+  const checkCmd = deps.checkCmd ?? defaultCheckCmd;
+  let geminiDir = findGeminiDir(getHome);
 
   if (!geminiDir) {
-    console.error(
-      `Antigravity not found — open Antigravity at least once to create ~/.gemini`,
-    );
-    exitFn(1);
-    return;
+    // Detect signal #2: the `agy` CLI on PATH — installed but never launched,
+    // so ~/.gemini doesn't exist yet; the write path below creates it.
+    if (!checkCmd("agy")) {
+      console.error(
+        `Antigravity not found — open Antigravity at least once to create ~/.gemini (or put the agy CLI on PATH)`,
+      );
+      exitFn(1);
+      return;
+    }
+    geminiDir = join(getHome(), ".gemini");
   }
 
   // --- 1. MCP server (mcpServers.fapony in ~/.gemini/config/mcp_config.json) ---
@@ -99,6 +106,10 @@ export function cmdInstallAntigravity(
         `── dry-run: would ${mcpIsNew ? "create" : "write"} ${mcpPath}${mcpIsNew ? "" : ` (mcpServers.${MCP_KEY})`} ──`,
       );
     } else {
+      // Escape hatch (plan §5): ~/.gemini/config may not exist yet — either
+      // the app never got as far as its config dir, or agy-on-PATH created
+      // nothing. Recursive mkdir is idempotent and non-destructive.
+      mkdirSync(configDir, { recursive: true });
       writeFileSync(mcpPath, `${JSON.stringify(after, null, 2)}\n`, "utf-8");
       console.error(`✓ added mcpServers.${MCP_KEY} to ${mcpPath}`);
       console.error(`  restart Antigravity to load the MCP server`);

package/src/install/detect.ts

@@ -1,7 +1,7 @@
 // src/install/detect.ts — detect which MCP clients are installed on this machine.
 //
 // Signal per client:
-//   antigravity = ~/.gemini exists (the app creates it on first run)
+//   antigravity = ~/.gemini exists (the app creates it on first run) OR `agy` on PATH
 //   claude      = `command -v claude` (CLI on PATH)
 //   cursor      = ~/.cursor exists (the app creates it on first run)
 //   opencode    = ~/.config/opencode/{opencode.json,opencode.jsonc} exists
@@ -28,14 +28,15 @@ export interface DetectedClient {
  * Returns one entry per platform, ordered: antigravity, claude, cursor, opencode, zcode, codex.
  *
  * Uses resolvers from each provider (file/dir-exists check) for
- * antigravity/cursor/opencode/zcode/codex, and `command -v claude` for claude — all
- * through injected deps for testability.
+ * antigravity/cursor/opencode/zcode/codex, and `command -v claude`/`command -v agy`
+ * for claude/antigravity — all through injected deps for testability.
  */
 export function detectClients(deps: InstallDeps = {}): DetectedClient[] {
   const getHome = deps.homedir ?? homedir;
   const checkCmd = deps.checkCmd ?? defaultCheckCmd;
 
   const claude = checkCmd("claude");
+  const agy = checkCmd("agy");
 
   const geminiDir = findGeminiDir(getHome);
   const cursorDir = findCursorDir(getHome);
@@ -46,10 +47,12 @@ export function detectClients(deps: InstallDeps = {}): DetectedClient[] {
   return [
     {
       platform: "antigravity",
-      installed: geminiDir !== null,
+      installed: geminiDir !== null || agy,
       why: geminiDir
         ? `dir at ${geminiDir}`
-        : "no ~/.gemini directory (open Antigravity once)",
+        : agy
+          ? "agy CLI on PATH"
+          : "no ~/.gemini directory (open Antigravity once)",
     },
     {
       platform: "claude",

package/src/install/opencode.ts

@@ -271,6 +271,9 @@ export const FaponyReadHint = async ({ directory }) => {
           if (ctx.memLines.length > 0) {
             recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "mem", file: rel, count: ctx.memLines.length });
           }
+          if (ctx.openBugIds.length > 0) {
+            recordHintFire({ ts: new Date().toISOString(), worktree: ctx.worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });
+          }
         }
       } catch {
         // a hint must never break a read
@@ -412,6 +415,9 @@ export const FaponyEditHint = async ({ directory }) => {
               if (ctx?.memLines?.length) {
                 recordHintFire({ ts: new Date().toISOString(), worktree, surface: "mem", file: rel, count: ctx.memLines.length });
               }
+              if (ctx?.openBugIds?.length) {
+                recordHintFire({ ts: new Date().toISOString(), worktree, surface: "open-bug", file: rel, count: ctx.openBugIds.length, ids: ctx.openBugIds });
+              }
             }
           } catch {
             // best-effort

package/src/install.ts

@@ -1,4 +1,4 @@
-// src/install.ts — `fapony install --platform opencode|claude|cursor|zcode|codex` command.
+// src/install.ts — `fapony install --platform antigravity|agy|opencode|claude|cursor|zcode|codex` command.
 // opencode: adds mcp.fapony config to ~/.config/opencode/opencode.json or opencode.jsonc.
 // claude: shells out to `claude mcp add` (never parses/writes ~/.claude.json directly).
 // cursor: writes mcpServers.fapony to ~/.cursor/mcp.json directly and merges the
@@ -59,7 +59,9 @@ export async function cmdInstall(
   args: string[],
   deps: InstallDeps = {},
 ): Promise<void> {
-  const platform = args.find((a) => !a.startsWith("--"));
+  const platformArg = args.find((a) => !a.startsWith("--"));
+  // `agy` = Antigravity's CLI name — alias, same provider.
+  const platform = platformArg === "agy" ? "antigravity" : platformArg;
   const dryRun = args.includes("--dry-run");
   const installAll = args.includes("--all");
   // Opt-in only: the git-autonomy rewrite is an opinion (commit-as-you-go),
@@ -96,10 +98,10 @@ export async function cmdInstall(
   }
   if (platform !== undefined) {
     console.error(
-      `usage: fapony install --platform antigravity|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy] [--plugins-only]`,
+      `usage: fapony install --platform antigravity|agy|opencode|claude|cursor|zcode|codex [--dry-run] [--git-autonomy] [--plugins-only]`,
     );
     console.error(
-      `  supported platforms: antigravity, opencode, claude, cursor, zcode, codex`,
+      `  supported platforms: antigravity (agy), opencode, claude, cursor, zcode, codex`,
     );
     (deps.exit ?? defaultExit)(1);
     return;

package/src/mem/commands/plan.ts

@@ -190,6 +190,68 @@ export const collectDepIssues = (active: string[]): string[] => {
   return issues;
 };
 
+// W1: status header says not-started but chunks are ticked.
+// W2: all chunks ticked but header never marked shipped.
+// WARN-level only — counted separately from issues, never changes exit code.
+//
+// Vocab measured from .fapony/{plan,done}/*.md (2026-09-23):
+//   in-progress 8 · done 4 · shipped/✅ shipped 6 · draft 1
+//   frontmatter status: shipped 8 · blocked 2
+const NOT_STARTED =
+  /(?:^|\n)>\s*\*?\*?Status:?\*?\*?\s+.*(?:draft|drafted|not[\s-]started)/i;
+const SHIPPED_RE =
+  /(?:^|\n)>\s*✅|(?:^|\n)>\s*\*?\*?Status:?\*?\*?\s+.*(?:shipped|done)/i;
+const FM_SHIPPED = /^status:\s*shipped\b/m;
+
+export const collectDriftWarns = (active: string[]): string[] => {
+  const warns: string[] = [];
+  for (const f of active) {
+    const fm = parsePlanFrontmatter(f);
+    // Skip plans whose frontmatter already says shipped/blocked/superseded or
+    // is a tracker — these have their own handling elsewhere.
+    if (FM_SHIPPED.test("") && fm.status === "shipped") continue;
+    if (fm.status === "blocked" || fm.status === "superseded") continue;
+    if (fm.kind === "tracker") continue;
+    // frontmatter status: shipped = already done
+    if (fm.status === "shipped") continue;
+
+    const text = readFileSync(f, "utf8");
+    const relPath = relative(planBase, f);
+    const { checked, unchecked } = countFirstSection(f);
+    const total = checked + unchecked;
+    if (total === 0) continue;
+
+    // W1: header says not-started but chunks are ticked
+    const head = text.slice(0, 2048);
+    if (
+      checked > 0 &&
+      NOT_STARTED.test(head) &&
+      !SHIPPED_RE.test(head) &&
+      !FM_SHIPPED.test(text)
+    ) {
+      // Extract the status value for the message
+      const statusMatch = />\s*\*?\*?Status:?\*?\*?\s+(.+)/i.exec(head);
+      const statusVal = statusMatch?.[1]?.replace(/\*\*/g, "").trim() ?? "?";
+      warns.push(
+        `${relPath} — status header says "${statusVal}" but ${checked} chunk(s) are ticked\n   fix: update the header to 🚧 in-progress or ✅ shipped`,
+      );
+    }
+
+    // W2: all chunks ticked but header never marked shipped
+    if (
+      checked > 0 &&
+      unchecked === 0 &&
+      !SHIPPED_RE.test(head) &&
+      !FM_SHIPPED.test(text)
+    ) {
+      warns.push(
+        `${relPath} — all ${checked} chunk(s) ticked but header never marked shipped\n   fix: add ✅ shipped to the header or run ${planSweepCmd} ${basename(f)} --apply`,
+      );
+    }
+  }
+  return warns;
+};
+
 // status:blocked with every first-section chunk ticked = deferred doc debt:
 // the work reads done but the plan stays in plan/ forever (shippedNotMoved
 // never lists it — HELD excludes it). Trackers never finish, so they are out.
@@ -735,6 +797,10 @@ export const cmdPlanCheck = (a: string[]) => {
   //    (HELD excludes it), so without this flag it sits in plan/ silently.
   for (const issue of collectBlockedTickedIssues(active)) issues.push(issue);
 
+  // 7) Drift warns — W1 (not-started header + ticks) and W2 (all ticked +
+  //    not shipped). WARN-only: counted separately, never changes exit code.
+  const driftWarns = collectDriftWarns(active);
+
   if (!quiet) {
     console.log(
       `closed chunks: ${closed} · citing a commit: ${citing} · verified: ${verified}`,
@@ -759,6 +825,10 @@ export const cmdPlanCheck = (a: string[]) => {
         );
       }
     }
+    if (driftWarns.length > 0) {
+      console.log(`\n⚠ ${driftWarns.length} drift warning(s) (not blocking):`);
+      for (const w of driftWarns) console.log(`- ${w}`);
+    }
   }
 
   if (issues.length === 0) {