# Phase 08: Development Architecture Document

## Entry Gate

```bash
devforgeai-validate phase-check ${DEVARCH_ID} --workflow=development-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 Development Architecture Document — a self-contained HTML file carrying a schema-valid JSON data island — and produce the explicit handoff payload for `/create-story`. |
| **REFERENCES** | `.claude/skills/spec-driven-development-architecture/references/development-architecture-output.schema.json`; `.claude/skills/spec-driven-development-architecture/assets/templates/development-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_build_order` is a non-empty array of `SEED-NNN` ids
- [ ] The output object passes structural validation against `development-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-development-architecture/references/development-architecture-output.schema.json")
Read(file_path=".claude/skills/spec-driven-development-architecture/assets/templates/development-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 `development_architecture_output` object from the checkpoint data of
Phases 01–07, matching `development-architecture-output.schema.json` v1.0:

```
development_architecture_output = {
  schema_version: "1.0",
  id: "${DEVARCH_ID}",                          # ^DEVARCH-[0-9]{3,}$
  title: "<feature name> Development Architecture",
  status: "Draft",
  created: "<ISO 8601 date>",
  source_solution_architecture: "<Phase 01 source_solution_architecture>",   # SOLARCH-NNN
  solution_architecture_validation: { schema_id: "solution-architecture-output-1.0",
                                      validation_status: "...", warnings: [...] },
  feature_ref:        "<Phase 02 feature_ref>",          # F-NN
  layer_placement_map:<Phase 03>,
  design_patterns:    <Phase 04>,
  module_structure:   <Phase 05>,
  dependency_wiring:  <Phase 05>,
  test_strategy_hooks:<Phase 06>,
  story_seeds:        <Phase 07>,
  handoff: { ... }                              # built in Step 8.2
}
```

`dependency_wiring` and `test_strategy_hooks` are optional in the schema but are
always produced by this skill — include them.

**VERIFY:**
- All 13 schema-required fields are present and non-null:
  `schema_version`, `id`, `title`, `status`, `created`,
  `source_solution_architecture`, `solution_architecture_validation`,
  `feature_ref`, `layer_placement_map`, `design_patterns`, `module_structure`,
  `story_seeds`, `handoff`
- `story_seeds` is a non-empty array

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-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-story` (`spec-driven-stories`) consumes:

```
handoff = {
  recommended_build_order: [ "SEED-NNN", ... ],   # ≥ 1 SEED id, dependency-respecting order
  implementation_constraints: [ "<constraint story authoring and implementation
                                  must not violate — layer rules, target paths,
                                  prescribed patterns, coverage thresholds>", ... ],
  open_questions: [ "<unresolved question — incl. the Phase 02 needs_adr_note and
                      every Phase 07 review_open_questions entry>", ... ]
}
```

`recommended_build_order` lists the `SEED-NNN` ids in the order they should be
implemented, respecting the Phase 05 `dependency_wiring` — a seed touching a
dependency component is built before the seed that consumes it. It MUST contain
≥ 1 id (the schema sets `minItems: 1`). `implementation_constraints` draws from the
layer-placement rules, the prescribed patterns, the test-strategy coverage layers,
and the Solution Architecture `sol_handoff.design_constraints`. `open_questions`
includes the Phase 02 `needs_adr_note` (if non-null) and every Phase 07
`review_open_questions` entry.

**VERIFY:**
- `handoff.recommended_build_order` is a non-empty array; every entry matches `^SEED-[0-9]{3,}$`
- Every `recommended_build_order` id is a `story_seeds` id
- `implementation_constraints` and `open_questions` are arrays (may be empty, never null)

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

---

### Step 8.3: Validate Against the Output Contract

**EXECUTE:**

Structurally validate `development_architecture_output` against
`development-architecture-output.schema.json` v1.0:

1. All 13 required top-level keys present
2. `schema_version == "1.0"`; `id` matches `^DEVARCH-[0-9]{3,}$`;
   `status` is one of `Draft`/`Reviewed`/`Accepted`/`Superseded`
3. `source_solution_architecture` matches `^SOLARCH-[0-9]{3,}$`;
   `feature_ref` matches `^F-[0-9]{2,}$`
4. Each `layer_placement_map[].component_ref` matches `^COMP-[0-9]{3,}$` and `layer`
   is one of the 4 enum values; each `layer_placement_map[].target_path` is non-empty
5. Each `design_patterns[]` has a non-empty `pattern` and `applies_to`; each
   `module_structure[]` has a non-empty `path` and `purpose`
6. Each `story_seeds[].id` matches `^SEED-[0-9]{3,}$` with a non-empty `title` and
   `summary`; each `test_strategy_hooks[].coverage_layer` (if set) is in
   `business_logic`/`application`/`infrastructure`; each `dependency_wiring[].injection_style`
   (if set) is in `constructor`/`property`/`method`/`factory`
7. `solution_architecture_validation.validation_status` is
   `passed`/`passed_with_warnings`/`failed`; `handoff.recommended_build_order` is a
   non-empty array of `^SEED-[0-9]{3,}$` ids

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

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-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 (`development-architecture-template.html`):

1. Substitute every `{{TOKEN}}` placeholder with rendered content from the output
   object (title, id, status, created, feature ref, layer-placement table, design-
   pattern table, module table, dependency-wiring table, test-hook table, story-
   seed table, handoff).
2. Replace each `data-section` body with the rendered section content.
3. Serialize the **entire** `development_architecture_output` object as compact JSON
   into the data island:
   `<script type="application/json" id="development-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 feature name (feature_scope.name)
output_path = "devforgeai/specs/architecture/${DEVARCH_ID}-${short_name}.development-architecture.html"
Write(file_path=output_path, content=<rendered HTML>)
```

**VERIFY:**
- `Glob(pattern=output_path)` returns exactly 1 file
- The file contains the `id="development-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 ${DEVARCH_ID} --workflow=development-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:
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  DEVELOPMENT ARCHITECTURE COMPLETE — ${DEVARCH_ID}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Document: {output_path}
Feature: {feature_ref}  |  derived from {source_solution_architecture}
Components: {n}  |  Patterns: {n}  |  Modules: {n}  |  Story seeds: {n}
Build order: {recommended_build_order}

Next step:
  /create-story — author story files from this document's story seeds.
  The story seeds and handoff are in the 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 ${DEVARCH_ID} --workflow=development-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 ${DEVARCH_ID} --workflow=development-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: Development Architecture Document"
  "Workflow complete — 8/8 phases. Document on disk at {output_path}."
```
