@polymorphism-tech/morph-spec 4.9.0 → 4.10.0

package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: morph:scope-escalation
+description: Guided workflow for mid-implementation scope escalation — analyzes complexity discovery, recommends action, and executes phase regression or task expansion
+user-invocable: true
+argument-hint: "[feature-name]"
+---
+
+# Scope Escalation Workflow
+
+Use this skill when a task during implementation reveals significantly more complexity than estimated.
+
+## Prerequisites
+
+- Feature must be in `implement` phase
+- You must have identified a specific task that triggered the discovery
+
+## Workflow
+
+### Step 1: COLLECT Evidence
+
+Ask the user (using `AskUserQuestion`):
+
+1. **Which task triggered the discovery?** (task ID from tasks.md)
+2. **What did you discover?** (specific complexity: hidden dependencies, wrong assumptions, missing abstractions)
+3. **Show evidence** — read the relevant code files to understand the actual complexity
+
+### Step 2: ANALYZE Impact
+
+Run dry-run analysis:
+
+```bash
+npx morph-spec scope escalate <feature> --task <id> --reason "<reason>" --dry-run
+```
+
+Read the recommendation output. Additionally:
+
+- Read `tasks.md` to understand which tasks are affected
+- Read `spec.md` to check if the spec assumed simpler architecture
+- Check completed tasks for potential impact
+
+### Step 3: CLASSIFY and PROPOSE
+
+Present the recommendation to the user:
+
+| Impact | Action | When |
+|--------|--------|------|
+| **Low** (1-3 tasks) | Task Expansion | The task is bigger than expected, but scope is contained |
+| **Medium** (4+ tasks, spec ok) | Regress to tasks | Multiple tasks need rewriting, but the spec is correct |
+| **High** (spec wrong) | Regress to design | The spec made incorrect assumptions about the codebase |
+
+Explain WHY you recommend this classification based on the evidence.
+
+### Step 4: APPROVE
+
+Pause and wait for user confirmation using `AskUserQuestion`:
+
+- "Do you agree with the [impact] classification?"
+- "Should we proceed with [action]?"
+- Allow override: "Or would you prefer a different target phase?"
+
+**DO NOT proceed without explicit user approval.**
+
+### Step 5: EXECUTE
+
+Based on approved action:
+
+**For expansion (low impact):**
+```bash
+npx morph-spec task expand <feature> <task-id> --into "T017a: <title>" "T017b: <title>" ...
+```
+
+**For regression (medium/high impact):**
+```bash
+npx morph-spec scope escalate <feature> --task <id> --reason "<reason>"
+```
+
+Or with target override:
+```bash
+npx morph-spec scope escalate <feature> --task <id> --reason "<reason>" --target design
+```
+
+### Step 6: GUIDE Next Steps
+
+After escalation:
+
+- **If regressed to tasks:** "Re-analyze the affected tasks. Rewrite tasks.md with accurate scope. Run `/morph-proposal <feature>` to continue from the tasks phase."
+- **If regressed to design:** "Re-analyze the spec. Update spec.md with the discovered architecture. Then regenerate tasks."
+- **If expanded:** "Continue implementing. Use `morph-spec task start <feature> <sub-task-id>` to start the first sub-task."
+
+Always remind: "Completed tasks flagged with `needsReview` should be checked for compatibility with the new scope."
+
+## Anti-Patterns
+
+- **DO NOT** skip the approval step
+- **DO NOT** escalate without evidence — read the actual code first
+- **DO NOT** regress to design when only tasks need rewriting
+- **DO NOT** expand when 4+ tasks are affected — regress instead

package/framework/standards/integration/mcp/mcp-tools.md

@@ -49,15 +49,10 @@ const repo = await mcp__github__get_repo();
 
 | MCP | Use Case | Example |
 |-----|----------|---------|
-| **Figma** | Extract design tokens, components | `mcp__figma__get_file({ fileKey })` |
 | **Playwright** | Navigate, screenshot, inspect live pages | `mcp__playwright__browser_navigate({ url })` |
 | **Context7** | Component library documentation | `mcp__context7__query_docs({ libraryId, query })` |
 
 ```javascript
-// Get design tokens from Figma
-const file = await mcp__figma__get_file({ fileKey: "abc123" });
-// → colors, typography, spacing from design file
-
 // Screenshot existing app for design reference
 await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
 const screenshot = await mcp__playwright__browser_take_screenshot();
@@ -180,6 +175,7 @@ for (const task of tasks) {
 | **GitHub** | Create PR, push branches | `mcp__github__create_pull_request()` |
 | **Context7** | Look up API usage during coding | `mcp__context7__query_docs()` |
 | **Playwright** | Smoke test deployed features, verify UI | `mcp__playwright__browser_navigate()` |
+| **Vercel** | Deploy, check logs, manage env vars | `mcp__vercel__list_projects()` |
 | **Azure** | Provision resources, check deployment status | Provider-specific |
 | **Docker** | Build images, manage containers | Provider-specific |
 
@@ -214,7 +210,25 @@ const logs = await mcp__playwright__browser_console_messages();
 // Screenshot for recap.md documentation
 const screenshot = await mcp__playwright__browser_take_screenshot();
 
-// Fallback: Bash for migrations, gh CLI for PRs
+// === VERCEL (Deployment & Environment) ===
+
+// List projects
+const projects = await mcp__vercel__list_projects();
+
+// Check deployment status and logs
+const deployments = await mcp__vercel__get_deployments({ projectId: 'my-project' });
+const logs = await mcp__vercel__get_deployment_logs({ deploymentId: deployments[0].uid });
+
+// Manage environment variables
+await mcp__vercel__manage_env_vars({
+  projectId: 'my-project',
+  action: 'set',
+  key: 'DATABASE_URL',
+  value: process.env.DATABASE_URL,
+  target: ['production', 'preview']
+});
+
+// Fallback: Bash for migrations, gh CLI for PRs, vercel CLI for deployments
 ```
 
 ---
@@ -225,7 +239,6 @@ const screenshot = await mcp__playwright__browser_take_screenshot();
 |------|----------|--------------------|
 | Database schema | Supabase/DB MCP | Grep queries + Read types |
 | Repo metadata | GitHub MCP | Bash `gh` CLI |
-| Design tokens | Figma MCP | Read CSS/SCSS variables |
 | Library docs | Context7 | WebSearch + WebFetch |
 | Live page preview | Playwright MCP | WebFetch URL |
 | Page interaction (click, type, navigate) | Playwright MCP | Manual testing |
@@ -233,6 +246,7 @@ const screenshot = await mcp__playwright__browser_take_screenshot();
 | Console error checking | Playwright MCP (`browser_console_messages`) | Browser DevTools |
 | Container ops | Docker MCP | Bash `docker` CLI |
 | Cloud resources | Azure MCP | Bash `az` CLI |
+| Vercel deployments | Vercel MCP | Bash `vercel` CLI |
 
 **Rule:** MCP tools provide structured data (JSON responses). Native tools require manual parsing. **Always prefer MCP when available** — fall back to native when not.
 
@@ -332,6 +346,8 @@ await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/fil
 
 ### Supabase: Full Schema Discovery
 
+> **v4 config:** Remote OAuth — `{ "type": "http", "url": "https://mcp.supabase.com/mcp" }`. Authenticate via `/mcp` in Claude Code.
+
 ```javascript
 // Complete workflow for Phase 2 schema analysis
 const tables = await mcp__supabase__list_tables();
@@ -362,6 +378,8 @@ const docs = await mcp__context7__query_docs({
 
 ### GitHub: Code Search Across Repo
 
+> **v4 config:** Docker — `{ "command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"] }`. Requires Docker Desktop.
+
 ```javascript
 // Find patterns in large codebase during Phase 2
 const results = await mcp__github__search_code({

package/framework/templates/docs/onboarding.md

@@ -97,8 +97,8 @@ morph-spec doctor
 │       ├── 0-proposal/
 │       ├── 1-design/
 │       ├── 2-ui/
-│       ├── 3-tasks/
-│       └── 4-implement/
+│       ├── 4-tasks/
+│       └── 5-implement/
 └── .claude/
     ├── commands/                  # Slash commands
     ├── skills/                    # Workflow skills

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "description": "MORPH-SPEC: AI-First development framework with validation pipeline and multi-stack support",
   "keywords": [
     "claude-code",
@@ -47,7 +47,6 @@
     "docs": "jsdoc -c jsdoc.json",
     "docs:watch": "jsdoc -c jsdoc.json --watch",
     "docs:serve": "npx http-server docs/api -p 8080 -o",
-    "version:bump": "node scripts/bump-version.js",
     "release": "node scripts/release.js",
     "postinstall": "node src/scripts/global-install.js"
   },

package/src/commands/agents/dispatch-agents.js

@@ -124,6 +124,51 @@ export function buildSkillsBlock(phase, phasesData) {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// MCP Awareness Injection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Build an MCP availability block for the given phase.
+ * Reads recommendedMCPs from phases.json and MCP usage info from mcp-registry.json.
+ * Returns null if no MCPs recommended for this phase.
+ *
+ * @param {string} phase - Phase id (e.g. 'implement')
+ * @param {Object|null} phasesData - Parsed phases.json content
+ * @param {Object} [opts] - Options
+ * @param {string} [opts.registryPath] - Override path to mcp-registry.json
+ * @returns {string|null}
+ */
+export function buildMcpBlock(phase, phasesData, opts = {}) {
+  try {
+    const mcps = phasesData?.phases?.[phase]?.recommendedMCPs;
+    if (!mcps || mcps.length === 0) return null;
+
+    // Try to load registry for usage descriptions
+    let registry = null;
+    const registryPath = opts.registryPath || join(__dirname, '../../../framework/skills/level-0-meta/mcp-registry.json');
+    try {
+      if (existsSync(registryPath)) {
+        registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+      }
+    } catch { /* non-blocking */ }
+
+    const lines = mcps.map(name => {
+      const usage = registry?.mcps?.[name]?.usage || '';
+      return usage ? `- ${name}: ${usage}` : `- ${name}`;
+    });
+
+    return [
+      `Available MCPs for ${phase} phase:`,
+      ...lines,
+      '',
+      'Use MCP tools when available; fall back to native tools (Bash, Read, Grep) when not.',
+    ].join('\n');
+  } catch {
+    return null;
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
@@ -201,7 +246,7 @@ export function parseAndGroupTasks(tasksPath) {
     const groups = {};
 
     // Match task headings: ### T001 — Title  or  ### T001: Title
-    const taskHeadingRe = /^###\s+(T\d{3,})\s*[—:\-]\s*(.+)$/gm;
+    const taskHeadingRe = /^###\s+(T\d{3,})\s*[—–:\-]\s*(.+)$/gm;
     // Match category line within a task block: **category**: `domain`  or  - category: application
     const categoryRe = /(?:\*\*category\*\*\s*:\s*`?([a-z-]+)`?|category:\s*([a-z-]+))/i;
 
@@ -344,13 +389,15 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
       rawPrompt = agentData.teammate.spawn_prompt;
     }
 
-    // Append standards digest as Constraints block, then required skills block
+    // Append standards digest as Constraints block, then skills block, then MCP block
     const briefing = buildAgentBriefing(agentId, phase);
     const skillsBlock = buildSkillsBlock(phase, phasesData);
+    const mcpBlock = buildMcpBlock(phase, phasesData);
     const fullTaskPrompt = [
       rawPrompt,
       briefing    ? `\n\nConstraints:\n${briefing}` : '',
       skillsBlock ? `\n\n${skillsBlock}`            : '',
+      mcpBlock    ? `\n\n${mcpBlock}`               : '',
     ].join('');
 
     dispatchableAgents.push({
@@ -398,7 +445,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
   if (phase === 'implement') {
     // Group tasks from tasks.md by domain category
-    const tasksPath = join(projectPath, `.morph/features/${featureName}/3-tasks/tasks.md`);
+    const tasksPath = join(projectPath, `.morph/features/${featureName}/4-tasks/tasks.md`);
     const tasksByGroup = parseAndGroupTasks(tasksPath);
 
     for (const [group, taskIds] of Object.entries(tasksByGroup)) {

package/src/commands/mcp/mcp-setup.js

@@ -19,7 +19,8 @@ import {
   installMcpWithCredentials,
   generateSetupInstructions,
   formatMcpStatusTable,
-  loadMcpRegistry
+  loadMcpRegistry,
+  isRemoteMcp
 } from '../../lib/installers/mcp-installer.js';
 import { detectClaudeConfig } from '../../lib/detectors/claude-config-detector.js';
 import { detectProject } from '../../lib/detectors/index.js';
@@ -187,7 +188,43 @@ async function setupSpecificMcp(targetPath, name, stack, existingMcps) {
     return;
   }
 
-  // Needs credentials
+  // Remote HTTP MCP — show setup command and optionally auto-configure
+  if (isRemoteMcp(mcpEntry.install.config)) {
+    console.log(chalk.cyan(`\n  Setting up ${name} MCP (remote)\n`));
+    console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
+    console.log('');
+
+    const instructions = generateSetupInstructions(name, mcpEntry);
+    console.log(chalk.white(`  Run this command to add the MCP:`));
+    console.log(chalk.cyan(`  ${instructions.cliCommand}`));
+    console.log('');
+
+    for (const warning of mcpEntry.install.warnings || []) {
+      console.log(chalk.yellow(`  ⚠ ${warning}`));
+    }
+
+    const { installNow } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'installNow',
+      message: 'Add to .claude/settings.local.json now?',
+      default: true
+    }]);
+
+    if (installNow) {
+      const spinner = ora(`Configuring ${name}...`).start();
+      const result = await installAutoMcps(targetPath, { [name]: mcpEntry });
+      if (result.added.length > 0) {
+        spinner.succeed(`${name} MCP configured (authenticate via /mcp in Claude Code)`);
+      } else {
+        spinner.info(`${name} MCP already configured`);
+      }
+    }
+
+    console.log('');
+    return;
+  }
+
+  // Needs credentials (stdio MCPs)
   console.log(chalk.cyan(`\n  Setting up ${name} MCP\n`));
   console.log(chalk.gray(`  Usage: ${mcpEntry.usage}`));
   console.log('');

package/src/commands/phase/phase-reset.js

@@ -0,0 +1,74 @@
+/**
+ * MORPH-SPEC Phase Reset Command
+ *
+ * Recovery tool for corrupted phase state.
+ * Sets the phase directly without approval gate checks.
+ *
+ * Usage:
+ *   morph-spec phase reset <feature> <phase>
+ */
+
+import chalk from 'chalk';
+import { loadState, saveState, derivePhase } from '../../core/state/state-manager.js';
+import { join } from 'path';
+
+const VALID_PHASES = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'plan', 'tasks', 'implement', 'sync'];
+
+/**
+ * Core reset logic — exported for testing.
+ * @param {string} featureName
+ * @param {string} targetPhase
+ * @returns {{ success: boolean, error?: string, derivedPhase?: string }}
+ */
+export function resetPhase(featureName, targetPhase) {
+  if (!VALID_PHASES.includes(targetPhase)) {
+    return {
+      success: false,
+      error: `Unknown phase: "${targetPhase}". Valid phases: ${VALID_PHASES.join(', ')}`
+    };
+  }
+
+  const state = loadState();
+  if (!state?.features?.[featureName]) {
+    return {
+      success: false,
+      error: `Feature "${featureName}" not found in state.json`
+    };
+  }
+
+  // Get filesystem-derived phase for comparison
+  const featureFolderPath = join(process.cwd(), '.morph', 'features', featureName);
+  const derivedPhase = derivePhase(featureFolderPath);
+
+  // Set phase directly — no approval gate checks
+  state.features[featureName].phase = targetPhase;
+  state.features[featureName].updatedAt = new Date().toISOString();
+  saveState(state);
+
+  return { success: true, derivedPhase };
+}
+
+/**
+ * CLI command handler
+ */
+export async function phaseResetCommand(feature, phase) {
+  console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan('║     MORPH-SPEC PHASE RESET                     ║'));
+  console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
+
+  const result = resetPhase(feature, phase);
+
+  if (!result.success) {
+    console.log(chalk.red(`\n✗ ${result.error}`));
+    process.exit(1);
+  }
+
+  console.log(chalk.green(`✓ Phase reset to "${phase}" for feature "${feature}"`));
+
+  if (result.derivedPhase !== phase) {
+    console.log(chalk.yellow(`\n⚠ Filesystem-derived phase is "${result.derivedPhase}" (folders on disk differ from state)`));
+    console.log(chalk.gray(`  This is expected during recovery. The state.json value takes priority.`));
+  }
+
+  console.log('');
+}

package/src/commands/project/doctor.js

@@ -84,7 +84,11 @@ const REQUIRED_COMMAND_FILES = [
   'src/commands/validation/validate-feature.js',
   'src/commands/templates/template-render.js',
   'src/commands/agents/dispatch-agents.js',
-  'src/commands/project/worktree.js'
+  'src/commands/project/worktree.js',
+  'src/commands/phase/phase-reset.js',
+  'src/commands/scope/escalate.js',
+  'src/commands/task/expand.js',
+  'src/lib/scope/impact-analyzer.js'
 ];
 
 // framework standards
@@ -296,10 +300,18 @@ async function doctorMcpCommand(targetPath) {
   for (const [name, config] of Object.entries(allMcpServers)) {
     const issues = [];
     let status = 'ok';
+    let isRemote = false;
 
-    // ── 1. Binary check ────────────────────────────────────────────────────
+    // ── 0. Remote MCP detection ────────────────────────────────────────────
+    // Remote MCPs use HTTP transport (type: "http" or url property) — no binary to check
+    if (config.type === 'http' || (config.url && !config.command)) {
+      isRemote = true;
+      // Remote MCPs are always "ok" from a config perspective — auth happens at runtime
+    }
+
+    // ── 1. Binary check (stdio MCPs only) ──────────────────────────────────
     const cmd = config.command || '';
-    if (cmd && !KNOWN_RUNTIMES.has(cmd)) {
+    if (!isRemote && cmd && !KNOWN_RUNTIMES.has(cmd)) {
       try {
         execSync(isWindows ? `where "${cmd}"` : `which "${cmd}"`, { stdio: 'ignore' });
       } catch {
@@ -329,12 +341,14 @@ async function doctorMcpCommand(targetPath) {
       }
     }
 
-    checks.push({ name, status, issues, cmd });
+    checks.push({ name, status, issues, cmd, isRemote });
   }
 
   // ── Display ────────────────────────────────────────────────────────────────
   for (const c of checks) {
-    const typeLabel = c.cmd ? chalk.gray(` [${c.cmd}]`) : '';
+    const typeLabel = c.isRemote
+      ? chalk.gray(` [remote: ${allMcpServers[c.name]?.url || 'http'}]`)
+      : c.cmd ? chalk.gray(` [${c.cmd}]`) : '';
 
     if (c.status === 'ok') {
       console.log(chalk.green(`  ✓ ${c.name}`) + typeLabel);