@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/path/scripts/workflow_run.py

@@ -5,27 +5,45 @@ import argparse
 import hashlib
 import json
 import os
+import re
 import subprocess
 import sys
 import tempfile
 from pathlib import Path
 
 try:
-    from scripts import _common
+    from scripts import _common, isolation
 except ImportError:  # bundled copy inside a skill's scripts directory
     import _common
+    import isolation
 
 
 class StepFailed(RuntimeError):
     pass
 
+
+def _table_rows(body):
+    """Cells of a Markdown table's data rows (header and separator skipped)."""
+    lines = [line.strip() for line in (body or "").splitlines() if line.strip().startswith("|")]
+    return [[cell.strip() for cell in re.split(r"(?<!\\)\|", line.strip("|"))] for line in lines[2:]]
+
 INSPECTION_SPECS = (("inspect_codebase", "codebase-mapper", "codebase", "evidence-codebase.md"),
                     ("inspect_docs", "docs-auditor", "docs-audit", "DOCS-AUDIT.md"))
 
 
+def _task_member(repo: Path, project_dir: str, task_id: str):
+    """The `repo:` member a task names, or None for a coordinator task."""
+    for path in sorted((repo / project_dir / "tasks").glob(f"{task_id}-*.md")):
+        fields, error = isolation.task_frontmatter(path.read_text(encoding="utf-8"))
+        if error:
+            raise StepFailed(error)
+        return fields.get("repo")
+    return None
+
+
 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:
+                 mapper_reviewed: bool = False, kind: str = None) -> dict:
     steps = []
     outputs = {}
     scripts = Path(__file__).resolve().parent
@@ -33,7 +51,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
 
     def step(script, *arguments, raw=False):
         command = [sys.executable, "-B", str(helpers / script), *arguments]
-        completed = subprocess.run(command, cwd=repo, capture_output=True, text=True)
+        completed = subprocess.run(command, cwd=repo, capture_output=True, encoding="utf-8", errors="replace")
         receipt = {"script": script, "command": command, "exit_code": completed.returncode,
                    "stdout": completed.stdout, "stderr": completed.stderr}
         steps.append(receipt)
@@ -50,12 +68,29 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
         return receipt["result"]
 
     common = ["--repo", str(repo), "--project-dir", project_dir]
+    next_step = "$gsd-path-forensics"
+
+    def gate_plan():
+        if step("discussion_records.py", "pending", "--repo", str(repo))["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, encoding="utf-8", errors="replace", check=True).stdout.strip()
+        step("check_task_briefs.py", "--repo", str(repo), "--base", head,
+             "--tasks-dir", f"{project_dir}/tasks", "--project-dir", project_dir)
+        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)]
+        return step("review_panel.py", *panel)
+
     try:
         if os.path.lexists(repo / ".gsd-path/runtime.json"):
             resolved = subprocess.run(
                 [sys.executable, "-B", str(repo / ".gsd-path/status_runtime.py"),
                  "--repo", str(repo), "--runtime-path"],
-                cwd=repo, capture_output=True, text=True)
+                cwd=repo, capture_output=True, encoding="utf-8", errors="replace")
             if resolved.returncode:
                 sys.stderr.write(resolved.stderr)
                 raise StepFailed(resolved.stderr.strip())
@@ -71,7 +106,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                    (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()
+                                    capture_output=True, encoding="utf-8", errors="replace", 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))
@@ -87,7 +122,7 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                         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")
+            inventory_file.write_bytes(inventory.encode("utf-8"))
             assignments = []
             for task_name, role, template, filename in specs:
                 isolated = step("isolation.py", "isolate-verify", "--repo", str(repo),
@@ -100,13 +135,14 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                          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"
+                         f"Write header Repo root: {repo}\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")
+                brief_file.write_bytes(brief.encode("utf-8"))
                 assignments.append({**isolated, "task_name": task_name, "role": str(role_path),
                                     "template": str(template_path), "output": output,
                                     "brief_file": str(brief_file)})
@@ -136,16 +172,16 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             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()
+                                    capture_output=True, encoding="utf-8", errors="replace", 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():
+            step("check_docs_audit.py", "--repo", docs["worktree"], "--primary", str(repo),
+                 "--audit", docs["output"], "--inventory", str(inventory_file))
+            if f"Audited HEAD: {expected_head}" not in (Path(docs["worktree"]) / docs["output"]).read_text(encoding="utf-8").splitlines():
                 raise StepFailed("audit does not name the supplied inspection baseline")
             for task_name, _, _, _ in INSPECTION_SPECS:
                 assignment = assignments[task_name]
@@ -161,10 +197,14 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                  "--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()
+                                  cwd=repo, capture_output=True, encoding="utf-8", errors="replace", check=True).stdout.strip()
             step("check_task_briefs.py", "--repo", str(repo), "--base", head,
-                 "--tasks-dir", f"{project_dir}/tasks")
+                 "--tasks-dir", f"{project_dir}/tasks", "--project-dir", project_dir)
             step("check_handoffs.py", "plan", *common)
+        elif action == "prepare-task" and _task_member(repo, project_dir, task_id):
+            # A member task works in a sidecar of its member; its Verify runs there at finish.
+            step("isolation.py", "isolate-member-task", "--repo", str(repo),
+                 "--member", _task_member(repo, project_dir, task_id), "--task-id", task_id)
         elif action == "prepare-task":
             task = step("isolation.py", "isolate-task", "--repo", str(repo),
                         "--base", expected_head, "--task-id", task_id,
@@ -186,33 +226,67 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
                 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"]:
+        elif action == "preauthorize":
+            # A block here is not a failure: the gate asks its owner as usual.
+            next_step = "ask the owner at this gate"
+            if project_dir != ".project" or kind not in {"intent", "plan"}:
+                raise StepFailed("pre-approval covers only intent or plan on the active track")
+            routed = step("pipeline_state.py", "route", *common)
+            if routed["route"].get("action") != "run-phase" or "recovery" in routed:
+                raise StepFailed("pre-approval needs an ordinary phase route")
+            if step("discussion_records.py", "pending", "--repo", str(repo))["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)
+            track = repo / project_dir
+            intent = (track / "intent/INTENT.md").read_text(encoding="utf-8")
+            lane = re.search(r"(?m)^Lane:\s*(.+)$", intent)
+            if not lane or lane.group(1).split("<!--", 1)[0].strip().strip("`") != "quick":
+                raise StepFailed("pre-approval covers only the quick lane")
+            intent = re.sub(r"(?s)<!--.*?-->", "", intent)
+            if re.search(r"(?m)^\s*-\s*\[(RESEARCH|NEEDS-USER)\]", _common.section_body(intent, "Open questions") or ""):
+                raise StepFailed("INTENT.md has open RESEARCH or NEEDS-USER questions")
+            audit_path = track / "research/DOCS-AUDIT.md"
+            if audit_path.exists():
+                audit = audit_path.read_text(encoding="utf-8")
+                queue = _table_rows(_common.section_body(audit, "Remediation queue"))
+                ruled = set()
+                for row in _table_rows(_common.section_body(audit, "User rulings")):
+                    if len(row) != 4 or row[1] not in {"fix-code", "fix-doc", "accept-drift"}:
+                        continue
+                    words = row[2].strip().strip('`"').strip()
+                    if words and words.casefold() != "none" and not re.fullmatch(r"<[^>]*>", words):
+                        ruled.add(row[0])
+                if any(len(row) == 6 and row[4] == "NEEDS-USER" and row[0] not in ruled for row in queue):
+                    raise StepFailed("DOCS-AUDIT.md has NEEDS-USER rows without a user ruling")
+            if kind == "intent":
+                # Malformed or incomplete spec-probe tables are not a pre-approvable draft.
+                step("check_handoffs.py", "intent", *common)
+            if kind == "plan":
+                if gate_plan()["mode"] != "off":
+                    raise StepFailed("pre-approval requires review_panel off")
+                plan = re.sub(r"(?s)<!--.*?-->", "", (track / "plan/PLAN.md").read_text(encoding="utf-8"))
+                config = _common.section_body(plan, "Config") or ""
+                skeptics = re.search(r"(?m)^[ \t]*-[ \t]*finding_skeptics:[ \t]*(\S+)", config)
+                if skeptics and skeptics.group(1) != "off":
+                    raise StepFailed("pre-approval requires finding_skeptics off")
+                # Quick-lane limit from project policy (gsd-path-plan Quick mode): one wave, at most two tasks.
+                if (len(re.findall(r"(?m)^## Wave \d+ — ", plan)) != 1
+                        or len(list((track / "tasks").glob("T[0-9][0-9][0-9]-*.md"))) > 2):
+                    raise StepFailed("pre-approval requires one wave and at most two tasks")
+            step("pipeline_state.py", "pre-approve", "--repo", str(repo), "--use", kind)
+        else:
+            gate_plan()
             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"}
+                "next": next_step}
     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("action", choices=("route", "gate-plan", "approve-plan", "build-evidence", "lint-round", "prepare-task", "prepare-final", "prepare-inspect", "finish-inspect", "preauthorize"))
     parser.add_argument("--repo", type=Path, required=True)
     parser.add_argument("--project-dir", choices=(".project", ".project/next"), default=".project")
     parser.add_argument("--expected-head")
@@ -220,15 +294,18 @@ def main(argv=None):
     parser.add_argument("--round-size", type=int)
     parser.add_argument("--inspection", type=Path)
     parser.add_argument("--mapper-reviewed", action="store_true")
+    parser.add_argument("--kind", choices=("intent", "plan"))
     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")
+    if arguments.action == "preauthorize" and not arguments.kind:
+        parser.error("preauthorize requires --kind")
     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)
+                          arguments.mapper_reviewed, arguments.kind)
     print(json.dumps(result, sort_keys=True))
     return 0 if result["status"] == "complete" else 1
 

package/skills/path/scripts/worktree_paths.py

@@ -13,10 +13,34 @@ import os
 import tempfile
 from pathlib import Path
 
-try:
-    import _common
-except ImportError:
-    from scripts import _common
+if __package__:
+    from . import _common
+else:
+    try:
+        import _common
+    except ImportError:
+        from scripts import _common
+
+
+def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    try:
+        if __package__:
+            from . import pipeline_git as pg
+        else:
+            from scripts import pipeline_git as pg
+    except ImportError:
+        try:
+            import pipeline_git as pg
+        except ImportError:
+            pg = None
+    if pg is not None:
+        return pg.worktree_list_porcelain(primary)
+    try:
+        output = _git(primary, "worktree", "list", "--porcelain", "-z")
+        return output, True
+    except ValueError:
+        output = _git(primary, "worktree", "list", "--porcelain")
+        return output, False
 
 
 def _git(primary: Path, *args: str) -> str:
@@ -27,7 +51,10 @@ def _git(primary: Path, *args: str) -> str:
 
 
 def _identity(path: Path) -> str:
-    return hashlib.sha256(os.fsencode(path)).hexdigest()
+    digest = hashlib.sha256(os.fsencode(path)).hexdigest()
+    # Two identities nest in every managed path; full digests would use about
+    # 130 of Windows' 260-character MAX_PATH before any repository content.
+    return digest[:16] if os.name == "nt" else digest
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
@@ -65,7 +92,7 @@ def _workspace(primary: Path, pin: bool) -> Path:
         receipt.parent.mkdir(parents=True, exist_ok=True)
         fd, temporary = tempfile.mkstemp(dir=receipt.parent)
         try:
-            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as handle:
                 json.dump({"primary": str(primary), "root": str(workspace)}, handle)
             try:
                 os.link(temporary, receipt)
@@ -76,17 +103,52 @@ def _workspace(primary: Path, pin: bool) -> Path:
     return workspace
 
 
+def release_workspace(primary: Path) -> bool:
+    """Forget the pinned placement receipt once no linked worktrees remain.
+
+    Lets GSD_PATH_WORKTREE_ROOT (or a new default) apply again at the next
+    milestone's first allocation. Returns True when a receipt was removed;
+    any remaining linked worktree (including one only still registered) keeps
+    the pin.
+    """
+    primary = primary.resolve()
+    common = Path(_git(primary, "rev-parse", "--git-common-dir"))
+    common = (primary / common).resolve()
+    receipt = common / "gsd-path" / "workspaces" / f"{_identity(primary)}.json"
+    if not receipt.is_file():
+        return False
+    output, nul_separated = _worktree_list_porcelain(primary)
+    records = output.split("\0\0") if nul_separated else [
+        block for block in output.strip().split("\n\n") if block.strip()
+    ]
+    for record in records:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        for field in fields:
+            if field.startswith("worktree ") and Path(field[len("worktree "):]).resolve() != primary:
+                return False
+    receipt.unlink()
+    return True
+
+
 def worktree_path(primary: Path, kind: str, name: str, *, pin: bool = False) -> Path:
     primary = primary.resolve()
-    if kind not in {"task", "verify", "integrate"} or not name or Path(name).name != name or name in {".", ".."}:
+    if kind not in {"task", "verify", "integrate", "bound"} or not name or Path(name).name != name or name in {".", ".."}:
         raise ValueError("invalid managed worktree kind or name")
+    if kind == "bound":
+        return _workspace(primary, pin) / kind / name
     legacy = (primary.parent / f".{primary.name}-gsd-path-integrate-{name}"
               if kind == "integrate" else primary.parent / f"{primary.name}.gsd-path" / kind / name)
     branch = f"refs/heads/gsd-path-{kind}/{name}"
-    records = _git(primary, "worktree", "list", "--porcelain", "-z").split("\0\0")
+    output, nul_separated = _worktree_list_porcelain(primary)
+    if nul_separated:
+        records = output.split("\0\0")
+    else:
+        records = [block for block in output.strip().split("\n\n") if block.strip()]
     for record in records:
-        fields = record.split("\0")
-        if f"worktree {legacy}" in fields and f"branch {branch}" in fields:
+        fields = record.split("\0") if nul_separated else record.splitlines()
+        # Compare as paths: git prints forward slashes on Windows.
+        worktrees = [Path(field[len("worktree "):]) for field in fields if field.startswith("worktree ")]
+        if legacy in worktrees and f"branch {branch}" in fields:
             return legacy
     # Keep collision checks and missing-directory recovery at the old location.
     if os.path.lexists(legacy):

package/skills/path/templates/codebase.md

@@ -4,7 +4,7 @@
      (brownfield mode), researchers (fifth standard dimension), the planner
      (conventions are binding), and reviewers. -->
 
-Repo root: <absolute path>
+Repo root: <absolute primary repo root, never a sidecar>
 Scanned: <date>
 Checks run: <exact commands run and their results, e.g. `npm test` → 37/40 pass>
 

package/skills/path/templates/docs-audit.md

@@ -3,7 +3,7 @@
 <!-- Written by the docs auditor ($gsd-path-docs-audit or $gsd-path-inspect).
      Every verdict carries evidence; a verdict without evidence is a defect. -->
 
-Repo root: <absolute path>
+Repo root: <absolute primary repo root, never a sidecar>
 Audited: <date>
 Audited HEAD: <40-hex commit the claims were checked at, or none>
 Alignment mode: <yes | no — yes when .project/ artifacts were also audited>
@@ -62,7 +62,11 @@ Worst drift: <one sentence — the most misleading claim found>
 ## Remediation queue
 
 <!-- Every non-verified claim, classified. The user rules on this queue;
-     the auditor never fixes anything. -->
+     the auditor never fixes anything.
+     Numbers are unique and strictly increasing, not necessarily contiguous.
+     A persisting row keeps its number; a new row takes a number above every
+     prior queue number and every User rulings Queue #. Never reuse a retired
+     number: a ruling stays bound to the item it was made for. -->
 
 | # | Doc | Claim | Verdict | Class | Suggested action |
 |---|-----|-------|---------|-------|------------------|

package/skills/path/templates/final-review.md

@@ -4,20 +4,32 @@
      criterion appears exactly once and carries checked evidence. A criterion
      listed in PLAN.md's Surface contract also names its Surface, and its
      Check is the walkthrough performed — never internal test output. Embedded
-     angle brackets are valid in concrete Check and Observed values. -->
+     angle brackets are valid in concrete Check and Observed values.
+     When .project/build/members.json locks members, add one line per locked
+     member after Reviewed HEAD: `Member reviewed HEAD: <member> <full SHA>`,
+     naming that member's bound branch tip. -->
 
 Reviewed HEAD: <full SHA>
 Overall verdict: <pass | blocked>
 
 <!-- pass only when every criterion is met; blocked when any criterion is
-     not-met or unverifiable. -->
+     not-met or unverifiable.
+     A criterion with a held-out edge (E#) or judgment prohibition (N#) in
+     INTENT.md is met only when Check, Observed, or Reference cites every such
+     id with its evidence; otherwise it is unverifiable with
+     `Finding: insufficient spec evidence: <id> ...`. -->
 
 ## Success criteria
 
-### SC1 — <criterion copied verbatim from INTENT.md>
+<!-- Each `### SCn —` title must match INTENT.md `## Success criteria` as
+     `_success_criteria` stores it: continuation lines join with a single
+     space and keep `- ` sub-bullet markers; comparison uses `_normalize_ws`
+     only. -->
+
+### SC1 — <criterion as stored by the gate>
 
 - **Verdict**: <met | not-met | unverifiable>
-- **Surface**: <the surface PLAN.md's Surface contract lists this criterion under; omit the whole field for any other criterion>
+- **Surface**: <exactly the surface name PLAN.md's Surface contract lists this criterion under, with no detail after it; omit the whole field for any other criterion>
 - **Check**: `<command actually run, or "none">`
 - **Observed**: <relevant output or observed behavior>
 - **Reference**: <file:line, artifact path, or "none">

package/skills/path/templates/gap-review.md

@@ -1,7 +1,8 @@
 # Gap Review — <N>: <risk identity>
 
 <!-- Written by one final gap reviewer. This file covers exactly one
-     cross-wave integration risk named in the review brief. -->
+     cross-wave integration risk named in the review brief. Repeat FINAL.md's
+     `Member reviewed HEAD: <member> <full SHA>` lines after Reviewed HEAD. -->
 
 Reviewed HEAD: <full SHA>
 Gap verdict: <pass | blocked>

package/skills/path/templates/intent.md

@@ -57,6 +57,36 @@ paragraph the user signed off on — do not edit without a new sign-off.>
 1. <criterion — a thing you can run/measure/see>
 2. ...
 
+## Edge coverage
+
+<!-- Written by define's edge probe (references/spec-probes.md). Walk every
+     success criterion; each applicable edge gets one row ruled by the user.
+     Disposition: criterion SCn (stated in that criterion) | held-out (a named
+     test pins the ruling written in Detail) | dismissed (Detail says why the
+     edge cannot occur). Every SCn appears at least once; a criterion with no
+     data shape gets category none, dismissed. Categories: boundary,
+     adjacency, empty, encoding, ordering, precision, idempotency,
+     concurrency, none. `check_handoffs.py intent` gates this table. -->
+
+| Edge | Criterion | Category | Disposition | Detail |
+|------|-----------|----------|-------------|--------|
+| E1 | SC1 | <category> | <disposition> | <ruling, examples, or dismissal reason> |
+
+## Prohibitions
+
+<!-- Written by define's prohibition probe. What each criterion must never
+     silently become: values, safety, privacy, fairness, transparency. Not
+     routine engineering, not generic security canon.
+     Disposition: criterion SCn (checkable; stated in that criterion) |
+     judgment (final reviewer judges it; Detail says what to look for) |
+     dismissed. A single row with Criterion `all`, Must not `none`, and
+     disposition dismissed, and no other row, records work that affects no
+     person directly. -->
+
+| Prohibition | Criterion | Must not | Disposition | Detail |
+|-------------|-----------|----------|-------------|--------|
+| N1 | SC1 | <what it must never become> | <disposition> | <what the reviewer looks for, or why dismissed> |
+
 ## Scope: in
 
 <The smallest version that hits the success criteria. Bullet list.>

package/skills/path/templates/patch-findings.md

@@ -11,6 +11,6 @@ State: ship/blocked
 ### P001 — <short finding title>
 
 - **Source**: `.project/review/FINAL.md`
-- **Locator**: `<SC number or gap risk row>`
-- **Evidence**: <observed result copied from the source review>
-- **Fix direction**: <concrete direction for the patch task>
+- **Locator**: <copy the full `Risk: ...` line from a gap review, or the `SC<n>` id from `FINAL.md`>
+- **Evidence**: <copy the gap review's `Found` or `FINAL.md`'s `Finding` field verbatim>
+- **Fix direction**: <copy the source's `Fix direction` field verbatim>

package/skills/path/templates/plan.md

@@ -47,8 +47,8 @@ Goal: <the end-to-end slice that runs>
 Review depth: <full | deep | verify-only>
 
 <!-- More waves: features by dependency, then polish. Rules:
-     - deps only in earlier waves, or same wave with no file overlap
-     - no two same-wave tasks share files
+     - deps only in earlier waves or the same wave
+     - same-wave tasks share files only when one transitively depends on the other
      - nothing from INTENT.md scope-out appears anywhere -->
 
 ## Surface contract
@@ -83,6 +83,21 @@ Walkthrough:
 |-----------|------|------------|
 | SC1 | T001 | AC1 |
 
+## Held-out checks
+
+<!-- Required when INTENT.md Edge coverage has a held-out edge; omit the
+     section entirely when it has none. One row per held-out edge, given to
+     the task that owns the edge's criterion. Test is a file listed in that
+     task's files (optionally `path::test_name`); the task's Verify runs it
+     and its Acceptance
+     criteria state the edge id and the ruling from INTENT.md Detail. Final
+     review cites this test's recorded result for the edge.
+     `scripts/check_handoffs.py plan` gates this table. -->
+
+| Edge | Task | Test |
+|------|------|------|
+| E1 | T001 | <test path from T001 files> |
+
 ## Dependency notes
 
 <Per non-obvious edge: the exact data or landed effect that makes X precede Y,

package/skills/path/templates/research-handoff.md

@@ -14,12 +14,23 @@ Intent: `.project/intent/INTENT.md`
 <!-- Include every standard dimension exactly once. A custom dimension may
      supplement these rows, never replace a standard row. -->
 - `domain` — dispatched → `.project/research/evidence-domain.md` — <why this dimension ran>
-- `stack` — skipped → none — <why this dimension was skipped>
+- `stack` — dispatched → `.project/research/evidence-stack.md` — <why this dimension ran>
 - `pitfalls` — skipped → none — <why this dimension was skipped>
 - `similar` — skipped → none — <why this dimension was skipped>
 
 ## Question assignments
 
 <!-- Copy every [RESEARCH] question from INTENT.md exactly once. Use `- none`
-     only when INTENT.md has no [RESEARCH] questions. -->
-- `[RESEARCH] <question copied from INTENT.md>` → `domain`
+     only when INTENT.md has no [RESEARCH] questions. The question is a
+     CommonMark code span: choose a fence length not used by a backtick run in
+     the question (a longer fence is usually easiest), with one space of
+     padding on each side. Each row may target one or more dispatched
+     dimensions, each in its own code span and separated by commas. Every
+     dispatched dimension must receive a question and answer all its assigned
+     questions in its evidence file. For example:
+     - `` [RESEARCH] Does `Widget` match `sample.json`? `` → `domain`, `stack`
+     A question that ends in a backtick also needs padding, as in:
+     - `` [RESEARCH] Does the label end with `Widget`?` `` → `domain`
+     After removing the fence and CommonMark padding, the text must equal the
+     INTENT question exactly. -->
+- `` [RESEARCH] <question copied from INTENT.md> `` → `domain`, `stack`

package/skills/path/templates/state.md

@@ -10,7 +10,7 @@ branch: null        # bound per milestone as gsd-path/M00N; after integration
                     # the router rebinds before any next-milestone file change
                     # the bound branch is never main; ship integrates it there
 archive: null       # persisted archive transaction path; never recomputed
-integration_default: direct # direct | pull-request; project setting
+integration_default: direct # direct | pull-request | external-landing; project setting
 integration: direct # current milestone; may override the default before build
 integration_source: default # default | milestone; preserves override provenance
 ---

package/skills/path/templates/task.md

@@ -10,6 +10,7 @@ worktree: null      # orchestrator-owned: isolated task worktree while active
 task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; null when serial
 # Optional explicit dispatch overrides: model: <advertised slug|inherit>
 # effort: <advertised effort|inherit>
+# repo: <member>    # multi-repo only: the MEMBERS.md member this task changes; omit for the coordinator
 files:              # every file this task may touch — dispatch checks overlap
   - <path>
 ---

package/skills/path/templates/wave-review.md

@@ -10,8 +10,11 @@
      with actual values, otherwise omit them:
 Reviewed HEAD: <full review commit SHA>
 Review scope: final
-     In each surface SC block also include Surface, Check, and Observed fields
-     using the final-review format. Record the actual walkthrough evidence once. -->
+     In each surface SC block keep the mandatory `- ✅` / `- ❌` evidence line
+     (the wave gate requires it). Also include Surface, Check, and Observed
+     fields using the final-review format. Surface holds exactly the surface name
+     from PLAN.md's Surface contract; put walkthrough detail in Check and Observed.
+     The `- ✅` line may summarize Observed; do not omit it. -->
 
 Wave verdict: <pass | blocked — blocked if any task fails>
 Cycle: <C>
@@ -43,12 +46,21 @@ Contract violations (blocking):
 <!-- One heading per INTENT.md success criterion owned by a task in this
      wave, ending `: pass` or `: fail`. `scripts/check_handoffs.py wave
      --review <this file>` gates the SC id set and verdicts. Omit this
-     section when no task in the wave owns an SC. -->
+     section when no task in the wave owns an SC.
+     Copy the criterion text from INTENT.md `## Success criteria` exactly as
+     `_success_criteria` stores it: indented continuation lines join with a
+     single space and keep their leading `- ` markers; the gate compares
+     heading text with `_normalize_ws` only (no paraphrase or stripped
+     sub-bullets). -->
 
-### SC1 — <criterion>: <pass | fail>
+### SC1 — <criterion as stored by the gate>: <pass | fail>
 - ✅ <evidence: verify output / file:line checked>
 - ❌ <criterion> — found: <what exists instead, file:line>
   fix: <concrete direction a coder can execute without re-investigating>
+<!-- Quick-lane final scope (Review scope: final): add after the evidence line:
+- **Surface**: <surface name from PLAN.md>
+- **Check**: `<walkthrough command>`
+- **Observed**: <what was seen> -->
 
 ## Fixed since last cycle