hex-execute — Execution Orchestrator

Thin dispatcher. A plan is a few pipelines cut along contracts; a pipeline is a chain of steps in one worktree. This file resolves the target, runs the contract wave, dispatches steps, merges, runs the integration gate concurrent with the review call, fixes, and hands to /hex-finalize. Vocabulary lives in hex-core and is linked here, never copied.

Shared contracts: protocol.md · workers.md · models.md · memory.md · worktree.md · verify.md. If hex-core is not installed: grim add ghcr.io/michael-herwig/arcana/hex-core:latest.

Argument syntax

/hex-execute [target] [--dry-run]

• target (optional): a plan artifact path; a free-text task (no plan artifact, one pipeline); or omitted — resolve the active-plan pointer from hex.md › Memory (memory.md).
• --dry-run — print the announce block and stop; no worker launches.

The run

Counts are fixed (DESIGN.md): two full gates (integration, release), ≤ 3 review calls, workers never wait, escalation by the orchestrator only.

1. Resolve memory and target

Locate .agents/memory/hex.md searching upward; a missing file is normal (memory.md) — use shipped defaults and note that /hex-init can create one. When present, read it whole: Pointers (verification, hub/generated files, fresh-build switch, worktree location), Preferences (model-class agent definitions, limits), Memory (active-plan pointer). A Federation lead: bullet means this repo is a satellite: halt per memory.md.

Resolve the target: explicit plan path (read it whole), active-plan pointer (none recorded: stop and ask), or free text (scope contracts inline). A plan carrying a Repo column: follow federation.md before anything else is written.

Plan State decides entry: plan-approved is normal. executing is a prior run — resume from the pipeline table's Status column (pending | active | merged | failed), resetting an unfinished pipeline to its last committed step; branches and worktrees are evidence only, the Implementation Steps checkboxes are the finer progress, and a resuming run never reads the per-run scratch root. landing is a finalize-only re-entry (federation.md). review or done: stop and report; the human decides whether to re-execute.

2. Announce

No approval gate — print the resolved config and proceed (the user can abort):

hex-execute
  Target:      .agents/plans/plan_cache.md
  Pipelines:   3 (A, B, C) — contract wave first, then A ∥ B ∥ C
  Jobs:        3 live × 4 = 12            (project single-build jobs: 12)
  Classes:     steps standard; B step 4 standard-high (plan mark)
  Review:      1 call after all pipelines land
  Gates:       integration (with review) · release (/hex-finalize)
  Branches:    feature hex/plan-cache; per pipeline hex/plan-cache--<pipeline>

Plus the federation pre-flight lines, when federated. A client that cannot spawn subagents announces Degraded: inline workers and runs each brief inline, sequentially (protocol.md). Then set the plan's State: executing.

3. Contract wave

Resolve the feature branch — the non-trunk branch already checked out, else hex/<plan-slug> from the trunk (worktree.md). A single pipeline (small task) skips the wave and the worktree: its steps run directly on the feature branch.

Otherwise one or a few standard steps write the stubs plus contract tests for every pipeline — public surface with not-implemented bodies, and the tests that pin each cross-pipeline contract, derived from the plan's component contracts, not from the stubs. Commit once. That commit is the frozen base of every pipeline.

4. Pipelines and steps

Each pipeline gets a branch hex/<plan-slug>--<pipeline-slug> and a worktree (worktree.md), all created from the wave commit; all pipelines start together. Pipelines own disjoint file sets. Inside a pipeline: serial steps, shared worktree, no merge, no review, no gate between steps. The orchestrator spawns every step itself (foreground results reach it; there is no driver agent in between) and starts a pipeline's next step the instant the previous returns.

Step. A fresh agent of class standard (standard-high only where the plan marks the step — at most 1 pipeline in 4), one small brief (workers.md rule 8: the excerpt, not the plan body). The step does contract-first TDD inside itself — specify, implement — and commits with --no-verify. Brief states:

• Step feedback is the only inner check. A behavioural step runs the tests it wrote or touched, once, with the narrowest command it picks (e.g. cargo test -p x), never the project's gate wrapper. A non-behavioural step (docs, taskfiles, config, renames, comments) runs nothing — "will this be exercised later anyway?" means skip.
• Every commit and merge on hex-owned branches uses --no-verify. This run's integration and release gates satisfy the project's "verify before commit" instructions; do not run the full gate.
• Never wait on a lock, a gate or a poll — return instead. No worker-side locks. A heavy or exclusive tool (bazel server, docker acceptance project) is gate-only; a step that needs a one-off exclusive check hands it to the orchestrator and does not wait.
• Never commit hub or generated files (lockfiles, baselines, goldens; the hex.md › Pointers list).
• Parallel builds: use at most the pipeline's jobs allotment.

Job budget. live pipelines × jobs per pipeline ≤ the project's single-build jobs. The orchestrator sets the allotment in every brief.

Contract drift. At each step return, git diff <wave-commit> over the contract-wave files. A touched contract: the orchestrator applies the edit to the feature branch, merges it into the affected pipelines' branches, and states the change in their next brief. No review is triggered.

Failure and escalation (orchestrator only, models.md): a step has failed when it returned incomplete or its output was rejected; a red TDD phase is not a failure. Same step failing again: retry at the same class with the failure attached → one class up → defer as residue and keep the loop going.

Pipeline done = its steps all returned. Merge it onto the feature branch with --no-verify, one pipeline at a time in dependency order, never a batch; no gate on the merge. Set its table Status: merged. Merge-time file-set re-validation and the conflict playbook are worktree.md's.

5. Integration gate ∥ review call

When every pipeline has merged, in the background and concurrently:

• Integration gate — the project's full documented verification on the feature branch (verify.md), after regenerating the hub and generated files once, minimally (no cargo update).
• Review call — one autonomous /hex-review over anchor..HEAD: staged panel and codex, seats split per pipeline plus one for the seams. /hex-review owns seats, rounds and the last-reviewed anchor.

Mid-run review calls: loop.md § Review calls.

One fix pass serves both: gate failures and the review's findings go to standard fixers per pipeline, in parallel, then the gate runs again. Red → one fix pass → gate again; at most 2 fix passes, then stop and hand the residue to the user. A gate that failed on infrastructure is rerun once.

6. Hand off

Set the plan's State: review, Next: /hex-finalize, Updated refreshed (a free-text target has no Status block — say so in the handoff). Run the upkeep step. Never push. Emit the handoff (contract):

## Execution Complete: <feature | plan name>

### Run
- Pipelines: <n> merged, <n> deferred · contract wave <sha>
- Integration gate: green | red after 2 fix passes (<cause>)
- Review calls: <n> · anchor <sha>

### Artifacts
- <plan path> (Status block advanced to `review`)
- <feature branch and tip>

### Deferred findings (need human judgment)
- Review: …
- Residue: … (steps deferred after escalation)

### Next step
    /hex-finalize

A plan carrying a Repo column adds the per-repo landing order and back-pointer list (federation.md).

Plan artifact

Co-owned with /hex-plan and /hex-review; no external state file.

## Status
- State:   executing      <!-- planning → plan-approved → executing → review → done -->
- Updated: 2026-07-19
- Next:    /hex-execute <this plan path>

• Living design record. When execution reveals a behaviour the plan did not specify, update the plan first, then the test, then the code.
• Spec deltas (C-419). On each pipeline merge, append its delta entries to the plan's single ## Spec Deltas block — one Target: for the plan (C-415), append-only, never rewriting another pipeline's entry. A MODIFIED entry's Base: is the pasted output of archive.md's stale-base sub-ID scan (C-405) over the live destination. A satellite-delivered entry (Repo ≠ .) defers rather than folding (C-415 clause 5). Grammar and guards: archive.md § Delta grammar.

Constraints

• Project rules, verification and artifact conventions come from project context and the hex.md › Pointers, never a hardcoded table; no documented verification means detect one command once and suggest /hex-init.
• The orchestrator's main loop only dispatches and merges; anything slow runs in the background. Event-driven on step returns, with a fallback tick of at least 20 minutes. Two levels: /hex-loop above, this run below.
• Never exceed the concurrency cap (protocol.md).
• Never push to remote. Never leave finished work uncommitted.
• No mid-flow questions; a scope surprise stops and re-routes to /hex-plan.

$ARGUMENTS