@josstei/maestro 1.6.4-rc.1

package/plugins/maestro/src/mcp/validation/agent-checker.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const {
+  KNOWN_AGENTS,
+  normalizeAgentName,
+  getAgentCapability,
+  canCreateFiles,
+} = require('../../core/agent-registry');
+
+const CREATION_SIGNAL_PATTERNS =
+  /\b(implement|create|build|scaffold|write|generate|set\s*up|develop)\b/i;
+
+/**
+ * Verify each phase's declared agent is known to the registry.
+ */
+function checkUnknownAgents(phases) {
+  const violations = [];
+  for (const phase of phases) {
+    const normalizedAgent = normalizeAgentName(phase.agent);
+    if (normalizedAgent && !KNOWN_AGENTS.includes(normalizedAgent)) {
+      violations.push({
+        rule: 'unknown_agent',
+        detail: `Phase ${phase.id}: unknown agent "${phase.agent}" (normalized: "${normalizedAgent}")`,
+        severity: 'error',
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Catch mismatches between an agent's write capability and a phase's
+ * file-touching workload. Read-only agents assigned to phases that
+ * declare `files` (planning-time), `files_created`, or `files_modified`
+ * emit an error; read-only agents assigned to phases whose name hints
+ * at creation emit a warning.
+ */
+function checkAgentCapabilities(phases) {
+  const violations = [];
+  for (const phase of phases) {
+    const normalizedAgent = normalizeAgentName(phase.agent);
+    if (!normalizedAgent) {
+      continue;
+    }
+
+    const touchesFiles =
+      (Array.isArray(phase.files) && phase.files.length > 0) ||
+      (Array.isArray(phase.files_created) && phase.files_created.length > 0) ||
+      (Array.isArray(phase.files_modified) && phase.files_modified.length > 0);
+
+    if (touchesFiles && !canCreateFiles(normalizedAgent)) {
+      violations.push({
+        rule: 'agent_capability_mismatch',
+        detail: `Phase ${phase.id}: agent '${phase.agent}' (${getAgentCapability(
+          normalizedAgent
+        )}) cannot deliver file-creating tasks. Use a write-capable agent (coder, data_engineer, etc.) or split into analysis + implementation phases.`,
+        severity: 'error',
+      });
+      continue;
+    }
+
+    if (
+      !touchesFiles &&
+      getAgentCapability(normalizedAgent) === 'read_only' &&
+      phase.name &&
+      CREATION_SIGNAL_PATTERNS.test(phase.name)
+    ) {
+      violations.push({
+        rule: 'agent_capability_mismatch',
+        detail: `Phase ${phase.id}: agent '${phase.agent}' (read_only) assigned to phase '${phase.name}' which may require file creation. Verify this agent can deliver the phase's requirements.`,
+        severity: 'warning',
+      });
+    }
+  }
+  return violations;
+}
+
+module.exports = {
+  checkUnknownAgents,
+  checkAgentCapabilities,
+};

package/plugins/maestro/src/mcp/validation/dag-checker.js

@@ -0,0 +1,214 @@
+'use strict';
+
+const { StateError } = require('../../lib/errors');
+
+/**
+ * Compute the topological depth (longest incoming dependency chain) for
+ * each phase. Throws if a cycle is reached — callers should run cycle
+ * detection first.
+ *
+ * @returns {Record<string|number, number>} phase id -> depth (root phases have depth 0)
+ */
+function computeDepths(phases, phaseById) {
+  const depthMap = {};
+
+  function getDepth(id) {
+    if (depthMap[id] !== undefined) {
+      return depthMap[id];
+    }
+
+    const phase = phaseById.get(id);
+    if (!phase || !phase.blocked_by || phase.blocked_by.length === 0) {
+      depthMap[id] = 0;
+      return 0;
+    }
+
+    depthMap[id] = -1;
+    const maxBlockerDepth = Math.max(
+      ...phase.blocked_by.map((blockedPhaseId) => {
+        const depth = getDepth(blockedPhaseId);
+        if (depth === -1) {
+          throw new StateError('computeDepths: unexpected cycle detected');
+        }
+        return depth;
+      })
+    );
+    depthMap[id] = maxBlockerDepth + 1;
+    return depthMap[id];
+  }
+
+  for (const phase of phases) {
+    getDepth(phase.id);
+  }
+
+  return depthMap;
+}
+
+/**
+ * Compute the transitive closure of phase dependencies (reachable blockers).
+ * Memoized via the optional `memo` parameter so repeated callers share state.
+ */
+function getTransitiveDependencies(phaseId, phaseById, memo = {}) {
+  if (memo[phaseId]) {
+    return memo[phaseId];
+  }
+
+  const phase = phaseById.get(phaseId);
+  if (!phase || !phase.blocked_by || phase.blocked_by.length === 0) {
+    memo[phaseId] = new Set();
+    return memo[phaseId];
+  }
+
+  const result = new Set();
+  for (const dependencyId of phase.blocked_by) {
+    result.add(dependencyId);
+    for (const transitiveDependency of getTransitiveDependencies(
+      dependencyId,
+      phaseById,
+      memo
+    )) {
+      result.add(transitiveDependency);
+    }
+  }
+
+  memo[phaseId] = result;
+  return result;
+}
+
+/**
+ * Depth-first cycle detection. Emits a single `cyclic_dependency`
+ * violation identifying the first phase at which a back-edge was found.
+ */
+function checkCycles(phases, phaseById) {
+  const violations = [];
+  const visited = new Set();
+  const inStack = new Set();
+
+  function hasCycle(id) {
+    if (inStack.has(id)) {
+      return true;
+    }
+
+    if (visited.has(id)) {
+      return false;
+    }
+
+    visited.add(id);
+    inStack.add(id);
+
+    const phase = phaseById.get(id);
+    if (phase) {
+      for (const dependencyId of phase.blocked_by || []) {
+        if (hasCycle(dependencyId)) {
+          return true;
+        }
+      }
+    }
+
+    inStack.delete(id);
+    return false;
+  }
+
+  for (const phase of phases) {
+    if (hasCycle(phase.id)) {
+      violations.push({
+        rule: 'cyclic_dependency',
+        detail: `Cycle detected involving phase ${phase.id}`,
+        severity: 'error',
+      });
+      break;
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Flag a blocked_by edge as redundant when the same blocker is already
+ * reachable transitively through a sibling dependency.
+ */
+function checkRedundantDependencies(phases, phaseById) {
+  const violations = [];
+  const memo = {};
+
+  for (const phase of phases) {
+    if (!phase.blocked_by || phase.blocked_by.length < 2) {
+      continue;
+    }
+
+    for (const dependencyId of phase.blocked_by) {
+      const otherDependencies = phase.blocked_by.filter(
+        (id) => id !== dependencyId
+      );
+      let redundant = false;
+
+      for (const otherDependencyId of otherDependencies) {
+        const transitiveDependencies = getTransitiveDependencies(
+          otherDependencyId,
+          phaseById,
+          memo
+        );
+        if (transitiveDependencies.has(dependencyId)) {
+          violations.push({
+            rule: 'redundant_dependency',
+            detail: `Phase ${phase.id}: dependency on phase ${dependencyId} is redundant (already reachable via phase ${otherDependencyId})`,
+            severity: 'warning',
+          });
+          redundant = true;
+          break;
+        }
+      }
+
+      if (redundant) {
+        break;
+      }
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Build the parallelization profile (depth-based batches, eligible count,
+ * maximum batch size) for the plan.
+ */
+function buildParallelizationProfile(phases, phaseById) {
+  const depths = computeDepths(phases, phaseById);
+  const batches = Object.entries(
+    phases.reduce((acc, phase) => {
+      const depth = depths[phase.id] || 0;
+      acc[depth] = acc[depth] || [];
+      acc[depth].push(phase.id);
+      return acc;
+    }, {})
+  )
+    .sort(([a], [b]) => Number(a) - Number(b))
+    .map(([depth, phaseIds]) => ({
+      depth: Number(depth),
+      phase_ids: phaseIds,
+    }));
+
+  let parallelEligible = 0;
+  for (const batch of batches) {
+    if (batch.phase_ids.length > 1) {
+      parallelEligible += batch.phase_ids.length;
+    }
+  }
+
+  return {
+    total_phases: phases.length,
+    depth_map: depths,
+    batches,
+    max_batch_size: Math.max(...batches.map((batch) => batch.phase_ids.length)),
+    parallel_eligible: parallelEligible,
+    effective_batches: batches.length,
+  };
+}
+
+module.exports = {
+  computeDepths,
+  getTransitiveDependencies,
+  checkCycles,
+  checkRedundantDependencies,
+  buildParallelizationProfile,
+};

package/plugins/maestro/src/mcp/validation/file-overlap-checker.js

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * Emit `file_overlap` violations when two phases marked `parallel` at
+ * the same dependency depth both declare ownership of the same file.
+ * Phases at different depths can safely touch the same file because
+ * they run sequentially.
+ *
+ * Ownership is the union of:
+ *   - `files` — the planning-time manifest (canonical plan input)
+ *   - `files_created` / `files_modified` — runtime-populated manifests
+ *     from previous executions of the plan (included for plans that
+ *     were already executed and are being re-validated against updated
+ *     rules).
+ */
+function checkFileOverlap(phases, depths) {
+  const parallelPhases = phases.filter((phase) => phase.parallel);
+  if (parallelPhases.length === 0) {
+    return [];
+  }
+
+  const violations = [];
+  const batchesByDepth = {};
+
+  for (const phase of parallelPhases) {
+    const depth = depths[phase.id] || 0;
+    batchesByDepth[depth] = batchesByDepth[depth] || [];
+    batchesByDepth[depth].push(phase);
+  }
+
+  for (const batch of Object.values(batchesByDepth)) {
+    if (batch.length < 2) {
+      continue;
+    }
+
+    const fileOwners = {};
+    for (const phase of batch) {
+      const files = [
+        ...(phase.files || []),
+        ...(phase.files_created || []),
+        ...(phase.files_modified || []),
+      ];
+
+      for (const file of files) {
+        if (fileOwners[file]) {
+          violations.push({
+            rule: 'file_overlap',
+            detail: `Parallel phases ${fileOwners[file]} and ${phase.id} both touch "${file}"`,
+            severity: 'error',
+          });
+        } else {
+          fileOwners[file] = phase.id;
+        }
+      }
+    }
+  }
+
+  return violations;
+}
+
+module.exports = {
+  checkFileOverlap,
+};

package/plugins/maestro/src/mcp/validation/schema-checker.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const { validatePhases } = require('../contracts/plan-schema');
+
+const PHASE_LIMITS = {
+  simple: 3,
+  medium: 5,
+  complex: Infinity,
+};
+
+/**
+ * Lightweight shape validation: guard against non-object plans or
+ * missing `phases` arrays so downstream checkers can assume a phase list.
+ * Returns a single `invalid_plan` violation when the structure is wrong.
+ */
+function checkPlanShape(plan) {
+  if (!plan || typeof plan !== 'object' || !Array.isArray(plan.phases)) {
+    return [
+      {
+        rule: 'invalid_plan',
+        detail: 'plan must be an object with a phases array',
+        severity: 'error',
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Enforce task-complexity phase budgets: simple<=3, medium<=5, complex unlimited.
+ */
+function checkPhaseCount(phases, taskComplexity) {
+  const limit = PHASE_LIMITS[taskComplexity] || Infinity;
+  if (phases.length > limit) {
+    return [
+      {
+        rule: 'phase_count',
+        detail: `${taskComplexity} tasks allow max ${limit} phases, got ${phases.length}`,
+        severity: 'error',
+      },
+    ];
+  }
+  return [];
+}
+
+/**
+ * Flag duplicate phase IDs. Emits one violation per duplicate occurrence
+ * (matches the original loop behavior).
+ */
+function checkDuplicateIds(phases) {
+  const violations = [];
+  const seenIds = new Set();
+  for (const phase of phases) {
+    if (seenIds.has(phase.id)) {
+      violations.push({
+        rule: 'duplicate_id',
+        detail: `Duplicate phase ID: ${phase.id}`,
+        severity: 'error',
+      });
+    }
+    seenIds.add(phase.id);
+  }
+  return violations;
+}
+
+/**
+ * Flag blocked_by entries that reference non-existent phase IDs.
+ */
+function checkDanglingDependencies(phases) {
+  const violations = [];
+  const allIds = new Set(phases.map((phase) => phase.id));
+  for (const phase of phases) {
+    for (const dependencyId of phase.blocked_by || []) {
+      if (!allIds.has(dependencyId)) {
+        violations.push({
+          rule: 'dangling_dependency',
+          detail: `Phase ${phase.id} references non-existent dependency: ${dependencyId}`,
+          severity: 'error',
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Delegate per-phase field validation to the shared `validatePhases` contract.
+ * Maps contract violations to the schema-checker violation shape.
+ */
+function checkPhaseFieldSchema(phases) {
+  const result = validatePhases(phases);
+  if (result.valid) return [];
+  return result.violations.map((violation) => ({
+    rule: violation.rule,
+    detail: `Phase ${violation.phase_id ?? '?'} field "${violation.field}" ${violation.rule.replace('_', ' ')}`,
+    severity: 'error',
+    phase_id: violation.phase_id,
+    field: violation.field,
+  }));
+}
+
+module.exports = {
+  checkPlanShape,
+  checkPhaseCount,
+  checkDuplicateIds,
+  checkDanglingDependencies,
+  checkPhaseFieldSchema,
+};

package/plugins/maestro/src/platforms/codex/runtime-config.js

@@ -0,0 +1,58 @@
+module.exports = {
+  name: 'codex',
+  outputDir: 'plugins/maestro/',
+
+  agentNaming: 'kebab-case',
+
+  env: {
+    extensionPath: '.',
+    workspacePath: 'MAESTRO_WORKSPACE_PATH',
+  },
+
+  relativeExtensionPath: true,
+
+  content: {
+    primary: 'filesystem',
+    fallback: 'none',
+  },
+
+  tools: {
+    read_file: 'direct file reads',
+    list_directory: 'exec_command (`rg --files` or `ls`)',
+    glob: 'exec_command (`rg --files` or `find`)',
+    grep_search: 'exec_command (`rg`)',
+    google_web_search: 'web search',
+    web_fetch: 'web fetch',
+    write_file: 'apply_patch',
+    replace: 'apply_patch',
+    run_shell_command: 'exec_command',
+    ask_user: 'request_user_input',
+    read_many_files: 'direct file reads',
+    write_todos: 'update_plan',
+    activate_skill: 'open the referenced skill and follow it',
+    enter_plan_mode: 'update_plan',
+    exit_plan_mode: 'request_user_input approval',
+    codebase_investigator: 'local inspection or spawn_agent',
+  },
+
+  delegation: {
+    pattern: 'spawn_agent(...)',
+    constraints: {
+      fork_full_context_incompatible_with: ['agent_type', 'model', 'reasoning_effort'],
+      result_surface: 'deferred',
+      child_cannot_prompt_user: true,
+    },
+  },
+
+  features: {
+    exampleBlocks: false,
+    claudeStateContract: false,
+    scriptBasedStateContract: false,
+    codexStateContract: true,
+  },
+
+  paths: {
+    skills: './skills/',
+    hooks: './scripts/',
+  },
+};

package/plugins/maestro/src/platforms/shared/adapters/conventions.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/** @type {string} */
+const ADAPTER_SUFFIX = '-adapter.js';
+
+/**
+ * Determine whether a filename follows the adapter naming convention.
+ * Accepts bare filenames only — paths with directory separators return false.
+ * @param {string} filename - Base filename (no directory components)
+ * @returns {boolean} True when filename matches the {runtime}-adapter.js pattern
+ */
+function isAdapterFile(filename) {
+  return filename.endsWith(ADAPTER_SUFFIX) && !filename.includes('/');
+}
+
+/**
+ * Extract the runtime name from an adapter filename.
+ * @param {string} filename - Base filename matching the adapter convention
+ * @returns {string|null} Runtime name (e.g. 'claude'), or null if filename
+ *   does not match the adapter convention
+ */
+function extractRuntime(filename) {
+  if (!isAdapterFile(filename)) {
+    return null;
+  }
+  return filename.slice(0, -ADAPTER_SUFFIX.length);
+}
+
+module.exports = { ADAPTER_SUFFIX, isAdapterFile, extractRuntime };

package/plugins/maestro/src/platforms/shared/adapters/exit-codes.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const EXIT_SUCCESS = 0;
+const EXIT_BLOCK = 2;
+
+module.exports = { EXIT_SUCCESS, EXIT_BLOCK };

package/plugins/maestro/src/platforms/shared/adapters/factory.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const { readBoundedJson } = require('../../../core/stdin-reader');
+const { EXIT_SUCCESS } = require('./exit-codes');
+
+/**
+ * Adapter contract expected by `hook-runner.js`:
+ *   normalizeInput(raw)  -> ctx       (runtime stdin -> internal context)
+ *   formatOutput(result) -> object    (internal result -> runtime stdout)
+ *   errorFallback()      -> object    (emitted on uncaught adapter errors)
+ *   readBoundedStdin()   -> Promise   (parse stdin as JSON, bounded size)
+ *   getExitCode(result)  -> number    (process exit code; defaults to 0)
+ *
+ * `defineAdapter` is a spec-assembler: it validates a caller-provided
+ * spec and fills in shared defaults (stdin reader, success-exit fallback)
+ * so each runtime adapter only declares its protocol-specific
+ * normalize/format/fallback/exit logic. Registry dispatch by runtime
+ * name is done separately by `hook-runner.js`.
+ */
+function defineAdapter(spec) {
+  if (!spec || typeof spec.normalizeInput !== 'function') {
+    throw new TypeError('Adapter spec must provide normalizeInput(raw)');
+  }
+  if (typeof spec.formatOutput !== 'function') {
+    throw new TypeError('Adapter spec must provide formatOutput(result)');
+  }
+  if (typeof spec.errorFallback !== 'function') {
+    throw new TypeError('Adapter spec must provide errorFallback()');
+  }
+
+  return {
+    normalizeInput: spec.normalizeInput,
+    formatOutput: spec.formatOutput,
+    errorFallback: spec.errorFallback,
+    readBoundedStdin: spec.readBoundedStdin || readBoundedJson,
+    getExitCode: spec.getExitCode || (() => EXIT_SUCCESS),
+  };
+}
+
+module.exports = { defineAdapter };

package/plugins/maestro/src/platforms/shared/agent-names.js

@@ -0,0 +1,10 @@
+module.exports = {
+  agentNames: [
+    'accessibility-specialist', 'analytics-engineer', 'api-designer', 'architect',
+    'code-reviewer', 'coder', 'compliance-reviewer', 'content-strategist',
+    'copywriter', 'data-engineer', 'debugger', 'design-system-engineer',
+    'devops-engineer', 'i18n-specialist', 'performance-engineer', 'product-manager',
+    'refactor', 'security-engineer', 'seo-specialist', 'technical-writer',
+    'tester', 'ux-designer',
+  ],
+};

package/plugins/maestro/src/platforms/shared/hook-runner.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { isAdapterFile, extractRuntime } = require('./adapters/conventions');
+
+const ADAPTERS_DIR = path.join(__dirname, 'adapters');
+const VALID_RUNTIMES = new Set(
+  fs.readdirSync(ADAPTERS_DIR)
+    .filter(isAdapterFile)
+    .map(extractRuntime)
+);
+
+const HOOK_MAP = require('../../generated/hook-registry.json');
+
+const runtime  = process.argv[2];
+const hookName = process.argv[3];
+
+if (!runtime || !hookName) {
+  process.stderr.write('Usage: node hook-runner.js <runtime> <hook-name>\n');
+  process.exit(1);
+}
+
+if (!VALID_RUNTIMES.has(runtime)) {
+  process.stderr.write('Unknown runtime: ' + runtime + '\n');
+  process.exit(1);
+}
+
+const hookEntry = HOOK_MAP[hookName];
+if (!hookEntry) {
+  process.stderr.write('Unknown hook: ' + hookName + '\n');
+  process.exit(1);
+}
+
+const adapter = require('./adapters/' + runtime + '-adapter');
+const logicModule = require(path.resolve(__dirname, '../../', hookEntry.module));
+const handler = logicModule[hookEntry.fn];
+
+adapter.readBoundedStdin()
+  .then((raw) => {
+    const ctx = adapter.normalizeInput(raw);
+    return handler(ctx);
+  })
+  .then((result) => {
+    process.stdout.write(JSON.stringify(adapter.formatOutput(result)) + '\n');
+    process.exitCode = adapter.getExitCode(result);
+  })
+  .catch((err) => {
+    process.stderr.write('Hook error: ' + err.message + '\n');
+    process.stdout.write(JSON.stringify(adapter.errorFallback()) + '\n');
+  });