@viloforge/vfkb 0.2.1

package/dist/stop-reminder.js

@@ -0,0 +1,130 @@
+// Stop-hook decision-capture reminder (RFC-008 / ADR-0027). A conditional,
+// once-per-turn end-of-turn nudge: when a turn plausibly made a decision but recorded
+// none, inject a reminder so the agent captures it before handing back to the user.
+//
+// Contract is EMPIRICALLY VERIFIED at Claude Code CLI v2.1.195 (brain gotcha
+// d70c0299e144): a Stop hook may emit
+//   {"hookSpecificOutput":{"hookEventName":"Stop","decision":"block","additionalContext":"…"}}
+// to continue the turn with that text as context; the harness passes `stop_hook_active`
+// (true on our own re-entry) as the NATIVE loop guard — no marker file needed.
+//
+// `decideStop` is the PURE core (deterministically unit-tested, the backstop). The git /
+// brain gathering is the impure shell, used by `cli.ts hook stop`.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { brainDir } from './storage.js';
+export const STOP_REMINDER = 'vfkb decision-capture check: this turn changed code/docs but no `decision` was recorded ' +
+    'to the brain. If a load-bearing decision was made, capture it now via ' +
+    '`mcp__vfkb__kb_add` (type=decision, why=<rationale>, role=human) — or ' +
+    '`vfkb add decision "…" --why "…" --role human` — and add an ADR under docs/adr/ for ' +
+    'anything architectural. If NO decision was made this turn, just finish normally.';
+// The strong-signal threshold: only nudge for a handoff once the session has
+// accumulated enough knowledge that a "what's next" pointer is worth writing. Below
+// this, the SessionEnd B2 floor (ADR-0033) still guarantees a committed handoff.
+export const HANDOFF_MIN_ENTRIES = 3;
+// GAP-1 B1 (RFC-011 §B): the higher-quality, agent-authored handoff nudge. The Stop
+// hook is the ONLY surface that can prompt the agent, but it fires per-turn while a
+// handoff is an end-of-session artifact — so the framing is deliberately conditional
+// ("if you're wrapping up"), letting the agent decline mid-session. It self-silences:
+// the moment ANY handoff/next entry is recorded, the trigger goes quiet (no
+// KB_SESSION_ID / per-session state needed — the side-effect it asks for is the guard).
+export const HANDOFF_REMINDER = 'vfkb handoff check: this session has recorded knowledge but no `handoff`/`next` entry. ' +
+    'If you are WRAPPING UP, record a durable handoff now — `mcp__vfkb__kb_add` ' +
+    '(type=fact, tags=handoff,next, role=human) naming what the NEXT session should pick up ' +
+    '(a real "next:", not just a summary). If you are still mid-session, ignore this and ' +
+    'finish normally — the SessionEnd floor will leave a fallback if you never do.';
+/**
+ * The pure decision. Block (inject the reminder, continuing the turn) only when a
+ * decision *plausibly* went unrecorded; otherwise allow the stop.
+ *  1. Native loop guard: never block our own re-entry (`stop_hook_active`), or it nags forever.
+ *  2. Conditional trigger: substantive work happened AND no decision was recorded this session.
+ *  (Not a true Brake — working-tree-changed ≠ decision-made; the committed ADR stays the
+ *  deterministic backstop for *significant* decisions. This just fires the nudge at the right
+ *  moment, only when plausibly needed.)
+ */
+export function decideStop(input, ctx) {
+    if (input?.stop_hook_active)
+        return { block: false };
+    const reminders = [];
+    // Decision-capture nudge (ADR-0027): work happened AND no decision recorded this session.
+    if (ctx.uncommittedWork && ctx.newDecisions === 0)
+        reminders.push(STOP_REMINDER);
+    // Handoff nudge (B1, RFC-011): work happened AND a strong-signal amount of knowledge
+    // accumulated AND no handoff/next entry yet. Self-silences once a handoff is recorded.
+    if (ctx.uncommittedWork && (ctx.newEntries ?? 0) >= HANDOFF_MIN_ENTRIES && (ctx.newHandoffs ?? 0) === 0)
+        reminders.push(HANDOFF_REMINDER);
+    if (reminders.length === 0)
+        return { block: false };
+    return { block: true, reminder: reminders.join('\n\n') };
+}
+/** Working tree has uncommitted src/ or docs/ changes (brain-only changes don't count as "work"). */
+export function hasUncommittedWork(cwd = process.cwd(), brain = brainDir()) {
+    let out;
+    try {
+        out = execFileSync('git', ['status', '--porcelain'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    catch {
+        return false; // not a repo / git missing → fail-open (don't nag)
+    }
+    const brainRel = relative(cwd, brain).replace(/\\/g, '/');
+    return out.split('\n').some((line) => {
+        const p = line.slice(3).trim(); // strip the 2-char status + space
+        if (!p)
+            return false;
+        if (brainRel && (p === brainRel || p.startsWith(brainRel + '/')))
+            return false;
+        return p.startsWith('src/') || p.startsWith('docs/');
+    });
+}
+/**
+ * Entries appended to the brain since HEAD, parsed. The brain is append-only
+ * (ADR-0019), so fresh entries are exactly the lines beyond the committed line count —
+ * no per-session state (KB_SESSION_ID) needed, and it aligns with the "record then commit"
+ * workflow: uncommitted entries are exactly this session's captures.
+ */
+export function newBrainEntriesSinceHead(brain = brainDir(), cwd = process.cwd()) {
+    const file = join(brain, 'entries.jsonl');
+    let current;
+    try {
+        current = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+    }
+    catch {
+        return []; // no brain file yet
+    }
+    const rel = relative(cwd, file).replace(/\\/g, '/');
+    let headCount = 0;
+    try {
+        const head = execFileSync('git', ['show', `HEAD:${rel}`], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+        headCount = head.split('\n').filter(Boolean).length;
+    }
+    catch {
+        headCount = 0; // file not in HEAD / no repo → treat all current as fresh
+    }
+    return current
+        .slice(headCount)
+        .map((l) => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e !== null);
+}
+/** Count `decision` entries appended to the brain since HEAD (ADR-0027 nudge trigger). */
+export function uncommittedDecisionCount(brain = brainDir(), cwd = process.cwd()) {
+    return newBrainEntriesSinceHead(brain, cwd).filter((e) => e.type === 'decision').length;
+}
+const isHandoff = (e) => (e.tags ?? []).some((t) => t === 'handoff' || t === 'next');
+/** Impure shell: gather the real context for `decideStop` from git + the brain. */
+export function gatherStopContext(cwd = process.cwd(), brain = brainDir()) {
+    const fresh = newBrainEntriesSinceHead(brain, cwd);
+    return {
+        uncommittedWork: hasUncommittedWork(cwd, brain),
+        newDecisions: fresh.filter((e) => e.type === 'decision').length,
+        newEntries: fresh.length,
+        newHandoffs: fresh.filter(isHandoff).length,
+    };
+}

package/dist/storage.js

@@ -0,0 +1,145 @@
+// vfkb storage POLICY (v2: ADR-0044 layered over the backend seam). This module is
+// backend-agnostic: LWW materialization, ADR-0042 read-boundary normalization, and
+// ADR-0014 content-hash freshness — all computed over whatever transport
+// `storageBackend()` provides (exactly one ships in v2: JSONL-on-disk, ADR-0019).
+// The exported API is unchanged from the pre-seam kernel — the DoD's refactor-safety
+// contract (the full suite passes untouched) hangs on that.
+import { basename, dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { storageBackend } from './backend.js';
+import { normalizeEntry } from './validate.js';
+export function isTombstone(r) {
+    return r.deleted === true;
+}
+// The resolved data location. For the JSONL backend this is the brain DIRECTORY the
+// committed file lives in — the path git-layer consumers (git.ts, gating.ts,
+// stop-reminder.ts, counters, the lock) anchor to. Kept here (not behind the seam):
+// those consumers exist because of ADR-0019's committed-file property, and a backend
+// without that property simply doesn't wire them.
+export function brainDir() {
+    // VFKB_DATA_DIR is canonical; VFKB_DIR is a kept-working deprecated alias (ADR-0032).
+    return process.env.VFKB_DATA_DIR || process.env.VFKB_DIR || join(homedir(), '.vfkb');
+}
+// Default project name when VFKB_PROJECT is unset. Generic wiring (the Claude Code
+// plugin, ADR-0045) can point VFKB_DATA_DIR at a brain but cannot know the project's
+// name, so derive it from where the brain lives: an explicit brain dir names its
+// project (its parent when the dir itself is dot-named, e.g. <repo>/.vfkb → repo);
+// otherwise the hook-injected $CLAUDE_PROJECT_DIR, then the cwd. The old hard-coded
+// 'spike' remains only as the last-resort literal (empty basename at fs root, or a
+// name that is nothing but stripped characters).
+export function defaultProject() {
+    const raw = (() => {
+        if (process.env.VFKB_PROJECT)
+            return process.env.VFKB_PROJECT;
+        const explicit = process.env.VFKB_DATA_DIR || process.env.VFKB_DIR;
+        if (explicit) {
+            const abs = resolve(explicit);
+            const name = basename(abs);
+            return name.startsWith('.') ? basename(dirname(abs)) : name;
+        }
+        const root = process.env.CLAUDE_PROJECT_DIR;
+        if (root)
+            return basename(resolve(root));
+        return basename(process.cwd());
+    })();
+    // The name lands verbatim inside the injected pseudo-XML headers
+    // (<vfkb-resume project="...">) — strip characters that would deform them.
+    return raw.replace(/["<>&]/g, '') || 'spike';
+}
+// --- append-only writes. Every write regenerates the freshness meta as a
+//     GUARANTEED side-effect (mykb L11; ADR-0014) — policy, so it lives here,
+//     above the backend's raw append. ---
+export function appendRecord(rec) {
+    storageBackend().append(rec);
+    writeMeta();
+}
+// ADR-0040: the exclusive section for read-decide-append engine ops, provided by
+// the backend (a lockfile for JSONL; a transaction for a future hosted backend).
+export function withExclusive(fn) {
+    return storageBackend().withExclusive(fn);
+}
+// --- Project context doc spine (D-ii / ADR-0025) — authored content, stored by the
+//     backend, never a JSONL entry (stays freely editable; the never-rewrite Brake
+//     governs entries only). ---
+export function contextSpinePath() {
+    return storageBackend().spinePath();
+}
+export function readContextSpine() {
+    return storageBackend().readSpine();
+}
+export function writeContextSpine(content) {
+    storageBackend().writeSpine(content);
+}
+let malformed = [];
+export function lastMalformed() {
+    return [...malformed];
+}
+export function readRecords() {
+    const { records, malformed: bad } = storageBackend().readAllRaw();
+    malformed = [...bad];
+    return records;
+}
+// Collapse the append log to the live entry set.
+// Per id, keep the record with the greatest `updated` (ties → later in file);
+// if that newest record is a tombstone, the id is gone. Order-independent in
+// `updated` → merge=union safe.
+export function materialize(records = readRecords()) {
+    const newest = new Map();
+    for (const r of records) {
+        if (!r || typeof r !== 'object' || typeof r.id !== 'string' || !r.id) {
+            // Unsalvageable: no usable id → excluded from the live set, visibly counted
+            // (ADR-0042 §2 — a distinct surfaced state, never a crash, never silent).
+            malformed.push({ issue: 'no usable id', raw: JSON.stringify(r).slice(0, 200) });
+            continue;
+        }
+        const cur = newest.get(r.id);
+        if (!cur || r.updated >= cur.updated)
+            newest.set(r.id, r);
+    }
+    const out = [];
+    for (const r of newest.values()) {
+        if (isTombstone(r))
+            continue;
+        // Whole-envelope normalization at the read boundary (ADR-0042 §2): every consumer
+        // sees a well-formed entry regardless of origin (vfkb write path, external
+        // projection, hand edit). Safe defaults for missing/invalid fields; unknown
+        // future fields pass through untouched (forward compatibility).
+        const n = normalizeEntry(r);
+        if (n.ok)
+            out.push(n.entry);
+        else
+            malformed.push({ issue: n.issue, raw: JSON.stringify(r).slice(0, 200) });
+    }
+    return out;
+}
+// --- content-derived freshness token (ADR-0014: NEVER mtime). Stable across
+//     file order and git operations; changes iff the live set changes. ---
+export function contentHash(entries = materialize()) {
+    const basis = entries
+        .map((e) => `${e.id}@${e.updated}`)
+        .sort()
+        .join('\n');
+    return createHash('sha256').update(basis).digest('hex').slice(0, 16);
+}
+export function readMeta() {
+    const raw = storageBackend().readMetaRaw();
+    if (raw === null)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function writeMeta() {
+    const entries = materialize();
+    const meta = {
+        content_hash: contentHash(entries),
+        entry_count: entries.length,
+        last_write: new Date().toISOString(),
+    };
+    storageBackend().writeMetaRaw(JSON.stringify(meta));
+    return meta;
+}

package/dist/types.js

@@ -0,0 +1,6 @@
+// vfkb entry envelope — Phase 0 spike shape.
+// Implements ADR-0011 (validity window + structured provenance.origin; trust derived).
+// Runtime companion for validating user-supplied type strings (issue #95).
+export const ENTRY_TYPES = ['fact', 'decision', 'gotcha', 'pattern', 'link'];
+// Runtime companion for validating user-supplied status strings (issue #95).
+export const DECISION_STATUSES = ['proposed', 'accepted', 'deprecated', 'superseded'];

package/dist/validate.js

@@ -0,0 +1,83 @@
+// ADR-0042 §2 (v2): whole-envelope validation at the READ boundary — the one place
+// that sees every entry regardless of origin (vfkb's own writes, vfwb's lossy external
+// projection, hand-edited legacy lines, a future RFC-019 backend). Malformed/missing
+// fields get safe DOCUMENTED defaults; a record that cannot be salvaged at all (no
+// usable id) is excluded from the live set and surfaced as a counted, inspectable
+// state (storage.lastMalformed / the context map's malformed count) — visible, never
+// a silent drop, and never a crash in a caller.
+//
+// Philosophy: permissive-with-defaults, loose (unknown future fields PASS THROUGH —
+// a v2 brain read by this code, or a foreign brain with extra fields, must not be
+// stripped). zod is used per the accepted ADR; it is currently satisfied transitively
+// via @modelcontextprotocol/sdk (declaring it directly is a noted follow-up).
+import { z } from 'zod';
+const ROLE = z.enum(['architect', 'pm', 'executor', 'judge', 'human', 'init', 'import']);
+const PROV_STATUS = z.enum(['verified', 'unverified', 'stale', 'expired']);
+// Defaults (documented): unknown role → executor (agent-trust, the safe floor);
+// unknown provenance → unverified (never accidentally verified); unknown zone →
+// incoming (never accidentally injected as established); missing tags → [].
+//
+// TWO KNOWN CONSEQUENCES (review gate, 2026-07-06 — deliberate, documented):
+// 1. PERSISTENCE-ON-UPDATE: update paths (updateEntry/setProvenanceStatus/transition)
+//    spread the NORMALIZED entry and re-append, so read-time defaults become stored
+//    values on the next edit of a legacy/foreign entry. The original line stays
+//    untouched (append-only intact) and normalization is idempotent, but an
+//    invalid-but-meaningful original value leaves the live record permanently.
+// 2. UNKNOWN TYPE COERCES TO 'fact' (the one place passthrough does NOT hold): a
+//    future v3 entry type read by this code renders as a fact, and via (1) an edit
+//    would persist that coercion. Revisit before any v3 schema introduces new types.
+const entrySchema = z
+    .looseObject({
+    id: z.string().min(1),
+    type: z.enum(['fact', 'decision', 'gotcha', 'pattern', 'link']).catch('fact'),
+    text: z.string().catch(''),
+    tags: z.array(z.string()).catch([]),
+    zone: z.enum(['incoming', 'established', 'archive']).catch('incoming'),
+    author: z.looseObject({ role: ROLE.catch('executor'), id: z.string().optional() }).catch({ role: 'executor' }),
+    refs: z
+        .looseObject({
+        supersedes: z.string().optional(),
+        contradicts: z.array(z.string()).optional().catch(undefined),
+    })
+        .optional()
+        .catch(undefined),
+    provenance: z
+        .looseObject({
+        status: PROV_STATUS.catch('unverified'),
+        date: z.string().optional(),
+        source: z.string().optional(),
+        detail: z.string().optional(),
+        origin: z.unknown().optional(),
+    })
+        .catch({ status: 'unverified' }),
+    validity: z
+        .looseObject({
+        valid_from: z.string().optional(),
+        valid_until: z.string().optional(),
+        recorded_invalid_at: z.string().optional(),
+    })
+        .catch({}),
+    status: z.enum(['proposed', 'accepted', 'deprecated', 'superseded']).optional().catch(undefined),
+    why: z.string().optional().catch(undefined),
+    constitutional: z.boolean().optional().catch(undefined),
+    adr_no: z.number().optional().catch(undefined),
+    session_id: z.string().optional().catch(undefined),
+    created: z.string().catch(''),
+    updated: z.string().catch(''),
+});
+export function normalizeEntry(raw) {
+    const parsed = entrySchema.safeParse(raw);
+    if (!parsed.success) {
+        // Only an unsalvageable record lands here (everything else is caught-with-default):
+        // not an object, or no usable string id.
+        return { ok: false, issue: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ') };
+    }
+    const e = parsed.data;
+    // valid_from is required by the TS envelope type (no runtime consumer today) —
+    // default it from the entry's own created stamp, else epoch (visibly ancient
+    // beats invisibly wrong).
+    if (!e.validity.valid_from) {
+        e.validity = { ...e.validity, valid_from: e.created || '1970-01-01T00:00:00.000Z' };
+    }
+    return { ok: true, entry: e };
+}

package/dist/version.js

@@ -0,0 +1,32 @@
+// FR-4 (ADR-0030) — engine identity, for the brain↔engine version stamp + doctor.
+//
+// SCHEMA_VERSION is the load-bearing compat signal: the .vfkb/entries.jsonl
+// envelope version (ADR-0011). Bump it ONLY on a breaking envelope change; a brain
+// stamped with a newer schema than the running engine is incompatible.
+//
+// ENGINE_VERSION / ENGINE_COMMIT identify the engine build. They are injected at
+// bundle build time via esbuild `define` (scripts/build-bundles.mjs, kept as the
+// primary); the tsc/dist path has no define, so ENGINE_VERSION falls back to the
+// package's OWN package.json (resolved relative to this module — dist/version.js
+// sits one level below package.json, same in the repo and inside an `npm i -g`
+// install). The old literal '0.0.0-dev' fallback meant an npm-installed vfkb-mcp
+// reported serverInfo.version 0.0.0-dev (observed — PR #122 review F4). `typeof
+// <undeclared>` is safe (never throws), so the define check works without the
+// symbols existing at runtime; the fs read is guarded so a missing/unreadable
+// manifest still yields the honest dev sentinel instead of a crash.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+export const SCHEMA_VERSION = 1;
+function ownPackageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+        return pkg.version || '0.0.0-dev';
+    }
+    catch {
+        return '0.0.0-dev';
+    }
+}
+export const ENGINE_VERSION = typeof __VFKB_VERSION__ !== 'undefined' ? __VFKB_VERSION__ : ownPackageVersion();
+export const ENGINE_COMMIT = typeof __VFKB_COMMIT__ !== 'undefined' ? __VFKB_COMMIT__ : 'dev';

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@viloforge/vfkb",
+  "version": "0.2.1",
+  "description": "ViloForge KnowledgeBase (vfkb) — per-project knowledge substrate for the ViloForge software factory. Greenfield TypeScript.",
+  "type": "module",
+  "main": "dist/engine.js",
+  "exports": {
+    ".": "./dist/engine.js",
+    "./pi-extension": "./dist/pi-extension.js",
+    "./pi-mcp-bridge": "./dist/pi-mcp-bridge.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "vfkb": "dist/cli.js",
+    "vfkb-mcp": "dist/mcp-server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vilosource/vfkb.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:bundles": "node scripts/build-bundles.mjs",
+    "pretest": "tsc",
+    "test": "vitest run",
+    "clean": "rm -rf dist",
+    "prepack": "npm run build && npm run build:bundles"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.9",
+    "@types/node": "^25.9.1",
+    "esbuild": "^0.21.5",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}