derive-interface-contracts

name	derive-interface-contracts
description	Design external system contracts from approved domain and architecture artifacts with stable IDs. Use when Codex needs REST, gRPC, event, CLI, queue, or other interface definitions that trace back to use cases, ports, and invariants and are ready for implementation planning. Do not use for domain modeling, architecture design, or implementation.

Derive Interface Contracts

Goal

Turn approved use cases and boundaries into explicit interface contracts that external callers, adapters, and implementation slices can rely on.

Read Shared Contract Reference before producing the artifact.

Trigger boundary

• Use after domain and architecture artifacts are approved.
• Do not use for domain modeling, architecture design, code review, or implementation.

Required input

• Required: approved domain model with metadata showing approval_status: approved and stable UC-* and INV-* IDs
• Required: approved architecture design with metadata showing approval_status: approved and stable PORT-* identifiers
• Required: use cases and any known interface constraints
• Optional: existing API conventions, auth constraints, external integration expectations

Refusal and blocked policy

• Derive contracts from use cases, not from arbitrary endpoint patterns.
• Preserve domain terminology and invariants.
• Support REST, gRPC, events, CLI commands, queue messages, or other suitable interfaces without assuming one transport by default.
• Return BLOCKED when the upstream domain or architecture artifact is missing, unapproved, or lacks stable IDs.
• Return BLOCKED when transport choice cannot be justified from use cases or integration constraints.

Workflow

1. Choose the contract style that best matches each use case and integration context.
2. Define the command, query, event, or interaction boundary for each CONTRACT-*.
3. Specify request and response shapes, validation rules, and refusal paths.
4. Make idempotency, ordering, retries, and error handling explicit when relevant.
5. Trace each contract back to UC-*, PORT-*, and INV-* identifiers.
6. Produce machine-readable specs only when the interface choice supports them and the user wants them.

Output contract

Write contracts.md and, when appropriate, a matching machine-readable contract such as openapi.yaml, event schemas, or CLI definitions. Use this Markdown structure:

# Interface Contracts

## Artifact Metadata
- artifact_id:
- artifact_type: contracts
- artifact_status: draft | current | superseded
- approval_status: pending_review | approved | changes_required | rejected
- approved_by_gate_profile: none | interface-contracts | cross-artifact-consistency
- gate_report_ref: none | <ref>
- upstream_artifact_refs:

## Contract Inventory
| contract_id | contract | style | actor_or_caller | backed_use_case_ids | backed_port_ids |
| --- | --- | --- | --- | --- | --- |

## Shared Terms And Invariants
- term_or_invariant_id:
- meaning_or_rule:

## Contract: CONTRACT-* <name>
- purpose:
- initiating_actor_or_system:
- mapped_use_case_ids:
- mapped_port_ids:
- preserved_invariant_ids:
- state_transition_ids_touched:
- request_or_input_shape:
- response_or_output_shape:
- validation_rules:
- errors_and_refusal_cases:
- idempotency_ordering_retry_rules:
- auth_or_permission_requirements:
- notes_for_adapters:

## Machine-Readable Spec Sync Rules
- contract_id:
- markdown_source_of_truth_for:
- machine_readable_artifact:
- parity_checks_required:

## Open Questions
- ...

Quality bar

• Do not invent operations that are not backed by approved use cases.
• Keep the contract language aligned with the domain model.
• Make unhappy paths explicit instead of burying them in prose.
• Ensure any generated machine-readable spec matches the Markdown contract exactly.
• Every contract must cite the UC-*, PORT-*, and INV-* records it depends on.
• Initialize artifact metadata with approval_status: pending_review until a gate or approver marks it otherwise.