task-pipeline-skill 1.91.2 → 1.93.2

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

@@ -0,0 +1,233 @@
+# Wave mode — closing a whole board in its final form
+
+`/task-pipeline waves`. The request is not one change but **the whole board**: every open
+item a project carries — the board and its lanes, carry-over ledgers, plan rows,
+verification rows still at `never`, scenarios with no coverage, open PRs and unlanded
+branches, asks from other products' sessions — plus the operator's new requests.
+
+**It is a program mode of the existing stages, not a parallel cycle.** Stages 0–4 run
+once, for the whole board. Stages 5–8 run once per wave. Stages 9–10 close the release.
+Every gate in [`stages.md`](stages.md) still holds where its stage runs; what the mode
+changes is how many times each stage runs, and over what.
+
+Decided by the operator on 2026-10-11 and first applied that day to a board of 701 items.
+
+## Contents
+
+- The rule it exists for
+- How the stages map
+- Wave 0 — the survey and the inventory
+- The questions — closed from sources, then one batch
+- The canvas — the target state over the current logic
+- Cutting the waves
+- The wave loop
+- The close pass, after every wave
+- A board bigger than one release
+- What stays human
+- The graph carries the wave
+- Rationalizations
+
+## The rule it exists for
+
+**Build the system in its final form, never through intermediate states.** An
+intermediate state that a later task undoes is the most expensive thing an agent
+produces: the build, the review, the migration and the operator's attention are each
+paid twice, and the second payment is for removing the first. So every item is designed
+against the target state of the whole system first, and only then cut into waves.
+
+**No wave builds a shape a later wave undoes.** A stub is allowed only at a contract the
+canvas declares, and the wave that removes it is named beside it. A stub with no named
+removal is the intermediate state this mode exists to refuse.
+
+What the mode buys, in the order the operator named it: transparency (the inventory,
+the canvas and the wave plan live in the repository, so any agent can resume from them),
+stability, autonomy, predictability (each wave says before it starts what it closes and
+how that is proved), minimum operator time, fast real results, and a strategy corrected
+on real agents, tasks and users rather than on the first guess.
+
+## How the stages map
+
+| Stage | In wave mode |
+|---|---|
+| 0 Intake | once, over the whole board: wave 0's survey is the harvest, the inventory is the work-list, and every in-scope item becomes or joins a REQ row in the operator's words |
+| 1 Docs study | once, for every contract the canvas locks |
+| 2 Brainstorm + decompose | once: the canvas extends the module map ([`decomposition.md`](decomposition.md)), and the work graph carries each node's wave |
+| 3 Spec | once: the canvas is the committed target-state spec; a wave's dossier may deepen a section, never contradict it |
+| 4 Plan | once: every wave's nodes, its exit criteria and the question batch. Re-cut at each wave boundary, as a recorded revision |
+| 5–8 Build → post-deploy | per wave, then the close pass |
+| 9 Docs + wiki · 10 Acceptance | once, to close the release, over everything the waves shipped |
+
+**One planning gate, not three prompts.** The manual gates of stages 0, 2 and 3 are
+presented together at the end of planning: the brief, the canvas, the wave plan and the
+question batch in one message. Each gate's criteria are still checked and printed; the
+operator is asked once, and the go names the gates it closes. Silence closes none.
+
+## Wave 0 — the survey and the inventory
+
+**Harvest every source of open work, by id** ([`knowledge-sources.md`](knowledge-sources.md)
+supplies the sources; [`backlog.md`](backlog.md) the board). For whole-project scope, run
+`project-audit` beside it as a read-only sidecar: its HTML and JSON are measured
+findings, and its proposed rows join the inventory like any other source. Where the
+product has users, walk their real path in the built app on a fresh profile with
+disposable data. A finding is a fact with a receipt, never an impression.
+
+**A declared source list outranks discovery.** Where the repository carries
+`docs/backlog-sources.json` — the contract is owned by the Fabric workspace's
+`knowledge/backlog.md` — the harvest reads exactly the sources it lists, as the board,
+with the id, title and status columns it names. Status changes land only in those owning
+files, under a lease. A new source joins the manifest in the same change. A generated
+view of them, such as a published common backlog, is never edited. A source of open
+work the manifest does not list is reported as a finding, not silently added.
+
+**One machine-readable inventory, nothing outside it.** A single committed file,
+`<artifacts>/specs/YYYY-MM-DD-<topic>-inventory.json`, one entry per open item:
+
+| Field | Carries |
+|---|---|
+| `id` | the item's id in its owning register; an item without one gets one there, in the same change |
+| `source` | where it was found, as `file:line` |
+| `status` | as measured, not as the register last said |
+| `area` | the part of the system it touches |
+| `node` | the canvas node it lands on |
+| `wave` | the wave that closes it, or the release it is carried to |
+| `release` | this release, or `program` |
+
+`blocked_by`, `closable_in_one_pass` and `notes` are worth carrying beside them.
+
+**Verify each open item against the code before trusting it.** A stale item is closed
+in its owning register with the receipt that shows it done; duplicates are clustered,
+both ids kept. A register that says *open* about shipped work is the commonest thing a
+survey finds.
+
+**Assign nodes and waves with a committed script, not by hand.** A deterministic script
+reads the inventory and a short wave table and writes `node`, `wave` and `release` onto
+every entry, then prints the counts per wave and per node. A re-cut is then a diff to a
+table and a re-run, which a reviewer can read; seven hundred hand-edited rows are not.
+
+## The questions — closed from sources, then one batch
+
+**Close every question from the sources first**, in this order: the operator's recorded
+decisions, ADRs and principles, the knowledge base, the code, the neighbours' contracts.
+A question answered there is recorded with its citation — *resolved from the sources,
+not asked* — and closed. What remains is only what is genuinely the operator's: access,
+consent, money, a business or product direction, an outward or irreversible act.
+
+**Those go once, as one batch, at the end of planning.** Each carries a recommended
+answer and the consequence of each answer, ordered so prerequisite decisions come first
+([`grill.md`](grill.md)). A go that leaves a question unanswered takes the
+recommendation, recorded as **assumed** in the decisions table, and every wave that
+depends on an assumption names it — so a different answer later re-plans exactly those
+waves and no others. After planning, a question is asked only at a wave boundary, in the
+hand-back's DECISIONS WAITING ([`progress.md`](progress.md)).
+
+**An outward or irreversible act is never assumed.** Publishing, tagging, deploying
+without a specific standing authorization, sending to a person, spending money,
+deleting data: each waits for the operator's explicit go, asked with a verified direct
+link. A recommendation is not an authorization.
+
+## The canvas — the target state over the current logic
+
+One committed spec, `<artifacts>/specs/YYYY-MM-DD-<topic>-canvas.md`, extending the module
+map. It is the current system with every change laid over it:
+
+1. **As-is → to-be per module and per contract** — data and events, screens and flows,
+   cross-product links.
+2. **The integration seams** — how each integration happens, who owns each side, what
+   crosses it.
+3. **REQ → module → wave**, one row per requirement.
+4. **Deleted or superseded** — what the new version removes (code, screens, contracts,
+   docs) and which wave removes it. A removal nobody wrote down survives the release.
+
+**Every inventory item lands on a node.** An item that lands nowhere is either out of
+scope — said, with a register row — or a gap in the canvas. **The canvas is reviewed for
+coherence before any wave is cut:** two items that change one seam are designed together,
+because designed apart they are the intermediate state the rule above forbids.
+
+## Cutting the waves
+
+**A wave holds only items closable in one pass.** All four, for every item in it:
+
+- its dependencies are done, or inside the same wave;
+- it touches one seam, or a few adjacent ones;
+- its verification can run together with the rest of the wave;
+- the wave leaves the system working — landable, with no half-built shape exposed.
+
+**Wave 1 is the walking skeleton**: the thinnest end-to-end path of the target that
+proves the spine, for the reason [`decomposition.md`](decomposition.md) gives for a
+platform's first brick. **Each wave names its exit criteria before it starts** — the
+tests, the live walk, the gates and the documents that will prove it closed. Criteria
+written after the wave are a description of what happened.
+
+An item that cannot close in one pass because it needs a person stays on its node,
+marked `needs-operator`, out of every wave until it is unblocked.
+
+## The wave loop
+
+Each wave runs stages 5–8 as [`stages.md`](stages.md) states them, then the close pass.
+Between waves the run does not ask whether to continue: it takes the next wave
+([`continuity.md`](continuity.md)). A genuine ambiguity parks its node `needs-operator`
+and the wave goes on with the nodes it does not block; the run stops only when the whole
+frontier is blocked. When the board is empty, it says so once.
+
+Research, the audit and the blind readings run in parallel agents; builds stay sequential
+wherever two of them share a seam ([`planning.md`](planning.md) → file ownership).
+
+## The close pass, after every wave
+
+In this order, inside the wave rather than after it:
+
+1. **Verify.** Every node the wave closes is certified ([`certification.md`](certification.md)),
+   and [`audit.md`](audit.md)'s exit is re-measured over what the wave touched.
+2. **Finish and fix — one fix round**, inside [`loop-guard.md`](loop-guard.md)'s caps.
+   Every finding is fixed in the wave or parked with a board row and its reason; nothing
+   is dropped silently.
+3. **Document** — the Doc Loop and the stage-9 propagation matrix
+   ([`documentation.md`](documentation.md)), scoped to the wave: scenarios, decisions,
+   docs and registers in the same change as the code.
+4. **Mark the canvas.** Each node the wave closed carries its status and the commit.
+5. **Re-read the goal** ([`continuity.md`](continuity.md) → *The goal is re-read between
+   items, not only the board*). A re-plan is a committed `revisions` entry plus a canvas
+   edit, never a quiet change.
+6. **Re-measure the inventory and re-cut the remaining waves** from the updated target —
+   never from the original guess. New findings join the inventory with ids.
+
+## A board bigger than one release
+
+**It becomes a program.** The release takes the first waves; the rest stays on the
+canvas by node, `release: program`, never dropped. The next release resumes from the
+canvas: it re-measures the inventory rather than re-running wave 0 from nothing, and its
+waves are cut from the nodes still open.
+
+## What stays human
+
+Sign-ins, consents, payments, sending to people, and every outward or irreversible act.
+The mode removes *"shall I continue?"* between waves and *"what did you mean?"* where a
+source already says; it never removes a person from a decision that is theirs. A
+`manual` gate still waits for its go ([`continuity.md`](continuity.md) → *The limit,
+before the capability*).
+
+## The graph carries the wave
+
+The work graph ([`work-graph.md`](work-graph.md)) carries `wave` on a node, an integer from
+1. Three verbs read it:
+
+- `graph.py validate` refuses an edge from a later wave's node into an earlier wave's
+  node: an earlier wave that waits on a later one cannot close in its own pass.
+- `graph.py next --wave N` prints wave N's frontier only. Exit `3` says the wave is done,
+  `4` that nothing in it is runnable, `1` that no node is in wave N.
+- `graph.py wave N-007 --to 3 --why "<reason>"` moves a node and writes the revision.
+  It refuses a move that would break the order above.
+
+Without python3 the same three facts live in the wave plan's table, checked by hand and
+said to be checked by hand.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "Ship the simple version now, the real one later" | That is the intermediate state. Its removal is a second build nobody planned |
+| "Ask each question as it comes up" | Each one is a human round. Close it from the sources, or put it in the batch |
+| "The board is too big to inventory" | The inventory is the plan. Without it the waves are cut from memory |
+| "Re-cutting waves makes the pipeline dynamic" | A re-cut is a committed revision and a canvas edit. The static-graph decision in [`planning.md`](planning.md) holds |
+| "The recommendation is obviously right, so assume the deploy go" | An outward act is never assumed. Ask for the specific go once, in the batch |
+| "Wave 3 can stub what wave 5 will build properly" | Only at a declared contract, with wave 5 named as the stub's removal |

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

@@ -41,6 +41,7 @@ turn of every loop.
 | `nodes[].blocked_by` | what must PRODUCE first. The frontier obeys a satisfaction predicate, and only `done` satisfies — a PARKED producer blocks its consumer, because a park is a decision not to produce, not a production. `next` names each held consumer with the park's reason; a valid alternative producer is an explicit, versioned edge change, never an implicit unblock |
 | `nodes[].touches` | what it **mutates**. Two runnable nodes writing one file is the false parallelism [`planning.md`](planning.md) refuses — *distinct is not the same as independent, and the check is what they touch, never what they are called* |
 | `nodes[].check` | **how this node will be closed** — one command, or the named judgement where no command can decide it. Required on every node except a `parked` one. The certification's `unit` tier runs it and reports its output as the evidence row ([`certification.md`](certification.md) — three blind tiers close a node, not one reader); before this field existed that instruction pointed at an absence, leaving a verifier the two things it forbids — invent a check, or run everything (B-080) |
+| `nodes[].wave` | wave mode only ([`waves.md`](waves.md)): the pass of stages 5–8 that closes the node, from 1. **An earlier wave may not wait on a later one** — `validate` refuses the edge, because a wave holds only what closes in its own pass |
 | `nodes[].evidence` | required when `status` is `done`. A node called done by assertion is what evidence exists to prevent |
 | `nodes[].parked_reason` | required when `status` is `parked`. A park with no reason is indistinguishable, a week later, from work quietly dropped |
 | `edges[].payload` | what the dependency hands over. **An edge carrying no named artifact is chronology drawn as architecture** |
@@ -54,11 +55,12 @@ conditional on the code, never merely sequenced after it.**
 | Verb | Prints | Codes |
 |---|---|---|
 | `validate` | every violation, in a stable order | `0` clean · `1` any |
-| `next` | the frontier, ordered by how much each node unblocks — **and nothing else** | `0` printed · `3` all done · `4` nothing runnable |
+| `next` | the frontier, ordered by how much each node unblocks — **and nothing else**. `--wave N` narrows it to one wave, and `3` then means *this wave is done* | `0` printed · `3` all done · `4` nothing runnable · `1` with `--wave`, a wave no node is in |
 | `coverage` | each requirement with the nodes serving it | `0` covered · `1` a gap, named |
 | `goal` | the release goal | `0` · `3` unstated |
 | `add` | the id it allocated | `0` · `1` refused |
 | `park` | the id and the reason | `0` · `1` refused |
+| `wave` | wave mode's re-cut: the node, its old and new wave, and the reason, which enters the revision log. Refuses a move that would leave an earlier wave waiting on a later one, and a `done` node | `0` · `1` refused |
 | `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` |

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

@@ -191,7 +191,13 @@ def verify_parents(report, plan):
     return out
 
 
-LEAF_SCHEMA = "execution-packet/1"
+LEAF_SCHEMA = "task-pipeline/execution-packet/1"
+# Fabric's content-addressed packet was also `execution-packet/1` until Fabric renamed its
+# format `session-handoff/1` (fabric-agent-contract R-01). The namespace keeps the two from
+# being read as each other. The bare id is still READ, until no live packet carries it:
+# 19 packets in one consumer repository did on 2026-10-12 (backlog B-135); refusing it
+# before they are migrated would break them.
+LEGACY_LEAF_SCHEMAS = ("execution-packet/1",)
 COLD_READER_QUESTIONS = ("goal", "inputs", "decisions", "scope", "outputs",
                          "acceptance", "guards", "resume")
 SHA_RE_STR = r"^[0-9a-f]{64}$"
@@ -356,7 +362,7 @@ def leaf_readiness(leaf):
     problems = []
     if not isinstance(leaf, dict):
         return ["leaf: not an object"]
-    if leaf.get("schema_version") != LEAF_SCHEMA:
+    if leaf.get("schema_version") not in (LEAF_SCHEMA,) + LEGACY_LEAF_SCHEMAS:
         problems.append("schema_version: missing or unknown — an unversioned "
                         "packet fails readiness")
     answers = {

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

@@ -88,7 +88,7 @@ TERMINAL = {"done", "parked"}
 NO_GRAPH = {"producer", "doctrine"}
 # One place, and the schema enumerates the same three. Two homes for this set is
 # what let `close` write a verb the format forbade.
-REVISION_VERBS = {"add", "park", "close", "invalidate", "waive"}
+REVISION_VERBS = {"add", "park", "close", "invalidate", "waive", "wave"}
 # Parking a node PROMOTES its dependents: `parked` is terminal, so anything
 # blocked on it becomes runnable even though the payload it waited on never
 # arrived. That is deliberate — `can_continue_around` in the verdict is the
@@ -276,6 +276,13 @@ def violations(graph):
                        f"{', '.join(SURFACE_CLASSES)}. A class nobody recognises requires no "
                        "visual reading, so a typo here would drop the tier that reads the pixels")
 
+        # Wave mode (`references/waves.md`). `True` is an int in Python, and a wave of
+        # `true` is a typo the ordering check below would read as wave 1.
+        if "wave" in n and not _is_wave(n["wave"]):
+            out.append(f"{nid}: wave is {n['wave']!r} — it must be an integer from 1. A wave "
+                       "nobody can order is a node no `next --wave` ever prints, and the "
+                       "order check below cannot see it")
+
         if n.get("status") == "done":
             ev = n.get("evidence")
             if not isinstance(ev, list) or not [e for e in ev
@@ -322,6 +329,17 @@ def violations(graph):
                            "and a dependency handing over nothing is the one this check "
                            "exists to refuse")
 
+    # An earlier wave may not wait on a later one: a wave holds only what closes in one
+    # pass, and a node whose producer is scheduled after it cannot close in its own.
+    wave_of = {n.get("id"): n.get("wave") for n in nodes if _is_wave(n.get("wave"))}
+    for e in graph.get("edges") or []:
+        src, dst = e.get("from"), e.get("to")
+        if src in wave_of and dst in wave_of and wave_of[src] > wave_of[dst]:
+            out.append(f"edge {src}→{dst}: {src} is in wave {wave_of[src]} and {dst} in "
+                       f"wave {wave_of[dst]} — an earlier wave would wait on a later one, "
+                       "so it cannot close in its own pass (references/waves.md). Move "
+                       f"{dst} to wave {wave_of[src]} or later, or {src} earlier")
+
     for i, r in enumerate(graph.get("revisions") or []):
         if not isinstance(r, dict):
             out.append(f"revisions[{i}] is not an object")
@@ -603,6 +621,11 @@ TIERS = ("unit", "seam", "product")
 VISUAL_TIER = "visual"
 ALL_TIERS = TIERS + (VISUAL_TIER,)
 SURFACE_CLASSES = ("flagship", "product", "internal", "ad")
+
+
+def _is_wave(w):
+    """A wave is an integer from 1 — and never a bool, which Python counts as an int."""
+    return isinstance(w, int) and not isinstance(w, bool) and w >= 1
 VISUAL_REQUIRED = ("flagship", "product")
 TIER_KEYS = ("node", "tier", "verdict", "scope", "confirms", "findings",
              "evidence", "not_examined")
@@ -746,13 +769,24 @@ def cmd_next(graph, args):
     if violations(graph):
         die("graph does not validate — run `validate` first", 1)
     nodes = graph.get("nodes") or []
+    wave = getattr(args, "wave", None)
+    if wave is not None:
+        # One wave's frontier, and its own endings: `3` is *this wave is done*, which is
+        # the close pass's cue, not the release's (references/waves.md).
+        if not _is_wave(wave):
+            die("--wave %r is not a wave — waves are integers from 1" % wave, 2)
+        nodes = [n for n in nodes if n.get("wave") == wave]
+        if not nodes:
+            die("no node is in wave %d — nothing to walk, and an empty wave is a wave plan "
+                "and a graph that disagree" % wave)
     if nodes and all(n.get("status") in TERMINAL for n in nodes):
         return 3
-    ready = frontier(graph)
+    in_scope = {n.get("id") for n in nodes}
+    ready = [n for n in frontier(graph) if n.get("id") in in_scope]
     # A consumer whose producer is PARKED is not runnable and never will be by
     # itself (FIX-PF-04.01) — say so BEFORE the empty-frontier exit, or the one
     # moment the operator most needs the reason is the one moment it is silent.
-    _by_id = {n.get("id"): n for n in nodes}
+    _by_id = {n.get("id"): n for n in graph.get("nodes") or []}
     for n in nodes:
         if n.get("status") in TERMINAL or n.get("status") == "running":
             continue
@@ -1123,6 +1157,46 @@ def cmd_park(graph, args):
     return 0
 
 
+def cmd_wave(graph, args):
+    """Move one node to another wave, carrying the reason — wave mode's re-cut.
+
+    The re-cut after every wave is a plan revision, and a revision nobody recorded is
+    the dynamic graph `references/planning.md` refuses. So the move is a verb: it
+    writes the `revisions` entry, and it refuses a move that would leave an earlier
+    wave waiting on a later one (`references/waves.md`).
+    """
+    guard(graph, args.graph)
+    why = (args.why or "").strip()
+    if not why:
+        die("`wave` needs a --why with something in it: a re-cut nobody gave a reason for "
+            "is the quiet edit the revision log exists to refuse — nothing was written")
+    if any(c in why for c in "\n\r"):
+        die("--why contains a line break — nothing was written")
+    if not _is_wave(args.to):
+        die("--to %r is not a wave — waves are integers from 1. Nothing was written"
+            % args.to)
+    node = next((n for n in graph.get("nodes") or [] if n.get("id") == args.node), None)
+    if node is None:
+        die("no node %s in this graph — nothing was written" % args.node)
+    if node.get("status") == "done":
+        die("%s is done, in wave %s — moving it would rewrite which pass closed it. "
+            "Nothing was written" % (args.node, node.get("wave")))
+    if node.get("wave") == args.to:
+        die("%s is already in wave %d — nothing was written" % (args.node, args.to))
+
+    before = node.get("wave")
+    node["wave"] = args.to
+    revise(graph, "wave", args.node, why)
+    bad = violations(graph)
+    if bad:
+        die("moving %s to wave %d would break the graph — nothing was written:\n  %s"
+            % (args.node, args.to, "\n  ".join(bad)))
+    save(args.graph, graph)
+    print("%s: wave %s → %d: %s" % (args.node, before if before is not None else "none",
+                                     args.to, why))
+    return 0
+
+
 def next_id(known):
     """The next id, from the MAXIMUM rather than from the count.
 
@@ -1359,7 +1433,7 @@ def cmd_producer(graph, args):
 def cmd_doctrine(graph, args):
     """Which doctrine this run actually read — B-061.
 
-    The bundle is 39 reference files. A run reads some subset and nothing recorded which,
+    The bundle is 40 reference files. A run reads some subset and nothing recorded which,
     so **a skipped file and a read one were indistinguishable** — the class every guard in
     this repository exists to catch, left standing over the doctrine itself.
 
@@ -1825,6 +1899,7 @@ 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"),
+    "wave": (cmd_wave, "move a node to another wave, carrying the reason"),
     "certify": (cmd_certify, "require three independent tier reports (four on a "
                              "flagship or product surface), then emit the verdict "
                              "`close` consumes"),
@@ -1905,6 +1980,15 @@ def main(argv=None):
     made["waive"].add_argument("--by", required=True,
                                help="the identity that authorized the exception")
 
+    made["next"].add_argument("--wave", type=int, default=None,
+                              help="print only this wave's frontier; exit 3 when the wave "
+                                   "is done (references/waves.md)")
+    p_wave = made["wave"]
+    p_wave.add_argument("node")
+    p_wave.add_argument("--to", type=int, required=True, help="the wave to move it to")
+    p_wave.add_argument("--why", required=True,
+                        help="why the re-cut moved it — it enters the revision log")
+
     p_park = made["park"]
     p_park.add_argument("node")
     # `required=True` makes the MISSING flag a usage error (exit 2). The empty and
@@ -1916,7 +2000,7 @@ def main(argv=None):
     verbs = {k: v[0] for k, v in VERBS.items()}
     if args.verb in NO_GRAPH:
         return verbs[args.verb](None, args)
-    if args.verb in ("add", "park", "close", "certify", "invalidate", "waive"):
+    if args.verb in ("add", "park", "wave", "close", "certify", "invalidate", "waive"):
         # The READ happens inside the lock too. Loading first and locking second is the
         # same lost update with an extra step: the stale copy is already in memory.
         with held(args.graph):

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

@@ -69,9 +69,11 @@ def problems(packet):
         return ["the packet is not a JSON object"]
 
     version = str(packet.get("schema_version", ""))
-    m = re.match(r"^execution-packet/(\d+)$", version)
+    # Namespaced since 1.93.0 (Fabric's former packet id was the bare one); the bare form
+    # is still read until the live packets carrying it are migrated (backlog B-135).
+    m = re.match(r"^(?:task-pipeline/)?execution-packet/(\d+)$", version)
     if not m:
-        out.append(f"schema_version {version!r} is not 'execution-packet/<major>' — "
+        out.append(f"schema_version {version!r} is not 'task-pipeline/execution-packet/<major>' — "
                    "a packet without a mandatory version is unversioned, rejected")
     elif int(m.group(1)) not in KNOWN_MAJORS:
         out.append(f"schema_version major {m.group(1)} is unknown to this consumer "

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

@@ -265,7 +265,7 @@ def _self_test():
             print("FAIL  %s: %s" % (name, e))
 
     def pkt(node, targets=(), full=True):
-        p = {"schema_version": "execution-packet/1", "node": node,
+        p = {"schema_version": "task-pipeline/execution-packet/1", "node": node,
              "intent": "do the thing", "inputs": [{"address": "a", "sha256": "0" * 64}],
              "decision_refs": [{"address": "d", "sha256": "1" * 64}],
              "source_scope": {"edit_targets": list(targets)},

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

@@ -242,7 +242,13 @@ def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | Non
                 f"{f' (kept as {kept})' if kept else ''} — {_now()}")
         _append(ledger, line)
         return line
-    wid = answer.get("workflowId") or state.get("workflowId")
+    if answer.get("handoffId") and not answer.get("leaseId"):
+        # An offer: the lease stays with this run until the successor accepts.
+        line = f"event: memory — handoff offered {answer['handoffId']} — {_now()}"
+        _append(ledger, line)
+        return line
+    wid = (answer.get("workflowId") or (answer.get("checkpoint") or {}).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")
@@ -255,6 +261,49 @@ def record(ledger: pathlib.Path, answer_text: str | None, unavailable: str | Non
     return line
 
 
+def handoff(ledger: pathlib.Path, provider: str, model: str | None, reason: str,
+            ttl: int) -> dict:
+    """`observatory_handoff_create` arguments for a PLANNED change of executor (R11).
+
+    Without this the only way a workflow moved was a refusal: the next executor wrote,
+    got `LeaseLost`, and read the workflow after the fact. A planned move offers it
+    instead — the lease stays with this run until the successor accepts, and the pack
+    the successor receives is assembled by Observatory from the last checkpoint.
+    """
+    state = _load_state(ledger)
+    if not state.get("workflowId"):
+        raise SystemExit("stage_checkpoint: no workflow yet — write a checkpoint first "
+                         "(emit → observatory_checkpoint_write → record)")
+    to = {"provider": provider, **({"model": model} if model else {})}
+    # Observatory digests the whole request, TTL included, so the TTL is in the key (another
+    # TTL is another offer, not an idempotency conflict). So is the ledger's length: once an
+    # offer is recorded the ledger grows, and offering again after it lapsed is a new offer —
+    # the same key would replay the first, expired answer. A retry before recording repeats.
+    try:
+        seen = len(ledger.read_text(encoding="utf-8").splitlines())
+    except OSError:
+        seen = 0
+    key = hashlib.sha256(f"{state['workflowId']}\n{json.dumps(to, sort_keys=True)}\n{reason}"
+                         f"\n{ttl}\n{seen}".encode()).hexdigest()[:32]
+    args = {"owner": OWNER, "idempotencyKey": "tp-ho-" + key, "workflowId": state["workflowId"],
+            "to": to, "reason": reason, "offerTtlSeconds": ttl}
+    if state.get("leaseId"):
+        args["leaseId"] = state["leaseId"]
+    return args
+
+
+def accept(ledger: pathlib.Path, handoff_id: str, session: str | None) -> dict:
+    """`observatory_handoff_accept` arguments for the successor, before its first write."""
+    if not handoff_id.startswith("handoff:"):
+        raise SystemExit("stage_checkpoint: a handoff id starts with 'handoff:'")
+    args = {"owner": OWNER,
+            "idempotencyKey": "tp-ac-" + hashlib.sha256(handoff_id.encode()).hexdigest()[:32],
+            "handoffId": handoff_id}
+    if session:
+        args["sessionId"] = session
+    return args
+
+
 def main(argv: list[str]) -> int:
     p = argparse.ArgumentParser(prog="stage_checkpoint.py",
                                 description="A workflow checkpoint at every stage boundary.")
@@ -271,11 +320,29 @@ def main(argv: list[str]) -> int:
     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)
+    h = sub.add_parser("handoff", help="observatory_handoff_create arguments: a PLANNED executor change")
+    h.add_argument("--ledger", default=DEFAULT_LEDGER)
+    h.add_argument("--to-provider", required=True)
+    h.add_argument("--to-model")
+    h.add_argument("--reason", default="plan_route",
+                   choices=["limit", "plan_route", "operator", "crash", "restart"])
+    h.add_argument("--offer-ttl", type=int, default=3600)
+    ac = sub.add_parser("accept", help="observatory_handoff_accept arguments, before the first write")
+    ac.add_argument("--ledger", default=DEFAULT_LEDGER)
+    ac.add_argument("--handoff-id", required=True)
+    ac.add_argument("--session")
     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 == "handoff":
+        print(json.dumps(handoff(ledger, a.to_provider, a.to_model, a.reason, a.offer_ttl),
+                         ensure_ascii=False))
+        return 0
+    if a.cmd == "accept":
+        print(json.dumps(accept(ledger, a.handoff_id, a.session), 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")),

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

@@ -20,7 +20,7 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 39 reference files and nothing recorded which of them a run read, so **a
+The bundle is 40 reference files and nothing recorded which of them a run read, so **a
 skipped file and a read one were indistinguishable** — the class every guard in this
 pipeline exists to catch, left standing over the doctrine itself.
 
@@ -48,7 +48,7 @@ same claim one level down.
 |---|---|---|
 | `unmeasured — no run ledger` | there is no ledger | nothing to read from |
 | `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
-| `N of 39 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
+| `N of 40 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **It is a disclosure: no floor, no direction, never a target.** A run that needs four files
 and reads four is not worse than one that reads thirty — and the moment the number becomes