akm-cli 0.9.0-rc.8 → 0.9.0

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

@@ -95,6 +95,7 @@ function recognize(c, file) {
         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,

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

@@ -1,19 +1,21 @@
 // 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, workflowProgramMatcher, } from "../../indexer/walk/matchers.js";
+import { directoryMatcher, extensionMatcher, parentDirHintMatcher, smartMdMatcher } from "../../indexer/walk/matchers.js";
 /**
- * The five builtin matchers, in registration order. The array index IS the
+ * 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.)
+ * 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,
-    workflowProgramMatcher,
 ];
 /**
  * Synchronous reproduction of `file-context.ts#runMatchers`'s arbitration

package/dist/core/adapter/validate-context.js

@@ -0,0 +1,214 @@
+// 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 ONE core {@link ValidateContext} implementation — akm 0.9.0 chunk-2/lint
+ * follow-up ("make `validate()` genuinely load-bearing").
+ *
+ * `BundleAdapter.validate()` (`./bundle-adapter.ts`) is a REQUIRED interface
+ * method whose contract is explicit and normative (`./bundle-adapter.ts:96-100`
+ * / the format-neutral spec §12.1): the adapter MUST NOT write and MUST NOT
+ * read the live filesystem — `ctx` serves the run's on-disk SNAPSHOT WITH the
+ * caller's pending {@link FileChange}s overlaid, plus a read-only `resolveRef`
+ * for link/xref existence. That overlay is meant to be built ONCE, centrally —
+ * "one core overlay implementation, not one per adapter" (the interface's own
+ * words) — so every `validate()` caller shares identical overlay semantics
+ * rather than each hand-rolling its own (as every adapter's own test suite has
+ * done up to now, see e.g. `tests/core/adapter/okf-adapter.test.ts`'s
+ * `overlayCtx`/`diskCtx`).
+ *
+ * The two production callers wired onto this factory:
+ *   - `akm lint`'s non-akm adapter dispatch (`commands/lint/index.ts`) — a
+ *     plain sweep with NO pending changes, so the overlay is empty and every
+ *     read falls straight through to disk.
+ *   - the proposal promotion preflight (`commands/proposal/repository.ts`
+ *     `preflightProposalPromotion`) — the one proposal's own `changes` are the
+ *     overlay, so `validate()` sees the bundle AS IT WOULD LOOK the instant
+ *     after the transaction commits, without that transaction ever touching
+ *     disk.
+ *
+ * ── resolveRef ──
+ *
+ * A bare (unqualified) `conceptId` is resolved as BOTH:
+ *   1. the AKM placement-derived path (`typeNameFromConceptId` + `stashDirFor`
+ *      + `assetPathForName` — the exact derivation `commands/lint/base-linter.ts
+ *      #refToRelPath` already uses for the akm-native `missing-ref` check); and
+ *   2. the DIRECT component-relative spelling (`<conceptId>.md`, and the bare
+ *      `<conceptId>` for an extensionless asset) — the form every non-akm
+ *      adapter's OWN conceptId already IS (OKF: path − `.md`; llm-wiki: same).
+ * A `bundle//conceptId`-qualified ref has its bundle prefix stripped before
+ * resolution — mirroring `base-linter.ts#classifyConceptRef`'s existing
+ * behavior (the legacy resolver has never scoped-by-bundle-name either; it
+ * searches every configured stash root for the bare conceptId). Existence is
+ * checked against the PRIMARY root (with the pending-changes overlay applied)
+ * first, then each extra root (disk only — a pending transaction never
+ * targets more than one bundle).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../asset/asset-placement.js";
+import { typeNameFromConceptId } from "../asset/resolve-ref.js";
+function toPosix(p) {
+    return p.replace(/\\/g, "/");
+}
+/** Build the overlay map, keyed by POSIX path relative to `root`. */
+function buildOverlay(root, changes) {
+    const overlay = new Map();
+    for (const change of changes) {
+        const relKey = toPosix(path.isAbsolute(change.path) ? path.relative(root, change.path) : change.path);
+        if (!relKey || relKey.startsWith(".."))
+            continue; // outside root — not this context's concern
+        if (change.op === "delete") {
+            overlay.set(relKey, null);
+            continue;
+        }
+        if (change.after !== undefined)
+            overlay.set(relKey, change.after);
+    }
+    return overlay;
+}
+function readDisk(absPath) {
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function existsOnDiskOrOverlay(relPath, root, overlay) {
+    const key = toPosix(relPath);
+    // Overlay entries are pending file contents by construction, so a present
+    // non-null entry is always a file.
+    if (overlay?.has(key))
+        return overlay.get(key) !== null;
+    try {
+        // `isFile()`, not `existsSync()`: a ref naming a DIRECTORY (e.g. a
+        // `pages/foo/` dir alongside no `pages/foo.md`) must not count as a
+        // resolved target — that would silently suppress a real
+        // `missing-ref`/`broken-xref` diagnostic.
+        return fs.statSync(path.join(root, relPath)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Refs come from bundle CONTENT (link targets, xrefs, `sources:` entries), so
+ * they are untrusted input. A ref must stay inside the bundle root: reject
+ * absolute paths and any `..` segment before joining, so content can never
+ * probe for existence outside its own bundle (nor report a resolved `path`
+ * pointing there). Mirrors the `isWithin` containment rule the write path
+ * already enforces in `core/write-source.ts`.
+ */
+function refEscapesBundle(conceptId) {
+    if (path.isAbsolute(conceptId) || conceptId.startsWith("/"))
+        return true;
+    return toPosix(conceptId)
+        .split("/")
+        .some((segment) => segment === "..");
+}
+/**
+ * Every on-disk relative path a bare `conceptId` might resolve to: the AKM
+ * placement-derived path (when the leading segment names a known placement
+ * stash-subdir) and the direct component-relative spellings every non-akm
+ * adapter's own conceptId already uses. Order doesn't matter — the caller
+ * checks all of them.
+ */
+function candidateRelPaths(conceptId) {
+    const candidates = [];
+    const parts = typeNameFromConceptId(conceptId);
+    if (parts !== undefined) {
+        const typeDir = stashDirFor(parts.type);
+        if (typeDir !== undefined)
+            candidates.push(assetPathForName(parts.type, typeDir, parts.name));
+    }
+    candidates.push(`${conceptId}.md`);
+    candidates.push(conceptId);
+    return candidates;
+}
+/** Strip an optional `#fragment` (export selector) — never part of the on-disk identity. */
+function stripFragment(ref) {
+    const hashIdx = ref.indexOf("#");
+    return hashIdx >= 0 ? ref.slice(0, hashIdx) : ref;
+}
+/**
+ * Strip an optional `bundle//` qualifier. Mirrors `base-linter.ts
+ * #classifyConceptRef`'s existing behavior: the legacy missing-ref checker has
+ * never resolved a qualifier against a NAMED bundle either — it searches every
+ * configured stash root for the bare conceptId. Keeping that same leniency
+ * here means this resolver's answers agree with today's `akm lint` for every
+ * ref shape that already worked.
+ */
+function stripBundlePrefix(ref) {
+    const boundary = ref.indexOf("//");
+    return boundary >= 0 ? ref.slice(boundary + 2) : ref;
+}
+/**
+ * Build the ONE core {@link ValidateContext}: reads/lookups served from the
+ * on-disk snapshot rooted at `options.root` (+ `options.extraRoots` for
+ * cross-bundle ref existence) WITH `options.changes` overlaid on `options.root`
+ * — never a write, never a live-FS read beyond that snapshot.
+ */
+export function createValidateContext(options) {
+    const root = options.root;
+    const extraRoots = options.extraRoots ?? [];
+    const overlay = buildOverlay(root, options.changes ?? []);
+    async function readFile(p) {
+        // An absolute candidate (e.g. a `stale-path` scan hit, which is always an
+        // absolute host path) bypasses the overlay — it can never name a pending
+        // change's stash-relative path, and reads straight from disk (the base
+        // checks' existing "does this literal absolute path exist" question).
+        if (path.isAbsolute(p))
+            return readDisk(p);
+        const key = toPosix(p);
+        if (overlay.has(key))
+            return overlay.get(key) ?? null;
+        return readDisk(path.join(root, p));
+    }
+    async function list(dir) {
+        const abs = path.isAbsolute(dir) ? dir : path.join(root, dir);
+        const relDir = toPosix(path.isAbsolute(dir) ? path.relative(root, dir) : dir);
+        const names = new Set();
+        try {
+            for (const entry of fs.readdirSync(abs))
+                names.add(entry);
+        }
+        catch {
+            // directory may not exist on disk yet — the overlay can still populate it
+        }
+        const prefix = relDir === "." || relDir === "" ? "" : `${relDir}/`;
+        for (const [key, value] of overlay) {
+            if (prefix.length > 0 && !key.startsWith(prefix))
+                continue;
+            const rest = prefix.length > 0 ? key.slice(prefix.length) : key;
+            if (rest.length === 0 || rest.includes("/"))
+                continue; // only direct children
+            if (value === null)
+                names.delete(rest);
+            else
+                names.add(rest);
+        }
+        return [...names];
+    }
+    async function resolveRef(ref) {
+        const conceptId = stripBundlePrefix(stripFragment(ref)).trim();
+        if (!conceptId)
+            return { exists: false };
+        if (refEscapesBundle(conceptId))
+            return { exists: false };
+        const candidates = candidateRelPaths(conceptId);
+        const roots = [
+            { root, usesOverlay: true },
+            ...extraRoots.map((r) => ({ root: r, usesOverlay: false })),
+        ];
+        for (const { root: candidateRoot, usesOverlay } of roots) {
+            for (const relPath of candidates) {
+                if (existsOnDiskOrOverlay(relPath, candidateRoot, usesOverlay ? overlay : null)) {
+                    return { exists: true, path: path.join(candidateRoot, relPath) };
+                }
+            }
+        }
+        return { exists: false };
+    }
+    return { readFile, list, resolveRef };
+}

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

@@ -0,0 +1,63 @@
+// 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 { localDateStamp } from "../common.js";
+import { UsageError } from "../errors.js";
+import { serializeFrontmatter } from "./asset-serialize.js";
+import { parseFrontmatterBlock, spliceFrontmatterLine } from "./frontmatter.js";
+/**
+ * Ensure an AKM-authored Markdown concept is also a conformant OKF concept.
+ *
+ * Stamps BOTH `type` and `updated`, because both are required of a conformant
+ * document and this is the one chokepoint every `.md` write passes through
+ * (`core/write-source.ts`). Without the `updated` stamp, every asset akm
+ * created for you — `akm remember`, `akm import`, accepted proposals,
+ * authored workflows — was immediately flagged `missing-updated` by akm's own
+ * `akm lint`, so the tool disagreed with itself about its own output.
+ *
+ * An existing `updated` is left alone: this fills a gap, it does not
+ * re-stamp on every write (which would churn timestamps and manufacture
+ * needless diffs in git-backed bundles).
+ *
+ * Source preservation: when the type already matches and the ONLY change is
+ * adding `updated`, the line is spliced into the original block textually —
+ * round-tripping through the YAML serializer would drop user-authored
+ * comments and normalize formatting just to contribute one field. Only a
+ * document whose `type` must actually be corrected takes the re-serialize
+ * path (as it always has).
+ */
+export function ensureAkmMarkdownType(content, type, now = new Date()) {
+    const block = parseFrontmatterBlock(content);
+    if (!block) {
+        return `---\n${serializeFrontmatter({ type, updated: localDateStamp(now) })}\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;
+    const needsUpdated = !("updated" in data);
+    if (data.type === type) {
+        if (!needsUpdated)
+            return content;
+        const spliced = spliceFrontmatterLine(content, `updated: ${localDateStamp(now)}`);
+        if (spliced !== null)
+            return spliced;
+        // Unreachable in practice (parseFrontmatterBlock succeeded above), but a
+        // re-serialized document beats a non-conformant one.
+    }
+    const { type: _priorType, ...rest } = data;
+    const next = { type, ...rest };
+    if (needsUpdated)
+        next.updated = localDateStamp(now);
+    return `---\n${serializeFrontmatter(next)}\n---\n${block.content}`;
+}

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

@@ -46,7 +46,7 @@ const workflowSpec = {
             if (lower.endsWith(ext))
                 return path.join(typeRoot, name);
         }
-        // Probe in priority order — `.md` first for back-compat — and fall back
+        // 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}`);
@@ -60,7 +60,7 @@ 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 (agent:code-reviewer, not agent:code-reviewer.md)
+        // Strip .md extension from canonical names.
         return rel.endsWith(".md") ? rel.slice(0, -3) : rel;
     },
     toAssetPath: (typeRoot, name) => {
@@ -74,7 +74,7 @@ const scriptSpec = {
     toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
     toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
 };
-const PLACEMENT_SPECS = {
+const BUILTIN_PLACEMENT_SPECS = {
     skill: {
         stashDir: "skills",
         isRelevantFile: (fileName) => fileName === "SKILL.md",
@@ -89,6 +89,18 @@ const PLACEMENT_SPECS = {
     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 },
@@ -154,6 +166,9 @@ const PLACEMENT_SPECS = {
     // 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];
@@ -174,9 +189,8 @@ export function stashDirFor(type) {
  * 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 by the Chunk-5 dual-grammar shim to reverse
- * a D-R2 qualified conceptId (`<stash-subdir>/<name>`) back to a legacy
- * `type:name` predicate so NULL-`item_ref` rows stay findable by new refs.
+ * 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)) {

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

@@ -11,16 +11,19 @@ function validateName(name) {
         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, "/"));
+    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");
     }
-    const segments = normalized.split("/");
-    if (segments.some((seg) => seg === "." || seg === "..")) {
-        throw new UsageError("Asset name cannot contain relative path segments.", "MISSING_REQUIRED_ARGUMENT");
-    }
 }
 function normalizeName(name) {
     return path.posix.normalize(name.replace(/\\/g, "/"));
@@ -34,9 +37,8 @@ function normalizeName(name) {
 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 so the dual-grammar input dispatch
- * (`resolve-ref.ts`) can classify a `prefix//tail` token by whether its prefix
- * is a legal bundle slug — the clean legacy-vs-new-grammar discriminator.
+ * 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);
@@ -53,7 +55,7 @@ export function isBundleSlug(s) {
  * 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
- * legacy body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
+ * body-ref scan (whitespace/quotes/brackets/comma/nl), and admits `/`,
  * `.`, and a trailing `#fragment`.
  */
 export const BUNDLE_REF_RE = /(?:^|[\s`"'(,[])([^\s:.#/`"'()[\],<>]+\/\/[^\s"'`)\]>,\n]+)/gm;

package/dist/core/asset/frontmatter-lint.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 { isScalar, parseDocument } from "yaml";
+/**
+ * Report a colon-bearing description only when YAML parsed it as a plain
+ * scalar. Quoted and block scalars may span physical lines and remain valid.
+ */
+export function checkUnquotedDescriptionColon(frontmatterText) {
+    if (!frontmatterText)
+        return null;
+    const document = parseDocument(frontmatterText);
+    const description = document.get("description", true);
+    if (document.errors.length === 0 &&
+        isScalar(description) &&
+        description.type === "PLAIN" &&
+        typeof description.value === "string" &&
+        description.value.includes(":")) {
+        return `description value contains unquoted colon: ${description.value}`;
+    }
+    // Preserve the existing finding for malformed plain scalars that YAML cannot
+    // construct, while letting valid multiline quoted/block scalars pass above.
+    if (document.errors.length > 0) {
+        const line = frontmatterText.split(/\r?\n/).find((candidate) => candidate.startsWith("description:"));
+        const value = line?.slice("description:".length).trim();
+        if (value?.includes(":"))
+            return `description value contains unquoted colon: ${value}`;
+    }
+    return null;
+}

package/dist/core/asset/frontmatter.js

@@ -51,15 +51,11 @@ export function parseFrontmatter(raw) {
     };
 }
 /**
- * Normalize YAML-parsed values to match expected AKM frontmatter types.
+ * Normalize YAML dates to match expected AKM frontmatter types.
  *
- * Two conversions:
- * 1. `Date` → YYYY-MM-DD string: the yaml "core" schema parses bare date
+ * `Date` → YYYY-MM-DD string: the yaml "core" schema parses bare date
  *    scalars like `2026-06-18` as JS Date instances. AKM frontmatter treats
  *    `updated:` and similar fields as plain strings.
- * 2. `null` → `""`: the yaml library parses empty-value keys (`key:` with no
- *    value) as `null`, but AKM callers historically received `""` from the
- *    hand-rolled parser. Convert to preserve backward compatibility.
  */
 function normalizeYamlValues(value) {
     if (value instanceof Date) {
@@ -68,11 +64,9 @@ function normalizeYamlValues(value) {
         const d = String(value.getUTCDate()).padStart(2, "0");
         return `${y}-${m}-${d}`;
     }
-    if (value === null)
-        return "";
     if (Array.isArray(value))
         return value.map(normalizeYamlValues);
-    if (typeof value === "object") {
+    if (value !== null && typeof value === "object") {
         return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, normalizeYamlValues(v)]));
     }
     return value;
@@ -130,6 +124,18 @@ function parseFrontmatterLenient(frontmatter) {
 export function mutateFrontmatter(filePath, mutator) {
     const raw = fs.readFileSync(filePath, "utf8");
     const parsed = parseFrontmatter(raw);
+    if (parsed.frontmatter?.trim()) {
+        let strict;
+        try {
+            strict = yamlParse(parsed.frontmatter);
+        }
+        catch {
+            throw new Error(`Cannot mutate malformed YAML frontmatter in ${filePath}.`);
+        }
+        if (strict === null || typeof strict !== "object" || Array.isArray(strict)) {
+            throw new Error(`Cannot mutate non-mapping YAML frontmatter in ${filePath}.`);
+        }
+    }
     const nextFrontmatter = mutator(parsed);
     if (nextFrontmatter === null)
         return false;
@@ -170,6 +176,28 @@ function countLines(text) {
         return 0;
     return text.split(/\r?\n/).length - 1;
 }
+/**
+ * Insert one `key: value` line just before the closing `---` of an existing
+ * frontmatter block, leaving every other byte — YAML comments, quoting, key
+ * order, line endings — untouched. Returns null when `raw` has no well-formed
+ * block, so callers can fall back to a parse-and-serialize path.
+ *
+ * This is the source-preserving way to ADD a field to user-authored
+ * frontmatter: round-tripping the mapping through the YAML serializer drops
+ * comments and normalizes formatting, which is unacceptable for a write that
+ * only needs to contribute one line. Shared by `ensureAkmMarkdownType`
+ * (stamping `updated:` on write) and lint's `--fix` for `missing-updated`.
+ */
+export function spliceFrontmatterLine(raw, line) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    lines.splice(closeIdx, 0, line);
+    return lines.join("\n");
+}
 /**
  * Parse a YAML scalar value (string, boolean, or number).
  *

package/dist/core/asset/markdown.js

@@ -2,6 +2,34 @@
 // 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 { parseFrontmatter } from "./frontmatter.js";
+/** Stable GitHub-style selector for a Markdown heading. */
+export function markdownHeadingSlug(heading) {
+    return heading
+        .trim()
+        .toLowerCase()
+        .replace(/<[^>]*>/g, "")
+        .replace(/[^\p{L}\p{N}\s_-]+/gu, "-")
+        .replace(/[\s_]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+export function markdownFragmentSlugs(content) {
+    return uniqueHeadingSlugs(parseMarkdownToc(content).headings).filter(Boolean);
+}
+function uniqueHeadingSlugs(headings) {
+    const used = new Set();
+    return headings.map((heading) => {
+        const base = markdownHeadingSlug(heading.text);
+        if (!base)
+            return "";
+        let slug = base;
+        let suffix = 0;
+        while (used.has(slug))
+            slug = `${base}-${++suffix}`;
+        used.add(slug);
+        return slug;
+    });
+}
 // ── Parsing ─────────────────────────────────────────────────────────────────
 export function parseMarkdownToc(content) {
     const lines = content.split(/\r?\n/);
@@ -31,61 +59,22 @@ export function parseMarkdownToc(content) {
 // ── Extraction ──────────────────────────────────────────────────────────────
 export function extractSection(content, heading) {
     const lines = content.split(/\r?\n/);
-    const target = heading.toLowerCase();
-    let startIdx = -1;
-    let startLevel = 0;
-    for (let i = 0; i < lines.length; i++) {
-        const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
-        if (!match)
-            continue;
-        const text = match[2].replace(/\s+#+\s*$/, "").trim();
-        if (text.toLowerCase() === target && startIdx === -1) {
-            startIdx = i;
-            startLevel = match[1].length;
-        }
-        else if (startIdx !== -1 && match[1].length <= startLevel) {
-            return {
-                content: lines.slice(startIdx, i).join("\n"),
-                startLine: startIdx + 1,
-                endLine: i,
-            };
-        }
-    }
-    if (startIdx === -1)
+    const headings = parseMarkdownToc(content).headings;
+    const fragment = heading.trim();
+    const slugIndex = uniqueHeadingSlugs(headings).indexOf(fragment);
+    const exact = slugIndex < 0 ? headings.find((candidate) => candidate.text.toLowerCase() === fragment.toLowerCase()) : undefined;
+    const selected = slugIndex >= 0 ? headings[slugIndex] : exact;
+    if (!selected)
         return null;
+    const next = headings.find((candidate) => candidate.line > selected.line && candidate.level <= selected.level);
+    const startIdx = selected.line - 1;
+    const endIdx = next ? next.line - 1 : lines.length;
     return {
-        content: lines.slice(startIdx).join("\n"),
-        startLine: startIdx + 1,
-        endLine: lines.length,
+        content: lines.slice(startIdx, endIdx).join("\n"),
+        startLine: selected.line,
+        endLine: endIdx,
     };
 }
-export function extractLineRange(content, start, end) {
-    const lines = content.split(/\r?\n/);
-    if (end < start)
-        return "";
-    const s = Math.max(1, Math.min(start, lines.length));
-    const e = Math.min(end, lines.length);
-    return lines.slice(s - 1, e).join("\n");
-}
-export function extractFrontmatterOnly(content) {
-    const parsed = parseFrontmatter(content);
-    return parsed.frontmatter;
-}
-// ── Formatting ──────────────────────────────────────────────────────────────
-export function formatToc(toc) {
-    if (toc.headings.length === 0) {
-        return `(no headings found — ${toc.totalLines} lines total)`;
-    }
-    const lineWidth = String(toc.totalLines).length;
-    const parts = toc.headings.map((h) => {
-        const lineNum = `L${String(h.line).padStart(lineWidth)}`;
-        const indent = "  ".repeat(h.level - 1);
-        const prefix = "#".repeat(h.level);
-        return `${lineNum}  ${indent}${prefix} ${h.text}`;
-    });
-    parts.push(`\n${toc.totalLines} lines total`);
-    return parts.join("\n");
-}
 // ── Fence stripping ──────────────────────────────────────────────────────────
 /**
  * Best-effort fence stripping. Strips `<think>` reasoning blocks emitted by