task-pipeline-skill 0.10.0 → 0.17.1

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

@@ -3,12 +3,19 @@
 For each stage: what it does, what to invoke, artifacts, and the **GATE** that
 must pass before advancing. Each gate is tagged with its **type** — `auto` (the
 orchestrator verifies the check itself, pass/fail) or `manual` (wait for the
-operator's explicit go). These stages (0 intake + 1→9) are the plugin's
+operator's explicit go). These stages (0 intake + 1→10) are the plugin's
 **example** flow, encoded in `pipeline.example.json` against the universal contract
 `pipeline.schema.json`; a host project replaces it with its own
 stages/agents/types (see SKILL.md → *Bring your own skills*).
 
-## 0 — Intake grill (Fable)
+## 0 — Intake grill — MANDATORY
+- **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
+  entry-from-super-ux short-circuit below, and even that still requires a scope
+  confirmation and a record of what was adopted vs skipped. A run that reaches
+  stage 1 without a committed, operator-confirmed brief is a **failed run** —
+  stop and go back.
 - **Entry-from-super-ux short-circuit (check FIRST).** task-pipeline is often
   launched *from* super-ux — its `/ux` action menu offers "execute autonomously
   via the task-pipeline plugin" once the UX chain (and often a
@@ -25,36 +32,40 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
 - **What (normal entry):** the operator's one-line task is almost never enough to
   run autonomously. Before anything else, **grill the operator** to expand that
   one line into a complete, unambiguous brief — resolve every decision branch
-  up front so stages 1→9 need no further human input beyond the manual gates.
+  up front so stages 1→10 need no further human input beyond the manual gates.
   This is input expansion, not design: turn "make me feature X" into locked
   answers for scope, users, constraints, data, edge cases, done-criteria.
-- **Invoke:** prefer the `grill-me` / `grilling` skill if it resolves; otherwise
-  run the built-in grill loop:
-  1. **One question per turn** — never bundle.
-  2. **Give a recommended answer with every question** (+ 1-line rationale);
-     "what do you think?" is lazy.
-  3. **Explore the codebase/docs before asking** — if `grep`/`Read`/context7
-     answers it, do that instead of spending a turn.
-  4. **Walk the decision tree depth-first**; finish a branch before opening
-     another; ask prerequisite decisions first.
-  5. **Reconcile contradictions** immediately; chase dodges ("we'll decide
-     later" → "what's the latest you can decide and still ship?").
+- **How it runs: [`grill.md`](grill.md)** — the full doctrine, built into this
+  skill (nothing to install). In short: one question per turn, a recommended
+  answer with each, explore the codebase before asking, depth-first through the
+  decision tree, contradictions reconciled on the spot; plus **domain awareness**
+  (challenge terms against `CONTEXT.md`, sharpen fuzzy language, stress-test with
+  concrete scenarios, cross-reference the code, record ADRs for hard-to-reverse
+  calls) and the **autonomy sweep** that pre-resolves every stage-1→10 blocker.
+  Deploy authorization has a hard floor there: a standing go counts only when it
+  names the target and the preconditions.
 - **UI early-detect:** one branch of the grill is always "does this touch a
   user-facing surface (web/mobile/CLI/TUI)?". If yes → surface **super-ux**
   now (use it if installed; otherwise give the install line — see SKILL.md
   *Prerequisites*); this arms the stage-3 UX track.
 - **Artifact:** lock the resolved decisions into a **task brief** committed at
   `docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` (scope, users/UI verdict,
-  constraints, assumptions, explicitly-deferred items, done-criteria). Seed it from
+  constraints, assumptions, explicitly-deferred items, done-criteria) **plus the
+  autonomy sweep's per-stage answers and the model decision**. Seed it from
   the skill's `templates/brief.md` skeleton — but only when absent, never
-  overwrite an existing brief. Stages 2–4 build on this brief.
+  overwrite an existing brief. Stages 2–4 build on this brief; stages 5–10 read
+  its autonomy section instead of asking. Where the session produced them, also:
+  an updated `CONTEXT.md` (terms written as they resolved) and any ADRs under
+  `docs/adr/` — see `grill.md` → *Domain awareness*.
 - **GATE (manual):** shared understanding reached — every detected branch has a
-  recorded answer or an explicit deferral, no open contradictions, and the
-  operator confirms the brief. Stop when a re-scan surfaces no new branches
-  (don't grill past diminishing returns; reversible calls can be deferred with a
-  note). Only then start stage 1.
+  recorded answer or an explicit deferral, no open contradictions, **every
+  autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
+  **REQ table is written and every row names its check**, the carry-over ledger is
+  seeded, the model decision is recorded, and the operator confirms the brief. Stop when a
+  re-scan surfaces no new branches (don't grill past diminishing returns;
+  reversible calls can be deferred with a note). Only then start stage 1.
 
-## 1 — Docs study (Fable)
+## 1 — Docs study
 - **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
@@ -63,16 +74,40 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
 - **GATE (auto):** every contract the design will lock is grounded in fetched docs,
   not recall. Unresolvable libraries are flagged in the spec.
 
-## 2 — Brainstorm (Fable)
-- **Invoke:** `superpowers:brainstorming`. One question at a time; 2–3 approaches +
-  a recommendation; design presented in sections.
+## 2 — Brainstorm + decompose
+- **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
+  approaches with a recommendation, design presented in sections and approved
+  section by section. **Hard gate:** no code, no scaffolding, no implementation
+  skill before the operator approves the design — including on "obviously simple"
+  tasks.
 - **UI detection (mandatory check):** decide whether the task touches any
   user-facing surface (web, mobile, CLI, TUI — new feature, new screen/command,
   or a change to user-visible behavior). Record the verdict; it arms the UX
   track in stage 3.
-- **GATE (manual):** the user approves the design **and** the UI verdict is recorded.
+- **Decomposition (platforms only): [`decomposition.md`](decomposition.md).** If
+  the brief describes a platform rather than a change — several independent
+  capabilities, several surfaces that could ship separately, REQs no single
+  deliverable satisfies — cut it into **modules** before any spec is written, and
+  commit the module map (`specs/<topic>-modules.md`): what each module delivers,
+  the entities it owns, what it depends on, the contracts it exposes, its REQs and
+  its status, in build order with the walking skeleton first. Single-module work
+  records `single module: <name>` in the design and moves on — a skipped
+  decomposition is a decision, never an omission.
+- **GATE (manual):** the user approves the design, the UI verdict is recorded,
+  **every REQ is answered by the design** — a requirement the design doesn't
+  address is either covered now or explicitly dropped by the operator, with the
+  drop recorded in the carry-over ledger — **and, for a platform, the module map is
+  approved**: brick criteria met or excepted in writing, dependency graph acyclic,
+  build order topological, every REQ mapped to exactly one module, cross-module
+  contracts named with their owner.
 
-## 3 — Spec (Fable) — with UX track for user-facing tasks
+## 3 — Spec — with UX track for user-facing tasks
+- **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
+  review gate.
 - **UX track (runs FIRST when stage 2 flagged UI; skip entirely otherwise).**
   Requires the **super-ux** skills. If missing on a UI task → give the install
   line and stop (see SKILL.md *Prerequisites*: `/plugin marketplace add
@@ -97,49 +132,72 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   never rebuild from scratch. If the chain already exists and is validated (e.g.
   the task entered from super-ux), just verify (linter green) and embed it into
   the spec; only build the parts that are missing.
-- **Spec:** brainstorming writes the design to
-  `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commits it. Lock all
+- **Spec:** write the approved design to
+  `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit it. Lock all
   shared contracts (types, schemas, signatures, file layout). For UI tasks the
   spec **embeds the UX layer**: links the validated scenario IDs, the flows and
   `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; for UI tasks
+- **GATE (manual):** 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`;
   the linter passes; every user-facing spec requirement traces to a scenario ID
   (or an explicit v1-mode/tiny-project waiver by the operator). No plan (stage 4)
   starts before this — the chain comes BEFORE interface.
 
-## 4 — Plan (Fable)
-- **Invoke:** `superpowers:writing-plans` →
-  `docs/superpowers/plans/YYYY-MM-DD-<feature>.md`. Zero-context tasks, exact
-  paths, TDD steps, DoD each, dependency graph + parallel groups, non-overlapping
-  file ownership.
-- **GATE (auto):** every spec requirement maps to a task; no placeholders; parallel-group
+## 4 — Plan
+- **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
+  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
+  `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:
+  every spec requirement maps to a task; no placeholders; names and
+  types consistent across tasks; every task carries a verifiable DoD; parallel-group
   tasks share no files. For UI tasks: every task building user-facing behavior
   names the scenario ID(s) and `SCR-` screen(s) it implements, and its DoD
   includes satisfying them **and** updating the affected super-ux layers in the
   same change (super-ux *same-change* rule).
 
-## 5 — Dev (Opus)
-- **Invoke:** `superpowers:using-git-worktrees` (isolate) →
-  `superpowers:subagent-driven-development` (or `superpowers:executing-plans`).
-  TDD per task (failing test → minimal impl → green → commit). Pin subagents to Opus.
-- **GATE (auto):** all plan tasks DONE (two-stage review: spec compliance, then code
-  quality); full test suite green.
+## 5 — Dev
+- **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,
+  then one fresh implementer subagent per task with a file-based brief and report,
+  a review after every task ([`review.md`](review.md)), and a five-round fix loop
+  with an explicit breaker. TDD per task ([`tdd.md`](tdd.md)): failing test →
+  watch it fail → minimal impl → watch it pass → commit. Pin subagents to the
+  run's confirmed model (`model-tiering.md`). The plan's parallel groups fan out
+  **only** when each implementer gets its own worktree; otherwise sequential.
+- **Integration closes the stage:** sync with the base branch, re-run the full suite
+  on the result, land it the project's way (merge, or a PR — outward, so it needs a
+  go), remove the worktree. Stages 7–9 act on the integrated result, so a branch the
+  operator chose to leave unmerged is recorded as such.
+- **GATE (auto):** all plan tasks DONE (three review verdicts per task: spec
+  compliance, **REQ satisfied**, code quality); every finding fixed or parked with a
+  ruling; **every parked finding and implementer concern harvested into the
+  carry-over ledger** — nothing stays only in the scratch workspace, which is
+  deleted; no task left BLOCKED; full test suite green; branch integrated per the brief's policy (or the operator's
+  "leave it" recorded).
 
-## 6 — Tests (Opus)
+## 6 — Tests
 - **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.
-- **Invoke:** the host test runner (see `conventions.md` → *Lint + test*);
-  `superpowers:test-driven-development` for any uncovered gap.
+- **Invoke:** the host test runner (see `conventions.md` → *Lint + test*); the
+  built-in [`tdd.md`](tdd.md) cycle for any uncovered gap — failing test first,
+  same as stage 5.
 - **GATE (auto):** the **full** suite is green (not just the new tests); new/changed code
   is covered; no `skip`/`xfail` smuggling a red suite past the gate. Never advance
   to deploy on a red or partial run.
 
-## 7 — Lint + deploy (host model)
+## 7 — Lint + deploy
 - 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 —
@@ -147,19 +205,97 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   if the project defines release automation (`pipeline.json` → `release`, toggle
   on), that is what "deploy" runs here.
 - **GATE (manual):** lint clean (host linter **and**, for UI projects, the super-ux
-  linter) **and** suite green **before** deploy. Deploy is outward → explicit
+  linter) **and** suite green **before** deploy, **and no REQ is still `open`** — a
+  `partial` ships only with the operator's explicit acceptance. A gap is cheapest to
+  close before it ships, and the operator is already present at this gate. Deploy is outward → explicit
   operator go. Respect deploy-from-main rules if the project mandates them.
 
-## 8 — Post-deploy (host model)
+## 8 — Post-deploy
 - 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 (host model)
+## 9 — Docs + wiki
 - Update host module docs / runbooks per the project's self-update rules, in the
   **same change**. For UI tasks, confirm the super-ux layers were updated in this
   change and the linter is green (super-ux *same-change* + *no-drift* rules). Then
   sync knowledge to the wiki (`wiki-update` skill).
 - **GATE (auto):** docs in sync with code; UI: super-ux layers current + linter
   green; wiki synced; dangling links fixed.
+
+## 10 — Acceptance
+- **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
+  asked for?" The loss happens on the seams between stages, and this is where it
+  surfaces.
+- **Runs last**, after docs and wiki — those are deliverables too, and a REQ may
+  name them.
+- **How it runs:** built in. Read the brief's REQ table, the carry-over ledger in
+  full, the plan's task statuses, git log, the final suite output, stage-8 notes and
+  stage-9 doc changes (plus `docs/ux/scenarios.md` + `/ux-lint` for UI tasks). Write
+  `docs/superpowers/specs/YYYY-MM-DD-<topic>-acceptance.md` — one row per REQ,
+  status `verified` / `partial` / `deferred` / `dropped`, each with **evidence** (a
+  passing test name, `file:line`, a command and its output, or a scenario ID).
+  "Done" without evidence is not done: downgrade to `partial` and say so rather
+  than upgrading the claim.
+- Then ask the operator the closing question out loud, list in hand: *here's what
+  you asked for, here's what shipped, here's what's deferred and where it lives —
+  what's missing?* Ask it even when the table is green; the operator holds context
+  the brief never captured, and this is the cheapest moment in the run to hear it.
+- **GATE (manual):** every REQ has a status (none `unknown`); every `verified`
+  carries evidence; every `partial` names what's missing and where it's tracked;
+  every `deferred`/`dropped` has the operator's agreement and, for `deferred`, a
+  tracker entry; no carry-over row left `unresolved`; the operator answers the
+  closing question and signs off. Manual by design — an automated check can prove
+  the table is well-formed, only the person who asked can confirm it is what they
+  asked for.
+
+## The program loop — a platform, one brick at a time
+
+When stage 2 produced a **module map** ([`decomposition.md`](decomposition.md)),
+stages 0–2 have run once for the whole platform and the rest of the pipeline runs
+**per module**, in build order:
+
+```
+module N → 3 spec (dossier) → 4 plan → 5 build → 6 tests → 7 lint+deploy
+         → 8 post-deploy → 9 docs+wiki → 10 acceptance → map status: done
+         → module N+1 (back to 3)
+```
+
+- **No re-grilling, no re-decomposing per module.** New information that changes the
+  map goes back to stage 2 as an explicit, operator-approved map revision — never a
+  quiet edit mid-module.
+- **Each module's spec is a full dossier** (`spec.md`): architecture, entities,
+  contracts in and out, business rules, edge and failure cases, UI/Figma chain when
+  it has a surface.
+- **Deploy cadence is the brief's call** (autonomy sweep): per module, or once after
+  several. Decide it up front, not per module.
+- **Update the module map's status in the same commit as that module's acceptance.**
+  The map is the resume point after a lost context.
+- **Program done** when every row is `done` or `deferred` with an agreed home, the
+  cross-module contracts are covered by tests that cross the seam, and a final
+  acceptance covers the platform's whole REQ table — not module by module.
+
+## Cross-cutting — the loop guard
+
+Any stage can be re-entered and any loop can churn: a pass undoing what an earlier
+pass decided, two shapes alternating, the same file rewritten with no new
+information. [`loop-guard.md`](loop-guard.md) is the detector and the break
+protocol, and it binds every repeating loop here — the stage-5 fix loop, a stage
+re-entered after a failed gate, the program loop above, any audit → fix → audit
+cycle.
+
+- **Every repeating pass logs one line per touched file** (`touch: <file> — pass N —
+  reason: <finding id / gate item>`) to the run ledger. Detection is mechanical, not
+  a feeling, and the ledger is what survives compaction.
+- **Trips on:** revert-oscillation (A→B→A); the same file edited twice for the same
+  reason; a finding already ADDRESSED or parked coming back; a stage entered a third
+  time for one artifact; two loops editing one file. Hard caps: 5 fix rounds per
+  task, 2 re-entries per stage per artifact, 3 passes per module.
+- **On a trip: stop editing.** Name shapes A and B with their evidence, escalate to
+  the layer that owns the conflict (rubric → operator → plan → spec → module map),
+  re-plan the check as an ordered one-item-per-line checklist, then go through it in
+  order, one commit per item. Never settle a higher-layer conflict inside a lower
+  loop, and never adjudicate before the cap.

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

@@ -0,0 +1,110 @@
+# TDD — stages 5 and 6, built in
+
+How every task in the build is implemented, and what stage 6 consolidates. Built
+into this skill; nothing to install.
+
+> Ported from the `test-driven-development` skill in
+> [obra/superpowers](https://github.com/obra/superpowers) (MIT — see `LICENSE` →
+> *Third-party*), with the stage-6 suite gate added.
+
+## The iron law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+**If you didn't watch the test fail, you don't know it tests the right thing.**
+
+Wrote code before the test? Delete it and start from the test. Not "keep it as
+reference", not "adapt it while writing tests", not "look at it once more". Delete
+means delete — code you kept is code the test was written to fit.
+
+**Always:** new features, bug fixes, refactors, behavior changes.
+**Exceptions, and only with the operator's say-so:** throwaway prototypes,
+generated code, pure configuration.
+
+Thinking "skip TDD just this once"? That thought is the rationalization, not the
+exception.
+
+## Red → green → refactor
+
+**RED — write one failing test.** One behavior, a name that describes that
+behavior, real code rather than mocks wherever mocks are avoidable.
+
+**Verify RED — run it and watch it fail. Mandatory.** Confirm it *fails* rather
+than *errors*, that the message is the one you expected, and that it fails because
+the feature is missing — not because of a typo or a bad import. A test that passes
+immediately is testing behavior that already exists: fix the test.
+
+**GREEN — the simplest code that passes.** No extra options, no "while I'm here"
+refactor of the neighbors, no configuration surface nobody asked for. YAGNI.
+
+**Verify GREEN — run it and watch it pass. Mandatory.** The new test passes, the
+other tests still pass, and the output is pristine — no stray warnings or errors.
+Test still fails → fix the code, never the test. Another test broke → fix it now.
+
+**REFACTOR — only once green.** Remove duplication, improve names, extract helpers.
+Tests stay green. No new behavior enters here.
+
+Then the next failing test.
+
+## Tests that stay honest
+
+- **Before writing a test, name the production change that would make it fail.**
+  Can't name one? The test asserts nothing useful.
+- **Assert on real behavior, never on mock behavior.** `expect(mock).toHaveBeenCalled()`
+  proves the mock works. Understand a dependency's side effects before mocking it —
+  a mock that lies is worse than no test.
+- **One thing per test.** An "and" in the name means two tests.
+- **Test-only helpers live in test utilities**, never as extra branches or flags in
+  production classes.
+- **Edge cases and failure paths are part of the task**, not a follow-up ticket:
+  empty input, boundary values, the network call that fails, the timeout.
+
+## Stage 6 — consolidation and the suite gate
+
+Stage 5 wrote the tests task by task. Stage 6 makes the whole thing true:
+
+- New functionality has tests (written test-first in stage 5) — fill any gap now,
+  the same way: failing test first.
+- Tests the change touched are updated or repaired, not deleted around.
+- Edge-case and failure-path coverage matches each task's DoD.
+- The test command is the one recorded in the brief's autonomy sweep; "green" means
+  what the brief says it means (including a known-red baseline, if one was
+  recorded).
+
+**GATE (auto):** the **full** suite is green — not just the new tests. New and
+changed code is covered. No `skip` / `xfail` / commented-out assertion smuggles a
+red suite past the gate. A partial or red run never advances to deploy; report it
+honestly instead.
+
+## When stuck
+
+| Problem | What it means |
+|---|---|
+| Don't know how to test it | Write the API you wish existed, then the assertion. Still stuck → ask the operator. |
+| The test is too complicated | The design is too complicated. Simplify the interface. |
+| Everything has to be mocked | The code is too coupled. Inject dependencies. |
+| Setup is enormous | Extract helpers; if it's still huge, the design is the problem. |
+| Fixing a bug | Write the failing test that reproduces it first. The test proves the fix and prevents the regression. |
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "Too simple to test" | Simple code breaks. The test costs 30 seconds. |
+| "I'll test after" | Tests written after pass immediately, which proves nothing. You never watched it fail, so you never proved it can catch the bug. |
+| "Tests after achieve the same thing — spirit, not ritual" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" After-the-fact tests are biased by the code that already exists. |
+| "I already tested it manually" | Ad-hoc, unrepeatable, no record of what was covered. "Worked when I tried it" is not coverage. |
+| "Deleting X hours of code is wasteful" | Sunk cost. The real choice is rewriting with TDD versus keeping code you can't trust. |
+| "Just exploring first" | Fine — throw the exploration away and start with TDD. |
+| "The existing code has no tests either" | You're improving it. Add tests for what you touch. |
+| "TDD will slow me down" | TDD is the fast path: bugs caught before commit, refactors without fear. The shortcut ends in production debugging. |
+
+## Red flags — stop and start over
+
+Code before test · test written after implementation · test passed on the first run
+· can't explain why it failed · "tests later" · "just this once" · "keep it as
+reference" · "it's about spirit not ritual" · "this case is different because…"
+
+All of them mean the same thing: delete the code, start from the failing test.

package/plugins/task-pipeline/skills/task-pipeline/templates/README.md

@@ -1,12 +1,20 @@
 # templates
 
-Skeletons task-pipeline seeds into a host project. Only the **brief** is owned by
-this plugin (it is the stage-0 intake artifact); the spec and plan skeletons come
-from the `superpowers` skills, and the `docs/ux/*` skeletons from `super-ux`.
+Skeletons task-pipeline seeds into a host project. Only the **brief** is a seeded
+file (it is the stage-0 intake artifact). The spec and plan have no skeleton here —
+their required structure is prescribed inline by `references/spec.md` and
+`references/planning.md`; the `docs/ux/*` skeletons come from `super-ux`.
 
 | Template | Seeded to | Stage |
 |---|---|---|
 | `brief.md` | `docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` | 0 — intake grill |
+| `carryover.md` | `docs/superpowers/specs/YYYY-MM-DD-<topic>-carryover.md` | 0 seeds, all stages append, 10 reads |
+| `context.md` | `CONTEXT.md` at the repo root (or per context) | 0 — grill, domain awareness |
+| `adr.md` | `docs/adr/NNNN-<slug>.md` | 0 — grill, hard-to-reverse decisions |
+
+`context.md` and `adr.md` are **format references**, not files to copy wholesale:
+the grill writes `CONTEXT.md` entries and ADRs in their shape, lazily — only once
+there is a resolved term or a decision worth recording.
 
 Seeding rule (per the ssheleg canon): create a template copy **only when the
 target is absent**; never overwrite an existing brief.

package/plugins/task-pipeline/skills/task-pipeline/templates/adr.md

@@ -0,0 +1,64 @@
+# ADR — format
+
+Architecture Decision Records live in `docs/adr/` with sequential numbering
+(`0001-slug.md`, `0002-slug.md`, …). Scan for the highest existing number and
+increment. Create the directory **lazily** — only when the first ADR is needed.
+
+> Adapted from Matt Pocock's `grill-with-docs` (MIT — see the repo LICENSE →
+> *Third-party*).
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1–3 sentences: what the context was, what was decided, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is recording *that* a
+decision was made and *why* — not filling out sections.
+
+## Optional sections
+
+Only when they add genuine value; most ADRs need none.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by
+  ADR-NNNN`) — useful once decisions start getting revisited.
+- **Considered options** — only when the rejected alternatives are worth
+  remembering.
+- **Consequences** — only when non-obvious downstream effects need calling out.
+
+## When to write one
+
+All three must hold:
+
+1. **Hard to reverse** — changing your mind later carries real cost.
+2. **Surprising without context** — a future reader will look at the code and
+   wonder "why on earth did they do it this way?"
+3. **A real trade-off** — genuine alternatives existed and one was picked for
+   specific reasons.
+
+Easy to reverse → skip it, you'll just reverse it. Not surprising → nobody will
+wonder. No real alternative → there's nothing to record beyond "we did the obvious
+thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is
+  event-sourced; the read model projects into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via
+  domain events, not synchronous HTTP."
+- **Technology choices carrying lock-in.** Database, message bus, auth provider,
+  deployment target — not every library, just the ones that would take a quarter to
+  swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer
+  context; others reference it by ID only." The explicit no's are as valuable as
+  the yes's.
+- **Deliberate deviations from the obvious path.** "Manual SQL instead of an ORM
+  because X." Anything a reasonable reader would assume the opposite of — this is
+  what stops the next engineer from "fixing" something deliberate.
+- **Constraints invisible in the code.** "No AWS, for compliance." "Sub-200ms
+  responses, per the partner API contract."
+- **Rejected alternatives whose rejection is non-obvious.** Considered GraphQL,
+  picked REST for subtle reasons → record it, or someone re-proposes GraphQL in six
+  months.

package/plugins/task-pipeline/skills/task-pipeline/templates/brief.md

@@ -15,6 +15,28 @@
 - **Out of scope / explicitly deferred:** … (with the reason and, for deferrals,
   the latest moment the decision can still be made)
 
+## Requirements (the REQ spine — every later stage traces to these IDs)
+
+Scope above is prose; this is the **addressable** form of it. One row per
+independently verifiable deliverable — not one per sentence. Every row needs a
+named check: **a requirement you can't say how to verify is a badly-stated
+requirement** — split it here, on the grill, not at acceptance.
+
+| ID | Requirement | How it's verified | Status |
+|---|---|---|---|
+| REQ-001 | … | test name / `file:line` / command + expected output / `SCN-…` | open |
+| REQ-002 | … | … | open |
+
+Status lifecycle, written at three checkpoints only (stage 4, stage 5, stage 10 —
+not continuously): `open` → `planned` → `built` → `verified` \| `partial` \|
+`deferred` \| `dropped`.
+
+> **The list is frozen once confirmed.** Adding a requirement mid-run is fine —
+> append it with its source. **Removing or narrowing one needs the operator's
+> explicit agreement**, recorded in the carry-over ledger. Silently restating the
+> task in smaller terms is the failure this table exists to prevent: every gate
+> after it goes green on the shrunken task and nothing reports the loss.
+
 ## Users & context
 
 - **Who / for what:** … (personas, the job being done)
@@ -26,6 +48,33 @@
 |---|---|---|---|
 | 1 | … | … | … |
 
+## Autonomy (the sweep — stages 1→10 read this instead of asking)
+
+Every row is either a resolved answer or an explicit **STOP AND ASK**. A blank row
+is not neutral — it is a scheduled interruption.
+
+| Stage | Question | Answer |
+|---|---|---|
+| run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
+| run-wide | Decide autonomously vs escalate to me | … |
+| 1 Docs | External libs/APIs/SDKs in play; any context7 can't resolve → where their docs live | … |
+| 2 Decompose | 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); scenario-tracing waiver, if any | … |
+| 4–5 Dev | Base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker | … |
+| 5 Integration | How the branch lands — direct merge, PR (who approves), or "leave it, I'll merge"; is parallel fan-out (one worktree per implementer) wanted? | … |
+| 6 Tests | Test command; what "green" means; known-red baseline; coverage expectation | … |
+| 7 Lint | Lint command (incl. `docs/ux/lint.py` for UI projects) | … |
+| 7 Deploy | Target + path; release automation on/off; deploy-from-main rule | … |
+| 7 Deploy | **Authorization** — standing go, or ask every time? | … |
+| 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 get tracked (issue tracker / backlog) | … |
+
+> **Deploy authorization has a hard floor.** A standing go counts only if it is
+> **specific** — named target and named preconditions ("staging, once lint and the
+> full suite are green; production always asks"). Vague blanket permission does not
+> authorize an outward, irreversible action; stage 7 stops and asks.
+
 ## Done-criteria
 
 - Observable, verifiable conditions that mean "this task is finished".

package/plugins/task-pipeline/skills/task-pipeline/templates/carryover.md

@@ -0,0 +1,36 @@
+# Carry-over ledger — <topic>
+
+> **Append-only.** Any stage may add a row; nobody edits or deletes one. Committed
+> to `docs/superpowers/specs/YYYY-MM-DD-<topic>-carryover.md` beside the brief, and
+> read in full by stage 10 (acceptance).
+>
+> **The rule: deferred out loud is forgotten.** If it isn't written here, it wasn't
+> deferred — it was lost. That covers everything said in passing: "we'll do that
+> later", "good enough for now", a `DONE_WITH_CONCERNS` from an implementer, a
+> reviewer's non-blocking finding, a requirement the operator agreed to drop.
+
+| # | Stage | What | Why it isn't done | REQ | Where it lives now |
+|---|---|---|---|---|---|
+| 1 | 5 Dev | XLSX export path | scope call — CSV first | REQ-004 | LIN-483 |
+| 2 | 5 Review | `export.ts` lacks a size guard | minor, non-blocking | — | backlog |
+| 3 | 2 Brainstorm | REQ-007 dropped: bulk export | operator agreed 2026-07-28 | REQ-007 | dropped |
+
+## Columns
+
+- **Stage** — where it surfaced, so acceptance knows how far it travelled.
+- **What** — the concrete thing not done. "Error handling" is not an entry;
+  "`export.ts` swallows a failed write instead of surfacing it" is.
+- **Why it isn't done** — scope call, blocked, deliberate deferral, out of budget.
+  "Forgot" is a legitimate and useful answer here.
+- **REQ** — the requirement it belongs to, or `—` if it's outside the REQ spine.
+- **Where it lives now** — issue id, backlog, `dropped` (with the operator's
+  agreement), or `unresolved`. **`unresolved` blocks the stage-10 gate**: an item
+  with no home is exactly the thing that gets forgotten, so acceptance refuses to
+  close on it.
+
+## Notes
+
+- Adding a row costs one line and never blocks a stage — that is the point. The
+  ledger is cheap precisely so nobody is tempted to keep it in their head.
+- Rows referencing a REQ feed that REQ's final status: an open carry-over row
+  means the requirement is at best `partial`, never `verified`.