akm-cli 0.8.1 → 0.9.0-beta.0

package/dist/{core → commands/improve/memory}/memory-belief.js

@@ -28,8 +28,8 @@
  * - MemOS (arXiv:2507.03724) — formal archive/merge/transition with shared state model
  */
 import fs from "node:fs";
-import { assembleAsset } from "./asset-serialize";
-import { parseFrontmatter } from "./frontmatter";
+import { assembleAsset } from "../../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 // ── Contradiction edge writer ─────────────────────────────────────────────────
 /**
  * Write `contradictedBy` and `beliefState: contradicted` edges to a memory

package/dist/{core → commands/improve/memory}/memory-contradiction-detect.js

@@ -35,11 +35,11 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { chatCompletion, parseEmbeddedJsonResponse } from "../llm/client";
-import { tryLlmFeature } from "../llm/feature-gate";
-import { assembleAsset } from "./asset-serialize";
-import { getDefaultLlmConfig } from "./config";
-import { parseFrontmatter } from "./frontmatter";
+import { assembleAsset } from "../../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { getDefaultLlmConfig } from "../../../core/config/config.js";
+import { chatCompletion, parseEmbeddedJsonResponse } from "../../../llm/client.js";
+import { tryLlmFeature } from "../../../llm/feature-gate.js";
 // ── Constants ────────────────────────────────────────────────────────────────
 /**
  * Maximum family size for pairwise contradiction checking. Families larger

package/dist/{core → commands/improve/memory}/memory-improve.js

@@ -3,10 +3,10 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { makeAssetRef, parseAssetRef } from "./asset-ref";
-import { assembleAsset } from "./asset-serialize";
-import { firstString, groupBy, stringArray } from "./common";
-import { parseFrontmatter } from "./frontmatter";
+import { makeAssetRef, parseAssetRef } from "../../../core/asset/asset-ref.js";
+import { assembleAsset } from "../../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { firstString, groupBy, stringArray } from "../../../core/common.js";
 const DERIVED_SUFFIX = ".derived";
 export function analyzeMemoryCleanup(stashDir, options = {}) {
     const records = collectDerivedMemories(stashDir, options.parentRef);

package/dist/commands/{reflect.js → improve/reflect.js}

@@ -24,27 +24,28 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { parseAssetRef } from "../core/asset-ref";
-import { assembleAssetFromString, serializeFrontmatter } from "../core/asset-serialize";
-import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
-import { ConfigError, UsageError } from "../core/errors";
-import { appendEvent, readEvents } from "../core/events";
-import { parseFrontmatter } from "../core/frontmatter";
-import { lintLessonContent } from "../core/lesson-lint";
-import { stripMarkdownFences } from "../core/markdown";
-import { checkReflectSize } from "../core/proposal-quality-validators";
-import { createProposal, isProposalSkipped, listProposals, } from "../core/proposals";
-import { lookup } from "../indexer/indexer";
-import { runAgent, } from "../integrations/agent";
-import { resolveProcessAgentProfile } from "../integrations/agent/config";
-import { buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../integrations/agent/prompts";
-import { resolveImproveProcessRunnerFromProfile } from "../integrations/agent/runner";
-import { runOpencodeSdk } from "../integrations/agent/sdk-runner";
-import { chatCompletion } from "../llm/client";
-import { isLlmFeatureEnabled } from "../llm/feature-gate";
-import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "./agent-support";
-import { deriveLessonRef, runLessonQualityJudge } from "./distill";
+import { assertNever } from "../../core/assert.js";
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { stripMarkdownFences } from "../../core/asset/markdown.js";
+import { resolveStashDir } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { appendEvent, readEvents } from "../../core/events.js";
+import { lintLessonContent } from "../../core/lesson-lint.js";
+import { lookup } from "../../indexer/indexer.js";
+import { runAgent, } from "../../integrations/agent/index.js";
+import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
+import { buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm, runnerSupportsFileWrite, } from "../../integrations/agent/runner.js";
+import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
+import { chatCompletion } from "../../llm/client.js";
+import { isLlmFeatureEnabled } from "../../llm/feature-gate.js";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
+import { checkReflectSize } from "../proposal/validators/proposal-quality-validators.js";
+import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
+import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -76,7 +77,7 @@ const MAX_REJECTED_PROPOSALS = 3;
  * Asset types that reflect is allowed to operate on.
  *
  * Reflect's canonical output shape is `frontmatter + markdown body`. Running it
- * against types whose on-disk form is NOT markdown (executable scripts, vault
+ * against types whose on-disk form is NOT markdown (executable scripts, env files
  * env files, YAML tasks) blindly prepends `---\n…\n---\n` to the asset and
  * breaks the runtime contract — for example a `.ts` script with a YAML preamble
  * is a TypeScript syntax error.
@@ -614,7 +615,7 @@ export async function akmReflect(options = {}) {
         parsedRef = parseAssetRef(options.ref);
         // 2a. Type guard — reflect only operates on asset types whose canonical
         // shape is `frontmatter + markdown body`. Refuse non-markdown types
-        // (script / vault / task) up-front so reflect never prepends YAML to a
+        // (script / env / task) up-front so reflect never prepends YAML to a
         // `.ts` file or rewrites a `.env` blob as prose. See REFLECT_ALLOWED_TYPES.
         if (!REFLECT_ALLOWED_TYPES.has(parsedRef.type)) {
             // Deterministic type-guard rejection — the LLM is never invoked. Emit
@@ -707,10 +708,10 @@ export async function akmReflect(options = {}) {
     }
     // Derive a display name for logging — either from the resolved profile or the runnerSpec.
     const resolvedProfileName = profile?.name ??
-        (runnerSpec?.kind === "llm"
+        (runnerSpec && runnerIsLlm(runnerSpec)
             ? `llm:${runnerSpec.connection.model}`
-            : runnerSpec?.kind !== undefined
-                ? `${runnerSpec.kind}:${runnerSpec.profile?.name ?? "unknown"}`
+            : runnerSpec
+                ? `${runnerSpec.kind}:${runnerSpec.profile.name ?? "unknown"}`
                 : "unknown");
     // 4. Build the shared prompt inputs — feedback, hints, lessons, rejected
     // proposals. These are stable across refinement iterations; only the
@@ -739,7 +740,7 @@ export async function akmReflect(options = {}) {
     // `profile.sdkMode` fallback also runs the SDK so it counts as file-writable.
     // Test seams (`options.runAgentOptions.spawn`) emulate agent CLI behaviour so
     // they participate as well — tests opt out by simply not writing the file.
-    const runnerSupportsFileWrite = runnerSpec ? runnerSpec.kind !== "llm" : true;
+    const canRunnerWriteFile = runnerSpec ? runnerSupportsFileWrite(runnerSpec) : true;
     // Initialized to a sentinel; always overwritten in the first loop iteration
     // (maxRefineIters is clamped to >= 1 above). TypeScript cannot prove a
     // for-loop always runs at least once, so we use a type assertion here.
@@ -775,7 +776,7 @@ export async function akmReflect(options = {}) {
         for (let iter = 0; iter < maxRefineIters; iter++) {
             // Synthesize a fresh tmp path per iteration so refinement passes never
             // clobber an earlier draft (and so reading back is unambiguous).
-            const iterDraftPath = runnerSupportsFileWrite ? synthesizeReflectDraftPath(options.ref) : undefined;
+            const iterDraftPath = canRunnerWriteFile ? synthesizeReflectDraftPath(options.ref) : undefined;
             if (iterDraftPath) {
                 draftPathsToCleanup.push(iterDraftPath);
                 lastDraftPath = iterDraftPath;
@@ -853,6 +854,10 @@ export async function akmReflect(options = {}) {
                             ...(runnerSpec.timeoutMs !== undefined ? { timeoutMs: runnerSpec.timeoutMs } : {}),
                         });
                         break;
+                    default:
+                        // Exhaustiveness arm (H1): a 4th RunnerSpec kind becomes a compile
+                        // error here instead of leaving `iterResult` unassigned at runtime.
+                        assertNever(runnerSpec);
                 }
             }
             else {

package/dist/commands/improve/session-asset.js

@@ -0,0 +1,248 @@
+// 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/.
+/**
+ * Session asset generation for the `extract` pass (#561).
+ *
+ * After the extractor distills memory proposals from a session, it ALSO writes
+ * the session itself to the stash as a first-class `session` asset so any agent
+ * — on any harness — can discover prior work via `akm search` / `akm curate`.
+ *
+ * Design constraints (see #561):
+ *   - ADDITIVE + FAIL-OPEN + CONFIG-GATED. Disabled (or no LLM provider) →
+ *     extract behaves EXACTLY as before. Nothing is written.
+ *   - The LLM summary call routes through the injectable {@link SessionSummaryGenerator}
+ *     seam so tests never touch a real provider, and so production wraps the
+ *     call in the existing `tryLlmFeature` fail-open pattern.
+ *   - The `log_path` + `access` frontmatter fields are the durable correlation
+ *     key — they survive index rebuilds (the body is re-derived from disk).
+ *
+ * The asset is written to `sessions/<harness>/<session-id>.md`; the registered
+ * `session` asset type (see `asset-spec.ts`) makes the normal index pass pick it
+ * up for FTS + vector search with no special-casing.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { assembleAsset } from "../../core/asset/asset-serialize.js";
+import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { normalizeHarnessId } from "../../integrations/harnesses/index.js";
+/**
+ * JSON Schema for the session-summary LLM call. Strict so providers that
+ * support schema enforcement constrain the output upstream; the parser only
+ * has to handle the happy path. `additionalProperties: false` drops any
+ * hallucinated keys before parsing.
+ */
+export const SESSION_SUMMARY_JSON_SCHEMA = {
+    type: "object",
+    required: ["summary", "key_topics"],
+    additionalProperties: false,
+    properties: {
+        summary: { type: "string" },
+        key_topics: { type: "array", items: { type: "string" } },
+        tags: { type: "array", items: { type: "string" } },
+    },
+};
+/**
+ * Render a compact transcript snippet from session events for the summary
+ * prompt. Mirrors the extract transcript format but caps total length so the
+ * summary prompt stays bounded regardless of session size.
+ */
+function renderTranscriptForSummary(events, maxChars = 12_000) {
+    if (events.length === 0)
+        return "(empty — no events)";
+    const lines = [];
+    let total = 0;
+    for (const e of events) {
+        const role = e.role ?? "unknown";
+        const text = e.text.trim();
+        if (!text)
+            continue;
+        const line = `[${role}] ${text}`;
+        if (total + line.length > maxChars)
+            break;
+        lines.push(line);
+        total += line.length + 2;
+    }
+    return lines.join("\n\n") || "(empty — no textual events)";
+}
+/**
+ * Build the user prompt for the session-summary LLM call. Pure — no IO. The
+ * model is asked for a dense 2–4 sentence summary plus key topics, optimised
+ * for semantic search recall.
+ */
+export function buildSessionSummaryPrompt(data) {
+    const ref = data.ref;
+    const startedAt = isoOrUndefined(ref.startedAt) ?? "unknown";
+    const endedAt = isoOrUndefined(ref.endedAt) ?? "unknown";
+    return [
+        "You are summarizing an agent coding session so it can be found later via semantic search.",
+        "Write a DENSE 2–4 sentence summary of what was worked on, the key decisions made, and the outcomes.",
+        "Then list the concrete entities touched: files, GitHub issues/PRs, commands, concepts, and people.",
+        "Optimise the summary for recall — include the specific nouns an agent would search for.",
+        "",
+        `Harness: ${ref.harness}`,
+        `Project: ${ref.projectHint ?? "(unknown)"}`,
+        `Started: ${startedAt}  Ended: ${endedAt}`,
+        `Title: ${ref.title ?? "(none)"}`,
+        "",
+        "Transcript:",
+        renderTranscriptForSummary(data.events),
+        "",
+        'Respond as JSON: {"summary": string, "key_topics": string[], "tags"?: string[]}.',
+    ].join("\n");
+}
+/**
+ * Parse the session-summary LLM response into a {@link SessionSummaryResult}.
+ * Defensive: tolerates prose preamble/postamble around the JSON, and returns
+ * `undefined` when nothing usable parses (fail-open: no asset is written).
+ */
+export function parseSessionSummary(raw) {
+    if (!raw || raw.trim().length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        const start = raw.indexOf("{");
+        const end = raw.lastIndexOf("}");
+        if (start === -1 || end <= start)
+            return undefined;
+        try {
+            parsed = JSON.parse(raw.slice(start, end + 1));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (!parsed || typeof parsed !== "object")
+        return undefined;
+    const obj = parsed;
+    const summary = typeof obj.summary === "string" ? obj.summary.trim() : "";
+    if (summary.length === 0)
+        return undefined;
+    const keyTopics = Array.isArray(obj.key_topics)
+        ? obj.key_topics.filter((t) => typeof t === "string" && t.trim().length > 0)
+        : [];
+    const tags = Array.isArray(obj.tags)
+        ? obj.tags.filter((t) => typeof t === "string" && t.trim().length > 0)
+        : undefined;
+    return { summary, keyTopics, ...(tags && tags.length > 0 ? { tags } : {}) };
+}
+/**
+ * Decide whether a session is long enough to index. `minDurationMinutes <= 0`
+ * disables the gate. When either timestamp is missing we DON'T gate it out —
+ * fail-open toward indexing, since a missing timestamp is not evidence of a
+ * trivial session.
+ */
+export function sessionMeetsDurationGate(data, minDurationMinutes) {
+    if (!Number.isFinite(minDurationMinutes) || minDurationMinutes <= 0)
+        return true;
+    const { startedAt, endedAt } = data.ref;
+    if (typeof startedAt !== "number" || typeof endedAt !== "number")
+        return true;
+    const durationMinutes = (endedAt - startedAt) / 60_000;
+    return durationMinutes >= minDurationMinutes;
+}
+/**
+ * Build per-harness `access` instructions for reading the raw session log.
+ *
+ * Documented convention (#561, checklist item "Document `access` field
+ * convention per harness"): the string tells a downstream agent exactly how to
+ * read and parse the log at `log_path`. New harnesses fall back to a generic
+ * `cat <log_path>` hint, which is always correct for a file-backed log.
+ */
+export function buildSessionAccessInstructions(harness, logPath) {
+    const canonical = normalizeHarnessId(harness);
+    if (canonical === "claude") {
+        return [
+            `Read with: cat ${logPath}`,
+            `Parse messages: jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ${logPath}`,
+        ].join("\n");
+    }
+    if (canonical === "opencode") {
+        return [
+            `Read with: cat ${logPath}`,
+            `The log is opencode session storage (JSON). Inspect with: jq '.' ${logPath}`,
+        ].join("\n");
+    }
+    // Generic fallback — file-backed logs are always readable with cat.
+    return `Read with: cat ${logPath}`;
+}
+/** ISO-8601 (UTC) from a ms-epoch, or undefined when absent/non-finite. */
+function isoOrUndefined(ms) {
+    return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
+}
+/** Default session-name slug: `<harness>-session-<yyyy-mm-dd>-<shortId>`. */
+export function buildSessionAssetName(harness, sessionId, startedAtMs) {
+    const canonical = normalizeHarnessId(harness);
+    const datePart = isoOrUndefined(startedAtMs)?.slice(0, 10) ?? "unknown-date";
+    const shortId = sessionId.slice(0, 8);
+    return `${canonical}-session-${datePart}-${shortId}`;
+}
+/**
+ * Assemble the full session asset (frontmatter + `## Summary` / `## Key topics`).
+ * Pure — no IO. Returns the serialized markdown string.
+ */
+export function buildSessionAssetContent(data, summary) {
+    const ref = data.ref;
+    const harness = ref.harness;
+    const startedAt = isoOrUndefined(ref.startedAt);
+    const endedAt = isoOrUndefined(ref.endedAt);
+    const name = buildSessionAssetName(harness, ref.sessionId, ref.startedAt);
+    const logPath = ref.filePath;
+    const baseTags = ["session", normalizeHarnessId(harness)];
+    const extraTags = (summary.tags ?? []).filter((t) => typeof t === "string" && t.trim().length > 0);
+    const tags = Array.from(new Set([...baseTags, ...extraTags]));
+    const frontmatter = {
+        name,
+        type: "session",
+        harness,
+        session_id: ref.sessionId,
+        ...(startedAt ? { started_at: startedAt } : {}),
+        ...(endedAt ? { ended_at: endedAt } : {}),
+        ...(ref.projectHint ? { project: ref.projectHint } : {}),
+        log_path: logPath,
+        access: buildSessionAccessInstructions(harness, logPath),
+        tags,
+    };
+    const topics = summary.keyTopics
+        .filter((t) => typeof t === "string" && t.trim().length > 0)
+        .map((t) => `- ${t.trim()}`)
+        .join("\n");
+    const body = `## Summary\n\n${summary.summary.trim()}\n\n## Key topics\n\n${topics || "- (none extracted)"}\n`;
+    // `description` is duplicated into frontmatter so the metadata pass surfaces
+    // it without re-reading the body — matches how other content types behave.
+    const content = assembleAsset({ ...frontmatter, description: summary.summary.trim() }, body);
+    return { name, frontmatter, content };
+}
+/** Resolve `<stash>/sessions/<harness>/<session-id>.md`. */
+export function resolveSessionAssetPath(stashDir, harness, sessionId) {
+    const dir = TYPE_DIRS.session ?? "sessions";
+    return path.join(stashDir, dir, normalizeHarnessId(harness), `${sessionId}.md`);
+}
+/**
+ * Generate (via the injected summarizer) and write a session asset to the stash.
+ *
+ * FAIL-OPEN: when the summarizer returns `undefined` (disabled / no LLM /
+ * error), NOTHING is written and `{ written: false }` is returned. Any write
+ * error is swallowed by the caller — session indexing must NEVER break extract.
+ */
+export async function writeSessionAsset(data, stashDir, generate) {
+    const summary = await generate(data);
+    if (!summary?.summary || summary.summary.trim().length === 0) {
+        return { written: false };
+    }
+    const { content } = buildSessionAssetContent(data, summary);
+    const harness = data.ref.harness;
+    const sessionId = data.ref.sessionId;
+    const filePath = resolveSessionAssetPath(stashDir, harness, sessionId);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, "utf8");
+    return {
+        written: true,
+        filePath,
+        ref: `session:${normalizeHarnessId(harness)}/${sessionId}`,
+        logPath: data.ref.filePath,
+    };
+}

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

@@ -2,7 +2,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `agents/` assets.
  *

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

@@ -18,18 +18,28 @@
 // will fail.
 //
 // Cases the contract covers (see fixture in the contract test):
-//   - existing memory / knowledge / agent / workflow / skill / vault refs
+//   - existing memory / knowledge / agent / workflow / skill refs
 //   - knowledge subdirectory layout (knowledge/<category>/<slug>.md)
 //   - skill multi-file layout (skills/<slug>/SKILL.md)
 //   - memory `.derived.md` sibling
-//   - vault default vs named (.env vs <name>.env)
 //   - 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)
+//
+// 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).
 // ----------------------------------------------------------------------------
 import fs from "node:fs";
 import path from "node:path";
-import { findSafeInsertionPoint } from "./markdown-insertion";
+import { getAssetTypes, resolveAssetPathFromName, TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { findSafeInsertionPoint } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 function formatDate(d) {
     const y = d.getFullYear();
@@ -85,45 +95,53 @@ function checkStalePath(body) {
     return null;
 }
 // ── missing-ref helpers ───────────────────────────────────────────────────────
-const REF_RE = /(?:^|[\s`"'(])((agent|command|knowledge|memory|script|skill|workflow|lesson|task|wiki|vault):[^\s"'`)\]>,\n]+)/gm;
 /**
- * Map from ref type to relative path pattern within stashRoot. Returns null to skip.
+ * 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`: the registry stores tasks as `<id>.yml`, but the missing-ref
+ *     linter has always resolved `task:` refs against `tasks/<id>.md`; that
+ *     behaviour is held constant here (non-env/secret behaviour is unchanged).
  *
  * Exported for contract testing — see header CONTRACT block.
  */
 export function refToRelPath(refType, refName) {
-    switch (refType) {
-        case "agent":
-            return path.join("agents", `${refName}.md`);
-        case "command":
-            return path.join("commands", `${refName}.md`);
-        case "knowledge":
-            return path.join("knowledge", `${refName}.md`);
-        case "memory":
-            return path.join("memories", `${refName}.md`);
-        case "script":
-            return null; // scripts live in nested dirs — skip
-        case "skill":
-            return path.join("skills", refName, "SKILL.md");
-        case "workflow":
-            return path.join("workflows", `${refName}.md`);
-        case "lesson":
-            return path.join("lessons", `${refName}.md`);
-        case "task":
-            return path.join("tasks", `${refName}.md`);
-        case "wiki":
-            return path.join("wikis", `${refName}.md`);
-        case "vault":
-            // Vaults are .env files. The canonical name "default" (or empty) maps to
-            // ".env"; any other name maps to "<name>.env".  This mirrors the vault
-            // asset-spec toAssetPath logic in src/core/asset-spec.ts.
-            if (!refName || refName === "default") {
-                return path.join("vaults", ".env");
-            }
-            return path.join("vaults", `${refName}.env`);
-        default:
-            return null;
-    }
+    // script is intentionally unresolvable (contract-pinned).
+    if (refType === "script")
+        return null;
+    // Preserve the legacy `.md` resolution for tasks.
+    if (refType === "task")
+        return path.join(TYPE_DIRS.task ?? "tasks", `${refName}.md`);
+    const typeDir = TYPE_DIRS[refType];
+    if (!typeDir)
+        return null; // unknown type — skip
+    // resolveAssetPathFromName 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);
 }
 /**
  * Returns true if `relPath` resolves to a real file (or multi-file directory

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

@@ -2,7 +2,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `commands/` assets.
  *

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

@@ -1,7 +1,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Default linter for asset types that have no type-specific rules beyond the
  * base checks (`unquoted-colon`, `missing-updated`).

package/dist/commands/lint/env-key-rules.js

@@ -24,7 +24,7 @@
  *   where the operator legitimately wants to set their editor — accept the
  *   FP and bypass with `--allow-insecure` after review.
  */
-import { listKeys } from "../env";
+import { listKeys } from "../env/env.js";
 // ── Dangerous key set ─────────────────────────────────────────────────────────
 export const DANGEROUS_VAULT_KEYS = new Set([
     // Dynamic linker hijacking (Linux glibc ld.so)

package/dist/commands/lint/index.js

@@ -4,12 +4,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
-import { resolveStashDir } from "../../core/common";
-import { loadConfig } from "../../core/config";
-import { parseFrontmatter } from "../../core/frontmatter";
-import { resolveSourceEntries } from "../../indexer/search-source";
-import { checkVaultForDangerousKeys } from "./env-key-rules";
-import { getLinterForType } from "./registry";
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { resolveStashDir } from "../../core/common.js";
+import { loadConfig } from "../../core/config/config.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { checkEnvForDangerousKeys } from "./env-key-rules.js";
+import { getLinterForType } from "./registry.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 const STASH_SUBDIRS = [
     "agents",
@@ -154,27 +154,21 @@ export function akmLint(options = {}) {
         }
     }
     // ── Env dangerous-key pass ─────────────────────────────────────────────────
-    // Scan every `.env` file under <stashRoot>/env/ (and the deprecated
-    // <stashRoot>/vaults/) across all stash roots for keys that are known to
-    // enable process-execution hijacking. Warn-only — findings go into `flagged`,
-    // never `fixed`.
+    // Scan every `.env` file under <stashRoot>/env/ across all stash roots for
+    // keys that are known to enable process-execution hijacking. Warn-only —
+    // findings go into `flagged`, never `fixed`.
     const envRoots = [stashRoot, ...extraStashRoots];
     for (const root of envRoots) {
-        for (const [subdir, prefix] of [
-            ["env", "env"],
-            ["vaults", "vault"],
-        ]) {
-            const dir = path.join(root, subdir);
-            if (!fs.existsSync(dir))
-                continue;
-            for (const envPath of collectEnvFiles(dir)) {
-                const baseName = path.basename(envPath, ".env");
-                // "default" (or empty) maps to ".env" → <prefix>:default
-                const ref = baseName === "" ? `${prefix}:default` : `${prefix}:${baseName}`;
-                const relPath = path.relative(root, envPath);
-                for (const issue of checkVaultForDangerousKeys(envPath, relPath, ref)) {
-                    flagged.push(issue);
-                }
+        const dir = path.join(root, "env");
+        if (!fs.existsSync(dir))
+            continue;
+        for (const envPath of collectEnvFiles(dir)) {
+            const baseName = path.basename(envPath, ".env");
+            // "default" (or empty) maps to ".env" → env:default
+            const ref = baseName === "" ? "env:default" : `env:${baseName}`;
+            const relPath = path.relative(root, envPath);
+            for (const issue of checkEnvForDangerousKeys(envPath, relPath, ref)) {
+                flagged.push(issue);
             }
         }
     }

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

@@ -1,7 +1,7 @@
 // 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 { BaseLinter } from "./base-linter";
+import { BaseLinter } from "./base-linter.js";
 /**
  * Linter for `knowledge/` assets.
  *