fapony 0.6.2 → 0.7.1

package/skill/review-pony/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: review-pony
-description: Review a plan, PR, diff, or design doc as a verification rather than an opinion — scope first, walk the real path, break it on paper, cite everything. Takes optional effort (low|medium|high|max, widens the walk only, never skips a pass) and --fix (apply CONFIRMED blocker/major findings after the report). Records surviving findings to the project's mem log after the report. Trigger on /review-pony and proactively whenever the user asks to review, audit, scrutinize, sanity-check, or get a second opinion on a plan, PR, diff, design doc, or proposed code change.
+description: Review a plan, PR, diff, or design doc as a verification rather than an opinion — scope first, walk the real path, break it on paper, cite everything. Takes optional effort (low|medium|high|max, widens the walk only, never skips a pass) and --fix (apply CONFIRMED blocker/major findings after the report). Records surviving findings to fael after the report. Trigger on /review-pony and proactively whenever the user asks to review, audit, scrutinize, sanity-check, or get a second opinion on a plan, PR, diff, design doc, or proposed code change.
 ---
 
 # Review Pony
@@ -84,7 +84,7 @@ Write down every place the walk surprises you. Surprises outrank style; chase th
 - `medium` (default) — as written above: full path, callers, tests on the path.
 - `high` — also second-degree callers, and read the tests that exercise them, not just the path.
 - `max` — also grep every changed file for second-degree callers, and re-open
-  every `deferred` line from the last review of this scope, if fapony has one.
+  every `deferred` line from the last review of this scope, if fael has one (`fael find --files <scope>`).
 
 Whatever level stopped you, say so in the one-line coverage note (see Report) — "walked to 1 hop"
 is honest, "walked" alone at `low` is not.
@@ -164,21 +164,20 @@ Fixing changes what actually shipped, not what the review found — re-run pass
 check on the new state before calling it done, but don't re-run the whole review. Record
 what you found, not the post-fix state (the row's text can say the fix was applied).
 
-## After: record what the next session needs (fapony)
+## After: record what the next session needs (fael)
 
 If a blocker/major CONFIRMED finding survived, or the verdict is rework/reject,
-call `mem_add` once, after the report is shown. Don't block the report on it,
+call fael's `add` tool once (or `fael add` in the shell), after the report is shown. Don't block the report on it,
 and don't let it change the report's content. Clean reviews (ship, nit-only
 findings) record nothing — there is nothing the next session needs to find.
 
-kind is `bug` when a finding survived (something is broken), `decision` when
+kind is `issue` when a finding survived (something is broken), `decision` when
 the verdict turns on scope alone (rework/reject from pass 1 — the review locks
 a direction). text is the report's verdict line, standalone — what broke or was
 decided, not that a review happened. files are the repo-relative paths actually
-walked — required, a row without them is unfindable. worktree is the absolute
-path (`git rev-parse --show-toplevel`), never a bare name. Only record into a
-project that already has a mem log — never create one uninvited.
-If `mem_add` errors, say so in one line and move on — never re-run a review
+walked — required, a row without them is unfindable. No fael in this session
+(no tool, no `fael` on PATH) = skip the record, never install it uninvited.
+If `add` errors, say so in one line and move on — never re-run a review
 because storage failed.
 
 ---
@@ -201,10 +200,9 @@ The four passes are the rules. These three are what they fail on in practice:
 ```
 1-4.  scope holds; walked the new gate branch; ran the evidence command — it exits 0
       without running the suite (CONFIRMED: `bun test` with no test dir exits 0)
-post. mem_add(kind="bug",
+post. add(kind="issue",
         text="incremental scan replaces cached history with a delta — cache holds 500, truth 1500",
-        files=["cache.ts", "claude-code.ts"],
-        worktree="/Users/you/Project/fapony/wt-fapony")
+        files=["cache.ts", "claude-code.ts"])
 ```
 
 A report in budget — same review that, narrated, ran five paragraphs:

package/src/adapters/cli.ts

@@ -4,17 +4,14 @@
 // (fapony.ts) calls cliMain(); this file owns all feature imports and the
 // argv routing.
 
-import { existsSync } from "node:fs";
 import { cmdAnalyze } from "../analyze/index.js";
 import { renderUsage, suggestCommand } from "../commands.js";
 import { cmdDebt } from "../debt/cli.js";
 import { cmdDigest } from "../digest/cli.js";
 import { cmdInit } from "../init.js";
-import { cmdInitMem } from "../init-mem.js";
 import { cmdInstall } from "../install.js";
 import { cmdLintBaseline } from "../lint-baseline.js";
-import { cmdMem, MEM_SUBCOMMANDS } from "../mem/index.js";
-import { initStore } from "../mem/store.js";
+import { cmdPlan } from "../plan/index.js";
 import { cmdPriceScan } from "../price/index.js";
 import { cmdReport, cmdReportWeb } from "../report/index.js";
 import { cmdPlanSeed } from "../seed/plan-seed.js";
@@ -24,14 +21,7 @@ import { cmdStats } from "../stats/index.js";
 import { cmdTelemetry } from "../telemetry.js";
 import { cmdUpdate } from "../update.js";
 import { cmdUsageScan, cmdUsageWeb } from "../usage/index.js";
-import {
-  cmdHookEditHint,
-  cmdHookMvGuard,
-  cmdHookReadHint,
-  cmdHookSessionStart,
-  cmdHookStop,
-} from "./hooks/index.js";
-import { cmdMcp } from "./mcp/transport.js";
+import { cmdHookMvGuard } from "./hooks/index.js";
 
 export async function cliMain(): Promise<void> {
   const [cmd, ...a] = process.argv.slice(2);
@@ -57,35 +47,14 @@ export async function cliMain(): Promise<void> {
     cmdStats(a);
   } else if (cmd === "telemetry") {
     await cmdTelemetry(a);
-  } else if (cmd === "init-mem") {
-    cmdInitMem(a);
-  } else if (cmd === "mem") {
-    const memDirIdx = a.indexOf("--mem-dir");
-    let overrideMemDir: string | undefined;
-    let rest = a;
-    if (memDirIdx !== -1) {
-      overrideMemDir = a[memDirIdx + 1];
-      if (!overrideMemDir || overrideMemDir.startsWith("--")) {
-        console.error("fapony mem: --mem-dir needs a value");
-        process.exit(1);
-      }
-      if (!existsSync(overrideMemDir)) {
-        console.error(
-          `fapony mem: --mem-dir path does not exist: ${overrideMemDir}`,
-        );
-        process.exit(1);
-      }
-      rest = a.filter((_, i) => i !== memDirIdx && i !== memDirIdx + 1);
-    }
-    initStore(process.cwd(), overrideMemDir);
-    try {
-      await cmdMem(rest, overrideMemDir);
-    } catch (e) {
-      console.error(
-        `fapony mem: ${e instanceof Error ? e.message : String(e)}`,
-      );
-      process.exit(1);
-    }
+  } else if (cmd === "plan") {
+    cmdPlan(a);
+  } else if (cmd === "mem" || cmd === "mcp" || cmd === "init-mem") {
+    // Memory moved to fael (2026-09-25) — say where, don't just "unknown".
+    console.error(
+      `fapony: memory moved to fael (npm i -g @inonix/fael) — "fapony mem <sub>" → "fael <sub>", plans → "fapony plan [sweep|check]"`,
+    );
+    process.exit(1);
   } else if (cmd === "init") {
     await cmdInit(a);
   } else if (cmd === "install") {
@@ -94,18 +63,8 @@ export async function cliMain(): Promise<void> {
     await cmdSetup();
   } else if (cmd === "update") {
     await cmdUpdate();
-  } else if (cmd === "hook-stop") {
-    await cmdHookStop();
-  } else if (cmd === "hook-read-hint") {
-    await cmdHookReadHint();
-  } else if (cmd === "hook-edit-hint") {
-    await cmdHookEditHint();
   } else if (cmd === "hook-mv-guard") {
     await cmdHookMvGuard();
-  } else if (cmd === "hook-session-start") {
-    await cmdHookSessionStart();
-  } else if (cmd === "mcp") {
-    cmdMcp();
   } else if (cmd === "report") {
     cmdReport(a);
   } else if (cmd === "report-web") {
@@ -118,7 +77,7 @@ export async function cliMain(): Promise<void> {
     cmdUsageWeb(a);
   } else {
     console.error(`fapony: unknown command "${cmd ?? ""}"`);
-    const hints = suggestCommand(cmd ?? "", MEM_SUBCOMMANDS);
+    const hints = suggestCommand(cmd ?? "");
     if (hints.length > 0) {
       console.error(`did you mean ${hints.map((h) => `"${h}"`).join(" or ")}?`);
     }

package/src/adapters/hooks/index.ts

@@ -15,24 +15,7 @@ export {
   sessionKey,
   utcStamp,
 } from "../../core/hook-helpers.js";
-export {
-  BUG_MARKERS,
-  hasBugMarker,
-  isBugfixCommit,
-} from "./bug-markers.js";
 export { computeHintImpact } from "./compute-hint-impact.js";
-export {
-  type ContextLineData,
-  readContextData,
-  readContextLines,
-} from "./context-data.js";
-export {
-  cmdHookEditHint,
-  type EditHintInput,
-  type EditTrackRow,
-  editHintFor,
-  editTrackPath,
-} from "./edit-hint.js";
 export {
   GIT_AUTONOMY_COMMIT_POLICY,
   GIT_AUTONOMY_PLUGIN_FILE,
@@ -48,53 +31,3 @@ export {
   rewriteGitAutonomyTool,
 } from "./git-autonomy.js";
 export { cmdHookMvGuard, mvGuardDecision } from "./mv-guard.js";
-export {
-  COMMIT_HINT_MIN_COMMITS,
-  type CommitHintInput,
-  cmdHookReadHint,
-  commitHintFor,
-  READ_HINT_MIN_BYTES,
-  READ_HINT_MIN_LIMIT,
-  type ReadHintInput,
-  type ReadTrackRow,
-  type RereadHintInput,
-  readHintFor,
-  readTrackPath,
-  rereadHintFor,
-} from "./read-hint.js";
-export {
-  capContext,
-  cmdHookSessionStart,
-  SESSION_START_MAX_CHARS,
-  sessionStartContext,
-} from "./session-start.js";
-export {
-  bugDedupeKey,
-  bugSignalFromTranscript,
-  cmdHookStop,
-  countTicks,
-  cursorTranscriptPath,
-  decideHandoff,
-  decideStop,
-  fileAtRevision,
-  type HandoffDecision,
-  type HandoffPlanFile,
-  handoffBaseSha,
-  handoffBlockMessage,
-  handoffDedupeKey,
-  hasHandoffLiteral,
-  isCodexPayload,
-  isCursorPayload,
-  isPlanPath,
-  memHasHandoffForPlan,
-  mergeStopReasons,
-  type NormalizedStopInput,
-  normalizeStopInput,
-  type RawStopPayload,
-  type StopClient,
-  sessionPlanFiles,
-  stopBlockedBefore,
-  stopBlockPath,
-  stopBlockSurface,
-  stopOutput,
-} from "./stop.js";

package/src/adapters/hooks/mv-guard.ts

@@ -1,5 +1,5 @@
 // src/adapters/hooks/mv-guard.ts — PreToolUse Bash guard: deny a raw `git mv`
-// of a plan file into a done/ directory, point at `fapony mem plan-sweep
+// of a plan file into a done/ directory, point at `fapony plan sweep
 // --apply` instead.
 //
 // Manual `git mv` skips the link rewrite plan-sweep does — that produced two
@@ -23,7 +23,7 @@ export function mvGuardDecision(command: unknown): string | null {
   const [, src] = m;
   return (
     `fapony: raw \`git mv\` of a plan into done/ skips the link rewrite — ` +
-    `run \`fapony mem plan-sweep --apply ${src}\` instead, it moves the file ` +
+    `run \`fapony plan sweep --apply ${src}\` instead, it moves the file ` +
     `and fixes inbound/outbound links together.`
   );
 }

package/src/analyze/discover.ts

@@ -10,7 +10,7 @@ import { join, relative, sep } from "node:path";
 export const SCAN_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".py", ".pyi"]);
 
 // "templates" for the same reason knip.json ignores templates/**: those files
-// ship as a template copied into other repos by `fapony init-mem` and never
+// ship as a template laid down in other repos by `fapony init` and never
 // have real importers here — scanning them produces false wrapper/orphan
 // signals (measured: conventions-seed flagged 8 "wrappers" that were all
 // src/mem/commands/*.ts helpers matched against unrelated identically-

package/src/analyze/index.ts

@@ -6,7 +6,6 @@
 
 export * from "./barrels.js";
 export * from "./blast.js";
-export * from "./cache.js";
 export * from "./cli.js";
 export * from "./criteria.js";
 export * from "./diagnose.js";

package/src/commands.ts

@@ -32,9 +32,9 @@ const GROUP_ORDER: CommandGroup[] = [
 
 export const COMMANDS: CommandInfo[] = [
   {
-    name: "mem",
+    name: "plan",
     group: "core",
-    summary: "project pain memory: decisions, bugs, notes",
+    summary: "where plans stand: next chunk, sweep shipped, check links/shas",
   },
   {
     name: "debt",
@@ -46,7 +46,6 @@ export const COMMANDS: CommandInfo[] = [
     group: "core",
     summary: 'separate "already red" from "I made it red"',
   },
-  { name: "init-mem", group: "core", summary: "delete legacy .memory/ dirs" },
   {
     name: "digest",
     group: "core",
@@ -78,41 +77,16 @@ export const COMMANDS: CommandInfo[] = [
     group: "lookup",
     summary: "write PLAN (+SPEC) with capped sections",
   },
-  {
-    name: "mcp",
-    group: "hooks",
-    summary: "MCP server (stdio JSON-RPC, 3 tools)",
-  },
-  {
-    name: "hook-stop",
-    group: "hooks",
-    summary: "Stop hook: block turns with commits but no mem row",
-  },
-  {
-    name: "hook-read-hint",
-    group: "hooks",
-    summary: "read/re-read annotations",
-  },
-  {
-    name: "hook-edit-hint",
-    group: "hooks",
-    summary: "importer count before editing shape",
-  },
   {
     name: "hook-mv-guard",
     group: "hooks",
     summary: "deny raw git mv of plan files into done/",
   },
-  {
-    name: "hook-session-start",
-    group: "hooks",
-    summary: "SessionStart: kickoff into context",
-  },
   { name: "init", group: "setup", summary: "scaffold .fapony/ in a worktree" },
   {
     name: "install",
     group: "setup",
-    summary: "wire MCP + skills into clients",
+    summary: "wire skills + plan-mv guard into clients",
   },
   { name: "setup", group: "setup", summary: "interactive wizard" },
   { name: "update", group: "setup", summary: "self-update via git pull" },
@@ -130,7 +104,7 @@ export const COMMANDS: CommandInfo[] = [
 // a `usage: fapony` line: scripts/smoke-publish.sh greps for it on a no-arg run.
 export const renderUsage = (): string => {
   const lines = [
-    "fapony — project pain memory for agent-written code",
+    "fapony — plan workflow + token-saving lookups for agent-written code",
     "usage: fapony <command> [args]",
     "",
   ];
@@ -140,7 +114,7 @@ export const renderUsage = (): string => {
   }
   lines.push(
     "",
-    "  fapony mem <sub> --help     per-subcommand details (only mem has --help)",
+    "  memory (decisions, bugs, notes) lives in fael — fael --help",
   );
   return lines.join("\n");
 };
@@ -162,19 +136,14 @@ export const levenshtein = (a: string, b: string): number => {
   return prev[b.length];
 };
 
-// Up to 3 suggestions within distance ≤ 2, against top-level names and mem
-// subs (so `fapony plan-check` offers `fapony mem plan-check`). Sorted by
-// distance, then alphabetically — deterministic for tests.
-export const suggestCommand = (cmd: string, memSubs: string[]): string[] => {
+// Up to 3 suggestions within distance ≤ 2 against top-level names. Sorted
+// by distance, then alphabetically — deterministic for tests.
+export const suggestCommand = (cmd: string): string[] => {
   const scored: Array<{ text: string; d: number }> = [];
   for (const c of COMMANDS) {
     const d = levenshtein(cmd, c.name);
     if (d <= 2) scored.push({ text: `fapony ${c.name}`, d });
   }
-  for (const s of memSubs) {
-    const d = levenshtein(cmd, s);
-    if (d <= 2) scored.push({ text: `fapony mem ${s}`, d });
-  }
   scored.sort((x, y) => x.d - y.d || (x.text < y.text ? -1 : 1));
   return scored.slice(0, 3).map((s) => s.text);
 };

package/src/core/config.ts

@@ -66,7 +66,6 @@ export interface Config {
     stateDir?: string;
     // plan/spec live in .fapony/{plan,spec} — not configurable (gitignored = private).
     doneDir?: string;
-    memDir?: string;
     evidenceFile?: string;
   } | null;
   safety?: {
@@ -100,7 +99,6 @@ export const SPEC_DIR = `${FAPONY_DIR}/spec`;
 // Archive sits beside plan/, not inside it, so archiving never changes a file's
 // depth and its relative links survive the move untouched.
 export const DEFAULT_DONE_DIR = `${FAPONY_DIR}/done`;
-export const DEFAULT_MEM_DIR = `${FAPONY_DIR}/.memory`;
 export const DEFAULT_EVIDENCE_FILE = `${FAPONY_DIR}/${EVIDENCE_FILENAME}`;
 
 export const DEFAULT_CONFIG: Config = {
@@ -136,10 +134,6 @@ export function doneDir(config?: Config): string {
   return config?.paths?.doneDir ?? DEFAULT_DONE_DIR;
 }
 
-export function memoryDir(config?: Config): string {
-  return config?.paths?.memDir ?? DEFAULT_MEM_DIR;
-}
-
 export function evidenceFile(config?: Config): string {
   return config?.paths?.evidenceFile ?? DEFAULT_EVIDENCE_FILE;
 }

package/src/core/fapony-dir.ts

@@ -0,0 +1,71 @@
+// src/core/fapony-dir.ts — where a repo's `.fapony/` (plan/ done/ spec/
+// conventions.json) lives: the nearest one walking up from cwd, bounded by the
+// git root, else `<root>/.fapony`. Monorepos keep one per app (apps/x/.fapony).
+
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { FAPONY_DIR } from "./config.js";
+
+/** Physical path (symlinks resolved) so start and repo root compare like with
+ *  like; falls back to a lexical resolve when the path does not exist yet. */
+function physical(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/** `git rev-parse --show-toplevel` from a directory, or null outside a repo. */
+function gitRootOf(fromDir: string): string | null {
+  try {
+    const { execSync } =
+      require("node:child_process") as typeof import("node:child_process");
+    const root = execSync("git rev-parse --show-toplevel", {
+      cwd: fromDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    return root || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The lexical ancestor of `fromDir` that is the git repo root, or null outside
+ * a repo. `git rev-parse` returns a physical path (it resolves /var → /private/
+ * var on macOS), so the walk compares `physical(dir)` against it and returns the
+ * path in the caller's own lexical form — the returned dir must match what the
+ * caller passed in, not a canonicalized stranger.
+ */
+export function repoRootOf(fromDir: string): string | null {
+  const start = resolve(fromDir);
+  const gitRoot = gitRootOf(start);
+  if (!gitRoot) return null;
+  const physicalRoot = physical(gitRoot);
+  let dir = start;
+  while (true) {
+    if (physical(dir) === physicalRoot) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/** Nearest `.fapony/` at or above `fromDir` (never past the git root), else
+ *  `<root>/.fapony` — which may not exist yet. */
+export function faponyDirFrom(fromDir: string): string {
+  const start = resolve(fromDir);
+  const root = repoRootOf(start);
+  let dir = start;
+  while (true) {
+    const candidate = join(dir, FAPONY_DIR);
+    if (existsSync(candidate)) return candidate;
+    if (dir === (root ?? "/")) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return join(root ?? start, FAPONY_DIR);
+}

package/src/core/hook-helpers.ts

@@ -1,8 +1,7 @@
 // src/core/hook-helpers.ts — pure helpers shared by hook adapters
 //
 // Extracted from src/hook.ts (PLAN-lib-layer chunk 3). These have zero
-// feature imports and are reused by stop, read-hint, edit-hint, and
-// session-start adapters.
+// feature imports and are reused by the hook adapters and the hint log.
 
 import { basename } from "node:path";
 

package/src/debt/load.ts

@@ -17,14 +17,12 @@ import {
   CONVENTIONS_FILENAME,
   FAPONY_DIR,
 } from "../core/config.js";
-import { resolveMemDir } from "../memory.js";
+import { faponyDirFrom } from "../core/fapony-dir.js";
 import type { Convention, LoadedConventions } from "./types.js";
 
 export function resolveConventionsPath(worktree: string): string | null {
-  // Conventions live in the same .fapony/ dir as the mem log — derive from
-  // the resolved mem dir so both resolvers cannot drift apart.
-  const memDir = resolveMemDir(worktree);
-  const base = memDir ? join(memDir, "..") : join(worktree, FAPONY_DIR);
+  // Conventions live in the nearest .fapony/ — the same dir `fapony plan` uses.
+  const base = faponyDirFrom(worktree);
   const app = join(base, CONVENTIONS_FILENAME);
   if (existsSync(app)) return app;
   // Monorepo where the app has not scaffolded .fapony/ yet, and single repos

package/src/debt/promotion.ts

@@ -12,7 +12,7 @@
 // short and don't count, to avoid over-matching)
 
 import { openDb } from "../db/store.js";
-import { readMemLog } from "../memory.js";
+import { readFaelLog } from "../fael.js";
 import {
   type Convention,
   type DebtReport,
@@ -57,7 +57,7 @@ interface EvidenceRow {
 function gatherEvidence(worktree: string): EvidenceRow[] {
   const out: EvidenceRow[] = [];
   try {
-    for (const r of readMemLog(worktree).rows) {
+    for (const r of readFaelLog(worktree).rows) {
       if (r.kind !== "bug" && r.kind !== "decision") continue;
       out.push({ ts: r.ts, files: r.files, hay: `${r.text}\n${r.spec ?? ""}` });
     }

package/src/debt/scan.ts

@@ -187,7 +187,7 @@ export function debtScan(
   };
 }
 
-/** Per-file lookup (hook-read-hint + --files): which conventions flag this file. */
+/** Per-file lookup (--files): which conventions flag this file. */
 export function debtForFile(
   worktree: string,
   absFile: string,

package/src/digest/collect.ts

@@ -16,8 +16,8 @@ import {
 import { type HintImpact, hintLogPath } from "../core/hint-log.js";
 import { parseSince } from "../core/since.js";
 import { openDb } from "../db/store.js";
+import { type MemRow, readFaelLog } from "../fael.js";
 import { computeHintImpact } from "../hook.js";
-import { type MemRow, readMemLog } from "../memory.js";
 import { isPassFamily, VERDICT_GRADES } from "../parse.js";
 import { imputeResult, loadPrices } from "../price/index.js";
 import { EMPTY_RESULT, type PassiveUsageResult } from "../session/types.js";
@@ -528,15 +528,14 @@ export async function collectDigest(
   let skippedMalformed = 0;
 
   // 1. memory log
-  const mem = readMemLog(worktree, sinceIso);
+  const mem = readFaelLog(worktree, sinceIso);
   skippedMalformed += mem.skipped;
   sources.push({
     name: "memory",
-    ok: mem.filesFound > 0,
-    detail:
-      mem.filesFound > 0
-        ? `${mem.rows.length} rows from ${mem.filesFound} file${mem.filesFound > 1 ? "s" : ""}`
-        : "no memory log — run: fapony init <path>",
+    ok: mem.ok,
+    detail: mem.ok
+      ? `${mem.rows.length} rows from fael`
+      : "fael not found — memory lives in fael (npm i -g @inonix/fael)",
   });
 
   // 2. plans