@sabaiway/agent-workflow-kit 10.3.0 → 10.5.0

package/tools/review-rounds.mjs

@@ -0,0 +1,115 @@
+import { isRenderableLine } from './repo-lex.mjs';
+import { isShipVerdict, isRecognizedVerdict } from './core-evidence.mjs';
+
+export const SIGNALS = Object.freeze({
+  NO_RECEIPTS: 'no receipts for <path>',
+  INCOMPLETE: 'incomplete round — <backend> missing: dispatch it',
+  CONVERGED: 'converged',
+  CROSSOVER: 'crossover — stop: diff-review',
+  CAP_REACHED: 'cap reached — classify each surviving finding: fixable-bug / inherent-layer-residual / escalate',
+  FOLD_AND_RE_REVIEW: 'round 1 — fold and re-review',
+});
+
+const isNonNegativeInteger = (value) => Number.isInteger(value) && value >= 0;
+const isPlainLine = isRenderableLine;
+
+const invalidFieldOf = (receipt) => {
+  if (typeof receipt?.artifactPath !== 'string') return 'artifactPath';
+  if (typeof receipt.fingerprint !== 'string' || !/^[0-9a-f]{64}$/u.test(receipt.fingerprint)) return 'fingerprint';
+  if (!isPlainLine(receipt.backend) || receipt.backend.length === 0) return 'backend';
+  if (receipt.probe !== false) return 'probe';
+  if (!isPlainLine(receipt.verdict)) return 'verdict';
+  if (!isNonNegativeInteger(receipt.durationS)) return 'durationS';
+  if (!isNonNegativeInteger(receipt.blocking)) return 'blocking';
+  return null;
+};
+
+export const groupRounds = (receipts, obligation) => {
+  const expected = new Set(obligation.backends);
+  const rounds = [];
+  const invalid = [];
+  const unexpected = [];
+  for (const receipt of receipts) {
+    const invalidField = invalidFieldOf(receipt);
+    if (invalidField !== null) {
+      invalid.push({ field: invalidField, receipt });
+      continue;
+    }
+    if (!expected.has(receipt.backend)) {
+      unexpected.push(receipt);
+      continue;
+    }
+    const previous = rounds.at(-1);
+    const round = previous?.fingerprint === receipt.fingerprint
+      ? previous
+      : { fingerprint: receipt.fingerprint, byBackend: {} };
+    if (round !== previous) rounds.push(round);
+    round.byBackend[receipt.backend] = receipt;
+  }
+  return { rounds, invalid, unexpected };
+};
+
+export const isComplete = (round, obligation) => {
+  const present = obligation.backends.filter((backend) => round.byBackend[backend] !== undefined);
+  return obligation.perBackend
+    ? present.length === obligation.backends.length
+    : present.length >= obligation.minShip;
+};
+
+const isConverged = (round, obligation) => obligation.backends
+  .map((backend) => round.byBackend[backend])
+  .filter(Boolean)
+  .every((receipt) => receipt.blocking === 0 && isShipVerdict(receipt.verdict));
+
+const hasCrossover = (rounds, obligation) => {
+  const [earlier, latest] = rounds.slice(-2);
+  return obligation.backends.some((shipBackend) => {
+    const shipEarlier = earlier.byBackend[shipBackend];
+    const shipLatest = latest.byBackend[shipBackend];
+    if (!isShipVerdict(shipEarlier?.verdict) || !isShipVerdict(shipLatest?.verdict)) return false;
+    return obligation.backends.some((negativeBackend) => {
+      if (negativeBackend === shipBackend) return false;
+      const negativeEarlier = earlier.byBackend[negativeBackend]?.verdict;
+      const negativeLatest = latest.byBackend[negativeBackend]?.verdict;
+      return isRecognizedVerdict(negativeEarlier) && !isShipVerdict(negativeEarlier)
+        && isRecognizedVerdict(negativeLatest) && !isShipVerdict(negativeLatest);
+    });
+  });
+};
+
+export const signalFor = (rounds, obligation, artifactPath) => {
+  if (rounds.length === 0) return SIGNALS.NO_RECEIPTS.replace('<path>', () => artifactPath);
+  const latest = rounds.at(-1);
+  if (!isComplete(latest, obligation)) {
+    const missing = obligation.backends.find((backend) => latest.byBackend[backend] === undefined);
+    return SIGNALS.INCOMPLETE.replace('<backend>', () => missing);
+  }
+  if (isConverged(latest, obligation)) return SIGNALS.CONVERGED;
+  const complete = rounds.filter((round) => isComplete(round, obligation));
+  if (complete.length >= 2 && hasCrossover(complete, obligation)) return SIGNALS.CROSSOVER;
+  if (complete.length >= 2) return SIGNALS.CAP_REACHED;
+  return SIGNALS.FOLD_AND_RE_REVIEW;
+};
+
+export const renderRounds = ({ rounds, invalid = [], unexpected = [], obligation, artifactPath, pathless = 0, malformed = 0 }) => {
+  const lines = [];
+  rounds.reduce((total, round, index) => {
+    const receipts = obligation.backends.map((backend) => round.byBackend[backend]).filter(Boolean);
+    const duration = receipts.reduce((sum, receipt) => sum + receipt.durationS, 0);
+    const cells = obligation.backends.map((backend) => {
+      const receipt = round.byBackend[backend];
+      return receipt === undefined
+        ? `${backend}: missing`
+        : `${backend}: ${receipt.verdict} (${receipt.blocking} blocking, ${receipt.durationS}s)`;
+    });
+    const next = total + duration;
+    lines.push(`round ${index + 1} · ${cells.join(' · ')} · receipted duration: ${duration}s · cumulative: ${next}s`);
+    return next;
+  }, 0);
+  for (const entry of invalid) lines.push(`invalid: ${entry.field}`);
+  for (const receipt of unexpected) lines.push(`unexpected: ${receipt.backend}`);
+  lines.push(`pathless plan/diff receipts: ${pathless}`);
+  lines.push(`malformed receipt lines: ${malformed}`);
+  lines.push(`signal: ${signalFor(rounds, obligation, artifactPath)}`);
+  return lines.join('\n');
+};

package/tools/review-state.mjs

@@ -93,9 +93,9 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { detectBackends, READY } from './detect-backends.mjs';
+import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { resolveActivityRecipe, DISPLAY_ALIASES, requiredBackendsForConfiguredRecipe } from './recipes.mjs';
+import { resolveActivityRecipe, DISPLAY_ALIASES, requiredBackendsForConfiguredRecipe, composeReadiness } from './recipes.mjs';
 import { CONFIG_REL, fail, loadConfig } from './orchestration-config.mjs';
 import { resolveFlowStorePath, readFlowStore, deriveFlowOwner, readPlanFrontmatterId } from './flow-store.mjs';
 import { CHAIN_KIND, authoritativeFlowRecords } from './flow-record.mjs';
@@ -309,16 +309,16 @@ export const degradeRecordSet = ({ cwd, env = process.env, fingerprint }) => {
 // work-tree ROOT when one exists — the fingerprint is root-anchored, so a subdirectory invocation
 // must read the same config/plans or a dirty unreceipted tree could false-PASS as "no plan in
 // flight". Outside a git tree the cwd is the only anchor (and --check exits 0).
-export const buildState = ({ cwd, env = process.env, detect = detectBackends, lstat = lstatSync, readFile = readFileSync } = {}) => {
+export const buildState = ({ cwd, env = process.env, detect = detectBackends, surveyVehicle, lstat = lstatSync, readFile = readFileSync } = {}) => {
   const root = gitLine(['rev-parse', '--show-toplevel'], cwd) ?? cwd;
   const { config, source: configSource } = loadConfig(root);
-  let detection = [];
+  // A bridge-detector throw reaches the hook, never a catch that would also lose the surveyed
+  // executor vehicle: bridge readiness goes unknown (fail closed below), the carrier stays known.
   let detectionWarning = null;
-  try {
-    detection = detect();
-  } catch (err) {
-    detectionWarning = `backend detection failed (${(err && err.message) || err}) — readiness unknown.`;
-  }
+  const onDetectError = (err) => {
+    detectionWarning = `backend detection failed (${(err && err.message) || err}) — bridge readiness unknown.`;
+  };
+  const detection = composeReadiness(root, { detect, surveyVehicle, onDetectError });
   // The resolver stays for DISPLAY/diagnostics only; the OBLIGATIONS come from the configured
   // recipe (never the readiness-degraded effective one — no silent solo).
   const resolved = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity: ACTIVITY, slot: SLOT });
@@ -439,7 +439,6 @@ export const buildState = ({ cwd, env = process.env, detect = detectBackends, ls
     degradedExempt,
     maskedUntracked: countNeverCommittableUntracked(cwd, { lstat }),
     detectionWarning,
-    anyReviewerReady: detection.some((b) => b.readiness === READY),
     flowPresent,
     flowArmed,
     flowBrokenReason,
@@ -733,7 +732,7 @@ export const main = (argv, ctx = {}) => {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
     const unknown = argv.find((a) => !KNOWN_ARGS.has(a));
     if (unknown !== undefined) throw fail(2, `unknown argument: ${unknown}`);
-    const state = buildState({ cwd, env, detect, lstat: ctx.lstat, readFile: ctx.readFile });
+    const state = buildState({ cwd, env, detect, surveyVehicle: ctx.surveyVehicle, lstat: ctx.lstat, readFile: ctx.readFile });
     const check = decideCheck(state);
     // The mask advisory is NON-FAILING by contract: one notice line, never an exit-code arm.
     const advisory = maskAdvisoryLine(state);

package/tools/set-recipe-roster.mjs

@@ -0,0 +1,167 @@
+import {
+  addReviewer,
+  expandShorthand,
+  lensMembersOf,
+  obligationsOf,
+  parseSlotToken,
+  removeReviewer,
+} from './review-roster.mjs';
+import { isReadyMember, resolveRoster, skippedLine } from './review-roster-resolve.mjs';
+import { applySetOps, assertSlot, fail } from './orchestration-config.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+
+const REVIEWER_KINDS = new Set(['add-reviewer', 'remove-reviewer']);
+
+const parseQualified = (token, flag) => {
+  const equals = token.indexOf('=');
+  const qualified = equals < 0 ? token : token.slice(0, equals);
+  const dot = qualified.indexOf('.');
+  if (equals <= 0 || equals === token.length - 1 || dot <= 0 || dot === qualified.length - 1) {
+    throw fail(2, `--${flag} must be <activity>.review=<member> (got "${token}")`);
+  }
+  return {
+    activity: qualified.slice(0, dot),
+    slot: qualified.slice(dot + 1),
+    member: token.slice(equals + 1),
+  };
+};
+
+export const parseReviewerOp = (kind, token) => {
+  if (!REVIEWER_KINDS.has(kind)) throw fail(2, `unknown reviewer op: ${kind}`);
+  const parsed = parseQualified(token, kind);
+  if (assertSlot(parsed.activity, parsed.slot) !== 'review') {
+    throw fail(2, `--${kind} requires a review slot (got "${parsed.activity}.${parsed.slot}")`);
+  }
+  try {
+    parseSlotToken(parsed.member);
+  } catch (error) {
+    throw fail(2, error.message);
+  }
+  return { kind, ...parsed };
+};
+
+const membersOf = (value) => {
+  if (Array.isArray(value)) return value;
+  const expanded = expandShorthand(value);
+  return expanded.lossless ? expanded.members : null;
+};
+
+const sameMembers = (left, right) => {
+  const a = membersOf(left);
+  const b = membersOf(right);
+  return a !== null && b !== null && a.length === b.length && a.every((member, index) => member === b[index]);
+};
+
+const reviewedRefusal = (activity) => fail(
+  2,
+  `reviewed has no lossless roster expansion — run --set ${activity}.review=council first, or use --add-reviewer ${activity}.review=codex-review / --add-reviewer ${activity}.review=agy-review on a solo slot`,
+);
+
+const applyOne = (value, op) => {
+  if (membersOf(value) === null) throw reviewedRefusal(op.activity);
+  try {
+    return op.kind === 'add-reviewer'
+      ? addReviewer(value, op.member)
+      : removeReviewer(value, op.member);
+  } catch (error) {
+    throw fail(2, error.code === 'last-member' ? `${error.message} — run --set ${op.activity}.review=solo` : error.message);
+  }
+};
+
+export const applyReviewerOps = (current, ops, { defaults = {}, seedReadme = null } = {}) => {
+  const states = new Map();
+  for (const op of ops) {
+    const key = `${op.activity}.${op.slot}`;
+    const raw = current?.[op.activity]?.[op.slot] ?? null;
+    const state = states.get(key) ?? {
+      activity: op.activity,
+      slot: op.slot,
+      from: raw,
+      beforeValue: raw ?? defaults[key],
+      value: raw ?? defaults[key],
+      named: new Set(),
+    };
+    if (state.value === undefined) throw fail(2, `no computed default supplied for ${key}`);
+    state.value = applyOne(state.value, op);
+    if (op.kind === 'add-reviewer') state.named.add(parseSlotToken(op.member).stem);
+    states.set(key, state);
+  }
+  const rows = [...states.values()].map((state) => {
+    const changed = !sameMembers(state.beforeValue, state.value);
+    return {
+      ...state,
+      changed,
+      to: changed ? state.value : state.from,
+      afterValue: changed ? state.value : state.beforeValue,
+    };
+  });
+  const changes = rows.filter((row) => row.changed).map((row) => ({
+    kind: 'set', activity: row.activity, slot: row.slot, recipe: row.to,
+  }));
+  return {
+    config: changes.length ? applySetOps(current, changes, { seedReadme }) : current,
+    rows,
+  };
+};
+
+const gateLabel = (value) => {
+  const members = membersOf(value) ?? [];
+  if (members.length === 0) return 'solo []';
+  const obligation = obligationsOf(members);
+  return `${obligation.recipe} [${obligation.backends.join(', ')}]`;
+};
+
+const valueLabel = (value) => value == null
+  ? '(computed default)'
+  : Array.isArray(value) ? JSON.stringify(value) : value;
+
+const lensRemedy = (parsed, member, agentsApply) => {
+  if (parsed.kind !== 'lens' || member.state !== 'missing') return null;
+  if (parsed.template === null) return `HAND-APPLY: create .claude/agents/${parsed.stem}.md as a read-only vehicle`;
+  return agentsApply ? `to place it, run exactly: ${agentsApply}` : null;
+};
+
+export const persistedLensStems = (config) => new Set(lensMembersOf(config ?? {})
+  .map((member) => parseSlotToken(member))
+  .filter((parsed) => parsed.derived)
+  .map((parsed) => parsed.stem));
+
+export const renderRosterPreview = (row, { agentsApply, wrote = false, persistedLenses = new Set() } = {}) => {
+  const lines = [row.changed
+    ? `  ${row.activity}.${row.slot}: ${valueLabel(row.from)} → ${valueLabel(row.to)}`
+    : `  ${row.activity}.${row.slot}: already ${valueLabel(row.from)} (no change)`];
+  const persisted = new Set((membersOf(row.from) ?? []).map((member) => parseSlotToken(member).stem));
+  for (const member of row.roster) {
+    const parsed = parseSlotToken(member.member);
+    const apply = lensRemedy(parsed, member, agentsApply);
+    const remedy = [member.reason, apply].filter(Boolean).join('; ') || null;
+    const posture = member.posture == null ? '' : ` (${member.posture})`;
+    lines.push(`      ↳ ${member.member}: ${isReadyMember(member) ? member.state : skippedLine(member, remedy)}${posture}`);
+    if (apply && parsed.derived && !wrote && !persisted.has(parsed.stem) && !persistedLenses.has(parsed.stem)) {
+      lines.push('        after --write — the agents writer derives this lens from what docs/ai/orchestration.json names');
+    }
+    if (parsed.kind === 'lens' && parsed.template === null && row.named.has(parsed.stem)) {
+      lines.push(`        resolved as a lens with no bundled template — a hand-written vehicle; if you meant a bridge, the review cmds are ${expandShorthand('council').members.join(', ')}`);
+    }
+  }
+  lines.push(`      gate: ${gateLabel(row.beforeValue)} → ${gateLabel(row.afterValue)}`);
+  return lines.join('\n');
+};
+
+export const resolveReviewerRows = (rows, deps = {}) => rows.map((row) => {
+  const members = membersOf(row.afterValue);
+  return {
+    ...row,
+    roster: members.length === 0 ? [] : resolveRoster({ value: members, ...deps }),
+  };
+});
+
+export const rosterJsonRows = (rows, changed) => rows.map((row) => changed ? ({
+  activity: row.activity, slot: row.slot, from: row.from, to: row.to,
+  effective: row.effective, degradedFrom: row.degradedFrom ?? null, reason: row.reason ?? null,
+  roster: row.roster ?? null,
+}) : ({
+  activity: row.activity, slot: row.slot, recipe: row.from, roster: row.roster ?? null,
+}));
+
+refuseDirectRun(import.meta.url);

package/tools/set-recipe.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // set-recipe.mjs — the WRITER for docs/ai/orchestration.json. The division of labor (AD-025): the AGENT
-// turns plain language into explicit `--set <activity>.<slot>=<recipe>` / `--unset <activity>.<slot>`
+// turns plain language into explicit `--set <activity>.<slot>=<value>` / `--unset <activity>.<slot>`
 // ops; the KIT does the deterministic validate → merge → preview → write. The kit ships NO NL parser
 // (stays dependency-free + deterministic) and performs no `all`-magic — the agent expands "both review"
 // into explicit per-activity ops (asking if scope is unclear).
@@ -17,15 +17,28 @@
 // language when narrating. Exit codes: 0 success (an explicit recipe that gracefully degrades is still
 // 0); 2 usage (bad/duplicate op, --write with zero ops); 1 config error (malformed/unreadable config)
 // or a write STOP (no deployment / symlinked leaf). main(argv, ctx) → { code, stdout, stderr }; cwd /
-// env / home / detect / fs are injectable for host-independent tests.
+// env / home / detect / surveyVehicle / fs are injectable for host-independent tests.
+//
+// It writes every slot of every activity in the registry (carriers.mjs, via recipes.mjs) — the
+// carrier slots and the `routine.parallel` switch included — and resolves each preview against the
+// SAME readiness the recipes advisor composes: detected backends plus the executor-vehicle survey.
 //
 // Dependency-free, Node >= 22. No side effects on import (the isDirectRun idiom).
 
 import { readFileSync, lstatSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { resolveActivityRecipe, composeActiveRecipeLine } from './recipes.mjs';
+import { settingsSnapshot } from './bridge-settings-read.mjs';
+import { posturesByBackend } from './bridge-posture.mjs';
+import { surveyVehicle } from './cheap-agents-read.mjs';
+import { applyCheapAgentsCommand } from './cheap-agents.mjs';
+import {
+  ACTIVITIES,
+  SLOT_RECIPES,
+  EXECUTOR_APPLY,
+  composeReadiness,
+  resolveActivityRecipe,
+  composeActiveRecipeLine,
+} from './recipes.mjs';
 import { loadAutonomy, resolveAutonomy } from './autonomy-config.mjs';
 import {
   CONFIG_REL,
@@ -35,26 +48,40 @@ import {
   parseOp,
   applySetOps,
   serializeConfig,
+  refreshReadme,
   CANON_README,
 } from './orchestration-config.mjs';
 import { writeConfig as writeConfigFs } from './orchestration-write.mjs';
+import {
+  applyReviewerOps,
+  parseReviewerOp,
+  persistedLensStems,
+  renderRosterPreview,
+  resolveReviewerRows,
+  rosterJsonRows,
+} from './set-recipe-roster.mjs';
 
 // ── argument parsing (usage errors → exit 2) ────────────────────────────────────────
 
-// Parse argv → { ops, write, json }. `--set`/`--unset` take a fully-qualified token (parseOp validates
-// it). A duplicate op for the same activity.slot, a `--write` with zero ops, an unknown flag, or a bad
-// token → exit 2. `--set=<tok>` / `--unset=<tok>` inline forms are accepted too.
+// Parse argv → { ops, write, json }. Fixed ops stay unique per slot; reviewer list ops accumulate.
+// A `--write` with zero ops, an unknown flag, or a bad token → exit 2. Inline forms are accepted too.
 const parseArgs = (argv) => {
   const ops = [];
-  const seen = new Set();
+  const fixed = new Set();
+  const reviewer = new Set();
   let write = false;
   let json = false;
   const takeOp = (kind, tok) => {
-    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires <activity>.<slot>${kind === 'set' ? '=<recipe>' : ''}`);
-    const op = parseOp(kind, tok);
+    const reviewerKind = kind === 'add-reviewer' || kind === 'remove-reviewer';
+    const form = reviewerKind ? '<activity>.review=<member>' : `<activity>.<slot>${kind === 'set' ? '=<value>' : ''}`;
+    if (tok === undefined || tok.startsWith('--')) throw fail(2, `--${kind} requires ${form}`);
+    const op = reviewerKind ? parseReviewerOp(kind, tok) : parseOp(kind, tok);
     const key = `${op.activity}.${op.slot}`;
-    if (seen.has(key)) throw fail(2, `duplicate op for "${key}" — name each activity.slot at most once`);
-    seen.add(key);
+    if (fixed.has(key) || (!reviewerKind && reviewer.has(key))) {
+      throw fail(2, `duplicate op for "${key}" — --set/--unset name each activity.slot at most once and cannot mix with reviewer list ops`);
+    }
+    if (reviewerKind) reviewer.add(key);
+    else fixed.add(key);
     ops.push(op);
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -63,23 +90,39 @@ const parseArgs = (argv) => {
     else if (a === '--write') write = true;
     else if (a === '--set') { takeOp('set', argv[i + 1]); i += 1; }
     else if (a === '--unset') { takeOp('unset', argv[i + 1]); i += 1; }
+    else if (a === '--add-reviewer') { takeOp('add-reviewer', argv[i + 1]); i += 1; }
+    else if (a === '--remove-reviewer') { takeOp('remove-reviewer', argv[i + 1]); i += 1; }
     else if (a.startsWith('--set=')) takeOp('set', a.slice('--set='.length));
     else if (a.startsWith('--unset=')) takeOp('unset', a.slice('--unset='.length));
+    else if (a.startsWith('--add-reviewer=')) takeOp('add-reviewer', a.slice('--add-reviewer='.length));
+    else if (a.startsWith('--remove-reviewer=')) takeOp('remove-reviewer', a.slice('--remove-reviewer='.length));
     else if (a.startsWith('-')) throw fail(2, `unknown flag: ${a}`);
     else throw fail(2, `unexpected argument: ${a}`);
   }
-  if (write && ops.length === 0) throw fail(2, 'nothing to write — pass at least one --set/--unset (a bare --write is a no-op)');
+  if (write && ops.length === 0) throw fail(2, 'nothing to write — pass at least one --set/--unset/--add-reviewer/--remove-reviewer (a bare --write is a no-op)');
   return { ops, write, json };
 };
 
 // ── effective-recipe resolution per op (degradation honesty) ────────────────────────
 
+// The readiness EVERY resolution here runs against: the detected bridges plus the executor-vehicle
+// survey, composed by the one helper the recipes CLI uses. Detection is a SECONDARY input — a bridge
+// detector throw must NOT block the write (the config write is readiness-independent) and must not
+// cost the CARRIER either: the hook warns, the bridge half floors at not-ready, the vehicle survives.
+const composeReadinessOrWarn = (cwd, deps, warnings) =>
+  composeReadiness(cwd, {
+    ...deps,
+    onDetectError: (err) => warnings.push(
+      `backend detection failed (${(err && err.message) || err}) — treating every bridge as not ready; recipes needing a bridge degrade to solo (the executor vehicle is unaffected).`,
+    ),
+  });
+
 // A single op's before/after value + the effective recipe it resolves to here (vs live readiness).
 // `to` is null for an unset (falls to the computed default). degradedFrom/reason carry the honesty.
-const resolveOp = (op, current, after, detection) => {
+const resolveOp = (op, current, after, readiness) => {
   const from = current?.[op.activity]?.[op.slot] ?? null;
   const to = after?.[op.activity]?.[op.slot] ?? null;
-  const r = resolveActivityRecipe({ config: after ?? {}, readiness: detection, activity: op.activity, slot: op.slot });
+  const r = resolveActivityRecipe({ config: after ?? {}, readiness, activity: op.activity, slot: op.slot });
   return { activity: op.activity, slot: op.slot, from, to, effective: r.recipe, degradedFrom: r.degradedFrom, reason: r.reason };
 };
 
@@ -92,15 +135,21 @@ const effectiveLine = (e) =>
     ? `effective here: ${e.effective} (requested ${e.degradedFrom} → degraded: ${e.reason})`
     : `effective here: ${e.effective}`;
 
-const formatHuman = ({ changed, unchanged, warnings, willWrite, wrote, fileBody, activeLine }) => {
+const formatHuman = ({ changed, unchanged, warnings, willWrite, wrote, fileBody, activeLine, agentsApply, persistedLenses }) => {
   const lines = [];
   if (wrote) lines.push(`wrote ${CONFIG_REL}`);
   else if (changed.length) lines.push(`set-recipe — preview (nothing written; re-run with --write to apply)`);
   for (const e of changed) {
+    if (Array.isArray(e.roster)) {
+      lines.push(renderRosterPreview(e, { agentsApply, wrote, persistedLenses }));
+      continue;
+    }
     lines.push(`  ${e.activity}.${e.slot}: ${valueLabel(e.from)} → ${valueLabel(e.to)}`);
     lines.push(`      ↳ ${effectiveLine(e)}`);
   }
-  for (const e of unchanged) lines.push(`  ${e.activity}.${e.slot}: already ${valueLabel(e.from)} (no change)`);
+  for (const e of unchanged) lines.push(Array.isArray(e.roster)
+    ? renderRosterPreview(e, { agentsApply, wrote, persistedLenses })
+    : `  ${e.activity}.${e.slot}: already ${valueLabel(e.from)} (no change)`);
   for (const w of warnings) lines.push(`  ⚠ ${w}`);
   if (wrote && fileBody) lines.push('', `${CONFIG_REL} now reads:`, fileBody.replace(/\n$/, ''));
   // The post-write discovery echo (AD-038): after every successful write, paste the freshly composed
@@ -117,8 +166,8 @@ const formatHuman = ({ changed, unchanged, warnings, willWrite, wrote, fileBody,
 };
 
 const buildJson = ({ changed, unchanged, warnings, writtenPath, noop, activeLine }) => ({
-  changed: changed.map((e) => ({ activity: e.activity, slot: e.slot, from: e.from, to: e.to, effective: e.effective, degradedFrom: e.degradedFrom ?? null, reason: e.reason ?? null })),
-  unchanged: unchanged.map((e) => ({ activity: e.activity, slot: e.slot, recipe: e.from })),
+  changed: rosterJsonRows(changed, true),
+  unchanged: rosterJsonRows(unchanged, false),
   writtenPath: writtenPath ?? null,
   noop,
   warnings,
@@ -127,19 +176,44 @@ const buildJson = ({ changed, unchanged, warnings, writtenPath, noop, activeLine
   activeLine: activeLine ?? null,
 });
 
+// The writable surface, rendered FROM the registry — never re-typed as literals, so an activity, a
+// slot or an accepted value added to the table shows up in the help (and in the doc that quotes it).
+const ACTIVITY_LINES = Object.entries(ACTIVITIES)
+  .map(([activity, def]) => `  ${activity} → ${Object.keys(def.slots).join(', ')}`)
+  .join('\n');
+
+const VALUE_LINES = Object.entries(SLOT_RECIPES)
+  .map(([slotType, values]) => `  ${slotType} slots accept ${values.join(' | ')}`)
+  .join('\n');
+
+const QUALIFIED_SLOTS = Object.entries(ACTIVITIES)
+  .flatMap(([activity, def]) => Object.keys(def.slots).map((slot) => `${activity}.${slot}`))
+  .join(', ');
+
 const HELP = `set-recipe — write the per-project orchestration config (docs/ai/orchestration.json).
 
 Usage:
-  node set-recipe.mjs [--set <activity>.<slot>=<recipe>]... [--unset <activity>.<slot>]... [--write] [--json]
+  node set-recipe.mjs [--set <activity>.<slot>=<value>]... [--unset <activity>.<slot>]...
+                      [--add-reviewer <activity>.review=<member>]...
+                      [--remove-reviewer <activity>.review=<member>]... [--write] [--json]
 
-  --set    <activity>.<slot>=<recipe>   pin a recipe (fully-qualified; e.g. plan-authoring.review=council)
+  --set    <activity>.<slot>=<value>   pin a value (fully-qualified; e.g. plan-authoring.review=council)
   --unset  <activity>.<slot>            return a slot to its computed default
+  --add-reviewer <activity>.review=<member>     append a reviewer (same-slot ops accumulate in argv order)
+  --remove-reviewer <activity>.review=<member>  remove a reviewer (same-slot ops accumulate in argv order)
   --write                               apply the change (default: preview only — writes nothing)
   --json                                machine-readable output
   --help, -h                            this help
 
-Activities/slots: plan-authoring → review;  plan-execution → execute, review
-Recipes:          review accepts solo|reviewed|council;  execute accepts solo|delegated
+Activities and their slots:
+${ACTIVITY_LINES}
+
+Accepted values per slot type:
+${VALUE_LINES}
+
+A carrier slot set to subagent needs the executor vehicle placed in this project — ${EXECUTOR_APPLY};
+without it the slot resolves to solo with the reason stated. routine.parallel is a flag, not a
+recipe: it never degrades.
 
 Previews by default; --write applies via an atomic, symlink/TOCTOU-safe write behind a deployment gate.
 Config writer only: it NEVER runs a backend and NEVER commits. Hand-editing the file stays fully supported.
@@ -152,7 +226,7 @@ Exit codes: 0 success (an explicit recipe that gracefully degrades is still 0);
 
 export const main = (argv, ctx = {}) => {
   const cwd = ctx.cwd ?? process.cwd();
-  const detect = ctx.detect ?? detectBackends;
+  const readinessDeps = { detect: ctx.detect, surveyVehicle: ctx.surveyVehicle };
   const readFile = ctx.readFileSync ?? readFileSync;
   const lstat = ctx.lstatSync ?? lstatSync;
   const writeConfig = ctx.writeConfig ?? writeConfigFs;
@@ -170,23 +244,43 @@ export const main = (argv, ctx = {}) => {
         return { code: 0, stdout: JSON.stringify(buildJson({ changed: [], unchanged: [], warnings: [], writtenPath: null, noop: true }), null, 2), stderr: '' };
       }
       const shown = current == null ? `(no ${CONFIG_REL} yet — computed defaults apply)` : serializeConfig(current).replace(/\n$/, '');
-      const hint = `\nPass --set <activity>.<slot>=<recipe> (preview) then --write to apply. Activities/slots: plan-authoring.review, plan-execution.execute, plan-execution.review.`;
+      const hint = `\nPass --set <activity>.<slot>=<value> (preview) then --write to apply. Activities/slots: ${QUALIFIED_SLOTS}.`;
       return { code: 0, stdout: `${source === 'none' ? '' : `${CONFIG_REL}:\n`}${shown}${hint}`, stderr: '' };
     }
 
-    const after = applySetOps(current, ops, { seedReadme: CANON_README });
-
-    // Detection is a SECONDARY input — it only refines the EFFECTIVE recipe note. A throw must NOT block
-    // the write (the config write is readiness-independent): treat all backends as not-ready, warn, exit 0.
+    // The merged config, then the _README refresh: a note that normalize-matches a KNOWN PRIOR canonical
+    // is replaced by the current one on a touched write, while a customized note stays untouched.
+    const render = { agentsApply: applyCheapAgentsCommand(cwd), persistedLenses: persistedLensStems(current) };
     const warnings = [];
-    let detection = [];
-    try {
-      detection = detect();
-    } catch (err) {
-      warnings.push(`backend detection failed (${(err && err.message) || err}) — treating all backends as not ready; recipes needing a backend degrade to solo.`);
-    }
-
-    const resolved = ops.map((op) => resolveOp(op, current, after, detection));
+    const readiness = composeReadinessOrWarn(cwd, readinessDeps, warnings);
+    const reviewerOps = ops.filter((op) => op.kind === 'add-reviewer' || op.kind === 'remove-reviewer');
+    const fixedOps = ops.filter((op) => op.kind === 'set' || op.kind === 'unset');
+    const fixedAfter = fixedOps.length
+      ? applySetOps(current, fixedOps, { seedReadme: CANON_README })
+      : current;
+    const defaults = Object.fromEntries(reviewerOps.map((op) => [
+      `${op.activity}.${op.slot}`,
+      resolveActivityRecipe({ config: {}, readiness, activity: op.activity, slot: op.slot }).recipe,
+    ]));
+    const reviewerResult = applyReviewerOps(fixedAfter, reviewerOps, { defaults, seedReadme: CANON_README });
+    const after = refreshReadme(reviewerResult.config ?? {}).config;
+    const surveyLens = ctx.surveyLens ?? ((spec) => surveyVehicle(cwd, spec, ctx));
+    const hasRoster = reviewerOps.length > 0 || Object.values(after).some((activity) => Array.isArray(activity?.review));
+    const settings = hasRoster ? settingsSnapshot({
+      getenv: ctx.env, home: ctx.home, readFile: ctx.readFileSync, lstat: ctx.lstatSync,
+    }) : null;
+    const postures = ctx.postures ?? (hasRoster ? posturesByBackend({ settings }) : {});
+    const reviewerRows = resolveReviewerRows(reviewerResult.rows, { readiness, surveyLens, postures })
+      .map((row) => {
+        const resolved = resolveActivityRecipe({
+          config: after, readiness, activity: row.activity, slot: row.slot, surveyLens, postures,
+        });
+        return { ...row, effective: resolved.recipe, degradedFrom: null, reason: null };
+      });
+    const resolved = [
+      ...fixedOps.map((op) => resolveOp(op, current, after, readiness)),
+      ...reviewerRows,
+    ];
     const changed = resolved.filter((e) => e.from !== e.to);
     const unchanged = resolved.filter((e) => e.from === e.to);
     const noop = changed.length === 0;
@@ -194,7 +288,7 @@ export const main = (argv, ctx = {}) => {
     if (!write) {
       const stdout = json
         ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath: null, noop }), null, 2)
-        : formatHuman({ changed, unchanged, warnings, willWrite: !noop, wrote: false });
+        : formatHuman({ changed, unchanged, warnings, willWrite: !noop, wrote: false, ...render });
       return { code: 0, stdout, stderr: '' };
     }
 
@@ -202,7 +296,7 @@ export const main = (argv, ctx = {}) => {
     if (noop) {
       const stdout = json
         ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath: null, noop: true }), null, 2)
-        : formatHuman({ changed, unchanged, warnings, willWrite: false, wrote: false });
+        : formatHuman({ changed, unchanged, warnings, willWrite: false, wrote: false, ...render });
       return { code: 0, stdout, stderr: '' };
     }
 
@@ -220,10 +314,12 @@ export const main = (argv, ctx = {}) => {
         return { error: (err && err.message) || String(err) };
       }
     })();
-    const activeLine = composeActiveRecipeLine({ config: after, source: CONFIG_REL }, detection, autonomyFacts);
+    const activeLine = composeActiveRecipeLine(
+      { config: after, source: CONFIG_REL }, readiness, autonomyFacts, { surveyLens, postures },
+    );
     const stdout = json
       ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath, noop: false, activeLine }), null, 2)
-      : formatHuman({ changed, unchanged, warnings, wrote: true, fileBody, activeLine });
+      : formatHuman({ changed, unchanged, warnings, wrote: true, fileBody, activeLine, ...render });
     return { code: 0, stdout, stderr: '' };
   } catch (err) {
     return { code: err.exitCode ?? 1, stdout: '', stderr: `set-recipe: ${err.message}` };