ytdb-slate 0.9.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

@@ -207,18 +207,18 @@ must be named instead of presented as the same measurement:
 
 | router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
-| off | — | off | off | 4 | 2,270 | 43 |
-| off | — | off | on | 5 | 3,340 | 65 |
-| off | — | on | off | 5 | 2,289 | 43 |
-| off | — | on | on | 6 | 3,359 | 65 |
-| on | `.pi/slate.json` six | off | off | 5 | 4,300 | 64 |
-| on | `.pi/slate.json` six | off | on | 6 | 5,370 | 86 |
-| on | `.pi/slate.json` six | on | off | 6 | 4,319 | 64 |
-| on | `.pi/slate.json` six | on | on | 7 | 5,389 | 86 |
-| on | all 9 shipped | off | off | 5 | 4,855 | 67 |
-| on | all 9 shipped | off | on | 6 | 5,925 | 89 |
-| on | all 9 shipped | on | off | 6 | 4,874 | 67 |
-| on | all 9 shipped | on | on | 7 | 5,944 | 89 |
+| 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
@@ -250,8 +250,9 @@ worker extensions and support verification decisions:
 
 | basis | models | worker extensions | paths | portable | lines | rough tokens |
 | --- | ---: | --- | ---: | ---: | ---: | ---: |
-| current `.pi/slate.json` dogfood config | 6 | pinned-package 2 units / 4 tools | 7 | 6,305 | 96 | ≈1,576 |
-| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 7 | 7,291 | 99 | ≈1,823 |
+| 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
@@ -261,6 +262,7 @@ units and four tools. Their worker-extension rule is 916 portable characters /
 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.
@@ -278,35 +280,46 @@ 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 paired maximal fixtures cover rule 8 with draft pull requests enabled and
-disabled. 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
+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 | measured | old bound | current bound | current reserve |
-| --- | ---: | ---: | ---: | ---: |
-| routing rule characters | 2,585 | 4,000 | 4,000 | 1,415 |
-| routing rule lines | 25 | 34 | 34 | 9 |
-| routing fixed prose | 1,110 | 1,500 | 1,500 | 390 |
-| largest model row | 183 | 300 | 300 | 117 |
-| router-on doctrine | 4,855 | 6,500 | 6,500 | 1,645 |
-| writing-only doctrine | 3,340 | 5,600 | 5,600 | 2,260 |
-| writing plus router | 5,925 | 6,300 | 6,500 | 575 |
-| writing plus extensions | 3,595 | 6,000 | 6,000 | 2,405 |
-| writing plus router and extensions | 6,180 | 6,600 | 6,800 | 620 |
-| maximal doctrine, draft PRs enabled | 7,291 | 7,800 | 7,900 | 609 |
-| maximal doctrine, draft PRs disabled | 7,272 | 7,800 | 7,900 | 628 |
-| capped worker rule | 1,347 | 1,600 | 1,600 | 253 |
-| writing rule characters | 1,070 | 1,150 | 1,150 | 80 |
-| writing rule lines | 23 | 24 | 25 | 2 |
+| 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,239 portable characters and exceeds the new
-7,900-character maximal bound by 339. That margin remains larger than the
+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.
 
@@ -314,11 +327,12 @@ 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. At four
-characters per token as a rough estimate, the shipped-rule table ranges from
-about 568 tokens to about 1,486 tokens. The current dogfood basis is about 1,576
-tokens. The representative maximum is about 1,823 tokens, or 0.72 percent of the
-default budget.
+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.

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 every conditional tail rule off and
-  `workflow.draftPRs` off, the block is **2,270 portable characters /
-  43 lines**, and configuring the router for six models nearly
-  doubles it, to **4,300** on that same basis — the routing rule
+  `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

@@ -507,7 +507,7 @@ model's ladder is unreadable.
   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 (2,270 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

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

package/docs/review-rules.md

@@ -15,8 +15,11 @@ type, also embed the §7 obligations or direct the reviewer to read them.
 
 ## 1. When to review
 
-- Every non-trivial change gets reviewed before it is declared done.
-- Rigor scales with risk of the change, never with effort already spent.
+- The agent code review of a track is skipped only when the whole change
+  is trivial. No track inside a medium, complex, or risky change is
+  trivial. Every required review occurs before the change is declared
+  done. [track-workflow.md](track-workflow.md) defines these classes.
+- Rigor scales with the change class, never with effort already spent.
   When in doubt, review more.
 - For long multi-step work streams, review high-risk steps in isolation
   right after they land — defects localized to one step get buried once
@@ -32,9 +35,18 @@ type, also embed the §7 obligations or direct the reviewer to read them.
   dispatch. Use `adversarial` for a perspective that actively seeks
   counterexamples and `reviewer` for every other review perspective.
 - Do not pass implementer episodes or implementer reasoning to
-  reviewers. Give a reviewer the artifact/diff, the intent of the
-  change, its in-scope files, and its charter plus reasoning/output
-  obligations (see the intro).
+  reviewers. Section 8 defines the single exception.
+- Every review dispatch includes the artifact/diff, the charter plus
+  reasoning/output obligations (see the intro), and a TRACK INTENTION
+  BLOCK with these four fields:
+  - target;
+  - scope boundary;
+  - deferred work;
+  - acceptance condition.
+  When no track exists, such as during a design-stage adversarial
+  review, the same four fields describe the whole change instead.
+  A reviewer without a target grades against an ideal and inflates
+  severity.
 - Independent perspectives run in PARALLEL on the same artifact.
 
 ## 3. Choose perspectives by what the change touches
@@ -143,13 +155,44 @@ perspective's charter:
   free number for its prefix.
 - Severity: **blocker** (must fix before done), **should-fix** (fix
   unless explicitly justified and reported), **suggestion** (optional).
-- Synthesize across reviewers: deduplicate by location/root cause,
-  keep all contributing IDs on the merged finding, and take the
-  highest severity when duplicates disagree (upgrade-only — never
-  downgrade a severity during synthesis).
+- Grade severity against the stated target of the track. A defect that
+  stops the track from reaching its target is a blocker or should-fix.
+  A defect outside the target is a suggestion.
+- Target-relative grading never lowers a safety defect or a correctness
+  defect. This safety floor protects concurrency, durability, recovery,
+  transactional semantics, a public API or behavioral change, security,
+  user data, and a missing test for a changed branch. Target-relative
+  grading can lower style concerns, refactoring opportunities,
+  neighboring-code concerns, and structural preferences.
+- Synthesize across reviewers by deduplicating findings with the same
+  location or root cause. Keep all contributing IDs on the merged
+  finding, and take the highest reviewer severity when duplicates
+  disagree. This upgrade-only rule governs deduplication only.
+- After synthesis, the orchestrator validates every finding's severity,
+  because the orchestrator holds the widest view of the change. It may
+  raise or lower a severity. It may not lower a finding that a gate
+  thread marked STILL OPEN or REGRESSION. Lowering a blocker requires
+  user confirmation.
+- Every change records the reviewer severity, validated severity,
+  validation reason, reviewer episode identifier, and observation path
+  for every finding. The final report shows the reviewer and validated
+  severities side by side.
+- Blockers and should-fix findings are fixed inside the change. Every
+  other finding becomes a suggestion and follows §5.
 
 ## 5. Reviewers find, implementers fix
 
+- An implementation-stage suggestion is NEVER fixed inside the change
+  that found it. Design-stage triage follows track-workflow.md § Finding
+  triage instead. The orchestrator collects implementation-stage
+  suggestions and presents them at the end. Each entry states what,
+  where, why it matters, and what a fix needs. The entry must be
+  readable without the review that produced it. The delivery record
+  preserves a durable one-line index of every suggestion. The
+  standalone text lives in the final report to the user or in a tracker
+  issue. `workflow.followUpIssues` controls only whether the
+  orchestrator asks which suggestions become tracker issues. The key
+  defaults to `false`. An off value never discards a suggestion.
 - Review threads never edit files; fix work is dispatched to an
   implementation thread (usually the one that produced the change, or
   a fresh one if it is gone or compromised — context-poisoned or
@@ -197,6 +240,8 @@ perspective's charter:
 
 ## 6. Iteration and termination
 
+- The review loop is internal to the orchestrator. Do not show the user
+  each iteration.
 - After fixes, re-verify each addressed finding — in a gate thread,
   not by trusting the fixer's claim. Dispatch every gate thread with the
   `reviewer` type. A gate thread is a fresh thread whose sole job is
@@ -212,11 +257,16 @@ perspective's charter:
   - **REGRESSION** — the fix broke something else; file the breakage
     as a new blocker (RG prefix).
 - Blockers loop until clear. Should-fix findings get up to 3
-  iterations for normal changes; go deeper only for high-risk changes.
-- No-progress rule: if an iteration clears nothing and surfaces no new
-  fixable finding, stop and escalate to the user instead of spinning.
-- Done = no blockers remain, addressed findings VERIFIED, and any
-  remaining should-fix/suggestions explicitly reported to the user.
+  iterations. The escape hatch in §8 is available when a trigger fires.
+- These escalations always reach the user: an iteration that clears
+  nothing, a third iteration on should-fix findings, a second regression
+  filed on one finding, and any proposed lowering of a blocker.
+- No-progress rule: if an iteration clears nothing, stop the ordinary
+  fix loop and escalate to the user instead of spinning. The escape
+  hatch in §8 remains available.
+- Done = no blockers remain, every addressed finding is VERIFIED, no
+  should-fix remains open without a recorded justification, and every
+  suggestion is reported to the user.
 
 ## 7. Reviewer evidence standards (how reviewers argue)
 
@@ -264,3 +314,23 @@ than implement its method.
   arguments carry no formal guarantee and do not replace running the
   project's checks.
 <!-- reviewer-charter:end -->
+
+## 8. Escape-hatch adversarial review
+
+- The escape hatch is available when a fix iteration clears nothing, a
+  gate thread returns STILL OPEN twice on one finding, the implementer
+  cannot locate the cause, or a fix keeps producing regressions.
+- The hatch dispatches a fresh adversarial thread. Its job is to explain
+  why the fix fails, not to grade the change.
+- This review is separate from the pre-implementation adversarial review
+  in [track-workflow.md](track-workflow.md). Neither review satisfies the
+  other. The escape hatch is available at every change class.
+- This review is the single exception to the §2 ban on passing
+  implementer episodes to reviewers. The orchestrator passes the
+  smallest episode subset that carries the evidence. It names every
+  episode passed and states why each one is needed.
+- The hatch output is evidence, not a verdict. It closes no finding and
+  lowers no severity. A null verdict proves nothing. Anything the hatch
+  raises goes to a normal gate thread for a verdict.
+- The hatch needs no research log. Append any decision that comes out of
+  it to the Decision Log.

package/docs/thread-cache-cost.md

@@ -93,6 +93,10 @@ The orchestrator chooses the work stream, thread, model, effort, task, and requi
 
 The tool makes one narrow economic judgement. It decides whether continuing the named thread costs more than a fresh thread seeded with named episodes.
 
+A blanket refusal of a thread restart has a price. Refuse a restart only when the next action depends on context from the previous action that the thread's episodes do not carry. The orchestrator can apply this test because it reads those episodes before choosing the successor's context.
+
+The compressed path is instructed to retain published findings, approved decisions, named file paths, recorded verification results, commands, error messages, and outcomes. The fallback path carries the task and up to 8,000 characters of the raw final worker output instead. Therefore the first group is available on the compressed path when retained, and on the fallback path only when the final output contains it. Terminal output can reach a fallback episode when the worker pasted it into that output. Compression can also retain terminal details when they are relevant, so terminal output is not a universal exclusion. Unrecorded intermediate reasoning and conversational details omitted from the final output remain unavailable on the fallback path, while compression is instructed to drop tactical noise. Continue the live thread when the next action needs context the episode does not contain. Permit a restart when the episode contains the context needed to act.
+
 ### Permission through `freshContext`
 
 The `freshContext` contract asks three separate questions:

package/docs/track-workflow.md

@@ -2,51 +2,107 @@
 
 The mandatory flow for every change delivered under this workflow:
 
-Research → (lazy) research log → user design review → adversarial
-review → user approves the track split → per-track loop (implement →
-track code review → fixes → mandatory user review → marker commit) →
-delivery.
+Research → confirm the change class → open a research log when required
+→ prepare the high-level design for medium, complex, and risky changes
+→ obtain pre-adversarial approval and adversarial review for complex and
+risky changes → obtain pre-implementation approval for every high-level
+design → per-track loop (implement → track code review when required →
+fixes → mandatory user review → marker commit when required) → delivery.
 
 Publishing is conditional on `workflow.draftPRs` in the project's
 `slate.json` (default: false). When it is ENABLED, an umbrella draft
-PR is created after both reviews pass and before implementation
-starts — see pr-publishing.md in this directory for all PR mechanics.
-When it is DISABLED, the workflow log is the change's durable record;
-its lifecycle is defined in § Research log below. Marker commits work
-identically in both modes.
-
-The flow scales with change size:
-
-| Change size | What applies |
-| --- | --- |
-| Multi-track change | Full flow as described above. |
-| Single-track change | No track split, no marker commits. Everything else applies. |
-| Trivial change (typo, doc-only, mechanical rename, obvious one-file fix) | No split. The planned-changes statement is a 2–3-sentence paragraph; the design review collapses into user consent to it. Micro adversarial review, or skip it with explicit user consent. |
-
-The mandatory user review gate applies at EVERY tier. For single-track
-and trivial changes the whole branch diff is the track, so the user
-review sits after the agent code review and before delivery.
-
-Throughout this document, the "planned-changes statement" is the
-high-level design summary of the change. With publishing enabled it
-becomes the Planned-changes section of the PR description (see
-pr-publishing.md); with publishing disabled it lives in the workflow
-log.
+PR is created after the applicable pre-implementation gates pass and
+before implementation starts — see pr-publishing.md in this directory
+for all PR mechanics. When it is DISABLED, the workflow log is the
+change's durable record; its lifecycle is defined in § Research log
+below. Marker commits work identically in both modes.
+
+## Change classes
+
+Gates key on the change class, not on size. 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.
+
+The orchestrator proposes the class and the user confirms it. The
+proposal states the class, the reason, and the property that would
+raise it. The orchestrator re-proposes the class whenever new
+information appears. An upgrade to any higher class after implementation
+starts pauses implementation. The orchestrator opens and backfills a
+research log when the new class requires one, then runs every newly
+required gate over the WHOLE change before implementation resumes. A
+gate whose prescribed timing has passed runs retroactively. The class
+is never lowered after implementation starts.
+
+Size drives only the track split and marker commits. The orchestrator
+owns the track split at every class; it is not a user approval gate.
+
+### Worked classification examples
+
+**Trivial — correct one misspelled word in an internal comment.**
+
+- Step 1 does not match because no risky category changes.
+- Step 2 does not match because the shape is clear and no parts interact.
+- Step 3 matches. The correction is an obvious fix, behavior does not change,
+  and one reviewer pass can verify the complete diff.
+- Result: **Trivial**.
+
+**Medium — rename one internal helper and update its 40 call sites.**
+
+- Step 1 does not match because no public surface, behavior, or other risky
+  category changes.
+- Step 2 does not match because the mechanical shape is clear, the call sites
+  do not interact, and no design alternative exists.
+- Step 3 does not match. The repository-wide refactor is not an obvious fix,
+  and one reviewer pass cannot cover all references, strings, and documentation.
+- Step 4 matches by default.
+- Result: **Medium**.
+
+**Complex — reorganize test-fixture assembly across its loader, builder, and
+cleanup modules.**
+
+- Step 1 does not match because production behavior and every risky category
+  stay unchanged.
+- Step 2 matches. Several parts interact, and live alternatives either
+  centralize fixture state or pass it explicitly between the modules.
+- Result: **Complex**.
+
+### Gate matrix
+
+| Gate | Trivial | Medium | Complex | Risky |
+| --- | --- | --- | --- | --- |
+| High-level design | No | Yes | Yes | Yes |
+| High-level design shown before adversarial review | No | No | Yes | Yes |
+| High-level design shown before implementation | No | Yes | Yes | Yes |
+| Adversarial review of the high-level design | No | No | Yes | Yes |
+| Research log | No, unless a trigger fires | Yes | Yes | Yes |
+| Agent code review of a track | No, when the whole change is wholly trivial | Yes | Yes | Yes |
+| User review of the track diff | Yes | Yes | Yes | Yes |
+
+The track split belongs to the orchestrator at every class.
 
 ## Research phase (lightweight)
 
 Research is interactive exploration before any implementation: read
 real source code, trace call chains, and clarify aims and constraints
-with the user. There is no design document, no implementation plan,
-and no mandatory artifacts. The phase ends when the initial design of
-the change is understood and has passed the user design review (see
-below).
+with the user. Before the class is settled, no design document,
+implementation plan, or mandatory artifact is assumed. The phase ends
+when the initial shape and class of the change are understood.
 
-## Research log (lazy-triggered)
+## Research log
 
-Start research WITHOUT a log. Open one the moment any trigger below
-fires, then backfill the decisions already made — backfilling is cheap
-while they are still in context.
+A research log is mandatory for every change above trivial. For the
+trivial class, and during research before the class is settled, start
+research WITHOUT a log. Open one the moment any trigger below fires,
+then backfill the decisions already made — backfilling is cheap while
+they are still in context.
 
 | # | Trigger |
 | --- | --- |
@@ -57,9 +113,19 @@ while they are still in context.
 | 5 | The change is multi-track. |
 | 6 | The user requests it. |
 
+The trigger table governs the trivial class and research before class
+confirmation. Once the user confirms a class above trivial, the log is
+mandatory whether or not a trigger fired.
+
+The Decision Log remains append-only throughout research and
+implementation. It records decisions taken after implementation
+starts because the log is the record that survives a context handoff.
+At high-level design approval, it records the workflow rule-set version and the
+gates already passed.
+
 ### Log format
 
-Four sections, opened with the log:
+Four sections are opened with the log:
 
 - **Initial request** — verbatim, written once.
 - **Decision Log** — append-only. Each entry is at most 4 lines: the
@@ -69,44 +135,53 @@ Four sections, opened with the log:
 - **Surprises & Discoveries**
 - **Open Questions**
 
-Two more named sections join as the corresponding phase begins:
+Three more named sections join as the corresponding material appears:
 
-- **Planned changes** — the planned-changes statement, added when the
-  design converges; the design review and adversarial review verdict
-  lines are appended at its end. (With publishing enabled this section
-  feeds the PR description at umbrella-PR creation.)
-- **Track table** — publishing disabled only: added when the user
-  approves the track split (constraints in § Track table). With
-  publishing enabled the table lives in the PR description from
-  creation instead.
+- **Planned changes** — contains the high-level design when it
+  converges; the applicable design-review and adversarial-review
+  verdict lines are appended at its end.
+- **Suggestions** — one standalone entry per suggestion. Each entry
+  states what the suggestion is, where it applies, why it matters,
+  and what a fix needs. It MUST be readable without the review that
+  produced it.
+- **Track table** — added when the orchestrator splits the change into
+  tracks (constraints in § Track table). With publishing enabled the
+  table also lives in the PR description as pr-publishing.md directs.
 
 ### Persistence
 
-During research the log lives as an untracked file `research-log.md`
-at the repo root. What happens next depends on `workflow.draftPRs`:
-
-- **Enabled** — the log's life ends at umbrella-PR creation: its
-  content folds into the PR description and the file is deleted
-  (mechanics owned by pr-publishing.md § Creation).
-- **Disabled (default)** — the log is RETAINED at the repo root as the
-  change's workflow log until the change is delivered (§ Delivery
-  below). The planned-changes statement and both verdict lines anchor
-  in its Planned changes section, the track table in its Track table
-  section (§ Log format), and post-design decisions keep appending to
-  the Decision Log.
+During the change the log lives as an untracked file
+`research-log.md` at the repo root. The log is RETAINED until delivery
+with `workflow.draftPRs` either enabled or disabled. Post-design and
+implementation decisions keep appending to its Decision Log.
+pr-publishing.md owns how the log content reaches the pull request
+description when publishing is enabled.
 
-### Delivery (publishing disabled)
+### Delivery
 
 A change is DELIVERED when its final squashed commit lands on the
 repository's default development branch, or when the user explicitly
-abandons it. At delivery the agent folds the log into the delivery
-commit's message body — the motivation, the planned-changes statement,
-and both verdict lines: the same content that would have become the PR
-description — strips the track table (track numbers are ephemeral
-branch-life identifiers and would dangle in history), resolves or
-explicitly hands any remaining Open Questions to the user, then
-deletes the log file. On abandonment the agent deletes the log file
-after offering its content to the user for archiving.
+abandons it. With publishing disabled for a medium, complex, or risky
+change, the agent folds the log into the delivery commit's message body
+— the motivation, Planned changes, and the applicable verdict lines:
+the same content that would have become the PR description — and strips
+the track table (track numbers are ephemeral branch-life identifiers and
+would dangle in history). For a trivial change, the initial request
+supplies the motivation, and the confirmed class proposal plus
+implemented result supply Planned changes. If that trivial change has a
+log, also fold in its relevant decisions and Open Questions. In either
+case, resolve or explicitly hand any remaining Open Questions to the
+user, then delete any log file. With publishing enabled,
+pr-publishing.md owns delivery of the log content. When the user reports
+the merge or a later session detects it, the agent deletes the retained
+local log. In both modes the retained local log is deleted only at
+delivery. On abandonment the agent deletes the log file after offering
+its content to the user for archiving.
+
+The delivery commit body carries a one-line index of every suggestion:
+identifier, location, and one-line summary. The standalone suggestion
+text lives in the final report to the user, or in a tracker issue when
+the project enables that prompt.
 
 Aim to keep the final delivery commit body at or below 16,384 UTF-8
 bytes, excluding the subject. This is a target, not a gate. Measure
@@ -139,103 +214,88 @@ nor an exercised exception for publishing-disabled delivery.
 
 ### Under-trigger guardrail
 
-When shaping the planned-changes statement without a log, state this
-explicitly (e.g. "no log kept — one trivial decision, no surprises")
-so the user can override and request one.
+For a trivial change shaped without a log, state this explicitly (for
+example, "no log kept — one trivial decision, no surprises") so the
+user can override and request one. This guardrail applies only to the
+trivial class.
+
+## High-level design and user review
 
-## User design review (mandatory, pre-adversarial)
+The **high-level design** is the workflow's single design artifact. It
+is required for medium, complex, and risky changes. It contains only the
+goal, approach, key decisions, rejected alternatives, risks, scope
+boundary, and open questions. Implementation detail belongs to code
+review, not to the high-level design.
 
-When research converges, the agent presents the design to the user:
-the proposed approach, key decisions with the alternatives rejected,
-risks, and open questions. The presentation input is keyed on log
-existence, the same way as the adversarial review's: log exists →
-present from the log; no log → present the draft planned-changes
-statement. The agent then loops on user feedback — revising the design
-(and log) — until the user explicitly approves. Only after that
-approval does the adversarial review run.
+For complex and risky changes, present the high-level design twice: once
+before the adversarial review, and once before implementation. For
+medium changes, present it once before implementation. For trivial
+changes, there is no high-level design and no consent gate. When the
+project sets `writing.check` to true, the high-level design follows the
+project's writing convention.
 
-Rationale: the user owns the design direction. Reviewing with the user
-first means the adversarial review attacks a stabilized, user-endorsed
-design instead of one the user may still redirect — adversarial rounds
-are not spent on designs that would change anyway. The loop mechanics
-mirror the track loop's mandatory user review (present → feedback →
-explicit approval); the position relative to machine review is
-deliberately inverted — here the user reviews first.
+At each presentation, the orchestrator loops on user feedback and
+revises the high-level design and log until the user explicitly
+approves. For a complex or risky change, append this verdict line after
+the first approval:
+
+```
+Design review (pre-adversarial): user-approved — YYYY-MM-DD
+```
 
-Durable record — append a verdict line to the log:
+For every change with a high-level design, append this second verdict
+line after the approval immediately before implementation:
 
 ```
-Design review: user-approved — YYYY-MM-DD
+Design review (pre-implementation): user-approved — YYYY-MM-DD
 ```
 
-With no log, append the line to the draft planned-changes statement
-instead. With publishing enabled it travels into the PR description at
-umbrella-PR creation (pr-publishing.md § Creation); with publishing
-disabled the workflow log's Planned changes section is the verdict
-line's only durable home — writing the first verdict line opens the
-log if none exists, seeded with the planned-changes statement. (Crossing a session boundary before the change is published
-or delivered is research-log trigger #4.) The verdict line is written
-at every tier; at the trivial tier it is appended after the
-planned-changes paragraph, which stands in for the Risks & accepted
-trade-offs subsection.
-
-Tier scaling: at the trivial tier the design review collapses into the
-user's consent to the 2–3-sentence planned-changes paragraph. With
-publishing enabled, the ask for trivial and single-track changes may
-be batched: the agent presents the design together with the draft PR
-description in ONE pre-adversarial ask, and the user's single approval
-covers both. Umbrella-PR creation still follows the adversarial
-review; the description is re-presented only if adversarial triage
-changed it.
-
-## Adversarial review (mandatory, pre-implementation)
-
-Adversarial review runs after the user approves the design in the user
-design review, BEFORE the planned-changes statement is finalized and
-implementation starts, for EVERY change. The rationale, briefly:
-critique activates latent knowledge that constructive planning does
-not (generator/critic asymmetry), and a fresh-context reviewer has no
-anchoring on the author's rationale.
-
-The reviewer must be a fresh context (sub-agent or fresh session) that
-did not author the decisions.
-
-Input is keyed on log existence:
-
-- Log exists → the adversary attacks the log (plus its cited
-  evidence).
-- No log → the adversary attacks the draft planned-changes statement.
-- Trivial tier → micro-review with one bounded question ("what breaks
-  / what am I not seeing?"), or skipped with explicit user consent.
-
-Charter scaling: for single-track changes, limit the mandate to
-correctness, hidden coupling, and missed alternatives — style and
-speculative scope creep are out of bounds.
-
-Licensed null verdict: "no substantive findings" is an acceptable,
-respected outcome — the review prompt must say so.
-
-Triage each finding with the user. Three outcomes:
+The Planned changes section of the retained log is the durable home
+for the high-level design and both lines. If adversarial triage changes
+the high-level design, the second presentation shows every change
+before the user gives the pre-implementation approval.
+
+## Adversarial review of the high-level design
+
+Adversarial review runs only for complex and risky changes. It runs
+after the user approves the high-level design for review and before its
+pre-implementation presentation. The reviewer judges the HIGH-LEVEL DESIGN.
+Implementation detail and style are out of bounds. The reviewer must
+be a fresh context that did not author the decisions.
+
+The adversary attacks the log and its cited evidence. Licensed null
+verdict: "no substantive findings" is an acceptable, respected outcome
+— the review prompt MUST say so.
+
+### Finding triage
+
+The orchestrator triages every finding itself with one of three
+outcomes:
 
 - **Strengthen** — enrich the alternatives-rejected rationale of the
   attacked decision.
 - **Reverse** — change the decision now, while it is still cheap.
 - **Accept-as-risk** — record it in Open Questions / Risks.
 
-Triage runs with the user, so a Reverse outcome is itself
-user-endorsed; after any reversal, refresh the design-review verdict
-line (new date) before any further adversarial round (a round-2
-reversal refreshes the line before the change is declared reviewed).
+Every reversal and every accepted risk appears in the high-level design
+that the user approves before implementation. A design-stage finding is
+triaged at design time whatever its severity. review-rules.md §5 governs
+implementation-stage suggestions, not design-stage findings.
 
-One round by default; run a second round only if any decision was
-actually reversed. Append a verdict line to the log (or to the draft
-planned-changes statement if there is no log — same homing rules as
-the design-review verdict line):
+One round runs by default. A second round runs only after a reversal.
+Append a verdict line to the log:
 
 ```
 Adversarial review: passed, N accepted risks — YYYY-MM-DD
 ```
 
+### Escape hatch during implementation
+
+review-rules.md in this directory defines a separate escape-hatch
+adversarial review. It runs during implementation when a fix is stuck.
+It is separate from this pre-implementation gate. Its output is
+evidence and never a verdict.
+
 ## Track loop
 
 A track is one unit in a stacked series: it builds on the tracks
@@ -243,10 +303,12 @@ before it, stands alone as an independently reviewable diff, and
 carries as much of the change as one reviewable diff holds.
 
 Sizing (soft bounds): a track of ≤~12 in-scope files folds into a
-neighbor; >~20–25 in-scope files is a split candidate.
+neighbor; >~20–25 in-scope files is a split candidate. Size determines
+the split and whether marker commits are needed. It does not determine
+the change class or any gate.
 
-The user approves the proposed track split before implementation
-starts. Mid-flight changes to the split are re-presented to the user.
+The orchestrator owns the track split. No user approval gate applies
+to the split.
 
 All development is linear on the single working branch; each track is
 a contiguous commit range. Track numbering is append-only: completed
@@ -254,24 +316,38 @@ tracks never renumber, a replanned remainder gets new numbers, and
 abandoned planned tracks are struck through in the track table — their
 numbers are never reused.
 
+Every review dispatch carries a track intention block with four
+fields: target, scope boundary, deferred work, and acceptance
+condition.
+
 Per-track sequence:
 
 1. Implement the track, following the project's own engineering
-   guidelines for commit/test/push discipline.
+   guidelines for commit/test/push discipline. An implementation
+   commit body states what had to be implemented, then how the result
+   differs and why. It never restates the diff.
 2. MANDATORY agent code review of the cumulative track diff
    `git diff <prev-marker>..HEAD` — correctness, test coverage, style,
    API surface, documentation sync — composed per review-rules.md in
-   this directory.
-3. Fix findings as normal commits.
+   this directory. Skip this step only when the WHOLE change is
+   trivial. No track inside a medium or higher change is trivial.
+3. Fix findings and handle suggestions under review-rules.md §5. Record
+   each suggestion as a standalone entry in the log's Suggestions
+   section.
 4. MANDATORY user review: present the track summary and the track diff
    to the user, then loop on user feedback — landing fixes as normal
    commits — until the user explicitly approves. The agent waits for
    that approval; the marker commit certifies a fully user-reviewed
    track.
-5. Land the marker commit.
+5. Land the marker commit when the change has more than one track.
 6. Update the track's row in the track table (status, scope drift);
-   revise the planned-changes statement only if reality diverged from
-   it.
+   revise the high-level design only if reality diverged from it.
+
+### Internal review loops and escalations
+
+The adversarial and agent code review loops are internal to the
+orchestrator. The orchestrator asks the user only for a decision it
+cannot make. review-rules.md §6 owns the escalation list.
 
 ### Track table
 
@@ -280,7 +356,7 @@ display-only index of the split: track names, one-line scopes,
 statuses — never commit SHAs, and never the source of truth for track
 boundaries (marker commits are, see § Marker commits). It lives in the
 umbrella PR description when publishing is enabled and in the workflow
-log's Track table section when it is disabled.
+log's Track table section in both modes.
 
 ## Marker commits (source of truth for track boundaries)
 
@@ -309,7 +385,7 @@ Properties:
 - The track table is never an alternative source of truth for
   boundaries (constraints owned by § Track table).
 
-Single-track changes land no markers — the whole branch diff is the
+A change with one track lands no marker — the whole branch diff is the
 track.
 
 ## Rebase note
@@ -326,14 +402,25 @@ via a doctrine extension (the `doctrineExtraPath` key in the project's
 `slate.json`). A layered peer review supplements, never replaces, the
 mandatory per-track user review.
 
+## Migration
+
+A change whose high-level design was approved under the previous rules finishes
+under those rules. The new rules apply to a change started after the
+upgrade. When the previous document text is no longer installed, the
+log's recorded rule-set version and gate list are the authority.
+
 ## Layering richer workflows on top
 
 Richer internal planning and execution machinery — whatever agent
 tooling is in use — may be layered on top of this baseline, provided
-it satisfies the mandatory gates: a user design review before
-adversarial review, pre-implementation adversarial review, an agent
-code review per track, a mandatory user review per track, marker
-commits at track boundaries, and — when draft-PR publishing is
-enabled — the obligations of pr-publishing.md (umbrella draft PR
-before coding starts, user-performed merge). This document defines the
-baseline that applies regardless of the tooling.
+it satisfies the mandatory gates for the confirmed class: a
+high-level design for medium and above; high-level design presentation
+before adversarial review for complex and risky; high-level design
+presentation before implementation for medium and above; adversarial
+review of the high-level design
+for complex and risky; a research log for medium and above; agent code
+review for every track unless the whole change is trivial; mandatory
+user review of every track diff; marker commits at multi-track
+boundaries; and, when draft-PR publishing is enabled, the obligations
+of pr-publishing.md. This document defines the baseline that applies
+regardless of the tooling.

package/docs/writing-guidance.md

@@ -127,8 +127,11 @@ not test idea count. The reminder then includes this exact scope guard:
 
 `Exclude research logs, worker task text, and the project's own agent instruction file.`
 
-This guard prevents the five requirements from applying to those
-excluded artifacts.
+This guard is a coarse summary wherever Slate renders it, including the
+doctrine rule and the reminder. The summary names research logs as excluded.
+When `writing.check` is true, the high-level design remains governed even
+while it lives inside a research log. This document is the authority on the
+precise scope of every rendering.
 
 These requirements are not mechanical checker findings. The shipped
 checker has no rule for idioms or bare-reference openers. It also has
@@ -441,4 +444,6 @@ These are settled decisions. Read them as scope, not as a backlog.
   review comments, release notes and messages to the user. Research
   logs, worker task text and this repository's own agent instruction
   file are excluded, because a dense exact register serves them
-  better.
+  better. When a project sets `writing.check` to true, its high-level
+  design is governed prose even while it lives inside an otherwise
+  excluded research log.

package/extension/index.ts

@@ -35,7 +35,7 @@
  *     "contextBudget": 256000, "orchestratorModeDefault": true,
  *     "orchestratorPromptDocs": ["docs/orchestrator-guidelines.md"],
  *     "workerPromptDocs": ["docs/thread-guidelines.md"],
- *     "workflow": { "draftPRs": false },
+ *     "workflow": { "draftPRs": false, "followUpIssues": false },
  *     "modelFailover": { "provider/id": "provider/id" },
  *     "preserveGlobalModelDefault": true,
  *     "doctrineExtraPath": "docs/project-doctrine.md",
@@ -74,6 +74,7 @@ import {
 	sanitizeCacheKeyEnabled,
 	sanitizeCacheKeyShards,
 	sanitizeEpisodeModel,
+	sanitizeWorkflowConfig,
 	SlateStore,
 	type SlateConfig,
 } from "./state.ts";
@@ -205,6 +206,7 @@ export default function (pi: ExtensionAPI) {
 		// and reported itself as a configuration fault.
 		showRouterWarnings = config.router.showWarnings === true;
 		config.writing = sanitizeWritingConfig(config.writing, warn);
+		config.workflow = sanitizeWorkflowConfig(config.workflow, warn);
 		// episodeModel too (RG20): an unusable value falls back to the built-in
 		// compressor, and until this ran it did so without saying anything at all.
 		config.episodeModel = sanitizeEpisodeModel(config.episodeModel, warn);

package/extension/mode.ts

@@ -460,6 +460,9 @@ function buildDoctrine(
    publishing mechanics are in ${PR_PUBLISHING_DOC}.`
 			: `Durable workflow records anchor in the retained repo-root workflow
    log per the workflow doc.`;
+	const followUpTail = trusted && config.workflow?.followUpIssues === true
+		? "\n   After review, ask the user which review suggestions become tracker issues."
+		: "";
 	const perspectives = config.reviewPerspectivesPath;
 	const rule9Tail =
 		trusted && typeof perspectives === "string" && perspectives && existsSync(resolve(cwd, perspectives))
@@ -484,7 +487,9 @@ threads execute. Rules:
    With acting off, omit it for no permission or supply it for a reported choice. \`[]\`
    refuses a restart and preserves the live transcript. A non-empty list of existing
    episode ids permits a restart and seeds the new thread. Slate restarts only when
-   cheaper. Continue the successor. Details: ${THREAD_CACHE_COST_DOC}
+   cheaper. A blanket refusal of a thread restart has a price. Refuse only when the
+   next action depends on context from the previous action that the thread's episodes
+   do not carry. Continue the successor. Details: ${THREAD_CACHE_COST_DOC}
 4. Compose context by reference: pass prior episode ids in \`context\` instead
    of restating their content.
 5. Your read-only tools (read/grep/find/ls) are for cheap orientation only;
@@ -492,16 +497,18 @@ threads execute. Rules:
 6. After every episode, update your strategy. Episodes marked STATUS: FAILED
    require adaptation, not blind retry.
 7. Keep your own messages strategic: goals, task routing, synthesis.
-8. Repository changes follow the slate track-based workflow — read
-   ${TRACK_WORKFLOW_DOC}
-   (skip the read if it is already in your context). Before the FIRST
-   dispatch that modifies files, confirm the pre-implementation gates ran
-   (user design review, adversarial review, user-approved scope).
+8. Scale change gates by class: trivial, medium, complex, or risky. The
+   orchestrator owns the track split. For repository changes, read
+   ${TRACK_WORKFLOW_DOC} (skip the read if it is already in your context). Above trivial, keep a research log. Every track diff requires
+   user review. Before the first file-modifying dispatch, confirm the user confirmed
+   the class and all required pre-implementation gates ran. Medium and above require
+   user-approved design. Complex and risky then require adversarial design review,
+   then final user approval.
    ${rule8Tail}
 9. Every non-trivial change gets reviewed before it is declared done.
    Before dispatching review threads, read
    ${REVIEW_RULES_DOC}
-   (skip the read if it is already in your context) and follow it.${rule9Tail}
+   (skip the read if it is already in your context) and follow it.${rule9Tail}${followUpTail}
 10. The design principles behind this architecture are documented in
    ${DESIGN_PRINCIPLES_DOC}.
    Read that file only when you must reason about slate itself (explaining

package/extension/state.ts

@@ -847,6 +847,52 @@ export interface ThreadChoiceConfig {
 	act?: boolean;
 }
 
+/** Optional raw workflow publishing and follow-up issue controls. */
+export interface WorkflowConfig {
+	draftPRs?: boolean;
+	followUpIssues?: boolean;
+}
+
+/** Sanitized workflow shape. draftPRs stays unvalidated until issue 164 resolves it. */
+export interface SanitizedWorkflowConfig {
+	draftPRs?: unknown;
+	followUpIssues: boolean;
+}
+
+/** Display a rejected workflow value without letting serialization abort session startup. */
+function quotedWorkflowValue(value: unknown): string {
+	let text: string | undefined;
+	try {
+		text = JSON.stringify(value);
+	} catch {
+		text = undefined;
+	}
+	if (text === undefined) {
+		try {
+			text = String(value);
+		} catch {
+			text = `[unprintable ${typeof value}]`;
+		}
+	}
+	return sanitizeForNotify(text);
+}
+
+/** Validate the follow-up issue switch while preserving an own draft publishing value. */
+export function sanitizeWorkflowConfig(raw: unknown, warn: (msg: string) => void): SanitizedWorkflowConfig {
+	if (raw === undefined) return { followUpIssues: false };
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { followUpIssues: false };
+	const value = raw as { draftPRs?: unknown; followUpIssues?: unknown };
+	const hasOwn = (key: "draftPRs" | "followUpIssues") => Object.prototype.hasOwnProperty.call(value, key);
+	const draftPRs = hasOwn("draftPRs") ? { draftPRs: value.draftPRs } : {};
+	const candidate = hasOwn("followUpIssues") ? value.followUpIssues : undefined;
+	if (candidate === undefined) return { ...draftPRs, followUpIssues: false };
+	if (typeof candidate === "boolean") return { ...draftPRs, followUpIssues: candidate };
+	warn(
+		`slate: ignoring workflow.followUpIssues ${quotedWorkflowValue(candidate)}. Expected true or false. Slate uses false.`,
+	);
+	return { ...draftPRs, followUpIssues: false };
+}
+
 /** Optional writing checks and context-cadenced reminders. */
 export interface WritingConfig {
 	check?: boolean;
@@ -866,7 +912,7 @@ export interface SlateConfig {
 	orchestratorModeDefault?: boolean; // seed orchestrator mode ON for fresh interactive sessions (unsaved until first real mutation)
 	orchestratorPromptDocs?: string[]; // role-guideline docs appended to the orchestrator prompt (cwd-relative paths, default none)
 	workerPromptDocs?: string[]; // role-guideline docs appended to worker system prompts (cwd-relative paths, default none)
-	workflow?: { draftPRs?: boolean }; // draftPRs: umbrella draft PRs are part of the pre-implementation gates (default false)
+	workflow?: WorkflowConfig | SanitizedWorkflowConfig; // raw or session-sanitized workflow controls (both default false)
 	modelFailover?: Record<string, string>; // model→model failover map ("provider/id" → "provider/id"); empty/absent = feature off
 	preserveGlobalModelDefault?: boolean; // restore the user's GLOBAL pi model defaults (defaultProvider/defaultModel/defaultThinkingLevel) after a slate-initiated model switch — failover and handoff adoption (default true; only an explicit false disables it) — see model-default.ts
 	doctrineExtraPath?: string; // cwd-relative markdown appended to the orchestrator doctrine (project-doctrine section)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytdb-slate",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Slate: thread-weaving orchestration for the pi coding agent — bounded worker actions, compressed episodes, mandatory research/design/adversarial/track review workflow, configurable model failover, and orchestrator context-budget handoff.",
   "license": "Apache-2.0",
   "repository": {