@opengsd/gsd-path 1.4.0 → 1.6.0

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

@@ -159,7 +159,12 @@ so the position is unchanged. Then:
    then stop and do not invent a patch finding. A `not-met`,
    `unverifiable`, or blocked gap with valid evidence sets `ship/blocked`,
    writes `.project/review/PATCH-FINDINGS.md` from the patch-findings template,
-   and runs `python3 <absolute check_handoffs.py> patch --repo <absolute repo
+   copying the full `Risk: ...` line into each gap finding's Locator, its
+   `Found` field into Evidence, and its `Fix direction` field verbatim. For a
+   `FINAL.md` finding, use its `SC<n>` id as Locator and copy its `Finding` and
+   `Fix direction` fields verbatim. The patch validator requires these source
+   field values to match exactly; do not shorten or paraphrase them. Run
+   `python3 <absolute check_handoffs.py> patch --repo <absolute repo
    root>`. Present the blocked outcome, link the resolved absolute
    PATCH-FINDINGS.md path, and state that patch planning is next. The manifest
    contains exactly those FINAL.md and gap rows. When routed by an active
@@ -262,7 +267,11 @@ The persisted `STATE.archive` field is the transaction identity.
    `python3 <absolute archive_milestone.py> close-members --repo <root>`
    after preflight passes and before recording shipment. It closes each
    locked member in lock order in that member's integration mode and
-   journals each one. When it returns `awaiting-merge`, report the member PR
+   journals each one. Each member closes onto the default branch that
+   MEMBERS.md records for it (`main` when its section has no
+   `Default branch`); when the command reports
+   `remote default must be <recorded>`, stop and report it. When it returns
+   `awaiting-merge`, report the member PR
    link, stop, and rerun the same command after the user merges it; never
    merge a member PR yourself. When it returns `integrated`, keep its `body`
    for the ship commit below.
@@ -305,8 +314,10 @@ The persisted `STATE.archive` field is the transaction identity.
    milestone is not shipped until integration below passes.
 7. Integrate only after the postcommit `validate` passes, with the recorded
    ship commit and exact reviewed HEAD unchanged. Run `python3 <absolute archive_milestone.py> integrate --repo <root> --slug <STATE.milestone>`.
-   This helper validates the ship commit, fetches origin, requires remote
-   default `main`, and follows the locked `STATE.integration` mode:
+   This helper validates the ship commit, fetches origin, requires the remote
+   default to equal STATE `default_branch` (`main` when the field is absent),
+   and follows the locked `STATE.integration` mode. `main` and `origin/main`
+   below mean that recorded branch:
 
    - `direct` owns the resumable merge transaction. It creates the canonical
      named integration worktree, performs the hook-verified `--no-ff` merge,
@@ -339,6 +350,22 @@ The persisted `STATE.archive` field is the transaction identity.
      landing SHA. A closed unmerged PR, squash, rebase, merge queue, moved
      head, duplicate PR, or non-GitHub.com origin blocks. The remote bound
      branch may be absent after a valid merge because GitHub may auto-delete it.
+   - `external-landing` is for an origin where Path cannot open the review
+     itself, such as GitLab, Gitea, or GitHub Enterprise Server. It needs no
+     forge CLI. The helper publishes the bound branch at the exact ship commit,
+     never pushes `main`, and returns `status: awaiting-merge` with `branch`,
+     `merge_subject`, and `merge_body`. Present **Outcome**, and state in
+     **Next** that the user must open a merge request from `branch` to `main`
+     in their own forge and merge it with a merge commit. The merge commit
+     message must be exactly `merge_subject`, a blank line, then `merge_body`;
+     show both values verbatim in a code block. Stop this ship invocation;
+     Path never opens or merges the request. The forge may delete the source
+     branch after the merge. On rerun after the merge, the helper requires exactly
+     one commit with that subject on `origin/main` first-parent history, that
+     exact body, and two parents with the ship commit as second parent. It
+     then writes and pushes the annotated milestone tag containing the ship
+     SHA and landing SHA. A squash, rebase, fast-forward, or different merge
+     message blocks.
 
    A passing run returns the same proof exposed by `validate-integrated`.
    A non-zero result blocks; rerun the exact `integrate` command to resume a
@@ -349,7 +376,7 @@ The persisted `STATE.archive` field is the transaction identity.
    continuing. Never merge into or re-ship the closed branch.
    For a later validation recheck with origin network access, run
    `python3 <absolute archive_milestone.py> validate-integrated --repo <root> --slug <STATE.milestone>`.
-   Both integration modes refresh the remote-default and mirrored milestone-tag
+   All integration modes refresh the remote-default and mirrored milestone-tag
    refs when an `origin` remote exists. Without that remote, validation resolves
    the existing remote-default refs locally, preserving offline direct-mode
    fixtures. PR mode also revalidates the PR identity, state, merge provenance,

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

@@ -38,8 +38,8 @@ bundles this file; spawned agents follow their role brief instead.
   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
+  STATE.integration is the current milestone choice. Both are `direct`,
+  `pull-request`, or `external-landing`; 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
@@ -82,7 +82,9 @@ bundles this file; spawned agents follow their role brief instead.
   `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.
+  `recover` reports it as `attested`, never as a proven landing. Attestation
+  matches the declared files literally: work that is only below a declared
+  directory can land but cannot be attested.
 - 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.
@@ -90,6 +92,12 @@ bundles this file; spawned agents follow their role brief instead.
   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.
+- The default branch is the one that STATE `default_branch` records at
+  initialization; a STATE file without the field means `main`. `main` and
+  `origin/main` in these rules mean that branch. Never change the record and
+  never take the name from a later `origin/HEAD` lookup. For a member
+  repository, the branch is the one that its `.project/MEMBERS.md` section
+  records as `Default branch`; a section without the field means `main`.
 - 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

package/skills/gsd-path-ship/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 have every word of the criterion in INTENT.md
+`## Success criteria`: join indented continuation lines and sub-bullets
+with a single space. You can keep or remove the `- ` markers of the
+sub-bullets; the gate compares every other word. 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-ship/references/reviewer-wave.md

@@ -17,16 +17,26 @@ tasks in this wave as the rubric. For each task:
    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
+   complete task acceptance or interface criterion (see Review file format
+   below). 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.
 
+A Log entry `orchestrator regression Verify of <task id> retired: superseded
+by <task id>` is not evidence: judge the superseding task's acceptance
+criteria. The same applies to the entry `orchestrator regression Verify of
+<fix task id>: part of <task id> retired: superseded by <task id>`.
+
 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.
+against that same isolated product. In each `### SCn —` heading, copy the
+complete criterion text from INTENT.md `## Success criteria` (see Review
+file format below). 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. 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`,
@@ -40,6 +50,30 @@ 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.
 
+### Review file format
+
+`scripts/check_handoffs.py wave` rejects a review file that breaks one of
+these rules, and `scripts/review_findings.py` cannot group a failure whose
+criterion text does not match. Apply the rules before you write the file.
+
+- **Section order.** Put the `## T### —` sections in task id order (T001
+  before T002). The order of the PLAN.md wave table does not apply. A `pass`
+  review has one section for each task of the wave.
+- **Section heading.** Write `## T### — <title>: pass` or `: fail`, where
+  `<title>` is the exact `title:` value of the task file.
+- **Evidence lines.** An evidence line starts with `- ✅ ` for pass or
+  `- ❌ ` for fail. Each task section and each `### SCn —` block needs one
+  or more lines with the marker of its own verdict. A failed task needs a
+  `- ❌ ` criterion line, also when other text describes the failure.
+- **Criterion text.** In a task evidence line and in a `### SCn —` heading,
+  copy every word of the criterion. Join wrapped lines and sub-bullets with
+  one space. You can keep or remove the `- ` markers of the sub-bullets.
+  A changed, added, removed or moved word does not match.
+- **Angle brackets.** Text such as `<b>` or `<path>` outside backticks reads
+  as an unfilled template placeholder and is rejected. Write literal markup
+  and code in backticks inside a sentence, for example: the output has
+  `<b>hello</b>`.
+
 ### Re-review after a proven repair
 
 When the brief supplies a `review_findings.py repair-evidence` receipt, use
@@ -47,14 +81,21 @@ 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
+for `files` inside the supplied sidecar. For a member repair (the receipt
+names `member`), use `member_base` and `member_commit` in that member's
+repository. `earlier_repairs` are linked repairs of the same findings that
+are already in the repair base. When the receipt has `later_repairs`, linked
+repairs changed the same files after this repair: apply their patches in
+order too. Read the repair task's recorded
+Verify, or with `later_repairs` that of the last one, which is the receipt's
+`verification`; 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.
+using that repair; the parent resolves it, or briefs this review in full at
+the current HEAD without a receipt, rather than creating another product fix
+for the unchanged historical failure.
 
 ## Final scope in a quick full wave
 
@@ -65,7 +106,10 @@ criterion's Intent coverage block includes `- **Surface**:`, `- **Check**:`, and
 `- **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
+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-ship/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-ship/references/runtime-selection.md

@@ -20,6 +20,15 @@ references to bundled copies of those helpers. Other skill helpers, templates,
 and role briefs remain in the installed skill bundle. Pass `-B` to Python helper
 invocations so execution does not create bytecode in the runtime store.
 
+The selected runtime is authoritative for each helper in its `manifest.json`;
+this includes `review_findings.py` and `task_context.py`. A selected runtime
+that was published before a helper became a runtime file does not list that
+helper: run the bundled copy until the project runtime is upgraded.
+`dispatch_driver.py` and `workflow_run.py` always run from the installed skill
+bundle, because they read role briefs and templates from it; a skill update
+replaces them, a runtime upgrade does not. The driver reloads the helper modules
+that it imports from the selected runtime.
+
 With no declaration, retain the legacy helper lookup. An existing
 `.gsd-path/runtime/` requires the explicit `--runtime-migrate --project PATH`
 operation before adopting external storage; review the resulting Git diff.

package/skills/gsd-path-ship/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.