@sabaiway/agent-workflow-kit 5.7.0 → 5.8.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 5.8.0 — the bundled agy bridge speaks the catalog the installed CLI actually serves, and grounding stops needing a shell (AD-095; antigravity-cli-bridge 5.2.0)
+
+**A model display string is matched exactly, so a stale one is not a documentation bug — it is a
+dispatch that refuses before it spends anything.** The bundled agy bridge had been describing a
+catalog captured from CLI v1.0.13 while the installed binary moved to 1.1.13. The user-facing
+catalog tables and every default pin now carry bytes read off `agy models` on the live binary,
+which also turned up a `Gemini 3.6 Flash` family no announcement mentioned and confirmed 3.5 Flash
+is still served. (The wrapper's own header comment stays a compact family inventory and now says
+so, pointing at `agy models` for the exact strings.)
+
+- **`Gemini 3.7 Flash (High)` is the bridge default for both roles** — `agy-run` and `agy-review` —
+  and joins the review wrapper's frontier set, so a council review on it stays advisory-silent.
+  Asserting frontier grade for the review lane was the maintainer's explicit call, not a default
+  that drifted. Any model remains selectable through `AGY_MODEL`; the sub-frontier advisory is
+  still a silenceable warning, never a gate.
+- **The catalog lists every served row individually.** The 3.6 and 3.5 families are enumerated
+  Low/Medium/High rather than collapsed into `(Low|Medium|High)` — a collapsed row reads as a
+  display string that does not exist, and pasting it fails.
+- **The reference stops overclaiming the wrapper's output.** v1.1.13 adds `--output-format
+  json|stream-json`, `--json-schema`, `--effort` and `--mode`; the wrapper adopts none of them, so
+  the docs now say text-DEFAULT and state plainly that raw passthrough JSON rides without
+  first-class parsing or validation. The old "no JSON output mode" sentence had become false.
+- **`grounding.mjs --extra <text|@file>` merges orchestrator facts inside the tool.** Appending
+  live judgment facts to an emitted facts payload had been a shell append four times running; it is
+  now an input. Extras append byte-verbatim after the mechanical sections. The read surface is
+  deliberately narrow and fail-closed: an `@file` must sit inside a PROVEN work tree (a successful
+  `git rev-parse --show-toplevel` — never a `cwd` fallback) or the system temp surface, never
+  inside the git dir including a linked worktree's `.git` gitfile, and it is read through the kit's
+  no-follow descriptor door so a FIFO cannot block the assembler and a symlink leaf cannot
+  substitute its target. Git location variables (`GIT_DIR`, `GIT_WORK_TREE`, …) are scrubbed before
+  every git query, so an ambient override cannot prove a foreign tree.
+
 ## 5.7.0 — what the kit emits is now something a test executed, a claim it proved, or a command you can run (AD-092 + AD-093 + AD-094; memory 4.3.0)
 
 **Three feedback plans, one release.** A live upgrade session on a deployed TypeScript project

package/README.md

@@ -237,7 +237,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<recipe>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend, never commits**; hand-editing stays fully supported. |
 | `/agent-workflow-kit review-state` | any time | **read-only review-receipt checker** — makes "reviewed ≠ shipped" detectable: the bridge review wrappers append a receipt per successful review (into a file inside the git dir — never committable); this checks that every backend your configured `plan-execution.review` recipe names holds a **fresh, grounded receipt for the current uncommitted tree** (any later edit moves the fingerprint and stales the receipt; a review continuation never re-attests a folded tree). `--check` gives a gate exit code to declare in `docs/ai/gates.json` **by hand or via the consent-gated seeder** (preview → your explicit yes; never without consent). `--await [--timeout <s>]` (AD-049) BLOCKS until every recipe-named backend has receipted the current tree — the durable completion signal is the receipt, never a process event — so you wait for the bridges instead of hand-polling. Never writes, never commits, never runs a subscription CLI; it spawns read-only `git` queries to fingerprint the tree — and `git commit --no-verify` stays possible (discipline, not a sandbox). |
 | `/agent-workflow-kit sandbox-masks` | any time | **cosmetic exclude lane for sandbox device masks** — an OS sandbox (Claude Code) injects character-device masks into the work tree as untracked `git status` noise; the review domain already ignores them **by construction** (never-committable untracked classes — char/block devices, FIFOs, sockets — are excluded from the fingerprint, the assembled review payload, and the clean checks). This mode hides them from `git status` too: flagless = read-only probe (derives the CURRENT mask set from the unfiltered walk + lstat — never a frozen list — and revalidates fenced entries, loudly flagging one that became a real path); `--apply` = consent-gated FULL-BLOCK replace of its own fenced block in `git rev-parse --git-path info/exclude` (stale masks drop by construction; `--clear` always means REMOVE the block — it takes precedence over the derivation). Writes ONLY its fence — never `.gitignore`, never global config; symlinked/non-regular exclude paths and malformed fences fail closed. Watch note: a real file at an excluded path is silently skipped by bulk staging (`git add -A`/`git add .`) — delete the stale line first; the probe flags exactly this case. |
-| `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. `--autonomy` (AD-044) appends the COMPUTED effective autonomy policy from the git-top `docs/ai/autonomy.json` (every red-line + per-activity level, stated source line; absent file → the computed defaults ARE the policy, exit 0; a malformed policy fails CLOSED, exit 1). Prints to stdout; `--out` writes **one scratch file only** — system-temp outside the repo ($TMPDIR / /tmp, rewritable) or a **fresh** gitignored in-repo path (create-only, exclusive write; an existing in-repo file, even gitignored, is refused — the `.env` clobber class); tracked, not-ignored-in-repo, other outside-repo, and symlink/non-regular destinations are all refused. Never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit grounding` | any time | **grounded-review facts assembler** — mechanizes populating `agy-review --facts @f`: slices your entry-point's **Hard Constraints** section verbatim (exactly one match, else a loud stop) and/or a plan's decision-bearing sections (`## Approach` + `## Verification` required, `## Decisions (locked)` when present; duplicates stop), under the same byte budget the agy wrapper enforces (minus `--reserve-bytes` for the artifact share), with a loud tail-trim on overflow. `--autonomy` (AD-044) appends the COMPUTED effective autonomy policy from the git-top `docs/ai/autonomy.json` (every red-line + per-activity level, stated source line; absent file → the computed defaults ARE the policy, exit 0; a malformed policy fails CLOSED, exit 1). `--extra <text|@file>` (repeatable) appends your own facts **byte-verbatim** after the mechanical sections, so the merge is a tool input rather than a shell append — an `@file` must sit inside the proven git work tree (never the git dir) or the system temp surface, and is read through a no-follow descriptor (a FIFO cannot block it, a symlink leaf cannot substitute its target). Prints to stdout; `--out` writes **one scratch file only** — system-temp outside the repo ($TMPDIR / /tmp, rewritable) or a **fresh** gitignored in-repo path (create-only, exclusive write; an existing in-repo file, even gitignored, is refused — the `.env` clobber class); tracked, not-ignored-in-repo, other outside-repo, and symlink/non-regular destinations are all refused. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit core-evidence` | any time | **the ONE loop-evidence writer** (strip-the-kit) — every core evidence record lands in a single append-only JSONL store inside the git dir (never committable; versioned schema, latest-per-key supersession, byte-identical duplicates refused, malformed lines fail every reader closed). `red-proof "<file>#<pattern>"` declares an observed-red **BEFORE a bugfix** (N/N red runs + content custody + base + the pre-fix fingerprint; green/mixed/timeout are DISTINGUISHED refusals — nothing written); `degrade --backend --reason` is the ONLY escape for an unavailable review backend (per-tree, never all backends); `summary` renders the whole loop state statelessly (gate result · per-backend verdicts · red-proofs · degrades) — no ledger, no rounds, nothing remembered. Honest residual: records are forgeable — self-discipline, not a security boundary. Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit coverage-check` | any time | **the final-run checker** (D3(c)+(d)) — **certifies coverage ONLY inside the `--final` run that owns the lcov** (ownership is exclusive by CONVENTION over the fixed path, not enforced — a concurrent writer to it is a stated residual, queued as LCOV-EXCLUSIVE-OWNERSHIP): an artifact on disk proves nothing about the tree it came from, so a standalone run prints its findings and states `attested=no` / `NO VERDICT` rather than a PASS (an lcov that predates an edit would otherwise certify a line the suite never executed). `attested=` claims a verdict was ISSUED, pass or fail — a run over uncovered lines still reads `attested=yes` and still exits 1, and a run whose coverage arm never executed (no lcov) reads `attested=no` even inside `--final`, because nothing was read and nothing is certified. The runner passes a nonce whose one-way commitment over `{nonce, fingerprint, base}` is the `final-start.attempt` it recorded; a context describing another tree, or matching no recorded attempt, is a REFUSAL, never a verdict. Findings are unchanged — reads the lcov the declared `unit-tests` gate produced at the FIXED git-dir path and fails on any uncovered CHANGED executable Node line (listed `file:line`; a changed file absent from the map is a file-level red; out-of-domain/unsupported files are LISTED — the claim narrowed honestly); VERIFIES every current-base red-proof declaration (bound test exists · custody hash unchanged · green N/N now · pre-fix fingerprint differs); prints `lcov-sha256=<hex|none>` of the exact bytes it consumed — the sha the `--final` receipt binds and re-hashes. An absent lcov is a LOUD `skipped-no-lcov`; a symlinked path is a refusal. `--check` is the gate exit code — declare it as the LAST gate (`run-gates --final` refuses otherwise). Read-only. |
 | `/agent-workflow-kit commit-guard` | any time | **the read-only pre-commit guard** (D10) — makes the commit capture the whole current working tree, so «verified» and «about to be committed» are the same bytes (the receipt itself has a stated residual — see the mode doc). FIRST it refuses an **INDEX that lags the verified working tree** (the gates and the fingerprint describe the WORKING tree while `git commit` takes the INDEX alone, and the fingerprint cannot tell them apart — so a lagging index used to ship a strict subset of what was verified): unstaged tracked paths or reviewable untracked-not-ignored paths, named up to a bounded cap with the remainder stated, a dirty tracked **submodule** named separately with its own recovery, and fail-closed on an undecidable probe. This deliberately blocks a partial commit. Then it binds the LATEST completed `run-gates --final` receipt to the EXACT current tree: refuses on a missing/red/stale receipt, fingerprint drift under the run, a dangling later attempt, declaration content drift, evidence-hash or lcov drift, or unsatisfied review obligations (the same review-state decision, recomputed over a sanitized env — forged out-of-repo stores never satisfy). Re-runs NO gate or test. Wire it into `.git/hooks/pre-commit` (the installer writes the RESOLVED invocation). `git commit --no-verify` stays the stated residual. |

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '5.7.0'
+  version: '5.8.0'
 ---
 
 # agent-workflow-kit

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: antigravity-cli-bridge
-description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
+description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its headless behaviour.
 metadata:
-  version: '5.1.1'
+  version: '5.2.0'
 ---
 
 # antigravity-cli-bridge
@@ -53,16 +53,22 @@ keep probes short (see *How the main agent drives agy*).
 ## Models
 
 Pass the **exact display string** to `--model` (or set `AGY_MODEL`). The wrapper defaults to
-`Gemini 3.1 Pro (High)`. Run `agy models` for the live list — if it differs from this table, the live
-list wins.
+`Gemini 3.7 Flash (High)`. Run `agy models` for the live list — if it differs from this table, the
+live list wins.
 
 | Model string | Use it for |
 |---|---|
-| `Gemini 3.5 Flash (Low)` | cheapest; reachability checks, smoke tests, simple transforms |
-| `Gemini 3.5 Flash (Medium)` | cheap probes, context-reachability checks, quick summaries |
-| `Gemini 3.5 Flash (High)` | fast drafting / review when a little more effort helps |
+| `Gemini 3.7 Flash (Low)` | cheapest; reachability checks, smoke tests, simple transforms |
+| `Gemini 3.7 Flash (Medium)` | cheap probes, context-reachability checks, quick summaries |
+| `Gemini 3.7 Flash (High)` | wrapper + review default; asserted frontier-grade (fork (a)) |
+| `Gemini 3.6 Flash (Low)` | previous Flash generation, still served — prefer 3.7 |
+| `Gemini 3.6 Flash (Medium)` | previous Flash generation, still served — prefer 3.7 |
+| `Gemini 3.6 Flash (High)` | previous Flash generation, still served — prefer 3.7 |
+| `Gemini 3.5 Flash (Low)` | older Flash generation, still served — prefer 3.7 |
+| `Gemini 3.5 Flash (Medium)` | older Flash generation, still served — prefer 3.7 |
+| `Gemini 3.5 Flash (High)` | older Flash generation, still served — prefer 3.7 |
 | `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
-| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `Gemini 3.1 Pro (High)` | hard reasoning, plan critique, architecture review (slower, deeper) |
 | `Claude Sonnet 4.6 (Thinking)` | a Claude second opinion through the same subscription |
 | `Claude Opus 4.6 (Thinking)` | strongest Claude reasoning available via `agy` |
 | `GPT-OSS 120B (Medium)` | an open-weights cross-check / diversity pass |
@@ -89,10 +95,12 @@ AGY_HARD_TIMEOUT=8m agy-run "..."             # hard wall-clock cap via timeout(
 agy-run "..." -- --add-dir .                  # passthrough agy flags (never a permission widener)
 ```
 
-`agy` is **headless-only** here (`-p`/`--print`) and there is **no JSON output mode** in v1.0.13 — you
-get plain text. If you need structure, ask for Markdown with explicit headings and validate it
+`agy` is **headless-only** here (`-p`/`--print`); v1.1.13 adds `--output-format json|stream-json`,
+and text stays the wrapper default — JSON can ride passthrough (`-- --output-format json`) but with
+no first-class parsing/validation (adoption is a backlog item). If you need structure, ask
+for Markdown with explicit headings and validate it
 yourself. Wrapper inputs: first argument is the prompt (`text`, `-` for stdin, or `@file`);
-`AGY_MODEL` (default `Gemini 3.1 Pro (High)`); `AGY_TIMEOUT` → `--print-timeout` (default `5m`);
+`AGY_MODEL` (default `Gemini 3.7 Flash (High)`); `AGY_TIMEOUT` → `--print-timeout` (default `5m`);
 `AGY_HARD_TIMEOUT` → hard `timeout(1)` wall-clock cap (default = `AGY_TIMEOUT`); extra `agy` flags
 after `--`. Full detail: [`references/models-and-flags.md`](references/models-and-flags.md).
 
@@ -154,7 +162,7 @@ release). `agy-review … --nonce <n>` is the plain-argument equivalent
 (one seam; flag and a non-empty env must agree, a disagreeing pair refuses pre-spend) — the lane
 for hosts whose dispatch policy has no env-prefix form.
 
-Frontier default `Gemini 3.1 Pro (High)`; **any** model is allowed (a sub-frontier one earns a
+Frontier default `Gemini 3.7 Flash (High)`; **any** model is allowed (a sub-frontier one earns a
 silenceable `AGY_PROBE=1` advisory). An oversized `code` review is **DELIVERED, not refused**: the
 change set is cut into under-cap parts, fed over continuation turns and reviewed in a final turn, and
 the answer must reproduce a line the wrapper picked from each part — a missing or wrong echo is a
@@ -190,9 +198,9 @@ without an explicit `--add-dir`, so ground a review **self-contained** via `agy-
 rather than relying on `agy` to read the change set. Re-runnable from a project root (use a cheap model):
 
 ```bash
-AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+AGY_MODEL="Gemini 3.7 Flash (Low)" agy-run \
   "Read the cwd context file and state the dialogue language plus one Hard Constraint, in two lines."
-AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+AGY_MODEL="Gemini 3.7 Flash (Low)" agy-run \
   "Without me pointing you at any file, name a project-specific skill under .agents/skills/ here and cite its path."
 ```
 
@@ -241,15 +249,16 @@ checklist, prompt templates, output handling). Essentials:
 - Subdirectory `CLAUDE.md` files are **not** auto-loaded by `agy` (only the cwd context file +
   `.agents/skills/`). Put cross-cutting rules in the root context file, or include local rules in the
   prompt when they matter.
-- **No JSON output** and **no `agy inspect`** in v1.0.13 — parse text; there is no machine-readable
-  introspection.
+- **Text is the wrapper default** — the CLI's 1.1.x `--output-format json|stream-json` can ride
+  passthrough but with no first-class parsing/validation (adoption is backlog) — and there is
+  **no `agy inspect`**: no machine-readable introspection.
 - Model names must match the `agy models` display strings **exactly**.
 - **Quota is finite.** Heavy use of Pro/Claude models can exhaust the subscription; prefer Flash for
   cheap work.
 - **A run can't hang forever.** The wrapper caps `agy` with `timeout(1)` (`AGY_HARD_TIMEOUT`,
   default = `AGY_TIMEOUT`) because `agy`'s own `--print-timeout` is **not** a reliable wall-clock
   kill (a run was seen surviving 32 min past a 10m `--print-timeout`). A heavy `--add-dir` agentic
-  prompt on the slowest model (`Gemini 3.1 Pro (High)`) can run unbounded — prefer a faster model or
+  prompt on a slow model (e.g. `Gemini 3.1 Pro (High)`) can run unbounded — prefer a faster model or
   a **self-contained prompt** (no `--add-dir`); an "exceeded the hard cap" error is the guard firing.
 - `agy` output is plain text and may be incomplete or out of date — treat it as advisory until the
   main agent verifies it.

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -35,7 +35,7 @@
 #   agy-review --conversation <id> [--decided @f] [--focus "…"]   # resume a specific conversation
 #
 # Environment (every optional var has an explicit default so a no-env run is safe under set -u):
-#   AGY_MODEL                default "Gemini 3.1 Pro (High)"; ANY model allowed (advisory warn off-frontier).
+#   AGY_MODEL                default "Gemini 3.7 Flash (High)"; ANY model allowed (advisory warn off-frontier).
 #                            Set empty (AGY_MODEL=) to drop --model and use agy's settings.json.
 #   AGY_HARD_TIMEOUT         default 30m  (duration string; the timeout(1) hard cap via agy-run)
 #   AGY_TIMEOUT              default = AGY_HARD_TIMEOUT (agy's soft --print-timeout)
@@ -322,11 +322,11 @@ aw_resolve_timeout_bin() {
   printf '%s' "$bin"
 }
 
-DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
+DEFAULT_AGY_REVIEW_MODEL="Gemini 3.7 Flash (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="5.1.1"  # aw-version-anchor
+AW_BRIDGE_VERSION="5.2.0"  # aw-version-anchor
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # D5 control-byte screen — IMMEDIATELY after resolution, BEFORE the off-frontier advisory (or any
@@ -335,8 +335,9 @@ if [[ "$AGY_MODEL" == *[$'\x01'-$'\x1f'$'\x7f']* ]]; then
   echo "error: AGY_MODEL contains control bytes — fix the setting (env or bridge-settings.conf) and re-run." >&2
   exit 2
 fi
-# Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable warning.
-FRONTIER_SET=("Gemini 3.1 Pro (High)" "Claude Opus 4.6 (Thinking)" "Claude Sonnet 4.6 (Thinking)")
+# Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable
+# warning. Gemini 3.7 Flash (High) is asserted frontier-grade (fork (a), maintainer 2026-08-14).
+FRONTIER_SET=("Gemini 3.7 Flash (High)" "Gemini 3.1 Pro (High)" "Claude Opus 4.6 (Thinking)" "Claude Sonnet 4.6 (Thinking)")
 
 # Duration-string timeouts (NOT codex's bare seconds): agy-run forwards a duration to --print-timeout,
 # and the timeout(1) hard cap is a duration too — never numerically compared, so 30m vs 2h is fine.

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -285,7 +285,16 @@ describe('agy-review.sh — model policy advisory (1)', () => {
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
     assert.doesNotMatch(r.stderr, /non-frontier model/);
-    assert.match(r.argv, /Gemini 3\.1 Pro \(High\)/, 'the frontier default reaches agy');
+    assert.match(r.argv, /Gemini 3\.7 Flash \(High\)/, 'the frontier default reaches agy');
+  });
+
+  it('an explicit Gemini 3.7 Flash (High) is FRONTIER — no advisory (fork (a), maintainer 2026-08-14)', () => {
+    const sb = makeSandbox();
+    const r = run(sb, { args: ['code', '--facts', 'a tiny fact'], env: { AGY_MODEL: 'Gemini 3.7 Flash (High)' } });
+    rmSync(sb.home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(r.stderr, /non-frontier model/, 'a FRONTIER_SET member never warns');
+    assert.match(r.argv, /Gemini 3\.7 Flash \(High\)/);
   });
 });
 
@@ -2444,8 +2453,8 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', () => {
     const receipts = readReceipts(sb.repo);
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /review posture: model=Gemini 3\.1 Pro \(High\)/, 'the banner states the actual run posture');
-    assert.deepEqual(receipts[0].posture, { model: 'Gemini 3.1 Pro (High)' }, 'banner ↔ receipt parity');
+    assert.match(r.stderr, /review posture: model=Gemini 3\.7 Flash \(High\)/, 'the banner states the actual run posture');
+    assert.deepEqual(receipts[0].posture, { model: 'Gemini 3.7 Flash (High)' }, 'banner ↔ receipt parity');
     assert.deepEqual(Object.keys(receipts[0]), Object.keys(RECEIPT_FIXTURE), 'fixture key set + order');
   });
 
@@ -2498,7 +2507,7 @@ describe('agy-review.sh — dispatch-posture labeling (D5)', () => {
     const receipts = readReceipts(sb.repo);
     rmSync(sb.home, { recursive: true, force: true });
     assert.equal(r.status, 0, r.stderr);
-    assert.match(r.stderr, /^review posture: model=Gemini 3\.1 Pro \(High\) timeout=30m$/m);
+    assert.match(r.stderr, /^review posture: model=Gemini 3\.7 Flash \(High\) timeout=30m$/m);
     assert.deepEqual(Object.keys(receipts[0].posture), ['model'], 'timeout never enters the receipt posture');
   });
 

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -17,7 +17,9 @@
 # policy (no plan contract, no auto-approve, no workspace edits) — that is left
 # to whatever flow we design later, which can opt in via passthrough flags.
 #
-# Models (pass the exact display string from `agy models`, or set AGY_MODEL):
+# Model families (compact inventory only; run `agy models` for exact display strings, then pass
+# one via AGY_MODEL):
+#   Gemini 3.7 Flash (Low|Medium|High), Gemini 3.6 Flash (Low|Medium|High),
 #   Gemini 3.5 Flash (Low|Medium|High), Gemini 3.1 Pro (Low|High),
 #   Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), GPT-OSS 120B (Medium)
 #
@@ -237,8 +239,9 @@ if ! command -v agy >/dev/null 2>&1; then
   exit 127
 fi
 
-# `-` (empty) => skip --model and let agy use settings.json; default to Pro.
-AGY_MODEL="${AGY_MODEL-Gemini 3.1 Pro (High)}"
+# `-` (empty) => skip --model and let agy use settings.json; default to Flash (High) — asserted
+# frontier-grade (fork (a), maintainer 2026-08-14).
+AGY_MODEL="${AGY_MODEL-Gemini 3.7 Flash (High)}"
 AGY_TIMEOUT="${AGY_TIMEOUT:-5m}"
 AGY_TIMEOUT="$(aw_effective_timeout AGY_TIMEOUT 5m)"
 # Hard wall-clock cap (defaults to AGY_TIMEOUT). agy's own --print-timeout is NOT a reliable
@@ -355,7 +358,7 @@ set -e
 if [[ $rc -eq 124 || $rc -eq 137 ]]; then
   echo "error: agy exceeded the hard cap AGY_HARD_TIMEOUT=$AGY_HARD_TIMEOUT and was terminated." >&2
   echo "       This usually means a heavy '--add-dir' agentic run, or the slowest model looping." >&2
-  echo "       Retry with a faster model (e.g. AGY_MODEL='Gemini 3.5 Flash (High)') or a" >&2
+  echo "       Retry with a faster model (e.g. AGY_MODEL='Gemini 3.7 Flash (Low)') or a" >&2
   echo "       self-contained prompt without --add-dir. Raise AGY_HARD_TIMEOUT only if the run is healthy." >&2
 fi
 exit $rc

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -447,6 +447,30 @@ describe('agy.sh — bridge settings file (bridges 2.3.0)', { concurrency: true
   });
 });
 
+// ── the wrapper's OWN default model (fork (a), round-1 council F3) ────────────────
+describe('agy.sh — default model pin', () => {
+  it('absent AGY_MODEL → the stub argv carries --model Gemini 3.7 Flash (High)', () => {
+    const home = makeSandbox(ARGV_STUB);
+    const argvFile = join(home, 'argv.txt');
+    const r = runWrapper(home, { AGY_STUB_ARGV: argvFile });
+    const argv = readFileSync(argvFile, 'utf8');
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(argv, /^--model$/m, 'the default run passes --model');
+    assert.match(argv, /^Gemini 3\.7 Flash \(High\)$/m, 'the wrapper default is the probed display string');
+  });
+
+  it("explicit AGY_MODEL='' drops --model entirely (settings.json takes over)", () => {
+    const home = makeSandbox(ARGV_STUB);
+    const argvFile = join(home, 'argv.txt');
+    const r = runWrapper(home, { AGY_MODEL: '', AGY_STUB_ARGV: argvFile });
+    const argv = readFileSync(argvFile, 'utf8');
+    rmSync(home, { recursive: true, force: true });
+    assert.equal(r.status, 0, r.stderr);
+    assert.doesNotMatch(argv, /^--model$/m, 'an explicit empty model never emits --model');
+  });
+});
+
 // ── settings surface ⟷ manifest (drift guard, D6) ────────────────────────────────
 // agy-run's --help stays candidate-C (not contract-pinned), but its SETTINGS surface
 // is manifest-pinned like the other three wrappers: the Settings help section and the

package/bridges/antigravity-cli-bridge/capability.json

@@ -3,9 +3,9 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "5.1.1",
+  "version": "5.2.0",
   "provides": ["review", "probe"],
-  "posture": { "model": "Gemini 3.1 Pro (High)" },
+  "posture": { "model": "Gemini 3.7 Flash (High)" },
   "roles": {
     "review": {
       "cmd": "agy-review",
@@ -180,7 +180,7 @@
       ],
       "guardrails": [
         { "value": "subscription-only — every *_API_KEY env var is unset before the run", "enforcement": "enforced", "source": "bin/agy.sh" },
-        { "value": "any model is selectable via AGY_MODEL; the default is Gemini 3.1 Pro (High)", "enforcement": "advisory", "source": "bin/agy.sh" },
+        { "value": "any model is selectable via AGY_MODEL; the default is Gemini 3.7 Flash (High)", "enforcement": "advisory", "source": "bin/agy.sh" },
         { "value": "hard wall-clock cap AGY_HARD_TIMEOUT (built-in default 5m)", "enforcement": "enforced", "condition": "only while timeout(1)/gtimeout is on PATH — otherwise the wrapper warns and runs uncapped", "source": "capability.json settings.AGY_HARD_TIMEOUT" },
         { "value": "the prompt rides a single argv — over AGY_MAX_PROMPT_BYTES (120000) the run refuses", "enforcement": "enforced", "source": "bin/agy.sh" },
         { "value": "no review posture, no grounding, no receipt — the reply is raw model output", "enforcement": "advisory", "source": "bin/agy.sh" }

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

@@ -18,13 +18,14 @@ edits, verification, and final judgment.
 
 | Task | Model |
 |---|---|
-| Reachability / smoke / "is it wired?" | `Gemini 3.5 Flash (Low)` |
-| Cheap probes, summaries | `Gemini 3.5 Flash (Medium)` |
-| Quick review with a little more effort | `Gemini 3.5 Flash (High)` |
-| Reasoning, plan critique, careful drafting | `Gemini 3.1 Pro (High)` (wrapper default) |
-| Same reasoning, lower quota cost | `Gemini 3.1 Pro (Low)` |
+| Reachability / smoke / "is it wired?" | `Gemini 3.7 Flash (Low)` |
+| Cheap probes, summaries | `Gemini 3.7 Flash (Medium)` |
+| Review, reasoning, careful drafting | `Gemini 3.7 Flash (High)` (wrapper default; asserted frontier-grade) |
+| Slower, deeper reasoning pass | `Gemini 3.1 Pro (High)` |
+| Same Pro reasoning, lower quota cost | `Gemini 3.1 Pro (Low)` |
 | A different engine's opinion | `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)` |
 
+The 3.6 / 3.5 Flash families remain served — prefer 3.7 (newest generation at the same tiers).
 Don't reach for Pro by reflex — Flash answers most reachability/probe questions for a fraction of the
 quota.
 
@@ -94,7 +95,7 @@ What it does for you, and what YOU must supply:
   `AGY_REVIEW_ALLOW_ADDDIR` is **RETIRED** (recognized, arms nothing): headless `agy` auto-denies its
   own `read_file`, so the offload it armed could return a confident fabrication with no way to tell.
   The kit never grants that permission — the feed exists so none is needed.
-- **Model:** frontier default `Gemini 3.1 Pro (High)`; any model is allowed (a sub-frontier one earns a
+- **Model:** frontier default `Gemini 3.7 Flash (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.
 - **Posture banner — quote it verbatim.** Every review states its ACTUAL posture on ONE stderr line
@@ -127,9 +128,9 @@ Probe **reachability** from a project root (cheap model) — this is the one pla
 context file is the point of the prompt:
 
 ```bash
-AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+AGY_MODEL="Gemini 3.7 Flash (Low)" agy-run \
   "Read the cwd context file and report the dialogue language plus one Hard Constraint."
-AGY_MODEL="Gemini 3.5 Flash (Low)" agy-run \
+AGY_MODEL="Gemini 3.7 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."
 ```
 

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

@@ -1,14 +1,18 @@
 # `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.13**; if the binary disagrees, the binary wins. The wrapper command is
+were captured from **v1.1.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.13** — ask for Markdown,
-bullets, tables, or fenced blocks when the caller needs structure, then validate the text yourself.
+wrapper always uses headless `-p`. v1.1.13 adds `--output-format text|json|stream-json` and
+`--json-schema` (structured output); **text stays the wrapper default** — raw passthrough
+(`agy-run "…" -- --output-format json`) is possible but rides with NO first-class parsing or schema
+validation (first-class adoption is a separate backlog item). When the caller needs structure
+through the wrapper, ask for Markdown, bullets, tables, or fenced blocks, then validate the text
+yourself.
 
 ## Wrapper contract
 
@@ -30,7 +34,7 @@ Environment:
 
 | Var | Default | Effect |
 |---|---|---|
-| `AGY_MODEL` | `Gemini 3.1 Pro (High)` | model display string; set empty (`AGY_MODEL=`) to drop `--model` and let `agy` use `settings.json` |
+| `AGY_MODEL` | `Gemini 3.7 Flash (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`. |
@@ -55,7 +59,7 @@ agy-review --continue | --conversation <id>   [--decided @f] [--focus "…"]   #
 
 | 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_MODEL` | `Gemini 3.7 Flash (High)` | frontier default (fork (a), 2026-08-14); **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 AND lets `code` run without `--facts` (an ungrounded probe never attests — its receipt is probe-marked) |
 | `AGY_REVIEW_MAX_TOTAL_BYTES` | `240000` | the ceiling on the SUM of all outgoing prompt bytes an oversized `code` review's chunked feed may send; checked BEFORE the first turn is spent |
 | `AGY_REVIEW_ALLOW_ADDDIR` | `0` | **RETIRED** — recognized so an existing settings line never warns as unknown, but it arms nothing. An oversized `code` review is a chunked feed with a per-part delivery proof; the `--add-dir` offload it armed could not be verified (headless `agy` auto-denies `read_file`) |
@@ -72,11 +76,17 @@ Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
 
 | Model string | Practical use |
 |---|---|
-| `Gemini 3.5 Flash (Low)` | lowest-cost smoke tests and simple rewrites |
-| `Gemini 3.5 Flash (Medium)` | cheap probes, fast summaries, context-reachability checks |
-| `Gemini 3.5 Flash (High)` | fast review when a little more reasoning effort is useful |
+| `Gemini 3.7 Flash (Low)` | lowest-cost smoke tests, cheap probes, simple rewrites (newest Flash) |
+| `Gemini 3.7 Flash (Medium)` | fast summaries, context-reachability checks |
+| `Gemini 3.7 Flash (High)` | wrapper + review default — asserted frontier-grade (fork (a)) |
+| `Gemini 3.6 Flash (Low)` | previous Flash generation, still served — prefer 3.7 |
+| `Gemini 3.6 Flash (Medium)` | previous Flash generation, still served — prefer 3.7 |
+| `Gemini 3.6 Flash (High)` | previous Flash generation, still served — prefer 3.7 |
+| `Gemini 3.5 Flash (Low)` | older Flash generation, still served — prefer 3.7 |
+| `Gemini 3.5 Flash (Medium)` | older Flash generation, still served — prefer 3.7 |
+| `Gemini 3.5 Flash (High)` | older Flash generation, still served — prefer 3.7 |
 | `Gemini 3.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
-| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `Gemini 3.1 Pro (High)` | hard reasoning, plan critique, architecture review (slower, deeper) |
 | `Claude Sonnet 4.6 (Thinking)` | cross-vendor reasoning comparison |
 | `Claude Opus 4.6 (Thinking)` | expensive deep critique when the user wants another high-end pass |
 | `GPT-OSS 120B (Medium)` | open-weights-style comparison / diversity pass |
@@ -84,11 +94,11 @@ Pass the **exact display string** from `agy models`, or set `AGY_MODEL`.
 Examples:
 
 ```bash
-AGY_MODEL="Gemini 3.5 Flash (Medium)" agy-run "Read AGENTS.md and report one Hard Constraint."
+AGY_MODEL="Gemini 3.7 Flash (Low)" agy-run "Read AGENTS.md and report one Hard Constraint."
 AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.md
 ```
 
-## Flags (from `agy --help`, v1.0.13)
+## Flags (from `agy --help`, v1.1.13)
 
 | Flag | Meaning | Notes |
 |---|---|---|
@@ -102,12 +112,19 @@ AGY_MODEL="Claude Sonnet 4.6 (Thinking)" AGY_TIMEOUT=10m agy-run @review-prompt.
 | `--dangerously-skip-permissions` | auto-approve all tool permissions | avoid by default; use only with explicit user approval |
 | `--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 |
+| `--output-format <fmt>` | print-mode output: `text` (default), `json`, `stream-json` | NEW in 1.1.x; not wrapper-adopted (backlog) |
+| `--json-schema <s\|path>` | enforce structured output (stream-json final result) | NEW in 1.1.x; not wrapper-adopted (backlog) |
+| `--effort <low\|medium\|high>` | reasoning effort for the session | NEW in 1.1.x; the display strings already carry an effort tier — the wrapper keeps model selection in ONE place (`AGY_MODEL`) |
+| `--mode <m>` | agent execution mode (`accept-edits`, `plan`) | NEW in 1.1.x; not used by the wrapper |
+| `--agent` / `--project <id>` / `--new-project` | agent + project selection for the session | NEW in 1.1.x; not used by the wrapper |
+| `--disable-slash-commands` | disable slash command/skill expansion in print mode | NEW in 1.1.x; not used by the wrapper |
 
-## Subcommands (v1.0.13)
+## Subcommands (v1.1.13)
 
-`changelog`, `help`, `install`, `models`, `plugin` / `plugins`, `update`.
+`agent` / `agents`, `changelog`, `help`, `install`, `models`, `plugin` / `plugins`, `update`.
 
-**Not available in v1.0.13:** any JSON output mode, and any `agy inspect`. Output is plain text.
+**Still not available in v1.1.13:** any `agy inspect`. Wrapper output stays plain text (the
+`--output-format` lane is not adopted here — see the backlog row).
 
 ## Project-context flags
 

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.13 or newer
+agy --version                          # expect 1.1.13 or newer
 ```
 
 - The binary is **`agy`** (not `antigravity`); it installs to `~/.local/bin/agy`.
@@ -59,12 +59,13 @@ agy --version
 echo "say OK" | agy-run -
 ```
 
-Expected: the version prints (`1.0.13` or newer), then a short reply containing `OK`. If `agy-run`
+Expected: the version prints (`1.1.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
 
-- `agy-run` is headless and plain-text only; there is no JSON output mode.
+- `agy-run` is headless and text by default; the CLI's 1.1.x `--output-format json` can ride
+  passthrough (`-- --output-format json`) but the wrapper adds no parsing/validation.
 - `AGY_MODEL` selects the exact model display string; `AGY_TIMEOUT` controls `--print-timeout`.
 - Extra `agy` flags go after `--`, e.g. `agy-run @prompt.md -- --add-dir .`.
 - Re-run interactive `agy` only when the OAuth token expires or the account changes.

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "5.7.0",
+  "version": "5.8.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/modes/grounding.md

@@ -2,14 +2,15 @@
 
 <!-- opt-in-capability: none — an on-demand assembler that leaves no persistent state the advisor could observe -->
 
-The **grounded-review facts assembler** (AD-038) — an ungrounded `agy` review GUESSES, and while the grounding contract is mechanized (`agy-review code --facts @f`), populating the facts file was a manual chore. This mode emits the **mechanical** facts sources of a payload (constraints / autonomy / plan / ledger digest); the orchestrator still owns any judgment-bearing additions. **Catalogued honestly as a WRITER** — `--out <path>` writes one file — with the invariant: `--out` accepts **only system-temp destinations outside the repo ($TMPDIR / /tmp — rewritable scratch) or a FRESH gitignored in-repo path (create-only, exclusive write)** and REFUSES everything else: a tracked path, an in-repo not-ignored path (a new untracked file would itself move the review fingerprint the facts are about to ground), an EXISTING in-repo file even when gitignored (the `.env` clobber class — this writer is bridge-tier auto-allowable), any other outside-repo destination, and symlink/non-regular leaves; **stdout is the default**. It never commits and never runs a subscription CLI.
+The **grounded-review facts assembler** (AD-038) — an ungrounded `agy` review GUESSES, and while the grounding contract is mechanized (`agy-review code --facts @f`), populating the facts file was a manual chore. This mode emits the **mechanical** facts sources of a payload (constraints / autonomy / plan / ledger digest); the orchestrator still owns any judgment-bearing additions — delivered via `--extra`, never a shell append onto the emitted file (corpus #88/#95). **Catalogued honestly as a WRITER** — `--out <path>` writes one file — with the invariant: `--out` accepts **only system-temp destinations outside the repo ($TMPDIR / /tmp — rewritable scratch) or a FRESH gitignored in-repo path (create-only, exclusive write)** and REFUSES everything else: a tracked path, an in-repo not-ignored path (a new untracked file would itself move the review fingerprint the facts are about to ground), an EXISTING in-repo file even when gitignored (the `.env` clobber class — this writer is bridge-tier auto-allowable), any other outside-repo destination, and symlink/non-regular leaves; **stdout is the default**. It never commits and never runs a subscription CLI.
 
-Run `node ${CLAUDE_SKILL_DIR}/tools/grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--reserve-bytes <n>] [--out <path>]`:
+Run `node ${CLAUDE_SKILL_DIR}/tools/grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--extra <text|@file>]... [--reserve-bytes <n>] [--out <path>]`:
 
 1. **`--constraints`** — slice the root `AGENTS.md` **Hard Constraints** section, verbatim and whole (exactly ONE matching heading; zero or several is a loud STOP, never a guess — the marker-slot discipline).
 2. **`--autonomy`** (AD-044 Plan 3) — append the COMPUTED effective autonomy policy: the shared resolver (`resolveAutonomy`) over the **git-top** `docs/ai/autonomy.json` renders every red-line + per-activity level with a stated source line. An ABSENT file is exit 0 — the computed defaults ARE the effective policy (unlike `velocity-profile --autonomy`, which writes settings and refuses an undeclared policy); a malformed/unreadable policy fails CLOSED (exit 1). Informational for the reviewing backend — enforcement stays the OS sandbox + the orchestrator. Rides between the constraints and the plan sections.
 3. **`--plan <path>`** — extract the plan's decision-bearing canonical sections, verbatim + whole: `## Approach` (REQUIRED — its "What we are NOT doing" text rides inside; it is not a heading in canon) and `## Verification` (REQUIRED — STOP if missing), plus `## Decisions (locked)` when present (the optional engine §7 heading); a DUPLICATE heading is always a STOP.
+4. **`--extra <text|@file>`** (corpus #88/#95 — the fourth firing of the same pre-dispatch append step) — append orchestrator-supplied facts byte-VERBATIM after the mechanical sections (repeatable, argv order; the `agy-review --facts` convention: literal text, or `@path` read whole through a race-free descriptor). An `@file` must resolve inside the PROVEN git work tree (rev-parse success — no cwd fallback; the git dir itself is refused) or the system temp surface — anything else refuses loudly (the exfil class: this tool is bridge-tier auto-allowable), as does a missing, EMPTY, or non-regular file (a FIFO cannot block the read). The merge happens INSIDE the tool, so the promptless lane is the invocation itself.
 5. **Byte budget** — the output honors the same `AGY_MAX_PROMPT_BYTES` contract the agy wrapper enforces (override may only tighten; the OS argv ceiling is rejected), MINUS **`--reserve-bytes <n>`** — the artifact share the caller expects `agy-review` to add around these facts. Overflow is trimmed tail-first with a loud in-band marker + stderr report — never a silent cut.
 6. Feed the result to the wrapper: `agy-review code --facts @<out>`. The `procedures` advisor renders this invocation as a concrete pre-step whenever the resolved review dispatch includes agy — populated with the in-flight plan path when exactly one plan is in flight.
 
-**Invariants:** writer (writes at most the ONE `--out` scratch file — system-temp, or a fresh gitignored in-repo path, exclusive-create) · never commits · never runs a subscription CLI · verbatim slices only (assembly is mechanical; facts judgment stays with the orchestrator).
+**Invariants:** writer (writes at most the ONE `--out` scratch file — system-temp, or a fresh gitignored in-repo path, exclusive-create) · never commits · never runs a subscription CLI · verbatim slices + verbatim extras (assembly is mechanical; facts judgment stays with the orchestrator — `--extra` carries it, the tool never edits it).

package/tools/grounding.mjs

@@ -11,6 +11,9 @@
 //                        it is not a heading in canon) and `## Verification` (REQUIRED — STOP if
 //                        missing), plus `## Decisions (locked)` (optional-if-absent, the engine §7
 //                        heading this release adds); a DUPLICATE heading is always a STOP.
+//   --extra <text|@file> append orchestrator-supplied facts verbatim AFTER the mechanical halves
+//                        (repeatable; @file reads are confined to the work tree + the system temp
+//                        surface — the merge happens INSIDE the tool, corpus #88/#95).
 //
 // Byte budget: the output honors the same AGY_MAX_PROMPT_BYTES contract the agy wrapper enforces
 // (default 120000; the override may only TIGHTEN — above the OS single-argv ceiling ~131000 is
@@ -31,6 +34,7 @@ import { tmpdir } from 'node:os';
 import { pathToFileURL } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { fail } from './orchestration-config.mjs';
+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';
@@ -81,7 +85,7 @@ export const sliceSection = (text, heading, { optional = false, label = 'documen
 
 // ── assembly ───────────────────────────────────────────────────────────────────────
 
-export const assembleGrounding = ({ constraintsText = null, autonomyText = null, planText = null, planLabel = 'plan' } = {}) => {
+export const assembleGrounding = ({ constraintsText = null, autonomyText = null, planText = null, planLabel = 'plan', extraTexts = [] } = {}) => {
   const parts = [];
   if (constraintsText != null) {
     parts.push(sliceSection(constraintsText, CONSTRAINTS_HEADING, { label: 'AGENTS.md' }));
@@ -96,6 +100,10 @@ export const assembleGrounding = ({ constraintsText = null, autonomyText = null,
       if (section != null) parts.push(section);
     }
   }
+  // Orchestrator extras ride LAST, verbatim in argv order — live judgment facts read after the
+  // mechanical slices, and the merge happens INSIDE the tool (corpus #88/#95: a shell append onto
+  // the emitted facts file was the recurring un-covered lane).
+  for (const t of extraTexts) parts.push(t);
   return parts.join('\n');
 };
 
@@ -151,10 +159,23 @@ const resolveAutonomyFacts = ({ cwd }) => {
   return renderAutonomyFacts(config, source);
 };
 
+// The realpath'd system temp surface ($TMPDIR / os.tmpdir() / /tmp) — the shared scratch boundary
+// for the --out write guard and the --extra read guard.
+const systemTempRoots = () => [...new Set([tmpdir(), process.env.TMPDIR, '/tmp'].filter(Boolean).map((p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}).filter(Boolean))];
+
 // ── the --out destination guard (gitignored / out-of-repo scratch ONLY) ────────────────
 
 const gitLine = (args, cwd) => {
-  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  // Ambient GIT_* location vars (GIT_DIR / GIT_WORK_TREE / …) would let rev-parse prove a FOREIGN
+  // tree — every location answer must come from cwd alone, for every gitLine consumer.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^GIT_/i.test(k)));
+  const r = spawnSync('git', args, { cwd, env, encoding: 'utf8', windowsHide: true });
   return r.error || r.status == null ? null : { status: r.status, stdout: r.stdout ?? '' };
 };
 
@@ -199,13 +220,7 @@ export const assertScratchDestination = (outPath, cwd) => {
   // the repo is scratch" would let an unattended run overwrite e.g. ~/.bashrc promptless.
   // $TMPDIR / os.tmpdir() / /tmp are the scratch surface; everything else refuses loudly.
   const assertTempScratch = () => {
-    const tempRoots = [...new Set([tmpdir(), process.env.TMPDIR, '/tmp'].filter(Boolean).map((p) => {
-      try {
-        return realpathSync(p);
-      } catch {
-        return null;
-      }
-    }).filter(Boolean))];
+    const tempRoots = systemTempRoots();
     if (!tempRoots.some((t) => full === t || full.startsWith(`${t}${sep}`))) {
       throw fail(1, `--out refuses an outside-repo destination that is not under a system temp root (${full}) — grounding output is scratch: use $TMPDIR//tmp, or a fresh gitignored in-repo path (temp roots checked: ${tempRoots.join(', ')})`);
     }
@@ -243,7 +258,8 @@ export const assertScratchDestination = (outPath, cwd) => {
 const HELP = `grounding — grounded-review facts assembler for the agent-workflow family (AD-038).
 
 Usage:
-  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--reserve-bytes <n>] [--out <path>]
+  node grounding.mjs [--constraints] [--autonomy] [--plan <path>] [--extra <text|@file>]...
+                     [--reserve-bytes <n>] [--out <path>]
 
   --constraints        slice the root AGENTS.md "Hard Constraints" section verbatim
                        (exactly one matching heading, else a loud STOP)
@@ -255,6 +271,14 @@ Usage:
   --plan <path>        extract the plan's decision-bearing sections verbatim + whole:
                        "## Approach" + "## Verification" (REQUIRED — STOP if missing),
                        "## Decisions (locked)" when present; a duplicate heading is a STOP
+  --extra <text|@file> append orchestrator-supplied extra facts byte-verbatim AFTER the
+                       mechanical sections (repeatable, argv order; the agy-review --facts
+                       convention: literal text, or @path read whole through a race-free
+                       descriptor). An @file must resolve inside the PROVEN git work tree
+                       (rev-parse success; the git dir itself refused) or the system temp
+                       surface — anything else refuses loudly, as does a missing, empty, or
+                       non-regular file. The merge happens INSIDE the tool: no shell append
+                       onto the emitted facts file
   --reserve-bytes <n>  the artifact share agy-review will add around these facts — the output
                        budget becomes AGY_MAX_PROMPT_BYTES − n (loud tail-trim on overflow)
   --out <path>         write instead of stdout — system-temp scratch (rewritable), or a FRESH
@@ -274,11 +298,19 @@ const parseArgs = (argv) => {
   let plan = null;
   let out = null;
   let reserve = 0;
+  const extra = [];
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--constraints') constraints = true;
     else if (a === '--autonomy') autonomy = true;
-    else if (a === '--plan') {
+    else if (a === '--extra') {
+      const val = argv[i + 1];
+      if (val == null || val === '' || val === '@' || val.startsWith('--')) {
+        throw fail(2, '--extra requires <text|@file> (repeatable)');
+      }
+      extra.push(val);
+      i += 1;
+    } else if (a === '--plan') {
       plan = argv[i + 1];
       if (!plan || plan.startsWith('--')) throw fail(2, '--plan requires a <path>');
       i += 1;
@@ -293,10 +325,10 @@ const parseArgs = (argv) => {
       i += 1;
     } else throw fail(2, `unknown argument: ${a}`);
   }
-  if (!constraints && !autonomy && plan == null) {
-    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, and/or --plan <path>');
+  if (!constraints && !autonomy && plan == null && extra.length === 0) {
+    throw fail(2, 'nothing to assemble — pass --constraints, --autonomy, --plan <path>, and/or --extra <text|@file>');
   }
-  return { constraints, autonomy, plan, out, reserve };
+  return { constraints, autonomy, plan, out, reserve, extra };
 };
 
 const resolveBudget = (env, reserve) => {
@@ -316,7 +348,7 @@ export const main = (argv, ctx = {}) => {
   const env = ctx.env ?? process.env;
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
-    const { constraints, autonomy, plan, out, reserve } = parseArgs(argv);
+    const { constraints, autonomy, plan, out, reserve, extra } = parseArgs(argv);
     const budget = resolveBudget(env, reserve);
 
     const readOrStop = (path, label) => {
@@ -348,8 +380,65 @@ export const main = (argv, ctx = {}) => {
     }
     const planText = plan != null ? readOrStop(plan, 'plan file') : null;
 
+    // --extra @file reads are CONFINED: the bridge tier auto-allows this tool with an args
+    // wildcard, so an unconfined @file would let an unattended run ship ANY readable file
+    // (~/.ssh, ~/.bashrc) into a prompt payload bound for a subscription CLI. The admitted read
+    // surface — computed ONCE per invocation — is the PROVEN git work tree (rev-parse success
+    // required; a cwd fallback would collapse the guard when cwd=$HOME) plus the system temp
+    // surface, MINUS the git dir(s) — repository internals never enter a facts payload. A non-@
+    // value is literal fact text (the agy-review --facts convention).
+    const extraReadSurface = () => {
+      const tempRoots = systemTempRoots();
+      const top = gitLine(['rev-parse', '--show-toplevel'], cwd);
+      if (top == null || top.status !== 0) return { tempRoots, topReal: null, gitDirsReal: [] };
+      const topReal = realpathSync(top.stdout.replace(/\r?\n$/, ''));
+      const gitDirsReal = ['--absolute-git-dir', '--git-common-dir'].map((flag) => {
+        const r = gitLine(['rev-parse', flag], cwd);
+        if (r == null || r.status !== 0) {
+          throw fail(1, `--extra cannot resolve the git dir (git rev-parse ${flag} failed) — refusing @file reads in an unmappable repo`);
+        }
+        return realpathSync(resolve(cwd, r.stdout.replace(/\r?\n$/, '')));
+      });
+      // The linked-worktree `.git` is a FILE inside the tree yet outside both answers above —
+      // repository metadata all the same.
+      gitDirsReal.push(join(topReal, '.git'));
+      return { tempRoots, topReal, gitDirsReal };
+    };
+    const surface = extra.some((v) => v.startsWith('@')) ? extraReadSurface() : null;
+    const resolveExtra = (value) => {
+      if (!value.startsWith('@')) return value;
+      const ref = value.slice(1);
+      const real = (() => {
+        try {
+          // Canonicalize the PARENT only — the leaf stays un-dereferenced so the no-follow open
+          // refuses a symlink leaf instead of silently reading its target.
+          const lexical = resolve(cwd, ref);
+          return join(realpathSync(dirname(lexical)), basename(lexical));
+        } catch (err) {
+          throw fail(1, `--extra file '${ref}' is unreadable (${(err && err.code) || err}) — STOP`);
+        }
+      })();
+      const within = (root) => real === root || real.startsWith(`${root}${sep}`);
+      const inTree = surface.topReal != null && within(surface.topReal);
+      if (!inTree && !surface.tempRoots.some(within)) {
+        throw fail(1, `--extra '@${ref}' resolves outside the work tree and the system temp surface (${real}) — refusing to read it into the facts payload`);
+      }
+      if (surface.gitDirsReal.some(within)) {
+        throw fail(1, `--extra '@${ref}' resolves inside the git dir (${real}) — repository internals never enter a facts payload`);
+      }
+      // Descriptor-bound read (the kit's ONE no-follow door): a FIFO cannot block the open, and a
+      // leaf swapped after the containment checks cannot change what the fd reads.
+      const r = readRegularFileNoFollow(real);
+      if (r.outcome === 'absent') throw fail(1, `--extra file '${ref}' is unreadable (ENOENT) — STOP`);
+      if (r.outcome === 'foreign') throw fail(1, `--extra file '${ref}' is not a regular file (${r.className}) — refusing; STOP`);
+      if (r.outcome !== 'ok') throw fail(1, `--extra file '${ref}' is unreadable (${r.code}) — STOP`);
+      if (r.content.trim() === '') throw fail(1, `--extra file '${ref}' is empty — nothing to append; STOP`);
+      return r.content; // byte-verbatim — no trailing-newline normalization
+    };
+    const extraTexts = extra.map(resolveExtra);
+
     const parts = [];
-    const assembled = assembleGrounding({ constraintsText, autonomyText, planText, planLabel: plan ?? 'plan' });
+    const assembled = assembleGrounding({ constraintsText, autonomyText, planText, planLabel: plan ?? 'plan', extraTexts });
     if (assembled) parts.push(assembled);
     const payload = parts.join('\n');
     const { text, trimmedBytes } = trimToBudget(payload, budget);