@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/utils/agents-installer.js

@@ -1,69 +1,24 @@
-/**
- * Agents Installer (v5)
- *
- * Installs morph-spec domain personas as native Claude Code subagents
- * in .claude/agents/morph-{id}.md.
- *
- * agents.json is the SINGLE SOURCE OF TRUTH (ADR-001, docs/specs/
- * dispatchable-personas/decisions.md). The .md files are DERIVED artifacts:
- * generated with a MANAGED header, regenerated on update/--reinstall, and
- * drift-checked by `morph-spec doctor` (checkAgentsDrift). Never hand-edit
- * them — that is exactly the v4 dual-source drift the v5 migration removed.
- *
- * 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 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, existsSync, readdirSync } from 'node:fs';
 import { join } from 'path';
 import { shouldInstall } from '../lib/stack-filter.js';
 import { realEffects } from '../lib/installers/effects.js';
 
-/** Default tool scope for domain personas (override per agent via agents.json `tools`). */
 export const DEFAULT_AGENT_TOOLS = 'Read, Write, Edit, Bash, Glob, Grep';
 
-/**
- * A persona that can change files: its effective tool scope grants Write or Edit.
- * Derived from the tools, so a persona made read-only stops being one.
- *
- * @param {object} agent - agents.json entry
- * @returns {boolean}
- */
+/** Derived from the effective tool scope (Write or Edit), so a persona made read-only stops being one. */
 export function isImplementer(agent) {
   const tools = String(agent?.tools ?? DEFAULT_AGENT_TOOLS).split(',').map((t) => t.trim());
   return tools.includes('Write') || tools.includes('Edit');
 }
 
-/**
- * Turn ceiling for a persona that omits agents.json `maxTurns` (ADR-004).
- *
- * 20 is the value the generator hardcoded before the field existed — the v4
- * Tier-2 default (commit 93aad05f) that survived the v5 flattening with no
- * recorded rationale. Keeping it as the default is what lets an old
- * agents.json render byte-for-byte the same .md as before.
- */
+// The value hardcoded before the field existed: an agents.json without `maxTurns` renders byte-for-byte as before.
 export const DEFAULT_MAX_TURNS = 20;
 
-/** Share of the ceiling (percent) at which a sub-agent checkpoints (partial report). */
 const CHECKPOINT_PERCENT = 70;
 
 /**
- * The ONE rule for a valid `maxTurns`. Four readers — installAgents,
- * checkAgentsDrift, doctor's validateAgentsJson and validate-framework.js
- * Check 6 — so the same agents.json can never pass in one and fail in another.
- *
- * Absent (`undefined`) is valid: it means "use the default". Anything present
- * must be an integer >= 1. `null` is NOT absent — whoever wants the default
- * removes the field.
- *
- * @param {unknown} value - the raw agents.json value
+ * The ONE validity rule, shared by installAgents, checkAgentsDrift, doctor and validate-framework.
+ * `undefined` means default; `null` is NOT absent.
  * @returns {string|null} what was expected, or null when valid
  */
 export function maxTurnsProblem(value) {
@@ -71,14 +26,6 @@ export function maxTurnsProblem(value) {
   return Number.isInteger(value) && value >= 1 ? null : 'esperado inteiro >= 1';
 }
 
-/**
- * The full message for an invalid `maxTurns` — persona, value received, what
- * is expected and how to get the default back. Every reader prints this one.
- *
- * @param {string} id - persona id (agents.json key)
- * @param {unknown} value - the raw agents.json value
- * @returns {string|null} null when valid
- */
 export function maxTurnsError(id, value) {
   const problem = maxTurnsProblem(value);
   if (!problem) return null;
@@ -89,41 +36,20 @@ export function maxTurnsError(id, value) {
     `Remova o campo para usar o default ${DEFAULT_MAX_TURNS}.`;
 }
 
-/**
- * Resolve the ceiling a persona is generated with: its `maxTurns`, or the
- * default when absent. Throws `maxTurnsError()` on an invalid value.
- *
- * @param {object} agent - agents.json entry with `id` merged in
- * @returns {number}
- */
 export function resolveMaxTurns(agent) {
   const error = maxTurnsError(agent.id, agent.maxTurns);
   if (error) throw new Error(error);
   return agent.maxTurns ?? DEFAULT_MAX_TURNS;
 }
 
-/** Values Claude Code accepts in a subagent's `effort` frontmatter. */
 export const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
 
-/**
- * The ONE rule for a valid `effort` — same four readers as `maxTurnsProblem`.
- * Absent means the frontmatter carries no `effort:` line and the sub-agent
- * inherits the session's effort, byte-for-byte what the generator emitted
- * before the field existed.
- *
- * @param {unknown} value - the raw agents.json value
- * @returns {string|null} what was expected, or null when valid
- */
+// Absent: no `effort:` line, so the sub-agent inherits the session effort.
 export function effortProblem(value) {
   if (value === undefined) return null;
   return VALID_EFFORTS.includes(value) ? null : `esperado um de ${VALID_EFFORTS.join('|')}`;
 }
 
-/**
- * @param {string} id - persona id (agents.json key)
- * @param {unknown} value - the raw agents.json value
- * @returns {string|null} null when valid
- */
 export function effortError(id, value) {
   const problem = effortProblem(value);
   if (!problem) return null;
@@ -131,26 +57,12 @@ export function effortError(id, value) {
     'Remova o campo para herdar o effort da sessão.';
 }
 
-/** A surface id is the key the mockup checklist names (`Superfície: admin-app`). */
 const SURFACE_ID_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
 const SURFACE_KEYS = new Set(['when', 'standards']);
 
-/**
- * The ONE rule for a valid `surfaces` — the optional map that splits a
- * persona's standards by the kind of screen it works on
- * (`{ "admin-app": { when, standards: [ids] } }`). Same four readers as
- * `maxTurnsProblem`, for the same reason.
- *
- * Absent (`undefined`) is valid: the persona reads only `standards`. A standard
- * listed both in `standards` (read on every surface) and in a surface is
- * refused: that is exactly how a "separated" persona keeps loading marketing
- * standards on a CRUD screen without anyone noticing.
- *
- * @param {unknown} surfaces - the raw agents.json value
- * @param {unknown} [standards] - the persona's universal `standards`
- * @returns {string|null} what is wrong, or null when valid
- */
+// A standard both universal and in a surface is refused: the persona would keep
+// loading it on every surface without anyone noticing.
 export function surfacesProblem(surfaces, standards = []) {
   if (surfaces === undefined) return null;
   if (surfaces === null || typeof surfaces !== 'object' || Array.isArray(surfaces)) {
@@ -185,14 +97,6 @@ export function surfacesProblem(surfaces, standards = []) {
   return null;
 }
 
-/**
- * The full message for an invalid `surfaces`. Every reader prints this one.
- *
- * @param {string} id - persona id (agents.json key)
- * @param {unknown} surfaces
- * @param {unknown} [standards]
- * @returns {string|null} null when valid
- */
 export function surfacesError(id, surfaces, standards) {
   const problem = surfacesProblem(surfaces, standards);
   if (!problem) return null;
@@ -200,14 +104,7 @@ export function surfacesError(id, surfaces, standards) {
     'Remova o campo para a persona ler só `standards`.';
 }
 
-/**
- * Every standard id a persona can cite: the universal list plus each
- * surface's. Reference checks read this, so a surface id that does not exist
- * fails like any other.
- *
- * @param {object} persona - agents.json entry
- * @returns {string[]} unique ids, universal first
- */
+/** @returns {string[]} unique ids of `standards` plus every surface's, universal first */
 export function personaStandardIds(persona) {
   const ids = [...(Array.isArray(persona?.standards) ? persona.standards : [])];
   const surfaces = persona?.surfaces;
@@ -219,48 +116,22 @@ export function personaStandardIds(persona) {
   return [...new Set(ids)];
 }
 
-/** The first validity error of a persona entry, or null — what drift reports as `invalid`. */
 function personaError(agent) {
   return maxTurnsError(agent.id, agent.maxTurns)
     ?? surfacesError(agent.id, agent.surfaces, agent.standards)
     ?? effortError(agent.id, agent.effort);
 }
 
-/**
- * Tools every persona gets on top of its scope. A `tools:` line is a strict
- * allowlist: without `Skill` the sub-agent cannot invoke a single skill, and
- * without `ToolSearch` it cannot load an MCP tool the session defers.
- */
+// `tools:` is a strict allowlist: without Skill no skill runs, without ToolSearch no deferred MCP tool loads.
 export const PLATFORM_TOOLS = ['Skill', 'ToolSearch'];
 
-/**
- * The server names an MCP registry entry is granted under. Claude Code names a
- * server's tools after WHERE it is configured — `mcp__context7__*` from
- * `.mcp.json`, `mcp__plugin_context7_context7__*` from the plugin — and a grant
- * only matches its own spelling (measured 2026-09-24: `mcp__context7` gave a
- * plugin-installed context7 nothing). So every spelling becomes a grant; one
- * the project does not configure is inert.
- *
- * @param {string} id - registry key
- * @param {object} entry - registry entry
- * @returns {string[]}
- */
+// A grant matches only its own spelling (`mcp__context7` vs `mcp__plugin_context7_context7`),
+// so every spelling becomes a grant; one the project does not configure is inert.
 export function mcpServerNames(id, entry) {
-  // A malformed list falls back to the id instead of breaking the render:
-  // installAgents and checkAgentsDrift both go through here (fail-open).
   return serverNamesProblem(id, entry?.serverNames) === null ? entry?.serverNames ?? [id] : [id];
 }
 
-/**
- * The ONE rule for a registry entry's `serverNames` (validate-framework Check 8
- * reads it). Absent is valid (`[id]`). Present: non-empty, only the characters
- * Claude Code keeps in a tool name, and it must include the id itself — that is
- * the name the MCP installer writes into `.mcp.json`.
- *
- * @param {string} id - registry key
- * @param {unknown} value - the raw `serverNames`
- * @returns {string|null} what was expected, or null when valid
- */
+// Must include the id itself: that is the name the MCP installer writes into `.mcp.json`.
 export function serverNamesProblem(id, value) {
   if (value === undefined) return null;
   if (!Array.isArray(value) || value.length === 0) return 'esperado array não vazio';
@@ -269,15 +140,7 @@ export function serverNamesProblem(id, value) {
   return value.includes(id) ? null : `precisa incluir o próprio id "${id}"`;
 }
 
-/**
- * Load the MCP servers known to the framework registry
- * (framework/mcp/registry.json) with the server names each is granted under.
- * Only registry-known ids in agents.json `mcp` become tool grants (fail-open
- * on any error).
- *
- * @param {string} frameworkDir
- * @returns {Map<string, string[]>|null} id → server names; null = no registry found (accept nothing)
- */
+/** @returns {Map<string, string[]>|null} id → server names; null = no registry (grant nothing) */
 export function loadKnownMcpIds(frameworkDir) {
   try {
     const registryPath = join(frameworkDir, 'mcp', 'registry.json');
@@ -289,21 +152,8 @@ export function loadKnownMcpIds(frameworkDir) {
   }
 }
 
-/**
- * Personas install-all default (friction fix, MORPH_GHLBrain 2026-07-11):
- * with NO known stack tags (greenfield / install before config.json exists)
- * EVERY persona is generated — a project that dispatches `morph-{id}` must
- * find the subagent registered, and an install that only lands
- * morph-evaluator forces every domain dispatch into the general-purpose
- * fallback. Stack filtering only applies when the project's stack is KNOWN
- * (tags non-empty): the fallback stays reserved for stacks the project
- * genuinely does not have. Note this deliberately differs from rules/skills
- * filtering (stack-filter.js), which stays minimal on greenfield.
- *
- * @param {object} agent - agents.json entry (with `stack`)
- * @param {string[]} projectTags
- * @returns {boolean}
- */
+// With no known stack tags every persona is generated: a dispatch of `morph-{id}` must find
+// its subagent. Deliberately differs from rules/skills filtering.
 export function agentEligible(agent, projectTags = []) {
   if (projectTags.length === 0) return true;
   return shouldInstall(agent.stack ?? ['*'], projectTags);
@@ -314,17 +164,6 @@ const MANAGED_HEADER =
   '     Do NOT edit by hand: changes are overwritten on `morph-spec update` / `setup-infra --reinstall`.\n' +
   '     To change this persona, edit agents.json and regenerate. Drift is flagged by `morph-spec doctor`. -->';
 
-/**
- * Install morph-spec domain personas as native Claude Code subagents.
- *
- * @param {string} projectDir - Target project directory
- * @param {string} frameworkDir - Path to morph-spec framework/ directory
- * @param {object} options
- * @param {string[]} [options.projectTags=[]] - Stack tags from config (e.g. ['dotnet', 'nextjs'])
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
- *   Coletor de efeitos; o default executa e registra numa lista descartada.
- * @returns {Promise<{ installed: number }>}
- */
 export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
   const { projectTags = [], fx = realEffects() } = options;
 
@@ -336,8 +175,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     .filter(([key]) => !key.startsWith('_comment'))
     .map(([id, data]) => ({ id, ...data }));
 
-  // Validate EVERY persona before the first write: refusing halfway through
-  // would leave some personas regenerated and others stale.
+  // Validate every persona before the first write: refusing halfway leaves a mix of stale and fresh.
   for (const agent of agents) {
     const error = personaError(agent);
     if (error) throw new Error(error);
@@ -348,10 +186,8 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   const knownMcpIds = loadKnownMcpIds(frameworkDir);
 
-  // Filter by stack — install-all when the stack is unknown (empty tags).
   const eligible = agents.filter(a => agentEligible(a, projectTags));
 
-  // Build set of all possible filenames for orphan cleanup
   const allPossible = new Set(agents.map(a => `morph-${a.id}.md`));
 
   let installed = 0;
@@ -373,12 +209,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     installed++;
   }
 
-  // Cleanup orphan morph-* files filtered out by stack.
-  //
-  // Calado em `dryRun` pelo mesmo motivo do laço gêmeo em skills-installer.js
-  // (D6): numa execução real do `update` este diretório acabou de ser apagado
-  // inteiro por `cleanFrameworkDirs()`, então o laço nunca remove nada. Num
-  // dry ingênuo ele veria o diretório antigo e preveria remoções inexistentes.
+  // Silent in dryRun: the real update's cleanFrameworkDirs() already emptied the dir.
   if (!fx.dryRun) {
     for (const file of readdirSync(targetDir)) {
       if (allPossible.has(file) && !installedFilenames.has(file)) {
@@ -390,20 +221,10 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
   return { installed, agents: installedAgents };
 }
 
-/**
- * Render the full .md content for a persona — deterministic, so the same
- * function serves the installer AND the doctor drift check (a hand-edited or
- * stale file differs byte-for-byte from this output).
- *
- * @param {object} agent - agents.json entry with `id` merged in
- * @param {Map<string, string[]>|null} [knownMcpIds] - registry-known MCP ids and
- *   their server names; agents.json `mcp` entries outside it are ignored (null = ignore all)
- * @returns {string} complete file content
- */
+// Deterministic: the doctor drift check compares files byte-for-byte against this output.
 export function renderAgentMd(agent, knownMcpIds = null) {
   const description = buildDescription(agent);
-  // Resolved ONCE: the frontmatter ceiling and the budget the body announces
-  // must be the same number — the sub-agent never sees its own frontmatter.
+  // One value for the frontmatter and the body: the sub-agent never sees its own frontmatter.
   const maxTurns = resolveMaxTurns(agent);
   const surfaces = surfacesError(agent.id, agent.surfaces, agent.standards);
   if (surfaces) throw new Error(surfaces);
@@ -417,9 +238,6 @@ export function renderAgentMd(agent, knownMcpIds = null) {
 function buildToolsLine(agent, knownMcpIds) {
   const base = String(agent.tools ?? DEFAULT_AGENT_TOOLS).split(',').map(t => t.trim()).filter(Boolean);
   const platform = PLATFORM_TOOLS.filter(t => !base.includes(t));
-  // Domain-relevant MCP servers (agents.json `mcp: [ids]`) become server-level
-  // grants, one per server name (`mcp__{name}`). Only registry-known ids are
-  // emitted; in projects without that server configured the grant is inert.
   const mcpGrants = (agent.mcp ?? [])
     .filter(id => knownMcpIds?.has(id))
     .flatMap(id => knownMcpIds.get(id).map(name => `mcp__${name}`));
@@ -428,16 +246,11 @@ function buildToolsLine(agent, knownMcpIds) {
 
 function buildFrontmatter(agent, description, knownMcpIds, maxTurns) {
   const lines = [
-    // Canonical 1:1 naming: frontmatter name === filename === subagent_type.
     `name: morph-${agent.id}`,
     `description: ${description}`,
-    // The evaluator is sonnet here; the dispatch routes it to opus when the risk
-    // detector flags the diff. A persona without the field inherits the session model.
     `model: ${agent.model ?? 'inherit'}`,
     `tools: ${buildToolsLine(agent, knownMcpIds)}`,
-    // Per persona in agents.json (ADR-004); absent → DEFAULT_MAX_TURNS. The
-    // line keeps its position so an agents.json without the field renders
-    // exactly what the hardcoded `maxTurns: 20` rendered.
+    // Position fixed so an agents.json without the field renders byte-for-byte as before.
     `maxTurns: ${maxTurns}`,
   ];
   if (agent.effort) lines.push(`effort: ${agent.effort}`);
@@ -453,6 +266,57 @@ function buildDescription(agent) {
   return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
 }
 
+const NEON_CAUTION = 'NEON: o MCP `neon` inspeciona schema e ensaia migração numa branch descartável ' +
+  '(prepare_database_migration → complete_database_migration); ele também APAGA branch e projeto — ' +
+  'nunca chame tool destrutiva sem confirmação humana explícita.';
+
+const STANDARDS_HINT = 'Digest de cada um: `morph-spec standards --find <id>`; só a seção que importa: ' +
+  '`morph-spec standards --show <id>#<âncora>` (`--show <id>` lista as âncoras).';
+
+export const DISPATCH_CONTRACT = [
+  '## Contrato de dispatch',
+  '',
+  'O dispatch traz só o que muda por fatia: id e título, `cobre` com o texto de cada cenário, `arquivos`, `standards`, ' +
+    'o caminho do relatório e, se houver, o worktree. O resto é este contrato.',
+  '',
+  '1. RELATÓRIO: GRAVE o arquivo de relatório que o dispatch nomeia (`.morph/features/{feature}/3-implement/reports/F{n}.md`) ' +
+    'ANTES de encerrar — é o retorno autoritativo, não a sua mensagem final. `SendMessage` não é substituto do relatório e não deve ser chamado.',
+  '2. ESTADO: NÃO toque em `plan.md`, `checks.json`, `feature.json`, `state.json` nem no board de sessão — todo estado é gravado exclusivamente pelo orquestrador.',
+  '3. TESTE: a prova é do orquestrador (`morph-spec verify {feature}`, depois do seu retorno), não sua. Escreva os testes pelo orçamento: ' +
+    'um por pós-condição, um de regressão por bug, variantes numa tabela (`[Theory]`/`it.each`). NÃO rode teste a cada marco nem faça ciclo red→green: ' +
+    'escreva código e testes, compile, e rode SÓ o filtro dos seus testes UMA vez, em primeiro plano, antes do relatório; se falhar, corrija e rode só os que falharam. ' +
+    'Grave a saída em arquivo (`… > .morph/logs/test-last.log 2>&1`, sem nada depois) e leia o arquivo — um pipe troca o exit do teste pelo do último comando. ' +
+    'Em batch paralelo SEM isolamento, só compile. Com `isolation: "worktree"`, o mesmo vale no seu worktree, e o último ato é o commit na branch dele.',
+  '4. ESCOPO: uma fatia, ~4 arquivos (nunca mais de 8). Escopo maior falha e volta — fatie antes, não depois.',
+  '5. SOBREVIVÊNCIA: o limite de turnos corta sem aviso: commite `wip(F{n})` a cada marco (um arquivo ou uma fatia coerente escrita), não só ao fim — ' +
+    'e só os seus arquivos (`git add <paths>`, nunca `-A` nem diretório). Sem commit, a retomada recomeça do zero.',
+  '6. PROCESSOS: NUNCA `taskkill /IM node.exe` (derruba os MCPs de todas as sessões). Encerre dev server pelo PID que você mesmo subiu. ' +
+    'Build e suíte pesados rodam por `morph-spec heavy run -- <comando>`, em primeiro plano. Exit 3 é fila cheia depois da espera da própria fila: ' +
+    'não repita nem espere em laço — diga no relatório o que não rodou.',
+  '7. REUSO: antes de criar tipo, componente, hook ou serviço NOVO, verifique se já existe: `morph-spec graph explain <nome>` e ' +
+    '`graph affected <conceito> --uses-only`; sem grafo (`no-graph`), caia para `grep -rn "<nome>"` e siga — a ausência de grafo nunca bloqueia. ' +
+    'Se criar mesmo assim, diga por que em uma linha no relatório.',
+  '8. MUTAÇÃO: nunca altere, reverta, mova ou apague código de produção para ver um teste falhar (`sed`, `mv`, `git show HEAD:… >`, `git stash`, ' +
+    '`git checkout --`). A prova de que o teste morde é do verificador (Gate 3).',
+  '9. ESCRITA: código e teste do projeto só por Write/Edit, nunca pelo Bash — heredoc, redirecionamento, `sed -i` ou script python/node que grava (`cat > X.cs <<EOF`, `sed -i … X.cs`): ' +
+    'os guards de escrita só enxergam Write/Edit.',
+  '',
+  'Formato do relatório (o `report-check` lê estas marcas):',
+  '',
+  '```',
+  '# F1 — <título>',
+  'O que foi feito, em 2-3 frases: o comportamento entregue e onde ele mora, sem repetir a lista de arquivos.',
+  '**Arquivos:** `src/a.cs`, `src/a.test.cs`',
+  '**Checks:**',
+  '- C1 — provado: `a.test.cs` › nome do teste (ou `arquivo:linha`)',
+  '- C2 — não provado: por quê',
+  '```',
+  '',
+  '`**Arquivos:**` lista TODO arquivo criado ou modificado, inclusive artefato auxiliar fora do plano (factory, seed, config gerada): ' +
+    'arquivo em produção sem dono é falha de protocolo que o Gate 3 aponta. Todo cenário que a fatia `cobre` aparece em `**Checks:**`. ' +
+    'Problemas e como foram resolvidos vão em prosa depois.',
+];
+
 function buildBody(agent, maxTurns) {
   const lines = [
     `# ${agent.title ?? agent.id}`,
@@ -461,12 +325,20 @@ function buildBody(agent, maxTurns) {
     '',
   ];
 
-  if (agent.domains?.length) {
+  // The shape without effort or surfaces renders byte-for-byte as the old fixture.
+  const legacyShape = !agent.effort && !agent.surfaces && isImplementer(agent);
+
+  if (legacyShape && agent.domains?.length) {
     lines.push('## Domains', ...agent.domains.map(d => `- ${d}`), '');
   }
 
+  if (!legacyShape && agent.mcp?.includes('neon')) {
+    lines.push(NEON_CAUTION, '');
+  }
+
   if (agent.standards?.length) {
     lines.push('## Standards to consult on demand');
+    if (!legacyShape) lines.push(STANDARDS_HINT);
     for (const s of agent.standards) lines.push(`- ${s}`);
     lines.push('');
   }
@@ -485,7 +357,9 @@ function buildBody(agent, maxTurns) {
     }
   }
 
-  if (isImplementer(agent)) {
+  if (agent.effort && isImplementer(agent)) {
+    lines.push(...DISPATCH_CONTRACT, '');
+  } else if (isImplementer(agent)) {
     lines.push(
       '## How you operate',
       '',
@@ -493,33 +367,27 @@ function buildBody(agent, maxTurns) {
       '',
     );
   } else {
-    // A read-only persona has no task to do nor doneCriteria to report.
     lines.push(
       '## Como você opera',
       '',
-      'Você é read-only: nunca escreva, edite nem reverta código, testes, `tasks.json` ou `feature.json` (nada de `git checkout --`). ' +
+      'Você é read-only: nunca escreva, edite nem reverta código, testes, o plano ou `feature.json` (nada de `git checkout --`). ' +
         'O entregável é o arquivo de relatório que o dispatch nomeia; sem arquivo nomeado, é a sua mensagem final (no scout, o mapa).',
       '',
     );
   }
 
   lines.push(
-    // `PARCIAL` on line 1 is what report-check reads; "no verdict" keeps an
-    // evaluator partial from carrying a Verdict the gate would read as final.
+    // `PARCIAL` on line 1 is what report-check reads; "no verdict" keeps a partial
+    // review from carrying a Verdict the gate would read as final.
     '## Turn budget',
     '',
-    // Pasted into EVERY dispatch of every persona — kept to the minimum that
-    // still carries the contract (test/framework/maf-expert-persona.test.js
-    // pins the rendered size).
     `You have ${maxTurns} turns (\`maxTurns\`); at the ceiling you are cut off mid-work, without warning. ` +
       'One response is one turn, however many parallel tool calls it makes. ' +
       `By turn ${checkpointTurn(maxTurns)}, if your dispatch names a report file, save a partial there — ` +
       '`PARCIAL` on line 1, done, remaining, files, no verdict (final report only) — then continue or stop, your call; the final report replaces it.',
   );
 
-  // The dispatch template is paraphrased by the orchestrator in the field; this
-  // body is the only text every implementer dispatch is guaranteed to carry.
-  // Gated on `effort` so a persona without it renders byte-for-byte as before.
+  // The only text every implementer dispatch is guaranteed to carry.
   if (agent.effort && isImplementer(agent)) {
     lines.push(
       '',
@@ -529,37 +397,22 @@ function buildBody(agent, maxTurns) {
         'Use Read/Grep/Glob, never grep/sed/cat/find via Bash. Check a library API in the `context7` MCP before guessing ' +
         '(load a deferred `mcp__` tool with ToolSearch). Write the tests the budget asks for, then run only your own ' +
         'filter ONCE before the report — no red→green cycles, no `morph-spec verify` (the orchestrator proves it). ' +
-        'Never alter, revert or move production code to watch a test fail: mutation proof belongs to the Gate 3 evaluator.',
+        'Never alter, revert or move production code to watch a test fail: mutation proof belongs to the Gate 3 verifier.',
     );
   }
 
   return lines.join('\n');
 }
 
-/** The turn at which a sub-agent with `maxTurns` saves its partial report. */
 function checkpointTurn(maxTurns) {
-  // Integer arithmetic: 0.7 × N in floating point is not always exact.
+  // Integer arithmetic: 0.7 × N in floating point is not exact.
   return Math.max(1, Math.floor((maxTurns * CHECKPOINT_PERCENT) / 100));
 }
 
-/**
- * Compatibility shim for older callers that expected installDomainAgents.
- * In v5 there is no separate "domain" install step — installAgents handles
- * everything from agents.json.
- */
 export async function installDomainAgents(projectDir, frameworkDir, options) {
-  // No-op: domain content is now defined inline in agents.json (persona field).
   return { specialists: 0 };
 }
 
-/**
- * Check which agents SHOULD be installed but are NOT.
- *
- * @param {string} projectDir
- * @param {string} frameworkDir
- * @param {string[]} projectTags
- * @returns {{ missing: Array<{ name: string, stacks: string[] }>, installed: number, expected: number }}
- */
 export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
   const targetDir = join(projectDir, '.claude', 'agents');
   const installedFiles = new Set();
@@ -594,26 +447,8 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
 }
 
 /**
- * Drift check between agents.json (source of truth) and the generated
- * .claude/agents/morph-*.md files. Consumed by `morph-spec doctor`.
- *
- * - missing: eligible persona with no .md installed → run setup-infra --reinstall
- * - stale:   .md exists but differs from renderAgentMd() output (hand-edited
- *            or generated by an older CLI) → regenerate. `staleFields` names
- *            what differs per file: the frontmatter keys, and `body`.
- * - invalid: persona whose agents.json entry cannot be rendered (an invalid
- *            `maxTurns` or `surfaces`) — reported with the reason instead of throwing, so
- *            the doctor prints the cause and not "failed to compute"
- * - orphans: morph-*.md files with no matching agents.json entry
- *
- * @param {string} projectDir
- * @param {string} frameworkDir - directory containing agents.json
- * @param {string[]} projectTags
- * @param {object} [options]
- * @param {string} [options.mcpRegistryDir=frameworkDir] - where `mcp/registry.json`
- *   lives. It must be the directory the INSTALLER read: an installed project's
- *   `.morph/framework/` carries agents.json but no `mcp/`, so rendering against
- *   it drops every `mcp__*` grant and flags a pristine install as stale.
+ * `mcpRegistryDir` must be where the INSTALLER read the registry: the installed
+ * `.morph/framework/` has no `mcp/`, and rendering against it flags a clean install as stale.
  * @returns {{ missing: string[], stale: string[], staleFields: Object<string, string[]>,
  *   invalid: Array<{ file: string, reason: string }>, orphans: string[], expected: number }}
  */
@@ -672,10 +507,6 @@ export function checkAgentsDrift(projectDir, frameworkDir, projectTags = [], opt
   return { missing, stale, staleFields, invalid, orphans, expected };
 }
 
-/**
- * Split a generated .md into its frontmatter map and the rest.
- * @returns {{ fields: Map<string, string>, body: string }}
- */
 function splitAgentMd(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match) return { fields: new Map(), body: content };
@@ -687,11 +518,6 @@ function splitAgentMd(content) {
   return { fields, body: match[2] };
 }
 
-/**
- * Name what differs between a .md on disk and its render: the frontmatter
- * keys whose value (or presence) differs, in render order, then `body`.
- * A file with no parseable frontmatter differs in everything → `frontmatter`.
- */
 function diffAgentMd(onDisk, rendered) {
   const disk = splitAgentMd(onDisk);
   const want = splitAgentMd(rendered);
@@ -699,16 +525,10 @@ function diffAgentMd(onDisk, rendered) {
   const keys = [...new Set([...want.fields.keys(), ...disk.fields.keys()])];
   const fields = keys.filter(k => disk.fields.get(k) !== want.fields.get(k));
   if (disk.body !== want.body) fields.push('body');
-  // Bytes differ but no key/value does (e.g. a stray blank line between the
-  // fences): still drift, and it lives in the frontmatter.
+  // Bytes differ but no key/value does (a stray blank line between the fences).
   return fields.length > 0 ? fields : ['frontmatter'];
 }
 
-/**
- * Compatibility export — kept so existing tests/CLI code that imports
- * formatStandardRef or parseSkillFile / collectSkillFiles still work,
- * but they are no-ops (will be removed in v5.1).
- */
 export function formatStandardRef(standard) {
   if (typeof standard === 'string') return `- ${standard}`;
   const id = standard.id || String(standard);