@ericrisco/rsc 0.1.21 → 0.1.23

package/README.md

@@ -150,6 +150,11 @@ rsc consult "I want to launch a SaaS"  # recommend only, no install
 rsc registry refresh                 # write .rsc/skill-registry.{json,md}
 rsc list                             # what rsc has installed
 rsc doctor                           # health check (state, hook, counts)
+rsc sync --target claude,codex       # refresh managed skills/hooks from the current package version
+rsc backups                          # list project-local snapshots
+rsc restore latest --dry-run         # preview restoring the newest snapshot
+rsc restore <snapshot-id>            # restore a project-local snapshot
+rsc upgrade --dry-run                # show npm upgrade + sync commands
 rsc uninstall postgresdb --dry-run   # preview a removal
 ```
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.21",
+  "version": "0.1.23",
   "counts": {
     "skills": 231
   },
@@ -3666,7 +3666,7 @@
     },
     {
       "id": "sdd",
-      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'de la idea a producción'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill.",
+      "description": "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'de la idea a producción', 'per-phase model routing', 'use a cheaper model for implementation', 'qué modelo por fase'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill.",
       "tags": [
         "sdd",
         "spec",
@@ -3685,7 +3685,7 @@
     },
     {
       "id": "sdd-init",
-      "description": "Use when calibrating an existing repo before running the rsc SDD flow: detecting stack, package manager, test runners, lint/type/build commands, monorepo signals, artifact store, execution mode, review budget, strict TDD capability, and project skill registry. Triggers: 'calibrate this repo for SDD', 'run sdd init', 'detect my test runner before implementing', 'set up SDD config', 'prepare this repo for spec-driven development'. NOT first-contact user/workspace bootstrap (init), NOT 01-TOOLS/02-DOCS scaffolding (harness), NOT writing a feature spec (specify).",
+      "description": "Use when calibrating an existing repo before running the rsc SDD flow: detecting stack, package manager, test runners, lint/type/build commands, monorepo signals, artifact store, execution mode, review budget, strict TDD capability, and project skill registry. Triggers: 'calibrate this repo for SDD', 'run sdd init', 'detect my test runner before implementing', 'set up SDD config', 'prepare this repo for spec-driven development', 'configure per-phase model routing', 'assign models per SDD phase', 'set up cheaper model for implementation'. NOT first-contact user/workspace bootstrap (init), NOT 01-TOOLS/02-DOCS scaffolding (harness), NOT writing a feature spec (specify).",
       "tags": [
         "sdd",
         "init",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -1,18 +1,27 @@
 import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { targetPaths } from '../targets/index.js';
 import { readState } from './lib/state.js';
 import { loadManifest } from './lib/manifest.js';
+import { listBackups } from './lib/backups.js';
 
 export function doctor({ target, home, cwd }) {
+  const root = cwd || process.cwd();
   const paths = targetPaths(target, home, cwd);
   const state = readState(paths.stateFile);
   const manifest = loadManifest();
+  const backups = listBackups({ cwd: root });
   const report = {
     target,
     installed: Object.keys(state.skills),
     missing: [],
     hookWired: existsSync(paths.hookTarget),
     manifestSkills: manifest.counts.skills,
+    backups: {
+      exists: existsSync(join(root, '.rsc', 'backups')),
+      count: backups.length,
+      latest: backups[0]?.id || null,
+    },
   };
   for (const [id, e] of Object.entries(state.skills)) {
     for (const f of e.files) if (!existsSync(f)) report.missing.push(`${id}:${f}`);

package/scripts/install-apply.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url';
 import { planInstall } from './install-plan.js';
 import { targetPaths, writeSkill, wireHook, unwireHook, baseDir, TARGET_IDS } from '../targets/index.js';
 import { readState, writeState } from './lib/state.js';
+import { createBackup } from './lib/backups.js';
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const CLI_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
@@ -32,10 +33,37 @@ function ensureBase(id, cwd, refresh) {
   return dest;
 }
 
-export async function applyInstall({ skillIds, target, home, cwd = process.cwd() }) {
+function generatedHookFiles({ target, cwd }) {
+  if (target !== 'claude') return [];
+  return [
+    join(cwd, '.rsc', 'session-start.mjs'),
+    join(cwd, '.rsc', 'worklog-checkpoint.mjs'),
+    join(cwd, '.rsc', 'ship-guard.mjs'),
+    join(cwd, '.rsc', 'danger-guard.mjs'),
+  ];
+}
+
+function managedPathsForInstall({ skillIds, target, home, cwd }) {
+  const paths = targetPaths(target, home, cwd);
+  const plan = planInstall({ skillIds, target, home, cwd });
+  const out = [paths.stateFile, versionFile(cwd)];
+  for (const step of plan) {
+    if (step.kind === 'skill') {
+      out.push(step.to, baseDir(step.id, cwd));
+    } else if (step.kind === 'hook') {
+      out.push(step.to, ...generatedHookFiles({ target, cwd }));
+    }
+  }
+  return [...new Set(out)];
+}
+
+export async function applyInstall({ skillIds, target, home, cwd = process.cwd(), operation = 'install', dryRun = false }) {
   const paths = targetPaths(target, home, cwd);
   const plan = planInstall({ skillIds, target, home, cwd });
+  const managedPaths = managedPathsForInstall({ skillIds, target, home, cwd });
+  if (dryRun) return { dryRun: true, skills: skillIds, paths: managedPaths };
   const state = readState(paths.stateFile);
+  const backup = createBackup({ cwd, operation, target, paths: managedPaths, cliVersion: CLI_VERSION });
   // Refresh bases when installing a different version than they were materialized at
   // (or a pre-versioning install where the marker is absent). Same version → no-op.
   const refresh = readBaseVersion(cwd) !== CLI_VERSION;
@@ -52,7 +80,7 @@ export async function applyInstall({ skillIds, target, home, cwd = process.cwd()
   writeState(paths.stateFile, state);
   mkdirSync(dirname(versionFile(cwd)), { recursive: true });
   writeFileSync(versionFile(cwd), CLI_VERSION + '\n');
-  return state;
+  return { ...state, backup };
 }
 
 export function listInstalled({ target, home, cwd = process.cwd() }) {
@@ -64,23 +92,52 @@ export async function uninstall({ skillIds, target, home, cwd = process.cwd(), d
   const paths = targetPaths(target, home, cwd);
   const state = readState(paths.stateFile);
   const removed = [];
+  const managedPaths = [paths.stateFile];
   for (const id of skillIds) {
     const entry = state.skills[id];
     if (!entry) continue;
     for (const f of entry.files) {
+      managedPaths.push(f);
       removed.push(f);
-      if (!dryRun && existsSync(f)) rmSync(f, { recursive: true, force: true });
     }
-    if (!dryRun) delete state.skills[id];
   }
-  if (!dryRun) writeState(paths.stateFile, state);
+  if (!removed.length) return removed;
+  if (dryRun) return removed;
+  createBackup({ cwd, operation: 'uninstall', target, paths: managedPaths, cliVersion: CLI_VERSION });
+  for (const id of skillIds) {
+    const entry = state.skills[id];
+    if (!entry) continue;
+    for (const f of entry.files) {
+      if (existsSync(f)) rmSync(f, { recursive: true, force: true });
+    }
+    delete state.skills[id];
+  }
+  writeState(paths.stateFile, state);
   return removed;
 }
 
+export async function syncInstalled({ target, home, cwd = process.cwd(), dryRun = false }) {
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const ids = Object.keys(state.skills || {});
+  if (!ids.length) return dryRun ? { dryRun: true, synced: [], paths: [] } : { synced: [], backup: null };
+  if (dryRun) {
+    return {
+      dryRun: true,
+      synced: ids,
+      paths: managedPathsForInstall({ skillIds: ids, target, home, cwd }),
+    };
+  }
+  const nextState = await applyInstall({ skillIds: ids, target, home, cwd, operation: 'sync' });
+  return { synced: ids, backup: nextState.backup };
+}
+
 // Remove EVERYTHING rsc put in this project: installed skills across all targets,
 // the wired hooks (settings.json entries / AGENTS-blocks / cursor rules), and the
 // shared `.rsc/` (base + hook scripts + version marker). `02-DOCS/` is the user's
 // own knowledge — kept unless `withDocs` is set. Returns the paths touched.
+// Note: backups live under `.rsc/backups/`, which this removes — so purge does not
+// snapshot (a pre-purge backup would delete itself). It is the deliberate escape hatch.
 export async function purge({ home, cwd = process.cwd(), withDocs = false, dryRun = false } = {}) {
   const removed = [];
   const drop = (p, recursive = false) => {

package/scripts/lib/backups.js

@@ -0,0 +1,154 @@
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+
+const SCHEMA_VERSION = 1;
+
+export function backupsDir(cwd = process.cwd()) {
+  return join(cwd, '.rsc', 'backups');
+}
+
+export function createBackup({ cwd = process.cwd(), operation, target, paths, cliVersion, now = new Date() }) {
+  const uniquePaths = [...new Set((paths || []).filter(Boolean))];
+  const id = uniqueSnapshotId({ cwd, now, operation, target });
+  const root = join(backupsDir(cwd), id);
+  const filesRoot = join(root, 'files');
+  mkdirSync(filesRoot, { recursive: true });
+
+  const entries = uniquePaths.map((absPath) => snapshotEntry({ cwd, root, absPath }));
+  const manifest = {
+    schemaVersion: SCHEMA_VERSION,
+    id,
+    createdAt: now.toISOString(),
+    operation,
+    target,
+    cwd,
+    cliVersion,
+    entries,
+  };
+  writeFileSync(join(root, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  return manifest;
+}
+
+export function listBackups({ cwd = process.cwd() } = {}) {
+  const dir = backupsDir(cwd);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .map((id) => readManifest({ cwd, id }))
+    .filter(Boolean)
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+}
+
+export function restoreBackup({ cwd = process.cwd(), id, dryRun = false }) {
+  const snapshot = resolveSnapshot({ cwd, id });
+  const changed = [];
+  for (const entry of snapshot.entries) {
+    const absPath = safeJoin(cwd, entry.path);
+    changed.push(absPath);
+    if (dryRun) continue;
+    restoreEntry({ cwd, snapshot, entry, absPath });
+  }
+  return { snapshot, changed };
+}
+
+function snapshotEntry({ cwd, root, absPath }) {
+  const rel = safeRelative(cwd, absPath);
+  if (!existsSync(absPath)) return { path: rel, existed: false, kind: 'missing' };
+
+  const stat = lstatSync(absPath);
+  if (stat.isSymbolicLink()) {
+    return { path: rel, existed: true, kind: 'symlink', linkTarget: readlinkSync(absPath) };
+  }
+
+  const contentPath = join('files', rel);
+  const contentAbs = join(root, contentPath);
+  mkdirSync(dirname(contentAbs), { recursive: true });
+  if (stat.isDirectory()) {
+    cpSync(absPath, contentAbs, { recursive: true });
+    return { path: rel, existed: true, kind: 'dir', contentPath };
+  }
+
+  cpSync(absPath, contentAbs);
+  return { path: rel, existed: true, kind: 'file', contentPath };
+}
+
+function restoreEntry({ cwd, snapshot, entry, absPath }) {
+  if (!entry.existed) {
+    rmSync(absPath, { recursive: true, force: true });
+    return;
+  }
+
+  rmSync(absPath, { recursive: true, force: true });
+  mkdirSync(dirname(absPath), { recursive: true });
+  if (entry.kind === 'symlink') {
+    symlinkSync(entry.linkTarget, absPath, process.platform === 'win32' ? 'junction' : undefined);
+    return;
+  }
+
+  const contentAbs = join(backupsDir(cwd), snapshot.id, entry.contentPath);
+  cpSync(contentAbs, absPath, { recursive: entry.kind === 'dir' });
+}
+
+function resolveSnapshot({ cwd, id }) {
+  if (!id) throw new Error('restore requires a snapshot id or latest');
+  if (id === 'latest') {
+    const latest = listBackups({ cwd })[0];
+    if (!latest) throw new Error('no backups found');
+    return latest;
+  }
+
+  const manifest = readManifest({ cwd, id });
+  if (!manifest) throw new Error(`backup not found: ${id}`);
+  return manifest;
+}
+
+function readManifest({ cwd, id }) {
+  const path = join(backupsDir(cwd), id, 'manifest.json');
+  if (!existsSync(path)) return undefined;
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function uniqueSnapshotId({ cwd, now, operation, target }) {
+  const base = snapshotId({ now, operation, target });
+  let id = base;
+  let counter = 2;
+  while (existsSync(join(backupsDir(cwd), id))) {
+    id = `${base}-${counter}`;
+    counter += 1;
+  }
+  return id;
+}
+
+function snapshotId({ now, operation, target }) {
+  const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\..*/, '').replace('T', '-');
+  return `${stamp}-${safeId(operation)}-${safeId(target || 'all')}`;
+}
+
+function safeId(value) {
+  return String(value).replace(/[^a-z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase();
+}
+
+function safeRelative(cwd, absPath) {
+  const rel = relative(cwd, absPath);
+  if (!rel || rel.startsWith('..') || rel.split(sep).includes('..')) {
+    throw new Error(`path is outside project root: ${absPath}`);
+  }
+  return rel.split(sep).join('/');
+}
+
+function safeJoin(cwd, relPath) {
+  if (!relPath || isAbsolute(relPath) || relPath.split('/').includes('..')) {
+    throw new Error(`path is outside project root: ${relPath}`);
+  }
+  return join(cwd, ...relPath.split('/'));
+}

package/scripts/lib/upgrade.js

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process';
+
+export function upgradePlan({ targets = [] } = {}) {
+  const targetArg = targets.length ? targets.join(',') : '<target>';
+  return {
+    installCommand: 'npm install -g @ericrisco/rsc@latest',
+    syncCommand: `rsc sync --target ${targetArg}`,
+  };
+}
+
+export function runUpgrade({ targets = [], dryRun = false, global = false } = {}) {
+  const plan = upgradePlan({ targets });
+  if (dryRun || !global) return { ran: false, plan };
+
+  const result = spawnSync('npm', ['install', '-g', '@ericrisco/rsc@latest'], { stdio: 'inherit' });
+  if (result.status !== 0) throw new Error('npm global upgrade failed');
+  return { ran: true, plan };
+}

package/scripts/rsc.js

@@ -4,12 +4,14 @@ import { detectTarget, TARGETS } from '../targets/index.js';
 import { detectRepo } from './detect-repo.js';
 import { rank } from './consult.js';
 import { expandRecommends, toOutcomes, hasOutcome } from './lib/recommend.js';
-import { applyInstall, listInstalled, uninstall, purge } from './install-apply.js';
+import { applyInstall, listInstalled, uninstall, syncInstalled, purge } from './install-apply.js';
 import { doctor } from './doctor.js';
 import { say, select, pickFrom, banner, confirm } from './lib/ui.js';
 import { refreshRegistry, registryStatus } from './lib/registry.js';
 import { audit, writeAuditReport } from './audit.js';
 import { DOMAINS } from './lib/domains.js';
+import { listBackups, restoreBackup } from './lib/backups.js';
+import { runUpgrade } from './lib/upgrade.js';
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];
@@ -200,6 +202,43 @@ async function main() {
       return void say(listInstalled({ target }).join('\n') || '(nothing installed)');
     case 'doctor':
       return void say(JSON.stringify(doctor({ target }), null, 2));
+    case 'sync': {
+      const dry = argv.includes('--dry-run');
+      for (const t of targets) {
+        const result = await syncInstalled({ target: t, dryRun: dry });
+        const verb = dry ? 'Would sync' : 'Synced';
+        say(`${verb} ${t}: ${result.synced.length ? result.synced.join(', ') : '(nothing to sync)'}`);
+        if (dry && result.paths?.length) {
+          for (const p of result.paths) say(`  ${p}`);
+        }
+      }
+      return;
+    }
+    case 'backups': {
+      const backups = listBackups();
+      if (!backups.length) return void say('(no backups)');
+      for (const b of backups) {
+        say(`${b.id}\t${b.operation}\t${b.target}\t${b.entries.length} files\t${b.createdAt}`);
+      }
+      return;
+    }
+    case 'restore': {
+      const dry = argv.includes('--dry-run');
+      const id = argv.slice(1).find((a) => !a.startsWith('--'));
+      const result = restoreBackup({ id, dryRun: dry });
+      say(`${dry ? 'Would restore' : 'Restored'} ${result.snapshot.id}`);
+      for (const p of result.changed) say(`  ${p}`);
+      return;
+    }
+    case 'upgrade': {
+      const dry = argv.includes('--dry-run');
+      const global = argv.includes('--global');
+      const result = runUpgrade({ targets, dryRun: dry, global });
+      if (result.ran) say('Upgraded global @ericrisco/rsc. Restart your shell if needed.');
+      else say(`${dry ? 'Would run' : 'Upgrade guide'}: ${result.plan.installCommand}`);
+      say(`After upgrade: ${result.plan.syncCommand}`);
+      return;
+    }
     case 'registry': {
       const sub = argv[1];
       if (sub === 'refresh') {
@@ -226,7 +265,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | audit | registry refresh | doctor | sync | backups | restore <id|latest> | upgrade | uninstall <id> | purge');
   }
 }
 

package/skills/analyze/SKILL.md

@@ -36,6 +36,10 @@ Do NOT use when (route elsewhere):
 - A test is failing or behavior is wrong → `debug`.
 - You intend to fix what you find right now → that is `implement`/`clarify`/`plan`/`tasks` work, not analyze. Analyze only reports.
 
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — it is the adversarial consistency gate across constitution ↔ spec ↔ plan ↔ tasks. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Read the accompaniment dial first
 
 Before reporting, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment level (the harness dial, L0..L3). It shapes how the report reads — not what gets checked. The six analyses always run in full; verbosity flexes:

package/skills/clarify/SKILL.md

@@ -88,6 +88,10 @@ How you ask determines whether you get a usable answer.
 - **One batch, ranked, then stop.** Don't drip questions one at a time over many turns unless the dial is L3. Don't dump thirty at once. Ask the few that matter, together.
 - **Quote the spec.** Anchor each question to the exact line or section it came from, so the user sees *why* it's open.
 
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default model tier is **`balanced`** — it ranks and asks the few high-leverage questions, not architecture. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## The accompaniment dial
 
 Read the level from `02-DOCS/wiki/harness/user-profile.md` and adapt **how many questions and how you frame them** — clarify is question-heavy, so the dial matters here more than almost anywhere:

package/skills/constitution/SKILL.md

@@ -15,6 +15,10 @@ A constitution is small, durable, and enforceable. It is **not** a wiki of every
 
 This skill produces `02-DOCS/wiki/sdd/constitution.md` and one Knowledge-map row in the root `CLAUDE.md`. It reconciles with — never duplicates — the stack conventions the harness keeps under `02-DOCS/wiki/stack/*`.
 
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — it sets the project's non-negotiables, the highest-leverage decisions in the repo. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Honor the accompaniment dial first
 
 Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` and match its `technical_level` and `accompaniment_level`. The constitution interview adapts:

package/skills/debug/SKILL.md

@@ -46,6 +46,10 @@ Do NOT use when:
 - The "bug" is actually an unclear requirement or contradictory spec — that's `clarify`/`analyze`,
   not a code defect.
 
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — root-cause diagnosis is deep reasoning. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Read the room first (accompaniment dial)
 
 Before diagnosing, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment

package/skills/implement/SKILL.md

@@ -158,6 +158,10 @@ test output. You merge the branches, then run the *combined* test suite before t
 green-in-isolation is not green-together. Hand the orchestration to `parallel`; keep the TDD
 discipline inside each branch.
 
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default model tier is **`balanced`** — it is the bulk of TDD execution: cost-sensitive, with quality balanced handles well. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model (this is where routing pays off most — fan-out runs on `balanced` while a hard sub-problem can be escalated to `heavy`). Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## The accompaniment dial — how loud at each checkpoint
 
 Read the level from `02-DOCS/wiki/harness/user-profile.md` and match it. Same work, different volume.

package/skills/parallel/SKILL.md

@@ -65,6 +65,7 @@ SUBAGENT BRIEF (one per unit)
 - Compact rules — 4-5 actionable rules digested from those skills for THIS unit
 - Skill fallback — what to do if a referenced skill is unavailable
 - Interface    — any contract it must conform to, FROZEN before dispatch (see the rule below)
+- Model tier   — the tier this unit runs on, by the KIND of work it does (only when routing is enabled — see below)
 - Report-back  — what to return: the diff, the test output, decisions worth logging, skill_resolution
 ```
 
@@ -72,6 +73,8 @@ SUBAGENT BRIEF (one per unit)
 
 Each subagent still owns its own discipline inside its scope — TDD via `implement`, the stack skill's test mechanics, decision logging. This skill does not relax any of that; it just runs several of them at once.
 
+**Per-unit model tier (when routing is enabled).** `parallel` has *no fixed tier* — this is the most concrete place per-phase model routing pays off. When `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`, give each unit the tier of the *kind of work it does*, not one tier for the whole fan-out: an implement-type unit → `balanced`, a scan/research/boilerplate unit → `light`, a unit doing genuine design or root-cause reasoning → `heavy`. Resolve the tier to a concrete model via `models.tiers` and **dispatch that subagent on that model** (e.g. Claude Code's `model` field on the Task/subagent) — real routing, independent of the session model. If routing is off or no profile exists, dispatch on the session model and say nothing. Full protocol: `../sdd/references/model-routing.md`.
+
 ### Skill resolution feedback
 
 Every subagent result must report:
@@ -137,6 +140,7 @@ Be honest about this — most task lists are *mostly* serial with a few disjoint
 | "The brief says 'see the other agent's output' — close enough." | That's a dependency, not independence. Serialize, or freeze the output first. |
 | "Combined suite is red, probably the slower unit — I'll tweak it." | Don't guess at the seam. Reproduce and isolate with debug. |
 | "I just want an isolated branch, so I'll use parallel." | That's isolation, not concurrency. Use worktrees. |
+| "Routing's on, so I'll run the whole fan-out on one tier." | `parallel` has no fixed tier — give each unit the tier of its own work (scan→light, build→balanced, design→heavy). |
 
 ## Red flags — stop and re-plan the partition
 
@@ -172,6 +176,7 @@ End with:
   "artifact": "02-DOCS/wiki/sdd/progress/<slug>.md",
   "next_recommended": "implement",
   "risk": "low|medium|high",
+  "model": { "per_unit": [{ "unit": "users-repo", "tier": "balanced", "resolved": "model-id" }], "routing": "on|off" },
   "skill_resolution": {
     "used": ["parallel"],
     "missing": [],

package/skills/plan/SKILL.md

@@ -150,6 +150,10 @@ mitigation or the spike that would retire it. Separately, log any decision still
 the riskiest plan. Significant design decisions taken during planning also get appended to
 `02-DOCS/wiki/sdd/decisions.md` (the SDD decisions log), so later phases can trace the *why*.
 
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — architecture, interfaces, data flow and risks are the heaviest cognitive load in the chain. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Adapting to the dial
 
 Read `02-DOCS/wiki/harness/user-profile.md` and match the artifact and your narration to it:

package/skills/review/SKILL.md

@@ -184,6 +184,10 @@ When you've processed the review, summarize for the reviewer (and the decisions
 
 ---
 
+## Model tier — `heavy` (opt-in routing)
+
+This phase's default model tier is **`heavy`** — adversarial diff reading is where the strongest model pays off most. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Accompaniment dial (L0..L3)
 
 Read the level from `02-DOCS/wiki/harness/user-profile.md`. **It changes the narration, never the rigor** — every level runs the same passes and the same evidence bar.

package/skills/sdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdd
-description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'de la idea a producción'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill."
+description: "Use when you want a disciplined, spec-driven path from a feature idea to shipped, verified software — the rsc-sdd dispatcher / front door. It states the SDD method, reads the accompaniment dial from 02-DOCS, and routes to the right phase skill: constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement -> verify -> review -> ship, with debug / worktrees / parallel callable on demand. Use it to START a feature, when unsure which SDD phase you are in, or to govern the whole flow. Triggers: 'spec-driven development', 'sdd', 'build this feature properly', 'start a new feature', 'I have an idea, take it to production', 'which phase am I in', 'run the sdd flow', 'desarrollo dirigido por especificación', 'monta esta feature bien', 'de la idea a producción', 'per-phase model routing', 'use a cheaper model for implementation', 'qué modelo por fase'. NOT itself a single phase (it dispatches), NOT the workspace harness (harness), NOT a stack build skill."
 tags: [sdd, spec, workflow, plan]
 recommends: [sdd-init, constitution, specify]
 profiles: [core, full]
@@ -46,23 +46,27 @@ constitution ─(once per project)─┐
                                           debug · worktrees · parallel
 ```
 
-| Phase | Owns | Writes | Sibling skill |
-| --- | --- | --- | --- |
-| **sdd-init** | Technical runtime calibration: stack, tests, commands, registry, budgets | `02-DOCS/wiki/sdd/config.yaml`, `.rsc/skill-registry.*` | `../sdd-init/SKILL.md` |
-| **proposal** | Optional pre-execution briefing for ambiguous/architectural/risky work | `02-DOCS/wiki/sdd/proposals/<slug>.md` | handled by `../specify/SKILL.md` when needed |
-| **constitution** | Project non-negotiables: stack canon, quality bars, conventions | `02-DOCS/wiki/sdd/constitution.md` | `../constitution/SKILL.md` |
-| **specify** | Turn a fuzzy intent into a spec — what & why, no how | `02-DOCS/wiki/sdd/specs/<slug>.md` | `../specify/SKILL.md` |
-| **clarify** | Surface ambiguities / edge cases, ask, bake answers back in | updates the spec | `../clarify/SKILL.md` |
-| **plan** | Technical plan: architecture, interfaces, data flow, tests, risks | `02-DOCS/wiki/sdd/plans/<slug>.md` | `../plan/SKILL.md` |
-| **tasks** | Break the plan into ordered, independently-verifiable tasks | task list in the plan artifact | `../tasks/SKILL.md` |
-| **analyze** | Consistency gate: constitution ↔ spec ↔ plan ↔ tasks (report only) | a gap report | `../analyze/SKILL.md` |
-| **implement** | Execute tasks with checkpoints; TDD discipline embedded | logs to `02-DOCS/wiki/sdd/decisions.md` | `../implement/SKILL.md` |
-| **verify** | Post-build gate: run the stack's checks + done-checks + acceptance | evidence | `../verify/SKILL.md` |
-| **review** | Adversarial code review — give and receive with rigor | review notes | `../review/SKILL.md` |
-| **ship** | Close the branch: PR / merge / cleanup. **Git authorship = Eric** | the merge/PR and archive bundle | `../ship/SKILL.md` |
-| **debug** | Root-cause diagnosis: reproduce → isolate → fix → verify | a diagnosis | `../debug/SKILL.md` |
-| **worktrees** | Isolate feature work in a branch/worktree before executing a plan | an isolated workspace | `../worktrees/SKILL.md` |
-| **parallel** | Fan out independent tasks across subagents, gather results | merged results | `../parallel/SKILL.md` |
+| Phase | Owns | Writes | Tier | Sibling skill |
+| --- | --- | --- | --- | --- |
+| **sdd-init** | Technical runtime calibration: stack, tests, commands, registry, budgets | `02-DOCS/wiki/sdd/config.yaml`, `.rsc/skill-registry.*` | light | `../sdd-init/SKILL.md` |
+| **proposal** | Optional pre-execution briefing for ambiguous/architectural/risky work | `02-DOCS/wiki/sdd/proposals/<slug>.md` | — | handled by `../specify/SKILL.md` when needed |
+| **constitution** | Project non-negotiables: stack canon, quality bars, conventions | `02-DOCS/wiki/sdd/constitution.md` | heavy | `../constitution/SKILL.md` |
+| **specify** | Turn a fuzzy intent into a spec — what & why, no how | `02-DOCS/wiki/sdd/specs/<slug>.md` | balanced | `../specify/SKILL.md` |
+| **clarify** | Surface ambiguities / edge cases, ask, bake answers back in | updates the spec | balanced | `../clarify/SKILL.md` |
+| **plan** | Technical plan: architecture, interfaces, data flow, tests, risks | `02-DOCS/wiki/sdd/plans/<slug>.md` | heavy | `../plan/SKILL.md` |
+| **tasks** | Break the plan into ordered, independently-verifiable tasks | task list in the plan artifact | balanced | `../tasks/SKILL.md` |
+| **analyze** | Consistency gate: constitution ↔ spec ↔ plan ↔ tasks (report only) | a gap report | heavy | `../analyze/SKILL.md` |
+| **implement** | Execute tasks with checkpoints; TDD discipline embedded | logs to `02-DOCS/wiki/sdd/decisions.md` | balanced | `../implement/SKILL.md` |
+| **verify** | Post-build gate: run the stack's checks + done-checks + acceptance | evidence | balanced | `../verify/SKILL.md` |
+| **review** | Adversarial code review — give and receive with rigor | review notes | heavy | `../review/SKILL.md` |
+| **ship** | Close the branch: PR / merge / cleanup. **Git authorship = Eric** | the merge/PR and archive bundle | light | `../ship/SKILL.md` |
+| **debug** | Root-cause diagnosis: reproduce → isolate → fix → verify | a diagnosis | heavy | `../debug/SKILL.md` |
+| **worktrees** | Isolate feature work in a branch/worktree before executing a plan | an isolated workspace | light | `../worktrees/SKILL.md` |
+| **parallel** | Fan out independent tasks across subagents, gather results | merged results | per-unit | `../parallel/SKILL.md` |
+
+> The **Tier** column is the *default* model tier each phase routes to when **per-phase model
+> routing** is enabled — see "Per-phase model routing" below. It is off by default and changes
+> nothing about the chain or the gates; it only decides which model does the work.
 
 > If a phase skill above does not yet exist in this repo, the chain still holds — do that phase's work inline following the method here, and skip the broken handoff. Never invent a sibling that is not installed.
 
@@ -105,6 +109,24 @@ Before dispatching, read `02-DOCS/wiki/harness/user-profile.md` and adapt — ex
 
 If there is no profile yet, default to **non-technical + ask the two harness gauging questions** (technical level, accompaniment level) before dispatching, and persist them — that is the harness's job and `sdd` honors it.
 
+## Per-phase model routing (opt-in)
+
+Different phases reward different models: architecture and adversarial review want the strongest
+one; scaffolding and git plumbing don't. SDD can route each phase to a **tier** — `heavy`
+(deep reasoning), `balanced` (execution), `light` (mechanical) — that resolves to a concrete
+model in `02-DOCS/wiki/sdd/config.yaml` under `models`. The default mapping is the **Tier**
+column above (quality-biased: heavy on constitution/plan/analyze/review/debug, balanced on
+execution, light on ship/worktrees/sdd-init).
+
+It is **off by default** (`models.enabled: false`). When the user opts in, each phase applies it
+two ways: **programmatically** — dispatching `Task`/`parallel` subagents on the tier's model
+(real routing, e.g. Claude Code) — and **advisorily** — announcing the recommended switch at the
+phase boundary, gated by the accompaniment dial, for inline work and assistants that can't switch
+programmatically. Never switch unasked, never claim a switch a tool can't make, and skip routing
+on trivial one-line changes. The `sdd` dispatcher itself never routes (staying on the session
+model); `parallel` has no fixed tier (each unit inherits the tier of its work). Full protocol,
+per-assistant mechanism, and the provider→model table: `references/model-routing.md`.
+
 ## Where the artifacts live (and why it matters)
 
 Every phase writes under `02-DOCS/wiki/sdd/` so the feature's reasoning outlives the chat:
@@ -158,6 +180,7 @@ Every SDD phase ends with the same parseable block so the dispatcher can chain p
   "artifact": "path/to/artifact-or-none",
   "next_recommended": "sdd-init|specify|clarify|plan|tasks|analyze|implement|verify|review|ship",
   "risk": "low|medium|high",
+  "model": { "tier": "heavy|balanced|light", "resolved": "model-id", "routing": "on|off" },
   "skill_resolution": {
     "used": [],
     "missing": [],
@@ -195,6 +218,8 @@ Include current phase, active artifacts, last verdict, completed tasks, next ste
 | "Run constitution again for this feature." | Constitution is once per project. If it exists, read it as guardrails and move on. |
 | "Ship now, I'll add Co-Authored-By: Claude." | `ship` enforces Eric-only authorship. No Claude co-author, no generated-with footer. |
 | "Invoke the `release` phase." | There is no such phase. Never invent a sibling — the chain is the chain. |
+| "Routing sounds useful, I'll switch to the heavy model on my own." | Routing is opt-in (`models.enabled:false`). Don't switch models unless the user turned it on. |
+| "I'll tell them I switched to Opus." (on an assistant with no per-subagent model) | Announce the recommended tier; never claim a switch the tool can't make. Honesty over magic. |
 
 ## Start here
 

package/skills/sdd/evals/cases.yaml

@@ -32,6 +32,9 @@ should_trigger:
   - prompt: "We have an existing repo and no SDD config yet. Start the SDD flow properly before we write a spec."
     why: "The dispatcher should notice the missing runtime calibration and route to sdd-init before specify on non-trivial work."
 
+  - prompt: "I want planning and review to run on the strongest model but implementation on a cheaper one. Set that up for our SDD flow."
+    why: "Per-phase model routing is an SDD concern the dispatcher owns: it should name the tier system (heavy/balanced/light), point at the models block in 02-DOCS/wiki/sdd/config.yaml written by sdd-init, and note it is opt-in — not start coding."
+
 should_not_trigger:
   - prompt: "Write the spec for the new export-to-CSV feature."
     route_to: "specify"
@@ -76,3 +79,12 @@ capability:
       - "Still requires a verification step after the change (the method serves shipping, not ceremony, but evidence before claiming done remains)"
       - "Does not abandon the method for genuinely risky work — distinguishes trivial from non-trivial and is honest about which this is"
       - "If git authorship comes up, notes ship enforces Eric-only authorship (no Co-Authored-By Claude, no generated-with footer)"
+
+  - scenario: "A user asks: 'Can SDD use a cheaper model for the boring phases and the strong one for the hard ones? How do I turn that on?' Show how the dispatcher explains per-phase model routing."
+    must_include:
+      - "Names the three tiers — heavy (deep reasoning), balanced (execution), light (mechanical) — and that each phase has a default tier"
+      - "States the default quality-biased mapping: heavy on constitution/plan/analyze/review/debug, balanced on specify/clarify/tasks/implement/verify, light on ship/worktrees/sdd-init"
+      - "Says routing is OFF by default (models.enabled:false) and lives in the models block of 02-DOCS/wiki/sdd/config.yaml, written by sdd-init; turning it on is the user's choice"
+      - "Explains the two application layers: programmatic (dispatching Task/parallel subagents on the tier's model, e.g. Claude Code) and advisory (announcing the recommended switch at the phase boundary, gated by the accompaniment dial)"
+      - "Is honest about limits: never switches unasked, never claims a model switch an assistant cannot make, and skips routing on trivial one-line changes"
+      - "Points to references/model-routing.md for the full protocol, per-assistant mechanism, and provider→model table rather than inventing model names inline"

package/skills/sdd/references/model-routing.md

@@ -0,0 +1,183 @@
+# Per-phase model routing — the protocol
+
+*Different SDD phases ask for different kinds of thinking. Architecture and adversarial
+review reward the strongest model; scaffolding and git plumbing don't. This is the protocol
+that lets each phase run on the model its work deserves — cheaper where it's safe, strong
+where it matters — without surprising anyone and without faking a switch a tool can't make.*
+
+This file is the **single source of truth** for the behavior. `sdd-init` writes the profile,
+`sdd` summarizes it, and every phase skill points here for the procedure. If the three ever
+disagree, this file wins.
+
+## Why this exists
+
+By default every SDD phase runs on whatever model the session happens to be on. That's either
+wasteful (running `ship`'s `git push` on the most expensive model) or risky (running an
+architecture `plan` on the cheapest one). Routing assigns each phase a **tier** and lets the
+phase put its work on the right model. It is **opt-in**: until the user turns it on, nothing
+changes and nothing is announced.
+
+## The three tiers (provider-neutral)
+
+Tiers are abstract so the profile survives a provider switch. A phase only ever names a tier;
+the concrete model is resolved from config.
+
+| Tier | For | Typical work |
+| --- | --- | --- |
+| **heavy** | deep reasoning | architecture, consistency gates, adversarial review, root-cause diagnosis |
+| **balanced** | execution | writing specs, code, tests, breaking work into tasks, interpreting check output |
+| **light** | mechanical / high-volume / exploration | scaffolding, file sweeps, scans, git plumbing, repo detection |
+
+## The profile (lives in `02-DOCS/wiki/sdd/config.yaml`)
+
+`sdd-init` writes this block. It is the canonical shape — keep it byte-for-byte in sync with
+the Config Shape in `../../sdd-init/SKILL.md` and the table in `../SKILL.md`.
+
+```yaml
+models:
+  enabled: false              # opt-in master switch; false = honor the session model, announce nothing
+  provider: anthropic         # which provider the tiers below resolve to
+  tiers:
+    heavy: claude-opus-4-8
+    balanced: claude-sonnet-4-6
+    light: claude-haiku-4-5-20251001
+  phases:
+    constitution: heavy
+    specify: balanced
+    clarify: balanced
+    plan: heavy
+    tasks: balanced
+    analyze: heavy
+    implement: balanced
+    verify: balanced
+    review: heavy
+    ship: light
+    debug: heavy
+    worktrees: light
+    sdd-init: light
+  overrides: {}               # per-phase tier overrides set by the user; preserved across re-calibration
+```
+
+**Master switch.** `enabled: false` (the default) means routing does nothing: honor the
+session model, never announce a switch, never nag. Everything below applies only when
+`enabled: true`.
+
+**Two phases are deliberately absent from `phases`:**
+
+- `sdd` (the dispatcher) — routing decisions are cheap; it stays on the session model.
+- `parallel` — it has no fixed tier. Each fanned-out subagent inherits the tier of the *kind
+  of work* its unit does (an implement-type unit → `balanced`; a scan/research unit → `light`;
+  a deep-reasoning unit → `heavy`).
+
+## Default phase → tier mapping (quality-biased) and why
+
+| Phase | Tier | Why |
+| --- | --- | --- |
+| constitution | heavy | Sets the project's non-negotiables — highest leverage, worth the best reasoning. |
+| specify | balanced | Drafts the what/why spec through dialogue; not architecture. |
+| clarify | balanced | Ranks and asks the few high-leverage questions; not architecture. |
+| plan | heavy | Architecture, interfaces, data flow, risks — the heaviest cognitive load. |
+| tasks | balanced | Decomposes the plan into verifiable tasks; structured but mechanical. |
+| analyze | heavy | Adversarial consistency gate across constitution ↔ spec ↔ plan ↔ tasks. |
+| implement | balanced | The bulk of TDD execution — cost-sensitive, quality sufficient. |
+| verify | balanced | Runs the checks and interprets failures with judgment. |
+| review | heavy | Adversarial diff reading — where the strongest model pays off most. |
+| ship | light | Close the branch: PR / merge / cleanup — mechanical. |
+| debug | heavy | Root-cause diagnosis — deep reasoning. |
+| worktrees | light | Isolate the workspace (git) — mechanical. |
+| sdd-init | light | Repo detection and calibration — mechanical. |
+
+The user owns this. They change a phase by adding it to `models.overrides` (e.g.
+`overrides: { implement: heavy }`), which wins over `phases`.
+
+## How a phase applies the profile (the procedure)
+
+Run this at the start of any SDD phase, after reading the accompaniment dial:
+
+1. **Read** `models` from `02-DOCS/wiki/sdd/config.yaml`. If the block is absent or
+   `enabled: false` → **do nothing**: honor the session model, say nothing about models.
+2. **Resolve the tier** for this phase: `models.overrides[phase]` if present, else
+   `models.phases[phase]`. (`parallel` resolves a tier per unit instead — see below.)
+3. **Resolve the model**: `models.tiers[tier]` for the active `models.provider`.
+4. **Apply, in two layers:**
+   - **Programmatic (real routing, where the assistant supports delegation).** When the phase
+     delegates work to a subagent (the `Task`/Agent tool) or fans out via `parallel`, set that
+     subagent's `model` to the resolved model. This is real routing regardless of the session
+     model and is the most reliable application — prefer it.
+   - **Advisory (all assistants, inline work).** If the resolved model differs from the current
+     session model and the work isn't being delegated, **announce** it at the phase boundary,
+     gated by the accompaniment dial (below), and give the switch command for the active
+     assistant (mechanism table below). Never block — the human may decline and continue.
+5. **Skip routing entirely** for a one-line / trivial change, exactly as the SDD skip rule says
+   for the rest of the chain. Ceremony serves shipping, not the other way around.
+6. **Record** the model actually used in the phase's result envelope (`model` field, below).
+   Log it to `02-DOCS/wiki/sdd/decisions.md` only when the choice actually mattered (e.g. you
+   overrode a tier for a hard plan) — not on every phase.
+
+### Announcement volume by accompaniment dial
+
+The dial controls how loudly you announce a switch; it never changes whether routing happens.
+
+| Level | On a model switch you… |
+| --- | --- |
+| **L0** "cavernícola" | Switch/dispatch silently. One short line only if the user must act (e.g. "para esta fase conviene opus: `/model opus`"). |
+| **L1** "breve" | One line: which tier/model and the one-word why. |
+| **L2** "explica decisiones" | Name the tier, the model, and why this phase warrants it; give the switch command. |
+| **L3** "acompañamiento total" | Explain the tier system as it applies here, the cost/quality trade-off, and how to override in config. |
+
+## Per-assistant switch mechanism
+
+We route programmatically only where the assistant exposes a per-subagent model. Everywhere
+else routing is advisory — announce the tier, the user switches in their tool.
+
+| Assistant | Programmatic (delegation) | Advisory (inline) |
+| --- | --- | --- |
+| **Claude Code** | `model` on the `Task`/Agent tool and on `parallel` subagents (`opus`/`sonnet`/`haiku`) | `/model <name>` for the session |
+| **Codex CLI** | — (solo-agent) | model flag / `model` in config |
+| **Cursor** | native subagent model where exposed | model picker in the UI |
+| **Gemini CLI** | — (experimental) | model flag |
+| **Copilot / Windsurf / Cline / others** | — | announce the tier; user switches in the tool's model selector |
+
+When the active assistant has **no** way to switch, still announce the recommended tier so the
+human can decide — but **never claim a switch happened**. Honesty over magic.
+
+## Provider → concrete models (repoint the tiers here)
+
+To target another provider, change `models.provider` and set `models.tiers` to that row.
+
+| provider | heavy | balanced | light |
+| --- | --- | --- | --- |
+| `anthropic` | `claude-opus-4-8` | `claude-sonnet-4-6` | `claude-haiku-4-5-20251001` |
+| `openai` | `gpt-5.1` (or current flagship) | `gpt-5.1-mini` | `gpt-5.1-nano` |
+| `google` | `gemini-2.5-pro` | `gemini-2.5-flash` | `gemini-2.5-flash-lite` |
+| `openrouter` | a strong model slug | a mid model slug | a cheap/free model slug |
+
+These are starting points — set them to whatever your account actually has. The tiers are the
+contract; the concrete names are yours to edit.
+
+## Result-envelope `model` field
+
+Every phase's result envelope carries the model it ran on, so the chain is auditable:
+
+```json
+{
+  "status": "complete",
+  "model": { "tier": "heavy", "resolved": "claude-opus-4-8", "routing": "on|off" },
+  "...": "rest of the standard envelope"
+}
+```
+
+When routing is off, emit `"model": { "routing": "off" }` (no tier/resolved) — don't invent a
+tier you didn't use.
+
+## Honesty rules / anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "Routing sounds good, I'll switch models even though the user never enabled it." | It's opt-in. `enabled: false` (and a missing block) means honor the session model and say nothing. |
+| "I'll tell the user I switched to Opus." (on an assistant with no programmatic switch) | You can't switch there. Announce the tier and the command; never claim a switch you didn't make. |
+| "L0 means terse, so I'll skip routing." | L0 changes words, not behavior. Route the same; just announce silently (or only when the user must act). |
+| "It's a one-line typo fix but the phase is `review`, so → heavy." | Skip routing on trivial changes, like the rest of the chain. Don't spin up the expensive model for a copy tweak. |
+| "I'll log the model on every phase." | Log to `decisions.md` only when the model choice mattered. The envelope `model` field already records the routine case. |
+| "config has no `models` block, I'll assume the defaults are active." | A missing block means routing is **off**. Defaults describe what `sdd-init` *writes*, not an implicit on-state. |
+| "Two parallel units, I'll run both on the phase's tier." | `parallel` has no fixed tier. Give each unit the tier of its own work. |

package/skills/sdd-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdd-init
-description: "Use when calibrating an existing repo before running the rsc SDD flow: detecting stack, package manager, test runners, lint/type/build commands, monorepo signals, artifact store, execution mode, review budget, strict TDD capability, and project skill registry. Triggers: 'calibrate this repo for SDD', 'run sdd init', 'detect my test runner before implementing', 'set up SDD config', 'prepare this repo for spec-driven development'. NOT first-contact user/workspace bootstrap (init), NOT 01-TOOLS/02-DOCS scaffolding (harness), NOT writing a feature spec (specify)."
+description: "Use when calibrating an existing repo before running the rsc SDD flow: detecting stack, package manager, test runners, lint/type/build commands, monorepo signals, artifact store, execution mode, review budget, strict TDD capability, and project skill registry. Triggers: 'calibrate this repo for SDD', 'run sdd init', 'detect my test runner before implementing', 'set up SDD config', 'prepare this repo for spec-driven development', 'configure per-phase model routing', 'assign models per SDD phase', 'set up cheaper model for implementation'. NOT first-contact user/workspace bootstrap (init), NOT 01-TOOLS/02-DOCS scaffolding (harness), NOT writing a feature spec (specify)."
 tags: [sdd, init, config, testing, registry]
 recommends: [sdd, specify, implement, verify]
 profiles: [core, full]
@@ -38,6 +38,8 @@ Ask only when the answer changes behavior. At L0/L1 infer defaults and show them
 | `artifact_store` | `02-DOCS/wiki/sdd` | Keep RSC artifacts in `02-DOCS`; do not create an `openspec/` parallel tree. |
 | `review_budget.line_budget` | `400` | Lower for solo tight review; higher only with explicit approval. |
 | `delivery_strategy.default` | `ask-on-risk` | `ask-on-risk`, `single-pr`, `autochain`, `exception`. |
+| `models.enabled` | `false` | Per-phase model routing is opt-in. Leave off unless the user asks for it; flipping it on is their call. |
+| `models.provider` | `anthropic` | Which provider the tiers resolve to. Set from the detected assistant when obvious, else `anthropic`. See `../sdd/references/model-routing.md` for other providers. |
 
 ## Detection
 
@@ -48,7 +50,8 @@ Use the repo detector exposed by the CLI code (`detectRepoProfile`) or reproduce
 - scripts: `test`, `lint`, `typecheck`, `build`;
 - runners: Vitest, Jest, Playwright, pytest, `go test`, `flutter test`;
 - monorepo signals;
-- recommended apply and verify commands.
+- recommended apply and verify commands;
+- the active assistant/provider when it's obvious from the environment (Claude Code, Codex, Gemini…), to seed `models.provider` — default `anthropic` when unsure. This only sets the *concrete model names*; routing itself stays off until the user opts in.
 
 If any runner is detected, set `testing.strict_tdd: true`. Strict TDD means implement phases must do red -> green -> triangulate edge cases -> refactor, with command evidence. If no runner is detected, set it false and record the gap rather than pretending.
 
@@ -118,9 +121,38 @@ phase_rules:
   implement: requires analyze pass, strict_tdd when testing.strict_tdd is true
   verify: requires spec tasks evidence
   archive: requires verify record and review/ship outcome
+models:
+  enabled: false              # opt-in master switch; false = honor session model, announce nothing
+  provider: anthropic         # which provider the tiers below resolve to
+  tiers:
+    heavy: claude-opus-4-8
+    balanced: claude-sonnet-4-6
+    light: claude-haiku-4-5-20251001
+  phases:
+    constitution: heavy
+    specify: balanced
+    clarify: balanced
+    plan: heavy
+    tasks: balanced
+    analyze: heavy
+    implement: balanced
+    verify: balanced
+    review: heavy
+    ship: light
+    debug: heavy
+    worktrees: light
+    sdd-init: light
+  overrides: {}               # per-phase tier overrides set by the user
 ```
 
-Preserve user edits if the file exists: update detected facts and leave comments/custom policy fields intact when possible. If preservation is risky, write a proposed replacement next to it as `config.proposed.yaml` and ask.
+The `models` block is the **per-phase model routing** profile: each phase declares a tier
+(`heavy`/`balanced`/`light`) and the tiers resolve to concrete models for `provider`. It ships
+**off** (`enabled: false`) — write it so the user can opt in, never switch models behind their
+back. The full protocol (how phases apply it, the per-assistant switch mechanism, the
+provider→model table) lives in `../sdd/references/model-routing.md`. Keep this block byte-for-byte
+in sync with that reference.
+
+Preserve user edits if the file exists: update detected facts and leave comments/custom policy fields intact when possible. **Never flip `models.enabled` or drop `models.overrides` on re-calibration** — those are user choices; preserve them verbatim and only refresh `tiers`/`provider` if the user asks. If preservation is risky, write a proposed replacement next to it as `config.proposed.yaml` and ask.
 
 ## Result Envelope
 
@@ -139,7 +171,8 @@ End with the standard SDD result envelope:
     "fallback": [],
     "compact_rules": [
       "Read config.yaml before choosing commands.",
-      "Use .rsc/skill-registry.json as the cheap skill index."
+      "Use .rsc/skill-registry.json as the cheap skill index.",
+      "Per-phase model routing ships off (models.enabled:false); never switch models unasked."
     ]
   },
   "evidence": ["npx @ericrisco/rsc registry refresh", "detected test commands recorded"]

package/skills/ship/SKILL.md

@@ -186,6 +186,10 @@ The commit is the durable record. Make it describe the change and tie it to the
 - **Body:** *why*, not a restatement of the diff. Reference the spec slug and any decision logged in `decisions.md`.
 - **Footer:** issue/PR refs only. **No `Co-Authored-By` for any AI. No "generated with" line.** This is where the violation usually sneaks in — leave the footer clean.
 
+## Model tier — `light` (opt-in routing)
+
+This phase's default model tier is **`light`** — closing the branch (PR / merge / cleanup) is mechanical. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change. The Eric-only authorship rule is independent of the model and never relaxes.
+
 ## Accompaniment dial (L0..L3)
 
 Read the level from `02-DOCS/wiki/harness/user-profile.md`. It changes the narration, **never** the safety checklist or the authorship rule.

package/skills/specify/SKILL.md

@@ -28,6 +28,10 @@ You are not slowing them down; you make the intent reviewable *before* code exis
 
 If you cannot describe a requirement without naming the technology, you have found a real question — record it as a point to clarify, do not guess the answer.
 
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default model tier is **`balanced`** — it drafts the what/why spec through dialogue, not architecture. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Read the room first (accompaniment dial)
 
 Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical level and accompaniment level, and adapt:

package/skills/tasks/SKILL.md

@@ -25,6 +25,10 @@ further questions.
 This is a process skill. It writes no runtime code. It produces one artifact: an
 ordered, checkable task list appended to the plan it was built from.
 
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default model tier is **`balanced`** — it decomposes an approved plan into verifiable tasks: structured work, not architecture. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Read the harness profile first
 
 Before producing anything, read `02-DOCS/wiki/harness/user-profile.md` for the

package/skills/verify/SKILL.md

@@ -31,6 +31,10 @@ Do NOT use when:
 - You're reading the diff adversarially for design/correctness smells a test can't catch → that's `review`.
 - There is no spec or task list to verify against → you're earlier in the chain; go to `specify`/`plan`/`tasks` first.
 
+## Model tier — `balanced` (opt-in routing)
+
+This phase's default model tier is **`balanced`** — it runs the checks and interprets failures with judgment. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Read the room first (accompaniment dial)
 
 Before running anything, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment level and adapt:

package/skills/worktrees/SKILL.md

@@ -125,6 +125,10 @@ level) before handing to `implement`.
 The native tool is preferred because it owns the session-switch and the exit lifecycle for you. The
 git path is the universal fallback and is exactly what the native tool does under the hood.
 
+## Model tier — `light` (opt-in routing)
+
+This phase's default model tier is **`light`** — isolating the workspace is mechanical git work. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
+
 ## Adapting to the dial
 
 Read `02-DOCS/wiki/harness/user-profile.md` and match your volume — the isolation is identical at