Define component-level boundaries for Spec Kitty 3.x while remaining
implementation-agnostic and behavior-focused, aligned to the four bounded
modules and the Op tier.
Scope Rules
Focus on conceptual components and contracts, not file/class listings.
Explain behavior and interaction patterns that matter architecturally.
Keep component definitions aligned with the container boundaries and 3.x ADRs.
Owns mission/WP lifecycle precedence and dependency gating
Lifecycle Command Gateway
Mission Mgmt
The status/ OHS facade — normalizes lifecycle mutation requests
Event Reducer + Snapshot Materializer
Mission Mgmt
Deterministically reduces the event log to a snapshot
Append-only Event Store
Mission Mgmt
JSONL event I/O with corruption detection — sole lane authority
WP Lane State (State pattern)
Mission Mgmt
Models lane behavior per the State pattern (2026-04-06-1)
resolve_action_context
Execution
Resolves CWD-invariant ExecutionContext + single CommitTarget
resolve_placement_only
Execution
WP-less planning projection over the same resolution authority
resolve_status_surface_with_anchor
Execution
Single-pass status surface + primary anchor; fails closed
Context Fragments
Execution
Cohesive value-object fragments composed per operation (op-composite)
Workspace + Worktree Coordinator
Execution
Resolves/reuses the execution workspace
CommitTarget(ref, kind)
Shared Kernel
The one destination ref + topology kind for artifacts and status
commit_guard.evaluate
Shared Kernel
The ONE commit-protection decision (pure; echoes target.ref)
GuardCapability
Shared Kernel
Asserted-at-the-surface authorization parameter to evaluate
Canonical-shape notes (3.x)
Execution-state resolution lives in mission_runtime; consumers import only
from the package root. The retired core/execution_context.py home is gone
and is not depicted (2026-04-25-1, 2026-06-07-1).
Authorization is one explicit GuardCapability argument; the five legacy
privilege channels were folded in and are not depicted.
Domain Alignment Matrix
Domain (bounded module)
Primary Components
Governance
Charter Activation Engine, Charter Cascade, Org Charter Extends Resolver, Doctrine Catalog Loader, Doctrine Relationship Graph, Agent Profile Repository, Glossary Corpus
Mission Management
Mission + WP Lifecycle, Lifecycle Command Gateway, Event Reducer + Snapshot Materializer, Append-only Event Store, WP Lane State
sequenceDiagram
participant User as Human/Agent
participant Router as Command Router
participant Mission as Mission + WP Lifecycle
participant Runtime as resolve_action_context
participant Kernel as CommitTarget(ref, kind)
User->>Router: invoke a mission action
Router->>Mission: dispatch lifecycle command
Mission->>Runtime: resolve_action_context(repo_root, action, ...)
Runtime->>Runtime: assemble fragments and resolve target_branch once
Runtime->>Kernel: produce single CommitTarget
Runtime-->>Mission: ExecutionContext + CommitTarget
Sequence B: Lifecycle mutation and single-destination commit protection
sequenceDiagram
participant User as Human/Agent
participant Gateway as Lifecycle Command Gateway (status/)
participant State as WP Lane State
participant Reducer as Event Reducer
participant Target as CommitTarget(ref, kind)
participant Guard as commit_guard.evaluate
User->>Gateway: request lifecycle transition
Gateway->>State: validate guarded transition
State->>Reducer: append event + materialize snapshot
Gateway->>Target: take resolved destination
Target->>Guard: evaluate(target, protection_state, capability)
Guard-->>Gateway: GuardVerdict (resolved_destination echoes target.ref)
Sequence C: Profile-governed Op invocation
sequenceDiagram
participant User as Human/Agent
participant OpCmd as Op Command Set
participant Inv as Op Invocation Context
participant Activation as Charter Activation Engine
participant DRG as Doctrine Relationship Graph
User->>OpCmd: spec-kitty dispatch
OpCmd->>Inv: open Op
Inv->>Activation: load action-scoped governance context
Activation->>DRG: resolve active artifacts + profile lineage
DRG-->>Inv: resolved governance context
Inv-->>User: do the work under context, then close Op with outcome
Sequence D: Charter activation and cascade
sequenceDiagram
participant Human as Human In Charge
participant Activation as Charter Activation Engine
participant Cascade as Charter Cascade
participant DRG as Doctrine Relationship Graph
Human->>Activation: charter activate <kind> <artifact> --cascade
Activation->>Activation: plan_activation (non-mutating validation)
Activation->>Cascade: follow requires/suggests edges
Cascade->>DRG: resolve cascade set (shared-reference safe)
Activation-->>Human: commit_activation (writes config only after plan succeeds)