Review #2 — task-workflow-format-unification.md (v7) vs. the implementation

Reviewer: independent reviewer #2 of 3. Repo: /home/user/akm @ claude/akm-markdown-tasks-history-75l6du (baselined on claude/release-0-9-0-polish-d6sycl, HEAD 3c5fadb). Scope: the spec in full, plus src/tasks/, src/workflows/{ir,exec,program}, schemas/*.json, config engine schema, model aliases, the task adapter, and the 0.9.0 migrator.

Overall. The direction is right and several of the spec's diagnoses are accurate (the unit: bag is awkward; resolvePromptSource() sniffing is bad; akm-task.json really is dead weight; freeze really does resolve by layers). But the document repeatedly presents new mechanism as existing mechanism. The three load-bearing "this already exists" claims — the configuration cascade, the single dispatch seam, and "no IR/freeze/journal changes" — do not survive contact with the code. run: shell units cannot be represented in IR v3 at all; the cascade that "already exists" is two layers deep with no persona layer and no defaults.model; and the output: "duplicate" the flatten deletes is two semantically distinct schemas that the sibling spec it cites explicitly distinguishes. The migration section's losslessness claim is false in at least four concrete ways.

Verdict: do not sign off decision 14 (or §3.6/§10) as written. The design is salvageable, but §10's non-goals must be withdrawn and the hidden cost (IR v4, plan-hash/journal migration, a persona-layer freeze path, a placeholder grammar decision, a redaction-policy change) has to be priced in before this is scoped as "authoring-surface changes".

Findings table

Critical

C1. unit.output and step.output are two different schemas; the flatten collides them

Spec §3.6: "output: is declared both on the step and inside the bag — a live wart in schemas/akm-workflow.json", and "The duplicate output declaration disappears with the bag." §6 repeats: "separate unit defs with a duplicated output".

They are not duplicates.

• src/workflows/ir/compile.ts:229 — unit.output → WorkflowUnitDraft.schema.
• src/workflows/ir/compile.ts:204 — step.output → WorkflowStepDraft.outputSchema.
• schema validates one unit's structured result, per dispatch attempt: src/workflows/exec/report.ts:1621 (Unit "…" result failed validation against its declared output schema), threaded to harness native structured output at native-executor.ts:1038,1092.
• outputSchema validates the promoted step artifact after reduction: src/workflows/exec/step-work.ts:558-561, native-executor.ts:55, ir/schema.ts:217.

And the spec this one claims consistency with says so in as many words — docs/architecture/specs/workflow-format-unification.md §2.3b: "For a map step, output: validates the promoted artifact, i.e. what the reducer produced — not one unit's result."

Consequence: on a map: step, map.unit.output (per-item schema, which drives each harness's native structured-output mode) and step.output (the collected array schema) are necessarily different documents. Deleting the bag deletes the ability to type a map step's per-item result at all — silently, since both spellings are output:. Existing workflows that set both will migrate to a conflict with no defined winner.

Recommendation: keep two spellings on the flattened step (e.g. result: for the per-unit schema and output: for the step artifact), or explicitly declare per-item schemas removed and accept losing harness-native structured output on map steps. Either way, remove the "duplicate" framing from §3.6/§6 — it is the justification for the change and it is wrong.

C2. run: shell units cannot be represented in IR v3; §10's non-goals are false

Spec §3.6: "A shell unit inside a workflow journals like any unit (workflow_run_units): no tokens, but status, timing, attempts, and failure_reason behave normally." §2: "unit-dispatch.ts is the one dispatch seam." §10: "no changes to … IR, freeze, journal, leases, or replay."

The code:

• src/workflows/exec/unit-dispatch.ts:19 — UnitDispatchRequest.engine: FrozenEngineSnapshot is required, as is invocation: IrInvocation.
• src/workflows/ir/schema.ts:48,65,76 — FrozenEngineSnapshot is a closed two-member union (llm | agent), validated by decodeWorkflowPlanV3 (ir/schema.ts:171 — irVersion must be 3; :341-374 field allowlists; :517 assertUnitEngineCompatibility).
• src/workflows/exec/native-executor.ts:638-645 — a unit with no frozen engine snapshot hard-fails dispatch_error before dispatch.
• src/workflows/ir/freeze.ts:49-62 — every unit runs freezeInvocation, which throws ConfigError("No workflow engine is selected…") when no engine resolves. A workflow made entirely of run: steps therefore cannot even be frozen on a machine with no agent CLI configured — the single most obvious use case for inline shell.

Adding a shell unit kind requires: a third FrozenEngineSnapshot variant or a new IR node kind, decodeWorkflowPlanV3 changes, an irVersion bump (persisted plan_json/plan_hash on run rows), a hashVersion bump in step-work.ts:379, and a frozenUnitRunner branch. That is an IR + freeze + journal + replay change, i.e. the exact four things §10 says are untouched. Nothing in the codebase currently executes a shell string at all — runCommandTask spawns pre-split argv with no shell (src/tasks/runner.ts:277-289, src/tasks/parser.ts:300-306), which the spec itself notes in §6.

Recommendation: withdraw the §10 non-goal, state IR v4 explicitly, and decide whether in-flight v3 runs are drained or migrated. Also state what freezeInvocation does for a shell unit (it must be skipped, not defaulted — otherwise every shell-only workflow requires an engine).

C3. The prose-append rule can change the prompt without changing the input hash

Spec §3.3: "the assembled prompt is a frozen string produced at one seam, so appending is a deterministic concat — easy", and the appended section is "appended to the assembled prompt after a blank line, byte-exact."

There are two seams, and the spec names the wrong one. step-work.ts:322-332 assembles the prompt via buildUnitPrompt; step-work.ts:376-392 computes the inputHash over template.instructions — the frozen template bytes — not over the assembled prompt. The comment at :342-350 states this deliberately. The codebase has already been bitten by exactly this: gateFeedback had to be added to the hash preimage (:362-368) because "omitting it made loop 1 and loop 2 journal identical hashes for different prompts, breaking the 'changed inputs ⇒ changed hash' audit contract."

If the ## <step-id> section of a uses: tasks/<id> step is appended at prompt-assembly time, two materially different prompts hash identically → classifyUnitReuse (native-executor.ts:690) reuses a completed row for a different ask, and editing only the step's section produces no re-dispatch.

Recommendation: the append must happen at compile time, folded into WorkflowUnitDraft.instructions before freeze, so it is inside the hash preimage by construction. Say so in §3.3. (This also makes the "byte-exact" and "blank line" rule a compile-time, testable property.)

Secondary: the rule is conditioned on "when the resolved work is agent-dispatched" — but for a uses: tasks/<id> step, whether the task resolves to agent work or shell work is known only after resolving the task. The same authored step therefore silently changes whether its prose is load-bearing or documentation depending on the referenced task's target — and a later edit to the task (prose → run:) silently demotes the workflow's prose to a comment. That is a footgun worth an explicit lint.

C4. params as a cascade value field collides with params: = declarations

§3.4 lists params in the flat value vocabulary, "legal at every layer, merged per-field with the nearest layer winning", and §3.3 says a referenced task is "one more layer".

But at the workflow-document layer, params: already means something else entirely: the declaration block, name → JSON Schema (schemas/akm-workflow.json:22-32; compile.ts:132-139 → plan.paramSchemas). A "document defaults" layer contributing params values into the same frontmatter namespace is not expressible.

Worse, cascading param values down from config/engine/persona layers breaks the declared-flag contract the spec cites in §2: materializeWorkflowParameterFlags (ir/params.ts:39-53) rejects any name not in plan.params, and assertRunParamsSatisfyPlan (run-workflow.ts:531) validates the journaled set. A global params default would inject undeclared names into every run.

Also unspecified: params means three different things across §3.2 — workflow param flags, command-template placeholder fills, and (per §3.4) a cascading value field. Merging them per-field across five layers has no coherent semantics (e.g. a persona node's params.scope leaking into an unrelated workflow's param set).

Recommendation: remove params from the cascade vocabulary. Make it a target-local input (uses:-adjacent only), and keep the document-level params: declaration block as-is.

Major

M1. The "cascade that already exists" is two layers, with no persona layer and no defaults.model

§2 and §3.4 lean hard on "Freeze already implements a configuration cascade" and "exposing this existing mechanism". What exists:

• freeze.ts:50 — layers = [documentDefaults?, unit?]. Two layers, both from the workflow document. Verified.
• freeze.ts:151-155 selectedEngine, :163-191 exactModel, :193-209 effectiveTimeout, :211-216 mergedLlmOverrides — nearest-wins / deep-merge. Verified.
• The engine node is not a layer: engine.model is consulted only as a fallback after the layers produce nothing (freeze.ts:171), and engine.timeoutMs likewise (:197). Same relative order the spec wants, but it is a two-branch fallback chain, not a layer list — generalizing it to five layers is a rewrite of these three functions, not an exposure.
• There is no persona layer at all. Nothing in freeze.ts loads an agent asset. This is the largest new piece of work in the whole proposal (see M4) and §3.4 describes it as already-mechanism.
• defaults.model does not exist. src/core/config/config-schema.ts:102-108: DefaultsSchema = { engine?, llmEngine?, improveStrategy? }.passthrough(). schemas/akm-config.json properties.defaults has the same three keys with additionalProperties: true. So the spec's §3.4 worked example ("defaults": { "engine": "claude", "model": "sonnet" }) is a config a user can write today, that validates, and that is silently ignored. That is a live drift bug the plan should fix explicitly, not a documented layer.

Recommendation: rewrite §2's fifth bullet and §3.4's "the mechanism already exists" framing to name what is new (persona layer, config defaults.model, env/cwd/shell layering, per-field merge across five layers) versus what is reused (nearest-wins over two workflow-document layers). Otherwise the estimate is wrong by a large factor.

M2. The kind-gated llm hard error is already dead code in the workflow path

§3.4: "llm: … was a grouping whose only job was to scope a kind-gated hard error"; §6: "a kind-gated hard error" (singular).

There are two behaviors, and one is a bug:

// src/workflows/ir/freeze.ts:67-73
const llm = engine.kind === "llm" ? mergedLlmOverrides(layers) : undefined;
if (engine.kind !== "llm" && llm !== undefined) { throw new ConfigError(...) }

The guard is unreachable — llm is undefined whenever kind !== "llm". So a workflow that sets defaults.llm.temperature under an agent engine today gets its overrides silently discarded, with no error and no warning. The live hard error exists only on the task path (src/tasks/runner.ts:497-502, NotFoundError — also the wrong error class for a config problem).

This matters for the proposal in two ways: (a) the "convert the error to a notice" work item is really "fix a silent-drop bug and convert a task-path error", and (b) §3.4's argument that "a global default temperature must not brick every agent-engine dispatch" is already true of workflows — the motivating hazard is one path only.

Recommendation: fix freeze.ts:67-73 independently (it is a bug on the current branch), and correct §3.4/§6 to describe two divergent behaviors.

M3. Model aliases are not portable to LLM endpoints

§3.5: "Aliases are per-platform, which is what makes a shared asset portable: model: sonnet resolves to the right string under a claude engine, an opencode engine, or an LLM endpoint."

src/integrations/agent/model-aliases.ts:45-76 — the built-in table has exactly two platform columns: claude and opencode. resolveLlmModel (:107-109) calls resolveModel(model, engineName, undefined, global, ["llm"]), i.e. it passes the engine name where platform is expected, then falls back to a "llm" column and "*". A user-supplied modelAliases table can supply those columns; the built-ins cannot. So under an LLM engine, model: sonnet returns "sonnet" verbatim (:103 entry?.platforms[platform] ?? model) and is sent as the model id to an OpenAI-compatible endpoint.

Since §3.4/§3.5 make aliases legal at every layer (including a shared persona node in a third-party bundle), this failure now occurs at more layers, not fewer, and only at dispatch.

Recommendation: either add an llm/* column to BUILTIN_ALIASES, or drop the portability claim and add a freeze-time notice when an alias fails to resolve against the selected engine.

M4. The persona layer is not "a node whose fields join the cascade" — it carries a system prompt and a gated tool policy

§3.4 describes agent: as picking "the persona node — who runs it (system prompt, tool policy, model preference)" and then only ever discusses model. The other two are the hard part:

• Today an agent asset yields { prompt (system), modelHint, toolPolicy } (src/output/renderers.ts:241-262), consumed only by akm agent (contribute-cli.ts:72-90 → AgentDispatchRequest).
• The workflow path deliberately does not carry them: native-executor.ts:1026 — "systemPrompt/tools/cwd come from the profile/asset, not the workflow unit"; unit-dispatch.ts:16 documents systemPrompt as "used by frozen workflow gate judges" only; buildAgentDispatchRequest (:1029-1039) passes only prompt/model/schema. FrozenEngineSnapshot has no tool-policy field (ir/schema.ts:60-75).
• Security-relevant: the agent asset's tools: is self-declared frontmatter, and there is an explicit provenance ceiling applied at the show layer that decides whether to honour it based on writable-own-stash vs read-only third-party source (renderers.ts:257-260, tagged "07 P1-D"). Freeze has no notion of source provenance. Making agent: a cascade selector resolved at freeze silently relocates that ceiling — or drops it.

Combined with §3.4's "This widens agent assets from today's model-hint-only frontmatter to the full value vocabulary", a third-party bundle's agent asset would now be able to set env, cwd, timeout and a tool policy for a workflow that merely names it. §10 says "no multi-file config merging" while §3.4 makes bundle assets configuration layers; that tension should be resolved explicitly with a provenance rule.

Recommendation: state that the persona layer contributes systemPrompt and toolPolicy into the frozen plan (IR change), and carry the existing provenance ceiling into freeze with a named test.

M5. Command-template filling: four conventions, one live bug, and a silent behavior change

§3.2: "uses: commands/<name> … params: fill the placeholders", "a placeholder with no matching param is an error at fill time"; §6: "one implementation, both surfaces" (from "n/a").

It is not "n/a" today, and the existing surface is inconsistent:

• src/output/renderers.ts:164-186 (extractParameters) advertises three conventions to consumers: $ARGUMENTS, $1…$9, and {{name}}.
• src/commands/agent/agent-dispatch.ts:63-72 (fillPlaceholders) substitutes only {{<digits>}}, positionally from --args, and leaves unmatched placeholders verbatim (:70).

So a command asset declaring {{scope}} is reported as having a scope parameter and can never be filled — an existing bug the plan inherits. And the spec's rule changes behavior on two axes at once: positional → named, and lenient → hard error. $ARGUMENTS-style command assets imported from Claude Code (which the agent: frontmatter support at renderers.ts:234 implies akm already ingests) would become errors under "a placeholder with no matching param is an error at fill time".

Recommendation: pick one grammar in the spec, state what happens to the other three, and state the inverse rule (extra params: with no placeholder — error or notice?). Treat this as a real work item, not a table row.

M6. uses: scripts/<name> is new execution surface, not consolidation

§3.2: "Execute the script asset per its own run/setup/cwd metadata — no AI." §6 files it under shared plumbing.

Today run/setup/cwd on a script asset are display hints only: resolveExecHints (src/output/renderers.ts:118-142) merges indexed metadata, @run/@setup/@cwd header comments, and — critically — auto-detection from extension + dependency files (detectExecHints). Nothing executes them.

Making them executable means: a scheduled task or workflow step naming a script from an installed third-party bundle runs (a) an auto-detected interpreter line and (b) a setup command (typically a package install) at cron time. src/core/activation-policy.ts enumerates four activation rules — dangerous env keys, install-time key scan, task activation, write activation — none covers executing a bundle-supplied script. The spec's §10 "no change to how script assets are authored or stored — this proposal executes and embodies them" waves past exactly the interesting part.

Recommendation: add an activation rule (fifth) for third-party script execution, decide whether setup runs at all (I'd say no — it is an install-time concern), and forbid auto-detected run for non-primary-bundle scripts.

M7. Literal env: values will be over-redacted

§3.7: "Values sourced from env/ and secrets/ assets join the dispatch's sensitiveValues" — implying literals do not.

collectWorkflowDispatchSensitiveValues (native-executor.ts:1163-1185) starts from new Set(Object.values(env ?? {})) — every resolved env value, no provenance distinction. collectSensitiveValues (src/core/redaction.ts:193-202) applies no length, entropy, or dictionary floor.

So env: [{ LOG_LEVEL: debug }] (the spec's own example, §3.7) adds the string "debug" to sensitiveValues, and every occurrence of debug in the unit's output, journaled result, and error text is replaced. Worse, redactUnitOutcome (:1187-1193) collapses any redacted failureReason to "reported_failure" — so a common literal value can silently destroy the failure taxonomy retry.on keys off.

Recommendation: tag env entries with provenance at resolution (ref vs literal) and feed only ref-sourced values to sensitiveValues; or add a minimum-length/entropy floor. Say which in §3.7.

M8. The env: list shape is an IR change, a hash-version change, and a per-unit-env change

§3.7: "This extends the existing schema additively — the workflow unit.env is already a list of ref strings, so every currently-valid value stays valid." §10: no IR/journal changes.

• compile.ts:46 / ir/schema.ts — env?: string[]. A list of string | Record<string,string> is a type change through WorkflowUnitDraft → IrUnitNode → decodeWorkflowPlanV3 validation → plan_json. Existing values stay authorable; the IR does not stay the same.
• step-work.ts:353-357,387 — the input-hash preimage includes env and the comment is explicit: "env carries NAMES ONLY, never resolved values: hashing a resolved secret would leak it into a durable hash oracle". A list containing literal mappings puts literal values into the preimage (fine) but mixes them with names, and secrets/<name> ref-valued entries must be hashed as refs, not values. Either way hashVersion: 4 (:379) has to become 5, which invalidates every journaled input_hash and every replay golden.
• Per-unit env is not supported. native-executor.ts:449-457 resolves env once per step, before any dispatch, from template.env, and passes one Record<string,string> to every unit (RunUnitInput.env, :611). §3.6's AKM_ITEM / AKM_ITEM_INDEX for map+shell steps requires per-unit env assembly, which also moves the sensitiveValues computation and the "one binding error fails the whole step cleanly" property (:446-448).
• The cascade also requires env at layers that have no env today: ProgramDefaults (program/schema.ts:203-211) has no env, and DEFAULTS_KEYS (parser.ts:104) does not list it.

Recommendation: drop "additively" from §3.7, name the hash-version bump, and specify per-unit env for map fan-out.

M9. Markdown-task recognition collides with the workflow adapter; the task goldens are declared immutable

§6: "Adapter | .yml-only recognize/place | markdown task recognized by type: task / tasks/ residence".

• src/core/adapter/adapters/index.ts:73-90 orders akmWorkflowAdapter before akmTaskAdapter.
• akm-workflow-adapter.ts:60-76 — "any .md file in this bundle IS a workflow … UNLESS its frontmatter declares a DIFFERENT non-empty type:".

So type: task is mandatory in practice for a markdown task in a workflow-adapter bundle; the "or tasks/ residence" alternative in §6 and the schedule-only examples pattern would be claimed as workflows. Note also that recognize() receives a component-relative path, and akmTaskAdapter.directoryList() returns ["."] (tasks live anywhere) — residence-based recognition is not available in this adapter's contract as written.

Separately, akm-task-adapter.ts:24-26 declares its fixture + four goldens (tests/fixtures/format-family-goldens/akm-task/{recognition,placement,lint,renderer}.json) a "Conformance oracle (authored, DO NOT modify)". §3.6's "schema and golden churn on a pre-release format — approved" does not acknowledge that these specific goldens are marked immutable, nor looksLikeRoot's .yml+schedule probe (:136-155), which would need a disjoint .md probe that does not fire on workflow bundles.

Recommendation: state that type: task is required (drop the residence alternative), and get explicit sign-off to re-author the akm-task conformance oracle.

M10. Migration is not a byte-rewrite, is not lossless, and re-creates the invisible-file failure

§8: "Task conversion joins it as one more content step", "No key survives with a changed meaning", and "The 0.7→0.8 lesson — leftover files must never be silently invisible — is honored structurally."

Four problems.

1. Shape. The existing task migration phase (scripts/akm-migrate/migrate/legacy/task-target-ref-migration.ts) rewrites YAML scalar bytes in place: TaskTargetRefRewrite = { filePath, from, to, before, after, mode } (:44-52) with an atomic same-path write. There is no rename in the plan structure, no journal phase for a rename, and no crash-resume story for a half-renamed set. .yml → .md plus a full frontmatter reshape plus body synthesis is a new migrator, not a new step.
2. Read-only bundles. :53-66 — readOnlyLegacyTasks exists precisely because "The migration NEVER rewrites a read-only bundle … but the 0.9 runtime removed the v1 parser, so these tasks will fail after upgrade." Under this proposal every .yml task in every registry-installed bundle becomes permanently unrunnable and unconvertible. "No key survives with a changed meaning" is true; "lossless" is not.
3. Invisible files. src/core/asset/asset-placement.ts:159-170 makes task .yml-only for isRelevantFile / toCanonicalName / toAssetPath. Flipping it to .md makes stray .yml task files invisible to resolveAssetPath — which is what akm task run uses (src/tasks/runner.ts:159). The 0.7→0.8 lesson is not honored "structurally"; it requires new code that deliberately scans for a no-longer-relevant extension in task sync / task doctor. That is a work item, not a property. (src/tasks/task-id.ts:8,15,41-46 also hardcodes .yml/.yaml, including in the portable-length budget.)
4. Dropped fields. The §8 table's llm.* row ends in an ellipsis. Three llm sub-fields have no home in §3.4's nine value fields: supportsJsonSchema, contextLength, enableThinking (src/tasks/parser.ts:331-338; src/tasks/schema.ts:61-68; schemas/akm-task.json:46-56; identical set on the workflow side, schemas/akm-workflow.json:76-87, and all six are carried into FrozenLlmEngine, freeze.ts:231-236). Either the vocabulary grows to twelve fields or the migration is lossy — the spec should say which.

M11. defaults.on_error is silently deleted

§3.4: "graph keys (map, route, inputs, output, gate, retry, on_error, isolation) are steps-only".

on_error is legal at document level today: src/workflows/parser.ts:104 (DEFAULTS_KEYS = ["engine","model","timeout","on_error","llm"]), schemas/akm-workflow.json:200, program/schema.ts:210, and it is read: compile.ts:231 — unit?.onError ?? defaults?.onError ?? "fail". Making on_error steps-only removes a working document-level default, and §8's migration table has no row for it.

Recommendation: either keep on_error (and retry, arguably) as a document default, or add a migration row that lifts defaults.on_error onto every step.

Minor

m1 — "Trigger keys are consumed only by akm task sync" (§3.3, decision 10) is inaccurate. enabled is also read at fire time by the runner: src/tasks/runner.ts:169 → shouldSkipUnactivatedTask({ enabled, scheduled }), which is activation-policy rule 3 (src/core/activation-policy.ts, doc block rule 3: "Task activation (tasks/runner.ts)"). This is a defense-in-depth property worth preserving; the spec's phrasing invites removing it.

m2 — §3.5's embodiment sentence is backwards. "akm agent embodiment honors it under an explicit --model override" — contribute-cli.ts:87-88: // --model flag wins over the asset's modelHint. The asset's model is honored in the absence of --model. The design conclusion drawn from it still stands, but the sentence should be fixed.

m3 — §3.5 understates the .yml prompt-asset bug. "prompt: agents/x resolves the asset to prompt text only". runner.ts:582-593 does fs.readFileSync(assetPath, "utf8") with no frontmatter stripping, so the YAML frontmatter (---\nmodel: opus\ntools: …\n---) is prepended to the prompt sent to the agent. Same for kind: "file" (:576-579). This is a live bug on the current branch, worth fixing independently of the proposal.

m4 — "the engine node … keeps its strict schema" overstates. Both LlmEngineSchema and AgentEngineSchema are .passthrough() (src/core/config/schema/engines.ts:54,82,104) with a blacklist superRefine (:83-88, :105-131). model legal on both, LLM fields rejected on agent kind — that part of §3.4 is verified. But the new value fields cwd, shell, env, params are in neither list, so an engine node would silently accept and silently ignore them. "Strict" needs to become strict (closed schema) if the spec's asymmetry argument is to hold.

m5 — status: draft overloads the OKF lifecycle family. schemas/akm-asset-envelope.json defines status: ["draft","stable","deprecated"] as "OKF v0.2 lifecycle status", shared across all asset types and stamped by okf-support.md's enhancement contract. §4 makes it load-bearing for scheduler installation ("draft tasks are never installed by sync"), creating a second activation gate alongside enabled: with no stated precedence, and leaving status: deprecated undefined. Recommend: keep activation on enabled: only, or define the truth table.

m6 — cwd: × isolation: worktree. request.cwd is currently set only by worktree isolation, and defaultUnitDispatcher rejects cwd on the llm runner (native-executor.ts:1063-1075). A user-set cwd: on an isolated step, or on an llm-engine step, has no defined behavior in the spec.

m7 — uses: coverage. §3.2 defines 5 of ~15 placement types (asset-placement.ts:89-178: skill, command, agent, script, memory, env, secret, lesson, task, session, fact, workflow, knowledge…). uses: lessons/x, uses: skills/x, uses: env/x need a stated rule (error with a hint, or "anything not listed is an error").

m8 — task id vs placement inconsistency inherited. asset-placement.ts:162-169 derives a task's canonical name from the relative path, so tasks/sub/x.yml indexes as sub/x; validateTaskId (task-id.ts:7, /^[A-Za-z0-9][A-Za-z0-9._-]*$/) rejects /, so akm task run sub/x throws. §4's "an ordinary akm markdown asset at <bundle>/tasks/<id>.md" plus the adapter's directoryList(): ["."] perpetuates it. Worth resolving in the same change.

m9 — embedded templates. src/tasks/embedded.ts:82 filters .yml and :97 drops any task whose target is not command — so the setup wizard's whole enumeration path changes with the format (and EmbeddedTask.command: string becomes run:). Confirmed 10 templates (src/assets/tasks/core/ ×5, src/assets/tasks/improve/ ×5), all command: targets, so §8's "ten embedded templates" is accurate.

Verified claims (the spec gets these right)

Recorded so the above is read as targeted, not blanket:

• §2 — akm workflow run is the canonical orchestrator; no start/next/complete subcommands; brief/report gated on experimental.workflowEngine (src/commands/workflow-cli.ts:160,324,351,522-530; src/workflows/exec/workflow-engine-gate.ts:39,56).
• §2 — scheduled workflow tasks run end-to-end (runner.ts:199-208,352-416 → runWorkflowSteps).
• §2 — UnitDispatchRequest carries prompt / frozen engine / timeoutMs / env / cwd / sensitiveValues, and results carry failureReason (unit-dispatch.ts:9-43).
• §2 — freeze assembles layers = [documentDefaults, unit], selects engine by nearest layer, resolves model/timeout/llm nearest-wins/deep-merged (freeze.ts:50,151-216) — accurate as far as it goes (see M1).
• §3.4 — temperature etc. are a config validation error on an agent-kind engine, model legal on both (engines.ts:99,105-120).
• §3.4 — command assets already read an agent: frontmatter field (renderers.ts:234).
• §3.5 — resolveModel is a four-tier chain (profile aliases → global table with "*" fallback → built-ins fable/opus/sonnet/haiku → verbatim), one level, no recursion (model-aliases.ts:45-104).
• §3.6 — output: is declared on both the step and the unit bag in schemas/akm-workflow.json (:234, :351). Present — but not a duplicate (C1).
• §3.7 — unit.env is currently array of string (akm-workflow.json:237-244).
• §6 — parseTaskDocument + TASK_KEYS + rejectTargetFields + resolvePromptSource = exactly 368 lines (src/tasks/parser.ts).
• §6 — akm-task.json is 87 lines and referenced only by tests/integration/tasks-schema.test.ts:8 (no runtime loader).
• §6 — runCommandTask runs raw argv only, no shell (runner.ts:277-289; parser.ts:300-306).
• §6 — lint lives in akm-task-adapter.ts as invalid-task-yaml (:88-98).
• §8 — task ids and the akm task run <id> ABI need not change; the scheduler argv shape is […akm, --scheduler-context, <path>, task, run, <id>, [--bundle <b>], --scheduled] and depends on the id, not the file format (scheduler-invocation.ts:59-78,198-227).
• §8 — 0.9.0 already refuses un-migrated installations at the config boundary (src/core/common.ts:228).
• §8 — ten embedded templates.
• §10 / §3.6 alignment with workflow-format-unification.md §2.3's forward reference: "If a non-agent unit kind (raw shell/exec) is ever added, that unit kind reintroduces substitution as its own need" — §3.6's AKM_ITEM env approach is consistent with that ruling.

Recommended changes before sign-off

1. Withdraw §10's "no changes to IR, freeze, journal, replay." Replace with an explicit list: IR v4, hashVersion 5, a shell node kind or third engine snapshot variant, a persona-layer freeze path, plan/journal migration for in-flight runs.
2. Fix C1 — keep two output spellings, or state the map-step loss.
3. Fix C3 — move the prose append to compile time, into the hashed instructions.
4. Remove params from the cascade vocabulary (C4).
5. Rewrite §2 bullet 5 and §3.4's framing (M1) to distinguish the two-layer nearest-wins resolver that exists from the five-layer cascade being proposed, and add defaults.model as a new config field (it is silently ignored today).
6. Add a provenance rule for bundle-asset configuration layers (M4, M6) — the tool-policy ceiling and script execution both need one.
7. Decide the placeholder grammar (M5) and the fate of $ARGUMENTS.
8. Rewrite §8 — losslessness is false for read-only bundles and for the three llm sub-fields; the migrator needs rename support; the "silently invisible" guarantee is a work item, not a structural property.
9. Independently fix, on the current branch: the dead llm guard (freeze.ts:67-73), the frontmatter-in-prompt bug (runner.ts:582-593), and the {{name}} vs {{0}} placeholder mismatch (renderers.ts:178 vs agent-dispatch.ts:68). All three are bugs today and the plan inherits them.