fix: /mgw:project overwrites ROADMAP.md without creating STATE.md or archiving old phases

[snipcodeit]

Problem

When /mgw:project initializes a new milestone, it writes .planning/ROADMAP.md directly but does not create .planning/STATE.md and does not archive existing phase directories. This leaves GSD workflows in a broken state — STATE.md is required by every GSD workflow (progress, plan, execute, resume) and the stale phase directories cause the roadmap analyzer to mismap completed work.

Current Behavior

Running /mgw:project to create a new milestone roadmap:

1. Writes .planning/ROADMAP.md with new phases — correct
2. Writes .mgw/project.json for MGW state — correct
3. Does NOT create .planning/STATE.md — GSD workflows break
4. Does NOT archive old .planning/phases/*/ — roadmap analyzer maps stale directories to new phases by number
5. Does NOT create/update .planning/MILESTONES.md — no milestone history

Observed Symptoms

• /gsd:health reports BROKEN status (E004: STATE.md not found)
• /gsd:progress shows 100% complete (8/8 plans) — mapping OLD phase directories to NEW roadmap entries
• Phase names don't match: disk has 01-shared-workflow-hardening but roadmap Phase 1 is "Community Files"
• All GSD workflows that read STATE.md on init will fail or produce incorrect routing

Expected Behavior

When /mgw:project creates a new milestone roadmap, it must also:

1. Create .planning/STATE.md from the GSD template, initialized to "Phase 1 ready to plan"
2. Archive old phase directories to .planning/ARCHIVED-phases-{old-milestone}/ (or defer to /gsd:complete-milestone)
3. Create/update .planning/MILESTONES.md to track the transition

Root Cause

commands/project.md (the /mgw:project skill definition) has a "CRITICAL BOUNDARY (PROJ-05)" that intentionally stops after writing ROADMAP.md. The design rationale was "fast and deterministic" — but it crosses the GSD boundary by writing ROADMAP.md without maintaining the rest of GSD's state contract.

The GSD new-project workflow expects a roadmapper agent to create ROADMAP.md + STATE.md + REQUIREMENTS.md together as a unit. /mgw:project bypasses the roadmapper and only creates one of the three required files.

Architecture Constraint

MGW must not block GSD workflows. MGW is an orchestration layer that sits on top of GSD. It should either:

• Option A: Delegate roadmap creation to GSD's roadmapper agent (which handles the full state lifecycle)
• Option B: Create all required GSD state files when it writes ROADMAP.md directly
• Option C: Call /gsd:health --repair after writing ROADMAP.md to regenerate missing state

The key principle: after any MGW operation, GSD workflows must work correctly. If MGW touches .planning/, it owns the responsibility of leaving it in a valid state.

Affected Files

File	Role	Status
commands/project.md	Skill definition for /mgw:project	Writes ROADMAP.md only
lib/gsd.cjs	Bridge to GSD tools	Has invokeGsdTool() but not used for state creation
lib/state.cjs	MGW's own .mgw/ state	Works correctly for MGW state

Immediate Fix Needed

For the current broken state:

1. Archive 01-shared-workflow-hardening/, 02-template-engine/, 03-project-initialization/, 05-standalone-tools/ to .planning/ARCHIVED-phases-internal-dev/
2. Create .planning/STATE.md from template, pointing at Phase 1 of current roadmap
3. Ensure /gsd:health reports HEALTHY

Long-term Fix

Modify /mgw:project to maintain the full GSD state contract when writing ROADMAP.md. This means either spawning the roadmapper or explicitly creating STATE.md alongside ROADMAP.md using lib/gsd.cjs.

Reproduction

# In any repo with existing .planning/ phases
/mgw:project  # Creates new ROADMAP.md
/gsd:health   # Reports BROKEN - STATE.md missing
/gsd:progress # Shows incorrect completion mapping

[snipcodeit]

MGW · triage-complete · 2026-02-26T23:08:17Z

Triage Complete

Scope	medium — 3 files across commands/project-skill, lib/state-or-gsd, .claude/commands-mirror
Validity	confirmed
Security	None
Route	gsd:quick --full — Medium scope (2 skill files + 1 lib), well-defined template contract, needs verification
Conflicts	None

Work begins on branch issue/33-mgw-project-state-md-archival.

Affected Files

• commands/project.md
• .claude/commands/mgw/project.md
• lib/gsd.cjs

[snipcodeit]

MGW · execution-complete · 2026-02-26T23:19:43Z

Execution Complete

2 atomic commit(s) on branch issue/33-mgw-project-state-md-archival.

Changes: 2 files changed, 232 insertions(+), 2 deletions(-)

Verification: 5/5 must-haves passed

Preparing pull request.

[snipcodeit]

MGW · pr-ready · 2026-02-26T23:20:55.171Z

PR Ready

PR #34 — #34

Adds archive_phases and write_state steps to /mgw:project so GSD state is always valid after project initialization.

Testing procedures posted on the PR.
This issue will auto-close when the PR is merged.

Pipeline Summary

Stage	Status
Triage	done
Planning	done
Plan Check	done (passed)
Execution	done (2 commits)
Verification	done (5/5 must-haves)
PR Creation	done (#34)

[snipcodeit]

Closing — the diagnosis was correct (MGW breaks GSD state) but the proposed fix was wrong (making MGW write more GSD files). The real fix: MGW should stop writing ROADMAP.md entirely. MGW derives its roadmap from GitHub state dynamically; GSD manages all .planning/ files. See replacement issue.