# Phase 08: Solution Architecture Document

## Entry Gate

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

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

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Synthesize every prior phase into the Solution Architecture Document — a self-contained HTML file carrying a schema-valid JSON data island — and produce the explicit handoff payload for `/create-development-architecture`. |
| **REFERENCES** | `.claude/skills/spec-driven-solution-architecture/references/solution-architecture-output.schema.json`; `.claude/skills/spec-driven-solution-architecture/assets/templates/solution-architecture-template.html` |
| **STEP COUNT** | 5 mandatory steps |

## Phase Exit Criteria

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

- [ ] The output object assembled with all 13 required schema fields populated
- [ ] `handoff.recommended_approach` is non-empty
- [ ] The output object passes structural validation against `solution-architecture-output.schema.json` v1.0
- [ ] The HTML document is on disk with an embedded, schema-valid JSON data island
- [ ] Next steps displayed to the user

**IF any criterion is unmet: HALT. The workflow is NOT complete.**

---

## Reference Loading

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

IF either Read fails: HALT — "Phase 08 reference files not loaded."

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

---

## Mandatory Steps

### Step 8.1: Assemble the Output Object

**EXECUTE:**

Build the `solution_architecture_output` object from the checkpoint data of
Phases 01–07, matching `solution-architecture-output.schema.json` v1.0:

```
solution_architecture_output = {
  schema_version: "1.0",
  id: "${SOLARCH_ID}",                       # ^SOLARCH-[0-9]{3,}$
  title: "<epic name> Solution Architecture",
  status: "Draft",
  created: "<ISO 8601 date>",
  source_system_architecture: "<Phase 01 source_system_architecture>",   # SYSARCH-NNN
  system_architecture_validation: { schema_id: "system-architecture-output-1.0",
                                    validation_status: "...", warnings: [...] },
  epic_ref:             "<Phase 02 epic_ref>",
  components:           <Phase 03 / 04 — components with exposes[] populated>,
  interface_contracts:  <Phase 04>,
  data_model:           <Phase 05>,
  integration_design:   <Phase 06>,
  feature_decomposition:<Phase 07>,
  handoff: { ... }                            # built in Step 8.2
}
```

**VERIFY:**
- All 13 schema-required fields are present and non-null:
  `schema_version`, `id`, `title`, `status`, `created`,
  `source_system_architecture`, `system_architecture_validation`, `epic_ref`,
  `components`, `interface_contracts`, `data_model`, `feature_decomposition`,
  `handoff`
- `components` and `feature_decomposition` are non-empty arrays

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

---

### Step 8.2: Build the Handoff Payload

**EXECUTE:**

The handoff is what `/create-development-architecture` consumes:

```
handoff = {
  recommended_approach: "<the technical-design direction the development
                          architect must work within — non-empty>",
  design_constraints: [ "<solution-level constraint the development architecture
                          must not violate — layer rules, contract shapes,
                          data-model invariants>", ... ],
  open_questions: [ "<unresolved question — incl. every Phase 07 NEEDS_ADR
                      feature and every Phase 06 integration unknown>", ... ]
}
```

`design_constraints` draws from the component layer rules, the interface
contracts, and the System Architecture `critical_constraints`. `open_questions`
includes every `needs_adr_open_questions` entry from Phase 07.

**VERIFY:**
- `handoff.recommended_approach` is a non-empty string
- `design_constraints` and `open_questions` are arrays (may be empty, never null)

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=08 --step=8.2 --project-root=. 2>&1
```
```json
{ "step": "8.2", "handoff": { "recommended_approach": "...",
  "design_constraints": [ ... ], "open_questions": [ ... ] } }
```

---

### Step 8.3: Validate Against the Output Contract

**EXECUTE:**

Structurally validate `solution_architecture_output` against
`solution-architecture-output.schema.json` v1.0:

1. All 13 required top-level keys present
2. `schema_version == "1.0"`; `id` matches `^SOLARCH-[0-9]{3,}$`;
   `status` is one of `Draft`/`Reviewed`/`Accepted`/`Superseded`
3. `source_system_architecture` matches `^SYSARCH-[0-9]{3,}$`;
   `epic_ref` matches `^EPIC-[0-9]{3,}$`
4. Each `components[].id` matches `^COMP-[0-9]{3,}$` and `layer` is one of the 4
   enum values; each `interface_contracts[].id` matches `^IFC-[0-9]{3,}$` and
   `kind` is in the 6-value enum; each `feature_decomposition[].id` matches
   `^F-[0-9]{2,}$` and `feasibility` is in `FEASIBLE`/`NEEDS_ADR`/`INFEASIBLE`
5. `data_model.entities` is present and non-empty; each
   `data_model.relationships[].cardinality` is in the 4-value enum
6. `system_architecture_validation.validation_status` is
   `passed` / `passed_with_warnings` / `failed`
7. `handoff` has a non-empty `recommended_approach`

**VERIFY:**
- All 7 checks pass
- IF any check fails: HALT — "Output object fails the
  solution-architecture-output contract. Fix the offending field before
  rendering the document."

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=08 --step=8.3 --project-root=. 2>&1
```
```json
{ "step": "8.3", "schema_validation": "passed" }
```

---

### Step 8.4: Render and Write the HTML Document

**EXECUTE:**

Render the loaded template (`solution-architecture-template.html`):

1. Substitute every `{{TOKEN}}` placeholder with rendered content from the output
   object (title, id, status, created, epic ref, component table, contract
   table, data-model tables, integration table, feature table, handoff).
2. Replace each `data-section` body with the rendered section content.
3. Serialize the **entire** `solution_architecture_output` object as compact JSON
   into the data island:
   `<script type="application/json" id="solution-architecture-data"> … </script>`
4. The file MUST be self-contained — inline CSS, no external assets. The JSON
   island is the machine-readable contract; the HTML is the human-facing carrier.

```
short_name = kebab-case of the epic name (epic_scope.name)
output_path = "devforgeai/specs/architecture/${SOLARCH_ID}-${short_name}.solution-architecture.html"
Write(file_path=output_path, content=<rendered HTML>)
```

**VERIFY:**
- `Glob(pattern=output_path)` returns exactly 1 file
- The file contains the `id="solution-architecture-data"` script tag
- No unrendered `{{TOKEN}}` placeholder remains in the file
- The embedded JSON parses and equals the validated output object from Step 8.3

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=08 --step=8.4 --project-root=. 2>&1
```
```json
{ "step": "8.4", "output_file": "<output_path>", "document_written": true }
```

---

### Step 8.5: Display Completion and Handoff

**EXECUTE:**
```
Display:
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SOLUTION ARCHITECTURE COMPLETE — ${SOLARCH_ID}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Document: {output_path}
Epic: {epic_ref}  |  derived from {source_system_architecture}
Components: {n}  |  Contracts: {n}  |  Entities: {n}  |  Features: {n}
Feasibility: {n} FEASIBLE, {n} NEEDS_ADR, {n} INFEASIBLE

Next step:
  /create-development-architecture — per-feature implementation design,
  consuming this document's JSON data island.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
```

Then `AskUserQuestion` — confirm the document is accurate, or open it for review
before proceeding.

**VERIFY:**
- Completion banner displayed with no `{placeholder}` text remaining
- User responded to the confirmation question

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=08 --step=8.5 --project-root=. 2>&1
```
```json
checkpoint.phases["08"] = {
  "status": "completed",
  "output_file": "<output_path>",
  "handoff": { ... },
  "user_confirmed": true
}
```

---

## Exit Gate

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

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

---

## Phase Transition Display

```
Display:
  "Phase 08 Complete: Solution Architecture Document"
  "Workflow complete — 8/8 phases. Document on disk at {output_path}."
```
