Post-Implementation Review: Feature 054 — Charter Interview Compiler and Bootstrap

Field Value
Date 2026-03-10
Feature 054-charter-interview-compiler-and-bootstrap
Branch feature/agent-profile-implementation
Work Packages WP01–WP12 (all done)
Scope Phase 1 of Doctrine-to-Execution Integration

1. Implementation Quality Assessment

What shipped well

  1. Transitive reference resolution (reference_resolver.py): The DFS walker from directives through tactic_refs to styleguides/toolguides/procedures is clean and cycle-safe. The two-stage intersection (action index intersection project selections) prevents cross-action governance bleed — this is a key architectural invariant and it holds.

  2. Action index design: actions/<action>/index.yaml is the right abstraction. It decouples "what governance applies to this phase" from "what the project selected" and keeps the intersection logic in one place (context.py).

  3. Charter-as-configuration: The decision to not materialise a library/ directory and instead fetch live from DoctrineService on every context call is correct. It avoids stale-cache bugs and keeps the doctrine package as the single source of truth for shipped content.

  4. Depth semantics: The 1/2/3 depth model with first-load bootstrap (depth 2) and subsequent compact (depth 1) is pragmatic. It prevents prompt bloat while still giving agents a full governance boot on first encounter.

  5. ArtifactKind consolidation (WP09–WP10): Moving from scattered string constants to a canonical enum reduces an entire class of typo bugs and makes the artifact taxonomy explicit in code.

  6. MissionRepository extraction (WP11): Redirecting package resolution away from specify_cli/missions/ to src/doctrine/missions/ correctly positions missions as doctrine artifacts rather than CLI concerns.

  7. Stale content removal (WP12): Cleaning specify_cli/missions/ content removes the ambiguity about which directory is authoritative for mission templates.

What could be stronger

  1. Guidelines prose is still narrative: The guidelines.md files in actions/<action>/ are free-form markdown rather than structured artifacts with schema validation. They are the only doctrine content not governed by JSON Schema. This makes them opaque to tooling — you cannot programmatically query "which guidelines mention worktrees" without text search.

  2. Context output is a string blob: CharterContextResult.text is rendered markdown. Consumers (agents, connectors) cannot selectively parse out directive content vs. tactic steps vs. guidelines without regex. A structured alternative (list of typed sections) would enable smarter downstream processing.

  3. Depth semantics are implicit: The depth 1/2/3 behaviour is documented but not visible to consumers. An agent receiving depth-1 compact output has no structured way to request "give me tactic X at full depth" without re-requesting the entire context at depth 3.

  4. Test coverage disparity: The charter compiler and context modules have good coverage, but the integration between context.py and the actual command templates (the bootstrap injection point) is tested through snapshot fixtures rather than behavioural assertions. This makes the test suite fragile to formatting changes.

  5. Local support file declarations are additive-only: The design is correct (local supplements shipped, never overrides), but there is no mechanism for a project to suppress a shipped directive it disagrees with. The only option is to not select it — which is fine if you control the charter, but becomes a friction point if a team inherits a pre-built charter.

2. Architecture Documents Requiring Update

Must update

Document What changed Action
initiatives/2026-03-doctrine-execution-integration/README.md Phase 1 status is "In Progress" but feature 054 is complete Update Phase 1 to "Complete" with completion date. Note remaining deployment item (m_2_0_2 migration for slimmed templates).
04_implementation_mapping/README.md Table row for Agent Tool Connectors still says src/specify_cli/missions/*/command-templates/ Update to reflect src/doctrine/missions/*/command-templates/ as new source (WP11/WP12).
04_implementation_mapping/README.md "What is emerging or aspirational" table lists "Charter compiler consumes Doctrine" as emerging Move to "What exists and works today" — this is now fully implemented.
04_implementation_mapping/README.md Charter components table is incomplete Add Action Context Resolver charter/context.py as distinct component with depth semantics and action index intersection.
03_components/README.md Component diagram does not show ActionIndex or ContextBootstrap Add ActionIndex as a component within Doctrine, and ContextBootstrap as a component within Charter.

Should update (alignment)

Document Gap Action
02_containers/README.md Loop C (Governance) does not describe action-scoped context Extend Loop C to show the charter context --action <X> path as a sub-loop of execution, not just a setup step.
00_landscape/README.md Doctrine container description says "knowledge store" without mentioning mission-scoped action indexes Add a note that Doctrine now includes action-scoped governance indexes per mission type.
02_containers/runtime-execution-domain.md No mention of governance injection at execution boundary Add a note that every WP execution begins with a charter context bootstrap call.

No update needed

Document Reason
ADRs 2026-02-23-1 (Doctrine Governance) Feature 054 is a faithful implementation of this ADR — no divergence.
ADR 2026-02-09-1 (Status Model) Orthogonal to 054.
ADR 2026-02-17-1 (Next Command) 054 does not change the next-action loop contract.

3. Proximity to "Indoctrinating" the Spec Kitty Process

Assessment: Close, but not yet self-hosting.

The gap between "doctrine artifacts exist" and "doctrine artifacts govern every spec-kitty action" has narrowed significantly with 054. Here is the maturity scorecard:

Capability Maturity Evidence
Directive content available at runtime Production DoctrineService + transitive resolution operational
Action-scoped governance injection Production Action indexes + context bootstrap working for all 4 software-dev actions
Charter as typed configuration Production Interview → compile → context pipeline end-to-end
Agent profile shaping governance Partial Models + repository exist (048). Profile-aware resolution in resolver.py. Not yet auto-selected during implement.
Governance prose extracted from templates Partial guidelines.md per action exists. Templates still contain narrative prose that should be doctrine but isn't yet schema-governed.
All missions doctrine-governed Partial software-dev fully wired. documentation, plan, research missions have action directories but thinner indexes.
Doctrine governs its own curation Not started The curation pipeline (_proposed/ → shipped/) is manual. No doctrine artifact governs how curation decisions are made.
Template slimming deployed Not started Migration m_2_0_2 pending. Current templates still carry inline governance prose alongside the bootstrap section.

What "fully indoctrinated" looks like:

  1. Every command template contains only structural workflow instructions (create worktree, run tests, commit). All governance content is retrieved at runtime via charter context.
  2. The charter interview is itself governed by doctrine (a "meta-interview directive" that defines what questions must be asked).
  3. Agent profile selection is automatic based on the action being performed (implement → implementer profile, review → reviewer profile).
  4. Non-software-dev missions (documentation, research) have equally rich action indexes.
  5. The curation pipeline has its own doctrine — curate is a mission type with its own action indexes and governance.

Estimated remaining work:

  • Template slimming migration (m_2_0_2): 1 feature
  • Auto profile selection: 1 feature
  • Documentation/research mission parity: 1 feature each
  • Curation-as-mission: 1 feature (this is the self-hosting milestone)

4. Next Curation Steps

Immediate (before merging this branch to main)

  1. Update the doctrine-execution-integration initiative: Mark Phase 1 complete. Document what Phase 1 actually delivered vs. what was planned. Note the deferred items (m_2_0_2 migration, MissionTemplateRepository).

  2. Run artifact curation: The 054 spec noted curation is "ongoing" but not a hard blocker. Now that the pipeline is operational, curate the _proposed/ directives top-to-bottom. This is the quality gate before the next consumers can trust the content.

  3. Validate action index completeness: For each of the 4 software-dev actions, verify that every directive referenced in the index actually exists in shipped/ and passes schema validation. Run:

    pytest tests/doctrine/ -k "action_index or directive_consistency"

Short-term (next 1-2 features)

  1. Deploy slimmed templates (m_2_0_2): Strip inline governance prose from all 48 agent template copies. Templates should contain only:

    • Charter context bootstrap call
    • Structural workflow steps (create worktree, run tests, commit)
    • Feature-specific interpolation variables

  2. Enrich non-software-dev action indexes: The documentation, plan, and research mission action indexes are thin. Add directive and tactic references appropriate to each mission type.

Medium-term (next 2-4 features)

  1. Auto profile selection: Wire agent profile resolution into the implement / review / specify entry points so the correct profile is selected automatically, not manually during interview.

  2. Structured context output: Replace CharterContextResult.text (string blob) with a structured payload that consumers can selectively query. This unblocks smarter connectors (Phase 2).

5. Streamlining Mission Steps via Doctrine Artifacts

Problem: Repeated governance across mission actions

Currently, each command template (specify.md, plan.md, implement.md, review.md) contains:

  1. A charter context bootstrap section (standardised)
  2. Structural workflow instructions (action-specific)
  3. Residual governance prose (should be doctrine, isn't yet)

Items 1 and 3 are repetitive across actions. The bootstrap call is identical except for the --action parameter. The residual prose often restates directive intent that is already captured in the shipped directive YAML.

Solution: MissionStepContracts + runtime enrichment

Implemented: MissionStepContract is a new doctrine artifact type (src/doctrine/mission_step_contracts/). Each contract defines the structural steps of a mission action, with optional delegation to doctrine artifacts for concretization and a freeform guidance field for step-specific prose.

Shipped contracts exist for all 4 software-dev actions:

  • implement.step-contract.yaml (6 steps, paradigm delegation for workspace)
  • specify.step-contract.yaml (6 steps)
  • plan.step-contract.yaml (6 steps)
  • review.step-contract.yaml (6 steps)

Key design:

  • delegates_to.kind links a step to a doctrine artifact type (paradigm, tactic, directive) for concretization at runtime
  • delegates_to.candidates lists which artifacts could concretize the step; the charter's selections determine which one applies
  • guidance is a freeform field for additional step-specific instructions
  • command is an optional CLI command for purely structural steps

Access via DoctrineService:

service = DoctrineService()
contract = service.mission_step_contracts.get_by_action("software-dev", "implement")

Next step: Template slimming migration (m_2_0_2) can now render step contracts instead of inline governance prose.

Doctrine artifacts that replace repeated template prose:

Currently repeated Doctrine artifact that replaces it
"Run tests before committing" in every template Directive 030 (test-and-typecheck-quality-gate)
"Use smallest viable diff" in every template Tactic change-apply-smallest-viable-diff
"Sign commits with co-author" in every template Directive 029 (agent-commit-signing-policy)
Worktree discipline prose Toolguide worktree-management (to be created)
Pre-read verification instructions Directive 028 (search-tool-discipline)

This eliminates governance duplication across 48 template copies (12 agents x 4 actions) and makes doctrine the single source of truth for behavioural rules.

6. Execution Topology Is Not Doctrine-Configurable

What Changed

An earlier idea in this postmortem was to make git execution topology configurable through doctrine paradigms. That direction is now explicitly rejected.

Spec Kitty's current contract is:

  • execution lanes are mandatory planning output
  • each lane owns exactly one worktree
  • each mission owns exactly one integration branch
  • work-package branches and per-WP worktree fallback paths do not exist

Why The Earlier Proposal Was Wrong

Treating branching strategy as a doctrine selection would have made the most failure-prone part of the runtime polymorphic. That increases the number of states the planner, implementer, merger, dashboard, migrations, prompts, and tests all need to understand.

The lane-only runtime instead fixes a single execution topology and moves project choice higher up the stack:

  • charters can influence process, review discipline, risk posture, and implementation tactics
  • charters do not get to swap out the runtime's git topology
  • orchestration stays deterministic because lane planning is the sole source of workspace structure

Current Architectural Position

The correct indirection point is not "pick a git strategy at runtime." The correct model is:

tasks finalization computes execution lanes
  -> lanes.json becomes mandatory
  -> implement allocates the lane worktree
  -> review runs in that same lane worktree
  -> merge consumes lane branches into the mission branch

This keeps topology computation centralized and testable. It also guarantees that overlapping or dependency-coupled work packages are serialized through the same lane workspace instead of being allowed to diverge.

Postmortem Outcome

The actionable conclusion from this section is the opposite of the original proposal:

  • remove legacy topology branches from runtime code
  • remove topology selection prose from prompts and doctrine
  • keep lane allocation as the only execution path
  • fail closed when lane planning artifacts are missing

That simplification has now replaced the older "strategy-polymorphic" direction.

  • Feature 054 spec: kitty-specs/054-charter-interview-compiler-and-bootstrap/spec.md
  • Doctrine execution integration: docs/plans/initiatives/2026-03-doctrine-execution-integration/
  • Implementation mapping: docs/architecture/04_implementation_mapping/README.md
  • System landscape: docs/architecture/00_landscape/README.md
  • ADR Doctrine Governance: docs/adr/2.x/2026-02-23-1-doctrine-artifact-governance-model.md
Edit this page