task-pipeline-skill 1.97.1 → 1.99.0

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

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""retro_budget.py: the byte budget of the retro's floor, measured and enforced.
+
+The floor is what stage 0 reads in full: the *Standing instructions* section and the
+*Run stamps* section of `<artifacts>/retro.md` (`references/retrospective.md` ->
+*The floor has a byte budget*). A cap of ten rows never bounded their SIZE: measured
+on 2026-10-20 across ~50 projects the floor ran from ~3k to ~76k tokens, one of them
+304 KB. This script is the bound.
+
+    retro_budget.py check   [--retro PATH] [--budget N] [--row N] [--stamp N]
+        prints one line: the floor's bytes, bytes/4 tokens, and the largest row of
+        each kind. Exit 0 within budget; 1 over budget (every offender listed);
+        2 could not measure (no file, or a floor section is missing).
+    retro_budget.py migrate [--retro PATH] [--archive PATH] [--write]
+        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
+        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.
+    retro_budget.py verify  [--retro PATH]
+        every `sha256:` pointer in the floor resolves to an archive block whose text
+        hashes to it. Exit 0, or 1 naming each pointer that does not.
+
+Standard library only, like every script this skill ships.
+"""
+import argparse
+import datetime
+import hashlib
+import os
+import re
+import sys
+
+BUDGET = 12000  # bytes of floor (standing instructions + run stamps)
+ROW = 600       # chars per standing-instruction row
+STAMP = 300     # chars per run-stamp row
+CAP = 10        # rows per table, the existing cap
+
+STANDING = "## Standing instructions"
+STAMPS = "## Run stamps"
+POINTER = re.compile(r"(retro/[0-9]{4}-Q[1-4]\.md) sha256:([0-9a-f]{12,64})")
+
+
+class Unmeasurable(Exception):
+    pass
+
+
+def sections(text):
+    """{name: (start, end)} line spans of the two floor sections, end exclusive."""
+    lines = text.split("\n")
+    spans = {}
+    for i, line in enumerate(lines):
+        for name in (STANDING, STAMPS):
+            if line.startswith(name) and name not in spans:
+                j = i + 1
+                while j < len(lines) and not (lines[j].startswith("## ")
+                                              or lines[j].startswith("# ")):
+                    j += 1
+                spans[name] = (i, j)
+    missing = [n for n in (STANDING, STAMPS) if n not in spans]
+    if missing:
+        raise Unmeasurable("no `%s` section, so the floor cannot be measured"
+                           % "` or `".join(missing))
+    return lines, spans
+
+
+def table_rows(lines, span):
+    """Indices of the data rows of every table inside a span (header and rule skipped)."""
+    out = []
+    start, end = span
+    i = start
+    while i < end:
+        if lines[i].startswith("|") and i + 1 < end and re.match(r"^\|\s*:?-{3}", lines[i + 1]):
+            i += 2
+            while i < end and lines[i].startswith("|"):
+                out.append(i)
+                i += 1
+            continue
+        i += 1
+    return out
+
+
+def cells(row):
+    parts = row.strip().split("|")
+    return [c.strip() for c in parts[1:-1]]
+
+
+def header_cols(lines, i):
+    """Column count of the table holding row i, read from its header (a `|` inside a
+    cell's text must not widen the row that replaces it)."""
+    k = i
+    while k > 0 and lines[k - 1].startswith("|"):
+        k -= 1
+    return len(cells(lines[k]))
+
+
+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])
+    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))
+    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]),
+        "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, "
+            "largest %d/%d · stamps %d/%d, largest %d/%d"
+            % (m["bytes"], m["tokens"], m["budget"], m["standing"], CAP, m["standing_max"], row,
+               m["stamps"], CAP, m["stamps_max"], stamp))
+
+
+def read(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return fh.read()
+    except OSError as exc:
+        raise Unmeasurable("cannot read %s (%s)" % (path, exc.strerror or exc))
+
+
+def default_archive(retro):
+    today = datetime.date.today()
+    q = (today.month - 1) // 3 + 1
+    return os.path.join(os.path.dirname(os.path.abspath(retro)), "retro",
+                        "%d-Q%d.md" % (today.year, q))
+
+
+def digest(text):
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def block(kind, label, text):
+    h = digest(text)
+    return h, ("\n### retro_budget migrate · %s · %s · %s\n\n<!-- sha256:%s -->\n%s\n"
+               % (datetime.date.today().isoformat(), kind, label, h, text))
+
+
+def cmd_check(a):
+    m = measure(read(a.retro), a.budget, a.row, a.stamp)
+    print(summary(m, a.row, a.stamp))
+    if m["over"]:
+        for o in m["over"]:
+            print("  over: " + o)
+        print("  remedy: retro_budget.py migrate --write moves the narrative to the archive "
+              "verbatim; an instruction still over the row limit is rewritten by hand")
+        return 1
+    return 0
+
+
+def cmd_migrate(a):
+    text = read(a.retro)
+    m = measure(text, a.budget, a.row, a.stamp)
+    lines = m["lines"]
+    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:
+            continue
+        c = cells(lines[i])
+        if len(c) < 3:
+            continue
+        h, b = block("stamp", "%s %s" % (c[0], c[2]), lines[i])
+        ptr = "moved: %s sha256:%s" % (rel, h[:12])
+        # the table keeps its column count: the pointer fills Verdict, `·` the rest
+        tail = ["·"] * max(0, header_cols(lines, i) - 4)
+
+        def row_of(topic):
+            return "| " + " | ".join([c[0], topic, c[2], ptr] + tail) + " |"
+
+        topic = c[1]
+        new = row_of(topic)
+        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:
+            continue
+        c = cells(lines[i])
+        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]))
+    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)))
+    if not a.write:
+        print("migrate: dry run, nothing written (pass --write)")
+        return 0
+    os.makedirs(os.path.dirname(os.path.abspath(archive)), exist_ok=True)
+    if not os.path.exists(archive):
+        with open(archive, "w", encoding="utf-8") as fh:
+            fh.write("# Retro archive · %s\n\n**Append-only. Queried, never read in full.** "
+                     "Blocks moved here by `retro_budget.py migrate` carry the sha256 of the "
+                     "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
+    tmp = a.retro + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines))
+    os.replace(tmp, a.retro)
+    after = measure(read(a.retro), a.budget, a.row, a.stamp)
+    print(summary(after, a.row, a.stamp))
+    bad = verify(a.retro)
+    if bad:
+        for b in bad:
+            print("  unproved: " + b)
+        return 1
+    for o in after["over"]:
+        print("  still over: " + o)
+    return 1 if after["over"] else 0
+
+
+def verify(retro):
+    text = read(retro)
+    lines, spans = sections(text)
+    floor = "\n".join(lines[spans[STANDING][0]:spans[STANDING][1]] +
+                      lines[spans[STAMPS][0]:spans[STAMPS][1]])
+    base = os.path.dirname(os.path.abspath(retro))
+    bad, cache = [], {}
+    for rel, short in POINTER.findall(floor):
+        path = os.path.join(base, rel)
+        if path not in cache:
+            try:
+                cache[path] = read(path)
+            except Unmeasurable:
+                cache[path] = None
+        arch = cache[path]
+        if arch is None:
+            bad.append("sha256:%s points at %s, which does not exist" % (short, rel))
+            continue
+        ok = False
+        for m in re.finditer(r"<!-- sha256:([0-9a-f]{64}) -->\n(.*?)\n(?=\n#{2,3} |\Z)", arch, re.S):
+            if m.group(1).startswith(short) and digest(m.group(2)) == m.group(1):
+                ok = True
+                break
+        if not ok:
+            bad.append("sha256:%s has no block in %s whose text hashes to it" % (short, rel))
+    return bad
+
+
+def cmd_verify(a):
+    bad = verify(a.retro)
+    for b in bad:
+        print("unproved: " + b)
+    if not bad:
+        print("verify: every archive pointer in the floor resolves and its hash matches")
+    return 1 if bad else 0
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    sub = p.add_subparsers(dest="cmd", required=True)
+    for name in ("check", "migrate", "verify"):
+        s = sub.add_parser(name)
+        s.add_argument("--retro", default="docs/evidence/retro.md")
+        s.add_argument("--budget", type=int, default=BUDGET)
+        s.add_argument("--row", type=int, default=ROW)
+        s.add_argument("--stamp", type=int, default=STAMP)
+        if name == "migrate":
+            s.add_argument("--archive")
+            s.add_argument("--write", action="store_true")
+    a = p.parse_args(argv)
+    try:
+        return {"check": cmd_check, "migrate": cmd_migrate, "verify": cmd_verify}[a.cmd](a)
+    except Unmeasurable as exc:
+        print("retro_budget: could not measure: %s" % exc, file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""short_path.py: stage 0's proportional decision, computed rather than proposed.
+
+`references/stage-00-intake.md` -> Phase 1d. Until 1.98.0 the short path was only
+*proposed*, and silence took the full flow; under a standing "decide and act"
+instruction silence is the normal answer, so a small fix met eleven stages every time.
+This script takes the five triage answers and DECIDES, printing the one line the run
+shows the operator.
+
+    short_path.py --files PATH [PATH ...] --contract yes|no --user-facing yes|no
+                  --deploy yes|no --risk R1|R2|R3 [--unknowns N]
+
+Exit 0: the short path (brief in the run ledger, build with tests, one verification,
+docs and handoff). Exit 3: the full flow, with every answer that ruled the short path
+out. Exit 2: usage. Standard library only.
+"""
+import argparse
+import sys
+
+MAX_FILES = 5
+SMALL_RISK = "R1"
+
+
+def decide(files, contract, user_facing, deploy, risk, unknowns=0):
+    """(short?, line) for the five answers plus the gap check's unknowns."""
+    n = len(set(files))
+    why = []
+    if unknowns:
+        why.append("%d material unknown(s) left by the gap check" % unknowns)
+    if n > MAX_FILES:
+        why.append("%d files, over %d" % (n, MAX_FILES))
+    if n == 0:
+        why.append("no file named, so the change is not bounded")
+    if contract:
+        why.append("a public contract is touched")
+    if user_facing:
+        why.append("a user-observable change")
+    if deploy:
+        why.append("a deploy target")
+    if risk != SMALL_RISK:
+        why.append("risk %s" % risk)
+    if why:
+        return False, "full flow: " + "; ".join(why)
+    return True, ("short path: %s · %d file%s · no contract · no user-facing change · "
+                  "no deploy" % (risk, n, "" if n == 1 else "s"))
+
+
+def yes_no(v):
+    v = v.strip().lower()
+    if v not in ("yes", "no"):
+        raise argparse.ArgumentTypeError("answer yes or no, not %r" % v)
+    return v == "yes"
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("--files", nargs="*", default=[], help="the paths the change touches")
+    p.add_argument("--contract", type=yes_no, required=True)
+    p.add_argument("--user-facing", type=yes_no, required=True)
+    p.add_argument("--deploy", type=yes_no, required=True)
+    p.add_argument("--risk", choices=("R1", "R2", "R3"), required=True)
+    p.add_argument("--unknowns", type=int, default=0)
+    a = p.parse_args(argv)
+    short, line = decide(a.files, a.contract, a.user_facing, a.deploy, a.risk, a.unknowns)
+    print(line)
+    return 0 if short else 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -32,12 +32,14 @@ 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]
         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
+        blocking <k>` lines, whose counts must match the inventory. Exit 0 done (the last
+        --clean-rounds rounds found no new blocking item: one by default, two when the
+        iteration carries an R3 or flagship node; 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
@@ -598,7 +600,7 @@ def ledger_rounds(path: pathlib.Path) -> dict[int, int]:
 
 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]:
+                   operator_go: bool = False, clean_rounds: int = 1) -> 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]
@@ -612,7 +614,9 @@ def finish_verdict(items: list[dict], rounds: int, max_rounds: int, max_releases
     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
+    # One clean round ends an iteration; two only where it carries an R3 or flagship node
+    # (`--clean-rounds 2`). Two for everything was the loop the 2026-10-20 cost audit measured.
+    clean = rounds >= clean_rounds and all(n == 0 for n in new[-clean_rounds:]) and not open_b
     green = checks is not None and checks[0] == checks[1]
     if clean and green:
         if rounds <= max_rounds:
@@ -625,7 +629,7 @@ def finish_verdict(items: list[dict], rounds: int, max_rounds: int, max_releases
     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")
+                "exit checks not all green" if not green else "a 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 "
@@ -640,7 +644,8 @@ def finish_verdict(items: list[dict], rounds: int, max_rounds: int, max_releases
     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")
+           ("a second round with no new blocking finding is owed" if clean_rounds > 1 else
+            "a round with no new blocking finding is owed"))
     return 3, "continue", dict(facts, why=why)
 
 
@@ -649,11 +654,14 @@ def cmd_finish(a) -> int:
         _, 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),
+    if a.clean_rounds not in (1, 2):
+        raise Fail(1, [f"--clean-rounds {a.clean_rounds} is not 1 or 2"])
+    for flag, v, least in (("--max-rounds", a.max_rounds, a.clean_rounds),
+                           ("--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"
+                f" — done needs {a.clean_rounds} clean rounds, so a smaller budget 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
@@ -684,7 +692,7 @@ def cmd_finish(a) -> int:
     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)
+                                   a.operator_go, a.clean_rounds)
     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")]
@@ -738,7 +746,11 @@ def main(argv: list[str]) -> int:
                    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-rounds", type=int, required=True,
+                   help="run.finish.maxRounds (default 3, at least --clean-rounds)")
+    f.add_argument("--clean-rounds", type=int, default=1,
+                   help="run.finish.cleanRounds: clean rounds that end the iteration, 1 by "
+                        "default, 2 when it carries an R3 or flagship node")
     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")

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

@@ -79,7 +79,7 @@ attached.
 Cut per `references/waves.md` → *Cutting the waves*: a wave holds only items closable in one
 pass; wave 1 is the walking skeleton; lanes run in parallel inside a wave and respect file
 ownership. Each node carries its own risk class (`references/iteration.md` → *Verification
-starts when a node lands*): R1 one passing round, R2 two, R3 three, one of them recorded adversarial.
+starts when a node lands*): R1 one passing round on one tier, R2 one, R3 two, one of them recorded adversarial.
 
 **Counts:** <from `waves.py count` and the graph: nodes by risk, by wave, out of waves>.
 

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

@@ -51,7 +51,7 @@
       "maximum": 3
     },
     "stages": {
-      "description": "The stage that owned the failure and the stage that surfaced it. A profile's stage ids need not be numbers.",
+      "description": "The stage that owned the failure and the stage that surfaced it. A profile's stage ids need not be numbers; a string id is one line of at most 32 characters, not blank, and gets the text fields' checks (no path, URL or credential shape). A longer or ill-shaped id an older index holds is normalised when read, never set aside.",
       "type": "object",
       "additionalProperties": false,
       "required": [
@@ -63,13 +63,19 @@
           "type": [
             "integer",
             "string"
-          ]
+          ],
+          "minLength": 1,
+          "maxLength": 32,
+          "pattern": "\\S"
         },
         "surfaced": {
           "type": [
             "integer",
             "string"
-          ]
+          ],
+          "minLength": 1,
+          "maxLength": 32,
+          "pattern": "\\S"
         }
       }
     },
@@ -96,7 +102,7 @@
       ],
       "properties": {
         "project": {
-          "description": "The project's pseudonymous key: `p-` and the first 12 hex digits of the repository's root commit. Never its name: a repository name can be a customer's or a product's (redaction rule 4). The shared store receives the same key, never a `project:<slug>` id.",
+          "description": "The project's pseudonymous key: `p-` and the first 12 hex digits of the repository's root commit: the first-parent root of its default branch (origin/HEAD, main, master or the branch init.defaultBranch names; without them the main worktree's HEAD), so every worktree and branch of one repository shares it. Never its name: a repository name can be a customer's or a product's (redaction rule 4). The shared store receives the same key, never a `project:<slug>` id.",
           "type": "string",
           "pattern": "^p-[0-9a-f]{12}$"
         },
@@ -116,7 +122,7 @@
   },
   "$defs": {
     "indexEntry": {
-      "description": "One line of the local index (lesson-index/1): one entry per classKey, a pure function of its origins, so a rebuild from the retros equals the incremental index byte for byte.",
+      "description": "One line of the local index (lesson-index/1): one entry per classKey, a pure function of its origins, so a complete rebuild of the same retros with nothing carried and no memory id recorded equals the incremental index byte for byte.",
       "type": "object",
       "additionalProperties": false,
       "required": [
@@ -169,13 +175,13 @@
         },
         "seen": {
           "type": "integer",
-          "minimum": 1,
-          "description": "How many origins hold the class."
+          "minimum": 0,
+          "description": "How many origins hold the class, counting re-derived and temporarily unavailable carried origins — not those carried as `checkout holds another project`."
         },
         "projects": {
           "type": "integer",
-          "minimum": 1,
-          "description": "How many distinct projects hold it."
+          "minimum": 0,
+          "description": "How many distinct projects hold it, counted like `seen`: an origin carried as `checkout holds another project` is kept but not counted."
         },
         "status": {
           "enum": [
@@ -207,7 +213,29 @@
               },
               "memory": {
                 "type": "string",
-                "pattern": "^mem:[^@\\s]+@[0-9]+$"
+                "pattern": "^mem:[^@\\s]+@[1-9][0-9]*$",
+                "description": "The shared store's id, `mem:<id>@<revision>` with the revision from 1. One id belongs to one (project, classKey): `record` refuses an id another project's or class's origin holds, and one the loader would refuse."
+              },
+              "carried": {
+                "enum": [
+                  "checkout not read",
+                  "checkout holds another project",
+                  "retro file not read",
+                  "no provenance",
+                  "commit does not resolve",
+                  "retro cites a commit that does not resolve",
+                  "lesson refused",
+                  "no checkout read holds it",
+                  "source not read"
+                ],
+                "description": "Set by `rebuild` on every previous origin it did not re-derive: a rebuild never removes or moves anything on its own, and `rebuild --prune-carried` (optionally `--prune-carried-reason`) is the only way an origin leaves the index. The origin keeps everything recorded on it, its memory id included. `checkout holds another project` — every checkout in the provenance now holds another project key AND the origin's own commit does not resolve there — is kept but not counted in seen/projects/status; every other reason is a temporary unavailability and is counted. `source not read` is the round-7 label, still accepted. Cleared when a checkout holding the origin reads it again."
+              },
+              "checkouts": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Provenance: the real top-level paths of the checkouts this origin was derived from; they decide only the carried reason, never a removal. Local to this machine's index; never emitted to a store, and not printed by `show`."
               },
               "lesson": {
                 "type": "object"

package/plugins/task-pipeline/skills/task-pipeline/templates/retro-archive.md

@@ -25,6 +25,8 @@ resolve — the documentation gate checks it.
   one, and it produces no fix)
 - **Fix:** grade 1 (mechanical) — … / grade 2 → `R-00N` / grade 3, expires in 2 runs
 - **The check:** … (what catches this the first time, from now on)
+- **Class:** one of the classes in `references/retrospective.md` · **Cost:** rounds,
+  burned tags, time
 - **Commit:** `<sha>` — the change that fixed it (a real short SHA, and it must
   resolve: the gate runs `git rev-parse --verify` over every one)
 - **Upstream?** … (a lesson true in any repository belongs in the skill's own
@@ -40,6 +42,13 @@ history attached**, which is what this section is for.
 |---|---|---|---|---|
 | <YYYY-MM-DD> | R-000 | … | became a check (`npm run lint:paths`) | `<sha>` |
 
+## Moved by `retro_budget.py migrate`
+
+Narrative the floor's byte budget moved out of `retro.md`: each block is the original
+text, verbatim, under a `<!-- sha256:… -->` line that hashes it, and the floor keeps a
+pointer (`retro/YYYY-QN.md sha256:<prefix>`). `retro_budget.py verify` proves every
+pointer. Blocks are appended at the end of this file.
+
 ## Run stamps
 
 Rotated out of `retro.md` when its live table passes ten. Append-only, whole rows —

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

@@ -13,6 +13,11 @@ not negotiable. The **Recent log** and the **archive**
 read end to end: nothing caps the log's length, and an uncapped section read in
 full is the volume that stops the ten binding rows being read.
 
+**The floor has a byte budget:** standing instructions plus run stamps under 12 000
+bytes, a standing row at most 600 characters (the story goes to the archive), a stamp
+one line of at most 300. `scripts/retro_budget.py check` measures it at stage 0 and at
+gate 10; `migrate --write` moves narrative to the archive verbatim, hash-proved.
+
 ## Standing instructions (max 10 — in force right now)
 
 Every row is a rule an agent must follow, that **no check can decide**. A rule a
@@ -49,6 +54,10 @@ stays short precisely so that reading it in full at stage 0 stays cheap.
 - **Fix:** grade 1 (mechanical) — … / grade 2 → `R-00N` / grade 3, expires in
   2 runs
 - **The check:** … (what catches this the first time, from now on)
+- **Class:** `exit-code` | `unwatched-check` | `release` | `collision` |
+  `destructive-undo` | `claim-by-say-so` | `stale-doc` | `wrong-copy` | `sibling` |
+  `truncated-output` | `shell-instrument` | `handback` | `loop` (recurrence is counted
+  by class) · **Cost:** … (rounds, burned tags, time)
 - **Lesson:** `<class-key>` — <the class, one sentence> · **When:** <trigger> · **Nouns:** <a>, <b>, <c>
   (optional, and on ONE line: write it only when the class would be true in another
   project — it makes the entry a lesson for `scripts/lessons.py add`, lesson/1. Without
@@ -74,7 +83,7 @@ this section is read in full at stage 0.
 | Date | Topic | Commit | Verdict | Retro |
 |---|---|---|---|---|
 | 2026-05-04 | `<topic>` | `<sha>` | 14/14 verified | 1 entry · 7 standing (was 9) · retired 3 · added 1 |
-| 2026-05-02 | `<topic>` | `<sha>` | 9/9 verified | no divergence · 9 standing · retired 0 |
+| 2026-05-02 | `<topic>` | `<sha>` | 9/9 verified | no divergence · 9 standing · prune: 0 retired |
 
 The `Commit` column is what turns a stamp from a date into a navigable point in
 history: `git show <sha>` is the run, and `git log <sha>..HEAD` is everything that