@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/commands/project/env.js

@@ -1,20 +1,3 @@
-/**
- * `morph-spec env [feature] [--json|--posix|--powershell]` — print the
- * dedicated environment of a worktree (port block + compose project) in a
- * shell-loadable form.
- *
- * Inside Claude Code the `worktree-env-inject` hook applies this block to
- * every dev-server / compose launcher automatically. This command is the same
- * contract for everything OUTSIDE the harness: a human terminal
- * (`eval "$(morph-spec env)"`), a CI step, a sub-agent running without hooks.
- * It derives from `buildComposeEnv` — the function the `verify` e2e node and
- * `e2e up` already use — so a shell and the stack can never disagree.
- *
- * Feature resolution: explicit argument, else the `morph/{f}` (or
- * `morph-task/{n}`) branch of the cwd. Read-only: allocation is idempotent and
- * never moves an existing block.
- */
-
 import { execFileSync } from 'child_process';
 import { readFileSync } from 'fs';
 import { join, resolve } from 'path';
@@ -49,14 +32,9 @@ function gitCommonDir(cwd) {
   }
 }
 
-/** POSIX single-quote. */
 const shq = (v) => `'${String(v).replace(/'/g, "'\\''")}'`;
 
-/**
- * Pure: the env map for a key, or `{ error }`.
- * @param {string|null} featureArg
- * @param {string} cwd
- */
+/** The env map for a key, or `{ error }`. */
 export function resolveWorktreeEnv(featureArg, cwd = process.cwd()) {
   const key = featureArg || envKeyFromBranch(currentBranch(cwd));
   if (!key) {
@@ -78,10 +56,6 @@ export function render(env, format) {
   return entries.map(([k, v]) => `export ${k}=${shq(v)}`).join('\n');
 }
 
-/**
- * @param {string|undefined} featureArg
- * @param {{ json?: boolean, posix?: boolean, powershell?: boolean }} options
- */
 export function envCommand(featureArg, options = {}) {
   const result = resolveWorktreeEnv(featureArg || null, process.cwd());
   if (result.error) {

package/src/commands/project/fleet.js

@@ -1,22 +1,7 @@
-/**
- * `morph-spec fleet [--json]` — the fleet view.
- *
- * One line per active feature across the primary root and every morph/*
- * worktree: phase, pending gates, slice progress, port block, handoff
- * freshness, last commit and dirtiness. This is the terminal surface the
- * operator scans between sessions ("what is each instance doing, what is
- * waiting on me") — `worktree list` remains the lean per-worktree view.
- *
- * Read-only, always exits 0 (fail-open — an empty fleet is an answer).
- */
-
 import chalk from 'chalk';
 import { scanFleet } from '../../lib/worktree/fleet-scanner.js';
 import { claimAge } from '../../../framework/hooks/shared/claim-registry.js';
 
-/**
- * @param {{ json?: boolean, cwd?: string }} [options]
- */
 export function fleetCommand(options = {}) {
   const fleet = scanFleet(options.cwd || process.cwd());
 
@@ -32,22 +17,13 @@ export function fleetCommand(options = {}) {
 
   const col = (s, w) => String(s ?? '-').padEnd(w);
 
-  /**
-   * The REMOTO cell. `-` means "unknown" (no origin, or the probe failed) —
-   * deliberately the same glyph as "nothing there", because both mean "do not
-   * trust the local view alone". `local` is the confident negative.
-   */
+  /** `-` (unknown) shares the "nothing there" glyph on purpose: both mean "do not trust the local view alone". */
   const remoteCell = (r) => {
     if (!r) return '-';
     if (r.pr) return `PR #${r.pr.number}${r.pr.state && r.pr.state !== 'OPEN' ? ` (${r.pr.state.toLowerCase()})` : ''}`;
     return r.pushed ? 'pushed' : 'local';
   };
 
-  /**
-   * The CLAIM cell — who is on this feature right now (B1). A stale claim is
-   * shown as stale, not hidden: "nobody here" and "somebody died here" are
-   * different facts for the operator.
-   */
   const claimCell = (c) => {
     if (!c) return '-';
     const age = claimAge(c);
@@ -55,10 +31,7 @@ export function fleetCommand(options = {}) {
   };
 
   console.log(chalk.white.bold(
-    // PHASE at 18: `aguardando-merge` (the pr-pending synthesized phase, see
-    // fleet-scanner.js) is 16 chars — 1 wider than the col width `list.js`
-    // already uses (17) for the identical string. A narrower column here
-    // would misalign every column after it just for that one row.
+    // PHASE at 18 fits `aguardando-merge`; narrower misaligns every column after it.
     col('FEATURE', 20) + col('TYPE', 9) + col('PHASE', 18) + col('FATIAS', 8)
     + col('GATES PEND.', 20) + col('WHERE', 24) + col('REMOTO', 16) + col('CLAIM', 16)
     + col('PORTS', 12) + col('HANDOFF', 9) + 'ATIVIDADE',
@@ -66,9 +39,7 @@ export function fleetCommand(options = {}) {
   for (const e of fleet.entries) {
     const slices = e.slices ? `${e.slices.done}/${e.slices.total}` : '-';
     const gates = e.pendingGates.length ? e.pendingGates.join(',') : '-';
-    // pr-pending has no worktree and isn't root-resident either — its branch
-    // is the only place it exists, so show that instead of the misleading
-    // 'raiz' a location-blind check would print.
+    // pr-pending exists only on its branch, never in a worktree or the root.
     const where = (e.location === 'worktree' || e.location === 'pr-pending') ? e.branch : 'raiz';
     const ports = e.env ? `${e.env.range[0]}-${e.env.range[1]}` : '-';
     const handoff = e.handoff?.exists ? 'sim' : '-';

package/src/commands/project/init.js

@@ -37,25 +37,8 @@ import { resolvePrimaryRoot } from './worktree.js';
 import { registerProject } from '../../lib/projects/registry.js';
 
 /**
- * Guard against running a full `init` install from inside a secondary
- * (linked) git worktree.
- *
- * A worktree's `.claude/` and `.morph/framework/` are junctions back to the
- * primary root (see `worktree.js`'s `setupInfraLinks`), but `.morph/config/`,
- * `.morph/context/`, `.morph/checkpoints/`, `.morph/memory/`, `.morph/archive/`
- * and `.morph/state.json` are NOT linked — a full `init` there would scaffold
- * a second, disconnected install (config, state) inside the worktree, orphaned
- * from the primary root's real install.
- *
- * Fail-SAFE (not fail-open): blocks whenever `resolvePrimaryRoot(targetPath)`
- * resolves to a path OTHER than `targetPath` itself. `resolvePrimaryRoot`
- * itself fails open to `targetPath` outside a git repo (or on any git error),
- * so non-git projects and the primary root itself are never blocked.
- * `--force` is the explicit override, mirroring init's own `--force` flag.
- *
- * @param {string} targetPath - Effective install target (init's targetPath)
- * @param {{ force?: boolean }} [options]
- * @returns {{ blocked: boolean, root?: string, target?: string }}
+ * A linked worktree junctions `.claude/` and `.morph/framework/` but not `.morph/config`/state:
+ * a full install there orphans a second, disconnected one. `--force` overrides.
  */
 export function checkSecondaryWorktreeGuard(targetPath, options = {}) {
   if (options.force) return { blocked: false };
@@ -72,9 +55,6 @@ export async function initCommand(options) {
   logger.dim(`Target: ${targetPath}`);
   logger.blank();
 
-  // Guard: refuse a full install from inside a secondary worktree — it would
-  // corrupt the shared infra junctioned back to the primary root and scaffold
-  // a second, disconnected .morph/config + state.json. --force overrides.
   const worktreeGuard = checkSecondaryWorktreeGuard(targetPath, options);
   if (worktreeGuard.blocked) {
     logger.warn(`Você está num worktree secundário (${worktreeGuard.target}).`);
@@ -83,11 +63,9 @@ export async function initCommand(options) {
     process.exit(0);
   }
 
-  // Check if already initialized
   const morphPath = join(targetPath, '.morph');
   if (await pathExists(morphPath)) {
     if (!options.force) {
-      // Check if project version is outdated — auto-update instead of blocking
       const projectCheck = await checkProjectOutdated(targetPath);
       if (projectCheck.isOutdated) {
         logger.info(`MORPH already initialized (v${projectCheck.current}). Framework update available (v${projectCheck.cliVersion}).`);
@@ -105,11 +83,8 @@ export async function initCommand(options) {
 
   try {
 
-    // Steps 1-10: Infrastructure (headless, no prompts)
     spinner.stop();
-    // force: true — the secondary-worktree guard already ran above (either we
-    // ARE the primary root, or the caller explicitly passed --force), so it
-    // must not be redundantly re-applied inside setupInfra().
+    // The secondary-worktree guard already ran above; setupInfra must not re-apply it.
     const infraResult = await setupInfra(targetPath, { force: true });
     if (infraResult?.refused) {
       process.exitCode = 1;
@@ -117,23 +92,18 @@ export async function initCommand(options) {
     }
     spinner.start('Continuing...');
 
-    // Derive display variables from what setupInfra installed
     const cliVersion = getInstalledCLIVersion();
     const commandsCopied = await pathExists(join(targetPath, '.claude', 'commands'));
     const rulesCopied = await pathExists(join(targetPath, '.claude', 'rules'));
-    // Re-run installClaudeHooks to get the result object (idempotent — hooks already installed)
     const hooksResult = await installClaudeHooks(targetPath);
 
-    // Re-derive config path for stack detection updates
     const configDir = join(morphPath, 'config');
     const configPath = join(configDir, 'config.json');
     const contextDir = join(morphPath, 'context');
 
-    // Read config written by setupInfra so stack detection can update it
     let config = (await pathExists(configPath)) ? await readJson(configPath) : { project: {} };
     if (!config.project) config.project = {};
 
-    // 11b. Detect Claude Code environment (plugins, MCPs, skills)
     spinner.text = 'Detecting Claude Code environment...';
     let claudeConfigDetected = null;
     let integrationsCreated = false;
@@ -152,14 +122,6 @@ export async function initCommand(options) {
           logger.info(summary);
         }
 
-        // Show MCP-to-phase mapping.
-        //
-        // This called mapMcpsToPhases with one argument where it takes three,
-        // so `phaseMatrix[currentPhase]` threw a TypeError on every project
-        // that had any MCP configured. The outer catch reported it as
-        // "Claude config detection skipped" — which reads like "nothing to
-        // detect" — and everything below it never ran: integrations.json was
-        // never written and the optimized settings were never generated.
         if (claudeConfigDetected.mcpServers.length > 0) {
           const byPhase = mcpAvailabilityByPhase(
             claudeConfigDetected.mcpServers,
@@ -195,11 +157,9 @@ export async function initCommand(options) {
         }
       }
     } catch (error) {
-      // Non-fatal: continue without integrations
       logger.dim(`  Claude config detection skipped: ${error.message}`);
     }
 
-    // 11c. Stack detection (moved before MCP setup so we know the stack)
     spinner.text = 'Detecting project stack...';
     let detectedStack = 'unknown';
     const hasProjectFiles = await pathExists(join(targetPath, 'package.json'))
@@ -214,7 +174,6 @@ export async function initCommand(options) {
         if (structure?.stack && structure.stack !== 'unknown') {
           detectedStack = structure.stack;
 
-          // Persist detected stack to config.json
           if (structure?.stack && structure.stack !== 'unknown') {
             config.project.stack = structure.stack;
           }
@@ -256,23 +215,19 @@ export async function initCommand(options) {
             logger.dim('Review and edit .morph/context/standards.md as needed.');
           }
 
-          // Re-install stack-filtered assets now that we know the stack
           const stackTags = getProjectTags(config);
           if (stackTags.length > 0) {
             spinner.start('Re-installing stack-filtered assets...');
             const frameworkDir = join(targetPath, '.morph', 'framework');
             const fwSrcDir = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'framework');
 
-            // Rules
             const rulesSrc = join(fwSrcDir, 'rules');
             const rulesDest = join(targetPath, '.claude', 'rules');
             installRulesForStack(rulesSrc, rulesDest, stackTags);
             installCommandsForStack(join(fwSrcDir, 'commands'), join(targetPath, '.claude', 'commands'), stackTags);
 
-            // Skills
             await installSkills(targetPath, { projectTags: stackTags });
 
-            // Agents (domain personas from agents.json)
             await installAgents(targetPath, fwSrcDir, { projectTags: stackTags });
             await installDomainAgents(targetPath, fwSrcDir, { projectTags: stackTags });
 
@@ -286,7 +241,6 @@ export async function initCommand(options) {
       }
     }
 
-    // 11d. MCP Auto-Setup
     let mcpSetupResult = null;
     if (!options.skipMcp) {
       try {
@@ -304,7 +258,6 @@ export async function initCommand(options) {
           logger.blank();
           logger.header('MCP Server Setup');
 
-          // Auto-install prompt
           let autoInstalled = {};
           if (hasAutoMcps) {
             const { installAuto } = await inquirer.prompt([{
@@ -322,7 +275,6 @@ export async function initCommand(options) {
                 autoInstalled[name] = orchestration.autoInstallable[name];
               }
 
-              // Install companion skills for MCPs that define them (e.g., Stitch agent skills)
               const skillResults = installCompanionSkills(orchestration.autoInstallable);
               for (const r of skillResults) {
                 if (r.success) {
@@ -334,13 +286,11 @@ export async function initCommand(options) {
             }
           }
 
-          // Credential MCPs — inline setup or instructions
           const manualInstalled = {};
           if (hasManualMcps) {
             for (const [name, entry] of Object.entries(orchestration.needsManualSetup)) {
               logger.blank();
 
-              // Show warnings
               for (const warning of entry.install.warnings || []) {
                 logger.warn(`  ${warning}`);
               }
@@ -354,7 +304,6 @@ export async function initCommand(options) {
               }]);
 
               if (setupNow) {
-                // Stitch — automated setup via setupStitch()
                 if (name === 'stitch' && !entry.install.autoInstall) {
                   spinner.start('Setting up Stitch MCP...');
                   const stitchResult = await setupStitch(targetPath);
@@ -374,7 +323,6 @@ export async function initCommand(options) {
                   continue;
                 }
 
-                // Remote MCPs — launch OAuth via claude mcp add
                 if (isRemoteMcp(entry.install.config)) {
                   const url = entry.install.config.url;
                   logger.info(`  Launching ${capitalizedName} OAuth authentication...`);
@@ -391,7 +339,6 @@ export async function initCommand(options) {
                   continue;
                 }
 
-                // Collect credentials
                 const credentialValues = {};
                 for (const cred of entry.install.credentials) {
                   const { value } = await inquirer.prompt([{
@@ -408,7 +355,6 @@ export async function initCommand(options) {
                 spinner.succeed(`${capitalizedName} MCP configured`);
                 manualInstalled[name] = entry;
               } else {
-                // Show setup instructions
                 const instructions = generateSetupInstructions(name, entry);
                 logger.blank();
                 logger.dim('  Add to .mcp.json → mcpServers:');
@@ -426,7 +372,6 @@ export async function initCommand(options) {
             }
           }
 
-          // Summary table
           const justInstalled = { ...autoInstalled, ...manualInstalled };
           const statusRows = formatMcpStatusTable(orchestration, justInstalled);
 
@@ -460,7 +405,6 @@ export async function initCommand(options) {
       logger.dim('\nSkipped MCP setup (--skip-mcp flag)');
     }
 
-    // Auto-generate architecture context (non-blocking on failure)
     spinner.text = 'Generating architecture context...';
     try {
       const { scanArchitecture, renderArchitectureContext } = await import('../../lib/generators/architecture-scanner.js');
@@ -468,15 +412,12 @@ export async function initCommand(options) {
       await renderArchitectureContext(targetPath, scanResult);
       spinner.succeed('Architecture context generated');
     } catch {
-      // Non-fatal: placeholder README.md remains
       spinner.warn('Architecture context generation skipped');
     }
 
     spinner.succeed('MORPH-SPEC installed successfully!');
-    // The dashboard's portfolio learns about the project here (fail-open).
     registerProject(targetPath, 'init');
 
-    // Show next steps
     logger.blank();
     logger.success(`MORPH-SPEC v${cliVersion} installed successfully!`);
     logger.blank();
@@ -517,7 +458,6 @@ export async function initCommand(options) {
 
     logger.dim('  ✓ .claude/skills/ (installed as skill directories)');
 
-    // Show agent team breakdown from setup-infra result
     const agents = infraResult?.agents;
     if (agents) {
       const total = (agents.tier1 || 0) + (agents.tier2 || 0) + (agents.specialists || 0) + (agents.personas || 0);
@@ -528,7 +468,6 @@ export async function initCommand(options) {
 
     logger.dim('  ✓ ~/.claude/statusline.sh (global statusline installed)');
 
-    // Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS in ~/.claude/settings.local.json
     logger.blank();
     const globalSettingsPath = join(homedir(), '.claude', 'settings.local.json');
     let agentTeamsEnabled = false;
@@ -536,7 +475,6 @@ export async function initCommand(options) {
       const globalSettings = await readJson(globalSettingsPath);
       agentTeamsEnabled = globalSettings?.env?.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS === '1';
     } catch {
-      // File missing or unreadable — treat as not enabled
     }
 
     if (agentTeamsEnabled) {
@@ -548,7 +486,6 @@ export async function initCommand(options) {
 
     logger.blank();
 
-    // Populate Claude Code persistent memory so future sessions enter contextualized
     try {
       const { installProjectMemory } = await import('../../lib/installers/memory-installer.js');
       const memResult = await installProjectMemory(targetPath, {
@@ -561,10 +498,9 @@ export async function initCommand(options) {
       logger.dim(`  ⚠ Memory install skipped: ${err.message}`);
     }
 
-    // Suggest tutorial for first-time users
     if (integrationsCreated) {
       logger.blank();
-      logger.info('First time using morph-spec? Run `/morph-proposal <feature>` to start a new feature.');
+      logger.info('First time using morph-spec? Run `/morph-plan <feature>` to start a new feature.');
     }
 
     logger.blank();

package/src/commands/project/install-plugin-cmd.js

@@ -1,4 +1,3 @@
-// src/commands/project/install-plugin-cmd.js
 import { installPlugin } from '../../scripts/install-plugin.js';
 import { logger } from '../../utils/logger.js';
 

package/src/commands/project/standards.js

@@ -1,30 +1,10 @@
-/**
- * `morph-spec standards [--find "<query>"] [--show <id>[#<anchor>]] [--category <c>] [--tags <a,b>] [--json]`
- *
- * `--find` scores the registry server-side and returns the TOP 3 hits with
- * digest and anchor keys, so nobody reads the whole registry to pick a
- * standard. `--show <id>#<anchor>` prints only that section of the .md;
- * `--show <id>` prints the digest and the anchors. Bare call: categories + counts.
- *
- * A query with no hit exits 0 (advisory, not a gate); under `--json` the
- * shape stays `{ query, results: [], suggestion }`.
- */
-
 import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import chalk from 'chalk';
 import { loadStandardsRegistry } from '../../lib/standards/registry.js';
 import { markdownHeadings, sectionBySlug } from '../../lib/standards/sections.js';
 
-/**
- * Resolve STANDARDS.json the same way doctor.js resolves the standards root:
- * an installed project first (`.morph/framework/standards/`), falling back
- * to this package's own bundled copy (`framework/standards/`) — the framework
- * repo in dev, or the npm package's own copy before `setup-infra` has run.
- *
- * @param {string} targetPath - project root to look for `.morph/` under
- * @returns {string|null} absolute path to STANDARDS.json, or null if neither exists
- */
+/** Installed project first, else this package's bundled copy (dev repo, or before `setup-infra` ran). */
 export function resolveStandardsJsonPath(targetPath) {
   const installed = join(targetPath, '.morph', 'framework', 'standards', 'STANDARDS.json');
   if (existsSync(installed)) return installed;
@@ -35,13 +15,6 @@ export function resolveStandardsJsonPath(targetPath) {
   return null;
 }
 
-/**
- * The one section a `--show` target names. `anchor` is an anchor key of the
- * registry entry (`regra`) or any heading slug of the .md (`#regra-principal`).
- * @returns {{ status: 'ok', section: string, slug: string }
- *   | { status: 'unknown-anchor', anchors: Record<string, string>, headings: string[] }
- *   | { status: 'unreadable' }}
- */
 export function resolveStandardSection(standard, mdText, anchor) {
   if (mdText === null) return { status: 'unreadable' };
   const anchors = standard.anchors || {};
@@ -98,11 +71,6 @@ function showStandard(standards, standardsJsonPath, target, json) {
   process.exit(1);
 }
 
-/**
- * category → count, sorted by count desc then name asc.
- * @param {object[]} standards
- * @returns {{ category: string, count: number }[]}
- */
 export function categoryCounts(standards) {
   const counts = {};
   for (const std of standards) {
@@ -114,16 +82,6 @@ export function categoryCounts(standards) {
     .sort((a, b) => b.count - a.count || a.category.localeCompare(b.category));
 }
 
-/**
- * Simple weighted relevance score for one standard against a query.
- * Tiers, as specified: name/id > tags(+aliases) > digest. category/subcategory
- * ride alongside the tags tier (lighter). A token-level fallback keeps
- * multi-word queries findable even without a verbatim phrase match anywhere.
- *
- * @param {object} std - one STANDARDS.json entry
- * @param {string} query - raw user query (already trimmed, non-empty)
- * @returns {number} score, 0 = no match
- */
 export function scoreStandard(std, query) {
   const q = query.toLowerCase();
   const tokens = q.split(/\s+/).filter((t) => t.length >= 3);
@@ -138,19 +96,15 @@ export function scoreStandard(std, query) {
 
   let score = 0;
 
-  // Tier 1: name / id — the strongest signal.
   if (id === q || name === q) score += 20;
   else if (id.includes(q) || name.includes(q)) score += 12;
 
-  // Tier 2: tags / aliases (curated search terms) + category/subcategory.
   if (tags.includes(q) || aliases.includes(q)) score += 8;
   else if (tags.some((t) => t.includes(q)) || aliases.some((a) => a.includes(q))) score += 5;
   if (category === q || subcategory === q) score += 4;
 
-  // Tier 3: digest — weakest signal, full-phrase substring only.
   if (digest.includes(q)) score += 2;
 
-  // Token-level fallback for multi-word queries with no verbatim match above.
   for (const tok of tokens) {
     if (name.includes(tok) || id.includes(tok)) score += 2;
     if (tags.some((t) => t.includes(tok)) || aliases.some((a) => a.includes(tok))) score += 1;
@@ -160,15 +114,6 @@ export function scoreStandard(std, query) {
   return score;
 }
 
-/**
- * Rank standards against a query, applying optional category/tags filters
- * first. Returns the TOP 3 with score > 0, sorted desc (ties broken by id).
- *
- * @param {object[]} standards
- * @param {string} query
- * @param {{ category?: string, tags?: string[] }} [filters]
- * @returns {Array<object & { score: number }>}
- */
 export function findStandards(standards, query, filters = {}) {
   const category = filters.category?.toLowerCase();
   const tags = (filters.tags || []).map((t) => t.toLowerCase());
@@ -189,15 +134,11 @@ export function findStandards(standards, query, filters = {}) {
     .slice(0, 3);
 }
 
-/** Parse `--tags a,b,c` into a trimmed, non-empty array. */
 function parseTagsOption(raw) {
   if (!raw) return [];
   return String(raw).split(',').map((t) => t.trim()).filter(Boolean);
 }
 
-/**
- * @param {{ find?: string, show?: string, category?: string, tags?: string, json?: boolean, cwd?: string }} [options]
- */
 export function standardsCommand(options = {}) {
   const cwd = options.cwd || process.cwd();
   const standardsJsonPath = resolveStandardsJsonPath(cwd);
@@ -220,7 +161,6 @@ export function standardsCommand(options = {}) {
   if (options.show) showStandard(standards, standardsJsonPath, options.show, options.json);
   const query = (options.find || '').trim();
 
-  // ── Bare call (no --find): categories + counts, cheap orientation ────────
   if (!query) {
     const counts = categoryCounts(standards);
     if (options.json) {
@@ -236,7 +176,6 @@ export function standardsCommand(options = {}) {
     process.exit(0);
   }
 
-  // ── --find: score + filter ────────────────────────────────────────────
   const filters = { category: options.category, tags: parseTagsOption(options.tags) };
   const results = findStandards(standards, query, filters);