@opengsd/gsd-path 1.0.0 → 1.1.0

package/skills/gsd-path-inspect/scripts/state_promote.py

@@ -11,6 +11,31 @@ from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional
 
 
+if __package__:  # imported as scripts.state_promote
+    from . import pipeline_state, state_checkpoint
+    from .pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+else:  # standalone script or sibling import
+    import pipeline_state
+    import state_checkpoint
+    from pipeline_state import (
+        NULL,
+        PROMOTION_RESIDUAL,
+        PROMOTION_SCHEMA,
+        PROMOTION_TRACKS,
+        SLUG_RE,
+        PipelineState,
+        PipelineStateError,
+    )
+
+
 def _render_roadmap(
     text: str,
     previous_milestone: str,
@@ -243,9 +268,9 @@ def _completed_promotion(
     if _head_with_exact_message(repo, subject, fields) != head:
         raise PipelineStateError("completed promotion has the wrong commit message")
 
-    active_text = pipeline_state._git_text_at(repo, base, ".project/STATE.md")
-    next_text = pipeline_state._git_text_at(repo, base, ".project/next/STATE.md")
-    roadmap_text = pipeline_state._git_text_at(repo, base, ".project/ROADMAP.md")
+    active_text = state_checkpoint._git_text_at(repo, base, ".project/STATE.md")
+    next_text = state_checkpoint._git_text_at(repo, base, ".project/next/STATE.md")
+    roadmap_text = state_checkpoint._git_text_at(repo, base, ".project/ROADMAP.md")
     if active_text is None or next_text is None or roadmap_text is None:
         raise PipelineStateError("promotion parent is missing required metadata")
     active_state = pipeline_state._state_from_text(active_text, "promotion parent STATE.md")
@@ -265,7 +290,7 @@ def _completed_promotion(
         )
 
     _promotion_tree_mapping(repo, base, head)
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     expected_roadmap = _render_roadmap(
         roadmap_text,
         active_state.milestone,
@@ -273,11 +298,11 @@ def _completed_promotion(
         branch,
         landing,
     )
-    current_roadmap = pipeline_state._git_text_at(repo, head, ".project/ROADMAP.md")
+    current_roadmap = state_checkpoint._git_text_at(repo, head, ".project/ROADMAP.md")
     if current_roadmap != expected_roadmap:
         raise PipelineStateError("completed promotion has invalid ROADMAP.md")
 
-    current_state = pipeline_state._git_text_at(repo, head, ".project/STATE.md")
+    current_state = state_checkpoint._git_text_at(repo, head, ".project/STATE.md")
     if current_state is None:
         raise PipelineStateError("completed promotion has no STATE.md")
     event = re.escape(_promotion_event(drift, branch, landing, base))
@@ -438,10 +463,10 @@ def _prepare_promotion(
         if source.exists() or source.is_symlink():
             if destination.exists() or destination.is_symlink():
                 raise PipelineStateError(f"promotion destination already exists: {destination}")
-            tracks[name] = pipeline_state._tree_digest(source)
+            tracks[name] = state_checkpoint._tree_digest(source)
     if not tracks:
         raise PipelineStateError("lookahead track has no promotable artifacts")
-    drift = pipeline_state._classify_plan_drift(repo, next_state, base, landing)
+    drift = state_checkpoint._classify_plan_drift(repo, next_state, base, landing)
     roadmap_path = project / "ROADMAP.md"
     roadmap_text = pipeline_state._read_real_file(roadmap_path, "ROADMAP.md")
     target_state = _promotion_state(
@@ -464,10 +489,10 @@ def _prepare_promotion(
         "landing": landing,
         "base": base,
         "tracks": tracks,
-        "residual_sha256": pipeline_state._tree_digest(next_root, tuple(tracks)),
-        "next_state_sha256": pipeline_state._sha256(next_text),
-        "active_state_sha256": pipeline_state._sha256(active_text),
-        "roadmap_sha256": pipeline_state._sha256(roadmap_text),
+        "residual_sha256": state_checkpoint._tree_digest(next_root, tuple(tracks)),
+        "next_state_sha256": state_checkpoint._sha256(next_text),
+        "active_state_sha256": state_checkpoint._sha256(active_text),
+        "roadmap_sha256": state_checkpoint._sha256(roadmap_text),
         "target_state": target_state,
         "target_roadmap": target_roadmap,
         "drift": drift,
@@ -521,7 +546,7 @@ def _resume_track_moves(project: Path, journal: dict[str, object], path: Path) -
         if not source_exists and not destination_exists:
             raise PipelineStateError(f"promotion lost both source and destination: {name}")
         candidate = source if source_exists else destination
-        if pipeline_state._tree_digest(candidate) != expected_digest:
+        if state_checkpoint._tree_digest(candidate) != expected_digest:
             raise PipelineStateError(f"promotion track drifted: {name}")
         if source_exists:
             source.rename(destination)
@@ -542,7 +567,7 @@ def _resume_metadata(project: Path, journal: dict[str, object], path: Path) -> N
             raise PipelineStateError("promotion journal has invalid metadata")
         if current == desired:
             continue
-        if pipeline_state._sha256(current) != expected_original:
+        if state_checkpoint._sha256(current) != expected_original:
             raise PipelineStateError(f"promotion metadata drifted: {target}")
         pipeline_state._atomic_write(target, desired)
         journal["stage"] = f"updated:{target.name}"
@@ -560,9 +585,9 @@ def _resume_next_removal(
         if residual.exists() or residual.is_symlink():
             raise PipelineStateError("promotion has both next track and residual staging")
         next_text = pipeline_state._read_real_file(next_root / "STATE.md", "next/STATE.md")
-        if pipeline_state._sha256(next_text) != journal.get("next_state_sha256"):
+        if state_checkpoint._sha256(next_text) != journal.get("next_state_sha256"):
             raise PipelineStateError("lookahead STATE drifted during promotion")
-        if pipeline_state._tree_digest(next_root) != journal.get("residual_sha256"):
+        if state_checkpoint._tree_digest(next_root) != journal.get("residual_sha256"):
             raise PipelineStateError("lookahead residual drifted during promotion")
         next_root.rename(residual)
         journal["stage"] = "next-staged"
@@ -574,7 +599,7 @@ def _resume_next_removal(
         raise PipelineStateError("promotion lost next track and residual staging")
     if residual.is_symlink() or not residual.is_dir():
         raise PipelineStateError(f"promotion residual must be a real directory: {residual}")
-    if pipeline_state._tree_digest(residual) != journal.get("residual_sha256"):
+    if state_checkpoint._tree_digest(residual) != journal.get("residual_sha256"):
         raise PipelineStateError("staged lookahead residual drifted during promotion")
 
 
@@ -714,30 +739,3 @@ def promote_next(
         "commit": commit,
         "drift": journal["drift"],
     }
-
-
-# pipeline_state 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 pipeline_state stay visible here.
-if __package__:  # imported as scripts.state_promote
-    from . import pipeline_state
-    from .pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )
-else:  # standalone script or sibling import
-    import pipeline_state
-    from pipeline_state import (
-        NULL,
-        PROMOTION_RESIDUAL,
-        PROMOTION_SCHEMA,
-        PROMOTION_TRACKS,
-        SLUG_RE,
-        PipelineState,
-        PipelineStateError,
-    )

package/skills/gsd-path-inspect/scripts/workflow_run.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""Run canonical workflow helpers with fixed arguments and fail-stop receipts."""
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    from scripts import _common
+except ImportError:  # bundled copy inside a skill's scripts directory
+    import _common
+
+
+class StepFailed(RuntimeError):
+    pass
+
+INSPECTION_SPECS = (("inspect_codebase", "codebase-mapper", "codebase", "evidence-codebase.md"),
+                    ("inspect_docs", "docs-auditor", "docs-audit", "DOCS-AUDIT.md"))
+
+
+def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str = None,
+                 task_id: str = None, round_size: int = None, inspection: Path = None,
+                 mapper_reviewed: bool = False) -> dict:
+    steps = []
+    outputs = {}
+    scripts = Path(__file__).resolve().parent
+
+    def step(script, *arguments, raw=False):
+        command = [sys.executable, "-B", str(scripts / script), *arguments]
+        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        receipt = {"script": script, "command": command, "exit_code": completed.returncode,
+                   "stdout": completed.stdout, "stderr": completed.stderr}
+        steps.append(receipt)
+        if completed.stderr:
+            sys.stderr.write(completed.stderr)
+        if completed.returncode:
+            raise StepFailed(script)
+        if raw:
+            return completed.stdout
+        try:
+            receipt["result"] = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            raise StepFailed(f"{script} did not return JSON") from error
+        return receipt["result"]
+
+    common = ["--repo", str(repo), "--project-dir", project_dir]
+    try:
+        if action == "route":
+            step("pipeline_state.py", "route", *common)
+        elif action == "prepare-inspect":
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if project_dir != ".project" or state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("initial inspection requires the active inspect track")
+            specs = INSPECTION_SPECS
+            if any((repo / project_dir / "research" / spec[3]).exists() or
+                   (repo / project_dir / "research" / spec[3]).is_symlink() for spec in specs):
+                raise StepFailed("prior inspection evidence requires the re-inspection contract")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if branch != state["branch"]:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            inventory = step("check_docs_audit.py", "--repo", str(repo), "--emit-inventory", raw=True)
+            resources = scripts.parent
+            if not (resources / "references").is_dir():
+                resources = resources / "skills/gsd-path"
+            for _, role, template, _ in specs:
+                for path in (resources / "references" / f"{role}.md", resources / "templates" / f"{template}.md"):
+                    if not path.is_file():
+                        raise StepFailed(f"missing inspection resource: {path}")
+            staging = Path(tempfile.mkdtemp(prefix="gsd-path-inspect-"))
+            inventory_file = staging / "inventory.txt"
+            inventory_file.write_text(inventory, encoding="utf-8")
+            assignments = []
+            for task_name, role, template, filename in specs:
+                isolated = step("isolation.py", "isolate-verify", "--repo", str(repo),
+                                "--base", expected_head, "--name", task_name.replace("_", "-"))
+                role_path = resources / "references" / f"{role}.md"
+                template_path = resources / "templates" / f"{template}.md"
+                output = f"{project_dir}/research/{filename}"
+                brief_file = staging / f"{task_name}.md"
+                brief = (f"Logical task: {task_name}\nRead and follow role: {role_path}\n"
+                         f"Template: {template_path}\nRepository and command cwd: {isolated['worktree']}\n"
+                         f"Recorded baseline and Audited HEAD: {isolated['base']}\n"
+                         f"Write only: {Path(isolated['worktree']) / output}\n"
+                         "Use only this supplied sidecar for project commands; do not create worktrees.\n"
+                         "The parent owns gates, collection, retirement, and phase state.\n"
+                         "Exclude .git, node_modules, .project/archive, and installed GSD Path and path skill bundles.\n")
+                if task_name == "inspect_docs":
+                    brief += ("Alignment mode: false. No prior audit or changed set.\n"
+                              "Frozen inventory follows; use it exactly, without rediscovery:\n" + inventory)
+                brief_file.write_text(brief, encoding="utf-8")
+                assignments.append({**isolated, "task_name": task_name, "role": str(role_path),
+                                    "template": str(template_path), "output": output,
+                                    "brief_file": str(brief_file)})
+            receipt_file = staging / "inspection.json"
+            outputs["inspection"] = {"repo": str(repo), "base": expected_head,
+                                     "inventory_file": str(inventory_file),
+                                     "inventory_sha256": hashlib.sha256(inventory_file.read_bytes()).hexdigest(),
+                                     "assignments": assignments, "receipt_file": str(receipt_file)}
+            _common.atomic_write(receipt_file, json.dumps(outputs["inspection"], sort_keys=True) + "\n")
+        elif action == "finish-inspect":
+            if not mapper_reviewed or inspection is None or project_dir != ".project":
+                raise StepFailed("finish-inspect requires the prepared active track and mapper review")
+            prepared = json.loads(inspection.read_text(encoding="utf-8"))
+            if prepared["repo"] != str(repo) or prepared["base"] != expected_head:
+                raise StepFailed("inspection receipt does not match repository and expected HEAD")
+            assignments = {a["task_name"]: a for a in prepared["assignments"]}
+            if len(prepared["assignments"]) != len(INSPECTION_SPECS) or set(assignments) != {s[0] for s in INSPECTION_SPECS}:
+                raise StepFailed("inspection receipt must name both original assignments")
+            for task_name, _, _, filename in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                if assignment["base"] != expected_head or assignment["output"] != f".project/research/{filename}":
+                    raise StepFailed("inspection assignment changed its baseline or output")
+            inventory_file = Path(prepared["inventory_file"])
+            if hashlib.sha256(inventory_file.read_bytes()).hexdigest() != prepared["inventory_sha256"]:
+                raise StepFailed("frozen inspection inventory changed")
+            state = step("pipeline_state.py", "validate", *common)["state"]
+            if state["phase"] != "inspect" or state["status"] != "active":
+                raise StepFailed("inspection completion requires inspect/active")
+            branch = subprocess.run(["git", "branch", "--show-current"], cwd=repo,
+                                    capture_output=True, text=True, check=True).stdout.strip()
+            if state["branch"] != branch:
+                raise StepFailed("current branch differs from the recorded inspection branch")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            docs = assignments["inspect_docs"]
+            step("check_docs_audit.py", "--repo", docs["worktree"], "--audit", docs["output"],
+                 "--inventory", str(inventory_file))
+            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text().splitlines():
+                raise StepFailed("audit does not name the supplied inspection baseline")
+            for task_name, _, _, _ in INSPECTION_SPECS:
+                assignment = assignments[task_name]
+                step("isolation.py", "collect-artifact", "--repo", str(repo),
+                     "--source", assignment["worktree"], "--base", expected_head,
+                     "--branch", assignment["branch"], "--source-path", assignment["output"],
+                     "--destination-path", assignment["output"])
+                step("isolation.py", "retire", "--repo", str(repo), "--worktree", assignment["worktree"],
+                     "--branch", assignment["branch"])
+            expected = [part for key, value in state.items()
+                        for part in (f"--expect-{key}", "null" if value is None else str(value))]
+            step("pipeline_state.py", "transition", *common, *expected,
+                 "--set-phase", "inspect", "--set-status", "done", "--event", "inspection artifacts passed")
+        elif action == "lint-round":
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task":
+            task = step("isolation.py", "isolate-task", "--repo", str(repo),
+                        "--base", expected_head, "--task-id", task_id,
+                        "--round-size", str(round_size))
+            if task["mode"] == "serial":
+                step("isolation.py", "isolate-verify", "--repo", str(repo),
+                     "--base", expected_head, "--name", f"task-{task_id.lower()}-verify")
+        elif action == "build-evidence":
+            proof = step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            # The landing proof has one canonical home; lean final-review reuse allows only this path.
+            evidence = repo / project_dir / "build" / "evidence.json"
+            _common.atomic_write(evidence, json.dumps(proof, indent=2, sort_keys=True) + "\n")
+            steps.append({"script": "workflow_run.py", "evidence": str(evidence)})
+        elif action == "prepare-final":
+            if project_dir != ".project":
+                raise StepFailed("final review requires the active milestone")
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("build_state.py", "verify-landed", *common, "--head", expected_head)
+            step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head)
+        else:
+            pending = step("discussion_records.py", "pending", "--repo", str(repo))
+            if pending["pending"]:
+                raise StepFailed("pending discussion requires its owner disposition")
+            step("check_handoffs.py", "plan", *common)
+            head = subprocess.run(["git", "rev-parse", "--verify", "HEAD"],
+                                  cwd=repo, capture_output=True, text=True, check=True).stdout.strip()
+            step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+                 "--tasks-dir", f"{project_dir}/tasks")
+            panel = ["validate-plan", "--plan", str(repo / project_dir / "plan/PLAN.md"),
+                     "--intent", str(repo / project_dir / "intent/INTENT.md")]
+            charter = repo / ".project/CHARTER.md"
+            if charter.exists():
+                panel += ["--charter", str(charter)]
+            step("review_panel.py", *panel)
+            if action == "approve-plan":
+                step("pipeline_state.py", "approve", *common, "--kind", "plan",
+                     "--expected-head", expected_head)
+    except (StepFailed, OSError, subprocess.CalledProcessError, ValueError, KeyError, TypeError) as error:
+        return {"status": "blocked", "reason": str(error), "steps": steps,
+                "next": "$gsd-path-forensics"}
+    return {"status": "complete", "steps": steps, **outputs}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"))
+    parser.add_argument("--repo", type=Path, required=True)
+    parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
+    parser.add_argument("--expected-head")
+    parser.add_argument("--task-id")
+    parser.add_argument("--round-size", type=int)
+    parser.add_argument("--inspection", type=Path)
+    parser.add_argument("--mapper-reviewed", action="store_true")
+    arguments = parser.parse_args(argv)
+    if arguments.action in {"approve-plan", "build-evidence", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect"} and not arguments.expected_head:
+        parser.error(f"{arguments.action} requires --expected-head")
+    if arguments.action == "prepare-task" and (not arguments.task_id or arguments.round_size is None):
+        parser.error("prepare-task requires --task-id and --round-size")
+    result = run_workflow(arguments.repo.resolve(), arguments.action,
+                          arguments.project_dir, arguments.expected_head,
+                          arguments.task_id, arguments.round_size, arguments.inspection,
+                          arguments.mapper_reviewed)
+    print(json.dumps(result, sort_keys=True))
+    return 0 if result["status"] == "complete" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/gsd-path-plan/SKILL.md

@@ -29,8 +29,11 @@ Before dispatch, enter from `decide/done` or `define/done` with
 `--set-phase plan --set-status active`, and event `planning started`. Resume
 `plan/blocked` through the same helper with event `planning resumed`. Require
 the returned track state to be `plan/active`; never edit STATE directly.
-Any later phase blocks instead of replacing an approved plan. Patch mode is
-the only reopen exception: require an approved plan, no in-progress task, and
+For a blocked build, use the [build recovery contract](references/build-recovery.md).
+The runtime's `build-repair` mode owns structural changes to the remaining task
+inventory and the normal approval checkpoint; it is distinct from append-only
+patch mode. Otherwise later phases block instead of replacing an approved plan.
+Patch mode requires an approved plan, no in-progress task, and
 state `plan/done` or `ship/blocked`; any other state blocks. `build/done` is
 reserved exclusively for the build orchestrator's transition recovery and
 must return there instead of reopening planning. When an active router
@@ -74,10 +77,17 @@ router supplied lookahead mode. Every per-milestone path below, including
 review-panel evidence, is rooted there. Program inputs remain at `.project/`
 as stated in Lookahead mode.
 
-1. Read the local [plan template](templates/plan.md), [task template](templates/task.md),
-   [plan-panel template](templates/plan-panel.md), `scripts/check_handoffs.py`,
-   and `scripts/review_panel.py`; resolve them to absolute paths.
-2. Read the local [planner role](references/planner.md), then follow the
+1. Resolve the local [plan template](templates/plan.md), [task template](templates/task.md),
+   `scripts/check_handoffs.py`, and `scripts/review_panel.py` to absolute paths.
+   Quick mode reads the plan and task templates because the parent writes
+   those artifacts. Other modes pass their paths to the planner. Execute the
+   helpers through the commands below and consume their results; their Python
+   source is not planning input. Read helper source only when diagnosing a
+   concrete failure that the returned error and documented recovery cannot
+   explain.
+2. In quick mode, skip planner dispatch and follow Quick mode below; do not
+   load the planner role or dispatch contract. In other modes, resolve the
+   local [planner role](references/planner.md) for the child, then follow the
    local [runtime dispatch contract](references/dispatch.md) with deterministic
    logical task name `plan`. Give it absolute role, `AGENTS.md`, `WORKFLOW.md`,
    input, template, and output paths, including `.project/LESSONS.md` when it
@@ -133,7 +143,7 @@ as stated in Lookahead mode.
    - Require a `Review depth` value (`full`, `deep`, or `verify-only`) on
      every wave. Wave 1 and any wave touching authentication, authorization,
      payments, data migration, or concurrency requires `full` or `deep`;
-     quick-lane single waves may use `verify-only`. The planner assigns `deep`
+     this includes quick-lane single waves. The planner assigns `deep`
      sparingly to waves where a wrong merge is irreversible or
      security-critical.
    - When INTENT.md `Surfaces:` is not `none`, require a PLAN.md
@@ -199,7 +209,9 @@ as stated in Lookahead mode.
    - `status: error` or exit 2 — use the same guarded transition to set
      `plan/blocked` with an event naming the helper error, link PLAN.md, and stop.
      A named family that is not advertised is an assertion failure.
-   - `status: ready` — for each selected family, spawn one independent child
+   - `status: ready` — resolve the local
+     [plan-panel template](templates/plan-panel.md) for the reviewers; other
+     statuses do not load this template. For each selected family, spawn one independent child
      with logical task name `review_plan_panel_<family>`, the reviewer role
      in plan-panel mode, the plan-panel template, and the exact helper-returned
      model slug when the host advertises model selection. Never override the
@@ -257,12 +269,8 @@ as stated in Lookahead mode.
    (event `patch plan approved`) without a plan checkpoint because build's
    patch re-entry commits the artifacts with its `build/active` transition.
    `pipeline_state.py transition` never approves a plan. Confirm approval,
-   link PLAN.md again, and state that
-   build starts next. Do not add another approval gate. When routed by an
-   active `$gsd-path`, return control to that router so its bundled build
-   contract starts. When invoked directly, stop and tell the user to explicitly
-   invoke `$gsd-path`, which routes to build; do not invoke an explicit-only
-   sibling skill yourself.
+   link PLAN.md again, and use the executable phase handoff in AGENTS.md.
+   The plan approval also authorizes build; do not add another approval gate.
 
 ## Ordering rules
 
@@ -273,8 +281,8 @@ as stated in Lookahead mode.
 ## Quick mode
 
 Legal entry: `define/done` where INTENT.md records `Lane: quick` (transition
-to `plan/active`, logging that research and decide were skipped for the
-quick lane). Quick mode dispatches no planner agent — the orchestrator writes
+to `plan/active` using exactly the Preconditions event `planning started`;
+record the skipped research and decide phases in the synthesis). Quick mode dispatches no planner agent — the orchestrator writes
 the artifacts directly:
 
 1. Write `.project/research/SYNTHESIS.md` containing only `## Settled` lines
@@ -282,7 +290,7 @@ the artifacts directly:
    plus a minimal `## For the planner` naming the walking skeleton. No
    invented decisions or runner-ups.
 2. Write `.project/plan/PLAN.md` with exactly one wave — `Review depth:
-   verify-only` permitted — and at most two deliverable-sized task files
+   full` or `deep` — and at most two deliverable-sized task files
    (project policy),
    honoring every task-contract rule above and `.project/LESSONS.md` when it
    exists. Write `review_panel: off` and `finding_skeptics: off` regardless

package/skills/gsd-path-plan/references/build-recovery.md

@@ -0,0 +1,78 @@
+# Return a blocked build to its contract owner
+
+Use this contract only for an active milestone at `build/blocked`: a documented
+structural plan defect, or an explicit user ruling that changes approved intent.
+It does not reopen ship, archived milestones, or lookahead. Build owns entry;
+Define owns intent corrections; Plan owns the replacement task inventory and
+approval. Routing remains a caller handoff under AGENTS.md.
+
+## Build: checkpoint and enter
+
+1. Record the finding or verbatim user ruling in STATE through its helper.
+   Stop dispatch. Use the normal recovery and retirement procedures until
+   every task is either unstarted `pending` with null dispatch metadata or
+   proven `done`. Preserve owned uncommitted work before any retirement.
+   Settle reviewers and their sidecars too. Dispatch records must have no pending
+   cleanup; records with reviewer `worktree` and `branch` ownership must also
+   record `cleanup_complete`. A `blocked` or `collected` outcome alone does not
+   prove retirement. Records that never owned a reviewer sidecar do not require
+   that retirement receipt. Use the existing dispatch retirement procedures;
+   recovery does not retire sidecars itself. Never infer that a timed-out child
+   stopped. Checkpoint the blocked state and artifacts using the Build
+   bookkeeping contract; the primary must be clean.
+2. Run `pipeline_state.py transition` with the complete current state expected,
+   `--set-status active`, and the matching target and event:
+
+   | Cause | Target | Exact event |
+   | --- | --- | --- |
+   | User changes a criterion, constraint, or veto | `--set-phase define` | `build intent corrections requested` |
+   | Task inventory, dependency, or wave repair | `--set-phase plan` | `build plan repair requested` |
+
+   The helper records the committed recovery base in STATE atomically. Do not
+   author or edit that record. Milestone, branch, integration settings, and
+   landed task contracts remain fixed throughout recovery.
+3. Return to the router or name the selected explicit skill. The route names
+   `corrections` for Define and `build-repair` for Plan. Other blocked-build
+   failures continue through ordinary Build recovery.
+
+## Define and Plan: prepare before editing
+
+Run the bundled `pipeline_state.py prepare-build-recovery --repo <absolute-root>`
+before changing any recovery artifact. This repeatable operation preserves the
+old review directory under `plan/build-recovery-<base>/review` and starts a fresh
+active review directory. STATE's recorded base owns an interrupted move; rerun
+this command to finish it. The helper validates the preserved bytes against Git.
+Do not remove, rewrite, or use the preserved reviews as current approval.
+
+**Define corrections.** Read the existing intent and governing program artifacts.
+Interview only the requested change; append the user's words under
+`## Corrections`, revise the affected intent, and present the delta for approval.
+Keep the milestone identity. Reclassify the lane using the normal lane rules.
+After approval, use the normal `define/active → define/done` transition and route
+from the approved lane. Standard intent goes through Research and Decide again;
+quick and milestone intent use their existing evidence gates. A program charter
+or roadmap conflict still requires its legal owner gate; this path cannot waive it.
+
+**Plan build-repair.** Read the corrected intent, current synthesis, existing plan,
+task files, and recovery base. Use the normal planner, lint, panel, and approval
+gates. Repair the remaining task inventory as needed, including split, rename,
+dependency, or wave changes. Keep IDs ordered and contiguous. Preserve every
+landed task file byte-for-byte, including its recorded base and proof. Any new
+work to satisfy a corrected criterion belongs in new pending tasks, not rewritten
+landed contracts. A plan-only recovery must not change approved intent.
+
+## Approve and return to Build
+
+Use normal `pipeline_state.py approve --kind plan --expected-head <HEAD>`.
+Neither `--patch` nor `--defer-checkpoint` is legal for recovery. The helper
+checks landed-task preservation and restored intent ownership, restores review
+evidence only for unchanged contracts, and creates the normal journaled plan
+checkpoint. A failed approval leaves recovery open.
+
+Return through `plan/done → build/active` with event `build started`. The dispatch
+driver uses a separate record directory for this recovery base, while retaining
+the milestone budget ledger. Resume only from the new approved task inventory.
+Unchanged wave evidence remains usable; changed waves need review in the new
+record directory. Retained task Verify receipts remain historical evidence for
+their original task and base, never proof for a changed task. Final review still
+requires current-HEAD evidence before shipment.

package/skills/gsd-path-plan/references/dispatch.md

@@ -122,6 +122,12 @@ directory for the full logical session; resumptions reuse it. Record completed
 parent CLI run events and each native child's session events with stable logical
 task names before the next dispatch. The helper reads host counters and refuses
 incomplete or ambiguous usage; never estimate tokens or reset the ledger.
+When the verified CLI adapter reports cumulative counters across `resume`, record
+each later invocation with `--previous-events <previous recorded CLI events>`.
+The helper checks thread identity and records only the new output, preserving the
+raw total and predecessor. Keep that chain in order; never sum cumulative totals.
+Use ordinary `record` for per-invocation counters. An unknown counter convention
+is unproven usage, not permission to guess.
 Run `admit` for the next task and stop dispatch on a blocked result. Preserve
 its output in the dispatch evidence. This gates observed usage only: concurrent
 or in-flight work can overrun before the host reports usage. Codex CLI has no