@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

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

@@ -0,0 +1,71 @@
+# 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

@@ -0,0 +1,298 @@
+# 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/framework/CLAUDE.md

@@ -74,4 +74,4 @@ MCP tools load on-demand instead of all at startup — keeps context clean for a
 
 ---
 
-*MORPH-SPEC v4.5.0 by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech*

package/framework/commands/morph-proposal.md

@@ -22,9 +22,9 @@ npx morph-spec state get {feature-name}
 ### Workflow
 
 1. **Detecte agentes automaticamente:**
-   ```bash
-   npx morph-spec detect-agents "$ARGUMENTS"
-   ```
+   - Read `.morph/framework/agents.json`
+   - Para cada agente, compare `domains` e `keywords` com a feature solicitada
+   - Registre os agentes relevantes: `npx morph-spec state add-agent {feature-name} {agent-id}`
 
 2. **Invoque skills dos agentes detectados:**
    - Para agentes com `skillPath` em agents.json, consulte o Skill correspondente

package/framework/hooks/README.md

@@ -12,12 +12,10 @@ framework/hooks/
 │   ├── user-prompt/
 │   │   └── enrich-prompt.js         # Context-aware prompt enrichment
 │   ├── pre-tool-use/
-│   │   ├── protect-readonly-files.js # Block edits to state.json & framework/
 │   │   ├── protect-spec-files.js    # Block edits to approved spec artifacts
 │   │   └── enforce-phase-writes.js  # Enforce writes to correct phase dir
 │   ├── post-tool-use/
-│   │   ├── track-output-creation.js # Auto-mark outputs as created
-│   │   └── dispatch.js              # Dispatch on CLI commands
+│   │   └── dispatch.js              # Dispatch on CLI commands (auto-checkpoint)
 │   ├── stop/
 │   │   └── validate-completion.js   # Advisory: warn about incomplete work
 │   ├── pre-compact/
@@ -85,7 +83,6 @@ The installer writes to `.claude/settings.local.json`:
       { "matcher": "Bash", "hooks": [...] }
     ],
     "PostToolUse": [
-      { "matcher": "Write", "hooks": [...] },
       { "matcher": "Bash", "hooks": [...] }
     ],
     "Stop": [{ "hooks": [...] }],
@@ -202,4 +199,4 @@ morph-spec doctor --reset
 
 ---
 
-*MORPH-SPEC v4.5.0 — Hooks Architecture v2.5*
+*MORPH-SPEC by Polymorphism Tech — Hooks Architecture v2.5*

package/framework/hooks/claude-code/pre-tool-use/protect-readonly-files.js

@@ -1,58 +1,7 @@
 #!/usr/bin/env node
-
 /**
- * PreToolUse Hook: Protect state.json & Framework Files
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Blocks direct edits to:
- *   - .morph/state.json → must use CLI commands
- *   - .morph/framework/** → read-only framework files
- *
- * Fail-open: exits 0 on any error.
+ * DEPRECATED — This hook has been replaced by native permissions.deny in settings.local.json.
+ * The file is kept as an empty stub. It is NOT registered in hooks-installer.js.
+ * Safe to delete.
  */
-
-import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists } from '../../shared/state-reader.js';
-import { isStatePath, isFrameworkPath } from '../../shared/phase-utils.js';
-import { block, pass } from '../../shared/hook-response.js';
-
-try {
-  // Skip if not a morph-spec project
-  if (!stateExists()) {
-    pass();
-  }
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const filePath = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
-  if (!filePath) pass();
-
-  // Block edits to state.json
-  if (isStatePath(filePath)) {
-    block(
-      'MORPH-SPEC: Direct edits to .morph/state.json are blocked.\n' +
-      'Use CLI commands instead:\n' +
-      '  morph-spec state set <feature> <key> <value>\n' +
-      '  morph-spec phase advance <feature>\n' +
-      '  morph-spec task done <feature> <taskId>\n' +
-      '  morph-spec approve <feature> <gate>'
-    );
-  }
-
-  // Block edits to framework files
-  if (isFrameworkPath(filePath)) {
-    block(
-      'MORPH-SPEC: Files in .morph/framework/ are read-only.\n' +
-      'These files are managed by the framework and overwritten on update.\n' +
-      'To customize, create project-specific overrides in .morph/context/ or .morph/config/.'
-    );
-  }
-
-  // All other files are allowed
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
-}
+process.exit(0);

package/framework/hooks/claude-code/session-start/inject-morph-context.js

@@ -11,13 +11,26 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { loadState, getActiveFeature, getPendingGates, getMissingOutputs } from '../../shared/state-reader.js';
+import { loadState, getActiveFeature, getPendingGates, getMissingOutputs, derivePhaseForFeature } from '../../shared/state-reader.js';
 import { stateExists } from '../../shared/state-reader.js';
 import { injectContext, pass } from '../../shared/hook-response.js';
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 
-const SPEC_MAX_CHARS = 3000;
+const DEFAULT_SPEC_MAX_CHARS = 3000;
+
+function getSpecMaxChars() {
+  try {
+    const configPath = join(process.cwd(), '.morph/config/config.json');
+    if (!existsSync(configPath)) return DEFAULT_SPEC_MAX_CHARS;
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return cfg?.hooks?.specInjectionLimit ?? DEFAULT_SPEC_MAX_CHARS;
+  } catch {
+    return DEFAULT_SPEC_MAX_CHARS;
+  }
+}
+
+const SPEC_MAX_CHARS = getSpecMaxChars();
 
 try {
   if (!stateExists()) pass();
@@ -30,7 +43,8 @@ try {
 
   if (active) {
     const { name, feature } = active;
-    lines.push(`- Active feature: ${name} (phase: ${feature.phase}, workflow: ${feature.workflow || 'auto'})`);
+    const phase = derivePhaseForFeature(name);
+    lines.push(`- Active feature: ${name} (phase: ${phase}, workflow: ${feature.workflow || 'auto'})`);
     lines.push(`- Status: ${feature.status}`);
 
     // Task progress
@@ -78,8 +92,9 @@ try {
     const featureNames = Object.keys(state.features);
     lines.push(`- Features: ${featureNames.length} (${featureNames.join(', ')})`);
 
-    for (const [name, feature] of Object.entries(state.features)) {
-      lines.push(`  - ${name}: phase=${feature.phase}, status=${feature.status}`);
+    for (const [fname, feat] of Object.entries(state.features)) {
+      const fPhase = derivePhaseForFeature(fname);
+      lines.push(`  - ${fname}: phase=${fPhase}, status=${feat.status}`);
     }
   }
 

package/framework/hooks/claude-code/statusline.py

@@ -347,7 +347,12 @@ def get_session_name(entries):
 def get_block_start(transcript_path, entries):
     """Find start of current 5-hour billing block. Cached per transcript."""
     h = hashlib.sha256(transcript_path.encode()).hexdigest()[:16]
-    cache_dir  = Path.home() / '.cache' / 'morph-spec'
+    # Use platform-appropriate cache directory
+    if os.name == 'nt':
+        base = Path(os.environ.get('LOCALAPPDATA', str(Path.home() / 'AppData' / 'Local')))
+        cache_dir = base / 'morph-spec' / 'cache'
+    else:
+        cache_dir = Path.home() / '.cache' / 'morph-spec'
     cache_file = cache_dir / f'block-{h}.json'
     now        = time.time()
     block_s    = 5 * 3600

package/framework/hooks/dev/check-sync-health.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * Dev Stop Hook: Sync Health Check (Advisory)
+ *
+ * Event: Stop
+ * Scope: Framework codebase only (dev hook)
+ *
+ * When Claude stops, checks for out-of-sync conditions:
+ *   1. Templates not in REGISTRY.json
+ *   2. Standards not in STANDARDS.json
+ *
+ * Uses readdirSync (no git dependency, fast).
+ * Returns advisory context if out-of-sync items found.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { injectContext, pass } from '../shared/hook-response.js';
+
+/**
+ * Recursively collect .md files from a directory.
+ * @param {string} dir - Directory to scan
+ * @param {string} [base] - Base path for relative paths
+ * @returns {string[]} Relative paths
+ */
+function collectMdFiles(dir, base) {
+  base = base || dir;
+  const results = [];
+  if (!existsSync(dir)) return results;
+
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules') continue;
+        results.push(...collectMdFiles(fullPath, base));
+      } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
+        const rel = fullPath.replace(base + '/', '').replace(base + '\\', '').replace(/\\/g, '/');
+        results.push(rel);
+      }
+    }
+  } catch {
+    // Fail-open
+  }
+
+  return results;
+}
+
+try {
+  // Prevent infinite loop
+  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+
+  const warnings = [];
+
+  // Check templates vs REGISTRY.json
+  const registryPath = 'framework/templates/REGISTRY.json';
+  if (existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+      const registeredPaths = new Set((registry.templates || []).map(t => t.path));
+      const templateFiles = collectMdFiles('framework/templates');
+
+      const unregistered = templateFiles.filter(f => !registeredPaths.has(f));
+      if (unregistered.length > 0) {
+        warnings.push(`Templates not in REGISTRY.json (${unregistered.length}):`);
+        for (const f of unregistered.slice(0, 5)) {
+          warnings.push(`  - ${f}`);
+        }
+        if (unregistered.length > 5) {
+          warnings.push(`  ... and ${unregistered.length - 5} more`);
+        }
+      }
+    } catch {
+      // Skip on error
+    }
+  }
+
+  // Check standards vs STANDARDS.json
+  const standardsPath = 'framework/standards/STANDARDS.json';
+  if (existsSync(standardsPath)) {
+    try {
+      const registry = JSON.parse(readFileSync(standardsPath, 'utf-8'));
+      const registeredPaths = new Set((registry.standards || []).map(s => s.path));
+      const standardFiles = collectMdFiles('framework/standards');
+
+      const unregistered = standardFiles.filter(f => !registeredPaths.has(f));
+      if (unregistered.length > 0) {
+        warnings.push(`Standards not in STANDARDS.json (${unregistered.length}):`);
+        for (const f of unregistered.slice(0, 5)) {
+          warnings.push(`  - ${f}`);
+        }
+        if (unregistered.length > 5) {
+          warnings.push(`  ... and ${unregistered.length - 5} more`);
+        }
+        warnings.push('  Run: node scripts/generate-standards-registry.js');
+      }
+    } catch {
+      // Skip on error
+    }
+  }
+
+  if (warnings.length === 0) pass();
+
+  const message = [
+    'MORPH-SPEC Dev: Out-of-sync items detected:',
+    ...warnings.map(w => `  ${w}`),
+  ].join('\n');
+
+  injectContext(message);
+} catch {
+  // Fail-open
+  process.exit(0);
+}