task-pipeline-skill 1.49.1 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 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
+
+- **The body shipped a rendering defect.** Four rows of the built-in-doctrine
+  index — `artifacts.md`, `companion-skills.md`, `conventions.md`,
+  `model-tiering.md` — sat between the grill's bullet list and `## How to run`
+  with no header row above them. GFM needs a delimiter row to open a table, so an
+  agent reading `SKILL.md` saw four lines of literal pipes. Moved back into the
+  index where their shape says they belong.
+
+- **"Three things the grill does beyond clarifying the request" listed two.** The
+  displaced rows had taken the third with them. Restored from
+  `references/grill.md`, which still carries it in full: **the design
+  destination** — which Figma file, in which team, decided at stage 0 rather than
+  at drawing time. Restored rather than renumbered, because the reference proves
+  what was lost; renumbering to "two" would have made the body agree with itself
+  and disagree with the doctrine.
+
+Guards: 309 → **309**. Property checks: 9 → 9. This release restores content and
+adds no enforcement — the defect was structural markdown, which no guard here
+reads, and the count is stated because two probes read the newest section.
+
+### Note on the token budget
+
+The body is **5969 tokens against a 5000 cap**, up 108: the restored bullet costs
+more than the four moved rows save. Correctness first — a body promising three
+items and delivering two, with four lines rendering as garbage, is worse than
+being over a soft cap it was already over.
+
+The gap is now measured rather than estimated, so it stops being re-litigated by
+prose trims. Three attempts at trimming prose produced 35 tokens between them. The
+whole doctrine index is 555 tokens — 320 in the descriptive column, 235 in the
+reference names — so compressing every description to nothing closes at most **26%
+of the 1219-token gap**, and less than that if the stage numbers stay, which are
+the navigational value. The remainder lives in the Stages table's `Gate` column
+(`grep -c '^\*\*Gate' references/stages.md` → **0**: the body is its only home)
+and in the five-step operating procedure. Closing the gap therefore means moving
+content into references — a restructuring of the skill, not a trim.
+
 ## v1.49.1 — the entry states the count its own guard reads
 
 ### 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.1 |
+| **Version** | 1.50.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.1",
+  "version": "1.50.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.1",
+  "version": "1.50.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -0,0 +1,19 @@
+{
+  "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.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/release-gate.sh\"",
+            "statusMessage": "stage 7: has stage 6 passed?",
+            "timeout": 20
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,143 @@
+#!/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 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.
+#
+# 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. Nothing here reruns a suite or believes a
+#      claim; `progress.md` makes the ledger append-only, and this reads it.
+#
+# 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" <<'PY'
+import json, shlex, sys, os, re
+
+ledger = sys.argv[1]
+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):
+                    # 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":
+                    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)
+
+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
+        break
+
+print("ok\t%s" % act if passed else "block\t%s\tno `stage: 6 … verdict pass` line in the ledger" % 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 stage 6 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.
+
+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/SKILL.md

@@ -73,6 +73,10 @@ gate stops until it is installed.
 | run-wide · the work-list **between** runs, and how its priority is computed | `references/backlog.md` |
 | run-wide · whether a **human** ever confirmed what shipped, and when | `references/verification.md` |
 | run-wide · how much unconfirmed work has piled up, and what to look at first | `references/exposure.md` |
+| any stage · Where each artifact belongs | `references/artifacts.md` |
+| preflight · Companion skills and their fallbacks | `references/companion-skills.md` |
+| 6–10 · How the host project's CLAUDE.md is read | `references/conventions.md` |
+| preflight · Model map, ids and the override | `references/model-tiering.md` |
 
 **Optional bridge.** An equivalent skill set the operator already runs (e.g.
 `superpowers:brainstorming` / `writing-plans` / `subagent-driven-development` /
@@ -152,10 +156,12 @@ Three things the grill does beyond clarifying the request:
   mid-flight (test/lint/deploy commands, branch policy, log locations, docs
   targets, the model decision, deploy authorization). Autonomy is bought here or
   not at all — an unasked question is a scheduled interruption.
-| any stage · Where each artifact belongs | `references/artifacts.md` |
-| preflight · Companion skills and their fallbacks | `references/companion-skills.md` |
-| 6–10 · How the host project's CLAUDE.md is read | `references/conventions.md` |
-| preflight · Model map, ids and the override | `references/model-tiering.md` |
+- **The design destination**, when the project designs in Figma: *which* file, in
+  which team — a stage-0 decision, never a stage-3 side effect. Left to drawing
+  time the question is answered by whoever is holding the brush, and the answer is
+  usually *create a new file* — which is how a project ends up with three files
+  called some variation of "Design", each with real work in it and no way to tell
+  which one the team opens.
 
 ## How to run
 

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,33 @@ 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 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`.
+
+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