@viloforge/vfkb 0.2.1

package/dist/env-compat.test.js

@@ -0,0 +1,23 @@
+// ADR-0032 — env var rename with back-compat: VFKB_DATA_DIR is canonical,
+// VFKB_DIR is a kept-working deprecated alias. (The bundle-var alias
+// VFKB_BUNDLE_DIR/VFKB_HOME is covered by src/bootstrap.test.ts + doctor.test.ts.)
+import { describe, it, expect, afterEach } from 'vitest';
+import { brainDir } from './storage.js';
+const saved = { data: process.env.VFKB_DATA_DIR, dir: process.env.VFKB_DIR };
+const restore = (k, v) => v === undefined ? delete process.env[k] : (process.env[k] = v);
+afterEach(() => {
+    restore('VFKB_DATA_DIR', saved.data);
+    restore('VFKB_DIR', saved.dir);
+});
+describe('env var back-compat (ADR-0032)', () => {
+    it('VFKB_DATA_DIR is canonical and takes precedence over VFKB_DIR', () => {
+        process.env.VFKB_DATA_DIR = '/canonical';
+        process.env.VFKB_DIR = '/legacy';
+        expect(brainDir()).toBe('/canonical');
+    });
+    it('VFKB_DIR still resolves the brain as a deprecated alias', () => {
+        delete process.env.VFKB_DATA_DIR;
+        process.env.VFKB_DIR = '/legacy';
+        expect(brainDir()).toBe('/legacy');
+    });
+});

package/dist/export.js

@@ -0,0 +1,371 @@
+// ADR-0047 (accepts RFC-022) — brain export projections: `vfkb export agents-md` +
+// `vfkb export okf`. One projection core, two render targets. The output is a pure
+// function of the brain's content: the "as-of" moment is max(entry.updated) — never
+// the wall clock — the tree rewrite never reads previously emitted output, ordering
+// is total (heuristicCompare + id tiebreak), and filenames derive from the entry id
+// alone. The ADR-0046 ratchet is the publish filter for BOTH targets.
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { deriveConstitution, effectiveStatus, heuristicCompare, isDecisionFamily, isInjectable, readAll, supersededIds, } from './engine.js';
+import { defaultProject, isTombstone, readContextSpine, readRecords } from './storage.js';
+import { normalizeEntry } from './validate.js';
+// Stamped into every emitted file; the scoped sweep deletes ONLY files carrying it,
+// and refuses a non-empty target that has none (a one-flag `--out` mistake must
+// hard-fail, not destroy hand-written content).
+export const GENERATED_MARKER = 'generated by vfkb export';
+// The sweep/guard check is LINE-ANCHORED to the emitted shape — a hand-written doc
+// that merely QUOTES the marker phrase mid-sentence (RFC-022 itself does) must
+// neither defeat the refusal nor enter the deletion set.
+const MARKER_LINE_RE = /^<!-- generated by vfkb export /m;
+// Export-sized budget for the AGENTS.md digest (a cold-agent digest, not a dump).
+export const EXPORT_BUDGET_CHARS = 40_000;
+const TYPE_DIR = {
+    fact: 'facts',
+    gotcha: 'gotchas',
+    pattern: 'patterns',
+    decision: 'decisions',
+    link: 'links',
+};
+// --- the shared projection core -------------------------------------------------
+// asOf = max(entry.updated) across the live brain — the projection's clock.
+function asOfDate(entries) {
+    let max = '';
+    for (const e of entries)
+        if (e.updated > max)
+            max = e.updated;
+    return (max || '0000-01-01').slice(0, 10);
+}
+// Total, stable ordering: heuristicCompare (tier → trust → recency) with an explicit
+// id tiebreak — same-millisecond writes exist, and V8 sort stability is not a contract.
+function exportCompare(a, b) {
+    return heuristicCompare(a, b) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+// The four-clause export predicate (ADR-0046's ratchet, RFC-022 §Target 2).
+// isInjectable evaluated at asOf carries clauses 2–4 (superseded/deprecated,
+// zone ≠ archive, stale/expired provenance, validity window open at asOf); the
+// ratchet adds verified-only and accepted-only-for-decisions on top. It is
+// deliberately STRICTER than live injection (ADR-0005 keeps unverified-labelled
+// injection for sessions; publishing is a different trust boundary).
+function exportEligible(e, asOf, superseded) {
+    if (!isInjectable(e, asOf, superseded))
+        return false;
+    if (e.provenance.status !== 'verified')
+        return false;
+    if (isDecisionFamily(e.type) && effectiveStatus(e, superseded) !== 'accepted')
+        return false;
+    return true;
+}
+// Record-level publish-grade check for the log.md derivation: was THIS historical
+// record's state publish-grade on its own terms? No superseded set (supersession is
+// a current-state fact, not a property of the old record) and no validity clause
+// (expiry is how an entry LEAVES the published view, which is what the log records).
+function recordWasPublishGrade(e) {
+    if (e.zone === 'archive')
+        return false;
+    if (e.provenance.status !== 'verified')
+        return false;
+    if (isDecisionFamily(e.type) && e.status !== 'accepted')
+        return false;
+    return true;
+}
+function firstSentence(text, max = 120) {
+    const oneLine = text.split('\n')[0];
+    const dot = oneLine.indexOf('. ');
+    const s = dot > 0 ? oneLine.slice(0, dot + 1) : oneLine;
+    return s.length > max ? `${s.slice(0, max - 1)}…` : s;
+}
+const yamlStr = (s) => JSON.stringify(s);
+function projectionInputs() {
+    const all = readAll();
+    const superseded = supersededIds(all);
+    const asOf = asOfDate(all);
+    const eligible = all.filter((e) => exportEligible(e, asOf, superseded)).sort(exportCompare);
+    return { all, superseded, asOf, eligible };
+}
+// --- the scoped sweep ------------------------------------------------------------
+function listFiles(dir) {
+    const out = [];
+    const walk = (d) => {
+        for (const name of readdirSync(d)) {
+            const p = join(d, name);
+            if (statSync(p).isDirectory())
+                walk(p);
+            else
+                out.push(p);
+        }
+    };
+    walk(dir);
+    return out;
+}
+function isGenerated(path) {
+    if (!path.endsWith('.md'))
+        return false;
+    try {
+        return MARKER_LINE_RE.test(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+}
+// Rewrite-preparation for the OKF tree: delete ONLY generated-marker files (then any
+// dirs left empty); refuse outright when a non-empty target carries no generated
+// files at all — that is a wrong `--out`, not a previous export.
+function prepareTree(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+        return;
+    }
+    const files = listFiles(dir);
+    if (files.length === 0)
+        return;
+    const generated = files.filter(isGenerated);
+    if (generated.length === 0) {
+        throw new Error(`vfkb export: refusing to write into non-empty ${dir} — it contains no generated files; point --out at an empty directory or a previous export target`);
+    }
+    for (const f of generated)
+        rmSync(f);
+    // remove dirs the sweep emptied (bottom-up), leaving any dir still holding foreign files
+    const dirs = [];
+    const collect = (d) => {
+        for (const name of readdirSync(d)) {
+            const p = join(d, name);
+            if (statSync(p).isDirectory()) {
+                collect(p);
+                dirs.push(p);
+            }
+        }
+    };
+    collect(dir);
+    for (const d of dirs.reverse()) {
+        if (readdirSync(d).length === 0)
+            rmSync(d, { recursive: true });
+    }
+}
+// --- target 1: AGENTS.md ----------------------------------------------------------
+export function exportAgentsMd(opts = {}) {
+    const { superseded, asOf, eligible } = projectionInputs();
+    const project = opts.project ?? defaultProject();
+    const budget = opts.budget ?? EXPORT_BUDGET_CHARS;
+    const out = opts.out ?? join(process.cwd(), 'AGENTS.md');
+    if (existsSync(out) && !MARKER_LINE_RE.test(readFileSync(out, 'utf8'))) {
+        throw new Error(`vfkb export: refusing to overwrite ${out} — it is not a previous export (no generated marker)`);
+    }
+    // Constitution leads (ADR-0008) — but the ratchet still binds: a constitutional
+    // decision below the publish bar does not ship.
+    const constitution = deriveConstitution().filter((e) => exportEligible(e, asOf, superseded));
+    const constitutionalIds = new Set(constitution.map((c) => c.id));
+    const knowledge = eligible.filter((e) => !constitutionalIds.has(e.id));
+    let head = `<!-- ${GENERATED_MARKER} agents-md; regenerate with \`vfkb export agents-md\`, do not hand-edit (as-of ${asOf}) -->\n` +
+        `# ${project} — agent context (generated from the vfkb brain)\n\n`;
+    if (constitution.length > 0) {
+        head += '## Constitution (always applies)\n';
+        for (const c of constitution) {
+            const n = typeof c.adr_no === 'number' ? `ADR-${String(c.adr_no).padStart(4, '0')} ` : '';
+            head += `- [${n}constitutional] ${c.text}\n`;
+        }
+        head += '\n';
+    }
+    // Export-variant map: counts over the PUBLISHED subset only (unpublished entries
+    // leak neither counts nor tag strings), no live-session affordances.
+    const published = [...constitution, ...knowledge];
+    const byType = new Map();
+    const tagCounts = new Map();
+    let accepted = 0;
+    for (const e of published) {
+        byType.set(e.type, (byType.get(e.type) ?? 0) + 1);
+        for (const t of e.tags)
+            tagCounts.set(t, (tagCounts.get(t) ?? 0) + 1);
+        if (isDecisionFamily(e.type))
+            accepted++;
+    }
+    const typesLine = [...byType.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([t, n]) => `${t} ${n}`)
+        .join(' · ');
+    const topTags = [...tagCounts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 8)
+        .map(([t, n]) => `${t}(${n})`)
+        .join(' ');
+    head += '## Map\n';
+    head += `${published.length} published entr${published.length === 1 ? 'y' : 'ies'}${typesLine ? ` · ${typesLine}` : ''}\n`;
+    head += `decisions: ${accepted} accepted (${constitution.length} constitutional)\n`;
+    if (topTags)
+        head += `top tags: ${topTags}\n`;
+    head += '\n';
+    const spine = readContextSpine();
+    if (spine)
+        head += `## Context (authored spine)\n${spine.trim()}\n\n`;
+    head += '## Knowledge (verified, published)\n';
+    let body = '';
+    let dropped = 0;
+    for (const e of knowledge) {
+        const line = `- [${e.type}] ${e.text}\n`;
+        if (head.length + body.length + line.length > budget) {
+            dropped++;
+            continue;
+        }
+        body += line;
+    }
+    if (dropped > 0)
+        body += `<!-- ${dropped} entries omitted for the ${budget}-char budget -->\n`;
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, head + body);
+    return { path: out };
+}
+// --- target 2: the OKF v0.1 bundle -------------------------------------------------
+function okfDoc(e, asOf, exportedDirs) {
+    const title = firstSentence(e.text);
+    const fm = ['---'];
+    fm.push(`type: ${e.type}`);
+    fm.push(`title: ${yamlStr(title)}`);
+    fm.push(`description: ${yamlStr(title)}`);
+    if (e.tags.length > 0)
+        fm.push(`tags: ${JSON.stringify(e.tags)}`);
+    fm.push(`timestamp: ${e.updated}`);
+    if (e.type === 'link') {
+        const url = /https?:\/\/[^\s)"'\]]+/.exec(e.text)?.[0]?.replace(/[.,;:]+$/, '');
+        if (url)
+            fm.push(`resource: ${yamlStr(url)}`); // never fabricated — only a real URL
+    }
+    fm.push(`generated_by: vfkb export okf`);
+    fm.push('---');
+    let body = `<!-- ${GENERATED_MARKER} okf; regenerate with \`vfkb export okf\`, do not hand-edit (as-of ${asOf}) -->\n\n`;
+    body += `${e.text.trim()}\n`;
+    const citations = [];
+    for (const rel of e.refs?.related ?? []) {
+        const dir = exportedDirs.get(rel);
+        citations.push(dir ? `- [/${dir}/${rel}.md](/${dir}/${rel}.md)` : `- related entry ${rel}`);
+    }
+    for (const f of e.refs?.files ?? [])
+        citations.push(`- ${f}`);
+    if (e.refs?.commit)
+        citations.push(`- commit ${e.refs.commit}`);
+    if (citations.length > 0)
+        body += `\n# Citations\n${citations.join('\n')}\n`;
+    return `${fm.join('\n')}\n${body}`;
+}
+// log.md — a pure function of the brain's RAW record history (readRecords-level).
+// The materialized LWW view cannot prove an entry was ever publish-grade (a
+// verified→stale restamp shows only `stale`; a tombstoned entry vanishes), so the
+// departure set is: some raw record was publish-grade AND the id is not exported now.
+function deriveLog(eligibleIds, records, live) {
+    const byId = new Map();
+    for (const r of records) {
+        if (!r || typeof r.id !== 'string')
+            continue;
+        const list = byId.get(r.id) ?? [];
+        list.push(r);
+        byId.set(r.id, list);
+    }
+    const liveById = new Map(live.map((e) => [e.id, e]));
+    const successorOf = new Map();
+    for (const e of live)
+        if (e.refs?.supersedes)
+            successorOf.set(e.refs.supersedes, e);
+    const departures = [];
+    for (const [id, recs] of byId) {
+        if (eligibleIds.has(id))
+            continue;
+        // earliest (min-updated) publish-grade record — set-deterministic, no reliance
+        // on file order even across hypothetical record reorderings
+        let grade;
+        for (const r of recs) {
+            if (isTombstone(r))
+                continue;
+            const n = normalizeEntry(r);
+            if (n.ok && recordWasPublishGrade(n.entry) && (!grade || n.entry.updated < grade.updated)) {
+                grade = n.entry;
+            }
+        }
+        if (!grade)
+            continue; // never publish-grade → not a departure
+        const cur = liveById.get(id);
+        let at;
+        let reason;
+        if (!cur) {
+            const tomb = recs.filter(isTombstone).sort((a, b) => b.updated.localeCompare(a.updated))[0];
+            at = tomb?.updated ?? grade.updated;
+            reason = 'deleted (tombstoned)';
+        }
+        else if (successorOf.has(id)) {
+            at = successorOf.get(id).updated;
+            reason = `superseded by ${successorOf.get(id).id}`;
+        }
+        else if (cur.provenance.status !== 'verified') {
+            at = cur.updated;
+            reason = `provenance re-stamped ${cur.provenance.status}`;
+        }
+        else if (cur.zone === 'archive') {
+            at = cur.updated;
+            reason = 'archived';
+        }
+        else if (cur.status === 'deprecated') {
+            at = cur.updated;
+            reason = 'deprecated';
+        }
+        else if (cur.validity.valid_until) {
+            at = cur.validity.valid_until;
+            reason = `validity window closed ${cur.validity.valid_until.slice(0, 10)}`;
+        }
+        else {
+            at = cur.updated;
+            reason = 'no longer eligible';
+        }
+        departures.push({
+            at,
+            id,
+            line: `- ${at.slice(0, 10)} — ${id} [${grade.type}] ${yamlStr(firstSentence(grade.text, 80))} — ${reason}`,
+        });
+    }
+    departures.sort((a, b) => a.at.localeCompare(b.at) || (a.id < b.id ? -1 : 1));
+    return departures.map((d) => d.line);
+}
+export function exportOkf(opts = {}) {
+    const { superseded, asOf, eligible } = projectionInputs();
+    const project = opts.project ?? defaultProject();
+    const dir = opts.out ?? join(process.cwd(), '.okf');
+    prepareTree(dir);
+    const marker = `<!-- ${GENERATED_MARKER} okf; regenerate with \`vfkb export okf\`, do not hand-edit (as-of ${asOf}) -->`;
+    const files = [];
+    const write = (rel, content) => {
+        const p = join(dir, rel);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, content);
+        files.push(rel);
+    };
+    const exportedDirs = new Map(eligible.map((e) => [e.id, TYPE_DIR[e.type]]));
+    const byDir = new Map();
+    for (const e of eligible) {
+        const d = TYPE_DIR[e.type];
+        const list = byDir.get(d) ?? [];
+        list.push(e);
+        byDir.set(d, list);
+    }
+    for (const [d, entries] of [...byDir.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        for (const e of entries)
+            write(`${d}/${e.id}.md`, okfDoc(e, asOf, exportedDirs));
+        const lines = entries.map((e) => `- [${firstSentence(e.text, 80).replace(/\]/g, '\\]')}](/${d}/${e.id}.md)`);
+        write(`${d}/index.md`, `${marker}\n\n# ${d}\n\n${lines.join('\n')}\n`);
+    }
+    const rootLines = [...byDir.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([d, entries]) => `- [${d}/](/${d}/index.md) — ${entries.length} document${entries.length === 1 ? '' : 's'}`);
+    write('index.md', `${marker}\n\n# ${project} — OKF bundle (generated from the vfkb brain, as-of ${asOf})\n\n` +
+        `${rootLines.join('\n') || '(no published entries)'}\n\n` +
+        `See [log.md](/log.md) for entries that have left the published view.\n`);
+    const logLines = deriveLog(new Set(eligible.map((e) => e.id)), readRecords(), readAll());
+    write('log.md', `${marker}\n\n# log — departures from the published view\n\n` +
+        `${logLines.join('\n') || '(none)'}\n`);
+    return { dir, files: files.sort() };
+}
+// CLI dispatch (`vfkb export <target> [--out <path>]`).
+export function runExport(target, opts = {}) {
+    if (target === 'agents-md')
+        return `wrote ${exportAgentsMd(opts).path}`;
+    if (target === 'okf') {
+        const r = exportOkf(opts);
+        return `wrote ${r.files.length} files → ${r.dir}`;
+    }
+    throw new Error('usage: vfkb export <agents-md|okf> [--out <path>]');
+}

package/dist/gating.js

@@ -0,0 +1,34 @@
+// Tool-gating (mykb L10 mitigation / D7c). Block harness file-write tools from
+// editing the brain JSONL directly — all writes MUST go through the engine (sole
+// writer, D4a; keeps the index/freshness invariants and the no-secrets lint).
+// Harness-agnostic: handles Claude Code ('Write'/'Edit'/'MultiEdit') and Pi
+// ('write'/'edit') tool names + their path aliases.
+import { resolve } from 'node:path';
+import { brainDir } from './storage.js';
+const WRITE_TOOLS = new Set([
+    'write',
+    'edit',
+    'multiedit',
+    'notebookedit',
+    'create',
+    'str_replace_editor',
+]);
+function extractPath(input) {
+    if (!input)
+        return undefined;
+    const p = input.file_path ?? input.path ?? input.filePath ?? input.notebook_path;
+    return typeof p === 'string' ? p : undefined;
+}
+// Is this tool call a direct write into the brain directory?
+export function isBrainWrite(toolName, input, brain = brainDir()) {
+    if (!toolName || !WRITE_TOOLS.has(toolName.toLowerCase()))
+        return false;
+    const p = extractPath(input);
+    if (!p)
+        return false;
+    const abs = resolve(p);
+    const root = resolve(brain);
+    return abs === root || abs.startsWith(root + '/');
+}
+export const GATING_REASON = 'vfkb: edit the brain via the engine/CLI/MCP, not by writing files directly ' +
+    '(keeps the index, freshness, and no-secrets invariants).';

package/dist/git.js

@@ -0,0 +1,43 @@
+// Brain git lifecycle (Phase 6). The per-project brain is its own git history;
+// the engine commits it (attributed to the writing role). Pure Node stdlib + the
+// git binary (no library dep).
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { brainDir } from './storage.js';
+function git(args, cwd) {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+}
+function ensureRepo(brain) {
+    if (!existsSync(join(brain, '.git'))) {
+        git(['init', '-q'], brain);
+    }
+}
+// Commit all brain changes. `role` attributes the commit (author.role, D4a).
+// Returns committed:false when there is nothing to commit (idempotent).
+export function save(message = 'vfkb: update', role = 'engine', brain = brainDir()) {
+    ensureRepo(brain);
+    git(['add', '-A'], brain);
+    const status = git(['status', '--porcelain'], brain).trim();
+    if (status.length === 0)
+        return { committed: false, message: 'nothing to commit' };
+    git([
+        '-c',
+        `user.name=vfkb (${role})`,
+        '-c',
+        'user.email=vfkb@vilosource.local',
+        'commit',
+        '-q',
+        '-m',
+        message,
+    ], brain);
+    return { committed: true, message };
+}
+export function saveAndPush(message = 'vfkb: update', role = 'engine', brain = brainDir()) {
+    const r = save(message, role, brain);
+    // Push only if a remote is configured (otherwise a local-only brain).
+    const remotes = git(['remote'], brain).trim();
+    if (remotes.length > 0)
+        git(['push', '-q'], brain);
+    return r;
+}

package/dist/import.js

@@ -0,0 +1,99 @@
+// FR-3 (ADR-0030) — `vfkb import`: bring existing knowledge across so "migrate a
+// project to vfkb" is a real verb, not a clean-slate restart. All imports route
+// through the engine (the write-gate applies) and are stamped role=import (Trust
+// 'import') + an `imported` tag — the mapping is explicitly LOSSY (ADR-0030).
+//
+//   --from-mykb <areaDir|name>  map a mykb area's *.jsonl into vfkb envelopes
+//   --from-adr <dir>            one `link` per ADR markdown file (default docs/adr)
+//   --from-markdown <file>      attach a historical doc as a referenced source
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { addEntry } from './engine.js';
+const MYKB_FILES = {
+    'decisions.jsonl': 'decision',
+    'facts.jsonl': 'fact',
+    'gotchas.jsonl': 'gotcha',
+    'patterns.jsonl': 'pattern',
+    'links.jsonl': 'link',
+};
+function stamp(type, text, tags, verified) {
+    const e = addEntry(type, text, {
+        role: 'import',
+        tags: ['imported', ...tags.filter((t) => t !== 'imported')],
+        provStatus: verified ? 'verified' : 'unverified',
+    });
+    return { id: e.id, type: e.type, text: e.text };
+}
+// mykb envelope -> vfkb text (lossy: area/zone/created/rejected fold or drop).
+function mykbText(type, e) {
+    const parts = [String(e.text ?? '').trim()];
+    if (type === 'decision' && e.why)
+        parts.push(`Why: ${e.why}`);
+    if (type === 'decision' && e.rejected)
+        parts.push(`Rejected: ${e.rejected}`);
+    if (type === 'gotcha' && e.resolution)
+        parts.push(`Resolution: ${e.resolution}`);
+    if (type === 'link' && e.url)
+        return `${parts[0]} → ${e.url}`;
+    return parts.filter(Boolean).join('\n\n');
+}
+export function resolveMykbArea(nameOrDir) {
+    if (existsSync(nameOrDir) && statSync(nameOrDir).isDirectory())
+        return nameOrDir;
+    return join(homedir(), '.mykb', 'areas', nameOrDir);
+}
+export function fromMykb(areaDir) {
+    if (!existsSync(areaDir))
+        throw new Error(`mykb area not found: ${areaDir}`);
+    const out = [];
+    for (const [file, type] of Object.entries(MYKB_FILES)) {
+        const path = join(areaDir, file);
+        if (!existsSync(path))
+            continue;
+        for (const line of readFileSync(path, 'utf8').split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let e;
+            try {
+                e = JSON.parse(trimmed);
+            }
+            catch {
+                continue; // skip a malformed line, don't abort the migration
+            }
+            const text = mykbText(type, e);
+            if (!text)
+                continue;
+            const verified = e?.provenance?.status === 'verified';
+            out.push(stamp(type, text, Array.isArray(e.tags) ? e.tags : [], verified));
+        }
+    }
+    return out;
+}
+function mdTitle(path) {
+    try {
+        const heading = readFileSync(path, 'utf8').split(/\r?\n/).find((l) => l.startsWith('# '));
+        if (heading)
+            return heading.replace(/^#\s+/, '').trim();
+    }
+    catch { }
+    return basename(path, extname(path));
+}
+export function fromAdr(dir = 'docs/adr') {
+    if (!existsSync(dir))
+        throw new Error(`ADR dir not found: ${dir}`);
+    const out = [];
+    for (const file of readdirSync(dir).sort()) {
+        if (extname(file) !== '.md' || /readme/i.test(file))
+            continue;
+        const rel = join(dir, file);
+        out.push(stamp('link', `${mdTitle(rel)} → ${rel}`, ['adr'], false));
+    }
+    return out;
+}
+export function fromMarkdown(file) {
+    if (!existsSync(file))
+        throw new Error(`markdown file not found: ${file}`);
+    return [stamp('link', `${mdTitle(file)} → ${file}`, ['doc'], false)];
+}

package/dist/import.test.js

@@ -0,0 +1,54 @@
+// FR-3 (ADR-0030) inner gate — `vfkb import` maps mykb / ADRs / markdown into vfkb
+// envelopes through the engine (role=import, lossy), skipping malformed input.
+import { describe, it, expect, beforeEach } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fromMykb, fromAdr, fromMarkdown } from './import.js';
+import { readAll } from './engine.js';
+beforeEach(() => {
+    process.env.VFKB_DIR = mkdtempSync(join(tmpdir(), 'vfkb-import-'));
+});
+const jl = (...objs) => objs.map((o) => JSON.stringify(o)).join('\n') + '\n';
+describe('vfkb import (FR-3)', () => {
+    it('maps a mykb area into vfkb envelopes (lossy), folding why/resolution/url', () => {
+        const area = mkdtempSync(join(tmpdir(), 'mykb-area-'));
+        writeFileSync(join(area, 'decisions.jsonl'), jl({ type: 'decision', text: 'D1', tags: ['arch'], why: 'because', provenance: { status: 'verified' } }));
+        writeFileSync(join(area, 'gotchas.jsonl'), jl({ type: 'gotcha', text: 'G1', resolution: 'fixed it' }));
+        writeFileSync(join(area, 'links.jsonl'), jl({ type: 'link', text: 'L1', url: 'https://x/y' }));
+        writeFileSync(join(area, 'facts.jsonl'), 'not json\n' + jl({ type: 'fact', text: 'F1' }));
+        const res = fromMykb(area);
+        expect(res.length).toBe(4); // the malformed line is skipped
+        const all = readAll();
+        const decision = all.find((e) => e.type === 'decision');
+        expect(decision.text).toContain('D1');
+        expect(decision.text).toContain('Why: because');
+        expect(decision.author.role).toBe('import');
+        expect(decision.tags).toContain('imported');
+        expect(decision.provenance.status).toBe('verified'); // mykb verified preserved
+        expect(all.find((e) => e.type === 'gotcha').text).toContain('Resolution: fixed it');
+        expect(all.find((e) => e.type === 'link').text).toBe('L1 → https://x/y');
+        expect(all.find((e) => e.type === 'fact').provenance.status).toBe('unverified');
+    });
+    it('from-adr creates one link per ADR markdown, skipping README', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'adr-'));
+        writeFileSync(join(dir, 'ADR-0001-foo.md'), '# ADR-0001: Foo decision\n\nbody');
+        writeFileSync(join(dir, 'ADR-0002-bar.md'), '# ADR-0002: Bar decision\n');
+        writeFileSync(join(dir, 'README.md'), '# index');
+        const res = fromAdr(dir);
+        expect(res.length).toBe(2);
+        const all = readAll();
+        expect(all.every((e) => e.type === 'link' && e.author.role === 'import')).toBe(true);
+        expect(all.find((e) => e.text.includes('Foo decision')).text).toContain('ADR-0001-foo.md');
+    });
+    it('from-markdown attaches a single referenced source', () => {
+        const f = join(mkdtempSync(join(tmpdir(), 'md-')), 'NOTES.md');
+        writeFileSync(f, '# Historical notes\n\nstuff');
+        const res = fromMarkdown(f);
+        expect(res.length).toBe(1);
+        expect(readAll()[0].text).toBe(`Historical notes → ${f}`);
+    });
+    it('throws a clear error on a missing source', () => {
+        expect(() => fromAdr('/no/such/dir')).toThrow(/ADR dir not found/);
+    });
+});