@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/utils/agents-installer.js

@@ -1,69 +1,24 @@
-/**
- * Agents Installer (v5)
- *
- * 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 8 personas (no tiers) across two axes — domain
- * (dotnet-senior, ef-modeler, maf-expert, nextjs-expert, ui-designer,
- * infra-engineer, verifier, reviewer, security) and stage (scout, read-only diagnosis before
- * implementation). Each persona is a subagent the Specialist (Claude in
- * implementer role) can dispatch. The 3 roles (Orchestrator/Specialist/
- * Evaluator) are assumed by Claude itself per MORPH.md, not as separate agents.
- */
-
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'path';
 import { shouldInstall } from '../lib/stack-filter.js';
 import { realEffects } from '../lib/installers/effects.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';
 
-/**
- * A persona that can change files: its effective tool scope grants Write or Edit.
- * Derived from the tools, so a persona made read-only stops being one.
- *
- * @param {object} agent - agents.json entry
- * @returns {boolean}
- */
+/** Derived from the effective tool scope (Write or Edit), so a persona made read-only stops being one. */
 export function isImplementer(agent) {
   const tools = String(agent?.tools ?? DEFAULT_AGENT_TOOLS).split(',').map((t) => t.trim());
   return tools.includes('Write') || tools.includes('Edit');
 }
 
-/**
- * Turn ceiling for a persona that omits agents.json `maxTurns` (ADR-004).
- *
- * 20 is the value the generator hardcoded before the field existed — the v4
- * Tier-2 default (commit 93aad05f) that survived the v5 flattening with no
- * recorded rationale. Keeping it as the default is what lets an old
- * agents.json render byte-for-byte the same .md as before.
- */
+// The value hardcoded before the field existed: an agents.json without `maxTurns` renders byte-for-byte as before.
 export const DEFAULT_MAX_TURNS = 20;
 
-/** Share of the ceiling (percent) at which a sub-agent checkpoints (partial report). */
 const CHECKPOINT_PERCENT = 70;
 
 /**
- * The ONE rule for a valid `maxTurns`. Four readers — installAgents,
- * checkAgentsDrift, doctor's validateAgentsJson and validate-framework.js
- * Check 6 — so the same agents.json can never pass in one and fail in another.
- *
- * Absent (`undefined`) is valid: it means "use the default". Anything present
- * must be an integer >= 1. `null` is NOT absent — whoever wants the default
- * removes the field.
- *
- * @param {unknown} value - the raw agents.json value
+ * The ONE validity rule, shared by installAgents, checkAgentsDrift, doctor and validate-framework.
+ * `undefined` means default; `null` is NOT absent.
  * @returns {string|null} what was expected, or null when valid
  */
 export function maxTurnsProblem(value) {
@@ -71,14 +26,6 @@ export function maxTurnsProblem(value) {
   return Number.isInteger(value) && value >= 1 ? null : 'esperado inteiro >= 1';
 }
 
-/**
- * The full message for an invalid `maxTurns` — persona, value received, what
- * is expected and how to get the default back. Every reader prints this one.
- *
- * @param {string} id - persona id (agents.json key)
- * @param {unknown} value - the raw agents.json value
- * @returns {string|null} null when valid
- */
 export function maxTurnsError(id, value) {
   const problem = maxTurnsProblem(value);
   if (!problem) return null;
@@ -89,41 +36,20 @@ export function maxTurnsError(id, value) {
     `Remova o campo para usar o default ${DEFAULT_MAX_TURNS}.`;
 }
 
-/**
- * Resolve the ceiling a persona is generated with: its `maxTurns`, or the
- * default when absent. Throws `maxTurnsError()` on an invalid value.
- *
- * @param {object} agent - agents.json entry with `id` merged in
- * @returns {number}
- */
 export function resolveMaxTurns(agent) {
   const error = maxTurnsError(agent.id, agent.maxTurns);
   if (error) throw new Error(error);
   return agent.maxTurns ?? DEFAULT_MAX_TURNS;
 }
 
-/** Values Claude Code accepts in a subagent's `effort` frontmatter. */
 export const VALID_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
 
-/**
- * The ONE rule for a valid `effort` — same four readers as `maxTurnsProblem`.
- * Absent means the frontmatter carries no `effort:` line and the sub-agent
- * inherits the session's effort, byte-for-byte what the generator emitted
- * before the field existed.
- *
- * @param {unknown} value - the raw agents.json value
- * @returns {string|null} what was expected, or null when valid
- */
+// Absent: no `effort:` line, so the sub-agent inherits the session effort.
 export function effortProblem(value) {
   if (value === undefined) return null;
   return VALID_EFFORTS.includes(value) ? null : `esperado um de ${VALID_EFFORTS.join('|')}`;
 }
 
-/**
- * @param {string} id - persona id (agents.json key)
- * @param {unknown} value - the raw agents.json value
- * @returns {string|null} null when valid
- */
 export function effortError(id, value) {
   const problem = effortProblem(value);
   if (!problem) return null;
@@ -131,26 +57,12 @@ export function effortError(id, value) {
     'Remova o campo para herdar o effort da sessão.';
 }
 
-/** A surface id is the key the mockup checklist names (`Superfície: admin-app`). */
 const SURFACE_ID_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 
 const SURFACE_KEYS = new Set(['when', 'standards']);
 
-/**
- * The ONE rule for a valid `surfaces` — the optional map that splits a
- * persona's standards by the kind of screen it works on
- * (`{ "admin-app": { when, standards: [ids] } }`). Same four readers as
- * `maxTurnsProblem`, for the same reason.
- *
- * Absent (`undefined`) is valid: the persona reads only `standards`. A standard
- * listed both in `standards` (read on every surface) and in a surface is
- * refused: that is exactly how a "separated" persona keeps loading marketing
- * standards on a CRUD screen without anyone noticing.
- *
- * @param {unknown} surfaces - the raw agents.json value
- * @param {unknown} [standards] - the persona's universal `standards`
- * @returns {string|null} what is wrong, or null when valid
- */
+// A standard both universal and in a surface is refused: the persona would keep
+// loading it on every surface without anyone noticing.
 export function surfacesProblem(surfaces, standards = []) {
   if (surfaces === undefined) return null;
   if (surfaces === null || typeof surfaces !== 'object' || Array.isArray(surfaces)) {
@@ -185,14 +97,6 @@ export function surfacesProblem(surfaces, standards = []) {
   return null;
 }
 
-/**
- * The full message for an invalid `surfaces`. Every reader prints this one.
- *
- * @param {string} id - persona id (agents.json key)
- * @param {unknown} surfaces
- * @param {unknown} [standards]
- * @returns {string|null} null when valid
- */
 export function surfacesError(id, surfaces, standards) {
   const problem = surfacesProblem(surfaces, standards);
   if (!problem) return null;
@@ -200,14 +104,7 @@ export function surfacesError(id, surfaces, standards) {
     'Remova o campo para a persona ler só `standards`.';
 }
 
-/**
- * Every standard id a persona can cite: the universal list plus each
- * surface's. Reference checks read this, so a surface id that does not exist
- * fails like any other.
- *
- * @param {object} persona - agents.json entry
- * @returns {string[]} unique ids, universal first
- */
+/** @returns {string[]} unique ids of `standards` plus every surface's, universal first */
 export function personaStandardIds(persona) {
   const ids = [...(Array.isArray(persona?.standards) ? persona.standards : [])];
   const surfaces = persona?.surfaces;
@@ -219,48 +116,22 @@ export function personaStandardIds(persona) {
   return [...new Set(ids)];
 }
 
-/** The first validity error of a persona entry, or null — what drift reports as `invalid`. */
 function personaError(agent) {
   return maxTurnsError(agent.id, agent.maxTurns)
     ?? surfacesError(agent.id, agent.surfaces, agent.standards)
     ?? effortError(agent.id, agent.effort);
 }
 
-/**
- * Tools every persona gets on top of its scope. A `tools:` line is a strict
- * allowlist: without `Skill` the sub-agent cannot invoke a single skill, and
- * without `ToolSearch` it cannot load an MCP tool the session defers.
- */
+// `tools:` is a strict allowlist: without Skill no skill runs, without ToolSearch no deferred MCP tool loads.
 export const PLATFORM_TOOLS = ['Skill', 'ToolSearch'];
 
-/**
- * The server names an MCP registry entry is granted under. Claude Code names a
- * server's tools after WHERE it is configured — `mcp__context7__*` from
- * `.mcp.json`, `mcp__plugin_context7_context7__*` from the plugin — and a grant
- * only matches its own spelling (measured 2026-09-24: `mcp__context7` gave a
- * plugin-installed context7 nothing). So every spelling becomes a grant; one
- * the project does not configure is inert.
- *
- * @param {string} id - registry key
- * @param {object} entry - registry entry
- * @returns {string[]}
- */
+// A grant matches only its own spelling (`mcp__context7` vs `mcp__plugin_context7_context7`),
+// so every spelling becomes a grant; one the project does not configure is inert.
 export function mcpServerNames(id, entry) {
-  // A malformed list falls back to the id instead of breaking the render:
-  // installAgents and checkAgentsDrift both go through here (fail-open).
   return serverNamesProblem(id, entry?.serverNames) === null ? entry?.serverNames ?? [id] : [id];
 }
 
-/**
- * The ONE rule for a registry entry's `serverNames` (validate-framework Check 8
- * reads it). Absent is valid (`[id]`). Present: non-empty, only the characters
- * Claude Code keeps in a tool name, and it must include the id itself — that is
- * the name the MCP installer writes into `.mcp.json`.
- *
- * @param {string} id - registry key
- * @param {unknown} value - the raw `serverNames`
- * @returns {string|null} what was expected, or null when valid
- */
+// Must include the id itself: that is the name the MCP installer writes into `.mcp.json`.
 export function serverNamesProblem(id, value) {
   if (value === undefined) return null;
   if (!Array.isArray(value) || value.length === 0) return 'esperado array não vazio';
@@ -269,15 +140,7 @@ export function serverNamesProblem(id, value) {
   return value.includes(id) ? null : `precisa incluir o próprio id "${id}"`;
 }
 
-/**
- * Load the MCP servers known to the framework registry
- * (framework/mcp/registry.json) with the server names each is granted under.
- * Only registry-known ids in agents.json `mcp` become tool grants (fail-open
- * on any error).
- *
- * @param {string} frameworkDir
- * @returns {Map<string, string[]>|null} id → server names; null = no registry found (accept nothing)
- */
+/** @returns {Map<string, string[]>|null} id → server names; null = no registry (grant nothing) */
 export function loadKnownMcpIds(frameworkDir) {
   try {
     const registryPath = join(frameworkDir, 'mcp', 'registry.json');
@@ -289,21 +152,8 @@ 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-verifier 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}
- */
+// With no known stack tags every persona is generated: a dispatch of `morph-{id}` must find
+// its subagent. Deliberately differs from rules/skills filtering.
 export function agentEligible(agent, projectTags = []) {
   if (projectTags.length === 0) return true;
   return shouldInstall(agent.stack ?? ['*'], projectTags);
@@ -314,17 +164,6 @@ const MANAGED_HEADER =
   '     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.
- *
- * @param {string} projectDir - Target project directory
- * @param {string} frameworkDir - Path to morph-spec framework/ directory
- * @param {object} options
- * @param {string[]} [options.projectTags=[]] - Stack tags from config (e.g. ['dotnet', 'nextjs'])
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
- *   Coletor de efeitos; o default executa e registra numa lista descartada.
- * @returns {Promise<{ installed: number }>}
- */
 export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
   const { projectTags = [], fx = realEffects() } = options;
 
@@ -336,8 +175,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     .filter(([key]) => !key.startsWith('_comment'))
     .map(([id, data]) => ({ id, ...data }));
 
-  // Validate EVERY persona before the first write: refusing halfway through
-  // would leave some personas regenerated and others stale.
+  // Validate every persona before the first write: refusing halfway leaves a mix of stale and fresh.
   for (const agent of agents) {
     const error = personaError(agent);
     if (error) throw new Error(error);
@@ -348,10 +186,8 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
 
   const knownMcpIds = loadKnownMcpIds(frameworkDir);
 
-  // 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`));
 
   let installed = 0;
@@ -373,12 +209,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     installed++;
   }
 
-  // Cleanup orphan morph-* files filtered out by stack.
-  //
-  // Calado em `dryRun` pelo mesmo motivo do laço gêmeo em skills-installer.js
-  // (D6): numa execução real do `update` este diretório acabou de ser apagado
-  // inteiro por `cleanFrameworkDirs()`, então o laço nunca remove nada. Num
-  // dry ingênuo ele veria o diretório antigo e preveria remoções inexistentes.
+  // Silent in dryRun: the real update's cleanFrameworkDirs() already emptied the dir.
   if (!fx.dryRun) {
     for (const file of readdirSync(targetDir)) {
       if (allPossible.has(file) && !installedFilenames.has(file)) {
@@ -390,20 +221,10 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
   return { installed, agents: installedAgents };
 }
 
-/**
- * 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 {Map<string, string[]>|null} [knownMcpIds] - registry-known MCP ids and
- *   their server names; agents.json `mcp` entries outside it are ignored (null = ignore all)
- * @returns {string} complete file content
- */
+// Deterministic: the doctor drift check compares files byte-for-byte against this output.
 export function renderAgentMd(agent, knownMcpIds = null) {
   const description = buildDescription(agent);
-  // Resolved ONCE: the frontmatter ceiling and the budget the body announces
-  // must be the same number — the sub-agent never sees its own frontmatter.
+  // One value for the frontmatter and the body: the sub-agent never sees its own frontmatter.
   const maxTurns = resolveMaxTurns(agent);
   const surfaces = surfacesError(agent.id, agent.surfaces, agent.standards);
   if (surfaces) throw new Error(surfaces);
@@ -417,9 +238,6 @@ export function renderAgentMd(agent, knownMcpIds = null) {
 function buildToolsLine(agent, knownMcpIds) {
   const base = String(agent.tools ?? DEFAULT_AGENT_TOOLS).split(',').map(t => t.trim()).filter(Boolean);
   const platform = PLATFORM_TOOLS.filter(t => !base.includes(t));
-  // Domain-relevant MCP servers (agents.json `mcp: [ids]`) become server-level
-  // grants, one per server name (`mcp__{name}`). 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))
     .flatMap(id => knownMcpIds.get(id).map(name => `mcp__${name}`));
@@ -428,16 +246,11 @@ function buildToolsLine(agent, knownMcpIds) {
 
 function buildFrontmatter(agent, description, knownMcpIds, maxTurns) {
   const lines = [
-    // Canonical 1:1 naming: frontmatter name === filename === subagent_type.
     `name: morph-${agent.id}`,
     `description: ${description}`,
-    // The verifier is sonnet here; the dispatch routes it to opus when the risk
-    // detector flags the diff. A persona without the field inherits the session model.
     `model: ${agent.model ?? 'inherit'}`,
     `tools: ${buildToolsLine(agent, knownMcpIds)}`,
-    // Per persona in agents.json (ADR-004); absent → DEFAULT_MAX_TURNS. The
-    // line keeps its position so an agents.json without the field renders
-    // exactly what the hardcoded `maxTurns: 20` rendered.
+    // Position fixed so an agents.json without the field renders byte-for-byte as before.
     `maxTurns: ${maxTurns}`,
   ];
   if (agent.effort) lines.push(`effort: ${agent.effort}`);
@@ -453,12 +266,6 @@ function buildDescription(agent) {
   return desc.length > 200 ? desc.slice(0, 197) + '...' : desc;
 }
 
-/**
- * The fixed half of every implementer dispatch. The orchestrator paraphrases
- * a prompt template in the field; the generated body is the only text a
- * dispatch is guaranteed to carry, so the contract lives here and the
- * dispatch carries only what changes per slice.
- */
 const NEON_CAUTION = 'NEON: o MCP `neon` inspeciona schema e ensaia migração numa branch descartável ' +
   '(prepare_database_migration → complete_database_migration); ele também APAGA branch e projeto — ' +
   'nunca chame tool destrutiva sem confirmação humana explícita.';
@@ -476,7 +283,7 @@ export const DISPATCH_CONTRACT = [
     'ANTES de encerrar — é o retorno autoritativo, não a sua mensagem final. `SendMessage` não é substituto do relatório e não deve ser chamado.',
   '2. ESTADO: NÃO toque em `plan.md`, `checks.json`, `feature.json`, `state.json` nem no board de sessão — todo estado é gravado exclusivamente pelo orquestrador.',
   '3. TESTE: a prova é do orquestrador (`morph-spec verify {feature}`, depois do seu retorno), não sua. Escreva os testes pelo orçamento: ' +
-    'um por pós-condição, um de regressão por bug, variantes numa tabela (`[Theory]`/`it.each`). NÃO rode teste a cada marco nem faça ciclo red→green: ' +
+    'um por Cn `prova: teste`, variantes em tabela (`[Theory]`/`it.each`); `leitura` sem teste. NÃO rode teste a cada marco nem faça ciclo red→green: ' +
     'escreva código e testes, compile, e rode SÓ o filtro dos seus testes UMA vez, em primeiro plano, antes do relatório; se falhar, corrija e rode só os que falharam. ' +
     'Grave a saída em arquivo (`… > .morph/logs/test-last.log 2>&1`, sem nada depois) e leia o arquivo — um pipe troca o exit do teste pelo do último comando. ' +
     'Em batch paralelo SEM isolamento, só compile. Com `isolation: "worktree"`, o mesmo vale no seu worktree, e o último ato é o commit na branch dele.',
@@ -518,7 +325,7 @@ function buildBody(agent, maxTurns) {
     '',
   ];
 
-  // The 5.3.0 shape (no effort, no surfaces, implementer) renders byte-for-byte as before.
+  // The shape without effort or surfaces renders byte-for-byte as the old fixture.
   const legacyShape = !agent.effort && !agent.surfaces && isImplementer(agent);
 
   if (legacyShape && agent.domains?.length) {
@@ -560,7 +367,6 @@ function buildBody(agent, maxTurns) {
       '',
     );
   } else {
-    // A read-only persona has no slice to implement nor scenario to report.
     lines.push(
       '## Como você opera',
       '',
@@ -571,22 +377,17 @@ function buildBody(agent, maxTurns) {
   }
 
   lines.push(
-    // `PARCIAL` on line 1 is what report-check reads; "no verdict" keeps an
-    // review partial from carrying a Verdict the gate would read as final.
+    // `PARCIAL` on line 1 is what report-check reads; "no verdict" keeps a partial
+    // review from carrying a Verdict the gate would read as final.
     '## Turn budget',
     '',
-    // Pasted into EVERY dispatch of every persona — kept to the minimum that
-    // still carries the contract (test/framework/maf-expert-persona.test.js
-    // pins the rendered size).
     `You have ${maxTurns} turns (\`maxTurns\`); at the ceiling you are cut off mid-work, without warning. ` +
       'One response is one turn, however many parallel tool calls it makes. ' +
       `By turn ${checkpointTurn(maxTurns)}, if your dispatch names a report file, save a partial there — ` +
       '`PARCIAL` on line 1, done, remaining, files, no verdict (final report only) — then continue or stop, your call; the final report replaces it.',
   );
 
-  // The dispatch template is paraphrased by the orchestrator in the field; this
-  // body is the only text every implementer dispatch is guaranteed to carry.
-  // Gated on `effort` so a persona without it renders byte-for-byte as before.
+  // The only text every implementer dispatch is guaranteed to carry.
   if (agent.effort && isImplementer(agent)) {
     lines.push(
       '',
@@ -603,30 +404,15 @@ function buildBody(agent, maxTurns) {
   return lines.join('\n');
 }
 
-/** The turn at which a sub-agent with `maxTurns` saves its partial report. */
 function checkpointTurn(maxTurns) {
-  // Integer arithmetic: 0.7 × N in floating point is not always exact.
+  // Integer arithmetic: 0.7 × N in floating point is not exact.
   return Math.max(1, Math.floor((maxTurns * CHECKPOINT_PERCENT) / 100));
 }
 
-/**
- * Compatibility shim for older callers that expected installDomainAgents.
- * In v5 there is no separate "domain" install step — installAgents handles
- * everything from agents.json.
- */
 export async function installDomainAgents(projectDir, frameworkDir, options) {
-  // No-op: domain content is now defined inline in agents.json (persona field).
   return { specialists: 0 };
 }
 
-/**
- * Check which agents SHOULD be installed but are NOT.
- *
- * @param {string} projectDir
- * @param {string} frameworkDir
- * @param {string[]} projectTags
- * @returns {{ missing: Array<{ name: string, stacks: string[] }>, installed: number, expected: number }}
- */
 export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
   const targetDir = join(projectDir, '.claude', 'agents');
   const installedFiles = new Set();
@@ -661,26 +447,8 @@ export function checkMissingAgents(projectDir, frameworkDir, projectTags = []) {
 }
 
 /**
- * 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. `staleFields` names
- *            what differs per file: the frontmatter keys, and `body`.
- * - invalid: persona whose agents.json entry cannot be rendered (an invalid
- *            `maxTurns` or `surfaces`) — reported with the reason instead of throwing, so
- *            the doctor prints the cause and not "failed to compute"
- * - orphans: morph-*.md files with no matching agents.json entry
- *
- * @param {string} projectDir
- * @param {string} frameworkDir - directory containing agents.json
- * @param {string[]} projectTags
- * @param {object} [options]
- * @param {string} [options.mcpRegistryDir=frameworkDir] - where `mcp/registry.json`
- *   lives. It must be the directory the INSTALLER read: an installed project's
- *   `.morph/framework/` carries agents.json but no `mcp/`, so rendering against
- *   it drops every `mcp__*` grant and flags a pristine install as stale.
+ * `mcpRegistryDir` must be where the INSTALLER read the registry: the installed
+ * `.morph/framework/` has no `mcp/`, and rendering against it flags a clean install as stale.
  * @returns {{ missing: string[], stale: string[], staleFields: Object<string, string[]>,
  *   invalid: Array<{ file: string, reason: string }>, orphans: string[], expected: number }}
  */
@@ -739,10 +507,6 @@ export function checkAgentsDrift(projectDir, frameworkDir, projectTags = [], opt
   return { missing, stale, staleFields, invalid, orphans, expected };
 }
 
-/**
- * Split a generated .md into its frontmatter map and the rest.
- * @returns {{ fields: Map<string, string>, body: string }}
- */
 function splitAgentMd(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
   if (!match) return { fields: new Map(), body: content };
@@ -754,11 +518,6 @@ function splitAgentMd(content) {
   return { fields, body: match[2] };
 }
 
-/**
- * Name what differs between a .md on disk and its render: the frontmatter
- * keys whose value (or presence) differs, in render order, then `body`.
- * A file with no parseable frontmatter differs in everything → `frontmatter`.
- */
 function diffAgentMd(onDisk, rendered) {
   const disk = splitAgentMd(onDisk);
   const want = splitAgentMd(rendered);
@@ -766,16 +525,10 @@ function diffAgentMd(onDisk, rendered) {
   const keys = [...new Set([...want.fields.keys(), ...disk.fields.keys()])];
   const fields = keys.filter(k => disk.fields.get(k) !== want.fields.get(k));
   if (disk.body !== want.body) fields.push('body');
-  // Bytes differ but no key/value does (e.g. a stray blank line between the
-  // fences): still drift, and it lives in the frontmatter.
+  // Bytes differ but no key/value does (a stray blank line between the fences).
   return fields.length > 0 ? fields : ['frontmatter'];
 }
 
-/**
- * Compatibility export — kept so existing tests/CLI code that imports
- * formatStandardRef or parseSkillFile / collectSkillFiles still work,
- * but they are no-ops (will be removed in v5.1).
- */
 export function formatStandardRef(standard) {
   if (typeof standard === 'string') return `- ${standard}`;
   const id = standard.id || String(standard);

package/src/utils/banner.js

@@ -1,4 +1,3 @@
-// src/utils/banner.js
 import chalk from "chalk";
 import { type as osType, release as osRelease, homedir } from "os";
 import { join } from "path";
@@ -7,7 +6,6 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 const BRAND = chalk.hex("#7C3AED");
 const DIM = chalk.dim;
 
-/** Purple gradient, one tone per logo line (top → bottom). */
 const GRADIENT = [
   "#6D28D9",
   "#7C3AED",
@@ -26,16 +24,8 @@ const LOGO_LINES = [
   "╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝",
 ];
 
-const LOGO_WIDTH = LOGO_LINES[0].length; // 44
+const LOGO_WIDTH = LOGO_LINES[0].length;
 
-/**
- * The morph-spec logo: gradient "MORPH" block art with a S P E C + version
- * rule underneath. Single source for the CLI help banner and the install
- * banner — one drawing, everywhere.
- *
- * @param {string} version - e.g. "7.7.2"
- * @returns {string}
- */
 export function renderLogo(version) {
   const art = LOGO_LINES.map(
     (line, i) => "  " + chalk.hex(GRADIENT[i])(line),
@@ -56,19 +46,8 @@ 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
- */
+// npm >=7 swallows postinstall output, so the first CLI run after an upgrade
+// shows the banner instead. Skips without a TTY or with MORPH_QUIET=1.
 export function maybePrintFirstRunBanner({ version, nodeVersion, markerDir }) {
   try {
     if (!process.stdout.isTTY) return false;
@@ -117,7 +96,7 @@ export function printInstallBanner({ version, nodeVersion, results = [] }) {
       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-proposal <feature>")}`,
+      `  ${chalk.cyan("3.")} Open it in Claude Code and run ${chalk.bold.white("/morph-plan <feature>")}`,
       "",
       sep("Next · project already on morph-spec"),
       `  ${chalk.cyan("1.")} Run ${chalk.bold.white("morph-spec update")} ${DIM("— after a CLI upgrade or a project.stack change: full stack-aware resync")}`,