@polymorphism-tech/morph-spec 7.8.0 → 7.9.0

package/src/commands/project/update.js

@@ -30,7 +30,7 @@ import { installSkills } from '../../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../../utils/agents-installer.js';
 import { injectMorphImport } from '../../utils/claude-md-injector.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
-import { updateClaudeMdAgentsBlock } from '../../scripts/setup-infra.js';
+import { updateClaudeMdAgentsBlock, installRulesForStack } from '../../scripts/setup-infra.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -322,28 +322,35 @@ export async function updateCommand(options) {
       logger.warn('  ⚠ framework/commands/ source missing — commands not updated');
     }
 
-    // Compute project tags for stack-aware installation of skills, agents, and rules
+    // Compute project tags for stack-aware installation of skills, agents, and rules.
+    // MUST come from the pre-clean backup: cleanFrameworkDirs() deleted .morph/config/
+    // above and restoreUserConfig() only runs at the end — re-reading the file here
+    // yields [] and silently downgrades the whole install to universal-only assets
+    // (the ".claude/agents/ only has morph-evaluator.md after update" bug).
     let projectTags = [];
     try {
-      const cfg = await readJson(join(morphPath, 'config', 'config.json'));
-      projectTags = getProjectTags(cfg);
-    } catch { /* ignore — config may not exist yet */ }
+      if (configBackup) projectTags = getProjectTags(configBackup);
+    } catch { /* ignore — malformed config */ }
 
     // Sync morph skills to .claude/skills/ for native Claude Code discovery
     updateSpinner.text = 'Syncing morph skills to .claude/skills/...';
-    await installSkills(targetPath, { projectTags });
+    const skillsResult = await installSkills(targetPath, { projectTags });
 
     // Sync native subagents to .claude/agents/
     updateSpinner.text = 'Syncing agents to .claude/agents/...';
     const agentsResult = await installAgents(targetPath, frameworkDir, { projectTags });
     await installDomainAgents(targetPath, frameworkDir, { projectTags });
 
-    // Sync path-scoped rules to .claude/rules/
+    // Sync path-scoped rules to .claude/rules/ — stack-filtered with orphan
+    // cleanup (parity with setup-infra), so `update` is a true superset of
+    // `setup-infra --reinstall` and also covers project.stack changes.
     updateSpinner.text = 'Syncing rules to .claude/rules/...';
     const rulesSrc = join(frameworkDir, 'rules');
     const rulesDest = join(claudeDest, 'rules');
+    let rulesResult = null;
     if (await pathExists(rulesSrc)) {
-      await copyDirectory(rulesSrc, rulesDest);
+      await ensureDir(rulesDest);
+      rulesResult = installRulesForStack(rulesSrc, rulesDest, projectTags);
     }
 
     // Sync runtime CLAUDE.md to .claude/CLAUDE.md and derive the personas
@@ -414,10 +421,13 @@ export async function updateCommand(options) {
     logger.dim('  ✓ .morph/framework/schemas/ + rubrics/ + evals/ (bar 9 + LLM rubrics)');
     if (commandsCopied) logger.dim('  ✓ .claude/commands/');
 
+    // Counts make a silent stack-filter downgrade visible at a glance —
+    // a dotnet project reporting "1 persona" is a red flag, not a success.
+    const tagsLabel = projectTags.length > 0 ? projectTags.join('+') : 'universal only';
     logger.dim(`  ✓ .claude/settings.local.json (${hooksResult.installed} hooks installed)`);
-    logger.dim('  ✓ .claude/skills/ (skills installed as directories)');
-    logger.dim('  ✓ .claude/agents/ (native subagents refreshed)');
-    logger.dim('  ✓ .claude/rules/ (path-scoped rules synced)');
+    logger.dim(`  ✓ .claude/skills/ (${skillsResult?.installed ?? '?'} skills — stack: ${tagsLabel})`);
+    logger.dim(`  ✓ .claude/agents/ (${agentsResult?.agents?.length ?? '?'} personas — stack: ${tagsLabel})`);
+    logger.dim(`  ✓ .claude/rules/ (${rulesResult?.installed ?? '?'} stack-filtered rules)`);
     logger.dim('  ✓ .claude/CLAUDE.md (runtime quick reference)');
     logger.dim('  ✓ ~/.claude/statusline.sh (global statusline synced)');
     logger.dim('  ✓ CLAUDE.md');

package/src/commands/state/create.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { createFeature } from '../../core/state/state-manager.js';
+
+/** Feature names are kebab-case: lowercase alphanumerics and hyphens. */
+const FEATURE_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+const VALID_STATUSES = ['draft', 'in_progress', 'completed'];
+
+/**
+ * `morph-spec create <feature>` — explicit feature birth: creates
+ * `.morph/features/{feature}/0-proposal/` and the canonical feature.json
+ * (shape documented in framework/schemas/feature.schema.json).
+ *
+ * Replaces the implicit birth via the state-sync hook on the first Write —
+ * the skills call this at proposal start so the authoritative state exists
+ * with the full canonical shape before any artifact lands. Idempotent: an
+ * existing feature is reported and left untouched.
+ */
+export async function createCommand(featureName, options = {}) {
+  try {
+    if (!FEATURE_NAME_RE.test(featureName)) {
+      console.error(chalk.red(`\n❌ Invalid feature name: "${featureName}"`));
+      console.error(chalk.gray('Use kebab-case: lowercase letters, digits and hyphens (e.g. "user-onboarding")\n'));
+      process.exit(1);
+    }
+
+    if (options.status !== undefined && !VALID_STATUSES.includes(options.status)) {
+      console.error(chalk.red(`\n❌ Invalid --status: "${options.status}"`));
+      console.error(chalk.gray(`Valid statuses: ${VALID_STATUSES.join(', ')}\n`));
+      process.exit(1);
+    }
+
+    const { feature, created } = await createFeature(featureName, { status: options.status });
+
+    // The proposal folder is the first working directory of every feature.
+    const featureDir = join(process.cwd(), '.morph', 'features', featureName);
+    mkdirSync(join(featureDir, '0-proposal'), { recursive: true });
+
+    if (options.json) {
+      console.log(JSON.stringify({ feature: featureName, created, ...feature }, null, 2));
+      return;
+    }
+
+    if (created) {
+      console.log(chalk.green(`\n✅ Feature created: ${featureName}`));
+      console.log(chalk.gray(`   .morph/features/${featureName}/feature.json (canonical shape) + 0-proposal/`));
+      console.log(chalk.gray(`   status: ${feature.status} | createdAt: ${feature.createdAt}\n`));
+    } else {
+      console.log(chalk.yellow(`\n⚠️  Feature "${featureName}" already exists — left untouched`));
+      console.log(chalk.gray(`   status: ${feature.status} | createdAt: ${feature.createdAt || 'unknown'}\n`));
+    }
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error creating feature: ${error.message}\n`));
+    process.exit(1);
+  }
+}

package/src/commands/state/gate-decision.js

@@ -0,0 +1,99 @@
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getFeature, updateFeature } from '../../core/state/state-manager.js';
+
+const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
+
+function parsePauseValue(raw) {
+  const v = String(raw).toLowerCase();
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  console.error(chalk.red(`\n❌ Invalid --pause: "${raw}" — expected true or false\n`));
+  process.exit(1);
+}
+
+/** trust from the committed config (BOM-tolerant), defaulting to "auto". */
+function readTrustFromConfig() {
+  try {
+    const path = join(process.cwd(), '.morph', 'config', 'config.json');
+    if (!existsSync(path)) return 'auto';
+    const raw = readFileSync(path, 'utf8').replace(/^/, '');
+    return JSON.parse(raw).trust || 'auto';
+  } catch {
+    return 'auto';
+  }
+}
+
+/**
+ * `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>]
+ * [--signals <json>] [--trust <mode>]` — record the trust decision for a gate
+ * under `gateDecisions` in the authoritative feature.json.
+ *
+ * Same philosophy as `morph-spec score`: the timestamp (`decidedAt`) is
+ * stamped server-side and the write is atomic (state-manager). This replaces
+ * the manual Edit of feature.json from the skills — which collided with the
+ * state-sync hook rewriting the file between the agent's Read and Edit
+ * ("file modified since read"). The canonical shape is documented in
+ * framework/schemas/feature.schema.json and consumed by gate-guard.js.
+ */
+export async function gateDecisionCommand(featureName, gateName, options = {}) {
+  try {
+    if (!VALID_GATES.includes(gateName)) {
+      console.error(chalk.red(`\n❌ Invalid gate: ${gateName}`));
+      console.error(chalk.gray(`Valid gates: ${VALID_GATES.join(', ')}\n`));
+      process.exit(1);
+    }
+
+    if (options.pause === undefined) {
+      console.error(chalk.red('\n❌ --pause is required (true or false)\n'));
+      process.exit(1);
+    }
+    const pause = parsePauseValue(options.pause);
+
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    let signals = {};
+    if (options.signals !== undefined) {
+      try {
+        signals = JSON.parse(options.signals);
+      } catch (err) {
+        console.error(chalk.red(`\n❌ Invalid --signals: not valid JSON (${err.message})\n`));
+        process.exit(1);
+      }
+      if (!signals || typeof signals !== 'object' || Array.isArray(signals)) {
+        console.error(chalk.red('\n❌ Invalid --signals: expected a JSON object, e.g. \'{"taskCount":12}\'\n'));
+        process.exit(1);
+      }
+    }
+
+    const entry = {
+      pause,
+      reason: options.reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
+      signals,
+      trust: options.trust || readTrustFromConfig(),
+      decidedAt: new Date().toISOString(),
+    };
+
+    await updateFeature(featureName, `gateDecisions.${gateName}`, entry);
+
+    if (options.json) {
+      console.log(JSON.stringify({ feature: featureName, gate: gateName, ...entry }, null, 2));
+      return;
+    }
+
+    console.log(chalk.green(`\n✅ Gate decision recorded: ${featureName}/${gateName} → pause: ${entry.pause}`));
+    console.log(chalk.gray(`   reason: ${entry.reason} | trust: ${entry.trust} | decidedAt: ${entry.decidedAt}`));
+    if (Object.keys(entry.signals).length > 0) {
+      console.log(chalk.gray(`   signals: ${JSON.stringify(entry.signals)}`));
+    }
+    console.log('');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error recording gate decision: ${error.message}\n`));
+    process.exit(1);
+  }
+}

package/src/core/state/state-manager.js

@@ -484,6 +484,61 @@ async function ensureFeature(featureName) {
   return state.features[featureName];
 }
 
+/**
+ * Explicitly create a feature with the canonical shape (documented in
+ * framework/schemas/feature.schema.json). Idempotent: an existing feature is
+ * returned untouched. This is the server-side birth path behind
+ * `morph-spec create` — replacing the implicit registration on the first
+ * Write into .morph/features/ (the state-sync hook remains as fallback).
+ *
+ * Works even before any state exists (scaffolds the root index), so a
+ * feature can be born as the very first morph action in a project.
+ *
+ * @param {string} featureName - Feature name (kebab-case)
+ * @param {{ status?: string }} [options]
+ * @returns {Promise<{ feature: Object, created: boolean }>}
+ */
+export async function createFeature(featureName, options = {}) {
+  const { status = 'in_progress' } = options;
+  const state = loadState(false) || scaffoldState();
+
+  const existing = state.features[featureName];
+  if (existing) {
+    return { feature: existing, created: false };
+  }
+
+  const now = new Date().toISOString();
+  state.features[featureName] = {
+    status,
+    createdAt: now,
+    updatedAt: now,
+    activeAgents: [],
+    approvalGates: {
+      proposal: { approved: false, timestamp: null, approvedBy: null },
+      uiux: { approved: false, timestamp: null, approvedBy: null },
+      plan: { approved: false, timestamp: null, approvedBy: null },
+      review: { approved: false, timestamp: null, approvedBy: null }
+    },
+    gateDecisions: {},
+    taskScores: {},
+    tasks: {
+      total: 0,
+      completed: 0,
+      inProgress: 0,
+      pending: 0
+    },
+    checkpoints: [],
+    dispatchLog: [],
+    trustConfig: {},
+    contextBundles: [],
+    fileChanges: []
+  };
+
+  state.metadata.totalFeatures = Object.keys(state.features).length;
+  saveState(state);
+  return { feature: state.features[featureName], created: true };
+}
+
 /**
  * Update feature property (supports nested keys like "tasks.completed")
  * @param {string} featureName - Feature name

package/src/scripts/setup-infra.js

@@ -77,6 +77,8 @@ export function installRulesForStack(rulesSrc, rulesDest, projectTags) {
       unlinkSync(join(rulesDest, file));
     }
   }
+
+  return { installed: installed.size };
 }
 
 /**

package/src/utils/agents-installer.js

@@ -45,6 +45,26 @@ export function loadKnownMcpIds(frameworkDir) {
   }
 }
 
+/**
+ * Personas install-all default (friction fix, MORPH_GHLBrain 2026-07-11):
+ * with NO known stack tags (greenfield / install before config.json exists)
+ * EVERY persona is generated — a project that dispatches `morph-{id}` must
+ * find the subagent registered, and an install that only lands
+ * morph-evaluator forces every domain dispatch into the general-purpose
+ * fallback. Stack filtering only applies when the project's stack is KNOWN
+ * (tags non-empty): the fallback stays reserved for stacks the project
+ * genuinely does not have. Note this deliberately differs from rules/skills
+ * filtering (stack-filter.js), which stays minimal on greenfield.
+ *
+ * @param {object} agent - agents.json entry (with `stack`)
+ * @param {string[]} projectTags
+ * @returns {boolean}
+ */
+export function agentEligible(agent, projectTags = []) {
+  if (projectTags.length === 0) return true;
+  return shouldInstall(agent.stack ?? ['*'], projectTags);
+}
+
 const MANAGED_HEADER =
   '<!-- MANAGED BY morph-spec — generated from .morph/framework/agents.json (single source of truth).\n' +
   '     Do NOT edit by hand: changes are overwritten on `morph-spec update` / `setup-infra --reinstall`.\n' +
@@ -75,11 +95,8 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   const knownMcpIds = loadKnownMcpIds(frameworkDir);
 
-  // Filter by stack
-  const eligible = agents.filter(a => {
-    const stack = a.stack ?? ['*'];
-    return shouldInstall(stack, projectTags);
-  });
+  // Filter by stack — install-all when the stack is unknown (empty tags).
+  const eligible = agents.filter(a => agentEligible(a, projectTags));
 
   // Build set of all possible filenames for orphan cleanup
   const allPossible = new Set(agents.map(a => `morph-${a.id}.md`));
@@ -231,12 +248,11 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
   let expected = 0;
 
   for (const a of agents) {
-    const stack = a.stack ?? ['*'];
-    if (!shouldInstall(stack, projectTags)) continue;
+    if (!agentEligible(a, projectTags)) continue;
     expected++;
     const filename = `morph-${a.id}.md`;
     if (!installedFiles.has(filename)) {
-      missing.push({ name: a.title ?? a.id, stacks: stack });
+      missing.push({ name: a.title ?? a.id, stacks: a.stack ?? ['*'] });
     }
   }
 
@@ -276,8 +292,7 @@ export function checkAgentsDrift(projectDir, frameworkDir, projectTags = []) {
   let expected = 0;
 
   for (const agent of agents) {
-    const stack = agent.stack ?? ['*'];
-    if (!shouldInstall(stack, projectTags)) continue;
+    if (!agentEligible(agent, projectTags)) continue;
     expected++;
     const filename = `morph-${agent.id}.md`;
     const filePath = join(targetDir, filename);

package/src/utils/banner.js

@@ -1,6 +1,8 @@
 // src/utils/banner.js
 import chalk from "chalk";
-import { type as osType, release as osRelease } from "os";
+import { type as osType, release as osRelease, homedir } from "os";
+import { join } from "path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 
 const BRAND = chalk.hex("#7C3AED");
 const DIM = chalk.dim;
@@ -54,6 +56,39 @@ export function renderLogo(version) {
   return `\n${art}\n${rule}\n`;
 }
 
+/**
+ * Print the install banner once per version change, on the first CLI run
+ * after an install/upgrade. npm ≥7 swallows lifecycle-script output, so the
+ * postinstall banner is invisible on a normal `npm i -g` — this is the
+ * fallback that guarantees the next-steps guidance is actually seen.
+ *
+ * Marker: ~/.claude/morph-spec-banner-version (last version shown).
+ * Skips silently when stdout is not a TTY (piped/parsed output) or when
+ * MORPH_QUIET=1. Fail-open: any fs error just skips the banner.
+ *
+ * @param {{version: string, nodeVersion: string, markerDir?: string}} opts
+ * @returns {boolean} true if the banner was printed
+ */
+export function maybePrintFirstRunBanner({ version, nodeVersion, markerDir }) {
+  try {
+    if (!process.stdout.isTTY) return false;
+    if (process.env.MORPH_QUIET === "1") return false;
+
+    const dir = markerDir ?? join(homedir(), ".claude");
+    const marker = join(dir, "morph-spec-banner-version");
+    const last = existsSync(marker) ? readFileSync(marker, "utf8").trim() : null;
+    if (last === version) return false;
+
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(marker, version, "utf8");
+
+    printInstallBanner({ version, nodeVersion, results: [] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function platformLabel() {
   const t = osType();
   const r = osRelease().split(".").slice(0, 2).join(".");
@@ -78,18 +113,15 @@ export function printInstallBanner({ version, nodeVersion, results = [] }) {
       `  ${DIM("Spec-driven development harness for Claude Code")}`,
       `  ${DIM("by Polymorphism Tech")} ${DIM("·")} ${DIM("Node")} ${chalk.white(nodeVersion)} ${DIM("·")} ${chalk.white(platformLabel())}`,
       "",
-      sep("Installed"),
-      ...itemLines,
-      "",
+      ...(itemLines.length > 0 ? [sep("Installed"), ...itemLines, ""] : []),
       sep("Next · new project"),
       `  ${chalk.cyan("1.")} ${DIM("cd")} ${chalk.white("your-project")} ${DIM("(git repo)")}`,
       `  ${chalk.cyan("2.")} Run ${chalk.bold.white("morph-spec init")}`,
       `  ${chalk.cyan("3.")} Open it in Claude Code and run ${chalk.bold.white("/morph-init")}`,
       "",
       sep("Next · project already on morph-spec"),
-      `  ${chalk.cyan("1.")} Run ${chalk.bold.white("morph-spec update")} ${DIM("— sync everything")}`,
+      `  ${chalk.cyan("1.")} Run ${chalk.bold.white("morph-spec update")} ${DIM("— after a CLI upgrade or a project.stack change: full stack-aware resync")}`,
       `  ${chalk.cyan("2.")} Run ${chalk.bold.white("morph-spec doctor")} ${DIM("— validate installation")}`,
-      `  ${chalk.cyan("3.")} ${DIM("Check")} ${chalk.white(".morph/config/config.json → project.stack")} ${DIM("(drives which tools install)")}`,
       "",
     ].join("\n"),
   );

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.0.0';
+const HOOKS_VERSION = '3.1.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -103,7 +103,9 @@ const MORPH_HOOKS = [
   },
 
   // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +
-  // tasks.json schema guard (validate-and-warn; status enum, effort enum) ===
+  // tasks.json schema guard (validate-and-warn; status enum, effort enum) +
+  // trace auto-generation (tasks.json write → .morph/traces/, replaces the
+  // manual trace-writing step the skills used to carry) ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
@@ -116,6 +118,11 @@ const MORPH_HOOKS = [
         type: 'command',
         command: 'node framework/hooks/claude-code/core/tasks-json-guard.js',
         timeout: 3000
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/trace-autogen.js',
+        timeout: 3000
       }
     ]
   },
@@ -153,13 +160,34 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === Stop — build check + session snapshot ===
+  // === 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).
   {
     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/validate-completion.js'
+      command: 'node framework/hooks/claude-code/core/subagent-report-guard.js',
+      timeout: 5000
     }]
   }
 ];

package/src/utils/skills-installer.js

@@ -169,4 +169,6 @@ export async function installSkills(projectDir, { projectTags = [] } = {}) {
       rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
     }
   }
+
+  return { installed: installed.size };
 }