@copperbox/why 1.0.0

package/dist/find-symbol.js

@@ -0,0 +1,267 @@
+// Symbol resolver (DESIGN.md §4, resolution order step 1).
+//
+// findSymbol re-evaluates the claim "this concept is about the symbol
+// `symbol`, last seen in `path` at commit `as_of`" against HEAD:
+//
+//   - The same file still declares the symbol exactly once → its current span.
+//   - The symbol is gone from that file (or the file is gone) → search files
+//     that git history *connects* to the original path (rename/copy detection
+//     via `git log --follow -M -C` over as_of..HEAD). A same-named symbol in
+//     a file git does not connect is NOT followed — the never-silently-wrong
+//     invariant beats recall, so the result is not-found instead.
+//   - More than one declaration in the deciding file, or more than one
+//     connected file declaring the symbol → ambiguous, never a guess.
+//
+// Parsing: tree-sitter via WASM (web-tree-sitter + the prebuilt grammars in
+// tree-sitter-wasms, both installed through package.json — nothing is fetched
+// at run time) for TypeScript/TSX/JavaScript, Rust, Python and Go, matching
+// declaration nodes by their `name` field. Any other extension falls back to
+// a line-regex heuristic over common declaration keywords (function / fn /
+// def / class / func). Heuristic results carry confidence: "heuristic" and
+// span only the declaration line itself — the heuristic can locate a
+// declaration but must never fabricate its extent. Tree-sitter results carry
+// confidence: "syntactic" and the full declaration node's span.
+import { createRequire } from "node:module";
+import { dirname, extname, join } from "node:path";
+import Parser from "web-tree-sitter";
+import { git, gitOrThrow, resolveAsOfCommit, showFile } from "./git.js";
+// --- tree-sitter setup -------------------------------------------------------
+const GRAMMAR_BY_EXTENSION = {
+    ".ts": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".jsx": "javascript",
+    ".rs": "rust",
+    ".py": "python",
+    ".pyi": "python",
+    ".go": "go",
+};
+const NAME = { nameField: "name" };
+const MODULE_VAR = { nameField: "name", spanIsParent: true, moduleScopeOnly: true };
+const DECL_RULES = {
+    typescript: {
+        function_declaration: NAME,
+        generator_function_declaration: NAME,
+        function_signature: NAME,
+        class_declaration: NAME,
+        abstract_class_declaration: NAME,
+        interface_declaration: NAME,
+        type_alias_declaration: NAME,
+        enum_declaration: NAME,
+        method_definition: NAME,
+        method_signature: NAME,
+        abstract_method_signature: NAME,
+        public_field_definition: NAME,
+        variable_declarator: MODULE_VAR,
+    },
+    javascript: {
+        function_declaration: NAME,
+        generator_function_declaration: NAME,
+        class_declaration: NAME,
+        method_definition: NAME,
+        field_definition: { nameField: "property" },
+        variable_declarator: MODULE_VAR,
+    },
+    rust: {
+        function_item: NAME,
+        function_signature_item: NAME,
+        struct_item: NAME,
+        enum_item: NAME,
+        union_item: NAME,
+        trait_item: NAME,
+        type_item: NAME,
+        mod_item: NAME,
+        const_item: NAME,
+        static_item: NAME,
+        macro_definition: NAME,
+    },
+    python: {
+        function_definition: NAME,
+        class_definition: NAME,
+        assignment: { nameField: "left", nameTypes: ["identifier"], moduleScopeOnly: true },
+    },
+    go: {
+        function_declaration: NAME,
+        method_declaration: NAME,
+        type_spec: NAME,
+        const_spec: NAME,
+        var_spec: NAME,
+    },
+};
+DECL_RULES.tsx = DECL_RULES.typescript;
+let parserReady;
+let sharedParser;
+const loadedLanguages = new Map();
+function loadLanguage(grammar) {
+    let language = loadedLanguages.get(grammar);
+    if (language === undefined) {
+        language = (async () => {
+            parserReady ??= Parser.init();
+            await parserReady;
+            const require = createRequire(import.meta.url);
+            const wasmDir = join(dirname(require.resolve("tree-sitter-wasms/package.json")), "out");
+            return Parser.Language.load(join(wasmDir, `tree-sitter-${grammar}.wasm`));
+        })();
+        loadedLanguages.set(grammar, language);
+    }
+    return language;
+}
+function nodeSpan(node) {
+    const start = node.startPosition.row + 1;
+    // Tree-sitter end positions are exclusive: ending at column 0 means the
+    // node really ends with the previous line's newline.
+    const end = node.endPosition.column === 0 ? node.endPosition.row : node.endPosition.row + 1;
+    return { start, end: Math.max(start, end) };
+}
+// Wrappers a module-scope declaration may sit inside without leaving module
+// scope; anything else on the way up (function bodies, blocks) means local.
+const SCOPE_WRAPPERS = new Set([
+    "export_statement",
+    "expression_statement",
+    "lexical_declaration",
+    "variable_declaration",
+]);
+const MODULE_ROOTS = new Set(["program", "module", "source_file"]);
+function atModuleScope(node) {
+    let cur = node.parent;
+    while (cur !== null && SCOPE_WRAPPERS.has(cur.type))
+        cur = cur.parent;
+    return cur !== null && MODULE_ROOTS.has(cur.type);
+}
+function collectDeclarations(root, rules, symbol) {
+    const matches = [];
+    const walk = (node) => {
+        const rule = rules[node.type];
+        if (rule !== undefined) {
+            const names = node
+                .childrenForFieldName(rule.nameField)
+                .filter((n) => rule.nameTypes === undefined || rule.nameTypes.includes(n.type));
+            if (names.some((n) => n.text === symbol) &&
+                (rule.moduleScopeOnly !== true || atModuleScope(node))) {
+                const spanNode = rule.spanIsParent === true && node.parent !== null ? node.parent : node;
+                matches.push(nodeSpan(spanNode));
+            }
+        }
+        for (const child of node.namedChildren)
+            walk(child);
+    };
+    walk(root);
+    return matches;
+}
+async function syntacticMatches(grammar, content, symbol) {
+    const language = await loadLanguage(grammar);
+    sharedParser ??= new Parser();
+    sharedParser.setLanguage(language);
+    const tree = sharedParser.parse(content);
+    try {
+        return collectDeclarations(tree.rootNode, DECL_RULES[grammar], symbol);
+    }
+    finally {
+        tree.delete();
+    }
+}
+// --- regex-heuristic fallback ------------------------------------------------
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function heuristicMatches(content, symbol) {
+    const sym = escapeRegExp(symbol);
+    const patterns = [
+        new RegExp(`(?:^|[^\\w.])function\\*?\\s+${sym}\\s*[(<]`),
+        new RegExp(`(?:^|[^\\w.])fn\\s+${sym}\\s*[(<]`),
+        new RegExp(`(?:^|[^\\w.])def\\s+${sym}\\s*\\(`),
+        new RegExp(`(?:^|[^\\w.])class\\s+${sym}(?:$|[^\\w])`),
+        new RegExp(`^\\s*func\\s+(?:\\([^)]*\\)\\s*)?${sym}\\s*\\(`),
+    ];
+    const matches = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        if (patterns.some((p) => p.test(lines[i]))) {
+            matches.push({ start: i + 1, end: i + 1 });
+        }
+    }
+    return matches;
+}
+/** Declarations of `symbol` in `path` at HEAD, or null if the path is absent. */
+async function matchesInFile(repo, path, symbol) {
+    const content = showFile(repo, "HEAD", path);
+    if (content === null)
+        return null;
+    const grammar = GRAMMAR_BY_EXTENSION[extname(path).toLowerCase()];
+    if (grammar !== undefined) {
+        return { matches: await syntacticMatches(grammar, content, symbol), confidence: "syntactic" };
+    }
+    return { matches: heuristicMatches(content, symbol), confidence: "heuristic" };
+}
+/** Files at HEAD whose content mentions `symbol` at all (textual pre-filter). */
+function grepCandidates(repo, symbol) {
+    const r = git(repo, ["grep", "-l", "--fixed-strings", "-e", symbol, "HEAD"]);
+    if (r.status === 1)
+        return [];
+    if (r.status !== 0)
+        throw new Error(`git grep failed: ${r.stderr.trim()}`);
+    return r.stdout
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => line.replace(/^HEAD:/, ""));
+}
+/**
+ * True when git history connects `candidate` (a path at HEAD) to the anchor's
+ * original path within as_of..HEAD: the original name appears in the
+ * candidate's `git log --follow -M -C --name-status` output for that window
+ * (as the old side of a rename/copy, or as the candidate's own earlier name).
+ */
+function connectedByHistory(repo, asOfSha, originalPath, candidate) {
+    const out = gitOrThrow(repo, [
+        "log",
+        "--follow",
+        "-M",
+        "-C",
+        "--name-status",
+        "--format=%H",
+        `${asOfSha}..HEAD`,
+        "--",
+        candidate,
+    ]);
+    for (const line of out.split("\n")) {
+        const fields = line.split("\t");
+        if (fields.length >= 2 && fields.slice(1).includes(originalPath))
+            return true;
+    }
+    return false;
+}
+export async function findSymbol(repo, anchor) {
+    const { path, symbol, asOf } = anchor;
+    if (symbol.trim() === "") {
+        throw new Error("symbol must be non-empty");
+    }
+    const asOfSha = resolveAsOfCommit(repo, asOf);
+    // Step 1: the anchored file itself, at HEAD.
+    const sameFile = await matchesInFile(repo, path, symbol);
+    if (sameFile !== null && sameFile.matches.length > 0) {
+        if (sameFile.matches.length > 1)
+            return { found: false, reason: "ambiguous" };
+        return { found: true, path, lines: sameFile.matches[0], confidence: sameFile.confidence };
+    }
+    // Step 2: only files git history connects to the original path.
+    const hits = [];
+    for (const candidate of grepCandidates(repo, symbol)) {
+        if (candidate === path)
+            continue;
+        const m = await matchesInFile(repo, candidate, symbol);
+        if (m === null || m.matches.length === 0)
+            continue;
+        if (!connectedByHistory(repo, asOfSha, path, candidate))
+            continue;
+        hits.push({ path: candidate, ...m });
+    }
+    if (hits.length === 0)
+        return { found: false, reason: "not-found" };
+    if (hits.length > 1 || hits[0].matches.length > 1)
+        return { found: false, reason: "ambiguous" };
+    return { found: true, path: hits[0].path, lines: hits[0].matches[0], confidence: hits[0].confidence };
+}

package/dist/git.d.ts

@@ -0,0 +1,17 @@
+export interface GitResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function git(repo: string, args: string[]): GitResult;
+export declare function gitOrThrow(repo: string, args: string[]): string;
+/**
+ * Resolve an anchor's `as_of` to a full commit sha. Both resolvers share the
+ * same precondition: the claim is only traceable forward if `as_of` is an
+ * ancestor of HEAD.
+ */
+export declare function resolveAsOfCommit(repo: string, asOf: string): string;
+/** Raw file content at rev, or null if the path is absent. */
+export declare function showFile(repo: string, rev: string, path: string): string | null;
+/** File content at rev as an array of lines, or null if the path is absent. */
+export declare function showLines(repo: string, rev: string, path: string): string[] | null;

package/dist/git.js

@@ -0,0 +1,51 @@
+// Thin wrappers over read-only git plumbing, shared by the anchor resolvers
+// (trace-range, find-symbol). Nothing here mutates a repository.
+import { spawnSync } from "node:child_process";
+export function git(repo, args) {
+    const r = spawnSync("git", ["-C", repo, "-c", "core.quotePath=false", ...args], {
+        encoding: "utf8",
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    if (r.error) {
+        throw new Error(`failed to run git ${args[0]}: ${r.error.message}`);
+    }
+    return { status: r.status ?? 1, stdout: r.stdout, stderr: r.stderr };
+}
+export function gitOrThrow(repo, args) {
+    const r = git(repo, args);
+    if (r.status !== 0) {
+        throw new Error(`git ${args.join(" ")} failed: ${r.stderr.trim()}`);
+    }
+    return r.stdout;
+}
+/**
+ * Resolve an anchor's `as_of` to a full commit sha. Both resolvers share the
+ * same precondition: the claim is only traceable forward if `as_of` is an
+ * ancestor of HEAD.
+ */
+export function resolveAsOfCommit(repo, asOf) {
+    const rev = git(repo, ["rev-parse", "--verify", "--quiet", `${asOf}^{commit}`]);
+    if (rev.status !== 0) {
+        throw new Error(`as_of "${asOf}" does not resolve to a commit in ${repo}`);
+    }
+    const sha = rev.stdout.trim();
+    if (git(repo, ["merge-base", "--is-ancestor", sha, "HEAD"]).status !== 0) {
+        throw new Error(`as_of ${asOf} is not an ancestor of HEAD; cannot resolve forward from it`);
+    }
+    return sha;
+}
+/** Raw file content at rev, or null if the path is absent. */
+export function showFile(repo, rev, path) {
+    const r = git(repo, ["show", `${rev}:${path}`]);
+    return r.status === 0 ? r.stdout : null;
+}
+/** File content at rev as an array of lines, or null if the path is absent. */
+export function showLines(repo, rev, path) {
+    const content = showFile(repo, rev, path);
+    if (content === null)
+        return null;
+    const lines = content.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}

package/dist/init.d.ts

@@ -0,0 +1,24 @@
+/** An init step that must stop the command cleanly (exit 1), not crash. */
+export declare class InitError extends Error {
+}
+/** One directory per concept type (DESIGN.md §1). */
+export declare const TYPE_DIRECTORIES: string[];
+export declare const SNIPPET_BEGIN = "<!-- why:begin -->";
+export declare const SNIPPET_END = "<!-- why:end -->";
+/** Root of the git repo enclosing `cwd`; the bundle always lives at its top. */
+export declare function findRepoRoot(cwd: string): string;
+/**
+ * Create `.why/` with the five type directories, a curated root index, and a
+ * log seeded with an init entry. Refuses to touch an existing `.why/` — an
+ * archive is history, so there is deliberately no --force.
+ */
+export declare function scaffoldBundle(repoRoot: string): Promise<string>;
+/** The knowledge-capture block dropped into CLAUDE.md (DESIGN.md §8). */
+export declare function captureSnippet(repoName: string): string;
+/**
+ * Write the capture snippet into the repo's CLAUDE.md, idempotently: create
+ * the file, append the block, or replace whatever sits between the existing
+ * markers. Unbalanced markers are refused — rewriting around them could
+ * silently mangle a hand-edited file.
+ */
+export declare function writeCaptureSnippet(repoRoot: string): Promise<"created" | "appended" | "replaced">;

package/dist/init.js

@@ -0,0 +1,100 @@
+// `why init`: scaffold a fresh `.why/` bundle at the repo root (DESIGN.md §1,
+// §8). Everything written here must load through okf-mcp with zero validation
+// problems — the bundle is plain OKF from its very first byte.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { appendLogEntry, OKF_VERSION, serializeDocument } from "@copperbox/okf-mcp";
+import { CONCEPT_TYPES } from "./bundle.js";
+import { BUNDLE_DIRNAME } from "./discover.js";
+/** An init step that must stop the command cleanly (exit 1), not crash. */
+export class InitError extends Error {
+}
+/** One directory per concept type (DESIGN.md §1). */
+export const TYPE_DIRECTORIES = CONCEPT_TYPES.map((type) => `${type}s`);
+export const SNIPPET_BEGIN = "<!-- why:begin -->";
+export const SNIPPET_END = "<!-- why:end -->";
+/** Root of the git repo enclosing `cwd`; the bundle always lives at its top. */
+export function findRepoRoot(cwd) {
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd,
+        encoding: "utf8",
+    });
+    const root = result.status === 0 ? result.stdout.trim() : "";
+    if (root === "") {
+        throw new InitError(`why init: ${cwd} is not inside a git repository — init scaffolds ${BUNDLE_DIRNAME}/ at the repo root`);
+    }
+    return root;
+}
+/**
+ * Create `.why/` with the five type directories, a curated root index, and a
+ * log seeded with an init entry. Refuses to touch an existing `.why/` — an
+ * archive is history, so there is deliberately no --force.
+ */
+export async function scaffoldBundle(repoRoot) {
+    const root = join(repoRoot, BUNDLE_DIRNAME);
+    if (existsSync(root)) {
+        throw new InitError(`why init: ${root} already exists — refusing to touch an existing archive. ` +
+            "There is no --force; if you truly want to start over, remove the directory yourself.");
+    }
+    for (const dir of TYPE_DIRECTORIES) {
+        await mkdir(join(root, dir), { recursive: true });
+    }
+    const name = basename(repoRoot);
+    const index = serializeDocument({
+        okf_version: OKF_VERSION,
+        generated: false,
+        description: `Decision archive for ${name} — the recovered why behind its code.`,
+    }, `# ${name} — decision archive\n`);
+    await writeFile(join(root, "index.md"), index, "utf8");
+    await appendLogEntry(root, `why init: scaffolded the empty bundle (${TYPE_DIRECTORIES.join(", ")})`);
+    return root;
+}
+/** The knowledge-capture block dropped into CLAUDE.md (DESIGN.md §8). */
+export function captureSnippet(repoName) {
+    return [
+        SNIPPET_BEGIN,
+        "## Decision archive (`.why/`)",
+        "",
+        "This repo keeps the *why* behind its code in `.why/`, an OKF bundle of",
+        "decisions, constraints, attempts, incidents, and open questions.",
+        "",
+        "- Before non-trivial work, consult the archive for the decisions and",
+        "  constraints shaping the code you are about to change (mount it:",
+        `  \`npx -y @copperbox/okf-mcp --bundle ${repoName}=.why --writable\`).`,
+        "- After making a durable decision — choosing an approach, ruling one out,",
+        "  hitting a constraint — record it in `.why/` while the context is fresh.",
+        SNIPPET_END,
+    ].join("\n");
+}
+/**
+ * Write the capture snippet into the repo's CLAUDE.md, idempotently: create
+ * the file, append the block, or replace whatever sits between the existing
+ * markers. Unbalanced markers are refused — rewriting around them could
+ * silently mangle a hand-edited file.
+ */
+export async function writeCaptureSnippet(repoRoot) {
+    const path = join(repoRoot, "CLAUDE.md");
+    const block = captureSnippet(basename(repoRoot));
+    let existing;
+    try {
+        existing = await readFile(path, "utf8");
+    }
+    catch {
+        await writeFile(path, `${block}\n`, "utf8");
+        return "created";
+    }
+    const begin = existing.indexOf(SNIPPET_BEGIN);
+    const end = existing.indexOf(SNIPPET_END);
+    if (begin !== -1 && end !== -1 && end >= begin) {
+        const updated = existing.slice(0, begin) + block + existing.slice(end + SNIPPET_END.length);
+        await writeFile(path, updated, "utf8");
+        return "replaced";
+    }
+    if (begin !== -1 || end !== -1) {
+        throw new InitError(`why init: ${path} has an unbalanced ${SNIPPET_BEGIN}/${SNIPPET_END} marker pair — fix it by hand before re-running --capture-snippet`);
+    }
+    await writeFile(path, `${existing.trimEnd()}\n\n${block}\n`, "utf8");
+    return "appended";
+}

package/dist/lint.d.ts

@@ -0,0 +1,40 @@
+import { type WhyBundle } from "./bundle.js";
+export type Severity = "error" | "warning";
+export interface Finding {
+    /** Stable rule id, `W###`. */
+    rule: RuleId;
+    severity: Severity;
+    /** Bundle-relative file path; `(bundle)` for bundle-level OKF findings. */
+    file: string;
+    message: string;
+}
+/**
+ * Every rule this linter can report. W0xx: okf-mcp pass-through; W1xx: `why:`
+ * field validity (§2 vocab tables); W2xx: required sections; W3xx: edge-section
+ * link targets; W4xx: status/section consistency (§3).
+ */
+export declare const RULES: {
+    readonly W001: "OKF conformance finding (okf-mcp validateBundle, passed through)";
+    readonly W100: "malformed `why:` value";
+    readonly W101: "unknown status for the concept's type";
+    readonly W102: "unknown confidence";
+    readonly W103: "malformed anchors entry";
+    readonly W104: "malformed verify block";
+    readonly W105: "unrecognized `why:` key";
+    readonly W106: "`why:` field not applicable to the concept's type";
+    readonly W200: "decision missing its `# Why` section";
+    readonly W201: "confidence inferred/speculative without a `# Citations` section";
+    readonly W202: "constraint missing its `# Still true?` section";
+    readonly W300: "`# Because of` link target must be a constraint/incident/attempt/decision";
+    readonly W301: "`# Instead of` link target must be an attempt";
+    readonly W302: "`# Superseded by` link target must be a decision";
+    readonly W303: "`# Led to` link target must be a decision/incident";
+    readonly W400: "status superseded without a `# Superseded by` section with a link";
+    readonly W401: "`# Superseded by` section without status superseded";
+    readonly W402: "expired constraint missing expired_on";
+};
+export type RuleId = keyof typeof RULES;
+/** Lint one loaded bundle; deterministic order (file, rule, message). */
+export declare function lintBundle(bundle: WhyBundle): Promise<Finding[]>;
+/** Human-readable findings, grouped by file; a clean line when there are none. */
+export declare function renderFindings(bundle: WhyBundle, findings: Finding[]): string[];

package/dist/lint.js

@@ -0,0 +1,161 @@
+// `why lint` (DESIGN.md §3): the why-schema layer above OKF conformance.
+// OKF conformance itself is okf-mcp's job — its validateBundle findings pass
+// through unmodified under the single rule id W001 — while the W1xx–W4xx
+// rules enforce the `why:` vocab tables (§2), required sections, edge-target
+// types, and status/section consistency (§3).
+import { validateBundle } from "@copperbox/okf-mcp";
+import { CONCEPT_TYPES, isOneOf, STATUS_VOCAB, } from "./bundle.js";
+/**
+ * Every rule this linter can report. W0xx: okf-mcp pass-through; W1xx: `why:`
+ * field validity (§2 vocab tables); W2xx: required sections; W3xx: edge-section
+ * link targets; W4xx: status/section consistency (§3).
+ */
+export const RULES = {
+    W001: "OKF conformance finding (okf-mcp validateBundle, passed through)",
+    W100: "malformed `why:` value",
+    W101: "unknown status for the concept's type",
+    W102: "unknown confidence",
+    W103: "malformed anchors entry",
+    W104: "malformed verify block",
+    W105: "unrecognized `why:` key",
+    W106: "`why:` field not applicable to the concept's type",
+    W200: "decision missing its `# Why` section",
+    W201: "confidence inferred/speculative without a `# Citations` section",
+    W202: "constraint missing its `# Still true?` section",
+    W300: "`# Because of` link target must be a constraint/incident/attempt/decision",
+    W301: "`# Instead of` link target must be an attempt",
+    W302: "`# Superseded by` link target must be a decision",
+    W303: "`# Led to` link target must be a decision/incident",
+    W400: "status superseded without a `# Superseded by` section with a link",
+    W401: "`# Superseded by` section without status superseded",
+    W402: "expired constraint missing expired_on",
+};
+/** Which W1xx rule a load-time `why:` diagnostic belongs to, by field. */
+const FIELD_RULES = {
+    status: "W101",
+    confidence: "W102",
+    anchors: "W103",
+    verify: "W104",
+    happened_on: "W100",
+    expired_on: "W100",
+};
+function ruleForDiagnostic(field) {
+    const segment = /^why\.([a-z_]+)/.exec(field)?.[1];
+    if (segment === undefined)
+        return "W100"; // `why` itself is not a map
+    return FIELD_RULES[segment] ?? "W105"; // any other segment is an unrecognized key
+}
+/** Allowed link-target types per edge section (DESIGN.md §3 table). */
+const EDGE_TARGETS = {
+    "because of": { rule: "W300", allowed: ["constraint", "incident", "attempt", "decision"] },
+    "instead of": { rule: "W301", allowed: ["attempt"] },
+    "superseded by": { rule: "W302", allowed: ["decision"] },
+    "led to": { rule: "W303", allowed: ["decision", "incident"] },
+};
+function hasSection(concept, heading) {
+    return concept.sections.some((s) => s.heading.toLowerCase() === heading);
+}
+function lintConcept(bundle, concept, push) {
+    const type = concept.frontmatter.type;
+    const why = concept.why;
+    // W106 — the §2 field table scopes some fields to one concept type.
+    if (why.verify !== undefined && type !== "constraint") {
+        push("W106", "warning", `why.verify: only a constraint carries a verify block, not a ${type} (DESIGN.md §2)`);
+    }
+    if (why.expired_on !== undefined && type !== "constraint") {
+        push("W106", "warning", `why.expired_on: only a constraint expires, not a ${type} (DESIGN.md §2)`);
+    }
+    if (why.confidence !== undefined && type === "question") {
+        push("W106", "warning", "why.confidence: a question is the uncertainty — it carries no confidence (DESIGN.md §2)");
+    }
+    // W2xx — required sections (§3).
+    if (type === "decision" && !hasSection(concept, "why")) {
+        push("W200", "error", 'every decision needs a "# Why" section — the narrative is the point');
+    }
+    if ((why.confidence === "inferred" || why.confidence === "speculative") &&
+        !hasSection(concept, "citations")) {
+        push("W201", "error", `confidence "${why.confidence}" requires a "# Citations" section backing the claim`);
+    }
+    if (type === "constraint" && !hasSection(concept, "still true?")) {
+        push("W202", "error", 'every constraint needs a "# Still true?" section — a constraint must be falsifiable');
+    }
+    // W3xx — links in edge sections must target the types the §3 table allows.
+    // Unresolved links are okf-mcp's broken-link findings, passed through as W001.
+    for (const link of concept.links) {
+        const edge = link.section === undefined ? undefined : EDGE_TARGETS[link.section.toLowerCase()];
+        if (edge === undefined || link.resolvedId === undefined)
+            continue;
+        const targetType = bundle.concepts.get(link.resolvedId)?.frontmatter.type;
+        if (targetType !== undefined && !isOneOf(edge.allowed, targetType)) {
+            push(edge.rule, "error", `"# ${link.section}" links to ${link.target}, a ${targetType} — allowed targets: ${edge.allowed.join(", ")}`);
+        }
+    }
+    // W4xx — status ⇔ section consistency.
+    const supersededLinks = concept.links.filter((l) => l.section?.toLowerCase() === "superseded by");
+    if (why.status === "superseded" && supersededLinks.length === 0) {
+        push("W400", "error", 'status "superseded" requires a "# Superseded by" section with at least one link to the successor');
+    }
+    // The reverse direction only where the type's vocab admits "superseded" —
+    // the §3 table allows the section on constraints, whose vocab does not.
+    const vocab = isOneOf(CONCEPT_TYPES, type) ? STATUS_VOCAB[type] : undefined;
+    if (supersededLinks.length > 0 && why.status !== "superseded" && vocab !== undefined && vocab.includes("superseded")) {
+        const actual = why.status === undefined ? "unset" : `"${why.status}"`;
+        push("W401", "error", `a "# Superseded by" section requires status "superseded" (status is ${actual})`);
+    }
+    if (type === "constraint" && why.status === "expired" && why.expired_on === undefined) {
+        push("W402", "error", 'status "expired" requires an expired_on date (DESIGN.md §2)');
+    }
+}
+/** Lint one loaded bundle; deterministic order (file, rule, message). */
+export async function lintBundle(bundle) {
+    const findings = [];
+    // OKF-level conformance is delegated wholesale; validateBundle's report
+    // already includes the load-time problems.
+    const okf = await validateBundle(bundle.okf);
+    for (const problem of [...okf.errors, ...okf.warnings]) {
+        findings.push({
+            rule: "W001",
+            severity: problem.severity,
+            file: problem.path ?? "(bundle)",
+            message: problem.message,
+        });
+    }
+    // `why:` field validity was already checked at load time (bundle.ts) —
+    // map each diagnostic to its stable rule id.
+    for (const diag of bundle.diagnostics) {
+        const rule = ruleForDiagnostic(diag.field);
+        findings.push({
+            rule,
+            severity: rule === "W105" ? "warning" : "error",
+            file: diag.path,
+            message: `${diag.field}: ${diag.message}`,
+        });
+    }
+    for (const concept of bundle.concepts.values()) {
+        lintConcept(bundle, concept, (rule, severity, message) => findings.push({ rule, severity, file: concept.path, message }));
+    }
+    return findings.sort((a, b) => a.file.localeCompare(b.file) || a.rule.localeCompare(b.rule) || a.message.localeCompare(b.message));
+}
+function count(n, word) {
+    return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+/** Human-readable findings, grouped by file; a clean line when there are none. */
+export function renderFindings(bundle, findings) {
+    if (findings.length === 0) {
+        return [`${bundle.root}: ${count(bundle.concepts.size, "concept")}, no findings`];
+    }
+    const lines = [];
+    let currentFile;
+    for (const finding of findings) {
+        if (finding.file !== currentFile) {
+            if (currentFile !== undefined)
+                lines.push("");
+            lines.push(finding.file);
+            currentFile = finding.file;
+        }
+        lines.push(`  ${finding.severity.padEnd(7)} ${finding.rule}  ${finding.message}`);
+    }
+    const errors = findings.filter((f) => f.severity === "error").length;
+    lines.push("", `${count(findings.length, "finding")} (${count(errors, "error")}, ${count(findings.length - errors, "warning")})`);
+    return lines;
+}

package/dist/serve-assets.d.ts

@@ -0,0 +1,10 @@
+/** The UI could not be bundled — operational, not a bug in the bundle. */
+export declare class AssetError extends Error {
+}
+export interface UiAssets {
+    html: string;
+    js: string;
+    css: string;
+}
+/** Bundle ui/ into self-contained in-memory assets. */
+export declare function buildUiAssets(): Promise<UiAssets>;