task-pipeline-skill 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## v1.13.0 — 2026-08-05
+
+### Added — the read-back: four rules that existed and were never handed over
+
+Stages 3 and 4 produced documents stating things nobody verified: that a named
+check exists, that the spec agrees with decisions already made, that the
+self-review happened at all, and that the change still costs what it was worth.
+
+Five defects, and **four of them are one shape.** The rule already lived in this
+bundle, in a stage that never handed it to the stage which had to obey it. The
+evidence-for-checks rule sits at stages 6 and 10; the rejected-alternatives rule
+sits at stage 2; `learned.md` rule 14 has sat at stage 9 since v1.4.0. Stage 3
+names checks, contradicts decisions and writes DoDs — and read none of them back.
+
+So the fix is one mechanism applied four times. `spec.md`'s self-review now asks
+whether every check it names is real, reads back the brief's `Decisions locked`
+table **and** the alternatives stage 2 rejected, and prints the cost.
+`planning.md` asks whether every command, path and file a DoD names resolves.
+`learned.md`'s stage map binds rule 14 at 3 and 4, not only at 9.
+
+**The fifth is a genuine absence, and it prints rather than decides.** Nothing
+anywhere asked whether a change had outgrown its worth. The new checkpoint counts
+surfaces, guards and REQ rows now versus at stage 2 and prints all three — the
+stage-3 gate is the operator's, and an agent that narrows the task on its own
+judgement breaks *never narrow the task silently*.
+
+**Both self-reviews now leave a committed trace.** A `## Self-review` section,
+identical in shape across the two files, every line a **computed number rather
+than a tick** — because a number nobody computed is visible as such and a
+checkbox never is. `planning.md` already demanded the REQ set difference be
+*printed*; this extends that principle to the rest of the checklist.
+
+Three guards prove the files carry the items, with four probes. What they cannot
+prove is that a run in someone else's repository performed a self-review — and
+that boundary is stated in the spec, in the guard's own comment and here, because
+a guard claiming otherwise would be the exact defect this release fixes.
+
+Negative self-tests: 76 → 80.
+
 ## v1.12.0 — 2026-08-05
 
 ### Added — a gate for the defects an agent leaves behind

package/CONTRIBUTING.md

@@ -124,6 +124,13 @@ scripts are validated by one iterated block, not two copies, and both must keep
 `# ---------- VERDICT` marker with nothing after it.
 *(guard: `the VERDICT block must be last and must `)*
 
+**Stages 3 and 4 must keep reading their rules back.** `spec.md`'s self-review asks
+whether every check it names is real, reads back the brief's decisions and stage 2's
+rejected options, and prints the cost; `planning.md` asks whether every command a DoD
+names resolves; `learned.md` binds rule 14 at both stages. Both files carry a
+committed `## Self-review` section of computed numbers rather than ticks.
+*(guard: `the self-review no longer asks `)*
+
 **11. Every reference over 100 lines carries a `## Contents` list**, and the list is
 compared against that file's own `##` headings. The guidance asks for it because a
 long file gets previewed with a partial read; the comparison is because a hand-kept

package/README.md

@@ -129,6 +129,7 @@ until it is installed.
 | any loop | [`loop-guard.md`](plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md) — churn detection, caps, the break protocol |
 | 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 |
 | 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 |
 

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.12.0 |
+| **Version** | 1.13.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 (15 evals, 5 categories). **Never executed** — see [`evals/RESULTS.md`](evals/RESULTS.md) |
@@ -38,7 +38,7 @@ apply.
    instruction surface, and every one is linked directly from `SKILL.md`.
 2. Read `templates/docgate.sh` before seeding it; it is the only shipped script a
    host project will run on its own repository.
-3. Run `npm run test:all` — 76 guards, each with a negative self-test that plants a
+3. Run `npm run test:all` — 80 guards, each with a negative self-test that plants a
    defect and requires rejection.
 4. Run `python3 evals/run.py` for the behavioural protocol, and read
    `evals/RESULTS.md` for what has actually been observed.
@@ -54,7 +54,7 @@ apply.
 - **Versions are pinned by git tag** and mirrored into `sshlg-skills`'s catalogue.
   Rollback is `git checkout v<previous>` or pinning the previous plugin version;
   the previous version is never deleted.
-- **Behavioural evidence is missing, not merely thin.** 76 structural guards prove
+- **Behavioural evidence is missing, not merely thin.** 80 structural guards prove
   the skill is well-formed. Until `evals/RESULTS.md` carries a dated run, nothing in
   this repository proves it *behaves* — triggers correctly, stays quiet on a
   question, or performs the steps it documents.

package/cursor/rules/task-pipeline.mdc

@@ -197,6 +197,13 @@ not authorize an outward, irreversible action — stage 7 stops and asks.
    exact values every later task inherits. Self-review it for placeholders,
    contradictions, ambiguity and scope before showing it. For UI tasks, run the UX
    chain FIRST (see super-ux below) and embed it.
+   **Before handing a spec or a plan over, read your rules back:** does every
+   check you named actually exist (or say `review`)? does anything here
+   contradict a decision already locked, including an option deliberately
+   rejected? how many surfaces, guards and requirements is this now versus
+   when the design was approved — print all three and let the operator
+   decide. Leave the answers as a committed `Self-review` section of
+   computed numbers, not ticks.
 4. **Plan** (auto) — every task names the REQ ids it `Implements:`, and the set of those ids must **equal** the brief's REQ set — a difference is scope lost, print it and fix it. Zero-context tasks: exact paths, complete code in every step,
    the exact command and its expected output, TDD steps, DoD each, dependency graph
    + parallel groups, non-overlapping file ownership. **No placeholders** — no TBD,

package/evals/RESULTS.md

@@ -37,7 +37,7 @@ or it belongs in a check.
 | Dated runs recorded | **0** | 2026-08-03 |
 
 The bottom two numbers are the honest state of this skill's behavioural evidence.
-Everything else in this repository is proven by 76 structural guards that check the
+Everything else in this repository is proven by 80 structural guards that check the
 *form*; these are the only checks that would speak to the *behaviour*, and they have
 not been run yet. Printed here so "63 of 63 green" is never read as "the skill is
 known to work".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.12.0",
+  "version": "1.13.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.12.0",
+  "version": "1.13.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -154,6 +154,8 @@ answer would have exposed it in a minute.
 | 3 Spec · 4 Plan | 2 (both directions), 8 (compute, never restate) |
 | 5 Dev | 9 (generators seed green), 12 (tests create their own state), 13 (local infra) |
 | 6 Tests | 4, 5, 10, 11 — every new check probed both ways, measured, and asserted on its exit code |
+| 3 Spec | 14 — every check the spec **names** must resolve at the moment it is named, or be marked `review` |
+| 4 Plan | 14 — every command, path and file a DoD names must resolve |
 | 9 Docs | 8, 14 — every number computed, every target resolvable |
 | 10 Acceptance | 1, 3, 6, 7 — axis rotation recorded, closure verified against artefacts, classes swept, ratchets printed |
 

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

@@ -193,6 +193,34 @@ A checklist you run yourself, inline. No subagent:
 5. **Parallel safety:** no two tasks in the same group write the same file; every
    `depends:` points at a task that really produces what's consumed.
 6. **DoD present and verifiable** on every task.
+7. **Every command, path and file a DoD names resolves.** Walk each task's
+   *Definition of done* and its steps and check the targets exist — a DoD that says
+   `npm run lint:paths` when no such script exists is an instruction the implementer
+   cannot follow and a check the acceptance cannot run.
+   [`learned.md`](learned.md) rule 14 has said *every target resolvable* since
+   v1.4.0 and fired only at stage 9 — four stages after the target is written here.
+8. **Run the hygiene gate** over what this stage wrote and record its counts below.
+
+**R-003 asked of this file, and answered:** `spec.md`'s items 8 and 9 — reading
+decisions back, and printing the cost — deliberately do **not** appear here. This
+stage settles nothing (see below), so it has no decisions to contradict and no scope
+of its own to grow. Its sibling's item 7 does belong, reworded for DoDs.
+
+### The `## Self-review` section — committed, not asserted
+
+Identical in shape to `spec.md`'s, so one habit covers both stages. Last section
+before the gate; every line a **computed number, not a tick**.
+
+```markdown
+## Self-review
+
+- REQ coverage: <n> in brief, <n> covered, difference <set or ∅>
+- Named checks: <n> named, <n> resolve, <n> marked `review`
+- Decisions: checked against <the brief's D-table> and <stage 2's rejected options> — <verdict>
+- Cost: <surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>
+- Hygiene: <n> checks, <n> findings, <n> open
+- Placeholders: <n> · Ambiguity: <n> found, <n> resolved inline
+```
 
 ## This stage settles nothing — and that is a rule, not an omission
 

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

@@ -58,6 +58,7 @@ a row pointing outside the bundle is the defect this file exists to catch.
 | **The routing default and its boundary** | `templates/routing-rule.md` |
 | The seeded doc map, registers and gate | `templates/docmap.md`, `templates/decisions.md`, `templates/open-questions.md`, `templates/docgate.sh` |
 | Which agent-introduced defects are found, and that the agent fixes them rather than the script | `templates/hygiene.sh`, `references/build.md` |
+| What a stage-3/4 self-review must read back, and that its trace is computed numbers | `references/spec.md`, `references/planning.md`, `references/learned.md` |
 | What a stage reads, and which host files bind it | `references/artifacts.md` |
 | The design conversation, its hard gate, UI detection, user paths | `references/brainstorm.md` |
 | Cutting a platform into modules, brick criteria, build order | `references/decomposition.md` |

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

@@ -143,6 +143,42 @@ Read what you wrote with fresh eyes and fix inline. No subagent, no second pass:
 4. **Scope:** is this one implementable plan, or does it need decomposition?
 5. **Ambiguity:** can any requirement be read two ways? Pick one and say it.
 6. **Traceability (UI):** does every user-facing requirement name its scenario ID?
+7. **Every check this spec names resolves.** Walk the verification claims — the
+   table, and every sentence that says how something is proven. For each: does that
+   check exist today, or is this plan building it? A check that is neither is **not**
+   a verification: mark it `review` and say so, or build it. This repository's whole
+   doctrine is that a green from a check nobody watched fail is not evidence — and
+   this stage is where checks are first *named*, which is one step earlier than
+   anyone was looking.
+8. **Read the decisions back.** Open the brief's `## Decisions locked` table **and**
+   the register entries stage 2 recorded for the alternatives it *rejected*
+   (`references/brainstorm.md` → *The approved design is a set of decisions*). Does
+   any contract here contradict one? Resolve it **out loud** — amend the spec, or
+   reverse the decision and record the reversal. A spec that quietly contradicts a
+   settled decision re-opens a question the operator already answered.
+9. **Print the cost.** Count the surfaces this spec touches, the guards it adds and
+   the REQ rows, now versus at stage 2. **Print all three and decide nothing.**
+   Growth is information for the operator, whose gate this is; an agent that narrows
+   the task on its own judgement breaks *never narrow the task silently*.
+10. **Run the hygiene gate** over what this stage wrote and record its counts below.
+
+### The `## Self-review` section — committed, not asserted
+
+The checklist above leaves a **committed trace**, last section before the gate.
+Every line carries a **computed number, not a tick**: a number nobody computed is
+visible as such, and a checkbox never is. `planning.md` uses the identical shape, so
+one habit covers both stages.
+
+```markdown
+## Self-review
+
+- REQ coverage: <n> in brief, <n> covered, difference <set or ∅>
+- Named checks: <n> named, <n> resolve, <n> marked `review`
+- Decisions: checked against <the brief's D-table> and <stage 2's rejected options> — <verdict>
+- Cost: <surfaces>/<guards>/<REQ> now, <…> at stage 2 — <proportionate | grown, and why>
+- Hygiene: <n> checks, <n> findings, <n> open
+- Placeholders: <n> · Ambiguity: <n> found, <n> resolved inline
+```
 
 ## Locked contracts are decisions — the register, not only the spec
 

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

@@ -251,7 +251,10 @@ never that the work was skipped quietly.
   `SCR-` screens, the CJM stages the feature serves, and the UX
   patterns/principles from super-ux that apply (`best-practices.md`,
   `ux-design-principles.md`, `component-guidelines.md`).
-- **GATE (manual):** spec committed **and** user-reviewed; **every section carries
+- **GATE (manual):** the **`## Self-review` section written and committed with
+  computed values** — every check the spec names resolving or marked `review`, the
+  brief's decisions and stage 2's rejected options read back with no unresolved
+  contradiction, and the cost delta printed; spec committed **and** user-reviewed; **every section carries
   `covers: REQ-…` and every REQ appears in at least one section**; for UI tasks
   additionally: the super-ux chain (foundation → flows → screens → scenarios) is
   designed, validated and approved; scenarios validated in `docs/ux/scenarios.md`;
@@ -270,7 +273,8 @@ never that the work was skipped quietly.
   paths, complete code in every step, TDD steps with expected output, DoD each,
   dependency graph + parallel groups, non-overlapping file ownership, and the
   Global Constraints block copied verbatim from the spec.
-- **GATE (auto):** **set equality — the REQ ids in the brief equal the union of
+- **GATE (auto):** the **`## Self-review` section written with computed values**,
+  every command, path and file a DoD names resolving; **set equality — the REQ ids in the brief equal the union of
   `Implements:` across plan tasks.** A non-empty difference fails the gate and is
   reported as the explicit list of dropped requirements; this is the seam where
   scope leaks silently, so the check is mechanical, not a judgement call. Plus: