@polymorphism-tech/morph-spec 7.9.3 → 8.0.0

package/src/lib/validators/verify-runner.js

@@ -0,0 +1,322 @@
+/**
+ * Verify Runner — deterministic build+tests+validators cadence.
+ *
+ * v8 adds a DETERMINISTIC verification node that runs BEFORE the LLM judge
+ * in the per-task loop: build + tests + validators (code, free) first; the
+ * LLM judge is only invoked once verify passes. This is a BINARY gate
+ * (pass/fail per node), NOT a second "bar 9" — the bar 9 remains morph-eval's.
+ *
+ * Pure orchestration — reuses (never reimplements):
+ *   - runBuildCheck()  from framework/hooks/shared/build-check.js
+ *   - runTestSuite()   from src/lib/tasks/test-runner.js
+ *   - runValidation()  from ./validation-runner.js
+ *   - loadRubric() + aggregateScores() from ./score-aggregator.js
+ *
+ * @module verify-runner
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+import { runBuildCheck, getBuildCommand } from '../../../framework/hooks/shared/build-check.js';
+import { runTestSuite, resolveTestCommand } from '../tasks/test-runner.js';
+import { runValidation } from './validation-runner.js';
+import { loadRubric, aggregateScores } from './score-aggregator.js';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+/** Default build timeout — dotnet cold build is slow; 30s (the Stop-hook default) is too short. */
+const DEFAULT_BUILD_TIMEOUT = 120_000;
+
+/** Number of trailing output lines kept for feedback/reporting. */
+const OUTPUT_TAIL_LINES = 20;
+
+/**
+ * Run the deterministic verify cadence for a feature (or a single task within it).
+ *
+ * @param {string} projectPath - Project root directory
+ * @param {string} featureName - Feature name
+ * @param {string|null} [taskId] - Task ID for task-scoped verify, or null/undefined for feature scope
+ * @param {Object} [options]
+ * @param {string} [options.rubric] - Force a rubric id (highest precedence)
+ * @param {number} [options.timeout] - Build timeout in ms (default 120000)
+ * @param {boolean} [options.skipTests] - Skip the tests node
+ * @param {boolean} [options.skipBuild] - Skip the build node
+ * @param {Function} [options._runBuildCheck] - Injectable override for runBuildCheck (testing)
+ * @param {Function} [options._runTestSuite] - Injectable override for runTestSuite (testing)
+ * @param {Function} [options._runValidation] - Injectable override for runValidation (testing)
+ * @returns {Promise<Object>} Aggregated verify result — see module docs for shape
+ */
+export async function runVerify(projectPath, featureName, taskId, options = {}) {
+  const {
+    rubric: rubricOverride,
+    timeout = DEFAULT_BUILD_TIMEOUT,
+    skipTests = false,
+    skipBuild = false,
+    _runBuildCheck = runBuildCheck,
+    _runTestSuite = runTestSuite,
+    _runValidation = runValidation,
+  } = options;
+
+  const stack = readStack(projectPath);
+
+  const nodes = {};
+  const feedback = [];
+
+  // 1. build
+  nodes.build = await runBuildNode({ projectPath, stack, timeout, skipBuild, _runBuildCheck });
+  appendBuildFeedback(feedback, nodes.build);
+
+  // 2. tests — skipped entirely (no invocation) when build already failed.
+  nodes.tests = await runTestsNode({ projectPath, skipTests, buildNode: nodes.build, _runTestSuite });
+  appendTestsFeedback(feedback, nodes.tests);
+
+  // 3. validators — ALWAYS runs, even on a red build (free static feedback).
+  const rubricId = resolveRubricId({ projectPath, featureName, taskId, rubricOverride });
+  nodes.validators = await runValidatorsNode({ projectPath, featureName, rubricId, _runValidation });
+  appendValidatorsFeedback(feedback, nodes.validators);
+
+  const status = Object.values(nodes).some((n) => n.status === 'fail') ? 'fail' : 'pass';
+
+  return {
+    version: 1,
+    feature: featureName,
+    task: taskId || null,
+    scope: taskId ? 'task' : 'feature',
+    stack,
+    rubric: rubricId,
+    status,
+    nodes,
+    feedback,
+  };
+}
+
+// ============================================================================
+// Build node
+// ============================================================================
+
+async function runBuildNode({ projectPath, stack, timeout, skipBuild, _runBuildCheck }) {
+  if (skipBuild) {
+    return { status: 'skip', command: null, durationMs: 0, reason: 'requested', output: '' };
+  }
+
+  const hasTsConfig = existsSync(join(projectPath, 'tsconfig.json'));
+  const command = getBuildCommand(stack, hasTsConfig);
+  if (!command) {
+    const reason = stack ? `no build command for stack "${stack}"` : 'no stack configured';
+    return { status: 'skip', command: null, durationMs: 0, reason, output: '' };
+  }
+
+  const start = Date.now();
+  const result = await _runBuildCheck(projectPath, stack, timeout);
+  const durationMs = Date.now() - start;
+
+  return {
+    status: result.status,
+    command,
+    durationMs,
+    reason: result.status === 'skip' ? 'no build command for stack' : null,
+    output: result.output || '',
+  };
+}
+
+function appendBuildFeedback(feedback, buildNode) {
+  if (buildNode.status !== 'fail') return;
+  for (const line of linesOf(buildNode.output)) {
+    feedback.push(`[build] ${line}`);
+  }
+}
+
+// ============================================================================
+// Tests node
+// ============================================================================
+
+async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }) {
+  const command = resolveTestCommand(projectPath);
+
+  if (skipTests) {
+    return { status: 'skip', command, durationMs: 0, reason: 'requested', output: '' };
+  }
+
+  if (buildNode.status === 'fail') {
+    return {
+      status: 'skip',
+      command,
+      durationMs: 0,
+      reason: 'build failed — test run would only add noise',
+      output: '',
+    };
+  }
+
+  const start = Date.now();
+  const result = await _runTestSuite(projectPath);
+  const durationMs = Date.now() - start;
+
+  if (result.skipped) {
+    return {
+      status: 'skip',
+      command,
+      durationMs,
+      reason: result.reason || 'no test command detected',
+      output: '',
+    };
+  }
+
+  return {
+    status: result.passed ? 'pass' : 'fail',
+    command,
+    durationMs,
+    reason: null,
+    output: result.passed ? '' : tailLines(result.output, OUTPUT_TAIL_LINES),
+  };
+}
+
+function appendTestsFeedback(feedback, testsNode) {
+  if (testsNode.status !== 'fail') return;
+  for (const line of linesOf(testsNode.output)) {
+    feedback.push(`[tests] ${line}`);
+  }
+}
+
+// ============================================================================
+// Validators node
+// ============================================================================
+
+async function runValidatorsNode({ projectPath, featureName, rubricId, _runValidation }) {
+  const start = Date.now();
+
+  // runValidation() prints chalk-formatted progress to stdout. verify emits
+  // JSON — silence console during the call and ALWAYS restore it, even if
+  // runValidation throws.
+  const originalLog = console.log;
+  const originalWarn = console.warn;
+  let validationResult;
+  try {
+    console.log = () => {};
+    console.warn = () => {};
+    validationResult = await _runValidation(projectPath, featureName, { mode: 'full' });
+  } finally {
+    console.log = originalLog;
+    console.warn = originalWarn;
+  }
+
+  const durationMs = Date.now() - start;
+
+  if (validationResult && validationResult._skipReason) {
+    return {
+      status: 'skip',
+      score: null,
+      action: null,
+      ran: [],
+      reason: validationResult._skipReason,
+      priorityFixes: [],
+      durationMs,
+    };
+  }
+
+  const rubric = loadRubric(projectPath, rubricId);
+  const scoreResult = aggregateScores(validationResult, rubric);
+
+  return {
+    status: validationResult.passed === false ? 'fail' : 'pass',
+    score: scoreResult.score,
+    action: scoreResult.action,
+    ran: Object.keys(validationResult.results || {}),
+    reason: null,
+    priorityFixes: scoreResult.priorityFixes || [],
+    durationMs,
+  };
+}
+
+function appendValidatorsFeedback(feedback, validatorsNode) {
+  for (const fix of validatorsNode.priorityFixes || []) {
+    const topIssue = fix.issues && fix.issues[0];
+    if (!topIssue) continue;
+    const location = topIssue.file
+      ? ` (${topIssue.file}${topIssue.line ? ':' + topIssue.line : ''})`
+      : '';
+    feedback.push(`[validators/${fix.category} ${fix.score}/10] ${topIssue.message}${location}`);
+  }
+}
+
+// ============================================================================
+// Rubric selection — flag > task group > config > default
+// ============================================================================
+
+function resolveRubricId({ projectPath, featureName, taskId, rubricOverride }) {
+  if (rubricOverride) return rubricOverride;
+
+  if (taskId) {
+    const group = readTaskGroup(projectPath, featureName, taskId);
+    const mapped = mapGroupToRubric(group);
+    if (mapped) return mapped;
+  }
+
+  const configRubric = readConfigRubric(projectPath);
+  if (configRubric) return configRubric;
+
+  return 'default';
+}
+
+/**
+ * Map a task's `group` field to a rubric id.
+ * backend|infra → 'backend', frontend → 'frontend', tests|docs|absent → null
+ * (falls through to config/default).
+ */
+function mapGroupToRubric(group) {
+  if (!group) return null;
+  const g = String(group).toLowerCase();
+  if (g === 'backend' || g === 'infra') return 'backend';
+  if (g === 'frontend') return 'frontend';
+  return null;
+}
+
+function readTaskGroup(projectPath, featureName, taskId) {
+  try {
+    const tasksPath = getAbsoluteOutputPath(projectPath, featureName, 'tasks');
+    if (!existsSync(tasksPath)) return null;
+    const tasksJson = JSON.parse(readFileSync(tasksPath, 'utf8'));
+    const task = (tasksJson.tasks || []).find((t) => t.id === taskId);
+    return task?.group ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function readConfigRubric(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return null;
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    return config?.validation?.rubric ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Shared helpers
+// ============================================================================
+
+/** Read the project stack directly from config.json — never the stack-profile
+ *  default (which falls back to 'unknown'→dotnet and would wrongly fire
+ *  `dotnet build` on a greenfield JS project). */
+function readStack(projectPath) {
+  try {
+    const configPath = join(projectPath, '.morph', 'config', 'config.json');
+    if (!existsSync(configPath)) return null;
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    return config?.project?.stack ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function linesOf(text) {
+  const trimmed = (text || '').trim();
+  return trimmed ? trimmed.split('\n') : [];
+}
+
+function tailLines(text, n) {
+  const lines = linesOf(text);
+  return lines.slice(-n).join('\n');
+}

package/src/lib/work-type-detector.js

@@ -0,0 +1,143 @@
+/**
+ * Work Type Detector — deterministic keyword classifier for `text`/`declaredScope`.
+ *
+ * Mirrors risk-detector.js's style: pure, deterministic, no I/O. This module
+ * is the TESTABLE MIRROR of the natural-language classification rules that
+ * live in MORPH.md — behavior described here must stay in sync with those
+ * rules, but this file is what `create`/`retype` call at runtime.
+ *
+ * Precedence: hotfix keywords win outright (a production incident never
+ * ties down against a bug or chore signal). Otherwise bug vs. chore is
+ * decided by keyword-match count, nudged by two weak signals:
+ *   - estimatedFiles <= 2   -> +1 toward bug   (small, surgical diffs)
+ *   - declaredScope <= 6 words -> +1 toward chore (a narrowly-scoped ask)
+ * A genuine tie between bug and chore is surfaced to the caller (LLM/HCOP
+ * router) rather than guessed at. Zero keyword matches -> no opinion; the
+ * caller defaults to `feature`.
+ */
+
+// Plural/inflected forms are listed EXPLICITLY: matching is whole-word, so
+// "incidentes" is not "incidente". Recall lives here, in a list that is visible
+// and tested, rather than in a matcher that would fire on fragments.
+const HOTFIX_KEYWORDS = [
+  'hotfix', 'produção quebrada', 'prod down', 'produção caiu', 'incident',
+  'incidents', 'incidente', 'incidentes', 'urgente', 'urgência', 'p0', 'outage',
+  'caiu em produção',
+];
+
+const BUG_KEYWORDS = [
+  'bug', 'bugs', 'fix', 'corrigir', 'corrige', 'broken', 'quebrado', 'quebrada',
+  'regressão', 'regressao', 'exception', 'exceptions', 'stack trace',
+  'não funciona', 'nao funciona', 'erro', 'erros',
+];
+
+const CHORE_KEYWORDS = [
+  'chore', 'typo', 'typos', 'rename', 'renomear', 'bump', 'dependência',
+  'dependencia', 'dependências', 'dependencias', 'config', 'configs', 'cleanup',
+  'limpeza', 'docs', 'documentação', 'lint', 'formatação',
+];
+
+/**
+ * @returns {string[]} the subset of `keywords` present in `haystack` as WHOLE
+ * words (or whole phrases), never as a fragment of a larger word.
+ *
+ * Substring matching routed real requests to the wrong pipeline: `p0` is two
+ * characters with outright hotfix precedence, so "endpoint group0" matched it
+ * and skipped Gates 1 and 2 by policy — no human, and not even the LLM router,
+ * since a substring hit reports `confidence: 'high'`. Same shape for `fix`
+ * inside "prefix"/"fixtures" and `bug` inside "debug".
+ *
+ * The failure directions are asymmetric, which is what settles the trade-off: a
+ * false POSITIVE silently skips approval gates, while a false negative usually
+ * only lowers confidence — and low confidence defers to the LLM router (exit 2).
+ * Matching strictly is therefore the safe error, and provably so for the vector
+ * that motivated it: whole-word matches are a strict SUBSET of substring matches
+ * per keyword, so narrowing can never invent a hotfix hit that substring didn't
+ * already have. No misroute INTO the only gate-skipping pipeline can be created
+ * here, only removed.
+ *
+ * Being precise about the limit of that argument, since overclaiming in a
+ * comment is what this file is fixing: the asymmetry holds per KEYWORD, not per
+ * CLASSIFICATION. Dropping a match can still shift the bug-vs-chore balance —
+ * losing a bug hit may promote a chore from `tie` to `high`, and chore also
+ * skips Gates 1 and 2. Whole-word matching DID cost recall that substring had:
+ * "bugs" contains "bug" but is not the word "bug". The answer is to list the
+ * forms (below), not to match loosely — recall belongs in the vocabulary, where
+ * it is explicit and testable, not in a matcher that fires on fragments.
+ *
+ * `\b` is not usable here: JS word boundaries are ASCII-only, so `\bnão\b`
+ * would find a boundary between `n` and `ã` and misbehave on half of these
+ * pt-BR keywords. Unicode letter/number lookarounds are the portable form.
+ */
+function matchKeywords(haystack, keywords) {
+  return keywords.filter((kw) => {
+    const escaped = kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(?<![\\p{L}\\p{N}])${escaped}(?![\\p{L}\\p{N}])`, 'u').test(haystack);
+  });
+}
+
+function wordCount(str) {
+  const trimmed = str.trim();
+  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+
+/**
+ * @param {object} input
+ * @param {string} [input.text]
+ * @param {string} [input.declaredScope]
+ * @param {number} [input.estimatedFiles]
+ * @returns {{
+ *   workType: string|null,
+ *   confidence: 'high'|'tie'|'none',
+ *   matched: { hotfix: string[], bug: string[], chore: string[], feature: string[] },
+ *   candidates: string[],
+ * }}
+ */
+export function detectWorkType({ text = '', declaredScope = '', estimatedFiles } = {}) {
+  const haystack = `${text} ${declaredScope}`.toLowerCase();
+
+  const hotfixMatched = matchKeywords(haystack, HOTFIX_KEYWORDS);
+  const bugMatched = matchKeywords(haystack, BUG_KEYWORDS);
+  const choreMatched = matchKeywords(haystack, CHORE_KEYWORDS);
+
+  const matched = {
+    hotfix: hotfixMatched,
+    bug: bugMatched,
+    chore: choreMatched,
+    feature: [], // no keywords of its own — the catch-all default
+  };
+
+  // Hard precedence: any hotfix signal wins outright, never ties down.
+  if (hotfixMatched.length > 0) {
+    return { workType: 'hotfix', confidence: 'high', matched, candidates: ['hotfix'] };
+  }
+
+  if (bugMatched.length === 0 && choreMatched.length === 0) {
+    return { workType: null, confidence: 'none', matched, candidates: [] };
+  }
+
+  let bugScore = bugMatched.length;
+  let choreScore = choreMatched.length;
+
+  // The weak nudges act ONLY as tie-breakers — apply them only when the raw
+  // keyword counts are already equal. Otherwise a clean single-keyword match
+  // on one type would be dragged into a tie by the other type's weak signal
+  // (e.g. a lone "bug" keyword + a short declaredScope), routing an
+  // unambiguous request to the LLM and risking a gate-skipping misroute.
+  if (bugMatched.length === choreMatched.length) {
+    if (typeof estimatedFiles === 'number' && estimatedFiles <= 2) {
+      bugScore += 1;
+    }
+
+    if (wordCount(declaredScope) > 0 && wordCount(declaredScope) <= 6) {
+      choreScore += 1;
+    }
+  }
+
+  if (bugScore === choreScore) {
+    return { workType: null, confidence: 'tie', matched, candidates: ['bug', 'chore'] };
+  }
+
+  const workType = bugScore > choreScore ? 'bug' : 'chore';
+  return { workType, confidence: 'high', matched, candidates: [workType] };
+}

package/src/scripts/setup-infra.js

@@ -11,7 +11,7 @@
  *   await setupInfra('/path/to/project');
  */
 
-import { join, dirname } from 'path';
+import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
 import { readFileSync, readdirSync, copyFileSync, unlinkSync } from 'fs';
@@ -22,7 +22,8 @@ import {
   writeJson,
   ensureDir,
   writeFile,
-  updateGitignore
+  updateGitignore,
+  ensureGitattributes
 } from '../utils/file-copier.js';
 import { parseStacks, getProjectTags, shouldInstall } from '../lib/stack-filter.js';
 import { injectMorphImport } from '../utils/claude-md-injector.js';
@@ -30,6 +31,7 @@ import { saveProjectMorphVersion, getInstalledCLIVersion } from '../utils/versio
 import { installClaudeHooks, installGlobalStatusline } from '../utils/claude-settings-manager.js';
 import { installSkills } from '../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../utils/agents-installer.js';
+import { resolvePrimaryRoot } from '../commands/project/worktree.js';
 
 const FRAMEWORK_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'framework');
 
@@ -159,14 +161,38 @@ export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = []) {
  * @param {object} options
  * @param {Function} options._exec - exec function (for testing)
  * @param {boolean} options.reinstall - If true, only re-install stack-aware assets (rules, skills, agents)
+ * @param {boolean} options.force - Bypass the secondary-worktree guard (see below). Callers
+ *   (e.g. `initCommand`) that already performed their own equivalent check pass this so the
+ *   check isn't redundantly re-applied here.
  */
-export async function setupInfra(targetPath, { _exec = execSync, reinstall = false } = {}) {
+export async function setupInfra(targetPath, { _exec = execSync, reinstall = false, force = false } = {}) {
   const quiet = process.env.MORPH_QUIET === '1';
 
   function log(msg) {
     if (!quiet) process.stdout.write(msg + '\n');
   }
 
+  // Guard: refuse a FULL install from inside a secondary (linked) worktree.
+  // `.claude/` and `.morph/framework/` are junctions back to the primary root
+  // there, but `.morph/config/`, `.morph/context/`, `.morph/checkpoints/`,
+  // `.morph/memory/`, `.morph/archive/` and `.morph/state.json` are NOT — a
+  // full install would scaffold a second, disconnected config/state tree
+  // inside the worktree. `reinstall` mode is exempt: it only touches
+  // .claude/* stack-aware assets, which are the junctioned (safe) subset.
+  // `resolvePrimaryRoot` fails open to `targetPath` itself outside a git repo
+  // (or on any git error), so non-git projects and the primary root are
+  // never blocked.
+  if (!reinstall && !force) {
+    const target = resolve(targetPath).replace(/\\/g, '/');
+    const root = resolvePrimaryRoot(targetPath);
+    if (root !== target) {
+      log(`Você está num worktree secundário (${target}).`);
+      log(`O morph-spec já está instalado na raiz primária (${root}).`);
+      log('Para reparar infra do worktree use `morph-spec worktree link --all`, não `init`/`setup-infra`.');
+      return { blocked: true, root, target };
+    }
+  }
+
   // --- Reinstall mode: only re-install stack-aware assets ---
   if (reinstall) {
     log('setup-infra (reinstall): re-installing stack-aware assets...');
@@ -354,9 +380,10 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
   const cliVersion = getInstalledCLIVersion();
   await saveProjectMorphVersion(targetPath, cliVersion);
 
-  // --- 18. updateGitignore ---
-  log('Step 18: Updating .gitignore...');
+  // --- 18. updateGitignore + .gitattributes ---
+  log('Step 18: Updating .gitignore + .gitattributes...');
   await updateGitignore(targetPath);
+  await ensureGitattributes(targetPath);
 
   // --- 19. Initialize state.json (only if not exists) ---
   log('Step 19: Initializing state.json...');

package/src/utils/agent-id-mapper.js

@@ -1,11 +1,11 @@
-/**
- * Map an agents.json ID to the Claude Code subagent_type.
- *
- * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
- * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
- * @returns {string} subagent_type matching .claude/agents/ filename stem
- */
-export function agentIdToSubagentType(id, tier) {
-  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
-  return `${prefix}${id}`;
-}
+/**
+ * Map an agents.json ID to the Claude Code subagent_type.
+ *
+ * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
+ * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
+ * @returns {string} subagent_type matching .claude/agents/ filename stem
+ */
+export function agentIdToSubagentType(id, tier) {
+  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
+  return `${prefix}${id}`;
+}

package/src/utils/agents-installer.js

@@ -13,10 +13,12 @@
  * Canonical naming: subagent_type = `morph-{id}` — the frontmatter `name`
  * matches the filename 1:1, and the skills dispatch that exact type.
  *
- * In v5 the harness has 7 domain personas (no tiers) — each persona is a
- * subagent the Specialist (Claude in implementer role) can dispatch when
- * working in that domain. The 3 roles (Orchestrator/Specialist/Evaluator)
- * are assumed by Claude itself per MORPH.md, not as separate agents.
+ * In v5 the harness has 8 personas (no tiers) across two axes — domain
+ * (dotnet-senior, ef-modeler, maf-expert, nextjs-expert, ui-designer,
+ * infra-engineer, evaluator) and stage (scout, read-only diagnosis before
+ * implementation). Each persona is a subagent the Specialist (Claude in
+ * implementer role) can dispatch. The 3 roles (Orchestrator/Specialist/
+ * Evaluator) are assumed by Claude itself per MORPH.md, not as separate agents.
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
@@ -163,8 +165,10 @@ function buildFrontmatter(agent, description, knownMcpIds) {
     // Canonical 1:1 naming: frontmatter name === filename === subagent_type.
     `name: morph-${agent.id}`,
     `description: ${description}`,
-    // Domain implementers inherit the session model by default — a hardcoded
-    // downgrade here would silently lower quality. Override via agents.json.
+    // model is dimensioned per stage/criticality in agents.json (v5.2.0):
+    // evaluator (quality multiplier) → opus, domain implementers → sonnet,
+    // scout (read-only, cheap) → haiku. Falls back to `inherit` only for
+    // personas that omit the field.
     `model: ${agent.model ?? 'inherit'}`,
     `tools: ${buildToolsLine(agent, knownMcpIds)}`,
     `maxTurns: 20`,