@polymorphism-tech/morph-spec 4.9.0 → 4.10.1

package/src/utils/agents-installer.js

@@ -8,8 +8,9 @@
  * maxTurns, skills, memory) followed by the agent's spawn prompt as the body.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';
 import { join } from 'path';
+import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
 
 /**
  * Installs tier-1 and tier-2 morph agents as native Claude Code subagents
@@ -39,7 +40,9 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   const DOTNET_STACKS = ['dotnet', 'blazor', 'dotnet-api', 'fullstack'];
   const eligible = agents.filter(a => {
-    if (a.tier !== 1 && a.tier !== 2) return false;
+    if (a.tier !== 1 && a.tier !== 2 && a.tier !== 4) return false;
+    // Tier 4 validators must have a teammate with spawn_prompt
+    if (a.tier === 4 && !a.teammate?.spawn_prompt) return false;
     // Skip dotnet-senior for non-.NET projects
     if (a.id === 'dotnet-senior' && projectStack && !DOTNET_STACKS.includes(projectStack)) {
       return false;
@@ -49,9 +52,11 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   let tier1 = 0;
   let tier2 = 0;
+  let tier4 = 0;
   for (const agent of eligible) {
     const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');
-    const filename = `morph-${slug}.md`;
+    const prefix = agent.tier === 4 ? 'morph-validator-' : 'morph-';
+    const filename = `${prefix}${slug}.md`;
     const targetPath = join(targetDir, filename);
 
     const description = buildDescription(agent);
@@ -63,8 +68,9 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
     if (agent.tier === 1) tier1++;
     else if (agent.tier === 2) tier2++;
+    else if (agent.tier === 4) tier4++;
   }
-  return { tier1, tier2 };
+  return { tier1, tier2, tier4 };
 }
 
 /**
@@ -88,6 +94,13 @@ const TIER_DEFAULTS = {
     skills: ['morph:checklist'],
     memory: 'local',
   },
+  4: {
+    model: 'haiku',
+    tools: 'Read, Glob, Grep',
+    maxTurns: 10,
+    skills: [],
+    memory: 'project',
+  },
 };
 
 /**
@@ -101,19 +114,27 @@ const TIER_DEFAULTS = {
 function buildFrontmatter(agent, description) {
   const defaults = TIER_DEFAULTS[agent.tier] ?? TIER_DEFAULTS[2];
   const name = agent.title ?? agent.name;
-  const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
 
-  return [
+  // Allow per-agent tool overrides (e.g., morph-spec-validator needs Bash for npm test)
+  const tools = agent.teammate?.tools ?? defaults.tools;
+  // Allow per-agent maxTurns override
+  const maxTurns = agent.teammate?.maxTurns ?? defaults.maxTurns;
+
+  const lines = [
     `name: ${name}`,
     `description: ${description}`,
     `model: ${defaults.model}`,
-    `tools: ${defaults.tools}`,
-    `maxTurns: ${defaults.maxTurns}`,
-    `skills:`,
-    skillsList,
-    `memory: ${defaults.memory}`,
-    '',
-  ].join('\n');
+    `tools: ${tools}`,
+    `maxTurns: ${maxTurns}`,
+  ];
+
+  if (defaults.skills.length > 0) {
+    const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
+    lines.push(`skills:`, skillsList);
+  }
+
+  lines.push(`memory: ${defaults.memory}`, '');
+  return lines.join('\n');
 }
 
 function buildDescription(agent) {
@@ -166,7 +187,8 @@ export function parseSkillFile(rawContent) {
     if (inlineMatch) description = inlineMatch[1].trim();
   }
 
-  return { name, description, allowedTools, body };
+  const stacks = parseStacks(rawContent);
+  return { name, description, allowedTools, stacks, body };
 }
 
 /**
@@ -195,7 +217,7 @@ export function collectSkillFiles(dir) {
  * @param {string} projectDir - Target project directory
  * @param {string} frameworkDir - Path to morph-spec framework/ directory
  */
-export async function installDomainAgents(projectDir, frameworkDir = 'framework') {
+export async function installDomainAgents(projectDir, frameworkDir = 'framework', { projectTags = [] } = {}) {
   const domainsDir = join(frameworkDir, 'agents');
   if (!existsSync(domainsDir)) return { specialists: 0 };
 
@@ -203,10 +225,12 @@ export async function installDomainAgents(projectDir, frameworkDir = 'framework'
   mkdirSync(targetDir, { recursive: true });
 
   let specialists = 0;
+  const installed = new Set();
   for (const filePath of collectSkillFiles(domainsDir)) {
     const raw = readFileSync(filePath, 'utf-8');
-    const { name, description, allowedTools, body } = parseSkillFile(raw);
+    const { name, description, allowedTools, stacks, body } = parseSkillFile(raw);
     if (!name) continue;
+    if (!shouldInstall(stacks, projectTags)) continue;
 
     const desc = description ?? `MORPH-SPEC domain agent: ${name}`;
     const frontmatter = [
@@ -219,9 +243,19 @@ export async function installDomainAgents(projectDir, frameworkDir = 'framework'
       '',
     ].join('\n');
 
-    const targetPath = join(targetDir, `morph-domain-${name}.md`);
+    const filename = `morph-domain-${name}.md`;
+    const targetPath = join(targetDir, filename);
     writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body.trimStart()}`, 'utf-8');
+    installed.add(filename);
     specialists++;
   }
+
+  // Cleanup orphan morph-domain-* files
+  for (const file of readdirSync(targetDir)) {
+    if (file.startsWith('morph-domain-') && !installed.has(file)) {
+      unlinkSync(join(targetDir, file));
+    }
+  }
+
   return { specialists };
 }

package/src/utils/claude-md-injector.js

@@ -0,0 +1,90 @@
+/**
+ * claude-md-injector.js
+ *
+ * Manages the root CLAUDE.md file in client projects.
+ * Instead of overwriting the user's CLAUDE.md, injects an @import line
+ * that references the morph-spec managed .claude/CLAUDE.md.
+ *
+ * The root CLAUDE.md belongs to the USER — morph-spec only adds its import.
+ */
+
+import { pathExists, readFile, writeFile } from './file-copier.js';
+
+const MORPH_IMPORT = '@.claude/CLAUDE.md';
+const MORPH_MARKER = 'MORPH-SPEC';
+
+/**
+ * Injects the morph-spec @import into the root CLAUDE.md.
+ *
+ * Three scenarios:
+ * 1. No CLAUDE.md exists → create minimal file with the import
+ * 2. Existing morph-only CLAUDE.md (old overwrite) → replace with minimal + import
+ * 3. Existing user CLAUDE.md → append import section at the end
+ *
+ * Idempotent — does nothing if the import already exists.
+ *
+ * @param {string} claudeMdPath - Absolute path to root CLAUDE.md
+ * @returns {Promise<'created'|'migrated'|'injected'|'already-present'>}
+ */
+export async function injectMorphImport(claudeMdPath) {
+  if (!await pathExists(claudeMdPath)) {
+    await writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
+    return 'created';
+  }
+
+  const content = await readFile(claudeMdPath);
+
+  if (content.includes(MORPH_IMPORT)) {
+    return 'already-present';
+  }
+
+  if (isMorphOnly(content)) {
+    await writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
+    return 'migrated';
+  }
+
+  // User has their own content — append the import section
+  const separator = content.endsWith('\n') ? '\n' : '\n\n';
+  await writeFile(claudeMdPath, `${content}${separator}## MORPH-SPEC\n\n${MORPH_IMPORT}\n`);
+  return 'injected';
+}
+
+/**
+ * Checks if CLAUDE.md contains ONLY morph-spec content (old overwrite pattern).
+ * Heuristic: contains MORPH-SPEC marker AND no substantial user content.
+ */
+function isMorphOnly(content) {
+  if (!content.includes(MORPH_MARKER)) return false;
+
+  // Strip morph-spec boilerplate markers and check if anything meaningful remains
+  const stripped = content
+    .replace(/# MORPH-SPEC Runtime Instructions/g, '')
+    .replace(/by Polymorphism Tech[^\n]*/g, '')
+    .replace(/\*MORPH-SPEC by Polymorphism Tech\*/g, '')
+    .replace(/@\.morph\/context\/README\.md/g, '')
+    .replace(/@\.claude\/CLAUDE\.md/g, '')
+    .replace(/## Critical Rules[\s\S]*?(?=##|$)/g, '')
+    .replace(/## Quick Reference[\s\S]*?(?=##|$)/g, '')
+    .replace(/## State & Outputs[\s\S]*?(?=##|$)/g, '')
+    .replace(/## Phase Sequence[\s\S]*?(?=##|$)/g, '')
+    .replace(/## Agents[\s\S]*?(?=##|$)/g, '')
+    .replace(/## Context Window Tip[\s\S]*?(?=##|$)/g, '')
+    .replace(/## Project Context[\s\S]*?(?=##|$)/g, '')
+    .replace(/[#\-|>*`\s]/g, '');
+
+  return stripped.length < 50;
+}
+
+/**
+ * Checks if the root CLAUDE.md has the morph-spec import.
+ * Used by doctor.js for health checks.
+ *
+ * @param {string} claudeMdPath - Absolute path to root CLAUDE.md
+ * @returns {Promise<'ok'|'missing'|'missing-import'>}
+ */
+export async function checkClaudeMdImport(claudeMdPath) {
+  if (!await pathExists(claudeMdPath)) return 'missing';
+  const content = await readFile(claudeMdPath);
+  if (content.includes(MORPH_IMPORT)) return 'ok';
+  return 'missing-import';
+}

package/src/utils/file-copier.js

@@ -144,7 +144,6 @@ export async function updateGitignore(projectPath) {
     '.claude/agents/',
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
-    '.mcp.json',
     '.worktrees/',
     ''
   ];

package/src/utils/hooks-installer.js

@@ -15,7 +15,7 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 
 /** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '2.10.0';
+const HOOKS_VERSION = '2.12.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -31,10 +31,7 @@ const MORPH_PERMISSIONS = [
   'Edit(.morph/state.json)',
   'Write(.morph/framework/**)',
   'Edit(.morph/framework/**)',
-  // Root CLAUDE.md (managed copy — source is framework/CLAUDE.md)
-  'Write(CLAUDE.md)',
-  'Edit(CLAUDE.md)',
-  // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE_runtime.md)
+  // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE.md)
   'Write(.claude/CLAUDE.md)',
   'Edit(.claude/CLAUDE.md)',
   // .claude/rules/ (copied from framework/rules/)
@@ -63,6 +60,16 @@ const MORPH_HOOKS = [
     }]
   },
 
+  // === SessionStart: compact only — post-compact context restore ===
+  {
+    event: 'SessionStart',
+    matcher: 'compact',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/session-start/post-compact-restore.js'
+    }]
+  },
+
   // === UserPromptSubmit ===
   {
     event: 'UserPromptSubmit',
@@ -93,6 +100,10 @@ const MORPH_HOOKS = [
       {
         type: 'command',
         command: 'node framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/task-tracking-guard.js'
       }
     ]
   },

package/src/utils/skills-installer.js

@@ -16,9 +16,10 @@
  * assets/) so Claude Code can execute scripts and load references on demand.
  */
 
-import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync, readFileSync, rmSync } from 'fs';
 import { join } from 'path';
 import { fileURLToPath } from 'url';
+import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
@@ -32,6 +33,16 @@ const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
  */
 const SKILL_LEVELS_TO_INSTALL = ['level-0-meta', 'level-1-workflows'];
 
+/**
+ * Check if a skill should be installed based on its stacks: frontmatter.
+ * @param {string} skillContent - Raw SKILL.md content
+ * @param {string[]} projectTags - Stack tags from config
+ * @returns {boolean}
+ */
+export function shouldInstallSkill(skillContent, projectTags) {
+  return shouldInstall(parseStacks(skillContent), projectTags);
+}
+
 /**
  * Recursively copy a directory tree from src to dest.
  * Creates dest if it doesn't exist. Skips README.md files.
@@ -71,7 +82,7 @@ function copyDirectory(src, dest) {
  * @param {string} srcDir - Source directory to walk
  * @param {string} destDir - Destination base directory (.claude/skills/)
  */
-function installSkillsFromDir(srcDir, destDir) {
+function installSkillsFromDir(srcDir, destDir, projectTags) {
   const entries = readdirSync(srcDir);
   for (const entry of entries) {
     const srcPath = join(srcDir, entry);
@@ -80,15 +91,19 @@ function installSkillsFromDir(srcDir, destDir) {
     if (stat.isDirectory()) {
       const skillMdPath = join(srcPath, 'SKILL.md');
       if (existsSync(skillMdPath)) {
-        // Directory-based skill — copy entire directory including scripts/, references/, assets/
+        // Directory-based skill — check stack filter before copying
+        const content = readFileSync(skillMdPath, 'utf-8');
+        if (!shouldInstallSkill(content, projectTags)) continue;
         const skillDestDir = join(destDir, entry);
         copyDirectory(srcPath, skillDestDir);
       } else {
         // Level/category directory — recurse
-        installSkillsFromDir(srcPath, destDir);
+        installSkillsFromDir(srcPath, destDir, projectTags);
       }
     } else if (entry.endsWith('.md') && entry !== 'README.md') {
-      // Legacy flat .md skill — wrap in subdirectory as SKILL.md
+      // Legacy flat .md skill — check stack filter before copying
+      const content = readFileSync(srcPath, 'utf-8');
+      if (!shouldInstallSkill(content, projectTags)) continue;
       const skillName = entry.slice(0, -3);
       const skillDir = join(destDir, skillName);
       mkdirSync(skillDir, { recursive: true });
@@ -97,6 +112,28 @@ function installSkillsFromDir(srcDir, destDir) {
   }
 }
 
+function collectSourceSkillNames() {
+  const names = new Set();
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+    collectNamesFromDir(levelDir, names);
+  }
+  return names;
+}
+
+function collectNamesFromDir(dir, names) {
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    if (!statSync(fullPath).isDirectory()) continue;
+    if (existsSync(join(fullPath, 'SKILL.md'))) {
+      names.add(entry);
+    } else {
+      collectNamesFromDir(fullPath, names);
+    }
+  }
+}
+
 /**
  * Install morph framework skills to .claude/skills/ in the target project.
  * Skills are copied into subdirectories as SKILL.md files so Claude Code can
@@ -104,15 +141,38 @@ function installSkillsFromDir(srcDir, destDir) {
  * /blazor-builder). Directory-based skills also get their scripts/,
  * references/, and assets/ subdirectories copied for on-demand loading.
  *
+ * Stack filtering: if projectTags is provided, only skills whose `stacks:`
+ * frontmatter matches the project tags are installed. Skills without a
+ * `stacks:` field are always installed (universal).
+ *
  * @param {string} projectDir - Target project root directory
+ * @param {Object} [options]
+ * @param {string[]} [options.projectTags=[]] - Stack tags from config
  */
-export async function installSkills(projectDir) {
+export async function installSkills(projectDir, { projectTags = [] } = {}) {
   const claudeSkillsDir = join(projectDir, '.claude', 'skills');
   mkdirSync(claudeSkillsDir, { recursive: true });
 
   for (const level of SKILL_LEVELS_TO_INSTALL) {
     const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
     if (!existsSync(levelDir)) continue;
-    installSkillsFromDir(levelDir, claudeSkillsDir);
+    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags);
+  }
+
+  // Collect installed morph-* skill names
+  const installed = new Set();
+  for (const entry of readdirSync(claudeSkillsDir)) {
+    if (existsSync(join(claudeSkillsDir, entry, 'SKILL.md'))) {
+      installed.add(entry);
+    }
+  }
+
+  // Cleanup orphan morph-* skill dirs that exist in source but were filtered out
+  const allSourceSkills = collectSourceSkillNames();
+  for (const entry of readdirSync(claudeSkillsDir)) {
+    if (!entry.startsWith('morph-')) continue;
+    if (!installed.has(entry) && allSourceSkills.has(entry)) {
+      rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
+    }
   }
 }

package/CLAUDE.md

@@ -1,98 +0,0 @@
-# MORPH-SPEC Runtime Instructions
-
-> by Polymorphism Tech — Spec-driven development for .NET/Blazor/Next.js/Azure
-
----
-
-## Project Context
-
-@.morph/context/README.md
-
----
-
-## Critical Rules
-
-**NEVER:**
-- Skip to code without a specification
-- Implement without design approval
-- Ignore standards in `.morph/framework/standards/`
-- Create infrastructure manually
-- Generate code without defined contracts
-- List questions as plain text — always use the `AskUserQuestion` tool
-
-**ALWAYS:**
-- Follow the mandatory phases
-- Generate outputs in `.morph/features/{feature}/`
-- Document decisions in `decisions.md`
-- Checkpoint every 3 implemented tasks
-- Use Infrastructure as Code
-- Use `AskUserQuestion` tool whenever asking the user anything (1–4 questions per call; split into sequential calls if more)
-
----
-
-## Quick Reference
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation |
-
----
-
-## State & Outputs
-
-| Path | Notes |
-|------|-------|
-| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
-| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
-| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
-| `.morph/config/config.json` | Project configuration (editable) |
-
-### mark-output types
-
-Use `morph-spec state mark-output <feature> <type>` with one of these exact type names:
-
-| Type | Phase | kebab alias |
-|------|-------|-------------|
-| `proposal` | proposal | — |
-| `schemaAnalysis` | design | `schema-analysis` |
-| `spec` | design | — |
-| `contracts` | design | — |
-| `contractsVsa` | design | `contracts-vsa` |
-| `decisions` | design | — |
-| `clarifications` | clarify | — |
-| `tasks` | tasks | — |
-| `uiDesignSystem` | uiux | `ui-design-system` |
-| `uiMockups` | uiux | `ui-mockups` |
-| `uiComponents` | uiux | `ui-components` |
-| `uiFlows` | uiux | `ui-flows` |
-| `recap` | implement | — |
----
-
-## Phase Sequence
-
-```
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-```
-
-Use `morph-spec status {feature}` to see current phase and pending approval gates.
-
----
-
-## Agents
-
-Tier-1 and tier-2 MORPH agents are available as native subagents in `.claude/agents/`.
-They can be invoked directly by Claude Code during multi-agent workflows.
-
----
-
-## Context Window Tip
-
-When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
-MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*