task-pipeline-skill 0.12.0 → 1.0.0

package/plugins/task-pipeline/skills/task-pipeline/pipeline.example.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./pipeline.schema.json",
   "version": 1,
-  "_note": "EXAMPLE ONLY — copy this file, rename to pipeline.json in your project, and rewrite it. This particular example encodes the plugin's own default flow (an up-front intake grill + superpowers + a super-ux UX track for user-facing tasks); it is NOT a fixed contract. Your project defines its own stages (any count), each executed by your own skills/agents, with your own gate types. Stage models use provider-agnostic tokens ('default' = the model confirmed for the run, 'inherit' = whatever the operator is on) — never hardcode a vendor model id, it goes stale. The universal contract is pipeline.schema.json; test/validate.py checks this example against it. gate.type: auto = orchestrator verifies the check itself (pass/fail); manual = wait for an explicit operator go. Which stages are manual vs auto is the operator's decision, not the plugin's.",
+  "_note": "EXAMPLE ONLY — copy this file, rename to pipeline.json in your project, and rewrite it. This particular example encodes the plugin's own default flow (an up-front intake grill + this skill's own built-in stage doctrine + a super-ux UX track for user-facing tasks); it is NOT a fixed contract. Reading skills[] in THIS example: a 'task-pipeline:<name>' entry is not an installable skill — it names this skill's own built-in doctrine file (references/<name>.md, e.g. task-pipeline:grill -> references/grill.md); a 'host:<name>' entry is the host project's own command for that job, resolved from its CLAUDE.md (see references/conventions.md); every other entry is a real skill/agent your environment resolves (super-ux:*, context7, wiki-query, wiki-update). In YOUR pipeline.json, put whatever names your environment actually resolves. Your project defines its own stages (any count), each executed by your own skills/agents, with your own gate types. Stage models use provider-agnostic tokens ('default' = the model confirmed for the run, 'inherit' = whatever the operator is on) — never hardcode a vendor model id, it goes stale. The universal contract is pipeline.schema.json; test/validate.py checks this example against it. gate.type: auto = orchestrator verifies the check itself (pass/fail); manual = wait for an explicit operator go. Which stages are manual vs auto is the operator's decision, not the plugin's. Any repeating loop in a run (fix loop, a re-entered stage, the per-module program loop) is bound by the loop guard: log every repeat touch, stop on oscillation, escalate to the layer that owns the conflict, then re-check in a planned order.",
   "stages": [
     {
       "id": 0,
@@ -9,11 +9,13 @@
       "name": "Intake grill",
       "model": "default",
       "skills": [
+        "task-pipeline:knowledge-harvest",
+        "wiki-query",
         "task-pipeline:grill"
       ],
       "gate": {
         "type": "manual",
-        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). The grill is built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-9 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1."
+        "check": "MANDATORY stage — never skipped (only sanctioned bypass: the entry-from-super-ux short-circuit). PHASE 1, before the first question: harvest the knowledge sources (references/knowledge-sources.md) — code, CLAUDE.md/AGENTS.md, CONTEXT.md + docs/adr, docs/ + docs/ux, past pipeline briefs and carry-over ledgers, the knowledge wiki when installed (obsidian-wiki — recommended, never required; detect ~/.obsidian-wiki/config), and any other repo or hosted doc system the project names as its docs — queried by this task's own terms, with the SOURCE LEDGER written into the brief (a row per source consulted, or an explicit 'none found'). PHASE 2, the grill, built into the skill (references/grill.md) — no companion to install. Per its contract: one question at a time, a recommended answer with each, explore the codebase/docs before asking, depth-first, contradictions reconciled; EVERY answer that touches a harvested source is validated against that source — the operator outranks any document, but only out loud, and the losing side is logged for the stage-9 doc update; domain awareness applied (terms challenged against CONTEXT.md, ADRs recorded for hard-to-reverse calls). The autonomy sweep is covered — every stage 1-10 has its blockers pre-resolved (docs sources, branch/tracker policy, test + lint commands, deploy target and authorization, log/health locations, docs+wiki targets) or is explicitly marked 'stop and ask here'. UI verdict recorded (arms super-ux); model decision recorded. All of it locked into a committed task brief the operator confirms before stage 1. The REQ table is written — one row per independently verifiable deliverable, each naming how it is verified — and frozen: adding later is free, removing or narrowing needs the operator's explicit agreement. The carry-over ledger is seeded."
       }
     },
     {
@@ -33,14 +35,15 @@
     {
       "id": 2,
       "state": "brainstorm",
-      "name": "Brainstorm",
+      "name": "Brainstorm + decompose",
       "model": "default",
       "skills": [
-        "superpowers:brainstorming"
+        "task-pipeline:brainstorm",
+        "task-pipeline:decompose"
       ],
       "gate": {
         "type": "manual",
-        "check": "the user approves the design AND the UI verdict is recorded (does the task touch a user-facing surface — web/mobile/CLI/TUI? this arms the stage-3 UX track)"
+        "check": "the user approves the design AND the UI verdict is recorded (does the task touch a user-facing surface — web/mobile/CLI/TUI? this arms the stage-3 UX track). Every REQ is answered by the design, or explicitly dropped by the operator into the carry-over ledger. For a platform (several independent capabilities or shippable surfaces): the module map specs/<topic>-modules.md is committed and approved — brick criteria met or excepted in writing, dependency graph acyclic, build order topological with the walking skeleton first, every REQ mapped to exactly one module, cross-module contracts named with their owner. Single-module work records 'single module: <name>' instead — a skipped decomposition is a recorded decision, never an omission"
       }
     },
     {
@@ -49,14 +52,16 @@
       "name": "Spec",
       "model": "default",
       "skills": [
+        "super-ux:ux",
         "super-ux:ux-foundation",
         "super-ux:ux-flows",
         "super-ux:ux-scenarios",
-        "superpowers:brainstorming"
+        "super-ux:ux-lint",
+        "task-pipeline:spec"
       ],
       "gate": {
         "type": "manual",
-        "check": "UX track ran FIRST for user-facing tasks (/ux -> ux-foundation CJM -> ux-flows screens -> ux-scenarios -> /ux-lint green); spec committed and user-reviewed; every user-facing requirement traces to a scenario ID"
+        "check": "UX track ran FIRST for user-facing tasks (/ux -> ux-foundation CJM -> ux-flows screens -> ux-scenarios -> /ux-lint green); spec committed and user-reviewed; every user-facing requirement traces to a scenario ID. Every spec section carries covers: REQ-... and every REQ appears in at least one section."
       }
     },
     {
@@ -65,11 +70,11 @@
       "name": "Plan",
       "model": "default",
       "skills": [
-        "superpowers:writing-plans"
+        "task-pipeline:plan"
       ],
       "gate": {
         "type": "auto",
-        "check": "every spec requirement maps to a task; no placeholders; parallel-group tasks share no files; UI tasks name the scenario ID(s) and SCR- screen(s) they implement in their DoD"
+        "check": "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. 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; UI tasks name the scenario ID(s) and SCR- screen(s) they implement in their DoD"
       }
     },
     {
@@ -78,12 +83,12 @@
       "name": "Dev",
       "model": "default",
       "skills": [
-        "superpowers:using-git-worktrees",
-        "superpowers:subagent-driven-development"
+        "task-pipeline:build",
+        "task-pipeline:review"
       ],
       "gate": {
         "type": "auto",
-        "check": "all plan tasks DONE (two-stage review: spec compliance, then code quality); full test suite green"
+        "check": "all plan tasks DONE — the per-task review returns three verdicts (spec compliance, REQ satisfied, code quality); every finding fixed or parked with a written ruling; no task left BLOCKED; full test suite green; the branch integrated per the brief's branch policy (base synced, suite green on the result, worktree removed) — or the operator's explicit 'leave it unmerged' recorded. Every parked finding and implementer concern is harvested into the carry-over ledger before the scratch workspace is deleted."
       }
     },
     {
@@ -92,11 +97,12 @@
       "name": "Tests",
       "model": "default",
       "skills": [
-        "superpowers:test-driven-development"
+        "host:test-runner",
+        "task-pipeline:tdd"
       ],
       "gate": {
         "type": "auto",
-        "check": "full suite green (not just new tests); new/changed code covered; no skip/xfail smuggling a red suite past the gate"
+        "check": "full suite green (not just new tests); new/changed code covered including failure paths; no skip/xfail smuggling a red suite past the gate; tests assert real behavior, not mock behavior"
       }
     },
     {
@@ -110,7 +116,7 @@
       ],
       "gate": {
         "type": "manual",
-        "check": "lint clean and full suite green before deploy; deploy is outward and needs explicit operator go — or the specific standing authorization recorded in the stage-0 brief (named target + named preconditions; a vague 'do everything' is not one)"
+        "check": "lint clean and full suite green before deploy; deploy is outward and needs explicit operator go — or the specific standing authorization recorded in the stage-0 brief (named target + named preconditions; a vague 'do everything' is not one). No REQ is still open; a partial ships only with the operator's explicit acceptance."
       }
     },
     {
@@ -137,7 +143,20 @@
       ],
       "gate": {
         "type": "auto",
-        "check": "docs in sync with code in the same change; wiki synced; dangling links fixed"
+        "check": "the stage-0 source ledger is the work list — every source the harvest read is updated if this run changed or disproved it; docs in sync with code in the same change; wiki synced via wiki-update when obsidian-wiki is installed (absent → recommended once, never a blocker); docs living in another repository are outward — proposed with an explicit go, or carried over with the exact edit; dangling links fixed"
+      }
+    },
+    {
+      "id": 10,
+      "state": "acceptance",
+      "name": "Acceptance",
+      "model": "default",
+      "skills": [
+        "task-pipeline:acceptance"
+      ],
+      "gate": {
+        "type": "manual",
+        "check": "Close the circle: every REQ in the brief has a status (verified / partial / deferred / dropped) — none unknown; every verified carries evidence (a passing test name, file:line, a command and its output, or a scenario ID) — 'done' without evidence is downgraded to partial, not upgraded; every partial names what is missing and where it is tracked; every deferred/dropped has the operator's agreement and, for deferred, a tracker entry; no carry-over row is left unresolved; and the operator answers the closing question — here is what you asked for, here is what shipped, here is what is deferred, what is missing? — and signs off"
       }
     }
   ],

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

@@ -0,0 +1,119 @@
+# Acceptance — stage 10, built in
+
+The pipeline is a funnel: every gate before this one asks *"is this artifact
+good?"* — is the spec committed, does the plan parallelize, is the suite green.
+None of them asks *"does this still contain everything that was asked for?"*
+
+That is this stage's only job: **go back to the brief and account for every
+requirement.** It is what turns the pipeline from a funnel into a circle.
+
+## Why a stage and not a gate
+
+The loss this catches doesn't happen inside a stage — it happens **on the seams**.
+Brief → spec → plan → task briefs is four rewrites by a model, and anything not
+carried forward disappears silently because nothing compares the lists. Stage 4's
+gate catches the brief→plan seam mechanically; stage 10 catches everything the
+run itself decided, deferred, or quietly dropped along the way.
+
+It runs **last** — after docs and wiki (stage 9), because those are deliverables
+too and a requirement may name them.
+
+## Inputs
+
+Read all of them before writing anything:
+
+- the brief's **REQ table** (`docs/superpowers/specs/<topic>-brief.md`)
+- the **carry-over ledger** (`…-carryover.md`) — in full, every row
+- the plan and its task statuses
+- git log for the run's branch; the test suite's final output
+- stage 8's post-deploy notes; stage 9's doc/wiki changes
+- for UI tasks: `docs/ux/scenarios.md` statuses and the `/ux-lint` result
+
+## Output — the coverage table
+
+Write `docs/superpowers/specs/YYYY-MM-DD-<topic>-acceptance.md`:
+
+```markdown
+# Acceptance — <topic>
+
+Run: <branch/commit range> · Date: YYYY-MM-DD
+
+| REQ | Requirement | Status | Evidence |
+|---|---|---|---|
+| REQ-001 | CSV export from a report | verified | `test_export_csv` ✓ · `api/export.ts:88` |
+| REQ-002 | Export respects active filters | verified | `test_export_respects_filters` ✓ · SCN-014 PASS |
+| REQ-003 | Button disabled on an empty report | deferred | agreed 2026-07-28 → LIN-482 |
+| REQ-004 | XLSX export | partial | CSV path done; XLSX missing → LIN-483 |
+
+## Carry-over still open
+
+- (rows from the ledger whose home is not an issue/backlog/`dropped`)
+
+## What the operator should look at
+
+- <anything the run judged, guessed, or deferred that deserves a second opinion>
+```
+
+### The four statuses
+
+| Status | Means | Requires |
+|---|---|---|
+| `verified` | done and demonstrated | **evidence** — a passing test name, `file:line`, command output, or a scenario ID with PASS |
+| `partial` | works for some of what was asked | an explicit list of what's missing + where it's tracked |
+| `deferred` | agreed not to do it now | the operator's agreement **and** a tracker entry |
+| `dropped` | agreed it isn't wanted | the operator's agreement + the reason |
+
+Those four are the only ways a requirement may close. Anything that fits none of
+them is `unknown`, and **`unknown` fails the gate** — that is the whole mechanism:
+the run cannot end while a requirement is still unclassified.
+
+## Evidence, not assertion
+
+**"Done" without evidence is not done.** This is the same rule the review rubric
+and the test-honesty rules apply one level down, raised to the level of intent:
+
+- A passing test **name**, not "tests pass".
+- A `file:line`, not "implemented in the export module".
+- A command **and its output**, not "verified manually".
+- For user-facing behavior, the scenario ID and its status.
+
+If the evidence for a requirement is "I read the code and it looks right", the
+status is `partial`, not `verified` — say so plainly rather than upgrading it.
+
+## The closing question
+
+The table is preparation. The stage exists for the question that follows it, asked
+out loud, with the list in front of the operator:
+
+> 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 all green. The operator holds context the brief
+never captured, and this is the cheapest moment in the whole run to hear it. An
+answer here becomes new REQ rows or new ledger entries — not a new argument about
+whether the run was finished.
+
+## GATE (manual)
+
+All of:
+
+1. **Every REQ has a status** — none `unknown`, none blank.
+2. **Every `verified` carries evidence** of the kind above.
+3. **Every `partial` names what's missing** and where it's tracked.
+4. **Every `deferred` / `dropped` has the operator's agreement** recorded (in the
+   ledger or here) and, for `deferred`, a tracker entry.
+5. **No carry-over row is left `unresolved`** — every one has a home.
+6. **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*. Do not let a green
+table substitute for that answer.
+
+## When the answer is "something's missing"
+
+Don't argue and don't re-litigate the gates. Add the missing thing as a new REQ
+row (with its check) or a ledger entry, then say plainly what it costs: a fix now,
+or a tracked follow-up. Both are legitimate outcomes of this stage. Closing the
+run with a known gap is fine **if the gap is written down** — closing it with the
+gap only in someone's memory is the failure mode this whole spine exists to
+prevent.

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

@@ -15,7 +15,10 @@ docs/
   superpowers/
     specs/
       YYYY-MM-DD-<topic>-brief.md     # stage 0 — locked intake brief (grill output)
-      YYYY-MM-DD-<topic>-design.md    # stage 3 — the spec (locks shared contracts)
+      YYYY-MM-DD-<topic>-carryover.md # stage 0 seeds it; EVERY stage appends; stage 10 reads it
+      YYYY-MM-DD-<topic>-modules.md   # stage 2 — module map + build order (platforms only)
+      YYYY-MM-DD-<topic>-design.md    # stage 3 — the spec / module dossier (locks shared contracts)
+      YYYY-MM-DD-<topic>-acceptance.md # stage 10 — REQ coverage table + evidence
     plans/
       YYYY-MM-DD-<topic>.md           # stage 4 — the implementation plan
   ux/                                 # super-ux, UI tasks only (see companion-skills.md)
@@ -29,16 +32,34 @@ docs/
 ```
 
 Naming: date-prefixed `YYYY-MM-DD-<topic>` slugs, one topic per file, kebab-case.
-The three superpowers artifacts share the **same `<topic>` slug** so brief →
-design → plan is traceable at a glance.
+Brief, carry-over, design, plan and acceptance share the **same `<topic>` slug**, so the chain is traceable
+at a glance.
+
+> The `docs/superpowers/` directory name is this pipeline's historical convention
+> (kept so existing projects don't have to migrate) — **not a dependency on any
+> external skill**. A host project may relocate the root via its `CLAUDE.md`; keep
+> the shape, keep the slugs.
+
+Loop-bearing runs also keep a **git-ignored** run ledger at `.task-pipeline/run.md` —
+stage-level and program-level repeat touches, one line each, so the loop guard can
+detect churn after a lost context (see [`loop-guard.md`](loop-guard.md)).
+
+Stage 5 also creates a **git-ignored** scratch workspace per plan at
+`.task-pipeline/build/<plan-basename>/` — ledger, task briefs, implementer reports,
+review packages. It is deleted when the final review is clean; git history is the
+record (see `build.md`).
 
 ## Stage → artifact map
 
 | Stage | Writes | Consumed by |
 |---|---|---|
-| 0 Intake | `specs/<topic>-brief.md` (seed from the skill's `templates/brief.md`) | stages 2–4 |
+| 0 Harvest | the brief's **Knowledge sources** ledger — every source consulted, its freshness, whether this run makes it stale | the grill (validation), **stage 9** (the update work list) |
+| 0 Intake | `specs/<topic>-brief.md` — incl. the **REQ table** (seed from `templates/brief.md`) | stages 2–5, 7, 10 |
+| 0→10 all | `specs/<topic>-carryover.md` — append-only ledger (seed from `templates/carryover.md`) | stage 10, in full |
+| 10 Acceptance | `specs/<topic>-acceptance.md` — every REQ with a status and evidence | the operator |
 | 0 Grill (domain) | `CONTEXT.md`, `docs/adr/NNNN-<slug>.md` — created **lazily**, only when a term resolves or a decision qualifies | stages 2–4 + the repo |
-| 3 Spec | `specs/<topic>-design.md` (+ links `docs/ux/*` for UI) | stage 4 |
+| 2 Decompose | `specs/<topic>-modules.md` — module map, build order, contracts, per-module status (platforms only) | stages 3–10, every module's run |
+| 3 Spec | `specs/<topic>-design.md` — module dossier for a decomposed platform (+ links `docs/ux/*` for UI) | stage 4 |
 | 4 Plan | `plans/<topic>.md` | stage 5 |
 | 3 UX track | `docs/ux/{foundation,flows,screens,scenarios}.md` | stages 4–9 + `/ux-lint` |
 | 8 Post-deploy | log/health notes (in the run, not a committed file) | stage 9 |
@@ -47,22 +68,34 @@ design → plan is traceable at a glance.
 ## This repo (task-pipeline itself), for reference
 
 ```
-.claude-plugin/marketplace.json              # marketplace manifest
+.claude-plugin/marketplace.json               # marketplace manifest
 plugins/task-pipeline/
-  .claude-plugin/plugin.json
+  .claude-plugin/plugin.json                  # plugin manifest
   commands/task-pipeline.md                   # /task-pipeline
   skills/task-pipeline/
-    SKILL.md
+    SKILL.md                                  # the orchestrator itself
     pipeline.schema.json                      # generic pipeline contract
     pipeline.example.json                     # this plugin's own flow, as config
-    references/{grill,stages,model-tiering,conventions,artifacts,companion-skills}.md
+    references/                               # built-in stage doctrine:
+      knowledge-sources.md grill.md           #   stage 0 (harvest, then interview)
+      brainstorm.md decomposition.md          #   stage 2
+      spec.md planning.md                     #   stages 3-4
+      build.md review.md tdd.md               #   stages 5-6
+      acceptance.md                           #   stage 10
+      loop-guard.md                           #   cross-cutting: churn detection
+      stages.md model-tiering.md              #   gates, model policy
+      conventions.md artifacts.md             #   host conventions, this layout
+      companion-skills.md                     #   optional companions + preflight
+    templates/                                # skeletons seeded into a host project
+      README.md brief.md carryover.md context.md adr.md
 cursor/rules/task-pipeline.mdc                # Cursor channel (self-contained rule)
-plugins/task-pipeline/skills/task-pipeline/templates/{brief,context,adr}.md      # stage-0 skeletons (ship on every channel)
 bin/task-pipeline.js                          # npx installer (package task-pipeline-skill)
-package.json
 install.sh                                    # POSIX installer
-test/validate.py                              # structural validator
-.github/workflows/{validate,release}.yml      # CI + toggleable release
-README.md  CHANGELOG.md  LICENSE
+test/validate.py                              # structural validator (npm test)
+.github/workflows/{validate,release}.yml      # CI + toggleable release automation
+.github/ISSUE_TEMPLATE/  .github/PULL_REQUEST_TEMPLATE.md
+package.json  .gitignore
+README.md  CHANGELOG.md  LICENSE  CLAUDE.md
+CONTRIBUTING.md  SECURITY.md  CODE_OF_CONDUCT.md
 docs/superpowers/{specs,plans}/               # this repo's own design history
 ```

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

@@ -0,0 +1,108 @@
+# Brainstorm — stage 2, built in
+
+The design conversation is **part of this skill**. No companion to install, no
+provider to resolve, nothing to fall back to: this file is the implementation.
+
+Stage 0 locked *what* is being built. Stage 2 decides *how*, and stops at an
+approved design — not at code.
+
+> Ported, with thanks, from the `brainstorming` skill in
+> [obra/superpowers](https://github.com/obra/superpowers) (MIT — see this repo's
+> `LICENSE` → *Third-party*), rewritten for this pipeline: the brief is the input,
+> the UI verdict is a required output, and the spec write-up moved to stage 3
+> ([`spec.md`](spec.md)).
+
+## The hard gate
+
+**No implementation action before the operator approves a design.** No code, no
+scaffolding, no file creation "to see how it'd look", no invoking a
+frontend/backend/build skill. This holds for every task regardless of how simple it
+looks.
+
+**"Too simple to need a design" is the trap, not the exception.** A one-function
+utility, a config flip, a copy change — all of them go through this stage. Simple
+tasks are where unexamined assumptions survive longest. The design may be three
+sentences; it still gets presented and approved.
+
+## Input: the brief, not a blank page
+
+Read the stage-0 brief first (`…-brief.md`). Everything it locked — scope, users,
+constraints, done-criteria, the autonomy sweep — is **settled**. Re-asking a
+question the grill already answered is the single most common way to waste this
+stage. If the brief and the codebase disagree, that's a contradiction to surface,
+not a question to re-open from scratch.
+
+## The loop
+
+1. **Explore the current state.** Files, module docs, recent commits, the
+   conventions the repo already follows. Do this before asking anything.
+2. **Scope check, early.** If the task actually describes several independent
+   capabilities or separately shippable surfaces, say so immediately: that is a
+   **platform**, and it gets cut into modules at the end of this stage by
+   [`decomposition.md`](decomposition.md), before any spec is written. Brainstorm
+   the platform's shape — the pieces, how they relate, what order they land in —
+   not the details of one corner; those belong to each module's own stage-3
+   dossier. Don't refine something that needs splitting first.
+3. **Questions one at a time.** Never bundle. Multiple choice where it fits, open
+   where it doesn't. Purpose, constraints, success criteria — anything the brief
+   left at design level.
+4. **Propose 2–3 approaches with trade-offs**, lead with your recommendation and
+   the reason for it. **YAGNI ruthlessly** — strip anything the task doesn't need
+   from every option before presenting.
+5. **Present the design in sections**, each scaled to its complexity (a couple of
+   sentences when it's straightforward, up to a few hundred words when it's
+   genuinely nuanced). Ask after each section whether it holds. Cover:
+   architecture, components, data flow, error handling and degradation, testing.
+6. **Go back when something doesn't fit.** A revised section beats a design that
+   was approved because it was hard to argue with.
+
+## Design for isolation and clarity
+
+- Break the system into units with **one clear purpose each**, communicating
+  through well-defined interfaces, understandable and testable on their own.
+- For every unit you should be able to answer: what does it do, how is it used,
+  what does it depend on?
+- Can a reader understand a unit without reading its internals? Can the internals
+  change without breaking consumers? If not, the boundaries need work.
+- Smaller focused files are also what the *implementer* (often a subagent with a
+  narrow context) handles reliably. A file growing large is usually a signal it
+  does too much.
+
+## Working in an existing codebase
+
+- Explore the structure before proposing changes; follow the patterns already
+  there.
+- Where existing code genuinely blocks the work — a file that's grown unwieldy,
+  tangled responsibilities, an unclear boundary the change has to cross — include
+  the targeted improvement in the design, the way a careful developer improves code
+  they're working in.
+- Don't propose unrelated refactoring. Anything out of scope goes to the backlog,
+  not into this design.
+
+## UI detection — a required output
+
+One branch is always: **does this touch a user-facing surface** (web, mobile, CLI,
+TUI — a screen, a command, a visible behavior)? Stage 0 usually answered it; this
+stage confirms it against the design that actually emerged. Record the verdict —
+it arms the stage-3 UX track ([`spec.md`](spec.md) → *UX track*). When it's
+genuinely borderline, record "yes": a false positive costs one extra chain, a false
+negative ships an unspecified interface.
+
+## GATE (manual)
+
+The operator approves the design **and** the UI verdict is recorded **and every REQ
+in the brief 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 written
+into the carry-over ledger. For a platform, the module map
+([`decomposition.md`](decomposition.md)) is committed and approved as part of this
+same gate. Then, and only then, stage 3 writes it up.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "The brief already says everything" | The brief locks *what*. If it also locked *how*, say so in one line and get the approval anyway — the gate is the point. |
+| "It's a one-line change, design is ceremony" | Then the design is one line. Present it. |
+| "I'll scaffold while they think" | Scaffolding is implementation. The gate is before it, not around it. |
+| "Both approaches are fine, let them pick" | You read the codebase, they didn't. Recommend, then let them override. |
+| "I'll add the extra option now, it's cheap" | YAGNI. Every unused branch is code someone maintains and a test someone writes. |