Contracts

drg-shape.md

DRG Shape Contract — Documentation Action Nodes

This contract specifies what src/doctrine/graph.yaml MUST contain after the implementer applies WP04. It is a regression contract: the implementer renders the YAML, the test enforces the contract.

Contract: nodes

For every <action> in {discover, audit, design, generate, validate, publish}:

- urn: action:documentation/<action>
  kind: action
  label: <action>

The 6 nodes MUST exist. The kind MUST be exactly action. The label MUST be the bare action verb (no prefix, no underscore, no slash).

Contract: edges

For every <action>, the edges declared in data-model.md → Edges MUST exist. Each is a {source, target, relation: scope} triple.

Minimum-edge invariant: every documentation action MUST have at least 3 outgoing relation: scope edges (mirrors research's lowest-edge action output).

Contract: action bundle ↔ DRG consistency

For every <action>:

  • src/doctrine/missions/documentation/actions/<action>/index.yaml MUST exist.
  • The directive slugs in index.yaml (e.g. 010-specification-fidelity-requirement) MUST map 1-to-1 with the directive URN edges in graph.yaml for the same action (e.g. directive:DIRECTIVE_010).
  • Same for tactics.

The mapping is by the URN's numeric / kebab suffix:

  • 010-specification-fidelity-requirement ⇔ directive:DIRECTIVE_010
  • 003-decision-documentation-requirement ⇔ directive:DIRECTIVE_003
  • 037-living-documentation-sync ⇔ directive:DIRECTIVE_037
  • 001-architectural-integrity-standard ⇔ directive:DIRECTIVE_001
  • requirements-validation-workflow ⇔ tactic:requirements-validation-workflow
  • premortem-risk-identification ⇔ tactic:premortem-risk-identification
  • adr-drafting-workflow ⇔ tactic:adr-drafting-workflow

Contract: load + resolve_context

After the nodes/edges are added:

from charter._drg_helpers import load_validated_graph
from doctrine.drg.query import resolve_context

graph = load_validated_graph(repo_root)
for action in ("discover", "audit", "design", "generate", "validate", "publish"):
    node = graph.get_node(f"action:documentation/{action}")
    assert node is not None, f"missing DRG node: action:documentation/{action}"

    ctx = resolve_context(graph, f"action:documentation/{action}", depth=2)
    assert ctx.artifact_urns, f"empty artifact_urns for action:documentation/{action}"

The integration walk and tests/specify_cli/test_documentation_drg_nodes.py both run this assertion (the test is the formal gate; the walk smoke-tests it via the full runtime path).

Verification

tests/specify_cli/test_documentation_drg_nodes.py MUST contain:

1. test_each_documentation_action_has_drg_node_and_context — the load + resolve_context assertions above. 2. test_action_bundle_matches_drg_edges — for every action, the URN-form edges in graph.yaml match the slug-form lists in actions/<action>/index.yaml. 3. test_resolve_context_within_research_2x — the median resolve_context latency for documentation actions over 5 runs is at most 2× the median for research actions over 5 runs (NFR-007).

step-contracts.md

Step Contract Shape Contracts

One paragraph per shipped contract. The implementer renders the full YAML using the data-model.md → Step contract shape example as the template.

Required keys for every contract (per existing schema; spec C-009 forbids new top-level fields):

  • schema_version: "1.0"
  • id: documentation-<action> (matches the file basename without extension)
  • action: <action>
  • mission: documentation
  • steps: list[StepDef] — at least: bootstrap (charter context load), 1-2 delegate steps, an artifact-write step, a commit step.

Each StepDef requires id, description; optional command, delegates_to{kind, candidates[]}, inputs[]. No expected_artifacts.

documentation-discover.step-contract.yaml

  • id: documentation-discover, action: discover, mission: documentation.
  • Bootstrap: spec-kitty charter context --action discover --role discover --json.
  • Capture-needs step delegates to directives: 010-specification-fidelity-requirement, 003-decision-documentation-requirement.
  • Validate-scope step delegates to tactic: requirements-validation-workflow.
  • Write step: Write spec.md in kitty-specs/{mission_slug}/.
  • Commit step delegates to directives: 029-agent-commit-signing-policy, 033-targeted-staging-policy.

documentation-audit.step-contract.yaml

  • id: documentation-audit, action: audit, mission: documentation.
  • Bootstrap: spec-kitty charter context --action audit --role audit --json.
  • Inventory-existing-docs step delegates to directive: 037-living-documentation-sync.
  • Identify-gaps step delegates to tactic: requirements-validation-workflow.
  • Write step: Write gap-analysis.md in kitty-specs/{mission_slug}/.
  • Commit step delegates to directives: 029-agent-commit-signing-policy, 033-targeted-staging-policy.

documentation-design.step-contract.yaml

  • id: documentation-design, action: design, mission: documentation.
  • Bootstrap: spec-kitty charter context --action design --role design --json.
  • Plan-divio-types step delegates to directive: 001-architectural-integrity-standard.
  • Architecture-decision step delegates to tactic: adr-drafting-workflow.
  • Validate-design step delegates to tactic: requirements-validation-workflow.
  • Write step: Write plan.md in kitty-specs/{mission_slug}/.
  • Commit step delegates to directives: 029-agent-commit-signing-policy, 033-targeted-staging-policy.

documentation-generate.step-contract.yaml

  • id: documentation-generate, action: generate, mission: documentation.
  • Bootstrap: spec-kitty charter context --action generate --role generate --json.
  • Produce-artifacts step delegates to directive: 010-specification-fidelity-requirement.
  • Living-doc-sync step delegates to directive: 037-living-documentation-sync.
  • Validate-output step delegates to tactic: requirements-validation-workflow.
  • Write step: Write docs/*/.md under kitty-specs/{mission_slug}/.
  • Commit step delegates to directives: 029-agent-commit-signing-policy, 033-targeted-staging-policy.

documentation-validate.step-contract.yaml

  • id: documentation-validate, action: validate, mission: documentation.
  • Bootstrap: spec-kitty charter context --action validate --role validate --json.
  • Quality-gates step delegates to directive: 010-specification-fidelity-requirement.
  • Risk-review step delegates to tactic: premortem-risk-identification.
  • Validate-against-spec step delegates to tactic: requirements-validation-workflow.
  • Write step: Write audit-report.md in kitty-specs/{mission_slug}/.
  • Commit step delegates to directives: 029-agent-commit-signing-policy, 033-targeted-staging-policy.

documentation-publish.step-contract.yaml

  • id: documentation-publish, action: publish, mission: documentation.
  • Bootstrap: spec-kitty charter context --action publish --role publish --json.
  • Living-doc-sync step delegates to directive: 037-living-documentation-sync.
  • Specification-fidelity step delegates to directive: 010-specification-fidelity-requirement.
  • Final-validation step delegates to tactic: requirements-validation-workflow.
  • Write step: Write release.md in kitty-specs/{mission_slug}/.
  • Commit step delegates to directives: 029-agent-commit-signing-policy, 033-targeted-staging-policy.

Verification: tests/specify_cli/mission_step_contracts/test_documentation_composition.py::test_all_six_contracts_load_cleanly round-trips each YAML through the existing contract loader and asserts:

  • id == basename(path).removesuffix(".step-contract.yaml")
  • action == basename(path).removeprefix("documentation-").removesuffix(".step-contract.yaml")
  • mission == "documentation"
  • len(steps) >= 4 (bootstrap + ≥1 delegate + write + commit)
  • no expected_artifacts key on the contract or any step (C-009)