# Bellona Bridge Retirement Gate

Status: local gate contract for `180.C.38.07`, `180.C.38.08`, `180.C.38.09`, and
`180.C.38.10`.

Implementation date: 2026-07-02.

`testing/bellona/remote-control/bridge-retirement-gate.ts` encodes the final
retirement contract for the old Blender and Unreal bridges. It does not remove
the bridges and does not claim retirement has happened. It blocks by default
until removal PRs, zero-consumer telemetry, package cleanup, post-removal
verification, documentation updates, and final approval evidence are all
attached.

## Covered Checklist Items

- `180.C.38.07`: removal PRs for `bridge-blender` and `bridge-unreal`, each with
  a canonical Oshun GitHub PR URL, non-draft submission state, bridge-specific
  migration-path and release-note links, plus a cutover-aware merge block.
- `180.C.38.08`: post-removal verification proving no service, test, script, or
  workspace dependency still uses the old bridges.
- `180.C.38.09`: cleanup of the old bridge app packages after Remote Host GA and
  zero-consumer proof.
- `180.C.38.10`: final roll-up after bridge retirement, documentation updates,
  merged removal PRs, and contextual bridge-retirement approver approval.

## Required Evidence

- Stage prerequisites: `180.C.29.10` and `180.C.38.01` through `.06`.
- Exactly one removal PR evidence record for each old bridge app; PR URLs must
  use the canonical `https://github.com/GreyChimp/oshun/pull/<number>` shape,
  submission timestamps must be on or after the local Stage 38 evidence contract
  date, migration paths must match
  `docs/domains/bellona/extras/remote-control/<bridge-id>-migration.md`, and
  release-note paths must match
  `docs/releases/2026-10-bridge-retirement-<bridge-id>.md`. Duplicate or
  conflicting PR records, or bridge records that reuse the same PR, migration,
  or release-note URL, do not satisfy the gate.
- Merged removal PR evidence before final roll-up, with merge timestamps on or
  after the cutover-aware merge block.
- Exactly one zero-consumer telemetry report for each old bridge, covering at
  least 30 consecutive days after the `2026-10-21` cutover anchor, with a
  distinct telemetry source rooted under
  `s3://oshun-release-evidence/180.C.38/<bridge-id>/` and a concrete
  non-placeholder source suffix.
- Exactly one per-command zero-consumer telemetry record for every
  compatibility-only command in the bridge coexistence plan, with no duplicate
  records, no unknown legacy command names, and zero production consumers for
  every record.
- Package cleanup evidence for `apps/bellona/bridge-blender` and
  `apps/bellona/bridge-unreal`, including exact removed app-path and package
  sets with no duplicate or unrelated removals, a canonical Oshun cleanup PR
  URL, and a workspace reference scan command using `rg`/`git grep` that targets
  the exact legacy bridge package names and app paths across apps, libraries,
  services, scripts, tests, and root workspace metadata as exact command targets
  rather than substring matches. Allowed residual reference paths must be unique
  docs or release-note paths, including case variants; active app, library,
  service, script, test, or workspace dependency paths cannot be whitelisted
  directly or through path traversal as allowed residual references. Cleanup
  completion timestamps must be on or after merged removal PRs and each bridge's
  zero-consumer telemetry window end.
- Post-removal scan output for apps, libraries, services, scripts, testing
  harnesses, and workspace metadata using an `rg`/`git grep` command that
  targets the exact legacy bridge package and path references plus root
  workspace metadata files.
- Documentation update confirmation and final retirement approval with a
  `operator:bridge-retirement-approver:` identity with a concrete
  non-placeholder approver suffix, notes, and an approval timestamp that is on
  or after the cutover anchor, every required removal PR submission and merge
  timestamp, every zero-consumer telemetry window end, the cleanup completion
  timestamp, and the post-removal verification run.

## Local Evaluator

The testing package exposes:

- `createRemoteControlBridgeRetirementGatePlan()`
- `createPassingRemoteControlBridgeRetirementEvidenceSnapshot()`
- `evaluateRemoteControlBridgeRetirementGate()`

The evaluator returns `blocked` without evidence. It only returns `passed` when
every Stage 38 retirement requirement is attached, including a post-removal scan
that explicitly covers apps, libraries, services, scripts, testing harnesses,
and workspace metadata. Duplicate PR, bridge telemetry, or command telemetry
records, reused per-bridge PR URLs or telemetry sources, non-canonical PR,
migration, release-note, telemetry, cleanup, or approver identities, placeholder
telemetry source or bridge-retirement approver suffixes, scan commands that do
not use a reference scanner, commands that omit or only partially cover
workspace metadata, commands that do not target exact legacy bridge package/path
references, cleanup records that whitelist active workspace dependency paths
directly or through path traversal as allowed residual references, cleanup
records with duplicate or unrelated removed bridge entries, stale removal
submissions, premature merges, cleanup timestamps that predate merged removal
PRs or zero-consumer telemetry, any non-canonical UTC millisecond retirement
timestamps, and final approvals that predate any required retirement evidence
are treated as incomplete evidence so conflicting, generic, placeholder, stale,
or overbroad records cannot mask a retirement blocker. This is intentionally
separate from the coexistence plan: coexistence proves the old bridges can stay
alive safely during rollout; the retirement gate proves they can be removed.

## Verification

```bash
pnpm exec vitest run --config vitest.config.ts tests/bridge-retirement-gate.test.ts --reporter=verbose
```

Focused coverage currently passes with 1 file / 34 tests and proves:

- the plan lists Stage `180.C.38.07` through `.10`, bridge IDs, cutover, and
  scan scope;
- the gate blocks by default instead of treating coexistence as retirement
  evidence;
- the gate passes only with complete PR, telemetry, cleanup, verification,
  documentation, and approval evidence;
- missing release-note or migration evidence blocks `180.C.38.07`;
- draft PR evidence blocks `180.C.38.07`, and unmerged PR evidence blocks
  `180.C.38.10`;
- stale removal submission timestamps, premature merge timestamps, and cleanup
  timestamps that predate zero-consumer evidence block `180.C.38.07`, `.08`,
  `.09`, and `.10` as applicable;
- non-canonical UTC millisecond PR, telemetry, cleanup, post-removal scan, and
  final approval timestamps block the relevant Stage 38 gates;
- duplicate removal PR evidence blocks `180.C.38.07` and the merged-removal
  roll-up;
- reused PR URLs across bridge removal records block `180.C.38.07`;
- non-canonical removal PR, migration, release-note, and cleanup PR artifacts
  block `180.C.38.07`, `180.C.38.08`, and `180.C.38.09`;
- nonzero or unknown compatibility-command telemetry blocks `180.C.38.09`;
- duplicate bridge telemetry reports block `180.C.38.09`;
- reused telemetry sources across bridge zero-consumer records block
  `180.C.38.09`;
- telemetry sources that are not rooted under the matching bridge evidence path
  and final approvals without `operator:bridge-retirement-approver:` identities
  block `180.C.38.09` and `180.C.38.10`;
- placeholder telemetry source and bridge-retirement approver contextual
  suffixes block `180.C.38.09` and `180.C.38.10`;
- duplicate compatibility-command telemetry records block `180.C.38.09`;
- telemetry windows that do not cover the post-cutover zero-consumer interval
  block `180.C.38.09`;
- missing package cleanup evidence blocks `180.C.38.09`;
- package cleanup evidence with duplicate or unrelated removed bridge paths or
  package names blocks `180.C.38.08` and `180.C.38.09`;
- package cleanup evidence cannot whitelist active workspace bridge references
  directly, through path traversal, or as case-variant duplicate allowed
  residual references;
- active post-removal dependency findings block `180.C.38.08` and the final
  roll-up.
- cleanup and post-removal scan commands that do not target legacy bridge
  package/path references block `180.C.38.08` and `180.C.38.09`.
- cleanup and post-removal scan commands that use bridge wildcards without exact
  package and app path targets block `180.C.38.08` and `180.C.38.09`.
- cleanup and post-removal commands that only echo bridge tokens or scanner
  names, or omit or only partially cover root workspace metadata files block
  `180.C.38.08` and `180.C.38.09`.
- cleanup and post-removal commands that mention exact bridge references, scan
  scopes, or workspace metadata only as substrings block `180.C.38.08` and
  `180.C.38.09`.
- missing post-removal scan scopes for apps, libraries, or testing harnesses
  block `180.C.38.08`.
- final approval timestamps that predate post-removal evidence block
  `180.C.38.10`.
- incomplete final approval metadata blocks `180.C.38.10`.
