task-pipeline-skill 1.95.0 → 1.97.1

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

@@ -108,14 +108,19 @@ Review in this order; stop reading the diff only when you've covered all of it.
 **Severities:**
 
 - **Critical** — wrong behavior, data loss, security hole, a red or dishonest test
-  suite. Blocks.
+  suite. Blocks the node when the defect is in its diff or caused by it.
 - **Important** — a real defect or spec gap that will bite: missing requirement,
-  unhandled failure path, a magic value the constraints named. Blocks.
+  unhandled failure path, a magic value the constraints named. Blocks the node when the
+  defect is in its diff or caused by it.
 - **Minor** — style, naming, a nit with no behavioral consequence. Never blocks;
   goes to the ledger.
 - **⚠️ Cannot verify from diff** — the requirement lives in unchanged code or spans
   tasks. Not a blocker for the reviewer; the controller resolves it.
 
+**A pre-existing defect the reviewer notices** — one the diff neither contains nor
+causes — does not block the node, whatever its severity. It goes to finish-line triage
+([`finish-line.md`](finish-line.md) → *Triage at discovery*).
+
 Formatting nits that don't change meaning are not findings. Praise is not a
 finding either.
 

package/plugins/task-pipeline/skills/task-pipeline/references/stage-05-dev.md

@@ -19,8 +19,8 @@ The full gate and freedom level remain in [stages.md](stages.md).
   contradiction that exists only between two of them.
 - **Web front end? The task's own surface is checked in a browser, not in the diff.**
   Where a browser channel is connected — `playwright` **or** `chrome-devtools`, either
-  one, whichever answers first (**how**: [`browser.md`](browser.md); which:
-  [`companion-skills.md`](companion-skills.md)): after a
+  one, on WebKit first with Chromium a stated exception (**how**, and the engine order:
+  [`browser.md`](browser.md); which: [`companion-skills.md`](companion-skills.md)): after a
   task that changes a rendered surface, load it, take a snapshot and read the
   console and the network log **before the task is marked DONE** — a component can be
   correct and land under a fixed header, and a review of the diff cannot see that.

package/plugins/task-pipeline/skills/task-pipeline/references/stage-08-post-deploy.md

@@ -13,8 +13,9 @@ The full gate and freedom level remain in [stages.md](stages.md).
 - **A deployed web target is opened, not curled.** A `200` proves the server
   answered; it says nothing about whether the page rendered, whether a bundle 404'd,
   or whether the console filled with errors on load — all three ship green past a
-  health check. Where a browser channel is connected — `playwright` **or**
-  `chrome-devtools`, either one ([`browser.md`](browser.md)) — load the deployed URL and read
+  health check. Where a browser channel is connected — `playwright` on WebKit first
+  **or** `chrome-devtools` as the stated Chromium exception, and a Chromium-only look
+  is reported as such; either one ([`browser.md`](browser.md)) — load the deployed URL and read
   the console and the network log; quote what you read, not that you looked
   ([`companion-skills.md`](companion-skills.md)). Absent → say the check was an HTTP
   response only, which is the honest name for it.

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

@@ -103,7 +103,9 @@ never that the work was skipped quietly.
   is now stale), no open contradictions, **every
   autonomy-sweep row is answered or explicitly marked "stop and ask here"**, **a
   user-facing task's brief names its `surface_class`**, the
-  **REQ table is written and every row names its check**, the carry-over ledger is
+  **REQ table is written and every row names its check**, **the brief's `## Finish line`
+  is filled — objective, exit checks on the artefact the operator uses, scope, budget and
+  base** ([`finish-line.md`](finish-line.md)), the carry-over ledger is
   seeded, **`.task-pipeline/run.md` exists and the header block has been printed**
   ([`progress.md`](progress.md)), the model decision is recorded, and the operator
   confirms the brief. Stop when a
@@ -252,8 +254,9 @@ never that the work was skipped quietly.
   page rendered — a component can be correct and land under a fixed header, a request
   can 404 while every unit test mocks it, and a console error costs nothing at test
   time. Where a browser channel is connected — `playwright` **or** `chrome-devtools`,
-  either one ([`browser.md`](browser.md) is the four commands this sentence means;
-  [`companion-skills.md`](companion-skills.md) is which channel):
+  either one, on WebKit first with Chromium a stated exception
+  ([`browser.md`](browser.md) is the four commands this sentence means and the engine
+  order; [`companion-skills.md`](companion-skills.md) is which channel):
   load the surface, take a snapshot, and read **the console and the network log**
   before calling it green. Absent, say the surface was verified **by reading the
   diff** — that is a weaker claim and the close-out records it as one, rather than
@@ -379,7 +382,9 @@ never that the work was skipped quietly.
   surfaced that nobody asked for, every decision still waiting **asked here with
   options rather than listed**, and the ambiguity count computed from the four
   registers with its ids ([`progress.md`](progress.md) → *The hand-back*) — a run
-  that cannot say what happened has not finished, it has stopped; **the environment is
+  that cannot say what happened has not finished, it has stopped; **the `finish:` line is
+  printed beside this verdict — `done`, `budget` or `blocked`, with its block**
+  ([`finish-line.md`](finish-line.md) → *The finish block*); **the environment is
   given back** — all eight classes enumerated, everything this run started ended and
   verified by re-enumerating rather than by the teardown's reply, an earlier run of
   this project ended only when **provably spent**, an item this project does not own

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

@@ -102,8 +102,9 @@ database created ten seconds ago" are different claims, and only the second one
   code does what its assertions say; it cannot see a component that renders correctly
   and lands under a fixed header, a request that 404s while every unit test mocks it,
   or a console error that costs nothing at test time. Where a browser channel is
-  connected — `playwright` **or** `chrome-devtools`, either one
-  ([`companion-skills.md`](companion-skills.md)) — open the surface and read
+  connected — `playwright` **or** `chrome-devtools`, either one, on WebKit first with
+  Chromium a stated exception ([`companion-skills.md`](companion-skills.md);
+  [`browser.md`](browser.md) → *Engine order*) — open the surface and read
   the console and the network log before calling it done — and **quote what you read**,
   not that you looked. Absent, the honest sentence is *"verified by reading the diff"*,
   which is a weaker claim and is recorded as one. Same family as a test that passes

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 52 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/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)

package/plugins/task-pipeline/skills/task-pipeline/templates/browser-claims.json

@@ -75,7 +75,7 @@
     "route": "/",
     "motion": "reduced",
     "captured_at": "2026-10-07T00:00:00Z",
-    "source": "the capability that took it, e.g. chrome-devtools take_screenshot"
+    "source": "the capability and engine that took it, e.g. playwright-cli screenshot (webkit)"
    },
    "figma_frame": "https://www.figma.com/design/<fileKey>/<file>?node-id=<frame>",
    "baseline": null,
@@ -120,7 +120,7 @@
     "route": "/",
     "motion": "reduced",
     "captured_at": "2026-10-07T00:00:00Z",
-    "source": "the capability that took it, e.g. chrome-devtools take_screenshot"
+    "source": "the capability and engine that took it, e.g. playwright-cli screenshot (webkit)"
    },
    "figma_frame": "https://www.figma.com/design/<fileKey>/<file>?node-id=<frame>",
    "baseline": null,
@@ -165,7 +165,7 @@
     "route": "/",
     "motion": "reduced",
     "captured_at": "2026-10-07T00:00:00Z",
-    "source": "the capability that took it, e.g. chrome-devtools take_screenshot"
+    "source": "the capability and engine that took it, e.g. playwright-cli screenshot (webkit)"
    },
    "figma_frame": "https://www.figma.com/design/<fileKey>/<file>?node-id=<frame>",
    "baseline": null,
@@ -210,7 +210,7 @@
     "route": "/",
     "motion": "reduced",
     "captured_at": "2026-10-07T00:00:00Z",
-    "source": "the capability that took it, e.g. chrome-devtools take_screenshot"
+    "source": "the capability and engine that took it, e.g. playwright-cli screenshot (webkit)"
    },
    "figma_frame": null,
    "baseline": null,
@@ -251,7 +251,7 @@
     "route": "/",
     "motion": "reduced",
     "captured_at": "2026-10-07T00:00:00Z",
-    "source": "the capability that took it, e.g. chrome-devtools take_screenshot"
+    "source": "the capability and engine that took it, e.g. playwright-cli screenshot (webkit)"
    },
    "figma_frame": null,
    "baseline": null,

package/plugins/task-pipeline/skills/task-pipeline/templates/inventory.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/inventory.schema.json",
   "title": "inventory/1 — <artifacts>/specs/YYYY-MM-DD-<topic>-inventory.json",
-  "description": "Wave 0's single machine-readable inventory: one item per open item of the board, every survey and every harvested source (references/waves.md, Wave 0). scripts/waves.py merges audit outputs into it (`merge`), writes `module`, `node`, `wave` and `release` from two short tables (`assign`), counts it (`count`) and refuses an item that lands nowhere (`validate`). The document is an object carrying `schema` and `items`; a bare array of items is read as the items of one. Fields a project needs beyond these go under an `x-` prefix.",
+  "description": "Wave 0's single machine-readable inventory: one item per open item of the board, every survey and every harvested source (references/waves.md, Wave 0). scripts/waves.py merges audit outputs into it (`merge`), writes `module`, `node`, `wave` and `release` from two short tables (`assign`), counts it (`count`), refuses an item that lands nowhere (`validate`) and computes the finish-line verdict from the triaged items (`finish`, references/finish-line.md). The document is an object carrying `schema` and `items`; a bare array of items is read as the items of one. Fields a project needs beyond these go under an `x-` prefix.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema", "items"],
@@ -17,6 +17,14 @@
       "additionalProperties": false,
       "patternProperties": {"^x-[a-z0-9-]+$": {}},
       "required": ["id", "title", "area", "kind", "severity", "evidence", "proposed_fix"],
+      "allOf": [
+        {"if": {"required": ["triage"], "properties": {"triage": {"const": "blocking"}}},
+         "then": {"required": ["test", "round"]}},
+        {"if": {"required": ["test"]},
+         "then": {"required": ["triage"], "properties": {"triage": {"const": "blocking"}}}},
+        {"if": {"required": ["test", "base_repro"], "properties": {"test": {"const": "B3"}}},
+         "then": {"properties": {"base_repro": {"not": {"const": "yes"}}}}}
+      ],
       "properties": {
         "id": {
           "description": "The item's id in its owning register. An item without one gets one there, in the same change. Unique across the inventory.",
@@ -60,6 +68,12 @@
         "blocked_by": {"type": "array", "items": {"type": "string"}},
         "closable_in_one_pass": {"type": "boolean"},
         "needs_operator": {"type": "boolean"},
+        "triage": {"description": "The finish-line class, set when the finding is found (references/finish-line.md → Triage at discovery). Only blocking findings argue for another round; deferred and noise never affect `waves.py finish`.", "enum": ["blocking", "deferred", "noise"]},
+        "test": {"description": "The blocking test that matched, first match wins: B1 an exit check is red; B2 a hotfix-lane entry; B3 it passes at Base; B4 a verified REQ or a published claim is false on the artefact. Required on a blocking item, refused on any other.", "enum": ["B1", "B2", "B3", "B4"]},
+        "round": {"description": "The finish-line round that found it, from 1. Required on a blocking item.", "type": "integer", "minimum": 1},
+        "base_repro": {"description": "Does the failure reproduce at the iteration's Base? `no` is a finding this iteration caused (self-inflicted).", "enum": ["yes", "no", "n/a"]},
+        "blast": {"description": "Who it hurts, 1–3 (references/prioritisation.md, backlog `sev × blast`): a priority input of a deferred row. `waves.py finish` lists a deferred item at blast 3 as a known risk.", "type": "integer", "minimum": 1, "maximum": 3},
+        "rung": {"description": "The impact rung (references/prioritisation.md): a priority input of a deferred row. `waves.py finish` lists a deferred item at I4 or I5 as a known risk.", "enum": ["I1", "I2", "I3", "I4", "I5"]},
         "notes": {"type": "string"}
       }
     },

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

@@ -20,7 +20,7 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 52 reference files and nothing recorded which of them a run read, so **a
+The bundle is 53 reference files and nothing recorded which of them a run read, so **a
 skipped file and a read one were indistinguishable** — the class every guard in this
 pipeline exists to catch, left standing over the doctrine itself.
 
@@ -48,7 +48,7 @@ same claim one level down.
 |---|---|---|
 | `unmeasured — no run ledger` | there is no ledger | nothing to read from |
 | `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
-| `N of 52 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
+| `N of 53 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **It is a disclosure: no floor, no direction, never a target.** A run that needs four files
 and reads four is not worse than one that reads thirty — and the moment the number becomes
@@ -71,6 +71,9 @@ holds: <stage id> — <n> (<class: what, owner>; … or "none") — enumerated <
 gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
 event: <compact|session-end|subagent|memory> — <detail> — <ISO-8601>
 review: <stage id> — surface <name> — rounds <N> — <returned|approved|unresolved> — <ISO-8601>
+finding: <id> — blocking:B<n> | deferred:B-NNN | noise — round <N> — base-repro yes|no|n/a
+round: <N> — <reading> — new blocking <k>
+finish: done|budget|blocked — rounds <n>/<max> — releases <n>/<max>
 read:  references/<file>.md            # hook-appended, deduped, UNATTESTED (no writer field)
 ```
 
@@ -118,6 +121,20 @@ read:  references/<file>.md            # hook-appended, deduped, UNATTESTED (no
   into the checkpoint of the stage it names, and stage 10 copies the last one per surface
   into the acceptance file. **It is a measurement, never a target**: a number of passes to
   beat is an instruction to stop showing the sheet.
+- **`finding:`** — one line per finding, written when it is found and before anyone fixes
+  it (`references/finish-line.md` → *Triage at discovery*, inside the skill). The class is
+  one of `blocking`, `deferred`, `noise`; a blocking line names its test, one of `B1`, `B2`,
+  `B3`, `B4`; a deferred line names its board row. `base-repro` says whether the failure
+  reproduces at the iteration's Base — `no` is a finding this iteration caused.
+- **`round:`** — one line per finish-line round, **clean rounds included**: its number, the
+  independent reading it ran (an audit axis, an observer, the post-release readback) and how
+  many new blocking findings it produced. A clean round leaves no `finding:` line, so without
+  this line two clean rounds and no rounds look the same; `scripts/waves.py finish --ledger`
+  counts the rounds from it and refuses when its counts disagree with the inventory.
+- **`finish:`** — one line when the iteration stops, beside stage 10's verdict: `done`,
+  `budget` or `blocked`, with the rounds and releases spent against their budget. The
+  block under it is `references/finish-line.md` → *The finish block*;
+  `scripts/waves.py finish` computes the verdict from the inventory.
 - **`touch:`** — one line per file per pass, and the reason names **what forced the
   edit**: a finding id, a failed gate item, an operator instruction. *"Cleanup"*,
   *"polish"* and *"while I was there"* are not reasons; they are churn with better
@@ -141,11 +158,18 @@ event: compact — auto — 2026-08-10T11:58Z
 event: subagent — general-purpose — 2026-08-10T12:00Z
 gate:  6 — command "npm test" — exit 0 — 2026-08-10T12:02Z
 review: 6 — surface landing — rounds 1 — returned — 2026-08-10T12:02Z
+finding: F-021 — blocking:B3 — round 1 — base-repro no
+finding: F-022 — deferred:B-118 — round 1 — base-repro yes
+round: 1 — exit checks + audit axis seams — new blocking 1
+finding: F-023 — noise — round 2 — base-repro n/a
+round: 2 — exit checks + observer — new blocking 0
+round: 3 — exit checks + post-release readback — new blocking 0
 stage: 6 Tests — gate manual — verdict pass — 2026-08-10T12:03Z
 hand:  3 — task "add CSV export to the orders table" — done 2 — surfaced 1 — decisions 1 — amb 2 (OQ-0007, ledger row 4)
        scope 5f21ac3/node-24-linux/REQ-001,REQ-004 — unverified 1 (XLSX path: no fixture)
 holds: 5 — 2 (worktree: build-csv-export, this run; container: pg-test, this run) — enumerated 8/8 classes
 holds: 10 — none — enumerated 7/8 classes, unlooked: containers (no docker on this host)
+finish: done — rounds 3/3 — releases 1/2
 ```
 
 The last two lines are a **trip**: the same file, two consecutive passes, the same