@sabaiway/agent-workflow-kit 10.4.0 → 10.5.0

package/tools/bridge-posture.mjs

@@ -0,0 +1,48 @@
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
+import { KNOWN_BACKENDS } from './detect-backends.mjs';
+import { receiptIdOfCmd } from './carriers.mjs';
+
+const oneLine = (value) => String(value).replace(/[\s]+/gu, ' ').trim();
+
+const validPosture = (posture) => posture !== null && typeof posture === 'object' && !Array.isArray(posture)
+  && typeof posture.model === 'string' && posture.model.length > 0
+  && (!Object.hasOwn(posture, 'effort') || (typeof posture.effort === 'string' && posture.effort.length > 0))
+  && (!Object.hasOwn(posture, 'tier') || posture.tier === null || (typeof posture.tier === 'string' && posture.tier.length > 0))
+  && Object.keys(posture).every((key) => ['model', 'effort', 'tier'].includes(key));
+
+const postureString = (posture, backend, settings) => {
+  const parts = [`model=${oneLine(posture.model)}`];
+  if (Object.hasOwn(posture, 'effort')) parts.push(`effort=${oneLine(posture.effort)}`);
+  if (Object.hasOwn(posture, 'tier')) {
+    const knob = (settings?.active ?? []).find((row) => row.key === 'CODEX_SERVICE_TIER' && row.bridge === backend.name);
+    parts.push(knob ? `tier=${oneLine(knob.value)} (bridge-settings)` : `tier=${posture.tier ?? 'standard'}`);
+  }
+  return parts.join(' ');
+};
+
+export const posturesByBackend = (ctx = {}) => {
+  const bundleRoot = ctx.bundleRoot ?? DEFAULT_BUNDLE_ROOT;
+  const read = ctx.readFile ?? readFileSync;
+  return Object.fromEntries(KNOWN_BACKENDS.flatMap((backend) => {
+    const cmd = backend.roleCmds?.review;
+    const receiptId = receiptIdOfCmd(cmd);
+    if (receiptId === null) return [];
+    const path = join(bundleRoot, backend.name, 'capability.json');
+    try {
+      const manifest = JSON.parse(String(read(path, 'utf8')));
+      if (!Object.hasOwn(manifest, 'posture')) {
+        return [[receiptId, { state: 'none', posture: null, path }]];
+      }
+      if (!validPosture(manifest.posture)) throw new Error('invalid posture block');
+      return [[receiptId, {
+        state: 'valid',
+        posture: postureString(manifest.posture, backend, ctx.settings ?? { active: [] }),
+        path,
+      }]];
+    } catch (error) {
+      return [[receiptId, { state: 'unreadable', posture: null, path, reason: oneLine(error?.message ?? error) }]];
+    }
+  }));
+};

package/tools/carriers.mjs

@@ -12,7 +12,7 @@ import { refuseDirectRun } from './direct-run.mjs';
 // `policy` marks an activity that is a SESSION with an autonomy level of its own; a routine chore
 // runs inside such a session and carries none.
 export const ACTIVITIES = {
-  'plan-authoring': { slots: { author: 'carrier', review: 'review' }, policy: true },
+  'plan-authoring': { slots: { author: 'carrier', fold: 'carrier', review: 'review' }, policy: true },
   'plan-execution': { slots: { execute: 'execute', review: 'review' }, policy: true },
   routine: { slots: { carrier: 'carrier', parallel: 'switch' }, policy: false },
 };
@@ -31,6 +31,18 @@ export const SLOT_RECIPES = {
 export const SWITCH_SLOT = 'switch';
 export const SWITCH_DEFAULT = 'on';
 
+const CODEX = 'codex-cli-bridge';
+const AGY = 'antigravity-cli-bridge';
+
+export const DISPLAY_ALIASES = Object.freeze({ [CODEX]: 'codex', [AGY]: 'agy' });
+export const BACKEND_PRIORITY = Object.freeze([CODEX, AGY]);
+export const REVIEW_CMD_ALIASES = Object.freeze({
+  'codex-review': Object.freeze({ backend: CODEX, receiptId: 'codex' }),
+  'agy-review': Object.freeze({ backend: AGY, receiptId: 'agy' }),
+});
+export const receiptIdOfCmd = (cmd) => REVIEW_CMD_ALIASES[cmd]?.receiptId ?? null;
+export const LENS_VERDICTS = Object.freeze(['ship', 'ship with nits', 'revise', 'rethink']);
+
 export const isSwitchSlot = (slotType) => slotType === SWITCH_SLOT;
 
 export const CARRY_ROLE = 'carry';
@@ -90,12 +102,12 @@ export const vehicleDegradeReason = (survey, applyHint = EXECUTOR_APPLY) => {
 // Pure constants. `procedures.mjs` prints them for a slot resolved to `subagent`; the wording is a
 // red line, so a render composes these strings and never re-words one.
 
-// The slice noun is per ACTIVITY — what a bounded slice IS differs for execution, authoring and a
-// routine chore, while the four dispatch lines below are shared by all three.
-export const SLICE_BY_ACTIVITY = {
-  'plan-authoring': 'a slice is a brief naming the goal, the governing spec(s) and the ledger constraints; the subagent drafts the plan or the contract from it, and the orchestrator reviews the draft as its own',
-  'plan-execution': 'a slice is a set of file-disjoint ledger rows; wording is copied verbatim where wording is a red line',
-  routine: "a slice is a bounded mechanical task; a read-only one (a sweep, gate triage) rides its placed read-only vehicle, or is carried solo with a stated reason when that vehicle is absent; a write-capable one (a regeneration, a fixture build) rides the executor; the changelog stays the orchestrator's",
+// The slice noun is per SLOT — authoring and folding share an activity but carry different work.
+export const SLICE_BY_SLOT = {
+  'plan-authoring.author': 'a slice is a brief naming the goal, the governing spec(s) and the ledger constraints; the subagent drafts the plan or the contract from it, and the orchestrator reviews the draft as its own',
+  'plan-authoring.fold': "a slice is the round's findings with their dispositions; the subagent edits the plan or the contract in place and returns; the orchestrator runs the self-consistency read itself",
+  'plan-execution.execute': 'a slice is a set of file-disjoint ledger rows; wording is copied verbatim where wording is a red line',
+  'routine.carrier': "a slice is a bounded mechanical task; a read-only one (a sweep, gate triage) rides its placed read-only vehicle, or is carried solo with a stated reason when that vehicle is absent; a write-capable one (a regeneration, a fixture build) rides the executor; the changelog stays the orchestrator's",
 };
 
 export const VEHICLE_STATE_TOKEN = '<state>';
@@ -120,10 +132,10 @@ export const SUBAGENT_SLOT_TYPES = Object.entries(SLOT_RECIPES)
   .map(([slotType]) => slotType);
 
 // dispatchForm({ activity, slot, state }) → the lines a `subagent`-resolved slot renders: the
-// activity's slice sentence, then the four shared lines with the surveyed vehicle state filled in.
+// slot's slice sentence, then the four shared lines with the surveyed vehicle state filled in.
 // A slot whose type cannot hold `subagent` (a review slot) and an unknown activity render nothing.
 export const dispatchForm = ({ activity, slot, state } = {}) => {
-  const slice = SLICE_BY_ACTIVITY[activity];
+  const slice = SLICE_BY_SLOT[`${activity}.${slot}`];
   const slotType = ACTIVITIES[activity]?.slots?.[slot];
   if (!slice || !SUBAGENT_SLOT_TYPES.includes(slotType)) return [];
   return [slice, ...DISPATCH_LINES.map((line) => line.replace(VEHICLE_STATE_TOKEN, state ?? MISSING))];

package/tools/cheap-agents-read.mjs

@@ -7,6 +7,7 @@ import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { refuseDirectRun } from './direct-run.mjs';
+import { deriveLensTemplate } from './review-roster-resolve.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -23,6 +24,7 @@ const EXIT_PRECONDITION = 1;
 export const CHEAP_AGENTS_STAMP = 'CHEAP_AGENTS_STAMP';
 export const CHEAP_AGENTS_SYMLINK = 'CHEAP_AGENTS_SYMLINK';
 export const CHEAP_AGENTS_BUNDLE = 'CHEAP_AGENTS_BUNDLE';
+export const CHEAP_AGENTS_CONFIG = 'CHEAP_AGENTS_CONFIG';
 
 export const makeCheapAgentsError = (code, message) =>
   Object.assign(new Error(`${ERROR_PREFIX} ${message}`), { name: 'CheapAgentsError', code, exitCode: EXIT_PRECONDITION });
@@ -107,13 +109,23 @@ export const planPlacement = (templates, projectDir, deps = {}) => {
 
 export const EXECUTOR_VEHICLE = 'executor.md';
 export const EXECUTOR_VEHICLE_REL = `${AGENTS_DIR}/${EXECUTOR_VEHICLE}`;
+export const EXECUTOR_VEHICLE_SPEC = Object.freeze({
+  stem: 'executor', template: 'executor', model: null, effort: null, tools: 'full', derived: false,
+});
+const READ_ONLY_TOOLS = new Set(['Read', 'Grep', 'Glob']);
 
 // The YAML subset a vehicle's frontmatter is read with: a bare scalar, a single- or double-quoted
 // scalar, or a flow sequence; an unquoted ` #comment` and surrounding whitespace are dropped first.
-const cleanValue = (raw) => {
-  const noComment = String(raw ?? '').replace(/^((?:[^"'#]|"[^"]*"|'[^']*')*?)\s+#.*$/u, '$1').trim();
-  return noComment.replace(/^(["'])(.*)\1$/u, '$2').replace(/^\[(.*)\]$/u, '$1').trim();
+const stripComment = (raw) => String(raw ?? '').replace(/^((?:[^"'#]|"[^"]*"|'[^']*')*?)\s+#.*$/u, '$1').trim();
+const cleanValue = (raw) => stripComment(raw).replace(/^(["'])(.*)\1$/u, '$2').replace(/^\[(.*)\]$/u, '$1').trim();
+
+const scalarValue = (raw) => {
+  const value = stripComment(raw);
+  const quoted = value.match(/^(["'])(.*)\1$/u);
+  if (quoted) return quoted[2].trim();
+  return /^[[{|>]|["']/u.test(value) ? null : value;
 };
+const scalarOf = (frontmatter, key) => scalarValue(frontmatter.match(new RegExp(`^${key}:(.*)$`, 'mu'))?.[1]);
 
 // The block-sequence items under the `tools:` key: `- item` lines indented deeper than the key,
 // with blank and comment lines allowed between them; the first other line ends the list.
@@ -133,40 +145,90 @@ const blockItems = (frontmatter) => {
   return items;
 };
 
-const executorFrontmatterRefusal = (content) => {
-  const frontmatter = String(content).replace(/\r\n/gu, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/u)?.[1] ?? '';
+const frontmatterOf = (content) => String(content).replace(/\r\n/gu, '\n').match(/^---\n([\s\S]*?)\n---(?:\n|$)/u)?.[1] ?? '';
+
+const listedTools = (frontmatter) => {
+  const inline = cleanValue(frontmatter.match(/^tools:(.*)$/mu)?.[1]);
+  return (inline || blockItems(frontmatter).join(', ')).split(',').map((tool) => cleanValue(tool)).filter(Boolean);
+};
+
+const executorFrontmatterRefusal = (frontmatter, stem) => {
   for (const key of ['name', 'tools']) {
     if ((frontmatter.match(new RegExp(`^${key}:`, 'gmu')) ?? []).length > 1) return `duplicate \`${key}:\` key in the frontmatter`;
   }
-  if (cleanValue(frontmatter.match(/^name:(.*)$/mu)?.[1]) !== 'executor') return 'frontmatter does not declare `name: executor`';
+  if (scalarOf(frontmatter, 'name') !== stem) return `frontmatter does not declare \`name: ${stem}\``;
   if (!/^tools:/mu.test(frontmatter)) return null;
-  const inline = cleanValue(frontmatter.match(/^tools:(.*)$/mu)?.[1]);
-  const listed = inline || blockItems(frontmatter).join(', ');
-  if (!listed) return 'tools: is empty — grant a list that includes Bash, or drop the line';
-  const granted = listed.split(',').map((tool) => cleanValue(tool));
-  return granted.includes('Bash') ? null : `tools: ${listed} is read-only`;
+  const granted = listedTools(frontmatter);
+  if (granted.length === 0) return 'tools: is empty — grant a list that includes Bash, or drop the line';
+  return granted.includes('Bash') ? null : `tools: ${granted.join(', ')} is read-only`;
 };
 
-// A symlinked, non-regular or unreadable vehicle is a STATE the carrier degrades on, so this survey
-// answers it instead of throwing: its callers compose the answer into a readiness array.
-export const surveyExecutorVehicle = (projectDir, deps = {}) => {
-  const rel = EXECUTOR_VEHICLE_REL;
+const lensFrontmatter = (frontmatter, stem) => {
+  for (const key of ['name', 'model', 'effort', 'tools']) {
+    const count = (frontmatter.match(new RegExp(`^${key}:`, 'gmu')) ?? []).length;
+    if (count !== 1) return { refusal: count === 0 ? `frontmatter has no \`${key}:\` key` : `duplicate \`${key}:\` key in the frontmatter` };
+  }
+  if (scalarOf(frontmatter, 'name') !== stem) {
+    return { refusal: `frontmatter does not declare \`name: ${stem}\`` };
+  }
+  const scalars = Object.fromEntries(['model', 'effort'].map((key) => [key, scalarOf(frontmatter, key)]));
+  for (const [key, value] of Object.entries(scalars)) {
+    if (value === null) return { refusal: `${key}: is not a scalar` };
+    if (value === '') return { refusal: `${key}: is empty` };
+  }
+  const tools = listedTools(frontmatter);
+  if (tools.length === 0) return { refusal: 'tools: must grant a non-empty read-only list' };
+  const unsafe = tools.find((tool) => !READ_ONLY_TOOLS.has(tool));
+  if (unsafe) return { refusal: `tools: grants non-read-only tool ${unsafe}` };
+  return { refusal: null, ...scalars };
+};
+
+const templateFor = (spec, deps) => {
+  if (spec.template == null) return null;
+  const bundled = readBundledAgents(deps).find((item) => item.name === `${spec.template}.md`);
+  if (!bundled) throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `${spec.template}.md is missing from the bundle`);
+  return {
+    name: `${spec.stem}.md`,
+    content: spec.derived ? deriveLensTemplate(bundled.content, spec) : bundled.content,
+  };
+};
+
+export const surveyVehicle = (projectDir, spec, deps = {}) => {
+  const rel = `${AGENTS_DIR}/${spec.stem}.md`;
   try {
-    const template = readBundledAgents(deps).find((item) => item.name === EXECUTOR_VEHICLE);
-    if (!template) throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `${EXECUTOR_VEHICLE} is missing from the bundle`);
+    const template = templateFor(spec, deps);
     const fs = readFsDeps(deps);
     assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
     assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
-    const [placement] = planPlacement([template], projectDir, deps);
-    if (placement.action === 'place') return { state: 'missing', reason: null, rel };
-    if (placement.action === 'already-current') return { state: 'placed', reason: null, rel };
-    const refusal = executorFrontmatterRefusal(placement.existing);
-    return refusal === null
-      ? { state: 'customized', reason: null, rel }
-      : { state: 'unusable', reason: refusal, rel };
+    const placeholder = template ?? { name: `${spec.stem}.md`, content: null };
+    const [placement] = planPlacement([placeholder], projectDir, deps);
+    if (placement.action === 'place') {
+      const reason = template === null ? 'no bundled template to derive it from' : null;
+      return { state: 'missing', reason, rel };
+    }
+    const frontmatter = frontmatterOf(placement.existing ?? template?.content);
+    if (placement.action === 'already-current') {
+      if (spec.tools !== 'read-only') return { state: 'placed', reason: null, rel };
+      const lens = lensFrontmatter(frontmatter, spec.stem);
+      return lens.refusal === null
+        ? { state: 'placed', reason: null, rel, model: lens.model, effort: lens.effort }
+        : { state: 'unusable', reason: lens.refusal, rel };
+    }
+    if (spec.tools !== 'read-only') {
+      const refusal = executorFrontmatterRefusal(frontmatter, spec.stem);
+      return refusal === null
+        ? { state: 'customized', reason: null, rel }
+        : { state: 'unusable', reason: refusal, rel };
+    }
+    const lens = lensFrontmatter(frontmatter, spec.stem);
+    return lens.refusal === null
+      ? { state: 'customized', reason: null, rel, model: lens.model, effort: lens.effort }
+      : { state: 'unusable', reason: lens.refusal, rel };
   } catch (err) {
     return { state: 'unusable', reason: err?.message ?? String(err), rel };
   }
 };
 
+export const surveyExecutorVehicle = (projectDir, deps = {}) => surveyVehicle(projectDir, EXECUTOR_VEHICLE_SPEC, deps);
+
 refuseDirectRun(import.meta.url);

package/tools/cheap-agents.mjs

@@ -10,7 +10,8 @@
 // The family's second `.claude/` writer, the velocity-profile.mjs writer discipline verbatim:
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
 //   • deployment-gated — `--apply` STOPs unless docs/ai/.workflow-version equals the lineage
-//     head (a dry-run stays usable on any project);
+//     head (a dry-run stays usable whatever the stamp says; an unreadable orchestration config
+//     STOPs both, since the derived lenses it names cannot be known);
 //   • symlink-safe — a symlinked `.claude` / `.claude/agents` / target file is a STOP, never a
 //     write-through;
 //   • NEVER overwrites an existing .claude/agents/ file whose content differs from the bundled
@@ -25,7 +26,8 @@
 // apply report reminds you.
 //
 // Exit codes: 0 done / dry-run (incl. preserved customizations — a user's file is a legitimate
-// state, not an error); 1 precondition STOP (stamp, symlink, missing bundle); 2 usage.
+// state, not an error); 1 precondition STOP (stamp, symlink, missing bundle, an unreadable
+// orchestration config — the derived lenses it names cannot be known); 2 usage.
 // Dependency-free, Node >= 22. No side effects on import.
 
 import { mkdirSync, writeFileSync } from 'node:fs';
@@ -33,6 +35,9 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isDirectRun } from './direct-run.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { lensMembersOf } from './review-roster.mjs';
+import { deriveLensTemplate, lensVehicleSpec } from './review-roster-resolve.mjs';
 // The READ core, never a second copy: the bundle, the placement plan and the executor survey live
 // there so the read-only advisor graph can reach them without reaching this writer.
 import {
@@ -42,6 +47,9 @@ import {
   EXPECTED_WORKFLOW_VERSION,
   UTF8,
   CHEAP_AGENTS_STAMP,
+  CHEAP_AGENTS_BUNDLE,
+  CHEAP_AGENTS_CONFIG,
+  EXECUTOR_VEHICLE,
   makeCheapAgentsError,
   readFsDeps,
   readBundledAgents,
@@ -59,6 +67,7 @@ export {
   CHEAP_AGENTS_STAMP,
   CHEAP_AGENTS_SYMLINK,
   CHEAP_AGENTS_BUNDLE,
+  CHEAP_AGENTS_CONFIG,
   makeCheapAgentsError,
   readBundledAgents,
   planPlacement,
@@ -86,6 +95,7 @@ model. The fifth, executor, is the ONE full-tool vehicle: dispatched only for a
 authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and
 it never commits.
 Default is --dry-run (a preview; writes nothing). --apply writes.
+Configured derived review lenses are planned and placed beside the bundled vehicles.
 An existing file with DIFFERENT content is preserved and reported, never overwritten.`;
 
 export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
@@ -95,10 +105,12 @@ const writeFsDeps = (deps = {}) => ({
   writeFile: deps.writeFile ?? writeFileSync,
 });
 
-export const preflightCheapAgents = ({ cwd }, deps = {}) => {
+export const preflightCheapAgents = ({ cwd, derived = [] }, deps = {}) => {
   const fs = readFsDeps(deps);
   const projectDir = cwd ?? process.cwd();
-  const templates = readBundledAgents(deps);
+  const templatesByName = new Map(readBundledAgents(deps).map((template) => [template.name, template]));
+  for (const template of derived) templatesByName.set(template.name, template);
+  const templates = [...templatesByName.values()];
   const stamp = readStamp(join(projectDir, WORKFLOW_STAMP), fs);
   const stampOk = stamp === EXPECTED_WORKFLOW_VERSION;
   assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
@@ -107,11 +119,38 @@ export const preflightCheapAgents = ({ cwd }, deps = {}) => {
   return { projectDir, stamp, stampOk, plan };
 };
 
+const loadConfigOrStop = (cwd, deps) => {
+  try {
+    return loadConfig(cwd, deps.readFile, deps.lstat).config;
+  } catch (err) {
+    throw makeCheapAgentsError(CHEAP_AGENTS_CONFIG, `${err?.message ?? err} — the agents writer cannot read the configured review lenses — nothing is placed`);
+  }
+};
+
+const configuredDerivedTemplates = (cwd, deps) => {
+  const config = loadConfigOrStop(cwd, deps);
+  const bundle = readBundledAgents(deps);
+  const templates = new Map();
+  for (const member of lensMembersOf(config)) {
+    const spec = lensVehicleSpec(member);
+    if (!spec.derived) continue;
+    const base = bundle.find((template) => template.name === `${spec.template}.md`);
+    if (!base) throw makeCheapAgentsError(CHEAP_AGENTS_BUNDLE, `${spec.template}.md is missing from the bundle`);
+    templates.set(`${spec.stem}.md`, { name: `${spec.stem}.md`, content: deriveLensTemplate(base.content, spec) });
+  }
+  return [...templates.values()];
+};
+
+export const applyCheapAgentsCommand = (root) =>
+  `node ${shellQuoteArg(fileURLToPath(import.meta.url))} --apply --cwd ${shellQuoteArg(root)}`;
+
 // ── the writer ────────────────────────────────────────────────────────────────────────
 
 export const writeCheapAgents = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const fs = writeFsDeps(deps);
-  const preflight = preflightCheapAgents({ cwd }, deps);
+  const projectDir = cwd ?? process.cwd();
+  const derived = configuredDerivedTemplates(projectDir, deps);
+  const preflight = preflightCheapAgents({ cwd: projectDir, derived }, deps);
   if (dryRun) return { wrote: false, dryRun: true, ...preflight };
 
   if (!preflight.stampOk) {
@@ -147,8 +186,9 @@ export const formatResult = (result) => {
   if (!result.stampOk) {
     lines.push(`note: no current deployment stamp found (${result.stamp ?? 'none'}) — --apply will refuse until init/upgrade runs.`);
   }
+  const readOnlyCount = result.plan.filter((item) => item.name !== EXECUTOR_VEHICLE).length;
   lines.push(
-    'four vehicles are Claude Code subagents with READ-ONLY tools and NO shell — so a fan-out can never turn into a wave of approval prompts.',
+    `${readOnlyCount} vehicles are Claude Code subagents with READ-ONLY tools and NO shell as bundled or derived (a customized file keeps whatever it grants) — so a fan-out on the shipped templates can never turn into a wave of approval prompts.`,
     `three of those ride the cheap lane (model: haiku, effort: low) for mechanical work; ${FALLBACK_LENS_ADDITIONAL_ONLY}`,
     'executor is the one FULL-TOOL vehicle: dispatched only for a bounded execution, authoring, or write-capable routine slice the orchestrator verifies, never for read-only work, and it never commits.',
   );
@@ -156,7 +196,7 @@ export const formatResult = (result) => {
   // item's one-liner, and that flow's contract is "run the printed command, no improvisation" — a
   // bare "re-run with --apply" would leave the caller to reconstruct --cwd and its quoting.
   if (result.dryRun && result.plan.some((item) => item.action === 'place')) {
-    lines.push(`to apply, run exactly: node ${shellQuoteArg(fileURLToPath(import.meta.url))} --apply --cwd ${shellQuoteArg(result.projectDir)}`);
+    lines.push(`to apply, run exactly: ${applyCheapAgentsCommand(result.projectDir)}`);
   }
   if (!result.dryRun && result.wrote) {
     lines.push('hidden-mode note: if this deployment is hidden, run the hide-footprint reconcile so the placed files stay out of `git status`.');

package/tools/detect-backends.mjs

@@ -97,7 +97,7 @@ const RAW_BACKENDS = [
         ],
         grounding: 'automatic — the wrapper precomputes the full working-tree change set (repo map, status, diffs, untracked contents) and codex auto-merges the root AGENTS.md; no grounding flags',
         continue: [],
-        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review',
+        receipt: 'side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan mode; durationS = integer wall-clock seconds from CLI start through verdict parsing and the wrapper prints review duration: <n>s; blocking = the count of [blocker] and [major] lines (schema mode: findings with either severity; a payload whose findings cannot be counted fails the run, no receipt); artifactPath = the normalized realpath on plan receipts only (repo-relative inside the work tree, absolute otherwise), while a double quote, backslash or control byte refuses pre-spend because the receipt encoder cannot carry it; verdict parsed from the mandated literal verdict line (schema mode: the verdict field); always fresh:true (one-shot) + grounded:true (native AGENTS.md auto-merge, factsHash null); probe = whether the run relaxed the quality guards (CODEX_PROBE=1), written on EVERY receipt so it self-declares — the kit\'s review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model, effort, tier} (tier null on the standard tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, and a posture value carrying control bytes refuses pre-spend in every mode; a run whose final message carries NO recognized \'Verdict: <ship|revise|rethink>\' line — empty or missing output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review',
         notes: [
           'the review posture banner appends a banner-only timeout=<duration> field — exactly the duration handed to timeout(1); the hard-timeout preflight fails CLOSED when no timeout/gtimeout binary exists (the wrapper refuses by name before any CLI run, so an uncapped review run can no longer happen), and the field never enters the receipt posture or the D5 banner↔receipt parity',
           'quote the posture banner verbatim when labeling this dispatch — the banner is the machine-stated posture; a prose re-type drifts',
@@ -139,7 +139,7 @@ const RAW_BACKENDS = [
           'agy-review --continue [--decided @f] [--focus "…"] [--nonce <n>]',
           'agy-review --conversation <id> [--decided @f] [--focus "…"] [--nonce <n>]',
         ],
-        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review",
+        receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; durationS = integer wall-clock seconds from CLI start through verdict parsing and the wrapper prints review duration: <n>s; blocking = the count of numbered items in the first ### Blocking section; artifactPath = the normalized realpath on plan/diff receipts only (repo-relative inside the work tree, absolute otherwise), while a double quote, backslash or control byte refuses pre-spend because the receipt encoder cannot carry it; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (code mode refuses pre-spend without one — no run, no receipt — unless --ungrounded/AGY_PROBE=1; in plan/diff an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); probe = whether the run relaxed the quality guards (AGY_PROBE=1), written on EVERY receipt so it self-declares — the kit's review-state gate rejects a probe-marked receipt (a probe review never attests) and equally rejects an unmarked one (silence is not a declaration); posture = the ACTUAL run posture {model} (agy has no tier), written on EVERY receipt (D5) — the gate rejects a receipt with an absent/invalid posture (a pre-D5 wrapper minted it; re-run the review), one stderr banner line states the same posture, an ATTESTING review with AGY_MODEL explicitly emptied refuses pre-spend, and a model string carrying control bytes refuses pre-spend in every mode; delivery = how the change set REACHED the model, currently emitted as 'inline' (the whole set rode one prompt — proven by construction) or 'fed' (a chunked feed whose per-part echo proof verified); REQUIRED on every agy code receipt and its ABSENCE is what stops a pre-fed-lane receipt attesting, while the gate accepts any well-formed declaration rather than a particular value; absent by construction on plan/diff/continuation receipts, which carry no change set; a run whose output carries NO recognized '### Verdict' section — empty output included — exits 4 with NO receipt (D4: a FAILED review to RE-RUN, never a fatal session error); when the dispatch nonce seam is supplied — the AW_REVIEW_NONCE environment value or its plain-argument equivalent --nonce <n> (one seam: the flag assigns the same value; supplying both with different values refuses pre-spend) — under the safe grammar [A-Za-z0-9._-]{1,64} (anything else refuses pre-spend), the wrapper first mints the finding MANIFEST {schema, backend, nonce, fingerprint, findings} beside the receipts file (agent-workflow-finding-manifest-<backend>-<nonce>.json; atomic, no-clobber — a byte-identical rewrite is an idempotent no-op, different bytes refuse loudly) ORDERED before the receipt append — a failed manifest write EXCLUDES the receipt append, so a nonce-supplied dispatch can never land a receipt without its readable manifest; a nonce-less invocation adds NO nonce field and mints NO finding manifest (the existing wrapperVersion field still changes with each bridge release); a write failure warns, never fails the review",
         notes: [
           'transport: every review dispatch drives the CLI in --output-format json (plus --disable-slash-commands) and the returned envelope is parsed in node (bin/agy-envelope.mjs) — the operator-facing invocations and flags above do NOT change, and on a ZERO exit the wrapper still PRINTS the review text, never JSON. A missing or unreadable envelope on a zero exit is a loud failure with NO receipt, never a downgraded verdict and never a fallback to raw-stdout parsing; a non-zero CLI exit keeps its own code and message, and publishes the captured stdout unchanged from the SINGLE dispatch or the FINAL fed turn (which may therefore be a JSON or partial payload — the envelope is parsed only on a zero exit); an INTERMEDIATE feed turn is the exception, its output stays private (Invariant E) and its failure prints only a named error. Enforced by a PRE-SPEND capability probe, not a version floor: agy --help must advertise --output-format and --disable-slash-commands, node must be >= 22, and bin/agy-envelope.mjs must be present — otherwise the review refuses before any run is spent and names the missing capability',
           'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',

package/tools/direct-run.mjs

@@ -62,6 +62,9 @@ export const LIBRARY_ONLY_MODULES = Object.freeze({
   // The READ core of the subagent-vehicle surface: it sits one name away from the writer
   // references/modes/agents.md DOES name, and reaching for it is reaching for the agents mode.
   'cheap-agents-read.mjs': '/agent-workflow-kit agents',
+  'review-roster.mjs': '/agent-workflow-kit recipes',
+  'review-roster-resolve.mjs': '/agent-workflow-kit recipes',
+  'set-recipe-roster.mjs': '/agent-workflow-kit set-recipe',
 });
 
 // The frozen refusal line. One line, names the module, names the command.

package/tools/fold-scope.mjs

@@ -22,10 +22,13 @@
 // Dependency-free, Node >= 22.
 
 import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { PLAN_HEADINGS, bulletBlocks } from './plan-shape.mjs';
+
+export { bulletBlocks };
 
 export const CLASSES = ['in-scope', 'new-invariant', 'blocking'];
 export const ROW_FIELDS = ['invariant', 'origin', 'narrow fix', 'proof', 'residual exposure'];
-export const ACCEPTANCE_HEADING = '## Verification';
+export const ACCEPTANCE_HEADING = PLAN_HEADINGS[2];
 // The canon says a deferral row carries "the origin `file:line`". Anchored at the start of the value
 // and a POSITIVE line number, so "file.mjs:12junk" and "file.mjs:0" are not one; trailing context
 // after the token is fine, because the canon asks the row to CARRY a file:line, not to carry nothing
@@ -35,68 +38,10 @@ const ORIGIN_SHAPE = /^\S+:[1-9]\d*(\s|$)/;
 // literals refuses fail-closed; the general per-project status grammar is queued, not guessed here.
 const CLOSED_MARKERS = ['DONE', 'CLOSED'];
 const ORIGIN_MISSING = 'origin (the canon requires a file:line)';
-const BULLET = /^-\s+\S/;
 
 const normalize = (s) => String(s ?? '').replace(/\r/g, '').replace(/\s+/g, ' ').trim();
 const contains = (haystack, needle) => normalize(haystack).toLowerCase().includes(needle);
 
-// The ONE bullet scan both readers use, over the block model's lines. A fenced region is a quotation
-// AND a boundary: it closes the block it interrupts, so text past a fence can never join the bullet
-// before it (which would let a far-side literal satisfy a near-side claim). A `-` plus any whitespace
-// run opens a block; a blank or indented line continues it; any other unindented line closes it.
-// Blocks are returned RAW (their own lines) — the queue reader needs the field lines inside them —
-// each carrying the body index it OPENS at, because a second reader (queue-audit.mjs) reports rows by
-// file line and a scan that dropped the index would have to re-derive it against a different grammar.
-//
-// `fenceContinues` is the SECOND reader's question, and it is a different one. A deferral row asks
-// what a bullet CLAIMS, so a fence must cut it. A queue row asks what a bullet COSTS and whether it
-// is still work, and there the fence-as-boundary is a hole: measured, a row carrying a code block
-// reported ONE line and its `**DONE 2026-01-01:**` two lines further down was invisible, so the
-// per-row cap could be walked straight past and a closure went unseen.
-//
-// Under the option only a NESTED fence continues an open block — one whose opening line is indented,
-// which is what makes it part of the list item at all. A fence opening at column 0 is a
-// DOCUMENT-level block and still closes the row, exactly as an unindented line does; absorbing it
-// charged a one-line row for six. The run is decided ONCE, at its opening line, so a content line
-// inside it cannot re-decide the question.
-//
-// The absorbed lines never enter `lines` — a marker inside a quotation is not a status — so the
-// block records where they were: `span` is the row's PHYSICAL extent, and `gaps` holds the `lines`
-// indices a fence run follows, so a reader assembling a multi-line span cannot join text from both
-// sides of a code block into one claim.
-export const bulletBlocks = (lines, fencedLines, from, to, { fenceContinues = false } = {}) => {
-  const blocks = [];
-  let current = null;
-  let absorbing = null;
-  const close = () => {
-    if (current) blocks.push(current);
-    current = null;
-  };
-  for (let index = from; index < to; index += 1) {
-    if (fencedLines.has(index)) {
-      if (absorbing === null) absorbing = Boolean(fenceContinues && current && /^\s+\S/.test(lines[index]));
-      if (!absorbing) close();
-      else {
-        current.span += 1;
-        current.gaps.add(current.lines.length - 1);
-      }
-      continue;
-    }
-    absorbing = null;
-    const line = lines[index];
-    if (BULLET.test(line)) {
-      close();
-      current = { start: index, lines: [line], span: 1, gaps: new Set() };
-    } else if (current && (line.trim() === '' || /^\s+\S/.test(line))) {
-      current.lines.push(line);
-      current.span += 1;
-    } else {
-      close();
-    }
-  }
-  close();
-  return blocks;
-};
 
 // extractAcceptance(planText) -> the top-level bullets under `## Verification`, each collapsed to one
 // line. Per the planning canon those bullets ARE the acceptance criteria and they are the WHOLE list.
@@ -131,7 +76,7 @@ const parseFields = (block) => {
     if (match) {
       open = match[1].toLowerCase().replace(/\s+/g, ' ');
       values[open] = [...(values[open] ?? []), match[2].trim()];
-    } else if (open && /^\s+\S/.test(line) && !BULLET.test(line.trim())) {
+    } else if (open && /^\s+\S/.test(line) && !/^-\s+\S/.test(line.trim())) {
       values[open][values[open].length - 1] += ` ${line.trim()}`;
     } else {
       open = null;

package/tools/grounding.mjs

@@ -36,7 +36,7 @@ import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 // (f) --autonomy (AD-044 Plan 3): the effective per-project autonomy policy for the facts payload.
 // READ core only — never autonomy-write.mjs (the import-split invariant).
 import { AUTONOMY_REL, loadAutonomy, resolveAutonomy, isSparseSeedConfig } from './autonomy-config.mjs';
-
+import { PLAN_HEADINGS } from './plan-shape.mjs';
 const PLAN_EXECUTION = 'plan-execution';
 
 // The agy single-argv byte contract (mirrors agy-review.sh — the wrapper is the enforcement home).
@@ -44,7 +44,7 @@ export const DEFAULT_MAX_PROMPT_BYTES = 120000;
 export const ARGV_HARD_MAX = 131000;
 
 export const CONSTRAINTS_HEADING = /^## .*Hard Constraints$/;
-export const PLAN_SECTIONS = ['## Goal and boundary', '## Module ledger', '## Verification'];
+export const PLAN_SECTIONS = PLAN_HEADINGS.slice(0, 3);
 
 // ── pure section slicing (exactly-one-match; the inject-methodology discipline) ────────