feat: MGW/GSD architecture repair — ROADMAP-first flow, debug route, phase traceability

[snipcodeit]

Summary

Full MGW v3 architecture implementation. What started as a foundation repair now covers state-aware project initialization, a 6-stage vision collaboration cycle for fresh projects, and multi-milestone GSD tracking.

Originally landed (Phase 1 + Phase 2)

• Add CLAUDE.md with architecture overview, delegation boundary, and command surface
• Refactor `mgw:project` to read GSD's ROADMAP.md first (Path A/B)
• Add `gsd:diagnose-issues` debug route through the pipeline
• ROADMAP.md existence gate in `run.md`
• Phase mapping lookup from `project.json` for PR traceability
• Failed issue recovery (Retry/Skip/Abort) and end-of-milestone report
• `diagnosing` pipeline stage; failed issues surfaced in `next.md`

Milestone A — State Detection + Alignment (issues #103–107, closed)

• A1 (`13bb053`): 5-signal state detection matrix (P/R/S/M/G) — Fresh/GSD-Only/GSD-Mid-Exec/Aligned/Diverged/Extend routing
• A2+A5 (`4efccc8`): `alignment-analyzer` Task agent for GSD-only backfill; `drift-analyzer` for diverged state reconciliation
• A3 (`88ef17d`): `milestone_mapper` step — GSD-to-GitHub milestone creation + `maps-to` link type in `link.md`
• A4 (`a0b8190`): `migrateProjectState()` + `resolveActiveMilestoneIndex()` in `lib/state.cjs`

Milestone B — Vision Collaboration Cycle (issues #108–112, closed)

• B1 (`3d77179`): Vision Brief JSON schema (`templates/vision-brief-schema.json`), CLAUDE.md Vision Cycle docs
• B2 (`4ec1b39`): `vision_intake` + `vision_research` steps — captures RAW_IDEA, spawns silent `vision-researcher` domain agent
• B3 (`04e3637`): `vision_questioning` loop — 8-round soft cap, 15-round hard cap, decisions appended to `vision-draft.md`
• B4 (`6ef9706`): `vision_synthesis` (synthesizer agent + accept/revise/dig-deeper loop) + `vision_condense` (condenser agent → `vision-handoff.md`)
• B5 (`b628466`): `spawn_gsd_new_project` — hands condensed Vision Brief to `gsd:new-project` Task spawn, verifies `.planning/` output, routes to `milestone_mapper`

Milestone C — Multi-Milestone Tracking (issues #113–116, closed)

• C1 (`37f3d5f`): Replace `current_milestone` integer with `active_gsd_milestone` string across `milestone.md`, `next.md`, `status.md`, `run.md`
• C2 (`c6bc557`): Cross-milestone detection in `run.md` — quick issues run in isolation, plan-phase issues warn + offer switch
• C3 (`c6fc5c8`): `maps-to` link consistency check in `mgw:sync` — verifies GSD milestone exists in `.planning/`
• C4 (`f1b4830`): Milestone completion verification — checks next milestone's GSD linkage, prompts `gsd:new-milestone` if unlinked

project.json Schema Delta

Field	Before	After
`current_milestone`	`7` (integer, 1-indexed)	kept for legacy compat via `resolveActiveMilestoneIndex()`
`active_gsd_milestone`	(absent)	`"v1.1"` (string, nullable)
`milestones[].gsd_milestone_id`	(absent)	`"v1.0"` (string, nullable)
`milestones[].gsd_state`	(absent)	`"active"|"completed"|"planned"|null`
`milestones[].roadmap_archived_at`	(absent)	ISO timestamp or null

State Sync

• `.mgw/project.json` updated: milestones 10–12 and all 14 issues tracked with new schema fields and board item IDs
• GitHub milestones 10, 11, 12 closed
• All 14 issues added to project board (docs: README.md missing init command and has stale state claims #9) with Status = done

Test Plan

• `mgw:project` on fresh repo → Vision Cycle → gsd:new-project → milestone creation
• `mgw:project` on GSD-only repo → alignment-analyzer → milestone backfill
• `mgw:project` on diverged repo → drift-analyzer → reconciliation table
• `mgw:project` on aligned repo → status report, extend offer
• `mgw:run` on quick issue in non-active milestone → "running in isolation" note
• `mgw:run` on plan-phase issue in non-active milestone → warning + switch/continue/abort
• `mgw:milestone` completion → next milestone GSD linkage check
• `mgw:sync` with maps-to links → validates GSD milestone in .planning/
• `lib/state.cjs` migration → existing project.json gets new null fields added
• `resolveActiveMilestoneIndex` → resolves both legacy integer and new string schema

Closes #100

[snipcodeit]

this looks like we're finally lineing up with our vision. however, the roadmap is attached to a specific milestone right? or is that the project? I'm seeing potentional collision of visions because mgw should be capable of handling multiple milestones, while I think gsd tends to deep focus 1 specific milestone at a time?

[snipcodeit]

Great question — the concern is valid but the architecture actually handles this correctly. Let me break it down:

GSD ROADMAP.md is milestone-scoped, not project-scoped

GSD's ROADMAP.md is replaced with each gsd:new-milestone run. From the GSD workflow:

Starting phase number: Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).

So ROADMAP.md always contains only the current active milestone's phases. It is not a cumulative document — it's a rolling window.

The intended handshake

The correct flow is:

1. gsd:new-project → PROJECT.md + ROADMAP.md (Milestone 1 phases)
2. mgw:project (init) → reads ROADMAP.md → creates GitHub Milestone 1 + issues for each phase
3. Pipeline executes Milestone 1 via GSD + MGW
4. gsd:complete-milestone → archives Milestone 1 state
5. gsd:new-milestone → replaces ROADMAP.md with Milestone 2 phases (continuing phase numbering)
6. mgw:project extend → reads updated ROADMAP.md → adds GitHub Milestone 2 + issues
7. Repeat

MGW's project.json accumulates ALL milestones across the project lifetime. GSD's ROADMAP.md always reflects only what's being built right now. There is no collision — they operate at different scopes by design.

What this PR actually does

Path A (HAS_ROADMAP=true) reads the current ROADMAP.md and creates one batch of GitHub issues from it — exactly what's needed for that milestone. It also handles the extend case: after gsd:new-milestone replaces ROADMAP.md, mgw:project extend with Path A reads the new milestone's phases and adds them to GitHub.

The one gap worth noting

The mgw:project extend flow currently relies on the user knowing to run gsd:new-milestone first before extending MGW. There's no enforcement or prompt that says "has GSD's new-milestone been run?" — we could add a check that validates the ROADMAP.md phases don't overlap with already-created GitHub issues (using the phase counter in project.json). That would be a small follow-up improvement, not a blocker here.

Short answer: your vision is intact. GSD deep-focuses one milestone at a time, MGW tracks the full project history across all milestones. ROADMAP.md is the handoff point — one milestone at a time, both tools agree on what's current.

[snipcodeit]

lets address some things

First, the correct flow is:

mgw:project (init) → (Should determine if previous work across gh, gsd, the local repo, or mgw has occurred. If it does this should trigger some sort of "Lets align with the current projects potential status" stage where it looks at dates, times, issues, comments, etc. it needs to determine WHAT project it's orchestrating. Previous milestones in existing gsd projects should be mapped for historical purposes, future milestones that might exist or phases should be loaded into gh as part of the reflection. If it determines it's a fresh project it should assist the user running gsd:new-project to gauge the FULL scope of the entire project. This will be incredibly extensive in MOST cases, so a collaboration, deliberation, recommendation cycle should occur with the user FIRST. This probably requires new agents, nested cycles and flow driven architecture, so research it.)
→After the project building cycle commences, we pass the entire context of the collaboration and planning cycle into gsd:new-project sub tasks(mgw:project SHOULD rely almost exclusively on tasks agents in order to keep clear context available for the larger orchestration it's handling and managing through mgw, and gsd planning files.) Ideally the user and mgw have collaborated to exactly what this LARGER vision will be, discussed team implementation strategies, observed behaviors from previous work, and gsd:new-project should get the full picture of what the PROJECT.md will be. Then we hit the point my previous comment was referencing.

Originally: gsd:new-project → PROJECT.md + ROADMAP.md

• This creates a set of milestones for the LARGER project. occasionally the gsd milestones will be exactly what the larger vision described, but theres a chance we have such a large scale project during the initial planning phase of mgw:project or mgw:milestone that we end up requiring multiple gsd:new-milestone's. now each inidividual milestone being created with mgw:project will be tracked in github, but what happens when i extend the project, across two seperate gsd:new-milestones and jump between working on issues for the two? or more than two.
  After: mgw:map-project-milestones
  I see us needing a map-project milestones orchastration agent or layer system. we need to be able to correctly archive, analyze, extract, create the gsd:phases and milestones (though the larger gsd project vs the gsd milestone do not have clear division in my head.), and utilizing context aware implementations.
  Pipeline executes Milestone 1 via GSD + MGW

What I WANT to do

/mgw:project "I need to design a website for my customer. He's a mechanic, and he's wanting a site to give him visibility on googles search engine, yelp, and other related social 'find a helper' kind of job sites"

MGW takes me through an extensive cycle where it has internal deliberation, suggestion, review, enhance, condence, etc phases. The idea here is that we end up flushing out the "Full Vision" without pretending we're done or pretending we've covered everything. We want to orchestrate, in some cases, the entire E2E fortune 500 business. Or a NASA flight command center module. Failure is not an option. GSD uses this same failure is not an option methodology which is why tens of thousands of people have flocked to it. Let's not make it worse, trying to make it better.

[snipcodeit]

Architectural Response: mgw:project Redesign

1. State Detection — Decision Tree

When mgw:project runs, before anything else it classifies the environment:

Signal	Check
P	.planning/PROJECT.md exists
R	.planning/ROADMAP.md exists
S	.planning/STATE.md exists
M	.mgw/project.json exists
G	GitHub milestones exist for this repo

P	R	S	M	G	Classification	Action
-	-	-	-	-	Fresh	Full Vision cycle → gsd:new-project
Y	-	-	-	-	GSD-Only (project started)	Alignment: import PROJECT.md context, backfill MGW state
Y	Y	Y	-	-	GSD-Only (mid-execution)	Alignment: parse ROADMAP.md + MILESTONES.md, create GitHub milestones, build project.json
Y	Y	Y	Y	Y	Aligned	Already initialized — report status, offer extend
Y	Y	Y	Y	Y	Diverged	project.json doesn't match GitHub reality — reconcile first

The critical missing case today: someone runs gsd:new-project, works for weeks, then installs MGW. Currently MGW asks "what are you building?" — it should say "I see you have X phases completed. Let me mirror that into GitHub." An alignment-analyzer Task agent handles this — reads .planning/* and git log, returns structured state the orchestrator uses to backfill project.json and create GitHub milestones.

---

2. "Full Vision" Collaboration Cycle

For the Fresh path — mechanic website or NASA flight module — the cycle before GSD ever touches .planning/:

Stage 1 — Intake (user-facing): Freeform. "What do you want to build?" Capture the raw idea.

Stage 2 — Domain Expansion (Task agent, silent): Spawn vision-researcher. Takes the raw idea and returns: domain analysis (what does a mechanic website actually need?), platform requirements (Google Business Profile, Yelp integration, schema.org markup, local SEO), competitive landscape, and risk factors. For the mechanic — surfaces mobile-first design, ADA compliance, review aggregation, booking system decision.

Stage 3 — Structured Questioning (user-facing, 3-8 rounds): Not "tell me more" — targeted questions informed by the research. "Should we integrate Google Business Profile directly, or optimize for organic search? Here's the tradeoff..." Each round narrows scope. Soft cap at 8 rounds, hard cap at 15.

Context strategy: The orchestrator maintains a rolling summary, not a growing transcript. Decisions get appended to .mgw/vision-draft.md after each round. Agents receive the current Brief plus latest delta — never the full conversation history. Context growth stays bounded.

Stage 4 — Vision Synthesis (Task agent, silent): Spawn vision-synthesizer. Takes all Q&A context and produces a draft Vision Brief: project identity, target users, core value proposition, feature categories (must/should/could/won't), technical constraints, success metrics, estimated scope, and recommended milestone structure.

Stage 5 — Review and Refine (user-facing): Present the Brief. User accepts, revises sections, or "dig deeper on X." Revisions loop back to Stage 4 with correction context.

Stage 6 — Condense (Task agent, silent): Spawn vision-condenser. Produces the handoff document — a structured prompt context passed directly into the gsd:new-project Task spawn. This is not a file, it's the full context package that makes gsd:new-project produce a PROJECT.md that reflects everything deliberated.

Agent roster for the cycle:

Agent	Runs	Output
vision-researcher	Once (Stage 2)	Domain analysis
vision-synthesizer	1-N (Stage 4, loops on revision)	Vision Brief draft
vision-condenser	Once (Stage 6)	Handoff context for gsd:new-project

---

3. GSD Project vs Milestone — Definitive Clarification

GSD Project (PROJECT.md) — the full vision. What you're building, why, for whom, success criteria, explicit out-of-scope. Persists across the entire project lifetime. Never replaced, only updated (requirements move from Active → Validated).

GSD Milestone (ROADMAP.md) — a sprint-sized unit of work. 3-12 phases. ROADMAP.md gets replaced by gsd:new-milestone. The old one gets archived to MILESTONES.md. One milestone = ~1-4 weeks of work.

One MGW project = one GSD project. Always. One repo, one PROJECT.md, one .mgw/project.json. MGW holds the full timeline (all milestones). GSD holds the current focus (one ROADMAP.md at a time). This asymmetry is correct — it's not a bug.

Milestone counts by scale: Mechanic website: 2-3 milestones. Enterprise SaaS: 10-20+. MGW itself: 7 milestones so far.

---

4. Multi-GSD-Milestone Tracking

The current project.json uses current_milestone as a single integer. This breaks when a user has issues open across two GSD milestones simultaneously.

Proposed schema change — replace current_milestone with:

{
  "active_gsd_milestone": "v1.1",
  "milestones": [
    {
      "github_number": 3,
      "name": "v1 — Foundation",
      "gsd_milestone_id": "v1.0",
      "gsd_state": "completed",
      "roadmap_archived_at": "2026-02-20T...",
      "issues": [...]
    },
    {
      "github_number": 4,
      "name": "v1 — Integrations",
      "gsd_milestone_id": "v1.1",
      "gsd_state": "active",
      "issues": [...]
    }
  ]
}

Jumping between milestones: mgw:run looks at the issue's milestone assignment in project.json and checks whether it matches active_gsd_milestone.

• Doesn't match + issue is gsd:quick: Run in isolation. Quick-route bugs don't need ROADMAP.md context — no milestone switch needed.
• Doesn't match + issue is gsd:plan-phase: Warn and offer to switch active GSD milestone (archive current ROADMAP.md, load archived target milestone). This is deliberate because plan-phase work needs ROADMAP.md awareness.

Cross-ref addition: New link type for the GitHub-to-GSD handshake:

{ "a": "milestone:3", "b": "gsd-milestone:v1.0", "type": "maps-to" }

---

5. mgw:map-project-milestones — Design

This is a step within mgw:project (and called by mgw:milestone on completion), not a standalone command.

What it does:

1. Read .planning/PROJECT.md, .planning/MILESTONES.md (archived milestones), .planning/ROADMAP.md (active milestone)
2. Read .mgw/project.json (what MGW already knows)
3. Query GitHub for all milestones + issue counts in the repo
4. Diff: which GSD milestones have no GitHub milestone? Which GitHub milestones have no GSD counterpart?
5. Create missing GitHub milestones, backfill project.json entries with gsd_milestone_id and gsd_state

The "3 GSD milestones, 2 GitHub milestones" case: Mapping agent detects the gap, creates the missing GitHub milestone using the archived milestone's name and description from MILESTONES.md, then creates issues from the phase structure. This is a scoped replay of the milestone/issue creation steps for just the missing entry.

---

6. Orchestrator Agent Architecture

The orchestrator is a thin coordinator. Here is the full spawn tree for the redesigned mgw:project:

/mgw:project "mechanic website..."
  │
  ├─[State Detection — orchestrator directly, no agent needed]
  │   File checks + single GraphQL call → classification
  │
  ├─[Fresh] ──────────────────────────────────────────────────────────
  │   Task: vision-researcher (Stage 2)
  │   [Questioning rounds — orchestrator handles user-facing]
  │   Task: vision-synthesizer (Stage 4, loops on revision)
  │   [User review — orchestrator handles]
  │   Task: vision-condenser (Stage 6)
  │   Task: gsd:new-project (receives condensed Vision Brief)
  │     └─ GSD produces PROJECT.md + ROADMAP.md
  │   Task: milestone-mapper (reads GSD output → GitHub milestones/issues)
  │   Orchestrator: write project.json, report summary
  │
  ├─[GSD-Only] ───────────────────────────────────────────────────────
  │   Task: alignment-analyzer (reads .planning/*, git log → structured state)
  │   Task: milestone-mapper (creates GitHub structure from GSD state)
  │   Orchestrator: write project.json, report summary
  │
  ├─[Aligned] ────────────────────────────────────────────────────────
  │   Orchestrator: report status, offer extend mode
  │
  └─[Diverged] ───────────────────────────────────────────────────────
      Task: drift-analyzer (compare project.json vs GitHub reality)
      Task: reconciler (fix gaps)
      Orchestrator: report what was fixed

What the orchestrator itself does and nothing more: state detection (file checks + one API call), classification, user-facing questioning, Task spawning with context passing, writing project.json from agent returns, displaying summaries. Everything analytical or creative is delegated.

---

7. Risks Worth Calling Out

GSD phases that got renamed/split during execution. The alignment agent tries to match phases to GitHub issues. If someone renamed a phase mid-sprint, fuzzy matching on title is needed — not exact slug matching. This needs to be explicit in the alignment agent's prompt.

Half-initialized GSD project (PROJECT.md exists, ROADMAP.md doesn't). User started gsd:new-project but didn't finish. Detection: P=true, R=false. Not GSD-Only — it's partial init. MGW should offer to resume gsd:new-project with existing PROJECT.md as context, not start over.

10+ milestone projects. The schema scales (just a longer array) but the Vision Cycle needs to handle scope gracefully. Only the first 2-3 milestones should be fully detailed in the Brief; later ones stay at "category" level. You can't plan milestone 9 before milestone 3 is done.

Vision Cycle context overload past round 12. The rolling summary + .mgw/vision-draft.md file approach addresses this. If compaction hits, the file persists and the orchestrator reads it back rather than relying on in-context history.

Extend mode while GSD is mid-milestone. mgw:project --extend should check STATE.md for active phase work before proceeding. If work is in progress: "You have active work in phase N. Complete or shelve it before extending the project."

---

Proposed Execution Plan

Milestone A — State Detection + Alignment (3-4 issues)

1. State detection algorithm in mgw:project (signal matrix + classification)
2. alignment-analyzer agent prompt (GSD-Only path)
3. milestone-mapper agent (create GitHub milestones/issues from GSD state)
4. Add gsd_milestone_id, gsd_state, active_gsd_milestone to project.json schema

Milestone B — Vision Collaboration Cycle (4-5 issues)

1. Vision Brief document format (fields, structure)
2. vision-researcher agent prompt
3. Structured questioning flow with round caps + rolling summary
4. vision-synthesizer + vision-condenser agents
5. Wire condensed output into gsd:new-project Task spawn

Milestone C — Multi-Milestone Tracking (3-4 issues)

1. Replace current_milestone with active_gsd_milestone in project.json
2. Milestone-switching logic in mgw:run (detect cross-milestone issue, quick vs plan-phase routing)
3. maps-to link type in cross-refs
4. Integrate map-project-milestones step into mgw:project alignment and mgw:milestone completion

Milestone A first — it unblocks both B and C and solves the most common real-world case (existing GSD projects adopting MGW). Milestone B is the largest and most novel. Milestone C is mechanical once A's schema changes land.