# Phase 02: Feature Framing

## Entry Gate

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

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

---

## Contract

| Attribute | Value |
|-----------|-------|
| **PURPOSE** | Establish WHICH feature this Development Architecture details and confirm its scope. One Development Architecture Document is produced per feature. The feature MUST be one of the `F-NN` entries in the source Solution Architecture's `feature_decomposition`. This phase selects the feature, resolves the components that realize it, and inspects the feature's feasibility verdict — a feature the Solution Architecture marked `INFEASIBLE` cannot be made implementation-ready as designed. |
| **REFERENCE** | `.claude/skills/spec-driven-development-architecture/references/development-architecture-output.schema.json` |
| **STEP COUNT** | 4 mandatory steps |

## Phase Exit Criteria

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

- [ ] `feature_ref` recorded, matching `^F-[0-9]{2,}$`, and present in `sol_feature_decomposition`
- [ ] The feature definition resolved from the Solution Architecture (name, description, feasibility, risk, components, technical_notes)
- [ ] No `INFEASIBLE` feature carried forward; any `NEEDS_ADR` feature recorded as a handoff open question
- [ ] `feature_components` resolved — every feature component id resolves to a `sol_components` entry
- [ ] `feature_scope` confirmed with the user

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

---

## Reference Loading

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

The `feature_ref` property (pattern `^F-[0-9]{2,}$`) is the field this phase
populates. IF the Read fails: HALT — "Phase 02 output contract not loaded."

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

---

## Mandatory Steps

### Step 2.1: Determine the Feature

**EXECUTE:**
```
Build the candidate list from sol_feature_decomposition (Phase 01) — each entry's
id, name, feasibility verdict, and components.

IF $FEATURE_ID was provided and matches ^F-[0-9]{2,}$:
  IF $FEATURE_ID is present in sol_feature_decomposition: feature_ref = $FEATURE_ID
  ELSE: HALT — "Feature ${FEATURE_ID} is not in the source Solution Architecture's
        feature_decomposition. This skill can only develop-architect a feature the
        Solution Architecture defined."
ELSE:
  AskUserQuestion — present the feature_decomposition list (id, name, feasibility,
  risk) and ask which feature this Development Architecture details.
  feature_ref = user selection.
```

One Development Architecture Document details exactly one feature. The feature is
never invented here — it is always selected from the upstream Solution Architecture.

**VERIFY:**
- `feature_ref` matches `^F-[0-9]{2,}$`
- `feature_ref` resolves to an entry in `sol_feature_decomposition`

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=02 --step=2.1 --project-root=. 2>&1
```
```json
{ "phase": "02", "step": "2.1", "feature_ref": "<F-NN>" }
```

---

### Step 2.2: Load the Feature Definition and Inspect Feasibility

**EXECUTE:**
```
Resolve the feature object from sol_feature_decomposition:
feature = {
  id, name, description, feasibility, risk, components, technical_notes
}

IF feature.feasibility == "INFEASIBLE":
  HALT — "The source Solution Architecture marked ${feature_ref} INFEASIBLE: it
  cannot be realized as designed. A Development Architecture cannot make an
  infeasible feature implementation-ready. Revise the Solution Architecture
  (re-run /create-solution-architecture) before develop-architecting this feature."

IF feature.feasibility == "NEEDS_ADR":
  Display: "${feature_ref} is marked NEEDS_ADR by the Solution Architecture — it
  requires a new architecture decision. The Development Architecture proceeds, but
  the open ADR question is carried into the Phase 08 handoff.open_questions."
  needs_adr_note = "Feature ${feature_ref} (${feature.name}) is NEEDS_ADR per the
  Solution Architecture — an ADR must resolve <the decision> before /dev."
ELSE:
  needs_adr_note = null
```

A `NEEDS_ADR` feature is non-blocking here — the decision belongs to an ADR or to
story creation — but it MUST surface in the handoff so it is not lost.

**VERIFY:**
- `feature.feasibility` is `FEASIBLE` or `NEEDS_ADR` (an `INFEASIBLE` verdict would have HALTed)
- `feature` object fully resolved

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=02 --step=2.2 --project-root=. 2>&1
```
```json
{ "step": "2.2", "feature": { "id": "...", "name": "...", "feasibility": "...",
  "risk": "...", "components": [...] }, "needs_adr_note": "<string|null>" }
```

---

### Step 2.3: Resolve and Confirm the Feature Scope

**EXECUTE:**
```
Resolve feature_components — for each COMP-NNN id in feature.components, look up
the full component object in sol_components (Phase 01): its name, responsibility,
layer, dependencies, and exposes. Every feature component id MUST resolve to a
sol_components entry — an unresolved id is a cross-reference error: HALT.

Frame the feature scope:
feature_scope = {
  name: "<feature name>",
  summary: "<one-paragraph statement of what this feature delivers>",
  components: [ "COMP-NNN", ... ],          # the feature's components
  interface_contracts: [ "IFC-NNN", ... ],  # contracts exposed/consumed by those components
  in_scope: [ "<capability inside this feature>", ... ],
  out_of_scope: [ "<adjacent capability NOT in this feature>", ... ]
}
```

`interface_contracts` is derived from the `exposes[]` of the feature components
and any `sol_interface_contracts` they consume. State a one-line scope
recommendation, then `AskUserQuestion` to confirm the feature scope before any
design work.

**VERIFY:**
- Every `feature.components` id resolves to a `sol_components` entry
- `feature_scope.summary` is a non-empty paragraph; `components` has ≥ 1 entry
- The user confirmed the scope (response non-empty)

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=02 --step=2.3 --project-root=. 2>&1
```
```json
{ "step": "2.3", "feature_components": [ ... ], "feature_scope": { ... },
  "user_confirmed_scope": true }
```

---

### Step 2.4: Record the Feature Framing

**EXECUTE:**
```
Assemble the feature framing for downstream phases. Layer placement (Phase 03),
design patterns (Phase 04), module structure (Phase 05), test hooks (Phase 06),
and story seeds (Phase 07) are ALL scoped to this feature — nothing outside
feature_scope is designed.
```

**VERIFY:**
- `feature_ref`, `feature`, `feature_components`, and `feature_scope` are all populated

**RECORD:**
```bash
devforgeai-validate phase-record ${DEVARCH_ID} --workflow=development-architecture --phase=02 --step=2.4 --project-root=. 2>&1
```
```json
checkpoint.phases["02"] = {
  "status": "completed",
  "feature_ref": "<F-NN>",
  "feature": { "id": "...", "name": "...", "description": "...",
               "feasibility": "...", "risk": "...", "components": [...],
               "technical_notes": "..." },
  "feature_components": [ { "id": "COMP-NNN", "name": "...", "responsibility": "...",
                            "layer": "...", "dependencies": [...], "exposes": [...] }, ... ],
  "feature_scope": { "name": "...", "summary": "...", "components": [...],
                     "interface_contracts": [...], "in_scope": [...], "out_of_scope": [...] },
  "needs_adr_note": "<string|null>"
}
```

---

## Exit Gate

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

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

---

## Phase Transition Display

```
Display:
  "Phase 02 Complete: Feature Framing"
  "Feature: {feature_ref} ({feature.feasibility})  |  {feature.name}"
  "Components: {count}  |  Interface contracts in scope: {count}"
  "Proceeding to Phase 03: Layer Placement Mapping"
```
