task-pipeline-skill 1.43.0 → 1.44.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## v1.44.0 — six lessons other projects paid for, carried home by the mechanism that exists for it
+
+`retro.publish` sends a skill-level lesson upstream as an issue. Six arrived in one day
+from projects that are not this one, and every one is a diagnosis: the class, why the
+existing doctrine did not catch it, and the fix by grade. This release is those six.
+
+| Issue | What it bought |
+|---|---|
+| #30 | a name in `verified by` **resolves**, or the row is `unknown` — never `verified` |
+| #31 | a probe that mutates a file asserts its plant landed **— now a guard** |
+| #32 | a seam is not a deliverable: an explicit REQ for the boundary, phrased as a journey |
+| #33 | the tests gate names **what each case consumes**; a timeout is unclassified, not slow |
+| #34 | stage 10 carries a `publish:` line — an unarmed path stops looking like silence |
+| #35 | a ratchet's matcher is itself a check: feed it a **near-miss it must reject** |
+
+### Two of them had already been found here, independently
+
+**#35 is the neighbour probe**, shipped in v1.42.0 after a reader defeated six guards whose
+evidence sat next to their subject. The reporting project reached it from a ratchet whose
+matcher credited every parent with its child's coverage. Same class, two routes, no
+contact — which is the strongest evidence either had.
+
+**#31 is R-001**, born here on 2026-08-03 and **retired in v1.38.0** on its own trigger:
+*"a probe harness exists that asserts the plant changed the parsed text"*. The harness does
+exist. The retirement was still premature, because the condition was *"a harness exists"*
+and the thing that mattered was *"the harness is used everywhere"*. It cost the reporting
+project three incidents in one day and this repository six in this session's own releases.
+**A retirement trigger phrased as the existence of a mechanism, rather than its reach, is
+a trigger that fires early.**
+
+### The number that took four attempts
+
+Enforcing #31 meant counting probes that mutate a file without asserting the plant landed:
+
+```
+hand-written classifier   206 of 206 already carry it   (wrong)
+the guard, first version   22 do not                    (wrong — one spelling)
+the sweep that followed    "fixed" 6 sound probes, corrupted 5
+the truth                  16
+```
+
+The guard corrected the hand count that motivated it. Then the guard was itself the class
+two sections above — keyed to one spelling, it reported as defective six probes that
+obeyed the rule in different words, and a sweep written from that verdict split five live
+statements. Found by `compile()` and a restore from git.
+
+**Every** mutating probe carries the assertion, and **no figure is written here** — the
+third attempt to put one beside it was wrong too. The count is a `grep` away and the
+guard computes it on every run; a number in prose next to a check that can count is
+restating instead of computing, which is the rule this very release imports and which
+this paragraph broke three times before it stopped trying.
+
+- Guards: 261 → **275**.
+
 ## v1.43.0 — the rail said where, and nothing said what happened
 
 A fourteen-iteration session on this repository ended each return with the same question

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.43.0 |
+| **Version** | 1.44.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.43.0",
+  "version": "1.44.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.43.0",
+  "version": "1.44.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -17,6 +17,8 @@ requirement.** It is what turns the pipeline from a funnel into a circle.
 - Several repositories — a submodule is finished when its parent says so
 - The closing question
 - The retrospective — the run's last act
+- A `verified by` name is a claim until it resolves
+- A seam is not a deliverable, and REQ rows are written against deliverables
 - GATE (manual)
 - When the answer is "something's missing"
 
@@ -201,6 +203,56 @@ GATE 10 acceptance: PASS — 14/14 REQ verified
   abstained: 2 (1 partial · 1 cannot-verify) · unlooked: 3 dormant
 ```
 
+## A `verified by` name is a claim until it resolves
+
+Reported from another project. Two rows in one run named checks that did not exist — a
+locale-parity test for a project with ten locales and no such test, an index-resolution
+test that had never been written. Both rows carried a status, an owner and an evidence
+cell. **Nothing in the artefact distinguishes *"this check exists and passed"* from *"this
+is the name a check would have if someone wrote it"*.**
+
+This file already requires the evidence to come from a check seen failing once. That
+requirement is about the **check**; nothing walks back from the **name** to ask whether a
+check by that name is on disk. The ladder walk found both, because it re-derives coverage
+from the artefact instead of reading the table — which also means the table was wrong for
+the whole run until its last gate.
+
+**So every name in a `verified by` cell resolves before the table is accepted** — to a
+file, a test name a runner will select, or a command that exits. A cell naming nothing is
+a REQ with status **`unknown`**, never `verified`.
+
+The coverage table is this pipeline's own record of what was proven. When it can carry an
+unresolvable name it stops measuring the run and starts recording the author's intent,
+which is [`gates.md`](gates.md)'s false success living inside the pipeline's own artefact.
+
+## A seam is not a deliverable, and REQ rows are written against deliverables
+
+Also reported. Two halves of a feature shipped in one run, each correct alone, each with a
+passing unit test. Together they formed a closed loop: a guard turned away users who had
+not reached a state, and the new flow that would put them into that state sat behind the
+guard. **The defect was in the seam, and a seam has no file.** The coverage table had a
+row per artefact and both rows were green.
+
+The blindness one layer down is already named — a handler test proves the handler, not the
+request path. This is that shape one layer up.
+
+**So when a run replaces a component that another component branches on, stage 2 writes an
+explicit REQ for the boundary** —
+not *"A works"* and *"B works"* but **"a user in state X reaches Y"**. Phrased as a
+journey it is testable; phrased as two artefacts it is not.
+
+**This does not contradict [`decomposition.md`](decomposition.md), and the wording matters
+because a first draft did.** That file says a REQ appearing in two modules means the seam
+runs *through* a requirement, and tells you to re-cut. A boundary REQ is not that: it is a
+single requirement about the transition, owned by **one** module — the one that consumes
+the boundary — and it maps to exactly one module like every other. Cite it as a journey
+owned by the downstream module, and both rules hold.
+
+**And where no check can span the seam** — a server-rendered redirect on one side, a
+client write on the other — the table says so under `unlooked` rather than showing two
+green rows. Two green halves reporting a working whole is exactly the shape this file
+spends its length refusing.
+
 ## GATE (manual)
 
 All of:

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

@@ -31,6 +31,8 @@ elsewhere and is not restated here:
 - Writing the check itself
 - Probing — plant, run, restore
 - 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
 - The false-positive budget
 - Ratchets
 - Disclosures — counted like a ratchet, and deliberately not monotone
@@ -347,6 +349,79 @@ the item, then match on flattened text so an emphasis marker cannot hide the bou
 where that ends*. It costs nothing and it is the only part of a check a later reader can
 disagree with before the defect arrives.
 
+## A ratchet's matcher is itself a check, and it needs a near-miss
+
+Reported from another project through `retro.publish`, and it is the neighbour probe's
+own class arrived at independently — which is the strongest evidence either has.
+
+A run built a ratchet to hold a coverage debt: a list of units with no test, a guard that
+fails when the list grows, a count printed at the gate. Exactly the shape
+[`audit.md`](audit.md) asks for instead of a deferred TODO. The guard decided whether a
+unit was covered by asking whether its identifier appeared **anywhere** in the test
+corpus. The identifiers were path-like and many were prefixes of longer ones, so every
+unit that happened to be the parent of another was credited with its child's coverage.
+
+**A ratchet whose matcher is looser than its subject shrinks itself.** It reports progress
+for work nobody did, and because a ratchet is trusted precisely so that nobody re-derives
+it, the error compounds for as long as the ratchet exists.
+
+Both existing rules were satisfied. The ratchet was printed. The guard had been seen going
+red when the list grew. Neither asks whether the matcher can tell its subject from a near
+neighbour, and that is the only question that would have caught it.
+
+**So before a ratchet is kept, feed its matcher a near-miss it must reject** — the prefix,
+the parent, the same name in a comment or an import, the longer extension. Seeing a guard
+go red on a real change proves it **reacts**; seeing it stay green on a look-alike proves
+it **discriminates**. Only the second makes its number worth trusting.
+
+**And when a matcher is corrected, re-derive the whole ratchet and print both numbers with
+the reason.** In the reporting project the corrected count was *identical* to the old one
+and the composition was not: rows credited falsely came back in as rows genuinely paid off
+went out. A single number with no delta reads as a run where nothing happened.
+
+## A green probe is evidence only if the mutation is known to have landed
+
+Also reported from another project, three times in one day, each caught only because the
+result was too good:
+
+1. a scripted substitution missed on indentation — the file was unchanged and the probe
+   measured nothing;
+2. an assertion written against a bare identifier kept matching the **import line** after
+   the field it guarded was deleted;
+3. a file-extension alternation matched the longer extension as though it were the
+   shorter, reporting nine live files as missing.
+
+In all three the observable was identical to success. *"See it fail once"* has an unstated
+precondition — **that the thing you changed is the thing the check reads** — and a planted
+defect that did not land produces the same green as a check that cannot fail.
+
+**So a probe that mutates an existing file asserts its plant landed, in the same breath as
+planting it.** A probe that writes a whole file has no such question: the file exists or
+the command failed. This repository measured itself while writing this section and got the
+number wrong three times. A hand-rolled classifier said *206 of 206 already carry it*.
+The guard written from the rule said **22 did not** — and was itself too narrow, matching
+one spelling of the assertion, so six probes that already had it in lower case were
+called defective. A sweep then "fixed" those six and **corrupted five**, splitting live
+statements. The true figure was **16**, and it took the guard, a compile check and a
+restore from git to find it.
+
+Two things are worth keeping from that. **The check corrected the measurement that
+motivated it** — which is the argument for writing checks rather than counting by hand.
+And **a check keyed to one spelling of a rule is the class two sections above**: it
+reported as defective the probes that obeyed the rule in different words. **Every**
+mutating probe carries the assertion now — the figure is deliberately not
+written here. A first draft said *201*, which was true of the branch point and false in
+the same commit, because the twelve probes added for this release are themselves mutating
+probes. The guard computes it; a number in prose beside a check that can count is the
+class this bundle calls restating instead of computing. Probes that write a whole file
+need none: the file exists or the command
+failed.
+
+**Prefer an assertion that names the construct over one that names a substring of it.** A
+guard written against a bare identifier survives the deletion of everything it guarded,
+because the identifier still appears in an import. That is case 2 above and it is the same
+class as the section before this one, one level down.
+
 ## The false-positive budget
 
 Run a new heuristic over the **real corpus** before shipping it and count the false

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

@@ -33,6 +33,7 @@ file exists to stop.
 - Write the entry only for a divergence — and name the layer that owned it
 - Every lesson carries its commit
 - The stamp table is capped at ten, and *one line per run* was never a cap
+- `publish:` is a line in the verdict, not a silence
 - Rotation — the archive is how pruning stops losing things
 - Three grades of fix — take the highest one that can work
 - Stamp first, then prune, then write
@@ -100,6 +101,42 @@ like every other rotation. **The count is printed at the prune**, beside the sta
 instructions' own count, so a table that stops rotating is visible rather than merely
 large.
 
+## `publish:` is a line in the verdict, not a silence
+
+Reported from another project, and the report is about this file: an operator asked, after
+many runs, why nothing had ever been published.
+
+The floor is right and does not move — publishing is opt-in per project, off by default,
+because an outward act taken from a generic flag is an outward act nobody authorized. The
+gap is what happens next. A project with no configuration produces, run after run,
+retrospective entries carrying lessons about **the skill**, and the mechanism reports
+nothing, because it was never armed. **An unarmed mechanism and a mechanism with nothing
+to say are indistinguishable from the outside** — [`gates.md`](gates.md)'s false success,
+applied to this bundle's own learning path. In the reporting project several runs had
+produced skill-level lessons over months; the count of published insights was zero and no
+gate had ever mentioned it.
+
+Stage 10 prints ratchets and two disclosures — what the run declined to claim, and what a
+check never looked at. Publishing is neither, so its absence is not observable at the only
+moment anyone is reading.
+
+**So stage 10's block carries one line for publication:**
+
+```
+publish: <issue url>                       — opened this run
+publish: 0 (configured, nothing insight-grade)
+publish: not configured (N insight-grade entries stayed local)
+```
+
+It arms nothing and authorizes nothing; it makes the silence legible. A count of zero
+beside *configured* is a fine answer. A **blank** where configuration is absent is how an
+instruction went unread for eight releases.
+
+**The failure mode survived its own fix, in a quieter form.** This section once said
+*"open an issue upstream"* while naming no repository, no trigger and no authorization,
+and every reader took it as done. The mechanism that replaced it is correct — and until
+this line existed it still had no way to say it never ran.
+
 ## Rotation — the archive is how pruning stops losing things
 
 At the prune, entries older than the last five run stamps **move** to

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

@@ -672,7 +672,12 @@ never that the work was skipped quietly.
   string, and the five redaction rules applied
   ([`retrospective.md`](retrospective.md) → *What may leave the project*). Absent, the
   step does not exist and is not asked about: publishing to another repository is an
-  outward act and silence authorizes none**; **the documentation gate has been seen
+  outward act and silence authorizes none. **Either way the verdict carries a `publish:`
+  line** — the issue url, `0 (configured, nothing insight-grade)`, or `not configured
+  (N insight-grade entries stayed local)`: an unarmed path and one with nothing to say
+  are otherwise indistinguishable, which is how this instruction went unread for eight
+  releases** ([`retrospective.md`](retrospective.md) → *`publish:` is a line in the
+  verdict*)**; **the documentation gate has been seen
   failing once against a planted defect and its ratchet counts are printed**
   ([`gates.md`](gates.md)); **every repository is closed — the parent included:
   `git submodule status` shows no `+`, each repo clean and pushed**; **every check this gate leans on has been seen failing

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

@@ -15,6 +15,7 @@ into this skill; nothing to install.
 - Tests that stay honest
 - Stage 6 — consolidation and the suite gate
 - When stuck
+- What a case consumes, and why a timeout is unclassified
 - Rationalizations
 - Red flags — stop and start over
 
@@ -134,6 +135,52 @@ honestly instead.
 | Setup is enormous | Extract helpers; if it's still huge, the design is the problem. |
 | Fixing a bug | Write the failing test that reproduces it first. The test proves the fix and prevents the regression. |
 
+## What a case consumes, and why a timeout is unclassified
+
+Reported from another project after hours spent reading environmental noise as product
+defects. An end-to-end suite registered a fresh account in every case. The product
+rate-limits registration to a handful per minute per address. **A suite of twenty-odd
+cases cannot avoid tripping its own product's limiter.**
+
+A throttled registration does not fail loudly. The form never advances, the case sits
+until its own timeout, and it reports **as a timeout** — which reads exactly like
+slowness. Cold compilation, hydration and a stale cache were each investigated and each
+was independently true; none was the cause.
+
+**A check that cannot run to completion in its own environment reports noise, and noise
+costs more than silence, because it looks like data.** Silence gets investigated. Noise
+gets interpreted.
+
+The neighbouring rule this bundle already has — *a check counts only where it runs* — is
+about **availability**: does the guard execute on the gate. This is about **capacity**:
+the harness is part of the system under test, and a suite that exhausts a production limit
+is measuring the limit.
+
+**So at the tests gate, name what each case consumes from the product** — accounts,
+rate-limited endpoints, external quota, seats, tokens — and confirm the suite's total
+stays under the product's own bound. Where it cannot, the suite **shares** the resource
+across cases instead of acquiring it per case.
+
+**Where the bound comes from, and what to do when it does not exist.** In order: the
+product's own configuration or code; the provider's documented limit; the operator. Write
+the answer into the brief's source ledger like any other fetched fact — a limit an agent
+remembered is a limit nobody can check. **Where none of the three answers, the row reads
+`bound: unknown` and the count goes to `unlooked`** rather than to a guess: this file's
+whole argument is that an unmeasured resource reports as a timeout, and an unmeasured
+*bound* does the same one level up.
+
+**And it does not override *The green from residue*.** That rule is about state a case
+inherits — a database, a volume, a clone — and it still says acquire fresh. This rule is
+about a resource **the product itself meters**. Where the two meet, the product's bound
+wins and the suite shares that one resource while everything else stays fresh; say which
+resource is shared and why.
+
+**And a timeout in an end-to-end suite is an unclassified result, not a slow one.** Before
+it is read as a performance signal the resource question above must have an answer, or the
+run is interpreting its own harness. In the reporting project this was also the most
+likely reason that suite had never once finished inside its CI time cap — so the cost was
+not only the hours, it was every defect the suite never got far enough to find.
+
 ## Rationalizations
 
 | Excuse | Reality |