task-pipeline-skill 1.94.1 → 1.96.0

package/plugins/task-pipeline/skills/task-pipeline/references/waves.md

@@ -211,11 +211,13 @@ In this order, inside the wave rather than after it:
 1. **Verify.** Every node the wave closes is certified ([`certification.md`](certification.md)),
    most of it already, as each node landed,
    and [`audit.md`](audit.md)'s exit is re-measured over what the wave touched.
-2. **Finish and fix — one fix round**, inside [`loop-guard.md`](loop-guard.md)'s caps.
-   Findings against this wave's nodes are fixed here or parked with a board row and reason.
-   Findings elsewhere join the inventory for a planned node; only the closed hotfix lane
-   bypasses that design ([`iteration.md`](iteration.md) → *No fix travels alone*). Nothing
-   is dropped silently.
+2. **Finish and fix — one fix round, for blocking findings only**, inside
+   [`loop-guard.md`](loop-guard.md)'s caps. Every finding is triaged when found
+   ([`finish-line.md`](finish-line.md) → *Triage at discovery*): blocking findings against
+   this wave's nodes are fixed here or parked with a board row and reason; deferred ones
+   become board rows; noise is one ledger line. Findings elsewhere join the inventory for a
+   planned node; only the closed hotfix lane bypasses that design
+   ([`iteration.md`](iteration.md) → *No fix travels alone*). Nothing is dropped silently.
 3. **Document** — the Doc Loop and the stage-9 propagation matrix
    ([`documentation.md`](documentation.md)), scoped to the wave: scenarios, decisions,
    docs and registers in the same change as the code.
@@ -224,7 +226,8 @@ In this order, inside the wave rather than after it:
    items, not only the board*). A re-plan is a committed `revisions` entry plus a canvas
    edit, never a quiet change.
 6. **Re-measure the inventory and re-cut the remaining waves** from the updated target —
-   never from the original guess. New findings join the inventory with ids.
+   never from the original guess. New findings join the inventory with ids and their
+   triage class; a deferred one never adds a wave to this release.
 
 ## A board bigger than one release
 

package/plugins/task-pipeline/skills/task-pipeline/scripts/graph.py

@@ -1580,7 +1580,7 @@ def cmd_producer(graph, args):
 def cmd_doctrine(graph, args):
     """Which doctrine this run actually read — B-061.
 
-    The bundle is 41 reference files. A run reads some subset and nothing recorded which,
+    The bundle is 53 reference files. A run reads some subset and nothing recorded which,
     so **a skipped file and a read one were indistinguishable** — the class every guard in
     this repository exists to catch, left standing over the doctrine itself.
 

package/plugins/task-pipeline/skills/task-pipeline/scripts/stage_checkpoint.py

@@ -10,9 +10,9 @@ run goes on exactly as before, and the ledger says memory was unavailable.
 This script never talks to Observatory: the agent calls the tool. The script does the two
 deterministic halves around that call, so nothing about the checkpoint is left to recall:
 
-    stage_checkpoint.py emit   [--ledger PATH] [--project project:<slug>]
+    stage_checkpoint.py emit   [--ledger PATH] [--project-root PATH] [--project project:<slug>]
                                [--constraint TEXT ...] [--credential PROJECT/ENV/NAME ...]
-        prints the tool's arguments as JSON, from the ledger's last `stage:` line
+        prints the tool's arguments as JSON, from the ledger and selected project profile
     stage_checkpoint.py record --answer FILE|-   [--ledger PATH]
         reads the tool's answer and keeps `workflowId` and `leaseId` for the next boundary
     stage_checkpoint.py record --unavailable "<reason>" [--for-run]   [--ledger PATH]
@@ -24,13 +24,17 @@ deterministic halves around that call, so nothing about the checkpoint is left t
 
 What it keeps, and where:
 
-- The arguments carry no prose the ledger does not hold: the run's topic is the goal, the
+- The ledger supplies the observed verdicts; the selected project `pipeline.json` supplies
+  stage order and names (bundled default only when project config is absent). The run's topic is the goal, the
   ledger's verdicts are `done`, the next stage is `open`, the operator's constraints come in
   as `--constraint`, keys are passed by NAME only (`--credential`), and the git checkout is
   an artifact (branch and a 12-character head). Observatory redacts what it stores as well.
-- `idempotencyKey` is derived from the run's topic and the exact `stage:` line, so a retry
+- `idempotencyKey` is derived from the run's topic and the exact `stage:` line (also the
+  profile digest for a configured profile), so a retry
   of the same boundary replays the first answer, and a stage that runs again (a new line, a
   new time) is a new checkpoint.
+- The first emit saves a run-scoped profile binding before returning arguments. A changed
+  profile/run or unreadable saved state refuses instead of switching an existing workflow.
 - `workflowId` and `leaseId` live in `.task-pipeline/memory.json`, mode 0600, beside the
   ledger in the git-ignored run directory, with the constraints and key names given so far:
   they are stated once and carried to every later boundary. The lease token is a write right: it is never
@@ -60,6 +64,7 @@ import json
 import os
 import pathlib
 import re
+import stat
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -80,15 +85,70 @@ MEMORY_EVENT = re.compile(r"^event:\s*memory\s+—\s")
 MEMORY_UNAVAILABLE = re.compile(r"^event:\s*memory\s+—\s+unavailable\b")
 
 
-def _stages() -> dict[int, str]:
-    """The stage names by id, from the bundle's own `pipeline.example.json` — the file the
-    validator compares with `references/stages.md`, so this list cannot drift from it."""
-    path = pathlib.Path(__file__).resolve().parents[1] / "pipeline.example.json"
+def _profile(root: pathlib.Path) -> tuple[list[dict], dict]:
+    """Admit the selected profile for the numeric checkpoint ledger, not execute gates."""
+    path = root / "pipeline.json"
     try:
+        path.lstat()
+        configured = True
+    except FileNotFoundError:
+        configured = False
+    except OSError:
+        raise SystemExit("stage_checkpoint: selected profile cannot be read")
+    if not configured:
+        path = pathlib.Path(__file__).resolve().parents[1] / "pipeline.example.json"
+    try:
+        if not stat.S_ISREG(path.stat().st_mode):
+            raise SystemExit("stage_checkpoint: selected profile is not a regular file")
         doc = json.loads(path.read_text(encoding="utf-8"))
-        return {int(s["id"]): str(s["name"]) for s in doc["stages"]}
-    except (OSError, ValueError, KeyError, TypeError):
-        return {}
+    except (OSError, ValueError, UnicodeError):
+        raise SystemExit("stage_checkpoint: selected profile cannot be read as JSON")
+    if not isinstance(doc, dict) or not isinstance(doc.get("stages"), list) or not doc["stages"]:
+        raise SystemExit("stage_checkpoint: selected profile needs a nonempty stages array")
+    mandatory = doc.get("must_understand", [])
+    if not isinstance(mandatory, list) or mandatory:
+        raise SystemExit("stage_checkpoint: unsupported mandatory profile capabilities")
+    stages, ids, states = [], set(), set()
+    for ordinal, stage in enumerate(doc["stages"]):
+        if not isinstance(stage, dict):
+            raise SystemExit("stage_checkpoint: malformed selected stage")
+        sid, state = stage.get("id", ordinal), stage.get("state")
+        name = stage.get("name", state)
+        if isinstance(name, str) and not name.strip():
+            name = state  # optional human label may be empty; stable state still identifies it
+        skills, gate = stage.get("skills"), stage.get("gate")
+        if (type(sid) is not int or sid < 0 or sid in ids or
+                not isinstance(state, str) or not state.strip() or state in states or
+                not isinstance(name, str) or not name.strip() or "\n" in name or "\r" in name or
+                not isinstance(skills, list) or not skills or
+                any(not isinstance(v, str) or not v.strip() for v in skills) or
+                not isinstance(gate, dict) or gate.get("type") not in ("auto", "manual", "judgment") or
+                not isinstance(gate.get("check"), str) or not gate["check"].strip() or
+                (gate["type"] == "judgment" and
+                 (not isinstance(gate.get("judge"), str) or not gate["judge"].strip()))):
+            raise SystemExit("stage_checkpoint: malformed or ambiguous selected stage")
+        ids.add(sid)
+        states.add(state)
+        stages.append({"id": sid, "name": name, "gate": gate["type"]})
+    semantic = {k: doc[k] for k in ("stages", "kernel", "must_understand") if k in doc}
+    identity = {"root": str(root), "source": "pipeline.json" if configured else "bundled-default",
+                "digest": hashlib.sha256(json.dumps(semantic, sort_keys=True,
+                                                    ensure_ascii=False).encode()).hexdigest()}
+    return stages, identity
+
+
+def _root(ledger: pathlib.Path, given: str | None) -> pathlib.Path:
+    if given:
+        root = pathlib.Path(given).resolve()
+        if not root.is_dir() or not ledger.is_relative_to(root):
+            raise SystemExit("stage_checkpoint: --project-root must contain the ledger")
+        return root
+    if ledger.parent.name == ".task-pipeline":
+        return ledger.parent.parent
+    git_root = _git(ledger.parent, "rev-parse", "--show-toplevel")
+    if not git_root:
+        raise SystemExit("stage_checkpoint: relocated ledger requires --project-root")
+    return pathlib.Path(git_root).resolve()
 
 
 def _now() -> str:
@@ -145,6 +205,8 @@ def _read_ledger(path: pathlib.Path) -> tuple[str, list[tuple]]:
     topic, stages = (TOPIC.match(rl).group(1) if rl else None), []
     for line in lines:
         s = STAGE.match(line)
+        if line.startswith("stage:") and not s:
+            raise SystemExit("stage_checkpoint: malformed stage ledger line")
         if s:
             stages.append((int(s.group(1)), s.group(2), s.group(3), s.group(4), s.group(5), line))
     if not topic:
@@ -176,14 +238,48 @@ def marker_for_this_run(ledger: pathlib.Path, state: dict) -> dict | None:
     return gone
 
 
+def _canonical_ledger(ledger: pathlib.Path) -> pathlib.Path:
+    # A file alias can put a prior record beside the link while emit read its target.
+    # Refuse it rather than choosing one of two potentially live workflow receipts.
+    try:
+        mode = ledger.lstat().st_mode
+    except FileNotFoundError:
+        return ledger.resolve()
+    except OSError:
+        raise SystemExit("stage_checkpoint: ledger cannot be read")
+    if stat.S_ISLNK(mode):
+        raise SystemExit("stage_checkpoint: ledger file alias is unsupported; reconcile and use the real ledger path")
+    if not stat.S_ISREG(mode):
+        raise SystemExit("stage_checkpoint: ledger is not a regular file")
+    return ledger.resolve()
+
+
 def _state_path(ledger: pathlib.Path) -> pathlib.Path:
-    return ledger.parent / STATE_NAME
+    path = _canonical_ledger(ledger).parent / STATE_NAME
+    try:
+        mode = path.lstat().st_mode
+    except FileNotFoundError:
+        return path
+    except OSError:
+        raise SystemExit("stage_checkpoint: memory state cannot be read")
+    if stat.S_ISLNK(mode):
+        raise SystemExit("stage_checkpoint: memory state link is unsafe; reconcile it before continuing")
+    if not stat.S_ISREG(mode):
+        raise SystemExit("stage_checkpoint: memory state is not a regular file")
+    return path
 
 
-def _load_state(ledger: pathlib.Path) -> dict:
+def _load_state(ledger: pathlib.Path, strict: bool = False) -> dict:
     try:
-        return json.loads(_state_path(ledger).read_text(encoding="utf-8"))
-    except (OSError, ValueError):
+        state = json.loads(_state_path(ledger).read_text(encoding="utf-8"))
+        if not isinstance(state, dict):
+            raise ValueError("state is not an object")
+        return state
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError, UnicodeError):
+        if strict:
+            raise SystemExit("stage_checkpoint: memory state cannot be read")
         return {}
 
 
@@ -224,14 +320,28 @@ def _project(root: pathlib.Path, given: str | None) -> str:
 
 
 def emit(ledger: pathlib.Path, project: str | None, constraints: list[str],
-         credentials: list[str]) -> dict:
+         credentials: list[str], project_root: str | None = None) -> dict:
+    ledger = _canonical_ledger(ledger)
     topic, stages = _read_ledger(ledger)
-    names = _stages()
+    root = _root(ledger, project_root)
+    profile, identity = _profile(root)
+    names = {s["id"]: s["name"] for s in profile}
     if not stages:
         raise SystemExit("stage_checkpoint: no `stage:` line yet — a checkpoint follows a gate")
     sid, name, gate, verdict, at, line = stages[-1]
-    root = ledger.parent.parent if ledger.parent.name == ".task-pipeline" else ledger.parent
-    state = _load_state(ledger)
+    state = _load_state(ledger, strict=True)
+    run = run_key(ledger.read_text(encoding="utf-8").splitlines())
+    binding = {**identity, "run": run}
+    previous = state.get("profile")
+    if previous is None and state.get("workflowId") and identity["source"] != "bundled-default":
+        raise SystemExit("stage_checkpoint: legacy workflow has no selected-profile binding; reconcile before emitting")
+    if previous is not None and previous != binding:
+        raise SystemExit("stage_checkpoint: selected profile or run changed; reconcile the saved workflow before emitting")
+    for observed in stages:
+        selected = next((s for s in profile if s["id"] == observed[0]), None)
+        if selected is None or (identity["source"] != "bundled-default" and
+                                (selected["name"] != observed[1] or selected["gate"] != observed[2])):
+            raise SystemExit("stage_checkpoint: ledger stage does not match the selected profile")
     # CONSTRAINTS AND KEYS OUTLIVE THE BOUNDARY THEY WERE GIVEN AT. The operator states them
     # once; a later boundary that dropped them would hand a successor an empty list — the
     # one thing a successor must never act without (found by the live receipt, 2026-10-05).
@@ -241,12 +351,18 @@ def emit(ledger: pathlib.Path, project: str | None, constraints: list[str],
     done = [{"step_id": f"stage-{s[0]}", "result": f"{s[1]}: gate {s[2]}, verdict {s[3]} at {s[4]}",
              "evidence": [f"ledger: {ledger.name}", *reviews.get(s[0], [])]}
             for s in stages if s[3] in ("pass", "skip")]
-    nxt = sid + 1 if verdict in ("pass", "skip") else sid
-    last = max(names) if names else 10
-    open_steps = [] if sid >= last and verdict == "pass" else [{
-        "step_id": f"stage-{nxt}",
-        "next_action": (f"enter stage {nxt} {names.get(nxt, '')}".strip() if nxt != sid
-                        else f"repair stage {sid} {name}: its gate failed")}]
+    position = next(i for i, s in enumerate(profile) if s["id"] == sid)
+    terminal = position == len(profile) - 1
+    closed = terminal and verdict == "pass"
+    if closed:
+        open_steps = []
+    elif verdict in ("pass", "skip") and not terminal:
+        nxt = profile[position + 1]["id"]
+        open_steps = [{"step_id": f"stage-{nxt}", "next_action": f"enter stage {nxt} {names[nxt]}"}]
+    else:
+        action = (f"confirm stage {sid} {name}: final stage was skipped" if verdict == "skip"
+                  else f"repair stage {sid} {name}: its gate did not pass")
+        open_steps = [{"step_id": f"stage-{sid}", "next_action": action}]
     creds = []
     for c in credentials:
         parts = c.split("/")
@@ -258,21 +374,26 @@ def emit(ledger: pathlib.Path, project: str | None, constraints: list[str],
     if head:
         artifacts.append({"kind": "git", "path": str(root), "branch": branch or "", "head": head[:12]})
     body = {"goal": topic,
-            "plan": [{"step_id": f"stage-{i}", "title": names[i]} for i in sorted(names)],
+            "plan": [{"step_id": f"stage-{i}", "title": names[i]} for i in names],
             "done": done, "open": open_steps, "constraints": constraints,
             "artifacts": artifacts, "notes": f"task-pipeline stage boundary; run ledger {ledger}"}
     if creds:
         body["credentials"] = creds
+    key = f"{topic}\n{line}"
+    if identity["source"] != "bundled-default":
+        key += "\n" + identity["digest"]
     args = {"owner": OWNER,
-            "idempotencyKey": "tp-" + hashlib.sha256(f"{topic}\n{line}".encode()).hexdigest()[:32],
+            "idempotencyKey": "tp-" + hashlib.sha256(key.encode()).hexdigest()[:32],
             "stepId": f"stage-{sid}", "status": STATUS.get(verdict, "in_progress"), "body": body,
-            "close": sid >= last and verdict == "pass"}
+            "close": closed}
     if state.get("workflowId") and state.get("leaseId"):
         args["workflowId"], args["leaseId"] = state["workflowId"], state["leaseId"]
     else:
         args["projectId"] = _project(root, project)
-    if constraints != state.get("constraints", []) or credentials != state.get("credentials", []):
-        _save_state(ledger, {**state, "constraints": constraints, "credentials": credentials})
+    if (previous != binding or constraints != state.get("constraints", []) or
+            credentials != state.get("credentials", [])):
+        _save_state(ledger, {**state, "constraints": constraints, "credentials": credentials,
+                             "profile": binding})
     return args
 
 
@@ -344,7 +465,7 @@ def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | Non
     lease = answer.get("leaseId") or state.get("leaseId")
     if not wid:
         raise SystemExit("stage_checkpoint: the answer names no workflowId")
-    _save_state(ledger, {**{k: v for k, v in state.items() if k in ("constraints", "credentials")},
+    _save_state(ledger, {**{k: v for k, v in state.items() if k in ("constraints", "credentials", "profile")},
                          "workflowId": wid, **({"leaseId": lease} if lease else {})})
     rev = (answer.get("checkpoint") or {}).get("revision") or answer.get("revision") or "?"
     step = answer.get("stepId") or "?"
@@ -406,6 +527,7 @@ def main(argv: list[str]) -> int:
     sub = p.add_subparsers(dest="cmd", required=True)
     e = sub.add_parser("emit", help="print the checkpoint tool's arguments")
     e.add_argument("--ledger", default=DEFAULT_LEDGER)
+    e.add_argument("--project-root", help="explicit project root for a relocated ledger")
     e.add_argument("--project", help="project:<slug>; default the checkout's folder name")
     e.add_argument("--constraint", action="append", default=[], help="repeatable")
     e.add_argument("--credential", action="append", default=[], help="PROJECT/ENV/NAME, repeatable")
@@ -430,9 +552,10 @@ def main(argv: list[str]) -> int:
     ac.add_argument("--handoff-id", required=True)
     ac.add_argument("--session")
     a = p.parse_args(argv)
-    ledger = pathlib.Path(a.ledger)
+    ledger = _canonical_ledger(pathlib.Path(a.ledger))
+    _state_path(ledger)  # every command refuses unsafe aliases before producing tool arguments
     if a.cmd == "emit":
-        print(json.dumps(emit(ledger, a.project, a.constraint, a.credential), ensure_ascii=False))
+        print(json.dumps(emit(ledger, a.project, a.constraint, a.credential, a.project_root), ensure_ascii=False))
         return 0
     if a.cmd == "handoff":
         print(json.dumps(handoff(ledger, a.to_provider, a.to_model, a.reason, a.offer_ttl),

package/plugins/task-pipeline/skills/task-pipeline/scripts/waves.py

@@ -30,6 +30,22 @@ reviewed; a table and a re-run can. This script is that re-run:
         refused halfway and a refused one writes nothing. Plan nodes the graph lacks are named
         and exit 1 before any write, unless --only-present
         (a plan that spans several repositories' graphs).
+    waves.py finish --inventory FILE --max-rounds N --max-releases M (--rounds K | --ledger RUN.md)
+                    --checks K/M --artefact NAME@SHA [--releases R] [--operator-go]
+        the finish-line verdict (`references/finish-line.md`) from the triaged items, and the
+        finish block printed. Only `triage: blocking` items count, less those closed as
+        duplicate, stale or not-reproduced; deferred and noise never change the verdict. The
+        round count is explicit: --rounds, or the ledger's `round: <N> — <reading> — new
+        blocking <k>` lines, whose counts must match the inventory. Exit 0 done (the last two
+        rounds found no new blocking item, none is open, --checks is all green, and the rounds
+        are within --max-rounds or --operator-go is passed); 5 the budget reached before done
+        (rounds at --max-rounds, releases at --max-releases with a blocker open, or done past
+        the round budget without --operator-go); 6 diverging (the blocking count did not fall
+        from one round that found some to the next, or it did not fall and the last round's
+        self-inflicted >= new, from round 2 on); 3 continue (including no --checks); 1
+        malformed (a schema error, a blocking item without `test` or `round`, B3 with
+        base_repro yes, a round past the rounds run, no round count, a ledger that disagrees,
+        --max-rounds below 2, an artefact that is not NAME@SHA).
 
 **The plan** is any JSON whose `nodes` list `{id, wave, closes}` — a work graph that carries
 `closes` on its nodes is one, and so is a short hand-written table. A node may carry
@@ -42,7 +58,7 @@ described in `templates/inventory.schema.json` (`$defs.modules`, `$defs.plan`).
 are listed in (wave, id) order, counts are sorted. A re-cut is a diff to a table and a
 re-run, which a reviewer can read.
 
-Exit codes: 0 done; 1 an item lands nowhere, or the tables and the inventory disagree, or a
+Exit codes (every verb but `finish`, whose own are above): 0 done; 1 an item lands nowhere, or the tables and the inventory disagree, or a
 graph move was refused; 2 a schema error, a table error (an id on two modules), usage, or an
 unreadable file. Stdlib only (`references/portability.md`).
 """
@@ -62,11 +78,18 @@ SCHEMA = HERE.parent / "templates" / "inventory.schema.json"
 GRAPH_PY = HERE / "graph.py"
 REQUIRED = ("id", "title", "area", "kind", "severity", "evidence", "proposed_fix")
 OPTIONAL = ("status", "source", "source_file", "repo", "module", "node", "wave", "release",
-            "register_id", "blocked_by", "closable_in_one_pass", "needs_operator", "notes")
+            "register_id", "blocked_by", "closable_in_one_pass", "needs_operator", "notes",
+            "triage", "test", "round", "base_repro", "blast", "rung")
 SEVERITY = ("critical", "high", "medium", "low", "info")
 STATUS = ("open", "changed", "closed", "fixed", "fixed-elsewhere", "duplicate", "moved", "stale",
           "not-reproduced", "carried")
 OPEN = ("open", "changed")
+# The finish line's vocabulary (references/finish-line.md → Triage at discovery). The
+# validator holds these to the doctrine, the run-ledger grammar and inventory/1's enums.
+TRIAGE = ("blocking", "deferred", "noise")
+TESTS = ("B1", "B2", "B3", "B4")
+BASE_REPRO = ("yes", "no", "n/a")
+RUNGS = ("I1", "I2", "I3", "I4", "I5")
 ID = re.compile(r"^[A-Za-z][A-Za-z0-9._-]{0,63}$")
 KIND = re.compile(r"^[a-z][a-z0-9-]*$")
 EXT = re.compile(r"^x-[a-z0-9-]+$")
@@ -115,9 +138,34 @@ def item_errors(x: object) -> list[str]:
     for k in ("closable_in_one_pass", "needs_operator"):
         if k in x and not isinstance(x[k], bool):
             errs.append(f"{iid}: `{k}` is not a boolean")
+    if "triage" in x and x["triage"] not in TRIAGE:
+        errs.append(f"{iid}: `triage` {x['triage']!r} is not one of {', '.join(TRIAGE)}")
+    if "test" in x and x["test"] not in TESTS:
+        errs.append(f"{iid}: `test` {x['test']!r} is not one of {', '.join(TESTS)}")
+    if "round" in x and not _posint(x["round"]):
+        errs.append(f"{iid}: `round` is not an integer from 1")
+    if "base_repro" in x and x["base_repro"] not in BASE_REPRO:
+        errs.append(f"{iid}: `base_repro` {x['base_repro']!r} is not one of {', '.join(BASE_REPRO)}")
+    if "blast" in x and not (_posint(x["blast"]) and x["blast"] <= 3):
+        errs.append(f"{iid}: `blast` is not 1, 2 or 3")
+    if "rung" in x and x["rung"] not in RUNGS:
+        errs.append(f"{iid}: `rung` {x['rung']!r} is not one of {', '.join(RUNGS)}")
+    if x.get("triage") == "blocking":
+        errs += [f"{iid}: blocking without `{k}` — a blocking finding names the B test that "
+                 "matched and the round that found it" for k in ("test", "round") if k not in x]
+        if x.get("test") == "B3" and x.get("base_repro") == "yes":
+            errs.append(f"{iid}: B3 says it passes at Base, and `base_repro: yes` says it fails "
+                        "there — one of the two is wrong")
+    elif "test" in x:
+        errs.append(f"{iid}: `test` on an item that is not blocking — a B test is what makes a "
+                    "finding blocking; without one it is deferred or noise")
     return errs
 
 
+def _posint(v) -> bool:
+    return isinstance(v, int) and not isinstance(v, bool) and v >= 1
+
+
 def schema_errors(items: list) -> list[str]:
     """inventory/1 itself, applied where `jsonschema` is installed. `item_errors` is the
     hand copy every install has; test/waves_test.py holds the two to one verdict."""
@@ -504,6 +552,163 @@ def cmd_sync_graph(a) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------- the finish line
+
+# A blocking item closed as one of these was never a blocker: it counts in no round.
+NOT_COUNTED = ("duplicate", "stale", "not-reproduced")
+ROUND_LINE = re.compile(r"^round:\s*(\d+)\s*[—-]\s*(.*?)\s*[—-]\s*new blocking\s*(\d+)\s*$")
+ARTEFACT = re.compile(r"^[^@\s]+@[0-9a-f]{7,40}$")
+
+
+def _priority(x: dict):
+    """Top priority first: the impact rung, then blast, then severity, then the id. Where an
+    item was found is not an input — a fresh finding is not next because it is fresh."""
+    rung = RUNGS.index(x["rung"]) + 1 if x.get("rung") in RUNGS else 0
+    return (-rung, -(x.get("blast") or 0), SEVERITY.index(x["severity"]), _natural(x["id"]))
+
+
+def _board_id(x: dict) -> str:
+    return x.get("register_id") or x["id"]
+
+
+def ledger_rounds(path: pathlib.Path) -> dict[int, int]:
+    """{round: new blocking} from the run ledger's `round:` lines (templates/run.md)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise Fail(1, [f"the run ledger {path} cannot be read ({type(exc).__name__})"])
+    out, errs = {}, []
+    for n, line in enumerate(text.splitlines(), 1):
+        if not line.startswith("round:"):
+            continue
+        m = ROUND_LINE.match(line.strip())
+        if not m:
+            errs.append(f"{path}:{n}: not `round: <N> — <reading> — new blocking <k>`")
+            continue
+        r = int(m[1])
+        if r < 1 or r in out:
+            errs.append(f"{path}:{n}: round {r} is below 1 or written twice")
+        out[r] = int(m[3])
+    if out and sorted(out) != list(range(1, max(out) + 1)):
+        errs.append(f"{path}: rounds {sorted(out)} are not 1..{max(out)} — a round line is missing")
+    if errs:
+        raise Fail(1, errs)
+    return out
+
+
+def finish_verdict(items: list[dict], rounds: int, max_rounds: int, max_releases: int,
+                   releases: int, checks: tuple[int, int] | None,
+                   operator_go: bool = False) -> tuple[int, str, dict]:
+    """(exit code, word, facts) — the finish line computed from the triaged items alone.
+    Deferred and noise items are counted for the block and never read for the verdict."""
+    triaged = [x for x in items if "triage" in x]
+    late = [f"{x['id']}: found in round {x['round']}, and only {rounds} round(s) ran"
+            for x in triaged if _posint(x.get("round")) and x["round"] > rounds]
+    if late:
+        raise Fail(1, late)
+    blocking = [x for x in triaged if x["triage"] == "blocking" and _status(x) not in NOT_COUNTED]
+    new = [sum(1 for x in blocking if x["round"] == r) for r in range(1, rounds + 1)]
+    selfinf = sum(1 for x in blocking if x["round"] == rounds and x.get("base_repro") == "no")
+    open_b = [x for x in blocking if _needs_node(x)]
+    facts = {"rounds": rounds, "new": new, "open": open_b, "fixed": len(blocking) - len(open_b),
+             "self_inflicted": selfinf}
+    clean = rounds >= 2 and new[-1] == 0 and new[-2] == 0 and not open_b
+    green = checks is not None and checks[0] == checks[1]
+    if clean and green:
+        if rounds <= max_rounds:
+            return 0, "done", facts
+        if operator_go:
+            return 0, "done", dict(facts, why=f"past budget — rounds {rounds}/{max_rounds} on the "
+                                              "operator's go")
+        return 5, "budget", dict(facts, why=f"past budget — operator's go required: done at round "
+                                            f"{rounds}/{max_rounds}")
+    if rounds >= max_rounds:
+        owed = (f"{len(open_b)} blocker(s) open" if open_b else
+                "exit checks not supplied" if checks is None else
+                "exit checks not all green" if not green else "the second clean round still owed")
+        return 5, "budget", dict(facts, why=f"rounds {rounds}/{max_rounds} reached before done — {owed}")
+    if open_b and releases >= max_releases:
+        return 5, "budget", dict(facts, why=f"releases {releases}/{max_releases} reached before "
+                                            f"done — {len(open_b)} blocker(s) open")
+    if rounds >= 2 and new[-1] >= new[-2] > 0:
+        return 6, "blocked", dict(facts, why=f"diverging — new blocking {new[-2]} → {new[-1]} "
+                                             "did not fall; run the loop guard's break protocol")
+    if rounds >= 2 and new[-1] >= new[-2] and selfinf and selfinf >= new[-1] - selfinf:
+        return 6, "blocked", dict(facts, why=f"diverging — round {rounds}: {selfinf} self-inflicted "
+                                             f"≥ {new[-1] - selfinf} new, and the count did not "
+                                             "fall; run the loop guard's break protocol")
+    why = (f"{len(open_b)} blocker(s) open" if open_b else
+           "exit checks not supplied — pass --checks K/M read on the artefact" if checks is None else
+           "exit checks not all green" if not green else
+           "a second round with no new blocking finding is owed")
+    return 3, "continue", dict(facts, why=why)
+
+
+def cmd_finish(a) -> int:
+    try:
+        _, items = load_inventory(pathlib.Path(a.inventory))
+    except Fail as exc:
+        raise Fail(1, exc.reasons)  # a malformed inventory is malformed here, never usage
+    for flag, v, least in (("--max-rounds", a.max_rounds, 2), ("--max-releases", a.max_releases, 1),
+                           ("--releases", a.releases, 0), ("--rounds", a.rounds, 0)):
+        if v is not None and v < least:
+            raise Fail(1, [f"{flag} {v} is below {least}" + (
+                " — done needs two clean rounds, so a budget of one can never be met"
+                if flag == "--max-rounds" else "")])
+    # THE ROUND COUNT IS EXPLICIT. A clean round leaves no item, so a count derived from the
+    # items can never see the two clean rounds `done` needs: the verdict would stay
+    # `continue` for ever. It comes from --rounds or from the ledger's `round:` lines.
+    led = ledger_rounds(pathlib.Path(a.ledger)) if a.ledger else None
+    if led is not None and not led and a.rounds is None:
+        raise Fail(1, [f"{a.ledger} carries no `round:` line and --rounds is absent — the round "
+                       "count cannot be read"])
+    if led is None and a.rounds is None:
+        raise Fail(1, ["the round count is not given — pass --rounds N, or --ledger with the run "
+                       "ledger's `round:` lines; clean rounds leave no item to count"])
+    rounds = a.rounds if a.rounds is not None else max(led)
+    if led and a.rounds is not None and a.rounds != max(led):
+        raise Fail(1, [f"--rounds {a.rounds} and the ledger's {max(led)} round(s) disagree"])
+    if led:
+        counted = {r: sum(1 for x in items if x.get("triage") == "blocking" and x.get("round") == r)
+                   for r in led}
+        bad = [f"round {r}: the ledger says new blocking {k}, the inventory holds {counted[r]}"
+               for r, k in sorted(led.items()) if counted[r] != k]
+        if bad:
+            raise Fail(1, bad)
+    checks = None
+    if a.checks:
+        m = re.fullmatch(r"(\d+)/(\d+)", a.checks.strip())
+        if not m or int(m[1]) > int(m[2]) or int(m[2]) == 0:
+            raise Fail(1, [f"--checks {a.checks!r} is not K/M green of M exit checks"])
+        checks = (int(m[1]), int(m[2]))
+    if a.artefact and not ARTEFACT.match(a.artefact):
+        raise Fail(1, [f"--artefact {a.artefact!r} is not NAME@SHA (a commit of 7-40 hex digits)"])
+    code, word, f = finish_verdict(items, rounds, a.max_rounds, a.max_releases, a.releases, checks,
+                                   a.operator_go)
+    deferred = sorted((x for x in items if x.get("triage") == "deferred"), key=_priority)
+    noise = [x for x in items if x.get("triage") == "noise"]
+    risks = [x for x in deferred if x.get("blast") == 3 or x.get("rung") in ("I4", "I5")]
+    pool = sorted((x for x in items if x.get("triage") != "blocking" and _needs_node(x)
+                   and x.get("triage") != "noise"), key=_priority)
+    budget = f"rounds {f['rounds']}/{a.max_rounds} — releases {a.releases}/{a.max_releases}"
+    if word == "continue":
+        print(f"next round: {f['rounds'] + 1}/{a.max_rounds} — {f['why']} — {budget}")
+    else:
+        print(f"finish: {word} — {budget}" + (f" — {f['why']}" if f.get("why") else ""))
+    print("  exit checks: " + (f"{checks[0]}/{checks[1]} green on {a.artefact or '<artefact not named>'}"
+                               if checks else "not supplied — read them on the artefact (--checks K/M)"))
+    print(f"  blocking: {len(f['open'])} open · {f['fixed']} fixed — new per round "
+          f"{' · '.join(str(n) for n in f['new']) or 'none'}"
+          + (f" — open: {', '.join(x['id'] for x in f['open'])}" if f["open"] else ""))
+    top = ", ".join(_board_id(x) for x in deferred[:5]) + (" …" if len(deferred) > 5 else "")
+    print(f"  deferred: {len(deferred)}" + (f" → {top}" if deferred else ""))
+    print(f"  noise: {len(noise)}")
+    print("  known risks: " + (", ".join(_board_id(x) for x in risks) or "none"))
+    print("  next: " + (f"{_board_id(pool[0])} (new iteration)" if pool
+                         else "highest-priority board row (read the board)"))
+    return code
+
+
 def main(argv: list[str]) -> int:
     p = argparse.ArgumentParser(prog="waves.py", description=__doc__.split("\n")[0])
     sub = p.add_subparsers(dest="cmd", required=True)
@@ -531,9 +736,20 @@ def main(argv: list[str]) -> int:
                                         "a lowering is refused")
     s.add_argument("--only-present", action="store_true",
                    help="ignore plan nodes this graph does not hold")
+    f = sub.add_parser("finish", help="the finish-line verdict from the triaged items, and the block")
+    f.add_argument("--inventory", required=True)
+    f.add_argument("--max-rounds", type=int, required=True, help="run.finish.maxRounds (default 3, at least 2)")
+    f.add_argument("--max-releases", type=int, required=True, help="run.finish.maxReleases (default 2)")
+    f.add_argument("--releases", type=int, default=0, help="releases this iteration made so far")
+    f.add_argument("--rounds", type=int, help="rounds run, clean ones included")
+    f.add_argument("--ledger", help="the run ledger; its `round:` lines are the round count")
+    f.add_argument("--operator-go", action="store_true",
+                   help="the operator's recorded go for rounds past --max-rounds")
+    f.add_argument("--checks", help="K/M — exit checks green on the artefact")
+    f.add_argument("--artefact", help="what they ran on, as NAME@SHA")
     a = p.parse_args(argv)
     verbs = {"merge": cmd_merge, "assign": cmd_assign, "count": cmd_count, "validate": cmd_validate,
-             "sync-graph": cmd_sync_graph}
+             "sync-graph": cmd_sync_graph, "finish": cmd_finish}
     try:
         return verbs[a.cmd](a)
     except Fail as exc:

package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md

@@ -18,6 +18,7 @@
 - Documentation (the phase-1b inventory — the four questions)
 - Scope
 - Requirements (the REQ spine — every later stage traces to these IDs)
+- Finish line (when this iteration stops)
 - Users & context
 - Decisions locked (the grill's output)
 - Autonomy (the sweep — stages 1→10 read this instead of asking)
@@ -101,6 +102,19 @@ not continuously): `open` → `planned` → `built` → `verified` \| `partial`
 > task in smaller terms is the failure this table exists to prevent: every gate
 > after it goes green on the shrunken task and nothing reports the loss.
 
+## Finish line (when this iteration stops)
+
+The contract the iteration stops against (the skill's `references/finish-line.md`). Written
+here, confirmed with the brief, and revised only as a recorded revision — a finding is not one.
+
+- **Objective:** <one sentence: what is true when this iteration is done>
+- **Exit checks:** <REQ id → command, run on the artefact the operator uses: released /
+  installed / deployed — one line each>
+- **Scope:** <the modules, paths and REQ ids this iteration may change, as a list>
+- **Budget:** `maxRounds` 3 · `maxReleases` 2 (the defaults; `pipeline.json` →
+  `run.finish` overrides them)
+- **Base:** <the commit this iteration started from>
+
 ## Users & context
 
 - **Who / for what:** … (personas, the job being done)