task-pipeline-skill 0.10.0 → 0.17.1

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

@@ -1,46 +1,98 @@
-# Companion skills — what powers each stage, how to install, what to run
+# Companions — what's built in, what's optional, what to install
 
-task-pipeline is a thin orchestrator; the actual work is done by companion
-skills. Preflight-detect each one; if a needed skill doesn't resolve, **give the
-operator the install line immediately** and (for required ones) stop until it's
-installed. Never silently degrade a required capability.
+**The pipeline's doctrine is entirely built into this skill.** Stages 0, 2, 3, 4, 5,
+6 and 10 run from `references/*.md` — no companion plugin, no resolution step, no
+fallback path, no version skew, and no failure mode where a stage can't run because
+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.
+
+## Built in — nothing to install
+
+| Stage | Doctrine |
+|---|---|
+| 0 Intake grill | `references/grill.md` |
+| 2 Brainstorm | `references/brainstorm.md` |
+| 2 Decompose (platforms only) | `references/decomposition.md` |
+| 3 Spec | `references/spec.md` |
+| 4 Plan | `references/planning.md` |
+| 5 Build (isolation, subagents, fix loop) | `references/build.md` + `references/review.md` |
+| 5–6 TDD + suite gate | `references/tdd.md` |
+| 10 Acceptance (REQ close-out) | `references/acceptance.md` |
+| any repeating loop | `references/loop-guard.md` |
 
 ## The matrix
 
 | Skill / tool | Needed for | Required? | Install |
 |---|---|---|---|
-| **superpowers** (`brainstorming`, `writing-plans`, `subagent-driven-development`, `using-git-worktrees`, `test-driven-development`) | stages 2, 4, 5, 6 | **Required** (always) | `/plugin marketplace add obra/superpowers` → `/plugin install superpowers@superpowers` |
 | **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`) |
-| **grill-me** / **grilling** | stage 0 intake grill | Optional (built-in grill loop is the fallback) | `npx skills add mattpocock/skills`, or the engineering-advanced-skills marketplace |
 | **context7** (MCP) | stage 1 docs study | Recommended (web-search fallback) | connect the context7 MCP server |
 | **wiki-update** | stage 9 wiki sync | Optional (skip wiki if absent) | user's wiki skill set |
+| ~~superpowers~~ | — | **Not a dependency.** Stages 2/4/5/6 run on the built-in doctrine above. See *Optional bridge* | — |
+| ~~grill-me / grilling~~ | — | **Not a dependency.** The stage-0 grill is built in (`references/grill.md`) | — |
+
+## Optional bridge — substituting an external skill set
+
+An operator who already runs an equivalent skill set may map it onto stages 2/4/5/6
+in their `pipeline.json` → `skills[]`, e.g. `superpowers:brainstorming`,
+`superpowers:writing-plans`, `superpowers:using-git-worktrees`,
+`superpowers:subagent-driven-development`, `superpowers:test-driven-development`.
+
+Rules for that bridge:
+
+- **It is a substitution, never a requirement.** Nothing detects it, nothing
+  recommends it, nothing waits for it, and its absence is never an error.
+- **The gates still govern.** Whatever runs a stage, `stages.md` decides when the
+  stage is done.
+- **Never mix providers inside one stage** — either the built-in doctrine runs it or
+  the substitute does; interleaving two review loops produces neither.
 
-## Preflight recommendation (emit before stage 0)
+## Preflight (emit before stage 0)
 
-At the very start, detect which of the above resolve and print ONE recommendation
-block so the operator can arm the full flow before work begins. Example:
+Detect the optional companions and print ONE block — companions **plus the model
+decision** (`model-tiering.md`), so the operator arms the whole run in a single
+exchange:
 
 ```
-Pipeline companions:
-  ✓ superpowers        — ready
-  ✗ super-ux           — this task looks user-facing; recommended. Install:
+Pipeline companions (stage doctrine is built in — nothing to install for it):
+  ✗ super-ux           — this task looks user-facing; required for the UX track:
                            /plugin marketplace add ssheleg/super-ux
                            /plugin install super-ux@super-ux
   ✓ context7           — ready
-  ✗ grill-me           — optional; falling back to the built-in grill loop
   ✓ wiki-update        — ready
-Recommend installing the ✗ items marked recommended, then say "continue".
+
+🧠 Model for this run: recommended <top tier available>. You're on <current>.
+   /model <id> to switch, or "keep current", or name per-stage overrides.
+
+Install the ✗ items you want, answer the model line, then say "continue".
 ```
 
 Rules:
-- Only flag **super-ux** as recommended when the task implies a UI (the stage-0
-  grill decides this; when unsure, flag it — a false positive costs one install).
-- **superpowers** missing → stop; it's required for the core stages.
+
+- Only flag **super-ux** when the task implies a UI (the stage-0 grill decides;
+  when unsure, flag it — a false positive costs one install).
+- **Never gate any stage on an install** except the stage-3 UX track on a UI task.
 - Optional tools missing → state the fallback, don't block.
 - Re-detect after the operator installs; don't assume.
+- The model answer goes into the brief. Don't ask again per stage
+  (`model-tiering.md` → *Mechanic*).
+
+## Credit
+
+The built-in doctrine is **ported, not depended on**:
+
+- The stage-0 grill is adapted from Matt Pocock's `grilling` / `grill-with-docs`
+  skills (MIT, https://github.com/mattpocock/skills).
+- Stages 2–6 are adapted from the `brainstorming`, `writing-plans`,
+  `using-git-worktrees`, `subagent-driven-development`, `test-driven-development`
+  and `requesting-code-review` skills in obra/superpowers (MIT,
+  https://github.com/obra/superpowers).
+
+Both notices live in the repo `LICENSE` → *Third-party*.
 
 ## Hand-off the other direction
 
-super-ux's `/ux` menu can hand off *to* this pipeline (its "execute
-autonomously" action). When entered that way the UX chain already exists — see
-`stages.md` → 0 *Entry-from-super-ux short-circuit*: verify, don't rebuild.
+super-ux's `/ux` menu can hand off *to* this pipeline (its "execute autonomously"
+action). When entered that way the UX chain already exists — see `stages.md` → 0
+*Entry-from-super-ux short-circuit*: verify, don't rebuild.

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

@@ -1,4 +1,4 @@
-# Host conventions (stages 6–9)
+# Host conventions (stages 6–10)
 
 The orchestrator is project-agnostic. For tests / lint / deploy / docs / wiki it reads the
 **host project's `CLAUDE.md` / `AGENTS.md` first**, then falls back to detection.
@@ -33,3 +33,13 @@ found, surface it and **ask** rather than guessing.
 - Host self-update rules (module docs, runbooks, agent-self cards, etc.) — update
   in the same change. Wiki: the `wiki-update` skill (resolves the vault via
   `~/.obsidian-wiki/config`). Fix dangling links.
+
+## Issue tracker (stage 10)
+
+Acceptance parks what wasn't delivered: every `deferred` REQ and every unresolved
+carry-over row needs a **home** — an issue, a backlog entry, a ticket id. Read the
+host's convention (`CLAUDE.md` usually names the tracker and the id format; else
+detect: a `.github/ISSUE_TEMPLATE/`, a Linear/Jira reference in recent commits, a
+`TODO.md`). Never invent a tracker, and never close a run on "we'll remember it" —
+if no tracker exists, write the row into the repo's backlog file and say where it
+went.

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

@@ -0,0 +1,139 @@
+# Decomposition — cutting a platform into bricks
+
+A one-feature task goes through the pipeline once. A **platform** — anything whose
+brief describes more than one deliverable, more than one surface, or a system
+rather than a change — must be cut into modules first, and then built one brick at
+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.
+
+## When it applies
+
+Decompose when any of these is true:
+
+- the brief names several independent capabilities ("accounts, billing, reporting");
+- the work spans several surfaces (API + web + worker) that could ship separately;
+- the REQ table has requirements that no single deliverable satisfies together;
+- the design's units have their own data and could plausibly be owned by different
+  people.
+
+Otherwise record one line in the design — `single module: <name>` — and go to
+stage 3. A skipped decomposition is a decision, never an omission.
+
+## How to cut
+
+**By capability, not by layer.** "Ordering", "Billing", "Notifications" are
+modules. "Controllers", "Services", "Database" are not: a layer cut forces every
+feature to touch every module, which is the opposite of a brick.
+
+A module is a **brick** when all of these hold:
+
+1. **Independently specifiable** — you can write its dossier without deciding
+   another module's internals.
+2. **Independently buildable and testable** — its tests pass without another
+   module's implementation present (stubs at the contract are fine).
+3. **Owns its data** — the entities it is the source of truth for belong to it, and
+   nothing else writes them.
+4. **Talks through declared contracts only** — every cross-module interaction is a
+   named API, event or schema, listed in both modules' dossiers.
+5. **Deliverable on its own** — landing it leaves the system working, even if the
+   capability is not yet reachable by users.
+
+If a candidate fails (2) or (3), the cut is in the wrong place: either merge it
+into its neighbor or move the disputed data to the module that truly owns it.
+
+**Order the bricks:**
+
+- **The walking skeleton first.** The first module is the thinnest end-to-end slice
+  that proves the architecture — one real path through the system, however small.
+  Building three "foundation" modules before anything runs end-to-end hides
+  integration risk until the worst possible moment.
+- Then topological order: nothing is built before what it depends on.
+- **No cycles.** A cycle means the cut is wrong. Break it by moving the shared
+  concept into its own module, or by turning one direction of the dependency into
+  an event the other module subscribes to. Record which you chose and why.
+
+## The module map — the artifact
+
+Write `docs/superpowers/specs/YYYY-MM-DD-<topic>-modules.md` and commit it. It is
+the program's spine: every later run reads it, and its status column is how a
+resumed session knows where the program stopped.
+
+```markdown
+# Module map — <platform>
+
+Build order is top to bottom. Status: `planned` → `in progress` → `done` |
+`deferred`. One row per module, no exceptions.
+
+| # | Module | Delivers | Owns (entities) | Depends on | Contracts exposed | UI? | REQs | Status |
+|---|---|---|---|---|---|---|---|---|
+| 1 | ordering | place and track an order | Order, OrderLine | — | `POST /orders`, `OrderPlaced` event | yes | REQ-001, REQ-004 | planned |
+| 2 | billing | charge for a placed order | Invoice, Payment | ordering | `InvoiceIssued` event | no | REQ-002 | planned |
+
+## Cut rationale
+
+<why these seams and not others; what was merged or split, and what a cycle forced>
+
+## Cross-module contracts
+
+<one block per contract: owner module, consumer(s), exact shape (schema or
+signature), and the failure behavior when the other side is unavailable>
+
+## Deferred to later modules
+
+<capabilities deliberately postponed, with the module that will carry them>
+```
+
+Every REQ from the brief appears in exactly one module's `REQs` cell. A REQ that
+fits nowhere means the map is incomplete; a REQ in two modules means the seam runs
+through a requirement — re-cut or split the REQ.
+
+## GATE (part of stage 2, manual)
+
+Together with the design approval:
+
+1. Every module satisfies the brick criteria, or its exception is written down.
+2. The dependency graph is acyclic and the build order is topological.
+3. The first module is a walking skeleton, or the reason it isn't is recorded.
+4. Every REQ maps to exactly one module.
+5. Cross-module contracts are named (shape can be locked later, in each module's
+   spec — but the *existence* and *owner* of each contract is decided here).
+6. The operator approves the map and the order.
+
+## The program loop — one brick at a time
+
+After the map is approved, the pipeline runs **per module**, in build order:
+
+```
+module N → stage 3 (dossier/spec) → 4 plan → 5 build → 6 tests
+         → 7 lint + deploy → 8 post-deploy → 9 docs + wiki → 10 acceptance
+         → mark module done → module N+1 (back to stage 3)
+```
+
+Rules for the loop:
+
+- **Stages 0–2 run once for the platform.** Modules do not re-grill and do not
+  re-decompose. New information that changes the map goes back to stage 2
+  deliberately, as a map revision with the operator's approval — not as a quiet
+  edit mid-module.
+- **Each module's spec is a full dossier** ([`spec.md`](spec.md)): architecture,
+  entities, contracts in and out, business rules, edge and failure cases, UI/Figma
+  chain when it has a surface.
+- **The contract is the boundary.** A module may stub what a later module will
+  provide, but it may not reach into another module's internals; if it needs to,
+  the seam is wrong — back to the map.
+- **Deploy cadence is the brief's call** (autonomy sweep): deploy each module as it
+  lands, or build several and deploy once. Record it; don't decide it per module.
+- **Update the map's status column as each module closes**, in the same commit as
+  that module's acceptance. The map is the resume point after a lost context.
+- **Loop discipline:** a module re-entering the same stage a third time trips the
+  loop guard ([`loop-guard.md`](loop-guard.md)) — stop, name the oscillation, and
+  fix the layer that owns it instead of iterating.
+
+## Program done
+
+The program is finished when every row is `done` or `deferred` with an agreed home,
+the cross-module contracts are exercised by tests that cross the seam (not just
+per-module unit tests), and the final acceptance covers the platform's REQ table as
+a whole — not module by module.

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

@@ -0,0 +1,169 @@
+# The grill — stage 0, built in
+
+The intake grill is **part of this skill**. No companion skill to install, no
+provider to resolve, nothing to fall back to: this file *is* the implementation.
+
+Its job is not to design. It is to take a one-line request ("make me feature X")
+and interview it into a brief complete enough that stages 1→10 finish without
+coming back to the operator.
+
+> Adapted, with thanks, from Matt Pocock's `grilling` / `grill-with-docs` skills
+> (MIT — see this repo's `LICENSE` → *Third-party*). The domain-awareness
+> half — glossary challenges, `CONTEXT.md`, ADR discipline — comes from there; the
+> autonomy sweep and the brief are this pipeline's.
+
+## The loop
+
+Interview the operator relentlessly about every aspect of the task until you reach
+a **shared understanding**. Walk down each branch of the decision tree, resolving
+dependencies between decisions one by one.
+
+1. **One question per turn.** Never bundle. Wait for the answer before the next.
+2. **Recommend an answer with every question** (+ a one-line rationale). "What do
+   you think?" is lazy — you have the codebase in front of you, they don't.
+3. **If the codebase can answer it, go read the codebase.** Spending the
+   operator's turn on something `grep`/`Read`/context7 would have told you is the
+   most common way to waste a grill.
+4. **Depth-first.** Finish a branch before opening another; ask prerequisite
+   decisions first, so later answers don't invalidate earlier ones.
+5. **Reconcile contradictions immediately**, and chase dodges: "we'll decide
+   later" → "what's the latest you can decide and still ship?"
+6. **Cover the autonomy sweep** (below). An unasked question is not neutral — it
+   is a scheduled interruption at stage 6.
+
+**Stop** when a re-scan surfaces no new branches. Don't grill past diminishing
+returns: genuinely reversible calls can be deferred with a note.
+
+## Domain awareness
+
+While exploring the codebase, also look for what the project already says about
+itself — and hold the operator to it.
+
+### Find the existing docs
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+A `CONTEXT-MAP.md` at the root means multiple contexts, and points at where each
+one lives (`src/ordering/CONTEXT.md`, `src/billing/CONTEXT.md`, …), each with its
+own `docs/adr/` alongside the system-wide one. Infer which context the task
+belongs to; if it's genuinely unclear, ask.
+
+Create these files **lazily** — only when you have something real to write.
+
+### Techniques during the session
+
+- **Challenge against the glossary.** When a term conflicts with `CONTEXT.md`, say
+  so on the spot: *"Your glossary defines 'cancellation' as X, but you seem to mean
+  Y — which is it?"*
+- **Sharpen fuzzy language.** Vague or overloaded terms get a proposed canonical
+  one: *"You're saying 'account' — do you mean the Customer or the User? Those are
+  different things."*
+- **Stress-test with concrete scenarios.** Invent specific cases that probe edge
+  conditions and force precision about the boundaries between concepts.
+- **Cross-reference with the code.** When the operator states how something works,
+  check whether the code agrees, and surface contradictions: *"Your code cancels
+  entire Orders, but you just said partial cancellation is possible — which is
+  right?"*
+- **Update `CONTEXT.md` inline.** Resolve a term → write it down right then, not in
+  a batch at the end. Format: [`templates/context.md`](../templates/context.md).
+  Keep it free of implementation detail — only terms a domain expert would
+  recognize.
+
+### Offer an ADR sparingly
+
+Only when **all three** are true:
+
+1. **Hard to reverse** — changing your mind later carries real cost.
+2. **Surprising without context** — a future reader will ask "why on earth this
+   way?"
+3. **A real trade-off** — genuine alternatives existed and one was chosen for
+   specific reasons.
+
+Any one missing → skip it. Format and what qualifies:
+[`templates/adr.md`](../templates/adr.md). ADRs land in `docs/adr/` with sequential
+numbering (scan for the highest number, increment).
+
+## The autonomy sweep
+
+Resolving the *task* is not enough. The grill must also pre-resolve everything that
+would otherwise stop stages 1→10 mid-flight. Every row gets an answer **or** an
+explicit "stop and ask me here":
+
+| Stage | What to settle up front |
+|---|---|
+| run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
+| 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
+| 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |
+| 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |
+| 4–5 Dev | base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker |
+| 5 Integration | how the branch lands (merge / PR + approver / "leave it unmerged"); parallel fan-out wanted (one worktree per implementer)? |
+| 6 Tests | the test command; what "green" means here; known-red baseline; coverage expectation |
+| 7 Lint+deploy | lint command; deploy target and path; release automation on/off; deploy-from-main rule; **deploy authorization** |
+| 8 Post-deploy | where logs / health live (app name, endpoint, workflow) |
+| 9 Docs+wiki | which module docs / runbooks this change updates; wiki sync yes/no |
+| 10 Acceptance | who signs off; where deferred REQs are tracked (issue tracker, backlog) |
+
+**Deploy authorization has a hard floor.** Deploy and publish are outward and
+irreversible, so a vague "just do everything" authorizes nothing. A standing
+authorization counts only when it is **specific** — named target, named
+preconditions ("staging once lint and the full suite are green; production always
+asks"). Specific and recorded → it satisfies the stage-7 manual gate. Broader,
+absent or ambiguous → stage 7 stops and asks.
+
+## The REQ spine — the grill's other hard output
+
+Prose scope is not checkable. Before the brief is confirmed, the grill must turn
+what was asked into an **addressable list of requirements**, because every later
+stage traces to these IDs and stage 10 accounts for every one of them.
+
+| ID | Requirement | How it's verified | Status |
+|---|---|---|---|
+| REQ-001 | … | test name / `file:line` / command + expected output / `SCN-…` | open |
+
+Three rules that decide whether the spine is worth anything:
+
+1. **One REQ = one independently verifiable deliverable.** Not one per sentence of
+   the request. A small task gets three rows, not thirty — an inflated table is
+   ignored, and an ignored table protects nothing.
+2. **Every row names its check.** *A requirement you can't say how to verify is a
+   badly-stated requirement* — split or sharpen it here, during the grill. This is
+   the single defence against the failure mode where three vague REQs cover a large
+   task and acceptance goes green over half of it.
+3. **Ask what "finished" means per row, not for the task overall.** "Export works"
+   hides five decisions; "exports the currently filtered rows as CSV, verified by
+   `test_export_respects_filters`" hides none.
+
+**Then freeze it.** Adding a requirement mid-run is fine — append with its source.
+**Removing or narrowing one requires the operator's explicit agreement**, recorded
+in the carry-over ledger. Quietly restating the task in smaller terms is the
+subtlest way to lose it: every gate downstream then passes honestly, on a task
+that shrank without anyone deciding it should.
+
+## Output
+
+Everything resolved goes into the **task brief**, seeded from
+[`templates/brief.md`](../templates/brief.md) and committed to
+`docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` — scope, **the REQ table**,
+users, UI verdict, constraints, locked decisions, the autonomy table,
+done-criteria, open assumptions. Seed the template only when the file is absent;
+never overwrite an existing brief.
+
+Alongside it, seed the **carry-over ledger** from
+[`templates/carryover.md`](../templates/carryover.md) at
+`…-carryover.md` — append-only, written by every later stage, read in full by
+stage 10. Anything deferred, dropped, or half-done from here on goes there the
+moment it's said: **deferred out loud is forgotten.**
+
+Plus, where the session produced them: an updated `CONTEXT.md` and any ADRs, each
+written as the decision landed.
+
+The operator confirms the brief. Only then does stage 1 begin.

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

@@ -0,0 +1,100 @@
+# Loop guard — breaking churn, cross-cutting
+
+Any stage that can repeat can also **churn**: a later pass undoing what an earlier
+pass in the same run already did, two shapes alternating, the same file rewritten
+round after round with no new information. Churn looks like progress and consumes
+a run.
+
+This file is the detector and the break protocol. It binds every repeating loop in
+the pipeline: the stage-5 fix loop, a stage re-entered after a failed gate, the
+per-module program loop ([`decomposition.md`](decomposition.md)), and any
+audit → fix → audit cycle.
+
+## Bookkeeping — the thing that makes detection mechanical
+
+You cannot detect churn from memory, especially after compaction. Every repeating
+pass appends one line to the run's ledger (`.task-pipeline/build/<plan>/progress.md`
+for stage 5; `.task-pipeline/run.md` for stage-level and program-level loops):
+
+```
+touch: <file> — pass <N> (<stage|round|module>) — reason: <finding id / gate item>
+```
+
+One line per file per pass. The reason must name **what forced the edit** — a
+finding id, a failed gate item, an operator instruction. "Cleanup", "polish" and
+"while I was there" are not reasons; they are churn with better manners.
+
+## Detection — any one of these trips the guard
+
+1. **Revert-oscillation.** An edit restores something an earlier pass in this run
+   deliberately removed, or re-removes what an earlier pass added. Shape A → B → A.
+2. **Repeat touch without new information.** The same file is edited in two
+   consecutive passes and the second pass's `reason` is the same finding/gate item
+   as the first — the fix did not fix it, or the two passes disagree about what
+   "fixed" means.
+3. **Finding resurrection.** A finding whose text (normalized) matches one already
+   marked ADDRESSED or parked-with-ruling in this run comes back.
+4. **Gate ping-pong.** The same stage is re-entered for the third time on the same
+   artifact, or two adjacent stages hand work back and forth (spec ⇄ plan,
+   plan ⇄ build) more than twice.
+5. **Cross-loop contradiction.** A pass in one loop edits a file that a *different*
+   loop (another task, another module) already closed in this run — two owners for
+   one file.
+
+Caps that trip the guard by themselves: **5 fix rounds** per task
+([`build.md`](build.md)), **2 re-entries** per stage per artifact, **3 passes** per
+module in the program loop.
+
+## The break protocol
+
+When the guard trips, **stop editing immediately**. Do not dispatch another fix, do
+not "just try one more thing". Then, in this order:
+
+1. **Freeze and name it.** Write the oscillation down in the ledger and to the
+   operator: shape **A** vs shape **B**, one line each, plus who is asking for each
+   (a finding, the plan's text, the spec, a gate check, an operator instruction) and
+   the evidence for each — `file:line`, the failing command, the review verdict.
+2. **Find the layer that owns the conflict.** Churn almost always means a decision
+   is being re-litigated at the wrong altitude:
+   - two findings disagree → the **review rubric** decides
+     ([`review.md`](review.md)); if it genuinely doesn't, it's a spec question;
+   - a finding contradicts the plan → the **operator** decides which governs
+     (never dismiss the finding, never fix against the plan silently);
+   - the plan contradicts the spec → back to **stage 4** with the evidence;
+   - the spec is ambiguous or wrong → back to **stage 3**, and if the ambiguity was
+     an unresolved intake question, say so — that is a stage-0 miss worth recording;
+   - two modules claim the same file or entity → back to **decomposition**: the cut
+     is wrong.
+   **Never resolve a higher-layer conflict inside a lower loop.** Patching code to
+   satisfy two contradictory requirements is how a run burns its remaining budget.
+3. **Re-plan the check.** Replace whatever ad-hoc verification was running with an
+   explicit ordered checklist: every disputed item, one line each, in dependency
+   order, with a single owner and a single verification command per item. Write it
+   to the ledger before touching anything.
+4. **Go in order, one at a time.** Verify item 1 → if it fails, fix only item 1 →
+   re-verify only item 1 → commit → item 2. No parallel edits, no bundled fixes, no
+   opportunistic cleanup in the same commit. The point is that each change has one
+   reason and one proof.
+5. **Re-check the whole list once** at the end, in the same order. If a later item
+   broke an earlier one, that pair is the real conflict — escalate it per step 2
+   instead of looping again.
+6. **Record the ruling.** Ledger line: `loop-guard: <A vs B> — ruling: <what governs
+   and why> — items: <N> verified in order`. The final review reads it.
+
+## When to stop and hand back
+
+If step 2 lands on "the operator decides", or a cap is hit a second time after a
+re-planned pass, **stop and report BLOCKED** with: the two shapes, the evidence, the
+history of passes, and your recommendation. That is a complete, honest hand-back —
+far cheaper than a third round of the same argument.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "One more pass and it converges" | Two passes with the same reason already proved it doesn't. The disagreement is above the code. |
+| "I'll just revert to what worked" | That is the oscillation, not the exit. Name A and B first. |
+| "The reviewer keeps changing its mind" | Different findings on the same lines mean the requirement is ambiguous. That's a spec question. |
+| "Tidying while I'm in the file" | Untracked edits are what make churn invisible. One reason per change, in the ledger. |
+| "Logging the loop is bureaucracy" | Detection needs a record; after compaction the ledger is the only memory that survives. |
+| "It's faster than escalating" | A run that spends its budget re-deciding a spec question delivers nothing. Escalation costs one message. |

package/plugins/task-pipeline/skills/task-pipeline/references/model-tiering.md

@@ -1,32 +1,65 @@
-# Model tiering
+# Model policy
 
-A **reminder**, not a hard block. Not every environment has every model — if you
-lack one, keep your current model; the pipeline still runs.
+**One model, confirmed once, before the run starts.** Not a per-stage tier list,
+not a hardcoded vendor id — a single decision the operator makes at preflight and
+the pipeline then honors without nagging.
 
-| Stages | Recommended | id |
-|---|---|---|
-| 0–4 (intake grill, docs, brainstorm, spec, plan) | Fable 5 | `claude-fable-5` |
-| 5–6 (subagent dev, tests) | Opus 5 | `claude-opus-5` |
-| 7–9 (lint/deploy, logs, docs) | inherit current | — |
+## The default
 
-## Mechanic
+> **Use the most capable reasoning model the environment offers** — at the time of
+> writing that is the **latest Opus generation**, but read that as *"the top tier
+> of whatever you're on"*, not as a specific string.
 
-At each stage boundary compare recommended vs current. If they differ, emit:
+Every stage runs on that model by default. The pipeline is a full delivery cycle:
+the grill has to hear what the operator didn't say, the spec has to lock contracts
+a zero-context implementer will follow, and the build has to hold a plan in its
+head. Downgrading any of those to save tokens costs more in rework than it saves.
 
-> ⏸ **Stage N (`<name>`) recommends `<model>` (`<id>`).** You're on `<current>`.
-> Switch: `/model <id>` — then say "continue". *(Reminder only.)*
+## Never hardcode a model id
 
-## Why manual
+Model ids go stale — generations ship, tiers get renamed, and the operator may not
+even be on the same provider. So:
 
-A skill runs inside the current context; it **cannot change the main-loop model**.
-Only the operator can, via `/model` (or `/fast`). The stages that most benefit from
-Fable (0–4) are interactive anyway (stage 0 is a live grill), so the operator is
-present to switch.
+- **Resolve at runtime.** Look at what the environment actually offers (`/model`,
+  the harness's model list) and pick the top reasoning tier available there.
+- **Treat any id in this repo as an example**, including in `pipeline.example.json`.
+  Stage configs use provider-agnostic tokens:
+  - `default` — the model confirmed for this run (the recommendation above)
+  - `inherit` — whatever the operator is currently on; no recommendation
+- **Another provider is fine.** "Top tier available" is the contract. If the
+  environment has no Opus-class model, the best available one is the right answer —
+  say which one you settled on and keep going.
 
-Stage 5 spawns subagents; those **are** pinned to Opus by the orchestrator via the
-`Agent` / `Workflow` model override — no operator action needed for subagents.
+## Mechanic — confirm at preflight, then stop asking
 
-## Override
+Once, as part of the preflight (before stage 0):
 
-Set your own map if your task warrants it (e.g. a heavy design needs Opus at
-stage 2). The recommendations are defaults, not rules.
+> 🧠 **Model for this run:** recommended **`<top tier available>`**. You're on
+> `<current>`.
+> Switch with `/model <id>`, or say "keep current" / name another. Per-stage
+> overrides welcome (e.g. a cheaper model for mechanical stages) — say so now and
+> I'll record the map.
+
+Record the answer in the stage-0 brief (`Model` row of the autonomy sweep). After
+that:
+
+- **Do not re-prompt at every stage boundary.** The decision is made; nagging is
+  the thing this replaces.
+- **Re-prompt only** when the operator recorded a *per-stage override map* and the
+  next stage's entry differs from the current model — then emit the same block
+  scoped to that stage.
+- A skill runs inside the current context and **cannot change the main-loop
+  model**; only the operator can, via `/model` (or `/fast`). Preflight is
+  interactive anyway, so this costs one exchange.
+
+## Subagents
+
+Stage 5 spawns subagents; the orchestrator pins them to the **run's confirmed
+model** via the `Agent` / `Workflow` model override. No operator action needed —
+and no silent downgrade to a cheaper tier.
+
+## Degradation
+
+The recommendation is a **reminder, not a block**. If the recommended tier isn't
+available, keep the current model, state plainly which one is in use, and run. The
+pipeline never stalls on a model it can't get.