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

package/dist/commands/workflow-cli.js

@@ -2,111 +2,22 @@
 // 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. Extracted verbatim from src/cli.ts (WS6) so the
- * God Module shrinks; the `main.subCommands.workflow` key and every subcommand's
- * args/output shape are byte-identical. Handlers whose body is a plain
- * `runWithJsonErrors(...) + output(...)` are migrated to `defineJsonCommand`,
- * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
- * form.
- *
- * 0.9.0 CLI overhaul (S5): `workflow template` is dropped — `workflow create
- * --print` prints the same content without writing. `workflow validate` is
- * dropped — `akm lint --type workflows` covers structural validation.
- * `workflow watch` is dropped — poll `akm log --since '@offset:<id>' --run
- * <run-id>` instead. Workflows are markdown-only (workflow-format-
- * unification) — `workflow create <name>.yaml` is a usage error.
+ * `akm workflow` command family. `run` is the canonical start/resume/execute
+ * surface; the former public `start`, `next`, and `complete` lifecycle is gone.
+ * `brief`/`report` retain the experimental harness-neutral driver protocol.
+ * Workflows are markdown-only; authoring uses `create --print` and validation
+ * uses `akm lint --type workflows`.
  */
-import { getParsedInvocation } from "../cli/invocation.js";
 import { getStringArg } from "../cli/parse-args.js";
-import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
+import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../cli/shared.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
-import { parseWorkflowJsonObject, parseWorkflowStepState, WORKFLOW_STEP_STATES } from "../workflows/cli.js";
 import { requireWorkflowEngineEnabled } from "../workflows/exec/workflow-engine-gate.js";
-import { abandonWorkflowRun, completeWorkflowStep, getNextWorkflowStep, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, startWorkflowRun, } from "../workflows/runtime/runs.js";
-const workflowStartCommand = defineJsonCommand({
-    meta: {
-        name: "start",
-        description: "Start a new workflow run in the current working scope",
-    },
-    args: {
-        ref: { type: "positional", description: "Workflow ref (workflows/<name>)", required: true },
-        params: { type: "string", description: "Workflow parameters as a JSON object" },
-        force: {
-            type: "boolean",
-            description: "Allow a parallel run when an active run already exists in this scope",
-            default: false,
-        },
-    },
-    async run({ args }) {
-        const result = await startWorkflowRun(args.ref, parseWorkflowJsonObject(args.params, "--params"), {
-            force: args.force === true,
-        });
-        output("workflow-start", result);
-    },
-});
-const workflowNextCommand = defineJsonCommand({
-    meta: {
-        name: "next",
-        description: "Show the next actionable workflow step in the current scope, auto-starting a run when passed a workflow ref",
-    },
-    args: {
-        target: { type: "positional", description: "Workflow run id or workflow ref", required: true },
-        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
-    },
-    async run({ args }) {
-        // `--dry-run` is intentionally NOT a declared arg (so it stays out of
-        // --help). The guard reads it straight from the invocation singleton so
-        // existing callers still get a clear, actionable error instead of a
-        // generic "unknown flag" from citty.
-        if (getParsedInvocation().hasFlag("--dry-run")) {
-            throw new UsageError("`akm workflow next` does not support --dry-run. Remove the flag to start or resume a run.", "INVALID_FLAG_VALUE");
-        }
-        const parsedParams = args.params ? parseWorkflowJsonObject(args.params, "--params") : undefined;
-        const result = await getNextWorkflowStep(args.target, parsedParams);
-        output("workflow-next", result);
-    },
-});
-const workflowCompleteCommand = defineJsonCommand({
-    meta: {
-        name: "complete",
-        description: "Update a workflow step state and persist notes/evidence",
-    },
-    args: {
-        runId: { type: "positional", description: "Workflow run id", required: true },
-        step: { type: "string", description: "Workflow step id", required: true },
-        state: {
-            type: "string",
-            description: `Step state (default: completed). One of: ${WORKFLOW_STEP_STATES.join(", ")}.`,
-        },
-        notes: { type: "string", description: "Notes for the completed step" },
-        summary: {
-            type: "string",
-            description: "Summary of work done (required when completing a step); validated against completion criteria",
-        },
-        evidence: { type: "string", description: "Evidence JSON object for the step" },
-    },
-    async run({ args }) {
-        const result = await completeWorkflowStep({
-            runId: args.runId,
-            stepId: args.step,
-            status: parseWorkflowStepState(args.state),
-            notes: args.notes,
-            summary: args.summary,
-            evidence: args.evidence ? parseWorkflowJsonObject(args.evidence, "--evidence") : undefined,
-        });
-        if ("ok" in result && result.ok === false) {
-            // Summary failed the completion-criteria validation gate (#506): the
-            // step stays pending and the agent receives corrective feedback.
-            output("workflow-complete-rejected", result);
-            return;
-        }
-        output("workflow-complete", result);
-    },
-});
+import { WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
+import { abandonWorkflowRun, getWorkflowStatus, hasWorkflowRun, listWorkflowRuns, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
 const workflowStatusCommand = defineJsonCommand({
     meta: {
         name: "status",
@@ -219,7 +130,7 @@ const workflowCreateCommand = defineJsonCommand({
             from: args.from,
             force: args.force,
         });
-        // Index the newly-written workflow so `akm workflow start` can resolve
+        // 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.
         await akmIndex({ stashDir: result.stashDir });
@@ -229,34 +140,149 @@ const workflowCreateCommand = defineJsonCommand({
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
-        description: "EXPERIMENTAL, gated behind `experimental.workflowEngine`: execute a workflow's steps with the native " +
-            "engine — akm dispatches each step's units (fan-out, schema output) to the configured runner and advances " +
-            "the run through the normal completion gates",
+        description: "Start or resume a workflow and execute it 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 },
-        params: { type: "string", description: "Workflow parameters as a JSON object (only for auto-started runs)" },
         "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)" },
     },
-    async run({ args }) {
-        requireWorkflowEngineEnabled(loadConfig(), "run");
+    async run({ args, rawArgs }) {
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
-        const rawMaxSteps = getStringArg(args, "max-steps");
-        let maxSteps;
-        if (rawMaxSteps !== undefined) {
-            maxSteps = Number.parseInt(rawMaxSteps, 10);
-            if (!/^\d+$/.test(rawMaxSteps) || maxSteps <= 0) {
-                throw new UsageError(`--max-steps must be a positive integer, got "${rawMaxSteps}".`, "INVALID_FLAG_VALUE");
+        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, WORKFLOW_MAX_RETRIES);
+        const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
+        const controller = new AbortController();
+        let timedOut = false;
+        let signalExitCode;
+        const interrupt = (signal) => {
+            signalExitCode = signal === "SIGINT" ? 130 : 143;
+            controller.abort(new Error(`Workflow run interrupted by ${signal}.`));
+        };
+        const onSigint = () => interrupt("SIGINT");
+        const onSigterm = () => interrupt("SIGTERM");
+        process.once("SIGINT", onSigint);
+        process.once("SIGTERM", onSigterm);
+        const timer = timeoutMs === undefined
+            ? undefined
+            : setTimeout(() => {
+                timedOut = true;
+                controller.abort(new Error(`Workflow run timed out after ${timeoutMs}ms.`));
+            }, timeoutMs);
+        timer?.unref?.();
+        try {
+            const result = await runWorkflowSteps({
+                target: args.target,
+                parameterFlags,
+                ...(maxSteps !== undefined ? { maxSteps } : {}),
+                ...(maxRetries !== undefined ? { maxRetries } : {}),
+                signal: controller.signal,
+            });
+            const rendered = { ...result, ...(timedOut ? { timedOut: true } : {}) };
+            output("workflow-run", rendered);
+            if (result.run.status === "failed" || result.gateRejection || result.aborted) {
+                process.exitCode = signalExitCode ?? EXIT_CODES.GENERAL;
             }
         }
-        const result = await runWorkflowSteps({
-            target: args.target,
-            ...(args.params ? { params: parseWorkflowJsonObject(args.params, "--params") } : {}),
-            ...(maxSteps !== undefined ? { maxSteps } : {}),
-        });
-        output("workflow-run", result);
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+        }
     },
 });
+const WORKFLOW_RUN_VALUE_FLAGS = new Set([
+    "max-steps",
+    "maxSteps",
+    "max-retries",
+    "maxRetries",
+    "timeout",
+    "format",
+    "detail",
+    "shape",
+    "output",
+]);
+const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set(["quiet", "verbose", "help", "no-quiet", "no-verbose"]);
+export function parseWorkflowParameterFlags(rawArgs, target) {
+    const flags = [];
+    let targetSeen = false;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = rawArgs[index];
+        if (token === "--") {
+            throw new UsageError("`akm workflow run` does not accept positional arguments after `--`.", "INVALID_FLAG_VALUE");
+        }
+        if (!token.startsWith("-") || token === "-" || /^-\d/.test(token)) {
+            if (!targetSeen) {
+                if (token !== target) {
+                    throw new UsageError("Workflow parameter flags must come after the workflow ref or run id.", "INVALID_FLAG_VALUE");
+                }
+                targetSeen = true;
+                continue;
+            }
+            throw new UsageError(`Unexpected positional workflow argument "${token}".`, "INVALID_FLAG_VALUE");
+        }
+        if (!token.startsWith("--"))
+            continue;
+        const body = token.slice(2);
+        const equalsAt = body.indexOf("=");
+        const name = equalsAt === -1 ? body : body.slice(0, equalsAt);
+        const inlineValue = equalsAt === -1 ? undefined : body.slice(equalsAt + 1);
+        if (name === "params") {
+            throw new UsageError("--params was removed. Pass each declared workflow parameter as its own flag, for example `--version=1.2.3`.", "INVALID_FLAG_VALUE");
+        }
+        if (WORKFLOW_RUN_VALUE_FLAGS.has(name)) {
+            if (inlineValue === undefined)
+                index += 1;
+            continue;
+        }
+        if (WORKFLOW_RUN_BOOLEAN_FLAGS.has(name))
+            continue;
+        if (!targetSeen) {
+            throw new UsageError("Workflow parameter flags must come after the workflow ref or run id.", "INVALID_FLAG_VALUE");
+        }
+        if (inlineValue !== undefined) {
+            flags.push({ name, value: inlineValue });
+            continue;
+        }
+        const next = rawArgs[index + 1];
+        if (next !== undefined && (!next.startsWith("-") || /^-\d/.test(next))) {
+            flags.push({ name, value: next });
+            index += 1;
+        }
+        else {
+            flags.push({ name, value: true });
+        }
+    }
+    return flags;
+}
+function parseIntegerFlag(raw, name, minimum, maximum) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!/^\d+$/.test(raw) || value < minimum || (maximum !== undefined && value > maximum)) {
+        const range = maximum === undefined ? `at least ${minimum}` : `from ${minimum} through ${maximum}`;
+        throw new UsageError(`${name} must be an integer ${range}, got "${raw}".`, "INVALID_FLAG_VALUE");
+    }
+    return value;
+}
+function parseWorkflowTimeout(raw) {
+    if (raw === undefined)
+        return undefined;
+    const match = /^(\d+)(ms|s|m)?$/.exec(raw);
+    if (!match) {
+        throw new UsageError(`--timeout must be N, Nms, Ns, or Nm, got "${raw}".`, "INVALID_FLAG_VALUE");
+    }
+    const amount = Number(match[1]);
+    const multiplier = match[2] === "m" ? 60_000 : match[2] === "s" ? 1_000 : 1;
+    const timeoutMs = amount * multiplier;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > WORKFLOW_MAX_TIMEOUT_MS) {
+        throw new UsageError(`--timeout must resolve to 1 through ${WORKFLOW_MAX_TIMEOUT_MS} milliseconds, got "${raw}".`, "INVALID_FLAG_VALUE");
+    }
+    return timeoutMs;
+}
 const workflowBriefCommand = defineJsonCommand({
     meta: {
         name: "brief",
@@ -433,9 +459,6 @@ export const workflowCommand = defineGroupCommand({
         description: "Author, inspect, and execute step-by-step workflow assets",
     },
     subCommands: {
-        start: workflowStartCommand,
-        next: workflowNextCommand,
-        complete: workflowCompleteCommand,
         status: workflowStatusCommand,
         list: workflowListCommand,
         create: workflowCreateCommand,

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

@@ -52,8 +52,10 @@
  */
 import path from "node:path";
 import { isDangerousEnvKey } from "../../../commands/lint/env-key-rules.js";
+import { taskFieldProblems } from "../../../tasks/schema.js";
 import { compileWorkflowPlan } from "../../../workflows/ir/compile.js";
 import { parseWorkflow } from "../../../workflows/parser.js";
+import { conceptIdForStashFile } from "../../asset/resolve-ref.js";
 /** Recommended `category` values for facts — `commands/lint/fact-linter.ts:9`. */
 const KNOWN_CATEGORIES = new Set(["personal", "team", "project", "convention", "meta"]);
 /** Placeholder markers a workflow stub carries — `commands/lint/workflow-linter.ts:10`. */
@@ -152,8 +154,12 @@ function collectSuppressedKeys(raw) {
 /**
  * env/secret dangerous-key scan (`lint/index.ts:191-218` + `env-key-rules.ts#checkEnvForDangerousKeys`),
  * keyed on `type` and preserving the `.env`-suffix narrowness (see file header).
- * Reads the overlay `raw`, not disk. `type`==="env" ⇒ ref prefix `env:`;
- * `type`==="secret" ⇒ `secret:` (`lint/index.ts:201-204`).
+ * Reads the overlay `raw`, not disk.
+ *
+ * The emitted `Ref:` comes from `conceptIdForStashFile` — the one place that
+ * spells a diagnostic ref the way `akm show` accepts it. It used to be
+ * hand-built as `env:<base>` / `secret:<base>`, a colon grammar the 0.9.0 ref
+ * parser rejects outright — a dead-end ref on a *security* finding.
  */
 export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     if (type !== "env" && type !== "secret")
@@ -161,9 +167,8 @@ export function dangerousEnvKeyDiagnostics(type, relPath, raw) {
     const baseNameWithExt = path.basename(relPath);
     if (!baseNameWithExt.endsWith(".env"))
         return []; // NARROWNESS: collectEnvFiles only visits *.env
-    const refPrefix = type === "env" ? "env" : "secret";
-    const baseName = path.basename(relPath, ".env");
-    const ref = baseName === "" ? `${refPrefix}:.env` : `${refPrefix}:${baseName}`;
+    // `relPath` is already stash-root-relative, so "." IS the stash root here.
+    const ref = conceptIdForStashFile(type, ".", relPath);
     const keys = scanKeys(raw);
     const suppressed = collectSuppressedKeys(raw);
     const diagnostics = [];
@@ -259,17 +264,16 @@ export function factDiagnostics(relPath, data) {
     }
     return [];
 }
-/** TaskLinter extra check (`task-linter.ts:25-58`). `data` is the parsed YAML. */
+/**
+ * TaskLinter extra check (`task-linter.ts:25-58`). `data` is the parsed YAML.
+ * Field rules come from the shared {@link taskFieldProblems} (see its doc for
+ * the lint-vs-parser reconciliation story); this sweep additionally requires
+ * at least one target.
+ */
 export function taskDiagnostics(relPath, data) {
     if (data === null || Object.keys(data).length === 0)
         return [];
-    const missing = [];
-    if (!("schedule" in data) || typeof data.schedule !== "string" || data.schedule.trim() === "") {
-        missing.push("schedule");
-    }
-    if (!("enabled" in data) || typeof data.enabled !== "boolean") {
-        missing.push("enabled (must be a boolean)");
-    }
+    const missing = taskFieldProblems(data);
     const hasTarget = "prompt" in data || "workflow" in data || "command" in data;
     if (!hasTarget)
         missing.push("prompt, workflow, or command");

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

@@ -12,11 +12,13 @@
  *
  * ── validate (spec §6 task validation column) ──
  *
- * A task must declare a `schedule`, an `enabled` boolean, and EXACTLY ONE
- * target (`prompt` XOR `workflow` XOR `command`). The akm adapter's
- * `TaskLinter` port checks "at least one" target; the native task family here is
- * STRICTER — declaring two targets is `invalid-task-yaml`. So this adapter owns
- * a purpose-built one-target check rather than reusing that port.
+ * A task must declare `version: 2`, a `schedule`, and EXACTLY ONE target
+ * (`prompt` XOR `workflow` XOR `command`). `enabled` is OPTIONAL — the parser
+ * defaults it to `true`, so an omitted field means an ACTIVE task — but must
+ * be a boolean when present. The akm adapter's `TaskLinter` port checks
+ * "at least one" target; the native task family here is STRICTER — declaring
+ * two targets is `invalid-task-yaml`. So this adapter owns a purpose-built
+ * one-target check rather than reusing that port.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -25,6 +27,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { taskFieldProblems } from "../../../tasks/schema.js";
 import { hashContent } from "./shared.js";
 /** A native task bundle is single-component; its one component is `main`. */
 const COMPONENT_ID = "main";
@@ -68,15 +71,15 @@ function parseTaskYaml(raw) {
     }
     return {};
 }
-/** The native `invalid-task-yaml` check: schedule + enabled(boolean) + EXACTLY ONE target. */
+/**
+ * The native `invalid-task-yaml` check: the shared field rules
+ * ({@link taskFieldProblems} — see its doc for the lint-vs-parser
+ * reconciliation story) plus this adapter's stricter EXACTLY-ONE-target rule.
+ */
 function taskDiagnostics(relPath, data) {
     if (Object.keys(data).length === 0)
         return [];
-    const problems = [];
-    if (typeof data.schedule !== "string" || data.schedule.trim() === "")
-        problems.push("schedule");
-    if (typeof data.enabled !== "boolean")
-        problems.push("enabled (must be a boolean)");
+    const problems = taskFieldProblems(data);
     const targets = TARGET_KEYS.filter((k) => k in data && data[k] !== undefined && data[k] !== null);
     if (targets.length === 0)
         problems.push("exactly one target (prompt, workflow, or command)");

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

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

package/dist/core/asset/frontmatter.js

@@ -176,6 +176,28 @@ function countLines(text) {
         return 0;
     return text.split(/\r?\n/).length - 1;
 }
+/**
+ * Insert one `key: value` line just before the closing `---` of an existing
+ * frontmatter block, leaving every other byte — YAML comments, quoting, key
+ * order, line endings — untouched. Returns null when `raw` has no well-formed
+ * block, so callers can fall back to a parse-and-serialize path.
+ *
+ * This is the source-preserving way to ADD a field to user-authored
+ * frontmatter: round-tripping the mapping through the YAML serializer drops
+ * comments and normalizes formatting, which is unacceptable for a write that
+ * only needs to contribute one line. Shared by `ensureAkmMarkdownType`
+ * (stamping `updated:` on write) and lint's `--fix` for `missing-updated`.
+ */
+export function spliceFrontmatterLine(raw, line) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---")
+        return null;
+    const closeIdx = lines.findIndex((l, i) => i > 0 && l.trim() === "---");
+    if (closeIdx === -1)
+        return null;
+    lines.splice(closeIdx, 0, line);
+    return lines.join("\n");
+}
 /**
  * Parse a YAML scalar value (string, boolean, or number).
  *

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

@@ -34,7 +34,7 @@
  * grammar to bridge any more.
  */
 import { NotFoundError, UsageError } from "../errors.js";
-import { placementSpecFor, stashDirFor, typeForStashDir } from "./asset-placement.js";
+import { deriveCanonicalAssetNameFromStashRoot, placementSpecFor, stashDirFor, typeForStashDir, } from "./asset-placement.js";
 import { isBundleSlug, parseBundleRef } from "./asset-ref.js";
 /**
  * Resolve a maybe-short input ref to a fully-qualified {@link ResolvedRef}
@@ -97,6 +97,19 @@ export function conceptIdFromTypeName(type, name) {
     const stashDir = stashDirFor(type);
     return stashDir !== undefined ? `${stashDir}/${name}` : name;
 }
+/**
+ * User-facing conceptId for a file on disk, derived through the placement
+ * spec's canonical-name rule — the ONE way a diagnostic should spell a ref it
+ * expects the user to paste into `akm show`. (The dangerous-env-key lint used
+ * to hand-build `env:<base>` colon refs the parser rejects; both its emission
+ * sites now route through here.) For a type with no placement spec — which no
+ * built-in caller passes — falls back to the raw name so the output is still
+ * informative rather than empty.
+ */
+export function conceptIdForStashFile(type, stashRoot, filePath) {
+    const name = deriveCanonicalAssetNameFromStashRoot(type, stashRoot, filePath);
+    return name === undefined ? filePath : conceptIdFromTypeName(type, name);
+}
 /**
  * Build the USER-FACING / envelope ref string for an indexed item, applying the
  * Chunk-5 flip F4b output-spelling rule (orchestrator decision; ref-grammar
@@ -116,8 +129,15 @@ export function conceptIdFromTypeName(type, name) {
  *     derived slug bundle id, never the retired `origin//type:name` spelling.
  */
 export function displayRef(item, defaultBundleId) {
-    const conceptId = item.conceptId ?? conceptIdFromTypeName(item.type, item.name);
-    const { bundleId } = item;
+    return displayRefForConceptId(item.conceptId ?? conceptIdFromTypeName(item.type, item.name), item.bundleId, defaultBundleId);
+}
+/**
+ * The F4b output-spelling flip itself, for a caller that already holds the
+ * conceptId (no `type`/`name` derivation needed — e.g. lint findings built
+ * from {@link conceptIdForStashFile}). {@link displayRef} delegates here, so
+ * the short-default / qualified-secondary rule still has exactly one home.
+ */
+export function displayRefForConceptId(conceptId, bundleId, defaultBundleId) {
     // Default/primary bundle → SHORT conceptId (the flip).
     if (bundleId === undefined || bundleId === defaultBundleId)
         return conceptId;

package/dist/core/common.js

@@ -409,7 +409,7 @@ export async function fetchWithRetry(url, init, options) {
             if (attempt < maxRetries && shouldRetry(response.status)) {
                 const retryAfter = parseRetryAfter(response);
                 const delay = retryAfter ?? baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-                await new Promise((r) => setTimeout(r, delay));
+                await abortableDelay(delay, init?.signal);
                 continue;
             }
             return response;
@@ -417,12 +417,41 @@ export async function fetchWithRetry(url, init, options) {
         catch (err) {
             if (attempt >= maxRetries)
                 throw err;
+            // A caller-supplied abort is terminal: never keep retrying past it.
+            if (init?.signal?.aborted)
+                throw err;
             const delay = baseDelay * 2 ** attempt * (0.5 + Math.random() * 0.5);
-            await new Promise((r) => setTimeout(r, delay));
+            await abortableDelay(delay, init?.signal);
         }
     }
     throw new Error("fetchWithRetry: unreachable");
 }
+/**
+ * Sleep, but wake immediately if `signal` aborts.
+ *
+ * A server-supplied `Retry-After` is honored verbatim and can be arbitrarily
+ * large. Sleeping it out with a bare `setTimeout` ignored the caller's abort
+ * signal entirely, so a single `429` could park an operation far past any
+ * deadline its caller believed it had imposed — the request timeout bounds
+ * only the request, never the wait between attempts.
+ */
+function abortableDelay(ms, signal) {
+    if (!signal)
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? new Error("Aborted"));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error("Aborted"));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 function shouldRetry(status) {
     return status === 429 || status >= 500;
 }
@@ -628,6 +657,20 @@ export function toErrorMessage(error) {
 export function todayIso() {
     return new Date().toISOString().slice(0, 10);
 }
+/**
+ * `YYYY-MM-DD` in LOCAL time — deliberately not {@link todayIso}, which is
+ * UTC and can differ near midnight. This is the spelling the `updated:`
+ * frontmatter stampers share (`core/asset/akm-markdown.ts` on write,
+ * `commands/lint/base-linter.ts` on `--fix`), so the field's format has one
+ * definition even though the two stampers pick different instants (now vs
+ * file mtime).
+ */
+export function localDateStamp(d) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
 /**
  * Return a filesystem-safe timestamp string derived from the current instant.
  * Colons and dots are replaced with hyphens so the result is safe as a

package/dist/core/config/config-schema.js

@@ -234,6 +234,14 @@ export const AkmConfigSchema = AkmConfigBaseSchema.superRefine((config, ctx) =>
             message: "llmEngine must name an LLM engine",
         });
     }
+    const workflowJudge = config.workflow?.judgeEngine;
+    if (workflowJudge && !config.engines?.[workflowJudge]) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["workflow", "judgeEngine"],
+            message: "judgeEngine does not name a configured engine",
+        });
+    }
     const defaultStrategy = config.defaults?.improveStrategy;
     if (defaultStrategy &&
         !BUILTIN_IMPROVE_STRATEGY_NAMES.includes(defaultStrategy) &&