ytdb-slate 0.4.0 → 0.5.0

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; 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.
+
+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 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.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,36 @@ 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.
+
+The feature is OFF until `router.models` lists something, and it 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 +311,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