Contracts

capstone-compile.md

Contract — Capstone charter compile (IC-05 / FR-014 / C-007)

The capstone WP MUST follow this ordered sequence. Order is load-bearing.

Preconditions

  • All conversion WPs approved; the wiring WP has run the single graph.yaml regeneration and tests/doctrine/drg/* are green.
  • The existing .kittify/charter/charter.md (v1.1.5) is read first — this is a reconcile, not a greenfield compile.

Sequence (activate → generate; NEVER the reverse)

1. Confirm graph + health: pytest tests/doctrine/drg/ -q green; spec-kitty doctor doctrine --json healthy. 2. Activate: spec-kitty charter activate <kind> <id> --cascade … for the catfooding artifacts. Writes .kittify/config.yaml activated_<kind> lists. (Activation ≠ generation — this step does not render the charter.) 3. Mirror answers (named manual sub-step — no auto-bridge): edit .kittify/charter/interview/answers.yaml so selected_directives/selected_tactics/… include the activated catfooding IDs. Without this, charter generate renders a charter that references none of them. 4. Generate: spec-kitty charter generate. Renders charter.md + references.yaml from answers + the activation-filtered DRG closure (this is why step 2 precedes step 4). 5. Reconcile: ensure the regenerated charter.md supersedes v1.1.5 coherently (version bump, existing content preserved/merged — not clobbered).

Acceptance (C-007 / NFR-003 / SC-003)

  • charter.md + references.yaml regenerated from the activated set; version past 1.1.5.
  • Reference closure non-shallow: every activated catfooding artifact's requires/suggests edges resolve in references.yaml (not just direct interview selections).
  • spec-kitty doctor doctrine --json healthy after compile.
  • spec-kitty charter list shows all 8 sections represented (SC-001).

Failure modes to guard

  • generate-before-activate → shallow closure (WRONG order).
  • skipping the answers mirror → charter references no catfooding directives.
  • greenfield generate → clobbers v1.1.5.

conversion-dod.md

Contract — Per-conversion Definition of Done

Every §-conversion WP (IC-02, IC-03) MUST satisfy this contract. It operationalizes C-001 + C-002.

Pre-conditions (first subtask — the overlap-audit, C-001)

1. Read the enumerated existing artifact(s) for this section (see data-model.md inventory). 2. Record an explicit augment-vs-create decision per target (DIRECTIVE_003): what already exists, what atom is uncovered, whether to extend/reference/create, and the chosen artifact kind. 3. If the audit shows the rule is fully covered → do NOT author a new artifact; extend/reference only. (A new artifact restating an existing rule fails review — NFR-002.)

Authoring

4. Author/extend the artifact(s) at the correct kind (per D-2). §1 MUST NOT be enforcement: required (C-006). 5. Author the artifact's inline DRG edges (requires/suggests/refines) in the YAML. Do NOT regenerate graph.yaml — that is the wiring WP's job (PD-2). 6. Stay within owned_files; shared surfaces are single-owner (C-003).

Gates (before move-to-for_review)

7. spec-kitty doctor doctrine --json → 0 skipped / 0 invalid (NFR-001). Note: doctor-green is NOT schema proof for newly-authored artifacts. doctor doctrine reports org/pack/selection/profile health — it does NOT schema-validate a newly-authored built-in directive/tactic/procedure/styleguide/toolguide. A malformed new artifact YAML passes doctor-green; real schema validation is gated in WP12's DRG tests. To catch schema errors at per-WP review (before WP12), run the targeted per-artifact gate below. 8. PWHEADLESS=1 python -m pytest tests/doctrine/drg/test_shipped_graph_valid.py -q → green for all newly authored or extended artifacts in this WP. This is the per-artifact schema validation gate. Run it against all new/changed artifact YAMLs immediately after authoring; a malformed YAML caught here saves WP12 from a downstream failure. Keep doctor-green (gate 7) AND this schema gate; they are complementary. 9. pytest tests/architectural/test_no_legacy_terminology.py → green; forbidden terms in examples are quoted-and-marked, not used (C-004). 10. ruff + mypy clean on any Python touched (NFR-004).

Deferred to the wiring WP (do NOT do here)

  • graph.yaml regeneration + tests/doctrine/drg/* pass.
  • Wiring the new directive into agent-profile directives: lists (C-002c).

Review checklist (reviewer)

  • Overlap-audit record present + honest (no duplicate authority).
  • Correct artifact kind; §1 optionality preserved.
  • Inline DRG edges present (regen deferred, not skipped).
  • tests/doctrine/drg/test_shipped_graph_valid.py green (per-artifact schema validation — confirms YAML is well-formed before WP12; doctor-green alone is not sufficient).
  • doctor + terminology + lint green.