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

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

@@ -0,0 +1,17 @@
+// 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/.
+import { getAdapters } from "./registry.js";
+/** Select the first built-in adapter whose ordered root probe claims `root`. */
+export function detectAdapterId(root, fallback = "akm") {
+    for (const adapter of getAdapters()) {
+        try {
+            if (adapter.looksLikeRoot?.(root) === true)
+                return adapter.id;
+        }
+        catch {
+            // An unreadable or racing probe does not claim the bundle.
+        }
+    }
+    return fallback;
+}

package/dist/core/adapter/recognize-match.js

@@ -0,0 +1,44 @@
+// 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/.
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher } from "../../indexer/walk/matchers.js";
+/**
+ * The four builtin matchers, in registration order. The array index IS the
+ * registration index `runMatchers` uses for tie-breaking. (The `wiki` matcher
+ * was removed in chunk 4 — the wiki asset-type is retired; LLM Wiki content is
+ * served by the first-class `llm-wiki` adapter, not the akm adapter. The YAML
+ * workflow-program matcher was removed by workflow-format-unification — one
+ * workflow format now, recognized by frontmatter `type: workflow` or
+ * residence under `workflows/`, both already covered by the remaining four.)
+ */
+const AKM_MATCHERS = [
+    extensionMatcher,
+    directoryMatcher,
+    parentDirHintMatcher,
+    smartMdMatcher,
+];
+/**
+ * Synchronous reproduction of `file-context.ts#runMatchers`'s arbitration
+ * (`:242-265`), minus its `ensureBuiltinsRegistered()` dynamic import. Runs
+ * every builtin matcher in registration order, collects the non-null
+ * `MatchResult`s, and returns the highest-specificity one (ties broken by the
+ * later-registered matcher — higher index — winning). Returns null when no
+ * matcher claims the file.
+ */
+export function recognizeMatch(file) {
+    const hits = [];
+    for (let i = 0; i < AKM_MATCHERS.length; i++) {
+        const result = AKM_MATCHERS[i](file);
+        if (result !== null)
+            hits.push({ result, index: i });
+    }
+    if (hits.length === 0)
+        return null;
+    hits.sort((a, b) => {
+        const specDiff = b.result.specificity - a.result.specificity;
+        if (specDiff !== 0)
+            return specDiff;
+        return b.index - a.index;
+    });
+    return hits[0].result;
+}

package/dist/core/adapter/registry.js

@@ -0,0 +1,56 @@
+// 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 format-family adapter registry — akm 0.9.0 (§4 / normative §12.6).
+ *
+ * A STATIC, FROZEN registry per normative §12.6: the ordered built-in adapter
+ * list ({@link BUILTIN_ADAPTERS}) is defined in the built-in barrel
+ * (`./adapters`) and this module exposes read-only lookups over it. There is NO
+ * mutable registration step and NO load-order dependency — `getAdapters()` and
+ * `adapterForId()` are populated at MODULE LOAD, so every production call site
+ * sees the full set without anyone first calling a registration function. This
+ * replaces the earlier mutable module-level singleton, whose "someone must
+ * register the built-ins first" contract left the registry empty in production
+ * (every source then fell back to `akm`).
+ *
+ * PRODUCTION CONSUMERS (all install/index-time, never query-time): the ordered
+ * `looksLikeRoot` probe in `installations.ts#detectAdapterId`, and the
+ * bundle-root probe in `provider-utils.ts#detectStashRoot`.
+ *
+ * KEYED BY `adapter.id` ONLY. Adapters are FORMAT FAMILIES (§0.2): one adapter
+ * per component root, and `recognize()` is the single source of truth for what
+ * a file IS. The open OKF `type` lives on the emitted `IndexDocument`, never on
+ * the adapter — so there is deliberately NO per-`type` → adapter mapping here.
+ *
+ * QUERY-TIME SAFETY (normative §14.3 / D11 — "adapters/registry never run at
+ * query time"): this module is imported only from install/index-time modules;
+ * the search path (`indexer/search/**`) does not import it, and importing the
+ * frozen list pulls the concrete adapters into no query-time graph.
+ */
+import { BUILTIN_ADAPTERS } from "./adapters/index.js";
+export { BUILTIN_ADAPTERS } from "./adapters/index.js";
+/** `adapter.id -> adapter`, frozen at module load from the static built-in list. */
+const BY_ID = new Map(BUILTIN_ADAPTERS.map((a) => [a.id, a]));
+/**
+ * Every built-in adapter, in the §1.2 install-time probe order (array order ==
+ * probe precedence; see `./adapters` for the ordering rationale). Returns a
+ * fresh array each call so callers may sort/filter it without disturbing the
+ * frozen registry.
+ */
+export function getAdapters() {
+    return [...BUILTIN_ADAPTERS];
+}
+/** Look up an adapter by its own `id` (matches `BundleComponent.adapter`); `undefined` for an unknown id (spec §4 — caller skips + warns). */
+export function adapterForId(id) {
+    return BY_ID.get(id);
+}
+/**
+ * DEPRECATED no-op retained for test back-compat only. The registry is a static
+ * frozen map (normative §12.6) populated at module load, so there is nothing to
+ * reset — `getAdapters()` / `adapterForId()` are always the full built-in set.
+ * New code MUST NOT depend on this.
+ */
+export function resetAdapterRegistryForTests() {
+    // intentionally empty — the registry is static; see the doc comment above.
+}

package/dist/core/adapter/types.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 {};

package/dist/core/asset/akm-markdown.js

@@ -0,0 +1,30 @@
+// 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/.
+import { parse as parseYaml } from "yaml";
+import { UsageError } from "../errors.js";
+import { serializeFrontmatter } from "./asset-serialize.js";
+import { parseFrontmatterBlock } from "./frontmatter.js";
+/** Ensure an AKM-authored Markdown concept is also a conformant OKF concept. */
+export function ensureAkmMarkdownType(content, type) {
+    const block = parseFrontmatterBlock(content);
+    if (!block)
+        return `---\ntype: ${type}\n---\n${content}`;
+    let parsed;
+    try {
+        parsed = block.frontmatter.trim() ? parseYaml(block.frontmatter) : {};
+    }
+    catch {
+        throw new UsageError("AKM Markdown has malformed YAML frontmatter.", "INVALID_FLAG_VALUE");
+    }
+    if (parsed === null)
+        parsed = {};
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new UsageError("AKM Markdown frontmatter must be a YAML mapping.", "INVALID_FLAG_VALUE");
+    }
+    const data = parsed;
+    if (data.type === type)
+        return content;
+    const { type: _priorType, ...rest } = data;
+    return `---\n${serializeFrontmatter({ type, ...rest })}\n---\n${block.content}`;
+}

package/dist/core/asset/asset-placement.js

@@ -0,0 +1,243 @@
+// 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/.
+/**
+ * Pure recognition/placement layer for the built-in akm asset types — akm
+ * 0.9.0 chunk-3 (the taxonomy-cutover leaf).
+ *
+ * This module is the SINGLE SOURCE OF TRUTH for the `AssetSpec` filesystem
+ * surface (`stashDir`/`isRelevantFile`/`toCanonicalName`/`toAssetPath`), the
+ * per-type stash-subdir map, and the derive/resolve helpers built on them.
+ * Chunk-3 deleted the mutable taxonomy globals that used to expose this data
+ * as ambient registries; the surface is now reached through the small typed
+ * accessors below (`stashDirFor`/`stashDirNames`/`placementTypes`/
+ * `assetPathForName`/`placementSpecFor`), which the `akm` bundle adapter
+ * (`adapter/adapters/akm-adapter.ts`) consumes for placement.
+ *
+ * ── Cycle-safety ──
+ *
+ * This leaf imports only Node builtins and the `core/recognition-util` pure
+ * sink, so it is NOT an import-cycle (SCC) participant. Depending on it from
+ * the `akm` adapter keeps the adapter a leaf. Renderer NAMES and action
+ * builders for the built-in types live in the static `type-presentation.ts`
+ * table (`TYPE_PRESENTATION`); they are intentionally absent here — placement
+ * is a filesystem concern, presentation is a rendering concern.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { SCRIPT_EXTENSIONS, WORKFLOW_EXTENSIONS } from "../recognition-util.js";
+function toPosix(input) {
+    return input.replace(/\\/g, "/");
+}
+const workflowSpec = {
+    isRelevantFile: (fileName) => WORKFLOW_EXTENSIONS.includes(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (rel.toLowerCase().endsWith(ext))
+                return rel.slice(0, -ext.length);
+        }
+        return rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Explicit extension wins (accepts refs like "release/ship.yaml").
+        const lower = name.toLowerCase();
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            if (lower.endsWith(ext))
+                return path.join(typeRoot, name);
+        }
+        // Probe in canonical extension priority order and fall back
+        // to the markdown path so error messages keep naming the canonical file.
+        for (const ext of WORKFLOW_EXTENSIONS) {
+            const candidate = path.join(typeRoot, `${name}${ext}`);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+        return path.join(typeRoot, `${name}.md`);
+    },
+};
+const markdownSpec = {
+    isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".md",
+    toCanonicalName: (typeRoot, filePath) => {
+        const rel = toPosix(path.relative(typeRoot, filePath));
+        // Strip .md extension from canonical names.
+        return rel.endsWith(".md") ? rel.slice(0, -3) : rel;
+    },
+    toAssetPath: (typeRoot, name) => {
+        // Accept both with and without .md extension
+        const withExt = name.endsWith(".md") ? name : `${name}.md`;
+        return path.join(typeRoot, withExt);
+    },
+};
+const scriptSpec = {
+    isRelevantFile: (fileName) => SCRIPT_EXTENSIONS.has(path.extname(fileName).toLowerCase()),
+    toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+    toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+};
+const BUILTIN_PLACEMENT_SPECS = {
+    skill: {
+        stashDir: "skills",
+        isRelevantFile: (fileName) => fileName === "SKILL.md",
+        toCanonicalName: (typeRoot, filePath) => {
+            const relDir = toPosix(path.dirname(path.relative(typeRoot, filePath)));
+            if (!relDir || relDir === ".")
+                return undefined;
+            return relDir;
+        },
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name, "SKILL.md"),
+    },
+    command: { stashDir: "commands", ...markdownSpec },
+    agent: { stashDir: "agents", ...markdownSpec },
+    knowledge: { stashDir: "knowledge", ...markdownSpec },
+    // R-045 / Q-18 second half (owner ruling 11, EXECUTE NOW) — `instruction` as
+    // a real stash-resident type, mirroring `knowledge`'s plain markdown spec.
+    // This is distinct from the ADAPTER-OWNED instruction docs emitted by
+    // format-family adapters (root CLAUDE.md/AGENTS.md via `tool-dir-shared.ts`):
+    // those carry `document.ownsPresentation === true` and are routed straight
+    // to their adapter's own projection by `rendererForIndexedEntry`
+    // (`src/commands/read/show.ts`), which checks `ownsPresentation` BEFORE
+    // ever consulting a type/renderer mapping. A stash-resident `instructions/`
+    // asset never sets that marker, so it always renders via the `knowledge-md`
+    // renderer (`TYPE_PRESENTATION.instruction`, `src/core/type-presentation.ts`)
+    // like any other placement type — no collision with the adapter-owned path.
+    instruction: { stashDir: "instructions", ...markdownSpec },
+    workflow: { stashDir: "workflows", ...workflowSpec },
+    script: { stashDir: "scripts", ...scriptSpec },
+    memory: { stashDir: "memories", ...markdownSpec },
+    // Environment assets — whole `.env` files sourced/injected wholesale. Replaced
+    // the deprecated `vault` type (removed in 0.9.0). Only key NAMES are surfaced
+    // as metadata; values and comment text are never read for indexing (comments
+    // routinely contain commented-out credentials).
+    env: {
+        stashDir: "env",
+        isRelevantFile: (fileName) => fileName === ".env" || fileName.endsWith(".env"),
+        toCanonicalName: (typeRoot, filePath) => {
+            const rel = toPosix(path.relative(typeRoot, filePath));
+            const fileName = path.basename(rel);
+            // Treat ".env" as the "default" env; "<name>.env" → "<name>"
+            if (fileName === ".env") {
+                const dir = path.dirname(rel);
+                return dir === "." || dir === "" ? "default" : `${dir}/default`;
+            }
+            const stripped = rel.endsWith(".env") ? rel.slice(0, -4) : rel;
+            return stripped;
+        },
+        toAssetPath: (typeRoot, name) => {
+            if (name === "default")
+                return path.join(typeRoot, ".env");
+            return path.join(typeRoot, name.endsWith(".env") ? name : `${name}.env`);
+        },
+    },
+    // Secrets — a single sensitive value used on its own for authentication (a
+    // PEM key, API token, TLS cert). Unlike `env` (a group of related .env
+    // configuration), the ENTIRE file is the one secret value — there is no safe
+    // region to parse, so only the filename is ever surfaced as metadata. A
+    // secret is any regular file under `secrets/` except `.lock`/`.sensitive`
+    // sidecars; the canonical name preserves the natural filename.
+    secret: {
+        stashDir: "secrets",
+        isRelevantFile: (fileName) => !fileName.endsWith(".lock") && !fileName.endsWith(".sensitive"),
+        toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
+        toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
+    },
+    // v1 spec §13 — `lesson` asset type. Required frontmatter fields are
+    // `description` and `when_to_use`; lint enforces both.
+    lesson: { stashDir: "lessons", ...markdownSpec },
+    // Scheduled tasks. A task file pairs a cron-style schedule with a target
+    // (workflow ref, prompt, or command). Stored as pure YAML under
+    // <stash>/tasks/<id>.yml.
+    task: {
+        stashDir: "tasks",
+        isRelevantFile: (fileName) => path.extname(fileName).toLowerCase() === ".yml",
+        toCanonicalName: (typeRoot, filePath) => {
+            const rel = toPosix(path.relative(typeRoot, filePath));
+            return rel.endsWith(".yml") ? rel.slice(0, -4) : rel;
+        },
+        toAssetPath: (typeRoot, name) => {
+            const withExt = name.endsWith(".yml") ? name : `${name}.yml`;
+            return path.join(typeRoot, withExt);
+        },
+    },
+    // #561 — agent sessions indexed as a first-class searchable asset type.
+    // Generated markdown written by the `extract` pass to
+    // `sessions/<harness>/<session-id>.md`.
+    session: { stashDir: "sessions", ...markdownSpec },
+    // Durable stash-level semantic knowledge — facts about the user, team, or
+    // project. A plain markdown spec; see docs/architecture/specs/fact-asset-type.md.
+    fact: { stashDir: "facts", ...markdownSpec },
+};
+const _placementKeysSubsetOfKnownTypes = true;
+void _placementKeysSubsetOfKnownTypes;
+const PLACEMENT_SPECS = { ...BUILTIN_PLACEMENT_SPECS };
+/** Live placement spec for a type, or `undefined` for an unknown type. */
+export function placementSpecFor(type) {
+    return PLACEMENT_SPECS[type];
+}
+/** Every registered placement spec (for whole-registry sweeps). */
+export function placementSpecList() {
+    return Object.values(PLACEMENT_SPECS);
+}
+/** Every registered placement type key (the set of types that have a stash subdir). */
+export function placementTypes() {
+    return Object.keys(PLACEMENT_SPECS);
+}
+/** The stash subdir a type places into, or `undefined` for an unknown type. */
+export function stashDirFor(type) {
+    return PLACEMENT_SPECS[type]?.stashDir;
+}
+/**
+ * Reverse of {@link stashDirFor}: the placement type owning a stash subdir, or
+ * `undefined` when no registered type places into it. The type→subdir map is a
+ * bijection over the built-in types (each type has a distinct subdir), so this
+ * is the well-defined inverse used to project a path-based conceptId onto the
+ * asset-type metadata required by native adapters.
+ */
+export function typeForStashDir(stashDir) {
+    for (const [type, spec] of Object.entries(PLACEMENT_SPECS)) {
+        if (spec.stashDir === stashDir)
+            return type;
+    }
+    return undefined;
+}
+/** All stash subdir names across the registered types. */
+export function stashDirNames() {
+    return Object.values(PLACEMENT_SPECS).map((spec) => spec.stashDir);
+}
+/**
+ * Mutate the placement registry to add/replace a type's spec. Used by the
+ * custom-asset-type registration surface (extension types); built-ins are
+ * baked into {@link PLACEMENT_SPECS} above.
+ */
+export function registerAssetSpec(type, spec) {
+    PLACEMENT_SPECS[type] = spec;
+}
+/** Remove a previously-registered type's spec. */
+export function deregisterAssetSpec(type) {
+    delete PLACEMENT_SPECS[type];
+}
+export function isRelevantAssetFile(assetType, fileName) {
+    return PLACEMENT_SPECS[assetType]?.isRelevantFile(fileName) ?? false;
+}
+export function deriveCanonicalAssetName(assetType, typeRoot, filePath) {
+    return PLACEMENT_SPECS[assetType]?.toCanonicalName(typeRoot, filePath);
+}
+export function deriveCanonicalAssetNameFromStashRoot(assetType, stashRoot, filePath) {
+    const relPath = toPosix(path.relative(stashRoot, filePath));
+    const segments = relPath.split("/").filter(Boolean);
+    const firstSegment = segments[0];
+    // When the first segment matches the canonical type dir (e.g. "agents"),
+    // use it as the type root so canonical names are relative to it.
+    // Otherwise fall back to stashRoot — this preserves the full relative path
+    // as the canonical name, which is correct for installed stashes that live
+    // under custom directories (e.g. "tools/agents/svelte-file-editor").
+    const typeRoot = firstSegment !== undefined && firstSegment === stashDirFor(assetType)
+        ? path.join(stashRoot, firstSegment)
+        : stashRoot;
+    return deriveCanonicalAssetName(assetType, typeRoot, filePath);
+}
+export function assetPathForName(assetType, typeRoot, name) {
+    const spec = PLACEMENT_SPECS[assetType];
+    if (!spec)
+        throw new Error(`Unknown asset type: "${assetType}"`);
+    return spec.toAssetPath(typeRoot, name);
+}

package/dist/core/asset/asset-ref.js

@@ -2,104 +2,135 @@
 // 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/.
 import path from "node:path";
-import { isAssetType } from "../common.js";
 import { UsageError } from "../errors.js";
-/** Accepted spelling aliases mapping to a canonical asset type. */
-const TYPE_ALIASES = {
-    environment: "env",
-};
-// ── Construction ────────────────────────────────────────────────────────────
+// ── Validation ──────────────────────────────────────────────────────────────
+function validateName(name) {
+    if (!name)
+        throw new UsageError("Empty asset name.", "MISSING_REQUIRED_ARGUMENT");
+    if (name.includes("\0"))
+        throw new UsageError("Null byte in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    if (/^[A-Za-z]:/.test(name))
+        throw new UsageError("Windows drive path in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    const slashName = name.replace(/\\/g, "/");
+    if (slashName === ".." || slashName.startsWith("../")) {
+        throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (slashName.split("/").some((seg) => seg === "." || seg === "..")) {
+        throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    const normalized = path.posix.normalize(slashName);
+    if (path.posix.isAbsolute(normalized))
+        throw new UsageError("Absolute path in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    }
+}
+function normalizeName(name) {
+    return path.posix.normalize(name.replace(/\\/g, "/"));
+}
 /**
- * Build a ref string from components.
+ * Bundle slug charset (spec §3.4): non-empty, and excluding `:`/`.`/`#`/`/`
+ * plus whitespace. Excluding `:`/`.` is what keeps `bundle//conceptId` lexically
+ * distinguishable from a URL in prose; excluding `/` is what makes the first
+ * `//` an unambiguous bundle boundary; excluding `#` reserves it for fragments.
+ */
+const BUNDLE_SLUG_RE = /^[^\s:.#/]+$/;
+/**
+ * True when `s` is a legal bundle slug (spec §11.1 / D-R5 charset: non-empty,
+ * no `:`/`.`/`#`/`/` or whitespace). Exported for input boundaries that need
+ * to distinguish bundle-qualified refs from source locators.
+ */
+export function isBundleSlug(s) {
+    return BUNDLE_SLUG_RE.test(s);
+}
+/**
+ * Body-ref recognition (prose): the FULLY-QUALIFIED anchored form ONLY
+ * (`<bundle>//<concept-id>[#<fragment>]`, spec §11.1 — the short form is never
+ * recognized in prose). `g`/`m` for scanning; group 1 = the whole ref token.
  *
- * Examples:
- *   makeAssetRef("script", "deploy.sh")
- *     → "script:deploy.sh"
- *   makeAssetRef("script", "deploy.sh", "npm:@scope/pkg")
- *     → "npm:@scope/pkg//script:deploy.sh"
- *   makeAssetRef("skill", "code-review", "local")
- *     → "local//skill:code-review"
- *   makeAssetRef("script", "db/migrate/run.sh", "owner/repo")
- *     → "owner/repo//script:db/migrate/run.sh"
+ * The leading `//` must be preceded by a bundle slug, so a URL (`https://…`,
+ * `//cdn.example.com/…`) never matches: a scheme carries a `:` before `//`
+ * (excluded from the slug), and a scheme-relative `//host` has no slug before
+ * its `//` at all. The bundle-slug charset here additionally excludes the prose
+ * boundary punctuation (brackets/parens/quotes/backtick/comma/angle) so a
+ * leading boundary char (e.g. the `[` of a markdown link) is not absorbed into
+ * the slug. The concept segment reuses the same terminator charset as the
+ * body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
+ * `.`, and a trailing `#fragment`.
  */
-export function makeAssetRef(type, name, origin) {
-    validateName(name);
-    const normalized = normalizeName(name);
-    const asset = `${type}:${normalized}`;
-    if (!origin)
-        return asset;
-    return `${origin}//${asset}`;
+export const BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]+)/gm;
+/** NFC-normalize + traversal/null-byte/drive-letter guard + path-normalize a concept id. */
+function normalizeConceptId(raw) {
+    const nfc = raw.normalize("NFC");
+    if (nfc.includes("#")) {
+        throw new UsageError("`#` is reserved for the export fragment in a concept id.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    validateName(nfc);
+    return normalizeName(nfc);
 }
 /**
- * Serialize a parsed {@link AssetRef} value-object back to its canonical
- * `[origin//]type:name` string form. The single formatter for refs — call
- * this instead of hand-building `${type}:${name}` template strings so the
- * serialization rules (origin prefix, name normalization) live in one place
- * and stay in lockstep with {@link parseAssetRef}.
+ * Build a fully-qualified (or short) bundle ref string from its components.
  *
- * `refToString(parseAssetRef(s))` round-trips for any `s` that
- * `parseAssetRef` accepts.
+ * Examples:
+ *   makeBundleRef(undefined, "knowledge/http-caching")   → "knowledge/http-caching"
+ *   makeBundleRef("core", "knowledge/http-caching")      → "core//knowledge/http-caching"
+ *   makeBundleRef("core", "skills/review", "usage")      → "core//skills/review#usage"
  */
-export function refToString(ref) {
-    return makeAssetRef(ref.type, ref.name, ref.origin);
+export function makeBundleRef(bundle, conceptId, fragment) {
+    const normalized = normalizeConceptId(conceptId);
+    let out = normalized;
+    if (bundle) {
+        if (!BUNDLE_SLUG_RE.test(bundle)) {
+            throw new UsageError(`Invalid bundle slug "${bundle}". A bundle slug may not contain ':', '.', '#', '/', or whitespace.`, "MISSING_REQUIRED_ARGUMENT");
+        }
+        out = `${bundle}//${normalized}`;
+    }
+    if (fragment)
+        out = `${out}#${fragment}`;
+    return out;
 }
-// ── Parsing ─────────────────────────────────────────────────────────────────
 /**
- * Parse a ref string in the format `[origin//]type:name`.
+ * Serialize a parsed {@link BundleRef} back to its canonical
+ * `[bundle//]conceptId[#fragment]` string form — the single formatter for the
+ * 0.9.0 grammar (call this instead of hand-building `${bundle}//${conceptId}`).
+ * `bundleRefToString(parseBundleRef(s))` round-trips for any `s` that
+ * `parseBundleRef` accepts.
  */
-export function parseAssetRef(ref) {
+export function bundleRefToString(ref) {
+    return makeBundleRef(ref.bundle, ref.conceptId, ref.fragment);
+}
+/**
+ * Parse a ref string in the 0.9.0 format `[<bundle>//]<concept-id>[#<fragment>]`.
+ * The bundle prefix and the export fragment are both optional; the short form
+ * (no `bundle//`) leaves `bundle` undefined for the caller to resolve against
+ * the containing bundle (§11.1).
+ */
+export function parseBundleRef(ref) {
     const trimmed = ref.trim();
     if (!trimmed)
         throw new UsageError("Empty ref.", "MISSING_REQUIRED_ARGUMENT");
-    let origin;
+    let bundle;
     let body = trimmed;
     const boundary = trimmed.indexOf("//");
     if (boundary >= 0) {
-        origin = trimmed.slice(0, boundary);
+        bundle = trimmed.slice(0, boundary);
         body = trimmed.slice(boundary + 2);
-        if (!origin)
-            throw new UsageError("Empty origin in ref.", "MISSING_REQUIRED_ARGUMENT");
-    }
-    const colon = body.indexOf(":");
-    if (colon <= 0) {
-        throw new UsageError(`Invalid ref "${trimmed}". Expected [origin//]type:name, e.g. skill:deploy or knowledge:guide.md`, "MISSING_REQUIRED_ARGUMENT");
+        if (!bundle)
+            throw new UsageError("Empty bundle in ref.", "MISSING_REQUIRED_ARGUMENT");
+        if (!BUNDLE_SLUG_RE.test(bundle)) {
+            throw new UsageError(`Invalid bundle slug "${bundle}" in ref "${trimmed}". A bundle slug may not contain ':', '.', '#', '/', or whitespace.`, "MISSING_REQUIRED_ARGUMENT");
+        }
     }
-    const rawType = body.slice(0, colon);
-    const rawName = body.slice(colon + 1);
-    // The `vault` asset type was removed in 0.9.0. Point callers at its
-    // replacements rather than failing with a generic unknown-type error.
-    if (rawType === "vault") {
-        throw new UsageError("The `vault` asset type was removed in 0.9.0 — use `env:` (whole .env config) or `secret:` (a single value).", "MISSING_REQUIRED_ARGUMENT");
-    }
-    // Type aliases: `environment:` is an accepted spelling of the canonical
-    // `env:` type.
-    const resolvedType = TYPE_ALIASES[rawType] ?? rawType;
-    if (!isAssetType(resolvedType)) {
-        throw new UsageError(`Invalid asset type: "${rawType}".`, "MISSING_REQUIRED_ARGUMENT");
-    }
-    validateName(rawName);
-    const name = normalizeName(rawName);
-    return { type: resolvedType, name, origin: origin || undefined };
-}
-// ── Validation ──────────────────────────────────────────────────────────────
-function validateName(name) {
-    if (!name)
-        throw new UsageError("Empty asset name.", "MISSING_REQUIRED_ARGUMENT");
-    if (name.includes("\0"))
-        throw new UsageError("Null byte in asset name.", "MISSING_REQUIRED_ARGUMENT");
-    if (/^[A-Za-z]:/.test(name))
-        throw new UsageError("Windows drive path in asset name.", "MISSING_REQUIRED_ARGUMENT");
-    const normalized = path.posix.normalize(name.replace(/\\/g, "/"));
-    if (path.posix.isAbsolute(normalized))
-        throw new UsageError("Absolute path in asset name.", "MISSING_REQUIRED_ARGUMENT");
-    if (normalized === ".." || normalized.startsWith("../")) {
-        throw new UsageError("Path traversal in asset name.", "MISSING_REQUIRED_ARGUMENT");
+    // Export fragment: everything after the first `#` in the concept body.
+    let fragment;
+    const hash = body.indexOf("#");
+    if (hash >= 0) {
+        fragment = body.slice(hash + 1) || undefined;
+        body = body.slice(0, hash);
     }
-    const segments = normalized.split("/");
-    if (segments.some((seg) => seg === "." || seg === "..")) {
-        throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
+    if (!body) {
+        throw new UsageError(`Invalid ref "${trimmed}". Expected [bundle//]conceptId, e.g. knowledge/guide or core//skills/review`, "MISSING_REQUIRED_ARGUMENT");
     }
-}
-function normalizeName(name) {
-    return path.posix.normalize(name.replace(/\\/g, "/"));
+    const conceptId = normalizeConceptId(body);
+    return { bundle: bundle || undefined, conceptId, fragment };
 }

package/dist/core/asset/asset-serialize.js

@@ -45,6 +45,26 @@ import { stringify as yamlStringify } from "yaml";
 export function serializeFrontmatter(frontmatter) {
     return yamlStringify(frontmatter).trimEnd();
 }
+/**
+ * Serialize a frontmatter object with every value `JSON.stringify`-quoted,
+ * without `---` fences and without a trailing newline.
+ *
+ * Use this instead of {@link serializeFrontmatter} when the input is a
+ * pre-validated LLM payload where `yaml.stringify` may emit shapes
+ * (`|`-block scalars, anchors, unquoted multiline) that the project's
+ * hand-rolled `parseFrontmatter` subset parser cannot read back. Every scalar
+ * becomes a quoted JSON literal; arrays become `[<json>, <json>]` (space after
+ * the comma). Field order is preserved from the input's insertion order.
+ *
+ * This is the single home for the "guaranteed-quoted scalars" serializer the
+ * module doc above anticipates; before it, `distill` (array-aware) and
+ * `distill/content-repair` (scalar-only) reimplemented it divergently.
+ */
+export function serializeFrontmatterQuoted(frontmatter) {
+    return Object.entries(frontmatter)
+        .map(([k, v]) => Array.isArray(v) ? `${k}: [${v.map((s) => JSON.stringify(s)).join(", ")}]` : `${k}: ${JSON.stringify(v)}`)
+        .join("\n");
+}
 /**
  * Assemble a complete asset file string from a frontmatter object and a body.
  *