ytdb-slate 0.4.0 → 0.5.1

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+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.
 
 ## Why Slate?
 
@@ -51,6 +51,12 @@ This summary is orientation only; the shipped docs listed below are normative.
 
 Slate can ride through model API outages. The opt-in `modelFailover` map in `.pi/slate.json` (trusted projects only) maps a model (`provider/id`) to an equal-quality alternative; on an eligible model API failure — not an abort or a context overflow, and for the orchestrator and worker sites only after pi's own retries are exhausted — the affected site (orchestrator, worker thread, or episode compression) retries once on the mapped model (single hop, never chained). An orchestrator failover — like the handoff adoption that re-applies a parent session's model — would otherwise leave pi's global model defaults changed, so Slate restores them on a best-effort basis unless `preserveGlobalModelDefault` is `false`. The map is empty by default (feature off) and read once at session start. Full semantics: the `modelFailover` row in [Configuration](#configuration) and the shipped [`docs/model-failover.md`](docs/model-failover.md) — if they disagree, that document wins.
 
+## 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. 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.
+
 ## Install
 
 Install into a project (pinned, project-scoped — recorded in `.pi/settings.json`):
@@ -68,7 +74,7 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | Key | Type | Default | Semantics |
 | --- | --- | --- | --- |
 | `orchestratorModeDefault` | boolean | `false` | Start fresh interactive sessions with orchestrator mode ON. |
-| `episodeModel` | string | newest available Anthropic Sonnet, else the worker's own model | Model (`provider/id`) used to compress a finished action into an episode. |
+| `episodeModel` | string | newest available Anthropic Sonnet, else the orchestrator's own base model | Model (`provider/id`) used to compress a finished action into an episode. Never the model an action was routed to: an episode is read by every later consumer of the thread, so one cheap route must not degrade the record. An unusable value is reported and the default is used. |
 | `workerTools` | string[] | `["read", "bash", "edit", "write", "grep", "find", "ls"]` | Tools available to worker threads (an empty list also falls back to the default). |
 | `workerExtensions` | string[] | `[]` | Regex patterns (matched **unanchored**) selecting which of the host session's already-loaded extensions also load into every worker thread; each matched extension's tools are added **on top of** `workerTools`. Empty (default) means workers load no extensions. The orchestrator keeps its restricted tool set but its doctrine is told what was whitelisted. Invalid patterns are dropped with a warning at session start. |
 | `maxConcurrent` | number | `4` | Maximum number of worker actions running concurrently (must be ≥ 1 — unenforced: a value of 0 or less silently hangs all dispatches). Excess dispatches wait in a queue; actions on the same thread always run in dispatch order. Default rationale: shipped `docs/design-principles.md` §5 (repo-local note). |
@@ -80,6 +86,8 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `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 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):
 
@@ -93,7 +101,8 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "workflow": { "draftPRs": true },
   "doctrineExtraPath": "docs/agents/workflow-additions.md",
   "reviewPerspectivesPath": "docs/agents/review-perspectives.md",
-  "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" }
+  "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" },
+  "router": { "models": ["openai/gpt-5.6-luna", "anthropic/claude-opus-5"] }
 }
 ```
 
@@ -126,7 +135,7 @@ Slate reads project configuration (`.pi/slate.json`) and injects project files (
 
 ## Shipped docs
 
-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:
+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/pr-publishing.md` — umbrella draft-PR publishing (cited only when `workflow.draftPRs` is `true`)
@@ -134,6 +143,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/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

@@ -118,6 +118,114 @@ paused, threshold compactions pass through as an escape valve.
 Overflow-recovery compaction and manual `/compact` are never
 touched.
 
+## What the always-loaded doctrine costs the budget
+
+The budget's denominator includes Slate's own always-loaded block.
+While orchestrator mode is on, the doctrine sits in the
+orchestrator's system prompt for the whole session — and, like the
+rest of the conversation (see the pricing cliff above), it is sent
+again with every request. It occupies its space in the window once;
+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
+(`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
+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:
+
+> 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:
+
+| router | models | `draftPRs` | paths | portable | lines | rendered at a 58-char docs dir |
+| --- | --- | --- | --- | --- | --- | --- |
+| 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 |
+
+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.
+
+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.
+- 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.
+
+## Worker threads: the routing window guard
+
+The budget above is the ORCHESTRATOR's. Worker threads have no
+budget and never pause; with action-level routing on, they get a
+weaker but automatic counterpart. Before each dispatch — whenever
+the thread's context size is knowable, so not for a thread whose
+worker session has not been opened yet — the routed model's
+REGISTRY context window is checked against that size using pi's OWN
+compaction settings, the same settings whose `reserveTokens` clamps
+the budget above. (The check runs even if you disabled
+auto-compaction: turning compaction off does not make an
+over-window dispatch safe, it only turns the compaction into an
+overflow error.) If the thread no longer fits, the action is moved
+to the widest listed model when that one is strictly wider, with a
+warning; if nothing listed is wider it runs anyway and pi compacts.
+The guard never blocks a dispatch and never pauses a thread.
+
+Two consequences for this document's subject:
+
+- The registry window is what decides the substitution, so the
+  overrides in the next section change worker routing too: raising
+  `gpt-5.6-*` to 1,050,000 makes those models genuinely wide
+  candidates rather than 272K ones.
+- A narrow model in `router.models` is not a hazard the way it would
+  be for the orchestrator — it is a model long threads get routed
+  AWAY from, paying the wider model's rate instead. That is not
+  silent: the substituted action carries a ⚠ notice naming both
+  models.
+
+Routing itself — the two `router` keys, what makes a model routable,
+how effort levels resolve and the full guard list — is documented in
+`model-routing.md` in this directory.
+
 ## Using GPT-5.6's full 1.05M window
 
 Two deliberate steps. First, raise the registry window in
@@ -155,6 +263,17 @@ dropped:
 WARNING: beyond 272K total input every request bills at the
 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
+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
+disagreement at its source. Leaving it alone is equally valid — the
+registry figure is the conservative one — and `model-routing.md`
+explains why Slate does not silence the warning by editing its own
+number.
+
 ## Accepted limitations
 
 - On models with a 272K pricing tier and a larger registry window
@@ -174,3 +293,9 @@ long-context rates listed above.
   compaction can land in the same cycle and the handoff brief is
   written from compacted context — episodes and thread state survive
   on disk, so handoff still functions.
+- The doctrine sizes above cover the shipped rules only. A project
+  that also injects `doctrineExtraPath` or `orchestratorPromptDocs`,
+  or whitelists worker extensions, pays for those on top in the same
+  always-loaded position, and Slate measures none of it against the
+  budget separately — it simply arrives as context the budget then
+  has less room for.

package/docs/design-principles.md

@@ -8,9 +8,22 @@ for its content. This document records the reasoning behind the
 extension's design so maintainers — and the orchestrator itself, on
 demand — can check changes and behavior against the original intent.
 
-Note: module headers cite ExecPlan decision ids (D3–D9, M1–M3) from the
-original implementation plan, which is not part of this repository. This
-document is the in-repo source for the architecture rationale.
+Note: module headers cite ids from design records that are not part of this
+repository — the original implementation plan (ExecPlan: D3–D9, M1–M3), later
+design rounds (higher-numbered D ids, and W ids for named warnings), and
+per-round review findings, whose prefix says which review raised them:
+AD (adversarial), AF (agent-failure), BG (blocker/bug), CN (concurrency),
+CQ (code quality), DF (data fidelity), N (numeric), RG (regression),
+RI (research integrity), SE (security), WB (worker boundary) and WS (worker
+safety). `extension/model-profiles.ts` additionally cites research TRACE keys
+(`G1a`, `GM3`, `O4.2`, `A4b`, …). Those name rows in the research corpus that
+produced the profile table; the corpus lives in the project repository and is
+NOT part of the published package, so in an installed copy the keys are
+provenance marks to quote when reporting a data problem, not links to follow.
+What a consumer can act on without the corpus is in `model-routing.md`
+(§ where the numbers come from): the table's provenance rules, its `asOf`
+date, and which fields are marked untraced. This document is the in-repo
+source for the architecture rationale.
 
 ## 1. The problems Slate is built to solve
 
@@ -167,6 +180,38 @@ while staying safe on common consumer API tiers; wider fan-outs only
 pay tail latency, and projects with higher-tier keys raise the cap in
 `slate.json`.
 
+Repo-local note (not from the report): **action-level model routing**
+applies P10's discipline to a second scarce resource. P10 treats
+CONTEXT as RAM; the optional `router.models` list treats SPEND the same
+way — each dispatched action gets a model and an effort level chosen to
+be up to the task and no more, instead of every action inheriting
+whatever model the orchestrator happens to be running. It is also a P1
+corollary: an action is only a bounded unit if what it may cost is
+bounded too, and the closed model list plus a derived (never inflated)
+effort level is what bounds it. The two disciplines even share
+machinery — pi's compaction settings, which clamp the orchestrator's
+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.
+
+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
+outside the configured list, a level a model does not offer — because
+those are decidable from the data. The obligations that require
+JUDGMENT about the work, such as which actions count as review or gate
+actions and what a compliance constraint demands of a given task, are
+stated in the doctrine for the orchestrator to honor and are not
+guards. That is the same reasoning as P6: the harness makes the right
+thing natural and blocks what it can decide, rather than pretending to
+adjudicate what it cannot see. Which obligations fall on which side of
+that line changes as the feature grows, so this document deliberately
+does not restate the list — `model-routing.md` in this directory owns
+it, along with the mechanics and the provenance of the routing data.
+
 Repo-local note (not from the report): the P7 guard was originally
 absolute — workers loaded no extensions, so Slate's `thread` tool simply
 never existed for them. The optional `workerExtensions` key (`slate.json`,
@@ -268,7 +313,19 @@ the load-on-demand discipline the extension itself prescribes:
   `review-rules.md`, and a pointer to the track-based 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. It costs a few hundred tokens and covers everything routine
+  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
+  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
+  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
   dispatching needs.
 - **Tier 2 — on demand.** This document. The doctrine carries a short
   pointer to it (doctrine rule 10); the orchestrator reads it only when

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