task-pipeline-skill 1.88.1 → 1.90.0

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

@@ -187,10 +187,28 @@ never that the work was skipped quietly.
 - **UI early-detect:** one branch of the grill is always "does this touch a
   user-facing surface (web/mobile/CLI/TUI)?". If yes → surface **super-ux**
   now (use it if installed; otherwise give the install line — see SKILL.md
-  *Prerequisites*); this arms the stage-3 UX track.
+  *Prerequisites*); this arms the stage-3 UX track. **And the same branch records
+  the surface's class** — the next bullet.
+- **The surface class.** Every user-facing task's brief carries
+  `surface_class: flagship | product | internal | ad`, and the class selects the gate
+  profile the visual layer is held to for the rest of the run:
+
+  | Class | What it is | Director record (stage 3) | Visual half (stages 5–6) | Stage 10 |
+  |---|---|---|---|---|
+  | `flagship` | the surface a product is judged by — landing, onboarding, paywall, a hero screen | the full record | **gate**: full matrix, pairwise across every axis, the full rubric | approved contact sheet |
+  | `product` | an ordinary screen of the product | the short record — Brief, Mode, References, Markers, Open | **gate**: every state and the mandatory pairs; the gate items of the rubric | approved contact sheet |
+  | `internal` | an admin panel, an internal tool, a CLI | none owed | recommended; the project linter is the floor | the functional look |
+  | `ad` | a creative that runs as an advertisement or a store asset | Brief, Mode, References, Markers, ADA (its rubric profile and safe zones), Open | **gate**: the ad profile and the safe zones | approved contact sheet |
+
+  Ask it as one question with a recommended answer read off the request — a landing or a
+  paywall is `flagship` unless the operator says otherwise — and never leave it to stage
+  5: a class decided at build time is decided by whoever wants the build to pass. A
+  work-graph node that builds the surface copies the class as `surface_class`, and
+  `graph.py certify` then owes the fourth, `visual` reading on `flagship` and `product`
+  ([`certification.md`](certification.md) → *The fourth reading*).
 - **Artifact:** lock the resolved decisions into a **task brief** committed at
-  `<artifacts>/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict,
-  constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
+  `<artifacts>/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict and,
+  for a user-facing task, `surface_class`, constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
   autonomy sweep's per-stage answers and the model decision**. Seed it from
   the skill's `templates/brief.md` skeleton — but only when absent, never
   overwrite an existing brief. Stages 2–4 build on this brief; stages 5–10 read
@@ -214,7 +232,8 @@ never that the work was skipped quietly.
   a recorded answer or an explicit deferral, **every answer that contradicted a
   harvested source has a recorded resolution** (which governs, and whether the doc
   is now stale), no open contradictions, **every
-  autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
+  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
   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
@@ -314,8 +333,9 @@ never that the work was skipped quietly.
   ssheleg/super-ux`). super-ux builds a traced chain — walk it top-down (see its
   `system-map.md`):
   0. **Destination first, when Figma is on.** The brief already names the team/org
-     and the file; `docs/ux/foundation.md` → *Design tooling* is the canonical
-     record. Confirm it **resolves** before drawing. **Never create a file while a
+     and the files — **one per surface** (App, Web, ASO: store screenshots, icon and
+     logo), never one file for every frame; `docs/ux/foundation.md` → *Design tooling*
+     is the canonical record. Confirm each **resolves** before drawing. **Never create a file while a
      recorded one resolves; if it doesn't resolve, stop and ask — never create a
      replacement** (that is the duplicate, and it hides a permissions problem).
      A creation happens at most once, in the named team, and its URL is written to
@@ -350,7 +370,10 @@ never that the work was skipped quietly.
   disagree together on one screen. The full doctrine — each track's scope and
   out-of-scope, the refusal sentences, the four contradictions the check
   catches — is [`spec.md`](spec.md) → *The COPY and VISUAL tracks, and their
-  convergence*, its one home.
+  convergence*, its one home. **The VISUAL track leaves a trace, not a fact**: a
+  director record at `docs/design/<surface>/director-record.md`, whose fields the gate
+  reads by the brief's `surface_class` (`python3 scripts/visual_gate.py record <file>
+  --class <c>`), and a refusal is that same file saying `Mode: declined` and why.
 - **Spec:** write the approved design to
   `<artifacts>/specs/YYYY-MM-DD-<topic>-design.md` and commit it. Lock all
   shared contracts (types, schemas, signatures, file layout). For UI tasks the
@@ -367,12 +390,23 @@ never that the work was skipped quietly.
   designed, validated and approved; scenarios validated in `docs/ux/scenarios.md`;
   the linter passes; every user-facing spec requirement traces to a scenario ID
   (or an explicit v1-mode/tiny-project waiver by the operator). **With Figma on:
-  the canonical record names one file, and every `screens.md` frame link carries
-  that same `:fileKey`** — a string match, not a judgement; a differing key means
-  the run drew in a second file nobody will open. **Every user-facing string went
+  the canonical record names one file per surface (App, Web, ASO), and every
+  `screens.md` frame link's `:fileKey` is one of them** — a string match, not a
+  judgement (`python3 scripts/visual_gate.py filekeys --record docs/ux/foundation.md
+  --screens docs/ux/screens.md`); a key outside the set means the run drew in a file
+  nobody recorded and nobody will open. **Every user-facing string went
   through the COPY track or the refusal is recorded**, and **the visual layer went
   through the VISUAL track or the refusal is recorded** — a recorded refusal passes
   this gate and an unmentioned one does not, which is the only difference that matters.
+  **And the VISUAL track is checked by its trace, not by the fact that it ran:** on a
+  `flagship`, `product` or `ad` surface the director record exists and carries the
+  fields its class owes — `python3 scripts/visual_gate.py record
+  docs/design/<surface>/director-record.md --class <surface_class>` exits 0. That
+  command checks the headings itself and runs the record's own validator from `sheleg-design`
+  (`--check-record`) where it is installed and new enough; where it is not, the
+  validator reads **NOT_RUN** beside the verdict — never PASS — and the gate stands on
+  the floor, said so. A record saying `Mode: declined` with its reason is the refusal,
+  and it passes.
   **Where both tracks ran, their convergence check is recorded** — findings with the
   ruling, or `Tracks converge: clean`; a screen where each track is right alone and they
   disagree together is the defect neither track's own review can see.
@@ -435,7 +469,18 @@ never that the work was skipped quietly.
   requires — never parked silently** — a browser finding filed without a ruling is the
   diff-review verdict wearing a screenshot; the look was worth taking only if it can
   still change the code or is on record as deliberately not doing so. Absent, say the surface was verified by reading
-  the diff and treat it as the weaker claim it is. Stage 6 repeats this over the whole tree; this one catches it while the
+  the diff and treat it as the weaker claim it is. **On a surface whose brief names a
+  `surface_class`, the project linter runs here too**, after each task that changes a
+  rendered surface — `python3 scripts/visual_gate.py lint <dir>`; an S1 finding is
+  fixed in the task, and NOT_RUN (exit 3) is recorded as such
+  ([`browser.md`](browser.md) → *The visual half*). **With Figma on, the token drift
+  probe runs beside it** after a task that touches the token file or a tokenised
+  component: `python3 scripts/visual_gate.py tokens --figma <variables.json> --css
+  <tokens.css>`. A FAIL is fixed in the task, renaming one side to match the other.
+  No export is NOT_RUN, recorded as such. A component whose API the task changed
+  updates its Code Connect mapping in the same change
+  ([`build.md`](build.md) → *Code Connect, kept*). A slop marker caught while the
+  implementer is dispatched costs a line; caught on the contact sheet it costs a round. Stage 6 repeats this over the whole tree; this one catches it while the
   implementer that wrote it is still dispatched. The matrix pointed this companion at
   stages 5–6 from the day it was added and **this stage had never named it** — found by
   the guard comparing the two, not by a reader.
@@ -472,7 +517,10 @@ never that the work was skipped quietly.
   printed beside their floors; the **full** suite is green (not just the new tests); new/changed code
   is covered; **every check this run added or widened has been probed both ways —
   seen rejecting a planted defect and passing the clean tree, asserted on its exit
-  code** ([`probing.md`](probing.md)); no `skip`/`xfail` smuggling a red suite past the gate. Never advance
+  code** ([`probing.md`](probing.md)); no `skip`/`xfail` smuggling a red suite past the gate; **on a
+  `flagship`, `product` or `ad` surface where the VISUAL track ran, the visual half's
+  `visual_gate.py sheet` exits 0** — NOT_RUN stops and asks, it is not green
+  ([`browser.md`](browser.md) → *The visual half*). Never advance
   to deploy on a red or partial run. **The carry-over count is printed beside this
   verdict** — a ratchet nobody prints is a TODO with a better name
   ([`audit.md`](audit.md)) — **and so are the disclosures**, `abstained` and
@@ -502,6 +550,21 @@ never that the work was skipped quietly.
   run that answers *the surface was checked* by pointing at its spec suite has answered
   a different question. Where the suite is the thing that changed, the look is what
   proves it runs against a page that renders.
+- **The visual half is a separate check, and on most user-facing classes a gate.** The
+  look above reads the accessibility tree; it cannot say whether the surface looks like
+  what was designed. Where the stage-3 VISUAL track ran on a `flagship`, `product` or
+  `ad` surface, stage 6 also owes **the contact sheet** — frames over the `SCR-NN` states
+  × viewport × theme × text × locale (pairwise, plus the mandatory pairs), each with its
+  capture record, diffed against its Figma frame or approved baseline, the project
+  linter run, the token drift probe run over the whole token file where Figma is on
+  (`visual_gate.py tokens`; NOT_RUN without an export, never PASS), and the rubric
+  read by a judge that is not the builder — and its command
+  exits 0: `python3 scripts/visual_gate.py sheet <contact-sheet.json> --class
+  <surface_class> --artifact-root <frames>` (NOT_RUN, exit 3, is not green). On
+  `internal` it is recommended and the linter is the floor. The re-render budget is
+  **one, two at most**, then `unresolved` to the person — never round three — and only
+  external, specific feedback starts a round. The procedure and the order of the checks:
+  [`browser.md`](browser.md) → *The visual half*.
 - **What the look finds is fixed here.** A rendering defect found at stage 6 is a
   stage-6 finding: fix it, look again, then call the stage green. Filing it to the
   board and advancing is how a run reports *checked in a browser* for a page it has
@@ -672,7 +735,14 @@ never that the work was skipped quietly.
   surface**: read it against the spec section that covers its `SCR-` id and against
   what shipped. The super-ux linter proves a frame link exists, is named right and
   is not stale — it cannot read the picture, so a frame promising a limit, a meter
-  or a tier nobody built passes every lint there is. An absence
+  or a tier nobody built passes every lint there is. **Where the VISUAL track ran, the
+  walk carries one more row: visual intent ↔ final render** — the director record (the
+  brief's falsifier, the signature moment, the rubric written before any render) read
+  against the **approved contact sheet**. On a `flagship`, `product` or `ad` surface the
+  sheet is approved (`visual_gate.py sheet … --require-approval` exits 0), and the last
+  `review:` line per surface — how many human rounds it took — is copied into the
+  acceptance file, because `.task-pipeline/run.md` does not outlive the run
+  ([`audit.md`](audit.md) → the `V→R` seam). An absence
   becomes a **new REQ row with its check** and *then* the table is written;
   appending after the table is how acceptance goes green over a gap. Findings that
   belong to a lower layer go back to that layer (spec → stage 3, plan → stage 4).

package/plugins/task-pipeline/skills/task-pipeline/references/work-graph.md

@@ -59,7 +59,7 @@ conditional on the code, never merely sequenced after it.**
 | `goal` | the release goal | `0` · `3` unstated |
 | `add` | the id it allocated | `0` · `1` refused |
 | `park` | the id and the reason | `0` · `1` refused |
-| `certify` | the round, and on a failure every `breaks` finding with its fix and its check | `0` all three tiers passed · `1` a tier failed, or a report is malformed |
+| `certify` | the round, and on a failure every `breaks` finding with its fix and its check | `0` every owed tier passed — three, or four with `visual` on a flagship or product node · `1` a tier failed, a required one is missing, or a report is malformed |
 | `close` | the goal, the new frontier count, and what was not verified | `0` · `1` refused **or the verdict stops the run** |
 | `producer` | what produced this proof — actor, model, runtime, skill, config, commit, trace | `0` |
 | `doctrine` | how many of the bundle's reference files this run opened | `0` |
@@ -84,7 +84,7 @@ A **`parked`** node is the single exemption: it is the one node nobody will clos
 *n/a — parked* in that field is confidence without correctness. `park` never removes what
 the node said it would run.
 
-**A node is closed by three readings, not one.** `certify` takes one tier report from each of `unit`, `seam` and `product` — dispatched blind and in parallel — requires all three to pass, and assembles the seven-key verdict `close` consumes. `close`'s contract is unchanged; what changed is that the verdict is now built from three readings at different distances instead of written from one, because a change can be correct where it was made and wrong one level out. A failing round records itself and leaves the node open. Doctrine: [`certification.md`](certification.md).
+**A node is closed by three readings, not one.** `certify` takes one tier report from each of `unit`, `seam` and `product` — dispatched blind and in parallel — requires all three to pass, and assembles the seven-key verdict `close` consumes. `close`'s contract is unchanged; what changed is that the verdict is now built from three readings at different distances instead of written from one, because a change can be correct where it was made and wrong one level out. A failing round records itself and leaves the node open. **A node whose `surface_class` is `flagship` or `product` owes a fourth, `visual` report** — the contact sheet read against the director record — and `certify` refuses the round without it; on any other node a `visual` report is accepted when given. Doctrine: [`certification.md`](certification.md).
 
 **`close` stamps the commit; the verifier never supplies it.** A verdict written after the
 tree moved is evidence about a different tree, and an agent cannot name the wrong commit if

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

@@ -268,6 +268,14 @@ def violations(graph):
                            "two commands cannot say which one closed the node, and the "
                            "verifier reports its output as one evidence row")
 
+        # The surface class (stage 0, `references/stages.md`) decides whether `certify`
+        # owes the fourth, `visual` reading. A class outside the four would silently
+        # require nothing, which is the one outcome a typo must not have.
+        if "surface_class" in n and n["surface_class"] not in SURFACE_CLASSES:
+            out.append(f"{nid}: surface_class is {n['surface_class']!r} — it must be one of "
+                       f"{', '.join(SURFACE_CLASSES)}. A class nobody recognises requires no "
+                       "visual reading, so a typo here would drop the tier that reads the pixels")
+
         if n.get("status") == "done":
             ev = n.get("evidence")
             if not isinstance(ev, list) or not [e for e in ev
@@ -574,6 +582,9 @@ def verdict_violations(v):
 #            tests of the neighbours the change can reach
 #   product  one level out again — the documentation, the scenarios, how this
 #            behaviour interacts with the rest of the product
+#   visual   the pixels — the contact sheet, the director record, the project
+#            linter and the rubric. Owed only where the node's `surface_class` is
+#            flagship or product; accepted, and counted, wherever it is given
 #
 # **All three must pass, and blind is the point.** Three agents that read each
 # other's reports are one opinion with three signatures; the disagreement is the
@@ -584,6 +595,15 @@ def verdict_violations(v):
 # stamp at three levels is worse than one verifier, because it costs three times
 # as much and reads as three times the assurance.
 TIERS = ("unit", "seam", "product")
+# The fourth reading, `visual`, reads the PIXELS — the contact sheet, the director
+# record, the project linter's output and the rubric — which none of the three opens.
+# It is owed by a node whose `surface_class` is one of VISUAL_REQUIRED, accepted when
+# given on any other node, and blind to the other three exactly as they are to each
+# other. `references/certification.md` → *The fourth reading*.
+VISUAL_TIER = "visual"
+ALL_TIERS = TIERS + (VISUAL_TIER,)
+SURFACE_CLASSES = ("flagship", "product", "internal", "ad")
+VISUAL_REQUIRED = ("flagship", "product")
 TIER_KEYS = ("node", "tier", "verdict", "scope", "confirms", "findings",
              "evidence", "not_examined")
 TIER_VERDICTS = ("pass", "fail")
@@ -596,10 +616,10 @@ SEVERITIES = ("breaks", "risk")
 # "the unit tier's verdict…"). Widened to the tense and possessive forms the
 # reader planted; still a closed list on purpose — a looser net here starts
 # matching a report's honest prose about its OWN tier.
-CROSS_TIER = re.compile(r"\b(?:unit|seam|product)\s+tier(?:'s)?\s+"
+CROSS_TIER = re.compile(r"\b(?:unit|seam|product|visual)\s+tier(?:'s)?\s+"
                         r"(?:passed|failed|says|said|confirm\w*|verdict|report)"
                         r"|\btier\s+\d\s+(?:passed|failed|says|said|confirm\w*)"
-                        r"|as\s+the\s+(?:unit|seam|product)\s+tier", re.I)
+                        r"|as\s+the\s+(?:unit|seam|product|visual)\s+tier", re.I)
 
 
 def tier_violations(t):
@@ -622,9 +642,9 @@ def tier_violations(t):
 
     if not isinstance(t["node"], str) or not t["node"].startswith(NODE_ID):
         out.append("tier report `node` is %r, which is not a node id" % (t["node"],))
-    if t["tier"] not in TIERS:
+    if t["tier"] not in ALL_TIERS:
         out.append("tier report `tier` is %r — it must be one of %s"
-                   % (t["tier"], ", ".join(TIERS)))
+                   % (t["tier"], ", ".join(ALL_TIERS)))
     if t["verdict"] not in TIER_VERDICTS:
         out.append("tier report `verdict` is %r — it must be `pass` or `fail`, because "
                    "a certification that admits a third state admits a maybe"
@@ -1482,6 +1502,14 @@ def cmd_certify(graph, args):
         die("certification is missing the %s report(s) — all three are required, because "
             "the level nobody read is the level the defect survives at"
             % ", ".join("`%s`" % m for m in missing))
+    sclass = node.get("surface_class")
+    if sclass in VISUAL_REQUIRED and VISUAL_TIER not in reports:
+        die("certification is missing the `%s` report — %s is a %s surface, and on one the "
+            "pixels are part of the requirement: none of unit, seam or product opens the "
+            "contact sheet, so without the fourth reading nobody looked at what a user sees "
+            "(references/certification.md → *The fourth reading*)" % (VISUAL_TIER, nid, sclass))
+    # The tiers THIS round read, in a stable order: the three always, `visual` when given.
+    tiers = [x for x in ALL_TIERS if x in reports]
 
     # The stamp, read here and never accepted from a report — same law as `close`.
     import subprocess
@@ -1493,7 +1521,7 @@ def cmd_certify(graph, args):
 
     prior = node.get("certification") or {}
     round_no = int(prior.get("round") or 0) + 1
-    tiers_now = {x: reports[x]["verdict"] for x in TIERS}
+    tiers_now = {x: reports[x]["verdict"] for x in tiers}
     history = list(prior.get("history") or []) + [tiers_now]
     node["certification"] = {
         "round": round_no,
@@ -1502,11 +1530,11 @@ def cmd_certify(graph, args):
         "history": history,
     }
 
-    failed = [x for x in TIERS if tiers_now[x] == "fail"]
+    failed = [x for x in tiers if tiers_now[x] == "fail"]
 
     # Churn, measured. A tier that has failed in every round so far is the one the
     # operator needs named; counting it here is what makes the loop visible.
-    churning = [x for x in TIERS
+    churning = [x for x in tiers
                 if len(history) >= 2 and all(h.get(x) == "fail" for h in history)]
 
     save(args.graph, graph)
@@ -1545,19 +1573,19 @@ def cmd_certify(graph, args):
     #                                   exactly what `can_continue_around: true` says)
     verdict = {
         "node": nid,
-        "done": [c for x in TIERS for c in reports[x]["confirms"]],
+        "done": [c for x in tiers for c in reports[x]["confirms"]],
         "not_done": [],
         "not_verified": ["%s: %s" % (x, n)
-                         for x in TIERS for n in reports[x]["not_examined"]],
+                         for x in tiers for n in reports[x]["not_examined"]],
         "blockers": [
             {"what": "%s (%s, found by the `%s` tier)" % (f["what"], f["where"], x),
              "blocks": [], "can_continue_around": True}
-            for x in TIERS for f in reports[x]["findings"]
+            for x in tiers for f in reports[x]["findings"]
             if f.get("severity") == "risk"
         ],
         "replan": {"possible": True, "add": [], "park": [],
-                   "why": "certified at all three tiers in round %d" % round_no},
-        "evidence": ["%s: %s" % (x, e) for x in TIERS for e in reports[x]["evidence"]],
+                   "why": "certified at all %d tiers in round %d" % (len(tiers), round_no)},
+        "evidence": ["%s: %s" % (x, e) for x in tiers for e in reports[x]["evidence"]],
     }
     # Proof identity (FIX-PF-02.01): the certification tested THIS tree, so it
     # records the commit it tested into the verdict it hands `close`. Without it
@@ -1579,7 +1607,7 @@ def cmd_certify(graph, args):
     # cannot hand the run a verdict its own consumer refuses.
     broken = verdict_violations(verdict)
     if broken:
-        die("all three tiers passed and the assembled verdict is still malformed — this "
+        die("every tier passed and the assembled verdict is still malformed — this "
             "is a defect in `certify`, not in the reports:\n  " + "\n  ".join(broken))
 
     out = args.verdict_out or os.path.join(os.path.dirname(args.graph) or ".",
@@ -1589,7 +1617,7 @@ def cmd_certify(graph, args):
         json.dump(verdict, fh, indent=2, ensure_ascii=False)
         fh.write("\n")
     os.replace(tmp, out)
-    print("%s: certified at unit, seam and product in round %d" % (nid, round_no))
+    print("%s: certified at %s in round %d" % (nid, ", ".join(tiers), round_no))
     print("verdict written to %s — close it with:" % out)
     print("  graph.py close --verdict %s" % out)
     return 0
@@ -1797,8 +1825,9 @@ VERBS = {
     "coverage": (cmd_coverage, "every requirement and the nodes serving it; exits 1 on a gap"),
     "add": (cmd_add, "add a node mid-run"),
     "park": (cmd_park, "park a node, carrying the reason"),
-    "certify": (cmd_certify, "require three independent tier reports, then emit "
-                             "the verdict `close` consumes"),
+    "certify": (cmd_certify, "require three independent tier reports (four on a "
+                             "flagship or product surface), then emit the verdict "
+                             "`close` consumes"),
     "close": (cmd_close, "consume a verdict, close one node and re-plan"),
 }
 

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

@@ -37,6 +37,9 @@ What it keeps, and where:
   the episode Observatory kept (`keptAs`), the token is dropped, and the run is told to read
   the workflow before writing again. A stale writer therefore stops after one refusal.
 
+Ledger lines it reads besides `stage:`: `review:` (the contact sheet's human rounds, stage 6
+and 10 on a visual surface), each carried as evidence on the stage it names.
+
 Ledger lines it appends, all of the existing `event:` shape:
 
     event: memory — checkpoint <stepId> rev <n> <workflowId> — <ISO-8601>
@@ -63,6 +66,10 @@ STATE_NAME = "memory.json"
 OWNER = "agent:task-pipeline"
 STAGE = re.compile(r"^stage:\s*(\d+)\s+(.+?)\s+—\s+gate\s+(\S+)\s+—\s+verdict\s+(\S+)\s+—\s+(\S+)\s*$")
 TOPIC = re.compile(r"^Run:\s*`([^`]+)`")
+# The contact sheet's human rounds (`references/browser.md` → *The visual half*): one line per
+# return or approval. Carried into the checkpoint of the stage it names, so the number of
+# passes a surface took is measured at the boundary rather than remembered at the end.
+REVIEW = re.compile(r"^review:\s*(\d+)\s+—\s+surface\s+(.+?)\s+—\s+rounds\s+(\d+)\s+—\s+(\S+)\s+—\s+\S+\s*$")
 STATUS = {"pass": "done", "skip": "done", "fail": "blocked"}
 
 
@@ -81,6 +88,17 @@ def _now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+def _reviews(path: pathlib.Path) -> dict[int, list[str]]:
+    """`review:` lines by the stage id they name, as evidence strings."""
+    out: dict[int, list[str]] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        m = REVIEW.match(line)
+        if m:
+            out.setdefault(int(m.group(1)), []).append(
+                f"review: {m.group(2)} rounds {m.group(3)} {m.group(4)}")
+    return out
+
+
 def _read_ledger(path: pathlib.Path) -> tuple[str, list[tuple]]:
     try:
         text = path.read_text(encoding="utf-8")
@@ -160,8 +178,10 @@ def emit(ledger: pathlib.Path, project: str | None, constraints: list[str],
     # one thing a successor must never act without (found by the live receipt, 2026-10-05).
     constraints = list(dict.fromkeys([*state.get("constraints", []), *constraints]))
     credentials = list(dict.fromkeys([*state.get("credentials", []), *credentials]))
+    reviews = _reviews(ledger)
     done = [{"step_id": f"stage-{s[0]}", "result": f"{s[1]}: gate {s[2]}, verdict {s[3]} at {s[4]}",
-             "evidence": [f"ledger: {ledger.name}"]} for s in stages if s[3] in ("pass", "skip")]
+             "evidence": [f"ledger: {ledger.name}", *reviews.get(s[0], [])]}
+            for s in stages if s[3] in ("pass", "skip")]
     nxt = sid + 1 if verdict in ("pass", "skip") else sid
     last = max(names) if names else 10
     open_steps = [] if sid >= last and verdict == "pass" else [{