Containers (living)
Who is this for (1)
- Stakeholder Persona: System Architect — Written for the System Architect reader.
| Field | Value |
|---|---|
| Status | Living |
| Date | 2026-06-11 (charter service direction added 2026-10-03) |
| Scope | C4 Level 2 container model — four bounded modules + Op tier |
| Related ADRs | 2026-06-03-1, 2026-06-03-2, 2026-06-03-3, 2026-06-07-1, 2026-04-25-1, 2026-05-16-1, 2026-10-03-1, 2026-10-01-2, 2026-10-12-2 |
Purpose
Show the major logical containers in Spec Kitty and define how they collaborate to enforce governance, mission lifecycle, execution-state resolution, and the single commit-protection decision.
Scope Rules
- Use stable logical container boundaries (the four bounded modules), not implementation package inventories.
- Focus on contracts, responsibilities, and behavior loops.
- Defer intra-module component detail to
../03_components/README.md. - Use
runtime-execution-domain.mdfor the deeper lifecycle/routing/FSM detail that would overload the top-level map.
Container Diagram (Mermaid)
The four bounded modules are the top-level containers. They communicate through
Open Host Service (OHS) facades only
(docs/adr/3.x/2026-06-03-1-execution-state-domain-model.md).
Planned Charter Service Containers
This refinement marks planned and future elements explicitly. It does not claim that a Java service directory or release artifact exists. See ADR 2026-10-03-1.
The seam is code under src/charter/ and holds only a transport client. Service launch and
lifecycle live in specify_cli, so charter gains no outbound edge to specify_cli.
The document projection is an implementation detail and not the rejected design where
Java only serves a permanent Python-compiled projection. The Mission Status Read
service shares neither charter domain nor process. Direct MCP and Python-seam
reads enter the same application and domain policies.
Container Responsibilities
| Container | Core Responsibility | Behavioral Ownership |
|---|---|---|
| CLI Command Surface | Interactive and scripted command entry point | Validates command intent and routes to the Op tier and bounded modules |
| Op Tier | Standalone dispatch invocations and the pre/post-mission lifecycle | Opens an Op under resolved governance context, does the work, closes the Op with the real outcome |
| Charter Engine | Charter interview, activation, cascade, and org-charter.yaml extends: resolution | Produces governance constraints (the active charter/doctrine policy) consumed by the Op tier and missions |
| Charter Offering + DRG | Typed governance/mission assets and the Doctrine Relationship Graph | Loads/validates doctrine resources; resolves profile lineage via DRG edges |
| Glossary Corpus | Canonical terminology surface | Supplies terms and guards terminology drift |
| Mission + WP lifecycle | Mission and work-package lifecycle precedence | Owns lifecycle sequencing; delegates execution-state resolution to mission_runtime |
status/ OHS facade | Canonical lifecycle and event semantics | Sole status authority — no module outside Mission Management imports status internals |
| Planning artifacts | specify / plan / tasks / finalize-tasks outputs | Commits planning artifacts to the resolved CommitTarget |
mission_runtime | Canonical execution-state surface | Resolves CWD-invariant ExecutionContext and the single CommitTarget; consumers import only from the package root |
resolve_placement_only | WP-less planning-phase projection | One narrow entry point over the same resolution authority — the planning CommitTarget |
resolve_status_surface_with_anchor | Single-pass status-surface + primary-anchor resolution | The one status-surface authority; fails closed rather than handing back a primary surface (kills the split-brain class) |
CommitTarget(ref, kind) | The one ref artifacts and status events resolve to | Self-validating value object pairing the destination ref with its topology kind |
commit_guard.evaluate + GuardCapability | The ONE commit-protection decision | Pure function: echoes CommitTarget.ref as the resolved destination; capability is asserted at the call site, never derived |
Canonical-shape notes (what these containers are NOT)
- The execution-state surface is the top-level
mission_runtimepackage. The retiredspecify_cli/core/execution_context.pyhome is gone and is deliberately not depicted (2026-04-25-1,2026-06-07-1). CommitTargetis(ref, kind)— a destination ref paired with its topology classification. The earlier sketch of(worktree_root, destination_ref)is superseded and not depicted (see the 2026-06-10 addendum todocs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md).- Commit protection is one pure decision (
commit_guard.evaluate) parameterized by an explicitGuardCapability; the five legacy privilege channels were folded into that capability and are not depicted. - The retired sync transport (daemon, offline queue, batch ingress) is gone and
is not depicted, and neither is the Zeitgeist moment publisher, which was removed from open-core (#6164; preserved in
spec-kitty/event-router).
Domain-to-Container Allocation
| Domain (bounded module) | Primary Containers | Secondary Containers |
|---|---|---|
| Governance | Charter Engine, Charter Offering + DRG, Glossary Corpus | CLI Command Surface, Op Tier |
| Mission Management | Mission + WP lifecycle, status/ OHS facade, Planning artifacts | CLI Command Surface |
| Execution / Runtime | mission_runtime, resolve_placement_only, resolve_status_surface_with_anchor, Workspace lifecycle | Mission + WP lifecycle |
| Shared Kernel | CommitTarget(ref, kind), commit_guard.evaluate + GuardCapability | — |
| Op Tier (cross-module) | Op Tier | Charter Engine, Mission + WP lifecycle |
Behavioral Collaboration Loops
Loop A: Mission lifecycle and execution-state resolution
- CLI captures the command and routes it to the Op tier / Mission Management.
- Mission Management calls
resolve_action_contextonmission_runtimeto get a CWD-invariantExecutionContextand the singleCommitTarget. - Lifecycle mutation commands execute through the
status/OHS facade. - The facade validates transitions, appends events, and materializes snapshots.
Loop B: Single-destination commit protection
mission_runtime(or the planning-phaseresolve_placement_only) produces oneCommitTarget(ref, kind).commit_guard.evaluatedecides — purely, from the target plus an assertedGuardCapability— whether the commit may land on that ref.- The verdict echoes
CommitTarget.refas the resolved destination; the guard never re-derives a destination and never performs a push.
Loop C: Governance-context-scoped Ops
- The Op tier asks the Charter Engine for the action-scoped governance context.
- The Charter Engine resolves the active charter/doctrine (including
org-charter.yamlextends:and DRG profile lineage). - The Op runs under that context and is closed with its real outcome.
Runtime/Execution Domain Detail
See Runtime/Execution Domain (Container Detail) for the canonical work-package lifecycle FSM, transition-guard summary, and execution/routing invariants.
Interaction Constraints
- State transitions are host-authoritative; orchestrator, Team Kitty and trackers use contract surfaces only.
- Modules communicate through OHS facades;
statusinternals are import-forbidden outside Mission Management. - There is exactly one execution-state surface (
mission_runtime) and one commit-protection decision (commit_guard.evaluate). - Tracker integrations are optional and boundary-scoped and never block local persistence.
Decision Traceability
Open-core container view: producer ecosystem and the API contract seam (2026-10-12)
This view groups the containers as the open-core producer ecosystem and draws the one
boundary to the opaque Team Kitty consumer. The CLI owns the append-only event ledger and the
wall-clock status reducer ((at, event_id) with the #4941 approved-departure lift; CLI lane
rows carry no Lamport clock); the Mission Status Read API (a Java service that is to start in-repo as a
modular component and be extracted when its contract freezes — ADR
2026-10-01-2,
Accepted) reads that ledger as a read model and conforms to the contract beside the Python
reducer. The charter stays in core until it is retired; its offering reads cut over to the
spec-kitty-charter service through charter.offering.api (ADR
2026-10-03-1,
Amendment 2026-10-19, superseding the repository extraction of ADR
2026-10-12-2); the
pack source home is spec-kitty-open-packs. Team Kitty (“Multiplayer Mode”) consumes the
API across its contract boundary and is a single opaque container here.
Where the pieces live (#6915): the Mission-Status Read API’s Java service and the mission-status
contract live in spec-kitty-events (service/, contracts/, released on the service-v* line); core
pins the read service for CI conformance only (pins/read-service.source.yaml) and ships the Python
reducer.
Alt-text: an open-core boundary containing the CLI, the event ledger, the wall-clock status reducer, the Mission-Status Read API (Java, planned, to start in-repo), the extracting charter and the fetched packs; four extracted packages (events, tracker, open-packs, doc-kitty) as separate units; and the API contract seam as the one boundary to the opaque Team Kitty consumer.
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 - ExecutionContext owner + CommitTarget ADR (incl. 2026-06-10 addendum):
docs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md - Shared package boundary ADR:
docs/adr/3.x/2026-04-25-1-shared-package-boundary.md - Runtime/execution detail:
runtime-execution-domain.md - Context view:
../01_context/README.md - Component view:
../03_components/README.md - Charter service strangler ADR:
2026-10-03-1