/gaia-config-gates

user-facing
Category:
Configuration
Lifecycle phase:
4 -- Implementation
Arguments:
<set|show|clear> <gate> [<internal> <verdict>]

What it does

/gaia-config-gates edits the gates section of .gaia/config/project-config.yaml -- the per-gate severity overrides. Each review gate (e.g., code-review, qa-tests, security-review) can override the global severity map with its own 5-into-3 mapping. When a per-gate override is absent for a given severity level, the global severity map wins by fall-through.

The editor preserves all YAML comments and formatting outside the edited section.

Fall-through semantics

When a review gate composes its verdict, the severity-to-verdict lookup follows this precedence:

  1. Per-gate override present -- the gate's own override wins.
  2. Per-gate override absent -- falls through to the global severity map.
  3. Neither present -- system defaults apply (APPROVE for Info and Low, REQUEST_CHANGES for Medium, BLOCKED for High and Critical).

When to use it

  • You want a specific review gate to be stricter or more lenient than the global severity map.
  • You want to view or remove per-gate severity overrides.

Prerequisites

  • project-config.yaml must exist. Run /gaia-init to create one if missing.

How to invoke

/gaia-config-gates show security-review
/gaia-config-gates set security-review Medium BLOCKED
/gaia-config-gates set code-review Low REQUEST_CHANGES
/gaia-config-gates clear security-review

What it does step by step

  1. Locate project-config.yaml Resolves the configuration file path via the canonical resolver.
  2. Dispatch subcommand Routes to the deterministic helper script:
    • set <gate> <internal> <verdict> -- set or replace a single per-gate mapping. Creates the gate block and the gates section if absent.
    • show <gate> -- print the current override map for the named gate, or "no overrides" when absent.
    • clear <gate> -- remove the named gate's override block. If no gates remain, removes the gates section.
  3. Suggest validation Recommends running /gaia-config-validate to confirm the file still passes schema validation.

Inputs

InputSourceDescription
Project configuration.gaia/config/project-config.yamlThe file containing the gates section.

Outputs

OutputLocationDescription
Updated gates section.gaia/config/project-config.yamlThe modified gates block (comment-preserving).

Example session

> /gaia-config-gates show security-review

no overrides for gate: security-review (falls through to global severity map)

> /gaia-config-gates set security-review Medium BLOCKED

gates section updated. Run /gaia-config-validate to verify.

> /gaia-config-gates show security-review

gates.security-review:
  Medium: BLOCKED
  (all other severities fall through to global map)

What to run next

Troubleshooting

no gates section

The section does not exist in your config file. The set subcommand creates it automatically on first write.

Invalid internal severity name

Only the closed set Critical, High, Medium, Low, Info is accepted. Any other value is rejected with exit 1.

Invalid verdict value

Only BLOCKED, REQUEST_CHANGES, APPROVE are accepted. Any other value is rejected with exit 1.

Unknown gate name warning

Gate names follow the kebab-case pattern. Unknown gate names produce a warning but proceed -- the gate registry is open to support custom review gates.