@brainervirus/workit-core 8.24.0 → 8.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "8.24.0",
+  "version": "8.26.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-fanout/SKILL.md

@@ -25,8 +25,8 @@ units of ~100+ lines each. Coupled work stays with one owner. Workit never spawn
    Never hand-edit it; change the plan or the standing orders and render again.
 4. **Spawn in a rolling window**, in the background, each in its own worktree:
    keep 4-6 in flight and refill from `spawnable` in `workit fanout status` as
-   each one finishes. Model: the brief's `model:` line, else TIER
-   (`references/orchestration.md`). Claude Code: the `implementer` agent, never
+   each one finishes. Model: the brief's `model:` and `effort:` lines (`workit models show`),
+   else TIER (`references/orchestration.md`). Claude Code: the `implementer` agent, never
    with `isolation: "worktree"`; Workit's hooks confine it to its WORKTREE.
 5. **Judge liveness by side effects only:** `workit fanout status` (head age,
    PR, CI, verdict, landed; STUCK past the TIMEBOX). Stop a stuck worker and
@@ -40,12 +40,12 @@ units of ~100+ lines each. Coupled work stays with one owner. Workit never spawn
    chain resumes. A fix round and recheck that both fail: a decider, not a
    third round; product choices go to the user (`references/orchestration.md`).
 7. **Verify by the workspace `verification` setting** (`workit grant show`).
-   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused (cheap model: Claude Code `model: sonnet`) and full a verifier after the last push. `self`: a verifier that wrote none
+   A report is a pointer, never evidence. `proportional` (default): each slice's lane (`workit pr status`) decides; none needs no verdict, self the author's `--self`, focused and full a verifier (Claude Code: the `model` and `effort` of `workit models show --role verifier`) after the last push; one verdict at a stack's top covers its unchanged lower PRs, and a stale one with `reverify: focused` re-checks only the new diff, reusing green CI. `self`: a verifier that wrote none
    of the slices, or you if you wrote none. `independent` or high risk: a
    separate verifier session, never yours (doctrine: the ledger only refuses
    authors). One verifier may take a batch of slices, one verdict per branch
    (`workit ledger verdict <result> --branch <b> --how "<evidence>"`), in a
-   session never chosen by the author. A review panel on separate models only at high risk.
+   session never chosen by the author. Spawn it with the brief's `verifier:` model (`workit models show --role verifier`). A review panel on separate models only at high risk.
 8. **Fan in** with `workit fanout check`: out-of-scope files (any file outside
    it stops the fan-in) and `git merge-tree` conflicts with trunk and between
    siblings. Fix what it names until it exits 0; a merged slice reads as

package/skills/workit-fanout/references/brief.md

@@ -25,7 +25,7 @@ REPORT: branch, head SHA, files changed, each VERIFY command with its exit code,
   each ACCEPTANCE line met / not met, rulings you made (`workit ledger ruling`),
   anything out of scope as a follow-up, not a diff.
 STANDING: <the standing orders, verbatim: `workit ledger standing add` records each one>
-WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit --cwd <it> …` there>
+WORKTREE: <the path `workit fanout worktree create <slice>` made; the worker runs `workit <verb> --cwd <it> …` there>
   <identity line, per the lead's host: see "Identity and git rules per host" below>
 ```
 
@@ -114,7 +114,7 @@ lead's host (`WORKIT_HOST`, or the host's own session variable):
 
 Once `workit fanout worktree create <slice>` made the worktree, the brief's
 WORKTREE line names it and RULES 1 and 3 run against it on every host:
-`workit --cwd <worktree> git commit …`, `workit --cwd <worktree> check <name>`,
+`workit git --cwd <worktree> commit …`, `workit check --cwd <worktree> <name>`,
 one verb per call. The worktree is already on the branch (MODE new or resume),
 so no branch command comes first. Without one, `MODE: resume` is
 `git switch <branch>` (the branch exists), then continue from its head. A race
@@ -124,13 +124,13 @@ attempt (`--attempt <n>`) follows its host's row with the branch
 ## Worker rules (`workit fanout brief` appends them as RULES)
 
 1. Work only in WORKTREE, already on the branch, one verb per call against it
-   (`workit --cwd <worktree> …`); Workit's hooks deny an implementer's change
+   (`workit <verb> --cwd <worktree> …`); Workit's hooks deny an implementer's change
    outside it. With no worktree made yet: create the branch (`MODE: new`) or
    `git switch` to it (`MODE: resume`), as the table above says.
 2. Decide ambiguities yourself and record them:
    `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
    Stop only for an irreversible action, a security-sensitive one, or a side
    effect outside the worktree.
-3. Commit with `workit --cwd <worktree> git commit -m "<msg>" -- <paths in SCOPE>`;
+3. Commit with `workit git --cwd <worktree> commit -m "<msg>" -- <paths in SCOPE>`;
    push only if the brief says so.
 4. Never record a verdict on your own work.

package/skills/workit-fanout/references/orchestration.md

@@ -5,22 +5,31 @@ and fans in. Workit records and checks; the host's own subagents run the work.
 
 ## TIER to model
 
-TIER is a field of each slice and of its brief. When the workspace sets
-`fanout.tierModels`, the brief has a `model:` line under TIER and `workit
-fanout status` names the model next to each spawnable slice: use that model.
-Without one, map TIER where the host lets you pick a model per spawn:
-
-| TIER | Claude Code (`model` on the Agent call) | Hosts without a per-spawn model |
-| --- | --- | --- |
-| scouting (read-only search, not a slice) | `haiku` | host default |
-| mundane | `sonnet` | host default |
-| standard | omit it (inherits yours) | host default |
-| hard | omit it (inherits yours); consider a race | host default |
-
-OpenCode takes a subagent's model from its agent config: pick a configured
-agent whose model fits the TIER, else the default. Codex, Cursor and Pi run
-every worker on the host's model, so TIER only sizes the timebox and decides
-whether to race.
+TIER is a field of each slice and of its brief. Role models come from the
+workspace (`models.roles`; `fanout.tierModels` still feeds the implementer
+tiers) and, on Claude Code, built-in defaults: the brief has a `model:` line
+(with `effort:` when set) under TIER and a `verifier:` line; `workit fanout
+status` names the model next to each spawnable slice; `workit models show
+[--role r] [--host h] --json` lists every role (decider, implementer tiers,
+verifier, reviewer, explore, babysit). Pass exactly that `model` (and `effort`
+where the host's spawn call takes one) on the spawn call: a subagent that
+passes none inherits your model. Scouting and PR babysitting use the `explore`
+and `babysit` roles. A role with no model (other hosts without config) runs
+on the host's model, and TIER only sizes the timebox and decides whether to
+race. Claude Code's built-in defaults, when nothing is configured:
+
+| Role or TIER | `model` on the Agent call |
+| --- | --- |
+| decider | `fable`, effort `high` |
+| hard | `opus` |
+| standard | `sonnet` |
+| mundane | `haiku` |
+| verifier | `sonnet` |
+| reviewer | `opus` |
+| explore, babysit | `haiku` |
+
+OpenCode takes a subagent's model from its agent config: pick a
+configured agent whose model fits the TIER, else the default.
 
 ## Rolling window
 
@@ -53,7 +62,7 @@ reversibility (the option cheapest to undo wins a tie), and the exact change
 list. The fixer applies that list once, then one focused recheck follows.
 
 - Hard call (shared contract, security, migration): two deciders on different
-  models (Claude Code: a different `model` on the Agent call; OpenCode: a
+  models (Claude Code: the `decider` role model, the other a different `model` on the Agent call; OpenCode: a
   child session on another configured agent; Codex, Cursor and Pi: one
   decider, since the host picks no model). If they disagree, you take the
   more reversible option.

package/skills/workit-implement/SKILL.md

@@ -40,7 +40,7 @@ description: Build a requested change in small verified steps - follow local pat
    status`). Lane none: no verdict. Lane self: after `workit check test` passes,
    record `workit ledger verdict tests-verified --self --how "<what you ran>"`;
    it reads self-reviewed, never verified, and is enough. Focused, full, high
-   risk or `verification: self|independent` merges: one fresh verifier per PR after the last push, its own host-derived session (Claude Code: the `verifier` agent, `model: sonnet` when focused; Codex:
+   risk or `verification: self|independent` merges: one fresh verifier per PR after the last push, its own host-derived session (Claude Code: the `verifier` agent with the `model` (and `effort`) of `workit models show --role verifier`; Codex:
    the `verifier` agent; OpenCode: a child session; Pi: a supervised worker),
    never a hand-minted id. Before saying done, reconcile
    every named deliverable against the target checkout and observe it (for a push:

package/skills/workit-review/SKILL.md

@@ -9,13 +9,16 @@ Review the candidate, never the author's summary of it. A session that wrote a
 commit on the branch cannot record a passing verdict: if that is you, hand the
 review to a fresh agent with its own host-derived session: Claude Code and
 Codex, the `reviewer` or `verifier` agent (`--session` and `--token` from SubagentStart);
-OpenCode, a child session; Pi, a supervised worker. Never hand-mint one such
+OpenCode, a child session; Pi, a supervised worker. On Claude Code pass the
+`model` and `effort` of `workit models show --role <verifier|reviewer>`. Never hand-mint one such
 as `<lead>-v1`: it is refused as `forged_session`.
 An author's `--self` verdict reads self-reviewed and never counts as
 independent; `type-check-only` never proves a behavior change.
 Depth follows the review lane in `workit pr status`: focused reads the diff and
 runs its tests; full also drives the real surface (verify-<app>). Review once
 per PR after its last push; a second pass on an unchanged head is waste.
+A stale verdict showing `reverify: focused (<files>)` in `workit pr status`: re-check only
+those files since the judged head and reuse green CI there (no fresh install, no full suite).
 
 1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
    for a PR, `workit pr status --json` (checks, unresolved threads).

package/skills/workit-ship/SKILL.md

@@ -51,7 +51,7 @@ the same check. Fix round and recheck both failed: a decider (workit-fanout).
    allows; no sleep loop. Red: read `logTail`, classify. Flake or infra: one
    `workit ci rerun --failed --reason flake|infra` per head. Real: reproduce
    with `workit check`, fix the root cause, batch every fix in one push.
-6. **Verified.** The lane in `workit pr status` decides: none, no verdict; self, your `--self` verdict; focused or full (or `verification: self|independent`), one non-author verifier per PR after the last push, never per push (workit-review), on Claude Code `model: sonnet` when focused. Land only when
+6. **Verified.** The lane in `workit pr status` decides: none, no verdict; self, your `--self` verdict; focused or full (or `verification: self|independent`), one non-author verifier per PR after the last push, never per push (workit-review), on Claude Code with the `model` and `effort` of `workit models show --role verifier`. A docs-only push (or test-only under a unit verdict) keeps the verdict (`carried`); `reverify: focused` re-checks only the new diff, reusing green CI; one verdict at a stack's top covers its unchanged lower PRs. Land only when
    granted: `workit stack land` or `workit pr merge`; `--unverified --reason` if user-asked.
 7. **Observe it landed:** `workit verify-delivery pr` or `merge`. After a failed
    verdict or a check red 3+ times, at any endpoint: offer `/wk-retro` in one

package/src/core/methods.ts

@@ -125,7 +125,7 @@ Autonomy contract:
 CLI first: if a step has one right answer, use the \`workit\` verb instead of
 hand-running git, gh or glab (\`workit git|pr|ci|check|help\`;
 else \`npx -y @brainervirus/workit-cli\`).
-Other checkout: \`workit --cwd <dir> <verb>\` (Codex: \`<verb> --cwd <dir>\`); one workit
+Other checkout: \`workit <verb> --cwd <dir> …\` (verb first: host rules match it); one workit
 verb per shell call, never \`cd <dir> && workit\`. zsh-safe: no \`echo =====\`
 (\`printf '%s\\n' ---\`), quote globs and URLs, no variable named \`status\` or \`path\`.
 Add Co-Authored-By via \`workit git commit --trailer "K: v" -- <paths>\`, never
@@ -137,7 +137,7 @@ authorizes an effect. Judge work once with
 \`workit policy assess --judge risk= behavior= product-choice= plan=\`.
 Across repositories, bind items to checkout, branch and endpoint, resolve
 competing targets before a mutation, and reconcile an uncertain
-external effect before a retry.
+effect before a retry.
 
 Mid-task: never silently drop or resume an objective (workit-continue).
 

package/src/core/policy/carry.ts

@@ -0,0 +1,74 @@
+// Verdict carry-over across a follow-up change (#334, decision mvk5q3io): a
+// verdict judged head H; the branch is now at H'. The branch's own change
+// since H (what came from the base left out, see lane.ts driftFiles) is
+// classified with the review lane, and the verdict still applies when:
+//
+//   lane-none   that change is lane `none`: docs, comment or formatting-only
+//               edits, generated copies (by the base's .gitattributes), or
+//               nothing at all (an empty commit);
+//   tests-only  the verdict is kind `unit` and the change is lane `self`
+//               (small) with every behavior file a test: test files off risk
+//               paths, no lockfile, no binary.
+//
+// Everything else is stale, failing closed: a behavior or risk-path change,
+// an opaque file, an unreadable diff, a judged head git no longer has. A
+// stale verdict whose change is lane `self` (small, no risk path, nothing
+// opaque) asks only a focused re-verify of the changed files.
+import { mergeBase, fileAt } from "../../git/rev";
+import { computeLane, driftFiles, kindOf, parseRiskPaths, RISK_PATHS_FILE } from "./lane";
+
+export type CarryRule = "lane-none" | "tests-only";
+
+export type Drift =
+  | { carries: true; rule: CarryRule; since: string; files: string[] }
+  | {
+      carries: false;
+      since: string;
+      /** The changed files, or null when they cannot be read. */
+      files: string[] | null;
+      /** A focused re-verify of `files` is enough (lane self). */
+      focused: boolean;
+      reason: string;
+    };
+
+const TEST_ONLY_KINDS: ReadonlySet<string> = new Set(["doc", "cosmetic", "generated", "test"]);
+
+/**
+ * Whether a `kind` verdict at `from` (keyed against `fromBase`, a commit)
+ * still applies at `to` (against `toBase`).
+ */
+export function verdictDrift(
+  cwd: string,
+  input: { from: string; to: string; fromBase: string; toBase: string; kind: string },
+): Drift {
+  const since = input.from;
+  const stale = (reason: string, files: string[] | null = null, focused = false): Drift => ({
+    carries: false,
+    since,
+    files,
+    focused,
+    reason,
+  });
+  const fromFork = mergeBase(cwd, input.fromBase, input.from);
+  const toFork = mergeBase(cwd, input.toBase, input.to);
+  const files =
+    fromFork && toFork
+      ? driftFiles(cwd, { from: input.from, to: input.to, fromFork, toFork })
+      : null;
+  if (!fromFork || !toFork || !files)
+    return stale(`the change since ${since.slice(0, 12)} cannot be read`);
+  // Repo risk paths from both base revisions: they only tighten.
+  const riskPaths = [fromFork, toFork].flatMap((fork) =>
+    parseRiskPaths(fileAt(cwd, fork, RISK_PATHS_FILE) ?? ""),
+  );
+  const lane = computeLane({ files, riskPaths });
+  const paths = files.map((file) => file.path);
+  if (lane.lane === "none") return { carries: true, rule: "lane-none", since, files: paths };
+  if (
+    input.kind === "unit" &&
+    lane.lane === "self" &&
+    files.every((file) => TEST_ONLY_KINDS.has(kindOf(file)))
+  )
+    return { carries: true, rule: "tests-only", since, files: paths };
+  return stale(lane.reasons[0] ?? `lane ${lane.lane}`, paths, lane.lane === "self");
+}

package/src/core/policy/lane.ts

@@ -25,15 +25,18 @@ import {
   diffNumstat,
   diffRaw,
   fileAt,
+  isTracked,
   mergeBase,
+  ownChangeDrift,
   readBlobs,
   resolveRef,
   treeFilesNamed,
   untrackedFiles,
+  worktreeTop,
 } from "../../git/rev";
 import type { VerificationMode } from "../../autonomy";
-import { git } from "../../git/ops";
-import { defaultBase, type VerdictCheck } from "../../ledger";
+import { defaultBase } from "../../git/default-base";
+import type { VerdictCheck } from "../../ledger";
 import { generatedByAttributes } from "./attributes";
 import { cosmeticChange, hasOpaqueLineBreak } from "./substance";
 
@@ -117,14 +120,21 @@ const LOCKFILES = new Set([
   "composer.lock",
 ]);
 
-/** Docs are told by extension only: code under `docs/` is code. */
-const DOC_EXT = /\.(?:md|mdx|markdown|rst|adoc|txt)$/iu;
+/**
+ * Docs are told by prose extension only: code under `docs/` is code. `.txt`
+ * is not a doc: requirements.txt, CMakeLists.txt or robots.txt change behavior.
+ */
+const DOC_EXT = /\.(?:md|mdx|markdown|rst|adoc)$/iu;
 const DOC_NAMES = /^(?:license|licence|notice|authors|changelog|changes|contributors)$/iu;
 /** Markdown that steers agents is behavior, not docs. */
 const INSTRUCTIONS =
   /(?:^|\/)(?:AGENTS|CLAUDE|GEMINI|SKILL)\.md$|(?:^|\/)(?:skills|agents|commands|rules|prompts)\/[^/]+/iu;
-const TEST_PATH =
-  /(?:^|\/)(?:test|tests|__tests__|spec|specs|fixtures)\/|\.(?:test|spec)\.[^/]+$/iu;
+/**
+ * A test file: under a `test/`, `tests/` or `__tests__/` folder, or named
+ * `*.test.*`, `*.spec.*` or `*_test.*`. A `fixtures/` or `spec/` folder can
+ * hold runtime data or code, so it is not a test path (it reads as behavior).
+ */
+const TEST_PATH = /(?:^|\/)(?:test|tests|__tests__)\/|\.(?:test|spec)\.[^/]+$|_test\.[^/]+$/iu;
 
 export type ChangedFile = {
   path: string;
@@ -156,7 +166,7 @@ export type LaneAssessment = {
   riskFiles: string[];
 };
 
-type FileKind = "doc" | "cosmetic" | "generated" | "lockfile" | "test" | "behavior";
+export type FileKind = "doc" | "cosmetic" | "generated" | "lockfile" | "test" | "behavior";
 
 const basename = (file: string): string => file.slice(file.lastIndexOf("/") + 1);
 
@@ -165,7 +175,7 @@ const isDoc = (file: string): boolean =>
   !INSTRUCTIONS.test(file) && (DOC_EXT.test(file) || DOC_NAMES.test(basename(file)));
 
 /** What a file off risk paths is; risk paths are decided before (see computeLane). */
-function kindOf(file: ChangedFile): FileKind {
+export function kindOf(file: ChangedFile): FileKind {
   if (file.binary) return "behavior";
   if (file.generated) return "generated";
   if (LOCKFILES.has(basename(file.path))) return "lockfile";
@@ -360,7 +370,13 @@ function generatedAt(cwd: string, fork: string, paths: readonly string[]): Set<s
 const forkOf = (cwd: string, base: string, head: string | null): string | null =>
   mergeBase(cwd, base, head ?? "HEAD");
 
-function laneFiles(cwd: string, fork: string, head: string | null): ChangedFile[] | null {
+/** The files of `fork..head`; generated copies are read from `attributesAt` (the base revision). */
+function laneFiles(
+  cwd: string,
+  fork: string,
+  head: string | null,
+  attributesAt: string = fork,
+): ChangedFile[] | null {
   const stats = diffNumstat(cwd, fork, head);
   const cosmetic = stats ? cosmeticFiles(cwd, fork, head) : null;
   if (!stats || !cosmetic) return null;
@@ -374,7 +390,7 @@ function laneFiles(cwd: string, fork: string, head: string | null): ChangedFile[
   ];
   const generated = generatedAt(
     cwd,
-    fork,
+    attributesAt,
     files.map((entry) => entry.path),
   );
   return files.map((entry) => ({
@@ -383,6 +399,41 @@ function laneFiles(cwd: string, fork: string, head: string | null): ChangedFile[
   }));
 }
 
+/**
+ * The files whose own change differs between two versions of a branch: the
+ * judged `from` (forked from `fromFork`) and the current `to` (forked from
+ * `toFork`). Generated copies are read from `toFork` only.
+ *
+ * - Same fork: the plain `from..to` diff, comments and formatting read as
+ *   in the lane.
+ * - Moved fork (a rebase): each file the branch touches is compared by exact
+ *   blob (see ownChangeDrift): it counts when the branch's resulting file
+ *   differs, or when the base changed it too between the forks. Their lines
+ *   come from `from..to`, which may include base edits (over-counting is the
+ *   safe direction), and none is cosmetic.
+ *
+ * Null when git cannot read either side.
+ */
+export function driftFiles(
+  cwd: string,
+  range: { from: string; to: string; fromFork: string; toFork: string },
+): ChangedFile[] | null {
+  if (range.fromFork === range.toFork) return laneFiles(cwd, range.from, range.to, range.toFork);
+  const drifted = ownChangeDrift(cwd, range);
+  const stats = drifted ? diffNumstat(cwd, range.from, range.to) : null;
+  if (!drifted || !stats) return null;
+  const byPath = new Map(stats.map((entry) => [entry.path, entry]));
+  const generated = generatedAt(cwd, range.toFork, drifted);
+  return drifted.map((file) => ({
+    path: file,
+    added: byPath.get(file)?.added ?? 0,
+    deleted: byPath.get(file)?.deleted ?? 0,
+    ...(byPath.get(file)?.binary ? { binary: true } : {}),
+    cosmetic: false,
+    generated: generated.has(file),
+  }));
+}
+
 /**
  * The changed files of `merge-base(base, head)..head`, or with `head` null
  * of the working tree (tracked changes plus untracked files) since
@@ -455,11 +506,9 @@ export function branchLane(
  * it is committed there. Null when there is nothing to warn about.
  */
 export function untrackedRiskPathsWarning(cwd: string): string | null {
-  const top = git(cwd, ["rev-parse", "--show-toplevel"]);
-  const root = top.ok ? top.stdout.trim() : "";
+  const root = worktreeTop(cwd);
   if (!root || !existsSync(path.join(root, RISK_PATHS_FILE))) return null;
-  const tracked = git(root, ["ls-files", "--error-unmatch", "--", RISK_PATHS_FILE]);
-  return tracked.ok
+  return isTracked(root, RISK_PATHS_FILE)
     ? null
     : `${RISK_PATHS_FILE} is not committed: it does not apply until it is committed on the base branch`;
 }

package/src/core/role-models.ts

@@ -0,0 +1,209 @@
+// Role models (#395): the model and effort a role runs on, per host.
+//
+// `models.roles` in workspaces.json (top level = global default, per
+// workspace = override, nested workspaces inherit like `fanout.tierModels`):
+//
+//   { "decider": { "claude_code": { "model": "fable", "effort": "high" } },
+//     "implementer": { "hard": { "claude_code": "opus" }, "standard": … },
+//     "verifier": { "claude_code": "sonnet", "default": "…" } }
+//
+// A role maps to a per-host object (keys: claude_code, opencode, codex,
+// cursor, pi, default) whose values are a model name or `{ model, effort? }`.
+// A bare model name or `{ model, effort? }` applies to every host. The
+// implementer takes one such value per fanout tier. `fanout.tierModels` is
+// read as the implementer tiers (a model name per tier and host, no effort);
+// within one workspace `models.roles` wins over it. Everything is read
+// leniently: a malformed entry is skipped and reported (`roleModelIssues`),
+// never an error. Claude Code has built-in defaults; other hosts inherit
+// their own default model when nothing is configured.
+import { hostFamily, modelSources } from "./workspaces";
+
+export const MODEL_ROLES = [
+  "decider",
+  "implementer",
+  "verifier",
+  "reviewer",
+  "explore",
+  "babysit",
+] as const;
+export type ModelRole = (typeof MODEL_ROLES)[number];
+export const MODEL_TIERS = ["mundane", "standard", "hard"] as const;
+export type ModelTier = (typeof MODEL_TIERS)[number];
+
+export type RoleSelector = { role: ModelRole; tier?: ModelTier };
+export type RoleModel = { model: string; effort: string | null; source: string };
+
+const HOST_KEYS = new Set([
+  "claude_code",
+  "opencode",
+  "codex",
+  "codex_cli",
+  "codex_desktop",
+  "cursor",
+  "pi",
+  "default",
+]);
+
+const BUILT_IN_CLAUDE_CODE: Record<string, { model: string; effort?: string }> = {
+  decider: { model: "fable", effort: "high" },
+  "implementer.hard": { model: "opus" },
+  "implementer.standard": { model: "sonnet" },
+  "implementer.mundane": { model: "haiku" },
+  verifier: { model: "sonnet" },
+  reviewer: { model: "opus" },
+  explore: { model: "haiku" },
+  babysit: { model: "haiku" },
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+const name = (value: unknown): string | null =>
+  typeof value === "string" && value.trim() ? value.trim() : null;
+
+/** `"model"` or `{ model, effort? }` as a model and effort; null when it names no model. */
+const leaf = (value: unknown): { model: string; effort: string | null } | null => {
+  const text = name(value);
+  if (text) return { model: text, effort: null };
+  if (!isObject(value)) return null;
+  const model = name(value.model);
+  return model ? { model, effort: name(value.effort) } : null;
+};
+
+const isFlat = (value: unknown): boolean =>
+  typeof value === "string" || (isObject(value) && Object.hasOwn(value, "model"));
+
+/** The value for `host` in a per-host object (or a flat value for every host). */
+const forHost = (value: unknown, host: string | null) => {
+  if (isFlat(value)) return leaf(value);
+  if (!isObject(value)) return null;
+  const family = host ? hostFamily(host) : null;
+  for (const key of [family, host, "default"])
+    if (key && Object.hasOwn(value, key)) {
+      const found = leaf(value[key]);
+      if (found) return found;
+    }
+  return null;
+};
+
+const rolesOf = (models: unknown): Record<string, unknown> | null =>
+  isObject(models) && isObject(models.roles) ? models.roles : null;
+
+/**
+ * The model and effort for a role on a host, or null (the host's own default
+ * applies). Order: the selected workspace, each enclosing workspace, the
+ * global default (each: `models.roles`, then `fanout.tierModels` for an
+ * implementer tier), then Claude Code's built-in defaults.
+ */
+export const resolveRoleModel = (
+  cwd: string,
+  selector: RoleSelector,
+  host: string | null,
+  dir?: string,
+): RoleModel | null => {
+  const { role, tier } = selector;
+  for (const source of modelSources(cwd, dir)) {
+    const where = source.global ? "the global default" : `workspace ${source.name}`;
+    const roles = rolesOf(source.models);
+    const configured = roles && Object.hasOwn(roles, role) ? roles[role] : undefined;
+    const fromRoles =
+      role === "implementer"
+        ? tier && isObject(configured) && Object.hasOwn(configured, tier)
+          ? forHost(configured[tier], host)
+          : null
+        : forHost(configured, host);
+    if (fromRoles) return { ...fromRoles, source: `models.roles in ${where}` };
+    if (role === "implementer" && tier && isObject(source.tierModels)) {
+      const fromTiers = Object.hasOwn(source.tierModels, tier)
+        ? forHost(source.tierModels[tier], host)
+        : null;
+      if (fromTiers)
+        return { model: fromTiers.model, effort: null, source: `fanout.tierModels in ${where}` };
+    }
+  }
+  if (host && hostFamily(host) === "claude_code") {
+    const builtIn = BUILT_IN_CLAUDE_CODE[tier ? `${role}.${tier}` : role];
+    if (builtIn)
+      return { model: builtIn.model, effort: builtIn.effort ?? null, source: "built-in" };
+  }
+  return null;
+};
+
+/**
+ * The implementer model when a host's agent serves every fanout tier (a Codex
+ * agent file, a Pi worker): set only when all three tiers resolve to the same
+ * model and effort, else null (the spawn or session decides per slice).
+ */
+export const uniformImplementerModel = (
+  cwd: string,
+  host: string | null,
+  dir?: string,
+): RoleModel | null => {
+  const tiers = MODEL_TIERS.map((tier) =>
+    resolveRoleModel(cwd, { role: "implementer", tier }, host, dir),
+  );
+  const [first] = tiers;
+  return first && tiers.every((t) => t?.model === first.model && t.effort === first.effort)
+    ? first
+    : null;
+};
+
+/** Every selector `models show` lists, in role order. */
+export const ROLE_SELECTORS: RoleSelector[] = MODEL_ROLES.flatMap((role): RoleSelector[] =>
+  role === "implementer" ? MODEL_TIERS.map((tier) => ({ role, tier })) : [{ role }],
+);
+
+const valueIssues = (where: string, value: unknown, out: string[]): void => {
+  if (isFlat(value)) {
+    if (!leaf(value)) out.push(`${where}.model: not a model name; ignored`);
+    if (isObject(value) && value.effort !== undefined && !name(value.effort))
+      out.push(`${where}.effort: not an effort name; ignored`);
+    return;
+  }
+  if (!isObject(value)) {
+    out.push(`${where}: not a model name or a per-host object; ignored`);
+    return;
+  }
+  for (const [host, entry] of Object.entries(value)) {
+    if (!HOST_KEYS.has(host)) out.push(`${where}.${host}: unknown host; ignored`);
+    else {
+      if (!leaf(entry)) out.push(`${where}.${host}.model: not a model name; ignored`);
+      if (isObject(entry) && entry.effort !== undefined && !name(entry.effort))
+        out.push(`${where}.${host}.effort: not an effort name; ignored`);
+    }
+  }
+};
+
+/**
+ * What `models.roles` holds that Workit ignores (an unknown role, tier or
+ * host, a value that is not a model name or effort), across the global
+ * default and every workspace matching cwd. `workit doctor` and `workit grant
+ * show` report them.
+ */
+export const roleModelIssues = (cwd: string, dir?: string): string[] => {
+  const issues: string[] = [];
+  for (const source of modelSources(cwd, dir)) {
+    if (source.models === undefined) continue;
+    const base = `${source.global ? "global default" : `workspace ${source.name}`} models.roles`;
+    if (
+      !isObject(source.models) ||
+      (source.models.roles !== undefined && !rolesOf(source.models))
+    ) {
+      issues.push(`${base} is not an object; ignored`);
+      continue;
+    }
+    for (const [role, value] of Object.entries(rolesOf(source.models) ?? {})) {
+      const where = `${base}.${role}`;
+      if (!(MODEL_ROLES as readonly string[]).includes(role))
+        issues.push(`${base}.${role}: unknown role; ignored`);
+      else if (role === "implementer") {
+        if (!isObject(value)) issues.push(`${where}: not an object keyed by tier; ignored`);
+        else
+          for (const [tier, entry] of Object.entries(value))
+            if (!(MODEL_TIERS as readonly string[]).includes(tier))
+              issues.push(`${where}.${tier}: unknown tier; ignored`);
+            else valueIssues(`${where}.${tier}`, entry, issues);
+      } else valueIssues(where, value, issues);
+    }
+  }
+  return issues;
+};