task-pipeline-skill 1.7.2 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## v1.8.0 — 2026-08-03
+
+### Added — the skill now meets Anthropic's own authoring guidance, measurably
+
+Audited against the four Agent Skills pages (overview, best practices, enterprise,
+API guide). Most of the spec already held — `name` 13/64 chars, `description` inside
+1024, `SKILL.md` 334/500 lines, all 23 references linked **directly** from SKILL.md,
+forward slashes only, 436 KB against a 30 MB ceiling, and the plan-validate-execute
+pattern the guidance describes is exactly the stage 3→4 set-equality check. Five
+things did not.
+
+**Every reference over 100 lines now carries a `## Contents` list — 21 files, from
+zero.** The guidance is explicit about why: *"This ensures Claude can see the full
+scope of available information even when previewing with partial reads."* That
+preview is real, and `references/stages.md` is 500 lines — an agent that previewed
+it saw stages 0 and 1 and could not learn stage 9 existed. The list is **compared
+against the file's own headings**, not merely required to be present, because a
+hand-maintained contents list is a second source that goes stale on the next
+heading.
+
+**A behavioural evaluation suite, where there was none.** 46 structural guards prove
+the skill is well-*formed*; nothing proved it *behaves*. `evals/` now carries 13
+evaluations across the five dimensions the enterprise page names — should-trigger,
+should-not-trigger, ambiguous, coexistence with super-ux, and instruction-following
+(does phase 1 really run before the first question; does stage 9 walk the matrix and
+print ratchets; does a stage-5 subagent refuse to write the register; does stage 10
+run the ladder walk before the table).
+
+`evals/run.py` validates the suite and prints the protocol. **It never reports a
+pass**, because Anthropic ships no runner and a script claiming to have executed a
+model would be the exact failure this repository is written against.
+`evals/RESULTS.md` records the honest state — *authored, zero models exercised, zero
+runs* — as a ratchet, so "46 of 46 green" is never read as "the skill is known to
+work".
+
+**A copyable run checklist and a stated degree of freedom per stage.** The guidance
+recommends a checklist Claude copies into its response for complex workflows, and
+matching specificity to fragility — high freedom in the open field, low on the
+narrow bridge. Every stage now declares which it is and why: stage 2 is high (many
+designs are valid), stages 5, 7 and 9 are low (TDD order, an irreversible deploy, a
+mechanical matrix walk).
+
+**`SKILL-CARD.md`** — the registry entry the enterprise guidance asks for (purpose,
+owner, version, dependencies, evaluation status) plus an honest pass over its
+risk-tier table. This skill scores **three High indicators** — shipped scripts, MCP
+references, tool invocations — and says so, along with the three things a consumer
+should know rather than discover: author and reviewer are the same person, commits
+are unsigned, and behavioural evidence is missing rather than thin.
+
+### Changed
+
+- **The description leads with what the skill does, then the trigger** — the shape
+  Anthropic's own examples use. The validator used to *require* the string start with
+  "Use when", which enforced the WHEN half and left the WHAT half optional; it now
+  checks for both, plus the third-person voice the guidance requires.
+- MCP tools are named fully qualified (`context7:resolve-library-id`), because
+  without the server prefix Claude may fail to locate the tool.
+
+Four new guards, each with a negative self-test watched failing.
+
 ## v1.7.2 — 2026-08-03
 
 ### Fixed — nine findings from a post-release investigation of v1.7.1

package/README.md

@@ -464,6 +464,32 @@ Code, and **any exit code other than 2 is non-blocking, so a crashing guard fail
 open** and stops guarding without announcing it. Elsewhere the run is `ungated` and
 must say so.
 
+### Held to Anthropic's own Skill authoring guidance
+
+Audited against the four Agent Skills pages. Most of it already held — `name`
+13/64 chars, `description` inside 1024, `SKILL.md` 334/500 lines, all 23 references
+linked **directly** from `SKILL.md`, 436 KB against a 30 MB ceiling. What did not,
+now does:
+
+- **Every reference over 100 lines carries a `## Contents` list**, and the list is
+  *compared against the file's own headings* rather than trusted. The guidance is
+  explicit about why: a long file gets previewed with a partial read, and
+  `stages.md` is 500 lines.
+- **A behavioural evaluation suite** (`evals/`) — 13 evaluations across the five
+  dimensions the enterprise guidance names: should-trigger, should-not-trigger,
+  ambiguous, coexistence, instruction-following. `evals/run.py` validates the suite
+  and prints the protocol; it **never reports a pass**, because no runner exists
+  upstream and a script claiming to have run a model would be the exact failure this
+  skill is written against. `evals/RESULTS.md` carries the honest state.
+- **A copyable run checklist** and a **stated degree of freedom per stage** — high
+  in the open field (brainstorm), low on the narrow bridge (TDD order, deploy, the
+  matrix walk).
+- **[`SKILL-CARD.md`](SKILL-CARD.md)** — the registry entry an enterprise reviewer
+  needs, with an honest pass over the risk-tier table. This skill scores three
+  *High* indicators and says so, along with what a consumer should know rather than
+  discover: author and reviewer are the same person, commits are unsigned, and the
+  eval suite has not been executed.
+
 ### The retrospective — the run teaches the next run, and the list stays short
 
 Every gate in this flow is good at *this* run and blind across runs. So the same
@@ -717,6 +743,8 @@ recommendation, so you arm the whole run in one exchange. Detail:
 | [`references/retrospective.md`](plugins/task-pipeline/skills/task-pipeline/references/retrospective.md) | the project retro: the three grades of fix, the mandatory prune, the cap of ten |
 | [`references/model-tiering.md`](plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md) | model policy, the `/model` reminder, overrides |
 | [`templates/`](plugins/task-pipeline/skills/task-pipeline/templates/README.md) | brief, carry-over ledger, `CONTEXT.md` and ADR skeletons, the doc map, both registers, the retro and its archive, the seeded `docgate.sh`, a worked hook |
+| [`SKILL-CARD.md`](SKILL-CARD.md) | the registry entry and risk-tier disclosure a reviewer needs before deploying it |
+| [`evals/`](evals/RESULTS.md) | the behavioural evaluation suite, its protocol, and what has actually been observed |
 | [`CHANGELOG.md`](CHANGELOG.md) | every release, with the reasoning behind it |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | dev setup, the validator, the version-sync rule, release flow |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.7.2",
+  "version": "1.8.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.7.2",
+  "version": "1.8.0",
   "author": {
     "name": "ssheleg",
     "url": "https://x.com/sshlg93"

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

@@ -1,6 +1,6 @@
 ---
 name: task-pipeline
-description: "Use when running a substantial task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, tests, lint/deploy, post-deploy log check, docs/wiki sync and acceptance — as gated stages whose doctrine is built entirely into this skill (no required companion skills). Triggers - 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline, or any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. The intake grill is mandatory - it front-loads every decision, including the per-stage autonomy sweep, so stages 1→10 run without mid-flight questions; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
+description: "Runs a substantial task through a full delivery pipeline: an intake grill that expands the request into a locked brief, then docs study, brainstorm, spec, plan, subagent build, tests, lint/deploy, post-deploy check, docs/wiki sync and acceptance — gated stages whose doctrine ships inside this skill (no required companions). Use when any substantial feature, fix or build should follow the disciplined cycle rather than ad-hoc coding, or on 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline. The grill is mandatory and front-loads every decision, so stages 1→10 run without mid-flight questions; documentation is a deliverable with its own gate; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host conventions so it stays project-agnostic."
 license: MIT
 ---
 

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

@@ -7,6 +7,19 @@ None of them asks *"does this still contain everything that was asked for?"*
 That is this stage's only job: **go back to the brief and account for every
 requirement.** It is what turns the pipeline from a funnel into a circle.
 
+## Contents
+
+- Why a stage and not a gate
+- First, the ladder walk — what the list itself is missing
+- Inputs
+- Output — the coverage table
+- Evidence, not assertion
+- Several repositories — a submodule is finished when its parent says so
+- The closing question
+- The retrospective — the run's last act
+- GATE (manual)
+- When the answer is "something's missing"
+
 ## Why a stage and not a gate
 
 The loss this catches doesn't happen inside a stage — it happens **on the seams**.

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

@@ -5,6 +5,12 @@ a resumed or handed-off run always knows where to look. This is the recommended
 structure; a host project may relocate roots via its `CLAUDE.md`, but keep the
 shape.
 
+## Contents
+
+- In the host project
+- Stage → artifact map
+- This repo (task-pipeline itself), for reference
+
 ## In the host project
 
 ```

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

@@ -14,6 +14,17 @@ This file is the method that finds those. It is **cross-cutting**: stage 10 runs
 before writing the coverage table, the program loop runs it per module, and a task
 whose whole job is "audit X" runs nothing else.
 
+## Contents
+
+- Three things that are easy to confuse
+- Why "look again, more carefully" stops working
+- The ladder
+- How one audit pass runs
+- Exit criterion — the part usually skipped
+- The three rules that stop this becoming another loop
+- When this runs
+- Rationalizations
+
 ## Three things that are easy to confuse
 
 | File | Runs when | Answers |

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

@@ -12,6 +12,18 @@ approved design — not at code.
 > the UI verdict is a required output, and the spec write-up moved to stage 3
 > ([`spec.md`](spec.md)).
 
+## Contents
+
+- The hard gate
+- Input: the brief, not a blank page
+- The loop
+- Design for isolation and clarity
+- Working in an existing codebase
+- UI detection — a required output
+- The approved design is a set of decisions — record them
+- GATE (manual)
+- Rationalizations
+
 ## The hard gate
 
 **No implementation action before the operator approves a design.** No code, no

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

@@ -29,6 +29,17 @@ the work; the gates, the artifacts and the review discipline do not. Say plainly
 that the run is inline, since a self-review is weaker evidence than a fresh
 reviewer's.
 
+## Contents
+
+- 1. Isolation
+- 2. Workspace and ledger
+- 3. Models
+- 4. The task loop
+- 5. Final whole-branch review
+- 6. Integrate, then finish
+- GATE (auto)
+- Rationalizations
+
 ## 1. Isolation
 
 Work never starts on `main`/`master` without the operator's explicit consent

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

@@ -8,6 +8,15 @@ something isn't installed.
 What remains is a short list of **optional** companions that make individual stages
 better, plus one that is required only for user-facing work.
 
+## Contents
+
+- Built in — nothing to install
+- The matrix
+- Optional bridge — substituting an external skill set
+- Preflight (emit before stage 0)
+- Credit
+- Hand-off the other direction
+
 ## Built in — nothing to install
 
 | Stage | Doctrine |
@@ -34,7 +43,7 @@ better, plus one that is required only for user-facing work.
 | Skill / tool | Needed for | Required? | Install |
 |---|---|---|---|
 | **super-ux** (`ux-foundation`, `ux-flows`, `ux-scenarios`, `ux-audit`, `/ux`, `/ux-lint`) | stage 3 UX track | **Required for any user-facing task** | `/plugin marketplace add ssheleg/super-ux` → `/plugin install super-ux@super-ux` (or `npx skills add ssheleg/super-ux`) |
-| **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
+| **context7** (MCP — call tools fully qualified: `context7:resolve-library-id`, `context7:query-docs`) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **Figma** (MCP) | stage 3 UX track, when the project designs visually — super-ux mirrors each `SCR-` screen/state into a frame | Optional, **UI + Figma-on only**. Absent → super-ux degrades to text-only *by itself and never blocks*, so shipping a UI feature with no mockups becomes a silent scope call — which is why the stage-0 sweep decides it | connect the Figma MCP server (`/mcp`, or your claude.ai connectors) |
 | **[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (`wiki-query`, `wiki-update`) | **stage 0 harvest** (query what's already known) **+ stage 9 sync** | **Recommended** — never a gate; absent → harvest runs on repo docs alone | `pip install obsidian-wiki` → `obsidian-wiki setup --vault /path/to/your/vault` |
 | **[graphify](https://github.com/Graphify-Labs/graphify)** (`/graphify`, `graphify query\|affected\|god-nodes`) | **stage 0 harvest** (reach: what calls this, what breaks if it moves) **+ stage 9 refresh + the graph↔docs divergence check** ([`knowledge-graph.md`](knowledge-graph.md)) | **Recommended** — never a gate; absent → the harvest greps instead, and the divergence axis is unavailable | `uv tool install graphifyy` → `graphify install` → `/graphify .` |

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

@@ -8,6 +8,15 @@ a time, each brick carrying its own documentation, spec, plan, build and gates.
 This runs at the end of **stage 2**, on the approved design, before any spec is
 written. It is skipped — explicitly, in writing — when the work is a single module.
 
+## Contents
+
+- When it applies
+- How to cut
+- The module map — the artifact
+- GATE (part of stage 2, manual)
+- The program loop — one brick at a time
+- Program done
+
 ## When it applies
 
 Decompose when any of these is true:

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

@@ -16,6 +16,20 @@ being written twice; write it once, here.
 
 ---
 
+## Contents
+
+- The inventory — four questions, answered before the first line of work
+- Registers and ids
+- Single source of truth
+- The Doc Loop
+- Changing your mind
+- The propagation matrix
+- Navigation
+- Intent and as-built
+- Registers are shared state
+- Where this binds in the pipeline
+- Rationalizations
+
 ## The inventory — four questions, answered before the first line of work
 
 Stage 0 answers these before the interview, and writes the answers to

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

@@ -19,6 +19,20 @@ elsewhere and is not restated here:
 
 ---
 
+## Contents
+
+- Axis A — the stage gate type
+- Axis B — the enforcement mechanism
+- Before you run a check
+- Anatomy of a project gate
+- Writing the check itself
+- Probing — plant, run, restore
+- The false-positive budget
+- Ratchets
+- Where a gate runs
+- Adding a check to an existing gate
+- Rationalizations
+
 ## Axis A — the stage gate type
 
 From [`../pipeline.schema.json`](../pipeline.schema.json), one per stage:

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

@@ -12,6 +12,16 @@ coming back to the operator.
 > half — glossary challenges, `CONTEXT.md`, ADR discipline — comes from there; the
 > autonomy sweep and the brief are this pipeline's.
 
+## Contents
+
+- Phase 1 — harvest before you ask
+- Phase 2 — the loop
+- Domain awareness
+- The autonomy sweep
+- The design destination — one file, decided here, never invented later
+- The REQ spine — the grill's other hard output
+- Output
+
 ## Phase 1 — harvest before you ask
 
 **Do not open the interview cold.** Stage 0 begins by finding what the project

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

@@ -4,6 +4,22 @@
 have.** A hook is rung 5 of [`gates.md`](gates.md)'s ladder — the only mechanism
 that acts *while the agent is working* rather than after the commit.
 
+## Contents
+
+- The limit, before the capability
+- The events
+- The `PreToolUse` contract
+- What the hook receives
+- Where it lives
+- Matchers
+- Performance
+- What belongs in a hook, and what does not
+- A worked example
+- Debugging
+- Removing them
+- Leases are not reimplemented here
+- Rationalizations
+
 ## The limit, before the capability
 
 **Hooks exist only in Claude Code.** On Cursor, Codex and the other agents a skill

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-graph.md

@@ -15,6 +15,14 @@ It is **recommended, never required**. No stage blocks on a missing graph; the
 harvest simply runs on the sources it has
 ([`knowledge-sources.md`](knowledge-sources.md)).
 
+## Contents
+
+- Detect it, and install it once
+- Stage 0 — query the graph before you ask the person
+- Stage 9 — the close-out has three artifacts, not two
+- The divergence check — the graph against the docs
+- Rationalizations
+
 ## Detect it, and install it once
 
 Detect, in this order:

package/plugins/task-pipeline/skills/task-pipeline/references/knowledge-sources.md

@@ -8,6 +8,19 @@ The same source list closes the loop at **stage 9**: what was read at the start
 what gets updated at the end. A source good enough to answer a question is a source
 that goes stale when the answer changes.
 
+## Contents
+
+- Why this is a phase and not "explore a bit first"
+- The sources, in the order to try them
+- The retro's standing instructions — an instruction source, not background
+- The code graph — recommended
+- The knowledge wiki — recommended
+- How to harvest — retrieval, not reading
+- Record it — the source ledger
+- Phase 2 — validate the answers against the harvest
+- Close the loop — stage 9 updates what stage 0 read
+- Rationalizations
+
 ## Why this is a phase and not "explore a bit first"
 
 An agent that starts asking without harvesting spends the operator's turns on

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

@@ -13,6 +13,14 @@ to be enforced and is not is the same failure as a gate that prints `FAIL` and e
 
 ---
 
+## Contents
+
+- The table — trigger · check · exit criterion
+- The incidents, so the rules are not abstract
+- The two that are not in the table, and why
+- The one instruction that would have prevented the most
+- Where these bind in the pipeline
+
 ## The table — trigger · check · exit criterion
 
 | # | Rule | Trigger | The check | Exit criterion |

package/plugins/task-pipeline/skills/task-pipeline/references/loop-guard.md

@@ -18,6 +18,14 @@ axis, don't push harder): [`audit.md`](audit.md) → *Every pass changes the axi
 Both can bind one run. Use this file's trips for edits, that file's crossover for
 searches.
 
+## Contents
+
+- Bookkeeping — the thing that makes detection mechanical
+- Detection — any one of these trips the guard
+- The break protocol
+- When to stop and hand back
+- Rationalizations
+
 ## Bookkeeping — the thing that makes detection mechanical
 
 You cannot detect churn from memory, especially after compaction. Every repeating

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

@@ -9,6 +9,18 @@ Built into this skill; nothing to install.
 > *Third-party*), extended with the dependency graph, parallel groups and
 > file-ownership rules this pipeline's stage-5 subagent build depends on.
 
+## Contents
+
+- Audience
+- Before writing tasks
+- Task right-sizing
+- Plan header — required
+- Task structure — required
+- No placeholders
+- Self-review — before handing off
+- This stage settles nothing — and that is a rule, not an omission
+- GATE (auto)
+
 ## Audience
 
 Assume a skilled developer who knows nothing about this codebase, this domain or

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

@@ -20,6 +20,17 @@ Every run writes a **stamp** and runs the **prune**. Only a run that *diverged*
 writes an entry. A retro that is empty after a messy run is the exact failure this
 file exists to stop.
 
+## Contents
+
+- Write the entry only for a divergence — and name the layer that owned it
+- Every lesson carries its commit
+- Rotation — the archive is how pruning stops losing things
+- Three grades of fix — take the highest one that can work
+- The prune — mandatory, and it runs BEFORE the new entry is written
+- The loop closes at stage 0
+- Where a lesson goes when it is not about this project
+- Rationalizations
+
 ## Write the entry only for a divergence — and name the layer that owned it
 
 An entry is owed when the run did not go as planned: a gate reopened, a stage was

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

@@ -10,6 +10,16 @@ install.
 > external helper scripts replaced by plain git commands so the doctrine works on
 > any agent.
 
+## Contents
+
+- The diff package
+- Reviewer inputs
+- Controller rules
+- The rubric
+- Prompt — task review
+- Prompt — scoped re-review
+- Prompt — final whole-branch review
+
 ## The diff package
 
 A reviewer never re-derives the diff with a dozen git calls, and the diff never

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

@@ -9,6 +9,16 @@ Writing the approved design down so a zero-context implementer — human or suba
 > *Third-party*), extended here with the UX track and the Global Constraints block
 > that stages 4–5 depend on.
 
+## Contents
+
+- Order of operations
+- UX track (user-facing tasks only)
+- Write the spec
+- Module dossier — when the run is one brick of a platform
+- Self-review — before showing it
+- Locked contracts are decisions — the register, not only the spec
+- GATE (manual)
+
 ## Order of operations
 
 For a **user-facing task** (stage-2 UI verdict = yes) the UX chain runs **first** —

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

@@ -8,7 +8,52 @@ operator's explicit go). These stages (0 intake + 1→10) are the plugin's
 `pipeline.schema.json`; a host project replaces it with its own
 stages/agents/types (see SKILL.md → *Bring your own skills*).
 
+## The run checklist — copy it, tick it
+
+Complex workflows lose steps silently. Copy this into your response at the start of
+a run and check items off as they close; it is the cheapest guard against the one
+failure this pipeline keeps paying for — a stage that *looks* done because nothing
+printed.
+
+```
+Pipeline progress
+- [ ]  0  Intake — harvest + doc inventory + reconcile, grill, REQ table, brief locked
+- [ ]  1  Docs study — every contract grounded on fetched docs, not recall
+- [ ]  2  Brainstorm — design approved, UI verdict recorded, every REQ answered
+- [ ]  3  Spec — committed, reviewed, every section covers: REQ-…
+- [ ]  4  Plan — REQ set equality holds, no placeholders, groups share no files
+- [ ]  5  Dev — tasks DONE, three verdicts each, suite green, branch integrated
+- [ ]  6  Tests — full suite green, new checks probed both ways
+- [ ]  7  Lint + deploy — clean, and the deploy authorization is specific
+- [ ]  8  Post-deploy — clean boot, or an honest degradation report
+- [ ]  9  Docs — matrix walked, registers written, docs gate green with ratchets printed
+- [ ] 10  Acceptance — ladder walk first, every REQ with evidence, retro written last
+```
+
+Each line is a **gate**, not a task: an unchecked box means the gate did not pass,
+never that the work was skipped quietly.
+
+## Contents
+
+- The run checklist — copy it, tick it
+- 0 — Intake grill — MANDATORY
+- 1 — Docs study
+- 2 — Brainstorm + decompose
+- 3 — Spec — with UX track for user-facing tasks
+- 4 — Plan
+- 5 — Dev
+- 6 — Tests
+- 7 — Lint + deploy
+- 8 — Post-deploy
+- 9 — Docs + wiki
+- 10 — Acceptance
+- The program loop — a platform, one brick at a time
+- Cross-cutting — the Doc Loop
+- Cross-cutting — the loop guard
+- Cross-cutting — the audit
+
 ## 0 — Intake grill — MANDATORY
+- **Freedom: medium** — the interview adapts to the answers; its two phases and their order do not ([`gates.md`](gates.md) → *Axis B*).
 - **Stage 0 is not optional and not skippable.** There is no "small enough task"
   exemption, no "the request was already clear" exemption, no starting stage 1
   "while the operator thinks". The only sanctioned bypass is the
@@ -109,15 +154,17 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   reversible calls can be deferred with a note). Only then start stage 1.
 
 ## 1 — Docs study
+- **Freedom: medium** — which sources to fetch is judgement; grounding contracts on fetched docs is not ([`gates.md`](gates.md) → *Axis B*).
 - **What:** ground every external library / API / SDK the task touches on the
   *current* docs, before locking any contract.
-- **Invoke:** `context7` MCP (`resolve-library-id` → `get-library-docs`, scope by
-  `topic`) or the `context7-docs` skill. Web-search fallback for libs context7
+- **Invoke:** the `context7` MCP — `context7:resolve-library-id` → `context7:query-docs`,
+  scoped by topic or the `context7-docs` skill. Web-search fallback for libs context7
   can't resolve.
 - **GATE (auto):** every contract the design will lock is grounded in fetched docs,
   not recall. Unresolvable libraries are flagged in the spec.
 
 ## 2 — Brainstorm + decompose
+- **Freedom: high** — many designs are valid — this is the open field, and the only fixed thing is the gate ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`brainstorm.md`](brainstorm.md)** — built into this skill. Read
   the brief first (stage 0 already answered scope/constraints/done-criteria), then
   explore the codebase, scope-check for decomposition, one question at a time, 2–3
@@ -147,6 +194,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   contracts named with their owner.
 
 ## 3 — Spec — with UX track for user-facing tasks
+- **Freedom: medium** — what the contract says is judgement; which contracts must be locked is a list ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`spec.md`](spec.md)** — built into this skill: the UX-track order,
   what the spec must lock (types, schemas, signatures, file layout, the **Global
   Constraints** block stages 4–5 depend on), the self-review pass and the operator
@@ -202,6 +250,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan
+- **Freedom: low** — the task format is prescribed and the REQ set-comparison is mechanical ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`planning.md`](planning.md)** — built into this skill →
   `docs/superpowers/plans/YYYY-MM-DD-<topic>.md` (same slug as the brief and the
   spec). Zero-context tasks, exact
@@ -220,6 +269,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   same change (super-ux *same-change* rule).
 
 ## 5 — Dev
+- **Freedom: low** — TDD order, worktree isolation and 'a subagent never writes the register' are the narrow bridge ([`gates.md`](gates.md) → *Axis B*).
 - **How it runs: [`build.md`](build.md)** — built into this skill: isolate the
   workspace (native worktree tool first, git fallback, baseline tests), keep a
   ledger under `.task-pipeline/build/<plan>/` so a compacted context can resume,
@@ -241,6 +291,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   "leave it" recorded).
 
 ## 6 — Tests
+- **Freedom: low** — green means the full suite, and no skip smuggles a red one past ([`gates.md`](gates.md) → *Axis B*).
 - **What:** consolidate test coverage for the change: confirm new functionality
   has tests (written test-first in stage 5), update/repair existing tests the
   change touched, and add edge-case + failure-path tests per DoD.
@@ -254,6 +305,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   ([`audit.md`](audit.md)).
 
 ## 7 — Lint + deploy
+- **Freedom: low** — outward and irreversible — the authorization floor is exact or the stage stops ([`gates.md`](gates.md) → *Axis B*).
 - Read host conventions (`conventions.md`): run the linter; fix failures. The suite
   is already green from stage 6 — re-run it if code changed since. For UI projects,
   the **super-ux linter** (`python3 docs/ux/lint.py` / `/ux-lint`) is part of lint —
@@ -268,12 +320,14 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   operator go. Respect deploy-from-main rules if the project mandates them.
 
 ## 8 — Post-deploy
+- **Freedom: medium** — where the logs live varies; 'clean boot or an honest degradation report' does not ([`gates.md`](gates.md) → *Axis B*).
 - Tail deploy logs / health-check per conventions. Confirm clean boot, no error
   spike, live subsystems healthy.
 - **GATE (auto):** clean boot confirmed, or an **honest degradation report** with next
   steps — never silent success.
 
 ## 9 — Docs + wiki
+- **Freedom: low** — the matrix walk and the gate are mechanical; what a doc says is not this stage's call ([`gates.md`](gates.md) → *Axis B*).
 - **The propagation sweep runs first** ([`documentation.md`](documentation.md)).
   The ledger below names the documents you **read**; the matrix in `docs/DOCMAP.md`
   names the documents you **owe**. They are not the same list, and the gap between
@@ -327,6 +381,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   carry-over count printed beside this verdict**.
 
 ## 10 — Acceptance
+- **Freedom: medium** — the walk and the evidence rule are fixed; whether it is what was asked for is the operator's ([`gates.md`](gates.md) → *Axis B*).
 - **What:** the closing stage — go back to the brief and account for **every**
   requirement. Doctrine: [`acceptance.md`](acceptance.md). Every earlier gate asks
   "is this artifact good?"; none asks "does this still contain everything that was

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

@@ -7,6 +7,16 @@ into this skill; nothing to install.
 > [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
 > *Third-party*), with the stage-6 suite gate added.
 
+## Contents
+
+- The iron law
+- Red → green → refactor
+- Tests that stay honest
+- Stage 6 — consolidation and the suite gate
+- When stuck
+- Rationalizations
+- Red flags — stop and start over
+
 ## The iron law
 
 ```