task-pipeline-skill 1.74.0 → 1.75.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## v1.75.0 — 2026-08-22 — the day's findings become doctrine
+
+Nothing new ships behind a flag here; what ships is the doctrine the previous release
+earned, written where the next run will read it instead of in a changelog nobody greps.
+
+**`documentation.md` canon 2 gains its dual.** *Numbers are computed, never restated* had
+a half nobody had written down: **an example that instantiates a number IS one.** A release
+note explaining that a count was written in the wrong shape — with the digits in it — places
+a second readable count in a section a gate reads, so a probe that removes the real one
+leaves the narrative matching and the guard silent. Measured three times in one hour, each
+time inside prose *about* this very failure. The umbrella already said it for commands:
+name a dead command, never claim it. It holds for a number, a version and a shape.
+
+**`gates.md` gains three sections.**
+
+*A probe rots, and every way it rots reports green.* The three assertions prove a probe
+works today; the thing it guards is the thing that moves it. An anchor pinned to a literal
+dies on the release that changes the number it guards. A precondition inherited from the
+tree evaporates **when the system works correctly** — an honest run stamp leaves nothing
+"after the newest stamp", a release absorbs the `## Unreleased` section — and the probe
+lands and proves nothing. The triage is one question: *what does this probe look for, and
+who is allowed to change it?*
+
+*A ratchet prices the rule, not the exception.* A coverage check that asserts once per
+exception and falls through on the ordinary case makes the correct remediation lower the
+count — so the gate goes red on the stricter answer and a legitimate lowering becomes
+indistinguishable from the failure the floor exists to catch. One assertion per subject
+examined, whatever its verdict. And measure the floor **after** the last edit: read, keep
+editing, restate is how every floor ends up below its true count, silently, because a floor
+is a minimum.
+
+*Run the whole suite locally before you push the tag.* Also **R-010**, because it is a
+run-level obligation rather than a note. One tag took five CI rounds where the last four
+were a single twelve-minute local run apart — and the second half is what makes it a rule:
+a branch push cannot see a tag that does not exist yet, so three checks have no earlier
+chance to fire.
+
+### And R-010 failed on its own release, which is the finding
+
+The local suite was green and CI was not. The difference was one precondition asking
+`os.path.isdir(".git")` — false in a **submodule** checkout, where `.git` is a file holding a
+gitdir pointer. The whole release-gap check had been switching itself off in the only checkout
+this family is developed in, since the day it was written, with no line of output. It ran in CI
+alone, which clones standalone, so a class of defect reached four tag pushes before anyone asked
+why the local run was green.
+
+This repository had already recorded that class **twice**, in `docgate.sh` and in the retro log,
+both naming `[ -d .git ]` as the wrong question. This instance was missed both times. Knowing a
+class is not sweeping it — which is standing instruction R-003, also already in force.
+
+Two fixes, and the second is the general one: ask `exists`, never `isdir`, of anything named
+`.git`; and **a precondition that fails must disclose rather than skip**. A check guarded by a
+bare `and` evaporates without output, and it evaporates most reliably in the environment its
+authors work in. R-010 gains the half it learned by failing: *a green local suite is not
+evidence until you know which checks looked* — tag locally first, run, then read the `unlooked`
+line before believing the exit code.
+
+Seven board citations into `gates.md` were re-pointed across two passes, which is the ordinary
+cost of inserting text above them and the reason those citations carry a phrase as well as a
+range.
+
+Guards: 412 → **412**. Flat by construction: this release adds doctrine, not checks, and a
+guard count that rose on a documentation change would be a number borrowed from a suite that
+never ran. The shape of that line is the one canon 2's new half is about, so it is written
+here in the form the guard reads and described nowhere else in this section.
+
 ## v1.74.0 — 2026-08-20 — a node is closed by three readings, not one
 
 **A verifier reads the diff it was handed, and that is the definition of its context, not a

package/SKILL-CARD.md

@@ -12,7 +12,7 @@ harmless.
 |---|---|
 | **Purpose** | Runs a substantial task through ten gated delivery stages — intake grill, docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs+registers, acceptance — refusing to advance until each gate passes |
 | **Owner** | ssheleg ([github.com/ssheleg/task-pipeline](https://github.com/ssheleg/task-pipeline)) |
-| **Version** | 1.74.0 |
+| **Version** | 1.75.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, and **one of two browser channels** — `playwright` (CLI or MCP) or `chrome-devtools` (MCP); either satisfies the browser step and neither is required. Every stage's doctrine ships in-repo; the one conditional requirement is super-ux for the stage-3 UX track on a user-facing task |
 | **Evaluation status** | Suite authored, 5 categories. One recorded run, **self-observed by the author**; **zero blind runs on zero of three models** — the split, and the numbers, live in [`evals/RESULTS.md`](evals/RESULTS.md) and are computed by `evals/run.py` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.74.0",
+  "version": "1.75.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.74.0",
+  "version": "1.75.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -49,9 +49,23 @@ the same run and a description of the behaviour is not the behaviour. → the re
 SHA-resolution guard; the finding shape in [`setup.md`](setup.md); [`tdd.md`](tdd.md) →
 *When the thing under test is an agent*.
 
-**2. Numbers are computed, never restated.** A count in prose is a number that was true
-once. Derive it at check time and compare the stated one against the computed one as the
-same object. → [`learned.md`](learned.md) rule 8.
+**2. Numbers are computed, never restated — and an example that instantiates a number
+IS one.** A count in prose is a number that was true once. Derive it at check time and
+compare the stated one against the computed one as the same object. → [`learned.md`](learned.md)
+rule 8.
+
+The half that costs more, because it is written by the person who understands the rule:
+**a document quoting a form as an example is indistinguishable from the form.** A release
+note explaining *"the count was written wrongly as `Guards: 412 → 412`"* has just placed a
+second readable count in a section whose count a gate reads — so when the probe removes the
+real one, the narrative still matches and the guard reports green over a section that states
+nothing. Measured three times in one hour on 2026-08-22, each time inside prose *about* this
+very failure: the release note, the board row filed against it, and the repair to the probe.
+
+The rule the umbrella already states for commands — **name a dead command, never claim it**
+— holds for a number, a version and a shape. Describe the wrong form; do not write it.
+*"the bold sat around the whole phrase instead of around the second number"* is checkable by
+a reader and invisible to a pattern; the same sentence with the digits in it is a live claim.
 
 **3. Every fact has exactly one home.** Other documents link to it; they never restate
 it. Two homes do not disagree on the day they are written — they disagree on the day one

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

@@ -31,6 +31,9 @@ elsewhere and is not restated here:
 - Anatomy of a project gate
 - Writing the check itself
 - Probing — plant, run, restore
+- A probe rots, and every way it rots reports green
+- A ratchet prices the rule, not the exception
+- Run the whole suite locally before you push the tag
 - The neighbour probe — plant the evidence outside the subject
 - A ratchet's matcher is itself a check, and it needs a near-miss
 - A green probe is evidence only if the mutation is known to have landed
@@ -385,6 +388,95 @@ Otherwise the next reader has to redo it to know whether it was ever done.
 
 ---
 
+## A probe rots, and every way it rots reports green
+
+The three assertions above prove a probe works **today**. They say nothing about the
+day after, and a probe is uniquely exposed: the thing it guards is the thing that moves
+it. Four rotted in one release on 2026-08-22, and none of them failed loudly — two
+reported `caught`, two reported nothing at all.
+
+**1. The anchor is a literal the guarded thing moves.** A probe pinned to *"the bundle
+is N reference files"* stops landing the day a reference file is added — on the release
+that changes the very number it guards. Same for a version, a count word, a phrase a
+release rewrites. **Derive the anchor**: read whatever the text currently says and make
+*that* wrong. A probe that computes `wrong = stated - 1` never needs maintaining.
+
+**2. The precondition is inherited from the tree rather than created.** This is the
+subtle one, because it is triggered by the system working correctly. A probe that
+narrows a declared gap to expose *releases after the newest run stamp* has nothing to
+expose the moment a release writes an honest stamp — the newest release is now the
+newest stamp. A probe requiring an `## Unreleased` section has none the moment a release
+absorbs it. **Both landed. Both proved nothing.** A probe must construct the state it
+needs: remove the stamp, write the section, then plant the defect.
+
+**3. The document quotes the form the probe removes.** Covered as
+[`documentation.md`](documentation.md) canon 2's second half, and it belongs here too
+because the probe is where it surfaces: prose describing the wrong shape *with real
+values in it* is a second instance of the shape. The probe deletes the real one, the
+narrative still matches, the guard is silent.
+
+**How to see it before CI does.** Ask one question per probe: *what does this probe
+LOOK FOR, and who is allowed to change it?* Where the answer is "the thing it guards",
+it is rotting already. A repository-wide sweep is one grep — a two-digit literal inside
+a needle, an `assert` or a `replace` — and the triage is: the number a probe **writes**
+is correct, the number it **looks for** is the defect.
+
+## A ratchet prices the rule, not the exception
+
+A floor that counts assertions is a floor that can be lowered by improving the code, if
+the assertions are attached to the wrong things.
+
+Measured: a coverage check called `check()` once per *exception* — a silent value, a kept
+value, a promise — and simply `continue`d on the ordinary case. Collapsing four kept
+values, **the remediation the requirement names first**, therefore dropped the count by
+four against its floor and turned the suite red on the stricter answer. The only way
+through was lowering a ratchet whose own reason says a falling count is how a deleted
+requirement hides — so a legitimate lowering and the failure the floor exists to catch
+became indistinguishable.
+
+**One assertion per subject examined, whatever its verdict.** The ordinary case asserts
+too. Then the floor is a function of how large the corpus is, not of how many exceptions
+it happens to contain, and doing the right thing can never lower it.
+
+**And measure the floor after the last edit, not before it.** Read the count, keep
+editing, restate the count you read — every floor set that way sits below the true one,
+and a floor is a minimum, so nothing ever says so. Where the gate cannot enforce
+equality — it must not, or the ratchet stops allowing growth — it can still **print the
+gap**: `floor 4026, ran 4027: 1 check is not pinned` turns a silent difference into a
+visible one for the cost of one line.
+
+## Run the whole suite locally before you push the tag
+
+Not a preference: an arithmetic. A release workflow that runs the full suite takes
+twenty-five to forty minutes per round, and it reports one failure at a time. The same
+suite on the machine that wrote the change takes twelve and reports all of them at once.
+
+On 2026-08-22 one tag took **five CI rounds** — a stray key in a `run:` block, a missing
+run stamp, a stamp cap, and then four rotted probes — where a single local `test:all`
+before the first push would have found the last four together. Every refusal was correct.
+The cost was entirely in asking the wrong machine.
+
+**A green local suite is not evidence until you know which checks LOOKED.** This
+instruction failed on its own release: the local run was green, CI was not, and the
+difference was a precondition asking `os.path.isdir(".git")` — false in a submodule
+checkout, where `.git` is a *file* holding a gitdir pointer. One check switched itself
+off in the only checkout the family is developed in, silently, and had been doing so
+since it was written. The repository had recorded that class **twice** already, in two
+other files, and this instance was missed both times: knowing a class is not sweeping
+it. Two consequences, and the second is the general one:
+
+- ask `exists`, never `isdir`, of anything named `.git`;
+- **a precondition that fails must disclose, not skip.** Where a check cannot run, it
+  appends to the unlooked list and the run prints it. A check guarded by a bare `and`
+  evaporates without a line of output, which is the one thing this file's own canon
+  forbids — and it evaporates most reliably in the environment its authors use.
+
+The rule has a second half, and it is the one that makes it stick: **a tag is the only
+thing that runs some checks.** A branch push cannot see a tag that does not exist yet, so
+the tag-ancestry check, the version-sync check and the run-stamp check have no earlier
+opportunity to fire. Locally, run them the way the release does — against the tree you are
+about to tag, with the suite the release claims.
+
 ## The neighbour probe — plant the evidence outside the subject
 
 A probe proves a guard rejects **the phrasing its author had in mind**. That is less than