Skip to content

Containers (living)

Who is this for (1)
FieldValue
StatusLiving
Date2026-06-11 (charter service direction added 2026-10-03)
ScopeC4 Level 2 container model — four bounded modules + Op tier
Related ADRs2026-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

  1. Use stable logical container boundaries (the four bounded modules), not implementation package inventories.
  2. Focus on contracts, responsibilities, and behavior loops.
  3. Defer intra-module component detail to ../03_components/README.md.
  4. Use runtime-execution-domain.md for 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).

Shared Kernel

Execution / Runtime Module

Mission Management Module

Governance Module

action-scoped context

tracker commands

resolve_action_context

resolve_placement_only

resolve_status_surface_with_anchor

produces

produces

GuardVerdict on resolved ref

CLI Command Surface

Charter Engine — activation, cascade, extends

Charter Offering + DRG

Glossary Corpus

Mission + WP lifecycle

status/ OHS facade — sole status authority

Planning artifacts (specify/plan/tasks)

mission_runtime — canonical execution surface

resolve_placement_only — planning CommitTarget

resolve_status_surface_with_anchor — status surface

Workspace + worktree lifecycle

CommitTarget(ref, kind)

commit_guard.evaluate + GuardCapability

Op Tier — dispatch + pre/post-mission lifecycle

External Orchestrator

External Tracker (local provider)

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.

Charter Service — planned, per worktree (Java 25, Spring Boot 4)

Charter layer (src/charter) — planned

Spec Kitty CLI (specify_cli) — current

CLI

planned: move onto the seam

planned governed MCP read

current write operations

planned: writes stay in Python

planned: starts service, gives seam endpoint

planned production reads

future migrated writes

authored source

derived read model

later, operation by operation

constrains

constrains

constrains

planned: launches and stops

Agent harness

CLI, runtime, and glossary callers — import charter internals directly

Current Python write paths — activation commit_plan, charter_yaml_io, compile

Service launch and lifecycle — planned

Charter API seam — planned (#645): transport client only

REST and MCP read adapters — planned

Java charter read application — planned

Java write application — future

Document projection — format deferred

Charter contract: contracts/charter/ and conformance corpus

Authored charter and pack YAML

Mission Status Read service — separate sibling

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

ContainerCore ResponsibilityBehavioral Ownership
CLI Command SurfaceInteractive and scripted command entry pointValidates command intent and routes to the Op tier and bounded modules
Op TierStandalone dispatch invocations and the pre/post-mission lifecycleOpens an Op under resolved governance context, does the work, closes the Op with the real outcome
Charter EngineCharter interview, activation, cascade, and org-charter.yaml extends: resolutionProduces governance constraints (the active charter/doctrine policy) consumed by the Op tier and missions
Charter Offering + DRGTyped governance/mission assets and the Doctrine Relationship GraphLoads/validates doctrine resources; resolves profile lineage via DRG edges
Glossary CorpusCanonical terminology surfaceSupplies terms and guards terminology drift
Mission + WP lifecycleMission and work-package lifecycle precedenceOwns lifecycle sequencing; delegates execution-state resolution to mission_runtime
status/ OHS facadeCanonical lifecycle and event semanticsSole status authority — no module outside Mission Management imports status internals
Planning artifactsspecify / plan / tasks / finalize-tasks outputsCommits planning artifacts to the resolved CommitTarget
mission_runtimeCanonical execution-state surfaceResolves CWD-invariant ExecutionContext and the single CommitTarget; consumers import only from the package root
resolve_placement_onlyWP-less planning-phase projectionOne narrow entry point over the same resolution authority — the planning CommitTarget
resolve_status_surface_with_anchorSingle-pass status-surface + primary-anchor resolutionThe 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 toSelf-validating value object pairing the destination ref with its topology kind
commit_guard.evaluate + GuardCapabilityThe ONE commit-protection decisionPure 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_runtime package. The retired specify_cli/core/execution_context.py home is gone and is deliberately not depicted (2026-04-25-1, 2026-06-07-1).
  • CommitTarget is (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 to docs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md).
  • Commit protection is one pure decision (commit_guard.evaluate) parameterized by an explicit GuardCapability; 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 ContainersSecondary Containers
GovernanceCharter Engine, Charter Offering + DRG, Glossary CorpusCLI Command Surface, Op Tier
Mission ManagementMission + WP lifecycle, status/ OHS facade, Planning artifactsCLI Command Surface
Execution / Runtimemission_runtime, resolve_placement_only, resolve_status_surface_with_anchor, Workspace lifecycleMission + WP lifecycle
Shared KernelCommitTarget(ref, kind), commit_guard.evaluate + GuardCapability—
Op Tier (cross-module)Op TierCharter Engine, Mission + WP lifecycle

Behavioral Collaboration Loops

Loop A: Mission lifecycle and execution-state resolution

  1. CLI captures the command and routes it to the Op tier / Mission Management.
  2. Mission Management calls resolve_action_context on mission_runtime to get a CWD-invariant ExecutionContext and the single CommitTarget.
  3. Lifecycle mutation commands execute through the status/ OHS facade.
  4. The facade validates transitions, appends events, and materializes snapshots.

Loop B: Single-destination commit protection

  1. mission_runtime (or the planning-phase resolve_placement_only) produces one CommitTarget(ref, kind).
  2. commit_guard.evaluate decides — purely, from the target plus an asserted GuardCapability — whether the commit may land on that ref.
  3. The verdict echoes CommitTarget.ref as the resolved destination; the guard never re-derives a destination and never performs a push.

Loop C: Governance-context-scoped Ops

  1. The Op tier asks the Charter Engine for the action-scoped governance context.
  2. The Charter Engine resolves the active charter/doctrine (including org-charter.yaml extends: and DRG profile lineage).
  3. 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

  1. State transitions are host-authoritative; orchestrator, Team Kitty and trackers use contract surfaces only.
  2. Modules communicate through OHS facades; status internals are import-forbidden outside Mission Management.
  3. There is exactly one execution-state surface (mission_runtime) and one commit-protection decision (commit_guard.evaluate).
  4. 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.

Spec Kitty open core (producer ecosystem)

appends events

folded by

snapshots

read model

canonical reference beside Java

loads governance (extracting)

resolves doctrine

consumed

consumed

pinned and fetched

conforms to

extract to own open-core repo

consumed across contract

CLI(Python)
command surface + governance
open-core · exists

Event ledger
status.events.jsonl
append-only · sole lane authority
open-core · exists

Status reducer
status.reducer.materialize_snapshot
wall clock (at, event_id)
open-core · exists

Mission-Status Read API
Java service · spec-kitty-events service/
pinned: pins/read-service.source.yaml
overview + mission detail
open-core · released in spec-kitty-events · pinned by core (CI conformance only)

Charter
src/charter/offering/
governance / doctrine / DRG
open-core · extracting

Fetched packs
packs/built-in + packs/internal
open-core · exists (pinned, fetched from open-packs)

spec-kitty-events
pkg (wheel) · exists

spec-kitty-tracker
pkg (wheel) · exists

spec-kitty-open-packs
published packs · exists

doc-kitty
docs-site toolkit
pkg · exists

mission-status-api
own open-core repo
planned extraction

Mission-Status API contract
spec-kitty-events contracts/mission-status
+ conformance fixtures (pinned release assets)
producer → consumer boundary

Team Kittyconsumer (opaque)
mission-ui · pack composer
consumer

Traceability