@opengsd/gsd-path 1.0.0 → 1.1.0

package/scripts/archive_milestone.py

@@ -239,15 +239,10 @@ class ArchiveError(RuntimeError):
 
 
 PIPELINE_MARKER = _common.PIPELINE_MARKER
-PR_CREDIT_LINE = (
-    "PR prepared with [GSD Path](https://github.com/open-gsd/gsd-path)."
-)
-GITHUB_HOST = "github.com"
 
 
-# discussion_validate and integration call back into this module through a
-# module reference and import the constants and ArchiveError above, so this
-# import must stay below those definitions.
+# discussion_validate calls back into this module and imports its constants
+# and ArchiveError, so this import must stay below those definitions.
 if __package__:  # imported as scripts.archive_milestone
     from .discussion_validate import (
         record_sections,
@@ -280,42 +275,6 @@ if __package__:  # imported as scripts.archive_milestone
         render_manifest,
         validate_manifest,
     )
-    from .integration import (
-        resolve_remote_default,
-        live_remote_ref,
-        publish_bound_branch,
-        refresh_origin,
-        optional_ref,
-        integration_names,
-        registered_worktree,
-        remove_registered_worktree,
-        delete_integration_branch,
-        require_generated_integration_commit,
-        discard_unpublished_stale_integration,
-        create_integration_merge,
-        require_annotated_tag,
-        ensure_integration_tag,
-        github_repository,
-        require_github_authentication,
-        github_api_json,
-        require_pull_request_shape,
-        require_pull_request_pages,
-        pull_request_head_matches_repository,
-        require_pull_request_identity,
-        find_pull_request,
-        pull_request_body,
-        update_pull_request_body,
-        create_pull_request,
-        pull_request_tag_message,
-        pull_request_tag_metadata,
-        require_pull_request_merge,
-        require_pull_request_merge_provenance,
-        integrate_pull_request,
-        integrate,
-        find_integrate_commit,
-        validate_integrated,
-        require_published_integration,
-    )
 else:  # standalone script or sibling import
     if __name__ == "__main__":
         sys.modules.setdefault("archive_milestone", sys.modules[__name__])
@@ -351,42 +310,6 @@ else:  # standalone script or sibling import
             render_manifest,
             validate_manifest,
         )
-        from integration import (
-            resolve_remote_default,
-            live_remote_ref,
-            publish_bound_branch,
-            refresh_origin,
-            optional_ref,
-            integration_names,
-            registered_worktree,
-            remove_registered_worktree,
-            delete_integration_branch,
-            require_generated_integration_commit,
-            discard_unpublished_stale_integration,
-            create_integration_merge,
-            require_annotated_tag,
-            ensure_integration_tag,
-            github_repository,
-            require_github_authentication,
-            github_api_json,
-            require_pull_request_shape,
-            require_pull_request_pages,
-            pull_request_head_matches_repository,
-            require_pull_request_identity,
-            find_pull_request,
-            pull_request_body,
-            update_pull_request_body,
-            create_pull_request,
-            pull_request_tag_message,
-            pull_request_tag_metadata,
-            require_pull_request_merge,
-            require_pull_request_merge_provenance,
-            integrate_pull_request,
-            integrate,
-            find_integrate_commit,
-            validate_integrated,
-            require_published_integration,
-        )
     except ImportError:  # pragma: no cover - package import used by tests
         from scripts.discussion_validate import (
             record_sections,
@@ -419,42 +342,6 @@ else:  # standalone script or sibling import
             render_manifest,
             validate_manifest,
         )
-        from scripts.integration import (
-            resolve_remote_default,
-            live_remote_ref,
-            publish_bound_branch,
-            refresh_origin,
-            optional_ref,
-            integration_names,
-            registered_worktree,
-            remove_registered_worktree,
-            delete_integration_branch,
-            require_generated_integration_commit,
-            discard_unpublished_stale_integration,
-            create_integration_merge,
-            require_annotated_tag,
-            ensure_integration_tag,
-            github_repository,
-            require_github_authentication,
-            github_api_json,
-            require_pull_request_shape,
-            require_pull_request_pages,
-            pull_request_head_matches_repository,
-            require_pull_request_identity,
-            find_pull_request,
-            pull_request_body,
-            update_pull_request_body,
-            create_pull_request,
-            pull_request_tag_message,
-            pull_request_tag_metadata,
-            require_pull_request_merge,
-            require_pull_request_merge_provenance,
-            integrate_pull_request,
-            integrate,
-            find_integrate_commit,
-            validate_integrated,
-            require_published_integration,
-        )
 
 
 @contextmanager
@@ -2238,6 +2125,11 @@ def parser() -> argparse.ArgumentParser:
 def main(argv: Optional[Sequence[str]] = None) -> int:
     arguments = parser().parse_args(argv)
     try:
+        if arguments.command in {"validate-integrated", "refresh-origin", "integrate"}:
+            if __package__:
+                from . import integration
+            else:
+                import integration
         if arguments.command == "prepare":
             result = prepare(arguments.repo, arguments.slug)
         elif arguments.command == "render-manifest":
@@ -2247,11 +2139,11 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         elif arguments.command == "abandon":
             result = abandon(arguments.repo, arguments.slug, arguments.reason)
         elif arguments.command == "validate-integrated":
-            result = validate_integrated(arguments.repo, arguments.slug)
+            result = integration.validate_integrated(arguments.repo, arguments.slug)
         elif arguments.command == "refresh-origin":
-            result = refresh_origin(arguments.repo)
+            result = integration.refresh_origin(arguments.repo)
         elif arguments.command == "integrate":
-            result = integrate(arguments.repo, arguments.slug)
+            result = integration.integrate(arguments.repo, arguments.slug)
         else:
             result = validate(arguments.repo)
     except (ArchiveError, OSError) as error:

package/scripts/bootstrap_repository.py

@@ -32,6 +32,7 @@ class BootstrapRequest:
     worktree: str
     branch: str
     description: Optional[str]
+    reuse_empty_worktree: bool = False
 
     @property
     def repository(self) -> str:
@@ -95,6 +96,8 @@ def request_from_arguments(arguments: argparse.Namespace) -> BootstrapRequest:
     if arguments.visibility not in {"public", "private", "internal"}:
         raise BootstrapError("visibility must be public, private, or internal")
 
+    if arguments.reuse_empty_worktree and arguments.worktree.is_symlink():
+        raise BootstrapError("linked worktree must not be a symlink")
     workspace = arguments.workspace.resolve()
     checkout = arguments.default_checkout.resolve()
     worktree = arguments.worktree.resolve()
@@ -116,6 +119,7 @@ def request_from_arguments(arguments: argparse.Namespace) -> BootstrapRequest:
         worktree=str(worktree),
         branch="gsd-path/M001",
         description=arguments.description,
+        reuse_empty_worktree=arguments.reuse_empty_worktree,
     )
 
 
@@ -148,7 +152,10 @@ def transaction_directory(request: BootstrapRequest, create: bool = False) -> Pa
 
 
 def request_payload(request: BootstrapRequest) -> dict:
-    return {"schema": "gsd-path/new-github/v1", **asdict(request)}
+    payload = {"schema": "gsd-path/new-github/v1", **asdict(request)}
+    if not request.reuse_empty_worktree:
+        del payload["reuse_empty_worktree"]
+    return payload
 
 
 def read_journal(request: BootstrapRequest) -> Optional[dict]:
@@ -272,6 +279,16 @@ def transaction_stages(request: BootstrapRequest) -> dict:
     }
 
 
+def reusable_empty_worktree(request: BootstrapRequest) -> bool:
+    path = request.worktree_path
+    return (
+        request.reuse_empty_worktree
+        and not path.is_symlink()
+        and path.is_dir()
+        and not any(path.iterdir())
+    )
+
+
 def preview(request: BootstrapRequest) -> dict:
     gh_authentication()
     stages = transaction_stages(request)
@@ -288,8 +305,12 @@ def preview(request: BootstrapRequest) -> dict:
         ("default checkout", request.checkout_path),
         ("linked worktree", request.worktree_path),
     ):
+        if path == request.worktree_path and reusable_empty_worktree(request):
+            continue
         if path.exists() or path.is_symlink():
-            raise BootstrapError(f"{label} path already exists: {path}")
+            raise BootstrapError(
+                f"{label} path already exists: {path}; preserve it and choose another path"
+            )
     return {**request_payload(request), "mode": "create", "stages": stages}
 
 
@@ -448,7 +469,7 @@ def allowed_partial_project_status(worktree: Path) -> bool:
 def create_or_verify_worktree(request: BootstrapRequest, base: str) -> None:
     checkout = request.checkout_path
     worktree = request.worktree_path
-    if not worktree.exists():
+    if not worktree.exists() or reusable_empty_worktree(request):
         branch_ref = f"refs/heads/{request.branch}"
         branch = run("git", "-C", str(checkout), "rev-parse", "--verify", branch_ref)
         if branch.returncode == 0:
@@ -680,6 +701,7 @@ def parser() -> argparse.ArgumentParser:
     argument_parser.add_argument("--default-checkout", type=Path, required=True)
     argument_parser.add_argument("--worktree", type=Path, required=True)
     argument_parser.add_argument("--description")
+    argument_parser.add_argument("--reuse-empty-worktree", action="store_true")
     argument_parser.add_argument("--state-template", type=Path)
     argument_parser.add_argument("--repository-template", type=Path)
     return argument_parser

package/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/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/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/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/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/scripts/git_guard.py

@@ -114,7 +114,8 @@ def message_of(message_file):
         lines.pop(0)
     if not lines:
         return "", ""
-    return lines[0].strip(), "\n".join(lines[1:]).strip("\n")
+    subject_end = lines.index("") if "" in lines else len(lines)
+    return " ".join(line.strip() for line in lines[:subject_end]), "\n".join(lines[subject_end:]).strip("\n")
 
 
 def archive_root(path):

package/scripts/install.mjs

@@ -15,6 +15,7 @@ export const GUARD_SCRIPTS = ["guard_hook.py", "git_guard.py"];
 export const GUARD_MARKER = "gsd-path guard";
 export const PROJECT_RUNTIME_SCRIPTS = [
   "pipeline_state.py",
+  "roadmap.py",
   "check_handoffs.py",
   "check_task_briefs.py",
   "isolation.py",
@@ -27,6 +28,7 @@ export const PROJECT_RUNTIME_SCRIPTS = [
   "archive_milestone.py",
   "review_panel.py",
   "_common.py",
+  "build_recovery.py",
   "state_checkpoint.py",
   "state_promote.py",
   "discussion_validate.py",