@opengsd/gsd-path 1.0.0 → 1.1.0

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

@@ -0,0 +1,21 @@
+## Final integration mode
+
+Use only final-review.md. Treat INTENT.md success criteria as the rubric.
+Exercise the running system and record `met`, `not-met`, or `unverifiable`
+with checked command output or a precise file reference. When PLAN.md carries
+a `## Surface contract`, every criterion it lists under a surface is checked
+by performing that surface's Walkthrough from its Entry in the supplied
+sidecar: `Surface` names that surface, Check names what was performed,
+Observed records what the surface actually showed at each state, and a missing
+or unreachable surface is `not-met`. A surface criterion is never `met` on
+internal test output alone. Run project commands only in the supplied verify
+sidecar at the exact reviewed HEAD. Do not
+re-run PLAN.md's project Verify; cite the orchestrator's recorded
+project-verify sidecar output. `pass`
+requires every criterion to be `met`.
+
+## Final gap mode
+
+Use only gap-review.md. Check the one cross-wave risk in the brief against the
+running system in the supplied verify sidecar at the exact reviewed HEAD.
+Record evidence and `pass` or `blocked`; an unverified risk is blocked.

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

@@ -0,0 +1,17 @@
+## Plan panel mode
+
+Use only plan-panel.md. Review `.project/plan/PLAN.md` and every task file
+against INTENT.md and SYNTHESIS.md. Do not edit those files. Write one
+finding block per issue, or `- none`. Mark `Kind: criterion` only when the
+finding names a written plan/task criterion; alternate designs are
+`Kind: preference`. This output is advisory. The structural plan gate and
+the user's approval remain the only plan gates.
+
+## Wave panel mode
+
+Use only wave-panel.md. Apply every Wave mode evidence rule (recorded SHAs,
+isolated patch, recorded Verify) when the brief supplies a verify sidecar.
+On a `deep` wave the brief is the adversarial lens only. Record findings
+the same way as plan panel mode. Do not write a Wave verdict and do not
+edit the canonical wave-review file. The inherit reviewer remains the only
+pass/fail.

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

@@ -0,0 +1,20 @@
+## Skeptic mode
+
+Use only skeptic.md. The brief supplies one canonical criterion locator, the
+failed criterion verbatim, and every distinct blocking observation for that
+criterion from the `deep` wave lenses, plus the involved task files and their
+recorded bases and proven landing commits. The only job is to refute all of
+those observations.
+
+- Apply every Wave mode evidence rule (recorded SHAs, isolated patch,
+  recorded Verify) in the supplied sidecar, scoped to the tasks the
+  observations cite.
+- Address every distinct observation separately. Record `Verdict: refuted`
+  only when checked evidence refutes every observation by proving each
+  claimed failure cannot occur or the cited criterion actually holds.
+  Anything short of that is `Verdict: stands`.
+- Stage
+  `.project/review/wave-N.cycleC.skeptic-<criterion_locator>.md` under the
+  supplied sidecar.
+- Do not write a Wave verdict and do not review anything beyond the
+  supplied criterion and observations.

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

@@ -0,0 +1,89 @@
+## Wave mode
+
+Use task acceptance criteria and the INTENT.md success criteria owned by
+tasks in this wave as the rubric. For each task:
+
+1. Read the task file's `base` and the landing commit SHA the orchestrator
+   supplied in your brief (it comes from `isolation.py land`/`recover`).
+   Never infer either SHA from task ids, branch position, or nearby history.
+2. Fail a missing, malformed, or invalid SHA. Inspect the commit with
+   `git show --format=fuller --stat --patch <commit> --`.
+3. In the supplied verify sidecar at `base`, apply only the complete
+   binary patch from `commit^..commit` for the task's declared product files
+   and inspect the diff. Use the orchestrator's recorded isolated Verify
+   output in that task's Log as the Verify evidence. Do not re-run the
+   task Verify command or PLAN.md's project Verify. Re-run a command only
+   when the recorded output plus the isolated diff cannot check the
+   criterion. Never use the primary worktree or branch tip as task
+   evidence. Do not create or remove Git worktrees yourself.
+4. Mark `pass` or `fail`. Before the evidence separator (` — `), copy the
+   complete task acceptance or interface criterion verbatim, joining wrapped
+   lines with spaces. Do not substitute an AC id or summary: finding grouping
+   binds this text to the task. Give the observed result, `file:line`, and
+   concrete fix direction for each failure.
+
+Then check each INTENT.md success criterion owned by a task in this wave
+against that same isolated product. Copy the criterion verbatim from
+INTENT.md. Mark `pass` or `fail` with evidence; a failed owned SC blocks
+the wave. Omit the Intent coverage section when no task in the wave owns
+an SC.
+
+Allow changed paths only in the task's `files` plus its assigned task file.
+Within the task file, allow orchestrator-owned `base`, `worktree`,
+`task_branch`, `status`, and `agent` fields plus append-only Log
+entries; block contract-body changes in the task commit. Warn on disabled tests
+or Verify commands that cannot fail unless either defeats a criterion. Set the
+wave verdict to `pass` only when every task passes and every owned INTENT
+success criterion for the wave passes.
+
+For cycle greater than 1, read the previous review, re-check every failure,
+and regression-check affected passes. State when the same criterion fails for
+a different reason. Use only the wave-review template.
+
+### Re-review after a proven repair
+
+When the brief supplies a `review_findings.py repair-evidence` receipt, use
+its isolated repair product for the linked original criteria, including owned
+INTENT criteria. The original faulty landing and earlier verdicts remain
+historical evidence; they do not force the later verdict to remain failed.
+Reconstruct the receipt's repair `base` plus only its `commit^..commit` patch
+for `files` inside the supplied sidecar. Read the repair task's recorded
+Verify, inspect the patch against the original unchanged contract, and reuse
+settled checks. Check unaffected criteria from their prior evidence plus the
+repair diff for regressions. Cite the receipt, repair landing and task Log in
+the new review. A receipt proves provenance, not acceptance: judge whether the
+repair actually satisfies the criterion. A missing or rejected receipt blocks
+using that repair; the parent resolves it rather than creating another product
+fix for the unchanged historical failure.
+
+## Final scope in a quick full wave
+
+When explicitly briefed with final scope, record `Review scope: final` and the
+full supplied review HEAD in the wave artifact. Check all INTENT success criteria
+and PLAN's Surface contract against the completed isolated product. Each surface
+criterion's Intent coverage block includes `- **Surface**:`, `- **Check**:`, and
+`- **Observed**:` with the walked states and actual result. Reuse recorded task
+output if it proves that exact walkthrough; run only a missing check. Final-scope
+coverage shares this wave artifact; do not write a second report. Shipping's
+runtime checks freshness and derives the final view from these records.
+
+## Deep review lenses
+
+A `deep` wave spawns two independent reviewers in parallel, each with a fresh
+context and its own verify sidecar at the recorded review base. Every
+Wave mode rule above applies to both lenses.
+
+- **Contract** — logical task name
+  `review_wave_<wave>_cycle_<cycle>_contract`; stages
+  `.project/review/wave-N.cycleC.contract.md`. This is the full wave review:
+  patches applied to the recorded base, recorded Verify plus diff, every
+  acceptance criterion and interface contract checked. Record `Lens:
+  contract`.
+- **Adversarial** — logical task name
+  `review_wave_<wave>_cycle_<cycle>_adversarial`; stages
+  `.project/review/wave-N.cycleC.adversarial.md`. Try to kill the work:
+  security holes, unhandled edge cases, failure modes, data-loss and
+  concurrency risks, missing error handling. Record `Lens: adversarial`.
+
+The wave passes only when both lenses return `pass`; any `blocked` lens
+blocks the wave.

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

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

package/skills/gsd-path-build/scripts/archive_milestone.py

@@ -239,15 +239,10 @@ class ArchiveError(RuntimeError):
 
 
 PIPELINE_MARKER = _common.PIPELINE_MARKER
-PR_CREDIT_LINE = (
-    "PR prepared with [GSD Path](https://github.com/open-gsd/gsd-path)."
-)
-GITHUB_HOST = "github.com"
 
 
-# discussion_validate and integration call back into this module through a
-# module reference and import the constants and ArchiveError above, so this
-# import must stay below those definitions.
+# discussion_validate calls back into this module and imports its constants
+# and ArchiveError, so this import must stay below those definitions.
 if __package__:  # imported as scripts.archive_milestone
     from .discussion_validate import (
         record_sections,
@@ -280,42 +275,6 @@ if __package__:  # imported as scripts.archive_milestone
         render_manifest,
         validate_manifest,
     )
-    from .integration import (
-        resolve_remote_default,
-        live_remote_ref,
-        publish_bound_branch,
-        refresh_origin,
-        optional_ref,
-        integration_names,
-        registered_worktree,
-        remove_registered_worktree,
-        delete_integration_branch,
-        require_generated_integration_commit,
-        discard_unpublished_stale_integration,
-        create_integration_merge,
-        require_annotated_tag,
-        ensure_integration_tag,
-        github_repository,
-        require_github_authentication,
-        github_api_json,
-        require_pull_request_shape,
-        require_pull_request_pages,
-        pull_request_head_matches_repository,
-        require_pull_request_identity,
-        find_pull_request,
-        pull_request_body,
-        update_pull_request_body,
-        create_pull_request,
-        pull_request_tag_message,
-        pull_request_tag_metadata,
-        require_pull_request_merge,
-        require_pull_request_merge_provenance,
-        integrate_pull_request,
-        integrate,
-        find_integrate_commit,
-        validate_integrated,
-        require_published_integration,
-    )
 else:  # standalone script or sibling import
     if __name__ == "__main__":
         sys.modules.setdefault("archive_milestone", sys.modules[__name__])
@@ -351,42 +310,6 @@ else:  # standalone script or sibling import
             render_manifest,
             validate_manifest,
         )
-        from integration import (
-            resolve_remote_default,
-            live_remote_ref,
-            publish_bound_branch,
-            refresh_origin,
-            optional_ref,
-            integration_names,
-            registered_worktree,
-            remove_registered_worktree,
-            delete_integration_branch,
-            require_generated_integration_commit,
-            discard_unpublished_stale_integration,
-            create_integration_merge,
-            require_annotated_tag,
-            ensure_integration_tag,
-            github_repository,
-            require_github_authentication,
-            github_api_json,
-            require_pull_request_shape,
-            require_pull_request_pages,
-            pull_request_head_matches_repository,
-            require_pull_request_identity,
-            find_pull_request,
-            pull_request_body,
-            update_pull_request_body,
-            create_pull_request,
-            pull_request_tag_message,
-            pull_request_tag_metadata,
-            require_pull_request_merge,
-            require_pull_request_merge_provenance,
-            integrate_pull_request,
-            integrate,
-            find_integrate_commit,
-            validate_integrated,
-            require_published_integration,
-        )
     except ImportError:  # pragma: no cover - package import used by tests
         from scripts.discussion_validate import (
             record_sections,
@@ -419,42 +342,6 @@ else:  # standalone script or sibling import
             render_manifest,
             validate_manifest,
         )
-        from scripts.integration import (
-            resolve_remote_default,
-            live_remote_ref,
-            publish_bound_branch,
-            refresh_origin,
-            optional_ref,
-            integration_names,
-            registered_worktree,
-            remove_registered_worktree,
-            delete_integration_branch,
-            require_generated_integration_commit,
-            discard_unpublished_stale_integration,
-            create_integration_merge,
-            require_annotated_tag,
-            ensure_integration_tag,
-            github_repository,
-            require_github_authentication,
-            github_api_json,
-            require_pull_request_shape,
-            require_pull_request_pages,
-            pull_request_head_matches_repository,
-            require_pull_request_identity,
-            find_pull_request,
-            pull_request_body,
-            update_pull_request_body,
-            create_pull_request,
-            pull_request_tag_message,
-            pull_request_tag_metadata,
-            require_pull_request_merge,
-            require_pull_request_merge_provenance,
-            integrate_pull_request,
-            integrate,
-            find_integrate_commit,
-            validate_integrated,
-            require_published_integration,
-        )
 
 
 @contextmanager
@@ -2238,6 +2125,11 @@ def parser() -> argparse.ArgumentParser:
 def main(argv: Optional[Sequence[str]] = None) -> int:
     arguments = parser().parse_args(argv)
     try:
+        if arguments.command in {"validate-integrated", "refresh-origin", "integrate"}:
+            if __package__:
+                from . import integration
+            else:
+                import integration
         if arguments.command == "prepare":
             result = prepare(arguments.repo, arguments.slug)
         elif arguments.command == "render-manifest":
@@ -2247,11 +2139,11 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         elif arguments.command == "abandon":
             result = abandon(arguments.repo, arguments.slug, arguments.reason)
         elif arguments.command == "validate-integrated":
-            result = validate_integrated(arguments.repo, arguments.slug)
+            result = integration.validate_integrated(arguments.repo, arguments.slug)
         elif arguments.command == "refresh-origin":
-            result = refresh_origin(arguments.repo)
+            result = integration.refresh_origin(arguments.repo)
         elif arguments.command == "integrate":
-            result = integrate(arguments.repo, arguments.slug)
+            result = integration.integrate(arguments.repo, arguments.slug)
         else:
             result = validate(arguments.repo)
     except (ArchiveError, OSError) as error: