@opengsd/gsd-path 1.0.0

package/skills/gsd-path/RESEARCH.md

@@ -0,0 +1,159 @@
+---
+name: gsd-path-research
+description: Dispatch parallel researchers and collect cited GSD Path evidence about domain, stack, pitfalls, and comparable products. Use only when the user explicitly invokes $gsd-path-research or an active $gsd-path router explicitly routes to this phase.
+---
+
+# GSD Path Research Phase
+
+Dispatch independent researchers and gate their evidence. Keep synthesis out
+of this phase. The durable output is a research dispatch manifest plus one
+evidence file per dispatched dimension.
+
+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 completion, apply the AGENTS.md
+pending-answer rule with the bundled `scripts/discussion_records.py`; a
+follow-up owned by research is resolved through its evidence handoff, or
+the phase blocks.
+
+## Preconditions
+
+Require `pipeline_state.py validate --repo <absolute root> [--project-dir
+.project/next]` to pass; otherwise return to `$gsd-path` for ownership
+checking. Legal entry is `define/done` or `research/active|blocked`. On
+`define/done`, enter with `pipeline_state.py transition`, expected phase/status
+`define/done`, exact branch and archive values, event `research started`, and
+set phase/status `research/active` (plus the same `--project-dir` in
+lookahead); never edit STATE directly. `research/done`
+`research/done` or any later phase blocks rather than replacing settled
+evidence beneath downstream artifacts. When an active router supplies the
+lookahead track root `.project/next/`, evaluate these preconditions against
+the track instead; see Lookahead mode. Require
+`.project/intent/INTENT.md` — or, in program flow, `.project/CHARTER.md` when
+the router dispatched program-scope research before any milestone INTENT
+exists. If neither exists, stop and route to
+`$gsd-path-define`. Confirm live search or web-reading capability before
+dispatch; if unavailable, block rather than allowing memory-based citations.
+
+Program scope: when working from CHARTER.md, dimensions decompose the full
+charter scope, not one milestone. Add program dimensions such as
+`domain-decomposition` (capability areas and their boundaries) and
+`capability-map` (what exists vs. what must be built) as custom dimensions
+alongside the standard set, so the roadmap phase inherits a complete scope
+map. The manifest's `Intent:` line names `.project/CHARTER.md` in this flow.
+
+## Lookahead mode
+
+Entered only when an active router supplies the lookahead track root
+`.project/next/` while the active STATE.md is `build/active` in program
+flow. Evaluate every state and artifact precondition against the track:
+`.project/next/STATE.md` is the state file, INTENT.md is
+`.project/next/intent/INTENT.md`, and the manifest and evidence files live
+under `.project/next/research/`. Program-level inputs (CHARTER.md,
+ROADMAP.md, top-level SYNTHESIS.md) are read from their active `.project/`
+paths. Brownfield input is the track's
+`.project/next/research/evidence-codebase.md` after lookahead inspect;
+do not substitute the building milestone's map. Archived evidence from
+earlier milestones uses the same archived-manifest rule as the roadmap
+phase. Validate the handoff with
+`python3 <absolute check_handoffs.py> research --repo <absolute repo root>
+--project-dir .project/next`. Dispatch, gates, and completion rules are
+unchanged; never write an active-path artifact.
+
+## Dispatch contract
+
+Read the local [researcher role](references/researcher.md), then follow the
+local [runtime dispatch contract](references/dispatch.md). Resolve the local
+[evidence template](templates/evidence.md), research-handoff template
+(`templates/research-handoff.md`), and `scripts/check_handoffs.py` to absolute
+paths. Include the role, `AGENTS.md`, `WORKFLOW.md`, INTENT.md, manifest,
+dimension, assigned questions, deterministic logical task name
+`research_<dimension>`, and exact output path in every brief. When
+`evidence-codebase.md` exists, include its absolute path in every brief as
+settled brownfield input.
+
+## Process
+
+1. Read INTENT.md — or CHARTER.md in program flow. Extract constraints,
+   vetoes, risks, and `RESEARCH`
+   questions. Create `.project/research/RESEARCH.md` from the local handoff
+   template before dispatch. Record every standard dimension exactly once as
+   `dispatched` or `skipped` with a reason, and assign every research question
+   to at least one dispatched dimension. No question may remain unassigned.
+2. Decide which standard dimensions have work: dispatch a dimension only when
+   it has at least one assigned `RESEARCH` question from INTENT.md or
+   CHARTER.md. Unsettled choices and risks need that source question before
+   dispatch. Skip a dimension
+   with nothing to answer — never spawn a researcher to fill a file — and
+   record every skipped dimension with its reason in `RESEARCH.md`. The
+   standard dimensions:
+
+   | Dimension | Output file | Focus |
+   | --- | --- | --- |
+   | domain | `evidence-domain.md` | prior art, domain rules, terminology, practitioner expectations |
+   | stack | `evidence-stack.md` | two or three viable stacks against the constraints |
+   | pitfalls | `evidence-pitfalls.md` | security, scale, reliability, and UX failure modes |
+   | similar | `evidence-similar.md` | comparable products and reusable lessons |
+
+   Dispatch up to the available child capacity, then dispatch each remaining
+   dimension when a slot opens. A pending corrected redispatch takes the slot
+   before any queued not-yet-dispatched dimension. Keep all briefs independent.
+   A custom fifth dimension supplements at least one dispatched standard
+   dimension; it never replaces the standard set.
+
+   In brownfield work, require stack research to weigh migration cost and
+   pitfalls research to check which failure modes already exist in the mapped
+   codebase.
+
+3. If a risk needs a distinct dimension, add one researcher, up to five total
+   (project policy).
+   Derive its filename deterministically as `evidence-<dimension-slug>.md`:
+   lowercase the label, replace non-alphanumeric runs with one hyphen, and
+   trim hyphens. Append `-2` only if it collides with an existing dimension.
+4. Validate each dispatched evidence file as its researcher returns. Require
+   at least one `## Finding` — a documented `no reliable source found` null
+   result recorded as a finding satisfies this gate, with the searches that
+   came up empty noted as its evidence — require Claim, Source, Confidence,
+   and Why it matters fields for every finding, and require an answer for
+   every question assigned to that dimension. For a missing or invalid file,
+   redispatch one complete corrected brief under the same logical task name,
+   following the runtime dispatch contract, as soon as a child slot allows —
+   never held until the remaining dimensions settle.
+5. After every dimension settles — validated, or its one corrected
+   redispatch collected — confirm every extracted `RESEARCH` question was
+   assigned to a dispatched dimension. Then run:
+
+   `python3 <absolute check_handoffs.py> research --repo <absolute repo root>`
+
+   The manifest is the source of truth for dispatched and skipped dimensions;
+   the STATE log records only a human-readable summary.
+   If any expected file still fails after its one corrected redispatch,
+   run `pipeline_state.py transition` with
+   expected `research/active`, exact branch and archive values,
+   `--set-status blocked`, and an event listing the failed evidence gate; then
+   present **Outcome** with the
+   failed gate, **Review** linking RESEARCH.md or STATE.md when the manifest is
+   missing, and **Next** naming the one correction or user decision required.
+   Stop; never advance with partial research.
+6. When all dispatched files and `RESEARCH.md` pass, run
+   `pipeline_state.py transition` with expected `research/active`, exact
+   branch and archive values, `--set-phase research --set-status done`, and
+   an event naming the manifest path, dispatched dimensions, skipped
+   dimensions, and question count. Include `--project-dir .project/next` for
+   lookahead. Require the returned state to be `research/done`. Report the
+   outcome, link the resolved absolute `RESEARCH.md` path,
+   summarize the dispatched evidence files, and name the decide phase as next.
+   The decide phase reads the manifest; it must not infer dispatch state from
+   a glob or free-form log. When routed by an active
+   `$gsd-path`, return control to that router. When invoked directly, stop and
+   tell the user to explicitly invoke `$gsd-path`, which routes to decide; do
+   not invoke an explicit-only sibling skill yourself.
+
+## Rules
+
+- Require evidence, not opinion: every claim needs a source actually checked
+  and a one-line tie-back to this project's intent.
+- Record conflicting sources rather than resolving them here.
+- Preserve dead ends and explicit `no reliable source found` answers.
+- Do not summarize the evidence; `$gsd-path-decide` owns that work.

package/skills/gsd-path/ROADMAP.md

@@ -0,0 +1,215 @@
+---
+name: gsd-path-roadmap
+description: Slice an approved GSD Path program charter into a dependency-ordered roadmap of independently shippable milestones. Use only when the user explicitly invokes $gsd-path-roadmap or an active $gsd-path router explicitly routes to this phase.
+---
+
+# 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](templates/roadmap.md) and resolve it to an
+   absolute path.
+2. Read the local [roadmapper role](references/roadmapper.md), then follow the
+   local [runtime dispatch contract](references/dispatch.md) 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 in an established repository, record the exact full current
+   HEAD before changing ROADMAP.md or STATE.md. For a milestone-boundary
+   re-slice, keep its matching roadmap entry `active`, use `pipeline_state.py
+   transition` to record `program roadmap re-slice approved` while expecting
+   and retaining the complete entering `inspect/active` or `define/active`
+   state, then checkpoint the pending `.project/` artifacts with:
+
+   ```text
+   python3 <absolute isolation.py> checkpoint \
+     --repo <absolute root> --expected-head <recorded full HEAD> \
+     --subject "roadmap: program roadmap approved" \
+     --body "Why: approved roadmap checkpoint" \
+     --allow-path .project
+   ```
+
+   On a post-abandon re-slice, mark only the helper-selected pending entry
+   `active`, use `pipeline_state.py transition` with the complete current
+   `roadmap/active` state as expected to set `phase: inspect`, `status: active`,
+   `milestone` to the selected slug, preserve the bound branch, and set
+   `archive: null`, with an event naming the abandoned predecessor. Then use
+   the same `isolation.py checkpoint` command above. For a first roadmap
+   approval, run:
+
+   ```text
+   python3 <absolute pipeline_state.py> approve \
+     --repo <absolute root> --kind roadmap \
+     --milestone <selected first pending slug> \
+     --expected-head <recorded full HEAD>
+   ```
+
+   The helper journals before mutation, proves the selected entry is pending
+   and no entry is already active, marks it active, changes STATE from
+   `roadmap/active` to `roadmap/done` with that milestone and event `program
+   roadmap approved`, and checkpoints all pending `.project/` artifacts with
+   the canonical roadmap subject and body, subject to the
+   top-level allowlist in
+   [isolation.PROJECT_ENTRIES](scripts/isolation.py). Require its typed result to report
+   `schema: gsd-path/state-checkpoint/v1`, `status: approved`, `kind: roadmap`,
+   `project_dir: .project`, `state.status: done`, the selected milestone, and
+   the returned current commit. Rerun the same command after interruption; the
+   matching journal owns recovery.
+
+   For every re-slice, remove `.project/ROADMAP.before-reslice.md` only after
+   the state transition succeeds and before the checkpoint. Retain it through
+   every requested revision and failed approval attempt.
+
+   Defer either checkpoint only when the directory is not yet a Git repository
+   or `.project/REPOSITORY.md` records `Kind: new-github`. For a normal
+   approval, run the same `approve` command with `--defer-checkpoint` instead
+   of `--expected-head`; it marks the selected entry active and records
+   `roadmap/done` with event `program roadmap approved`. `pipeline_state.py
+   transition` never approves a roadmap. For
+   a milestone-boundary re-slice, use the retaining transition above; for a
+   post-abandon re-slice, use its transition above. The build transition
+   commit owns the pending artifacts. Confirm approval and link ROADMAP.md again. For
+   a milestone-boundary re-slice, state that the preserved inspect or define
+   phase resumes; for a post-abandon re-slice, state that inspect is next;
+   otherwise state that define (milestone mode) is next. Do not
+   add another approval gate. When routed by an active `$gsd-path`, return
+   control to that router so it routes the resulting state; never name define
+   as next when inspect was preserved or selected. When invoked directly, stop
+   and tell the user to explicitly invoke `$gsd-path`, which routes the same
+   result; do not invoke an explicit-only sibling skill yourself.
+
+## 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.