@sabaiway/agent-workflow-kit 1.13.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

@@ -218,6 +218,70 @@ export const recommendRecipe = (detection) => {
   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.

package/tools/recipes.test.mjs

@@ -9,8 +9,11 @@ import {
   BACKEND_ROLES,
   BACKEND_META,
   DISPLAY_ALIASES,
+  ACTIVITIES,
+  SLOT_RECIPES,
   planRecipe,
   recommendRecipe,
+  resolveActivityRecipe,
   formatRecipes,
 } from './recipes.mjs';
 import { READY, NEEDS_SKILL, NEEDS_CLI, NEEDS_CREDENTIALS, DEGRADED } from './detect-backends.mjs';
@@ -349,6 +352,178 @@ describe('formatRecipes — deterministic advisor text', () => {
   });
 });
 
+// ── ACTIVITIES + resolveActivityRecipe (the activity-procedures resolver) ───────────
+
+describe('ACTIVITIES — the v1 activity/slot table', () => {
+  it('declares exactly plan-authoring (review) and plan-execution (execute, review)', () => {
+    assert.deepEqual(Object.keys(ACTIVITIES), ['plan-authoring', 'plan-execution']);
+    assert.deepEqual(Object.keys(ACTIVITIES['plan-authoring'].slots), ['review']);
+    assert.deepEqual(Object.keys(ACTIVITIES['plan-execution'].slots), ['execute', 'review']);
+  });
+
+  it('every slot type maps to a SLOT_RECIPES list, and every listed recipe is a real RECIPE id', () => {
+    const recipeIds = new Set(RECIPES.map((r) => r.id));
+    for (const def of Object.values(ACTIVITIES)) {
+      for (const slotType of Object.values(def.slots)) {
+        assert.ok(Array.isArray(SLOT_RECIPES[slotType]), `slot type "${slotType}" has a recipe list`);
+        for (const id of SLOT_RECIPES[slotType]) assert.ok(recipeIds.has(id), `"${id}" is a real recipe`);
+      }
+    }
+  });
+
+  it('review composes solo|reviewed|council; execute composes solo|delegated', () => {
+    assert.deepEqual(SLOT_RECIPES.review, ['solo', 'reviewed', 'council']);
+    assert.deepEqual(SLOT_RECIPES.execute, ['solo', 'delegated']);
+  });
+});
+
+// The activity/slot drift guard — the JS ACTIVITIES table must match the engine canon's parseable
+// `Slots:` lines (the kit parses ONLY that line; the steps are rendered verbatim). Clones the
+// engine↔kit recipe-name parity pattern above.
+describe('engine↔kit activity/slot parity — ACTIVITIES matches procedures.md `Slots:` lines', () => {
+  const PROCEDURES = readFileSync(join(REPO_ROOT, 'agent-workflow-engine', 'references', 'procedures.md'), 'utf8');
+  const sectionOf = (activity) => {
+    const lines = PROCEDURES.split('\n');
+    const start = lines.findIndex((l) => l.trim() === `## ${activity}`);
+    if (start === -1) return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+      if (/^## /.test(lines[i])) {
+        end = i;
+        break;
+      }
+    }
+    return lines.slice(start, end);
+  };
+  const slotsOf = (activity) => {
+    const sec = sectionOf(activity);
+    if (!sec) return null;
+    const slotsLine = sec.slice(1).map((l) => l.trim()).find((l) => l.startsWith('Slots:'));
+    if (!slotsLine) return null;
+    return slotsLine
+      .replace(/^Slots:\s*/, '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+  };
+
+  for (const [activity, def] of Object.entries(ACTIVITIES)) {
+    it(`${activity}: the canon's Slots line equals the JS slot set`, () => {
+      assert.deepEqual(slotsOf(activity), Object.keys(def.slots), `procedures.md "## ${activity}" Slots: drifted from ACTIVITIES`);
+    });
+  }
+
+  it('procedures.md declares no activity section absent from the ACTIVITIES table', () => {
+    const headingIds = PROCEDURES.split('\n')
+      .filter((l) => /^## /.test(l))
+      .map((l) => l.replace(/^##\s+/, '').trim());
+    for (const id of headingIds) assert.ok(ACTIVITIES[id], `procedures.md "## ${id}" has no ACTIVITIES entry`);
+  });
+});
+
+describe('resolveActivityRecipe — defaults (config silent), readiness-aware', () => {
+  it('review default is Reviewed when a backend is ready — NOT Council (recommendRecipe is not reused)', () => {
+    const r = resolveActivityRecipe({ readiness: detect(READY, READY), activity: 'plan-authoring', slot: 'review' });
+    assert.equal(r.recipe, 'reviewed');
+    assert.equal(r.source, 'default');
+    assert.equal(r.degradedFrom, null);
+    // sanity: recommendRecipe DOES return council for the same detection — the default must not.
+    assert.equal(recommendRecipe(detect(READY, READY)).recipe, 'council');
+  });
+
+  it('review default is Solo when no backend is ready', () => {
+    const r = resolveActivityRecipe({ readiness: detect(NEEDS_SKILL, NEEDS_SKILL), activity: 'plan-authoring', slot: 'review' });
+    assert.equal(r.recipe, 'solo');
+    assert.equal(r.source, 'default');
+  });
+
+  it('execute default is Solo even when codex is ready (Delegated is opt-in)', () => {
+    const r = resolveActivityRecipe({ readiness: detect(READY, READY), activity: 'plan-execution', slot: 'execute' });
+    assert.equal(r.recipe, 'solo');
+    assert.equal(r.source, 'default');
+  });
+});
+
+describe('resolveActivityRecipe — config-driven, graceful degradation', () => {
+  const config = { 'plan-authoring': { review: 'council' }, 'plan-execution': { execute: 'delegated', review: 'reviewed' } };
+
+  it('config review=council holds when both backends are ready', () => {
+    const r = resolveActivityRecipe({ config, readiness: detect(READY, READY), activity: 'plan-authoring', slot: 'review' });
+    assert.equal(r.recipe, 'council');
+    assert.equal(r.source, 'config');
+    assert.equal(r.degradedFrom, null);
+    assert.equal(r.overrideUnsatisfied, false);
+  });
+
+  it('config review=council degrades GRACEFULLY to Reviewed with one backend (not a loud override)', () => {
+    const r = resolveActivityRecipe({ config, readiness: detect(READY, NEEDS_SKILL), activity: 'plan-authoring', slot: 'review' });
+    assert.equal(r.recipe, 'reviewed');
+    assert.equal(r.degradedFrom, 'council');
+    assert.equal(r.overrideUnsatisfied, false);
+    assert.match(r.reason, /not installed|council/i);
+  });
+
+  it('config execute=delegated holds when codex is ready', () => {
+    const r = resolveActivityRecipe({ config, readiness: detect(READY, NEEDS_SKILL), activity: 'plan-execution', slot: 'execute' });
+    assert.equal(r.recipe, 'delegated');
+    assert.equal(r.degradedFrom, null);
+  });
+
+  it('config execute=delegated degrades to Solo when codex is not ready (agy cannot execute)', () => {
+    const r = resolveActivityRecipe({ config, readiness: detect(NEEDS_SKILL, READY), activity: 'plan-execution', slot: 'execute' });
+    assert.equal(r.recipe, 'solo');
+    assert.equal(r.degradedFrom, 'delegated');
+    assert.equal(r.overrideUnsatisfied, false);
+    assert.match(r.reason, /execute/i);
+  });
+});
+
+describe('resolveActivityRecipe — override precedence + LOUD degradation', () => {
+  it('an override beats the config entry', () => {
+    const config = { 'plan-authoring': { review: 'solo' } };
+    const r = resolveActivityRecipe({ config, readiness: detect(READY, READY), activity: 'plan-authoring', slot: 'review', override: 'council' });
+    assert.equal(r.recipe, 'council');
+    assert.equal(r.source, 'override');
+  });
+
+  it('an unsatisfiable override degrades LOUDLY (overrideUnsatisfied = true)', () => {
+    const r = resolveActivityRecipe({ readiness: detect(READY, NEEDS_SKILL), activity: 'plan-authoring', slot: 'review', override: 'council' });
+    assert.equal(r.recipe, 'reviewed');
+    assert.equal(r.degradedFrom, 'council');
+    assert.equal(r.overrideUnsatisfied, true, 'an explicit override that cannot be satisfied is flagged loud');
+  });
+
+  it('a satisfiable override is not flagged', () => {
+    const r = resolveActivityRecipe({ readiness: detect(READY, READY), activity: 'plan-authoring', slot: 'review', override: 'council' });
+    assert.equal(r.recipe, 'council');
+    assert.equal(r.overrideUnsatisfied, false);
+  });
+});
+
+describe('resolveActivityRecipe — defensive validity + purity', () => {
+  it('throws on an unknown activity', () => {
+    assert.throws(() => resolveActivityRecipe({ readiness: detect(READY, READY), activity: 'nope', slot: 'review' }), /unknown activity/);
+  });
+  it('throws on an unknown slot for the activity', () => {
+    assert.throws(
+      () => resolveActivityRecipe({ readiness: detect(READY, READY), activity: 'plan-authoring', slot: 'execute' }),
+      /unknown slot/,
+    );
+  });
+  it('throws on a recipe invalid for the slot (e.g. delegated in a review slot)', () => {
+    assert.throws(
+      () => resolveActivityRecipe({ readiness: detect(READY, READY), activity: 'plan-authoring', slot: 'review', override: 'delegated' }),
+      /invalid recipe/,
+    );
+  });
+  it('does not mutate the detection input', () => {
+    const det = detect(READY, READY);
+    const snapshot = JSON.parse(JSON.stringify(det));
+    resolveActivityRecipe({ readiness: det, activity: 'plan-execution', slot: 'review' });
+    assert.deepEqual(det, snapshot);
+  });
+});
+
 describe('recipes.mjs CLI — read-only, exit 0', () => {
   it('prints the recipes and exits 0', () => {
     const out = execFileSync(process.execPath, [SCRIPT], { encoding: 'utf8', env: { ...process.env, PATH: '' } });