…
1. **A feature is a spec section with a short id** on its heading: `## Waiting lists {#waitlist}`. Its design, implementation and test sections reuse the same id (`{#waitlist}`), and you update them together, in the same change.
-2. **Each behaviour the feature promises is one spec line ending with a code:** `- A full event puts new sign-ups on the waiting list. ^waitlist-1`. The code is the feature's short name and a number. Write `^waitlist-` and let d2 give the number when it can; never renumber a code or reuse a retired one. A spec line says what is, never who decided it or when: names, dates and item numbers go in the topic's changelog, the project log and the item; a "how: [[Design#…]]" pointer is fine.
+2. **Each behaviour the feature promises is one spec line ending with a code:** `- A full event puts new sign-ups on the waiting list. ^waitlist-1`. The code is the feature's short name and a number. Write `^waitlist-` and let d2 give the number when it can; never renumber a code or reuse a retired one. A spec line says what is, never who decided it or when: names, dates and item numbers go in the project's history (`POST /api/v2/history`) and the item; a "how: [[Design#…]]" pointer is fine.
3. **The other levels point to it:** a design, implementation or test line that deals with that behaviour ends with `[[Spec#^waitlist-1]]` (two links if it covers two). The link shows as a small `WAITLIST-1` chip and jumps to the spec line.
4. **Code can't hold links:** a test's name starts with the code (`WAITLIST-1 a full event…`), and code that realises a behaviour carries a `// covers: waitlist-1` comment.
…
- **Rate limits:** a token may make about 120 requests, 30 writes, 20 messages and 10 new pipeline items a minute. Over that you get `429 E_RATE` with `Retry-After`: wait that long. If you keep hitting it, you're probably in a loop: stop and post `stuck`.
-## AI log: record what you changed
+## History: record what you changed
-Append an entry to `AiLog:PROJECT` for every piece of work in which you changed anything in the project, before telling the user it's done. It's how the people on the project see, check and undo what you did. The user reads it at `/topics?category=AiLog`.
+Add a history entry for every piece of work in which you changed anything in the project, before telling the user it's done. It's how the people on the project see, check and undo what you did. They read it in the project's history views (`Log:PROJECT`, `Log:Ai`), or with `GET /api/v2/history?type=ai`.
- **One entry per piece of work**, not per request you made: "added the Trail class and 12 trails" is one entry.
-- **Append-only:** send each entry with `POST /api/v2/topics/AiLog:PROJECT/append`, as for the project log; a `PUT` of the log is refused.
-- **Format:**
+- **Write it with `POST /api/v2/history`:** `{type: "ai", text, item?, feature?, about?: {anchors}}`; `text` is markdown, any number of lines. d2 sets the time and the author from your token. The history is append-only: a correction is a new entry with `replaces: <id>`. The old `AiLog:` topics are no longer written.
+- **Text format:**
~~~markdown
-### 14:30 · Added trails
+Added trails
- **Asked by:** Razie
…
- **Marketing blurbs**, where the project keeps them: a blurb for each feature whose design is approved or ships.
+- **No broadcasts, and no notices about items** (Razie, 2026-10-02, standing): never message a whole role (`to: role:coder`, `dispatcher`, `monitor`, `designer` or `all`) unless your person asks in so many words — *send to coders*, *send to dispatchers*, *send to monitors*. The other roles feed off the pipeline themselves (the monitor talks to the dispatchers, they to the coders), so an item you file, release or change reaches them there; a message about it, or about work still to come, only confuses them. For designers this replaces the shared *notices go on the board* line. Replies to a named agent that wrote to you, and messages to your person, are fine.
+
+- **A ticket a coder can work from alone** (Razie, 2026-10-02, standing): the coder's context goes on the work, not on chasing it. Every coder item you file has:
+ - **Quotes, not big links.** The few lines it needs, quoted; link a section only when most of it is needed.
+ - **A reading budget:** the ticket plus what it links stays under about 15K characters; a bigger one is split.
+ - **Code pointers:** the nearest existing component to copy and the files it will touch, from the code base's own topics (`Proto1Code`).
+ - **Decided for you:** every small call a coder would otherwise guess (names, storage, paging, error codes, defaults), settled in the ticket.
+ - **Black-box tests first:** the feature's tests written in the tests topic before the item is released; the ticket names them, and its *Done when* is that they pass, unchanged.
+ - **Never rewrite a taken or done item's document:** add a note; its document is the coder's record.
+
**Under a dispatcher** (^agents-31): designers run unattended, several at once, as coders do. Then:
…
### Your project: four topics to keep up to date
-Every project has four working topics, made when the project is created. They're how the people on the project, and the next AI session, know what's going on. Keep them current as you work; it's part of the job, not an extra.
+Every project has three working topics and its history, made when the project is created. They're how the people on the project, and the next AI session, know what's going on. Keep them current as you work; it's part of the job, not an extra.
- [[AiSpec:PROJECT]]: **the project's specification.** What it's for, its requirements, its design, its open questions. It says what's true now.
-- [[Log:PROJECT]]: **the project log.** The people's changes and decisions, dated, with who made the call.
+- **The project history** (`GET /api/v2/history`, shown as [[Log:PROJECT]]): the people's decisions and changes, dated, with who made the call, and every change you make (`type: ai`).
- [[ToDo:PROJECT]]: **the to-do list.** What's agreed but not done yet.
-- [[AiLog:PROJECT]]: **the AI log.** Every change you make in the project, dated, with what you touched and why.
How to use them:
-1. **Start of work:** read all four. Follow the spec; don't reopen decisions that are in the log; offer the next to-do when the user asks what's next.
-2. **When something is agreed:** update `AiSpec:PROJECT` in the same conversation, and add an entry to `Log:PROJECT` saying who decided it (see "Project log" below).
+1. **Start of work:** read the three topics and the recent history (`GET /api/v2/history?type=decision`). Follow the spec; don't reopen decisions that are in the log; offer the next to-do when the user asks what's next.
+2. **When something is agreed:** update `AiSpec:PROJECT` in the same conversation, and add a `decision` entry to the history saying who decided it (see "Project history" below).
3. **When something is deferred or promised for later:** add it to `ToDo:PROJECT`. **When it's done:** tick it.
-4. **Whenever you change anything** (a topic, a class, objects, a style, a setting): add an entry to `AiLog:PROJECT` before telling the user it's done (see "AI log" below).
-5. The logs are **append-only**: add to them with `POST /api/v2/topics/<log>/append` (see below); never edit or delete an old entry; a correction is a new entry.
+4. **Whenever you change anything** (a topic, a class, objects, a style, a setting): add an `ai` entry to the history before telling the user it's done (see "History" above).
+5. The history is **append-only**: add to it with `POST /api/v2/history`; nothing is edited or deleted; a correction is a new entry with `replaces`.
A bigger feature can have its own spec (`AiSpec:<name>` or `OpenSpec:<name>`); link it from `AiSpec:PROJECT`.
-**Releases.** A project has a version (`version` in `Settings:PROJECT`). When an admin releases it (the members page, or `POST /api/v2/project/release` with `{"version": "1.2.0"}` using an admin-level token), the project log and the AI log roll over: the old ones become `Log:PROJECT-v1.2.0` and `AiLog:PROJECT-v1.2.0`, and new ones start, linking back. Keep writing to `Log:PROJECT` and `AiLog:PROJECT`; read the `-v…` ones only for history.
+**Releases.** A project has a version (`version` in `Settings:PROJECT`). When an admin releases it (the members page, or `POST /api/v2/project/release` with `{"version": "1.2.0"}` using an admin-level token), the history keeps every entry across releases; read an older stretch with `since` and `until`.
### Specifications: AiSpec or OpenSpec topics {lookup}
…
- A `PUT` replaces the whole topic: read it, change it, write it back.
-### Project log: record the people's decisions and changes
+### Project history: record the people's decisions and changes
-Record in `Log:PROJECT` every decision the people on the project make, and every change they make or ask for to the spec, the design or the settings, as it's agreed, so they have a dated history of what was decided, by whom, and why. The user reads it at `/topics?category=Log`. (The demo also keeps this prototype's own log, `Log:diesel2`.)
+Record every decision the people on the project make, and every change they make or ask for to the spec, the design or the settings, as it's agreed, so they have a dated history of what was decided, by whom, and why. They read it as [[Log:PROJECT]], or with `GET /api/v2/history?type=decision`.
-- **With the spec:** a decision usually changes an `AiSpec:` topic too; update both, and link the spec in `Where`.
+- **With the spec:** a decision usually changes an `AiSpec:` topic too; update both, and name its sections in `about.anchors`.
- **When:** as soon as the user and you settle a design decision (a choice between options, a rule, a name, a trade-off, reversing an earlier call), in the same conversation, before moving on. Record decisions, not every change or the conversation itself.
-- **Read first:** at the start of work on a project, read its log, so you don't reopen settled decisions. If the user wants to revisit one, that's fine; the new call is a new entry.
-- **Append-only, through `append`:** logs take additions only. Send each entry with `POST /api/v2/topics/Log:PROJECT/append` (the entry's text as the body, or `{"text": …, "date": "YYYY-MM-DD"}`): d2 puts it under that day's `## YYYY-MM-DD` heading, making the heading if needed, and publishes it at once (never a draft). A `PUT` or a draft of a log is refused (`E_APPEND_ONLY`); only the project's admins edit old entries. A reversal is a new entry that says which one it replaces ("Supersedes 2026-09-23 · …").
+- **Read first:** at the start of work on a project, read its recent decisions, so you don't reopen settled ones. If the user wants to revisit one, that's fine; the new call is a new entry.
+- **Write it with `POST /api/v2/history`:** `{type: "decision", person: "<who decided>", text, about: {layer: "spec" | "design" | "build", anchors: [...]}, feature?, item?}` (`type: "change"` for a change that isn't a decision). d2 sets the time and author; nothing is edited or deleted; a reversal is a new entry with `replaces: <id>`. `Log:PROJECT` is no longer written as a topic.
- **Who decided:** the user's call, or your proposal that the user accepted ("Claude proposed; Razie approved"). Your own suggestions that weren't accepted don't go in.
-- **Format:** one entry per decision, a `###` heading and its lines (d2 adds the day's `## YYYY-MM-DD` above it):
+- **Text format:** a title line and its lines:
~~~markdown
-### Int is Java's long
+Int is Java's long
- **Decided by:** Razie
…
- **What you keep:** the code and your code base's own topics, named after the code base (on d2spec, proto1): `Proto1Impl` (per feature, how you built it against the design and notes for the final implementation, **no code references**), `Proto1Code` (files, classes, the box, deploys, releases), `Proto1Routes` (routes as built) and `Proto1Test` (code tests and test files) — **nothing else.** You don't edit Spec, UiSpec, Design, Testing or Routes; on d2spec those now hold only the designer's part. A topic marked **MOVED** says at its top who updates it and with what only: Prototype1 and Implementation take no writes; Routes keeps only planned routes, Testing only design tests, Design only mechanisms. (Razie, designer: built with d2 chat, 2026-10-02): what the build settled for them goes back to the designer as a list (next bullet), and the designer makes those edits when it next checks the pipeline. **Why:** coders spent a third of a run on draft writes and `409`s against each other (dispatcher report P-655).
+- **Facts every coder needs** (d2spec, collected from coders' reports 2026-10-02): the host is `https://<project>.aiheroapps.com` (d2spec: `https://d2spec.aiheroapps.com`) — `D2_URL` may be unset, so set it yourself. Bodies: `POST /api/v2/pipeline/<id>/take {as, name}`, `POST /api/v2/pipeline/<id>/note {text}` (not `note`), `POST /api/v2/agents/status {agent, state, every, context, …}`. **Your `every` is a promise:** use at least `1800` and post a status before any step that may run longer, or d2 counts you quiet and your item can be released. `npm run test:full` prints **nothing until the end** and has no per-test timeout: past ~2 minutes with no output, look with `ps` for a hung test before blaming your code; if the whole suite crawls, the temp dir may be full of old `d2*` test dirs (clear ones older than 20 minutes with no test server running). The item's own `touches` are authoritative over any copy in a prompt. A new topic's `PUT` answers `201`; project names starting with `d2` are reserved.
- **Code tests** are yours; the design tests you run with every build and never change. A behaviour's test name starts with its code (`WAITLIST-1 …`); code that realises a behaviour carries `// covers: waitlist-1`.
- **Deploys and releases** follow the project's permissions (`ops.deploy`); check the tests' fail count before deploying and the deployed version after.
…
Several coders build at once, so each has its own branch and folds it in itself: you know both sides of your own merge, nobody else does.
-- **Your branch is `razwip-<your agent name>`, cut from `main`.** Commit to it as you go, each commit naming its item like any other (above). The **code**, though, carries feature ids and behaviour codes (`// covers: waitlist-1`) and never a `P-n`: an item is why a line was written, and the line outlives it.
+- **Your branch is `razwip-<your agent name>`, cut from `razwip`** (not `main`: the work since the last release is on `razwip`, 2026-10-03). Commit to it as you go, each commit naming its item like any other (above). The **code**, though, carries feature ids and behaviour codes (`// covers: waitlist-1`) and never a `P-n`: an item is why a line was written, and the line outlives it.
- **When the build and its tests are done, post `merging`** — it reads and is leased exactly like `working`, so keep posting inside your `every` — then pull `razwip`, merge your branch into **`razwip`, never `main`**, resolve your own conflicts, run the tests your work touches, push your branch and `razwip`, and post `done` with `timing.merge` (the minutes the merge took) beside the other steps.
-- **Who pushes `main` is what `startedBy` says** (Razie, designer-2 chat, 2026-10-01). A coder merges only into `razwip`; **merging `razwip` into `main` and pushing it is a release**, and a release belongs to whoever is at the top of your chain. **Started by a dispatcher** — you post `startedBy` — your dispatcher releases: when it's happy with `razwip` it merges `razwip` into `main` and pushes it once, at its checkpoint, behind the full suite and the release deploy. **Started by nobody** (a chat or a terminal session your person opened, no `startedBy`) you are the top of your own chain and release yourself: merge `razwip` into `main`, push it, release deploy, box suite, as a dispatcher would. It is the same word that decides where your questions go (*Waiting on your person*, above), and for the same reason: what you don't release, you don't answer for.
+- **Coders never merge into `main`** (Razie, 2026-10-03; every coder, chat or dispatched): build, run your component tests, make sure what you did works, then merge your ticket branch into **`razwip`**, push it, and stop — no full suite, no `main`, no deploy, no box suite (the full suite runs only when Razie asks for a deploy). **Merging `razwip` into `main` is the release:** it happens only when Razie says *run the full test and deploy*, done by a dispatcher (or the chat he tells), behind the full suite, the release deploy and the box suite. Who started you still decides where your questions go (*Waiting on your person*, above). **Why:** releases after every batch cost a full checkpoint (~13 min) each — ten releases for ~18 items on 2026-10-02/03.
+- **Told to pick up items from the pipeline, take five or more** (Razie, 2026-10-03): as a chat coder, take at least five pickable items in pick order whose `touches` don't collide (fewer only when fewer are pickable), take them all first, and build them as one run: build, your component tests, merge into `razwip`, push. One start-up and one wrap-up for five items, not five.
- **Whoever gets there second sees the first one's work.** That is the point of merging late: the `touches` lanes keep the overlap small and your merge is the safety net under them.
- **A merge you haven't resolved in 20 minutes is `stuck`,** naming both sides (your commit and what it landed on). Don't guess at another agent's change and don't force it: say so and stop.
…
- **Items that collide, or may collide, go in the same batch when the budget allows** (Razie, 2026-09-30). Two lanes on one file end in a merge; one agent on both ends in one edit. So when the flags say two items touch the same files, that is a reason to give them to one coder, not a reason to hold one back — and it is why the take reports a collision instead of refusing it. When the budget can't hold both, start the one that lands first and tell the second agent what it will be rebasing onto.
- **How many coders at once is yours to decide** (Razie, designer: built with d2 chat, 2026-10-02): group the pickable items into batches so that **no two batches touch the same files** (what collides goes in one batch, as above), then start one coder per batch worth running, up to the project's agent cap; a start word with a number (*with 3 coders*) is a ceiling, not a target. The grouping is the round's plan. Fill the slots from `GET /api/v2/pipeline?role=coder&pickable=1`, in Next up order, **one item (or one batch) per agent**, posting `working` as you start each, and **decide each row from its flags** — `collides`, `mayCollide`, `size`, `important` — and how many slots are idle. `?free=1` is the easy answer to *what can I start right now* and a filter, never a fence: the rows it leaves out are still takeable, and the table below is what decides. Each coder pushes its own branch and merges it itself, so you don't merge for them.
-- **Take before you start a coder:** once you commit an item (or a batch) to a coder, take each item for it straight away, under the coder's name (`POST /api/v2/pipeline/<id>/take {as: "coder", name: "<the coder's name>"}`), before the coder starts. A taken item is locked to its holder, so nobody — a designer re-sizing or splitting it included — reshapes it while it's being built. **Why:** on 2026-10-02 a designer split P-626 and made it medium minutes after dispatcher-2 had committed a coder to it as the large item; neither side got a signal.
+- **One report per round** (Razie, 2026-10-03): post **one** board message per round — the plan (taken and skipped, with reasons), the results, the release — under the 4000 cap; more only when something blocks. **Why:** six messages cost a dispatcher 9 minutes of a 59-minute run (d2spec P-616).
+- **Take before you start a coder:** once you commit an item (or a batch) to a coder, take each item for it straight away, under the coder's name (`POST /api/v2/pipeline/<id>/take {as: "coder", name: "<the coder's name>"}`), before the coder starts — and before you write its prompt: an `E_TAKEN` costs one call, a prompt four minutes (d2spec P-616). A taken item is locked to its holder, so nobody — a designer re-sizing or splitting it included — reshapes it while it's being built. **Why:** on 2026-10-02 a designer split P-626 and made it medium minutes after dispatcher-2 had committed a coder to it as the large item; neither side got a signal.
- **No `touches`, no take** (Razie, designer: built with d2 chat, 2026-10-02); [[Spec#^pipe-70]]): a coder item whose `touches` is empty goes back to the designer untaken — `PATCH {for: "designer"}` with a note *touches missing* — and you go on down Next up. `touches: nothing` is a declaration (it changes no file) and is taken like any other.
- **`touches` is a top-level item field** (`PATCH /api/v2/pipeline/<id> {touches}`; `GET` returns it at the top), not under `links` — `collides` and `mayCollide` are the ones under `links`. **Why:** dispatcher-2 read `links.touches`, found `{}` on every item and nearly reported a filled backfill as missing (2026-10-02).
…
- **Say what you did about stops, every time:** every round report and every status text carries `stop received: none`, `obeyed (<message id>)` or `overridden because …` — `none` included, so silence is never ambiguous. Acknowledge a stop with `replyTo` the moment you read it.
- **When an agent ends** (Razie, 2026-09-29): as soon as its run is over, however it ended (done, stuck, stopped, out of room), post **`gone`** for it: `POST /api/v2/agents/status {agent: "<its name>", role: "<its role>", state: "gone", startedBy: "<your name>", text: "ended: <how>"}`, so the board never shows an agent that no longer exists as working or idle.
-- **Checkpoint after each agent run** (Razie, 2026-09-29): post `working` with `text: "checkpoint"`, then **check that `main` hasn't moved under you** — git takes any push d2 can't see, so compare `origin/main` with your last release and post a `warning` naming the commits if anything but your own release is on it, which means a coder of yours released when only you may (the monitor reads the board for the same thing) — **and read that same log for commits with no `P-n` on them**, which is a `warning` too and never a refusal, since the commit is already made and the fix is the next one — then merge razwip into main, push, release deploy, run the box suite, and publish the drafts your agent touched (only those no other role has edited since, per the draft's history; list the others in the checkpoint notice for Razie, so another role's half-done edits aren't published). Then a board notice. If a step fails, stop, post `stuck` with why, and don't start the next agent. Razie can also say *checkpoint* on the board at any time.
+- **No release after every batch** (Razie, 2026-10-03, until the full test is faster — d2spec P-726): between releases your coders' work collects on `razwip`; check each coder's merge with the component tests it touched and start the next batch. Run the checkpoint below **only when Razie says *run the full test and deploy***.
+- **The checkpoint** (Razie, 2026-09-29; now on his word, above): post `working` with `text: "checkpoint"`, then **check that `main` hasn't moved under you** — git takes any push d2 can't see, so compare `origin/main` with your last release and post a `warning` naming the commits if anything but your own release is on it, which means a coder of yours released when only you may (the monitor reads the board for the same thing) — **and read that same log for commits with no `P-n` on them**, which is a `warning` too and never a refusal, since the commit is already made and the fix is the next one — then merge razwip into main, push, release deploy, run the box suite, and publish the drafts your agent touched (only those no other role has edited since, per the draft's history; list the others in the checkpoint notice for Razie, so another role's half-done edits aren't published). Then a board notice. If a step fails, stop, post `stuck` with why, and don't start the next agent. Razie can also say *checkpoint* on the board at any time.
- **Collect the run's decisions into one item for the designer.** Your coders decide the small things themselves and write each one down as a `Decided:` line (see the coder's section). At the checkpoint, gather them from the run's commits and closing notes and file one item for `designer agent`, **`Decided in v<x>`** — the version you just released — with each line under the P-n it came from. It is not an approval and nothing waits on it: the code is built, released and already in the designer's world. It is the designer reading, in one place, what a dozen small choices have quietly made true, and deciding which ones belong in the design and which ones want undoing while they are still cheap. File it even when there is one line; the value is that the item always exists, so nobody has to remember to look. Nothing to collect, no item.
- **Your agents' start prompt** is the *Start prompt* below; fill in its blanks for each agent. Always pass `as` and `name` on its pipeline calls and `startedBy` on its statuses. **Copy it from here every time, and never carry a previous agent's prompt forward:** its push line is the coder section's, word for word, and it drifted once because `coder-N.prompt` was copied prompt to prompt — ten coders in a row were told to push `main`, and one did.
…
### Start prompt
-> You are **<agent name>**, a coder agent started by the dispatcher for Razie on d2spec. Read `GET /api/v2/skills?role=coder` and follow it. Work folder: `<folder>`. Your item(s): <P-n links>. Load keys with `source <env file>`; never print one — check it loaded with `${D2_TOKEN:+set}` (prints `set` or nothing) or `${#D2_TOKEN}` (its length), never `echo $D2_TOKEN`, `env`, `set` or `printenv`. Build any pipeline note or board message in a file and send it with `--data-binary @file`: backticks inside a double-quoted shell string are run by bash, `python3 -c "…"` included. On every pipeline call pass `as: "coder agent"` and `name: "<agent name>"`; on every status pass `startedBy: "<dispatcher name>"` and your `context`. Work on `razwip-<agent name>`, cut from `main`. Take → build → the tests you touch → drafts → add your design calls to <design-call item> → post `merging`, merge your branch into **`razwip`, never `main`**, resolve your own conflicts, re-run those tests, push your branch and `razwip` → board notice → post `done` with `changed` and `timing.merge`. Don't publish drafts and don't deploy either: your dispatcher releases — `main`, the deploy and the box suite — once, at its checkpoint.
+> You are **<agent name>**, a coder agent started by the dispatcher for Razie on d2spec. Read `GET /api/v2/skills?role=coder` and follow it. Work folder: `<folder>`. Your item(s): <P-n links>. Load keys with `source <env file>`; never print one — check it loaded with `${D2_TOKEN:+set}` (prints `set` or nothing) or `${#D2_TOKEN}` (its length), never `echo $D2_TOKEN`, `env`, `set` or `printenv`. Build any pipeline note or board message in a file and send it with `--data-binary @file`: backticks inside a double-quoted shell string are run by bash, `python3 -c "…"` included. On every pipeline call pass `as: "coder agent"` and `name: "<agent name>"`; on every status pass `startedBy: "<dispatcher name>"` and your `context`. Work on `razwip-<agent name>`, cut from `razwip`. Take → build → the tests you touch → drafts → add your design calls to <design-call item> → post `merging`, merge your branch into **`razwip`, never `main`**, resolve your own conflicts, re-run those tests, push your branch and `razwip` → board notice → post `done` with `changed` and `timing.merge`. Don't publish drafts and don't deploy either: your dispatcher releases — `main`, the deploy and the box suite — once, at its checkpoint.
### Designer start prompt
…
> You are **designer-\<n\>**, a designer agent started by \<dispatcher\> for Razie on d2spec. Read `GET /api/v2/skills?role=designer` and `Skill:process` and follow them. Your item(s): \<P-n links\>. Load keys with `source <env file>`; never print one — check it loaded with `${D2_BUILDER:+set}` (prints `set` or nothing) or `${#D2_BUILDER}` (its length), never `echo $D2_BUILDER`, `env`, `set` or `printenv`. Build any pipeline note or board message in a file and send it with `--data-binary @file`: backticks inside a double-quoted shell string are run by bash, `python3 -c "…"` included. On every pipeline call pass `as: "designer agent"` and `name: "designer-<n>"`; on every status pass `startedBy: "<dispatcher name>"` and your `context`. Read your Next up as `?role=designer&pickable=1&pickFor=designer-<n>`, so what follows up your own work comes first. **Take each item you work**, and leave a review batch held until its last section is accepted, so the answers reach you. Ask nothing in your output: proposals go in a review batch, small things in the digest, and what truly blocks goes to the monitor's flag. Write drafts with `?section=` and `If-Match`; on `409 E_DRAFT_CHANGED` re-read, merge and retry, never force. Don't publish a draft and don't deploy: the dispatcher checkpoints.
-## Changelog
-
-- 2026-10-02: fail an item on its own content with a why; two fails send it back FAILED, never re-dispatched (Razie; d2spec P-674).
-- 2026-10-02: read only the linked sections, a status before and after; dead after half an hour, declared, recovered and handed on by the dispatcher — flexible to 60 min for now, cases noted on d2spec P-673 (Razie, designer: process improvements 2 chat; d2spec P-670).
-- 2026-10-02: `touches` is top-level; a status per phase (the monitor; Razie, designer: process improvements chat, reviewed with the monitor).
-- 2026-10-02: the batch budget is eight again, how many is the dispatcher's call (Razie, designer-10, process improvements chat).
-- 2026-10-02: no touches, no take (back to the designer; `nothing` is a declaration); the final integration and mongo tests on cloud5 (Razie, designer: built with d2 chat, 2026-10-02).
-- 2026-10-02: coders keep only the code and *As built* and send the designer an As built list with suggested doc updates; the dispatcher decides how many coders, batching so no two batches share files (Razie, designer: built with d2 chat, 2026-10-02).
-- 2026-10-01: coders: an item's *Read only these docs* line bounds what spec they read (Razie, designer-3 chat; d2spec P-574).
-- 2026-10-01: **hand over only what's unfinished** (Razie approved, designer-2 chat; P-528): an agent that finishes cleanly posts `done` with a short summary and writes **no** handover item — the items, their notes, the commits and the checkpoint already carry what a successor needs — and one that stops part-way still writes one, listing only what is left. P-504 was the case: a handover describing work that had shipped sat `new` at the head of the coder queue until Razie dropped it. A dispatcher is the exception, because its handover is held between rounds rather than written at the end. And a handover picked up with nothing left in it is closed with one line rather than worked, which is the one time *don't mark a handover done* doesn't hold.
-- 2026-10-01: **every commit carries its item** (Razie's order 2026-09-30 via the monitor, confirmed in the designer-2 chat; P-521): a commit message names its `P-n`, **merge commits included**, and designer, skill and seed commits as much as a coder's build — 208 of 224 commits on `main` since 2026-09-28 already did, and the 16 without were mostly the skill and seed ones this line is for. Several items: name them all; no item at all: file one first. It is said in the shared part, where every role reads it, and the coder's *A branch of your own* points at it instead of repeating it. The *code* never carrying a `P-n` is the other half of that sentence and is a different rule, left where it was. The checkpoint reads the release's log once for both of its warnings: `main` moved, and a commit with no item on it.
-- 2026-10-01: **who pushes `main`: the release belongs to the top of the coder's chain** (Razie, designer-2 chat, P-520): a coder **started by a dispatcher** pushes its branch and `razwip` and never `main` — its dispatcher merges and pushes `main` once, at its checkpoint — and a coder **nobody started** (a chat, a terminal session) releases itself, because it is the top of its own chain. `startedBy` decides it, the same word that decides who a question goes to (P-507). The rule is in the coder's *A branch of your own*, the *Start prompt*'s push line is that line word for word, and the dispatcher copies the prompt from the skill every time: the drift came from carrying `coder-N.prompt` forward, which told coder-56 to coder-65 to push `main` and one of them did. Since d2 can't refuse a git push, the checkpoint compares `origin/main` with the last release and warns on anything else there.
-- 2026-10-01: **a dispatcher with nothing running posts `idle` and says why; its last word is `done`** (Razie, designer-2 chat, P-514): one showed `working` with nothing to do — the only pickable coder item was reserved for Razie's own chat and the rest were paused — and then exited, its last word still `working`. So `working` is now **only** while an agent of yours actually runs; `idle` carries **one line of why**, and `paused` is not the only way work is withheld, so the reason comes from the open list minus the pickable one (an item waiting on one that isn't `done`, a handover reserved for a chat, a paused queue); and a dispatcher signs off `done`, or `handing-over`. `gone` is not its sign-off — that is what it posts for each agent *it* ends and what d2 sets for one it can't see (`quiet` first, P-510).
-- 2026-10-01: **mint your own token before anything else** (P-489, [[Spec#^agtok-3]]): the token you are given is your **role**'s; `POST /api/v2/tokens/agent {name}` answers one that is yours alone, for one run. Use that token and the `agent` name it gives you — a name is never given to two of your person's agents on a project, so it may not be the one you asked for. Nothing renews it: `401 E_AUTH "expired: mint a new one"` means mint again and carry on. Your secrets travel with the mint; your rate limits are the role token's, shared with your siblings. A dispatcher passes the **role** token to each agent it starts, because an agent token can't mint.
-- 2026-10-01: **the batch budget is five small items, and only [[Spec#^pipe-40]] says so** (Razie, designer-2 chat): it was eight here and in Design 25 while the Spec and `Pipe.batch()` ran five, so the skill told a dispatcher one thing and the code suggested another. Five: a coder reached 70–75% of its context after one large item and five more, [[Spec#^pipe-40]] and the code already ran five, and a smaller batch checkpoints more often. The number is now stated in one place and pointed at from both of the two here, and the sentences that used to repeat it — *eight small items are each a file and a test*, *up to seven more smalls* — no longer name a number at all.
-
-- 2026-09-30: **alone items and waiting on itself** (Razie, designer-2 chat; ^pipe-62, ^pipe-63; P-479, P-490): an `alone` item (a refactor, titled *Refactor:*) runs by itself on the coder side — finish what you hold, take nothing new while it is first or running, and d2 refuses those takes (`E_ALONE_NEXT`, `E_ALONE_BUSY`, `E_ALONE_RUNNING`); the dispatcher gives it one coder, alone. A held handover waits on itself (`waitingOn: "self"`): muted in the list, not stuck, picked up by id by the next session.
-
-- 2026-09-30: **dispatchers for designers** (Razie, designer chat, ^agents-31, P-441): a dispatcher may serve the designer role (`for: ["designer"]`, or `for: ["coder", "designer"]` on one dispatcher, since one dispatcher per role per person still holds) and run `designer-1..n` unattended. A designer **takes what it works**, and a review batch stays held by the designer that wrote it until every section is accepted, so the person's answers reach the agent that knows why; gone or handing over releases it to the role, and the next designer takes the batch up, whose sections carry their own context. **Follow-ups go home first:** `GET /api/v2/pipeline?pickable=1&pickFor=<agent>` puts the items that follow up that agent's own work — `links.follows` or `parent` naming an item it holds or last held, and work on a feature whose last item was its — ahead of everything but a released item and the handover. No new field: an item already names its last taker. `pickFor` is a **re-ordering and never a filter**, so a call that names no agent gets exactly the list it always got, and nothing is fenced off from anyone. Headless designers ask nothing in their output: proposals go in a review batch, small things in the digest, what truly blocks goes to the monitor's flag.
-- 2026-09-30: **important only means pick me** (Razie, designer-2 chat, P-471): ★ is a place in the pick order and never a size, so an important item is picked first and then batches like any other item of its size — a small ★ goes with up to seven more smalls, and only a `large` item runs alone. The policy table's **big** is `large` alone: a small ★ colliding with a small item in flight is `small + small` (take), not `small + big`, and what drains behind a waiting item drains behind a large one. **Small ★ merge requests batch together at the head of a run**, in branch order. It replaces *a large item, and an important one, go alone*, whose cost was a whole run — start, full suite, deploy, checkpoint — for a one-file designer merge.
-- 2026-09-30: **a summary on every item you file** (P-447): `summary` on `POST /api/v2/pipeline` and `PATCH /api/v2/pipeline/<id>` — one sentence, at most 200 characters, `""` to clear — shown under the title on the item's page, with the document's first sentence as the fallback when there is none.
-- 2026-09-30: **the dispatcher's policy table** (Razie, designer-2 chat, P-416): what fills a slot is decided from the row's flags, not fenced off by them — `no flags` and `small + small` take, `small + big` skips the round, `big + any` stays separate, `mayCollide` counts half, and with `one slot` everything is taken because one coder cannot collide with itself. Pick order is a preference, not a barrier: the walk goes past a skipped item and takes what doesn't collide with the one waiting, so a waiting important item drains instead of growing. A small item skipped twice is taken anyway; a big one waits as long as it collides. Each round's plan — taken and skipped, each with the line that decided it — is one board notice. The table lives in this skill, so tuning it is an edit.
-- 2026-09-30: **coders decide the small things, and say so** (P-432): a detail the design never mentioned is the coder's call, written down as a `Decided:` line — what, and why — in the commit and in the note that closes the item; anything that changes what a feature promises is still a design call. The dispatcher gathers them at each checkpoint into one `Decided in v<x>` item for the designer, which nothing waits on: it is the designer seeing in one place what a run's small choices have made true.
-- 2026-09-30: **the dispatcher batches to a budget** (P-427): up to eight small items, or a medium with its related smalls; large and important alone. It replaces *up to five in all*, in the shared part and in the dispatcher's section, which disagreed with what the dispatchers were already doing. Items that collide or may collide with each other go in the same batch when the budget allows, so one coder does both instead of two lanes merging.
-- 2026-09-30: **only files collide, not topics** (P-428): a `touches` entry that names a topic rather than a path is worth declaring and is never a collision, since d2 merges a topic's drafts itself and git does not merge for you. The open row gained `collideFiles`: which of its own files are the ones at stake.
-- 2026-09-30: **a collision is a fact, not a refusal** (Razie, designer-2 chat, P-415): `take` always succeeds and its answer carries `collides: [ids]` beside `mayCollide: [ids]`; `E_COLLIDES` and `force` are gone, from the route and from MCP's `pipeline_take`. A collision is *possible*, not absolute, and between small modules usually cheap to merge, so the server states the facts and the dispatcher or a person decides. `?free=1` is unchanged, and is now plainly a filter rather than a fence.
-- 2026-09-30: **the handover is held, not closed** (^pipe-58, P-426): take your role's handover at start, before you read it, hold it while you work, and put it down (`/putdown`) when you post `done` or `waiting` — never mark it done. A handover nobody holds sits `new` at the head of its role's Next up and reads like available work: a dispatcher's live handover was offered to a coder as its first pickable item and its suggested batch, for a whole session, and an earlier dispatcher lost a night to the same thing. Put down only what you hold — another agent's item answers `E_NOT_YOURS`, by name even when both agents share one token.
-- 2026-09-30: **the safe idiom for a key, given outright next to the prohibition** (P-422, and P-414 which asked the same): `${VAR:+set}` or `${#VAR}`, never `echo $VAR`, `env`, `set` or `printenv`, with the reason the probe *did my env file load?* is the moment it goes wrong. In the shared part (any agent loads credentials), in the dispatcher's *Keys* bullet, and in the *Start prompt*, so it no longer depends on a dispatcher remembering to paste it. A coder that had *never print a key* in its prompt echoed two token values while probing exactly that, and they had to be rotated. Same change: build a note or message in a file and send it with `--data-binary @file` — backticks in a double-quoted shell string are run by bash, which lost two notes' identifiers and, in one case, launched an agent early.
-- 2026-10-01: **a question goes up the chain that started you** (Razie, designer-2 chat, P-507): ask your `startedBy`; only an agent nobody started waits on its person, and d2 lights their waiting-on-you flag for it. For a chat `idle` (a turn that ended) is not `waiting` (a question it needs answered), and a question ends with a `**** PLEASE ANSWER:` line.
-- 2026-10-01: **say where to look** (rule 8): a *Look at:* line of links right after an item's title when you finish it for a person (Razie, designer-2 chat).
-- 2026-10-01: **coders merge into `razwip`, never `main`** (Razie, designer-2 chat): a coder merges its branch into `razwip` and pushes its branch and `razwip`; only the release merges `razwip` into `main` — the dispatcher at its checkpoint when it's happy with `razwip`, or a coder nobody started, releasing itself. The coder section and the start prompt both said "merge into your local `main`", which is where the drift to pushing `main` began.
-- 2026-10-01: **messages are read by `since`, never by count; a dispatcher reads them again right before starting an agent and says `stop received: …` in every report** (Razie, designer-2 chat, from the monitor's issue 6abe8814/6abe8a1c): a stop pushed below a `&limit=3` window by the dispatcher's own coder's notices went unseen for 71 minutes.
-- 2026-09-30: **an item that says nothing about what it touches collides with nothing** (Razie's ruling, designer-2 chat, P-405, built the same day). A take whose overlap can't be known succeeds and carries `mayCollide: [ids]` — the items in progress of its role it might overlap — and the coders resolve any real overlap when they merge. The coder reads them before merging; the dispatcher passes them to the agent it starts and keeps filling its lanes.
-- 2026-09-30: **coders in parallel** (Razie, designer chat, P-385, built P-390): a coder works on `razwip-<agent>` cut from main and folds it in itself — post `merging` (coloured and leased like `working`), merge, resolve your own conflicts, re-run the tests you touch, push `razwip`, `done` with `timing.merge`; unresolved at 20 minutes is `stuck` with both sides named. A coder told to take a free item uses `?free=1` and never forces. The dispatcher is told how many coders to run (*start dispatcher with N coders*, default 1), fills that many lanes from `?free=1` one item per agent, and holds its checkpoint while any coder is `merging` or `stuck`.
-- 2026-09-29: a spec line says what is, never who decided it or when; names, dates and item numbers go in the changelog, the project log and the item (Razie, designer chat, P-374).
-- 2026-09-29: take under your own agent name (`name`), never your person's; handing over or going gone releases your items to your role, still in progress, first in its pickable list (Razie, designer chat, ^pipe-53, P-306).
-- 2026-09-29: a project's own process is `Skill:process`, read after the base skills; no copies of base skills (P-302).
-- 2026-09-29: any role writes an answer as a Report topic (askedBy, an *Asked:* line first, `ephemeral` for a one-off) (P-296).
-- 2026-09-29: waiting says what for: `waitingFor` prompt (with `text`, `chat`) or item (Razie, designer chat, ^agents-29).
-- 2026-09-29: skills follow the permissions: publishing a skill goes through `docs.skill` (default *person*), no hard rule of its own (Razie, designer chat, ^agents-2, P-270).
-- 2026-09-29: a **dispatcher** section (P-220, with Razie): starting, keys from the vault, its states (idle, working, working "checkpoint", handing-over, always with context), the loop, the three session commands, `gone` for each agent when its run ends, a checkpoint after every agent run (merge, push, deploy, test, publish its drafts), the agents' start prompt here instead of on the CDN, one running design-call item per session, handover from 70%, coder and tester only.
-- 2026-09-28: review with a comment: resolve an `acceptedIf` and finish with a note (it closes), or return it with questions; `reviewAgain` always comes back to review; ask up the chain with `/ask` (P-231).
-- 2026-09-28: a message's id is the store's (24 hex digits), not `M-n` (P-205 rework, cluster-friendly).
-- 2026-09-28: board messages have ids (`M-n`); answer with `replyTo` instead of a new message; answered pairs and messages over 3 days old go to the log daily (P-205).
-- 2026-09-28: dispatchers: `role: dispatcher` with `for: [roles]`, one per role (`E_EXISTS`), `startedBy` on the agents they start, shown `dispatching` while those agents work (P-194).
-- 2026-09-28: `done` stays done: the heartbeat never marks a done agent gone (P-192).
-- 2026-09-28: agent work goes to `<role> agent`: d2 re-points a bare specialist role (hint `N_PIPE_AGENT_ROLE`) unless askedBy (P-186).
-- 2026-09-28: *person* is your person themself only (E_SCOPE even with askedBy); *asks* passes at once with askedBy, else an approval; send askedBy whenever your person told you to (P-176).
-- 2026-09-28: split out of `Skill:diesel2` (P-146): the pipeline as a role, the board, approvals, handovers, the contract between the roles, and a section per role (designer, coder, tester).
-- 2026-09-29: a dispatcher posts `startedBy` from its start prompt's *started by <name>* (P-342, the monitor couldn't find its dispatcher).
-- 2026-09-29: read your work and your board lean (P-345): `forRole`, `forName`, `status=open` and `fields` on the pipeline list (no `doc` in it), `since` (a message id too) and `limit` on the board.
-- 2026-10-02: new project structure, implementation move ([[d2spec.NewProjectStructure]]): coders write only their code base's topics (Proto1Impl, Proto1Code, Proto1Routes, Proto1Test on d2spec); each moved topic says at its top who updates it with what (Razie, designer: new project structure chat).
-