create-claude-cabinet 0.45.0 → 0.47.0

package/templates/cabinet/memory-lifecycle-contract.md

@@ -0,0 +1,135 @@
+# Memory Lifecycle Contract
+
+The shared contract for how built-in memory stays bounded as it grows.
+Every component that reads or writes the memory dir follows this:
+`validate-memory.mjs`, `write-memory-file.mjs`, the `/cc-remember` and
+`/memory` skills, the `memory-index-guard` hook, and (Stage 2) the
+lifecycle verbs. Full design + cabinet critique: see
+`.claude/plans/cross-store-memory-redesign.md` (act:02d15a70 = Stage 1,
+this contract; act:45fb9169 = Stage 2, gated).
+
+## The core principle
+
+`MEMORY.md` is loaded **in full at every session start** — it competes
+for the model's context window, so it has a hard budget (≤200 lines /
+≤25KB). The disease this contract cures: the old rule required the
+eagerly-loaded index to enumerate EVERY memory file (one line each), so
+its size tracked total memory count and it overflowed forever — the
+prune→overflow→prune treadmill.
+
+The fix decouples the eager index from total volume: `MEMORY.md` is a
+bounded **working set**, not a complete catalogue. Total memory can grow
+without bound (disk and search both scale for decades); only what loads
+eagerly is bounded. This is the same shape watchtower threads already
+use — surface the current cursor, leave the history on disk.
+
+## The three blocks of MEMORY.md
+
+A well-formed `MEMORY.md` working set has three kinds of content:
+
+1. **Pinned tier (decay-exempt).** Load-bearing knowledge a fresh
+   session needs surfaced *unbidden* — hard constraints, identity, hard
+   preferences, active-project pointers. These are valuable precisely
+   because they are stable and often OLD; they must never decay out on
+   recency. The defining test: *would a session that has never seen this
+   fail without it, and would it not know to go looking?* (e.g. "CC
+   hooks read tool input from stdin, not `$CLAUDE_TOOL_INPUT`".) Mark a
+   pinned entry with `pinned: true` in its file frontmatter (the Stage-1
+   default authority; revisit in Stage 2).
+
+2. **Recency block.** The recent window of curated entries, newest
+   first, filling the remaining budget to roughly 80% of the cap.
+   Recency is a fine proxy for "likely relevant next session" for
+   episodic material — and a BAD proxy for load-bearing constraints,
+   which is exactly why they go in the pinned tier instead.
+
+3. **Region pointers.** The cue-based-retrieval tier (see below) that
+   lets everything outside the working set stay reachable without a line
+   each.
+
+## Reachability replaces enumeration
+
+The validator invariant is no longer "every file has its own index
+line." It is: **every on-disk memory file is reachable from
+`MEMORY.md`** — by one of:
+
+- a direct working-set or `MEMORY-archive.md` index line, OR
+- a **region pointer** whose glob matches the file.
+
+A file that is none of these is an orphan and fails validation.
+"Present on disk" alone is **not** reachable — that test would be
+vacuous (every file is grep-able), which would silently delete the
+guarantee rather than relax it. The point of relaxing enumeration is to
+allow *bounded* indexing (a region covers N files with one line), not to
+allow invisible files.
+
+## Region pointers
+
+A region pointer declares that a whole class of files is reachable
+without enumerating them. Format — the **backtick-quoted glob is the
+only part the validator reads**; the rest is free-text guidance:
+
+```
+- region `lesson_*.md` → older lessons; grep the memory dir
+- region `session_summary_*.md` → past session records; grep by date
+```
+
+Rules:
+
+- **Globs use `*` and `?` only**, matched against the bare filename.
+- **Region pointers are DERIVED, never authoritative.** They are
+  regenerated from what's actually on disk (by hand in Stage 1, by the
+  consolidation pass in Stage 2). A pointer whose glob matches **zero**
+  files on disk is a stale, confidently-wrong retrieval cue — *worse
+  than no map* — and **fails validation**. Fix the glob or remove it;
+  never hand-edit a pointer to claim a region that isn't there.
+- **Region pointers are for recoverable history you'd think to search**
+  (old session narratives, cooled lesson archives). They are the WRONG
+  home for latent constraints — those stay in the pinned tier, eagerly
+  present, because their value is that you retrieve them *without*
+  knowing to look.
+
+## Spill-rate instrumentation (the Stage-2 gate)
+
+`validate-memory.mjs` appends a working-set pressure sample to
+`<memoryDir>/.memory-pressure.jsonl` (a dotfile — invisible to the
+orphan scan) at most once per day, only when utilization is ≥90% of the
+budget. This measures how often the working set actually runs near its
+limit, so Stage 2 (the lifecycle verbs + a background forcing function)
+is built only if the data shows recurring pressure on authored files —
+not on a felt "it keeps overflowing" metaphor. Stage 1 alone stops the
+acute treadmill; the sampler decides whether Stage 2 is warranted.
+
+## Stage 2 (designed, gated — NOT yet built)
+
+The lifecycle verbs and their forcing function are specified in the plan
+but gated on the spill-rate data. When built they will carry these
+already-decided constraints (recorded here so Stage 1 doesn't paint them
+into a corner):
+
+- **decay** — drop an entry from the working set; the file stays
+  reachable (via a region pointer or the archive). Reversible.
+- **consolidate** — merge a cluster into one gist that ALWAYS keeps a
+  lossless `consolidated_from:` provenance pointer (lossy = dropped from
+  the working set, never erased from disk). A cluster containing a
+  pinned/load-bearing entry files to the inbox; it never auto-applies,
+  because the *gist* becomes the retrieved truth and a wrong gist erases
+  a load-bearing detail.
+- **supersede** — mark an entry false/obsolete so retrieval stops
+  surfacing it as live truth (kept on disk for audit, with a reverse
+  breadcrumb in its successor). Deferred until the frontmatter-parsing
+  question is resolved (line-scan vs. a deliberately-added dependency —
+  the repo currently refuses a YAML parser; see
+  `lesson_parsefrontmatter_flow_sequences`). supersede is a reference
+  graph: dangling targets, cycles, and re-pointing working-set/region
+  references to the superseded slug must all be validated.
+- **Cross-store fold** — for session-summaries carrying design
+  reasoning, the durable target is a committed `.claude/methodology/`
+  gist, NEVER the thread cursor (which holds understanding, not
+  narration) and NEVER a delete-in-the-same-pass (the memory dir and
+  threads are both local-only/ungit'd; append-verify-then-mark
+  `folded_into:`, reclaim in a separate idempotent sweep).
+- **Forcing function** — memory hygiene (decay/consolidate) extends
+  Ring 2-slow's existing `runMemoryHygiene`; only drift-supersede is the
+  Ring 4 memory pass. No new ring for hygiene. First passes run
+  dry-run-with-report.

package/templates/cabinet/pib-db-access.md

@@ -23,6 +23,19 @@ Check: are pib_* MCP tools available?
   NO  → use node scripts/pib-db.mjs list-projects, etc.
 ```
 
+### MCP invocation specifics (read before first use, not after a failure)
+
+Two details that otherwise cost a failed call + a `ToolSearch` round-trip
+every session:
+
+- **Full tool names are prefixed `mcp__pib-db__`** (e.g.
+  `mcp__pib-db__pib_query`). When loading deferred tools via `ToolSearch`,
+  query `select:mcp__pib-db__pib_query,mcp__pib-db__pib_list_actions` —
+  the bare `pib_*` names will not match.
+- **`pib_query`'s parameter is `sql`, not `query`.** Calling it with a
+  `query` argument fails (and can fail quietly). The CLI form is
+  `query "SQL"`; the MCP form is `{ "sql": "SELECT ..." }`.
+
 ## Available Operations
 
 | MCP Tool                   | CLI Equivalent                                  | Description                    |

package/templates/cabinet/skill-output-conventions.md

@@ -133,7 +133,41 @@ that format here; reference it.
 user's actual situation. This applies whether the choice is rendered via
 AskUserQuestion or prose — the primitive changes, the posture doesn't.
 
-## 9. Calibration Examples
+## 9. Operator-Facing Register: Plain English by Default
+
+When a skill addresses the operator about substantial work — a plan, an
+audit finding, a checkpoint decision, a status report — there are **two
+readers, and they need two registers:**
+
+- **The filed artifact** (the plan in pib-db, the finding's record, the
+  report on disk) stays **technical and complete** — exact file paths,
+  function names, fids, acceptance criteria. A future session executes
+  from it cold, so precision is the whole point.
+- **What you SAY to the operator** is **plain English** — concept first,
+  the stakes spelled out, any decision framed as options with tradeoffs.
+  Keep file paths and symbol names out of the spoken prose; they live in
+  the filed artifact, reachable on request or behind a collapsed
+  "full detail" pointer.
+
+The operator is the director, not the implementer (see the user-role
+brief): they decide *what* and *why* and must be able to weigh in without
+parsing every technical detail. A wall of paths and identifiers is noise
+to that judgment — it buries the one thing they're being asked to decide.
+Lead with what changed and why it matters; keep the file-and-line
+narrative for the record.
+
+This is the **default register** for operator-facing skill output. It
+does NOT relax the filed artifact's rigor — a plan still files
+QA-compliant notes, an audit still records exact locations. The split is
+between the *record* (technical) and the *briefing* (plain). When in
+doubt, write the briefing as if explaining to a sharp colleague who
+hasn't seen the code.
+
+This is a *register* rule (how to phrase), distinct from §5 (prose vs
+dialog as the *primitive*) and §8 (present-don't-prescribe as the
+*posture*) — all three compose.
+
+## 10. Calibration Examples
 
 **Before/after — engagement decision items** (the Tier 1 conversion):