@opengsd/gsd-path 1.6.1 → 1.7.0

package/skills/path/scripts/lean_verification.py

@@ -108,10 +108,14 @@ def _final_view(relative, text, criteria, reviewed, head, surfaces=None):
                 fields[field] = contracts._raw_source_field(block, field, relative)
         if "Surface" in fields and not {"Check", "Observed"}.issubset(fields):
             raise contracts.HandoffError(f"{criterion} lacks its recorded surface walkthrough")
+        reference = f"{relative} — {criterion}"
+        if "Observed" in fields and evidence:
+            # The reviewer may cite held-out and judgment ids on the evidence line.
+            reference += f"; evidence: {evidence}"
         lines += [f"### {criterion} — {title}", "", "- **Verdict**: met",
                   f"- **Check**: {fields.get('Check', 'none')}",
                   f"- **Observed**: {fields.get('Observed', evidence)}",
-                  f"- **Reference**: {relative} — {criterion}",
+                  f"- **Reference**: {reference}",
                   "- **Finding**: none", "- **Fix direction**: none"]
         if "Surface" in fields:
             expected = (surfaces or {}).get(criterion)
@@ -227,8 +231,14 @@ def _retire_execution(repo, head, execution):
     isolation.retire(repo, worktree, execution["branch"], force=False)
 
 
-def verify_project(repo, expected_head):
-    """Execute project Verify in isolation, retaining output for retry reuse."""
+def verify_project(repo, expected_head, *, rerun: bool = False):
+    """Execute project Verify in isolation, retaining output for retry reuse.
+
+    With ``rerun`` (the owner's explicit ``prepare-final --rerun`` after a
+    host-caused failure diagnosed through the forensics contract), a recorded
+    execution at the same command and commit is retired and the command runs
+    again, appending a second ledger entry; the failed entry stays as history.
+    """
     repo = Path(repo).resolve()
     _require_ship_inputs(repo, expected_head)
     plan = contracts._read(repo, ".project/plan/PLAN.md")
@@ -243,7 +253,6 @@ def verify_project(repo, expected_head):
     destination = repo / relative
     if destination.is_symlink():
         raise contracts.HandoffError("project verification evidence must be a real file")
-    expected_destination = hashlib.sha256(destination.read_bytes()).hexdigest() if destination.exists() else None
     execution = entry.get("execution") if entry else None
     if entry and execution is None:
         raise contracts.HandoffError("recorded verification lacks output; preserve and reconcile its evidence")
@@ -259,11 +268,16 @@ def verify_project(repo, expected_head):
                     relative, relative, journal["expected_destination"],
                 )
         _retire_execution(repo, expected_head, execution)
-        view = _gap_view(command, expected_head, execution, waves)
-        if not destination.exists() or destination.read_text(encoding="utf-8") != view:
-            _common.atomic_write(destination, view)
-        return {"passed": entry["result"] == "pass", "reused": True,
-                "path": str(destination), "execution": execution}
+        if not rerun:
+            view = _gap_view(command, expected_head, execution, waves)
+            if not destination.exists() or destination.read_text(encoding="utf-8") != view:
+                _common.atomic_write(destination, view)
+            return {"passed": entry["result"] == "pass", "reused": True,
+                    "path": str(destination), "execution": execution}
+    # Hash after any prior execution's recovery: a rerun's old-collection
+    # recovery can rewrite the gap view, and the fresh collection must expect
+    # the file as it stands now, not before the recovery (#454).
+    expected_destination = hashlib.sha256(destination.read_bytes()).hexdigest() if destination.exists() else None
     sidecar = isolation.isolate_verify(repo, expected_head, "project-verify")
     worktree = Path(sidecar["worktree"])
     try:
@@ -291,18 +305,20 @@ def verify_project(repo, expected_head):
         execution["members"] = {name: record["tip"] for name, record in sidecars.items()}
     else:
         build_state.verify_record(str(repo), command, expected_head,
-                                  "pass" if passed else "fail", execution=execution)
+                                  "pass" if passed else "fail", execution=execution,
+                                  rerun=rerun)
     isolation.clean_verify(repo, worktree, expected_head, sidecar["branch"])
     _common.atomic_write(worktree / relative, _gap_view(command, expected_head, execution, waves))
     collection = isolation.collect_artifact(repo, worktree, expected_head, sidecar["branch"],
                                             relative, relative, expected_destination)
     isolation.retire(repo, worktree, sidecar["branch"], force=False)
     return {"passed": passed, "reused": False, "path": str(destination),
-            "execution": execution, "collection": collection}
+            "execution": execution, "collection": collection,
+            **({"rerun": True} if rerun else {})}
 
 
-def prepare_final(repo, expected_head):
-    verification = verify_project(repo, expected_head)
+def prepare_final(repo, expected_head, *, rerun: bool = False):
+    verification = verify_project(repo, expected_head, rerun=rerun)
     if not verification["passed"]:
         return {"status": "blocked", "verification": verification,
                 "reason": "project Verify failed; use its recorded output"}
@@ -323,9 +339,12 @@ def main(argv=None):
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--repo", type=Path, required=True)
     parser.add_argument("--expected-head", required=True)
+    parser.add_argument("--rerun", action="store_true",
+                        help="re-execute project Verify at the same head after a host-caused "
+                             "failure, appending a new ledger entry")
     args = parser.parse_args(argv)
     try:
-        result = prepare_final(args.repo.resolve(), args.expected_head)
+        result = prepare_final(args.repo.resolve(), args.expected_head, rerun=args.rerun)
     except (contracts.HandoffError, isolation.IsolationError, build_state.BuildStateError,
             OSError, subprocess.CalledProcessError) as error:
         print(str(error), file=sys.stderr)

package/skills/path/scripts/loop_run.py

@@ -530,10 +530,15 @@ def run_shell(command: str, timeout: float) -> tuple[Optional[int], str]:
         except subprocess.TimeoutExpired as drained:
             stdout = drained.stdout or expired.stdout or b""
             stderr = drained.stderr or expired.stderr or b""
-            if process.stdout:
-                process.stdout.close()
-            if process.stderr:
-                process.stderr.close()
+            # Windows communicate() reads in threads that hold each pipe's lock,
+            # so close() would block until an orphaned grandchild (bash forks
+            # commands it runs from a script file) exits; leave them to the
+            # daemon reader threads there.
+            if os.name != "nt":
+                if process.stdout:
+                    process.stdout.close()
+                if process.stderr:
+                    process.stderr.close()
             process.kill()
             process.wait(timeout=5)
         output = stdout.decode("utf-8", errors="replace") + stderr.decode("utf-8", errors="replace")

package/skills/path/scripts/members.py

@@ -34,9 +34,17 @@ MEMBERS_FILE = "MEMBERS.md"
 MARKER_SCHEMA = "gsd-path/member/v1"
 MARKER_KEYS = {"schema", "coordinator", "project", "name"}
 NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
-FIELDS = ("Checkout", "Remote", "Integration")
+FIELDS = ("Checkout", "Remote", "Integration", "Prepare")
+# The first three are required; Prepare (isolate provisioning, #463) and
+# Default branch are optional.
+REQUIRED_FIELDS = ("Checkout", "Remote", "Integration")
 # Optional: `add` records it one time; a row without it means main.
 DEFAULT_BRANCH_FIELD = "Default branch"
+# Optional: a shell command run inside each fresh member isolate before any
+# Verify (#463). It provisions what a bare worktree lacks — submodules from
+# the primary checkout's object store, gitignored build inputs — and must
+# copy, never link, outside the isolate (#462).
+PREPARE_FIELD = "Prepare"
 INTEGRATIONS = ("default", "direct", "pull-request")
 GITHUB_REMOTE_RE = re.compile(
     r"(?:https://github\.com/|git@github\.com:|ssh://git@github\.com/)([^/\s]+)/([^/\s]+)"
@@ -206,10 +214,15 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
         return []
     if path.is_symlink() or not path.is_file():
         raise MembersError("MEMBERS.md must be a regular file")
+    return parse_members(path.read_text(encoding="utf-8"))
+
+
+def parse_members(text: str) -> list[dict[str, str]]:
+    """Parse MEMBERS.md text."""
     members: list[dict[str, str]] = []
     current: Optional[dict[str, str]] = None
     preamble: list[str] = []
-    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+    for number, line in enumerate(text.splitlines(), 1):
         if line.startswith("## "):
             name = line[3:].strip()
             if not NAME_RE.fullmatch(name):
@@ -241,7 +254,7 @@ def read_members(coordinator: Path) -> list[dict[str, str]]:
     if len(set(names)) != len(names):
         raise MembersError("MEMBERS.md repeats a member name")
     for member in members:
-        missing = [field for field in FIELDS if not member.get(field.lower())]
+        missing = [field for field in REQUIRED_FIELDS if not member.get(field.lower())]
         if missing:
             raise MembersError(f"MEMBERS.md member {member['name']} lacks {', '.join(missing)}")
         if member["integration"] not in INTEGRATIONS:
@@ -510,6 +523,7 @@ def render(members: Sequence[dict[str, str]]) -> str:
         f"Checkout: {member['checkout']}\n"
         f"Remote: {member['remote']}\n"
         f"Integration: {member['integration']}\n"
+        + (f"{PREPARE_FIELD}: {member['prepare']}\n" if "prepare" in member else "")
         # A row that never had the field keeps none, so old rows are not rewritten.
         + (f"{DEFAULT_BRANCH_FIELD}: {member['default_branch']}\n" if "default_branch" in member else "")
         for member in members

package/skills/path/scripts/pipeline_state.py

@@ -1407,6 +1407,12 @@ def _route_state(repo: Path, project_dir: str = ".project") -> dict[str, object]
             mode="milestone" if status == "done" else "normal",
             reason=f"state is {phase}/{status}",
         )
+    if phase == "plan" and status == "blocked":
+        return _route_result(
+            state,
+            "block",
+            reason="plan is blocked; resolve the correction or user decision named by the plan gate before resuming",
+        )
     if phase == "plan" and status != "done":
         return _route_result(state, "run-phase", phase="plan", reason=f"state is {phase}/{status}")
     if phase == "plan":
@@ -2373,9 +2379,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.project_dir,
             )
         elif args.command == "approve" and (args.defer_checkpoint or args.patch):
-            if args.expected_head is not None:
+            if args.defer_checkpoint and args.expected_head is not None:
                 raise PipelineStateError(
-                    "--expected-head is not accepted with --defer-checkpoint or --patch"
+                    "--expected-head is not accepted with --defer-checkpoint"
                 )
             result = state_checkpoint.defer_approval(
                 args.repo,
@@ -2384,6 +2390,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
                 args.milestone,
                 args.patch,
             )
+            if args.expected_head is not None:
+                result["expected_head_accepted"] = args.expected_head
         elif args.command == "approve":
             if args.expected_head is None:
                 raise PipelineStateError(

package/skills/path/scripts/state_checkpoint.py

@@ -458,6 +458,21 @@ 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 project_dir == ".project":
+        # Unsupported .project entries must surface at approval, before build,
+        # where removing them is cheapest (#466). Like the checkpoint, judge
+        # each git-visible entry by whether it still exists in the worktree.
+        project = repo / ".project"
+        unsupported = sorted(
+            name
+            for name in pipeline_state._common.git_visible_entries(project) - PROJECT_ENTRIES
+            if (project / name).exists() or (project / name).is_symlink()
+        )
+        if unsupported:
+            raise PipelineStateError(
+                "unsupported .project artifacts: " + ", ".join(unsupported)
+                + "; remove or relocate them before approving the plan"
+            )
     if __package__:
         from .check_task_briefs import BriefError, _member_bases, plan_validation_bases, validate_task_briefs
     else:

package/skills/path/scripts/status_runtime.py

@@ -128,7 +128,76 @@ def manifest_digest(manifest: dict) -> str:
     return hashlib.sha256(json.dumps(manifest, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
 
 
+def manifest_successors(manifest: dict) -> tuple:
+    """The validated successor digests a runtime's hashed manifest names (#468).
+
+    `successors` is an optional list of unique 64-hex lowercase store digests.
+    It lives inside the manifest, so the runtime's own digest covers it: a
+    runtime can only bless successors its hashed bytes name. A malformed
+    field makes the whole runtime invalid — acceptance never widens on a
+    shape the store cannot prove.
+    """
+    successors = manifest.get("successors", [])
+    if (not isinstance(successors, list)
+            or not all(
+                isinstance(item, str) and len(item) == 64
+                and all(char in "0123456789abcdef" for char in item)
+                for item in successors
+            )
+            or len(set(successors)) != len(successors)):
+        raise ValueError("invalid manifest successors")
+    return tuple(successors)
+
+
+def accepted_runtime_dirs(repo: Path) -> set:
+    """The pinned runtime's directory plus every validated successor (#468).
+
+    Owner-ruled option (i) on #468: acceptance after ship is anchored in the
+    pinned runtime's own hashed manifest. It names successor digests; each
+    hop is validated exactly like the pin and may name further successors.
+    A named entry that is missing or fails validation simply does not widen
+    the set — the pinned runtime keeps working — and a visited set ends
+    blessed cycles. Nothing outside the pin's hashed reach is ever accepted.
+    """
+    pin = declaration(repo)
+    pin_root, pin_manifest = _validated_manifest(pin)
+    accepted = {pin_root.resolve()}
+    seen = {pin["digest"]}
+    pending = list(manifest_successors(pin_manifest))
+    while pending:
+        digest = pending.pop()
+        if digest in seen:
+            continue
+        seen.add(digest)
+        try:
+            # version None: the hop's trust anchor is the digest the pinned
+            # bytes named, never a version claim. The successors followed
+            # come from the same manifest read whose digest was proven —
+            # a mid-walk entry swap cannot smuggle a different list.
+            root, manifest = _validated_manifest(
+                {"schema": RUNTIME_SCHEMA, "version": None, "digest": digest}
+            )
+            named = manifest_successors(manifest)
+        except (OSError, ValueError, TypeError):
+            continue
+        pending.extend(named)
+        accepted.add(root.resolve())
+    return accepted
+
+
 def validate_runtime(data: dict) -> Path:
+    return _validated_manifest(data)[0]
+
+
+def _validated_manifest(data: dict) -> tuple:
+    """validate_runtime, returning the exact manifest whose digest was proven.
+
+    Callers that act on manifest content (the #468 successor walk) must use
+    this returned object, never a second read of manifest.json: a concurrent
+    swap between reads could otherwise validate one manifest while following
+    successors from another. `version` None anchors on the digest alone —
+    used by the walk for hops whose version no declaration supplies.
+    """
     root = runtime_home() / data["digest"]
     hint = (f"Runtime {data['version']} ({data['digest']}) is unavailable or invalid at {root}. "
             "Run gsd-path --runtime-restore --project <project-root> "
@@ -141,7 +210,8 @@ def validate_runtime(data: dict) -> Path:
             raise ValueError("symlinked manifest")
         manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
         if (not isinstance(manifest, dict) or manifest_digest(manifest) != data["digest"]
-                or manifest.get("version") != data["version"]):
+                or (data["version"] is not None
+                    and manifest.get("version") != data["version"])):
             raise ValueError("manifest identity mismatch")
         files = manifest.get("files")
         if not isinstance(files, dict) or "pipeline_state.py" not in files:
@@ -164,9 +234,10 @@ def validate_runtime(data: dict) -> Path:
             runtime_entries.add(path.name)
         if runtime_entries != set(files) | {"manifest.json"}:
             raise ValueError("unexpected runtime files")
+        manifest_successors(manifest)
     except (OSError, ValueError, TypeError) as error:
         raise ValueError(hint + f" ({error})") from error
-    return root
+    return root, manifest
 
 
 def resolve_runtime(repo: Path) -> Path:

package/skills/path/scripts/workflow_run.py

@@ -43,7 +43,8 @@ def _task_member(repo: Path, project_dir: str, task_id: str):
 
 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, kind: str = None) -> dict:
+                 mapper_reviewed: bool = False, kind: str = None,
+                 rerun: bool = False) -> dict:
     steps = []
     outputs = {}
     scripts = Path(__file__).resolve().parent
@@ -231,7 +232,8 @@ def run_workflow(repo: Path, action: str, project_dir: str, expected_head: str =
             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)
+            rerun_flag = ("--rerun",) if rerun else ()
+            step("lean_verification.py", "--repo", str(repo), "--expected-head", expected_head, *rerun_flag)
         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"
@@ -302,6 +304,9 @@ def main(argv=None):
     parser.add_argument("--inspection", type=Path)
     parser.add_argument("--mapper-reviewed", action="store_true")
     parser.add_argument("--kind", choices=("intent", "plan"))
+    parser.add_argument("--rerun", action="store_true",
+                        help="prepare-final: re-execute project Verify at the same head after a "
+                             "host-caused failure, appending a new ledger entry")
     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")
@@ -309,10 +314,12 @@ def main(argv=None):
         parser.error("prepare-task requires --task-id and --round-size")
     if arguments.action == "preauthorize" and not arguments.kind:
         parser.error("preauthorize requires --kind")
+    if arguments.rerun and arguments.action != "prepare-final":
+        parser.error(f"--rerun applies only to prepare-final, not {arguments.action}")
     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.kind)
+                          arguments.mapper_reviewed, arguments.kind, arguments.rerun)
     print(json.dumps(result, sort_keys=True))
     return 0 if result["status"] == "complete" else 1
 

package/skills/path/scripts/worktree_paths.py

@@ -7,11 +7,13 @@ import sys
 # Runtime helpers must not modify their immutable installation.
 sys.dont_write_bytecode = True
 
+import contextlib
 import hashlib
 import json
 import os
 import tempfile
 from pathlib import Path
+from typing import Optional
 
 if __package__:
     from . import _common
@@ -22,7 +24,39 @@ else:
         from scripts import _common
 
 
+# Run-scoped cache for read-only consumers (#469): recovery resolves a
+# placement per task, and each resolution lists the whole worktree registry
+# and re-reads the placement receipt. Within one read-only run none of that
+# can change, so the listing and the derived workspace answer once. Flows
+# that create, move, or retire worktrees never enter this scope.
+_PLACEMENT_CACHE: Optional[dict] = None
+
+
+@contextlib.contextmanager
+def readonly_placement_cache():
+    global _PLACEMENT_CACHE
+    if _PLACEMENT_CACHE is not None:  # already inside a read-only run
+        yield
+        return
+    _PLACEMENT_CACHE = {"porcelain": {}, "workspace": {}}
+    try:
+        yield
+    finally:
+        _PLACEMENT_CACHE = None
+
+
 def _worktree_list_porcelain(primary: Path) -> tuple[str, bool]:
+    if _PLACEMENT_CACHE is not None:
+        key = str(primary)
+        if key in _PLACEMENT_CACHE["porcelain"]:
+            return _PLACEMENT_CACHE["porcelain"][key]  # type: ignore[index]
+        output = _worktree_list_porcelain_uncached(primary)
+        _PLACEMENT_CACHE["porcelain"][key] = output
+        return output
+    return _worktree_list_porcelain_uncached(primary)
+
+
+def _worktree_list_porcelain_uncached(primary: Path) -> tuple[str, bool]:
     try:
         if __package__:
             from . import pipeline_git as pg
@@ -58,6 +92,17 @@ def _identity(path: Path) -> str:
 
 
 def _workspace(primary: Path, pin: bool) -> Path:
+    if _PLACEMENT_CACHE is not None and not pin:
+        key = str(primary)
+        if key in _PLACEMENT_CACHE["workspace"]:
+            return _PLACEMENT_CACHE["workspace"][key]  # type: ignore[index]
+        workspace = _workspace_uncached(primary, False)
+        _PLACEMENT_CACHE["workspace"][key] = workspace
+        return workspace
+    return _workspace_uncached(primary, pin)
+
+
+def _workspace_uncached(primary: Path, pin: bool) -> Path:
     common = Path(_git(primary, "rev-parse", "--git-common-dir"))
     common = (primary / common).resolve()
     identity = _identity(primary)

package/skills/path/templates/intent.md

@@ -123,6 +123,8 @@ paragraph the user signed off on — do not edit without a new sign-off.>
 
 ## Corrections
 
-<!-- Verbatim user corrections from playback and later phases. Append-only.
-     These are the highest-signal intent data in the file. -->
-- <date>: "<what the user said>"
+<!-- Verbatim user corrections from playback and later phases. Append-only,
+     numbered from C1: the id gives a correction citable identity — wave
+     dispositions and scope exclusions authorize through it. These are the
+     highest-signal intent data in the file. -->
+- C1 <YYYY-MM-DD>: "<what the user said>"

package/skills/path/templates/task.md

@@ -3,15 +3,22 @@ id: T001
 title: <imperative, specific>
 wave: 1
 deps: []            # task ids whose output or landed effect this task needs
-status: pending     # orchestrator-owned: pending | in-progress | done | failed | blocked
+status: pending     # orchestrator-owned: pending | in-progress | done | failed | blocked | withdrawn
 agent: null         # orchestrator-owned: set at dispatch
 base: null          # orchestrator-owned: clean layer SHA for isolated Verify
 worktree: null      # orchestrator-owned: isolated task worktree while active
 task_branch: null   # orchestrator-owned: gsd-path-task/<id> while parallel; null when serial
+# member_base: <sha> # orchestrator-owned, member-repo tasks only: the member repository's starting commit
+# reads:                # optional read-only cross-repository inputs, one per line (#471):
+#   - web: .github/workflows/build.yml    # a member path at that member's validation base
+#   - coordinator: docs/decisions.tsv     # from a member task: the coordinator's layer base
 # 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
 # supersedes: [<task id>]  # only when INTENT requires it: earlier-wave tasks whose behavior this task replaces; retires their Verify
+# Withdrawn — <YYYY-MM-DD>: "<owner ruling verbatim>"  # only in the Log, only
+#   after an owner ruling: status: withdrawn keeps the id in inventory with no
+#   dispatch and no landing; the citation line is mandatory or the gate fails (#483)
 files:              # every file this task may touch — dispatch checks overlap
   - <path>
 ---

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

@@ -31,15 +31,25 @@ Tasks reviewed: <count>
      the task file. An evidence line starts with `- ✅ ` (pass) or `- ❌ `
      (fail). A section needs one or more lines with the marker of its own
      verdict, so a failed task needs a `- ❌ ` criterion line.
-     Per task criterion: copy every word of the acceptance/interface
-     criterion before the em dash; join wrapped lines and sub-bullets with
-     spaces (the `- ` markers of sub-bullets are optional). An AC id or
-     summary alone cannot be matched by review_findings.py.
+     On a `- ✅ ` line, name the criterion either by copying every word of
+     the acceptance/interface criterion before the em dash (join wrapped
+     lines and sub-bullets with spaces; the `- ` markers of sub-bullets are
+     optional) or by citing its stable id in the task's numbered list
+     (`T001/AC1`, `T001/IF2`) together with the evidence. A `- ❌ ` line
+     always copies the criterion verbatim: review_findings.py groups
+     findings by that text.
      Write literal markup and code in backticks inside a sentence: text
      such as <b> outside backticks reads as an unfilled placeholder. -->
 - ✅ <criterion> — <evidence: verify output / file:line checked>
 - ❌ <criterion> — found: <what exists instead, file:line>
   fix: <concrete direction a coder can execute without re-investigating>
+- <task id>/<ACn|IFn> — disposition: <authority and date> (<Cn>): <reason>
+     <!-- Only for a claim an INTENT.md correction defers or excludes; cite
+          its number (C1) — a disposition with no citation, or with a Cn
+          that INTENT.md `## Corrections` does not define, fails the gate. Every
+          acceptance criterion and interface bullet must otherwise appear
+          above, as evidence or a finding. One line may cite several ids
+          (T001/AC1, T001/AC2) when one observation covers them. -->
 
 Warnings (non-blocking):
 - <weakened test / unfailable verify / none>
@@ -52,18 +62,24 @@ Contract violations (blocking):
 ## Intent coverage
 
 <!-- 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.
+     wave, ending `: pass` or `: fail`, in ascending SC id order (SC2
+     before SC4), with an em dash (—) after the id. `scripts/check_handoffs.py
+     wave --review <this file>` gates the SC ids, their order, and
+     verdicts. Omit this section when no task in the wave owns an SC.
      Copy every word of the criterion from INTENT.md `## Success criteria`:
      join indented continuation lines and sub-bullets with a single space
      (the `- ` markers of sub-bullets are optional). The gate compares every
      other word: no paraphrase, no dropped sub-bullet.
      Each SC block needs an evidence line with the marker of its own
-     verdict: `- ✅ ` (pass) or `- ❌ ` (fail). -->
+     verdict: `- ✅ ` (pass) or `- ❌ ` (fail).
+     Under a `pass` SC only, record each subclaim an INTENT.md correction
+     excludes as `- Excluded by <Cn>: <subclaim>`; the Cn must exist in
+     INTENT.md `## Corrections`. An exclusion records retained scope, not
+     a failure. -->
 
 ### SC1 — <criterion from INTENT.md>: <pass | fail>
 - ✅ <evidence: verify output / file:line checked>
+- Excluded by <Cn>: <subclaim the correction removes>
 - ❌ <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: