@opengsd/gsd-path 1.1.0 → 1.3.0

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.
@@ -110,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
@@ -144,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.
@@ -271,9 +274,12 @@ 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

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

package/skills/gsd-path-define/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
@@ -1743,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"}
@@ -1808,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)
@@ -1816,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:
@@ -1880,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 = []
@@ -1926,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),

package/skills/gsd-path-define/scripts/build_recovery.py

@@ -3,6 +3,11 @@
 
 from __future__ import annotations
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 from pathlib import Path

package/skills/gsd-path-define/scripts/check_handoffs.py

@@ -7,6 +7,9 @@ import json
 import re
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
@@ -131,6 +134,9 @@ def _strict_frontmatter(text: str, label: str) -> Dict[str, object]:
     while index < len(lines):
         line = lines[index]
         if line == "---":
+            for field in ('model', 'effort'):
+                if field in values and (not isinstance(values[field], str) or not values[field].strip()):
+                    raise HandoffError(f'{label}: {field} must be a nonempty scalar or inherit')
             return values
         if not line.strip() or line.lstrip().startswith("#"):
             index += 1

package/skills/gsd-path-define/scripts/check_task_briefs.py

@@ -6,6 +6,9 @@ import argparse
 import json
 import re
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 

package/skills/gsd-path-define/scripts/detect_project.py

@@ -34,6 +34,9 @@ import re
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 from datetime import date
 from pathlib import Path, PurePosixPath, PureWindowsPath
 from typing import Iterable, NamedTuple, Optional, Sequence
@@ -1200,7 +1203,14 @@ def filled_state_template(template: str, slug: str, phase: str) -> str:
     text = text.replace("YYYY-MM-DD — <phase> — project initialized", stamp)
     if "<slug>" in text or "YYYY-MM-DD" in text:
         raise DetectError("state template placeholder remains")
-    return text
+    try:
+        from .path_config import initial_state
+    except ImportError:
+        from path_config import initial_state
+    try:
+        return initial_state(text)
+    except (OSError, ValueError, RuntimeError) as error:
+        raise DetectError(str(error)) from error
 
 
 def write_all(descriptor: int, payload: bytes) -> None:

package/skills/gsd-path-define/scripts/discussion_records.py

@@ -7,6 +7,9 @@ import json
 import os
 import shutil
 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

package/skills/gsd-path-define/scripts/discussion_validate.py

@@ -2,6 +2,11 @@
 # gsd-path project runtime
 """Validate discussion records, reviews and the manifest for archive_milestone."""
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 import shutil
@@ -409,7 +414,7 @@ def remove_interrupted_carry_copy(active_root: Path, archive: Path) -> None:
 
 
 def require_transaction_context(
-    project: Path, state: PipelineState, phases: Sequence[str]
+    project: Path, state: PipelineState, phases: Sequence[str], *, historical: bool = False
 ) -> None:
     phase = state.phase
     if phase not in phases:
@@ -429,7 +434,7 @@ def require_transaction_context(
     )
     if archive_milestone.is_unset(expected_branch):
         raise ArchiveError("STATE.md does not name a bound build branch")
-    if current_branch != expected_branch:
+    if current_branch != expected_branch and not historical:
         raise ArchiveError(
             f"current branch {current_branch!r} does not match STATE.branch {expected_branch!r}"
         )
@@ -446,7 +451,7 @@ def require_transaction_context(
         ),
         "inspect non-project worktree status",
     )
-    if non_project_status:
+    if non_project_status and not historical:
         raise ArchiveError("non-.project worktree changes block the archive transaction")
 
 

package/skills/gsd-path-define/scripts/integration.py

@@ -2,6 +2,11 @@
 # gsd-path project runtime
 """Own milestone integration, publication, tags, and completion proof."""
 
+import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
+
 import json
 import re
 from pathlib import Path, PurePosixPath
@@ -21,6 +26,7 @@ try:
     from pipeline_state import PipelineState
     from isolation import publication_base
     import _common
+    import worktree_paths
 except ImportError:  # pragma: no cover - package import used by tests
     from scripts.pipeline_git import (
         bound_branch_name,
@@ -35,6 +41,7 @@ except ImportError:  # pragma: no cover - package import used by tests
     from scripts.pipeline_state import PipelineState
     from scripts.isolation import publication_base
     from scripts import _common
+    from scripts import worktree_paths
 
 
 if __package__:
@@ -156,10 +163,13 @@ def optional_ref(project: Path, ref: str) -> Optional[str]:
     return result.stdout.strip() if result.returncode == 0 else None
 
 
-def integration_names(project: Path, archive_name: str) -> tuple[str, Path]:
+def integration_names(project: Path, archive_name: str, *, pin: bool = False) -> tuple[str, Path]:
     identifier = milestone_id(milestone_number(archive_name))
     branch = f"gsd-path-integrate/{identifier}"
-    worktree = project.parent / f".{project.name}-gsd-path-integrate-{identifier}"
+    try:
+        worktree = worktree_paths.worktree_path(project, "integrate", identifier, pin=pin)
+    except (ValueError, OSError) as error:
+        raise ArchiveError(str(error)) from error
     return branch, worktree
 
 
@@ -1044,7 +1054,7 @@ def integrate(repo: Path, slug: str) -> dict:
             ship_commit,
         )
     publishable_bound_branch(project, bound_branch, ship_commit)
-    integration_branch, worktree = integration_names(project, archive_name)
+    integration_branch, worktree = integration_names(project, archive_name, pin=True)
     interrupted_worktree = registered_worktree(project, integration_branch)
     if (
         interrupted_worktree is not None
@@ -1222,7 +1232,9 @@ def find_integrate_commit(
     return merge_commit
 
 
-def validate_integrated(repo: Path, slug: str, *, refresh: bool = True) -> dict:
+def validate_integrated(
+    repo: Path, slug: str, *, refresh: bool = True, historical: bool = False
+) -> dict:
     project = repo.resolve()
     active_root = archive_milestone.require_project_layout(project)
     state, _, loaded_state_path = archive_milestone.strict_state(project)
@@ -1235,7 +1247,7 @@ def validate_integrated(repo: Path, slug: str, *, refresh: bool = True) -> dict:
         )
 
     # (a) The shipped transaction itself must still validate.
-    shipped = archive_milestone.validate(repo)
+    shipped = archive_milestone.validate(repo, historical=historical)
     configured = shipped["archive"]
     ship_commit = shipped["commit"]
     archive_name = PurePosixPath(configured).name
@@ -1340,6 +1352,10 @@ def validate_integrated(repo: Path, slug: str, *, refresh: bool = True) -> dict:
     contains = run_git(project, "merge-base", "--is-ancestor", merge_commit, remote_default)
     if contains.returncode != 0:
         raise ArchiveError(f"{remote_default} does not contain the integration merge")
+    if (historical
+            and run_git(project, "branch", "--show-current").stdout.strip() != bound_branch
+            and run_git(project, "merge-base", "--is-ancestor", merge_commit, "HEAD").returncode):
+        raise ArchiveError("HEAD does not contain the integration merge")
 
     # (e) The bound branch tip and annotated tag must be published on origin.
     require_published_integration(
@@ -1348,7 +1364,8 @@ def validate_integrated(repo: Path, slug: str, *, refresh: bool = True) -> dict:
         ship_commit,
         tag_name,
         merge_commit,
-        allow_missing_bound=state.integration == "pull-request",
+        allow_missing_bound=state.integration == "pull-request" or (historical and has_origin),
+        retired=historical,
     )
 
     result = {
@@ -1369,7 +1386,9 @@ def validate_integrated(repo: Path, slug: str, *, refresh: bool = True) -> dict:
         refs = [(f"refs/heads/{default_name}", result["base"]),
                 (f"refs/tags/{tag_name}", optional_ref(project, tag_ref))]
         if state.integration == "direct":
-            refs.append((f"refs/heads/{bound_branch}", ship_commit))
+            bound_ref = f"refs/heads/{bound_branch}"
+            if not historical or live_remote_ref(project, bound_ref) is not None:
+                refs.append((bound_ref, ship_commit))
         for ref, expected in refs:
             if live_remote_ref(project, ref) != expected:
                 raise ArchiveError(f"published {ref} differs from local integration evidence")
@@ -1385,6 +1404,7 @@ def require_published_integration(
     tag_name: str,
     merge_commit: str,
     allow_missing_bound: bool = False,
+    retired: bool = False,
 ) -> None:
     if allow_missing_bound:
         published_ship = live_remote_ref(project, f"refs/heads/{bound_branch}")
@@ -1408,7 +1428,7 @@ def require_published_integration(
 
     bound_ref = f"refs/remotes/origin/{bound_branch}"
     if run_git(project, "rev-parse", "--verify", "--quiet", bound_ref).returncode != 0:
-        if not allow_missing_bound:
+        if not retired:
             raise ArchiveError(f"missing published bound branch: origin/{bound_branch}")
     else:
         published_ship = archive_milestone.require_git_success(

package/skills/gsd-path-define/scripts/isolation.py

@@ -18,6 +18,9 @@ import re
 import stat
 import subprocess
 import sys
+
+# Runtime helpers must not modify their immutable installation.
+sys.dont_write_bytecode = True
 import tempfile
 from pathlib import Path, PurePosixPath
 from typing import Dict, Optional, Sequence, Set
@@ -33,6 +36,7 @@ try:
         task_commit_subject,
     )
     import _common
+    import worktree_paths
 except ImportError:  # pragma: no cover - package import used by tests
     from scripts.pipeline_git import (
         attest_commit_body,
@@ -44,6 +48,7 @@ except ImportError:  # pragma: no cover - package import used by tests
         task_commit_subject,
     )
     from scripts import _common
+    from scripts import worktree_paths
 
 
 TASK_BRANCH_PREFIX = "gsd-path-task/"
@@ -57,7 +62,9 @@ VERIFY_LEDGER_PATH = _common.VERIFY_LEDGER_PATH
 LANDED_VERDICTS = frozenset({"recovered", "attested"})
 # Orchestrator bookkeeping that may stay uncommitted in the primary while a
 # parallel task lands; the next `.project` checkpoint commits it.
-BOOKKEEPING_PATHS = DISCUSSION_PATHS | {VERIFY_LEDGER_PATH}
+BOOKKEEPING_PATHS = DISCUSSION_PATHS | {
+    VERIFY_LEDGER_PATH, ".project/config.json", ".project/model-policy.json",
+}
 # Bookkeeping path prefixes: pipeline records plus the guard's own install
 # artifacts. git_guard and the post-adoption proof share this one definition.
 BOOKKEEPING_PREFIXES = (
@@ -142,8 +149,11 @@ def common_git_dir(repo: Path) -> Path:
     return (repo / raw).resolve()
 
 
-def sidecar_root(primary: Path, kind: str, name: str) -> Path:
-    return primary.parent / f"{primary.name}.gsd-path" / kind / name
+def sidecar_root(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
+    try:
+        return worktree_paths.worktree_path(primary, kind, name, pin=pin)
+    except (ValueError, OSError) as error:
+        raise IsolationError(str(error)) from error
 
 
 def validate_task_id(task_id: str) -> str:
@@ -553,7 +563,7 @@ def isolate_task(
             "worktree": str(primary),
         }
     branch = task_branch_name(task_id)
-    destination = sidecar_root(primary, "task", task_id)
+    destination = sidecar_root(primary, "task", task_id, pin=True)
     create_named_worktree(primary, branch, destination, resolved_base)
     return {
         "base": resolved_base,
@@ -589,7 +599,7 @@ def isolate_verify(primary: Path, base: str, name: str, historical_task: Optiona
             + ", ".join(product_dirt)
         )
     branch = verify_branch_name(name)
-    destination = sidecar_root(primary, "verify", name)
+    destination = sidecar_root(primary, "verify", name, pin=True)
     create_named_worktree(primary, branch, destination, resolved_base)
     return {
         "base": resolved_base,