task-pipeline-skill 1.99.0 → 1.100.0

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

@@ -15,7 +15,9 @@ on 2026-10-20 across ~50 projects the floor ran from ~3k to ~76k tokens, one of
         moves narrative out of the floor VERBATIM into the archive, each block
         carrying the sha256 of the text it holds, and leaves a pointer in its place:
         a stamp row over the stamp limit keeps Date, Topic and Commit; a standing row
-        over the row limit loses its `Because` cell. Without --write it prints the
+        over the row limit loses its `Because` cell; a standing instruction written as
+        a numbered list item keeps its bold rule and its `*(Retire ...)*` trigger; the
+        oldest run stamps past the cap of ten rotate out whole. Without --write it prints the
         plan and writes nothing. Exit 0 when the floor is then within budget, 1 when a
         row is still over (an instruction too long to shorten by moving its story:
         rewrite it by hand), 2 could not measure.
@@ -95,41 +97,133 @@ def header_cols(lines, i):
     return len(cells(lines[k]))
 
 
+ITEM = re.compile(r"^(\d+)\.\s")
+BULLET = re.compile(r"^[-*]\s")
+DATE = re.compile(r"(\d{4}-\d{2}-\d{2})")
+
+
+def list_items(lines, span, marker=ITEM):
+    """(start, end) line spans of numbered list items inside a span, end exclusive.
+
+    An older retro writes its standing instructions as `N. **rule** ...` paragraphs, not
+    the template's table. An item runs until the next item, or the first non-indented,
+    non-blank line (a vacancy note, a heading's prose); trailing blank lines are not part
+    of it. Reading such a floor as zero rows was B-244 in sshlg-skills."""
+    out = []
+    start, end = span
+    i = start
+    while i < end:
+        if not marker.match(lines[i]):
+            i += 1
+            continue
+        j = i + 1
+        while j < end and not marker.match(lines[j]) and (
+                not lines[j].strip() or lines[j].startswith((" ", "\t"))
+                # a lazy continuation: unindented text directly under the item's last line,
+                # unless it opens something of its own (a list, a rule, a note, a table)
+                or (lines[j - 1].strip() and not lines[j].startswith(("|", "#", "*("))
+                    and not ITEM.match(lines[j]) and not BULLET.match(lines[j])
+                    and not re.match(r"^(?:[+]\s|>|\d+\)\s)", lines[j])
+                    and not re.match(r"^(?:-{3,}|\*{3,}|_{3,})\s*$", lines[j]))):
+            j += 1
+        k = j
+        while k > i + 1 and not lines[k - 1].strip():
+            k -= 1
+        out.append((i, k))
+        i = j
+    return out
+
+
+def stamp_date(lines, sp):
+    """The date a run stamp was written: a table row's Date cell, or the first date in a
+    list stamp's opening line. None when it has none (the stamp cannot be ordered)."""
+    if lines[sp[0]].startswith("|"):
+        c = cells(lines[sp[0]])
+        m = re.match(r"\s*(\d{4}-\d{2}-\d{2})", c[0]) if c else None
+    else:
+        m = DATE.search(lines[sp[0]])
+    return m.group(1) if m else None
+
+
+LEAD = re.compile(r"^(?:[-*]|\d+\.)\s+((?:\*\*.+?\*\*\s*)+)")
+ONLY_DATE = re.compile(r"^(?:\*\*\s*\(?\d{4}-\d{2}-\d{2}\)?\s*\*\*\s*)+$")
+RETIRE = re.compile(r"\*\((Retire.*?)\)\*")
+
+
+def lead_of(lines, sp):
+    """The item's leading bold spans, verbatim (`**(date)** **rule.**` keeps both), or None
+    when there are none or they hold only a date: the rule must survive in the floor."""
+    m = LEAD.match(" ".join(l.strip() for l in lines[sp[0]:sp[1]]))
+    if not m or ONLY_DATE.match(m.group(1).strip()):
+        return None
+    return m.group(1).strip()
+
+
+def loose_prose(lines, span, taken):
+    """Paragraphs of a section that are neither table lines nor list stamps: [(start, end)]."""
+    out, start, end = [], span[0] + 1, span[1]
+    i = start
+    while i < end:
+        if i in taken or not lines[i].strip() or lines[i].startswith("|"):
+            i += 1
+            continue
+        j = i
+        while j < end and j not in taken and lines[j].strip() and not lines[j].startswith("|"):
+            j += 1
+        # This script's own pointer notes are not prose: moving them again on the next
+        # run would make migrate rewrite an over-budget floor forever.
+        if not any(POINTER.search(l) for l in lines[i:j]):
+            out.append((i, j))
+        i = j
+    return out
+
+
 def measure(text, budget=BUDGET, row=ROW, stamp=STAMP):
     lines, spans = sections(text)
     floor = "\n".join(lines[spans[STANDING][0]:spans[STANDING][1]]) + "\n" + \
             "\n".join(lines[spans[STAMPS][0]:spans[STAMPS][1]])
     nbytes = len(floor.encode("utf-8"))
-    std = table_rows(lines, spans[STANDING])
-    stm = table_rows(lines, spans[STAMPS])
+    std = [(i, i + 1) for i in table_rows(lines, spans[STANDING])]
+    form = "table"
+    if not std:
+        std = list_items(lines, spans[STANDING])
+        form = "numbered list" if std else "table"
+    # A run stamp is a table row or, in an older retro, a `- **date — title** ...` item.
+    stm = [(i, i + 1) for i in table_rows(lines, spans[STAMPS])] + \
+        list_items(lines, spans[STAMPS], BULLET)
+    stm.sort()
+    width = lambda sp: len("\n".join(lines[sp[0]:sp[1]]))
     over = []
     if nbytes > budget:
         over.append("floor is %d bytes, over the budget of %d" % (nbytes, budget))
-    for i in std:
-        if len(lines[i]) > row:
-            over.append("standing row %s is %d chars, over %d"
-                        % ((cells(lines[i]) or ["?"])[0], len(lines[i]), row))
-    for i in stm:
-        if len(lines[i]) > stamp:
-            c = cells(lines[i])
-            over.append("stamp %s %s is %d chars, over %d"
-                        % (c[0] if c else "?", c[2] if len(c) > 2 else "", len(lines[i]), stamp))
+    for sp in std:
+        if width(sp) > row:
+            label = (cells(lines[sp[0]]) or ["?"])[0] if form == "table" \
+                else "#" + ITEM.match(lines[sp[0]]).group(1)
+            over.append("standing row %s is %d chars, over %d" % (label, width(sp), row))
+    for sp in stm:
+        if width(sp) > stamp:
+            c = cells(lines[sp[0]]) if lines[sp[0]].startswith("|") else []
+            label = "%s %s" % (c[0], c[2] if len(c) > 2 else "") if c \
+                else "%s (list)" % (stamp_date(lines, sp) or "undated")
+            over.append("stamp %s is %d chars, over %d" % (label.strip(), width(sp), stamp))
     if len(std) > CAP:
         over.append("%d standing rows, over the cap of %d" % (len(std), CAP))
     if len(stm) > CAP:
         over.append("%d run stamps, over the cap of %d" % (len(stm), CAP))
     return {
         "bytes": nbytes, "tokens": nbytes // 4, "budget": budget,
-        "standing": len(std), "standing_max": max([len(lines[i]) for i in std] or [0]),
-        "stamps": len(stm), "stamps_max": max([len(lines[i]) for i in stm] or [0]),
+        "standing": len(std), "standing_max": max([width(sp) for sp in std] or [0]), "form": form,
+        "stamps": len(stm), "stamps_max": max([width(sp) for sp in stm] or [0]),
         "over": over, "lines": lines, "spans": spans, "std": std, "stm": stm,
     }
 
 
 def summary(m, row=ROW, stamp=STAMP):
-    return ("retro floor: %d bytes · ~%d tokens (bytes/4) · budget %d · standing %d/%d rows, "
+    return ("retro floor: %d bytes · ~%d tokens (bytes/4) · budget %d · standing %d/%d rows%s, "
             "largest %d/%d · stamps %d/%d, largest %d/%d"
-            % (m["bytes"], m["tokens"], m["budget"], m["standing"], CAP, m["standing_max"], row,
+            % (m["bytes"], m["tokens"], m["budget"], m["standing"], CAP,
+               " (numbered list)" if m.get("form") == "numbered list" else "", m["standing_max"], row,
                m["stamps"], CAP, m["stamps_max"], stamp))
 
 
@@ -177,9 +271,92 @@ def cmd_migrate(a):
     archive = a.archive or default_archive(a.retro)
     rel = os.path.relpath(os.path.abspath(archive),
                           os.path.dirname(os.path.abspath(a.retro))).replace(os.sep, "/")
-    moved = []
-    for i in m["stm"]:
-        if len(lines[i]) <= a.stamp:
+    moved = []      # (first line, last line exclusive, replacement lines, block, label)
+    head = m["spans"][STAMPS][0]
+    notes = []      # pointer lines inserted under the Run stamps heading
+    rotated = set()
+    if len(m["stm"]) > CAP:
+        # The cap rotates the OLDEST stamps out whole (references/retrospective.md, *The
+        # stamp table is capped at ten*). Oldest is read from the date, never from the
+        # position: tables and lists are written both ways round.
+        # A same-day tie is broken by position, the way its own block is written: a list
+        # written newest-first and a table written oldest-first can sit side by side.
+        def block_of(sp):
+            if not lines[sp[0]].startswith("|"):
+                return "list"
+            k = sp[0]
+            while k > 0 and lines[k - 1].startswith("|"):
+                k -= 1
+            return k
+        blocks = {}
+        for n, sp in enumerate(m["stm"]):
+            blocks.setdefault(block_of(sp), []).append((n, stamp_date(lines, sp)))
+        newest_first, votes = {}, []
+        for key, seq in blocks.items():
+            ds = [d for _, d in seq]
+            down = sum(1 for x, y in zip(ds, ds[1:]) if x and y and x > y)
+            up = sum(1 for x, y in zip(ds, ds[1:]) if x and y and x < y)
+            newest_first[key] = None if down == up else down > up
+            if newest_first[key] is not None:
+                votes.append(newest_first[key])
+        # A block whose dates show no direction takes the section's; with no evidence
+        # anywhere, newest first, the template's order.
+        fallback = sum(votes) * 2 >= len(votes) if votes else True
+        for key in newest_first:
+            if newest_first[key] is None:
+                newest_first[key] = fallback
+        dated = [(stamp_date(lines, sp), -n if newest_first[block_of(sp)] else n, sp)
+                 for n, sp in enumerate(m["stm"])]
+        if any(d is None for d, _, _ in dated):
+            print("migrate: a run stamp carries no YYYY-MM-DD date; rotate the stamps by hand")
+        else:
+            rotated = set(sp for _, _, sp in sorted(dated)[:len(dated) - CAP])
+            # A rotated table row travels under its table's header, so the archive keeps
+            # a table and the header of a table emptied by the rotation is not lost.
+            parts, headed = [], set()
+            for sp in m["stm"]:
+                if sp not in rotated:
+                    continue
+                if lines[sp[0]].startswith("|"):
+                    k = sp[0]
+                    while k > 0 and lines[k - 1].startswith("|"):
+                        k -= 1
+                    if k not in headed:
+                        headed.add(k)
+                        parts.append("\n".join(lines[k:k + 2]))
+                parts.append("\n".join(lines[sp[0]:sp[1]]))
+            text = "\n".join(parts)
+            for k in headed:
+                j = k + 2
+                while j < len(lines) and lines[j].startswith("|"):
+                    j += 1
+                if all((r, r + 1) in rotated for r in range(k + 2, j)):
+                    moved.append((k, k + 2, [], None, None))   # archived above, with its rows
+            h, b = block("stamps", "%d oldest rotated" % len(rotated), text)
+            for sp in rotated:
+                moved.append((sp[0], sp[1], [], None, None))
+            notes.append(("Rotated out: %d oldest run stamps, verbatim in %s sha256:%s"
+                          % (len(rotated), rel, h[:12]), b, "%d oldest run stamps rotated" % len(rotated)))
+    for sp in m["stm"]:
+        i = sp[0]
+        if sp in rotated or len("\n".join(lines[sp[0]:sp[1]])) <= a.stamp:
+            continue
+        if not lines[i].startswith("|"):
+            # A list stamp keeps its bold title; the narrative moves.
+            item = "\n".join(lines[sp[0]:sp[1]])
+            title = lead_of(lines, sp)
+            if not title:
+                print("migrate: the %s stamp has no **bold** title to keep; shorten it by hand"
+                      % (stamp_date(lines, sp) or "undated"))
+                continue
+            h, b = block("stamp", stamp_date(lines, sp) or "undated", item)
+            ptr = " moved: %s sha256:%s" % (rel, h[:12])
+            t = title
+            if len("- %s%s" % (t, ptr)) > a.stamp:
+                inner = re.sub(r"\*\*", "", t)
+                t = "**%s…**" % inner[:max(8, a.stamp - len("- ****…") - len(ptr))].rstrip()
+            moved.append((sp[0], sp[1], ["- %s%s" % (t, ptr)], b,
+                          "stamp %s (list)" % (stamp_date(lines, sp) or "undated")))
             continue
         c = cells(lines[i])
         if len(c) < 3:
@@ -197,22 +374,69 @@ def cmd_migrate(a):
         if len(new) > a.stamp:
             keep = max(8, len(topic) - (len(new) - a.stamp) - 1)
             new = row_of(topic[:keep].rstrip() + "…")
-        moved.append((i, new, b, "stamp %s %s" % (c[0], c[2])))
-    for i in m["std"]:
-        if len(lines[i]) <= a.row:
+        moved.append((i, i + 1, [new], b, "stamp %s %s" % (c[0], c[2])))
+    if m["bytes"] > a.budget:
+        # Prune paragraphs between the stamps were a measured share of the floor
+        # (*A prune that retires nothing writes its count into the stamp row*): over
+        # budget, every loose paragraph of the Run stamps section moves, verbatim.
+        taken = set(k for s0, s1 in m["stm"] for k in range(s0, s1))
+        prose = loose_prose(lines, m["spans"][STAMPS], taken)
+        # verify ends an archive block at a blank line before a heading, so a paragraph
+        # holding a heading stays in the floor rather than moving unprovable.
+        held = [pp for pp in prose if any(re.match(r"^#{1,6} ", l) for l in lines[pp[0]:pp[1]])]
+        for p0, _ in held:
+            print("migrate: a heading inside Run stamps stays in the floor: %s" % lines[p0][:60])
+        prose = [pp for pp in prose if pp not in held]
+        if prose:
+            text = "\n\n".join("\n".join(lines[p0:p1]) for p0, p1 in prose)
+            h, b = block("stamps prose", "%d paragraphs" % len(prose), text)
+            for p0, p1 in prose:
+                moved.append((p0, p1, [], None, None))
+            notes.append(("Moved out: %d loose paragraphs, verbatim in %s sha256:%s"
+                          % (len(prose), rel, h[:12]), b, "%d prose paragraphs" % len(prose)))
+    if notes:
+        moved.append((head + 1, head + 1, sum([["", n] for n, _, _ in notes], []), None, None))
+        for n, b, label in notes:
+            moved.append((head + 1, head + 1, [], b, label))
+    for s0, s1 in m["std"]:
+        item = "\n".join(lines[s0:s1])
+        if len(item) <= a.row:
             continue
-        c = cells(lines[i])
+        # Already migrated and still too long: its story is gone, the rule itself is the
+        # length. Moving the pointer again would rewrite the floor on every run.
+        if POINTER.search(item):
+            continue
+        if m["form"] == "numbered list":
+            # Keep the rule (its bold lead) and its retire-when trigger; the story moves.
+            flat = " ".join(l.strip() for l in lines[s0:s1])
+            num = ITEM.match(lines[s0]).group(1)
+            lead = lead_of(lines, (s0, s1))
+            retire = RETIRE.findall(flat)
+            if not lead:
+                print("migrate: standing #%s opens with no **bold** rule (or only a date); "
+                      "rewrite it by hand" % num)
+                continue
+            h, b = block("standing", "#" + num, item)
+            new = "%s. %s%s story: %s sha256:%s" % (
+                num, lead, (" *(%s)*" % retire[-1]) if retire else "", rel, h[:12])
+            if not retire:
+                print("migrate: standing #%s carries no *(Retire ...)* trigger; add one by hand" % num)
+            moved.append((s0, s1, [new], b, "standing #%s story" % num))
+            continue
+        c = cells(lines[s0])
         if len(c) < 5:
             continue
         h, b = block("standing", c[0], c[4])
         c[4] = "story: %s sha256:%s" % (rel, h[:12])
-        moved.append((i, "| " + " | ".join(c) + " |", b, "standing %s Because" % c[0]))
+        moved.append((s0, s1, ["| " + " | ".join(c) + " |"], b, "standing %s Because" % c[0]))
     if not moved:
         print(summary(m, a.row, a.stamp))
         print("migrate: nothing to move")
         return 1 if m["over"] else 0
-    for i, new, _, label in moved:
-        print("migrate: %s -> %s (%d -> %d chars)" % (label, rel, len(lines[i]), len(new)))
+    for s0, s1, new, _, label in moved:
+        if label:
+            print("migrate: %s -> %s%s" % (label, rel, "" if s0 == s1 else " (%d -> %d chars)" % (
+                len("\n".join(lines[s0:s1])), len("\n".join(new)))))
     if not a.write:
         print("migrate: dry run, nothing written (pass --write)")
         return 0
@@ -224,10 +448,25 @@ def cmd_migrate(a):
                      "text they hold; the floor keeps a pointer to it.\n"
                      % os.path.basename(archive)[:-3])
     with open(archive, "a", encoding="utf-8") as fh:
-        for _, _, b, _ in moved:
-            fh.write(b)
-    for i, new, _, _ in moved:
-        lines[i] = new
+        for _, _, _, b, _ in moved:
+            if b:
+                fh.write(b)
+    # Rebuild from the bottom so earlier spans keep their indices.
+    for s0, s1, new, _, _ in sorted(moved, key=lambda x: (x[0], x[1]), reverse=True):
+        lines[s0:s1] = new
+    # Removed stamps leave their blank separators behind: within Run stamps, one blank
+    # line between blocks is enough. Only a run that removed something tidies, so a
+    # table retro that only had a row shortened keeps its bytes (1.99.0 behaviour).
+    removed = any(s0 != s1 and not new for s0, s1, new, _, _ in moved)
+    _, sp2 = sections("\n".join(lines))
+    a0, a1 = sp2[STAMPS]
+    seg = lines[a0:a1]
+    kept = []
+    for k, line in enumerate(seg):
+        if removed and not line.strip() and kept and not kept[-1].strip():
+            continue
+        kept.append(line)
+    lines[a0:a1] = kept
     tmp = a.retro + ".tmp"
     with open(tmp, "w", encoding="utf-8") as fh:
         fh.write("\n".join(lines))

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

@@ -32,7 +32,7 @@ reviewed; a table and a re-run can. This script is that re-run:
         (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]
-                    [--clean-rounds 1|2]
+                    [--clean-rounds 1|2] [--max-agents 2]
         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
@@ -47,7 +47,10 @@ reviewed; a table and a re-run can. This script is that re-run:
         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).
+        --max-rounds below 2, an artefact that is not NAME@SHA). Since 1.100.0 the ledger's
+        `agents: <N> — <k>` lines (the most sub-agents running at once in round N) are read
+        too: a round over --max-agents (run.finish.maxAgents, 2 by default) is a budget
+        verdict, exit 5, unless --operator-go.
 
 **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
@@ -559,6 +562,7 @@ def cmd_sync_graph(a) -> int:
 # 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*$")
+AGENTS_LINE = re.compile(r"^agents:\s*(\d+)\s*[—-]\s*(\d+)\b")
 ARTEFACT = re.compile(r"^[^@\s]+@[0-9a-f]{7,40}$")
 
 
@@ -598,6 +602,27 @@ def ledger_rounds(path: pathlib.Path) -> dict[int, int]:
     return out
 
 
+def ledger_agents(path: pathlib.Path) -> dict[int, int]:
+    """{round: most sub-agents at once} from the run ledger's `agents:` lines (since 1.100.0).
+    A round written twice keeps its larger count: the budget is about the peak."""
+    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("agents:"):
+            continue
+        m = AGENTS_LINE.match(line.strip())
+        if not m:
+            errs.append(f"{path}:{n}: not `agents: <N> — <k>`")
+            continue
+        out[int(m[1])] = max(out.get(int(m[1]), 0), int(m[2]))
+    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, clean_rounds: int = 1) -> tuple[int, str, dict]:
@@ -693,12 +718,31 @@ def cmd_finish(a) -> int:
         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, a.clean_rounds)
+    # The parallel-agent budget (run.finish.maxAgents): a round that ran more sub-agents at
+    # once than the budget allows stops the iteration like any other budget, said with the
+    # numbers; the operator's go lifts it, out loud.
+    agents = ledger_agents(pathlib.Path(a.ledger)) if a.ledger else {}
+    if a.max_agents < 1:
+        raise Fail(1, [f"--max-agents {a.max_agents} is below 1"])
+    stray = sorted(r for r in agents if r < 1 or r > rounds)
+    if stray:
+        raise Fail(1, [f"{a.ledger}: an `agents:` line names round {r}, and only rounds 1..{rounds} ran"
+                       for r in stray])
+    over = sorted((r, k) for r, k in agents.items() if k > a.max_agents)
+    named = ", ".join(f"round {r}: {k}/{a.max_agents}" for r, k in over)
+    if over and not a.operator_go and code in (0, 3):
+        code, word = 5, "budget"
+        f = dict(f, why="agents over budget — " + named)
+    elif over and a.operator_go and code in (0, 3):
+        f = dict(f, why=((f.get("why") + "; ") if f.get("why") else "") + "agents over budget on the operator's go — " + named)
     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}"
+    peak = max(agents.values()) if agents else None
+    budget = (f"rounds {f['rounds']}/{a.max_rounds} — releases {a.releases}/{a.max_releases} — agents "
+              + (f"{peak}/{a.max_agents}" if peak is not None else f"unrecorded/{a.max_agents}"))
     if word == "continue":
         print(f"next round: {f['rounds'] + 1}/{a.max_rounds} — {f['why']} — {budget}")
     else:
@@ -756,8 +800,11 @@ def main(argv: list[str]) -> int:
     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")
+                   help="the operator's recorded go for rounds past --max-rounds and sub-agents past "
+                        "--max-agents; the block says which budget it lifted")
     f.add_argument("--checks", help="K/M — exit checks green on the artefact")
+    f.add_argument("--max-agents", type=int, default=2,
+                   help="run.finish.maxAgents: sub-agents running at once in one round (default 2)")
     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,

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 53 reference files and nothing recorded which of them a run read, so **a
+The bundle is 54 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 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 |
+| `N of 54 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
@@ -73,7 +73,8 @@ 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>
+agents: <N> — <most sub-agents running at once in round N>
+finish: done|budget|blocked — rounds <n>/<max> — releases <n>/<max> — agents <n>/<max>
 read:  references/<file>.md            # hook-appended, deduped, UNATTESTED (no writer field)
 ```
 
@@ -161,6 +162,7 @@ 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
+agents: 1 — 2
 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
@@ -169,7 +171,7 @@ hand:  3 — task "add CSV export to the orders table" — done 2 — surfaced 1
        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
+finish: done — rounds 3/3 — releases 1/2 — agents 2/2
 ```
 
 The last two lines are a **trip**: the same file, two consecutive passes, the same