# Phase 06: Integration Design

## Entry Gate

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

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

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Realize each system integration point this epic touches — turn the System Architecture's `integration_topology` (the WHAT: which external systems exist) into a concrete integration design (the HOW: interaction sequence, error handling, retry/idempotency posture). |
| **REFERENCE** | `.claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json` |
| **STEP COUNT** | 4 mandatory steps |

## Phase Exit Criteria

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

- [ ] The integration points in scope for this epic selected from `sysarch_integration_topology`
- [ ] Each in-scope integration has a concrete `design` describing the interaction
- [ ] Each in-scope integration has a `failure_handling` posture recorded
- [ ] An epic touching zero integrations records `integration_design: []` explicitly

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

---

## Reference Loading

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

The `integration_design` property — an array of `{ integration_ref, design,
failure_handling }` objects — is exactly what this phase produces. IF the Read
fails: HALT — "Phase 06 output contract not loaded."

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

---

## Mandatory Steps

### Step 6.1: Select the In-Scope Integration Points

**EXECUTE:**

From the Phase 01 `sysarch_integration_topology` (the `INT-NNN` integration
points of the System Architecture), select the subset this epic actually touches:

```
FOR each integration_point INT in sysarch_integration_topology:
  IF this epic's components (Phase 03) or contracts (Phase 04) exchange data
     with INT:
    INT is in scope for integration design.
```

An epic that touches no external integrations is valid — record the empty
selection explicitly. Do not silently omit integrations; state which were
considered and excluded.

**VERIFY:**
- Every `sysarch_integration_topology` entry was classified in-scope or out-of-scope
- The in-scope selection references only real `INT-NNN` ids

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=06 --step=6.1 --project-root=. 2>&1
```
```json
{ "phase": "06", "step": "6.1", "in_scope_integrations": ["INT-NNN", ...],
  "out_of_scope_integrations": ["INT-NNN", ...] }
```

---

### Step 6.2: Design the Interaction

**EXECUTE:**

For each in-scope integration point, write the concrete interaction design:

```
integration_design_entry = {
  integration_ref: "INT-NNN",          # from sysarch_integration_topology
  design: "<the interaction: which component initiates, the call/message
            sequence, the protocol, the data exchanged, ordering/timing
            constraints, and which IFC-NNN contract carries it>",
  failure_handling: "<filled in Step 6.3>"
}
```

The `design` MUST name the owning `COMP-NNN` and reference the `IFC-NNN` contract
(Phase 04) that carries the exchange. A `trust_boundary: true` integration is
security-sensitive — confirm authentication / data-protection handling with the
user (HALT trigger #7).

**VERIFY:**
- Every in-scope integration has a non-empty `design`
- Every `integration_ref` matches `^INT-[0-9]{3,}$` and exists in `sysarch_integration_topology`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=06 --step=6.2 --project-root=. 2>&1
```
```json
{ "step": "6.2", "integration_designs": [ { "integration_ref": "INT-NNN",
  "design": "..." }, ... ] }
```

---

### Step 6.3: Design the Failure Handling

**EXECUTE:**

For each in-scope integration, specify the failure posture:

```
failure_handling = "<error handling on failure; retry policy (count, backoff);
                     idempotency posture; timeout; fallback / degraded behavior;
                     what happens to in-flight data>"
```

An outbound or bidirectional integration without an idempotency/retry posture is
an incomplete design — every external call can fail. A genuine unknown is
recorded as an open question for the Phase 08 handoff, not left blank.

**VERIFY:**
- Every in-scope integration has a non-empty `failure_handling`

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

---

### Step 6.4: Record the Integration Design

**EXECUTE:**
```
Assemble the integration_design array — one entry per in-scope integration,
each with integration_ref, design, and failure_handling.
IF no integrations are in scope: integration_design = []
```

**VERIFY:**
- `integration_design` is an array (may be empty, never null)
- Every entry has `integration_ref` and `design`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=06 --step=6.4 --project-root=. 2>&1
```
```json
checkpoint.phases["06"] = {
  "status": "completed",
  "integration_design": [ { "integration_ref": "INT-NNN", "design": "...",
                            "failure_handling": "..." }, ... ]
}
```

---

## Exit Gate

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

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

---

## Phase Transition Display

```
Display:
  "Phase 06 Complete: Integration Design"
  "Integrations realized: {count}  |  Out of scope: {count}"
  "Proceeding to Phase 07: Feature Decomposition"
```
