task-pipeline-skill 0.12.0 → 1.0.0

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

@@ -3,7 +3,7 @@
 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*).
@@ -32,16 +32,30 @@ 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.
+- **Phase 1 — harvest the knowledge sources FIRST**
+  ([`knowledge-sources.md`](knowledge-sources.md)). Before the first question:
+  query what the project already knows about this task — code, `CLAUDE.md`,
+  `CONTEXT.md`/ADRs, `docs/` + `docs/ux/`, past pipeline briefs and carry-over
+  ledgers, the **knowledge wiki** if one is installed
+  ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki) — recommended,
+  never required), and any **other repo or hosted doc system the project names as
+  its docs**. Write the **source ledger** into the brief (a row per source, or an
+  explicit "none found"). It is retrieval scoped by the task's own nouns, not a
+  read of everything — and it is what makes phase 2's answers checkable instead of
+  merely confident.
 - **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**
+  decision tree, contradictions reconciled on the spot; **every answer that touches
+  a harvested source is checked against it** — the operator outranks any document,
+  but only out loud, and the losing side is logged for the stage-9 doc update; 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→9 blocker.
+  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
@@ -53,14 +67,18 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   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; stages 5–9 read
+  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, **every
+- **GATE (manual):** shared understanding reached — **the source ledger is written
+  (every source consulted, or an explicit "none found")**, every detected branch has
+  a recorded answer or an explicit deferral, **every answer that contradicted a
+  harvested source has a recorded resolution** (which governs, and whether the doc
+  is now stale), no open contradictions, **every
   autonomy-sweep row is answered or explicitly marked "stop and ask here"**, the
-  model decision is recorded, and the operator confirms the brief. Stop when a
+  **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.
 
@@ -73,16 +91,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
-- **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 — 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
@@ -98,8 +140,9 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
      map**: task analysis, user-flow diagrams (branches, error paths), every
      screen + state with wireframe and (Figma on) a Figma frame link.
   4. `ux-scenarios` → `docs/ux/scenarios.md` — the **WHAT** (source of truth for
-     behavior): scenarios validated per the format contract (`scenario-format.md`,
-     ux-contract v4) — IDs, statuses, `Traces:` to stories/journey stages/flows,
+     behavior): scenarios validated against the scenario-format contract super-ux
+     itself ships (`scenario-format.md` — read its current version there, never
+     pin one here) — IDs, statuses, `Traces:` to stories/journey stages/flows,
      edge/error states enumerated.
   5. **Run the super-ux linter** (`/ux-lint` or `python3 docs/ux/lint.py`) — it
      must pass: no drift, no orphans, no broken traces or stale Figma links.
@@ -107,14 +150,15 @@ 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
@@ -122,30 +166,51 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   starts before this — the chain comes BEFORE interface.
 
 ## 4 — Plan
-- **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
+- **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
-- **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 the
-  run's confirmed model (`model-tiering.md`).
-- **GATE (auto):** all plan tasks DONE (two-stage review: spec compliance, then code
-  quality); full test suite green.
+- **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
 - **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.
@@ -158,7 +223,9 @@ 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
@@ -168,9 +235,97 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   steps — never silent success.
 
 ## 9 — Docs + wiki
+- **The stage-0 source ledger is the work list** ([`knowledge-sources.md`](knowledge-sources.md)
+  → *Close the loop*): every source the harvest read gets updated if this run
+  changed or disproved it. What was worth reading at stage 0 and is wrong now is
+  the next run's false premise.
 - 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.
+  change and the linter is green (super-ux *same-change* + *no-drift* rules).
+- **Sync the knowledge wiki** — `wiki-update` when
+  [obsidian-wiki](https://github.com/ar9av/obsidian-wiki) is installed (detect:
+  `~/.obsidian-wiki/config`, or the skill resolves). Not installed → recommend it
+  once with its install line and continue; a missing wiki never blocks the gate.
+  Distil the knowledge (decisions, seams, why), not a diff summary.
+- **Docs living in another repository** are outward: propose the edit, get an
+  explicit go, then open a PR there. No go → the exact edit goes in the carry-over
+  ledger.
+- **GATE (auto):** docs in sync with code; every stale row in the source ledger
+  either updated or carried over with its edit; UI: super-ux layers current +
+  linter green; wiki synced (or absent and recommended once); 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,14 @@
 # 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 |
 

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

@@ -9,12 +9,56 @@
 - **UI verdict:** yes / no — does this touch a user-facing surface (web/mobile/CLI/TUI)?
   If yes, the stage-3 super-ux UX track is armed.
 
+## Knowledge sources (the phase-1 harvest — written BEFORE the first question)
+
+What the project already knew about this task, and where it said so. One row per
+source actually consulted; `none found` is a valid, useful row. Stage 9 updates
+this same list — a source worth reading at the start is the next run's false
+premise if the run leaves it wrong.
+
+| Source | What it says about this task | Fresh? | Authority | Stale after this run? |
+|---|---|---|---|---|
+| `docs/adr/NNNN-….md` | … | YYYY-MM | decision | no |
+| wiki: `projects/…/concepts/…` | … | YYYY-MM | context | **yes — update at stage 9** |
+| `CLAUDE.md` | test/lint/deploy commands, house rules | current | convention | no |
+
+Precedence when two disagree: **code > host docs and ADRs > wiki > memory.** The
+operator outranks every document — but only **out loud**: an override quoted
+against its source is a recorded decision, an unquoted one is an undetected
+divergence.
+
+- **Doc repos / hosted doc systems this project names:** … (or `none`)
+- **Knowledge wiki:** installed / not installed
+  ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki); recommended, never a gate)
+
 ## Scope
 
 - **In scope:** …
 - **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,7 +70,7 @@
 |---|---|---|---|
 | 1 | … | … | … |
 
-## Autonomy (the sweep — stages 1→9 read this instead of asking)
+## 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.
@@ -35,15 +79,19 @@ is not neutral — it is a scheduled interruption.
 |---|---|---|
 | run-wide | Model for this run | … (most capable available unless overridden; per-stage overrides here) |
 | run-wide | Decide autonomously vs escalate to me | … |
+| 0 Harvest | Doc sources beyond this repo — other repos, hosted docs, the knowledge wiki; and may stage 9 write to them? | … (another repo is outward: propose + PR, never a direct push) |
 | 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 | … |
+| 9 Docs+wiki | Which module docs / runbooks this change updates; wiki sync yes/no; which stale ledger rows get fixed | … |
+| 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

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`.