# Phase 01: Solution Architecture Ingestion & Validation

## Entry Gate

```bash
devforgeai-validate phase-check ${DEVARCH_ID} --workflow=development-architecture --from=00 --to=01 --project-root=. 2>&1
```

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

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Locate the persisted Solution Architecture Document on disk, read it, extract its JSON data island, and validate that island against `solution-architecture-output.schema.json` v1.0 BEFORE any development-design work. This is the structural enforcement of the Solution→Development handoff seam — the schema-validation-before-consumption pattern applied here exactly as `spec-driven-solution-architecture` Phase 01 applies it to the System→Solution seam. |
| **REFERENCE** | `.claude/skills/spec-driven-development-architecture/references/solution-architecture-output.schema.json` |
| **STEP COUNT** | 5 mandatory steps |

## Phase Exit Criteria

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

- [ ] `source_solution_architecture` recorded and the document confirmed present on disk via `Glob()`
- [ ] Solution Architecture Document content read from disk (NOT from conversation memory)
- [ ] JSON data island extracted and parsed into a structured object
- [ ] All 13 required top-level keys present; `schema_version == "1.0"`
- [ ] `solution_architecture_validation` recorded with a `validation_status` of `passed` or `passed_with_warnings`

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

---

## Reference Loading

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

IF the Read fails: HALT — "Phase 01 input contract not loaded. Cannot validate the Solution Architecture Document."

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

---

## Mandatory Steps

### Step 1.1: Locate the Solution Architecture Document on Disk

**EXECUTE:**
```
IF $SOLARCH_REF was provided as an argument:
  IF $SOLARCH_REF is a path ending in .html:
    candidate = $SOLARCH_REF
  ELSE IF $SOLARCH_REF matches ^SOLARCH-[0-9]{3,}$:
    Glob(pattern="devforgeai/specs/architecture/${SOLARCH_REF}-*.solution-architecture.html")
    candidate = that match
ELSE:
  Glob(pattern="devforgeai/specs/architecture/SOLARCH-*.solution-architecture.html")
  IF exactly 1 match: candidate = that match
  IF 0 matches: HALT — "No Solution Architecture Document found. Run /create-solution-architecture first."
  IF >1 match:
    AskUserQuestion — present the candidate documents, ask the user which Solution
    Architecture this development architecture is derived from. candidate = user selection.
```

**VERIFY:**
- `candidate` is a non-empty relative path
- `Glob(pattern=candidate)` returns exactly 1 file

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=01 --step=1.1 --project-root=. 2>&1
```
```json
{ "phase": "01", "step": "1.1", "solution_architecture_path": "<candidate>" }
```

---

### Step 1.2: Read the Solution Architecture Document From Disk

**EXECUTE:**
```
Read(file_path=<solution_architecture_path>)
```

This is the handoff-enforcement point: the Solution Architecture MUST be read from
the persisted file. Do NOT reconstruct, summarize, or assume its content from the
conversation context — even if `/create-solution-architecture` ran in the same session.

**VERIFY:**
- Read returned content with length > 0
- The content contains the literal string `id="solution-architecture-data"`
- IF the data-island script tag is absent: HALT — "Solution Architecture Document has no JSON data island; cannot validate against the input contract."

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=01 --step=1.2 --project-root=. 2>&1
```
```json
{ "step": "1.2", "document_read": true, "content_length": "<int>" }
```

---

### Step 1.3: Extract and Parse the JSON Data Island

**EXECUTE:**
```
Locate the data island by string-matching the opening tag
  <script type="application/json" id="solution-architecture-data">
and the next closing </script> tag. The text BETWEEN them is the
machine-readable contract payload.

Parse that text as JSON into a structured object: solution_architecture.
```

The HTML is the human-facing carrier; the JSON island is the authoritative
contract. Always validate against the parsed island, never against rendered HTML
prose.

**VERIFY:**
- The text between the tags is non-empty
- It parses as valid JSON (a top-level object, not an array or scalar)
- IF parse fails: HALT — "Solution Architecture data island is not valid JSON."

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=01 --step=1.3 --project-root=. 2>&1
```
```json
{ "step": "1.3", "data_island_extracted": true, "top_level_keys": ["<keys found>"] }
```

---

### Step 1.4: Structural Validation Against the Input Contract

**EXECUTE:**

The 5-step structural check is enforced by the deterministic CLI gate
`devforgeai-validate validate-solution-architecture-output` (ADR-084).
The CLI performs the same 5 checks the prose used to enumerate inline —
but as a binary gate the orchestrator cannot abbreviate or skip:

1. **Required top-level keys (13).** Confirm ALL are present:
   `schema_version`, `id`, `title`, `status`, `created`,
   `source_system_architecture`, `system_architecture_validation`, `epic_ref`,
   `components`, `interface_contracts`, `data_model`, `feature_decomposition`,
   `handoff`.
2. **Version pin.** Confirm `schema_version == "1.0"`.
3. **ID-pattern conformance:**
   - `id` matches `^SOLARCH-[0-9]{3,}$`
   - `epic_ref` matches `^EPIC-[0-9]{3,}$`
   - each `components[].id` matches `^COMP-[0-9]{3,}$`
   - each `interface_contracts[].id` matches `^IFC-[0-9]{3,}$`
   - each `feature_decomposition[].id` matches `^F-[0-9]{2,}$`
4. **Feature decomposition present.** `feature_decomposition` is a non-empty array —
   this skill details ONE of its features; an empty array means there is nothing
   to develop-architect.
5. **Handoff present.** `handoff.recommended_approach` is a non-empty string — the
   technical-design direction the development architecture must work within.

Checks 1, 2, and **4** are blocking (`severity=fail`); checks 3 and 5 are
warning-capable (`severity=warning`). Check 4's `severity=fail` is the
principal divergence from the PM Plan and System Architecture sibling
validators — `feature_decomposition` empty is explicitly a failure
condition per the classification block below. This is the same
Schema-Validation-Before-Consumption pattern that ADR-082 / H5
established at the DEVARCH → Stories handoff.

```
Bash:
  devforgeai-validate validate-solution-architecture-output \
      "$solution_architecture_path" --project-root=. --format=json
IF exit code != 0:
  Display the CLI's JSON `checks[]` array (each failing row carries
  `name`, `severity`, and `diagnostic`) so the user sees which checks
  failed.
  HALT — "Solution Architecture Document failed input-contract
  validation; cannot proceed."
```

Classify the outcome (the CLI emits `validation_status` directly — the
orchestrator does NOT re-classify):
- **passed** — all 5 checks pass
- **passed_with_warnings** — checks 1, 2, & 4 pass; check 3 or 5 has a
  minor, non-blocking gap (recorded in the CLI's `warnings[]` field)
- **failed** — any required key missing OR `schema_version != "1.0"` OR
  `feature_decomposition` empty (CLI exit code 1)

**VERIFY:**
- The CLI ran to completion and emitted a JSON payload
- A `validation_status` value is present in the CLI output

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=01 --step=1.4 --project-root=. 2>&1
```

The CLI's `--format=json` output pre-rolls every field this RECORD
captures — extract them directly from the JSON output rather than
re-classifying:

```json
{
  "step": "1.4",
  "missing_keys": ["<from CLI JSON missing_keys[]>"],
  "schema_version_found": "<from CLI JSON schema_version_found>",
  "id_pattern_violations": ["<from CLI JSON id_pattern_violations[]>"],
  "warnings": ["<from CLI JSON warnings[]>"]
}
```

---

### Step 1.5: Record the Validation Verdict

**EXECUTE:**
```
IF validation_status == "failed":
  Display the failure detail (missing keys / wrong version / empty feature_decomposition).
  HALT — "Solution Architecture Document failed input-contract validation.
  The Development Architecture cannot be built on a non-conforming Solution
  Architecture. Re-run /create-solution-architecture or correct the document,
  then retry."

IF validation_status == "passed_with_warnings":
  Display the warnings and continue.

Build the solution_architecture_validation object that Phase 08 embeds into the output:
solution_architecture_validation = {
  "schema_id": "solution-architecture-output-1.0",
  "validation_status": "<passed|passed_with_warnings>",
  "warnings": [<warning strings>]
}

Also capture provenance and design inputs for downstream phases:
  source_solution_architecture = solution_architecture.id          (SOLARCH-NNN)
  sol_epic_ref                 = solution_architecture.epic_ref
  sol_components               = solution_architecture.components
  sol_interface_contracts      = solution_architecture.interface_contracts
  sol_data_model               = solution_architecture.data_model
  sol_integration_design       = solution_architecture.integration_design
  sol_feature_decomposition    = solution_architecture.feature_decomposition
  sol_handoff                  = solution_architecture.handoff
```

**VERIFY:**
- `validation_status` is `passed` or `passed_with_warnings` (a `failed` status
  would have HALTed above)
- `source_solution_architecture` matches `^SOLARCH-[0-9]{3,}$`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=01 --step=1.5 --project-root=. 2>&1
```
```json
checkpoint.phases["01"] = {
  "status": "completed",
  "solution_architecture_path": "<path>",
  "source_solution_architecture": "<SOLARCH-NNN>",
  "solution_architecture_validation": { "schema_id": "solution-architecture-output-1.0",
                                        "validation_status": "<status>", "warnings": [...] },
  "solution_architecture": { "<the parsed Solution Architecture object, retained for Phases 02-08>" }
}
```

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${DEVARCH_ID} --workflow=development-architecture --phase=01 --checkpoint-passed --project-root=. 2>&1
```

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

---

## Phase Transition Display

```
Display:
  "Phase 01 Complete: Solution Architecture Ingestion & Validation"
  "Source: {source_solution_architecture}  |  Validation: {validation_status}"
  "Epic: {sol_epic_ref}  |  Components: {count}  |  Features available: {count}"
  "Proceeding to Phase 02: Feature Framing"
```
