akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/adapter/adapters/shared.js

@@ -0,0 +1,286 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Shared helpers for the concrete `BundleAdapter` implementations under
+ * `src/core/adapter/adapters/` — akm 0.9.0 chunk-2, WI-A (the `okf` adapter).
+ *
+ * ── Cycle-safety (chunk-2 "cycle-safety watch") ──
+ *
+ * The base-check logic below is a PORT, not an import, of
+ * `src/commands/lint/base-linter.ts`'s `runBaseChecks` (the 4 checks every
+ * non-`DefaultLinter` class inherits: unquoted-colon, missing-updated,
+ * stale-path, missing-ref). Importing `base-linter.ts` directly would add a
+ * new `src/core/adapter` -> `src/commands/lint` edge; `base-linter.ts`
+ * itself imports `core/asset/asset-spec.ts` (a baseline cycle participant,
+ * `scripts/lint-import-cycles.ts`) and `commands/lint/markdown-insertion.ts`
+ * — pulling either into `src/core/adapter/`'s import graph risks adding a
+ * 19th cycle participant against the zero-tolerance ratchet (baseline 18).
+ * Per the brief's explicit instruction ("copy the pure logic to a leaf ...
+ * do NOT use dynamic import to launder"), the pure regex/string logic is
+ * duplicated here, adapted to `Diagnostic`/`ValidateContext`. Verified
+ * cycle-safe: `bun scripts/lint-import-cycles.ts` stays at 18 with this file
+ * present (see the WI-A report).
+ *
+ * ── What did NOT get ported ──
+ *
+ * `bundle-adapter.ts`'s own doc comment is explicit that `validate()`
+ * "MUST NOT write and MUST NOT read the live filesystem" — reads go through
+ * `ValidateContext`, which serves the run snapshot WITH pending changes
+ * overlaid. `stale-path`'s legacy check called `fs.existsSync` directly on
+ * arbitrary absolute paths found in content; here it goes through
+ * `ctx.readFile(candidate)` instead (a `null` result means "does not
+ * exist") — the interface-compliant translation of the same check, not a
+ * behavior change for any path that genuinely exists or doesn't.
+ *
+ * The `refs:`-frontmatter-array authoritative-list carve-out (session-
+ * checkpoint memories; `base-linter.ts`'s `extractFrontmatterRefs`) is NOT
+ * ported here — it is memory/session-specific and no OKF concept uses it. A
+ * later memory/note adapter should extend `extractProseRefTokens`'s caller with
+ * that carve-out when it ports memory/session.
+ *
+ * The fence-strip (`stripFencedBlocksSimple` below) is a simplified,
+ * same-INTENT reimplementation of `markdown-insertion.ts`'s
+ * `findFenceRegions` (which is also table/HTML-region aware, because it
+ * additionally powers safe line INSERTION, a concern this module doesn't
+ * have) — not byte-identical on every edge case, but sufficient for "don't
+ * flag a ref/path inside a ``` example," which is the only thing this
+ * module needs the strip for.
+ */
+import { createHash } from "node:crypto";
+import { parseFrontmatter } from "../../asset/frontmatter.js";
+// ── Small pure helpers, reused across the concrete adapters ──────────────────
+/** Content hash feeding `IndexDocument.hash` (incrementality/fingerprints, `types.ts` doc comment). */
+export function hashContent(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** Trim a possibly-non-string frontmatter value down to a non-empty string or `undefined` (mirrors `core/common.ts#asNonEmptyString`, duplicated locally to avoid importing a cycle-participant module for a 4-line helper). */
+export function nonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/** Read a frontmatter `tags:` array down to its non-empty string entries, or `undefined` when there are none (mirrors `output/renderers.ts#readFrontmatterTags`). */
+export function readTags(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const tags = value.filter((tag) => typeof tag === "string" && tag.trim().length > 0);
+    return tags.length > 0 ? tags : undefined;
+}
+// ── Base validate checks (port of `BaseLinter.runBaseChecks`) ────────────────
+function checkUnquotedColon(frontmatterText) {
+    if (!frontmatterText)
+        return null;
+    for (const line of frontmatterText.split(/\r?\n/)) {
+        const match = line.match(/^description:\s*(.*)/);
+        if (!match)
+            continue;
+        const value = match[1].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            return null;
+        }
+        if (value.includes(":")) {
+            return `description value contains unquoted colon: ${value}`;
+        }
+    }
+    return null;
+}
+function checkMissingUpdated(data, frontmatterText) {
+    return frontmatterText !== null && !("updated" in data);
+}
+function findStalePathCandidates(body) {
+    const pathRe = /(?:\/home\/|\/tmp\/|\/var\/|\/root\/|\/opt\/)[^\s"'`)\]>,\n]+/g;
+    const out = [];
+    let match;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
+    while ((match = pathRe.exec(body)) !== null)
+        out.push(match[0]);
+    return out;
+}
+/** See file header: same intent as `markdown-insertion.ts#findFenceRegions`, not byte-identical. */
+function stripFencedBlocksSimple(body) {
+    const lines = body.split(/\r?\n/);
+    let inFence = false;
+    const out = lines.map((line) => {
+        if (/^\s*```/.test(line)) {
+            const wasInFence = inFence;
+            inFence = !inFence;
+            return wasInFence || inFence ? "" : line;
+        }
+        return inFence ? "" : line;
+    });
+    return out.join("\n");
+}
+// Ref-token grammar — copied from `base-linter.ts`'s `BUNDLE_REF_RE`
+// (`core/asset/asset-ref.ts`, spec §11.1 / ref-grammar decision D-R3) as a VALUE,
+// not an import (same cycle-avoidance rationale as the file header — the source
+// string is duplicated so no new `core/adapter` -> `core/asset` edge is added for
+// this scan). Recognizes the 0.9.0 FULLY-QUALIFIED `<bundle>//<concept-id>
+// [#fragment]` prose body-ref anchored form ONLY. Per D-R3, a bare short
+// conceptId in prose is NOT a ref, so it is never flagged here (it is a ref only
+// in the ref-LIST channels — {@link refTokenFromListValue}). The pre-0.9.0
+// `<type>:<slug>` colon grammar is gone from every recognition surface.
+const BUNDLE_BODY_REF_RE_SRC = "(?:^|[\\s`\"'(,[])([^\\s:.#/`\"'()[\\],<>]+\\/\\/[^\\s\"'`)\\]>,\\n]+)";
+/**
+ * A conceptId that is a lint false positive rather than a real ref — mirrors the
+ * `isNonRefName` guards `base-linter.ts` applies deep in its existence check:
+ * template placeholders (`skills/<name>`) and degenerate/incomplete tokens.
+ */
+function isNonRefConceptId(conceptId) {
+    const id = conceptId.split("#", 1)[0]; // drop the export #fragment selector
+    if (!id || id.length <= 1 || id === "**")
+        return true;
+    if (id.includes("<"))
+        return true; // template placeholder, e.g. `skills/<name>`
+    return false;
+}
+/**
+ * Extract the fully-qualified `bundle//conceptId` refs from PROSE — the flipped
+ * `base-linter.ts#checkMissingRefs` semantics (`BUNDLE_REF_RE`, qualified-only;
+ * bare short conceptIds are NOT refs, D-R3). Fenced code is stripped first so
+ * example refs inside ``` are not flagged; shell-substitution (`$(`/`${`) and
+ * ACP (`::`) false positives are dropped.
+ */
+function extractProseRefTokens(text) {
+    const re = new RegExp(BUNDLE_BODY_REF_RE_SRC, "gm");
+    const scanBody = stripFencedBlocksSimple(text);
+    const refs = [];
+    let match;
+    // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
+    while ((match = re.exec(scanBody)) !== null) {
+        const token = match[1];
+        if (token.includes("$(") || token.includes("${") || token.includes("::"))
+            continue;
+        if (isNonRefConceptId(token.slice(token.indexOf("//") + 2)))
+            continue;
+        refs.push(token);
+    }
+    return refs;
+}
+/**
+ * Recognize a single frontmatter ref-LIST value (`xrefs:`/`supersededBy:`/
+ * `contradictedBy:`) as a whole ref — the flipped `base-linter.ts#
+ * checkMissingRefsInList` semantics. Unlike prose, a bare short `conceptId` IS a
+ * ref here (the value's whole purpose is to name one asset). Returns the ref
+ * token, or `null` for a false positive or a legacy `origin//type:name` value
+ * (the colon-grammar is retired — D-R3).
+ */
+function refTokenFromListValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes("$(") || trimmed.includes("${") || trimmed.includes("::"))
+        return null;
+    const boundary = trimmed.indexOf("//");
+    // Qualified `bundle//conceptId`: a colon in the tail marks a legacy/remote
+    // `origin//type:name` — not the 0.9.0 grammar — so skip it. Un-prefixed values
+    // are a 0.9.0 short conceptId; a colon there is likewise the retired grammar.
+    const conceptId = boundary >= 0 ? trimmed.slice(boundary + 2) : trimmed;
+    if (conceptId.includes(":") || isNonRefConceptId(conceptId))
+        return null;
+    return trimmed;
+}
+const XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
+function readRefStringOrArray(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : null;
+    }
+    if (!Array.isArray(value))
+        return null;
+    const out = value.filter((v) => typeof v === "string" && v.trim().length > 0).map((v) => v.trim());
+    return out.length > 0 ? out : null;
+}
+/**
+ * Port of `BaseLinter.runBaseChecks`, adapted to the read-only
+ * `ValidateContext`/`Diagnostic` shapes (adapter spec §12.1). Reproduces
+ * unquoted-colon / missing-updated / stale-path / missing-ref for ONE file's
+ * already-parsed content.
+ *
+ * `fixed` is always `false`: `BundleAdapter.validate` MUST NOT write the
+ * filesystem, so there is no fix-apply mechanism at this layer — a documented,
+ * intentional behavior narrowing from the legacy `--fix`-capable linter.
+ *
+ * `componentRoot` is `BundleComponent.root` — used only for the stale-path
+ * "portable form" hint (mirrors legacy `ctx.stashRoot`-relative substitution;
+ * no I/O).
+ */
+export async function runBaseValidateChecks(relPath, parsed, componentRoot, ctx) {
+    const diagnostics = [];
+    const { data, content: body, frontmatter } = parsed;
+    const unquotedColonDetail = checkUnquotedColon(frontmatter);
+    if (unquotedColonDetail) {
+        diagnostics.push({ file: relPath, issue: "unquoted-colon", detail: unquotedColonDetail, fixed: false });
+    }
+    if (checkMissingUpdated(data, frontmatter)) {
+        diagnostics.push({
+            file: relPath,
+            issue: "missing-updated",
+            detail: "no updated field in frontmatter",
+            fixed: false,
+        });
+    }
+    const staleCandidates = [
+        ...findStalePathCandidates(body),
+        ...(frontmatter ? findStalePathCandidates(frontmatter) : []),
+    ];
+    for (const candidate of staleCandidates) {
+        const found = await ctx.readFile(candidate);
+        if (found !== null)
+            continue;
+        const portableHint = candidate.startsWith(componentRoot)
+            ? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(componentRoot.length)})`
+            : "";
+        diagnostics.push({
+            file: relPath,
+            issue: "stale-path",
+            detail: `nonexistent path: ${candidate}${portableHint}`,
+            fixed: false,
+        });
+    }
+    for (const ref of extractProseRefTokens(body)) {
+        const { exists } = await ctx.resolveRef(ref);
+        if (!exists)
+            diagnostics.push({ file: relPath, issue: "missing-ref", detail: `missing ref: ${ref}`, fixed: false });
+    }
+    if (frontmatter !== null) {
+        for (const key of XREF_FRONTMATTER_KEYS) {
+            const values = readRefStringOrArray(data[key]);
+            if (values === null)
+                continue;
+            for (const value of values) {
+                const ref = refTokenFromListValue(value);
+                if (ref === null)
+                    continue;
+                const { exists } = await ctx.resolveRef(ref);
+                if (!exists) {
+                    diagnostics.push({
+                        file: relPath,
+                        issue: "missing-ref",
+                        detail: `missing ref: ${ref} (frontmatter ${key})`,
+                        fixed: false,
+                    });
+                }
+            }
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Shared per-change loop: for every non-delete change with readable content,
+ * parse frontmatter and run {@link runBaseValidateChecks}. Adapters with extra
+ * per-type checks (e.g. `okf`'s missing-type / OKF-link warnings) run their own
+ * loop and call {@link runBaseValidateChecks} directly instead.
+ */
+export async function validateChangesWithBaseChecks(c, changes, ctx) {
+    const diagnostics = [];
+    for (const change of changes) {
+        if (change.op === "delete")
+            continue;
+        const raw = change.after ?? (await ctx.readFile(change.path));
+        if (typeof raw !== "string")
+            continue;
+        const parsed = parseFrontmatter(raw);
+        diagnostics.push(...(await runBaseValidateChecks(change.path, parsed, c.root, ctx)));
+    }
+    return diagnostics;
+}

package/dist/core/adapter/adapters/tool-dir-shared.js

@@ -0,0 +1,217 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Shared recognition / placement / validation for the two AGENT TOOL-DIRECTORY
+ * adapters — `claude` (`.claude`) and `opencode` (`.opencode`) — akm 0.9.0
+ * format-family work item (#46). Both translate a foreign tool layout into the
+ * open AKM `type` vocabulary (spec §6/§7): a root instruction file
+ * (CLAUDE.md / AGENTS.md) → `instruction`, `commands/*.md` → `command`,
+ * `agents/*.md` → `agent`, `skills/<name>/SKILL.md` → `skill` (item = the dir).
+ * They differ only in three parameters carried on {@link ToolDirLayout}:
+ *   - the instruction basename + its concept id,
+ *   - the accepted subdir spellings (opencode accepts the SINGULAR
+ *     `command/`/`agent/`/`skill/` aliases per open-question-6, claude does not),
+ *   - the adapter id + component id.
+ *
+ * The SKILL.md codec is shared with the `agent-skills` adapter as functions
+ * (spec §8): a skill's conceptId is its DIRECTORY, and its `name` is the
+ * frontmatter `name` (== the dir name per the Agent Skills §4.5 hard rule).
+ *
+ * ── D-R6 (reserved files) ──
+ *
+ * `index.md` / `log.md` are OKF structural files at EVERY depth — never a
+ * concept. `classify` excludes them up front so a stray `commands/index.md`
+ * never becomes a `command` (mirrors okf/akm/llm-wiki `RESERVED_FILES`).
+ *
+ * ── validate leniency (spec §6 skill row) ──
+ *
+ * The tool-dir adapters TOLERATE the tools' native frontmatter (argument-hint,
+ * allowed-tools, tools, model, mode, temperature, agent, …) — the strict
+ * unknown-frontmatter behavior belongs to `agent-skills`, not here. So `command`
+ * / `agent` get a LENIENT name-or-signal check (never the akm `CommandLinter`'s
+ * frontmatter `name`+`type` requirement, which these tool files do not carry),
+ * `skill` gets the coded `missing-skill-md` directory check
+ * ({@link skillDirectoryDiagnostics}), and `instruction` runs the shared base
+ * checks (a no-op on a frontmatter-free CLAUDE.md/AGENTS.md). Notably NO base
+ * checks run on command/agent/skill: their tool frontmatter carries no `updated`
+ * field, so `missing-updated` would fire on every file and contradict the lint
+ * golden's clean result.
+ *
+ * ── Cycle-safety ──
+ *
+ * Imported only by `claude-adapter.ts` / `opencode-adapter.ts` (themselves
+ * imported by the `adapters/index.ts` barrel — NOT test-only: `core/adapter/
+ * registry.ts:33` imports it in production for the frozen `BUILTIN_ADAPTERS`
+ * list). This leaf still can never gain an inbound edge from a cycle
+ * participant, since nothing on that import chain imports back into it. It
+ * value-imports only pure leaves (`shared`, `akm-lint`, `frontmatter`) plus
+ * Node builtins.
+ */
+import path from "node:path";
+import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { skillDirectoryDiagnostics } from "./akm-lint.js";
+import { hashContent, nonEmptyString, readTags, runBaseValidateChecks } from "./shared.js";
+/** OKF reserved structural files (D-R6) — excluded at every depth, case-insensitive. */
+const RESERVED_FILES = new Set(["index.md", "log.md"]);
+/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
+const MAX_CONTENT_CHARS = 100_000;
+/** The canonical (plural) subdir spellings writes normalize to (open-question-6). */
+const CANONICAL_COMMAND_DIR = "commands";
+const CANONICAL_AGENT_DIR = "agents";
+const CANONICAL_SKILL_DIR = "skills";
+const SKILL_MANIFEST = "SKILL.md";
+function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+function isReserved(base) {
+    return RESERVED_FILES.has(base.toLowerCase());
+}
+/** Classify one component-root-relative file into a tool-dir `type` + conceptId, or abstain (null). */
+function classify(relPath, layout) {
+    const posix = toPosix(relPath);
+    const segs = posix.split("/").filter((s) => s.length > 0);
+    if (segs.length === 0)
+        return null;
+    const base = segs[segs.length - 1];
+    if (isReserved(base))
+        return null;
+    // Root instruction file.
+    if (segs.length === 1 && base === layout.instructionFile) {
+        return { type: "instruction", conceptId: layout.instructionConceptId, name: layout.instructionConceptId };
+    }
+    const head = segs[0];
+    const ext = path.extname(base).toLowerCase();
+    // skill: <skillDir>/<name>/SKILL.md — the item is the DIRECTORY. Any other
+    // file under a skill dir (bundled resources) is part of the item, not a concept.
+    if (layout.skillDirs.has(head)) {
+        if (segs.length >= 3 && base === SKILL_MANIFEST) {
+            return { type: "skill", conceptId: `${segs[0]}/${segs[1]}`, name: segs[1] };
+        }
+        return null;
+    }
+    if (layout.commandDirs.has(head) && ext === ".md" && segs.length >= 2) {
+        return { type: "command", conceptId: posix.replace(/\.md$/i, ""), name: base.replace(/\.md$/i, "") };
+    }
+    if (layout.agentDirs.has(head) && ext === ".md" && segs.length >= 2) {
+        return { type: "agent", conceptId: posix.replace(/\.md$/i, ""), name: base.replace(/\.md$/i, "") };
+    }
+    return null;
+}
+/** recognize() for a tool-dir adapter: derive the open `type`, project the OKF-shaped fields. */
+export function recognizeToolDir(layout, c, file) {
+    const cls = classify(file.relPath, layout);
+    if (cls === null)
+        return null;
+    const raw = file.content();
+    const parsed = parseFrontmatter(raw);
+    const data = parsed.data;
+    const body = parsed.content;
+    // For a skill, `name` is the frontmatter `name` (== dir name); otherwise the
+    // basename-derived concept name.
+    const name = cls.type === "skill" ? (nonEmptyString(data.name) ?? cls.name) : cls.name;
+    const description = nonEmptyString(data.description);
+    const tags = readTags(data.tags);
+    const doc = {
+        ref: `${c.id}//${cls.conceptId}`,
+        bundle: c.id,
+        component: layout.componentId,
+        conceptId: cls.conceptId,
+        path: file.absPath,
+        hash: hashContent(raw),
+        adapterId: layout.adapterId,
+        type: cls.type,
+        name,
+        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+    };
+    if (cls.type === "instruction")
+        doc.ownsPresentation = true;
+    if (description !== undefined)
+        doc.description = description;
+    if (tags !== undefined)
+        doc.tags = tags;
+    return doc;
+}
+/**
+ * placeNew() for a tool-dir adapter (spec §7: "AKM workspace layout IS the tool
+ * dir minus the prefix"). Writes NORMALIZE to the canonical plural subdir
+ * (open-question-6): a `command/foo` concept still places at `commands/foo.md`.
+ * The instruction file is fixed at the component root.
+ */
+export function placeNewToolDir(layout, c, conceptId) {
+    const posix = toPosix(conceptId);
+    if (posix === layout.instructionConceptId)
+        return path.join(c.root, layout.instructionFile);
+    const segs = posix.split("/").filter((s) => s.length > 0);
+    const head = segs[0];
+    const rest = segs.slice(1).join("/");
+    if (rest.length > 0) {
+        if (layout.skillDirs.has(head))
+            return path.join(c.root, CANONICAL_SKILL_DIR, rest, SKILL_MANIFEST);
+        if (layout.commandDirs.has(head))
+            return path.join(c.root, CANONICAL_COMMAND_DIR, `${rest}.md`);
+        if (layout.agentDirs.has(head))
+            return path.join(c.root, CANONICAL_AGENT_DIR, `${rest}.md`);
+    }
+    return path.join(c.root, `${posix}.md`);
+}
+/** LENIENT command/agent check: a diagnostic only when NEITHER a name/description NOR a type-shaped signal is present. */
+function nameOrSignalDiagnostics(type, relPath, data, body) {
+    if (nonEmptyString(data.name) !== undefined || nonEmptyString(data.description) !== undefined)
+        return [];
+    // command-shaped body/frontmatter signals (spec §6 command row): $ARGUMENTS / $1 / an `agent` frontmatter key.
+    if (type === "command" &&
+        (/\$ARGUMENTS\b/.test(body) || /\$\d/.test(body) || nonEmptyString(data.agent) !== undefined)) {
+        return [];
+    }
+    return [
+        {
+            file: relPath,
+            issue: "missing-name-or-type",
+            detail: `${type} has neither a name/description nor a ${type}-shaped signal`,
+            fixed: false,
+        },
+    ];
+}
+/** validate() for a tool-dir adapter — see file header for the leniency contract. */
+export async function validateToolDir(layout, c, changes, ctx) {
+    const diagnostics = [];
+    const seenSkillDirs = new Set();
+    for (const change of changes) {
+        if (change.op === "delete")
+            continue;
+        const raw = change.after ?? (await ctx.readFile(change.path));
+        if (typeof raw !== "string")
+            continue;
+        const relPath = toPosix(change.path);
+        // The one coded skill check (missing-skill-md) fires on ANY change under a
+        // `skills/<name>/…` package (self-gated + deduped), even a bundled resource —
+        // mirrors the akm adapter's per-change SkillLinter.lintDirectory pass.
+        diagnostics.push(...(await skillDirectoryDiagnostics(relPath, seenSkillDirs, ctx)));
+        const cls = classify(change.path, layout);
+        if (cls === null)
+            continue;
+        if (cls.type === "instruction") {
+            diagnostics.push(...(await runBaseValidateChecks(relPath, parseFrontmatter(raw), c.root, ctx)));
+        }
+        else if (cls.type === "command" || cls.type === "agent") {
+            const parsed = parseFrontmatter(raw);
+            diagnostics.push(...nameOrSignalDiagnostics(cls.type, relPath, parsed.data, parsed.content));
+        }
+        // skill: covered by skillDirectoryDiagnostics above; no additional per-file check.
+    }
+    return diagnostics;
+}
+/** Build the concrete `BundleAdapter` from a layout + a `looksLikeRoot` probe (claude/opencode share everything else). */
+export function makeToolDirAdapter(layout, looksLikeRoot) {
+    return {
+        id: layout.adapterId,
+        version: "0.9.0",
+        extensions: [".md"],
+        recognize: (c, file) => recognizeToolDir(layout, c, file),
+        validate: (c, changes, ctx) => validateToolDir(layout, c, changes, ctx),
+        placeNew: (c, conceptId) => placeNewToolDir(layout, c, conceptId),
+        directoryList: () => [CANONICAL_COMMAND_DIR, CANONICAL_AGENT_DIR, CANONICAL_SKILL_DIR],
+        looksLikeRoot,
+    };
+}

package/dist/core/adapter/adapters/website-snapshot-adapter.js

@@ -0,0 +1,155 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The `website-snapshot` adapter — akm 0.9.0 format-family work item (#46).
+ *
+ * A READ-ONLY (Mode A) view over a materialized crawl snapshot written by
+ * `src/sources/snapshot-fetchers/website-ingest.ts` (spec §6/§7). The on-disk
+ * pages are KNOWLEDGE-shaped markdown under `stash/knowledge/**` with no `type:`
+ * field; this adapter RE-TYPES them to the open `type: website`. Per
+ * open-question-3 (RESOLVED, maintainer 2026-07) the re-type is GATED — it
+ * applies only to a page carrying the `website` tag / a `sourceUrl` (a page
+ * lacking both is not re-typed); the document KEEPS its `sourceUrl` (surfaced as
+ * `sourceRef` on `documentJson`); and the conceptId STRIPS the
+ * `stash/knowledge/` prefix. `manifest.json` is snapshot PROVENANCE
+ * (`{url, fetchedAt}`), read by the probe but never indexed as a concept.
+ *
+ * Read-only ⇒ NO `placeNew` (Mode B export routes content through the
+ * DESTINATION adapter, which owns placement). `validate` runs base checks only
+ * (a mirror the adapter does not author has no native validators); `updated`
+ * never appears on a snapshot page, so `missing-updated` is filtered out.
+ *
+ * Conformance oracle (authored, DO NOT modify): fixture
+ * `tests/fixtures/bundles/website-snapshot/` + goldens
+ * `tests/fixtures/format-family-goldens/website-snapshot/{recognition,placement,lint,renderer}.json`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { parseFrontmatter, parseFrontmatterBlock } from "../../asset/frontmatter.js";
+import { hashContent, nonEmptyString, runBaseValidateChecks } from "./shared.js";
+/** A snapshot bundle is single-component; its one component is `main`. */
+const COMPONENT_ID = "main";
+/** The crawl page root the snapshot writer materializes pages under. */
+const PAGES_PREFIX = "stash/knowledge/";
+/** The provenance manifest basename (probe marker only, never indexed). */
+const MANIFEST_FILE = "manifest.json";
+/** The tag the snapshot writer stamps on every crawled page. */
+const WEBSITE_TAG = "website";
+/** Upper bound on the bounded `content` FTS field (mirrors okf-adapter). */
+const MAX_CONTENT_CHARS = 100_000;
+function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+function parseSnapshotFrontmatter(raw) {
+    const out = { tags: [] };
+    const block = parseFrontmatterBlock(raw);
+    if (!block)
+        return out;
+    let data = {};
+    try {
+        const value = parseYaml(block.frontmatter);
+        if (value && typeof value === "object" && !Array.isArray(value))
+            data = value;
+    }
+    catch {
+        return out;
+    }
+    out.title = nonEmptyString(data.title);
+    out.description = nonEmptyString(data.description);
+    out.sourceUrl = nonEmptyString(data.sourceUrl);
+    if (Array.isArray(data.tags)) {
+        out.tags = data.tags.filter((t) => typeof t === "string" && t.trim().length > 0).map((t) => t.trim());
+    }
+    return out;
+}
+/** True when a page is a crawl snapshot page under `stash/knowledge/**`. */
+function isSnapshotPage(relPath) {
+    const posix = toPosix(relPath);
+    return posix.startsWith(PAGES_PREFIX) && posix.toLowerCase().endsWith(".md");
+}
+/** The GATED re-type predicate (open-question-3): the page carries the `website` tag OR a `sourceUrl`. */
+function isReTypeGated(fm) {
+    return fm.sourceUrl !== undefined || fm.tags.includes(WEBSITE_TAG);
+}
+/** conceptId = page path − `stash/knowledge/` prefix − `.md`. */
+function conceptIdOf(relPath) {
+    return toPosix(relPath).slice(PAGES_PREFIX.length).replace(/\.md$/i, "");
+}
+function recognize(c, file) {
+    if (file.ext !== ".md" || !isSnapshotPage(file.relPath))
+        return null;
+    const raw = file.content();
+    const fm = parseSnapshotFrontmatter(raw);
+    if (!isReTypeGated(fm))
+        return null; // not a re-typed website page
+    const conceptId = conceptIdOf(file.relPath);
+    const name = fm.title ?? conceptId.split("/").pop() ?? conceptId;
+    const body = parseFrontmatter(raw).content;
+    const doc = {
+        ref: `${c.id}//${conceptId}`,
+        bundle: c.id,
+        component: COMPONENT_ID,
+        conceptId,
+        path: file.absPath,
+        hash: hashContent(raw),
+        adapterId: "website-snapshot",
+        ownsPresentation: true,
+        type: "website",
+        name,
+        content: body.length > MAX_CONTENT_CHARS ? body.slice(0, MAX_CONTENT_CHARS) : body,
+    };
+    if (fm.description !== undefined)
+        doc.description = fm.description;
+    if (fm.sourceUrl !== undefined)
+        doc.documentJson = { sourceRef: fm.sourceUrl };
+    return doc;
+}
+async function validate(c, changes, ctx) {
+    const diagnostics = [];
+    for (const change of changes) {
+        if (change.op === "delete")
+            continue;
+        const raw = change.after ?? (await ctx.readFile(change.path));
+        if (typeof raw !== "string")
+            continue;
+        if (!isSnapshotPage(change.path))
+            continue;
+        const base = await runBaseValidateChecks(toPosix(change.path), parseFrontmatter(raw), c.root, ctx);
+        // A read-only crawl mirror carries `fetchedAt` provenance, never an `updated`
+        // field — so `missing-updated` is not a defect on a snapshot page.
+        diagnostics.push(...base.filter((d) => d.issue !== "missing-updated"));
+    }
+    return diagnostics;
+}
+export const websiteSnapshotAdapter = {
+    id: "website-snapshot",
+    version: "0.9.0",
+    extensions: [".md"],
+    recognize,
+    validate,
+    // No placeNew: the snapshot is READ-ONLY (Mode A). Export (Mode B) routes
+    // content through the DESTINATION adapter, which owns placement.
+    /**
+     * Install-time probe (§1.2): a root carrying the snapshot provenance
+     * `manifest.json` (`{url, fetchedAt}`). No other bundle root carries this
+     * exact marker, so the probe is unambiguous.
+     */
+    looksLikeRoot(root) {
+        let raw;
+        try {
+            raw = fs.readFileSync(path.join(root, MANIFEST_FILE), "utf8");
+        }
+        catch {
+            return false;
+        }
+        try {
+            const manifest = JSON.parse(raw);
+            return typeof manifest.url === "string" && typeof manifest.fetchedAt === "string";
+        }
+        catch {
+            return false;
+        }
+    },
+};

package/dist/core/adapter/bundle-adapter.js

@@ -0,0 +1,4 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+export {};