@sabaiway/agent-workflow-kit 1.20.0 → 1.22.0

package/bridges/antigravity-cli-bridge/references/driving-agy.md

@@ -51,6 +51,41 @@ agy-run "Continue from the prior architecture critique; focus on test gaps." --
 Use conversation state only when it saves quota or preserves useful context. For auditable decisions,
 prefer self-contained prompts.
 
+## Review via `agy-review` (grounded second opinion)
+
+For a code / plan / diff review, drive the dedicated **`agy-review`** wrapper rather than hand-rolling a
+prompt for `agy-run`. It **mechanizes the grounded-review contract** (see
+[`review-prompt.md`](./review-prompt.md)) so grounding is the enforced default, not a per-call effort:
+
+```bash
+agy-review code  [--facts @facts.md] [--decided @decided.md] [--focus "…"] [extra focus…]
+agy-review plan  <plan-file> [--facts @f] [--decided @f] [--focus "…"]
+agy-review diff  <diff-file> [--facts @f] [--decided @f] [--focus "…"]
+agy-review --continue          [--decided @f] [--focus "…"]   # round-2 delta — no re-assembly
+agy-review --conversation <id> [--decided @f] [--focus "…"]
+```
+
+What it does for you, and what YOU must supply:
+
+- **It** assembles POSTURE + a model/cutoff GUARD + your facts + your already-decided list + your focus
+  + the artifact (in `code` mode, the **repo-complete** working-tree change set) + a strict output
+  SHAPE, then delegates execution to `agy-run` (so the hard timeout, the subscription invariant, and
+  the single-argv byte ceiling apply once).
+- **You** supply what a script can't generate: `--facts @file` (the **verified facts** the model must
+  review AGAINST — agy reads nothing by default, so without this it guesses), `--decided @file` (the
+  **anti-circling** list of things already handled — the round-2 payload), and `--focus`.
+- **Anti-circling round 2:** after folding round 1, iterate with `agy-review --continue --decided
+  @round1-decisions.md --focus "only the still-open items"`. The continuation sends a small DELTA
+  (restated posture + new focus + the output shape + the decided list) and never re-sends the artifact
+  — `agy` holds it in the conversation.
+- **Oversized `code` review:** the byte ceiling (`AGY_MAX_PROMPT_BYTES`, default 120000) trips with
+  trim/split guidance. `AGY_REVIEW_ALLOW_ADDDIR=1` offloads ONLY the change set to a private staging
+  dir and passes it via `--add-dir` (the grounding stays inline) — this re-enables the Issue-001 stall
+  risk, bounded by the hard timeout; prefer splitting into focused per-area reviews.
+- **Model:** frontier default `Gemini 3.1 Pro (High)`; any model is allowed (a sub-frontier one earns a
+  silenceable `AGY_PROBE=1` advisory). The service can still **stall on large/substantive prompts**
+  (Issue-001) — keep reviews **focused**; the hard timeout is the guard.
+
 ## Escalation policy (edits, network, git)
 
 The wrapper passes no `--add-dir`, no `--dangerously-skip-permissions`, and no `--sandbox`. Treat this
@@ -70,7 +105,8 @@ rewrite history. Return findings and suggested changes only.
 
 ## Project-context prompts
 
-Probe reachability from a project root (cheap model):
+Probe **reachability** from a project root (cheap model) — this is the one place `agy` reading its cwd
+context file is the point of the prompt:
 
 ```bash
 AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
@@ -79,24 +115,12 @@ AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
   "Without using a file pointer, is there a project-specific planning skill in this repo? Name it and cite its path."
 ```
 
-Plan-review prompt shape:
-
-```text
-You are reviewing the plan below from the current repository root.
-Use the root context file and per-workspace skills if they are reachable.
-Do not edit files. Do not run git write commands.
-Return: 1) blocking issues  2) non-blocking risks  3) missing verification  4) a concise recommendation.
-The implementation plan text follows in this same prompt.
-```
-
-Diff/code-review prompt shape (provide the diff as text):
-
-```text
-Review this diff against the stated constraints.
-Focus on bugs, behavioural regressions, missing tests, and violations of the project rules.
-Cite file paths and line hints from the diff where possible. Do not summarise unless there are no findings.
-The project constraints and diff text follow in this same prompt.
-```
+**For an actual review, do NOT hand-roll a prompt that tells `agy` to "use the root context file if
+reachable"** — that is the documented root cause of guessing (`agy` cannot reliably read the repo code
+or the diff without an explicit `--add-dir`). Use **`agy-review`** (above): it makes the review
+**self-contained via `--facts`** plus the assembled artifact, so the review never *depends* on `agy`
+reading anything. `agy` may still surface the single cwd context file, but the grounded contract does
+not rely on it.
 
 ## Handling output
 

package/bridges/antigravity-cli-bridge/references/models-and-flags.md

@@ -1,13 +1,13 @@
 # `agy` models & flags (reference)
 
 The source of truth is the live binary: `agy --version`, `agy --help`, `agy models`. The tables below
-were captured from **v1.0.10**; if the binary disagrees, the binary wins. The wrapper command is
+were captured from **v1.0.13**; if the binary disagrees, the binary wins. The wrapper command is
 `agy-run`, backed by `bin/agy.sh`.
 
 ## Headless behaviour
 
 Use `-p`, `--print`, or `--prompt` to run one non-interactive prompt and print the text response. The
-wrapper always uses headless `-p`. **There is no JSON output mode in v1.0.10** — ask for Markdown,
+wrapper always uses headless `-p`. **There is no JSON output mode in v1.0.13** — ask for Markdown,
 bullets, tables, or fenced blocks when the caller needs structure, then validate the text yourself.
 
 ## Wrapper contract
@@ -32,11 +32,38 @@ Environment:
 |---|---|---|
 | `AGY_MODEL` | `Gemini 3.1 Pro (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
 | `AGY_TIMEOUT` | `5m` | value passed to `--print-timeout` |
+| `AGY_HARD_TIMEOUT` | `= AGY_TIMEOUT` | hard `timeout(1)` wall-clock cap (a duration string) |
+| `AGY_MAX_PROMPT_BYTES` | `120000` | single-argv byte ceiling. `agy` takes the prompt as ONE `-p` argv; past `MAX_ARG_STRLEN` (~131072) `execve` fails with a cryptic `Argument list too long`. The wrapper measures the resolved `-`/`@file` prompt and fails loud over the ceiling. A huge **literal** `agy-run "<huge>"` fails at the wrapper's own `exec`, so route large prompts via `-`/`@file`. |
 
 Subscription invariant: the wrapper prepends `$HOME/.local/bin` to `PATH` and clears
 `ANTIGRAVITY_API_KEY` / `GEMINI_API_KEY` / `GOOGLE_API_KEY` / `GOOGLE_GENAI_API_KEY` before execution.
 Auth comes from the user's cached OAuth token, never from bundled credentials.
 
+## `agy-review` contract (review role)
+
+For a code / plan / diff review, drive **`agy-review`** (backed by `bin/agy-review.sh`) instead of
+hand-rolling an `agy-run` prompt. It mechanizes the **grounded-review contract** (see
+[`review-prompt.md`](./review-prompt.md)) and delegates execution to `agy-run`, so the timeout, the
+subscription invariant, and the byte ceiling all apply once. The playbook is in
+[`driving-agy.md`](./driving-agy.md); the surface:
+
+```bash
+agy-review code|plan <file>|diff <file> [--facts @f] [--decided @f] [--focus "…"]
+agy-review --continue | --conversation <id>   [--decided @f] [--focus "…"]   # round-2 delta
+```
+
+| Var | Default | Effect |
+|---|---|---|
+| `AGY_MODEL` | `Gemini 3.1 Pro (High)` | frontier default; **any** model is allowed — a sub-frontier one earns a silenceable advisory (quality-first, not a gate) |
+| `AGY_PROBE` | `0` | `1` silences the off-frontier model advisory (throwaway probe) |
+| `AGY_REVIEW_ALLOW_ADDDIR` | `0` | `1` lets an oversized `code` review offload ONLY the change set to a private staging dir via `--add-dir` (the grounding stays inline; re-enables the Issue-001 stall risk — prefer splitting into focused reviews) |
+| `AGY_HARD_TIMEOUT` | `30m` | the review's hard cap (longer default than a probe — reviews are slower) |
+| `AGY_MAX_PROMPT_BYTES` | `120000` | the same single-argv byte ceiling; oversized → trim/split (or the `--add-dir` escape above) |
+
+`agy-review` is **read-only** and **advisory**: it never edits, commits, or passes a stray `--`
+passthrough (it owns the posture). The service can still **stall on large/substantive prompts**
+(Issue-001) regardless of `--add-dir`, so keep reviews **focused**; the hard timeout is the guard.
+
 ## Models
 
 Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
@@ -59,7 +86,7 @@ AGY_MODEL="Gemini 3.5 Flash (Medium)" agy-run "Read AGENTS.md and report one Har
 AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.md
 ```
 
-## Flags (from `agy --help`, v1.0.10)
+## Flags (from `agy --help`, v1.0.13)
 
 | Flag | Meaning | Notes |
 |---|---|---|
@@ -74,11 +101,11 @@ AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.
 | `--sandbox` | run with terminal restrictions enabled | prefer when delegating a prompt that might trigger tool/terminal work |
 | `--log-file <path>` | override the CLI log-file path | keep logs secret-free and out of committed artifacts |
 
-## Subcommands (v1.0.10)
+## Subcommands (v1.0.13)
 
 `changelog`, `help`, `install`, `models`, `plugin` / `plugins`, `update`.
 
-**Not available in v1.0.10:** any JSON output mode, and any `agy inspect`. Output is plain text.
+**Not available in v1.0.13:** any JSON output mode, and any `agy inspect`. Output is plain text.
 
 ## Project-context flags
 
@@ -91,3 +118,7 @@ AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.
 
 Use `--add-dir` for extra directories not already reachable from cwd. Subdirectory `CLAUDE.md` files
 are **not** auto-loaded — include those local rules manually in the prompt when they matter.
+
+This is **reachability only** — `agy` may *surface* the single cwd context file, but it does **not**
+read your repo code or a diff without an explicit `--add-dir`. So a **review must be self-contained**:
+ground it with `agy-review --facts @file` (above), never by relying on `agy` to read the change set.

package/bridges/antigravity-cli-bridge/references/review-prompt.md

@@ -1,51 +1,59 @@
-# Review prompt template — `agy-run` (review role)
+# Grounded review contract — `agy-review` (review role)
 
 The `review` role of `antigravity-cli-bridge` delegates a **read-only second opinion** to `agy`.
-`agy` cannot see the conversation and (in v1.0.10) has no JSON output, so the prompt must be
-**self-contained** and ask for **plain-Markdown findings only** — no repo edits, no git writes.
-Fill the `{{…}}` slots, pipe it to `agy-run`, then verify every finding locally before acting.
+`agy` reads **nothing** by default and its training predates the current codebase, so an *ungrounded*
+review **guesses** — stale-model false positives ("that model can't exist") and partial-diff false
+positives ("the bridge code is missing"). The fix is the **agy analog of codex's precomputed diff**:
+feed `agy` a **self-contained** prompt of **verified facts** plus the **full artifact**, and forbid it
+from opining on model names / its own cutoff.
+
+> **This file is a STATIC, human-readable reference of the assembled contract — NOT a dynamically
+> rendered template.** `bin/agy-review.sh` assembles the prompt **in code**; the `{{…}}` below are
+> documentation placeholders, not runtime substitutions. The **wrapper is the executable source of
+> truth** — if it disagrees with this file, the wrapper wins (no drift). Drive it through `agy-review`
+> (see [`driving-agy.md`](./driving-agy.md)), supplying `--facts` / `--decided` / `--focus`.
+
+## Assembled prompt shape (byte-stable order)
 
 ```text
-You are a meticulous staff-level reviewer giving a SECOND OPINION. You are read-only:
-do not propose to edit files, run commands, or make git changes — return findings only.
+POSTURE  You are a meticulous staff-level engineer giving a read-only SECOND OPINION. Read-only:
+         do NOT propose edits, run commands, or make git changes — findings ONLY, advisory.
+
+GUARD    Do NOT comment on AI model names/versions or your own knowledge cutoff — irrelevant here
+         and a known source of false positives. Review ONLY the engineering, AGAINST the facts.
 
-## What to review
-{{TARGET}}   # e.g. "the implementation plan below" or "the working-tree diff below"
+## Grounded facts — review AGAINST these, do NOT guess the code
+{{GROUNDED_FACTS}}   # from --facts @file (omitted -> an in-band note + a LOUD stderr warning)
 
-## Project rules
-Read the repo's root AGENTS.md (your cwd) and obey its Hard Constraints and conventions.
-If AGENTS.md declares a verification/gate set, judge the change against it; if it declares
-none, say so — do NOT invent checks.
+## Decisions already made / already addressed — do NOT re-raise these
+{{ALREADY_DECIDED}}  # from --decided @file (optional — the anti-circling lever; the round-2 payload)
 
-## Material
-{{CONTENT}}  # paste the plan text, or the unified diff, or the file excerpts under review
+## Focus
+{{FOCUS}}            # from --focus "…" + any trailing focus words, merged in parse order (optional)
 
-## Focus (optional)
-{{FOCUS}}    # e.g. "correctness of the new reducer", "backward-compat of the stamp takeover"
+## The change set / plan / diff under review
+{{ARTIFACT}}         # code: the assembled, repo-complete working-tree change set (or, when oversized
+                     #   with AGY_REVIEW_ALLOW_ADDDIR=1, a private --add-dir staging file)
+                     # plan/diff: the supplied file, inlined
 
 ## Output — Markdown, this exact shape, nothing else
 ### Verdict
 One line: SHIP / SHIP WITH NITS / REWORK, plus a one-sentence reason.
 ### Blocking
-Numbered. Correctness bugs, contract violations, data loss, security. Cite file:line.
-Empty? write "none".
+Numbered. Correctness bugs, contract violations, data loss, security. Cite file:line. Empty? "none".
 ### Non-blocking
-Numbered. Simplifications, reuse, naming, missing tests. Cite file:line.
+Numbered. Simplifications, reuse, naming, missing tests. Cite file:line. Empty? "none".
 ### Questions
-Anything ambiguous that changes your verdict if answered.
+Anything ambiguous that would change your verdict if answered.
 ```
 
-## Usage
+## Why no "read the repo's AGENTS.md" instruction
 
-```bash
-# critique a plan
-AGY_MODEL="Gemini 3.1 Pro (High)" agy-run @/tmp/review-prompt.filled.md
-
-# critique the current diff (build the prompt with the diff pasted into {{CONTENT}})
-git diff | ...  # assemble the filled prompt, then:
-agy-run @/tmp/review-prompt.filled.md
-```
+Earlier versions told `agy` to *read the repo's root `AGENTS.md` (your cwd)*. That was the documented
+root cause of guessing: `agy` cannot reliably read repo code or the diff without an explicit
+`--add-dir`, so a review that **depends** on it silently reviews half a picture. The grounded contract
+removes that dependency — everything the model needs is **in the prompt** (`--facts` + the artifact).
+`agy` may still *surface* the single cwd context file, but a review must never **rely** on it.
 
-Treat the result as **advisory** — `agy` output may be incomplete or out of date. The orchestrator
-re-runs the project's real gates and owns every accepted change. See
-[`driving-agy.md`](./driving-agy.md).
+Treat the result as **advisory** — re-run the project's real gates and verify every finding locally
+before acting.

package/bridges/antigravity-cli-bridge/setup/README.md

@@ -9,7 +9,7 @@ works in any project.
 ```bash
 curl -fsSL https://antigravity.google/cli/install.sh | bash
 export PATH="$HOME/.local/bin:$PATH"   # add to ~/.bashrc / ~/.zshrc to persist
-agy --version                          # expect 1.0.10 or newer
+agy --version                          # expect 1.0.13 or newer
 ```
 
 - The binary is **`agy`** (not `antigravity`); it installs to `~/.local/bin/agy`.
@@ -29,22 +29,27 @@ is **personal** — never copy, commit, package, print, or share that directory
 needs no API keys and must not be configured with API-key billing; the wrapper unsets every
 `*_API_KEY` so billing can never silently fall back to pay-as-you-go.
 
-## 3. Put the wrapper on `PATH` as `agy-run`
+## 3. Put the wrappers on `PATH` (`agy-run` + `agy-review`)
 
-The skill ships the wrapper at `bin/agy.sh`. Expose it on `PATH` under the stable name `agy-run`
-(idempotent; refuses to clobber a non-symlink):
+The skill ships **two** wrappers: `bin/agy.sh` (the `probe` role, exposed as `agy-run`) and
+`bin/agy-review.sh` (the grounded `review` role, exposed as `agy-review`). Expose **both** on `PATH`
+(idempotent; refuses to clobber a non-symlink). The kit's `setup-backends.mjs` does this automatically;
+by hand:
 
 ```bash
 mkdir -p "$HOME/.local/bin"
 skill_dir="$HOME/.claude/skills/antigravity-cli-bridge"   # adjust if installed elsewhere
-dst="$HOME/.local/bin/agy-run"
-if [ -e "$dst" ] && [ ! -L "$dst" ]; then
-  echo "STOP: $dst exists and is not a symlink"; exit 1
-fi
-chmod +x "$skill_dir/bin/agy.sh"
-ln -sfn "$skill_dir/bin/agy.sh" "$dst"
+for pair in "agy-run:bin/agy.sh" "agy-review:bin/agy-review.sh"; do
+  name="${pair%%:*}"; src="$skill_dir/${pair#*:}"
+  dst="$HOME/.local/bin/$name"
+  if [ -e "$dst" ] && [ ! -L "$dst" ]; then
+    echo "STOP: $dst exists and is not a symlink"; exit 1
+  fi
+  chmod +x "$src"
+  ln -sfn "$src" "$dst"
+done
 export PATH="$HOME/.local/bin:$PATH"
-command -v agy-run
+command -v agy-run agy-review
 ```
 
 ## 4. Smoke test
@@ -54,7 +59,7 @@ agy --version
 echo "say OK" | agy-run -
 ```
 
-Expected: the version prints (`1.0.10` or newer), then a short reply containing `OK`. If `agy-run`
+Expected: the version prints (`1.0.13` or newer), then a short reply containing `OK`. If `agy-run`
 reports `'agy' not found`, fix your `PATH` (step 1). If it asks you to sign in, complete step 2.
 
 ## Notes

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/templates/agent_rules.md

@@ -61,10 +61,17 @@ Before proposing changes or committing, review against:
 ### 2.4. Quality Gates
 - Always run type-checker, linter, and all tests before committing.
 
-### 2.5. Right-altitude & code-grounded (planning + review)
+### 2.5. Planning, review & process-fidelity invariants
+Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **Convergence heuristic.** When a review round keeps finding mechanism issues on a stable architecture, stop refining prose — raise the altitude or hand it to Execute. (Full canon: the project's planning methodology / workflow-methodology canon.)
+- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic is the trigger to write the test instead.
+- **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
+- **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
+- **Heavy review at the diff.** Plan-review settles architecture only (≤2 rounds, stop at the pre-existing→fold-induced crossover); the exhaustive per-Step review runs against real compiling code + the full suite, where a regression fails a gate immediately.
+- **Convergence bar.** A review loop is CLEAN only when one round returns **0 blockers + 0 majors** from EVERY backend the recipe names (nits + a ship verdict is the stop). Folding ≠ convergence — re-review after folding.
+- **Recipe fidelity.** Council runs every backend the recipe names, **every round**; silently dropping a ready backend for quota/convenience is a forbidden downgrade — an unavailable backend is a LOUD, stated degrade, never a quiet drop.
+- **ExitPlanMode ≠ execute.** A harness "approved — start coding" prompt authorizes the PLAN only; this methodology overrides it. Continue into execution only as a DELIBERATE transition after the plan + cold-start prompt exist, never an implicit slide.
 
 ---
 

package/tools/detect-backends.mjs

@@ -19,7 +19,7 @@
 // Pure, dependency-injectable (fs/env/validator are deps), dependency-free, Node >= 18. Every fs
 // probe is wrapped → an explicit `unknown` + reason, never a throw and never a nameless failure.
 
-import { existsSync, statSync, accessSync, realpathSync, readFileSync, constants } from 'node:fs';
+import { existsSync, statSync, accessSync, realpathSync, constants } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import os from 'node:os';
@@ -51,10 +51,13 @@ const EXPECTED_KIND = 'execution-backend';
 // The kit-owned registry: the per-backend facts the detector needs even when a bridge is NOT
 // installed (no manifest on disk to read). Kept in lockstep with the in-repo manifests by the
 // drift-guard test. `credential.env: null` → no env override exists (do not invent one).
+// `wrapperCmds` is the EXPECTED deduped roles[].cmd set the CURRENT kit bundles — readiness probes
+// THIS set (not the installed manifest's), so a stale install missing a wrapper surfaces DEGRADED.
 export const KNOWN_BACKENDS = [
   {
     name: 'codex-cli-bridge',
     installed: { env: 'CODEX_CLI_BRIDGE_DIR', default: '~/.claude/skills/codex-cli-bridge', file: 'SKILL.md' },
+    wrapperCmds: ['codex-exec', 'codex-review'],
     bin: 'codex',
     credential: { env: 'CODEX_HOME', default: '~/.codex', file: 'auth.json' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/codex-cli-bridge/setup/README.md',
@@ -66,6 +69,7 @@ export const KNOWN_BACKENDS = [
   {
     name: 'antigravity-cli-bridge',
     installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
+    wrapperCmds: ['agy-review', 'agy-run'],
     bin: 'agy',
     credential: { env: null, default: '~/.gemini/antigravity-cli', file: 'antigravity-oauth-token' },
     setupUrl: 'https://github.com/sabaiway/agent-workflow/blob/main/antigravity-cli-bridge/setup/README.md',
@@ -154,31 +158,6 @@ export const probeCredential = (entry, deps = {}) => {
   return { state: probeFile(file, deps), path: file };
 };
 
-const defaultReadManifest = (skillDir, deps = {}) => {
-  const read = deps.readFile ?? readFileSync;
-  try {
-    return JSON.parse(read(join(skillDir, 'capability.json'), 'utf8'));
-  } catch {
-    return null;
-  }
-};
-
-// The bridge's PATH wrapper names = the deduped `roles[].cmd` set (codex's review + execute roles
-// are two cmds; antigravity's review + probe roles share one `agy-run`).
-const wrapperCmds = (manifest) => {
-  const roles = manifest && typeof manifest.roles === 'object' && !Array.isArray(manifest.roles) ? manifest.roles : {};
-  const seen = new Set();
-  const out = [];
-  for (const role of Object.values(roles)) {
-    const cmd = role && typeof role.cmd === 'string' ? role.cmd : null;
-    if (cmd && !seen.has(cmd)) {
-      seen.add(cmd);
-      out.push(cmd);
-    }
-  }
-  return out;
-};
-
 const computeReadiness = (manifestState, cli, credentials, wrappers) => {
   if (manifestState !== OK) return NEEDS_SKILL;
   if (cli.state !== PRESENT) return NEEDS_CLI;
@@ -204,7 +183,6 @@ export const detectBackend = (entry, deps = {}) => {
       return { name: cmd, state: r.state };
     });
   const probeCredentialsFn = deps.probeCredentials ?? ((e) => probeCredential(e, deps));
-  const readManifest = deps.readManifest ?? ((dir) => defaultReadManifest(dir, deps));
 
   const resolvedDir = resolveDir({ env: entry.installed.env, default: entry.installed.default }, getenv, home);
   const markerPresent = probeFile(join(resolvedDir, entry.installed.file), deps) === PRESENT;
@@ -238,7 +216,10 @@ export const detectBackend = (entry, deps = {}) => {
 
   const cliProbe = probeCliFn(entry.bin);
   const credentials = probeCredentialsFn(entry);
-  const wrappers = isOk ? wrapperCmds(readManifest(resolvedDir)).map(probeWrapperFn) : [];
+  // Probe the EXPECTED wrapper set the kit bundles (entry.wrapperCmds), NOT the installed manifest's
+  // roles — so a STALE install missing a newer wrapper (e.g. agy-review on a v1.0.0 antigravity) is
+  // reported DEGRADED rather than a false "ready N/N". Keeps detectBackend pure (reads only its args).
+  const wrappers = isOk ? (entry.wrapperCmds ?? []).map(probeWrapperFn) : [];
   const readiness = computeReadiness(manifestState, cliProbe, credentials, wrappers);
 
   const installed = manifestState !== NOT_INSTALLED;

package/tools/family-members.mjs

@@ -57,7 +57,8 @@ export const FAMILY_MEMBERS = [
     installed: { env: 'ANTIGRAVITY_CLI_BRIDGE_DIR', default: '~/.claude/skills/antigravity-cli-bridge', file: 'SKILL.md' },
     deployed: null,
     npm: null,
-    wrapperCmds: ['agy-run'],
+    // review → agy-review, probe → agy-run (first-seen role order in capability.json; bridge 2.0.0).
+    wrapperCmds: ['agy-review', 'agy-run'],
   },
 ];
 

package/tools/recipes.mjs

@@ -46,11 +46,12 @@ export const BACKEND_META = {
   [AGY]: {
     cost: 'subscription',
     quota: { kind: 'subscription', finite: true },
-    health: 'Note: the Antigravity service may stall on substantive prompts (Issue-001) — prefer codex while it lasts.',
+    health: 'Note: grounded agy-review gives a SOUND second opinion (it removes the stale-model/partial-diff false positives) — but the Antigravity service can still stall on substantive prompts (Issue-001), so keep reviews focused and prefer codex for large or latency-sensitive ones.',
   },
 };
 
-// Deterministic tie-break order: codex before agy (agy carries the standing health caveat above).
+// Deterministic tie-break order: codex before agy. agy is a sound grounded reviewer now, but codex is
+// the more reliable default for substantive reviews (agy carries the standing service-stall caveat above).
 const BACKEND_PRIORITY = [CODEX, AGY];
 const priorityIndex = (name) => {
   const i = BACKEND_PRIORITY.indexOf(name);

package/tools/release-scan.mjs

@@ -20,6 +20,7 @@ export const ALLOWLIST = [
   'codex-review',
   'antigravity-cli-bridge',
   'agy-run',
+  'agy-review',
   'agent-workflow-kit',
   'agent-workflow-memory',
   'agent-workflow-engine',