@opengsd/gsd-path 1.3.0 → 1.4.0

package/scripts/check_handoffs.py

@@ -13,12 +13,16 @@ sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
-try:
-    from pipeline_state import PipelineStateError, load_state
-    import _common
-except ImportError:  # pragma: no cover - package imports used by tests
-    from scripts.pipeline_state import PipelineStateError, load_state
-    from scripts import _common
+if __package__:
+    from .pipeline_state import PipelineStateError, load_state
+    from . import _common
+else:
+    try:
+        from pipeline_state import PipelineStateError, load_state
+        import _common
+    except ImportError:  # pragma: no cover - package imports used by tests
+        from scripts.pipeline_state import PipelineStateError, load_state
+        from scripts import _common
 
 
 PIPELINE = "gsd-path/v2"
@@ -377,7 +381,10 @@ def validate_research(
 ) -> Dict[str, object]:
     """Validate the research-to-synthesis hand-off and return its summary."""
 
-    _require_state(root, "research", "active", project_dir)
+    # Research runs this before closing; decide runs it after its entry transition.
+    _require_state_one_of(
+        root, {("research", "active"), ("decide", "active")}, project_dir
+    )
     return validate_research_artifacts(root, project_dir)
 
 
@@ -548,6 +555,45 @@ def _reviewed_head(text: str, source: str) -> str:
     return value
 
 
+MEMBER_HEAD_PATTERN = re.compile(r"(?m)^Member reviewed HEAD:(.*)$")
+
+
+def member_reviewed_heads(text: str, source: str) -> Dict[str, str]:
+    """`Member reviewed HEAD: <member> <sha>` lines, one per member of a multi-repo milestone."""
+    heads: Dict[str, str] = {}
+    # Only the header binds heads; command output quoted in later sections cannot add one.
+    for value in MEMBER_HEAD_PATTERN.findall(_strip_comments(text).split("\n## ", 1)[0]):
+        name, _, sha = value.strip().partition(" ")
+        if not name or not SHA_PATTERN.fullmatch(sha.strip()):
+            raise HandoffError(
+                f"{source} Member reviewed HEAD must be '<member> <full commit SHA>', not {value.strip() or 'empty'}"
+            )
+        if name in heads:
+            raise HandoffError(f"{source} repeats Member reviewed HEAD for {name}")
+        heads[name] = sha.strip()
+    return heads
+
+
+def _member_tips(root: Path) -> Dict[str, str]:
+    """Each locked member's bound branch tip; empty when the milestone locks no member."""
+    try:
+        import isolation
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import isolation
+    lock = root / ".project/build/members.json"
+    if not lock.is_file():
+        return {}
+    tips: Dict[str, str] = {}
+    try:
+        for item in json.loads(lock.read_text(encoding="utf-8"))["members"]:
+            checkout, _, entry = isolation._member_context(root, item["name"])
+            tips[entry["name"]] = isolation.git_output(
+                checkout, "rev-parse", "--verify", f"refs/heads/{entry['branch']}^{{commit}}")
+    except isolation.IsolationError as error:
+        raise HandoffError(str(error)) from error
+    return tips
+
+
 def _strip_comments(text: str) -> str:
     return COMMENT_PATTERN.sub("", text)
 
@@ -750,6 +796,8 @@ def _task_texts(root: Path, project_dir: str) -> Dict[str, str]:
         raise HandoffError(f"missing {project_dir}/tasks")
     tasks: Dict[str, str] = {}
     for path in sorted(tasks_dir.iterdir()):
+        if _common.is_ignored_junk(path):
+            continue
         named = TASK_FILE_NAME.fullmatch(path.name)
         if named is None or not path.is_file() or path.is_symlink():
             raise HandoffError(f"non-canonical task artifact: {path.name}")
@@ -1008,7 +1056,10 @@ def _validate_task_graph(
     graph: Dict[str, List[str]] = {}
     task_waves: Dict[str, int] = {}
     task_files: Dict[str, List[str]] = {}
+    # `repo:` names the member a task changes; absent means the coordinator.
+    task_repos: Dict[str, str] = {}
     for task_id, text in tasks.items():
+        task_repos[task_id] = str(_strict_frontmatter(text, task_id).get("repo") or "")
         # Patch mode reopens planning beside landed tasks; only new tasks start clean.
         landed = _task_scalar(text, task_id, "status") == "done"
         _require_task_structure(task_id, text, initial=initial and not landed)
@@ -1028,7 +1079,7 @@ def _validate_task_graph(
 
     for index, left in enumerate(task_ids):
         for right in task_ids[index + 1 :]:
-            if task_waves[left] != task_waves[right]:
+            if task_waves[left] != task_waves[right] or task_repos[left] != task_repos[right]:
                 continue
             overlap = sorted(set(task_files[left]) & set(task_files[right]))
             if overlap:
@@ -1039,6 +1090,7 @@ def _validate_task_graph(
     visiting: Set[str] = set()
     visited: Set[str] = set()
     dependency_files: Dict[str, Set[str]] = {}
+    dependency_pairs: Dict[str, Set[Tuple[str, str]]] = {}
 
     def visit(task_id: str) -> None:
         if task_id in visiting:
@@ -1046,11 +1098,15 @@ def _validate_task_graph(
         if task_id in visited:
             return
         visiting.add(task_id)
-        dependency_files[task_id] = set()
+        dependency_pairs[task_id] = set()
         for dependency in graph[task_id]:
             visit(dependency)
-            dependency_files[task_id].update(task_files[dependency])
-            dependency_files[task_id].update(dependency_files[dependency])
+            dependency_pairs[task_id].update((task_repos[dependency], name) for name in task_files[dependency])
+            dependency_pairs[task_id].update(dependency_pairs[dependency])
+        # A dependency's files are supplied only within the same repo.
+        dependency_files[task_id] = {
+            name for repo, name in dependency_pairs[task_id] if repo == task_repos[task_id]
+        }
         visiting.remove(task_id)
         visited.add(task_id)
 
@@ -1212,7 +1268,7 @@ def _head_file(root: Path, relative: str) -> Optional[str]:
         ["git", "show", f"HEAD:{relative}"],
         cwd=root,
         capture_output=True,
-        text=True,
+        encoding="utf-8", errors="replace",
         check=False,
     )
     return result.stdout if result.returncode == 0 else None
@@ -1313,6 +1369,21 @@ def validate_roadmap(
     return {"phase": "roadmap", "milestones": ids, "dependencies": dependencies}
 
 
+def _integrated_members(root: Path, state: Dict[str, str]) -> Set[str]:
+    """Members this milestone already closed; a new task for one would need a second merge."""
+    match = re.fullmatch(r"gsd-path/M(\d{3,})", state.get("branch") or "")
+    common = subprocess.run(["git", "-C", str(root), "rev-parse", "--path-format=absolute", "--git-common-dir"],
+                            capture_output=True, text=True, check=False)
+    if match is None or common.returncode != 0:
+        return set()
+    if __package__:
+        from . import members
+    else:
+        import members
+    rows = members.milestone_member_close(Path(common.stdout.strip()), int(match.group(1)))
+    return {row["name"] for row in rows if row.get("status") == "integrated"}
+
+
 def validate_plan(
     root: Path, project_dir: str = DEFAULT_PROJECT_DIR
 ) -> Dict[str, object]:
@@ -1332,6 +1403,14 @@ def validate_plan(
     # Build readiness owns task lifecycle validation; coverage must survive landings.
     state = _require_pipeline(root, project_dir)
     _validate_task_graph(wave_depths, tasks, initial=state["phase"] == "plan")
+    integrated = _integrated_members(root, state)
+    for task_id, text in tasks.items():
+        repo = str(_strict_frontmatter(text, task_id).get("repo") or "")
+        if repo in integrated and _task_scalar(text, task_id, "status") != "done":
+            raise HandoffError(
+                f"{task_id} changes member {repo}, which is already integrated in this milestone; "
+                "plan that change in a new milestone"
+            )
     assigned: Dict[str, Set[str]] = {task_id: set() for task_id in tasks}
     covered = set()
     for criterion, task_id, acceptance in rows:
@@ -1591,6 +1670,19 @@ def validate_wave_evidence(
     }
 
 
+def criterion_surfaces(root: Path, project_dir: str = DEFAULT_PROJECT_DIR) -> Dict[str, str]:
+    """Map each surface-owned INTENT SC to the surface PLAN.md's contract lists it under."""
+
+    surface_of: Dict[str, str] = {}
+    surfaces = _surfaces(_read(root, _intent_path(project_dir)), "INTENT.md")
+    if surfaces:
+        plan = _read(root, f"{project_dir}/plan/PLAN.md")
+        for surface, (_task, owned) in _surface_contract(plan, surfaces).items():
+            for criterion in owned:
+                surface_of[criterion] = surface
+    return surface_of
+
+
 def validate_final(
     root: Path, project_dir: str = DEFAULT_PROJECT_DIR, *, final_text: Optional[str] = None
 ) -> Dict[str, object]:
@@ -1599,20 +1691,14 @@ def validate_final(
     _require_state(root, "ship", "active", project_dir)
     intent = _read(root, _intent_path(project_dir))
     criteria = _success_criteria(intent)
-    surface_of: Dict[str, str] = {}
-    surfaces = _surfaces(intent, "INTENT.md")
-    if surfaces:
-        plan = _read(root, f"{project_dir}/plan/PLAN.md")
-        for surface, (_task, owned) in _surface_contract(plan, surfaces).items():
-            for criterion in owned:
-                surface_of[criterion] = surface
+    surface_of = criterion_surfaces(root, project_dir)
     relative = f"{project_dir}/review/FINAL.md"
     text = _read(root, relative) if final_text is None else final_text
     reviewed_head = _reviewed_head(text, relative)
     head_result = subprocess.run(
         ("git", "-C", str(root), "rev-parse", "--verify", "HEAD"),
         capture_output=True,
-        text=True,
+        encoding="utf-8", errors="replace",
         check=False,
     )
     if head_result.returncode != 0:
@@ -1623,6 +1709,14 @@ def validate_final(
             f"FINAL.md Reviewed HEAD {reviewed_head} is not the current HEAD "
             f"{current_head}; re-run the final review on the current commit"
         )
+    member_heads = member_reviewed_heads(text, relative)
+    tips = _member_tips(root)
+    if member_heads != tips:
+        expected = ", ".join(f"{name} {tip}" for name, tip in tips.items()) or "none"
+        raise HandoffError(
+            f"FINAL.md Member reviewed HEAD lines must name each locked member head ({expected}); "
+            "re-run the final review on the current member heads"
+        )
     overall = _line_value(text, "Overall verdict:")
     if overall not in {"pass", "blocked"}:
         raise HandoffError("FINAL.md Overall verdict is invalid")
@@ -1697,6 +1791,8 @@ def validate_final(
             raise HandoffError(f"{gap_relative} heading does not match its file number")
         if _reviewed_head(gap, gap_relative) != reviewed_head:
             raise HandoffError(f"{gap_relative} Reviewed HEAD differs from FINAL.md")
+        if member_reviewed_heads(gap, gap_relative) != member_heads:
+            raise HandoffError(f"{gap_relative} Member reviewed HEAD lines differ from FINAL.md")
         verdict = _line_value(gap, "Gap verdict:")
         if verdict not in {"pass", "blocked"}:
             raise HandoffError(f"{gap_relative} Gap verdict is invalid")

package/scripts/check_task_briefs.py

@@ -12,10 +12,13 @@ sys.dont_write_bytecode = True
 from pathlib import Path, PurePosixPath
 from typing import Dict, List, Optional, Sequence, Set, Tuple
 
-try:
-    import _common
-except ImportError:  # pragma: no cover - package import used by tests
-    from scripts import _common
+if __package__:
+    from . import _common
+else:
+    try:
+        import _common
+    except ImportError:  # pragma: no cover - package import used by tests
+        from scripts import _common
 
 
 DEFAULT_TASKS_DIR = ".project/tasks"
@@ -183,10 +186,47 @@ def _verify_tokens(block: str) -> List[str]:
     return tokens
 
 
+def _member_bases(root: Path):
+    """Resolve a member name to (checkout, origin/main SHA), reading MEMBERS.md once."""
+    cache: Dict[str, Optional[Tuple[Path, str]]] = {}
+
+    def locate(name: str) -> Optional[Tuple[Path, str]]:
+        if name not in cache:
+            if __package__:
+                from . import members
+            else:
+                try:
+                    import members
+                except ImportError:  # pragma: no cover - package import used by tests
+                    from scripts import members
+            try:
+                listed = {member["name"]: Path(member["checkout"]) for member in members.read_members(root)}
+                checkout = listed.get(name)
+                if checkout is None:
+                    cache[name] = None
+                else:
+                    # A build lock selects the bound tip, including during Plan recovery;
+                    # without the lock, use origin/main before the first build start.
+                    lock = root / members.LOCK_PATH
+                    locked = [entry for entry in (json.loads(lock.read_text(encoding="utf-8"))["members"]
+                                                  if lock.is_file() else []) if entry["name"] == name]
+                    if locked:
+                        cache[name] = (checkout, _resolve_base(checkout, f"refs/heads/{locked[0]['branch']}"))
+                    else:
+                        members.require_origin_main(checkout)
+                        cache[name] = (checkout, _resolve_base(checkout, "refs/remotes/origin/main"))
+            except (members.MembersError, BriefError) as error:
+                raise BriefError(f"member {name} is unavailable: {error}") from error
+        return cache[name]
+
+    return locate
+
+
 def _lint_task(
     repo: Path, base: str, path: Path,
     dependency_files: Optional[Dict[str, Set[str]]] = None,
     landed_bases: Optional[Dict[str, str]] = None,
+    member_base=None,
 ) -> Tuple[str, List[str], Optional[str], int]:
     text = path.read_text(encoding="utf-8")
     fields, error = _frontmatter(text)
@@ -198,6 +238,15 @@ def _lint_task(
     checked = 0
     if fields is None:
         return task_id, [error or "invalid frontmatter"], None, checked
+    # A member task's paths resolve in the member at its origin/main, where the
+    # member bound branch starts; `repo:` absent means the coordinator.
+    git_root = repo
+    member = fields.get("repo")
+    if member is not None:
+        located = member_base(member) if isinstance(member, str) and member and member_base else None
+        if located is None:
+            return task_id, [f"repo: names no member in MEMBERS.md: {member}"], None, checked
+        git_root, base = located[0], (landed_bases or {}).get(task_id, located[1])
 
     for field in REQUIRED_FIELDS:
         if field not in fields:
@@ -237,7 +286,7 @@ def _lint_task(
             for parent in candidate.parents:
                 if str(parent) == ".":
                     break
-                kind = _run_git(repo, "cat-file", "-t", f"{base}:{parent}")
+                kind = _run_git(git_root, "cat-file", "-t", f"{base}:{parent}")
                 if kind.returncode == 0 and kind.stdout.strip() != "tree":
                     problems.append(
                         f"files entry {normalized} has non-directory ancestor "
@@ -255,7 +304,7 @@ def _lint_task(
                 token not in declared
                 and token not in supplied
                 and not _supplied_contract(repo, path, token)
-                and not _base_exists(repo, base, token)
+                and not _base_exists(git_root, base, token)
             ):
                 problems.append(f"## {name} names a path missing at the layer base: {token}")
 
@@ -267,7 +316,7 @@ def _lint_task(
         else:
             for token in _verify_tokens(block.group("block")):
                 checked += 1
-                if token not in declared and token not in supplied and not _base_exists(repo, base, token):
+                if token not in declared and token not in supplied and not _base_exists(git_root, base, token):
                     problems.append(f"## Verify names a path missing at the layer base: {token}")
 
     contract = None
@@ -284,6 +333,7 @@ def validate_task_briefs(
     root: Path, base: str, tasks_dir: str = DEFAULT_TASKS_DIR,
     *, dependency_files: Optional[Dict[str, Set[str]]] = None,
     landed_bases: Optional[Dict[str, str]] = None,
+    member_base=None,
 ) -> Dict[str, object]:
     """Lint task briefs using the caller's validation bases.
 
@@ -305,9 +355,11 @@ def validate_task_briefs(
     task_files = sorted(tasks_path.glob("*.md"))
     if not task_files:
         raise BriefError(f"no task briefs found in {tasks_dir}")
+    if member_base is None:
+        member_base = _member_bases(root)
     for path in task_files:
         task_id, task_problems, contract, task_checked = _lint_task(
-            root, resolved_base, path, dependency_files, landed_bases
+            root, resolved_base, path, dependency_files, landed_bases, member_base
         )
         problems.extend(f"{task_id}: {problem}" for problem in task_problems)
         if contract is not None:

package/scripts/check_update.py

@@ -37,8 +37,8 @@ def is_newer(latest, installed):
 def _write_cache(now, latest):
     try:
         CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
-        CACHE_PATH.write_text(
-            json.dumps({"checked_at": now, "latest": latest}), encoding="utf-8"
+        CACHE_PATH.write_bytes(
+            json.dumps({"checked_at": now, "latest": latest}).encode("utf-8")
         )
     except OSError:
         pass

package/scripts/core_hook_gate.py

@@ -12,6 +12,9 @@ def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--repo", required=True, action="append", type=Path)
     parser.add_argument("--command", required=True)
+    # Windows wrappers record bash: the host ran the original through Git Bash,
+    # and shell=True would run it through cmd.exe instead.
+    parser.add_argument("--shell", choices=("bash",))
     args = parser.parse_args()
     payload = sys.stdin.buffer.read()
     try:
@@ -26,7 +29,13 @@ def main():
     except (OSError, ValueError, RuntimeError):
         # An uncertain event keeps the original hook's protection and errors.
         pass
-    result = subprocess.run(args.command, shell=True, input=payload)
+    if args.shell == "bash":
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        import _common
+
+        result = subprocess.run(_common.bash_argv(args.command), input=payload)
+    else:
+        result = subprocess.run(args.command, shell=True, input=payload)
     return result.returncode if result.returncode >= 0 else 128 - result.returncode
 
 

package/scripts/core_hook_settings.py

@@ -8,7 +8,6 @@ import os
 from pathlib import Path
 import shlex
 import stat
-import subprocess
 import sys
 import tempfile
 
@@ -47,8 +46,15 @@ def plan(args):
     gate = Path(__file__).resolve().with_name("core_hook_gate.py")
     if not gate.is_file():
         raise ValueError(f"missing installed hook gate: {gate}")
-    argv = [sys.executable, "-B", str(gate), "--repo", str(repo), "--command", original]
-    replacement = subprocess.list2cmdline(argv) if os.name == "nt" else shlex.join(argv)
+    if os.name == "nt":
+        # Claude Code runs Windows hook commands in Git Bash: quote for bash,
+        # use forward slashes, and have the gate run the original through bash
+        # rather than cmd.exe.
+        argv = [Path(sys.executable).as_posix(), "-B", gate.as_posix(), "--repo", repo.as_posix(),
+                "--shell", "bash", "--command", original]
+    else:
+        argv = [sys.executable, "-B", str(gate), "--repo", str(repo), "--command", original]
+    replacement = shlex.join(argv)
     entry["command"] = replacement
     after = (json.dumps(data, indent=2) + "\n").encode()
     receipt = {
@@ -60,7 +66,8 @@ def plan(args):
         "after": base64.b64encode(after).decode(),
     }
     # Settings may contain secrets; the review/rollback copy is owner-only.
-    with open(args.receipt, "x", encoding="utf-8", opener=lambda path, flags: os.open(path, flags, 0o600)) as handle:
+    with open(args.receipt, "x", encoding="utf-8", newline="\n",
+              opener=lambda path, flags: os.open(path, flags, 0o600)) as handle:
         json.dump(receipt, handle, indent=2)
         handle.write("\n")
     return {"status": "planned", "receipt": str(args.receipt.absolute())}