@polymorphism-tech/morph-spec 9.8.0 → 10.1.1

package/src/lib/installers/stack-sync.js

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { detectProject } from '../detectors/index.js';
+import { getProjectTags, parseStacks, shouldInstall } from '../stack-filter.js';
+import { WORKTREE_DIR_NAMES } from '../worktree/dirs.js';
+import { resolveComposeFile } from '../../../framework/hooks/shared/e2e-check.js';
+import { createEffects } from './effects.js';
+import { MAF_RULE, MAF_TAG, installRuleFile, ruleContentFor } from './rules-installer.js';
+
+const RULES_SRC = join(import.meta.dirname, '..', '..', '..', 'framework', 'rules');
+const STACK_TAGS = new Set(['nextjs', 'dotnet']);
+const SKIP_DIRS = new Set(['node_modules', 'bin', 'obj', ...WORKTREE_DIR_NAMES]);
+const MAX_DEPTH = 5;
+const MAX_ENTRIES = 20000;
+const NEXT_CONFIG = /^next\.config\.(js|mjs|cjs|ts|mts)$/;
+const DOCKER_FILE = /^(Dockerfile.*|docker-compose\..*|compose\.ya?ml)$/;
+const MAF_PACKAGE =/Include="Microsoft\.Agents\.AI(\.[^"]*)?"/;
+
+function ruleFiles(rulesSrc) {
+  return readdirSync(rulesSrc).filter((f) => f.endsWith('.md'))
+    .map((file) => ({ file, stacks: parseStacks(readFileSync(join(rulesSrc, file), 'utf-8')) }));
+}
+
+/** The tags some rule's `stacks:` names: the only detected tags worth persisting. */
+export function ruleTags(rulesSrc = RULES_SRC) {
+  return new Set(ruleFiles(rulesSrc).flatMap(({ stacks }) => stacks).filter((s) => s !== '*'));
+}
+
+function walk(root, visit) {
+  let seen = 0;
+  const stack = [[root, 0]];
+  while (stack.length) {
+    const [dir, depth] = stack.pop();
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (++seen > MAX_ENTRIES) return;
+      if (e.isDirectory()) {
+        if (depth < MAX_DEPTH && !e.name.startsWith('.') && !SKIP_DIRS.has(e.name)) stack.push([join(dir, e.name), depth + 1]);
+      } else if (e.isFile()) {
+        visit(e.name, join(dir, e.name));
+      }
+    }
+  }
+}
+
+/**
+ * `tags`: what the files show, for picking rules. `persist`: the subset safe to write into config.json —
+ * `docker` only with a compose file, since a declared `docker` without one turns the e2e node red.
+ */
+export function detectStackTags(projectDir, { config = null, rulesSrc = RULES_SRC } = {}) {
+  const found = new Set();
+  const { structure } = detectProject(projectDir);
+  for (const t of String(structure.stack).split('+')) found.add(t);
+  for (const t of structure.integrations) found.add(t);
+
+  walk(projectDir, (name, path) => {
+    if (name.endsWith('.csproj') || name.endsWith('.sln') || name.endsWith('.slnx')) found.add('dotnet');
+    if (NEXT_CONFIG.test(name)) found.add('nextjs');
+    if (DOCKER_FILE.test(name)) found.add('docker');
+    if (name.endsWith('.csproj') || name === 'Directory.Packages.props') {
+      try { if (MAF_PACKAGE.test(readFileSync(path, 'utf-8'))) found.add(MAF_TAG); } catch { /* unreadable: not MAF */ }
+    }
+  });
+
+  const wanted = ruleTags(rulesSrc);
+  wanted.add(MAF_TAG);
+  const tags = [...found].filter((t) => wanted.has(t));
+  const hasCompose = Boolean(resolveComposeFile(projectDir, config ?? {}));
+  const persist = tags.filter((t) => t !== 'docker' || hasCompose);
+  return { tags, persist };
+}
+
+/** Adds the tags the config lacks; never removes one. `unknown` is a placeholder, not a tag. */
+export function mergeDetectedTags(config, tags) {
+  const have = new Set(getProjectTags(config));
+  const added = tags.filter((t) => !have.has(t));
+  if (added.length === 0) return { config, added, changed: false };
+
+  const project = { ...(config.project ?? {}) };
+  const stackParts = typeof project.stack === 'string'
+    ? project.stack.split('+').filter((s) => s && s !== 'unknown')
+    : [];
+  const integrations = Array.isArray(project.integrations) ? [...project.integrations] : [];
+  for (const t of added) (STACK_TAGS.has(t) ? stackParts : integrations).push(t);
+  if (stackParts.length) project.stack = stackParts.join('+');
+  if (integrations.length) project.integrations = integrations;
+  return { config: { ...config, project }, added, changed: true };
+}
+
+const configPathOf = (projectDir) => join(projectDir, '.morph', 'config', 'config.json');
+
+function readConfig(path) {
+  return JSON.parse(readFileSync(path, 'utf-8').replace(/^/, ''));
+}
+
+function missingRules(projectDir, tags, rulesSrc) {
+  const rulesDest = join(projectDir, '.claude', 'rules');
+  const missing = [];
+  const stale = [];
+  for (const { file, stacks } of ruleFiles(rulesSrc)) {
+    if (stacks.includes('*') || !shouldInstall(stacks, tags)) continue;
+    const dest = join(rulesDest, file);
+    if (!existsSync(dest)) { missing.push(file); continue; }
+    if (file !== MAF_RULE || !tags.includes(MAF_TAG)) continue;
+    const desired = ruleContentFor(file, readFileSync(join(rulesSrc, file), 'utf-8'), tags);
+    if (readFileSync(dest, 'utf-8') !== desired) stale.push(file);
+  }
+  return { missing, stale };
+}
+
+let warned = false;
+function warnOnce(log, message) {
+  if (warned) return;
+  warned = true;
+  log(`⚠ stack-sync: ${message}`);
+}
+
+const NOOP = Object.freeze({ added: [], updated: [], tags: [], configChanged: false });
+
+/**
+ * Installs every stack rule (a `stacks:` other than `*`) the project needs and lacks, after adding to
+ * config.json the stack tags its files show. Only an installed project (with config.json) is touched. Never throws.
+ * `persistTags: false` leaves config.json alone: a check (`verify`) may write gitignored harness files, never a tracked one.
+ */
+export function syncStackRules(projectDir, {
+  dryRun = false, fx = createEffects({ dryRun }), log = (line) => console.log(line), rulesSrc = RULES_SRC,
+  persistTags = true,
+} = {}) {
+  try {
+    const configPath = configPathOf(projectDir);
+    if (!existsSync(configPath)) return { ...NOOP };
+    let config;
+    try { config = readConfig(configPath); } catch {
+      warnOnce(log, `${configPath} ilegível — regras de stack não sincronizadas`);
+      return { ...NOOP };
+    }
+
+    const detected = detectStackTags(projectDir, { config, rulesSrc });
+    const merged = persistTags
+      ? mergeDetectedTags(config, detected.persist)
+      : { config, added: [], changed: false };
+    if (merged.changed) {
+      fx.writeJson(configPath, merged.config);
+      log(`  + config.json: ${merged.added.join(', ')} (detectado nos arquivos)`);
+    }
+
+    const tags = [...new Set([...getProjectTags(merged.config), ...detected.tags])];
+    const { missing, stale } = missingRules(projectDir, tags, rulesSrc);
+    const rulesDest = join(projectDir, '.claude', 'rules');
+    for (const file of [...missing, ...stale]) {
+      installRuleFile(rulesSrc, rulesDest, file, tags, fx);
+      log(`  + .claude/rules/${file} (stack: ${tags.join('+')})`);
+    }
+    return { added: missing, updated: stale, tags, configChanged: merged.changed };
+  } catch (err) {
+    warnOnce(log, err?.message ?? String(err));
+    return { ...NOOP };
+  }
+}
+
+/** What `stack-set` accepts: the stack tags, and the integrations some rule (or the MAF rewrite) reacts to. */
+export function knownStackTags(rulesSrc = RULES_SRC) {
+  const integrations = [...ruleTags(rulesSrc), MAF_TAG].filter((t) => !STACK_TAGS.has(t));
+  return { stacks: [...STACK_TAGS].sort(), integrations: [...new Set(integrations)].sort() };
+}
+
+/**
+ * The user's choice of stack, written into config.json (`project.stack` replaced, `integrations` added to),
+ * then the rules it needs installed. `{ error }` names what was refused; nothing is written then.
+ */
+export function setProjectStack(projectDir, stack, {
+  integrations = [], dryRun = false, fx = createEffects({ dryRun }), log = (line) => console.log(line), rulesSrc = RULES_SRC,
+} = {}) {
+  const configPath = configPathOf(projectDir);
+  if (!existsSync(configPath)) return { error: `${configPath} ausente — rode morph-spec init antes` };
+  const known = knownStackTags(rulesSrc);
+  const stackTags = String(stack ?? '').split('+').map((t) => t.trim()).filter(Boolean);
+  const unknown = [
+    ...stackTags.filter((t) => !known.stacks.includes(t)),
+    ...integrations.filter((t) => !known.integrations.includes(t)),
+  ];
+  if (stackTags.length === 0 || unknown.length > 0) {
+    return { error: `tag desconhecida: ${unknown.join(', ') || '(stack vazia)'}. Stack: ${known.stacks.join(' | ')} (unidas por +); --with: ${known.integrations.join(', ')}` };
+  }
+  let config;
+  try { config = readConfig(configPath); } catch { return { error: `${configPath} ilegível` }; }
+  if (integrations.includes('docker') && !resolveComposeFile(projectDir, config)) {
+    return { error: 'docker sem compose deixa o nó e2e vermelho: crie o compose primeiro (o plan-check e o update declaram docker quando ele existir)' };
+  }
+
+  const project = { ...(config.project ?? {}), stack: stackTags.join('+') };
+  const merged = [...new Set([...(Array.isArray(project.integrations) ? project.integrations : []), ...integrations])];
+  if (merged.length) project.integrations = merged;
+  fx.writeJson(configPath, { ...config, project });
+  log(`  + config.json: project.stack = ${project.stack}${merged.length ? `, integrations = ${merged.join(', ')}` : ''}`);
+  return { stack: project.stack, integrations: merged, sync: syncStackRules(projectDir, { dryRun, fx, log, rulesSrc }) };
+}
+
+/** Read-only, for `doctor`: what `syncStackRules` would add. `null` when the config is absent or unreadable. */
+export function stackRuleGaps(projectDir, { rulesSrc = RULES_SRC } = {}) {
+  try {
+    const configPath = configPathOf(projectDir);
+    if (!existsSync(configPath)) return null;
+    const config = readConfig(configPath);
+    const stack = config?.project?.stack;
+    const detected = detectStackTags(projectDir, { config, rulesSrc });
+    const tags = [...new Set([...getProjectTags(config), ...detected.tags])];
+    const { missing, stale } = missingRules(projectDir, tags, rulesSrc);
+    return {
+      stackMissing: !stack || stack === 'unknown',
+      undeclared: detected.persist.filter((t) => !getProjectTags(config).includes(t)),
+      missing: [...missing, ...stale],
+      tags,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/lib/plan/checks.js

@@ -2,88 +2,18 @@ import { createHash } from 'crypto';
 import { existsSync, readFileSync } from 'fs';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { frozenBody } from '../../../framework/hooks/shared/errata.js';
-import { readAgentsJson } from '../specs/screen-checklist.js';
 import { getFeature } from '../../../framework/hooks/shared/state-reader.js';
 import { findArtifactTerms } from './artifact-vocabulary.js';
-import { PROOF_KINDS, RISK_KINDS, REUSE_VERDICTS, ADR_SCOPES, SECTIONS, CONFLICTS_HEADING } from './plan-parser.js';
+import { mediaCitationError } from './media.js';
+import { PROOF_KINDS, RISK_KINDS, REWORK_RUNGS, REUSE_VERDICTS, ADR_SCOPES, SECTIONS, CONFLICTS_HEADING } from './plan-parser.js';
 
 export const CHECKS_VERSION = 1;
-export const MAX_SLICE_FILES = 8;
-export const MAX_SLICES = 12;
-export const MAX_PARALLEL = 4;
 
 /** sha256 of the plan without its errata: appending a correction never invalidates the extracted checks. */
 export function planHash(text) {
   return createHash('sha256').update(frozenBody(text), 'utf8').digest('hex');
 }
 
-/** The installed agents.json, else the package's; null when unreadable (personas then go unchecked). */
-export function knownPersonas(cwd) {
-  const agents = readAgentsJson(cwd)?.agents;
-  return agents && typeof agents === 'object' ? Object.keys(agents) : null;
-}
-
-/** The ids on a dependency cycle, or null. */
-export function dependencyCycle(slices) {
-  const deps = new Map(slices.map((s) => [s.id, s.depends ?? []]));
-  const state = new Map();
-  const stack = [];
-  const visit = (id) => {
-    if (state.get(id) === 'done' || !deps.has(id)) return null;
-    if (state.get(id) === 'open') return stack.slice(stack.indexOf(id)).concat(id);
-    state.set(id, 'open');
-    stack.push(id);
-    for (const dep of deps.get(id)) {
-      const cycle = visit(dep);
-      if (cycle) return cycle;
-    }
-    stack.pop();
-    state.set(id, 'done');
-    return null;
-  };
-  for (const id of deps.keys()) {
-    const cycle = visit(id);
-    if (cycle) return cycle;
-  }
-  return null;
-}
-
-const fileKey = (f) => f.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
-
-// A slice joins a wave only after its dependencies ran, never with one touching its files, and at most
-// MAX_PARALLEL per wave. Empty on a dependency cycle.
-export function parallelGroups(slices) {
-  if (dependencyCycle(slices)) return [];
-  const ids = new Set(slices.map((s) => s.id));
-  const depth = new Map();
-  const depthOf = (slice) => {
-    if (depth.has(slice.id)) return depth.get(slice.id);
-    const parents = (slice.depends ?? []).filter((d) => ids.has(d)).map((d) => slices.find((s) => s.id === d));
-    const value = parents.length === 0 ? 0 : 1 + Math.max(...parents.map(depthOf));
-    depth.set(slice.id, value);
-    return value;
-  };
-  const layers = [];
-  for (const slice of slices) (layers[depthOf(slice)] ??= []).push(slice);
-
-  const groups = [];
-  for (const layer of layers.filter(Boolean)) {
-    const open = [];
-    for (const slice of layer) {
-      const files = new Set((slice.files ?? []).map(fileKey));
-      const group = open.find((g) => g.ids.length < MAX_PARALLEL && ![...files].some((f) => g.files.has(f)));
-      if (group) {
-        group.ids.push(slice.id);
-        files.forEach((f) => group.files.add(f));
-      } else {
-        open.push({ ids: [slice.id], files });
-      }
-    }
-    groups.push(...open.map((g) => g.ids));
-  }
-  return groups;
-}
-
 // A frozen body already extracted under older rules cannot gain a `risco:` line, so it is not demanded.
 export function planRuleOptions(cwd, featureName) {
   return {
@@ -94,14 +24,53 @@ export function planRuleOptions(cwd, featureName) {
 
 const foldRisk = (s) => s.normalize('NFD').replace(/\p{M}/gu, '').replace(/`/g, '').toLowerCase().trim();
 const RISK_BY_FOLD = new Map(RISK_KINDS.map((r) => [foldRisk(r), r]));
+const RUNG_BY_FOLD = new Map(REWORK_RUNGS.map((r) => [foldRisk(r), r]));
+const canonicalRung = (rung) => (rung === null ? null : RUNG_BY_FOLD.get(foldRisk(rung)) ?? false);
 const REGRESSION_WORK_TYPES = ['bug', 'hotfix'];
+const POLICY_PLAN_WORK_TYPES = ['chore', 'hotfix'];
+// Vetar por número só vale para o que custa pouco errar: o resto é pergunta. Aviso, não erro: o vocabulário
+// é comum em plano por outros motivos, e um erro só ensinaria a reescrever a linha.
+const NEVER_DEFAULT_RE = /\b(autentica\w*|senha|password|credencia\w*|segredo|secret|api key|chave de api|permiss\w*|pagamento|cobranc\w*|billing|drop (table|column)|(apaga\w*|delet\w*|exclu\w*) (o |os |a |as )?(dado|registro|lead|conta|cliente)s?)\b/;
+
+function defaultsWarnings(plan, at) {
+  return plan.defaults.items.flatMap((d) => {
+    const hit = NEVER_DEFAULT_RE.exec(foldRisk(d.text));
+    return hit ? [`padrão ${d.n} toca "${hit[1]}"${at(d.line)} — credencial, permissão, pagamento e apagar dado viram pergunta, nunca padrão`] : [];
+  });
+}
+
+// Optional: absent is fine; present, every line is a transition the plan view can draw.
+function statesErrors(plan, at) {
+  if (!plan.present.states) return [];
+  const { transitions, invalid } = plan.states;
+  const errors = invalid.map((l) => `## ${SECTIONS.states}: "${l.raw}" não é transição — use "- origem → destino: gatilho"${at(l.line)}`);
+  if (transitions.length === 0 && invalid.length === 0) errors.push(`## ${SECTIONS.states} vazia — liste as transições ou apague a seção`);
+  return errors;
+}
 
-export function validatePlan(plan, { personas = null, surfaces = null, workType = null, riskRules = true } = {}) {
+function defaultsErrors(plan, { workType, riskRules }, at) {
+  const { items, none } = plan.defaults;
+  if (!plan.present.defaults) {
+    return riskRules && !POLICY_PLAN_WORK_TYPES.includes(workType)
+      ? [`seção obrigatória ausente: ## ${SECTIONS.defaults} — numere o que você decidiu sem perguntar, ou escreva "nenhum"`]
+      : [];
+  }
+  if (items.length === 0) {
+    return none ? [] : [`## ${SECTIONS.defaults} sem item numerado ("1. …") nem "nenhum"`];
+  }
+  return items.some((d, i) => d.n !== i + 1)
+    ? [`## ${SECTIONS.defaults} numerada fora de 1..${items.length} — o usuário veta pelo número`]
+    : [];
+}
+
+export function validatePlan(plan, { workType = null, riskRules = true, text = null } = {}) {
   const errors = [];
   const warnings = [];
+  const media = riskRules ? mediaCitationError(text) : null;
+  if (media) errors.push(media);
   const at = (line) => (line ? ` (linha ${line})` : '');
 
-  for (const key of ['problem', 'scenarios', 'decisions', 'slices']) {
+  for (const key of ['problem', 'scenarios', 'decisions']) {
     if (!plan.present[key]) errors.push(`seção obrigatória ausente: ## ${SECTIONS[key]}`);
   }
   if (plan.present.decisions && !plan.conflicts) {
@@ -114,7 +83,7 @@ export function validatePlan(plan, { personas = null, surfaces = null, workType
   }
 
   const duplicated = (items) => items.map((i) => i.id).filter((id, i, all) => all.indexOf(id) !== i);
-  for (const [label, items] of [['cenário', plan.scenarios], ['fatia', plan.slices], ['ADR', plan.adrs]]) {
+  for (const [label, items] of [['cenário', plan.scenarios], ['ADR', plan.adrs]]) {
     for (const id of new Set(duplicated(items))) errors.push(`${label} duplicado: ${id}`);
   }
 
@@ -136,6 +105,9 @@ export function validatePlan(plan, { personas = null, surfaces = null, workType
     } else if (risk && proof === 'leitura') {
       warnings.push(`${c.id}: risco "${risk}" provado só por leitura${at(c.line)}`);
     }
+    if (canonicalRung(c.rung) === false) {
+      errors.push(`${c.id}: degrau "${c.rung}" fora de ${REWORK_RUNGS.join(' | ')}${at(c.line)}`);
+    }
     const terms = findArtifactTerms(c.text);
     if (terms.length > 0 && !c.artifactWhy) {
       errors.push(`${c.id} descreve artefato ("${terms.join(', ')}") sem "> Por que artefato:" — reescreva como efeito observável ou justifique${at(c.line)}`);
@@ -147,37 +119,20 @@ export function validatePlan(plan, { personas = null, surfaces = null, workType
     errors.push(`${workType} sem cenário de regressão — o sintoma do bug real vira um Cn com "prova: teste" e "risco: regressão"`);
   }
 
-  const scenarioIds = new Set(plan.scenarios.map((c) => c.id));
-  const sliceIds = new Set(plan.slices.map((s) => s.id));
-  const covered = new Set();
-  for (const s of plan.slices) {
-    if (!s.persona) {
-      errors.push(`${s.id} sem "- persona:"${at(s.line)}`);
-    } else if (personas && !personas.includes(s.persona)) {
-      errors.push(`${s.id}: persona "${s.persona}" não existe em agents.json (${personas.join(', ')})${at(s.line)}`);
-    }
-    if (s.files.length > MAX_SLICE_FILES) {
-      errors.push(`${s.id} toca ${s.files.length} arquivos — o teto é ${MAX_SLICE_FILES}; divida a fatia${at(s.line)}`);
-    }
-    for (const c of s.covers) {
-      if (scenarioIds.has(c)) covered.add(c);
-      else errors.push(`${s.id} cobre ${c}, que não existe em ## ${SECTIONS.scenarios}${at(s.line)}`);
-    }
-    for (const d of s.depends) {
-      if (!sliceIds.has(d)) errors.push(`${s.id} depende de ${d}, que não existe${at(s.line)}`);
-    }
-    if (s.covers.length === 0) warnings.push(`${s.id} não cobre nenhum cenário${at(s.line)}`);
-    if (s.unknownKeys.length > 0) warnings.push(`${s.id}: chave desconhecida ${s.unknownKeys.join(', ')}${at(s.line)}`);
-    if (s.surface && surfaces && !surfaces.includes(s.surface)) {
-      warnings.push(`${s.id}: superfície "${s.surface}" não é uma de ${surfaces.join(', ')}${at(s.line)}`);
-    }
+  errors.push(...defaultsErrors(plan, { workType, riskRules }, at));
+  errors.push(...statesErrors(plan, at));
+  warnings.push(...defaultsWarnings(plan, at));
+
+  const isSlices = (s) => /^fatias$/i.test(s.name.trim());
+  if (plan.sections.some((s) => !s.key && isSlices(s))) {
+    warnings.push('## Fatias não é lida desde a 10.0: o plano inteiro se implementa numa sessão, e os cenários definem o pronto');
   }
-  for (const c of plan.scenarios) {
-    if (!covered.has(c.id)) errors.push(`${c.id} não é coberto por nenhuma fatia ("- cobre: ${c.id}")`);
+  const known = new Set(Object.values(SECTIONS).map(foldRisk));
+  for (const s of plan.sections.filter((section) => !section.key && !isSlices(section))) {
+    warnings.push(known.has(foldRisk(s.name))
+      ? `## ${s.name} repetida${at(s.line)} — só a primeira é lida, o conteúdo desta se perde`
+      : `## ${s.name} não é seção do plano${at(s.line)} — o plan-check não a lê`);
   }
-  const cycle = dependencyCycle(plan.slices);
-  if (cycle) errors.push(`ciclo em "depende": ${cycle.join(' → ')}`);
-  if (plan.slices.length > MAX_SLICES) warnings.push(`${plan.slices.length} fatias — acima de ${MAX_SLICES}, considere dividir a feature`);
 
   for (const r of plan.reuse) {
     if (!REUSE_VERDICTS.includes(r.verdict)) {
@@ -200,10 +155,7 @@ export function buildChecks(feature, text, plan) {
     planHash: planHash(text),
     checks: plan.scenarios.map((c) => ({
       id: c.id, text: c.text, proof: c.proof ? c.proof.toLowerCase() : null, artifactWhy: c.artifactWhy || null,
-    })),
-    slices: plan.slices.map((s) => ({
-      id: s.id, title: s.title, persona: s.persona, surface: s.surface,
-      standards: s.standards, files: s.files, depends: s.depends, covers: s.covers,
+      rung: canonicalRung(c.rung) || null,
     })),
     reuse: plan.reuse.map(({ concept, verdict, target, why }) => ({ concept, verdict, target, why })),
     adrs: plan.adrs.map((a) => ({ id: a.id, title: a.title, scope: ADR_SCOPES.includes(a.scope) ? a.scope : null })),
@@ -222,7 +174,7 @@ export function readPlanChecks(cwd, featureName) {
   } catch {
     return { status: 'unreadable', checks: null };
   }
-  if (checks?.version !== CHECKS_VERSION || !Array.isArray(checks.slices) || !Array.isArray(checks.checks)) {
+  if (checks?.version !== CHECKS_VERSION || !Array.isArray(checks.checks)) {
     return { status: 'unreadable', checks: null };
   }
   let plan;

package/src/lib/plan/critique.js

@@ -0,0 +1,28 @@
+import { existsSync, readFileSync } from 'fs';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+
+export const CRITIQUE_EXEMPT_WORK_TYPES = ['chore', 'hotfix'];
+
+const PLAN_HASH_RE = /^\*\*Plan-Hash:\*\*\s*`?([0-9a-f]{64})`?\s*$/m;
+const APPLIED_RE = /^\*\*Aplicado-em:\*\*\s*`?([0-9a-f]{64})`?\s*$/gm;
+
+// A critique counts for the plan it read or for the plan the session wrote after applying it:
+// otherwise every fix it asks for would demand a new critique.
+export function critiqueStatus(text, currentHash) {
+  if (typeof text !== 'string') return 'missing';
+  const read = PLAN_HASH_RE.exec(text)?.[1];
+  if (!read) return 'no-hash';
+  const applied = [...text.matchAll(APPLIED_RE)].map((m) => m[1]);
+  const valid = applied.length ? applied[applied.length - 1] : read;
+  return currentHash === read || currentHash === valid ? 'fresh' : 'stale';
+}
+
+export function readPlanCritique(cwd, featureName, { workType, planChecks }) {
+  if (CRITIQUE_EXEMPT_WORK_TYPES.includes(workType)) return 'exempt';
+  const currentHash = planChecks?.status === 'fresh' ? planChecks.checks?.planHash : null;
+  if (!currentHash) return null;
+  const path = getAbsoluteOutputPath(cwd, featureName, 'planCritique');
+  let text = null;
+  try { text = existsSync(path) ? readFileSync(path, 'utf8') : null; } catch { text = null; }
+  return critiqueStatus(text, currentHash);
+}

package/src/lib/plan/media.js

@@ -0,0 +1,42 @@
+export const MEDIA_STANDARD_IDS = [
+  'ai-agents-modalities-image-gen',
+  'ai-agents-media-video',
+  'ai-agents-media-pipeline',
+];
+
+// O plano escreve o standard pelo id ou pelo caminho (com ou sem `framework/`/`standards/`).
+export function standardIdOf(value) {
+  return String(value ?? '').trim().replace(/\\/g, '/')
+    .replace(/^(\.morph\/)?(framework\/)?(standards\/)?/, '')
+    .replace(/\.md$/, '')
+    .replace(/\//g, '-');
+}
+
+export function featureGeneratesMedia(planText) {
+  if (typeof planText !== 'string') return false;
+  const tokens = new Set(planText.split(/[\s`'",;:()[\]|]+/).map((t) => standardIdOf(t.replace(/[.!?]+$/, ''))));
+  return MEDIA_STANDARD_IDS.some((id) => tokens.has(id));
+}
+
+const fold = (s) => s.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
+
+// Vocabulário estreito de propósito: "imagem" sozinha (upload, avatar) não é mídia gerada.
+const GENERATED_MEDIA_RE = new RegExp([
+  String.raw`\b(gera[rd]?[ao]?s?|geracao|generat\w*)\b[^.\n]{0,40}\b(imagem|imagens|images?|videos?|ilustrac\w*|thumbnails?)\b`,
+  String.raw`\b(imagem|imagens|videos?|ilustrac\w*|thumbnails?)\b[^.\n]{0,20}\bgerad[ao]s?\b`,
+  String.raw`\b(text|texto)[- ]?(to|para)[- ]?(image|imagem|video)\b`,
+  String.raw`\b(img2vid|image-gen|gpt-image|dall-?e|seedance|midjourney|stable diffusion|nano banana|sora|veo ?\d)\b`,
+].join('|'));
+
+const NO_MEDIA_RE = /^\s*[-*]?\s*\**midia gerada:?\**:?\s*nao\b/m;
+
+/** Plano que fala em gerar imagem ou vídeo e não cita o standard deixaria o guardrail desarmado em silêncio. */
+export function mediaCitationError(planText) {
+  if (typeof planText !== 'string' || featureGeneratesMedia(planText)) return null;
+  const text = fold(planText);
+  if (NO_MEDIA_RE.test(text)) return null;
+  const hit = GENERATED_MEDIA_RE.exec(text);
+  if (!hit) return null;
+  return `o plano fala em mídia gerada ("${hit[0].trim()}") sem citar o standard: cite ${MEDIA_STANDARD_IDS.map((id) => `\`${id}\``).join(', ')} `
+    + 'conforme o caso (é o que arma as provas de mídia do Gate 3), ou escreva a linha "Mídia gerada: não" se nada é gerado por IA';
+}

package/src/lib/plan/plan-html.js

@@ -0,0 +1,125 @@
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+const NODE_W = 132;
+const NODE_H = 40;
+const GAP = 84;
+const LANE = 38;
+
+/** States in the order a reader meets them: breadth-first from the first transition's origin. */
+export function stateOrder(transitions) {
+  const order = [];
+  const seen = new Set();
+  const queue = transitions.length ? [transitions[0].from] : [];
+  const visit = (s) => { if (!seen.has(s)) { seen.add(s); queue.push(s); } };
+  if (queue.length) seen.add(queue[0]);
+  while (queue.length) {
+    const s = queue.shift();
+    order.push(s);
+    for (const t of transitions) if (t.from === s) visit(t.to);
+  }
+  for (const t of transitions) for (const s of [t.from, t.to]) if (!seen.has(s)) { seen.add(s); order.push(s); }
+  return order;
+}
+
+// One row of states; a forward transition arcs above, a backward one below, each in its own lane so
+// labels never stack; a self-transition loops over its node.
+export function stateMachineSvg(transitions) {
+  if (!transitions.length) return '';
+  const order = stateOrder(transitions);
+  const x = (s) => 24 + order.indexOf(s) * (NODE_W + GAP);
+  const span = (t) => Math.abs(order.indexOf(t.to) - order.indexOf(t.from));
+  const forward = transitions.filter((t) => order.indexOf(t.to) > order.indexOf(t.from)).sort((a, b) => span(a) - span(b));
+  const backward = transitions.filter((t) => order.indexOf(t.to) < order.indexOf(t.from)).sort((a, b) => span(a) - span(b));
+  const loops = transitions.filter((t) => t.to === t.from);
+  const top = 24 + (forward.length + (loops.length ? 1 : 0)) * LANE;
+  const height = top + NODE_H + 24 + backward.length * LANE;
+  const width = 48 + order.length * NODE_W + (order.length - 1) * GAP;
+  const mid = (s) => x(s) + NODE_W / 2;
+
+  const edge = (t, i, above) => {
+    const x1 = mid(t.from) + (above ? 18 : -18);
+    const x2 = mid(t.to) + (above ? -18 : 18);
+    const y0 = above ? top : top + NODE_H;
+    const y = above ? top - (i + 1) * LANE : top + NODE_H + (i + 1) * LANE;
+    const lx = (x1 + x2) / 2;
+    return `<path class="edge" d="M${x1} ${y0} C${x1} ${y} ${x2} ${y} ${x2} ${y0}" marker-end="url(#arrow)"/>`
+      + `<text class="edge-label" x="${lx}" y="${y + (above ? 0 : 14)}" text-anchor="middle"><title>${esc(t.trigger)}</title>${esc(t.trigger)}</text>`;
+  };
+  const loop = (t) => {
+    const cx = mid(t.from);
+    return `<path class="edge" d="M${cx - 14} ${top} C${cx - 30} ${top - LANE} ${cx + 30} ${top - LANE} ${cx + 14} ${top}" marker-end="url(#arrow)"/>`
+      + `<text class="edge-label" x="${cx}" y="${top - LANE + 4}" text-anchor="middle">${esc(t.trigger)}</text>`;
+  };
+
+  return `<svg class="machine" viewBox="0 0 ${width} ${height}" style="width:100%;min-width:${Math.round(width * 0.6)}px" role="img" aria-label="Máquina de estados: ${esc(order.join(', '))}">
+<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0 0L10 5L0 10z" class="arrow-head"/></marker></defs>
+${forward.map((t, i) => edge(t, i, true)).join('\n')}
+${backward.map((t, i) => edge(t, i, false)).join('\n')}
+${loops.map(loop).join('\n')}
+${order.map((s) => `<g class="state"><rect x="${x(s)}" y="${top}" width="${NODE_W}" height="${NODE_H}" rx="10"/><text x="${mid(s)}" y="${top + NODE_H / 2 + 5}" text-anchor="middle">${esc(s)}</text></g>`).join('\n')}
+</svg>`;
+}
+
+const RUNG_TONE = { 'migrar': 'warn', 'irreversível': 'bad', 'irreversivel': 'bad' };
+
+function scenarioCard(c) {
+  const chips = [
+    c.proof && `<span class="chip">prova: ${esc(c.proof)}</span>`,
+    c.risk && `<span class="chip">risco: ${esc(c.risk)}</span>`,
+    c.rung && `<span class="chip ${RUNG_TONE[c.rung.toLowerCase()] ?? ''}">degrau: ${esc(c.rung)}</span>`,
+  ].filter(Boolean).join('');
+  return `<li class="card"><div class="cid">${esc(c.id)}</div><div><p>${esc(c.text)}</p>${chips ? `<div class="chips">${chips}</div>` : ''}</div></li>`;
+}
+
+export function renderPlanHtml(feature, plan, { planHash = null } = {}) {
+  const defaults = plan.defaults?.items ?? [];
+  const transitions = plan.states?.transitions ?? [];
+  const section = (title, body) => `<section><h2>${esc(title)}</h2>${body}</section>`;
+  return `<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Plano — ${esc(feature)}</title>
+<style>
+:root { --bg:#f6f7f9; --card:#fff; --fg:#14171c; --dim:#4b5260; --faint:#7a8291; --hair:#dfe3ea; --ok:#2f7d4f; --warn:#a35f00; --bad:#b4232f; --accent:#2d5bd7; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0f1115; --card:#171a21; --fg:#e8ebf0; --dim:#b3bac6; --faint:#7f8796; --hair:#2a2f3a; --ok:#5cc28a; --warn:#e2a54b; --bad:#f07178; --accent:#8fb0ff; } }
+* { box-sizing:border-box; }
+body { margin:0; background:var(--bg); color:var(--fg); font:15px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif; }
+main { max-width:920px; margin:0 auto; padding:40px 16px 64px; }
+h1 { font-size:28px; margin:0 0 4px; letter-spacing:-.01em; }
+.meta { color:var(--faint); font-size:13px; margin:0 0 32px; }
+h2 { font-size:15px; margin:32px 0 12px; }
+ul.cards { list-style:none; padding:0; margin:0; display:grid; gap:10px; }
+.card { display:grid; grid-template-columns:3rem minmax(0,1fr); gap:12px; background:var(--card); border:1px solid var(--hair); border-radius:12px; padding:14px 16px; }
+.card p { margin:0; }
+.cid { font:600 13px/1.6 ui-monospace, monospace; color:var(--accent); }
+.chips { display:flex; flex-wrap:wrap; gap:6px; margin-top:8px; }
+.chip { font-size:12px; color:var(--dim); border:1px solid var(--hair); border-radius:999px; padding:1px 9px; }
+.chip.warn { color:var(--warn); border-color:currentColor; }
+.chip.bad { color:var(--bad); border-color:currentColor; }
+ol.defaults { margin:0; padding-left:22px; color:var(--dim); }
+ol.defaults li { margin:4px 0; }
+.scroll { overflow-x:auto; background:var(--card); border:1px solid var(--hair); border-radius:12px; padding:12px; }
+.machine .state rect { fill:var(--bg); stroke:var(--accent); stroke-width:1.5; }
+.machine .state text { fill:var(--fg); font:600 13px system-ui, sans-serif; }
+.machine .edge { fill:none; stroke:var(--faint); stroke-width:1.5; }
+.machine .arrow-head { fill:var(--faint); }
+.machine .edge-label { fill:var(--dim); font:12px system-ui, sans-serif; paint-order:stroke; stroke:var(--card); stroke-width:4px; }
+.none { color:var(--faint); }
+</style>
+</head>
+<body>
+<main>
+<h1>${esc(feature)}</h1>
+<p class="meta">Visão do plano, só leitura — gerada pelo <code>morph-spec plan-check</code> a partir de 2-plan/plan.md${planHash ? ` (${esc(planHash.slice(0, 12))})` : ''}. Para mudar, edite o plan.md.</p>
+${section(`Cenários (${plan.scenarios.length})`, `<ul class="cards">${plan.scenarios.map(scenarioCard).join('')}</ul>`)}
+${transitions.length ? section('Estados', `<div class="scroll">${stateMachineSvg(transitions)}</div>`) : ''}
+${section('Padrões assumidos', defaults.length
+    ? `<ol class="defaults">${defaults.map((d) => `<li value="${d.n}">${esc(d.text)}</li>`).join('')}</ol><p class="meta">Para vetar um, responda "veta N" no gate.</p>`
+    : '<p class="none">Nenhum.</p>')}
+</main>
+</body>
+</html>
+`;
+}