task-pipeline-skill 0.12.0 → 1.0.0

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

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

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

@@ -4,7 +4,7 @@ The intake grill is **part of this skill**. No companion skill to install, no
 provider to resolve, nothing to fall back to: this file *is* the implementation.
 
 Its job is not to design. It is to take a one-line request ("make me feature X")
-and interview it into a brief complete enough that stages 1→9 finish without
+and interview it into a brief complete enough that stages 1→10 finish without
 coming back to the operator.
 
 > Adapted, with thanks, from Matt Pocock's `grilling` / `grill-with-docs` skills
@@ -12,7 +12,27 @@ coming back to the operator.
 > half — glossary challenges, `CONTEXT.md`, ADR discipline — comes from there; the
 > autonomy sweep and the brief are this pipeline's.
 
-## The loop
+## Phase 1 — harvest before you ask
+
+**Do not open the interview cold.** Stage 0 begins by finding what the project
+already knows about this task: the code, `CLAUDE.md`, `CONTEXT.md` and the ADRs,
+`docs/` and `docs/ux/`, past pipeline briefs, the **knowledge wiki** when one is
+installed, and any **other repository or hosted doc system the project names as
+its docs**. Full procedure, source order, the wiki's detection and install line,
+and the ledger to write: [`knowledge-sources.md`](knowledge-sources.md).
+
+Two things come out of it, both required before question one:
+
+- the **source ledger** in the brief — one row per source consulted, what it says
+  about this task, and how fresh it is (`no sources found` is a valid row);
+- the list of things you therefore **don't need to ask**, and the specific points
+  where a source looks stale or ambiguous — those become the sharpest questions.
+
+Everything below runs against that harvest. An answer you can't check against a
+source is a recollection, and the whole loop exists to stop the run from building
+on one.
+
+## Phase 2 — the loop
 
 Interview the operator relentlessly about every aspect of the task until you reach
 a **shared understanding**. Walk down each branch of the decision tree, resolving
@@ -73,6 +93,15 @@ Create these files **lazily** — only when you have something real to write.
   check whether the code agrees, and surface contradictions: *"Your code cancels
   entire Orders, but you just said partial cancellation is possible — which is
   right?"*
+- **Cross-reference with the harvest — every answer, not just the domain ones.**
+  Phase 1 put the ADRs, runbooks and wiki pages in your hands; use them the same
+  way: *"The March ADR says orders are written only through the command handler,
+  you just described a direct write — has that changed?"* 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. When two sources
+  disagree, precedence is code > host docs/ADRs > wiki > memory, and the loser is
+  logged for the stage-9 update ([`knowledge-sources.md`](knowledge-sources.md) →
+  *Phase 2*).
 - **Update `CONTEXT.md` inline.** Resolve a term → write it down right then, not in
   a batch at the end. Format: [`templates/context.md`](../templates/context.md).
   Keep it free of implementation detail — only terms a domain expert would
@@ -95,19 +124,23 @@ numbering (scan for the highest number, increment).
 ## The autonomy sweep
 
 Resolving the *task* is not enough. The grill must also pre-resolve everything that
-would otherwise stop stages 1→9 mid-flight. Every row gets an answer **or** an
+would otherwise stop stages 1→10 mid-flight. Every row gets an answer **or** an
 explicit "stop and ask me here":
 
 | Stage | What to settle up front |
 |---|---|
 | run-wide | the model decision ([`model-tiering.md`](model-tiering.md)); what to decide autonomously vs escalate |
+| 0 Harvest | doc sources beyond this repo — other repos, hosted doc systems, the knowledge wiki — and whether stage 9 may write to them (another repo is outward: propose + PR, never a direct push) |
 | 1 Docs | external libs/APIs/SDKs in play; any private ones context7 can't resolve → where their docs live |
+| 2 Decompose | is this a platform (several capabilities/surfaces) or one module? if platform: deploy cadence — per module or once at the end |
 | 2–3 Spec | UI verdict (arms super-ux); any scenario-tracing waiver |
 | 4–5 Dev | base branch; worktree/branch policy; is `main` off-limits; commit convention; task tracker |
+| 5 Integration | how the branch lands (merge / PR + approver / "leave it unmerged"); parallel fan-out wanted (one worktree per implementer)? |
 | 6 Tests | the test command; what "green" means here; known-red baseline; coverage expectation |
 | 7 Lint+deploy | lint command; deploy target and path; release automation on/off; deploy-from-main rule; **deploy authorization** |
 | 8 Post-deploy | where logs / health live (app name, endpoint, workflow) |
 | 9 Docs+wiki | which module docs / runbooks this change updates; wiki sync yes/no |
+| 10 Acceptance | who signs off; where deferred REQs are tracked (issue tracker, backlog) |
 
 **Deploy authorization has a hard floor.** Deploy and publish are outward and
 irreversible, so a vague "just do everything" authorizes nothing. A standing
@@ -116,14 +149,52 @@ preconditions ("staging once lint and the full suite are green; production alway
 asks"). Specific and recorded → it satisfies the stage-7 manual gate. Broader,
 absent or ambiguous → stage 7 stops and asks.
 
+## The REQ spine — the grill's other hard output
+
+Prose scope is not checkable. Before the brief is confirmed, the grill must turn
+what was asked into an **addressable list of requirements**, because every later
+stage traces to these IDs and stage 10 accounts for every one of them.
+
+| ID | Requirement | How it's verified | Status |
+|---|---|---|---|
+| REQ-001 | … | test name / `file:line` / command + expected output / `SCN-…` | open |
+
+Three rules that decide whether the spine is worth anything:
+
+1. **One REQ = one independently verifiable deliverable.** Not one per sentence of
+   the request. A small task gets three rows, not thirty — an inflated table is
+   ignored, and an ignored table protects nothing.
+2. **Every row names its check.** *A requirement you can't say how to verify is a
+   badly-stated requirement* — split or sharpen it here, during the grill. This is
+   the single defence against the failure mode where three vague REQs cover a large
+   task and acceptance goes green over half of it.
+3. **Ask what "finished" means per row, not for the task overall.** "Export works"
+   hides five decisions; "exports the currently filtered rows as CSV, verified by
+   `test_export_respects_filters`" hides none.
+
+**Then freeze it.** Adding a requirement mid-run is fine — append with its source.
+**Removing or narrowing one requires the operator's explicit agreement**, recorded
+in the carry-over ledger. Quietly restating the task in smaller terms is the
+subtlest way to lose it: every gate downstream then passes honestly, on a task
+that shrank without anyone deciding it should.
+
 ## Output
 
 Everything resolved goes into the **task brief**, seeded from
 [`templates/brief.md`](../templates/brief.md) and committed to
-`docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` — scope, users, UI verdict,
-constraints, locked decisions, the autonomy table, done-criteria, open
-assumptions. Seed the template only when the file is absent; never overwrite an
-existing brief.
+`docs/superpowers/specs/YYYY-MM-DD-<topic>-brief.md` — scope, **the REQ table**,
+**the phase-1 source ledger**, users, UI verdict, constraints, locked decisions,
+the autonomy table, done-criteria, open assumptions. Seed the template only when
+the file is absent; never overwrite an existing brief.
+
+The ledger is not decoration: **stage 9 updates exactly what stage 0 read**, and
+every doc the grill proved stale is already listed there with what's wrong.
+
+Alongside it, seed the **carry-over ledger** from
+[`templates/carryover.md`](../templates/carryover.md) at
+`…-carryover.md` — append-only, written by every later stage, read in full by
+stage 10. Anything deferred, dropped, or half-done from here on goes there the
+moment it's said: **deferred out loud is forgotten.**
 
 Plus, where the session produced them: an updated `CONTEXT.md` and any ADRs, each
 written as the decision landed.

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

@@ -0,0 +1,159 @@
+# Knowledge sources — harvest before the grill, update after the build
+
+Stage 0 has two phases. This file is **phase 1**: before the first question is
+asked, find and read what the project already knows about this task. The interview
+([`grill.md`](grill.md)) is phase 2, and it runs *against* what was harvested here.
+
+The same source list closes the loop at **stage 9**: what was read at the start is
+what gets updated at the end. A source good enough to answer a question is a source
+that goes stale when the answer changes.
+
+## Why this is a phase and not "explore a bit first"
+
+An agent that starts asking without harvesting spends the operator's turns on
+questions the project already answered — in an ADR, in a runbook, in a wiki page
+written three months ago by the same person now being asked. That is the expensive
+failure, but not the worst one.
+
+The worst one is silent: **the operator misremembers, the agent believes them, and
+the run builds on it.** People answer from memory about systems they wrote a year
+ago. Without the documents in hand you cannot tell a decision from a recollection,
+so every later gate passes honestly on a false premise. Harvesting first is what
+makes the grill's answers *checkable* instead of merely confident.
+
+## The sources, in the order to try them
+
+| # | Source | How to find it | What it's good for |
+|---|---|---|---|
+| 1 | **The code** | the repo you're in | what actually runs — the tiebreaker |
+| 2 | **Host agent docs** | `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/` | conventions, commands, deploy path, house rules |
+| 3 | **Domain docs** | `CONTEXT.md` / `CONTEXT-MAP.md`, `docs/adr/` | the glossary and the decisions with their reasons |
+| 4 | **Product/UX docs** | `docs/ux/` (super-ux chain), `README`, runbooks | user-facing behavior that is already specified |
+| 5 | **Pipeline history** | `docs/superpowers/specs/`, `plans/`, past `-carryover.md` | what a previous run of this pipeline decided or deferred |
+| 6 | **The knowledge wiki** | see below | distilled cross-project knowledge, prior sessions, why decisions were made |
+| 7 | **Other doc repos the project names** | a docs repo URL or submodule in `CLAUDE.md`/`README`, a sibling checkout, a `docs/` monorepo package | specs, contracts and runbooks that live outside this repo |
+| 8 | **Hosted doc systems the project names** | Notion / Confluence / Google Docs referenced in the project | the same, when the team keeps them there |
+
+Rules for the list:
+
+- **Never invent a source.** A doc repo is in scope because the project names it,
+  not because it plausibly exists. Nothing is cloned or fetched on a guess.
+- **Sources 7–8 are read-only at this stage**, and reading a hosted system needs a
+  connected tool — if there's no tool, record the gap and ask the operator to paste
+  what matters rather than pretending the source was covered.
+- **The wiki is optional; the harvest is not.** With no wiki and no doc repos, the
+  harvest is sources 1–5 and takes two minutes. Skipping it is never the answer.
+
+## The knowledge wiki — recommended
+
+The wiki this pipeline is built to work with is
+**[obsidian-wiki](https://github.com/ar9av/obsidian-wiki)** (Karpathy's LLM-wiki
+pattern: raw sources → distilled wiki → schema). It is the one source that carries
+*why* across projects and across months, which is exactly what a fresh context lacks.
+
+**Detect it** — any of: `~/.obsidian-wiki/config` exists; the `wiki-query` /
+`wiki-update` skills resolve.
+
+- **Installed → use it.** Query it during the harvest (`wiki-query`, or the vault's
+  `index.md` + a targeted grep when the skill isn't loaded), and sync back at stage
+  9 (`wiki-update`).
+- **Not installed → recommend it once, in the preflight block, with the line:**
+
+  ```
+  pip install obsidian-wiki
+  obsidian-wiki setup --vault /path/to/your/vault
+  ```
+
+  Then continue without it. It is a **recommendation, never a gate** — no stage
+  blocks on a missing wiki, and the pipeline never nags twice in a run.
+
+## How to harvest — retrieval, not reading
+
+The harvest is bounded by the *task*, not by the size of the sources. You are not
+reading the wiki; you are asking it about this task.
+
+1. **Take the task's nouns** — the entities, the feature name, the subsystem, the
+   file paths the operator mentioned — plus their obvious synonyms.
+2. **Query each source with those terms**: `wiki-query` for the wiki; `grep`/`Read`
+   for repo docs; the tracker/hosted-doc tool if one is connected.
+3. **Follow one hop, not ten.** A hit that names an ADR, a scenario id or a module
+   is worth opening. A page three links away is context, not evidence.
+4. **Stop when the terms stop returning anything new.** Same rule as the interview:
+   no grinding past diminishing returns.
+
+## Record it — the source ledger
+
+Write what you found into the brief's **Knowledge sources** section
+([`templates/brief.md`](../templates/brief.md)) before the first question. One row
+per source actually consulted:
+
+| Source | What it says about this task | Fresh? | Authority |
+|---|---|---|---|
+| `docs/adr/0007-single-write-model.md` | orders are written only through the command handler | 2026-03 | decision |
+| wiki: `projects/x/concepts/billing-seams` | why invoicing was split out; the retry rule | 2026-06 | context |
+| `CLAUDE.md` | test = `npm test`, deploy from `main` only | current | convention |
+| (none for the export UI) | — | — | — |
+
+The ledger is what makes phase 2 work: during the interview you cite rows from it,
+and at stage 9 you update the same rows. A source consulted but not recorded is a
+source nobody will update.
+
+**"No sources found" is a valid, recorded outcome.** Write the row. An empty ledger
+tells the next run that the search happened and came back empty — silence doesn't.
+
+## Phase 2 — validate the answers against the harvest
+
+This is the payoff, and it belongs to the grill loop
+([`grill.md`](grill.md) → *Domain awareness*). Every operator answer that touches a
+harvested source gets checked against it, on the spot:
+
+> "The ADR from March says orders are written only through the command handler —
+> you just described a direct write. Has that changed, or should the export go
+> through the handler?"
+
+Three shapes and what to do with each:
+
+| The answer… | Do |
+|---|---|
+| **agrees** with the source | nothing — note it, move on |
+| **contradicts** a source | quote the source, name the conflict, ask which governs. The answer is either "the doc is stale" (→ it gets updated at stage 9, log it now) or "I misremembered" (→ the doc stands). Both are cheap here and expensive at stage 6 |
+| **goes beyond** every source | this is new knowledge — it belongs in the brief, and usually in `CONTEXT.md` or an ADR as it lands |
+
+**The operator outranks the docs — but only out loud.** A person may overrule any
+document; they may not do it by accident. The point of quoting the source is that
+the override becomes a recorded decision instead of an undetected divergence.
+
+**Precedence when two sources disagree with each other:** code > host docs and
+ADRs > the wiki > anyone's memory. The wiki is *distilled* knowledge and can lag
+the repo by months; the code is what runs. A disagreement between them is a grill
+question, never a silent pick — and it is usually a sign the doc is due an update.
+
+## Close the loop — stage 9 updates what stage 0 read
+
+The ledger is the stage-9 work list. For each row:
+
+- **Host repo docs, ADRs, runbooks, `docs/ux/`** — updated in the **same change**,
+  per the host's own rules ([`conventions.md`](conventions.md)).
+- **Anything the run proved stale** — including a doc that was "wrong but nobody
+  had time": that's why the conflict was logged in phase 2 instead of only being
+  resolved verbally.
+- **The wiki** — `wiki-update` syncs what this run learned. Distil the *knowledge*
+  (decisions, seams, gotchas, why), never a diff summary.
+- **Another repository's docs** — writing to a repo the operator didn't ask you to
+  touch is **outward**: propose the change, get an explicit go, then open a PR
+  there. Absent a go, it goes in the carry-over ledger with the exact edit needed.
+
+A source that was worth reading at stage 0 and is wrong at stage 9 is the next
+run's false premise. Closing that loop is the whole point of harvesting from a
+written list instead of from whatever the search happened to surface.
+
+## Rationalizations
+
+| Excuse | Reality |
+|---|---|
+| "I'll just ask them, it's faster" | You'll ask about things a doc already answers, and you'll believe an answer you can't check. Retrieval is cheaper than a turn. |
+| "The wiki's probably stale" | Then say so with the page in hand and get it corrected. "Probably stale" unread is an assumption; read, it's a finding. |
+| "No docs in this repo" | Check `CLAUDE.md` for the repo that has them, and the wiki for the last time anyone touched this. Then record the empty ledger. |
+| "The operator knows their own system" | They do — a year ago, before three other people changed it. That's the exact case where quoting the doc pays. |
+| "Reading the whole wiki costs too much" | The harvest is a query per task noun, not a read. If it feels expensive, you're reading instead of retrieving. |
+| "I'll update the docs at the end from memory" | The ledger exists because the end is exactly when you no longer remember which sources you leaned on. |

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

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