golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
6cfa0c55d205eaeaf005f4d21f7b5e5cefa4448c
msd-core/docs/research/gemini-to-antigravity-migration.md
Jakub Zych a9a7a328e6 refactor: hard-fork GSD -> MSD (Make Software Done) 
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
2026-10-06 01:47:40 +02:00

381 lines
36 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# The Gemini → Antigravity migration: authoritative picture
Researched against primary sources only (source, capability manifests, ADRs, tests, git
history, CHANGELOG) on branch `next` at commit `c0b2a05d2f`. Every claim below is cited
`file:line` or a commit SHA.
## 1. Timeline / provenance
- **2026-06-18** — Google sunsets Gemini CLI for free/Pro/Ultra tiers. Cited throughout the
codebase, e.g. `GEMINI.md:1`, `bin/install.js:1075`.
- **Removal commit: `8f2ebbe9bf`** — `feat(#1928): remove sunset Gemini CLI runtime, redirect
to Antigravity (#1996)`, authored 2026-07-04. Commit message (verbatim): *"Remove the gemini
runtime from the enum (16->15), aliases, labels, config-home fragment, install path,
converters (convertClaudeToGemini{Markdown,Toml,Agent}, convertSlashCommandsToGeminiMentions),
capability descriptor, gemini-extension.json, RULESET.GEMINI.*, and the interactive menu…
Antigravity is preserved throughout: its GEMINI.md contextFileName, .gemini/antigravity
config home, the shared convertGeminiToolName/claudeToGeminiTools tool vocabulary, and the
'gemini' hookEvents dialect it declares."* This is the single authoritative statement of
intent for the whole migration — the taxonomy in §2 is a direct expansion of it.
- Deleted in this commit (via `git log --diff-filter=D --name-only`): `capabilities/gemini/capability.json`, `gemini-extension.json`, `tests/gemini-namespacing.test.cjs`, `tests/issue-775-gemini-extension.test.cjs`, `tests/bug-2557-gemini-local-hook-paths.test.cjs`, `tests/bug-3037-gemini-duplicate-commands.test.cjs`, `tests/enh-776-install-gemini-hook-events.test.cjs`, `tests/fixtures/golden-install-parity/gemini.json`.
- Follow-up in the same PR: dropped Gemini CLI from `.github/ISSUE_TEMPLATE/bug_report.yml` and `feature_request.yml` (review nit from @davesienkowski).
- Changeset: `.changeset/vivid-foxes-click.md` → rendered at `CHANGELOG.md:1012` / `CHANGELOG.md:1281` (duplicated, both a "recent" and an older archival copy of the same line): *"Removed the sunset Gemini CLI runtime — use Antigravity CLI instead… (#1928) (#1996)"*.
- `GEMINI.md` itself was **repointed, not deleted**, in the same commit (`git log --oneline -- GEMINI.md` shows `8f2ebbe9bf` as the second-most-recent touch after the original `a3aa0ae142` "ship a gemini-extension.json extension package" (#775/#818)).
- **`capabilities/gemini/capability.json` was re-created later**, as a reviewer-lane-only
manifest, by the reviewer-lane-declaration work: `6a9babda69` `chore(#2798): declare the
eleven reviewer lanes as manifest data (#2837)`, per ADR-2782 (`docs/adr/2782-reviewer-lane-capability-surface.md`). Confirmed live today: `capabilities/gemini/capability.json:1-6` — `"role": "reviewer"`, description *"cross-AI `/msd-review` reviewer lane only; not a MSD install target (no runtime body, no artifacts)"*. This is intentional, not a regression of #1928 — CHANGELOG.md:810 documents the same PR: *"Five reviewers MSD never installs into (Gemini, CodeRabbit, Ollama, LM Studio, llama.cpp) become lane-only capabilities with no install surface."*
- **Antigravity's own evolution as a runtime** (separate from the Gemini removal, but
entangled with it because it shares the `.gemini` dialect):
- `fbd62cd84f` `feat(#1035): phase 5a — author 16 role:runtime capability descriptors (registry-only) (#1039)` — Antigravity first declared as a capability descriptor.
- `5695522d5f` `feat(#2096): migrate Antigravity onto EoS declarative adapter + permission-writer + MCP companion (ADR-1239)` — CHANGELOG.md:973 / :1240.
- `3738`/`4274` (per CHANGELOG.md:224/343) — Antigravity's global skills/agents home corrected from `~/.gemini/antigravity` to `~/.gemini/config` (the dir `agy` actually scans), captured today as `runtime.artifactLayout.global[].home` = `.gemini/config` in `capabilities/antigravity/capability.json:31,40`; the retirement of the old spot is migration `src/installer-migrations/010-antigravity-retire-confighome-artifacts.cts`, changeset text at `docs/installer-migrations.md:583`.
- No ADR is dedicated solely to "retire Gemini runtime" — the decision is recorded as a
changeset + PR (#1928/#1996), not an ADR. The relevant ADRs (`docs/adr/1244-capability-ecosystem.md`, `docs/adr/2782-reviewer-lane-capability-surface.md`, `docs/adr/3660-runtime-artifact-layout-module.md`, `docs/adr/894-capability-declaration-format.md`) describe the *general* capability/reviewer-lane machinery that both Gemini's reviewer lane and Antigravity's runtime lane now ride on, not the migration event itself. **UNDETERMINED** whether an ADR was ever intended for the removal decision specifically — none exists under `docs/adr/`.
## 2. Taxonomy of `gemini` senses
**(a) Gemini *runtime* / install target — RETIRED.** Proven by:
- `bin/install.js:1073-1087` — `if (args.includes('--gemini'))` prints the sunset notice and exits 1; no install path remains.
- `bin/install.js:1075`: `'Gemini CLI was sunset by Google on 2026-06-18 and is no longer served for free/Pro/Ultra tiers.'`
- Guard test `tests/gemini-runtime-removed.test.cjs:1-19` (docblock) states the contract explicitly: *"Coverage: A. CLI redirect contract… B. The `gemini` runtime is gone from every runtime-name-policy surface. C. Antigravity is PRESERVED everywhere it shared surface with gemini (GEMINI.md instruction file + the shared convertGeminiToolName tool vocabulary)."* Test body (`:60-93`) asserts `--gemini` exits 1, cites the sunset date, redirects to `--antigravity`, and creates no `.gemini` dir.
- `capabilities/antigravity/capability.json:1-6` no longer has a `gemini` sibling runtime descriptor; `capabilities/gemini/capability.json:1-4` explicitly has **no `runtime` body at all** — only `reviewer`.
**(b) Gemini *CLI reviewer lane* (`capabilities/gemini/`) — LIVE and INTENTIONAL.**
- `capabilities/gemini/capability.json:1-40` — `role: "reviewer"`, `reviewer.slug: "gemini"`, flags `--gemini`, spawn transport `gemini -p - -m <model>`. Still wired into the registry: `msd-core/bin/lib/capability-registry.cjs:1793-1817` (reviewer body), `:4945-4947` (config-key ownership), `:8148` (`"gemini": []` — no requires).
- Documented as a live reviewer flag in `docs/COMMANDS.md:269,757,1038,1810,1826,1834,1847-1851` and `docs/CONFIGURATION.md:297,329,340,384,394,401,1464,1474,1476,1492`, and in `docs/reference/capability-matrix.md:125` — `| gemini | reviewer | full | >=1.8.0 | — | — | first-party |`.
- CHANGELOG.md:89 shows the lane still receiving fixes as recently as #3996/#4184. This is a maintained, first-party lane — not an oversight.
**(c) Google Gemini directories/dialect that Antigravity legitimately reuses — MUST NOT be renamed.**
Confirmed exactly as the CRITICAL CONTEXT states, all still present and load-bearing:
- `capabilities/antigravity/capability.json:11-15` — `configHome.kind: "dot-home-nested"`, `parent: ".gemini"`, nested under `~/.gemini/antigravity`.
- `capabilities/antigravity/capability.json:31,40` — `artifactLayout.global[].home: ".gemini/config"` (the dir `agy` scans for machine-local discovery, per #3738).
- `capabilities/antigravity/capability.json:56` — `hookEvents: "gemini"` (hook-event dialect).
- `capabilities/antigravity/capability.json:78` — `hostBehaviors.projectInstructionFile: "GEMINI.md"`.
- Confirmed as deliberate, not incidental, in `src/runtime-name-policy.cts:105,117,127` (doc comments: *"antigravity: GEMINI.md is Antigravity CLI's contextFileName (the Gemini…)"*) and in `docs/reference/host-integration-capability-matrix.md:342` (EoS migration note: `hostBehaviors.projectInstructionFile` reads `"GEMINI.md" — Antigravity CLI's contextFileName, successor to the sunset Gemini CLI per #1928`).
- Shared tool-name vocabulary: `bin/install.js:1628-1720` — `claudeToGeminiTools`, `convertGeminiToolName` — still present and used by Antigravity's agent converter (`convertClaudeAgentToAntigravityAgent`, imported by `tests/gemini-runtime-removed.test.cjs:53` specifically to assert this survives). CHANGELOG.md:1455 confirms the shared vocabulary: *"excluded from the Gemini and Gemini-backed Antigravity agent `tools:` frontmatter."*
- `docs/reference/host-integration-capability-matrix.md:315,317,322,330` cite Google's own migration blog (`developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli`) as the evidentiary source for Antigravity inheriting the Gemini backend.
**(d) Gemini *models* in the model catalog — legitimate product names.**
- `msd-core/bin/shared/model-catalog.json` contains `gemini-*` model IDs (not read directly here per the guard, but referenced in CHANGELOG.md:1561: *"the gemini opus default `gemini-3-pro` → `gemini-3.1-pro-preview`"*).
- Config docs: `docs/CONFIGURATION.md:297,1492` (`"gemini": "gemini-2.5-pro"`), `docs/CLI-TOOLS.md:1426` (`review.models.gemini "gemini-2.5-pro"`). All legitimate — naming the provider's model, not the retired runtime.
**(e) Historical/archival references — immutable, must not be rewritten.**
- `CHANGELOG.md` (dozens of lines, e.g. :1012, :1281, :1455, :1456, :1557) — release history, must stay as-is per repo convention (`CHANGELOG.md is Locked` — CLAUDE.md §"CHANGESETS & RELEASE NOTES").
- `.changeset/archived/fix-3344-gemini-agent-tool.md`, `.changeset/archived/fix-3362-windows-powershell-gemini.md`, `.changeset/archived/gemini-skip-local-when-global.md`, `.changeset/archived/213-antigravity-2-runtime-dirs.md`, `.changeset/archived/3608-antigravity-update-runtime.md`, `.changeset/archived/503-antigravity-agent-local-detection.md` — archived fragments, immutable release-note history.
- `docs/RELEASE-NOTES-LEGACY.md`, `docs/whats-new-1.7.0.md`, `.pr-body-3514.md`, `.pr-body-3515.md` — point-in-time snapshots; PRESERVE.
- `VERSIONING.md:133` — `` `gemini-extension.json` — Gemini CLI extension manifest (issue #775) `` — this line documents a **file that no longer exists** (`gemini-extension.json` was deleted in `8f2ebbe9bf`, confirmed via `find . -iname 'gemini-extension.json'` returning nothing). This is borderline (e) vs. (f): it reads as changelog-style provenance for a retired artifact, but VERSIONING.md is not an archival/frozen document the way CHANGELOG.md is — it is an active reference doc (`file inventory / what ships in which package`). **Verdict: MIGRATE or annotate** — see §4.
**(f) STALE references — treat Gemini as a live runtime/install target.**
See the full inventory in §4. Headline finding: the four README translations and most of the
`docs/{ja-JP,ko-KR,pt-BR,zh-CN}/` doc mirrors still describe "Gemini CLI" as a currently
supported, installable runtime alongside Claude Code/OpenCode/Kilo/Codex/Copilot/Antigravity —
while the English originals were scrubbed clean in `8f2ebbe9bf` and have zero such language.
## 3. The `GEMINI.md` file at repo root
- **What it is now**: Antigravity's `contextFileName` (inherited from the shared Gemini 3
backend) — the file Antigravity auto-reads for project context, analogous to `CLAUDE.md` for
Claude Code or `AGENTS.md` for Codex/OpenCode. Confirmed by its own banner: `GEMINI.md:1-6`
— *"# MSD Core — Antigravity CLI context… this file is the context Antigravity reads
automatically (its `contextFileName` is `GEMINI.md`, inherited from the shared Gemini 3
backend)."*
- **Provenance**: originally shipped as part of a Gemini CLI extension package
(`a3aa0ae142` `feat(#775): ship a gemini-extension.json extension package (#818)`), then
**repointed to Antigravity** in the removal commit `8f2ebbe9bf` (same commit that deleted
the Gemini runtime). It is correctly an Antigravity artifact today, not a Gemini-runtime
leftover — PRESERVE.
- **Who generates/consumes it for user projects** (distinct from this repo's own root
`GEMINI.md`, which is MSD's self-description for AI agents working on MSD itself):
`getProjectInstructionFile(runtime)` in `src/runtime-name-policy.cts:105-127` maps
`antigravity → GEMINI.md` (also `gemini → GEMINI.md` per CHANGELOG.md:1488, though the
`gemini` runtime key itself no longer resolves to an installable runtime — the mapping table
entry is vestigial/defensive, not reachable through `--gemini`). Compiled counterpart:
`msd-core/bin/lib/runtime-name-policy.cjs:118,130,140`. Consumed by the new-project workflow
and `generate-claude-md` path per CHANGELOG.md:1488: *"A shared `getProjectInstructionFile(runtime)` policy… is now the single source of truth consumed by both the new-project workflow and the generate-claude-md path, with a parity test guarding drift."*
- **Guard**: `tests/project-instruction-file-parity.test.cjs` exists (per the file inventory)
and is the parity test CHANGELOG.md:1488 refers to. `tests/product-name-purity.test.cjs:23-41`
(`PRODUCTS`, `README_FILES`, `findProductParentheticals`) is a different, narrower guard —
it checks that product names aren't parenthetically mis-glossed in READMEs, not that
Gemini-as-runtime language is absent. Neither test inspects the translated docs (§5).
- **Verdict: PRESERVE.** The root `GEMINI.md` is correct and current.
## 4. Inventory of stale references (representative — not all ~400 hits)
`grep -rliE gemini` across the tree (excluding `node_modules`, `.git`, `.changeset`) returns
**~280 files** referencing `gemini`; the overwhelming majority are legitimate senses (b)–(e) —
reviewer-lane docs, model-catalog entries, ADR/CHANGELOG history, and the Antigravity dialect
notes in `CONTEXT.md`, `docs/reference/host-integration-capability-matrix.md`, and
`docs/installer-migrations.md:446,583`. The generated files (`docs/FEATURES.md`,
`msd-core/bin/lib/capability-registry.cjs`, `msd-core/bin/lib/capability-validator.cjs`) are
**not hand-edited** — `docs/FEATURES.md` is emitted by `scripts/gen-features.cjs` (registered
in `scripts/docs-guard-registry.cjs`), and the `.cjs` registry files under `msd-core/bin/lib/`
are the build output of the `.cts` sources under `src/` (per `CONTEXT.md:248`, "NOT generated
from `src/*.cts`" applies only to `bin/install.js` itself — the `msd-core/bin/lib/*` modules
ARE generated). Do not hand-edit generated files; any fix belongs in the `.cts` source or the
capability `.json` and must be regenerated.
| File | Line | Current text (paraphrased) | Sense | Verdict | Why |
|---|---|---|---|---|---|
| `README.ja-JP.md` | 9, 24, 46 | Lists "Gemini CLI" as a supported runtime alongside Claude Code/OpenCode/Kilo/Codex/Copilot/Cursor/Windsurf | (f) | **MIGRATE** | English `README.md` has **zero** gemini mentions (verified via grep); translation was never updated after `8f2ebbe9bf` |
| `README.ko-KR.md` | 9, 24, 46 | Same as above (Korean) | (f) | **MIGRATE** | Same |
| `README.zh-CN.md` | 9, 24, 46 | Same as above (Chinese) | (f) | **MIGRATE** | Same |
| `README.pt-BR.md` | 9, 24, 46 | Same as above (Portuguese) | (f) | **MIGRATE** | Same |
| `docs/ja-JP/ARCHITECTURE.md` | 24, 115, 449, 561, 637 | Describes Gemini CLI as a live runtime with install paths (`~/.gemini/`), colon-form commands, and a runtime table row | (f) | **MIGRATE** | `docs/ARCHITECTURE.md` (EN) has no such runtime-table row for gemini; only legitimate Antigravity `.gemini/*` path mentions (`:708,995`) |
| `docs/ko-KR/ARCHITECTURE.md` | 24, 118, 487, 615 | Same (Korean) | (f) | **MIGRATE** | Same |
| `docs/ja-JP/COMMANDS.md` | 10, 1241 | "Gemini CLI: `/msd:command-name`" colon-namespace install instructions; `--gemini` reviewer row mixed with stale namespace claim | (f) partial | **MIGRATE** (namespace claim only) | EN `docs/COMMANDS.md` documents `--gemini` only as a reviewer flag (sense b, legitimate); the colon-namespace-install prose is runtime-install language that no longer applies |
| `docs/ko-KR/COMMANDS.md` | 10, 1247 | Same | (f) partial | **MIGRATE** | Same |
| `docs/ja-JP/USER-GUIDE.md` | 39, 674, 751 | "Gemini CLI-only" colon-form install flag, `~/.gemini` config dir table row, non-Claude runtime list including Gemini CLI | (f) | **MIGRATE** | EN `docs/USER-GUIDE.md` has zero gemini mentions |
| `docs/ko-KR/USER-GUIDE.md`, `docs/pt-BR/USER-GUIDE.md`, `docs/zh-CN/USER-GUIDE.md` | (equivalent) | Same pattern | (f) | **MIGRATE** | Same |
| `docs/ja-JP/FEATURES.md` | 1016 | "REQ-RUNTIME-01: system must support Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Antigravity" | (f) | **MIGRATE** (or regenerate — see note) | EN `docs/FEATURES.md` is generated and does not list Gemini as a supported runtime requirement; translations of a generated doc need their own regeneration/translation pipeline, not hand-edits |
| `docs/ko-KR/FEATURES.md`, `docs/zh-CN/FEATURES.md` | (equivalent) | Same | (f) | **MIGRATE** | Same |
| `docs/ja-JP/how-to/set-up-cross-ai-review.md` | 11, 18, 144 | Lists Gemini CLI as one of the review-lane CLIs (legitimate, sense b) but frames install/auth instructions in runtime-like terms | (b), mostly legitimate | **VERIFY, likely PRESERVE** | Reviewer-lane language is legitimate; flagged only because it needs a human check that no install-target framing leaked in — lower priority than the ARCHITECTURE/USER-GUIDE/README hits |
| `docs/ja-JP/how-to/install-on-your-runtime.md` | 49, 55 | "### Gemini CLI" section header with its own install instructions (skills path `~/.gemini/`, restart Gemini CLI) | (f) | **MIGRATE/DELETE** | EN `docs/how-to/install-on-your-runtime.md` has no Gemini CLI section — only Antigravity's `.gemini/antigravity*` dialect notes (`:443,448`). The whole translated section describes a runtime that no longer installs |
| `docs/ko-KR/how-to/install-on-your-runtime.md`, `docs/pt-BR/...`, `docs/zh-CN/...` | (equivalent) | Same | (f) | **MIGRATE/DELETE** | Same |
| `docs/ja-JP/context-monitor.md`, `docs/ko-KR/context-monitor.md`, `docs/pt-BR/context-monitor.md`, `docs/zh-CN/context-monitor.md` | 3, 65 | "Gemini CLI's hook is `AfterTool`" | (c)-adjacent | **VERIFY** | This is describing the hook-event dialect (legitimate, sense c, since Antigravity inherits it) but phrased as "for Gemini CLI" rather than "for the Gemini-family hookEvents dialect (used by Antigravity)" — a wording/attribution nit, not a functional error; low priority |
| `VERSIONING.md` | 133 | `` `gemini-extension.json` — Gemini CLI extension manifest (issue #775) `` | (e)/(f) boundary | **MIGRATE (annotate as removed)** | The file was deleted in `8f2ebbe9bf`; VERSIONING.md is an active reference doc (not a frozen changelog), so this line should either be removed or annotated "(removed #1928)" |
| `bin/install.js` | 1628-1720 | `claudeToGeminiTools` / `convertGeminiToolName` | (c) | **PRESERVE — trap** | Actively used by Antigravity's agent converter; explicitly guarded by `tests/gemini-runtime-removed.test.cjs:53` Coverage C |
| `capabilities/gemini/capability.json` | whole file | Reviewer-lane-only manifest | (b) | **PRESERVE — trap** | Deliberately re-created post-removal; see §1, §2(b) |
| `capabilities/antigravity/capability.json` | 11-15, 31, 40, 56, 78 | `.gemini` configHome/artifactLayout/hookEvents/GEMINI.md | (c) | **PRESERVE — trap** | Antigravity's real on-disk contract; renaming breaks the actual IDE integration |
| `GEMINI.md` (root) | whole file | Antigravity context file | (c) | **PRESERVE — trap** | See §3 |
| `docs/CONFIGURATION.md`, `docs/COMMANDS.md`, `docs/CLI-TOOLS.md`, `docs/reference/capability-matrix.md` (EN) | many | `review.models.gemini`, `--gemini` reviewer flag, model IDs | (b), (d) | **PRESERVE** | Reviewer lane + model catalog, both live and correct |
| `CHANGELOG.md` | many (e.g. 1012, 1281, 1455-1456) | Migration history | (e) | **PRESERVE — locked** | `CHANGELOG.md is Locked` per CLAUDE.md; never hand-edit |
| `.changeset/archived/*gemini*`, `.changeset/archived/*antigravity*` | whole files | Archived fragments | (e) | **PRESERVE** | Immutable release history |
**Not checked exhaustively** (out of budget for this pass, flagged for a follow-up sweep):
`docs/pt-BR/COMMANDS.md`, `docs/pt-BR/CONFIGURATION.md`, `docs/pt-BR/CLI-TOOLS.md`,
`docs/zh-CN/COMMANDS.md`, `docs/zh-CN/CONFIGURATION.md`, `docs/zh-CN/CLI-TOOLS.md`,
`docs/{ja-JP,ko-KR,pt-BR,zh-CN}/how-to/{configure-model-profiles,execute-a-phase,set-up-cross-ai-review,spike-and-sketch,verify-and-ship}.md`,
`docs/{ja-JP,ko-KR,pt-BR,zh-CN}/INVENTORY.md`, `docs/{ja-JP,ko-KR,pt-BR,zh-CN}/CLI-TOOLS.md`. Given
the pattern found in ARCHITECTURE.md/COMMANDS.md/USER-GUIDE.md/FEATURES.md/README across all
four locales, it is highly likely the same "Gemini CLI listed as a live runtime" pattern
recurs in most of these — **UNDETERMINED exact count without a full per-file diff against the
EN originals; estimated 60-100 additional stale lines across the untranslated-drift set**
(the raw `grep -c 'Gemini CLI'` across `docs/pt-BR/ docs/zh-CN/` + the four translated READMEs
alone already returned 61 matches in this pass).
**Estimated total stale (sense-f) reference count: at least 30 confirmed above, likely
100+ once the full ja-JP/ko-KR/pt-BR/zh-CN doc tree is diffed line-by-line against the EN
originals.** This is overwhelmingly a **translation-parity problem**, not a scattered set of
independent bugs — one systemic gap (translations never re-synced after `8f2ebbe9bf`)
accounts for nearly all of it.
## 5. Guards: what catches regressions, and what doesn't
- `tests/gemini-runtime-removed.test.cjs` — **scope is explicitly stated in its own docblock
(`:1-19`)**: (A) the `--gemini` CLI redirect contract, (B) `gemini` gone from
`runtime-name-policy` surfaces (`canonicalizeRuntimeName`, `getRuntimeLabel`,
`getGlobalConfigHomeFragment`, `getRuntimeNewProjectCommand`, `runtimeFlags`,
`getProjectInstructionFile` — all imported at `:44-51`), (C) Antigravity's shared surface
(`GEMINI.md`, `convertGeminiToolName`) survives. **It never reads any file under `docs/` or
any `README.*` translation** — it only spawns the installer and inspects
`runtime-name-policy.cjs`/`capability-registry.cjs`/`install.js` exports. A stale
"Gemini CLI is a supported runtime" sentence in `README.ja-JP.md` cannot fail this test by
construction.
- `tests/product-name-purity.test.cjs:23-41` — scoped to `PRODUCTS`/`README_FILES` and
`findProductParentheticals`: checks that product names aren't mis-glossed parenthetically
(e.g. "Claude (Anthropic's coding agent)" drift), not that a named product is still a live
install target. Different axis entirely.
- `tests/project-instruction-file-parity.test.cjs` — guards that `getProjectInstructionFile`
stays consistent between the new-project workflow and the generate-claude-md path
(CHANGELOG.md:1488). Code-level parity, not prose-level.
- `tests/docs-parity-live-registry.test.cjs:43` (`LOCALES` constant) and
`tests/docs-state-md-locale-parity.test.cjs:30` (`LOCALES` constant) — these **are** the
repo's translation-parity guards, but (per their names and the `docs-guard-registry.cjs`
registration table) they check *structural* parity — that a live registry-derived table
(reviewer flags, STATE.md field reference) is present and enumerated identically across
locales — not that free-form prose describing "which runtimes MSD supports" is factually
current. They would catch a **missing row**, not a **stale but present** row.
- **Missing guard**: there is no test that asserts "no locale doc claims Gemini CLI is an
installable runtime" the way `tests/gemini-runtime-removed.test.cjs` asserts it for the
English surfaces and the installer itself. This is the specific gap that let ~30-100+ stale
translated-doc references slip through three-plus release cycles since `8f2ebbe9bf`
(2026-07-04) to today (2026-09-13).
- Recommended shape for the missing guard (not implemented by this research task, which is
read-only): a locale-parity test that, for each `docs/<locale>/*.md` and `README.<locale>.md`
file, asserts it contains no "Gemini CLI" occurrence outside a reviewer-lane-flag context
(mirroring the EN original's own absence), OR a stronger structural fix — derive the
runtime-list prose (`docs/ARCHITECTURE.md`'s "Claude Code / OpenCode / Kilo / Codex /
Copilot / Antigravity / Trae / Cline / Augment Code" enumeration) from
`runtime-name-policy`'s `allRuntimes` at doc-generation time instead of hand-authoring it in
ten languages independently.
## 6. Ripple / bookkeeping requirements for any fix
Per this repo's own `CLAUDE.md` (project instructions) and repo conventions, a change that
touches the stale references identified in §4 must carry:
- **Changeset required.** `CLAUDE.md` §"CHANGESETS & RELEASE NOTES": drop a fragment in
`.changeset/` via `npm run changeset -- --type <T> --pr <NNN> --body "..."`. Type would be
`Fixed` (docs-only correction of stale claims) per the six allowed types
(`Added|Changed|Deprecated|Removed|Fixed|Security`) — there is no `Documentation` type; a
docs-only fix uses `Fixed`.
- **`CHANGELOG.md` stays locked** — never hand-edit; the changeset renders it.
- **`docs/INVENTORY.md` + manifest regen** if any file is added/removed/renamed:
`node scripts/gen-inventory-manifest.cjs --write` (CLAUDE.md "KNOWN DEFECTS" §"Inventory
Drift"). A pure text edit inside existing translated `.md` files likely does not trigger
this, but deleting a stale section (e.g. the Gemini CLI subsection in
`docs/*/how-to/install-on-your-runtime.md`) does not remove a *file*, so INVENTORY.md
itself is probably unaffected — **UNDETERMINED without running the generator**.
- **Golden install-tree regeneration** — not applicable here; these are prose docs, not
installer output fixtures (`tests/fixtures/install-tree/*.json`,
`tests/fixtures/golden-install-parity/*.json`). No golden fixture references were found to
need regeneration for a docs-only fix.
- **`docs/FEATURES.md` / generated capability fragments** — per this task's own note, these
are generated by `scripts/gen-features.cjs` and the `.cts→.cjs` build; any fix to their
*translated* counterparts (`docs/{ja-JP,ko-KR,zh-CN}/FEATURES.md`) needs to go through
whatever translation/regeneration pipeline produces them (not located/verified in this pass
— **UNDETERMINED**: no `gen-features-<locale>.cjs` or translation-sync script was found by
name; the translated FEATURES.md files may be manually maintained mirrors, which would make
them structurally prone to exactly this kind of drift).
- **Glossary gate** — `CLAUDE.md` "Repo conventions" cites `msd-context-md-glossary-is-a-pr-gate` (per user memory index); `CONTEXT.md` itself mentions Gemini/Antigravity only in the legitimate installer/config-dir sense (`CONTEXT.md:248`) and does not need correction based on this pass.
- **Translation parity** — no dedicated "translation must match EN" gate was found beyond the
narrow structural `LOCALES`-based tests in §5; this is the actual missing-guard finding.
- **ADR requirement** — a prose/docs correction of this kind (removing stale claims,
no behavior change) does not meet the bar for "every bug-fix and feature change requires
ADR" in the sense `docs/adr/` uses (ADRs there are architectural decisions, not doc
corrections); **no new ADR is required** for fixing the stale references themselves. An ADR
would only be warranted if the *fix* itself introduced a new mechanism (e.g. a
runtime-list-derived doc generator).
## Scope note
This document is read-only research. No source file other than this one was modified. The
`docs/{ja-JP,ko-KR,pt-BR,zh-CN}` files listed as MIGRATE in §4 were identified but **not
edited** — remediation is a separate, subsequent change subject to the ripple requirements in
§6.
---
## 7. Addendum — the severest class the §4 sweep missed: live workflow behavior
§4 concluded the residue is "overwhelmingly a translation-parity problem". That is true by
*count*, but not by *severity*. Runtime-loaded workflow text under `msd-core/workflows/` still
assigns and offers the retired `gemini` runtime id, and the name policy resolves that id to
**Claude Code** instead of failing loudly.
### 7.1 Measured: an unknown runtime id resolves to a safe-looking known
Executed against `next@c0b2a05d2f`:
```
canonicalizeRuntimeName('gemini') = null
getProjectInstructionFile('gemini') = "AGENTS.md"
getRuntimeLabel('gemini') = "Claude Code"
getGlobalConfigHomeFragment('gemini') = "'.claude'"
getGlobalConfigDir('gemini') = ~/.claude
getGlobalConfigDir('antigravity') = ~/.gemini/antigravity
```
`gemini` is correctly non-canonical, so `tests/gemini-runtime-removed.test.cjs` Coverage B
passes. But the other accessors do not reject it — they fall through to Claude Code defaults.
A stale `RUNTIME="gemini"` therefore produces a *plausible wrong answer* rather than an error:
the Claude config dir, the label "Claude Code", and `AGENTS.md` as the instruction file.
Note `AGENTS.md` also contradicts the workflow's own documented claim at
`msd-core/workflows/new-project.md:1216` and `:1238` ("`GEMINI.md` for gemini/antigravity").
The prose and the policy disagree about the same retired id.
### 7.2 The live assignment sites that reach it
| File | Line | Text | Verdict |
|---|---|---|---|
| `msd-core/workflows/new-project.md` | 76 | `` Path contains `/.gemini/` → `RUNTIME=gemini` `` | **MIGRATE** — `~/.gemini` is Antigravity's parent; the only live child is `~/.gemini/antigravity` |
| `msd-core/workflows/new-project.md` | 84 | `elif [ -n "$GEMINI_CONFIG_DIR" ]; then RUNTIME="gemini"` | **MIGRATE** — live shell branch minting a non-canonical id that silently resolves to Claude Code (§7.1) |
| `msd-core/workflows/new-project.md` | 576 | "required for non-Claude runtimes: Codex, Gemini CLI, OpenCode…" | **MIGRATE** — names a sunset product as a supported runtime |
| `msd-core/workflows/new-project.md` | 1216, 1238 | "`GEMINI.md` for gemini/antigravity" | **MIGRATE** — drop `gemini/`; keep `antigravity` |
| `msd-core/workflows/settings-advanced.md` | 412 | `{ label: "gemini", description: "Gemini CLI." }` | **MIGRATE** — a user-facing `AskUserQuestion` menu still **offers Gemini CLI as a selectable runtime** |
| `msd-core/workflows/settings-advanced.md` | 393 | "Common runtimes: claude, codex, gemini, qwen" | **MIGRATE** |
| `msd-core/workflows/settings-advanced.md` | 360 | model-profile table row keyed `gemini` (runtime axis) | **MIGRATE** — the row key is the retired runtime; the `gemini-*` model IDs in it are legitimate (sense d) |
| `msd-core/workflows/settings-advanced.md` | 510-512 | `config-set runtime gemini`, `model_profile_overrides.gemini.*` | **MIGRATE** — documented examples that set a non-canonical runtime |
| `msd-core/workflows/settings-advanced.md` | 673-675 | `google` provider rows | **PRESERVE** — provider axis, not runtime |
| `msd-core/workflows/reapply-patches.md` | 62-63, 91-92, 101 | probes `$GEMINI_CONFIG_DIR` and `~/.gemini/msd-local-patches`; bare `.gemini` in the dir scan | **MIGRATE** — same class as #4347 but **hand-written, so `npm run sync:launcher` does not reach it** |
| `msd-core/workflows/update.md` | 77, 135, 276, 277, 315 | bare `~/.gemini/` / `./.gemini/` as a runtime config dir | **MIGRATE** — the live dir is `~/.gemini/antigravity` |
| `msd-core/workflows/update.md` | 466 | dir scan list including bare `.gemini` | **MIGRATE** |
| `msd-core/workflows/update.md` | 17, 466 | `.gemini/antigravity{,-ide,-cli}` → `antigravity` | **PRESERVE** |
These are **not** doc-only paths for gating purposes: `pre-pr-gate.sh`'s `DOC_ONLY_RE` anchors
its `*.md` arm at repo root only, so `msd-core/workflows/*.md` is gated code.
### 7.3 Second, un-migrated launcher generation
`commands/msd/graphify.md:83,100,125,144,164` and `skills/msd-graphify/SKILL.md` carry an
**older** launcher form (the long `elif [ -f … ]` chain) than the compact `_msd_at` form in
`msd-core/workflows/_runtime-launcher.snippet.sh:1`. Both generations carry the
`${GEMINI_CONFIG_DIR:-$HOME/.gemini}` arm. Any fix that only re-runs the launcher sync will
therefore miss the graphify copies — a generative-fix divergence hazard.
### 7.4 Consequence for the guard design
The missing guard proposed in §5 was scoped to locale prose. It must also cover code and
runtime-loaded workflow text, and the cheapest durable form is to make the name policy
**fail loud** on a non-canonical id rather than defaulting to Claude Code — which would have
turned every site in §7.2 into a hard error on the day #1928 landed.
---
## 8. Addendum — 2026-09-14 (#4727): §2(c) narrowed, deliberately
Everything above §8 is pinned to `next` at `c0b2a05d2f` and is left byte-for-byte intact on
purpose: §1 quotes #1928's commit message verbatim and §2(a) quotes a test docblock verbatim, so
rewriting either to match a later tree would falsify a primary source. The delta is recorded here
instead.
### This overturns a verdict recorded above. Saying so plainly.
§2(c) is headed **"MUST NOT be renamed"**, and the §6 PRESERVE table files
`claudeToGeminiTools` / `convertGeminiToolName` under category (c) with the verdict
**"PRESERVE — trap"**. #4727 renamed them anyway:
| before | after |
|---|---|
| `claudeToGeminiTools` | `claudeToAntigravityTools` |
| `convertGeminiToolName` | `convertAntigravityToolName` |
That is a **narrowing of (c), not compliance with it**, and the earlier verdict was too broad
rather than wrong. (c)'s real subject is the part of the Gemini surface that Google owns — the
directories, the hook dialect, `GEMINI.md`, the model ids, and, for these two symbols
specifically, the **mapped values**:
```
read_file write_file replace run_shell_command glob
search_file_content google_web_search web_fetch write_todos
```
Those are Gemini's built-in tool names, Antigravity genuinely speaks that dialect, and they remain
byte-identical — the "trap" the table warned about is real and still stands for them. What (c) had
swept in along with them were two **MSD-chosen identifiers**, which no external contract references.
Renaming those breaks nothing and removes a name that had outlived its runtime by more than a year.
Superseded rows, named explicitly so a later reader is not misled: §2(c)'s
"Shared tool-name vocabulary" bullet (~`:55`) and the §6 PRESERVE table row for `bin/install.js`
(~`:136`) both cite `bin/install.js:1628-1720` under the old identifiers. The cited line range is
still correct; only the two names are now the Antigravity-prefixed ones.
### One citation above now reproduces superseded wording
§2(a) (~`:40`) quotes the `tests/gemini-runtime-removed.test.cjs` docblock verbatim, including the
phrase *"the shared convertGeminiToolName tool vocabulary"*. #4727 reworded that docblock to name
the live symbol, so **the quotation no longer matches its source**. Disclosed rather than silently
edited, because editing the quote is precisely what this addendum exists to avoid. The docblock had
to move: leaving it would have made the repo's #1928 guard describe a symbol that no longer exists.
### What was NOT renamed, and one coverage gap
Untouched: `~/.gemini/antigravity{,-ide,-cli}` and `~/.gemini` as their parent; `~/.gemini/config`
(#3738); `GEMINI.md` as `projectInstructionFile`; `hookEvents: "gemini"`; every `gemini-*` /
`google/gemini-*` model id and `providerPresets.google`; the `--gemini` **installer** flag, which
remains #1928's sunset redirect; the `GEMINI_CONFIG_DIR` launcher arm (epic #4632). `bin/install.js`
still carries 36 `gemini` references after the rename, which is the correct number.
The symbol existed **twice** — the extracted copy in `src/runtime-artifact-conversion.cts` (and that
module's `export =` block, added by #1182 as a dependency closure) plus a working inline copy in
`bin/install.js`. `CLAUDE.md` labels that file "(generated)", but no `package.json` script emits it;
`build:lib` is `tsc -p tsconfig.build.json` and writes `msd-core/bin/lib/**` only. Both copies were
renamed, since renaming one would have left two names for one concept.
**Known gap:** the `bin/install.js` half is test-unprotected. That file exports none of the four
identifiers, and the export audit asserts `installer[name] === undefined` for both spellings, so
reverting that half would break no test — its behavior is covered, its *naming* is not. Closing that
requires the repo-wide drift guard (#4729), which is the last phase of this epic for exactly this
reason.
Reference in New Issue View Git Blame Copy Permalink