@polymorphism-tech/morph-spec 7.5.0 → 7.7.0

package/src/utils/agents-installer.js

@@ -4,6 +4,15 @@
  * Installs morph-spec domain personas as native Claude Code subagents
  * in .claude/agents/morph-{id}.md.
  *
+ * agents.json is the SINGLE SOURCE OF TRUTH (ADR-001, docs/specs/
+ * dispatchable-personas/decisions.md). The .md files are DERIVED artifacts:
+ * generated with a MANAGED header, regenerated on update/--reinstall, and
+ * drift-checked by `morph-spec doctor` (checkAgentsDrift). Never hand-edit
+ * them — that is exactly the v4 dual-source drift the v5 migration removed.
+ *
+ * Canonical naming: subagent_type = `morph-{id}` — the frontmatter `name`
+ * matches the filename 1:1, and the skills dispatch that exact type.
+ *
  * In v5 the harness has 7 domain personas (no tiers) — each persona is a
  * subagent the Specialist (Claude in implementer role) can dispatch when
  * working in that domain. The 3 roles (Orchestrator/Specialist/Evaluator)
@@ -14,6 +23,33 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlink
 import { join } from 'path';
 import { shouldInstall } from '../lib/stack-filter.js';
 
+/** Default tool scope for domain personas (override per agent via agents.json `tools`). */
+export const DEFAULT_AGENT_TOOLS = 'Read, Write, Edit, Bash, Glob, Grep';
+
+/**
+ * Load the ids of MCP servers known to the framework registry
+ * (framework/mcp/registry.json). Used to validate agents.json `mcp` entries:
+ * only registry-known servers become tool grants (fail-open on any error).
+ *
+ * @param {string} frameworkDir
+ * @returns {Set<string>|null} null = no registry found (accept nothing)
+ */
+export function loadKnownMcpIds(frameworkDir) {
+  try {
+    const registryPath = join(frameworkDir, 'mcp', 'registry.json');
+    if (!existsSync(registryPath)) return null;
+    const registry = JSON.parse(readFileSync(registryPath, 'utf-8'));
+    return new Set(Object.keys(registry.mcps ?? {}));
+  } catch {
+    return null;
+  }
+}
+
+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' +
+  '     To change this persona, edit agents.json and regenerate. Drift is flagged by `morph-spec doctor`. -->';
+
 /**
  * Install morph-spec domain personas as native Claude Code subagents.
  *
@@ -37,6 +73,8 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
   const targetDir = join(projectDir, '.claude', 'agents');
   mkdirSync(targetDir, { recursive: true });
 
+  const knownMcpIds = loadKnownMcpIds(frameworkDir);
+
   // Filter by stack
   const eligible = agents.filter(a => {
     const stack = a.stack ?? ['*'];
@@ -48,17 +86,20 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   let installed = 0;
   const installedFilenames = new Set();
+  const installedAgents = [];
 
   for (const agent of eligible) {
     const filename = `morph-${agent.id}.md`;
     const targetPath = join(targetDir, filename);
 
-    const description = buildDescription(agent);
-    const body = buildBody(agent);
-    const frontmatter = buildFrontmatter(agent, description);
-
-    writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body}\n`, 'utf-8');
+    writeFileSync(targetPath, renderAgentMd(agent, knownMcpIds), 'utf-8');
     installedFilenames.add(filename);
+    installedAgents.push({
+      id: agent.id,
+      name: `morph-${agent.id}`,
+      title: agent.title ?? agent.id,
+      domains: agent.domains ?? [],
+    });
     installed++;
   }
 
@@ -69,15 +110,46 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     }
   }
 
-  return { installed };
+  return { installed, agents: installedAgents };
 }
 
-function buildFrontmatter(agent, description) {
+/**
+ * Render the full .md content for a persona — deterministic, so the same
+ * function serves the installer AND the doctor drift check (a hand-edited or
+ * stale file differs byte-for-byte from this output).
+ *
+ * @param {object} agent - agents.json entry with `id` merged in
+ * @param {Set<string>|null} [knownMcpIds] - registry-known MCP ids; agents.json
+ *   `mcp` entries outside this set are ignored (null = ignore all)
+ * @returns {string} complete file content
+ */
+export function renderAgentMd(agent, knownMcpIds = null) {
+  const description = buildDescription(agent);
+  const frontmatter = buildFrontmatter(agent, description, knownMcpIds);
+  const body = buildBody(agent);
+  return `---\n${frontmatter}---\n\n${MANAGED_HEADER}\n\n${body}\n`;
+}
+
+function buildToolsLine(agent, knownMcpIds) {
+  const base = agent.tools ?? DEFAULT_AGENT_TOOLS;
+  // Domain-relevant MCP servers (agents.json `mcp: [ids]`) become server-level
+  // grants (`mcp__{id}`). Only registry-known ids are emitted; in projects
+  // without that server configured the grant is inert.
+  const mcpGrants = (agent.mcp ?? [])
+    .filter(id => knownMcpIds?.has(id))
+    .map(id => `mcp__${id}`);
+  return [base, ...mcpGrants].join(', ');
+}
+
+function buildFrontmatter(agent, description, knownMcpIds) {
   const lines = [
-    `name: ${agent.id}`,
+    // Canonical 1:1 naming: frontmatter name === filename === subagent_type.
+    `name: morph-${agent.id}`,
     `description: ${description}`,
-    `model: sonnet`,
-    `tools: Read, Write, Edit, Bash, Glob, Grep`,
+    // Domain implementers inherit the session model by default — a hardcoded
+    // downgrade here would silently lower quality. Override via agents.json.
+    `model: ${agent.model ?? 'inherit'}`,
+    `tools: ${buildToolsLine(agent, knownMcpIds)}`,
     `maxTurns: 20`,
   ];
   if (agent.color) lines.push(`color: ${agent.color}`);
@@ -171,6 +243,66 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
   return { missing, installed: installedFiles.size, expected };
 }
 
+/**
+ * Drift check between agents.json (source of truth) and the generated
+ * .claude/agents/morph-*.md files. Consumed by `morph-spec doctor`.
+ *
+ * - missing: eligible persona with no .md installed → run setup-infra --reinstall
+ * - stale:   .md exists but differs from renderAgentMd() output (hand-edited
+ *            or generated by an older CLI) → regenerate
+ * - orphans: morph-*.md files with no matching agents.json entry
+ *
+ * @param {string} projectDir
+ * @param {string} frameworkDir - directory containing agents.json
+ * @param {string[]} projectTags
+ * @returns {{ missing: string[], stale: string[], orphans: string[], expected: number }}
+ */
+export function checkAgentsDrift(projectDir, frameworkDir, projectTags = []) {
+  const targetDir = join(projectDir, '.claude', 'agents');
+  const agentsJsonPath = join(frameworkDir, 'agents.json');
+  if (!existsSync(agentsJsonPath)) {
+    return { missing: [], stale: [], orphans: [], expected: 0 };
+  }
+
+  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
+  const agents = Object.entries(agentsJson.agents ?? {})
+    .filter(([key]) => !key.startsWith('_comment'))
+    .map(([id, data]) => ({ id, ...data }));
+
+  const knownMcpIds = loadKnownMcpIds(frameworkDir);
+  const knownFilenames = new Set(agents.map(a => `morph-${a.id}.md`));
+  const missing = [];
+  const stale = [];
+  let expected = 0;
+
+  for (const agent of agents) {
+    const stack = agent.stack ?? ['*'];
+    if (!shouldInstall(stack, projectTags)) continue;
+    expected++;
+    const filename = `morph-${agent.id}.md`;
+    const filePath = join(targetDir, filename);
+    if (!existsSync(filePath)) {
+      missing.push(filename);
+      continue;
+    }
+    const onDisk = readFileSync(filePath, 'utf-8').replace(/\r\n/g, '\n');
+    if (onDisk !== renderAgentMd(agent, knownMcpIds)) {
+      stale.push(filename);
+    }
+  }
+
+  const orphans = [];
+  if (existsSync(targetDir)) {
+    for (const file of readdirSync(targetDir)) {
+      if (file.startsWith('morph-') && file.endsWith('.md') && !knownFilenames.has(file)) {
+        orphans.push(file);
+      }
+    }
+  }
+
+  return { missing, stale, orphans, expected };
+}
+
 /**
  * Compatibility export — kept so existing tests/CLI code that imports
  * formatStandardRef or parseSkillFile / collectSkillFiles still work,

package/src/utils/hooks-installer.js

@@ -102,14 +102,22 @@ const MORPH_HOOKS = [
     ]
   },
 
-  // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) ===
+  // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +
+  // tasks.json schema guard (validate-and-warn; status enum, effort enum) ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
-    hooks: [{
-      type: 'command',
-      command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
-    }]
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/post-edit-typecheck.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/tasks-json-guard.js',
+        timeout: 3000
+      }
+    ]
   },
 
   // === PostToolUse: Write|Edit|AskUserQuestion — state-sync (autonomous state.json updates) ===

package/framework/rubrics/eval-rubric.json

@@ -1,66 +0,0 @@
-{
-  "id": "eval",
-  "version": "1.0.0",
-  "description": "Eval rubric for morph-eval system. Scores phase outputs across structural and semantic dimensions.",
-  "categories": {
-    "structural_compliance": {
-      "weight": 0.25,
-      "description": "Required sections, headers, formatting present in phase outputs",
-      "dimensions": {
-        "proposal": ["has_problem_statement", "has_proposed_solution", "min_length_300"],
-        "spec": ["has_overview", "has_functional_requirements", "has_fr_sections", "has_data_model"],
-        "tasks": ["has_task_headers", "has_fr_references", "no_duplicate_ids"],
-        "contracts": ["has_type_definitions", "correct_naming_conventions"]
-      }
-    },
-    "content_quality": {
-      "weight": 0.30,
-      "description": "LLM-as-judge: completeness, specificity, actionability of outputs",
-      "dimensions": {
-        "completeness": "Covers all aspects of the feature request",
-        "specificity": "Requirements are concrete and testable, not vague",
-        "actionability": "A developer could implement from this alone",
-        "architecture_depth": "Component boundaries, data flow, error handling clear"
-      }
-    },
-    "cross_phase_consistency": {
-      "weight": 0.25,
-      "description": "Alignment between spec, tasks, mandate, and contracts",
-      "dimensions": {
-        "fr_coverage": "Every spec FR referenced by at least one task",
-        "mandate_integrity": "Mandate includes all tasks with acceptance criteria",
-        "contract_alignment": "Spec Data Model entities appear in contracts",
-        "dependency_ordering": "Task dependencies are topologically valid"
-      }
-    },
-    "stack_appropriateness": {
-      "weight": 0.20,
-      "description": "Outputs match the target technology stack",
-      "dimensions": {
-        "correct_language": "Contracts use the right language for the stack (TS vs CS)",
-        "framework_patterns": "Architecture follows stack conventions (App Router, VSA, etc.)",
-        "tool_chain": "Build/test commands match the stack"
-      }
-    }
-  },
-  "thresholds": {
-    "approve": 8.0,
-    "retry": 6.0,
-    "max_iterations": 3,
-    "regression_tolerance": 0.5
-  },
-  "scoring": {
-    "structural": {
-      "method": "binary_checklist",
-      "description": "Each dimension is pass/fail. Score = (passed / total) * 10"
-    },
-    "llm_judge": {
-      "method": "evidence_based",
-      "description": "LLM scores 1-10 per dimension with evidence quotes and gap descriptions"
-    },
-    "cross_phase": {
-      "method": "ratio_based",
-      "description": "FR coverage ratio, mandate inclusion ratio. Score = ratio * 10"
-    }
-  }
-}

package/framework/templates/infrastructure/docker/easypanel.template.json

@@ -1,46 +0,0 @@
-{
-  "name": "{{kebabCase FEATURE_NAME}}",
-  "services": [
-    {
-      "type": "app",
-      "data": {
-        "projectName": "{{kebabCase FEATURE_NAME}}",
-        "serviceName": "{{kebabCase FEATURE_NAME}}-app",
-        "source": {
-          "type": "github",
-          "owner": "{{GITHUB_OWNER}}",
-          "repo": "{{GITHUB_REPO}}",
-          "ref": "main",
-          "autoDeploy": true
-        },
-        "build": {
-          "type": "dockerfile",
-          "dockerfile": "Dockerfile"
-        },
-        "deploy": {
-          "replicas": 1,
-          "command": null,
-          "zeroDowntime": true
-        },
-        "env": [
-          {
-            "key": "NODE_ENV",
-            "value": "production"
-          },
-          {
-            "key": "DATABASE_URL",
-            "value": "${DATABASE_URL}"
-          }
-        ],
-        "domains": [
-          {
-            "host": "{{kebabCase FEATURE_NAME}}.easypanel.host",
-            "port": 3000,
-            "https": true
-          }
-        ],
-        "mounts": []
-      }
-    }
-  ]
-}

package/framework/templates/infrastructure/github/workflows/deploy-easypanel.yml.hbs

@@ -1,31 +0,0 @@
-name: Deploy to EasyPanel
-
-on:
-  workflow_call:
-    inputs:
-      environment:
-        required: true
-        type: string
-      image:
-        required: true
-        type: string
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment: ${{{{ inputs.environment }}}}
-    steps:
-      - name: Trigger EasyPanel Deploy
-        run: |
-          curl -X POST ${{{{ secrets.EASYPANEL_WEBHOOK_URL }}}} \
-            -H "Authorization: Bearer ${{{{ secrets.EASYPANEL_API_TOKEN }}}}" \
-            -H "Content-Type: application/json" \
-            -d '{
-              "image": "${{{{ inputs.image }}}}",
-              "environment": "${{{{ inputs.environment }}}}"
-            }'
-
-      - name: Health Check
-        run: |
-          sleep 30  # Wait for deployment
-          curl --retry 10 --retry-delay 5 --retry-connrefused ${{{{ secrets.APP_URL }}}}/health