@viloforge/vfkb 0.4.0 → 0.5.0

package/dist/engine.js

@@ -4,7 +4,10 @@
 // the tiered Heuristic reranker (ADR-0012), the budgeted render (ADR-0015), capture.
 // Pure Node stdlib, ZERO runtime deps.
 import { randomBytes } from 'node:crypto';
-import { appendRecord, materialize, readRecords, lastMalformed, withExclusive, contextSpinePath, readContextSpine, writeContextSpine, defaultProject, } from './storage.js';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { appendRecord, materialize, readRecords, lastMalformed, withExclusive, contextSpinePath, readContextSpine, writeContextSpine, defaultProject, brainDir, } from './storage.js';
 import { selectIndex } from './index-store.js';
 import { testHoldForRace } from './lock.js';
 import { assertNoSecrets } from './secrets.js';
@@ -396,6 +399,46 @@ export function latestCrossRepo(all = readAll(), today = nowIso().slice(0, 10),
     }
     return latest;
 }
+/**
+ * ADR-0065 §1 — the CLI write path an agent should reach for when the MCP face
+ * errors or disappears.
+ *
+ * Resolved from THIS MODULE's own location, never `process.argv[1]`. argv[1] is
+ * the *entry* script, which is only the CLI on one of the three faces:
+ *   - plugin bundles:  dist/bundles/{vfkb.mjs, vfkb-mcp.mjs}  — siblings
+ *   - npm install:     dist/{cli.js, mcp-server.js}           — siblings
+ *   - pi / embedded:   argv[1] is the HOST's script entirely
+ * Using argv[1] emitted `node ".../dist/mcp-server.js" add …` on the npm MCP
+ * face — a command that starts a stdio server, blocks on stdin and writes
+ * nothing (observed; review of PR #217, blocking 1). The engine module always
+ * ships beside its own CLI face, so its directory is the stable anchor.
+ *
+ * Both paths are QUOTED — plugin cache paths can contain spaces, and a command
+ * truncating at the first space is the quiet-failure class this ADR exists to
+ * remove. The brain dir is ABSOLUTE-ised for the same reason: VFKB_DATA_DIR is
+ * commonly configured relative (".vfkb"), and a command pasted from another cwd
+ * would otherwise create a second brain in the wrong directory.
+ */
+const CLI_FACES = ['vfkb.mjs', 'cli.js', 'cli.mjs'];
+/** The CLI entry point shipped beside the engine, or undefined if none is found. */
+export function resolveCliFace(engineDir) {
+    return CLI_FACES.map((f) => join(engineDir, f)).find((p) => existsSync(p));
+}
+export function renderCaptureFallback(engineDir = dirname(fileURLToPath(import.meta.url))) {
+    // engineDir is injectable for tests ONLY. Under vitest the engine runs from
+    // src/, where no BUILT cli face exists, so the default correctly yields the
+    // unresolved marker — the real-path guarantee is therefore asserted against
+    // the built artifact in test/mcp-write-loudness.test.ts, not here.
+    const cli = resolveCliFace(engineDir);
+    // Never emit a path we could not verify: a wrong command pasted mid-failure is
+    // worse than an honest gap (ADR-0051 §3 — say what is unknown, don't imply).
+    const target = cli
+        ? `node "${cli}"`
+        : `node <vfkb CLI not found beside the engine at ${engineDir} — locate vfkb.mjs or cli.js>`;
+    return (`capture fallback: if the kb_* tools error or disappear, the CLI still writes ` +
+        `(same engine, separate process; journaled per ADR-0064) —\n` +
+        `  VFKB_DATA_DIR="${resolvePath(brainDir())}" ${target} add <type> "…" [--tags a,b] [--why "…"]`);
+}
 export function renderContextBundle(project = defaultProject(), budget = SESSION_BUDGET_CHARS) {
     const all = readAll();
     const today = nowIso().slice(0, 10);
@@ -444,6 +487,14 @@ export function renderContextBundle(project = defaultProject(), budget = SESSION
     }
     // Context Map (ADR-0006): the navigational index, always injected, never dropped.
     body += renderContextMap() + '\n\n';
+    // Capture fallback (ADR-0065 §1 ← RFC-035): the hooks and the MCP server are
+    // separate processes over the same engine bundle, so a dead MCP face does not
+    // imply a dead CLI — and with ADR-0064's journal the CLI write is exactly as
+    // durable. That fallback already exists but is undocumented at the moment of
+    // failure; an agent mid-loss has no reason to know it. Joins the never-dropped
+    // preamble, costing at most one lowest-ranked entry — the same trade the
+    // ADR-0049/ADR-0063 pins already made, stated as a decision, not a side effect.
+    body += renderCaptureFallback() + '\n\n';
     // Ranked lines are collected (not appended) so the omission note can evict
     // trailing lines when needed — under the old append-as-you-go shape, a body
     // that filled the budget exactly silently dropped the note itself, hiding

package/dist/hook-stdin-failopen.test.js

@@ -0,0 +1,217 @@
+// Issue #214 — a hook whose stdin never closes must FAIL OPEN, not stall.
+//
+// MEASURED ground truth (2026-07-18, this worktree, before the fix):
+//   - `node dist/cli.js hook pre-tool-use` with a payload written but stdin
+//     never closed WROTE `{}` (readStdin's 2s watchdog fired and produced the
+//     right answer) and then NEVER EXITED — killed at 10s. The stdin 'data'
+//     listener keeps the event loop alive, so resolving the promise is not
+//     enough: the process still holds the harness.
+//   - `node scripts/hook-durable-claim-check.mjs` under the same condition
+//     wrote NOTHING and never exited (it only ever acts on 'end').
+//
+// Why that matters: Claude Code's default `command`-hook timeout is 600s
+// (code.claude.com/docs/en/hooks). What the harness does when that expires
+// (allow vs deny) is NOT documented — but a PreToolUse hook that pins a tool
+// call for up to ten minutes violates the repo protocol either way.
+//
+// ALTITUDE: this drives the REAL shipped artifacts as child processes over a
+// real pipe — the built `dist/cli.js` and the standalone hook script. It does
+// not call readStdin() directly, because the bug is not in the promise, it is
+// in whether the PROCESS terminates. A test of the helper would have stayed
+// green through the entire defect.
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const repoRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const cliPath = join(repoRoot, 'dist', 'cli.js');
+const durableHook = join(repoRoot, 'scripts', 'hook-durable-claim-check.mjs');
+// SANDBOX (ADR-0029 clause 1: "isolated from the live/dogfooded system").
+// `hook post-tool-use` CAPTURES its payload into the brain, and the brain dir
+// defaults to ~/.vfkb — the operator's REAL, git-tracked global brain. Without
+// this every run of this file, and every RED mutation run a future engineer
+// performs to re-verify the guard, appends junk `fact` entries to a committed
+// file. That is not hypothetical: it was OBSERVED during review of this very
+// PR (18 stray `/etc/hostname` entries, ~/.vfkb left dirty).
+//
+// This is self-enforcing, not a convention: the payload-survival test below
+// asserts the entry lands in THIS dir, so dropping VFKB_DATA_DIR turns the
+// sandbox brain empty and takes the suite RED.
+let brainDir;
+beforeAll(() => {
+    brainDir = mkdtempSync(join(tmpdir(), 'vfkb-stdin-failopen-'));
+});
+afterAll(() => {
+    if (brainDir)
+        rmSync(brainDir, { recursive: true, force: true });
+});
+/** Env for every spawned hook: the real harness vars, but a throwaway brain. */
+function sandboxEnv() {
+    return {
+        ...process.env,
+        CLAUDE_PROJECT_DIR: repoRoot,
+        VFKB_DATA_DIR: brainDir,
+    };
+}
+// readStdin's watchdog is 2000ms. Allow generous headroom for process spawn +
+// a loaded CI box, but stay far below anything a human would call a stall.
+const MUST_EXIT_WITHIN_MS = 8000;
+/**
+ * Spawn `cmd args`, WRITE the payload to stdin, and deliberately NEVER close
+ * stdin. This is the exact condition in issue #214: the writer stays attached.
+ * Resolves when the child exits, or reports exited:false after the deadline.
+ */
+function probeWithUnclosedStdin(cmd, args, payload, deadlineMs = MUST_EXIT_WITHIN_MS) {
+    return new Promise((resolveP) => {
+        const t0 = Date.now();
+        const child = spawn(cmd, args, {
+            cwd: repoRoot,
+            env: sandboxEnv(),
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        child.stdout.on('data', (d) => (stdout += d));
+        child.stderr.on('data', () => { });
+        child.stdin.on('error', () => { });
+        child.stdin.write(payload); // NOTE: no .end() — stdin stays open forever.
+        let settled = false;
+        const kill = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            resolveP({ exited: false, code: null, stdout, elapsedMs: Date.now() - t0 });
+        }, deadlineMs);
+        child.on('exit', (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(kill);
+            // Give stdout a tick to flush before reporting.
+            setTimeout(() => resolveP({ exited: true, code, stdout, elapsedMs: Date.now() - t0 }), 20);
+        });
+    });
+}
+const benignPayload = JSON.stringify({
+    session_id: 'stdin-failopen-test',
+    cwd: '/nonexistent-vfkb-probe',
+    tool_name: 'Read',
+    tool_input: { file_path: '/etc/hostname' },
+});
+describe('issue #214 — hooks fail open when stdin never closes', () => {
+    beforeAll(() => {
+        // The property under test is about the SHIPPED binary. If it is missing the
+        // test must fail loudly, never silently skip (a skipped guard is a blind one).
+        expect(existsSync(cliPath), `dist/cli.js missing — run \`npm run build\` (pretest does this)`).toBe(true);
+        expect(existsSync(durableHook)).toBe(true);
+    });
+    // The PreToolUse gate is the highest-stakes case: it sits between the agent
+    // and every Write/Edit, so a wedge here wedges the whole session.
+    it('dist/cli.js hook pre-tool-use TERMINATES and allows the call', async () => {
+        const r = await probeWithUnclosedStdin('node', [cliPath, 'hook', 'pre-tool-use'], benignPayload);
+        expect(r.exited, `hook pre-tool-use did not exit within ${MUST_EXIT_WITHIN_MS}ms with stdin held open ` +
+            `(stdout so far: ${JSON.stringify(r.stdout)}). A PreToolUse hook that never exits ` +
+            `pins the tool call until the harness's 600s cancel.`).toBe(true);
+        expect(r.code).toBe(0);
+        // Fail OPEN means EMITTING the allow shape, not merely declining to deny.
+        // Asserting only `not.toContain('deny')` is satisfied by empty stdout — the
+        // quiet-success trap (ADR-0051 clause 3). Assert the payload positively.
+        expect(r.stdout.trim()).toBe('{}');
+    }, 30000);
+    // Every other hook subcommand shares the same readStdin() convention, so the
+    // guard must hold uniformly — this is a convention fix, not a one-file patch.
+    for (const sub of ['post-tool-use', 'stop', 'session-end', 'session-start']) {
+        it(`dist/cli.js hook ${sub} TERMINATES with stdin held open`, async () => {
+            const r = await probeWithUnclosedStdin('node', [cliPath, 'hook', sub], benignPayload);
+            expect(r.exited, `hook ${sub} did not exit within ${MUST_EXIT_WITHIN_MS}ms with stdin held open ` +
+                `(stdout so far: ${JSON.stringify(r.stdout)})`).toBe(true);
+            expect(r.code).toBe(0);
+            // Terminating silently is NOT failing open — the harness gets no decision.
+            // Every hook subcommand emits a JSON object on the allow path.
+            expect(r.stdout.trim().startsWith('{'), `hook ${sub} exited but emitted no JSON decision (stdout: ${JSON.stringify(r.stdout)})`).toBe(true);
+        }, 30000);
+    }
+    // The cli.ts analogue of the durable-claim payload test below. Terminating is
+    // only half the contract: readStdin must resolve with the bytes that ARRIVED,
+    // not an empty string. A watchdog that fires and DISCARDS the buffer exits 0,
+    // emits `{}`, and passes every termination assertion above while silently
+    // making the hook inert — the quiet-success trap (ADR-0051 clause 3), and the
+    // exact asymmetry review finding R2 flagged (the .mjs side was guarded here,
+    // cli.ts was not). Mutation: `resolve(data)` -> `resolve('')` in finish().
+    //
+    // Observed at the shipped altitude: post-tool-use CAPTURES the payload into
+    // the brain, so the sandbox brain is the proof the bytes survived. This also
+    // pins the sandbox itself — with VFKB_DATA_DIR dropped, this file is empty.
+    it('post-tool-use still CAPTURES a payload whose stdin never closed (watchdog must not discard)', async () => {
+        const marker = `stdin-failopen-marker-${Date.now()}`;
+        const payload = JSON.stringify({
+            session_id: 'stdin-failopen-capture',
+            tool_name: 'Read',
+            tool_input: { file_path: `/probe/${marker}` },
+        });
+        const r = await probeWithUnclosedStdin('node', [cliPath, 'hook', 'post-tool-use'], payload);
+        expect(r.exited, 'post-tool-use did not exit with stdin held open').toBe(true);
+        const entriesPath = join(brainDir, 'entries.jsonl');
+        expect(existsSync(entriesPath), `no brain written at ${entriesPath} — the watchdog resolved but the payload was dropped, ` +
+            `so captureToolCall saw nothing. The hook is inert.`).toBe(true);
+        const brain = readFileSync(entriesPath, 'utf8');
+        expect(brain, `the captured entry does not carry the payload's marker — readStdin settled on the ` +
+            `deadline but discarded the buffered bytes.`).toContain(marker);
+    }, 30000);
+    // The standalone Brake reads stdin with the same await-until-'end' pattern and
+    // ships to this repo's own .claude/settings.json — issue #214's stated scope.
+    it('scripts/hook-durable-claim-check.mjs TERMINATES with stdin held open', async () => {
+        const r = await probeWithUnclosedStdin('node', [durableHook], benignPayload);
+        expect(r.exited, `durable-claim hook did not exit within ${MUST_EXIT_WITHIN_MS}ms with stdin held open`).toBe(true);
+        expect(r.code).toBe(0);
+    }, 30000);
+    // ...and it must still be able to SPEAK on a durable-artifact payload it only
+    // ever saw partially. A watchdog that fires but drops the payload would turn
+    // the Brake inert under load — the exact class of defect this repo keeps hitting.
+    it('durable-claim hook still emits its reminder from a payload whose stdin never closed', async () => {
+        const durablePayload = JSON.stringify({
+            tool_name: 'Bash',
+            tool_input: { command: 'gh issue create --title "x" --body "y"' },
+        });
+        const r = await probeWithUnclosedStdin('node', [durableHook], durablePayload);
+        expect(r.exited, 'durable-claim hook did not exit with stdin held open').toBe(true);
+        expect(r.stdout).toContain('DURABLE ARTIFACT');
+        expect(r.stdout).toContain('hookSpecificOutput');
+    }, 30000);
+    // CONTRAST ARM: the normal path (stdin properly closed) must be FAST and
+    // unaffected. If the watchdog became the only exit route, every hook would
+    // suddenly cost 2s — a regression the termination assertions alone miss.
+    it('the normal closed-stdin path stays fast (watchdog is not the exit route)', async () => {
+        const runClosed = async () => {
+            const t0 = Date.now();
+            const out = await new Promise((resolveP) => {
+                const child = spawn('node', [cliPath, 'hook', 'pre-tool-use'], {
+                    cwd: repoRoot,
+                    env: sandboxEnv(),
+                });
+                let s = '';
+                child.stdout.on('data', (d) => (s += d));
+                child.on('exit', () => resolveP(s));
+                child.stdin.end(benignPayload); // properly closed
+            });
+            return { out, elapsed: Date.now() - t0 };
+        };
+        let r = await runClosed();
+        // The bound MUST stay below STDIN_WATCHDOG_MS (2000ms) or it asserts nothing
+        // — the whole point is distinguishing "exited via 'end'" from "exited via the
+        // watchdog". So instead of loosening it past the thing it measures, absorb a
+        // single transient runner stall by retrying once (review finding R3). A build
+        // where the watchdog IS the only exit route takes ~2s on BOTH attempts, so
+        // this keeps the full mutation-detecting power.
+        if (r.elapsed >= 1900)
+            r = await runClosed();
+        // Positive assertion: it must actually EMIT the allow decision on the normal
+        // path. (Dropping the 'end' handler makes the process exit 0 fast and silent
+        // — mutation M4 — which an `not.toContain('deny')` check passes happily.)
+        expect(r.out.trim()).toBe('{}');
+        expect(r.elapsed, `closed-stdin hook took ${r.elapsed}ms on two consecutive attempts — the 2s watchdog ` +
+            `should NOT be the exit route`).toBeLessThan(1900);
+    }, 30000);
+});

package/dist/init.js

@@ -96,8 +96,9 @@ This repo uses **vfkb** as its knowledge substrate (project \`${project}\`). Kno
 - **Record knowledge** with the \`mcp__vfkb__kb_add\` tool (or \`node .vfkb/bin/bootstrap.mjs cli add …\`):
   \`decision\`, \`fact\`, \`gotcha\`, \`pattern\`, \`link\` — put a decision's rationale in its text.
   **Capture load-bearing decisions immediately — don't defer.**
-- Only \`.vfkb/entries.jsonl\`, \`.vfkb/manifest.json\`, and \`.vfkb/bin/\` are committed;
-  \`.vfkb/index-meta.json\`, \`.sessions/\`, \`.signals/\` are derived/gitignored.
+- Committed: \`.vfkb/entries.jsonl\`, \`.vfkb/manifest.json\` (the ADR-0030 engine stamp —
+  **never gitignore \`manifest.json\`**), and \`.vfkb/bin/\`. Derived/gitignored, all five:
+  \`.vfkb/index-meta.json\`, \`.vfkb/.sessions/\`, \`.vfkb/.signals/\`, \`.vfkb/.journal/\`, \`.vfkb/.lock\`.
 
 Two env vars: **\`VFKB_DATA_DIR\`** = this repo's brain (\`.vfkb\`, set by the wiring) · **\`VFKB_BUNDLE_DIR\`**
 = the shared vfkb engine bundles — set it once per machine, e.g. \`export VFKB_BUNDLE_DIR=/path/to/vfkb/dist/bundles\`.
@@ -201,16 +202,56 @@ export function initProject(root, opts = {}) {
     // 4. .gitignore — the derived/operational stanza (append once).
     {
         const path = join(root, '.gitignore');
-        const lines = ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/', '.vfkb/.journal/'];
+        // Every derived/operational path. `.lock` is the ADR-0040 concurrency lock:
+        // transient, but a `git add .vfkb` timed against a concurrent write would
+        // commit it. Keep in step with vfkb's own .gitignore — a consumer whose
+        // ignore set is narrower than the engine's is a sweep waiting to happen
+        // (one ran across 10 repos on 2026-07-18 for exactly this).
+        const lines = [
+            '.vfkb/index-meta.json',
+            '.vfkb/.sessions/',
+            '.vfkb/.signals/',
+            '.vfkb/.journal/',
+            '.vfkb/.lock',
+        ];
+        // The header the stanza should carry. The OLD one claimed "only
+        // .vfkb/entries.jsonl is committed", which is FALSE — manifest.json is
+        // committed by design (ADR-0030, the brain↔engine stamp, distinct from the
+        // derived index-meta.json). That sentence caused a real defect: the natural
+        // response to an untracked manifest.json is to gitignore it, and one
+        // consumer ended up with no engine stamp at all.
+        const HEADER = [
+            '# vfkb — entries.jsonl + manifest.json (the ADR-0030 engine stamp) are committed;',
+            '# the vfkb paths below are derived/operational and stay out of git',
+        ];
+        // Any header this generator has ever emitted, so an upgrade HEALS the stanza
+        // in place. Appending a corrected block while leaving the old one alone left
+        // the false claim intact AND first in the file, contradicted by a second
+        // stanza below it — worse than not fixing it (review of PR #219, blocking 1).
+        const STALE_HEADER = /^#\s*vfkb\s*—\s*derived\/operational \(only \.vfkb\/entries\.jsonl is committed\)\s*$/;
         const existed = existsSync(path);
         const cur = existed ? readFileSync(path, 'utf8') : '';
-        const missing = lines.filter((l) => !cur.split(/\r?\n/).includes(l));
-        if (missing.length === 0) {
+        const curLines = cur.split(/\r?\n/);
+        const missing = lines.filter((l) => !curLines.includes(l));
+        const staleAt = curLines.findIndex((l) => STALE_HEADER.test(l));
+        if (missing.length === 0 && staleAt === -1) {
             changes.push({ path: '.gitignore', action: 'skipped' });
         }
+        else if (staleAt !== -1) {
+            // Heal: swap the stale header for the correct one and fold any missing
+            // paths into THAT stanza, so the file ends up with exactly one.
+            const out = [...curLines];
+            out.splice(staleAt, 1, ...HEADER);
+            let last = staleAt + HEADER.length - 1;
+            for (let i = last + 1; i < out.length && /^\.vfkb\//.test(out[i].trim()); i++)
+                last = i;
+            out.splice(last + 1, 0, ...missing);
+            writeFileSync(path, out.join('\n'));
+            changes.push({ path: '.gitignore', action: 'updated' });
+        }
         else {
             const prefix = cur && !cur.endsWith('\n') ? '\n' : '';
-            const block = `${prefix}${cur ? '\n' : ''}# vfkb — derived/operational (only .vfkb/entries.jsonl is committed)\n${missing.join('\n')}\n`;
+            const block = `${prefix}${cur ? '\n' : ''}${HEADER.join('\n')}\n${missing.join('\n')}\n`;
             writeFileSync(path, cur + block);
             changes.push({ path: '.gitignore', action: existed ? 'updated' : 'created' });
         }

package/dist/init.test.js

@@ -4,7 +4,7 @@
 // consumer-onboarding L4 scenario is the capability-level DoD (ADR-0029).
 import { describe, it, expect, beforeEach } from 'vitest';
 import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { spawnSync, execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { initProject } from './init.js';
@@ -58,6 +58,75 @@ describe('vfkb init (FR-1)', () => {
         expect(read('.gitignore')).toContain('.vfkb/.sessions/');
         expect(read('AGENTS.md')).toContain('How we track work HERE');
     });
+    // The generator, not the symptom. A 10-repo sweep (2026-07-18) added
+    // `.vfkb/.lock` and corrected a false comment across every consumer — and
+    // `vfkb init` would have re-introduced both on the next new repo. Fixing ten
+    // copies without fixing what emits them is a sweep you run again.
+    describe('the emitted .gitignore stanza is correct at the source', () => {
+        it('ignores every derived/operational path, including the lock', () => {
+            initProject(root, { project: 'demo' });
+            const gi = read('.gitignore');
+            for (const p of ['.vfkb/index-meta.json', '.vfkb/.sessions/', '.vfkb/.signals/', '.vfkb/.journal/', '.vfkb/.lock']) {
+                expect(gi, `missing ignore rule ${p}`).toContain(p);
+            }
+        });
+        it('does NOT ignore the two committed files', () => {
+            initProject(root, { project: 'demo' });
+            const gi = read('.gitignore')
+                .split(/\r?\n/)
+                .filter((l) => l.trim() && !l.trim().startsWith('#'));
+            // entries.jsonl is the brain; manifest.json is the ADR-0030 engine stamp.
+            expect(gi).not.toContain('.vfkb/entries.jsonl');
+            expect(gi).not.toContain('.vfkb/manifest.json');
+            expect(gi).not.toContain('.vfkb/');
+        });
+        // The assertion that can fail for the RIGHT reason. Substring checks match a
+        // COMMENTED-OUT path just as happily: prefixing every emitted path with '# '
+        // produced a stanza that ignores NOTHING and still passed them (review of
+        // PR #219, major 2). git is the only authority on what a .gitignore does.
+        it('git actually ignores the derived paths and NOT the committed ones', () => {
+            initProject(root, { project: 'demo' });
+            execFileSync('git', ['init', '-q'], { cwd: root });
+            const ignored = (p) => {
+                try {
+                    execFileSync('git', ['check-ignore', '-q', p], { cwd: root, stdio: 'ignore' });
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            };
+            for (const p of ['.vfkb/.lock', '.vfkb/.journal/wal.jsonl', '.vfkb/index-meta.json', '.vfkb/.sessions/x', '.vfkb/.signals/y']) {
+                expect(ignored(p), `${p} should be ignored`).toBe(true);
+            }
+            // The brain and the ADR-0030 engine stamp MUST stay committable.
+            expect(ignored('.vfkb/entries.jsonl'), 'entries.jsonl must not be ignored').toBe(false);
+            expect(ignored('.vfkb/manifest.json'), 'manifest.json must not be ignored').toBe(false);
+        });
+        it('HEALS an old stanza in place instead of appending a contradictory one', () => {
+            // Every existing consumer takes this path; greenfield is the rare case.
+            writeFileSync(join(root, '.gitignore'), '# vfkb — derived/operational (only .vfkb/entries.jsonl is committed)\n' +
+                '.vfkb/index-meta.json\n.vfkb/.sessions/\n.vfkb/.signals/\n.vfkb/.journal/\n');
+            initProject(root, { project: 'demo' });
+            const gi = read('.gitignore');
+            expect(gi, 'the false claim must not survive').not.toMatch(/only \.vfkb\/entries\.jsonl is committed/i);
+            // Exactly ONE stanza — not the old one plus a corrected one below it.
+            expect(gi.split('derived/operational').length - 1).toBe(1);
+            expect(gi).toContain('.vfkb/.lock');
+            // and the healed stanza still works
+            execFileSync('git', ['init', '-q'], { cwd: root });
+            expect(() => execFileSync('git', ['check-ignore', '-q', '.vfkb/.lock'], { cwd: root, stdio: 'ignore' })).not.toThrow();
+        });
+        it('does not claim entries.jsonl is the ONLY committed file', () => {
+            // That comment was false and load-bearing: the natural response to an
+            // untracked manifest.json is to gitignore it, which is exactly how one
+            // consumer ended up with no engine stamp at all.
+            initProject(root, { project: 'demo' });
+            const gi = read('.gitignore');
+            expect(gi).not.toMatch(/only .vfkb\/entries\.jsonl is committed/i);
+            expect(gi).toMatch(/manifest\.json/);
+        });
+    });
     it('defaults the project name to the directory basename', () => {
         initProject(root, {});
         const mcp = JSON.parse(read('.mcp.json'));

package/dist/manifest.js

@@ -10,8 +10,18 @@ import { SCHEMA_VERSION, ENGINE_VERSION, ENGINE_COMMIT } from './version.js';
 export function manifestPath(brainDir) {
     return join(brainDir, 'manifest.json');
 }
-export function currentManifest() {
-    return { schema_version: SCHEMA_VERSION, engine_version: ENGINE_VERSION, engine_commit: ENGINE_COMMIT };
+// #212 — `dev` is version.ts's honest sentinel for "this build has no esbuild
+// define, so it does not know its own commit" (the tsc/dist path, i.e. the
+// documented `node dist/cli.js` fallback). A missing commit says the same thing.
+export function isUnknownCommit(commit) {
+    return !commit || commit === 'dev';
+}
+export function currentManifest(opts = {}) {
+    return {
+        schema_version: SCHEMA_VERSION,
+        engine_version: opts.engineVersion ?? ENGINE_VERSION,
+        engine_commit: opts.engineCommit ?? ENGINE_COMMIT,
+    };
 }
 export function readManifest(brainDir) {
     const p = manifestPath(brainDir);
@@ -24,12 +34,38 @@ export function readManifest(brainDir) {
         return undefined;
     }
 }
+// #212 — would writing the stamp materially IMPROVE this brain's provenance?
+//
+// True when there is no stamp at all, or when the stored identity is unknown and
+// the running engine knows its own. A stored sha that merely DIFFERS is not a
+// re-stamp trigger: that is drift, and reporting drift is doctor's job — silently
+// overwriting the evidence would destroy the very signal doctor reads.
+export function manifestNeedsStamp(brainDir, engineCommit = ENGINE_COMMIT) {
+    const cur = readManifest(brainDir);
+    if (!cur)
+        return true;
+    return isUnknownCommit(cur.engine_commit) && !isUnknownCommit(engineCommit);
+}
 // Write the stamp if absent or stale. Returns 'created' | 'updated' | 'skipped'.
-export function writeManifest(brainDir) {
+//
+// #212 (stamping half) — engine identity is a PROVENANCE record, so it only ever
+// ratchets UNKNOWN -> KNOWN. A build that does not know its own commit must not
+// overwrite a brain that does: `vfkb init` calls this unconditionally, so a
+// re-run from the tsc/dist path is a live downgrade path. A dev build may still
+// CREATE a stamp (broadcast's heal depends on it, and a manifest's load-bearing
+// field is schema_version); recording `dev` there is honest — it is a brain whose
+// provenance genuinely is unknown, and doctor says exactly that.
+export function writeManifest(brainDir, opts = {}) {
     const p = manifestPath(brainDir);
     const existed = existsSync(p);
     const cur = readManifest(brainDir);
-    const next = currentManifest();
+    const next = currentManifest(opts);
+    if (cur && isUnknownCommit(next.engine_commit) && !isUnknownCommit(cur.engine_commit)) {
+        // Preserve the pair, not just the sha: a real commit carrying some other
+        // build's version number would be a fresh falsehood, not a preserved truth.
+        next.engine_commit = cur.engine_commit;
+        next.engine_version = cur.engine_version;
+    }
     if (cur && JSON.stringify(cur) === JSON.stringify(next))
         return 'skipped';
     mkdirSync(dirname(p), { recursive: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viloforge/vfkb",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "ViloForge KnowledgeBase (vfkb) — per-project knowledge substrate for the ViloForge software factory. Greenfield TypeScript.",
   "type": "module",
   "main": "dist/engine.js",