akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/workflows/source-ir/schema.js

@@ -14,8 +14,8 @@ import { validateExtraParams } from "../../core/extra-params.js";
 import { checkJsonSchemaDefinition } from "../../core/json-schema.js";
 import { parseReference } from "../program/expressions.js";
 import { PROGRAM_RETRY_REASONS } from "../program/schema.js";
-import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXEC_ARG_BYTES, WORKFLOW_MAX_EXEC_ARGV, WORKFLOW_MAX_EXEC_CWD_LENGTH, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
-import { canonicalTopologicalJobs, compareWorkflowSourceCodePoints } from "./ordering.js";
+import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXEC_ARG_BYTES, WORKFLOW_MAX_EXEC_ARGV, WORKFLOW_MAX_EXEC_CWD_LENGTH, WORKFLOW_MAX_EXEC_PASS_ENV, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_GATE_LOOPS, WORKFLOW_MAX_INPUTS, WORKFLOW_MAX_MAP_EXPANSION, WORKFLOW_MAX_OUTPUTS, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_RETRIES, WORKFLOW_MAX_ROUTE_BRANCHES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "../resource-limits.js";
+import { compareWorkflowSourceCodePoints } from "./compare.js";
 import { canonicalizeWorkflowCron, canonicalizeWorkflowRun, canonicalizeWorkflowWorkingDirectory, classifyWorkflowStepUses, rejectNulInArgv, validateWorkflowBuiltinCommand, WorkflowSourceSemanticError, } from "./semantics.js";
 export const WORKFLOW_SOURCE_IR_VERSION = 1;
 export const WORKFLOW_SOURCE_IR_MAX_BYTES = 2 * 1024 * 1024;
@@ -35,6 +35,7 @@ export function decodeWorkflowSourceIrV1(input, options = {}) {
         "description",
         "tags",
         "params",
+        "outputs",
         "defaults",
         "budget",
         "preamble",
@@ -50,6 +51,7 @@ export function decodeWorkflowSourceIrV1(input, options = {}) {
     optionalString(root.preamble, "preamble");
     optionalStringList(root.tags, "tags", 256);
     validateParams(root.params);
+    validateOutputs(root.outputs);
     validateUnit(root.defaults, "defaults", true);
     validateBudget(root.budget);
     span(root.source, "source");
@@ -58,8 +60,8 @@ export function decodeWorkflowSourceIrV1(input, options = {}) {
         fail("triggers must contain 1 through 64 entries");
     }
     validateTriggers(root.triggers);
-    if (!Array.isArray(root.jobs) || root.jobs.length === 0 || root.jobs.length > 256) {
-        fail("jobs must contain 1 through 256 entries");
+    if (!Array.isArray(root.jobs) || root.jobs.length !== 1) {
+        fail("jobs must contain exactly 1 entry");
     }
     const jobIds = new Set();
     for (const [index, job] of root.jobs.entries())
@@ -69,7 +71,6 @@ export function decodeWorkflowSourceIrV1(input, options = {}) {
             if (!jobIds.has(need))
                 fail(`job ${job.id} needs missing job ${need}`);
     }
-    validateTopologicalJobs(root.jobs);
     return decoded;
 }
 function validateTrigger(value, index) {
@@ -177,6 +178,9 @@ function validateStep(value, jobId, index, stepIds, options) {
         fail(`step ${id} uses must be a non-empty string`);
     if (step.run !== undefined && !hasRun)
         fail(`step ${id} run must be a non-empty string`);
+    // A-N3: captured at the outer scope so scalarRecord's task-scoped widening
+    // (below) can consult it without re-classifying `step.uses`.
+    let usesTarget;
     if (hasUses) {
         let target;
         try {
@@ -185,6 +189,7 @@ function validateStep(value, jobId, index, stepIds, options) {
         catch (cause) {
             semanticFail(cause, `step ${id} uses`);
         }
+        usesTarget = target;
         if (target.kind === "builtin-command") {
             if (step.commandMode !== "literal" &&
                 step.commandMode !== "portable-template" &&
@@ -214,7 +219,13 @@ function validateStep(value, jobId, index, stepIds, options) {
         }
     }
     validateExec(step.exec, `step ${id} exec`, options);
-    scalarRecord(step.with, `step ${id} with`, true);
+    // A-N3, widened in P3a (spec docs/plans/specs/p3a-plan-v5-child-freeze.md
+    // §4.2 step 7, row B-10, A-N8): the "must be a scalar" restriction narrows
+    // to non-task, non-workflow targets only. A tasks/<ref> or workflows/<ref>
+    // step's with: may carry any JSON value the bounded document front end
+    // already accepts; freeze (src/workflows/freeze/**) decides what a
+    // declared input/param actually accepts.
+    scalarRecord(step.with, `step ${id} with`, true, usesTarget?.kind === "task" || usesTarget?.kind === "workflow");
     environment(step.env, `step ${id} env`);
     rejectStepWithExpressions(step, id);
     rejectExpressionsInRecord(step.env, `step ${id} env`);
@@ -258,17 +269,6 @@ function validateStep(value, jobId, index, stepIds, options) {
     extensions(step.extensions, `step ${id} extensions`);
     span(step.source, `step ${id} source`);
 }
-function validateTopologicalJobs(jobs) {
-    const result = canonicalTopologicalJobs(jobs);
-    if (!result.ok) {
-        if (result.kind === "missing")
-            fail(`job ${result.job.id} needs missing job ${result.dependency}`);
-        fail("jobs contain a dependency cycle");
-    }
-    if (result.jobs.some((job, index) => job.id !== jobs[index]?.id)) {
-        fail("jobs are not in canonical dependency-topological order");
-    }
-}
 function compareCodePoints(left, right) {
     return compareWorkflowSourceCodePoints(left, right);
 }
@@ -441,10 +441,13 @@ function validateRouteTargets(steps, jobId) {
         }
     }
 }
-function validateReference(value, location) {
+function validateReference(value, location, expectedKind) {
     const parsed = parseReference(value);
     if (!parsed.ok)
         fail(`${location} is invalid: ${parsed.message}`);
+    if (expectedKind && parsed.expr.kind !== expectedKind) {
+        fail(`${location} must reference a step output (steps.<id>.output...), not a param`);
+    }
 }
 function validateParams(value) {
     if (value === undefined)
@@ -459,6 +462,30 @@ function validateParams(value) {
         validateSchema(schema, `params.${name}`, false);
     }
 }
+/**
+ * Structural re-validation of `outputs:` (P3b, spec §4.2) — the parser
+ * (`../parser.ts`) already enforces the same rules at authoring time; this is
+ * the corruption-gate re-check every source-IR field gets, mirroring
+ * `validateParams` immediately above.
+ */
+function validateOutputs(value) {
+    if (value === undefined)
+        return;
+    const outputs = record(value, "outputs");
+    if (Object.keys(outputs).length === 0 || Object.keys(outputs).length > WORKFLOW_MAX_OUTPUTS) {
+        fail(`outputs must contain 1 through ${WORKFLOW_MAX_OUTPUTS} entries`);
+    }
+    for (const [name, declaration] of Object.entries(outputs)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            fail(`outputs has invalid name ${name}`);
+        const decl = record(declaration, `outputs.${name}`);
+        keys(decl, ["from", "schema"], `outputs.${name}`);
+        nonEmptyString(decl.from, `outputs.${name}.from`);
+        validateReference(decl.from, `outputs.${name}.from`, "stepOutput");
+        if (decl.schema !== undefined)
+            validateSchema(decl.schema, `outputs.${name}.schema`, false);
+    }
+}
 function validateBudget(value) {
     if (value === undefined)
         return;
@@ -545,14 +572,25 @@ function rejectExpressionsInRecord(value, location) {
             fail(`${location}.${key} contains an unsupported expression`);
     }
 }
+/** A-N3: recurses into nested values, since a task step's with: may now carry an object/array. */
+function containsUnsupportedExpression(value) {
+    if (typeof value === "string")
+        return value.includes("${{");
+    if (Array.isArray(value))
+        return value.some((item) => containsUnsupportedExpression(item));
+    if (value !== null && typeof value === "object") {
+        return Object.values(value).some((item) => containsUnsupportedExpression(item));
+    }
+    return false;
+}
 function rejectStepWithExpressions(step, id) {
     if (step.with === undefined)
         return;
     for (const [key, item] of Object.entries(record(step.with, `step ${id} with`))) {
-        if (typeof item !== "string" || !item.includes("${{"))
-            continue;
         if (step.uses === "akm/command" && step.commandMode === "literal" && key === "content")
             continue;
+        if (!containsUnsupportedExpression(item))
+            continue;
         fail(`step ${id} with.${key} contains an unsupported expression`);
     }
 }
@@ -722,13 +760,23 @@ function stringList(value, location, max, allowEmpty) {
         seen.add(item);
     }
 }
-function scalarRecord(value, location, allowNull) {
+/**
+ * `allowNonScalar` (A-N3, P2b; widened in P3a, A-N8): when true (a
+ * `tasks/<ref>` or `workflows/<ref>` step's `with:`), the key-grammar check
+ * still runs but the scalar/null value restriction is skipped entirely — a
+ * declared object/array-typed input or param, or a `{from: "..."}`
+ * reference, may decode. Every other target keeps the byte-identical
+ * scalar-or-null restriction.
+ */
+function scalarRecord(value, location, allowNull, allowNonScalar = false) {
     if (value === undefined)
         return;
     const map = record(value, location);
     for (const [key, item] of Object.entries(map)) {
         if (!/^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/.test(key))
             fail(`${location} has invalid key ${key}`);
+        if (allowNonScalar)
+            continue;
         if (item === null && allowNull)
             continue;
         if (typeof item !== "string" && typeof item !== "number" && typeof item !== "boolean") {

package/dist/workflows/source-ir/semantics.js

@@ -6,7 +6,6 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseBuiltinCommandAction } from "../../commands/command/builtin-action.js";
 import { validatePortableCommandTemplate } from "../../commands/command/portable-template.js";
-import { bundleRefToString, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseSchedule } from "../../tasks/schedule.js";
 import { classifyWorkflowSourceUses } from "./uses.js";
 const TOKEN_SAFE_RUN = /^[A-Za-z0-9_./:@+=,-]+(?: [A-Za-z0-9_./:@+=,-]+)*$/;
@@ -83,9 +82,6 @@ export function classifyWorkflowStepUses(value, classifier = classifyWorkflowSou
     if (value.length === 0 || value.trim() !== value || /\s/.test(value)) {
         throw new WorkflowSourceSemanticError("unsupported-uses-target", "uses must be one exact, non-empty executable ref");
     }
-    const task = canonicalTaskTarget(value);
-    if (task)
-        return task;
     let target;
     try {
         target = classifier(value);
@@ -93,29 +89,15 @@ export function classifyWorkflowStepUses(value, classifier = classifyWorkflowSou
     catch (cause) {
         throw usesFailure(value, cause);
     }
-    if (target.kind === "github-action") {
-        throw new WorkflowSourceSemanticError("remote-action-acquisition-out-of-scope", `Remote action acquisition is out of scope for ${JSON.stringify(value)}.`);
-    }
-    if (target.kind === "workflow") {
-        throw new WorkflowSourceSemanticError("nested-workflow-unsupported", `Nested workflow target ${JSON.stringify(value)} is unsupported in a workflow step.`);
-    }
+    // P3a (docs/plans/specs/p3a-plan-v5-child-freeze.md §1.3(2)/§4, A-N4): a
+    // `kind: "workflow"` target used to throw `nested-workflow-unsupported`
+    // here. That rejection is REMOVED — classification returns the workflow
+    // target like any other target-ref-shaped `uses:`, and freeze decides
+    // (`src/workflows/freeze/targets/child-workflow.ts`, the ONE recursive
+    // child-workflow resolver both the direct and task-wrapped composition
+    // forms route through).
     return target;
 }
-function canonicalTaskTarget(value) {
-    try {
-        const parsed = parseBundleRef(value);
-        if (parsed.fragment !== undefined || bundleRefToString(parsed) !== value)
-            return undefined;
-        const slash = parsed.conceptId.indexOf("/");
-        if (slash < 0 || parsed.conceptId.slice(0, slash) !== "tasks" || parsed.conceptId.length === slash + 1) {
-            return undefined;
-        }
-        return { kind: "task", ref: value };
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Validate AKM's built-in command action at the shared source/decoder boundary.
  *

package/dist/workflows/source-ir/triggers.js

@@ -0,0 +1,79 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { asRecord, checkKeys, cloneBoundedJson, noGithubExpression, own, presentJsonValue, sourceError, stringField, TASK_V3_MAX_SCHEDULES, } from "../../tasks/source/bounded-document.js";
+const SOURCE_LABEL = "task v3 source";
+function ctxFrom(options) {
+    return {
+        filePath: options.filePath,
+        sourceLabel: SOURCE_LABEL,
+        ...(options.lineAt ? { lineAt: options.lineAt } : {}),
+    };
+}
+const ON_KEYS = ["schedule", "workflow_dispatch"];
+function parseOn(value, ctx) {
+    const input = asRecord(value, ctx, ["on"]);
+    const keys = Object.keys(input);
+    if (keys.length === 0)
+        sourceError(ctx, ["on"], "must declare schedule and/or workflow_dispatch.");
+    const unsupported = keys.find((key) => !ON_KEYS.includes(key));
+    if (unsupported)
+        sourceError(ctx, ["on", unsupported], "is an unsupported local service event; no scheduler binding was created.");
+    const schedules = [];
+    if (own(input, "schedule")) {
+        if (!Array.isArray(input.schedule) || input.schedule.length === 0) {
+            sourceError(ctx, ["on", "schedule"], "must be a non-empty list of {cron: string} records.");
+        }
+        if (input.schedule.length > TASK_V3_MAX_SCHEDULES) {
+            sourceError(ctx, ["on", "schedule"], `accepts at most ${TASK_V3_MAX_SCHEDULES} entries.`);
+        }
+        for (const [index, raw] of input.schedule.entries()) {
+            const entry = asRecord(raw, ctx, ["on", "schedule", index]);
+            checkKeys(entry, ["cron"], ctx, ["on", "schedule", index]);
+            if (!own(entry, "cron"))
+                sourceError(ctx, ["on", "schedule", index, "cron"], "is required.");
+            const cron = stringField(entry.cron, ctx, ["on", "schedule", index, "cron"], { nonempty: true });
+            noGithubExpression(cron, ctx, ["on", "schedule", index, "cron"]);
+            schedules.push(Object.freeze({ cron, source: `on.schedule[${index}].cron`, ordinal: index }));
+        }
+    }
+    let manual = false;
+    if (own(input, "workflow_dispatch")) {
+        const dispatch = input.workflow_dispatch;
+        if (dispatch !== null) {
+            const mapping = asRecord(presentJsonValue(dispatch, ctx, ["on", "workflow_dispatch"]), ctx, [
+                "on",
+                "workflow_dispatch",
+            ]);
+            if (Object.keys(mapping).length > 0) {
+                sourceError(ctx, ["on", "workflow_dispatch"], "must be null or an empty mapping; inputs are unsupported.");
+            }
+        }
+        manual = true;
+    }
+    return Object.freeze({ manual, schedules: Object.freeze(schedules) });
+}
+/**
+ * `on:` is the one canonical scheduling source a workflow YAML trigger
+ * fragment has a live caller for (see file header — the task-v3 `akm:`
+ * options bag this used to also accept is deleted, along with the
+ * "exactly one scheduling source" choice between the two).
+ */
+function compileTriggers(input, ctx) {
+    if (!own(input, "on"))
+        sourceError(ctx, ["on"], "is required.");
+    return parseOn(presentJsonValue(input.on, ctx, ["on"]), ctx);
+}
+/**
+ * Classify the strict trigger fragment `{on}` into deterministic local
+ * scheduler bindings. Full workflow adapters pass only that one field; this
+ * rejects `jobs` and every other workflow field (and, since the review fix
+ * above, `akm` too) rather than owning the document grammar.
+ */
+export function classifyWorkflowYamlTriggers(value, options) {
+    const ctx = ctxFrom(options);
+    const cloned = cloneBoundedJson(value, ctx, [], { nodes: 0 });
+    const input = asRecord(cloned, ctx, []);
+    checkKeys(input, ["on"], ctx, []);
+    return compileTriggers(input, ctx);
+}

package/dist/workflows/source-ir/uses.js

@@ -2,13 +2,39 @@
 // 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/.
 /**
- * Workflow source adapters deliberately do not own an executable-ref grammar.
- * `tasks/...` is the one workflow-only target and is recognized by
- * `classifyWorkflowStepUses`; every remaining target delegates here to WP6's
- * canonical task-v3 classifier.
+ * The workflow `uses:` classification seam (P1a Lane B,
+ * docs/plans/specs/p1a-with-rejection-classifier.md §4.2).
+ *
+ * `classifyWorkflowSourceUses` is the canonical non-task `uses:` classifier
+ * used by direct source-IR decoding (and, via `compile.ts`, by the GitHub-YAML
+ * entrypoint): it recognizes the `akm/command` builtin special case and
+ * otherwise delegates to `classifyTargetRef` (src/execution/target-ref.ts),
+ * the canonical classifier for `commands/`, `scripts/`, `tasks/`, and
+ * `workflows/` asset refs — including `tasks/...` targets, for which
+ * `classifyTargetRef`'s own `tasks/` arm is the one authority (brief §8.1;
+ * P4 deleted `classifyWorkflowStepUses`'s `canonicalTaskTarget` pre-check in
+ * semantics.ts, which used to match them first).
+ *
+ * This module imports NOTHING from `src/tasks/source-v3.ts`: workflow `uses:`
+ * classification no longer delegates to the task-v3 grammar, and (P4) native
+ * target classification recognizes no GitHub Action variant at all —
+ * `WorkflowSourceUsesTarget` below has no `github-action` member, typed or
+ * otherwise.
+ */
+import { classifyTargetRef } from "../../execution/target-ref.js";
+/**
+ * Canonical non-task classifier used by direct source-IR decoding (and the
+ * GitHub-YAML entrypoint's default, wired via compile.ts). Layers the
+ * `akm/command` builtin special case over `classifyTargetRef`, which throws
+ * `UsageError` `TARGET_REF_INVALID` for anything else.
  */
-import { classifyTaskV3Uses } from "../../tasks/source-v3.js";
-/** Canonical non-task classifier used by direct source-IR decoding. */
 export function classifyWorkflowSourceUses(value) {
-    return classifyTaskV3Uses(value);
+    if (value === "akm/command") {
+        return Object.freeze({ kind: "builtin-command", ref: "akm/command" });
+    }
+    // classifyTargetRef's return type is structurally identical to this
+    // module's `{ kind: "command" | "script" | "task" | "workflow"; ref:
+    // string }` union arm, so it is assignable to WorkflowSourceUsesTarget
+    // without a cast.
+    return classifyTargetRef(value);
 }

package/docs/migration/README.md

@@ -2,7 +2,7 @@
 
 Upgrade guides and per-release migration notes.
 
-- [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2 to task-v3 conversion, the single durable-v4 workflow boundary, and release behavior changes
+- [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes

package/docs/migration/release-notes/0.9.2.md

@@ -21,19 +21,95 @@ the recovery snapshot and migration 002's rebuild. Snapshot readers and targets
 are bound to their held inodes, not swappable pathnames. A failed snapshot path
 is reported and never removed by cleanup code.
 
-Task sources now use Task v3. Normal execution rejects task-v2 files; preview
-the repository-wide conversion with `akm migrate apply --dry-run`, review every
-`changed`, `skipped`, or `blocked` result, then run `akm migrate apply`. The
-migrator validates the replacement before it backs up and replaces a source,
-and ambiguous argv arrays remain blocked for manual review.
+Task sources now use task source v4. Normal execution rejects task-v3 and
+task-v2 files with `TASK_SCHEMA_VERSION_UNSUPPORTED`; preview the
+repository-wide conversion with `akm migrate apply --dry-run`, review every
+`changed`, `skipped`, or `blocked` result, then run `akm migrate apply` — it
+now runs both the v2→v3 and v3→v4 generations in one pass. The migrator
+validates each replacement before it backs up and replaces a source, and
+ambiguous cases (an argv array with no safe shell equivalent, a `with:`
+block with no v4 equivalent, an ambiguous scheduling source, and similar)
+remain blocked for manual review. Task source v4 adds typed `inputs:` with
+defaults, a single bounded `output:` schema, optional `schedule:`, and
+per-schedule-binding enablement. See
+[Task sources](../v0.9.1-to-v0.9.2.md#task-sources) and
+[The migration procedure](../v0.9.1-to-v0.9.2.md#the-migration-procedure).
+
+Task run history's `target.kind` result field also changed vocabulary:
+`"prompt"` is now `"command"` (an agent/LLM dispatch), and the old shared
+`"command"` split into `"shell"` and `"script"`. `akm task history` reads
+both generations of existing rows correctly, forever, keyed on a per-row
+`targetVocab` marker — but a pre-0.9.2 akm's decoder does not recognize
+that marker and **throws** reading a row this release (or later) wrote, so
+upgrade once and don't downgrade below 0.9.2 for a given `state.db`. See
+[Task history result vocabulary](../v0.9.1-to-v0.9.2.md#task-history-result-vocabulary-targetkind).
 
 Workflows now accept peer Markdown (`.md`) and GitHub-shaped YAML (`.yml`)
-sources through source IR v1. Runs freeze durable plan v4, the only executable
-plan format. Pre-v4 stored plans are rejected; start a new run from current
-source. A v4 resume does not re-read the authored workflow, configuration, or
-asset index. Scheduled fires are new starts, so they read the current source
-and create a fresh v4 freeze. V4 also rejects `inherit_env`; use exact named
-environment bindings and `pass_env` names instead.
+sources through source IR v1. Runs freeze durable plan `irVersion` 5, the
+only executable plan format. Pre-`irVersion`-5 stored plans cannot resume,
+next, complete, or run — `status`, `list`, and `abandon` keep working, and
+`akm workflow abandon <id>` followed by a fresh `akm workflow run <ref>`
+recovers a blocked run; no data is lost. A resume does not re-read the
+authored workflow, configuration, or asset index. Scheduled fires are new
+starts, so they read the current source and create a fresh freeze. `.yml`
+also rejects `inherit_env`; use exact named environment bindings and
+`pass_env` names instead. See
+[Workflow cutover](../v0.9.1-to-v0.9.2.md#workflow-cutover).
+
+A workflow step can now compose another workflow as a child — directly
+(`uses: workflows/<ref>`) or through a task whose own target is a workflow
+— bounded by composition depth, cycle detection, and aggregate embedded-plan
+size, all checked at freeze before the parent run is published. Running the
+step drives the child to completion inline, in the parent's own process:
+cancellation propagates because it is the same process, the child is
+independently resumable, and `akm workflow status` on the parent renders a
+`children:` tree. A workflow may also declare `outputs:` — a run-level
+export resolved once from persisted step evidence at completion, which a
+composing parent step promotes as its own output. See
+[Child workflows](../v0.9.1-to-v0.9.2.md#child-workflows) and
+[Workflow outputs](../v0.9.1-to-v0.9.2.md#workflow-outputs).
+
+A workflow step's `with:` on a `uses: tasks/<ref>` target now **binds** the
+task's declared `inputs:` — literal values or `{from: "steps.<id>.output…"}`
+references resolved just before dispatch (the reference grammar also
+accepts `{from: "params.<name>"}`, but a composing step's own document can
+never declare `params:`, so that form is not reachable in this release) —
+instead of being silently dropped. A `with:` on a task with no `inputs:`,
+or on a `commands/`/`scripts/` target (never binding surfaces), is now
+rejected at freeze rather than discarded. See
+[`with:` on a task-composed step now binds — or rejects](../v0.9.1-to-v0.9.2.md#with-on-a-task-composed-step-now-binds--or-rejects).
+
+Three recognized-but-limited constructs are removed outright in 0.9.2: the
+GitHub Action `uses:` locator (`owner/repo[/path]@ref`) is no longer
+recognized anywhere — it was always rejected before dispatch in every prior
+release, so this deletes the recognition, not a working capability;
+multi-job GitHub-shaped YAML is rejected at the source adapter instead of
+parsing clean and being refused later in two different places — split a
+multi-job document into single-job workflows composed with a child-workflow
+step; and the second task scheduling syntax (`akm.schedule` / a task's
+top-level `on:`) is gone along with task v3, leaving task source v4's
+optional top-level `schedule:` as the one canonical form. See
+[GitHub Action locators are no longer recognized anywhere](../v0.9.1-to-v0.9.2.md#github-action-locators-are-no-longer-recognized-anywhere)
+and
+[Multi-job YAML is rejected at the adapter boundary](../v0.9.1-to-v0.9.2.md#multi-job-yaml-is-rejected-at-the-adapter-boundary).
+
+Two new read-only introspection verbs: `akm workflow plan <ref>`
+(secret-free by construction) compiles, resolves, and freezes a workflow
+without publishing a run, printing the canonical step graph, target/child
+expansion, and input bindings; `akm task explain <ref>` prints a task's
+resolved target, declared and supplied `inputs:` (secret-shaped values
+redacted on a best-effort heuristic basis), and schedule bindings — its
+default and `--format json` output are the same raw JSON. See
+[New commands](../v0.9.1-to-v0.9.2.md#new-commands).
+
+Task-source, workflow-source, and composition failures now report
+phase-specific `UsageError` codes (`TASK_SOURCE_INVALID`,
+`TASK_SCHEMA_VERSION_UNSUPPORTED`, `TARGET_REF_INVALID`,
+`WORKFLOW_SOURCE_INVALID`, `COMPOSITION_INVALID`, `INPUT_BINDING_INVALID`,
+`TASK_TARGET_UNSUPPORTED`, `WORKFLOW_OUTPUT_INVALID`,
+`WORKFLOW_IR_VERSION_UNSUPPORTED`) instead of the generic
+`INVALID_FLAG_VALUE`; exit codes are unchanged. See
+[Diagnostics](../v0.9.1-to-v0.9.2.md#diagnostics).
 
 `akm command run --dry-run` performs authorization and adapter lowering but
 does not dispatch or materialize credentials. It writes no authored source or

package/docs/migration/release-notes/README.md

@@ -7,8 +7,9 @@ live one level up in `docs/migration/`.
 
 ## Available notes
 
-- [0.9.2](0.9.2.md) — task v3, workflow source IR v1 and durable v4,
-  command diagnostics, and strategy judgment migration
+- [0.9.2](0.9.2.md) — task source v4 migration, workflow source IR v1 and
+  durable-v4-family `irVersion: 5`, command diagnostics, and strategy judgment
+  migration
 
 ## Adding notes for a new release
 

package/docs/migration/v0.8-to-v0.9.md

@@ -7,8 +7,8 @@ in place is not.
 ## What the upgrade preserves
 
 - authored assets that you copy into a current bundle;
-- task-v2 source files that the explicit task migrator can translate without
-  guessing;
+- task-v2 source files that the explicit task migrator can translate — through
+  task-v3 and on to task source v4 — without guessing;
 - package-manager or standalone-binary updates through `akm upgrade`.
 
 ## What it does not preserve
@@ -17,7 +17,7 @@ in place is not.
 - old `index.db`, `workflow.db`, task-history JSONL, or legacy lock/cache
   layouts;
 - old ref grammar or old workflow/task execution paths;
-- in-flight pre-v4 workflow plans.
+- in-flight workflow plans older than `irVersion: 5`.
 
 Those formats are not compatibility inputs to the current runtime. Keep an
 archive if you need historical inspection; do not place it in the live 0.9
@@ -70,16 +70,18 @@ for 0.8 databases.
 
 ### 4. Convert task-v2 sources explicitly
 
-Normal task execution accepts task v3 only. Preview every translation:
+Normal task execution accepts task source v4 only. Preview every translation:
 
 ```sh
 akm migrate status
 akm migrate apply --dry-run
 ```
 
-Review each `changed`, `skipped`, and `blocked` entry. The migrator blocks
-ambiguous argv arrays or any conversion whose execution meaning is not
-provable. Rewrite blocked files manually as task v3.
+Review each `changed`, `skipped`, and `blocked` entry. The migrator runs both
+generations in one pass — task-v2 to task-v3, then task-v3 to task source
+v4 — against the resulting files. It blocks ambiguous argv arrays or any
+conversion whose execution meaning is not provable. Rewrite blocked files
+manually as task source v4.
 
 Apply only after the preview is correct:
 
@@ -106,9 +108,9 @@ existing scheduler entry.
 ## Workflow boundary
 
 Current Markdown and GitHub-shaped YAML workflows compile to the same source
-IR and freeze durable plan IR v4. Durable v4 is the only executable stored
-plan. Do not copy an old workflow database expecting old runs to resume; start
-new runs from current authored sources.
+IR and freeze the durable plan v4 family's executable `irVersion: 5` format.
+That is the only executable stored plan. Do not copy an old workflow database
+expecting old runs to resume; start new runs from current authored sources.
 
 ## Recovery
 
@@ -117,6 +119,6 @@ and restore the archived 0.8 installation with its matching 0.8 executable.
 Do not mix old executable code with current state or current executable code
 with old state.
 
-For the task-v3 format and the narrower 0.9.1-to-0.9.2 transition, see
+For the task source v4 format and the narrower 0.9.1-to-0.9.2 transition, see
 [Tasks](../reference/tasks.md) and
 [Migrating from 0.9.1 to 0.9.2](v0.9.1-to-v0.9.2.md).

package/docs/migration/v0.9.0-troubleshooting.md

@@ -83,32 +83,39 @@ akm migrate status
 akm migrate apply --dry-run
 ```
 
-A blocked file is intentionally unchanged. Common causes are argv arrays,
-shell-sensitive command forms, invalid YAML, unsupported fields, or a source
-that cannot be proven writable. Rewrite that file manually as task v3 and
-preview again.
+The migrator runs two generations in one pass — task-v2 to task-v3, then
+task-v3 to task source v4 against the resulting files — and either
+generation can block a file. A blocked file is intentionally unchanged.
+Common causes at the v2-to-v3 stage are argv arrays, shell-sensitive command
+forms, invalid YAML, unsupported fields, or a source that cannot be proven
+writable; rewrite that file manually as task v3 and preview again. Common
+causes at the v3-to-v4 stage are a GitHub Action `uses:` locator (no v4
+equivalent) or a `with:` block on a non-command target (v4 wants declared
+`inputs:` instead); rewrite that file manually as task source v4 and preview
+again.
 
 The task migrator does not repair config or databases.
 
 ## Task migration was interrupted
 
 The migrator validates and backs up each changed task immediately before its
-atomic replacement. Re-run the preview. Already-current v3 files are skipped;
-remaining v2 files are planned again from their current bytes. A changed input
-generation fails closed instead of applying a stale plan.
+atomic replacement. Re-run the preview. Already-current task source v4 files
+are skipped; remaining v2 and v3 files are planned again from their current
+bytes. A changed input generation fails closed instead of applying a stale
+plan.
 
 Use the per-file backup only to reverse that file deliberately. Do not copy a
 backup over a file while a task sync or scheduler process is running.
 
 ## A workflow will not resume
 
-Only durable plan IR v4 executes. Pre-v4 stored plans are rejected rather than
-decoded by a compatibility runtime. Start a new run from the current Markdown
-or YAML workflow source.
+Only the durable plan v4 family's `irVersion: 5` executes. Pre-`irVersion`-5
+stored plans are rejected rather than decoded by a compatibility runtime.
+Start a new run from the current Markdown or YAML workflow source.
 
-For a v4 run, a missing or changed authored source is not a resume blocker: the
-run uses its frozen plan. A plan-hash or schema failure is durable-state
-corruption and must fail closed.
+For an `irVersion: 5` run, a missing or changed authored source is not a resume
+blocker: the run uses its frozen plan. A plan-hash or schema failure is
+durable-state corruption and must fail closed.
 
 ## A stale transaction journal is reported