@polymorphism-tech/morph-spec 8.37.0 → 8.38.0

package/src/lib/worktree/ignored-triage.js

@@ -18,10 +18,10 @@
  *   REPLICABLE — the primary root has the same relative path with identical
  *                content. Deleting the worktree's copy loses nothing; the
  *                original stays where it always was.
- *   DISPOSABLE — a well-known build artifact (`bin/`, `obj/`, `node_modules/`,
- *                `__pycache__/`, `test-results/`, `.auth/`, `*.tsbuildinfo`).
- *                Reproducible from source, which is a STRONGER guarantee than
- *                backed up.
+ *   DISPOSABLE — a well-known build artifact or cache (`bin/`, `obj/`,
+ *                `node_modules/`, `.next/`, `TestResults/`, `graphify-out/`…,
+ *                see DISPOSABLE_DIR_NAMES). Reproducible from source, which is a
+ *                STRONGER guarantee than backed up.
  *   EXCLUSIVE  — everything else: no counterpart in the root, or a counterpart
  *                whose content differs. These are the only bytes at stake, and
  *                the caller copies them to `finish-backup` before proceeding.
@@ -37,10 +37,16 @@ import { existsSync, lstatSync, readdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 
 /**
- * Well-known, regenerable build artifacts. Deliberately narrow — do NOT add
- * speculative patterns (`dist/`, `.next/`) that a project might legitimately
- * hand-edit; anything unlisted still reaches the EXCLUSIVE bucket, where it is
- * backed up rather than assumed disposable.
+ * Well-known, regenerable build artifacts and caches. Deliberately narrow — do
+ * NOT add names a project might use for hand-written output (`dist/`,
+ * `build/`, `coverage/`); anything unlisted still reaches the EXCLUSIVE bucket,
+ * where it is backed up rather than assumed disposable. Each name here is a
+ * directory its own tool rewrites from scratch: `.next/` (next build/dev),
+ * `.turbo/`, `.pytest_cache/`, `TestResults/` (VSTest), `graphify-out/`
+ * (`morph-spec graph build`). `.next/` is also the one that makes a backup
+ * weigh hundreds of megabytes; `graphify-out/` is seeded into every worktree
+ * and is past the replica size cap (18 MB in a real project), so without its
+ * entry every `finish` would back it up.
  *
  * `.auth/` (Playwright storage state) belongs here for a reason worth stating:
  * it holds a captured session, so it LOOKS like precious local state — but it
@@ -49,6 +55,7 @@ import { join } from 'path';
  */
 const DISPOSABLE_DIR_NAMES = new Set([
   'bin', 'obj', 'node_modules', '__pycache__', 'test-results', '.auth',
+  '.next', '.turbo', '.pytest_cache', 'TestResults', 'graphify-out',
 ]);
 const DISPOSABLE_FILE_RE = /\.tsbuildinfo$/;
 

package/src/lib/worktree/worktree-audit.js

@@ -37,6 +37,7 @@ import { detectDefaultBranch } from '../git/default-branch.js';
 import { buildPrIndex } from '../git/pr-index.js';
 import { classifyBranch, commitsAhead, resolveBaseRef } from '../git/branch-classifier.js';
 import { auditDockerStacks } from './docker-audit.js';
+import { auditFinishBackups } from './finish-backup.js';
 
 const norm = (p) => resolve(p).replace(/\\/g, '/');
 
@@ -423,6 +424,10 @@ export function auditWorktrees(cwd = process.cwd(), { exec } = {}) {
   }
   issues.push(...auditDockerStacks(root, { exec, features: treeFeatures }));
 
+  // What a worktree removal leaves behind in `.git/morph-spec/finish-backup/`
+  // past its retention — `warn`, pruned by `--prune` and by the next finish.
+  issues.push(...auditFinishBackups(root));
+
   return issues;
 }
 

package/src/scripts/setup-infra.js

@@ -174,16 +174,23 @@ export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = [], optio
  * @param {string} targetPath - Absolute path to the target project directory
  * @param {object} options
  * @param {Function} options._exec - exec function (for testing)
+ * @param {Function} [options._detectGraphifyVersion] - graphify probe (for testing: the
+ *   step-18b branches differ with graphify installed or not, and CI has no Python)
+ * @param {Function} [options._log] - log sink (for testing: replaces stdout, which the test
+ *   runner itself reports through — stubbing it swallows test results)
  * @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, force = false } = {}) {
+export async function setupInfra(targetPath, {
+  _exec = execSync, _detectGraphifyVersion = null, _log = null, reinstall = false, force = false,
+} = {}) {
   const quiet = process.env.MORPH_QUIET === '1';
 
   function log(msg) {
-    if (!quiet) process.stdout.write(msg + '\n');
+    if (_log) _log(msg);
+    else if (!quiet) process.stdout.write(msg + '\n');
   }
 
   // Guard: refuse a FULL install from inside a secondary (linked) worktree.
@@ -441,24 +448,26 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
   // (setup-infra-cmd.js), então nada aqui pode escapar do try.
   log('Step 18b: Codebase graph (graphify)...');
   try {
-    const { writeGraphifyignore } = await import('../lib/graph/graphifyignore.js');
+    const { writeGraphifyignore, describeOutdatedIgnore } = await import('../lib/graph/graphifyignore.js');
     const {
       detectInstaller, installArgs, detectGraphifyVersion,
-      GRAPHIFY_VERSION, GRAPHIFY_BIN, GRAPHIFY_PACKAGE,
+      GRAPHIFY_VERSION, GRAPHIFY_PACKAGE,
     } = await import('../lib/graph/graphify-runtime.js');
     const { ensureClaudeignore } = await import('../utils/file-copier.js');
     const { scanDatabaseSchema } = await import('../lib/generators/architecture-scanner.js');
 
     const ignore = writeGraphifyignore(targetPath, projectTags ?? []);
-    log(ignore.written
-      ? '  ✓ .graphifyignore (stack-aware)'
-      : '  ✓ .graphifyignore já existia — preservado');
+    if (ignore.migrated) log('  ✓ .graphifyignore atualizado (dublês, fixtures e helpers de teste no grafo)');
+    else if (ignore.written) log('  ✓ .graphifyignore (stack-aware)');
+    else log('  ✓ .graphifyignore já existia — preservado');
+    if (ignore.outdated) log(`  ⚠ ${describeOutdatedIgnore(ignore.outdated)}`);
 
     // Um graph.json de 12 MB reescrito a cada commit invalida o prompt cache.
     await ensureClaudeignore(targetPath, ['graphify-out/']);
     log('  ✓ graphify-out/ no .claudeignore');
 
-    const installed = detectGraphifyVersion();
+    const probe = _detectGraphifyVersion ?? detectGraphifyVersion;
+    const installed = probe();
     if (installed === GRAPHIFY_VERSION) {
       log(`  ✓ graphify ${installed} já instalado`);
     } else {
@@ -479,16 +488,18 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
       }
     }
 
-    if (detectGraphifyVersion()) {
-      try {
-        // Só os git hooks (post-commit/post-checkout/merge driver). NUNCA
-        // `graphify claude install`: ele escreveria uma seção no CLAUDE.md e um
-        // PreToolUse hook próprio, colidindo com os hooks do morph-spec.
-        _exec(`${GRAPHIFY_BIN} hook install`, { cwd: targetPath, stdio: 'ignore' });
-        log('  ✓ git hooks do graphify (rebuild assíncrono no post-commit)');
-      } catch {
-        log('  ⚠ graphify hook install falhou — rode manualmente se quiser rebuild automático');
-      }
+    // Nenhum hook do graphify: o refresh mora nos hooks do Claude (step 16 —
+    // graph-refresh-kick + SessionStart), que o `update` reinstala. O
+    // `graphify hook install` ficou de fora por três defeitos medidos no 0.9.50:
+    // sai sem fazer nada em worktree vinculada, não tem post-merge (merge e pull
+    // nunca rebuildam) e, num commit depois de um fast-forward, carimba o HEAD
+    // num grafo sem os arquivos do merge. E nunca `graphify claude install`:
+    // escreveria no CLAUDE.md e um PreToolUse próprio.
+    //
+    // A linha só sai com o graphify presente, e diz o que dispara de fato: um
+    // commit feito no terminal não dispara nada até o próximo desses.
+    if (probe()) {
+      log('  ✓ refresh automático do grafo da raiz: depois dos comandos git/gh/morph-spec do agente e no início de cada sessão');
     }
   } catch (err) {
     log(`  ⚠ Step do grafo pulado: ${err.message}`);

package/src/utils/agents-installer.js

@@ -29,6 +29,172 @@ 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}
+ */
+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.
+ */
+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
+ * @returns {string|null} what was expected, or null when valid
+ */
+export function maxTurnsProblem(value) {
+  if (value === undefined) return null;
+  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;
+  const shown = typeof value === 'string' || (value !== null && typeof value === 'object')
+    ? JSON.stringify(value)
+    : String(value);
+  return `agents.json: persona "${id}" tem maxTurns inválido (${shown}) — ${problem}. ` +
+    `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;
+}
+
+/** 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
+ */
+export function surfacesProblem(surfaces, standards = []) {
+  if (surfaces === undefined) return null;
+  if (surfaces === null || typeof surfaces !== 'object' || Array.isArray(surfaces)) {
+    return 'esperado objeto { "<superfície>": { when, standards } }';
+  }
+  const entries = Object.entries(surfaces);
+  if (entries.length === 0) return 'esperado ao menos uma superfície';
+
+  const universal = new Set(Array.isArray(standards) ? standards : []);
+  for (const [name, def] of entries) {
+    if (!SURFACE_ID_RE.test(name)) return `superfície "${name}" — o id é kebab-case (ex.: "admin-app")`;
+    if (def === null || typeof def !== 'object' || Array.isArray(def)) {
+      return `superfície "${name}" — esperado { when, standards }`;
+    }
+    const unknown = Object.keys(def).filter((k) => !SURFACE_KEYS.has(k));
+    if (unknown.length > 0) return `superfície "${name}" — campo desconhecido: ${unknown.join(', ')}`;
+    if (typeof def.when !== 'string' || def.when.trim() === '') {
+      return `superfície "${name}" — "when" precisa dizer que telas são dessa superfície`;
+    }
+    const ids = def.standards;
+    if (!Array.isArray(ids) || ids.length === 0 || ids.some((s) => typeof s !== 'string' || s.trim() === '')) {
+      return `superfície "${name}" — "standards" precisa ser uma lista não vazia de ids`;
+    }
+    const repeated = ids.filter((s, i) => ids.indexOf(s) !== i);
+    if (repeated.length > 0) return `superfície "${name}" repete ${[...new Set(repeated)].join(', ')}`;
+    const overlap = ids.filter((s) => universal.has(s));
+    if (overlap.length > 0) {
+      return `superfície "${name}" repete standard da lista universal (${overlap.join(', ')}) — ` +
+        'um standard é universal OU de uma superfície';
+    }
+  }
+  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;
+  return `agents.json: persona "${id}" tem surfaces inválido — ${problem}. ` +
+    '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
+ */
+export function personaStandardIds(persona) {
+  const ids = [...(Array.isArray(persona?.standards) ? persona.standards : [])];
+  const surfaces = persona?.surfaces;
+  if (surfaces && typeof surfaces === 'object' && !Array.isArray(surfaces)) {
+    for (const def of Object.values(surfaces)) {
+      if (Array.isArray(def?.standards)) ids.push(...def.standards);
+    }
+  }
+  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);
+}
+
 /**
  * Load the ids of MCP servers known to the framework registry
  * (framework/mcp/registry.json). Used to validate agents.json `mcp` entries:
@@ -95,6 +261,13 @@ 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.
+  for (const agent of agents) {
+    const error = personaError(agent);
+    if (error) throw new Error(error);
+  }
+
   const targetDir = join(projectDir, '.claude', 'agents');
   fx.ensureDir(targetDir);
 
@@ -154,8 +327,13 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
  */
 export function renderAgentMd(agent, knownMcpIds = null) {
   const description = buildDescription(agent);
-  const frontmatter = buildFrontmatter(agent, description, knownMcpIds);
-  const body = buildBody(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.
+  const maxTurns = resolveMaxTurns(agent);
+  const surfaces = surfacesError(agent.id, agent.surfaces, agent.standards);
+  if (surfaces) throw new Error(surfaces);
+  const frontmatter = buildFrontmatter(agent, description, knownMcpIds, maxTurns);
+  const body = buildBody(agent, maxTurns);
   return `---\n${frontmatter}---\n\n${MANAGED_HEADER}\n\n${body}\n`;
 }
 
@@ -170,7 +348,7 @@ function buildToolsLine(agent, knownMcpIds) {
   return [base, ...mcpGrants].join(', ');
 }
 
-function buildFrontmatter(agent, description, knownMcpIds) {
+function buildFrontmatter(agent, description, knownMcpIds, maxTurns) {
   const lines = [
     // Canonical 1:1 naming: frontmatter name === filename === subagent_type.
     `name: morph-${agent.id}`,
@@ -181,7 +359,10 @@ function buildFrontmatter(agent, description, knownMcpIds) {
     // personas that omit the field.
     `model: ${agent.model ?? 'inherit'}`,
     `tools: ${buildToolsLine(agent, knownMcpIds)}`,
-    `maxTurns: 20`,
+    // 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.
+    `maxTurns: ${maxTurns}`,
   ];
   if (agent.color) lines.push(`color: ${agent.color}`);
   lines.push(`memory: project`, '');
@@ -195,7 +376,7 @@ function buildDescription(agent) {
   return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
 }
 
-function buildBody(agent) {
+function buildBody(agent, maxTurns) {
   const lines = [
     `# ${agent.title ?? agent.id}`,
     '',
@@ -213,15 +394,51 @@ function buildBody(agent) {
     lines.push('');
   }
 
+  if (agent.surfaces) {
+    const read = agent.standards?.length ? 'Read the list above plus only' : 'Read only';
+    lines.push(
+      '## Standards by surface',
+      '',
+      'A screen is ONE surface — the mockup checklist names it (`Superfície`). ' +
+        `${read} the list of that screen's surface; never another surface's standards for that screen.`,
+      '',
+    );
+    for (const [name, def] of Object.entries(agent.surfaces)) {
+      lines.push(`### ${name}`, def.when, ...def.standards.map((s) => `- ${s}`), '');
+    }
+  }
+
   lines.push(
     '## How you operate',
     '',
     'You are a domain persona dispatched per task. Read the spec/mandate/tasks/standards passed to you, do the work, and return a concise summary plus an auto-score 0-10. Refer to MORPH.md section 6 for the dispatch contract.',
+    '',
+    // Generic on purpose: this body reaches every dispatch (implement, apply,
+    // uiux, hotfix, review). The scout has no canonical file and no Write; the
+    // evaluator's file is evaluator-report.md. `PARCIAL` on line 1 is what
+    // report-check reads (verdict report-incomplete, action resume); "no
+    // score" keeps an evaluator partial from carrying a Composite-Score 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 score (final report only) — then continue or stop, your call; the final report replaces it.',
   );
 
   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.
+  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
@@ -279,19 +496,30 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
  *
  * - 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
+ *            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
- * @returns {{ missing: string[], stale: string[], orphans: string[], expected: number }}
+ * @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.
+ * @returns {{ missing: string[], stale: string[], staleFields: Object<string, string[]>,
+ *   invalid: Array<{ file: string, reason: string }>, orphans: string[], expected: number }}
  */
-export function checkAgentsDrift(projectDir, frameworkDir, projectTags = []) {
+export function checkAgentsDrift(projectDir, frameworkDir, projectTags = [], options = {}) {
+  const { mcpRegistryDir = frameworkDir } = options;
   const targetDir = join(projectDir, '.claude', 'agents');
   const agentsJsonPath = join(frameworkDir, 'agents.json');
   if (!existsSync(agentsJsonPath)) {
-    return { missing: [], stale: [], orphans: [], expected: 0 };
+    return { missing: [], stale: [], staleFields: {}, invalid: [], orphans: [], expected: 0 };
   }
 
   const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
@@ -299,24 +527,33 @@ export function checkAgentsDrift(projectDir, frameworkDir, projectTags = []) {
     .filter(([key]) => !key.startsWith('_comment'))
     .map(([id, data]) => ({ id, ...data }));
 
-  const knownMcpIds = loadKnownMcpIds(frameworkDir);
+  const knownMcpIds = loadKnownMcpIds(mcpRegistryDir);
   const knownFilenames = new Set(agents.map(a => `morph-${a.id}.md`));
   const missing = [];
   const stale = [];
+  const staleFields = {};
+  const invalid = [];
   let expected = 0;
 
   for (const agent of agents) {
     if (!agentEligible(agent, projectTags)) continue;
     expected++;
     const filename = `morph-${agent.id}.md`;
+    const error = personaError(agent);
+    if (error) {
+      invalid.push({ file: filename, reason: error });
+      continue;
+    }
     const filePath = join(targetDir, filename);
     if (!existsSync(filePath)) {
       missing.push(filename);
       continue;
     }
     const onDisk = readFileSync(filePath, 'utf-8').replace(/\r\n/g, '\n');
-    if (onDisk !== renderAgentMd(agent, knownMcpIds)) {
+    const rendered = renderAgentMd(agent, knownMcpIds);
+    if (onDisk !== rendered) {
       stale.push(filename);
+      staleFields[filename] = diffAgentMd(onDisk, rendered);
     }
   }
 
@@ -329,7 +566,39 @@ export function checkAgentsDrift(projectDir, frameworkDir, projectTags = []) {
     }
   }
 
-  return { missing, stale, orphans, expected };
+  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 };
+  const fields = new Map();
+  for (const line of match[1].split('\n')) {
+    const kv = line.match(/^([A-Za-z][\w-]*):\s?(.*)$/);
+    if (kv) fields.set(kv[1], kv[2]);
+  }
+  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);
+  if (disk.fields.size === 0) return disk.body === want.body ? ['frontmatter'] : ['frontmatter', 'body'];
+  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.
+  return fields.length > 0 ? fields : ['frontmatter'];
 }
 
 /**