/gaia-bridge-enable

What it does

/gaia-bridge-enable turns on the Test Execution Bridge by setting test_execution_bridge.bridge_enabled = true in .gaia/config/project-config.yaml.

Enabling the bridge is necessary but not sufficient. Tests run in reviews only when test_execution.tier_N.command is also populated (see /gaia-config-test). Without that wiring, qa-test-runner.sh skips with a HARD-FAIL instead of false-green — the bridge flag alone does not dispatch execution. Use, for example, /gaia-config-test set tier_1.command 'python3 -m pytest tests/ -q' to wire the command. The runners declared in .gaia/config/test-environment.yaml are the second half of the contract: they describe the runtime surface (image / binary / port) that the configured command runs against.

The command is idempotent: invoking it when the bridge is already enabled reports the state and exits without writing. It also performs three side effects that the previous version did not:

• Migrates the legacy manifest path. If a file exists at the pre-v1.157.0 location .gaia/artifacts/test-artifacts/test-environment.yaml, it is moved to the canonical config/test-environment.yaml. The move is idempotent and emits a one-time deprecation warning.
• Auto-generates the manifest when absent. If no manifest exists at the canonical path, Step 4 offers to generate a stack-specific one inline. No separate /gaia-brownfield invocation is required.
• Surfaces the manifest summary. On a successful enable, Step 5 prints the canonical path, the generated runners, and (when the manifest was just generated) an “edit to fine-tune for your project” nudge.

When to use it

• You want to enable real test execution during development workflows.
• You set up a test runner and want to connect it to GAIA.
• You are onboarding an existing project and want to enable the bridge without running the full /gaia-brownfield flow.

Prerequisites

• The test_execution_bridge configuration block must exist. Run /gaia-config-ci first if it does not.
• A project root. The command operates on the directory containing .gaia/config/project-config.yaml.

How to invoke

/gaia-bridge-enable

No arguments. State is read from .gaia/config/project-config.yaml and behaviour adapts to the current presence or absence of config/test-environment.yaml.

What it does step by step

1. Read current state Reads the bridge_enabled flag from .gaia/config/project-config.yaml.
2. Check idempotency If already enabled, reports the state and exits without writing.
3. Flip the flag Sets bridge_enabled from false to true, preserving all comments and formatting.
4. Post-flip checks (resolve the manifest) Stats config/test-environment.yaml. Three outcomes drive the next behaviour: present and valid (proceed), present but invalid (surface schema errors as warnings; do not roll back the enable flag), or absent (offer the manifest options below).
5. Report Prints a summary including the canonical manifest path, the detected runners (when present), and an “edit config/test-environment.yaml to fine-tune for your project” nudge when the manifest was just generated in this invocation.

Manifest options (Step 4)

When the manifest is absent, the command presents two options:

Under YOLO mode the command auto-selects option [a]. If the auto-generator helper itself exits non-zero (a defensive fallback case), Step 4 falls back to option [b]'s template-copy behaviour and emits a warning rather than crashing.

Inputs

This command takes no arguments. State is read from:

• .gaia/config/project-config.yaml (the bridge_enabled flag and CI block)
• config/test-environment.yaml (presence, schema, sentinel state)
• .gaia/artifacts/test-artifacts/test-environment.yaml (legacy path; migrated if present)
• Project tree (consulted by the auto-generator to detect the stack)

Outputs

Example session

First invocation on a Python project with no manifest:

> /gaia-bridge-enable

Bridge enabled. Test execution bridge is now active.

Manifest: config/test-environment.yaml does not exist.

  [a] Auto-generate a stack-specific manifest (recommended)
  [b] Copy the schema example template

Choice: a

Auto-generated config/test-environment.yaml for detected stack: python.

  Path:    config/test-environment.yaml
  Runners: unit (tier 1), integration (tier 2)

edit config/test-environment.yaml to fine-tune for your project

Idempotent re-invocation:

> /gaia-bridge-enable

Bridge already enabled.

Invocation that migrates a legacy manifest:

> /gaia-bridge-enable

Detected legacy manifest at .gaia/artifacts/test-artifacts/test-environment.yaml.
Moved to config/test-environment.yaml.
DEPRECATION: the legacy path will be removed in a future release.

Bridge enabled. Test execution bridge is now active.

  Path:    config/test-environment.yaml
  Runners: unit (tier 1), e2e (tier 3)

What to run next

• Review and edit the manifest. Open config/test-environment.yaml and verify the runners and timeouts match your project. The full schema reference, every field, and copy-ready examples for all seven supported stacks live on the dedicated reference page.
• Link runners to promotion-chain environments (optional, schema v2). Add promotion_chain_env_id to each runner to inherit CI provider and branch context from ci_cd.promotion_chain. Edit the chain itself with /gaia-ci-edit.
• Run a development workflow. Tests will now be dispatched to the configured runners. Start with /gaia-atdd or any review command (/gaia-review-all).

Troubleshooting

test_execution_bridge block missing

The configuration block does not exist. Run /gaia-config-ci to set up CI, which creates this block.

Sentinel still present after generation

The manifest contains the # GAIA-MANIFEST-TEMPLATE: … line and Layer 0 refuses to run tests. The literal output from check-manifest-sentinel.sh is:

Layer 0 readiness FAILED: config/test-environment.yaml contains the unmodified-template sentinel (GAIA-MANIFEST-TEMPLATE). Either run /gaia-bridge-enable to regenerate against current detection signals, or edit config/test-environment.yaml directly to populate stack-specific runners.
bridge_status: manifest_unmodified_template

This happens when no stack was detected (generic make test placeholder was emitted) or when you selected option [b]. Customise the runners using a stack-specific example, then delete the sentinel line. Re-run /gaia-bridge-enable to re-evaluate. The bridge_status: manifest_unmodified_template line is a stable machine-readable key you can grep for in CI logs.

Schema validation failed

The manifest exists but does not parse against the schema. The command surfaces the validation errors and prints the canonical path so you know where to look. The bridge_enabled flag is not rolled back — fix the file and re-evaluate. See manifest troubleshooting for common schema mistakes.

Generator failed, fell back to template-copy

The auto-generator helper exited non-zero (most commonly: jq not installed, or detect-signals.sh missing). The command falls back to option [b]'s template-copy and emits a warning. Install the missing prerequisite, delete the fallback manifest, and re-run to get a stack-specific manifest.

Legacy manifest at .gaia/artifacts/test-artifacts/

You should not see this as a problem — the migration is automatic on first invocation. If the move appeared to fail, inspect the stderr output of the migration helper and move the file by hand: mv .gaia/artifacts/test-artifacts/test-environment.yaml config/test-environment.yaml.

Related commands