feat(prompt-variance): extract family prompt variance as a versioned package

Directors resolve default/muse/grok rows and assemble prompts through
packages/prompt-variance instead of hand-concatenated grokAntiThrash
booleans. Default/grok director output is byte-identical (sha256 match
across all directors); muse rules now also render in prompt-size rows.

Verification: bun test src/agent src/subagent src/prompts.test.ts
packages/prompt-variance/ — 1416 pass, 0 fail. tsc --noEmit reports only
the pre-existing vendor/intx-types semver error, identical on main.

Author: TheGreatAxios

packages/prompt-variance/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "prompt-variance",
+  "version": "1.4.0",
+  "private": true,
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  }
+}

packages/prompt-variance/src/assemble.ts

@@ -0,0 +1,33 @@
+import type { PromptVarianceRow } from "./rows.js";
+
+export interface AssembledPromptVariance {
+  systemPrompt: string;
+  toolNames: readonly string[];
+}
+
+/**
+ * Assemble a prompt from sections plus a family variance row (CL-8269).
+ * The row residual renders last; advertised denies filter the mounted
+ * tool names. Variance is subtractive only: the output names are always
+ * a subset of the input names, in input order.
+ */
+export function assemble(
+  sections: readonly string[],
+  familyRow: PromptVarianceRow,
+  tools: readonly string[],
+): AssembledPromptVariance {
+  if (familyRow.advertisedToolDeny.includes("use_skill")) {
+    throw new Error(
+      `prompt-variance: row "${familyRow.id}" denies use_skill — brief-named skills always load directly`,
+    );
+  }
+  const systemPrompt =
+    familyRow.residual.length > 0
+      ? [...sections, familyRow.residual].join("\n\n")
+      : sections.join("\n\n");
+  const deny = new Set(familyRow.advertisedToolDeny);
+  return {
+    systemPrompt,
+    toolNames: tools.filter((name) => !deny.has(name)),
+  };
+}

packages/prompt-variance/src/index.ts

@@ -0,0 +1,16 @@
+export { assemble, type AssembledPromptVariance } from "./assemble.js";
+export {
+  applyRowOverride,
+  resolvePromptVariance,
+} from "./resolve.js";
+export {
+  defaultRow,
+  FAMILY_IDS,
+  FAMILY_ROWS,
+  grokRow,
+  museRow,
+  type PromptVarianceFamily,
+  type PromptVarianceRender,
+  type PromptVarianceRow,
+  type PromptVarianceRowOverride,
+} from "./rows.js";

packages/prompt-variance/src/resolve.ts

@@ -0,0 +1,43 @@
+import {
+  defaultRow,
+  FAMILY_ROWS,
+  type PromptVarianceFamily,
+  type PromptVarianceRow,
+} from "./rows.js";
+
+/**
+ * Apply a row's per-model-id override, if any. Model ids match
+ * case-insensitively against the row's lowercase override keys; an
+ * unknown id resolves to the base row unchanged.
+ */
+export function applyRowOverride(
+  row: PromptVarianceRow,
+  model?: string,
+): PromptVarianceRow {
+  if (model === undefined) return row;
+  const override = row.overrides?.[model.trim().toLowerCase()];
+  if (override === undefined) return row;
+  return {
+    ...row,
+    residual: override.residual ?? row.residual,
+    advertisedToolDeny: override.advertisedToolDeny ?? row.advertisedToolDeny,
+    sectionOmit: override.sectionOmit ?? row.sectionOmit,
+  };
+}
+
+/**
+ * Resolve the variance row for a family, mirroring the leaves-only gate:
+ * the grok finish-bias residual only makes sense on leaf workers, so
+ * orchestrators fall back to the default shape. Muse keeps its residual
+ * on both — its constructors append the same text at the tail either way.
+ */
+export function resolvePromptVariance(input: {
+  family: PromptVarianceFamily;
+  orchestrator?: boolean;
+  model?: string;
+}): PromptVarianceRow {
+  if (input.family === "grok" && input.orchestrator === true) {
+    return applyRowOverride(defaultRow, input.model);
+  }
+  return applyRowOverride(FAMILY_ROWS[input.family], input.model);
+}

packages/prompt-variance/src/rows.ts

@@ -0,0 +1,94 @@
+/**
+ * Versioned model-family prompt variance (CL-8269). One row per tuned
+ * family: a tail residual plus the tool names the family must not
+ * advertise. Directors assemble prompts through `assemble`, never by
+ * hand-concatenating family booleans.
+ *
+ * Only families with shipped eval numbers live here: default/muse/grok.
+ * glm/claude/gpt rows land when CL-8265 / 7772 / 7775 characterize them.
+ */
+
+/** Families with a shipped variance row. */
+export type PromptVarianceFamily = "default" | "muse" | "grok";
+
+/** Residuals render at the tail so they cannot disturb the cached prefix. */
+export type PromptVarianceRender = "tail";
+
+export interface PromptVarianceRowOverride {
+  residual?: string;
+  advertisedToolDeny?: readonly string[];
+  sectionOmit?: readonly string[];
+}
+
+export interface PromptVarianceRow {
+  id: PromptVarianceFamily;
+  render: PromptVarianceRender;
+  /** Tail text appended to the assembled prompt. Empty when the family needs none. */
+  residual: string;
+  /**
+   * Tool names to drop from the advertised set (CL-7668). Subtractive
+   * only — a row can never grant a tool `assemble` was not given.
+   * `use_skill` is never denied: brief-named skills load directly.
+   */
+  advertisedToolDeny: readonly string[];
+  /** Assembly section ids to omit for this family. Empty until a family needs one. */
+  sectionOmit: readonly string[];
+  /** Optional per-model-id refinements, keyed by lowercase model id. */
+  overrides?: Record<string, PromptVarianceRowOverride>;
+}
+
+export const FAMILY_IDS: readonly PromptVarianceFamily[] = [
+  "default",
+  "muse",
+  "grok",
+];
+
+export const defaultRow: PromptVarianceRow = {
+  id: "default",
+  render: "tail",
+  residual: "",
+  advertisedToolDeny: [],
+  sectionOmit: [],
+};
+
+// Muse Spark does not reliably stop a tool loop at medium reasoning effort:
+// the same run with these three rules appended finished in 3 turns on 4.3x
+// fewer input tokens (CL-7869). Byte-identical to the shipped text so the
+// size table and the constructor append cannot drift apart.
+export const museRow: PromptVarianceRow = {
+  id: "muse",
+  render: "tail",
+  residual:
+    "Tool discipline:\n" +
+    "- Batch independent tool calls into a single turn.\n" +
+    "- Never re-read a file you have already read this session.\n" +
+    "- Do not narrate; act.",
+  advertisedToolDeny: [],
+  sectionOmit: [],
+};
+
+// Tiny residual for Grok/xAI workers: mining showed higher tools-only thrash
+// than Codex on the same harness. Shared thrash harness + spawn contracts do
+// the structural work; this is only a finish-bias nudge, not a full rewrite.
+// Built from the current grok finish-bias text on origin/main; the CL-8297
+// residual folds in here at merge time.
+export const grokRow: PromptVarianceRow = {
+  id: "grok",
+  render: "tail",
+  residual: [
+    "Finish bias (xAI / Grok worker):",
+    "- Once you can answer the dispatch brief, prefer the structured report over another speculative tool call.",
+    "- If the next call would only re-open paths you already read, write the report instead.",
+    "- When the dispatch brief's done-definition is met, write the report envelope instead of making one more search or micro-edit.",
+    "- Route file and web work through the dedicated tools, never run_shell — mining showed grok reaching for shell first when a typed tool already covered the job.",
+  ].join("\n"),
+  // Leaf value; resolvePromptVariance clears it for orchestrators.
+  advertisedToolDeny: ["skill_search"],
+  sectionOmit: [],
+};
+
+export const FAMILY_ROWS: Record<PromptVarianceFamily, PromptVarianceRow> = {
+  default: defaultRow,
+  muse: museRow,
+  grok: grokRow,
+};

src/agent/model-family-policy.ts

@@ -2,6 +2,7 @@ import {
   detectModelFamily,
   type ModelFamily,
 } from "../subagent/provider-family.js";
+import { museRow } from "../../packages/prompt-variance/src/index.js";
 
 /**
  * Per-model-family tuning for the shared directors (main chat director and
@@ -120,11 +121,8 @@ const KIMI_POLICY: Omit<ModelFamilyPolicy, "family"> = { ...DEFAULT_POLICY };
 // three rules appended finished in 3 turns on 4.3x fewer input tokens. At
 // minimal effort it terminates either way, so the rules earn their keep exactly
 // at the rungs where each wasted turn is most expensive. See CL-7869.
-const MUSE_TOOL_DISCIPLINE_RULES =
-  "Tool discipline:\n" +
-  "- Batch independent tool calls into a single turn.\n" +
-  "- Never re-read a file you have already read this session.\n" +
-  "- Do not narrate; act.";
+// Single-sourced from the versioned prompt-variance package (CL-8269).
+const MUSE_TOOL_DISCIPLINE_RULES = museRow.residual;
 
 const MUSE_POLICY: Omit<ModelFamilyPolicy, "family"> = {
   ...DEFAULT_POLICY,

src/agent/prompt-sizes.test.ts

@@ -27,7 +27,7 @@ import { resolveExecDirectorOverlay } from "../exec/runner.js";
 /**
  * Prompt size budget (CL-7664). Numeric asserts only — copy edits must not
  * fail this test. Baselines are a checked-in snapshot of the max measured
- * sizes across both families from the canonical fixture in
+ * sizes across all three families from the canonical fixture in
  * src/agent/prompt-sizes.ts; budgets add a +2000 char / +3000 byte allowance
  * (ceiling to 100) in code below. Bytes get the larger headroom because
  * multibyte copy can shift them faster. Adding a director is a type error
@@ -200,15 +200,15 @@ describe("director prompt size budget", () => {
 
   test("tool names match the production mount: no dupes, no phantoms", () => {
     for (const directorId of DIRECTOR_IDS) {
-      for (const family of ["default", "grok"] as const) {
+      for (const family of ["default", "muse", "grok"] as const) {
         const names = canonicalToolNamesForDirector(
           DIRECTOR_REGISTRY[directorId],
           family,
         );
         expect(new Set(names).size, `${directorId} [${family}]`).toBe(
           names.length,
         );
-        // Neither fixture family is Codex, so the Codex proxies
+        // No fixture family is Codex, so the Codex proxies
         // (createCodexToolProxies returns [] when !isCodex) must be absent,
         // as must list_dir, which no subagent mount installs.
         for (const phantom of [
@@ -234,17 +234,20 @@ describe("director prompt size budget", () => {
   test("formatPromptSizeTable renders one row per director", () => {
     const table = formatPromptSizeTable(rows);
     expect(table).toContain(
-      "| director | default chars (bytes) | grok chars (bytes) |",
+      "| director | default chars (bytes) | muse chars (bytes) | grok chars (bytes) |",
     );
     for (const directorId of DIRECTOR_IDS) {
       const base = rows.find(
         (r) => r.directorId === directorId && r.family === "default",
       );
+      const muse = rows.find(
+        (r) => r.directorId === directorId && r.family === "muse",
+      );
       const grok = rows.find(
         (r) => r.directorId === directorId && r.family === "grok",
       );
       expect(table).toContain(
-        `| ${directorId} | ${base?.chars} (${base?.bytes}) | ${grok?.chars} (${grok?.bytes}) |`,
+        `| ${directorId} | ${base?.chars} (${base?.bytes}) | ${muse?.chars} (${muse?.bytes}) | ${grok?.chars} (${grok?.bytes}) |`,
       );
     }
   });

src/agent/prompt-sizes.ts

@@ -38,8 +38,9 @@ import { webSearchDefinition } from "../tools/web-search.js";
  * appendix, with the Grok finish-bias note gated by
  * shouldApplyGrokAntiThrash (leaves on Grok-family providers only) and the
  * family promptResidual (CL-8297 tool budget for grok leaves, XML
- * task_guidance block for claude leaves) resolved from the model family
- * policy.
+ * task_guidance block for claude leaves, narrate-before-tools nudge for
+ * gpt leaves) resolved from the model family policy. Residual texts are
+ * single-sourced from the versioned prompt-variance package (CL-8269).
  *
  * The env and provider inputs are pinned here so sizes never drift with the
  * machine, date, or checkout — only real prompt changes move the numbers.
@@ -60,13 +61,17 @@ const GROK_PROVIDER = { providerName: "xai/default", model: "grok-4.6" };
 // Default-family probe: an unrecognized provider stays on the default
 // family no matter how many family rows land (claude/gpt already ship),
 // so the default column carries no residual.
+const MUSE_PROVIDER = {
+  providerName: "opencode-go",
+  model: "muse-spark-1.3-contributor",
+};
 const DEFAULT_PROVIDER = {
   providerName: "unknown-provider",
   model: "unknown-model",
 };
 
-/** Families in the size table: default assembly vs Grok (+finish-bias note). */
-export type PromptSizeFamily = "default" | "grok";
+/** Families in the size table: default, muse (+tool-discipline rules), grok (+finish-bias note). */
+export type PromptSizeFamily = "default" | "muse" | "grok";
 
 /**
  * Pinned AGENTS.md body for prefix measurement. Production reads the live
@@ -162,7 +167,12 @@ export function assembleDirectorPrompt(
 ): string {
   const pkg = DIRECTOR_REGISTRY[directorId];
   const orchestrator = pkg.spawn.maySpawn;
-  const provider = family === "grok" ? GROK_PROVIDER : DEFAULT_PROVIDER;
+  const provider =
+    family === "grok"
+      ? GROK_PROVIDER
+      : family === "muse"
+        ? MUSE_PROVIDER
+        : DEFAULT_PROVIDER;
   const policy = resolveModelFamilyPolicy({ ...provider, orchestrator });
   return buildSubAgentSystemPrompt(
     [formatDirectorSystemPrompt(pkg)],
@@ -234,7 +244,7 @@ export function measureSkywalkerPrefix(): SkywalkerPrefixSize {
 export function directorPromptSizeTable(): DirectorPromptSize[] {
   const rows: DirectorPromptSize[] = [];
   for (const directorId of DIRECTOR_IDS) {
-    for (const family of ["default", "grok"] as const) {
+    for (const family of ["default", "muse", "grok"] as const) {
       rows.push(measureDirectorPrompt(directorId, family));
     }
   }
@@ -244,18 +254,21 @@ export function directorPromptSizeTable(): DirectorPromptSize[] {
 /** Render the size table as markdown (for PR bodies and budget updates). */
 export function formatPromptSizeTable(rows: DirectorPromptSize[]): string {
   const lines = [
-    "| director | default chars (bytes) | grok chars (bytes) |",
-    "| --- | --- | --- |",
+    "| director | default chars (bytes) | muse chars (bytes) | grok chars (bytes) |",
+    "| --- | --- | --- | --- |",
   ];
   for (const directorId of DIRECTOR_IDS) {
     const base = rows.find(
       (r) => r.directorId === directorId && r.family === "default",
     );
+    const muse = rows.find(
+      (r) => r.directorId === directorId && r.family === "muse",
+    );
     const grok = rows.find(
       (r) => r.directorId === directorId && r.family === "grok",
     );
     lines.push(
-      `| ${directorId} | ${base?.chars} (${base?.bytes}) | ${grok?.chars} (${grok?.bytes}) |`,
+      `| ${directorId} | ${base?.chars} (${base?.bytes}) | ${muse?.chars} (${muse?.bytes}) | ${grok?.chars} (${grok?.bytes}) |`,
     );
   }
   return lines.join("\n");