@polymorphism-tech/morph-spec 7.6.0 → 7.7.1

package/src/commands/tasks/dag.js

@@ -0,0 +1,68 @@
+import chalk from 'chalk';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { parseTasksJson } from '../../lib/tasks/tasks-json-parser.js';
+import { planDispatch } from '../../lib/tasks/dispatch-planner.js';
+
+/**
+ * `morph-spec dag <feature>` — analyze the tasks.json DAG and print the
+ * sequential vs parallel dispatch decision, weighted by effort.
+ *
+ * This is the command morph-apply §2 runs instead of re-deriving the rules
+ * (and instead of the old inline JS snippets the LLM could not execute).
+ */
+export async function dagCommand(featureName, options = {}) {
+  try {
+    const tasksPath = join(process.cwd(), '.morph', 'features', featureName, '2-plan', 'tasks.json');
+    if (!existsSync(tasksPath)) {
+      console.error(chalk.red(`\n❌ tasks.json not found for feature "${featureName}"`));
+      console.error(chalk.gray(`Expected at: .morph/features/${featureName}/2-plan/tasks.json\n`));
+      process.exit(1);
+    }
+
+    // parseTasksJson validates the schema and throws with the error list.
+    const data = await parseTasksJson(tasksPath);
+    const plan = planDispatch(data);
+
+    if (options.json) {
+      console.log(JSON.stringify(plan, null, 2));
+      return;
+    }
+
+    console.log(chalk.bold(`\n📊 DAG — ${featureName}`));
+    console.log('━'.repeat(60));
+
+    const { stats } = plan;
+    console.log(`\nTasks: ${stats.total} total, ${stats.pending} pendente(s)`);
+    const groupLine = Object.keys(stats.groups)
+      .map(g => `${g}:${stats.groups[g]} (peso ${stats.weights[g]})`)
+      .join(' | ');
+    if (groupLine) console.log(chalk.gray(`Grupos pendentes: ${groupLine}`));
+
+    const modeLabel = {
+      'sequential': 'SEQUENCIAL (auto-advance)',
+      'parallel-flows': 'PARALELO por fluxo de domínio',
+      'parallel-roots': 'PARALELO por raízes independentes',
+    }[plan.mode];
+    console.log(chalk.cyan(`\nDecisão: ${modeLabel}`));
+    console.log(`  → ${plan.reason}`);
+
+    for (const flow of plan.flows) {
+      console.log(`  ${chalk.green('▶')} Fluxo ${chalk.bold(flow.group)} (peso ${flow.weight}): ${flow.taskIds.join(', ')}`);
+    }
+    if (plan.batch.length > 0) {
+      console.log(`  ${chalk.green('▶')} Batch paralelo: ${plan.batch.join(', ')}`);
+    }
+    if (plan.inline.length > 0) {
+      console.log(`  ${chalk.yellow('○')} Inline (sem dispatch próprio): ${plan.inline.join(', ')}`);
+    }
+    if (plan.sequentialRemainder.length > 0) {
+      console.log(`  ${chalk.gray('→')} Sequencial: ${plan.sequentialRemainder.join(', ')}`);
+    }
+
+    console.log('\n' + '━'.repeat(60) + '\n');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error analyzing DAG: ${error.message}\n`));
+    process.exit(1);
+  }
+}

package/src/dashboard/scanner/rubrics-scanner.js

@@ -7,6 +7,6 @@ export function scanRubrics(frameworkDir) {
   return readdirSync(dir).filter(f => f.endsWith('.json')).map(f => {
     const d = JSON.parse(readFileSync(join(dir, f), 'utf8'));
     return { id: d.id, version: d.version || '1.0.0', description: d.description || '',
-      categories: d.categories || {}, thresholds: d.thresholds || { approve: 8.0, retry: 6.0 } };
+      categories: d.categories || {}, thresholds: d.thresholds || { approve: 9.0, retry: 6.0 } };
   });
 }

package/src/lib/generators/recap-generator.js

@@ -183,7 +183,7 @@ function buildRecapMarkdown(data) {
     const scores = validationResult.scores;
     md += `### Quality Score: ${scores.score}/10\n\n`;
     md += `| Category | Score | Weight | Status |\n|----------|-------|--------|--------|\n`;
-    const approveThreshold = scores.approveThreshold ?? 8.0;
+    const approveThreshold = scores.approveThreshold ?? 9.0;
     for (const [category, data] of Object.entries(scores.breakdown)) {
       if (category === '_unmapped') continue;
       const pct = Math.round(data.weight * 100);

package/src/lib/tasks/dispatch-planner.js

@@ -0,0 +1,201 @@
+/**
+ * dispatch-planner.js — effort-weighted sequential vs parallel decision for a
+ * feature's tasks.json DAG.
+ *
+ * Encodes the dispatch rules from morph-apply §2 ("Análise de DAG") so the
+ * decision is deterministic and CLI-driven (`morph-spec dag <feature>`)
+ * instead of re-derived by the LLM each session:
+ *
+ *   1. <= 3 tasks total → sequential (dispatch overhead beats the work).
+ *   2. >= 2 independent group flows with enough weight → one agent per flow.
+ *   3. >= 3 independent roots with effort M or heavier → parallel root batch.
+ *   4. otherwise → sequential with auto-advance.
+ *
+ * Effort weighting: S=1, M=2, L=4, XL=8. S-only roots and light flows never
+ * earn their own agent — they are returned as `inline` (the orchestrator runs
+ * them in the sequential lane, or folds them into a single grouped agent), so
+ * dispatch overhead never exceeds the work being dispatched.
+ *
+ * Pure module — operates on a parsed tasks.json document, no I/O.
+ */
+
+export const EFFORT_WEIGHT = { S: 1, M: 2, L: 4, XL: 8 };
+
+/** A root must weigh at least this (effort M) to earn its own agent. */
+export const ROOT_DISPATCH_MIN_WEIGHT = 2;
+
+/** A flow must weigh at least this (an L, or 2×M…) to earn its own agent. */
+export const FLOW_DISPATCH_MIN_WEIGHT = 4;
+
+/** Mirror of the morph-apply cap on simultaneous agents. */
+export const MAX_PARALLEL_AGENTS = 4;
+
+function weightOf(task) {
+  return EFFORT_WEIGHT[task.effort] ?? EFFORT_WEIGHT.M;
+}
+
+function groupOf(task) {
+  // Same fallback as groupTasks() in tasks-json-parser.js
+  return task.group || 'backend';
+}
+
+/**
+ * Ids of tasks whose dependency chain crosses group boundaries — integration
+ * tasks and everything downstream of them. These never belong to a flow: they
+ * run in the sequential lane after the parallel batch converges.
+ */
+function crossGroupTaskIds(tasks) {
+  const byId = new Map(tasks.map(t => [t.id, t]));
+  const cross = new Set();
+
+  for (const task of tasks) {
+    for (const dep of task.dependencies) {
+      const depTask = byId.get(dep);
+      if (depTask && groupOf(depTask) !== groupOf(task)) {
+        cross.add(task.id);
+        break;
+      }
+    }
+  }
+
+  // Propagate downstream: a task depending (transitively) on a cross-group
+  // task cannot run inside a single-group flow either.
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const task of tasks) {
+      if (cross.has(task.id)) continue;
+      if (task.dependencies.some(dep => cross.has(dep))) {
+        cross.add(task.id);
+        changed = true;
+      }
+    }
+  }
+
+  return cross;
+}
+
+function buildStats(tasks, pending) {
+  const groups = {};
+  const weights = {};
+  for (const task of pending) {
+    const g = groupOf(task);
+    groups[g] = (groups[g] || 0) + 1;
+    weights[g] = (weights[g] || 0) + weightOf(task);
+  }
+  return { total: tasks.length, pending: pending.length, groups, weights };
+}
+
+/**
+ * Decide how to execute the remaining tasks of a parsed tasks.json document.
+ *
+ * @param {object} data - parsed tasks.json ({ version, feature, tasks[] })
+ * @returns {{
+ *   mode: 'sequential' | 'parallel-flows' | 'parallel-roots',
+ *   reason: string,
+ *   stats: { total: number, pending: number, groups: object, weights: object },
+ *   flows: Array<{ group: string, taskIds: string[], weight: number }>,
+ *   batch: string[],
+ *   inline: string[],
+ *   sequentialRemainder: string[]
+ * }}
+ */
+export function planDispatch(data) {
+  const tasks = Array.isArray(data?.tasks) ? data.tasks : [];
+  const pending = tasks.filter(t => t.status === 'pending');
+  const stats = buildStats(tasks, pending);
+  const empty = { flows: [], batch: [], inline: [] };
+
+  if (pending.length === 0) {
+    return {
+      mode: 'sequential',
+      reason: 'nenhuma task pendente — nada a despachar',
+      stats, ...empty, sequentialRemainder: [],
+    };
+  }
+
+  // Rule 1 — tiny plans never pay for dispatch.
+  if (tasks.length <= 3) {
+    return {
+      mode: 'sequential',
+      reason: `${tasks.length} task(s) no total (<= 3) — overhead de Agent dispatch não compensa`,
+      stats, ...empty, sequentialRemainder: pending.map(t => t.id),
+    };
+  }
+
+  // Rule 2 — independent domain flows (backend ‖ frontend …).
+  const cross = crossGroupTaskIds(tasks);
+  const flowsMap = new Map();
+  for (const task of pending) {
+    if (cross.has(task.id)) continue;
+    const g = groupOf(task);
+    if (!flowsMap.has(g)) flowsMap.set(g, { group: g, taskIds: [], weight: 0 });
+    const flow = flowsMap.get(g);
+    flow.taskIds.push(task.id);
+    flow.weight += weightOf(task);
+  }
+  const allFlows = [...flowsMap.values()];
+  const worthyFlows = allFlows
+    .filter(f => f.weight >= FLOW_DISPATCH_MIN_WEIGHT)
+    .sort((a, b) => b.weight - a.weight);
+  const lightFlows = allFlows.filter(f => f.weight < FLOW_DISPATCH_MIN_WEIGHT);
+
+  if (worthyFlows.length >= 2) {
+    const flows = worthyFlows.slice(0, MAX_PARALLEL_AGENTS);
+    const overflow = worthyFlows.slice(MAX_PARALLEL_AGENTS);
+    const inline = [
+      ...lightFlows.flatMap(f => f.taskIds),
+      ...overflow.flatMap(f => f.taskIds),
+    ];
+    const sequentialRemainder = pending
+      .filter(t => cross.has(t.id))
+      .map(t => t.id);
+
+    const flowDesc = flows.map(f => `${f.group}:${f.taskIds.length} (peso ${f.weight})`).join(' ‖ ');
+    return {
+      mode: 'parallel-flows',
+      reason:
+        `${flows.length} fluxos de domínio independentes com peso suficiente — ${flowDesc} → ` +
+        `1 agente por fluxo` +
+        (inline.length ? `; ${inline.length} task(s) leve(s) inline (sem dispatch próprio)` : '') +
+        (sequentialRemainder.length ? `; integração cross-group sequencial no fim (${sequentialRemainder.join(', ')})` : ''),
+      stats, flows, batch: [], inline, sequentialRemainder,
+    };
+  }
+
+  // Rule 3 — root fan-out, weighted by effort (S roots never earn an agent).
+  const roots = pending.filter(t => t.dependencies.length === 0);
+  const weightedRoots = roots
+    .filter(t => weightOf(t) >= ROOT_DISPATCH_MIN_WEIGHT)
+    .sort((a, b) => weightOf(b) - weightOf(a));
+  const sRoots = roots.filter(t => weightOf(t) < ROOT_DISPATCH_MIN_WEIGHT);
+
+  if (weightedRoots.length >= 3) {
+    const batch = weightedRoots.slice(0, MAX_PARALLEL_AGENTS).map(t => t.id);
+    const inline = sRoots.map(t => t.id);
+    const sequentialRemainder = pending
+      .filter(t => !batch.includes(t.id) && !inline.includes(t.id))
+      .map(t => t.id);
+
+    return {
+      mode: 'parallel-roots',
+      reason:
+        `${weightedRoots.length} raízes independentes com effort M+ → batch paralelo (${batch.join(', ')})` +
+        (inline.length ? `; raízes S inline — não ganham dispatch próprio (${inline.join(', ')})` : '') +
+        `; restante sequencial`,
+      stats, flows: [], batch, inline, sequentialRemainder,
+    };
+  }
+
+  // Rule 4 — sequential.
+  const reason = roots.length >= 3
+    ? `${roots.length} raízes independentes, mas apenas ${weightedRoots.length} com effort M+ ` +
+      `(raízes S não ganham dispatch próprio — overhead > trabalho) → sequencial com auto-advance`
+    : 'sem fluxos ou raízes independentes suficientes → sequencial com auto-advance';
+
+  return {
+    mode: 'sequential',
+    reason,
+    stats, ...empty, sequentialRemainder: pending.map(t => t.id),
+  };
+}

package/src/lib/validators/score-aggregator.js

@@ -24,7 +24,7 @@ const FALLBACK_RUBRIC = {
       description: 'All validators (fallback — no rubric configured)'
     }
   },
-  thresholds: { approve: 8.0, retry: 6.0 }
+  thresholds: { approve: 9.0, retry: 6.0 }
 };
 
 /**
@@ -176,7 +176,7 @@ export function aggregateScores(validationResult, rubric, configOverrides = {})
   const score = Math.round(weightedScore * 10) / 10;
 
   // Determine action
-  const approveThreshold = configOverrides.approve ?? rubric.thresholds?.approve ?? 8.0;
+  const approveThreshold = configOverrides.approve ?? rubric.thresholds?.approve ?? 9.0;
   const retryThreshold = configOverrides.retry ?? rubric.thresholds?.retry ?? 6.0;
 
   let action;
@@ -210,7 +210,7 @@ export function aggregateScores(validationResult, rubric, configOverrides = {})
  * @param {number} [approveThreshold] - For display
  * @returns {string}
  */
-export function formatScoreBreakdown(scoreResult, approveThreshold = 8.0) {
+export function formatScoreBreakdown(scoreResult, approveThreshold = 9.0) {
   const lines = [];
 
   lines.push(`Score: ${scoreResult.score}/10 (threshold: ${approveThreshold})`);

package/src/scripts/setup-infra.js

@@ -118,6 +118,34 @@ async function installStackAwareAssets(targetPath, log) {
   return { agentCounts, domainCounts, projectTags };
 }
 
+/**
+ * Rewrite the managed personas block in .claude/CLAUDE.md with the agents
+ * ACTUALLY installed (derived list — never a hand-written promise).
+ * No markers / no file → no-op (fail-open).
+ * Exported so `morph-spec update` derives the same block on upgrades.
+ *
+ * @param {string} claudeMdPath - Absolute path to the installed .claude/CLAUDE.md
+ * @param {Array<{ name: string, title: string, domains: string[] }>} agents
+ */
+export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = []) {
+  if (!(await pathExists(claudeMdPath))) return;
+  const START = '<!-- morph-agents:start -->';
+  const END = '<!-- morph-agents:end -->';
+  const content = readFileSync(claudeMdPath, 'utf-8');
+  if (!content.includes(START) || !content.includes(END)) return;
+
+  const list = agents.length > 0
+    ? agents.map(a => `- \`${a.name}\` — ${a.title}${a.domains?.length ? ` (${a.domains.join(', ')})` : ''}`).join('\n')
+    : '_Nenhuma persona instalada — configure `project.stack` em `.morph/config/config.json` e rode `morph-spec setup-infra --reinstall`._';
+
+  const block = `${START}\n**Personas instaladas neste projeto** (derivado de agents.json na última instalação):\n\n${list}\n${END}`;
+  const updated = content.replace(
+    new RegExp(`${START}[\\s\\S]*?${END}`),
+    block
+  );
+  await writeFile(claudeMdPath, updated);
+}
+
 /**
  * Installs MORPH-SPEC infrastructure into the target project directory.
  * Headless — no prompts, no spinner (suppressed when MORPH_QUIET=1), no stack detection.
@@ -138,6 +166,9 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
   if (reinstall) {
     log('setup-infra (reinstall): re-installing stack-aware assets...');
     const { agentCounts, domainCounts } = await installStackAwareAssets(targetPath, log);
+    // Keep the derived personas list in .claude/CLAUDE.md in sync with what
+    // was actually (re)installed.
+    await updateClaudeMdAgentsBlock(join(targetPath, '.claude', 'CLAUDE.md'), agentCounts?.agents ?? []);
     log('setup-infra (reinstall): complete.');
     return {
       agents: {
@@ -236,6 +267,16 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
     await copyDirectory(rubricsSrc, rubricsDest);
   }
 
+  // --- 7c. Copy framework/evals → .morph/framework/evals ---
+  // Rubricas .md (bandas 0-10) + trace-schema.md — referenciadas por
+  // morph-eval/morph-review/agents.json via .morph/framework/evals/.
+  log('Step 7c: Copying evals (rubrics .md + trace schema)...');
+  const evalsSrc = join(FRAMEWORK_DIR, 'evals');
+  const evalsDest = join(frameworkDestDir, 'evals');
+  if (await pathExists(evalsSrc)) {
+    await copyDirectory(evalsSrc, evalsDest);
+  }
+
   // --- 8. Copy framework/agents.json → .morph/framework/agents.json ---
   log('Step 8: Copying agents.json...');
   const agentsSrc = join(FRAMEWORK_DIR, 'agents.json');
@@ -286,6 +327,8 @@ export async function setupInfra(targetPath, { _exec = execSync, reinstall = fal
   const runtimeClaudeMdDest = join(claudeDest, 'CLAUDE.md');
   if (await pathExists(claudeMdSrc)) {
     await copyFile(claudeMdSrc, runtimeClaudeMdDest);
+    // Derive the personas section from what step 10-13 actually installed.
+    await updateClaudeMdAgentsBlock(runtimeClaudeMdDest, agentCounts?.agents ?? []);
   }
 
   // --- 15. installGlobalStatusline (non-critical) ---

package/src/utils/agents-installer.js

@@ -4,6 +4,15 @@
  * 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 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)
@@ -14,6 +23,33 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlink
 import { join } from 'path';
 import { shouldInstall } from '../lib/stack-filter.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';
+
+/**
+ * Load the ids of MCP servers known to the framework registry
+ * (framework/mcp/registry.json). Used to validate agents.json `mcp` entries:
+ * only registry-known servers become tool grants (fail-open on any error).
+ *
+ * @param {string} frameworkDir
+ * @returns {Set<string>|null} null = no registry found (accept nothing)
+ */
+export function loadKnownMcpIds(frameworkDir) {
+  try {
+    const registryPath = join(frameworkDir, 'mcp', 'registry.json');
+    if (!existsSync(registryPath)) return null;
+    const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+    return new Set(Object.keys(registry.mcps ?? {}));
+  } catch {
+    return null;
+  }
+}
+
+const MANAGED_HEADER =
+  '<!-- MANAGED BY morph-spec — generated from .morph/framework/agents.json (single source of truth).\n' +
+  '     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.
  *
@@ -37,6 +73,8 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
   const targetDir = join(projectDir, '.claude', 'agents');
   mkdirSync(targetDir, { recursive: true });
 
+  const knownMcpIds = loadKnownMcpIds(frameworkDir);
+
   // Filter by stack
   const eligible = agents.filter(a => {
     const stack = a.stack ?? ['*'];
@@ -48,17 +86,20 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   let installed = 0;
   const installedFilenames = new Set();
+  const installedAgents = [];
 
   for (const agent of eligible) {
     const filename = `morph-${agent.id}.md`;
     const targetPath = join(targetDir, filename);
 
-    const description = buildDescription(agent);
-    const body = buildBody(agent);
-    const frontmatter = buildFrontmatter(agent, description);
-
-    writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body}\n`, 'utf-8');
+    writeFileSync(targetPath, renderAgentMd(agent, knownMcpIds), 'utf-8');
     installedFilenames.add(filename);
+    installedAgents.push({
+      id: agent.id,
+      name: `morph-${agent.id}`,
+      title: agent.title ?? agent.id,
+      domains: agent.domains ?? [],
+    });
     installed++;
   }
 
@@ -69,15 +110,46 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     }
   }
 
-  return { installed };
+  return { installed, agents: installedAgents };
 }
 
-function buildFrontmatter(agent, description) {
+/**
+ * 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 {Set<string>|null} [knownMcpIds] - registry-known MCP ids; agents.json
+ *   `mcp` entries outside this set are ignored (null = ignore all)
+ * @returns {string} complete file content
+ */
+export function renderAgentMd(agent, knownMcpIds = null) {
+  const description = buildDescription(agent);
+  const frontmatter = buildFrontmatter(agent, description, knownMcpIds);
+  const body = buildBody(agent);
+  return `---\n${frontmatter}---\n\n${MANAGED_HEADER}\n\n${body}\n`;
+}
+
+function buildToolsLine(agent, knownMcpIds) {
+  const base = agent.tools ?? DEFAULT_AGENT_TOOLS;
+  // Domain-relevant MCP servers (agents.json `mcp: [ids]`) become server-level
+  // grants (`mcp__{id}`). 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))
+    .map(id => `mcp__${id}`);
+  return [base, ...mcpGrants].join(', ');
+}
+
+function buildFrontmatter(agent, description, knownMcpIds) {
   const lines = [
-    `name: ${agent.id}`,
+    // Canonical 1:1 naming: frontmatter name === filename === subagent_type.
+    `name: morph-${agent.id}`,
     `description: ${description}`,
-    `model: sonnet`,
-    `tools: Read, Write, Edit, Bash, Glob, Grep`,
+    // Domain implementers inherit the session model by default — a hardcoded
+    // downgrade here would silently lower quality. Override via agents.json.
+    `model: ${agent.model ?? 'inherit'}`,
+    `tools: ${buildToolsLine(agent, knownMcpIds)}`,
     `maxTurns: 20`,
   ];
   if (agent.color) lines.push(`color: ${agent.color}`);
@@ -171,6 +243,66 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
   return { missing, installed: installedFiles.size, expected };
 }
 
+/**
+ * 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
+ * - 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 }}
+ */
+export function checkAgentsDrift(projectDir, frameworkDir, projectTags = []) {
+  const targetDir = join(projectDir, '.claude', 'agents');
+  const agentsJsonPath = join(frameworkDir, 'agents.json');
+  if (!existsSync(agentsJsonPath)) {
+    return { missing: [], stale: [], orphans: [], expected: 0 };
+  }
+
+  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
+  const agents = Object.entries(agentsJson.agents ?? {})
+    .filter(([key]) => !key.startsWith('_comment'))
+    .map(([id, data]) => ({ id, ...data }));
+
+  const knownMcpIds = loadKnownMcpIds(frameworkDir);
+  const knownFilenames = new Set(agents.map(a => `morph-${a.id}.md`));
+  const missing = [];
+  const stale = [];
+  let expected = 0;
+
+  for (const agent of agents) {
+    const stack = agent.stack ?? ['*'];
+    if (!shouldInstall(stack, projectTags)) continue;
+    expected++;
+    const filename = `morph-${agent.id}.md`;
+    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)) {
+      stale.push(filename);
+    }
+  }
+
+  const orphans = [];
+  if (existsSync(targetDir)) {
+    for (const file of readdirSync(targetDir)) {
+      if (file.startsWith('morph-') && file.endsWith('.md') && !knownFilenames.has(file)) {
+        orphans.push(file);
+      }
+    }
+  }
+
+  return { missing, stale, orphans, expected };
+}
+
 /**
  * Compatibility export — kept so existing tests/CLI code that imports
  * formatStandardRef or parseSkillFile / collectSkillFiles still work,

package/src/utils/hooks-installer.js

@@ -102,14 +102,22 @@ const MORPH_HOOKS = [
     ]
   },
 
-  // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) ===
+  // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +
+  // tasks.json schema guard (validate-and-warn; status enum, effort enum) ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
-    }]
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/tasks-json-guard.js',
+        timeout: 3000
+      }
+    ]
   },
 
   // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous state.json updates) ===

package/framework/rubrics/eval-rubric.json

@@ -1,66 +0,0 @@
-{
-  "id": "eval",
-  "version": "1.0.0",
-  "description": "Eval rubric for morph-eval system. Scores phase outputs across structural and semantic dimensions.",
-  "categories": {
-    "structural_compliance": {
-      "weight": 0.25,
-      "description": "Required sections, headers, formatting present in phase outputs",
-      "dimensions": {
-        "proposal": ["has_problem_statement", "has_proposed_solution", "min_length_300"],
-        "spec": ["has_overview", "has_functional_requirements", "has_fr_sections", "has_data_model"],
-        "tasks": ["has_task_headers", "has_fr_references", "no_duplicate_ids"],
-        "contracts": ["has_type_definitions", "correct_naming_conventions"]
-      }
-    },
-    "content_quality": {
-      "weight": 0.30,
-      "description": "LLM-as-judge: completeness, specificity, actionability of outputs",
-      "dimensions": {
-        "completeness": "Covers all aspects of the feature request",
-        "specificity": "Requirements are concrete and testable, not vague",
-        "actionability": "A developer could implement from this alone",
-        "architecture_depth": "Component boundaries, data flow, error handling clear"
-      }
-    },
-    "cross_phase_consistency": {
-      "weight": 0.25,
-      "description": "Alignment between spec, tasks, mandate, and contracts",
-      "dimensions": {
-        "fr_coverage": "Every spec FR referenced by at least one task",
-        "mandate_integrity": "Mandate includes all tasks with acceptance criteria",
-        "contract_alignment": "Spec Data Model entities appear in contracts",
-        "dependency_ordering": "Task dependencies are topologically valid"
-      }
-    },
-    "stack_appropriateness": {
-      "weight": 0.20,
-      "description": "Outputs match the target technology stack",
-      "dimensions": {
-        "correct_language": "Contracts use the right language for the stack (TS vs CS)",
-        "framework_patterns": "Architecture follows stack conventions (App Router, VSA, etc.)",
-        "tool_chain": "Build/test commands match the stack"
-      }
-    }
-  },
-  "thresholds": {
-    "approve": 8.0,
-    "retry": 6.0,
-    "max_iterations": 3,
-    "regression_tolerance": 0.5
-  },
-  "scoring": {
-    "structural": {
-      "method": "binary_checklist",
-      "description": "Each dimension is pass/fail. Score = (passed / total) * 10"
-    },
-    "llm_judge": {
-      "method": "evidence_based",
-      "description": "LLM scores 1-10 per dimension with evidence quotes and gap descriptions"
-    },
-    "cross_phase": {
-      "method": "ratio_based",
-      "description": "FR coverage ratio, mandate inclusion ratio. Score = ratio * 10"
-    }
-  }
-}