@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-build/SKILL.md

@@ -3,7 +3,8 @@ name: gsd-path-build
 description: Execute or resume an approved GSD Path plan with isolated task worktrees, deterministic commits, and independent wave review. Use only when the user explicitly invokes $gsd-path-build or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Build Orchestrator
 
@@ -100,6 +101,11 @@ rule; never invoke an explicit-only sibling skill yourself.
 checkpoint `.project/` records uses this helper. Record the exact full HEAD
 before the first metadata change in that checkpoint, then run:
 
+Before dispatch, also checkpoint a pre-existing `.project/build/verify-ledger.jsonl`
+when it is an ignored regular file absent from HEAD, even if Git reports no
+other pending paths. The `build:` checkpoint validates and force-adds only
+that ledger; a malformed ledger blocks the checkpoint.
+
 Explicit configuration edits in `.project/config.json` and
 `.project/model-policy.json` are expected bookkeeping. Include them in the next
 normal checkpoint before a clean dispatch base; they may remain pending while

package/skills/gsd-path-build/references/build-native.md

@@ -24,6 +24,14 @@ python3 <absolute dispatch_driver.py> round --repo <absolute primary> --wave <N>
   [--child-timeout <owner seconds>]
 ```
 
+Use the absolute `dispatch_driver.py` from the active installed
+`gsd-path-build` skill when orchestrating a consuming project's build; that
+copy resolves role briefs and templates from its own skill bundle. The
+repository or npm package also supports the top-level `scripts/dispatch_driver.py`:
+when a default is not beside that script, it resolves from the shipped
+`skills/gsd-path` bundle. Explicit `--role-brief`, `--task-template`, and
+`--template` paths override those defaults and must name existing files.
+
 `round` owns the entry transition described in Preconditions and branch
 binding, checkpointed as `build: start milestone`, and sets `build/blocked`
 on a dependency deadlock or a blocked
@@ -82,9 +90,12 @@ dispatch contract and perform steps 1–5 by hand.
    - `recovered`: the task is landed (`land` already stamped `status: done`
      and `base`). Retire a still-present task worktree with `isolation.py
      retire` only when the report shows it present, clean, and on the task
-     branch. If only `task_branch` remains, finish its proven interrupted
-     retirement with `retire --branch <task_branch> --force --landed-commit
-     <commit>`; both absent is valid.
+     branch. If the checkout directory is absent and `task_branch` remains,
+     finish its proven interrupted retirement with `retire --branch
+     <task_branch> --force --landed-commit <commit>`. This also clears a stale
+     registration at that task's sidecar path after the landing proof passes;
+     a locked registration fails without deleting the branch. Both absent is
+     valid.
    - `resume`: continue from the returned `base`, `task_branch`, and worktree
      (the primary itself when no task branch exists); when the report shows
      the worktree absent, return the task to `pending` only when ownership is
@@ -133,6 +144,13 @@ dispatch contract and perform steps 1–5 by hand.
    even while unrelated tasks still run, so rerun `ready` after each landing.
    A `NEEDS-ORCHESTRATOR` block stays unselectable until its `Orchestrator
    answer` is recorded in the task Log and the task is back to `pending`.
+   An all-done wave whose latest canonical review cycle has any blocked lens
+   gates later waves: `ready` selects unfinished later tasks with a `## Review
+   findings` section that depend on it, sets `current_wave` to the earliest
+   repair wave, and adds `repair_for_wave` with the source wave. When no such
+   repair remains, `ready` returns no tasks and adds `blocked_review` (`wave`,
+   `cycle`, `waiting_waves`); a later passing canonical review cycle releases
+   the waiting waves.
    Its typed errors are the recovery rule:
    - `task-recovery-required`: for each listed failed or blocked task run
      `python3 <absolute build_state.py> reconcile --repo <absolute primary>
@@ -171,7 +189,17 @@ dispatch contract and perform steps 1–5 by hand.
    then create the retry. If retirement was interrupted after removing the
    worktree, rerun the same command; the recorded failed or blocked task and
    its exact base prove the remaining branch before deletion. Create the retry
-   from the new clean primary HEAD. After
+   from the new clean primary HEAD. A member task (`repo: <member>`) stays
+   `pending` in the coordinator; its rejected attempt lives in the member
+   sidecar. Copy the live copy's Log delta into the coordinator task file,
+   checkpoint it, then retire the sidecar with `python3 <absolute isolation.py>
+   retire-member-task --repo <absolute primary> --member <member> --task-id
+   <id> --task-file <task path> --force`. It refuses until the committed task
+   file holds that delta, and a rerun finishes an interrupted retirement. A
+   copy that fails the append-only check holds no trusted delta: record your
+   own rejection evidence in the coordinator task Log and checkpoint it, as for
+   a coordinator diff rejection; retirement then reports `copy_rejected`. The
+   next `prepare-task` creates the retry sidecar at the member bound tip. After
    resolving a recoverable `build/blocked` condition, use
    `pipeline_state.py transition` with the blocked state and bound branch as
    expected fields to set `build/active` and log the resolution. Checkpoint it
@@ -183,19 +211,21 @@ dispatch contract and perform steps 1–5 by hand.
    a later round unlocked by fresh landings records the later HEAD — and
    lint every ready task's brief with the bundled
    `scripts/check_task_briefs.py --repo <absolute repo root> --base <recorded
-   base>` and re-check Intent coverage with
+   base> --project-dir <routed project dir>` and re-check Intent coverage with
    `python3 <absolute check_handoffs.py> plan --repo <absolute repo root>`
    before creating any worktree; a lint or coverage failure is a documented plan
    defect — repair it against INTENT.md and SYNTHESIS.md, then re-establish
    the base. Then isolate each ready task with
    `python3 <absolute workflow_run.py> prepare-task --repo <absolute primary>
    --expected-head <recorded base> --task-id <id> --round-size <N>` where N is the
-   number of tasks in this dispatch round. Serial (`N=1`) returns the primary
-   worktree and `task_branch: null` — the coder works on the bound branch.
+   number of tasks in this dispatch round. For a coordinator task, serial
+   (`N=1`) returns the primary worktree and `task_branch: null` — the coder
+   works on the bound branch.
    The runner also creates a named verification sidecar at this clean base
    before dispatch. Retain both helper results in the dispatch evidence.
-   Parallel (`N>=2`) creates a named `gsd-path-task/<id>` branch and linked
-   worktree at that base; never a detached HEAD. Record dispatch through
+   For a coordinator task, parallel (`N>=2`) creates a named
+   `gsd-path-task/<id>` branch and linked worktree at that base; never a
+   detached HEAD. Record dispatch through
    `python3 <absolute isolation.py> activate-task --repo <returned worktree>
    --base <recorded base> --task-id <id> --agent build_<id> --task-file
    <exact selected task-file path> [--task-branch <returned task_branch>]`.
@@ -207,14 +237,26 @@ dispatch contract and perform steps 1–5 by hand.
    round. Do not append a dispatch Log entry: the isolated task later appends
    at that location, and two parallel appends make the cherry-pick ambiguous. Reuse a retained worktree only when
    its recorded base, branch, and task agree exactly.
+   A member task (`repo: <member>`) returns `mode: member` from
+   `prepare-task`: a member sidecar at the member bound tip, with no
+   coordinator verify sidecar. Record its dispatch with `python3 <absolute
+   isolation.py> activate-member-task --repo <absolute primary> --member
+   <member> --task-id <id> --agent build_<id> --task-file <exact task-file
+   path> --base <recorded base>`. It writes the live task copy (returned as
+   `copy`) inside the member sidecar; the coordinator task file stays
+   unchanged. Brief the coder with the member sidecar root and that live copy
+   as its task file, plus the coordinator's INTENT.md. Step 5's `finish` lands
+   it in the member and records it in the coordinator.
 
 4. **Dispatch the round.** Following the local runtime dispatch contract,
    spawn one implementation-capable child per task with deterministic logical
    task name `build_<task_id>`.
    Its brief contains the absolute isolated-worktree root, coder role, task
-   file, task template, and the absolute INTENT.md path in that worktree.
+   file, task template, and the absolute INTENT.md path in the coordinator for
+   member tasks or in that worktree for coordinator tasks.
    Generate the coder's intent view with `python3 <absolute task_context.py>
-   --repo <absolute isolated-worktree> --task <absolute task file>` and include
+   --repo <absolute coordinator root for member tasks, otherwise isolated-worktree>
+   --task <absolute live task copy for member tasks, otherwise isolated task file>` and include
    its output in the brief. The helper preserves all global rules and falls
    back to full intent when projection is ambiguous. Never summarize it by hand.
    Add no hidden implementation context; repair a
@@ -233,10 +275,15 @@ dispatch contract and perform steps 1–5 by hand.
    completion when it lands — never wait for slower in-flight tasks first;
    when several results wait, land them in task-id order.
 
-   - For `ready`, compare the complete worktree diff to `base`. Permit only
-     declared `files` plus append-only Log changes in that task file. Include
-     additions, deletions, renames, and binary changes; an unexpected path
-     blocks before any product commit.
+   - For a `ready` coordinator task, compare the complete worktree diff to
+     `base`. Permit only declared `files` plus append-only Log changes in that
+     task file. Include additions, deletions, renames, and binary changes; an
+     unexpected path blocks before any product commit.
+   - For a `ready` member task, compare the complete member sidecar diff to the
+     returned `member_base`. Permit only declared `files`, including additions,
+     deletions, renames, and binary changes. Separately check the returned live
+     task `copy` against the coordinator task contract for an append-only Log.
+     An unexpected path or Log change blocks before any product commit.
    - For a returned `ready` coder, run `python3 <absolute dispatch_driver.py>
      finish --repo <absolute primary> --task-id <id>`. This action works with
      native child tools; no child command is needed. It reproduces serial work
@@ -276,6 +323,7 @@ dispatch contract and perform steps 1–5 by hand.
      task to `blocked` or `failed`, revoke a parallel isolate's active dispatch
      with `python3 <absolute isolation.py> deactivate-task
      --repo <isolated worktree> --task-id <id> --task-branch <task_branch>`.
+     A member task keeps `pending` instead; follow the member retry in step 2.
      Then update and checkpoint the bookkeeping and apply the recovery
      rule. Preserve the isolated worktree unless and until the explicit clean
      retry-retirement procedure in step 2 owns and removes it.

package/skills/gsd-path-build/references/dispatch.md

@@ -44,6 +44,19 @@ use exactly one matching branch:
   create another worktree. Encode task dependencies explicitly; launch
   independent children concurrently up to the host's advertised
   concurrent-subagent capacity.
+- A `muse.subagent_spawn` tool (with `muse.subagent_wait`,
+  `muse.subagent_read_result`, and `muse.subagent_send_message` siblings) is
+  Muse Code. Omit `subagent_type` (general-purpose, full capability), pass the
+  logical task name as `task_name` and `role`, and the complete brief as
+  `objective`. Never set `worktree_isolation`. Keep the returned
+  `subagent_id`; send a correction to a still-live child with
+  `muse.subagent_send_message` mode `followup` and the complete new prompt,
+  otherwise start a fresh child. Collect with `muse.subagent_wait`
+  (`wait_for: task_terminal`) then `muse.subagent_read_result`; on
+  `root_capacity_exhausted`, wait for a child to finish and retry. Spawn has no
+  model or effort argument, so record no such capability. If only
+  `muse.workflow` is exposed (untrusted workspace), do not script or inline
+  the work; stop and report that the workspace must be trusted.
 
 For every branch:
 

package/skills/gsd-path-build/references/operating-rules.md

@@ -0,0 +1,214 @@
+# Operating rules for phase work
+
+These rules extend the project `AGENTS.md` block. Every GSD Path skill
+bundles this file; spawned agents follow their role brief instead.
+
+## Files and state
+
+- `.project/discuss/DIALOGUE.md` and `.project/discuss/ANSWERS.md` are the
+  append-only memory for any-phase discussion. Read them before continuing an
+  existing thread; never treat chat history alone as durable context.
+- The discussion skill never commits. Every phase orchestrator treats only
+  complete append-only discussion records as expected bookkeeping and includes
+  them in its next normal `.project/` checkpoint; build does so before its next
+  clean layer base, and ship includes them in its transaction.
+- Write every output to the handoff path in WORKFLOW.md, using the absolute
+  bundled template path supplied by the active phase skill. An output that
+  needs verbal explanation is defective.
+- With no `.project/STATE.md`, route through the bundled
+  `scripts/detect_project.py initialize --repo <absolute-root> --template
+  <absolute-state-template> --require-git` helper; `route: setup-repository`
+  leaves the invocation folder unchanged and routes to repository setup before
+  state creation or branch binding. Never delete the invocation folder or its
+  state to satisfy bootstrap path checks. Do not classify from a directory listing
+  or conversation. Follow its JSON `verdict` and `route`. Reserve `classify`
+  for read-only inspection; do not use it as a state-initialization preflight.
+- `.project/STATE.md` tracks phase position. Parse and validate it only with
+  the bundled `scripts/pipeline_state.py validate` command, route with its
+  `route` command, and make ordinary phase transitions only with its
+  expected-state `transition`. A journaled transaction helper may write only
+  the state fields its contract explicitly owns. Never reproduce these
+  deterministic operations in model reasoning. The
+  orchestrator alone owns task frontmatter base, isolated worktree/branch,
+  status, and agent; the landing commit is proven from git by `isolation.py
+  recover`, never recorded. Require `pipeline: gsd-path/v2`; never
+  consume an ambiguous or differently owned state file. Artifacts outrank
+  summaries; reconcile STATE.md when it disagrees with task frontmatter.
+  During a program build, `.project/next/STATE.md` may hold
+  the lookahead planning track for the next milestone; it follows the same
+  marker rule, owns no task frontmatter, and never binds a branch.
+- STATE.integration_default is the project closeout choice and
+  STATE.integration is the current milestone choice. Both are `direct` or
+  `pull-request`; STATE.integration_source is `default` or `milestone` and
+  preserves explicit override provenance. Older v2 state defaults to `direct`,
+  and modes may be changed only through `pipeline_state.py
+  configure-integration` before build. A next milestone resets its current
+  choice from the project default.
+- Spawned agents have isolated context. Follow the installed runtime dispatch
+  contract and brief them with exact input and output paths, constraints, a
+  deterministic logical task name, and a bounded responsibility. Independent
+  briefs may run in parallel up to available child capacity; a dependent
+  brief runs as soon as its dependencies complete.
+
+## Stay in role
+
+- The codebase mapper and docs auditor observe and verify; they are strictly
+  read-only, report observations rather than judgments, and never resolve a
+  doc-vs-code conflict — that ruling belongs to the user.
+- Build, test, lint, and help commands are not presumed read-safe. Read-only
+  roles run project commands only in orchestrator-created disposable worktrees
+  at a recorded revision; otherwise they use static evidence or mark the check
+  unverifiable. They never create worktrees or run commands in the source tree.
+- Researchers gather evidence; they do not decide. A dimension is researched
+  only when it has open questions; the research phase records dispatched and
+  skipped dimensions. Brownfield adds `evidence-codebase.md` as settled input.
+- The decider works from existing evidence; it does not re-research. An
+  unresolved or uncited required decision fails the synthesis gate.
+- The planner reads both INTENT.md and SYNTHESIS.md and specs
+  deliverable-sized outcomes and constraints; every INTENT success criterion
+  maps to a task AC and Verify in PLAN.md Intent coverage. Coders own
+  implementation decisions inside those bounds.
+- Coders implement only their full task contract, including owned INTENT
+  success criteria read from INTENT.md, and append their result to the
+  task Log. They never change task state, review acceptance, stage, commit, or
+  freelance outside declared files.
+- The orchestrator dispatches, arbitrates, and creates task isolation and
+  verify sidecars through the bundled `scripts/isolation.py` helper — named
+  branches only, never a detached HEAD — lands task work serially, and
+  records each clean base in task frontmatter; `land` stamps the landed
+  state into the task's own commit, so a task has exactly one commit. It
+  writes no product code. When a done task's work already sits on the bound
+  branch without a landing commit, only an explicit owner ruling through
+  `isolation.py attest` may stand in for it: one `.project/`-only commit that
+  names the base, the attested HEAD, the declared files that changed, the
+  task Verify recorded as passing at that HEAD, and the ruling verbatim.
+  `recover` reports it as `attested`, never as a proven landing.
+- All pipeline work for a milestone lives on `gsd-path/M00N` (M001, M002,
+  …) bound in STATE.branch. The next milestone binds a new unused
+  `gsd-path/M00N` at the remote default after the previous ship integrates.
+  Integration at ship is the only path from the bound branch to the default
+  branch — either Path's direct merge or a Path-owned PR merged by the user.
+  The bound branch never receives merges or back-merges and is never the
+  GitHub default.
+- After initialization writes STATE.md, and before entering the first pipeline
+  phase in an existing Git repository, the router calls
+  `scripts/pipeline_git.py bind-initial` with the selected M00N and exact
+  fetched `origin/main` SHA. The helper alone checks worktree identity and
+  cleanliness, exact base, and every local, remote, and other-worktree
+  collision before creating or adopting the branch. The sole cleanliness
+  exception is untracked `.project/STATE.md`: validated v2 state in active
+  inspect or define, with null milestone, branch, and archive, in a real
+  directory containing only that regular file with no hard links. The helper
+  checks its identity and bytes across binding. Do not commit initialization
+  before binding. The router persists its
+  typed result in the new state. Build has no branch-creation authority.
+- After `validate-integrated` passes and before any next-milestone file
+  changes, the router calls the bundled `scripts/pipeline_git.py bind-next`
+  helper with the previous bound branch, exact ship SHA, and exact current
+  `origin/main` SHA. The helper moves the clean primary worktree to the new
+  unused `gsd-path/M00N` branch at that SHA without moving the previous
+  branch or entering the default checkout, then retires the integrated
+  previous branch — deleted locally and on origin; the ship commit stays
+  reachable from the integration merge and its annotated tag. The router
+  persists the new branch in STATE; a wrong-SHA or colliding branch blocks.
+  After validated PR integration, `bind-next --allow-missing-previous` may
+  retire only the local previous branch when GitHub already auto-deleted its
+  remote branch.
+  `bind-initial`, this handoff, and the approved new-repository bootstrap are
+  the only bound-branch creation authorities, and the handoff's retirement
+  push is the router's only bound-branch deletion authority. When a lookahead
+  track exists, the router then calls `scripts/pipeline_state.py promote-next`;
+  only that journaled helper moves the track, updates state and roadmap,
+  classifies plan drift, and writes the router promotion commit.
+- Build adopts the branch recorded in STATE.branch, never whatever is current
+  when a recorded branch exists. A new-GitHub REPOSITORY.md proves the
+  default checkout and first bound branch; later milestones may rebind
+  `gsd-path/M00N` without rewriting that artifact. Build ignores older
+  milestone ship and integrate commits inherited through main. A ship commit
+  for the current STATE.branch milestone must be an ancestor of origin/main;
+  if it is not, that milestone's integration is incomplete and control routes
+  to ship, not build. Direct mode requires the matching canonical `integrate:`
+  commit; PR mode requires tag metadata and a two-parent merge whose second
+  parent is the ship commit. A null branch returns
+  to the router; build never creates, selects, switches, or rebinds it.
+- The ship phase makes exactly one commit on the bound branch — the
+  `.project/`-only ship commit recording
+  STATE.md, the final-review artifacts, and the archive — and additionally
+  owns the integration leg. Direct mode creates and pushes one `--no-ff` merge
+  onto `main` with subject
+  `integrate: M00N — merge gsd-path/M00N into main`. Pull-request mode creates
+  or reuses one GitHub.com PR and waits for the user to merge it with a merge
+  commit; it never auto-merges. Both modes create one annotated
+  `milestone/<NNN>-<slug>` tag after merge validation.
+  The roadmap and
+  plan phases each make exactly one approval checkpoint commit
+  (`.project/`-only, deferred to the build transition commit during a
+  new-repository transaction or before Git exists). Their bundled
+  `pipeline_state.py approve` command journals before changing STATE or
+  ROADMAP.md and owns that canonical checkpoint; a routed
+  `resume-checkpoint` must finish before phase work. The router makes one
+  bookkeeping commit through `pipeline_state.py promote-next` when promoting a
+  lookahead track at a milestone boundary. Every other commit belongs to the
+  orchestrator.
+- Reviewers verify and block; they never fix. A block names the criterion,
+  observed result, evidence location, and concrete fix direction. An optional
+  review panel is advisory: the canonical reviewer remains the only wave
+  pass/fail, and panel findings never average or auto-replan. Same-model
+  agreement is not independent verification: matching verdicts from one
+  model family count as a single evidence path. Independence comes from
+  re-run commands, reconstructed patches, different sources, or a
+  different model family. Resolve panel
+  membership with the bundled `scripts/review_panel.py` helper; do not invent
+  model families or slugs. Create task isolation and verify sidecars with the
+  bundled `scripts/isolation.py` helper; do not invent `git worktree add` or
+  `--detach`. Undo unpublished pipeline work with `scripts/pipeline_undo.py`;
+  do not invent `git reset`. Diagnose a stuck pipeline with
+  `scripts/pipeline_diagnose.py`.
+- A bundled helper that exits non-zero stops the current step. Print its
+  stderr verbatim, run `scripts/pipeline_diagnose.py diagnose --repo
+  <absolute-root>` (bundled with `$gsd-path-forensics`), and report both.
+  Do not rerun the same command unchanged unless the helper's own contract
+  names that exact rerun as its interruption recovery. Never repair state or
+  Git by hand instead.
+- The discussion sidecar may run during any non-shipped phase. It grounds
+  answers in code and phase artifacts, may perform focused research when
+  needed, and writes only its discussion artifacts; it never changes phase
+  state or bypasses a phase gate.
+- During an uncommitted archive transaction, discussion writes a complete
+  active copy that extends the archived pair. The ship phase reruns `prepare`;
+  the helper validates the prefix and atomically reconciles both files.
+  Discussion never edits an archive directly or writes after shipment.
+- The loop runner wraps explicit skills in a bounded check → verify → fix →
+  verify pass driven by a LOOP.md spec. It never advances a phase gate
+  itself and never commits or pushes.
+- Fix tasks use the complete task template, not an abbreviated finding.
+
+## New GitHub repositories
+
+- Create a GitHub repository only from an explicit user request followed by an
+  approval of the exact owner/name, visibility, default-checkout path,
+  `gsd-path/M001` branch, and linked primary-worktree path. Before the
+  external action produces an artifact, present those proposed targets as the
+  inline **Review** surface using the active router's preview contract.
+  Do not write a
+  preview file into the invocation directory or another repository. Run the
+  bundled bootstrap helper's read-only `preview` command for this evidence.
+- After approval, the bootstrap helper persists the exact targets under the
+  approved workspace before the first external mutation. Its `create` command
+  creates or verifies the remote, checkout, branch, and linked worktree one
+  stage at a time. A matching journal permits explicit resume and adoption; a
+  collision without that journal blocks. The helper removes the journal only
+  after writing owned STATE.md and fixed-format `.project/REPOSITORY.md` in the
+  linked worktree.
+- During an approved new-repository transaction, the router may create the
+  first GSD Path branch and linked primary worktree at the verified
+  remote-default SHA and persist that branch in STATE.md and REPOSITORY.md.
+  Build must verify and adopt that exact binding from REPOSITORY.md, never a
+  free-form log. Task branches and task worktrees remain exclusively
+  build-orchestrator owned.
+- Keep the cloned default checkout clean on the remote default branch. Run the
+  pipeline from the linked GSD Path worktree; never initialize `.project/` in
+  the default checkout, reuse an existing branch or path (except an explicitly
+  approved empty linked-worktree folder via `--reuse-empty-worktree`), move an existing
+  repository, or recover a partial GitHub creation without the exact approved
+  journal and re-verification.

package/skills/gsd-path-build/references/reviewer-final.md

@@ -1,8 +1,13 @@
 ## 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
+Each `### SCn —` heading must match the criterion text as
+`check_handoffs._success_criteria` stores it from INTENT.md `## Success
+criteria`: indented continuation lines join with a single space and keep
+their `- ` list markers; the gate compares titles with `_normalize_ws`
+only. 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,
@@ -14,6 +19,19 @@ re-run PLAN.md's project Verify; cite the orchestrator's recorded
 project-verify sidecar output. `pass`
 requires every criterion to be `met`.
 
+When INTENT.md `## Edge coverage` or `## Prohibitions` tags a criterion with a
+`held-out` edge or a `judgment` prohibition, grade that criterion on cited
+evidence for every tag (see the [spec-reach probes](spec-probes.md)). Name
+each id in Check, Observed, or Reference with its evidence: the held-out
+test's recorded passing output from the PLAN.md `## Held-out checks` test, or
+the observed behavior judged against the prohibition's Detail. When a tag's
+evidence is missing, did not run, or cannot be judged, record `unverifiable`
+with `Finding: insufficient spec evidence: <id> <what is missing>` and a Fix
+direction naming the check to add or run. Never mark such a criterion `met`
+on inference or on code that merely looks right; the ship gate refuses a
+`met` verdict that does not cite every tag. Grade untagged criteria as usual:
+the trigger is the INTENT.md tag, never your own doubt.
+
 ## Final gap mode
 
 Use only gap-review.md. Check the one cross-wave risk in the brief against the

package/skills/gsd-path-build/references/reviewer-wave.md

@@ -23,10 +23,18 @@ tasks in this wave as the rubric. For each task:
    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
+against that same isolated product. In each `### SCn —` heading, copy the
+criterion text exactly as `check_handoffs._success_criteria` stores it from
+INTENT.md `## Success criteria`: indented continuation lines are joined
+with a single space and keep their `- ` list markers in the compared text;
+only whitespace is normalized at the gate. Do not paraphrase or drop
+sub-bullets. 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.
+an SC. When INTENT.md `## Edge coverage` or `## Prohibitions` has rows for
+an owned SC, judge it against those rulings too: cite each `held-out` edge
+id with its held-out test's recorded output and each `judgment` prohibition
+id with what you observed. A missing held-out result or a violated ruling
+fails the SC.
 
 Allow changed paths only in the task's `files` plus its assigned task file.
 Within the task file, allow orchestrator-owned `base`, `worktree`,
@@ -62,8 +70,13 @@ 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
+`- **Observed**:` with the walked states and actual result. `Surface` holds
+exactly the surface name from PLAN's Surface contract; walkthrough detail belongs
+in Check and Observed. Reuse recorded task
+output if it proves that exact walkthrough; run only a missing check. Cite
+every `held-out` edge and `judgment` prohibition id of each criterion in its
+evidence; shipping derives FINAL.md from these records, and an uncited id
+sends the milestone to a dispatched final review instead. 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.
 

package/skills/gsd-path-build/references/reviewer.md

@@ -46,7 +46,9 @@ Resolve sibling links against this role file's directory.
   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.
+  warn that it needs tightening, unless INTENT.md `## Edge coverage` or
+  `## Prohibitions` rules on that reading: a ruling there binds, and a
+  reading that contradicts it fails.
 - Do not edit code, tasks, plans, or implementation state.
 
 Return verdicts and the review output path without extra prose.

package/skills/gsd-path-build/references/spec-probes.md

@@ -0,0 +1,150 @@
+# Spec-reach probes
+
+Define runs two probes over the success criteria before approval: the edge
+probe (what each criterion must do at its edges) and the prohibition probe
+(what each criterion must never silently become). Both leave a table in
+INTENT.md. Plan, build review, and final review read those tables; the
+`check_handoffs.py intent`, `plan`, and `final` gates enforce them.
+
+## Why define owns this
+
+A reviewer can only check what the intent states. An edge nobody wrote down
+is never checked: final review covers exactly the INTENT success criteria,
+and a reviewer passes any reasonable reading of an ambiguous one. Model
+reviewers are also confidently wrong on exactly these gaps. On three tasks
+whose correct behavior the spec left unstated, LLM verifier verdicts caught
+the defect 0 times in 12 while a held-out test caught all three; in a larger
+replication, stating the surfaced edge in the spec raised the verifier's
+catch rate to 98% ([Verifier Reach Is Spec Reach](https://github.com/davesienkowski/verifier-reach-is-spec-reach)).
+A smarter reviewer does not close that gap; a wider intent does. The user is
+present at define, so define is where the edge gets its ruling.
+
+## Edge probe
+
+Walk every success criterion:
+
+1. Name the data shapes the criterion handles, then raise only the
+   categories those shapes reach:
+
+   | Shape | Categories |
+   |-------|------------|
+   | numeric range, dates, money, counts | boundary, precision |
+   | list, set, rows, intervals | adjacency, empty, ordering |
+   | text, names, identifiers | empty, encoding |
+   | state that persists or repeats | idempotency, concurrency |
+   | files, network, processes | concurrency |
+
+2. For each raised category, write one concrete candidate edge and the
+   ruling you recommend:
+
+   | Category | Probe question |
+   |----------|----------------|
+   | boundary | What happens exactly at each minimum, maximum, or threshold, and one step either side? |
+   | adjacency | When two items are equal or just touch, do they merge, collide, or stay separate? |
+   | empty | What is the result for empty, single-item, or missing input? |
+   | encoding | Whose length or equality applies: bytes, code points, grapheme clusters, normalized form, case? |
+   | ordering | When items compare equal, is output order specified and stable? |
+   | precision | Where can rounding, overflow, or truncation happen, and which rule applies? |
+   | idempotency | What happens when this runs twice on the same input? |
+   | concurrency | If interrupted or run in parallel, what is guaranteed? |
+
+3. Ask the user in one small round, all criteria together, recommended
+   ruling first. Never rule on an edge's behavior yourself: the correct
+   answer is exactly what the criteria did not say, so a guess here is the
+   defect this probe exists to prevent. Under pre-approval, an edge whose
+   behavior the user has not stated is still a required answer: stop and
+   ask instead of ruling.
+
+4. Record each ruling as one row:
+   - `criterion SCn` when the answer is observable where the user sees the
+     work. Add or amend that success criterion (define owns criteria), then
+     point the row at it. An existing criterion that already states the
+     edge may be named directly.
+   - `held-out` when the answer is a precise rule or a set of examples that
+     belongs in a test rather than a user-facing criterion (a normalization
+     form, a rounding rule, an inclusive bound on an internal API). Write the
+     ruling or the user's examples verbatim in Detail. The plan must schedule
+     a named test that pins it.
+   - `dismissed` when the edge cannot occur for this criterion. Detail says
+     why ("input is a closed enum"). "Not important" is not a reason.
+
+Every criterion gets at least one row. A criterion with no data shape gets
+one row with category `none`, dismissed with its reason.
+
+## Prohibition probe
+
+Walk every success criterion with one adversarial question: what could this
+silently become that the user would not want, although nothing in INTENT.md
+forbids it? Generate candidates privately, then keep only values, safety,
+privacy, fairness, and transparency items: "must not email unsubscribed
+users", "must not store raw card numbers in logs", "must not use guilt
+wording". Drop routine engineering items (mutating input, throwing on empty
+input, leaking handles); those are edges or ordinary review. Do not mint
+generic security or compliance canon (injection, path traversal, data
+retention law); record a real compliance need under Constraints instead.
+Expect two or three kept items for work people touch, and often none for
+internals.
+
+Present the kept items with a recommended ruling and record each as a row:
+
+- `criterion SCn` when a test or command can check it. State it as a
+  success criterion and point the row at it.
+- `judgment` when it is real but not mechanically checkable. Detail says
+  what the final reviewer looks for.
+- `dismissed` when the user rules it out. Detail records the reason.
+
+Work that affects no person directly records a single row instead, and no
+other: `| N1 | all | none | dismissed | <why no person is affected> |`.
+
+## INTENT.md tables
+
+```markdown
+## Edge coverage
+
+| Edge | Criterion | Category | Disposition | Detail |
+|------|-----------|----------|-------------|--------|
+| E1 | SC1 | boundary | criterion SC4 | |
+| E2 | SC1 | empty | dismissed | the command always receives at least one file |
+| E3 | SC2 | encoding | held-out | names compare by NFC code points, case-sensitive |
+
+## Prohibitions
+
+| Prohibition | Criterion | Must not | Disposition | Detail |
+|-------------|-----------|----------|-------------|--------|
+| N1 | SC2 | send a reminder to an unsubscribed user | criterion SC5 | |
+| N2 | SC2 | use guilt or shame wording | judgment | reminder copy is neutral and states only the due item |
+```
+
+Ids are contiguous from `E1` and `N1`. Detail is required for every row that
+is not `criterion SCn`. The headings are exact: `## Edge coverage` and
+`## Prohibitions`. An INTENT.md without them predates the probes and is not
+rechecked; a near-miss heading fails the gate rather than switching it off.
+
+## Downstream
+
+- **Plan.** Every `held-out` edge gets one PLAN.md `## Held-out checks` row
+  naming the task that owns the edge's criterion and the test file (a
+  `path::test_name` node id is fine). That file is listed in the task's
+  `files`, the task's Verify runs it, and the task's Acceptance criteria
+  state the edge id and its ruling. A `criterion SCn` row needs nothing extra: SCn is
+  already covered like any criterion. A `judgment` prohibition belongs in
+  the owning task's Approach so the coder knows the line.
+- **Review.** A row pins the reading of its criterion. A reviewer does not
+  pass a reading that contradicts a ruling in either table, and cites each
+  held-out edge and judgment prohibition id with its evidence.
+- **Final review.** A criterion that carries a held-out edge or a judgment
+  prohibition is `met` only when its Check, Observed, or Reference cites
+  every such id with the evidence: the held-out test's recorded passing
+  output, or the observed behavior judged against Detail. When that
+  evidence is missing, did not run, or cannot be judged, record
+  `unverifiable` with `Finding: insufficient spec evidence: <id> ...`;
+  never `met` on inference. The trigger is the tag, not reviewer doubt:
+  criteria without a tag are graded as usual and never abstained.
+
+## What the gates can and cannot prove
+
+`check_handoffs.py intent` (before approval and again when define records
+approval), `plan`, and `final` prove the tables are complete, every held-out
+edge has a scheduled test, and every tagged `met` cites its tags. They cannot
+prove who made a ruling or that a cited result says what the verdict claims.
+Those stay with the define conversation and the reviewer's recorded evidence.