@sabaiway/agent-workflow-engine 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to the methodology engine. Versions are this **package's** n
 they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
 (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.2.0 — Orchestration recipes: a named vocabulary for composing the bridges
+
+The engine now also owns the **orchestration-recipe** canon — the named patterns an agent uses to
+compose the optional execution-backends (the `codex` / `agy` bridges) into `plan → execute → review`.
+Four recipes, built over the bridges' role vocabulary: **Solo** (no backend — the floor), **Reviewed**
+(one backend reviews), **Council** (both review, you synthesize), **Delegated** (a backend executes a
+bounded sub-task). The orchestrator always owns the decisions and the single commit; a backend is
+advisory or delegated, never autonomous. The kit reads this canon **live** and surfaces a read-only
+`/agent-workflow-kit recipes` advisor that plans a recipe for the current environment.
+
+### Added
+- **`references/orchestration.md`** — the canonical narrative: the four recipes over the role
+  vocabulary, the when/why decision guidance, the graceful-degradation lattice (Council → Reviewed →
+  Solo; Delegated → Solo, always with a stated reason), and the quota/health guard.
+- **`references/orchestration-slot.md`** — the bounded **one-line** fragment the composition root
+  injects into a deployed `AGENTS.md` (between the `workflow:orchestration` markers). It names the four
+  recipes and routes to `/agent-workflow-kit recipes` — never to this engine-internal reference.
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file). The
+npm package version is a separate axis.
+
+## 1.1.0 — Live-read ready: never-downgrade gate + installer hardening
+
+The kit now reads this canon **live from the installed engine** and has retired its bundled mirror
+(see the kit's 1.11.0 / **AD-016**). This release hardens the engine's own installer to match — so an
+engine placed by `npx … kit init` (or by hand) is safe to refresh.
+
+### Added
+- **Never-downgrade gate** (cloned from the kit, AD-012): a bare `npx … init` that npx serves from an
+  **older cached build** can no longer overwrite a **newer** installed canon — `init` compares the
+  on-disk version (no network) and refuses loudly unless you pass `--allow-downgrade`. A same-version
+  re-run prints a cache hint and points at `@latest`. An existing but **unreadable** `SKILL.md` fails
+  closed (the gate is never silently bypassed).
+
+### Fixed
+- Containment check now accepts a legitimately-contained child literally named `..foo` (it wrongly
+  rejected anything starting with `..` before); `tildify` collapses only a **leading** `$HOME`, never
+  a mid-path occurrence (**Issue-004**, fixed in lockstep with the memory installer).
+
+### Changed
+- The installer is importable without side effects (the `isDirectRun` guard) and exports its
+  path/format helpers for in-process tests. The installer's own bare `npx … init` strings now use
+  `@latest`.
+
 ## 1.0.0
 
 First publish. The canonical home of the `agent-workflow` planning methodology is now an

package/README.md

@@ -3,16 +3,18 @@
 **The canonical home of the `agent-workflow` planning methodology.** It owns the
 methodology *text* — the Plan → Phase → Step vocabulary, the plan-file lifecycle
 (`docs/plans/*.md`, ephemeral, never committed), the `queue.md` series index, the mandatory
-final **Phase: Cleanup**, and the bounded methodology slot fragment the family kit injects
-into a deployed project's `AGENTS.md`.
+final **Phase: Cleanup**, the **orchestration-recipe** vocabulary (Solo / Reviewed / Council /
+Delegated), and the two bounded slot fragments the family kit injects into a deployed project's
+`AGENTS.md`.
 
 This is the **methodology engine** of the `agent-workflow` family — the canonical source the
 rest of the family builds on. It is **content**, not a runtime: it reads nothing, writes
 nothing, and mutates no project file. It deliberately **knows nobody else** in the family —
 it only *provides* the methodology; the family composition root (`agent-workflow-kit`) is the
-one that injects it. The kit currently consumes a **byte-identical, drift-guarded mirror** of
-this canon bundled inside the kit; the live `kit → engine` read (and retiring that mirror)
-lands in the next slice.
+one that injects it. The kit reads **this canon live from the installed engine** and injects the
+bounded slot from it — **one source of truth, no bundled mirror** (Plan 3D / AD-016).
+`npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a core part of the kit; if a
+slot fill is needed but the engine is absent, the kit's reconcile **fails loudly**.
 
 ## Install
 
@@ -40,13 +42,19 @@ the canonical methodology reference on disk:
   Plan → Phase → Step vocabulary, the plan-file lifecycle, the `queue.md` series index, the
   mandatory final **Phase: Cleanup**, and the plan-then-execute split.
 - [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded**
-  fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
+  methodology fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
   pointer, kept under the entry point's line cap).
+- [`references/orchestration.md`](references/orchestration.md) — the canonical **orchestration-recipe**
+  reference: the four recipes (Solo / Reviewed / Council / Delegated) over the bridges' role
+  vocabulary, the when/why, the graceful-degradation lattice, and the quota/health guard.
+- [`references/orchestration-slot.md`](references/orchestration-slot.md) — the **bounded** one-line
+  orchestration fragment the composition root injects into a deployed `AGENTS.md`, routing to the
+  in-project recipes surface.
 
 ## What this package ships
 
-`SKILL.md` (the canon overview + ownership rule), `references/` (the full methodology
-reference + the bounded slot fragment), `capability.json` (the family manifest), and this
+`SKILL.md` (the canon overview + ownership rule), `references/` (the full methodology + orchestration
+references + the two bounded slot fragments), `capability.json` (the family manifest), and this
 installer. It ships **no** family-wide tooling (the schema/validator/injection live in the
 composition root) and mutates nothing — preserving "knows nobody".
 

package/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: agent-workflow-engine
-description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, and the bounded methodology slot fragment. A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) currently keeps byte-identical mirror copies of this text (drift-guarded) and injects the slot from its mirror; the live kit → engine read + mirror retirement land in the next slice.
+description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, the bounded methodology slot fragment, and the orchestration-recipe vocabulary (Solo / Reviewed / Council / Delegated). A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) reads this canon LIVE from the installed engine and injects the bounded slots from it — one source of truth, no bundled mirror; `npx @sabaiway/agent-workflow-kit@latest init` installs the engine.
 disable-model-invocation: true
 metadata:
-  version: '1.0.0'
+  version: '1.2.0'
 ---
 
 # agent-workflow-engine
 
 The **canonical source of truth** for the `agent-workflow` planning methodology. It is a
 **published, installable npm package** (`capability.json` → `available:true`): it holds the
-methodology text and **provides** it, but it ships no runtime and mutates no files. The kit
-currently keeps **byte-identical mirror copies** of these files so the live injection + fallback
-keep working with no new dependency; a drift-guard test pins the mirrors to this canon. The live
-`kit → engine` read (and retiring the mirror) lands in the next slice.
+methodology text and **provides** it, but it ships no runtime and mutates no files. The kit reads
+**this canon live from the installed engine** (resolved via the family `detect.installed` pattern)
+and injects the bounded slot fragment from it — **one source of truth, no bundled mirror**.
+`npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a core part of the kit; when a
+slot fill is needed but the engine is absent, the kit's reconcile **fails loudly** (never silently).
 
 ## What it provides (`provides: ["plan"]`)
 
@@ -25,6 +26,14 @@ keep working with no new dependency; a drift-guard test pins the mirrors to this
   composition root injects into a deployed project's `AGENTS.md`, between the
   `<!-- workflow:methodology:start -->` / `<!-- workflow:methodology:end -->` markers. A short
   summary + pointer, not the full reference, so the entry point stays under its line cap.
+- [`references/orchestration.md`](references/orchestration.md) — the canonical **orchestration-recipe**
+  reference: the four recipes (Solo / Reviewed / Council / Delegated) defined over the bridges' role
+  vocabulary, the when/why decision guidance, the graceful-degradation lattice, and the quota/health
+  guard. The kit owns the executable dispatch and surfaces it as `/agent-workflow-kit recipes`.
+- [`references/orchestration-slot.md`](references/orchestration-slot.md) — the **bounded** one-line
+  orchestration fragment the composition root injects into a deployed `AGENTS.md`, between the
+  `<!-- workflow:orchestration:start -->` / `<!-- workflow:orchestration:end -->` markers. It names the
+  four recipes and routes to `/agent-workflow-kit recipes`, never to this engine-internal reference.
 
 ## Ownership rule (the engine knows nobody)
 
@@ -36,9 +45,8 @@ no outbound edges.
 ## Status & roadmap
 
 The engine is **no longer a stub**: it is a published, `available:true`, installable npm package
-(`@sabaiway/agent-workflow-engine`). The kit currently keeps **byte-identical mirror copies** of
-this canon (drift-guarded), so the live injection + fallback keep working with no new dependency.
-The live `kit → engine` read (the kit reading this canon from the installed engine instead of its
-bundled mirror) and **retiring that mirror** land in the next slice. See the kit's
-`tools/inject-methodology.mjs` for the marker contract and the slot reconciliation the kit runs on
-bootstrap + upgrade.
+(`@sabaiway/agent-workflow-engine`). The kit reads **this canon live from the installed engine** and
+injects the methodology slot from it — the old bundled mirror is **retired** (Plan 3D / AD-016):
+**one source of truth**. `npx @sabaiway/agent-workflow-kit@latest init` installs the engine as a core
+part of the kit. See the kit's `tools/inject-methodology.mjs` (the marker contract + slot
+reconciliation) and `tools/engine-source.mjs` (the live read + fail-loud resolver).

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // One-shot installer for @sabaiway/agent-workflow-engine.
 //
-//   npx @sabaiway/agent-workflow-engine init
+//   npx @sabaiway/agent-workflow-engine@latest init
 //
 // Copies the methodology canon into the canonical skill home
 // (~/.claude/skills/agent-workflow-engine, override with --dir or
@@ -17,7 +17,7 @@
 // No telemetry, no phone-home. Dependency-free, Node >= 18.
 
 import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -37,7 +37,11 @@ const PAYLOAD = [
   'references',
 ];
 
-const tildify = (path) => path.replace(homedir(), '~');
+// Collapse only a LEADING homedir() to "~" — anchored at the string start (boundary-checked with
+// `sep`), never a mid-path occurrence. A naive `path.replace(homedir(), '~')` would rewrite the
+// first match anywhere in the path (Issue-004). Exported so the regression can pin it in-process.
+export const tildify = (path) =>
+  path === homedir() ? '~' : path.startsWith(homedir() + sep) ? `~${path.slice(homedir().length)}` : path;
 
 const readVersion = async () => {
   try {
@@ -48,6 +52,54 @@ const readVersion = async () => {
   }
 };
 
+// Never-downgrade gate helpers (D3 / AD-012) — cloned from the kit installer so a bare `npx … init`
+// serving an OLDER cached build cannot overwrite a NEWER installed canon. Dependency-free semver:
+// parse the leading x.y.z (prerelease/build ignored). compareSemver → -1 | 0 | 1, or null when
+// either side is unparseable (a legacy install predating any stamp → no gate).
+const parseSemver = (str) => {
+  const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+
+const compareSemver = (a, b) => {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  const firstDiff = [0, 1, 2].map((i) => (pa[i] === pb[i] ? 0 : pa[i] < pb[i] ? -1 : 1)).find((c) => c !== 0);
+  return firstDiff ?? 0;
+};
+
+// Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level or
+// deeper-nested decoy `version:` (mirrors the manifest validator + the kit installer). Pure walk.
+const metadataVersion = (frontmatter) => {
+  const lines = frontmatter.split(/\r?\n/);
+  const metaIdx = lines.findIndex((l) => /^metadata:[ \t]*$/.test(l));
+  if (metaIdx === -1) return null;
+  const after = lines.slice(metaIdx + 1);
+  const dedent = after.findIndex((l) => /^[^ \t]/.test(l)); // a column-0 line closes the metadata block
+  const block = dedent === -1 ? after : after.slice(0, dedent);
+  const baseIndent = block.length ? (block[0].match(/^[ \t]*/)?.[0] ?? '') : '';
+  const verLine = block.find((l) => l.startsWith(`${baseIndent}version:`));
+  return verLine?.match(/version:[ \t]*['"]?(\d+\.\d+\.\d+)['"]?/)?.[1] ?? null;
+};
+
+// The installed version is read from the target's SKILL.md frontmatter metadata.version (the engine's
+// detect.installed.file). Returns the semver string, or null when ABSENT / unstamped (legacy → no
+// gate). A SKILL.md that EXISTS but cannot be read is NOT swallowed as "legacy": fail closed (throw)
+// so the gate can never be silently bypassed (AGENTS.md: no silent failures).
+const readInstalledVersion = async (target) => {
+  const skill = resolve(target, 'SKILL.md');
+  if (!existsSync(skill)) return null; // absent → new/legacy install, nothing to compare
+  const text = await readFile(skill, 'utf8').catch((err) => {
+    throw new Error(
+      `[agent-workflow-engine] cannot read the installed SKILL.md (${tildify(skill)}): ${err.message}. ` +
+        `Refusing to install over an unreadable canon — fix permissions/contents or remove it, then re-run.`,
+    );
+  });
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return fm ? metadataVersion(fm[1]) : null;
+};
+
 // lstat without following symlinks; null when the path does not exist. Using lstat (not
 // existsSync, which FOLLOWS symlinks and so reports a *dangling* symlink as absent) is what
 // makes the guard below catch a dangling destination symlink too.
@@ -64,9 +116,12 @@ const lstatNoFollow = (path) => {
 // within `root`. Walks `root` plus each existing path component down to `dest`; if the
 // root, an intermediate dir, or the leaf is a symlink (including a dangling one), a copy
 // could escape the target — STOP rather than follow it. Also refuses a dest outside `root`.
-const assertContainedRealPath = (root, dest) => {
+export const assertContainedRealPath = (root, dest) => {
   const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
+  // A true escape is `..` exactly or a `..`-prefixed PATH SEGMENT (`../x`) — NOT any string starting
+  // with the two chars "..": a legitimately-contained child literally named `..foo` has rel `..foo`,
+  // which the old `rel.startsWith('..')` wrongly rejected (Issue-004).
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(`[agent-workflow-engine] refusing to write outside the target dir: ${dest}`);
   }
   if (lstatNoFollow(root)?.isSymbolicLink()) {
@@ -106,6 +161,7 @@ const parseArgs = (argv) => {
   return {
     help: argv.includes('--help') || argv.includes('-h'),
     version: argv.includes('--version') || argv.includes('-v'),
+    allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
   };
 };
@@ -120,13 +176,15 @@ const printHelp = (version) => {
   console.log(`agent-workflow-engine ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-engine init [--dir <path>]
+  npx @sabaiway/agent-workflow-engine@latest init [--dir <path>] [--allow-downgrade]
   npx @sabaiway/agent-workflow-engine --version
   npx @sabaiway/agent-workflow-engine --help
 
 Installs/refreshes the methodology canon at ~/.claude/skills/agent-workflow-engine
   (override with --dir <path> or AGENT_WORKFLOW_ENGINE_DIR). init is additive —
-  it never deletes your files and never writes through a symlink.
+  it never deletes your files and never writes through a symlink. If the installed
+  canon is newer than the version you ran, init refuses (no network — it compares the
+  version on disk) and points you at @latest; --allow-downgrade overrides that refusal.
 
 The engine is the methodology canon the family kit builds on — it is content, not a
 project deploy and not a model-invoked skill, so there is nothing to run inside an agent.
@@ -159,6 +217,26 @@ const main = async () => {
     console.error(`[agent-workflow-engine] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
     process.exit(1);
   }
+
+  // Stale-cache defenses (no network — version already on disk vs this runner). Read BEFORE any write
+  // so a refusal touches nothing. cmp is null on a legacy/unparseable install → no gate.
+  const installedVersion = wasPresent ? await readInstalledVersion(target) : null;
+  const cmp = installedVersion ? compareSemver(installedVersion, version) : null;
+
+  // Never-downgrade gate (D3 / AD-012): a bare `npx … init` can run an OLDER cached build, which
+  // would overwrite a NEWER installed canon with old text. Refuse loudly (nonzero) unless
+  // --allow-downgrade — surfacing the cache trap instead of silently regressing (no silent failures).
+  if (cmp === 1 && !args.allowDowngrade) {
+    console.error(
+      `[agent-workflow-engine] refusing to downgrade: the installed canon is v${installedVersion}, but ` +
+        `this runner is the OLDER v${version}.\n` +
+        `  This is the classic npx cache serving a stale build. To get the newest canon, bypass the cache:\n` +
+        `    npx @sabaiway/agent-workflow-engine@latest init\n` +
+        `  (or pass --allow-downgrade to overwrite the newer install with v${version} anyway).`,
+    );
+    process.exit(1);
+  }
+
   await mkdir(target, { recursive: true });
   await Promise.all(
     PAYLOAD.map((entry) => copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target)),
@@ -167,13 +245,38 @@ const main = async () => {
     `[agent-workflow-engine] ${wasPresent ? 'updated the canon to' : 'installed'} v${version} -> ${tildify(target)}`,
   );
 
+  // No-op re-run (same version) → almost always npx served a cached build; say so + point at @latest.
+  if (cmp === 0) {
+    console.log(
+      `[agent-workflow-engine] note: no version change — the canon was already v${version}. If you ` +
+        `expected an update, npx likely served a cached build; re-run bypassing the cache:\n` +
+        `    npx @sabaiway/agent-workflow-engine@latest init`,
+    );
+  }
+
   console.log(`
 This installed the methodology canon at ${tildify(target)}. The engine is content the
 family kit builds on — there is nothing to run inside an agent.
 To update it later, re-run:  npx @sabaiway/agent-workflow-engine@latest init`);
 };
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests can
+// import this module to unit-test its exported helpers with no side effects. Compare by REAL path:
+// npx invokes the bin through a node_modules/.bin symlink, so process.argv[1] is that symlink while
+// import.meta.url is the resolved real file — a raw string compare reads them as different and main()
+// never runs. realpathSync collapses the symlink so both sides match. (Same idiom as the kit.)
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-engine",
   "kind": "methodology-engine",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "available": true,
   "provides": ["plan"],
   "roles": {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-engine",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step vocabulary, plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/orchestration-slot.md

@@ -0,0 +1 @@
+> **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.

package/references/orchestration.md

@@ -0,0 +1,92 @@
+# Orchestration Recipes
+
+Canonical, on-demand reference for **how an orchestrating agent composes the optional
+execution-backends** (the family's subscription-CLI bridges) into the `plan → execute → review`
+flow. This is the *narrative* source of truth — the **vocabulary** (what each recipe is), the
+**when/why** (which to reach for), the **graceful-degradation lattice** (what happens when a backend
+is unavailable), and the **quota/health guard**. The kit (`agent-workflow-kit`) owns the *executable*
+dispatch (`tools/recipes.mjs` — `planRecipe` / `recommendRecipe`) and surfaces it read-only as
+`/agent-workflow-kit recipes`; the two representations are kept in lockstep by a recipe-name parity
+guard. For the plan lifecycle this composes with, see [`planning.md`](planning.md).
+
+---
+
+## 1. The role vocabulary recipes are built over
+
+A recipe is an **orchestration pattern**, not a runnable script. The **orchestrator** (the main
+agent) always owns the decisions, the edits it accepts, verification, and the **single commit** — a
+backend is **advisory or delegated, never autonomous, and never commits**.
+
+Each backend declares what it can do in its `capability.json` `provides` / `roles`:
+
+- **`codex-cli-bridge`** (`codex`) — `provides: ["execute", "review"]`. It can run a bounded
+  execution sub-task (`codex-exec`, output: a diff) and give an advisory review (`codex-review`,
+  modes `plan` / `code`).
+- **`antigravity-cli-bridge`** (`agy`) — `provides: ["review", "probe"]`. It can give an advisory
+  review and answer a bounded probe (both via `agy-run`).
+
+Both are **subscription** backends with a **finite quota** — spend deliberately.
+
+## 2. The four recipes
+
+| Recipe (id) | Pattern | Roles needed | Backends that satisfy it |
+|-------------|---------|--------------|--------------------------|
+| **Solo** (`solo`) | The orchestrator plans, executes, and self-reviews. No backend. | none | — (always available; the floor) |
+| **Reviewed** (`reviewed`) | The orchestrator executes; **one** backend reviews the result (advisory). | ≥1 backend providing `review` | `codex` and/or `agy` |
+| **Council** (`council`) | **Both** backends review independently; the orchestrator synthesizes the two opinions. | ≥2 backends providing `review` | `codex` **and** `agy` |
+| **Delegated** (`delegated`) | The orchestrator hands a **bounded** execution sub-task to a backend, then reviews the returned diff and commits. | ≥1 backend providing `execute` | `codex` only |
+
+## 3. When / why to reach for each (the decision vocabulary)
+
+- **Solo** — the default for small, self-contained, low-risk work where a second opinion would not
+  change the outcome: typos, one-line fixes, mechanical edits, doc tweaks. It is also the **floor**
+  every other recipe degrades to, so the flow never blocks on a backend.
+- **Reviewed** — the everyday choice when work carries real risk (a bug class, a security surface, a
+  non-obvious refactor) and an independent reviewer is worth one backend's quota. When **both**
+  backends can review, prefer **`codex`** (deterministic tie-break — `agy` carries a standing health
+  caveat, §5).
+- **Council** — for high-stakes or genuinely ambiguous decisions where two *diverse* opinions catch
+  what one would miss. It spends **two** backends' quota, so reserve it for changes that justify the
+  cost.
+- **Delegated** — when a bounded, well-specified sub-task can be handed off (parallelism, or to keep
+  the orchestrator's own context focused). Only `codex` provides `execute`. The orchestrator still
+  reviews the returned diff and owns the commit — delegation never bypasses the review or the gate.
+
+## 4. Graceful degradation (never silent)
+
+Availability is **pure file-presence**: a backend is dispatchable **iff its detector `readiness` is
+`ready`** — full stop. Every other readiness (`needs-skill` / `needs-cli` / `needs-credentials` /
+`degraded`) means *not dispatchable*, and the specific value is the human reason (not installed → run
+`/agent-workflow-kit setup`; CLI missing → install the CLI; credentials missing → log in; degraded →
+the wrapper is not on `PATH`). This is a claim about **set-up state only** — never about whether a
+backend's *service* is actually responsive.
+
+When a recipe's roles can't be satisfied, it **degrades to a weaker recipe with a stated reason** —
+always reported, never silently dropped:
+
+- **Council → Reviewed → Solo.** Only one of the two reviewers is `ready` → Reviewed with that one;
+  neither is `ready` → Solo.
+- **Delegated → Solo.** No backend provides `execute` and is `ready` → Solo, with the reason.
+- **Reviewed → Solo.** No backend provides `review` and is `ready` → Solo, with the reason.
+
+## 5. Quota & health guard (advisory)
+
+Backends are **subscription** services with **finite** quota. The orchestrator should: prefer the
+cheapest model that fits the task; not reach for a top-tier model by reflex; and remember that
+**Council spends two backends' quota** for one decision.
+
+A **standing health advisory** applies to `agy`: the Antigravity service can **stall on substantive
+prompts** (a long hang that returns nothing — an external service issue, not a setup problem;
+tracked as **Issue-001** in the kit's known issues). It is **invisible to file-presence detection**,
+so it is *not* a readiness signal — it is a static caveat attached whenever a recipe would use `agy`. While it lasts, **prefer `codex`** for substantive
+reviews (this is the Reviewed tie-break in §3). The recipe machinery **never runs a subscription
+CLI** to check — detection stays read-only.
+
+## 6. The orchestrator always commits
+
+No recipe makes a backend write to the repo or create a commit. The kit's `recipes` surface is
+**read-only** — it lists the recipes, plans one for the current environment, and recommends a
+default; it **never executes** a recipe and **never runs a subscription CLI**. The orchestrator
+executes the chosen recipe through the bridge skills, accepts or rejects every edit, runs the
+verification gate, and makes the **one** commit — exactly as the plan lifecycle (`planning.md`)
+requires.