P0 — invariant inventory for the task/workflow refactor

Status: ready for test authoring Phase: P0 of the akm task/workflow refactor Owner artifacts: tests only — P0 changes no production code

This document is the single source of truth for the three P0 test-writing lanes. Lanes do not re-derive these facts from the codebase and do not read the parent plan. Every file:line reference below was verified at the current head of claude/breaking-changes-0-9-2-3cfyvp (== release/0.9.2).

0. What P0 is

P0 pins current behavior — including behavior we have already decided is wrong — with passing characterization tests. Nothing is fixed here.

The contract that makes the later phases cheap:

• Every row in the two tables below gets at least one test that passes today.
• A row in Behavior to replace is a test that a later phase will deliberately flip — exactly one pinned test per deliberate change, so a reviewer of P1–P4 can see the behavior change as a test diff rather than having to reason about it.
• A row in Behavior to preserve is a test that must keep passing through every later phase. A later phase breaking one of these is a regression, not a decision.

Therefore:

• Pin the observable effect (thrown error type + code + message text, stored string, env var seen by a child, resulting shape), never the internal call path. Tests that assert on private helpers make the later phases harder, not safer.
• Where a message string is quoted below, pin it verbatim. Byte-identical duplicate messages (R-03) are pinned at each site separately so a later phase cannot collapse two rejections into one without a visible test diff.
• Do not "improve" anything you find while writing these tests. A defect you notice that is not in these tables belongs in the Review log, not in a fix.

ID scheme

P-nn = preserve. R-nn = replace. Lanes cite these IDs in test names so the phase that flips a row can find its test with a grep.

Behavior to preserve

These are load-bearing today and stay load-bearing after the refactor.

Behavior to replace

Each row is a deliberate future change. P0 pins it passing; the named phase flips exactly the pinned tests.

Lane pin checklists

Three lanes work in parallel. Each lane owns its rows end to end; no row is shared between lanes except R-04, which is split explicitly below.

Lane A — workflows

Owns everything under src/workflows/.

• [x] R-01 (a) A workflow step uses: tasks/<ref> with with: {…} of scalar values decodes with no error and no diagnostic.
• [x] R-01 (b) Guardrails that do fire today still fire: a non-scalar with value fails via scalarRecord (schema.ts:389), and with without uses fails with step <id> with is legal only with uses (schema.ts:393).
• [x] R-01 (c) The drop is proven by equality: freeze the same task step twice, once with with: and once without, and assert the two resolved dispatches are equal. This is the test P1a flips to an expected rejection.
• [x] R-01 (d) Contrast case: the same with: on uses: akm/command is consumed (source-freeze-v4.ts:148) and target-validated (schema.ts:371). Pin it so P1a's rejection cannot accidentally cover the builtin-command path too.
• [x] R-02 A uses: scripts/<ref> step freezes to a script dispatch carrying the script's own qualified ref, exact bytes, and interpreter — the identity shape the synthetic document produces is not observable anywhere production surfaces (see the Review log) and is not pinned; likewise the bare-Error invariant at source-freeze-v4.ts:296 is unreachable from directScript's own call site and is not pinned.
• [x] R-03 Two tests, one per reachable site: semantics.ts:141-146 (code nested-workflow-unsupported) and source-freeze-v4.ts:220-222. source-freeze-v4.ts:237-239 guards the byte-identical message one call later in the same taskDispatch, but is unreachable in practice — no fixture can pass the :220 guard and still reach :237 with prepared.kind === "workflow" (see the Review log) — so it is recorded as a dead duplicate rather than pinned by a third test.
• [x] R-04 (c) A GitHub-action locator in a workflow step throws code remote-action-acquisition-out-of-scope.
• [x] R-05 (a) A 2-job source parses clean into 2 jobs.
• [x] R-05 (b) Freezing it throws the exact multi-job UsageError.
• [x] R-05 (c) compileWorkflowPlan returns ok: false with the exact message and the second job's line — not a throw.
• [x] P-08 Job-count bounds (0, 1, 256, 257), needs validation (missing / cycle / duplicate), needs sorting, and the canonical emission order for two independently-ready jobs.

Lane B — tasks

Owns everything under src/tasks/ plus the usage-events default.

• [x] P-01 with + command ref → exact UsageError message, code INVALID_FLAG_VALUE.
• [x] P-02 with + script ref → exact UsageError message, code INVALID_FLAG_VALUE.
• [x] P-03 with + workflow ref → params deep-equals the authored mapping; absent with → {}; result frozen.
• [x] P-04 workflow ref + any env: → exact UsageError message.
• [x] P-05 Workflow arm stamps and restores global process.env.AKM_EVENT_SOURCE; restoration happens on the throwing path too; a pre-set more-specific value survives.
• [x] P-06 Native shell/script arm sets it in the child env only; parent process.env never mutated.
• [x] P-07 resolveUsageEventSource table: unset/"" → "user"; each valid value → itself; garbage → "unknown".
• [x] R-06 Neither-and-both scheduling sources produce the same error text; the akm.schedule success shape (source: "akm.schedule", ordinal: 0, manual: false) is pinned.
• [x] R-07 Prompt arm sets AKM_EVENT_SOURCE nowhere, and resolveUsageEventSource() observed from inside it returns "user". Assert (c) explicitly.
• [x] R-08 Four arms × (stored target_kind string, read-back shape), plus the null/unrecognized → { kind: "unknown" } case. Shell and script must both be pinned even though they store the same string.
• [x] R-09 With no bundleName and no defaultBundle, the qualified task ref resolves against bundle stash. Assert the ref string, never the option key.

Harness note for P-05 (and P-06's negative half): tests/_preload.ts installs a tripwire that throws if a test leaks an AKM_* env var that was not present at preload time (AGENTS.md, "Test-isolation harness"). P-05 exercises a production path that mutates process.env.AKM_EVENT_SOURCE on purpose. Observe the stamp from inside the run (via an injected runWorkflowStepsImpl) and let the production finally restore it; never leave the var set across the test boundary and never set it by hand outside the sandbox helpers.

Lane C — fixtures

Owns the shared fixture surface both other lanes build on. Lane C lands first; A and B consume it.

• [x] A task-step-with-with workflow fixture pair: identical sources differing only by the with: block (R-01 c needs both halves).
• [x] A builtin-command-with-with workflow fixture (R-01 d), so the consumed path and the dropped path sit side by side.
• [x] A script-step workflow fixture (R-02).
• [x] Two nested-workflow fixtures, one per reachable R-03 site: a workflow step naming a workflow directly (semantics.ts:141-146) and a task document whose uses is a workflow (source-freeze-v4.ts:220-222). source-freeze-v4.ts:237-239 is a documented-dead duplicate of the second site (see the Review log) and is not a fixture requirement.
• [x] GitHub-action fixtures (R-04): a task document with an action uses, and a workflow step with the same locator. Include one near-miss locator that falls through to the trailing classifyTaskV3Uses throw.
• [x] Multi-job fixtures (R-05, P-08): a valid 2-job source with needs; a 0-job source; a >256-job source; a missing-needs source; a cycle; a duplicate-needs source; and a two-independently-ready-jobs source for canonical ordering.
• [x] Scheduling fixtures (R-06): neither source, both sources, akm.schedule only, on: only.
• [x] Task target fixtures covering all four prepared arms — workflow, command (agent/LLM), shell, script — reused by R-08 and by P-05/P-06/R-07.
• [x] Fixtures use tests/_helpers/sandbox.ts (sandboxStashDir(), writeSandboxConfig()); no process.env.HOME mutation, no process.chdir, no globalThis.fetch = (scripts/lint-tests-isolation.ts enforces this).
• [x] Every new test file carries the MPL-2.0 header (scripts/lint-license-headers.ts).

Acceptance criteria

• [x] docs/plans/specs/p0-invariants.md exists and is the only file changed by the spec commit.
• [x] No file under src/ is modified in P0. git diff --stat release/0.9.2..HEAD -- src/ is empty at the end of the phase.
• [x] Every row P-01…P-08 has at least one test that passes at current head.
• [x] Every row R-01…R-09 has at least one test that passes at current head.
• [x] Each test names its row ID (e.g. R-08) in its describe/it title, so the phase that flips a row can find it with a grep.
• [x] R-03's two reachable sites (semantics.ts:141-146, source-freeze-v4.ts:220-222) are each covered by a distinct test reaching that distinct code site, distinguishable by fixture rather than by message text; the third site (source-freeze-v4.ts:237-239) is a documented-dead duplicate recorded in the Review log rather than pinned.
• [x] R-05 pins both the throwing freeze path and the non-throwing compileWorkflowPlan return path.
• [x] R-07 asserts the "user" resolution explicitly, not merely the absence of the env var.
• [x] R-08 pins the stored target_kind string for all four prepared arms plus the null/unrecognized read-back.
• [x] R-09 asserts a resulting ref string, not the stashDir option name.
• [x] No test asserts on a private helper where an observable surface (error type + code + message, stored string, child env, returned shape) was available.
• [x] All new tests use tests/_helpers/sandbox.ts; bun scripts/lint-tests-isolation.ts passes.
• [x] Every new test file carries the MPL-2.0 header; bun scripts/lint-license-headers.ts passes.
• [x] bunx biome check --write src/ tests/ produces no further changes; bunx tsc --noEmit is clean.
• [x] bun run check passes (lint + typecheck + test:unit + test:integration).
• [x] Any defect discovered while writing these tests but not listed in the tables is recorded in the Review log below and left unfixed.

Review log

2026-08-25 — R-03's third site (src/workflows/ir/source-freeze-v4.ts:237-239) is unreachable in practice. That guard fires on prepared.kind === "workflow", where prepared is the return of prepareTaskV3Execution. prepareTaskV3Execution (src/tasks/runtime-v3.ts:415) returns kind: "workflow" only when the parsed task document's target.uses.kind === "workflow" — exactly the condition the :220-222 guard in the same taskDispatch call already tests, on the same parsed task object, before prepareTaskV3Execution is ever invoked. No fixture can pass the :220 guard and still reach :237 with prepared.kind === "workflow": the two sites guard one condition twice, not two independently reachable failures. The R-03 row and the Lane A checklist have been amended to name two reachable sites (semantics.ts:141-146, source-freeze-v4.ts:220-222) plus this documented-dead duplicate, rather than requiring a third, unreachable pin. Left unfixed — no production change in P0.

2026-08-25 — R-02's bare invariant (src/workflows/ir/source-freeze-v4.ts:296, if (prepared.kind !== "script") throw new Error("direct script did not project as a script")) is unreachable from directScript's own call site. directScript is invoked only from resolveStep (source-freeze-v4.ts:144) when target.kind === "script", and the synthetic task document it fabricates always sets uses: <owned.ref> where owned.ref is built with plural = "scripts" (resolveOwnedAssetCore) — so the synthetic document's uses: always classifies, and always prepares, as kind: "script". No fixture reachable through directScript's own call site can make prepareTaskV3Execution return anything else. Exercising the :296 throw would require calling directScript (or prepareTaskV3Execution) with an argument shape it never receives in production. The R-02 row has been amended to not require pinning this invariant. Left unfixed — no production change in P0.

2026-08-25 — R-02's synthetic-document identity fields (filePath, taskId, taskRef) are computed but not observable anywhere production surfaces. directScript (source-freeze-v4.ts:274-298) fabricates filePath = \${asset.path}#${step.id}`, taskId = step.id, and taskRef = `${asset.ref}#${step.id}`, and threads them through prepareTaskV3Executionvia the synthetic document. ButscriptResult()— the only reader of that prepared execution — copies just.sourceRef/.interpreter/.extension/.bytesBase64/.byteLength/.sha256/.cwdIdentityintoFrozenWorkflowScriptTarget; .taskId/.taskRefare dropped. No seam at head re-exposes them either: the one other exported entry point over this path,resolveWorkflowSourceV4, returns the same FrozenWorkflowTargetshape. A characterization test can therefore only pin these fields by hand-constructing the same literalsdirectScriptcomputes and feeding them toparseTaskV3Yaml/prepareTaskV3Executiondirectly (astests/workflows/characterization-classification.test.ts's R-02 identity-contract test does) — which asserts the test's own inputs round-trip, not a surface directScript` itself could break. The R-02 row has been amended to name only the surfaces that are observable (script ref, bytes, interpreter), pinned by the row's companion end-to-end test. Left unfixed — no production change in P0.

2026-08-25 — phase close-out (orchestrator). Three adversarial review rounds ran: 6 → 5 → 3 CONFIRMED findings, each round's findings distinct (deepening precision, not reshaped repeats), each fixed in its own fix(p0) commit. The round budget expired before a fourth confirming round, so the orchestrator verified the round-3 fixes directly against the reviewer's required changes instead of dispatching another round — rationale: all three were narrow, mechanical, and independently checkable (P-05 during-throw observation via observedDuring; R-08 null-fallback rows {kind:"workflow", ref:""} / {kind:"prompt", engine:null}; R-04 near-miss locator owner/repo pinned to the trailing message). All three land in fix(p0): address review findings (round 3) and match the required changes exactly.

Two ADVISORY findings were applied at close-out because they protect known upcoming phases from spurious failures: R-01(c)'s plan-JSON substring probe now uses the distinctive sentinel r01-dropped-sentinel instead of the generic word scope (protects P3a's plan-shape changes), and characterization-fixture-contracts.test.ts's generic flip comments now name their flipping phases (P2a/P2c for v3-migration fixtures, P3a for the irVersion-4 assertion; the read-set test is reclassified PRESERVE). Remaining advisories recorded, not applied: R-05(a) grep-anchor placement; P-08 1-job bound cited only via fixture tests; classifyWorkflowStepUses delegation call-count assertions pin an internal seam; P-06 child-env observed via stdout log rather than a spawn seam; R-07 positional args[2] env capture couples to runAgent argument order; R-05(b) skips akmIndex where siblings call it. Later phases may harden these opportunistically when touching those files.

Gate: bun run lint green, bunx tsc --noEmit green, unit 3879 pass / 0 fail (sharded runners). The full integration suite runs as the final gate step; its result is appended below when it completes. git diff origin/release/0.9.2..HEAD -- src/ is empty — P0 changed no production code. All acceptance boxes ticked.

2026-08-26 — integration gate confirmed green. Full integration suite: 5622 pass / 57 skip / 0 fail across 419 files (sharded runners). An initial run had 15 environment-caused failures in registry-pinned-transport, registry-network-boundary, and package-launcher — all traced to the container's default Node being v22 while akm 0.9.2 requires Node >= 24 (the transport helper and npm launcher enforce it). Fixed at the environment level by installing Node v24.19.0 and making it the default; no repository change was needed and the failures predate P0 (they reproduce at the untouched baseline in a Node-22 environment). P0 gate: lint green, tsc green, unit 3879/0, integration 5622/0.

2026-08-26 — P-05 reclassification (P1b Lane C, required by D5, spec docs/plans/specs/p1b-model-extraction.md §1.2). P-05 pinned the pre-P1b MECHANISM: the workflow dispatch arm (runner.ts:534-535, :552-555 at P0 head) stamped process.env.AKM_EVENT_SOURCE GLOBALLY for the duration of an in-process workflow-task run, then restored the prior value (or deleted the key) in a finally, so a child akm invocation made by a workflow step inherited the stamp through ambient environment inheritance. D5 always scheduled this mechanism for replacement — the global mutation was a correctness liability in its own right (P0's own row named it a cross-run-leakage risk that only worked because the stamp/restore pair happened to be synchronous-safe), and the design decision (D5, phase P1b) was to thread the resolved event source through an explicit, typed ExecutionProvenanceContext instead. P1b (F-1) deletes the global process.env stamp and its finally restore outright — nothing under src/ writes process.env.AKM_EVENT_SOURCE any more (grep-provable: rg "process\.env\.AKM_EVENT_SOURCE\s*=" src/ and rg "delete process\.env\.AKM_EVENT_SOURCE" src/ both return zero hits) — and threads the value through a new optional eventSource option instead: run-task.ts's ExecutionProvenanceContext → run-workflow-task.ts → RunWorkflowOptions.eventSource → src/workflows/exec/run-workflow.ts → native-executor.ts's StepExecutionContext.eventSource → unit-dispatch.ts's UnitDispatchRequest.eventSource → exec-unit.ts's childEnv, applied to the allowlisted base only when the ambient passthrough left the name absent.

The mechanism changed; the four contract clauses P-05 protected did not:

• (a) in-process workflow execution and usage recording still observe event source "task" for an unscheduled or scheduled task run alike (D5-N1) — now via the explicit eventSource option read from inside the orchestrator, rather than via process.env read from inside the same process;
• (b) no cross-run leakage — strengthened, not merely preserved: process.env.AKM_EVENT_SOURCE is now NEVER mutated at all (no set, no delete), so there is no restore step to get wrong and no window, however small, in which a concurrently-running unrelated task could observe the stamp;
• (c) child-env stamping is unchanged for the arm P-06 pins (native shell/script) and is now ALSO correct for the arm R-07 pinned as a defect (prompt/command) and for an exec-unit child of a real, non-injected workflow run — all three reach the dispatched child's environment through an explicit value, never through inherited ambient state;
• (d) a pre-set, more-specific ambient AKM_EVENT_SOURCE still wins everywhere it won before — the explicit eventSource value is only ever a FALLBACK (process.env.AKM_EVENT_SOURCE ?? provenance.eventSource at each dispatch arm, and exec-unit.ts's childEnv applies its stamp only when the allowlisted-base collection left the name absent), so an already-present ambient value is never overwritten.

Verified end to end by tests/integration/tasks-provenance-characterization.test.ts's flipped P-05 rows (including a REAL, non-injected runWorkflowSteps → exec-unit child observing the stamp) and by tests/integration/tasks-provenance-context.test.ts's new RunTaskOptions.provenance coverage. No production change to P0 itself; this entry documents P1b Lane C's implementation of the flip P0's own R-07/P-05 rows named as pending.

2026-08-26 — P-05 reclassified by P1b (D5). P-05 pinned the workflow arm's global process.env.AKM_EVENT_SOURCE stamp-and-restore as then-current MECHANISM; the refactor plan always scheduled D5 to replace that mechanism with an explicit ExecutionProvenanceContext threaded through dispatch. P1b flipped P-05's mechanism-level assertions per its authorized-flips table; the preserved CONTRACT — in-process execution and usage recording observe "task", no cross-run leakage (the global is now never mutated: before, during, after), child-env stamping (P-06) unchanged, pre-set ambient values still win — is pinned by the amended tests/integration/tasks-provenance-characterization.test.ts and the new tasks-provenance-context.test.ts. R-07's defect (prompt arm recording scheduled usage as "user") is fixed as planned.

2026-08-26 — R-06 close-out: the replacement is scoped to task source v4, not a flip of the row itself (P2a, docs/plans/specs/p2a-task-source-v4.md §1.5 D2-N6, §6 F-0). The R-06 row's "Flips in" cell reads "P2a (optional schedule)"; that cell names the phase that introduces the first document shape the rule does not apply to, not a change to the rule task v3 itself pins. Task source v4 (version: 4) makes schedule: OPTIONAL — an absent schedule: parses as valid and projects to triggers = { manual: true, schedules: [] } (D2-N6) — but compileTriggers (src/tasks/source-v3.ts:450-464 as of this entry — :636-651 at the R-06 row's own "verified at head" commit, before P2a's D2-N4 extraction moved code within the file; same function, unchanged body) is untouched by P2a: a version: 3 document that declares neither akm.schedule nor on: (or declares both) still fails with the byte-identical message must declare exactly one scheduling source: akm.schedule or on., still via sourceError(ctx, [], …) with the empty path, and still with the three frozen-shape assertions on the akm.schedule success arm. All three of tests/integration/tasks-scheduling-characterization.test.ts's R-06 tests (the neither-case at :45, the both-case at :57, and the akm.schedule success shape at :73, including its Object.isFrozen assertions) pass unchanged after P2a — verified as part of P2a's preservation gates. R-06 therefore stands, unflipped, for every version: 3 document; only a version: 4 document gets the new, additive optional-scheduling row (B-06/B-07 in the P2a spec's behavior table). v3's exactly-one-scheduling-source rule stands until P4 removes v3 acceptance outright — this row should not be read as "replaced" in the sense of no longer holding for any document, only as "superseded for the one new document shape that did not exist before P2a."

2026-08-28 — P4 close-out (Lane C, docs/plans/specs/p4-deletions-closeout.md §5.5): final disposition of every R row, and of the P rows P4 supersedes. P4 is the last phase in the refactor ladder; the three deletion families (§3) and the vocabulary/documentation close-out (§4) are landed at Lane C's head. This entry appends §5.5's disposition table verbatim — no pinned row's text above is edited, this is prose-only closure:

Two dispositions above are worth flagging as observed, not merely asserted, at P4 Lane C's head: P-04's "stays pinned" held through §5.2's own INVALID_FLAG_VALUE re-coding sweep — the workflow- target env: guard's code was measured, found pinned by tests/integration/tasks-with-classification-characterization.test.ts's P-04 block, and left INVALID_FLAG_VALUE rather than recoded to COMPOSITION_INVALID as §5.2's generic target table would otherwise have applied, exactly as this table's row anticipates. R-08's "PRESERVE surface forever" held the same way against src/tasks/source/bounded-document.ts's six-throw front-end recode: the D8 legacy read mapping in src/tasks/run/task-history.ts was not among the sites touched, and its own byte-unchanged tests stayed green throughout.