akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/core/adapter/adapters/akm-workflow-adapter.js

@@ -6,7 +6,7 @@
  *
  * A native akm workflow bundle: Markdown workflow sources.
  *
- * ── validate (spec §6 workflow row) ──
+ * ── validate ──
  *
  * Reuses the akm adapter's per-type workflow checks (shared base checks +
  * `placeholder-stub` + `invalid-workflow-structure`). Delegates to the SAME
@@ -37,8 +37,8 @@ function isReservedDocFile(fileName) {
 }
 /**
  * Recognition gate: any `.md` file in this bundle IS a workflow (this
- * adapter's entire domain is workflows — spec §2.5, "residence under
- * workflows/"), UNLESS its frontmatter declares a DIFFERENT non-empty
+ * adapter's entire domain is workflows), UNLESS its frontmatter declares a
+ * DIFFERENT non-empty
  * `type:` (an explicit opt-out, e.g. a README-shaped doc that wants to be
  * something else). No content sniffing.
  */
@@ -114,8 +114,8 @@ async function validate(c, changes, ctx) {
  * looksLikeRoot). Unlike `isWorkflowFile` (which admits an absent `type:` —
  * the lenient default ONCE a source is already known to be this bundle),
  * this requires an EXPLICIT `type: workflow` — the install-time probe is
- * choosing WHICH adapter owns an unconfigured root among several candidates
- * (spec §1.2), and an incidental `.md` with no frontmatter type at all
+ * choosing WHICH adapter owns an unconfigured root among several candidates,
+ * and an incidental `.md` with no frontmatter type at all
  * (common in an OKF or llm-wiki bundle) must not misclassify that root as
  * akm-workflow's.
  */

package/dist/core/adapter/adapters/claude-adapter.js

@@ -4,7 +4,7 @@
 /**
  * The `claude` tool-directory adapter — akm 0.9.0 format-family work item (#46).
  *
- * Recognizes a Claude Code `.claude` layout (spec §6/§7, real-world:
+ * Recognizes a Claude Code `.claude` layout (real-world:
  * https://code.claude.com/docs/en/claude-directory): a root `CLAUDE.md` →
  * `instruction`, `commands/*.md` → `command`, `agents/*.md` → `agent`,
  * `skills/<name>/SKILL.md` → `skill` (item = the dir; bundled resources abstain),

package/dist/core/adapter/adapters/dotenv-adapter.js

@@ -4,7 +4,7 @@
 /**
  * The `dotenv` adapter — akm 0.9.0 format-family work item (#46).
  *
- * A metadata-only env/secret bundle (spec §6/§7, normative §21.2). REDACTION IS
+ * A metadata-only env/secret bundle. REDACTION IS
  * A HARD CONTRACT keyed on the ADAPTER, never on the open `type` value (a
  * frontmatter `type:` cannot opt out):
  *   - `env/*.env` → `type: env` — only the KEY NAMES are surfaced (on `hints`);
@@ -16,7 +16,7 @@
  * conceptId: env strips `.env`; secret keeps its natural path (including any
  * extension). Neither branch ever writes a value onto the emitted document.
  *
- * ── validate (spec §6 env/secret validation column) ──
+ * ── validate ──
  *
  * The dangerous-key scan (`dangerous-env-key`), reusing the akm adapter's
  * `dangerousEnvKeyDiagnostics` — which preserves the code-grounded narrowness:
@@ -31,6 +31,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { assetPathCandidatesForName, typeForStashDir } from "../../asset/asset-placement.js";
 import { scanEnvKeyNames, toPosix } from "../../common.js";
+import { sensitiveMarkerPath } from "../../sensitive-marker-path.js";
 import { dangerousEnvKeyDiagnostics } from "./akm-lint.js";
 import { hashContent } from "./shared.js";
 /** A dotenv bundle is single-component; its one component is `main`. */
@@ -39,7 +40,7 @@ const COMPONENT_ID = "main";
 const ENV_DIR = "env";
 /** The `secrets/` content subdir (whole-file secrets). */
 const SECRETS_DIR = "secrets";
-/** Non-secret marker suffixes under `secrets/` (spec §6 secret row). */
+/** Non-secret marker suffixes under `secrets/`. */
 const SECRET_SKIP_SUFFIXES = [".lock", ".sensitive"];
 /** Classify a component-root-relative file as env / secret, or null (abstain). */
 function classify(relPath) {
@@ -73,7 +74,7 @@ function classify(relPath) {
  * disagreed about a documented promise.
  */
 function hasSensitiveMarker(absPath, type) {
-    const marker = type === "env" ? absPath.replace(/\.env$/i, ".sensitive") : `${absPath}.sensitive`;
+    const marker = sensitiveMarkerPath(absPath, type === "env" ? "env" : "secret");
     return marker !== absPath && fs.existsSync(marker);
 }
 function conceptIdForPath(type, relativePath) {
@@ -167,8 +168,8 @@ export const dotenvAdapter = {
             return [];
         const primaries = assetPathCandidatesForName(type, path.join(c.root, head), rest);
         const expanded = primaries.flatMap((primary) => type === "env"
-            ? [primary, primary.replace(/\.env$/i, ".sensitive")]
-            : [primary, `${primary}.sensitive`, `${primary}.lock`]);
+            ? [primary, sensitiveMarkerPath(primary, "env")]
+            : [primary, sensitiveMarkerPath(primary, "secret"), `${primary}.lock`]);
         return expanded.map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
     },
     /** The dotenv bundle owns its `env/` + `secrets/` dirs. */

package/dist/core/adapter/adapters/generic-files-adapter.js

@@ -4,16 +4,16 @@
 /**
  * The `generic-files` adapter — akm 0.9.0 format-family work item (#46).
  *
- * The AKM-native FALLBACK family (spec §7). Any leftover file is classified by
- * extension (open-question-5, RESOLVED — maintainer 2026-07):
+ * The AKM-native FALLBACK family. Any leftover file is classified by
+ * extension:
  *   - a SCRIPT_EXTENSIONS extension → `script` (conceptId KEEPS the extension);
  *   - markdown / plain-text → `document` (conceptId STRIPS the extension);
  *   - everything else → `file` (conceptId keeps the extension).
  * Placement is IDENTITY: `document` appends `.md`, `script`/`file` keep their
- * natural path. D-R6 reserved files (`index.md`/`log.md`) are excluded from the
+ * natural path. Reserved files (`index.md`/`log.md`) are excluded from the
  * catch-all so a structural listing is never indexed as a `document`.
  *
- * EXPLICIT-CONFIG ONLY: `generic-files` is never in the §1.2 auto-probe order —
+ * EXPLICIT-CONFIG ONLY: `generic-files` is never in the auto-probe order —
  * a user opts in deliberately — so `looksLikeRoot` NEVER fires. It has no
  * type-specific validators (`validate` runs base checks only).
  *
@@ -83,7 +83,7 @@ async function validate(c, changes, ctx) {
         const raw = change.after ?? (await ctx.readFile(change.path));
         if (typeof raw !== "string")
             continue;
-        // No type-specific validators — base checks only (spec §6 script/document/file rows).
+        // No type-specific validators — base checks only.
         diagnostics.push(...(await runBaseValidateChecks(toPosix(change.path), parseFrontmatter(raw), c.root, ctx)));
     }
     return diagnostics;

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

@@ -39,12 +39,11 @@ export { okfAdapter } from "./okf-adapter.js";
 export { opencodeAdapter } from "./opencode-adapter.js";
 export { websiteSnapshotAdapter } from "./website-snapshot-adapter.js";
 /**
- * Every built-in adapter, frozen in the §1.2 install-time probe order: the first
+ * Every built-in adapter, frozen in the install-time probe order: the first
  * adapter whose `looksLikeRoot` fires claims a root, so MORE-SPECIFIC probes
  * come FIRST. This ARRAY ORDER is the executable probe order (`getAdapters()`
  * returns it verbatim) and is pinned by the conformance suite's ordered-owner
- * matrix — it, not the spec §1.2(3) 5-adapter prose listing, is authoritative
- * for the implemented 11-family set.
+ * matrix, and is authoritative for the implemented 11-family set.
  *
  * Probe-precedence rationale (grounds "cannot shadow the existing three"):
  *
@@ -63,7 +62,7 @@ export { websiteSnapshotAdapter } from "./website-snapshot-adapter.js";
  *    package), `akm-workflow` (a workflow-shaped top-level file), and `akm-task`
  *    (a schedule-bearing top-level `.yml`) carry disjoint, specific markers that
  *    fire on none of the other roots; they come at the front for clarity.
- *  - `generic-files` is EXPLICIT-CONFIG ONLY (§1.2) — its `looksLikeRoot` never
+ *  - `generic-files` is EXPLICIT-CONFIG ONLY — its `looksLikeRoot` never
  *    fires — so it is LAST and can never shadow anything.
  */
 export const BUILTIN_ADAPTERS = Object.freeze([

package/dist/core/adapter/adapters/llm-wiki-adapter.js

@@ -2,14 +2,12 @@
 // 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 first-class `llm-wiki` adapter — akm 0.9.0 chunk-4 (DEV-7 restore).
+ * The first-class `llm-wiki` adapter.
  *
- * The `wiki` ASSET-TYPE dies in chunk 4 (plan §11 Chunk 4 / §7.4), but the LLM
- * Wiki structure stays first-class as its OWN adapter. This relocates the
- * native wiki semantics from the retired `src/wiki/` module into a
- * `BundleAdapter` implementing `docs/architecture/specs/akm-0.9.0-bundle-adapter-spec.md` §7
- * (llm-wiki row), §6 (wiki-page row), §0.2 (the `wiki` asset-type is retired;
- * the adapter is first-class), §1.2 (probe = schema.md + pages/), §9 (links).
+ * The `wiki` ASSET-TYPE is retired, but the LLM Wiki structure stays first-class
+ * as its OWN adapter: a `BundleAdapter` carrying the native wiki semantics
+ * (probe = schema.md + pages/, wiki-page recognition, links) that the retired
+ * `src/wiki/` module used to own.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/llm-wiki/` + goldens
@@ -17,7 +15,7 @@
  * The adapter is built to MATCH those goldens (driven by
  * `tests/core/adapter/llm-wiki-adapter.test.ts`).
  *
- * ── Structure (spec §7, wiki.ts canonical-content contract) ──
+ * ── Structure ──
  *
  *   - `schema.md` / `index.md` / `log.md` at the wiki ROOT are RESERVED
  *     (recognized, never indexed as concepts) — analogous to OKF's index.md/log.md.
@@ -31,24 +29,24 @@
  *   - Anything else (root README, stray root `.md`, other dirs) is NOT a wiki
  *     asset (`recognize` abstains) — pages live under `pages/`.
  *
- * ── Links / citations (spec §9) ──
+ * ── Links / citations ──
  *
  * A page's `IndexDocument.links` = its resolved `xrefs:` frontmatter (the
  * `wiki:<name>/<conceptId>` form, stripped to the target conceptId) PLUS its
  * body bundle-relative markdown links, deduped, first-appearance order. Its
  * `sources:` frontmatter resolves to the cited raw conceptIds (citation edges),
- * carried on `documentJson` (adapter extras — plan §4.3) and consumed by the
+ * carried on `documentJson` (adapter extras) and consumed by the
  * uncited-raw lint check.
  *
- * ── validate (spec §6/§7, §9) — native wiki checks ONLY ──
+ * ── validate — native wiki checks ONLY ──
  *
  * The native structural checks ported from the retired `src/wiki/` module's
  * `lintWiki`: `broken-xref`
  * (an xref target that does not resolve to an existing page), `uncited-raw`
  * (a `raw/` source not cited by any page's `sources:`), `missing-description`
  * (a page with no description), and `broken-source` (a page `sources:` entry
- * with no matching raw file). Broken xrefs are TOLERATED (warning, non-blocking,
- * spec §9). The shared `runBaseValidateChecks` (unquoted-colon / missing-updated
+ * with no matching raw file). Broken xrefs are TOLERATED (warning, non-blocking).
+ * The shared `runBaseValidateChecks` (unquoted-colon / missing-updated
  * / stale-path / missing-ref) is NOT run: wiki files never carry an `updated`
  * field, so `missing-updated` would fire on every page/reserved file and
  * contradict the lint golden's clean result — the native checks are the wiki's
@@ -82,7 +80,7 @@ const WIKI_COMPONENT_ID = "main";
 const WIKI_SOURCE_TYPE = "wiki-source";
 /** Default open `type` for a `pages/` file whose frontmatter carries no `pageKind`. */
 const DEFAULT_PAGE_KIND = "note";
-/** Reserved wiki files (case-insensitive) at the wiki ROOT — recognized, never indexed as concepts (spec §7). */
+/** Reserved wiki files (case-insensitive) at the wiki ROOT — recognized, never indexed as concepts. */
 const RESERVED_ROOT_FILES = new Set(["schema.md", "index.md", "log.md"]);
 /** Content subdirectory holding immutable ingested sources. */
 const RAW_SUBDIR = "raw";

package/dist/core/adapter/adapters/okf-adapter.js

@@ -2,30 +2,28 @@
 // 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 reference `okf` adapter — akm 0.9.0 chunk-2, WI-A.
+ * The reference `okf` adapter.
  *
- * Implements `docs/architecture/specs/akm-0.9.0-bundle-adapter-spec.md` §5 (the reference
- * OKF adapter) + §5.1 (BINDING: `okf` reads `type` FROM FRONTMATTER, with NO
- * directory gate) EXACTLY. This is pure OKF: `type` from frontmatter, identity
- * from path, no directory routing anywhere.
+ * Pure OKF: `type` is read FROM FRONTMATTER, with NO directory gate; identity
+ * is from path; there is no directory routing anywhere.
  *
- *  - recognize (§5): any `.md` NOT named `index.md`/`log.md` (case-insensitive,
+ *  - recognize: any `.md` NOT named `index.md`/`log.md` (case-insensitive,
  *    reserved) → one concept. `type` = frontmatter `type` when a non-empty
  *    string, else the `knowledge` default. conceptId = the concept's path
- *    within the component root minus `.md`. The OKF field projection (§0.1/§3):
+ *    within the component root minus `.md`. The OKF field projection:
  *    name ← title (fallback: last path segment), description ← description,
  *    tags ← tags, updated ← timestamp. The directory a file sits in NEVER
  *    affects `type`.
- *  - links (§9): BOTH OKF link forms — `/`-rooted bundle-relative and standard
+ *  - links: BOTH OKF link forms — `/`-rooted bundle-relative and standard
  *    relative — resolve deterministically into target conceptIds, stored on
  *    `IndexDocument.links`. Unresolvable / out-of-component links are dropped
  *    (tolerant).
- *  - validate (§5, LENIENT): base checks only; unknown frontmatter never fails;
+ *  - validate (LENIENT): base checks only; unknown frontmatter never fails;
  *    `missing-type` is INFO; `missing-ref` on OKF links is a non-blocking
  *    WARNING (consumers tolerate broken links). Reads go through
  *    `ctx.readFile`; ref existence via `ctx.resolveRef`. Never touches the live
  *    filesystem.
- *  - directoryList / looksLikeRoot per §5 / §1.2. Authoring is deliberately
+ *  - directoryList / looksLikeRoot. Authoring is deliberately
  *    absent; AKM-native writers fail before mutating an OKF bundle.
  */
 import fs from "node:fs";

package/dist/core/adapter/adapters/opencode-adapter.js

@@ -5,7 +5,7 @@
  * The `opencode` tool-directory adapter — akm 0.9.0 format-family work item
  * (#46).
  *
- * Recognizes an OpenCode `.opencode` layout (spec §6/§7, real-world:
+ * Recognizes an OpenCode `.opencode` layout (real-world:
  * https://opencode.ai/docs/{commands,agents,skills,rules}/): a root `AGENTS.md`
  * → `instruction`, `commands/*.md` → `command`, `agents/*.md` → `agent`,
  * `skills/<name>/SKILL.md` → `skill`, and ABSTAINS on `opencode.json` runtime

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

@@ -99,11 +99,11 @@ function stripFencedBlocksSimple(body) {
     return out.join("\n");
 }
 // Ref-token grammar — copied from `base-linter.ts`'s `BUNDLE_REF_RE`
-// (`core/asset/asset-ref.ts`, spec §11.1 / ref-grammar decision D-R3) as a VALUE,
+// (`core/asset/asset-ref.ts`) as a VALUE,
 // not an import (same cycle-avoidance rationale as the file header — the source
 // string is duplicated so no new `core/adapter` -> `core/asset` edge is added for
 // this scan). Recognizes the 0.9.0 FULLY-QUALIFIED `<bundle>//<concept-id>
-// [#fragment]` prose body-ref anchored form ONLY. Per D-R3, a bare short
+// [#fragment]` prose body-ref anchored form ONLY. A bare short
 // conceptId in prose is NOT a ref, so it is never flagged here (it is a ref only
 // in the ref-LIST channels — {@link refTokenFromListValue}). The pre-0.9.0
 // `<type>:<slug>` colon grammar is gone from every recognition surface.
@@ -178,7 +178,7 @@ function readRefStringOrArray(value) {
 }
 /**
  * Port of `BaseLinter.runBaseChecks`, adapted to the read-only
- * `ValidateContext`/`Diagnostic` shapes (adapter spec §12.1). Reproduces
+ * `ValidateContext`/`Diagnostic` shapes. Reproduces
  * unquoted-colon / missing-updated / stale-path / missing-ref for ONE file's
  * already-parsed content.
  *

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

@@ -5,24 +5,24 @@
  * Shared recognition / placement / validation for the two AGENT TOOL-DIRECTORY
  * adapters — `claude` (`.claude`) and `opencode` (`.opencode`) — akm 0.9.0
  * format-family work item (#46). Both translate a foreign tool layout into the
- * open AKM `type` vocabulary (spec §6/§7): a root instruction file
+ * open AKM `type` vocabulary: a root instruction file
  * (CLAUDE.md / AGENTS.md) → `instruction`, `commands/*.md` → `command`,
  * `agents/*.md` → `agent`, `skills/<name>/SKILL.md` → `skill` (item = the dir).
  * They differ only in two parameters carried on {@link ToolDirLayout}:
  *   - the instruction basename + its concept id,
  *   - the adapter id + component id.
  *
- * The SKILL.md codec is shared with the `agent-skills` adapter as functions
- * (spec §8): a skill's conceptId is its DIRECTORY, and its `name` is the
- * frontmatter `name` (== the dir name per the Agent Skills §4.5 hard rule).
+ * The SKILL.md codec is shared with the `agent-skills` adapter as functions:
+ * a skill's conceptId is its DIRECTORY, and its `name` is the
+ * frontmatter `name` (== the dir name per the Agent Skills hard rule).
  *
- * ── D-R6 (reserved files) ──
+ * ── reserved files ──
  *
  * `index.md` / `log.md` are OKF structural files at EVERY depth — never a
  * concept. `classify` excludes them up front so a stray `commands/index.md`
  * never becomes a `command` (mirrors okf/akm/llm-wiki `RESERVED_FILES`).
  *
- * ── validate leniency (spec §6 skill row) ──
+ * ── validate leniency ──
  *
  * The tool-dir adapters TOLERATE the tools' native frontmatter (argument-hint,
  * allowed-tools, tools, model, mode, temperature, agent, …) — the strict
@@ -47,7 +47,6 @@
  * Node builtins.
  */
 import path from "node:path";
-import { createAdapterExtensions, } from "../../../execution/source.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
 import { toPosix } from "../../common.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
@@ -149,7 +148,7 @@ export function readCandidatesToolDir(layout, c, conceptId) {
 function nameOrSignalDiagnostics(type, relPath, data, body) {
     if (nonEmptyString(data.name) !== undefined || nonEmptyString(data.description) !== undefined)
         return [];
-    // command-shaped body/frontmatter signals (spec §6 command row): $ARGUMENTS / $1 / an `agent` frontmatter key.
+    // command-shaped body/frontmatter signals: $ARGUMENTS / $1 / an `agent` frontmatter key.
     if (type === "command" &&
         (/\$ARGUMENTS\b/.test(body) || /\$\d/.test(body) || nonEmptyString(data.agent) !== undefined)) {
         return [];
@@ -193,21 +192,6 @@ export async function validateToolDir(layout, c, changes, ctx) {
     }
     return diagnostics;
 }
-function nativeExecutionExtensions(layout, cls, data) {
-    const values = {};
-    if (layout.adapterId === "claude" && cls.type === "command" && Object.hasOwn(data, "argument-hint")) {
-        if (typeof data["argument-hint"] !== "string") {
-            throw new TypeError("frontmatter.argument-hint must be a string");
-        }
-        values.argumentHint = data["argument-hint"];
-    }
-    if (layout.adapterId === "opencode" && Object.hasOwn(data, "mode")) {
-        if (typeof data.mode !== "string")
-            throw new TypeError("frontmatter.mode must be a string");
-        values.mode = data.mode;
-    }
-    return Object.keys(values).length > 0 ? createAdapterExtensions(layout.adapterId, values) : undefined;
-}
 /** Translate a native Claude/OpenCode command or agent without exposing raw frontmatter. */
 export function renderToolDirExecutionSource(layout, c, file) {
     const cls = classify(file.relPath, layout);
@@ -225,9 +209,7 @@ export function renderToolDirExecutionSource(layout, c, file) {
         },
         defaults: (data) => executionDefaultsFromFrontmatter(data, {
             kind: cls.type === "command" ? "command" : "persona",
-            toolsKeys: layout.adapterId === "claude" && cls.type === "command" ? ["allowed-tools", "tools"] : ["tools"],
         }),
-        extensions: (data) => nativeExecutionExtensions(layout, cls, data),
     });
 }
 /** Build the concrete `BundleAdapter` from a layout + a `looksLikeRoot` probe (claude/opencode share everything else). */

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

@@ -5,10 +5,10 @@
  * The `website-snapshot` adapter — akm 0.9.0 format-family work item (#46).
  *
  * A READ-ONLY (Mode A) view over a materialized crawl snapshot written by
- * `src/sources/snapshot-fetchers/website-ingest.ts` (spec §6/§7). The on-disk
+ * `src/sources/snapshot-fetchers/website-ingest.ts`. The on-disk
  * pages are KNOWLEDGE-shaped markdown under `stash/knowledge/**` with no `type:`
- * field; this adapter RE-TYPES them to the open `type: website`. Per
- * open-question-3 (RESOLVED, maintainer 2026-07) the re-type is GATED — it
+ * field; this adapter RE-TYPES them to the open `type: website`. The re-type
+ * is GATED — it
  * applies only to a page carrying the `website` tag / a `sourceUrl` (a page
  * lacking both is not re-typed); the document KEEPS its `sourceUrl` (surfaced as
  * `sourceRef` on `documentJson`); and the conceptId STRIPS the

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

@@ -27,7 +27,7 @@ const SHADOWABLE_ADAPTER_IDS = new Set(["agent-skills", "claude", "opencode"]);
 /**
  * True when `root` — already claimed by `winnerId` (one of
  * {@link SHADOWABLE_ADAPTER_IDS}) — ALSO carries a top-level directory the
- * `akm` adapter's own probe recognizes as its workspace shape (spec §1.2) and
+ * `akm` adapter's own probe recognizes as its workspace shape and
  * that `winnerId` does not own (its `directoryList()`, or — for `agent-skills`,
  * which owns no fixed directory names — a root-level `<name>/SKILL.md`
  * package) but which holds at least one real file. Cheap by design: only

package/dist/core/adapter/execution-source.js

@@ -5,7 +5,7 @@ import { createHash } from "node:crypto";
 import { isMap, isScalar, parseDocument, visit } from "yaml";
 import { cloneExecutionJson, cloneExecutionJsonObject, } from "../../execution/json.js";
 import { snapshotStrictRecord } from "../../execution/record.js";
-import { cloneToolSelection, createAdapterRenderedExecutionSource, } from "../../execution/source.js";
+import { createAdapterRenderedExecutionSource, warnRetiredEngineKey, } from "../../execution/source.js";
 import { UsageError } from "../errors.js";
 import { warnOnce } from "../warn.js";
 function nextLine(text, start) {
@@ -145,12 +145,6 @@ export function executionDefaultsFromFrontmatter(data, options) {
     if (typeof allowTopLevelEngine !== "boolean") {
         throw new TypeError("execution frontmatter projection options.allowTopLevelEngine must be a boolean");
     }
-    const configuredToolsKeys = Object.hasOwn(options, "toolsKeys")
-        ? cloneExecutionJson(options.toolsKeys, "execution frontmatter projection options.toolsKeys")
-        : ["tools"];
-    if (!Array.isArray(configuredToolsKeys) || configuredToolsKeys.some((key) => typeof key !== "string" || !key)) {
-        throw new TypeError("execution frontmatter projection options.toolsKeys must be an array of non-empty strings");
-    }
     const namespace = own(frontmatter, "akm")
         ? requireMetadataMapping(frontmatter.akm, "frontmatter.akm")
         : snapshotStrictRecord({}, "frontmatter.akm");
@@ -161,36 +155,27 @@ export function executionDefaultsFromFrontmatter(data, options) {
                 ? `frontmatter.akm.${key}`
                 : undefined;
         if (location) {
-            throw new TypeError(`${location} is host-controlled and cannot be declared by an executable asset; configure the selected engine or workflow execution environment instead`);
+            throw new TypeError(`${location} is host-controlled and cannot be declared by an executable asset; configure the selected harness or workflow execution environment instead`);
         }
     }
     const out = Object.create(null);
     if (kind === "command" && own(frontmatter, "agent")) {
         out.agent = nullableString(frontmatter.agent, "frontmatter.agent");
     }
-    const namespacedEngine = own(namespace, "engine")
-        ? nullableString(namespace.engine, "frontmatter.akm.engine")
-        : undefined;
-    const topLevelEngine = allowTopLevelEngine && own(frontmatter, "engine")
-        ? nullableString(frontmatter.engine, "frontmatter.engine")
-        : undefined;
-    if (topLevelEngine !== undefined)
-        out.engine = topLevelEngine;
-    else if (namespacedEngine !== undefined)
-        out.engine = namespacedEngine;
+    // `engine` is the retired spelling of `connection` / `harness`; the resolver reads it as whichever it names.
+    for (const key of ["connection", "harness", "engine"]) {
+        const topLevel = allowTopLevelEngine && own(frontmatter, key) ? nullableString(frontmatter[key], `frontmatter.${key}`) : undefined;
+        const namespaced = own(namespace, key) ? nullableString(namespace[key], `frontmatter.akm.${key}`) : undefined;
+        if (topLevel !== undefined)
+            out[key] = topLevel;
+        else if (namespaced !== undefined)
+            out[key] = namespaced;
+        if (key === "engine" && out.engine !== undefined)
+            warnRetiredEngineKey();
+    }
     if (own(frontmatter, "model")) {
         out.model = nullableString(frontmatter.model, "frontmatter.model");
     }
-    let toolsSelected = false;
-    for (const key of configuredToolsKeys) {
-        if (!own(frontmatter, key))
-            continue;
-        const selection = cloneToolSelection(frontmatter[key], `frontmatter.${key}`);
-        if (!toolsSelected) {
-            out.tools = selection;
-            toolsSelected = true;
-        }
-    }
     let inferenceEntries;
     if (own(namespace, "inference")) {
         if (namespace.inference === null)
@@ -283,12 +268,6 @@ export function renderMarkdownExecutionSource(input) {
     if (hasDefaults && defaults === undefined) {
         throw new TypeError("adapter execution source defaults must be omitted or resolve to an object");
     }
-    const extensionsProjection = input.extensions;
-    const extensionsAreProjected = typeof extensionsProjection === "function";
-    const extensions = extensionsAreProjected ? extensionsProjection(parsed.data) : extensionsProjection;
-    if (Object.hasOwn(input, "extensions") && !extensionsAreProjected && extensions === undefined) {
-        throw new TypeError("adapter execution source extensions must be omitted or be an adapter-owned extension object");
-    }
     return createAdapterRenderedExecutionSource({
         kind,
         content: parsed.content,
@@ -300,6 +279,5 @@ export function renderMarkdownExecutionSource(input) {
             hash: createHash("sha256").update(raw, "utf8").digest("hex"),
         },
         ...(hasDefaults ? { defaults } : {}),
-        ...(extensions === undefined ? {} : { extensions }),
     });
 }

package/dist/core/adapter/registry.js

@@ -41,7 +41,7 @@ const BY_ID = new Map(BUILTIN_ADAPTERS.map((a) => [a.id, a]));
 export function getAdapters() {
     return [...BUILTIN_ADAPTERS];
 }
-/** Look up an adapter by its own `id` (matches `BundleComponent.adapter`); `undefined` for an unknown id (spec §4 — caller skips + warns). */
+/** Look up an adapter by its own `id` (matches `BundleComponent.adapter`); `undefined` for an unknown id (the caller skips + warns). */
 export function adapterForId(id) {
     return BY_ID.get(id);
 }

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

@@ -2,12 +2,10 @@
 // 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").
+ * The ONE core {@link ValidateContext} implementation.
  *
  * `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
+ * method whose contract is explicit: 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 —

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

@@ -138,7 +138,7 @@ const BUILTIN_PLACEMENT_SPECS = {
         toCanonicalName: (typeRoot, filePath) => toPosix(path.relative(typeRoot, filePath)),
         toAssetPath: (typeRoot, name) => path.join(typeRoot, name),
     },
-    // v1 spec §13 — `lesson` asset type. Required frontmatter fields are
+    // `lesson` asset type. Required frontmatter fields are
     // `description` and `when_to_use`; lint enforces both.
     lesson: { stashDir: "lessons", ...markdownSpec },
     // Scheduled tasks. A task file pairs a cron-style schedule with a target

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

@@ -29,14 +29,14 @@ function normalizeName(name) {
     return path.posix.normalize(name.replace(/\\/g, "/"));
 }
 /**
- * Bundle slug charset (spec §3.4): non-empty, and excluding `:`/`.`/`#`/`/`
+ * Bundle slug charset: non-empty, and excluding `:`/`.`/`#`/`/`
  * plus whitespace. Excluding `:`/`.` is what keeps `bundle//conceptId` lexically
  * distinguishable from a URL in prose; excluding `/` is what makes the first
  * `//` an unambiguous bundle boundary; excluding `#` reserves it for fragments.
  */
 const BUNDLE_SLUG_RE = /^[^\s:.#/]+$/;
 /**
- * True when `s` is a legal bundle slug (spec §11.1 / D-R5 charset: non-empty,
+ * True when `s` is a legal bundle slug (charset: non-empty,
  * no `:`/`.`/`#`/`/` or whitespace). Exported for input boundaries that need
  * to distinguish bundle-qualified refs from source locators.
  */
@@ -45,7 +45,7 @@ export function isBundleSlug(s) {
 }
 /**
  * Body-ref recognition (prose): the FULLY-QUALIFIED anchored form ONLY
- * (`<bundle>//<concept-id>[#<fragment>]`, spec §11.1 — the short form is never
+ * (`<bundle>//<concept-id>[#<fragment>]` — the short form is never
  * recognized in prose). `g`/`m` for scanning; group 1 = the whole ref token.
  *
  * The leading `//` must be preceded by a bundle slug, so a URL (`https://…`,

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

@@ -12,6 +12,11 @@
  *                 against an injected {@link RefContext}. This is the "the short
  *                 form is input sugar" rule (§11.1) made structural: only a
  *                 `ResolvedRef` ever crosses a storage boundary.
+ *                 It answers "which bundle" against an injected index snapshot;
+ *                 it does not find files. "Where is the file for this ref right
+ *                 now" has one answer, `resolveConceptOwner`
+ *                 (`src/indexer/lookup/adapter-concept-owner.ts`), which
+ *                 every resolver that needs a path calls.
  *   - serialize — `bundleRefToString` (`asset-ref.ts`); serializing a
  *                 `ResolvedRef` always emits the fully-qualified form.
  *

package/dist/core/bundle-rename.js

@@ -6,7 +6,7 @@
  * bundle's key. A bundle id is a mass identity prefix: every durable ref this
  * tool minted (`entries.item_ref`/`bundle_id`, `proposals.ref`, a pending
  * proposal's `proposedTarget.source`, a workflow task_history row's
- * `target_ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
+ * `target_ref`, a `workflow_runs.workflow_ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
  * `bundles` key strands all of it (see `src/indexer/bundle-identity-guard.ts`
  * §11.5). This module is the rekey transaction that guard's docstring points
  * to.
@@ -32,6 +32,7 @@ import { closeDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from
 import { getFilePathsByBundle, renameEntriesBundleId } from "../storage/repositories/index-entries-repository.js";
 import { countProposalsForBundleRename, renameProposalsBundleRef } from "../storage/repositories/proposals-repository.js";
 import { countTaskHistoryTargetRefs, renameTaskHistoryTargetRefs, } from "../storage/repositories/task-history-repository.js";
+import { countWorkflowRunRefsForRename, renameWorkflowRunRefs } from "../storage/repositories/workflow-runs-repository.js";
 import { selectBackend } from "../tasks/backends/index.js";
 import { bundleRefToString, parseBundleRef } from "./asset/asset-ref.js";
 import { validateExplicitBundleName } from "./bundle-id.js";
@@ -152,12 +153,17 @@ async function buildPlan(config, oldId, newId, sched) {
     let proposalRefs = 0;
     let proposalTargets = 0;
     let taskHistoryRefs = 0;
+    let workflowRunRefs = 0;
+    let activeWorkflowRuns = [];
     if (fs.existsSync(getStateDbPath())) {
         withStateDb((db) => {
             const counts = countProposalsForBundleRename(db, oldId);
             proposalRefs = counts.refs;
             proposalTargets = counts.targets;
             taskHistoryRefs = countTaskHistoryTargetRefs(db, oldId);
+            const runs = countWorkflowRunRefsForRename(db, oldId);
+            workflowRunRefs = runs.refs;
+            activeWorkflowRuns = runs.active;
         });
     }
     return {
@@ -170,7 +176,8 @@ async function buildPlan(config, oldId, newId, sched) {
         },
         lock: { present: lockPresent },
         index: { entries: indexEntries },
-        state: { proposalRefs, proposalTargets, taskHistoryRefs },
+        state: { proposalRefs, proposalTargets, taskHistoryRefs, workflowRunRefs },
+        activeWorkflowRuns,
         contentRefs,
         nativeSchedulerRows,
     };
@@ -254,12 +261,13 @@ export async function renameBundle(oldId, newId, options = {}, deps) {
             closeDatabase(writeIndexDb);
         }
     }
-    // State: proposals.ref, a pending proposal's proposedTarget.source, and
-    // workflow task_history.target_ref.
+    // State: proposals.ref, a pending proposal's proposedTarget.source,
+    // workflow task_history.target_ref, and workflow_runs.workflow_ref.
     if (fs.existsSync(getStateDbPath())) {
         withStateDb((db) => {
             renameProposalsBundleRef(db, oldId, newId);
             renameTaskHistoryTargetRefs(db, oldId, newId);
+            renameWorkflowRunRefs(db, oldId, newId);
         });
     }
     // Scheduler: remove native rows still naming `<old>//` (see