@viloforge/vfkb 0.4.0 → 0.5.0

package/dist/cli.js

@@ -43,16 +43,44 @@ function packageVersion() {
         return ENGINE_VERSION;
     }
 }
+// The hook stdin-read convention (issue #214). A hook must NEVER wedge a tool
+// call — it fails open or it does not ship. Two things are required for that,
+// and the original guard only did the first:
+//
+//   1. RESOLVE on a deadline, so a writer that never closes stdin still yields
+//      whatever arrived (the pre-existing 2s watchdog did this correctly).
+//   2. RELEASE stdin once settled, so the PROCESS can actually exit. A live
+//      'data' listener refs the pipe and keeps the event loop alive — MEASURED
+//      2026-07-18: `dist/cli.js hook pre-tool-use` wrote its allow decision
+//      `{}` at 2s and then hung until SIGKILL at 10s. The right answer,
+//      delivered by a process the harness is still waiting on, is still a stall.
+//
+// Claude Code cancels a `command` hook only at its default 600s timeout
+// (code.claude.com/docs/en/hooks), and what it does on expiry — allow or deny —
+// is NOT documented. So the wedge is up to ten minutes and its outcome unknown;
+// neither is acceptable for a PreToolUse gate.
+const STDIN_WATCHDOG_MS = 2000;
 function readStdin() {
     return new Promise((resolve) => {
         let data = '';
         if (process.stdin.isTTY)
             return resolve('');
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            // Stop holding the event loop open: without this the hook produces the
+            // correct output and still never exits (clause 2 above).
+            process.stdin.pause();
+            process.stdin.unref?.();
+            resolve(data);
+        };
         process.stdin.setEncoding('utf8');
         process.stdin.on('data', (c) => (data += c));
-        process.stdin.on('end', () => resolve(data));
-        // Guard: if nothing arrives, don't hang forever.
-        setTimeout(() => resolve(data), 2000).unref?.();
+        process.stdin.on('end', finish);
+        process.stdin.on('error', finish); // a broken pipe must fail open too
+        setTimeout(finish, STDIN_WATCHDOG_MS).unref?.();
     });
 }
 // Positional flag lookup for the HOOK subcommands only — hooks stay fail-open
@@ -158,7 +186,18 @@ async function dispatch() {
             let failed = 0;
             for (const r of results) {
                 if (r.ok) {
-                    process.stdout.write(`written\t${r.target}\t${r.id}\t${r.posture}${r.healed ? '\t(manifest healed — brain was wired but manifest-less, vfkb#193)' : ''}\n`);
+                    // #212 — `healed` (manifest was ABSENT, #193) and `upgraded` (manifest
+                    // was PRESENT but of unknown provenance, "dev") are different repairs
+                    // and must read differently: reporting an upgrade as a heal tells the
+                    // operator the manifest was missing when it never was, misdirecting
+                    // diagnosis to #193. An unrendered `upgraded` is the same defect in
+                    // silent form — the audit signal simply never reaches the operator.
+                    const repair = r.healed
+                        ? '\t(manifest healed — brain was wired but manifest-less, vfkb#193)'
+                        : r.upgraded
+                            ? '\t(manifest provenance upgraded — engine identity was unknown ("dev"), now the running sha, vfkb#212)'
+                            : '';
+                    process.stdout.write(`written\t${r.target}\t${r.id}\t${r.posture}${repair}\n`);
                 }
                 else {
                     failed++;

package/dist/docs-committed-brain-files.test.js

@@ -0,0 +1,416 @@
+import { describe, it, expect } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { initProject } from './init.js';
+/**
+ * Issue #220 — "only .vfkb/entries.jsonl is committed" is FALSE.
+ *
+ * `.vfkb/manifest.json` is committed BY DESIGN (ADR-0030: the brain↔engine
+ * version stamp, explicitly distinct from the derived, gitignored
+ * `index-meta.json`). The false sentence caused a real defect: the natural
+ * response to an untracked `manifest.json` is to gitignore it, and ViloGate
+ * ended up the only consumer with NO engine stamp at all.
+ *
+ * These guards assert at the altitude of the SHIPPED artifacts — the doc files
+ * a reader actually reads, and **git itself** for ground truth — not a helper.
+ *
+ * HISTORICAL documents are deliberately out of scope. `docs/adr/` and
+ * `docs/rfc/` are decided, immutable records (ADR-0001); the sentence was TRUE
+ * when RFC-011 was written (manifest.json arrived with ADR-0030, `.journal/`
+ * with ADR-0064). Editing a decided document to match present reality is the
+ * opposite of the immutability norm. CHANGELOG.md is a historical log too.
+ */
+const REPO = join(__dirname, '..');
+/** Docs a reader/agent consults for CURRENT truth. Excludes decided records. */
+const LIVE_DOCS = [
+    'CLAUDE.md',
+    'README.md',
+    'docs/CONSUMER-ONBOARDING.md',
+    'docs/CONSUMER-ONBOARDING-PROMPT.md',
+    'docs/RUNBOOK-claude-code-integration.md',
+];
+const read = (p) => readFileSync(join(REPO, p), 'utf8');
+/** The full derived/operational set that must be gitignored. */
+const DERIVED = [
+    'index-meta.json',
+    '.sessions/',
+    '.signals/',
+    '.journal/',
+    '.lock',
+];
+describe('the committed-vs-gitignored brain contract in live docs (issue #220)', () => {
+    it('GROUND TRUTH: git tracks entries.jsonl AND manifest.json under .vfkb/', () => {
+        const tracked = execFileSync('git', ['ls-files', '.vfkb/'], { cwd: REPO, encoding: 'utf8' })
+            .split('\n')
+            .filter(Boolean)
+            .sort();
+        // If this ever changes, the docs below are describing a different world and
+        // this whole test file must be revisited rather than the docs patched.
+        expect(tracked).toEqual(['.vfkb/entries.jsonl', '.vfkb/manifest.json']);
+    });
+    it.each(LIVE_DOCS)('%s does not repeat the false "only entries.jsonl" claim', (doc) => {
+        const text = read(doc);
+        // Matches "Only `.vfkb/entries.jsonl` is committed", "only entries.jsonl is
+        // committed", "`entries.jsonl` is committed, the rest is gitignored", etc.
+        const FALSE_CLAIM = /\b(only|Only)\b[^.\n]{0,40}`?\.?(vfkb\/)?entries\.jsonl`?[^.\n]{0,40}\bis committed\b/;
+        const REST_IS_IGNORED = /`entries\.jsonl`\s+is committed,\s*the rest is gitignored/;
+        expect(text, `${doc}: the false "only entries.jsonl is committed" claim`).not.toMatch(FALSE_CLAIM);
+        expect(text, `${doc}: "the rest is gitignored" is flatly false`).not.toMatch(REST_IS_IGNORED);
+    });
+    /**
+     * Split a markdown doc into STATEMENTS a reader consumes as one unit: a
+     * bullet / table row / code line, plus its indented continuation lines.
+     *
+     * Checking the whole document is too coarse to be a guard: a doc can drop
+     * manifest.json from its `git add` line and still pass, because the name
+     * survives in some unrelated paragraph. (Observed — three mutations passed a
+     * document-wide check.) The statement is the altitude a reader copies from.
+     */
+    function statements(text) {
+        const out = [];
+        let inFence = false;
+        let open = false; // is the last statement still accepting continuations?
+        // Unwrap blockquotes first — CONSUMER-ONBOARDING-PROMPT.md is one long `>`
+        // quote, and without this every wrapped continuation line looks like a new
+        // block, splitting one bullet into fragments and reporting a complete list
+        // as partial.
+        for (const raw of text.replace(/^> ?/gm, '').split('\n')) {
+            if (/^\s*```/.test(raw)) {
+                inFence = !inFence;
+                out.push(raw);
+                open = false;
+                continue;
+            }
+            // Inside a fence every line stands alone — a `git add` line is exactly
+            // what a reader copies, so it must carry the whole truth by itself.
+            if (inFence) {
+                out.push(raw);
+                open = false;
+                continue;
+            }
+            if (raw.trim() === '') {
+                open = false;
+                continue;
+            }
+            // Block starters: bullet, ordered item, table row, heading, blockquote
+            // bullet. Each begins a new statement.
+            const startsBlock = /^\s*(?:[-*+]\s|\d+\.\s|\||#{1,6}\s)/.test(raw);
+            if (open && !startsBlock)
+                out[out.length - 1] += ' ' + raw.trim();
+            else
+                out.push(raw.trim());
+            open = true;
+        }
+        return out;
+    }
+    /** A statement that tells the reader something is committed. */
+    const CLAIMS_COMMITTED = /\bgit add\b|\bis committed\b|\bare committed\b|\*\*Committed\b|\bCommitted (from|\(|:)/;
+    it.each(LIVE_DOCS.filter((d) => d !== 'README.md'))('%s names manifest.json in EVERY statement that says what is committed', (doc) => {
+        // Consecutive `git add` lines are ONE instruction to the reader — the
+        // correct form splits manifest.json onto its own guarded line (it may not
+        // exist on a plugin-born brain), so judging each line alone is wrong.
+        const merged = [];
+        for (const s of statements(read(doc))) {
+            const prev = merged[merged.length - 1];
+            if (prev !== undefined && /^\s*git add\b/.test(s) && /^\s*git add\b/.test(prev))
+                merged[merged.length - 1] = prev + ' ; ' + s.trim();
+            else
+                merged.push(s);
+        }
+        const relevant = merged.filter((s) => /entries\.jsonl/.test(s) && CLAIMS_COMMITTED.test(s));
+        // If none matched, the guard has silently stopped guarding.
+        expect(relevant.length, `${doc}: no committed-brain statement found to check`).toBeGreaterThan(0);
+        for (const s of relevant) {
+            expect(s, `${doc}: this statement tells the reader what is committed but omits manifest.json:\n  ${s.trim()}`).toMatch(/manifest\.json/);
+            // Naming manifest.json somewhere in the statement is not enough — the
+            // statement must not ALSO scope the committed set to entries.jsonh
+            // alone. "`entries.jsonl` only (…manifest.json…)" named it and still
+            // told the reader the wrong thing (mutation M4 stayed green).
+            // Tight window so the legitimate "written only by `vfkb init`" nearby
+            // is not caught.
+            expect(s, `${doc}: this statement scopes the committed set to entries.jsonl alone:\n  ${s.trim()}`).not.toMatch(/(?<![-\w])only\b[^.\n]{0,25}entries\.jsonl|entries\.jsonl[^.\n]{0,25}(?<![-\w])only\b/i);
+        }
+    });
+    it.each([
+        'docs/CONSUMER-ONBOARDING.md',
+        'docs/CONSUMER-ONBOARDING-PROMPT.md',
+        'docs/RUNBOOK-claude-code-integration.md',
+    ])('%s enumerates the COMPLETE derived/gitignored set', (doc) => {
+        const text = read(doc);
+        for (const p of DERIVED) {
+            expect(text, `${doc} omits the derived path ${p}`).toContain(p);
+        }
+    });
+    /**
+     * A reader copies a fenced gitignore block wholesale. Checking the document
+     * for the path names is too coarse — a block can drop `.lock` and still pass
+     * because the name survives in a prose bullet elsewhere (observed: mutation
+     * M9 stayed green against the document-wide check).
+     */
+    /**
+     * Pure extraction so BOTH the per-doc guard and the non-vacuity floor can
+     * call it. It used to be a module-level array populated by an earlier
+     * `it.each`, which made the floor depend on test execution ORDER — under
+     * `-t`, `--shard`, or a `.only` it failed spuriously, and a gate that blocks
+     * honest work is a defect in its own right.
+     */
+    function gitignoreBlocks(doc) {
+        // Consume ANY language tag. Matching only ```/```gitignore mispairs the
+        // fences (a ```sh open is skipped, so the block boundaries invert) and the
+        // filter below then silently keeps nothing — a vacuous test. Verified
+        // non-empty by the count assertion at the end of this file.
+        const text = read(doc).replace(/^> ?/gm, ''); // unwrap blockquoted fences
+        return ([...text.matchAll(/```[A-Za-z]*\n([\s\S]*?)```/g)]
+            .map((m) => m[1])
+            // A gitignore block: every non-comment line is a bare path, and at least
+            // one is a .vfkb path. Commands (git add …, node …) are not.
+            .filter((b) => /^\s*\.vfkb\/\S+\s*$/m.test(b) &&
+            b
+                .split('\n')
+                .filter((l) => l.trim() && !l.trim().startsWith('#'))
+                .every((l) => /^\s*\S+\s*$/.test(l) && !/[$=]|^\s*(git|node|npm|claude)\b/.test(l))));
+    }
+    it.each(LIVE_DOCS)('%s: every copyable .vfkb gitignore block is COMPLETE and correct', (doc) => {
+        for (const b of gitignoreBlocks(doc)) {
+            for (const p of DERIVED)
+                expect(b, `${doc}: gitignore block omits ${p}:\n${b}`).toContain(p);
+            expect(b, `${doc}: a gitignore block ignores the COMMITTED manifest.json:\n${b}`).not.toMatch(/manifest\.json/);
+            expect(b, `${doc}: a gitignore block ignores the COMMITTED entries.jsonl:\n${b}`).not.toMatch(/entries\.jsonl/);
+        }
+    });
+    /**
+     * The catch-all. Not every ignore list is a fenced block — the onboarding
+     * PROMPT carries one as a `#` comment inside a bash fence, which the fence
+     * guard skips (mutation M12 stayed green). Rule: any statement that
+     * enumerates two or more derived paths is presenting "the set", so it must
+     * present the WHOLE set. A partial list is how `.journal/` and `.lock` went
+     * missing from 10 consumer repos.
+     *
+     * KNOWN FALSE POSITIVE (accepted, and cheap to work around): a statement that
+     * legitimately discusses a SUBSET for some other reason — e.g. "`.sessions/`
+     * and `.signals/` are per-machine" — is rejected too, because the rule cannot
+     * tell "here is the ignore set" from "here are two of its members". Scoping it
+     * to statements containing the word "gitignore" was tried and is worse: the
+     * PROMPT's list lives on a bare `#   .vfkb/…` line whose gating word is on the
+     * PREVIOUS line, so the scoped rule let mutation M12 through. Blocking an
+     * honest sentence is a defect (review charge step 6) — the escape hatch is to
+     * split such a sentence, or add it to an exemption list here with a reason.
+     * The scope is 5 curated docs, so the blast radius is small and visible.
+     */
+    it.each(LIVE_DOCS)('%s: no statement enumerates a PARTIAL derived set', (doc) => {
+        for (const s of statements(read(doc))) {
+            const present = DERIVED.filter((p) => s.includes(p));
+            if (present.length < 2)
+                continue;
+            const missing = DERIVED.filter((p) => !s.includes(p));
+            expect(missing, `${doc}: partial derived set — missing ${missing.join(', ')}:\n  ${s}`).toEqual([]);
+        }
+    });
+    /**
+     * The correction must not overshoot into a SECOND false claim.
+     * `writeManifest` has exactly two call sites — `vfkb init` (src/init.ts) and
+     * the cross-repo broadcast heal (src/broadcast.ts). The ordinary write path
+     * never creates a manifest, so a PLUGIN-born brain legitimately has none
+     * (vfkb#193), and `doctor` reports that as a warn. An onboarding doc that
+     * says "commit manifest.json" unconditionally hands the plugin reader a
+     * `git add` that fails with "pathspec did not match".
+     */
+    it('the two writeManifest call sites are still exactly init + broadcast', () => {
+        // Scan EVERY src/*.ts — a hardcoded candidate list can only notice a caller
+        // disappearing, never one being ADDED, which is the direction that falsifies
+        // the docs' "exactly two callers" claim. (That was the bug: the old filter's
+        // own comment said "if this list grows…" over a list that could not grow.)
+        const files = execFileSync('git', ['ls-files', 'src/*.ts'], { cwd: REPO, encoding: 'utf8' })
+            .split('\n')
+            .filter((f) => f && !f.endsWith('.test.ts'));
+        expect(files.length, 'no src files scanned — the guard would pass vacuously').toBeGreaterThan(10);
+        // Strip line comments first — grepping the raw text counts a COMMENTED-OUT
+        // call as a live call site (mutation M16 stayed green against that).
+        const callers = files.filter((f) => /writeManifest\s*\(/.test(read(f)
+            .split('\n')
+            .filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l))
+            .join('\n')));
+        // If this list grows, the "plugin-born brains have none" caveat in the docs
+        // may have stopped being true and must be re-checked against the new caller.
+        expect(callers.sort()).toEqual(['src/broadcast.ts', 'src/init.ts', 'src/manifest.ts']);
+    });
+    /**
+     * POLARITY. The guards above check that manifest.json is NAMED and that fenced
+     * ignore blocks do not list it — but a prose sentence is what a reader acts on,
+     * and flipping "never gitignore `manifest.json`" to "always gitignore
+     * `manifest.json`" satisfies every one of them. That single flip reintroduces
+     * the exact ViloGate defect this file exists to prevent, so the polarity of the
+     * rule is itself the thing to assert.
+     *
+     * The negation must sit ADJACENT to the verb (only markdown emphasis or a short
+     * "a reason to" may intervene). A loose "somewhere in the sentence there is a
+     * 'not'" test passes on "…is not one — gitignoring it is fine", which is the
+     * failure it is meant to catch.
+     */
+    const NEVER_GITIGNORE = /\b(?:never|not)\b[\s*_`]{0,6}(?:a reason to\s+)?gitignor/i;
+    /**
+     * Fires only when the gitignore VERB is applied to manifest.json — the two are
+     * within 30 characters of each other. Merely co-occurring in a long sentence is
+     * not the claim (`init` "writes … `manifest.json` … and the `.gitignore`
+     * stanza" is honest, as is "`manifest.json` … is committed; the derived paths
+     * are gitignored"). `(?<!\.)` drops the FILENAME `.gitignore`, which is a noun.
+     *
+     * The window is `[^\n]` and NOT `[^.\n]`: excluding dots looked tidier but the
+     * path a doc actually writes is `.vfkb/manifest.json`, whose own dots ended the
+     * window early — the flip "do NOT gitignore .vfkb/manifest.json" → "do
+     * gitignore .vfkb/manifest.json" stayed GREEN against the dot-excluding form.
+     */
+    const IGNORES_MANIFEST = /(?<!\.)gitignor\w*[^\n]{0,30}manifest\.json|manifest\.json[^\n]{0,30}(?<!\.)gitignor/i;
+    it.each(LIVE_DOCS)('%s: no statement tells the reader to gitignore manifest.json', (doc) => {
+        for (const s of statements(read(doc))) {
+            if (!IGNORES_MANIFEST.test(s))
+                continue;
+            expect(s, `${doc}: this statement pairs manifest.json with gitignoring and is NOT negated — ` +
+                `it reads as an instruction to ignore the committed engine stamp:\n  ${s}`).toMatch(NEVER_GITIGNORE);
+        }
+    });
+    // README.md is a project overview, not a wiring doc — it never enumerates the
+    // ignore contract, so requiring the rule there would block honest prose. The
+    // other four are exactly the docs a consumer acts on.
+    it.each(LIVE_DOCS.filter((d) => d !== 'README.md'))('%s: states the never-gitignore-manifest.json rule outright', (doc) => {
+        const stated = statements(read(doc)).filter((s) => /manifest\.json/.test(s) && NEVER_GITIGNORE.test(s));
+        expect(stated.length, `${doc}: the load-bearing rule "never gitignore manifest.json" is absent. ` +
+            `Naming manifest.json on a committed list is not enough — the reader's mistake ` +
+            `is ignoring it, so the doc must say not to.`).toBeGreaterThan(0);
+    });
+    /**
+     * A reader who skims to the copyable gitignore fence never reads the prose
+     * above it. The correction is only delivered if it sits where they land, so
+     * every fence must be followed by the rule. This is what makes the sentence
+     * after each block undeletable — deleting it, or the RUNBOOK's whole
+     * committed-vs-gitignored section, previously left the suite green.
+     */
+    it.each(LIVE_DOCS)('%s: every .vfkb gitignore fence is followed by the rule', (doc) => {
+        const lines = read(doc).replace(/^> ?/gm, '').split('\n');
+        for (const b of gitignoreBlocks(doc)) {
+            const firstPath = b.split('\n').find((l) => l.trim().startsWith('.vfkb/')).trim();
+            const at = lines.findIndex((l) => l.trim() === firstPath);
+            expect(at, `${doc}: could not locate the block in the file`).toBeGreaterThan(-1);
+            // Find the closing fence, then look at the prose immediately after it.
+            let close = at;
+            while (close < lines.length && !/^\s*```\s*$/.test(lines[close]))
+                close++;
+            const after = lines.slice(close + 1, close + 13).join('\n');
+            expect(after, `${doc}: the gitignore block a reader copies is not followed by ` +
+                `"never gitignore manifest.json". A skimmer copies the block and never sees ` +
+                `the warning:\n${after}`).toMatch(NEVER_GITIGNORE);
+            expect(after, `${doc}: the post-block warning does not name manifest.json`).toMatch(/manifest\.json/);
+        }
+    });
+    /**
+     * The RUNBOOK's canonical reference block. Every guard above is document-wide
+     * or fence-anchored, so this whole section could be DELETED and the suite
+     * stayed green — the RUNBOOK's §6 fence and §0 table independently satisfied
+     * the document-wide `toContain` checks. That is the "commenting out every
+     * emitted path still passed" failure mode: the section is a deliverable, so
+     * assert it exists and that its BODY carries the contract.
+     */
+    it('the RUNBOOK keeps its "Committed vs gitignored" section, correct and complete', () => {
+        const text = read('docs/RUNBOOK-claude-code-integration.md');
+        const HEADING = '### Committed vs gitignored in `.vfkb/`';
+        const at = text.indexOf(HEADING);
+        expect(at, `the RUNBOOK's "${HEADING}" section is gone`).toBeGreaterThan(-1);
+        // Body = up to the next heading of any level.
+        const rest = text.slice(at + HEADING.length);
+        const end = rest.search(/\n#{1,6} |\n---\s*\n/);
+        const body = end === -1 ? rest : rest.slice(0, end);
+        expect(body.length, 'the section heading survives but its body is empty').toBeGreaterThan(200);
+        const committed = body.split(/\*\*Gitignored/)[0];
+        expect(committed, 'the section no longer lists manifest.json as committed').toMatch(/manifest\.json/);
+        expect(committed, 'the section no longer lists entries.jsonl as committed').toMatch(/entries\.jsonl/);
+        for (const p of DERIVED)
+            expect(body, `the section's gitignored list omits ${p}`).toContain(p);
+        expect(body, 'the section no longer carries the never-gitignore rule').toMatch(NEVER_GITIGNORE);
+    });
+    /**
+     * SCOPE. LIVE_DOCS is a curated list, so the false claim could be reintroduced
+     * in any doc outside it with no CI signal. Sweep every tracked markdown file
+     * instead, minus the decided/immutable records (ADR-0001) and the changelog,
+     * where the sentence was TRUE when written.
+     */
+    it('no tracked markdown outside the decided records repeats the false claim', () => {
+        const docs = execFileSync('git', ['ls-files', '*.md'], { cwd: REPO, encoding: 'utf8' })
+            .split('\n')
+            .filter((f) => f && !f.startsWith('docs/adr/') && !f.startsWith('docs/rfc/') && f !== 'CHANGELOG.md');
+        expect(docs.length, 'no markdown scanned — vacuous').toBeGreaterThan(5);
+        const FALSE_CLAIM = /\b(only|Only)\b[^.\n]{0,40}`?\.?(vfkb\/)?entries\.jsonl`?[^.\n]{0,40}\bis committed\b/;
+        // Statement-level, so a sentence that QUOTES the claim in order to call it
+        // false — the roadmap's record of the defect — is a description, not a
+        // repetition. Anything asserting it as fact carries no such disclaimer.
+        const offenders = docs.flatMap((f) => statements(read(f))
+            .filter((s) => FALSE_CLAIM.test(s) && !/\bfalse\b/i.test(s) && !/#220\b/.test(s))
+            .map((s) => `${f}: ${s.slice(0, 120)}`));
+        expect(offenders, 'these statements repeat "only entries.jsonl is committed"').toEqual([]);
+    });
+    /**
+     * The ENGINE is an emitter of this contract too: `vfkb init` writes an
+     * AGENTS.md stanza into every newly-wired consumer repo. It shipped the same
+     * partial-derived-set defect the docs had (3 of 5 paths), so a consumer's own
+     * agent instructions taught the mistake this PR corrects everywhere else.
+     * Asserted against the FILE init actually writes, not the source template.
+     */
+    it('vfkb init writes an AGENTS.md stanza with the complete, correct contract', () => {
+        const root = mkdtempSync(join(tmpdir(), 'vfkb-agents-'));
+        try {
+            initProject(root, { project: 'probe' });
+            const agents = readFileSync(join(root, 'AGENTS.md'), 'utf8');
+            for (const p of DERIVED)
+                expect(agents, `init's AGENTS.md omits the derived path ${p}`).toContain(p);
+            expect(agents, "init's AGENTS.md omits the committed manifest.json").toContain('manifest.json');
+            expect(agents, "init's AGENTS.md does not carry the never-gitignore rule").toMatch(NEVER_GITIGNORE);
+            for (const s of statements(agents)) {
+                if (!IGNORES_MANIFEST.test(s))
+                    continue;
+                expect(s, `init's AGENTS.md tells the agent to gitignore manifest.json:\n  ${s}`).toMatch(NEVER_GITIGNORE);
+            }
+        }
+        finally {
+            rmSync(root, { recursive: true, force: true });
+        }
+    });
+    it.each(['docs/CONSUMER-ONBOARDING.md', 'docs/CONSUMER-ONBOARDING-PROMPT.md'])('%s does not promise manifest.json unconditionally exists', (doc) => {
+        const text = read(doc);
+        // It must carry the caveat...
+        expect(text, `${doc}: no plugin-born-brain caveat for manifest.json`).toMatch(/plugin-born|if present|whenever it exists|have none/i);
+        // ...and no bare `git add` may list manifest.json as a required pathspec
+        // without an escape (|| true / 2>/dev/null), which is what fails on a
+        // plugin-wired repo.
+        for (const s of statements(text)) {
+            if (!/^\s*git add\b/.test(s) || !/manifest\.json/.test(s))
+                continue;
+            expect(s, `${doc}: this git add fails on a plugin-born brain:\n  ${s}`).toMatch(/\|\|\s*true|2>\/dev\/null/);
+        }
+    });
+    // The check above is a loop over a filtered list — if the filter matches
+    // nothing it passes vacuously (it did, on the first draft: a fence-pairing
+    // bug left 0 blocks and 3 mutations stayed green). This asserts the guard
+    // actually had something to guard.
+    it('the gitignore-block guard is not vacuous — it saw real blocks', () => {
+        const seen = LIVE_DOCS.flatMap(gitignoreBlocks);
+        expect(seen.length).toBeGreaterThanOrEqual(2);
+    });
+    it("this repo's own .gitignore ignores every derived path and NOT the committed ones", () => {
+        const gi = read('.gitignore');
+        for (const p of DERIVED)
+            expect(gi, `.gitignore omits ${p}`).toContain(`.vfkb/${p}`);
+        expect(gi).not.toMatch(/^\.vfkb\/manifest\.json\s*$/m);
+        expect(gi).not.toMatch(/^\.vfkb\/entries\.jsonl\s*$/m);
+    });
+    it('doctor.ts does not enumerate a stale partial gitignore set in prose', () => {
+        // Strip comment markers + collapse whitespace so a claim that spans a
+        // wrapped comment still matches (the stale one did).
+        const src = read('src/doctor.ts').replace(/^\s*\/\/ ?/gm, '').replace(/\s+/g, ' ');
+        // The old comment said only `.signals/` (plus .sessions/ and
+        // index-meta.json) is in init's stanza — 3 of 5, stale since ADR-0064.
+        expect(src).not.toMatch(/plus \.sessions\/ and index-meta\.json/);
+        // And it must name the two paths ADR-0064 / the lock added.
+        expect(src).toMatch(/\.journal\//);
+    });
+});

package/dist/doctor.js

@@ -3,8 +3,8 @@
 // or inconsistent wiring, and the dual-clone drift signal (a brain last stamped by
 // a different engine build). Deterministic; unit-tested (the inner gate per ADR-0023).
 import { execFileSync } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { join, dirname, relative, resolve, isAbsolute } from 'node:path';
 import { SCHEMA_VERSION, ENGINE_VERSION, ENGINE_COMMIT } from './version.js';
 import { journalStatus } from './journal.js';
 import { readManifest } from './manifest.js';
@@ -313,12 +313,81 @@ export async function checkNpmCurrency(opts) {
         clearTimeout(timer);
     }
 }
+// #186 — what OLD (pre-plugin) vfkb wiring actually is: a hook command that
+// invokes the ENGINE's hook dispatcher, either through the committed bootstrap
+// (ADR-0031) or by naming a hook subcommand directly.
+//
+// The predicate used to be `JSON.stringify(hook).includes('vfkb')`, which
+// classified ANY hook mentioning the string as old wiring — including the
+// ADR-0059 INACTIVE guard (`.claude/vfkb-guard.mjs`) that the plugin's own
+// MIGRATION_GUIDE tells every consumer to commit. So a correctly migrated repo
+// was told to delete its own INACTIVE detector, and real double wiring was
+// buried in a warning consumers had learned to ignore.
+const HOOK_SUBCOMMANDS = ['session-start', 'pre-tool-use', 'post-tool-use', 'stop', 'session-end'];
+export function isEngineWiring(hookJson) {
+    // Compare against the LITERAL command text, not its JSON encoding: a tab in the
+    // command is the two characters \\t once stringified, and a quoted subcommand is
+    // \\". Un-escaping first means the separator rule below is about real whitespace
+    // and quoting rather than about JSON spelling. (Review of PR #216, minor 5: the
+    // previous `\\?` sat before the whitespace, where JSON never puts a backslash.)
+    const text = hookJson.replace(/\\[tnr]/g, ' ').replace(/\\(.)/g, '$1');
+    if (/bootstrap\.mjs/.test(text))
+        return true;
+    return new RegExp(`\\bhook["'\\s]+(${HOOK_SUBCOMMANDS.join('|')})\\b`).test(text);
+}
+// #212 — a sentinel commit means "this build does not know its own identity"
+// (version.ts's honest `dev` fallback on the tsc/dist path), NOT "a different
+// engine stamped this brain". Comparing a sentinel against a real sha is not a
+// drift observation, it is an absence of one.
+//
+// The old predicate exempted a dev RUNNING engine but not a dev MANIFEST, so a
+// brain stamped by a dist-path build (e.g. the documented `node dist/cli.js`
+// fallback, which is how ViloGate's manifest got `"dev"`) reported drift forever
+// against every real-sha engine.
+export function engineDrift(manifestCommit, runningCommit) {
+    if (!manifestCommit || manifestCommit === 'dev')
+        return false;
+    if (!runningCommit || runningCommit === 'dev')
+        return false;
+    return manifestCommit !== runningCommit;
+}
+// #206 — the work tree that actually governs a path, or undefined outside a repo.
+function repoToplevel(root) {
+    try {
+        return execFileSync('git', ['-C', root, 'rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+// Containment on path BOUNDARIES: `/repo` must not be judged to contain
+// `/repo-other/...`. Both sides are realpath'd so a symlinked brain dir (or a
+// /tmp that resolves to /private/tmp) compares honestly rather than by spelling.
+function isUnder(parent, child) {
+    if (!parent)
+        return false;
+    const real = (p) => {
+        try {
+            return realpathSync(p);
+        }
+        catch {
+            return resolve(p);
+        }
+    };
+    const rel = relative(real(parent), real(child));
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
 export function runDoctor(opts) {
     const { root, brainDir, env } = opts;
+    // The identity we compare the brain's stamp against (injectable — see DoctorOpts).
+    const runningCommit = opts.engineCommit ?? ENGINE_COMMIT;
     const checks = [];
     const add = (name, status, detail) => checks.push({ name, status, detail });
     // 1. Engine identity (info).
-    add('engine', 'ok', `version ${ENGINE_VERSION} · commit ${ENGINE_COMMIT} · schema v${SCHEMA_VERSION}`);
+    add('engine', 'ok', `version ${ENGINE_VERSION} · commit ${runningCommit} · schema v${SCHEMA_VERSION}`);
     // Read the project settings once (used by plugin detection, hooks checks, and
     // project-consistency below), and detect ADR-0045 plugin wiring up front — it changes
     // what "healthy" means for the wiring checks AND which advice is safe to give
@@ -330,9 +399,19 @@ export function runDoctor(opts) {
     // 2. Brain ↔ engine compat (the load-bearing check).
     const mf = readManifest(brainDir);
     if (!mf) {
-        add('brain manifest', 'warn', plugin
-            ? `no manifest.json in ${brainDir} — it will be stamped on the next write`
-            : `no manifest.json in ${brainDir} — run \`vfkb init\` (or it will be stamped on next write)`);
+        add('brain manifest', 'warn', 
+        // #188 — the ordinary write path (addEntry → appendRecord → backend.append)
+        // never touches manifest.json. `writeManifest` has exactly two callers:
+        // `vfkb init` (init.ts) and the broadcast heal, which fires only when the
+        // manifest is ABSENT (broadcast.ts). Saying "on the next write" claimed
+        // behaviour the code does not have.
+        // On a PLUGIN-wired repo the message must not prescribe `vfkb init` — that
+        // advice is what scaffolds double wiring (issue #77), and the invariant is
+        // asserted in doctor.test.ts. A plugin-born brain simply has no manifest
+        // until a cross-repo broadcast heals it (vfkb#193).
+        plugin
+            ? `no manifest.json in ${brainDir} — plugin-born brains have none until a cross-repo broadcast heals it (vfkb#193); the ordinary write path never creates one`
+            : `no manifest.json in ${brainDir} — run \`vfkb init\` to stamp it (the ordinary write path never creates one)`);
     }
     else if (typeof mf.schema_version !== 'number') {
         add('brain manifest', 'warn', 'manifest has no numeric schema_version');
@@ -344,10 +423,19 @@ export function runDoctor(opts) {
         add('brain↔engine compat', 'warn', `brain schema v${mf.schema_version} is older than engine v${SCHEMA_VERSION} — migration may be needed`);
     }
     else {
-        add('brain↔engine compat', 'ok', `schema v${mf.schema_version} matches`);
+        // #212 — a sentinel stamp is suppressed as DRIFT (it is not drift), but it must
+        // not become invisible: the brain's provenance genuinely is unrecorded, and the
+        // stamping half of #212 (a build that does not know its commit should not write
+        // one) is still open. Reported in the detail rather than as a new warn — it is a
+        // true statement, but not one the consumer can act on, and this PR exists to stop
+        // doctor crying wolf.
+        const sentinel = mf.engine_commit === 'dev'
+            ? ` · stamped by a build that did not know its own commit ("dev") — provenance unknown (#212)`
+            : '';
+        add('brain↔engine compat', 'ok', `schema v${mf.schema_version} matches${sentinel}`);
         // Drift signal: same schema but a different engine build last stamped the brain.
-        if (mf.engine_commit && ENGINE_COMMIT !== 'dev' && mf.engine_commit !== ENGINE_COMMIT) {
-            add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${ENGINE_COMMIT} — possible dual-clone drift`);
+        if (engineDrift(mf.engine_commit, runningCommit)) {
+            add('engine drift', 'warn', `brain last stamped by engine ${mf.engine_commit}, running ${runningCommit} — possible dual-clone drift`);
         }
     }
     // 2b. Durable-capture journal (ADR-0064): what would recovery do, and is a
@@ -367,7 +455,12 @@ export function runDoctor(opts) {
         // has no .journal/ gitignore line — its next `git add .vfkb` would COMMIT
         // the wal (a tracked journal dies by the same reset --hard, RFC-034
         // Alternatives; and a committed wal defeats §4 redaction).
-        if (existsSync(join(brainDir, '.journal'))) {
+        // #206 — judge only a journal the repo actually governs. With the brain on
+        // the default ~/.vfkb tier (VFKB_DATA_DIR outside the work tree),
+        // `check-ignore` exits 128 ("path outside work tree"), which the catch-all
+        // below read as plain "not ignored" — so doctor advised editing a .gitignore
+        // that does not govern that path at all.
+        if (existsSync(join(brainDir, '.journal')) && isUnder(repoToplevel(root), join(brainDir, '.journal'))) {
             try {
                 execFileSync('git', ['-C', root, 'check-ignore', '-q', join(brainDir, '.journal', 'wal.jsonl')], {
                     stdio: 'ignore',
@@ -430,7 +523,7 @@ export function runDoctor(opts) {
     // 5. Hooks wiring (same plugin logic as check 4).
     const hooks = settings?.hooks ?? {};
     const expected = ['SessionStart', 'PreToolUse', 'Stop', 'SessionEnd'];
-    const have = expected.filter((e) => JSON.stringify(hooks[e] ?? '').includes('vfkb'));
+    const have = expected.filter((e) => isEngineWiring(JSON.stringify(hooks[e] ?? '')));
     if (plugin && have.length > 0) {
         add('.claude/settings.json', 'warn', `vfkb hooks present ALONGSIDE the plugin (double wiring) — remove them; the plugin's hooks are primary (ADR-0045)`);
     }