@opengsd/gsd-path 1.3.0 → 1.4.0

package/skills/gsd-path/SKILL.md

@@ -3,13 +3,29 @@ name: gsd-path
 description: Inspect .project/STATE.md, report GSD Path progress, and run the next valid phase. Use only when the user explicitly invokes $gsd-path. The status argument reports state without advancing; config views or edits settings without advancing. Do not infer this skill from generic project, next-step, or resume requests.
 ---
 
-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).
 
 ## Configuration mode
 
 When the first argument is `config`, read [Path settings](references/config.md)
 and complete that request without initializing state or advancing a phase.
 
+## Pre-approval
+
+`--pre-approve <kinds>` in the arguments (`intent`, `plan`, or `intent,plan`)
+grants those gates ahead of time for this run, for unattended quick lanes.
+After `.project/STATE.md` exists and before milestone intent approval, run
+`python3 <absolute pipeline_state.py> pre-approve --repo <absolute root>
+--grant <kinds>` once; its Log record is the grant. Write only the kinds the
+owner passed. A refused grant stops the run with the helper's message. Ship,
+roadmap, patch selection, and repository setup are never pre-approved. At a
+granted gate, the define or plan contract runs `python3 <absolute
+workflow_run.py> preauthorize --repo <absolute root> --kind <kind>` before
+asking: `complete` passes the gate through its normal approval command;
+`blocked` asks the owner as usual. A grant never answers an interview
+question, ruling, or `NEEDS-USER` item.
+
 # GSD Path Router
 
 Determine the current pipeline phase, report it briefly, and run the next valid
@@ -188,6 +204,34 @@ The current value resets from the project default at the next milestone.
 Both settings lock when build starts. A lookahead STATE inherits the active
 project's `integration_default` and uses it for `integration`.
 
+## Member repositories
+
+A coordinator project can change other repositories (members) in the same
+milestone; `.project/MEMBERS.md` lists them. Change members only at a
+milestone boundary, never during build or ship. Resolve the bundled
+`scripts/members.py` to an absolute path and use it; never edit MEMBERS.md
+or a member marker by hand.
+
+- To add an existing repository, it needs a GitHub.com `origin` whose default
+  is `main`, a clean worktree, and no active milestone of its own. Ask for the
+  member name, checkout path, and integration (`direct`, `pull-request`, or
+  `default`, which follows the milestone's choice), then run
+  `python3 <members.py> add --repo <absolute-root> --name <name> --checkout <path> --integration <mode>`.
+- To create a new member repository, present the exact `owner/name`,
+  visibility, and checkout path as the **Review** surface and get approval
+  first, as for a new GitHub repository. Then run the same command with
+  `--create <owner/name> --visibility <visibility>`. It journals the approved
+  target before creating anything; rerun the identical command to resume.
+- After adding a member, tell the user to install its guard hooks:
+  `npx @opengsd/gsd-path@latest --member-of <absolute-root> --project <member checkout>`.
+- `python3 <members.py> validate --repo <absolute-root>` checks every member;
+  `repair` rewrites stale markers; `detect --checkout <path>` reports whether a
+  repository is a member and of which coordinator.
+
+Build locks the members that tasks name and works in Path-owned member
+branches `gsd-path/<project>-M00N`. Ship runs `close-members` after preflight
+to merge each member in lock order, then ships the coordinator.
+
 ## Transaction recovery first
 
 For a helper failure, use the diagnostic in the sibling bundle:

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

@@ -82,9 +82,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
@@ -171,7 +174,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
@@ -190,12 +203,14 @@ dispatch contract and perform steps 1–5 by hand.
    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 +222,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 +260,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 +308,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/references/codebase-mapper.md

@@ -10,7 +10,8 @@ change nothing outside your single output file.
 - Read AGENTS.md and the template before scanning. 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
+  path; the orchestrator transfers it after validation. `Repo root` still names
+  the primary repo root, never the disposable root. Do not ask the user
   questions.
 
 ## What to establish

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

@@ -11,7 +11,8 @@ actually does. Read-only: change nothing outside your single output file.
 - 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
+  path; the orchestrator transfers it after validation. `Repo root` still names
+  the primary repo root, never the disposable root. Do not ask the user
   questions.
 
 ## Method

package/skills/gsd-path/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/references/planner.md

@@ -86,6 +86,14 @@ plan order above, which still keeps plan-invalidating risk in wave 1.
   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.
+- In a multi-repo milestone (`.project/MEMBERS.md` lists members), each task
+  changes exactly one repo. Give a member task `repo: <member>`; its `files`
+  and Verify are relative to that member's root, and its Verify runs there.
+  Coordinator tasks omit `repo:`. Split work that spans repos into one task
+  per repo joined by an Interface contract. PLAN.md's project Verify runs
+  from the coordinator root and reaches a member as `../<member>`. Do not
+  plan a task for a member this milestone already closed at ship; plan it in
+  the next milestone.
 - Preserve every template field and its required initial value.
 
 Put the full-project build-and-test command in PLAN.md. Copy `Review panel:`

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

@@ -62,7 +62,9 @@ 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
+`- **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. 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.