akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/commands/workflow-cli.js

@@ -2,8 +2,9 @@
 // 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/.
 /**
- * `akm workflow` command family. `run` is the canonical start/resume/execute
- * surface; the former public `start`, `next`, and `complete` lifecycle is gone.
+ * `akm workflow` command family. `run` is the canonical start/execute surface
+ * (a ref starts a new run, a run id drives that run) and `resume` reopens a
+ * run; the former public `start`, `next`, and `complete` lifecycle is gone.
  * `create --print` emits Markdown, the only workflow source format. Validate
  * with `akm lint --type workflows`.
  */
@@ -13,7 +14,6 @@ import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, TransientError, UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
-import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/resource-limits.js";
 import { abandonWorkflowRun, getWorkflowStatus, listWorkflowRuns, resolveWorkflowRunTarget, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
@@ -21,7 +21,7 @@ import { akmWorkflowPlan } from "./workflow/plan.js";
 const workflowStatusCommand = defineJsonCommand({
     meta: {
         name: "status",
-        description: "Show full workflow run state for review or resume; workflow refs resolve within the current scope",
+        description: "Show full workflow run state for review or resume; a workflow ref shows its most recent run",
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (workflows/<name>)", required: true },
@@ -31,16 +31,17 @@ const workflowStatusCommand = defineJsonCommand({
                 "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
             default: false,
         },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Runs are no longer scoped to a directory.
         "all-scopes": {
             type: "boolean",
-            description: "When resolving a workflow ref (not a run id), search every scope instead of only the current one (#942).",
+            description: "Deprecated, no effect: runs are host-wide, not scoped to a directory. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
-        const allScopes = args["all-scopes"] === true;
         const resolvedRunId = await resolveWorkflowRunTarget(target);
         if (resolvedRunId !== undefined) {
             const result = await getWorkflowStatus(resolvedRunId, { includeUnits });
@@ -48,9 +49,8 @@ const workflowStatusCommand = defineJsonCommand({
             return;
         }
         let runs;
-        let scopeKey;
         try {
-            ({ runs, scopeKey } = await listWorkflowRuns({ workflowRef: target, allScopes }));
+            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
         }
         catch (error) {
             if (!target.includes(":") && !target.includes("/")) {
@@ -60,14 +60,6 @@ const workflowStatusCommand = defineJsonCommand({
         }
         const mostRecent = runs[0];
         if (!mostRecent) {
-            // #942: name the scope actually searched and point at `--all-scopes`
-            // rather than a bare "not found" — the ref-fallthrough lookup is
-            // scope-local by default, so "no runs" here means "none in THIS
-            // scope", not "none anywhere". Already searching every scope (or no
-            // real scope was filtered on) has nothing more specific to suggest.
-            if (!allScopes && scopeKey !== null) {
-                throw new NotFoundError(`No workflow runs found for ${target} in scope ${scopeKey}.`, "WORKFLOW_NOT_FOUND", `Run 'akm workflow status ${target} --all-scopes' to search every scope.`);
-            }
             throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
         }
         const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
@@ -77,9 +69,7 @@ const workflowStatusCommand = defineJsonCommand({
 const workflowListCommand = defineJsonCommand({
     meta: {
         name: "list",
-        description: "List workflow runs in the current working scope. A scheduled task runs from the scheduler's cwd, so its runs " +
-            "sit in another scope: get the run id from `akm task history <task-id> --limit 1` (detail.runId) and pass it " +
-            "to `akm workflow status <run-id>`, which works from any directory, or pass --all-scopes.",
+        description: "List workflow runs on this host, most recently updated first",
     },
     args: {
         ref: { type: "string", description: "Filter to one workflow ref" },
@@ -89,11 +79,11 @@ const workflowListCommand = defineJsonCommand({
             description: "Also include child workflow runs (hidden by default, P3b)",
             default: false,
         },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Runs are no longer scoped to a directory.
         "all-scopes": {
             type: "boolean",
-            description: "Search every scope instead of only the current one (#942). The envelope's top-level `scopeKey` is " +
-                "`null` with this flag, otherwise the scope that was searched — so an empty `runs: []` is never " +
-                'indistinguishable from "nothing anywhere".',
+            description: "Deprecated, no effect: runs are host-wide, not scoped to a directory. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
@@ -102,7 +92,6 @@ const workflowListCommand = defineJsonCommand({
             workflowRef: args.ref,
             activeOnly: args.active,
             includeChildren: args.children,
-            allScopes: args["all-scopes"],
         });
         output("workflow-list", result);
     },
@@ -158,12 +147,6 @@ const workflowCreateCommand = defineJsonCommand({
             from: args.from,
             force: args.force,
         });
-        // Index the newly-written workflow so `akm workflow run` can resolve
-        // a workflowEntryId without requiring an explicit `akm index` call
-        // first. Uses the same incremental index path that `akm add` uses.
-        // `result.bundleDir` — the indexer's own `IndexOptions.stashDir` field
-        // name is unchanged (indexer vocabulary is out of scope, P4 row B-50).
-        await akmIndex({ stashDir: result.bundleDir });
         output("workflow-create", { ok: true, ...result });
     },
 });
@@ -184,29 +167,34 @@ const WORKFLOW_RUN_SKIP_REASONS = {
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
-        description: "Start or resume a workflow and execute it through completion, failure, a verification gate, or an explicit limit",
+        description: "Start a new run of a workflow ref, or drive an existing run by id, through completion, failure, a verification gate, or an explicit limit",
     },
     args: {
-        target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
+        target: {
+            type: "positional",
+            description: "Workflow ref (starts a new run) or workflow run id (drives that run)",
+            required: true,
+        },
         "max-steps": { type: "string", description: "Stop after executing this many steps" },
         "max-retries": { type: "string", description: "Retry a failed workflow step this many additional times" },
         timeout: { type: "string", description: "Whole-run timeout: N, Nms, Ns, or Nm (bare N is milliseconds)" },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. A workflow ref always starts a new run now.
         new: {
             type: "boolean",
-            description: "Start a fresh run even if one is already active for this ref, leaving the existing run untouched " +
-                "(never abandons it). A workflow ref only — passing a run id with --new is a usage error.",
+            description: "Deprecated, no effect: a workflow ref always starts a new run. Accepted through 0.10 for existing scripts.",
             default: false,
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "If another akm process is already driving this run, or state.db is busy with another " +
-                "writer, skip gracefully (exit 0) instead of failing (exit 75). Use for high-frequency scheduled runs " +
-                "so they don't pile up failures while a longer-running invocation is in progress.",
+            description: "If another akm process is already driving this run (or, for a workflow ref, an active run of it), or " +
+                "state.db is busy with another writer, skip gracefully (exit 0) instead of failing (exit 75). Use for " +
+                "high-frequency scheduled runs so they don't pile up failures while a longer-running invocation is in progress.",
             default: false,
         },
     },
     async run({ args, rawArgs }) {
-        const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
+        const { findLiveLockedRunOfRef, runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
         const parameterFlags = parseWorkflowParameterFlags(rawArgs, args.target);
         const maxSteps = parseIntegerFlag(getStringArg(args, "max-steps"), "--max-steps", 1);
         const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0);
@@ -228,15 +216,25 @@ const workflowRunCommand = defineJsonCommand({
             timeoutMs,
             reason: `Workflow run timed out after ${timeoutMs}ms.`,
         });
+        const skip = (reason, message) => {
+            warn(`[workflow] ${message} skipping (--skip-if-locked)`);
+            output("workflow-run", { ok: true, target: args.target, skipped: { reason, message } });
+        };
         try {
             let result;
             try {
+                // #1239: a ref start never conflicts with another run of the ref, so
+                // the one extra condition is an active run of it a live process is driving.
+                const held = skipIfLocked ? await findLiveLockedRunOfRef(args.target) : undefined;
+                if (held) {
+                    skip("lock-held", `Workflow run ${held.runId} of ${args.target} is already being driven by another akm process (pid ${held.holder}).`);
+                    return;
+                }
                 result = await runWorkflowSteps({
                     target: args.target,
                     parameterFlags,
                     ...(maxSteps !== undefined ? { maxSteps } : {}),
                     ...(maxRetries !== undefined ? { maxRetries } : {}),
-                    newRun: args.new,
                     signal: controller.signal,
                 });
             }
@@ -247,9 +245,7 @@ const workflowRunCommand = defineJsonCommand({
                 // off UsageError) — a bad flag or malformed input still fails loudly
                 // even with the flag set.
                 if (skipIfLocked && err instanceof TransientError && WORKFLOW_RUN_SKIP_REASONS[err.code]) {
-                    const reason = WORKFLOW_RUN_SKIP_REASONS[err.code];
-                    warn(`[workflow] ${err.message} skipping (--skip-if-locked)`);
-                    output("workflow-run", { ok: true, target: args.target, skipped: { reason, message: err.message } });
+                    skip(WORKFLOW_RUN_SKIP_REASONS[err.code], err.message);
                     return;
                 }
                 throw err;
@@ -371,10 +367,9 @@ function parseWorkflowTimeout(raw) {
     }
     return timeoutMs;
 }
-// P3b Lane B (spec docs/plans/specs/p3b-child-executor.md §4.6): read-only
-// compile+freeze introspection — zero durable writes, zero usage/event rows
-// (row B-48). `--json` is deliberately NOT a flag anywhere in this CLI
-// (B-N9); the global `--format json` is spliced on by `defineJsonCommand`.
+// Read-only compile+freeze introspection — zero durable writes, zero
+// usage/event rows. `--json` is deliberately NOT a flag anywhere in this CLI;
+// the global `--format json` is spliced on by `defineJsonCommand`.
 const workflowPlanCommand = defineJsonCommand({
     meta: {
         name: "plan",

package/dist/core/adapter/adapters/agent-skills-adapter.js

@@ -8,18 +8,18 @@
  * github.com/anthropics/skills): each `<name>/SKILL.md` is one `skill` item
  * whose conceptId is the package DIRECTORY (`<name>`); bundled resources under
  * the package (`<name>/reference/FORMS.md`) are part of the item, not standalone
- * concepts (item-scoped incrementality, spec §4). The SKILL.md codec is shared
- * with claude/opencode as functions (spec §8); this adapter differs in that the
+ * concepts (item-scoped incrementality). The SKILL.md codec is shared
+ * with claude/opencode as functions; this adapter differs in that the
  * package dir sits directly under the component root (no `skills/` prefix) and
- * that `validate` enforces the FULL Agent Skills contract (spec §4.5).
+ * that `validate` enforces the FULL Agent Skills contract.
  *
  * RECOGNITION ≠ VALIDATION: an invalid skill (bad name charset, over-long
  * description) is still RECOGNIZED as `type: skill` (the raw invalid `name` is
  * projected so it is inspectable downstream); the violations surface only in
- * `validate` (spec §4.5). This mirrors how `okf` recognizes content and defers
+ * `validate`. This mirrors how `okf` recognizes content and defers
  * leniency to validate.
  *
- * ── validate (spec §4.5, APPROVED codes — maintainer resolution 2026-07) ──
+ * ── validate ──
  *
  *   - `skill-name-invalid` — name must be NFKC 1-64 chars matching
  *     `^[a-z0-9]+(-[a-z0-9]+)*$`, carry no reserved word, and equal the parent
@@ -32,8 +32,7 @@
  *     cannot reach it, because a change is always a file and a manifest-less
  *     package contributes no SKILL.md change (issue #774).
  *
- * The two field codes are APPROVED-BUT-NOT-YET-CODED elsewhere and are
- * implemented here. Base checks are NOT run:
+ * The two field codes are implemented here. Base checks are NOT run:
  * a SKILL.md carries no `updated` field, so `missing-updated` would fire on
  * every conformant skill and contradict the lint golden.
  *
@@ -50,12 +49,12 @@ import { hashContent, nonEmptyString, readTags } from "./shared.js";
 const COMPONENT_ID = "main";
 /** The skill manifest basename (the item marker). */
 const SKILL_MANIFEST = "SKILL.md";
-/** Agent Skills hard limits (spec §4.5). */
+/** Agent Skills hard limits. */
 const NAME_MAX = 64;
 const DESCRIPTION_MAX = 1024;
 /** Agent Skills reserved words a name must not contain (real-world source). */
 const RESERVED_NAME_WORDS = ["anthropic", "claude"];
-/** name charset/shape rule (spec §4.5). */
+/** name charset/shape rule. */
 const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /** conceptId + package-dir name for a `<name>/SKILL.md` file, or null when the file is not a skill manifest. */
 function skillPackage(relPath) {
@@ -111,7 +110,7 @@ function skillFieldDiagnostics(relPath, dirName, data) {
             file: relPath,
             issue: "skill-name-invalid",
             detail: `skill name '${name}' must match ^[a-z0-9]+(-[a-z0-9]+)*$ (NFKC, 1-${NAME_MAX} chars, ` +
-                `no reserved word, == parent dir name '${dirName}') — Agent Skills hard rule (spec §4.5).`,
+                `no reserved word, == parent dir name '${dirName}') — Agent Skills hard rule.`,
             fixed: false,
         });
     }
@@ -120,7 +119,7 @@ function skillFieldDiagnostics(relPath, dirName, data) {
         diagnostics.push({
             file: relPath,
             issue: "skill-description-too-long",
-            detail: `skill description is ${description.length} characters; the Agent Skills hard limit is 1-${DESCRIPTION_MAX} (spec §4.5).`,
+            detail: `skill description is ${description.length} characters; the Agent Skills hard limit is 1-${DESCRIPTION_MAX}.`,
             fixed: false,
         });
     }

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

@@ -2,19 +2,18 @@
 // 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 AKM workspace's own `akm` adapter — akm 0.9.0 chunk-2, WI-B.
+ * The AKM workspace's own `akm` adapter.
  *
- * Implements `docs/architecture/specs/akm-0.9.0-bundle-adapter-spec.md` §5.1 (BINDING) +
- * §6 + §7 (the `akm` row) EXACTLY: a BEHAVIOR-PRESERVING PORT that reproduces
+ * A BEHAVIOR-PRESERVING PORT that reproduces
  * TODAY'S classification and placement VERBATIM by REUSING the existing matcher
  * stack. It is NOT re-derived onto frontmatter `type` (that is the sibling
- * `okf` adapter's job, §5), NOT split per-`type` (the 14 AKM formats are `type`
- * VALUES the single `akm` adapter emits, §6/§0.2), and introduces NO new
+ * `okf` adapter's job), NOT split per-`type` (the 14 AKM formats are `type`
+ * VALUES the single `akm` adapter emits), and introduces NO new
  * positional/directory heuristics of its own.
  *
- * ── recognize (§5.1): the sync `runMatchers` reproduction ──
+ * ── recognize: the sync `runMatchers` reproduction ──
  *
- * `file-context.ts#runMatchers` (`:242-265`) is async ONLY because of its lazy
+ * `file-context.ts#runMatchers` is async ONLY because of its lazy
  * `ensureBuiltinsRegistered()` dynamic import; its ARBITRATION is pure and
  * synchronous. We reproduce it here by importing the SAME four builtin matcher
  * functions (`matchers.ts` `extensionMatcher` / `directoryMatcher` /
@@ -31,10 +30,10 @@
  * same arbitration.
  *
  * The winning `MatchResult.renderer` is carried on `documentJson.renderer` so
- * WI-C can wire presentation via `TYPE_PRESENTATION` without a new
- * `IndexDocument` field (WI-C owns presentation).
+ * presentation can be wired via `TYPE_PRESENTATION` without a new
+ * `IndexDocument` field.
  *
- * ── conceptId (§5.1 + ref-grammar decision D-R2): the QUALIFIED spelling ──
+ * ── conceptId: the QUALIFIED spelling ──
  *
  * conceptId = `<stash-subdir>/<canonical-name>` — the placement stash-subdir
  * (`stashDirFor(type)`) followed by the winning type's canonical name
@@ -43,26 +42,26 @@
  * extension, env/task strip their ext, and secret/session keep the natural
  * path). For Markdown types this IS the OKF concept ID (path − `.md`); it is
  * the same spelling `readCandidates` consumes, so
- * recognize/read share one identity (D-R2 resolved the earlier split). The
- * `type` is carried separately on `IndexDocument.type`, per §0.2 (type ≠
+ * recognize/read share one identity. The
+ * `type` is carried separately on `IndexDocument.type` (type ≠
  * identity), and `entry.name` keeps the BARE canonical name for FTS parity.
  *
  * ── readCandidates / directoryList / looksLikeRoot: type-driven placement ──
  *
  * Placement is type-driven (`path-resolver.ts#buildDiskCandidates`: the primary
  * candidate is `assetPathForName(ref.type, join(root, stashDirFor(ref.type)),
- * ref.name)`). §5.1 removes `type` from the ref, so `readCandidates` recovers
+ * ref.name)`). A ref carries no `type`, so `readCandidates` recovers
  * it from the conceptId's LEADING path segment — the qualified `<stash-subdir>/
- * <name>` form of §1.3 — reverse-mapping that segment against the placement
+ * <name>` form — reverse-mapping that segment against the placement
  * stash-subdir map and then delegating to `assetPathCandidatesForName`.
  *
- * ── validate: base checks only (WI-B) ──
+ * ── validate ──
  *
- * Base validate checks only for this WI (shared `validateChangesWithBaseChecks`
- * — the ported unquoted-colon / missing-updated / stale-path / missing-ref).
- * The per-type linters (SkillLinter/WorkflowLinter/TaskLinter/…) are WI-C.
+ * Shared base checks (`validateChangesWithBaseChecks` — the ported
+ * unquoted-colon / missing-updated / stale-path / missing-ref), then the
+ * per-type linters (SkillLinter/WorkflowLinter/TaskLinter/…) in `akm-lint.ts`.
  *
- * ── Cycle-safety (chunk-3 cutover, baseline 18) ──
+ * ── Cycle-safety ──
  *
  * This module VALUE-imports `matchers.ts` (indexer/walk) for classification and
  * `asset-placement.ts` (core/asset) for placement — delegating to the existing
@@ -74,15 +73,14 @@
  * in production for the frozen `BUILTIN_ADAPTERS` list
  * (`installations.ts#detectAdapterId`, `provider-utils.ts#detectStashRoot`).
  * The adapter is still itself a leaf, since neither the barrel nor the
- * registry import anything that imports back into this file — verified: `bun
- * scripts/lint-import-cycles.ts` reports 0 cycle participants and this module
- * is NOT one.
+ * registry import anything that imports back into this file.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../../../indexer/passes/metadata.js";
 import { assetPathCandidatesForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { sensitiveMarkerPath } from "../../sensitive-marker-path.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { recognizeMatch } from "../recognize-match.js";
 import { perTypeValidateChecks, skillDirectoryDiagnostics } from "./akm-lint.js";
@@ -95,15 +93,14 @@ import { hashContent, RESERVED_FILES, runBaseValidateChecks } from "./shared.js"
 // unaffected.
 export { recognizeMatch } from "../recognize-match.js";
 /**
- * OKF reserved structural files (ref-grammar decision D-R6, spec §5.1 /
- * adapter-spec §5.1/§6): `index.md` (directory listing) and `log.md` (update
+ * OKF reserved structural files: `index.md` (directory listing) and `log.md` (update
  * history) are bundle structure at EVERY depth — never a concept document. The
  * `okf` / `llm-wiki` adapters already exclude them (`shared.ts`'s
  * `RESERVED_FILES`); this brings the `akm` adapter into conformance so a
  * `knowledge/index.md` never classifies as a `knowledge` item. Case-insensitive,
  * matched on the bare filename so the exclusion holds at any depth.
  */
-/** True when `name` (a bare file name) is an OKF reserved file, case-insensitively (D-R6). */
+/** True when `name` (a bare file name) is an OKF reserved file, case-insensitively. */
 function isReservedFileName(name) {
     return RESERVED_FILES.has(name.toLowerCase());
 }
@@ -136,7 +133,7 @@ function akmStashAbstains(root, absPath) {
         return true;
     // Skip env `.env` files that have a sibling `.sensitive` marker file.
     if (segments[0] === "env" && (absPath.endsWith(".env") || path.basename(absPath) === ".env")) {
-        if (fs.existsSync(absPath.replace(/\.env$/, ".sensitive")))
+        if (fs.existsSync(sensitiveMarkerPath(absPath, "env")))
             return true;
     }
     // Skip secret files that are themselves a `.sensitive` marker, or that have a
@@ -145,7 +142,7 @@ function akmStashAbstains(root, absPath) {
     if (segments[0] === "secrets") {
         if (absPath.endsWith(".sensitive") || absPath.endsWith(".lock"))
             return true;
-        if (fs.existsSync(`${absPath}.sensitive`))
+        if (fs.existsSync(sensitiveMarkerPath(absPath, "secret")))
             return true;
     }
     // Inside a `wikis/<name>/` directory, the root-level infrastructure files
@@ -166,11 +163,11 @@ function stashDirToType(stashDir) {
 }
 /**
  * The search-surface `IndexDocument` fields that have NO first-class `IndexDocument`
- * home (spec §3) and therefore ride `documentJson` so the persist-time fold
- * (`search-fields.ts:28-33`) can still reach them — the exact set
+ * home and therefore ride `documentJson` so the persist-time fold
+ * (`search-fields.ts`) can still reach them — the exact set
  * `buildSearchFields` folds into the `hints`/`content` FTS columns beyond the
  * first-class name/description/tags/aliases/searchHints, plus the provenance the
- * WI-C tests read (renderer/source). Kept as a named list so the fold surface and
+ * tests read (renderer/source). Kept as a named list so the fold surface and
  * the mapping stay in lockstep.
  */
 const DOCUMENT_JSON_CARRIED_FIELDS = [
@@ -203,11 +200,11 @@ const DOCUMENT_JSON_CARRIED_FIELDS = [
 ];
 /**
  * Map the fully-assembled `IndexDocument` (produced by the shared metadata
- * pipeline) onto an `IndexDocument` (spec §3). First-class ranking/embedding
+ * pipeline) onto an `IndexDocument`. First-class ranking/embedding
  * fields land on named IndexDocument fields; every other search-surface or
  * signal field rides `documentJson` (opaque adapter extras) so nothing the
- * ranking/embedding/filter inputs read is lost — the M-b shadow-parity gate.
- * The winning renderer name is carried on `documentJson.renderer` (WI-C contract).
+ * ranking/embedding/filter inputs read is lost.
+ * The winning renderer name is carried on `documentJson.renderer`.
  */
 function indexDocumentFromEntry(entry, base, rendererName) {
     const extras = { renderer: rendererName };
@@ -264,7 +261,7 @@ function conceptIdForRecognizedType(root, filePath, type) {
     return stashDir !== undefined ? `${stashDir}/${canonicalName}` : canonicalName;
 }
 function recognize(c, file) {
-    // D-R6 (spec §5.1): `index.md` / `log.md` are OKF reserved structural files at
+    // `index.md` / `log.md` are OKF reserved structural files at
     // every depth — never items. Excluded BEFORE classification so a directory
     // listing or update log never becomes a `knowledge` (or other) concept.
     if (isReservedFileName(file.fileName))
@@ -294,12 +291,12 @@ function recognize(c, file) {
     // `skills/skills/x`. `entry.name` below keeps the BARE canonical name —
     // identity ≠ search text.
     const dirPath = path.dirname(file.absPath);
-    // Chunk 5 M-b: recognize now carries the FULL index-time metadata surface
-    // (spec §2/§3), reproducing `buildEntryFromFile`'s flat-walk metadata
+    // recognize carries the FULL index-time metadata surface,
+    // reproducing `buildEntryFromFile`'s flat-walk metadata
     // output by SHARING its P1/P2/P4 assembly and substituting the synchronous
     // `foldRecognizedMetadata` (+ `applyFoldedMetadata`, which replicates the
     // in-place contributor precedence) for the async P3 renderer contributors.
-    // `entry.name` = the BARE canonical name (conceptId minus the D-R2 stash-subdir
+    // `entry.name` = the BARE canonical name (conceptId minus the stash-subdir
     // prefix) so the FTS `name` column
     // matches the pre-0.9.0 indexer (search-behavior parity), NOT the frontmatter
     // title. Parity is by construction — the two paths differ only in the P3 step,
@@ -347,14 +344,13 @@ function renderExecutionSource(c, file) {
         defaults: (data) => executionDefaultsFromFrontmatter(data, {
             kind: document.type === "command" ? "command" : "persona",
             allowTopLevelEngine: true,
-            toolsKeys: ["tools"],
         }),
     });
 }
 /**
  * A read-only {@link FileContext} backed by an OVERLAY string (a pending
  * change's content) instead of the live filesystem — the `validate` contract
- * ({@link BundleAdapter.validate} doc comment / adapter-spec §12.1) forbids
+ * ({@link BundleAdapter.validate} doc comment) forbids
  * reading the live FS. It mirrors `buildFileContext`'s eager path-field
  * derivation exactly (so the matchers classify identically) and serves the
  * overlay bytes from `content()`/`frontmatter()`. `stat()` throws: no matcher
@@ -395,7 +391,7 @@ function buildOverlayContext(root, relPathInput, raw) {
     };
 }
 /**
- * `validate` (spec §6) = shared base checks + the winning `type`'s per-type
+ * `validate` = shared base checks + the winning `type`'s per-type
  * extra checks, reproducing today's `akmLint`/`getLinterForType` dispatch
  * byte-for-byte (the FROZEN `lint/all-types.json` `perType` golden is the gate).
  *
@@ -439,7 +435,6 @@ async function validate(c, changes, ctx) {
             body: parsed.content,
             ext: overlay.ext,
             ctx,
-            workspaceRoot: c.root,
         })));
         diagnostics.push(...(await skillDirectoryDiagnostics(change.path, seenSkillDirs, ctx)));
     }

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

@@ -2,10 +2,9 @@
 // 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/.
 /**
- * Per-`type` validate checks for the `akm` adapter — akm 0.9.0 chunk-2, WI-C,
- * implementing spec §6 (the per-`type` validation column) as a
- * behavior-preserving port of `src/commands/lint/*`'s type linters. The `akm`
- * adapter's `validate` = shared base checks (WI-A `shared.ts`) + these per-type
+ * Per-`type` validate checks for the `akm` adapter: a behavior-preserving
+ * port of `src/commands/lint/*`'s type linters. The `akm`
+ * adapter's `validate` = shared base checks (`shared.ts`) + these per-type
  * extra checks, keyed on the winning `type`, reproducing today's
  * `getLinterForType(subdir).lint(ctx)` dispatch. The FROZEN lint golden
  * (`tests/fixtures/goldens/lint/all-types.json`, `perType`) is the conformance
@@ -30,7 +29,7 @@
  * `ValidateContext` (the run snapshot + pending overlay) — the live linters'
  * `fs.existsSync` sibling/SKILL.md probes become `ctx.readFile` lookups.
  *
- * ── env/secret dangerous-key narrowness (PRESERVED, spec §6) ──
+ * ── env/secret dangerous-key narrowness (PRESERVED) ──
  *
  * Today's scan (`collectEnvFiles`) only visits `.env`-SUFFIXED files under
  * `env/` and `secrets/`, so `secrets/<bare-name>` is NOT scanned. This port
@@ -207,7 +206,7 @@ export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs =
  * routes through `ctx`.
  */
 export async function perTypeValidateChecks(args) {
-    const { type, relPath, raw, data, frontmatter, body, ext, ctx, workspaceRoot } = args;
+    const { type, relPath, raw, data, frontmatter, body, ext, ctx } = args;
     switch (type) {
         case "command":
             return nameOrTypeDiagnostics(relPath, data, frontmatter, ["command"]);
@@ -216,7 +215,7 @@ export async function perTypeValidateChecks(args) {
         case "fact":
             return factDiagnostics(relPath, data);
         case "task":
-            return taskDiagnostics(relPath, raw, workspaceRoot);
+            return taskDiagnostics(relPath, raw);
         case "workflow":
             return ext === ".md" ? workflowDiagnostics(relPath, raw, body) : [];
         case "memory":
@@ -255,9 +254,9 @@ export function factDiagnostics(relPath, data) {
     return [];
 }
 /**
- * Task validation has one semantic owner: the version-routed task source
- * parser (spec docs/plans/specs/p2a-task-source-v4.md §3.6) — `version: 3`
- * through the strict task-v3 grammar, `version: 4` through task source v4.
+ * Task validation has one semantic owner: the task source parser, which reads
+ * task source v4 and refuses an older `version` with
+ * `TASK_SCHEMA_VERSION_UNSUPPORTED`.
  * Keeping raw YAML at this boundary preserves duplicate-key, alias/tag,
  * source-location, descriptor, resource-bound, and migration-hint behavior.
  *
@@ -266,12 +265,11 @@ export function factDiagnostics(relPath, data) {
  * contract; the cron suits the local scheduler backend), so `akm lint --type
  * tasks` never reports clean a task that sync would refuse.
  */
-export function taskDiagnostics(relPath, raw, workspaceRoot) {
+export function taskDiagnostics(relPath, raw) {
     try {
         const parsed = parseTaskSource({
             filePath: relPath,
             yaml: raw,
-            ...(workspaceRoot ? { workspaceRoot } : {}),
         });
         assertTaskScheduleInputsSatisfyContract(parsed.v4, relPath);
         assertTaskScheduleCronValid(parsed.v4, backendNameForPlatform());

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

@@ -170,7 +170,7 @@ export function foldRecognizedMetadata(rendererName, file) {
         case "task-yaml": {
             out.tags = Array.from(new Set([...(out.tags ?? []), "task", "scheduled"]));
             try {
-                const parsed = parseTaskSource({ yaml: file.content(), filePath: file.absPath, workspaceRoot: file.stashRoot });
+                const parsed = parseTaskSource({ yaml: file.content(), filePath: file.absPath });
                 const v4 = parsed.v4;
                 const target = v4.target;
                 const hints = new Set();
@@ -261,7 +261,7 @@ export function foldRecognizedMetadata(rendererName, file) {
         // ── workflow-document-metadata (historical renderer id `workflow-md`, peer sources) ──
         case "workflow-md": {
             try {
-                const result = compileWorkflowSource(file.content(), { path: file.relPath, workspaceRoot: file.stashRoot });
+                const result = compileWorkflowSource(file.content(), { path: file.relPath });
                 if (!result.ok)
                     return out;
                 const plan = result.plan;

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

@@ -4,7 +4,7 @@
 /**
  * The `akm-task` adapter for task `.yml` sources.
  *
- * A native akm task-YAML bundle (spec §6/§7). A `.yml` file derives
+ * A native akm task-YAML bundle. A `.yml` file derives
  * `type: task`; conceptId strips the `.yml` extension. Tasks are AKM-native
  * YAML, NOT OKF markdown concepts. Recognition does NOT gate on validity — an
  * invalid task (e.g. `uses` plus `run`) is still RECOGNIZED; the `invalid-task-yaml`
@@ -14,16 +14,15 @@
  * is not a task spelling (nothing indexes or schedules it), so it is reported
  * as `invalid-task-yaml` rather than silently skipped (issue #760).
  *
- * ── validate (spec §6 task validation column) ──
+ * ── validate ──
  *
  * Validation enters the canonical task source parser (`parseTaskSource`,
  * which reads only task source v4 — a `version: 2` or `version: 3`
  * document fails closed with `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming
  * `akm migrate apply`, which converts it). That parser owns the closed key sets,
  * the executable-selector XOR, hostile YAML policy, the `akm/command`
- * builtin, bounds, and physical `working-directory` containment. The
- * adapter only translates a parser failure into the format-family
- * diagnostic shape.
+ * builtin, and bounds. The adapter only translates a parser failure into
+ * the format-family diagnostic shape.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -38,7 +37,7 @@ import { toPosix } from "../../common.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
-/** The task YAML extension (spec §6 task row). */
+/** The task YAML extension. */
 const TASK_EXT = TASK_EXTENSION;
 function recognize(c, file) {
     if (file.ext !== TASK_EXT)
@@ -59,7 +58,7 @@ function recognize(c, file) {
         content: raw,
     };
 }
-async function validate(c, changes, ctx) {
+async function validate(_c, changes, ctx) {
     const diagnostics = [];
     for (const change of changes) {
         if (change.op === "delete")
@@ -84,7 +83,7 @@ async function validate(c, changes, ctx) {
             continue;
         }
         try {
-            parseTaskSource({ yaml: raw, filePath: relPath, workspaceRoot: c.root });
+            parseTaskSource({ yaml: raw, filePath: relPath });
         }
         catch (cause) {
             diagnostics.push({
@@ -145,7 +144,7 @@ export const akmTaskAdapter = {
                 continue;
             }
             try {
-                parseTaskSource({ yaml: raw, filePath: entry.name, workspaceRoot: root });
+                parseTaskSource({ yaml: raw, filePath: entry.name });
                 return true;
             }
             catch {