@maestrofrontier/frontier 1.4.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@maestrofrontier/frontier",
+  "version": "1.4.0",
+  "description": "Achieve Frontier AI performance in your CLI by fusing the model CLIs you already run. Maestro Frontier is an opt-in, zero-dependency local multi-CLI fusion engine for AI coding agents: fan a prompt across a panel of any 1 to 8 local model CLIs you pick, have a judge model and a synthesizer you choose read the answers into a structured analysis and write one grounded synthesis (default Opus 4.8, override either with --judge/--synth). On a 100-task benchmark every fusion panel outscored its individual member models. Three adapters ship today: Opus 4.8, GPT-5.5, Gemini 3.1 Pro, with Kimi, DeepSeek, GLM, and Qwen to follow. Off, single, and fusion modes switch via /maestro:frontier. Built on Maestro orchestration discipline: decision-gated routing, verified done-claims, surgical scope, and structural enforcement hooks.",
+  "keywords": ["multi-cli-fusion", "fusion-engine", "frontier", "multi-agent", "orchestration", "claude-code", "gemini", "codex", "agents", "hooks", "doctrine"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mbanderas/maestro.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "maestro": "bin/maestro.cjs"
+  },
+  "files": [
+    "bin/maestro.cjs",
+    "frontier/cli.cjs",
+    "frontier/config.cjs",
+    "frontier/dispatch.cjs",
+    "frontier/judge.cjs",
+    "frontier/run.cjs",
+    "frontier/schema.cjs",
+    "frontier/semaphore.cjs",
+    "frontier/synthesize.cjs",
+    "scripts/install.cjs",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "docs/orchestration.md",
+    "commands/",
+    "integrations/",
+    "hooks/frontier-autorun.cjs",
+    "hooks/hooks.json",
+    "hooks/maestro-doctrine-guard.cjs",
+    "hooks/maestro-gate-reminder.cjs",
+    "hooks/maestro-gate-telemetry.cjs",
+    "hooks/maestro-loop-guard.cjs",
+    "hooks/maestro-phase-scope.cjs",
+    "hooks/maestro-statusline-sync.cjs",
+    "hooks/maestro-subagent-guard.cjs",
+    "hooks/maestro-terse-mode.cjs",
+    "hooks/maestro-toolbudget-advisory.cjs",
+    "settings/cli.cjs",
+    "settings/config.cjs"
+  ],
+  "scripts": {
+    "test": "node scripts/run-hook-tests.cjs",
+    "lint": "npx --yes markdownlint-cli2",
+    "bench-verify": "node scripts/bench-verify.cjs"
+  }
+}

package/scripts/install.cjs

@@ -0,0 +1,490 @@
+#!/usr/bin/env node
+// Maestro installer — writes doctrine + engine + tool wrapper into a target
+// project. Append-only for AGENTS.md, no-clobber for wrapper files, safe to
+// re-run. Zero dependencies (Node stdlib only). CommonJS (.cjs).
+//
+// Usage (as module):  const { run } = require('./install.cjs'); run(argv);
+// Usage (as script):  node scripts/install.cjs [flags]
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+// ---- constants ----
+
+const PKG_ROOT    = path.join(__dirname, '..');
+const SENTINEL    = '<!-- maestro:begin -->';
+const SENTINEL_END = '<!-- maestro:end -->';
+
+// Map target -> { templateSrc, projectDest, userDest }
+// templateSrc is relative to PKG_ROOT.
+// userDest null means no global install path for this target.
+const WRAPPER_MAP = {
+  codex: {
+    src:  'integrations/codex/prompts/frontier.md',
+    proj: '.codex/prompts/frontier.md',
+    user: path.join(os.homedir(), '.codex', 'prompts', 'frontier.md'),
+  },
+  cursor: {
+    src:  'integrations/cursor/commands/frontier.md',
+    proj: '.cursor/commands/frontier.md',
+    user: null, // no global path for cursor
+  },
+  gemini: {
+    src:  'integrations/gemini/commands/frontier.toml',
+    proj: '.gemini/commands/frontier.toml',
+    user: path.join(os.homedir(), '.gemini', 'commands', 'frontier.toml'),
+  },
+  cline: {
+    src:  'integrations/cline/skills/frontier/SKILL.md',
+    proj: '.cline/skills/frontier/SKILL.md',
+    user: path.join(os.homedir(), '.cline', 'skills', 'frontier', 'SKILL.md'),
+  },
+  windsurf: {
+    src:  'integrations/windsurf/workflows/frontier.md',
+    proj: '.windsurf/workflows/frontier.md',
+    user: path.join(os.homedir(), '.codeium', 'windsurf', 'global_workflows', 'frontier.md'),
+  },
+};
+
+// Marker dirs used for auto-detection (scanned inside project root)
+const AUTO_MARKERS = [
+  { dir: '.cursor',  target: 'cursor'   },
+  { dir: '.gemini',  target: 'gemini'   },
+  { dir: '.codex',   target: 'codex'    },
+  { dir: '.cline',   target: 'cline'    },
+  { dir: '.windsurf',target: 'windsurf' },
+  { dir: '.claude',  target: 'claude'   },
+];
+
+// ---- safety helpers ----
+
+/**
+ * Returns true if p is a symlink (lstat-based). Never throws.
+ * @param {string} p
+ * @returns {boolean}
+ */
+function isSymlink(p) {
+  try {
+    return fs.lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Create directories for destPath. Refuses to create through a symlinked
+ * ancestor directory. Returns true on success, false on refusal.
+ * @param {string} destPath
+ * @returns {boolean}
+ */
+function safeMkdirp(destPath) {
+  const dir = path.dirname(destPath);
+  // Walk ancestors from PKG_ROOT outward — only check the leaf dir because
+  // we cannot reliably validate every ancestor on all OSes; the write will
+  // fail safely if anything is wrong.
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write buf to dest. Refuses if dest (or its parent dir) is a symlink.
+ * Returns { ok: true } or { ok: false, reason: string }.
+ * @param {string} dest
+ * @param {string|Buffer} content
+ * @returns {{ ok: boolean, reason?: string }}
+ */
+function safeWrite(dest, content) {
+  // Check parent dir
+  const dir = path.dirname(dest);
+  if (isSymlink(dir)) {
+    return { ok: false, reason: `parent dir is a symlink: ${dir}` };
+  }
+  // Check destination itself
+  if (isSymlink(dest)) {
+    return { ok: false, reason: `destination is a symlink: ${dest}` };
+  }
+  try {
+    fs.writeFileSync(dest, content, 'utf8');
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: String(err.message || err) };
+  }
+}
+
+// ---- parse argv ----
+
+/**
+ * @param {string[]} argv
+ * @returns {{ target: string, project: string, user: boolean, dryRun: boolean, noHooks: boolean }}
+ */
+function parseArgs(argv) {
+  const opts = {
+    target:  'auto',
+    project: process.cwd(),
+    user:    false,
+    dryRun:  false,
+    noHooks: false,
+  };
+
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--target' && i + 1 < argv.length) {
+      opts.target = argv[++i];
+    } else if (a === '--project' && i + 1 < argv.length) {
+      opts.project = argv[++i];
+    } else if (a === '--user') {
+      opts.user = true;
+    } else if (a === '--dry-run') {
+      opts.dryRun = true;
+    } else if (a === '--no-hooks') {
+      opts.noHooks = true;
+    }
+    i++;
+  }
+
+  opts.project = path.resolve(opts.project);
+  return opts;
+}
+
+// ---- auto-detect ----
+
+/**
+ * Detect which tool is in use by looking for marker dirs.
+ * @param {string} projectRoot
+ * @returns {string} detected target or 'none'
+ */
+function detectTarget(projectRoot) {
+  for (const { dir, target } of AUTO_MARKERS) {
+    try {
+      const p = path.join(projectRoot, dir);
+      const st = fs.lstatSync(p);
+      if (st.isDirectory()) return target;
+    } catch {
+      // not found
+    }
+  }
+  return 'none';
+}
+
+// ---- install actions ----
+
+/**
+ * Install doctrine (AGENTS.md) into project root. Append-only, idempotent.
+ * @param {string} projectRoot
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean} true = success (or no-op), false = error
+ */
+function installDoctrine(projectRoot, dryRun, log) {
+  const dest     = path.join(projectRoot, 'AGENTS.md');
+  const srcPath  = path.join(PKG_ROOT, 'AGENTS.md');
+
+  let srcContent;
+  try {
+    srcContent = fs.readFileSync(srcPath, 'utf8');
+  } catch (err) {
+    log(`ERROR: cannot read package AGENTS.md: ${err.message}`);
+    return false;
+  }
+
+  const block = `\n${SENTINEL}\n${srcContent}\n${SENTINEL_END}\n`;
+
+  // Check if dest exists
+  let existsStat;
+  try { existsStat = fs.lstatSync(dest); } catch { existsStat = null; }
+
+  if (existsStat) {
+    if (existsStat.isSymbolicLink()) {
+      log(`ERROR: AGENTS.md is a symlink — refusing to write through it: ${dest}`);
+      return false;
+    }
+
+    let existing;
+    try { existing = fs.readFileSync(dest, 'utf8'); } catch (err) {
+      log(`ERROR: cannot read existing AGENTS.md: ${err.message}`);
+      return false;
+    }
+
+    if (existing.includes(SENTINEL)) {
+      log(`[doctrine] AGENTS.md already contains sentinel — skipping`);
+      return true;
+    }
+
+    // Append block
+    if (dryRun) {
+      log(`[dry-run] would append maestro doctrine to existing ${dest}`);
+      return true;
+    }
+
+    const res = safeWrite(dest, existing + block);
+    if (!res.ok) {
+      log(`ERROR: failed to append to AGENTS.md: ${res.reason}`);
+      return false;
+    }
+    log(`[doctrine] appended maestro block to existing AGENTS.md`);
+    return true;
+  }
+
+  // Absent — write fresh. Wrap in sentinel block so subsequent runs detect it.
+  if (dryRun) {
+    log(`[dry-run] would create ${dest}`);
+    return true;
+  }
+
+  if (!safeMkdirp(dest)) {
+    log(`ERROR: could not create parent dir for ${dest}`);
+    return false;
+  }
+
+  const freshContent = SENTINEL + '\n' + srcContent + '\n' + SENTINEL_END + '\n';
+  const res = safeWrite(dest, freshContent);
+  if (!res.ok) {
+    log(`ERROR: failed to write AGENTS.md: ${res.reason}`);
+    return false;
+  }
+  log(`[doctrine] wrote AGENTS.md`);
+  return true;
+}
+
+/**
+ * Recursively copy srcDir -> destDir, skipping *.test.cjs files.
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean}
+ */
+function copyDirRecursive(srcDir, destDir, dryRun, log) {
+  let entries;
+  try {
+    entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  } catch (err) {
+    log(`ERROR: cannot read dir ${srcDir}: ${err.message}`);
+    return false;
+  }
+
+  let ok = true;
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name.endsWith('.test.cjs')) continue;
+
+    const src  = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!copyDirRecursive(src, dest, dryRun, log)) ok = false;
+    } else if (entry.isFile()) {
+      if (dryRun) {
+        log(`[dry-run] would write ${dest}`);
+        continue;
+      }
+
+      if (isSymlink(dest)) {
+        log(`ERROR: destination is a symlink — refusing: ${dest}`);
+        ok = false;
+        continue;
+      }
+      if (isSymlink(path.dirname(dest))) {
+        log(`ERROR: destination parent is a symlink — refusing: ${dest}`);
+        ok = false;
+        continue;
+      }
+
+      try {
+        fs.mkdirSync(destDir, { recursive: true });
+        const content = fs.readFileSync(src);
+        fs.writeFileSync(dest, content);
+        log(`[engine] copied ${dest}`);
+      } catch (err) {
+        log(`ERROR: failed to copy ${src} -> ${dest}: ${err.message}`);
+        ok = false;
+      }
+    }
+  }
+  return ok;
+}
+
+/**
+ * Install engine files (frontier/ dir + bin/maestro.cjs).
+ * @param {string} projectRoot
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean}
+ */
+function installEngine(projectRoot, dryRun, log) {
+  const srcFrontier  = path.join(PKG_ROOT, 'frontier');
+  const destFrontier = path.join(projectRoot, 'frontier');
+  const srcBin       = path.join(PKG_ROOT, 'bin', 'maestro.cjs');
+  const destBin      = path.join(projectRoot, 'bin', 'maestro.cjs');
+
+  let ok = copyDirRecursive(srcFrontier, destFrontier, dryRun, log);
+
+  // bin/maestro.cjs
+  if (dryRun) {
+    log(`[dry-run] would write ${destBin}`);
+  } else {
+    if (isSymlink(destBin)) {
+      log(`ERROR: bin/maestro.cjs is a symlink — refusing: ${destBin}`);
+      ok = false;
+    } else {
+      try {
+        fs.mkdirSync(path.dirname(destBin), { recursive: true });
+        fs.writeFileSync(destBin, fs.readFileSync(srcBin));
+        log(`[engine] copied ${destBin}`);
+      } catch (err) {
+        log(`ERROR: failed to copy bin/maestro.cjs: ${err.message}`);
+        ok = false;
+      }
+    }
+  }
+
+  return ok;
+}
+
+/**
+ * Install wrapper file (no-clobber).
+ * @param {string} target
+ * @param {string} projectRoot
+ * @param {boolean} userGlobal
+ * @param {boolean} dryRun
+ * @param {(msg: string) => void} log
+ * @returns {boolean}
+ */
+function installWrapper(target, projectRoot, userGlobal, dryRun, log) {
+  if (target === 'claude') {
+    log('[claude] No wrapper file — plugin delivers the command.');
+    log('[claude] To install the plugin: /plugin marketplace add mbanderas/maestro');
+    log('[claude] Then: /plugin install maestro@maestro');
+    return true;
+  }
+
+  const mapping = WRAPPER_MAP[target];
+  if (!mapping) {
+    log(`ERROR: unknown target: ${target}`);
+    return false;
+  }
+
+  const src = path.join(PKG_ROOT, mapping.src);
+
+  let dest;
+  if (userGlobal) {
+    if (!mapping.user) {
+      log(`[wrapper] --user not supported for target ${target} — writing to project instead`);
+      dest = path.join(projectRoot, mapping.proj);
+    } else {
+      dest = mapping.user;
+    }
+  } else {
+    dest = path.join(projectRoot, mapping.proj);
+  }
+
+  // Check if dest exists already (no-clobber)
+  let destStat;
+  try { destStat = fs.lstatSync(dest); } catch { destStat = null; }
+
+  if (destStat) {
+    if (destStat.isSymbolicLink()) {
+      log(`ERROR: wrapper dest is a symlink — refusing: ${dest}`);
+      return false;
+    }
+    log(`[wrapper] skipped (exists, not clobbered): ${dest}`);
+    return true;
+  }
+
+  let srcContent;
+  try {
+    srcContent = fs.readFileSync(src, 'utf8');
+  } catch (err) {
+    log(`ERROR: cannot read template ${src}: ${err.message}`);
+    return false;
+  }
+
+  if (dryRun) {
+    log(`[dry-run] would create ${dest}`);
+    return true;
+  }
+
+  if (!safeMkdirp(dest)) {
+    log(`ERROR: could not create parent dir for ${dest}`);
+    return false;
+  }
+
+  const res = safeWrite(dest, srcContent);
+  if (!res.ok) {
+    log(`ERROR: failed to write wrapper ${dest}: ${res.reason}`);
+    return false;
+  }
+  log(`[wrapper] wrote ${dest}`);
+  return true;
+}
+
+// ---- main entry ----
+
+/**
+ * Run the installer. Returns a numeric exit code (0 = success).
+ * @param {string[]} argv
+ * @returns {number}
+ */
+function run(argv) {
+  const opts = parseArgs(argv || []);
+  const { target: rawTarget, project, user: userGlobal, dryRun } = opts;
+
+  const lines = [];
+  const log = (msg) => { lines.push(msg); process.stdout.write(msg + '\n'); };
+
+  if (dryRun) log('[dry-run] planning only — no files will be written');
+
+  // Resolve target
+  let target = rawTarget;
+  if (target === 'auto') {
+    target = detectTarget(project);
+    if (target === 'none') {
+      log('[auto] no tool marker dir found — installing doctrine + engine only');
+      log('[auto] pass --target <tool> to install a command wrapper');
+    } else {
+      log(`[auto] detected target: ${target}`);
+    }
+  }
+
+  const VALID_TARGETS = ['auto', 'claude', 'codex', 'cursor', 'gemini', 'cline', 'windsurf'];
+  if (!VALID_TARGETS.includes(rawTarget)) {
+    log(`ERROR: unknown --target value: ${rawTarget}`);
+    return 1;
+  }
+
+  let anyError = false;
+
+  // 1. Doctrine
+  if (!installDoctrine(project, dryRun, log)) anyError = true;
+
+  // 2. Engine
+  if (!installEngine(project, dryRun, log)) anyError = true;
+
+  // 3. Wrapper (skip if no specific target detected)
+  if (target !== 'none') {
+    if (!installWrapper(target, project, userGlobal, dryRun, log)) anyError = true;
+  }
+
+  if (anyError) {
+    log('install completed with errors (see above)');
+    return 1;
+  }
+  log('install complete');
+  return 0;
+}
+
+// ---- CLI entry ----
+
+if (require.main === module) {
+  const code = run(process.argv.slice(2));
+  process.exit(code);
+}
+
+module.exports = { run };

package/settings/cli.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// Maestro Settings — portable CLI. Usable from Codex and any other agent,
+// and the write path the /maestro:settings command calls. Subcommands:
+//   settings status [--json]
+//   settings set <terse|frontier|context-bar> <value> [--judge M] [--synth M] [--models a,b,c]
+// All state I/O goes through settings/config.cjs, which is the one writer
+// over the three existing stores. Zero deps, CJS.
+
+'use strict';
+
+const settings = require('./config.cjs');
+
+function getFlag(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i !== -1 && i + 1 < argv.length ? argv[i + 1] : null;
+}
+
+function fmtFrontier(f) {
+  if (!f || !f.mode || f.mode === 'off') return 'off';
+  if (f.mode === 'single') return 'single ' + (f.model || '?');
+  if (f.mode === 'fusion') {
+    let s = 'fusion ' + (f.preset || '?');
+    if (f.preset === 'custom' && Array.isArray(f.models)) s += ' [' + f.models.join(',') + ']';
+    const extra = [];
+    if (f.judgeModel) extra.push('judge=' + f.judgeModel);
+    if (f.synthModel) extra.push('synth=' + f.synthModel);
+    if (extra.length) s += ' ' + extra.join(' ');
+    return s;
+  }
+  return f.mode;
+}
+
+function cmdStatus(argv) {
+  const scope = getFlag(argv, '--scope') || undefined;
+  const all = settings.readAll(scope);
+  if (argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(all, null, 2) + '\n');
+    return;
+  }
+  const t = all.terse;
+  const cb = all.contextBar;
+  const lines = ['Maestro settings'];
+  lines.push('  terse        ' + t.level + '  (source: ' + t.source + ')' +
+    (t.envOverride ? '  [MAESTRO_TERSE_LEVEL override active]' : ''));
+  lines.push('  frontier     ' + fmtFrontier(all.frontier));
+  lines.push('  context-bar  ' + (cb.enabled ? 'on' : 'off') +
+    (cb.scriptConfirmed ? '' : '  [status-line script unconfirmed: ' + cb.dir + ']'));
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+function cmdList(argv) {
+  const c = settings.catalog();
+  if (argv.includes('--json')) {
+    process.stdout.write(JSON.stringify(c, null, 2) + '\n');
+    return;
+  }
+  const labelOf = {};
+  c.frontier.models.forEach(m => { labelOf[m.id] = m.label; });
+  const lines = ['Maestro settings — available values'];
+  lines.push('  terse        ' + c.terse.values.join(' | '));
+  lines.push('  context-bar  ' + c.contextBar.values.join(' | '));
+  lines.push('  frontier     off | single:<model> | fusion:<preset>');
+  lines.push('    models     ' + c.frontier.models.map(m => m.id + ' (' + m.label + ')').join(', '));
+  lines.push('    presets');
+  c.frontier.presets.forEach(p => {
+    const desc = p.models
+      ? p.models.map(id => labelOf[id] || id).join(' + ')
+      : 'choose your own models (--models a,b,c)';
+    lines.push('      ' + p.id.padEnd(14) + desc);
+  });
+  lines.push('    judge/synth  ' + c.frontier.stageModels.join(', ') +
+    '  (default judge=' + c.frontier.defaults.judge + ', synth=' + c.frontier.defaults.synth + ')');
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+function cmdSet(argv) {
+  const key = argv[0];
+  const value = argv[1];
+  if (!key || value === undefined) {
+    process.stderr.write('Usage: settings set <terse|frontier|context-bar> <value>\n');
+    process.exit(2);
+  }
+  const opts = {
+    judge: getFlag(argv, '--judge'),
+    synth: getFlag(argv, '--synth'),
+    models: getFlag(argv, '--models'),
+    model: getFlag(argv, '--model'),
+    preset: getFlag(argv, '--preset'),
+    scope: getFlag(argv, '--scope'),
+  };
+  Object.keys(opts).forEach(k => { if (opts[k] == null) delete opts[k]; });
+
+  const r = settings.setKey(key, value, opts);
+  if (!r.ok) {
+    process.stderr.write('ERROR: ' + r.error + '\n');
+    process.exit(2);
+  }
+  process.stdout.write('set ' + key + ' = ' + value + '\n');
+  if (r.warning) process.stdout.write('WARNING: ' + r.warning + '\n');
+}
+
+function usageText() {
+  return (
+    'Usage:\n' +
+    '  settings status [--json] [--scope <name>]\n' +
+    '  settings list [--json]\n' +
+    '  settings help\n' +
+    '  settings set <key> <value> [--judge M] [--synth M] [--models a,b,c] [--scope <name>]\n' +
+    '    terse        <off|lite|full|ultra>\n' +
+    '    frontier     <off | single:<model> | fusion:<preset>>\n' +
+    '    context-bar  <on|off>\n' +
+    '  --scope targets a named frontier state (e.g. codex, cursor); omit to autodetect (Claude Code => per-workspace cc-<hash>)\n'
+  );
+}
+
+function usage() {
+  process.stderr.write(usageText());
+}
+
+// `help` prints the usage grammar plus the available-values catalog to
+// stdout, so a non-interactive user (Codex, scripts) gets the same matrix the
+// keyboard picker offers.
+function cmdHelp() {
+  process.stdout.write(usageText() + '\n');
+  cmdList([]);
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  if (cmd === 'status') cmdStatus(argv.slice(1));
+  else if (cmd === 'list') cmdList(argv.slice(1));
+  else if (cmd === 'help' || cmd === '--help' || cmd === '-h') cmdHelp();
+  else if (cmd === 'set') cmdSet(argv.slice(1));
+  else { usage(); process.exit(2); }
+}
+
+if (require.main === module) main();
+
+module.exports = { main, fmtFrontier };