@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/scaffold/scaffold.js

@@ -1,11 +1,3 @@
-/**
- * Scaffold Command - Generate feature files from templates.
- *
- * Sub-commands:
- * - scaffold dotnet <feature> <slice-name> — VSA feature slice (.NET)
- * - scaffold nextjs <feature> — Feature page + components (Next.js)
- */
-
 import chalk from 'chalk';
 import { relative } from 'path';
 import { logger } from '../../utils/logger.js';
@@ -17,11 +9,6 @@ import {
 
 const KEBAB_REGEX = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
-/**
- * Validate that a name is valid kebab-case.
- * @param {string} name
- * @param {string} label
- */
 function validateKebabCase(name, label) {
   if (!KEBAB_REGEX.test(name)) {
     logger.error(`Invalid ${label}: "${name}"`);
@@ -30,11 +17,6 @@ function validateKebabCase(name, label) {
   }
 }
 
-/**
- * Log the result of a scaffold operation.
- * @param {Array<{path: string, skipped: boolean}>} files
- * @param {string} outputDir
- */
 function logResult(files, outputDir) {
   let created = 0;
   let skipped = 0;
@@ -56,16 +38,12 @@ function logResult(files, outputDir) {
   logger.info(parts.join(', '));
 }
 
-/**
- * Scaffold .NET VSA feature slice.
- */
 export async function scaffoldDotnetCommand(feature, sliceName, options) {
   validateKebabCase(feature, 'feature name');
   validateKebabCase(sliceName, 'slice name');
 
   const outputDir = options.outputDir || process.cwd();
 
-  // Detect or use provided namespace
   const namespace = options.namespace || detectNamespace(outputDir);
   if (!namespace) {
     logger.error('Could not detect namespace');
@@ -100,9 +78,6 @@ export async function scaffoldDotnetCommand(feature, sliceName, options) {
   }
 }
 
-/**
- * Scaffold Next.js feature page with components and hooks.
- */
 export async function scaffoldNextjsCommand(feature, options) {
   validateKebabCase(feature, 'feature name');
 

package/src/commands/state/advance.js

@@ -1,54 +1,30 @@
 import chalk from 'chalk';
 import { existsSync, mkdirSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { join, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
 import { unmetPrereqs } from '../../core/state/gate-order.js';
 import { OUTPUT_SCHEMA } from '../../core/paths/output-schema.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 import { uiuxAutoApprovalBlock } from '../../lib/specs/screen-checklist.js';
+import { seedDesignArtifacts } from '../../lib/specs/design-seed.js';
+import { sliceProgress } from '../../../framework/hooks/shared/slice-progress.js';
+import { autoApprovalRefusal, printRefusal } from './auto-approval.js';
+import { seedDotnetBuildIgnores } from '../../lib/stack/dotnet-build-ignores.js';
 
 const FRAMEWORK_DIR = fileURLToPath(new URL('../../../framework/', import.meta.url));
 
-/**
- * `morph-spec advance <feature>` — approve the current phase's gate AND scaffold
- * the next phase's folder in one step. This is the sanctioned, one-command way
- * to move a feature forward: it removes the need to hand-edit state.json (gate)
- * AND the need to `mkdir` the next phase folder by hand. Once the gate is
- * approved, the enforce-phase-writes hook permits writing the next phase's first
- * canonical artifact (which then advances the derived phase).
- */
+// `implement` has no gate: advancing from it only scaffolds the review folder.
+const PHASE_GATE = { plan: 'plan', uiux: 'uiux', review: 'review' };
 
-// The gate approved when *completing* a given phase. `implement` has no gate
-// (it ends when all tasks are done), so advancing from implement just scaffolds
-// the review folder.
-const PHASE_GATE = { proposal: 'proposal', uiux: 'uiux', plan: 'plan', review: 'review' };
-
-// The next phase folder to scaffold when advancing FROM a given phase. The
-// default forward path skips the optional design phase (proposal → plan); pass
-// --design to take the uiux branch (proposal → 1-design).
 const NEXT_PHASE_DIR = {
-  proposal: '2-plan',
-  uiux: '2-plan',
   plan: '3-implement',
+  uiux: '3-implement',
   implement: '4-review',
 };
 
-/**
- * The canonical artifacts the phase being CLOSED owes, per
- * `framework/phases.json → phases[phase].requiredOutputs`, resolved to real
- * filenames through OUTPUT_SCHEMA.
- *
- * Data-driven on purpose: adding an artifact to a phase must not need a code
- * change here, and the list must never drift from the phase definition.
- * Fail-open — an unreadable phases.json/OUTPUT_SCHEMA yields an empty list, so
- * a broken install degrades to today's behaviour instead of blocking every
- * advance.
- *
- * @param {string} phase
- * @param {string} featurePath
- * @returns {string[]} relative paths of the MISSING required artifacts
- */
+// Data-driven from phases.json so the list never drifts from the phase definition. Fail-open:
+// an unreadable phases.json yields an empty list instead of blocking every advance.
 function missingPhaseArtifacts(phase, featurePath) {
   try {
     const phasesPath = join(FRAMEWORK_DIR, 'phases.json');
@@ -56,33 +32,27 @@ function missingPhaseArtifacts(phase, featurePath) {
     const required = phases[phase]?.requiredOutputs || [];
     const missing = [];
     for (const outputType of required) {
-      // requiredOutputs already carries OUTPUT_SCHEMA's camelCase keys — an
-      // unknown key is skipped rather than guessed at.
+      // An unknown key is skipped rather than guessed at.
       const entry = OUTPUT_SCHEMA[outputType];
       if (!entry?.filename || !entry?.phaseDir) continue;
       const rel = `${entry.phaseDir}/${entry.filename}`;
       if (!existsSync(join(featurePath, entry.phaseDir, entry.filename))) missing.push(rel);
     }
+    if (phase === 'implement') missing.push(...unfinishedSliceReports(featurePath));
     return missing;
   } catch {
     return [];
   }
 }
 
-/**
- * When a required artifact is absent HERE, check whether it exists in the
- * worktree that owns this feature. `feature.json` travels committed on
- * `morph/{feature}`, so a feature developed in a worktree has its artifacts
- * there and only a scaffold in the primary root — running `advance` from the
- * root then demanded a file that already exists, one directory over.
- *
- * Message-only: this never reads state for a decision and never writes across
- * trees. It replaces a misleading error with an accurate one.
- *
- * Fail-open — no git, no worktree, or any error yields null (today's message).
- *
- * @returns {Promise<{path: string, branch: string|null, present: string[]}|null>}
- */
+function unfinishedSliceReports(featurePath) {
+  const progress = sliceProgress(featurePath);
+  if (!progress) return ['2-plan/checks.json'];
+  return progress.slices.filter((s) => s.status !== 'feito').map((s) => `3-implement/reports/${s.id}.md`);
+}
+
+// Message-only and fail-open: names the worktree that holds the artifacts instead of demanding
+// a file that exists one directory over. Never writes across trees.
 async function artifactsLiveInWorktree(featureName, missing) {
   try {
     const { findWorktreeForFeature } = await import('../project/worktree.js');
@@ -97,7 +67,6 @@ async function artifactsLiveInWorktree(featureName, missing) {
   }
 }
 
-/** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
 function resolveApprovedBy(options) {
   if (options.approver) return options.approver;
   if (options.mode === 'auto') return 'auto';
@@ -105,6 +74,16 @@ function resolveApprovedBy(options) {
   return 'auto';
 }
 
+export function reportDotnetIgnores(added) {
+  if (added.length) console.log(chalk.gray(`   .gitignore: ${added.join(' ')} adicionados (projeto .NET) — commite antes do primeiro build.`));
+}
+
+function reportDesignSeed({ mockups, designSystem }) {
+  const rel = (p) => relative(process.cwd(), p).replace(/\\/g, '/');
+  if (mockups.written) console.log(chalk.gray(`   Escrito ${rel(mockups.path)} a partir do template (checklist de tela por \`## Tela:\`).`));
+  if (designSystem.written) console.log(chalk.gray(`   Escrito ${rel(designSystem.path)} a partir do template (o projeto não tinha design system).`));
+}
+
 export async function advanceCommand(featureName, options = {}) {
   try {
     const feature = getFeature(featureName);
@@ -113,9 +92,7 @@ export async function advanceCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    // Owner-tree guard: a live worktree elsewhere owns this feature's state —
-    // never stamp a gate onto the root's birth-instant skeleton (branch-drift
-    // created by this command, not merely left behind by one).
+    // A live worktree elsewhere owns the state: never stamp a gate onto the root skeleton.
     const owner = assertOwnerTree(featureName, process.cwd());
     if (owner.blocked) {
       for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec advance ${featureName}`)) {
@@ -127,6 +104,21 @@ export async function advanceCommand(featureName, options = {}) {
     const featurePath = join(process.cwd(), '.morph', 'features', featureName);
     const phase = derivePhase(featurePath);
 
+    // The plan gate is often closed by the human's answer to the gate question
+    // (state-sync), which already moves the derived phase to implement: taking
+    // the design branch then is opening 1-design/, not closing a phase.
+    if (options.design && phase === 'implement' && feature.approvalGates?.plan?.approved === true) {
+      mkdirSync(join(featurePath, '1-design'), { recursive: true });
+      reportDesignSeed(seedDesignArtifacts(featureName, process.cwd()));
+      reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
+      try {
+        const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
+        writeHandoff(featureName, process.cwd());
+      } catch { /* fail-open */ }
+      console.log(chalk.green(`\n✅ "${featureName}": gate plan já aprovado — ramo de design aberto (1-design/).\n`));
+      return;
+    }
+
     if (phase === 'review') {
       console.log(chalk.yellow(`\n⚠️  Feature "${featureName}" is already at the final phase (review).`));
       console.log(chalk.gray(`Approve Gate 3 with: morph-spec approve ${featureName} review`));
@@ -134,19 +126,10 @@ export async function advanceCommand(featureName, options = {}) {
       return;
     }
 
-    // Phase-exit artifact check (D3): a phase transition must not step over the
-    // artifact the phase it is CLOSING owes. Observed: a feature reached review
-    // with NO 3-implement/recap.md — the file was written later, by hand, so
-    // the Gate 3 review had nothing to review. `implement` has no gate, which
-    // is precisely why nothing stopped it.
-    //
-    // `--force` bypasses (same deliberate-recovery role it already plays for
-    // gate order) but still names what was skipped — a silent bypass would be
-    // the defect again.
+    // `implement` has no gate, so this is what keeps unfinished slice reports out of review.
+    // `--force` bypasses it but still names what was skipped.
     const missingArtifacts = missingPhaseArtifacts(phase, featurePath);
     if (missingArtifacts.length && !options.force) {
-      // Divergence, not absence: name the tree that actually holds the work
-      // instead of asking for a file that exists in it.
       const elsewhere = await artifactsLiveInWorktree(featureName, missingArtifacts);
       if (elsewhere) {
         console.error(chalk.red(`\n❌ A fase "${phase}" de "${featureName}" não pode ser encerrada A PARTIR DESTA ÁRVORE.`));
@@ -160,36 +143,16 @@ export async function advanceCommand(featureName, options = {}) {
         process.exit(1);
       }
 
-      console.error(chalk.red(`\n❌ A fase "${phase}" não pode ser encerrada — artefato(s) obrigatório(s) ausente(s):`));
+      console.error(chalk.red(`\n❌ A fase "${phase}" não pode ser encerrada — artefato(s) obrigatório(s) ausente(s) ou PARCIAL:`));
       for (const rel of missingArtifacts) console.error(chalk.gray(`   • ${rel}`));
       console.error(chalk.gray('\n   Produza o artefato e rode de novo, ou passe --force para avançar assim mesmo.\n'));
       process.exit(1);
     }
 
-    // 1) Approve the gate that completes the current phase.
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
 
-    // The screen checklist is part of what the uiux phase owes. The predicate
-    // is approve.js's too: an "auto" signature never closes a gate the
-    // gate-check would pause, and a recorded decision or a human signature
-    // (--approver) is the answer to that pause; --force is not, as in approve.
-    const checklistBlock = phase === 'uiux' ? uiuxAutoApprovalBlock(process.cwd(), featureName, feature) : null;
-    if (checklistBlock && approvedBy === 'auto') {
-      console.error(chalk.red(`\n❌ A fase "uiux" não pode ser encerrada com assinatura automática — ${checklistBlock}.`));
-      console.error(chalk.gray('\n   Complete o checklist (ver a skill morph-uiux) e rode de novo. Quem decidiu aprovar assim'));
-      console.error(chalk.gray(`   mesmo grava a decisão (morph-spec gate-decision ${featureName} uiux --pause false --reason "...")`));
-      console.error(chalk.gray('   ou assina com --approver <nome>. O --force não dispensa o checklist.\n'));
-      process.exit(1);
-    }
-
-    // Gate monotonicity (mirrors approve.js): advance is a gate write-path too,
-    // so it must not stamp gate N while a predecessor is pending. In the
-    // sanctioned flow advance is always in-order (it approves G1 before the plan
-    // artifact that flips the phase to plan exists), but an anomalous filesystem
-    // state — e.g. 2-plan/spec.md present without Gate 1, the lead-termometro
-    // shape — would otherwise let advance deepen the violation by stamping G2.
-    // Escape via --force for deliberate recovery.
+    // Gate monotonicity: never stamp gate N while a predecessor is pending (`--force` to recover).
     if (gate) {
       const unmet = unmetPrereqs(gate, feature.approvalGates);
       if (unmet.length && !options.force) {
@@ -199,35 +162,19 @@ export async function advanceCommand(featureName, options = {}) {
       }
     }
 
-    // Hotfix backstop (defensive, mirrors approve.js): the phase==='review'
-    // early-return above already stops advance from ever reaching a
-    // gate==='review' approval, but guard the approval itself too so this
-    // stays true even if the early-return's shape changes later. Gate on the
-    // RESOLVED approvedBy — headless contexts have no TTY and resolve to
-    // "auto" regardless of --mode, so checking the raw --mode string alone
-    // would let them slip through (same bug the approve.js backstop had).
-    if (gate === 'review' && feature.workType === 'hotfix' && approvedBy === 'auto') {
-      console.error(chalk.red('\n❌ Hotfix exige aprovação humana no Gate 3 — trust:auto não se aplica.'));
-      console.error(chalk.gray('   Aprove com --approver <nome>, num terminal interativo, ou pela resposta humana "aprovado" (state-sync) ao review-report via AskUserQuestion.\n'));
-      process.exit(1);
-    }
-
-    // Gate idempotency (F15): `setApprovalGate` REPLACES the gate object whole
-    // (state-manager.js), so re-writing an already-approved gate does not
-    // refresh it — it destroys `approvedBy`, `timestamp`, `notes` and
-    // `selfAssessed` in one assignment. And `resolveApprovedBy` above answers
-    // "auto" in every headless context, so `approve f proposal --approver
-    // lucas` followed by `advance f` used to rewrite a human's signature as
-    // "auto" — the one stamp the charter forbids on a human-approved gate.
-    // The state-sync hook already carries exactly this guard; `advance`, the
-    // other gate write-path, simply never got it.
-    //
-    // It skips ONLY the write. The scaffold and the handoff below still run,
-    // so re-running `advance` after a failed scaffold keeps working — the
-    // reason this is a guard and not an abort.
+    // `setApprovalGate` replaces the gate whole: rewriting an approved gate would turn a human
+    // signature into "auto". Skips ONLY the write, so the scaffold and handoff below still run.
     const priorGate = gate ? feature.approvalGates?.[gate] : null;
     const alreadyApproved = priorGate?.approved === true;
 
+    const refusal = alreadyApproved ? null
+      : autoApprovalRefusal({ cwd: process.cwd(), featureName, feature, gate, approvedBy });
+    if (refusal) {
+      printRefusal(chalk, refusal);
+      process.exit(1);
+    }
+    const checklistBlock = phase === 'uiux' && !alreadyApproved ? uiuxAutoApprovalBlock(process.cwd(), featureName, feature) : null;
+
     if (gate && !alreadyApproved) {
       await setApprovalGate(featureName, gate, true, {
         approvedBy,
@@ -236,17 +183,16 @@ export async function advanceCommand(featureName, options = {}) {
       });
     }
 
-    // 2) Scaffold the next phase folder so the agent can write its first artifact.
     let nextDir = NEXT_PHASE_DIR[phase];
-    if (phase === 'proposal' && options.design) nextDir = '1-design';
+    if (phase === 'plan' && options.design) nextDir = '1-design';
     if (nextDir) {
       const nextPath = join(featurePath, nextDir);
       if (!existsSync(nextPath)) mkdirSync(nextPath, { recursive: true });
     }
+    if (nextDir === '1-design') reportDesignSeed(seedDesignArtifacts(featureName, process.cwd()));
+    if (phase === 'plan') reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
 
-    // Fleet handoff: a phase transition is exactly when a session hands the
-    // feature over (to a new instance, or to itself after /compact) — refresh
-    // the derived handoff.md so the next reader starts from the new phase.
+    // A phase transition is when a session hands the feature over: refresh handoff.md.
     try {
       const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
       writeHandoff(featureName, process.cwd());
@@ -260,8 +206,7 @@ export async function advanceCommand(featureName, options = {}) {
       const by = options.force ? '--force' : `aprovado por ${approvedBy}`;
       console.log(chalk.yellow(`   ⚠️  ${by}: avançou com o ${checklistBlock}.`));
     }
-    // Report what actually happened: claiming "approved (auto)" when nothing
-    // was written is how the destroyed signature stayed invisible.
+    // Never claim "approved (auto)" when nothing was written.
     if (gate && alreadyApproved) {
       console.log(chalk.gray(`   Gate "${gate}" was already approved (${priorGate.approvedBy || 'unknown'}) — approval preserved, nothing re-written.`));
     } else if (gate) {