work-kit-cli 0.3.0 → 0.4.1

package/cli/src/commands/setup.ts

@@ -1,8 +1,11 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
+import { spawnSync } from "node:child_process";
 import { doctorCommand } from "./doctor.js";
 import { bold, dim, green, yellow, red, cyan } from "../utils/colors.js";
+import { ensureKnowledgeDir, KNOWLEDGE_DIR, KNOWLEDGE_LOCK } from "../utils/knowledge.js";
+import { ensureGitignored } from "./init.js";
 
 const SKILLS_SOURCE = path.resolve(import.meta.dirname, "..", "..", "..", "skills");
 
@@ -195,6 +198,157 @@ function installHooks(projectDir: string): { added: number; file: string } {
   return { added: WK_HOOKS.length, file: settingsFile };
 }
 
+// ── Playwright detection / install ─────────────────────────────────
+//
+// Work-kit's Test phase requires a real E2E framework. We standardize on
+// Playwright. setup/upgrade detect whether the target project already has
+// it; if not, we offer to install it (and optionally scaffold a config).
+
+type PackageManager = "pnpm" | "yarn" | "npm";
+
+function detectPackageManager(projectDir: string): PackageManager {
+  if (fs.existsSync(path.join(projectDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(projectDir, "yarn.lock"))) return "yarn";
+  return "npm";
+}
+
+function hasPlaywrightInstalled(projectDir: string): boolean {
+  const pkgPath = path.join(projectDir, "package.json");
+  if (!fs.existsSync(pkgPath)) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    return Boolean(deps["@playwright/test"] || deps["playwright"]);
+  } catch {
+    return false;
+  }
+}
+
+function hasPlaywrightConfig(projectDir: string): boolean {
+  return ["playwright.config.ts", "playwright.config.js", "playwright.config.mjs", "playwright.config.cjs"]
+    .some((f) => fs.existsSync(path.join(projectDir, f)));
+}
+
+function runStreamed(cmd: string, args: string[], cwd: string): boolean {
+  const result = spawnSync(cmd, args, { cwd, stdio: "inherit" });
+  return result.status === 0;
+}
+
+function installPlaywrightPackage(pm: PackageManager, projectDir: string): boolean {
+  const args =
+    pm === "pnpm" ? ["add", "-D", "@playwright/test"] :
+    pm === "yarn" ? ["add", "-D", "@playwright/test"] :
+    ["install", "-D", "@playwright/test"];
+  console.error(`  ${dim(`$ ${pm} ${args.join(" ")}`)}`);
+  if (runStreamed(pm, args, projectDir)) return true;
+
+  // The most common npm failure here is ERESOLVE — the user's project has
+  // a pre-existing peer-dep conflict that npm refuses to resolve. Retry with
+  // --legacy-peer-deps so Playwright still installs; the user's underlying
+  // conflict is left for them to fix separately.
+  if (pm === "npm") {
+    console.error(`  ${yellow("!")} npm install failed (likely peer-dep conflict). Retrying with --legacy-peer-deps...`);
+    const fallbackArgs = [...args, "--legacy-peer-deps"];
+    console.error(`  ${dim(`$ ${pm} ${fallbackArgs.join(" ")}`)}`);
+    if (runStreamed(pm, fallbackArgs, projectDir)) {
+      console.error(`  ${dim("Note: installed with --legacy-peer-deps. Your project still has the original peer-dep conflict — fix it separately when convenient.")}`);
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function installPlaywrightBrowsers(projectDir: string): boolean {
+  // Chromium-only — fastest install, covers most E2E needs.
+  console.error(`  ${dim("$ npx playwright install chromium")}`);
+  return runStreamed("npx", ["playwright", "install", "chromium"], projectDir);
+}
+
+function scaffoldPlaywrightConfig(pm: PackageManager, projectDir: string): boolean {
+  // `npm init playwright@latest` works regardless of pm (it just runs the create-playwright bin).
+  // Yarn/pnpm have their own equivalents but npm init is universally available.
+  console.error(`  ${dim("$ npm init playwright@latest -- --quiet --browser=chromium --no-examples")}`);
+  return runStreamed(
+    "npm",
+    ["init", "playwright@latest", "--", "--quiet", "--browser=chromium", "--no-examples"],
+    projectDir
+  );
+}
+
+async function ensurePlaywright(projectDir: string): Promise<void> {
+  console.error(`\nChecking Playwright (required for work-kit's E2E test step)...`);
+
+  // Non-Node project — nothing to do.
+  if (!fs.existsSync(path.join(projectDir, "package.json"))) {
+    console.error(`  ${dim("No package.json found — skipping Playwright setup.")}`);
+    return;
+  }
+
+  const pm = detectPackageManager(projectDir);
+  const installed = hasPlaywrightInstalled(projectDir);
+  const configured = hasPlaywrightConfig(projectDir);
+
+  if (installed && configured) {
+    console.error(`  ${green("\u2713")} Playwright already installed and configured.`);
+    return;
+  }
+
+  if (!installed) {
+    const answer = (await promptUser(`  Install Playwright (@playwright/test) via ${pm}? [y/N]: `)).toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      console.error(`  ${yellow("!")} Skipped. The wk-test E2E step will fail until Playwright is installed.`);
+      return;
+    }
+    if (!installPlaywrightPackage(pm, projectDir)) {
+      console.error(`  ${red("\u2717")} Failed to install @playwright/test.`);
+      return;
+    }
+    if (!installPlaywrightBrowsers(projectDir)) {
+      console.error(`  ${red("\u2717")} Failed to install Chromium browser.`);
+      return;
+    }
+    console.error(`  ${green("+")} Installed @playwright/test and Chromium.`);
+  }
+
+  if (!hasPlaywrightConfig(projectDir)) {
+    const answer = (await promptUser(`  No playwright.config found. Scaffold one now? [y/N]: `)).toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+      console.error(`  ${yellow("!")} Skipped scaffolding. Create a playwright.config.ts before running wk-test.`);
+      return;
+    }
+    if (!scaffoldPlaywrightConfig(pm, projectDir)) {
+      console.error(`  ${red("\u2717")} Scaffolding failed. Run \`npm init playwright@latest\` manually.`);
+      return;
+    }
+    console.error(`  ${green("+")} Playwright config scaffolded.`);
+  }
+}
+
+// Project knowledge files (lessons/conventions/risks/workflow) are committed
+// to the repo. Only the lockfile is gitignored.
+function setupKnowledgeDir(projectDir: string): void {
+  console.error(`\nScaffolding ${KNOWLEDGE_DIR}/ (project knowledge files)...`);
+  try {
+    const { created } = ensureKnowledgeDir(projectDir);
+    if (created.length > 0) {
+      for (const f of created) {
+        console.error(`  ${green("+")} ${KNOWLEDGE_DIR}/${f}`);
+      }
+      console.error(`  ${yellow("!")} ${bold("These files are committed to your repo.")} Don't write secrets in them.`);
+      console.error(`  ${dim("work-kit redacts known secret shapes at write time, but the regex sweep is best-effort.")}`);
+    } else {
+      console.error(`  ${dim("Already scaffolded.")}`);
+    }
+    ensureGitignored(projectDir, `${KNOWLEDGE_DIR}/${KNOWLEDGE_LOCK}`);
+  } catch (err) {
+    console.error(`  ${red("\u2717")} ${(err as Error).message}`);
+  }
+}
+
 async function promptUser(question: string): Promise<string> {
   const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
   return new Promise((resolve) => {
@@ -278,6 +432,12 @@ export async function setupCommand(targetPath?: string): Promise<void> {
     console.error(`  ${red("✗")} ${(err as Error).message}`);
   }
 
+  // Ensure Playwright is available — wk-test's E2E step requires it.
+  await ensurePlaywright(projectDir);
+
+  // Scaffold the project-level knowledge directory.
+  setupKnowledgeDir(projectDir);
+
   // Run doctor against the target project
   console.error("\nRunning doctor...");
   const result = doctorCommand(projectDir);

package/cli/src/commands/status.ts

@@ -6,6 +6,7 @@ interface StatusOutput {
   branch: string;
   mode: string;
   classification?: string;
+  modelPolicy: string;
   status: string;
   currentPhase: string | null;
   currentStep: string | null;
@@ -40,6 +41,7 @@ export function statusCommand(worktreeRoot?: string): StatusOutput {
     branch: state.branch,
     mode: state.mode,
     ...(state.classification && { classification: state.classification }),
+    modelPolicy: state.modelPolicy ?? "auto",
     status: state.status,
     currentPhase: state.currentPhase,
     currentStep: state.currentStep,

package/cli/src/commands/workflow.ts

@@ -1,11 +1,13 @@
 import { readState, writeState, findWorktreeRoot } from "../state/store.js";
-import { STEPS_BY_PHASE, PHASE_NAMES, MODE_AUTO } from "../state/schema.js";
+import { STEPS_BY_PHASE, PHASE_NAMES, MODE_AUTO, PhaseName } from "../state/schema.js";
 import { parseLocation } from "../state/helpers.js";
+import { resolveModel } from "../config/model-routing.js";
 import type { Action } from "../state/schema.js";
 
 interface WorkflowStatus {
   action: "workflow_status";
-  workflow: { step: string; status: string }[];
+  modelPolicy: string;
+  workflow: { step: string; status: string; model?: string }[];
 }
 
 export type WorkflowResult = Action | WorkflowStatus;
@@ -113,13 +115,21 @@ export function workflowCommand(opts: {
     return { action: "wait_for_user", message: `Removed ${opts.remove} from workflow.` };
   }
 
-  // No add/remove — show current workflow
+  // No add/remove — show current workflow with resolved model per step
   const workflow = state.workflow
     .filter((s) => s.included)
-    .map((s) => ({
-      step: `${s.phase}/${s.step}`,
-      status: state.phases[s.phase]?.steps[s.step]?.status || "unknown",
-    }));
-
-  return { action: "workflow_status", workflow };
+    .map((s) => {
+      const model = resolveModel(state, s.phase as PhaseName, s.step);
+      return {
+        step: `${s.phase}/${s.step}`,
+        status: state.phases[s.phase]?.steps[s.step]?.status || "unknown",
+        ...(model && { model }),
+      };
+    });
+
+  return {
+    action: "workflow_status",
+    modelPolicy: state.modelPolicy ?? "auto",
+    workflow,
+  };
 }

package/cli/src/config/constants.ts

@@ -34,6 +34,16 @@ export const CLI_NPX_BINARY = "npx work-kit-cli";
  */
 export const PROJECT_CONFIG_FILE = ".work-kit-config.json";
 
+// ── Knowledge ───────────────────────────────────────────────────────
+
+/**
+ * Project knowledge directory at the main repo root. Holds curated
+ * lessons/conventions/risks/workflow files. Committed to git; only
+ * KNOWLEDGE_LOCK is gitignored.
+ */
+export const KNOWLEDGE_DIR = ".work-kit-knowledge";
+export const KNOWLEDGE_LOCK = ".lock";
+
 // ── Limits ──────────────────────────────────────────────────────────
 
 export const MAX_LOOPBACKS_PER_ROUTE = 2;

package/cli/src/config/model-routing.test.ts

@@ -0,0 +1,190 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { resolveModel, BY_PHASE, BY_STEP } from "./model-routing.js";
+import type { WorkKitState, ModelPolicy, Classification } from "../state/schema.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `wk-model-routing-${randomUUID()}`);
+  fs.mkdirSync(path.join(dir, ".work-kit"), { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) fs.rmSync(dir, { recursive: true, force: true });
+  tmpDirs = [];
+});
+
+function fakeState(opts: {
+  worktreeRoot: string;
+  policy?: ModelPolicy;
+  classification?: Classification;
+  mode?: "auto-kit" | "full-kit";
+}): Pick<WorkKitState, "modelPolicy" | "classification" | "mode"> & { metadata: { worktreeRoot: string } } {
+  return {
+    modelPolicy: opts.policy,
+    classification: opts.classification,
+    mode: (opts.mode ?? "full-kit") as any,
+    metadata: { worktreeRoot: opts.worktreeRoot },
+  };
+}
+
+describe("resolveModel — defaults", () => {
+  it("uses step default when no policy or override", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+    assert.equal(resolveModel(state, "build", "commit"), "haiku");
+    assert.equal(resolveModel(state, "review", "security"), "opus");
+  });
+
+  it("falls back to phase default for unknown step", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp });
+    // Pick a phase/step that isn't in BY_STEP
+    const key = "plan/__nonexistent__";
+    assert.ok(!(key in BY_STEP));
+    assert.equal(resolveModel(state, "plan", "__nonexistent__"), BY_PHASE.plan);
+  });
+});
+
+describe("resolveModel — session policy", () => {
+  it("policy=opus forces opus for every step, even mechanical ones", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp, policy: "opus" });
+    assert.equal(resolveModel(state, "build", "commit"), "opus");
+    assert.equal(resolveModel(state, "deploy", "monitor"), "opus");
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("policy=haiku forces haiku everywhere", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp, policy: "haiku" });
+    assert.equal(resolveModel(state, "plan", "investigate"), "haiku");
+    assert.equal(resolveModel(state, "review", "security"), "haiku");
+  });
+
+  it("policy=inherit returns undefined so no model is passed", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({ worktreeRoot: tmp, policy: "inherit" });
+    assert.equal(resolveModel(state, "plan", "investigate"), undefined);
+    assert.equal(resolveModel(state, "build", "core"), undefined);
+    assert.equal(resolveModel(state, "deploy", "merge"), undefined);
+  });
+
+  it("policy=auto is equivalent to omitting it", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const autoState = fakeState({ worktreeRoot: tmp, policy: "auto" });
+    const unsetState = fakeState({ worktreeRoot: tmp });
+    assert.equal(
+      resolveModel(autoState, "plan", "investigate"),
+      resolveModel(unsetState, "plan", "investigate")
+    );
+  });
+});
+
+describe("resolveModel — classification", () => {
+  it("small-change knocks plan/investigate down to haiku in auto-kit mode", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "small-change",
+      mode: "auto-kit",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "haiku");
+  });
+
+  it("bug-fix keeps plan/investigate on opus (not in its override map)", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "bug-fix",
+      mode: "auto-kit",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+    assert.equal(resolveModel(state, "plan", "blueprint"), "sonnet");
+  });
+
+  it("refactor promotes review/performance to opus", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "refactor",
+      mode: "auto-kit",
+    });
+    assert.equal(resolveModel(state, "review", "performance"), "opus");
+  });
+
+  it("classification overrides are ignored in full-kit mode", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "small-change",
+      mode: "full-kit",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("session policy beats classification override", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    const state = fakeState({
+      worktreeRoot: tmp,
+      classification: "small-change",
+      mode: "auto-kit",
+      policy: "opus",
+    });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+});
+
+describe("resolveModel — workspace JSON override", () => {
+  it("workspace model-config.json beats session policy", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      JSON.stringify({ "build/commit": "sonnet" })
+    );
+    const state = fakeState({ worktreeRoot: tmp, policy: "opus" });
+    assert.equal(resolveModel(state, "build", "commit"), "sonnet");
+    // Other steps still forced to opus by the policy
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("workspace JSON beats step default", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      JSON.stringify({ "plan/investigate": "haiku" })
+    );
+    const state = fakeState({ worktreeRoot: tmp });
+    assert.equal(resolveModel(state, "plan", "investigate"), "haiku");
+  });
+
+  it("malformed JSON falls back silently to defaults", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      "{not json"
+    );
+    const state = fakeState({ worktreeRoot: tmp });
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+  });
+
+  it("invalid tier values in JSON are ignored", () => {
+    const tmp = makeTmpDir(); tmpDirs.push(tmp);
+    fs.writeFileSync(
+      path.join(tmp, ".work-kit", "model-config.json"),
+      JSON.stringify({ "plan/investigate": "turbo", "build/core": "opus" })
+    );
+    const state = fakeState({ worktreeRoot: tmp });
+    // Bad value ignored → falls back to step default
+    assert.equal(resolveModel(state, "plan", "investigate"), "opus");
+    // Good value applied
+    assert.equal(resolveModel(state, "build", "core"), "opus");
+  });
+});

package/cli/src/config/model-routing.ts

@@ -0,0 +1,208 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import {
+  ModelTier,
+  PhaseName,
+  WorkKitState,
+  Classification,
+  isModelTier,
+} from "../state/schema.js";
+import { STATE_DIR } from "../state/store.js";
+
+/**
+ * Per-phase/step model routing.
+ *
+ * Resolution order (highest precedence first):
+ *   1. Workspace override    .work-kit/model-config.json        (per-session, per-step map)
+ *   2. User global override  ~/.claude/work-kit/models.json     (per-user, all projects)
+ *   3. Session model policy  state.modelPolicy                  (set at init via skill flag)
+ *   4. Classification        BY_CLASSIFICATION (auto-kit only)
+ *   5. Step default          BY_STEP
+ *   6. Phase default         BY_PHASE
+ *   7. Hard default          "sonnet"
+ *
+ * When state.modelPolicy is "inherit" (or layered overrides have not set a
+ * value), resolveModel() returns `undefined` so the orchestrator skill omits
+ * the `model` parameter on the Agent tool — identical to pre-routing behavior.
+ */
+
+const HARD_DEFAULT: ModelTier = "sonnet";
+
+// ── Phase defaults ──────────────────────────────────────────────────
+
+export const BY_PHASE: Record<PhaseName, ModelTier> = {
+  plan: "sonnet",
+  build: "sonnet",
+  test: "sonnet",
+  review: "sonnet",
+  deploy: "haiku",
+  "wrap-up": "sonnet",
+};
+
+// ── Step-level overrides (phase/step keys) ──────────────────────────
+
+export const BY_STEP: Record<string, ModelTier> = {
+  // Plan — research/design-heavy steps benefit from opus
+  "plan/clarify": "sonnet",
+  "plan/investigate": "opus",
+  "plan/sketch": "sonnet",
+  "plan/scope": "sonnet",
+  "plan/ux-flow": "sonnet",
+  "plan/architecture": "opus",
+  "plan/blueprint": "opus",
+  "plan/audit": "opus",
+
+  // Build — mechanical steps drop to haiku, implementation stays sonnet
+  "build/setup": "haiku",
+  "build/migration": "sonnet",
+  "build/red": "sonnet",
+  "build/core": "sonnet",
+  "build/ui": "sonnet",
+  "build/refactor": "sonnet",
+  "build/integration": "sonnet",
+  "build/commit": "haiku",
+
+  // Test — verify is mechanical, e2e/validate need judgment
+  "test/verify": "haiku",
+  "test/e2e": "sonnet",
+  "test/validate": "sonnet",
+
+  // Review — security & compliance get opus; rest sonnet
+  "review/self-review": "sonnet",
+  "review/security": "opus",
+  "review/performance": "sonnet",
+  "review/compliance": "opus",
+  "review/handoff": "sonnet",
+
+  // Deploy — mostly mechanical
+  "deploy/merge": "haiku",
+  "deploy/monitor": "haiku",
+  "deploy/remediate": "sonnet",
+
+  // Wrap-up — synthesis
+  "wrap-up/summary": "sonnet",
+};
+
+// ── Classification overrides (auto-kit only) ────────────────────────
+
+export const BY_CLASSIFICATION: Record<Classification, Partial<Record<string, ModelTier>>> = {
+  "small-change": {
+    // Trivial work: knock plan and reviews down a tier
+    "plan/clarify": "haiku",
+    "plan/investigate": "haiku",
+    "plan/sketch": "haiku",
+    "plan/scope": "haiku",
+    "plan/ux-flow": "haiku",
+    "plan/architecture": "haiku",
+    "plan/blueprint": "haiku",
+    "plan/audit": "haiku",
+    "review/security": "sonnet",
+    "review/compliance": "sonnet",
+  },
+  "bug-fix": {
+    // Bug fixes still need opus for investigate; rest can relax
+    "plan/clarify": "sonnet",
+    "plan/sketch": "sonnet",
+    "plan/scope": "sonnet",
+    "plan/architecture": "sonnet",
+    "plan/blueprint": "sonnet",
+    "plan/audit": "sonnet",
+  },
+  refactor: {
+    // Perf review matters most for refactors — promote it
+    "review/performance": "opus",
+  },
+  feature: {},
+  "large-feature": {},
+};
+
+// ── JSON override loading ───────────────────────────────────────────
+
+type OverrideMap = Partial<Record<string, ModelTier>>;
+
+interface LoadedOverrides {
+  workspace: OverrideMap;
+  userGlobal: OverrideMap;
+}
+
+/**
+ * Read+validate the optional JSON override files. Silently returns empty
+ * maps on any read/parse/validation error — overrides are strictly opt-in
+ * and must never block the workflow.
+ */
+export function loadOverrides(worktreeRoot: string): LoadedOverrides {
+  return {
+    workspace: readJsonMap(path.join(worktreeRoot, STATE_DIR, "model-config.json")),
+    userGlobal: readJsonMap(path.join(os.homedir(), ".claude", "work-kit", "models.json")),
+  };
+}
+
+function readJsonMap(filePath: string): OverrideMap {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const out: OverrideMap = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === "string" && isModelTier(value)) {
+        out[key] = value;
+      }
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+// ── Resolution ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the model tier for a given phase/step in a given session.
+ *
+ * Returns `undefined` when the session policy is "inherit" (or when an
+ * override file explicitly maps to inherit via a missing entry — this does
+ * not happen today but stays consistent with "no opinion" semantics).
+ *
+ * Callers treat `undefined` as "do not pass a model parameter to the Agent
+ * tool" — identical to pre-routing behavior.
+ */
+export function resolveModel(
+  state: Pick<WorkKitState, "modelPolicy" | "classification" | "mode"> & { metadata: { worktreeRoot: string } },
+  phase: PhaseName,
+  step: string
+): ModelTier | undefined {
+  const key = `${phase}/${step}`;
+  const policy = state.modelPolicy ?? "auto";
+
+  // Policy "inherit" short-circuits everything: no model override at all.
+  if (policy === "inherit") {
+    return undefined;
+  }
+
+  // Layers 1 & 2: JSON overrides win over everything else.
+  const overrides = loadOverrides(state.metadata.worktreeRoot);
+  if (overrides.workspace[key]) return overrides.workspace[key];
+  if (overrides.userGlobal[key]) return overrides.userGlobal[key];
+
+  // Layer 3: Forced policy (opus/sonnet/haiku) beats all routing.
+  if (policy !== "auto") {
+    return policy;
+  }
+
+  // Layer 4: Classification override (auto-kit only).
+  if (state.mode === "auto-kit" && state.classification) {
+    const classOverride = BY_CLASSIFICATION[state.classification][key];
+    if (classOverride) return classOverride;
+  }
+
+  // Layer 5: Step default.
+  if (BY_STEP[key]) return BY_STEP[key];
+
+  // Layer 6: Phase default.
+  if (BY_PHASE[phase]) return BY_PHASE[phase];
+
+  // Layer 7: Hard default.
+  return HARD_DEFAULT;
+}