Skip to content

Components (living)

Who is this for (1)
FieldValue
StatusLiving
Date2026-06-11 (charter service direction added 2026-10-03)
ScopeC4 Level 3 logical component view
Related ADRs2026-06-03-1, 2026-06-03-2, 2026-06-03-3, 2026-06-07-1, 2026-04-06-1, 2026-05-16-1, 2026-10-03-1

Purpose

Define component-level boundaries for Spec Kitty while remaining implementation-agnostic and behavior-focused, aligned to the four bounded modules and the Op tier.

Scope Rules

  1. Focus on conceptual components and contracts, not file/class listings.
  2. Explain behavior and interaction patterns that matter architecturally.
  3. Keep component definitions aligned with the container boundaries and the ADRs.

Component Diagram (Mermaid)

Shared Kernel

Execution / Runtime Module

Mission Management Module

Governance Module

CLI Command Surface

planning phase

GuardVerdict

terminology guard

Command Router

Workflow Command Set — specify/plan/tasks/implement/review/merge

Status Mutation Command Set

Op Command Set — dispatch

Charter Activation Engine

Charter Cascade (DRG-driven)

Org Charter Extends Resolver

Charter Offering Loader

Doctrine Relationship Graph

Agent Profile Repository

Glossary Corpus

Mission + WP Lifecycle

Lifecycle Command Gateway (status/ facade)

Event Reducer + Snapshot Materializer

Append-only Event Store

WP Lane State (State pattern)

resolve_action_context

resolve_placement_only

resolve_status_surface_with_anchor

Context Fragments — Identity/BranchRef/Workspace/StatusSurface/Placement/PromptSource

Workspace + Worktree Coordinator

CommitTarget(ref, kind)

commit_guard.evaluate

GuardCapability

Op Invocation Context — open/close Op

Planned Charter Service Components

The planned service uses separate read and later write application modules over one pure domain. Every infrastructure dependency points inward through a port. The Python charter API seam, planned under #645, stays outside this hexagon. See ADR 2026-10-03-1.

Outbound infrastructure

Pure charter domain

Application

Inbound infrastructure

planned read delegation

future migrated writes

planned governed read

constrains

constrains

constrains

constrains

constrains

Python charter API seam (src/charter) — planned (#645), transport client only

Agent harness — planned MCP client

REST adapter — planned

MCP adapter — planned

Write adapter — future

Read application — planned

Write application — future

Domain models

Validation, merge, activation, resolution policies

Repository ports

Lossless YAML adapter — future write path

Document projection adapter — format deferred

SQL adapter — future and deferred

Charter contract: contracts/charter/ and conformance fixtures

Read and write applications do not depend on each other. Domain components import no YAML, JSON, HTTP, MCP, database, or application-framework library. The SQL adapter is a replaceable storage edge, not a domain or API change. Direct MCP and Python-seam reads converge on the same read application. The seam sits in the charter layer and holds only a transport client. Service launch and lifecycle stay in specify_cli, so charter has no outbound edge to specify_cli.

Component Responsibility Map

ComponentModuleResponsibility
Command RouterCLINormalizes and dispatches commands to the correct surface
Workflow Command SetCLIDrives specify/plan/tasks/implement/review/merge command families
Status Mutation Command SetCLIHandles lane-transition and status-mutation commands
Op Command SetCLIHandles spec-kitty dispatch governed invocations
Op Invocation ContextOp TierOpens an Op under resolved governance context and closes it with the real outcome
Charter Activation EngineGovernancePlan/commit activation seam; writes config only after plan succeeds
Charter CascadeGovernanceFollows DRG requires/suggests edges for cascade (de)activation
Org Charter Extends ResolverGovernanceCanonical org-charter.yaml extends: chain resolver (charter.org_extends): base-first order, fail-closed on cycles/missing bases; the legacy loader delegates here
Charter Offering LoaderGovernanceLoads doctrine assets as typed artifacts; surfaces load diagnostics
Doctrine Relationship GraphGovernanceGenerated edge graph; resolves profile lineage (specializes_from)
Agent Profile RepositoryGovernanceResolves agent profiles via DRG traversal
Glossary CorpusGovernanceCanonical terminology surface and drift guard
Mission + WP LifecycleMission MgmtOwns mission/WP lifecycle precedence and dependency gating
Lifecycle Command GatewayMission MgmtThe status/ OHS facade — normalizes lifecycle mutation requests
Event Reducer + Snapshot MaterializerMission MgmtDeterministically reduces the event log to a snapshot
Append-only Event StoreMission MgmtJSONL event I/O with corruption detection — sole lane authority
WP Lane State (State pattern)Mission MgmtModels lane behavior per the State pattern (2026-04-06-1)
resolve_action_contextExecutionResolves CWD-invariant ExecutionContext + single CommitTarget
resolve_placement_onlyExecutionWP-less planning projection over the same resolution authority
resolve_status_surface_with_anchorExecutionSingle-pass status surface + primary anchor; fails closed
Context FragmentsExecutionCohesive value-object fragments composed per operation (op-composite)
Workspace + Worktree CoordinatorExecutionResolves/reuses the execution workspace
CommitTarget(ref, kind)Shared KernelThe one destination ref + topology kind for artifacts and status
commit_guard.evaluateShared KernelThe ONE commit-protection decision (pure; echoes target.ref)
GuardCapabilityShared KernelAsserted-at-the-surface authorization parameter to evaluate

Canonical-shape notes

  • 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).
  • CommitTarget is (ref, kind), not (worktree_root, destination_ref) — see the 2026-06-10 addendum to ADR docs/adr/3.x/2026-06-03-2-executioncontext-owner-and-committarget.md.
  • 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
GovernanceCharter Activation Engine, Charter Cascade, Org Charter Extends Resolver, Charter Offering Loader, Doctrine Relationship Graph, Agent Profile Repository, Glossary Corpus
Mission ManagementMission + WP Lifecycle, Lifecycle Command Gateway, Event Reducer + Snapshot Materializer, Append-only Event Store, WP Lane State
Execution / Runtimeresolve_action_context, resolve_placement_only, resolve_status_surface_with_anchor, Context Fragments, Workspace + Worktree Coordinator
Shared KernelCommitTarget(ref, kind), commit_guard.evaluate, GuardCapability
Op Tier (cross-module)Op Command Set, Op Invocation Context

Behavioral Sequences

Sequence A: Execution-state resolution (CWD-invariant)

CommitTarget(ref, kind)resolve_action_contextMission + WP LifecycleCommand RouterHuman/AgentCommitTarget(ref, kind)resolve_action_contextMission + WP LifecycleCommand RouterHuman/Agentinvoke a mission actiondispatch lifecycle commandresolve_action_context(repo_root, action, ...)assemble fragments and resolve target_branch onceproduce single CommitTargetExecutionContext + CommitTarget

Sequence B: Lifecycle mutation and single-destination commit protection

commit_guard.evaluateCommitTarget(ref, kind)Event ReducerWP Lane StateLifecycle Command Gateway (status/)Human/Agentcommit_guard.evaluateCommitTarget(ref, kind)Event ReducerWP Lane StateLifecycle Command Gateway (status/)Human/Agentrequest lifecycle transitionvalidate guarded transitionappend event + materialize snapshottake resolved destinationevaluate(target, protection_state, capability)GuardVerdict (resolved_destination echoes target.ref)

Sequence C: Profile-governed Op invocation

Doctrine Relationship GraphCharter Activation EngineOp Invocation ContextOp Command SetHuman/AgentDoctrine Relationship GraphCharter Activation EngineOp Invocation ContextOp Command SetHuman/Agentspec-kitty dispatchopen Opload action-scoped governance contextresolve active artifacts + profile lineageresolved governance contextdo the work under context, then close Op with outcome

Sequence D: Charter activation and cascade

Doctrine Relationship GraphCharter CascadeCharter Activation EngineHuman In ChargeDoctrine Relationship GraphCharter CascadeCharter Activation EngineHuman In Chargecharter activate <kind> <artifact> --cascadeplan_activation (non-mutating validation)follow requires/suggests edgesresolve cascade set (shared-reference safe)commit_activation (writes config only after plan succeeds)

Canonical work package FSM

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

Guard summary:

  1. Canonical lanes: planned, claimed, in_progress, for_review, in_review, approved, done, blocked, canceled.
  2. done and canceled are terminal unless an explicit force override is used.
  3. doing is an input alias for in_progress and is never persisted.
  4. Transition guards are transition-specific (actor, workspace context, review reference, done evidence, explicit reason fields).
  5. Dependency gating: a WP cannot be claimed/implemented until every dependency is approved or done.

Coupling and Trade-off Notes

  1. A single execution-state surface (mission_runtime) trades a new top-level package for domain clarity and re-derivation prevention.
  2. A single commit-protection decision (commit_guard.evaluate) makes authorization greppable and auditable for the LLM-agent threat model.
  3. OHS facades keep status internals private to Mission Management.
  4. Governance/doctrine coupling is deliberate to preserve policy traceability.

Decision Traceability

Traceability