Runtime/Execution Domain (living container detail)
Who is this for (1)
- Stakeholder Persona: System Architect — Written for the System Architect reader.
| Field | Value |
|---|---|
| Status | Living |
| Date | 2026-06-11 |
| Scope | Container-level execution-state resolution, routing, and the canonical WP lifecycle FSM |
| Related ADRs | 2026-06-03-1, 2026-06-03-2, 2026-06-07-1, 2026-04-06-1, 2026-05-01-1 |
Purpose
Provide a focused container-level view of the Execution / Runtime module: execution-state resolution, the single commit destination, branch-target routing, and the canonical work-package lifecycle FSM.
Domain Boundary (Container Level)
| Concern | Primary Containers | Outcome |
|---|---|---|
| Execution-state resolution | mission_runtime (resolve_action_context), Workspace lifecycle | CWD-invariant ExecutionContext + single CommitTarget |
| Planning-phase placement | resolve_placement_only | The WP-less planning CommitTarget from the same authority |
| Status-surface resolution | resolve_status_surface_with_anchor | Single-pass status surface + primary anchor (fails closed) |
| Lifecycle mutation | status/ OHS facade (Mission Management) | Guarded transition validation and event-sourced persistence |
| Commit protection | commit_guard.evaluate + GuardCapability (Shared Kernel) | The one allow/refuse decision on the resolved ref |
Runtime/Execution Invariants
- There is exactly one execution-state surface: the top-level
mission_runtimepackage. The retiredspecify_cli/core/execution_context.pyhome is gone. resolve_action_contextis CWD-invariant, topology-aware, and mode-correct; it raises rather than silently falling back on unresolvable context.target_branchis resolved exactly once per operation and threaded onto the context; no downstream surface re-derives it.mid8is derived exactly once asmission_id[:8].- Lifecycle authority remains host-owned even when hosted moments are enabled.
Single Commit Destination (CommitTarget)
CommitTargetis(ref, kind): a destinationrefpaired with its topologykind—PRIMARY,COORDINATION, orFLATTENED. (It is NOT the earlier(worktree_root, destination_ref)sketch — see the 2026-06-10 addendum to ADRdocs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md.)resolve_placement_onlyis a narrower entry point over the same resolution authority asresolve_action_context— the topology classification is byte-identical for the same mission, not a parallel resolver.commit_guard.evaluateis pure: it echoestarget.refas the resolved destination and never re-derives one.GuardCapability(STANDARDby default) is asserted at the call site, never derived from message text, file content, env, or op records. No capability can authorize a push toorigin/main— the guard only ever commits locally.
Branch Target Routing Invariants
- Mission metadata (
meta.json) carries canonical identity (mission_id) and the routing authority (target_branch). - Lifecycle/status commits route to the resolved
CommitTarget.ref, not the caller’s location. - Worktree context does not reassign lifecycle authority; the resolved context is CWD-invariant.
- When a mission declares
coordination_branch, the status surface is composed once for the coordination root; a materialized coord root lacking the mission dir fails closed rather than falling back to a primary surface.
Canonical work package lifecycle FSM
The lane state is owned by an append-only event log and reduced to a snapshot;
lane behavior is modeled with the State pattern (2026-04-06-1). doing is an
input alias for in_progress and is never persisted.
Transition Guard Summary
- Canonical lanes:
planned,claimed,in_progress,for_review,in_review,approved,done,blocked,canceled. blockedis reachable from every non-terminal lane;canceledis reachable from all.doneandcanceledare terminal (a force override is required to leave).doingis an input alias forin_progress, resolved at input boundaries and never persisted.- Guard requirements are transition-specific:
actor, workspace context,review_ref, done evidence, and explicit reason fields. - Dependency gating: a WP with
dependenciescannot be claimed/implemented until every dependency isapprovedordone.
Runtime/Execution Container Interaction
Traceability
- Domain model ADR:
docs/adr/3.x/2026-06-03-1-execution-state-domain-model.md - Canonical execution surface ADR:
docs/adr/3.x/2026-06-07-1-execution-state-canonical-surface.md - WP State pattern ADR:
docs/adr/3.x/2026-04-06-1-wp-state-pattern-for-lane-behavior.md - Container map:
README.md - Component model:
../03_components/README.md