@mgiles/perk 1.0.1 → 2.0.0

package/extension/worker/worker.ts

@@ -12,24 +12,33 @@
 // /plan-body materialization, `run_id` mint) is the cold-door/runner's job and is a PREPARED-
 // WORKTREE input (audit Gap 7): the worker inherits `PERK_RUN_ID` from the env and never re-mints.
 //
+// Budget semantics: `budget.tokens` counts FRESH WORK only — assistant `input + output` per
+// `turn_end`. Cache reads/writes and the provider `reasoning` breakdown (a subset of `output` in
+// pi-ai's normalization) are excluded by design; see `applyEvent`.
+//
 // Inverse of `extension/worker/readOnlySession.ts`: that builds a fully-isolated READ-ONLY child (loads
 // nothing, `["read","grep","find","ls"]`); the worker is the OPPOSITE — read-write defaults + the
-// real perk extension loaded from the worktree's `.pi/settings.json` (cwd-discovery), with the
+// real perk extension loaded from the worktree's `.pi/settings.json` (disk-layered settings:
+// `SettingsManager.create(worktree, throwawayAgentDir)` resolves the managed project-tier
+// `packages` list — perk + the borrowed set, the same package set as a warm session), with the
 // user-global tier locked out via a throwaway `agentDir`.
 
 import { appendFileSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { env } from "node:process";
-import type { Api, Model } from "@earendil-works/pi-ai";
+// pi-ai's `ModelThinkingLevel` (`"off" | minimal | … | xhigh`) is the union `resolveCliModel`
+// returns and `createAgentSessionFromServices` accepts; the pi-coding-agent root does not
+// re-export a thinking-level type (only `ThinkingLevelChangeEntry`).
+import type { Api, Model, ModelThinkingLevel as ThinkingLevel } from "@earendil-works/pi-ai";
 import {
   AuthStorage,
   type CreateAgentSessionRuntimeFactory,
-  type CreateAgentSessionServicesOptions,
   createAgentSessionFromServices,
   createAgentSessionRuntime,
   createAgentSessionServices,
   ModelRegistry,
+  resolveCliModel,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
@@ -37,6 +46,7 @@ import { planReadInstruction } from "../doors/lifecycleGates.ts";
 import { ensureRunScratch, type PlanRef, readPlanRef, runEventsPath } from "../substrate/cache.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
 import { render } from "../substrate/prompts.ts";
+import { captureSessionPointer } from "../substrate/sessionPointers.ts";
 import { rebuildWorkflowState } from "../substrate/workflowState.ts";
 import { capForModel } from "./readOnlySession.ts";
 
@@ -115,8 +125,18 @@ export interface DriveStageOptions {
   stage: DriveStage;
   /** The seeded first prompt (see `initialPromptFor`). */
   initialPrompt: string;
-  /** Explicit model; else the first available from the registry (Gap 5). */
+  /**
+   * Explicit model; else the SDK's own default resolution picks one at session creation
+   * (settings `defaultModel` → pi's per-provider defaults → first available — Gap 5). Never
+   * pre-pinned here: `getAvailable()` sorts alphabetically, so `[0]` is the *oldest* model of
+   * the first provider (a since-removed `claude-3-5-haiku` date-pin 404'd a whole remote drive).
+   */
   model?: Model<Api>;
+  /**
+   * Thinking level parsed from the `--model <pattern>:<level>` suffix (`resolveWorkerModel`).
+   * `undefined` ⇒ the SDK's settings-default resolution — unchanged behavior.
+   */
+  thinkingLevel?: ThinkingLevel;
   authStorage?: AuthStorage;
   modelRegistry?: ModelRegistry;
   budget: DriveBudget;
@@ -126,12 +146,11 @@ export interface DriveStageOptions {
 
 /**
  * The offline seam (mirrors `readOnlySession.test.ts`'s `runTask` injection). `createRuntime`
- * overrides the production runtime factory so tests drive synthetic sessions; `resourceLoaderOptions`
- * tunes the project-tier load; `now` injects the clock for deterministic `elapsed_ms`.
+ * overrides the production runtime factory so tests drive synthetic sessions; `now` injects the
+ * clock for deterministic `elapsed_ms`.
  */
 export interface DriveStageDeps {
   createRuntime?: (opts: DriveStageOptions) => Promise<DriveRuntimeLike>;
-  resourceLoaderOptions?: CreateAgentSessionServicesOptions["resourceLoaderOptions"];
   now?: () => number;
   /** The structured run-event sink. Absent ⇒ the default run-scoped NDJSON file sink. */
   eventSink?: RunEventSink;
@@ -149,7 +168,14 @@ export interface DriveEvent {
     role?: string;
     stopReason?: string;
     errorMessage?: string;
-    usage?: { input?: number; output?: number };
+    /**
+     * Assistant token usage. `reasoning` is a provider-reported breakdown that is a **subset of
+     * `output`** on every pi-ai provider that populates it (anthropic `thinking_tokens`, google
+     * `thoughtsTokenCount` folded into `output`, openai `reasoning_tokens` inside completion/
+     * output tokens — verified @ pi-ai 0.80.5), so it is deliberately EXCLUDED from the budget
+     * sum: adding it would double-count.
+     */
+    usage?: { input?: number; output?: number; reasoning?: number };
     /** Assistant text/content blocks (where `[WIP:n]`/`[DONE:n]` markers live). */
     content?: unknown;
   };
@@ -162,7 +188,13 @@ export interface DriveSessionLike {
   prompt(text: string): Promise<void>;
   abort(): Promise<void>;
   dispose(): void;
-  sessionManager: { getBranch(): unknown[] };
+  sessionManager: { getBranch(): unknown[]; getSessionFile?(): string | null };
+  /**
+   * Optional (presence-gated): when the session exposes its extension runner, `driveStage`
+   * preflights the stage's terminating perk tool post-bind and fails fast (zero-turn
+   * `no_extension_tools`) instead of burning the budget on a tool-less session.
+   */
+  extensionRunner?: { getAllRegisteredTools(): { definition: { name: string } }[] };
 }
 
 /** The runtime surface (structurally satisfied by pi's `AgentSessionRuntime`). */
@@ -209,6 +241,10 @@ function detailsOf(result: unknown): Record<string, unknown> | null {
  * assistant token usage (the `sumAssistantTokens` pattern in objective.ts), captures the `submit`
  * /`resolve_review_threads` terminal tool details, and records a post-acceptance model error
  * (assistant `message_end` with `stopReason:"error"`, surfaced with retry off — audit §B #4).
+ *
+ * The token sum is `input + output` ONLY: `usage.reasoning` is a subset of `output` on every
+ * pi-ai provider that reports it (see the `DriveEvent.usage` doc), so summing it would
+ * double-count.
  */
 export function applyEvent(counters: DriveCounters, event: DriveEvent): void {
   if (event.type === "turn_end") {
@@ -314,6 +350,17 @@ export function evaluateTerminal(args: {
   };
 }
 
+/**
+ * The post-bind preflight rule (pure): the stage's terminating perk tool must be registered —
+ * `implement` → `submit`, `address` → `resolve_review_threads`. Returns the required tool name
+ * when absent, else `null`. Deliberately does NOT require the `subagent` tool for `address` — the
+ * subagent-under-worker live smoke stays the §8.11 carried risk.
+ */
+export function missingTerminatingTool(stage: DriveStage, toolNames: string[]): string | null {
+  const required = stage === "implement" ? "submit" : "resolve_review_threads";
+  return toolNames.includes(required) ? null : required;
+}
+
 /** Pull a `{ number, url }` PR from a captured `submit` details block; null when malformed. */
 function extractPr(
   details: Record<string, unknown> | null,
@@ -465,9 +512,11 @@ export function defaultEventSink(worktree: string, runId: string): RunEventSink
 /**
  * Re-derive the stage's initial prompt from the plan-ref — the TS twin of
  * `perk/run/launch.py._implement_prompt`/`_address_prompt`. INVARIANT: textual parity with the Python
- * plane (asserted reciprocally in `worker.test.ts` + `tests/test_worker_prompt_parity.py`); the
- * resolved skill-binding suffix is delivered by the cold door, not here. Returns
- * `null` when there is no plan-ref (nothing to prime).
+ * plane (asserted reciprocally in `worker.test.ts` + `tests/test_worker_prompt_parity.py`). No
+ * skill-binding suffix is appended here: in the driven session the bindings arrive via Mechanism A
+ * (bindingDelivery.ts injects the handoff stage's render because this prompt carries no
+ * `BINDING_HEADER`) — content byte-identical to the cold door's suffix (contracts.md §8.38).
+ * Returns `null` when there is no plan-ref (nothing to prime).
  *
  * The implement primer's wording lives in the canonical template `prompts/stages/implement.md`,
  * rendered by the shared seam (contracts.md §8.31); branching stays in code — only the `read_cmd`
@@ -493,7 +542,7 @@ export function initialPromptFor(
   }
   // address
   const modelClause = classifierModel
-    ? `, passing \`model: "${classifierModel}"\` on that call (the configured [subagents] review-classifier model)`
+    ? `, passing \`model: "${classifierModel}"\` on that call (the configured [models.subagents] review-classifier model)`
     : "";
   return render("stages/address/action.md", {
     provider,
@@ -548,20 +597,24 @@ export function createBindManager(binding: unknown, listener: (event: DriveEvent
 /**
  * Build the asymmetric runtime: `cwd = worktree` (project tier — perk's `@mgiles/perk` extension via the
  * managed `.pi/settings.json`, the managed `AGENTS.md`/`APPEND_SYSTEM.md`) and `agentDir = throwaway`
- * (user-global tier OUT), compaction-off + retry-off settings, env-var/registry auth+model (Gap 5).
- * No `tools` allowlist — read-write defaults + extension tools. The `createAgentSessionServices`
- * factory builds the `DefaultResourceLoader` internally from `cwd`/`agentDir` (recipe correction #1).
+ * (user-global tier OUT — the throwaway dir has no `settings.json`, so the global tier is empty),
+ * env-var/registry auth+model (Gap 5). Settings are DISK-LAYERED (`SettingsManager.create` +
+ * `applyOverrides`, the SDK's sanctioned "with overrides" shape — docs/sdk.md "Settings
+ * Management"): the project tier resolves the managed `packages` list, while the compaction-off/
+ * retry-off determinism overrides ride the merged view only (package resolution reads the
+ * per-scope raws — overrides cannot leak into it). Missing `npm:` packages auto-install into
+ * `.pi/npm` during the loader's reload (skipped under `PI_OFFLINE`); an install failure throws →
+ * `driveStage`'s catch arm → a loud `failed`/`drive_error`. No `tools` allowlist — read-write
+ * defaults + extension tools. The `createAgentSessionServices` factory builds the
+ * `DefaultResourceLoader` internally from `cwd`/`agentDir` (recipe correction #1).
  */
 async function defaultCreateRuntime(
   opts: DriveStageOptions,
-  deps: DriveStageDeps,
-  resolved: { authStorage: AuthStorage; modelRegistry: ModelRegistry; model: Model<Api> },
+  resolved: ResolvedAuth,
 ): Promise<DriveRuntimeLike> {
   const agentDir = mkdtempSync(join(tmpdir(), "perk-worker-agent-"));
-  const settingsManager = SettingsManager.inMemory({
-    compaction: { enabled: false },
-    retry: { enabled: false },
-  });
+  const settingsManager = SettingsManager.create(opts.worktree, agentDir);
+  settingsManager.applyOverrides({ compaction: { enabled: false }, retry: { enabled: false } });
   const factory: CreateAgentSessionRuntimeFactory = async (factoryOpts) => {
     const services = await createAgentSessionServices({
       cwd: factoryOpts.cwd,
@@ -569,14 +622,31 @@ async function defaultCreateRuntime(
       authStorage: resolved.authStorage,
       settingsManager,
       modelRegistry: resolved.modelRegistry,
-      resourceLoaderOptions: deps.resourceLoaderOptions,
     });
     const result = await createAgentSessionFromServices({
       services,
       sessionManager: factoryOpts.sessionManager,
       sessionStartEvent: factoryOpts.sessionStartEvent,
+      // `undefined` ⇒ the SDK's initial-model resolution picks the model (see `resolveAuth`);
+      // an `undefined` thinkingLevel likewise defers to the settings default.
       model: resolved.model,
+      thinkingLevel: opts.thinkingLevel,
     });
+    // Name the model that will actually drive (the SDK may have picked it) — the remote step
+    // log is otherwise silent about it until a provider error.
+    const chosen = result.session.model;
+    console.error(
+      `perk worker: model ${chosen ? `${chosen.provider}/${chosen.id}` : "unresolved"}`,
+    );
+    // Loud construction diagnostics (the CAUSE behind a later `no_extension_tools` symptom):
+    // settings I/O errors and extension load errors are recorded, not raised, by the SDK —
+    // surfacing them is the app layer's job. Fail-soft reporting only; never throws.
+    for (const entry of result.extensionsResult.errors) {
+      console.error(`perk worker: extension load error — ${entry.path}: ${entry.error}`);
+    }
+    for (const entry of settingsManager.drainErrors()) {
+      console.error(`perk worker: settings error (${entry.scope}) — ${String(entry.error)}`);
+    }
     return { ...result, services, diagnostics: services.diagnostics };
   };
   const runtime = await createAgentSessionRuntime(factory, {
@@ -589,19 +659,67 @@ async function defaultCreateRuntime(
 
 // --- model/auth resolution (Gap 5) --------------------------------------------------------------
 
-interface ResolvedAuth {
+export interface ResolvedAuth {
   authStorage: AuthStorage;
   modelRegistry: ModelRegistry;
-  model: Model<Api>;
+  /** The EXPLICIT model only; `undefined` defers the pick to the SDK at session creation. */
+  model: Model<Api> | undefined;
 }
 
-/** Resolve auth + model; returns null (never throws) when no model is available. */
-function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
+/**
+ * Resolve auth; returns null (never throws) when no model is available at all. The model is NOT
+ * pre-pinned from the registry: an `undefined` model lets `createAgentSession` run its own
+ * initial-model resolution (settings `defaultModel` → pi's curated per-provider defaults → first
+ * available), which picks a current-generation model instead of the registry's
+ * alphabetically-first (= oldest) entry.
+ */
+export function resolveAuth(opts: DriveStageOptions): ResolvedAuth | null {
   const authStorage = opts.authStorage ?? AuthStorage.create();
   const modelRegistry = opts.modelRegistry ?? ModelRegistry.create(authStorage);
-  const model = opts.model ?? modelRegistry.getAvailable()[0];
-  if (!model) return null;
-  return { authStorage, modelRegistry, model };
+  if (!opts.model && modelRegistry.getAvailable().length === 0) return null;
+  return { authStorage, modelRegistry, model: opts.model };
+}
+
+/** What an explicit `--model` flag resolves to (a thin projection of `ResolveCliModelResult`). */
+export interface ResolvedWorkerModel {
+  model: Model<Api> | undefined;
+  thinkingLevel: ThinkingLevel | undefined;
+  /** Non-fatal resolution diagnostic (e.g. an invalid `:thinking` suffix) — surface, continue. */
+  warning: string | undefined;
+  /** Fatal: the pattern resolved to no model — fail fast, never guess. */
+  error: string | undefined;
+}
+
+/**
+ * Resolve an explicit `--model` flag with pi's OWN CLI semantics (`resolveCliModel`): fuzzy
+ * matching, bare-id resolution, `provider/pattern`, and a `:thinking` suffix — the same chain the
+ * flag's string hits in an interactive pi launch, closing the warm/cold parity gap (cf.
+ * docs/learned/workflow/execution-path-parity.md). `raw` falsy ⇒ all-undefined (the SDK's own
+ * default resolution picks the model at session creation — see `resolveAuth`). A resolution that
+ * yields neither a model nor an error is normalized to the worker's not-found error.
+ */
+export function resolveWorkerModel(
+  raw: string | undefined,
+  modelRegistry: ModelRegistry,
+): ResolvedWorkerModel {
+  if (!raw) {
+    return { model: undefined, thinkingLevel: undefined, warning: undefined, error: undefined };
+  }
+  const result = resolveCliModel({ cliModel: raw, modelRegistry });
+  if (result.model === undefined && result.error === undefined) {
+    return {
+      model: undefined,
+      thinkingLevel: undefined,
+      warning: result.warning,
+      error: `model '${raw}' not found in the registry.`,
+    };
+  }
+  return {
+    model: result.model,
+    thinkingLevel: result.thinkingLevel,
+    warning: result.warning,
+    error: result.error,
+  };
 }
 
 // --- the drive primitive ------------------------------------------------------------------------
@@ -677,12 +795,50 @@ export async function driveStage(
     runtime = deps.createRuntime
       ? await deps.createRuntime(opts)
       : // biome-ignore lint/style/noNonNullAssertion: resolved is non-null on the production path.
-        await defaultCreateRuntime(opts, deps, resolved!);
+        await defaultCreateRuntime(opts, resolved!);
 
     let boundSession = runtime.session;
     await bindManager.bind(boundSession);
     emitter.emit({ kind: "run_started", run_id: runId, stage: opts.stage });
 
+    // Terminating-tool preflight (presence-gated on `extensionRunner`): disk discovery has a
+    // silent-zero arm — a missing/unparseable `.pi/settings.json` or an unresolvable local-path
+    // package yields ZERO extension tools without throwing — so fail fast (zero turns) instead of
+    // burning the whole budget on a drive that can never call its terminating tool. Reuses the
+    // `model_error` terminal signal with a distinct `error.type` (the `no_model` precedent).
+    if (boundSession.extensionRunner) {
+      const toolNames = boundSession.extensionRunner
+        .getAllRegisteredTools()
+        .map((t) => t.definition.name);
+      const missing = missingTerminatingTool(opts.stage, toolNames);
+      if (missing !== null) {
+        return finish({
+          status: "failed",
+          terminal_signal: "model_error",
+          pr: null,
+          errorType: "no_extension_tools",
+          errorMessage:
+            `perk extension tools did not register — the ${opts.stage} stage's terminating ` +
+            `tool \`${missing}\` is missing. Check the worktree's .pi/settings.json packages ` +
+            "list (perk init converges it); construction diagnostics are on stderr.",
+        });
+      }
+    }
+
+    // Implementation/worker session pointer (contracts.md §8.35): the headless drive records the
+    // inner driven session's file under THIS run id into the shared main checkout (the worktree's
+    // `mainCheckoutRoot`), labelled `.worker` by capture site. The inner session's own
+    // `session_start` records the matching `.main`. Best-effort + non-fatal (carrier warns).
+    if (opts.stage === "implement") {
+      captureSessionPointer({
+        cwd: opts.worktree,
+        runId,
+        klass: "implementation",
+        site: "worker",
+        sessionFile: boundSession.sessionManager.getSessionFile?.() ?? null,
+      });
+    }
+
     // Budget/abort wiring (Gap 2): wall-clock timer + external signal both trip → session.abort().
     const timer = setTimeout(() => trip("budget"), opts.budget.wallClockMs);
     if (opts.signal) {

package/extension/workerMain.ts

@@ -9,15 +9,15 @@
 // stderr), and exits 0 on `completed` else non-zero. Runs as `.ts` under node 22 type-stripping.
 
 import { argv, env, exit, stderr, stdout } from "node:process";
-import type { Api, Model } from "@earendil-works/pi-ai";
 import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
-import { runEventsPath } from "./substrate/cache.ts";
+import { runEventsPath, workflowDir } from "./substrate/cache.ts";
 import {
   type DriveBudget,
   type DriveStage,
   driveStage,
   initialPromptForWorktree,
   type RunOutcome,
+  resolveWorkerModel,
 } from "./worker/worker.ts";
 
 /** Documented defaults for the budget watchdog (overridable via flags). */
@@ -90,23 +90,23 @@ async function main(): Promise<number> {
   const initialPrompt = initialPromptForWorktree(parsed.worktree, parsed.stage);
   if (initialPrompt === null) {
     stderr.write(
-      `perk worker: no plan-ref under ${parsed.worktree}/.pi/workflow — cannot seed the ${parsed.stage} prompt.\n`,
+      `perk worker: no plan-ref under ${workflowDir(parsed.worktree)} — cannot seed the ${parsed.stage} prompt.\n`,
     );
     return 2;
   }
 
-  // Headless auth/model (Gap 5): env-var key resolution; `--model provider/id` else first available.
+  // Headless auth/model (Gap 5): env-var key resolution; an explicit `--model` resolves with
+  // pi's CLI semantics (fuzzy matching, `provider/pattern`, a `:thinking` suffix —
+  // `resolveWorkerModel`), else the SDK's default resolution at session creation (settings
+  // default → pi's per-provider defaults → first available) — the deferral is unchanged.
   const authStorage = AuthStorage.create();
   const modelRegistry = ModelRegistry.create(authStorage);
-  let model: Model<Api> | undefined;
-  if (parsed.model) {
-    const [provider, ...rest] = parsed.model.split("/");
-    model = modelRegistry.find(provider ?? "", rest.join("/"));
-    if (!model) {
-      stderr.write(`perk worker: model '${parsed.model}' not found in the registry.\n`);
-      return 2;
-    }
+  const resolved = resolveWorkerModel(parsed.model, modelRegistry);
+  if (resolved.error) {
+    stderr.write(`perk worker: ${resolved.error}\n`);
+    return 2;
   }
+  if (resolved.warning) stderr.write(`perk worker: ${resolved.warning}\n`);
 
   const controller = new AbortController();
   const onSignal = (): void => controller.abort();
@@ -119,7 +119,8 @@ async function main(): Promise<number> {
       worktree: parsed.worktree,
       stage: parsed.stage,
       initialPrompt,
-      model,
+      model: resolved.model,
+      thinkingLevel: resolved.thinkingLevel,
       authStorage,
       modelRegistry,
       budget: parsed.budget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgiles/perk",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "perk Pi extension (session interior) for the plan-oriented workflow.",
   "license": "MIT",
   "repository": {
@@ -34,9 +34,6 @@
     "lint": "biome check extension",
     "format": "biome format --write extension"
   },
-  "dependencies": {
-    "nunjucks": "3.2.4"
-  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
@@ -45,10 +42,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.16",
-    "@earendil-works/pi-ai": "0.78.1",
-    "@earendil-works/pi-coding-agent": "0.78.1",
+    "@earendil-works/pi-ai": "0.80.5",
+    "@earendil-works/pi-coding-agent": "0.80.5",
     "@types/node": "22.19.19",
-    "@types/nunjucks": "3.2.6",
     "typescript": "6.0.3",
     "yaml": "2.9.0"
   }

package/prompts/README.md

@@ -1,6 +1,14 @@
-# prompts — canonical cross-plane prompt templates
+# prompts — perk's externalized prompt prose
 
-perk's prompt templates, authored once and **bundled into every build artifact**
+This directory is the canonical home for **all** of perk's externalized prompt prose. A
+template may be **cross-plane** (rendered in production by both planes) or **single-plane**
+(rendered by only one plane — e.g. a warm-door-only or cold-door-only seed/guidance prompt);
+either way it is authored within the frozen mini-jinja subset below and listed in
+`_fixtures/live.yaml`, where it is rendered on **both** engines and asserted byte-equal
+regardless of which plane consumes it in production (a free cross-engine portability guarantee,
+costing nothing since the subset is shared).
+
+The templates are authored once and **bundled into every build artifact**
 (the Python wheel as package data `perk/_prompts/`; the npm package under `prompts/`),
 exactly like `shared/`. Each plane locates this directory at runtime through its own
 resolver — `prompts_dir()` (`perk/_resources.py`) and `promptsDir()`
@@ -10,6 +18,49 @@ Templates are rendered by jinja2 (Python) and a vendored TS subset (the extensio
 are loaded by explicit name through the resolver — never by scanning the directory, so
 this README is a durable doc, not a template.
 
-The render seam, the frozen template-grammar spec, and the real prompt content land in
-later nodes; for now this file is the bundling/resolution probe that gives the directory
-tracked content.
+## Frozen template grammar
+
+The templates use a deliberately tiny, **frozen** subset of jinja syntax — the canonical
+"mini-jinja" surface. jinja2 is the reference engine; the extension renders the same subset. A
+**cross-plane conformance guard** (`tests/test_prompt_grammar.py` +
+`extension/substrate/promptGrammar.test.ts`) fails CI if any template uses a construct outside the
+subset.
+
+## Render parity — two decoupled tiers
+
+The two render seams (jinja2 on Python, the vendored mini-jinja on TS) are kept byte-identical by
+two tiers that separate the frozen render **contract** from real prompt **prose**:
+
+- **Tier A — contract snapshots.** `_fixtures/cases.yaml` lists purpose-built fixture templates
+  under `_fixtures/templates/` (one per render feature) with committed goldens under
+  `_fixtures/golden/` (jinja2's output). Both planes assert `render == golden`
+  (`tests/test_prompts.py` + `extension/substrate/prompts.test.ts`). These goldens change only when
+  the render contract changes — never when a real prompt's prose changes.
+- **Tier B — live cross-engine equality.** `_fixtures/live.yaml` lists every real template with
+  representative vars and **no** golden. `tests/test_prompt_parity.py` renders each real template
+  with jinja2, shells out once to `extension/testing/renderLive.ts` (mini-jinja), and asserts the
+  two outputs are byte-equal — so editing a real prompt's prose touches no fixture. A coverage
+  guard asserts every real template is listed in `live.yaml`.
+
+The subset is exactly four categories:
+
+1. **Variable substitution** — `{{ name }}`, where the contents are a single bare identifier
+   (`[A-Za-z_][A-Za-z0-9_]*`). Nothing else: no filters, no dotted access, no parentheses, no
+   literals, no operators.
+2. **Include** — `{% include "path/to/file.md" %}`, a double-quoted root-relative path only.
+3. **Conditionals** — `{% if cond %}` / `{% elif cond %}` / `{% else %}` / `{% endif %}`, where
+   `cond` uses only bare identifiers (truthiness), double-quoted string literals, `==`, and the
+   keywords `and` / `or` / `not`. For example: `{% if provider == "github" or provider == "linear" %}`,
+   `{% if not pr_id %}`.
+4. **Plain tags** — `{% %}` only. The whitespace-control markers `{%- … -%}` / `{{- … -}}` are
+   **not allowed**; tag-line stripping is handled by the render env's `trim_blocks` setting.
+
+**Not allowed** (the guard fails on these): `{% for x in y %}` / `{% endfor %}`, `{% set %}`,
+`{% macro %}` / `{% block %}` / `{% extends %}` / `{% raw %}`, `{# comments #}`, filters
+(`{{ x | upper }}`), attribute access (`{{ user.name }}`), `!=` / `<` / `>`, `in`, `is`,
+parentheses, and numeric literals.
+
+This README is **excluded** from the guard's scan — it is documentation, never rendered, and the
+out-of-subset examples above are shown deliberately as prose. The canonical spec lives in
+[`shared/contracts.md` §8.31](../shared/contracts.md). Widening the subset is a deliberate
+decision that amends §8.31 **and** both guards.