ytdb-slate 0.6.0 → 0.6.1

package/README.md

@@ -69,6 +69,8 @@ The option has prompt cost. Each orchestrator system prompt contains the doctrin
 
 The shipped CLI checks plain files, JSONL records, and unified diffs. See [`docs/writing-guidance.md`](docs/writing-guidance.md) for its rules, limits, output, and command examples.
 
+Set `writing.remind` to `true` to add context-paced reminders after eligible tool results. Context-paced means Slate waits for configured context growth between reminders. The reminders are hidden from the normal TUI. They repeat five writing requirements and the scope exclusion before the next assistant response. This option remains off unless `writing.check` is also `true`.
+
 ## Install
 
 Install into a project (pinned, project-scoped — recorded in `.pi/settings.json`):
@@ -95,6 +97,8 @@ Optional config file: `slate.json` in the project's pi config dir (`.pi/slate.js
 | `workerPromptDocs` | string[] | `[]` | Project markdown files whose **contents** are appended to every worker-thread system prompt. |
 | `workflow.draftPRs` | boolean | `false` | Enable umbrella draft-PR publishing for tracks. |
 | `writing.check` | boolean | `false` | Add the writing doctrine rule, per-turn status, and worker guidance. An absent option is silently off. A malformed `writing` value, or a non-boolean `check` value, warns and defaults to off. Unknown `writing` keys warn and are ignored. See [`docs/writing-guidance.md`](docs/writing-guidance.md). |
+| `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). |
 | `doctrineExtraPath` | string | — | Project markdown whose **content** is appended to the orchestrator doctrine (project-specific workflow additions). |
 | `reviewPerspectivesPath` | string | — | Project review charters, each declaring its own finding-ID prefix. The doctrine references this **path**; the orchestrator reads the file alongside the shipped review rules. |
 | `modelFailover` | object (string → string) | — (empty, failover off) | Map of `provider/id` → equal-quality alternative model; on a model API failure the affected site retries once on the mapped model (worker/orchestrator sites only after pi's own retries are exhausted; episode compression has no pi retry loop). Read once at session start — see [`docs/model-failover.md`](docs/model-failover.md). |
@@ -112,7 +116,11 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
   "orchestratorPromptDocs": ["docs/agents/orchestrator-guidelines.md"],
   "workerPromptDocs": ["docs/agents/thread-guidelines.md"],
   "workflow": { "draftPRs": true },
-  "writing": { "check": true },
+  "writing": {
+    "check": true,
+    "remind": false,
+    "remindPercent": 10
+  },
   "doctrineExtraPath": "docs/agents/workflow-additions.md",
   "reviewPerspectivesPath": "docs/agents/review-perspectives.md",
   "modelFailover": { "anthropic/claude-sonnet-5": "openai/gpt-5.2" },
@@ -120,6 +128,8 @@ Example `.pi/slate.json` (the `docs/agents/...` paths are placeholders — point
 }
 ```
 
+Older Slate releases warn about these reminder keys and ignore them. Use a Slate release whose documentation includes these keys.
+
 > **Silent skip:** the project-file keys fail silently — no error is shown. For the content-injected keys (`orchestratorPromptDocs`, `workerPromptDocs`, `doctrineExtraPath`) a missing, unreadable, or empty file is skipped and nothing is injected. For `reviewPerspectivesPath` the pointer is omitted only when the file is missing — the file is not read at injection time, so an unreadable or empty file is still cited. Verify your paths after copying the example.
 
 **Worker extensions (`workerExtensions`).** By default worker threads load no extensions. This key is a list of regex patterns that select extensions the **host session has already loaded** and load them into every worker too. Each pattern is matched **unanchored** (unlike `contextBudget.overrides`, which is anchored) against a load unit's recorded source spec (e.g. `npm:pi-web-search@1.3.1`), its load-unit path, or the entry path of any tool that unit contributes, so a bare package name matches:

package/docs/context-budget.md

@@ -108,6 +108,32 @@ Rationale: the clamp guarantees the pause fires before pi's
 auto-compaction and leaves room to write the handoff brief; the
 half-window floor keeps small-window models usable.
 
+## Writing-reminder cadence
+
+The effective budget also sets the optional hidden writing-reminder cadence.
+When `writing.check` and `writing.remind` are both true, Slate computes:
+
+```
+interval = max(8192, floor(effectiveBudget × remindPercent / 100))
+```
+
+`remindPercent` defaults to 10 and accepts a finite value in `(0, 100]`. The
+context-window clamp therefore shortens the cadence on a model whose configured
+budget does not fit. Slate checks the cadence after tool results. One reminder
+slot can fire after each assistant response.
+
+A successful handoff adoption sets `forceNext`. The next eligible tool result
+then bypasses token cadence and missing usage. It does not bypass trust,
+orchestrator mode, `writing.check`, `writing.remind`, or pause gates. Slate
+commits the cadence mark only when pi starts delivery of the custom message.
+
+The current hidden message is 320 ASCII characters, including its `[slate]`
+header, five reminder requirements, blank separator, and scope exclusion. That
+is about 80 tokens at four characters per token. This count is for the exact
+rendered production string, without JSONL framing or provider-role overhead. The
+message enters conversation context only when a reminder fires. Later requests
+resend it with the rest of the conversation.
+
 ## Compaction policy
 
 In orchestrator mode, for budget-driven configs only: a
@@ -150,34 +176,36 @@ construction and makes the arithmetic one multiplication:
 `doctrine-budget` in `verification/resolver-checks.mjs` is the
 definition of record for this convention and its enforced bounds.
 This table is a measured snapshot, not a second authority. It uses
-the same real shipped-profile fixture as that check; the six-model
-rows use the six configured models in this repository's documented
-example. Every row states its full basis, because router state,
-model count, `draftPRs`, and `writing.check` each move the number:
+the same shipped-profile fixture as that check. The six-model rows
+use the six models in this repository's `.pi/slate.json`. Every row
+states its full basis, because router state, model count, `draftPRs`,
+and `writing.check` each move the number. Rows with the same fixture
+and basis must agree with `verification/README.md`. A different basis
+must be named instead of presented as the same measurement:
 
 | router | models | `draftPRs` | `writing.check` | paths | portable | lines |
 | --- | --- | --- | --- | --- | --- | --- |
 | off | — | off | off | 3 | 1,929 | 38 |
-| off | — | off | on | 4 | 2,683 | 53 |
+| off | — | off | on | 4 | 2,999 | 60 |
 | off | — | on | off | 4 | 1,948 | 38 |
-| off | — | on | on | 5 | 2,702 | 53 |
-| on | 6 configured | off | off | 4 | 3,879 | 58 |
-| on | 6 configured | off | on | 5 | 4,633 | 73 |
-| on | 6 configured | on | off | 5 | 3,898 | 58 |
-| on | 6 configured | on | on | 6 | 4,652 | 73 |
+| off | — | on | on | 5 | 3,018 | 60 |
+| on | `.pi/slate.json` six | off | off | 4 | 3,879 | 58 |
+| on | `.pi/slate.json` six | off | on | 5 | 4,949 | 80 |
+| on | `.pi/slate.json` six | on | off | 5 | 3,898 | 58 |
+| on | `.pi/slate.json` six | on | on | 6 | 4,968 | 80 |
 | on | all 9 shipped | off | off | 4 | 4,434 | 61 |
-| on | all 9 shipped | off | on | 5 | 5,188 | 76 |
+| on | all 9 shipped | off | on | 5 | 5,504 | 83 |
 | on | all 9 shipped | on | off | 5 | 4,453 | 61 |
-| on | all 9 shipped | on | on | 6 | 5,207 | 76 |
+| on | all 9 shipped | on | on | 6 | 5,523 | 83 |
 
 An untrusted project reads the first row whatever its `slate.json`
 says: no project config is loaded, so no optional rule renders. Line
 counts do not vary with the install path. Enabling `draftPRs` costs
 19 portable characters plus one embedded path. Enabling
-`writing.check` costs 754 portable characters, adds 15 lines to the
-whole doctrine, and adds one embedded path; considered alone, the
-writing rule is 754 portable characters / 16 lines because its
-leading newline becomes the separator when appended.
+`writing.check` costs 1,070 portable characters, adds 22 lines to the
+whole doctrine, and adds one embedded path. Considered alone, the
+writing rule is 1,070 portable characters / 23 lines. Its leading
+newline becomes the separator when appended.
 
 Two parts of the block grow with configuration rather than with the
 path:
@@ -191,20 +219,56 @@ path:
   legend adds a one-off clause per marker it has to explain, so
   growth is not only the sum of new rows.
 - The worker-extension rule grows per whitelisted extension and per
-  tool that extension contributes, so it has no fixed size; one
+  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. At four
-characters per token as a rough estimate (no tokenizer was run, and
-the routing table is denser than prose), the portable block ranges
-from about 482 tokens at the baseline to about 1,302 with all nine
-models, `draftPRs`, and writing enabled. That is close to half a
-percent of the default budget at the largest measured configuration,
-though it is re-sent on every request rather than paid once. It is
-listed here because it is context Slate itself puts in front of the
-model on every turn, and because it is the number to check before
-assuming the budget's headroom is all conversation.
+The table above isolates the shipped rules. Two representative bases include
+worker extensions and support verification decisions:
+
+| basis | models | worker extensions | paths | portable | lines | rough tokens |
+| --- | ---: | --- | ---: | ---: | ---: | ---: |
+| current `.pi/slate.json` dogfood config | 6 | real 2 units / 4 tools | 6 | 5,884 | 90 | ≈1,471 |
+| stable maximal fixture | 9 | synthetic 2 units / 4 tools, every rendered field at its cap | 6 | 6,870 | 93 | ≈1,718 |
+
+The dogfood row uses `workflow.draftPRs: true`, `writing.check: true`, and the
+six models in `.pi/slate.json`. Its extension basis is
+`pi-smart-fetch@0.3.12` plus `pi-web-search@1.3.1`. Those packages resolve to two
+units and four tools. Their worker-extension rule is 916 portable characters /
+11 lines. Raw size remains symbolic: `portable + 6 × length(installed docs
+directory)`. No maintainer checkout path belongs in this shipped document.
+
+The stable maximal row uses all nine shipped profiles, draft PRs, and writing.
+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.
+
+Those are the renderer caps. The fixture uses safe ASCII letters. It is
+independent of installed extension labels, descriptions, versions and other
+prose. The worker rule measures 1,347 characters against its 1,600-character
+verification budget.
+
+`doctrine-budget` caps that representative maximal doctrine at 7,200 portable
+characters. The measured 6,870 leaves 330 characters, or 4.6 percent of the
+7,200-character bound. A positive control adds one capped tool
+and three copies of the largest measured model row. It measures 7,634 portable
+characters and exceeds the bound by 434. These figures are verification budgets,
+never runtime limits. Arbitrary user extension rosters can exceed them.
+
+The exact values are maintenance tripwires. A deliberate doctrine wording,
+requirement roster, renderer cap, or fixture change requires a fresh render
+through `doctrine-budget`. Update its exact expectations and every published
+figure in the same commit. Keep the positive control steps unchanged unless the
+fixture design itself changes.
+
+Against a 256,000-token context budget, these blocks remain small. At four
+characters per token as a rough estimate, the shipped-rule table ranges from
+about 482 tokens to about 1,381 tokens. The current dogfood basis is about 1,471
+tokens. The representative maximum is about 1,718 tokens, or 0.67 percent of the
+default budget.
+
+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.
 
 ### Worker writing preamble
 
@@ -317,9 +381,8 @@ number.
   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.
+- The doctrine sizes above cover the stated fixtures only. A project that
+  injects `doctrineExtraPath` or `orchestratorPromptDocs` pays for those on top.
+  A larger worker-extension roster also adds context beyond the representative
+  fixtures. Slate imposes no runtime doctrine-size limit. This content simply
+  leaves less room under the context budget.

package/docs/writing-guidance.md

@@ -1,15 +1,14 @@
 # Writing guidance and the prose checker
 
-Slate ships one writing convention and one command that measures
-prose against a mechanical proxy for it. Both are opt-in: with
-`writing.check` absent or false nothing about them is loaded,
-rendered or paid for.
+Slate ships an optional writing convention and a command that measures
+prose against a mechanical proxy. With `writing.check` absent or false,
+Slate loads no writing guidance. The command remains available.
 
 This document is reference documentation, not workflow doctrine. It
 is the definition of record for the rule set, the severity classes,
-the command line and the caps. The always-loaded doctrine rule states
-the convention in a few lines and cites this file for everything
-else, so that a session pays for the detail only when it reads it.
+the command line and the caps. The enabled doctrine rule states the
+convention in a few lines and cites this file for everything else.
+A session pays for the detail only when it reads this file.
 
 ## What the checker is, and what it is not
 
@@ -52,25 +51,37 @@ accuracy, structure or completeness at all.
 
 ## Enabling it
 
-One boolean in the project's `.pi/slate.json`:
+Configure writing features in the project's `.pi/slate.json`:
 
 ```json
-{ "writing": { "check": true } }
+{
+  "writing": {
+    "check": true,
+    "remind": false,
+    "remindPercent": 10
+  }
+}
 ```
 
-The default is false. An absent `writing` key is silent. A malformed
-one warns once and leaves the feature off, as does a non-boolean
-`check`; unknown keys under `writing` warn and are ignored. The
-validator is `sanitizeWritingConfig` in `extension/writing.ts`.
+All three values are optional. `check` and `remind` default to false.
+`remindPercent` defaults to 10. `remind` is inert unless `check` is
+true.
 
-Slate reads project config only for a TRUSTED project. Both
-prompt-visible sites also re-check trust when they inject the doctrine
-rule or worker preamble. The worker check is defense in depth for a
-future direct call to `openWorkerSession`; the current config path is
-already gated in `extension/index.ts`. An untrusted project therefore
-behaves as if the switch were off, whatever its `slate.json` says.
+A malformed `writing` value warns once and uses all defaults. A
+non-boolean `check` or `remind` value warns and uses its default.
+Unknown keys under `writing` also warn and are ignored.
 
-The switch turns on three things and nothing else:
+`remindPercent` must be a finite number in `(0, 100]`. An invalid
+value warns and defaults to 10. The validator is
+`sanitizeWritingConfig` in `extension/writing.ts`.
+
+Slate reads project config only for a TRUSTED project. The doctrine,
+worker preamble, and reminder gates also check trust at their injection
+points. These checks provide defense in depth because
+`extension/index.ts` already gates the current config path. An
+untrusted project behaves as if the switches were off.
+
+The `check` switch turns on three things:
 
 1. **The doctrine rule.** One numbered rule is appended to the
    orchestrator's system prompt while orchestrator mode is on. It
@@ -80,26 +91,136 @@ The switch turns on three things and nothing else:
    preamble. With the switch off the preamble is byte-identical to
    its pre-feature text.
 3. **The turn status line.** In an interactive session, the Slate
-   status line gains a `writing <n>/<m>` counter: `m` turns of the
-   orchestrator's own prose were measured and `n` of them carried at
-   least one `fail` class match.
+   status line gains a `writing <n>/<m>` counter. `m` counts measured
+   prose turns. `n` counts turns with at least one `fail` finding.
+
+The separate `remind` switch adds a hidden, context-paced message.
+Context-paced means Slate waits for configured context growth between
+reminders. It works only while `check` remains on. The next section
+defines this channel and its gates.
+
+Running the command by hand needs no config. It is a plain Node
+command and works whether either switch is on.
+
+## Writing requirements and reminders
+
+The doctrine includes these six requirements in this order:
+
+- Avoid idioms.
+- Replace bare-reference openers with the subject they reference.
+- Explain each project-specific term at first use.
+- Define each abbreviation at first use.
+- Express one idea in each sentence.
+- Use one term for each concept.
+
+These project-authored summaries came from the investigation for
+[issue #96](https://github.com/JetBrains/ytdb-slate/issues/96). ASD-STE100
+informed that work. Slate copied no standard text or controlled
+vocabulary, and it claims no conformance.
+
+A reminder repeats five lines. It omits this doctrine-only line:
+
+`Express one idea in each sentence.`
+
+The sentence-length rules provide a nearby mechanical signal. They do
+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.
+
+These requirements are not mechanical checker findings. The shipped
+checker has no rule for idioms or bare-reference openers. It also has
+no rule for project-term explanations or abbreviation definitions.
+It cannot enforce one term per concept.
+
+After an eligible tool result, Slate queues a hidden custom message
+with active `steer`. The message has `display: false` and arrives
+before the next assistant response.
 
-Running the command by hand needs no config at all. It is a plain
-Node command and it works whether or not the switch is on.
+The normal UI has no reminder indicator. It does not appear in the
+normal TUI or tool panel. A tool-free round receives no reminder.
+
+To diagnose delivery, inspect the session JSONL through pi. A delivered
+reminder has entry type `custom_message`, `customType` set to
+`slate-writing-reminder`, and `display` set to false. It also enters
+later model context. This diagnostic does not depend on a stable
+session-file path.
+
+Every reminder gate must be open:
+
+- orchestrator mode is on
+- the project is trusted
+- `writing.check` and `writing.remind` are true
+- Slate is not paused
+- the context threshold is reached, or a handoff forces the next reminder
+- no reminder has been sent in the current assistant response round
+
+Slate permits at most one reminder for each assistant response round.
+Parallel tool results therefore cannot produce repeated reminders in
+one round.
+
+The interval is `remindPercent` of Slate's current effective context
+budget. Slate rounds down to whole tokens, then applies an 8,192-token
+floor. It applies no interval cap.
+
+The default interval is 10 percent. The configured range is greater
+than zero through 100, inclusive. The effective budget reflects the
+live model, configured budget, context window, and Slate's handoff
+headroom.
+
+The 8,192-token floor makes sufficiently small percentages equivalent.
+At 100 percent, normal cadence reaches its threshold at the effective
+pause boundary. These endpoints remain valid. A forced post-handoff
+reminder bypasses the cadence threshold.
+
+After a reminder, Slate marks the current context usage. Another
+reminder needs one full interval of growth. When context usage shrinks,
+Slate lowers the mark to the new usage before measuring growth again.
+
+A trusted handoff reloads the doctrine in the fresh session. It also
+forces a reminder after the first eligible tool result. This forced
+reminder does not need context usage or a reached threshold.
+
+A representative 256,000-token budget gives a 25,600-token default
+interval. This example only illustrates cadence. Slate has no
+controlled comparison or claim that reminders improve prose.
+
+## Keeping the requirement text synchronized
+
+`WRITING_REQUIREMENTS` and `WRITING_SCOPE_EXCLUSION` in
+`extension/writing-reminder.ts` export the authoritative wording.
+The complete six-line roster has three manual copies: this guide,
+AGENTS.md's roster, and resolver exact fixtures. The integration canary
+manually copies only the five reminder-eligible lines.
+
+The scope exclusion has three exact copies: this guide, resolver exact
+fixtures, and the integration canary. AGENTS.md carries equivalent
+scope prose, not an exact copy. All applicable copies must update in
+one commit.
+
+`extension/mode.ts` renders the authoritative exports directly. The
+shell harness reads expected text from canary evidence. Neither file
+holds a manual wording copy.
 
 ## What it costs when it is on
 
 The doctrine rule is part of every orchestrator system prompt, so its
 cost is paid on every turn. The worker addition is paid once per
-worker dispatch. `context-budget.md` defines the portable-character
-measure, records the whole-doctrine sizes and owns the size budget.
+worker dispatch. Each sent reminder also enters later model context.
+`context-budget.md` defines the portable-character measure. It records
+the whole-doctrine sizes and owns the size budget.
 
 An interactive session also runs the checker synchronously after each
 completed assistant message. The hook refuses text over 16 KiB and
 reports `writing skipped (message too large)`. This TUI bound is
-separate from the command's 1 MiB input cap. The hook is human-only
-telemetry: it does not change the model input, and a checker failure
-reports `writing unavailable` rather than failing the turn.
+separate from the command's 1 MiB input cap.
+
+The checker hook is human-only telemetry. It does not change model
+input. A checker failure reports `writing unavailable` instead of
+failing the turn. The optional reminder uses the separate model-visible
+channel described above.
 
 ## What counts as prose
 
@@ -312,8 +433,9 @@ These are settled decisions. Read them as scope, not as a backlog.
 - **No verdict.** No rule class is a defect by itself, and no clean
   run is a pass. `review-rules.md` owns the mapping from a match to a
   severity, and a reviewer owns the judgement.
-- **Not a gate.** The turn hook is telemetry. It returns nothing to
-  the model, changes no prompt, and cannot fail a turn.
+- **Not a gate.** The checker hook is telemetry. It changes no model
+  input and cannot fail a turn. The optional reminder is guidance,
+  not a checker verdict.
 - **Not universal.** The convention covers prose written for people:
   documents, README text, pull request and commit text, issues,
   review comments, release notes and messages to the user. Research

package/extension/handoff.ts

@@ -92,6 +92,7 @@ interface PendingHandoff {
 
 export interface SlateHandoffHooks {
 	startHandoff(ctx: ExtensionCommandContext, focus?: string): Promise<void>;
+	effectiveContextBudget(contextWindow: number, ctx: ExtensionContext): number | undefined;
 }
 
 function pendingFile(cwd: string): string {
@@ -224,6 +225,24 @@ function resolveBudgetTokens(budget: ContextBudgetObject | undefined, modelSpec:
 	return DEFAULT_CONTEXT_BUDGET_TOKENS;
 }
 
+/** Apply Slate's context-window clamp to one configured budget. */
+export function effectiveContextBudgetTokens(configured: number, contextWindow: number, reserveTokens: number): number {
+	return Math.min(
+		configured,
+		Math.max(contextWindow - reserveTokens - BRIEF_HEADROOM_TOKENS, Math.ceil(contextWindow / 2)),
+	);
+}
+
+/** Resolve one model's configured budget and apply the shared window clamp. */
+export function effectiveContextBudgetForModel(
+	budget: ContextBudgetObject | undefined,
+	modelSpec: string,
+	contextWindow: number,
+	reserveTokens: number,
+): number {
+	return effectiveContextBudgetTokens(resolveBudgetTokens(budget, modelSpec), contextWindow, reserveTokens);
+}
+
 /** Last assistant message text on the current branch (the handoff brief). */
 function lastAssistantText(ctx: ExtensionCommandContext): string {
 	let text = "";
@@ -315,6 +334,17 @@ export function registerSlateHandoff(
 		return cachedReserveTokens;
 	};
 
+	const effectiveContextBudget = (contextWindow: number, ctx: ExtensionContext): number | undefined => {
+		if (!ctx.model) return undefined;
+		const budget = getConfig().contextBudget;
+		return effectiveContextBudgetForModel(
+			typeof budget === "number" ? { tokens: budget } : budget,
+			`${ctx.model.provider}/${ctx.model.id}`,
+			contextWindow,
+			reserveTokens(ctx),
+		);
+	};
+
 	/** Handoff instructions shared by both pause sites (turn check + compaction intercept). */
 	const pauseInstructions = (headline: string) =>
 		[
@@ -357,15 +387,12 @@ export function registerSlateHandoff(
 				typeof budget === "number" ? { tokens: budget } : budget,
 				`${ctx.model.provider}/${ctx.model.id}`,
 			);
-			// Clamp to the window: the pause must fire BEFORE pi's compaction point
-			// (contextWindow − reserveTokens) with room to write the brief — but
-			// never below half the window, so a small-window model still gets a
-			// usable orchestrator instead of a near-zero effective budget.
-			// (usage.contextWindow > 0 is guaranteed: getContextUsage returns
-			// undefined when no window is known.)
-			const effective = Math.min(
-				configured,
-				Math.max(usage.contextWindow - reserveTokens(ctx) - BRIEF_HEADROOM_TOKENS, Math.ceil(usage.contextWindow / 2)),
+			// Use the same effective budget exposed to context-cadenced features.
+			const effective = effectiveContextBudgetForModel(
+				typeof budget === "number" ? { tokens: budget } : budget,
+				`${ctx.model.provider}/${ctx.model.id}`,
+				usage.contextWindow,
+				reserveTokens(ctx),
 			);
 			if (usage.tokens < effective) return;
 			const used = usage.tokens.toLocaleString("en-US");
@@ -472,6 +499,8 @@ export function registerSlateHandoff(
 			const matches = !!pending.parentSession && pending.parentSession === ctx.sessionManager.getHeader()?.parentSession;
 			if (!matches) return;
 			store.adoptSnapshot(pending.snapshot, ctx);
+			store.writingReminder.forceNext = true;
+			store.writingReminder.adoptedThisSessionStart = true;
 			store.paused = false;
 			store.save();
 			rmSync(file, { force: true });
@@ -686,5 +715,5 @@ export function registerSlateHandoff(
 		}
 	};
 
-	return { startHandoff };
+	return { startHandoff, effectiveContextBudget };
 }

package/extension/mode.ts

@@ -32,6 +32,20 @@ import {
 import { loadPromptDocs } from "./prompt-docs.ts";
 import { THINKING_LEVELS } from "./route.ts";
 import { orchestratorCostUsd, type SlateConfig, type SlateStore } from "./state.ts";
+import {
+	claimWritingReminder,
+	commitWritingReminder,
+	decideWritingReminder,
+	rearmWritingReminder,
+	renderWritingDoctrineRequirements,
+	renderWritingReminderMessage,
+	renderWritingScopeExclusion,
+	resetWritingReminderSession,
+	WRITING_REMINDER_CUSTOM_TYPE,
+	writingReminderDeliveryDetails,
+	writingReminderGateOpen,
+	writingReminderInterval,
+} from "./writing-reminder.ts";
 import { measureWritingTurn, type WritingChecker, type WritingCounters } from "./writing.ts";
 import type { WorkerExtensionSet, WorkerExtensionUnit } from "./worker-extensions.ts";
 
@@ -406,12 +420,14 @@ ${n}. Check all user-facing prose before delivery. Use short, active sentences a
    A sentence over 20 words warns. Shorten it when meaning stays clear.
 
    Do not use semicolons or contractions. Keep exact technical terms. The check
-   does not test vocabulary.
+   does not test vocabulary. Follow these writing requirements:
+
+${renderWritingDoctrineRequirements("   ")}
 
-   Apply it to README text, documentation, code comments, and pull request text.
-   Apply it to commit bodies, issues, review comments, release notes, and messages
-   to the user. Exclude research logs, worker task text, and the project's own agent
-   instruction file.
+   Apply these requirements to README text, documentation, code comments, and
+   pull request text. Apply them to commit bodies, issues, review comments,
+   release notes, and messages to the user.
+${renderWritingScopeExclusion("   ")}
 
    Rules, limits and the checker command:
    ${WRITING_GUIDANCE_DOC}
@@ -662,6 +678,71 @@ export function registerSlateMode(
 		return { systemPrompt: event.systemPrompt + parts.join("") };
 	});
 
+	// Each assistant response opens one reminder slot for its following tools.
+	// A prior queue claim that never started delivery is retryable in this slot.
+	pi.on("message_end", (event) => {
+		if (event.message.role === "assistant") {
+			Object.assign(store.writingReminder, rearmWritingReminder(store.writingReminder));
+		}
+	});
+
+	// message_start proves that pi began delivering our custom steer.
+	pi.on("message_start", (event) => {
+		if (event.message.role === "custom" && event.message.customType === WRITING_REMINDER_CUSTOM_TYPE) {
+			Object.assign(
+				store.writingReminder,
+				commitWritingReminder(store.writingReminder, event.message.details, event.message.content),
+			);
+		}
+	});
+
+	// Claim the round before sendMessage can synchronously trigger other hooks.
+	pi.on("tool_result", (_event, ctx) => {
+		const config = getConfig().writing;
+		const runtime = store.writingReminder;
+		if (
+			!writingReminderGateOpen(
+				{
+					orchestratorMode: store.orchestratorMode,
+					trusted: ctx.isProjectTrusted(),
+					check: config?.check === true,
+					remind: config?.remind === true,
+					paused: store.paused,
+				},
+				runtime.sentThisRound,
+			)
+		) {
+			return;
+		}
+		const usage = ctx.getContextUsage();
+		const effectiveBudget = usage ? hooks.effectiveContextBudget(usage.contextWindow, ctx) : undefined;
+		const interval =
+			effectiveBudget === undefined ? undefined : writingReminderInterval(effectiveBudget, config?.remindPercent ?? 10);
+		const decision = decideWritingReminder(runtime.markTokens, usage?.tokens, interval, runtime.forceNext);
+		const reminderContent = renderWritingReminderMessage();
+		Object.assign(runtime, claimWritingReminder(runtime, decision, reminderContent));
+		if (!decision.send) return;
+		const deliveryId = runtime.pending?.deliveryId;
+		if (deliveryId === undefined) {
+			Object.assign(runtime, rearmWritingReminder(runtime));
+			return;
+		}
+		try {
+			pi.sendMessage(
+				{
+					customType: WRITING_REMINDER_CUSTOM_TYPE,
+					content: reminderContent,
+					display: false,
+					details: writingReminderDeliveryDetails(deliveryId),
+				},
+				{ deliverAs: "steer" },
+			);
+		} catch {
+			// A synchronous queue failure leaves force and cadence retryable.
+			if (runtime.pending) Object.assign(runtime, rearmWritingReminder(runtime));
+		}
+	});
+
 	// The writing checker reads only the completed assistant message from
 	// turn_end. It returns no hook result, so it is human-only telemetry and
 	// cannot alter what the model receives.
@@ -704,9 +785,11 @@ export function registerSlateMode(
 		writingCounters.findingTurns = 0;
 		writingCheckerPromise = undefined;
 		writingStatus = "fresh";
-		// store.restore() (index.ts) and pending-handoff adoption (handoff.ts)
-		// ran before this handler in registration order; re-apply the persisted
-		// mode to the fresh runtime.
+		Object.assign(store.writingReminder, resetWritingReminderSession(store.writingReminder));
+		// Preserve force only when the earlier handoff handler marked this cycle.
+		// The reset consumes that marker, so a later generic session_start clears
+		// stale force. Registration order remains index restore, handoff, then mode.
+		// Re-apply the persisted mode to the fresh runtime.
 		//
 		// Config-driven default: seed orchestrator mode ON for a genuinely FRESH
 		// interactive session. Running AFTER restore and handoff adoption means

package/extension/state.ts

@@ -18,6 +18,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 // below on why that matters).
 import type { ThinkingLevel } from "./model-profiles.ts";
 import { sanitizeForNotify } from "./notify.ts";
+import { createWritingReminderRuntime, type WritingReminderRuntime } from "./writing-reminder.ts";
 
 /**
  * ADDITIVE TOLERANCE (the persistence model has no migration hook): the
@@ -481,9 +482,11 @@ export interface RouterConfig {
 	allowUnmeasuredEffort?: boolean;
 }
 
-/** Optional writing checks. Off unless `check` is explicitly true. */
+/** Optional writing checks and context-cadenced reminders. */
 export interface WritingConfig {
 	check?: boolean;
+	remind?: boolean;
+	remindPercent?: number;
 }
 
 export interface SlateConfig {
@@ -519,6 +522,8 @@ export class SlateStore {
 	workerCostUsd = 0;
 	/** Orchestrator spend inherited from ancestor sessions across handoffs. */
 	carriedCostUsd = 0;
+	/** Session-instance reminder state. It is never part of a snapshot. */
+	readonly writingReminder: WritingReminderRuntime = createWritingReminderRuntime();
 	/** Invoked after every save/restore; used by mode.ts to refresh the widget. */
 	onDidChange?: () => void;
 

package/extension/writing-reminder.ts

@@ -0,0 +1,184 @@
+/** One writing requirement and the channels that render it. */
+export interface WritingRequirement {
+	text: string;
+	reminder: boolean;
+}
+
+/** The ordered source of truth for writing doctrine and reminders. */
+export const WRITING_REQUIREMENTS: readonly WritingRequirement[] = Object.freeze([
+	Object.freeze({ text: "Avoid idioms.", reminder: true }),
+	Object.freeze({ text: "Replace bare-reference openers with the subject they reference.", reminder: true }),
+	Object.freeze({ text: "Explain each project-specific term at first use.", reminder: true }),
+	Object.freeze({ text: "Define each abbreviation at first use.", reminder: true }),
+	Object.freeze({ text: "Express one idea in each sentence.", reminder: false }),
+	Object.freeze({ text: "Use one term for each concept.", reminder: true }),
+]);
+
+/** The shared exclusion guard for doctrine and hidden reminders. */
+export const WRITING_SCOPE_EXCLUSION =
+	"Exclude research logs, worker task text, and the project's own agent instruction file.";
+
+export const WRITING_REMINDER_CUSTOM_TYPE = "slate-writing-reminder";
+
+export interface WritingReminderDeliveryDetails {
+	deliveryId: number;
+}
+
+export interface PendingWritingReminder {
+	deliveryId: number;
+	nextMarkTokens: number;
+	consumeForce: boolean;
+	expectedContent: string;
+}
+
+export interface WritingReminderRuntime {
+	markTokens: number;
+	sentThisRound: boolean;
+	forceNext: boolean;
+	deliverySequence: number;
+	adoptedThisSessionStart: boolean;
+	pending?: PendingWritingReminder;
+}
+
+export interface WritingReminderGate {
+	orchestratorMode: boolean;
+	trusted: boolean;
+	check: boolean;
+	remind: boolean;
+	paused: boolean;
+}
+
+export interface WritingReminderDecision {
+	send: boolean;
+	nextMarkTokens: number;
+}
+
+export function createWritingReminderRuntime(): WritingReminderRuntime {
+	return {
+		markTokens: 0,
+		sentThisRound: false,
+		forceNext: false,
+		deliverySequence: 0,
+		adoptedThisSessionStart: false,
+	};
+}
+
+/** Convert a configured percentage of the effective budget to a token cadence. */
+export function writingReminderInterval(effectiveBudgetTokens: number, remindPercent: number): number {
+	return Math.max(8_192, Math.floor((effectiveBudgetTokens * remindPercent) / 100));
+}
+
+/** Decide whether policy gates permit a reminder before checking its cadence. */
+export function writingReminderGateOpen(gate: WritingReminderGate, sentThisRound: boolean): boolean {
+	return gate.orchestratorMode && gate.trusted && gate.check && gate.remind && !gate.paused && !sentThisRound;
+}
+
+/**
+ * Decide one cadence step. A smaller trustworthy usage lowers the mark.
+ * Force sends without usage and leaves the mark unchanged.
+ */
+export function decideWritingReminder(
+	markTokens: number,
+	usageTokens: number | null | undefined,
+	intervalTokens: number | undefined,
+	forceNext: boolean,
+): WritingReminderDecision {
+	const trustworthyUsage =
+		typeof usageTokens === "number" && Number.isFinite(usageTokens) && usageTokens >= 0 ? usageTokens : undefined;
+	const loweredMark = trustworthyUsage === undefined ? markTokens : Math.min(markTokens, trustworthyUsage);
+	if (forceNext) return { send: true, nextMarkTokens: trustworthyUsage ?? loweredMark };
+	if (trustworthyUsage === undefined || intervalTokens === undefined) {
+		return { send: false, nextMarkTokens: loweredMark };
+	}
+	const send = trustworthyUsage >= loweredMark + intervalTokens;
+	return { send, nextMarkTokens: send ? trustworthyUsage : loweredMark };
+}
+
+/** Claim a round before queueing. Cadence and force remain uncommitted. */
+export function claimWritingReminder(
+	runtime: WritingReminderRuntime,
+	decision: WritingReminderDecision,
+	expectedContent: string,
+): WritingReminderRuntime {
+	if (!decision.send) return { ...runtime, markTokens: decision.nextMarkTokens };
+	const deliveryId = runtime.deliverySequence + 1;
+	return {
+		...runtime,
+		sentThisRound: true,
+		deliverySequence: deliveryId,
+		pending: { deliveryId, nextMarkTokens: decision.nextMarkTokens, consumeForce: runtime.forceNext, expectedContent },
+	};
+}
+
+export function writingReminderDeliveryDetails(deliveryId: number): WritingReminderDeliveryDetails {
+	return { deliveryId };
+}
+
+/** Match pi's hidden details and exact content to the current queue claim. */
+export function writingReminderDeliveryMatches(
+	runtime: WritingReminderRuntime,
+	details: unknown,
+	content: unknown,
+): boolean {
+	if (!runtime.pending || typeof details !== "object" || details === null) return false;
+	try {
+		return (
+			(details as { deliveryId?: unknown }).deliveryId === runtime.pending.deliveryId &&
+			content === runtime.pending.expectedContent
+		);
+	} catch {
+		return false;
+	}
+}
+
+/** Commit cadence and force when pi starts the matching custom message. */
+export function commitWritingReminder(
+	runtime: WritingReminderRuntime,
+	details: unknown,
+	content: unknown,
+): WritingReminderRuntime {
+	if (!writingReminderDeliveryMatches(runtime, details, content)) return runtime;
+	return {
+		...runtime,
+		markTokens: runtime.pending?.nextMarkTokens ?? runtime.markTokens,
+		forceNext: runtime.pending?.consumeForce ? false : runtime.forceNext,
+		pending: undefined,
+	};
+}
+
+/** Open the next round and discard any queue claim that never started delivery. */
+export function rearmWritingReminder(runtime: WritingReminderRuntime): WritingReminderRuntime {
+	return { ...runtime, sentThisRound: false, pending: undefined };
+}
+
+/** Reset session cadence and preserve force only for this cycle's adoption. */
+export function resetWritingReminderSession(runtime: WritingReminderRuntime): WritingReminderRuntime {
+	return {
+		markTokens: 0,
+		sentThisRound: false,
+		forceNext: runtime.adoptedThisSessionStart && runtime.forceNext,
+		deliverySequence: runtime.deliverySequence,
+		adoptedThisSessionStart: false,
+		pending: undefined,
+	};
+}
+
+export function renderWritingDoctrineRequirements(indent = ""): string {
+	return WRITING_REQUIREMENTS.map((requirement) => `${indent}- ${requirement.text}`).join("\n");
+}
+
+export function renderWritingScopeExclusion(indent = ""): string {
+	return `${indent}${WRITING_SCOPE_EXCLUSION}`;
+}
+
+export function renderWritingReminder(): string {
+	const requirements = WRITING_REQUIREMENTS.filter((requirement) => requirement.reminder)
+		.map((requirement) => `- ${requirement.text}`)
+		.join("\n");
+	return `${requirements}\n\n${WRITING_SCOPE_EXCLUSION}`;
+}
+
+/** The complete hidden custom-message content. */
+export function renderWritingReminderMessage(): string {
+	return `[slate] Writing reminder:\n${renderWritingReminder()}`;
+}

package/extension/writing.ts

@@ -71,21 +71,17 @@ export function measureWritingTurn(
 }
 
 /** The known `writing` keys. Report anything else as a likely typo. */
-const WRITING_KEYS = ["check"];
+const WRITING_KEYS = ["check", "remind", "remindPercent"];
 
-/**
- * Validate the raw `writing` config value. An absent value silently returns the
- * default. A wrong shape warns once and returns the default. Unknown keys and a
- * wrong-typed `check` value warn, while valid input is copied into a new object.
- */
+/** Validate the raw `writing` config value and apply independent defaults. */
 export function sanitizeWritingConfig(raw: unknown, warn: (msg: string) => void): Required<WritingConfig> {
-	const defaults: Required<WritingConfig> = { check: false };
+	const defaults: Required<WritingConfig> = { check: false, remind: false, remindPercent: 10 };
 	if (raw === undefined) return defaults;
 	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
 		warn('slate: ignoring writing — expected an object like { "check": true }');
 		return defaults;
 	}
-	const value = raw as { check?: unknown };
+	const value = raw as { check?: unknown; remind?: unknown; remindPercent?: unknown };
 
 	const unknownKeys = Object.keys(value).filter((key) => !WRITING_KEYS.includes(key));
 	if (unknownKeys.length > 0) {
@@ -96,22 +92,36 @@ export function sanitizeWritingConfig(raw: unknown, warn: (msg: string) => void)
 		);
 	}
 
-	let rawCheck: unknown;
-	if (Object.prototype.hasOwnProperty.call(value, "check")) {
+	const read = (key: keyof typeof value): unknown => {
+		if (!Object.prototype.hasOwnProperty.call(value, key)) return undefined;
 		try {
-			rawCheck = value.check;
+			return value[key];
 		} catch {
-			warn("slate: ignoring writing.check — could not read the value (defaulting to false)");
+			const fallback = key === "remindPercent" ? 10 : false;
+			warn(`slate: ignoring writing.${key} — could not read the value (defaulting to ${fallback})`);
+			return undefined;
 		}
-	}
-	let check = false;
-	if (rawCheck !== undefined) {
-		if (typeof rawCheck !== "boolean") {
-			warn("slate: ignoring writing.check — expected true or false (defaulting to false)");
+	};
+	const booleanValue = (key: "check" | "remind", fallback: boolean): boolean => {
+		const candidate = read(key);
+		if (candidate === undefined) return fallback;
+		if (typeof candidate === "boolean") return candidate;
+		warn(`slate: ignoring writing.${key} — expected true or false (defaulting to ${fallback})`);
+		return fallback;
+	};
+
+	const check = booleanValue("check", defaults.check);
+	const requestedRemind = booleanValue("remind", defaults.remind);
+	const rawPercent = read("remindPercent");
+	let remindPercent = defaults.remindPercent;
+	if (rawPercent !== undefined) {
+		if (typeof rawPercent === "number" && Number.isFinite(rawPercent) && rawPercent > 0 && rawPercent <= 100) {
+			remindPercent = rawPercent;
 		} else {
-			check = rawCheck;
+			warn("slate: ignoring writing.remindPercent — expected a finite number in (0, 100] (defaulting to 10)");
 		}
 	}
 
-	return { check };
+	// A reminder without the checker is disabled at the config boundary.
+	return { check, remind: check && requestedRemind, remindPercent };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ytdb-slate",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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": {