# Phase 05: Module Structure & Dependency Wiring

## Entry Gate

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

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

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Turn the layer-placement map (Phase 03) and the prescribed patterns (Phase 04) into a concrete module/file plan and a dependency-wiring graph. The `module_structure` is the planned source-tree layout — modules, their purpose, their key units (classes/functions/interfaces). The `dependency_wiring` is the construction-time graph — which component receives which dependency, and by which injection style. |
| **REFERENCE** | `.claude/skills/spec-driven-development-architecture/references/development-architecture-output.schema.json` |
| **STEP COUNT** | 5 mandatory steps |

## Phase Exit Criteria

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

- [ ] `module_structure` enumerated — each `module` with a `path` and a `purpose`
- [ ] Every module `path` sits under a Phase 03 `target_path` (consistent with `source-tree/`)
- [ ] `dependency_wiring` mapped — each edge with a `consumer`, a `dependency`, and an `injection_style`
- [ ] Every `consumer`/`dependency` resolves to a feature component (or a named abstraction it depends on)
- [ ] No wiring edge violates a layer-boundary rule

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

---

## Reference Loading

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

The `$defs.module` shape (`path`, `purpose`, `key_units`) and the `dependency_wiring`
item shape (`consumer`, `dependency`, `injection_style`) are exactly what this phase
produces. IF the Read fails: HALT — "Phase 05 output contract not loaded."

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

---

## Mandatory Steps

### Step 5.1: Plan the Module Structure

**EXECUTE:**

From the `layer_placement_map` (Phase 03) and `design_patterns` (Phase 04), plan
the modules the feature implementation needs:

```
module = {
  path: "<source-tree file or directory path — under a Phase 03 target_path>",
  purpose: "<what this module is responsible for, one sentence>",
  key_units: [ "<class / function / interface the module will contain>", ... ]
}
```

Guidance:
- Each feature component (Phase 02) becomes one or more modules under its Phase 03
  `target_path`. A component realised by a prescribed pattern usually splits into
  the pattern's parts — e.g. a Repository pattern → an interface module (the port)
  + an implementation module (the adapter).
- `key_units` names the concrete classes/functions/interfaces — enough for
  `/create-story` and `/dev` to know what to build, not the code itself.
- Module paths MUST sit under the `target_path` Phase 03 assigned to the owning
  component. A module path outside every `target_path` is a structural error.

**VERIFY:**
- ≥ 1 module identified
- Every module has a non-empty `path` and `purpose`
- Every module `path` sits under a Phase 03 `target_path`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=05 --step=5.1 --project-root=. 2>&1
```
```json
{ "phase": "05", "step": "5.1", "module_structure": [ { "path": "...",
  "purpose": "...", "key_units": [ ... ] } ] }
```

---

### Step 5.2: Map the Dependency Wiring

**EXECUTE:**

From the Solution Architecture component `dependencies` (carried in
`feature_components`, Phase 02) and the prescribed patterns (Phase 04), map the
construction-time wiring:

```
wiring_edge = {
  consumer:   "<COMP-NNN that receives the dependency>",
  dependency: "<COMP-NNN, or the named abstraction/port, that is injected>",
  injection_style: "constructor" | "property" | "method" | "factory"
}
```

Guidance:
- Every `feature_components[].dependencies` entry is a wiring edge.
- **Constructor injection is the default** — it makes dependencies explicit and
  testable, and counters the direct-instantiation anti-pattern (Phase 04).
- Use `factory` when construction is conditional or deferred; `property` / `method`
  only when constructor injection is genuinely unsuitable — and say why in the
  module `purpose` or a `key_unit` note.
- When a component depends on an abstraction (a port / interface) rather than a
  concrete component, name the abstraction as the `dependency`.

**VERIFY:**
- Every `feature_components` dependency is represented as a wiring edge
- Every `consumer` resolves to a feature component
- Every `injection_style` is one of the 4 enum values

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=05 --step=5.2 --project-root=. 2>&1
```
```json
{ "step": "5.2", "dependency_wiring": [ { "consumer": "COMP-NNN",
  "dependency": "COMP-NNN", "injection_style": "constructor" } ] }
```

---

### Step 5.3: Validate the Wiring Against the Layer Rules

**EXECUTE:**
```
FOR each wiring_edge:
  - Confirm the consumer→dependency edge respects the layer-boundary rules loaded
    in Phase 03 (dependencies point inward; the domain layer depends on nothing
    outward). A wiring edge that violates a layer rule is an architecture-constraints
    violation — HALT and AskUserQuestion: introduce an abstraction in the inner
    layer, or escalate the conflict.
  - Confirm there is no construction cycle — a cycle is a wiring smell; HALT and
    AskUserQuestion to break it.
```

**VERIFY:**
- No wiring edge violates a layer-boundary rule
- No construction cycle remains

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=05 --step=5.3 --project-root=. 2>&1
```
```json
{ "step": "5.3", "wiring_violations_resolved": [ ... ] }
```

---

### Step 5.4: Identify the Composition Root

**EXECUTE:**
```
Note where the feature's object graph is assembled — the composition root (the
entry point / DI container registration / factory module that wires the graph the
Phase 05.2 edges describe). Record it as a module in module_structure if it is a
distinct file, or as a note on an existing presentation/application module.
```

The composition root is the one place direct instantiation is expected — it is how
DI avoids direct instantiation everywhere else. Naming it keeps `/dev` from
scattering construction across the feature.

**VERIFY:**
- The composition root is identified (a module entry or a recorded note)

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=05 --step=5.4 --project-root=. 2>&1
```
```json
{ "step": "5.4", "composition_root": "<module path or note>" }
```

---

### Step 5.5: Record the Module Structure and Wiring

**EXECUTE:**
```
Assemble the module_structure array (each a full module object) and the
dependency_wiring array (each a full wiring edge).
```

**VERIFY:**
- `module_structure` is a non-empty array; every entry has `path` and `purpose`
- `dependency_wiring` is an array; every entry has `consumer` and `dependency`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=05 --step=5.5 --project-root=. 2>&1
```
```json
checkpoint.phases["05"] = {
  "status": "completed",
  "module_structure": [ { "path": "...", "purpose": "...", "key_units": [ ... ] }, ... ],
  "dependency_wiring": [ { "consumer": "COMP-NNN", "dependency": "COMP-NNN",
                           "injection_style": "constructor" }, ... ],
  "composition_root": "<module path or note>"
}
```

---

## Exit Gate

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

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

---

## Phase Transition Display

```
Display:
  "Phase 05 Complete: Module Structure & Dependency Wiring"
  "Modules planned: {count}  |  Wiring edges: {count}"
  "Composition root: {composition_root}"
  "Proceeding to Phase 06: Test Strategy Hooks"
```
