@opengsd/gsd-path 1.0.0 → 1.1.0

package/skills/gsd-path-ship/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/gsd-path-ship/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/gsd-path-ship/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)
 

package/skills/gsd-path-ship/scripts/pipeline_state.py

@@ -32,8 +32,9 @@ try:
         collect_artifact_recoveries,
     )
     import _common
+    import roadmap
 except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
-    if error.name not in {"isolation", "_common"}:
+    if error.name not in {"isolation", "_common", "roadmap"}:
         raise
     from scripts.isolation import (
         IsolationError,
@@ -41,7 +42,7 @@ except ModuleNotFoundError as error:  # pragma: no cover - package imports used
         checkpoint as isolation_checkpoint,
         collect_artifact_recoveries,
     )
-    from scripts import _common
+    from scripts import _common, roadmap
 
 try:  # pragma: no cover - exercised only on Windows
     import fcntl
@@ -82,7 +83,6 @@ SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
 BOUND_BRANCH_RE = _common.BOUND_BRANCH_RE
 ARCHIVE_RE = re.compile(r"^\.project/archive/(\d{3,})-([a-z0-9][a-z0-9-]*)/?$")
 FRONTMATTER_RE = re.compile(r"^([a-z_]+):\s*([^#]*?)(?:\s+#.*)?$")
-ROADMAP_HEADING_RE = re.compile(r"^### (M\d{3,}) — ([a-z0-9][a-z0-9-]*)\s*$")
 TASK_ID_RE = re.compile(r"^T\d{3,}$")
 TASK_FILE_RE = re.compile(r"^(T\d{3,})-[a-z0-9][a-z0-9-]*\.md$")
 PLAN_APPROVAL_SUBJECT = "plan: build plan approved"
@@ -110,7 +110,7 @@ LOOKAHEAD_EVIDENCE_RE = re.compile(r"^research/evidence-[a-z0-9][a-z0-9-]*\.md$"
 PROMOTION_RESIDUAL = ".gsd-path-promote-next-residual"
 CHECKPOINT_SCHEMA = "gsd-path/state-checkpoint/v1"
 CHECKPOINT_JOURNAL_NAME = "gsd-path-state-checkpoint.json"
-CHECKPOINT_KINDS = ("plan", "roadmap")
+CHECKPOINT_KINDS = ("plan", "roadmap", "roadmap-reslice")
 SHIPMENT_SCHEMA = "gsd-path/shipment/v1"
 SHIPMENT_JOURNAL_NAME = "gsd-path-shipment.json"
 UNDO_TRANSACTION_SCHEMA = "gsd-path/undo-transaction/v2"
@@ -126,6 +126,8 @@ CROSS_PHASE_TRANSITIONS = {
     ("decide", "done", "plan", "active"),
     ("roadmap", "done", "define", "active"),
     ("plan", "done", "build", "active"),
+    ("build", "blocked", "define", "active"),
+    ("build", "blocked", "plan", "active"),
     ("build", "active", "ship", "active"),
     ("build", "done", "ship", "active"),
     ("ship", "active", "shipped", "done"),
@@ -166,99 +168,10 @@ class ApprovedTaskContract:
     files: tuple[str, ...]
 
 
-# state_checkpoint and state_promote call back into this module through a
-# module reference and import the constants and classes above, so this import
-# must stay below those definitions.
-if __package__:  # imported as scripts.pipeline_state
-    from .state_checkpoint import (
-        _sha256,
-        _tree_digest,
-        _checkpoint_artifact_digest,
-        _roadmap_status,
-        _activate_roadmap_milestone,
-        _approval_details,
-        _checkpoint_request_fields,
-        _checkpoint_file,
-        _approval_journal,
-        _remove_checkpoint_temporary,
-        _converge_checkpoint_file,
-        _unlink_checkpoint_journal,
-        _resume_checkpoint_locked,
-        checkpoint_approval,
-        _checkpoint_deferral_error,
-        defer_approval,
-        resume_checkpoint,
-        _task_files,
-        _approval_checkpoint,
-        _validate_approval_track,
-        _safe_declared_paths,
-        _git_text_at,
-        _approved_task_contracts,
-        _task_contracts_at,
-        _classify_plan_drift,
-    )
-    from .state_promote import (
-        _render_roadmap,
-        _promotion_event,
-        _promotion_state,
-        _head_with_exact_message,
-        _tree_entries,
-        _promotion_tree_mapping,
-        _completed_promotion,
-        _prepare_promotion,
-        _require_journal_request,
-        _resume_track_moves,
-        _resume_metadata,
-        _resume_next_removal,
-        _commit_promotion,
-        promote_next,
-    )
-else:  # standalone script or sibling import
-    if __name__ == "__main__":
-        sys.modules.setdefault("pipeline_state", sys.modules[__name__])
-    from state_checkpoint import (
-        _sha256,
-        _tree_digest,
-        _checkpoint_artifact_digest,
-        _roadmap_status,
-        _activate_roadmap_milestone,
-        _approval_details,
-        _checkpoint_request_fields,
-        _checkpoint_file,
-        _approval_journal,
-        _remove_checkpoint_temporary,
-        _converge_checkpoint_file,
-        _unlink_checkpoint_journal,
-        _resume_checkpoint_locked,
-        checkpoint_approval,
-        _checkpoint_deferral_error,
-        defer_approval,
-        resume_checkpoint,
-        _task_files,
-        _approval_checkpoint,
-        _validate_approval_track,
-        _safe_declared_paths,
-        _git_text_at,
-        _approved_task_contracts,
-        _task_contracts_at,
-        _classify_plan_drift,
-    )
-    from state_promote import (
-        _render_roadmap,
-        _promotion_event,
-        _promotion_state,
-        _head_with_exact_message,
-        _tree_entries,
-        _promotion_tree_mapping,
-        _completed_promotion,
-        _prepare_promotion,
-        _require_journal_request,
-        _resume_track_moves,
-        _resume_metadata,
-        _resume_next_removal,
-        _commit_promotion,
-        promote_next,
-    )
+# Standalone transaction imports must reuse this state module and its types.
+if __name__ == "__main__":
+    sys.modules.setdefault("pipeline_state", sys.modules[__name__])
+
 
 def _run_git(
     repo: Path,
@@ -693,6 +606,21 @@ def _next_skill(route: Mapping[str, object]) -> Optional[str]:
     return None
 
 
+def _completion_status(repo: Path, state: Mapping[str, object], project_dir: str) -> dict:
+    if project_dir != ".project" or state.get("phase") != "shipped":
+        return {"status": "not-shipped"}
+    if __package__:
+        from . import integration
+    else:
+        import integration
+    try:
+        proof = integration.validate_integrated(
+            repo, str(state.get("milestone") or ""), refresh=False)
+    except (integration.ArchiveError, OSError) as error:
+        return {"status": "unverified", "reason": str(error)}
+    return {"status": "verified", "proof": proof}
+
+
 def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]:
     """Report owned state, route, and git facts without advancing a phase."""
     resolved = _repo_root(repo)
@@ -726,9 +654,11 @@ def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
         "undo": None,
         "collect_artifact": None,
     }
+    completion = _completion_status(resolved, state, project_dir)
     return {
         "schema": STATUS_SCHEMA,
         "advance": False,
+        "completion": completion,
         "state": state,
         "route": route,
         "path": str(_track_root(resolved, project_dir) / "STATE.md"),
@@ -753,6 +683,28 @@ def status_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
         "lookahead": lookahead.exists() or lookahead.is_symlink(),
         "journals": journals,
         "next_skill": _next_skill(route if isinstance(route, dict) else {}),
+        "handoff": phase_handoff(state, route, _track_root(resolved, project_dir) / "STATE.md", completion),
+    }
+
+
+def phase_handoff(state: Mapping[str, object], route: Mapping[str, object], path: Path,
+                  completion: Mapping[str, object]) -> dict[str, str]:
+    """Present the authoritative route without granting continuation authority."""
+    action = route["action"]
+    if action == "run-phase":
+        next_action = f"Invoke $gsd-path to continue with {route['phase']}."
+        router_next = f"Continue with {route['phase']}; honor its input and approval gates."
+    else:
+        next_action = router_next = f"{action}: {route['reason']}"
+    outcome = f"{state['phase']}/{state['status']}"
+    if completion["status"] == "unverified":
+        outcome = f"Unverified: {outcome}"
+    return {
+        "outcome": outcome,
+        "review": str(path),
+        "next": next_action,
+        "phase_next": next_action,
+        "router_next": router_next,
     }
 
 
@@ -784,50 +736,11 @@ def _intent_lane(track: Path) -> Optional[str]:
 
 
 def _active_roadmap_has_questions(project: Path, milestone: Optional[str] = None) -> bool:
-    """Report open questions for the active entry, or for ``milestone`` when given."""
     text = _read_real_file(project / "ROADMAP.md", "ROADMAP.md")
-    lines = text.splitlines()
-    active_section: Optional[list[str]] = None
-    for index, line in enumerate(lines):
-        heading = ROADMAP_HEADING_RE.fullmatch(line)
-        if heading is None:
-            continue
-        if int(heading.group(1).removeprefix("M")) < 1:
-            raise PipelineStateError(
-                f"ROADMAP.md has invalid milestone id: {heading.group(1)}"
-            )
-        end = next(
-            (
-                cursor
-                for cursor in range(index + 1, len(lines))
-                if ROADMAP_HEADING_RE.fullmatch(lines[cursor]) is not None
-            ),
-            len(lines),
-        )
-        section = lines[index:end]
-        if milestone is not None:
-            if heading.group(2) == milestone:
-                active_section = section
-            continue
-        if any(re.fullmatch(r"Status:\s*active(?:\s+#.*)?", item) for item in section):
-            if active_section is not None:
-                raise PipelineStateError("ROADMAP.md has more than one active milestone")
-            active_section = section
-    if active_section is None:
-        if milestone is not None:
-            raise PipelineStateError(f"ROADMAP.md is missing lookahead milestone: {milestone}")
-        raise PipelineStateError("ROADMAP.md has no active milestone")
     try:
-        start = active_section.index("Open questions") + 1
-    except ValueError as error:
-        raise PipelineStateError("active roadmap milestone has no Open questions") from error
-    questions = [
-        line[2:].strip()
-        for line in active_section[start:]
-        if line.startswith("- ")
-    ]
-    return any(question.lower() != "none" for question in questions)
-
+        return roadmap.has_questions(text, milestone)
+    except roadmap.RoadmapError as error:
+        raise PipelineStateError(str(error)) from error
 
 def _valid_patch_findings(repo: Path) -> bool:
     validator = Path(__file__).resolve().with_name("check_handoffs.py")
@@ -1106,6 +1019,14 @@ def route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]:
     """Route ordinary phase work only when its pending discussion owner can enter."""
     result = _route_state(repo, project_dir)
     route = result["route"]
+    if project_dir == ".project" and route["action"] == "run-phase":
+        recovery = _build_recovery().context(_repo_root(repo))
+        if recovery and recovery["active"]:
+            result["recovery"] = recovery
+            if route.get("phase") == "define":
+                route["mode"] = "corrections"
+            elif route.get("phase") == "plan":
+                route["mode"] = "build-repair"
     if route["action"] == "run-phase" and result["state"]["archive"] is None:
         reason = _pending_discussion_block(_repo_root(repo), route.get("phase"))
         if reason:
@@ -1159,7 +1080,11 @@ def _route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
                 return result
             checkpoint_journal = _git_path(resolved, CHECKPOINT_JOURNAL_NAME)
             if checkpoint_journal.exists() or checkpoint_journal.is_symlink():
-                transaction = _approval_journal(
+                if __package__:
+                    from . import state_checkpoint
+                else:
+                    import state_checkpoint
+                transaction = state_checkpoint._approval_journal(
                     resolved,
                     _read_json(checkpoint_journal),
                 )
@@ -1736,6 +1661,16 @@ def transition_state(
             event,
             project_dir,
         )
+        recovery_context = _build_recovery().context(resolved, text) if project_dir == ".project" else None
+        if recovery_context and recovery_context["active"]:
+            if (state.milestone, state.branch, state.archive) != (after.milestone, after.branch, after.archive):
+                raise PipelineStateError("build recovery must preserve milestone identity")
+        if state.phase == "build" and after.phase in {"define", "plan"}:
+            recovery = _build_recovery().begin(resolved, state, after, event)
+            rendered = _append_event(
+                rendered, after.phase,
+                _build_recovery().MARKER + json.dumps(recovery, sort_keys=True),
+            )
         if after.status != "blocked":
             reason = _pending_discussion_block(
                 resolved, after.phase if after.status == "active" else None
@@ -1767,6 +1702,14 @@ def transition_state(
     }
 
 
+def _build_recovery():
+    if __package__:
+        from scripts import build_recovery
+    else:
+        import build_recovery
+    return build_recovery
+
+
 def configure_integration(
     repo: Path,
     scope: str,
@@ -1786,7 +1729,9 @@ def configure_integration(
     project = _track_root(resolved, project_dir)
     with _state_lock(project):
         state, text, path = load_state(resolved, project_dir)
-        if state.phase in {"build", "ship", "shipped"}:
+        if state.phase in {"build", "ship", "shipped"} or (
+            project_dir == ".project" and _build_recovery().context(resolved, text)
+        ):
             raise PipelineStateError("integration mode is locked when build starts")
         if scope == "default":
             integration = (
@@ -2022,49 +1967,18 @@ def _render_transition(
 
 
 def _roadmap_sections(text: str) -> dict[str, tuple[str, int, int]]:
-    lines = text.splitlines(keepends=True)
-    headings: list[tuple[str, str, int]] = []
-    for index, line in enumerate(lines):
-        match = ROADMAP_HEADING_RE.fullmatch(line.rstrip("\r\n"))
-        if match:
-            if int(match.group(1).removeprefix("M")) < 1:
-                raise PipelineStateError(f"ROADMAP.md has invalid milestone id: {match.group(1)}")
-            headings.append((match.group(1), match.group(2), index))
-    sections: dict[str, tuple[str, int, int]] = {}
-    for position, (milestone_id, slug, start) in enumerate(headings):
-        end = headings[position + 1][2] if position + 1 < len(headings) else len(lines)
-        if slug in sections:
-            raise PipelineStateError(f"ROADMAP.md repeats milestone slug: {slug}")
-        sections[slug] = (milestone_id, start, end)
-    return sections
-
+    try:
+        return roadmap.strict_sections(text)
+    except roadmap.RoadmapError as error:
+        raise PipelineStateError(str(error)) from error
 
 def _replace_roadmap_field(
-    lines: list[str],
-    start: int,
-    end: int,
-    field: str,
-    expected: set[str],
-    value: str,
+    lines: list[str], start: int, end: int, field: str, expected: set[str], value: str,
 ) -> None:
-    found: Optional[int] = None
-    for index in range(start, end):
-        raw = lines[index].rstrip("\r\n")
-        ending = lines[index][len(raw) :]
-        match = re.match(rf"^({re.escape(field)}:\s*)(\S+)(.*)$", raw)
-        if match is None:
-            continue
-        if found is not None:
-            raise PipelineStateError(f"ROADMAP.md repeats {field} in one milestone")
-        if match.group(2) not in expected:
-            raise PipelineStateError(
-                f"ROADMAP.md {field} is {match.group(2)}, expected {sorted(expected)}"
-            )
-        lines[index] = f"{match.group(1)}{value}{match.group(3)}{ending}"
-        found = index
-    if found is None:
-        raise PipelineStateError(f"ROADMAP.md milestone is missing {field}")
-
+    try:
+        return roadmap.replace_field(lines, start, end, field, expected, value)
+    except roadmap.RoadmapError as error:
+        raise PipelineStateError(str(error)) from error
 
 def _git_path(repo: Path, name: str) -> Path:
     value = _run_git(repo, "rev-parse", "--git-path", name).stdout.strip()
@@ -2163,7 +2077,7 @@ def _specified_fields(arguments: argparse.Namespace, prefix: str) -> dict[str, O
 def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     subparsers = parser.add_subparsers(dest="command", required=True)
-    for command in ("validate", "route", "status"):
+    for command in ("validate", "route", "status", "prepare-build-recovery"):
         subparser = subparsers.add_parser(command)
         subparser.add_argument("--repo", required=True, type=Path)
         subparser.add_argument("--project-dir", default=".project")
@@ -2204,6 +2118,16 @@ def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
 
 def main(argv: Optional[Sequence[str]] = None) -> int:
     args = parse_args(argv)
+    if args.command in {"approve", "resume-checkpoint"}:
+        if __package__:
+            from . import state_checkpoint
+        else:
+            import state_checkpoint
+    elif args.command == "promote-next":
+        if __package__:
+            from . import state_promote
+        else:
+            import state_promote
     try:
         if args.command == "validate":
             result = validate_state(args.repo, args.project_dir)
@@ -2211,6 +2135,10 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             result = route_state(args.repo, args.project_dir)
         elif args.command == "status":
             result = status_state(args.repo, args.project_dir)
+        elif args.command == "prepare-build-recovery":
+            if args.project_dir != ".project":
+                raise PipelineStateError("build recovery requires the active track")
+            result = _build_recovery().prepare(args.repo)
         elif args.command == "transition":
             result = transition_state(
                 args.repo,
@@ -2224,7 +2152,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 raise PipelineStateError(
                     "--expected-head is not accepted with --defer-checkpoint or --patch"
                 )
-            result = defer_approval(
+            result = state_checkpoint.defer_approval(
                 args.repo,
                 args.kind,
                 args.project_dir,
@@ -2236,7 +2164,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 raise PipelineStateError(
                     "approve requires --expected-head unless --defer-checkpoint or --patch"
                 )
-            result = checkpoint_approval(
+            result = state_checkpoint.checkpoint_approval(
                 args.repo,
                 args.kind,
                 args.expected_head,
@@ -2244,7 +2172,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.milestone,
             )
         elif args.command == "resume-checkpoint":
-            result = resume_checkpoint(args.repo)
+            result = state_checkpoint.resume_checkpoint(args.repo)
         elif args.command == "promote-next":
             if args.integrate is not None and (
                 args.base is not None or args.landing is not None
@@ -2262,7 +2190,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 raise PipelineStateError(
                     "promote-next requires --base or legacy --integrate"
                 )
-            result = promote_next(
+            result = state_promote.promote_next(
                 args.repo,
                 args.milestone,
                 args.branch,