task-pipeline-skill 1.47.0 → 1.47.2

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## v1.47.2 — the body stopped retelling its own references
+
+`Prerequisites` was 2585 of the body's 6585 tokens, and most of it was a second
+telling: super-ux, the bridge, the grill, the harvest, the documentation gate and the
+retrospective each have a reference that carries them in full. The body now keeps what
+a reference cannot — the traps, and the one hard requirement — and points at the rest.
+
+What stayed inline, deliberately: **the stage-3 spec gate stops** on a UI task with no
+super-ux; the grill's single sanctioned bypass; **the retro is read two ways** and the
+difference matters (standing instructions in full because they bind and are bounded,
+the recent log queried because nothing caps it); a stale code graph is a false premise
+**carrying the authority of a machine**, since a wrong doc gets argued with and a wrong
+graph gets believed; and the operator outranks any document **only out loud**.
+
+~6585 → ~6180 tokens against a 5000 budget. **Still over, and the rest is not a trim.**
+What remains is `How to run` and `Stages` — the operating instructions themselves —
+and moving those out is a decision about what a reader must have in hand before the
+first stage, not a compression exercise. It is coupled to the description question the
+v1.47.0 entry recorded: both are about what this one file is obliged to carry.
+
+## v1.47.1 — the fixes a reader found, which three releases shipped without
+
+v1.46.0 was tagged and published from a commit that carried this branch's doctrine and
+none of the three commits answering the reviewer. The defects below were already found
+and already fixed when the release went out; this is them arriving.
+
+**`docs/DOCMAP.md` forbade the register shipping beside it.** It said, in as many words,
+that no `docs/DECISIONS.md` is created here deliberately — and the release shipped that
+file. The old rule was right about the risk and wrong about the mechanism: `OQ-####`
+closes with `Resolved→DEC-####`, and a CHANGELOG version heading cannot be that target,
+because two decisions in one release collapse to a single pointer. SSOT is kept by
+direction now — the reason lives in `DECISIONS.md`, the CHANGELOG points at the id. The
+reversal is `DEC-0003`, because a register that appears without a decision is exactly
+the fork the old rule feared.
+
+**`HOW-IT-WORKS.md` called itself the version it was written under.** Its first line
+promises a rewrite every release and names the banner as the freshness signal; the
+banner read 1.45.0 while every other surface read 1.46.0. Corrected, and the two
+releases that landed from another session are named for what they were, so the gap in
+the version history is explained rather than silent.
+
+**An absolute rule keeps every keyword while an appended clause reverses it.** This
+release found that class, guarded it on stage 10's criterion 13, and left `residue.md`'s
+two absolute rules on plain substring presence — *"never released by this run, unless it
+has clearly expired"* passed. Sweeping the fix to its siblings then produced the reason
+to sweep it structurally: the second copy of the carve-out pattern had its escaping
+doubled, so it matched a literal backslash and walked past every inversion while looking
+correct. One home now — `_EXCEPTION_MARKER` and the `_carve_out` helper that reads it —
+with two call sites.
+
+**A probe demanded a dependency the harness disclaims.** `res8` required PyYAML to be
+installed; the guard it tests degrades honestly without it. `test:all` was red on any
+machine lacking it. Three branches now: the guard fired, the guard said it could not
+look, or neither — and only the third is an error.
+
+Also: the owner-row check went through `_row_cells` instead of a hand-rolled regex, as
+that helper's own docstring asks; and a reflow that fixed a 157-character line had
+orphaned two words onto a five-character one.
+
+Guards: 291 → **294**.
+
 ## v1.47.0 — a green suite that cannot speak for an agent
 
 The suite gate at stage 6 assumes the thing under test is deterministic: run it twice,

package/HOW-IT-WORKS.md

@@ -5,7 +5,7 @@ explains the machine — what routes a request into it, what each stage refuses
 let past, and what makes any claim it prints believable. The README sells it and
 tells you how to install it; this file tells you how it thinks.
 
-> **Version 1.45.0.** The "What changed" section at the bottom carries the last
+> **Version 1.47.1.** The "What changed" section at the bottom carries the last
 > few releases. Everything above it describes the pipeline as it is *now*, not as
 > it was designed.
 
@@ -238,7 +238,7 @@ This is the part most pipelines skip, and it is the reason this one is trustwort
 rather than merely tidy.
 
 **Every guard is proven against a planted defect.** `npm run test:all` breaks the
-thing each of the **291** checks is about, and requires that check to reject it. A
+thing each of the **294** checks is about, and requires that check to reject it. A
 guard that has never been watched failing is not a guard; it is a comment.
 
 **The neighbour probe.** A check has a *subject* — the rule it is about — and
@@ -291,7 +291,28 @@ a run diverges  →  retro entry  →  retro.publish  →  upstream issue
 
 ## What changed, by version
 
-### v1.45.0 — what a run leaves running, what "done" costs to say, what a check is for
+### v1.47.1 — the fixes a reader found, which three releases shipped without
+Three releases went out from another session while this branch was reviewed, and
+each carried the same defects forward: the doc map forbidding the decisions register
+shipping beside it, this file naming a version two releases stale, two absolute rules
+invertible by an appended clause, a probe demanding PyYAML the harness disclaims, and
+a probe that stopped reproducing its own hazard when its target string was quoted —
+which leaves `main`'s own suite red. Every one was found and fixed before the first
+of those releases; this is them arriving.
+
+### v1.47.0 / v1.46.0 — shipped from another session
+A green suite that cannot speak for an agent; and this branch's residue, completion
+honesty, proportionate verification and improvement-iteration doctrine, which reached
+main through the merge commit rather than through this branch's own release.
+
+v1.46.0 was tagged from a commit carrying this branch's doctrine and none of the
+three commits answering its reviewer. The doc map forbade the decisions register
+shipping beside it; this file called itself the version it was written under; two
+absolute rules were guarded by substring alone and inverted by an appended clause;
+and a probe demanded PyYAML the harness disclaims. All four were found and fixed
+before the release went out, and arrived after it.
+
+### v1.46.0 — what a run leaves running, what "done" costs to say, what a check is for
 Four rules the pipeline had been following by disposition rather than by doctrine.
 **Residue**: eight classes of thing a run leaves running or leaves behind, enumerated
 by class and never by one tool — the case that produced it was a task inventory
@@ -304,6 +325,12 @@ the deliverable is the working result and the check is how you know — scaled t
 issue resolves when behaviour changed and its close names the address; unworked ones
 accumulate visibly rather than being triaged into silence. Guards: 275 → 291.
 
+### v1.45.1 / v1.45.0 — shipped from another session while this branch was paused
+The reference routing existed three times over and was cut to one home; the guard
+count the self-test plants into was restored. Neither is this branch's work — they
+are here because they hold the version numbers this branch was originally built
+under, which is why it ships as 1.46.0.
+
 ### v1.44.0 — six lessons from other projects, and the guards that hold them
 Six issues published by runs in other repositories were worked into doctrine:
 seam testing at stage 6, `verified by` names that must resolve, a probe's green

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

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

@@ -74,98 +74,66 @@ gate stops until it is installed.
 | 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` |
 
-**Optional bridge.** If the operator already runs an equivalent skill set (e.g.
+**Optional bridge.** An equivalent skill set the operator already runs (e.g.
 `superpowers:brainstorming` / `writing-plans` / `subagent-driven-development` /
-`using-git-worktrees` / `test-driven-development`), it can be mapped onto stages
-2/4/5/6 in `pipeline.json` → `skills[]`. That is a **substitution, never a
-requirement**: the built-in doctrine is normative, the gates in
-`references/stages.md` still govern, and nothing detects, recommends or waits for
-an external provider.
-
-**super-ux — recommended for ANY user-facing task.** The moment a task implies a
-user interface (web / mobile / CLI / TUI — a screen, a command, a visible
-behavior; the stage-0 grill detects this early), super-ux is the recommended
-workflow for the WHY→UI→scenario chain (`/ux`, `ux-foundation`, `ux-flows`,
-`ux-scenarios`, `/ux-lint`).
-- **Already installed?** (does `/ux` or `super-ux:ux-foundation` resolve) → **use
-  it**: `/ux` at intake, then the stage-3 UX track walks its traced chain —
-  `ux-foundation` (personas, JTBD, CJM, stories) → `ux-flows` (user flows +
-  `screens.md`, Figma frames when on) → `ux-scenarios` (traced scenarios) → the
-  `/ux-lint` linter (`docs/ux/lint.py`) must pass. Wire that linter into the host
-  CI/pre-commit so UX drift can't merge.
-- **Not installed?** → recommend it and give the install line right away:
-  ```
-  /plugin marketplace add ssheleg/super-ux
-  /plugin install super-ux@super-ux
-  ```
-  (or `npx skills add ssheleg/super-ux`). For UI tasks the spec gate **requires**
-  it — install before stage 3, otherwise stop and ask the operator to install.
-
-**The grill is built in — no companion skill, nothing to install.** Stage 0 ships
-with this skill: the full doctrine lives in `references/grill.md`
-(interview loop, domain awareness, autonomy sweep, output). It is **mandatory** —
-no "clear enough task" exemption, no starting stage 1 without a committed,
-operator-confirmed brief. The one sanctioned bypass is the entry-from-super-ux
-short-circuit, and even that demands a scope confirmation.
-
-It also produces the **REQ spine**: the request as an addressable list of
-requirements, each naming how it will be verified. Stages 3–5 trace to those ids,
-stage 4's gate is a mechanical set-comparison against them, and **stage 10 accounts
-for every one** — which is what turns the pipeline from a funnel into a circle.
-
-**Harvest before you ask.** Stage 0 opens with a **knowledge harvest**
-(`references/knowledge-sources.md`), not a
-question: pull what the project already knows about this task from the code, the
-**code graph** if one is built
-(`references/knowledge-graph.md` — graphify;
-recommended, never required),
-`CLAUDE.md`, `CONTEXT.md`/ADRs, **the decision register**, `docs/` + `docs/ux/`,
-past pipeline briefs, **the retro's standing instructions and run stamps** —
-`docs/superpowers/retro.md`, read in full because they *bind* this run and are
-bounded by construction (ten rows; one line per run), while its **recent log** and the
-archive under `docs/superpowers/retro/` are **queried** by the task's nouns
-(`references/retrospective.md`) —
-the **knowledge wiki** if one is installed
-([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended, never
-required) and any **other repo or hosted doc system the project names as its
-docs**. Write the source ledger into the brief, then interview *against* it: every
-answer that touches a source is checked against that source, and the operator
-outranks any document — but only out loud, so an override is a recorded decision
-instead of an undetected divergence. The same ledger is stage 9's work list.
+`using-git-worktrees` / `test-driven-development`) can be mapped onto stages 2/4/5/6
+in `pipeline.json` → `skills[]`. That is a **substitution, never a requirement**: the
+built-in doctrine is normative, the gates in `references/stages.md` still govern, and
+nothing detects, recommends or waits for an external provider.
+
+**super-ux — recommended for ANY user-facing task**, and the one thing that can stop a
+gate. The moment a task implies an interface (web / mobile / CLI / TUI — the stage-0
+grill detects it early), the WHY→UI→scenario chain runs through `/ux`,
+`ux-foundation`, `ux-flows`, `ux-scenarios` and the `/ux-lint` linter, which belongs in
+the host's CI so UX drift cannot merge. **Not installed on a UI task? The stage-3 spec
+gate stops** — offer `/plugin marketplace add ssheleg/super-ux` and
+`/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) and wait.
+Details: `references/companion-skills.md`.
+
+**The grill is built in and mandatory** (`references/grill.md`). No "clear enough task"
+exemption, no stage 1 without a committed, operator-confirmed brief; the one sanctioned
+bypass is the entry-from-super-ux short-circuit, and even that demands a scope
+confirmation. It produces the **REQ spine** — the request as an addressable list, each
+row naming how it is verified. Stages 3–5 trace to those ids, stage 4's gate is a
+mechanical set-comparison against them, and **stage 10 accounts for every one**, which
+is what turns the pipeline from a funnel into a circle.
+
+**Harvest before you ask** (`references/knowledge-sources.md`). Stage 0 opens by
+pulling what the project already knows about *this* task — the code and its graph,
+`CLAUDE.md`, `CONTEXT.md`/ADRs, the decision register, `docs/` and `docs/ux/`, past
+briefs, the wiki, and whatever else the project names as its docs. **The retro is read
+two ways and the difference matters:** its standing instructions and run stamps are
+read **in full** because they bind this run and are bounded by construction; its recent
+log and archive are **queried** by the task's nouns, because nothing caps them
+(`references/retrospective.md`). Write the source ledger into the brief and interview
+*against* it: every answer touching a source is checked against it, and the operator
+outranks any document — **but only out loud**, so an override is a recorded decision
+rather than an undetected divergence. That ledger is also stage 9's work list.
 
 **Three artifacts close a run, not two.** Stage 9 syncs the docs, the wiki **and the
-code graph** (`/graphify . --update`) — the graph is what the *next* run's harvest
-queries first, so a stale one is a false premise carrying the authority of a
-machine. Refreshing it also buys the **graph↔docs divergence check**: a hub no
-document names, an edge the docs deny, a doc naming a module the graph no longer
-has. Doc-side findings are fixed at stage 9; absences become REQ rows at stage 10
-(`references/knowledge-graph.md`,
-`references/audit.md`).
-
-**Documentation is a deliverable, and it has a gate**
-(`references/documentation.md`). Stage 0's harvest
-reads what the project knows; a second phase asks the four questions that make it a
-*system* — where settled things live, what each fact's single home is, what a change
-of type X obliges, and what proves it — and writes them to `docs/DOCMAP.md`. From
-then on the **Doc Loop** fires whenever anything is settled, at **any** stage, not
-only at stage 9; the stage-9 sweep walks the **propagation matrix** (the harvest
-ledger names what you *read*, the matrix names what you *owe*); and *"docs in sync"*
-stops being an assertion and becomes a command with an exit code. Governance is a
-by-product: the run already produces decisions, so recording one is transcription
-plus a stable id, never a second act of thinking.
-
-**The run teaches the next run — and the list stays short.** Every gate is good at
-*this* run and blind across runs, so the same class of failure can be caught, fixed
-and forgotten five times with nothing noticing it is the same one. The last act of
-stage 10 is therefore the **retrospective**
-(`references/retrospective.md`, written to
-`docs/superpowers/retro.md`): **stamp the run first** — one line, and the only thing
-that makes the next step computable — **then prune**, every standing instruction
-checked against its retirement triggers (it became a check · its surface is gone · it
-hasn't fired in five run stamps **or in sixty days** — the calendar is the unit that
-still moves when the stamp counter has stopped), the list held to a hard cap of **ten**, every
-deletion logged, then write an entry **only if the run diverged** (symptom, the
-stage that *owned* it, root cause, fix, and the check that catches it next time).
+code graph** (`/graphify . --update`). The graph is what the next run's harvest queries
+first, so a stale one is a false premise **carrying the authority of a machine** —
+a wrong doc gets argued with, a wrong graph gets believed. Refreshing it buys the
+graph↔docs divergence check; doc-side findings are fixed at stage 9, absences become
+REQ rows at stage 10 (`references/knowledge-graph.md`, `references/audit.md`).
+
+**Documentation is a deliverable, and it has a gate** (`references/documentation.md`).
+A second stage-0 phase asks the four questions that make docs a *system* — where
+settled things live, each fact's single home, what a change of type X obliges, what
+proves it — and writes them to `docs/DOCMAP.md`. From then the **Doc Loop** fires
+whenever anything is settled, at **any** stage rather than only at stage 9; the stage-9
+sweep walks the **propagation matrix** (the harvest ledger names what you *read*, the
+matrix names what you *owe*); and *"docs in sync"* becomes a command with an exit code.
+
+**The run teaches the next run, and the list stays short**
+(`references/retrospective.md`). Every gate is good at *this* run and blind across
+runs, so one class of failure can be caught, fixed and forgotten five times with
+nothing noticing it is the same one. Stage 10's last act: **stamp the run first** — the
+only thing that makes the next step computable — **then prune** every standing
+instruction against its retirement triggers, hold the list to a hard cap of **ten**,
+log every deletion, and write an entry **only if the run diverged** (symptom, the stage
+that *owned* it, root cause, fix, and the check that catches it next time).
+
 Stage 0 reads those standing instructions in full, which is exactly why the prune is
 a gate criterion and not a good intention: a rule nobody reads to the end is worse
 than no rule, because everyone believes it is covered. **The order is load-bearing,