ytdb-slate 0.5.0 → 0.6.0

package/README.md

@@ -1,5 +1,7 @@
 # ytdb-slate
 
+[![CI status](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml/badge.svg?branch=main)](https://github.com/JetBrains/ytdb-slate/actions/workflows/tier-1.yml)
+
 Slate is a thread-weaving orchestration extension for the [pi coding agent](https://pi.dev).
 
 The orchestrator (your main pi session) dispatches **bounded actions** to persistent **worker threads**. Each completed action is compressed by an LLM into an **episode** — a durable, structured record (intent, actions, findings, artifacts, open issues, handoff notes) that the orchestrator composes into further dispatches instead of re-reading raw transcripts. On top of that, Slate injects a mandatory workflow doctrine: research before design, design review, adversarial review, and track review — with optional umbrella **draft-PR publishing** for tracks. An opt-in **model-failover** map adds high availability: when a model API fails, the orchestrator, worker threads, and episode compression each retry once on a configured equal-quality alternative. A second opt-in, **action-level model routing**, gives each dispatched action a model and an effort level chosen to be up to the task and no more, so cost is bounded per action instead of per session.
@@ -53,10 +55,20 @@ Slate can ride through model API outages. The opt-in `modelFailover` map in `.pi
 
 ## Action-level model routing
 
-Slate can pick the model and the effort level per dispatched action rather than running every action on whatever model the orchestrator happens to be on. `router.models` in `.pi/slate.json` (trusted projects only) is a closed list of `provider/id` specs; a dispatch then runs on the `model` and `effort` arguments of that action, else on the thread's own base model and a level DERIVED for the model that actually runs — the lowest level that model has a capability measurement at, never a fixed default. The list is empty by default, and empty means off: no list is enforced, nothing is seeded, and model selection is exactly what it was before the router existed. Only models Slate ships a benchmark profile for can be routed to; entries pi cannot serve, or has no profile for, are dropped with a warning naming them.
+Slate can pick the model and the effort level per dispatched action rather than running every action on whatever model the orchestrator happens to be on. `router.models` in `.pi/slate.json` (trusted projects only) is a closed list of `provider/id` specs. Each action uses its `model` and `effort` arguments when present. Otherwise, it uses the thread's base model and a level DERIVED for the model it routes to. That level is the lowest one with a capability measurement, never a fixed default. The list is empty by default. An empty list disables candidate-list enforcement, base seeding, effort derivation, and the router's window, billing, and substitution paths. Per-action `model` and `effort` arguments stay active on both router states. Slate always checks an explicit effort against pi's vocabulary, and against the ladder of the model it routes to whenever it has that model's profile data. An action that omits `model` plans for the thread's pre-router pin, and a thread with no pin gives it no plan target. An action that omits `effort` resolves no level. In both cases the worker session returns to what it opened on. [`docs/model-routing.md`](docs/model-routing.md) holds the full contract, including the known cases where the model or level that runs differs. Only models Slate ships a benchmark profile for can be routed to; entries pi cannot serve, or has no profile for, are dropped with a warning naming them.
 
 What the code enforces is deliberately narrower than what the routing data advises. The dispatch guards refuse an unlisted model, a level off the target model's ladder and a level the provider rejects outright; they warn about — and mark — an unmeasured level, refusing it only when `router.allowUnmeasuredEffort` is `false`; and the context-window guard substitutes a wider listed model instead of ever blocking an action. The obligations that come from the profile data itself — keeping review and gate actions on measured levels, and honoring a REFUSE such as `anthropic/claude-fable-5`'s for zero-data-retention work — are stated in the doctrine for the orchestrator to honor; they are **not** code-enforced guards. Full semantics: the `router.*` rows in [Configuration](#configuration) and the shipped [`docs/model-routing.md`](docs/model-routing.md) — if they disagree, that document wins.
 
+## Optional writing guidance
+
+Set `writing.check` to `true` to add writing guidance and human-only telemetry. In orchestrator mode, Slate adds a doctrine rule that states the convention. It also adds a status value such as `writing 1/4`. This value means that one of four measured prose turns had a fail-level finding. Each worker gets a shorter preamble reminder about sentence length, semicolons, and contractions.
+
+The option has prompt cost. Each orchestrator system prompt contains the doctrine rule. You pay for this text on every turn. Each worker session also gets a gated preamble addition. Both additions are absent when the option is off. The worker preamble then stays byte-identical to its pre-feature form.
+
+> **No conformance claim:** This is a dictionary-free proxy. It embeds no controlled vocabulary and claims no ASD-STE100 conformance.
+
+The shipped CLI checks plain files, JSONL records, and unified diffs. See [`docs/writing-guidance.md`](docs/writing-guidance.md) for its rules, limits, output, and command examples.
+
 ## Install
 
 Install into a project (pinned, project-scoped — recorded in `.pi/settings.json`):
@@ -82,11 +94,12 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `orchestratorPromptDocs` | string[] | `[]` | Project markdown files (paths relative to the project root) whose **contents** are appended to the orchestrator system prompt. |
 | `workerPromptDocs` | string[] | `[]` | Project markdown files whose **contents** are appended to every worker-thread system prompt. |
 | `workflow.draftPRs` | boolean | `false` | Enable umbrella draft-PR publishing for tracks. |
+| `writing.check` | boolean | `false` | Add the writing doctrine rule, per-turn status, and worker guidance. An absent option is silently off. A malformed `writing` value, or a non-boolean `check` value, warns and defaults to off. Unknown `writing` keys warn and are ignored. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
 | `doctrineExtraPath` | string | — | Project markdown whose **content** is appended to the orchestrator doctrine (project-specific workflow additions). |
 | `reviewPerspectivesPath` | string | — | Project review charters, each declaring its own finding-ID prefix. The doctrine references this **path**; the orchestrator reads the file alongside the shipped review rules. |
 | `modelFailover` | object (string → string) | — (empty, failover off) | Map of `provider/id` → equal-quality alternative model; on a model API failure the affected site retries once on the mapped model (worker/orchestrator sites only after pi's own retries are exhausted; episode compression has no pi retry loop). Read once at session start — see [`docs/model-failover.md`](docs/model-failover.md). |
 | `preserveGlobalModelDefault` | boolean | `true` | Put pi's global model defaults (`defaultProvider`, `defaultModel`, `defaultThinkingLevel`) back after a Slate-initiated model switch — orchestrator failover and handoff adoption — so the switch stays session-scoped. `false` turns that restore off at both sites (the switches themselves are unaffected), leaving each one persisted in pi's global settings. Best-effort: Slate reverts only a value its own switch produced, and can stand down or give up — limits in [`docs/model-failover.md`](docs/model-failover.md). |
-| `router.models` | string[] | `[]` (empty — routing off) | Closed list of models (`provider/id`) an action may be routed to. **Empty or absent means the router is OFF and dispatch behaves exactly as it did before the router existed** — no model list is enforced and no thread gets a seeded base model. A listed model becomes routable only where four things intersect: your list, a benchmark profile Slate ships for that model, pi's model registry, and credentials pi actually has configured; anything that fails one of those is dropped with a warning naming it (if every entry drops, routing turns off with one summary warning). Read once at session start and resolved once per session — see [`docs/model-routing.md`](docs/model-routing.md). |
+| `router.models` | string[] | `[]` (empty — routing off) | Closed list of models (`provider/id`) an action may use. Empty or absent means the router is OFF. Slate enforces no candidate list, seeds no thread base, derives no effort level, and runs no router-only window, billing, or substitution path. Per-action `model` and `effort` arguments stay active on both router states. Slate still checks explicit effort against pi's vocabulary and the routed model's ladder when it has that model's profile data. An action that omits `model` plans for the thread's pre-router pin, and a thread with no pin gives it no plan target. An action that omits `effort` resolves no level. In both cases the worker session returns to what it opened on. The known cases where the model or level that runs differs are listed in [`docs/model-routing.md`](docs/model-routing.md). A listed model becomes routable only if Slate has its benchmark profile, pi registers it, and credentials are configured. Slate drops other entries with a warning. If all entries drop, routing turns off with one summary warning. Slate reads and resolves the list once per session. See [`docs/model-routing.md`](docs/model-routing.md). |
 | `router.allowUnmeasuredEffort` | boolean | `true` | What happens when an explicitly requested effort level is on the target model's ladder but has no capability measurement in Slate's profiles: `true` dispatches it with a ⚠ notice and marks the episode `(unmeasured level)`; `false` refuses the dispatch. Either way a level that is off the model's ladder, or one the provider rejects outright, is refused, and a level Slate DERIVES for an action is always a measured one. |
 
 Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point them at markdown files that actually exist in **your** project):
@@ -99,6 +112,7 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
   "workflow": { "draftPRs": true },
+  "writing": { "check": true },
   "doctrineExtraPath": "docs/agents/workflow-additions.md",
   "reviewPerspectivesPath": "docs/agents/review-perspectives.md",
   "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" },
@@ -143,6 +157,7 @@ In orchestrator mode, Slate appends a short **doctrine** (a block of numbered ru
 - `docs/design-principles.md` — Slate's own design rationale
 - `docs/model-failover.md` — the opt-in `modelFailover` map (**reference documentation** — unlike the entries above it is not workflow doctrine and is not cited by the doctrine)
 - `docs/context-budget.md` — the orchestrator `contextBudget`: defaults, per-model overrides, the window clamp, and the pricing rationale (also **reference documentation**, not cited by the doctrine)
+- `docs/writing-guidance.md` — the optional writing convention, `writing.check` behavior, status line, and checker CLI
 - `docs/model-routing.md` — action-level model routing: the two `router` keys, how a model becomes routable, how an omitted effort level resolves, the dispatch guards, and the warnings a first routed session emits. Unlike the two entries above it **is** cited by the doctrine, by absolute path, but only while the routing rule renders — it is the extra embedded path that appears with the rule, the fourth normally and the fifth when `workflow.draftPRs` is also on, which the size arithmetic in `docs/context-budget.md` accounts for. The routable model list itself is never read from this file: the rule renders it live from the session's own resolution, because that set depends on your registry and credentials.
 
 Project-specific additions layer on top — they extend, not replace, the shipped doctrine — via two distinct mechanisms:

package/docs/context-budget.md

@@ -129,69 +129,93 @@ you pay its input tokens every turn.
 
 **Its size depends on where the package is installed.** That is not
 obvious, and it catches anyone who measures: the doctrine cites the
-shipped docs by ABSOLUTE path, so three to five full filesystem
-paths are embedded in the block — three at minimum
+shipped docs by ABSOLUTE path, so three to six full filesystem paths
+are embedded in the block — three at minimum
 (`track-workflow.md`, `review-rules.md`, `design-principles.md`),
 plus `pr-publishing.md` when `workflow.draftPRs` is on, plus
-`model-routing.md` when the routing rule renders. Every additional
-character in the installed `docs/` directory therefore costs 3–5
+`model-routing.md` when the routing rule renders, plus
+`writing-guidance.md` when `writing.check` is on. Every additional
+character in the installed `docs/` directory therefore costs 3–6
 characters of doctrine.
 
-So the figures below are **portable characters**, defined exactly as
-Slate's own automated size check defines them: the block with each
-occurrence of the installed `docs/` DIRECTORY removed, keeping the
-filename. That makes them install-invariant by construction —
-verified by measuring at a 12-character docs path and at this repo's
-58-character one, which give identical portable counts — and it
-makes the arithmetic one multiplication:
+The figures below are **portable characters**, defined exactly as
+Slate's own automated `doctrine-budget` check defines them: the
+block with each occurrence of the installed `docs/` DIRECTORY
+removed, keeping the filename. That makes them install-invariant by
+construction and makes the arithmetic one multiplication:
 
 > rendered characters = portable + (embedded paths × length of your
 > installed `docs/` directory)
 
-Every row below states its full basis, because router state, model
-count and `draftPRs` each move the number:
+`doctrine-budget` in `verification/resolver-checks.mjs` is the
+definition of record for this convention and its enforced bounds.
+This table is a measured snapshot, not a second authority. It uses
+the same real shipped-profile fixture as that check; the six-model
+rows use the six configured models in this repository's documented
+example. Every row states its full basis, because router state,
+model count, `draftPRs`, and `writing.check` each move the number:
 
-| router | models | `draftPRs` | paths | portable | lines | rendered at a 58-char docs dir |
+| router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
-| off | — | off | 3 | 1,929 | 38 | 2,103 |
-| off | — | on | 4 | 1,948 | 38 | 2,180 |
-| on | 6 configured | off | 4 | 3,870 | 58 | 4,102 |
-| on | 6 configured | on | 5 | 3,889 | 58 | 4,179 |
-| on | all 9 shipped | off | 4 | 4,448 | 61 | 4,680 |
-| on | all 9 shipped | on | 5 | 4,467 | 61 | 4,757 |
+| off | — | off | off | 3 | 1,929 | 38 |
+| off | — | off | on | 4 | 2,683 | 53 |
+| off | — | on | off | 4 | 1,948 | 38 |
+| off | — | on | on | 5 | 2,702 | 53 |
+| on | 6 configured | off | off | 4 | 3,879 | 58 |
+| on | 6 configured | off | on | 5 | 4,633 | 73 |
+| on | 6 configured | on | off | 5 | 3,898 | 58 |
+| on | 6 configured | on | on | 6 | 4,652 | 73 |
+| on | all 9 shipped | off | off | 4 | 4,434 | 61 |
+| on | all 9 shipped | off | on | 5 | 5,188 | 76 |
+| on | all 9 shipped | on | off | 5 | 4,453 | 61 |
+| on | all 9 shipped | on | on | 6 | 5,207 | 76 |
 
 An untrusted project reads the first row whatever its `slate.json`
-says: no project config is loaded, so neither optional rule renders.
-Line counts do not vary with the install path. Enabling `draftPRs`
-costs 19 portable characters plus one more embedded path.
+says: no project config is loaded, so no optional rule renders. Line
+counts do not vary with the install path. Enabling `draftPRs` costs
+19 portable characters plus one embedded path. Enabling
+`writing.check` costs 754 portable characters, adds 15 lines to the
+whole doctrine, and adds one embedded path; considered alone, the
+writing rule is 754 portable characters / 16 lines because its
+leading newline becomes the separator when appended.
 
 Two parts of the block grow with configuration rather than with the
 path:
 
 - The routing rule is a live table with ONE ROW PER ROUTABLE MODEL,
   so what renders is the models you CONFIGURE — not the nine Slate
-  ships profiles for. It is 1,941 portable characters / 20 lines for
-  six configured models and 2,519 / 23 for all nine. A model ROW
-  costs 154–186 characters; the legend adds a one-off clause per
-  marker it has to explain, so listing the first cheap-tier model
-  costs ~50 characters more than its row (two new clauses). That is
-  why stepping from six to nine averages 193 per model where the
-  first six average 171.
+  ships profiles for. In this snapshot it is 1,950 portable
+  characters and adds 20 doctrine lines for six configured models;
+  for all nine it is 2,505 characters and adds 23 lines. The six
+  model rows are 146–181 characters; all nine are 146–183. The
+  legend adds a one-off clause per marker it has to explain, so
+  growth is not only the sum of new rows.
 - The worker-extension rule grows per whitelisted extension and per
   tool that extension contributes, so it has no fixed size; one
   extension contributing two tools measured 373 portable characters
   / 7 lines.
 
-Against a 256,000-token budget none of this is material — as a rough
-estimate, at 4 characters per token (no tokenizer was run, and the
-table is denser than prose, so treat it as a floor) the whole block
-is ≈480–525 tokens with both optional rules off and ≈970–1,025 with
-six models routed, each range spanning portable to as-rendered-here.
-That is under half a percent of the default budget, though it is
-re-sent on every request rather than paid once. It is listed here
-because it is context Slate itself puts in front of the model on
-every turn, and because it is the number to check before assuming
-the budget's headroom is all conversation.
+Against a 256,000-token budget none of this is material. At four
+characters per token as a rough estimate (no tokenizer was run, and
+the routing table is denser than prose), the portable block ranges
+from about 482 tokens at the baseline to about 1,302 with all nine
+models, `draftPRs`, and writing enabled. That is close to half a
+percent of the default budget at the largest measured configuration,
+though it is re-sent on every request rather than paid once. It is
+listed here because it is context Slate itself puts in front of the
+model on every turn, and because it is the number to check before
+assuming the budget's headroom is all conversation.
+
+### Worker writing preamble
+
+The doctrine table does not include the worker preamble. It belongs
+to each worker session's system prompt, not to the orchestrator's
+per-turn doctrine. The feature-off preamble is 226 bytes. With
+`writing.check` on it is 384 bytes, a 158-byte increase (the
+157-byte guidance plus its separating space). These are UTF-8 byte
+counts; the current text is ASCII, so its character counts happen to
+be identical. This separate figure states the worker-session cost
+without presenting it as orchestrator doctrine.
 
 ## Worker threads: the routing window guard
 

package/docs/design-principles.md

@@ -194,7 +194,9 @@ context budget, also decide per dispatch whether a worker thread still
 fits the model it is routed to, in which case the action moves to the
 widest listed model rather than being blocked.
 
-The feature is OFF until `router.models` lists something, and it is
+Candidate routing is OFF until `router.models` lists something — the
+per-action `model` and `effort` arguments, and a fallback a failover
+is holding, stay active either way. The feature is
 built on a deliberate split that is worth holding onto when reasoning
 about the architecture: the code ENFORCES less than the routing data
 ADVISES. Dispatch guards refuse what is mechanically wrong — a model

package/docs/model-failover.md

@@ -89,11 +89,11 @@ Failover applies at three sites:
   model and the failed action is re-prompted once with a continuation
   nudge. The transcript is preserved; usage and cost accumulate across
   both attempts. The thread stays on the mapped model while its
-  session is live and returns to its configured model when the session
-  is reopened (e.g. after a pi restart). The `threads` listing marks a
-  switched live session as `model=A ⇒B (live)` — the marker means a
-  live failover switch happened (it is not a value comparison) and
-  disappears when the session is reopened.
+  session is live, including across later model-less actions, and the
+  `threads` listing marks it `live=<model> (failover)`. The hold, the
+  marker and the retry inside the failing dispatch are cases M1, M6
+  and M2 of [Known cases where the model or level
+  differs](model-routing.md#known-cases-where-the-model-or-level-differs).
 - **Episode compression.** The compression call is retried once with
   the mapped compressor model — only if it is distinct from the
   original, resolvable, and authed. If the retry also fails, the

package/docs/model-routing.md

@@ -6,14 +6,19 @@ list of models an action may run on; every dispatch then resolves to
 one model from that list and one effort level from that model's own
 ladder — chosen to be up to the task and no more, so the bill is
 bounded by the action rather than by the session's current model.
-The list is empty by default: with no entries the router is OFF, no
-model list is enforced, no thread gets a seeded base, and a
-dispatch that names no model resolves exactly as it did before the
-router existed — the thread's pre-router pin, else the host
-session's model. (The per-action `model` and `effort` arguments
-themselves are honoured on both router states; see the accepted
-limitations.) This document is reference documentation, not
-workflow doctrine.
+The list is empty by default. With no entries the router is OFF: no
+model list is enforced, no thread gets a seeded base, no effort level
+is derived, and the router's window, billing and substitution paths
+are inert. A dispatch that names no model then plans for the thread's
+pre-router pin, and for no model at all when the thread has none: a
+new worker opens on the host session's model, and a reused one stays
+on the model it opened on. The per-action `model` and `effort`
+arguments are honoured on both router states. What a dispatch plans
+is not always what it runs; the cases known to bite are collected
+under [Known cases where the model or level
+differs](#known-cases-where-the-model-or-level-differs).
+
+This document is reference documentation, not workflow doctrine.
 
 A model can only be routed to if Slate ships a benchmark profile for
 it. An entry with no profile is named in a warning and excluded —
@@ -26,36 +31,44 @@ from](#where-the-numbers-come-from-and-how-stale-they-can-be).
 
 ## What routing decides, per action
 
-Two levers, both per dispatch — on a new thread and on a
+Two route inputs are per dispatch — on a new thread and on a
 continuation alike:
 
 - **the model** — the `model` argument (`"provider/id"`), else the
-  thread's base model (router ON), else the thread's pre-router pin
-  or the host session's model (router OFF);
+  thread's base model (router ON), else the thread's pre-router pin,
+  else no plan target at all, in which case the session returns to
+  the model it opened on (router OFF; M1, M3, M7);
 - **the effort level** — the `effort` argument (one of pi's thinking
-  levels), else a level Slate resolves for the model that actually
-  runs (router ON) or the level the worker session opened on (router
+  levels), else a level Slate resolves for the model it routes to
+  (router ON) or the level the worker session opened on (router
   OFF). See [Effort levels](#effort-levels).
 
-Neither is sticky, and that is the guarantee to hold on to: an
-explicit `model` or `effort` governs its own action and no later
-one. An omitted `model` resolves to the thread's base. An omitted
-`effort` resolves differently on the two router states, and neither
-of them is "whatever the last action asked for":
+The arguments themselves do not become thread defaults. An explicit
+`effort` never governs a later action. An explicit `model` governs
+only its own action too, outside M1, M3, M6 and M7. An omitted `effort`
+is never "whatever the last action asked for":
 
 - **router on** — the thread's base effort, re-validated, or a level
-  derived for the model that runs (see [Effort
+  derived for the model it routes to (see [Effort
   levels](#effort-levels)). A thread based on `luna@medium` whose
   previous action ran at `max` runs the next one at `medium`.
-- **router off** — nothing is resolved, so the worker session is put
-  back to the level it opened on, which is pi's own settings default
+- **router off** — the worker session is put back to the level it
+  opened on, which is pi's own settings default
   (`defaultThinkingLevel`, else pi's built-in default). Slate passes
   that level explicitly at every open, so it is re-clamped against
   the session's current model rather than inherited from the session
   file.
 
-A thread's base model and base effort are separate state, visible in
-the `threads` listing, and are never set from an action's own route.
+The model axis carries live-session cases the effort axis does not,
+M1 and M3 among them, and they predate action-level routing. The
+effort axis shares only M7. All of them, with the code that
+implements each, are under [Known cases where the model or level
+differs](#known-cases-where-the-model-or-level-differs).
+
+A thread's base model and base effort are separate planning state,
+visible in the `threads` listing, and are never set from an action's
+own route. A live failover marker, when present, identifies the
+model that currently overrides that nominal base.
 
 Two things can come back instead of a normal episode:
 
@@ -68,6 +81,120 @@ Two things can come back instead of a normal episode:
   result — advisory: an evidence gap, a window substitution, a
   long-context billing cliff, a re-seeded base. The action ran.
 
+## Known cases where the model or level differs
+
+The model and the level an action runs on are not always the ones it
+asked for, or the ones its thread implies. The cases below are the
+ones known to bite, each with the code that implements it. **This
+list is not exhaustive.** `planRoute`, `decideModelSwitch` and
+`decideEffortSwitch` in `extension/route.ts`, applied by `applyRoute`
+in `extension/threads.ts`, are the authority: read them when you need
+certainty rather than a map. This section is the reference for these
+cases. Other sites may name or summarise them; if a summary disagrees,
+this section governs, with the source functions above the ultimate
+authority.
+
+Why the MODEL can differ:
+
+- **M1 — a live failover holds the thread.** After a successful
+  `modelFailover` the worker stays on its fallback, and a dispatch
+  that omits `model` keeps it: the revert to the session's opening
+  model stands down (BG16). The hold ends when the session is
+  disposed, and when a later non-`openOnly` route moves it — an
+  explicit `model` on either router state, or the thread's routed
+  base while the router is ON. An OFF pre-router pin is `openOnly`
+  and does not release it. A reopen ends it too, except in M6.
+  *Code:* the `failover-held` keep in `decideModelSwitch`
+  (`route.ts`); `applyRoute` clears the marker after a plan-driven
+  `setModel`, and `liveFailoverModel` reports it (`threads.ts`).
+- **M2 — a failover fires inside the dispatch.** When the attempt
+  fails with a model-API error, Slate switches the live session to
+  the mapped model and re-prompts once. One episode covers both
+  attempts, and its `ran:` line names the model the action ended on
+  rather than the planned one. *Code:* the `isFailoverCandidate`
+  block in `runDispatchInner` (`threads.ts`) and `planFailoverSwitch`,
+  guard 7 (`route.ts`).
+- **M3 — the revert was attempted and failed.** A dispatch that names
+  no model switches the session back to the model it opened on. When
+  that spec no longer resolves, or `setModel` throws, Slate warns and
+  leaves the session on the model the previous action left it on
+  (BG24). A PLAN-driven switch that fails is the opposite case: the
+  dispatch aborts, nothing runs and no episode is written. M7 is the
+  case where no revert is attempted at all. *Code:* `giveUp` inside
+  `applyRoute` (`threads.ts`).
+- **M4 — the window guard substitutes** (router ON). A model that
+  cannot hold the thread's context is replaced by the widest listed
+  candidate, and only when one is STRICTLY wider than the model it
+  would replace. When nothing listed is wider, the action runs on the
+  original model and a warning says pi will compact. It never blocks
+  the action, and `substitutedFrom` records a replacement. *Code:*
+  `strictlyWider` in `planRoute`'s guard 5 (`route.ts`).
+- **M5 — the thread's base was not routable** (router ON). A base
+  that is absent or has fallen off the list is re-seeded to a listed
+  candidate with a warning, so a model-less dispatch runs on the
+  seeded base and not on the value the record carried. *Code:* the
+  re-seed branch of `planRoute` with `defaultBase` (`route.ts`),
+  written back by `persistReseededBase` (`threads.ts`).
+- **M6 — a reopened session restores a model from its file** (CQ3).
+  Slate passes the reopening model explicitly whenever the dispatch
+  resolves one, and that overrides the session file. When the
+  dispatch resolves no model at all and the host session has none
+  either, pi restores the file's last model change instead, which can
+  be a fallback M1 was holding. The `live=` marker is cleared on every
+  reopen, so in this one shape the fallback outlives its marker.
+  *Code:* `opts.model ? resolveModel(ctx, opts.model) : ctx.model` in
+  `openWorkerSession` (`worker.ts`); the marker delete in
+  `openWorkerFor` and the CQ3 note on `liveFailoverModel`
+  (`threads.ts`).
+- **M7 — nothing was captured to return to.** When the worker session
+  reported no model as it opened, there is no revert target, and a
+  dispatch that names no model leaves the session where it is with no
+  switch attempted. The effort axis has the same keep when no opening
+  level was captured. *Code:* `NO_SESSION_BASELINE` and the
+  `no-baseline` keeps in `decideModelSwitch` and `decideEffortSwitch`,
+  fed by `captureSessionBaseline` (`route.ts`).
+
+Why the LEVEL can differ. There is no counterpart to M1 here: a
+dispatch that names no `effort` returns the session to the level it
+opened on. M7 and E6 are known cases in which it does not.
+
+- **E1 — pi clamps a level Slate cannot judge.** When the ladder for
+  the judged model is unreadable — no profile, a throwing lookup, a
+  non-array ladder — the guards stand down and the level goes to pi,
+  which clamps it to something the model offers. Slate reports
+  nothing, because it has no evidence to report. *Code:*
+  `checkEffortFor` and `guardEffort`'s `ladderKnown` (`route.ts`).
+- **E2 — M4 moved the model under an explicit level.** A level that
+  is not valid on the substituted model is DROPPED with a warning
+  rather than refusing the action — a context size must never
+  hard-block a dispatch — and the session's opening level applies.
+  *Code:* the `soft` branch of `guardEffort` (`route.ts`).
+- **E3 — a stored base level no longer holds.** A base effort is a
+  cached derivation over a table that ships with Slate. When today's
+  table no longer reads it as `ok`, it is silently re-derived for
+  that model: nobody asked for that level, so a stale cache is
+  Slate's to correct rather than news to report. *Code:* the stored
+  base-effort branch of `planRoute`, with `lowestMeasuredEffort`
+  (`route.ts`).
+- **E4 — the action's model is not the base model.** An explicit
+  `model`, or M4, drops the inherited base level and derives the new
+  model's own lowest measured level instead. A level derived for one
+  model is never carried onto another. *Code:* the effort resolution
+  in `planRoute`, keyed on `judgedModel` (`route.ts`).
+- **E5 — M2 re-clamps the level.** The failover route requests no
+  level, and pi re-clamps the session's current level for the
+  fallback model. *Code:* `session.setModel(mapped)` in the failover
+  block (`threads.ts`); `openWorkerSession` passes the settings
+  default explicitly at every open for the same reason (`worker.ts`).
+- **E6 — the level was judged for one model and another model runs.**
+  When M1, M3 or M7 leaves the session on a model other than the plan
+  target, the level the plan resolved is still applied, and pi clamps
+  it to that model's own ladder with nothing reported.
+  `effortJudgedFor` names the model the judgement was about, which is
+  then not the model that ran. *Code:* the effort switch in
+  `applyRoute`, which runs after a model `keep` (`threads.ts`), and
+  `decideEffortSwitch` (`route.ts`).
+
 ## Configuration
 
 `router` lives in `.pi/slate.json` and, like the rest of that file,
@@ -196,7 +323,8 @@ The vocabulary is pi's ladder and nothing else: `off`, `minimal`,
 actually offers is per model — the shipped table records a ladder
 per model id, not a family rule.
 
-**An omitted `effort` never resolves to a fixed default.** In order:
+**An omitted `effort` never resolves to a fixed default.** With the
+router ON, in order:
 
 1. the thread's stored base effort — but only when the action runs
    on the thread's base model, and only while that stored level
@@ -205,8 +333,8 @@ per model id, not a family rule.
    the ladder, or onto the provider's rejection list) is silently
    re-derived; nobody asked for it, so a stale cache is Slate's
    problem to correct rather than news to report;
-2. otherwise the **lowest measured level of the model that actually
-   runs** — the lowest level on its ladder that carries a traced
+2. otherwise the **lowest measured level of the model it routes to**
+   — the lowest level on that model's ladder that carries a traced
    capability measurement. A level derived for one model is never
    carried onto another, so an explicit `model`, or a window
    substitution, re-derives it;
@@ -214,14 +342,19 @@ per model id, not a family rule.
    the level the worker session opened on applies, which is pi's own
    settings default — never a level another action left behind.
 
+With the router OFF Slate resolves no level at all, so that same
+opening level applies to every action that omits `effort`.
+
 So a higher level is only ever reached by naming it: pass `effort`
 explicitly on the dispatch. A derived level is measured by
 construction and therefore cannot trip the effort guards; only an
 explicit one can.
 
-An explicit level is judged against the model the action will
-actually run on, and the difference between a warning and a refusal
-is:
+An explicit level is judged against the model the action routes to,
+which `effortJudgedFor` names. [Known cases where the model or level
+differs](#known-cases-where-the-model-or-level-differs) collects what
+can move either afterwards. The difference between a warning and a
+refusal is:
 
 - **evidence gap** (the level is on that model's ladder but no
   traced source reports a capability result there) — advisory. The
@@ -230,8 +363,8 @@ is:
   `router.allowUnmeasuredEffort: false` turns this one case into a
   hard refusal for the whole project;
 - **off the model's ladder** — refused, whenever the ladder is
-  known. pi would otherwise clamp the level silently and the
-  orchestrator would believe the action ran at a level the model
+  known, outside E2. pi would otherwise clamp the level silently and
+  the orchestrator would believe the action ran at a level the model
   never offered;
 - **rejected outright by the provider** — refused, always. Such a
   level is still on pi's ladder for the model (the table records the
@@ -300,26 +433,27 @@ model's ladder is unreadable.
   its decision to make), the same lines in the live progress output,
   and `details.ranModel` / `details.ranEffort` /
   `details.ranEffortUnmeasured` / `details.warnings` for a renderer.
-- **In the `threads` listing:** `base=<model>@<level>?` — what a
-  dispatch that omits `model` will run on. The trailing `?` marks
+- **In the `threads` listing:** `base=<model>@<level>?` — the nominal
+  plan target when a dispatch omits `model`. The trailing `?` marks
   the level, not the model, as provisional: it is a stored default,
-  re-checked on every dispatch. Then `last=<model>@<level>` — what the thread's
-  last action actually ran on, with `(unmeasured)` where that
-  applies — and `live=<model> (failover)` while a failover holds the
-  live session.
+  re-validated against the model's current capability data on every
+  dispatch and silently re-derived if it no longer holds. `last=` is
+  the model and level that the last action actually ran on, with
+  `(unmeasured)` where that applies. `live=<model> (failover)` means
+  a held fallback currently overrides the nominal base for the live
+  session.
 - **At the session level:** the resolution's own warnings, as UI
   notifications (console when no UI is attached).
 - **In the orchestrator's own system prompt, every turn:** the
   doctrine gains a routing rule — a table with one row per routable
   model, plus the rules for reading it. This is the surface you do
-  not see, and it is the router's standing cost: 1,941 characters /
-  20 lines for six configured models, 2,519 / 23 for all nine — a
-  model row costs 154–186 characters, plus a one-off legend clause
-  for each marker it introduces (listing the first cheap-tier model
-  costs ~50 characters beyond its row, which is why six→nine
-  averages 193 per model against the first six's 171). Configuring
-  the router roughly doubles Slate's always-loaded block (1,929
-  characters with routing off). Those are PORTABLE characters — the
+  not see, and it is the router's standing cost: 1,950 characters /
+  20 added doctrine lines for six configured models, 2,505 / 23 for
+  all nine. In the current snapshot a model row costs 146–183
+  characters, plus a one-off legend clause for each marker it
+  introduces. Configuring the router roughly doubles Slate's
+  always-loaded block (1,929 characters with routing and writing
+  off). Those are PORTABLE characters — the
   doctrine with each occurrence of the installed `docs/` directory
   removed, filenames kept — because the doctrine embeds absolute doc
   paths and its raw size therefore depends on where the package is
@@ -519,13 +653,16 @@ concern; a green suite says nothing about it.
   dispatch guard and anything else that consults the router agree.
   A key or provider added mid-session, and an edit to
   `slate.json`, both need a new pi session.
-- **Router OFF is not "no effort checking".** With an empty list
-  there is no model list, no window guard, no billing notice, no
-  seeded base and no substitution — but an explicit `effort` is
-  still judged against the shipped profile for the model that runs,
-  when pi's registry can serve that model. The `model` argument
-  itself is passed through byte-for-byte, so a malformed spec still
-  produces pi's own error.
+- **Router OFF disables candidate routing, not action arguments or
+  failover.** With an empty list there is no model list, window
+  guard, billing notice, seeded base or candidate substitution, and
+  Slate derives no effort level. A model-less plan targets the
+  thread's pre-router pin, else nothing, so the session returns to the
+  model it opened on outside M1, M3 and M7, and to the level it opened
+  on outside M7 and E6. An explicit `effort` is still judged against
+  the shipped profile for the plan target when pi's registry can serve
+  that model. The `model` argument itself is passed through
+  byte-for-byte, so a malformed spec still produces pi's own error.
 - **A mid-thread model switch costs the prompt cache.** A long
   thread runs overwhelmingly on cache reads; routing a small action
   to a cheaper model on a cold cache can cost more than staying on