fapony 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fapony",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Token usage across Claude Code, OpenCode, Codex & ZCode on one yardstick — plus a project mem log and convention-debt tracker agents query via 3 MCP tools. No server, your data stays local",
   "license": "MIT",
   "author": "delamind (https://github.com/kire21b)",

package/src/adapters/hooks/context-data.ts

@@ -3,11 +3,19 @@
 // Split from src/hook.ts (PLAN-lib-layer chunk 3). Used by both read-hint and
 // edit-hint adapters to attach debt/mem lines when a file is open.
 
-import { realpathSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { collectSourceFiles, SCAN_EXTS } from "../../analyze/index.js";
-import { MEM_TEXT_MAX, readMemLog } from "../../core/mem-log.js";
+import { readTrackDir, sessionKey } from "../../core/hook-helpers.js";
+import { clipMemText, readMemLog } from "../../core/mem-log.js";
 import { debtForFile, resolveDebtScope } from "../../debt/index.js";
+import { movedTargets } from "../../mem/selectors.js";
 
 const DEBT_HINT_MAX = 3;
 const MEM_HINT_MAX = 2;
@@ -23,10 +31,40 @@ export interface ContextLineData {
   memIds: string[];
 }
 
-/** Structured data behind readContextLines — used by cmdHookReadHint for logging. */
+/** Mem row ids already shown this session — a row repeats on every read/edit otherwise. */
+function shownPath(session: string): string {
+  return join(readTrackDir(), `${sessionKey(session)}.mem-shown`);
+}
+
+function readShown(session: string): Set<string> {
+  try {
+    const p = shownPath(session);
+    if (!existsSync(p)) return new Set();
+    return new Set(readFileSync(p, "utf-8").split("\n").filter(Boolean));
+  } catch {
+    return new Set();
+  }
+}
+
+function markShown(session: string, ids: string[]): void {
+  if (ids.length === 0) return;
+  try {
+    mkdirSync(readTrackDir(), { recursive: true });
+    appendFileSync(shownPath(session), `${ids.join("\n")}\n`, "utf-8");
+  } catch {
+    // a hint must never fail the tool call
+  }
+}
+
+/**
+ * Structured data behind readContextLines — used by cmdHookReadHint for logging.
+ * With a session, a non-bug mem row shows once per session (open bugs always
+ * show: they are exact files[] matches and the point is to nag until closed).
+ */
 export function readContextData(
   filePath: unknown,
   cwd: string,
+  session?: unknown,
 ): ContextLineData | null {
   try {
     if (typeof filePath !== "string" || filePath === "") return null;
@@ -71,6 +109,26 @@ export function readContextData(
     // even though the file being touched sits right under its log (bug muc9q47r).
     const mem = readMemLog(dirname(abs));
     if (mem.rows.length > 0) {
+      // PLAN-mem-core chunk 5 — follow moves: a row naming old/a.ts still
+      // shows when the file now lives at new/a.ts, as long as no other a.ts
+      // exists on disk. Missing = stat-miss on the worktree-joined path; the
+      // tree walk runs only when some row actually names a missing file.
+      const missingOld = new Set<string>();
+      for (const r of mem.rows)
+        for (const f of r.files ?? [])
+          if (f !== rel && !existsSync(join(worktree, f))) missingOld.add(f);
+      const moved =
+        missingOld.size > 0
+          ? movedTargets([...missingOld], collectSourceFiles(worktree))
+          : null;
+      const filesOf = (r: (typeof mem.rows)[number]): string[] =>
+        (r.files ?? []).map((f) => moved?.get(f) ?? f);
+      const movedFrom = (r: (typeof mem.rows)[number]): string => {
+        const from = (r.files ?? []).find(
+          (f) => f !== rel && moved?.get(f) === rel,
+        );
+        return from ? ` (moved from ${from})` : "";
+      };
       // Open bugs first (PLAN-active-pain chunk 3): a kind:"bug" row whose id
       // is in no close row's ref — the same tombstone shape as openRows in
       // src/mem/selectors.ts, never a regex on text. Exact files[] match only:
@@ -82,23 +140,29 @@ export function readContextData(
       for (const r of mem.rows) {
         if (openLines.length >= MEM_HINT_MAX) break;
         if (r.kind !== "bug" || !r.id || closed.has(r.id)) continue;
-        if (!(r.files ?? []).includes(rel)) continue;
+        if (!filesOf(r).includes(rel)) continue;
         openLines.push(
-          `fapony mem: OPEN BUG ${r.id} — "${r.text.slice(0, MEM_TEXT_MAX)}" — ปิดด้วย fapony mem close ${r.id} "<msg>" เมื่อแก้แล้ว`,
+          `fapony mem: OPEN BUG ${r.id} — "${clipMemText(r.text)}" — ปิดด้วย fapony mem close ${r.id} "<msg>" เมื่อแก้แล้ว${movedFrom(r)}`,
         );
         openBugIds.push(r.id);
       }
       const base = basename(rel);
-      const direct: typeof mem.rows = [];
+      // Tiers: files[] names this file > text/spec mentions the path >
+      // basename-only. readMemLog is newest first, so each tier is too.
+      const exact: typeof mem.rows = [];
+      const mention: typeof mem.rows = [];
       const baseOnly: typeof mem.rows = [];
       for (const r of mem.rows) {
-        if (r.kind === "claim" || r.kind === "release") continue;
-        const hay = `${r.text}\n${r.spec ?? ""}\n${(r.files ?? []).join(",")}`;
-        if ((r.files ?? []).includes(rel) || hay.includes(rel)) {
-          direct.push(r);
+        if (r.kind === "claim" || r.kind === "release" || r.kind === "close") {
+          continue;
+        }
+        if (filesOf(r).includes(rel)) {
+          exact.push(r);
           continue;
         }
-        if (base && hay.includes(base)) baseOnly.push(r);
+        const hay = `${r.text}\n${r.spec ?? ""}\n${(r.files ?? []).join(",")}`;
+        if (hay.includes(rel)) mention.push(r);
+        else if (base && hay.includes(base)) baseOnly.push(r);
       }
       let usableBase = baseOnly;
       if (baseOnly.length > 0) {
@@ -107,21 +171,29 @@ export function readContextData(
         ).length;
         if (sameName !== 1) usableBase = [];
       }
+      const shown =
+        typeof session === "string" && session !== ""
+          ? readShown(session)
+          : null;
       // Open lines take the closed rows' slots first; the rest fills the
       // remaining budget without adding lines past the cap — and without
-      // repeating a row already emitted as OPEN BUG.
+      // repeating a row already emitted as OPEN BUG or shown this session.
       const emitted = new Set(openBugIds);
-      const rest = [...direct, ...usableBase]
-        .filter((r) => !(r.id && emitted.has(r.id)))
+      const rest = [exact, mention, usableBase]
+        .flat()
+        .filter((r) => !(r.id && (emitted.has(r.id) || shown?.has(r.id))))
         .slice(0, MEM_HINT_MAX - openLines.length);
       for (const line of openLines) memLines.push(line);
       memIds.push(...openBugIds);
+      const restIds: string[] = [];
       for (const r of rest) {
-        if (r.id) memIds.push(r.id);
+        if (r.id) restIds.push(r.id);
         memLines.push(
-          `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${r.text.slice(0, MEM_TEXT_MAX)}`,
+          `fapony mem: ${r.ts.slice(0, 10)} ${r.kind} — ${clipMemText(r.text)}${movedFrom(r)}`,
         );
       }
+      memIds.push(...restIds);
+      if (shown && typeof session === "string") markShown(session, restIds);
     }
     return { worktree, debtIds, debtLines, memLines, openBugIds, memIds };
   } catch {

package/src/adapters/hooks/edit-hint.ts

@@ -133,7 +133,7 @@ export async function cmdHookEditHint(): Promise<void> {
     const parts: string[] = [];
     const hint = editHintFor({ filePath, cwd, session });
     if (hint) parts.push(hint);
-    const ctx = readContextData(filePath, cwd);
+    const ctx = readContextData(filePath, cwd, session);
     if (ctx) {
       for (const line of [...ctx.debtLines, ...ctx.memLines]) {
         parts.push(line);

package/src/adapters/hooks/read-hint.ts

@@ -11,11 +11,10 @@ import {
   realpathSync,
   statSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join, relative, resolve } from "node:path";
 import { SCAN_EXTS } from "../../analyze/index.js";
 import { recordHintFire } from "../../core/hint-log.js";
-import { sessionKey } from "../../core/hook-helpers.js";
+import { readTrackDir, sessionKey } from "../../core/hook-helpers.js";
 import { readMemLog } from "../../memory.js";
 import { renderSeed } from "../../seed/review-seed.js";
 import { hasBugMarker, isBugfixCommit } from "./bug-markers.js";
@@ -105,21 +104,12 @@ export function readHintFor(opts: ReadHintInput): string | null {
 
 // --- Re-read tracking (mtime heuristic) ---
 
-const READ_TRACK_DIR = "read-track";
-
 export interface ReadTrackRow {
   ts: string;
   path: string;
   mtime: number;
 }
 
-/** Directory holding one read log per session. */
-function readTrackDir(): string {
-  const base =
-    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
-  return join(base, READ_TRACK_DIR);
-}
-
 /** Absolute path of a session's read log — may not exist. */
 export function readTrackPath(session: string): string {
   return join(readTrackDir(), `${sessionKey(session)}.jsonl`);
@@ -324,7 +314,7 @@ export async function cmdHookReadHint(): Promise<void> {
       session,
     });
     if (reread) parts.push(reread);
-    const ctx = readContextData(filePath, cwd);
+    const ctx = readContextData(filePath, cwd, session);
     if (ctx) {
       for (const line of [...ctx.debtLines, ...ctx.memLines]) {
         parts.push(line);

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

@@ -112,9 +112,9 @@ export const TOOLS = [
         },
         key: {
           type: "string",
-          pattern: "^[a-z0-9-]{3,40}$",
+          pattern: "^[a-z0-9-]{3,40}(:[a-z0-9-]{1,40})?$",
           description:
-            "Problem identity (not kind, not files) — same problem, same key",
+            "Problem identity (not kind, not files) — same problem, same key; domain:sub (e.g. auth:login) when the repo declares domains",
         },
       },
       required: ["worktree", "kind", "text", "files"],

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

@@ -13,6 +13,7 @@ import {
   engineClose,
   engineFind,
 } from "../../../mem/engine.js";
+import { loadKeyRegistry } from "../../../mem/key-registry.js";
 import { initStore, KINDS, type WorkKind } from "../../../mem/store.js";
 import { type MemRow, readMemLog, resolveMemDir } from "../../../memory.js";
 import { errorResult, jsonResult, type ToolResult } from "../types.js";
@@ -101,9 +102,10 @@ export function toolMemFind(args: Record<string, unknown>): ToolResult {
   // 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).
+  // A bare domain doubles as a prefix — key:"auth" catches every auth:*.
   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"',
+      'key must be a string matching [a-z0-9-]{3,40}(:[a-z0-9-]{1,40})? — e.g. "fix-stop-dedupe" or "auth:login"',
     );
   }
   const key = typeof args.key === "string" ? args.key : undefined;
@@ -129,12 +131,16 @@ export function memAdd(args: {
   key?: string;
 }): MemAddResult {
   initStore(args.worktree);
+  // Registry beside the mem log; absent = free-form keys (never reject).
+  // Loaded per call, not at MCP start (initialize budget ≤ ~100ms).
+  const reg = loadKeyRegistry(args.worktree);
   return engineAdd({
     kind: args.kind,
     text: args.text,
     files: args.files,
     spec: args.spec,
     key: args.key,
+    knownDomains: reg.path ? reg.domains : null,
   });
 }
 
@@ -186,7 +192,7 @@ export function toolMemAdd(args: Record<string, unknown>): ToolResult {
   // 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"',
+      'key must be a string matching [a-z0-9-]{3,40}(:[a-z0-9-]{3,40})? — e.g. "fix-stop-dedupe" or "auth:login"',
     );
   }
   const key = typeof args.key === "string" ? args.key : undefined;

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. Name a known problem with --key <a-z0-9-id> and recall every row for it via mem_find key.
+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 <domain:sub> 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/config.ts

@@ -92,8 +92,10 @@ export interface RolePricing {
 export const FAPONY_DIR = ".fapony";
 export const CONFIG_FILENAME = "fapony.config.json";
 export const CONVENTIONS_FILENAME = "conventions.json";
+export const KEYS_FILENAME = "keys.json";
 export const EVIDENCE_FILENAME = "evidence.json";
 export const CONVENTIONS_FILE = `${FAPONY_DIR}/${CONVENTIONS_FILENAME}`;
+export const KEYS_FILE = `${FAPONY_DIR}/${KEYS_FILENAME}`;
 // plan/spec live in .fapony/ — not configurable (gitignored = private).
 export const PLAN_DIR = `${FAPONY_DIR}/plan`;
 export const SPEC_DIR = `${FAPONY_DIR}/spec`;

package/src/core/hook-helpers.ts

@@ -4,7 +4,8 @@
 // feature imports and are reused by stop, read-hint, edit-hint, and
 // session-start adapters.
 
-import { basename } from "node:path";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
 
 /** UTC 'YYYY-MM-DD HH:MM:SS' — the format events.ts is written in. */
 export function utcStamp(d: Date): string {
@@ -29,3 +30,10 @@ export function sessionKey(session: string): string {
   const base = basename(session).replace(/\.[^.]+$/, "");
   return base.replace(/[^A-Za-z0-9_-]/g, "-") || "unknown";
 }
+
+/** Per-session hint state dir (read log + shown mem ids) — disposable, never in a worktree. */
+export function readTrackDir(): string {
+  const base =
+    process.env.FAPONY_STATE_DIR || join(homedir(), ".config", "fapony");
+  return join(base, "read-track");
+}

package/src/core/mem-log.ts

@@ -31,12 +31,31 @@ export interface MemRow {
 /** 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;
 
+/** Cut a row's text to MEM_TEXT_MAX at a word boundary, marked with `…` — never mid-word. */
+export function clipMemText(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  if (flat.length <= MEM_TEXT_MAX) return flat;
+  const cut = flat.slice(0, MEM_TEXT_MAX - 1);
+  const space = cut.lastIndexOf(" ");
+  // ponytail: no space in the back half (one long token/path) = hard cut
+  return `${(space > MEM_TEXT_MAX / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
 /**
  * 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).
+ *
+ * Bare (`fix-stop-dedupe`) or namespaced (`auth:login`, `nope:x`): the domain
+ * half is checked against `.fapony/keys.json` when that file exists
+ * (PLAN-mem-core chunk 4); the sub half is free (≥1 char — it names one
+ * problem, not a namespace). One colon at most — the engine splits on the
+ * first one, so a second colon never validates.
  */
-export const KEY_RE = /^[a-z0-9-]{3,40}$/;
+export const KEY_RE = /^[a-z0-9-]{3,40}(:[a-z0-9-]{1,40})?$/;
+
+/** A single key segment (domain in the registry, sub after the colon). */
+export const KEY_SEGMENT_RE = /^[a-z0-9-]{3,40}$/;
 
 interface RawMemRow {
   ts?: string;

package/src/install/opencode.ts

@@ -238,7 +238,7 @@ export const FaponyReadHint = async ({ directory }) => {
           session: input.sessionID,
         });
         if (reread) parts.push(reread);
-        const ctx = readContextData(filePath, directory);
+        const ctx = readContextData(filePath, directory, input.sessionID);
         if (ctx) {
           for (const line of [...ctx.debtLines, ...ctx.memLines]) {
             parts.push(line);
@@ -384,7 +384,7 @@ export const FaponyEditHint = async ({ directory }) => {
         });
         if (hint) parts.push(hint);
         // Attach mem/debt context (same as read hint — annotate only, cap 5 lines)
-        const ctx = readContextData(filePath, directory);
+        const ctx = readContextData(filePath, directory, input.sessionID);
         if (ctx) {
           for (const line of [...ctx.debtLines, ...ctx.memLines]) {
             parts.push(line);

package/src/mem/commands/read.ts

@@ -2,16 +2,40 @@
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { collectSourceFiles } from "../../analyze/index.js";
 import { parseSince } from "../../core/since.js";
 import { baselinePath, readEvidenceLintCmd } from "../../lint-baseline.js";
 import { CLI_FIND_EXCLUDE, engineFind } from "../engine.js";
+import { loadKeyRegistry } from "../key-registry.js";
 import { doneLines, fmtClose, fmtRow } from "../render.js";
-import { claimsOf, openKeys, openRows, staleReport } from "../selectors.js";
+import {
+  claimsOf,
+  evictionReport,
+  openKeys,
+  openRows,
+  staleReport,
+} from "../selectors.js";
 import type { CloseRow, LogRow, WorkRow } from "../store.js";
-import { allRows, app, memCmd, planDir, root, rows } from "../store.js";
+import { allRows, app, LOG, memCmd, planDir, root, rows } from "../store.js";
 import { checkTickedLine, planSweepCmd, shippedNotMoved } from "./plan.js";
 import { THRESHOLD } from "./rotate.js";
 
+/**
+ * One ⚠ line when the mem log is gitignored — the log's promise is that a
+ * clone carries every decision; an ignored log keeps them on this machine
+ * only, and nothing else says so. Ignoring may be deliberate (a public repo),
+ * so this warns, never blocks.
+ */
+function ignoredLogLine(): string | null {
+  try {
+    const p = Bun.spawnSync(["git", "check-ignore", "-q", LOG], { cwd: root });
+    if (p.exitCode !== 0) return null;
+  } catch {
+    return null;
+  }
+  return `⚠ mem log is gitignored (${basename(LOG)}) — decisions and plan ticks stay on this machine; a clone gets none of them`;
+}
+
 /** Files changed on this branch vs dev — empty set when dev is missing or diff fails. */
 function getBranchDiffFiles(cwd: string): Set<string> {
   try {
@@ -65,6 +89,14 @@ const openKeysLine = (all: LogRow[]): string => {
   return `open keys: ${body}${more} — ${memCmd} find --key <key>`;
 };
 
+// Registry line (PLAN-mem-core chunk 4): one line naming the allowed domains
+// so the agent keys the row right the first time — silent with no registry.
+const keyDomainsLine = (): string => {
+  const reg = loadKeyRegistry(root || process.cwd());
+  if (!reg.path || !reg.domains.length) return "";
+  return `key domains: ${reg.domains.join(", ")} — use --key domain:sub`;
+};
+
 const shortText = (text: string, max = RECENT_OPEN_TEXT): string => {
   if (text.length <= max) return text;
   const cut = text.slice(0, max);
@@ -78,7 +110,23 @@ export const cmdDone = () => {
 };
 
 export const cmdStale = () => {
-  for (const l of staleReport(rows())) console.log(l);
+  const all = rows();
+  for (const l of staleReport(all)) console.log(l);
+  // Eviction (PLAN-mem-core chunk 5): rows whose files[] are all gone from
+  // disk, with unique-basename moves followed. Local only — existsSync +
+  // collectSourceFiles, never git. The tree walk runs only when some row
+  // actually names a missing file.
+  if (!root) return;
+  const exists = (f: string) => existsSync(join(root, f));
+  if (
+    !all.some(
+      (r) =>
+        "files" in r && ((r as WorkRow).files ?? []).some((f) => !exists(f)),
+    )
+  )
+    return;
+  for (const l of evictionReport(all, exists, collectSourceFiles(root)))
+    console.log(l);
 };
 
 export const cmdFind = (a: string[]) => {
@@ -553,8 +601,12 @@ export const cmdKickoff = (a: string[]) => {
   if (!arg && !planFile) {
     // no args = ranked open rows + next up + recent closes
     console.log(`# ${app} — ${all.length} entries`);
+    const ignored = ignoredLogLine();
+    if (ignored) console.log(ignored);
     const keys = openKeysLine(all);
     if (keys) console.log(keys);
+    const domains = keyDomainsLine();
+    if (domains) console.log(domains);
 
     const open = openRows(all);
     const claims = claimsOf(all);
@@ -714,6 +766,8 @@ export const cmdKickoff = (a: string[]) => {
   } else if (planFile) {
     const title = readPlanTitle(planFile);
     console.log(`# ${title || basename(planFile)} — plan`);
+    const ignored = ignoredLogLine();
+    if (ignored) console.log(ignored);
     if (planCheckboxes.length) {
       console.log(
         `\n## unchecked\n${planCheckboxes.map((c) => `- [ ] ${c}`).join("\n")}`,

package/src/mem/commands/write.ts

@@ -1,6 +1,7 @@
 // commands/write.ts — mutating commands: add, close, claim, release, synced, hook
 
 import { CapError, engineAdd, engineClose } from "../engine.js";
+import { loadKeyRegistry } from "../key-registry.js";
 import { claimsOf, openRows } from "../selectors.js";
 import type { WorkKind } from "../store.js";
 import { KINDS, memCmd, put, root, rows } from "../store.js";
@@ -125,8 +126,18 @@ export const cmdAdd = async (a: string[]) => {
   }
   // Domain rules (caps, id) live in the shared engine — this wrapper owns
   // only argv surface and the MEM_FORCE hint wording (PLAN-unify-mem-engine).
+  // The registry lives beside the mem log; absent = free-form keys (never
+  // reject). root is set by initStore at dispatch; cwd covers direct calls.
   try {
-    const { id } = engineAdd({ kind: a[0], text, spec, files, key: keyVal });
+    const reg = loadKeyRegistry(root || process.cwd());
+    const { id } = engineAdd({
+      kind: a[0],
+      text,
+      spec,
+      files,
+      key: keyVal,
+      knownDomains: reg.path ? reg.domains : null,
+    });
     console.log(id);
   } catch (e) {
     if (e instanceof CapError) {

package/src/mem/engine.ts

@@ -11,6 +11,7 @@
 // (PLAN-unify-mem-engine chunk 1)
 
 import { KEY_RE } from "../core/mem-log.js";
+import { checkKeyDomain, keyMatchesQuery } from "./key-registry.js";
 import { openRows } from "./selectors.js";
 import { KINDS, nextId, put, rows, type WorkKind } from "./store.js";
 
@@ -38,6 +39,12 @@ export interface EngineAddArgs {
   spec?: string;
   /** Problem identity — optional, but validated against KEY_RE whenever present. */
   key?: string;
+  /**
+   * Registry domains for this repo (`.fapony/keys.json` via loadKeyRegistry).
+   * null/undefined = no registry on disk = free-form keys, never reject.
+   * Wrappers resolve it; the engine stays pure (no fs).
+   */
+  knownDomains?: string[] | null;
 }
 
 export interface EngineAddResult {
@@ -68,9 +75,13 @@ export function engineAdd(a: EngineAddArgs): EngineAddResult {
   // with a usable example, never silently drop the key (SPEC-mem-keys §Validation).
   if (a.key !== undefined && !KEY_RE.test(a.key)) {
     throw new Error(
-      `key must match [a-z0-9-]{3,40} — e.g. "fix-stop-dedupe", got "${a.key}"`,
+      `key must match [a-z0-9-]{3,40}(:[a-z0-9-]{1,40})? — e.g. "fix-stop-dedupe" or "auth:login", got "${a.key}"`,
     );
   }
+  // Registry gate (PLAN-mem-core chunk 4): the domain half must be declared.
+  const domainError =
+    a.key !== undefined ? checkKeyDomain(a.key, a.knownDomains) : null;
+  if (domainError) throw new Error(domainError);
 
   const all = rows();
   if (a.kind === "next" && !process.env.MEM_FORCE) {
@@ -190,10 +201,12 @@ export interface EngineFindArgs {
    */
   open?: boolean;
   /**
-   * Exact problem-identity match — rows whose effective key differs fall out
-   * (v:1 rows included; they stay reachable via files/text). A close row
-   * matches through the key of the work row its ref points at (derived at
-   * read time, never stored). A pure miss also returns knownKeys.
+   * Problem-identity match — a bare domain doubles as a prefix (`auth`
+   * catches every `auth:*`; `auth:login` is exact). Rows whose effective key
+   * differs fall out (v:1 rows included; they stay reachable via
+   * files/text). A close row matches through the key of the work row its
+   * ref points at (derived at read time, never stored). A pure miss also
+   * returns knownKeys.
    */
   key?: string;
 }
@@ -248,10 +261,11 @@ export function engineFind<T extends FindableRow>(
     out = out.filter((r) => !drop.has(r.kind));
   }
 
-  // Exact key match, before text/files — a wrong key must never fall through
-  // to substring luck. Close rows derive their key from the ref'd work row
-  // (read-time derive: match only; the row itself stays keyless). knownKeys
-  // fires only on a pure key miss — answer a wrong guess with the real list.
+  // Domain-prefix key match, before text/files — a wrong key must never fall
+  // through to substring luck. Close rows derive their key from the ref'd
+  // work row (read-time derive: match only; the row itself stays keyless).
+  // knownKeys fires only on a pure key miss — answer a wrong guess with the
+  // real list.
   let knownKeys: string[] | undefined;
   if (a.key) {
     const want = a.key;
@@ -266,8 +280,8 @@ export function engineFind<T extends FindableRow>(
       (r.kind === "close" && typeof r.ref === "string"
         ? idKey.get(r.ref)
         : undefined);
-    out = out.filter((r) => eff(r) === want);
-    if (!all.some((r) => eff(r) === want)) {
+    out = out.filter((r) => keyMatchesQuery(eff(r), want));
+    if (!all.some((r) => keyMatchesQuery(eff(r), want))) {
       const distinct = new Set<string>();
       for (const r of all) {
         if (r.key) distinct.add(r.key);

package/src/mem/index.ts

@@ -52,7 +52,7 @@ example: fapony mem kickoff .fapony/plan/PLAN-x.md`,
   add: `usage: fapony mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [--key k] [spec.md]
 append one row to the mem log
   --files f1,f2   repo-relative paths this row is about (required)
-  --key k         problem identity, [a-z0-9-]{3,40} — same problem = same key (optional)
+  --key k         problem identity, bare or domain:sub (e.g. auth:login) — the domain must be in .fapony/keys.json when that file exists (optional)
   --stdin         read <text> from stdin (avoids shell metachar)
 example: fapony mem add decision "chose X because Y" --files src/a.ts,src/b.ts --key unify-mem-engine`,
   close: `usage: fapony mem close <id> "<what was done | commit>"
@@ -63,7 +63,7 @@ example: fapony mem close mt14 "fixed in a2c6beb"`,
 substring search over every row's text/spec/ref (rotated archives included) — bookkeeping kinds (close/synced/claim/release) hidden unless --kind names them
   --kind a,b    include only these kinds (overrides the bookkeeping default)
   --files f1,f2 rows about these paths (stored files[] first, text/spec/ref fallback)
-  --key k       exact problem-identity match — a miss prints the known keys
+  --key k       problem-identity match — a bare domain catches every domain:* (auth matches auth:login); a miss prints the known keys
   --since 7d    only rows at or after this time (<N>d or YYYY-MM-DD)
   --limit n     max rows returned (default 20, newest first)
 example: fapony mem find "usage-web" --kind bug,decision --limit 5`,

package/src/mem/key-registry.ts

@@ -0,0 +1,116 @@
+// src/mem/key-registry.ts — domain key registry (`domain:sub`).
+//
+// PLAN-mem-core chunk 4: keys an agent invents never converge (3%), so a repo
+// that wants convergence declares its domains in `.fapony/keys.json`, beside
+// `conventions.json` — fixed path, no config field (rule: never add a field
+// derivable from structure). No file = keys stay free-form (never reject);
+// a file = the domain half must be listed, the sub half stays free.
+//
+// Shape: {"domains": ["auth", "hook"]} (a bare ["auth"] array reads the same).
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { FAPONY_DIR, KEYS_FILE, KEYS_FILENAME } from "../core/config.js";
+import { KEY_SEGMENT_RE } from "../core/mem-log.js";
+import { resolveMemDir } from "../memory.js";
+
+/** Split `domain:sub` — null domain = a bare legacy key, always allowed. */
+export function splitKey(key: string): { domain: string; sub: string } | null {
+  const i = key.indexOf(":");
+  if (i < 0) return null;
+  return { domain: key.slice(0, i), sub: key.slice(i + 1) };
+}
+
+/**
+ * A bare domain query doubles as a prefix: `auth` matches the exact key
+ * `auth` and every `auth:*`. A query carrying a colon is an exact match —
+ * `auth:login` never pulls in `auth:logout`.
+ */
+export function keyMatchesQuery(
+  rowKey: string | undefined,
+  query: string,
+): boolean {
+  if (!rowKey) return false;
+  if (query.includes(":")) return rowKey === query;
+  return rowKey === query || rowKey.startsWith(`${query}:`);
+}
+
+export function resolveKeysPath(worktree: string): string | null {
+  // Same anchor as conventions.json: the .fapony/ dir holding the mem log,
+  // so the registry and the log cannot drift apart.
+  const memDir = resolveMemDir(worktree);
+  const base = memDir ? join(memDir, "..") : join(worktree, FAPONY_DIR);
+  const app = join(base, KEYS_FILENAME);
+  if (existsSync(app)) return app;
+  const root = join(worktree, KEYS_FILE);
+  return existsSync(root) ? root : null;
+}
+
+export interface KeyRegistry {
+  path: string | null;
+  /** Sorted, deduped, segment-valid — the list reject messages print. */
+  domains: string[];
+  warnings: string[];
+}
+
+/** Missing file = empty + no error (same contract as conventions.json). */
+export function loadKeyRegistry(worktree: string): KeyRegistry {
+  const path = resolveKeysPath(worktree);
+  if (!path) return { path: null, domains: [], warnings: [] };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return { path, domains: [], warnings: [`keys.json unreadable: ${path}`] };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      path,
+      domains: [],
+      warnings: [
+        `keys.json is not valid JSON — ${
+          e instanceof Error ? e.message.split("\n")[0] : "parse error"
+        }`,
+      ],
+    };
+  }
+  const rows: unknown[] = Array.isArray(parsed)
+    ? parsed
+    : Array.isArray((parsed as { domains?: unknown }).domains)
+      ? (parsed as { domains: unknown[] }).domains
+      : [];
+  const seen = new Set<string>();
+  let dropped = 0;
+  for (const r of rows) {
+    if (typeof r === "string" && KEY_SEGMENT_RE.test(r)) seen.add(r);
+    else dropped++;
+  }
+  const warnings =
+    dropped > 0
+      ? [
+          `keys.json: ${dropped} entr${dropped === 1 ? "y" : "ies"} dropped (not [a-z0-9-]{3,40})`,
+        ]
+      : [];
+  return { path, domains: [...seen].sort(), warnings };
+}
+
+/**
+ * null domains = no registry on disk = free-form keys (never reject).
+ * A registry gates only the domain half; bare keys stay backward compatible.
+ */
+export function checkKeyDomain(
+  key: string,
+  domains: string[] | null | undefined,
+): string | null {
+  if (domains == null) return null;
+  const split = splitKey(key);
+  if (!split) return null;
+  if (domains.includes(split.domain)) return null;
+  return (
+    `unknown key domain "${split.domain}" — known domains: ` +
+    (domains.length ? domains.join(", ") : "(none yet)")
+  );
+}

package/src/mem/selectors.ts

@@ -131,6 +131,73 @@ export const staleReport = (all: LogRow[]): string[] => {
   return out;
 };
 
+// Eviction (PLAN-mem-core chunk 5): rows whose files[] no longer resolve on
+// disk. Local only — the caller passes existence, this module never touches
+// fs or git (plan §4: eviction ไม่เรียก git เลย). Append-only: these selectors
+// report and redirect, they never delete rows.
+export const evictedRows = (
+  all: LogRow[],
+  exists: (rel: string) => boolean,
+): WorkRow[] =>
+  openRows(all).filter(
+    (r) =>
+      (r.files ?? []).length > 0 && (r.files ?? []).every((f) => !exists(f)),
+  );
+
+// Follow a move by basename: a missing path whose basename names exactly one
+// file on disk is treated as moved there. Two files sharing the basename =
+// ambiguous → no entry (silent, never guessed). A rename that changes the
+// basename itself is out of reach — said plainly, not guessed at.
+export const movedTargets = (
+  missing: string[],
+  onDisk: string[],
+): Map<string, string> => {
+  const byBase = new Map<string, string[]>();
+  for (const f of onDisk) {
+    const b = f.slice(f.lastIndexOf("/") + 1);
+    const list = byBase.get(b) ?? [];
+    list.push(f);
+    byBase.set(b, list);
+  }
+  const out = new Map<string, string>();
+  for (const old of missing) {
+    const b = old.slice(old.lastIndexOf("/") + 1);
+    const cands = (byBase.get(b) ?? []).filter((f) => f !== old);
+    if (cands.length === 1) out.set(old, cands[0]);
+  }
+  return out;
+};
+
+// One report for `mem stale`: EVICTED for open rows whose files[] are all
+// gone, MOVED for rows rescued by a unique-basename match. Rows with ≥1 file
+// still on disk stay silent — mem find --files still reaches them.
+export const evictionReport = (
+  all: LogRow[],
+  exists: (rel: string) => boolean,
+  onDisk: string[],
+): string[] => {
+  const open = openRows(all);
+  const gone = (files: string[]): string[] => files.filter((f) => !exists(f));
+  const moved = movedTargets(
+    [...new Set(open.flatMap((r) => gone(r.files ?? [])))],
+    onDisk,
+  );
+  const out: string[] = [];
+  for (const r of evictedRows(all, exists)) {
+    const missing = gone(r.files ?? []);
+    const rescued = missing.filter((f) => moved.has(f));
+    if (rescued.length === missing.length) {
+      const hops = rescued.map((f) => `${f} → ${moved.get(f)}`).join(", ");
+      out.push(`MOVED [${r.id}] ${r.kind} ${hops} — "${r.text}"`);
+    } else {
+      out.push(
+        `EVICTED [${r.id}] ${r.kind} files gone: ${missing.join(", ")} — "${r.text}"`,
+      );
+    }
+  }
+  return out;
+};
+
 // 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: