akm-cli 0.6.1 → 0.7.0-rc1

package/dist/tests/contracts/reflect-propose-envelope.test.js

@@ -0,0 +1,139 @@
+/**
+ * Envelope-shape contract tests for `akm reflect` and `akm propose` (#226).
+ *
+ * Locks the structural shape of the success and failure envelopes so a
+ * future refactor cannot silently rename or drop a field. The producer-shape
+ * functions in `src/output/shapes.ts` are the production rendering path —
+ * we exercise them with realistic command result objects.
+ *
+ * Backfill for issue #284 GAP-MED 2.
+ */
+import { describe, expect, test } from "bun:test";
+import { shapeProposalProducerOutput } from "../../src/output/shapes";
+const proposal = {
+    id: "uuid-1",
+    ref: "lesson:rg-over-grep",
+    status: "pending",
+    source: "reflect",
+    sourceRun: "run-7",
+    createdAt: "2026-04-27T00:00:00Z",
+    updatedAt: "2026-04-27T00:00:00Z",
+    payload: { content: "BODY" },
+};
+describe("reflect/propose success envelope contract", () => {
+    test("normal: required fields present", () => {
+        const result = {
+            schemaVersion: 1,
+            ok: true,
+            ref: "lesson:rg-over-grep",
+            agentProfile: "claude",
+            durationMs: 12,
+            proposal,
+        };
+        const out = shapeProposalProducerOutput(result, "normal");
+        expect(out.ok).toBe(true);
+        expect(out.ref).toBe("lesson:rg-over-grep");
+        expect(out.agentProfile).toBe("claude");
+        expect(out.durationMs).toBe(12);
+        expect(out).toHaveProperty("proposal");
+        // schemaVersion only at full
+        expect(out).not.toHaveProperty("schemaVersion");
+    });
+    test("full: success envelope adds schemaVersion", () => {
+        const result = {
+            schemaVersion: 1,
+            ok: true,
+            ref: "lesson:rg-over-grep",
+            agentProfile: "claude",
+            durationMs: 12,
+            proposal,
+        };
+        const out = shapeProposalProducerOutput(result, "full");
+        expect(out.schemaVersion).toBe(1);
+    });
+    test("brief: shaped proposal still includes id+ref+status (via brief→normal upgrade)", () => {
+        const result = { schemaVersion: 1, ok: true, ref: "lesson:rg-over-grep", proposal };
+        const out = shapeProposalProducerOutput(result, "brief");
+        const p = out.proposal;
+        expect(p.id).toBe("uuid-1");
+        expect(p.ref).toBe("lesson:rg-over-grep");
+        expect(p.status).toBe("pending");
+    });
+});
+describe("reflect/propose failure envelope contract", () => {
+    test("non_zero_exit: required failure fields present", () => {
+        const failure = {
+            schemaVersion: 1,
+            ok: false,
+            reason: "non_zero_exit",
+            error: "exited with code 7",
+            ref: "lesson:rg-over-grep",
+            exitCode: 7,
+            stdout: "out",
+            stderr: "err",
+        };
+        const out = shapeProposalProducerOutput(failure, "normal");
+        expect(out.ok).toBe(false);
+        expect(out.reason).toBe("non_zero_exit");
+        expect(out.error).toBe("exited with code 7");
+        expect(out.ref).toBe("lesson:rg-over-grep");
+        expect(out.exitCode).toBe(7);
+        // stdio only at full
+        expect(out).not.toHaveProperty("stdout");
+        expect(out).not.toHaveProperty("stderr");
+    });
+    test("spawn_failed: exitCode null is preserved", () => {
+        const failure = {
+            schemaVersion: 1,
+            ok: false,
+            reason: "spawn_failed",
+            error: "ENOENT: command not found",
+            exitCode: null,
+        };
+        const out = shapeProposalProducerOutput(failure, "normal");
+        expect(out.ok).toBe(false);
+        expect(out.reason).toBe("spawn_failed");
+        expect(out.exitCode).toBeNull();
+    });
+    test("parse_error: ref optional", () => {
+        const failure = {
+            schemaVersion: 1,
+            ok: false,
+            reason: "parse_error",
+            error: "agent stdout was not valid JSON",
+            exitCode: 0,
+        };
+        const out = shapeProposalProducerOutput(failure, "normal");
+        expect(out.reason).toBe("parse_error");
+        expect(out).not.toHaveProperty("ref");
+    });
+    test("timeout: timeout reason discriminant", () => {
+        const failure = {
+            schemaVersion: 1,
+            ok: false,
+            reason: "timeout",
+            error: "timed out after 100ms",
+            exitCode: 143,
+        };
+        const out = shapeProposalProducerOutput(failure, "full");
+        expect(out.reason).toBe("timeout");
+        expect(out.schemaVersion).toBe(1);
+    });
+    test("propose-specific failure: type+name appear when set on the result", () => {
+        // propose surfaces `type` and `name` in failure envelopes (the input args),
+        // separate from the agent-side `ref`. shapeProposalProducerOutput threads
+        // both fields through unconditionally when present.
+        const failure = {
+            schemaVersion: 1,
+            ok: false,
+            reason: "non_zero_exit",
+            error: "agent failed",
+            type: "skill",
+            name: "hello",
+            exitCode: 3,
+        };
+        const out = shapeProposalProducerOutput(failure, "normal");
+        expect(out.type).toBe("skill");
+        expect(out.name).toBe("hello");
+    });
+});

package/dist/tests/contracts/spec-helpers.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import path from "node:path";
+const repoRoot = path.resolve(import.meta.dir, "..", "..");
+export const SPEC_PATH = path.join(repoRoot, "docs", "technical", "v1-architecture-spec.md");
+export const CLI_DOC_PATH = path.join(repoRoot, "docs", "cli.md");
+export const CONFIG_DOC_PATH = path.join(repoRoot, "docs", "configuration.md");
+export const MIGRATION_PATH = path.join(repoRoot, "docs", "migration", "v1.md");
+export function readDoc(p) {
+    return fs.readFileSync(p, "utf8");
+}
+/**
+ * Extract a section by its heading line (e.g. "## 9. Locked contracts for v1").
+ * Returns an empty string if the heading is not present.
+ *
+ * Used by contract tests to scope their assertions to a single spec
+ * section so unrelated edits elsewhere in the doc don't cause false
+ * positives.
+ */
+export function extractSection(doc, heading) {
+    const start = doc.indexOf(heading);
+    if (start < 0)
+        return "";
+    const depthMatch = heading.match(/^#+/);
+    const depth = depthMatch ? depthMatch[0].length : 2;
+    // Stop only on a heading at the SAME depth or shallower, OUTSIDE any
+    // fenced code block. Markdown headings inside ```...``` blocks are not
+    // real headings and must not terminate a section. We stream the doc line
+    // by line tracking fence state.
+    const lines = doc.slice(start + heading.length).split("\n");
+    const stopRe = new RegExp(`^#{1,${depth}}\\s`);
+    let inFence = false;
+    let consumed = 0;
+    // Skip the rest of the heading line itself.
+    consumed += (lines.shift() ?? "").length + 1;
+    for (const line of lines) {
+        const fenceMatch = /^(```+|~~~+)/.test(line.trimStart());
+        if (fenceMatch) {
+            inFence = !inFence;
+        }
+        else if (!inFence && stopRe.test(line)) {
+            return doc.slice(start, start + heading.length + consumed);
+        }
+        consumed += line.length + 1;
+    }
+    return doc.slice(start);
+}

package/dist/tests/contracts/v1-spec-section-11-proposal-queue.test.js

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { akmDistill } from "../../src/commands/distill";
+import { akmPropose } from "../../src/commands/propose";
+import { akmReflect } from "../../src/commands/reflect";
+import { readEvents } from "../../src/core/events";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §11 — Proposal queue (Planned for v1).
+const REQUIRED_PROPOSAL_FIELDS = ["id", "ref", "status", "source", "sourceRun", "createdAt", "updatedAt"];
+const REQUIRED_PROPOSAL_COMMANDS = ["list", "show", "diff", "accept", "reject"];
+const REQUIRED_EVENTS = ["propose_invoked", "reflect_invoked", "distill_invoked", "promoted", "rejected"];
+describe("v1 spec §11 — proposal queue", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 11. Proposal queue");
+    test("§11 exists and is marked Planned for v1", () => {
+        expect(section).not.toBe("");
+        expect(section).toContain("Planned for v1");
+    });
+    test("§11.1 names the per-id proposal directory layout as the durable store", () => {
+        // Storage is one directory per proposal under <stashRoot>/.akm/proposals/<id>/
+        // containing a single proposal.json (queue state, not asset state).
+        expect(section).toContain(".akm/proposals/<id>/");
+        expect(section).toContain("proposal.json");
+    });
+    test("§11.1 declares each required proposal field", () => {
+        for (const field of REQUIRED_PROPOSAL_FIELDS) {
+            expect(section).toContain(`\`${field}\``);
+        }
+    });
+    test("§11.1 declares pending/accepted/rejected statuses + archive-by-move", () => {
+        expect(section).toContain("`pending`");
+        expect(section).toContain("`accepted`");
+        expect(section).toContain("`rejected`");
+        // Archival is a directory move, not a separate status (see §11.1 prose).
+        expect(section).toMatch(/archive\/<id>\/|archive-by-move|moved to.*archive/i);
+    });
+    test("§11.2 lists every proposal subcommand", () => {
+        for (const cmd of REQUIRED_PROPOSAL_COMMANDS) {
+            expect(section).toContain(`akm proposal ${cmd}`);
+        }
+    });
+    test("§11.2 says `accept` validates BEFORE promoting", () => {
+        const flat = section.replace(/\s+/g, " ");
+        expect(flat).toMatch(/validation .*\*\*before\*\* promoting/i);
+    });
+    test("§11.2 says `accept` promotes via writeAssetToSource()", () => {
+        // The locked rule is "all asset writes funnel through writeAssetToSource".
+        // The proposal queue is the only legal path that bypasses it for queue
+        // state — promotion must hand back to the single dispatch point.
+        expect(section).toContain("writeAssetToSource()");
+    });
+    test("§11.1 says multiple proposals per `ref` coexist", () => {
+        // The id is per-proposal; the ref isn't unique. The queue must hold N
+        // proposals for the same target ref without filesystem collisions.
+        // Directory-per-id is the mechanism the spec calls out for this.
+        expect(section).toMatch(/multiple proposals.*for the same `ref`|coexist for the same `ref`/i);
+    });
+    test("§11.2 names a `--reason` flag on `reject`", () => {
+        expect(section).toMatch(/akm proposal reject.*--reason/);
+    });
+    test("§11.3 declares every locked event name", () => {
+        for (const event of REQUIRED_EVENTS) {
+            expect(section).toContain(`\`${event}\``);
+        }
+    });
+    test("§11.3 says other plugins cannot reuse these event names", () => {
+        expect(section).toMatch(/cannot reuse these names/i);
+    });
+    test("§11 stops before §12 (helper boundary check)", () => {
+        // Defensive: extractSection() returns to EOF if no sibling stop
+        // heading exists. Pin the section terminus so a missing §12 heading
+        // (or a renamed one) trips this test instead of silently spilling
+        // §12+§13+§14 content into the §11 assertions above.
+        expect(section).not.toContain("## 12.");
+        expect(section).not.toContain("## 13.");
+        expect(section).not.toContain("## 14.");
+    });
+});
+// ── #284 GAP-MED 4: event metadata shape ─────────────────────────────────────
+//
+// Locks the metadata payload of the producer events so observers (audit,
+// dashboards) can rely on consistent keys.
+const tempDirs = [];
+const savedEnv = {
+    AKM_STASH_DIR: process.env.AKM_STASH_DIR,
+    XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+    XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+};
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function makeStashDir() {
+    const stash = makeTempDir("akm-events-meta-stash-");
+    for (const sub of ["lessons", "skills", "memories"]) {
+        fs.mkdirSync(path.join(stash, sub), { recursive: true });
+    }
+    return stash;
+}
+function makeProfile() {
+    return {
+        name: "fake-agent",
+        bin: "fake-agent",
+        args: [],
+        stdio: "captured",
+        envPassthrough: ["PATH"],
+        parseOutput: "text",
+    };
+}
+function asReadableStream(text) {
+    const bytes = new TextEncoder().encode(text);
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+function fakeSpawn(stdout, exitCode) {
+    return () => {
+        const proc = {
+            exitCode,
+            exited: Promise.resolve(exitCode),
+            stdout: asReadableStream(stdout),
+            stderr: asReadableStream(""),
+            stdin: null,
+            kill: () => undefined,
+        };
+        return proc;
+    };
+}
+const VALID_LESSON_PAYLOAD = JSON.stringify({
+    ref: "lesson:rg",
+    content: "---\ndescription: Use rg\nwhen_to_use: large repos\n---\n\nUse rg.\n",
+});
+const VALID_SKILL_PAYLOAD = JSON.stringify({
+    ref: "skill:hello",
+    content: "---\ndescription: hi\nwhen_to_use: greeting\n---\n\nHi.\n",
+});
+beforeEach(() => {
+    process.env.XDG_CACHE_HOME = makeTempDir("akm-events-meta-cache-");
+    process.env.XDG_CONFIG_HOME = makeTempDir("akm-events-meta-config-");
+});
+afterEach(() => {
+    if (savedEnv.AKM_STASH_DIR === undefined)
+        delete process.env.AKM_STASH_DIR;
+    else
+        process.env.AKM_STASH_DIR = savedEnv.AKM_STASH_DIR;
+    if (savedEnv.XDG_CACHE_HOME === undefined)
+        delete process.env.XDG_CACHE_HOME;
+    else
+        process.env.XDG_CACHE_HOME = savedEnv.XDG_CACHE_HOME;
+    if (savedEnv.XDG_CONFIG_HOME === undefined)
+        delete process.env.XDG_CONFIG_HOME;
+    else
+        process.env.XDG_CONFIG_HOME = savedEnv.XDG_CONFIG_HOME;
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("§11 event metadata shape (runtime)", () => {
+    test("reflect_invoked carries `task` + optional `profile` in metadata", async () => {
+        const stash = makeStashDir();
+        await akmReflect({
+            ref: "lesson:rg",
+            task: "focus on perf",
+            profile: "claude",
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: { spawn: fakeSpawn(VALID_LESSON_PAYLOAD, 0) },
+        });
+        const { events } = readEvents({ type: "reflect_invoked" });
+        expect(events.length).toBe(1);
+        const md = (events[0].metadata ?? {});
+        expect(md.task).toBe("focus on perf");
+        expect(md.profile).toBe("claude");
+        expect(events[0].ref).toBe("lesson:rg");
+    });
+    test("propose_invoked carries `type`+`name`+`task` in metadata", async () => {
+        const stash = makeStashDir();
+        await akmPropose({
+            type: "skill",
+            name: "hello",
+            task: "say hi",
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: { spawn: fakeSpawn(VALID_SKILL_PAYLOAD, 0) },
+        });
+        const { events } = readEvents({ type: "propose_invoked" });
+        expect(events.length).toBe(1);
+        const md = (events[0].metadata ?? {});
+        expect(md.type).toBe("skill");
+        expect(md.name).toBe("hello");
+        expect(md.task).toBe("say hi");
+        expect(events[0].ref).toBe("skill:hello");
+    });
+    test("distill_invoked metadata includes `outcome` (queued|skipped|validation_failed)", async () => {
+        const stash = makeStashDir();
+        const config = {
+            stashDir: stash,
+            sources: [{ type: "filesystem", name: "stash", path: stash, writable: true }],
+            defaultWriteTarget: "stash",
+            llm: {
+                endpoint: "http://localhost:11434/v1/chat/completions",
+                model: "test-model",
+                features: { feedback_distillation: true },
+            },
+        };
+        await akmDistill({
+            ref: "skill:deploy",
+            config,
+            stashDir: stash,
+            chat: async () => "---\ndescription: x\nwhen_to_use: y\n---\n\nbody.\n",
+            lookupFn: async () => null,
+            readEventsFn: (() => ({ events: [], nextOffset: 0 })),
+        });
+        const { events } = readEvents({ type: "distill_invoked" });
+        expect(events.length).toBe(1);
+        const md = (events[0].metadata ?? {});
+        expect(["queued", "skipped", "validation_failed"]).toContain(md.outcome);
+        // `proposalId` only stamped on the queued path
+        if (md.outcome === "queued")
+            expect(typeof md.proposalId).toBe("string");
+    });
+});

package/dist/tests/contracts/v1-spec-section-12-agent-config.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { CONFIG_DOC_PATH, extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §12 — Agent CLI integration (Planned for v1).
+const BUILT_IN_PROFILES = ["opencode", "claude", "codex", "gemini", "aider"];
+const SPAWN_FAILURE_REASONS = ["timeout", "spawn_failed", "non_zero_exit", "parse_error"];
+describe("v1 spec §12 — agent CLI integration", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 12. Agent CLI integration");
+    test("§12 exists and is marked Planned for v1", () => {
+        expect(section).not.toBe("");
+        expect(section).toContain("Planned for v1");
+    });
+    test("§12.1 lists every built-in profile", () => {
+        for (const p of BUILT_IN_PROFILES) {
+            expect(section).toContain(`\`${p}\``);
+        }
+    });
+    test("§12.1 declares the AgentProfile shape", () => {
+        expect(section).toMatch(/interface AgentProfile/);
+        expect(section).toMatch(/readonly bin: string/);
+        expect(section).toMatch(/readonly args: readonly string\[\]/);
+        expect(section).toMatch(/captured.*interactive/s);
+    });
+    test("§12.2 names every spawn-wrapper failure reason", () => {
+        for (const r of SPAWN_FAILURE_REASONS) {
+            expect(section).toContain(`"${r}"`);
+        }
+    });
+    test("§12.4 declares reflect/propose write only to the proposal queue", () => {
+        expect(section).toMatch(/write\s*\*\*only\*\*\s*to the proposal queue/i);
+    });
+    test("§12 stops before §13 (helper boundary check)", () => {
+        // Defensive: extractSection() returns to EOF if no sibling stop
+        // heading exists. Pin the section terminus so a missing §13 heading
+        // (or a renamed one) trips this test instead of silently spilling
+        // §13+§14 content into the §12 assertions above.
+        expect(section).not.toContain("## 13.");
+        expect(section).not.toContain("## 14.");
+    });
+});
+describe("v1 spec §12 — configuration.md mirrors the agent block", () => {
+    const config = readDoc(CONFIG_DOC_PATH);
+    const block = extractSection(config, "## `agent.*` block");
+    test("configuration.md has the agent block section", () => {
+        expect(block).not.toBe("");
+    });
+    test("configuration.md declares the three top-level agent keys", () => {
+        expect(block).toContain("`agent.default`");
+        expect(block).toContain("`agent.timeoutMs`");
+        expect(block).toContain("`agent.profiles[<name>]`");
+    });
+    test("configuration.md says missing `agent` block raises ConfigError with hint", () => {
+        expect(block).toMatch(/ConfigError/);
+        expect(block).toMatch(/hint/i);
+    });
+});

package/dist/tests/contracts/v1-spec-section-13-lesson-type.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "bun:test";
+import { ASSET_SPECS, TYPE_DIRS } from "../../src/core/asset-spec";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §13 — Lesson asset type (Planned for v1).
+describe("v1 spec §13 — lesson asset type", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 13. Lesson asset type");
+    test("§13 exists and is marked Planned for v1", () => {
+        expect(section).not.toBe("");
+        expect(section).toContain("Planned for v1");
+    });
+    test("§13.1 declares `description` and `when_to_use` are required", () => {
+        expect(section).toMatch(/description:\s*required/);
+        expect(section).toMatch(/when_to_use:\s*required/);
+    });
+    test("§13.2 stores lessons under `lessons/`", () => {
+        expect(section).toContain("`lessons/<name>.md`");
+    });
+    test("§13.3 routes distill output through the proposal queue", () => {
+        expect(section).toMatch(/akm distill/);
+        expect(section).toMatch(/akm proposal accept/);
+    });
+    test("`lesson` is registered as a well-known asset type at runtime", () => {
+        expect(ASSET_SPECS.lesson).toBeDefined();
+        expect(TYPE_DIRS.lesson).toBe("lessons");
+    });
+    test("§13 stops before §14 (helper boundary check)", () => {
+        // Defensive: extractSection() returns to EOF if no sibling stop
+        // heading exists. Pin the section terminus so a missing §14 heading
+        // (or a renamed one) trips this test instead of silently spilling
+        // §14 content into the §13 assertions above.
+        expect(section).not.toContain("## 14.");
+    });
+});

package/dist/tests/contracts/v1-spec-section-14-llm-features.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, test } from "bun:test";
+import { isLlmFeatureEnabled, tryLlmFeature } from "../../src/llm/feature-gate";
+import { CONFIG_DOC_PATH, extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §14 — `llm.features.*` (Planned for v1).
+//
+// The locked feature keys cannot be renamed after v1.0. New keys may be
+// added; these must not move. Spec §14 retains the historical phantom keys
+// (`tag_dedup`, `memory_consolidation`, `embedding_fallback_score`) so the
+// spec text continues to compile, but they are not in the runtime schema or
+// in user-facing configuration.md (issue #284 phantom-flag cleanup).
+const LOCKED_FEATURE_KEYS = ["curate_rerank", "feedback_distillation", "memory_inference", "graph_extraction"];
+describe("v1 spec §14 — llm.features.*", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "## 14. `llm.features.*`");
+    test("§14 exists and is marked Planned for v1", () => {
+        expect(section).not.toBe("");
+        expect(section).toContain("Planned for v1");
+    });
+    test("§14.1 declares every locked feature key", () => {
+        for (const k of LOCKED_FEATURE_KEYS) {
+            expect(section).toContain(`\`${k}\``);
+        }
+    });
+    test("§14.1 declares all defaults are false", () => {
+        expect(section).toMatch(/defaults are\s*`false`|all defaults are\s*`false`|defaults\s*`false`/i);
+    });
+    test("§14.2 defines mandatory failure-mode rules", () => {
+        expect(section).toMatch(/check the feature flag before/i);
+        expect(section).toMatch(/hard timeout/i);
+        expect(section).toMatch(/never\s*\*\*\s*mutate state on failure/i);
+    });
+    test("§14.4 codifies the statelessness invariant", () => {
+        expect(section).toMatch(/holds no state across calls/i);
+        expect(section).toMatch(/no streaming sessions/i);
+    });
+    test("§14.5 routes distill output through the proposal queue", () => {
+        const flat = section.replace(/\s+/g, " ");
+        expect(flat).toMatch(/`lesson` \*\*proposal\*\*/i);
+        expect(section).toContain("distill_invoked");
+    });
+    test("§14 documents orthogonality between llm.features.* and index.<pass>.llm", () => {
+        expect(section).toMatch(/orthogonal/i);
+        expect(section).toMatch(/llm\.features\.<key>/);
+        expect(section).toMatch(/index\.<pass>\.llm/);
+    });
+    test("§14 stops before §15 (helper boundary check)", () => {
+        // Defensive: extractSection() returns to EOF if no sibling stop
+        // heading exists. Pin the section terminus so a missing §15 heading
+        // (or a renamed one) trips this test instead of silently spilling
+        // §15+ content into the §14 assertions above.
+        expect(section).not.toContain("## 15.");
+        expect(section).not.toContain("## Appendix");
+    });
+});
+describe("v1 spec §14 — configuration.md mirrors the feature gates", () => {
+    const config = readDoc(CONFIG_DOC_PATH);
+    const block = extractSection(config, "## `llm.features.*` map");
+    test("configuration.md has the llm.features section", () => {
+        expect(block).not.toBe("");
+    });
+    test("configuration.md lists every locked feature key", () => {
+        for (const k of LOCKED_FEATURE_KEYS) {
+            expect(block).toContain(k);
+        }
+    });
+    test("configuration.md says unknown llm.features keys are warn-and-ignore", () => {
+        expect(block).toMatch(/Unknown keys.*warn-and-ignore/i);
+    });
+});
+describe("v1 spec §14 — runtime gate seam", () => {
+    // The graceful-fallback contract says: disabled gate returns the fallback
+    // without ever calling fn; throws are swallowed and return fallback. We
+    // pin the seam shape here so renames trigger the contract test.
+    test("isLlmFeatureEnabled is exported and pure", () => {
+        expect(typeof isLlmFeatureEnabled).toBe("function");
+        expect(isLlmFeatureEnabled(undefined, "curate_rerank")).toBe(false);
+    });
+    test("tryLlmFeature returns fallback when the gate is disabled (no fn call)", async () => {
+        let called = false;
+        const result = await tryLlmFeature("curate_rerank", undefined, () => {
+            called = true;
+            return "ran";
+        }, "fallback");
+        expect(result).toBe("fallback");
+        expect(called).toBe(false);
+    });
+    test("tryLlmFeature swallows throws and returns fallback when enabled", async () => {
+        const config = { llm: { features: { curate_rerank: true } } };
+        const result = await tryLlmFeature("curate_rerank", config, () => {
+            throw new Error("boom");
+        }, "fallback");
+        expect(result).toBe("fallback");
+    });
+});

package/dist/tests/contracts/v1-spec-section-4-1-asset-types.test.js

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { ASSET_SPECS } from "../../src/core/asset-spec";
+import { isAssetType } from "../../src/core/common";
+import { extractSection, readDoc, SPEC_PATH } from "./spec-helpers";
+// Pins v1 spec §4.1 — Asset type rules (open set).
+//
+// These tests are intentionally about the *rule*, not the specific list of
+// well-known types. The closed-set list can grow without breaking the
+// contract; what cannot change is that types are an open string set and
+// that the renderer registry is the authority.
+describe("v1 spec §4.1 — asset type rules (open set)", () => {
+    const spec = readDoc(SPEC_PATH);
+    const section = extractSection(spec, "### 4.1 Asset type rules (open set)");
+    test("§4.1 declares the open set rule in the spec", () => {
+        expect(section).not.toBe("");
+        expect(section).toContain("open string");
+        // Renderer registry is named as the authority for well-known types.
+        expect(section).toMatch(/renderer/i);
+    });
+    test("§4.1 names every well-known type that has a renderer today", () => {
+        // Every type that ships with an ASSET_SPECS entry today must be named in
+        // the well-known list. Adding a new type is fine; silently dropping one
+        // is not.
+        for (const type of Object.keys(ASSET_SPECS)) {
+            expect(section).toContain(`\`${type}\``);
+        }
+    });
+    test("§4.1 names `lesson` as a planned-for-v1 well-known type", () => {
+        expect(section).toContain("`lesson`");
+    });
+    test("isAssetType() accepts arbitrary strings — open set in code", () => {
+        // The spec says the type is an open string. The runtime validator must
+        // not reject unknown types as part of ref parsing. We only assert the
+        // function returns the expected boolean shape; specific well-known
+        // values are allowed but not required to be the only true cases.
+        expect(typeof isAssetType("skill")).toBe("boolean");
+        expect(typeof isAssetType("definitely-not-a-real-type")).toBe("boolean");
+    });
+});