@opengsd/gsd-path 1.3.1 → 1.5.0

package/skills/gsd-path-build/scripts/state_checkpoint.py

@@ -17,12 +17,15 @@ from datetime import date
 from pathlib import Path, PurePosixPath
 from typing import Mapping, Optional, Sequence
 
-try:
-    from isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
-except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
-    if error.name != "isolation":
-        raise
-    from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, require_commit, require_full_sha, PROJECT_ENTRIES
+if __package__:
+    from .isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
+else:
+    try:
+        from isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
+    except ModuleNotFoundError as error:  # pragma: no cover - package imports used by tests
+        if error.name != "isolation":
+            raise
+        from scripts.isolation import IsolationError, checkpoint as isolation_checkpoint, PROJECT_ENTRIES
 
 
 if __package__:
@@ -66,6 +69,11 @@ def _sha256(content: str) -> str:
     return hashlib.sha256(content.encode("utf-8")).hexdigest()
 
 
+def _is_junk_file(path: Path) -> bool:
+    # Drift digests skip OS junk by name: Finder rewrites it whatever its ignore status.
+    return path.name in pipeline_state._common.OS_JUNK_NAMES and path.is_file() and not path.is_symlink()
+
+
 def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
     if path.is_symlink() or not path.is_dir():
         raise PipelineStateError(f"promotion path must be a real directory: {path}")
@@ -74,7 +82,7 @@ def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
         if child.is_symlink():
             raise PipelineStateError(f"promotion path contains a symlink: {child}")
         relative = child.relative_to(path).as_posix()
-        if PurePosixPath(relative).parts[0] in excluded:
+        if PurePosixPath(relative).parts[0] in excluded or _is_junk_file(child):
             continue
         if child.is_dir():
             digest.update(f"d\0{relative}\0".encode())
@@ -87,15 +95,15 @@ def _tree_digest(path: Path, excluded: Sequence[str] = ()) -> str:
 
 
 def _checkpoint_artifact_digest(project: Path, mutable_paths: set[str]) -> str:
-    """Hash every approval artifact except the helper-owned metadata files."""
+    """Hash approval artifacts except helper-owned metadata and OS junk."""
     digest = hashlib.sha256()
     for child in sorted(project.rglob("*")):
         if child.is_symlink():
             raise PipelineStateError(f"checkpoint path contains a symlink: {child}")
         relative = child.relative_to(project).as_posix()
-        # Unsupported entries (OS junk) are refused by the checkpoint itself; leaving them
-        # out lets a refused approval resume after the owner removes them.
-        if relative in mutable_paths or relative.split("/", 1)[0] not in PROJECT_ENTRIES:
+        # Finder can rewrite OS junk during approval; it must not cause artifact drift.
+        if (relative in mutable_paths or relative.split("/", 1)[0] not in PROJECT_ENTRIES
+                or _is_junk_file(child)):
             continue
         if child.is_dir():
             digest.update(f"d\0{relative}\0".encode())
@@ -333,11 +341,7 @@ def _converge_checkpoint_file(path: Path, before: str, after: str, label: str) -
 
 def _unlink_checkpoint_journal(path: Path) -> None:
     path.unlink()
-    descriptor = os.open(path.parent, os.O_RDONLY)
-    try:
-        os.fsync(descriptor)
-    finally:
-        os.close(descriptor)
+    pipeline_state._common.fsync_directory(path.parent)
 
 
 def _resume_checkpoint_locked(
@@ -439,41 +443,85 @@ def _validate_plan_briefs(repo: Path, kind: str, project_dir: str) -> None:
     if head.returncode != 0:
         # Pre-Git approval defers base-dependent checks to build.
         return
+    if __package__:
+        from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+    else:
+        try:
+            from check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+        except ModuleNotFoundError as error:  # pragma: no cover - package imports
+            if error.name != "check_task_briefs":
+                raise
+            from scripts.check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
+    if __package__:
+        from . import check_handoffs
+    else:
+        try:
+            import check_handoffs
+        except ModuleNotFoundError as error:
+            if error.name != "check_handoffs":
+                raise
+            from scripts import check_handoffs
     try:
-        from check_task_briefs import BriefError, validate_task_briefs
-    except ModuleNotFoundError as error:  # pragma: no cover - package imports
-        if error.name != "check_task_briefs":
-            raise
-        from scripts.check_task_briefs import BriefError, validate_task_briefs
-    try:
-        import check_handoffs
-    except ModuleNotFoundError as error:
-        if error.name != "check_handoffs":
-            raise
-        from scripts import check_handoffs
-    try:
-        tasks, dependency_files = check_handoffs.plan_brief_inputs(repo, project_dir)
-        landed_bases = {}
-        for task_id, text in tasks.items():
-            if check_handoffs._task_scalar(text, task_id, "status") != "done":
-                continue
-            agent = check_handoffs._task_scalar(text, task_id, "agent")
-            if agent in {"", "null"}:
-                raise BriefError(f"{task_id} landed task has no recorded agent")
-            recorded_base = check_handoffs._task_scalar(text, task_id, "base")
-            try:
-                landed_bases[task_id] = require_commit(repo, require_full_sha(recorded_base))
-            except IsolationError as error:
-                raise BriefError(f"{task_id} landed task has invalid historical base: {error}") from error
-            dependency_files[task_id] = set()
+        member_base = _member_bases(repo)
+        tasks, dependency_files, landed_bases = plan_validation_bases(
+            repo, project_dir, member_base, initial=True
+        )
         validate_task_briefs(
             repo, head.stdout.strip(), f"{project_dir}/tasks",
             dependency_files=dependency_files, landed_bases=landed_bases,
+            member_base=member_base,
         )
+        if project_dir == ".project/next":
+            # Promotion checks lookahead member tasks from the bases their briefs were checked at.
+            named = {
+                str(check_handoffs._strict_frontmatter(text, task_id).get("repo"))
+                for task_id, text in tasks.items()
+                if check_handoffs._strict_frontmatter(text, task_id).get("repo")
+                and check_handoffs._task_scalar(text, task_id, "status") != "done"
+            }
+            if named:
+                bases = {name: member_base(name)[1] for name in sorted(named)}
+                milestone = pipeline_state.load_state(repo, project_dir)[0].milestone
+                path = _lookahead_member_bases_path(repo, str(milestone))
+                path.parent.mkdir(parents=True, exist_ok=True)
+                pipeline_state._common.atomic_write(path, json.dumps(
+                    {"schema": LOOKAHEAD_MEMBER_BASES_SCHEMA, "milestone": milestone, "bases": bases},
+                    indent=2, sort_keys=True) + "\n")
     except (BriefError, check_handoffs.HandoffError) as error:
         raise PipelineStateError(f"task brief validation failed: {error}") from error
 
 
+LOOKAHEAD_MEMBER_BASES_SCHEMA = "gsd-path/lookahead-member-bases/v1"
+
+
+def _lookahead_member_bases_path(repo: Path, milestone: str) -> Path:
+    common = pipeline_state._run_git(repo, "rev-parse", "--path-format=absolute", "--git-common-dir").stdout.strip()
+    return Path(common) / "gsd-path" / "lookahead-member-bases" / f"{milestone}.json"
+
+
+def _lookahead_member_bases(repo: Path, milestone: str) -> Optional[dict]:
+    path = _lookahead_member_bases_path(repo, milestone)
+    if not path.is_file():
+        return None
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if value.get("schema") != LOOKAHEAD_MEMBER_BASES_SCHEMA or value.get("milestone") != milestone:
+        return None
+    return value.get("bases")
+
+
+def _shipped_member_merges(repo: Path, landing: str) -> dict:
+    """Member merges named by the ship commit the integration landing merged."""
+    if __package__:
+        from .pipeline_git import ship_member_rows
+    else:
+        from pipeline_git import ship_member_rows
+    ship = pipeline_state._run_git(repo, "rev-parse", "--verify", "--quiet", f"{landing}^2", check=False)
+    if ship.returncode != 0:
+        return {}
+    message = pipeline_state._run_git(repo, "show", "-s", "--format=%B", ship.stdout.strip()).stdout
+    return {row["name"]: row["merge"] for row in ship_member_rows(message)}
+
+
 def checkpoint_approval(
     repo: Path,
     kind: str,
@@ -1027,6 +1075,46 @@ def _classify_plan_drift(
         }
     approved = _approved_task_contracts(repo, checkpoint)
     current = _task_contracts_at(repo, revision)
+    if __package__:
+        from . import check_handoffs
+    else:
+        import check_handoffs
+    # Member task paths live in member repos: compare each member from the base its brief
+    # was checked at to the member merge the shipped milestone made (both fixed commits).
+    task_repos = {
+        task_id: str(check_handoffs._strict_frontmatter(contract.text, contract.path).get("repo") or "")
+        for task_id, contract in approved.items()
+    }
+    active_member_tasks = {
+        task_id for task_id, name in task_repos.items()
+        if name and check_handoffs._task_scalar(approved[task_id].text, task_id, "status") != "done"
+    }
+    active_members = {task_repos[task_id] for task_id in active_member_tasks}
+    member_changes: dict[str, list] = {}
+    if active_members:
+        bases = _lookahead_member_bases(repo, str(state.milestone)) or {}
+        if any(name not in bases for name in active_members):
+            return {
+                "class": "unverifiable",
+                "checkpoint": checkpoint,
+                "task_ids": [],
+                "changed_paths": [],
+                "contract_paths": [],
+                "member_tasks": True,
+                "reason": "member bases were not recorded at plan approval",
+            }
+        if __package__:
+            from . import members
+        else:
+            import members
+        checkouts = {item["name"]: Path(item["checkout"]) for item in members.read_members(repo)}
+        merges = _shipped_member_merges(repo, landing or revision)
+        for name in active_members:
+            member_changes[name] = [
+                item for item in pipeline_state._run_git(
+                    checkouts[name], "diff", "--no-renames", "--name-only", "-z", bases[name], merges[name]
+                ).stdout.split("\0") if item
+            ] if name in merges else []
 
     contract_paths: set[str] = set()
     flagged_ids: set[str] = set()
@@ -1050,9 +1138,12 @@ def _classify_plan_drift(
 
     product_paths: set[str] = set()
     for task_id, contract in approved.items():
+        member = task_repos.get(task_id)
+        if member and task_id not in active_member_tasks:
+            continue
         matches = sorted(
-            changed_path
-            for changed_path in changed
+            (f"{member}:{changed_path}" if member else changed_path)
+            for changed_path in (member_changes[member] if member else changed)
             if any(
                 changed_path == path
                 or changed_path.startswith(f"{path.rstrip('/')}/")

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

@@ -82,6 +82,8 @@ def _promotion_event(
         if isinstance(task_ids, list) and task_ids:
             return f"{prefix}; plan drift flagged tasks {', '.join(task_ids)}"
         return f"{prefix}; plan contract changed after approval"
+    if drift_class == "unverifiable" and drift.get("member_tasks"):
+        return f"{prefix}; plan drift unverifiable because member bases were not recorded at plan approval"
     if drift_class == "unverifiable":
         return f"{prefix}; plan drift unverifiable because approval checkpoint is missing"
     return prefix

package/skills/gsd-path-build/scripts/task_context.py

@@ -9,15 +9,17 @@ from pathlib import Path
 
 try:
     from scripts import check_handoffs as contracts
+    from scripts import _common
 except ImportError:
     import check_handoffs as contracts
+    import _common
 
 
 def render(repo: Path, task: Path) -> str:
     intent_path = repo.resolve() / '.project/intent/INTENT.md'
     task = task.resolve()
-    intent = intent_path.read_bytes().decode('utf-8')
-    task_text = task.read_bytes().decode('utf-8')
+    intent = _common.read_user_text(intent_path)
+    task_text = _common.read_user_text(task)
     owned = contracts._owned_criteria(task_text, task.stem)
     criteria = contracts._success_criteria(intent)
     unknown = set(owned) - set(criteria)
@@ -40,7 +42,14 @@ def render(repo: Path, task: Path) -> str:
         if simple:
             before, after = intent[:section.start('body')], intent[section.end('body'):]
             # Corrections and task interfaces can explicitly refer to another SC.
-            required = set(owned) | set(re.findall(r'\bSC\d+\b', before + after + task_text))
+            # The spec-probe tables name every SC by design, so they select nothing.
+            scanned = re.sub(r'(?ms)^## (?:Edge coverage|Prohibitions)[ \t]*\n.*?(?=^## |\Z)', '',
+                             before + after)
+            required = set(owned) | set(re.findall(r'\bSC\d+\b', scanned + task_text))
+            # An owned criterion's edge or prohibition ruled into another SC needs that SC's text.
+            for rows in (contracts.edge_coverage(intent, criteria), contracts.prohibitions(intent, criteria)):
+                required |= {row['target'] for row in (rows or {}).values()
+                             if row['target'] and row['criterion'] in owned}
             selected = ''.join(chunk for item, chunk in zip(items, chunks) if f'SC{item[1]}' in required)
             projected = before + '\n' + (selected or '- No criteria assigned.\n\n') + after
             mode = 'owned-criteria'

package/skills/gsd-path-build/scripts/token_budget.py

@@ -10,12 +10,16 @@ import json
 import sys
 from pathlib import Path
 
-try:
-    from _common import atomic_write
-    from loop_run import log_lock
-except ModuleNotFoundError:  # pragma: no cover - package imports
-    from scripts._common import atomic_write
-    from scripts.loop_run import log_lock
+if __package__:
+    from ._common import atomic_write
+    from .loop_run import log_lock
+else:
+    try:
+        from _common import atomic_write
+        from loop_run import log_lock
+    except ModuleNotFoundError:  # pragma: no cover - package imports
+        from scripts._common import atomic_write
+        from scripts.loop_run import log_lock
 
 
 SCHEMA = "gsd-path/token-budget/v1"
@@ -97,14 +101,14 @@ def operate(args):
                       "task_limit": args.task_limit, "session_limit": args.session_limit,
                       "authority": args.authority}
             if ledger.exists():
-                data = json.loads(ledger.read_text())
+                data = json.loads(ledger.read_text(encoding="utf-8"))
                 if any(data.get(key) != value for key, value in policy.items()):
                     raise ValueError("existing session policy differs; configuration cannot reset usage")
             else:
                 data = {**policy, "observations": {}}
                 atomic_write(ledger, json.dumps(data, indent=2) + "\n")
             return {"status": "configured", "hard_cap_supported": False}
-        data = json.loads(ledger.read_text())
+        data = json.loads(ledger.read_text(encoding="utf-8"))
         if data.get("schema") != SCHEMA or data.get("host") != "codex-cli":
             raise ValueError("unsupported budget ledger")
         if args.action == "record":

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