@viloforge/vfkb 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vilosource
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# vfkb — ViloForge KnowledgeBase
+
+> Decision-grade, git-native memory for AI coding agents.
+> *They remember what was said. vfkb remembers what your project decided — with rationale, lifecycle, and receipts.*
+
+[![review-gate](https://github.com/vilosource/vfkb/actions/workflows/review-gate.yml/badge.svg)](https://github.com/vilosource/vfkb/actions/workflows/review-gate.yml)
+[![test](https://github.com/vilosource/vfkb/actions/workflows/test.yml/badge.svg)](https://github.com/vilosource/vfkb/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](package.json)
+
+vfkb is a **per-project knowledge substrate for coding agents**: an append-only JSONL brain
+(`.vfkb/entries.jsonl`) that lives *inside your repo*, travels with every clone and branch, and is
+injected into agent sessions automatically. One TypeScript engine — **zero runtime dependencies**
+(Node stdlib; only the MCP server adds `@modelcontextprotocol/sdk` + `zod`) — exposed through
+three faces: **Claude Code hooks**, an in-process **[Pi](https://github.com/earendil-works/pi)
+extension**, and a **9-tool MCP server** any MCP client can pull from.
+
+This repo dogfoods itself: [`.vfkb/`](.vfkb/) is vfkb's own committed brain — 200+ entries of the
+decisions, gotchas and handoffs that built it.
+
+---
+
+## Contents
+
+- [Why vfkb](#why-vfkb)
+- [How it compares](#how-it-compares)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [How it works](#how-it-works)
+- [Proving it works](#proving-it-works)
+- [Key concepts](#key-concepts)
+- [Requirements](#requirements)
+- [Documentation](#documentation)
+- [Project status](#project-status)
+- [Lineage & acknowledgements](#lineage--acknowledgements)
+- [License](#license)
+
+---
+
+## Why vfkb
+
+AI coding agents start every session from zero. The architect that plans your payment system knows
+nothing about your payment system. An executor discovers "money needs Postgres `NUMERIC`, not
+float," fixes it, ships — and the next task makes the same mistake, because the lesson was never
+written anywhere an agent will read. The human ends up being the only shared memory between
+agents, which makes the human the bottleneck.
+
+Most "AI memory" products attack this by remembering **conversations** — extract facts from chat,
+embed them, retrieve them semantically. vfkb attacks a different problem: preserving a project's
+**engineering judgment**. That demands properties conversation-recall systems don't have:
+
+|                                                        | Chat history | `CLAUDE.md` / `AGENTS.md` | Hosted memory platforms | Vector RAG | **vfkb** |
+|--------------------------------------------------------|:---:|:---:|:---:|:---:|:---:|
+| Structured entries (type, tags, provenance)            | ✗ | ✗ | ~ | ~ | **✓** |
+| Decision lifecycle (immutable, supersede-only, status)  | ✗ | ✗ | ✗ | ✗ | **✓** |
+| Trust model: operator-verified ≠ agent-asserted         | ✗ | ✗ | ✗ | ✗ | **✓** |
+| Stale / superseded knowledge filtered out at inject     | ✗ | ✗ | ~ | ✗ | **✓** |
+| Git-native: diffable, branchable, reviewed in PRs       | ✗ | ✓ | ✗ | ✗ | **✓** |
+| Auto-injected at session start (no retrieval round-trip)| ✗ | ✓ (always on) | ~ | ✗ | **✓** |
+| Deterministic & offline — no embeddings, server, or API keys | ✓ | ✓ | ✗ | ✗ | **✓** |
+| Says "no recorded entry" instead of guessing            | ✗ | ✗ | ✗ | ✗ | **✓** |
+
+Two things follow from the git-native choice that no external memory store can offer:
+
+1. **Memory rides code review.** Knowledge changes are diffs; a wrong "fact" is caught in a PR like
+   a wrong line of code. Branches carry their own knowledge, and concurrent sessions merge
+   conflict-free (`merge=union` on the append-only log, plus a cross-process lock).
+2. **Memory has provenance you can audit.** Every entry records who wrote it (human / agent /
+   import), whether it was verified, when it expires, and — for decisions — *why*, what it
+   superseded, and its lifecycle status. Trust is **derived**, never self-declared.
+
+## How it compares
+
+Feature-level differences against the systems we studied, per their public docs as of mid-2026 —
+these are good tools solving a *different* problem:
+
+- **[mem0](https://github.com/mem0ai/mem0)** — a universal memory layer: an LLM extraction
+  pipeline over conversations, stored in your choice of ~20 vector stores or a managed platform,
+  retrieved semantically. Optimized for user/session personalization at scale. vfkb stores what a
+  *human or agent deliberately recorded* about a *project* — no extraction step, no embeddings, no
+  hosted service, and agent-written entries are explicitly second-class until verified.
+- **[Zep / Graphiti](https://github.com/getzep/graphiti)** — a temporal knowledge graph where
+  facts carry validity windows; strong at "what was true when." vfkb's validity is explicit rather
+  than inferred (validity windows, `stale`/`expired` provenance, and supersede chains an operator
+  can read as an ADR log), and it needs no graph service — the brain is a text file in your repo.
+- **[Letta (MemGPT)](https://github.com/letta-ai/letta)** — an agent runtime with OS-style memory
+  tiers managed by the agent itself. vfkb is the opposite shape: not a runtime, but a substrate
+  *under* whatever harness you already run (Claude Code, Pi, anything speaking MCP).
+- **[MemPalace](https://github.com/MemPalace/mempalace)** — local-first, verbatim conversation
+  storage with scoped semantic search. Shares vfkb's local-first stance; differs on what's worth
+  keeping (verbatim transcripts vs. curated, typed judgment) and on retrieval (embeddings vs.
+  deterministic lexical search with an honest no-match).
+- **`CLAUDE.md` / `AGENTS.md` files** — the right instinct (project knowledge in the repo), but
+  flat prose: no types, no provenance, no lifecycle, no queries, always fully in context. vfkb
+  *generates* an `AGENTS.md` projection from the brain (`vfkb export agents-md`) so you can have
+  both.
+
+## Install
+
+### From source
+
+```bash
+git clone https://github.com/vilosource/vfkb.git
+cd vfkb
+npm install
+npm run build      # tsc → dist/ (no native modules)
+npm test           # vitest — 265 deterministic tests
+
+node dist/cli.js --help          # the CLI
+node dist/mcp-server.js          # the MCP server (stdio)
+```
+
+### As a Claude Code plugin (the auto-layer)
+
+The [vfkb-claude-plugin](https://github.com/vilosource/vfkb-claude-plugin) bundles the engine,
+MCP server, and hooks so a Claude Code session runs on vfkb automatically — session-start
+injection, brain-write gating, end-of-turn decision reminders, and session-end auto-commit.
+See that repo for install instructions and its current, mechanically-tracked
+[delivery status](https://github.com/vilosource/vfkb-claude-plugin/blob/main/DELIVERY-STATUS.json).
+
+### As an MCP server (any harness)
+
+Point any MCP client at `dist/mcp-server.js` with `VFKB_DATA_DIR` set to the brain directory:
+
+```json
+{ "mcpServers": { "vfkb": { "command": "node", "args": ["dist/mcp-server.js"],
+                            "env": { "VFKB_DATA_DIR": ".vfkb" } } } }
+```
+
+Nine tools: `kb_add` · `kb_get` · `kb_list` · `kb_map` · `kb_context` · `kb_search` ·
+`kb_supersede` · `kb_transition` · `kb_resume`. For Pi there is also
+`dist/pi-mcp-bridge.js`, an extension that gives Pi Claude-compatible MCP support
+(`mcp__<server>__<tool>` naming).
+
+## Quick start
+
+```bash
+alias vfkb='VFKB_DATA_DIR=.vfkb node /path/to/vfkb/dist/cli.js'
+
+vfkb init                    # scaffold this repo as a vfkb consumer (.vfkb/ + wiring)
+
+# Record knowledge — deliberate, typed, attributed
+vfkb add fact "The API gateway strips the X-Request-Id header" --tag networking --role human
+vfkb add gotcha "pgbouncer in transaction mode breaks LISTEN/NOTIFY" --tag database --role human
+vfkb add decision "Use NUMERIC for money columns" \
+  --why "float rounding lost cents in reconciliation" --role human
+vfkb add link "Payment flow design" "docs/design/payments.md" --role human
+
+# Query it
+vfkb list --tag networking --limit 5     # newest 5 entries carrying the tag
+vfkb search "money columns" --type decision --verified
+vfkb map                                 # what knowledge exists, at a glance
+vfkb context                             # the project context doc — an agent's first read
+
+# Session continuity
+vfkb resume                              # what the last session did + the live knowledge bundle
+vfkb resume-note "next: wire the ALB target group"
+
+# Lifecycle — decisions are immutable; supersede, never edit
+vfkb supersede <id> "Use NUMERIC(19,4) for money columns" --why "scale fixed by audit" --role human
+
+# Health + delivery
+vfkb doctor                              # brain/engine/wiring diagnosis, incl. plugin staleness
+vfkb save                                # commit the brain (it ships with your repo)
+vfkb export agents-md                    # generate an AGENTS.md projection for non-vfkb tooling
+```
+
+Unknown or repeated flags **error loudly** — silent argument drops are treated as bugs here
+(see [issue #95](https://github.com/vilosource/vfkb/issues/95) for the class this killed).
+
+## How it works
+
+### The entry envelope
+
+The atomic unit is a typed entry: **fact**, **decision**, **gotcha**, **pattern**, or **link** —
+with tags, a lifecycle **zone** (`incoming` → `established` → `archive`), **provenance**
+(`verified` / `unverified` / `stale` / `expired`, plus a validity window), and an author role from
+which **trust is derived** (operator / agent / import). Decisions additionally carry rationale
+(`why`), a status (`proposed` → `accepted` → `deprecated` / `superseded`), optional
+**constitutional** weight (always injected, leads every session), and supersede references — an
+ADR log the engine can execute.
+
+### The storage kernel
+
+One append-only JSONL file, materialized last-write-wins with tombstones. No database, no
+server, no native modules. `merge=union` in `.gitattributes` makes concurrent branch writes
+merge conflict-free by construction; a cross-process lock serializes the read-decide-append
+critical section for same-machine concurrency. The search index is derived and rebuildable —
+the log is the only source of truth.
+
+### Injection, not retrieval
+
+At session start the harness face injects a **resume digest** (what the last session added,
+superseded, captured — *recomputed from the brain*, never a stale summary) plus a **knowledge
+bundle**: constitutional decisions first, then the pinned handoff, then relevance-filtered
+entries. Stale, expired, superseded, and archived knowledge is filtered out *before* the agent
+sees it. On-demand search is a deterministic two-stage lexical retriever with a relevance floor
+and an honest empty result: `NO-MATCH` with a cause ("no recorded entry" vs. "all matches
+stale"), because a memory that guesses is worse than no memory.
+
+### Guardrails
+
+- **Write-time no-secrets lint** — planted credentials are rejected at `add`, not found in review.
+- **Tool gating** — the Claude Code `PreToolUse` hook denies direct edits to `.vfkb/`, forcing
+  writes through the engine (and its lint, lock, and envelope validation).
+- **Hooks fail open** — a malformed payload or crash never wedges the host session.
+- **Session-end auto-commit** — the brain is committed on exit (topic branches only, pathspec-
+  scoped, never `main`), so `/exit` doesn't lose the day's knowledge.
+
+## Proving it works
+
+Unit tests prove the modules; they cannot prove an agent *behaves better because of vfkb*. So
+every user-facing capability ships behind an **agent-driven scenario harness** (L4): a real agent
+(Pi/DeepSeek and Claude Code arms) runs in a dockerized sandbox against the real surface, scored
+on **observable effects** — the agent's output or the brain's state, never self-report — and
+always against a **contrast arm** (no memory, or a naive flat-dump memory) so the win is shown to
+be *caused* by vfkb. A capability is DEMONSTRATED at ≥2/3 trials, and the records are committed
+under [`scenarios/records/`](scenarios/records/). A proof that cannot fail proves nothing — every
+harness carries an arm that can go red, and several have (that's how they earn trust).
+
+The same standard applies to the project's own process: every implementation PR carries an
+adversarial review record ([`reviews/`](reviews/)) verified by a deterministic CI gate, and the
+project's Definition of Done ([ADR-0050](docs/adr/ADR-0050-l4-dod-constitutional-brake.md),
+[ADR-0051](docs/adr/ADR-0051-delivery-honesty.md)) forbids calling anything "done" that hasn't
+been *observed* working — a rule vfkb's own brain enforces on every session it boots.
+
+## Key concepts
+
+| Term | Meaning |
+|------|---------|
+| **Brain** | The per-project knowledge store — `.vfkb/entries.jsonl`, committed with the repo. |
+| **Entry** | Atomic unit: fact, decision, gotcha, pattern, or link — typed, tagged, attributed. |
+| **Decision family** | Immutable entries with lifecycle status and supersede chains; an executable ADR log. `proposed` decisions are RFCs. |
+| **Constitutional** | A decision injected at the top of *every* session — the project's non-negotiables. |
+| **Zone** | Lifecycle stage: `incoming` (unproven) → `established` (trusted set) → `archive`. |
+| **Provenance** | Verification state (`verified`/`unverified`/`stale`/`expired`) + validity window + origin. |
+| **Trust** | Derived from author role: operator / agent / import. Agents cannot self-promote. |
+| **Handoff** | A tagged fact carrying session-to-session continuity; pinned in the resume render. |
+| **Curator** | Deliberate promotion/archive/merge operations — deltas only, never text rewrites. |
+| **L4 scenario** | An agent-driven, sandboxed, contrast-armed proof that a capability changes real agent behavior. |
+
+## Requirements
+
+- **Node.js ≥ 20**
+- **git** (the brain rides your repo)
+- No native modules, no database, no API keys. Runtime deps: `@modelcontextprotocol/sdk` + `zod`
+  (MCP server only — the engine itself is stdlib).
+
+## Documentation
+
+- [`docs/DESIGN.md`](docs/DESIGN.md) — engineering design; [`docs/FEATURES.md`](docs/FEATURES.md)
+  — the verified feature reference (every feature marked BUILT / PARTIAL / GATED).
+- [`docs/adr/`](docs/adr/) — 52 architecture decision records (Nygard format, immutable);
+  [`docs/rfc/`](docs/rfc/) — 24 RFCs. The project practices what it stores: decisions before code.
+- [`docs/STATUS-AND-ROADMAP.md`](docs/STATUS-AND-ROADMAP.md) — north star;
+  [`docs/H4-DEVELOPMENT-ROADMAP.md`](docs/H4-DEVELOPMENT-ROADMAP.md) — execution authority.
+
+## Project status
+
+**Alpha, used in anger daily.** The v1 per-project tier and the v2 storage/session backbone are
+built and shipped; 265 deterministic tests plus the L4 scenario suite. vfkb develops itself on its
+own brain (200+ committed entries) — every session that builds vfkb resumes from vfkb. Public API,
+CLI surface, and storage schema may still move before 1.0. Part of the
+[ViloForge](https://github.com/vilosource) ecosystem: [vfwb](https://github.com/vilosource/vfwb)
+(the planning workbench that grounds against vfkb) is in design.
+
+## Lineage & acknowledgements
+
+vfkb is the third generation of one idea — *agents deserve a project memory with provenance*:
+
+- **[OSB — OpenSecondBrain](https://github.com/vilosource/osb)** (Go) proved the knowledge model
+  (facts/decisions/gotchas/patterns with provenance) on Claude Code via file conventions and
+  adapter prompts.
+- **[mykb](https://github.com/vilosource/mykb)** (TypeScript, [Pi](https://github.com/earendil-works/pi))
+  proved mechanical enforcement: three-tier context delivery, tool gating, and the JSONL+SQLite
+  hybrid — with storage prior art from
+  [Engram](https://github.com/Gentleman-Programming/engram) and
+  [Beads](https://github.com/gastownhall/beads).
+- **vfkb** is the greenfield reimplementation for fleet use: pure-stdlib engine, harness-portable
+  faces (hooks / extension / MCP), the decision family, derived trust, and the L4 evidence
+  culture.
+
+We also studied [MemPalace](https://github.com/MemPalace/mempalace) — its local-first,
+zero-API-call stance is the right one, and vfkb shares it while betting on curated judgment over
+verbatim recall. Thanks to Mario Zechner's [Pi](https://github.com/earendil-works/pi) for the
+harness extensibility the Pi face builds on.
+
+## License
+
+[MIT](LICENSE) © vilosource

package/dist/args.js

@@ -0,0 +1,82 @@
+// Strict CLI argument parsing (issue #95 — the silent-flag family).
+// Every verb declares its flags; anything unknown or repeated ERRORS instead of
+// being silently ignored. The `hook` subcommands are intentionally NOT parsed
+// through this — the harness hook contract is fail-open (a hook must never
+// wedge a session over an argv quirk).
+/** A user-facing argv mistake — the CLI prints the message + usage and exits 1. */
+export class UsageError extends Error {
+}
+export function parseArgs(verb, args, spec) {
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith('--')) {
+            positionals.push(a);
+            continue;
+        }
+        const name = a.slice(2);
+        const kind = spec[name];
+        if (!kind) {
+            throw new UsageError(`unknown flag --${name} for '${verb}'${didYouMean(name, spec)}${knownFlags(spec)}`);
+        }
+        if (flags.has(name)) {
+            throw new UsageError(`repeated flag --${name} for '${verb}' — give it once` +
+                (kind === 'value' ? ` (use a comma-separated value for multiples, e.g. --${name} a,b)` : ''));
+        }
+        if (kind === 'boolean') {
+            flags.set(name, true);
+            continue;
+        }
+        const next = args[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            if (kind === 'optional-value') {
+                flags.set(name, true);
+                continue;
+            }
+            throw new UsageError(`flag --${name} for '${verb}' requires a value`);
+        }
+        flags.set(name, next);
+        i++;
+    }
+    return { verb, positionals, flags };
+}
+/** String value of a flag, if given with one. */
+export function flagValue(p, name) {
+    const v = p.flags.get(name);
+    return typeof v === 'string' ? v : undefined;
+}
+/** Comma-separated flag → trimmed non-empty list (undefined when absent).
+ *  A given-but-empty value (--tag "" / --tag ,,,) ERRORS — it would otherwise
+ *  silently mean "no filter" on list and "untagged" on add (the #95 class). */
+export function flagList(p, name) {
+    const v = flagValue(p, name);
+    if (v === undefined)
+        return undefined;
+    const items = v.split(',').map((t) => t.trim()).filter(Boolean);
+    if (items.length === 0) {
+        throw new UsageError(`flag --${name} for '${p.verb}' must be a non-empty comma-separated list (got '${v}')`);
+    }
+    return items;
+}
+/** Positive-integer flag; errors on anything else (silent NaN was the old behavior). */
+export function flagInt(p, name) {
+    const v = flagValue(p, name);
+    if (v === undefined)
+        return undefined;
+    if (!/^\d+$/.test(v) || Number(v) < 1) {
+        throw new UsageError(`flag --${name} for '${p.verb}' must be a positive integer (got '${v}')`);
+    }
+    return Number(v);
+}
+function didYouMean(name, spec) {
+    // The observed trap: --tags for --tag (four real entries landed untagged).
+    const singular = name.replace(/s$/, '');
+    if (singular !== name && spec[singular])
+        return ` — did you mean --${singular} a,b (comma-separated)?`;
+    return '';
+}
+function knownFlags(spec) {
+    const names = Object.keys(spec);
+    return names.length ? ` (known: ${names.map((n) => `--${n}`).join(', ')})` : ' (it takes no flags)';
+}

package/dist/backend.js

@@ -0,0 +1,115 @@
+// ADR-0044 (v2): the storage-backend interface — the seam the engine's persistence
+// flows through instead of assuming a local file directly. Exactly ONE implementation
+// ships in v2: JSONL-on-disk, matching ADR-0019 byte-for-byte (zero behavior change —
+// the DoD is the full pre-existing suite passing unchanged). A second (hosted) backend
+// is explicitly NOT decided here; `setStorageBackend` is the future opt-in door.
+//
+// Layering: engine.ts → storage.ts (backend-AGNOSTIC policy: LWW materialization,
+// ADR-0042 normalization, ADR-0014 meta derivation) → this interface (transport:
+// where records/spine/meta/session records physically live, and what "exclusive"
+// means there — a lockfile here, a transaction in a hypothetical hosted backend).
+// Git-layer consumers (git.ts, gating.ts, stop-reminder.ts, session-end.ts) stay
+// file-based BY DESIGN: they exist because the brain is a committed file (ADR-0019);
+// a backend without that property simply doesn't wire them.
+// KNOWN HOLE (review gate, deliberate): counters.ts (.signals telemetry) is
+// engine-owned but still direct-fs — it joins the seam in whatever follow-up first
+// needs it behind one (a second backend); until then signals are local-disk-only.
+//
+// The method surface was shaped by the shipped v2 code, per RFC-019's sequencing
+// intent: records (the kernel), spine/meta (ADR-0025/0014), session records
+// (ADR-0039's registry), withExclusive (ADR-0040's critical section).
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { withBrainLock } from './lock.js';
+// One shared env resolver (review gate F3): the JSONL file, the lock, and the
+// git layer must never drift onto different directories. Call-time-only cycle
+// with storage.ts — safe (nothing dereferences at module init).
+import { brainDir } from './storage.js';
+// --- the one shipped implementation: JSONL on disk (ADR-0019) ---
+const dataDir = () => brainDir();
+const safeKey = (id) => id.replace(/[^A-Za-z0-9_-]/g, '_');
+class JsonlFsBackend {
+    name = 'jsonl-fs';
+    location() {
+        return dataDir();
+    }
+    file() {
+        return join(dataDir(), 'entries.jsonl');
+    }
+    append(rec) {
+        mkdirSync(dataDir(), { recursive: true });
+        appendFileSync(this.file(), JSON.stringify(rec) + '\n', 'utf8');
+    }
+    readAllRaw() {
+        const f = this.file();
+        if (!existsSync(f))
+            return { records: [], malformed: [] };
+        const records = [];
+        const malformed = [];
+        const lines = readFileSync(f, 'utf8').split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const l = lines[i];
+            if (l.trim().length === 0)
+                continue;
+            try {
+                records.push(JSON.parse(l));
+            }
+            catch (err) {
+                // ADR-0042: one corrupt line must not crash every read of the whole brain.
+                malformed.push({ line: i + 1, issue: `unparseable JSON: ${err.message}`, raw: l.slice(0, 200) });
+            }
+        }
+        return { records, malformed };
+    }
+    readMetaRaw() {
+        const f = join(dataDir(), 'index-meta.json');
+        return existsSync(f) ? readFileSync(f, 'utf8') : null;
+    }
+    writeMetaRaw(json) {
+        mkdirSync(dataDir(), { recursive: true });
+        writeFileSync(join(dataDir(), 'index-meta.json'), json, 'utf8');
+    }
+    readSpine() {
+        const p = this.spinePath();
+        return existsSync(p) ? readFileSync(p, 'utf8').trim() : null;
+    }
+    writeSpine(content) {
+        mkdirSync(dataDir(), { recursive: true });
+        writeFileSync(this.spinePath(), content);
+    }
+    spinePath() {
+        return join(dataDir(), 'context.md');
+    }
+    listSessionIds() {
+        const dir = join(dataDir(), '.sessions');
+        if (!existsSync(dir))
+            return [];
+        return readdirSync(dir)
+            .filter((f) => f.endsWith('.json'))
+            .map((f) => f.slice(0, -'.json'.length));
+    }
+    readSessionRecord(id) {
+        const f = join(dataDir(), '.sessions', `${safeKey(id)}.json`);
+        return existsSync(f) ? readFileSync(f, 'utf8') : null;
+    }
+    writeSessionRecord(id, json) {
+        const dir = join(dataDir(), '.sessions');
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, `${safeKey(id)}.json`), json, 'utf8');
+    }
+    withExclusive(fn) {
+        return withBrainLock(fn);
+    }
+}
+const jsonl = new JsonlFsBackend();
+let current = jsonl;
+export function storageBackend() {
+    return current;
+}
+// The future opt-in door (a hosted/alternate backend per project) and the test seam.
+// Returns the previous backend so callers can restore it.
+export function setStorageBackend(b) {
+    const prev = current;
+    current = b;
+    return prev;
+}

package/dist/bootstrap.test.js

@@ -0,0 +1,64 @@
+// ADR-0031 inner gate — the committed bootstrap guard resolves the engine via
+// $VFKB_HOME and DEGRADES GRACEFULLY when it is unset: SessionStart informs the
+// user (a valid hook payload), PreToolUse/Stop never block, and a resolved engine
+// is run transparently. This is the guardrail for "VFKB_HOME not set".
+import { describe, it, expect, beforeAll } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { initProject } from './init.js';
+let bootstrap;
+let fakeHome;
+beforeAll(() => {
+    const root = mkdtempSync(join(tmpdir(), 'vfkb-boot-'));
+    initProject(root, { project: 'demo' });
+    bootstrap = join(root, '.vfkb', 'bin', 'bootstrap.mjs');
+    // a fake $VFKB_HOME whose "engines" just echo their argv so we can see passthrough
+    fakeHome = mkdtempSync(join(tmpdir(), 'vfkb-fakehome-'));
+    const stub = 'console.log("ENGINE " + process.argv.slice(2).join(" "));';
+    writeFileSync(join(fakeHome, 'vfkb.mjs'), stub);
+    writeFileSync(join(fakeHome, 'vfkb-mcp.mjs'), stub);
+});
+function run(args, env) {
+    return spawnSync('node', [bootstrap, ...args], {
+        encoding: 'utf8',
+        env: { ...process.env, VFKB_HOME: undefined, VFKB_BUNDLE_DIR: undefined, ...env },
+    });
+}
+describe('bootstrap guard (ADR-0031)', () => {
+    it('VFKB_HOME unset + session-start: emits a clear INACTIVE banner (exit 0)', () => {
+        const r = run(['cli', 'hook', 'session-start'], { VFKB_HOME: undefined });
+        expect(r.status).toBe(0);
+        const payload = JSON.parse(r.stdout);
+        expect(payload.hookSpecificOutput.hookEventName).toBe('SessionStart');
+        expect(payload.hookSpecificOutput.additionalContext).toContain('VFKB_BUNDLE_DIR');
+        expect(payload.hookSpecificOutput.additionalContext).toContain('INACTIVE');
+    });
+    it('VFKB_HOME unset + pre-tool-use: never blocks (exit 0, no stdout payload)', () => {
+        const r = run(['cli', 'hook', 'pre-tool-use'], { VFKB_HOME: undefined });
+        expect(r.status).toBe(0);
+        expect(r.stdout.trim()).toBe('');
+        expect(r.stderr).toContain('VFKB_BUNDLE_DIR'); // informs on stderr
+    });
+    it('VFKB_HOME unset + mcp: exits cleanly (no crash)', () => {
+        const r = run(['mcp'], { VFKB_HOME: undefined });
+        expect(r.status).toBe(0);
+    });
+    it('VFKB_HOME set: runs the resolved engine transparently (passthrough)', () => {
+        const r = run(['cli', 'hook', 'session-start'], { VFKB_BUNDLE_DIR: fakeHome });
+        expect(r.status).toBe(0);
+        expect(r.stdout.trim()).toBe('ENGINE hook session-start');
+    });
+    it('VFKB_HOME still works as a deprecated alias (passthrough)', () => {
+        const r = run(['cli', 'hook', 'session-start'], { VFKB_HOME: fakeHome });
+        expect(r.status).toBe(0);
+        expect(r.stdout.trim()).toBe('ENGINE hook session-start');
+    });
+    it('VFKB_BUNDLE_DIR set but bundles missing: degrades like unset', () => {
+        const empty = mkdtempSync(join(tmpdir(), 'vfkb-empty-'));
+        const r = run(['cli', 'hook', 'session-start'], { VFKB_HOME: empty });
+        expect(r.status).toBe(0);
+        expect(JSON.parse(r.stdout).hookSpecificOutput.additionalContext).toContain('INACTIVE');
+    });
+});