# Initiative: 2026-03 Doctrine-to-Execution Integration

This initiative captures the assessment and roadmap for wiring the doctrine
repository layer (delivered in feature 046) into the charter resolver,
mission template system, and execution dispatch chain.

## Context

Feature 046 delivered typed Pydantic models and repository services for all
6 doctrine artifact types (directives, tactics, paradigms, styleguides,
toolguides, agent profiles). These are loadable on-demand through
`DoctrineService` but are not yet consumed by the execution pipeline.

The current execution flow resolves governance through string-based lookups
in `governance.yaml` and injects charter summaries into agent prompts.
Agents receive directive titles but not the enriched content (procedures,
tactic_refs, scope, validation_criteria) that was added in 046.

## Current Execution Flow (As-Is)

```
CLI (spec-kitty implement WP01)
  |
  v
implement.py: create worktree and context
  |
  v
prompt_builder.py: build_prompt()
  |-- Load mission config (software-dev/mission.yaml)
  |-- Load command template (software-dev/command-templates/implement.md)
  |-- Load charter (build_charter_context)
  |     |-- Parse charter.md (first load only)
  |     |-- Resolve governance (directives as strings, paradigms as strings)
  |     +-- Inject summary + references into prompt
  +-- Assemble final prompt with governance context
  |
  v
Rendered markdown prompt -> Agent (12 adapter formats)
```

**Key gap**: The charter resolver uses `governance.yaml` with string-based
directive/paradigm references. It does not call `DoctrineService` to retrieve
the full typed artifacts with procedures, tactic steps, and cross-references.

## Target Execution Flow (To-Be)

```
CLI (spec-kitty implement WP01)
  |
  v
implement.py: create worktree and context
  |
  v
prompt_builder.py: build_prompt()
  |-- Load mission template (via MissionTemplateRepository)
  |-- Load command template (doctrine artifact, not inline markdown)
  |-- Load charter
  |     |-- Resolve governance via DoctrineService
  |     |-- DoctrineService.directives.get(id) -> full Directive with procedures
  |     |-- Resolve tactic_refs -> full Tactic objects with steps
  |     +-- Inject enriched, actionable governance into prompt
  +-- Assemble prompt with on-demand depth loading
  |
  v
Connector interface contract -> Agent adapter (pluggable)
```

## Implementation Status

| Phase | Status | Feature |
|-------|--------|---------|
| Phase 1: Charter Resolver + Mission Template Extraction | ✅ Complete (2026-03-10) | `054-charter-interview-compiler-and-bootstrap` |
| Phase 2: Connector Interface Contract | Planned | TBD |
| Phase 3: Event Store Interface Abstraction | Deferred | TBD |

---

## Roadmap: Three Phases

### Phase 1: Charter Resolver + Mission Template Extraction (single mission)

**Goal**: Wire `DoctrineService` into the charter resolver and extract
inline mission governance into proper doctrine artifacts.

**Scope** (as implemented in feature 054):

1. Replace string-based directive lookups in `charter/resolver.py` with
   `DoctrineService.directives.get(id)` calls. Inject full directive content
   (intent, procedures, tactic_refs, scope) into agent prompts.

2. Resolve `tactic_refs` transitively: when a directive references tactics,
   load the full `Tactic` objects with steps and inject them as actionable
   procedure guidance.

3. Extract inline governance from `software-dev` command templates
   (`specify.md`, `plan.md`, `implement.md`, `review.md`) into per-action
   doctrine files at `src/doctrine/missions/software-dev/actions/<action>/guidelines.md`.
   Templates reference IDs and retrieve content at runtime via `charter context`.

4. Implement action-scoped iterative deepening in `charter context` via `--depth <1|2|3>`:
   - Retrieval is scoped via two-stage intersection: action index (`actions/<action>/index.yaml`) ∩ project selections (`references.yaml`). Prevents cross-action content bleed.
   - Each artifact type fetched via its own dedicated repository service (`DirectiveRepository`, `TacticRepository`, etc.) — no cross-type fetches.
   - Depth 1 (compact): directive titles + tactic IDs for the action scope
   - Depth 2 (bootstrap): full directive procedures + tactic steps via `DoctrineService` for the action scope
   - Depth 3 (explicit): adds styleguide/toolguide details + per-action mission guidelines

5. Charter treated as configuration layer only — `generate` no longer
   materialises content into `.kittify/charter/library/`. All content
   retrieved live from `DoctrineService` on each `context` call.

6. Deploy slimmed templates to all 48 agent copies via migration `m_2_0_2`.

**Entry point**: `src/specify_cli/charter/context.py`, `src/specify_cli/charter/resolver.py`.

**Note on MissionTemplateRepository**: Creation deferred to a follow-on feature.
The `src/doctrine/missions` package is used directly by `context.py` for
action guidelines in this iteration.

**Prerequisite status**: Curation cycle is ongoing. Feature 054 proceeded against
the current 046 artifacts; full curation alignment was not a hard blocker for
Phase 1 mechanics.

**Completion notes** (2026-03-10): All 12 WPs merged. Remaining deployment item:
migration `m_2_0_2` for slimmed agent templates (tracked separately).
`MissionTemplateRepository` creation deferred to follow-on work. See
`2026-03-054-postmortem/README.md` for full review.

### Phase 2: Connector Interface Contract (separate mission)

**Goal**: Formalize the boundary between Orchestration and Agent Tool
Connectors so external execution engines can be plugged in.

**Scope**:

1. Define a formal `ConnectorProtocol` (Python Protocol) that agent adapters
   must implement. Current 12 markdown template adapters become the reference
   implementation.

2. Abstract prompt dispatch from the current render-to-file approach into a
   contract: `dispatch(wp_context, governance_context) -> ExecutionResult`.

3. Create adapter implementations for at least one external tool as proof
   of concept.

**External tool mapping**:

| Tool | Fits As | Role in Architecture |
|------|---------|---------------------|
| Kestra | Orchestration engine | DAG executor for WP dependency graphs. Event-sourced. Replaces in-process WP scheduling. |
| n8n | Orchestration engine (visual) | Visual DAG executor with webhook-driven agent connector triggers. |
| PromptFlow | Agent Tool Connector | Microsoft's prompt chaining structures prompt -> agent -> result with tracing. |
| Semantic Kernel | Agent Tool Connector SDK | Programmatic adapter layer. Plugins map to governance injection point. |
| LangFlow | Agent Tool Connector (visual) | Visual prompt flow builder for doctrine-enriched prompt construction. |

**Key architectural insight**: None of these replace Kitty-core (planning,
doctrine, charter). They replace the execution machinery. Principle 2
(implementation-agnostic boundaries) means the Orchestration container's
interface contract stays the same regardless of backend.

**Integration pattern**:

```
Kitty-core (doctrine + planning)
  |
  v  [interface contract]
Orchestration (Kestra / n8n / in-process)
  |
  v  [connector contract]
Agent adapter (PromptFlow / SK / LangFlow / markdown templates)
```

### Phase 3: Event Store Interface Abstraction

**Goal**: Formalize the Event Store container boundary so alternative backends
(database, remote service) can replace the current filesystem implementation.

**Deferred**: Lower priority than Phases 1-2. The current filesystem-based
event store (JSONL + frontmatter) works for local-first operation.

## Critical Path

```
Curation cycle (interactive review of 046 artifacts)
  |
  v
Phase 1: Charter resolver + mission template extraction
  |
  v
Phase 2: Connector interface contract
  |
  v
Phase 3: Event store abstraction (deferred)
```

Phase 1 is complete. Phase 2 is now the critical path item.

## Curation Prerequisite

Before Phase 1, all 046 doctrine artifacts must be reviewed through an
interactive curation cycle to confirm alignment with project owner intent:

- 26 enriched directives (001-026): intent, procedures, tactic_refs, scope
- 12 shipped tactics: steps, references, operational guidance
- Paradigm extensions: opposed_by tensions, tactic_refs wiring
- 7 new directives (020-026): validate these are the right concepts to formalize

**Method**: Top-to-bottom vertical slices per directive. For each directive,
review intent -> scope -> procedures -> tactic_refs (resolve to full tactics)
-> opposed_by tensions. Confirm or adjust at each layer.

## Feature 055 — Doctrine Stack Init & Profile Integration

### Architectural Assessment (2026-03-20)

Feature 055 fills the remaining gaps between the doctrine repository layer (046)
and runtime execution. It targets three integration surfaces:

1. **Init-time doctrine onboarding** — Embeds charter setup into
   `spec-kitty init` (accept defaults or inline interview). Closes the gap
   where governance activation was a disconnected discovery step.

2. **Profile injection at workflow execution** — The implement workflow resolves
   agent profiles from WP frontmatter and injects identity fragments into the
   prompt. Same injection pattern as charter governance context
   (`_render_charter_context()` in `workflow.py`). This makes profiles
   functional participants in the Execution Coordination behavior loop
   (see `architecture/2.x/02_containers/README.md`).

3. **Default fallback identity (`generic-agent`)** — Proposed in `_proposed/`
   with single directive reference. Ensures backward compatibility for projects
   without explicit profile assignments.

### Relationship to Initiative Phases

| Initiative Phase | 055 Contribution |
|------------------|------------------|
| Phase 1 (Charter Resolver) | Extends: init-time charter generation from defaults or interview answers |
| Phase 2 (Connector Interface) | Prepares: profile identity fragments become part of the governance context payload that connectors must carry |
| Curation Prerequisite | Respects: `generic-agent` profile + directive start in `_proposed/`, require HIC review before promotion |

### Scope Boundaries

055 does **not** address:
- Profile injection for non-implement workflows (review, accept). Natural follow-on.
- Profile inheritance resolution (045-WP15). `generic-agent` is standalone.
- Connector protocol formalization (Phase 2). 055 uses the current render-to-file path.
- Modular code refactoring (004). Orthogonal file sets, no functional dependency.

### Pre-work Included

- **`--feature` → `--mission` rename** (issue #241): Boy Scout cleanup of
  terminology drift. Introduces `--mission` as canonical flag, preserves
  `--feature` as deprecated alias with warning. Scoped as pre-work to avoid
  introducing new `--feature` references in 055's init and workflow changes.

### Architectural Dependencies

- `AgentProfileRepository` (045-WP02): shipped, provides two-source profile resolution
- `DoctrineService` (046): shipped, provides typed artifact access
- Charter resolver (054): shipped, provides action-scoped context injection
- Profile CLI (`agent profile show/list`): shipped (045-WP07), used by `profile-context` template

### Gap Analysis: Issue #284 (Customizable Git Strategy)

This direction is now obsolete. Later runtime work standardized on mandatory
execution lanes and removed configurable git-topology branches from the active
system.

What 055 still proves is narrower and still valid:
- doctrine artifacts can be resolved at runtime and injected into execution
  context
- profile defaults can be overridden by project-level selections

What 055 does **not** imply anymore:
1. Git execution topology should be doctrine-configurable
2. The orchestrator should become strategy-polymorphic
3. The charter should decide between multiple workspace/branching models

Current position:
- doctrine influences behavior inside the lane-only runtime
- doctrine does not select between competing git execution strategies
- `lanes.json` and the lane allocator are the only source of workspace topology

## Observation: Agent Hook-Based Enforcement

Some agentic tooling providers support **pre-tool-use hooks** — shell scripts
that intercept and rewrite tool calls before execution. Claude Code's
`PreToolUse` hook is the reference implementation: it can transparently rewrite
`git status` → `rtk git status` without requiring the agent to be aware of the
proxy, providing deterministic enforcement of tooling guidance like DIRECTIVE_028.

### Architectural implications

Hook-based enforcement sits at a **different layer** than doctrine injection:

```
Doctrine (directives, toolguides)        ← guidance layer (all agents)
  |
  v
Charter context injection           ← prompt layer (all agents)
  |
  v
Agent hook rewrite (PreToolUse)           ← enforcement layer (select agents only)
```

The guidance and prompt layers are universal — every agent receives tooling
directives through the charter context pipeline. The hook layer is an
**optional acceleration** that provides deterministic enforcement for agents
whose host environment supports it.

### Provider support matrix (known)

| Provider | Hook support | Enforcement path |
|----------|-------------|------------------|
| Claude Code | Yes (`PreToolUse`, `PostToolUse`) | Shell script intercepts and rewrites Bash tool calls |
| GitHub Copilot | No | Directive-only (prompt layer) |
| Cursor | No | Directive-only (prompt layer) |
| Windsurf | No | Directive-only (prompt layer) |
| Others | Unknown | Assume directive-only until verified |

### Design rule

**Hooks must not be the sole mechanism for enforcing tooling behavior.** The
doctrine stack (directive + toolguide + charter context) is the primary
guidance layer and must be sufficient on its own. Hooks are a deterministic
accelerator when available — they reduce token waste and eliminate agent
decision overhead — but the system must degrade gracefully to directive-only
guidance when hooks are not supported.

This means:
1. Directives and toolguides must contain complete guidance (not "use the hook")
2. Charter context injection must surface tooling preferences in prompts
3. Hooks are additive enforcement, not a replacement for prompt-layer governance
4. Agent-specific hook configurations belong in the agent's environment
   (e.g., `.claude/settings.json`), not in doctrine artifacts

## Related Artifacts

- Feature 046 spec: `kitty-specs/046-doctrine-artifact-domain-models/spec.md`
- System Landscape: `architecture/2.x/00_landscape/README.md`
- Implementation Mapping: `architecture/2.x/04_implementation_mapping/README.md`
- Current resolver: `src/specify_cli/charter/resolver.py`
- Current prompt builder: `src/specify_cli/next/prompt_builder.py`
- Mission schema: `src/doctrine/schemas/mission.schema.yaml`
- DoctrineService: `src/doctrine/service.py`
- Feature 055 spec: `kitty-specs/055-doctrine-stack-init-and-profile-integration/spec.md`
- Issue #284: Hardened and customizable git usage
- Issue #241: Rename `--feature` flag to `--mission`
