# Phase 03: Layer Placement Mapping

## Entry Gate

```bash
devforgeai-validate phase-check ${DEVARCH_ID} --workflow=development-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** | Map every component of the feature to its architectural layer and its concrete target location in the source tree. The Solution Architecture already assigned each component a `layer`; this phase confirms that layer and ADDS the implementation-ready `target_path` — the source-tree directory where the component's code will live, consistent with `source-tree/` and `architecture-constraints.md`. |
| **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:

- [ ] `source-tree/` and `architecture-constraints.md` loaded (or an explicit fallback recorded)
- [ ] Every feature component has a confirmed `layer` ∈ the 4-value enum
- [ ] Every feature component has a non-empty `target_path` in the source tree
- [ ] No `target_path` contradicts the `source-tree/` structure or the component's layer
- [ ] `layer_placement_map` assembled — one `layer_placement` entry per feature component

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

---

## Reference Loading [MANDATORY]

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

`architecture-constraints.md` is a constitutional file this phase MUST load — its
layer-boundary rules govern every `target_path` (Step 3.1). It is hook-enforced:
`pre-phase-record-reference-check.sh` (ADR-091) blocks `phase-record` for this phase
if it was not Read(). The output schema above defines the `$defs.layer_placement`
shape (`component_ref`, `layer`, `target_path`, `rationale`) each step must produce.
(`source-tree/governance.json` is also read in Step 3.1 but is intentionally NOT
gate-enforced: it is read optional-with-fallback (`Glob → IF found … ELSE fallback`),
so a hard `[MANDATORY]` requirement would false-block projects that legitimately lack
it. gh#297/ADR-135 gates constitutional `.yaml` reads — NOT `.json` — for exactly this
reason; do not add `governance.json` to this manifest.) IF any Read fails: HALT —
"Phase 03 references not loaded."

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

---

## Mandatory Steps

### Step 3.1: Load the Source-Tree and Layer Rules

**EXECUTE:**
```
Glob(pattern="devforgeai/specs/context/source-tree/governance.json")
IF found:
  Read(file_path="devforgeai/specs/context/source-tree/governance.json")
  Extract the directory structure and the layer→directory conventions.
ELSE:
  Record an explicit fallback: the standard layered layout — presentation under
  src/presentation/ (or src/api/, src/cli/), application under src/application/,
  domain under src/domain/, infrastructure under src/infrastructure/.

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: dependencies point inward only.
```

`source-tree/` and `architecture-constraints.md` are constitutional and immutable —
read them, never edit them. Their structure governs every `target_path`.

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

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

---

### Step 3.2: Confirm the Component Layers

**EXECUTE:**
```
FOR each component C in feature_components (Phase 02):
  C.layer was assigned by the Solution Architecture. Confirm it is one of:
    "presentation" | "application" | "domain" | "infrastructure"
  The Development Architecture does NOT re-decide the layer — the Solution
  Architecture owns layer placement. IF a component's layer is missing or not in
  the enum, that is a defect in the source document: HALT and AskUserQuestion.
```

This phase REFINES the Solution Architecture's layer assignment into a source-tree
location — it does not overrule it.

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

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=03 --step=3.2 --project-root=. 2>&1
```
```json
{ "step": "3.2", "component_layers": [ { "component_ref": "COMP-NNN", "layer": "..." } ] }
```

---

### Step 3.3: Assign the Target Path

**EXECUTE:**
```
FOR each component C in feature_components:
  Derive C.target_path — the source-tree directory the component's code will live in:
    - Use the layer→directory convention from source-tree/ (Step 3.1).
    - Place the component under the directory that source-tree/ assigns to its
      layer, in a sub-directory named for the component's domain/feature concern.
    - Example: a domain component for orders → "src/domain/orders/".
  When source-tree/ gives no unambiguous home for the layer, or two locations are
  equally valid, HALT and AskUserQuestion — do not guess a path.

layer_placement_entry = {
  component_ref: "COMP-NNN",
  layer: "<the confirmed layer>",
  target_path: "<source-tree directory>",
  rationale: "<why this path — which source-tree/ convention it follows>"
}
```

**VERIFY:**
- Every component has a non-empty `target_path`
- Every `component_ref` matches `^COMP-[0-9]{3,}$`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=03 --step=3.3 --project-root=. 2>&1
```
```json
{ "step": "3.3", "target_paths": [ { "component_ref": "COMP-NNN", "target_path": "..." } ] }
```

---

### Step 3.4: Validate Against the Source Tree and Constraints

**EXECUTE:**
```
FOR each layer_placement_entry:
  - Confirm target_path is consistent with the source-tree/ structure — it sits
    under a directory source-tree/ recognizes for the component's layer.
  - Confirm the placement does not violate a layer-boundary rule: a domain
    component does not land in an infrastructure directory, etc.
  - A target_path that contradicts source-tree/ is an architecture-constraints
    violation — HALT and AskUserQuestion: correct the path or escalate the conflict.
```

**VERIFY:**
- No `target_path` contradicts `source-tree/`
- No placement violates a layer-boundary rule

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

---

### Step 3.5: Record the Layer Placement Map

**EXECUTE:**
```
Assemble the layer_placement_map array — one entry per feature component, each a
full layer_placement object with component_ref, layer, target_path, and rationale.
```

**VERIFY:**
- `layer_placement_map` has one entry per feature component
- Every entry has `component_ref`, `layer`, `target_path`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=03 --step=3.5 --project-root=. 2>&1
```
```json
checkpoint.phases["03"] = {
  "status": "completed",
  "source_tree_source": "<source>",
  "layer_rules_source": "<source>",
  "layer_placement_map": [
    { "component_ref": "COMP-001", "layer": "domain",
      "target_path": "src/domain/...", "rationale": "..." }, ...
  ]
}
```

---

## Exit Gate

```bash
devforgeai-validate phase-complete ${DEVARCH_ID} --workflow=development-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: Layer Placement Mapping"
  "Components mapped: {count}  |  Layers used: {list}"
  "Source-tree paths assigned: {count}"
  "Proceeding to Phase 04: Design Pattern Selection"
```
