/nw-finalize

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

Finalize a completed feature: verify all steps done|create evolution document|migrate lasting artifacts to permanent directories|preserve delivery history|remove session-only state. Agent gathers project data|analyzes execution history|writes summaries|migrates|cleans session state.

`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 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 Copy to Permanent Destinations

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

| 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 — Preserve History and Clean Session State

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 gen