# Harvest — the stop pipeline

Load when: `/brainstorm stop`; any question about where session content lands. The twin reads it to build the manifest.

Stop is a fixed pipeline: converge, final sync, one approval, apply, the uselessness test, the move, the offer. You orchestrate it, because every approval belongs to the user; the twin executes each leg as a `stop` dispatch. The session's product is the mutated living docs, so the pipeline's exit condition is checkable: a context-free reader given only the harvested destinations reconstructs the design. Until that passes, the folder stays under `docs/research/`, visibly unfinished.

## 1. Converge

Every open fork is resolved into a decision or parked with a destination, now.

- **Offer one blindspot pass first** if none has run this session: one line, yes or no. A yes dispatches it before the convergence.
- Run the convergence as converge picks: one pick per fork, recommendation first, batched. A park names where its resolution will land.
- The user may resolve or park; they may not leave a fork open. A fork the user will not decide is parked to the repository's open-questions home.

## 2. Final sync and manifest

Dispatch the twin, scope `final sync + compose + manifest`. It reconciles, composes, runs the detector at `--gate=manifest`, and builds `ops/manifest.md` (`Status: proposed`) only when that gate is clean. While the gate fails, relay what blocks in plain words and go back to step 1.

## 3. One approval

Show the manifest table and ask once: approve, or name the rows to change. This is the designed gate before the harvest writes into canonical documents; nothing is written until it is answered, and on silence the session stays open with the manifest proposed. Under standing approval ("don't seek any more approvals"), record the approval as standing and continue.

## 4. Apply

Dispatch the twin, scope `apply`. It sets `Status: approved`, reads **both sides** of every destination before writing (the destination's current content is a contract, not a blank page), formats each artifact through the `documentation` skill, and sets `Status: applied`.

**The apply is all-or-nothing and loud.** If it cannot finish, the twin reports exactly what applied and stops; relay that verbatim. The folder stays under `docs/research/`, and the user restarts the stop. Never resume silently from a half-applied state: a bad harvest corrupting canonical docs is worse than a skipped one, and a loud early failure the user can fix beats damage discovered after the folder is gone.

## 5. The uselessness test

Dispatch the twin, scope `uselessness test`. It spawns a fresh, context-free cold reader whose brief holds only the allowed-path list (the manifest's destinations, never the session folder) and the task to reconstruct the design: the thesis, the commitments, the reasoning, the declined branches. It grades the reconstruction against the ledger and the thesis and records the result in the manifest.

- **Pass** (`Result: pass`, `Gaps: none`) → step 6.
- **Gaps** → each is a named piece of knowledge the destinations lost. The fix re-enters at step 3 as a delta manifest (`Round` incremented), approved like the first, then applied and retested.

If the twin reports it cannot spawn a sub-agent, dispatch the cold reader yourself, on the **standard tier** (Sonnet on Anthropic; the flagship model at default reasoning effort on OpenAI): reconstruction from a short path list is synthesis, not frontier work. Its brief is the allowed-path list and the reconstruction task, nothing else; give the twin its reply to grade. Neither you nor the twin may be the reader: a reader that has seen the session already knows every undefined term.

## 6. The move

Dispatch the twin, scope `move`. It runs `--gate=move`, deletes `ops/`, moves the folder to `docs/history/brainstorms/{topic}/` (with `git mv` when any file in it is tracked, plain `mv` when none is, because `git mv` refuses a never-committed folder), and sets `Status: harvested`. The location is the completion marker: a folder still under `docs/research/` is unfinished by definition. Under standing approval, hold this step and step 7 for the end-of-session message, because deleting the untracked capture cannot be undone.

## 7. The offer

Relay the twin's offer as one question: **delete the moved folder, or commit it.** The design assumes deletion, since the uselessness test has made the folder redundant; committing keeps a git-history record the user chose. An uncommitted folder deleted at stop leaves no forensics, which the user accepts by choosing delete.

## Where content lands

The twin routes by scope, never by surface file:

| Piece of the surface | Destination |
| --- | --- |
| The whole surface, distilled | one reader-first source-of-truth document at the repository's canonical home (`docs/features/`, `docs/architecture/`, else a topic `Readme.md`): the thesis as what it is, the domain fragment as how it works, the ledger as present-tense rationale with no `D`/`F` codes |
| Executable work | plans, split by deliverable, never by surface file |
| Decisions | one record per decision subject; a decision revising a recorded subject updates that record in place, its declined alternatives riding along |
| Domain-model changes | the living domain-model document, which the `boundary` skill reads at the next plan check |
| Parked forks | the repository's open-questions home, each pointing to where its resolution will land |
| Will-build-later | the backlog |
| Deliberately-not-building | the destination's non-goals |
| Weighed and chose another | a **Declined:** line with its re-evaluate condition, in the decision record or the source-of-truth document's rationale |

- **Rejection rationale and reasoning chains need an explicit destination**, or the uselessness test fails; they are what living docs lose first.
- **No destination links back into the session folder.** The folder is about to be deleted; a link into it is a pointer to nothing, and the detector fails the move on one.
- **Steering is not feature truth.** A harvested principle goes to the steering layer (`docs/architecture/`); a feature fact goes to its feature doc. The harvest links between them and never copies prose across them.
- **Starting or harvesting a session edits no index.** The folder's location is the record.

## Degradations — flagged, never silent

| Missing | Then |
| --- | --- |
| The `documentation` skill | the twin formats the artifacts itself, and the manifest records which path ran |
| Nested sub-agent dispatch | you dispatch the cold reader (step 5) |
| The detector, or Node | the twin runs the schema's checks by hand and says so in its report; relay it as a flagged fact |
| Any leg failing | the twin logs `S<n> → failed` with the reason; relay it and re-run that leg |

## Field lessons — apply

Each was measured on a live harvest; the twin applies them, and you relay where one changes what the user sees.

- **The move gate run immediately before the move is the verdict.** Its checks read `ops/`, which the move deletes, so a re-run after the move fails by construction. Verify the post-move state by hand instead: `Status: harvested`, no `ops/`, links resolving.
- **Distil the process record into `state.md` before the move.** The sync log dies with `ops/`; a ten-line dispatch summary separates a record that shows its workings from one that asserts its decisions from nowhere.
- **A never-committed harvest artifact that turns out wrong is deleted, not deprecated.** Deprecating in place protects readers holding a pointer, and a file that was never committed has none.
- **At manifest time, read every existing architecture decision's Decision and open questions against the new decisions.** A harvest routes only through the docs its decisions name, and the ledger never names the neighbours, so grep finds nothing: the test is decision against decision. Report the unaffected verdicts with their evidence too.
- **A manifest row names one site; the file it opens holds more.** Fix every site of the same doctrine inside a file the manifest already opens, since a self-contradicting document is worse than a wider diff, but never wander into a file no row names: that becomes a backlog row, because a canonical doc is not rewritten outside an approved scope. Say per row which you did.
- **Re-run the uselessness test when the destination set changes**, not only when content does: a consolidation that moves referrers produces a document set no cold reader has graded. The recurring find is a truth doc stating a decided-but-unbuilt mechanism in the present tense; the fix is one clause naming the unbuilt prerequisite.
- **Rephrase a retirement rather than suppress the linter.** `doc-lint` blocks honest retirement sentences ("superseded by", "no longer"); say "retired by" the record, "is not the product's position", "lives in a package that is gone", and reach for `doc-lint-disable` only when the banned phrase is itself the claim.
- **Amending another session's draft: change the contradicting claim everywhere it is asserted, and nothing else.** A claim stated in nine places and fixed in three leaves the doc worse; a one-paragraph note on what changed and what did not keeps the amendment legible to its author.
- **A suppression marker is a dated claim about code and decays faster than the prose around it.** A harvest deleting doctrine rows corrects their wrappers first, as a manifest row of its own, never as collateral of a delete. A phantom guard spreads by citation: grep the guard's path, not its name, and count live docs apart from frozen ones, which record what was believed and are not edited.
- **Retiring a guardrail row edits three artifacts.** The row is cited by id from feature docs and frozen plans, wrapped in a marker naming where its code lives, and restated in the out-of-scope register at the foot of the same file: keep the id and mark the row retired with a pointer, correct the wrapper, and replace the register bullet with a pointer, or the file contradicts itself twenty lines apart.
- **Size decision records to the repository's own decision doctrine before writing them.** One record per argued subject feels natural and yields micro-records where the rule is one record per architectural subject; the test is whether a reader would ever need one without the others. The safe shape is one record per plane with a section per settled subject, each keeping its Decision, Why and Declined lines, and a separate record only for a genuinely different subject. Link with section anchors where a bare pointer loses precision, and check anchors by hand: the link checker strips them.
- **A per-file lint hook reads intermediate states.** It queues rows from mid-edit files; run the linter over the whole edited set before calling the apply done, and leave its stale rows for the facilitator rather than draining them.