@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/state/retype.js

@@ -1,31 +1,12 @@
 import chalk from 'chalk';
-import { mkdirSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from 'fs';
 import { join } from 'path';
 import { getFeature, setApprovalGate, updateFeature } from '../../core/state/state-manager.js';
 import { WORK_TYPES, isValidWorkType, POLICY_APPROVER_PREFIX } from '../../core/work-types.js';
+import { renderPlanSkeleton } from '../../lib/plan/plan-template.js';
 
-/**
- * `morph-spec retype <feature> <newType>` — mid-flight work-type change with
- * asymmetric gate rules that preserve GENUINE human/auto approvals and only
- * ever undo policy stamps:
- *
- *  - Blocked outright once Gate 3 (review) is approved — the feature already
- *    shipped its pipeline, retyping it retroactively would be revisionist.
- *  - Downgrade (fewer skipped gates → more skipped gates, e.g. feature/bug
- *    → chore/hotfix) is blocked once Gate 2 (plan) carries a genuine
- *    (non-policy) approval — the plan was already accepted under the old
- *    type's scrutiny; retyping around it would erase that judgment call.
- *  - Upgrade (more skipped gates → fewer, e.g. chore/hotfix → feature/bug)
- *    is always allowed before review: it only ever ADDS scrutiny.
- *
- * Applying a retype resets exactly the gates that were stamped
- * `policy:{oldType}` and the NEW type no longer skips (so the human is asked
- * again), stamps `policy:{newType}` on any of the new type's skippedGates
- * that aren't already approved (a prior genuine approval is left standing —
- * that's the "preserves human approvals" half of the contract), scaffolds
- * any phase folders the new type needs that don't exist yet, and appends an
- * audit entry to `workTypeHistory`.
- */
+// Retype only ever undoes `policy:` stamps: blocked once review is approved; a downgrade
+// is blocked once the plan carries a genuine approval; an upgrade only adds scrutiny.
 export async function retypeCommand(featureName, newType, options = {}) {
   try {
     if (!isValidWorkType(newType)) {
@@ -61,15 +42,14 @@ export async function retypeCommand(featureName, newType, options = {}) {
       const genuinelyApproved = planGate?.approved === true
         && !String(planGate.approvedBy || '').startsWith(POLICY_APPROVER_PREFIX);
       if (genuinelyApproved) {
-        console.error(chalk.red(`\n❌ Gate 2 (plan) já aprovado por "${planGate.approvedBy}"; downgrade bloqueado — o plano já foi aceito\n`));
+        console.error(chalk.red(`\n❌ Gate do plano já aprovado por "${planGate.approvedBy}"; downgrade bloqueado — o plano já foi aceito\n`));
         process.exit(1);
       }
     }
 
     const now = new Date().toISOString();
 
-    // Reset gates that were stamped policy:{oldType} and the new type no
-    // longer skips — a genuine (non-policy) approval is never touched.
+    // A genuine (non-policy) approval is never reset.
     const resetGates = [];
     for (const [gate, data] of Object.entries(feature.approvalGates || {})) {
       const isPolicyStamped = String(data?.approvedBy || '').startsWith(POLICY_APPROVER_PREFIX);
@@ -79,8 +59,7 @@ export async function retypeCommand(featureName, newType, options = {}) {
       }
     }
 
-    // Stamp the new type's skipped gates — but only the ones not already
-    // approved (preserves a prior genuine approval untouched).
+    // A gate already approved keeps its genuine approval.
     const stampedGates = [];
     for (const gate of newWorkType.skippedGates) {
       if (!feature.approvalGates?.[gate]?.approved) {
@@ -93,6 +72,11 @@ export async function retypeCommand(featureName, newType, options = {}) {
     }
 
     const featureDir = join(process.cwd(), '.morph', 'features', featureName);
+    const planPath = join(featureDir, '2-plan', 'plan.md');
+    if (stampedGates.includes('plan') && existsSync(planPath)
+        && readFileSync(planPath, 'utf8') === renderPlanSkeleton(featureName)) {
+      unlinkSync(planPath);
+    }
     for (const folder of newWorkType.scaffold) {
       mkdirSync(join(featureDir, folder), { recursive: true });
     }

package/src/commands/validation/index.js

@@ -1,5 +1,2 @@
-/**
- * Validation Commands
- */
 export { validateFeatureCommand } from './validate-feature.js';
 export { verifyCommand } from './verify.js';

package/src/commands/validation/mutate.js

@@ -1,9 +1,9 @@
 import chalk from 'chalk';
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
-import { resolveTestBuildTargets } from '../../lib/tasks/test-runner.js';
-import { dotnetTestMode } from '../../lib/tasks/dotnet-test-introspection.js';
+import { discoverDotnetBuildTargets } from '../../lib/tasks/test-runner.js';
+import { dotnetTestMode } from '../../lib/mutation/dotnet-introspection.js';
 import { dotnetBuildCommands } from '../../lib/mutation/commands.js';
 import { resolveTestNodes } from '../../lib/tasks/test-nodes.js';
 import { changedPathsAgainst, detectDefaultBranch, getHeadSha } from '../../lib/git/default-branch.js';
@@ -12,7 +12,8 @@ import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js
 import { resolveGitCommonDir } from '../../../framework/hooks/shared/git-paths.js';
 import { BACKSLASH_TOKEN, ManifestError } from '../../lib/mutation/manifest.js';
 import { groupByNode, loadPlan } from '../../lib/mutation/plan.js';
-import { dotnetSubset, jsSubset, testProjectDirsOf } from '../../lib/mutation/subset.js';
+import { dotnetSubset, jsSubset, mutatedTypesOf, testFilesCiting, testProjectDirsOf } from '../../lib/mutation/subset.js';
+import { isFinished } from '../../dashboard/scanner/feature-status.js';
 import { dotnetAdapter, genericAdapter, spawnExec } from '../../lib/mutation/adapters.js';
 import { runMutation } from '../../lib/mutation/runner.js';
 import { renderSection, summarize } from '../../lib/mutation/report.js';
@@ -22,11 +23,8 @@ const EXIT = { ok: 0, failed: 1, usage: 2, busy: 3, unsafe: 4 };
 const KEEP_RUNS = 2;
 const DEFAULT_JOBS = 2;
 
-/**
- * One heavy slot per worker: the first waits like any heavy node, the others
- * are taken only if free right now. The run uses as many workers as it got,
- * so a busy machine degrades to sequential instead of queueing.
- */
+// One heavy slot per worker: the first waits, the others are taken only if free now,
+// so a busy machine degrades to sequential instead of queueing.
 export function workerGate({ root, feature, jobs }) {
   const config = readHeavyConfig(root);
   const gates = [createHeavyGate({ projectPath: root, label: 'mutate', feature, config })];
@@ -97,23 +95,72 @@ export function restoreLatest(root, out = console) {
   return restored;
 }
 
+function testDirsOf(node, root, { projectsOnly = false } = {}) {
+  const cwd = resolve(root, node.cwd || '.');
+  const targets = discoverDotnetBuildTargets(node, cwd);
+  return testProjectDirsOf(root, projectsOnly ? targets.filter((t) => !/\.slnx?$/i.test(t)) : targets, cwd);
+}
+
 function subsetFor({ node, group, root, options }) {
   if (options.subset === false) return { usable: false, reason: '--no-subset' };
   const mutatedFiles = group.regions.map((r) => r.file);
   if (node.runner === 'dotnet') {
     const base = detectDefaultBranch(root);
     const changed = base ? changedPathsAgainst(base, root) : [];
-    return dotnetSubset({ root, testProjectDirs: testProjectDirsOf(root, resolveTestBuildTargets(node)), mutatedFiles, changed });
+    return dotnetSubset({ root, testProjectDirs: testDirsOf(node, root), mutatedFiles, changed });
   }
   return jsSubset({ runner: node.runner, command: node.command, root, mutatedFiles });
 }
 
-export async function mutateCommand(feature, options = {}) {
+function e2eManualProtocol(feature, node) {
+  const f = feature ?? '<feature>';
+  const round = `eval "$(morph-spec env ${f})" && morph-spec e2e up ${f} && morph-spec heavy run -- ${node.command}`;
+  return 'mutate só recompila localmente, e a suíte que alcança esse código testa o container do compose: o mutante sairia sobrevivente em falso. ' +
+    `Prove à mão pelo nó "${node.id}", cada passo numa linha só e encadeado por \`&&\` (nunca \`;\`: um passo que falha não pode deixar a suíte rodar sobre o código original; ` +
+    'e o env da feature se perde entre chamadas de Bash): ' +
+    `(1) base verde antes do 1º mutante: \`${round}\`; ` +
+    `(2) por mutante: edite a linha && \`${round}\`; ` +
+    `(3) restaure, confirme com \`git diff --quiet -- <arquivo>\` e suba a stack de novo (\`eval "$(morph-spec env ${f})" && morph-spec e2e up ${f}\`). ` +
+    'Registre cada mutante em 4-review (expect, resultado, teste que o matou).';
+}
+
+// A .cs file belongs to every dotnet suite, by runner, not by project reference: a unit suite
+// "owns" code only an e2e suite executes. With an e2e node declared, a unit suite with no test
+// naming a type of the mutated file is not evidence, so the run is refused.
+function uncitedUnderE2e({ root, groups, nodes }) {
+  const e2e = nodes.filter((n) => n.e2e);
+  if (e2e.length === 0) return [];
+  const e2eDirs = new Set(e2e.filter((n) => n.runner === 'dotnet').flatMap((n) => testDirsOf(n, root)));
+  const uncited = [];
+  for (const { node, regions } of groups.filter((g) => g.node.runner === 'dotnet')) {
+    const direct = new Set(testDirsOf(node, root, { projectsOnly: true }));
+    const dirs = testDirsOf(node, root).filter((d) => direct.has(d) || !e2eDirs.has(d));
+    for (const region of regions) {
+      const types = mutatedTypesOf(root, [region.file]);
+      if (testFilesCiting({ root, testProjectDirs: dirs, types, exclude: [region.file] }).length === 0) uncited.push({ region, node, types, e2e });
+    }
+  }
+  return uncited;
+}
+
+function soleActiveFeature(root) {
+  const dir = join(root, '.morph', 'features');
+  let names;
+  try { names = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); } catch { return null; }
+  const active = names.filter((name) => {
+    try { return !isFinished(JSON.parse(readFileSync(join(dir, name, 'feature.json'), 'utf8'))); } catch { return false; }
+  });
+  return active.length === 1 ? active[0] : null;
+}
+
+export async function mutateCommand(featureArg, options = {}) {
   const root = resolve(options.cwd ?? process.cwd());
   if (options.restore) { restoreLatest(root); return null; }
 
-  const planPath = resolve(root, options.plan ?? join('.morph', 'features', feature ?? '', '4-review', 'mutants.json'));
-  if (!existsSync(planPath)) return fail(`manifesto não encontrado: ${planPath}\nEscreva-o com a ferramenta Write, se você a tem; só com Bash, heredoc de delimitador entre aspas simples, com a barra invertida do código como ${BACKSLASH_TOKEN} — formato em .morph/framework/CLI.md, seção mutate.`, EXIT.usage);
+  const feature = featureArg ?? soleActiveFeature(root);
+  if (!feature && !options.plan) return fail('sem feature: passe <feature> (nenhuma, ou mais de uma, em andamento) ou o manifesto por --plan.', EXIT.usage);
+  const planPath = resolve(root, options.plan ?? join('.morph', 'features', feature, '4-review', 'mutants.json'));
+  if (!existsSync(planPath)) return fail(`manifesto não encontrado: ${planPath}\nEscreva-o com a ferramenta Write, se você a tem; só com Bash, heredoc de delimitador entre aspas simples, com a barra invertida do código como ${BACKSLASH_TOKEN} — formato em .morph/framework/CLI.md, seção "### mutate".`, EXIT.usage);
 
   let regions;
   try {
@@ -125,16 +172,26 @@ export async function mutateCommand(feature, options = {}) {
   }
 
   const { nodes } = resolveTestNodes(root);
-  const { groups, orphans } = groupByNode(regions, nodes, root);
+  const { groups, orphans, stackOnly } = groupByNode(regions, nodes, root);
   if (orphans.length > 0) {
     return fail(`nenhuma suíte declarada roda: ${orphans.map((o) => `${o.id} (${o.file})`).join(', ')}\nDeclare o nó em project.tests[] (.morph/config/config.json).`, EXIT.usage);
   }
+  if (stackOnly.length > 0) {
+    const named = stackOnly.map(({ region, node }) => `${region.id} (${region.file}) → nó "${node.id}"`).join(', ');
+    return fail(`só uma suíte e2e: true cobre: ${named}\nProve a guarda por um teste de unidade, ou: ${e2eManualProtocol(feature, stackOnly[0].node)}`, EXIT.usage);
+  }
   const mtp = groups.find((g) => g.node.runner === 'dotnet' && dotnetTestMode(resolve(root, g.node.cwd || '.')) === 'mtp');
   if (mtp) return fail(`a suíte "${mtp.node.id}" roda no Microsoft.Testing.Platform (global.json): o TRX do VSTest, de onde o veredito e o motivo saem, não existe nela. Suporte a MTP ainda não há — rode a mutação com a suíte inteira à mão.`, EXIT.usage);
   const uncompilable = groups.find((g) => g.node.runner === 'dotnet' && dotnetBuildCommands(g.node, root).length === 0);
-  if (uncompilable) return fail(`a suíte "${uncompilable.node.id}" não aponta nenhum .csproj (solution, ou nada): sem saber o que compilar, todo mutante rodaria sobre o binário antigo e sairia "sobrevivente". Declare o campo build no nó (config.json, project.tests[]).`, EXIT.usage);
+  if (uncompilable) return fail(`a suíte "${uncompilable.node.id}" não deixa descobrir o que compilar: o comando não nomeia .sln/.slnx/.csproj e o diretório alvo não tem uma única solution (ou um único projeto). Sem isso, todo mutante rodaria sobre o binário antigo e sairia "sobrevivente". Nomeie a solution no comando ou declare o campo build no nó (config.json, project.tests[]).`, EXIT.usage);
   const preDecided = groups.find((g) => g.node.status);
   if (preDecided) return fail(`a suíte "${preDecided.node.id}" já vem decidida como ${preDecided.node.status}: ${preDecided.node.reason ?? ''}`, EXIT.usage);
+  const uncited = uncitedUnderE2e({ root, groups, nodes });
+  if (uncited.length > 0) {
+    const named = uncited.map(({ region, node, types }) => `${region.id} (${region.file}; tipos: ${types.join(', ') || 'nenhum legível'}) → nenhum teste da suíte "${node.id}" os cita`).join('\n');
+    const e2eIds = uncited[0].e2e.map((n) => `"${n.id}"`).join(', ');
+    return fail(`${named}\nNó e2e: true declarado: ${e2eIds}. ${e2eManualProtocol(feature, uncited[0].e2e[0])}`, EXIT.usage);
+  }
 
   if (!options.allowDirty) {
     const dirty = gitOut(root, ['status', '--porcelain', '--', ...new Set(regions.map((r) => r.file))]).trim();
@@ -184,15 +241,18 @@ export async function mutateCommand(feature, options = {}) {
   const order = new Map(regions.map((r, i) => [r.id, i]));
   merged.mutants.sort((a, b) => order.get(a.id) - order.get(b.id));
   const section = renderSection(merged, { head: git.head(), date: new Date().toISOString().slice(0, 10), subset: subsets[0] ?? null });
-  const outPath = resolve(root, options.out ?? join('.morph', 'features', feature ?? '_', '4-review', 'mutation-section.md'));
-  mkdirSync(join(outPath, '..'), { recursive: true });
-  writeFileSync(outPath, section);
+  const outRel = options.out ?? (feature ? join('.morph', 'features', feature, '4-review', 'mutation-section.md') : null);
+  const outPath = outRel ? resolve(root, outRel) : null;
+  if (outPath) {
+    mkdirSync(join(outPath, '..'), { recursive: true });
+    writeFileSync(outPath, section);
+  }
 
   const tally = summarize(merged);
   if (options.json) console.log(JSON.stringify({ ...merged, tally, section: outPath }, null, 2));
   else {
     console.log(section);
-    console.log(chalk.gray(`seção gravada em ${outPath}`));
+    console.log(chalk.gray(outPath ? `seção gravada em ${outPath}` : 'seção não gravada: sem feature nem --out'));
     console.log(`${chalk.green(`${tally.killed} mortos`)} · ${tally.survived ? chalk.yellow(`${tally.survived} sobreviveram`) : '0 sobreviveram'} · ${tally['build-error']} não compilaram · ${tally.inconclusive} inconclusivos`);
   }
   if (!merged.restore.ok || ['mismatch', 'unlocated'].includes(merged.binary.proof) || !merged.restore.treeClean) process.exitCode = EXIT.unsafe;

package/src/commands/validation/plan-check.js

@@ -0,0 +1,81 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { atomicWriteJson } from '../../core/state/state-manager.js';
+import { isGateApproved } from '../../../framework/hooks/shared/state-reader.js';
+import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
+import { parsePlan } from '../../lib/plan/plan-parser.js';
+import { buildChecks, knownPersonas, parallelGroups, planHash, validatePlan } from '../../lib/plan/checks.js';
+import { knownSurfaces } from '../../lib/specs/screen-checklist.js';
+import { revocationWarnings } from '../../lib/specs/adr-index.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
+import { seedDotnetBuildIgnores } from '../../lib/stack/dotnet-build-ignores.js';
+import { reportDotnetIgnores } from '../state/advance.js';
+
+function readJson(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return null; }
+}
+
+/** Parse and judge `2-plan/plan.md` of the project at `cwd`; with no error, write `2-plan/checks.json`. */
+export function runPlanCheck(featureName, cwd = process.cwd()) {
+  const planPath = getAbsoluteOutputPath(cwd, featureName, 'plan');
+  const checksPath = getAbsoluteOutputPath(cwd, featureName, 'checks');
+  const base = { feature: featureName, plan: planPath, checksPath };
+  if (!existsSync(planPath)) return { ...base, ok: false, exit: 2, error: 'plan-not-found', errors: [], warnings: [], groups: [] };
+
+  const text = readFileSync(planPath, 'utf8');
+  const plan = parsePlan(text);
+  const { errors, warnings } = validatePlan(plan, { personas: knownPersonas(cwd), surfaces: knownSurfaces(cwd) });
+  warnings.push(...revocationWarnings(cwd, plan));
+  const groups = errors.length === 0 ? parallelGroups(plan.slices) : [];
+  const hash = planHash(text);
+  const result = { ...base, planHash: hash, errors, warnings, groups, written: false };
+  if (errors.length > 0) return { ...result, ok: false, exit: 1 };
+
+  const approved = isGateApproved(featureName, 'plan', cwd);
+  const previous = existsSync(checksPath) ? readJson(checksPath) : null;
+  if (approved && previous && previous.planHash !== hash) {
+    return { ...result, ok: false, exit: 1, error: 'frozen', previousHash: previous.planHash ?? null };
+  }
+
+  atomicWriteJson(checksPath, buildChecks(featureName, text, plan));
+  return { ...result, ok: true, exit: 0, written: true };
+}
+
+export function planCheckCommand(featureName, options = {}) {
+  const owner = assertOwnerTree(featureName, process.cwd());
+  if (owner.blocked) {
+    for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec plan-check ${featureName}`)) {
+      console.error(chalk[tone](text));
+    }
+    process.exit(1);
+  }
+
+  const result = runPlanCheck(featureName);
+  const gitignoreAdded = result.written ? seedDotnetBuildIgnores(process.cwd(), { featureName }) : [];
+  if (options.json) {
+    if (gitignoreAdded.length) result.gitignoreAdded = gitignoreAdded;
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.exit);
+  }
+
+  if (result.error === 'plan-not-found') {
+    console.error(chalk.red(`plan-check: ${result.plan} não existe — o create escreve o esqueleto em 2-plan/plan.md (chore/hotfix: você o cria); gramática completa: morph-spec plan-check --help`));
+    process.exit(2);
+  }
+  for (const e of result.errors) console.log(chalk.red(`  ✗ ${e}`));
+  for (const w of result.warnings) console.log(chalk.yellow(`  ⚠ ${w}`));
+
+  if (result.error === 'frozen') {
+    console.log(chalk.red(`✗ plan-check: o gate plan de ${featureName} está aprovado e o plan.md mudou fora da errata — checks.json congelado.`));
+    console.log(chalk.gray('  Fato errado sobre o código: acrescente em ## Errata (não muda o planHash).'));
+    console.log(chalk.gray(`  Mudança real de escopo: morph-spec unapprove ${featureName} plan, rode plan-check e re-apresente o gate.`));
+  } else if (!result.ok) {
+    console.log(chalk.red(`✗ plan-check: ${result.errors.length} erro(s) em ${result.plan} — checks.json não foi gravado`));
+  } else {
+    console.log(chalk.green(`✓ plan-check: ${join('2-plan', 'checks.json')} gravado (${result.planHash.slice(0, 12)})`));
+    result.groups.forEach((g, i) => console.log(chalk.gray(`  onda ${i + 1}: ${g.join(', ')}${g.length > 1 ? ' (paralelo)' : ''}`)));
+    reportDotnetIgnores(gitignoreAdded);
+  }
+  process.exit(result.exit);
+}