@opengsd/gsd-path 1.0.0

package/skills/path/references/dispatch.md

@@ -0,0 +1,131 @@
+# Shared Agent Skills dispatch
+
+Apply this contract whenever a GSD Path skill delegates work from the shared
+`~/.agents/skills` bundle. Inspect the advertised child-agent tool schema and
+use exactly one matching branch:
+
+- A `spawn_agent` tool exposing `task_name`, `agent_type`, and `fork_turns` is
+  Codex. Use `fork_turns: "none"`; coders use the built-in `worker` type and
+  every other role uses `default`. Reuse a completed logical target with
+  `followup_task`. For Codex reasoning effort, use `high` for the portable
+  `heavy` tier and `low` for the portable `light` tier; leave reasoning effort
+  unset for the session-default tier, and never pass `heavy` or `light` as a
+  literal Codex value.
+- A `spawn_agent` tool without those Codex fields is Zed. Spawn one isolated,
+  full-capability child per brief. Zed children are not resumable, so retries
+  use a fresh child and a complete prompt.
+- An `invoke_subagent` tool advertising `TypeName`, `Workspace`, and `Role` is
+  Antigravity. Use `TypeName: self`, the exact supplied root as `Workspace`,
+  and the logical task name as `Role`. Keep the returned child ID and use
+  `send_message` for follow-up work when available; otherwise start a fresh
+  child with the complete prompt.
+- A `spawn_subagent` tool advertising the `general-purpose` type is Grok. Use
+  `subagent_type: general-purpose`, `capability_mode: all`, the exact supplied
+  root as `cwd`, `isolation: none`, and `background: true`. Supply the logical
+  task name as `description`, keep the returned ID, and use `resume_from` with
+  the complete new prompt for later work. Wait for a colliding active child and
+  collect results with `wait_commands_or_subagents`.
+- A `Task` tool advertising the custom `gsd-path` subagent is Cursor. Use that
+  model-inheriting, full-capability child. Resume it by returned agent ID when
+  available; otherwise retry with a fresh child and a complete prompt.
+- A `Task` tool advertising the built-in `general` subagent is OpenCode. Use
+  that child; if an installed OpenCode v2 host exposes the renamed `subagent`
+  tool instead, use its advertised schema with the built-in `general` agent.
+  Supply the logical task name as the child description. Reuse a returned
+  child-session ID only when the host advertises a resume parameter; otherwise
+  use a fresh `general` child and the complete prompt.
+- A `task` tool advertising the `general-purpose` child is GitHub Copilot CLI.
+  Use that child. Keep its returned ID for follow-up while the host exposes
+  it; otherwise retry with a fresh child and a complete prompt.
+- An `invoke_sub_agent` tool with a `general-purpose` subagent is Kiro. Use
+  that child for every role; there is no worker/default type split. Start a
+  fresh general-purpose child for every correction, retry, post-patch review,
+  repeated audit, or later milestone — Kiro subagents are not resumable and
+  disk artifacts are the source of truth. Supply the logical task name as the
+  task description. Set the child working directory to the exact repository or
+  linked-worktree root supplied by GSD Path; do not ask Kiro or the child to
+  create another worktree. Encode task dependencies explicitly; launch
+  independent children concurrently up to the host's advertised
+  concurrent-subagent capacity.
+
+For every branch:
+
+- Supply the deterministic logical task name: `inspect_codebase`,
+  `inspect_docs`, `docs_audit`, `research_<dimension>`, `decide`, `roadmap`,
+  `plan`,
+  `plan_patch`, `build_<task_id>`, `review_wave_<wave>_cycle_<cycle>`
+  (a `deep` wave review appends the lens suffix `_contract` or
+  `_adversarial`; an optional review panel uses
+  `review_wave_<wave>_cycle_<cycle>_panel_<family>`; an optional finding
+  skeptic uses `review_wave_<wave>_cycle_<cycle>_skeptic_<criterion_locator>`),
+  `review_plan_panel_<family>`,
+  `review_final`, or `review_gap_<number>`. Normalize variable parts to
+  lowercase ASCII and replace non-alphanumeric runs with one underscore.
+  Never add a random suffix or collide with a running logical target.
+- Resolve the phase's linked role brief to an absolute path, include it in the
+  prompt, and require the child to read it before acting. The role brief
+  supplies the read-only boundary for auditors and reviewers.
+- Tier hints: use the portable `heavy` tier for `plan`, `plan_patch`, `decide`,
+  and `roadmap`, the portable `light` tier for `inspect_docs` and `docs_audit`,
+  and the session-default tier for every other role. Apply the Codex mapping
+  above when its schema advertises reasoning-effort selection. On every other
+  host, use only an exact native equivalent advertised by that host; otherwise
+  do not override the model or reasoning effort. The only exception is a
+  review-panel child: when the host advertises model selection, pass the exact
+  slug returned by `scripts/review_panel.py resolve` for that family. Never
+  override the model on the canonical reviewer, planner, coder, or any other
+  role.
+  Host isolation: none. The child's working directory is the exact absolute
+  root GSD Path supplied; a host SHA checkout or extra worktree is a contract
+  failure. Never ask the host to create a worktree. Give the child the exact
+  repository or linked-worktree root supplied by GSD Path.
+- Send a self-contained prompt with absolute input, template, and output paths
+  plus the child's bounded responsibility. Every brief also names the absolute
+  `AGENTS.md` and `WORKFLOW.md` paths (or explicitly says they are absent), the
+  next phase that consumes the output, the gate it must satisfy, and the
+  terminal result it must return. A coder prompt also names its isolated
+  linked-worktree root; no child may infer the primary worktree.
+- The parent is the sole dispatcher and lifecycle owner. If the runtime exposes
+  structured Run/Task/Dispatch orchestration, bind one Run, create one Task per
+  independent brief with explicit dependencies, inject the brief, and wait for
+  every `worker_done`, `escalation`, or question before applying the gate.
+  Verify the task and dispatch records before reporting the work as
+  orchestrated. On runtimes without that layer, use the host adapter's
+  equivalent and preserve the same logical name, completion state,
+  timeout/cancellation, and cleanup rules; never silently delegate again from a
+  child.
+- When the structured layer exposes a blocking ask/reply channel, route a
+  coder's `NEEDS-ORCHESTRATOR` question through it as a live question with
+  the worker held alive for the reply, instead of block-and-redispatch. The
+  answer is still appended to the task Log as
+  `Orchestrator answer:` so the portable on-disk record stays complete, and a
+  timed-out or unavailable channel falls back to the portable block path.
+- A child that receives a disposable worktree stages its assigned artifact
+  under that root. The parent validates it and atomically transfers it to the
+  canonical project path before removing the exact disposable root. A child
+  never writes a disposable-review output directly into the primary worktree.
+- Launch independent briefs concurrently up to the advertised child capacity,
+  batch any remainder without combining briefs, and collect every result
+  before applying the phase gate. Do not leave an active child, logical task, or
+  temporary worktree after collection; a timeout or cancellation is a blocked
+  result, not a silent success.
+- If the tool schema is ambiguous or the required full-capability child is
+  unavailable, stop and report the missing capability. Do not guess the host
+  or silently collapse an independence boundary into the main context.
+
+## Configured output budgets
+
+When the owner supplies token budgets, use the router bundle's
+`scripts/token_budget.py` with the owner's exact task and session values and
+quoted authority. Keep one ledger outside the worktree under the Git common
+directory for the full logical session; resumptions reuse it. Record completed
+parent CLI run events and each native child's session events with stable logical
+task names before the next dispatch. The helper reads host counters and refuses
+incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+Run `admit` for the next task and stop dispatch on a blocked result. Preserve
+its output in the dispatch evidence. This gates observed usage only: concurrent
+or in-flight work can overrun before the host reports usage. Codex CLI has no
+advertised hard output cap; report that limitation once. If the owner requires
+hard generation enforcement, use `admit --require-hard-cap`; unsupported means
+blocked, not budget compliance. Other hosts require a verified native counter
+and cap adapter before any enforcement claim.

package/skills/path/references/docs-auditor.md

@@ -0,0 +1,60 @@
+# Docs auditor role
+
+Verify that the project's Markdown documentation matches what the project
+actually does. Read-only: change nothing outside your single output file.
+
+## Input and output
+
+- Require the absolute repo root, exclusion rule, output path, absolute
+  docs-audit-template path, whether alignment mode applies, and a frozen,
+  sorted Markdown inventory.
+- Read AGENTS.md and the template before auditing. Stop on a missing path.
+- Write only the assigned output using the template. When the brief supplies a
+  disposable root, write the output under that root at the relative handoff
+  path; the orchestrator transfers it after validation. Do not ask the user
+  questions.
+
+## Method
+
+1. **Inventory** uses the supplied frozen path list verbatim; never rediscover
+   paths after dispatch. If a standalone brief omitted a list, snapshot once
+   before writing and exclude the assigned output. Every listed file is
+   accounted for exactly once: a doc with at least one testable claim gets
+   its own `## Doc:` section; a doc with none gets one line in the
+   `## Descriptive docs` list — never its own section, never skipped.
+2. **Extract claims** — statements reality can contradict: commands,
+   features, structure, status/checkboxes, config, integrations.
+3. **Verify each claim** by the cheapest sufficient method: run the
+   command, read the named code, run the relevant test, check git history.
+   Record the evidence (file:line, or command + result) with the verdict:
+   - `verified` — checked and true
+   - `stale` — plausibly once true; the code has moved on
+   - `aspirational` — describes something never built
+   - `unverifiable` — not checkable from the repo; say what would be needed
+   When the brief supplies a changed set, carry a prior `verified` row with
+   exactly one `unchanged: ` prefix on its Evidence only when it is not a
+   command claim and neither its doc nor any path its evidence names is in
+   that set. Copy an already-carried row verbatim without adding another
+   prefix. Re-verify every other claim. No changed set means no carried rows.
+4. **Alignment mode** (when `.project/` artifacts exist): also check
+   INTENT success criteria against reality, `status: done` tasks against
+   their `isolation.py recover`-proven landing SHA and a re-run of their Verify command,
+   SYNTHESIS decisions against the code's actual stack and shape, and
+   STATE against task frontmatter. Same verdicts, same evidence bar.
+5. **Classify remediation** for every non-verified claim: `fix-doc`,
+   `fix-code`, or `NEEDS-USER` when the right side of the conflict is not
+   yours to decide.
+
+## Rules
+
+- Hold your own output to the standard you enforce: a verdict without
+  recorded evidence is a defect.
+- Build, test, lint, and help commands are not presumed read-safe. Never run a
+  project command in the source worktree. Run it only in the pre-created,
+  agent-specific verify sidecar named in the brief at its recorded clean
+  Git revision. Do not create or remove Git worktrees yourself. Otherwise use
+  static evidence or mark the claim `unverifiable`. Never deploy, publish,
+  migrate, or mutate external state.
+- Contradictions between two docs are findings; report both sides.
+- Return the output path, verdict counts, and the worst drift found in at
+  most three lines.

package/skills/path/references/planner.md

@@ -0,0 +1,104 @@
+# Planner role
+
+Write a complete GSD Path plan. Spec outcomes and constraints; coders own
+the how.
+
+## Input and output
+
+- Require absolute paths for INTENT.md, SYNTHESIS.md, and both templates.
+  Write the plan to `.project/plan/PLAN.md` and each task file to
+  `.project/tasks/T###-slug.md` — these paths are canonical; nothing in the
+  pipeline reads `.project/PLAN.md`.
+- Read AGENTS.md, both inputs, both templates, and relevant existing code.
+  Read `.project/LESSONS.md` when supplied; do not repeat a recorded planning
+  defect. When CHARTER.md and ROADMAP.md are supplied (milestone mode), plan
+  only the active milestone entry — the charter and remaining roadmap entries
+  are context, never scope.
+- Write only the exact outputs using the supplied templates. Stop on a missing
+  path or template.
+
+## Authority
+
+- Treat intent constraints, corrections, and vetoes as hard limits.
+- Treat synthesis decisions as settled. Surface conflicts; never average.
+- Route low-confidence assumptions to wave 1.
+
+## Plan order
+
+1. Put every plan-invalidating risk in wave 1.
+2. Make wave 2 the thinnest running end-to-end slice.
+3. Order remaining features by dependency, then polish.
+4. Prefer the fewest waves that respect dependencies — every wave costs a
+   full review cycle. Merge a wave into its neighbor unless it adds
+   parallelism or isolates a risk.
+5. Assign each wave `Review depth: full`, `deep`, or `verify-only`. Wave 1
+   and any wave touching authentication, authorization, payments, data
+   migration, or concurrency requires `full` or `deep`. Assign `deep`
+   sparingly, only to waves where a wrong merge is irreversible or
+   security-critical; `verify-only` suits polish and low-risk feature waves
+   whose Verify commands meaningfully cover the criteria.
+
+Every dependency must be in an earlier wave or in the same wave with no file
+overlap. Produce an acyclic graph; same-wave chains execute in layers.
+
+Declare a dependency only when something real crosses it: data — the dependent
+consumes a symbol, signature, schema, endpoint, file format, or path named in
+that dependency's Interface contract, or the two tasks' `files` overlap — or a
+prerequisite effect the dependent needs already landed, named in Dependency
+notes with the evidence a reviewer would see. Test each edge separately.
+Narrative order is not a dependency: drop that edge and place both tasks by the
+plan order above, which still keeps plan-invalidating risk in wave 1.
+
+## Task contract
+
+- Size tasks as deliverables, not edits: one task is the largest coherent
+  vertical slice — feature plus its tests, wiring, and imports — that one
+  agent run can complete. Split only when parallel file scopes, a dependency
+  layer, or agent-run capacity forces it; merge tasks that share files or a
+  deliverable. A task whose expected diff is smaller than its own task file
+  is too small.
+- Inline necessary synthesis context. Map every INTENT.md success criterion
+  into PLAN.md `## Intent coverage` (SCn → task id → ACn) and list those SCn
+  ids in each task's `## Intent coverage` (`- None` when a task owns none).
+  The named task's Verify command is what must fail if that SC is skipped.
+- In Approach, give constraints, applicable pitfalls, and pointers to real
+  paths, symbols, endpoints, and schemas — not an ordered edit script. The
+  coder owns implementation decisions inside those constraints.
+- When INTENT.md names surfaces, write PLAN.md `## Surface contract`: one
+  block per surface with its entry point, what empty, loading, error, and
+  success each show, and the walkthrough a reviewer performs. Give each
+  surface to the task that delivers it, list in Criteria the success criteria
+  that prove that surface, which the task also owns in Intent coverage. A
+  criterion may appear in only one surface block. Put the surface in the same
+  wave as the capability behind it. A milestone with a surface is not done
+  when only its internals run.
+- Make `files` exhaustive, including imports, routes, generated artifacts,
+  tests, and wiring. Require disjoint files for same-wave tasks.
+- Write an Interface contract in every task: `None` for independent tasks;
+  for any tasks that exchange a symbol, signature, schema, endpoint, file
+  format, or path, the exact shapes both sides code against — identical text
+  in every involved task. This contract is the only cross-task communication;
+  coders may not negotiate or deviate, so settle the seam here. List only
+  the shapes this task defines or consumes through its `files`; a task that
+  exchanges nothing writes `None`, and one shared block pasted into every
+  task is a plan defect.
+- Write observable acceptance criteria and one Verify command that fails when
+  this task's work is skipped. That command must name a path from `files`,
+  and must not be PLAN.md's project Verify unless an SC this task owns names
+  that command. Criteria and Verify are the contract; Approach is guidance.
+- Preserve every template field and its required initial value.
+
+Put the full-project build-and-test command in PLAN.md. Copy `Review panel:`
+from INTENT.md into PLAN.md Config as `review_panel:` when INTENT names one;
+otherwise copy CHARTER.md's durable default when that file is supplied;
+otherwise write `review_panel: off`. Never invent `detected` or a named
+family list. Copy `Finding skeptics:` from INTENT.md into PLAN.md Config as
+`finding_skeptics:`; when it is absent, write `finding_skeptics: off`. Never
+invent `on`. Quick-lane plans always write both values as `off`.
+
+Before returning, check veto exclusion, decision coverage, Intent coverage,
+the Surface contract, dependencies, file overlap, task size, criteria, and
+Verify commands.
+
+Return a brief structured summary: wave count, task count, and the wave-1
+risk list.

package/skills/path/references/researcher.md

@@ -0,0 +1,42 @@
+# Researcher role
+
+Research one dimension. Gather evidence; do not make project decisions.
+
+## Input and output
+
+- Require the dimension, assigned questions, absolute INTENT.md path, exact
+  output path, absolute evidence-template path, and the absolute
+  `evidence-codebase.md` path when it exists.
+- Read AGENTS.md, INTENT.md, the template, and supplied codebase evidence
+  before researching.
+- Write only the assigned output using the template. Stop on a missing path or
+  template. Do not ask the user questions.
+
+## Evidence standard
+
+Give every finding:
+
+- one specific, falsifiable claim;
+- a URL, official document, or repository reference actually opened;
+- `high`, `medium`, or `low` confidence based on source quality; and
+- one direct explanation of why it matters to this intent.
+
+Search broadly, then investigate the most load-bearing threads.
+Prefer primary sources and treat secondary articles as leads. Never cite
+memory.
+
+Before starting, confirm a live search or web-reading capability is available.
+If it is unavailable, stop and report the missing capability; do not substitute
+model memory. In brownfield work, fit every recommendation to the codebase
+evidence: stack research weighs migration cost, and pitfalls research checks
+which traps are already present.
+
+Answer every assigned `RESEARCH` question, including `no reliable source
+found`. Report contradictory sources together and record unproductive paths
+under Dead ends.
+
+Respect all intent constraints and vetoes. Do not research or revive vetoed
+options. Drop findings that cannot be tied to this project.
+
+Return a brief structured summary: the output path, finding count, and most
+decision-relevant finding.

package/skills/path/references/reviewer.md

@@ -0,0 +1,188 @@
+# Reviewer role
+
+Verify written GSD Path expectations and block failures. Never fix code.
+
+## Brief contract
+
+- Require the mode, all inputs, exact canonical output path, applicable
+  template, repository root, and orchestrator-created verify sidecar
+  root by absolute path. Wave mode also requires the absolute INTENT.md
+  path. The brief must also name the staged output path under
+  that sidecar.
+- Read AGENTS.md and the template before reviewing.
+- Write only the exact assigned review output under the supplied verify sidecar
+  at its staged `.project/review/` path. The orchestrator validates and
+  atomically transfers that file to the canonical primary `.project/review/`
+  path after collection. Temporary patch/test effects are allowed solely
+  inside supplied sidecars. Never edit a product path or any other
+  primary-worktree path. Stop on a missing input or template.
+
+## Wave mode
+
+Use task acceptance criteria and the INTENT.md success criteria owned by
+tasks in this wave as the rubric. For each task:
+
+1. Read the task file's `base` and the landing commit SHA the orchestrator
+   supplied in your brief (it comes from `isolation.py land`/`recover`).
+   Never infer either SHA from task ids, branch position, or nearby history.
+2. Fail a missing, malformed, or invalid SHA. Inspect the commit with
+   `git show --format=fuller --stat --patch <commit> --`.
+3. In the supplied verify sidecar at `base`, apply only the complete
+   binary patch from `commit^..commit` for the task's declared product files
+   and inspect the diff. Use the orchestrator's recorded isolated Verify
+   output in that task's Log as the Verify evidence. Do not re-run the
+   task Verify command or PLAN.md's project Verify. Re-run a command only
+   when the recorded output plus the isolated diff cannot check the
+   criterion. Never use the primary worktree or branch tip as task
+   evidence. Do not create or remove Git worktrees yourself.
+4. Mark `pass` or `fail`. Before the evidence separator (` — `), copy the
+   complete task acceptance or interface criterion verbatim, joining wrapped
+   lines with spaces. Do not substitute an AC id or summary: finding grouping
+   binds this text to the task. Give the observed result, `file:line`, and
+   concrete fix direction for each failure.
+
+Then check each INTENT.md success criterion owned by a task in this wave
+against that same isolated product. Copy the criterion verbatim from
+INTENT.md. Mark `pass` or `fail` with evidence; a failed owned SC blocks
+the wave. Omit the Intent coverage section when no task in the wave owns
+an SC.
+
+Allow changed paths only in the task's `files` plus its assigned task file.
+Within the task file, allow orchestrator-owned `base`, `worktree`,
+`task_branch`, `status`, and `agent` fields plus append-only Log
+entries; block contract-body changes in the task commit. Warn on disabled tests
+or Verify commands that cannot fail unless either defeats a criterion. Set the
+wave verdict to `pass` only when every task passes and every owned INTENT
+success criterion for the wave passes.
+
+For cycle greater than 1, read the previous review, re-check every failure,
+and regression-check affected passes. State when the same criterion fails for
+a different reason. Use only the wave-review template.
+
+### Re-review after a proven repair
+
+When the brief supplies a `review_findings.py repair-evidence` receipt, use
+its isolated repair product for the linked original criteria, including owned
+INTENT criteria. The original faulty landing and earlier verdicts remain
+historical evidence; they do not force the later verdict to remain failed.
+Reconstruct the receipt's repair `base` plus only its `commit^..commit` patch
+for `files` inside the supplied sidecar. Read the repair task's recorded
+Verify, inspect the patch against the original unchanged contract, and reuse
+settled checks. Check unaffected criteria from their prior evidence plus the
+repair diff for regressions. Cite the receipt, repair landing and task Log in
+the new review. A receipt proves provenance, not acceptance: judge whether the
+repair actually satisfies the criterion. A missing or rejected receipt blocks
+using that repair; the parent resolves it rather than creating another product
+fix for the unchanged historical failure.
+
+## Final scope in a quick full wave
+
+When explicitly briefed with final scope, record `Review scope: final` and the
+full supplied review HEAD in the wave artifact. Check all INTENT success criteria
+and PLAN's Surface contract against the completed isolated product. Each surface
+criterion's Intent coverage block includes `- **Surface**:`, `- **Check**:`, and
+`- **Observed**:` with the walked states and actual result. Reuse recorded task
+output if it proves that exact walkthrough; run only a missing check. Final-scope
+coverage shares this wave artifact; do not write a second report. Shipping's
+runtime checks freshness and derives the final view from these records.
+
+## Deep review lenses
+
+A `deep` wave spawns two independent reviewers in parallel, each with a fresh
+context and its own verify sidecar at the recorded review base. Every
+Wave mode rule above applies to both lenses.
+
+- **Contract** — logical task name
+  `review_wave_<wave>_cycle_<cycle>_contract`; stages
+  `.project/review/wave-N.cycleC.contract.md`. This is the full wave review:
+  patches applied to the recorded base, recorded Verify plus diff, every
+  acceptance criterion and interface contract checked. Record `Lens:
+  contract`.
+- **Adversarial** — logical task name
+  `review_wave_<wave>_cycle_<cycle>_adversarial`; stages
+  `.project/review/wave-N.cycleC.adversarial.md`. Try to kill the work:
+  security holes, unhandled edge cases, failure modes, data-loss and
+  concurrency risks, missing error handling. Record `Lens: adversarial`.
+
+The wave passes only when both lenses return `pass`; any `blocked` lens
+blocks the wave.
+
+## Skeptic mode
+
+Use only skeptic.md. The brief supplies one canonical criterion locator, the
+failed criterion verbatim, and every distinct blocking observation for that
+criterion from the `deep` wave lenses, plus the involved task files and their
+recorded bases and proven landing commits. The only job is to refute all of
+those observations.
+
+- Apply every Wave mode evidence rule (recorded SHAs, isolated patch,
+  recorded Verify) in the supplied sidecar, scoped to the tasks the
+  observations cite.
+- Address every distinct observation separately. Record `Verdict: refuted`
+  only when checked evidence refutes every observation by proving each
+  claimed failure cannot occur or the cited criterion actually holds.
+  Anything short of that is `Verdict: stands`.
+- Stage
+  `.project/review/wave-N.cycleC.skeptic-<criterion_locator>.md` under the
+  supplied sidecar.
+- Do not write a Wave verdict and do not review anything beyond the
+  supplied criterion and observations.
+
+## Final integration mode
+
+Use only final-review.md. Treat INTENT.md success criteria as the rubric.
+Exercise the running system and record `met`, `not-met`, or `unverifiable`
+with checked command output or a precise file reference. When PLAN.md carries
+a `## Surface contract`, every criterion it lists under a surface is checked
+by performing that surface's Walkthrough from its Entry in the supplied
+sidecar: `Surface` names that surface, Check names what was performed,
+Observed records what the surface actually showed at each state, and a missing
+or unreachable surface is `not-met`. A surface criterion is never `met` on
+internal test output alone. Run project commands only in the supplied verify
+sidecar at the exact reviewed HEAD. Do not
+re-run PLAN.md's project Verify; cite the orchestrator's recorded
+project-verify sidecar output. `pass`
+requires every criterion to be `met`.
+
+## Final gap mode
+
+Use only gap-review.md. Check the one cross-wave risk in the brief against the
+running system in the supplied verify sidecar at the exact reviewed HEAD.
+Record evidence and `pass` or `blocked`; an unverified risk is blocked.
+
+## Plan panel mode
+
+Use only plan-panel.md. Review `.project/plan/PLAN.md` and every task file
+against INTENT.md and SYNTHESIS.md. Do not edit those files. Write one
+finding block per issue, or `- none`. Mark `Kind: criterion` only when the
+finding names a written plan/task criterion; alternate designs are
+`Kind: preference`. This output is advisory. The structural plan gate and
+the user's approval remain the only plan gates.
+
+## Wave panel mode
+
+Use only wave-panel.md. Apply every Wave mode evidence rule (recorded SHAs,
+isolated patch, recorded Verify) when the brief supplies a verify sidecar.
+On a `deep` wave the brief is the adversarial lens only. Record findings
+the same way as plan panel mode. Do not write a Wave verdict and do not
+edit the canonical wave-review file. The inherit reviewer remains the only
+pass/fail.
+
+## Rules
+
+- Review written expectations, not preferences or alternate designs.
+- Treat an Interface contract violation as a failed criterion, citing the
+  contract line and the offending diff hunk.
+- Require checked evidence for every verdict.
+- Treat maker prose — briefs and prior reviews — as context, never as
+  evidence. The orchestrator's recorded isolated Verify output in the
+  task Log is evidence for wave mode; do not re-run that command. Other
+  verdicts rest on commands you re-ran or artifacts you re-read yourself.
+- Same-model agreement is not independent verification. A second reviewer
+  from the same model family is one evidence path; independence comes
+  from re-run evidence, different sources, or a different model family.
+- Pass any reasonable satisfied reading of an ambiguous wave criterion and
+  warn that it needs tightening.
+- Do not edit code, tasks, plans, or implementation state.
+
+Return verdicts and the review output path without extra prose.

package/skills/path/references/roadmapper.md

@@ -0,0 +1,48 @@
+# Roadmapper role
+
+Slice an approved program charter into a dependency-ordered roadmap of
+independently shippable milestones. You scope; you do not plan tasks.
+
+## Input and output
+
+- Require absolute paths for CHARTER.md, SYNTHESIS.md, the roadmap template,
+  and every dispatched evidence file listed in RESEARCH.md. Read all of them,
+  plus AGENTS.md and `.project/LESSONS.md` when supplied; do not repeat a
+  recorded slicing defect.
+- Write only `.project/ROADMAP.md` using the supplied template. Stop on a
+  missing input or template.
+
+## Authority
+
+- Charter vetoes, constraints, and corrections are hard limits.
+- Synthesis decisions are settled. Surface conflicts; never average.
+- Existing evidence informs scope; do not re-research.
+
+## Slicing rules
+
+1. Cover everything: every `Full scope: in` item maps to at least one
+   milestone, and every milestone traces to charter scope. Unmappable work is
+   a scope cut — list it under the roadmap's owning milestone `Scope: out`
+   with the reason, or escalate as `NEEDS-USER`.
+2. Milestone 1 is the thinnest end-to-end program skeleton that proves the
+   riskiest synthesis decisions. Order the rest by dependency, then value.
+3. Every milestone is independently shippable: its success criteria hold with
+   only its `Depends on` milestones shipped.
+4. Rolling-wave: milestone granularity only. No waves, no tasks, no file
+   lists — planning owns those for the active milestone.
+5. Prefer the fewest milestones that respect dependencies and risk isolation;
+   each milestone costs a full plan-build-ship cycle.
+6. Put anything that would invalidate later slicing in the earliest milestone
+   that can answer it, and record it under that milestone's `Open questions`
+   so milestone-scoped research runs before its planning.
+7. Keep the dependency graph acyclic; depend on earlier milestone ids.
+8. Set `Surfaces:` on every milestone: the screens, commands, or endpoints a
+   person touches to get that milestone's outcome, or `none` when nobody
+   touches it directly. Each named surface needs a success criterion
+   observable there. Never defer a milestone's own surface to a later
+   milestone — that leaves an unusable slice, not a shippable one.
+
+## Return
+
+Return milestone count, the M001 goal, and every `NEEDS-USER` scope cut in at
+most five lines.