@opengsd/gsd-path 1.0.0 → 1.2.0

package/skills/gsd-path-decide/scripts/state_promote.py

@@ -4,6 +4,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil
@@ -11,6 +16,31 @@ from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional
 
 
+if __package__:  # imported as scripts.state_promote
+    from . import pipeline_state, state_checkpoint
+    from .pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+else:  # standalone script or sibling import
+    import pipeline_state
+    import state_checkpoint
+    from pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+
+
 def _render_roadmap(
     text: str,
     previous_milestone: str,
@@ -243,9 +273,9 @@ def _completed_promotion(
     if _head_with_exact_message(repo, subject, fields) != head:
         raise PipelineStateError("completed promotion has the wrong commit message")
 
-    active_text = pipeline_state._git_text_at(repo, base, ".project/STATE.md")
-    next_text = pipeline_state._git_text_at(repo, base, ".project/next/STATE.md")
-    roadmap_text = pipeline_state._git_text_at(repo, base, ".project/ROADMAP.md")
+    active_text = state_checkpoint._git_text_at(repo, base, ".project/STATE.md")
+    next_text = state_checkpoint._git_text_at(repo, base, ".project/next/STATE.md")
+    roadmap_text = state_checkpoint._git_text_at(repo, base, ".project/ROADMAP.md")
     if active_text is None or next_text is None or roadmap_text is None:
         raise PipelineStateError("promotion parent is missing required metadata")
     active_state = pipeline_state._state_from_text(active_text, "promotion parent STATE.md")
@@ -265,7 +295,7 @@ def _completed_promotion(
         )
 
     _promotion_tree_mapping(repo, base, head)
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     expected_roadmap = _render_roadmap(
         roadmap_text,
         active_state.milestone,
@@ -273,11 +303,11 @@ def _completed_promotion(
         branch,
         landing,
     )
-    current_roadmap = pipeline_state._git_text_at(repo, head, ".project/ROADMAP.md")
+    current_roadmap = state_checkpoint._git_text_at(repo, head, ".project/ROADMAP.md")
     if current_roadmap != expected_roadmap:
         raise PipelineStateError("completed promotion has invalid ROADMAP.md")
 
-    current_state = pipeline_state._git_text_at(repo, head, ".project/STATE.md")
+    current_state = state_checkpoint._git_text_at(repo, head, ".project/STATE.md")
     if current_state is None:
         raise PipelineStateError("completed promotion has no STATE.md")
     event = re.escape(_promotion_event(drift, branch, landing, base))
@@ -438,10 +468,10 @@ def _prepare_promotion(
         if source.exists() or source.is_symlink():
             if destination.exists() or destination.is_symlink():
                 raise PipelineStateError(f"promotion destination already exists: {destination}")
-            tracks[name] = pipeline_state._tree_digest(source)
+            tracks[name] = state_checkpoint._tree_digest(source)
     if not tracks:
         raise PipelineStateError("lookahead track has no promotable artifacts")
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     roadmap_path = project / "ROADMAP.md"
     roadmap_text = pipeline_state._read_real_file(roadmap_path, "ROADMAP.md")
     target_state = _promotion_state(
@@ -464,10 +494,10 @@ def _prepare_promotion(
         "landing": landing,
         "base": base,
         "tracks": tracks,
-        "residual_sha256": pipeline_state._tree_digest(next_root, tuple(tracks)),
-        "next_state_sha256": pipeline_state._sha256(next_text),
-        "active_state_sha256": pipeline_state._sha256(active_text),
-        "roadmap_sha256": pipeline_state._sha256(roadmap_text),
+        "residual_sha256": state_checkpoint._tree_digest(next_root, tuple(tracks)),
+        "next_state_sha256": state_checkpoint._sha256(next_text),
+        "active_state_sha256": state_checkpoint._sha256(active_text),
+        "roadmap_sha256": state_checkpoint._sha256(roadmap_text),
         "target_state": target_state,
         "target_roadmap": target_roadmap,
         "drift": drift,
@@ -521,7 +551,7 @@ def _resume_track_moves(project: Path, journal: dict[str, object], path: Path) -
         if not source_exists and not destination_exists:
             raise PipelineStateError(f"promotion lost both source and destination: {name}")
         candidate = source if source_exists else destination
-        if pipeline_state._tree_digest(candidate) != expected_digest:
+        if state_checkpoint._tree_digest(candidate) != expected_digest:
             raise PipelineStateError(f"promotion track drifted: {name}")
         if source_exists:
             source.rename(destination)
@@ -542,7 +572,7 @@ def _resume_metadata(project: Path, journal: dict[str, object], path: Path) -> N
             raise PipelineStateError("promotion journal has invalid metadata")
         if current == desired:
             continue
-        if pipeline_state._sha256(current) != expected_original:
+        if state_checkpoint._sha256(current) != expected_original:
             raise PipelineStateError(f"promotion metadata drifted: {target}")
         pipeline_state._atomic_write(target, desired)
         journal["stage"] = f"updated:{target.name}"
@@ -560,9 +590,9 @@ def _resume_next_removal(
         if residual.exists() or residual.is_symlink():
             raise PipelineStateError("promotion has both next track and residual staging")
         next_text = pipeline_state._read_real_file(next_root / "STATE.md", "next/STATE.md")
-        if pipeline_state._sha256(next_text) != journal.get("next_state_sha256"):
+        if state_checkpoint._sha256(next_text) != journal.get("next_state_sha256"):
             raise PipelineStateError("lookahead STATE drifted during promotion")
-        if pipeline_state._tree_digest(next_root) != journal.get("residual_sha256"):
+        if state_checkpoint._tree_digest(next_root) != journal.get("residual_sha256"):
             raise PipelineStateError("lookahead residual drifted during promotion")
         next_root.rename(residual)
         journal["stage"] = "next-staged"
@@ -574,7 +604,7 @@ def _resume_next_removal(
         raise PipelineStateError("promotion lost next track and residual staging")
     if residual.is_symlink() or not residual.is_dir():
         raise PipelineStateError(f"promotion residual must be a real directory: {residual}")
-    if pipeline_state._tree_digest(residual) != journal.get("residual_sha256"):
+    if state_checkpoint._tree_digest(residual) != journal.get("residual_sha256"):
         raise PipelineStateError("staged lookahead residual drifted during promotion")
 
 
@@ -714,30 +744,3 @@ def promote_next(
         "commit": commit,
         "drift": journal["drift"],
     }
-
-
-# pipeline_state imports this module, so the parent is resolved after the
-# definitions above. Parent functions are looked up on the module at call time
-# so patches applied to pipeline_state stay visible here.
-if __package__:  # imported as scripts.state_promote
-    from . import pipeline_state
-    from .pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )
-else:  # standalone script or sibling import
-    import pipeline_state
-    from pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )

package/skills/gsd-path-decide/scripts/worktree_paths.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+# gsd-path project runtime
+"""Placement shared by task isolation, verification, and integration."""
+
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
+import hashlib
+import json
+import os
+import tempfile
+from pathlib import Path
+
+try:
+    import _common
+except ImportError:
+    from scripts import _common
+
+
+def _git(primary: Path, *args: str) -> str:
+    result = _common.run_git(primary, *args)
+    if result.returncode:
+        raise ValueError(result.stderr.strip() or "cannot inspect worktree placement")
+    return result.stdout.rstrip("\n")
+
+
+def _identity(path: Path) -> str:
+    return hashlib.sha256(os.fsencode(path)).hexdigest()
+
+
+def _workspace(primary: Path, pin: bool) -> Path:
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    identity = _identity(primary)
+    receipt = common / "gsd-path" / "workspaces" / f"{identity}.json"
+    try:
+        data = json.loads(receipt.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        pass
+    else:
+        if (not isinstance(data, dict) or data.get("primary") != str(primary)
+                or not isinstance(data.get("root"), str)
+                or not Path(data["root"]).is_absolute()):
+            raise ValueError(f"invalid worktree placement receipt: {receipt}")
+        return Path(data["root"])
+
+    root = Path(os.environ.get("GSD_PATH_WORKTREE_ROOT") or Path.home() / ".gsd-path" / "projects").expanduser()
+    if not root.is_absolute():
+        raise ValueError("GSD_PATH_WORKTREE_ROOT must be absolute")
+    root = root.resolve()
+    parent = root
+    while not parent.exists():
+        parent = parent.parent
+    ancestor = _common.run_git(parent, "rev-parse", "--git-common-dir")
+    same_repository = (
+        ancestor.returncode == 0
+        and (parent / ancestor.stdout.strip()).resolve() == common
+    )
+    if root.is_relative_to(primary) or same_repository:
+        raise ValueError(f"managed worktree root must be outside this repository's worktrees: {root}")
+    workspace = root / _identity(common) / identity
+    if pin:
+        receipt.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(dir=receipt.parent)
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                json.dump({"primary": str(primary), "root": str(workspace)}, handle)
+            try:
+                os.link(temporary, receipt)
+            except FileExistsError:
+                return _workspace(primary, False)
+        finally:
+            os.unlink(temporary)
+    return workspace
+
+
+def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
+    primary = primary.resolve()
+    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+        raise ValueError("invalid managed worktree kind or name")
+    legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
+              if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
+    branch = f"refs/heads/gsd-path-{kind}/{name}"
+    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    for record in records:
+        fields = record.split("\0")
+        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+            return legacy
+    # Keep collision checks and missing-directory recovery at the old location.
+    if os.path.lexists(legacy):
+        return legacy
+    return _workspace(primary, pin) / kind / name

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

@@ -3,6 +3,8 @@ name: gsd-path-define
 description: Define and approve project or milestone intent through an interview or milestone confirmation, writing .project/CHARTER.md or .project/intent/INTENT.md. Use only when the user explicitly invokes $gsd-path-define or an active $gsd-path router explicitly routes to this phase.
 ---
 
+Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+
 # GSD Path Define Phase
 
 Turn a project idea or approved roadmap entry into an approved intent artifact.
@@ -36,16 +38,22 @@ ROADMAP.md exists), `roadmap/done`
 lookahead track at `define/active|blocked` also requires both current-track
 inspection artifacts and a Log entry proving `inspect/done` for the same
 milestone after its latest activation; otherwise route to inspect.
+The sole later-phase exception is a blocked build entered through the
+[build recovery contract](references/build-recovery.md). Follow its preparation
+and corrections procedure when the runtime returns mode `corrections`; keep
+the existing milestone identity and approval gate. Otherwise
 `define/done` or any later phase blocks rather than overwriting approved
 intent and leaving downstream artifacts stale. When an active router supplies
 the lookahead track root `.project/next/`, require its STATE.md to be a regular
 non-symlink file and evaluate this section against that track's state and
 paths; see Lookahead mode. If STATE.md is missing, run the bundled
 `python3 <absolute-bundled-script> initialize --repo <absolute-root>
---template <absolute-state-template>` helper (`scripts/detect_project.py`) and
+--template <absolute-state-template> --require-git` helper (`scripts/detect_project.py`) and
 follow its returned JSON `verdict` / `route`. This is the only no-state
 boundary; do not run `classify` first or classify from a directory listing or
-conversation. If the command exits nonzero, returns `error`, or returns
+conversation. Handle `route: setup-repository` before the write gate: preserve
+the folder unchanged and return to `$gsd-path` for repository setup; no state
+was written. If the command exits nonzero, returns `error`, or returns
 `wrote_state: false`, report the error and block without routing or claiming
 STATE.md was written.
 - `owned` — continue under the existing-state rules above.
@@ -104,12 +112,13 @@ the charter instead of the single-milestone checklist:
 4. **Constraints** — program-level stack, budget, deadline, integrations.
 5. **Program success criteria** — observable when the last milestone ships.
 6. **Review panel** — optional durable default (`off` | `detected` | named
-   families). Default `off`. This value persists on CHARTER.md; later
+   families). Use the configured future preference unless the user chooses
+   otherwise (see Output contract). This value persists on CHARTER.md; later
    milestone INTENT files copy it and may override.
 
 Read the local [charter template](templates/charter.md), write the approval
-draft to `.project/CHARTER.md` including `Review panel:` (default `off`;
-never invent `detected` or a named list), and run the same playback-approval
+draft to `.project/CHARTER.md` including the configured or explicitly chosen
+`Review panel:` value, and run the same playback-approval
 loop as the standard Process. On approval, retain the reviewed
 `Review panel:` value on CHARTER.md, run `pipeline_state.py transition` with
 expected `define/active`, milestone/branch/archive all at their exact current
@@ -138,7 +147,7 @@ State ownership. There is no re-interview of charter or roadmap scope:
    Risks and Open questions from the entry (tagged `RESEARCH`/`NEEDS-USER`),
    `Lane: milestone`, `Surfaces:` copied verbatim from the entry, and
    `Review panel:` copied from CHARTER.md (default
-   `off` when CHARTER omits it). The confirmation may override the copied
+   the configured preference when CHARTER omits it). The confirmation may override the copied
    panel value; do not invent `detected` or a named list. When brownfield,
    fill `## Current state` from the map, record doc-vs-code rulings as in
    Brownfield mode, and add protected existing behavior under Scope out.
@@ -265,27 +274,20 @@ question. The rules change for every primary mode:
 ## Output contract
 
 At approval, retain the already reviewed `Lane:` value and its one-line reason.
-Retain `Review panel:` as reviewed: the CHARTER copy or the user's override
-in milestone/lookahead mode, the CHARTER value in program mode, or `off`
-when the user did not choose a panel and no CHARTER default exists.
+Before presenting an approval draft without a CHARTER or explicit panel choice,
+read `settings.review_panel.value` from the selected runtime's `path_config.py
+show --repo <absolute-root>` (bundle for legacy projects; off for older selected
+runtimes without config support). Include that preference in the draft.
+Retain `Review panel:` as reviewed: the CHARTER copy, the explicit user choice,
+or the configured future preference. Quick lane keeps the panel off.
 
 After approval, finalize `.project/intent/INTENT.md` and run
 `pipeline_state.py transition` with expected `define/active`, the exact
 current milestone/branch/archive values, event `milestone intent approved`,
 `--set-phase define --set-status done --set-milestone <milestone slug>`, and
 `--project-dir .project/next` in lookahead. Require returned `define/done` and
-the exact milestone. Report the next phase
-from the approved lane. For `Lane: standard`, research is next. For
-`Lane: quick`, planning is next and research and decide are skipped. For
-`Lane: milestone`, use the resolved roadmap entry matching the track STATE's
-`milestone`: milestone-scoped research is next when that entry lists open
-questions; otherwise planning is next and research and decide are skipped.
-Confirm the approved outcome, link the final INTENT.md again, and name that
-next phase before routing. When routed by an active `$gsd-path`, return control
-to that router so its bundled next contract can auto-advance to the named
-phase. When invoked directly, stop and tell the user to explicitly invoke
-`$gsd-path`, which selects that next phase; do not invoke an explicit-only
-sibling skill yourself.
+the exact milestone. Confirm the approved outcome and link INTENT.md again.
+Use the executable phase handoff in AGENTS.md for the next action.
 
 ## Rules
 

package/skills/gsd-path-define/references/build-recovery.md

@@ -0,0 +1,78 @@
+# Return a blocked build to its contract owner
+
+Use this contract only for an active milestone at `build/blocked`: a documented
+structural plan defect, or an explicit user ruling that changes approved intent.
+It does not reopen ship, archived milestones, or lookahead. Build owns entry;
+Define owns intent corrections; Plan owns the replacement task inventory and
+approval. Routing remains a caller handoff under AGENTS.md.
+
+## Build: checkpoint and enter
+
+1. Record the finding or verbatim user ruling in STATE through its helper.
+   Stop dispatch. Use the normal recovery and retirement procedures until
+   every task is either unstarted `pending` with null dispatch metadata or
+   proven `done`. Preserve owned uncommitted work before any retirement.
+   Settle reviewers and their sidecars too. Dispatch records must have no pending
+   cleanup; records with reviewer `worktree` and `branch` ownership must also
+   record `cleanup_complete`. A `blocked` or `collected` outcome alone does not
+   prove retirement. Records that never owned a reviewer sidecar do not require
+   that retirement receipt. Use the existing dispatch retirement procedures;
+   recovery does not retire sidecars itself. Never infer that a timed-out child
+   stopped. Checkpoint the blocked state and artifacts using the Build
+   bookkeeping contract; the primary must be clean.
+2. Run `pipeline_state.py transition` with the complete current state expected,
+   `--set-status active`, and the matching target and event:
+
+   | Cause | Target | Exact event |
+   | --- | --- | --- |
+   | User changes a criterion, constraint, or veto | `--set-phase define` | `build intent corrections requested` |
+   | Task inventory, dependency, or wave repair | `--set-phase plan` | `build plan repair requested` |
+
+   The helper records the committed recovery base in STATE atomically. Do not
+   author or edit that record. Milestone, branch, integration settings, and
+   landed task contracts remain fixed throughout recovery.
+3. Return to the router or name the selected explicit skill. The route names
+   `corrections` for Define and `build-repair` for Plan. Other blocked-build
+   failures continue through ordinary Build recovery.
+
+## Define and Plan: prepare before editing
+
+Run the bundled `pipeline_state.py prepare-build-recovery --repo <absolute-root>`
+before changing any recovery artifact. This repeatable operation preserves the
+old review directory under `plan/build-recovery-<base>/review` and starts a fresh
+active review directory. STATE's recorded base owns an interrupted move; rerun
+this command to finish it. The helper validates the preserved bytes against Git.
+Do not remove, rewrite, or use the preserved reviews as current approval.
+
+**Define corrections.** Read the existing intent and governing program artifacts.
+Interview only the requested change; append the user's words under
+`## Corrections`, revise the affected intent, and present the delta for approval.
+Keep the milestone identity. Reclassify the lane using the normal lane rules.
+After approval, use the normal `define/active → define/done` transition and route
+from the approved lane. Standard intent goes through Research and Decide again;
+quick and milestone intent use their existing evidence gates. A program charter
+or roadmap conflict still requires its legal owner gate; this path cannot waive it.
+
+**Plan build-repair.** Read the corrected intent, current synthesis, existing plan,
+task files, and recovery base. Use the normal planner, lint, panel, and approval
+gates. Repair the remaining task inventory as needed, including split, rename,
+dependency, or wave changes. Keep IDs ordered and contiguous. Preserve every
+landed task file byte-for-byte, including its recorded base and proof. Any new
+work to satisfy a corrected criterion belongs in new pending tasks, not rewritten
+landed contracts. A plan-only recovery must not change approved intent.
+
+## Approve and return to Build
+
+Use normal `pipeline_state.py approve --kind plan --expected-head <HEAD>`.
+Neither `--patch` nor `--defer-checkpoint` is legal for recovery. The helper
+checks landed-task preservation and restored intent ownership, restores review
+evidence only for unchanged contracts, and creates the normal journaled plan
+checkpoint. A failed approval leaves recovery open.
+
+Return through `plan/done → build/active` with event `build started`. The dispatch
+driver uses a separate record directory for this recovery base, while retaining
+the milestone budget ledger. Resume only from the new approved task inventory.
+Unchanged wave evidence remains usable; changed waves need review in the new
+record directory. Retained task Verify receipts remain historical evidence for
+their original task and base, never proof for a changed task. Final review still
+requires current-HEAD evidence before shipment.

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