akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/workflows/ir/plan-hash.js

@@ -2,18 +2,10 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Plan hashing for the frozen-plan contract (redesign addendum, R1).
- *
- * `workflow run` persists `plan_json` + `plan_hash` on the run row
- * (migration 006); every later invocation executes that snapshot. The hash is
- * the sha256 (hex) of the plan's CANONICAL JSON — object keys recursively
- * sorted — so two structurally-equal plans hash identically regardless of key
- * insertion order, and the same program always freezes to the same hash.
- *
- * Pure module: no IO beyond node:crypto, no engine imports.
+ * Plan hashing: sha256 of the plan's canonical JSON (keys recursively sorted),
+ * stored beside `plan_json` as information — a stored plan is never gated on it.
  */
 import { createHash } from "node:crypto";
-import { decodeWorkflowPlanV4, WORKFLOW_IR_V5_VERSION } from "./schema-v4.js";
 /** sha256 hex of the canonical (recursively sorted-keys) JSON of the plan. */
 export function computePlanHash(plan) {
     return createHash("sha256").update(canonicalPlanJson(plan)).digest("hex");
@@ -26,30 +18,6 @@ export function canonicalPlanJson(plan) {
 export function canonicalJson(value) {
     return JSON.stringify(sortKeys(value));
 }
-/** Decode, require stored canonical bytes, then verify the stored SHA-256. */
-export function decodeCanonicalPlan(runId, planJson, planHash, expectedVersion) {
-    let parsed;
-    try {
-        parsed = JSON.parse(planJson);
-    }
-    catch {
-        throw new Error(`Workflow run ${runId} has corrupt frozen plan JSON.`);
-    }
-    const canonicalWire = canonicalJson(parsed);
-    if (planJson !== canonicalWire)
-        throw new Error(`Workflow run ${runId} has noncanonical frozen plan JSON.`);
-    const actual = createHash("sha256").update(planJson).digest("hex");
-    if (!planHash || !/^[0-9a-f]{64}$/.test(planHash) || actual !== planHash)
-        throw new Error(`Workflow run ${runId} frozen plan integrity check failed.`);
-    if (expectedVersion !== undefined && expectedVersion !== null && expectedVersion !== WORKFLOW_IR_V5_VERSION) {
-        throw new Error(`Workflow run ${runId} uses unsupported workflow IR version ${expectedVersion}; this runtime supports only workflow IR version 5.`);
-    }
-    const plan = decodeWorkflowPlanV4(parsed);
-    const canonical = canonicalPlanJson(plan);
-    if (planJson !== canonical)
-        throw new Error(`Workflow run ${runId} has noncanonical frozen plan JSON.`);
-    return plan;
-}
 function sortKeys(value) {
     if (value === null || typeof value === "string" || typeof value === "boolean")
         return value;

package/dist/workflows/parser.js

@@ -10,11 +10,12 @@
  * parsed with the `yaml` package's `parseDocument` + `LineCounter` (best-effort
  * per-key line anchoring), the body's heading list with `parseMarkdownToc`
  * (already fence-aware) — both already in the codebase. The parser
- * accumulates `WorkflowError`s rather than throwing.
+ * accumulates `WorkflowError`s rather than throwing, and emits a compiled
+ * {@link WorkflowPlan} directly (`plan.ts`).
  *
  * Frontmatter carries the orchestration graph (params/defaults/budget/steps);
  * the body carries per-step prose, joined to the graph by step id. Body rules
- * (spec §2.2), exactly three:
+ *, exactly three:
  *
  *   1. Every level-2 heading must be `## <step-id>` for a DECLARED step,
  *      exactly (fenced code blocks are skipped when scanning for headings).
@@ -31,16 +32,45 @@
  * (`program/expressions.ts`): `map.over`, `route.input`, `inputs[]`.
  */
 import { LineCounter, parseDocument } from "yaml";
+import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { parseFrontmatterBlock } from "../core/asset/frontmatter.js";
 import { parseMarkdownToc } from "../core/asset/markdown.js";
-import { isContainedRelativePath, isRecord } from "../core/common.js";
+import { compareCodePoints, isContainedRelativePath, isRecord } from "../core/common.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../core/extra-params.js";
 import { checkJsonSchemaDefinition, JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS } from "../core/json-schema.js";
+import { INPUT_NAME_PATTERN } from "../execution/input-contract.js";
+import { WORKFLOW_PLAN_VERSION, } from "./plan.js";
 import { parseReference } from "./program/expressions.js";
-import { PROGRAM_ISOLATION_KINDS, PROGRAM_ON_ERROR, PROGRAM_PARAM_NAME_PATTERN, PROGRAM_REDUCERS, PROGRAM_RETRY_REASONS, PROGRAM_STEP_ID_PATTERN, } 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_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "./resource-limits.js";
-import { WORKFLOW_SCHEMA_VERSION, } from "./schema.js";
-import { runSemanticChecks } from "./validator.js";
+import { jsonBytes, utf8Bytes, WORKFLOW_ENGINE_NAME_PATTERN, WORKFLOW_ENV_VAR_NAME_PATTERN, WORKFLOW_MAX_CONCURRENCY, WORKFLOW_MAX_ENGINE_NAME_LENGTH, WORKFLOW_MAX_EXTRA_PARAMS_BYTES, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_SCHEMA_BYTES, WORKFLOW_MAX_SOURCE_BYTES, WORKFLOW_MAX_TIMEOUT_MS, } from "./resource-limits.js";
+// ── The Markdown grammar's vocabulary (pinned against schemas/akm-workflow.json) ──
+export const PROGRAM_REDUCERS = ["collect", "vote"];
+export const PROGRAM_ON_ERROR = ["fail", "continue"];
+export const PROGRAM_ISOLATION_KINDS = ["none", "worktree"];
+/** `retry.on`: exactly the persisted `AgentFailureReason` taxonomy (the `satisfies` fails typecheck on drift). */
+const RETRY_REASON_SET = {
+    timeout: true,
+    spawn_failed: true,
+    non_zero_exit: true,
+    parse_error: true,
+    cooldown: true,
+    llm_rate_limit: true,
+    llm_content_filter: true,
+    llm_invalid_json: true,
+    content_policy_reject: true,
+    unsupported_type: true,
+    no_change: true,
+    quality_rejected: true,
+    aborted: true,
+};
+export const PROGRAM_RETRY_REASONS = Object.keys(RETRY_REASON_SET);
+/**
+ * Step ids are exactly the `<ident>` grammar `steps.<id>.output` references
+ * accept: no dots, so every step is addressable and `<stepId>.gate` can never
+ * collide with a real step id.
+ */
+export const PROGRAM_STEP_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+/** Param (and output) names: plain `params.<ident>`-addressable identifiers, shared with task inputs. */
+export const PROGRAM_PARAM_NAME_PATTERN = INPUT_NAME_PATTERN;
 /** Envelope keys every AKM markdown asset carries ($ref'd from schemas/akm-asset-envelope.json). */
 const ENVELOPE_KEYS = [
     "type",
@@ -174,7 +204,7 @@ export function parseWorkflow(markdown, source) {
     checkUnknownKeys(ctx, root, [], TOP_LEVEL_KEYS, "workflow frontmatter");
     checkEnvelopeFields(ctx, root, frontmatterEndLine);
     const description = typeof root.description === "string" ? root.description : undefined;
-    const tags = readTags(ctx, root.tags, frontmatterEndLine);
+    readTags(ctx, root.tags, frontmatterEndLine);
     const params = parseParams(ctx, root.params);
     const outputs = parseOutputs(ctx, root.outputs);
     const defaults = parseDefaults(ctx, root.defaults);
@@ -194,46 +224,113 @@ export function parseWorkflow(markdown, source) {
                 });
             }
         }
-        else {
-            if (step.route === undefined && !section.instructions) {
-                errors.push({
-                    line: section.headingLine,
-                    message: `Step "${step.id}" section ("## ${step.id}") is empty. Add the step's instructions below the heading.`,
-                });
+        else if (step.route === undefined && !section.instructions) {
+            errors.push({
+                line: section.headingLine,
+                message: `Step "${step.id}" section ("## ${step.id}") is empty. Add the step's instructions below the heading.`,
+            });
+        }
+        for (const [block, what] of [
+            [section?.instructions, "instructions exceed"],
+            [section?.gateRubric, "gate rubric exceeds"],
+        ]) {
+            if (block && utf8Bytes(block.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
+                errors.push({ line: block.source.start, message: `Step "${step.id}" ${what} the 256 KiB resource limit.` });
             }
         }
-        const gate = step.gate ?? (section?.gateRubric ? {} : undefined);
-        const out = {
-            id: step.id,
+        const rubric = section?.gateRubric?.text;
+        return {
+            stepId: step.id,
+            title: step.id,
             sequenceIndex: index,
-            ...(step.unit ? { unit: step.unit } : {}),
-            ...(step.map ? { map: step.map } : {}),
-            ...(step.route ? { route: step.route } : {}),
-            ...(step.inputs ? { inputs: step.inputs } : {}),
-            ...(step.output !== undefined ? { output: step.output } : {}),
-            ...(gate ? { gate } : {}),
-            ...(section?.instructions ? { instructions: section.instructions } : {}),
-            ...(section?.gateRubric ? { gateRubric: section.gateRubric } : {}),
-            source: step.source,
+            spec: stepSpec(step, section),
+            ...(step.route
+                ? {
+                    route: {
+                        input: step.route.input,
+                        when: Object.fromEntries(step.route.branches.map((branch) => [branch.match, branch.stepId])),
+                        ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
+                    },
+                }
+                : {}),
+            ...(step.output !== undefined ? { outputSchema: step.output } : {}),
+            gate: {
+                kind: "gate",
+                id: `${step.id}.gate`,
+                stepId: step.id,
+                criteria: rubric?.trim() ? [rubric] : [],
+                maxLoops: step.gate?.maxLoops ?? 1,
+                frozenJudge: null,
+            },
         };
-        return out;
     });
-    const draft = {
-        schemaVersion: WORKFLOW_SCHEMA_VERSION,
-        ...(description ? { description } : {}),
-        ...(tags ? { tags } : {}),
-        ...(params ? { params } : {}),
-        ...(outputs ? { outputs } : {}),
-        ...(defaults ? { defaults } : {}),
+    checkCanonicalXrefs(root.xrefs, frontmatterEndLine, errors);
+    if (errors.length > 0)
+        return { ok: false, errors: sortErrors(errors) };
+    const paramNames = params ? Object.keys(params) : [];
+    const plan = {
+        irVersion: WORKFLOW_PLAN_VERSION,
+        title: source.title ?? path.replace(/^.*[\\/]/, "").replace(/\.[^.]*$/, ""),
+        ...(params && paramNames.length > 0 ? { params: paramNames, paramSchemas: params } : {}),
+        ...(outputs ? { outputs: sortedByName(outputs) } : {}),
         ...(budget ? { budget } : {}),
-        steps,
+        ...(defaults ? { defaults } : {}),
+        ...(description ? { description } : {}),
         ...(preamble ? { preamble } : {}),
-        source: { path, lineCount: totalLines },
+        steps,
     };
-    runSemanticChecks(draft, root, frontmatterEndLine, errors);
-    if (errors.length > 0)
-        return { ok: false, errors: sortErrors(errors) };
-    return { ok: true, document: draft };
+    return { ok: true, plan };
+}
+/** The authored step as the plan carries it. A prose step is inline `akm/command` literal content. */
+function stepSpec(step, section) {
+    const prose = section?.instructions?.text;
+    if (step.route)
+        return { ...(prose?.trim() ? { instructions: prose } : {}), source: step.source };
+    const dispatchUnit = step.map?.unit ?? step.unit;
+    const { exec, source: _unitSource, ...unit } = dispatchUnit ?? { source: step.source };
+    return {
+        ...(exec
+            ? { exec: { ...exec }, ...(prose?.trim() ? { instructions: prose } : {}) }
+            : { uses: "akm/command", commandMode: "literal", with: { content: prose ?? "" } }),
+        ...(Object.keys(unit).length > 0 ? { unit } : {}),
+        ...(step.map
+            ? {
+                map: {
+                    over: step.map.over,
+                    ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
+                    ...(step.map.reducer !== undefined ? { reducer: step.map.reducer } : {}),
+                },
+            }
+            : {}),
+        ...(step.inputs ? { inputs: [...step.inputs] } : {}),
+        source: step.source,
+    };
+}
+/** `outputs:` in canonical wire order (code-point ascending by name). */
+function sortedByName(entries) {
+    return Object.fromEntries(Object.keys(entries)
+        .sort(compareCodePoints)
+        .map((name) => [name, entries[name]]));
+}
+/** `xrefs` entries must be canonical asset refs. */
+function checkCanonicalXrefs(value, line, errors) {
+    if (!Array.isArray(value))
+        return; // shape already flagged by checkXrefs
+    for (const ref of value) {
+        try {
+            if (typeof ref !== "string")
+                throw new Error("non-canonical ref");
+            const parsed = parseBundleRef(ref);
+            if (parsed.conceptId.includes(":") || ref !== bundleRefToString(parsed))
+                throw new Error("non-canonical ref");
+        }
+        catch {
+            errors.push({
+                line,
+                message: `Workflow frontmatter "xrefs" contains an invalid or non-canonical ref: ${String(ref)}.`,
+            });
+        }
+    }
 }
 function bindStepSections(headings, lines, bodyStartLine, totalLines, path, declaredIds, errors) {
     const sections = new Map();
@@ -425,9 +522,9 @@ function parseParams(ctx, raw) {
     return Object.keys(params).length > 0 ? params : undefined;
 }
 /**
- * `outputs:` (P3b, spec §4.2): named, optionally schema-validated projections
+ * `outputs:`: named, optionally schema-validated projections
  * of step artifacts, exported when the run completes. Symmetrical with
- * `parseParams` above (B-N4) — same authoring surface, same name grammar,
+ * `parseParams` above — same authoring surface, same name grammar,
  * same schema-subset validator, same per-schema byte bound — but each entry
  * is a STRUCTURED `{from, schema?}` mapping rather than a bare JSON Schema.
  *
@@ -435,7 +532,7 @@ function parseParams(ctx, raw) {
  * `steps.<id>.output(.<seg>)*` reference (never `params.<name>` — an output
  * projects a step artifact, never a param, B-07). Whether the named step is
  * actually DECLARED in this document is a semantic, cross-step check left to
- * `ir/compile.ts`'s reference validation (B-06), mirroring how `inputs[]` /
+ * `compile.ts`'s `checkWorkflowPlan`, mirroring how `inputs[]` /
  * `map.over` / `route.input` already split "syntax here, semantics there".
  */
 function parseOutputs(ctx, raw) {

package/dist/{commands/improve/consolidate/types.js → workflows/plan.js}

@@ -1,4 +1,5 @@
 // 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/.
-export {};
+/** Stored plans record this; earlier releases wrote 4 and 5, which still decode. */
+export const WORKFLOW_PLAN_VERSION = 6;

package/dist/workflows/renderer.js

@@ -2,17 +2,15 @@
 // 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/.
 /**
- * Show + indexing renderer for peer workflow sources. `.md` and `.yml` both
- * compile through `compileWorkflowSource` into source IR v1, which is projected
- * down to the public `ShowResponse` shape and into search hints for the indexer,
- * including a compact per-step orchestration summary (engine/model or an exec
- * unit's argv, `map.over` reference, route table) when the step declares one.
+ * Show renderer for peer workflow sources. `.md` and `.yml` both compile
+ * through `compileWorkflowSource` into a plan, which is projected down to the
+ * public `ShowResponse` shape, including a compact per-step orchestration
+ * summary (engine/model or an exec unit's argv, `map.over` reference, route
+ * table) when the step declares one.
  */
 import { displayRef } from "../core/asset/resolve-ref.js";
 import { UsageError } from "../core/errors.js";
-import { projectExecCore } from "./program/schema.js";
-import { compileWorkflowSource } from "./source-ir/compile.js";
-import { sourceStepInstructions, workflowShellCommand } from "./source-ir/program.js";
+import { compileWorkflowSource, routeDescription, workflowStepInstructions } from "./compile.js";
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -26,36 +24,18 @@ function deriveName(ctx) {
     const ext = ctx.relPath.lastIndexOf(".");
     return ext > 0 ? ctx.relPath.slice(0, ext) : ctx.relPath;
 }
-function loadSourceIr(ctx) {
+function loadPlan(ctx) {
     const result = compileWorkflowSource(ctx.content(), { path: ctx.relPath, workspaceRoot: ctx.stashRoot });
     if (result.ok)
-        return result.ir;
+        return result.plan;
     const summary = result.errors.map((e) => `${e.path}:${e.line} — ${e.message}`).join("\n");
     throw new UsageError(`Workflow has errors:\n${summary}`);
 }
-/**
- * The instruction text a step contributes to the flat step projection. A
- * route step has no body requirement, so a deterministic description of the
- * routing table stands in when it declares no section (the spine still needs
- * a non-empty instructions string).
- */
-function stepInstructions(step) {
-    const instructions = sourceStepInstructions(step);
-    if (instructions)
-        return instructions;
-    if (step.route) {
-        const branches = step.route.branches.map((b) => `"${b.match}" -> ${b.stepId}`);
-        if (step.route.defaultStepId !== undefined)
-            branches.push(`default -> ${step.route.defaultStepId}`);
-        return `Route on ${step.route.input}: ${branches.join(", ")}.`;
-    }
-    return "";
-}
 /** Project the `params` block into the flat `WorkflowParameter` list. */
-function projectParameters(sourceIr) {
-    if (!sourceIr.params)
+function projectParameters(plan) {
+    if (!plan.paramSchemas)
         return undefined;
-    const parameters = Object.entries(sourceIr.params).map(([name, schema]) => {
+    const parameters = Object.entries(plan.paramSchemas).map(([name, schema]) => {
         const description = schema.description;
         return { name, ...(typeof description === "string" && description !== "" ? { description } : {}) };
     });
@@ -91,15 +71,9 @@ function projectParameters(sourceIr) {
  * already carries whole.
  */
 function summarizeStepOrchestration(step, defaults) {
-    const unit = step.unit;
-    const exec = step.exec
-        ? step.exec
-        : step.run !== undefined
-            ? {
-                command: workflowShellCommand(step.shell ?? "sh", step.run),
-                ...(step.workingDirectory ? { cwd: step.workingDirectory } : {}),
-            }
-            : undefined;
+    const spec = step.spec;
+    const unit = spec?.unit;
+    const exec = spec?.exec;
     const engine = exec ? undefined : (unit?.engine ?? defaults?.engine);
     const model = exec ? undefined : (unit?.model ?? defaults?.model);
     const timeoutMs = unit?.timeoutMs !== undefined ? unit.timeoutMs : defaults?.timeoutMs;
@@ -107,25 +81,24 @@ function summarizeStepOrchestration(step, defaults) {
         ...(engine !== undefined ? { engine } : {}),
         ...(model !== undefined ? { model } : {}),
         ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-        // Same projection the draft and the frozen plan use, so what `show` prints
-        // cannot drift from what runs.
-        ...(exec ? { exec: projectExecCore(exec) } : {}),
-        ...(step.map
+        // Same projection the frozen plan uses, so what `show` prints cannot drift from what runs.
+        ...(exec ? { exec: { ...exec } } : {}),
+        ...(spec?.map
             ? {
                 fanOut: {
-                    over: step.map.over,
-                    ...(step.map.concurrency !== undefined ? { concurrency: step.map.concurrency } : {}),
-                    reducer: step.map.reducer ?? "collect",
+                    over: spec.map.over,
+                    ...(spec.map.concurrency !== undefined ? { concurrency: spec.map.concurrency } : {}),
+                    reducer: spec.map.reducer ?? "collect",
                 },
             }
             : {}),
-        ...(unit?.output !== undefined || step.output !== undefined ? { hasSchema: true } : {}),
+        ...(unit?.output !== undefined || step.outputSchema !== undefined ? { hasSchema: true } : {}),
         ...(unit?.env !== undefined ? { env: [...unit.env] } : {}),
         ...(step.route
             ? {
                 route: {
                     input: step.route.input,
-                    branches: step.route.branches.map((b) => ({ match: b.match, stepId: b.stepId })),
+                    branches: Object.entries(step.route.when).map(([match, stepId]) => ({ match, stepId })),
                     ...(step.route.defaultStepId !== undefined ? { defaultStepId: step.route.defaultStepId } : {}),
                 },
             }
@@ -133,20 +106,15 @@ function summarizeStepOrchestration(step, defaults) {
     };
     return Object.keys(summary).length > 0 ? summary : undefined;
 }
-function projectStepDefinitions(sourceIr) {
-    const flattened = sourceIr.jobs.flatMap((job) => job.steps.map((step) => ({ jobId: job.id, step })));
-    const counts = new Map();
-    for (const { step } of flattened)
-        counts.set(step.id, (counts.get(step.id) ?? 0) + 1);
-    return flattened.map(({ jobId, step }, sequenceIndex) => {
-        const id = (counts.get(step.id) ?? 0) > 1 ? `${jobId}-${step.id}` : step.id;
-        const orchestration = summarizeStepOrchestration(step, sourceIr.defaults);
+function projectStepDefinitions(plan) {
+    return plan.steps.map((step, sequenceIndex) => {
+        const orchestration = summarizeStepOrchestration(step, plan.defaults);
+        const instructions = workflowStepInstructions(step);
         return {
-            id,
-            // No titles in the shared source IR — a step IS its id.
-            title: step.id,
-            instructions: stepInstructions(step),
-            ...(step.gate?.rubric?.trim() ? { completionCriteria: [step.gate.rubric] } : {}),
+            id: step.stepId,
+            title: step.stepId,
+            instructions: instructions || (step.route ? routeDescription(step.route) : ""),
+            ...(step.gate.criteria.length > 0 ? { completionCriteria: [...step.gate.criteria] } : {}),
             sequenceIndex,
             ...(orchestration ? { orchestration } : {}),
         };
@@ -156,26 +124,25 @@ export const workflowMdRenderer = {
     name: "workflow-md",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
-        const sourceIr = loadSourceIr(ctx);
+        const plan = loadPlan(ctx);
         // WI-8.5b (display flip): the `akm workflow run <ref>` action is DISPLAY
         // output — its spelling follows the D-R5 display rule (`displayRef`). A
         // primary/default-bundle workflow renders the SHORT conceptId
         // (`workflows/<name>`); a named source qualifies it as
         // (`<bundle>//workflows/<name>`).
         const ref = displayRef({ type: "workflow", name, bundleId: ctx.origin }, ctx.defaultBundle);
-        const parameters = projectParameters(sourceIr);
+        const parameters = projectParameters(plan);
         return {
             type: "workflow",
             name,
             path: ctx.absPath,
             action: buildWorkflowAction(ref),
-            ...(sourceIr.preamble ? { content: sourceIr.preamble } : {}),
-            description: sourceIr.description,
-            // No authored title in the shared source IR — the asset's human name is
-            // its `description`/H1 like any other asset; this is its canonical name.
+            ...(plan.preamble ? { content: plan.preamble } : {}),
+            description: plan.description,
+            // No authored title — the asset's human name is its `description`/H1; this is its canonical name.
             workflowTitle: name,
             ...(parameters ? { parameters: parameters.map((p) => p.name), workflowParameters: parameters } : {}),
-            steps: projectStepDefinitions(sourceIr),
+            steps: projectStepDefinitions(plan),
         };
     },
 };

package/dist/workflows/resource-limits.js

@@ -6,18 +6,8 @@ export const WORKFLOW_MAX_SOURCE_BYTES = 1024 * 1024;
 export const WORKFLOW_MAX_INSTRUCTION_BYTES = 256 * 1024;
 export const WORKFLOW_MAX_SCHEMA_BYTES = 256 * 1024;
 export const WORKFLOW_MAX_EXTRA_PARAMS_BYTES = 64 * 1024;
-// ── Dispatch-significant bounds shared across validation layers ──────────────
-//
-// Defined ONCE here so the enforcement layers cannot drift:
-//   1. the parser (`../parser.ts`) — line-anchored authoring-time errors,
-//   2. the published JSON Schema (`schemas/akm-workflow.json`) — mirrored
-//      `maximum`/`pattern`/`maxLength` values, pinned against these constants
-//      by `tests/integration/workflows/schema-drift.test.ts`,
-//   3. the strict frozen-plan decoder (`./ir/schema.ts`) — the corruption
-//      gate for persisted plans.
-// A bound enforced only by the decoder surfaces as a terse, unlocated
-// "Invalid frozen workflow plan" at `workflow run` — after lint and
-// `workflow create` already said the document was fine.
+// ── Bounds the parser enforces, mirrored by schemas/akm-workflow.json ────────
+// (pinned by tests/workflows/schema-drift.test.ts)
 /** Max per-step map fan-out concurrency (also the run-level concurrency ceiling). */
 export const WORKFLOW_MAX_CONCURRENCY = 64;
 /** Max timeout in milliseconds (setTimeout's 32-bit signed ceiling: 2^31-1, ~24.8 days). */
@@ -26,69 +16,21 @@ export const WORKFLOW_MAX_TIMEOUT_MS = EXECUTION_MAX_TIMEOUT_MS;
 export const WORKFLOW_ENGINE_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 export const WORKFLOW_MAX_ENGINE_NAME_LENGTH = 63;
 // ── exec (shell) unit bounds ─────────────────────────────────────────────────
-/**
- * Grammar for an env var NAME in `pass_env:`. Matches the frozen-plan
- * `envPassthrough` grammar in `ir/schema.ts` so both allowlist surfaces accept
- * exactly the same identifiers.
- */
+/** Grammar for an env var NAME (`pass_env:`, step `env:` keys, task env). */
 export const WORKFLOW_ENV_VAR_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /**
- * Default wall-clock timeout for an exec unit that declares no `timeout:` and
- * inherits no document `defaults.timeout`.
- *
- * 10 minutes matches `DEFAULT_LLM_TIMEOUT_MS`. Unlike an agent harness (which
- * owns its own lifetime, hence `DEFAULT_AGENT_TIMEOUT_MS === null`), a shell
- * command has NO lifetime discipline of its own: an unbounded default would let
- * a hung `npm install` or an interactive prompt wedge a workflow run forever.
- * Authors who genuinely need an unbounded command write `timeout: none`.
+ * Default timeout for an exec unit with no `timeout:` of its own or in
+ * `defaults` (a command has no lifetime discipline; `timeout: none` opts out).
  */
 export const DEFAULT_EXEC_TIMEOUT_MS = 600_000;
 /**
- * Max BYTES of ONE captured pipe an exec unit RETAINS in memory (stdout and
- * stderr are retained separately).
- *
- * This is a RETENTION cap, not a permission to run. Without it the capture is
- * bounded only by the command's exit or the wall timeout, so a command that
- * writes continuously (`yes`, a verbose test loop) grows a string in the akm
- * process until the host runs out of memory — and the default budget gives it
- * ten minutes to do so. What the cap buys is a BOUND where there was none: the
- * retained prefix is promoted into the unit's outcome text and every outcome is
- * held until the step reduces, so the worst case is (units in the STEP × this
- * cap) — the step's width, not the in-flight width, is what sizes it.
- *
- * On reaching the cap the reader switches to DRAIN-AND-DISCARD: it keeps
- * pulling from the pipe (so the child never blocks on backpressure) and stops
- * RETAINING. The command therefore runs to completion and its real exit code
- * stands — a passing-but-chatty test suite is no longer failed over log volume.
- * What overflow costs is honesty about the artifact, and that is paid two ways
- * in `exec/exec-unit.ts`:
- *
- *   - no declared `output:` schema → the unit succeeds and its artifact carries
- *     an unmistakable {@link WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER} block naming
- *     the total and retained byte counts, so truncated text can never be
- *     mistaken for the whole output;
- *   - a declared `output:` schema → the unit fails `exec_output_limit`, because
- *     validating a truncated JSON prefix is meaningless and promoting it would
- *     corrupt every downstream reference. That is the residual failure the cap
- *     genuinely justifies.
- *
- * 8 MiB is deliberately generous, so any output a step is likely to produce
- * fits many times over and an ordinary full test/build log is nowhere near
- * it.
+ * Max bytes of one captured pipe an exec unit retains in memory. Past it the
+ * reader drains and discards, so the command still runs to its real exit
+ * code; the artifact gets a {@link WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER}
+ * block, or the unit fails `exec_output_limit` if it declared an `output:` schema.
  */
 export const WORKFLOW_MAX_EXEC_OUTPUT_BYTES = 8 * 1024 * 1024;
-/**
- * Marker stamped on an exec artifact that was RETAINED ONLY IN PART because the
- * command wrote past {@link WORKFLOW_MAX_EXEC_OUTPUT_BYTES}.
- *
- * Deliberately ugly and unique: a truncated value must NEVER be mistakable
- * for a complete one by a downstream `steps.<id>.output` reference, by a gate
- * judge, by `akm workflow status`, or by a human reading the row. The
- * artifact is TEXT here rather than a JSON value, so the marker is appended
- * as a trailing block instead of replacing the value with an envelope: the
- * retained prefix is still genuinely useful (it is the head of a real log),
- * and the block says exactly how much is missing.
- */
+/** Appended to an exec artifact retained only in part, so it is never mistaken for complete output. */
 export const WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER = "__akm_exec_output_truncated__";
 // Per-var: Win32 `SetEnvironmentVariable` caps one variable at 32 767 UTF-16
 // code units; measuring UTF-8 bytes is conservative in the right direction.
@@ -116,65 +58,15 @@ const EXEC_CONTEXT_LIMITS_POSIX = {
 export function execContextLimits(platform = process.platform) {
     return platform === "win32" ? EXEC_CONTEXT_LIMITS_WIN32 : EXEC_CONTEXT_LIMITS_POSIX;
 }
-/**
- * Max characters of the per-unit human diagnostic — the `error`/stderr text
- * journaled on a failed unit row and rendered by `akm workflow status --units`.
- *
- * ONE constant for the write side (`exec/native-executor.ts`, which clips before
- * journaling) and the read side (`runtime/runs.ts`, which clips whatever a row
- * already holds), so a diagnostic can never be stored larger than the surface
- * that displays it. Long enough for a real stack trace or a compiler's error
- * block; short enough that a runaway command cannot turn the journal into its
- * log file.
- */
+/** Max characters of a unit's journaled diagnostic, on both the write and the display side. */
 export const WORKFLOW_UNIT_DIAGNOSTIC_CLIP = 2_000;
-/**
- * Truncate to `max` chars with an ellipsis marker.
- *
- * Lives with the bounds rather than with either caller: the write side
- * (`exec/step-work.ts`) and the read side (`runtime/runs.ts`) clip against the
- * same constants, and `runtime/runs.ts` cannot take the helper from
- * `exec/step-work.ts` — that module imports `runtime/runs.ts`.
- */
+/** Truncate to `max` chars with an ellipsis marker. */
 export function clip(text, max) {
     return text.length > max ? `${text.slice(0, max)}…` : text;
 }
-// ── Persistence bounds ───────────────────────────────────────────────────────
-//
-// `workflow_run_steps.evidence_json` is persisted WHOLE and unclipped. It used
-// to be capped at 1 MiB, past which the row was replaced by a marked
-// truncation envelope — but the run still looked successful, and the NEXT
-// invocation (a resume, or any later step referencing the artifact) failed
-// permanently: the value was gone from the only place a resumed run can read
-// it from, so every prior paid step had to be re-run from scratch. SQLite has
-// no practical row-size problem here (its own ceiling is ~1 GB), so there is
-// nothing this cap protected that a full write does not already handle
-// correctly. `JSON.stringify` throwing on genuinely unserializable evidence
-// is unchanged.
 export function utf8Bytes(value) {
     return Buffer.byteLength(value, "utf8");
 }
 export function jsonBytes(value) {
     return utf8Bytes(JSON.stringify(value));
 }
-// ── Recursive child-workflow composition bounds (spec docs/plans/specs/
-// ── p3a-plan-v5-child-freeze.md §4.5, A-N6) ──────────────────────────────────
-//
-// Composition DEPTH is unbounded — `assertNoCompositionCycle` (freeze/targets/
-// child-workflow.ts) already makes infinite composition mathematically
-// impossible, so a depth ceiling on top of it only bounded how many
-// legitimately distinct workflows an author could nest.
-//
-// This section used to also cap the AGGREGATE canonical-JSON bytes of every
-// embedded child plan in one root freeze (`WORKFLOW_MAX_EMBEDDED_CHILD_PLAN_BYTES`,
-// enforced in `freeze/targets/child-workflow.ts` and re-checked on every
-// decode in `ir/schema-v4.ts`'s `decodeChildWorkflowTarget`), alongside a
-// standalone cap on any one frozen plan's own bytes
-// (`WORKFLOW_MAX_PLAN_BYTES`, enforced in `ir/plan-hash.ts` and
-// `ir/schema.ts`). A large plan is not a wrong plan: composing several
-// substantial workflows together is a legitimate, deliberate authoring
-// choice, and SQLite has no practical row-size problem here (its own
-// ceiling is ~1 GB) — there was nothing left for either cap to protect that
-// `planHash`/`contentHash` verification does not already cover. Both caps
-// are removed; the hash/canonical-JSON integrity checks they sat next to
-// are unchanged.