@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/framework/hooks/dev/guard-version-numbers.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PreToolUse Hook: Guard Version Numbers
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ * Scope: Framework codebase only (dev hook)
+ *
+ * Blocks Write/Edit to files that contain hardcoded version patterns
+ * like "MORPH-SPEC v4.8.1". Version should only be in package.json.
+ *
+ * Checked extensions: .md, .cs, .css, .js (covers templates + source)
+ * Exceptions: CHANGELOG.md, node_modules/, test/, package.json, package-lock.json
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath, getContentToValidate } from '../shared/payload-utils.js';
+import { block, pass } from '../shared/hook-response.js';
+
+const VERSION_PATTERN = /MORPH-SPEC\s+v\d+\.\d+\.\d+/;
+const CHECKED_EXTENSIONS = ['.md', '.cs', '.css', '.js', '.html', '.txt'];
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check relevant file types
+  if (!CHECKED_EXTENSIONS.some(ext => filePath.endsWith(ext))) pass();
+
+  // Exceptions
+  if (filePath.includes('node_modules/')) pass();
+  if (filePath.endsWith('CHANGELOG.md')) pass();
+  if (filePath.includes('test/')) pass();
+  if (filePath.endsWith('package.json')) pass();
+  if (filePath.endsWith('package-lock.json')) pass();
+
+  const content = getContentToValidate(payload);
+  if (!content) pass();
+
+  if (VERSION_PATTERN.test(content)) {
+    block(
+      `MORPH-SPEC: Hardcoded version number detected in '${filePath}'.\n` +
+      `Version should only be in package.json. Use 'MORPH-SPEC by Polymorphism Tech' without version.\n` +
+      `Pattern found: ${content.match(VERSION_PATTERN)?.[0]}`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/sync-standards-registry.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PostToolUse Hook: Standards Registry Sync Advisory
+ *
+ * Event: PostToolUse | Matcher: Write
+ * Scope: Framework codebase only (dev hook)
+ *
+ * After a Write to framework/standards/**/*.md, checks if the file
+ * is registered in framework/standards/STANDARDS.json.
+ * If not, injects an advisory to regenerate the registry.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath } from '../shared/payload-utils.js';
+import { approve, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/standards/**/*.md
+  if (!filePath.includes('framework/standards/')) pass();
+  if (!filePath.endsWith('.md')) pass();
+
+  // Skip meta files
+  const basename = filePath.split('/').pop();
+  if (basename === 'README.md') pass();
+  if (basename === 'STANDARDS.json') pass();
+
+  // Extract relative path from framework/standards/
+  const standardsIdx = filePath.indexOf('framework/standards/');
+  if (standardsIdx === -1) pass();
+  const relativePath = filePath.slice(standardsIdx + 'framework/standards/'.length);
+
+  // Read STANDARDS.json
+  const registryPath = 'framework/standards/STANDARDS.json';
+  if (!existsSync(registryPath)) pass();
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  const registeredPaths = (registry.standards || []).map(s => s.path);
+
+  if (!registeredPaths.includes(relativePath)) {
+    approve(
+      `MORPH-SPEC: Standard '${relativePath}' is not in STANDARDS.json.\n` +
+      `Run: node scripts/generate-standards-registry.js`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/sync-template-registry.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PostToolUse Hook: Template Registry Sync Advisory
+ *
+ * Event: PostToolUse | Matcher: Write
+ * Scope: Framework codebase only (dev hook)
+ *
+ * After a Write to framework/templates/**/*.md, checks if the file
+ * is registered in framework/templates/REGISTRY.json.
+ * If not, injects an advisory to add the entry.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath } from '../shared/payload-utils.js';
+import { approve, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/templates/**/*.md
+  if (!filePath.includes('framework/templates/')) pass();
+  if (!filePath.endsWith('.md')) pass();
+
+  // Skip meta files
+  const basename = filePath.split('/').pop();
+  if (basename === 'README.md') pass();
+  if (basename === 'REGISTRY.json') pass();
+
+  // Extract relative path from framework/templates/
+  const templateIdx = filePath.indexOf('framework/templates/');
+  if (templateIdx === -1) pass();
+  const relativePath = filePath.slice(templateIdx + 'framework/templates/'.length);
+
+  // Read REGISTRY.json
+  const registryPath = 'framework/templates/REGISTRY.json';
+  if (!existsSync(registryPath)) pass();
+
+  const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+  const registeredPaths = (registry.templates || []).map(t => t.path);
+
+  if (!registeredPaths.includes(relativePath)) {
+    approve(
+      `MORPH-SPEC: Template '${relativePath}' is not in REGISTRY.json.\n` +
+      `Add an entry to framework/templates/REGISTRY.json with id, path, phase, and outputName fields.`
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/validate-skill-format.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PreToolUse Hook: Validate Skill Frontmatter Format
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ * Scope: Framework codebase only (dev hook)
+ *
+ * Validates that SKILL.md files written to framework/skills/ have valid
+ * YAML frontmatter with required `name:` and `description:` fields.
+ *
+ * Only validates on Write (full content). Edit operations pass through.
+ * Simple regex parsing (no YAML library dependency).
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath, getContentToValidate, isWriteOperation } from '../shared/payload-utils.js';
+import { block, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/skills/**/SKILL.md
+  if (!filePath.includes('framework/skills/')) pass();
+  if (!filePath.endsWith('SKILL.md')) pass();
+
+  // Only validate full Write operations (not Edit patches)
+  if (!isWriteOperation(payload)) pass();
+
+  const content = getContentToValidate(payload);
+  if (!content) pass();
+
+  // Check for YAML frontmatter delimiters
+  const frontmatterMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!frontmatterMatch) {
+    block(
+      `MORPH-SPEC: SKILL.md at '${filePath}' is missing YAML frontmatter.\n` +
+      'All skill files must start with --- delimited YAML frontmatter containing name: and description: fields.'
+    );
+  }
+
+  const frontmatter = frontmatterMatch[1];
+  const missing = [];
+
+  if (!/^name:/m.test(frontmatter)) {
+    missing.push('name:');
+  }
+  if (!/^description:/m.test(frontmatter)) {
+    missing.push('description:');
+  }
+
+  if (missing.length > 0) {
+    block(
+      `MORPH-SPEC: SKILL.md at '${filePath}' is missing required frontmatter fields:\n` +
+      missing.map(m => `  - ${m}`).join('\n') + '\n\n' +
+      'All skill files must have name: and description: in their YAML frontmatter.'
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/dev/validate-standard-format.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * Dev PreToolUse Hook: Validate Standard Format
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ * Scope: Framework codebase only (dev hook)
+ *
+ * Validates that files written to framework/standards/ follow the required format:
+ *   - `> **Scope:**` metadata header
+ *   - `> **Layer:**` metadata header
+ *   - `> **Keywords:**` metadata header
+ *   - Footer: `*MORPH-SPEC by Polymorphism Tech*`
+ *
+ * Only validates on Write (full content). Edit operations pass through.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readStdin } from '../shared/stdin-reader.js';
+import { getFilePath, getContentToValidate, isWriteOperation } from '../shared/payload-utils.js';
+import { block, pass } from '../shared/hook-response.js';
+
+try {
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check framework/standards/**/*.md
+  if (!filePath.includes('framework/standards/')) pass();
+  if (!filePath.endsWith('.md')) pass();
+
+  // Skip non-standard files
+  const basename = filePath.split('/').pop();
+  if (basename === 'README.md') pass();
+  if (basename === 'STANDARDS.json') pass();
+
+  // Only validate full Write operations (not Edit patches)
+  if (!isWriteOperation(payload)) pass();
+
+  const content = getContentToValidate(payload);
+  if (!content) pass();
+
+  const missing = [];
+
+  if (!/>\s*\*\*Scope:\*\*/.test(content)) {
+    missing.push('> **Scope:** metadata header');
+  }
+  if (!/>\s*\*\*Layer:\*\*/.test(content)) {
+    missing.push('> **Layer:** metadata header');
+  }
+  if (!/>\s*\*\*Keywords:\*\*/.test(content)) {
+    missing.push('> **Keywords:** metadata header');
+  }
+  if (!/\*MORPH-SPEC by Polymorphism Tech\*/.test(content)) {
+    missing.push('Footer: *MORPH-SPEC by Polymorphism Tech*');
+  }
+
+  if (missing.length > 0) {
+    block(
+      `MORPH-SPEC: Standard file '${basename}' is missing required format elements:\n` +
+      missing.map(m => `  - ${m}`).join('\n') + '\n\n' +
+      'All framework standards must include Scope/Layer/Keywords metadata headers and the standard footer.'
+    );
+  }
+
+  pass();
+} catch {
+  // Fail-open
+  process.exit(0);
+}

package/framework/hooks/shared/payload-utils.js

@@ -0,0 +1,39 @@
+/**
+ * Shared payload utilities for Claude Code Write/Edit hooks.
+ *
+ * Extracts file path and content from tool_input payloads,
+ * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
+ */
+
+/**
+ * Get the file path from a hook payload, normalizing backslashes.
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Normalized file path or empty string
+ */
+export function getFilePath(payload) {
+  const raw = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
+  return raw.replace(/\\/g, '/');
+}
+
+/**
+ * Get the content being written or edited.
+ * For Write: returns `content` (full file content).
+ * For Edit: returns `new_string` (replacement text).
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {string} Content string or empty string
+ */
+export function getContentToValidate(payload) {
+  const input = payload?.tool_input;
+  if (!input) return '';
+  // Write tool uses 'content', Edit tool uses 'new_string'
+  return input.content || input.new_string || '';
+}
+
+/**
+ * Check if this is a Write operation (full file content available).
+ * @param {Object} payload - Hook payload from stdin
+ * @returns {boolean} True if Write (content exists), false if Edit or unknown
+ */
+export function isWriteOperation(payload) {
+  return typeof payload?.tool_input?.content === 'string';
+}

package/framework/hooks/shared/state-reader.js

@@ -73,15 +73,39 @@ export function getFeature(featureName, projectPath) {
   return state?.features?.[featureName] || null;
 }
 
+/**
+ * Derive phase from filesystem (v5.0.0+: phase deleted from state).
+ * Checks for phase folders in descending order, returns highest present.
+ * @param {string} featureName
+ * @param {string} [projectPath]
+ * @returns {string} Phase name
+ */
+export function derivePhaseForFeature(featureName, projectPath) {
+  const basePath = join(projectPath || process.cwd(), '.morph/features', featureName);
+  const phaseMap = [
+    ['4-implement', 'implement'],
+    ['3-tasks', 'tasks'],
+    ['2-ui', 'uiux'],
+    ['1-design', 'design'],
+    ['0-proposal', 'proposal'],
+  ];
+  for (const [folder, phase] of phaseMap) {
+    if (existsSync(join(basePath, folder))) return phase;
+  }
+  return 'setup';
+}
+
 /**
  * Get the current phase of a feature.
+ * Falls back to filesystem derivation when phase is not in state (v5.0.0+).
  * @param {string} featureName
  * @param {string} [projectPath]
  * @returns {string|null}
  */
 export function getFeaturePhase(featureName, projectPath) {
   const feature = getFeature(featureName, projectPath);
-  return feature?.phase || null;
+  if (!feature) return null;
+  return feature.phase || derivePhaseForFeature(featureName, projectPath);
 }
 
 /**

package/framework/rules/morph-workflow.md

@@ -58,7 +58,7 @@ Run a checkpoint every 3 completed tasks:
 **Design Gate:** Before moving from Design → Tasks, spec must be approved.
 **Implementation Gate:** Before starting implementation, task list must be approved.
 
-Check approval status: `morph-spec state show {feature}`
+Check approval status: `morph-spec approval-status {feature}`
 
 ---
 

package/framework/skills/level-0-meta/morph-init/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: morph-init
+description: >
+  LLM-powered project initialization. Installs morph-spec infrastructure if
+  needed, auto-installs required plugins (superpowers, context7), analyzes any
+  project structure intelligently, generates rich context/README.md and
+  config.json, and configures MCPs. Use once per project after installing
+  @polymorphism-tech/morph-spec. Re-run with /morph-init refresh to update
+  context as the project evolves.
+argument-hint: "[refresh]"
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# morph-init — LLM-Powered Project Initialization
+
+> Run once after `npm install -g @polymorphism-tech/morph-spec`.
+> Re-run as `/morph-init refresh` when your project evolves.
+
+---
+
+## Step 0 — Required Plugins
+
+Check for required Claude Code plugins: **superpowers** and **context7**.
+
+Read `~/.claude/plugins/installed_plugins.json` and check for:
+- `superpowers@claude-plugins-official`
+- `context7@claude-plugins-official`
+
+For each missing plugin, run:
+
+```bash
+morph-spec install-plugin superpowers
+morph-spec install-plugin context7
+```
+
+**If the command succeeds:** `✓ {plugin} installed. Restart Claude Code after /morph-init completes.`
+
+**If the command fails:** Show this and **STOP** — do not continue:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Plugin {plugin} requires manual installation:              │
+│                                                             │
+│  1. Claude Code → Settings (Cmd/Ctrl+,) → Extensions        │
+│  2. Browse → search "{plugin}" → Install                    │
+│  3. Restart Claude Code                                     │
+│  4. Re-run /morph-init                                      │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Both `superpowers` and `context7` are required. Do not continue if either is missing.
+
+---
+
+## Step 1 — Infrastructure
+
+Check if `.morph/` exists in the current directory.
+
+**If MISSING:**
+```bash
+morph-spec setup-infra
+```
+Output confirms: `✓ MORPH-SPEC infrastructure installed.`
+
+**If EXISTS and argument is `refresh`:** Continue — will overwrite context and config.
+
+**If EXISTS and no argument:**
+Ask: *"MORPH already initialized. Refresh context and config? (y/n)"*
+If `n` → STOP.
+
+---
+
+## Step 2 — Analyze Project
+
+Gather evidence to build a stack map. Run these in parallel:
+
+| Tool | Pattern | Signal |
+|------|---------|--------|
+| `Glob` | `**/package.json` | Detect next, supabase, clerk, stripe in deps |
+| `Glob` | `**/*.csproj` | .NET projects at any depth |
+| `Glob` | `**/next.config.{js,ts,mjs}` | Next.js in any subdirectory |
+| `Glob` | `**/components.json` | shadcn/ui |
+| `Glob` | `**/docker-compose*.yml` | Container services |
+| `Glob` | `database/migrations/**` | Supabase local dev |
+| `Glob` | `supabase/**` | Supabase project config |
+| `Glob` | `**/*.razor` | Blazor |
+| `Read` | `.env.example` | Env vars reveal integrations |
+| `Read` | `README.md` | Existing project description |
+| `Grep` | `@supabase/supabase-js` | Supabase dep in any package.json |
+| `Grep` | `clerk\|auth0\|nextauth` | Auth provider |
+| `Grep` | `stripe\|asaas` | Payment provider |
+
+Read each found `package.json` for dependency names. Build an **evidence map**:
+
+```
+stack:         [nextjs, dotnet, ...]
+integrations:  [supabase, docker, clerk, ...]
+uiLibrary:     shadcn | fluent-ui | mudblazor | null
+monorepo:      true | false
+frontendPath:  src/frontend (if monorepo)
+backendPath:   src/backend (if monorepo)
+```
+
+---
+
+## Step 3 — Ask Targeted Questions
+
+**Rule: only ask what cannot be inferred with ≥90% confidence from files.**
+
+Ask at most 3 questions, only those that apply:
+
+| # | Question | Condition | Purpose |
+|---|----------|-----------|---------|
+| 1 | *"Em uma frase: qual é o objetivo principal do **[ProjectName]**?"* | Always | README.md Overview |
+| 2 | *"Confirmo: frontend em `{frontendPath}`, backend em `{backendPath}`. Correto?"* | Monorepo detected | Validate paths before persisting |
+| 3 | *"Supabase Cloud (managed) ou self-hosted?"* | Supabase detected | MCP URL configuration |
+
+Do **not** ask about technology already confirmed by file evidence.
+
+---
+
+## Step 4 — Generate `context/README.md`
+
+Write `.morph/context/README.md`:
+
+```markdown
+# [ProjectName] — Project Context
+
+## Overview
+[Answer from question 1]
+
+## Tech Stack
+| Layer      | Technology | Location |
+|------------|-----------|----------|
+[One row per detected layer — frontend, backend, database, UI library, auth, payments]
+
+## Architecture
+[monorepo / single-stack / etc — describe layers and responsibilities]
+
+## Key Integrations
+[Per integration: service → purpose → detected via: evidence file/dep]
+
+## Agent Notes
+[Patterns from eslint/tsconfig/.editorconfig, important paths,
+ project-specific conventions for MORPH agents]
+```
+
+---
+
+## Step 5 — Update `config.json`
+
+Read `.morph/config/config.json` and merge into `project`:
+
+```json
+{
+  "framework": "global",
+  "frameworkVersion": "[current version]",
+  "project": {
+    "name": "[ProjectName]",
+    "description": "[answer from question 1]",
+    "stack": "[stacks joined with +, e.g. nextjs+dotnet]",
+    "architecture": "[monorepo | single-stack | detected pattern]",
+    "uiLibrary": "[detected or null]",
+    "integrations": ["supabase", "docker", "clerk"],
+    "frontendPath": "[path if monorepo, else omit]",
+    "backendPath": "[path if monorepo, else omit]"
+  }
+}
+```
+
+---
+
+## Step 6 — Configure MCPs
+
+For each detected integration with an available MCP:
+
+**Supabase detected:**
+> *"Configure Supabase MCP now? I'll need `SUPABASE_URL` and `SERVICE_ROLE_KEY`."*
+- YES → collect credentials → add to `.claude/settings.local.json` under `mcpServers`
+- NO → show snippet + `morph-spec mcp setup supabase`
+
+**GitHub:**
+> *"Configure GitHub MCP? I'll need a `GITHUB_PERSONAL_ACCESS_TOKEN`."*
+- YES/NO → same pattern
+
+Only offer Figma, Docker, Azure if explicitly detected in `.env.example`.
+
+---
+
+## Step 7 — Final Output
+
+Before printing the summary, check `~/.claude/settings.local.json` for `env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`. If set to `"1"`, mark Agent Teams as enabled; otherwise show the warning.
+
+```
+✓ Plugins:       superpowers ✓   context7 ✓
+✓ Infrastructure: .morph/ structure, hooks, agents, rules, skills
+✓ Agents:        [N] total ([T1] orchestrators, [T2] domain leaders, [S] specialists)
+✓ context/README.md generated
+✓ config.json updated
+  Stack: [stack]  |  Architecture: [architecture]
+  Integrations:   [list]
+✓ MCPs: [configured list]
+
+[If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1":]
+✓ Agent Teams: enabled
+
+[If CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is NOT set:]
+⚠ Agent Teams not enabled. Multi-agent workflows require:
+  ~/.claude/settings.local.json → {"env": {"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"}}
+
+[If any plugin was newly installed:]
+○ Restart Claude Code to activate newly installed plugins.
+
+Next: /morph-proposal [feature-name]
+```

package/framework/skills/level-0-meta/morph-replicate/SKILL.md

@@ -77,7 +77,7 @@ Gerar lista de telas para implementar na ordem correta:
 ### T001: Setup Design System
 - Criar/atualizar wwwroot/css/design-system.css
 - Adicionar todas as classes CSS listadas
-- Validar com `morph-spec validate-css`
+- Validar com `morph-spec validate`
 
 ### T002: {Nome da Tela 1}
 - Ler: {prototype-path}/{tela1}.html
@@ -92,7 +92,7 @@ Gerar lista de telas para implementar na ordem correta:
 
 ### TXXX: Validacao Final
 - Build completo
-- `morph-spec validate-css`
+- `morph-spec validate`
 - Testar responsividade
 ```
 
@@ -130,7 +130,7 @@ Para cada tela, seguir este fluxo:
 
 6. **Validar CSS**
    ```bash
-   morph-spec validate-css src/MyApp.Web
+   morph-spec validate src/MyApp.Web
    ```
 
 ---
@@ -217,4 +217,4 @@ Mapeamento HTML → Blazor:
 
 ---
 
-*MORPH-SPEC v2.2.0 by Polymorphism Tech*
+*MORPH-SPEC by Polymorphism Tech*