@sabaiway/agent-workflow-kit 1.11.0 → 1.13.0

package/tools/inject-methodology.test.mjs

@@ -1,6 +1,6 @@
 import { describe, it, after } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, mkdtempSync, rmSync, chmodSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,8 +17,17 @@ import {
   AGENTS_MD_CAP,
   START_MARKER,
   END_MARKER,
+  ORCH_START_MARKER,
+  ORCH_END_MARKER,
+  ORCHESTRATION_DESCRIPTOR,
+  findMarkerSlot,
+  extractMarkerSlot,
 } from './inject-methodology.mjs';
 
+// Read the orchestration slot's content from a reconciled entry point.
+const extractOrch = (text) => extractMarkerSlot(text, ORCHESTRATION_DESCRIPTOR);
+const hasOrchSlot = (text) => findMarkerSlot(text, ORCHESTRATION_DESCRIPTOR).state === 'ok';
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const SCRIPT = join(HERE, 'inject-methodology.mjs');
 
@@ -29,6 +38,9 @@ const SCRIPT = join(HERE, 'inject-methodology.mjs');
 // Single-line (like the canonical fragment) so byte-equality holds in both LF and CRLF documents.
 const FRAGMENT =
   '> **Workflow methodology (test fixture)** — plan → execute → review. Plans are ephemeral, gitignored, never committed; every Plan ends with a mandatory **Phase: Cleanup**.\n';
+// The SECOND bounded fragment (Plan 4) — distinct content so a test can tell which slot got which.
+const ORCH_FRAGMENT =
+  '> **Orchestration recipes (test fixture)** — Solo / Reviewed / Council / Delegated; pick one with `/agent-workflow-kit recipes`.\n';
 
 // Temp dirs created by the fixtures below — cleaned up once after the whole file.
 const tmpDirs = [];
@@ -36,8 +48,9 @@ after(() => tmpDirs.forEach((d) => rmSync(d, { recursive: true, force: true })))
 
 // A minimal but VALID installed-engine fixture: a methodology-engine capability.json + a SKILL.md
 // whose metadata.version matches it (the validator's authoritative version source when there is no
-// package.json) + the live fragment at references/methodology-slot.md. detectEngine accepts it.
-const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0') => {
+// package.json) + BOTH live fragments (methodology + orchestration). detectEngine accepts it; pass
+// `orchFragment = null` to model an OLDER engine (<1.2.0) that ships no orchestration fragment.
+const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0', orchFragment = ORCH_FRAGMENT) => {
   const dir = mkdtempSync(join(tmpdir(), 'engine-fixture-'));
   tmpDirs.push(dir);
   const manifest = {
@@ -54,6 +67,7 @@ const makeEngineFixture = (fragment = FRAGMENT, version = '1.0.0') => {
   writeFileSync(join(dir, 'SKILL.md'), `---\nname: agent-workflow-engine\nmetadata:\n  version: '${version}'\n---\n# engine\n`);
   mkdirSync(join(dir, 'references'), { recursive: true });
   writeFileSync(join(dir, 'references', 'methodology-slot.md'), fragment);
+  if (orchFragment != null) writeFileSync(join(dir, 'references', 'orchestration-slot.md'), orchFragment);
   return dir;
 };
 
@@ -66,6 +80,11 @@ const withEngine = (engineDir) => ({ ...process.env, AGENT_WORKFLOW_ENGINE_DIR:
 const wrap = (inner) =>
   `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${inner}${END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
 
+// An entry point carrying BOTH reconciled slots (the orchestration pair sits right under the
+// methodology pair, as the descriptor anchors it) — the deployed shape after a dual-slot reconcile.
+const wrapDual = (methInner, orchInner) =>
+  `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${methInner}${END_MARKER}\n${ORCH_START_MARKER}${orchInner}${ORCH_END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
+
 // The exact Session-Protocols line both deployed templates carry — the slot anchor.
 const ANCHOR_LINE =
   'Start-of-session, during-work, and task-completion procedures live in [`docs/ai/agent_rules.md`](./docs/ai/agent_rules.md) §1. **Read it before any code change.**';
@@ -401,26 +420,32 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     }
   };
 
-  it('markerless legacy (with anchor) → slot inserted + filled from the live engine fragment (exit 0)', () => {
+  it('markerless legacy (with anchor) → BOTH slots inserted + filled from their own live engine fragments (exit 0)', () => {
     withTempAgents(legacyWithAnchor(), (agents) => {
       execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
       const out = readFileSync(agents, 'utf8');
       assert.equal(findSlot(out).state, 'ok');
-      assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim(), 'methodology slot filled from the methodology fragment');
+      assert.ok(hasOrchSlot(out), 'the orchestration slot was inserted below the methodology pair');
+      assert.equal(extractOrch(out).trim(), ORCH_FRAGMENT.trim(), 'orchestration slot filled from the orchestration fragment');
     });
   });
 
-  it('present empty slot → filled from the live engine fragment (exit 0)', () => {
+  it('present empty methodology slot → BOTH slots filled; each from its OWN engine fragment (exit 0)', () => {
     withTempAgents(wrap('\n'), (agents) => {
       execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) });
-      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), FRAGMENT.trim());
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
+      assert.equal(extractOrch(out).trim(), ORCH_FRAGMENT.trim());
+      // Per-slot fragment sourcing: the two slots carry DIFFERENT content (not both the methodology one).
+      assert.notEqual(extractSlot(out).trim(), extractOrch(out).trim());
     });
   });
 
-  it('filled/customized slot → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
-    const custom = wrap('\nuser notes\n');
+  it('BOTH slots already filled → zero-diff no-op WITHOUT consulting the engine (engine absent, exit 0)', () => {
+    const custom = wrapDual('\nuser meth notes\n', '\nuser orch notes\n');
     withTempAgents(custom, (agents) => {
-      // Engine pointed at a path that does not exist — a filled slot must NOT require it.
+      // Engine pointed at a path that does not exist — a fully-filled entry point must NOT require it.
       execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
       assert.equal(readFileSync(agents, 'utf8'), custom);
     });
@@ -444,7 +469,7 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     });
   });
 
-  it('explicit [fragment.md] override fills from that file and skips engine resolution (engine absent)', () => {
+  it('explicit [fragment.md] override fills methodology ONLY and skips both engine + the orchestration slot', () => {
     const override = '> custom override fragment line\n';
     const fdir = mkdtempSync(join(tmpdir(), 'frag-'));
     tmpDirs.push(fdir);
@@ -452,7 +477,98 @@ describe('reconcile CLI — atomic ensure+inject-if-empty+cap, reading the fragm
     writeFileSync(fpath, override);
     withTempAgents(wrap('\n'), (agents) => {
       execFileSync(process.execPath, [SCRIPT, 'reconcile', agents, fpath], { stdio: 'pipe', env: withEngine(NO_ENGINE) });
-      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), override.trim());
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(out).trim(), override.trim(), 'methodology filled from the explicit fragment');
+      assert.ok(!hasOrchSlot(out), 'an explicit single-file override binds methodology only — no orchestration slot added');
+    });
+  });
+
+  it('dual-block cap → orchestration pointer is SOFT-skipped (reported), the file is byte-unchanged (exit 0)', () => {
+    // A 100-line entry point with a FILLED methodology slot + an EMPTY orchestration slot: filling the
+    // orchestration slot would push it to 101 > 100, so it is skipped loudly while methodology stays.
+    const head = [
+      '# AGENTS.md',
+      '',
+      '## Session Protocols',
+      '',
+      'Read it before any code change.',
+      '',
+      START_MARKER,
+      FRAGMENT.trim(),
+      END_MARKER,
+      ORCH_START_MARKER,
+      ORCH_END_MARKER,
+    ];
+    const pad = Array.from({ length: AGENTS_MD_CAP - head.length }, (_, i) => `pad line ${i}`);
+    const atCap = [...head, ...pad].join('\n') + '\n';
+    withTempAgents(atCap, (agents) => {
+      const out = execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { encoding: 'utf8', env: withEngine(ENGINE) });
+      assert.match(out, /skipped/i, 'the orchestration cap-skip is reported, not silent');
+      assert.equal(readFileSync(agents, 'utf8'), atCap, 'file byte-unchanged — the orchestration pointer was withheld, methodology already present');
+    });
+  });
+
+  it('malformed orchestration pair → hard STOP (nonzero), file byte-unchanged (methodology fine)', () => {
+    const malformedOrch =
+      `# AGENTS.md\n\nintro line.\n\n${START_MARKER}\n${FRAGMENT.trim()}\n${END_MARKER}\n` +
+      `${ORCH_START_MARKER}\n${ORCH_END_MARKER}\n${ORCH_START_MARKER}\n${ORCH_END_MARKER}\n`;
+    withTempAgents(malformedOrch, (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), malformedOrch, 'no partial write on an orchestration STOP');
+    });
+  });
+
+  it('engine too old (no orchestration fragment) → methodology filled, orchestration SOFT-skipped (exit 0, not a regression)', () => {
+    // A VALID engine that ships methodology-slot.md but NOT orchestration-slot.md (i.e. <1.2.0). The
+    // methodology fill must NOT be discarded — only the recipes pointer is withheld, reported, exit 0.
+    const oldEngine = makeEngineFixture(FRAGMENT, '1.0.0', null);
+    withTempAgents(wrap('\n'), (agents) => {
+      const out = execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { encoding: 'utf8', env: withEngine(oldEngine) });
+      const text = readFileSync(agents, 'utf8');
+      assert.equal(extractSlot(text).trim(), FRAGMENT.trim(), 'methodology pointer filled (not discarded by the too-old engine)');
+      assert.match(out, /skipped/i, 'the orchestration skip is reported (not silent)');
+      assert.match(out, /too old/i, 'the skip names the too-old-engine reason');
+      assert.ok(!hasOrchSlot(text), 'a too-old engine adds no orchestration pointer');
+    });
+  });
+
+  it('orchestration fragment PRESENT but unreadable → hard STOP (a corrupt engine is NOT mislabeled "too old")', () => {
+    if (process.getuid && process.getuid() === 0) return; // root bypasses 0o000 perms — can't restrict
+    const corruptEngine = makeEngineFixture(FRAGMENT, '1.2.0', '> orchestration line\n'); // both fragments present
+    const orchPath = join(corruptEngine, 'references', 'orchestration-slot.md');
+    chmodSync(orchPath, 0o000);
+    let restricted = false;
+    try {
+      readFileSync(orchPath, 'utf8');
+    } catch {
+      restricted = true;
+    }
+    if (!restricted) {
+      chmodSync(orchPath, 0o644); // exotic FS / perms ignored → can't exercise this path here
+      return;
+    }
+    try {
+      withTempAgents(wrap('\n'), (agents) => {
+        assert.throws(() =>
+          execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(corruptEngine) }),
+        );
+        assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), '', 'no partial write on a corrupt-fragment STOP');
+      });
+    } finally {
+      chmodSync(orchPath, 0o644); // restore so the after() cleanup can remove the fixture
+    }
+  });
+
+  it('fully absent engine + a fill needed → hard STOP (methodology fragment also unavailable)', () => {
+    // Distinct from the too-old case: a fully absent engine cannot supply EITHER fragment, so the
+    // methodology slot fill itself STOPs first — the dual-slot reconcile never silently no-ops.
+    withTempAgents(wrap('\n'), (agents) => {
+      assert.throws(() =>
+        execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe', env: withEngine(NO_ENGINE) }),
+      );
+      assert.equal(readFileSync(agents, 'utf8'), wrap('\n'), 'no partial write when the engine is fully absent');
     });
   });
 

package/tools/manifest/validate.mjs

@@ -77,7 +77,9 @@ const readSkillVersion = (text) => {
 
 // Authoritative version source: package.json where one exists, else SKILL.md
 // frontmatter metadata.version. So a bridge (no package.json) can't drift from its SKILL.md.
-const readAuthoritativeVersion = (skillDir) => {
+// Exported so the family registry (tools/family-registry.mjs) reports an INSTALLED member's
+// version from the SAME authoritative source the validator checks — no second, drifting reader.
+export const readAuthoritativeVersion = (skillDir) => {
   const pkgPath = join(skillDir, 'package.json');
   if (existsSync(pkgPath)) {
     try {

package/tools/recipes.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// Recipe planner — the pure brain behind the read-only `/agent-workflow-kit recipes` advisor.
+//
+// A "recipe" is a NAMED orchestration pattern over the family's optional execution-backends (the
+// subscription-CLI bridges: codex-cli-bridge → `codex`, antigravity-cli-bridge → `agy`), composed
+// into the plan → execute → review flow. The ENGINE owns the canonical narrative
+// (agent-workflow-engine/references/orchestration.md — the when/why, kept in lockstep by the
+// recipe-name parity guard in recipes.test.mjs); this module owns the EXECUTABLE dispatch: given a
+// recipe + the read-only detector's view of the environment, which backend does which role, how it
+// degrades when a backend isn't ready, and the advisory quota/health notes.
+//
+// Invariants (the backends/status posture): pure (no fs/network/CLI in planRecipe/recommendRecipe),
+// read-only, NEVER runs a subscription CLI. The kit only surfaces/selects/plans a recipe — the
+// orchestrator (the main agent) executes it via the bridge skills and always makes the single commit;
+// a backend is advisory or delegated, never autonomous. Dependency-free, Node >= 18.
+
+import { pathToFileURL } from 'node:url';
+import {
+  detectBackends,
+  READY,
+  NEEDS_SKILL,
+  NEEDS_CLI,
+  NEEDS_CREDENTIALS,
+  DEGRADED,
+} from './detect-backends.mjs';
+
+const CODEX = 'codex-cli-bridge';
+const AGY = 'antigravity-cli-bridge';
+
+// The manifest-name → human-alias map (the detector emits manifest names; humans say codex/agy).
+export const DISPLAY_ALIASES = { [CODEX]: 'codex', [AGY]: 'agy' };
+
+// The backend → role table, keyed by the manifest name the detector emits (status.name) — NOT the
+// display alias. Drift-guarded against each bridge capability.json `provides[]` (recipes.test.mjs).
+export const BACKEND_ROLES = {
+  [CODEX]: ['execute', 'review'],
+  [AGY]: ['review', 'probe'],
+};
+
+// Advisory metadata the DETECTION object does not carry (it has no cost/quota — those live only in
+// capability.json). cost/quota are drift-guarded against the manifests; the agy `health` advisory is
+// static project knowledge (Issue-001: the Antigravity service can stall on substantive prompts —
+// invisible to file-presence detection, so it is NOT a readiness signal, only a standing caveat).
+export const BACKEND_META = {
+  [CODEX]: { cost: 'subscription', quota: { kind: 'subscription', finite: true } },
+  [AGY]: {
+    cost: 'subscription',
+    quota: { kind: 'subscription', finite: true },
+    health: 'Note: the Antigravity service may stall on substantive prompts (Issue-001) — prefer codex while it lasts.',
+  },
+};
+
+// Deterministic tie-break order: codex before agy (agy carries the standing health caveat above).
+const BACKEND_PRIORITY = [CODEX, AGY];
+const priorityIndex = (name) => {
+  const i = BACKEND_PRIORITY.indexOf(name);
+  return i === -1 ? BACKEND_PRIORITY.length : i;
+};
+
+// The four recipes, in lattice order. `role` is the backend role a recipe needs (null = Solo, no
+// backend); `minBackends` is how many READY providers it needs; `degradesTo` is the next-weaker
+// recipe when it can't be satisfied (the chain terminates at Solo, which is always satisfiable).
+export const RECIPES = [
+  {
+    id: 'solo',
+    title: 'Solo',
+    role: null,
+    minBackends: 0,
+    degradesTo: null,
+    summary: 'the orchestrator plans, executes, and self-reviews — no backend (always available; the floor).',
+  },
+  {
+    id: 'reviewed',
+    title: 'Reviewed',
+    role: 'review',
+    minBackends: 1,
+    degradesTo: 'solo',
+    summary: 'the orchestrator executes; one backend reviews the result (advisory). Prefers codex when both are ready.',
+  },
+  {
+    id: 'council',
+    title: 'Council',
+    role: 'review',
+    minBackends: 2,
+    degradesTo: 'reviewed',
+    summary: 'both backends review independently; the orchestrator synthesizes the two opinions.',
+  },
+  {
+    id: 'delegated',
+    title: 'Delegated',
+    role: 'execute',
+    minBackends: 1,
+    degradesTo: 'solo',
+    summary: 'the orchestrator hands a bounded execution sub-task to a backend (codex exec), then reviews the diff and commits.',
+  },
+];
+
+const recipeById = (id) => RECIPES.find((r) => r.id === id);
+
+// The human reason a non-ready readiness yields (read-only file-presence remedies — never a claim
+// about whether the backend's service is responsive).
+const READINESS_REASON = {
+  [NEEDS_SKILL]: 'bridge skill not installed — run /agent-workflow-kit setup',
+  [NEEDS_CLI]: 'the CLI is not installed',
+  [NEEDS_CREDENTIALS]: 'not signed in (credentials missing)',
+  [DEGRADED]: 'wrapper not on PATH — run /agent-workflow-kit setup',
+};
+
+// ── pure planner ───────────────────────────────────────────────────────────────
+
+// Backends (ready or not) whose role table includes `role`.
+const providersOf = (role, detection) => detection.filter((b) => (BACKEND_ROLES[b.name] ?? []).includes(role));
+
+// READY providers of `role`, in deterministic priority order (codex before agy) → an array of names.
+const readyProvidersOf = (role, detection) =>
+  providersOf(role, detection)
+    .filter((b) => b.readiness === READY)
+    .sort((a, b) => priorityIndex(a.name) - priorityIndex(b.name))
+    .map((b) => b.name);
+
+// Availability = readiness === READY, full stop. A recipe is satisfiable iff it needs no backend OR
+// enough READY providers of its role exist.
+const isSatisfiable = (recipe, detection) =>
+  recipe.role === null || readyProvidersOf(recipe.role, detection).length >= recipe.minBackends;
+
+// Why a recipe can't run as-is — the specific not-ready providers and their readiness-derived reasons.
+const degradeReason = (recipe, detection) => {
+  const providers = providersOf(recipe.role, detection);
+  if (providers.length === 0) {
+    return `${recipe.title} needs a backend providing ${recipe.role}, but no backend provides it`;
+  }
+  const ready = providers.filter((b) => b.readiness === READY);
+  const detail = providers
+    .filter((b) => b.readiness !== READY)
+    .map((b) => `${DISPLAY_ALIASES[b.name] ?? b.name}: ${READINESS_REASON[b.readiness] ?? b.readiness}`)
+    .join('; ');
+  return `${recipe.title} needs ${recipe.minBackends} backend(s) providing ${recipe.role}, but only ${ready.length} ready${detail ? ` — ${detail}` : ''}`;
+};
+
+// Per-stage dispatch for an EFFECTIVE (already-satisfiable) recipe: the first `minBackends` READY
+// providers, in priority order. Solo dispatches nothing (the orchestrator does it all).
+const dispatchFor = (recipe, detection) => {
+  if (recipe.role === null) return [];
+  return readyProvidersOf(recipe.role, detection)
+    .slice(0, recipe.minBackends)
+    .map((name) => ({ role: recipe.role, backend: name, display: DISPLAY_ALIASES[name] }));
+};
+
+const QUOTA_NOTE = "Prefer the cheapest model that fits the task; don't reach for a top-tier model by reflex.";
+const COUNCIL_QUOTA_NOTE = "Council spends two backends' quota for one decision — reserve it for changes that justify the cost.";
+
+// Advisory notes for an effective recipe: a quota reminder when any backend is dispatched, the
+// two-quota caveat for Council, and the agy health advisory whenever the dispatch actually uses agy.
+const notesFor = (recipe, dispatch) => {
+  const notes = [];
+  if (dispatch.length > 0) notes.push(QUOTA_NOTE);
+  if (recipe.id === 'council') notes.push(COUNCIL_QUOTA_NOTE);
+  if (dispatch.some((d) => d.backend === AGY) && BACKEND_META[AGY].health) notes.push(BACKEND_META[AGY].health);
+  return notes;
+};
+
+// planRecipe(recipe, detection) → pure plan. `recipe` is a recipe id or descriptor. Walks the
+// degradation chain (with a stated reason per step) until a satisfiable recipe is reached, then emits
+// the per-stage dispatch + advisory notes. Deterministic; never mutates the detection input.
+export const planRecipe = (recipe, detection) => {
+  const requested = typeof recipe === 'string' ? recipeById(recipe) : recipe;
+  if (!requested) throw new Error(`unknown recipe: ${recipe}`);
+  let current = requested;
+  const degradation = [];
+  while (!isSatisfiable(current, detection)) {
+    const next = recipeById(current.degradesTo);
+    degradation.push({ from: current.id, to: next.id, reason: degradeReason(current, detection) });
+    current = next;
+  }
+  const dispatch = dispatchFor(current, detection);
+  return {
+    requested: requested.id,
+    effective: current.id,
+    degraded: current.id !== requested.id,
+    degradation,
+    dispatch,
+    notes: notesFor(current, dispatch),
+  };
+};
+
+// How close to ready a non-ready backend is — used to surface the most-actionable remedy first.
+const READINESS_RANK = { [DEGRADED]: 3, [NEEDS_CREDENTIALS]: 2, [NEEDS_CLI]: 1, [NEEDS_SKILL]: 0 };
+const READINESS_REMEDY = {
+  [NEEDS_SKILL]: 'run /agent-workflow-kit setup',
+  [NEEDS_CLI]: 'install its CLI',
+  [NEEDS_CREDENTIALS]: 'sign in',
+  [DEGRADED]: 'run /agent-workflow-kit setup (wrapper not on PATH)',
+};
+
+// recommendRecipe(detection) → { recipe, clause }. Never blank: both ready → Council (Reviewed the
+// everyday default); one ready → Reviewed; none installed → Solo + a setup pointer; a backend
+// present-but-not-ready → Solo with that backend's specific remedy. Pure.
+export const recommendRecipe = (detection) => {
+  const readyReview = readyProvidersOf('review', detection);
+  if (readyReview.length >= 2) {
+    return { recipe: 'council', clause: 'Council available, Reviewed the everyday default' };
+  }
+  if (readyReview.length === 1) {
+    return { recipe: 'reviewed', clause: `Reviewed available (via ${DISPLAY_ALIASES[readyReview[0]]})` };
+  }
+  // No ready reviewer → Solo. Say how to unlock more: a present-but-not-ready backend names its
+  // remedy; nothing installed names the setup pointer.
+  const present = detection.filter((b) => b.readiness !== NEEDS_SKILL && b.readiness !== READY);
+  if (present.length === 0) {
+    return { recipe: 'solo', clause: 'Solo — run /agent-workflow-kit setup to add a backend' };
+  }
+  // Rank by how close to ready; break ties with the SAME codex-before-agy priority the dispatch path
+  // uses (priorityIndex) so the recommendation is deterministic regardless of detection emission order.
+  const best = [...present].sort(
+    (a, b) => (READINESS_RANK[b.readiness] ?? -1) - (READINESS_RANK[a.readiness] ?? -1) || priorityIndex(a.name) - priorityIndex(b.name),
+  )[0];
+  const remedy = READINESS_REMEDY[best.readiness] ?? best.readiness;
+  return { recipe: 'solo', clause: `Solo — ${DISPLAY_ALIASES[best.name] ?? best.name}: ${remedy} to unlock Reviewed` };
+};
+
+// ── report + CLI ─────────────────────────────────────────────────────────────────
+
+// The structured report behind `--json` — the recipes, the recommendation, and a plan per recipe.
+export const buildReport = (detection) => ({
+  recipes: RECIPES.map(({ id, title, role, minBackends, degradesTo, summary }) => ({
+    id,
+    title,
+    role,
+    minBackends,
+    degradesTo,
+    summary,
+  })),
+  recommendation: recommendRecipe(detection),
+  plans: RECIPES.map((r) => planRecipe(r.id, detection)),
+});
+
+// formatRecipes(detection) → deterministic human advisor text: the four recipes, the recommendation,
+// and the per-recipe plan for the current environment (degradation reasons + dispatch + notes).
+export const formatRecipes = (detection) => {
+  const lines = [
+    'agent-workflow orchestration recipes (read-only — the orchestrator executes via the bridge skills and always commits)',
+    '',
+  ];
+  for (const r of RECIPES) lines.push(`  ${r.title} (${r.id}) — ${r.summary}`);
+  const rec = recommendRecipe(detection);
+  lines.push('', `recommended here: ${rec.recipe} — ${rec.clause}`, '', 'plan for the current environment:');
+  for (const r of RECIPES) {
+    const p = planRecipe(r.id, detection);
+    const arrow = p.degraded ? ` → ${p.effective}` : '';
+    const who = p.dispatch.length ? p.dispatch.map((d) => `${d.display} ${d.role}`).join(', ') : 'orchestrator only';
+    lines.push(`  ${r.title}${arrow}: ${who}`);
+    for (const step of p.degradation) lines.push(`      ↳ ${step.reason}`);
+    for (const note of p.notes) lines.push(`      • ${note}`);
+  }
+  return lines.join('\n');
+};
+
+const main = (argv) => {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    console.log(`recipes — read-only orchestration-recipe advisor for the agent-workflow family.
+
+Usage:
+  node recipes.mjs [--json]
+
+Lists the four recipes (Solo / Reviewed / Council / Delegated) and, from the read-only backend
+detector, plans + recommends one for the current environment. Detection only — never writes, never
+commits, never runs a subscription CLI.`);
+    return;
+  }
+  const detection = detectBackends();
+  if (argv.includes('--json')) console.log(JSON.stringify(buildReport(detection), null, 2));
+  else console.log(formatRecipes(detection));
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));