Skip to content

Runtime/Execution Domain (living container detail)

Who is this for (1)
FieldValue
StatusLiving
Date2026-06-11
ScopeContainer-level execution-state resolution, routing, and the canonical WP lifecycle FSM
Related ADRs2026-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)

ConcernPrimary ContainersOutcome
Execution-state resolutionmission_runtime (resolve_action_context), Workspace lifecycleCWD-invariant ExecutionContext + single CommitTarget
Planning-phase placementresolve_placement_onlyThe WP-less planning CommitTarget from the same authority
Status-surface resolutionresolve_status_surface_with_anchorSingle-pass status surface + primary anchor (fails closed)
Lifecycle mutationstatus/ OHS facade (Mission Management)Guarded transition validation and event-sourced persistence
Commit protectioncommit_guard.evaluate + GuardCapability (Shared Kernel)The one allow/refuse decision on the resolved ref

Runtime/Execution Invariants

  1. There is exactly one execution-state surface: the top-level mission_runtime package. The retired specify_cli/core/execution_context.py home is gone.
  2. resolve_action_context is CWD-invariant, topology-aware, and mode-correct; it raises rather than silently falling back on unresolvable context.
  3. target_branch is resolved exactly once per operation and threaded onto the context; no downstream surface re-derives it.
  4. mid8 is derived exactly once as mission_id[:8].
  5. Lifecycle authority remains host-owned even when hosted moments are enabled.

Single Commit Destination (CommitTarget)

resolve_action_context (mission_runtime)

resolve_placement_only (planning phase)

CommitTarget(ref, kind)

commit_guard.evaluate(target, protection_state, capability)

GuardVerdict — resolved_destination echoes target.ref

  • CommitTarget is (ref, kind): a destination ref paired with its topology kind — PRIMARY, COORDINATION, or FLATTENED. (It is NOT the earlier (worktree_root, destination_ref) sketch — see the 2026-06-10 addendum to ADR docs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md.)
  • resolve_placement_only is a narrower entry point over the same resolution authority as resolve_action_context — the topology classification is byte-identical for the same mission, not a parallel resolver.
  • commit_guard.evaluate is pure: it echoes target.ref as the resolved destination and never re-derives one. GuardCapability (STANDARD by default) is asserted at the call site, never derived from message text, file content, env, or op records. No capability can authorize a push to origin/main — the guard only ever commits locally.

Branch Target Routing Invariants

  1. Mission metadata (meta.json) carries canonical identity (mission_id) and the routing authority (target_branch).
  2. Lifecycle/status commits route to the resolved CommitTarget.ref, not the caller’s location.
  3. Worktree context does not reassign lifecycle authority; the resolved context is CWD-invariant.
  4. 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.

claim (actor)

start (workspace_context)

ready_for_review (subtasks + evidence)

pick_up_review (reviewer)

approve (review_ref)

integrate (done evidence)

changes_requested (review_ref)

changes_requested (review_ref)

blocked

blocked

blocked

blocked

blocked

blocked

unblock

cancel

cancel

cancel

cancel

cancel

cancel

cancel

planned

claimed

in_progress

for_review

in_review

approved

done

blocked

canceled

Transition Guard Summary

  1. Canonical lanes: planned, claimed, in_progress, for_review, in_review, approved, done, blocked, canceled.
  2. blocked is reachable from every non-terminal lane; canceled is reachable from all.
  3. done and canceled are terminal (a force override is required to leave).
  4. doing is an input alias for in_progress, resolved at input boundaries and never persisted.
  5. Guard requirements are transition-specific: actor, workspace context, review_ref, done evidence, and explicit reason fields.
  6. Dependency gating: a WP with dependencies cannot be claimed/implemented until every dependency is approved or done.

Runtime/Execution Container Interaction

ExecutionContext + CommitTarget

lifecycle mutation command

event log + snapshot

guarded commit on resolved ref

lane transition

CLI Command Surface

mission_runtime — resolve_action_context

Workspace / worktree lifecycle

status/ OHS facade (Mission Management)

commit_guard.evaluate

Zeitgeist moment (drain-gated, after local persistence)

Traceability