akm-cli 0.9.30 → 0.9.32

package/docs/architecture/specs/workflow-engine-buy-vs-build.md

@@ -0,0 +1,231 @@
+# Workflow Engine: Buy vs Build
+
+Status: DECISION RECORD — A/B investigation complete, recommendation stated
+Date: 2026-08-01
+Question: can a third-party library offload the maintenance burden of akm's
+hand-rolled workflow/task engine?
+Constraints (owner): no server; markdown authoring preserved (simple
+JSON/YAML acceptable only if markdown becomes cumbersome).
+Evidence: [the review corpus](./reviews/task-workflow-unification/README.md) — see its
+library-evaluation section
+Companion: [`task-workflow-format-unification.md`](./task-workflow-format-unification.md)
+(Design A's authoring/config layer, independently reviewed across five rounds)
+
+---
+
+## 0. Answer
+
+**Build — keep the engine.** Not for lack of a good library: OpenWorkflow is
+genuinely well-built and empirically durable. The blocker is that the thing
+being "offloaded" is mostly not there. Measured against the actual tree,
+**~7% of `src/workflows/exec` + `ir` is the generic durable-execution
+concern these libraries sell**; the other ~93% is akm's product and would
+survive adoption unchanged — while adoption *subtracts* capabilities the
+engine has today.
+
+Take the dependency **below** the engine instead, and cut scope **above**
+it (§7). That is where the maintenance burden actually is.
+
+## 1. Method
+
+Three independent Opus investigations, all forbidden from relying on
+training knowledge — every claim verified against live artifacts:
+
+| Investigation | Scope | Report |
+|---|---|---|
+| bunqueue | Full rubric + source read | [`library-eval-bunqueue.md`](./reviews/task-workflow-unification/library-eval-bunqueue.md) |
+| OpenWorkflow | Full rubric + **executed** (SIGKILL durability probe, schema-collision repro) | [`library-eval-openworkflow.md`](./reviews/task-workflow-unification/library-eval-openworkflow.md) |
+| Landscape | 25+ candidates against the hard constraints | [`library-eval-alternatives.md`](./reviews/task-workflow-unification/library-eval-alternatives.md) |
+
+Rubric derived from what the engine demonstrably does (established across
+the five review rounds behind the companion spec): embedded in a
+short-lived CLI process; crash-resume from `state.db`; completed-unit reuse
+keyed on **content hashes**; map fan-out with concurrency caps and
+reducers; minutes-long units with leases and stall recovery; judged gate
+loops; and the `brief`/`report` driver protocol.
+
+## 2. The decisive measurement
+
+`src/workflows/exec` + `src/workflows/ir` = **8,705 LOC**. Composition:
+
+| Component | LOC | Would a library replace it? |
+|---|---|---|
+| `brief.ts` + `report.ts` — external-driver protocol | **2,690 (31%)** | No — no library has an analogue |
+| `ir/` — schema, compile, freeze, plan hash, params | 1,635 | No — determinism/replay identity is akm's contract |
+| Dispatch, gates, worktrees, step-work | ~3,750 | No — agent/LLM dispatch, judged gates, redaction |
+| Journal/resume/lease/concurrency plumbing | **~630 (7%)** | **Yes — this is the addressable surface** |
+
+Rows sum to 8,705. The plumbing row is a *region* count, not a file-level
+partition — no whole-file split yields it (the only fully generic files are
+`scheduler.ts` 118 + `unit-writer.ts` 29). The defensible band is ~490–720,
+depending on whether the journal-row rehydration helpers and the gate
+resume seed count as plumbing or as product; the conclusion is unchanged
+anywhere in that band.
+
+For calibration, the generic concurrency concern is `src/core/concurrent.ts`
+(40) + `src/workflows/concurrency-policy.ts` (20) = **60 lines** — both of
+which sit *outside* the 8,705.
+
+A dependency that replaces 7% while adding an integration seam, a schema
+bridge, and a pre-1.0 upstream is not a burden transfer. It is a burden
+trade at unfavourable odds.
+
+## 3. Candidate results
+
+| | bunqueue | OpenWorkflow | Weft | Mastra | XState v5 |
+|---|---|---|---|---|---|
+| License | MIT | Apache-2.0 | MIT | Apache-2.0 | MIT |
+| Server-free | ⚠ single-process only | ✅ | ⚠ single-engine only | ✅ | ✅ |
+| SQLite durability + resume | ⚠ name-keyed | ✅ *(SIGKILL-verified)* | ✅ | ⚠ snapshot, no lease | ❌ |
+| Bounded fan-out + reducer | ❌ | ❌ *(issue #20, 9mo)* | ⚠ | ✅ | ⚠ |
+| Error-classified retry | ❌ | ❌ | ⚠ | ⚠ | ⚠ |
+| Per-step timeout / cancel | ⚠ 30s default | ❌ *(no AbortSignal)* | ⚠ | ✅ | ✅ |
+| Windows CI | ❌ | ❌ | ✅ target | ⚠ | ✅ |
+| Bus factor | 1 | 1 | 1 | team | team |
+| **% of exec+ir deletable** | **0–3%** | **8–12%** | ~6% | 10–15% | 4–6% |
+
+**Eliminated on the no-server constraint** (one line each in the landscape
+report): Temporal, Inngest, Trigger.dev, Hatchet, Windmill, n8n, Restate,
+Conductor, Camunda/Zeebe, Dapr, Azure Durable Functions, AWS durable
+execution, Convex, Cloudflare Workflows, Vercel Workflow DevKit, Upstash,
+Obelisk, HotMesh, Resonate. **On storage**: BullMQ (Redis), pg-boss/Absurd
+(Postgres), Agenda (Mongo), SideQuest (LGPL — license). **Not
+orchestrators**: bree, croner, better-queue, p-queue, `@deepkit/workflow`,
+liteflow. **Dead**: workflow-es (2022, `inversify@^4`).
+
+Three verifications that overturned plausible assumptions:
+
+- **DBOS Transact TS is still Postgres-only.** The tarball for
+  `@dbos-inc/dbos-sdk@4.25.14` (2026-07-30) contains zero SQLite files;
+  only `pg` and `postgresql://`. The June 2026 SQLite announcement was the
+  **Go** SDK.
+- **Effect's workflow/cluster packages fail on akm's exact topology** —
+  open upstream issues #6176/#6179: `SqliteError: database is locked` with
+  one runner plus multiple short-lived client processes on one store.
+- **LangGraph JS's SQLite checkpointer hard-depends on `better-sqlite3`**
+  (native addon), which would break `bun build --compile` single-binary
+  distribution across all five targets.
+
+## 4. The architectural finding (independent of maturity)
+
+Every candidate expresses a workflow as **code** — a function whose steps
+are memoized by *call position* as execution proceeds. akm expresses a
+workflow as **data**: markdown compiles to a frozen plan, and units are
+memoized by *content hash* (today `hashVersion 4`: frozen template bytes,
+item, declared inputs, params snapshot, dispatch snapshot, invocation,
+schema, env names, isolation, gate feedback — the companion spec proposes
+`hashVersion 5`, adding post-append/post-fill template bytes, the `uses:`
+target kind plus resolved-asset content hash, the persona snapshot, shell text/`shell`/`cwd`, and env *literal*
+values).
+
+Two consequences that no amount of library maturity fixes:
+
+1. **Adoption inverts the memoization key.** A code-DSL engine would have
+   to be handed a closure generated from akm's plan at runtime; its cache
+   then keys on call order, not content. Edit a step's prose and a
+   call-order cache happily reuses the completed result — precisely the
+   silent-replay-reuse bug the review rounds forced into `hashVersion 5`.
+   akm would keep its own hash layer *on top*, so the library's durability
+   is redundant rather than substitutive.
+2. **Gate loops are content-addressed retries.** A failed gate re-runs its
+   step *with judge feedback* — same call position, materially different
+   ask. akm handles this by folding `gateFeedback` into the hash preimage.
+   Under call-order memoization, loop 2 either wrongly reuses loop 1 or
+   wrongly re-runs everything.
+
+This is why bunqueue's reviewer landed on the same phrase independently:
+*code-DSL saga engine for one long-lived process* vs *frozen-data-plan
+executor for concurrent short-lived CLI runs*.
+
+## 5. Design A — build (the reviewed plan)
+
+The companion spec, as it stands after five review rounds: markdown tasks
+and workflows on one parser, `uses:`/`run:` targets, steps-are-tasks
+composition, the five-layer cascade, IR v4 with a shell invocation kind,
+`hashVersion 5`, env provenance split, ceiling-inherited shell execution,
+migration inside the journaled 0.9.0 cutover.
+
+Maintenance burden, honestly: akm owns ~630 LOC of journal/lease/resume
+plumbing plus the IR pipeline. The plumbing is the *stable* part — the
+tables, leases, and claim rows have not been the source of churn; format
+and dispatch semantics have.
+
+**Risk:** correctness of concurrency and replay is akm's problem. Mitigated
+by what already exists — the journal, `plan_hash`, deterministic replay
+tests, and the chaos/crash-window suites.
+
+## 6. Design B — buy (OpenWorkflow, at its strongest)
+
+Designed to win if it can. OpenWorkflow scores best of the candidates
+(embedded, zero runtime deps, empirically SIGKILL-durable, Apache-2.0).
+
+**Shape.** Markdown authoring is preserved exactly — the constraint is not
+the discriminator. `akm workflow run` compiles markdown → frozen plan
+→ *generates an OpenWorkflow definition* whose steps call akm dispatch.
+OpenWorkflow owns run/step journaling, resume, memoization, heartbeats.
+akm keeps the parser, IR/freeze, cascade, gates, dispatch, redaction.
+
+**What is deleted:** ~670 LOC (~8%, the low end of §3's 8–12% estimate) —
+the run/step journal writer, resume bookkeeping, lease renewal. That is
+~40 LOC above §2's ~630 central estimate and sits inside its ~490–720
+band: OpenWorkflow absorbs a little more than the narrowest reading of
+"plumbing," which is the most favourable assumption available to it.
+
+**What must be built to stand still** (each verified absent upstream):
+
+| Gap | Consequence |
+|---|---|
+| No concurrency cap (issue #20, open 9 months) | Re-implement bounded fan-out — the capability was the point |
+| No per-step timeout, **no `AbortSignal`** | Lose in-flight cancellation of agent spawns; a runaway unit cannot be preempted |
+| No error classification | Re-implement the 12-value failure taxonomy driving retry |
+| Schema collision — **reproduced**: `no such column: parent_step_attempt_id`, no table-prefix option | A **second DB file**, which breaks single-transaction atomicity across the gate spine |
+| 1,000 step-attempt cap | 10× below akm's 10,000-unit expansion limit |
+| `brief`/`report` (2,690 LOC) are built on the `workflow_run_units` row shape (`WorkflowRunUnitRow`, consumed field-by-field — `input_hash`, `phase`, `claim_holder`, `attempts`, `result_json`, `failure_reason` — through the `withWorkflowRunsRepo` seam, not raw SQL) | The protocol must be re-pointed at a foreign schema it does not control |
+
+**Net:** ~670 LOC deleted, ~400+ LOC of adapters and re-implementations
+added, atomicity and cancellation lost, a 10× capacity regression, and a
+bus-factor-1 pre-1.0 dependency placed in the execution path of an
+autonomous scheduled system. The landscape reviewer's phrasing for the
+comparable case applies: *net LOC plausibly negative*.
+
+## 7. Recommendation
+
+**Adopt Design A.** Then pursue the two moves that actually reduce burden —
+neither of which is a workflow engine:
+
+1. **Dependency below the engine, not instead of it.** Replace
+   `core/concurrent.ts` with `p-limit`/`p-queue` if desired. Small, real,
+   zero architectural risk. (Optional; 40 lines — the other 20 of §2's
+   calibration figure are `workflows/concurrency-policy.ts`, whose
+   cap-precedence policy survives the swap unchanged.)
+2. **Cut scope above the engine — the real lever.** `brief`/`report` is
+   **2,690 LOC, 31% of the engine**, and is Experimental/opt-in behind
+   `experimental.workflowEngine` while `run` is Stable and ungated. That
+   is the largest maintenance liability in the subsystem *and* the most
+   removable. Recommend an explicit keep/cut decision on the external
+   driver protocol as its own proposal — cutting it removes ~4× more code
+   than the best library adoption would, with no new dependency.
+
+**Worth stealing** (patterns, not packages): bunqueue's `pivot()` for plan
+changes mid-run, its non-terminal `compensation-stuck` state, and its
+seeded `simulatedClock()` for deterministic time tests; OpenWorkflow's
+SIGKILL-probe test methodology, which is a stronger durability check than
+akm's current crash-window suites.
+
+## 8. Reopen triggers
+
+Revisit if any becomes true:
+
+- DBOS Transact **TS** ships a SQLite system DB (Go/Python already have it).
+- Weft reaches 1.0 with documented **multi-process lease coordination** —
+  it is the only library designed for akm's runtime shape (Bun-native,
+  `bun:sqlite`, `windows-x64` compile target); today it explicitly refuses
+  concurrent engines against one store and is 8 weeks old.
+- OpenWorkflow lands concurrency caps (#20), `AbortSignal`, and a table
+  prefix — the three gaps that force the second DB file and the capability
+  regressions.
+- akm's own plumbing becomes a churn source. It has not been; format and
+  dispatch semantics have.
+
+The trigger is not "a library got popular." It is "a library removes more
+than it adds," measured the way §2 measures it.

package/docs/architecture/specs/workflow-format-unification.md

@@ -0,0 +1,437 @@
+# Workflow Format Unification
+
+Status: PROPOSAL v2 — owner decisions from review round 1 applied
+Date: 2026-07-30
+Supersedes: the dual markdown/YAML-program authoring surface (both unreleased)
+
+Owner decisions incorporated in v2: no interpolation syntax in prose (§2.3),
+gate rubrics live in the body (§2.4), steps have no titles — bare ids only
+(§2.2).
+
+## 0. Why now
+
+The workflow feature has never shipped (`experimental.workflowEngine` opt-in,
+0.9.0-rc). There are currently **two authoring formats** for one asset type,
+and the seams between them have started leaking into unrelated systems — the
+OKF provenance work (#730) tripped over workflow's closed frontmatter
+allowlist, which exists only because the markdown format grew its own bespoke
+validation instead of sharing the asset envelope every other type uses. This
+is the moment to unify: nothing on disk to migrate, no users to break.
+
+## 1. Review of the two current formats
+
+### 1.1 Format A — markdown workflow (`src/workflows/parser.ts`, ~500 lines)
+
+A bespoke prose grammar: one magic `# Workflow:` H1, magic `## Step:` H2s, a
+magic `Step ID:` body line, magic `### Instructions` / `### Completion
+Criteria` subsection names. Capabilities: **linear steps only** — no routing,
+fan-out, retry, timeout, engine/model selection, output schemas, or budgets.
+The compile path (`ir/compile.ts` `compileWorkflowPlan`) lowers every step to
+one fail-fast unit node with verbatim instructions.
+
+### 1.2 Format B — YAML program (`src/workflows/program/*`, ~1,300 lines)
+
+The full orchestration surface: `unit | map | route` steps, `${{ … }}`
+template expressions, retries keyed on the failure taxonomy, timeouts,
+per-unit engine/model/llm overrides, JSON-Schema-typed params and step
+outputs, gates with `max_loops`, budgets, worktree isolation.
+Instructions are embedded YAML block scalars.
+
+### 1.3 The divergences (each one is a standing cost)
+
+| Concern | Markdown | YAML program |
+|---|---|---|
+| Step id grammar | `[A-Za-z0-9][A-Za-z0-9._-]*` — dots allowed | `[A-Za-z_][A-Za-z0-9_-]*` — dots forbidden |
+| Params | name → description string, untyped | name → JSON Schema |
+| Templating | **none** — instructions verbatim | `${{ … }}` expressions, real substitution |
+| Gate | `### Completion Criteria` bullets; no `max_loops` | `gate:` with criteria/max_loops |
+| Capabilities | linear only | full orchestration |
+| Frontmatter validation | closed hand-maintained allowlist | closed key lists, JSON Schema published |
+| Title | required `# Workflow:` H1 prefix | `name:` field duplicating the filename |
+| Version | internal `schemaVersion 1` | `version: 2` (IR is v3) |
+
+Beyond the table, four structural costs:
+
+1. **The fake templating trap.** Every shipped example workflow
+   (`scripts/akm-eval/example-stash/workflows/*.md`) uses `{{ repo }}`-style
+   moustaches that **the engine never substitutes** — markdown instructions
+   compile `templating: "verbatim"`. The YAML format substitutes `${{ … }}`
+   for real. Two syntaxes; one is decorative and exists only as a convention
+   the executing agent is hoped to honor.
+2. **Content sniffing everywhere.** Two structural probes
+   (`looksLikeWorkflow`, `looksLikeWorkflowProgram`) consulted by the indexer
+   matchers, the workflow adapter (`recognize()` returns `"markdown" |
+   "yaml-program"`), the asset loader (extension dispatch + probe), and the
+   proposal validator (which sniffs *content* when no path is available).
+   `canonicalizeWorkflowName` collapses `foo.md` / `foo.yaml` / `foo.yml` to
+   one identity, so the two formats can silently collide on one ref.
+3. **The closed-allowlist special case.** Workflow markdown is the only AKM
+   type validating frontmatter against a closed hand-maintained key set. It
+   is why #730's provenance stamping needed a re-validation fallback in the
+   promotion path, why the allowlist had to learn `generated`/`verified`/
+   `provenance` by name, and why its error message is now stale
+   (`validator.ts:94` still enumerates the pre-#730 keys). Every future
+   machine-stamped key repeats this.
+4. **Double everything.** Two parsers, two templates, two doc sections, two
+   test suites, two JSON representations feeding one `WorkflowPlanDraft`.
+   ~1,800 lines of format code for one asset type.
+
+### 1.4 What is genuinely good and must survive
+
+- **The IR and engine.** Both frontends compile to one `WorkflowPlanDraft` →
+  frozen IR v3. Deterministic replay, journaled units, leases, brief/report —
+  none of that is format-coupled. This proposal changes **frontends only**.
+- **The closed reference grammar** (`program/expressions.ts`) — though in v2
+  of this proposal it *shrinks* from a template language to a bare reference
+  string format (§2.3).
+- **The program vocabulary** (unit/map/route, gate control, retry taxonomy,
+  budgets, defaults): well-designed, schema-validated, kept nearly verbatim.
+- **Markdown prose as the instruction medium.** The example workflows prove
+  the point: real instructions are long structured prose with code fences,
+  sub-headings, and lists. Markdown is their native medium.
+
+## 2. Design
+
+### 2.1 Principle
+
+> **One file. Machine surface in frontmatter, prose surface in the body,
+> joined by step id. Prose is never templated — data reaches units as
+> attached context, not string splices.**
+
+A workflow is an ordinary AKM markdown asset — same envelope as every other
+type, OKF-conformant frontmatter + body — whose frontmatter carries the
+entire orchestration graph and whose body carries per-step instructions and
+gate rubrics under plain headings.
+
+### 2.2 The format
+
+````markdown
+---
+type: workflow
+description: Drive a batch of GitHub issues to merged PRs.
+params:
+  repo:   { type: string, description: Target repository owner/name }
+  issues: { type: array,  description: Issue numbers to implement }
+defaults: { timeout: 10m, on_error: fail }
+budget: { max_units: 60 }
+steps:
+  - id: intake
+    output: { type: object }
+  - id: implement
+    map:
+      over: steps.intake.output.issues
+      concurrency: 3
+      unit: { isolation: worktree, retry: { max: 2, on: [timeout] } }
+    # `output` describes the REDUCER RESULT: the default `collect` reducer
+    # folds per-item unit results into an array.
+    output: { type: array }
+    # Retry lives here, not in a backward route: a failed gate re-runs this
+    # step with the judge's feedback, bounded by max_loops.
+    gate: { max_loops: 2 }
+  - id: verdict
+    inputs: [steps.implement.output]
+    output: { type: object }
+  - id: pick-outcome
+    route:
+      input: steps.verdict.output.status
+      when: [{ match: clean, step: announce }]
+      default: escalate       # both targets are LATER steps — routes are forward-only
+  - id: escalate
+    inputs: [steps.verdict.output]
+  - id: announce
+    inputs: [steps.implement.output]
+---
+
+# GitHub Issues Parallel Implementer
+
+Free preamble prose. Indexed for search, shown in `akm show`, never
+dispatched. Any headings except level-2 are fine here.
+
+## intake
+
+Everything under this heading, byte-exact, is the step's instructions —
+sub-headings, fences, lists, all of it. The run's params arrive as attached
+context; refer to them by name in prose ("clone the `repo` parameter's
+repository").
+
+## implement
+
+This section is the **map unit template**. The engine attaches each unit's
+item (and its index) as context; the prose says "the issue you were given."
+
+### gate
+
+The gate rubric — as long as it needs to be. Full prose, bullets, examples
+of passing and failing artifacts. The judge receives this whole section.
+
+- Every issue in the working set has a mergeable PR or a recorded blocker.
+- No PR was opened against a branch other than the declared base.
+
+## verdict
+
+Inspect the implementation results and report whether the batch is clean or
+needs escalation.
+
+## escalate
+
+Escalate blockers from the verdict, with the verdict artifact attached as
+context (declared via `inputs:` above).
+
+## announce
+
+Post the summary. The `implement` step's artifact is attached as context
+(declared via `inputs:` above).
+````
+
+**Frontmatter** (validated by one published JSON Schema):
+
+- The standard AKM asset envelope — `type`, `description`, `tags`,
+  `when_to_use`, `xrefs`, `updated`/`timestamp`, and the OKF v0.2 families
+  (`generated`, `verified`, `provenance`, `status`, `stale_after`) — via a
+  shared `$ref`'d envelope definition (§2.5).
+- The orchestration keys, adopted from program v2 with these changes:
+  - `version:` and `name:` **dropped**. Identity is the ref; the frozen plan
+    already versions execution semantics (IR v3); the authoring schema
+    evolves additively like every other asset type.
+  - `instructions:` keys **removed** — prose lives only in the body.
+  - `gate.criteria` **removed** — rubrics live in the body (§2.4). `gate:`
+    retains only the optional `max_loops` configuration.
+  - **No titles anywhere.** No step `title:` key, no display-title heading
+    suffix. A step is its id; the asset's human name is its `description`
+    and H1 like any other asset.
+  - New `inputs:` key on unit/map steps: the prior-step artifacts this step
+    consumes, as bare reference strings (§2.3). Replaces prose splicing as
+    the way a step sees upstream data, and gives replay hashing its exact
+    input set. Sub-paths are legal (`steps.x.output.issues`, not just
+    `steps.x.output`) so a step re-dispatches only when the slice it
+    consumes changes.
+  - A step with no `map:` and no `route:` **is** a unit step; bare
+    `- id: validate` is the complete minimal declaration. `unit:` remains as
+    the optional dispatch-override bag (engine/model/llm/timeout/retry/
+    on_error/env/isolation).
+  - One id grammar everywhere: `[A-Za-z_][A-Za-z0-9_-]*`.
+  - Keys stay snake_case (`on_error`, `max_loops`) — the existing AKM/OKF
+    frontmatter convention.
+
+**Body** (three rules):
+
+1. Every level-2 heading must be `## <step-id>` for a declared step, exactly.
+   (Fenced code blocks are skipped when scanning for headings.)
+2. A unit or map step **must** have a section (its instructions / per-item
+   template, byte-exact to the next H2 or EOF). A route step **may** have one
+   (documentation, plus a gate rubric if gated). Everything before the first
+   H2 is free preamble.
+3. Inside a step section, an optional `### gate` sub-heading starts the
+   step's gate rubric (running to the section end). It is the format's
+   **single reserved marker**. Omitted or empty rubric text skips validation;
+   a non-empty rubric enables optional validation. Frontmatter `gate:` without
+   a rubric is valid but inert.
+
+No `Step ID:` lines, no `# Workflow:` prefix, no reserved H3s beyond `gate`.
+
+### 2.3 No interpolation syntax — references and attached context
+
+v1 of this proposal kept `${{ … }}` templating in prose and added a `$${{`
+escape. The owner asked the right question — *why have the syntax at all?* —
+and the answer is that only the **engine** ever needed deterministic value
+resolution, and the engine only reads **whole-value frontmatter positions**:
+
+- `map.over` — the list to fan out over.
+- `route.input` — the value routing matches on.
+- `inputs:` — the artifacts a step consumes (new, replacing prose splicing).
+
+Whole-value positions need no delimiters. These become **bare reference
+strings** with the same closed grammar, shrunk from four roots to two:
+
+    params.<name>
+    steps.<id>.output( .<ident> | [<int>] )*
+
+`item` and `item_index` are **deleted from the language**: with no splicing
+there is nothing to substitute — the engine attaches each map unit's item and
+index as context alongside the prompt.
+
+**Prose is never templated.** Each dispatched unit receives, as structured
+attached context: the run params (params are run-scoped and documented
+non-secret), its item + index (map units), and the artifacts named by its
+step's `inputs:`. Instructions refer to these in plain language — which is
+exactly how the classic driver and all nine example workflows already
+functioned, since their moustaches were never substituted.
+
+What this buys:
+
+- The escape-syntax question evaporates — there are no delimiters in prose.
+- The P1 injection class dies at the root: data never enters the instruction
+  string at all, spliced or otherwise.
+- `program/expressions.ts` shrinks from a template parser (segments,
+  literals, offsets) to a small reference-string parser.
+- Bodies are pure markdown — cohesive with every other asset, no syntax an
+  OKF reader or a human editor has to know about.
+
+Determinism and replay identity are preserved: unit identity hashes the
+frozen template bytes + canonical item JSON + declared-input artifact hashes
++ the params snapshot — the same inputs the journal's replay machinery keys
+on today, minus the string splice. `inputs:` gives the hash its exact
+upstream set, so a step re-dispatches only when data it actually consumes
+changes (the precision splicing used to provide implicitly).
+
+The honest trade-off: prose can no longer compose a value mid-string with
+engine-guaranteed fidelity ("run `git checkout <item>`") — the executing
+agent performs that mapping from attached context. Every current executor is
+an agent/LLM engine, so this is the same trust the instructions already
+extend everywhere else. If a non-agent unit kind (raw shell/exec) is ever
+added, *that unit kind* reintroduces substitution as its own need — scoped
+there, not in prose.
+
+### 2.3a Routes are forward-only; gates are the retry mechanism
+
+Two invariants inherited unchanged from the program format, doubly enforced
+today (`program/parser.ts:459` and `ir/schema.ts:227`), and preserved here:
+
+- **A route target must be a LATER step**, and a step never routes to itself.
+  The plan stays a DAG, so termination is structural rather than a runtime
+  budget's job.
+- **Retry is a gate, not a backward edge.** A failed gate re-runs its own
+  step with the judge's feedback, bounded by `gate.max_loops`; a declared
+  `output:` schema that the artifact fails is the one error the gate loop may
+  retry through (`artifactSchemaFailure`). Anything wanting "go back and fix
+  it" expresses it as a gate on the step being fixed.
+
+A backward `default:` therefore does not mean "loop" — it is a lint error.
+
+### 2.3b `output:` describes the reducer result
+
+For a map step, `output:` validates the **promoted artifact**, i.e. what the
+reducer produced — not one unit's result. The default `collect` reducer folds
+per-item results into an **array**, so a collected map step's schema is
+`{ type: array }`. (`vote` folds to the winning value.) A unit step's
+`output:` describes that single unit's structured result.
+
+### 2.4 Gates: control in frontmatter, rubric in the body
+
+Owner decision: rubrics are often long — real rubric documents, not
+one-liners — and belong in the body. The split:
+
+- **Frontmatter `gate:`** optionally carries `max_loops`. It does not enable
+  validation by itself; without a non-empty body rubric it is inert.
+- **Body `### gate`** (inside the step's section) carries the rubric: full
+  prose, bullets, worked examples. The judge receives the whole section
+  byte-exact. Omitted or empty text skips validation. This replaces both the
+  markdown format's `### Completion Criteria` bullets and the program's
+  `gate.criteria` string list.
+
+### 2.5 Validation model — and the end of the allowlist special case
+
+One published JSON Schema (`schemas/akm-workflow.json`, repurposed) validates
+the entire frontmatter. Its top level `$ref`s a new **shared asset-envelope
+schema** — the common keys every AKM markdown type carries, including the
+machine-stamped OKF families. Consequences:
+
+- Workflow stops being the only type with a bespoke closed key set; "closed"
+  becomes `additionalProperties: false` over `envelope ∪ workflow-keys`,
+  defined in one place.
+- A future machine-stamped key is added to the envelope definition **once**,
+  and every schema-validated type inherits it — the #730 fallback dance and
+  the stale hand-written key-list message become structurally impossible.
+  The promotion-path re-validation backstop is deleted.
+- Editors get frontmatter completion/validation via the published schema
+  (yaml-language-server association) — tooling no bespoke markdown grammar
+  can offer.
+
+Semantic passes keep their existing implementations from the program parser,
+retargeted at frontmatter: duplicate ids, route targets exist / are
+forward-only / are unique, reference strings resolve to earlier steps,
+timeout format, retry-reason taxonomy, resource limits. Body checks are the
+three rules of §2.2.
+
+Recognition simplifies to: frontmatter `type: workflow`, or residence under
+`workflows/` — no content sniffing. `WORKFLOW_EXTENSIONS` shrinks to `.md`.
+
+### 2.6 OKF cohesion
+
+The unified asset **is** an OKF-shaped document: frontmatter + markdown
+body, no inline syntax. Provenance stamping applies with zero
+special-casing. A third-party OKF reader sees a normal document — prose
+overview, sections per step — degrading gracefully to readable procedure
+documentation. `status: draft` / `stale_after` become meaningful on
+workflows for free (e.g. a future rule that draft workflows refuse `run` —
+noted, not proposed here).
+
+## 3. What gets deleted
+
+- `src/workflows/parser.ts`'s grammar: `# Workflow:` / `## Step:` /
+  `Step ID:` / reserved-H3 subsections (frontmatter/toc plumbing is reused
+  by the new body binder).
+- `looksLikeWorkflow` / `looksLikeWorkflowProgram` sniffing and the
+  `"markdown" | "yaml-program"` mode split in the adapter, matchers, loader,
+  and proposal validator.
+- The YAML program as a distinct on-disk format; its field validation
+  survives as the frontmatter semantic passes.
+- **The template expression language**: `${{ … }}` delimiters, segment
+  parsing, `item`/`item_index` roots, and the escape question — replaced by
+  bare reference strings in three frontmatter positions plus context
+  attachment.
+- The workflow-only closed frontmatter allowlist and its hand-maintained
+  error string, replaced by the schema.
+- The #730 promotion-path re-validation fallback.
+- Step titles in all forms; the `name:` and `version:` keys.
+- One of the two authoring templates, one of the two doc sections, the
+  extension-collapse logic beyond `.md`, `isWorkflowProgramPath`.
+
+Net: two formats' worth of parsing/dispatch (~1,800 lines) replaced by one
+frontmatter schema + semantic passes + a three-rule body binder, with the
+IR, engine, and journal reused unchanged — and the template language itself
+reduced to a reference-string parser.
+
+## 4. Blast radius (all unreleased surfaces)
+
+- **Engine seam (the one non-frontend change):** unit dispatch gains context
+  attachment (params / item / declared inputs) and unit-identity hashing
+  keys on (template, item, input hashes, params) instead of instantiated
+  strings. Journal shape is already compatible; freeze pins the plan either
+  way.
+- **Templates**: both authoring templates → one.
+- **Examples**: 9 example-bundle workflows rewritten; their fake moustaches
+  become plain prose references to attached context — which is how they
+  already behaved in practice.
+- **Fixtures/goldens**: `format-family-goldens/`, `all-types` fixtures,
+  parser/program suites (program-parser tests largely port).
+- **Docs**: `docs/reference/workflows.md` collapses its two format sections;
+  the expression-language section shrinks to the reference grammar.
+- **Index cache**: `workflow_documents` re-derives on reindex (unreleased).
+- **CLI**: `akm workflow create` emits the unified template; `create
+  <name>.yaml` dies.
+
+## 5. Decision log and remaining questions
+
+Resolved by owner (review round 1):
+
+1. ~~Escape syntax~~ — **moot**: no interpolation in prose at all (§2.3).
+2. ~~Gate criteria location~~ — **body**, under the single reserved
+   `### gate` marker; control fields stay in frontmatter (§2.4).
+3. ~~Step titles~~ — **none**; a step is its id.
+4. ~~Heading form~~ — **bare `## <id>`**.
+
+Resolved by owner (review round 2):
+
+5. **`inputs:` accepts sub-paths.** `steps.x.output` and
+   `steps.x.output.issues` are both legal — the reference grammar already
+   parses the path form, and a narrower declared input means a narrower
+   replay hash, so a step re-dispatches only when the slice it actually
+   consumes changes.
+6. **All run params attach to every unit.** No per-step params declaration.
+   Params are run-scoped and documented non-secret (`docs/reference/
+   workflows.md`, "Params are not secret"); secrets travel as `env:` refs,
+   which remain per-unit. This keeps the attachment model uniform: every
+   unit receives params, its item + index if it is a map unit, and the
+   artifacts its step's `inputs:` names.
+
+No open questions remain. This proposal is ready to implement.
+
+## 6. Non-goals
+
+- No engine, IR, freeze, journal, lease, or brief/report changes beyond the
+  dispatch-context seam noted in §4.
+- No new orchestration capabilities (no new step kinds, reducers, or
+  reference roots).
+- No change to task/env/script/secret formats; task remains a YAML type —
+  tasks are machine schedules, not prose procedures.