@polymorphism-tech/morph-spec 9.0.0 → 9.2.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

@@ -14,44 +14,17 @@ 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).
- */
-
-// The gate approved when *completing* a given phase. `implement` has no gate
-// (it ends when all slices are done), so advancing from implement just
-// scaffolds the review folder.
+// `implement` has no gate: advancing from it only scaffolds the review folder.
 const PHASE_GATE = { plan: 'plan', uiux: 'uiux', review: 'review' };
 
-// The next phase folder to scaffold when advancing FROM a given phase. The
-// default forward path skips the optional design phase (plan → implement); pass
-// --design to take the uiux branch (plan → 1-design).
 const NEXT_PHASE_DIR = {
   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');
@@ -59,8 +32,7 @@ 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}`;
@@ -79,20 +51,8 @@ function unfinishedSliceReports(featurePath) {
   return progress.slices.filter((s) => s.status !== 'feito').map((s) => `3-implement/reports/${s.id}.md`);
 }
 
-/**
- * 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>}
- */
+// 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');
@@ -107,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';
@@ -133,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}`)) {
@@ -169,17 +126,10 @@ export async function advanceCommand(featureName, options = {}) {
       return;
     }
 
-    // Phase-exit artifact check: a phase transition must not step over what the
-    // phase it is CLOSING owes. `implement` has no gate, so this is the only
-    // thing that keeps a feature with unfinished slice reports out of review.
-    //
-    // `--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.`));
@@ -199,16 +149,10 @@ export async function advanceCommand(featureName, options = {}) {
       process.exit(1);
     }
 
-    // 1) Approve the gate that completes the current phase.
     const gate = PHASE_GATE[phase];
     const approvedBy = resolveApprovedBy(options);
 
-    // 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, but an anomalous filesystem
-    // state — e.g. 1-design/design-system.md present without the plan gate —
-    // would otherwise let advance deepen the violation by stamping uiux.
-    // 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) {
@@ -218,19 +162,8 @@ export async function advanceCommand(featureName, options = {}) {
       }
     }
 
-    // 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 plan --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;
 
@@ -250,7 +183,6 @@ 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 === 'plan' && options.design) nextDir = '1-design';
     if (nextDir) {
@@ -260,9 +192,7 @@ export async function advanceCommand(featureName, options = {}) {
     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());
@@ -276,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) {

package/src/commands/state/approve.js

@@ -19,16 +19,10 @@ export { REVIEWED_SHA_TOKEN };
 
 const SIGNED_OFF = { required: [], reports: {}, checks: { status: 'ok', total: 0, missing: [], notProven: [] } };
 
-/**
- * Do the review reports still describe the current tree? Every report present
- * is compared; the worst answer wins.
- *
- * @param {ReturnType<typeof reviewReports>} reports
- * @returns {{ status: 'ok'|'stale'|'unstamped'|'skip', file?: string, reviewed?: string, head?: string, ahead?: number }}
- *   `skip`: no verifier report or no git repo. Never a false refusal.
- */
+// The worst answer across every report present wins. `skip` (no report at all, no git) never
+// refuses falsely.
 function reviewStaleness(reports) {
-  if (reports.verifier.status === 'missing') return { status: 'skip' };
+  if (Object.values(reports).every((r) => r.status === 'missing')) return { status: 'skip' };
   const cwd = process.cwd();
   let head;
   try {
@@ -64,9 +58,6 @@ function reviewStaleness(reports) {
   return unstamped ?? { status: 'ok', head };
 }
 
-/**
- * Unapprove action function - Revoke a previously approved gate
- */
 export async function unapproveCommand(featureName, gateName, options = {}) {
   try {
     if (!VALID_GATES.includes(gateName)) {
@@ -95,8 +86,7 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
       return;
     }
 
-    // Same honesty rule as approveCommand: don't pretend a human revoked
-    // the gate when there's no interactive shell behind the invocation.
+    // Don't pretend a human revoked the gate without an interactive shell behind the call.
     let revokedBy;
     if (options.revoker) {
       revokedBy = options.revoker;
@@ -123,44 +113,25 @@ export async function unapproveCommand(featureName, gateName, options = {}) {
   }
 }
 
-/**
- * Approval Commands - Manage approval gates for MORPH workflow
- *
- * Commands:
- * - approve: Mark a gate as approved
- * - unapprove: Revoke a gate approval
- * - approval-status: Show approval status for all gates
- */
-
 const program = new Command();
 
-/**
- * Valid approval gate names
- */
 const VALID_GATES = ['plan', 'uiux', 'review'];
 
-/**
- * Approve action function - Mark a gate as approved
- */
 export async function approveCommand(featureName, gateName, options = {}) {
   try {
-    // Validate gate name
     if (!VALID_GATES.includes(gateName)) {
       console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
       console.log(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
       process.exit(1);
     }
 
-    // Get feature state
     const feature = getFeature(featureName);
     if (!feature) {
       console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
       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 approve ${featureName} ${gateName}`)) {
@@ -169,27 +140,18 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Check if already approved
     const currentStatus = getApprovalGate(featureName, gateName);
     if (currentStatus?.approved) {
       console.log(chalk.yellow(`\n⚠️  Gate "${gateName}" is already approved`));
       console.log(chalk.gray(`Approved at: ${currentStatus.timestamp}`));
       console.log(chalk.gray(`Approved by: ${currentStatus.approvedBy || 'Unknown'}`));
-      // This early-out is a no-op that still exits 0 — deliberate, and
-      // `--force` does NOT cover it (that flag only covers gate ORDER). A
-      // caller who meant to re-approve therefore reads success and is left
-      // with nowhere to go. The way out already exists as `unapprove`; the
-      // message just never named it. Naming it is the whole fix (no new flag).
+      // `--force` does not cover this no-op (it only covers gate ORDER), so name the way out.
       console.log(chalk.gray(`To approve it again, revoke it first: morph-spec unapprove ${featureName} ${gateName}\n`));
       if (gateName === 'plan') reportDotnetIgnores(seedDotnetBuildIgnores(process.cwd(), { featureName }));
       return;
     }
 
-    // Gate monotonicity: a gate may only be approved once its predecessors are
-    // approved (plan → review; uiux requires plan). Prevents the shape of a
-    // review approved with the plan still pending. Policy-stamped
-    // gates count as approved, so chore/hotfix satisfy prereqs naturally.
-    // Escape via --force for deliberate recovery.
+    // Gate monotonicity: predecessors first; policy stamps count (`--force` to recover).
     const unmet = unmetPrereqs(gateName, feature.approvalGates);
     if (unmet.length && !options.force) {
       console.error(chalk.red(`\n❌ Cannot approve "${gateName}" — prerequisite gate(s) not approved: ${unmet.join(', ')}.`));
@@ -197,22 +159,8 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Resolve who approved BEFORE the hotfix backstop — the backstop gates on
-    // the resolved signature, not the raw --mode string (see below).
-    //
-    // approvedBy resolution (most explicit wins):
-    //   1. --approver flag (CLI caller signalled who approved)
-    //   2. --mode auto  → "auto" (intentionally non-human signature)
-    //   3. interactive shell (TTY on stdin) → $USER / $USERNAME (a real
-    //      human is at the terminal; their name is the honest answer)
-    //   4. non-interactive (no TTY) → "auto"
-    //
-    // The TTY check exists because morph-spec is increasingly invoked
-    // from headless contexts (claude -p subprocesses, CI, the
-    // morph-e2e-tester). Stamping the host's $USERNAME on a gate that
-    // no human actually approved is misleading — it lies to the audit
-    // trail. "auto" reads as what it is: a deterministic policy gate,
-    // not a human signing off.
+    // Resolved BEFORE the hotfix backstop, which gates on the signature. Without a TTY the answer
+    // is "auto": stamping $USERNAME on a gate no human approved lies to the audit trail.
     let approvedBy;
     if (options.approver) {
       approvedBy = options.approver;
@@ -230,16 +178,8 @@ export async function approveCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Gate 3 staleness backstop (D1): a review reviews a TREE, and the tree
-    // moves. Observed: a review report written at b30ac6e, then T3 landed and
-    // inverted the default of a business rule; the report stayed in the repo
-    // claiming 976/976 tests (they were 982) and never mentioning T3. Nothing
-    // detected that the review artifact had fallen behind the code it reviews.
-    //
-    // The report stamps the SHA it reviewed; approval compares it with HEAD.
-    // A stamp that is BEHIND HEAD refuses. A MISSING stamp only warns — reports
-    // written before this existed must not brick a legacy feature — but the
-    // warning names the exact token to add, so it teaches instead of nagging.
+    // A review reviews a TREE: a `Reviewed-SHA` behind HEAD refuses. A missing stamp only warns,
+    // naming the token to add, so a legacy report does not brick the feature.
     const reports = gateName === 'review' ? reviewReports(process.cwd(), featureName) : null;
     if (gateName === 'review') {
       const stale = reviewStaleness(reports);
@@ -290,9 +230,8 @@ export async function approveCommand(featureName, gateName, options = {}) {
           selfAssessed = true;
         }
 
-        // Sem gate-check prévio não há `gateDecisions.review` para o backstop acima morder; em
-        // campo, ships passaram assim com verify vermelho ou ausente. A auto-aprovação recalcula
-        // a decisão pela MESMA régua do gate-check. --self-assessed já dispensou os relatórios.
+        // Sem gate-check prévio não há `gateDecisions.review` para o backstop morder: a auto-aprovação
+        // recalcula a decisão pela MESMA régua do gate-check. --self-assessed já dispensou os relatórios.
         if (approvedBy === 'auto') {
           const signals = collectSignals(featureName, feature, process.cwd(), 'review');
           if (selfAssessed) signals.reviewReports = SIGNED_OFF;
@@ -321,12 +260,7 @@ export async function approveCommand(featureName, gateName, options = {}) {
       ...(selfAssessed ? { selfAssessed: true } : {}),
     });
 
-    // Fleet handoff (mirrors advance.js): approving a gate is exactly when a
-    // feature hands over between sessions too — `approve` is the real path
-    // the plan gate took in the field (`approve <f> plan --mode auto`), not just
-    // `advance`, so a handoff.md left stale after approve was the common
-    // case, not the edge case. Same helper, same fail-open contract: a
-    // regeneration failure must never fail the approval itself.
+    // Approving is a session handoff too; a regeneration failure must never fail the approval.
     try {
       const { writeHandoff } = await import('../../lib/generators/handoff-generator.js');
       writeHandoff(featureName, process.cwd());
@@ -347,28 +281,20 @@ export async function approveCommand(featureName, gateName, options = {}) {
   }
 }
 
-/**
- * Approve command - Mark a gate as approved
- */
 program
   .command('approve <feature> <gate>')
   .description('Approve a phase gate to allow workflow progression')
   .action(approveCommand);
 
-/**
- * Approval status action function - Show all gates and their status
- */
 export async function approvalStatusCommand(featureName, options = {}) {
   try {
-    // Get feature state
     const feature = getFeature(featureName);
     if (!feature) {
       console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
       process.exit(1);
     }
 
-    // v5 removed the stored feature.phase — derive it from the filesystem +
-    // approved gates (same as `morph-spec status`), never print "unknown".
+    // Phase derived from the filesystem + approved gates, never "unknown".
     const featurePath = join(process.cwd(), '.morph', 'features', featureName);
     const phase = feature.phase || derivePhase(featurePath);
 
@@ -377,7 +303,6 @@ export async function approvalStatusCommand(featureName, options = {}) {
     const uiuxGate = getApprovalGate(featureName, 'uiux');
     const uiuxTaken = uiuxGate?.approved === true || existsSync(join(featurePath, '1-design'));
 
-    // JSON output
     if (options.json) {
       const status = {
         feature: featureName,
@@ -398,11 +323,9 @@ export async function approvalStatusCommand(featureName, options = {}) {
     console.log(chalk.bold(`\n📋 Approval Status for: ${featureName}`));
     console.log('━'.repeat(60));
 
-    // Show current phase
     console.log(chalk.cyan(`\nCurrent Phase: ${phase}`));
     console.log(chalk.gray(`Feature Status: ${feature.status || 'unknown'}\n`));
 
-    // Show each gate
     console.log(chalk.bold('Approval Gates:'));
 
     for (const gateName of VALID_GATES) {
@@ -444,7 +367,6 @@ export async function approvalStatusCommand(featureName, options = {}) {
       }
     }
 
-    // Show approval history if available
     const history = getApprovalHistory(featureName);
     if (history && history.length > 0) {
       console.log(chalk.bold('\nApproval History:'));
@@ -462,16 +384,12 @@ export async function approvalStatusCommand(featureName, options = {}) {
   }
 }
 
-/**
- * Approval status command - Show all gates and their status
- */
 program
   .command('approval-status <feature>')
   .alias('status')
   .description('Show approval status for all gates')
   .action(approvalStatusCommand);
 
-// Only parse if run directly (not imported as module)
 if (import.meta.url === `file://${process.argv[1]}`) {
   if (process.argv.length > 2) {
     program.parse(process.argv);