@polymorphism-tech/morph-spec 7.8.1 → 7.9.1

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,9 +113,7 @@ 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")}`,

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 };
 }