ytdb-slate 0.8.0 → 0.10.0

package/README.md

@@ -4,7 +4,9 @@
 
 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.
+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. Slate also injects a mandatory workflow doctrine. Its design and review gates scale with the confirmed change class. Optional umbrella **draft-PR publishing** covers 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.
 
 ## Why Slate?
 
@@ -36,16 +38,29 @@ Full rationale: [`docs/design-principles.md`](docs/design-principles.md), shippe
 
 ## Feature development workflow
 
-In orchestrator mode, Slate injects a track-based development workflow as doctrine — it is not optional; project configuration can extend it (`doctrineExtraPath`) but never replace it. The flow:
+In orchestrator mode, Slate injects a mandatory track-based development workflow. Project configuration can extend it through `doctrineExtraPath`. Configuration cannot replace it.
+
+Slate uses four change classes. Evaluate these tests in order. The first match
+sets the class:
+
+1. **Risky:** The change touches concurrency, durability, recovery,
+   transactional semantics, security, or user data. This class also covers a
+   public API or behavioral change, or a silent failure mode.
+2. **Complex:** The shape is unclear, several parts interact, or a live design
+   alternative exists.
+3. **Trivial:** The change is an obvious fix with no behavioral change, and one
+   reviewer pass covers it.
+4. **Medium:** Otherwise.
+
+After classification, follow these workflow steps:
 
-1. **Research** — interactive exploration; a research log opens lazily when defined triggers fire (non-trivial decisions, surprises, risky invariants, session boundaries).
-2. **User design review** — the user approves the design direction before any machine review.
-3. **Adversarial review** — a fresh-context reviewer attacks the design pre-implementation; findings are triaged with the user.
-4. **Track split approval** — the user approves how the change splits into independently reviewable tracks.
-5. **Per-track loop** — implement → agent code review → fixes → mandatory user review → marker commit (an empty commit marking the track's boundary in history).
-6. **Delivery** — with draft-PR publishing enabled, the squash-merge is performed by the user; the agent never merges. With it disabled (the default), the change lands as a squashed commit that carries the workflow log's key content in its message.
+1. **Classification and research** — the orchestrator proposes the change class, and the user confirms it. A research log is required for medium changes and above.
+2. **Design gates** — medium changes need high-level design approval before implementation. Complex and risky changes add an adversarial review between two user approvals.
+3. **Track split** — the orchestrator owns the split. Size determines tracks and marker commits, not workflow gates.
+4. **Per-track loop** — each track gets implementation, fixes, and mandatory user review. Agent code review is skipped only when the whole change is trivial.
+5. **Delivery** — the user performs the squash merge when draft publishing is enabled. Otherwise, the squashed commit carries the workflow log's key content.
 
-The workflow scales with change size: multi-track changes get the full flow, single-track changes skip the split and the marker commits, and trivial changes shrink the pre-implementation reviews to consent plus a micro-review (skippable with explicit user consent) — the agent code review and the mandatory user review still apply at every tier. Umbrella draft-PR publishing activates only when `workflow.draftPRs` is `true`.
+Trivial changes have no high-level design gate. Every change keeps mandatory user review of its track diff. Umbrella draft-PR publishing activates only when `workflow.draftPRs` is `true`.
 
 This summary is orientation only; the shipped docs listed below are normative.
 
@@ -104,6 +119,7 @@ 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. |
+| `workflow.followUpIssues` | boolean | `false` | When true, the orchestrator asks which suggestions become follow-up issues in the project tracker. Suggestions are always reported whatever the value. |
 | `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). |
 | `writing.remind` | boolean | `false` | Send a hidden reminder after an eligible tool result. All gates must pass: orchestrator mode, project trust, `writing.check`, this option, no pause, cadence or handoff force, and one-per-round control. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
 | `writing.remindPercent` | number | `10` | Set cadence as a percentage of Slate's current effective context budget. The value must be finite and in `(0, 100]`. The interval has an 8,192-token floor and no cap. A handoff force bypasses this threshold. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
@@ -124,7 +140,7 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "maxConcurrent": 4,
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
-  "workflow": { "draftPRs": true },
+  "workflow": { "draftPRs": true, "followUpIssues": false },
   "writing": {
     "check": true,
     "remind": false,
@@ -170,7 +186,7 @@ Slate reads project configuration (`.pi/slate.json`) and injects project files (
 
 In orchestrator mode, Slate appends a short **doctrine** (a block of numbered rules) to the orchestrator's system prompt each turn. The doctrine does not embed the workflow docs — it cites them by **absolute path**, resolved inside the installed package (not your project), and the orchestrator reads them on demand. Those embedded paths are also why the block's character count depends on your install location; [`docs/context-budget.md`](docs/context-budget.md) has the measured sizes, with and without the optional rules, and the arithmetic for your own install:
 
-- `docs/track-workflow.md` — the track-based workflow (research → design review → adversarial review → track review)
+- `docs/track-workflow.md` — the class-scaled workflow for research, high-level design, adversarial review, and track review
 - `docs/pr-publishing.md` — umbrella draft-PR publishing (cited only when `workflow.draftPRs` is `true`)
 - `docs/review-rules.md` — review discipline and finding rules
 - `docs/design-principles.md` — Slate's own design rationale

package/docs/context-budget.md

@@ -142,13 +142,16 @@ schema. A tool description and a parameter description are therefore both
 always loaded.
 
 The current `thread` tool description is 1,386 UTF-8 bytes. Its serialized
-parameter schema is 1,791 bytes, measured as `JSON.stringify(parameters)`, and
-includes the 289-byte `type` parameter description. The description and schema
-are 3,177 bytes together before provider framing. The thread-type wording in
-the description and schema adds 142 bytes to the previous combined figure. The
-increase is roughly 36 tokens at four characters per token. The figure excludes
-the prompt snippet, prompt guidelines, tool name,
-provider framing, and any serialization outside the parameter schema.
+parameter schema is 2,005 bytes, measured as `JSON.stringify(parameters)`.
+The schema includes the 289-byte `type` parameter description and the
+`freshContext` argument.
+
+The description and schema total 3,391 bytes before provider framing. The
+`freshContext` schema entry adds 214 bytes to the previous combined figure.
+The increase is roughly 54 tokens at four characters per token.
+
+The figure excludes the prompt snippet, prompt guidelines, tool name,
+provider framing, and serialization outside the parameter schema.
 
 The always-loaded doctrine has a separate measurement after the compaction
 policy.
@@ -174,14 +177,14 @@ 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 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, plus
-`writing-guidance.md` when `writing.check` is on. Every additional
-character in the installed `docs/` directory therefore costs 3–6
-characters of doctrine.
+shipped docs by ABSOLUTE path, so four to seven full filesystem paths
+are embedded in the block — four at minimum
+(`thread-cache-cost.md`, `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, plus `writing-guidance.md` when `writing.check` is on.
+Every additional character in the installed `docs/` directory therefore
+costs 4–7 characters of doctrine.
 
 The figures below are **portable characters**, defined exactly as
 Slate's own automated `doctrine-budget` check defines them: the
@@ -204,18 +207,18 @@ must be named instead of presented as the same measurement:
 
 | router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
-| off | — | off | off | 3 | 1,929 | 38 |
-| off | — | off | on | 4 | 2,999 | 60 |
-| off | — | on | off | 4 | 1,948 | 38 |
-| off | — | on | on | 5 | 3,018 | 60 |
-| on | `.pi/slate.json` six | off | off | 4 | 3,879 | 58 |
-| on | `.pi/slate.json` six | off | on | 5 | 4,949 | 80 |
-| on | `.pi/slate.json` six | on | off | 5 | 3,898 | 58 |
-| on | `.pi/slate.json` six | on | on | 6 | 4,968 | 80 |
-| on | all 9 shipped | off | off | 4 | 4,434 | 61 |
-| on | all 9 shipped | off | on | 5 | 5,504 | 83 |
-| on | all 9 shipped | on | off | 5 | 4,453 | 61 |
-| on | all 9 shipped | on | on | 6 | 5,523 | 83 |
+| off | — | off | off | 4 | 2,701 | 46 |
+| off | — | off | on | 5 | 3,771 | 68 |
+| off | — | on | off | 5 | 2,720 | 46 |
+| off | — | on | on | 6 | 3,790 | 68 |
+| on | `.pi/slate.json` six | off | off | 5 | 4,731 | 67 |
+| on | `.pi/slate.json` six | off | on | 6 | 5,801 | 89 |
+| on | `.pi/slate.json` six | on | off | 6 | 4,750 | 67 |
+| on | `.pi/slate.json` six | on | on | 7 | 5,820 | 89 |
+| on | all 9 shipped | off | off | 5 | 5,286 | 70 |
+| on | all 9 shipped | off | on | 6 | 6,356 | 92 |
+| on | all 9 shipped | on | off | 6 | 5,305 | 70 |
+| on | all 9 shipped | on | on | 7 | 6,375 | 92 |
 
 An untrusted project reads the first row whatever its `slate.json`
 says: no project config is loaded, so no optional rule renders. Line
@@ -231,9 +234,9 @@ 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. 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
+  ships profiles for. In this snapshot it is 2,030 portable
+  characters and adds 21 doctrine lines for six configured models;
+  for all nine it is 2,585 characters and adds 24 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.
@@ -247,17 +250,19 @@ worker extensions and support verification decisions:
 
 | basis | models | worker extensions | paths | portable | lines | rough tokens |
 | --- | ---: | --- | ---: | ---: | ---: | ---: |
-| current `.pi/slate.json` dogfood config | 6 | real 2 units / 4 tools | 6 | 5,884 | 90 | ≈1,471 |
-| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 6 | 6,870 | 93 | ≈1,718 |
+| current `.pi/slate.json` dogfood config | 6 | pinned-package 2 units / 4 tools | 7 | 6,736 | 99 | ≈1,684 |
+| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 7 | 7,722 | 102 | ≈1,931 |
+| follow-up-issues maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 7 | 7,800 | 103 | ≈1,950 |
 
 The dogfood row uses `workflow.draftPRs: true`, `writing.check: true`, and the
 six models in `.pi/slate.json`. Its extension basis is
 `pi-smart-fetch@0.3.12` plus `pi-web-search@1.3.1`. Those packages resolve to two
 units and four tools. Their worker-extension rule is 916 portable characters /
-11 lines. Raw size remains symbolic: `portable + 6 × length(installed docs
+11 lines. Raw size remains symbolic: `portable + 7 × length(installed docs
 directory)`. No maintainer checkout path belongs in this shipped document.
 
 The stable maximal row uses all nine shipped profiles, draft PRs, and writing.
+The follow-up-issues row uses the same basis with `workflow.followUpIssues: true`.
 Its direct post-resolution worker fixture has two units and four tools. Unit
 labels are 128 characters. Tool names are 64 characters. Descriptions are 140
 characters.
@@ -267,24 +272,67 @@ independent of installed extension labels, descriptions, versions and other
 prose. The worker rule measures 1,347 characters against its 1,600-character
 verification budget.
 
-`doctrine-budget` caps that representative maximal doctrine at 7,200 portable
-characters. The measured 6,870 leaves 330 characters, or 4.6 percent of the
-7,200-character bound. A positive control adds one capped tool
-and three copies of the largest measured model row. It measures 7,634 portable
-characters and exceeds the bound by 434. These figures are verification budgets,
-never runtime limits. Arbitrary user extension rosters can exceed them.
-
-The exact values are maintenance tripwires. A deliberate doctrine wording,
-requirement roster, renderer cap, or fixture change requires a fresh render
-through `doctrine-budget`. Update its exact expectations and every published
-figure in the same commit. Keep the positive control steps unchanged unless the
-fixture design itself changes.
-
-Against a 256,000-token context budget, these blocks remain small. At four
-characters per token as a rough estimate, the shipped-rule table ranges from
-about 482 tokens to about 1,381 tokens. The current dogfood basis is about 1,471
-tokens. The representative maximum is about 1,718 tokens, or 0.67 percent of the
-default budget.
+The reserve policy is: every doctrine upper bound must exceed its current
+measurement by at least five percent, with a required character-bound raise
+rounded up to the next hundred characters. Existing bounds stay in place when
+they already satisfy the policy. Line bounds use the same five-percent rule and
+the next whole line.
+
+Two guards have different jobs. An exact pinned literal is the sensitive guard.
+It fails for every size change in its rendered fixture, including one character.
+The maximal fixtures cover draft pull requests enabled, draft pull requests
+disabled, and follow-up issues enabled. Each budget term also has one enforced
+bound. The bound is a coarse ceiling that stops unbounded growth over time. A
+bound close to a fixture adds friction but no detection, because its exact
+literal already detects the change. Real reserve therefore weakens nothing.
+
+A doctrine change updates the exact literal and every published measurement. A
+maintainer revisits a bound only when the reserve policy requires it. The check
+applies the five-percent rule to every upper bound, so this decision is auditable.
+
+| budget term | current | enforced bound | current reserve |
+| --- | ---: | ---: | ---: |
+| routing rule characters | 2,585 | 4,000 | 1,415 |
+| routing rule lines | 25 | 34 | 9 |
+| routing fixed prose | 1,110 | 1,500 | 390 |
+| largest model row | 183 | 300 | 117 |
+| router-on doctrine | 5,286 | 6,500 | 1,214 |
+| writing-only doctrine | 3,771 | 5,600 | 1,829 |
+| writing plus router | 6,356 | 6,700 | 344 |
+| writing plus extensions | 4,026 | 6,000 | 1,974 |
+| writing plus router and extensions | 6,611 | 7,000 | 389 |
+| maximal doctrine, draft PRs enabled | 7,722 | 8,200 | 478 |
+| maximal doctrine, draft PRs disabled | 7,703 | 8,200 | 497 |
+| maximal doctrine, follow-up issues enabled | 7,800 | 8,200 | 400 |
+| capped worker rule | 1,347 | 1,600 | 253 |
+| writing rule characters | 1,070 | 1,150 | 80 |
+| writing rule lines | 23 | 25 | 2 |
+
+The four changed bound decisions record the user's choices. The fuller
+Option 3 text puts the enforcement trigger, class confirmation, presentation
+order, and two previously unstated gates in the injected prompt. Writing plus
+router moved from 6,500 to 6,700. Writing plus router and extensions moved from
+6,800 to 6,900. The maximal family moved from 7,900 to 8,200. Writing plus router
+and extensions then moved from 6,900 to 7,000 with user approval so rule 8 could
+keep the skip-the-read clause that rules 9 and 10 also carry. A redundant read of
+the track workflow document costs far more than the clause.
+
+The positive control adds one capped tool and four copies of the largest
+measured model row. It measures 8,670 portable characters and exceeds the
+8,200-character maximal bound by 470. That margin remains larger than the
+184-character maximum model-row growth and the 212-character capped tool growth.
+The raised bound does not blunt the positive control.
+
+These figures are verification budgets, never runtime limits. Arbitrary user
+extension rosters can exceed them. Keep the positive-control steps unchanged
+unless the fixture design itself changes.
+
+Against a 256,000-token context budget, these blocks remain small. The rough
+estimate divides each measured portable-character render by four and rounds to
+the nearest whole token. The shipped-rule table ranges from about 675 tokens to
+about 1,594 tokens. The current dogfood basis is about 1,684 tokens. The stable
+representative maximum is about 1,931 tokens. The follow-up-issues maximum is
+about 1,950 tokens, or 0.76 percent of the default budget.
 
 No tokenizer was run, and tables are denser than prose. The block is re-sent on every request rather than paid once. These figures show how
 much headroom Slate consumes before conversation content.
@@ -381,7 +429,9 @@ long-context rates listed above.
 
 With action-level routing on, this override also settles a warning
 you will otherwise see once per session for each configured
-`gpt-5.6-*` model: Slate's own profile for those models records a
+`gpt-5.6-*` model during resolution. Dispatch-time price divergence warnings
+are conditional and can repeat on later dispatches. Slate's own profile for those
+models records a
 1,050,000-token window, pi's stock registry reports 272,000, and the
 router reports that divergence without adjudicating it (routing uses
 the registry figure). Raising the registry window removes the

package/docs/design-principles.md

@@ -312,19 +312,19 @@ the load-on-demand discipline the extension itself prescribes:
 
 - **Tier 1 — always loaded.** The doctrine in `mode.ts` is the operational
   distillation of P1–P10, the review discipline defined in
-  `review-rules.md`, and a pointer to the track-based workflow protocol
-  that ships with this package (`track-workflow.md` in this directory),
+  `review-rules.md`, and a pointer to the class-scaled track workflow
+  protocol that ships with this package (`track-workflow.md` in this directory),
   appended to the system prompt every turn while orchestrator mode is
   on. Sizing it matters to the tiering argument, so it is measured
-  rather than asserted: with both conditional tail rules and
-  `workflow.draftPRs` off, the block is **1,929 portable characters /
-  38 lines**, and configuring the router for six models roughly
-  DOUBLES it, to **3,870** on that same basis — the routing rule
+  rather than asserted: with every conditional tail rule off and
+  `workflow.draftPRs` off, the block is **2,701 portable characters /
+  46 lines**, and configuring the router for six models nearly
+  doubles it, to **4,731** on that same basis — the routing rule
   renders one table row per routable model. (Portable characters, and
   the rest of the configurations, are defined and tabulated in
   `context-budget.md`; the raw count also depends on where the package
   is installed, because the doctrine embeds absolute doc paths.) At a
-  rough 4 characters per token that is order-500 tokens, order-1,000
+  rough 4 characters per token that is order-700 tokens, order-1,200
   with the router on — so the original "a few hundred tokens" holds
   only for the fixed rules, and a configured router buys its table with
   a real slice of every request. It still covers everything routine

package/docs/model-routing.md

@@ -279,6 +279,7 @@ warning, but removal is not the ADD remedy in condition 2. Condition
 | pi has no usable credentials configured for it | dropped | "has no usable credentials configured in pi. Slate drops it from routing." | configuration fault |
 | every entry is dropped | router turns OFF | "survived validation. The warnings above name each dropped entry" | configuration fault |
 | no usable input price exists for today's date | kept, ordered last | "Slate cannot compare its cost with the other models." | model data note |
+| a profile price is negative or non-finite | kept, ordered last or unavailable | "has invalid input price data" or "has invalid output price data" | model data note |
 | no usable effort ladder exists in the profile | kept | "Such a level passes through to pi, which clamps it" | model data note |
 | profile context window differs from the registry window | kept, registry value used | "differs between two sources" | model data note |
 | the first profile names unknown routing-critical fields | kept | "picks models from a research table shipped inside slate" | model data note |
@@ -288,20 +289,30 @@ warning, but removal is not the ADD remedy in condition 2. Condition
 | every configured candidate is marked non-preferred | cheapest candidate becomes the base | "profiles mark every configured model as one it must never pick by itself" | configuration fault |
 | resolution throws | router turns OFF | "routing is disabled. The router could not resolve its model list" | configuration fault |
 
-Every warning is emitted at most once per session. The complete
-resolution retains every warning regardless of display filtering.
-With `router.showWarnings: true`, every warning reaches the same
-channel as the other config warnings: a UI notification when a UI is
-attached, the console otherwise. With the default `false`, every
-configuration fault still reaches that channel and model data notes
-do not.
-
-When at least one note is hidden, Slate emits one discoverability
-line after resolution. It gives the hidden warning count, names
-`router.showWarnings`, and says that a hidden warning can affect
-which model runs an action. The count is warnings, not physical
-display lines: one warning can wrap across several lines. No
-discoverability line appears when nothing was hidden.
+Each resolution warning is deduplicated by a condition key and retained in the
+frozen resolution regardless of display filtering. With `router.showWarnings:
+true`, every resolution warning reaches the normal UI notification or console
+channel. With the default `false`, every configuration fault remains visible
+and model data notes are hidden.
+
+When resolution hides at least one note, Slate emits one discoverability line.
+It gives the hidden warning count, names `router.showWarnings`, and says that a
+hidden warning can affect model selection. The count is warnings, not physical
+display lines. The line appears at most once per session.
+
+Dispatch-time warnings are separate. Context substitution, effort evidence
+gaps, long-context billing, failover window notices, and the model-visible
+registry-price divergence warning are evaluated for each planned action. They
+can repeat on later dispatches. The divergence warning is hardened and capped
+through the router sanitizer. It omits exact rates and is not deduplicated.
+
+The exact-rate companion uses the class-aware router sink as a model data note.
+It is hidden by default and shown when `router.showWarnings` is true. Its
+condition key includes the model, date, and differing rates, so identical live
+evidence reports once while changed evidence reports again. It passes through
+the same control stripping, citation cleanup, field caps, and whole-message cap
+as resolution warnings. A hidden dispatch-time note can trigger the one-time
+discoverability line only when resolution did not already trigger it.
 
 Half a list is still a routing policy, so partial drops leave the
 router ON. Nothing surviving is not a policy: the router turns OFF
@@ -485,17 +496,18 @@ model's ladder is unreadable.
   `(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).
+- **At the session level:** configuration faults and model data notes enabled by
+  `router.showWarnings`, as UI notifications or console output. The default
+  instead shows one discoverability line when it hides notes.
 - **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,950 characters /
-  20 added doctrine lines for six configured models, 2,505 / 23 for
+  not see, and it is the router's standing cost: 2,030 characters /
+  21 added doctrine lines for six configured models, 2,585 / 24 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
+  always-loaded block (2,701 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
@@ -506,10 +518,12 @@ model's ladder is unreadable.
 
 ## Expected first-session warnings
 
-The stock count below is a render over this repository's
-`.pi/slate.json`, the shipped profile table, and the provider data
-inside the pinned pi 0.83.0 package. It does not read the live model
-registry. The packaged OpenAI data at
+The stock count below comes from executing `resolveModelRouter` with this
+repository's sanitized `.pi/slate.json`, the shipped profile table, and a real
+`ModelRuntime` from the pinned pi 0.83.0 package. The runtime used
+`modelsPath: null` and `allowModelNetwork: false`, so no local registry override
+or network refresh could affect it. Dummy OpenAI and Anthropic credentials made
+the configured-auth premise explicit. The packaged OpenAI data at
 `@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai/dist/providers/data/openai.json`
 reports a **272,000-token** context window for
 `openai/gpt-5.6-luna`, `openai/gpt-5.6-terra` and
@@ -528,8 +542,8 @@ data notes**. The default `router.showWarnings: false` therefore
 shows **0 of those warnings** and one discoverability line. That line
 begins `slate: there are 11 hidden warnings in the model router.`
 Enabling the option shows all 11 warnings and no discoverability
-line. Each warning fires at most once per session, and the resolution
-is frozen after the first consultation.
+line. Each resolution warning fires at most once per session, and the
+resolution is frozen after the first consultation.
 
 | warnings | class | condition keys | why | shown by default |
 | --- | --- | --- | --- | --- |
@@ -576,9 +590,31 @@ A hidden warning can still alter which model runs an action. Context-
 window divergence is the concrete case, and the stock registry emits
 three such hidden notes for this list. Routing uses the registry
 window, and that value drives the context-window substitution guard.
-`router.showWarnings` changes display only; it does not change the
+`router.showWarnings` changes display only. It does not change the
 resolution or the guard input.
 
+## Thread choice after routing
+
+Routing resolves the model and effort for one action. Thread choice then uses that applied pair when it evaluates a continuation.
+
+A model or effort change makes the existing prefix cold. Current cache-write prices are 12.5 times the matching cache-read prices.
+
+The `thread` tool owns the economic comparison. The orchestrator still decides whether named episodes can replace the live transcript.
+
+On a continuation with `threadChoice.act: true`, `freshContext` is required. With acting off, it is optional. Every supplied valid value reaches the planner on either continuation path. An empty array refuses a restart. A non-empty list of existing episode ids permits one and seeds the new thread.
+
+Whenever `freshContext` is supplied, malformed input or an unknown episode is a tool error before creation or mutation. A valid value on a creation call is accepted and unused because creation has no planner.
+
+The planner can return `continue`, `fresh`, `abstain`, or `refused`. Only `fresh` can trigger a restart when `threadChoice.act` is enabled.
+
+Acting defaults off. The default `threadChoice.report` setting returns the verdict without moving the action.
+
+The planner uses current price rows, recorded prefix size, episode size, and dated retention evidence. It abstains when required price or size evidence is missing.
+
+A stale retention row grants no retention window. Missing retention or elapsed time does not prove expiry, so an unchanged route remains warm.
+
+The complete mechanism and evidence limits are in [Thread cache cost](thread-cache-cost.md).
+
 ## What the router does NOT enforce
 
 Two obligations carried by the shipped profile data and stated in
@@ -724,11 +760,9 @@ concern; a green suite says nothing about it.
   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
-  the warm one. The router compares base rates, not the cache state
-  of your thread.
+- **A mid-thread route can cost the prompt cache.** A model or effort
+  change makes the prefix cold. The thread-choice planner prices that
+  cache state after routing. See [Thread choice after routing](#thread-choice-after-routing).
 - **The window guard can move an action to a model you did not
   choose** (it warns, and names what it replaced), and it never
   blocks: if nothing listed is wider, the action runs and pi

package/docs/pr-publishing.md

@@ -9,21 +9,36 @@ workflow-log lifecycle in that mode is owned by track-workflow.md
 
 ## Creation
 
-The umbrella draft PR is created once the design has passed the user
-design review and the adversarial review, BEFORE implementation:
+For every change with a high-level design, draft the PR description
+before the pre-implementation presentation. Present the draft alongside
+the high-level design, so one approval covers both. The description has
+no separate approval gate.
+
+The umbrella draft PR is created after the gate required by the
+confirmed change class passes and BEFORE implementation. For a complex
+or risky change, that gate is the final high-level design approval after
+the adversarial review. For a medium change, it is the high-level design
+approval. A trivial change has no high-level design gate, so the PR is
+created after the user confirms the class and before implementation:
 
 - Created as a DRAFT, based on the repository's default development
   branch.
 - If the working branch has no diff against the base yet, land a
   bootstrap empty commit so the PR can be created.
-- At creation, the research log's content folds into the PR
-  description — Key decisions, Risks, and Open questions feed the
-  corresponding Planned-changes subsections, and the design review and
-  adversarial review verdict lines land in Risks & accepted
-  trade-offs — and the log file is deleted. Decisions made after PR
-  creation are appended to the PR description directly.
-- The user approves the description (and the track split — see
-  track-workflow.md) before implementation starts.
+- At creation for a medium, complex, or risky change, the research
+  log's Planned changes content folds into the PR description. Key
+  decisions, Risks, and Open questions feed the corresponding
+  Planned-changes subsections. The applicable design review verdict
+  lines land in Risks & accepted trade-offs. The adversarial review
+  verdict line lands there only when that review ran; a medium change
+  carries the design verdict lines alone.
+- For a trivial change, the initial request supplies Motivation. The
+  confirmed class proposal and intended fix supply Planned changes. If
+  a log exists, its relevant decisions and Open Questions also fold
+  into the description.
+- The research log is retained until delivery, and its Decision Log
+  keeps appending during implementation. track-workflow.md § Research
+  log owns the full lifecycle.
 
 ## Description rules
 
@@ -46,8 +61,13 @@ Subsections activate when their content exists:
 - **Key decisions** — chosen vs rejected; preempts "why not X?" review
   comments.
 - **Out of scope** — explicit non-goals.
-- **Risks & accepted trade-offs** — including the design review and
-  adversarial review verdict lines.
+- **Risks & accepted trade-offs** — including the applicable design
+  review verdict lines, and the adversarial review verdict line only
+  when that review ran.
+- **Suggestions** — a one-line index per suggestion: identifier,
+  location, and one-line summary. The standalone text lives in the
+  final report to the user or in a tracker issue when
+  `workflow.followUpIssues` enables that prompt.
 - **Verification approach** — 1–2 lines.
 
 "Deep enough" test: a reviewer who knows the codebase but not this
@@ -113,7 +133,10 @@ executed in order:
   review) is completed or explicitly user-waived — flipping never
   discards a pending review.
 - All commits landed since the last user-approved gate are presented
-  to the user.
+  to the user. For a trivial change, present the description here
+  because no design gate presented it before implementation.
+- Every remaining suggestion is reported to the user, and the
+  Suggestions index is present in the description.
 - Strip the whole Tracks section from the description, whatever its
   form — the table for multi-track changes or the "N/A (single-track)"
   placeholder — plus any notes under it. Track numbers are ephemeral
@@ -153,6 +176,9 @@ of any recorded size exception.
 
 ## After the merge
 
+Complete the research-log delivery cleanup defined by
+track-workflow.md § Research log.
+
 Any cleanup a layered peer-review process requires (closing its review
 PRs, deleting its pinned branches) is an agent duty, executed when the
 user reports the merge or a later session detects it, per that