task-pipeline-skill 1.93.2 → 1.94.1

package/plugins/task-pipeline/hooks/memory-nudge.sh

@@ -8,10 +8,19 @@
 # matters: once per stage line, as context the model reads, and never again for the same
 # line. It decides nothing and blocks nothing.
 #
+# Silent for the rest of a run that recorded memory unavailable FOR THE RUN
+# (`stage_checkpoint.py record --unavailable "<why>" --for-run` writes a marker into
+# .task-pipeline/memory.json carrying a hash of the Run: line's topic and date; the marker
+# is honoured only while the ledger names that same run and still carries the marker's own
+# ledger line, and a later `record --answer` clears it). Without that marker a
+# machine with no Observatory paid about eleven nudges per run for one unchanging fact
+# (CHANGELOG, Unreleased). The first nudge of a run also says where Observatory comes from, once.
+#
 # Silent everywhere else: no ledger means exit 0 after one file test.
 set -uo pipefail
 ledger="${CLAUDE_PROJECT_DIR:-$PWD}/.task-pipeline/run.md"
 [ -f "$ledger" ] || exit 0
+TP_SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")/../skills/task-pipeline/scripts" 2>/dev/null && pwd)" \
 python3 - "$ledger" <<'PY' 2>/dev/null || true
 import hashlib, json, os, re, sys
 ledger = sys.argv[1]
@@ -27,8 +36,27 @@ for i, l in enumerate(lines):
         last_mem = i
 if last_stage < 0 or last_mem > last_stage:
     sys.exit(0)
+here = os.path.dirname(ledger)
+# The run key comes from stage_checkpoint.py's own helper — one definition of "this run" for
+# the marker it writes and the pointer below. Unimportable: no key, so the marker is not
+# honoured and the nudge behaves as before (never blocks).
+try:
+    sys.path.insert(0, os.environ["TP_SCRIPTS"])
+    import pathlib
+    from stage_checkpoint import run_key, marker_for_this_run
+    this_run = run_key(lines)
+except Exception:
+    this_run = marker_for_this_run = None
+try:
+    state = json.load(open(os.path.join(here, "memory.json"), encoding="utf-8"))
+    # Honoured only for the run that wrote it — same topic and start date, and its own
+    # `unavailable for this run` line still in this ledger (a reseeded ledger has none).
+    if marker_for_this_run and marker_for_this_run(pathlib.Path(ledger), state):
+        sys.exit(0)
+except (OSError, ValueError, AttributeError, TypeError):
+    pass  # no marker, or one that cannot be read: nudge as before, never block
 line = lines[last_stage]
-mark = os.path.join(os.path.dirname(ledger), ".memory-nudged")
+mark = os.path.join(here, ".memory-nudged")
 key = hashlib.sha256(line.encode()).hexdigest()[:16]
 try:
     if open(mark).read().strip() == key:
@@ -42,8 +70,22 @@ except OSError:
 sid = re.match(r"^stage:\s*(\S+)", line).group(1)
 msg = (f"task-pipeline: stage {sid}'s gate returned and no workflow-memory line follows it. "
        "With Observatory's tools: `scripts/stage_checkpoint.py emit` → observatory_checkpoint_write "
-       "→ `stage_checkpoint.py record --answer -`. Without them: "
-       "`stage_checkpoint.py record --unavailable \"<why>\"`. (references/continuity.md, Part 3)")
+       "→ `stage_checkpoint.py record --answer -`. Without them, once for the whole run: "
+       "`stage_checkpoint.py record --unavailable \"<why>\" --for-run`. (references/continuity.md, Part 3)")
+# Once per run, keyed by the ledger's `Run:` line: where the tools come from.
+run_id = this_run or hashlib.sha256(ledger.encode()).hexdigest()[:16]
+pointer = os.path.join(here, ".memory-pointer")
+try:
+    shown = open(pointer).read().strip() == run_id
+except OSError:
+    shown = False
+if not shown:
+    msg += (" Observatory is the public engine passioncode-ai/project-observatory-dashboard "
+            "(its README: Install, MCP).")
+    try:
+        open(pointer, "w").write(run_id + "\n")
+    except OSError:
+        pass
 print(json.dumps({"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": msg}}))
 PY
 exit 0

package/plugins/task-pipeline/skills/evidence-docs/references/gates.md

@@ -50,12 +50,14 @@ From [`../pipeline.schema.json`](https://github.com/ssheleg/task-pipeline/blob/m
 |---|---|---|
 | `auto` | the orchestrator verifies the `check` itself, pass/fail, and stops on fail | advancing on an unverified check |
 | `judgment` | somebody **rules** on it, because no complete deterministic check exists; the gate names its `judge` | recording the ruling in the slot reserved for what a machine established |
-| `manual` | wait for the operator's **explicit** go | treating an auto verification as the approval |
+| `manual` | the operator's **explicit** go, or specific standing authorization naming the act | treating an auto verification as the approval |
 
 **An auto gate never substitutes for a required manual approval.** A green table is
 not the operator confirming it is what they asked for, and no amount of checking
 makes it one. Which stages are manual is the **operator's** decision, recorded in
 their `pipeline.json`; the framework fixes no stage count and no gate assignment.
+A standing authorization is cited with its source and scope, not inferred from a generic
+loop flag ([`continuity.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/continuity.md) → *The limit, before the capability*).
 
 **That sentence is about the pipeline's SHAPE, and nothing else.** It says a project
 chooses how many stages it runs and which of them wait for a person. It does not say the
@@ -495,8 +497,9 @@ run:
   what it does not cover, stated, beats two measurements and no decision.
 
 **This never licenses skipping a gate.** The gates are the floor, and the floor is
-not proportionate to anything — a `manual` gate waits, `unknown` fails stage 10, and
-a green nobody watched fail is not evidence at any blast radius. What is
+not proportionate to anything — a `manual` gate waits without an explicit go or a
+specific standing authorization naming its act, cited with source and scope;
+`unknown` fails stage 10, and a green nobody watched fail is not evidence at any blast radius. What is
 proportionate is the work *above* the floor: how many axes, how many passes, how
 much of the corpus. Cutting the floor to go faster is not speed; it is the failure
 this whole file exists to prevent, arriving on schedule.

package/plugins/task-pipeline/skills/evidence-docs/references/hooks.md

@@ -219,7 +219,8 @@ Since v1.50.0 the plugin carries hooks of its own. `hooks/release-gate.sh`
 tag push, `gh release create`, `npm publish` — while the run says the suite has not
 passed. `hooks/gate-observer.sh` (`PostToolUse` and `PostToolUseFailure`) records
 what the declared gate command actually did. `hooks/memory-nudge.sh` (`PostToolUse` on `Bash|Edit|Write|MultiEdit`) reminds,
-once per returned gate, that no workflow-memory line follows it
+once per returned gate, that no workflow-memory line follows it — unless the run recorded
+memory unavailable with `--for-run`
 ([`continuity.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/continuity.md), Part 3).
 
 **Two lessons from v1.50.0, both shipped as defects and both fixed in v1.51.0.**

package/plugins/task-pipeline/skills/evidence-docs/references/retrospective.md

@@ -44,6 +44,7 @@ file exists to stop.
 - A fix to one call site closes a call site, not a class
 - The loop closes at stage 0
 - Where a lesson goes when it is not about this project
+- Recording to a shared lesson store, where the host has one
 - Publishing the insight — the skill learns from every project that runs it
 - The improvement iteration — what happens to a published insight next
 - What may leave the project — the redaction list
@@ -416,6 +417,28 @@ file that accumulates universal rules is a fork of the skill that nobody named.
 trigger and no authorization** — an instruction on rung 1 that everybody read as done.
 The rest of this section is the mechanism.
 
+## Recording to a shared lesson store, where the host has one
+
+**One job: let the next agent on another project read this lesson at its stage 0.** An
+entry whose class would be true in another project carries a `**Lesson:**` line — the class
+key, the class in one sentence, when it applies, 3–8 search nouns. That line makes it a
+*lesson* ([`lesson.schema.json`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/templates/lesson.schema.json), lesson/1): with task-pipeline installed, its `scripts/lessons.py add` puts it in the
+local index every install has, and where the session lists a shared lesson store (an
+Observatory) it is also recorded there, as a proposal. An entry without the line stays
+private to this project.
+
+**A lesson is not a publication, but the redaction list below binds it too — with one
+relaxation.** On this machine or estate (the local index, a shared store), rule 2 is relaxed
+for exactly two fields: the evidence commit and the pseudonymous project key (`p-` and 12 hex
+of the root commit, the same key in the store, never the repository's name or a
+`project:<slug>` id). A private repository's SHA names nothing; a public repository's SHA is
+searchable, so it stays in its field and never in text. Rules 1, 3, 4 and 5 still bind every
+text field: no path at all, no code or value, no person's, company's, customer's or
+product's name, a title that states the class. `retro.publish` strips the whole origin.
+The read side is source 7b of [`knowledge-sources.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md). Where no store exists the run
+says `shared lessons: absent` rather than nothing.
+Mechanics and the read and write recipes: [`iteration.md`](https://github.com/ssheleg/task-pipeline/blob/main/plugins/task-pipeline/skills/task-pipeline/references/iteration.md) → *The learning loop*.
+
 ## Publishing the insight — the skill learns from every project that runs it
 
 **One job: stop a lesson dying in the repository that learned it.**
@@ -507,7 +530,9 @@ is what you want them to do.
 ## What may leave the project — the redaction list
 
 An issue is a **public artefact in someone else's repository**. What travels is the
-*class*; what stays is everything that identifies where it happened.
+*class*; what stays is everything that identifies where it happened. This list binds
+whatever leaves the estate, and every lesson too; *Recording to a shared lesson store*
+above names the one relaxation a lesson kept on this machine or estate gets.
 
 | Goes | Stays |
 |---|---|

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: task-pipeline
-description: "Use when work changes the repository — feature, fix, bug, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, баг, рефактор, миграция, интеграция, доработать, починить, внедрить, перевести — or a finding that lands in it: audit/аудит, bug hunt/проверь ошибки, production check/проверь прод, PR review/ревью PR — or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. Runs a substantial task through gated stages: intake grill, docs, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki, acceptance. 'waves' / 'волнами' closes the whole board; 'checkup' / 'чекап' lists unconfirmed releases; 'setup' audits docs. Not for: answering a question, explaining code, a typo, a one-line edit, a mechanical rename, reconnaissance that lands nothing — say 'no pipeline' / 'без пайплайна' to opt out."
+description: "Use when work changes the repository — feature, fix, bug, refactor, migration, integration, rewrite, adoption or hardening; фича, фикс, баг, рефактор, миграция, интеграция, доработать, починить, внедрить, перевести — or a finding that lands in it: audit/аудит, bug hunt/проверь ошибки, production check/проверь прод, PR review/ревью PR — or on 'run this through the pipeline'/'прогони по конвейеру', 'the full cycle'/'полный цикл', /task-pipeline. Runs a substantial task through gated stages: intake grill, docs, brainstorm, spec, plan, build, tests, deploy, post-deploy, docs/wiki, acceptance. 'waves'/'волнами'/'release iteration'/'итерация релиза' closes the board; 'checkup'/'чекап' lists unconfirmed releases; 'setup' audits docs. Not for: answering a question, explaining, a typo, a one-line edit, a rename, recon that lands nothing — say 'no pipeline'/'без пайплайна' to opt out."
 license: MIT
 compatibility: "Doctrine runs on any agent. The bundled scripts need python3; the run needs git. Missing either degrades, never blocks — the graph verbs and seeded gates go unused, and the run says so."
 ---
@@ -46,7 +46,7 @@ kernel field. Each gate has a **type**: `auto` (the
 orchestrator verifies the `check` itself, pass/fail), `judgment` (no complete
 deterministic check exists — a named judge rules, and the ruling is recorded as
 judgement, never as a measurement; `references/gates.md` → *The judgment gate*)
-or `manual` (wait for an explicit operator go); which stages are manual is the
+or `manual` (an explicit go, including specific standing authorization); which stages are manual is the
 operator's call. In the
 example's `skills[]`, `task-pipeline:<name>` denotes this skill's own built-in
 doctrine (`references/<name>.md`) and `host:<name>` denotes the host project's own
@@ -122,11 +122,10 @@ Stage 0 reads those standing instructions in full, which is why the prune is a g
 criterion: a rule nobody reads to the end is worse than no rule, because everyone
 believes it is covered.
 
-Three things the grill does beyond clarifying the request, each in full in
-[`references/grill.md`](references/grill.md):
-- **Domain awareness** — it reads the project's `CONTEXT.md` / `docs/adr/` and holds the operator to them, writing resolved terms back as they land.
-- **The autonomy sweep** — it pre-resolves what would otherwise stop stages 1→10 mid-flight. Autonomy is bought here or not at all; an unasked question is a scheduled interruption.
-- **The design destination** with Figma on — *which* file per surface, in which team, decided at stage 0. Left to drawing time it is answered by whoever holds the brush, and the answer is usually *create a new file*.
+**At stage 0, read [grill.md](references/grill.md)** for domain awareness
+(`CONTEXT.md` / ADRs; write resolved terms back), the autonomy sweep (pre-resolve
+stages 1→10), and the Figma design destination (file and team per surface, settled
+before drawing, never invented by the drawing agent).
 
 ## How to run
 
@@ -176,13 +175,16 @@ Three things the grill does beyond clarifying the request, each in full in
    build order, one brick at a time — stages 0–2 run once, and the module map's
    status column is the resume point (`references/stages.md` → *The program loop*).
    **The whole board?** `/task-pipeline waves` (`references/waves.md`): stages
-   0–4 once, 5–8 per wave, 9–10 to close.
+   0–4 once, 5–8 per wave, 9–10 to close. **The project moves in releases**: the loop
+   around the waves — survey, module dossiers, one design, parallel build, checks that
+   start as each node lands, release, post-release check, next pool — is
+   `references/iteration.md`. A finding joins the inventory; it is not fixed alone.
 4. Do **not** advance until the stage **gate** passes (`references/stages.md`).
    Honor the gate **type**: for `auto`, verify the gate's `check` yourself and
    stop/return on fail; for `judgment`, record the named judge's ruling as
-   judgement, never as a measurement; for `manual`, present the result and
-   **wait for the operator's explicit "continue"/go** — neither of the other
-   two ever substitutes for a required manual approval.
+   judgement, never as a measurement; for `manual`, present the result and cite the
+   **operator's explicit go or standing authorization naming this act**. Other gate
+   types and generic loop flags cannot supply that authority (`references/continuity.md`).
 5. **The cross-cutting rules fire at any stage**, not only here — the Doc Loop, the
    loop guard, the audit's exit, the frozen REQ list, the carry-over ledger, and
    what counts as evidence, and **every gate prints `holds: N`** — what this run left

package/plugins/task-pipeline/skills/task-pipeline/graph.schema.json

@@ -91,9 +91,10 @@
             "running",
             "done",
             "blocked",
-            "parked"
+            "parked",
+            "waiting"
           ],
-          "description": "`blocked` is waiting on an edge; `parked` is the verifier's deliberate *«this is a blocker, continue around it»*. The two are different facts and collapsing them loses the one a person needs."
+          "description": "`blocked` is waiting on an edge; `parked` is the verifier's deliberate *«this is a blocker, continue around it»*. The two are different facts and collapsing them loses the one a person needs. `waiting` records an external event and a watcher locator; it is never runnable."
         },
         "claim": {
           "type": [
@@ -205,6 +206,10 @@
           ],
           "description": "The class of the user-facing surface this node builds, copied from the brief's `surface_class` (stage 0). It selects the gate profile, and `graph.py certify` reads it: on `flagship` or `product` the fourth, `visual` tier report is REQUIRED, because none of unit, seam or product opens the contact sheet; on any other class a `visual` report is accepted when given. Absent on a node that builds no user-facing surface. `references/certification.md` → *The fourth reading*."
         },
+        "risk": {
+          "enum": ["R1", "R2", "R3"],
+          "description": "The node's risk class (`references/iteration.md` → *Verification starts when a node lands*), computed from what it touches and never lowered to save time. It sets how many PASSING certification rounds the node owes (a failed round counts for nothing): R1 one, R2 two, R3 three, one of them recorded adversarial (`certify --kind adversarial`). A round is the three blind tiers plus one fix cycle. Absent outside wave mode or a release iteration. `graph.py close` refuses a node until the rounds its class owes have passed."
+        },
         "wave": {
           "type": "integer",
           "minimum": 1,
@@ -264,6 +269,11 @@
               "type": "string",
               "minLength": 1
             },
+            "kinds": {
+              "type": "array",
+              "description": "One entry per round: `blind` (the default) or `adversarial` (`graph.py certify --kind adversarial`). An R3 node owes three passing rounds, one of them adversarial (`references/certification.md` → *Rounds owed by risk class*).",
+              "items": {"enum": ["blind", "adversarial"]}
+            },
             "history": {
               "type": "array",
               "minItems": 1,
@@ -392,6 +402,9 @@
             }
           },
           "description": "The IMMUTABLE dispatch packet this node was built from (FIX-PF-05.01): address + digest of the compiled packet (REQ refs, constraints, interfaces, artifact digests, base, scope, budget, profile, skill lock — no ephemeral secret). Links the node to the exact context it ran under, so a graph in a git-ignored workspace still points at a durable, content-addressed packet."
+        },
+        "waiting_on": {
+          "$ref": "#/definitions/wait_record"
         }
       },
       "allOf": [
@@ -406,6 +419,9 @@
         },
         {
           "$ref": "#/definitions/rule_running_needs_claim"
+        },
+        {
+          "$ref": "#/definitions/rule_waiting_needs_watcher"
         }
       ]
     },
@@ -450,9 +466,12 @@
             "close",
             "invalidate",
             "waive",
-            "wave"
+            "wave",
+            "risk",
+            "wait",
+            "resume"
           ],
-          "description": "Which mutation made this entry. `close` joined the two on 2026-08-17 with T-5 — and it was caught by a probe rather than by the fixture asserting *the graph after a close still validates*, because `violations()` never reaches an enum. The same disagreement B-084 records, one field over. `invalidate` joined with PF-02.02: a REQ/interface/brief change supersedes a node and resets its downstream proofs. `wave` joined with wave mode: the re-cut after every wave moves nodes between waves, and a move nobody recorded is the quiet re-plan `references/planning.md` refuses."
+          "description": "Which mutation made this entry. `close` joined the two on 2026-08-17 with T-5 — and it was caught by a probe rather than by the fixture asserting *the graph after a close still validates*, because `violations()` never reaches an enum. The same disagreement B-084 records, one field over. `invalidate` joined with PF-02.02: a REQ/interface/brief change supersedes a node and resets its downstream proofs. `wave` joined with wave mode: the re-cut after every wave moves nodes between waves, and a move nobody recorded is the quiet re-plan `references/planning.md` refuses. `risk` joined with the release iteration: `waves.py sync-graph` sets a node's risk class from the plan, and a lowering carries its own reason."
         },
         "node": {
           "type": "string",
@@ -468,6 +487,9 @@
         "precondition": {
           "type": "string",
           "description": "The tree the mutation was made against — the proven HEAD for a `close` (FIX-PF-02.01). A revision then carries a VERSION, so a brief/REQ/interface change that moves the tree is a visibly different precondition, which is what invalidates a proof taken before it."
+        },
+        "waiting_on": {
+          "$ref": "#/definitions/wait_record"
         }
       }
     },
@@ -575,6 +597,69 @@
           }
         }
       }
+    },
+    "rule_waiting_needs_watcher": {
+      "if": {
+        "properties": {
+          "status": {
+            "const": "waiting"
+          }
+        },
+        "required": [
+          "status"
+        ]
+      },
+      "then": {
+        "required": [
+          "waiting_on"
+        ],
+        "properties": {
+          "claim": {
+            "type": "null"
+          }
+        }
+      },
+      "else": {
+        "not": {
+          "required": [
+            "waiting_on"
+          ]
+        }
+      }
+    },
+    "wait_record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "watcher"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{32}$",
+          "minLength": 32,
+          "maxLength": 32
+        },
+        "kind": {
+          "enum": [
+            "ci",
+            "review",
+            "peer",
+            "release",
+            "time",
+            "lease"
+          ]
+        },
+        "watcher": {
+          "type": "string",
+          "pattern": "\\S",
+          "not": {
+            "pattern": "[\\r\\n]"
+          }
+        }
+      }
     }
   }
 }

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

@@ -205,6 +205,13 @@
           "type": "string",
           "description": "Free prose beside `goal`."
         },
+        "authorized_by": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "\\S",
+          "not": {"pattern": "[\\r\\n]"},
+          "description": "Optional single-line source locator (for example docs/DECISIONS.md:42) for the specific standing authorization covering the tag and its publication. The locator is not authorization: read the source and verify its authority, currentness and scope at stage 7. Absent: inspect existing recorded authority before asking; do not infer a grant from checks approval, loop mode or this field's mere presence (references/deploy-targets.md)."
+        },
         "approval": {
           "enum": [
             "checks",

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

@@ -21,6 +21,7 @@ exactly one seam, and that seam already existed as a dangling pointer.
 - A row that says work exists names where it lives
 - Priority is computed, not assigned
 - The shape is not fixed, so nothing may assume it
+- A declared source list — `docs/backlog-sources.json`
 - A decision is not debt — `waived`
 - What a loop iteration does with it
 - Rationalizations
@@ -161,6 +162,30 @@ The same rule governs the verification ledger, where five shapes exist across th
 and only one carries a column that can say a *person* looked
 ([`exposure.md`](exposure.md)).
 
+## A declared source list — `docs/backlog-sources.json`
+
+A project whose open work lives in several files — a board, a roadmap, a lane per product —
+can declare them, and then the board is exactly those files. Wave 0's harvest reads only the
+sources the manifest lists, with the id, title and status columns each one names
+([`waves.md`](waves.md) → *Wave 0*). A source of open work the manifest does not list is
+reported as a finding, never silently added; a status change lands only in the owning file,
+under a lease.
+
+**The shape is [`templates/backlog-sources.schema.json`](../templates/backlog-sources.schema.json)**
+(backlog-sources/1), and it is the rule for anyone using this skill:
+- `schema` is 1, `repository` the repository's canonical GitHub URL, `sources` 1–100 entries;
+- each source is a relative `path` (no hidden, `.` or `..` segment), a `goal` anchor, and a
+  `kind` — `tasks` (the default) or `context`;
+- a `tasks` source has a `format`: `table`, `checklist` or `json-tasks`. A table names its
+  `idColumn` and `titleColumn`, and exactly one of `statusColumn` or `defaultStatus: "open"`;
+- `idPattern` is a literal prefix, optionally `[0-9]+`, anchored at both ends; `excludeIds`
+  a unique list.
+
+Two rules a schema cannot state are the harvest's to check: each path is a regular file
+reached through no symlink, and no two declarations are identical. The Fabric workspace keeps
+a source contract this one is compatible with; that page is provenance, not authority, and a
+public reader never needs it.
+
 ## A decision is not debt — `waived`
 
 `open` is work not done. `dropped` is an idea abandoned. Neither fits a deliberate **no**

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

@@ -21,6 +21,7 @@ queue is — graph or plan — is what decides, not the mood of the closer.
 - The report, and where each field lands
 - The commands
 - The fix cycle, and its ceiling
+- Rounds owed by risk class
 - What this costs, said out loud
 - Rationalizations
 
@@ -217,10 +218,53 @@ has failed **every** round. A run spinning on one level needs the operator to se
 *which* level:
 
 - the same tier every round → the level is being misread, or the node is the wrong
-  shape. Not one fix away. Re-plan the node, do not attempt round four.
+  shape. Not one fix away. Re-plan the node, do not attempt another failing round. (An R3
+  node's owed rounds are not this count — *Rounds owed by risk class*, below.)
 - different tiers each round → churn across levels. Usually one requirement that
   was never decided, surfacing at whichever distance looks at it.
 
+## Rounds owed by risk class
+
+In a release iteration a node carries `risk` (R1–R3, [`work-graph.md`](work-graph.md);
+[`iteration.md`](iteration.md) → *Verification starts when a node lands*), and the class
+decides how many **passing** rounds the node owes before `close` accepts it: **R1 one, R2
+two, R3 three, of which one is adversarial.** A round is the three blind tiers (four on a
+flagship or product surface) plus one fix cycle. `graph.py certify` prints `round N: k of M
+owed passing rounds — not closable yet` until the count is met (`k of M owed passing rounds —
+closable` once it is), and `graph.py close` refuses
+the verdict until then. **Only passing rounds count** — a round passes when every tier
+passes, read from `certification.history` — and, for R3, one of the passing rounds must be
+one recorded with `--kind adversarial`
+(`certification.kinds`, one entry per round). A node with a `risk` and no certification at
+all is refused by `close` too: its class owes at least one round.
+
+**What a round after a clean round reads.** The node's **whole diff at the new HEAD** — not
+the fix diff alone, and not the previous round's reports. A clean round proves the tree it
+read; the next owed round asks the same three distances again of the whole change as it
+stands, so a defect the first reading accepted has a second chance to be seen from a fresh
+context.
+
+**Owed rounds and the ceiling are different counts.** `--ceiling` measures churn: how many
+rounds a node has *failed*, and which tier keeps failing. An R3 node that owes three rounds
+and passes them is not "at round four" of anything; its owed rounds are the plan, and the
+ceiling's warning is about failing rounds beyond what the class owes. Read the ceiling's
+output only when rounds fail.
+
+**The adversarial round** (one of R3's three, on another model where one is available):
+1. **Plant defects in the change** — off-by-one in a limit, an inverted check, a dropped
+   error path — and require the node's own checks to fail on each. A plant that passes is a
+   finding against the check, not against the plant.
+2. **Model the external system's state across runs** — a policy edited between two runs, a
+   key or resource renamed, two writers at once, a provider that echoes a request back or
+   answers twice. The defects of a money or credential path live in the second run, not
+   the first.
+3. **Try the abuse cases** a caller outside the trust boundary would: inputs at and past
+   every bound, replays, a revoked identity, an out-of-order sequence.
+
+It is a different question, not a stricter reading: on 2026-10-12 one iteration's third
+round on a spend-limits node found three breaks of a money invariant that two blind rounds
+had passed. Record it with `certify --kind adversarial`.
+
 ## What this costs, said out loud
 
 Three agents per node instead of one — four on a flagship or product surface. That is