@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

package/docs/plans/2026-02-24-tutorial-command-design.md

@@ -1,71 +0,0 @@
-# Design: `morph-spec tutorial` Command
-
-**Status:** COMPLETE (see implementation plan)
-
-**Date:** 2026-02-24
-
----
-
-## Problem
-
-After `morph-spec init`, first-time users see a suggestion to run `morph-spec tutorial`, but the command doesn't exist. New users also lack a quick way to understand the spec-first workflow and its phase pipeline.
-
----
-
-## Goal
-
-A self-contained CLI command that teaches the MORPH-SPEC mental model: the phase pipeline, what each phase produces, and how to trigger each phase. Pure stdout, no side effects.
-
----
-
-## Approach: Workflow Walkthrough
-
-A static, colored terminal output that explains the full pipeline top-to-bottom. No arguments, no options, no network calls, no file I/O.
-
-Chosen over:
-- **Interactive mode** — risks accidentally modifying project state
-- **Quick reference** — duplicates `--help` with little added value
-
----
-
-## Output Structure
-
-1. **Header** — title + one-sentence philosophy
-2. **Pipeline diagram** — ASCII showing phase sequence with optional phases bracketed
-3. **Per-phase block** — for each of the 8 phases:
-   - Phase name + number
-   - What it does (1 sentence)
-   - What it produces (output files)
-   - How to trigger it (CLI command or `/slash-command` in Claude Code)
-4. **Getting Started** — 3-step CTA ending with `morph-spec doctor` tip
-
----
-
-## Implementation
-
-| Item | Detail |
-|------|--------|
-| File | `src/commands/project/tutorial.js` |
-| Export | `tutorialCommand` |
-| Registration (index) | `src/commands/project/index.js` |
-| Registration (bin) | `bin/morph-spec.js` |
-| Dependencies | `chalk` (already installed) |
-| Side effects | None — pure stdout |
-| Size | ~100 lines |
-
-Also: revert `init.js:518` back to `morph-spec tutorial` (the original intent).
-
----
-
-## Phases Covered
-
-| Phase | Trigger |
-|-------|---------|
-| 0 · Proposal | `/morph-proposal <feature>` |
-| 1 · Setup | auto-triggered inside `/morph-proposal` |
-| 1.5 · UI/UX (optional) | `/phase-uiux <feature>` |
-| 2 · Design | `/phase-design <feature>` |
-| 3 · Clarify | `/phase-clarify <feature>` |
-| 4 · Tasks | auto-generated, or `/phase-tasks <feature>` |
-| 5 · Implement | `/morph-apply <feature>` |
-| 6 · Sync (optional) | `morph-spec sync <feature>` |

package/docs/plans/2026-02-24-tutorial-command.md

@@ -1,298 +0,0 @@
-# Tutorial Command Implementation Plan
-
-**Status:** COMPLETE
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add a `morph-spec tutorial` command that prints the full MORPH-SPEC phase pipeline and getting-started steps to stdout.
-
-**Architecture:** Single new file `src/commands/project/tutorial.js` exporting `tutorialCommand`. Registered in `bin/morph-spec.js` and re-exported from `src/commands/project/index.js`. Pure stdout using `chalk` — no file I/O, no network, no side effects. Also reverts `init.js` to suggest `morph-spec tutorial` (instead of the broken replacement made in a prior session).
-
-**Tech Stack:** Node.js ESM, chalk (already installed), node:test + node:assert for tests.
-
----
-
-### Task 1: Create `tutorial.js`
-
-**Files:**
-- Create: `src/commands/project/tutorial.js`
-- Test: `test/commands/tutorial.test.js`
-
-**Step 1: Write the failing test**
-
-Create `test/commands/tutorial.test.js`:
-
-```js
-import { test, describe } from 'node:test';
-import assert from 'node:assert/strict';
-import { tutorialCommand } from '../../src/commands/project/tutorial.js';
-
-describe('tutorialCommand', () => {
-  test('tutorialCommand is a function', () => {
-    assert.equal(typeof tutorialCommand, 'function');
-  });
-
-  test('tutorialCommand runs without throwing', () => {
-    assert.doesNotThrow(() => tutorialCommand());
-  });
-
-  test('tutorialCommand returns undefined (pure side-effect)', () => {
-    const result = tutorialCommand();
-    assert.equal(result, undefined);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-```bash
-node --test test/commands/tutorial.test.js
-```
-Expected: FAIL — "Cannot find module"
-
-**Step 3: Write the implementation**
-
-Create `src/commands/project/tutorial.js`:
-
-```js
-/**
- * Tutorial Command
- *
- * Prints the MORPH-SPEC workflow pipeline and getting-started steps.
- * Pure stdout — no file I/O, no network, no side effects.
- *
- * Usage: morph-spec tutorial
- */
-
-import chalk from 'chalk';
-
-const PHASES = [
-  {
-    label: 'FASE 0 · PROPOSAL',
-    what: 'Captures user story + acceptance criteria.',
-    produces: '0-proposal/proposal.md',
-    how: '/morph-proposal <feature>  (in Claude Code)',
-  },
-  {
-    label: 'FASE 1 · SETUP',
-    what: 'Detects stack, activates agents, confirms environment.',
-    produces: '.morph/state.json initialized',
-    how: 'auto-triggered inside /morph-proposal',
-  },
-  {
-    label: 'FASE 1.5 · UI/UX',
-    what: 'Design system, mockups, component specs, user flows.',
-    produces: '2-ui/{design-system,mockups,components,flows}.md',
-    how: '/phase-uiux <feature>  (in Claude Code)',
-    optional: true,
-  },
-  {
-    label: 'FASE 2 · DESIGN',
-    what: 'Technical spec + C# contracts + architecture decisions.',
-    produces: '1-design/{spec.md, contracts-level{N}.cs, decisions.md}',
-    how: '/phase-design <feature>  (in Claude Code)',
-  },
-  {
-    label: 'FASE 3 · CLARIFY',
-    what: 'Reviews spec for ambiguities, adds edge cases.',
-    produces: '1-design/spec.md (updated with clarifications)',
-    how: '/phase-clarify <feature>  (in Claude Code)',
-  },
-  {
-    label: 'FASE 4 · TASKS',
-    what: 'Atomic task breakdown, DDD-aware.',
-    produces: '3-tasks/tasks.md',
-    how: 'auto-generated during /morph-proposal, or /phase-tasks <feature>',
-  },
-  {
-    label: 'FASE 5 · IMPLEMENT',
-    what: 'Code implementation with checkpoints every 3 tasks.',
-    produces: '4-implement/recap.md + source code',
-    how: '/morph-apply <feature>  (in Claude Code)',
-  },
-  {
-    label: 'FASE 6 · SYNC',
-    what: 'Syncs decisions back to project standards.',
-    produces: '.morph/framework/standards/ (updated)',
-    how: 'morph-spec sync <feature>',
-    optional: true,
-  },
-];
-
-const SEP = chalk.dim('─'.repeat(58));
-
-export function tutorialCommand() {
-  console.log('');
-  console.log(chalk.cyan.bold('  MORPH-SPEC Workflow Tutorial'));
-  console.log(SEP);
-  console.log('');
-  console.log(
-    chalk.white(
-      '  MORPH-SPEC is spec-first: every feature goes through phases\n' +
-      '  before any code is written. Each phase produces structured\n' +
-      '  outputs that feed the next.'
-    )
-  );
-  console.log('');
-  console.log(SEP);
-  console.log(chalk.cyan.bold('  PIPELINE'));
-  console.log(SEP);
-  console.log('');
-  console.log(
-    chalk.white('  proposal → setup → ') +
-    chalk.dim('[uiux]') +
-    chalk.white(' → design → clarify → tasks → implement → ') +
-    chalk.dim('[sync]')
-  );
-  console.log(chalk.dim('  (phases in brackets are optional)'));
-  console.log('');
-
-  for (const phase of PHASES) {
-    console.log(SEP);
-    const label = phase.optional
-      ? chalk.cyan.bold(`  ${phase.label}`) + chalk.dim('  [optional]')
-      : chalk.cyan.bold(`  ${phase.label}`);
-    console.log(label);
-    console.log(chalk.white(`  What:     ${phase.what}`));
-    console.log(chalk.dim(`  Produces: ${phase.produces}`));
-    console.log(chalk.green(`  How:      ${phase.how}`));
-    console.log('');
-  }
-
-  console.log(SEP);
-  console.log(chalk.cyan.bold('  GETTING STARTED'));
-  console.log(SEP);
-  console.log('');
-  console.log(chalk.white('  1. Open Claude Code in your project'));
-  console.log(chalk.white('  2. Run:  ') + chalk.green('/morph-proposal <your-feature-name>'));
-  console.log(chalk.white('  3. Answer the questions — morph-spec handles the rest'));
-  console.log('');
-  console.log(chalk.dim('  Tip: run `morph-spec doctor` to verify your installation first.'));
-  console.log('');
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-```bash
-node --test test/commands/tutorial.test.js
-```
-Expected: 3 passing
-
-**Step 5: Commit**
-
-```bash
-git add src/commands/project/tutorial.js test/commands/tutorial.test.js
-git commit -m "feat(tutorial): add tutorial command with phase pipeline walkthrough"
-```
-
----
-
-### Task 2: Wire into project index and bin
-
-**Files:**
-- Modify: `src/commands/project/index.js`
-- Modify: `bin/morph-spec.js`
-
-**Step 1: Add export to `src/commands/project/index.js`**
-
-After the existing `export { updateCommand }` line, add:
-
-```js
-export { tutorialCommand } from './tutorial.js';
-```
-
-**Step 2: Add import to `bin/morph-spec.js`**
-
-After the `import { doctorCommand }` line (line ~13), add:
-
-```js
-import { tutorialCommand } from '../src/commands/project/tutorial.js';
-```
-
-**Step 3: Register the command in `bin/morph-spec.js`**
-
-After the `doctor` command block (~line 128), add:
-
-```js
-program
-  .command('tutorial')
-  .description('Learn the MORPH-SPEC workflow — phase pipeline and getting started')
-  .action(tutorialCommand);
-```
-
-**Step 4: Smoke-test the CLI**
-
-```bash
-node bin/morph-spec.js tutorial
-```
-Expected: Full pipeline output printed to terminal without errors.
-
-```bash
-node bin/morph-spec.js --help | grep tutorial
-```
-Expected: `tutorial   Learn the MORPH-SPEC workflow...`
-
-**Step 5: Commit**
-
-```bash
-git add src/commands/project/index.js bin/morph-spec.js
-git commit -m "feat(tutorial): register tutorial command in CLI"
-```
-
----
-
-### Task 3: Restore the `init.js` suggestion message
-
-**Files:**
-- Modify: `src/commands/project/init.js:518`
-
-**Step 1: Revert the message**
-
-Find line 518 in `src/commands/project/init.js`. Replace:
-
-```js
-logger.info('First time using morph-spec? Run `morph-spec doctor` to verify your setup, then `/morph-proposal <feature>` to start.');
-```
-
-With:
-
-```js
-logger.info('First time using morph-spec? Run `morph-spec tutorial` to get started.');
-```
-
-**Step 2: Verify the change**
-
-```bash
-grep -n "tutorial" src/commands/project/init.js
-```
-Expected: line 518 shows `morph-spec tutorial`
-
-**Step 3: Commit**
-
-```bash
-git add src/commands/project/init.js
-git commit -m "fix(init): restore morph-spec tutorial suggestion after command now exists"
-```
-
----
-
-### Task 4: Run full test suite
-
-**Step 1: Run all tests**
-
-```bash
-node --test
-```
-Expected: all existing tests pass + 3 new tutorial tests pass, 0 failures.
-
-**Step 2: If any failures, fix before continuing**
-
-Do not proceed until `node --test` shows 0 failures.
-
-**Step 3: Commit if any fixes were needed**
-
-```bash
-git add -p
-git commit -m "fix(tutorial): address test suite issues"
-```

package/scripts/bump-version.js

@@ -1,248 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Version Bump Script for MORPH-SPEC Framework
- *
- * Updates the version number across all files that contain it.
- * Single source of truth: package.json
- *
- * Usage:
- *   node scripts/bump-version.js patch       # 4.8.0 → 4.8.1
- *   node scripts/bump-version.js minor       # 4.8.0 → 4.9.0
- *   node scripts/bump-version.js major       # 4.8.0 → 5.0.0
- *   node scripts/bump-version.js 4.9.0       # explicit version
- *   node scripts/bump-version.js --dry-run patch  # preview changes
- *
- * npm script:
- *   npm run version:bump -- patch
- *   npm run version:bump -- --dry-run minor
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { glob } from 'glob';
-
-// ── Exported helpers (used by tests) ─────────────────────────────────
-
-/**
- * Compute a new version from a current version and bump type.
- * @param {string} current - Current semver (e.g. "4.8.0")
- * @param {string} type - "patch", "minor", "major", or explicit "X.Y.Z"
- * @returns {string} New version string
- */
-export function bumpVersion(current, type) {
-  const [major, minor, patch] = current.split('.').map(Number);
-  switch (type) {
-    case 'major': return `${major + 1}.0.0`;
-    case 'minor': return `${major}.${minor + 1}.0`;
-    case 'patch': return `${major}.${minor}.${patch + 1}`;
-    default: {
-      if (/^\d+\.\d+\.\d+$/.test(type)) return type;
-      throw new Error(`Invalid version or bump type: "${type}". Expected: patch, minor, major, or X.Y.Z`);
-    }
-  }
-}
-
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Build the list of file updates for a version bump.
- * @param {string} rootDir - Project root directory
- * @param {string} currentVersion - Current version string
- * @param {string} newVersion - Target version string
- * @returns {Array<{file: string, replacements: Array<{pattern: RegExp, replacement: string}>}>}
- */
-export function buildFileUpdates(rootDir, currentVersion, newVersion) {
-  const cv = escapeRegex(currentVersion);
-
-  const updates = [
-    {
-      file: 'package.json',
-      replacements: [
-        { pattern: new RegExp(`"version":\\s*"${cv}"`), replacement: `"version": "${newVersion}"` },
-      ],
-    },
-    {
-      file: 'claude-plugin.json',
-      replacements: [
-        { pattern: new RegExp(`"version":\\s*"${cv}"`), replacement: `"version": "${newVersion}"` },
-      ],
-    },
-    {
-      file: 'README.md',
-      replacements: [
-        { pattern: new RegExp(`\\*\\*Version:\\*\\*\\s*${cv}`), replacement: `**Version:** ${newVersion}` },
-        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
-      ],
-    },
-    {
-      file: 'docs/ARCHITECTURE.md',
-      replacements: [
-        { pattern: new RegExp(`morph-spec v${cv}`, 'g'), replacement: `morph-spec v${newVersion}` },
-      ],
-    },
-    {
-      file: 'docs/CHEATSHEET.md',
-      replacements: [
-        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
-      ],
-    },
-    {
-      file: 'docs/COMMAND-FLOWS.md',
-      replacements: [
-        { pattern: new RegExp(`Version:\\s*${cv}`), replacement: `Version: ${newVersion}` },
-        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
-      ],
-    },
-    {
-      file: 'docs/QUICKSTART.md',
-      replacements: [
-        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
-      ],
-    },
-    {
-      file: 'framework/hooks/dev/guard-version-numbers.js',
-      replacements: [
-        { pattern: new RegExp(`MORPH-SPEC v${cv}`), replacement: `MORPH-SPEC v${newVersion}` },
-      ],
-    },
-  ];
-
-  // Skill files (cliVersion in YAML frontmatter)
-  const skillFiles = glob.sync('framework/skills/level-1-workflows/*/SKILL.md', { cwd: rootDir });
-  for (const sf of skillFiles) {
-    updates.push({
-      file: sf,
-      replacements: [
-        { pattern: new RegExp(`cliVersion:\\s*"${cv}"`), replacement: `cliVersion: "${newVersion}"` },
-      ],
-    });
-  }
-
-  return updates;
-}
-
-/**
- * Apply version updates to files on disk.
- * @param {string} rootDir - Project root directory
- * @param {Array} fileUpdates - From buildFileUpdates()
- * @param {{ dryRun?: boolean }} options
- * @returns {{ updatedCount: number, replacementCount: number, warnings: string[] }}
- */
-export function applyUpdates(rootDir, fileUpdates, { dryRun = false } = {}) {
-  let updatedCount = 0;
-  let replacementCount = 0;
-  const warnings = [];
-
-  for (const { file, replacements } of fileUpdates) {
-    const fullPath = join(rootDir, file);
-
-    if (!existsSync(fullPath)) {
-      warnings.push(`SKIP ${file} (file not found)`);
-      continue;
-    }
-
-    let content = readFileSync(fullPath, 'utf-8');
-    let fileChanged = false;
-
-    for (const { pattern, replacement } of replacements) {
-      if (pattern.test(content)) {
-        content = content.replace(pattern, replacement);
-        fileChanged = true;
-        replacementCount++;
-      }
-    }
-
-    if (fileChanged) {
-      if (!dryRun) {
-        writeFileSync(fullPath, content, 'utf-8');
-      }
-      updatedCount++;
-    } else {
-      warnings.push(`${file} (no matches — pattern may have changed)`);
-    }
-  }
-
-  return { updatedCount, replacementCount, warnings };
-}
-
-// ── CLI entry point ──────────────────────────────────────────────────
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const isMainModule = process.argv[1]?.replace(/\\/g, '/').endsWith('scripts/bump-version.js');
-
-if (isMainModule) {
-  const ROOT = join(__dirname, '..');
-  const args = process.argv.slice(2);
-  const dryRun = args.includes('--dry-run');
-  const filtered = args.filter(a => a !== '--dry-run');
-
-  if (filtered.length === 0) {
-    console.error(
-      'Usage: node scripts/bump-version.js [--dry-run] <patch|minor|major|X.Y.Z>'
-    );
-    process.exit(1);
-  }
-
-  const input = filtered[0];
-  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
-  const currentVersion = pkg.version;
-
-  let newVersion;
-  try {
-    newVersion = bumpVersion(currentVersion, input);
-  } catch (err) {
-    console.error(err.message);
-    process.exit(1);
-  }
-
-  if (newVersion === currentVersion) {
-    console.log(`Version is already ${currentVersion}. Nothing to do.`);
-    process.exit(0);
-  }
-
-  console.log(`\nBumping version: ${currentVersion} → ${newVersion}`);
-  if (dryRun) console.log('(dry run — no files will be modified)\n');
-  else console.log('');
-
-  const fileUpdates = buildFileUpdates(ROOT, currentVersion, newVersion);
-  const result = applyUpdates(ROOT, fileUpdates, { dryRun });
-
-  for (const file of fileUpdates) {
-    const fullPath = join(ROOT, file.file);
-    if (existsSync(fullPath)) {
-      const content = readFileSync(fullPath, 'utf-8');
-      const hasMatch = file.replacements.some(r =>
-        dryRun
-          ? new RegExp(escapeRegex(currentVersion)).test(content)
-          : new RegExp(escapeRegex(newVersion)).test(content)
-      );
-      if (hasMatch) console.log(`  ✓ ${file.file}`);
-    }
-  }
-
-  console.log('');
-  if (result.warnings.length > 0) {
-    console.log('Warnings:');
-    for (const w of result.warnings) console.log(`  ⚠ ${w}`);
-    console.log('');
-  }
-
-  console.log(
-    `${dryRun ? 'Would update' : 'Updated'} ${result.updatedCount} files (${result.replacementCount} replacements).`
-  );
-
-  if (dryRun) {
-    console.log('\nRe-run without --dry-run to apply changes.');
-  } else {
-    console.log(`\nVersion is now ${newVersion}.`);
-    console.log('Next steps:');
-    console.log('  1. Review changes: git diff');
-    console.log(`  2. Commit: git commit -am "chore: bump version to ${newVersion}"`);
-    console.log(`  3. Tag: git tag v${newVersion}`);
-    console.log('  4. Publish: npm publish');
-  }
-}