@sabaiway/agent-workflow-kit 1.17.0 → 1.19.0

package/tools/procedures.mjs

@@ -17,48 +17,36 @@
 // installed engine is absent / invalid / too old to ship references/procedures.md).
 
 import { readFileSync, lstatSync } from 'node:fs';
-import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { detectBackends } from './detect-backends.mjs';
-import { ACTIVITIES, SLOT_RECIPES, resolveActivityRecipe } from './recipes.mjs';
+import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
 import { resolveEngineDir, readEngineFragment, PROCEDURES_FRAGMENT_REL } from './engine-source.mjs';
-
-// The hand-edited, per-project config (strict JSON). cwd-relative — the error prefix uses this rel path
-// so a user sees a path they can open, never an absolute temp/host path.
-export const CONFIG_REL = 'docs/ai/orchestration.json';
-
-// A tagged failure: a plain Error carrying the intended process exit code (2 usage / 1 config|engine).
-// Avoids a class (project rule) while letting main() map a throw to the right code in one place.
-const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+// The config schema/read core lives in orchestration-config.mjs (the single config contract). procedures
+// is READ-ONLY: it imports the reader + the SHARED slot/recipe validity, never the fs-writer
+// (orchestration-write.mjs) — so "the read-only advisor can never reach a writer" is STRUCTURALLY true
+// (an import-split test pins it). CONFIG_REL is RE-EXPORTED so existing importers (procedures.test.mjs,
+// historically) keep their import site working.
+import { CONFIG_REL, fail, loadConfig, assertSlotRecipe } from './orchestration-config.mjs';
+export { CONFIG_REL };
 
 // ── argument + override parsing (usage errors → exit 2) ─────────────────────────────
 
 // Parse the activity's --override <slot>=<recipe> tokens into a { slot: recipe } map, validating each
-// against the activity's slots + SLOT_RECIPES. Every malformed token is a USAGE error (exit 2): a bare
-// `<recipe>` (no slot), an unknown slot for the activity, an invalid recipe-for-slot, or a duplicate
-// slot. (An override naming a recipe whose backend merely is not `ready` is NOT a usage error — it
-// degrades loudly at resolution time, exit 0.)
-const parseOverrides = (tokens, activity, activityDef) => {
+// against the SHARED slot/recipe validity table (assertSlotRecipe — the SAME accept/reject the set-recipe
+// op parser uses, drift-guarded). Every malformed token is a USAGE error (exit 2): a bare `<recipe>` (no
+// slot), an unknown slot for the activity, an invalid recipe-for-slot, or a duplicate slot. (An override
+// naming a recipe whose backend merely is not `ready` is NOT a usage error — it degrades loudly at
+// resolution time, exit 0.) The `--override` grammar stays activity-SCOPED (the activity comes from the
+// CLI arg), unlike the fully-qualified `--set <activity>.<slot>=<recipe>` the writer takes.
+const parseOverrides = (tokens, activity) => {
   const overrides = {};
   for (const tok of tokens) {
     const eq = tok.indexOf('=');
     if (eq <= 0) throw fail(2, `--override must be <slot>=<recipe> (got "${tok}")`);
     const slot = tok.slice(0, eq);
     const recipe = tok.slice(eq + 1);
-    const slotType = activityDef.slots[slot];
-    if (!slotType) {
-      throw fail(
-        2,
-        `--override: unknown slot "${slot}" for activity "${activity}" (${activity} slots: ${Object.keys(activityDef.slots).join(', ')})`,
-      );
-    }
-    if (!(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
-      throw fail(
-        2,
-        `--override: invalid recipe "${recipe}" for ${slotType} slot of "${activity}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
-      );
-    }
+    assertSlotRecipe(activity, slot, recipe); // shared validity (unknown slot / invalid recipe → exit 2)
     if (slot in overrides) throw fail(2, `--override: duplicate override for slot "${slot}"`);
     overrides[slot] = recipe;
   }
@@ -94,80 +82,7 @@ const parseArgs = (argv) => {
   if (!activity) throw fail(2, `missing <activity> (known: ${KNOWN_ACTIVITIES()})`);
   const activityDef = ACTIVITIES[activity];
   if (!activityDef) throw fail(2, `unknown activity "${activity}" (known: ${KNOWN_ACTIVITIES()})`);
-  return { activity, overrides: parseOverrides(overrideTokens, activity, activityDef), json };
-};
-
-// ── config IO + validation (config errors → exit 1) ────────────────────────────────
-
-// Validate a parsed orchestration.json object against the §2.0 schema. Strict: an unknown top-level
-// activity, an unknown slot for an activity, or a recipe invalid-for-slot is an error. All slots are
-// optional. An optional "_README" string key is allowed + ignored (self-documentation). Never a silent
-// fallback — every rejection is a loud `path: reason`.
-const validateConfig = (config) => {
-  if (config === null || typeof config !== 'object' || Array.isArray(config)) {
-    throw fail(1, `${CONFIG_REL}: must be a JSON object of activity → { slot: recipe }`);
-  }
-  for (const [key, val] of Object.entries(config)) {
-    if (key === '_README') {
-      if (typeof val !== 'string') throw fail(1, `${CONFIG_REL}: "_README" must be a string`);
-      continue;
-    }
-    const activityDef = ACTIVITIES[key];
-    if (!activityDef) {
-      throw fail(1, `${CONFIG_REL}: unknown activity "${key}" (known: ${KNOWN_ACTIVITIES()})`);
-    }
-    if (val === null || typeof val !== 'object' || Array.isArray(val)) {
-      throw fail(1, `${CONFIG_REL}: activity "${key}" must be a JSON object of slot → recipe`);
-    }
-    for (const [slot, recipe] of Object.entries(val)) {
-      const slotType = activityDef.slots[slot];
-      if (!slotType) {
-        throw fail(
-          1,
-          `${CONFIG_REL}: unknown slot "${slot}" for activity "${key}" (${key} slots: ${Object.keys(activityDef.slots).join(', ')})`,
-        );
-      }
-      if (typeof recipe !== 'string' || !(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
-        throw fail(
-          1,
-          `${CONFIG_REL}: invalid recipe "${recipe}" for ${slotType} slot of "${key}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
-        );
-      }
-    }
-  }
-  return config;
-};
-
-// Load + validate the config from <cwd>/docs/ai/orchestration.json. Absent FILE → computed defaults
-// (NOT an error): { config: null, source: 'none' }. Malformed JSON / schema-invalid / unreadable →
-// loud `path: reason` (exit 1). The resolver receives the parsed+validated object (§2.2 IO/resolver split).
-// Exported so the read-only status settings-survey (family-registry.mjs) reuses ONE config reader —
-// same strict-JSON + loud-on-malformed contract, no second drifting implementation (Plan 3.1).
-export const loadConfig = (cwd, readFile = readFileSync, lstat = lstatSync) => {
-  const full = join(cwd, CONFIG_REL);
-  // Distinguish a TRULY-absent config (no entry at all → computed defaults) from a present-but-
-  // unreadable one (a directory, a DANGLING SYMLINK, a permission error → loud exit 1). lstat does NOT
-  // follow the link, so a dangling symlink reads as "present" here and its later read failure surfaces
-  // loudly — never silently treated as absent (no-silent-failures Hard Constraint).
-  try {
-    lstat(full);
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return { config: null, source: 'none' };
-    throw fail(1, `${CONFIG_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
-  }
-  let raw;
-  try {
-    raw = readFile(full, 'utf8');
-  } catch (err) {
-    throw fail(1, `${CONFIG_REL}: unreadable (${(err && err.code) || (err && err.message) || err})`);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw fail(1, `${CONFIG_REL}: malformed JSON (${err.message})`);
-  }
-  return { config: validateConfig(parsed), source: CONFIG_REL };
+  return { activity, overrides: parseOverrides(overrideTokens, activity), json };
 };
 
 // ── engine canon: live read + per-activity section extraction (engine errors → exit 1) ──

package/tools/renderers.mjs

@@ -0,0 +1,119 @@
+// renderers.mjs — the direct-CLI presenters (plain + ansi) for the four status blocks. Plan §4.2/§4.5.
+//
+// Input: the ViewModel (view-model.mjs, built from the no-leak envelope) + a resolved surface
+// (surface.mjs: { mode, width, color, ascii }). Output: a single string. `mode` selects plain vs ansi;
+// the JSON mode is handled by the caller (it prints the envelope, not a render). The renderers do
+// LAYOUT + GLYPHS only — phrasing + headline counts already live in the ViewModel.
+//
+// Pure, no side effects, Node >= 18.
+
+import { BLOCK_TITLES, SETTINGS_LABELS, glyphsFor, NO_DEPLOYMENT } from './presentation.mjs';
+
+const MEMBER_COL = 20;
+const VERSION_COL = 12;
+const READINESS_COL = 14;
+const STAMP_COL = 26;
+const SETTINGS_COL = 14;
+
+const SGR = Object.freeze({ bold: '\x1b[1m', reset: '\x1b[0m' });
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export const visibleLength = (s) => s.replace(ANSI_RE, '').length;
+
+const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
+// A styled span only when color is on — so color:false emits ZERO SGR (plain output, byte-clean).
+const heading = (text, color) => (color ? `${SGR.bold}${text}${SGR.reset}` : text);
+
+const renderMembers = (vm, { color, glyph }) => {
+  const lines = [heading(BLOCK_TITLES.members, color), ''];
+  for (const m of vm.members) {
+    const ver = m.version ? `v${m.version}` : '—';
+    const tail = m.statePhrase == null ? '' : m.statePhrase; // installed → the version IS the info
+    lines.push(`  ${pad(m.display, MEMBER_COL)}${pad(ver, VERSION_COL)}${tail}`.trimEnd());
+    for (const note of m.notes) lines.push(`      ${glyph.note} ${note}`); // verbatim caveats (INV-3)
+  }
+  // refresh.behind drives a HEADLINE COUNT only — the recovery command stays in the verbatim notes
+  // above (the direct CLI never dedupes, never re-prints it). Omitted when nothing is behind.
+  if (vm.headline.behind > 0) {
+    lines.push(`  ${vm.headline.behind} member(s) need a refresh (see the ${glyph.note} notes above).`);
+  }
+  return lines;
+};
+
+const renderBridges = (vm, { glyph, color }) => {
+  if (!vm.bridges) return [];
+  const lines = ['', heading(BLOCK_TITLES.bridges, color), ''];
+  for (const b of vm.bridges) {
+    const wrappers = b.wrappers.map((w) => `${w.cmd} ${glyph[w.state] ?? glyph.unknown}`).join(', ') || '—';
+    lines.push(`  ${pad(b.display, MEMBER_COL)}${pad(b.readiness, READINESS_COL)}wrappers: ${wrappers}`);
+  }
+  return lines;
+};
+
+const renderProject = (vm, { color }) => {
+  const p = vm.project;
+  if (!p) return [];
+  const lines = ['', heading(BLOCK_TITLES.project(p.dir), color), ''];
+  if (!p.deployed) {
+    lines.push(`  ${NO_DEPLOYMENT}`);
+    return lines;
+  }
+  for (const s of p.deployStamps) lines.push(`  ${pad(s.display, STAMP_COL)}${s.version ?? '—'}`);
+  lines.push(`  ${pad('docs/ai present', STAMP_COL)}${p.docsAi ? 'yes' : 'no'}`);
+  if (p.visibility) {
+    const v = p.visibility.error ? `error: ${p.visibility.error}` : p.visibility.phrase;
+    lines.push(`  ${pad('visibility', STAMP_COL)}${v}`);
+  }
+  return lines;
+};
+
+const renderSettings = (vm, { color, glyph }) => {
+  const s = vm.project?.settings;
+  if (!s) return [];
+  const lines = ['', heading(BLOCK_TITLES.settings, color)];
+  // recipes — the effective recipe per slot, or a loud error; a detector floor adds a sub-line.
+  if (s.recipes?.error) lines.push(`  ${pad(SETTINGS_LABELS.recipes, SETTINGS_COL)}error: ${s.recipes.error}`);
+  else if (s.recipes) {
+    const joined = s.recipes.pairs.map((p) => `${p.key}=${p.recipe}`).join(' · ') || '—';
+    lines.push(`  ${pad(SETTINGS_LABELS.recipes, SETTINGS_COL)}${joined}`);
+    if (s.recipes.detectError) {
+      lines.push(`  ${pad('', SETTINGS_COL)}${glyph.note} couldn't check backends (${s.recipes.detectError}); recipes floored at solo`);
+    }
+  }
+  // attribution — effective includeCoAuthoredBy; a real local override is called out.
+  if (s.attribution?.error) lines.push(`  ${pad(SETTINGS_LABELS.attribution, SETTINGS_COL)}error: ${s.attribution.error}`);
+  else if (s.attribution) {
+    const override = s.attribution.override ? ' (local override)' : '';
+    lines.push(`  ${pad(SETTINGS_LABELS.attribution, SETTINGS_COL)}includeCoAuthoredBy effective=${String(s.attribution.effective)}${override}`);
+  }
+  // velocity — effective defaultMode + per-source allow counts.
+  if (s.velocity?.error) lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}error: ${s.velocity.error}`);
+  else if (s.velocity) {
+    lines.push(`  ${pad(SETTINGS_LABELS.velocity, SETTINGS_COL)}defaultMode=${String(s.velocity.defaultMode)} · allow project/local=${s.velocity.allow.project}/${s.velocity.allow.local}`);
+  }
+  return lines;
+};
+
+// Pad each NON-empty line UP to the surface width (by VISIBLE length, so SGR codes don't count); empty
+// separator lines stay empty. `width` is a MIN target for a consistent block, NOT a hard max: a long
+// content line — a verbatim caveat `↳`, a long recipe row — is left INTACT and is NEVER truncated,
+// because truncating could hide part of a recovery command (a no-silent-failure violation). The
+// terminal soft-wraps an over-width line; data integrity wins over a perfectly rectangular block.
+const padLineTo = (line, width) => {
+  if (line === '') return '';
+  const vis = visibleLength(line);
+  return vis < width ? line + ' '.repeat(width - vis) : line;
+};
+
+export const render = (vm, surface = {}) => {
+  const glyph = glyphsFor(Boolean(surface.ascii));
+  const color = surface.mode === 'ansi' && Boolean(surface.color); // color applies in ansi mode only
+  const ctx = { color, glyph };
+  const lines = [
+    ...renderMembers(vm, ctx),
+    ...renderBridges(vm, ctx),
+    ...renderProject(vm, ctx),
+    ...renderSettings(vm, ctx),
+  ];
+  if (surface.mode === 'ansi') return lines.map((l) => padLineTo(l, surface.width ?? 80)).join('\n');
+  return lines.join('\n');
+};

package/tools/set-recipe.mjs

@@ -0,0 +1,217 @@
+#!/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>`
+// 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).
+//
+// Posture: PREVIEW BY DEFAULT (dry-run); `--write` applies. It NEVER commits and NEVER runs a backend.
+// It previews current→proposed for the CHANGED slots only, resolves the effective recipe vs LIVE backend
+// readiness (degradation honesty on BOTH the preview and the --write path), and writes only via the
+// hardened writeConfig (deployment gate; exclusive-create tmp+rename; symlink/TOCTOU-safe; last-writer-
+// wins). A no-op set never writes and never spuriously seeds the _README. `--unset` returns a slot to its
+// computed default, so reverting needs no hand-edit either. Hand-edit stays first-class — this is an
+// OFFERED convenience, never a lock.
+//
+// Output is ENGLISH/structured (repo-artifact Hard Constraint); the agent localizes to the user's
+// 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.
+//
+// Dependency-free, Node >= 18. No side effects on import (the isDirectRun idiom).
+
+import { readFileSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { detectBackends } from './detect-backends.mjs';
+import { resolveActivityRecipe } from './recipes.mjs';
+import {
+  CONFIG_REL,
+  fail,
+  loadConfig,
+  validateConfig,
+  parseOp,
+  applySetOps,
+  serializeConfig,
+  CANON_README,
+} from './orchestration-config.mjs';
+import { writeConfig as writeConfigFs } from './orchestration-write.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.
+const parseArgs = (argv) => {
+  const ops = [];
+  const seen = 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 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);
+    ops.push(op);
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--json') json = true;
+    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.startsWith('--set=')) takeOp('set', a.slice('--set='.length));
+    else if (a.startsWith('--unset=')) takeOp('unset', a.slice('--unset='.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)');
+  return { ops, write, json };
+};
+
+// ── effective-recipe resolution per op (degradation honesty) ────────────────────────
+
+// 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 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 });
+  return { activity: op.activity, slot: op.slot, from, to, effective: r.recipe, degradedFrom: r.degradedFrom, reason: r.reason };
+};
+
+// ── rendering (ENGLISH; the agent localizes) ────────────────────────────────────────
+
+const valueLabel = (v) => (v == null ? '(computed default)' : v);
+
+const effectiveLine = (e) =>
+  e.degradedFrom
+    ? `effective here: ${e.effective} (requested ${e.degradedFrom} → degraded: ${e.reason})`
+    : `effective here: ${e.effective}`;
+
+const formatHuman = ({ changed, unchanged, warnings, willWrite, wrote, fileBody }) => {
+  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) {
+    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 w of warnings) lines.push(`  ⚠ ${w}`);
+  if (wrote && fileBody) lines.push('', `${CONFIG_REL} now reads:`, fileBody.replace(/\n$/, ''));
+  if (!wrote) {
+    if (!changed.length) lines.push('  no changes — nothing to write.');
+    else if (willWrite) lines.push('', `would write ${CONFIG_REL} — re-run with --write to apply.`);
+  }
+  return lines.join('\n');
+};
+
+const buildJson = ({ changed, unchanged, warnings, writtenPath, noop }) => ({
+  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 })),
+  writtenPath: writtenPath ?? null,
+  noop,
+  warnings,
+});
+
+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]
+
+  --set    <activity>.<slot>=<recipe>   pin a recipe (fully-qualified; e.g. plan-authoring.review=council)
+  --unset  <activity>.<slot>            return a slot to its computed default
+  --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
+
+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.
+
+Exit codes: 0 success (an explicit recipe that gracefully degrades is still 0);
+            2 usage (bad/duplicate op, or --write with no ops);
+            1 config error (malformed/unreadable config) or a write STOP (no deployment / symlinked leaf).`;
+
+// ── main ────────────────────────────────────────────────────────────────────────────
+
+export const main = (argv, ctx = {}) => {
+  const cwd = ctx.cwd ?? process.cwd();
+  const detect = ctx.detect ?? detectBackends;
+  const readFile = ctx.readFileSync ?? readFileSync;
+  const lstat = ctx.lstatSync ?? lstatSync;
+  const writeConfig = ctx.writeConfig ?? writeConfigFs;
+  try {
+    if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
+    const { ops, write, json } = parseArgs(argv);
+
+    // Load the current config first (loadConfig throws fail(1) loud on malformed/unreadable — a write
+    // never clobbers an unparseable file; the message points the agent at the parse error to help fix it).
+    const { config: current, source } = loadConfig(cwd, readFile, lstat);
+
+    // No ops + no --write → show the current config + a hint (read-only; nothing changes).
+    if (ops.length === 0) {
+      if (json) {
+        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.`;
+      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.
+    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 changed = resolved.filter((e) => e.from !== e.to);
+    const unchanged = resolved.filter((e) => e.from === e.to);
+    const noop = changed.length === 0;
+
+    if (!write) {
+      const stdout = json
+        ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath: null, noop }), null, 2)
+        : formatHuman({ changed, unchanged, warnings, willWrite: !noop, wrote: false });
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    // --write. A no-op never writes (idempotent; never re-seeds the _README).
+    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 });
+      return { code: 0, stdout, stderr: '' };
+    }
+
+    validateConfig(after); // defensive re-validate immediately before the write
+    const { writtenPath } = writeConfig(cwd, after, ctx);
+    const fileBody = serializeConfig(after);
+    const stdout = json
+      ? JSON.stringify(buildJson({ changed, unchanged, warnings, writtenPath, noop: false }), null, 2)
+      : formatHuman({ changed, unchanged, warnings, wrote: true, fileBody });
+    return { code: 0, stdout, stderr: '' };
+  } catch (err) {
+    return { code: err.exitCode ?? 1, stdout: '', stderr: `set-recipe: ${err.message}` };
+  }
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  const r = main(process.argv.slice(2));
+  if (r.stdout) console.log(r.stdout);
+  if (r.stderr) console.error(r.stderr);
+  process.exit(r.code);
+}

package/tools/setup-backends.mjs

@@ -24,9 +24,9 @@ import {
 import { join, resolve, relative, dirname, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import os from 'node:os';
-import { KNOWN_BACKENDS, detectBackend, resolveDir, guideFor } from './detect-backends.mjs';
+import { KNOWN_BACKENDS, detectBackend, detectBackends, resolveDir, guideFor, READY } from './detect-backends.mjs';
 import { copyTreeRefresh, linkManaged } from './fs-safe.mjs';
-import { validateManifest, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
+import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // bridges/ ships beside tools/ in both the repo and the installed kit, so this resolves in both.
@@ -315,9 +315,18 @@ export const planFor = (backend, deps = {}) => {
   }
 
   let links;
+  let version = null;
+  let priorVersion = null;
   try {
     const fs = fsDeps(deps);
-    const derived = deriveLinks(readBundledManifest(place.bundleDir, deps), skillDir);
+    const readVersion = deps.readVersion ?? readAuthoritativeVersion;
+    const bundledManifest = readBundledManifest(place.bundleDir, deps);
+    // The bundled bridge version (what setup will place/refresh) + the prior installed version (only on
+    // a refresh — a place has no prior). readAuthoritativeVersion is the SAME source `status` reads, so
+    // setup never invents a second version reader. A place / absent-prior shows no arrow (never "vnull").
+    version = typeof bundledManifest.version === 'string' ? bundledManifest.version : null;
+    priorVersion = place.action === 'refresh' ? readVersion(skillDir).version ?? null : null;
+    const derived = deriveLinks(bundledManifest, skillDir);
     // Preflight the BUNDLE sources (what we will copy → link). After place, the skill source IS the
     // bundle source, so checking it here makes a dry-run faithfully predict linkWrappers instead of
     // reporting "ok" and then throwing at apply time.
@@ -347,7 +356,7 @@ export const planFor = (backend, deps = {}) => {
   const onPath = bindirOnPath(bindir, deps.getenv ?? process.env, platform);
   const bindirHint = onPath ? null : `add ${bindir} to PATH to use the wrappers: export PATH="${bindir}:$PATH"  (persist in ~/.bashrc / ~/.zshrc)`;
 
-  return { name: entry.name, skillDir, bindir, platform, place, links, guides, bindirHint, outcome: 'ok' };
+  return { name: entry.name, skillDir, bindir, platform, place, links, guides, bindirHint, outcome: 'ok', version, priorVersion };
 };
 
 // Perform an `ok` plan's deterministic steps. Re-derives + re-checks inside the primitives (no trust
@@ -361,6 +370,16 @@ const applyBackend = (plan, deps) => {
 
 // ── formatting ─────────────────────────────────────────────────────────────────
 
+// The bridge version label for the skill line: place / absent-prior → "(vX)" (no arrow, never
+// "vnull → vX"); refresh with a DIFFERENT prior → "(vOld → vNew)"; refresh equal / null prior → "(vX)".
+const versionLabel = (plan) => {
+  if (!plan.version) return '';
+  if (plan.place?.action === 'refresh' && plan.priorVersion && plan.priorVersion !== plan.version) {
+    return ` (v${plan.priorVersion} → v${plan.version})`;
+  }
+  return ` (v${plan.version})`;
+};
+
 const formatBackend = (plan, applied) => {
   const lines = [`  ${plan.name} → ${plan.outcome}`];
   if (plan.outcome === 'unsupported') {
@@ -372,7 +391,7 @@ const formatBackend = (plan, applied) => {
     return lines.join('\n');
   }
   const placeVerb = applied ? { place: 'placed', refresh: 'refreshed' } : { place: 'will place', refresh: 'will refresh' };
-  lines.push(`      • skill: ${placeVerb[plan.place.action]} → ${plan.skillDir}`);
+  lines.push(`      • skill: ${placeVerb[plan.place.action]}${versionLabel(plan)} → ${plan.skillDir}`);
   for (const l of plan.links) {
     const verb = l.dstState === 'ours' ? 'already linked' : applied ? 'linked' : 'will link';
     lines.push(`      • wrapper ${l.cmd}: ${verb} → ${l.dst}`);
@@ -382,6 +401,41 @@ const formatBackend = (plan, applied) => {
   return lines.join('\n');
 };
 
+// ── close-the-loop: surface versions + a proactive recipe offer ───────────────────
+
+// The closing pointer: setup surfaces only the bridge it touched; the full family + deployment version
+// view lives in the read-only status mode.
+const STATUS_POINTER = 'Full family + deployment versions: /agent-workflow-kit status';
+
+// Count the review-capable backends that are READY right now (both bridges provide review, so a READY
+// count ≥1 unlocks Reviewed, ≥2 unlocks Council). Uses the MULTI-backend detector. A detection failure
+// → null: we can't tell, so we make NO offer (never a false one). Read-only.
+const reviewReadyCount = (deps) => {
+  const detectAll = deps.detectAll ?? detectBackends;
+  try {
+    return detectAll(deps).filter((d) => d.readiness === READY).length;
+  } catch {
+    return null;
+  }
+};
+
+// After a successful setup, if a review backend NEWLY became ready (the pre-apply readiness in planFor
+// is stale — re-detect AFTER apply), offer to set the review recipe — for BOTH planning AND execution
+// review (planning review is a core goal; never offer only plan-execution). Council when ≥2 are ready,
+// else Reviewed (with a one-reviewer alternative noted). English; the agent localizes when it narrates.
+export const proactiveReviewOffer = (before, after) => {
+  if (before == null || after == null || after <= before) return null;
+  const depth = after >= 2 ? 'council' : 'reviewed';
+  const lines = [
+    '',
+    `A review backend is now ready (${after} ready). To have your plans reviewed, set the review recipe (preview first; I'll write it for you — or edit docs/ai/orchestration.json yourself):`,
+    `  /agent-workflow-kit set-recipe --set plan-authoring.review=${depth}`,
+    `  /agent-workflow-kit set-recipe --set plan-execution.review=${depth}`,
+  ];
+  if (depth === 'council') lines.push('  (or =reviewed for a single reviewer)');
+  return lines.join('\n');
+};
+
 // ── CLI ─────────────────────────────────────────────────────────────────────────
 
 const USAGE = `usage: setup-backends [<backend>] [--bindir <path>] [--dry-run] [--help]
@@ -448,12 +502,16 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
 
   const runDeps = { ...deps, bindir: args.bindir ?? deps.bindir };
   log(args.dryRun ? 'agent-workflow backend setup — DRY RUN (no changes)' : 'agent-workflow backend setup (link-only)');
+  // Snapshot review readiness BEFORE applying, so we can offer the recipe only on a true readiness flip.
+  const reviewBefore = args.dryRun ? null : reviewReadyCount(runDeps);
   let worst = 0;
+  let appliedOk = false;
   for (const name of targets) {
     let plan = planFor(name, runDeps);
     if (!args.dryRun && plan.outcome === 'ok') {
       try {
         applyBackend(plan, runDeps);
+        appliedOk = true;
       } catch (err) {
         plan = { ...plan, outcome: err.code === SETUP_STOP ? 'stop' : 'error', reason: err.message };
       }
@@ -461,6 +519,14 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     log(formatBackend(plan, !args.dryRun));
     if (plan.outcome === 'stop' || plan.outcome === 'error') worst = 1;
   }
+  log('');
+  log(STATUS_POINTER);
+  // Re-detect AFTER apply (pre-apply readiness is stale): a review backend that just became ready earns
+  // a proactive set-recipe offer. Only after a real apply (never on a dry-run or a no-op run).
+  if (!args.dryRun && appliedOk) {
+    const offer = proactiveReviewOffer(reviewBefore, reviewReadyCount(runDeps));
+    if (offer) log(offer);
+  }
   return worst;
 };