@maestrofrontier/frontier 1.4.0

package/frontier/synthesize.cjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Maestro Frontier — synthesis stage: build prompt + invoke Opus for final answer.
+
+'use strict';
+
+const dispatch = require('./dispatch.cjs');
+
+/**
+ * Build the synthesis prompt for Opus.
+ * @param {string} userPrompt
+ * @param {{ analysis?: import('./schema.cjs').Analysis, responses: import('./schema.cjs').PanelResponse[] }} bundle
+ * @param {object} cfg
+ * @returns {string}
+ */
+function buildSynthPrompt(userPrompt, bundle, cfg) {
+  const antiMajority =
+    'Do NOT majority-vote or pick the most common answer; weigh correctness and evidence — ' +
+    'a single correct minority response outweighs a popular wrong one.';
+
+  let groundingSection;
+  if (bundle.analysis) {
+    groundingSection =
+      `PANEL ANALYSIS (structured):
+${JSON.stringify(bundle.analysis, null, 2)}
+
+Ground your final answer in this analysis:
+- Adopt the consensus points as established facts.
+- RESOLVE contradictions by reasoning about which stance is most correct; do not dodge them.
+- Preserve unique insights that add value.
+- Address any blind spots the analysis identified.`;
+  } else {
+    const raw = bundle.responses.map(
+      r => `### Response from ${r.model}\n${r.content}`
+    ).join('\n\n');
+    groundingSection =
+      `RAW PANEL RESPONSES:
+${raw}
+
+Ground your final answer in these responses.`;
+  }
+
+  return `You are a SYNTHESIZER producing the definitive final answer to a user question.
+
+USER QUESTION:
+${userPrompt}
+
+${groundingSection}
+
+IMPORTANT: ${antiMajority}
+
+Write the final answer as clear, direct prose. No JSON, no meta-commentary, no preamble about your process. Output the answer only.`;
+}
+
+/**
+ * Run the synthesis stage. Returns the final answer string or '' on failure (degrades gracefully).
+ * @param {string} userPrompt
+ * @param {{ analysis?: import('./schema.cjs').Analysis, responses: import('./schema.cjs').PanelResponse[] }} bundle
+ * @param {object} cfg
+ * @param {{ spawn?: Function }} [deps]
+ * @returns {Promise<string>}
+ */
+async function runSynth(userPrompt, bundle, cfg, deps) {
+  const spawn = (deps && deps.spawn) || dispatch.spawnOne;
+  let r;
+  try {
+    r = await spawn(
+      buildSynthPrompt(userPrompt, bundle, cfg),
+      cfg.adapters[cfg.synthModel],
+      { timeoutMs: cfg.timeoutMs, fusionDepth: 1 }
+    );
+  } catch {
+    return '';
+  }
+
+  if (r && r.ok && r.content) return r.content;
+  return '';
+}
+
+module.exports = { buildSynthPrompt, runSynth };

package/hooks/frontier-autorun.cjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Maestro Frontier autorun hook (UserPromptSubmit). When the engine is
+// armed (frontier-state mode != 'off'), every user prompt is run through
+// the configured preset/model via runFrontier, and the synthesized answer
+// is injected back as additionalContext with a relay instruction + a
+// one-line preset header, so the live session relays it. mode == 'off' ->
+// zero overhead: no engine require, no spawn, no injected context.
+//
+// Recursion guard (load-bearing): the engine spawns child `claude -p`
+// CLIs, and headless `claude -p` re-fires UserPromptSubmit hooks (verified
+// against the Claude Code hooks contract). dispatch.cjs sets FUSION_DEPTH
+// on every spawned child; this hook no-ops whenever FUSION_DEPTH is present,
+// BEFORE any engine require or spawn. Without it the first armed prompt
+// would fork the engine recursively.
+//
+// Degrade-to-normal: any engine error, empty answer, or thrown exception
+// exits 0 with empty stdout (logging only to stderr), so a broken engine
+// never blocks or corrupts a turn — the session just answers normally. A
+// UserPromptSubmit hook can only ADD context; it cannot suppress the main
+// turn, which is exactly the relay model.
+//
+// .cjs so Node treats it as CommonJS regardless of any parent "type":
+// "module" package.json. configDir/state patterns reused from
+// frontier/config.cjs; structure ported from maestro-terse-mode.cjs.
+
+'use strict';
+
+const fs = require('fs');
+
+function noop() { process.exit(0); }
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { noop(); }
+
+if (data.hook_event_name !== 'UserPromptSubmit') noop();
+
+// Recursion guard FIRST: never run the engine inside an engine-spawned CLI.
+// The engine sets FUSION_DEPTH on every child (dispatch.cjs:108); depth >= 1
+// means we are inside a spawned panel/judge/synth process. Mirror run.cjs's
+// own parseInt check (run.cjs:27) so the two layers agree and a stray
+// FUSION_DEPTH='0'/'' in the environment reads as "not a child".
+const fusionDepth = parseInt(process.env.FUSION_DEPTH || '0', 10);
+if (Number.isFinite(fusionDepth) && fusionDepth >= 1) noop();
+
+let state;
+try {
+  const cfg = require('../frontier/config.cjs');
+  const cwd = data.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  // This hook only ever runs under Claude Code, so force a per-workspace
+  // scope; resolveScope honors --scope/MAESTRO_SCOPE first, then we ensure
+  // we never fall back to the shared legacy 'default' file.
+  let scope = cfg.resolveScope([], { cwd });
+  if (scope === 'default') scope = 'cc-' + cfg.workspaceHash(cwd);
+  state = cfg.loadState(scope);
+} catch {
+  noop();
+}
+
+// Off -> zero overhead: no run.cjs require, no spawn, no injected context.
+if (!state || state.mode === 'off') noop();
+
+const prompt = String(data.prompt || '');
+
+// Optional length gate (default 0 = every prompt). Skips trivially short
+// prompts ("yes"/"ok") so they don't pay a full engine run.
+const rawMin = Number(state.autorunMinChars);
+const minChars = Number.isFinite(rawMin) && rawMin > 0 ? rawMin : 0;
+if (prompt.trim().length < minChars) noop();
+
+// Any unexpected throw after the await boundary degrades to a normal turn,
+// never a non-zero exit / unhandled rejection.
+run().catch((e) => {
+  process.stderr.write('frontier-autorun: ' + ((e && e.message) || e) + '\n');
+  process.exit(0);
+});
+
+async function run() {
+  let result;
+  try {
+    const { runFrontier } = require('../frontier/run.cjs');
+    result = await runFrontier({ prompt, state });
+  } catch (e) {
+    process.stderr.write('frontier-autorun: ' + ((e && e.message) || e) + '\n');
+    noop();
+  }
+
+  if (!result || result.status !== 'ok' || !result.final) {
+    if (result && result.status === 'error') {
+      process.stderr.write(
+        'frontier-autorun: engine error [' + result.failure_reason + ']: ' + result.error + '\n');
+    }
+    noop();
+  }
+
+  const context =
+    'MAESTRO FRONTIER AUTORUN — ' + presetHeader(state) + '\n\n' +
+    'The Maestro Frontier engine already ran this prompt through the panel ' +
+    'above and produced the answer below. Relay it as your response — you ' +
+    'may reformat for clarity, but do not redo the work or contradict it:\n\n' +
+    result.final;
+
+  // fs.writeSync (synchronous, unbuffered) guarantees the full payload reaches
+  // stdout before exit. process.exit() does NOT drain a pipe-backed
+  // process.stdout, which would truncate a large engine answer (multi-KB
+  // synthesis) into malformed JSON the hook consumer cannot parse.
+  fs.writeSync(1, JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: context,
+    },
+  }));
+  process.exit(0);
+}
+
+function presetHeader(st) {
+  if (st.mode === 'single') return 'single · ' + st.model;
+  if (st.mode === 'fusion') {
+    const preset = st.preset === 'custom'
+      ? 'custom (' + (Array.isArray(st.models) ? st.models.join(', ') : '') + ')'
+      : st.preset;
+    return 'fusion · ' + preset;
+  }
+  return String(st.mode);
+}

package/hooks/hooks.json

@@ -0,0 +1,103 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-doctrine-guard.cjs\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-terse-mode.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-statusline-sync.cjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-gate-reminder.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-terse-mode.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/frontier-autorun.cjs\"",
+            "timeout": 300
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-subagent-guard.cjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-loop-guard.cjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-phase-scope.cjs\""
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-toolbudget-advisory.cjs\""
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/maestro-gate-telemetry.cjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/maestro-doctrine-guard.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Maestro PreToolUse doctrine-read guard. Enforces AGENTS.md S7.2
+// structurally: when the doctrine is autoloaded (CLAUDE.md/AGENTS.md
+// present at cwd, which Claude Code injects at session start), a Read
+// of AGENTS.md or CLAUDE.md re-buys tokens for content already in
+// context. This hook replaces the probabilistic S7.2 prose line with a
+// deterministic deny.
+//
+// Modes via MAESTRO_DOCTRINE_GUARD:
+// - "always" (default): deny every doctrine Read while doctrine files
+//   exist at cwd. Safe on Claude Code, where subagents receive the
+//   project doctrine automatically; the deny reason tells the model
+//   to use the in-context copy.
+// - "once": allow the first doctrine Read per session (marker file in
+//   the OS temp dir keyed by session_id), deny repeats. For runtimes
+//   whose subagents genuinely lack the doctrine in context (S7.2:
+//   "a subagent without it in context reads AGENTS.md once").
+// - "0": disabled.
+//
+// When no doctrine file exists at cwd nothing was autoloaded, so reads
+// pass through untouched (e.g. inspecting another repo's AGENTS.md).
+// docs/orchestration.md is never guarded -- it is the on-demand layer
+// and reading it is the intended path. Fails open on any error.
+//
+// Payload fields verified against code.claude.com/docs/en/hooks
+// (PreToolUse input: session_id, cwd, tool_name, tool_input; output:
+// hookSpecificOutput.permissionDecision allow|deny|ask + reason),
+// 2026-06-11.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const mode = process.env.MAESTRO_DOCTRINE_GUARD || 'always';
+if (mode === '0') process.exit(0);
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+if (data.tool_name !== 'Read' || !data.tool_input) process.exit(0);
+
+const fp = data.tool_input.file_path;
+if (typeof fp !== 'string') process.exit(0);
+const base = path.basename(fp).toLowerCase();
+if (base !== 'agents.md' && base !== 'claude.md') process.exit(0);
+
+// Guard only when the doctrine was actually autoloaded: a doctrine file
+// at cwd is what Claude Code injects at session start.
+const cwd = typeof data.cwd === 'string' ? data.cwd : process.cwd();
+let autoloaded = false;
+try {
+  autoloaded = fs.existsSync(path.join(cwd, 'CLAUDE.md'))
+    || fs.existsSync(path.join(cwd, 'AGENTS.md'));
+} catch { autoloaded = false; }
+if (!autoloaded) process.exit(0);
+
+if (mode === 'once' && data.session_id) {
+  const marker = path.join(
+    os.tmpdir(),
+    `maestro-doctrine-guard-${String(data.session_id).replace(/[^a-zA-Z0-9-]/g, '_')}`
+  );
+  if (!fs.existsSync(marker)) {
+    try { fs.writeFileSync(marker, '1'); } catch { /* still allow */ }
+    process.exit(0);
+  }
+}
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'PreToolUse',
+    permissionDecision: 'deny',
+    permissionDecisionReason: 'maestro-doctrine-guard: denied Read of '
+      + path.basename(fp) + ' -- the doctrine is autoloaded into context '
+      + 'at session start (AGENTS.md S7.2); use the in-context copy '
+      + 'instead of re-reading it from disk. The on-demand protocol '
+      + 'layer lives in docs/orchestration.md, which is not blocked.'
+  }
+}));
+process.exit(0);

package/hooks/maestro-gate-reminder.cjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Maestro UserPromptSubmit gate reminder. Soft, additive, fire-once.
+//
+// Injects the Decision Gate checklist (AGENTS.md S1) as additional
+// context on the FIRST user prompt of a session, so the gate survives
+// attention decay in long interactive sessions. Hooks inject context;
+// they cannot force a verdict or a spawn — this is a reminder, not an
+// enforcement gate.
+//
+// Fire-once: a marker file keyed by session_id under the OS temp dir.
+// Opt-out: MAESTRO_GATE_REMINDER=0 disables entirely.
+// The measured default includes the spawn imperative. A shorter
+// verdict-only variant was tested and removed after increasing turns
+// and cost in a 2026-06-12 smoke run.
+//
+// Payload fields verified against code.claude.com/docs/en/hooks
+// (UserPromptSubmit input: session_id, transcript_path, cwd, prompt;
+// stdout JSON hookSpecificOutput.additionalContext is added to
+// context), 2026-06-11.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+if (process.env.MAESTRO_GATE_REMINDER === '0') process.exit(0);
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+if (!data.session_id) process.exit(0);
+
+const marker = path.join(
+  os.tmpdir(),
+  `maestro-gate-reminder-${String(data.session_id).replace(/[^a-zA-Z0-9-]/g, '_')}`
+);
+if (fs.existsSync(marker)) process.exit(0);
+try { fs.writeFileSync(marker, '1'); } catch { /* still remind */ }
+
+const checklistLines = [
+  'Maestro Decision Gate (S1): before the first file edit, output the',
+  'counted verdict line `GATE: files=<n> concerns=<m> -> single-agent',
+  '| multi-agent — <reason>`. files>=5 across 2+ concerns = multi-agent:',
+  'spawn the Planner via the Agent/Task tool BEFORE any edit. A met',
+  'trigger downgrades ONLY on >60% file overlap between subtasks or',
+  '<=3 files total in one dependency chain. Sub-trigger tasks stay',
+  'single-agent.'
+];
+const checklist = checklistLines.join('\n');
+
+process.stdout.write(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: 'UserPromptSubmit',
+    additionalContext: checklist,
+  },
+}));
+process.exit(0);

package/hooks/maestro-gate-telemetry.cjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// Maestro SessionEnd gate telemetry. Strictly opt-in, strictly local.
+//
+// Records one JSON line per session so you can audit your own Decision
+// Gate behavior over time (AGENTS.md S1): did the session route
+// single-agent or multi-agent, how many specialists were spawned, and
+// how the session ended.
+//
+// Privacy: does nothing unless MAESTRO_TELEMETRY=1. Writes only to
+// ~/.claude/maestro-telemetry.jsonl on this machine. No network, ever.
+// Captures counts and the project folder NAME only -- no prompts, no
+// file contents, no paths beyond the basename.
+//
+// Payload fields verified against code.claude.com/docs/en/hooks
+// (SessionEnd input: session_id, transcript_path, cwd, reason;
+// SessionEnd output cannot block), 2026-06-10.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+//
+// Install: see README "Claude Code: Gate Telemetry".
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+if (process.env.MAESTRO_TELEMETRY !== '1') process.exit(0);
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+// Spawn count alone misses the measured failure mode: a multi-agent
+// verdict stated in text but no specialist ever spawned. Parse the S1
+// verdict line too and record verdict vs spawned separately; mismatch
+// flags either direction (multi verdict with 0 spawns, single verdict
+// with spawns). Last verdict line wins (re-gated mid-session).
+const verdictRe = /GATE:\s*files=\S+\s+concerns=\S+\s*->\s*(single|multi)-agent/;
+let agentCount = 0;
+let verdict = null;
+if (data.transcript_path && fs.existsSync(data.transcript_path)) {
+  try {
+    const buf = fs.readFileSync(data.transcript_path, 'utf8');
+    const text = buf.length > 8000000 ? buf.slice(-8000000) : buf;
+    for (const line of text.split(/\r?\n/)) {
+      let e;
+      try { e = JSON.parse(line); } catch { continue; }
+      if (!e || e.type !== 'assistant' || !e.message || !Array.isArray(e.message.content)) continue;
+      for (const item of e.message.content) {
+        if (!item) continue;
+        if (item.type === 'tool_use' && (item.name === 'Task' || item.name === 'Agent')) agentCount++;
+        if (item.type === 'text' && typeof item.text === 'string') {
+          const m = item.text.match(verdictRe);
+          if (m) verdict = m[1];
+        }
+      }
+    }
+  } catch {}
+}
+
+const row = {
+  ts: new Date().toISOString(),
+  session_id: data.session_id || null,
+  gate: agentCount > 0 ? 'multi' : 'single',
+  verdict,
+  agent_count: agentCount,
+  mismatch: verdict !== null && ((verdict === 'multi') !== (agentCount > 0)),
+  reason: data.reason || null,
+  project: data.cwd ? path.basename(data.cwd) : null
+};
+
+try {
+  const dir = path.join(os.homedir(), '.claude');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.appendFileSync(path.join(dir, 'maestro-telemetry.jsonl'), JSON.stringify(row) + '\n');
+} catch {}
+
+process.exit(0);

package/hooks/maestro-loop-guard.cjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Maestro Stop-event loop guard. Enforces AGENTS.md S10 structurally.
+//
+// Fires only when the session shows loop evidence: active session crons
+// (/loop <interval>) in the Stop payload's `session_crons`, or
+// ScheduleWakeup calls (self-paced loops) in the transcript. Then:
+// - Warn when no checkpoint artifact (_*.md) exists in cwd -- S10
+//   requires one durable checkpoint file, read first on every wakeup.
+// - Warn when wakeup count exceeds MAESTRO_LOOP_MAX_ITER (default 50)
+//   -- S10 hard caps: the end condition set at start wins over anything
+//   encountered mid-run.
+//
+// Fires at most once per session (transcript marker), never blocks,
+// degrades silently on missing payload fields. Payload fields verified
+// against code.claude.com/docs/en/hooks and the Claude Code changelog
+// (Stop input: session_crons, transcript_path, cwd;
+// output: hookSpecificOutput.additionalContext), 2026-06-10.
+//
+// .cjs so Node treats it as CommonJS regardless of any "type": "module"
+// package.json in a parent directory of the install location.
+//
+// Install: see README "Claude Code: Loop Guard".
+
+const fs = require('fs');
+const path = require('path');
+
+let data = {};
+try { data = JSON.parse(fs.readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+// Defensive: never re-enter a stop-hook continuation loop.
+if (data.stop_hook_active === true) process.exit(0);
+
+let txText = '';
+const txPath = data.transcript_path;
+if (txPath && fs.existsSync(txPath)) {
+  try {
+    const buf = fs.readFileSync(txPath, 'utf8');
+    txText = buf.length > 2000000 ? buf.slice(-2000000) : buf;
+  } catch {}
+}
+
+// Fire once per session.
+if (txText.includes('Maestro loop guard:')) process.exit(0);
+
+const crons = Array.isArray(data.session_crons) ? data.session_crons : [];
+const wakeups = (txText.match(/"name"\s*:\s*"ScheduleWakeup"/g) || []).length;
+const looping = crons.length > 0 || wakeups > 0;
+if (!looping) process.exit(0);
+
+const warnings = [];
+
+const cap = parseInt(process.env.MAESTRO_LOOP_MAX_ITER, 10) || 50;
+if (wakeups > cap) {
+  warnings.push(`${wakeups} wakeups exceed the iteration cap (${cap}). S10: hard caps bound autonomous runs -- re-check the end condition declared at start; if it is met, deliver the final report and stop scheduling.`);
+}
+
+if (data.cwd) {
+  let hasCheckpoint = false;
+  try {
+    hasCheckpoint = fs.readdirSync(data.cwd).some(f => /^_.+\.md$/i.test(f) && f !== '_.md');
+  } catch { hasCheckpoint = true; } // unreadable cwd: assume fine, fail open
+  if (!hasCheckpoint) {
+    warnings.push('Session is looping but no checkpoint artifact (_<task>.md) exists in the working directory. S10: externalize phase status, findings, and decisions to one durable gitignored file and read it first on every wakeup.');
+  }
+}
+
+if (warnings.length) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'Stop',
+      additionalContext: 'Maestro loop guard:\n- ' + warnings.join('\n- ')
+    }
+  }));
+}
+
+process.exit(0);