task-pipeline-skill 1.49.2 → 1.51.0

package/CHANGELOG.md

@@ -1,5 +1,107 @@
 # Changelog
 
+## 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
+
+- **`plugins/task-pipeline/hooks/release-gate.sh` — the stage-7 rule, enforced at
+  agent time.** `stages.md` has always said a release does not leave stage 7 until
+  the full suite is green at stage 6. That was a sentence an agent reads and a
+  person hopes was obeyed, checked — when it was checked — after the tag was
+  already public. A `PreToolUse` hook now refuses `git tag`, a tag push,
+  `gh release create` and `npm publish` while the run ledger records no
+  `stage: 6 … verdict pass`.
+
+  Three narrownesses are the whole design, and each is the difference between a
+  gate people keep and a gate people rip out:
+
+  1. **Only outward acts.** Ordinary commits are how stage 5 works; gating them
+     would fight the pipeline's own build loop and be gone within a day.
+  2. **Only where a pipeline runs.** No `.task-pipeline/run.md` means exit 0
+     before anything else is read, so enabling the plugin changes nothing in any
+     other repository on the machine.
+  3. **Only what the ledger says.** Nothing reruns a suite or believes a claim —
+     `progress.md` already makes the ledger append-only, and this reads it.
+
+  The refusal names the act, the ledger to record the stage in, and the opt-out.
+  A refusal with no next step is how an operator learns to remove a gate.
+
+  Fail-closed by construction: an internal failure exits 2 as well, because every
+  non-zero code other than 2 is non-blocking in Claude Code, and a crashing gate
+  that fails open is worse than no gate — it reads as one.
+
+- **`test/release_gate_test.py`** — 16 fixtures, run as a process with real JSON on
+  stdin, wired into `npm run test:all` and CI. Eight of them were watched failing:
+  the first implementation fed its own python source to `python3 -` through a
+  heredoc **and** tried to read the payload from stdin, so `sys.stdin.read()` came
+  back empty, every release was classified as "not a release", and the gate
+  allowed everything while looking installed. The payload now travels in the
+  environment.
+
+### Notes
+
+- The hook lives in the plugin's `hooks/hooks.json` rather than in `SKILL.md`
+  front matter. Front-matter hooks are scoped to a skill's activation; a release
+  gate has to hold for the whole run, across turns where the skill is not the
+  thing being invoked. `agent-sync` already enforces its leases from the same
+  channel, so this is the family's proven path rather than a new one.
+
+Guards: 309 → **310**. Property checks: 9 → 9. The new guard is the negative
+self-test that disarms the release gate — it blanks the payload handoff, which is
+how the gate was really broken for its first eight fixtures — and requires the
+suite to notice. `test/negatives.py`'s floor moved with it in the same change,
+because a floor below the count cannot notice losing the difference.
+
 ## v1.49.2 — four stray table rows, and a list that promised three and delivered two
 
 ### Fixed

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.49.2 |
+| **Version** | 1.51.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.49.2",
+  "version": "1.51.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"
@@ -9,7 +9,8 @@
     "test": "python3 test/validate.py",
     "test:negatives": "python3 test/negatives.py",
     "test:probe": "python3 test/probe.py --self-test",
-    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe"
+    "test:all": "python3 test/validate.py && python3 test/negatives.py && npm run test:probe && npm run test:hooks",
+    "test:hooks": "python3 test/release_gate_test.py"
   },
   "files": [
     "bin",

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

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

@@ -0,0 +1,45 @@
+{
+  "description": "task-pipeline — the stage-7 gate and the observation it rests 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": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/release-gate.sh\"",
+            "statusMessage": "has the tests gate passed?",
+            "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
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,223 @@
+#!/usr/bin/env bash
+# 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 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:
+#
+#   1. Only OUTWARD acts. `git tag`, a tag push, `gh release create`, `npm
+#      publish`. Ordinary commits are how stage 5 works — gating them would fight
+#      the pipeline's own build loop and be gone within a day.
+#   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, 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
+# crashing gate that fails open is worse than no gate, because it reads as one.
+set -uo pipefail
+
+input=$(cat 2>/dev/null || true)
+
+project="${CLAUDE_PROJECT_DIR:-$PWD}"
+ledger="$project/.task-pipeline/run.md"
+
+decide() {
+  # The payload travels in the environment, NOT on stdin: the heredoc below IS
+  # 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" "$project" <<'PY'
+import json, shlex, sys, os, re
+
+ledger, project = sys.argv[1], sys.argv[2]
+raw = os.environ.get("HOOK_INPUT", "")
+try:
+    data = json.loads(raw)
+except Exception:
+    print("skip"); raise SystemExit(0)
+
+cmd = ((data.get("tool_input") or {}).get("command") or "")
+try:
+    tokens = shlex.split(cmd)
+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]
+    for i, t in enumerate(low):
+        rest = low[i + 1:]
+        # `git -C dir -c k=v tag v1` — the subcommand is the first token after
+        # git that is not a flag or a flag's value. Tokenised rather than matched
+        # as a substring: `git log --grep=tag` must not count.
+        if t.endswith("git"):
+            j = 0
+            while j < len(rest):
+                if rest[j] in ("-C", "-c", "--git-dir", "--work-tree"):
+                    j += 2; continue
+                if rest[j].startswith("-"):
+                    j += 1; continue
+                break
+            if j < len(rest):
+                sub = rest[j]
+                args = rest[j + 1:]
+                if sub == "tag" and not any(a in ("-d", "--delete", "-l", "--list") for a in args):
+                    if any(not a.startswith("-") for a in args):
+                        return "git tag"
+                if sub == "push":
+                    if any(a in ("--tags", "--follow-tags") for a in args):
+                        return "git push --tags"
+                    if any(a.startswith("refs/tags/") or re.fullmatch(r"v?\d+\.\d+\.\d+.*", a) for a in args):
+                        return "git push <tag>"
+        if t.endswith("gh") and rest[:2] == ["release", "create"]:
+            return "gh release create"
+        if t.endswith("npm") and "publish" in rest:
+            return "npm publish"
+    return None
+
+
+act = outward(tokens)
+if not act:
+    print("skip"); raise SystemExit(0)
+
+if not os.path.exists(ledger):
+    print("skip"); raise SystemExit(0)
+
+try:
+    text = open(ledger, encoding="utf-8").read()
+except Exception:
+    # The ledger exists and cannot be read: this project IS governed and the
+    # 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)
+
+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
+
+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
+}
+
+verdict=$(decide 2>/dev/null)
+status=$?
+
+# A gate that cannot reach its own decision must not wave the release through.
+if [ $status -ne 0 ] || [ -z "$verdict" ]; then
+  [ -f "$ledger" ] || exit 0
+  echo "task-pipeline: the stage-7 gate could not run (python3 missing or failed), and this project has a run in flight ($ledger). Refusing an outward act rather than failing open." >&2
+  exit 2
+fi
+
+state=$(printf '%s' "$verdict" | cut -f1)
+act=$(printf '%s' "$verdict" | cut -f2)
+why=$(printf '%s' "$verdict" | cut -f3)
+
+case "$state" in
+  skip|ok) exit 0 ;;
+  block)
+    cat >&2 <<EOF
+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 the tests stage in $ledger, then release.
+
+To release deliberately without the pipeline, remove the ledger or say
+«без пайплайна» and take the route by hand.
+EOF
+    exit 2 ;;
+  *) exit 0 ;;
+esac

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

@@ -17,6 +17,7 @@ that acts *while the agent is working* rather than after the commit.
 - A worked example
 - Debugging
 - Removing them
+- The one this skill ships
 - Leases are not reimplemented here
 - Rationalizations
 
@@ -207,6 +208,50 @@ hooks enforced is still available as a command and still stated in the doctrine
 and the run is **`ungated`** from then on, which is a thing to say out loud rather
 than a detail to omit.
 
+## The one this skill ships
+
+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:
+
+| Narrowness | Why it is not a smaller feature |
+|---|---|
+| Only outward acts, never ordinary commits | stage 5 commits per task by design; a gate that fights the build loop is removed within a day |
+| Silent where no `.task-pipeline/run.md` exists | enabling the plugin must change nothing in a repository that runs no pipeline |
+| Reads the ledger, never reruns a suite | `progress.md` already makes the ledger append-only; a second source of truth about "did stage 6 pass" is the failure this file warns about below |
+
+**Fail-closed, deliberately.** Every non-zero exit code other than `2` is
+non-blocking, so an internal failure exits `2` as well. A crashing gate that fails
+open is worse than no gate: it reads as one.
+
+**The defect worth remembering** — the first implementation fed its own python
+source to `python3 -` through a heredoc *and* read the payload from stdin. The
+heredoc **is** stdin, so the payload came back empty, every act classified as "not
+a release", and the gate allowed everything while looking installed. Eight fixtures
+caught it. A hook that cannot see its own input is indistinguishable, from the
+outside, from a hook that approves.
+
 ## Leases are not reimplemented here
 
 Guarded registers and lease arbitration belong to a coordination tool

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

@@ -30,6 +30,7 @@ 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 ledger this reads from
 - Rationalizations
 
@@ -317,6 +318,24 @@ 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 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,20 @@ 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>
 ```
 
 - **`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.
+
 - **`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 +69,8 @@ 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
+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)