gsd-path-roadmap

Before executing project helpers, read runtime selection and operating rules.

GSD Path Roadmap Phase

Dispatch one roadmapper, gate its roadmap, and obtain the single approval that authorizes milestone planning. Rolling-wave: the roadmap scopes every milestone; waves and tasks belong to $gsd-path-plan.

Routing instructions below are caller handoffs under the AGENTS.md handoff rule; never invoke an explicit-only sibling skill yourself.

Before dispatch and again before approval, apply the AGENTS.md pending-answer rule with the bundled scripts/discussion_records.py; a follow-up owned by roadmap is resolved in ROADMAP.md, or the phase blocks.

Preconditions

Require pipeline_state.py validate --repo <absolute root> to pass; otherwise return to $gsd-path for ownership checking. Legal entry is decide/done with an existing .project/CHARTER.md and no .project/ROADMAP.md yet, roadmap/active|blocked, or a milestone-boundary re-slice: inspect/active or define/active with no approved INTENT.md for the next milestone and a user request to re-scope the remaining pending entries, or roadmap/active with STATE.milestone null and an abandoned entry in ROADMAP.md (the post-abandon re-slice the build orchestrator hands off). Enter from decide/done only with pipeline_state.py transition, exact expected phase/status/milestone/branch/archive fields, event roadmap started, and --set-phase roadmap --set-status active; never edit STATE directly. In a milestone-boundary re-slice, preserve the entering inspect/active or define/active state throughout the re-slice. Any later phase blocks; mid-milestone re-scope is never legal — finish or ship the active milestone first. A decide/done state with ROADMAP.md already present is milestone-scope decide; route to $gsd-path-plan, never regenerate the roadmap beneath it. Absent CHARTER.md, this is not a program: route to $gsd-path, which continues the single-milestone flow at plan. Before dispatching every re-slice, run the bundled scripts/promote_lookahead.py snapshot-roadmap --roadmap .project/ROADMAP.md --snapshot .project/ROADMAP.before-reslice.md helper. Create the baseline once and retain it through every revision; an existing result is recovery evidence and must never be replaced from the current candidate. When .project/next/ holds a lookahead track, also save its milestone slug. Do not ask for the keep/discard ruling until the candidate roadmap has been generated and passed its gate.

Require .project/CHARTER.md and .project/SYNTHESIS.md (program scope) with a non-empty ## Decisions or ## Settled section and no unresolved NEEDS-USER items before dispatch. Route to the producing phase when a precondition fails.

Process

1. Read the local roadmap template and resolve it to an absolute path.

2. Read the local roadmapper role, then follow the local runtime dispatch contract with deterministic logical task name roadmap and a heavy tier hint. Give it absolute role, AGENTS.md, WORKFLOW.md, CHARTER.md, SYNTHESIS.md, every dispatched evidence file named in .project/research/RESEARCH.md — after milestone archival has moved the active research directory, name the read-only archived manifest and evidence copies under their .project/archive/<NNN>-<slug>/research/ paths instead — template, and output paths, including .project/LESSONS.md when it exists. On a re-slice, also give .project/ROADMAP.before-reslice.md with the instruction to preserve shipped entries byte-for-byte except Status/Archive/Integrated fields and to never modify abandoned entries at all. For a milestone-boundary re-slice, also preserve the existing active entry byte-for-byte; only pending entries are in scope. The output is exactly .project/ROADMAP.md — no other location is canonical.

3. Gate ROADMAP.md: First run python3 <absolute check_handoffs.py> roadmap --repo <absolute root>; its structural result is required in addition to the semantic checks below.

   • Every CHARTER.md Full scope: in item maps to at least one milestone, and every milestone traces back to charter scope.
   • Every milestone entry has Goal, Depends on, Surfaces, Status, Archive, Scope in/out, Success criteria, Risks, and Open questions fields; ids are unique and ordered.
   • Every milestone whose Surfaces is not none has at least one success criterion observable at each named surface. A milestone that delivers something a person uses never carries Surfaces: none.
   • Dependencies reference earlier milestone ids and form an acyclic graph.
   • M001 is the thinnest end-to-end skeleton that burns the riskiest synthesis decisions.
   • Rolling-wave: no waves, tasks, or file lists anywhere in the roadmap.
   • No scope-out veto appears in any milestone; every synthesis decision is honored by at least one milestone's scope.
   • On a re-slice, shipped entries differ from .project/ROADMAP.before-reslice.md only in Status/Archive/Integrated; abandoned entries are byte-for-byte identical.
   • On a milestone-boundary re-slice, the prior active entry is byte-for-byte identical to .project/ROADMAP.before-reslice.md.

4. Redispatch one complete corrected brief under logical task name roadmap, following the runtime dispatch contract and including all gate failures. Allow one revision round. If it still fails, keep the entering inspect/active or define/active state for a milestone-boundary re-slice and use pipeline_state.py transition with that complete state as both the expected and retained state and an event naming the failed roadmap gate. Otherwise use the helper with expected roadmap/active, exact milestone, branch, and archive values, --set-status blocked, and the same event. Then present Outcome with the failed gate, Review linking the resolved absolute ROADMAP.md path (or STATE.md when ROADMAP.md is missing), and Next naming the one correction or user decision required. Stop.

5. On a re-slice with a saved lookahead track, run the bundled scripts/promote_lookahead.py compare-entry --before .project/ROADMAP.before-reslice.md --after .project/ROADMAP.md --milestone <lookahead-slug> helper now. When STATE.milestone is set, append --active-milestone <STATE.milestone>; when it is unset, omit that option. It compares every plan-binding part of the entry while ignoring only Status, Archive, and Integrated, and requires that entry to remain the candidate roadmap's first dependency-ready milestone. When it returns status: unchanged, ask the user to choose Keep the unchanged lookahead track (recommended) or Discard and regenerate the lookahead track. When it returns status: changed, offer Discard and regenerate the lookahead track (recommended) or Request roadmap changes; keeping the stale track is not valid. Apply the ruling and record the helper result and ruling with pipeline_state.py transition, expecting and retaining the complete entering state with event lookahead re-slice ruling: <ruling>; never append it directly. Retain the baseline through any requested roadmap revisions and the final approval decision.

6. On a post-abandon re-slice, first run the bundled scripts/promote_lookahead.py select-next --roadmap .project/ROADMAP.md helper against the gated candidate. When it returns status: complete, report program completion against CHARTER.md's program success criteria and stop without offering a pending-milestone approval. When it returns status: selected, use only its exact milestone in the approval and transition below. A status: none result blocks without mutation. Show every milestone id, goal, and dependency summary as the outcome. Link the resolved absolute .project/ROADMAP.md path, then ask one explicit next question. For a milestone-boundary re-slice, list Approve roadmap and resume the active milestone (recommended) first. For a post-abandon re-slice, list Approve roadmap and inspect <selected-milestone> (recommended) first. Otherwise list Approve roadmap and start the first pending milestone (recommended) first. In every case, list Request changes as the alternative. If the user requests changes, retain the entering state for a milestone-boundary re-slice; otherwise keep phase: roadmap, status: active. Retain the baseline, revise, and re-gate against that same baseline.

7. On approval, record the full current HEAD and use the bundled approval module. For a first roadmap approval use --kind roadmap; for either re-slice use --kind roadmap-reslice. In a milestone-boundary re-slice, --milestone is the unchanged active milestone; after abandon, it is the helper-selected pending milestone reviewed by the user.

   python3 <absolute pipeline_state.py> approve \
     --repo <absolute root> --kind roadmap-reslice \
     --milestone <reviewed milestone slug> --expected-head <recorded full HEAD>
   

   The helper owns roadmap selection, expected state, baseline cleanup and the approval checkpoint. It journals before mutation, retains the baseline bytes for recovery, and refuses changes to settled or active entries. A milestone-boundary re-slice retains Inspect or Define; a post-abandon re-slice enters Inspect. Require its typed result to report status: approved, the requested kind, milestone and returned commit. After an interruption, follow the router's resume-checkpoint action; do not edit state, delete the baseline or checkpoint separately.

   Before Git exists, or during a Kind: new-github transaction, use the same approval command with --defer-checkpoint instead of --expected-head. That existing deferred path writes the metadata without a Git journal or commit; the next build checkpoint owns it. Retain the baseline through revisions and rejected approvals. Confirm approval, link ROADMAP.md again, and use the executable phase handoff in AGENTS.md without another gate.

Rules

• Cover the charter exactly: no unmapped scope, no unscoped milestones.
• Milestone granularity only; never drift into waves, tasks, or file scopes.
• Every milestone must be shippable on its own stated dependencies.
• Surface scope cuts as NEEDS-USER; never drop charter scope silently.