# Phase 04: Interface & Contract Design

## Entry Gate

```bash
devforgeai-validate phase-check ${SOLARCH_ID} --workflow=solution-architecture --from=03 --to=04 --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Proceed to Phase 04 |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — previous phase not complete |

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Design the interface contracts between components and with external systems — REST endpoints, GraphQL operations, gRPC methods, service interfaces, message contracts, and events. Every contract is owned by exactly one component and consumed by zero or more. The `api-designer` subagent designs the contract shapes; this phase frames the seams, assigns `IFC-NNN` ids, and cross-links them to the component decomposition. |
| **REFERENCE** | `.claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json` |
| **SUBAGENT** | `api-designer` (contract shape design) |
| **STEP COUNT** | 5 mandatory steps |

## Phase Exit Criteria

Before this phase can complete, ALL of the following MUST be true:

- [ ] Every interface seam between components (and to external systems) identified
- [ ] `api-designer` invoked; it returned structured contract designs
- [ ] `interface_contracts` assembled — each an `IFC-NNN` with a `kind`
- [ ] Every contract has a valid `provided_by` `COMP-NNN`; `components[].exposes` cross-linked

**IF any criterion is unmet: HALT. Do NOT proceed to Phase 05.**

---

## Reference Loading

```
Read(file_path=".claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json")
```

The `$defs.interface_contract` shape (`id`, `name`, `kind`, `request`, `response`,
`errors`, `provided_by`, `consumed_by`) is exactly what each step below must
produce. IF the Read fails: HALT — "Phase 04 output contract not loaded."

Do NOT rely on memory of previous reads. Load fresh every time this phase executes.

---

## Mandatory Steps

### Step 4.1: Identify the Interface Seams

**EXECUTE:**

From the Phase 03 `components` and their `dependencies`, and from the Phase 01
`sysarch_integration_topology`, enumerate every seam that needs a contract:

```
- Each dependency edge COMP-A → COMP-B is a candidate seam: COMP-B exposes a
  contract that COMP-A consumes.
- Each presentation-layer component exposes contracts to external callers
  (the system's API surface).
- Each external integration (INT-NNN from the System Architecture) that this
  epic touches needs a contract describing the exchange.
```

**VERIFY:**
- Every Phase 03 dependency edge maps to at least one identified seam, OR is
  explicitly recorded as an in-process call needing no formal contract

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=04 --step=4.1 --project-root=. 2>&1
```
```json
{ "phase": "04", "step": "4.1", "seams": [ { "provider": "COMP-NNN",
  "consumers": ["COMP-NNN"], "purpose": "..." } ] }
```

---

### Step 4.2: Invoke api-designer

**EXECUTE:**
```
Task(
  subagent_type="api-designer",
  prompt="Design the interface contracts for epic ${epic_ref} of this project.

    Inputs:
    - Components (with layer and responsibility): ${components}
    - Interface seams to design: ${seams}
    - External integrations in scope: ${relevant INT-NNN from the System Architecture}
    - Locked tech stack (governs protocol choices): ${sysarch_tech_stack}

    For each seam, design ONE contract. Return structured JSON ONLY — do NOT
    write files:
    { contracts: [ {
        name, kind: 'rest_endpoint'|'graphql_operation'|'grpc_method'|
                    'service_interface'|'message_contract'|'event',
        request:  '<request / input shape summary>',
        response: '<response / output shape summary>',
        errors:   [ '<error case>', ... ],
        provider_component: 'COMP-NNN',
        consumer_components: [ 'COMP-NNN', ... ] } ] }

    Protocol choices MUST be consistent with the locked tech stack. Do NOT
    introduce a protocol or framework absent from it."
)
```
This is a BLOCKING task. Wait for the result before proceeding.

**VERIFY:**
- Task returned a `contracts` array with ≥ 1 entry (or an explicit, recorded
  reason the epic needs no formal contracts)
- Every contract has `name`, `kind`, `provider_component`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=04 --step=4.2 --project-root=. 2>&1
```
```json
{ "step": "4.2", "api_designer_contracts": [ ... ] }
```

---

### Step 4.3: Assign IDs and Validate the Contracts

**EXECUTE:**

For each contract the `api-designer` returned, assign an `IFC-NNN` id and build
the schema-conformant object:

```
interface_contract = {
  id: "IFC-001",                 # ^IFC-[0-9]{3,}$
  name: "<contract name>",
  kind: "<one of the 6 enum values>",
  request: "<request shape summary>",
  response: "<response shape summary>",
  errors: [ "<error case>", ... ],
  provided_by: "COMP-NNN",       # MUST be a component defined in Phase 03
  consumed_by: [ "COMP-NNN", ... ]
}
```

Verify each `kind` is one of the 6 enum values; verify `provided_by` and every
`consumed_by` entry is a real `COMP-NNN` from the Phase 03 decomposition. A
contract referencing an undefined component is a cross-reference error — HALT and
reconcile.

**VERIFY:**
- Every contract has a unique `id` matching `^IFC-[0-9]{3,}$`
- Every `kind` is in the 6-value enum
- Every `provided_by` / `consumed_by` id resolves to a Phase 03 component

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=04 --step=4.3 --project-root=. 2>&1
```
```json
{ "step": "4.3", "interface_contracts": [ ... ] }
```

---

### Step 4.4: Cross-Link Components to Contracts

**EXECUTE:**
```
FOR each interface_contract IFC:
  Append IFC.id to the exposes[] array of the component IFC.provided_by.
Update the Phase 03 components array in the checkpoint with the populated
exposes[] arrays.
```

This closes the loop: a Phase 03 component now declares which `IFC-NNN` contracts
it exposes, and each contract declares its `provided_by` component.

**VERIFY:**
- Every component that provides ≥ 1 contract has a non-empty `exposes[]`
- Every `IFC-NNN` appears in exactly one component's `exposes[]`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=04 --step=4.4 --project-root=. 2>&1
```
```json
{ "step": "4.4", "components_exposes_updated": true }
```

---

### Step 4.5: Record the Interface Contracts

**EXECUTE:**
```
Assemble the interface_contracts array and the updated components array
(with exposes[] populated).
```

**VERIFY:**
- `interface_contracts` is consistent: every id unique, every component reference valid

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=04 --step=4.5 --project-root=. 2>&1
```
```json
checkpoint.phases["04"] = {
  "status": "completed",
  "interface_contracts": [ { "id": "IFC-001", "name": "...", "kind": "...",
    "request": "...", "response": "...", "errors": [...],
    "provided_by": "COMP-NNN", "consumed_by": [...] }, ... ],
  "components": [ "<Phase 03 components with exposes[] now populated>" ]
}
```

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${SOLARCH_ID} --workflow=solution-architecture --phase=04 --checkpoint-passed --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | Phase 04 complete — proceed to next phase |
| 127 | CLI not installed — proceed without enforcement |
| Other | HALT — checkpoint/step validation failed |

---

## Phase Transition Display

```
Display:
  "Phase 04 Complete: Interface & Contract Design"
  "Contracts: {count}  |  Kinds: {list}"
  "Components exposing contracts: {count}"
  "Proceeding to Phase 05: Data Model Design"
```
