@sabaiway/agent-workflow-kit 10.3.0 → 10.5.0

package/tools/family-registry.mjs

@@ -28,7 +28,7 @@ import { parseSemver, compareSemver } from './semver-lite.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { START_MARKER, excludePath, inferVisibility } from './hide-footprint.mjs';
 import { readEngineFragment, ORCHESTRATION_FRAGMENT_REL, PROCEDURES_FRAGMENT_REL, AUTONOMY_FRAGMENT_REL, LENS_FRAGMENT_REL, LENS_PRIORS_REL } from './engine-source.mjs';
-import { ACTIVITIES, resolveActivityRecipe } from './recipes.mjs';
+import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
 // The config reader lives in orchestration-config.mjs (the single config contract). The read-only status
 // settings-survey reuses THIS reader (one strict-JSON + loud-on-malformed contract), not a second copy.
 import { loadConfig } from './orchestration-config.mjs';
@@ -52,9 +52,10 @@ import { HOOK_FILE_REL as GATE_HOOK_FILE_REL, isHookWired } from './gate-hook.mj
 // writer, which pulls in the atomic-write core) so the status survey stays a pure reader.
 import { settingsSnapshot } from './bridge-settings-read.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
-// The cheap-agents writer's own bundle reader + placement planner — reused by the settings survey
-// (one implementation, never a drifting copy; cheap-agents imports only node builtins, no cycle).
-import { readBundledAgents, planPlacement } from './cheap-agents.mjs';
+// The cheap-agents READ core's bundle reader, placement planner and executor-vehicle survey —
+// reused by the settings survey (one implementation, never a drifting copy; the read core imports
+// only node builtins, no cycle).
+import { readBundledAgents, planPlacement, surveyExecutorVehicle, EXECUTOR_VEHICLE, assertDirSafe, readFsDeps, CLAUDE_DIR, AGENTS_DIR } from './cheap-agents-read.mjs';
 // The status vocabulary (manifestState constants, internal→public maps, display names, the no-leak
 // forbidden set) lives in the frozen labels.mjs LEAF (Plan §4.2 B1) so the import graph is acyclic —
 // nothing imports family-registry for vocabulary. Imported here for internal use; the public subset is
@@ -486,9 +487,6 @@ export const surveyProject = (projectDir, deps = {}) => {
 // consumes THIS, never the human table verbatim. An envelope-shape test pins its shape so later phases
 // (the settings/visibility block) can't silently break the Phase-2 version consumer.
 
-// STATE_PUBLIC (internal→public token map) + DISPLAY_NAMES + displayOf now live in labels.mjs (B1) —
-// imported at the top of this file. They are used below exactly as before.
-
 // ── the settings survey (Phase 3) — read-only, honest, localized-on-error ──────────
 // Each sub-survey returns a small user-safe object OR a single `{ error }` field (a localized message,
 // never a crash): a malformed/unreadable file in ONE area must not break the rest of `status`. The
@@ -527,19 +525,21 @@ export const surveyVisibility = (dir, deps = {}) => {
 };
 
 // orchestration recipes: the EFFECTIVE recipe per slot (config · default · effective), engine-free —
-// shared loadConfig + resolveActivityRecipe + the read-only backend detector. A malformed config → a
-// localized error field; a detection failure floors at solo (a corrupt bridge must not break the view).
+// shared loadConfig + resolveActivityRecipe + the ONE readiness composition (detected backends +
+// the executor vehicle). A malformed config → a localized error field; a detection failure floors
+// at solo (a corrupt bridge must not break the view) but is surfaced as `detectError`, so the
+// render says "couldn't check backends" instead of letting a real solo-default look identical.
 export const surveyRecipes = (dir, deps = {}) => {
-  // A detector failure floors recipes at solo (mirrors procedures) but is surfaced as `detectError`, so
-  // the render says "couldn't check backends" instead of letting a real solo-default look identical.
   const { detection, error: detectError } = detectSafe(deps);
+  const projectDir = resolve(dir);
+  const readiness = composeReadiness(projectDir, { ...deps, detect: () => detection });
   try {
-    const { config, source } = loadConfig(resolve(dir), deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
+    const { config, source } = loadConfig(projectDir, deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
     const activities = {};
     for (const [activity, def] of Object.entries(ACTIVITIES)) {
       activities[activity] = {};
       for (const slot of Object.keys(def.slots)) {
-        const r = resolveActivityRecipe({ config: config ?? {}, readiness: detection, activity, slot });
+        const r = resolveActivityRecipe({ config: config ?? {}, readiness, activity, slot });
         activities[activity][slot] = { recipe: r.recipe, source: r.source, degradedFrom: r.degradedFrom ?? null };
       }
     }
@@ -616,14 +616,34 @@ export const surveyGateHook = (dir, deps = {}) => {
 };
 
 // cheap agents: the kit-placed .claude/agents/ vehicles (Mode: agents) — how many of the bundled
-// cheap-lane definitions are present in the project. A customized copy counts as PLACED (it exists;
-// the writer preserves it) — the welcome-mat agents rung keys on zero placed. Read-only; REUSES the
-// writer's own bundle reader + placement planner (cheap-agents.mjs — one implementation).
+// definitions are present in the project, plus the ONE full-tool vehicle's own state. A customized
+// copy counts as PLACED (it exists; the writer preserves it) — the welcome-mat agents rung keys on
+// zero placed, so the counts span every vehicle, the executor included. The executor state comes
+// from the read core's survey (the subagent carrier's one instrument — one implementation), which
+// answers a state instead of throwing; its reason rides along when it carries one.
 export const surveyCheapAgents = (dir, deps = {}) => {
   try {
+    const projectDir = resolve(dir);
     const templates = readBundledAgents(deps);
-    const plan = planPlacement(templates, resolve(dir), deps);
-    return { bundled: templates.length, placed: plan.filter((p) => p.action !== 'place').length };
+    const vehicle = (deps.surveyVehicle ?? surveyExecutorVehicle)(projectDir, deps);
+    // The executor is judged by its own survey (which answers a state where the placement plan
+    // would throw); the plan covers the read-only vehicles, so a broken executor never hides them,
+    // and it never follows a symlinked ancestor — the writer's own guard refuses first.
+    const executor = { executor: vehicle.state, ...(vehicle.reason ? { executorReason: safeLine(vehicle.reason) } : {}) };
+    try {
+      const fs = readFsDeps(deps);
+      assertDirSafe(join(projectDir, CLAUDE_DIR), CLAUDE_DIR, fs);
+      assertDirSafe(join(projectDir, AGENTS_DIR), AGENTS_DIR, fs);
+      const plan = planPlacement(templates.filter((t) => t.name !== EXECUTOR_VEHICLE), projectDir, deps);
+      return {
+        bundled: templates.length,
+        readOnly: templates.filter((t) => t.name !== EXECUTOR_VEHICLE).length,
+        placed: plan.filter((p) => p.action !== 'place').length + (['placed', 'customized'].includes(vehicle.state) ? 1 : 0),
+        ...executor,
+      };
+    } catch (err) {
+      return { error: localizeError(err), ...executor };
+    }
   } catch (err) {
     return { error: localizeError(err) };
   }

package/tools/flow-check.mjs

@@ -29,8 +29,7 @@ import {
   resolveReceiptsPath, readReceipts, computeTreeFingerprint,
 } from './core-evidence.mjs';
 import { loadConfig } from './orchestration-config.mjs';
-import { requiredBackendsForConfiguredRecipe, DISPLAY_ALIASES } from './recipes.mjs';
-import { detectBackends } from './detect-backends.mjs';
+import { requiredBackendsForConfiguredRecipe, DISPLAY_ALIASES, composeReadiness } from './recipes.mjs';
 import { decideFlowCheck } from './flow-check-cores.mjs';
 import { short } from './flow-check-rungs.mjs';
 import {
@@ -116,11 +115,7 @@ export const computeFlowDecision = ({ cwd = process.cwd(), consumer = 'gate', pr
     let readiness = [];
     let detectionFailed = false;
     if (configFailure == null && config?.['plan-execution']?.review == null) {
-      try {
-        readiness = detectBackends();
-      } catch {
-        detectionFailed = true;
-      }
+      readiness = composeReadiness(top, { ...probes, onDetectError: () => { detectionFailed = true; } });
     }
     const obligations = configFailure == null
       ? requiredBackendsForConfiguredRecipe({ config, readiness, detectionFailed })

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) ────────
 

package/tools/inject-methodology.mjs

@@ -86,10 +86,14 @@ export const KNOWN_PRIOR_METHODOLOGY_SLOT = [
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe.',
   // engine 2.1.0 — the pre-canon-rewrite pointer (vocabulary + plan-then-execute wording, with the communication contract).
   '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
+  // engine 4.2.0 — the two-activity pointer, before `routine` joined the named activities.
+  '> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. The plan shape, its caps and lifecycle live in the project\'s **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5. Named activities (plan-authoring, plan-execution) have procedures — see `/agent-workflow-kit procedures <activity>` for the steps + resolved recipe. **Communication:** user-facing messages deliver the artifact inline (paste the prompt / diff / command — never "see §X" as a substitute), lead with the result, show exactly what was asked, and never read as mockery (a large artifact: a real summary inline + a link).',
 ];
 export const KNOWN_PRIOR_ORCH_SLOT = [
   // v1.3.0 — pre-read-at-start orchestration pointer (recipes vocabulary, no orchestration.json clause).
   '> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs.',
+  // engine 4.2.0 — the four-recipe pointer with the read-at-start clause, before the Subagent carrier joined the list.
+  '> **Orchestration recipes** — compose plan → execute → review with a named recipe: **Solo** (no backend), **Reviewed** (one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a bounded sub-task); the orchestrator always commits, a backend is never autonomous. Pick + plan one for this environment with `/agent-workflow-kit recipes` (read-only); the deployed how/why lives in your `docs/ai/` workflow docs. At the start of a planning/execution session, read your standing recipe preference in `docs/ai/orchestration.json` — set it in plain language with `/agent-workflow-kit set-recipe` (previews first; hand-edit stays supported).',
 ];
 
 // A slot descriptor bundles everything the generic engine needs to operate on ONE marker pair.

package/tools/orchestration-config.mjs

@@ -22,6 +22,16 @@ import { readFileSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { ACTIVITIES, SLOT_RECIPES } from './recipes.mjs';
 import { refuseDirectRun } from './direct-run.mjs';
+import { validateRoster } from './review-roster.mjs';
+import {
+  CANON_README,
+  KNOWN_PRIOR_README,
+  normalizeCanonical,
+  refreshIfCanonical,
+  refreshReadme,
+} from './orchestration-readme.mjs';
+
+export { CANON_README, KNOWN_PRIOR_README, normalizeCanonical, refreshIfCanonical, refreshReadme };
 
 // The hand-editable / agent-writable, 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.
@@ -68,7 +78,7 @@ export const assertSlotRecipe = (activity, slot, recipe, exitCode = 2) => {
   if (!(SLOT_RECIPES[slotType] ?? []).includes(recipe)) {
     throw fail(
       exitCode,
-      `invalid recipe "${recipe}" for ${slotType} slot of "${activity}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
+      `invalid value "${recipe}" for ${slotType} slot of "${activity}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
     );
   }
   return slotType;
@@ -98,14 +108,14 @@ const parseQualified = (lhs, flag) => {
 export const parseOp = (kind, token) => {
   if (kind === 'set') {
     const eq = token.indexOf('=');
-    if (eq <= 0) throw fail(2, `--set must be <activity>.<slot>=<recipe> (got "${token}")`);
+    if (eq <= 0) throw fail(2, `--set must be <activity>.<slot>=<value> (got "${token}")`);
     const recipe = token.slice(eq + 1);
-    if (!recipe) throw fail(2, `--set must be <activity>.<slot>=<recipe> (got "${token}")`);
+    if (!recipe) throw fail(2, `--set must be <activity>.<slot>=<value> (got "${token}")`);
     const { activity, slot } = parseQualified(token.slice(0, eq), '--set');
     assertSlotRecipe(activity, slot, recipe);
     return { kind: 'set', activity, slot, recipe };
   }
-  if (token.includes('=')) throw fail(2, `--unset takes <activity>.<slot> without a recipe (got "${token}")`);
+  if (token.includes('=')) throw fail(2, `--unset takes <activity>.<slot> without a value (got "${token}")`);
   const { activity, slot } = parseQualified(token, '--unset');
   assertSlot(activity, slot);
   return { kind: 'unset', activity, slot };
@@ -242,10 +252,18 @@ export const validateConfig = (config) => {
           `${CONFIG_REL}: unknown slot "${slot}" for activity "${key}" (${key} slots: ${Object.keys(activityDef.slots).join(', ')})`,
         );
       }
+      if (Array.isArray(recipe) && slotType === 'review') {
+        try {
+          validateRoster(recipe);
+        } catch (error) {
+          throw fail(1, `${CONFIG_REL}: invalid review roster for "${key}.${slot}" (${error.message})`);
+        }
+        continue;
+      }
       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(', ')})`,
+          `${CONFIG_REL}: invalid value ${JSON.stringify(recipe)} for ${slotType} slot of "${key}" (${slotType} accepts: ${SLOT_RECIPES[slotType].join(', ')})`,
         );
       }
     }
@@ -338,62 +356,6 @@ export const serializeConfig = (config) => {
   return `${JSON.stringify(ordered, null, 2)}\n`;
 };
 
-// ── canonical-refresh (shared by the _README refresh + the injected-slot refresh) ───
-// normalizeCanonical: trim + LF-normalize (handles the CRLF / trailing-whitespace trap) so a byte-noisy
-// copy of a canonical string still matches. refreshIfCanonical: replace `current` with `next` IFF it
-// normalize-equals ANY known prior canonical; otherwise return `current` UNCHANGED (preserve a
-// customization). Pure; no fs. Used for the orchestration `_README` and the two injected pointers.
-
-export const normalizeCanonical = (s) => String(s).replace(/\r\n/g, '\n').trim();
-
-export const refreshIfCanonical = (current, knownPriorCanonicals, next) => {
-  const cur = normalizeCanonical(current);
-  return knownPriorCanonicals.some((prior) => normalizeCanonical(prior) === cur) ? next : current;
-};
-
-// ── canonical `_README` (drift-guarded, append-only known-prior set) ─────────────────
-// CANON_README is the CURRENT onboarding note — what the templates ship + what a refresh installs. It
-// frames hand-edit as a still-available option AND points at the set-recipe writer (no "never written
-// for you"). KNOWN_PRIOR_README is the APPEND-ONLY set of every PREVIOUS canonical note: any release
-// that changes CANON_README must FIRST append the outgoing string here, so an immediately-previous
-// deployment still normalize-matches and gets refreshed (a customized note never matches → preserved).
-export const CANON_README =
-  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. " +
-  "Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, " +
-  "previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you " +
-  "prefer; that option never goes away. Each activity is configured independently (e.g. plan-authoring, " +
-  "plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts " +
-  "solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an " +
-  "'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default " +
-  "below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second " +
-  "opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's " +
-  "line (or run `set-recipe --unset <activity>.<slot>`) to fall back to the computed default (reviewed when a " +
-  "review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps " +
-  "plus the recipe resolved for your environment. Strict JSON — no comments.";
-
-export const KNOWN_PRIOR_README = [
-  // v1 (pre-set-recipe) — the "Hand-edit this file — it is never written for you" note. APPEND-ONLY.
-  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
-];
-
-// refreshReadme(config) → { config, changed }: refresh ONLY the `_README` value when it normalize-
-// matches a known prior canonical (preserve a customized note untouched); seed it when absent. The
-// stamp-independent config-ensure (kit fallback + memory delegated upgrade paths) uses this so an
-// install-base deployment gains the new note without a migration file — never clobbering a customization.
-export const refreshReadme = (config) => {
-  if (config == null || typeof config !== 'object' || Array.isArray(config)) {
-    return { config, changed: false };
-  }
-  const had = config._README;
-  const nextReadme = had === undefined ? CANON_README : refreshIfCanonical(had, KNOWN_PRIOR_README, CANON_README);
-  if (nextReadme === had) return { config, changed: false };
-  const next = { _README: nextReadme };
-  for (const [k, v] of Object.entries(config)) {
-    if (k !== '_README') next[k] = v;
-  }
-  return { config: next, changed: true };
-};
-
 // The canonical seed file body (what `init` deploys + what serializeConfig round-trips byte-identically).
 export const SEED_CONFIG = { _README: CANON_README, 'plan-authoring': { review: 'solo' }, 'plan-execution': { execute: 'solo', review: 'solo' } };
 

package/tools/orchestration-readme.mjs

@@ -0,0 +1,70 @@
+export const normalizeCanonical = (value) => String(value).replace(/\r\n/gu, '\n').trim();
+
+export const refreshIfCanonical = (current, knownPriorCanonicals, next) => {
+  const normalized = normalizeCanonical(current);
+  return knownPriorCanonicals.some((prior) => normalizeCanonical(prior) === normalized) ? next : current;
+};
+
+const V1_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). " +
+  "The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.";
+
+const V2_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell " +
+  "the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, " +
+  "and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option " +
+  "never goes away. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is " +
+  "each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you " +
+  "self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | " +
+  "delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no " +
+  "execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand " +
+  "off execution; those need an execution backend set up first. Remove a slot's line (or run `set-recipe --unset " +
+  "<activity>.<slot>`) to fall back to the computed default (reviewed when a review backend is ready, otherwise " +
+  "solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your " +
+  "environment. Strict JSON — no comments.";
+
+const V3_README =
+  "Per-project orchestration config: the recipe used at each step (slot) of each named activity. " +
+  "Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, " +
+  "previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you " +
+  "prefer; that option never goes away. Three activities are configured independently, and so is each slot " +
+  "within them: 'plan-authoring' (slots author, review), 'plan-execution' (slots execute, review) and " +
+  "'routine' (slots carrier, parallel). A slot's value is a recipe: a 'review' slot accepts " +
+  "solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an " +
+  "'execute' slot accepts solo | delegated | subagent (you implement / a backend runs a bounded sub-task / a " +
+  "full-tool frontier subagent carries a bounded slice you verify); the carrier slots 'plan-authoring.author' " +
+  "and 'routine.carrier' accept solo | subagent. 'routine.parallel' is a flag rather than a recipe: it accepts " +
+  "on | off and decides whether file-disjoint subagent slices dispatch concurrently. The default below is " +
+  "'solo' for every recipe and carrier slot, and 'on' for the parallel switch — no execution backend required. " +
+  "Raise a slot to reviewed or council for a second " +
+  "opinion, or to delegated to hand off execution; those need an execution backend set up first. 'subagent' " +
+  "needs the executor vehicle placed in this project — the composition root's `agents` writer places it; without " +
+  "it the slot resolves to solo with the reason stated. Remove a slot's line, or a whole activity block (or " +
+  "run `set-recipe --unset <activity>.<slot>`), to fall back to the computed default: reviewed when a review " +
+  "backend is ready and otherwise solo for a review slot, solo for author, execute and carrier, on for " +
+  "parallel. Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for " +
+  "your environment. Strict JSON — no comments.";
+
+const ROSTER_README = V3_README.replace(
+  "a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize)",
+  "a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize), or an explicit roster array such as [\"codex-review\", \"agy-review\", \"review-lens\"] in hand-edit form",
+);
+
+export const CANON_README = ROSTER_README
+  .replace("'plan-authoring' (slots author, review)", "'plan-authoring' (slots author, fold, review)")
+  .replace("the carrier slots 'plan-authoring.author' and 'routine.carrier'", "the carrier slots 'plan-authoring.author', 'plan-authoring.fold' and 'routine.carrier'")
+  .replace('solo for author, execute and carrier', 'solo for author, fold, execute and carrier');
+
+export const KNOWN_PRIOR_README = Object.freeze([V1_README, V2_README, V3_README, ROSTER_README]);
+
+export const refreshReadme = (config) => {
+  if (config == null || typeof config !== 'object' || Array.isArray(config)) return { config, changed: false };
+  const current = config._README;
+  const readme = current === undefined
+    ? CANON_README
+    : refreshIfCanonical(current, KNOWN_PRIOR_README, CANON_README);
+  if (readme === current) return { config, changed: false };
+  const next = { _README: readme };
+  for (const [key, value] of Object.entries(config)) if (key !== '_README') next[key] = value;
+  return { config: next, changed: true };
+};

package/tools/plan-shape-cli.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+import { readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tokenizeMarkdown } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { plansInFlight, PLANS_REL } from './plan-files.mjs';
+import { buildFacts, openRepo } from './plan-shape-facts.mjs';
+import { checkPlan, checkPlanStructure, formatFindings, parseLedger, PLAN_TITLE_PREFIX, verifyPlan } from './plan-shape.mjs';
+
+const USAGE = `Usage:
+  node plan-shape-cli.mjs --check <plan>
+  node plan-shape-cli.mjs --verify <plan>
+  node plan-shape-cli.mjs --check --in-flight
+  node plan-shape-cli.mjs --verify --in-flight`;
+
+const readPlan = (path) => {
+  const result = readRegularFileNoFollow(path);
+  if (result.outcome !== 'ok') throw new Error(`${path} must be a readable regular plan file (${result.className ?? result.code ?? result.outcome})`);
+  return result.content;
+};
+
+const readPlanEntries = (cwd) => {
+  try {
+    return readdirSync(join(cwd, PLANS_REL), { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw new Error(`${PLANS_REL} could not be read (${error?.code ?? 'fs error'})`);
+  }
+};
+
+const getPaths = (text) => {
+  try {
+    const rows = parseLedger(text).rows.filter((row) => row.valid);
+    return [...rows.map((row) => row.path), ...rows.map((row) => row.anchorPath).filter(Boolean)];
+  } catch {
+    return [];
+  }
+};
+
+const isPlanShape = (text) => {
+  try {
+    const first = tokenizeMarkdown(text, 'the in-flight document').headings[0];
+    return Boolean(first && first.level === 1 && first.text.startsWith(PLAN_TITLE_PREFIX));
+  } catch {
+    return true;
+  }
+};
+
+const writeLine = (write, line) => write(`${line}\n`);
+
+// A facts failure scoped to the plan's own paths is that plan's listed finding, so the other plans
+// are still judged; a repository-level refusal (the practice, a package, its pins) keeps its usage class.
+const buildPlanFacts = (cwd, repo, text) => {
+  try {
+    return { facts: buildFacts(cwd, { paths: getPaths(text), repo }) };
+  } catch (error) {
+    if (error?.scope !== 'plan') throw error;
+    return { findings: [{ line: 1, code: 'facts', message: error.message, rowId: null }], skips: [] };
+  }
+};
+
+const judgeWith = (cwd, repo, text, rules) => {
+  const built = buildPlanFacts(cwd, repo, text);
+  return built.facts ? rules(text, built.facts) : built;
+};
+
+const runExplicit = (cwd, arm, operand, write) => {
+  const text = readPlan(resolve(cwd, operand));
+  const result = judgeWith(cwd, openRepo(cwd), text, arm === '--check' ? checkPlan : verifyPlan);
+  writeLine(write, formatFindings(result, operand));
+  return result.findings.length === 0 ? 0 : 1;
+};
+
+const runInFlight = (cwd, write) => {
+  const entries = readPlanEntries(cwd);
+  const names = plansInFlight(cwd, () => entries);
+  const documents = names.map((name) => {
+    const label = `${PLANS_REL}/${name}`;
+    return { label, text: readPlan(resolve(cwd, label)) };
+  });
+  const judged = documents.filter((document) => isPlanShape(document.text));
+  const repo = openRepo(cwd);
+  const results = judged.map((document) => {
+    const result = judgeWith(cwd, repo, document.text, checkPlanStructure);
+    writeLine(write, formatFindings(result, document.label));
+    return result;
+  });
+  writeLine(write, `plan-shape: judged plans: ${judged.length}`);
+  writeLine(write, `plan-shape: skipped by shape: ${documents.length - judged.length}`);
+  return results.some((result) => result.findings.length > 0) ? 1 : 0;
+};
+
+export const main = (argv = process.argv.slice(2), io = {}) => {
+  const cwd = io.cwd ?? process.cwd();
+  const stdout = io.stdout ?? ((text) => process.stdout.write(text));
+  const stderr = io.stderr ?? ((text) => process.stderr.write(text));
+  const [arm, operand, ...rest] = argv;
+  if (!['--check', '--verify'].includes(arm) || !operand || rest.length > 0) {
+    writeLine(stderr, USAGE);
+    return 2;
+  }
+  try {
+    return operand === '--in-flight' ? runInFlight(cwd, stdout) : runExplicit(cwd, arm, operand, stdout);
+  } catch (error) {
+    writeLine(stderr, `plan-shape: ${error.message}`);
+    return 2;
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main();