fapony 0.3.6 → 0.5.0

package/src/mem/commands/read.ts

@@ -6,8 +6,8 @@ import { parseSince } from "../../core/since.js";
 import { baselinePath, readEvidenceLintCmd } from "../../lint-baseline.js";
 import { CLI_FIND_EXCLUDE, engineFind } from "../engine.js";
 import { doneLines, fmtClose, fmtRow } from "../render.js";
-import { claimsOf, openRows, staleReport } from "../selectors.js";
-import type { CloseRow, WorkRow } from "../store.js";
+import { claimsOf, 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 { checkTickedLine, planSweepCmd, shippedNotMoved } from "./plan.js";
 import { THRESHOLD } from "./rotate.js";
@@ -49,6 +49,21 @@ const BUGS_LIMIT = 10;
 const BRANCH_LIMIT = 10;
 const RECENT_OPEN_LIMIT = 10;
 const RECENT_OPEN_TEXT = 160;
+const OPEN_KEYS_LIMIT = 8;
+
+// Important-index line (PLAN-mem-keys chunk 3): one line under the kickoff
+// header listing keys that still have open rows — silent when none. Placed
+// before every tier so the 4KB session-start cap can never drop it (only
+// ## recent is cut first). Counts are open rows per key, not total rows.
+const openKeysLine = (all: LogRow[]): string => {
+  const keys = openKeys(all);
+  if (!keys.length) return "";
+  const shown = keys.slice(0, OPEN_KEYS_LIMIT);
+  const body = shown.map(({ key, open }) => `${key}(${open})`).join(", ");
+  const more =
+    keys.length > OPEN_KEYS_LIMIT ? ` +${keys.length - OPEN_KEYS_LIMIT}` : "";
+  return `open keys: ${body}${more} — ${memCmd} find --key <key>`;
+};
 
 const shortText = (text: string, max = RECENT_OPEN_TEXT): string => {
   if (text.length <= max) return text;
@@ -67,7 +82,7 @@ export const cmdStale = () => {
 };
 
 export const cmdFind = (a: string[]) => {
-  // mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--open]
+  // mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--key k] [--open]
   // Query logic lives in the shared engine (../engine.ts) — this wrapper owns
   // only argv parsing + the single-line print. MCP memFind calls the same
   // engine with no kind default (contract); CLI keeps its legacy default of
@@ -83,11 +98,15 @@ export const cmdFind = (a: string[]) => {
     return 2;
   };
 
-  let kind: string[] | undefined;
-  let files: string[] | undefined;
+  // Accumulators, not reassignments: a repeated list flag must grow the set,
+  // never last-win (PLAN-comma-x chunk 2). Exported as string[] | undefined
+  // after the loop so every downstream check reads the same shape.
+  const kindAcc: string[] = [];
+  const filesAcc: string[] = [];
   let sinceRaw: string | undefined;
   let limit: number | undefined;
   let open = false;
+  let key: string | undefined;
   const positional: string[] = [];
 
   for (let i = 0; i < a.length; ) {
@@ -100,10 +119,12 @@ export const cmdFind = (a: string[]) => {
         );
         process.exit(1);
       }
-      kind = v
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean);
+      kindAcc.push(
+        ...v
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean),
+      );
       i += consumed("--kind", i);
     } else if (t === "--files" || t.startsWith("--files=")) {
       const v = flagVal("--files", i);
@@ -113,11 +134,25 @@ export const cmdFind = (a: string[]) => {
         );
         process.exit(1);
       }
-      files = v
-        .split(",")
-        .map((s) => s.trim().replace(/^\.\//, ""))
-        .filter(Boolean);
+      filesAcc.push(
+        ...v
+          .split(",")
+          .map((s) => s.trim().replace(/^\.\//, ""))
+          .filter(Boolean),
+      );
       i += consumed("--files", i);
+    } else if (t === "--key" || t.startsWith("--key=")) {
+      const v = flagVal("--key", i);
+      if (!v || v.startsWith("--")) {
+        console.error(
+          `--key needs a value — usage: ${memCmd} find --key fix-stop-dedupe`,
+        );
+        process.exit(1);
+      }
+      // No KEY_RE validation on the read side — a wrong-pattern key never
+      // exists in the log, so the engine answers with knownKeys instead.
+      key = v;
+      i += consumed("--key", i);
     } else if (t === "--since" || t.startsWith("--since=")) {
       const v = flagVal("--since", i);
       if (!v || v.startsWith("--")) {
@@ -146,17 +181,20 @@ export const cmdFind = (a: string[]) => {
     }
   }
 
+  const kind = kindAcc.length ? kindAcc : undefined;
+  const files = filesAcc.length ? filesAcc : undefined;
   const q = positional.join(" ").trim();
   if (
     !q &&
     !kind?.length &&
     !files?.length &&
+    !key &&
     !sinceRaw &&
     limit === undefined &&
     !open
   ) {
     console.error(
-      `usage: ${memCmd} find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--open]`,
+      `usage: ${memCmd} find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--key k] [--open]`,
     );
     process.exit(1);
   }
@@ -172,21 +210,24 @@ export const cmdFind = (a: string[]) => {
   }
 
   // allRows, not rows: find is recall — rotated history counts
-  const { rows: newest } = engineFind(allRows(), {
+  const result = engineFind(allRows(), {
     text: q || undefined,
     files,
     kind,
     excludeKind: kind?.length ? undefined : CLI_FIND_EXCLUDE,
     sinceIso,
+    key,
     limit,
     open: open || undefined,
   });
   // Legacy order: oldest first (engine returns newest first — same set, CLI print order unchanged)
-  const hits = [...newest].reverse();
+  const hits = [...result.rows].reverse();
   for (const r of hits) {
     if ("id" in r) {
+      // #key only when present — rows without one keep the old shape
+      const keyTag = r.key ? ` #${r.key}` : "";
       console.log(
-        `- [${r.id}] ${r.ts.slice(0, 10)} ${r.kind} ${r.text ?? ""}${r.spec ? ` → ${r.spec}` : ""}`,
+        `- [${r.id}] ${r.ts.slice(0, 10)} ${r.kind}${keyTag} ${r.text ?? ""}${r.spec ? ` → ${r.spec}` : ""}`,
       );
     } else {
       const label = "ref" in r && r.ref ? `${r.ref}(${r.kind})` : r.kind;
@@ -194,7 +235,19 @@ export const cmdFind = (a: string[]) => {
       console.log(`- [${label}] ${r.ts.slice(0, 10)} ${r.kind} ${body}`);
     }
   }
-  if (!hits.length) console.log("(no matches)");
+  if (!hits.length) {
+    // A wrong key answers with the real ones (SPEC fail example) — a silent
+    // empty would read as "this problem never happened" (rule 9).
+    if (key && result.knownKeys) {
+      console.log(
+        `no key ${key}; known keys: ${
+          result.knownKeys.length ? result.knownKeys.join(", ") : "(none)"
+        }`,
+      );
+    } else {
+      console.log("(no matches)");
+    }
+  }
 };
 
 /** Read a plan file and extract checked + unchecked items from the first ## section. */
@@ -500,6 +553,8 @@ export const cmdKickoff = (a: string[]) => {
   if (!arg && !planFile) {
     // no args = ranked open rows + next up + recent closes
     console.log(`# ${app} — ${all.length} entries`);
+    const keys = openKeysLine(all);
+    if (keys) console.log(keys);
 
     const open = openRows(all);
     const claims = claimsOf(all);

package/src/mem/commands/write.ts

@@ -19,30 +19,87 @@ export const cmdAdd = async (a: string[]) => {
   // PLAN-convention-debt chunk 3: files[] is required — a measured optional field
   // had fill rate 0 (required+enum = 50/50) and recall on old logs without files[] caught only
   // 48.1% — fix the write side, not the read side: a row that does not name the file = unfindable when you touch that file
-  const filesFlagIdx = a.indexOf("--files");
-  const filesVal = filesFlagIdx >= 0 ? a[filesFlagIdx + 1] : undefined;
-  if (!filesVal || filesVal.startsWith("--")) {
+
+  // Positional reparse (PLAN-comma-x chunk 2): walk argv once, consume every
+  // known flag occurrence, keep the rest as positional = text + optional
+  // trailing spec.md. The old filter removed only the first --files value by
+  // identity, so `--files a --files b` left the stray `b` in the row text
+  // (live corruption, row muds6zg5) — and a text word equal to the files
+  // value was eaten instead. Flag strip stays positional, never by value:
+  // a key like "fix" may legitimately sit inside the text.
+  const positional: string[] = [];
+  const rawFiles: string[] = [];
+  let filesValueMissing = false;
+  let useStdin = false;
+  let sawKey = false;
+  let keyVal: string | undefined;
+  const rest = a.slice(1);
+  for (let i = 0; i < rest.length; i++) {
+    const t = rest[i];
+    if (t === "--stdin") {
+      useStdin = true;
+      continue;
+    }
+    if (t === "--files") {
+      const v = rest[i + 1];
+      if (v !== undefined && !v.startsWith("--")) {
+        rawFiles.push(v);
+        i++;
+      } else {
+        filesValueMissing = true; // dies in validation below
+      }
+      continue;
+    }
+    if (t === "--key" || t.startsWith("--key=")) {
+      const eq = t.startsWith("--key=");
+      const v = eq ? t.slice("--key=".length) : rest[i + 1];
+      if (!sawKey) {
+        sawKey = true;
+        keyVal = v; // first occurrence wins — validated below
+      }
+      // Consume the value token on every occurrence so a stray repeat never
+      // leaks into the text (same leak class as a repeated --files).
+      if (!eq && v !== undefined && !v.startsWith("--")) i++;
+      continue;
+    }
+    positional.push(t);
+  }
+
+  // Validation order unchanged from the old parser: files → key → hold → text.
+  if (filesValueMissing || rawFiles.length === 0) {
     console.error(
       `--files is required — usage: ${memCmd} add ${a[0]} "<text>" --files path/to/file.ts[,more] [spec.md]`,
     );
     process.exit(1);
   }
-  const files = filesVal
-    .split(",")
-    .map((s) => s.trim().replace(/^\.\//, ""))
-    .filter(Boolean);
-  if (files.length === 0) {
+  const files: string[] = [];
+  for (const v of rawFiles) {
+    const parts = v
+      .split(",")
+      .map((s) => s.trim().replace(/^\.\//, ""))
+      .filter(Boolean);
+    if (parts.length === 0) {
+      console.error(
+        `--files needs at least one path — usage: ${memCmd} add ${a[0]} "<text>" --files path/to/file.ts[,more]`,
+      );
+      process.exit(1);
+    }
+    files.push(...parts);
+  }
+  // --key is optional; pattern validation lives in engineAdd (one checker,
+  // both surfaces — PLAN-mem-keys chunk 1). argv layer only extracts it.
+  // Accepts `--key value` and `--key=value` alike (same as cmdFind) — an
+  // exact-match lookup for "--key" would leave a `--key=x` token inside the
+  // text and write a keyless row with exit 0 (silent drop, never allowed).
+  if (sawKey && (!keyVal || keyVal.startsWith("--"))) {
     console.error(
-      `--files needs at least one path — usage: ${memCmd} add ${a[0]} "<text>" --files path/to/file.ts[,more]`,
+      `--key needs a value — usage: ${memCmd} add ${a[0]} "<text>" --files f1,f2 --key fix-stop-dedupe`,
     );
     process.exit(1);
   }
-  const arg = a.slice(1);
-  const useStdin = arg.includes("--stdin");
-  const filtered = arg.filter(
-    (x) => x !== "--stdin" && x !== "--files" && x !== filesVal,
-  );
-  const spec = filtered.at(-1)?.endsWith(".md") ? filtered.pop() : undefined;
+  const spec = positional.at(-1)?.endsWith(".md")
+    ? positional.pop()
+    : undefined;
   if (a[0] === "hold" && !spec) {
     console.error(
       `hold requires a spec — usage: ${memCmd} add hold "..." --files f1,f2 <spec.md>`,
@@ -58,18 +115,18 @@ export const cmdAdd = async (a: string[]) => {
     }
   } else {
     // text is required
-    if (!filtered.length || (filtered.length === 0 && !spec)) {
+    if (positional.length === 0) {
       console.error(
         `text is required — usage: ${memCmd} add <kind> "<text>" --files f1,f2 [spec.md]`,
       );
       process.exit(1);
     }
-    text = filtered.join(" ");
+    text = positional.join(" ");
   }
   // 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).
   try {
-    const { id } = engineAdd({ kind: a[0], text, spec, files });
+    const { id } = engineAdd({ kind: a[0], text, spec, files, key: keyVal });
     console.log(id);
   } catch (e) {
     if (e instanceof CapError) {

package/src/mem/engine.ts

@@ -10,6 +10,7 @@
 // does it at dispatch, the MCP wrapper does it per call with its worktree.
 // (PLAN-unify-mem-engine chunk 1)
 
+import { KEY_RE } from "../core/mem-log.js";
 import { openRows } from "./selectors.js";
 import { KINDS, nextId, put, rows, type WorkKind } from "./store.js";
 
@@ -35,6 +36,8 @@ export interface EngineAddArgs {
   text: string;
   files: string[];
   spec?: string;
+  /** Problem identity — optional, but validated against KEY_RE whenever present. */
+  key?: string;
 }
 
 export interface EngineAddResult {
@@ -43,6 +46,7 @@ export interface EngineAddResult {
   text: string;
   files: string[];
   spec?: string;
+  key?: string;
   ts: string;
 }
 
@@ -60,6 +64,13 @@ export function engineAdd(a: EngineAddArgs): EngineAddResult {
   if (a.kind === "hold" && !a.spec) {
     throw new Error("hold requires a spec — pass spec: <path/to/SPEC.md>");
   }
+  // One validator for both surfaces (CLI argv reaches here too) — reject loudly
+  // 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}"`,
+    );
+  }
 
   const all = rows();
   if (a.kind === "next" && !process.env.MEM_FORCE) {
@@ -83,14 +94,27 @@ export function engineAdd(a: EngineAddArgs): EngineAddResult {
 
   const id = nextId(all);
   const ts = new Date().toISOString();
+  // Every row written from here on is v:2 — key optional, but the version
+  // stamps the schema so a reader can tell new rows from v:1 legacy ones.
+  // JSON.stringify drops the undefined key, so keyless rows carry only v.
   put({
     id,
     kind: a.kind as WorkKind,
     text: a.text,
     spec: a.spec,
     files: a.files,
+    key: a.key,
+    v: 2,
   });
-  return { id, kind: a.kind, text: a.text, files: a.files, spec: a.spec, ts };
+  return {
+    id,
+    kind: a.kind,
+    text: a.text,
+    files: a.files,
+    spec: a.spec,
+    key: a.key,
+    ts,
+  };
 }
 
 export interface EngineCloseArgs {
@@ -165,11 +189,20 @@ export interface EngineFindArgs {
    * qualify. Default false — recall shows closed rows too.
    */
   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.
+   */
+  key?: string;
 }
 
 export interface EngineFindResult<T> {
   rows: T[];
   total: number;
+  /** Present only on a pure key miss — every distinct key in `all`, sorted. */
+  knownKeys?: string[];
 }
 
 export type FindableRow = {
@@ -178,6 +211,7 @@ export type FindableRow = {
   spec?: string;
   ref?: string;
   files?: string[];
+  key?: string;
   ts: string;
 };
 
@@ -214,6 +248,34 @@ 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.
+  let knownKeys: string[] | undefined;
+  if (a.key) {
+    const want = a.key;
+    const idKey = new Map<string, string>();
+    for (const r of all) {
+      if ("id" in r && typeof r.id === "string" && r.key) {
+        idKey.set(r.id, r.key);
+      }
+    }
+    const eff = (r: T): string | undefined =>
+      r.key ??
+      (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)) {
+      const distinct = new Set<string>();
+      for (const r of all) {
+        if (r.key) distinct.add(r.key);
+      }
+      knownKeys = [...distinct].sort();
+    }
+  }
+
   if (a.text?.trim()) {
     const needle = a.text.toLowerCase();
     out = out.filter((r) =>
@@ -245,5 +307,9 @@ export function engineFind<T extends FindableRow>(
 
   const total = out.length;
   const limit = Math.max(0, a.limit ?? FIND_DEFAULT_LIMIT);
-  return { rows: out.slice(0, limit), total };
+  return {
+    rows: out.slice(0, limit),
+    total,
+    ...(knownKeys ? { knownKeys } : {}),
+  };
 }

package/src/mem/index.ts

@@ -25,9 +25,9 @@ const MEM_HELP = `usage: fapony mem [--mem-dir <path>] <sub> [args]
 subcommands:
   where                       show the resolved mem dir and which step won
   kickoff [<plan.md>] [--pick <n>]   open a session + a next-up list
-  add <kind> "<text>" --files f1,f2 [spec.md]
+  add <kind> "<text>" --files f1,f2 [--key k] [spec.md]
   close <id> "<msg>"          close a bug
-  find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n]
+  find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--key k]
                           substring-search every row (archives included)
   done | stale              views
   claim <id> | release <id> | synced   bookkeeping
@@ -49,19 +49,21 @@ open a session and print a "next up" list (priority plans, unchecked chunks, ope
   <plan.md>   plan whose first unchecked chunk is offered as a context line
   --pick <n>  run suggestion [n] non-interactively; refuses context/template items
 example: fapony mem kickoff .fapony/plan/PLAN-x.md`,
-  add: `usage: fapony mem add <next|bug|decision|note|hold> "<text>" --files f1,f2 [spec.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)
   --stdin         read <text> from stdin (avoids shell metachar)
-example: fapony mem add decision "chose X because Y" --files src/a.ts,src/b.ts`,
+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>"
 tombstone a bug so it stops showing as open work
   --stdin         read the message from stdin
 example: fapony mem close mt14 "fixed in a2c6beb"`,
-  find: `usage: fapony mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n]
+  find: `usage: fapony mem find ["<text>"] [--kind a,b] [--files f1,f2] [--since <N>d|YYYY-MM-DD] [--limit n] [--key k]
 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
   --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/render.ts

@@ -6,7 +6,10 @@ import type { ClaimRow, CloseRow, LogRow, WorkRow } from "./store.js";
 export const fmtRow = (r: WorkRow, claims?: Map<string, ClaimRow>) => {
   let s = `- [${r.id}]`;
   if (claims?.has(r.id)) s += ` (${claims.get(r.id)?.agent})`;
-  s += ` ${r.kind} ${r.text}`;
+  s += ` ${r.kind}`;
+  // key only when present — rows without one stay byte-identical
+  if (r.key) s += ` #${r.key}`;
+  s += ` ${r.text}`;
   if (r.spec) s += ` → ${r.spec}`;
   return s;
 };

package/src/mem/selectors.ts

@@ -25,6 +25,19 @@ export const openRows = (all: LogRow[]): WorkRow[] => {
   );
 };
 
+// Distinct keys on open work rows, sorted — the important-index ingredient
+// (PLAN-mem-keys chunk 3). A key is open while ≥1 keyed row survives the
+// tombstone set; computed live like every other selector, never persisted.
+export const openKeys = (all: LogRow[]): { key: string; open: number }[] => {
+  const counts = new Map<string, number>();
+  for (const r of openRows(all)) {
+    if (r.key) counts.set(r.key, (counts.get(r.key) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([key, open]) => ({ key, open }))
+    .sort((a, b) => a.key.localeCompare(b.key));
+};
+
 // C) claimsOf: returns Map ref → latest claim row still active
 // active = the latest claim|release row is a claim and ref is not in dead (close)
 export const claimsOf = (all: LogRow[]): Map<string, ClaimRow> => {

package/src/mem/store.ts

@@ -34,6 +34,8 @@ type WorkRow = {
   text: string;
   spec?: string;
   files?: string[];
+  key?: string;
+  v?: number;
 };
 
 type CloseRow = {