task-pipeline-skill 1.51.0 → 1.52.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # 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

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.51.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.51.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.51.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/hooks.json

@@ -1,5 +1,5 @@
 {
-  "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.",
+  "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": [
       {
@@ -13,6 +13,17 @@
             "timeout": 20
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/build-gate.sh\"",
+            "timeout": 20
+          }
+        ]
       }
     ],
     "PostToolUse": [
@@ -40,6 +51,42 @@
           }
         ]
       }
+    ],
+    "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/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/references/progress.md

@@ -31,6 +31,7 @@ maintains them and the next run reads them as current.
 - 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
 
@@ -336,6 +337,20 @@ written from memory is a summary that is confidently wrong exactly when it matte
 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

@@ -29,6 +29,7 @@ touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate
 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
@@ -42,6 +43,19 @@ gate:  <stage id> — command "<cmd>" — exit <N> — <ISO-8601>
   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
@@ -69,6 +83,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
+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)