@opengsd/gsd-path 1.0.0 → 1.2.0

package/scripts/build_recovery.py

@@ -0,0 +1,292 @@
+# gsd-path project runtime
+"""Guard a blocked build's return to Define or Plan using its committed base."""
+
+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
+
+
+EVENTS = {
+    "define": "build intent corrections requested",
+    "plan": "build plan repair requested",
+}
+MARKER = "build recovery: "
+
+
+def runtime():
+    if __package__:
+        from scripts import pipeline_state
+    else:
+        import pipeline_state
+    return pipeline_state
+
+
+def checkpoint_runtime():
+    if __package__:
+        from scripts import state_checkpoint
+    else:
+        import state_checkpoint
+    return state_checkpoint
+
+
+def context(repo: Path, text: str | None = None) -> dict | None:
+    state = runtime()
+    current, loaded, _ = state.load_state(repo)
+    text = loaded if text is None else text
+    recovery = None
+    for line in text.splitlines():
+        if " — " not in line:
+            continue
+        event = line.split(" — ", 2)[-1]
+        if event.startswith(MARKER):
+            try:
+                value = json.loads(event[len(MARKER):])
+            except ValueError as error:
+                raise state.PipelineStateError("invalid build recovery record") from error
+            if (not isinstance(value, dict) or set(value) != {"base", "branch", "kind"}
+                    or value["kind"] not in EVENTS
+                    or not isinstance(value["base"], str)
+                    or not re.fullmatch(r"[0-9a-f]{40}", value["base"])):
+                raise state.PipelineStateError("invalid build recovery record")
+            recovery = {**value, "active": True} if value["branch"] == current.branch else None
+        elif event == "build started" and recovery:
+            recovery["active"] = False
+    if recovery:
+        if not state._is_ancestor(repo, recovery["base"], "HEAD"):
+            raise state.PipelineStateError("build recovery base is not an ancestor of HEAD")
+        source = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/STATE.md")
+        if source is None:
+            raise state.PipelineStateError("build recovery base has no STATE.md")
+        before = state._state_from_text(source)
+        if ((before.phase, before.status) != ("build", "blocked")
+                or before.branch != current.branch or before.milestone != current.milestone):
+            raise state.PipelineStateError("build recovery base does not prove this blocked milestone")
+    return recovery
+
+
+def task_fields(text: str, label: str) -> dict:
+    if __package__:
+        from scripts.isolation import task_frontmatter
+    else:
+        from isolation import task_frontmatter
+    fields, error = task_frontmatter(text)
+    if fields is None:
+        raise runtime().PipelineStateError(f"{label}: {error}")
+    return fields
+
+
+def settled_tasks(repo: Path) -> dict[str, tuple[str, dict]]:
+    """Read task ownership without requiring the graph that Plan must repair."""
+    state = runtime()
+    directory = repo / ".project/tasks"
+    if directory.is_symlink() or not directory.is_dir():
+        raise state.PipelineStateError("build recovery requires real task artifacts")
+    tasks = {}
+    for path in sorted(directory.iterdir()):
+        if not re.fullmatch(r"T[0-9]{3}-[a-z0-9][a-z0-9-]*\.md", path.name):
+            raise state.PipelineStateError(f"invalid recovery task path: {path.name}")
+        text = state._read_real_file(path, path.name)
+        fields = task_fields(text, path.name)
+        if fields.get("status") not in {"pending", "done"}:
+            raise state.PipelineStateError(f"settle task ownership before recovery: {path.name}")
+        if fields["status"] == "pending" and any(
+            fields.get(key) != "null" for key in ("agent", "base", "worktree", "task_branch")
+        ):
+            raise state.PipelineStateError(f"pending task retains dispatch metadata: {path.name}")
+        tasks[path.name] = (text, fields)
+    if not tasks:
+        raise state.PipelineStateError("build recovery requires task artifacts")
+    return tasks
+
+
+def begin(repo: Path, before, after, event: str) -> dict:
+    state = runtime()
+    if (before.phase, before.status) != ("build", "blocked") or after.phase not in EVENTS:
+        raise state.PipelineStateError("build recovery requires build/blocked")
+    if event != EVENTS[after.phase]:
+        raise state.PipelineStateError(f"state transition requires event: {EVENTS[after.phase]}")
+    if before.archive is not None or before.branch != state._current_branch(repo):
+        raise state.PipelineStateError("build recovery requires the active bound branch")
+    if state._worktree_changes(repo):
+        raise state.PipelineStateError("checkpoint the blocked build before recovery")
+    if any(state.transaction_journals(repo).values()):
+        raise state.PipelineStateError("finish pending transactions before build recovery")
+    records = records_root(repo)
+    for directory in {path.parent.parent for path in records.rglob("attempt-*/state.json")}:
+        latest = max(directory.glob("attempt-*/state.json"), key=lambda path: int(path.parent.name.split("-")[1]))
+        record = state._read_json(latest)
+        if (record.get("cleanup_pending")
+                or (record.get("worktree") and record.get("branch") and not record.get("cleanup_complete"))
+                or record.get("outcome") not in {"landed", "collected", "blocked", "resolved", "redispatched"}):
+            raise state.PipelineStateError(f"settle dispatch records before recovery: {latest}")
+    tasks = settled_tasks(repo)
+    state._read_real_file(repo / ".project/plan/PLAN.md", "PLAN.md")
+    state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md")
+    base = state._run_git(repo, "rev-parse", "HEAD").stdout.strip()
+    done = [repo / ".project/tasks" / name for name, (_, fields) in tasks.items()
+            if fields["status"] == "done"]
+    if done:
+        if __package__:
+            from scripts.isolation import verify_landed_task_files
+        else:
+            from isolation import verify_landed_task_files
+        verify_landed_task_files(repo, done, ".project/tasks", base)
+    return {"kind": after.phase, "base": base, "branch": before.branch}
+
+
+def records_root(repo: Path) -> Path:
+    if __package__:
+        from scripts import isolation
+    else:
+        import isolation
+    root = isolation.common_git_dir(repo) / "gsd-path/dispatch" / isolation.require_bound(repo).replace("/", "-")
+    recovery = context(repo)
+    return root / recovery["base"] if recovery else root
+
+
+def review_backup(repo: Path, recovery: dict) -> Path:
+    return repo / ".project/plan" / f"build-recovery-{recovery['base']}" / "review"
+
+
+def validate_review_backup(repo: Path, recovery: dict, directory: Path) -> None:
+    state = runtime()
+    if directory.exists():
+        checkpoint_runtime()._tree_digest(directory)  # Reject symlinks and special files before reading.
+    expected = {}
+    for path in state._run_git(repo, "ls-tree", "-r", "--name-only", "-z",
+                               recovery["base"], "--", ".project/review").stdout.split("\0"):
+        if path:
+            expected[str(Path(path).relative_to(".project/review"))] = checkpoint_runtime()._git_text_at(repo, recovery["base"], path)
+    actual = {str(path.relative_to(directory)): path.read_text(encoding="utf-8")
+              for path in directory.rglob("*") if path.is_file()} if directory.exists() else {}
+    if actual != expected:
+        raise state.PipelineStateError("review backup differs from the recovery base")
+
+
+def prepare(repo: Path) -> dict:
+    """Move old reviews once; the durable STATE record owns interruption recovery."""
+    state = runtime()
+    repo = state._repo_root(repo)
+    with state._state_lock(repo / ".project"):
+        recovery = context(repo)
+        if not recovery or not recovery["active"]:
+            raise state.PipelineStateError("no active build recovery")
+        target = review_backup(repo, recovery)
+        if (repo / ".project/plan").is_symlink() or target.parent.is_symlink() or target.is_symlink():
+            raise state.PipelineStateError("unsafe recovery review backup")
+        source = repo / ".project/review"
+        if source.is_symlink():
+            raise state.PipelineStateError("unsafe recovery review directory")
+        if not target.exists():
+            validate_review_backup(repo, recovery, source)
+            target.parent.mkdir(exist_ok=True)
+            if source.exists():
+                source.rename(target)
+            else:
+                target.mkdir()
+        validate_review_backup(repo, recovery, target)
+        source.mkdir(exist_ok=True)
+    return {"status": "prepared", "recovery": recovery, "path": str(target)}
+
+
+def validate_plan(repo: Path) -> None:
+    state = runtime()
+    recovery = context(repo)
+    if not recovery or not recovery["active"]:
+        return
+    if not review_backup(repo, recovery).is_dir():
+        raise state.PipelineStateError("run prepare-build-recovery before planning")
+    validate_review_backup(repo, recovery, review_backup(repo, recovery))
+    source = checkpoint_runtime()._task_contracts_at(repo, recovery["base"], ".project/tasks")
+    current = settled_tasks(repo)
+    done = set()
+    for _, (path, text) in source.items():
+        fields = task_fields(text, path)
+        if fields.get("status") == "done":
+            name = Path(path).name
+            done.add(name)
+            if name not in current or current[name][0] != text:
+                raise state.PipelineStateError(f"build recovery must preserve landed task: {name}")
+    if any(fields["status"] == "done" and name not in done
+           for name, (_, fields) in current.items()):
+        raise state.PipelineStateError("build recovery cannot manufacture landed tasks")
+    if recovery["kind"] == "plan":
+        intent = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/intent/INTENT.md")
+        if state._read_real_file(repo / ".project/intent/INTENT.md", "INTENT.md") != intent:
+            raise state.PipelineStateError("plan repair cannot change approved intent")
+    unchanged = unchanged_waves(repo, recovery)
+    for path in (repo / ".project/review").iterdir():
+        match = re.match(r"wave-([1-9]\d*)[.]", path.name)
+        if match and int(match[1]) not in unchanged:
+            raise state.PipelineStateError("changed wave must be reviewed after build resumes")
+
+
+def unchanged_waves(repo: Path, recovery: dict) -> set[int]:
+    """Reuse evidence only when its intent, wave contract, and task bytes match."""
+    state = runtime()
+    project = repo / ".project"
+    old_intent = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/intent/INTENT.md")
+    if state._read_real_file(project / "intent/INTENT.md", "INTENT.md") != old_intent:
+        return set()
+    old_plan = checkpoint_runtime()._git_text_at(repo, recovery["base"], ".project/plan/PLAN.md") or ""
+    new_plan = state._read_real_file(project / "plan/PLAN.md", "PLAN.md")
+
+    def sections(text):
+        return {match[1]: match[2] for match in re.finditer(
+            r"(?ms)^## ([^\n]+)\n(.*?)(?=^## |\Z)", text,
+        )}
+
+    old_sections, new_sections = sections(old_plan), sections(new_plan)
+    # Non-wave settings govern every wave, including coverage and surfaces.
+    if ({k: v for k, v in old_sections.items() if not k.startswith("Wave ")}
+            != {k: v for k, v in new_sections.items() if not k.startswith("Wave ")}):
+        return set()
+    old_tasks = checkpoint_runtime()._task_contracts_at(repo, recovery["base"], ".project/tasks")
+    current = settled_tasks(repo)
+    unchanged = set()
+    for title, body in new_sections.items():
+        match = re.match(r"Wave ([1-9]\d*)\b", title)
+        if not match or old_sections.get(title) != body:
+            continue
+        wave = match[1]
+        before = {Path(path).name: text for path, text in old_tasks.values()
+                  if task_fields(text, path).get("wave") == wave}
+        after = {name: text for name, (text, fields) in current.items() if fields.get("wave") == wave}
+        if before and before == after:
+            unchanged.add(int(wave))
+    return unchanged
+
+
+def restore_unchanged_reviews(repo: Path) -> None:
+    recovery = context(repo)
+    if not recovery or not recovery["active"]:
+        return
+    unchanged = unchanged_waves(repo, recovery)
+    for path in review_backup(repo, recovery).iterdir():
+        match = re.match(r"wave-([1-9]\d*)[.]", path.name)
+        if match and int(match[1]) in unchanged:
+            destination = repo / ".project/review" / path.name
+            content = path.read_text(encoding="utf-8")
+            if not destination.exists() or runtime()._read_real_file(destination, destination.name) != content:
+                runtime()._atomic_write(destination, content)
+
+
+def inventory_checkpoint(repo: Path, head: str) -> bool:
+    state = runtime()
+    if state._run_git(repo, "show", "-s", "--format=%s", head).stdout.strip() != state.PLAN_APPROVAL_SUBJECT:
+        return False
+    text = checkpoint_runtime()._git_text_at(repo, head, ".project/STATE.md")
+    if text is None:
+        return False
+    approved = state._state_from_text(text)
+    if (approved.phase, approved.status) != ("plan", "done"):
+        return False
+    recovery = context(repo, text)
+    return bool(recovery and recovery["active"])

package/scripts/build_state.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Build task readiness, landing reconciliation, and the verify ledger."""
 
 from __future__ import annotations
@@ -7,6 +8,7 @@ import argparse
 import json
 import re
 import sys
+sys.dont_write_bytecode = True
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path, PurePosixPath

package/scripts/check_docs_audit.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# gsd-path project runtime
 """Gate a GSD Path docs audit (.project/research/DOCS-AUDIT.md) against its contract.
 
 Checks the rules the docs-audit contract states in prose: the header lines,
@@ -21,7 +22,8 @@ are rejected.
 The frozen inventory travels in the dispatch brief; pass it with
 `--inventory FILE` (one POSIX path per line, `-` for stdin). Without it the
 gate derives the inventory from tracked Markdown files, excluding `.git`,
-`node_modules`, `.project/archive/**`, installed `*/skills/gsd-path*` bundles,
+`node_modules`, `.project/archive/**`, installed `*/skills/gsd-path*` and
+`*/skills/path` bundles,
 the audit itself, and — unless the
 audit declares `Alignment mode: yes` — everything else under `.project/`.
 """
@@ -31,6 +33,7 @@ import json
 import re
 import subprocess
 import sys
+sys.dont_write_bytecode = True
 from datetime import date
 from pathlib import Path
 from typing import Dict, List, Optional, Sequence
@@ -100,9 +103,10 @@ def _not_placeholder(value: str, label: str) -> None:
 
 
 def _installed_skill(parts: Sequence[str]) -> bool:
-    """True for files inside an installed GSD Path skill bundle (<host>/skills/gsd-path*/…)."""
+    """Exclude installed GSD Path bundles, including the path router alias."""
     return any(
-        parts[index] == "skills" and parts[index + 1].startswith("gsd-path")
+        parts[index] == "skills" and
+        (parts[index + 1].startswith("gsd-path") or parts[index + 1] == "path")
         for index in range(len(parts) - 2)
     )
 

package/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
@@ -1462,7 +1468,7 @@ def validate_wave_evidence(
         raise HandoffError(f"{name} Cycle field does not match its filename")
     if _line_value(text, "Depth:") != expected_depth:
         raise HandoffError(f"{name} Depth does not match PLAN.md")
-    lens_fields = re.findall(r"(?m)^Lens:\s*(\S.*?)\s*$", text)
+    lens_fields = re.findall(r"(?m)^Lens:[ \t]*(\S.*?)[ \t]*$", text)
     if lens is None and lens_fields:
         raise HandoffError(f"{name} must not declare a review lens")
     if lens is not None and lens_fields != [lens]:

package/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/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:
@@ -1439,7 +1449,7 @@ def write_state_anchored(
 
 
 def initialize(
-    repo: Path, template: Path, phase: Optional[str] = None
+    repo: Path, template: Path, phase: Optional[str] = None, *, require_git: bool = False
 ) -> dict:
     if phase is not None and phase not in {"inspect", "define"}:
         raise DetectError(f"initialize phase must be inspect or define: {phase}")
@@ -1458,6 +1468,13 @@ def initialize(
     if payload["verdict"] not in {"brownfield", "greenfield"}:
         payload["wrote_state"] = False
         return payload
+    if require_git:
+        git = subprocess.run(
+            ["git", "-C", str(root), "rev-parse", "--is-inside-work-tree"],
+            env=git_environment(), capture_output=True, text=True, check=False,
+        )
+        if git.returncode != 0 or git.stdout.strip() != "true":
+            return {**payload, "route": "setup-repository", "wrote_state": False}
     expected = "inspect" if payload["verdict"] == "brownfield" else "define"
     if phase is None:
         phase = expected
@@ -1491,6 +1508,7 @@ def parser() -> argparse.ArgumentParser:
     result.add_argument("--repo", type=Path, required=True)
     result.add_argument("--template", type=Path)
     result.add_argument("--phase", choices=("inspect", "define"))
+    result.add_argument("--require-git", action="store_true")
     return result
 
 
@@ -1503,7 +1521,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             if arguments.template is None:
                 raise DetectError("initialize requires --template")
             payload = initialize(
-                arguments.repo, arguments.template, arguments.phase
+                arguments.repo, arguments.template, arguments.phase,
+                require_git=arguments.require_git
             )
             return emit(payload, 2 if payload.get("error") else 0)
         raise DetectError(f"unknown command: {arguments.command}")

package/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/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")