@opengsd/gsd-path 1.3.0 → 1.4.0

package/skills/gsd-path-forensics/scripts/path_config.py

@@ -174,13 +174,13 @@ def set_value(repo, scope, key, value, reset=False):
     if scope == 'project':
         state, _, _ = sibling('pipeline_state').load_state(repo)
         branch = subprocess.run(['git', '-C', str(repo), 'branch', '--show-current'],
-                                capture_output=True, text=True)
+                                capture_output=True, encoding="utf-8", errors="replace")
         if branch.returncode or not state.branch or branch.stdout.strip() != state.branch:
             raise ValueError('Run the router to bind the project branch before editing settings.')
         head = subprocess.run(['git', '-C', str(repo), 'rev-parse', '--verify', 'HEAD'], capture_output=True)
         if head.returncode == 0:
             closed = subprocess.run([sys.executable, '-B', str(Path(__file__).with_name('git_guard.py')),
-                                     'closed-milestone'], cwd=repo, capture_output=True, text=True)
+                                     'closed-milestone'], cwd=repo, capture_output=True, encoding="utf-8", errors="replace")
             if closed.returncode:
                 raise ValueError(closed.stderr.strip() or 'Cannot verify the milestone branch is open.')
     if scope == 'project' and key == 'integration':

package/skills/gsd-path-forensics/scripts/pipeline_diagnose.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import shlex
 import sys
 
@@ -20,14 +21,14 @@ from typing import Callable, Optional, Sequence
 
 
 def _load_diagnose_modules():
-    try:
-        import archive_milestone
-        import detect_project
-        import discussion_records
-        import integration
-        import isolation
-        import pipeline_git
-        import pipeline_state
+    if __package__:
+        from . import archive_milestone
+        from . import detect_project
+        from . import discussion_records
+        from . import integration
+        from . import isolation
+        from . import pipeline_git
+        from . import pipeline_state
         return (
             archive_milestone,
             detect_project,
@@ -37,17 +38,35 @@ def _load_diagnose_modules():
             pipeline_git,
             pipeline_state,
         )
-    except ModuleNotFoundError as error:
-        if error.name not in {
-            "archive_milestone",
-            "detect_project",
-            "discussion_records",
-            "integration",
-            "isolation",
-            "pipeline_git",
-            "pipeline_state",
-        }:
-            raise
+    else:
+        try:
+            import archive_milestone
+            import detect_project
+            import discussion_records
+            import integration
+            import isolation
+            import pipeline_git
+            import pipeline_state
+            return (
+                archive_milestone,
+                detect_project,
+                discussion_records,
+                integration,
+                isolation,
+                pipeline_git,
+                pipeline_state,
+            )
+        except ModuleNotFoundError as error:
+            if error.name not in {
+                "archive_milestone",
+                "detect_project",
+                "discussion_records",
+                "integration",
+                "isolation",
+                "pipeline_git",
+                "pipeline_state",
+            }:
+                raise
     try:
         from scripts import (
             archive_milestone,
@@ -116,21 +135,25 @@ _worktree_report = isolation._worktree_report
 PipelineStateError = pipeline_state.PipelineStateError
 status_state = pipeline_state.status_state
 validate_state = pipeline_state.validate_state
+_run_git = pipeline_state._run_git
 
-try:
-    import pipeline_undo
-except ModuleNotFoundError as error:
-    if error.name != "pipeline_undo":
-        raise
+if __package__:
+    from . import pipeline_undo
+else:
     try:
-        from scripts import pipeline_undo
+        import pipeline_undo
     except ModuleNotFoundError as error:
-        if error.name not in {"scripts", "scripts.pipeline_undo"}:
+        if error.name != "pipeline_undo":
             raise
-        shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
-        if str(shared) not in sys.path:
-            sys.path.insert(0, str(shared))
-        import pipeline_undo
+        try:
+            from scripts import pipeline_undo
+        except ModuleNotFoundError as error:
+            if error.name not in {"scripts", "scripts.pipeline_undo"}:
+                raise
+            shared = Path(__file__).resolve().parents[2] / "gsd-path" / "scripts"
+            if str(shared) not in sys.path:
+                sys.path.insert(0, str(shared))
+            import pipeline_undo
 
 UndoError = pipeline_undo.UndoError
 undo_preview = pipeline_undo.preview
@@ -194,7 +217,12 @@ def _state_template() -> Path:
 
 def _command(module: object, *arguments: object) -> str:
     script = Path(str(getattr(module, "__file__"))).resolve()
-    return shlex.join([sys.executable, str(script), *map(str, arguments)])
+    def text(value: object) -> str:
+        # Agents paste this into Git Bash on Windows, where unquoted
+        # backslashes are escapes; forward slashes need no quoting.
+        return value.as_posix() if isinstance(value, Path) and os.name == "nt" else str(value)
+
+    return shlex.join([text(Path(sys.executable)), text(script), *map(text, arguments)])
 
 
 def _route_retry(
@@ -391,6 +419,29 @@ def diagnose(repo: Path) -> dict[str, object]:
             for key, path in (status.get("journals") or {}).items()
             if path
         }
+        pending_members = [row["name"] for row in status.get("members") or [] if row["close"] == "pending"]
+        if pending_members:
+            findings.append(
+                _finding(
+                    "member-close",
+                    "stuck",
+                    "member close is pending for: " + ", ".join(pending_members),
+                    _command(archive_milestone, "close-members", "--repo", resolved),
+                )
+            )
+        common = _run_git(resolved, "rev-parse", "--path-format=absolute", "--git-common-dir", check=False)
+        landings = sorted(
+            (Path(common.stdout.strip()) / "gsd-path" / "member-landings").glob("*.json")
+        ) if common.returncode == 0 else []
+        if landings:
+            findings.append(
+                _finding(
+                    "member-landing",
+                    "stuck",
+                    "member landing journal is pending: " + ", ".join(path.stem for path in landings),
+                    "resume build; the dispatch driver finishes pending member landings before new work",
+                )
+            )
         undo_probe = by_name["undo-preview"]
         undo_result = undo_probe["result"] if undo_probe["ok"] else None
         route_retry = _route_retry(resolved, route, undo_result)

package/skills/gsd-path-forensics/scripts/pipeline_undo.py

@@ -25,22 +25,30 @@ from pathlib import Path, PurePosixPath
 from typing import Optional, Sequence
 
 def _load_pipeline_modules():
-    try:
-        import archive_milestone
-        import isolation
-        import pipeline_git
-        import pipeline_state
-        import state_checkpoint
+    if __package__:
+        from . import archive_milestone
+        from . import isolation
+        from . import pipeline_git
+        from . import pipeline_state
+        from . import state_checkpoint
         return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
-    except ModuleNotFoundError as error:
-        if error.name not in {
-            "archive_milestone",
-            "isolation",
-            "pipeline_git",
-            "pipeline_state",
-            "state_checkpoint",
-        }:
-            raise
+    else:
+        try:
+            import archive_milestone
+            import isolation
+            import pipeline_git
+            import pipeline_state
+            import state_checkpoint
+            return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
+        except ModuleNotFoundError as error:
+            if error.name not in {
+                "archive_milestone",
+                "isolation",
+                "pipeline_git",
+                "pipeline_state",
+                "state_checkpoint",
+            }:
+                raise
     try:
         from scripts import archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
         return archive_milestone, isolation, pipeline_git, pipeline_state, state_checkpoint
@@ -94,7 +102,7 @@ UNDO_TRANSACTION_SCHEMA = pipeline_state.UNDO_TRANSACTION_SCHEMA
 UNDO_TRANSACTION_NAME = pipeline_state.UNDO_TRANSACTION_NAME
 ROADMAP_APPROVAL_SUBJECT = "roadmap: program roadmap approved"
 TASK_SUBJECT_RE = re.compile(r"^(T\d{3,}): .+")
-KINDS = ("checkpoint", "task", "uncommitted-archive", "lookahead")
+KINDS = ("checkpoint", "task", "member-task", "uncommitted-archive", "lookahead")
 PROMOTION_PREFIX = "router: promote lookahead milestone "
 ABANDON_PREFIX = "build: abandon milestone "
 INTEGRATE_PREFIX = "integrate: "
@@ -528,6 +536,7 @@ def _prepare_transaction(
     branch: str,
     archive: Optional[str],
     discussion: Optional[dict[str, bytes]],
+    member_fields: Optional[dict[str, str]] = None,
 ) -> dict[str, object]:
     transaction = {
         "schema": UNDO_TRANSACTION_SCHEMA,
@@ -545,6 +554,8 @@ def _prepare_transaction(
         ),
         "discussion": _encode_discussion(discussion),
     }
+    if member_fields is not None:
+        transaction.update(member_fields)
     _write_json(_git_path(repo, UNDO_TRANSACTION_NAME), transaction)
     return transaction
 
@@ -641,7 +652,7 @@ def _transaction_recovery_stage(
     expected_head = str(transaction["expected_head"])
     parent = str(transaction["parent"])
     current = _optional_rev(repo, "HEAD")
-    if transaction["kind"] == "checkpoint":
+    if transaction["kind"] in {"checkpoint", "member-task"}:
         allowed = {expected_head, parent}
     else:
         allowed = {expected_head}
@@ -662,8 +673,60 @@ def _transaction_recovery_stage(
     return "reset"
 
 
+def _member_undo_parent(repo: Path, member: str, landing: str) -> str:
+    """The member landing's parent, while that landing is the unpublished bound tip."""
+    checkout, _, entry = isolation._member_context(repo, member)
+    bound = entry["branch"]
+    if _run_git(checkout, "rev-parse", f"refs/heads/{bound}").stdout.strip() != landing:
+        raise UndoError(f"member {member} {bound} moved past this landing")
+    _require_member_unpublished(checkout, member, landing, bound)
+    return _run_git(checkout, "rev-parse", f"{landing}^").stdout.strip()
+
+
+def _require_member_unpublished(checkout: Path, member: str, landing: str, bound: str) -> None:
+    for ref, where in (("refs/remotes/origin/main", "origin/main"), (f"refs/remotes/origin/{bound}", f"origin/{bound}")):
+        if _run_git(checkout, "merge-base", "--is-ancestor", landing, ref, check=False).returncode == 0:
+            raise UndoError(f"member {member} landing is already on {where}")
+
+
+def _require_no_member_landing_journal(repo: Path) -> None:
+    directory = isolation.common_git_dir(repo).joinpath(*isolation.MEMBER_LANDING_DIR)
+    if any(directory.glob("*.json")):
+        raise UndoError("member landing journal is pending; recover member landing first")
+
+
+def _undo_member_landing(repo: Path, transaction: dict[str, object]) -> None:
+    """Reset the member bound branch first; a resumed undo finds it already reset."""
+    member = str(transaction["member"])
+    checkout, _, entry = isolation._member_context(repo, member)
+    tip = _run_git(checkout, "rev-parse", f"refs/heads/{entry['branch']}").stdout.strip()
+    if tip == transaction["member_parent"]:
+        _require_member_unpublished(checkout, member, str(transaction["landing"]), entry["branch"])
+        return
+    if tip != transaction["landing"]:
+        raise UndoError(f"member {member} bound branch moved during undo")
+    if _member_undo_parent(repo, member, str(transaction["landing"])) != transaction["member_parent"]:
+        raise UndoError(f"member {member} landing parent changed during undo")
+    bound = Path(isolation.member_bound_checkout(repo, member)["checkout"])
+    if _run_git(bound, "status", "--porcelain", "--untracked-files=all").stdout:
+        raise UndoError(f"member {member} bound checkout is dirty")
+    _run_git(bound, "reset", "--hard", str(transaction["member_parent"]))
+
+
 def _finish_transaction(repo: Path, transaction: dict[str, object]) -> None:
+    if transaction["kind"] == "member-task":
+        with isolation._member_landing_lock(repo):
+            _finish_transaction_locked(repo, transaction)
+        return
+    _finish_transaction_locked(repo, transaction)
+
+
+def _finish_transaction_locked(repo: Path, transaction: dict[str, object]) -> None:
+    if transaction["kind"] == "member-task":
+        _require_no_member_landing_journal(repo)
     stage = _transaction_recovery_stage(repo, transaction)
+    if transaction["kind"] == "member-task":
+        _undo_member_landing(repo, transaction)
     if stage == "prepared":
         _require_unpublished_reset(repo, str(transaction["branch"]))
         _reset_to(repo, str(transaction["parent"]))
@@ -675,11 +738,7 @@ def _finish_transaction(repo: Path, transaction: dict[str, object]) -> None:
         _remove_untracked_tree(repo, archive)
     path = _git_path(repo, UNDO_TRANSACTION_NAME)
     path.unlink()
-    descriptor = os.open(path.parent, os.O_RDONLY)
-    try:
-        os.fsync(descriptor)
-    finally:
-        os.close(descriptor)
+    pipeline_state._common.fsync_directory(path.parent)
 
 
 def classify_undo(repo: Path) -> dict[str, object]:
@@ -821,6 +880,28 @@ def classify_undo(repo: Path) -> dict[str, object]:
         proof_error = _task_proof_error(resolved, head)
         if proof_error:
             return _blocked([f"task landing ownership is unproven: {proof_error}"])
+        record = isolation.MEMBER_RECORD_RE.search(body)
+        if record is not None:
+            try:
+                _require_no_member_landing_journal(resolved)
+                member_parent = _member_undo_parent(resolved, record["member"], record["landing"])
+            except (IsolationError, UndoError, PipelineStateError) as error:
+                return _blocked([f"member landing undo is unsafe: {error}"])
+            return {
+                "kind": "member-task",
+                "branch": recorded_branch,
+                "head": head,
+                "parent": parent,
+                "subject": subject,
+                "member": record["member"],
+                "landing": record["landing"],
+                "member_parent": member_parent,
+                "effects": [
+                    f"reset member {record['member']} bound branch to {member_parent}",
+                    f"reset {recorded_branch} to {parent}",
+                ],
+                "blocked": [],
+            }
         return {
             "kind": "task",
             "branch": recorded_branch,
@@ -978,6 +1059,20 @@ def apply_undo(repo: Path, kind: str, expected_head: str) -> dict[str, object]:
             discussion,
         )
         _finish_transaction(resolved, transaction)
+    elif kind == "member-task":
+        with isolation._member_landing_lock(resolved):
+            _require_no_member_landing_journal(resolved)
+            if preview(resolved)["target"] != target:
+                raise UndoError("member task undo target changed after preview")
+            if _worktree_changes(resolved):
+                raise UndoError("worktree changed after member task undo preview")
+            _require_unpublished_reset(resolved, str(target["branch"]))
+            transaction = _prepare_transaction(
+                resolved, kind, expected_head, str(target["parent"]), str(target["branch"]), None, None,
+                {"member": str(target["member"]), "landing": str(target["landing"]),
+                 "member_parent": str(target["member_parent"])},
+            )
+            _finish_transaction_locked(resolved, transaction)
     elif kind == "task":
         parent = target["parent"]
         if not parent:

package/skills/gsd-path-forensics/scripts/review_panel.py

@@ -470,7 +470,7 @@ def merge_artifacts(
         lines.append(artifact["text"].rstrip())
         lines.append("")
     output.parent.mkdir(parents=True, exist_ok=True)
-    output.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+    output.write_bytes(("\n".join(lines).rstrip() + "\n").encode("utf-8"))
     return {
         "output": str(output.resolve()),
         "families": families,

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

@@ -13,10 +13,13 @@ import os
 import tempfile
 from pathlib import Path
 
-try:
-    import _common
-except ImportError:
-    from scripts import _common
+if __package__:
+    from . import _common
+else:
+    try:
+        import _common
+    except ImportError:
+        from scripts import _common
 
 
 def _git(primary: Path, *args: str) -> str:
@@ -27,7 +30,10 @@ def _git(primary: Path, *args: str) -> str:
 
 
 def _identity(path: Path) -> str:
-    return hashlib.sha256(os.fsencode(path)).hexdigest()
+    digest = hashlib.sha256(os.fsencode(path)).hexdigest()
+    # Two identities nest in every managed path; full digests would use about
+    # 130 of Windows' 260-character MAX_PATH before any repository content.
+    return digest[:16] if os.name == "nt" else digest
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
@@ -65,7 +71,7 @@ def _workspace(primary: Path, pin: bool) -> Path:
         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:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
                 json.dump({"primary": str(primary), "root": str(workspace)}, handle)
             try:
                 os.link(temporary, receipt)
@@ -78,15 +84,19 @@ def _workspace(primary: Path, pin: bool) -> Path:
 
 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 {".", ".."}:
+    if kind not in {"task", "verify", "integrate", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
         raise ValueError("invalid managed worktree kind or name")
+    if kind == "bound":
+        return _workspace(primary, pin) / kind / 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:
+        # Compare as paths: git prints forward slashes on Windows.
+        worktrees = [Path(field[len("worktree "):]) for field in fields if field.startswith("worktree ")]
+        if legacy in worktrees and f"branch {branch}" in fields:
             return legacy
     # Keep collision checks and missing-directory recovery at the old location.
     if os.path.lexists(legacy):

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

@@ -3,7 +3,8 @@ name: gsd-path-inspect
 description: Inspect an existing codebase and its documentation to establish brownfield ground truth before intent is defined. Use only when the user explicitly invokes $gsd-path-inspect or an active $gsd-path router explicitly routes to this phase.
 ---
 
-Before executing project helpers, read [runtime selection](references/runtime-selection.md).
+Before executing project helpers, read [runtime selection](references/runtime-selection.md)
+and [operating rules](references/operating-rules.md).
 
 # GSD Path Inspect Phase
 
@@ -112,15 +113,15 @@ Preparation never changes phase state; neither command dispatches agents.
    includes its path and revision for project commands; expected new pipeline
    artifacts do not make product code dirty. Each agent writes only its
    assigned output under that sidecar and keeps it there for the gates in step
-   3. Otherwise no
+   3; its `Repo root` header still names the absolute primary. Otherwise no
    project command may run. The docs-auditor brief carries current HEAD as the
    audit baseline only when its verify sidecar was created at HEAD; otherwise
    it carries `none`. The auditor writes that baseline as `Audited HEAD`.
 3. Gate both artifacts against their templates: the codebase evidence needs
    a filled `## Map` plus findings as observed — no quota, but an empty
    findings section must say why; the docs audit must pass the bundled
-   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --audit
-   <track-relative DOCS-AUDIT.md> --inventory <frozen inventory file>`, where
+   `python3 <absolute check_docs_audit.py> --repo <docs sidecar> --primary
+   <absolute primary> --audit <track-relative DOCS-AUDIT.md> --inventory <frozen inventory file>`, where
    the audit path is `.project/research/DOCS-AUDIT.md` normally and
    `.project/next/research/DOCS-AUDIT.md` in Lookahead mode; add
    `--prior-audit <temporary prior-audit file>` when one was preserved and

package/skills/gsd-path-inspect/references/codebase-mapper.md

@@ -10,7 +10,8 @@ change nothing outside your single output file.
 - Read AGENTS.md and the template before scanning. Stop on a missing path.
 - Write only the assigned output using the template. When the brief supplies a
   disposable root, write the output under that root at the relative handoff
-  path; the orchestrator transfers it after validation. Do not ask the user
+  path; the orchestrator transfers it after validation. `Repo root` still names
+  the primary repo root, never the disposable root. Do not ask the user
   questions.
 
 ## What to establish

package/skills/gsd-path-inspect/references/docs-auditor.md

@@ -11,7 +11,8 @@ actually does. Read-only: change nothing outside your single output file.
 - Read AGENTS.md and the template before auditing. Stop on a missing path.
 - Write only the assigned output using the template. When the brief supplies a
   disposable root, write the output under that root at the relative handoff
-  path; the orchestrator transfers it after validation. Do not ask the user
+  path; the orchestrator transfers it after validation. `Repo root` still names
+  the primary repo root, never the disposable root. Do not ask the user
   questions.
 
 ## Method