@polymorphism-tech/morph-spec 8.32.0 → 8.34.2

package/src/lib/validators/shared/emit-validator-dispatch.js

@@ -1,14 +1,14 @@
-/**
- * Stub: validation dispatch was driven by tier-4 agents in v4.
- * In v5, validation is handled by morph-eval skill invoked directly
- * by the Evaluator role. This function is kept for call-site compatibility.
- *
- * @module emit-validator-dispatch
- */
-
-/**
- * No-op in v5. Validation dispatch is now handled by morph-eval skill.
- */
-export async function emitValidatorDispatch(_featureName, _phase, _cwd) {
-  // v5: evaluation driven by morph-eval skill, not CLI dispatch
-}
+/**
+ * Stub: validation dispatch was driven by tier-4 agents in v4.
+ * In v5, validation is handled by morph-eval skill invoked directly
+ * by the Evaluator role. This function is kept for call-site compatibility.
+ *
+ * @module emit-validator-dispatch
+ */
+
+/**
+ * No-op in v5. Validation dispatch is now handled by morph-eval skill.
+ */
+export async function emitValidatorDispatch(_featureName, _phase, _cwd) {
+  // v5: evaluation driven by morph-eval skill, not CLI dispatch
+}

package/src/lib/validators/shared/issue-counter.js

@@ -1,14 +1,14 @@
-/**
- * Shared issue counting utility for validators
- *
- *
- * @param {Array} issues - Array of validation issues with type property
- * @returns {{errors: number, warnings: number, infos: number}} Count by type
- */
-export function countIssues(issues) {
-  return {
-    errors: issues.filter((i) => i.type === 'error').length,
-    warnings: issues.filter((i) => i.type === 'warning').length,
-    infos: issues.filter((i) => i.type === 'info').length,
-  };
-}
+/**
+ * Shared issue counting utility for validators
+ *
+ *
+ * @param {Array} issues - Array of validation issues with type property
+ * @returns {{errors: number, warnings: number, infos: number}} Count by type
+ */
+export function countIssues(issues) {
+  return {
+    errors: issues.filter((i) => i.type === 'error').length,
+    warnings: issues.filter((i) => i.type === 'warning').length,
+    infos: issues.filter((i) => i.type === 'info').length,
+  };
+}

package/src/lib/validators/verify-runner.js

@@ -48,7 +48,8 @@ const OUTPUT_TAIL_LINES = 20;
  * @param {string|null} [taskId] - Task ID for task-scoped verify, or null/undefined for feature scope
  * @param {Object} [options]
  * @param {string} [options.rubric] - Force a rubric id (highest precedence)
- * @param {number} [options.timeout] - Build timeout in ms (default 120000)
+ * @param {number} [options.timeout] - Timeout in ms for the build AND tests nodes
+ *   (default: 120000 for build; for tests, see resolveTestTimeout())
  * @param {boolean} [options.skipTests] - Skip the tests node
  * @param {boolean} [options.skipBuild] - Skip the build node
  * @param {boolean} [options.skipE2e] - Skip the e2e node
@@ -86,7 +87,18 @@ export async function runVerify(projectPath, featureName, taskId, options = {})
   appendBuildFeedback(feedback, nodes.build);
 
   // 2. tests — skipped entirely (no invocation) when build already failed.
-  nodes.tests = await runTestsNode({ projectPath, skipTests, buildNode: nodes.build, _runTestSuite });
+  // The tests node gets the SAME --timeout the user typed, but only when they
+  // typed one: `timeout` above is defaulted for the build, and passing that
+  // default down would silently outrank config.project.testTimeoutMs and the
+  // per-project scaling (see resolveTestTimeout()).
+  const explicitTimeout = Number.isFinite(options.timeout) ? options.timeout : undefined;
+  nodes.tests = await runTestsNode({
+    projectPath,
+    skipTests,
+    buildNode: nodes.build,
+    timeout: explicitTimeout,
+    _runTestSuite,
+  });
   appendTestsFeedback(feedback, nodes.tests);
 
   // 3. validators — ALWAYS runs, even on a red build (free static feedback).
@@ -174,7 +186,7 @@ function appendBuildFeedback(feedback, buildNode) {
 // Tests node
 // ============================================================================
 
-async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }) {
+async function runTestsNode({ projectPath, skipTests, buildNode, timeout, _runTestSuite }) {
   const command = resolveTestCommand(projectPath);
 
   if (skipTests) {
@@ -192,7 +204,7 @@ async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }
   }
 
   const start = Date.now();
-  const result = await _runTestSuite(projectPath);
+  const result = await _runTestSuite(projectPath, { timeout });
   const durationMs = Date.now() - start;
 
   if (result.skipped) {
@@ -205,6 +217,20 @@ async function runTestsNode({ projectPath, skipTests, buildNode, _runTestSuite }
     };
   }
 
+  // A timeout has no verdict to report: the tail of a truncated log reads like
+  // a passing run cut mid-sentence. Lead with what actually happened.
+  if (result.timedOut) {
+    const tail = tailLines(result.output, OUTPUT_TAIL_LINES);
+    return {
+      status: 'fail',
+      command,
+      durationMs,
+      timedOut: true,
+      reason: result.message,
+      output: tail ? `${result.message}\n${tail}` : result.message,
+    };
+  }
+
   return {
     status: result.passed ? 'pass' : 'fail',
     command,
@@ -328,10 +354,17 @@ async function runE2eNode({ projectPath, featureName, taskId, skipE2e, freshE2e,
     durationMs,
     reason: result.reason ?? null,
     output: result.output || '',
+    // Non-fatal findings (e.g. a compose with fixed ports at the ROOT, where
+    // nothing collides yet). Surfaced so the same compose does not fail
+    // unannounced the day the feature moves into a worktree.
+    warnings: Array.isArray(result.warnings) ? result.warnings : [],
   };
 }
 
 function appendE2eFeedback(feedback, e2eNode) {
+  for (const warning of e2eNode.warnings || []) {
+    feedback.push(`[e2e] warning: ${warning}`);
+  }
   if (e2eNode.status !== 'fail') return;
   if (e2eNode.reason) feedback.push(`[e2e] ${e2eNode.reason}`);
   for (const line of linesOf(e2eNode.output)) {

package/src/lib/worktree/dirs.js

@@ -0,0 +1,32 @@
+/**
+ * dirs.js — the ONE place the worktree container directory is named.
+ *
+ * Every reader that resolves worktrees BY CONVENTION (test discovery, graph
+ * ignore list, the installed .gitignore, the architecture scanner, the
+ * dashboard scanner) imports from here. Duplicating the string is how the
+ * C1 bug comes back: a reader keeps the old name and silently goes blind.
+ *
+ * Readers that go through `git worktree list` (fleet, finish, worktree list)
+ * never depended on this — git records absolute paths.
+ */
+
+/**
+ * The directory new worktrees are created under, relative to the primary root.
+ *
+ * NO leading dot, deliberately (C1). Jest escapes the `.` when it interpolates
+ * an absolute `rootDir` into the `testMatch` glob, so `<root>/.worktrees/...`
+ * stops matching and an entire frontend suite reports **0 tests without an
+ * error** — the suite "passes" having tested nothing. The dot bought nothing:
+ * the directory is gitignored either way.
+ */
+export const WORKTREES_DIR = 'worktrees';
+
+/**
+ * The pre-C1 directory name. New worktrees never land here, but every reader
+ * that resolves worktrees BY CONVENTION must still accept it, so a machine
+ * that already had `.worktrees/{f}` keeps working with no manual migration.
+ */
+export const LEGACY_WORKTREES_DIR = '.worktrees';
+
+/** Both names, new first — the read order for convention-based lookups. */
+export const WORKTREE_DIR_NAMES = [WORKTREES_DIR, LEGACY_WORKTREES_DIR];

package/src/lib/worktree/env-allocator.js

@@ -21,6 +21,8 @@
 
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { join } from 'path';
+// src/ → hooks/shared/ is the allowed direction (hooks are installed standalone).
+import { composeProjectName } from '../../../framework/hooks/shared/e2e-check.js';
 
 const DEFAULT_BASE_PORT = 4000;
 const DEFAULT_BLOCK_SIZE = 10;
@@ -124,9 +126,46 @@ export function releaseEnvBlock(feature, { gitCommonDir }) {
 }
 
 /**
- * Render the `.morph/worktree.env` contents for a block, stack-aware.
- * `PORT` covers next/vite/node dev servers; dotnet gets its own URL on base+1
- * so a full-stack worktree runs web and api side by side inside one block.
+ * Fixed offsets inside a block. The block has 10 ports; four are named, the
+ * rest (+4..+9) are the project's to use. A new offset added here MUST also be
+ * published by the compose template (`${VAR:-default}:container`), or it is a
+ * port nobody listens on.
+ */
+export const PORT_OFFSETS = Object.freeze({ web: 0, api: 1, postgres: 2, redis: 3 });
+
+/**
+ * The ONE port-layout contract. Two writers derive from it — the
+ * `.morph/worktree.env` manifest (`buildEnvFileContent`) and the env handed to
+ * `docker compose` (`src/lib/e2e/compose-env.js`) — so a worktree's file and
+ * its running stack can never describe different worlds.
+ *
+ * `COMPOSE_PROJECT_NAME` is part of the layout on purpose: a hand-run
+ * `docker compose up` inside the worktree must land in the isolated project,
+ * not in the root's. Every value is a string (env-safe); key order is stable.
+ *
+ * @param {{ base: number, range: [number, number] }} block
+ * @param {{ stack?: string, feature?: string }} [opts]
+ * @returns {Record<string,string>}
+ */
+export function portLayout(block, { stack = '', feature = '' } = {}) {
+  const env = {};
+  if (feature) env.COMPOSE_PROJECT_NAME = composeProjectName(feature);
+  env.MORPH_PORT_BASE = String(block.base);
+  env.MORPH_PORT_RANGE = `${block.range[0]}-${block.range[1]}`;
+  env.PORT = String(block.base + PORT_OFFSETS.web);
+  env.API_PORT = String(block.base + PORT_OFFSETS.api);
+  env.POSTGRES_PORT = String(block.base + PORT_OFFSETS.postgres);
+  env.REDIS_PORT = String(block.base + PORT_OFFSETS.redis);
+  if (/\bdotnet\b/i.test(String(stack))) {
+    env.ASPNETCORE_URLS = `http://localhost:${block.base + PORT_OFFSETS.api}`;
+  }
+  return env;
+}
+
+/**
+ * Render the `.morph/worktree.env` contents for a block: a header, the
+ * feature, and exactly the `portLayout()` pairs — nothing else, so the file
+ * cannot drift from what compose receives.
  *
  * @param {string} feature
  * @param {{ base: number, range: [number, number] }} block
@@ -135,15 +174,10 @@ export function releaseEnvBlock(feature, { gitCommonDir }) {
  */
 export function buildEnvFileContent(feature, block, stack = '') {
   const lines = [
-    `# Managed by morph-spec — fleet env desta worktree (feature: ${feature}).`,
-    '# Derivado e local: nunca commitar, nunca editar à mão (regenerado pelo worktree setup).',
+    `# Managed by morph-spec — ambiente dedicado desta worktree (feature: ${feature}).`,
+    '# Derivado, git-invisível, regenerado por `worktree setup|link`; nunca editar nem commitar.',
     `MORPH_FEATURE=${feature}`,
-    `MORPH_PORT_BASE=${block.base}`,
-    `MORPH_PORT_RANGE=${block.range[0]}-${block.range[1]}`,
-    `PORT=${block.base}`,
+    ...Object.entries(portLayout(block, { stack, feature })).map(([k, v]) => `${k}=${v}`),
   ];
-  if (/\bdotnet\b/i.test(String(stack))) {
-    lines.push(`ASPNETCORE_URLS=http://localhost:${block.base + 1}`);
-  }
   return `${lines.join('\n')}\n`;
 }

package/src/lib/worktree/worktree-audit.js

@@ -247,9 +247,47 @@ export function auditWorktrees(cwd = process.cwd()) {
 
     const feature = entry.branch?.match(/^refs\/heads\/morph\/(.+)$/)?.[1] || null;
     if (!feature) {
-      // Only worth reporting when it sits in morph's own worktree container —
-      // a worktree the user keeps elsewhere is none of morph's business.
       const inContainer = WORKTREE_DIR_NAMES.some((d) => path.startsWith(`${rootNorm}/${d}/`));
+      const task = entry.branch?.match(/^refs\/heads\/morph-task\/(.+)$/)?.[1] || null;
+
+      if (!inContainer) {
+        // A worktree OUTSIDE morph's container was created behind morph's back
+        // (a native Claude Code run before the WorktreeCreate hook, a raw
+        // `git worktree add ../x`, another skill). It has no junctions, no port
+        // block, and nothing morph runs there — the exact shape that let a
+        // root's `.claude/` be emptied. Reported as `warn` (never a failure,
+        // NEVER pruned): the work inside may be the only copy.
+        const work = unintegratedWork(root, entry.branch, prIndex);
+        issues.push({
+          type: 'out-of-container',
+          severity: 'warn',
+          path,
+          detail: `${path} é um worktree fora de worktrees/ (${entry.branch || 'HEAD destacado'}) — criado sem o morph: sem junctions, sem portas, invisível ao \`fleet\`${work.unintegrated ? `; carrega trabalho NÃO integrado (${work.evidence})` : ''}`,
+          fix: work.unintegrated
+            ? `integre a branch primeiro; depois \`morph-spec worktree remove --target "${path}"\`. Novos worktrees: \`morph-spec worktree setup <f>\` ou \`worktree provision <n>\``
+            : `morph-spec worktree remove --target "${path}"  — e crie os próximos por \`morph-spec worktree setup <f>\` / \`worktree provision <n>\``,
+        });
+        continue;
+      }
+
+      if (task) {
+        // `morph-task/*`: a task-isolation tree provisioned by the WorktreeCreate
+        // hook. Clean → nothing to say (the orchestrator removes it after the
+        // merge). With commits the default does not have → report, never
+        // suggest removal.
+        const work = unintegratedWork(root, entry.branch, prIndex);
+        if (work.unintegrated) {
+          issues.push({
+            type: 'unintegrated-work',
+            severity: 'info',
+            path,
+            detail: `${path} é um worktree de isolamento de task (${entry.branch}) com trabalho NÃO integrado (${work.evidence})`,
+            fix: `integre a branch (\`git merge --no-ff morph-task/${task}\` no orquestrador) e depois \`morph-spec worktree remove --target "${path}"\``,
+          });
+        }
+        continue;
+      }
+
       if (inContainer) {
         // Same hazard as `no-feature` below, and it needs the same guard:
         // "invisible to fleet" says nothing about whether the WORK is safe

package/src/utils/agent-id-mapper.js

@@ -1,11 +1,11 @@
-/**
- * Map an agents.json ID to the Claude Code subagent_type.
- *
- * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
- * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
- * @returns {string} subagent_type matching .claude/agents/ filename stem
- */
-export function agentIdToSubagentType(id, tier) {
-  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
-  return `${prefix}${id}`;
-}
+/**
+ * Map an agents.json ID to the Claude Code subagent_type.
+ *
+ * @param {string} id - Agent ID from agents.json (e.g., "nextjs-expert")
+ * @param {number} [tier] - Agent tier (1-4). Defaults to non-validator.
+ * @returns {string} subagent_type matching .claude/agents/ filename stem
+ */
+export function agentIdToSubagentType(id, tier) {
+  const prefix = tier === 4 ? 'morph-validator-' : 'morph-';
+  return `${prefix}${id}`;
+}