@polymorphism-tech/morph-spec 7.9.3 → 8.0.0

package/src/lib/installers/memory-installer.js

@@ -39,7 +39,7 @@ metadata:
 ## Key paths
 
 - \`.morph/framework/MORPH.md\` — NLH charter (read once per session)
-- \`.morph/framework/agents.json\` — 7 domain personas
+- \`.morph/framework/agents.json\` — 8 agents: 7 domain personas + 1 stage persona (\`scout\`, read-only)
 - \`.morph/framework/standards/STANDARDS.json\` — standards index (load on demand)
 - \`.morph/framework/schemas/tasks.schema.json\` — JSON Schema for tasks.json
 - \`.morph/features/{feature}/\` — feature artifacts: 0-proposal / 1-design / 2-plan / 3-implement / 4-review

package/src/lib/risk-detector.js

@@ -15,6 +15,13 @@
 const SCOPE_TASK_THRESHOLD = 20;
 const MIN_EVAL_SCORE = 9;
 
+// Work types whose ship gate (review) always pauses for a human, regardless
+// of trust mode — a type policy, not a per-feature risk signal. Mirrors
+// `forcedPauseGates` in src/core/work-types.js (hotfix.review); kept here too
+// because risk-detector is the deterministic layer consumed independent of
+// the work-type config object.
+const FORCED_PAUSE_WORK_TYPES = ['hotfix'];
+
 /**
  * @param {object} config - .morph/config/config.json contents (uses `trust`)
  * @param {object} signals
@@ -27,6 +34,13 @@ export function shouldPauseGate(config, signals) {
     return { pause: true, reason: 'trust mode is manual' };
   }
 
+  if (FORCED_PAUSE_WORK_TYPES.includes(signals.workType)) {
+    return {
+      pause: true,
+      reason: 'hotfix: aprovação humana obrigatória no ship (política de tipo — ignora trust:auto)',
+    };
+  }
+
   if (signals.designSystemDivergence) {
     return { pause: true, reason: 'design-system divergence detected' };
   }
@@ -61,6 +75,7 @@ export function shouldPauseGate(config, signals) {
  */
 export function getRiskSignals(signals) {
   const out = [];
+  if (FORCED_PAUSE_WORK_TYPES.includes(signals.workType)) out.push('hotfix (gate humano obrigatório)');
   if (signals.designSystemDivergence) out.push('design-system divergence');
   if (Array.isArray(signals.standardsViolations) && signals.standardsViolations.length > 0) {
     out.push(`standards violations: ${signals.standardsViolations.join(', ')}`);
@@ -77,4 +92,5 @@ export function getRiskSignals(signals) {
 export const RISK_CONSTANTS = {
   SCOPE_TASK_THRESHOLD,
   MIN_EVAL_SCORE,
+  FORCED_PAUSE_WORK_TYPES,
 };

package/src/lib/tasks/dispatch-planner.js

@@ -39,6 +39,108 @@ function groupOf(task) {
   return task.group || 'backend';
 }
 
+/**
+ * Normalize a planned output path for collision comparison: forward slashes,
+ * collapsed repeated slashes, no leading `./` or `/`, no trailing slash,
+ * lowercased (Windows/macOS filesystems are case-insensitive). Returns '' for
+ * empty/nullish input. `..`/`.` segments are left as-is on purpose (resolving
+ * them would risk false-positives; two genuinely different relative spellings
+ * stay distinct).
+ */
+export function normalizeOutputPath(p) {
+  return String(p ?? '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/\/{2,}/g, '/')
+    .replace(/^\.\//, '')
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+/**
+ * Two normalized paths "overlap" if they are equal, or one is a directory
+ * ancestor of the other — boundary-aware so `src/a` contains `src/a/b` but
+ * NOT `src/ab`. Empty paths never overlap.
+ */
+export function pathsOverlap(a, b) {
+  if (!a || !b) return false;
+  if (a === b) return true;
+  const [shorter, longer] = a.length <= b.length ? [a, b] : [b, a];
+  return longer.startsWith(`${shorter}/`);
+}
+
+/**
+ * Decide whether a parallel batch's units would write to overlapping paths,
+ * and therefore whether each agent should run in its own git worktree
+ * (`isolation: "worktree"`, per morph-apply §3b-w) instead of the shared
+ * working tree.
+ *
+ * A *unit* is the set of task ids a single agent owns (one flow, or one batch
+ * root). Tasks WITHIN a unit run serially under that agent, so their outputs
+ * never race — only CROSS-unit overlaps matter. The recommendation is global
+ * per batch: any collision → isolate the whole batch. Units whose tasks
+ * declare no `outputs` are an *unknown footprint* — they do NOT force
+ * isolation (fail-open) but are flagged so the caller knows the dag can't
+ * prove the batch is collision-free.
+ *
+ * @param {Array<{ key: string, taskIds: string[] }>} units
+ * @param {Map<string, object>} tasksById
+ * @returns {{ recommended: 'none'|'worktree', collisions: Array<{path: string, units: string[], tasks: string[]}>, unknownFootprint: string[], reason: string }}
+ */
+export function buildIsolation(units, tasksById) {
+  const unknownFootprint = [];
+  const unitOutputs = units.map(unit => {
+    const outs = [];
+    for (const id of unit.taskIds) {
+      const task = tasksById.get(id);
+      const declared = Array.isArray(task?.outputs) ? task.outputs : [];
+      let validForTask = 0;
+      for (const raw of declared) {
+        const path = normalizeOutputPath(raw);
+        if (path) { outs.push({ path, task: id }); validForTask += 1; }
+      }
+      // No usable output paths (none declared, or all normalize to '') → the
+      // dag can't prove this task's footprint. Flag it (fail-open).
+      if (validForTask === 0) unknownFootprint.push(id);
+    }
+    return { key: unit.key, outs };
+  });
+
+  const collisions = [];
+  for (let i = 0; i < unitOutputs.length; i++) {
+    for (let j = i + 1; j < unitOutputs.length; j++) {
+      for (const a of unitOutputs[i].outs) {
+        for (const b of unitOutputs[j].outs) {
+          if (pathsOverlap(a.path, b.path)) {
+            collisions.push({
+              path: a.path === b.path ? a.path : `${a.path} ∩ ${b.path}`,
+              units: [unitOutputs[i].key, unitOutputs[j].key],
+              tasks: [a.task, b.task],
+            });
+          }
+        }
+      }
+    }
+  }
+
+  const recommended = collisions.length > 0 ? 'worktree' : 'none';
+  let reason;
+  if (collisions.length > 0) {
+    reason =
+      `${collisions.length} colisão(ões) de outputs entre unidades paralelas — ` +
+      `isole cada agente num worktree (morph-apply §3b-w)`;
+  } else if (unknownFootprint.length > 0) {
+    reason =
+      `sem colisão detectada, mas ${unknownFootprint.length} task(s) paralela(s) sem ` +
+      `outputs declarados (footprint desconhecido) — o dag não garante ausência de colisão`;
+  } else {
+    reason = 'nenhuma colisão de outputs entre unidades paralelas — batch na working tree compartilhada';
+  }
+
+  return { recommended, collisions, unknownFootprint, reason };
+}
+
 /**
  * Ids of tasks whose dependency chain crosses group boundaries — integration
  * tasks and everything downstream of them. These never belong to a flow: they
@@ -97,7 +199,8 @@ function buildStats(tasks, pending) {
  *   flows: Array<{ group: string, taskIds: string[], weight: number }>,
  *   batch: string[],
  *   inline: string[],
- *   sequentialRemainder: string[]
+ *   sequentialRemainder: string[],
+ *   isolation: { recommended: 'none'|'worktree', collisions: Array<{path: string, units: string[], tasks: string[]}>, unknownFootprint: string[], reason: string }
  * }}
  */
 export function planDispatch(data) {
@@ -105,12 +208,15 @@ export function planDispatch(data) {
   const pending = tasks.filter(t => t.status === 'pending');
   const stats = buildStats(tasks, pending);
   const empty = { flows: [], batch: [], inline: [] };
+  const tasksById = new Map(tasks.map(t => [t.id, t]));
+  // A batch with no parallel units can't have concurrent-write collisions.
+  const noIsolation = buildIsolation([], tasksById);
 
   if (pending.length === 0) {
     return {
       mode: 'sequential',
       reason: 'nenhuma task pendente — nada a despachar',
-      stats, ...empty, sequentialRemainder: [],
+      stats, ...empty, sequentialRemainder: [], isolation: noIsolation,
     };
   }
 
@@ -119,7 +225,7 @@ export function planDispatch(data) {
     return {
       mode: 'sequential',
       reason: `${tasks.length} task(s) no total (<= 3) — overhead de Agent dispatch não compensa`,
-      stats, ...empty, sequentialRemainder: pending.map(t => t.id),
+      stats, ...empty, sequentialRemainder: pending.map(t => t.id), isolation: noIsolation,
     };
   }
 
@@ -160,6 +266,12 @@ export function planDispatch(data) {
         (inline.length ? `; ${inline.length} task(s) leve(s) inline (sem dispatch próprio)` : '') +
         (sequentialRemainder.length ? `; integração cross-group sequencial no fim (${sequentialRemainder.join(', ')})` : ''),
       stats, flows, batch: [], inline, sequentialRemainder,
+      // Units = the dispatched flows (one agent each). Inline/overflow/cross-
+      // group remainder run in the sequential lane, never concurrently.
+      isolation: buildIsolation(
+        flows.map(f => ({ key: f.group, taskIds: f.taskIds })),
+        tasksById,
+      ),
     };
   }
 
@@ -184,6 +296,12 @@ export function planDispatch(data) {
         (inline.length ? `; raízes S inline — não ganham dispatch próprio (${inline.join(', ')})` : '') +
         `; restante sequencial`,
       stats, flows: [], batch, inline, sequentialRemainder,
+      // Units = each batch root (one agent each); inline S-roots and the
+      // sequential remainder don't run concurrently with the batch.
+      isolation: buildIsolation(
+        batch.map(id => ({ key: id, taskIds: [id] })),
+        tasksById,
+      ),
     };
   }
 
@@ -196,6 +314,6 @@ export function planDispatch(data) {
   return {
     mode: 'sequential',
     reason,
-    stats, ...empty, sequentialRemainder: pending.map(t => t.id),
+    stats, ...empty, sequentialRemainder: pending.map(t => t.id), isolation: noIsolation,
   };
 }

package/src/lib/tasks/mermaid-renderer.js

@@ -0,0 +1,132 @@
+/**
+ * mermaid-renderer.js — pure renderer: tasks.json DAG -> Mermaid flowchart TD.
+ *
+ * Backs `morph-spec dag <feature> --mermaid` (S8-T1), so the plan's DAG can be
+ * visualized at Gate 2 (IndyDevDan rec. 2: draw the workflow in Mermaid before
+ * automating it).
+ *
+ * STRICT Mermaid rules enforced here (see project CLAUDE.md — violating these
+ * breaks rendering in Obsidian):
+ *   - every node label wrapped in double quotes, no exceptions
+ *   - labels never start with a numeric-with-dot prefix ("1. ", "2. ...") —
+ *     Obsidian's markdown-list parser chokes on it even inside quotes
+ *   - `&` inside labels -> `e`
+ *   - line breaks inside labels -> `<br/>`, never a literal `\n`
+ *   - double quotes inside titles are stripped so they can't break out of the
+ *     surrounding label quotes
+ *
+ * Pure module: no fs, no Date.now()/Math.random(). Tasks are sorted by
+ * numeric id so output is stable regardless of input order.
+ */
+
+const MAX_TITLE_LENGTH = 40;
+
+const VALID_STATUS_CLASSES = ['done', 'in_progress', 'blocked', 'skipped', 'pending'];
+
+// Web-safe fill/stroke pairs, one per task status.
+const CLASS_DEFS = [
+  'classDef done fill:#c6f6d5,stroke:#2f855a,color:#22543d',
+  'classDef in_progress fill:#bee3f8,stroke:#2b6cb0,color:#2a4365',
+  'classDef blocked fill:#feb2b2,stroke:#c53030,color:#63171b',
+  'classDef skipped fill:#e2e8f0,stroke:#718096,color:#2d3748',
+  'classDef pending fill:#edf2f7,stroke:#a0aec0,color:#2d3748',
+];
+
+function numericId(id) {
+  const match = /^T(\d+)$/.exec(id ?? '');
+  return match ? parseInt(match[1], 10) : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * Sanitize arbitrary text for embedding inside a double-quoted Mermaid node
+ * label, per the project's strict Mermaid rules.
+ *
+ * - double quotes stripped (they would close the label's own quotes)
+ * - `&` -> `e`
+ * - truncated to MAX_TITLE_LENGTH chars + `…`
+ * - line breaks -> `<br/>`
+ *
+ * Ordering matters: truncation runs on the raw text BEFORE newlines expand to
+ * `<br/>`. Newline->`<br/>` is the only length-changing substitution (1 char ->
+ * 5); truncating after it could slice a tag mid-way ("...<b…"), so we truncate
+ * first — every emitted `<br/>` is then guaranteed whole. The char-for-char
+ * substitutions (`"`->`'`, `&`->`e`) don't move the truncation boundary.
+ */
+export function sanitizeLabel(text) {
+  let out = String(text ?? '');
+  out = out.replace(/"/g, "'");
+  out = out.replace(/&/g, 'e');
+  if (out.length > MAX_TITLE_LENGTH) {
+    out = `${out.slice(0, MAX_TITLE_LENGTH)}…`;
+  }
+  out = out.replace(/\r\n|\r|\n/g, '<br/>');
+  return out;
+}
+
+/**
+ * Same fallback as groupOf() in dispatch-planner.js / groupTasks() in
+ * tasks-json-parser.js — tasks without a `group` field are treated as
+ * 'backend'.
+ */
+function groupOf(task) {
+  return task.group || 'backend';
+}
+
+function statusClass(status) {
+  return VALID_STATUS_CLASSES.includes(status) ? status : 'pending';
+}
+
+/**
+ * Render a parsed tasks.json document as a Mermaid `flowchart TD`.
+ *
+ * @param {{ tasks?: Array<{ id: string, title: string, dependencies?: string[], effort?: string, group?: string, status?: string }> }} tasksData
+ * @returns {string}
+ */
+export function renderMermaidFlowchart(tasksData) {
+  const tasks = Array.isArray(tasksData?.tasks) ? tasksData.tasks : [];
+
+  if (tasks.length === 0) {
+    return ['flowchart TD', '  empty["sem tasks"]'].join('\n');
+  }
+
+  const sorted = [...tasks].sort((a, b) => numericId(a.id) - numericId(b.id));
+  const knownIds = new Set(sorted.map(t => t.id));
+
+  // Group tasks by `group`, preserving the deterministic sorted-by-id order
+  // in which each group is first encountered.
+  const groups = new Map();
+  for (const task of sorted) {
+    const g = groupOf(task);
+    if (!groups.has(g)) groups.set(g, []);
+    groups.get(g).push(task);
+  }
+
+  const lines = ['flowchart TD'];
+
+  for (const [group, groupTasks] of groups) {
+    lines.push(`  subgraph ${group}["${sanitizeLabel(group)}"]`);
+    for (const task of groupTasks) {
+      const label = `${task.id} · ${sanitizeLabel(task.title)} (${task.effort})`;
+      lines.push(`    ${task.id}["${label}"]`);
+    }
+    lines.push('  end');
+  }
+
+  // Edges — one per dependency. Dependencies pointing at a non-existent id
+  // are silently skipped (never throw on a dangling reference).
+  for (const task of sorted) {
+    const deps = Array.isArray(task.dependencies) ? task.dependencies : [];
+    for (const dep of deps) {
+      if (!knownIds.has(dep)) continue;
+      lines.push(`  ${dep} --> ${task.id}`);
+    }
+  }
+
+  lines.push(...CLASS_DEFS);
+
+  for (const task of sorted) {
+    lines.push(`  class ${task.id} ${statusClass(task.status)}`);
+  }
+
+  return lines.join('\n');
+}

package/src/lib/tasks/task-classifier.js

@@ -1,30 +1,30 @@
-/**
- * Task classifier — identifies test/validation and infrastructure tasks by title.
- */
-
-const TEST_TASK_PATTERN = /\b(tests?|testing|specs?|coverage|e2e|unit|integration|integra[cç][aã]o|valida[cç][aã]o|cobertura|testes?)\b/i;
-
-/**
- * Returns true if the task title indicates a testing or validation task.
- *
- * @param {string} taskTitle
- * @returns {boolean}
- */
-export function isTestTask(taskTitle) {
-  if (!taskTitle) return false;
-  return TEST_TASK_PATTERN.test(taskTitle);
-}
-
-const INFRA_TASK_PATTERN = /\b(infrastructure|infra|cleanup|migration|migra[cç][aã]o|config|setup|ci\/cd|devops|deploy|docker|packages?|dependencies|tags)\b/i;
-
-/**
- * Returns true if the task title indicates an infrastructure/cleanup/migration task.
- * Used to skip contract validation and suppress breaking change warnings.
- *
- * @param {string} taskTitle
- * @returns {boolean}
- */
-export function isInfrastructureTask(taskTitle) {
-  if (!taskTitle) return false;
-  return INFRA_TASK_PATTERN.test(taskTitle);
-}
+/**
+ * Task classifier — identifies test/validation and infrastructure tasks by title.
+ */
+
+const TEST_TASK_PATTERN = /\b(tests?|testing|specs?|coverage|e2e|unit|integration|integra[cç][aã]o|valida[cç][aã]o|cobertura|testes?)\b/i;
+
+/**
+ * Returns true if the task title indicates a testing or validation task.
+ *
+ * @param {string} taskTitle
+ * @returns {boolean}
+ */
+export function isTestTask(taskTitle) {
+  if (!taskTitle) return false;
+  return TEST_TASK_PATTERN.test(taskTitle);
+}
+
+const INFRA_TASK_PATTERN = /\b(infrastructure|infra|cleanup|migration|migra[cç][aã]o|config|setup|ci\/cd|devops|deploy|docker|packages?|dependencies|tags)\b/i;
+
+/**
+ * Returns true if the task title indicates an infrastructure/cleanup/migration task.
+ * Used to skip contract validation and suppress breaking change warnings.
+ *
+ * @param {string} taskTitle
+ * @returns {boolean}
+ */
+export function isInfrastructureTask(taskTitle) {
+  if (!taskTitle) return false;
+  return INFRA_TASK_PATTERN.test(taskTitle);
+}