task-pipeline-skill 1.87.1 → 1.89.1

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,12 @@ 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*). 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 +511,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 +544,19 @@ 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, 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 +727,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

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""A workflow checkpoint at every stage boundary, built from the run ledger.
+
+When the host has Project Observatory's memory tools (`observatory_checkpoint_write`, or
+`memory.checkpoint.write` under memory/0.1), a run writes one checkpoint each time a gate
+returns. A session that runs out of quota, is compacted or is replaced by another agent then
+continues from the last finished stage instead of re-deriving it. Without those tools the
+run goes on exactly as before, and the ledger says memory was unavailable.
+
+This script never talks to Observatory: the agent calls the tool. The script does the two
+deterministic halves around that call, so nothing about the checkpoint is left to recall:
+
+    stage_checkpoint.py emit   [--ledger PATH] [--project project:<slug>]
+                               [--constraint TEXT ...] [--credential PROJECT/ENV/NAME ...]
+        prints the tool's arguments as JSON, from the ledger's last `stage:` line
+    stage_checkpoint.py record --answer FILE|-   [--ledger PATH]
+        reads the tool's answer and keeps `workflowId` and `leaseId` for the next boundary
+    stage_checkpoint.py record --unavailable "<reason>"   [--ledger PATH]
+        the tools are absent or failed: one ledger line, exit 0, the run continues
+    stage_checkpoint.py state  [--ledger PATH]
+        the workflow this run writes to, for `observatory_checkpoint_latest` after a resume
+
+What it keeps, and where:
+
+- The arguments carry no prose the ledger does not hold: the run's topic is the goal, the
+  ledger's verdicts are `done`, the next stage is `open`, the operator's constraints come in
+  as `--constraint`, keys are passed by NAME only (`--credential`), and the git checkout is
+  an artifact (branch and a 12-character head). Observatory redacts what it stores as well.
+- `idempotencyKey` is derived from the run's topic and the exact `stage:` line, so a retry
+  of the same boundary replays the first answer, and a stage that runs again (a new line, a
+  new time) is a new checkpoint.
+- `workflowId` and `leaseId` live in `.task-pipeline/memory.json`, mode 0600, beside the
+  ledger in the git-ignored run directory, with the constraints and key names given so far:
+  they are stated once and carried to every later boundary. The lease token is a write right: it is never
+  printed, never appended to the ledger, never put in a commit.
+- A refused write (`LeaseLost`: another executor holds the workflow now) is recorded with
+  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>
+    event: memory — refused <error> (kept as <id>) — <ISO-8601>
+    event: memory — unavailable — <reason> — <ISO-8601>
+
+Exit codes: 0 done (including "unavailable", which is a state, not a failure); 2 the ledger
+or the answer cannot be read.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+DEFAULT_LEDGER = ".task-pipeline/run.md"
+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"}
+
+
+def _stages() -> dict[int, str]:
+    """The stage names by id, from the bundle's own `pipeline.example.json` — the file the
+    validator compares with `references/stages.md`, so this list cannot drift from it."""
+    path = pathlib.Path(__file__).resolve().parents[1] / "pipeline.example.json"
+    try:
+        doc = json.loads(path.read_text(encoding="utf-8"))
+        return {int(s["id"]): str(s["name"]) for s in doc["stages"]}
+    except (OSError, ValueError, KeyError, TypeError):
+        return {}
+
+
+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")
+    except OSError as exc:
+        raise SystemExit(f"stage_checkpoint: the ledger {path} cannot be read ({type(exc).__name__})")
+    topic, stages = None, []
+    for line in text.splitlines():
+        m = TOPIC.match(line)
+        if m and topic is None and "<topic>" not in m.group(1):
+            topic = m.group(1)
+        s = STAGE.match(line)
+        if s:
+            stages.append((int(s.group(1)), s.group(2), s.group(3), s.group(4), s.group(5), line))
+    if not topic:
+        raise SystemExit("stage_checkpoint: the ledger names no run (`Run: `<topic>`` line)")
+    return topic, stages
+
+
+def _state_path(ledger: pathlib.Path) -> pathlib.Path:
+    return ledger.parent / STATE_NAME
+
+
+def _load_state(ledger: pathlib.Path) -> dict:
+    try:
+        return json.loads(_state_path(ledger).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _save_state(ledger: pathlib.Path, state: dict) -> None:
+    path = _state_path(ledger)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(state, f)
+    os.chmod(path, 0o600)
+    ignore = path.parent / ".gitignore"
+    lines = ignore.read_text(encoding="utf-8").splitlines() if ignore.exists() else []
+    if STATE_NAME not in lines:
+        ignore.write_text("\n".join([*lines, STATE_NAME]) + "\n", encoding="utf-8")
+
+
+def _append(ledger: pathlib.Path, line: str) -> None:
+    ledger.parent.mkdir(parents=True, exist_ok=True)
+    with ledger.open("a", encoding="utf-8") as f:
+        f.write(line + "\n")
+
+
+def _git(root: pathlib.Path, *args: str) -> str | None:
+    try:
+        r = subprocess.run(["git", *args], cwd=root, capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return r.stdout.strip() if r.returncode == 0 and r.stdout.strip() else None
+
+
+def _project(root: pathlib.Path, given: str | None) -> str:
+    if given:
+        return given
+    top = _git(root, "rev-parse", "--show-toplevel")
+    name = pathlib.Path(top or root).name.lower()
+    slug = re.sub(r"[^a-z0-9._-]+", "-", name).strip("-") or "unnamed"
+    return f"project:{slug}"
+
+
+def emit(ledger: pathlib.Path, project: str | None, constraints: list[str],
+         credentials: list[str]) -> dict:
+    topic, stages = _read_ledger(ledger)
+    names = _stages()
+    if not stages:
+        raise SystemExit("stage_checkpoint: no `stage:` line yet — a checkpoint follows a gate")
+    sid, name, gate, verdict, at, line = stages[-1]
+    root = ledger.parent.parent if ledger.parent.name == ".task-pipeline" else ledger.parent
+    state = _load_state(ledger)
+    # CONSTRAINTS AND KEYS OUTLIVE THE BOUNDARY THEY WERE GIVEN AT. The operator states them
+    # once; a later boundary that dropped them would hand a successor an empty list — the
+    # one thing a successor must never act without (found by the live receipt, 2026-10-05).
+    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}", *reviews.get(s[0], [])]}
+            for s in stages if s[3] in ("pass", "skip")]
+    nxt = sid + 1 if verdict in ("pass", "skip") else sid
+    last = max(names) if names else 10
+    open_steps = [] if sid >= last and verdict == "pass" else [{
+        "step_id": f"stage-{nxt}",
+        "next_action": (f"enter stage {nxt} {names.get(nxt, '')}".strip() if nxt != sid
+                        else f"repair stage {sid} {name}: its gate failed")}]
+    creds = []
+    for c in credentials:
+        parts = c.split("/")
+        if len(parts) != 3 or not all(parts):
+            raise SystemExit("stage_checkpoint: --credential is PROJECT/ENV/NAME, a name never a value")
+        creds.append({"project": parts[0], "env": parts[1], "name": parts[2]})
+    artifacts = []
+    branch, head = _git(root, "rev-parse", "--abbrev-ref", "HEAD"), _git(root, "rev-parse", "HEAD")
+    if head:
+        artifacts.append({"kind": "git", "path": str(root), "branch": branch or "", "head": head[:12]})
+    body = {"goal": topic,
+            "plan": [{"step_id": f"stage-{i}", "title": names[i]} for i in sorted(names)],
+            "done": done, "open": open_steps, "constraints": constraints,
+            "artifacts": artifacts, "notes": f"task-pipeline stage boundary; run ledger {ledger}"}
+    if creds:
+        body["credentials"] = creds
+    args = {"owner": OWNER,
+            "idempotencyKey": "tp-" + hashlib.sha256(f"{topic}\n{line}".encode()).hexdigest()[:32],
+            "stepId": f"stage-{sid}", "status": STATUS.get(verdict, "in_progress"), "body": body,
+            "close": sid >= last and verdict == "pass"}
+    if state.get("workflowId") and state.get("leaseId"):
+        args["workflowId"], args["leaseId"] = state["workflowId"], state["leaseId"]
+    else:
+        args["projectId"] = _project(root, project)
+    if constraints != state.get("constraints", []) or credentials != state.get("credentials", []):
+        _save_state(ledger, {**state, "constraints": constraints, "credentials": credentials})
+    return args
+
+
+def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | None) -> str:
+    if unavailable is not None:
+        reason = " ".join(unavailable.split())[:200] or "no reason given"
+        line = f"event: memory — unavailable — {reason} — {_now()}"
+        _append(ledger, line)
+        return line
+    try:
+        answer = json.loads(answer_text or "")
+    except ValueError:
+        raise SystemExit("stage_checkpoint: the answer is not JSON")
+    if not isinstance(answer, dict):
+        raise SystemExit("stage_checkpoint: the answer is not an object")
+    state = _load_state(ledger)
+    if answer.get("error"):
+        kept = answer.get("keptAs")
+        if answer["error"] in ("LeaseLost", "WorkflowClosed"):
+            # A stale writer stops here: the token is dropped and the next boundary starts
+            # by reading the workflow, not by writing to it again.
+            state.pop("leaseId", None)
+            state["stale"] = answer["error"]
+            _save_state(ledger, state)
+        line = (f"event: memory — refused {answer['error']}"
+                f"{f' (kept as {kept})' if kept else ''} — {_now()}")
+        _append(ledger, line)
+        return line
+    wid = answer.get("workflowId") or state.get("workflowId")
+    lease = answer.get("leaseId") or state.get("leaseId")
+    if not wid:
+        raise SystemExit("stage_checkpoint: the answer names no workflowId")
+    _save_state(ledger, {**{k: v for k, v in state.items() if k in ("constraints", "credentials")},
+                         "workflowId": wid, **({"leaseId": lease} if lease else {})})
+    rev = (answer.get("checkpoint") or {}).get("revision") or answer.get("revision") or "?"
+    step = answer.get("stepId") or "?"
+    line = f"event: memory — checkpoint {step} rev {rev} {wid} — {_now()}"
+    _append(ledger, line)
+    return line
+
+
+def main(argv: list[str]) -> int:
+    p = argparse.ArgumentParser(prog="stage_checkpoint.py",
+                                description="A workflow checkpoint at every stage boundary.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    e = sub.add_parser("emit", help="print the checkpoint tool's arguments")
+    e.add_argument("--ledger", default=DEFAULT_LEDGER)
+    e.add_argument("--project", help="project:<slug>; default the checkout's folder name")
+    e.add_argument("--constraint", action="append", default=[], help="repeatable")
+    e.add_argument("--credential", action="append", default=[], help="PROJECT/ENV/NAME, repeatable")
+    r = sub.add_parser("record", help="keep the answer, or record that memory is unavailable")
+    r.add_argument("--ledger", default=DEFAULT_LEDGER)
+    g = r.add_mutually_exclusive_group(required=True)
+    g.add_argument("--answer", help="a file with the tool's JSON answer, or - for stdin")
+    g.add_argument("--unavailable", help="why the tools could not be used")
+    s = sub.add_parser("state", help="the workflow this run writes to; never the token")
+    s.add_argument("--ledger", default=DEFAULT_LEDGER)
+    a = p.parse_args(argv)
+    ledger = pathlib.Path(a.ledger)
+    if a.cmd == "emit":
+        print(json.dumps(emit(ledger, a.project, a.constraint, a.credential), ensure_ascii=False))
+        return 0
+    if a.cmd == "state":
+        st = _load_state(ledger)
+        print(json.dumps({"workflowId": st.get("workflowId"), "holdsLease": bool(st.get("leaseId")),
+                          "stale": st.get("stale")}))
+        return 0
+    text = None
+    if a.answer is not None:
+        text = sys.stdin.read() if a.answer == "-" else pathlib.Path(a.answer).read_text(encoding="utf-8")
+    print(record(ledger, text, a.unavailable))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))