2.x Components

Field	Value
Status	Draft
Date	2026-03-01
Scope	C4 Level 3 logical component view
Related ADRs	`2026-01-29-13`, `2026-02-09-1..4`, `2026-02-17-1..3`, `2026-02-23-1..3`, `2026-02-25-1..3`

Purpose

Define component-level boundaries for Spec Kitty 2.x while remaining implementation-agnostic and behavior-focused.

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 container boundaries and ADR decisions.

Component Diagram (Mermaid)

flowchart TB
    subgraph CLI["CLI Command Surface"]
      router[Command Router]
      workflow[Workflow Command Set]
      statusCmd[Status Mutation Command Set]
      governanceCmd[Governance Command Set]
      apiCmd[Orchestrator API Command Set]
    end

    subgraph Runtime["Runtime and Mission Resolver"]
      nextLoop[Next Loop Coordinator]
      missionResolve[Mission Discovery and Resolution]
      runtimeAsset[Runtime Asset Lifecycle Coordinator]
      templateResolve[Tiered Template Resolution Pipeline]
      runtimeMigration[Runtime Asset Migration Path]
      featureCtx[Feature Context Detection]
      decisionOut[Next-Action Recommendation Output]
    end

    subgraph Governance["Charter and Governance Engine"]
      interview[Charter Interview Flow]
      compile[Charter Compiler]
      ctxResolve[Action Context Resolver]
    end

    subgraph Knowledge["Doctrine and Glossary"]
      doctrineCatalog[Doctrine Catalog Loader]
      schemaGate[Schema Validation Gate]
      glossaryHook[Glossary Hook Coordinator]
    end

    subgraph State["Status and Event Model Layer"]
      lifecycleGateway[Lifecycle Command Gateway]
      targetRouter[Target-Line Router]
      wpLifecycle[WP Lifecycle Engine]
      eventSemantics[Event Semantics Reducer]
    end

    subgraph Sync["Sync Reliability Core"]
      syncRuntime[Sync Runtime Coordinator]
      syncIdentity[Sync Identity Resolver]
      syncClock[Lamport Clock Coordinator]
      syncQueue[Offline Queue Manager]
      syncTransport[Sync Transport Session]
      trackerGateway[Tracker Connector Gateway]
    end

    router --> workflow
    router --> statusCmd
    router --> governanceCmd
    router --> apiCmd

    workflow --> nextLoop
    nextLoop --> missionResolve
    missionResolve --> runtimeAsset
    runtimeAsset --> templateResolve
    runtimeAsset --> runtimeMigration
    nextLoop --> featureCtx
    nextLoop --> decisionOut

    governanceCmd --> interview
    interview --> compile
    compile --> ctxResolve

    missionResolve --> doctrineCatalog
    doctrineCatalog --> schemaGate
    nextLoop --> glossaryHook
    glossaryHook --> doctrineCatalog

    statusCmd --> lifecycleGateway
    apiCmd --> lifecycleGateway
    lifecycleGateway --> targetRouter
    targetRouter --> wpLifecycle
    wpLifecycle --> eventSemantics
    eventSemantics --> syncRuntime
    syncRuntime --> syncIdentity
    syncRuntime --> syncClock
    syncRuntime --> syncQueue
    syncRuntime --> syncTransport
    syncTransport --> trackerGateway

Component Responsibility Map

Component	Responsibility
Command Router	Normalizes and dispatches commands to the correct capability surface
Workflow Command Set	Drives specify/plan/tasks/implement/review/merge command families
Status Mutation Command Set	Handles lane transition and status-mutation command families
Governance Command Set	Handles charter/guidance workflow interactions
Orchestrator API Command Set	Handles API-surface lifecycle operations
Next Loop Coordinator	Governs canonical per-agent execution sequencing
Mission Discovery and Resolution	Selects mission/runtime assets by deterministic precedence
Runtime Asset Lifecycle Coordinator	Coordinates runtime bootstrap, tier selection, and compatibility checks
Tiered Template Resolution Pipeline	Resolves prompt/template payloads by configured precedence tiers
Runtime Asset Migration Path	Applies forward-compatible migration behavior for legacy runtime assets
Feature Context Detection	Determines active feature context without ambiguous heuristics
Next-Action Recommendation Output	Emits decisioning output without applying lifecycle mutation
Charter Interview Flow	Captures governance intent from the Human in Charge
Charter Compiler	Produces charter bundles and references
Action Context Resolver	Provides command-scoped governance context
Doctrine Catalog Loader	Loads doctrine assets as typed artifacts
Schema Validation Gate	Enforces artifact compliance before runtime use
Glossary Hook Coordinator	Applies glossary checks during mission execution
Lifecycle Command Gateway	Normalizes lifecycle mutation requests before state transition validation
Target-Line Router	Resolves routing intent from feature metadata (`target_branch`)
WP Lifecycle Engine	Enforces canonical work-package state transitions
Event Semantics Reducer	Materializes authoritative state from event logs
Sync Runtime Coordinator	Owns sync runtime lifecycle and projection scheduling behavior
Sync Identity Resolver	Adds and backfills identity attribution for emitted events
Lamport Clock Coordinator	Maintains monotonic event ordering across projections
Offline Queue Manager	Persists events for eventual sync when transport/auth is unavailable
Sync Transport Session	Manages authenticated realtime and delivery sessions
Tracker Connector Gateway	Adapts host state to external tracker APIs

Domain Alignment Matrix

See 2.x Domain Breakdown for domain-level definitions.

Domain	Primary Components
Project and Governance Onboarding	`Governance Command Set`, `Charter Interview Flow`, `Charter Compiler`
Mission Runtime and Flow Control	`Command Router`, `Next Loop Coordinator`, `Mission Discovery and Resolution`, `Runtime Asset Lifecycle Coordinator`, `Tiered Template Resolution Pipeline`, `Next-Action Recommendation Output`
Doctrine and Knowledge Governance	`Doctrine Catalog Loader`, `Schema Validation Gate`, `Glossary Hook Coordinator`
Work Package State and Evidence	`Status Mutation Command Set`, `Lifecycle Command Gateway`, `Target-Line Router`, `WP Lifecycle Engine`, `Event Semantics Reducer`, `Feature Context Detection`
External Integration Boundaries	`Orchestrator API Command Set`, `Sync Runtime Coordinator`, `Sync Transport Session`, `Tracker Connector Gateway`

Behavioral Sequences

Sequence A: Canonical `next` Decisioning (No Direct Mutation)

sequenceDiagram
    participant User as Human/Agent
    participant Router as Command Router
    participant Loop as Next Loop Coordinator
    participant Mission as Mission Discovery and Resolution
    participant Doctrine as Doctrine Catalog Loader

    User->>Router: invoke next-style command
    Router->>Loop: dispatch runtime action
    Loop->>Mission: resolve mission assets
    Mission->>Doctrine: load and validate doctrine context
    Doctrine-->>Loop: validated context
    Loop-->>User: next-action recommendation

Sequence B: Lifecycle Mutation and Target-Line Routing

sequenceDiagram
    participant User as Human/Agent
    participant Router as Command Router
    participant StatusCmd as Status Mutation Command Set
    participant Route as Target-Line Router
    participant State as WP Lifecycle Engine
    participant Events as Event Semantics Reducer

    User->>Router: invoke lifecycle mutation
    Router->>StatusCmd: dispatch mutation command
    StatusCmd->>Route: resolve target-line routing
    Route->>State: validate guarded transition
    State->>Events: append event and materialize state
    Events-->>User: mutation result and authoritative state

Sequence C: Sync Projection Reliability Path

sequenceDiagram
    participant Events as Event Semantics Reducer
    participant Sync as Sync Runtime Coordinator
    participant Identity as Sync Identity Resolver
    participant Clock as Lamport Clock Coordinator
    participant Queue as Offline Queue Manager
    participant Transport as Sync Transport Session
    participant Tracker as Tracker Connector Gateway

    Events->>Sync: enqueue projection candidate
    Sync->>Identity: ensure event identity
    Sync->>Clock: assign ordering metadata
    Sync->>Queue: persist durable queue item
    Sync->>Transport: attempt authenticated delivery
    Transport->>Tracker: project tracker update

Sequence D: Governance Update and Runtime Reuse

sequenceDiagram
    participant Human as Human In Charge
    participant GovCmd as Governance Command Set
    participant Interview as Charter Interview Flow
    participant Compile as Charter Compiler
    participant Resolver as Action Context Resolver

    Human->>GovCmd: start governance update
    GovCmd->>Interview: collect governance answers
    Interview->>Compile: compile charter bundle
    Compile->>Resolver: refresh action context projection
    Resolver-->>GovCmd: updated governance context
    GovCmd-->>Human: confirmation and next actions

Canonical Work Package FSM

stateDiagram-v2
    [*] --> planned
    planned --> claimed: claim (actor)
    claimed --> in_progress: start (workspace_context)
    in_progress --> for_review: ready_for_review (subtasks + evidence)
    for_review --> done: approve (done evidence)

    for_review --> in_progress: changes_requested (review_ref)
    for_review --> planned: replan (review_ref)
    in_progress --> planned: reassign (reason)

    planned --> blocked: blocked
    claimed --> blocked: blocked
    in_progress --> blocked: blocked
    for_review --> blocked: blocked
    blocked --> in_progress: unblock

    planned --> canceled: cancel
    claimed --> canceled: cancel
    in_progress --> canceled: cancel
    for_review --> canceled: cancel
    blocked --> canceled: cancel

Guard summary:

Canonical lanes: planned, claimed, in_progress, for_review, done, blocked, canceled.
done and canceled are terminal unless an explicit force override is used.
Transition guard requirements are transition-specific and include actor, workspace context, review reference, done evidence, and explicit reason fields.

Coupling and Trade-off Notes

next loop centralization improves consistency but requires strict mission compatibility discipline.
Runtime decisioning and lifecycle mutation are intentionally separated, reducing hidden side effects.
Governance and doctrine coupling is deliberate to preserve policy traceability.
Sync reliability internals are explicit because ordering/durability constraints affect system behavior.
Tracker connector isolation keeps third-party integration optional and bounded.

Decision Traceability

Traceability

Domain map: ../README.md#domain-breakdown
Usage flow reference: ../README.md#usage-flow-high-level-user-journey
Context view: ../01_context/README.md
Container view: ../02_containers/README.md
Runtime loop ADR: ../adr/2026-02-17-1-canonical-next-command-runtime-loop.md
Doctrine governance ADR: ../adr/2026-02-23-1-doctrine-artifact-governance-model.md

2.x Components

Purpose

Scope Rules

Component Diagram (Mermaid)

Component Responsibility Map

Domain Alignment Matrix

Behavioral Sequences

Sequence A: Canonical next Decisioning (No Direct Mutation)

Sequence B: Lifecycle Mutation and Target-Line Routing

Sequence C: Sync Projection Reliability Path

Sequence D: Governance Update and Runtime Reuse

Canonical Work Package FSM

Coupling and Trade-off Notes

Decision Traceability

Traceability

Sequence A: Canonical `next` Decisioning (No Direct Mutation)