@sabaiway/agent-workflow-kit 1.5.2 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,73 @@ 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.
 
+## 1.7.0 — Link-only backend auto-setup; bridges bundled in the tarball
+
+The optional execution-backend bridges (`codex-cli-bridge` → `codex`, `antigravity-cli-bridge` →
+`agy`) can now be set up from the kit itself, via a new **opt-in, in-agent** mode —
+**`/agent-workflow-kit setup [backend]`** (`tools/setup-backends.mjs`). It owns only the two
+**deterministic, secret-free** steps and **guides** the rest (AD-011):
+
+- **Bridges are bundled in the kit's npm tarball** under `bridges/<name>/` — a **byte-identical
+  mirror** of the repo-root bridges, pinned by `test/bridges-mirror.test.mjs` (the same drift-guard
+  pattern as the methodology mirror). So `setup` places a bridge from local files, with **no network
+  fetch**. `init` (npx) bundles them but still **does not place** them — that stays the opt-in
+  `setup` job (preserving the honest `init` ≠ deploy claim).
+- **`setup` places/refreshes the bundled bridge skill**, but only into a dir that is **absent /
+  empty / proven-managed** (valid manifest, matching `name`+`kind`); a stub/foreign/invalid/
+  unsupported manifest, a marker fs-error, a non-empty unknown dir, or a symlinked dir → **STOP**,
+  never overwritten. Refresh re-runs on a managed dir so re-running `setup` delivers bundled fixes.
+- **It links the wrappers** (`codex-exec` / `codex-review`; `agy-run`) onto `PATH` (`~/.local/bin`,
+  override with `--bindir`) via **managed symlinks** — replacing only a symlink already pointing at
+  our source. It **preflights every target first**, so a conflict on one wrapper makes **zero**
+  changes; a non-symlink or a foreign symlink → STOP. Wrapper presence is judged **per-bindir**, not
+  PATH-wide. `--dry-run` prints the plan and changes nothing.
+- **The binary install + the interactive subscription login stay manual** — `setup` prints the exact
+  commands (the detector's axis-aware `guideFor`), never runs a subscription CLI, never commits. On
+  **Windows** it reports *unsupported — use WSL* and mutates nothing (the wrappers are POSIX `.sh`).
+- Internal: the symlink-traversal-safe copy/link primitives are now shared in `tools/fs-safe.mjs`
+  (the npx installer consumes them and gained an `isDirectRun` guard so importing it runs nothing).
+  The per-package publish workflow now gates the kit on its **whole** test suite, not just the
+  shipped enforcement scripts.
+
+No `docs/ai` structural change → the deployment-lineage head stays **`1.3.0`**; no migration.
+
+## 1.6.0 — Methodology slot reconciliation; engine becomes the canonical methodology home
+
+The workflow methodology now has a **single canonical home** in `agent-workflow-engine`
+(`available:false` — content only, not yet published or wired live), and the kit keeps
+**byte-identical mirror copies** so the existing injection + fallback keep working with **no new
+runtime dependency**. A drift-guard test (`tools/methodology-mirror.test.mjs`) pins the mirrors to
+the engine canon: `references/planning.md` and `tools/methodology-slot.md` must equal their engine
+counterparts byte-for-byte.
+
+The user-facing win is **stamp-independent slot reconciliation**. A single atomic, idempotent kit
+operation now **ensures the `workflow:methodology` slot exists and is filled** in a deployed
+`AGENTS.md`, on **bootstrap** and on **every upgrade**:
+
+- **`tools/inject-methodology.mjs`** gains `METHODOLOGY_ANCHOR`, `EMPTY_SLOT`, `ensureSlot`, and
+  `reconcileSlot` (reusing the existing `findSlot` / `injectMethodology` / `extractSlot` marker
+  parser — no second parser). `reconcileSlot` = **ensure the slot exists** (insert an empty marker
+  pair right after the Session-Protocols anchor when a legacy entry point lacks one) → **inject the
+  bounded fragment ONLY IF the slot is empty** (a filled / user-customized slot is preserved
+  verbatim) → **cap-check** (`AGENTS.md` ≤ 100 lines). On a malformed slot or a missing / duplicate
+  anchor it **STOPs with an error and never edits** — the file is left byte-for-byte unchanged.
+- A new CLI mode — `inject-methodology.mjs reconcile <AGENTS.md>` — runs that policy as **one
+  atomic write** (temp + rename); there is no partial state where markers exist but the fill failed.
+- The kit **fallback** entry-point template (`references/templates/AGENTS.md`) now ships the **empty
+  methodology slot** (matching memory's template) instead of an inline methodology line, so a fresh
+  fallback bootstrap gets a slot the kit fills. A new test (`test/fallback-template-cap.test.mjs`)
+  pins that template — empty and filled — under the 100-line cap.
+- **Bootstrap** and **upgrade** (`SKILL.md`) now run `reconcile`. On upgrade it runs
+  **before** the lineage short-circuit, so the slot is reconciled on every upgrade — reaching even
+  legacy **`1.3.0`** deployments — **without bumping the deployment-lineage head**.
+
+The deployment-lineage head **stays `1.3.0`** and `agent-workflow-memory` is **untouched** (no code,
+version, or migration change): reconciliation is stamp-independent, so it needs no head bump (which
+would have forced a memory republish, since the head is hard-coded in memory's stamp module).
+Additive — no user-facing break. The engine's npm packaging, `available:true`, and the live
+`kit → engine` read selector are deferred to the next plan.
+
 ## 1.5.2 — README uplift to front-door grade (docs)
 
 Docs-only patch. The npm-facing `README.md` is uplifted to match the GitHub family front door's

package/README.md

@@ -216,6 +216,7 @@ command is printed).
 | `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, preserves your authored memory, applies migrations, re-stamps |
 | `/agent-workflow-kit backends` | any time | **read-only** check of the optional execution-backends (the `codex` / `agy` bridges): what's set up vs missing and the next step. Never writes, never commits, never runs a subscription CLI (credentials = marker-file presence, not a live login). |
+| `/agent-workflow-kit setup [backend]` | opt-in, any time | **link-only** auto-setup of a bridge: places the bundled bridge skill (only into an absent / empty / managed dir — never overwrites an unmanaged one) + links its wrappers onto `PATH` via managed symlinks (idempotent; refuses to clobber a non-symlink; try `--dry-run` to preview). The binary install + the one-time subscription login stay **manual**: it prints the exact **login** command and points the binary install at each bridge's `setup/README.md`. POSIX wrappers — on Windows use WSL. Never commits, never runs a subscription CLI. |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.
 
@@ -248,17 +249,20 @@ agent-workflow-kit  —  the composition root (installed via npx … init)
    ├─ delegates ─▶ memory substrate   (healthy copy, else bundled fallback)
    ├─ injects   ─▶ workflow methodology  (engine = future supplier; stub)
    ├─ deploys   ─▶ AGENTS.md + docs/ai/ + Node scripts + pre-commit hook
-   └─ detects   ─▶ optional backends     (codex / agy — not by init)
+   ├─ detects   ─▶ optional backends   (codex / agy, read-only)
+   └─ sets up   ─▶ a bridge (opt-in)   (place skill + link wrappers)
 ```
 
 - **Delegates** substrate deployment to **`@sabaiway/agent-workflow-memory`** when a healthy
   standalone copy is present, else uses its **bundled fallback** — same `docs/ai/` either way.
 - **Injects** the bounded workflow methodology into the deployed `AGENTS.md`. Its *future* home is
   **`agent-workflow-engine`** — today an `available: false` stub, never one of the shipped backends.
-- **Detects** the optional `codex` / `agy` **bridges** — agent skills with a manual once-per-machine
-  setup (not npm, not installed by `init`); `/agent-workflow-kit backends` reports readiness
-  read-only. A bridge reads the deployed memory only if it wins that tool's context-file priority,
-  and the bridges call third-party services (so "no telemetry" covers family code, not those).
+- **Detects & (opt-in) sets up** the optional `codex` / `agy` **bridges** — agent skills (not npm, not
+  installed by `init`). `/agent-workflow-kit backends` reports readiness **read-only**;
+  `/agent-workflow-kit setup` does the **link-only** part (place the bundled bridge skill + link its
+  wrappers), while the binary install + the subscription login stay manual. A bridge reads the deployed
+  memory only if it wins that tool's context-file priority, and the bridges call third-party services
+  (so "no telemetry" covers family code, not those).
 
 > Full member-by-member map + the whole-family story: the
 > **[family front door](https://github.com/sabaiway/agent-workflow#readme)** — this page stays the
@@ -295,7 +299,10 @@ agent-workflow-kit/
 │   ├── delegation.mjs        ← detect substrate · delegate-or-fall-back
 │   ├── inject-methodology.mjs ← write the methodology slot
 │   ├── detect-backends.mjs    ← read-only backend detector
+│   ├── setup-backends.mjs     ← link-only backend setup
+│   ├── fs-safe.mjs            ← symlink-safe copy/link
 │   └── release-scan.mjs       ← attribution / release gate
+├── bridges/         ← bundled bridge skill mirrors (codex / antigravity)
 ├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```

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: '1.5.2'
+  version: '1.7.0'
 ---
 
 # agent-workflow-kit
@@ -49,21 +49,25 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
 **Hand-off contract (explicit; tested independent of agent interpretation).**
 - **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
   answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
-  `docs/ai/` + `AGENTS.md` + **`.memory-version`**. The kit then **injects the bounded
-  methodology slot** (below) and writes the kit-fallback **`.workflow-version`**. → **both
-  stamps** present.
+  `docs/ai/` + `AGENTS.md` (with the empty slot) + **`.memory-version`**. The kit then
+  **reconciles the bounded methodology slot** (below) and writes the kit-fallback
+  **`.workflow-version`**. → **both stamps** present.
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure below from its own
-  bundled assets and writes **`.workflow-version`** only. Softly suggest installing
+  bundled assets — whose entry-point template now ships the **empty methodology slot** the kit
+  reconciles + fills — and writes **`.workflow-version`** only. Softly suggest installing
   `agent-workflow-memory` — never a prerequisite.
 
-**Methodology injection (the kit is the ONLY writer of memory's slot).** After `AGENTS.md`
-exists, inject the bounded methodology fragment into its `workflow:methodology` slot:
-`node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs <project>/AGENTS.md`. It injects a short
-summary + pointer (Phase-1 source: the kit's bundled `tools/methodology-slot.md`) — **not** the
-full `references/planning.md` — and keeps `AGENTS.md` under its ≤100-line cap. Marker contract:
-exactly one ordered `start → end` pair → replace only the bytes between them; markers absent →
-no-op; any malformed state (single, reversed, nested, duplicate) → no-op **with an error**,
-never edit.
+**Methodology slot reconciliation (the kit is the ONLY writer of memory's slot).** After
+`AGENTS.md` exists, reconcile its `workflow:methodology` slot:
+`node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. Reconcile is
+**one atomic operation**: **ensure the slot exists** (insert an empty marker pair right after the
+Session-Protocols anchor when a legacy entry point lacks one) → **inject the bounded fragment ONLY
+IF the slot is empty** (a filled / user-customized slot is preserved verbatim) → **cap-check**
+(keeps `AGENTS.md` ≤100 lines). The fragment is a short summary + pointer (source: the kit's bundled
+`tools/methodology-slot.md`, a **byte-identical mirror of the `agent-workflow-engine` canon**) —
+**not** the full `references/planning.md`. Contract: exactly one ordered `start → end` pair; a
+malformed slot (single, reversed, nested, duplicate) or a missing / duplicate anchor → **STOP with
+an error**, never edit (the file is left byte-for-byte unchanged).
 
 **One composition-level commit gate.** The delegated memory mode performs **no** commit and
 raises **no** "ask to commit". There is exactly **one** gate, owned by the kit, **after**
@@ -79,6 +83,7 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 - **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
 - **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
 - **`/agent-workflow-kit backends`** — read-only environment check: which optional **execution-backends** (the `codex` / `agy` bridges) are set up vs missing. Never writes, never commits, never runs a subscription CLI.
+- **`/agent-workflow-kit setup [backend]`** — the **link-only**, opt-in companion to `backends`: place the bundled bridge skill + link its wrappers onto `PATH`. **In-agent only** — `init` (npx) never places bridges. The binary install + the interactive subscription login stay **manual** (it prints the exact commands); idempotent; refuses to clobber a non-symlink; never commits, never runs a subscription CLI.
 
 ### Mode: bootstrap
 
@@ -103,7 +108,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 9. **Wire / hide** per visibility (see contract). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
 10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
     `docs/ai/.workflow-version` (one semver line). The lineage head is **`1.3.0`** — the shared
-    `agent-workflow` deployment lineage, **NOT** this kit's package version (`1.4.0`). The two are
+    `agent-workflow` deployment lineage, **NOT** this kit's npm package version (see
+    `package.json` / `CHANGELOG.md`). The two are
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
@@ -122,11 +128,13 @@ Fill strategy:
 ### Mode: upgrade
 
 1. Read `docs/ai/.workflow-version` (the project's stamped lineage). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
-2. Compare to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If equal → report "up to date" and stop. If the stamp is **greater than the head** or unparseable → **STOP and report** (never downgrade).
-3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
-4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
-5. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-6. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
+2. **Never-downgrade gate — FIRST, before any write.** Compare the stamp to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If the stamp is **greater than the head** or unparseable → **STOP and report**; do not touch a newer / unknown deployment at all (not even the methodology slot).
+3. **Reconcile the methodology slot — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. This ensures the `workflow:methodology` slot exists and is filled on **every** upgrade, idempotently (zero-diff when already present + filled) — so even a legacy / current **`1.3.0`** deployment gains the slot **without a lineage-head bump** (the head stays `1.3.0`; **no `agent-workflow-memory` change**). It inserts an empty slot at the Session-Protocols anchor if absent, preserves a customized slot verbatim, and STOPs (never edits) on a malformed slot or a missing / duplicate anchor. No-Node project: open `AGENTS.md`, and if there is no `<!-- workflow:methodology:start/end -->` pair, paste it right after the *Read it before any code change.* line and fill it from `tools/methodology-slot.md`.
+4. **Equal-head short-circuit.** If the stamp **equals** the head → the lineage is up to date: **stop here** (the slot was already reconciled in step 3).
+5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
+6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
+7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
 
 ### Mode: backends
 
@@ -138,6 +146,26 @@ Read-only. Answers *"which optional execution-backends are set up vs missing, an
    - **"credentials present"** means the credential-marker **file** exists — it is **not** a live login check. The detector never runs `codex login status` / `agy` (that would spawn a paid, slow, networked subscription CLI).
    - The bridges' wrappers are **POSIX `.sh`** scripts. On Windows the detector still works, but the bridges themselves are **not promised to run** — say so rather than implying they will.
 
+### Mode: setup
+
+The **only writer** among the backend modes, and **opt-in / in-agent only** — it is **never** part of `init`. The npx installer deploys the *kit* and bundles the bridge skills in its tarball, but **does not place** them (that honesty claim is load-bearing — see `decisions.md` AD-009 / AD-011). `setup` owns exactly the two deterministic, secret-free steps and **guides** the rest. It **never commits and never runs a subscription CLI**.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs [<backend>] [--bindir <path>] [--dry-run]`:
+
+- `<backend>` — `codex` | `agy` | `antigravity` | `codex-cli-bridge` | `antigravity-cli-bridge`; omit for **all**.
+- `--bindir <path>` — where to link the wrappers (default `~/.local/bin`).
+- `--dry-run` — print the per-backend plan and change **nothing** (run this first).
+- `--help`, `-h` — usage.
+
+For each backend it:
+1. **Places / refreshes the bundled bridge skill** (from the kit's `bridges/<name>/` mirror) into its canonical dir — but only when that dir is **absent / empty / proven-managed** (valid manifest, matching `name`+`kind`). A `stub` / `foreign` / `invalid` / `unsupported` dir, a marker fs-error, or a symlinked dir → **STOP**, never overwritten. Refresh re-runs on a proven-managed dir so re-running `setup` delivers bundled fixes.
+2. **Links its wrappers** (`codex-exec` / `codex-review`; `agy-run`) onto `--bindir` via **managed symlinks** — replacing only a symlink that already points at our source. A non-symlink or a foreign symlink → **STOP**; it **preflights every target first**, so a conflict on one wrapper makes **zero** changes. If `--bindir` is not on `PATH`, it prints the one-line `export PATH=…` to add — it never edits a shell rc.
+3. **Guides the manual, secret-bearing steps it will NOT automate** — the binary install (each bridge's `setup/README.md` §1) and the one-time interactive subscription login (`codex login` / `agy`) — printing the exact command for whichever axis is still missing (axis-aware: it can ask for both the CLI and the login at once).
+
+**Windows:** the wrappers are POSIX `.sh`; on `win32` it reports *unsupported — use WSL* and mutates nothing.
+
+**Exit codes:** `0` = done / already set up / only manual steps remain (guidance is never a failure); **non-zero** = a STOP (a dir/symlink it refuses to clobber), a bad argument, a missing bundle, or a native fs error (the underlying reason is preserved in the message).
+
 ---
 
 ## Gotchas
@@ -207,6 +235,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot injection), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`, plus the axis-aware `guideFor`), `setup-backends.mjs` (the **link-only** backend setup behind `/agent-workflow-kit setup` — place the bundled bridge + link wrappers), `fs-safe.mjs` (the shared symlink-traversal-safe copy/link primitives both `setup-backends` and the npx installer use), and `release-scan.mjs` (the attribution-off release gate). The bundled bridge skill mirrors live under [`bridges/`](bridges/) (byte-identical to the repo-root bridges, pinned by `test/bridges-mirror.test.mjs`). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -18,19 +18,22 @@
 //
 // Dependency-free, Node >= 18.
 
-import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
+import { readFile, mkdir } from 'node:fs/promises';
 import { existsSync, lstatSync } from 'node:fs';
-import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { copyTreeRefresh } from '../tools/fs-safe.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = resolve(__dirname, '..');
 
 // The deployable skill = everything except the npm wrapper (package.json, bin/).
 // capability.json (the family manifest) + tools/ (the family schema + validator the kit runs
-// as the memory detector) must land in the installed skill dir too.
+// as the memory detector) must land in the installed skill dir too. bridges/ carries the
+// byte-identical execution-backend skill mirrors (codex/antigravity) so `setup` can place a bridge
+// from the installed kit, with no network fetch (Plan B / AD-011).
 const PAYLOAD = [
   'SKILL.md',
   'README.md',
@@ -40,6 +43,7 @@ const PAYLOAD = [
   'launchers',
   'migrations',
   'tools',
+  'bridges',
 ];
 
 const tildify = (path) => path.replace(homedir(), '~');
@@ -64,42 +68,10 @@ const lstatNoFollow = (path) => {
   }
 };
 
-// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest` within
-// `root` (root / intermediate dir / leaf, including a dangling one), or to a dest outside `root`.
-const assertContainedRealPath = (root, dest) => {
-  const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
-    throw new Error(`[agent-workflow-kit] refusing to write outside the target dir: ${dest}`);
-  }
-  if (lstatNoFollow(root)?.isSymbolicLink()) {
-    throw new Error(`[agent-workflow-kit] refusing to install into a symlinked target dir: ${root}`);
-  }
-  const walk = (acc, part) => {
-    const cur = join(acc, part);
-    if (lstatNoFollow(cur)?.isSymbolicLink()) {
-      throw new Error(`[agent-workflow-kit] refusing to write through a symlink at ${cur} (would escape ${root}).`);
-    }
-    return cur;
-  };
-  rel.split(sep).filter(Boolean).reduce(walk, root);
-};
-
-const copyRecursive = async (src, dest, root) => {
-  assertContainedRealPath(root, dest); // never write through a dest symlink (root/intermediate/leaf)
-  const stat = await lstat(src);
-  if (stat.isSymbolicLink()) {
-    if (existsSync(dest)) return; // additive: never delete/replace an existing entry
-    const linkTarget = await readlink(src);
-    await symlink(linkTarget, dest);
-  } else if (stat.isDirectory()) {
-    await mkdir(dest, { recursive: true });
-    const entries = await readdir(src);
-    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry), root)));
-  } else {
-    await mkdir(dirname(dest), { recursive: true });
-    await copyFile(src, dest);
-  }
-};
+// The symlink-traversal guard + the recursive refresh copy now live in tools/fs-safe.mjs (shared,
+// dependency-injectable, unit-tested in isolation). install.mjs consumes copyTreeRefresh, which guards
+// every dest via assertContainedRealPath internally. The local lstatNoFollow above stays for the
+// pre-flight check on the target root itself (a nicer error than letting the copy throw).
 
 const parseArgs = (argv) => {
   const dirFlag = argv.indexOf('--dir');
@@ -150,7 +122,15 @@ const main = async () => {
 
   // Critical payload must be present, or the install would silently ship a kit that can't run
   // its own detector (tools/) or family contract (capability.json). Fail loudly, don't filter away.
-  const REQUIRED = ['SKILL.md', 'capability.json', 'references', 'tools', 'migrations'];
+  const REQUIRED = [
+    'SKILL.md',
+    'capability.json',
+    'references',
+    'tools',
+    'migrations',
+    'bridges/codex-cli-bridge',
+    'bridges/antigravity-cli-bridge',
+  ];
   const missing = REQUIRED.filter((entry) => !existsSync(resolve(PKG_ROOT, entry)));
   if (missing.length > 0) {
     console.error(`[agent-workflow-kit] package payload incomplete — missing: ${missing.join(', ')} (corrupt install?)`);
@@ -164,11 +144,9 @@ const main = async () => {
     process.exit(1);
   }
   await mkdir(target, { recursive: true });
-  await Promise.all(
-    PAYLOAD.filter((entry) => existsSync(resolve(PKG_ROOT, entry))).map((entry) =>
-      copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target),
-    ),
-  );
+  for (const entry of PAYLOAD.filter((e) => existsSync(resolve(PKG_ROOT, e)))) {
+    copyTreeRefresh(resolve(PKG_ROOT, entry), resolve(target, entry), target);
+  }
   console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
 
   // Wire non-Claude agents — best-effort; the launcher only touches tools you have.
@@ -198,7 +176,12 @@ This command only installs/updates the kit itself (in ${tildify(target)}).
 To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@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 assert it has no side effects. Same idiom as tools/detect-backends.mjs.
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/bin/install.test.mjs

@@ -5,9 +5,10 @@ import { mkdtemp, rm, mkdir, symlink, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
+const KIT_ROOT = dirname(dirname(INSTALLER));
 // --no-launchers so the test never wires Codex/Devin on the host.
 const runInstaller = (target) =>
   spawnSync(process.execPath, [INSTALLER, '--dir', target, '--no-launchers'], { encoding: 'utf8' });
@@ -64,3 +65,31 @@ describe('kit installer — payload + symlink-traversal hardening', () => {
     assert.deepEqual(await readdir(real), []);
   });
 });
+
+describe('kit installer — module hygiene', () => {
+  it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
+    // `node -e` has no argv[1], so isDirectRun is false → importing must not run main()
+    // (no FS writes, no exit). A child process keeps the assertion off the test runner's own state.
+    const url = JSON.stringify(pathToFileURL(INSTALLER).href);
+    const res = spawnSync(
+      process.execPath,
+      ['--input-type=module', '-e', `import(${url}).then(() => console.log('IMPORT_OK'));`],
+      { encoding: 'utf8' },
+    );
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /IMPORT_OK/);
+    assert.doesNotMatch(res.stdout, /installed v|updated the kit/);
+  });
+});
+
+describe('kit installer — published tarball bundles the bridges', () => {
+  it('npm pack ships bridges/<name>/ (the execution-backend skill mirrors)', () => {
+    // The real `files` whitelist decides what publishes — assert against `npm pack`, not the source
+    // tree, so a dropped `bridges/` entry in package.json fails here (not silently at install time).
+    const res = spawnSync('npm', ['pack', '--dry-run', '--json'], { cwd: KIT_ROOT, encoding: 'utf8' });
+    assert.equal(res.status, 0, res.stderr || res.error?.message);
+    const paths = JSON.parse(res.stdout)[0].files.map((f) => f.path);
+    assert.ok(paths.includes('bridges/codex-cli-bridge/SKILL.md'), 'codex bridge SKILL.md not packed');
+    assert.ok(paths.includes('bridges/antigravity-cli-bridge/bin/agy.sh'), 'antigravity agy.sh not packed');
+  });
+});

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

@@ -0,0 +1,178 @@
+---
+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.
+metadata:
+  version: '1.0.0'
+---
+
+# antigravity-cli-bridge
+
+Bridges the main agent to **Antigravity CLI** (`agy`), Google's successor to Gemini CLI. As of
+2026-06-18 the old Gemini CLI stopped serving Google AI Pro / Ultra / free tiers; terminal access to
+Google's models moved to `agy`. This is a **delegated-execution backend** beside Codex: the main
+agent stays the orchestrator — owning decisions, edits, verification, and user-facing claims — and
+hands `agy` a bounded, self-contained sub-task answered from the **subscription** quota (no
+pay-as-you-go billing). `agy` reaches Gemini, Claude, and GPT-OSS through one subscription, so it
+serves as both a cheap probe engine (Flash) and a strong second opinion (Pro / Claude Thinking).
+
+## Overview / when to use
+
+Use this skill when the user wants to:
+
+- Delegate a focused prompt to `agy` in headless mode.
+- Use Gemini, Claude, or GPT-OSS access available through a Google AI Pro/Ultra subscription.
+- Ask a second model to review a plan, summarise project context, or critique a diff supplied in the
+  prompt.
+- Install, authenticate, smoke-test, or troubleshoot `agy`, or understand its models/flags/quota.
+
+Do **not** use it to bundle secrets, bypass subscription auth, or hand uncontrolled repository
+mutations to `agy`.
+
+## Install
+
+Clean-machine setup is in [`setup/README.md`](setup/README.md). In short: the binary is **`agy`**
+(not `antigravity`), installs to `~/.local/bin/agy`, and must be on `PATH`; expose this skill's
+wrapper [`bin/agy.sh`](bin/agy.sh) on `PATH` as `agy-run`.
+
+## Auth — subscription only (invariant)
+
+`agy` authenticates with a cached **OAuth token** from a **Google AI Pro/Ultra** sign-in:
+
+```text
+~/.gemini/antigravity-cli/antigravity-oauth-token
+```
+
+Never read, print, copy, commit, or package that token — it is personal and is **never bundled** with
+this skill. The wrapper [`bin/agy.sh`](bin/agy.sh) **unsets every `*_API_KEY`** (`ANTIGRAVITY_API_KEY`,
+`GEMINI_API_KEY`, `GOOGLE_API_KEY`, `GOOGLE_GENAI_API_KEY`) before invoking `agy`, so a stray key can
+never silently switch you to pay-as-you-go billing.
+
+**Caveat:** the subscription has a finite quota. Prefer the cheapest model that fits the task, and
+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.
+
+| 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.1 Pro (Low)` | cheaper Pro pass for medium reasoning |
+| `Gemini 3.1 Pro (High)` | wrapper default; hard reasoning, plan critique, architecture review |
+| `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 |
+
+## Usage
+
+Drive `agy` only through the wrapper [`bin/agy.sh`](bin/agy.sh) (installed on `PATH` as `agy-run`):
+
+```bash
+agy-run "your prompt"                         # prompt as an argument
+echo "your prompt" | agy-run -                # prompt from stdin
+agy-run @path/to/prompt.md                    # prompt from a file
+AGY_MODEL="Claude Opus 4.6 (Thinking)" agy-run "..."   # pick a model
+AGY_TIMEOUT=10m agy-run "..."                 # agy's soft --print-timeout
+AGY_HARD_TIMEOUT=8m agy-run "..."             # hard wall-clock cap via timeout(1)
+agy-run "..." -- --add-dir . --dangerously-skip-permissions   # passthrough agy flags
+```
+
+`agy` is **headless-only** here (`-p`/`--print`) and there is **no JSON output mode** in v1.0.10 — you
+get plain text. 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_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).
+
+## Project context (how `agy` sees the repo)
+
+From its **current working directory** `agy` reads one root context file by priority, plus
+per-workspace skills:
+
+```text
+.antigravity.md > GEMINI.md > AGENTS.md
+.agents/skills/
+```
+
+So when you run `agy-run` from a project root, `agy` loads the **highest-priority context file that
+exists** — in most repos that is `AGENTS.md`, so its Hard Constraints are available — plus the
+project's `.agents/skills/`, with no wiring needed. **A `.antigravity.md` or `GEMINI.md`, if present,
+shadows `AGENTS.md`** (only the winning file is read), so put cross-cutting rules in whichever file
+wins, or include them in the prompt. Probe results in a real repo confirmed `agy` read the root
+`AGENTS.md` (returning the dialogue language + a Hard Constraint) and cited
+`.agents/skills/<skill>/SKILL.md` by path.
+
+**Honest scope:** these probes prove *reachability* — `agy` surfaces the cwd context file and
+per-workspace skills by directory scan. In testing it also **named a project-specific skill without
+being pointed at any file** (auto-discovery), but that is `agy`'s own mechanism, not a guaranteed
+Claude-style description-dispatch engine; don't promise more than the probe shows in a given repo.
+Re-runnable from a project root (use a cheap model):
+
+```bash
+AGY_MODEL="Gemini 3.5 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 \
+  "Without me pointing you at any file, name a project-specific skill under .agents/skills/ here and cite its path."
+```
+
+## How the main agent drives `agy` efficiently
+
+See [`references/driving-agy.md`](references/driving-agy.md) for the full playbook (delegation
+checklist, prompt templates, output handling). Essentials:
+
+- **Pick the cheapest model that fits.** Flash (Low/Medium) for reachability/probes; Pro (High) for
+  reasoning; `Claude Sonnet 4.6 (Thinking)`, `Claude Opus 4.6 (Thinking)`, or `GPT-OSS 120B (Medium)`
+  for a different engine's opinion (exact strings — see the Models table) — all on the same
+  subscription. Quota is finite, so don't reach for Pro by reflex.
+- **Hand `agy` a self-contained prompt.** It cannot see your conversation — embed the goal,
+  constraints, relevant excerpts, and the expected output shape; nothing more.
+- **Continue a thread** with `-- --continue` (most recent) or `-- --conversation <id>` (by id) instead
+  of re-sending context.
+- **Treat output as advisory** and verify before acting — check claims against local files, re-run
+  tests/linters yourself, reject advice that conflicts with user instructions or repo rules.
+- **Escalations are done by hand, not by `agy`.** The wrapper passes no `--add-dir`, no
+  `--dangerously-skip-permissions`, and no `--sandbox` — but that is a **policy boundary you state in
+  the prompt, not an enforced sandbox**. Keep repo edits, new dependencies/network installs, and git
+  writes (branch/add/commit/stash/reset/rewrite) with the orchestrator, and tell `agy` in the prompt
+  to return findings only. Add `-- --sandbox` when delegating anything that could trigger
+  terminal/tool work; opt into `-- --add-dir . --dangerously-skip-permissions` only for a flow that
+  genuinely needs writes, then review the diff afterwards.
+
+## Complementary skills (optional, standalone-first)
+
+`agy-run` works in any directory where `agy` is installed and authenticated. The two skills below are
+**not required** to use `agy` — surface them only when they actually help.
+
+- **`agent-workflow-memory`** (family **context provider**) — if the current project has **no**
+  `AGENTS.md` + `docs/ai/`, `agy` has no per-workspace context to read. The memory substrate creates
+  it. Soft-recommend it (only when the user wants the memory workflow):
+  `npx @sabaiway/agent-workflow-memory init`, then `/agent-workflow-memory` in the project — or
+  bootstrap the whole family via the **`agent-workflow-kit`** orchestrator
+  (`npx @sabaiway/agent-workflow-kit init`), which delegates substrate deployment to memory. Never a
+  prerequisite for using `agy`.
+- **`codex-cli-bridge`** (sibling backend, OpenAI Codex) — recommend **by actual presence**: if
+  `~/.claude/skills/codex-cli-bridge/` exists you have a **second delegated engine** (Codex for
+  sandboxed repo edits with gates; `agy` for subscription-quota Gemini/Claude reasoning). If it is
+  **not** installed, treat it as a **planned sibling** — don't assume it exists.
+
+## Known limitations
+
+- 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.10 — parse text; there is 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
+  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.