task-pipeline-skill 1.28.0 → 1.29.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## v1.29.0 — a sixth axis, and three summaries that each read as complete
+
+**Re-derivation** joins the rotation axes in `references/audit.md`: take a number the
+audit already produced and produce it again with a command of a **different shape**,
+then print both. Not a second opinion — a second route. Re-running the same command is
+a spell-check of the first run; only a differently-shaped question can come back
+disagreeing. The exit criterion is **the pair printed**, never "verified", never
+"matches": a re-derivation reported as agreement is a claim about a measurement nobody
+can see.
+
+It earns its place from this repository's own record. Four applications, two of which
+refuted something already written down as fact: the version invariant called *four-way*
+over five surfaces (`CONTRIBUTING.md:74`), and a graph shrink read as legitimate
+tightening at 864→839 and as erosion at 839→798 — **same procedure, opposite answers**,
+which is the whole argument for the axis in one line.
+
+**The enumeration had already drifted, and nothing could see it.** Measured before
+writing a word of doctrine: `audit.md` defined five axes, the Cursor rule summarised
+four, `README.md` three. Each reads as complete on its own, because a list of three
+orthogonal things is a convincing list of three orthogonal things. The Cursor rule now
+carries all six (it is self-contained by contract and cannot point anywhere); README
+stops enumerating and names the file that defines them — deleting a restatement is how
+every count this repository got wrong has been fixed.
+
+A guard now derives the axis keys from `audit.md` **at check time** and requires any
+paragraph naming three or more of them to name all of them. Its first run accused
+`stages.md` of enumerating three axes whose three hits were 595 lines apart and meant
+different things; scoped to the file, the predicate was measuring vocabulary rather
+than enumeration. The unit is the paragraph, and the guard says so in its own comment.
+
+**Found by the false positive:** `gates.md` was titled *the two axes* over a file with
+Axis A, B and C, and four surfaces repeated the two. README's prose named two and never
+mentioned degrees of freedom at all — the axis about how much latitude an instruction
+leaves, which is the one that gets skipped. All five sites corrected, and the count is
+now computed from the `## Axis` headings by a claim-registry class, alongside a second
+class for the rotation axes. The two are separated by the qualifier, because *axes* is
+polysemous in this corpus and a guard that conflates them reports drift that is not
+there.
+
+**Review round.** Four findings, none from the probes. The guard re-read thirty
+surfaces already cached; the flattening idiom had been hand-rolled three times, each
+commenting on the earlier ones, and is now `_flatten()`; the spec claimed a guard that
+did not exist. And the Cursor rule's **own** Gates section still said *"two axes"* with
+no Axis C — introduced by this PR, fifty lines below an edit it made. Nothing could see
+it: the claim registry's corpus held neither the Cursor rule nor the command file.
+Both are in it now, and the count moved 6 → 7 the moment they were.
+
+A second round found the same I/O class at two more call sites. Re-deriving its size
+with a differently-shaped command — an instrumented run rather than a grep of the
+source — put it at **25 reads of `audit.md` and 668 `.md` opens per run**, against an
+estimate of "3+". The two named sites are fixed; the rest is carry-over row 12 with the
+number attached, because a class measured and then left unmentioned is the TODO this
+repository refuses to keep.
+
+A third round found the sibling of the idiom the second round found — the
+paragraph-split, hand-rolled at four sites — now `_paragraphs()`, whose docstring says
+what the unit costs. And it found that the new **rotation axes** claim class was
+permanently dormant and had **never been watched failing**: dormant is green by design
+here, which is exactly why a dormant class still needs its plant. It has one now.
+
+Guards: 136 → **144**.
+
 ## v1.28.0
 
 ### Eight ways to say "I don't know", and no way to count them

package/CONTRIBUTING.md

@@ -329,7 +329,27 @@ guess. This repository had eight vocabularies for declining to claim and, until
 zero counters.
 *(guard: `a worked GATE verdict omits `)*
 
-**39. Every invariant above names the guard that enforces it, and that guard exists.**This list claims to be *what the validator enforces*; it was eight guards behind when
+**39. A surface that enumerates the rotation axes enumerates all of them.** The axes
+live once, in `references/audit.md`; the Cursor rule summarises them because it is
+self-contained by contract and can point nowhere. Measured on 2026-08-09: the
+definition held five, the Cursor rule four, README three — and each read as complete,
+because a list of three orthogonal things is a convincing list of three orthogonal
+things. The keys are derived from `audit.md` at check time, never hand-listed, and the
+unit is the **paragraph**: scoped to the file, the first version of this guard reported
+`stages.md` for three hits 595 lines apart that meant three different things. Either
+name every axis or stop enumerating and name the file.
+*(guard: `enumerates the rotation axes but names`)*
+
+**40. Counts of "axes" are computed, and the two kinds are kept apart.** `gates.md` is
+built on three of its own (context, enforcement, degrees of freedom) and `audit.md`
+rotates between six; the word is polysemous in this corpus. `gates.md` was titled *"the
+two axes"* over a file with Axis A, B and C, and four surfaces repeated it — including
+README's prose, which never mentioned degrees of freedom at all. Both counts are now
+claim-registry classes, separated by the qualifier, so a guard cannot report drift
+between two things that were never the same list.
+*(guard: `gates.md's own axes`)*
+
+**41. Every invariant above names the guard that enforces it, and that guard exists.**This list claims to be *what the validator enforces*; it was eight guards behind when
 an audit measured it. A claim of enforcement is now checked like any other claim.
 *(guard: `whose message does not appear in`)* — and a cited literal must lie inside
 a **single** string in `test/validate.py`: the check reads that file as text, so a

package/README.md

@@ -131,7 +131,7 @@ until it is installed.
 | run-wide pacing | [`continuity.md`](plugins/task-pipeline/skills/task-pipeline/references/continuity.md) — the loop mode (`run.loop`, default off, never collapses a manual gate) and the context budget (fires on a harness signal, never on an estimate) |
 | 0 + 9 + any settled decision | [`documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) — the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
 | 3 + 4 · every spec and plan | the self-review reads its rules back — is every named check real, does anything contradict a locked decision or a rejected option, and what does this cost now versus at design time. Answers land as a committed `## Self-review` of computed numbers |
-| 6–10 + any check you write | [`gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) — the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors |
+| 6–10 + any check you write | [`gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) — the three axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors |
 | any agent-time enforcement | [`hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) — the `PreToolUse` contract, the fail-open hazard, the Claude-Code-only limit |
 
 **Ported, not depended on.** Stage 0 is adapted from
@@ -431,8 +431,9 @@ Three rules keep the audit from becoming another loop:
   Measured over seven passes on a production repository, by pass six the audit was
   mostly repairing its own previous pass — while the finding count still looked
   healthy. So count both numbers every pass (new findings vs. self-inflicted ones);
-  when the second overtakes the first, **rotate the axis** — seams down one
-  deliverable, then invariants across deliverables, then one class swept end to end.
+  when the second overtakes the first, **rotate the axis**. The axes are orthogonal
+  by construction and there is one list of them, in `references/audit.md` — this line
+  used to restate three of the five that existed, and read as complete while doing it.
 - **A class that repeats twice becomes a gate, not a note.** Once is an incident;
   twice is a category, and a category belongs in lint or CI where nobody has to
   remember it. The third instance in a ledger is how a mechanical defect becomes
@@ -482,12 +483,17 @@ teaches everyone on day one that the gate is noise.
 
 ### Gates and hooks — how a rule becomes something that can say no
 
-Two axes, deliberately not conflated. **The stage gate type** (`auto` = verify it
+Three axes, deliberately not conflated. **The stage gate type** (`auto` = verify it
 yourself; `manual` = wait for an explicit go) is about this pipeline. **The
 enforcement mechanism** is a ladder a rule climbs: a doctrine line → a review
 question → a script check (promote here once the class has occurred *twice*) → a CI
 step → a hook. A rule may sit on several rungs; what it may never do is *pretend* to
-be on a higher one.
+be on a higher one. **Degrees of freedom** is the third and the one that gets
+skipped: how much latitude the *instruction* leaves — an open field where many
+routes reach a good answer, a narrow bridge where the guardrails are the wording.
+Over-constraining costs as much as under-constraining and is harder to see, because
+an agent following the letter past the point where the letter fits still reports
+success.
 
 The skill ships the anatomy of a gate that cannot lie — non-zero exit on any
 failure, the verdict block last with nothing after it, a scope header saying what it
@@ -810,7 +816,7 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/artifacts.md`](plugins/task-pipeline/skills/task-pipeline/references/artifacts.md) | the canonical document layout each stage writes to |
 | [`references/conventions.md`](plugins/task-pipeline/skills/task-pipeline/references/conventions.md) | how stages 6–10 read the host project's `CLAUDE.md`, and how the documentation regime is detected |
 | [`references/documentation.md`](plugins/task-pipeline/skills/task-pipeline/references/documentation.md) | the doc system: the inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built |
-| [`references/gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) | the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs |
+| [`references/gates.md`](plugins/task-pipeline/skills/task-pipeline/references/gates.md) | the three axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs |
 | [`references/deploy-targets.md`](plugins/task-pipeline/skills/task-pipeline/references/deploy-targets.md) | stages 7–8: writing the runbook when there is none, the template, per-platform deploy and log verbs, the verification trio |
 | [`references/hooks.md`](plugins/task-pipeline/skills/task-pipeline/references/hooks.md) | the `PreToolUse` contract, the fail-open hazard, placement, and the Claude-Code-only limit |
 | [`references/knowledge-graph.md`](plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md) | the code graph: install line, stage-0 reach queries, the stage-9 refresh, the graph↔docs divergence check |

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.28.0 |
+| **Version** | 1.29.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/cursor/rules/task-pipeline.mdc

@@ -404,7 +404,11 @@ its own previous pass while the finding count still looked healthy. So:
   to end (every error path, every count, every status vocabulary), then — where a
   code graph exists — **the graph against the docs**, the only axis that finds an
   absence without reading for it (a hub no document names, an edge the docs deny, a
-  doc naming a module the graph no longer has).
+  doc naming a module the graph no longer has), then **false success** (not "is this
+  check correct" but "what does this mechanism print when it did not look?"), then
+  **re-derivation** — a number the audit already produced, produced again by a
+  command of a *different shape*, with **both printed**; agreement asserted instead
+  of a pair printed is not a re-derivation.
 - **Audit bottom-up.** A missing artefact at a low rung makes everything above it
   meaningless; top-down you polish a surface for a contract that doesn't exist.
 - **A class that repeats twice becomes a check, not a note.** Once is an incident;
@@ -453,7 +457,7 @@ you *read*; the matrix names the documents you *owe*. The document nobody read i
 exactly the document nobody updated. At stage 9, walk the matrix for every change
 type the run produced, then run the documentation gate and print its ratchet counts.
 
-## Gates: two axes, and how to build one that cannot lie
+## Gates: three axes, and how to build one that cannot lie
 
 **Axis A — the stage gate type.** `auto` = verify the check yourself and stop on
 fail; `manual` = wait for an explicit operator go. An auto gate never substitutes
@@ -465,6 +469,17 @@ script check (promote here once the class has occurred **twice**) → CI step
 A rule may sit on several rungs; what it may never do is *pretend* to be on a higher
 one — that is the same failure as a gate that prints `FAIL` and exits `0`.
 
+**Axis C — degrees of freedom**, and it is the one that gets skipped. Axis B says how
+hard a rule bites; this says how much latitude the *instruction* leaves. **high** —
+prose direction, no prescribed sequence, for steps where many routes reach a good
+answer. **medium** — a named order with room inside each step. **low** — run exactly
+this, in this order, for a step that is fragile, irreversible, or must be identical
+every time. Match the level to how fragile the step is, not to how important it feels:
+an open field versus a narrow bridge. **Over-constraining costs as much as
+under-constraining and is harder to see** — a high-freedom step written as low freedom
+produces an agent that follows the letter past the point where the letter stopped
+fitting, and reports success, because it did what it was told.
+
 **Before you run any check:** the base is green (or its known-red baseline is
 recorded); the check has been probed; you have read its scope header and know what
 it does **not** cover; you have read its ratchet floors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.28.0",
+  "version": "1.29.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 must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -335,7 +335,7 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
 - `references/retrospective.md` — stage 10's last act: the project retro (`docs/superpowers/retro.md`), the three grades of fix, the mandatory prune and its cap of ten
 - `references/documentation.md` — cross-cutting: the doc inventory, registers and ids, SSOT, the Doc Loop, supersede semantics, the propagation matrix, intent vs as-built
-- `references/gates.md` — cross-cutting: the two axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs
+- `references/gates.md` — cross-cutting: the three axes, the promotion ladder, gate anatomy, the probe recipe, ratchet floors, where a gate runs
 - `references/deploy-targets.md` — stages 7–8: writing the runbook when there is none, the template, per-platform deploy and log verbs, and the verification trio
 - `references/hooks.md` — agent-time enforcement: the PreToolUse contract, the fail-open hazard, placement, and the Claude-Code-only limit
 - `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks

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

@@ -291,6 +291,25 @@ construction**:
    every pass that reads for wrongness. Sweep the change for actions trusted by
    their own reply. Definition and the known shapes: [`gates.md`](gates.md) →
    *False success*.
+6. **Re-derivation** — take a number the audit has already produced and produce it
+   again with a command of a **different shape**, then print both. Not a second
+   opinion: a second *route*. Re-running the same command is a spell-check of the
+   first run; asking a different question that must land on the same number is the
+   only version that can come back disagreeing. The exit criterion is **the pair
+   printed** — never "verified", never "matches". A re-derivation reported as
+   agreement is a claim about a measurement nobody can see.
+
+   ```
+   claimed:    the version invariant is four-way          (CONTRIBUTING.md, prose)
+   re-derived: grep -rl '"version"\|^## v' --include='*.json' --include='*.md' . \
+                 | wc -l                                  -> 5 surfaces
+   verdict:    REFUTED — the sentence and the corpus disagree; the corpus wins
+   ```
+
+   Rotate onto this axis when the reading axes go quiet **and the change carries
+   numbers**: counts in prose, thresholds, "N of M" claims, anything a document
+   asserts about itself. Its yield is not proportional to effort — it is
+   proportional to how long the first number went unchallenged.
 
 **The crossover is measurable, so measure it.** Every pass, count two numbers: new
 findings, and findings caused by the previous pass's own fixes. When the second

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

@@ -1,4 +1,4 @@
-# Gates — the two axes, and how to build one that cannot lie
+# Gates — the three axes, and how to build one that cannot lie
 
 **One job: turn a rule into something that can say no.** [`audit.md`](audit.md)
 says a class seen twice *belongs in a script*; this file is where that script comes