task-pipeline-skill 1.87.0 → 1.88.1

package/CHANGELOG.md

@@ -1,3 +1,83 @@
+## v1.88.1 — v1.88.0's payload, released with its no-stamp declaration
+
+The same payload as `v1.88.0`: the stage-boundary checkpoint writer, `scripts/stage_checkpoint.py`
+(PB-137 N-024). `release.yml` refused the `v1.88.0` tag's tree because that version was named
+nowhere in `docs/evidence/retro.md` → *Releases that carry no stamp*. Nothing published under
+it. This release names both versions there first, and its tag was cut locally before
+`npm run test:all` ran against its tree (`R-010`).
+
+## v1.88.0 — a stage boundary leaves a checkpoint the next executor can continue from
+
+The run ledger survives a compaction. It does not survive a quota that ran out on another
+account, or a run continued by a different agent. When the host has Project Observatory's
+memory tools (`observatory_checkpoint_write`, or `memory.checkpoint.write` under
+memory/0.1), every gate that returns now also writes a workflow checkpoint. Without the
+tools, nothing changes except one ledger line. This is PB-137 N-024 of the agent-memory
+program.
+
+- **`scripts/stage_checkpoint.py`** ships in the bundle and needs only the standard library.
+  It never talks to Observatory itself: `emit` builds the tool's arguments from the ledger,
+  and `record` keeps the answer.
+  - `emit` takes the run's topic as the goal, the verdicts as `done`, and the next stage
+    (named from `pipeline.example.json`) as `open`. Operator constraints and key *names*
+    are given once and carried to every later boundary.
+  - The idempotency key comes from the exact `stage:` line, so a retry replays and a stage
+    that runs again is a new checkpoint.
+  - `record` keeps `workflowId` and `leaseId` in `.task-pipeline/memory.json` (0600,
+    git-ignored). On a `LeaseLost` refusal it drops the token, so a stale writer stops
+    after one refusal.
+  - `record --unavailable` appends one `event: memory — unavailable` line and exits 0.
+- **`references/continuity.md` → Part 3** says when and how to write the checkpoint, and
+  what it is not: a second ledger, or the narrative.
+- **`event:` gains the `memory` kind** in `templates/run.md` and `references/progress.md`,
+  written by the script rather than the hook.
+- **`test/stage_checkpoint_test.py`** (39 cases), run by `npm test` and `test:all`:
+  - a boundary built from the ledger;
+  - retry versus repeat;
+  - continuation across boundaries, with the token absent from every output;
+  - provider loss;
+  - a stale writer and its successor;
+  - credentials by name only;
+  - a failed gate stays open and acceptance closes;
+  - no ledger.
+- **A live receipt against the Observatory engine** (main after PR #159, 7 of 7):
+  - the first write starts a workflow;
+  - a retry replays;
+  - `memory.checkpoint.write` continues it, with the constraints carried;
+  - after a handoff the old writer is refused `LeaseLost` and drops its token;
+  - no token reaches the ledger.
+
+  It also found the one defect fixed before release: constraints were lost after the
+  first boundary.
+
+## v1.87.1 — the SessionEnd timeout no host gave
+
+Codex 0.157 prints `clamping SessionEnd hook timeout to 3s in …/task-pipeline/…/hooks.json`
+at every session start. `hooks.json` declared 10 s for `run-lifecycle.sh`; Codex clamps a
+SessionEnd handler to 3 s, and Claude Code sizes its SessionEnd wait from the largest
+handler timeout. The script already fitted: it appends one line, and its own header states
+the 1.5-second budget. So the number was the only defect, and a warning on every Codex
+start the only cost.
+
+Guards: 429 → **430**.
+
+- **`hooks/hooks.json` declares `timeout: 3`** for SessionEnd. `test/validate.py` now reads
+  the plugin's OWN hooks file, which it never checked before (only the template), and holds
+  it and `templates/hooks.example.json` to a 3 s SessionEnd cap. The new negative step
+  plants the shipped 10 through `test/plant_sessionend_timeout.py`, which asserts that the
+  plant landed.
+- **`validate.yml` gets room again, 512 419 → 506 050 bytes.** The new step on its own
+  pushed the workflow past GitHub's 512 000-byte limit, where it stays `active` and never
+  runs. The largest inline plant (*a release MENTIONED but not declared*, 7.9 kB) moved
+  verbatim into `test/plant_gap_mention.py`, with the same exit-9 skip. It is watched
+  rejecting its planted defect through `test/negatives.py -k MENTIONED`.
+- **The dormancy guard reads the script a step calls.** Moving that plant took its `SKIP:`
+  branch out of the step text, and `anchors.py` read only the step. So it stopped calling
+  the step skip-capable, and deleting its `# dormant-when:` passed. `test:all` caught this
+  through *a plant that can decline to run and never says when*. `Step.skip_capable` now
+  also follows `python3 test/plant_*.py` into the file. A new `anchors_test.py` case is red
+  without the fix.
+
 ## v1.87.0 — stage 4 stops handing over a plan the next agent cannot execute
 
 The operator's finding, 2026-09-13: **agents change between sessions, and whatever a

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.87.0 |
+| **Version** | 1.88.1 |
 | **Surface** | Claude Code (filesystem skill + plugin) and the vercel `skills` CLI. **Not** uploaded to the Skills API; custom Skills do not sync across surfaces |
 | **Dependencies** | None required. Optional: `context7` (MCP), `figma` (MCP), super-ux, agent-sync, graphify, obsidian-wiki, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.87.0",
+  "version": "1.88.1",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"
   },
   "scripts": {
-    "test": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && npm run test:audit-regressions",
-    "test:all": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/negatives.py && npm run test:certify && npm run test:exposure && npm run test:probe && npm run test:anchors && npm run test:runner && npm run test:hooks && npm run test:artifacts && npm run test:docs && npm run test:audit-regressions",
+    "test": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/stage_checkpoint_test.py && npm run test:audit-regressions",
+    "test:all": "python3 test/validate.py && python3 test/graph_test.py && python3 test/project_audit_test.py && python3 test/packet_schema_test.py && python3 test/browser_claims_test.py && python3 test/stage_checkpoint_test.py && python3 test/negatives.py && npm run test:certify && npm run test:exposure && npm run test:probe && npm run test:anchors && npm run test:runner && npm run test:hooks && npm run test:artifacts && npm run test:docs && npm run test:audit-regressions",
     "test:negatives": "python3 test/negatives.py",
     "test:exposure": "python3 test/exposure_test.py",
     "test:probe": "python3 test/probe.py --self-test",

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "task-pipeline",
   "displayName": "Task Pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/judgment/manual gates, a frozen requirement spine that closes with evidence, a work board and a verification ledger that outlive a run, an exposure line naming what shipped unconfirmed, a progress rail computed from the project's own config, a loop guard whose review ceiling measures rather than stops, and stage-3 tracks for what a product does, how it sounds and how it looks. Two modes need no task: `checkup` (what is unverified) and `setup` (audit existing docs). Retro insights can publish upstream as issues, opt-in and redacted.",
-  "version": "1.87.0",
+  "version": "1.88.1",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/hooks/hooks.json

@@ -83,7 +83,7 @@
             "type": "command",
             "shell": "bash",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
-            "timeout": 10
+            "timeout": 3
           }
         ]
       }

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

@@ -20,6 +20,7 @@ almost no window left, loses the middle of it, and re-derives what it already di
 - The evidence rule
 - What happens at the signal
 - The flush is not a new document
+- Part 3 — workflow memory at the stage boundary
 - Rationalizations
 
 ## The limit, before the capability
@@ -305,6 +306,22 @@ copy of the truth, it is written once, nobody updates it, and the next run reads
 it as current. The artifacts above are read by later stages anyway; making them
 right costs nothing extra and pays twice.
 
+## Part 3 — workflow memory at the stage boundary
+
+The ledger survives a compaction. It does not survive a quota that ran out on another
+account, or a run picked up by a different agent on another machine. When the host has
+Project Observatory's memory tools, **every gate that returns also writes a workflow
+checkpoint**, and the next executor continues from the last finished stage.
+
+- **When.** After the `stage:` line is appended, every time a gate returns, whatever the verdict. A failed gate's checkpoint says `blocked` and keeps the stage open. Acceptance closes the workflow.
+- **How.** `scripts/stage_checkpoint.py emit` prints the tool's arguments, built from the ledger alone: the topic, the verdicts, the next stage, the operator's constraints and key names. Pass them to `observatory_checkpoint_write`, or to `memory.checkpoint.write` under memory/0.1. Then hand the answer to `stage_checkpoint.py record --answer -`.
+- **The constraints.** Give the brief's restrictive rules once, as `--constraint`. They are carried to every later boundary, and a successor reads them first.
+- **Keys.** Pass keys by name, as `--credential PROJECT/ENV/NAME`, never as a value.
+- **Without the tools.** `stage_checkpoint.py record --unavailable "<why>"` appends one `event: memory — unavailable` line, and the run continues exactly as before. Missing memory is a state the ledger names, not a failure.
+- **A refusal.** `LeaseLost` means another executor holds the workflow now. The script drops the token. Read the workflow (`observatory_checkpoint_latest` with `stage_checkpoint.py state`'s id) before doing anything else. A stale writer stops after one refusal.
+- **The lease token.** It lives in `.task-pipeline/memory.json` (mode 0600, git-ignored) and never in the ledger, a reply or a commit.
+- **What this is not.** Not a second ledger and not the narrative. The checkpoint is the work's state for the next executor. The wiki and the ledger keep everything else.
+
 ## Rationalizations
 
 | Excuse | Reality |

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

@@ -396,9 +396,13 @@ again, and it looks like enforcement while being a mirror.
 Three moments the rail cannot show, recorded by `hooks/run-lifecycle.sh` as
 
 ```
-event: <compact|session-end|subagent> — <detail> — <ISO-8601>
+event: <compact|session-end|subagent|memory> — <detail> — <ISO-8601>
 ```
 
+The fourth kind, `memory`, is appended by `scripts/stage_checkpoint.py` rather than
+by the hook. It records a workflow checkpoint written at a stage boundary, a refusal,
+or that memory was unavailable ([`continuity.md`](continuity.md) → *Part 3*).
+
 The rail reads none of them; `checkup` reads `session-end`, which is how an
 abandoned run stops being invisible. Before this the ledger simply stopped at
 whatever stage the session died on — and a stopped ledger is indistinguishable

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

@@ -0,0 +1,272 @@
+#!/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 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*`([^`]+)`")
+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 _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]))
+    done = [{"step_id": f"stage-{s[0]}", "result": f"{s[1]}: gate {s[2]}, verdict {s[3]} at {s[4]}",
+             "evidence": [f"ledger: {ledger.name}"]} for s in stages if s[3] in ("pass", "skip")]
+    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:]))

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

@@ -69,7 +69,7 @@ hand:  <N|10> — task "<quoted>" — done <n> — surfaced <n> — decisions <n
        scope <commit>/<env>/<REQ ids> — unverified <n|none-in-scope> (<what, or the literal>)
 holds: <stage id> — <n> (<class: what, owner>; … or "none") — enumerated <n>/8 classes, <unlooked: classes not enumerable>
 gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
-event: <compact|session-end|subagent> — <detail> — <ISO-8601>
+event: <compact|session-end|subagent|memory> — <detail> — <ISO-8601>
 read:  references/<file>.md            # hook-appended, deduped, UNATTESTED (no writer field)
 ```