@polymorphism-tech/morph-spec 4.7.1 → 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

@@ -56,7 +56,7 @@
 proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
 ```
 
-Use `morph-spec state show {feature}` to see current phase and pending approval gates.
+Use `morph-spec status {feature}` to see current phase and pending approval gates.
 
 ---
 
@@ -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/
@@ -47,13 +45,13 @@ framework/hooks/
 |-------|------|------|---------|
 | **SessionStart** | inject-morph-context.js | Inject context | Shows active feature, phase, pending approvals |
 | **UserPromptSubmit** | enrich-prompt.js | Inject context | Warns about wrong-phase work, injects commands |
-| **PreToolUse** (Write\|Edit) | protect-readonly-files.js | Block | Blocks edits to state.json and .morph/framework/ |
+| **PreToolUse** (Write\|Edit) | _(native permissions.deny)_ | Block | Blocks edits to state.json and .morph/framework/ |
 | **PreToolUse** (Write\|Edit) | protect-spec-files.js | Block | Blocks edits to spec files after approval |
 | **PreToolUse** (Write\|Edit) | enforce-phase-writes.js | Block | Ensures writes go to current phase directory |
 | **PreToolUse** (Bash) | _(prompt-type inline guard)_ | Block | Blocks `rm -rf .morph/` and direct state edits via Claude's reasoning |
-| **PostToolUse** (Write) | track-output-creation.js | Auto-state | Marks outputs as created when files are written |
 | **PostToolUse** (Bash) | dispatch.js | Dispatch | Triggers checkpoints on task completion |
-| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/outputs |
+| **PostToolUseFailure** | handle-tool-failure.js | Logging | Appends structured JSON to .morph/logs/tool-failures.log |
+| **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/pending gates |
 | **PreCompact** | save-morph-context.js | Snapshot | Saves state to .morph/memory/ before compaction |
 | **Notification** | approval-reminder.js | Advisory | Reminds about pending approval gates |
 
@@ -69,6 +67,10 @@ framework/hooks/
 
 Hooks are automatically installed by `morph-spec init` and updated by `morph-spec update`.
 
+During init/update, the entire `framework/hooks/` directory is copied to `.morph/framework/hooks/`.
+Hook commands in `.claude/settings.local.json` reference `$CLAUDE_PROJECT_DIR/.morph/framework/hooks/`
+so they work correctly in any project regardless of how morph-spec was installed.
+
 The installer writes to `.claude/settings.local.json`:
 
 ```json
@@ -81,7 +83,6 @@ The installer writes to `.claude/settings.local.json`:
       { "matcher": "Bash", "hooks": [...] }
     ],
     "PostToolUse": [
-      { "matcher": "Write", "hooks": [...] },
       { "matcher": "Bash", "hooks": [...] }
     ],
     "Stop": [{ "hooks": [...] }],
@@ -122,10 +123,10 @@ Claude calls Write/Edit tool
     ↓
 Claude Code sends JSON to stdin: { tool_input: { file_path: "..." } }
     ↓
-protect-readonly-files.js
+[native permissions.deny]
     ├── Is .morph/state.json? → BLOCK (use CLI)
     ├── Is .morph/framework/**? → BLOCK (read-only)
-    └── Other → pass
+    └── Other → continue
     ↓
 protect-spec-files.js
     ├── Is in .morph/features/{feature}/?
@@ -198,4 +199,4 @@ morph-spec doctor --reset
 
 ---
 
-*MORPH-SPEC v4.3.7 — Hooks Architecture v2*
+*MORPH-SPEC by Polymorphism Tech — Hooks Architecture v2.5*

package/framework/hooks/claude-code/notification/approval-reminder.js

@@ -26,6 +26,8 @@ try {
 
   // Only remind about gates relevant to the current phase
   const phaseGateRelevance = {
+    proposal: ['proposal'],
+    setup: ['proposal'],
     design: ['design'],
     clarify: ['design'],
     tasks: ['design', 'tasks'],

package/framework/hooks/claude-code/post-tool-use/dispatch.js

@@ -46,7 +46,7 @@ function dispatch(command) {
         const completed = (feature.tasks.completed || 0) + 1; // +1 because task-done hasn't executed yet
         if (completed > 0 && completed % 3 === 0) {
           const checkpointNum = Math.floor(completed / 3);
-          run(`node bin/morph-spec.js checkpoint-save ${featureName} --note "Auto-checkpoint #${checkpointNum} at task ${completed}"`);
+          run(`morph-spec checkpoint-save ${featureName} --note "Auto-checkpoint #${checkpointNum} at task ${completed}"`);
         }
       }
     } catch {

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/claude-code/stop/validate-completion.js

@@ -58,7 +58,7 @@ try {
   // Check pending approval gates
   if (feature.approvalGates) {
     const pendingGates = Object.entries(feature.approvalGates)
-      .filter(([, gate]) => !gate.approved && gate.timestamp === null)
+      .filter(([, gate]) => !gate.approved && !gate.timestamp)
       .map(([name]) => name);
 
     // Only warn about gates relevant to current/past phases

package/framework/hooks/claude-code/user-prompt/enrich-prompt.js

@@ -24,7 +24,7 @@ try {
   const payload = await readStdin();
   if (!payload) pass();
 
-  const userPrompt = payload?.user_prompt || payload?.content || '';
+  const userPrompt = payload?.prompt || payload?.user_prompt || payload?.content || '';
   if (!userPrompt || userPrompt.length < 3) pass();
 
   const promptLower = userPrompt.toLowerCase();