task-pipeline-skill 1.50.0 → 1.52.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## v1.52.0 — the three moments the run's own record could not show
+
+### Added
+
+- **`hooks/run-lifecycle.sh`** — one line shape for three events the ledger was
+  blind to:
+
+  ```
+  event: <compact|session-end|subagent> — <detail> — <ISO-8601>
+  ```
+
+  - `compact` marks the boundary **the ledger exists because of** —
+    `templates/run.md` says so in its own header, and until now that boundary was
+    the one thing the file could not show. A resumed run could not tell "the
+    context was compacted here" from "nothing happened".
+  - `session-end` marks a run whose session ended without reaching acceptance.
+    That is precisely what `/task-pipeline checkup` looks for, and it was
+    invisible: the ledger simply stopped, which is indistinguishable from a run
+    still in progress. A run that *did* reach acceptance is not filed as
+    abandoned, or the report fills with runs that closed exactly as intended.
+  - `subagent` records one finishing, so the `hand:` count has something to be
+    checked against other than itself.
+
+  **It never writes a `hand:` line, and that is not a shortcut.** That shape
+  carries `done`, `surfaced`, `decisions` and `amb` — judgements only the agent
+  holds. A hook filling them in would fabricate the evidence the line exists to
+  provide. It records what it can see and leaves the accounting to whoever can
+  account.
+
+  One shape rather than three: a ledger grammar is read by four documents and
+  several hooks, and every shape added is a shape each of them must learn.
+
+- **`hooks/build-gate.sh`** — editing the product before the plan is agreed now
+  asks. Stage 5 is where code is written; editing during intake, docs, brainstorm,
+  spec or plan is the pipeline's discipline being skipped, and it is the skip
+  nobody notices because the work looks like progress.
+
+  `ask`, never `deny`: the routing boundary says a typo, a one-line fix or a
+  mechanical rename never went through the pipeline anyway, and no hook can tell a
+  typo from a feature. **The build stage is resolved by role, never by number** —
+  the same lesson v1.51.0 learned from the release gate, applied before it could
+  be repeated. **The pipeline's own artefacts are never gated**: `docs/`,
+  `.task-pipeline/`, README and CHANGELOG are what stages 0-4 are *for*.
+
+Guards: 311 → **312**. Property checks: 9 → 9. The release-gate suite is 29 → 43
+fixtures, all run as processes.
+
+## v1.51.0 — the gate stopped being keyed to a number, and stopped believing the agent
+
+### Fixed
+
+- **v1.50.0's release gate blocked every release forever in any project whose flow
+  has no stage 6.** It matched `stage: 6` literally. A six-stage project with tests
+  green at stage 4 could never tag anything again — and this file's own
+  `progress.md` says the rail "is computed, never eleven" for exactly this reason:
+  a host project replaces the flow. A wrong rail misinforms; a wrong gate stops the
+  work. Reproduced against a six-stage project before it was fixed.
+
+  The tests stage is now resolved from `pipeline.json` — a stage whose `state` is
+  `tests`, or one declaring `gate.command` — and failing that from the ledger by
+  name. When it cannot be resolved the gate still refuses, because a run is in
+  flight and nothing in it reports a suite passing, but the reason now says how to
+  make the flow readable.
+
+### Added
+
+- **`hooks/gate-observer.sh` — the observation the gate rests on.**
+  `stage: … verdict pass` is typed by the agent the release gate constrains, so on
+  its own the gate confirmed an assertion with the same assertion. The observer
+  records the **observed** exit code of the command the project declared, as a new
+  ledger line:
+
+  ```
+  gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
+  ```
+
+  and the release gate requires the claim and the observation to agree. It records
+  a red run as a red run — a hook that hid one would read as "the suite was never
+  run", which is the opposite of what happened. Only the declared command is
+  observed, compared on the normalised command line: `echo "npm test"` and
+  `npm test --watch` are not the project's gate, and treating them as one puts a
+  fabricated observation in the file the gate trusts.
+
+  **No `gate.command` declared → the gate degrades to the claim alone.** Stated
+  here rather than discovered.
+
+  **The LAST observation, not any of them.** "Some run of the suite was green" is
+  true of almost every repository that has ever been red, and a gate satisfied by
+  history rather than by current state is satisfied permanently. Found by running
+  the observer against this pipeline's own ledger, where an earlier green sat
+  above a later red and the gate waved it through.
+
+Guards: 310 → **311**. Property checks: 9 → 9. The new guard disarms the
+corroboration — it makes the gate accept the claim alone — and requires the suite
+to notice; `test/negatives.py`'s floor moved with it in the same change. The
+release-gate suite is 16 → 29 fixtures, all run as processes.
+
 ## v1.50.0 — the stage-7 gate stops being a sentence somebody reads
 
 ### Added

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.50.0 |
+| **Version** | 1.52.0 |
 | **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. 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,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "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"

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

@@ -2,7 +2,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/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.50.0",
+  "version": "1.52.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/hooks/build-gate.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# PreToolUse — editing the product before the plan is agreed.
+#
+# `stages.md` says no stage advances until its gate passes, and stage 5 is where
+# code gets written. Editing the product during intake, docs, brainstorm, spec or
+# plan is the pipeline's own discipline being skipped — and it is the skip nobody
+# notices, because the work looks like progress.
+#
+# **`ask`, never `deny`, and the reason is this file's own doctrine.** The routing
+# boundary says a typo, a one-line edit or a mechanical rename does not go through
+# the pipeline, and no hook can tell a typo from a feature. A refusal here would
+# fight the honest cases daily and be removed inside a week; a question answered
+# once costs a keystroke.
+#
+# **The build stage is resolved by ROLE, never by number.** v1.50.0 matched
+# `stage: 6` literally and blocked every release in a six-stage project; the same
+# mistake here would put a prompt in front of every edit in any project whose flow
+# is numbered differently. `pipeline.json` → a stage whose `state` is `build`, else
+# one whose name says build. Unresolvable → silence, because a question nobody can
+# act on is worse than none.
+#
+# **The pipeline's own artefacts are never gated.** Stages 0-4 exist to WRITE
+# things — the brief, the spec, the plan, the ledger. A gate that asked about those
+# would fire on the very work it is protecting.
+set -uo pipefail
+
+input=$(cat 2>/dev/null || true)
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+ledger="$project/.task-pipeline/run.md"
+[ -f "$ledger" ] || exit 0
+
+HOOK_INPUT="$input" python3 - "$ledger" "$project" <<'PY' 2>/dev/null || exit 0
+import json, os, re, sys
+
+ledger, project = sys.argv[1], sys.argv[2]
+try:
+    data = json.loads(os.environ.get("HOOK_INPUT", ""))
+except Exception:
+    raise SystemExit(0)
+
+ti = data.get("tool_input") or {}
+path = ti.get("file_path") or ti.get("notebook_path") or ""
+if not path:
+    raise SystemExit(0)
+
+rel = os.path.relpath(path, project) if os.path.isabs(path) else path
+rel = rel.replace(os.sep, "/")
+# The run writes these; gating them would fire on the work stages 0-4 are for.
+if rel.startswith("..") or re.match(r"^(docs/|\.task-pipeline/|\.claude/|CHANGELOG\.md|README\.md)", rel):
+    raise SystemExit(0)
+
+try:
+    text = open(ledger, encoding="utf-8").read()
+except Exception:
+    raise SystemExit(0)
+
+stage_lines = [l.strip() for l in text.splitlines() if l.strip().startswith("stage:")]
+if not stage_lines:
+    raise SystemExit(0)
+
+
+def build_stage_id():
+    """By role, never by number — the mistake v1.50.0 shipped in the release gate."""
+    try:
+        cfg = json.load(open(os.path.join(project, "pipeline.json"), encoding="utf-8"))
+        for s in cfg.get("stages") or []:
+            if isinstance(s, dict) and s.get("state") == "build":
+                return str(s.get("id"))
+    except Exception:
+        pass
+    for l in stage_lines:
+        m = re.match(r"stage:\s*(\S+)\s+([^—]*)", l)
+        if m and re.search(r"build|dev\b", m.group(2), re.I):
+            return m.group(1)
+    return None
+
+
+build_id = build_stage_id()
+if build_id is None:
+    raise SystemExit(0)          # unresolvable: a question nobody can act on
+
+# Has the run entered the build stage at all? Entering is enough — the gate is
+# about editing BEFORE the plan is agreed, not about the build's own verdict.
+entered = any(re.match(r"stage:\s*%s\b" % re.escape(build_id), l) for l in stage_lines)
+if entered:
+    raise SystemExit(0)
+
+last = stage_lines[-1]
+m = re.match(r"stage:\s*(\S+)\s+([^—]*)", last)
+now = "%s %s" % (m.group(1), m.group(2).strip()) if m else "an early stage"
+
+print(json.dumps({"hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "ask",
+    "permissionDecisionReason":
+        "This run is at stage %s and has not entered the build stage (%s). Editing "
+        "the product before the plan is agreed is the pipeline's own discipline "
+        "being skipped — and it is the skip nobody notices, because the work looks "
+        "like progress.\n\n"
+        "Allow if this is a typo, a one-line fix or a mechanical rename, which the "
+        "routing boundary says never went through the pipeline anyway. Otherwise "
+        "finish the plan and record stage %s in %s.\n\n"
+        "The pipeline's own artefacts — docs/, .task-pipeline/, README, CHANGELOG — "
+        "are never gated." % (now, build_id, build_id, ledger),
+}}))
+PY
+exit 0

package/plugins/task-pipeline/hooks/gate-observer.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# PostToolUse — record what the gate command actually did.
+#
+# `stage: 6 tests — gate manual — verdict pass` is typed by the agent. The stage-7
+# release gate reads that line, so on its own it corroborates a claim with the same
+# claim, made by the party it constrains. Nothing in the pipeline observed the
+# suite; it observed a sentence about the suite.
+#
+# This appends the observation:
+#
+#     gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
+#
+# and `release-gate.sh` then requires the claim and the observation to agree.
+#
+# **Only a command the project declared.** `pipeline.json` → the stage whose
+# `gate.command` is set. Nothing is guessed from the shape of a command line: a
+# heuristic over strings the environment also produces is `learned.md` rule 15,
+# and a gate built on one would record `npm test` from a `README` example.
+#
+# **It records, it never judges.** A failing run is written down as a failing run.
+# A hook that quietly declined to record a red result would be worse than no hook,
+# because the absence would read as "the suite was never run".
+#
+# Silent everywhere else: no ledger, no declaration, no match — exit 0 having done
+# nothing, so enabling this plugin changes nothing in a repository that is not
+# running a pipeline.
+set -uo pipefail
+
+input=$(cat 2>/dev/null || true)
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+ledger="$project/.task-pipeline/run.md"
+[ -f "$ledger" ] || exit 0
+
+HOOK_INPUT="$input" python3 - "$ledger" "$project" <<'PY' 2>/dev/null || true
+import json, os, re, sys, datetime
+
+ledger, project = sys.argv[1], sys.argv[2]
+try:
+    data = json.loads(os.environ.get("HOOK_INPUT", ""))
+except Exception:
+    raise SystemExit(0)
+
+cmd = ((data.get("tool_input") or {}).get("command") or "").strip()
+if not cmd:
+    raise SystemExit(0)
+
+try:
+    cfg = json.load(open(os.path.join(project, "pipeline.json"), encoding="utf-8"))
+except Exception:
+    raise SystemExit(0)
+
+target = None
+for s in cfg.get("stages") or []:
+    if isinstance(s, dict) and (s.get("gate") or {}).get("command"):
+        target = (str(s.get("id")), (s.get("gate") or {})["command"].strip())
+        break
+if not target:
+    raise SystemExit(0)
+
+stage_id, declared = target
+
+# Compared on the normalised command line, not on a substring: `echo "npm test"`
+# and `npm test --watch` are not the project's gate, and treating them as one puts
+# a fabricated observation in the ledger the release gate trusts.
+def norm(s):
+    return " ".join(s.split())
+
+if norm(cmd) != norm(declared):
+    raise SystemExit(0)
+
+# PostToolUse fires on success; PostToolUseFailure carries the error. Both are
+# wired to this script, and `error` present means the command did not exit 0.
+failed = bool(data.get("error")) or data.get("hook_event_name") == "PostToolUseFailure"
+out = data.get("tool_output") or {}
+if isinstance(out, dict) and out.get("exit_code") is not None:
+    code = int(out["exit_code"])
+else:
+    code = 1 if failed else 0
+
+stamp = datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+line = 'gate:  %s — command "%s" — exit %d — %s\n' % (stage_id, norm(declared), code, stamp)
+
+# Append-only, like every other line in this file. A ledger that is rewritten is a
+# ledger whose history can be edited to say the suite passed.
+with open(ledger, "a", encoding="utf-8") as fh:
+    fh.write(line)
+PY
+exit 0

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

@@ -1,5 +1,5 @@
 {
-  "description": "task-pipeline — the stage-7 gate, enforced at agent time. Every hook exits 0 immediately when the project has no .task-pipeline/run.md, so installing the plugin globally changes nothing in a repository that is not running a pipeline.",
+  "description": "task-pipeline — the gates and the observations they rest on. Every hook exits 0 immediately when the project has no .task-pipeline/run.md, so installing the plugin globally changes nothing in a repository that is not running a pipeline.",
   "hooks": {
     "PreToolUse": [
       {
@@ -9,10 +9,83 @@
             "type": "command",
             "shell": "bash",
             "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/release-gate.sh\"",
-            "statusMessage": "stage 7: has stage 6 passed?",
+            "statusMessage": "has the tests gate passed?",
             "timeout": 20
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/build-gate.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/gate-observer.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/gate-observer.sh\"",
+            "timeout": 20
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-lifecycle.sh\"",
+            "timeout": 10
+          }
+        ]
       }
     ]
   }

package/plugins/task-pipeline/hooks/release-gate.sh

@@ -2,9 +2,9 @@
 # PreToolUse — the stage-7 gate, made mechanical.
 #
 # `stages.md` already says a release does not leave stage 7 until the full suite
-# is green at stage 6. Until now that was a sentence an agent reads and a person
-# hopes was obeyed; the tag is public before anybody can check. This refuses the
-# irreversible act while the run's own ledger records no passing stage 6.
+# is green at the tests stage. Until now that was a sentence an agent reads and a
+# person hopes was obeyed; the tag is public before anybody can check. This
+# refuses the irreversible act while the run's own ledger says otherwise.
 #
 # THREE DELIBERATE NARROWNESSES, each one the difference between a gate people
 # keep and a gate people rip out:
@@ -15,8 +15,28 @@
 #   2. Only in a project that is running a pipeline. No `.task-pipeline/run.md`
 #      means exit 0 before anything else is read, so installing this plugin
 #      changes nothing anywhere else.
-#   3. Only what the ledger SAYS. Nothing here reruns a suite or believes a
-#      claim; `progress.md` makes the ledger append-only, and this reads it.
+#   3. Only what the ledger SAYS, plus what a hook OBSERVED. Nothing here reruns a
+#      suite.
+#
+# WHICH STAGE IS THE TESTS STAGE IS NOT A CONSTANT, and v1.50.0 shipped it as one.
+# It matched `stage: 6` literally, so a project whose flow has six stages — tests
+# at stage 4, everything green — could never tag anything again. The pipeline's own
+# `progress.md` says the rail "is computed, never eleven" because a host project
+# replaces the flow; a gate keyed to a stage number is the same error with worse
+# consequences, because a wrong rail misinforms and a wrong gate stops the work.
+# The stage is now resolved from `pipeline.json` (a stage whose `state` is `tests`,
+# or one declaring `gate.command`), and failing that from the ledger by name. When
+# it cannot be resolved at all the gate still REFUSES — a run is in flight and
+# nothing in it reports a suite passing, and "we could not tell, so we let it go"
+# is exactly what a release gate exists to refuse — but the reason says how to make
+# the flow readable, because a refusal with no next step is one that gets removed.
+#
+# AND THE CLAIM IS CORROBORATED. `stage: … verdict pass` is typed by the agent this
+# gate constrains, so on its own the gate confirms an assertion with itself. Where
+# the stage declares `gate.command`, `hooks/gate-observer.sh` records the OBSERVED
+# exit code of that command as a `gate:` line, and both must agree. Declare no
+# command and the gate degrades to the claim alone — stated here rather than
+# discovered.
 #
 # Exit 2 blocks the call and shows stderr as the reason. Any other non-zero code
 # is NON-blocking in Claude Code, so an internal failure exits 2 as well: a
@@ -33,10 +53,10 @@ decide() {
   # stdin for `python3 -`, so a script fed that way can never also read the hook's
   # JSON from there. Watched failing — the gate allowed every release, silently,
   # because `sys.stdin.read()` came back empty and an empty payload is a skip.
-  HOOK_INPUT="$input" python3 - "$ledger" <<'PY'
+  HOOK_INPUT="$input" python3 - "$ledger" "$project" <<'PY'
 import json, shlex, sys, os, re
 
-ledger = sys.argv[1]
+ledger, project = sys.argv[1], sys.argv[2]
 raw = os.environ.get("HOOK_INPUT", "")
 try:
     data = json.loads(raw)
@@ -49,6 +69,7 @@ try:
 except ValueError:
     tokens = cmd.split()
 
+
 def outward(tokens):
     """Is this an act that other people can see the moment it succeeds?"""
     low = [t.lower() for t in tokens]
@@ -69,7 +90,6 @@ def outward(tokens):
                 sub = rest[j]
                 args = rest[j + 1:]
                 if sub == "tag" and not any(a in ("-d", "--delete", "-l", "--list") for a in args):
-                    # A bare `git tag` lists; a tag with a name creates one.
                     if any(not a.startswith("-") for a in args):
                         return "git tag"
                 if sub == "push":
@@ -83,6 +103,7 @@ def outward(tokens):
             return "npm publish"
     return None
 
+
 act = outward(tokens)
 if not act:
     print("skip"); raise SystemExit(0)
@@ -97,17 +118,76 @@ except Exception:
     # gate cannot tell. Fail closed, and say which file to look at.
     print("block\t%s\tthe run ledger could not be read" % act); raise SystemExit(0)
 
-passed = False
-for line in text.splitlines():
-    line = line.strip()
-    if not line.startswith("stage:"):
-        continue
-    m = re.match(r"stage:\s*6\b", line)
-    if m and re.search(r"verdict\s+pass", line):
-        passed = True
+stage_lines = [l.strip() for l in text.splitlines() if l.strip().startswith("stage:")]
+
+
+def declared_test_stage():
+    """The tests stage, from the project's own flow. `(id, command)` or None."""
+    try:
+        cfg = json.load(open(os.path.join(project, "pipeline.json"), encoding="utf-8"))
+    except Exception:
+        return None
+    for s in cfg.get("stages") or []:
+        if not isinstance(s, dict):
+            continue
+        gate = s.get("gate") or {}
+        if s.get("state") == "tests" or gate.get("command"):
+            return (str(s.get("id")), gate.get("command"))
+    return None
+
+
+def ledger_test_stage():
+    """Failing a declaration, the stage the ledger itself calls the tests one."""
+    for l in stage_lines:
+        m = re.match(r"stage:\s*(\S+)\s+([^—]*)", l)
+        if m and re.search(r"test", m.group(2), re.I):
+            return (m.group(1), None)
+    return None
+
+
+found = declared_test_stage() or ledger_test_stage()
+if not found:
+    # A run is in flight and NOTHING in it reports a suite passing. Blocking is
+    # right — the alternative reads as "we could not tell, so we let it go", which
+    # is what a release gate exists to refuse. The reason says how to be readable.
+    print("block\t%s\tno stage in this run reports the suite passing; declare "
+          "the tests stage as `\"state\": \"tests\"` in pipeline.json, or record "
+          "it in the ledger with `test` in its name" % act)
+    raise SystemExit(0)
+
+stage_id, command = found
+
+claimed_at = None
+for i, l in enumerate(stage_lines):
+    if re.match(r"stage:\s*%s\b" % re.escape(stage_id), l) and re.search(r"verdict\s+pass", l):
+        claimed_at = i
         break
 
-print("ok\t%s" % act if passed else "block\t%s\tno `stage: 6 … verdict pass` line in the ledger" % act)
+if claimed_at is None:
+    print("block\t%s\tno `stage: %s … verdict pass` line in the ledger" % (act, stage_id))
+    raise SystemExit(0)
+
+# The claim is the agent's. Where the project declared the command, an observation
+# by a hook must agree with it — otherwise the gate corroborates an assertion with
+# the same assertion.
+if command:
+    observed = [l.strip() for l in text.splitlines()
+                if re.match(r"gate:\s*%s\b" % re.escape(stage_id), l.strip())]
+    if not observed:
+        print("block\t%s\tthe ledger claims stage %s passed, and no hook observed "
+              "`%s` running — the claim is the agent's own" % (act, stage_id, command))
+        raise SystemExit(0)
+    # THE LAST observation, not any of them. "Some run of the suite was green" is
+    # true of almost every repository that has ever been red, and a gate satisfied
+    # by history rather than by the current state is satisfied permanently. Found
+    # by running the observer against this pipeline's own ledger, where an earlier
+    # green sat above a later red and the gate waved it through.
+    if not re.search(r"—\s*exit\s+0\b", observed[-1]):
+        print("block\t%s\tthe most recent observed run of `%s` did not exit 0"
+              % (act, command))
+        raise SystemExit(0)
+
+print("ok\t%s" % act)
 PY
 }
 
@@ -129,11 +209,11 @@ case "$state" in
   skip|ok) exit 0 ;;
   block)
     cat >&2 <<EOF
-task-pipeline: \`$act\` is an outward, irreversible act and stage 6 has not passed
-in this run — $why.
+task-pipeline: \`$act\` is an outward, irreversible act and the tests gate has not
+passed in this run — $why.
 
 The tag is public the moment it lands; reading the verdict afterwards is not a
-gate. Run the full suite, record stage 6 in $ledger, then release.
+gate. Run the full suite, record the tests stage in $ledger, then release.
 
 To release deliberately without the pipeline, remove the ledger or say
 «без пайплайна» and take the route by hand.

package/plugins/task-pipeline/hooks/run-lifecycle.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+# PreCompact · SessionEnd · SubagentStop — the three moments the run's own record
+# cannot see, written down as they happen.
+#
+# One line shape for all three:
+#
+#     event: <kind> — <detail> — <ISO-8601>
+#
+# **Why one shape and not three.** A ledger grammar is read by four documents and
+# two hooks; every shape added is a shape each of them must learn. These three are
+# the same kind of fact — something happened to the RUN rather than to a stage —
+# and a `kind` field costs one word against three grammars.
+#
+# WHAT EACH ONE IS FOR
+#
+#   compact      — the ledger exists because compaction happens; `templates/run.md`
+#                  says so in its own header. Until now the boundary itself was the
+#                  one event the file could not show, so a resumed run could not
+#                  tell "the context was compacted here" from "nothing happened".
+#   session-end  — a run whose session ended without reaching acceptance is
+#                  ABANDONED, and abandoned runs are exactly what
+#                  `/task-pipeline checkup` exists to surface. Before this they
+#                  were invisible: the ledger simply stopped, which looks identical
+#                  to a run still in progress.
+#   subagent     — stage 5 dispatches implementers as subagents, and the `hand:`
+#                  line counts them. Both sides of that count are written by the
+#                  same agent from the same memory, so the audit comparing them
+#                  compares a number with itself.
+#
+# **It does NOT write `hand:` lines, and that is not a shortcut.** That shape
+# carries `done`, `surfaced`, `decisions` and `amb` — judgements only the agent
+# holds. A hook filling them in would be fabricating the very evidence the line
+# exists to provide. So it records what it can actually see (a subagent of this
+# type stopped) and leaves the accounting to whoever can account.
+#
+# Silent with no ledger, and never blocking: none of these events should ever cost
+# a session. `SessionEnd` hooks share a 1.5-second budget, so this appends one line
+# and exits.
+set -uo pipefail
+
+input=$(cat 2>/dev/null || true)
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+ledger="$project/.task-pipeline/run.md"
+[ -f "$ledger" ] || exit 0
+
+HOOK_INPUT="$input" python3 - "$ledger" <<'PY' 2>/dev/null || true
+import json, os, sys, datetime, re
+
+ledger = sys.argv[1]
+try:
+    data = json.loads(os.environ.get("HOOK_INPUT", ""))
+except Exception:
+    raise SystemExit(0)
+
+event = data.get("hook_event_name")
+
+
+def clean(text, limit=90):
+    """One line, no separators that would break the ledger's own grammar."""
+    s = re.sub(r"\s+", " ", str(text or "")).replace("—", "-").strip()
+    return s[:limit]
+
+
+if event == "PreCompact":
+    kind, detail = "compact", clean(data.get("trigger") or "unknown")
+elif event == "SessionEnd":
+    # A run that reached acceptance is finished, not abandoned. Recording an end
+    # for it would fill `checkup` with runs that closed exactly as intended.
+    try:
+        text = open(ledger, encoding="utf-8").read()
+    except Exception:
+        raise SystemExit(0)
+    stages = [l.strip() for l in text.splitlines() if l.strip().startswith("stage:")]
+    closed = any(re.search(r"verdict\s+pass", l) and re.search(r"accept", l, re.I) for l in stages)
+    if closed:
+        raise SystemExit(0)
+    kind = "session-end"
+    detail = "%s - run not closed, no acceptance recorded" % clean(data.get("reason") or "other", 40)
+elif event == "SubagentStop":
+    kind = "subagent"
+    detail = clean(data.get("agent_type") or "unknown", 40)
+else:
+    raise SystemExit(0)
+
+stamp = datetime.datetime.now(datetime.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+with open(ledger, "a", encoding="utf-8") as fh:
+    fh.write('event: %s — %s — %s\n' % (kind, detail, stamp))
+PY
+exit 0

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

@@ -106,7 +106,8 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "full suite green (not just new tests); new/changed code covered including failure paths; no skip/xfail smuggling a red suite past the gate; tests assert real behavior, not mock behavior"
+        "check": "full suite green (not just new tests); new/changed code covered including failure paths; no skip/xfail smuggling a red suite past the gate; tests assert real behavior, not mock behavior",
+        "command": "npm test"
       }
     },
     {

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

@@ -210,10 +210,27 @@ than a detail to omit.
 
 ## The one this skill ships
 
-Since v1.50.0 the plugin carries a hook of its own —
-`hooks/release-gate.sh`, wired at `PreToolUse` on `Bash`. It refuses an
-**outward, irreversible act** (`git tag`, a tag push, `gh release create`,
-`npm publish`) while the run ledger records no `stage: 6 … verdict pass`.
+Since v1.50.0 the plugin carries hooks of its own. `hooks/release-gate.sh`
+(`PreToolUse` on `Bash`) refuses an **outward, irreversible act** — `git tag`, a
+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.
+
+**Two lessons from v1.50.0, both shipped as defects and both fixed in v1.51.0.**
+
+*A gate keyed to a stage NUMBER is the rail's mistake with worse consequences.*
+The first version matched `stage: 6` literally. `progress.md` says the rail "is
+computed, never eleven" because a host project replaces the flow — and a project
+whose flow has six stages, tests green at stage 4, could never tag anything again.
+A wrong rail misinforms; a wrong gate stops the work. The stage is resolved from
+`pipeline.json` (`state: "tests"`, or a stage declaring `gate.command`), and
+failing that from the ledger by name.
+
+*A gate that reads a claim written by the party it constrains confirms an
+assertion with itself.* `stage: … verdict pass` is typed by the agent. Where the
+stage declares `gate.command`, the observer writes the **observed** exit code as a
+`gate:` line and the release gate requires both. Declare no command and it
+degrades to the claim alone — which is stated here rather than discovered.
 
 It is the worked example above, made real, and its three narrownesses are the
 reusable part:

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

@@ -30,6 +30,8 @@ maintains them and the next run reads them as current.
 - Every number is borrowed
 - Absent is a word, never a zero
 - The `holds:` line — what the run is still holding
+- The observation beside the claim
+- The run's own lifecycle
 - The run ledger this reads from
 - Rationalizations
 
@@ -317,6 +319,38 @@ Three things make the line worth writing rather than a habit:
 Doctrine, including the eight classes and what must **not** be torn down:
 [`residue.md`](residue.md).
 
+## The observation beside the claim
+
+A `stage:` verdict is written by the agent. Since v1.51.0 the ledger also carries
+
+```
+gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
+```
+
+written by `hooks/gate-observer.sh` and by nothing else: the **observed** exit code
+of the command the project declared in `pipeline.json` → the tests stage's
+`gate.command`. The rail does not read it — a glyph still comes from the verdict —
+but the stage-7 release gate requires the claim and the observation to agree.
+
+The reason is the one this whole file is about, arriving one level down. A rail
+written from memory is a summary that is confidently wrong exactly when it matters;
+a gate that reads a verdict typed by the agent it constrains is the same shape
+again, and it looks like enforcement while being a mirror.
+
+## The run's own lifecycle
+
+Three moments the rail cannot show, recorded by `hooks/run-lifecycle.sh` as
+
+```
+event: <compact|session-end|subagent> — <detail> — <ISO-8601>
+```
+
+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
+from a run still in progress, which is the exact shape *absent is a word, never a
+zero* exists to refuse.
+
 ## The run ledger this reads from
 
 `.task-pipeline/run.md`, seeded at stage 0 from

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

@@ -11,9 +11,16 @@
 
 Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
+## Contents
+
+- Lines
+- Log
+- Why it is not the build ledger
+- What closes it, and what survives it
+
 ## Lines
 
-Append-only. Four shapes, and nothing else belongs here:
+Append-only. These shapes, and nothing else belongs here (the list is the count — a written one drifts, and this one already had):
 
 ```
 stage: <id> <name> — gate <auto|manual> — verdict <pass|fail|skip> — <ISO-8601>
@@ -21,11 +28,34 @@ iter:  <N> — item <B-NNN or task id> — closed at gate <stage id>
 touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate item>
 hand:  <N|10> — task "<quoted>" — done <n> — surfaced <n> — decisions <n> — amb <n> (<ids or "— no register">)
 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>
 ```
 
 - **`stage:`** — written when a gate **returns**, not when the stage is entered. The
   rail's `✓` is derived from this line and from nothing else; a glyph set from memory
   is a summary that is confidently wrong exactly when it matters.
+- **`gate:`** — written by `hooks/gate-observer.sh`, never by an agent. It is the
+  only line here that records what a command **did** rather than what somebody
+  concluded: the exit code of the stage's declared `gate.command`, observed. The
+  `stage:` line above it is the agent's claim, and the release gate requires the
+  two to agree — without this, a gate reads a claim written by the party it
+  constrains and confirms an assertion with itself. Absent where the project
+  declares no command, and the release gate then degrades to the claim alone.
+
+- **`event:`** — written by `hooks/run-lifecycle.sh`, the three moments this file
+  otherwise cannot show. `compact` marks the boundary the ledger exists *because
+  of* — without it a resumed run cannot tell a compaction from nothing happening.
+  `session-end` marks a run whose session ended without reaching acceptance, which
+  is what `/task-pipeline checkup` looks for and what was previously invisible: the
+  ledger simply stopped, and a stopped ledger looks exactly like a run still in
+  progress. `subagent` records one finishing, so the `hand:` count below has
+  something to be checked against other than itself.
+
+  **It never writes a `hand:` line.** That shape carries `done`, `surfaced`,
+  `decisions` and `amb` — judgements only the agent holds, and a hook filling them
+  in would fabricate the evidence the line exists to provide.
+
 - **`iter:`** — one line per iteration closed. The progress line's counter is
   `grep -c '^iter:'`, never a number anyone remembers.
 - **`hand:`** — one per hand-back, at an iteration's close and at stage 10
@@ -53,6 +83,10 @@ stage: 1 Docs study — gate auto — verdict pass — 2026-08-10T11:31Z
 touch: src/export.ts — pass 1 (stage 5) — reason: TASK-3
 touch: src/export.ts — pass 2 (stage 5) — reason: F-014
 touch: src/export.ts — pass 3 (stage 5) — reason: F-014
+event: compact — auto — 2026-08-10T11:58Z
+event: subagent — general-purpose — 2026-08-10T12:00Z
+gate:  6 — command "npm test" — exit 0 — 2026-08-10T12:02Z
+stage: 6 Tests — gate manual — verdict pass — 2026-08-10T12:03Z
 hand:  3 — task "add CSV export to the orders table" — done 2 — surfaced 1 — decisions 1 — amb 2 (OQ-0007, ledger row 4)
 holds: 5 — 2 (worktree: build-csv-export, this run; container: pg-test, this run) — enumerated 8/8 classes
 holds: 10 — none — enumerated 7/8 classes, unlooked: containers (no docker on this host)