akm-cli 0.9.29 → 0.9.31

package/docs/architecture/specs/reviews/task-workflow-unification/panel-r1-architecture.md

@@ -0,0 +1,27 @@
+# v8 spec architecture review
+
+major | task path has no freeze stage today, and the spec never says whether it gets one | `runPromptTask`/`runCommandTask` in `src/tasks/runner.ts` resolve engine/model/cascade against *live* `loadConfig()` synchronously inline (no compile/resolve/freeze staging, no persisted plan), while §5.4's two-stage freeze is specified purely in workflow terms (`compileResolveFreezeWorkflow`) — the spec asserts cascade.ts is "consumed at freeze (workflows) and dispatch (tasks)" but never states whether task dispatch runs compile→resolve→freeze in-memory-only or calls cascade.ts directly, skipping the asset-loader injection seam that persona/`uses:` resolution depends on. | spec §4.3, §5.4; `src/tasks/runner.ts:461-567`; `src/workflows/ir/freeze.ts:43`
+
+major | AgentUnitExecutor seam glosses over two structurally different dispatch surfaces | Workflow dispatch already flows through `UnitDispatchRequest` (frozen `FrozenEngineSnapshot`, `IrInvocation`, `env: Record<string,string>`, journaled via `workflow_run_units`) in `src/workflows/exec/unit-dispatch.ts`, but the task-prompt path (`runPromptTask`) builds a `RunnerSpec` from live config via `resolveEngine`/`resolveLlmEngineUse` and calls `executeRunner()` directly, then writes to `task_history`/`logs.db` — a completely different type and persistence shape; "one AgentUnitExecutor, two callers" needs an adapter layer the spec doesn't name, not just a shared strategy interface. | `src/workflows/exec/unit-dispatch.ts:9-31`; `src/tasks/runner.ts:479-539`
+
+major | ShellUnitExecutor claim ignores that the task runner's shell path is a distinct, already-hardened subsystem | `runCommandTask` already owns process-group kill-ladders, `AKM_EVENT_SOURCE` stamping, `resolveNestedAkmCommand`, and its own log/history sinks (`src/tasks/runner.ts:250-341`); folding this into one `ShellUnitExecutor` shared with the orchestrator's `Bun.spawn()` path is plausible but the spec treats it as "just" a strategy swap (§5.1) when it actually requires reconciling two independent timeout/kill/logging contracts — not costed anywhere in §9. | `src/tasks/runner.ts:273-296`; spec §5.1, §9
+
+major | cascade module's two consumption times are not obviously bitemporally safe for `uses: tasks/<ref>` composition | A workflow step referencing `tasks/<id>` resolves that task's cascade layers at the workflow's freeze time (baked into the frozen plan), but the *same* task run standalone via `akm task run <id>` re-resolves cascade against config as of the actual run — the spec never states which config snapshot a step's `uses: tasks/<ref>` composition should read (config at workflow-freeze time vs. config at task-file's own authoring), so two runs of "the same" referenced task can diverge without either being wrong per the spec's own text. | spec §4 layers table, §5.4; `src/workflows/ir/freeze.ts:41` ("only source-to-runtime boundary")
+
+major | persona snapshot / "show layer" reuse is directionally sound but the show layer isn't a resolver today, it's a CLI-output formatter | The provenance ceiling the spec cites is real (`src/commands/read/show.ts:433-445`, `isPrimaryStash` gate deleting `toolPolicy` for non-writable stashes) but it lives inside `akm show`'s response-shaping code, not a reusable resolution function; extracting a `{systemPrompt, toolPolicy, model, …}` snapshot for freeze means carving a pure resolver out of a command handler that currently also does display formatting — a real but unscoped refactor, understated as "consumes the show layer's verdict." | `src/commands/read/show.ts:433-445`; spec §4 item 2
+
+minor | IrInvocation as currently typed (`engine: string` required, `model`, `timeoutMs`, `llm?`) is agent/llm-shaped only — extending it to a `{kind:"agent",…}|{kind:"shell",…}` discriminated union is the right shape given `IrRuntimeKind` already exists as `"llm"\|"agent"\|"sdk"`, but the spec should say explicitly whether `IrRuntimeKind` gets a `"shell"` member or whether shell units carry no `runner` field at all — `decodeWorkflowPlanV3`'s `validateInvocation`/`assertUnitEngineCompatibility` (`src/workflows/ir/schema.ts:481-527`) hard-requires `invocation.engine` on every unit today, so the decoder rewrite is nontrivial, not a narrow "instructions become optional" patch. | `src/workflows/ir/schema.ts:78-84, 383-452, 517-527`; spec §5.2
+
+minor | hashVersion 5 preimage table is a clean, additive extension of the existing pattern | `step-work.ts`'s `computeStepWorkList` already documents its hash preimage exhaustively (hashVersion 4, lines 375-392) and explicitly walks through why each field is in/out; the v5 additions (target kind + ref + content hash, shell text, env literal values) fit the same discipline and the existing code's own doc comments make clear this is a well-understood seam to extend, not a risky one. | `src/workflows/exec/step-work.ts:333-392`; spec §5.3
+
+minor | "one cascade module" name is right, but engine/model resolution logic that would feed it is currently duplicated three ways with subtly different fallback rules (`exactModel`/`effectiveTimeout` in freeze.ts, `resolveEngine`+inline overrides in runner.ts, `resolveLlmEngineUse` in engine-resolution.ts) — each has bespoke opencode-sdk-fallback handling; cascade.ts absorbing all three without losing the sdk-fallback edge cases (`freeze.ts:174-186, 199-208`) is the real engineering cost, understated by calling it "one cascade module." | `src/workflows/ir/freeze.ts:163-209`; `src/tasks/runner.ts:479-514`; spec §4 item 3
+
+minor | env literal/ref provenance split matches an idiom the codebase already uses elsewhere (names-only hashing, resolved-value redaction sets) | `step-work.ts` already hashes `env: template.env ?? null` as ref *names* only and documents exactly the "hashing a resolved secret would leak it" rationale the spec restates in §5.5 — this is not a new pattern, it's naming an existing invariant, which is the correct minimal move. | `src/workflows/exec/step-work.ts:353-358`; spec §5.5
+
+minor | `type: task` adapter-ordering claim is correct and lint-checkable today | `BUILTIN_ADAPTERS` in `src/core/adapter/adapters/index.ts:73-90` does put `akmWorkflowAdapter` before `akmTaskAdapter`, both before the loose `akmAdapter`, confirming the spec's M8 claim that "workflow adapter is ordered first and claims `.md` files" is grounded, not asserted. | `src/core/adapter/adapters/index.ts:73-90`; spec §3
+
+minor | GHA-alignment naming (`uses:`/`run:`/`with:`) is clean and the mutual-exclusion rule maps directly onto a single discriminated `Target` union — no simpler alternative stands out; the one soft spot is overloading `uses: tasks/<n>` to mean "compose this task's fields into me" while `uses: workflows/<r>` means "invoke and return," two different composition semantics under one keyword, which the spec acknowledges (no nesting rule) but doesn't name as an asymmetry worth flagging to authors beyond a doc note. | spec §2.2, §5.1
+
+minor | over-engineered: threading `llm` overrides validation (`assertUnitEngineCompatibility`, `validateLlmOverrides`) through a *shell* invocation union member that never carries them is dead branch surface — the discriminated union (§5.1 `{kind:"shell",...}`) should structurally exclude `llm`/`engine` fields rather than relying on decoder-time cross-checks the way today's single-shape `IrInvocation` must; the spec doesn't say the shell variant drops the whole `invocation` wrapper, so decoder complexity may grow rather than shrink under v4. | `src/workflows/ir/schema.ts:481-498, 517-527`; spec §5.2
+
+minor | under-specified: scheduler-id mapping (`/` → `--` with collision lint) and per-engine capability-declaration shape are both explicitly deferred to the implementer (§11 "Open items") — reasonable to defer, but subdir task ids interacting with `validateTaskId`'s current rejection of `/` (cited in §9) means the migration step and the new id grammar must land atomically, which isn't sequenced anywhere in §8's migration steps. | spec §8, §11; `src/tasks/task-id.ts` (not read in depth but referenced by spec)

package/docs/architecture/specs/reviews/task-workflow-unification/panel-r1-coverage.md

@@ -0,0 +1,74 @@
+# Audit of v8 §11 findings cross-reference
+
+Spec: /home/user/akm/docs/architecture/specs/task-workflow-format-unification.md (v8)
+Baseline: claude/akm-markdown-tasks-history-75l6du @ current HEAD (d8095a0)
+Consolidated findings: scratchpad/review-consolidated.md
+
+Method: for each finding, located v8's claimed resolution via §11's table, read the
+referenced section in full, and where v8 makes a factual claim about current code
+(to justify the design), re-verified that claim by reading the cited file/lines
+directly. Flagged anything that only restates the finding, that is logically
+incomplete relative to the finding's actual scope, or that conflicts with another
+part of v8 or with a documented architectural decision elsewhere in the codebase.
+
+## Verified genuinely resolved (design-level; spec, not code, so "resolved" = coherent design that actually addresses the mechanism, not just names it)
+
+- C1 (output collision): compile.ts:204 (`step.output` → `outputSchema`) and
+  compile.ts:229 (`unit?.output` → `schema`) confirm the two real, distinct
+  schema slots v8's §7 two-homes design targets. Accurate and complete.
+- C2 (shell units in IR): unit-dispatch.ts:19 confirms `engine: FrozenEngineSnapshot`
+  is non-optional today, matching v8's premise; §5.2's discriminated-union +
+  per-kind engine resolution is a real fix, not a rename.
+- C3 (hash preimage): hashVersion 5 table in §5.3 covers every named gap (run: text,
+  shell/cwd, uses: ref + content hash, env literals) and the freeze-time-append
+  design in §2.3 correctly resolves the "no single seam" objection.
+- C4 (cascade layers): config-schema.ts:102-108 confirms `DefaultsSchema` is
+  `.passthrough()` with no `model` field, matching v8's claim; §4's "build, not
+  expose" inventory (6 concrete numbered work items) is substantive, not hand-wavy.
+- M2 (placeholder grammar): agent-dispatch.ts:67-72 confirms `fillPlaceholders`
+  only substitutes positional `{{\d+}}` (matches v7-era `{{0}}` bug claim); named
+  `{{name}}` is recognized only by `extractParameters` (renderers.ts) for metadata,
+  never filled — confirms the bug is real and v8's with:/with.arguments design
+  addresses it.
+- M3 (env additive): compile.ts:46 confirms `env?: string[]` — IR literally cannot
+  carry literal values today. §5.5's provenance split is a real fix.
+- M4 (alias portability): model-aliases.ts confirms `BUILTIN_ALIASES` has only
+  `claude`/`opencode` columns (no `"*"`), while the *global* config-level alias
+  table already supports a `"*"` fallback (config-schema.ts / model-aliases.ts
+  doc comment) — so v8's proposed "give builtins a `*` column too" is consistent
+  with an existing pattern, not novel invention.
+- M6 (dead kind-gate): freeze.ts:67-73 confirms the exact dead-code shape
+  (`llm` computed only when `kind==="llm"`, then guarded on `kind!=="llm"`).
+  Accurate; the capability-notice replacement in §4 item 4 is coherent.
+- M9 (akm-bin resolution) — see PARTIAL below.
+- M11 (freeze IO / lint never freezes): grep confirms `compileResolveFreezeWorkflow`
+  has exactly one call site (runs.ts:241). The two-stage compile/resolve/freeze +
+  lint dry-freeze design in §5.4 is a real structural fix.
+- M12 (defaults.on_error exists today): program/schema.ts:204-211 confirms
+  `ProgramDefaults.onError` already exists at document level, exactly as the
+  finding states. §4's decision to keep on_error/retry as value fields is a
+  direct, correct response.
+- M8 (adapter ordering): akm-workflow-adapter.ts:66-70 confirms `isWorkflowFile`
+  returns true whenever `type` is undefined or `"workflow"` — any `.md` without a
+  contrary `type:` is claimed by the workflow adapter, confirming the collision.
+  Making `type: task` mandatory (§3) is a workable, not hand-waved, fix.
+
+## Problems found
+
+C5 | contradicts | v8 §5.6 proposes a new persisted per-bundle trust grant (`bundles.<name>.allowScriptExecution`, settable via `akm setup`/`akm config set`) to unlock third-party script execution — but src/core/activation-policy.ts explicitly documents a 2026-07-14 decision that the "installation is not activation" work "ships no new trust / approval / security machinery: no labeling, action clamps, confirm prompts, digests, trust records, or persisted `workspace_bindings`," and the existing analogous `tools:` provenance ceiling (show.ts:433-445) has no override at all — it unconditionally strips `toolPolicy` for non-primary-stash assets. v8's claimed "same ceiling philosophy" is therefore inaccurate: the tools: ceiling is a hard, ungrantable ceiling, while the new mechanism is an invertible, persisted, named per-bundle opt-in — a materially bigger and different kind of security surface than the finding's own comparison implies, and one that runs directly against a decision already on record in the codebase.
+
+M13 | partial | v8's §11 row points only to "§3 (improve excluded from task bodies)," which resolves the improve-pipeline half of the finding, but the finding's other half — "the akm adapter special-cases type:'task' as pure YAML so markdown checks never fire" (akm-adapter.ts:404-412, confirmed: `parsed = { data, content: raw, frontmatter: null }` for `type==="task"`, explicitly to suppress `missing-updated`) — is never revisited. v8's own §3 examples give tasks substantial free-form prose bodies that are now the literal executable prompt, but no change to the lint/OKF parse path is proposed to give that prose the same base-check coverage other markdown assets get (frontmatter-shaped checks like `unquoted-colon`/`missing-updated` still never fire on tasks); only `stale-path`/`missing-ref` (body-scoped, frontmatter-independent) survive.
+
+M9 | partial | §5.7's fix ("PATH prepend... replacing the argv-rewrite that shell text would defeat") glosses over why `resolveNestedAkmCommand` was built as an argv splice in the first place: `resolveAkmInvocation()` (resolve-akm-bin.ts) can return a *multi-element* invocation (e.g. a node/bun launcher + script path), not always a single standalone binary. A bare PATH prepend only works when there is one real executable file to point `PATH` at; the multi-arg-launcher case needs a synthesized shim (a generated `akm` script that re-invokes `node <path>`), which is materially more than "PATH prepend" and isn't mentioned.
+
+Minor findings with no resolution anywhere in v8 (contradicts §11's blanket "all resolved or explicitly costed" claim and the Minors row's non-exhaustive listing):
+
+- "§3.5 embodiment sentence reads backwards (--model wins over hint)" (1/3) — no trace of this in v8; the section was restructured away but the underlying precedence claim about `--model` vs. an alias/tier hint is never restated or corrected anywhere in v8's aliasing text (§4 item 5).
+- "Value fields on `uses: workflows/*` tasks are structurally inert (run-workflow takes ref+params only)" (1/3) — not mentioned; §2.2's table gives `with:` → declared param flags for `uses: workflows/<r>` but never addresses whether cascade value fields (timeout, model, etc.) set on such a task do anything, which was the actual complaint.
+- "uses: table covers 5 of ~15 placement types; no rule for the rest" (1/3) — not mentioned anywhere in v8.
+- "single-file provenance lost" (part of the 256 KiB composition finding, 1/3) — §5.4 addresses the 256 KiB cap-breach half ("carry the existing... cap with a lint warning at 80%") but not the provenance-loss half of the same finding.
+
+## Notes on things that check out but are worth flagging as "costed, not fixed" (v8 is honest about these, no complaint)
+
+- M4/§4 item 6: gate judge (`judgeEngine`) explicitly stays outside the cascade in 0.9.0 — correctly flagged as deferred rather than claimed resolved.
+- M7/§8: migration section is a genuine rewrite against the real migrator, spot-checked one mapping (`name:` → body H1) is plausible; not exhaustively re-verified against `task-target-ref-migration.ts` line-by-line given time budget.

package/docs/architecture/specs/reviews/task-workflow-unification/panel-r1-security.md

@@ -0,0 +1,15 @@
+# Security/migration review — task-workflow-format-unification.md v8 (d8095a0), baseline 71bb686
+
+- critical | §5.6 grant mechanism does not exist anywhere in the codebase | `allowScriptExecution` / `bundles.<name>.allowScriptExecution` has zero hits in `src/`, so today "third-party bundle → script asset" is unconditionally executable (script `run:`/`setup:` is already advisory-only per `src/core/activation-policy.ts` comments) — the whole §5.6 line is unbuilt, not just "resolve-time enforceable," and no code path currently gates it | grep across `src/` for `allowScriptExecution`/`ScriptExecution`; `src/core/activation-policy.ts` rules 1-4 (env/task/write-activation only, no script-execution rule).
+- critical | §5.6's reused "ceiling philosophy" (tools: provenance gate, M5) is unverified against code | The spec says script-execution enforcement reuses "the writable-vs-third-party provenance ceiling for self-declared `tools:`" that "already lives" at the show layer, but no such ceiling/gate keyed on writable-vs-registryId for `tools:` was found anywhere under `src/integrations/agent/`, `src/core/adapter/`, or `src/core/asset/` — if M5's premise is wrong, §5.6's plan to "consume the show layer's verdict" has nothing to consume and must build the primitive from scratch, changing the cost estimate | grep for `provenance ceiling`/`toolPolicy` in agent/adapter trees turned up no writable/registryId-keyed logic; only `activation-policy.ts` rule 4 (`isSourceWriteActivated`) and rule 1 (env dangerous-key) exist as analogous patterns.
+- major | §5.6 composition-chain bypass is not addressed by the per-bundle grant design | A writable task composing `uses: tasks/<ref>` where the referenced task (in a third-party bundle) itself targets `uses: scripts/<n>` resolves recursively (§5.1 `{ kind: task, ref }` "resolves recursively once") — the spec never states whose bundle-grant applies (the composing writable task's bundle, which has no grant, or the referenced task's own third-party bundle, which needs one) or how §5.4's resolve stage attributes the grant when task-A (bundle X, writable) pulls task-B (bundle Y, third-party, ungranted) that pulls script-C — this is exactly the "composition chains" bypass route named in the audit brief and v8 gives it no explicit resolution rule | §5.1 recursive task resolution; §5.6 (grant keyed by bundle, not by resolved-asset chain); §2.3 "no nesting" only forbids workflow-in-step, not task-in-task depth-1 recursion through third-party bundles.
+- major | §5.6 grant granularity is per-bundle, not per-asset, so one grant silently activates every future script in that bundle including ones added after the grant (bundle-update bypass) | The grant text says "settable... by `akm config set`" against `bundles.<name>.allowScriptExecution: true` — a boolean on the whole bundle. §5.6 does not pin the grant to a content hash or a specific script set, so `akm update` on a third-party bundle can swap in new/modified script content (or a modified `run:`/`cwd:`) that inherits the prior grant with no re-confirmation — the audit brief's "bundle update swapping script content after grant" bypass is not closed by the design as stated | §5.6 grant text (`bundles.<name>.allowScriptExecution: true`); no mention of grant invalidation on content change; contrast with §5.3's hash-preimage discipline for *dispatch* identity, which has no counterpart for *authorization* identity.
+- major | §5.6 cron-fire-time vs sync-time grant evaluation is unspecified, and §5.4 says resolution happens at "resolve time," which for the task path is `task sync`/lint, not `task run` fire time | The audit brief specifically asks whether grants are evaluated at sync time (when the OS entry is installed) or fire time (when cron actually invokes `akm task run <id>`); §5.6 says "enforced at both executors" and "applied at resolve time (§5.4)" but §5.4's two-stage compile/resolve/freeze pipeline is described for workflows, and the task path's own freeze/resolve moment relative to `sync` vs the scheduler's `task run` invocation is never pinned — if the grant is checked at `sync` time only, revoking `allowScriptExecution` after sync leaves the OS-level cron entry still firing the script, since §5.2 says cron enable/disable is a separate `enabled:` gate, not a script-authorization gate | §5.6; §2.3 ("Trigger keys ... consumed only by `akm task sync` and, at fire time, the task runner's enabled gate `runner.ts:169`" — this passage explicitly documents `enabled` as fire-time-checked but says nothing analogous for the script-execution grant).
+- major | §5.5 "literal entries ... never redacted" collides with `param-secrets.ts`'s own heuristic scanner for exactly this shape of leak, and the spec does not reconcile the two | `param-secrets.ts` exists specifically because author-written values (there: workflow params) that "look like credentials" are dangerous when they cannot be redacted — it scans key names and value entropy and warns. §5.5 freezes `env:` literal values into the plan with the identical non-redactable contract ("frozen into the plan, hashed, shown by `brief`, never redacted") but the spec's decision log gives no equivalent heuristic-warning obligation for literal env entries the way `param-secrets.ts` already provides for params — an author who writes `env: [{ API_KEY: "sk-live-..." }]` (a plausible mistake, not even malicious) gets zero warning at freeze/lint time despite the codebase already having the exact detector (`detectSecretShapedParams`) that could be pointed at literal env values too | `src/workflows/exec/param-secrets.ts` (rationale + `detectSecretShapedParams`); spec §5.5 (no mention of applying the existing secret-shape heuristic to literal env entries); §5.4 (lint's dry-freeze would be the natural hook and isn't used for this).
+- major | §5.5's `AKM_ITEM` (JSON) env injection has no shell-escaping/quoting story and no code precedent to check against | `AKM_ITEM` does not exist anywhere in `src/` yet (grep confirms zero hits) — this is wholly new plumbing proposed by §5.5 ("a `map:` step with a shell target receives `AKM_ITEM` (JSON) and `AKM_ITEM_INDEX` per unit"). JSON serialized into a process env var is safe from *shell metacharacter* injection only if the executor sets it via the `env` object passed to `spawn`/`Bun.spawn` (not string-interpolated into a shell command line); the spec doesn't say which, and existing shell-invoking code in this codebase (`src/tasks/backends/exec-utils.ts` `spawnCommand`) passes argv arrays with no shell, which is the safe pattern, but nothing pins §5.5's `AKM_ITEM` assembly to that pattern rather than to a `run:` string that a script might `eval`/interpolate itself (e.g., a script doing `node -e "$AKM_ITEM"` would be JSON-injection-shaped if the JSON contains `"`/backtick sequences and the script author naively string-interpolates it into a nested command) | §5.5 "Env assembly moves per-unit ... receives `AKM_ITEM` (JSON)"; no code precedent (`grep AKM_ITEM src/` → 0 hits); `src/tasks/backends/exec-utils.ts` `spawnCommand` shows the codebase's existing safe argv-array convention that §5.5 should but does not explicitly commit to.
+- major | §8 migration plan does not fit the actual 71bb686 backup/journal model for the .yml→.md file-level transform | `migration-backup.ts`'s manifest/journal machinery (`ARTIFACT_NAMES`, `MigrationBackupManifest`, apply/restore journal + sentinel) covers exactly four opaque artifacts — `config.json`, `state.db`, `workflow.db`, `index.db` — and has no concept of per-bundle-file changes; the *actual* hardened per-file transform pattern in this codebase is `task-target-ref-migration.ts`'s plan/apply split (read-before-write byte-fencing via `current.equals(rewrite.before)`, single atomic rename per file, no cross-file transaction). §8's `.yml`→`.md` conversion is a two-file operation (create the new `.md`, remove the old `.yml`) that this per-file model does not support atomically: an interruption between writing the new `.md` and removing the old `.yml` leaves both present, which the spec's own "`<id>.yml` + `<id>.md` collide on one conceptId → same named error" rule would then fire on the *migrator's own* half-applied state, turning an interrupted migration into a self-inflicted hard error rather than a resumable step | `scripts/akm-migrate/migration-backup.ts` (ARTIFACT_NAMES, manifest scope); `scripts/akm-migrate/migrate/legacy/task-target-ref-migration.ts` (per-file plan/apply, single-file atomicity only); spec §8 tombstone-collision rule.
+- major | §8's "vendored, frozen copy of the v2 task parser" fix is not yet applied at 71bb686 — the cited defect is confirmed live, not already resolved | `scripts/akm-migrate/migrate/legacy/task-target-ref-migration.ts` line 25 currently does `import { parseTaskDocument } from "../../../../src/tasks/parser"` — the live, non-frozen parser — exactly the M7 finding the spec describes as needing a fix "as part of this work." This is consistent with the spec's own claim (not a contradiction), but it means the "frozen-migrator principle" is presently violated in the baseline the spec is built on, and v8 gives no interim mitigation for the window between baseline and when the vendoring lands — any `src/tasks/parser` change merged before the vendoring work starts will retroactively break `akm-migrate` silently, since nothing in the migrator's test suite pins the parser's frozen behavior independent of `src/tasks/parser` | `scripts/akm-migrate/migrate/legacy/task-target-ref-migration.ts:25`; spec §8 first bullet and §11 M7 row.
+- major | §8 read-only bundle handling for the .yml tombstone/collision rule doesn't address the same read-only-bundle carve-out already coded for the *existing* migration | `task-target-ref-migration.ts`'s `planTaskTargetRefMigration` explicitly skips non-writable bundles and instead *warns* that their v1 `.yml` tasks "will not run after upgrade" (never rewritten, never deleted) — this is the precedent §8's new `.yml`→`.md` conversion must follow for read-only bundles, but §8 states only "task discovery keeps matching `tasks/*.yml` permanently, as a diagnostic" and "sync/doctor/lint each hard-error" without saying whether that hard-error applies to a read-only third-party bundle the operator cannot fix (contradicting the existing precedent of warn-and-continue for exactly that case) — operators with a read-only bundle carrying legacy `.yml` tasks would move from "warned, keeps working" (current) to "hard-errors sync/doctor/lint" (v8), a behavior regression not costed anywhere in §9 | §8 tombstone rule; `task-target-ref-migration.ts` lines 253-271 (existing read-only warn-and-skip precedent); spec §9 cost inventory has no line for this regression.
+- minor | §2.4 lenient placeholder filling is prompt-injection-adjacent but bounded by scope, not fully safe | Leaving unmatched `{{name}}`/`$ARGUMENTS`/`$1`-`$9` verbatim (rather than erroring) means an operator who edits `with:` and mistypes a key, or pulls a shared command asset whose placeholder grammar drifted, gets a raw `{{typo}}` or literal `$3` byte-string injected into the agent prompt with no runtime signal beyond a lint warning that a human must have already run and read — this is "silent garbage into an agent prompt" as the audit brief frames it; it's a correctness/quality risk more than an injection vector since the text is author-controlled, not attacker-controlled, but shared/imported command templates make the author and the operator different trust boundaries, and §2.4 doesn't add any freeze-time notice surfaced to the *operator* (only lint, which is opt-in) | §2.4 ("An unmatched placeholder or unused `with:` key is a lint warning and is left verbatim — not a runtime hard error"); §5.4 (lint dry-freeze exists but running lint is not mandatory before dispatch).
+- minor | §5.7 PATH-prepend hijack risk is named but Windows semantics are not actually specified | §5.7 says bare `akm` resolves "by PATH prepend in the child environment" replacing the argv-rewrite, and separately flags Windows via `schtasks`/`PATHEXT`/`COMSPEC` handling elsewhere in the codebase (`redaction.ts` allowlists `PATHEXT`, `COMSPEC`, `WINDIR` explicitly, suggesting Windows env quirks are already a known sharp edge) — but §5.7 never states whether the prepend uses `;`-joined `Path`/`PATH` (Windows env vars are case-insensitive and there can be both `Path` and `PATH` keys colliding) nor whether a child script that does its own `where akm`/`akm.cmd` shim resolution could still pick up a stale/hijacked entry earlier in the *original* PATH the prepend is supposed to shadow (prepending only shadows if the child's PATH lookup honors first-match order, which is true for `cmd.exe` but not guaranteed for every shell/script interpreter a `scripts/` asset might invoke) | §5.7; `src/core/redaction.ts` PATHEXT/COMSPEC/WINDIR allowlist entries (evidence Windows env handling is already fragile in this codebase); no cross-reference to `src/tasks/resolve-akm-bin.ts`'s existing Windows-aware absolute-path resolution, which §5.7 could reuse instead of a PATH string prepend.
+- minor | §5.5 env-literal redaction carve-out has no cross-check against `redactSensitiveValue`'s recursive, boundary-agnostic redaction, creating a silent divergence between two redaction call sites | `src/core/redaction.ts`'s `redactSensitiveValue` recursively redacts every string leaf of a structured value using `sensitiveValues` before it "crosses a durable/output boundary" — a general-purpose function with no knowledge of the env literal/ref split §5.5 introduces; if any caller applies `redactSensitiveValue` to a frozen plan (or its env-literal entries) using a `sensitiveValues` set built only from ref-sourced secrets (per §5.5's "never redacted" contract for literals), literals are correctly preserved — but if a *different* caller (e.g. a generic log-sanitization pass) instead builds `sensitiveValues` more broadly and includes literal values, §5.5's "never redacted" guarantee silently breaks for that surface with no test/contract in the spec pinning which call sites must respect the split | `src/core/redaction.ts:385-398` (`redactSensitiveValue`, generic/recursive, no literal/ref awareness); spec §5.5 (states the contract but does not name which call sites must special-case literals vs which already handle the split correctly).

package/docs/architecture/specs/reviews/task-workflow-unification/panel-r2-adversarial.md

@@ -0,0 +1,132 @@
+# Adversarial review — task-workflow-format-unification.md v9 (round 2, cold read)
+
+Scope: read the spec cold, then verified its file:line evidence against the actual
+tree at HEAD (`ec5d062`, branch `claude/akm-markdown-tasks-history-75l6du`) for
+src/workflows, src/tasks, src/core, src/integrations/agent, scripts/akm-migrate.
+Most citations were spot-checked directly; two rounds of prior Sonnet panel
+review already landed on v8→v9, so this pass hunts specifically for what those
+missed rather than re-litigating settled findings (all of which I re-verified
+and found accurate: freeze.ts:50/67-73 dead llm guard, config-schema.ts
+DefaultsSchema passthrough + no model field + defaults.llm/agent/improve
+hard-rejected at line ~234-241, show.ts:433-445 tools: ceiling, runner.ts:592-593
+raw-frontmatter bug, activation-policy.ts's no-new-trust-machinery decision,
+task-target-ref-migration.ts:25 importing the live `src/tasks/parser`,
+compile.ts:204/229 output vs outputSchema split, param-secrets.ts's
+detectSecretShapedParams, model-aliases.ts's claude/opencode-only columns,
+step-work.ts hashVersion 4 preimage, WORKFLOW_IR_VERSION currently 3).
+
+## Findings
+
+### MAJOR — §2.4's cited "current filler" evidence points at the wrong function; the actual bug lives in a different, unmentioned call site
+
+§2.4 states: "the current filler substitutes only positional `{{0}}` forms
+leniently (`src/output/renderers.ts:164-186` — a live bug fixed by this work)."
+
+`src/output/renderers.ts:164-186` is `extractParameters()`, called only from
+`commandMdRenderer.buildShowResponse` (line 235) to populate the `parameters`
+field shown by `akm show`. It does not fill or substitute anything — it just
+regexes the template for `$ARGUMENTS`/`$1-9`/`{{name}}` names for display.
+
+The actual filler with exactly the described `{{0}}`/`{{1}}`-only lenient
+behavior is `fillPlaceholders()` in `src/commands/agent/agent-dispatch.ts:67-72`,
+used by `akm agent --command <ref>` dispatch (a CLI entry point the spec never
+mentions). This is a load-bearing citation — it's the concrete evidence
+anchoring §2.4's entire contract and the §9 "inherited bugs fixed en route"
+line — and it misdirects an implementer to a display-only function while
+leaving the actual buggy code, and its actual call site, uncited. It also
+hides a real open question the spec doesn't address: does the new
+cascade-driven `with:`/`$ARGUMENTS`/`{{name}}` filler specified in §2.4
+replace `agent-dispatch.ts`'s `fillPlaceholders`, or do the two now coexist
+with different (old lenient-`{{0}}`-only vs new full-grammar) semantics for
+the same command asset type depending on dispatch path? The spec is silent.
+
+Refs: `docs/architecture/specs/task-workflow-format-unification.md:113-114`,
+`src/output/renderers.ts:164-186,220-238`, `src/commands/agent/agent-dispatch.ts:14-16,63-72`.
+
+### MAJOR — §3's "recognition requires `type: task`" evidence covers only bundle-root probing; the actual per-file indexer classifier that types ordinary `tasks/*.md` files has no task branch at all, and has an ordering hazard the spec's own example would trip
+
+§3 argues residence-only recognition is unimplementable "because the workflow
+adapter is ordered first and claims `.md` files without a contrary `type:`"
+citing `src/core/adapter/adapters/index.ts:73-90`. That citation (plus
+`akm-workflow-adapter.ts`'s `isWorkflowFile`, which returns true when
+`type === undefined`) is accurate, but it is evidence about **single-file
+bundle-root detection** (`akmWorkflowAdapter`/`akmTaskAdapter` `looksLikeRoot`,
+i.e. "is this repo root itself one task/workflow file") — a different code
+path from the one that actually assigns a `type` to every ordinary file inside
+a ordinary akm stash during `akm index`, which is `src/indexer/walk/matchers.ts`
+(consumed directly by `akmAdapter`, per `akm-adapter.ts:27`).
+
+In that classifier:
+- `classifyBySmartMd` (matchers.ts:199-248) special-cases `fm.type === "workflow"`
+  (line 223-225) but has **no `fm.type === "task"` branch at all** today.
+- The `tasks/` directory rule (`DIR_TYPE_MAP`, matchers.ts:98-105) only tests
+  `ext === ".yml"` — a `tasks/<id>.md` file gets **zero** directory-based
+  specificity from either `classifyByDirectory` or `classifyByParentDirHint`
+  today, contrary to what "residence is a lint expectation" implies is already
+  meaningfully wired.
+- Absent a new, correctly-ordered `type === "task"` branch, the classifier's
+  existing `"agent" in fm → { type: "command" }` rule (matchers.ts:234-236)
+  fires first and would misclassify the spec's *own* first example task (§3,
+  `agent: agents/reviewer` top-level key) as a command, exactly the kind of
+  silent miswiring the workflow branch at line 223 was positioned early to
+  avoid.
+
+§9's cost-inventory line ("markdown task recognition (`type: task`)") doesn't
+name matchers.ts, the DIR_TYPE_MAP fix, or this ordering hazard, so an
+implementer following only the cited evidence can miss the actual mechanism
+that has to change and can reproduce the ordering bug live in the spec's own
+worked example.
+
+Refs: spec `docs/architecture/specs/task-workflow-format-unification.md:135-139`;
+`src/indexer/walk/matchers.ts:98-105,199-248`;
+`src/core/adapter/adapters/akm-adapter.ts:27`;
+`src/core/adapter/adapters/akm-workflow-adapter.ts:69`.
+
+### MINOR — "document defaults" layer's applicability to a bare (non-referenced) task is left to inference
+
+§4's six-layer cascade table lists `document defaults:` as a layer distinct
+from `uses: tasks/<ref>` and `step/task keys`, but §3's task schema shows no
+`defaults:` sub-block for a standalone task file — only workflows have
+`asset.document.defaults` today (`freeze.ts:52`). It's a reasonable inference
+that "document defaults" is workflow-only and collapses/no-ops for a bare
+task, but the spec never says so explicitly, and a task that both composes
+another task (`uses: tasks/<ref>`) *and* wants its own "defaults for this
+document" layer (as opposed to its own directly-set fields) has no described
+home. Low risk — an implementer would likely get this right by analogy to the
+existing `documentDefaults` special-casing in freeze.ts — but it's a genuine
+gap in an otherwise very precisely specified cascade.
+
+Refs: spec §4 layers table (line 238); `src/workflows/ir/freeze.ts:52`.
+
+### MINOR — script/task "resolved content hash" for the tools: ceiling doesn't state whether frozen workflow plans re-read script bytes at dispatch
+
+§5.3's hash preimage records "target kind + `uses:` ref + resolved content
+hash" for re-dispatch invalidation, implying script *bytes* are not made
+durable in the plan the way command templates are (§2.4 says command
+templates are filled and frozen). If a script referenced by a frozen workflow
+plan is edited between freeze and (possibly much later, queued) execution,
+the plan's content hash goes stale for journal/idempotency bookkeeping, but
+the spec doesn't say whether execution reads the live file (current bytes) or
+a frozen copy, and doesn't note this as a deliberate asymmetry vs. commands.
+Not a security issue (the ceiling only gates non-primary-stash sources, and
+editing your own primary-stash file is expected), but worth one sentence so
+an implementer doesn't have to guess whether "resolved content hash" implies
+plan-embedded bytes.
+
+Refs: spec §5.3 preimage table (line 368); §2.4 (lines 126-128, "filling
+happens at freeze... producing the prompt string").
+
+## Verdict
+
+No criticals found. The two majors above are citation/evidence gaps rather
+than design contradictions — the underlying design decisions (§2.4's contract,
+§3's `type: task` requirement) are themselves sound and match the codebase's
+real needs; what's wrong is that the evidence anchoring them points at the
+wrong or incomplete code, which is exactly the kind of thing this spec has
+otherwise been extremely disciplined about getting right (nearly every other
+citation checked out verbatim, including several with exact line numbers).
+An implementer working strictly from the cited evidence would fix the wrong
+placeholder-filler function and would very plausibly ship a task-recognition
+patch that misclassifies its own worked example. Both are cheap to fix in the
+spec (retarget the citations, name matchers.ts + DIR_TYPE_MAP + the ordering
+requirement) before implementation starts.

package/docs/architecture/specs/reviews/task-workflow-unification/panel-r2-verification.md

@@ -0,0 +1,147 @@
+# Round-2 verification of v9 against round-1 Sonnet panel (coverage/architecture/adversarial/security)
+
+Spec: docs/architecture/specs/task-workflow-format-unification.md, v9 (ec5d062), branch
+claude/akm-markdown-tasks-history-75l6du. Baseline for code claims: same checkout.
+
+Method: for every critical/major in the four r1 reports, located the v9 text via §11's
+cross-reference table, read the cited section in full, and where the fix leans on a
+factual code claim, re-verified the claim by reading the cited file. Then checked the
+new text against the rest of v9 for reintroduced contradictions, with extra scrutiny on
+the five areas called out (§5.6 ceiling, persona-snapshot hash, `with:` merge, tombstone
++ crash-window ordering, shim vs resolve-akm-bin.ts).
+
+## Criticals — all four verified fixed, no reintroduced contradiction
+
+- **coverage C5** (§5.6 grant contradicts activation-policy's no-new-trust decision):
+  v9 deletes the `bundles.<name>.allowScriptExecution` grant entirely and replaces it
+  with exact inheritance of the existing `tools:` provenance ceiling (primary-stash-only,
+  no override, fail-closed) — verified `show.ts:433-445` really has no override
+  (`if (response.toolPolicy !== undefined && !isPrimaryStash) delete ...`), matching v9's
+  description exactly. `activation-policy.ts`'s "no new trust machinery" decision (header
+  comment, 2026-07-14) is respected: zero new config, zero persisted state. Fixed.
+- **security "grant mechanism doesn't exist" / "ceiling philosophy unverified"**: moot —
+  v8's grant is withdrawn. The second half of this finding (reviewer claimed the `tools:`
+  ceiling "was not found" in code) is factually wrong — it exists at `show.ts:433-445` —
+  and v9 §11 correctly flags this as the one rejected panel claim. Confirmed correct.
+- **adversarial "`with:` merge/replace semantics undefined"**: §2.2 now states the rule
+  explicitly — per-key shallow merge on a step→task→(command|workflow) composition chain,
+  referencing step wins, `with.arguments` replaced whole. Checked against §2.3 ("no
+  nesting: a task referencing a task is an error") — the chain is capped at depth 1
+  exactly where the merge rule assumes it stops, no gap. Checked against §4 ("`with:` is
+  not a value field... merges per-key at its target, outside the cascade") — value-field
+  cascade (§4's layer list, which includes `uses: tasks/<ref>` as a layer) and `with:`
+  merge are two disjoint mechanisms over two disjoint key sets; no overlap, no
+  contradiction. Fixed.
+- **adversarial "hashVersion 5 omits persona snapshot"**: §5.3's table now has a
+  `persona snapshot hash` row (system prompt, tool policy, value fields). Matches §4.2's
+  persona-snapshot shape (`{systemPrompt, toolPolicy, model, …valueFields}`) verbatim —
+  same field list on both sides. Fixed, consistent.
+- **adversarial "`.yml` tombstone hard-error has no remedy for read-only bundles"**: §8
+  now carves out read-only/third-party bundles to a warning instead of a hard error,
+  explicitly citing it as matching the existing migrator precedent. Verified against
+  `scripts/akm-migrate/migrate/legacy/task-target-ref-migration.ts:246-266` —
+  `planTaskTargetRefMigration` really does skip non-writable bundles and warn-and-continue
+  for legacy files it can't rewrite, word-for-word the precedent v9 claims. Fixed.
+> **Editor's note (archival).** The cosmetic stage-name mismatch this
+> report flags in §5.6 was fixed in the same revision that followed this
+> panel: v9 now says the ceiling is evaluated in the **resolve stage** for
+> both surfaces. The finding is retained as the historical record of what
+> the panel saw, not as an open issue.
+
+
+## Majors — verified fixed unless noted
+
+All of the following were checked and are substantively addressed with no new
+contradiction: architecture's five majors (task-path staging named in §5.1 as
+"resolve → execute"; `RunnerSpec`-vs-`UnitDispatchRequest` split pushed to the sink
+per §5.1; `ShellUnitExecutor` explicitly extracted from the task runner's hardened path,
+not rebuilt; monotemporal composition rule pins config-snapshot timing for `uses:
+tasks/<ref>`; persona resolver extraction named and costed in §9); adversarial's
+`extra_params` deep-merge preservation (§4 merge-classes, matches `freeze.ts:211-216`
+`mergedLlmOverrides`/`deepMergeConfig` exactly), shell `timeoutMs` slot (§5.2), shell
+crash/lease semantics (§5.2), persona-toolPolicy-vs-engine-capability reconciliation
+(§4.2's "unconsumed-field notice" line folds it into §4 item 4's capability-notice
+mechanism); security's composition-chain bypass (§5.6 bullet 3, "inherit from the
+defining asset's own source"), grant-granularity/bundle-update bypass (moot — grant
+removed), sync-vs-fire-time gap (§5.6 bullet 2, evaluated at resolution not at
+sync/enable time), `env:` literal-secret-heuristic reuse (§5.5, points at
+`param-secrets.ts`'s `detectSecretShapedParams` directly), `AKM_ITEM` shell-injection
+story (§5.5 pins it to the `exec-utils` env-object pattern, never shell-text splice),
+and the two-file migration atomicity gap (§8 states journal-then-verify-then-delete
+ordering explicitly as new work, costed in §9, rather than claiming the existing
+4-artifact `migration-backup.ts` model already covers it — checked, that model really
+is scoped to `config.json`/`state.db`/`workflow.db`/`index.db` only, so v9's honesty
+about this being an extension is accurate, not a claim contradicted by code).
+
+- **coverage M13 (improve-exclusion mechanism)**: §3 now removes the `type:"task"`
+  pure-YAML special-case (markdown base checks fire) and separately declares tasks
+  improve-ineligible via a per-type adapter capability. The capability-declaration
+  *pattern* genuinely exists today (`bundle-adapter.ts:9`, "one interface, optional
+  capability methods"), so naming that seam is not fabricated — but the concrete
+  eligibility check in `src/commands/improve/eligibility.ts` is currently a hardcoded
+  `indexed.entry.type === "..."` string comparison, not adapter-capability-driven; v9
+  doesn't say eligibility.ts itself gets refactored to consult the new capability
+  rather than its own type-string list. Not a contradiction, but thinner than "names a
+  mechanism" suggests — residual gap, not blocking.
+- **coverage M9 / adversarial-adjacent (akm-bin shim)**: §5.7's synthesized-shim design
+  (write a temp-dir `sh`/`.cmd` shim invoking the exact resolved multi-element
+  invocation, PATH-prepend the shim's directory) matches `resolve-akm-bin.ts`'s actual
+  return shape (`argv: string[]`, up to two elements for the npm/checkout launcher
+  cases) — the shim approach correctly generalizes to the multi-element case a bare PATH
+  prepend cannot. Fixed.
+
+## Special-attention items — findings
+
+1. **§5.6 ceiling enforceability at both resolve points**: the mechanism itself
+   (primary-stash-only, checked at the point the target asset is resolved, no override)
+   is sound and symmetric for workflows and tasks. However, v9 states the enforcement
+   point as "freeze for workflows, dispatch for tasks" — but §5.1 (this same v9 revision)
+   explicitly renames task staging to **"resolve → execute"** (no stage named "dispatch"),
+   and §5.4 explicitly splits workflow freeze into **compile → resolve → freeze**, with
+   asset loading (the thing the ceiling needs to inspect) happening in **resolve**, not
+   in the now-narrower **freeze** ("snapshot + hash" only). So §5.6's own enforcement-point
+   language doesn't line up with the stage names v9 itself just introduced elsewhere
+   (§5.1, §5.4) to fix the architecture panel's "staging is unstated" finding. This is
+   cosmetic (both "resolve" and "freeze"/"dispatch" as used here occur before any
+   shell/agent actually spawns, so no execution-order security gap results), but it is a
+   real terminology inconsistency introduced by the v9 redesign, not present as such
+   before the two staging fixes existed to be inconsistent with. Not blocking; a
+   copy-edit item.
+2. **"scope: non-AI exec surface only" loophole for third-party `run:` tasks scheduled
+   via sync review**: no loophole found. §5.6's own definition of "shell-class work"
+   explicitly includes "the `run:` text of a task," so a third-party task whose target is
+   `run:` is covered by the ceiling and refuses regardless of whether the operator
+   reviewed and enabled it via `sync` (activation-policy rule 3 is a separate, orthogonal
+   gate that only concerns *whether the task fires at all*, not *whether its shell target
+   is trusted*). The "agent-dispatched third-party tasks... unchanged" carve-out only
+   exempts prose/agent-dispatch tasks (which have no direct shell surface here), not
+   `run:`/script tasks. No new hole.
+3. **Persona-snapshot hash vs §4.2 resolver extraction**: consistent — §5.3's new row
+   lists exactly the fields §4.2's snapshot shape defines (systemPrompt, toolPolicy,
+   value fields), and both are attributed to the same extracted resolver.
+4. **`with:` merge rule vs §4 cascade and §2.3's override bullet**: consistent — verified
+   above, disjoint mechanisms, no double-counting.
+5. **Tombstone carve-out + crash-window ordering vs §8's journal claims and the real
+   migrator**: consistent — the read-only carve-out matches
+   `task-target-ref-migration.ts`'s existing warn-and-skip behavior; the create-verify-
+   delete ordering is honestly presented as new work extending (not already covered by)
+   `migration-backup.ts`'s 4-artifact model, and it's costed in §9's "Named refactors" row.
+6. **Shim design vs `resolve-akm-bin.ts`**: consistent — the shim generalizes correctly
+   to the multi-element launcher case `resolveAkmInvocation()` can return.
+
+## Verdict
+
+ALL FIXES HOLD.
+
+Residual (non-blocking) notes:
+- §5.6's "freeze for workflows, dispatch for tasks" enforcement-point language uses stage
+  names that don't match the stage vocabulary §5.1/§5.4 just introduced in this same
+  revision ("resolve → execute" for tasks; compile→resolve→freeze for workflows, with
+  asset resolution living in "resolve" not "freeze"). Suggest wording as "resolve for
+  workflows, resolve for tasks" (or just "at resolve, for both") to align with §5.1/§5.4.
+- §3's improve-ineligibility fix correctly names an existing capability-declaration
+  *pattern* in the adapter interface, but doesn't state that
+  `src/commands/improve/eligibility.ts`'s current hardcoded `entry.type === "..."` checks
+  need to be rewired to consult that capability — worth a one-line addition if precision
+  matters, but doesn't reopen the original finding (a mechanism is now named, whereas
+  before none was).