dsh-compound-engineering 0.0.0-stage → 0.1.0

package/skills/ce-work/references/cross-model-execution.md

@@ -0,0 +1,191 @@
+# Cross-Model Execution Contract
+
+Read this reference only when `references/execution-engines.md` finds an applicable external route, or when you are recovering an existing external run. It defines how the host picks one fixed route, what authority the external worker gets, when native fallback is allowed, how requested and actual identity are kept apart, what the run record must contain, and how one unit moves through the controller one transaction at a time. The host drives the bundled controller, detached runner, and adapter; no worker response or process exit can substitute for controller and Git evidence.
+
+When this file records that the run leaves the host, that record is the egress: sending repository content, or the authority to change it, to an external process. When this file records a receipt, that is a fact the controller wrote, not something the worker or the host inferred.
+
+## Interpret route intent and standing configuration
+
+`references/execution-engines.md` decides whether an external route applies and which source has authority. This section turns that source into ordered candidates.
+
+A live request such as "use Codex" is preference-strength by default. Interpret unambiguous strict intent such as "must use Codex" or "only use Codex" as requirement-strength; intent is the contract, not any single keyword. The resolved mode is `prefer` or `require`. Requirement strength fixes the requested external identity while that route is viable; it never authorizes another external recipient and does not turn route unavailability into a blocker.
+
+Live or contextual intent may name one route or an ordered fallback list (for example, "prefer Cursor with Grok, then Codex"). Preserve that order and normalize each harness/model candidate with the same rules as standing configuration. A typed caller binding remains a single already-selected candidate; do not widen its exact four-field grammar into a list.
+
+Standing configuration uses one mode plus an ordered route list. Resolve `work_engine_mode` and `work_engine_preferences` independently from the two repo files (`config.local.yaml` then `config.yaml`); a present local list, including `[]`, replaces the team list. Do not pick one file for the whole group.
+
+```yaml
+work_engine_mode: prefer
+work_engine_preferences:
+  - harness: cursor
+    model: composer
+  - harness: codex
+    model: gpt-6.1-sol
+  - harness: claude
+work_engine_effort:
+  codex: xhigh
+  claude: max
+```
+
+- `work_engine_mode`: `off | prefer | require`
+- `work_engine_preferences`: one or more ordered candidate objects
+- `harness`: `codex | claude | grok | cursor | opencode | antigravity`
+- optional `model`: a model id or family understood by that harness; omission means its configured default
+- optional `work_engine_effort`: a map from harness to the reasoning effort its external worker runs at, written in that harness's own levels (Antigravity takes `low | medium | high`); a harness left out keeps its default
+
+Do not put CLI commands or flags in configuration. The list expresses implementation intent; the skill's adapter recipes and local inspection determine how to invoke it. Composer is therefore `{ harness: cursor, model: composer }`, while `{ harness: cursor }` means Cursor's configured default.
+
+Normalize a qualified candidate to the controller's fixed route: Codex -> `codex`, Claude -> `claude`, native Grok -> `grok-cli`, Cursor with no model -> `cursor`, a Composer-family Cursor model -> `composer`, a Grok-family Cursor model -> `grok-cursor`, another explicit Cursor model -> `cursor` with that controller-authorized model selector, OpenCode -> `opencode`, and Antigravity -> `antigravity`. A model selector is data, never shell syntax; if it cannot be represented by the fixed adapter's safe model token, the candidate is unavailable. A Cursor model selector is one of Cursor's own model ids, which may end in a bracketed preset such as `grok-4.7[context=256k,reasoning_effort=high,fast=true]`; record that id as the requested model, since Cursor routes take no separate effort. With no model pin, `grok-cursor` requests that high/fast Grok preset and `composer` requests `composer-2.5[fast=true]`. The `antigravity` route runs only `gemini-*` models, because Antigravity also serves other vendors' models. An Antigravity candidate with no model becomes two exact candidates in this order: `gemini-4-argon`, then `gemini-3.8-flash`. Accounts differ in which Gemini models they offer, and once `init` records a model the run cannot change it, so the preflight model check below settles which one runs. A configured Antigravity model stays exact like any other pin.
+
+`work_engine_effort` resolves on its own under the same two-file rule, and a present local map replaces the team map. It requests an effort for every candidate of that harness, including a candidate a caller binding or live intent selected, and it applies whatever `work_engine_mode` says. A candidate that cannot run at the effort requested for it is unavailable before any work is sent, the same as any other unavailable candidate, and nothing runs at a different effort than the one requested. The adapter script owns which levels each route accepts; ask it at preflight rather than judging the value yourself. A candidate that collapses to native execution runs at the session's own effort, so say that the configured effort was not applied. A value that is not a harness map requests nothing: say once that it was ignored and continue with each route's default.
+
+An enabled mode without a valid candidate list is unavailable rather than guessed. When the list is exhausted, both `prefer` and `require` disclose every attempted route and reason once, then continue natively on the current harness and session model. A required route is never replaced by another unrequested external recipient. Standing configuration supplies defaults, not permission to change recipient or broaden authority.
+
+## Resolve one requested route
+
+Use only these targets: `codex`, `claude`, `grok`, `cursor`, `composer`, `opencode`, and `antigravity`. Keep five identity facts separate in every disclosure and receipt: target, harness/intermediary route, requested model, actual model, and receipt status.
+
+**Fixed controller route tokens:** record exactly `codex`, `claude`, `grok-cli`, `cursor`, `composer`, `grok-cursor`, `opencode`, or `antigravity` in the egress record the controller stores. `grok-cli` maps target `grok` to its native harness; `grok-cursor` maps target `grok` through intermediary `cursor`. These controller tokens are exact values, not descriptive labels.
+
+- `cursor` means the Cursor harness with its configured default model.
+- `composer` means a Composer-family model through Cursor.
+- `grok` prefers its fixed native route; a Grok model through Cursor is a different intermediary and must be separately permitted and recorded.
+
+When a standing preference lists candidates in order, preflight them in that order without sending anything out. Skip a candidate only when its harness and requested/default model are equivalent to the current host, or when observed evidence shows it is unavailable. An explicit different model in the same harness is still a distinct candidate. After skipping a candidate, record why and continue to the next candidate. Attempt the documented adapter recipe first. Local CLI help or version information may refine a compatible mapping, but only inside the same sanctioned harness/model family and only if the fixed adapter still enforces every restriction. An explicit model pin cannot become another model. When `work_engine_effort` requests an effort for the candidate's harness, preflight also asks the adapter whether that route can run at it. The effort is data, never shell syntax, the same as a model selector: only a plain token that starts with a letter or digit and continues with letters, digits, `-`, or `_` may appear in a command, and any other value makes the candidate unavailable without running anything. Ask with this skill's bundled script by its absolute path under the skill directory, because it is not on `PATH`: `CROSS_MODEL_EFFORT_OVERRIDE='<token>' "<skill-dir>/scripts/cross-model-work.sh" --emit-adapter <route>`. Exit 2 naming the effort means the route cannot run at it, and the candidate is unavailable with that reason. A script that cannot be found or run is a broken preflight to report, not evidence about the route. For each `antigravity` candidate, also run `"<skill-dir>/scripts/cross-model-work.sh" --check-model antigravity <model>` before `init`. It opens an Antigravity session for that model and sends no prompt. Exit 0 means the account offers the model. Exit 2 means the candidate is unavailable, with the reason on stderr (for example, the models the account does offer, or a missing Google sign-in); continue to the next candidate. The first qualified candidate becomes the one fixed recipient.
+
+Every route reaches its agent through the pinned acpx, run with `npx`, so each needs Node 22.13 or newer, `npx`, and `jq` besides its own agent CLI. When one is missing, npm cannot fetch acpx, an acpx config file replaces the route's agent launch, or the agent rejects the model before the prompt, the adapter sends nothing and publishes an unavailable receipt whose reason starts `transport unavailable (pre-egress, `. Handle it like any other unavailable route.
+
+Before egress, you may keep moving down the list after a candidate is proven unavailable. After dispatch starts, the adapter receives one fixed recipient and must never switch recipients, providers, or intermediaries internally. A different recipient requires a separately resolved and recorded attempt, and only after the first attempt reaches an authoritative terminal or reaped state; it is never an in-flight fallback.
+
+Disclose any compatible model alias or substitution, and never relabel an unverified served model.
+
+If a target asks for the same-host default with no distinct serving route or model, collapse to native execution. Record the target as requested and native as actual; do not create an external job merely to call the current host's default model through itself.
+
+## Apply preference or requirement strength
+
+Cross-model implementation routes are write- and shell-capable. Never request broader host permissions merely to make one reachable. If the current host boundary makes a route unavailable, apply the native fallback for its resolved mode instead of escaping that boundary.
+
+**Preference-strength (`prefer`):** attempt the fixed route in both direct and automatic workflows. If preflight proves it unavailable, continue with native execution and prominently report requested versus actual route/model plus the observed `fallback_reason`.
+
+**Requirement-strength (`require`):** keep the requested external identity fixed while the route is viable. If preflight proves it unavailable, disclose the reason once and continue on the current harness and session model without prompting, erroring, elevating the host boundary, or substituting another external recipient. A started attempt is not preflight-unavailable: no fallback begins until it reaches an authoritative terminal or reaped state.
+
+## Sanction before egress
+
+Before repository content or bounded mutation authority leaves the host, disclose and durably record:
+
+- the binding `source` that authorizes external execution;
+- the fixed recipient, provider, harness route, and every intermediary;
+- the repository/unit material exposed, including the bounded source/unit packet and workspace content;
+- the caller restrictions and which are adapter-enforced versus cooperative; and
+- that linked worktree isolation contains accidental concurrent mutation but is not an OS security sandbox.
+
+Treat a required restriction the adapter cannot enforce as route unavailable; apply `prefer` or `require` instead of weakening it silently. This record is route-specific.
+
+No route currently confines the worker to its workspace, so every route records `restriction_posture: cooperative`, and a run that requires enforced confinement finds every route unavailable. The worker runs with every permission request approved, as the same OS user. What each route still limits, observed through acpx 0.19.4:
+
+| Route | Limits that hold |
+|---|---|
+| `codex` | Shell commands run in Codex's `workspace-write` sandbox: no network, `.git` read-only, no writes outside the workspace and temp dirs. Codex's own auto-review can still approve a file edit outside the workspace. |
+| `grok-cli` | File edits through acpx stay inside the workspace. Shell commands are unconfined. |
+| `claude` | None beyond the packet. It runs with `--safe-mode`, so the checkout's project settings and hooks do not apply. |
+| `cursor`, `composer`, `grok-cursor`, `opencode` | None beyond the packet. |
+| `antigravity` | None beyond the packet. It runs in Antigravity's `auto_edit` mode with a private settings home, so the user's own Antigravity or Gemini settings, skills, and API keys do not apply. |
+
+Any retry that changes a recipient or intermediary requires a newly resolved and recorded job.
+
+## Bound worker authority
+
+The worker receives one unit, one workspace, one fixed recipient, and only inherited authority. It may narrow scope or authority, never broaden either. Its packet grants no canonical commit, push, PR, shipping, recipient-switch, fallback, peer scheduling, or scope-expansion authority.
+
+An external worker may edit only inside its controller-owned detached worktree. Do not instruct it to run `git add`, `git commit`, or another Git index write. Leave the completed working tree uncommitted; the host snapshots the tree. Codex's `workspace-write` shell sandbox cannot write the linked-worktree Git admin dir, because the index lives in the shared Git common dir outside the workspace. Worker commits are never required. When the worker finishes, the controller turns the complete working tree into an isolated transport commit for the host to inspect. Only the host may apply output to the canonical checkout, run authoritative verification, create a host-only canonical commit, or continue into the shipping steps that follow implementation, whether `ce-work` runs those itself or returns them to a caller.
+
+A Codex `workspace-write` packet must also treat socket binds, OS permission checks, and peer-credential probes as host-owned. Preserve the host command and observed result; do not treat a sandbox `EPERM` as proof the host lacks the capability.
+
+Ordinary synchronous native units stay in the active checkout. Ordinary native subagent isolation remains harness-owned. Only the external cross-model controller may create detached sibling worktrees under its private run root; this exception does not authorize `ce-work` to create worktrees for native execution. An active checkout that is already a linked worktree does not disable this route: the controller registers another detached **sibling** through the shared Git common directory under `/tmp/compound-engineering-<effective-uid>/ce-work/<run-id>/`, never a nested worktree beneath the active checkout.
+
+## Preserve route and lifecycle receipts
+
+Direct runs and return-to-caller runs record the same facts, even though what they say to the user and what shipping steps follow differ:
+
+- `implementation_engine_binding`: resolved `mode`, `target`, `model`, and `source`;
+- `requested_route` and `actual_route`, including every intermediary;
+- `requested_model`, `actual_model`, and served-model receipt status;
+- `requested_effort` or `null`; served effort is never verified, so report it as `unverified`;
+- `fallback_reason` or `null`;
+- `source_kind` (`plan` or `prompt`) and its controller-recorded digest;
+- `run_id` and per-unit `unit_receipts` that distinguish process terminal state, integration, authoritative verification, host canonical commit, and cleanup;
+- `plan_checkpoint`: a disclosed host commit only when the resolved selected plan was the sole canonical dirt;
+- `blockers`; and
+- `recovery_path` for preserved inspectable state.
+
+Never infer success from detached-process completion alone. The run receipt is complete only after every required unit reaches its host-owned canonical state. A plan-only checkpoint is disclosed to the direct user or returned to an automatic caller; unrelated dirt never receives an implicit checkpoint and instead makes the external route unavailable.
+
+## Build a source for bare-prompt work
+
+A formal plan is not required when Phase 0 (Input Triage) has already judged a bare prompt concrete enough to execute. Before controller initialization, write one bounded implementation brief directly to OS temp outside the repository. The brief is a distilled statement of what the worker is allowed to do, not a transcript: never include raw conversation history, unrelated session context, credentials, or speculative scope.
+
+Populate these headings with concrete evidence from the request and Phase 0 discovery:
+
+- `Request` — the current implementation request, paraphrased only to remove unrelated conversation;
+- `Goal` — one observable outcome;
+- `Scope` — expected files or areas of the code, and discovered patterns/tests;
+- `Acceptance and verification` — behavior and authoritative checks that prove completion;
+- `Constraints and exclusions` — inherited restrictions, non-goals, and unresolved boundaries; and
+- `Units` — use one conservative `P1` unit by default; create more only when discovery establishes distinct goals, dependencies, expected files, and verification without guessing.
+
+If any of Goal, bounded Scope, or Acceptance and verification cannot be populated, do not initialize the controller or send anything out. Return to Phase 0 clarification or planning. Compute the brief's SHA-256, call controller `init` with `--prompt-brief <temp-path> --prompt-digest <sha256>`, and use the controller-owned private copy and digest thereafter. The caller's temp path is never authoritative after initialization. Invocation origin does not change this contract.
+
+## Serial external-unit protocol
+
+Run this protocol from the host checkout for one ready unit at a time. Resolve each bundled script from this skill's directory. The host remains the orchestrator throughout; the external CLI only authors the bounded unit. Use `git -C <canonical-checkout>` for every host Git operation; never rely on the shell's current directory after resolving or running a bundled script.
+
+**Visibility and stop invariant:** use separate host tool calls and invoke only one state-changing controller transition per call until terminal scope inspection. Never generate or run a shell script that spans `start` through waiting or integration, spans multiple units, loops over the external runtime, or conditionally continues into another transition. `start` must return before supervision. Cap each runner wait at 60 seconds, then sync and publish progress in later host tool calls. After scope inspection, use the controller's single fail-stop `integrate` transaction; do not manually chain its internal Git/controller transitions. A nonzero controller, runner, verification, or Git exit ends that host tool call; inspect controller status and enter its prescribed restoration or recovery path before any later transition.
+
+When set, `CE_WORK_RUNS_ROOT` is the parent CE Work directory containing all `<run-id>/` directories, not an individual run directory.
+
+1. **Resolve, preflight, and sanction.** Apply the authority-and-scope resolution in `execution-engines.md`. For an ordered standing preference, skip a candidate equivalent to the current host and preflight each remaining candidate until the first qualifies; record every rejected candidate and reason. Verify the fixed adapter and caller restrictions, then disclose the authorizing source, the route and its intermediaries, the material exposed, and which restrictions are enforced versus cooperative. The controller `init` egress object uses the exact plural keys `route`, `intermediaries`, and `restrictions`: direct `codex`, `claude`, `grok-cli`, `cursor`, `opencode`, and `antigravity` routes use `intermediaries: []`, while `composer` and `grok-cursor` use `intermediaries: ["cursor"]`. When an effort was requested for the fixed recipient, add it to that egress object as `effort` and name it in the disclosure. The controller records it at `init` and writes it into every attempt's authorization, so each unit, retry, and resume of the run uses the recorded value; do not resolve it again from config after `init`. If all candidates are unavailable, both `prefer` and `require` disclose the attempted routes and reasons once, then continue natively on the current harness and session model without starting an external controller run.
+2. **Establish the durable source and clean canonical state.** Initialize the private run with `unit-workspace.py` `init`; the controller creates `/tmp/compound-engineering-<effective-uid>/ce-work/<run-id>` itself (under `$TMPDIR/compound-engineering-<effective-uid>/` instead when `/tmp` cannot host a writable private root, as in a sandbox that only allowlists `$TMPDIR`; `unit-workspace.py` resolves that itself). Do not pre-create the run directory. For a repository plan, pass `--plan <path> --plan-digest <sha256>`; the selected plan may be the only dirty path, and `unit-workspace.py` `checkpoint-plan` records that exact plan-only checkpoint. That exact plan-only state is checkpointable, not a route blocker. For a bounded prompt brief, pass `--prompt-brief <temp-path> --prompt-digest <sha256>`; the controller copies it into private run state, and the canonical checkout must already be clean because no repository source is eligible for checkpointing. Only checkpoint failure or unrelated dirt makes the route unavailable. Re-read canonical repository, branch, HEAD, source kind/digest, and cleanliness before preparing a unit.
+   Once `init` returns `READY`, the engine decision is closed for that unit. The next implementation path is `prepare` then the fixed-author start, or a blocker that preserves the returned recovery path. Expected latency, orchestration cost, or a later judgment that native work would be simpler is not route unavailability and never authorizes canonical writes. Native implementation becomes eligible only through the controller's `claim-fallback` check described later under "Resume and fallback exactly once".
+3. **Prepare one bounded unit packet.** For a plan, include only the Goal Capsule, Definition of Done, active unit, relevant Verification Contract rows, cited R/F/AE/KTD excerpts, any Product Contract Key Decision whose exact `Governs R…` links name the active unit's cited R-IDs, inherited restrictions, expected files, evidence strategy, and explicit exclusions. For a prompt brief, include only the matching P-unit's Goal, Scope, Acceptance and verification, Constraints and exclusions, expected files, and evidence strategy. Do not expose the whole plan, prompt brief, or conversation by default. Write the packet source directly to OS temp outside the canonical checkout, such as a source file beneath the controller-returned recovery path; never draft it inside the repository and move or copy it later. Call `unit-workspace.py` `prepare` with that packet source path, unit id, recorded base, dependencies, wave fields, and the activity kind the route qualifies for (`incremental` or `hard-only`). Every route streams its ACP session, so `incremental` is the default. Use only the controller-returned `attempt_id`, controller-owned `packet_path`, and computed `packet_digest` for dispatch; never substitute the caller's source path, a caller-computed digest, or an assumed attempt name.
+   `prepare` refuses only on unrelated dirt or a moved HEAD; the size and shape of the canonical checkout's git-ignored inventory (installed dependencies, virtualenvs, build caches, symlinks) never make the route unavailable.
+4. **Start one fixed author.** The controller-issued authorization schema binds `run_id`, `unit_id`, and `attempt_id` to the fixed route/model/intermediary and packet contract. Call `peer-job-runner.py` `start --no-sweep --input-digest <controller-packet-digest>` with skill `ce-work`; the runner label must equal the unit id exactly, without the attempt id or another suffix, and `--result-path` must be `<controller-result-dir>/implementation-result.json`. Both `--input-digest` and the adapter's expected-packet argument must use the exact `packet_digest` returned by `prepare`; omitting the runner flag or recomputing/substituting either value makes the job ineligible for `record-job`. The runner and controller share the same root automatically: `CE_WORK_RUNS_ROOT` wins when set, otherwise both derive CE Work state from `CE_PEER_JOBS_ROOT`. Set `CE_PEER_HARD_SECS=7200` on every production CE Work runner start rather than relying on the shared runner default. Set `CE_PEER_IDLE_SECS=600` for route-qualified `incremental` activity and `CE_PEER_IDLE_SECS=0` for `hard-only` or otherwise untrustworthy activity. The 600-second window resets on progress and detects a stall; it is not a wall-clock maximum. Its production worker command is `cross-model-work.sh <authorization_path> <workspace> <unit-packet> <expected-packet-sha256> <result-dir>`; invoke the returned adapter path directly as the first worker argv, without a `bash`, `sh`, or `env` prefix, and pass only the controller-returned `authorization_path`, never a caller-supplied route string or an ambient model or effort override. The runner exports its controller-visible job id to the worker. Before prompt construction or external CLI start, the adapter must pass that runner-exported job id and obtain controller `authorize-dispatch` success by calling `unit-workspace.py` `authorize-dispatch`. That success reads the actual runner metadata and exact worker argv, rejecting a shell prefix or substituted adapter before anything is sent out, then atomically binds that job id to the exact attempt before egress along with the authorization digest, workspace, packet path and digest, and result directory while revalidating the controller-owned exact route, model, and intermediary contract. A second job for the attempt is refused. A missing or refused handshake, including hand-authored or cross-attempt authorization, means nothing is sent out. Model pins and the requested effort come only from the authorized projection. The adapter's `--emit-adapter` mode remains introspection only and never authorizes production dispatch. Capture the returned job id immediately with `unit-workspace.py` `record-job`, using the controller-returned `attempt_id` verbatim; this idempotently confirms the same validated binding. Never hold one host tool call open for the external runtime and never let the adapter select another recipient.
+5. **Observe without steering.** Interleave runner `status --skill ce-work` or `wait --skill ce-work --max-secs 60` calls with separate `unit-workspace.py` `sync-job` calls; every bare-job-id runner `status`, `wait`, `result`, or `reap` call must carry `--skill ce-work` under the same `CE_WORK_RUNS_ROOT` / `CE_PEER_JOBS_ROOT` selection used at start. Report unit, route, elapsed time, latest meaningful activity, the activity kind in effect, and terminal state after each cycle. When a unit's activity cannot be trusted to show progress within the idle window, `hard-only` is the normal posture: disable idle timeout, retain the universal hard cap, and never infer failure or fallback merely from absent incremental activity. A live or temporarily unreachable attempt is still authoritative: do not start fallback or duplicate work. Reap only through the explicit controller/runner path and retain its workspace.
+6. **Terminalize complete Git output.** On authoritative `done`, call `unit-workspace.py` `terminalize`. Require its pinned synthetic transport commit to have the recorded base as sole parent and the complete final workspace tree. In a later host call, inspect the actual transport diff, changed paths, binary/mode/rename/delete evidence, adapter result, packet expected scope, and any scope-expansion request. A generated byproduct or any unexplained difference between actual transport paths, expected scope, and the worker's evidence is unexpected scope: preserve it for host resolution and do not take the integration lock.
+7. **Integrate through the fail-stop controller transaction.** After the separate scope-inspection call accepts the complete transport, invoke `unit-workspace.py integrate --run-id <run-id> --unit-id <unit-id> --commit-message <message> --verification-summary <summary> [--allowed-head <recorded-head>] -- <verification-command-and-argv>`. Pass a simple Verification Contract command as direct argv. If it contains shell syntax such as `$(...)`, a pipe, `&&`, a redirect, or a glob, invoke an explicit shell with pipe-failure handling on the first attempt, for example `-- bash -o pipefail -c 'test "$(cat delegated.txt)" = "expected"'`; quoting `$(...)` as a direct argument does not expand it. Do not manually chain or conditionally reproduce this transaction.
+8. **Let `integrate` perform every canonical change.** It performs `unit-workspace.py` `integration-acquire`, `unit-workspace.py` `preflight`, `git cherry-pick --no-commit`, `unit-workspace.py` `mark-applied`, authoritative canonical verification with Python bytecode disabled, exact canonical-state reconciliation, `unit-workspace.py` `mark-verified`, one host-owned commit, and `unit-workspace.py` `mark-committed`. For a wave it also records `wave-advance`; after a reconciled commit it performs `unit-workspace.py` `cleanup` and `unit-workspace.py` `integration-release`.
+9. **Treat its outcome as authoritative.** Capture the authoritative command's exit status directly; never infer a pass from stdout. Any change to tracked state — HEAD, branch, index, or status-visible paths — fails reconciliation. Git-ignored state is not part of that proof. The controller inventories ignored entries by metadata before and after verification and discloses `changed`, `removed`, and `created` counts with a bounded path sample as `ignored_state` in every verification receipt and return body. It never copies, restores, or deletes ignored files, so a verification command that mutates a cache or a local database changes only what native units already could. Ignored files the command creates stay in place. Empty ignored directories are not inventoried. `.env`-class files and local databases receive no protection from a misbehaving verification command. Verification and clean-state reconciliation happen before `mark-verified`. A rejected verification or a failed pre-commit controller/Git step forbids the commit, calls `unit-workspace.py` `restore`, proves exact pre-fold equality, and releases the lock before fallback, retry, or another unit. If exact restoration cannot be proven, it retains the lock, workspace, transport ref, and recovery path. A crash after the canonical commit remains resumable evidence and must not be redispatched.
+10. **Run the source-wide checks through the controller.** After every external unit is committed and cleaned, invoke `unit-workspace.py verify-run --run-id <run-id> --verification-summary <summary> -- <verification-command-and-argv>` for the plan-wide Verification Contract gates or the prompt brief's authoritative checks. Do not run those final commands directly in the canonical checkout or hide their status behind a later command. `verify-run` starts only from a clean canonical snapshot, captures the command's exit status directly with Python bytecode disabled, restores tracked state to the exact starting snapshot, discloses ignored-state divergence as `ignored_state` per step 9, and records a durable receipt. A failing check retains its private log and blocks the return to the caller or the shipping steps even after cleanup succeeds.
+
+Report every transition in the direct commentary or in the structured return to the caller: resolved source kind, route, plan checkpoint when applicable, dispatch, activity, terminal result, transport/scope inspection, integration, restoration if any, authoritative verification, canonical commit, cleanup, blocker, and recovery path. The serial protocol does not authorize parallel waves or automatic redispatch; those require the checks in the next two sections.
+
+## Parallel external-wave protocol
+
+Use a wave only after the always-loaded Parallel Safety Check proves the ready units independent across dependencies, declared files, shared contracts/interfaces, migrations, lockfiles, generated, registry, or config files, environment singletons, and expected merge cost. Uncertainty selects serial execution. The host stays the scheduler: workers cannot add peers, broaden the wave, or change their own dependencies. Cap the wave at 3-5 workers.
+
+1. Record one wave id, dependency order, and **one recorded wave base** from a clean canonical checkout. Prepare every member from that same base with distinct controller-owned workspaces. Synchronous native work remains in the active checkout; every concurrent worker is isolated.
+2. Start the fixed-route jobs concurrently, observe them without steering, and terminalize every worker into its base-parented synthetic transport commit **before the first fold-in**. If any worker has not terminalized, integrate none. Inspect all actual transport inventories before mutation; same-path changes stop the wave, while shared-interface or other semantic contention returns to host resolution even when paths differ.
+3. Integrate results sequentially in dependency order under the canonical integration lock. The first unit preflights against the wave base. A clean textual apply is not semantic compatibility: inspect scope, run that unit's authoritative verification against the advancing canonical tree, and create one host-owned canonical commit.
+4. While that unit's lock is still held, call `unit-workspace.py` `wave-advance` with its exact recorded canonical commit. The controller accepts only the manifest-confirmed commit whose parent is the recorded pre-fold HEAD, then adds it to later siblings as one of the **exact earlier host-owned canonical commits**. Clean and release the completed unit before acquiring the next sibling's lock.
+5. For each later result, pass only the current exact recorded wave commit to `preflight`. Unknown HEAD movement blocks. Even when three-way application is clean, repeat actual-scope inspection, semantic revalidation, authoritative verification, and a separate host commit. A transport commit is never merged or committed directly.
+6. Conflict, scope expansion, semantic collision, test failure, or commit failure enters the serial protocol's exact restoration while the lock remains held. No sibling, retry, or fallback starts until restoration is proven and the lock is released; affected dependents remain queued. After readiness is recomputed, unaffected siblings may continue. The affected unit requires explicit host resolution, re-dispatch on the new base, or serial fallback; never blind-merge a colliding or stale result.
+7. Repeated collision, broad unplanned edits, or inability to prove exact restoration disables more waves for the run. Preserve inspectable workspaces and refs; failure of one unit does not discard an unaffected sibling, but it never authorizes a dependent unit early.
+
+## Resume and fallback exactly once
+
+When the caller supplies a run id directly or through return-to-caller `implementation_run:<safe-id>`, use `unit-workspace.py` `resume --run-id <id>` and treat that id as authoritative. This recovery step happens before ordinary input classification and must not dispatch new work. Without a supplied run id, a plan-backed run must use `resume --repo <canonical-checkout> --plan-digest <selected-plan-digest>` for discovery; never infer or select a run id by listing the shared run root. Prompt-backed runs require their disclosed run id; do not rediscover them from conversation text or a caller temp path. Resume only a single unfinished plan-backed run matching repository identity, branch, and plan digest; if several match, list the matching run ids and recovery paths and block selection rather than choosing one. Do not dispatch a new third run while matching unfinished state remains ambiguous. An unsafe or foreign-mode manifest is a blocker, not a candidate to skip.
+
+When all units are terminal (`cleaned` or `native-completed`) and a successful plan-wide verification receipt already exists, the completed run is observation-only. Build the structured return from the manifest and stored receipts; recovery must not rerun a Verification Contract gate, call `verify-run`, or execute test/build/format/install/generation commands merely to reconfirm completed evidence. A missing required receipt is a reported recovery blocker, not permission to improvise a loose verification step.
+
+Resume reconciles durable evidence, but must not redispatch, reapply, recommit, or run either owning tail (the standalone shipping steps or the caller's). It may adopt exactly one matching unbound runner job, monitor a recorded live job, terminalize authoritative `done` output, continue an interrupted exact restoration, or record a verified canonical commit whose parent and tree match the pre-fold evidence. A transport ref written before its manifest row is reusable only when its sole parent and final tree match. Preflight records the expected post-apply tree and changed-path set: an exact match may reconcile an apply that landed before its manifest row, while unknown dirt blocks without destructive restoration.
+
+Use the controller's `status`, `reap`, and `cleanup` operations for preserved work. Loss of contact leaves a recorded job live until runner evidence becomes terminal or an explicit reap records termination. Cleanup is idempotent after an interrupted worktree removal. Explicit abandonment requires the exact transport SHA, or the exact terminal job id when a failed/reaped attempt produced no transport.
+
+After exact restoration, exact abandonment cleanup, and integration-lock release, re-dispatch a corrected unit under the same scalar `run_id` by calling `prepare` with a fresh `attempt_id`. Preserve the earlier attempt receipts; do not mint another run id or represent one logical run as a list of run ids. The controller refuses a retry that changes the unit's recorded dependency or wave/base contract.
+
+Post-start fallback is a separate atomic check. After authoritative failure, timeout, `died-without-result`, or exact restoration and lock release, disclose the unavailable route once and call `unit-workspace.py` `claim-fallback` before native implementation. The first `prefer` or `require` claim authorizes exactly one fallback on the current harness and session model; `FALLBACK_ALREADY_AUTHORIZED` means do not start it again. Requirement strength prevents external recipient substitution while the route is viable, but never turns an unavailable route into an error or user-choice gate. A live job or successful unreconciled output refuses the claim. If integration began, no retry, sibling, or fallback claim is eligible until exact restoration is recorded and the canonical checkout still equals that snapshot. After the claimed native implementation is committed and locally verified, call `unit-workspace.py` `complete-fallback` with the accepted HEAD, a SHA-256 digest of the local verification evidence, and a bounded summary; both `prefer` and `require` claims can complete. `FALLBACK_COMPLETED` closes that unit only. Once every unit is terminal, run the plan-wide Verification Contract through `verify-run`; do not report the run complete until the controller returns `RUN_VERIFIED` and stores its successful receipt.
+
+## Preserve tail ownership
+
+The engine changes only who writes the implementation. A standalone invocation resumes `ce-work`'s quality and shipping workflow after local implementation. `mode:return-to-caller` returns implementation and local-verification receipts with `standalone_shipping_skipped: true`; it never runs the simplify, review, PR, or CI steps that belong to the caller. External workers never inherit either set of shipping steps.
+
+**A successful controller `init` locks that unit to the selected cross-model engine.** From that point, advance it through this controller protocol or return blocked with its recovery path. Never reclassify it as trivial, abandon it for speed, or implement it natively unless the protocol later returns an explicit fallback authorization.

package/skills/ce-work/references/execution-engines.md

@@ -0,0 +1,64 @@
+# Execution Engines
+
+`ce-work` has two implementation engines: native execution (inline or subagents, scheduled by `references/execution-strategy.md`) and cross-model execution. The engine decides who authors the code. It never changes who runs the finishing steps (final simplify, review, PR, and CI; see "Resume the correct tail" below). Native execution is the default: it stays selected unless applicable live intent, a caller binding, or an enabled standing preference selects cross-model execution.
+
+Engine selection applies only to code execution. Knowledge-work keeps its carve-out. Legacy plans and bare code prompts may select cross-model execution; otherwise they use the inline/subagent flow in `references/execution-strategy.md`.
+
+Invocation origin supplies no routing authority and may not be detectable. Resolve the same inputs whether `ce-work` was explicitly invoked or selected by the host: current-task intent, still-active session intent, typed caller binding, active project instructions, enabled checkout configuration, then native execution.
+
+## Decide whether an external route applies
+
+Resolve one implementation binding from applicable authority and scope; do not reduce routing to keyword matching or a closed state machine. Obey the host's instruction hierarchy first. Within the same authority, prefer narrower and more current intent, using these sources:
+
+1. an explicit assignment or constraint in the current task;
+2. a still-active session preference or constraint;
+3. a typed caller binding at its recorded provenance (for example, an LFG current-task assignment keeps current-task authority when it reaches `ce-work`);
+4. the project's active instructions and conventions already in context;
+5. enabled per-checkout configuration; then
+6. native execution.
+
+Lower sources may fill an unspecified detail but cannot contradict or broaden a higher source. Incidental mentions in feature prose, quoted material, examples, comparisons, filenames, or discussion do not activate routing. If two applicable instructions of equal authority genuinely conflict on which external worker receives the work, or on whether work leaves the host at all, tell the user about the conflict instead of guessing.
+
+For example, current-task strict Composer resolves to Composer with `require` even when a caller Codex binding and config Cursor preference are both present. Without that task instruction, a caller Codex binding sourced from the current LFG task keeps that provenance. Without applicable live or caller intent, the ordered config candidates apply only when standing mode is enabled.
+
+### Typed caller binding
+
+Input triage passes only a fully validated and normalized typed caller binding. Treat it as one already-selected candidate; preserve its caller-visible provenance in the durable run record and never send its fields into planning or review input. Downstream consumers and workers may narrow its authority or restrictions but never broaden them.
+
+A validated recovery run id selects durable state. It never authorizes a fresh dispatch or a different route.
+
+### Standing configuration
+
+<!-- ce-config-layers:start -->
+**Resolve ordinary CE yaml keys from the two repo files.**
+
+- **Read** `<repo-root>/.compound-engineering/config.local.yaml`, then `config.yaml` (`<repo-root>` = `git rev-parse --show-toplevel`). Missing files are skipped. Gitignore does not change resolution.
+- **Win** with the first active (non-commented) value. For scalars, empty is unset; an invalid value continues to the next layer, then the skill default. For lists and maps, a present key — including an empty list or map — replaces the whole key.
+- **Do not** use this rule for `docs_root` — that key is `config.yaml` only.
+<!-- ce-config-layers:end -->
+
+
+
+Standing configuration selects cross-model execution only when `work_engine_mode` resolves to `prefer` or `require` (`off | prefer | require`) from the two repo files, `config.local.yaml` then `config.yaml`. `off` disables only the standing preference. It does not cancel applicable live intent or a typed caller binding.
+
+When no source applies, run native execution and do not load the cross-model reference. When one does, read `references/cross-model-execution.md` and resolve the route there before any content or authority leaves the host. It owns route strength, the target vocabulary, the `work_engine_preferences` and `work_engine_effort` schema, candidate traversal, and preflight. If no candidate qualifies there, continue natively as that reference directs.
+
+For a bare prompt, cross-model execution is eligible only after Phase 0 has established a concrete goal, bounded scope, and authoritative verification. The cross-model reference turns that discovery into a private prompt brief and conservative P-unit packet. An unclear bare prompt returns to clarification or planning before any work is sent to an external worker; it does not fall through to a smarter external worker and ask that worker to invent the scope.
+
+## Run the chosen engine
+
+- **Native:** follow `references/execution-strategy.md` for scheduling and dispatch, and the Phase 2 loop in `references/implementation-loop.md`. `ce-work` creates the tasks, orders the units, dispatches, verifies, and commits.
+- **Cross-model:** follow the serial external-unit transaction in `references/cross-model-execution.md` through the bundled controller, detached runner, and fixed adapter. Never let the detached worker select a fallback recipient.
+
+## Resume the correct tail
+
+After either engine finishes implementation, inspect the diff and continue with the finishing steps that belong to whoever owns them. On its own, an engine does no more than implementation and local verification.
+
+| Mode | After implementation, `ce-work` ... |
+|---|---|
+| **Standalone** (user invoked `ce-work` directly, or `ce-plan` handed off interactively) | Resumes its Phase 3-4 finishing steps: quality checks, simplification, review, commit, and handoff in `references/shipping-workflow.md`. |
+| **Return-to-caller** (`mode:return-to-caller`, e.g. under `lfg`) | Performs implementation and local verification only, then returns the structured summary in `references/return-to-caller.md` (`standalone_shipping_skipped: true`). Does not run simplify/review/PR/CI; the caller runs those. |
+
+## Progress visibility (independent of tail ownership)
+
+Whoever runs the finishing steps opens the PR. During a long run, commit each completed unit so progress stays observable in git. In return-to-caller mode `ce-work` must not open any PR, but it may commit and report progress in its structured summary. Never write progress or status into the plan body; git, commits, and the returned summary carry it.

package/skills/ce-work/references/execution-strategy.md

@@ -0,0 +1,73 @@
+# Execution Strategy and Native Dispatch
+
+Read this after the engine is resolved and before dispatching any worker or scheduling a parallel wave. `SKILL.md` resolves the route and enforces the checks on in-progress files and writes; the reference for the selected engine holds any engine-specific lock. This file describes how native work is scheduled, packaged, dispatched, and integrated.
+
+For the inline/subagent engine, **run each dependency layer's independent units together as a parallel wave of fresh workers.** This is the default, not an optimization to opt into: a wave spends more tokens than inline work in exchange for finishing sooner, and that is the intended trade. Serialize writes only where the dependency graph actually demands it, and only for the specific units that demand it. Let the plan's `Dependencies` and `Files` drive batching: run an independent dependency layer together, then the next. Serializing a whole plan is justified only by a genuinely linear dependency chain, or by units that can neither meet the shared-workspace wave contract below nor obtain an isolated workspace. Blanket caution never justifies it.
+
+A unit that must run in sequence gains no time from a worker, so run it inline in this context. Give a sequential unit a fresh worker only when this context is crowded enough that a clean window would materially help that unit.
+
+| Strategy | When to use |
+|----------|-------------|
+| **Inline** | Trivial work (1-2 files, no real decomposition), units the dependency graph chains, work needing user interaction mid-flight, or bare prompts that lack structured units |
+| **Parallel subagents** | The default for structured multi-unit plans: dispatch each dependency layer's independent units (per the Parallel Safety Check) together, then the next layer — in harness-isolated workspaces, or in the shared workspace under the wave contract below |
+| **Serial subagents** | A chained unit when this context is crowded enough that a fresh window would materially help it. Fresh context per unit, executed in dependency order |
+
+**Parallel Safety Check**: scheduling is separate from engine and workspace selection. Apply this check to native and cross-model candidates before dispatching a wave:
+
+1. Start only with units whose dependencies are already committed and whose peers in the same readiness layer do not depend on one another.
+2. Map declared files to units from each candidate's `Files:` section, then reason beyond those declarations. File overlap is necessary but not sufficient: shared types/APIs/interfaces, migrations, lockfiles, generated artifacts/clients, registry or config/schema surfaces, and an environment singleton (one dev server/port, shared database, browser session, package install, or rate limit) all create contention.
+3. Estimate expected merge and verification cost. Even isolated workers serialize when they share a contract or when reconciling their likely outputs is not obviously smaller and safer than serial authoring.
+4. Dispatch together only when dependencies, declared files, semantic surfaces, runtime resources, and expected merge cost all support independence. Resolve uncertainty by inspection, not by default: read the actual files and contracts in question; minutes of reading is cheaper than hours of serial waiting. When contention survives inspection, **decline parallelism** for exactly the contending units and dispatch the rest of the layer in parallel. Uncertainty about one unit never serializes its whole layer. Safety still beats speed for the units that genuinely contend.
+5. Give every concurrent worker either an isolated workspace or membership in a shared-workspace wave that meets the wave contract below. A synchronous native unit stays in the active checkout.
+6. Cap concurrency at a bounded batch (~3-5 workers), even when more units appear independent.
+7. Weigh the cold-start cost before decomposing: every dispatched worker pays a context ramp-up before its first write. A unit too small to outweigh its own ramp-up belongs batched with related small units into one worker's packet, or done inline, rather than dispatched alone.
+8. Abort criteria: broad unplanned edits, semantic overlap, out-of-scope failures, or repeated collision disables further waves; preserve or finish affected work serially.
+
+Isolation for native workers is the harness's job, within the boundary `SKILL.md` sets. Probe what your native subagent mechanism provides and pick the parallel path:
+- **Harness-native isolated workers**: each worker edits an isolated workspace the harness manages, for example Claude Code `Agent` with worktree isolation, or a harness worker capability whose result confirms an isolated workspace. Being already inside a worktree does not block this route (harness-managed worktrees are peers, not nested). But a harness-supplied workspace is not automatically a faithful snapshot of your tree: when the session itself runs inside a managed worktree, the harness may cut the copy from the primary checkout or its default branch instead (observed live), and uncommitted state never survives isolation. So dispatch each isolated worker with the intended base commit SHA. Before editing, the worker verifies its copy's `HEAD` equals that SHA, and on mismatch stops and reports rather than proceeding; the orchestrator then runs that unit on the shared workspace under the wave contract or serially. A unit that depends on uncommitted state cannot use this route. Parallelize only units that pass the Safety Check; isolation makes recovery possible, not overlap safe.
+- **Shared workspace only**: subagents edit your working directory. Dispatch a parallel wave only when it meets the shared-workspace wave contract below; units that cannot meet it run serially. Do not infer isolation from the presence of a subagent API; use only a capability the active harness actually exposes.
+- **No subagent mechanism:** run inline.
+
+**Dispatch a wave in one response.** When a dependency layer clears the Safety Check, first privately list every dispatch-ready unit; then issue every worker dispatch that doesn't depend on another's result in that one response — multiple dispatch tool calls in a single message (e.g. Claude Code `Agent` calls), never one per turn.
+
+**Native dispatch (inline/subagent engines only)** uses your harness's subagent/worker mechanism. Once a unit is selected for cross-model execution, use the loaded controller protocol for that unit; it must not re-enter this ordinary subagent dispatch.
+
+A generic subagent is one whose whole brief is the prompt you send it. When the host's subagent tool makes you name an agent, use only a name you have seen the host list, and list its agents before the first dispatch if you have not. Pick the plain one that adds no role of its own, which still counts as a generic subagent. Never pick a specialist, such as a reviewer or worker agent, whose own role prompt, output format, or tool limits would replace or narrow your prompt.
+
+Classify a rejected native dispatch by whether a worker launched: correct a pre-launch argument rejection once, leave capacity-limited work queued, and if another launch failure survives correction, execute that unit inline under the same unit packet and verification contract.
+
+**Fresh worker invariant (native subagent dispatch only):** When dispatching an implementation unit to a native subagent worker, create a new worker context with no prior implementation-unit transcript. Bind the worker handle to exactly that unit: it may continue or recover the same unit, but never receive a different unit. Retire each handle after its unit is integrated; never retask it or retain idle implementation workers for reuse. Invoke an explicit close/release operation only when the active harness exposes one and assigns that lifecycle action to the caller; otherwise completion is the worker's release boundary. Inline execution creates no worker context or handle, so it has nothing to retire.
+
+Give each native worker:
+- The plan path plus a **bounded unit packet** and inherited authority — Goal Capsule, Definition of Done, the unit's section, the Verification Contract entries relevant to it, any referenced R/F/AE/KTD excerpts, **plus any Product Contract Key Decision whose `Governs R…` links name the unit's cited R-IDs** (its `session-settled:` annotation reaches the worker only through this reverse link — cited KTDs alone carry only planning-decision labels). A downstream worker may narrow that unit and authority, never broaden either. Do not send "read the whole plan" as the worker prompt. (For a legacy non-unified plan, the plan path for reference is acceptable.)
+- The unit's Goal, Files, Approach, Execution note, Patterns, Test scenarios, Verification, and any resolved deferred questions for it.
+- The **Build what was asked** rule from `references/implementation-loop.md`, verbatim, and the instruction that tests prove the behavior the unit builds: make vague scenarios concrete, and add no scenarios or handling for failure paths, validation, or edge cases the unit does not build. The worker reports anything it considered and did not build.
+- **Instruction to choose the unit's evidence strategy and gather the evidence** (see Evidence Strategy in Phase 2) — for behavior-bearing changes, honor the Execution note and default to proof-first or characterization-first: create/update/strengthen the test and observe the red failure or characterization baseline **before** changing production code. The worker is the only party that witnesses this, so it must capture it as it goes.
+- **Instruction to report, in its final message, both (a) the file paths it changed and (b) the unit's verification evidence** — `behavior_changed`, existing tests inspected, tests added/changed or used unchanged, the red failure or characterization observed (when applicable), the verification run and result, and any deliberate no-test exception with its reason. The handoff is a text summary on most harnesses with no guaranteed diff, so reported paths are the orchestrator's starting hint (it still verifies the actual tree); the evidence fields are **not** reconstructable from the tree afterward, so a worker that omits them forces the orchestrator to re-derive or leave `verification_evidence` incomplete.
+- **No canonical commits.** Native workers implement and may run their *own unit's* focused tests in isolation as a self-check; the **orchestrator owns staging, the canonical commits, and the authoritative test runs**. A worker in a harness-isolated worktree may commit on its own branch only when the harness hands results back as a branch; that commit only carries the change, and the orchestrator still verifies it and makes the canonical commit. A worker in the shared workspace runs no Git command that writes the index. An external cross-model worker leaves its tree uncommitted, within the boundary `SKILL.md` sets; the host's transport snapshots only move changes and are never canonical commits.
+
+**Shared-workspace wave contract**: a parallel wave in a shared working directory is permitted only while all of these hold. A unit that cannot meet one runs serially or gets isolation:
+
+- **Clean committed baseline.** Dispatch the wave from a committed tree, so each worker's output is attributable and revertible by its file set and an aborted wave restores to the baseline.
+- **Exclusive ownership, including hidden write surfaces.** Beyond the disjoint declared files the Safety Check already verified, every hidden write surface (lockfiles, generated artifacts, snapshots, formatter sweeps, package manifests) is either excluded from all workers or assigned to exactly one.
+- **No worker Git operations.** Workers must not `git add`, commit, or otherwise write the index; concurrent index writes corrupt the shared index. The orchestrator stages and commits after the batch.
+- **Orchestrator-owned verification.** Workers run no mutating verification (full suites, installs, builds that write shared state); a worker may run a single focused unit test only if it touches no shared state. The authoritative run happens after the wave on the integrated tree.
+- **Abort on unowned writes.** A write outside every worker's exclusive set aborts the wave and disables further shared-workspace waves for the run. Restore to the baseline only changes attributable to a worker. A change no worker accounts for may be the user's: preserve it and stop for reconciliation rather than discarding it.
+
+**Permission mode:** Omit the `mode` parameter when dispatching subagents so the user's configured permission settings apply. Do not pass `mode: "auto"`; it overrides user-level settings like `bypassPermissions`.
+
+**After each serial inline/subagent unit:** review the diff against the unit's scope and `Files:`, run the relevant tests, fix before starting the next (never on a broken tree), record the unit's verification evidence (from the worker's return when a worker ran), update the task list, and commit. If the unit used a native subagent worker, retire its handle per the fresh worker invariant, then dispatch the next subagent unit in a new worker context. An inline unit has no worker handle to retire; start the next unit directly.
+
+**After a parallel inline/subagent batch, the orchestrator integrates; never trust the handoff summary alone:**
+1. Wait for every worker in the batch to finish.
+2. **Inspect the actual tree, not reported paths.** Determine what each worker really changed (`git status`/diff in its workspace or the shared dir). Reported paths are a hint; declared `Files:` are often incomplete, because workers create or modify files the plan didn't anticipate.
+3. **Detect real collisions and semantic contention**: compare actual paths plus shared contracts, generated/config surfaces, and verification effects. A clean merge is not proof of compatibility. Preserve or re-run colliding units on the advancing canonical base; never blind-merge them.
+4. **Review, test, commit, and retire each unit in dependency order — the orchestrator owns commits.** Integrate one result, inspect actual scope, run authoritative verification, create its canonical commit, then immediately retire that unit's worker per the fresh worker invariant before considering the next. Never send the retired handle another implementation unit or keep it in an orchestrator-managed idle pool. Clean up an isolated workspace only when the harness assigns that cleanup to the caller and only after proving the unit's work was integrated — never infer manual cleanup commands from the provider name. Revalidate every remaining result against the advancing canonical tree. Capture each worker's returned verification evidence into the run's `verification_evidence` roll-up. If a worker omitted it, re-derive what the tree allows and mark the rest as unverified rather than fabricating a red-before-implementation observation the worker never reported.
+5. Update the task list (progress lives in the commits).
+6. Dispatch the next dependency layer only after every unit in the batch has been integrated and its worker retired. Any remaining isolated-workspace cleanup follows the active harness's ownership and lifecycle contract.
+
+**Per-harness integration (examples; the universal flow above is the contract):**
+- **Harness-owned worktree/branch:** integrate one branch in dependency order, verify, and commit before the next; on conflict abort and re-run or explicitly resolve that unit against the advanced tree.
+- **Harness-owned uploaded change set:** accept one isolated result, inspect and verify it, commit it canonically, then release the worker before the next result.
+- **Shared workspace:** worker outputs sit uncommitted in the one working directory. Ownership decides who *may* write a path, never what a delta *is*: attribute each delta from what the unit's worker reports and inspection confirms, and commit or roll back only worker-attributed changes. A delta no worker accounts for, inside or outside an owned set, may be the user's, so preserve it and stop for reconciliation. Verify and commit in dependency order.
+- **External cross-model workspace:** follow the conditionally loaded cross-model parallel-wave protocol and controller receipts; ordinary branch-merge shortcuts do not apply.

package/skills/ce-work/references/implementation-loop.md

@@ -0,0 +1,107 @@
+# Implementation Loop
+
+1. **Task Execution Loop**
+
+Work the tasks in dependency order. Mark a task completed only after each of these holds, in this order:
+
+- **Completion signal checked first.** If any part of the unit's completion depends on out-of-repo state (a console setting, DNS record, CMS object, live-system rows), that part has no git-derived completion signal: decide it from the observed state of the deliverable, never from a clean tree or a tracker write. Mark it complete only when that state is already satisfied; execute only when it is observably unsatisfied and re-applying is safe or the user has authorized it; otherwise ask or block. If the unit's entire completion signal is repository-derived and that work is already present and matches the plan's intent (files exist with the expected capability, or the unit's `Verification` criteria are already satisfied by the current code), the work has likely shipped on a prior branch or session. Verify it matches, mark the task complete, and move on. Do not silently reimplement.
+- **Evidence chosen before behavior changes.** Find the existing tests for the files you will change (Test Discovery, below). Choose the evidence strategy for this task before changing behavior: use an existing failing test, update or strengthen an existing test, add a new failing test, add characterization coverage, or record a deliberate no-test exception with replacement verification. For behavior-bearing changes, default to test-first or characterization-first when the current code and its tests make that practical, even if the plan has no `Execution note`. When the evidence strategy calls for pre-implementation proof, create/update/strengthen the test or characterization coverage now and verify the expected failure or baseline capture before changing production code.
+- **Built to the plan.** Implement following existing conventions and the unit's `Patterns to follow`. Add, update, or remove any remaining tests needed to match implementation changes.
+- **Nothing that worked is broken.** Run System-Wide Test Check (below). Run tests after changes. If two fixes for the same failing check have not worked, stop patching: name the assumption both fixes relied on and check it, so the next change targets the root cause. When that assumption came from the plan and correcting it stays within the agreed scope, correct it and note what changed; report a blocker only when correcting it would change a settled decision, need authority the run lacks, or need input only the user can give.
+- **Evidence recorded.** Assess testing coverage: did this task change behavior? If yes, were existing tests inspected and were tests written, updated, strengthened, or deliberately left unchanged with a reason? If no tests were added or changed, is the justification deliberate (e.g., pure config, no behavioral change, manual-only surface) and paired with replacement verification? Record verification evidence for the task: behavior-change signal, existing tests inspected, tests added/changed/used unchanged, red failure or characterization observed when applicable, verification run, and any exception reason.
+
+Then mark the task completed in the task tracker and decide whether to commit it (Incremental Commits, below).
+
+When the selected engine is cross-model execution, this loop still decides unit order, the evidence strategy, inspection of what actually changed, authoritative verification, and incremental canonical commits; the worker's authoring follows the serial external-unit protocol in `references/cross-model-execution.md`. A detached worker process finishing proves only that authoring finished; do not mark the task complete until the controller records the host-owned canonical commit. A unit whose workspace was preserved, or whose restoration is blocked, stops this loop before any fallback, retry, or next unit.
+
+**Build what was asked.** The plan's units and scope, or the request itself when there is no plan, define what gets built. Add a mechanism neither asked for, such as a guard, retry, fallback, validation layer, option, mode, abstraction, or support on another interface, only when an existing contract requires it or one of these holds:
+
+- Leaving it out lets harm land before anyone catches it. Trace that the failure can actually happen here; something that notices the failure counts, while an instruction asking a person to avoid it, or to clean up by hand afterward, does not.
+- Adding it later would be expensive, because it concerns stored data or its format, a public or shared interface, money, or security.
+
+Give a mechanism that passes its smallest form. One that fails is not built: report it with the task's outcome as considered and not built, with one line on why. When you cannot tell, build it. An item the plan already lists as a non-goal stays unbuilt unless implementation turns up evidence the plan did not have; then build it and say what that evidence was. Never narrow requested behavior to fit a safeguard by delaying, gating, capping, or skipping part of what was asked. When a needed safeguard truly conflicts with requested behavior, check whether the plan or request already specified the design that carries the risk. If it did, that trade-off is decided: build it as specified and report the risk. Only a conflict the plan and request leave open is the requester's decision; stop before building either side and ask, or return it as a blocker.
+
+When the work replaces a function, type, or module whose callers are all in this repository, update those callers and remove the old version in the same change instead of keeping it as a wrapper or alias. An interface used outside this repository, or one the plan says to keep, is an existing contract and keeps working.
+
+Batch independent reads within a task: the plan's referenced files, pattern searches, and test discovery don't depend on one another — request them all in one response rather than one per turn. Only the write-and-verify steps are inherently sequential.
+
+For a parallel wave, the loop pauses after every canonical result so the host can integrate it. Inspect the actual result rather than its declared scope, re-run the independence judgment against the advancing tree, and recompute readiness from committed prerequisites. Affected dependents remain queued. An unaffected sibling may continue only after any failed apply or verification has been restored exactly and the prior integration lock released. Re-dispatch a stale or colliding result on the new base, resolve it explicitly, or finish it serially. Never treat a conflict-free apply as proof that the results are compatible. Repeated collision or broad edits disable further parallel waves for the run.
+
+When a unit carries an `Execution note`, honor its intent rather than matching a fixed vocabulary. For notes that ask for proof-first work, write or identify the relevant failing test before implementation for that unit. For notes that ask for characterization, capture existing behavior before changing it. For notes that point away from unit coverage, run the named replacement verification and record why ordinary tests were not the right proof. For units without an `Execution note`, make the same decision from code and test discovery: upgrade to proof-first or characterization-first when behavior changes and there is a practical place to test it; proceed pragmatically only when the task is non-behavioral or the exception is deliberate.
+
+Guardrails for execution evidence:
+- Do not write the test and implementation in the same step when working proof-first
+- Do not skip verifying that a new or changed test fails for the expected reason before implementing the fix or feature
+- Do not over-implement beyond the current behavior slice when working proof-first
+- Do not add a duplicate regression test when an existing test is the right home; update or strengthen that test instead, then observe the failure before changing code
+- A new or changed test must fail when the behavior it names breaks, and keep passing when only the implementation changes. It fails that bar when its expected value comes from the code under test, when a mock or fixture supplies the result the code should produce, or when it asserts calls between internal parts instead of what the code returns, stores, or sends across its boundary
+- Do not add a production export, flag, wrapper, or hook that only tests use when the real entry point can drive the behavior; test through that entry point instead
+- Skip proof-first discipline for trivial renames, pure configuration, pure styling, generated artifacts, and manual-only surfaces, but record the reason and replacement verification while continuing execution
+
+**Test Discovery** — Before implementing changes to a file, find its existing test files (search for test/spec files that import, reference, or share naming patterns with the implementation file). When a plan specifies test scenarios or test files, start there, then check for additional test coverage the plan may not have enumerated. Changes to implementation files should be accompanied by corresponding test updates — new tests for new behavior, modified tests for changed behavior, removed or updated tests for deleted behavior.
+
+**Evidence Strategy** — Test discovery decides where proof belongs:
+
+| Situation | Action |
+|-----------|--------|
+| Existing test already fails for the intended behavior | Use that as the red evidence; do not add a duplicate test |
+| Existing test covers the contract but asserts the old or wrong expectation | Update that test, run it, and verify the expected failure before implementation |
+| Existing test is over-mocked or misses the real chain | Strengthen/refactor it narrowly, then verify it fails for the right reason |
+| No existing test covers the behavior | Add the smallest focused failing test or characterization test that proves the behavior slice |
+| Testing is inappropriate for the task | Record the no-test exception and replacement verification before marking the task complete |
+
+**Test Scenario Completeness** — Tests prove the behavior the unit builds. Before writing tests for a feature-bearing unit, make any vague plan scenario concrete (e.g., "validates correctly" becomes named inputs and expected outcomes) from the unit's Goal and Approach. A scenario category the plan left out is not a gap to fill: do not add scenarios for failure handling, validation, or edge cases the unit does not build, and do not build handling so that such a scenario can exist. Draw from these categories where the unit has them: happy path; edge cases in inputs the unit really receives; error paths for failure handling the unit builds; integration across a layer the unit changes, exercised without mocks.
+
+**System-Wide Test Check** — Before marking a task done, trace what the change touches beyond its own files: callbacks, middleware, observers, and hooks up to two levels out, and any other interface that already exposes the behavior you changed. Read the actual code, not docs. What already worked through those paths must still work, so run or update the tests that cover them. A leaf change that touches none of them passes at once.
+
+2. **Incremental Commits**
+
+After completing each task, decide whether to commit. Never commit while its tests fail. **Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
+
+If the plan has Implementation Units, use them as a starting guide for commit boundaries — but adapt based on what you find during implementation. A unit might need multiple commits if it's larger than expected, or small related units might land together. Use each unit's Goal to inform the commit message.
+
+**Message convention:** match project commit conventions already in context; else match the recent log pattern; else conventional commits (`type(scope): description`). User override wins.
+
+Preserve the full resolved message as data through the selected engine's canonical commit owner. If that owner cannot accept the full message, stop and report the blocker rather than truncate it or bypass the owner's protocol. Cross-model commits follow the controller integration contract in `references/cross-model-execution.md`.
+
+For native host-owned Git commits, write the full resolved message to a file outside the repo with your file-write tool. Pass that file to Git so the shell never interprets message text.
+
+**Native Git commit workflow:**
+```bash
+# 1. Verify tests pass (use project's test command)
+# Examples: bin/rails test, npm test, pytest, go test, etc.
+
+# 2. Stage only files related to this logical unit (not `git add .`)
+git add <files related to this logical unit>
+
+# 3. Commit with the resolved message, limited to those same paths
+git commit -F <message-file> -- <files related to this logical unit>
+```
+
+**Note:** Incremental commits add no plugin-generated attribution. The final Phase 4 handoff passes `branding:on` so `ce-commit-push-pr` can add generic Compound Engineering branding to the PR.
+
+**Workers:** worker commits follow the **No canonical commits** rule in `references/execution-strategy.md`; only the orchestrator makes canonical commits.
+
+3. **Simplify as You Go**
+
+After completing a cluster of related implementation units (or every 2-3 units), review recently changed files for simplification opportunities — consolidate duplicated patterns, extract shared helpers, and improve code reuse and efficiency. This is especially valuable when using subagents, since each agent works with isolated context and can't see patterns emerging across units.
+
+Don't simplify after every single unit — early patterns may look duplicated but diverge intentionally in later units. Wait for a natural phase boundary or when you notice accumulated complexity.
+
+If **`ce-simplify-code`** is available, invoke it with `mode:pipeline` at phase boundaries (especially before Phase 3 when the accumulated cluster has >=30 substantive changed code lines — count human-authored code, not total diff lines, so a mostly test-fixture/config/generated/mechanical cluster does not trigger the check). Otherwise, review the changed files yourself for reuse and consolidation opportunities. When invoking it, pass each test the evidence record names as proving the work (a red-before-fix test, characterization coverage, or an existing test used unchanged) as `proof-test:<path>`, so the simplification leaves that test untouched.
+
+When the plan carries `session-settled:`-labeled KTDs or Key Decisions, pass the plan path as context for which structures must stay as they are, not as the simplification scope, with the one-line constraint that labeled entries are settled decisions the simplification must preserve (e.g., deliberate duplication stays duplicated).
+
+4. **UI Verification** (if applicable)
+
+For UI work built from a Figma design, read `references/agents/figma-design-sync.md` and dispatch a generic subagent seeded with that local prompt to compare the implementation against the design. Do not dispatch a standalone agent by type/name. Apply the reported fixes that hold up against the project's conventions, then compare again until it reports a match or only differences you judge intentional.
+
+For other user-visible UI changes, check the changed UI in a browser at desktop and mobile widths when browser tooling is available. If none is available, review the layout code for overflow and responsive breakage and record that browser verification was unavailable. Phase 4's screenshot capture still applies when the change is user-visible.
+
+5. **Track Progress**
+- Add a task when requested work turns out larger than expected; a mechanism nobody asked for goes through **Build what was asked** first
+- When the plan defines U-IDs for Implementation Units, or the plan or origin document carries stable R-IDs (and optionally A/F/AE IDs), reference them in blockers, deferred-work notes, task summaries, and final verification — not routine status updates. U-IDs anchor units across plan edits; R/A/F/AE anchor product intent across the brainstorm-plan handoff. Use the IDs the plan supplies and do not invent ones it does not. This preserves traceability without burying signal under noise.
+
+## Settled decisions during implementation
+
+A KTD or Product Contract Key Decision carrying a `session-settled:` annotation (classes `user-directed` / `user-approved`) records a decision the user already made; it is not yours to improve. A product decision's label arrives through the Key Decision whose `Governs R…` links name your unit's Rs, not through a KTD. This scopes to labeled entries only: details the plan leaves open remain your judgment, and a real defect discovered inside a settled approach is still reported at full strength; the label never suppresses defect evidence. If implementation reveals a labeled decision is unworkable to the point of invalidating it (infeasible, wrong-thing, destructive), that is a genuine blocker: report it rather than silently working around or "fixing" the decision.

package/skills/ce-work/references/implementation-result-schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://compound-engineering.dev/schemas/ce-work-implementation-result-v1.json",
+  "title": "CE Work external implementation worker result",
+  "type": "object",
+  "required": [
+    "terminal_status",
+    "summary",
+    "changed_files",
+    "evidence",
+    "scope_expansion"
+  ],
+  "properties": {
+    "terminal_status": {
+      "type": "string",
+      "enum": ["completed", "blocked", "scope_expansion"]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "changed_files": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "evidence": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "scope_expansion": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["requested_paths", "reason"],
+          "properties": {
+            "requested_paths": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "reason": { "type": "string", "minLength": 1 }
+          },
+          "additionalProperties": false
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}