@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/path/references/reviewer.md

@@ -17,159 +17,23 @@ 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
+## Load the assigned mode
 
-Use task acceptance criteria and the INTENT.md success criteria owned by
-tasks in this wave as the rubric. For each task:
+Read only the row matching the brief. Common rules below apply to every mode.
+Resolve sibling links against this role file's directory.
 
-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.
+| 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
 
+- When `GSD_PATH_JEV=1`, wave and final reviewers follow the optional
+  [Jev evidence screening procedure](jev-review.md) for uncovered criteria.
 - Review written expectations, not preferences or alternate designs.
 - Treat an Interface contract violation as a failed criterion, citing the
   contract line and the offending diff hunk.

package/skills/path/references/runtime-selection.md

@@ -0,0 +1,25 @@
+# Project runtime selection
+
+Before running a project runtime helper, check for
+`<absolute-project>/.gsd-path/runtime.json`. When present, run the stable launcher:
+
+```sh
+python3 -B <absolute-project>/.gsd-path/status_runtime.py --repo <absolute-project> --runtime-path
+```
+
+Use `python` only when it is the compatible Python 3.9+ interpreter. A failure
+stops helper execution: follow the exact-version restore action in the error.
+Do not install, upgrade, or fall back to the current plugin's runtime implicitly.
+
+The returned directory is the verified Project runtime. Resolve helper names
+present in its `manifest.json` from that directory, including status, state,
+isolation, integration, archive, recovery, build-state, final-verification, and guard helpers.
+The workflow runner resolves its subprocess helpers from this same directory;
+helper imports stay within the selected runtime. This rule overrides
+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.
+
+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/path/scripts/_common.py

@@ -9,6 +9,11 @@ consuming module keep working.
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import os
 import re

package/skills/path/scripts/archive_milestone.py

@@ -16,6 +16,9 @@ import re
 import shutil
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from contextlib import contextmanager
 from datetime import date
 from pathlib import Path, PurePosixPath
@@ -239,15 +242,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 +278,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 +313,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 +345,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
@@ -1856,6 +1746,12 @@ def require_clean_active_root(active_root: Path, archive: Path) -> None:
     carried_forward = pending_ruling_count(archived_audit)
     # Persistent project metadata ships but never archives with a milestone.
     allowed = {"STATE.md", "REPOSITORY.md", "archive", "LESSONS.md", "next"}
+    for name in ("config.json", "model-policy.json"):
+        path = active_root / name
+        if path.exists() or path.is_symlink():
+            if path.is_symlink() or not path.is_file() or path.stat().st_nlink != 1:
+                raise ArchiveError(f"project settings must be a regular unlinked file: {path}")
+            allowed.add(name)
     if (active_root / "CHARTER.md").is_file():
         # Program flow: these persist at the .project/ top level.
         allowed |= {"CHARTER.md", "ROADMAP.md", "SYNTHESIS.md"}
@@ -1921,6 +1817,7 @@ def prepared_transaction(
     repo: Path,
     phases: Sequence[str],
     must_be_uncommitted: bool = False,
+    *, historical: bool = False,
 ) -> tuple:
     project = repo.resolve()
     active_root = require_project_layout(project)
@@ -1929,7 +1826,7 @@ def prepared_transaction(
     state, _, loaded_state_path = strict_state(project)
     if loaded_state_path.resolve() != state_path.resolve():
         raise ArchiveError("strict STATE.md loader returned an unexpected path")
-    require_transaction_context(project, state, phases)
+    require_transaction_context(project, state, phases, historical=historical)
 
     configured = state.archive
     if configured is None:
@@ -1993,10 +1890,11 @@ def require_canonical_commit_body(
         raise ArchiveError(f"{label} commit body does not match required fields")
 
 
-def find_ship_commit(project: Path, archive_name: str) -> str:
+def find_ship_commit(project: Path, archive_name: str, *, historical: bool = False) -> str:
     expected_subject = ship_subject(archive_name)
     log = require_git_success(
-        run_git(project, "log", "--first-parent", "--format=%H%x00%s", "HEAD"),
+        run_git(project, "log", *([] if historical else ["--first-parent"]),
+                "--format=%H%x00%s", "HEAD"),
         "inspect HEAD history for the ship commit",
     )
     matches = []
@@ -2039,19 +1937,22 @@ def validate_shipped_roadmap(text: str, state: PipelineState, archive: str) -> N
         raise ArchiveError("ROADMAP.md must record Status: shipped and the exact Archive")
 
 
-def validate(repo: Path) -> dict:
+def validate(repo: Path, *, historical: bool = False) -> dict:
     project, _, state, configured, archive, archived_files, reviewed_head = prepared_transaction(
         repo,
         ("shipped",),
+        historical=historical,
     )
     if state.status != "done":
         raise ArchiveError("STATE.md is not shipped/done")
 
-    project_status = require_git_success(run_git(project, "status", "--porcelain"), "inspect worktree status")
+    project_status = require_git_success(
+        run_git(project, "status", "--porcelain", *(["--", ".project"] if historical else [])),
+        "inspect worktree status")
     if project_status:
         raise ArchiveError("ship transaction worktree is not clean")
 
-    ship_commit = find_ship_commit(project, archive.name)
+    ship_commit = find_ship_commit(project, archive.name, historical=historical)
 
     parents = require_git_success(
         run_git(project, "rev-list", "--parents", "-n", "1", ship_commit),
@@ -2238,6 +2139,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 +2153,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:

package/skills/path/scripts/bootstrap_repository.py

@@ -32,6 +32,7 @@ class BootstrapRequest:
     worktree: str
     branch: str
     description: Optional[str]
+    reuse_empty_worktree: bool = False
 
     @property
     def repository(self) -> str:
@@ -95,6 +96,8 @@ def request_from_arguments(arguments: argparse.Namespace) -> BootstrapRequest:
     if arguments.visibility not in {"public", "private", "internal"}:
         raise BootstrapError("visibility must be public, private, or internal")
 
+    if arguments.reuse_empty_worktree and arguments.worktree.is_symlink():
+        raise BootstrapError("linked worktree must not be a symlink")
     workspace = arguments.workspace.resolve()
     checkout = arguments.default_checkout.resolve()
     worktree = arguments.worktree.resolve()
@@ -116,6 +119,7 @@ def request_from_arguments(arguments: argparse.Namespace) -> BootstrapRequest:
         worktree=str(worktree),
         branch="gsd-path/M001",
         description=arguments.description,
+        reuse_empty_worktree=arguments.reuse_empty_worktree,
     )
 
 
@@ -148,7 +152,10 @@ def transaction_directory(request: BootstrapRequest, create: bool = False) -> Pa
 
 
 def request_payload(request: BootstrapRequest) -> dict:
-    return {"schema": "gsd-path/new-github/v1", **asdict(request)}
+    payload = {"schema": "gsd-path/new-github/v1", **asdict(request)}
+    if not request.reuse_empty_worktree:
+        del payload["reuse_empty_worktree"]
+    return payload
 
 
 def read_journal(request: BootstrapRequest) -> Optional[dict]:
@@ -272,6 +279,16 @@ def transaction_stages(request: BootstrapRequest) -> dict:
     }
 
 
+def reusable_empty_worktree(request: BootstrapRequest) -> bool:
+    path = request.worktree_path
+    return (
+        request.reuse_empty_worktree
+        and not path.is_symlink()
+        and path.is_dir()
+        and not any(path.iterdir())
+    )
+
+
 def preview(request: BootstrapRequest) -> dict:
     gh_authentication()
     stages = transaction_stages(request)
@@ -288,8 +305,12 @@ def preview(request: BootstrapRequest) -> dict:
         ("default checkout", request.checkout_path),
         ("linked worktree", request.worktree_path),
     ):
+        if path == request.worktree_path and reusable_empty_worktree(request):
+            continue
         if path.exists() or path.is_symlink():
-            raise BootstrapError(f"{label} path already exists: {path}")
+            raise BootstrapError(
+                f"{label} path already exists: {path}; preserve it and choose another path"
+            )
     return {**request_payload(request), "mode": "create", "stages": stages}
 
 
@@ -448,7 +469,7 @@ def allowed_partial_project_status(worktree: Path) -> bool:
 def create_or_verify_worktree(request: BootstrapRequest, base: str) -> None:
     checkout = request.checkout_path
     worktree = request.worktree_path
-    if not worktree.exists():
+    if not worktree.exists() or reusable_empty_worktree(request):
         branch_ref = f"refs/heads/{request.branch}"
         branch = run("git", "-C", str(checkout), "rev-parse", "--verify", branch_ref)
         if branch.returncode == 0:
@@ -540,7 +561,14 @@ def render_state(template: Path, request: BootstrapRequest) -> str:
     )
     if "<slug>" in content or "branch: null" in content:
         raise BootstrapError("state template placeholders were not fully replaced")
-    return content
+    try:
+        from .path_config import initial_state
+    except ImportError:
+        from path_config import initial_state
+    try:
+        return initial_state(content)
+    except (OSError, ValueError, RuntimeError) as error:
+        raise BootstrapError(str(error)) from error
 
 
 def render_binding(
@@ -680,6 +708,7 @@ def parser() -> argparse.ArgumentParser:
     argument_parser.add_argument("--default-checkout", type=Path, required=True)
     argument_parser.add_argument("--worktree", type=Path, required=True)
     argument_parser.add_argument("--description")
+    argument_parser.add_argument("--reuse-empty-worktree", action="store_true")
     argument_parser.add_argument("--state-template", type=Path)
     argument_parser.add_argument("--repository-template", type=Path)
     return argument_parser