@polymorphism-tech/morph-spec 7.9.4 → 8.1.0

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 = '3.1.0';
+const HOOKS_VERSION = '3.3.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -26,22 +26,24 @@ const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
  * state.json is NOT in deny because the agent edits it directly as a
  * fallback to the state-sync hook (per v7 hybrid state model). The
  * framework/ tree remains read-only — only the installer touches it.
+ *
+ * `Edit(path)` ONLY — never a matching `Write(path)`. Claude Code matches file
+ * permissions on `Edit(path)` rules alone; an `Edit` rule covers every
+ * file-editing tool, Write included, while a `Write(path)` rule matches nothing
+ * and is reported as a warning on every session start. Verified empirically, not
+ * assumed: with `Edit(.morph/framework/**)` as the ONLY deny entry, the Write
+ * tool was refused and the target file was never created.
  */
 const MORPH_DENY = [
   // Framework files — installer-managed, immutable at runtime
-  'Write(.morph/framework/**)',
   'Edit(.morph/framework/**)',
   // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE.md)
-  'Write(.claude/CLAUDE.md)',
   'Edit(.claude/CLAUDE.md)',
   // .claude/rules/ (copied from framework/rules/)
-  'Write(.claude/rules/**)',
   'Edit(.claude/rules/**)',
   // .claude/agents/morph-* (generated by agents-installer)
-  'Write(.claude/agents/morph-*)',
   'Edit(.claude/agents/morph-*)',
   // .claude/skills/ (copied from framework/skills/)
-  'Write(.claude/skills/**)',
   'Edit(.claude/skills/**)',
 ];
 
@@ -51,15 +53,16 @@ const MORPH_DENY = [
  * Pre-authorizes operations the agent legitimately performs during the
  * morph-spec flow, so the user does not get permission prompts on every
  * proposal.md / spec.md / tasks.json write.
+ *
+ * `Edit(path)` ONLY, for the same reason as MORPH_DENY: the `Edit` rule already
+ * covers Write, and a `Write(path)` rule is inert noise.
  */
 const MORPH_ALLOW = [
   // Feature artifacts — the agent's working directory during proposal/plan/implement/review
-  'Write(.morph/features/**)',
   'Edit(.morph/features/**)',
   // state.json — fallback path when state-sync hook can't cover a case
   'Edit(.morph/state.json)',
   // Long-lived architectural context — agent may reconcile during brainstorming
-  'Write(.morph/context/**)',
   'Edit(.morph/context/**)',
   // Folder creation under .morph
   'Bash(mkdir:.morph/**)',
@@ -74,6 +77,19 @@ const MORPH_PERMISSIONS = MORPH_DENY;
  * Each entry maps to a Claude Code hook event.
  */
 const MORPH_HOOKS = [
+  // === SessionStart — worktree feature identity (secondary worktree) or
+  // active-feature summary (primary root). Fulfills the SessionStart
+  // injection role long documented but never wired (inject-morph-context.js). ===
+  {
+    event: 'SessionStart',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/worktree-context.js',
+      timeout: 5000
+    }]
+  },
+
   // === PreToolUse: Write|Edit — phase + spec protection (silent on success) ===
   {
     event: 'PreToolUse',
@@ -160,34 +176,13 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === Stop — build check + session snapshot + dispatch-report guard ===
-  // subagent-report-guard blocks (once) a dispatched sub-agent stopping
-  // without SendMessage — clause 1 of the dispatch protocol. In the
-  // orchestrator's session it is inert (marker never in a user message).
+  // === Stop — build check + session snapshot ===
   {
     event: 'Stop',
     matcher: null,
-    hooks: [
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/validate-completion.js'
-      },
-      {
-        type: 'command',
-        command: 'node framework/hooks/claude-code/core/subagent-report-guard.js',
-        timeout: 5000
-      }
-    ]
-  },
-
-  // === SubagentStop — dispatch-report guard for Task-tool subagents ===
-  {
-    event: 'SubagentStop',
-    matcher: null,
     hooks: [{
       type: 'command',
-      command: 'node framework/hooks/claude-code/core/subagent-report-guard.js',
-      timeout: 5000
+      command: 'node framework/hooks/claude-code/core/validate-completion.js'
     }]
   }
 ];
@@ -266,11 +261,21 @@ export async function installClaudeHooks(targetPath) {
   settings.permissions.deny = settings.permissions.deny || [];
   settings.permissions.allow = settings.permissions.allow || [];
 
-  // Stale-entry cleanup: remove old morph-managed deny entries (e.g. state.json
-  // was previously in deny — v7 moves it to allow)
+  // Stale-entry cleanup: remove morph-managed entries we no longer install.
+  // The filters below drop `MORPH_*.includes(p)` before re-adding, so an entry
+  // that LEFT those lists would otherwise survive forever in an existing
+  // install — the upgrade path has to name it explicitly to reclaim it.
+  //   - state.json: was in deny pre-v7, now lives in allow.
+  //   - Write(...): matched nothing and made Claude Code warn on every session
+  //     start; the paired Edit(...) rule is what actually enforced them.
   const STALE_DENY = [
     'Write(.morph/state.json)',
     'Edit(.morph/state.json)',
+    'Write(.morph/framework/**)',
+    'Write(.claude/CLAUDE.md)',
+    'Write(.claude/rules/**)',
+    'Write(.claude/agents/morph-*)',
+    'Write(.claude/skills/**)',
   ];
   settings.permissions.deny = settings.permissions.deny.filter(
     p => !MORPH_DENY.includes(p) && !STALE_DENY.includes(p)
@@ -279,8 +284,12 @@ export async function installClaudeHooks(targetPath) {
     settings.permissions.deny.push(perm);
   }
 
+  const STALE_ALLOW = [
+    'Write(.morph/features/**)',
+    'Write(.morph/context/**)',
+  ];
   settings.permissions.allow = settings.permissions.allow.filter(
-    p => !MORPH_ALLOW.includes(p)
+    p => !MORPH_ALLOW.includes(p) && !STALE_ALLOW.includes(p)
   );
   for (const perm of MORPH_ALLOW) {
     settings.permissions.allow.push(perm);

package/src/utils/skills-installer.js

@@ -1,174 +1,174 @@
-/**
- * Skills Installer
- *
- * Copies framework skills to .claude/skills/ during morph-spec init.
- * Installs only the `core/` skill set — the canonical NLH skills referenced by
- * MORPH.md (morph-brainstorming, morph-stack-scan, morph-plan, morph-implement,
- * morph-eval, morph-review, morph-standards). The 3-tier system was collapsed
- * into a single source of truth in framework/skills/core/.
- *
- * Source skills are directory-based: framework/skills/core/{skill-name}/SKILL.md
- * (plus optional scripts/, references/, assets/ subdirectories).
- *
- * Directory-based skills have their entire directory copied so Claude Code can
- * execute scripts and load references on demand.
- */
-
-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');
-
-/**
- * Skill levels to install in .claude/skills/.
- * Only `core/` survives — single source of truth aligned with MORPH.md.
- */
-const SKILL_LEVELS_TO_INSTALL = ['core'];
-
-/**
- * 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.
- *
- * @param {string} src - Source directory path
- * @param {string} dest - Destination directory path
- */
-function copyDirectory(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    if (entry === 'README.md') continue;
-    const srcPath = join(src, entry);
-    const destPath = join(dest, entry);
-    if (statSync(srcPath).isDirectory()) {
-      copyDirectory(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-/**
- * Walk srcDir and install skills into destDir.
- *
- * Handles two source formats:
- *   1. Directory-based skill: srcDir/{skill-name}/SKILL.md
- *      → copies entire directory (SKILL.md + scripts/ + references/ + assets/)
- *      → destDir/{skill-name}/
- *
- *   2. Flat .md skill (legacy): srcDir/{skill-name}.md
- *      → destDir/{skill-name}/SKILL.md
- *
- * The `core/` level directory is traversed recursively. A directory is
- * recognized as a skill directory when it contains a SKILL.md file.
- *
- * @param {string} srcDir - Source directory to walk
- * @param {string} destDir - Destination base directory (.claude/skills/)
- */
-function installSkillsFromDir(srcDir, destDir, projectTags) {
-  const entries = readdirSync(srcDir);
-  for (const entry of entries) {
-    const srcPath = join(srcDir, entry);
-    const stat = statSync(srcPath);
-
-    if (stat.isDirectory()) {
-      const skillMdPath = join(srcPath, 'SKILL.md');
-      if (existsSync(skillMdPath)) {
-        // 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, projectTags);
-      }
-    } else if (entry.endsWith('.md') && entry !== 'README.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 });
-      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
-    }
-  }
-}
-
-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
- * discover them natively via /<skill-name> syntax (e.g., /phase-design,
- * /nextjs-expert). 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, { 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, 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 });
-    }
-  }
-
-  return { installed: installed.size };
-}
+/**
+ * Skills Installer
+ *
+ * Copies framework skills to .claude/skills/ during morph-spec init.
+ * Installs only the `core/` skill set — the canonical NLH skills referenced by
+ * MORPH.md (morph-brainstorming, morph-stack-scan, morph-plan, morph-implement,
+ * morph-eval, morph-review, morph-standards). The 3-tier system was collapsed
+ * into a single source of truth in framework/skills/core/.
+ *
+ * Source skills are directory-based: framework/skills/core/{skill-name}/SKILL.md
+ * (plus optional scripts/, references/, assets/ subdirectories).
+ *
+ * Directory-based skills have their entire directory copied so Claude Code can
+ * execute scripts and load references on demand.
+ */
+
+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');
+
+/**
+ * Skill levels to install in .claude/skills/.
+ * Only `core/` survives — single source of truth aligned with MORPH.md.
+ */
+const SKILL_LEVELS_TO_INSTALL = ['core'];
+
+/**
+ * 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.
+ *
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ */
+function copyDirectory(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    if (entry === 'README.md') continue;
+    const srcPath = join(src, entry);
+    const destPath = join(dest, entry);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirectory(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Walk srcDir and install skills into destDir.
+ *
+ * Handles two source formats:
+ *   1. Directory-based skill: srcDir/{skill-name}/SKILL.md
+ *      → copies entire directory (SKILL.md + scripts/ + references/ + assets/)
+ *      → destDir/{skill-name}/
+ *
+ *   2. Flat .md skill (legacy): srcDir/{skill-name}.md
+ *      → destDir/{skill-name}/SKILL.md
+ *
+ * The `core/` level directory is traversed recursively. A directory is
+ * recognized as a skill directory when it contains a SKILL.md file.
+ *
+ * @param {string} srcDir - Source directory to walk
+ * @param {string} destDir - Destination base directory (.claude/skills/)
+ */
+function installSkillsFromDir(srcDir, destDir, projectTags) {
+  const entries = readdirSync(srcDir);
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      const skillMdPath = join(srcPath, 'SKILL.md');
+      if (existsSync(skillMdPath)) {
+        // 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, projectTags);
+      }
+    } else if (entry.endsWith('.md') && entry !== 'README.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 });
+      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
+    }
+  }
+}
+
+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
+ * discover them natively via /<skill-name> syntax (e.g., /phase-design,
+ * /nextjs-expert). 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, { 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, 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 });
+    }
+  }
+
+  return { installed: installed.size };
+}

package/framework/hooks/claude-code/core/subagent-report-guard.js

@@ -1,95 +0,0 @@
-#!/usr/bin/env node
-/**
- * subagent-report-guard.js — Stop / SubagentStop hook
- *
- * Enforces clause 1 of the morph-spec dispatch protocol: a dispatched
- * sub-agent's FINAL act is SendMessage to the orchestrator (main). Plain text
- * in the last message never reaches the orchestrator, and an idle agent forces
- * the costly nag-and-wait cycle (observed 2/2 in real apply sessions —
- * MORPH_GHLBrain 2026-07-11).
- *
- * Detection: the session transcript (JSONL) contains the dispatch-protocol
- * marker ("Protocolo obrigatório") inside a USER message — that is how the
- * dispatch prompt arrives in the sub-agent's own transcript. In the
- * ORCHESTRATOR's transcript the marker only appears inside assistant tool_use
- * input (the Agent call that did the dispatch), so the orchestrator is never
- * blocked by this guard. A SendMessage tool_use anywhere in an assistant
- * message counts as the report.
- *
- * Action: block the stop ONCE ({"decision":"block"}) with the exact
- * instruction to call SendMessage — the agent continues and reports.
- * stop_hook_active guards against blocking loops. Fail-open on any error.
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { stateExists } from '../../shared/state-reader.js';
-import { block, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-
-const PROTOCOL_MARKER = 'Protocolo obrigatório';
-
-function readStdin() {
-  try {
-    return JSON.parse(readFileSync(0, 'utf8') || '{}');
-  } catch {
-    return {};
-  }
-}
-
-function projectDir() {
-  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
-}
-
-/**
- * Scan a transcript for the dispatch-protocol marker (user messages only) and
- * for a SendMessage tool call (assistant messages).
- *
- * @param {string} path - JSONL transcript path
- * @returns {{ dispatched: boolean, reported: boolean }}
- */
-function scanTranscript(path) {
-  const raw = readFileSync(path, 'utf8');
-  let dispatched = false;
-  let reported = false;
-  for (const line of raw.split('\n')) {
-    if (!line.trim()) continue;
-    let role = null;
-    try {
-      const entry = JSON.parse(line);
-      role = entry?.message?.role ?? entry?.type ?? null;
-    } catch {
-      continue;
-    }
-    if (!dispatched && role === 'user' && line.includes(PROTOCOL_MARKER)) dispatched = true;
-    if (!reported && role === 'assistant' && line.includes('"name":"SendMessage"')) reported = true;
-  }
-  return { dispatched, reported };
-}
-
-try {
-  if (!stateExists(projectDir())) pass();
-
-  const input = readStdin();
-
-  // Never loop: a previous block already forced one continuation — let this
-  // stop through even if the agent still failed to report.
-  if (input.stop_hook_active) pass();
-
-  const transcriptPath = input.transcript_path;
-  if (!transcriptPath || !existsSync(transcriptPath)) pass();
-
-  const { dispatched, reported } = scanTranscript(transcriptPath);
-  if (!dispatched || reported) pass();
-
-  logHookActivity('subagent-report-guard', input.hook_event_name || 'Stop', 'blocked', projectDir());
-  block(
-    '[morph-spec] PROTOCOLO DE RETORNO — você foi despachado com o protocolo obrigatório ' +
-    'mas ainda não chamou SendMessage. Sua última mensagem em texto NÃO chega ao orquestrador. ' +
-    'Antes de encerrar, chame a tool SendMessage com to:"main" e o relatório completo no content: ' +
-    '(1) o que foi feito em 2-3 frases, (2) arquivos modificados, (3) problemas encontrados e ' +
-    'como foram resolvidos, (4) auto-score 0-10. O SendMessage é o seu ato final.'
-  );
-} catch {
-  // Fail-open
-  process.exit(0);
-}