@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/project/env.js

@@ -1,20 +1,3 @@
-/**
- * `morph-spec env [feature] [--json|--posix|--powershell]` — print the
- * dedicated environment of a worktree (port block + compose project) in a
- * shell-loadable form.
- *
- * Inside Claude Code the `worktree-env-inject` hook applies this block to
- * every dev-server / compose launcher automatically. This command is the same
- * contract for everything OUTSIDE the harness: a human terminal
- * (`eval "$(morph-spec env)"`), a CI step, a sub-agent running without hooks.
- * It derives from `buildComposeEnv` — the function the `verify` e2e node and
- * `e2e up` already use — so a shell and the stack can never disagree.
- *
- * Feature resolution: explicit argument, else the `morph/{f}` (or
- * `morph-task/{n}`) branch of the cwd. Read-only: allocation is idempotent and
- * never moves an existing block.
- */
-
 import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
 import { join, resolve } from 'path';
@@ -49,14 +32,9 @@ function gitCommonDir(cwd) {
   }
 }
 
-/** POSIX single-quote. */
 const shq = (v) => `'${String(v).replace(/'/g, "'\\''")}'`;
 
-/**
- * Pure: the env map for a key, or `{ error }`.
- * @param {string|null} featureArg
- * @param {string} cwd
- */
+/** The env map for a key, or `{ error }`. */
 export function resolveWorktreeEnv(featureArg, cwd = process.cwd()) {
   const key = featureArg || envKeyFromBranch(currentBranch(cwd));
   if (!key) {
@@ -78,10 +56,6 @@ export function render(env, format) {
   return entries.map(([k, v]) => `export ${k}=${shq(v)}`).join('\n');
 }
 
-/**
- * @param {string|undefined} featureArg
- * @param {{ json?: boolean, posix?: boolean, powershell?: boolean }} options
- */
 export function envCommand(featureArg, options = {}) {
   const result = resolveWorktreeEnv(featureArg || null, process.cwd());
   if (result.error) {

package/src/commands/project/fleet.js

@@ -1,22 +1,7 @@
-/**
- * `morph-spec fleet [--json]` — the fleet view.
- *
- * One line per active feature across the primary root and every morph/*
- * worktree: phase, pending gates, task progress, port block, handoff
- * freshness, last commit and dirtiness. This is the terminal surface the
- * operator scans between sessions ("what is each instance doing, what is
- * waiting on me") — `worktree list` remains the lean per-worktree view.
- *
- * Read-only, always exits 0 (fail-open — an empty fleet is an answer).
- */
-
 import chalk from 'chalk';
 import { scanFleet } from '../../lib/worktree/fleet-scanner.js';
 import { claimAge } from '../../../framework/hooks/shared/claim-registry.js';
 
-/**
- * @param {{ json?: boolean, cwd?: string }} [options]
- */
 export function fleetCommand(options = {}) {
   const fleet = scanFleet(options.cwd || process.cwd());
 
@@ -32,22 +17,13 @@ export function fleetCommand(options = {}) {
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
 
-  /**
-   * The REMOTO cell. `-` means "unknown" (no origin, or the probe failed) —
-   * deliberately the same glyph as "nothing there", because both mean "do not
-   * trust the local view alone". `local` is the confident negative.
-   */
+  /** `-` (unknown) shares the "nothing there" glyph on purpose: both mean "do not trust the local view alone". */
   const remoteCell = (r) => {
     if (!r) return '-';
     if (r.pr) return `PR #${r.pr.number}${r.pr.state && r.pr.state !== 'OPEN' ? ` (${r.pr.state.toLowerCase()})` : ''}`;
     return r.pushed ? 'pushed' : 'local';
   };
 
-  /**
-   * The CLAIM cell — who is on this feature right now (B1). A stale claim is
-   * shown as stale, not hidden: "nobody here" and "somebody died here" are
-   * different facts for the operator.
-   */
   const claimCell = (c) => {
     if (!c) return '-';
     const age = claimAge(c);
@@ -55,20 +31,15 @@ export function fleetCommand(options = {}) {
   };
 
   console.log(chalk.white.bold(
-    // PHASE at 18: `aguardando-merge` (the pr-pending synthesized phase, see
-    // fleet-scanner.js) is 16 chars — 1 wider than the col width `list.js`
-    // already uses (17) for the identical string. A narrower column here
-    // would misalign every column after it just for that one row.
-    col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 18) + col('TASKS', 8)
+    // PHASE at 18 fits `aguardando-merge`; narrower misaligns every column after it.
+    col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 18) + col('FATIAS', 8)
     + col('GATES PEND.', 20) + col('WHERE', 24) + col('REMOTO', 16) + col('CLAIM', 16)
     + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
   ));
   for (const e of fleet.entries) {
-    const tasks = e.tasks ? `${e.tasks.done}/${e.tasks.total}` : '-';
+    const slices = e.slices ? `${e.slices.done}/${e.slices.total}` : '-';
     const gates = e.pendingGates.length ? e.pendingGates.join(',') : '-';
-    // pr-pending has no worktree and isn't root-resident either — its branch
-    // is the only place it exists, so show that instead of the misleading
-    // 'raiz' a location-blind check would print.
+    // pr-pending exists only on its branch, never in a worktree or the root.
     const where = (e.location === 'worktree' || e.location === 'pr-pending') ? e.branch : 'raiz';
     const ports = e.env ? `${e.env.range[0]}-${e.env.range[1]}` : '-';
     const handoff = e.handoff?.exists ? 'sim' : '-';
@@ -80,7 +51,7 @@ export function fleetCommand(options = {}) {
     // length and append the padding by hand.
     const claimPlain = e.claim ? `${e.claim.live ? 'sessão' : 'morta'} (${claimAge(e.claim)})` : '-';
     console.log(
-      col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 18) + col(tasks, 8)
+      col(e.feature, 20) + col(e.workType || '-', 9) + col(e.phase, 18) + col(slices, 8)
       + col(gates, 20) + col(where, 24) + col(remoteCell(e.remote), 16)
       + claimCell(e.claim) + ' '.repeat(Math.max(1, 16 - claimPlain.length))
       + col(ports, 12) + col(handoff, 9) + activity,

package/src/commands/project/heavy.js

@@ -4,9 +4,9 @@ import { logger } from '../../utils/logger.js';
 import { readHeavyConfig } from '../../../framework/hooks/shared/heavy-config.js';
 import { createHeavyGate, HeavyBusyError } from '../../lib/heavy/gate.js';
 import { describeHolder, heavyDir, heavyStatus } from '../../../framework/hooks/shared/heavy-slots.js';
+import { resolveSpawn } from '../../../framework/hooks/shared/spawn-command.js';
 
 const EXIT_BUSY = 3;
-const NEEDS_CMD_SHIM = /^(npm|npx|pnpm|yarn)$/;
 
 export function heavyStatusCommand(options = {}) {
   const config = readHeavyConfig(process.cwd());
@@ -49,8 +49,8 @@ export function heavyRunCommand(command, options = {}) {
     process.exit(EXIT_BUSY);
   }
 
-  const exe = process.platform === 'win32' && NEEDS_CMD_SHIM.test(file) ? `${file}.cmd` : file;
-  const res = spawnSync(exe, args, { stdio: 'inherit', shell: exe.endsWith('.cmd') });
+  const spawn = resolveSpawn(file, args);
+  const res = spawnSync(spawn.file, spawn.args, { stdio: 'inherit', shell: spawn.shell });
   gate.release();
 
   if (res.error) {

package/src/commands/project/init.js

@@ -37,25 +37,8 @@ import { resolvePrimaryRoot } from './worktree.js';
 import { registerProject } from '../../lib/projects/registry.js';
 
 /**
- * Guard against running a full `init` install from inside a secondary
- * (linked) git worktree.
- *
- * A worktree's `.claude/` and `.morph/framework/` are junctions back to the
- * primary root (see `worktree.js`'s `setupInfraLinks`), but `.morph/config/`,
- * `.morph/context/`, `.morph/checkpoints/`, `.morph/memory/`, `.morph/archive/`
- * and `.morph/state.json` are NOT linked — a full `init` there would scaffold
- * a second, disconnected install (config, state) inside the worktree, orphaned
- * from the primary root's real install.
- *
- * Fail-SAFE (not fail-open): blocks whenever `resolvePrimaryRoot(targetPath)`
- * resolves to a path OTHER than `targetPath` itself. `resolvePrimaryRoot`
- * itself fails open to `targetPath` outside a git repo (or on any git error),
- * so non-git projects and the primary root itself are never blocked.
- * `--force` is the explicit override, mirroring init's own `--force` flag.
- *
- * @param {string} targetPath - Effective install target (init's targetPath)
- * @param {{ force?: boolean }} [options]
- * @returns {{ blocked: boolean, root?: string, target?: string }}
+ * A linked worktree junctions `.claude/` and `.morph/framework/` but not `.morph/config`/state:
+ * a full install there orphans a second, disconnected one. `--force` overrides.
  */
 export function checkSecondaryWorktreeGuard(targetPath, options = {}) {
   if (options.force) return { blocked: false };
@@ -72,9 +55,6 @@ export async function initCommand(options) {
   logger.dim(`Target: ${targetPath}`);
   logger.blank();
 
-  // Guard: refuse a full install from inside a secondary worktree — it would
-  // corrupt the shared infra junctioned back to the primary root and scaffold
-  // a second, disconnected .morph/config + state.json. --force overrides.
   const worktreeGuard = checkSecondaryWorktreeGuard(targetPath, options);
   if (worktreeGuard.blocked) {
     logger.warn(`Você está num worktree secundário (${worktreeGuard.target}).`);
@@ -83,11 +63,9 @@ export async function initCommand(options) {
     process.exit(0);
   }
 
-  // Check if already initialized
   const morphPath = join(targetPath, '.morph');
   if (await pathExists(morphPath)) {
     if (!options.force) {
-      // Check if project version is outdated — auto-update instead of blocking
       const projectCheck = await checkProjectOutdated(targetPath);
       if (projectCheck.isOutdated) {
         logger.info(`MORPH already initialized (v${projectCheck.current}). Framework update available (v${projectCheck.cliVersion}).`);
@@ -105,31 +83,27 @@ export async function initCommand(options) {
 
   try {
 
-    // Steps 1-10: Infrastructure (headless, no prompts)
     spinner.stop();
-    // force: true — the secondary-worktree guard already ran above (either we
-    // ARE the primary root, or the caller explicitly passed --force), so it
-    // must not be redundantly re-applied inside setupInfra().
+    // The secondary-worktree guard already ran above; setupInfra must not re-apply it.
     const infraResult = await setupInfra(targetPath, { force: true });
+    if (infraResult?.refused) {
+      process.exitCode = 1;
+      return infraResult;
+    }
     spinner.start('Continuing...');
 
-    // Derive display variables from what setupInfra installed
     const cliVersion = getInstalledCLIVersion();
     const commandsCopied = await pathExists(join(targetPath, '.claude', 'commands'));
     const rulesCopied = await pathExists(join(targetPath, '.claude', 'rules'));
-    // Re-run installClaudeHooks to get the result object (idempotent — hooks already installed)
     const hooksResult = await installClaudeHooks(targetPath);
 
-    // Re-derive config path for stack detection updates
     const configDir = join(morphPath, 'config');
     const configPath = join(configDir, 'config.json');
     const contextDir = join(morphPath, 'context');
 
-    // Read config written by setupInfra so stack detection can update it
     let config = (await pathExists(configPath)) ? await readJson(configPath) : { project: {} };
     if (!config.project) config.project = {};
 
-    // 11b. Detect Claude Code environment (plugins, MCPs, skills)
     spinner.text = 'Detecting Claude Code environment...';
     let claudeConfigDetected = null;
     let integrationsCreated = false;
@@ -148,14 +122,6 @@ export async function initCommand(options) {
           logger.info(summary);
         }
 
-        // Show MCP-to-phase mapping.
-        //
-        // This called mapMcpsToPhases with one argument where it takes three,
-        // so `phaseMatrix[currentPhase]` threw a TypeError on every project
-        // that had any MCP configured. The outer catch reported it as
-        // "Claude config detection skipped" — which reads like "nothing to
-        // detect" — and everything below it never ran: integrations.json was
-        // never written and the optimized settings were never generated.
         if (claudeConfigDetected.mcpServers.length > 0) {
           const byPhase = mcpAvailabilityByPhase(
             claudeConfigDetected.mcpServers,
@@ -191,11 +157,9 @@ export async function initCommand(options) {
         }
       }
     } catch (error) {
-      // Non-fatal: continue without integrations
       logger.dim(`  Claude config detection skipped: ${error.message}`);
     }
 
-    // 11c. Stack detection (moved before MCP setup so we know the stack)
     spinner.text = 'Detecting project stack...';
     let detectedStack = 'unknown';
     const hasProjectFiles = await pathExists(join(targetPath, 'package.json'))
@@ -210,7 +174,6 @@ export async function initCommand(options) {
         if (structure?.stack && structure.stack !== 'unknown') {
           detectedStack = structure.stack;
 
-          // Persist detected stack to config.json
           if (structure?.stack && structure.stack !== 'unknown') {
             config.project.stack = structure.stack;
           }
@@ -252,23 +215,19 @@ export async function initCommand(options) {
             logger.dim('Review and edit .morph/context/standards.md as needed.');
           }
 
-          // Re-install stack-filtered assets now that we know the stack
           const stackTags = getProjectTags(config);
           if (stackTags.length > 0) {
             spinner.start('Re-installing stack-filtered assets...');
             const frameworkDir = join(targetPath, '.morph', 'framework');
             const fwSrcDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'framework');
 
-            // Rules
             const rulesSrc = join(fwSrcDir, 'rules');
             const rulesDest = join(targetPath, '.claude', 'rules');
             installRulesForStack(rulesSrc, rulesDest, stackTags);
             installCommandsForStack(join(fwSrcDir, 'commands'), join(targetPath, '.claude', 'commands'), stackTags);
 
-            // Skills
             await installSkills(targetPath, { projectTags: stackTags });
 
-            // Agents (domain personas from agents.json)
             await installAgents(targetPath, fwSrcDir, { projectTags: stackTags });
             await installDomainAgents(targetPath, fwSrcDir, { projectTags: stackTags });
 
@@ -282,7 +241,6 @@ export async function initCommand(options) {
       }
     }
 
-    // 11d. MCP Auto-Setup
     let mcpSetupResult = null;
     if (!options.skipMcp) {
       try {
@@ -300,7 +258,6 @@ export async function initCommand(options) {
           logger.blank();
           logger.header('MCP Server Setup');
 
-          // Auto-install prompt
           let autoInstalled = {};
           if (hasAutoMcps) {
             const { installAuto } = await inquirer.prompt([{
@@ -318,7 +275,6 @@ export async function initCommand(options) {
                 autoInstalled[name] = orchestration.autoInstallable[name];
               }
 
-              // Install companion skills for MCPs that define them (e.g., Stitch agent skills)
               const skillResults = installCompanionSkills(orchestration.autoInstallable);
               for (const r of skillResults) {
                 if (r.success) {
@@ -330,13 +286,11 @@ export async function initCommand(options) {
             }
           }
 
-          // Credential MCPs — inline setup or instructions
           const manualInstalled = {};
           if (hasManualMcps) {
             for (const [name, entry] of Object.entries(orchestration.needsManualSetup)) {
               logger.blank();
 
-              // Show warnings
               for (const warning of entry.install.warnings || []) {
                 logger.warn(`  ${warning}`);
               }
@@ -350,7 +304,6 @@ export async function initCommand(options) {
               }]);
 
               if (setupNow) {
-                // Stitch — automated setup via setupStitch()
                 if (name === 'stitch' && !entry.install.autoInstall) {
                   spinner.start('Setting up Stitch MCP...');
                   const stitchResult = await setupStitch(targetPath);
@@ -370,7 +323,6 @@ export async function initCommand(options) {
                   continue;
                 }
 
-                // Remote MCPs — launch OAuth via claude mcp add
                 if (isRemoteMcp(entry.install.config)) {
                   const url = entry.install.config.url;
                   logger.info(`  Launching ${capitalizedName} OAuth authentication...`);
@@ -387,7 +339,6 @@ export async function initCommand(options) {
                   continue;
                 }
 
-                // Collect credentials
                 const credentialValues = {};
                 for (const cred of entry.install.credentials) {
                   const { value } = await inquirer.prompt([{
@@ -404,7 +355,6 @@ export async function initCommand(options) {
                 spinner.succeed(`${capitalizedName} MCP configured`);
                 manualInstalled[name] = entry;
               } else {
-                // Show setup instructions
                 const instructions = generateSetupInstructions(name, entry);
                 logger.blank();
                 logger.dim('  Add to .mcp.json → mcpServers:');
@@ -422,7 +372,6 @@ export async function initCommand(options) {
             }
           }
 
-          // Summary table
           const justInstalled = { ...autoInstalled, ...manualInstalled };
           const statusRows = formatMcpStatusTable(orchestration, justInstalled);
 
@@ -456,7 +405,6 @@ export async function initCommand(options) {
       logger.dim('\nSkipped MCP setup (--skip-mcp flag)');
     }
 
-    // Auto-generate architecture context (non-blocking on failure)
     spinner.text = 'Generating architecture context...';
     try {
       const { scanArchitecture, renderArchitectureContext } = await import('../../lib/generators/architecture-scanner.js');
@@ -464,15 +412,12 @@ export async function initCommand(options) {
       await renderArchitectureContext(targetPath, scanResult);
       spinner.succeed('Architecture context generated');
     } catch {
-      // Non-fatal: placeholder README.md remains
       spinner.warn('Architecture context generation skipped');
     }
 
     spinner.succeed('MORPH-SPEC installed successfully!');
-    // The dashboard's portfolio learns about the project here (fail-open).
     registerProject(targetPath, 'init');
 
-    // Show next steps
     logger.blank();
     logger.success(`MORPH-SPEC v${cliVersion} installed successfully!`);
     logger.blank();
@@ -513,7 +458,6 @@ export async function initCommand(options) {
 
     logger.dim('  ✓ .claude/skills/ (installed as skill directories)');
 
-    // Show agent team breakdown from setup-infra result
     const agents = infraResult?.agents;
     if (agents) {
       const total = (agents.tier1 || 0) + (agents.tier2 || 0) + (agents.specialists || 0) + (agents.personas || 0);
@@ -524,7 +468,6 @@ export async function initCommand(options) {
 
     logger.dim('  ✓ ~/.claude/statusline.sh (global statusline installed)');
 
-    // Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in ~/.claude/settings.local.json
     logger.blank();
     const globalSettingsPath = join(homedir(), '.claude', 'settings.local.json');
     let agentTeamsEnabled = false;
@@ -532,7 +475,6 @@ export async function initCommand(options) {
       const globalSettings = await readJson(globalSettingsPath);
       agentTeamsEnabled = globalSettings?.env?.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === '1';
     } catch {
-      // File missing or unreadable — treat as not enabled
     }
 
     if (agentTeamsEnabled) {
@@ -544,7 +486,6 @@ export async function initCommand(options) {
 
     logger.blank();
 
-    // Populate Claude Code persistent memory so future sessions enter contextualized
     try {
       const { installProjectMemory } = await import('../../lib/installers/memory-installer.js');
       const memResult = await installProjectMemory(targetPath, {
@@ -557,10 +498,9 @@ export async function initCommand(options) {
       logger.dim(`  ⚠ Memory install skipped: ${err.message}`);
     }
 
-    // Suggest tutorial for first-time users
     if (integrationsCreated) {
       logger.blank();
-      logger.info('First time using morph-spec? Run `/morph-proposal <feature>` to start a new feature.');
+      logger.info('First time using morph-spec? Run `/morph-plan <feature>` to start a new feature.');
     }
 
     logger.blank();

package/src/commands/project/install-plugin-cmd.js

@@ -1,4 +1,3 @@
-// src/commands/project/install-plugin-cmd.js
 import { installPlugin } from '../../scripts/install-plugin.js';
 import { logger } from '../../utils/logger.js';
 

package/src/commands/project/setup-infra-cmd.js

@@ -4,7 +4,8 @@ import { logger } from '../../utils/logger.js';
 export async function setupInfraCommand(options) {
   const targetPath = options.path || process.cwd();
   try {
-    await setupInfra(targetPath, { reinstall: options.reinstall ?? false });
+    const result = await setupInfra(targetPath, { reinstall: options.reinstall ?? false });
+    if (result?.refused) process.exitCode = 1;
   } catch (err) {
     logger.error(`setup-infra failed: ${err.message}`);
     process.exit(1);

package/src/commands/project/stack-scan.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getFeatureDir } from '../../core/paths/output-schema.js';
+import { readMorphConfig } from '../../lib/tasks/test-runner.js';
+import { notAuditedReason, scanStack, renderStackScan } from '../../lib/stack/stack-scan.js';
+import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
+
+export const STACK_SCAN_FILE = 'stack-scan.md';
+
+/** Scan the tree at `cwd`; with a feature, write `2-plan/stack-scan.md`. */
+export function runStackScan(featureName, cwd = process.cwd()) {
+  const result = scanStack(cwd, readMorphConfig(cwd));
+  const markdown = renderStackScan(result, featureName ?? 'projeto');
+  if (!featureName) return { ...result, markdown, written: null, exit: 0 };
+
+  const featureDir = join(cwd, getFeatureDir(featureName));
+  if (!existsSync(featureDir)) return { ...result, markdown, written: null, exit: 2, error: 'feature-not-found' };
+  const planDir = join(featureDir, '2-plan');
+  mkdirSync(planDir, { recursive: true });
+  const written = join(planDir, STACK_SCAN_FILE);
+  writeFileSync(written, markdown, 'utf8');
+  return { ...result, markdown, written, exit: 0 };
+}
+
+export function stackScanCommand(featureName, options = {}) {
+  if (featureName) {
+    const owner = assertOwnerTree(featureName, process.cwd());
+    if (owner.blocked) {
+      for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec stack-scan ${featureName}`)) {
+        console.error(chalk[tone](text));
+      }
+      process.exit(1);
+    }
+  }
+
+  const result = runStackScan(featureName);
+  if (options.json) {
+    const { markdown, ...rest } = result;
+    console.log(JSON.stringify(rest, null, 2));
+    process.exit(result.exit);
+  }
+  if (result.error === 'feature-not-found') {
+    console.error(chalk.red(`stack-scan: a feature "${featureName}" não existe — rode morph-spec create ${featureName} antes`));
+    process.exit(2);
+  }
+  if (result.written) {
+    const high = result.deviations.filter((d) => d.severity === 'Bloqueante' || d.severity === 'Alto').length;
+    console.log(chalk.green(`✓ stack-scan: ${join(getFeatureDir(featureName), '2-plan', STACK_SCAN_FILE)} gravado`));
+    const summary = result.greenfield ? 'greenfield'
+      : !result.audited ? notAuditedReason(result)
+      : `${result.deviations.length} desvio(s), ${high} Bloqueante/Alto`;
+    console.log(chalk.gray(`  ${summary}`));
+  } else {
+    process.stdout.write(result.markdown);
+  }
+  process.exit(result.exit);
+}