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

package/dist/commands/lint/base-linter.js

@@ -10,7 +10,7 @@
 // `<type>:<slug>` -> on-disk-asset question and MUST agree on the set of
 // reachable refs for any given stash layout.
 //
-// The lock is enforced by `tests/contracts/ref-resolver-contract.test.ts`,
+// The lock is enforced by `tests/integration/contracts/ref-resolver-contract.test.ts`,
 // which drives this implementation through a canonical fixture set. The
 // akm-plugins repo ships an equivalent test that drives its copy through the
 // SAME inputs and asserts identical outcomes. Any change to the resolver
@@ -19,27 +19,24 @@
 //
 // Cases the contract covers (see fixture in the contract test):
 //   - existing memory / knowledge / agent / workflow / skill refs
-//   - knowledge subdirectory layout (knowledge/<category>/<slug>.md)
+//   - namespaced knowledge paths (knowledge/<category>/<slug>.md)
 //   - skill multi-file layout (skills/<slug>/SKILL.md)
-//   - memory `.derived.md` sibling
 //   - namespaced slugs containing `/`
 //   - env (`env/.env`, `env/<name>.env`) and secret (`secrets/<name>`) refs
 //   - non-existent refs
-//   - script type (unresolvable by design — both must return false)
+//   - script paths with explicit extensions
 //
-// As of 0.9 the type alternation in `REF_RE` and the path mapping in
-// `refToRelPath` are DERIVED FROM THE ASSET REGISTRY (`getAssetTypes()` /
-// `resolveAssetPathFromName` in `src/core/asset/asset-spec.ts`) rather than
-// hand-encoded, so they can no longer drift from the registry. The previously
-// hand-listed `vault` type was removed from the registry in 0.9 (replaced by
-// `env`); `vault:` refs are therefore no longer matched here. `env:`/`secret:`
-// refs are now matched and path-resolved. `script` stays unresolvable and
-// `task` keeps its legacy `.md` resolution (see refToRelPath for both).
+// As of 0.9 the path mapping in `refToRelPath` is DERIVED FROM THE PLACEMENT
+// SPECS (`assetPathForName` in `src/core/asset/asset-placement.ts`) rather than
+// hand-encoded, so it can no longer drift from the placement layer. `env`/
+// `secret`, `script`, and `task` refs are path-resolved.
 // ----------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
-import { getAssetTypes, resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
-import { findFenceRegions, findSafeInsertionPoint } from "./markdown-insertion.js";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
+import { BUNDLE_REF_RE } from "../../core/asset/asset-ref.js";
+import { typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
+import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function formatDate(d) {
     const y = d.getFullYear();
@@ -130,52 +127,24 @@ function stripFencedBlocks(body) {
     return lines.join("\n");
 }
 // ── missing-ref helpers ───────────────────────────────────────────────────────
-/**
- * Type alternation for {@link REF_RE}, derived from the asset registry at
- * module load so it can never drift from `ASSET_SPECS`. Longest-first ordering
- * is defensive (no built-in type is a prefix of another, but a future custom
- * `registerAssetType` one might be) so the alternation prefers the longest
- * match. Regex metacharacters are escaped in case a custom type introduces one.
- */
-function buildRefTypeAlternation() {
-    const types = [...getAssetTypes()].sort((a, b) => b.length - a.length);
-    return types.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|");
-}
-// Only the TYPE alternation is registry-derived; the surrounding grammar
-// (boundary prefix, capture group, slug charset) is byte-identical to the
-// legacy hand-written pattern. Deriving the types from `getAssetTypes()` means
-// `env`/`secret` (added in 0.9) are now matched, and the removed `vault` type
-// is not — both follow the registry automatically.
-const REF_RE = new RegExp(`(?:^|[\\s\`"'(])((${buildRefTypeAlternation()}):[^\\s"'\`)\\]>,\\n]+)`, "gm");
 /**
  * Map from ref type to relative path pattern within stashRoot. Returns null to
  * skip (type is unresolvable by the slug walker).
  *
- * Path layout is owned by the asset registry: we resolve through
- * `resolveAssetPathFromName(type, TYPE_DIRS[type], name)` so the linter and the
- * rest of the CLI agree on where an asset lives. Two legacy carve-outs are
- * preserved to keep pre-0.9 behaviour byte-identical:
- *   - `script`: returns null (scripts live in nested dirs with arbitrary
- *     extensions — unresolvable by the slug-based walker, as the contract pins).
- *   - `task`: M1 fix — tasks are stored as `<id>.yml` on disk, so resolve
- *     `task:` refs against `tasks/<id>.yml` to match actual on-disk layout.
+ * Path layout is owned by the placement layer: we resolve through
+ * `assetPathForName(type, stashDirFor(type), name)` so the linter and the
+ * rest of the CLI agree on where an asset lives.
  *
  * Exported for contract testing — see header CONTRACT block.
  */
 export function refToRelPath(refType, refName) {
-    // script is intentionally unresolvable (contract-pinned).
-    if (refType === "script")
-        return null;
-    // M1: tasks are stored as .yml on disk; resolve task: refs against tasks/<id>.yml.
-    if (refType === "task")
-        return path.join(TYPE_DIRS.task ?? "tasks", `${refName}.yml`);
-    const typeDir = TYPE_DIRS[refType];
+    const typeDir = stashDirFor(refType);
     if (!typeDir)
         return null; // unknown type — skip
-    // resolveAssetPathFromName returns a path rooted at the type dir we pass in,
+    // assetPathForName returns a path rooted at the type dir we pass in,
     // i.e. "<typeDir>/<...>" — exactly the stash-relative path this helper has
     // always returned.
-    return resolveAssetPathFromName(refType, typeDir, refName);
+    return assetPathForName(refType, typeDir, refName);
 }
 /**
  * Returns true if `relPath` resolves to a real file (or multi-file directory
@@ -185,114 +154,182 @@ export function refToRelPath(refType, refName) {
  */
 export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
     for (const root of stashRoots) {
-        const absPath = path.join(root, relPath);
-        if (fs.existsSync(absPath))
-            return true;
-        // Multi-file skill layout: directory containing SKILL.md
-        const bareDir = absPath.replace(/\.md$/, "");
-        if (fs.existsSync(bareDir) && fs.existsSync(path.join(bareDir, "SKILL.md")))
-            return true;
-        // .derived.md variant for memory refs
-        if (refType === "memory") {
-            const derivedPath = path.join(root, "memories", `${refName}.derived.md`);
-            if (fs.existsSync(derivedPath))
-                return true;
-        }
-        // Knowledge-specific: search subdirectories like knowledge/projects/, knowledge/tools/, etc.
-        if (refType === "knowledge") {
-            try {
-                const knowledgeDir = path.join(root, "knowledge");
-                if (fs.existsSync(knowledgeDir) && fs.statSync(knowledgeDir).isDirectory()) {
-                    const entries = fs.readdirSync(knowledgeDir, { withFileTypes: true });
-                    for (const entry of entries) {
-                        if (!entry.isDirectory())
-                            continue;
-                        const subPath = path.join(knowledgeDir, entry.name, `${refName}.md`);
-                        if (fs.existsSync(subPath))
-                            return true;
-                    }
-                }
-            }
-            catch {
-                // Ignore errors reading directory
-            }
-        }
-        // Fallback: the refName may already encode the full stash-relative path
-        // (e.g. knowledge:skills/foo/references/bar where the file lives at
-        // <stash>/skills/foo/references/bar.md, not <stash>/knowledge/skills/...).
-        const directPath = path.join(root, `${refName}.md`);
-        if (fs.existsSync(directPath))
-            return true;
-        const directDir = path.join(root, refName);
-        if (fs.existsSync(directDir) && fs.existsSync(path.join(directDir, "SKILL.md")))
+        if (resolveRefPathInStash(relPath, refType, refName, root) !== null)
             return true;
     }
     return false;
 }
 /**
- * Returns an array of {ref, resolvedRelPath} for every local AKM ref in the
- * body that does not resolve to a real file under any of the provided stash roots.
+ * Resolve the on-disk primary file for a ref within a SINGLE stash root, using
+ * the same reachability rules (in the same order) as
+ * {@link refExistsInAnyStash}, which delegates here. Returns the absolute path
+ * of the file that makes the ref "exist" — for a multi-file skill directory
+ * that is its `SKILL.md` primary — or `null` when the ref does not resolve in
+ * this root.
  *
- * Skips false-positive patterns:
- * - Shell variables: memory:$(cmd) or knowledge:${VAR}
- * - ACP type notation: agent::Type (double colons are C++/ACP syntax)
- * - Incomplete/placeholder refs: slug is single character or "**"
+ * Extracted for SPEC-5 (`--supersedes` demotion): write commands need the
+ * superseded asset's actual file to mutate, and forking a second resolver
+ * would drift from lint's. NOT part of the akm-plugins ref-resolver contract
+ * (the contract pins `refToRelPath` + `refExistsInAnyStash`; this is the
+ * shared internal both build on).
  */
-function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
-    const allRoots = [stashRoot, ...extraStashRoots];
+export function resolveRefPathInStash(relPath, _refType, _refName, root) {
+    const absPath = path.join(root, relPath);
+    if (fs.existsSync(absPath))
+        return absPath;
+    return null;
+}
+/**
+ * A `(refType, refName)` pair that is not a lint-checkable local asset ref —
+ * shared skip-guard for recognized `bundle//conceptId` refs. Filters the
+ * false-positive patterns:
+ *   - Shell variables: memory:$(cmd) or knowledge:${VAR} (guarded by callers on
+ *     the raw token, before it is split).
+ *   - Empty names or names that look like absolute paths / home dirs / URLs.
+ *   - Incomplete/placeholder refs: single-character slug or "**".
+ *   - Template placeholder refs like skill:<name> / workflow:<my-workflow>.
+ */
+function isNonRefName(refName) {
+    if (!refName || refName.startsWith("/") || refName.startsWith("~") || refName.startsWith("http"))
+        return true;
+    if (refName.length <= 1 || refName === "**")
+        return true;
+    if (refName.startsWith("<") || refName.includes("<"))
+        return true;
+    return false;
+}
+/**
+ * Resolve a `(refType, refName)` pair against `allRoots`. Returns the resolved
+ * stash-relative path when the ref is MISSING (no file under any root), or
+ * `null` when it resolves, is a skipped/unresolvable type, or is a
+ * non-ref-shaped name. The single existence check both grammars route through.
+ */
+function localRefMissingRelPath(refType, refName, allRoots) {
+    if (isNonRefName(refName))
+        return null;
+    const relPath = refToRelPath(refType, refName);
+    if (relPath === null)
+        return null; // type is skipped / unresolvable
+    return refExistsInAnyStash(relPath, refType, refName, allRoots) ? null : relPath;
+}
+/**
+ * 0.9.0 grammar recognition: fully-qualified `bundle//conceptId` body-refs
+ * (`BUNDLE_REF_RE`, the anchored prose form — spec §11.1 / ref-grammar decision
+ * D-R3). The conceptId is reverse-translated to its legacy `type`/`name` via the
+ * D-R2 static table (`typeNameFromConceptId`) so the SAME on-disk existence
+ * check applies; a conceptId whose leading segment names no known stash-subdir
+ * is not a local asset ref and is skipped (foreign-adapter / cross-bundle prose).
+ */
+function scanBundleRefs(scanBody, allRoots) {
     const missing = [];
+    const re = new RegExp(BUNDLE_REF_RE.source, BUNDLE_REF_RE.flags);
     let match;
-    const re = new RegExp(REF_RE.source, REF_RE.flags);
-    // C1: Strip fenced code blocks so example refs inside ``` are not flagged.
-    const scanBody = stripFencedBlocks(body);
     // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic regex loop
     while ((match = re.exec(scanBody)) !== null) {
-        const fullRef = match[1]; // e.g. "workflow:foo" or "local//workflow:foo"
-        // Skip shell variables: memory:$(cmd) or knowledge:${VAR}
-        if (fullRef.includes("$(") || fullRef.includes("${")) {
-            continue;
-        }
-        // Skip ACP type notation: agent::Type (double colons)
-        if (fullRef.includes("::")) {
-            continue;
-        }
-        // Strip leading "local//" prefix if present
-        let ref = fullRef;
-        if (ref.startsWith("local//")) {
-            ref = ref.slice("local//".length);
-        }
-        else if (fullRef.includes("//")) {
-            // Has a remote origin prefix (e.g. "npm:", "github:", "owner/repo//") — skip
+        const token = match[1]; // e.g. "core//memories/foo"
+        if (token.includes("$(") || token.includes("${") || token.includes("::"))
             continue;
-        }
-        // Skip refs that start with obvious remote prefixes
-        const colonIdx = ref.indexOf(":");
-        if (colonIdx === -1)
+        const boundary = token.indexOf("//");
+        if (boundary < 0)
             continue;
-        const refType = ref.slice(0, colonIdx);
-        const refName = ref.slice(colonIdx + 1);
-        // Guard against empty names or names that look like paths/URLs
-        if (!refName || refName.startsWith("/") || refName.startsWith("~") || refName.startsWith("http")) {
+        const found = classifyConceptRef(token.slice(boundary + 2), allRoots);
+        if (found !== null)
+            missing.push({ ref: token, resolvedRelPath: found });
+    }
+    return missing;
+}
+/**
+ * Map a bare 0.9.0 conceptId (`<stash-subdir>/<name>`, e.g. `memories/foo`) to
+ * its legacy `type`/`name` and run the shared existence check. Returns the
+ * missing relPath, or `null` when it resolves or is not a known local
+ * asset-type prefix. Drops a trailing `#fragment` (export selector) before
+ * mapping.
+ */
+function classifyConceptRef(rawConceptId, allRoots) {
+    const conceptId = rawConceptId.split("#", 1)[0];
+    const parts = typeNameFromConceptId(conceptId);
+    if (parts === undefined)
+        return null; // foreign type / not a local asset ref
+    return localRefMissingRelPath(parts.type, parts.name, allRoots);
+}
+/**
+ * Returns an array of {ref, resolvedRelPath} for every local AKM ref in the
+ * PROSE body that does not resolve to a real file under any of the provided
+ * stash roots. Recognizes the 0.9.0 fully-qualified `bundle//conceptId` grammar
+ * ({@link scanBundleRefs}). Bare short conceptIds are NOT refs in prose (D-R3) —
+ * those are recognized only in the ref-list channels
+ * ({@link checkMissingRefsInList}).
+ */
+function checkMissingRefs(body, stashRoot, extraStashRoots = []) {
+    const allRoots = [stashRoot, ...extraStashRoots];
+    // C1: Strip fenced code blocks so example refs inside ``` are not flagged.
+    const scanBody = stripFencedBlocks(body);
+    return dedupeMissing(scanBundleRefs(scanBody, allRoots));
+}
+/**
+ * Missing-ref check for the REF-LIST channels (frontmatter `refs:` /
+ * `xrefs:` / `supersededBy:` / `contradictedBy:`) where EACH value is a whole
+ * ref, not prose. Unlike the body scan, a bare short conceptId (`memories/foo`)
+ * IS a ref here (the value's whole purpose is to name one asset), so the flipped
+ * short-conceptId frontmatter the 0.9.0 output emits is no longer invisible.
+ * Recognizes, per value:
+ *   - fully-qualified `bundle//conceptId`;
+ *   - bare short `conceptId` (`<stash-subdir>/<name>`).
+ */
+function checkMissingRefsInList(values, stashRoot, extraStashRoots = []) {
+    const allRoots = [stashRoot, ...extraStashRoots];
+    const missing = [];
+    for (const raw of values) {
+        const value = raw.trim();
+        if (!value || value.includes("$(") || value.includes("${") || value.includes("::"))
             continue;
-        }
-        // Skip placeholder/incomplete refs: single character slug or "**"
-        if (refName.length <= 1 || refName === "**") {
+        const boundary = value.indexOf("//");
+        if (boundary >= 0) {
+            // Qualified: `bundle//conceptId` (0.9.0). A colon in the tail marks a
+            // legacy/remote `origin//type:name` — not the new grammar, so skip it.
+            const tail = value.slice(boundary + 2);
+            if (tail.includes(":"))
+                continue;
+            const rel = classifyConceptRef(tail, allRoots);
+            if (rel !== null)
+                missing.push({ ref: value, resolvedRelPath: rel });
             continue;
         }
-        // Skip template placeholder refs like skill:<name> or workflow:<my-workflow>
-        if (refName.startsWith("<") || refName.includes("<")) {
+        // Un-prefixed: a 0.9.0 short `conceptId`. (Post-Chunk-8 the durable
+        // frontmatter xref channel is conceptId-spelled — the legacy `type:name`
+        // ref-list arm is retired.)
+        const rel = classifyConceptRef(value, allRoots);
+        if (rel !== null)
+            missing.push({ ref: value, resolvedRelPath: rel });
+    }
+    return dedupeMissing(missing);
+}
+/** Dedupe missing-ref records by their `ref` token (both arms can flag one ref). */
+function dedupeMissing(rows) {
+    const seen = new Set();
+    const out = [];
+    for (const row of rows) {
+        if (seen.has(row.ref))
             continue;
-        }
-        const relPath = refToRelPath(refType, refName);
-        if (relPath === null)
-            continue; // type is skipped
-        if (!refExistsInAnyStash(relPath, refType, refName, allRoots)) {
-            missing.push({ ref: fullRef, resolvedRelPath: relPath });
-        }
+        seen.add(row.ref);
+        out.push(row);
     }
-    return missing;
+    return out;
 }
 // ── frontmatter refs ─────────────────────────────────────────────────────────
+/**
+ * Frontmatter keys that carry cross-reference lists per the stash
+ * organization conventions: `xrefs:` (provenance / associative links),
+ * `supersededBy:` and `contradictedBy:` (belief-state correction links).
+ * The missing-ref check validates each of these in ADDITION to the body /
+ * `refs:` scan — they are the channel the conventions mandate, and a rename
+ * would otherwise dangle them silently.
+ *
+ * `sources:` is deliberately excluded (non-wiki `sources:` was rejected as a
+ * typed channel; wiki `sources:` is checked by lintWiki). `evidenceSources:` is
+ * excluded because it can point at merged-away or pruned assets.
+ */
+const XREF_FRONTMATTER_KEYS = ["xrefs", "supersededBy", "contradictedBy"];
 /**
  * Return the `refs:` array from frontmatter when it is present and is an
  * array of strings; otherwise return `null` to signal the caller should
@@ -342,6 +379,22 @@ function readRefsArray(value) {
     }
     return out;
 }
+/**
+ * Like {@link readRefsArray} but also accepts a single scalar string,
+ * normalizing it to a one-element list. The indexer's
+ * `normalizeNonEmptyStringList` treats `supersededBy: memory:x` and
+ * `supersededBy: [memory:x]` identically — both are live data — so the
+ * frontmatter xref-channel check must validate both shapes; the array-only
+ * reader silently skipped dangling scalar refs. Returns `null` for any other
+ * type (missing key, number, object) and for a blank scalar.
+ */
+function readRefStringOrArray(value) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? [trimmed] : null;
+    }
+    return readRefsArray(value);
+}
 /**
  * Detect a leading nested frontmatter block in `body` (i.e. a `---\n…\n---`
  * pair that opens within the first few lines of the body). When present,
@@ -407,204 +460,178 @@ function parseInnerFrontmatterBlock(body) {
     }
     return data;
 }
-// ── BaseLinter ────────────────────────────────────────────────────────────────
+// ── Base checks ─────────────────────────────────────────────────────────────
 /**
- * Abstract base class providing the two cross-type checks shared by all asset
- * linters: `unquoted-colon` and `missing-updated`.
+ * The cross-type checks every asset linter runs first: `unquoted-colon`,
+ * `missing-updated`, `stale-path`, and `missing-ref`.
+ *
+ * akm 0.9.0 chunk-3 (plan §12): this was the `BaseLinter.runBaseChecks`
+ * protected method every per-type linter class inherited. Those classes are
+ * gone — the format-generic checks live here as ONE shared function (this), and
+ * the per-`type` extra rules moved to the `akm` adapter's `validate`
+ * (`core/adapter/adapters/akm-lint.ts`). The live `akmLint` command
+ * (`commands/lint/index.ts`) calls this directly, then appends the adapter's
+ * per-type findings.
  *
- * Subclasses call `runBaseChecks(ctx)` and append any type-specific issues.
- * File mutations triggered by base checks are flushed to disk inside this
- * method; subclasses must re-read `ctx.raw` if they need the post-fix content
- * (in practice the base class updates `ctx.raw` in place when `fix` is true).
+ * File mutations triggered by the fixable base checks (`unquoted-colon`,
+ * `missing-updated`) are flushed to disk here when `ctx.fix` is set, and
+ * `ctx.raw` is updated in place so a caller can re-parse the post-fix content.
  */
-export class BaseLinter {
-    /**
-     * Check for missing `name` or `type` fields in frontmatter.
-     *
-     * Returns a detail string if fields are absent/empty, `null` if all present.
-     */
-    checkMissingNameOrType(data, frontmatterText) {
-        if (!frontmatterText)
-            return null;
-        const missingFields = [];
-        if (!("name" in data) || !data.name)
-            missingFields.push("name");
-        if (!("type" in data) || !data.type)
-            missingFields.push("type");
-        if (missingFields.length === 0)
-            return null;
-        return `missing fields: ${missingFields.join(", ")}`;
-    }
-    /**
-     * Validate that the `type` field value is one of an allowed set.
-     *
-     * Returns a detail string if the value is present but invalid, `null` if valid or absent.
-     */
-    checkInvalidTypeValue(data, allowedTypes) {
-        if (!("type" in data) || !data.type)
-            return null; // absent — covered by checkMissingNameOrType
-        const value = String(data.type);
-        if (allowedTypes.includes(value))
-            return null;
-        return `type field has invalid value '${value}'; expected one of: ${allowedTypes.join(", ")}`;
-    }
-    /**
-     * Derive a URL-safe slug from a file path.
-     */
-    suggestSlug(filePath) {
-        return path
-            .basename(filePath, ".md")
-            .toLowerCase()
-            .replace(/[^a-z0-9-]+/g, "-")
-            .replace(/-+/g, "-")
-            .replace(/^-|-$/g, "");
-    }
-    /**
-     * Insert one or more lines into a markdown body at a safe location.
-     *
-     * "Safe" means: not inside a markdown table, HTML table, fenced code block,
-     * or indented code block. If `proposedLineNumber` falls inside one of those
-     * regions, the helper pushes the insertion to immediately after the region.
-     * This is a regression guard against the class of bug where an auto-fix
-     * splits a table fence by injecting a callout between the separator row
-     * and the first data row (broke `knowledge/akm-cli-reference.md` in 0.8.0).
-     *
-     * Subclasses that perform line-based body insertion MUST route through this
-     * helper instead of calling `splice` directly. Insertion fixers must NOT
-     * touch frontmatter — use `fixMissingUpdated` / `fixUnquotedColon` style
-     * regex edits for that case (those already operate inside the `---…---`
-     * fence and don't intersect with body line numbers).
-     *
-     * @param raw                 Full file contents (frontmatter + body).
-     * @param newLines            Lines to insert (without trailing newlines).
-     * @param proposedLineNumber  0-based line index within `raw` where the
-     *                            caller wants the new content to appear.
-     * @returns The mutated file contents with `newLines` spliced at the
-     *          adjusted safe position.
-     */
-    insertLinesSafely(raw, newLines, proposedLineNumber) {
-        const lines = raw.split(/\r?\n/);
-        const safeIdx = findSafeInsertionPoint(lines, proposedLineNumber);
-        lines.splice(safeIdx, 0, ...newLines);
-        return lines.join("\n");
-    }
-    runBaseChecks(ctx) {
-        const issues = [];
-        let currentRaw = ctx.raw;
-        let modified = false;
-        // M8: Parse lint_skip from frontmatter for per-file rule suppression.
-        // Accept both an array (`lint_skip: [missing-ref, stale-path]`) and a
-        // single scalar (`lint_skip: missing-ref`). Non-string entries are coerced
-        // and trimmed so loosely-typed YAML still gates correctly.
-        const rawLintSkip = ctx.data?.lint_skip;
-        const lintSkip = (Array.isArray(rawLintSkip) ? rawLintSkip : rawLintSkip != null ? [rawLintSkip] : [])
-            .map((v) => String(v).trim())
-            .filter(Boolean);
-        const shouldRun = (issueType) => !lintSkip.includes(issueType);
-        // ── 1. unquoted-colon ──────────────────────────────────────────────────
-        if (shouldRun("unquoted-colon")) {
-            const unquotedColonDetail = checkUnquotedColon(ctx.frontmatter);
-            if (unquotedColonDetail) {
-                if (ctx.fix) {
-                    currentRaw = fixUnquotedColon(currentRaw);
-                    modified = true;
-                    issues.push({
-                        file: ctx.relPath,
-                        issue: "unquoted-colon",
-                        detail: unquotedColonDetail,
-                        fixed: true,
-                    });
-                }
-                else {
-                    issues.push({
-                        file: ctx.relPath,
-                        issue: "unquoted-colon",
-                        detail: unquotedColonDetail,
-                        fixed: false,
-                    });
-                }
-            }
-        } // end shouldRun("unquoted-colon")
-        // ── 2. missing-updated ─────────────────────────────────────────────────
-        if (shouldRun("missing-updated") && checkMissingUpdated(ctx.data, ctx.frontmatter)) {
+export function runBaseChecks(ctx) {
+    const issues = [];
+    let currentRaw = ctx.raw;
+    let modified = false;
+    // M8: Parse lint_skip from frontmatter for per-file rule suppression.
+    // Accept both an array (`lint_skip: [missing-ref, stale-path]`) and a
+    // single scalar (`lint_skip: missing-ref`). Non-string entries are coerced
+    // and trimmed so loosely-typed YAML still gates correctly.
+    const rawLintSkip = ctx.data?.lint_skip;
+    const lintSkip = (Array.isArray(rawLintSkip) ? rawLintSkip : rawLintSkip != null ? [rawLintSkip] : [])
+        .map((v) => String(v).trim())
+        .filter(Boolean);
+    const shouldRun = (issueType) => !lintSkip.includes(issueType);
+    // ── 1. unquoted-colon ──────────────────────────────────────────────────
+    if (shouldRun("unquoted-colon")) {
+        const unquotedColonDetail = checkUnquotedColon(ctx.frontmatter);
+        if (unquotedColonDetail) {
             if (ctx.fix) {
-                let mtime;
-                try {
-                    mtime = fs.statSync(ctx.filePath).mtime;
-                }
-                catch {
-                    mtime = new Date();
-                }
-                currentRaw = fixMissingUpdated(currentRaw, mtime);
+                currentRaw = fixUnquotedColon(currentRaw);
                 modified = true;
                 issues.push({
                     file: ctx.relPath,
-                    issue: "missing-updated",
-                    detail: `stamped updated: ${formatDate(mtime)}`,
+                    issue: "unquoted-colon",
+                    detail: unquotedColonDetail,
                     fixed: true,
                 });
             }
             else {
                 issues.push({
                     file: ctx.relPath,
-                    issue: "missing-updated",
-                    detail: "no updated field in frontmatter",
+                    issue: "unquoted-colon",
+                    detail: unquotedColonDetail,
                     fixed: false,
                 });
             }
         }
-        if (modified) {
-            fs.writeFileSync(ctx.filePath, currentRaw, "utf8");
-            // Propagate the mutated raw back so subclasses can re-parse if needed
-            ctx.raw = currentRaw;
-        }
-        // ── 3. stale-path ──────────────────────────────────────────────────────
-        // M3: checkStalePath returns all stale matches; push one issue per path.
-        // M4: Also scan ctx.frontmatter for stale paths (absolute paths in frontmatter).
-        if (shouldRun("stale-path")) {
-            const staleInBody = checkStalePath(ctx.body);
-            const staleInFrontmatter = ctx.frontmatter ? checkStalePath(ctx.frontmatter) : [];
-            for (const candidate of [...staleInBody, ...staleInFrontmatter]) {
-                // M4: Suggest portable replacement when path is under stashRoot.
-                const portableHint = candidate.startsWith(ctx.stashRoot)
-                    ? ` (portable form: $AKM_STASH_DIR${candidate.slice(ctx.stashRoot.length)})`
-                    : "";
-                issues.push({
-                    file: ctx.relPath,
-                    issue: "stale-path",
-                    detail: `nonexistent path: ${candidate}${portableHint}`,
-                    fixed: false,
-                });
+    } // end shouldRun("unquoted-colon")
+    // ── 2. missing-updated ─────────────────────────────────────────────────
+    if (shouldRun("missing-updated") && checkMissingUpdated(ctx.data, ctx.frontmatter)) {
+        if (ctx.fix) {
+            let mtime;
+            try {
+                mtime = fs.statSync(ctx.filePath).mtime;
             }
+            catch {
+                mtime = new Date();
+            }
+            currentRaw = fixMissingUpdated(currentRaw, mtime);
+            modified = true;
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-updated",
+                detail: `stamped updated: ${formatDate(mtime)}`,
+                fixed: true,
+            });
+        }
+        else {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-updated",
+                detail: "no updated field in frontmatter",
+                fixed: false,
+            });
         }
-        // ── 4. missing-ref ─────────────────────────────────────────────────────
-        // Carve-out for assets that declare an explicit `refs:` array in
-        // frontmatter (e.g. session-checkpoint memories captured by the
-        // claude-code hook). The frontmatter array is the *authoritative*
-        // ref list — any ref-shaped tokens in the body are treated as
-        // literal strings (heredocs, grep patterns, JSON values, regex
-        // patterns embedded in tool transcripts). Without this carve-out
-        // every session capture produces a fresh batch of `missing-ref`
-        // flags on every literal `<type>:<slug>` token in a transcript.
+    }
+    if (modified) {
+        fs.writeFileSync(ctx.filePath, currentRaw, "utf8");
+        // Propagate the mutated raw back so subclasses can re-parse if needed
+        ctx.raw = currentRaw;
+    }
+    // ── 3. stale-path ──────────────────────────────────────────────────────
+    // M3: checkStalePath returns all stale matches; push one issue per path.
+    // M4: Also scan ctx.frontmatter for stale paths (absolute paths in frontmatter).
+    if (shouldRun("stale-path")) {
+        const staleInBody = checkStalePath(ctx.body);
+        const staleInFrontmatter = ctx.frontmatter ? checkStalePath(ctx.frontmatter) : [];
+        for (const candidate of [...staleInBody, ...staleInFrontmatter]) {
+            // M4: Suggest portable replacement when path is under stashRoot.
+            const portableHint = candidate.startsWith(ctx.stashRoot)
+                ? ` (portable form: $AKM_BUNDLE_DIR${candidate.slice(ctx.stashRoot.length)})`
+                : "";
+            issues.push({
+                file: ctx.relPath,
+                issue: "stale-path",
+                detail: `nonexistent path: ${candidate}${portableHint}`,
+                fixed: false,
+            });
+        }
+    }
+    // ── 4. missing-ref ─────────────────────────────────────────────────────
+    // Carve-out for assets that declare an explicit `refs:` array in
+    // frontmatter (e.g. session-checkpoint memories captured by the
+    // claude-code hook). The frontmatter array is the *authoritative*
+    // ref list — any ref-shaped tokens in the body are treated as
+    // literal strings (heredocs, grep patterns, JSON values, regex
+    // patterns embedded in tool transcripts). Without this carve-out
+    // every session capture produces a fresh batch of `missing-ref`
+    // flags on every literal `<type>:<slug>` token in a transcript.
+    //
+    // The producer guarantees that entries in `refs:` already resolve
+    // (it validates against the live stash before writing), so we
+    // still run `checkMissingRefs` against the array itself to catch
+    // refs that were valid at capture time but later removed from the
+    // stash.
+    if (shouldRun("missing-ref")) {
+        const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
+        // An explicit `refs:` array is a REF LIST (each value is a whole ref —
+        // short conceptIds included); a bare body is PROSE (anchored refs only).
+        const missingRefs = explicitRefs !== null
+            ? checkMissingRefsInList(explicitRefs, ctx.stashRoot, ctx.extraStashRoots)
+            : checkMissingRefs(ctx.body, ctx.stashRoot, ctx.extraStashRoots);
+        for (const { ref, resolvedRelPath } of missingRefs) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "missing-ref",
+                detail: `missing ref: ${ref} (resolved to ${resolvedRelPath})`,
+                fixed: false,
+            });
+        }
+        // Frontmatter xref channels (xrefs / supersededBy / contradictedBy).
+        // Runs regardless of the `refs:` body-scan carve-out above — that
+        // carve-out governs only the BODY scan (`refs: []` declares "no
+        // outbound refs in the body", not "skip my correction links").
+        // Non-ref-shaped values (URLs, `raw/<slug>`, `<placeholder>`
+        // templates, shell vars) fall out via checkMissingRefs' guards.
         //
-        // The producer guarantees that entries in `refs:` already resolve
-        // (it validates against the live stash before writing), so we
-        // still run `checkMissingRefs` against the array itself to catch
-        // refs that were valid at capture time but later removed from the
-        // stash.
-        if (shouldRun("missing-ref")) {
-            const explicitRefs = extractFrontmatterRefs(ctx.data, ctx.body);
-            const refSource = explicitRefs !== null ? explicitRefs.join("\n") : ctx.body;
-            const missingRefs = checkMissingRefs(refSource, ctx.stashRoot, ctx.extraStashRoots);
-            for (const { ref, resolvedRelPath } of missingRefs) {
-                issues.push({
-                    file: ctx.relPath,
-                    issue: "missing-ref",
-                    detail: `missing ref: ${ref} (resolved to ${resolvedRelPath})`,
-                    fixed: false,
-                });
+        // Gate: runs when the file has a frontmatter block OR when an
+        // authoritative `refs:` list was extracted. On the task/YAML path
+        // (lint/index.ts) ctx.frontmatter is always null and the whole file
+        // IS the body (`body === raw`); the top-level YAML keys land in
+        // ctx.data. Without `refs:` the body scan above already catches ref
+        // values under these keys, so running the pass would double-report —
+        // skip it. With `refs:` present the body scan is suppressed
+        // (refSource is the refs list), so this pass is the ONLY thing that
+        // validates the xref keys — it must run or dangling task xrefs go
+        // unreported. The two cases are mutually exclusive, so no ref is
+        // ever double-reported. Md files without a frontmatter block and
+        // without `refs:` land in the skip branch with empty ctx.data, so
+        // nothing is lost for them either.
+        if (ctx.frontmatter !== null || explicitRefs !== null) {
+            for (const key of XREF_FRONTMATTER_KEYS) {
+                const values = readRefStringOrArray(ctx.data?.[key]);
+                if (values === null)
+                    continue;
+                const missingXrefs = checkMissingRefsInList(values, ctx.stashRoot, ctx.extraStashRoots);
+                for (const { ref, resolvedRelPath } of missingXrefs) {
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "missing-ref",
+                        detail: `missing ref: ${ref} (frontmatter ${key}; resolved to ${resolvedRelPath})`,
+                        fixed: false,
+                    });
+                }
             }
         }
-        return issues;
     }
+    return issues;
 }