# Task / Workflow Unification: One Target Vocabulary, One Prose Rule

Status: PROPOSAL v9 — v8 (the post-Opus-review redesign) revised against a
four-lens Sonnet panel, then re-verified claim-by-claim against the current
baseline (98 claims checked, 22 corrected; a further 7 corrections from an
audit of that pass). Review corpus:
[`reviews/task-workflow-unification/`](./reviews/task-workflow-unification/).
Baselined on `origin/main` @ `17a0dca`, which merged the 0.9 polish branch
(`71bb686`). Breaking changes are approved for 0.9.0.
Date: 2026-08-01
Related: [`workflow-format-unification.md`](./workflow-format-unification.md),
[`okf-support.md`](./okf-support.md),
[`docs/reference/workflows.md`](../../reference/workflows.md)

> **2026-08-18 owner clarification:**
> [Agent, Command, Engine, and Model Resolution](./agent-command-engine-model-design.md)
> is authoritative wherever this proposal discusses agent personas, command
> execution, command placeholders, engine/model cascading, tool policy,
> capability handling, or model aliases. In particular, this proposal's
> `with:`/named/positional command-template grammar, primary-bundle tool-policy
> ceiling, static engine-capability declarations, and built-in wildcard alias
> recommendations are superseded. The owner subsequently settled the 0.9.2
> source-format direction in the
> [0.9.2 implementation plan](../../plans/0.9.2-agent-command-workflow-plan.md):
> task v3 is GitHub-step-shaped, AKM Markdown and GitHub-shaped YAML are peer
> workflow formats, and both compile through one internal versioned IR. The
> concrete schemas and examples below are therefore non-normative. The
> still-compatible concepts — tasks as scheduling wrappers, agents as
> selectors rather than targets, task composition in workflow steps, live task
> resolution, and frozen workflow resolution — remain design input.

---

## 1. Grounding — what tasks and workflows are in akm

Owner's model; everything below derives from it.

1. **A task is a bundle asset that abstracts over OS-scheduled work** —
   discovered like any asset, *enabled* into a cron/launchd/schtasks entry
   that executes the defined work or dispatches an agent with the task's
   prompt. A platform-agnostic way to share repeatable processes behind one
   CLI.
2. **A workflow step is a task** — defined inline or referenced by ref — so
   the same repeatable process is composable without duplicating content or
   config.
3. **Fewer concepts, lower cognitive load.** akm is a simple, intuitive
   abstraction layer over the tools and processes autonomous agents use.

Not in scope: tasks do not grow `steps:`; workflows do not grow `schedule:`.
The unit of sharing is the asset, of scheduling the task, of procedure the
workflow.

## 2. The format (stable since v5–v6, corrections applied)

### 2.1 Targets

| Declaration | Work performed |
|---|---|
| *(none)* | Agent, prompted with **the nearest prose** — a task's body, or a step's `## <id>` section |
| `uses: <asset-ref>` | Execute the referenced asset per its subdir-declared type (§2.2) |
| `run: <shell text>` | Shell, no AI — GitHub-Actions semantics; `sh` on POSIX, `powershell` on Windows, `shell:` override |

`uses:` xor `run:` — one schema rule; the double-target error class is
structurally impossible. No ref-vs-inline sniffing exists.

> **The prose rule.** The machine surface names the target; the nearest
> prose is the instructions. With no target key, the prose *is* the work.

### 2.2 `uses:` — a closed set of four executable types

| Ref | Execution | Inputs |
|---|---|---|
| `uses: commands/<n>` | Fill the template (§2.4), dispatch an agent | `with:` |
| `uses: scripts/<n>` | Execute per the script's `run`/`setup`/`cwd` — gated by the execution-activation policy (§5.6) | `env:` |
| `uses: tasks/<n>` *(steps only)* | Compose the task as this step's work (§2.3) | the task's own, overridable |
| `uses: workflows/<r>` *(tasks only)* | `runWorkflowSteps()` | `with:` → declared param flags |

Any other subdir (including `agents/` — a persona, not work) is an error
with a targeted hint. **`with:` replaces v5–v7's call-site `params:`** —
review finding M1 (3/3): `params:` already means *declarations* (name →
JSON Schema) in workflow frontmatter, and one key carrying declarations,
run-arguments, placeholder fills, *and* a cascading value was the same
overload this spec deletes `prompt:` for. GHA's `inputs:`/`with:` split
exists precisely here, and §2.4/§4 give `with:` exactly one meaning:
**inputs handed to the referenced asset, never cascaded.**

Two `uses:` modes differ in kind, named for authors: `tasks/<n>`
**composes** — the referenced definition becomes this step's own work —
while `workflows/<r>` **invokes** — a child run executes and returns.
`with:` merge on a composition chain (a step referencing a task that
itself targets a command or workflow) is per-key shallow merge, referencing
step wins; `with.arguments` is one key, replaced whole. The merged mapping
feeds the final target: placeholder fill for a command, declared param
flags for a workflow.

### 2.3 Steps are tasks — composition by reference

```yaml
steps:
  - id: lint
    uses: tasks/lint-check   # the task's target, fields, env, and body
    timeout: 2m              # call-site override (one cascade layer nearer)
  - id: fix
    run: bun run fix         # inline task: same keys, defined here
```

- Step keys override the referenced task's keys — the task and the step are
  adjacent cascade layers (§4); `env:` concatenates task-then-step.
- Trigger keys (`schedule`, `enabled`) are consumed **only** by
  `akm task sync` and, at fire time, the task runner's enabled gate
  (`src/tasks/runner.ts:169` — v7's "sync-only" wording corrected).
  Anywhere else they are no-ops with a lint notice; a referenced task
  cannot double-fire.
- **Call-site prose is appended at freeze, not at dispatch.** Review
  finding (3/3): there is no "one assembled prompt seam" — prompts are
  built per-unit at dispatch, and the unit hash covers the *frozen
  template*, not the assembled string. So: when the resolved work is
  agent-dispatched, the step's section text is concatenated onto the
  frozen instruction template (blank-line separator, byte-exact) **at
  freeze**, which puts it inside the hash preimage automatically and keeps
  the append ahead of the item/inputs/gate blocks. For shell work the
  section is documentation, ignored at runtime.
- Refs resolve at freeze (§5.4), so in-flight runs are immune to edits.
- No nesting: a referenced task targeting `workflows/*` is a compile error
  on a step; a task referencing a task is an error.

### 2.4 Command templates — filled against the real placeholder grammar

Review finding M2 (3/3): command placeholders are `$ARGUMENTS` / `$1`–`$9`
(positional) and `{{name}}` per the advertised grammar
(`extractParameters`, `src/output/renderers.ts:164-186`); the actual
filler is `fillPlaceholders()` in
`src/commands/agent/agent-dispatch.ts:67-72`, which substitutes only
positional `{{0}}` forms, leniently — a live bug fixed by this work, and
a second call site the new `with:` contract replaces. Three further
grammars for the same placeholders exist today and diverge from each
other: the indexer's recognition sniff `COMMAND_PLACEHOLDER_RE`
(`src/indexer/walk/matchers.ts:126`, consumed at `:239`) matching only
`$ARGUMENTS`/`$1`–`$3`; `extractCommandParameters`
(`src/indexer/passes/metadata.ts:440-461`), a near-clone of the display
grammar that differs from it in case-sensitivity and digit bounding; and
a lenient sniff at
`src/core/adapter/adapters/tool-dir-shared.ts:201-204`.

**Convergence is scoped to the fill and display grammars — the two
recognition sniffs keep their `$`-only forms.** Adding `{{name}}` to
`COMMAND_PLACEHOLDER_RE` would be a live mis-classification hazard, not a
cleanup: it returns specificity 18, outranking the directory rules
(10/15), so any `knowledge/`, `facts/`, or `instructions/` `.md`
containing a mustache token would be re-typed `command`. The recognition
gap is narrower than it looks anyway — `classifyByDirectory` /
`classifyByParentDirHint` (`matchers.ts:43-47`, `:147-156`, `:178-197`)
already type any `.md` under `commands/` as a command at specificity
10/15, beating `classifyBySmartMd`'s `knowledge` (5). The sniff is only
the fallback for command-shaped `.md` living *outside* `commands/`
without `tools:`/`agent:` frontmatter. The contract, defined against that
reality:

- `with:` mapping keys fill `{{name}}` placeholders.
- The reserved key `with.arguments` (string) fills `$ARGUMENTS`, and its
  whitespace-split words fill `$1`–`$9`.
- An unmatched placeholder or unused `with:` key is a **lint warning and is
  left verbatim** — not a runtime hard error, so imported `$ARGUMENTS`
  commands remain usable as targets.
- `with.arguments` is reserved: a literal `{{arguments}}` placeholder is
  filled by it too, with a lint warning about the shadowing. Words past
  `$9` remain reachable only through `$ARGUMENTS`.

Filling happens at freeze (workflows) / dispatch (tasks), producing the
prompt string. Bodies remain verbatim — templating stays scoped to the
command asset type, whose definition is "a template with placeholders."

## 3. The task asset

`<bundle>/tasks/<id>.md`: the shared envelope (`$ref
akm-asset-envelope.json`, OKF v0.2 families included), trigger keys, at
most one target, and any §4 fields. No `version:` key. **Recognition
requires frontmatter `type: task`, honored in two subsystems** (R2
finding: v8 cited only one). At the bundle-adapter layer, the workflow
adapter is ordered ahead of the task and generic akm adapters in the
source-root probe list (6th of 11 —
`src/core/adapter/adapters/index.ts:73-90`; that array is `looksLikeRoot`
probe order, and only the adapter that claims a root ever calls
`recognize()` on its files), and inside an akm-workflow bundle it claims
every `.md` file whose frontmatter does not declare a contrary `type:`
(`akm-workflow-adapter.ts:67-70`, `:160`). At the per-file
indexer classifier — the path that actually types `tasks/*.md` during
normal indexing — `src/indexer/walk/matchers.ts` gains a `type: task`
branch **ordered before** its existing `"agent" in fm → command` rule
(`matchers.ts:234-236`), which would otherwise misclassify any task
carrying an `agent:` selector — including this section's own example.
Residence is a lint *expectation*, not a recognition signal.

````markdown
---
type: task
description: Weekly review digest.
schedule: "0 8 * * 1"
agent: agents/reviewer
timeout: 10m
---

Review the week's completed tasks and summarize action items.
````

````markdown
---
type: task
description: Full nightly quality sweep.
schedule: "15 2 * * *"
run: akm improve --strategy thorough --skip-if-locked
---

# Nightly improve sweep

Runbook prose: indexed, shown, never executed.
````

````markdown
---
type: task
schedule: "@daily"
uses: commands/weekly-review
with: { scope: team }
env: [env/prod]
---
````

Lifecycle unchanged: discover via search/show; enable via `enabled:` +
`task sync`; the OS entry still invokes `akm task run <id>`. Lifecycle
interactions pinned (review minors): `status: draft` → `sync` never
installs, regardless of `enabled:`; `status: deprecated` → installs with a
warning; a previously-installed task that becomes `draft` (or
`enabled: false`) is uninstalled by the next `sync` — reconciliation is to
desired state, both directions.

Two adapter-policy changes with named mechanisms (panel M13 follow-up):
the akm adapter's current `type: "task"` special-case — parse as pure
YAML, `frontmatter: null`, so markdown base checks never fire
(`akm-adapter.ts:404-412`) — is **removed with the format**, and markdown
tasks get the full markdown base-check suite; and tasks are declared
**improve-ineligible**. No such site exists on `BundleAdapter`
(`src/core/adapter/bundle-adapter.ts:69-121` declares only adapter-level
optional methods), so v8's "where the adapter already declares per-type
capabilities" was wrong. Three candidate homes, cheapest first: the
existing per-type refusal set `DISTILL_REFUSED_INPUT_TYPES`
(`src/commands/improve/distill.ts:134-142`, already gated at
`eligibility.ts:380` and documented as driving the planner "for free")
gains `task`; or the per-type table `TYPE_PRESENTATION`
(`src/core/type-presentation.ts:74`) gains an eligibility flag; or
`eligibility.ts` gains an explicit type filter. A task body is an
executable prompt,
not curatable knowledge. Lint runs; improve never rewrites it.

## 4. Configuration: two selectors, one value vocabulary, one cascade — built, not "exposed"

v7 claimed freeze "already implements" the cascade. Review finding C4
(3/3): freeze's layer list is exactly `[documentDefaults, unit]`
(`freeze.ts:50`); `DefaultsSchema` has **no** `model` field and is
`.passthrough()`, so v7's own worked example is a silent no-op today
(`config-schema.ts:102-108`); `defaults.llm` is hard-rejected as retired;
no persona layer exists. What exists is a two-layer resolver whose *shape*
proves the pattern fits. This section specifies **building** the rest.

**Selectors** (nearest wins; each picks a node whose fields join the
cascade):

| Selector | Node | Source |
|---|---|---|
| `engine:` | execution node | config `engines.<name>` |
| `agent:` | persona node | bundle `agents/<name>` |

**Value fields** — legal at every layer, merged per-field, nearest wins;
`env:` concatenates: `model` · `temperature` · `max_tokens` ·
`extra_params` · `timeout` · `env` · `cwd` · `shell` · `on_error` · `retry`.

(`with:` is *not* a value field — it binds to one referenced asset. `params`
no longer exists as a field name outside workflow declarations. `on_error`/
`retry` join the vocabulary because `defaults.on_error` already exists at
document level today — review M12 — making "graph keys are steps-only"
false for them; they remain meaningless on a task and lint says so. Value
fields other than `timeout`/`env` on a `uses: workflows/*` task draw the
same inapplicable-field notice — they configure a unit, and a workflow
invocation has none.)

**Merge classes, stated once** (panel finding: a generic "nearest wins"
would silently downgrade the existing deep-merge): **scalars** (`model`,
`temperature`, `max_tokens`, `timeout`, `cwd`, `shell`, `on_error`) —
nearest wins whole; **mappings** (`extra_params`) — deep-merged along the
chain, preserving today's `deepMergeConfig` behavior
(`freeze.ts:211-216`); **lists** (`env`) — concatenated, later wins;
**`retry`** — replaced whole (half-merging `max`/`on` would be
incoherent). `with:` merges per-key at its target (§2.2), outside the
cascade.

**Layers, far → near:**

```
config defaults: → engines.<selected> → agents/<selected> → document defaults: → uses: tasks/<ref> → step/task keys
```

(`document defaults:` is the workflow frontmatter's `defaults:` block and
exists only there — a standalone task IS its own call site, so for tasks
that layer is simply absent, not an implied new task key.)

**What must be built (the honest inventory):**

1. `DefaultsSchema` gains the value fields, and stops silently swallowing
   unknown keys (strict with migration-safe notices).
2. A **persona snapshot**: the agent asset resolved through the
   provenance ceiling — 07 P1-D, today inline in the show command
   (`src/commands/read/show.ts:433-445`): self-declared `tools:` honored
   ONLY for the operator's **primary bundle**, keyed off primary-bundle
   identity, explicitly *not* the writable bit, failing closed. That
   check is **extracted into a shared persona resolver** consumed by both
   `show` and freeze — a named refactor in §9, since its current home is
   a CLI formatter. The snapshot `{systemPrompt, toolPolicy, model,
   …valueFields}` freezes into the plan; `toolPolicy` is consumed by
   agent-kind engines and draws the standard unconsumed-field notice on
   LLM engines. (This also fixes the live bug where `prompt: agents/x`
   ships raw file bytes *including frontmatter* to the model —
   `runner.ts:592-593`.)
3. One cascade module — a new shared module (e.g. `src/core/cascade.ts`;
   there is no `src/exec/` tree today, only `src/workflows/exec/` and
   `src/tasks/`) — the only implementation of layer merge, consumed at
   freeze (workflows) and dispatch (tasks). It
   consolidates the three engine/model resolution sites that exist today
   (`freeze.ts:163-209`, `tasks/runner.ts:479-514`, engine-resolution)
   including their subtly divergent opencode-sdk `llmEngine` fallback
   rules — one implementation, one fallback rule.
4. **Capability notices replace both kind-gates.** The task path's hard
   error and freeze's guard — which review M6 showed is *dead code*
   (`freeze.ts:67-73` computes `llm` only for llm engines, then guards
   `kind !== "llm"`), meaning workflows already silently drop these fields
   — are both replaced by one behavior: engines declare the fields they
   consume; an unconsumed field is a lint/freeze **notice**. Strictness
   stays only where the kind is known at authoring time: the engine node's
   own schema (which today is `.passthrough()` + blacklist; it becomes
   genuinely strict as part of this work — review minor).
5. Aliases: resolution runs once, after the cascade settles `model`,
   through the existing `resolveModel()` chain. Review M4 (3/3): the
   builtin table has only `claude`/`opencode` columns, so portability to
   LLM endpoints is currently *false* — the builtin entries gain a `"*"`
   column, and an alias that resolves nowhere for the selected platform is
   a freeze/lint notice, not silent pass-through.
6. The gate judge (`workflow.judgeEngine`) stays outside the cascade in
   0.9.0 — frozen separately, as shipped. Noted, not changed.

One sentence to teach: *set a field where it should usually apply;
override it closer when a case differs; the nearest value wins.*

## 5. Execution architecture

### 5.1 One target model, two executors

A shared target module resolves every declaration to a typed value:

```
Target = { kind: agent-prose }            # nearest prose is the prompt
       | { kind: command,  ref, with }    # template fill → agent prompt
       | { kind: script,   ref }          # script asset, exec
       | { kind: shell,    text, shell }  # inline run:
       | { kind: workflow, ref, with }    # tasks only
       | { kind: task,     ref }          # steps only; resolves recursively once
```

Execution is a strategy seam with exactly two implementations:

- **AgentUnitExecutor** — today's paths (task runner's `executeRunner()`;
  the orchestrator's journaled `UnitDispatcher`), consuming an assembled
  prompt + frozen engine + persona snapshot.
- **ShellUnitExecutor** — `Bun.spawn()` for `run:` text and script assets,
  used by both the task runner and the orchestrator.

Staging is symmetric and named (panel: the task path's staging was
unstated): **tasks** run *resolve → execute* — the same resolve stage
(cascade, persona, targets, templates) with no plan persistence;
**workflows** run *compile → resolve → freeze → execute* (§5.4). Both
executors sit behind one interface; each surface wraps results into its
own recording sink (`task_history`/`logs.db` vs the run journal) — the
adapter lives at the sink, not inside the executor, which is how the
`RunnerSpec`-vs-`UnitDispatchRequest` split stays out of the executors'
type signatures: the resolve stage produces one dispatch plan both
consume. **ShellUnitExecutor is extracted from the task runner's existing
hardened command path** (`runManagedSubprocess`, `src/core/subprocess.ts`,
called at `tasks/runner.ts:277-289`: process-group spawn, SIGTERM→SIGKILL
kill ladder, injectable spawn/timer seams, `AKM_EVENT_SOURCE` stamping)
and adopted by the orchestrator — not a new spawn wrapper.
(`src/tasks/backends/exec-utils.ts` is the scheduler-backend exec seam,
not part of this path.) Composition is monotemporal by rule: a referenced
task's fields join the cascade from the copy resolved at freeze, under the
workflow's config snapshot — a composed task never re-reads config at
dispatch.

Run recording stays split (cron job vs journaled plan) — that boundary is
real. Everything upstream unifies: target resolution, template filling,
cascade, alias resolution, env assembly.

### 5.2 Shell units in the IR — v3 → v4, not a non-goal

Review C2 (3/3): `IrInvocation.engine` and `UnitDispatchRequest.engine`
are required, the engine snapshot union is closed, freeze hard-errors with
no engine, and the IR rejects empty instructions — v7's "no IR changes"
was false. Owned properly:

- `IrInvocation` becomes a discriminated union:
  `{ kind: "agent", engine, … }` | `{ kind: "shell", script, shell, cwd,
  timeoutMs }` (`timeout` is a value field for `run:`, so the shell member
  carries it). Shell members exclude engine/llm fields **structurally** —
  by union-member shape, not by decoder-validated absence.
- Engine resolution happens **per unit kind**: shell units need no engine,
  so a shell-only workflow freezes on an engine-less machine (the current
  "no engine selected" error narrows to plans containing agent units).
- Instructions become optional for shell units (parser + IR relaxation —
  review M10; agent units keep the non-empty invariant).
- Shell units journal as normal `workflow_run_units` rows (status, timing,
  attempts, `failure_reason`; no tokens). Under the external driver
  protocol, shell units are **orchestrator-owned**: `brief` lists them as
  non-claimable and the engine executes them natively — a harness never
  claims shell work.
- Crash/restart: shell units use the same claim/lease rows as agent
  units; a running shell unit whose lease expires re-dispatches on resume
  under its retry policy. Re-execution idempotency is the author's
  contract — the same contract every cron job already carries — stated in
  the docs, not solvable by the engine.
- Plan IR version bumps to 4; decoders reject v4 plans in older binaries
  (existing plan-version machinery).

### 5.3 Unit identity — hashVersion 5, preimage stated

Review C3 (3/3): hashVersion 4's preimage (`step-work.ts:333-392`) covers
the frozen template bytes but none of the *other* new inputs — shell text,
the `uses:` target kind/ref/content hash, and the persona snapshot.
Without a bump, editing `run:` text, re-pointing a `uses:` ref, or editing
`agents/<n>` would silently reuse completed journal rows. (Freeze-time
prose appending, §2.3, already rides in via `template`.) hashVersion 5's
preimage, explicitly:

| Field | Notes |
|---|---|
| template instructions | **post** freeze-time prose append (§2.3) and **post** template fill, so `with:` values are covered via the filled bytes |
| target kind + `uses:` ref + resolved content hash | a re-pointed or edited referenced asset re-dispatches; also the retained provenance for composed steps (the "single-file provenance" minor). Script bytes are **embedded at resolve**, like a command's filled text — execution never re-reads live files, keeping composition monotemporal (§5.1) |
| persona snapshot hash | system prompt, tool policy, and value fields of the frozen persona — editing `agents/<n>` re-dispatches (panel critical: omitted in v8) |
| shell text, `shell`, `cwd` | shell units |
| item / inputs / params / dispatch / invocation / schema | as v4 |
| env **names** + env **literal values** | see §5.5 — literals are plan content; ref-sourced values stay names-only |
| isolation, gateFeedback | as v4 |

`retry`/`on_error` stay excluded (policy, not input) — unchanged rationale.

### 5.4 Freeze becomes two stages; lint gets a dry freeze

Review M11: `uses:` resolution needs asset IO inside a function documented
pure, and freeze currently has exactly one caller (run start), so every
composition error would escape lint. Restructure: **compile** (pure) →
**resolve** (asset loader injected: personas, referenced tasks, command
templates) → **freeze** (snapshot + hash). `akm lint --type workflows`
runs compile+resolve with the real loader and no persistence, so dangling
`uses:` refs, back-door workflow nesting, placeholder mismatches, and
capability notices all surface at lint time. Composed instructions carry
the existing 256 KiB cap with a lint warning at 80%.

### 5.5 `env:` — one shape, two provenance classes

Format unchanged from v6 (list of env-asset refs and literal mappings,
later wins, bare-mapping shorthand). Semantics corrected by review M3
(3/3), which showed "strictly additive" was false at the IR/hash/redaction
layers. The clean line is **provenance, not shape**:

- **Literal entries** are plan content: author-written bytes already
  durable in the source file — frozen into the plan, hashed (§5.3), shown
  by `brief`, **never redacted** (`LOG_LEVEL: debug` must not scrub
  "debug" from every log — the over-redaction finding).
- **Ref-sourced entries** (`env/<n>` groups, `secrets/<n>` values) are
  runtime-resolved: hashed by **name only**, resolved at dispatch, values
  joined to `sensitiveValues` for redaction, never durable. (Existing
  contract, now stated as the rule.)
- IR `env` becomes a typed entry list (ref | literal-pair) — an IR v4
  change, not "additive."
- Env assembly moves per-unit where fan-out requires it: a `map:` step
  with a shell target receives `AKM_ITEM` (JSON) and `AKM_ITEM_INDEX`
  per unit — set as env-object entries on the spawned process (the
  `runManagedSubprocess` `env:` pattern — `src/core/subprocess.ts`, as
  used at `tasks/runner.ts:284`), never spliced into shell text.
- Literal entries run the existing secret-shape heuristic
  (`param-secrets.ts`'s `detectSecretShapedParams`, built for exactly this
  risk on params): a secret-shaped literal is a lint error pointing at
  `secrets/<n>`.
- The split is enforced at one place: a single env-assembly resolver (§8
  plumbing) is the only producer of env entries and of their
  `sensitiveValues` contributions, so the literal/ref line cannot
  silently diverge per call site.

### 5.6 Executing scripts inherits the tools: ceiling — no new trust machinery

v8 proposed a per-bundle grant key. The panel killed it twice over:
`activation-policy.ts` documents a standing decision **against new
persisted trust machinery**, and the claimed precedent — the `tools:`
provenance ceiling — has **no override at all**. v9 inherits the ceiling
exactly instead of imitating it loosely:

- Shell-class work (a script asset, or the `run:` text of a task) executes
  **only when its defining asset lives in the operator's primary bundle** —
  the same line 07 P1-D draws for self-declared tool grants
  (`show.ts:433-445`): keyed off primary-bundle identity, explicitly *not*
  the writable bit, failing closed.
- Evaluated in the **resolve stage** (§5.1) — the shared stage both
  surfaces run before any execution — so there is no sync-time/fire-time
  gap and no standing grant for a bundle update to swap content under.
- Composition chains inherit the rule from the **defining asset's own
  source**: a primary-bundle task that `uses:` a third-party script — or
  composes a third-party task whose target is shell — refuses with an
  error naming the ref and its source. No chain launders provenance.
- The remedy is an existing verb, not a config bit: `akm clone <ref>`
  copies the asset into the primary bundle, where the operator owns and
  reviews the bytes; the refusal message says exactly that.
- Scope: this ceiling governs the **new non-AI exec surface only**.
  Agent-dispatched third-party tasks remain governed by the existing
  scheduling gates (setup/sync review, `enabled:`), unchanged.

Zero new config, zero persisted trust state. Loosening later (per-bundle
grants) is an additive future decision that must revisit the
activation-policy document — deliberately out of 0.9.0 scope.

### 5.7 Shell ergonomics

- Bare `akm` in shell/script work resolves to the current installation by
  a **synthesized shim**, not a bare PATH prepend: `resolveAkmInvocation()`
  can return a multi-element launcher invocation (`bun <script>` — the
  case the argv-splice was built for, panel M9 follow-up), so the runner
  writes a platform-appropriate shim (sh script / `.cmd`) invoking the
  exact resolved invocation into the run's temp dir and prepends that dir
  to the child `PATH` (case-insensitive `Path` merge on Windows). Replaces
  the argv rewrite for shell work and covers scripts for free; the task
  runner keeps the argv rewrite only for legacy `.yml` until retirement.
- `cwd:` under `isolation: worktree` is resolved relative to the worktree
  root; `cwd:` on the LLM runner is a capability notice (review minors).

## 6. GitHub Actions alignment — familiar, not copied

Adopted: `uses:`/`run:` pair with mutual exclusion; **`with:` for inputs
to the referenced thing** (returned to the adopted column by M1);
step-level keys with no nesting bag; shell semantics with per-OS defaults
and `shell:`; `env:` bare-mapping shorthand; `cwd:`; `on_error`/`timeout`
as step keys. Kept akm: typed asset refs (the subdir says what executes —
GHA's `uses:` is opaque); `params:` reserved for declarations; no step
`name:`; bundles as the sharing unit.

## 7. Steps flatten to the task shape — with the schema collision fixed

The `unit:` bag and `map.unit` are still deleted; targets and value fields
sit on the step; `map:` keeps `over`/`concurrency`/`reducer`. But v7's
"duplicate `output` wart" was **wrong** — review C1 (3/3):
`unit.output` compiles to the per-dispatch structured-result `schema`
(driving structured retry / `parse_error`) while `step.output` compiles to
`outputSchema`, the promoted artifact the gate validates
(`compile.ts:204,229` — verified). Two concepts, two homes:

- **`output:`** on a step — the step's **artifact** schema, all step kinds.
  On a unit step it also serves as the dispatch result schema (result *is*
  the artifact).
- **`map.output:`** — the **per-item** result schema of a map step's units;
  the step's `output:` continues to describe the reduced artifact.

```yaml
- id: review
  map: { over: steps.intake.output.files, concurrency: 3, output: { type: object } }
  output: { type: array }        # what `steps.review.output` resolves to
```

## 8. Migration — inside the hardened 0.9.0 cutover

Rebuilt against the `71bb686` migrator and review M7 (3/3):

- **The converter joins the content-migration step with a vendored,
  frozen copy of the v2 task parser** — the current
  `task-target-ref-migration.ts` imports the *live* parser from `src/`,
  which violates the frozen-migrator principle and breaks the moment the
  live parser is replaced; that gets fixed as part of this work.
- Mapping: `command: <shell string>` → `run:` verbatim; `command:
  [argv…]` → `run:` with each element shell-escaped **for POSIX `sh`, the
  migrated task recording `shell: sh` explicitly** so the Windows
  `powershell` default never reinterprets the quoting; `prompt: |` →
  body; `prompt: commands/x` → `uses:` + `with:`; `prompt: agents/x` →
  `agent:`; `prompt: ./file.md` → inlined; `workflow:`+`params` →
  `uses: workflows/…` + `with:`; `timeoutMs` → `timeout`;
  `llm.maxTokens`/`llm.temperature`/`llm.extraParams` → flat fields;
  **`name:` → the body's H1** when the converted body has none, else a
  per-task migration notice (never silently dropped);
  `llm.supportsJsonSchema`/`contextLength`/`enableThinking` are
  endpoint-capability facts that belong on the **engine node** — the
  migrator emits a per-task notice naming the value and the config key
  (lossy-with-notice, never silent).
- Scheduler entries untouched: ids and the `akm task run <id>` ABI do not
  change.
- **The `.yml` tombstone rule** replaces v7's false "structural" claim
  (refusals key on config/DB shape, not stray files, and placement
  filters by extension — a stray `.yml` today would be invisible or
  wrongly installed): task discovery keeps matching `tasks/*.yml`
  **permanently, as a diagnostic**. In **writable** bundles, `sync`,
  `doctor`, and `lint` hard-error naming the file and the fix; in
  **read-only/third-party** bundles the same diagnostic is a warning —
  the operator cannot edit those files, matching the migrator's existing
  read-only carve-out (`task-target-ref-migration.ts:253-271`). Either
  way a `.yml` is never installed and never silently skipped.
  `<id>.yml` + `<id>.md` colliding on one conceptId is the same named
  error. **Conversion is interruption-safe by ordering**: the migrator
  journals the `.md` write and verifies it before removing the `.yml`,
  and the collision diagnostic special-cases the byte-equivalent
  mid-migration pair (resume completes the removal instead of erroring on
  the migrator's own half-applied state — the panel's crash-window
  finding; the current *backup* model journals whole-DB/config artifacts
  only (`migration-backup.ts:54`), so per-file crash safety lives in the
  content-migration step's own resume ledger —
  `content-migration-report.json`'s `reservedRenames`
  (`config-migrate.ts:518-575`); the `.md`-write-then-`.yml`-delete
  ordering extends that existing ledger rather than introducing per-file
  journaling, costed in §9).
- Embedded templates convert to `.md`; `listEmbeddedTasks` and `akm
  setup`'s task review move to markdown-aware editing (the current YAML
  round-trip would destroy bodies — review minor).
- The id-grammar work (subdir ids, scheduler-id `/` → `--` mapping with
  collision lint) lands **in the same migration step, before scheduler
  reconciliation** — sequencing the panel flagged as unstated.
- The pre-flatten workflow schema (`unit:`, `map.unit`, `defaults.llm`)
  converts in the same step: bag fields lift, `llm` flattens,
  `unit.output` → `map.output` or step `output:` per §7.

## 9. Cost inventory — what this actually changes

Honest replacement for v7's §10 (review: "non-goals false ×4").

| Surface | Change |
|---|---|
| IR | v3 → v4: invocation union, optional instructions (shell), typed env entries, `map.output` |
| Unit hash | hashVersion 4 → 5 (§5.3 preimage) |
| Freeze | two-stage (compile/resolve/freeze), per-kind engine resolution, persona snapshot, prose append, capability notices |
| Dispatch | executor strategy (agent/shell); persona fields reach `UnitDispatchRequest` |
| Schemas | shared target+value defs; task schema rewritten; workflow schema flattened; `DefaultsSchema` extended and made strict; engine schemas made strict |
| Parsers | `parseTaskDocument` retired to the migrator (vendored); unified parser gains task recognition; section-required rule relaxed per target kind; the indexer classifier (`matchers.ts`) gains a `type: task` branch ordered ahead of the `"agent" in fm` rule |
| Adapters | markdown task recognition (`type: task`); the `type: "task"` pure-YAML special-case removed (markdown base checks apply); improve-ineligibility declared per-type (§3 — `DISTILL_REFUSED_INPUT_TYPES` is the cheapest of three homes); akm-task format-family goldens rewritten directly (they carry `specificationGolden: true` / `adapterStatus: NOT IMPLEMENTED`, and `DESIGNATIONS.json` does not cover that tree at all). **DESIGNATIONS re-pointing is mandatory pre-work**: six entries are touched — `cli/c-tasks-family.json` (already `re-baseline`, chunk 9) plus five goldens pinning `tasks/*.yml` paths — `recognition/all-types.json`, `placement/all-types.json`, `minting/oracle.json` (chunk 4), `lint/all-types.json` (chunk 3), `renderer/all-types.json` (chunk 8) — whose `reBaselineChunk` must be re-pointed at this change *before* it lands, per the DESIGNATIONS `$policy` surface-owner rule |
| Named refactors | 07 P1-D ceiling extracted from `show.ts` into a shared persona resolver; ShellUnitExecutor extracted from the task runner's hardened command path; the three engine/model resolution sites consolidated into the cascade module; the `akm` shim mechanism; per-file create-verify-delete ordering added to the content-migration step's existing `reservedRenames` resume ledger |
| CLI | `task create`; `task add` retires with `.yml`; capability notices in lint/doctor |
| Storage | `task_history.target_kind` values widened (additive) |
| Docs/tests | reference docs, ~10 templates, format-family goldens, parser/freeze/executor suites |

Inherited bugs fixed en route: `{{0}}`-only placeholder filling; raw
frontmatter shipped to models via `prompt: agents/x`; subdir task ids
indexed but unrunnable (`validateTaskId` rejects `/` — the id grammar
gains subdir support with the scheduler-id mapping documented); freeze's
dead llm guard.

## 10. Non-goals (now true)

- No new orchestration semantics: `map`/`route`/`gate` behavior, leases,
  check-ins, replay *logic*, and the driver protocol are unchanged (shell
  units are orchestrator-owned under it).
- No scheduler-backend, `sync`-reconciliation, or `akm task run <id>` ABI
  changes.
- No change to how command/script/agent/env/secret assets are authored.
- No multi-file config merging; the cascade layers are config nodes,
  bundle assets, and document/call-site keys.
- Gate judge selection stays outside the cascade in 0.9.0.

## 11. Findings cross-reference and decision log

| Finding (consolidated) | Resolution |
|---|---|
| C1 output collision (3/3) | §7 — two schemas, two homes (`output:` / `map.output:`) |
| C2 shell units unrepresentable (3/3) | §5.2 — IR v4 invocation union, per-kind engine resolution |
| C3 hash preimage (3/3) | §5.3 — hashVersion 5, preimage table; §2.3 freeze-time append |
| C4 cascade layers don't exist (3/3) | §4 — "built, not exposed"; build inventory |
| C5 script execution security (2/3) | §5.6 — the tools: ceiling inherited exactly (primary-bundle only, no override); v8's grant key withdrawn after the panel showed it contradicted activation-policy's no-new-trust-machinery decision |
| M1 params overload (3/3) | §2.2 — `with:` for inputs; `params:` declarations only; neither cascades |
| M2 placeholder grammar (3/3) | §2.4 — `with:`/`with.arguments` against the real grammar; lenient + lint |
| M3 env not additive (3/3) | §5.5 — literal/ref provenance split; IR v4; per-unit env |
| M4 alias portability (3/3) | §4.5 — `"*"` columns + unresolved-alias notice |
| M5 agent plumbing + ceiling; false corroboration | §4.2 — persona snapshot via show layer; corroboration claim retracted |
| M6 dead kind-gate (2/3) | §4.4 — both gates → capability notices |
| M7 migration overclaims (3/3) | §8 — vendored parser, full mapping, tombstone rule |
| M8 adapter recognition (2/3) | §3 — `type: task` required |
| M9 akm-bin rewrite (2/3) | §5.7 — synthesized shim (a bare PATH prepend cannot cover multi-element launcher invocations) |
| M10 prose invariants (2/3) | §5.2 — per-kind relaxation, costed |
| M11 lint never freezes (1/3) | §5.4 — dry freeze in lint |
| M12 `defaults.on_error` (2/3) | §4 — `on_error`/`retry` join the value vocabulary |
| M13 improve surface (1/3) | §3 — improve excluded from task bodies |
| Minors | §3 (draft/deprecated), §5.7 (cwd), §8 (embedded/setup, collisions), §9 (bugs fixed, target_kind, goldens) |

Decisions 1–14 (rounds 1–6) stand as logged in v7 except where this
revision supersedes them with review evidence: call-site `params:` →
`with:` (M1); "expose the cascade" → "build the cascade" (C4); "duplicate
output" → two-schema design (C1); §10 non-goals → §9 cost inventory
(C2/C3). v7's remaining question (cascade sign-off) is superseded by this
section's cross-reference — the cascade shape survived review; its cost
didn't, and is now stated.

**Round 1 Sonnet panel (v8 → v9).** Four independent reviewers (coverage
audit, architecture, fresh adversarial, security+migration; full reports
`sonnet-r1-*.md` in the session scratchpad). Panel criticals, all applied:
the §5.6 grant key contradicted activation-policy's documented
no-new-trust-machinery decision → replaced by exact ceiling inheritance;
the v8 hash preimage omitted the persona snapshot → added; `with:` merge
on composition chains was undefined → §2.2; the tombstone hard-error was
unactionable on read-only bundles → warning carve-out. Panel majors, all
applied: task-path staging named (resolve → execute); executor sinks as
the adapter boundary; ShellUnitExecutor extracted from the task runner's
hardened path, not rebuilt; monotemporal composition rule; persona
resolver extraction scoped; merge classes stated (deep-merge preserved
for `extra_params`); shell invocation carries `timeoutMs`; shell-unit
crash/lease semantics; toolPolicy under capability notices; improve
exclusion given a named mechanism; migration crash-window ordering;
POSIX-pinned migrated quoting; launcher-aware shim. One panel claim was
verified false and rejected: "the tools: ceiling doesn't exist" — it does
(`show.ts:433-445`), inline in the show command, which is exactly why §4
scopes its extraction.

Open items: none blocking. Two implementation-time choices are delegated
to the implementer with defaults: the exact capability-declaration shape
per engine kind (default: a static field list per kind), and the
scheduler-id mapping for subdir task ids (default: `/` → `--` with
collision lint).