# Phase 03: Component Decomposition

## Entry Gate

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

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

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Decompose the epic into logical software components — cohesive units of responsibility, each placed in an architectural layer, with the inter-component dependency graph mapped. Components are the building blocks the interface contracts (Phase 04) and feature decomposition (Phase 07) are expressed in terms of. |
| **REFERENCE** | `.claude/skills/spec-driven-solution-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:

- [ ] The layer-boundary rules loaded from `architecture-constraints.md` (or an explicit fallback recorded)
- [ ] `components` enumerated — each a `COMP-NNN` with a single responsibility and a layer
- [ ] Every component's `layer` is one of the 4 enum values
- [ ] The dependency graph mapped; no dependency violates a layer-boundary rule

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

---

## Reference Loading [MANDATORY]

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

The `$defs.component` shape (`id`, `name`, `responsibility`, `layer`,
`dependencies`, `exposes`) is exactly what each step below must produce. IF the
Read fails: HALT — "Phase 03 output contract not loaded."

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

---

## Mandatory Steps

### Step 3.1: Load the Layer-Boundary Rules

**EXECUTE:**
```
Glob(pattern="devforgeai/specs/context/architecture-constraints.md")
IF found:
  Read(file_path="devforgeai/specs/context/architecture-constraints.md")
  Extract the layer-boundary rules — which layers may depend on which.
ELSE:
  Record an explicit fallback: the standard 4-layer rule — dependencies point
  inward only (presentation → application → domain; infrastructure → domain),
  the domain layer depends on nothing.
```

`architecture-constraints.md` is constitutional and immutable — read it, never
edit it. Its layer rules govern Step 3.4.

**VERIFY:**
- Layer-boundary rules captured (from the context file or the recorded fallback)

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=03 --step=3.1 --project-root=. 2>&1
```
```json
{ "phase": "03", "step": "3.1", "layer_rules_source": "<architecture-constraints.md|fallback>" }
```

---

### Step 3.2: Identify the Components

**EXECUTE:**

From `epic_scope.in_scope` and `epic_scope.requirement_refs` (Phase 02), identify
the components. Each component is a cohesive unit with ONE responsibility (SRP):

```
component = {
  id: "COMP-001",                # ^COMP-[0-9]{3,}$
  name: "<noun phrase — what the component is>",
  responsibility: "<the single responsibility, one sentence>",
  layer: "<assigned in Step 3.3>",
  dependencies: [],              # mapped in Step 3.4
  exposes: []                    # cross-linked from Phase 04 (IFC-NNN ids)
}
```

A component whose `responsibility` needs the word "and" to describe it is doing
two jobs — split it. Every epic in-scope capability must be realized by at least
one component.

**VERIFY:**
- ≥ 1 component identified
- Every `id` matches `^COMP-[0-9]{3,}$` and is unique
- Every `responsibility` describes a single concern

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=03 --step=3.2 --project-root=. 2>&1
```
```json
{ "step": "3.2", "components_identified": [ { "id": "...", "name": "...", "responsibility": "..." } ] }
```

---

### Step 3.3: Place Each Component in a Layer

**EXECUTE:**

Assign every component a `layer` from the 4-value enum, consistent with the
`architecture-constraints.md` layer model:

```
"presentation"   — UI, controllers, API surface, CLI entry points
"application"    — use-case orchestration, application services, workflow coordination
"domain"         — entities, domain logic, business rules, invariants
"infrastructure" — persistence, external-service clients, messaging, framework adapters
```

When a component's placement is genuinely ambiguous, HALT and AskUserQuestion —
do not guess; layer placement determines the dependency rules in Step 3.4.

**VERIFY:**
- Every component has a `layer` ∈ {presentation, application, domain, infrastructure}

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=03 --step=3.3 --project-root=. 2>&1
```
```json
{ "step": "3.3", "layer_placement": [ { "id": "COMP-NNN", "layer": "..." } ] }
```

---

### Step 3.4: Map the Dependency Graph

**EXECUTE:**

For each component, list the `COMP-NNN` ids it depends on. Every dependency MUST
respect the layer-boundary rules from Step 3.1:

```
FOR each component C:
  FOR each dependency D:
    IF the edge C → D violates a layer-boundary rule
       (e.g. a domain component depending on an infrastructure component):
      This is an architecture-constraints violation — HALT and AskUserQuestion:
      restructure the dependency (introduce an abstraction in the inner layer),
      or escalate as a constraint conflict.
Also check for dependency cycles — a cycle is a decomposition smell; HALT and
AskUserQuestion to break it.
```

**VERIFY:**
- Every `dependencies[]` entry is a valid `COMP-NNN` id defined in Step 3.2
- No dependency violates a layer-boundary rule
- No dependency cycle remains

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=03 --step=3.4 --project-root=. 2>&1
```
```json
{ "step": "3.4", "dependency_edges": [ { "from": "COMP-NNN", "to": "COMP-NNN" } ],
  "violations_resolved": [ ... ] }
```

---

### Step 3.5: Record the Component Decomposition

**EXECUTE:**
```
Assemble the components array — each entry the full component object with id,
name, responsibility, layer, and dependencies. Leave exposes as an empty array;
Phase 04 cross-links the IFC-NNN ids each component exposes.
```

**VERIFY:**
- The `components` array is non-empty and every entry has `id`, `name`,
  `responsibility`, `layer`

**RECORD:**
```bash
devforgeai-validate phase-record ${SOLARCH_ID} --workflow=solution-architecture --phase=03 --step=3.5 --project-root=. 2>&1
```
```json
checkpoint.phases["03"] = {
  "status": "completed",
  "layer_rules_source": "<source>",
  "components": [
    { "id": "COMP-001", "name": "...", "responsibility": "...",
      "layer": "...", "dependencies": [ ... ], "exposes": [] }, ...
  ]
}
```

---

## Exit Gate

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

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

---

## Phase Transition Display

```
Display:
  "Phase 03 Complete: Component Decomposition"
  "Components: {count}  |  Layers used: {list}"
  "Dependency edges: {count}  |  Layer violations resolved: {count}"
  "Proceeding to Phase 04: Interface & Contract Design"
```
