@opengsd/gsd-path 1.0.0 → 1.1.0

package/skills/path/scripts/build_recovery.py

@@ -0,0 +1,287 @@
+# gsd-path project runtime
+"""Guard a blocked build's return to Define or Plan using its committed base."""
+
+from __future__ import annotations
+
+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/skills/path/scripts/check_docs_audit.py

@@ -21,7 +21,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/`.
 """
@@ -100,9 +101,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/skills/path/scripts/check_handoffs.py

@@ -1462,7 +1462,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/skills/path/scripts/detect_project.py

@@ -1439,7 +1439,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 +1458,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 +1498,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 +1511,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/skills/path/scripts/dispatch_driver.py

@@ -31,13 +31,14 @@ from typing import BinaryIO, Callable, Dict, List, Optional
 
 try:
     from scripts import (_common, archive_milestone, build_state, discussion_validate, isolation,
-                         pipeline_state, review_findings, review_panel, workflow_run)
+                         pipeline_state, review_findings, review_panel, workflow_run, task_context)
     from scripts import check_handoffs as contracts
 except ImportError:  # bundled copy inside a skill's scripts directory
     import _common
     import archive_milestone
     import build_state
     import check_handoffs as contracts
+    import task_context
     import discussion_validate
     import isolation
     import pipeline_state
@@ -94,7 +95,7 @@ def milestone_slug(primary: Path) -> str:
 
 
 def records_root(primary: Path) -> Path:
-    return isolation.common_git_dir(primary) / "gsd-path" / "dispatch" / milestone_slug(primary)
+    return pipeline_state._build_recovery().records_root(primary)
 
 
 def budget_ledger(primary: Path) -> Path:
@@ -246,6 +247,7 @@ def brief_text(state: Dict[str, object], role_brief: Path, task_template: Path)
     if state.get("answered"):
         lines.append(f"The task Log now records an `{ANSWER_MARK}` to your earlier question; "
                      "continue from it.")
+    lines.append(task_context.render(worktree, worktree / str(state['task_file'])))
     return "\n".join(lines) + "\n"
 
 

package/skills/path/scripts/integration.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # gsd-path project runtime
-"""Integrate a shipped milestone by merge, pull request and tag for archive_milestone."""
+"""Own milestone integration, publication, tags, and completion proof."""
 
 import json
 import re
@@ -37,6 +37,20 @@ except ImportError:  # pragma: no cover - package import used by tests
     from scripts import _common
 
 
+if __package__:
+    from . import archive_milestone
+    from .archive_milestone import ArchiveError
+else:
+    import archive_milestone
+    from archive_milestone import ArchiveError
+
+
+PR_CREDIT_LINE = (
+    "PR prepared with [GSD Path](https://github.com/open-gsd/gsd-path)."
+)
+GITHUB_HOST = "github.com"
+
+
 run_git = _common.run_git
 run_command = _common.run_command
 
@@ -1208,7 +1222,7 @@ def find_integrate_commit(
     return merge_commit
 
 
-def validate_integrated(repo: Path, slug: str) -> dict:
+def validate_integrated(repo: Path, slug: str, *, refresh: bool = True) -> dict:
     project = repo.resolve()
     active_root = archive_milestone.require_project_layout(project)
     state, _, loaded_state_path = archive_milestone.strict_state(project)
@@ -1228,7 +1242,8 @@ def validate_integrated(repo: Path, slug: str) -> dict:
 
     # Refresh whenever origin exists so direct mode cannot miss a published tag.
     # Fixtures that only plant refs/remotes/origin/* keep resolve_remote_default.
-    if run_git(project, "remote", "get-url", "origin").returncode == 0:
+    has_origin = run_git(project, "remote", "get-url", "origin").returncode == 0
+    if has_origin and refresh:
         remote_default = refresh_origin(project)["remote_default"]
     else:
         remote_default = resolve_remote_default(project)
@@ -1348,6 +1363,16 @@ def validate_integrated(repo: Path, slug: str) -> dict:
         "mode": state.integration,
         "tag": tag_name,
     }
+    if has_origin and not refresh:
+        # Status must not fetch or write refs. Missing/stale local evidence is
+        # unverified; the normal ship validator remains the refresh owner.
+        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))
+        for ref, expected in refs:
+            if live_remote_ref(project, ref) != expected:
+                raise ArchiveError(f"published {ref} differs from local integration evidence")
     if pull_request is not None:
         result["pull_request"] = pull_request
     return result
@@ -1412,22 +1437,3 @@ def require_published_integration(
         raise ArchiveError(
             f"published milestone tag {tag_name} does not point at the integration merge"
         )
-
-
-# archive_milestone 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 archive_milestone stay visible here.
-if __package__:  # imported as scripts.integration
-    from . import archive_milestone
-    from .archive_milestone import (
-        GITHUB_HOST,
-        PR_CREDIT_LINE,
-        ArchiveError,
-    )
-else:  # standalone script or sibling import
-    import archive_milestone
-    from archive_milestone import (
-        GITHUB_HOST,
-        PR_CREDIT_LINE,
-        ArchiveError,
-    )

package/skills/path/scripts/isolation.py

@@ -2016,7 +2016,15 @@ def _recovery_task_inventory(
     relative_posix_dir = PurePosixPath(relative_dir.as_posix())
     revisions = [head]
     parents = git_output(primary, "show", "-s", "--format=%P", head).split()
-    if parents:
+    # A recovery plan checkpoint owns replacement of unstarted task briefs.
+    # Ordinary commits still require the parent inventory so a deletion cannot
+    # silently hide a task from recovery.
+    if __package__:
+        from scripts import build_recovery
+    else:
+        import build_recovery
+    replaced = build_recovery.inventory_checkpoint(primary, head)
+    if parents and not replaced:
         revisions.append(parents[0])
     tracked = set()
     for revision in revisions:

package/skills/path/scripts/lean_verification.py

@@ -94,7 +94,7 @@ def _final_view(relative, text, criteria, reviewed, head):
                   f"- **Reference**: {relative} — {criterion}",
                   "- **Finding**: none", "- **Fix direction**: none"]
         if "Surface" in fields:
-            lines.append(f"- **Surface**: {fields['Surface']}")
+            lines.append(f"- **Surface**: {contracts._unquoted(fields['Surface']).partition(',')[0]}")
         lines.append("")
     return "\n".join(lines)