akm-cli 0.9.29 → 0.9.31

package/docs/architecture/decisions/0007-workflow-composition-bounds.md

@@ -0,0 +1,83 @@
+# 0007 — Recursive child-workflow composition bounds
+
+## Context
+
+P3a made a workflow step able to compose another workflow as a child — via
+a direct `uses: workflows/<ref>` step or a task-wrapped `uses: tasks/<ref>`
+step whose target is itself a workflow — and made that composition
+recursive: a child can itself compose a grandchild, bounded only by policy.
+Recursion without a bound is a corruption/DoS surface at both ends of the
+plan's lifecycle: an attacker-controlled or merely buggy source could
+either recurse arbitrarily deep at freeze time, or (once persisted) blow up
+the aggregate bytes a parent plan carries once every descendant's frozen
+plan is embedded inside it.
+
+## Decision
+
+Moved verbatim from `src/workflows/resource-limits.ts`'s composition-bounds
+section:
+
+> Enforced ONCE, at freeze, before publication, in
+> `src/workflows/freeze/targets/child-workflow.ts` — the ONE resolver both
+> the direct `uses: workflows/<ref>` form and the task-wrapped form route
+> through — and re-enforced as a corruption gate whenever a parent plan is
+> DECODED (`src/workflows/ir/schema-v4.ts`'s recursive
+> `decodeChildWorkflowTarget`).
+>
+> `WORKFLOW_MAX_COMPOSITION_DEPTH` (= 8): max workflow composition depth —
+> the root workflow plus this many descendant levels (root is depth 0, so 8
+> descendant levels freeze and a 9th fails). Deep enough that no legible
+> authored composition hits it (the per-workflow bounds — 256 steps, 64
+> engines, 10 000 map expansion — are the practical ceilings), shallow
+> enough that the worst case is bounded recursion during freeze and decode.
+>
+> The max AGGREGATE canonical-JSON bytes of every embedded child plan in
+> ONE root freeze (the sum across the whole composition tree, not per
+> child) is deliberately HALF of `WORKFLOW_MAX_PLAN_BYTES` rather than a
+> larger value layered on top of it: an embedded child plan lives INSIDE
+> its parent's own plan bytes, so a cap independent of (and comparable to)
+> the total plan cap would let composition alone exhaust it. Halving keeps
+> the parent's own content always able to claim at least half the budget,
+> and lets this actionable, freeze-time `COMPOSITION_INVALID` (which names
+> the offending child ref and the running total) fire before the terse,
+> unlocated decoder message a reviewer would otherwise have to debug.
+> Rejected alternative: raising `WORKFLOW_MAX_PLAN_BYTES` itself, which
+> would relax a corruption/DoS bound for every plan — including ones with
+> no children — to serve a bound only composition needs (A-N6).
+
+## Consequences
+
+- The bound is enforced TWICE by design, not once: at freeze (where a
+  violation gets an actionable `COMPOSITION_INVALID` naming the offending
+  ref) and again at decode (where it acts purely as a corruption gate for a
+  persisted plan that should already be valid). A future change that
+  removes the decode-time re-check on the theory that "freeze already
+  checked it" would remove the last line of defense against a corrupted or
+  hand-edited `plan_json` row.
+- `WORKFLOW_MAX_COMPOSITION_DEPTH` and the aggregate-bytes cap are both
+  named in `docs/plans/specs/p4-deletions-closeout.md` §0 as one of the
+  three numbers ("`WORKFLOW_MAX_*` limits, plan `irVersion` 5, `hashVersion`
+  6") that P4 is expressly forbidden from changing — a P4 commit that
+  touches either is a review-blocking violation, and the same discipline
+  should apply to any later phase unless a spec explicitly re-opens it.
+  **2026-08-27 update:** `hashVersion` itself moved on from that pinned
+  value after this ADR was written — P4's R-R15 advisory (a reference
+  binding's resolved value sitting outside the unit-input hash) was closed
+  by bumping `hashVersion` 5 → 7 to fold `taskInputs` into the preimage
+  (`src/workflows/exec/step-work.ts`, `.update("akm.workflow.unit\0v7\0")`,
+  `hashVersion: 7`); see ADR 0002's "Consequences" entry for the full
+  supersession. The composition-bounds discipline this entry describes
+  still applies to `WORKFLOW_MAX_COMPOSITION_DEPTH` and the aggregate-bytes
+  cap unchanged — only the `hashVersion` figure in the quoted §0 sentence is
+  now stale.
+- The half-of-plan-bytes ratio is a relationship, not an independent
+  constant — if `WORKFLOW_MAX_PLAN_BYTES` itself is ever revisited, the
+  composition cap should move with it rather than being independently
+  retuned, per the rejected-alternative reasoning above.
+
+## Provenance
+
+- Source: `src/workflows/resource-limits.ts`, the "Recursive child-workflow
+  composition bounds" section.
+- Spec: `docs/plans/specs/p3a-plan-v5-child-freeze.md` §4.5, A-N6.
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0008-task-binding-normalization.md

@@ -0,0 +1,88 @@
+# 0008 — Task input binding normalization and re-binding across a composition
+
+## Context
+
+P2b gave a task-composing workflow step a `with:` record that freezes into
+typed `TaskInputBinding[]` against the target's declared `inputs:`
+contract. P3a then made workflows composable — a task-wrapped step can
+target a child WORKFLOW rather than a plain task — which raises a second
+problem `freezeTaskInputBindings` alone does not solve: a v4 task's own
+already-classified bindings (literal or reference) need to be re-expressed
+against the CHILD workflow's declared `params:` contract, by name, without
+re-deriving each entry's classification from its value's shape a second
+time.
+
+## Decision
+
+Moved verbatim from `src/workflows/freeze/task-bindings.ts`'s module
+header:
+
+> The pure `with:` -> `TaskInputBinding[]` normalizer (spec
+> docs/plans/specs/p2b-input-bindings.md §3.2 A2, §3.3), plus the pure
+> re-binder a recursive composition needs on top of it (spec
+> docs/plans/specs/p3a-plan-v5-child-freeze.md A-N8).
+>
+> `freezeTaskInputBindings` classifies a genuinely AUTHORED `with:` record
+> against a contract; `src/workflows/freeze/targets/task.ts`'s
+> `taskDispatch` calls it with THIS step's own authored `with:` against the
+> composed task's own `InputContract`, never anything from an outer
+> composition (§3.5 — there is no merge across a composition chain).
+> `rebindTaskInputBindings` instead takes an ALREADY-classified
+> `TaskInputBinding[]` — a v4 task's own effective inputs — and re-binds it
+> by name against a DIFFERENT contract, trusting each entry's existing
+> `kind` rather than re-deriving it from the value's shape;
+> `src/workflows/freeze/targets/child-workflow.ts`'s `childWorkflowDispatch`
+> is its only caller, re-binding a task-wrapped composition's effective
+> inputs against the child workflow's declared `params:`.
+>
+> Everything decidable at FREEZE time is decided here: an unknown `with:`
+> key, a missing required-without-default input, a literal value failing
+> its declared schema, and a reference's syntax + "names an earlier step
+> that exists" / "names a declared workflow param" structural check. A
+> reference's *resolved* value is validated PRE-ATTEMPT instead
+> (`src/workflows/exec/step-work.ts`, §3.6) — this module never resolves
+> anything, so it needs no run params and no step outputs.
+>
+> Pure function: no IO, no config reads. Imports only
+> `src/execution/input-contract.ts`, `src/workflows/program/expressions.ts`,
+> and `src/core/errors.ts`.
+
+And from `rebindTaskInputBindings`'s own doc comment — the part explaining
+WHY re-binding cannot simply reuse `freezeTaskInputBindings`:
+
+> This exists because a `kind: "literal"` binding's VALUE can be an
+> arbitrary JSON value, including one shaped exactly like the `{from:
+> "<ref>"}` reference grammar (e.g. a declared default for an object-typed
+> input). Round-tripping such a binding back through a `with:`-shaped
+> record and re-running `freezeTaskInputBindings`'s value-shape-driven
+> classification (`normalizeOneEntry`) would silently reinterpret that
+> literal as a live reference binding — the composing task's OWN contract
+> already settled `kind` once; this function trusts that answer instead of
+> asking the value's shape again (code-review finding, docs/plans/specs/
+> p3a-plan-v5-child-freeze.md).
+
+## Consequences
+
+- `freezeTaskInputBindings` and `rebindTaskInputBindings` must never be
+  merged into one shape-sniffing function, even though they look similar —
+  doing so would reintroduce exactly the silent-reinterpretation bug the
+  code-review finding above caught: a literal value that happens to look
+  like `{from: "..."}` would flip from literal to reference on its second
+  pass through composition.
+- A reference binding's `from` target (an earlier step or declared param)
+  never changes across a re-bind — only which CONTRACT it validates against
+  changes. A future caller that tries to re-target a reference's `from`
+  during re-binding is outside this module's contract and needs new
+  reasoning, not an extension of `rebindTaskInputBindings`.
+- Both functions stay pure and IO-free by construction — a caller that
+  needs a resolved value (not just a structurally-validated binding) is
+  looking for `step-work.ts`'s pre-attempt resolution instead, not a change
+  to this module.
+
+## Provenance
+
+- Source: `src/workflows/freeze/task-bindings.ts`, module header and
+  `rebindTaskInputBindings`'s doc comment (code-review finding).
+- Spec: `docs/plans/specs/p2b-input-bindings.md` §3.2 A2, §3.3;
+  `docs/plans/specs/p3a-plan-v5-child-freeze.md` A-N8.
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0009-child-run-publication-column-parity.md

@@ -0,0 +1,80 @@
+# 0009 — Child-run publication's hand-duplicated INSERT column list
+
+## Context
+
+`WorkflowRunsRepository.insertRun` is the ordinary path that creates a
+top-level `workflow_runs` row: a 13-column `INSERT` built from
+`InsertRunInput`. P3a added `publishChildWorkflowRun`, the idempotent
+publication path a parent step uses to create (or, on a race, discover) a
+child run — `SELECT`-else-`INSERT` inside one `BEGIN IMMEDIATE` transaction,
+so two concurrent callers racing on the same `(parentRunId, invocationKey)`
+serialize on SQLite's write lock instead of double-inserting. Its own
+`INSERT` is NOT a call to `insertRun` — it is a second, hand-written
+16-column `INSERT` (the same 13 columns plus `parent_run_id`,
+`parent_unit_id`, `invocation_key`) inside the same prepared statement as
+the idempotency check.
+
+This is not an oversight. P3a's review log (R11) considered sharing one
+`INSERT` builder between the two paths and explicitly declined to guess at
+the right shape for it with the caller (`publishChildWorkflowRun`) barely a
+commit old — a signature refactor made in haste, before the shape had
+proven itself in use, was judged a worse bet than a documented duplication.
+
+## Decision
+
+**Keep the duplication as an explicit, cross-referenced invariant rather
+than refactoring it.** `insertRun`'s 13-column list and
+`publishChildWorkflowRun`'s first 13 columns must stay byte-identical by
+hand — each site carries a one-line comment naming the other and pointing
+here. This was re-affirmed rather than fixed during the P4 close-out
+(`docs/plans/specs/p4-deletions-closeout.md` §8, row R-R3): "A signature
+refactor now, with P3b's caller one commit old, is exactly the guess R11
+declined to make."
+
+The two INSERTs are NOT candidates for a trivial "extract the shared 13
+columns" refactor either, despite looking like one: they run inside
+different transaction shapes (`insertRun` runs standalone or inside
+whatever transaction its caller already holds; `publishChildWorkflowRun`
+runs inside its own `immediateTransaction`, specifically `BEGIN IMMEDIATE`
+so the idempotency check and the insert are atomic against a racing
+publisher) and `publishChildWorkflowRun`'s version is followed by
+`insertSteps`, a `plan_json`/`plan_hash`/`plan_ir_version` update, and an
+idempotent `workflow_started` event insert — all inside the SAME
+transaction, none of which `insertRun`'s callers do at the same call site.
+A shared builder would need to either accept both shapes as parameters
+(defeating the point of extraction) or leave the transaction/follow-up
+choreography to the caller anyway (in which case the "shared" part is only
+the column list, which is exactly what the hand-duplication already is).
+
+## Consequences
+
+- Any future change to `workflow_runs`'s schema that adds or removes a
+  column BOTH paths write must update both `INSERT`s in the same commit.
+  The two comments (at `insertRun` and at `publishChildWorkflowRun`'s
+  `INSERT`) exist specifically so a reviewer checking one site is pointed at
+  the other.
+- A drift between the two column lists is a silent correctness bug, not a
+  compile error — SQLite's parameter binding is positional, so a column
+  added to `insertRun` but not to `publishChildWorkflowRun` (or reordered in
+  one but not the other) would silently bind the wrong value to the wrong
+  column rather than failing loudly. This is precisely why the invariant
+  comment exists as a standing reminder rather than being left implicit.
+- A future refactor attempt should re-read R11 and this record before
+  concluding the duplication is accidental — it is a deliberate,
+  re-affirmed choice made twice (P3a, then P4), not an oversight waiting to
+  be cleaned up.
+
+## Provenance
+
+- Sites: `src/storage/repositories/workflow-runs-repository.ts` —
+  `WorkflowRunsRepository.insertRun` and
+  `WorkflowRunsRepository.publishChildWorkflowRun`.
+- Source: P3a Review log, finding R11 (the original "should these share a
+  builder?" question, declined).
+- Disposition: `docs/plans/specs/p4-deletions-closeout.md` §8, row R-R3
+  ("RESOLVED AS AN INVARIANT, not a refactor").
+- Extracted: P4, 2026-08-27. Unlike ADRs 0001–0005/0007–0008, this record is
+  new content written for the close-out, not a moved essay — there was no
+  pre-existing long comment block to extract; R11's finding lived only in a
+  review log until this record and the two source comments it backs were
+  added.

package/docs/architecture/decisions/0010-driver-protocol-cut.md

@@ -0,0 +1,36 @@
+# 0010 — The external driver protocol was cut
+
+## Context
+
+An earlier design considered an external driver protocol for workflow
+execution: `workflow brief` / `workflow report` verbs plus a `--settle`
+flag, giving an outside process a way to drive a run step-by-step instead
+of `akm`'s own native engine executing it end to end.
+
+## Decision
+
+Cut. AKM's native engine (`src/workflows/exec/native-executor.ts`) is the
+only executor; no external driver protocol was implemented or shipped in
+any 0.9.x release.
+
+This ADR is a stub, not the normative record. The full decision — including
+the option considered, the evidence gathered, and the verification greps
+proving nothing in `src/` implements the cut surface — lives in
+`docs/architecture/specs/driver-protocol-keep-or-cut.md`, which this stub
+exists only to make discoverable from the ADR index (this refactor's design
+history otherwise lives entirely under `docs/architecture/decisions/`).
+
+## Consequences
+
+See `docs/architecture/specs/driver-protocol-keep-or-cut.md` for the full
+consequence analysis. In short: `workflow_run_units` has had exactly one
+consumer (the native executor) throughout, with no dual-executor
+compatibility surface to maintain.
+
+## Provenance
+
+- Normative record: `docs/architecture/specs/driver-protocol-keep-or-cut.md`.
+- Cross-referenced from: `docs/plans/0.9.2-architecture-deletion-audit.md`'s
+  "Deleted architecture" table; `docs/architecture/specs/
+  workflow-engine-buy-vs-build.md` §7 (Recommendation).
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0011-engine-run-loop-invariants.md

@@ -0,0 +1,125 @@
+# 0011 — The engine run loop's invariants: gate spine, frozen plan, run lease, process lifecycle
+
+## Context
+
+`src/workflows/exec/run-workflow.ts` is `akm workflow run`'s
+start/resume/execute path — the single execution surface that walks a
+frozen plan and dispatches every unit. It sits one layer above
+`native-executor.ts` (unit dispatch, ADR 0001) and `step-work.ts` (pure
+step semantics, ADR 0002): this module is where the ENGINE LOOP's own
+invariants live — never bypassing the gate spine, reading the plan from
+its frozen row rather than live source, holding a run lease, running
+bounded gate loops, and not leaking OS handles on exit.
+
+## Decision
+
+Moved verbatim from `run-workflow.ts`'s module header:
+
+> Engine-driven workflow execution — the `akm workflow run`
+> start/resume/execute path, and the single execution surface for a run:
+> akm walks the frozen plan and dispatches every unit itself.
+>
+> **Invariant (plan §*Never bypass the gate spine*):** every step advances
+> through `completeWorkflowStep`, never by writing step rows directly, so
+> the summary-validation gate and run-state derivation stay authoritative.
+> A gate rejection (`SummaryValidationFailure`) STOPS the engine and
+> surfaces the corrective feedback — a gate is a gate, even for the engine.
+>
+> **Artifact-judging gates (redesign addendum, R2):** when a step declares
+> completion criteria, the engine hands the gate a summary BUILT FROM the
+> step's promoted artifact (canonical JSON, clipped, prefixed with a
+> one-line unit count — `buildArtifactSummary`) instead of the machine-prose
+> execution summary, so the judge evaluates real results. Each
+> engine-driven judge call is journaled as a unit row (`node_id
+> "<stepId>.gate"`, `unit_id "<stepId>.gate:l<loop>"`, runner "llm",
+> `result_json` = the verdict) through the writer queue — it is an LLM call
+> like any other. Human approvals are never cached: a blocked gate stays
+> blocked.
+>
+> **Bounded gate loops (`gate.max_loops`, addendum R2):** a rejection on a
+> step with `maxLoops > 1` re-executes the step subgraph with the judge's
+> feedback + `missing[]` threaded into every unit prompt (`gateFeedback` on
+> `StepExecutionContext`) — the feedback changes each unit's input hash, so
+> the loop re-dispatches naturally instead of reusing the rejected rows.
+> After `maxLoops` rejections the engine stops with the gate feedback,
+> exactly like the one-shot case. A typed-artifact schema mismatch feeds
+> the same loop (the validation errors are the feedback; no judge ran, so
+> no gate unit is journaled for that attempt) — only the FINAL loop's
+> mismatch fails the run. `effectiveGateMaxLoops` caps a step to a SINGLE
+> loop whenever its subgraph's frozen target is anything other than a
+> `command` (agent/SDK/LLM-runner) target — which covers both an `exec`
+> unit (a `shell`/`script` target) and a composed `child-workflow` step,
+> for two DIFFERENT reasons that both land on the same cap. An exec unit's
+> argv is frozen and never interpolated, so it cannot read the feedback: a
+> second loop would only re-run the identical side effect. A child-workflow
+> unit has no prompt to thread feedback into either — its only frozen input
+> is the composing step's resolved `with:` bindings, published once to the
+> child run — so a second loop would re-publish the same child with
+> byte-identical bindings rather than asking it anything new. Only a
+> `command`-targeted (engine) step, whose feedback is threaded into its
+> prompt, can loop past one; an authored `gate.max_loops` on an engine step
+> is untouched.
+>
+> **Frozen plan (redesign addendum, R1):** the plan graph is read from the
+> run row (`plan_json`, persisted by `startWorkflowRun` under migration
+> 006) with a `plan_hash` integrity check — the workflow asset file is
+> NEVER re-read for an in-flight run, so a mid-run asset edit cannot change
+> behavior. Durable-row resume: re-invoking a partially-executed run
+> re-dispatches only work that never completed.
+>
+> **Run lease (redesign addendum, R2):** exactly one engine invocation
+> drives a run at a time. The lease (random holder id + 90s expiry on the
+> run row) is acquired before any dispatch, renewed between steps, and
+> released in a `finally` unless a failed run retains it as forensic
+> state; a second `workflow run` on a live-leased run refuses up front, and
+> an expired lease is claimable (crash recovery). While the lease is live,
+> any competing spine advance is refused — the engine owns the run while
+> driving (enforced inside `completeWorkflowStep`).
+>
+> **Process-lifecycle contract (owner finding 4 — no leaked handles):** the
+> SDK dispatch path caches `opencode serve` CHILD PROCESSES in a per-env
+> registry for reuse across units. Each live child is an OS handle that
+> keeps Bun's event loop open; the registry's own teardown is wired only to
+> `process.once('exit')`, which never fires while a child holds the loop
+> open. That deadlock hangs a one-shot CLI (`akm workflow run` has no
+> `process.exit` on success — it relies on the loop draining). The engine
+> therefore DRAINS the dispatch registry (`disposeDispatchResources`) in its
+> run `finally`, on EVERY exit path, so the process exits cleanly the
+> moment the run resolves. The drain is synchronous, idempotent, and a
+> no-op when no SDK server started.
+
+## Consequences
+
+- Any future code path that advances a step must go through
+  `completeWorkflowStep` — a direct write to a step row bypasses both the
+  summary-validation gate and run-state derivation, silently breaking the
+  gate-is-a-gate guarantee even if the write itself succeeds.
+- Because the frozen plan is read from `plan_json` (never the live asset),
+  editing a workflow's Markdown/YAML source after a run has started has
+  **no effect** on that run — this is the same "child source edits cannot
+  alter an in-flight parent run" property child workflows rely on (P3a),
+  applied to the root run itself.
+- A new dispatch backend that spawns a long-lived child process (the way
+  the SDK harness does) must register its teardown with the SAME drain the
+  engine already calls in its run `finally` — relying on `process.exit` or
+  `process.once('exit')` alone reintroduces the exact hang class "owner
+  finding 4" fixed.
+- The run lease is the ONLY exclusivity mechanism for driving a run;
+  anything that touches a run's step spine outside `completeWorkflowStep`
+  while a lease might be live needs to reason about this contract
+  explicitly rather than assuming single-writer access.
+
+## Provenance
+
+- Source: `src/workflows/exec/run-workflow.ts`, module header.
+- Review markers: "redesign addendum" R1/R2, "owner finding 4".
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.
+  Added as an 11th record, past the ten-item minimum set the spec named —
+  `run-workflow.ts` carries "(comment only)" on Lane B's file list (§6) but
+  was not cited by name in §4.2's minimum-ADR-set table; this essay does not
+  fit cleanly inside any of the other ten without either duplicating engine-
+  loop-specific reasoning into a step- or unit-scoped record or dropping it,
+  both of which the spec's no-reasoning-deleted rule forecloses. §4.2
+  explicitly permits the implementer to merge related essays and record the
+  final set in the commit body — this is the converse case, an essay that
+  does not merge cleanly, so it gets its own number instead.

package/docs/architecture/decisions/README.md

@@ -0,0 +1,62 @@
+# Architecture decision records
+
+This directory holds the design history that used to live as long comment
+blocks inside the modules the 0.9.2 task/workflow refactor touched. Brief
+§9 named the problem directly: *"Historical essays inside large modules |
+Keep invariant comments locally; move design history to ADRs | Reduce
+cognitive load without deleting important reasoning."* These records are
+that move.
+
+## Format
+
+- One file per decision: `NNNN-kebab-title.md`, numbered in the order the
+  decision was extracted, not the order the underlying work happened.
+- No front matter.
+- Four sections, in this order:
+  - **Context** — the problem the module was solving and the constraints in
+    play when the decision was made.
+  - **Decision** — what was decided, including the essay's own reasoning
+    verbatim where it was already written as reasoning. Nothing here is
+    deleted or "cleaned up" on the move — see the binding rule below.
+  - **Consequences** — what the decision implies for callers, for future
+    changes, and (where the essay named one) for alternatives that were
+    considered and rejected.
+  - **Provenance** — the source file(s) and, where the essay named one, the
+    spec section or review round the reasoning came from, plus the date and
+    phase this record was extracted.
+
+## What moves here and what stays in the code
+
+Per the brief's own framing (§15, quoted in
+`docs/plans/specs/p4-deletions-closeout.md` §1.5): a code comment that
+explains *why mutation is delayed, why a hash includes a field, why a
+transaction boundary exists, why a source is revalidated, why a child
+invocation is idempotent* — a short, load-bearing invariant a maintainer
+needs sitting right next to the code — **stays in the code**. A comment
+block that is historical narrative — peer-review findings, an earlier
+draft, a superseded alternative, a phase-by-phase chronology of how a
+design arrived where it is — moves here instead, replaced in the source by
+a one-line invariant summary plus a relative link back to the ADR that
+carries the full reasoning.
+
+**Binding rule carried from the spec:** no ADR may delete reasoning. An
+essay's text moves; it is not summarized away. Where an essay describes
+behavior a later phase deleted, the ADR records the behavior **and** its
+removal date, rather than being quietly rewritten as if the behavior never
+existed.
+
+## Index
+
+| ADR | Title | Source essay | Extracted |
+|---|---|---|---|
+| [0001](./0001-no-interpolation-attached-structured-context.md) | No interpolation — data reaches units as attached structured context | `src/workflows/exec/native-executor.ts` module header (data flow / reference scope / peer-review-R1 narrative) | P4 |
+| [0002](./0002-unit-reuse-and-input-hash-scope.md) | Unit reuse and the input-hash scope | `src/workflows/exec/step-work.ts` (module purity contract; `computeUnitInputHash`'s doc comment) | P4 |
+| [0003](./0003-child-env-allowlist-and-provenance.md) | The exec unit's child-environment allowlist and provenance | `src/workflows/exec/exec-unit.ts` (module header; the default-allowlist rationale; capture/overflow semantics; `childEnv`'s layering) | P4 |
+| [0004](./0004-task-input-contract-and-flag-coercion.md) | The shared input contract, generalized from workflow params | `src/execution/input-contract.ts` module header | P4 |
+| [0005](./0005-task-result-vocabulary-and-legacy-read-mapping.md) | The D8 result-vocabulary re-code and its legacy read mapping | `src/tasks/run/task-result.ts` + `src/tasks/run/task-history.ts` headers (the mapping's own one-line invariant stays in `task-history.ts`) | P4 |
+| [0006](./0006-task-source-version-routing.md) | Task source version routing, from three generations to one | `src/tasks/source/parse-task-source.ts` routing-table header | P4 |
+| [0007](./0007-workflow-composition-bounds.md) | Recursive child-workflow composition bounds | `src/workflows/resource-limits.ts` (the composition-depth and aggregate-plan-bytes section) | P4 |
+| [0008](./0008-task-binding-normalization.md) | Task input binding normalization and re-binding across a composition | `src/workflows/freeze/task-bindings.ts` (module header; `rebindTaskInputBindings`'s doc comment) | P4 |
+| [0009](./0009-child-run-publication-column-parity.md) | Child-run publication's hand-duplicated INSERT column list | New content — the R11/R-R3 disposition (`docs/plans/specs/p4-deletions-closeout.md` §8), not a moved essay | P4 |
+| [0010](./0010-driver-protocol-cut.md) | The external driver protocol (`workflow brief`/`workflow report`/`--settle`) was cut | Stub pointing at `docs/architecture/specs/driver-protocol-keep-or-cut.md`, which stays the normative decision record | P4 |
+| [0011](./0011-engine-run-loop-invariants.md) | The engine run loop's invariants: gate spine, frozen plan, run lease, process lifecycle | `src/workflows/exec/run-workflow.ts` module header | P4 |