git:20260611.3860ed5 to git:20260825.15011e6

20 added, 19 removed. Audit A to A.

---

name: nw-finalize

description: "Archives a completed feature to docs/evolution/, migrates lasting artifacts to permanent directories, and cleans up the temporary workspace. Use after all implementation steps pass and mutation testing completes."

user-invocable: false

argument-hint: '[agent] [feature-id] - Example: @platform-architect "auth-upgrade"'

---

# NW-FINALIZE: Feature Completion and Archive

**Wave**: CROSS_WAVE

**Agent**: @nw-platform-architect (default) or specified agent

## Overview

- `docs/feature/{feature-id}/` is a **temporary workspace** — it exists during active nWave waves (DISCUSS through DELIVER). At finalize, artifacts with lasting value migrate to permanent directories; the rest is discarded.

+ `docs/feature/{feature-id}/` becomes **delivery history** at finalize. Artifacts with lasting value are also copied to permanent directories, while the complete wave history remains available to the wave matrix.

## Usage

```

/nw-finalize @{agent} "{feature-id}"

```

## Context Files Required

The completion-evidence files are `docs/feature/{feature-id}/deliver/roadmap.json` (the original project plan) and `docs/feature/{feature-id}/deliver/execution-log.json` (step execution history).

## Pre-Dispatch Gate: All Work Complete

Before dispatching, verify all work is done — prevents archiving incomplete features.

1. **Parse execution log** — Read `docs/feature/{feature-id}/deliver/execution-log.json`. Gate: file readable.

2. **Verify completeness** — Check every step has status `DONE`. Gate: all steps DONE.

3. **Block or proceed** — If any step is not DONE, list incomplete steps with current status and halt. If all DONE, proceed to dispatch. Gate: zero incomplete steps before dispatch.

## Phases

### Phase A — Evolution Document

1. **Gather source data** — Read `execution-log.json` + `roadmap.json` (the step log and plan), and all `*/wave-decisions.md` files. Gate: source files read.

2. **Extract key decisions** — Pull decisions, issues, and lessons from wave-decisions files. Gate: decisions list assembled.

3. **Write evolution doc** — Create `docs/evolution/YYYY-MM-DD-{feature-id}.md` with: feature summary, business context, key decisions, work completed (from `execution-log.json`), lessons learned, issues encountered, links to migrated permanent artifacts. Gate: file written.

### Phase B — Migrate Lasting Artifacts

1. **Scan workspace** — List all files under `docs/feature/{feature-id}/`. Gate: file list produced.

2. **Match against destination map** — For each file, apply the destination map below. Gate: migration plan assembled.

3. **Create destination directories** — Create any missing permanent directories. Gate: directories exist.

4. **Copy files** — Copy each matched file to its permanent destination. Gate: all copies verified.

- 5. **Log skipped files** — Note any files from the discard list (not migrated). Gate: discard list documented.

+ 5. **Log non-migrated files** — Note files retained only in delivery history (not copied). Gate: non-migration list documented.

#### Destination Map

| Source (temporary workspace) | Destination (permanent) | Condition |

|---|---|---|

| `design/architecture-design.md` | `docs/architecture/{feature}/` | If exists |

| `design/component-boundaries.md` | `docs/architecture/{feature}/` | If exists |

| `design/technology-stack.md` | `docs/architecture/{feature}/` | If exists |

| `design/data-models.md` | `docs/architecture/{feature}/` | If exists |

| `design/adrs/ADR-*.md` | `docs/adrs/` | Flat namespace, cross-feature |

| `distill/walking-skeleton.md` | `docs/scenarios/{feature}/` | Walking skeleton specification |

| `discuss/journey-*.yaml` | `docs/ux/{feature}/` | If UX journeys exist |

| `discuss/journey-*-visual.md` | `docs/ux/{feature}/` | If UX visuals exist |

Research docs (`docs/research/`) are already in a permanent location — no migration needed.

- #### What NOT to Migrate (Discard)

+ #### What NOT to Copy to Permanent Destinations

- These are process scaffolding — valuable during delivery, disposable after:

+ These are process scaffolding. They remain in delivery history but are not copied elsewhere:

- | File pattern | Why discard |

+ | File pattern | Why not copied |

|---|---|

| `deliver/execution-log.json` | Audit trail — captured in evolution doc |

| `deliver/roadmap.json` | Step plan — superseded by evolution doc + git history |

| `deliver/.develop-progress.json` | Resume state — temporary |

| `design/review-*.md` | Review findings captured in evolution doc |

| `discuss/dor-checklist.md` | Process gate, not lasting value |

| `discuss/shared-artifacts-registry.md` | Process scaffolding |

| `discuss/prioritization.md` | Superseded by roadmap execution |

| `*/wave-decisions.md` | Key decisions extracted into evolution doc |

- ### Phase C — Cleanup Workspace

+ ### Phase C — Preserve History and Clean Session State

- 1. **List remaining files** — List all files still in `docs/feature/{feature-id}/` after migration. Gate: list produced.

- 2. **Present for approval** — Show the exact list to the user and request approval. Gate: user explicitly approves.

- 3. **Preserve workspace** — `docs/feature/{feature-id}/` is NOT deleted. The wave matrix derives status from this directory. Removing it would make finalized features disappear from the matrix. The evolution doc in `docs/evolution/` is the summary; the feature directory is the history. Gate: directory preserved, session markers removed.

- 4. **Clean session artifacts only** — Remove `.nwave/des/deliver-session.json`, `.develop-progress.json`, and any temp files. Do NOT remove wave artifacts (discuss/, design/, distill/, deliver/). Gate: session markers removed, wave artifacts intact.

+ 1. **List session artifacts** — List only session markers and temp files proposed for removal. Gate: exact list produced.

+ 2. **Present for approval** — Show the exact removal list to the user and request approval. Gate: user explicitly approves.

+ 3. **Preserve delivery history** — `docs/feature/{feature-id}/` is NOT deleted. The wave matrix derives status from this directory. Removing it would make finalized features disappear from the matrix. The evolution doc in `docs/evolution/` is the summary; the feature directory is the history. Gate: directory and wave artifacts preserved.

+ 4. **Remove session artifacts only** — Remove `.nwave/des/deliver-session.json`, `.develop-progress.json`, and approved temp files. Do NOT remove wave artifacts (discuss/, design/, distill/, deliver/). Gate: session markers removed, wave artifacts intact.

**NEVER delete without user approval.** Show exactly what will be removed.

### Phase D — Post-Cleanup Verification

1. **Verify migrated files** — Confirm every file copied in Phase B exists at its destination. Gate: all destinations present.

2. **Update architecture doc statuses** — Change any "FUTURE DESIGN" labels to "IMPLEMENTED" in migrated architecture docs. Gate: no stale FUTURE DESIGN labels.

3. **Optionally generate reference docs** — Invoke /nw-document unless `--skip-docs` flag provided. Gate: docs generated or skipped.

4. **Commit evolution doc and artifacts** — Commit 1: evolution doc + migrated artifacts. Gate: commit created.

- 5. **Commit workspace cleanup** — Commit 2: workspace removal. Gate: commit created and pushed.

+ 5. **Commit session cleanup** — Commit 2: removal of session-only artifacts. Gate: commit created and pushed.

## Agent Invocation

@{agent}

Finalize: {feature-id}

**Key constraints:**

1. Follow the 4-phase process (A → B → C → D) in order.

2. Create evolution document BEFORE migration (needs source files).

3. Migrate BEFORE cleanup (preserves artifacts).

- 4. Show cleanup list and wait for user approval before removing anything.

+ 4. Show the session-artifact removal list and wait for user approval before removing anything.

5. Commit and push after approval.

## Success Criteria

- [ ] All steps verified DONE before dispatch

- [ ] Evolution document created in docs/evolution/

- [ ] Architecture docs migrated to docs/architecture/{feature}/

- [ ] ADRs migrated to docs/adrs/ (if any)

- [ ] Scenario docs migrated to docs/scenarios/{feature}/ (if any)

- [ ] UX journeys migrated to docs/ux/{feature}/ (if any)

- - [ ] User approved cleanup before workspace removal

- - [ ] Workspace directory removed: docs/feature/{feature-id}/

+ - [ ] User approved removal of session-only artifacts

+ - [ ] Workspace directory preserved: docs/feature/{feature-id}/

+ - [ ] Only session markers and approved temp files removed

- [ ] Architecture docs updated to "IMPLEMENTED" status

- [ ] Committed and pushed

## Permanent Directory Structure

```

docs/

adrs/ # ADR-NNN-{slug}.md (flat, cross-feature)

architecture/ # Design docs by feature

{feature}/

architecture-design.md

component-boundaries.md

data-models.md

technology-stack.md

decisions/ # Product decisions by feature (optional)

{feature}/

evolution/ # Post-mortem summaries

YYYY-MM-DD-{feature-id}.md

research/ # Research docs (flat, cross-feature)

scenarios/ # Acceptance test documentation by feature

{feature}/

walking-skeleton.md

ux/ # UX specs and journeys by feature

{feature}/

journey-*.yaml

journey-*-visual.md

```

## Error Handling

| Error | Response |

|-------|----------|

| Invalid agent name | "Invalid agent. Available: nw-researcher, nw-software-crafter, nw-solution-architect, nw-product-owner, nw-acceptance-designer, nw-platform-architect" |

| Missing feature ID | "Usage: /nw-finalize @agent 'feature-id'" |

| Project directory not found | "Project not found: docs/feature/{feature-id}/" |

| Incomplete steps | Block finalization, list incomplete steps |

- | No files to migrate | Log "No lasting artifacts found — skipping Phase B" and proceed to cleanup |

+ | No files to migrate | Log "No lasting artifacts found — skipping Phase B" and proceed to session cleanup |

## Examples

### Example 1: Standard finalization

```

/nw-finalize @nw-platform-architect "auth-upgrade"

```

- Verifies all steps done. Creates evolution doc. Migrates `design/architecture-design.md` → `docs/architecture/auth-upgrade/`, ADRs → `docs/adrs/`, test-scenarios → `docs/scenarios/auth-upgrade/`. Shows remaining files, user approves, removes workspace. Commits.

+ Verifies all steps done. Creates evolution doc. Migrates `design/architecture-design.md` → `docs/architecture/auth-upgrade/`, ADRs → `docs/adrs/`, test-scenarios → `docs/scenarios/auth-upgrade/`. Shows session artifacts, user approves their removal, and preserves the feature history. Commits.

### Example 2: Blocked by incomplete steps

```

/nw-finalize @nw-platform-architect "data-pipeline"

```

Pre-dispatch gate finds step 02-03 status IN_PROGRESS. Returns: "BLOCKED: 1 incomplete step - 02-03: IN_PROGRESS. Complete all steps before finalizing."

## Next Wave

**Handoff To**: Feature complete - no next wave

- **Deliverables**: docs/evolution/YYYY-MM-DD-{feature-id}.md, migrated artifacts, cleaned workspace

+ **Deliverables**: docs/evolution/YYYY-MM-DD-{feature-id}.md, migrated artifacts, preserved feature history with session state removed

## Expected Outputs

```

docs/evolution/YYYY-MM-DD-{feature-id}.md

docs/architecture/{feature}/ (migrated design docs)

docs/adrs/ADR-*.md (migrated ADRs)

docs/scenarios/{feature}/ (migrated test scenarios)

docs/ux/{feature}/ (migrated UX journeys, if any)

- Removed: docs/feature/{feature-id}/

+ Preserved: docs/feature/{feature-id}/ (wave history; session artifacts removed)

```