akm-cli 0.9.29 → 0.9.31

package/docs/architecture/decisions/0002-unit-reuse-and-input-hash-scope.md

@@ -0,0 +1,142 @@
+# 0002 — Unit reuse and the input-hash scope
+
+## Context
+
+A resumed workflow run must recompute the same units the original run
+dispatched, byte-for-byte, so that journaled rows can stand in for a live
+dispatch instead of re-executing. That guarantee depends on two things
+staying strictly separated: which computations are PURE functions of
+`(frozen plan, params, journaled results)`, and exactly which fields feed
+the hash that decides whether a journaled unit is still valid to reuse.
+`src/workflows/exec/step-work.ts` is the one module both the fresh-execution
+path (`native-executor.ts`) and the resume/replay path share for these
+decisions, specifically so the two paths cannot drift apart.
+
+## Decision
+
+### The module's purity contract
+
+Moved verbatim from `step-work.ts`'s module header:
+
+> Shared step semantics — the ONE implementation of a step's orchestration
+> decisions, consumed by the engine loop (`run-workflow.ts` +
+> `native-executor.ts`) on both the fresh-execution and the resume/replay
+> path. The cardinal rule here is *no duplicated semantics*: work-list
+> computation, prompt assembly, reducer/artifact promotion, output-schema
+> validation, artifact-judged gate summaries, gate-feedback recovery, and
+> route evaluation live here so a first run and a resumed run of the same
+> frozen plan produce byte-identical unit graphs.
+>
+> **What is PURE here.** `computeStepWorkList` — given the frozen step plan
+> and a `WorkListInput` (params, prior step outputs, gate-loop number + its
+> recovered feedback) — is a pure function: same inputs ⇒ same unit ids,
+> input hashes, and fully-resolved prompts. It takes NO clock, NO IO, and NO
+> journal (journal-derived state, i.e. the recovered gate feedback, is
+> passed in). This is the load-bearing guarantee that a resumed run
+> recomputes exactly the units the original run dispatched, so journaled
+> rows can be reused instead of re-executed. So are the reducer/artifact
+> helpers (`buildEvidence`, `projectStepOutput`, `validateStepArtifact`,
+> `buildArtifactSummary`), the gate-feedback recovery (`recoverGateFeedback`
+> / `activeGateLoop`), and route evaluation (`evaluateRoute` and its
+> bookkeeping).
+>
+> **What does IO here.** The gate-evaluation journaling
+> (`journalGateEvaluationStart` / `journalGateEvaluationFinish`) writes
+> `workflow_run_units` rows through the serialized writer queue — an
+> engine-driven judge call is an LLM call and is journaled like a unit. It
+> lives here (not in the engine loop) so every caller journals gate
+> evaluations through the identical writer.
+>
+> This module NEVER dispatches a unit and NEVER writes step rows: dispatch
+> is the executor's job (`native-executor.ts`), advancing the gated spine is
+> the engine loop's job (`run-workflow.ts` via `completeWorkflowStep`).
+
+### The input-hash preimage
+
+Moved verbatim from `computeUnitInputHash`'s doc comment:
+
+> The canonical dispatch-input envelope (reviewer finding #1). Every field
+> here is a PLAN-FROZEN input that changes what the backend is actually
+> asked to do, so a completed unit is reused ONLY when all of them match; a
+> change to any of them re-dispatches. `canonicalJsonString` sorts keys
+> recursively, so the preimage is order-independent, and this is the ONE
+> place a unit's inputHash is computed (every caller goes through
+> `computeStepWorkList`) — a hash that is byte-identical across a fresh run
+> and a resume is structural, not coincidental.
+>
+> Unit identity (workflow-format-unification, spec §2.3/§4) hashes the
+> FROZEN TEMPLATE BYTES (`template.instructions`, byte-exact, never an
+> instantiated/interpolated string) + the canonical item JSON + the
+> declared-input artifacts + the params snapshot — instead of a
+> resolved/spliced prompt string, since there is no more splicing.
+>
+> Included beyond the template/runner/model/schema baseline: resolved
+> timeoutMs, named environment bindings, and isolation — each reaches
+> dispatch and a changed one yields a materially different call. `env`
+> carries NAMES ONLY, never resolved values: hashing a resolved secret would
+> leak it into a durable hash oracle and would spuriously re-dispatch on
+> every secret rotation. `retry`/`onError` are DELIBERATELY excluded — they
+> govern failed-unit re-dispatch and step-level failure reduction, not a
+> COMPLETED unit's inputs/output, so a completed row stays valid across
+> policy changes.
+>
+> `gateFeedback` IS included (conditionally, so a no-feedback unit's
+> preimage is byte-identical to before): it is appended to the prompt by
+> `buildUnitPrompt`, so a gate loop's retry is materially a different ask
+> than the rejected attempt. Replay-safe: feedback is re-derived from the
+> journaled gate decision, so a resumed retry re-hashes identically.
+>
+> `taskInputs` IS included, on the same conditional terms (R-R15,
+> `hashVersion` 7): a reference binding's RESOLVED value reaches the unit's
+> prompt / `AKM_TASK_INPUTS` / `childParams`, so a changed upstream value is
+> a materially different ask even though the binding's authored shape inside
+> `frozenTarget` is unchanged. Hashing it makes a resume whose journaled
+> upstream output was altered fail loudly as replay divergence instead of
+> silently reusing the stale row. The key is absent for a unit whose target
+> carries no `inputBindings`, so a binding-free unit's preimage keeps the
+> shape it had — only the version fields moved.
+>
+> Command targets carry their frozen argv/script/cwd/timeout identity in the
+> same target slot used by agent, SDK, and direct-LLM work. The complete
+> current target is hashed once, so a completed unit is reused only for the
+> exact durable request that originally produced it.
+>
+> Ambient config is deliberately excluded because it is not consulted
+> during execution. The frozen target and named environment bindings are
+> the runtime identity boundary; only the values behind those names remain
+> live.
+
+## Consequences
+
+- Any new field added to a unit's dispatch plan must be triaged against
+  this scope explicitly: does it change what the backend is asked to do
+  (include it), is it a policy about failure handling rather than a
+  completed unit's inputs/output (exclude it, like `retry`/`onError`), or is
+  it a resolved secret value (exclude the value, include only the name)?
+  Getting this wrong either lets a materially different request reuse a
+  stale journaled row, or spuriously invalidates every journaled row on an
+  unrelated change.
+- `hashVersion` (currently **7**) is the version prefix mixed into this hash;
+  changing what this preimage covers requires bumping it. P4's R-R15 carried
+  advisory — a reference binding's RESOLVED value sitting outside this hash —
+  is exactly such a scope change, and it is now **resolved**: `taskInputs`
+  (the resolved values of a composed task's reference-kind `inputBindings`) is
+  a conditional preimage field, present only for a unit whose frozen target
+  carries `inputBindings`, and closing it came with the bump this rule
+  mandates. The 0.9.2 line's released tags (`v0.9.2-alpha.1`…`alpha.4`) all
+  carry 5, so the durable, user-visible step is 5 → 7. The "left unfixed
+  rather than folded in as a quiet scope change" note in
+  `docs/plans/specs/p4-deletions-closeout.md` §8 R-R15 (and p3b §3.6's "why
+  `hashVersion` stays 6") records the state BEFORE that bump and is
+  superseded by this entry.
+- Because the whole module is import-cycle-free with respect to dispatch
+  (it never dispatches, never writes step rows), the fresh-execution and
+  resume/replay paths cannot silently diverge by one of them bypassing this
+  module's decisions.
+
+## Provenance
+
+- Source: `src/workflows/exec/step-work.ts`, module header (the Purity
+  Contract) and `computeUnitInputHash`'s doc comment (reviewer finding #1).
+- Spec: workflow-format-unification, spec §2.3/§4.
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0003-child-env-allowlist-and-provenance.md

@@ -0,0 +1,189 @@
+# 0003 — The exec unit's child-environment allowlist and provenance
+
+## Context
+
+`src/workflows/exec/exec-unit.ts` is the one place a frozen workflow spawns
+a shell command as a unit. A spawned child inherits none of AKM's own
+process safety by default — no argv-injection protection, no environment
+isolation, no output bound — so every one of those has to be a deliberate
+design choice in this one module rather than an accident of whatever
+`child_process` defaults to.
+
+## Decision
+
+### The module's invariants
+
+Moved verbatim from `exec-unit.ts`'s module header:
+
+> The `exec` unit runner — the ONE place a frozen workflow spawns a shell
+> command as a unit. The invariants it exists to hold:
+>
+> - ARGV, NEVER A SHELL STRING. `IrExecSpec.command` is an argv ARRAY and
+>   the format has no shell-string spelling at all; the child is spawned
+>   directly, so `;`, `|`, `&&`, `$(…)`, backticks, `>` and `*` are inert
+>   literal argument BYTES. A workflow that wants a pipeline names the
+>   interpreter itself (`["bash", "-lc", "a | b"]`), visibly in frontmatter.
+> - NON-BLOCKING. Everything on this path is async. A synchronous call here
+>   blocks the event loop and with it every concurrently-scheduled unit,
+>   the run's lease heartbeat, and abort handling.
+> - NO LEAKED CHILDREN. `runManagedSubprocess` spawns DETACHED and runs a
+>   SIGTERM→SIGKILL ladder against the whole process group, so `--timeout`
+>   and Ctrl-C really do stop a running command and its descendants.
+> - CONTAINMENT. `exec.cwd` is relative and `..`-free by construction
+>   (parser and frozen-plan decoder), which is necessary but not sufficient:
+>   a subdirectory can be a symlink. The RESOLVED path is therefore
+>   re-checked against the RESOLVED base immediately before spawning.
+> - BOUNDED SPEND. A command is arbitrary code with no resource discipline
+>   of its own, so each resource it spends on akm's behalf has a ceiling in
+>   `workflows/resource-limits.ts`: wall clock (`DEFAULT_EXEC_TIMEOUT_MS` or
+>   the authored `timeout:`), retained output
+>   (`WORKFLOW_MAX_EXEC_OUTPUT_BYTES` per pipe) and the context environment
+>   (`execContextLimits`, checked BEFORE the spawn so an oversized artifact
+>   yields an actionable akm error, not a bare `E2BIG`).
+> - ALLOWLISTED ENVIRONMENT. The child does NOT inherit akm's environment:
+>   it starts EMPTY and receives exactly `EXEC_DEFAULT_ENV_PASSTHROUGH` plus
+>   the unit's `exec.passEnv`, then the resolved `env:` bindings, then the
+>   engine-authored `AKM_*` context. See `childEnv`.
+>
+> Secrets: `env` values reaching this module are already resolved from
+> `env:` bindings by NAME (`resolveEnvBinding`) — the plan never carries
+> inline secrets and the input hash only ever carries names. The caller
+> scrubs the outcome with `redactUnitOutcome` BEFORE anything is journaled,
+> which is why this module may return raw stdout/stderr diagnostics without
+> knowing anything about redaction.
+>
+> Layering: a LEAF. Node built-ins, `core/common` (for `isWithinAsync`, the
+> CONTAINMENT recheck above), `core/spawn-env`, `core/subprocess`,
+> `core/warn` and the import-free `workflows/resource-limits` (plus erased
+> types) only, so the executor can consume it without opening an import
+> cycle.
+
+### The default allowlist and why it is an allowlist
+
+Moved verbatim from `EXEC_DEFAULT_ENV_PASSTHROUGH`'s doc comment and
+`childEnv`'s doc comment:
+
+> The DEFAULT environment allowlist for an exec unit's child — the single
+> definition of the EXEC list (the docs describe it, the tests assert
+> against it, and `exec.passEnv` extends it per unit). The win32
+> process-creation names are not re-spelled here: they are spread from
+> `WIN32_SPAWN_ENV_FLOOR`, which owns them.
+>
+> The child starts from an EMPTY environment and receives only these names,
+> matching how an agent harness child is already built
+> (`profile.envPassthrough` → `collectAllowlistedEnv`) — and literally
+> extending the same `COMMON_SPAWN_ENV_PASSTHROUGH` baseline those profiles
+> start from, so the two child-spawn allowlists share one floor. Every
+> entry earns its place by being load-bearing for ordinary commands on some
+> supported platform: `PATH` (command resolution), `HOME` (the config/cache
+> root essentially every toolchain reads), `USER`/`LOGNAME` (process
+> identity for git/ssh), `SHELL` (tools that re-exec a login shell),
+> `LANG`/`LC_ALL`/`LC_CTYPE` (text encoding — without a locale a command
+> falls back to the C locale and mangles non-ASCII stdout, which IS this
+> unit's artifact), `TERM` (some CLIs abort or emit raw escape bytes with no
+> TERM), `TZ` (timestamps a command prints would otherwise silently switch
+> to the host default), `TMPDIR` (POSIX scratch space), the win32 spawn
+> floor plus `APPDATA`/`LOCALAPPDATA`/`ProgramData`/`ProgramFiles` (Windows
+> toolchain roots not on the floor itself), and `AKM_EVENT_SOURCE`
+> (provenance, never a secret: an exec unit that calls `akm` must record
+> machine traffic rather than user demand, exactly as the agent passthrough
+> list does — DRIFT-6).
+>
+> Deliberately ABSENT and reachable only through `exec.passEnv` / `env:`:
+> credentials of every kind, cloud/CI vars, and the proxy family
+> (`HTTP_PROXY` & friends) — proxy URLs routinely embed credentials, which
+> is why akm's redaction policy already treats URL-shaped passthrough
+> values as credential-bearing.
+>
+> The child's environment resolves in three layers with fixed precedence:
+> (1) the BASE — the default allowlist plus the unit's `exec.passEnv`
+> names; (2) the unit's resolved `env:` bindings; (3) the engine-authored
+> `AKM_*` context, LAST so a workflow-supplied binding can never shadow the
+> ids/item the engine is telling the command the truth about.
+>
+> **Why the default is an allowlist.** Not because it stops an attacker: a
+> command that runs at all can read the same credentials off disk that the
+> environment would have handed it, and a workflow source is executed code
+> either way (`docs/guides/run-workflows.md`, "workflow sources are
+> executed code"). The allowlist earns its place for three narrower, real
+> reasons: it bounds ACCIDENTAL exposure — the ambient shell of whoever ran
+> `akm workflow run` (or the CI job that did) routinely carries tokens for
+> unrelated services, and a third-party workflow step that merely prints
+> its environment should not get them for free; it makes the environment
+> surface EXPLICIT and REVIEWABLE — what a command can see is this constant
+> plus lines in the frontmatter diff, rather than "whatever the invoking
+> shell happened to export"; and it matches the convention akm already
+> applies to spawned children — `profile.envPassthrough` in
+> `integrations/agent/spawn.ts` has always built agent-harness children
+> this way, and the SAME `collectAllowlistedEnv` does it here, so there is
+> one mechanism to review instead of two.
+
+### Capture and overflow semantics
+
+Moved verbatim from `runExecUnit`'s doc comment:
+
+> Run one exec unit and map its process outcome onto the dispatch
+> vocabulary: non-zero exit → `non_zero_exit`, wall-clock expiry →
+> `timeout`, cancellation → `aborted`, a child that never started →
+> `spawn_failed`. All four are pre-existing `AgentFailureReason` members, so
+> `retry.on` keeps working unchanged. The out-of-taxonomy
+> `exec_cwd_escape`, `exec_output_limit`, `exec_context_too_large` and
+> `exec_capture_incomplete` are deliberate: each is tampering, a runaway, an
+> authoring bug, or work that ALREADY RAN — never a transient — so no
+> `retry.on` value can ever re-dispatch one.
+>
+> **An INCOMPLETE STDOUT capture is a failure, never a partial artifact.**
+> `exitCode === 0` is not on its own proof that stdout was fully read: a
+> pipe can error, and the stream-drain timeout can fire while the command
+> LEADER has already exited 0 because a background descendant still holds
+> the stdout fd open. Both leave a PREFIX, and promoting it would hand the
+> next step, the gate judge and `steps.<id>.output` a silently truncated
+> artifact. So the unit fails instead, through the same shared classifier
+> (`streamCaptureFailure`) the agent spawn path uses. Only STDOUT is fatal
+> here — stderr is a diagnostic channel that never contributes to the
+> artifact, so a stderr drain that did not finish leaves the unit's actual
+> result intact. The stdout reason is `exec_capture_incomplete`,
+> deliberately OUTSIDE the `retry.on` taxonomy, for the same reason
+> `journal_write_failed` is: the command RAN TO COMPLETION and exited 0 —
+> what failed is akm's record of it. A retryable reason here would let
+> `retry.on: [spawn_failed]` re-dispatch byte-identical argv for a command
+> that already deployed, already published, already migrated.
+>
+> **Output OVERFLOW does not fail a command that passed.** Crossing
+> `WORKFLOW_MAX_EXEC_OUTPUT_BYTES` is a different condition: the reader DID
+> drain the pipe to its end, it just stopped RETAINING, so the child never
+> blocked and its exit code is real. Overflow splits by what the unit
+> PROMISED about its output: no declared `output:` schema → success, with
+> the artifact carrying a `WORKFLOW_EXEC_OUTPUT_TRUNCATED_MARKER` block
+> naming both byte counts; a declared `output:` schema →
+> `exec_output_limit`, since a truncated JSON prefix cannot parse and
+> promoting it would corrupt every downstream reference to the typed
+> artifact. stderr overflow never fails anything.
+
+## Consequences
+
+- Adding a new name to `EXEC_DEFAULT_ENV_PASSTHROUGH` is a real security
+  and portability decision, not a drive-by convenience edit — every
+  existing entry earns its place with a documented reason above, and a new
+  one should be held to the same bar.
+- The allowlist mechanism (`collectAllowlistedEnv`) is deliberately the
+  SAME one `integrations/agent/spawn.ts` uses for agent-harness children —
+  a divergence between the two lists is a drift to catch, not a place to
+  special-case exec units.
+- The engine-authored `AKM_*` context is applied LAST specifically so no
+  authored `env:` binding can ever shadow it; any future third environment
+  layer must preserve that ordering guarantee or a workflow step gains the
+  ability to spoof its own run/step/unit identity to the engine.
+- `exec_capture_incomplete` and `exec_output_limit` must never be added to
+  any `retry.on` taxonomy — doing so would let a step's own retry policy
+  re-run a command whose side effects already happened.
+
+## Provenance
+
+- Source: `src/workflows/exec/exec-unit.ts` — module header (invariants),
+  `EXEC_DEFAULT_ENV_PASSTHROUGH`'s doc comment, `childEnv`'s doc comment,
+  `runExecUnit`'s doc comment.
+- Related: DRIFT-6 (`AKM_EVENT_SOURCE` provenance parity with the agent
+  passthrough list); `docs/guides/run-workflows.md` ("workflow sources are
+  executed code").
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0004-task-input-contract-and-flag-coercion.md

@@ -0,0 +1,97 @@
+# 0004 — The shared input contract, generalized from workflow params
+
+## Context
+
+Before task source v4, workflow parameters (`WorkflowParameterPlan` /
+`WorkflowParameterFlag` in `src/workflows/ir/params.ts`) had their own
+pure validation/coercion vocabulary, and nothing else in the codebase
+needed the same shape. Task source v4 introduced typed `inputs:`
+declarations on tasks (P2a), which need the identical kind of contract —
+declared names, types, defaults, required-ness, JSON-schema validation —
+but for a different caller (a task) with its own diagnostics vocabulary
+(different error codes and messages than a workflow parameter flag). Rather
+than duplicate the logic, P2a generalized the workflow-only module into a
+shared one.
+
+## Decision
+
+Moved verbatim from `src/execution/input-contract.ts`'s module header:
+
+> The shared input contract (P2a Lane B, docs/plans/specs/
+> p2a-task-source-v4.md §4, §1.3 D3, and the disambiguations
+> D3-N1/D3-N2/D3-N3 in §1.5).
+>
+> This module GENERALIZES the pure module `src/workflows/ir/params.ts`
+> (`WorkflowParameterPlan`, `WorkflowParameterFlag`,
+> `materializeWorkflowParameterFlags`, `validateWorkflowParams`,
+> `assertRunParamsSatisfyPlan`) into a contract-shaped vocabulary that both
+> workflow params AND task source v4's `inputs:` declarations can consume.
+> `src/workflows/ir/params.ts` becomes a THIN CONSUMER of this module: it
+> adapts a `WorkflowParameterPlan` into an `InputContract`
+> (`contractFromPlan`), supplies the workflow-specific diagnostics
+> vocabulary, and re-exports its three wrappers under their existing names
+> — byte-identical messages, codes, and hints
+> (`tests/workflows/workflow-param-flags.test.ts`,
+> `tests/integration/workflows/params-validation.test.ts`).
+>
+> `TaskInputBinding` is declared here for P2b (task source v4 `inputs:`
+> delivery). P2a only ever produces `kind: "literal"` bindings, and nothing
+> consumes them yet — P2a's contract for inputs is VALIDATION only
+> (docs/plans/specs/p2a-task-source-v4.md §0).
+>
+> **D3-N1 (import boundary):** `src/execution/**` must never import
+> `src/workflows/**` — `tests/architecture/import-cycle-ratchet.test.ts`
+> runs a shrink-only, EMPTY baseline, and an `execution -> workflows` edge
+> would close a cycle the moment `workflows/ir/params.ts` imports back into
+> this module. `INPUT_NAME_PATTERN` is therefore DEFINED here (identical
+> source/flags to today's `PROGRAM_PARAM_NAME_PATTERN`) rather than
+> imported from the workflow program vocabulary; `src/workflows/program/
+> schema.ts` becomes a re-export of this constant instead. Permitted
+> imports: `node:crypto`, `src/core/errors`, `src/core/json-schema`, and
+> `src/execution/**` — see `tests/execution/input-contract.test.ts`'s
+> purity scan, which reads this file as text/AST and asserts the allowlist.
+>
+> **D3-N2 (canonical JSON):** `canonicalInputJson`/`canonicalInputHash`
+> implement the SAME recursive key-sort + `JSON.stringify` as
+> `canonicalJson` (`src/workflows/ir/plan-hash.ts`) locally, rather than
+> importing it — `plan-hash.ts` also imports `./schema-v4` and
+> `../resource-limits`, so importing it would drag workflow IR into
+> `src/execution/**` and violate D3-N1. `tests/execution/
+> input-contract.test.ts` asserts BYTE EQUALITY with `canonicalJson` over a
+> fixture set covering nested objects, arrays, `null`, unicode keys, and
+> insertion-order permutations, so the duplication cannot drift unnoticed.
+>
+> **D3-N3 (injected diagnostics vocabulary):** `materializeInputFlags`
+> contains no literal user-facing string. Every message/code it raises is
+> produced by a caller-supplied `InputFlagDiagnostics` — `params.ts`'s
+> `WORKFLOW_PARAMETER_DIAGNOSTICS` reproduces today's five
+> workflow-parameter strings/codes exactly; `src/tasks/source/
+> task-input-diagnostics.ts` supplies the task vocabulary.
+>
+> Pure module: no IO, no engine imports.
+
+## Consequences
+
+- Workflow params and task `inputs:` share exactly one validation/coercion
+  implementation; a bug fix or a new capability (e.g. a new JSON-schema
+  subset feature) lands once and both callers get it.
+- The two callers can still speak entirely different user-facing vocabulary
+  (different error codes, different hint text) because the diagnostics are
+  injected, not hardcoded — `materializeInputFlags` itself never needs to
+  know which caller it is serving.
+- `src/execution/**` staying import-free of `src/workflows/**` is a
+  standing constraint, not a one-time fact: any future change that makes
+  this module (or anything it imports) reach into `src/workflows/**` closes
+  an import cycle and fails `tests/architecture/import-cycle-ratchet.test.ts`'s
+  shrink-only, empty baseline.
+- The canonical-JSON duplication between here and `workflows/ir/plan-hash.ts`
+  is deliberate, not an oversight — a future refactor that "de-duplicates"
+  it by importing across the D3-N1 boundary is the violation, not the
+  duplication itself.
+
+## Provenance
+
+- Source: `src/execution/input-contract.ts`, module header.
+- Spec: `docs/plans/specs/p2a-task-source-v4.md` §4, §1.3 D3, §1.5
+  (D3-N1/D3-N2/D3-N3).
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0005-task-result-vocabulary-and-legacy-read-mapping.md

@@ -0,0 +1,108 @@
+# 0005 — The D8 result-vocabulary re-code and its legacy read mapping
+
+## Context
+
+Before P1b's D8 vocabulary re-code, a task's result `target.kind` used
+`"prompt"` for a prepared command/agent-LLM result and one shared
+`"command"` for every native (shell/script) result, which conflated two
+materially different execution shapes under one label and mislabeled an
+LLM-routed dispatch as a literal "prompt". D8 renamed the written
+vocabulary; the harder problem was that `task_history` is a durable,
+already-populated table — existing rows on disk still carry the OLD labels,
+and `readTaskHistory` has to keep returning a coherent shape for both
+generations of rows forever.
+
+## Decision
+
+Moved verbatim from `src/tasks/run/task-result.ts`'s module header:
+
+> `TaskRunResult` — the shape every dispatch arm returns — plus the small
+> cluster of helpers that build one directly: `preparedResultTarget` (the D8
+> result-vocabulary projection of a freshly prepared execution),
+> `finishDisabledTask` (the disabled-task short-circuit), and
+> `exitCodeForStatus` (the OS-scheduler exit-code mapping). `RunTaskOptions`
+> — the public options bag `runTask()`, `load-task.ts`, and every dispatch
+> arm read from — lives here too, alongside the other public-surface types
+> the compat shim (`src/tasks/runner.ts`) re-exports.
+>
+> D8 (§5.3, §6 F-2): `preparedResultTarget`'s prepared-command arm now
+> returns `{kind:"command", engine}` (formerly `{kind:"prompt", engine}`);
+> its native arm now returns the bare `{kind:"shell"}` / `{kind:"script"}`
+> (formerly one shared `{kind:"command"}`) — the arm-specific `cmd` is
+> added by `run-native-task.ts` once it has actually built the argv,
+> mirroring the pre-P1b shape where the bare disabled-task projection never
+> carried `cmd` either.
+
+And from `src/tasks/run/task-history.ts`'s module header (the WRITE half —
+the READ half's mapping rule is kept in the code itself, not moved; see
+below):
+
+> The `task_history` read/write boundary: `appendHistory` (write) and
+> `readTaskHistory` / `taskHistoryRowToResult` (read).
+>
+> D8 (spec §5.3, §6 F-2) result-vocabulary re-code, implemented entirely at
+> this read/write boundary. WRITE: every row `appendHistory` writes now
+> carries `targetVocab: 2` in its metadata, and the new target_kind strings
+> ("command" for a prepared command/agent-LLM result, "shell", "script",
+> "workflow" unchanged).
+
+## Consequences
+
+- Every NEW row written after D8 is unambiguous — `targetVocab: 2` plus the
+  new `target_kind` strings mean a reader never has to guess which
+  generation a row belongs to.
+- Every OLD row (written before D8, no `targetVocab` marker at all) must
+  keep reading correctly forever — this is not a migration that runs once
+  and finishes; there is no "convert task_history in place" step, because
+  the table is an append-only historical log, not authoring state. The
+  read-side mapping rule is therefore a PERMANENT part of the codebase
+  (`docs/plans/specs/p4-deletions-closeout.md` row B-51: "it reads old rows
+  forever. Deleting it is a review-blocking violation.").
+- The exact legacy mapping — kept in `src/tasks/run/task-history.ts` itself
+  as a short invariant comment, not summarized here, because a maintainer
+  reading `taskHistoryRowToResult` needs it right there — is: a legacy row
+  (no `targetVocab` marker) maps `"prompt"` → `{kind:"command", engine}`,
+  `"command"` → `{kind:"shell"}`, `"workflow"` unchanged, and anything else
+  (including the new vocabulary's own strings written WITHOUT a marker,
+  which no production writer ever does) → `"unknown"`. The P0-pinned null
+  fallbacks survive: a workflow row's `ref` falls back to `""`, the
+  command/prompt arm's `engine` falls back to `null`.
+- `SAFE_TASK_ATTEMPT_ERROR_CODES` (`src/tasks/run/attempt-lifecycle.ts`) is a
+  related but separate allowlist — it decides which error CODES are safe to
+  surface verbatim in a `detail.error` column, not which result-kind
+  strings are legal. Do not conflate the two when reading either file.
+- **Removed 2026-08-28** (review finding against this phase's own close-out
+  spec, `docs/plans/specs/p4-deletions-closeout.md`): `finishDisabledTask`
+  and `preparedResultTarget`, quoted above as part of the moved essay, are no
+  longer in `src/tasks/run/task-result.ts`. `finishDisabledTask`'s only
+  caller — `run-task.ts`'s `shouldSkipUnactivatedTask` — was deleted by the
+  SAME phase's P4-N6 (task source v4 has no document-level `enabled` to skip
+  at fire time), which left `finishDisabledTask` fully dead; `preparedResultTarget`
+  was in turn `finishDisabledTask`'s only caller, so it went dead with it.
+  Deleting them also retired the `"disabled"` `TaskRunStatus` member
+  `finishDisabledTask` was the sole producer of, and the now-unreachable
+  `result.status === "disabled"` branch in `src/commands/tasks/tasks.ts`.
+  This does not touch the D8 vocabulary or the legacy read mapping this ADR
+  is about — every OTHER dispatch arm still builds its own
+  `TaskRunResult.target` per the Decision above, and `task-history.ts`'s read
+  side is unchanged.
+- **Superseded 2026-09-01**: the "PERMANENT part of the codebase" ruling
+  above (row B-51) is overturned. `task_history` is DB-owned data, and the
+  legacy->current remap is deterministic and total, so it belongs in a
+  one-time schema migration, not three permanently-recurring read-side
+  branches (the mapping had been independently re-implemented at
+  `src/tasks/run/task-history.ts`, `src/commands/health/improve-metrics.ts`'s
+  `isAgentTaskHistoryRow`, and `src/commands/health/windows.ts`). State
+  migration `025-task-history-vocabulary-backfill`
+  (`src/core/state/migrations.ts`) now rewrites every legacy row's
+  `target_kind` (and stamps `targetVocab: 2`) the first time a pre-migration
+  state.db is opened by this or a later release; all three read sites were
+  deleted and now read `target_kind` directly in the current vocabulary.
+
+## Provenance
+
+- Source: `src/tasks/run/task-result.ts` module header;
+  `src/tasks/run/task-history.ts` module header (WRITE half only — the READ
+  half's mapping rule stays in the code as a permanent invariant).
+- Spec: `docs/plans/specs/p1b-model-extraction.md` §5.3, §6 F-2.
+- Extracted: P4 (`docs/plans/specs/p4-deletions-closeout.md` §4.2), 2026-08-27.

package/docs/architecture/decisions/0006-task-source-version-routing.md

@@ -0,0 +1,124 @@
+# 0006 — Task source version routing, from three generations to one
+
+## Context
+
+Between P2a and P4, `src/tasks/source/parse-task-source.ts` was the one
+place every task document's `version:` field got routed to a parser.
+Through that window there were three live generations to route between:
+task v2 (retired at the router itself, with a dedicated unsupported-version
+error), task v3 (the shipped grammar every existing task file on disk still
+used), and task source v4 (the new grammar P2a introduced). The router had
+to dispatch to the right parser without a second parse, a re-serialization,
+or a synthetic document — an invariant P1b §4.3 established for the
+front end and every later phase carried forward unchanged.
+
+Two things about that routing were the module's own, deliberately preserved
+warts, recorded as such at the time rather than fixed:
+
+1. The bounded YAML front end's pre-version failures (source not a string,
+   source too large, YAML parse/warning/expansion) render with a fixed
+   label — `"task v3 source"` — even when the document under parse turns out
+   to declare `version: 4`, because `root.version` cannot be read until the
+   front end has already succeeded or failed. P2a's spec explicitly deferred
+   fixing this: "P4 owns the final label once v3 is gone."
+2. For any `version:` other than `2`, `3`, or `4`, the router fell through to
+   `parseTaskV3Document`'s OWN wording — "version is required and must be
+   exactly 3." — a message that names the wrong number for a document that
+   was never v3 in the first place. This was also deliberately deferred:
+   "P4 owns the final version-error text."
+
+## Decision
+
+Moved verbatim from `src/tasks/source/parse-task-source.ts`'s module header,
+as it read from P2a through the end of P3b (immediately before P4 §3.2
+rewrote it):
+
+> The task source version router (spec docs/plans/specs/p2a-task-source-v4.md
+> §3.4, §1.5 D2-N2).
+>
+> Runs the bounded YAML front end ONCE (`readBoundedTaskSourceYaml`), reads
+> `root.version`, and dispatches into `parseTaskV3Document` (unmodified,
+> exported from `../source-v3`) or `parseTaskSourceV4Document` with that
+> SAME `{root, lineAt}` — no second parse, no re-serialization, no synthetic
+> document (the P1b §4.3 invariant this phase carries forward).
+>
+> D2-N2's exact routing table:
+>
+> | root `version` | routed to | observable result |
+> |---|---|---|
+> | `4` | `parseTaskSourceV4Document` | new grammar |
+> | `3` | `parseTaskV3Document` | byte-identical to today |
+> | `2` | `parseTaskV3Document` | byte-identical (raises `taskV2UnsupportedError` itself) |
+> | absent/other | `parseTaskV3Document` | byte-identical (its own preserved wording) |
+>
+> Only `version: 4` needs an explicit branch: `parseTaskV3Document` already
+> raises `taskV2UnsupportedError` for `version: 2` and its own "version is
+> required.../must be exactly 3" wording for everything else
+> (`source-v3.ts:720-722`) — a DELIBERATELY preserved wart, not fixed here
+> (P4 owns the final version-error text).
+>
+> The front end's own pre-version failures (source not a string, source too
+> large, YAML parse/warning/expansion) ALWAYS render with the "task v3
+> source" label, even when the document later declares `version: 4` —
+> `root.version` cannot be read until the front end already succeeded. This
+> is a deliberate, spec-recorded wart (§3.4): "P4 owns the final label once
+> v3 is gone."
+
+P4 §3.2 (`docs/plans/specs/p4-deletions-closeout.md`) removed task source v3
+acceptance from `src` entirely (§3 family A2) and, in the same commit,
+rewrote the router to close both warts. The terminal routing table, in
+place since:
+
+| root `version` | outcome |
+|---|---|
+| `4` | `parseTaskSourceV4Document` — the new grammar (row B-13) |
+| any other number | `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator (rows B-14/B-15) |
+| absent / not a number | `parseTaskSourceV4Document`'s own `TASK_SOURCE_INVALID` "version is required and must be 4" / "must be exactly 4" wording (row B-16) |
+
+A missing or non-numeric `version:` still routes into the v4 parser rather
+than the generic unsupported-version rejection — that part of the shape is
+unchanged from the original design — because a document with no readable
+version was never task v2 or v3 in the first place, and the v4 parser's own
+field error names the one grammar `src` still accepts.
+
+## Consequences
+
+- **Wart 1 closed (row B-17).** The front end's pre-version failure label is
+  now `"task source"` — version-agnostic, since at that point in parsing no
+  version has been read yet — instead of the `"task v3 source"` label that
+  used to leak the retired generation's name into an error about a document
+  that might turn out to be `version: 4`.
+- **Wart 2 closed (row B-16).** A document with an unreadable `version:`
+  (missing, or not a number) now gets the v4 parser's own "is required and
+  must be 4." / "must be exactly 4." wording, naming the grammar `src`
+  actually accepts, instead of `parseTaskV3Document`'s inherited "must be
+  exactly 3." — which named a generation the document was never going to be.
+- **The routing table shrank from three live branches to one.** `version: 3`
+  and `version: 2` no longer parse at all — both now raise
+  `TASK_SCHEMA_VERSION_UNSUPPORTED` with the migrator hint (rows B-14, B-15),
+  where they used to route to `parseTaskV3Document` and execute
+  byte-identically to any other release. This is the observable break every
+  task v3 (and v2) file on disk hits; `docs/migration/v0.9.1-to-v0.9.2.md`
+  and `CHANGELOG.md` document the remedy (`akm migrate apply`).
+- **The router no longer imports `../source-v3` for a parser call at all.**
+  `parseTaskV3Document` moved to the frozen, vendored migrator copy
+  (`scripts/akm-migrate/migrate/task-source-v3-frozen.ts`) — the router's
+  only remaining job is: is this `version: 4`, or not.
+- `ParsedTaskSource` collapsed from a two-member discriminated union
+  (`{version: 3, v3: ...} | {version: 4, v4: ...}`) to the single-member
+  shape `Readonly<{version: 4; v4: TaskSourceV4Document}>` — every consumer
+  that used to branch on `parsed.version === 4` simplified to its v4 arm.
+
+## Provenance
+
+- Source: `src/tasks/source/parse-task-source.ts` module header, as it read
+  from P2a (`git show 0f16f70fdc61:src/tasks/source/parse-task-source.ts`)
+  through immediately before P4 §3.2's rewrite.
+- Spec: `docs/plans/specs/p2a-task-source-v4.md` §3.4, §1.5 D2-N2 (the
+  original routing design and both recorded warts);
+  `docs/plans/specs/p4-deletions-closeout.md` §3.2.2, §4.2 (the rewrite that
+  closed both warts and required this ADR).
+- Extracted: P4, 2026-08-28 (review finding against this phase's own
+  close-out spec — the index row for this ADR existed from P4's ADR-move
+  commit onward, but the file itself was not authored until this
+  correction).