@sabaiway/agent-workflow-kit 1.12.0 → 1.14.0

package/tools/procedures.test.mjs

@@ -0,0 +1,303 @@
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, symlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { main, extractSection, CONFIG_REL } from './procedures.mjs';
+import { READY, NEEDS_SKILL } from './detect-backends.mjs';
+
+// Host-independent fixtures: a temp cwd for the config + the REPO's OWN engine via
+// AGENT_WORKFLOW_ENGINE_DIR (it ships references/procedures.md, so the live read is deterministic and
+// needs no separate engine fixture) + an INJECTED synthetic detection (ctx.detect) so the resolved
+// recipe never depends on which backends the test host happens to have installed.
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ENGINE_DIR = join(HERE, '..', '..', 'agent-workflow-engine');
+const CODEX = 'codex-cli-bridge';
+const AGY = 'antigravity-cli-bridge';
+const detect = (codex, agy) => () => [
+  { name: CODEX, readiness: codex },
+  { name: AGY, readiness: agy },
+];
+
+let cwd;
+beforeEach(() => {
+  cwd = mkdtempSync(join(tmpdir(), 'procedures-cwd-'));
+  mkdirSync(join(cwd, 'docs', 'ai'), { recursive: true });
+});
+afterEach(() => {
+  rmSync(cwd, { recursive: true, force: true });
+});
+
+const writeConfig = (json) => writeFileSync(join(cwd, CONFIG_REL), json);
+// Run main() with the repo engine + an injected detection; config comes from the temp cwd.
+const run = (argv, { codex = READY, agy = READY } = {}) =>
+  main(argv, { cwd, env: { AGENT_WORKFLOW_ENGINE_DIR: ENGINE_DIR }, detect: detect(codex, agy) });
+
+describe('procedures CLI — happy path (section verbatim + resolved recipe)', () => {
+  it('plan-authoring prints the canon section + the resolved review recipe, exit 0', () => {
+    const r = run(['plan-authoring'], { codex: READY, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0, r.stderr);
+    assert.match(r.stdout, /## plan-authoring/);
+    assert.match(r.stdout, /Slots: review/);
+    assert.match(r.stdout, /resolved recipes for "plan-authoring"/);
+    assert.match(r.stdout, /review: reviewed — computed default/);
+  });
+
+  it('plan-execution resolves BOTH slots (execute then review)', () => {
+    const r = run(['plan-execution'], { codex: READY, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0, r.stderr);
+    assert.match(r.stdout, /## plan-execution/);
+    assert.match(r.stdout, /Slots: execute, review/);
+    assert.match(r.stdout, /execute: solo — computed default/);
+    assert.match(r.stdout, /review: reviewed — computed default/);
+  });
+
+  it('section extraction is scoped to the requested activity (no sibling section bleeds in)', () => {
+    const r = run(['plan-execution'], { codex: READY, agy: READY });
+    assert.ok(r.stdout.includes('## plan-execution'));
+    assert.ok(!r.stdout.includes('## plan-authoring'), 'only the requested activity section is printed');
+  });
+});
+
+describe('procedures CLI — config IO (§2.2)', () => {
+  it('absent config → computed defaults, stated as configSource:none', () => {
+    const r = run(['plan-authoring', '--json'], { codex: NEEDS_SKILL, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0, r.stderr);
+    const j = JSON.parse(r.stdout);
+    assert.equal(j.configSource, 'none');
+    assert.equal(j.slots.review.source, 'default');
+    assert.equal(j.slots.review.recipe, 'solo', 'no ready backend → review defaults to solo');
+  });
+
+  it('a valid config drives the slot (execute=delegated honoured when codex is ready)', () => {
+    writeConfig(JSON.stringify({ _README: 'composition-root config', 'plan-execution': { execute: 'delegated' } }));
+    const r = run(['plan-execution', '--json'], { codex: READY, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0, r.stderr);
+    const j = JSON.parse(r.stdout);
+    assert.equal(j.configSource, CONFIG_REL);
+    assert.equal(j.slots.execute.recipe, 'delegated');
+    assert.equal(j.slots.execute.source, 'config');
+  });
+
+  it('malformed JSON → loud `path: malformed JSON …`, exit 1', () => {
+    writeConfig('{ not valid json');
+    const r = run(['plan-authoring']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, new RegExp(`${CONFIG_REL}: malformed JSON`));
+  });
+
+  it('schema-invalid (recipe not allowed for the slot) → loud `path: invalid recipe …`, exit 1', () => {
+    writeConfig(JSON.stringify({ 'plan-authoring': { review: 'delegated' } }));
+    const r = run(['plan-authoring']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /invalid recipe "delegated" for review slot of "plan-authoring"/);
+  });
+
+  it('schema-invalid (unknown activity) → exit 1', () => {
+    writeConfig(JSON.stringify({ 'plan-foo': { review: 'reviewed' } }));
+    const r = run(['plan-authoring']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /unknown activity "plan-foo"/);
+  });
+
+  it('schema-invalid (unknown slot) → exit 1', () => {
+    writeConfig(JSON.stringify({ 'plan-authoring': { execute: 'solo' } }));
+    const r = run(['plan-authoring']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, /unknown slot "execute" for activity "plan-authoring"/);
+  });
+
+  it('unreadable config (a directory in its place → EISDIR) → loud `path: unreadable …`, exit 1', () => {
+    mkdirSync(join(cwd, CONFIG_REL)); // orchestration.json IS a dir → readFileSync throws
+    const r = run(['plan-authoring']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, new RegExp(`${CONFIG_REL}: unreadable`));
+  });
+
+  it('a DANGLING symlink at the config path is unreadable (exit 1), NOT silently treated as absent', () => {
+    // A broken config symlink is a present-but-broken config — surface it loudly, never fall through to
+    // defaults (no-silent-failures). lstat sees the link; readFileSync follows it to a missing target.
+    symlinkSync(join(cwd, 'nowhere.json'), join(cwd, CONFIG_REL));
+    const r = run(['plan-authoring']);
+    assert.equal(r.code, 1);
+    assert.match(r.stderr, new RegExp(`${CONFIG_REL}: unreadable`));
+  });
+});
+
+describe('procedures CLI — usage errors → exit 2', () => {
+  it('unknown <activity> → exit 2', () => {
+    const r = run(['plan-foo']);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /unknown activity "plan-foo"/);
+  });
+
+  it('missing <activity> → exit 2', () => {
+    const r = run([]);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /missing <activity>/);
+  });
+
+  it('a bare --override <recipe> (no slot) → exit 2', () => {
+    const r = run(['plan-authoring', '--override', 'council']);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /--override must be <slot>=<recipe>/);
+  });
+
+  it('--override with an unknown slot for the activity → exit 2', () => {
+    const r = run(['plan-authoring', '--override', 'execute=delegated']);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /unknown slot "execute" for activity "plan-authoring"/);
+  });
+
+  it('--override with a recipe invalid for the slot → exit 2', () => {
+    const r = run(['plan-authoring', '--override', 'review=delegated']);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /invalid recipe "delegated" for review slot/);
+  });
+
+  it('a duplicate --override for the same slot → exit 2', () => {
+    const r = run(['plan-execution', '--override', 'review=council', '--override', 'review=solo']);
+    assert.equal(r.code, 2);
+    assert.match(r.stderr, /duplicate override for slot "review"/);
+  });
+});
+
+describe('procedures CLI — override resolution (degrades loudly, still exit 0)', () => {
+  it('an UNSATISFIABLE explicit override degrades loudly and exits 0 with a warning', () => {
+    // council needs two ready reviewers; only codex is ready → degrade to reviewed, flagged loud.
+    const r = run(['plan-authoring', '--override', 'review=council', '--json'], { codex: READY, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0, r.stderr);
+    const j = JSON.parse(r.stdout);
+    assert.equal(j.slots.review.recipe, 'reviewed');
+    assert.equal(j.slots.review.degradedFrom, 'council');
+    assert.equal(j.slots.review.source, 'override');
+    assert.equal(j.warnings.length, 1, 'an unsatisfiable override is surfaced as a loud warning');
+    assert.match(j.warnings[0], /could not be satisfied/);
+  });
+
+  it('the same override in human mode prints a ⚠ warning line', () => {
+    const r = run(['plan-authoring', '--override', 'review=council'], { codex: READY, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /warnings:/);
+    assert.match(r.stdout, /⚠/);
+  });
+
+  it('a satisfiable override holds with no warning (exit 0)', () => {
+    const r = run(['plan-authoring', '--override', 'review=council', '--json'], { codex: READY, agy: READY });
+    assert.equal(r.code, 0);
+    const j = JSON.parse(r.stdout);
+    assert.equal(j.slots.review.recipe, 'council');
+    assert.equal(j.warnings.length, 0);
+  });
+});
+
+describe('procedures CLI — a backend-detection failure does NOT break activity resolution', () => {
+  // A corrupt / unreadable bridge can make the detector throw. Detection is a SECONDARY input (it only
+  // refines the recipe), so a throw must NOT surface as a config/engine error (exit 1) — resolution
+  // floors at Solo and the failure is a loud warning, exit 0.
+  const throwingDetect = () => {
+    throw Object.assign(new Error('corrupt bridge manifest (EISDIR)'), { code: 'EISDIR' });
+  };
+
+  it('detect() throwing → exit 0, a warning, and every slot floors at solo', () => {
+    const r = main(['plan-execution', '--json'], { cwd, env: { AGENT_WORKFLOW_ENGINE_DIR: ENGINE_DIR }, detect: throwingDetect });
+    assert.equal(r.code, 0, r.stderr);
+    const j = JSON.parse(r.stdout);
+    assert.equal(j.slots.execute.recipe, 'solo');
+    assert.equal(j.slots.review.recipe, 'solo');
+    assert.ok(j.warnings.some((w) => /backend detection failed/.test(w)), 'the detection failure is surfaced as a warning');
+  });
+
+  it('the same failure in human mode prints a ⚠ warning, still exit 0', () => {
+    const r = main(['plan-authoring'], { cwd, env: { AGENT_WORKFLOW_ENGINE_DIR: ENGINE_DIR }, detect: throwingDetect });
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /backend detection failed/);
+    assert.match(r.stdout, /review: solo/);
+  });
+});
+
+describe('procedures CLI — --json schema (§2.0)', () => {
+  it('emits activity, section, per-slot resolution, configSource, warnings', () => {
+    const r = run(['plan-execution', '--json'], { codex: READY, agy: NEEDS_SKILL });
+    assert.equal(r.code, 0, r.stderr);
+    const j = JSON.parse(r.stdout);
+    assert.deepEqual(Object.keys(j).sort(), ['activity', 'configSource', 'section', 'slots', 'warnings'].sort());
+    assert.equal(j.activity, 'plan-execution');
+    assert.match(j.section, /## plan-execution/);
+    for (const slot of ['execute', 'review']) {
+      assert.ok(j.slots[slot], `slot ${slot} present`);
+      assert.deepEqual(Object.keys(j.slots[slot]).sort(), ['degradedFrom', 'reason', 'recipe', 'source'].sort());
+    }
+    assert.ok(Array.isArray(j.warnings));
+  });
+});
+
+describe('procedures CLI — --help is read-only and exits 0', () => {
+  it('prints usage naming both activities and exits 0', () => {
+    const r = run(['--help']);
+    assert.equal(r.code, 0);
+    assert.match(r.stdout, /plan-authoring/);
+    assert.match(r.stdout, /plan-execution/);
+    assert.match(r.stdout, /never commits/);
+  });
+});
+
+// §4.0 — an installed engine too old to ship references/procedures.md must FAIL LOUDLY (exit 1 with a
+// clear "upgrade the engine" message), never a cryptic read error. A temp fixture models a VALID
+// methodology-engine that ships every fragment EXCEPT procedures.md (i.e. engine < 1.3.0).
+describe('procedures CLI — engine too old (no procedures.md) → loud exit 1', () => {
+  const makeOldEngine = () => {
+    const dir = mkdtempSync(join(tmpdir(), 'old-engine-'));
+    const manifest = {
+      family: 'agent-workflow',
+      schema: 1,
+      name: 'agent-workflow-engine',
+      kind: 'methodology-engine',
+      version: '1.2.0',
+      available: true,
+      provides: ['plan'],
+      roles: {},
+    };
+    writeFileSync(join(dir, 'capability.json'), JSON.stringify(manifest, null, 2));
+    writeFileSync(join(dir, 'SKILL.md'), "---\nname: agent-workflow-engine\nmetadata:\n  version: '1.2.0'\n---\n# engine\n");
+    mkdirSync(join(dir, 'references'), { recursive: true });
+    writeFileSync(join(dir, 'references', 'methodology-slot.md'), '> methodology fragment\n');
+    // deliberately NO references/procedures.md
+    return dir;
+  };
+
+  it('exits 1 with an upgrade-the-engine message (not a cryptic fs error)', () => {
+    const oldEngine = makeOldEngine();
+    try {
+      const r = main(['plan-authoring'], { cwd, env: { AGENT_WORKFLOW_ENGINE_DIR: oldEngine }, detect: detect(READY, READY) });
+      assert.equal(r.code, 1);
+      assert.match(r.stderr, /procedures\.md/, 'the error names the missing fragment');
+      assert.match(r.stderr, /upgrade the engine|@latest init/i, 'the error tells the user to upgrade the engine');
+    } finally {
+      rmSync(oldEngine, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('extractSection (unit) — boundary + verbatim', () => {
+  const FIXTURE = ['# Title', '', '## plan-authoring', '', 'Slots: review', '', 'step one', '', '## plan-execution', '', 'Slots: execute, review', '', 'step two', ''].join('\n');
+
+  it('returns the requested section, heading-to-next-heading', () => {
+    const sec = extractSection(FIXTURE, 'plan-authoring');
+    assert.match(sec, /## plan-authoring/);
+    assert.match(sec, /Slots: review/);
+    assert.match(sec, /step one/);
+    assert.ok(!sec.includes('plan-execution'), 'stops before the next ## heading');
+  });
+
+  it('extracts the LAST section to EOF', () => {
+    const sec = extractSection(FIXTURE, 'plan-execution');
+    assert.match(sec, /step two/);
+    assert.ok(!sec.includes('plan-authoring'));
+  });
+
+  it('throws (engine-too-old) when the activity section is absent', () => {
+    assert.throws(() => extractSection(FIXTURE, 'plan-nope'), /has no "## plan-nope" section/);
+  });
+});

package/tools/recipes.mjs

@@ -0,0 +1,340 @@
+#!/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` };
+};
+
+// ── activity procedures: per-slot recipe resolution ────────────────────────────────
+
+// The named activities and their typed recipe slots — the EXECUTABLE mirror of the engine canon
+// (agent-workflow-engine/references/procedures.md). Drift-guarded against that canon's `Slots:` lines
+// (recipes.test.mjs): the activity ids and each section's slot set must match this table. The slot
+// VALUE is the slot's recipe-TYPE (used to look up which recipes are valid for it, SLOT_RECIPES); in
+// v1 each slot's key equals its type, but the indirection keeps a future renamed slot expressible.
+export const ACTIVITIES = {
+  'plan-authoring': { slots: { review: 'review' } },
+  'plan-execution': { slots: { execute: 'execute', review: 'review' } },
+};
+
+// Which recipes are valid in each slot type. `review` composes a review DEPTH (Solo / Reviewed /
+// Council); `execute` composes Solo / Delegated (delegation is opt-in). A recipe outside its slot's
+// list is a config error (the IO shell) or a usage error (an --override) — never silently coerced.
+export const SLOT_RECIPES = {
+  review: ['solo', 'reviewed', 'council'],
+  execute: ['solo', 'delegated'],
+};
+
+// The computed default for a slot when the config is silent (no file, or no entry for this slot).
+// review → Reviewed when ANY review-capable backend is `ready`, else Solo (NEVER Council — Council is
+// opt-in; it spends two backends' quota). execute → Solo (Delegated is opt-in only). Readiness-aware,
+// so a computed default is always satisfiable and never itself degrades. Deliberately NOT
+// recommendRecipe (which returns Council when both are ready — that drives the status line, not a
+// per-slot default).
+const computedDefaultForSlot = (slotType, detection) => {
+  if (slotType === 'review') return readyProvidersOf('review', detection).length >= 1 ? 'reviewed' : 'solo';
+  return 'solo'; // execute (and any future opt-in slot) floors at Solo
+};
+
+// resolveActivityRecipe({ config, readiness, activity, slot, override }) → the effective recipe for ONE
+// slot of an activity, with graceful-vs-loud degradation. Precedence: an explicit `override` (degrades
+// LOUDLY — overrideUnsatisfied, so the agent tells the user) > the `config` entry (degrades gracefully)
+// > the computed default (graceful; readiness-aware so it never degrades). Satisfiability + the
+// degradation lattice REUSE planRecipe (Council → Reviewed → Solo; Delegated → Solo) — the single source
+// of the recipe lattice. `readiness` is the detector array ([{ name, readiness }]). Pure; never mutates.
+export const resolveActivityRecipe = ({ config = {}, readiness = [], activity, slot, override } = {}) => {
+  const activityDef = ACTIVITIES[activity];
+  if (!activityDef) throw new Error(`unknown activity: ${activity}`);
+  const slotType = activityDef.slots[slot];
+  if (!slotType) throw new Error(`unknown slot "${slot}" for activity "${activity}"`);
+
+  const configured = config?.[activity]?.[slot];
+  const requested = override ?? configured ?? computedDefaultForSlot(slotType, readiness);
+  const source = override != null ? 'override' : configured != null ? 'config' : 'default';
+
+  // Defensive: the IO shell (config) and CLI (override) validate recipe-for-slot first; a stray value
+  // here is a programmer error, surfaced loudly rather than silently coerced into a neighbour recipe.
+  if (!(SLOT_RECIPES[slotType] ?? []).includes(requested)) {
+    throw new Error(`invalid recipe "${requested}" for ${slotType} slot of "${activity}"`);
+  }
+
+  const plan = planRecipe(requested, readiness);
+  const degraded = plan.degraded;
+  return {
+    recipe: plan.effective,
+    source,
+    degradedFrom: degraded ? requested : null,
+    reason: degraded ? plan.degradation.map((d) => d.reason).join('; ') : null,
+    overrideUnsatisfied: source === 'override' && degraded,
+  };
+};
+
+// ── 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));