gaia-framework 1.105.1 → 1.127.2

package/.claude/commands/gaia-bridge-disable.md

@@ -0,0 +1,18 @@
+---
+name: 'bridge-disable'
+description: 'Disable the Test Execution Bridge in global.yaml.'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/core/workflows/bridge-toggle/workflow.yaml as 'workflow-config'
+4. Set parameter: --mode disable
+5. Follow workflow.xml instructions EXACTLY
+6. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-bridge-enable.md

@@ -0,0 +1,18 @@
+---
+name: 'bridge-enable'
+description: 'Enable the Test Execution Bridge in global.yaml.'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/core/workflows/bridge-toggle/workflow.yaml as 'workflow-config'
+4. Set parameter: --mode enable
+5. Follow workflow.xml instructions EXACTLY
+6. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-fill-test-gaps.md

@@ -0,0 +1,17 @@
+---
+name: 'fill-test-gaps'
+description: 'Read gap report, triage by severity and story, propose remediation actions. Use when "fill test gaps".'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/testing/workflows/fill-test-gaps/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/CLAUDE.md

@@ -140,17 +140,34 @@ backlog → validating → ready-for-dev → in-progress → invalid → review
 ```
 
 **Review Gate:** A story in `review` requires ALL six reviews to pass before moving to `done`:
-- `/gaia-code-review` — APPROVE or REQUEST_CHANGES
+- `/gaia-code-review` — PASSED or FAILED
 - `/gaia-qa-tests` — PASSED or FAILED
 - `/gaia-security-review` — PASSED or FAILED
 - `/gaia-test-automate` — PASSED or FAILED
 - `/gaia-test-review` — PASSED or FAILED
 - `/gaia-review-perf` — PASSED or FAILED
 
+**Gate status vocabulary** (canonical, enforced by `/gaia-validate-story`): `UNVERIFIED` (default, not yet run) | `PASSED` (review passed) | `FAILED` (review failed). No other values are permitted in the Review Gate table. Code Review uses `APPROVE`/`REQUEST_CHANGES` as its internal verdict keyword in the report body, but writes `PASSED`/`FAILED` to the Review Gate row.
+
 Run `/gaia-run-all-reviews` to execute all six reviews sequentially via subagents — one command instead of six.
 
 If any review fails, the story returns to `in-progress`. The Review Gate table in the story file tracks progress.
 
+### Review Gate-to-Tier Mapping (E17-S12, FR-195)
+
+When the Test Execution Bridge (ADR-028) is enabled, each review gate is linked to a set of test tiers (from the E17-S11 three-tier model) whose evidence is required to produce a PASSED verdict. The canonical mapping lives in `Gaia-framework/src/bridge/review-gate-tier-mapping.js` (`DEFAULT_GATE_TIER_MAPPING`) and can be overridden per-project via the `tiers.gate_mapping` block in `test-environment.yaml`.
+
+| Review Gate | Required Tiers |
+|---|---|
+| `/gaia-qa-tests` | Tier 1 + Tier 2 (unit + integration) |
+| `/gaia-test-automate` | Tier 1 (unit) |
+| `/gaia-test-review` | Tier 2 (integration) |
+| `/gaia-review-perf` | Tier 3 (e2e) |
+| `/gaia-security-review` | Tier 2 + Tier 3 (integration + e2e) |
+| `/gaia-code-review` | no tier (static analysis only) |
+
+When a gate is UNVERIFIED, the Nudge Block surfaces the required tiers (e.g., "run Tier 1 + Tier 2 tests") via `formatNudgeSuggestion(gate, mapping)`. Full rationale and override semantics live in architecture §10.20.4.
+
 ### Infra Review Gate Substitutions
 
 For infrastructure stories (those whose `traces_to` field contains `IR-###`, `OR-###`, or `SR-###` requirement IDs), 4 of the 6 review gates use adapted criteria. Code Review and Security Review remain unchanged for all story types.
@@ -166,6 +183,52 @@ For infrastructure stories (those whose `traces_to` field contains `IR-###`, `OR
 
 **Detection mechanism:** The `review-gate-check` protocol reads the story's `traces_to` field and checks the requirement ID prefix. Each story is evaluated independently — platform projects with mixed stories get per-story gate selection based on their own requirement prefix.
 
+## Bridge Scope
+
+The Test Execution Bridge (ADR-028, architecture §10.20) orchestrates test runs ONLY. The bridge does not deploy services, does not modify databases, and does not alter any infrastructure. This is a hard scope constraint enforced in code (FR-203) and must be preserved in every future change.
+
+**Supported stacks (built-in adapters, architecture §10.20.11):**
+
+The bridge ships with five static-import stack adapters, selected automatically by `getAdapter()` in `Gaia-framework/src/bridge/adapters/index.js`. Priority order is deterministic: `javascript → python → java → go → flutter`.
+
+| Stack | Representative runner command | Detection pattern |
+|---|---|---|
+| JavaScript / TypeScript | `npx vitest run` (also `npm test`, Jest, Mocha, TAP) | `package.json` |
+| Python | `pytest` | `pyproject.toml` / `pytest.ini` / `setup.cfg` / `setup.py` |
+| Java | `mvn test` (also `gradle test`) | `pom.xml` / `build.gradle` |
+| Go | `go test ./...` | `go.mod` |
+| Flutter / Dart | `flutter test` | `pubspec.yaml` |
+
+Adding a new stack adapter is documented in `docs/architecture/bridge-adapter-contract.md`. External / dynamic adapter loading is explicitly out of scope (architecture §10.20.11.4, threat T37).
+
+**The bridge DOES:**
+- Invoke project-owned test runners via standard CLI commands — one adapter per stack, one representative runner shown per row above
+- Trigger a single CI workflow declared in `test-environment.yaml` via `gh workflow run`
+- Poll the CI run until terminal state and fetch the run log
+- Parse runner/CI output into the `test-results/{story_key}-execution.json` evidence schema
+- Reject commands containing shell chaining operators (`;`, `&&`, `||`, `|`, `>`, `<`) outside of quoted arguments
+- Reject any command not explicitly allowlisted from `test-environment.yaml` runners or the `package.json` test script
+
+**The bridge DOES NOT:**
+- Deploy services, applications, or container images
+- Provision, modify, or tear down infrastructure (no `terraform apply`, no `kubectl apply`, no `docker run -d`)
+- Alter databases (no migrations, no seed scripts, no schema changes)
+- Commit code, push branches, or mutate the git repository
+- Execute arbitrary shell commands or shell substitution (`` ` `` and `$()` are always rejected)
+- Trigger any GitHub Actions workflow other than the `ci_workflow` declared in `test-environment.yaml`
+
+**Enforcement points:**
+- `Gaia-framework/src/bridge/bridge-scope-guard.js` — shared scope guard module exporting `assertInScope`, `assertCommandAllowed`, `assertCiWorkflowAllowed`
+- Layer 2 local execution (`layer-2-local-execution.js`) calls all three guards before `spawn`
+- Layer 2 CI execution (`layer-2-ci-execution.js`) calls the shell-operator guard on the runner command and the CI workflow allowlist guard before `gh workflow run`
+
+**Threat model:** Architecture §10.20.10 enumerates the five bridge threats:
+- **T20** — Environment misconfiguration (runner declared in `test-environment.yaml` does not match project stack). Mitigated by Layer 0 readiness checks and `assertCommandAllowed`.
+- **T21** — Runner discovery failure (Layer 1 cannot match story key to test files). Mitigated by structured Layer 1 failure + `bridge_status: runner_not_found` evidence fallback.
+- **T22** — Execution timeout (subprocess or CI workflow hangs). Mitigated by NFR-033 configurable timeout + SIGTERM/SIGKILL escalation.
+- **T23** — Subprocess runaway via shell injection (chaining/substitution/redirection operators). Mitigated by `assertInScope` scope guard.
+- **T24** — CI API unavailability (`gh` missing, auth expired, network failure). Mitigated by `defaultGhCheck` probe and local fallback + `assertCiWorkflowAllowed` on the fallback workflow.
+
 ## Memory Hygiene
 
 Agent memory sidecars accumulate decisions across sessions. Run `/gaia-memory-hygiene` periodically (recommended before each sprint) to detect stale, contradicted, or orphaned entries by cross-referencing sidecar decisions against current planning and architecture artifacts.

package/_gaia/_config/gaia-help.csv

@@ -51,6 +51,8 @@ module,phase,name,code,command,required,agent-name,description,output-location
 "testing","anytime","test-review","test-review","gaia-test-review","false","test-architect","Review test quality","docs/test-artifacts"
 "testing","anytime","nfr-assessment","nfr","gaia-nfr","false","test-architect","Assess non-functional requirements","docs/test-artifacts"
 "testing","anytime","traceability","trace","gaia-trace","false","test-architect","Generate traceability matrix","docs/test-artifacts"
+"testing","anytime","test-gap-analysis","test-gap-analysis","gaia-test-gap-analysis","false","test-architect","Scan test suite against requirements to identify coverage gaps","docs/test-artifacts"
+"testing","4-implementation","fill-test-gaps","fill-test-gaps","gaia-fill-test-gaps","false","test-architect","End-to-end remediation for test-gap-analysis findings (sub-workflow composition)","docs/test-artifacts"
 "lifecycle","3-solutioning","security-threat-model","threat-model","gaia-threat-model","false","security","Create STRIDE/DREAD threat model","docs/planning-artifacts"
 "lifecycle","4-implementation","security-review","security-review","gaia-security-review","false","security","Pre-merge OWASP security review","docs/implementation-artifacts"
 "lifecycle","3-solutioning","infrastructure-design","infra-design","gaia-infra-design","false","devops","Design deployment topology and IaC","docs/planning-artifacts"

package/_gaia/_config/global.yaml

@@ -3,7 +3,7 @@
 # After modifying this file, run /gaia-build-configs to regenerate resolved configs.
 
 framework_name: "GAIA"
-framework_version: "1.105.1"
+framework_version: "1.127.2"
 
 # User settings
 user_name: "jlouage"
@@ -48,3 +48,16 @@ installed_path: "{project-root}/_gaia"
 config_path: "{project-root}/_gaia/_config"
 memory_path: "{project-root}/_memory"
 checkpoint_path: "{project-root}/_memory/checkpoints"
+
+# Test Execution Bridge (ADR-028, FR-202, NFR-035)
+# Opt-in subsystem that runs tests during the post-review phase of applicable workflows.
+# When bridge_enabled is false (the default), ALL bridge layers are completely bypassed
+# with zero behavior change — no log messages, no file reads. This is the safety toggle
+# for the entire bridge subsystem. Existing installations are unaffected by default.
+test_execution_bridge:
+  # Master switch. false = bridge completely inactive (default, opt-in semantics).
+  # Set to true to activate the bridge in applicable workflows.
+  bridge_enabled: false
+  # Maximum wall-clock seconds the bridge will wait for a test run before aborting.
+  # Only consulted when bridge_enabled is true.
+  timeout_seconds: 300

package/_gaia/_config/lifecycle-sequence.yaml

@@ -399,6 +399,13 @@ sequence:
       standalone: true
       note: "Return to current lifecycle phase"
 
+  bridge-toggle:
+    module: core
+    command: /gaia-bridge-enable
+    next:
+      standalone: true
+      note: "Run /gaia-build-configs to regenerate resolved configs after toggling"
+
   party-mode:
     module: core
     command: /gaia-party
@@ -573,10 +580,23 @@ sequence:
     next:
       standalone: true
       suggestions:
+        - command: /gaia-sprint-plan
+          context: "To schedule remediation stories discovered by the gap analysis"
+        - command: /gaia-trace
+          context: "To update traceability matrix after closing coverage gaps"
         - command: /gaia-test-design
-          context: "To design tests covering newly identified coverage gaps"
-        - command: /gaia-test-automate
-          context: "To automate tests filling the identified gaps"
+          context: "To redesign the test plan based on gap analysis findings"
+
+  fill-test-gaps:
+    module: testing
+    command: /gaia-fill-test-gaps
+    next:
+      standalone: true
+      suggestions:
+        - command: /gaia-test-gap-analysis
+          context: "To regenerate the gap analysis report before triaging"
+        - command: /gaia-sprint-plan
+          context: "To schedule remediation stories from the triage table"
 
   traceability:
     module: testing

package/_gaia/_config/skill-manifest.csv

@@ -14,3 +14,4 @@ name,displayName,description,path,applicable_agents
 "memory-management-cross-agent","Memory Management Cross-Agent","Cross-agent memory read protocol for loading other agents' sidecar files","_gaia/lifecycle/skills/memory-management-cross-agent.md","all"
 "document-rulesets","Document Rulesets","Artifact type detection, document-specific validation rulesets (prd, arch, ux, test-plan, epics), two-pass validation logic","_gaia/lifecycle/skills/document-rulesets.md","validator"
 "figma-integration","Figma Integration","Design tool detection, token extraction (W3C DTCG), component specs, frame generation, asset export, per-stack resolution","_gaia/dev/skills/figma-integration.md","all-dev"
+"edge-cases","Edge Cases","Structured edge case analysis for M+ stories — boundary, error, timing, concurrency, integration, security, data, environment categories","_gaia/dev/skills/edge-cases.md","all-dev,sm,pm,qa,test-architect"

package/_gaia/_config/workflow-manifest.csv

@@ -1,5 +1,6 @@
 name,displayName,description,module,phase,path,command,agent
 "brainstorming","Brainstorming","Facilitated brainstorming session","core","anytime","_gaia/core/workflows/brainstorming/workflow.yaml","gaia-brainstorming","orchestrator"
+"bridge-toggle","Bridge Toggle","Enable or disable the Test Execution Bridge in global.yaml","core","anytime","_gaia/core/workflows/bridge-toggle/workflow.yaml","gaia-bridge-enable","orchestrator"
 "party-mode","Party Mode","Multi-agent group discussion","core","anytime","_gaia/core/workflows/party-mode/workflow.yaml","gaia-party","orchestrator"
 "advanced-elicitation","Advanced Elicitation","Deep requirements elicitation","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/advanced-elicitation/workflow.yaml","gaia-advanced-elicitation","orchestrator"
 "brainstorm-project","Brainstorm Project","Brainstorm a new project idea","lifecycle","1-analysis","_gaia/lifecycle/workflows/1-analysis/brainstorm-project/workflow.yaml","gaia-brainstorm","analyst"
@@ -47,6 +48,7 @@ name,displayName,description,module,phase,path,command,agent
 "nfr-assessment","NFR Assessment","Assess non-functional requirements","testing","anytime","_gaia/testing/workflows/nfr-assessment/workflow.yaml","gaia-nfr","test-architect"
 "traceability","Traceability","Generate traceability matrix","testing","anytime","_gaia/testing/workflows/traceability/workflow.yaml","gaia-trace","test-architect"
 "test-gap-analysis","Test Gap Analysis","Scan test suite against requirements to identify coverage gaps","testing","anytime","_gaia/testing/workflows/test-gap-analysis/workflow.yaml","gaia-test-gap-analysis","test-architect"
+"fill-test-gaps","Fill Test Gaps","End-to-end remediation for test-gap-analysis findings (sub-workflow composition)","testing","4-implementation","_gaia/testing/workflows/fill-test-gaps/workflow.yaml","gaia-fill-test-gaps","test-architect"
 "security-threat-model","Security Threat Model","Create STRIDE/DREAD threat model","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/security-threat-model/workflow.yaml","gaia-threat-model","security"
 "security-review","Security Review","Pre-merge OWASP security review","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/security-review/workflow.yaml","gaia-security-review","security"
 "infrastructure-design","Infrastructure Design","Design deployment topology and IaC","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/infrastructure-design/workflow.yaml","gaia-infra-design","devops"

package/_gaia/core/agents/orchestrator.md

@@ -122,7 +122,7 @@ You must fully embody this agent's persona and follow the activation protocol EX
 
       {if review_count > 0:}
       Stories still in review:
-      {for each: story key, which reviews PASSED/FAILED/PENDING}
+      {for each: story key, which reviews UNVERIFIED/PASSED/FAILED}
 
       {if failed_count > 0:}
       Failed stories:

package/_gaia/core/protocols/review-gate-check.xml

@@ -27,9 +27,20 @@
 
 <step n="1" title="Read Review Gate and Determine Gate Type">
   <action>Read the story file's Review Gate table</action>
-  <action>If Review Gate section is missing: initialize it with EXACTLY 6 rows — Code Review (PENDING), QA Tests (PENDING), Security Review (PENDING), Test Automation (PENDING), Test Review (PENDING), Performance Review (PENDING). Do NOT add any other rows.</action>
+  <action>If Review Gate section is missing: initialize it with EXACTLY 6 rows — Code Review (UNVERIFIED), QA Tests (UNVERIFIED), Security Review (UNVERIFIED), Test Automation (UNVERIFIED), Test Review (UNVERIFIED), Performance Review (UNVERIFIED). Do NOT add any other rows.</action>
   <action>If Review Gate table has extra rows beyond the 6 valid ones: remove the invalid rows</action>
-  <action>Parse each row: Review name, Status (PENDING | PASSED | FAILED), Report link</action>
+  <action>Parse each row: Review name, Status (UNVERIFIED | PASSED | FAILED), Report link</action>
+
+  <!-- Legacy Status Normalization (E17-S2 / FR-191 / NFR-035)
+       Stories created before the UNVERIFIED/PASSED/FAILED vocabulary (E17-S1)
+       may carry legacy status values such as a literal dash ("-"), blank cells,
+       or the word "pending". These are treated as "not yet run" and MUST be
+       normalized to UNVERIFIED BEFORE gate evaluation in Step 2 so that Step 2
+       operates on canonical values only. NFR-035 requires this backward
+       compatibility — existing stories must not be broken by the vocabulary
+       change.
+  -->
+  <action>LEGACY NORMALIZATION (E17-S2 / NFR-035): Before evaluating gates, normalize every row's status by converting legacy values to the canonical vocabulary. For each of the 6 rows, if the Status cell is any of: a literal dash character "-", blank (empty cell or whitespace-only), or the word "pending" (case-insensitive), replace it with UNVERIFIED. This normalization happens in-memory during parsing — it does NOT rewrite the story file unless a subsequent review workflow persists its own update. Any other legacy value not in {"-", blank, "pending"} is left as-is and will be flagged by the PASSED/FAILED check in Step 2. The canonical mapping is: "-" → UNVERIFIED, blank → UNVERIFIED, "pending" → UNVERIFIED. After this step every row's in-memory status MUST be one of UNVERIFIED, PASSED, or FAILED.</action>
 
   <!-- Infra Gate Detection (FR-129): per-story gate type selection based on requirement ID prefix -->
   <action>Read the story file's YAML frontmatter traces_to field (e.g., traces_to: [IR-001, FR-128])</action>
@@ -44,14 +55,43 @@
   <critical>
     <mandate>You MUST execute the transition even if the gate was already fully passed before this run. The purpose is to ensure story status matches gate state.</mandate>
     <mandate>Use the status-sync protocol to update story status — this ensures both story file and sprint-status.yaml stay in sync.</mandate>
+    <mandate>HARD GATE (E17-S15 / A-050): A story transitioning from 'review' to 'done' MUST have a {story_key}-review-summary.md file in {implementation_artifacts}/. This is enforced structurally — not advisory. The only exception is when the story has zero individual review reports (i.e., it never actually entered the review process).</mandate>
   </critical>
   <action>Check two things: (1) the Review Gate table rows, (2) the current story status</action>
   <action>If ALL 6 rows show PASSED AND story status is 'review': read the "Definition of Done" section — verify every item is checked (- [x]). If any item is unchecked: log "BLOCKED: DoD incomplete — {unchecked items}". Do NOT transition to done.</action>
-  <action>If ALL 6 rows show PASSED AND all DoD items checked AND story status is 'review':
+  <action>REVIEW SUMMARY HARD GATE (E17-S15 / A-050 / AC1, AC2, AC3): If ALL 6 rows show PASSED AND all DoD items checked AND story status is 'review', perform the review-summary.md existence check BEFORE invoking status-sync:
+    1. Build the summary file path: {implementation_artifacts}/{story_key}-review-summary.md
+    2. Check whether the summary file exists on disk.
+    3. If the summary file EXISTS: the hard gate passes — proceed to invoke status-sync below.
+    4. If the summary file is MISSING: apply the skip-when-never-reviewed exception. Count how many of the 6 individual review reports exist on disk:
+       - {implementation_artifacts}/{story_key}-review.md (Code Review)
+       - {implementation_artifacts}/{story_key}-security-review.md (Security Review)
+       - {test_artifacts}/{story_key}-qa-tests.md (QA Tests)
+       - {test_artifacts}/{story_key}-test-automation.md (Test Automation)
+       - {test_artifacts}/{story_key}-test-review.md (Test Review)
+       - {implementation_artifacts}/{story_key}-performance-review.md (Performance Review)
+       If ALL 6 individual review reports are ALSO missing (count == 0), the story never entered review — the summary is not required for this edge case. Log "Review summary check skipped: story {story_key} has no review reports on disk (story was not actually reviewed)." and proceed to invoke status-sync below.
+       If ANY of the 6 individual review reports exist (count greater than 0) but the summary is missing, the hard gate FAILS. HALT with this exact message and do NOT invoke status-sync: "Review summary missing for {story_key}. Run `/gaia-run-all-reviews {story_key}` to generate the summary, or create it manually via `/gaia-create-review-summary {story_key}`."</action>
+  <action>If ALL 6 rows show PASSED AND all DoD items checked AND story status is 'review' AND the review-summary hard gate passed above:
     <invoke-protocol ref="status-sync" story_key="{story_key}" new_status="done" source_workflow="review-gate-check" />
   </action>
   <action>If ALL 6 rows show PASSED AND the story status is already 'done': log "Story already done. No update needed."</action>
-  <action>If any row is FAILED: log which reviews failed. Do not change story status.</action>
-  <action>If any row is PENDING: log which reviews are still pending. Do not change story status.</action>
+
+  <!-- FAILED Gate Reporting (E17-S2 / FR-191 / AC3)
+       When any gate is FAILED the protocol surfaces which gates failed and
+       returns the story to in-progress so the developer can address the
+       review feedback and re-enter the review cycle.
+  -->
+  <action>FAILED GATE REPORTING (AC3): If any row has Status == FAILED, collect the list of failed gate names into a comma-separated list (e.g., "Code Review, Security Review"). Emit this exact message format: "Review gate FAILED for {story_key}. Failed gates: {list of FAILED gate names}. Story is returned to in-progress so the developer can address the review feedback." Then invoke the status-sync protocol to transition the story from 'review' to 'in-progress' — the story MUST be returned to in-progress when any gate is FAILED:
+    <invoke-protocol ref="status-sync" story_key="{story_key}" new_status="in-progress" source_workflow="review-gate-check" />
+  </action>
+
+  <!-- UNVERIFIED Gate Reporting (E17-S2 / FR-191 / AC4)
+       When any gate is UNVERIFIED the protocol reports the count and the
+       specific gate names of those not yet run. It blocks advancement to
+       done without changing the story status — the story stays in 'review'
+       until the outstanding reviews are executed.
+  -->
+  <action>UNVERIFIED GATE REPORTING (AC4): If no row is FAILED but any row has Status == UNVERIFIED, count the UNVERIFIED rows (N) and collect the list of gate names of the UNVERIFIED rows. Emit this exact message format: "{N} gates not yet run for {story_key}. Outstanding gate names: {list of UNVERIFIED gate names}. Run the corresponding review workflows (/gaia-code-review, /gaia-qa-tests, /gaia-security-review, /gaia-test-automate, /gaia-test-review, /gaia-review-perf) or /gaia-run-all-reviews to complete them." The count N and the names MUST both appear in the emitted message. This blocks advancement to done — do NOT change the story status; the story remains in 'review' until all gates show PASSED.</action>
 </step>
 </protocol>

package/_gaia/core/validators/test-environment-validator.js

@@ -194,6 +194,182 @@ function validateRunnerEntry(runner, index) {
   return warnings;
 }
 
+// ─── E25-S6: tiers.stack_hints validation ──────────────────────
+//
+// The generic parseSimpleYaml above only supports 2-level maps, so the
+// deeply-nested `tiers.stack_hints.{pytest_markers,gradle_tasks,go_build_tags,
+// flutter_suites}` block is scanned directly from the raw YAML text. This keeps
+// the existing parser untouched and avoids introducing a new YAML dependency
+// (same approach used elsewhere in the bridge adapters — see ADR-038 §10.20.11).
+//
+// Contract: FR-312, ADR-038 §10.20.11 (stack adapter registry).
+// See docs/test-artifacts/test-environment.yaml.example for canonical usage.
+
+/**
+ * Allowed keys inside `tiers.stack_hints`. Any other key is a validation error
+ * naming the unknown key and the accepted keys (AC6).
+ */
+const STACK_HINT_KEYS = Object.freeze([
+  "pytest_markers",
+  "gradle_tasks",
+  "go_build_tags",
+  "flutter_suites",
+]);
+
+/**
+ * Extract the `tiers.stack_hints` block from raw YAML text using a
+ * line-oriented indent scan. Returns an object describing the block and any
+ * shape violations — does not throw. When the block is absent, returns null.
+ *
+ * Supported shapes (partial blocks are valid — unset tiers fall back to the
+ * adapter default, per Dev Notes):
+ *   tiers:
+ *     stack_hints:
+ *       pytest_markers: ["slow", "integration"]
+ *       gradle_tasks:
+ *         unit: test
+ *         integration: integrationTest
+ *         e2e: e2eTest
+ *       go_build_tags: [integration, e2e]
+ *       flutter_suites:
+ *         unit: test/
+ *         integration: integration_test/
+ *         e2e: integration_test/e2e/
+ *
+ * @param {string} text
+ * @returns {{ raw: object, warnings: string[] }|null}
+ */
+function extractStackHints(text) {
+  const lines = text.split(/\r?\n/);
+
+  // Locate `tiers:` at column 0.
+  let tiersIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^tiers\s*:\s*(#.*)?$/.test(lines[i])) {
+      tiersIdx = i;
+      break;
+    }
+  }
+  if (tiersIdx === -1) return null;
+
+  // Find `stack_hints:` nested under `tiers:` (indent >= 2, < indent of next
+  // top-level key). We just look line-by-line for a `^(\s+)stack_hints\s*:`
+  // whose indent is > 0 and occurs before any column-0 key after `tiers:`.
+  let hintsIdx = -1;
+  let hintsIndent = -1;
+  for (let i = tiersIdx + 1; i < lines.length; i++) {
+    const l = lines[i];
+    if (l.trim() === "" || l.trimStart().startsWith("#")) continue;
+    const indent = l.length - l.trimStart().length;
+    if (indent === 0) break; // left the tiers: subtree
+    if (/^\s+stack_hints\s*:\s*(#.*)?$/.test(l)) {
+      hintsIdx = i;
+      hintsIndent = indent;
+      break;
+    }
+  }
+  if (hintsIdx === -1) return null;
+
+  // Walk child lines whose indent is > hintsIndent. Stop when indent <= hintsIndent.
+  const warnings = [];
+  const block = {};
+  let currentKey = null;
+  let currentKeyIndent = -1;
+  let currentSubMap = null;
+
+  const recordUnknown = (key) => {
+    warnings.push(
+      `Unknown key 'tiers.stack_hints.${key}'. Accepted keys: ${STACK_HINT_KEYS.join(", ")}.`
+    );
+  };
+
+  for (let i = hintsIdx + 1; i < lines.length; i++) {
+    const rawLine = lines[i];
+    const stripped = rawLine.replace(/#.*$/, "").trimEnd();
+    if (stripped.trim() === "") continue;
+    const indent = stripped.length - stripped.trimStart().length;
+    if (indent <= hintsIndent) break; // left stack_hints subtree
+
+    const trimmed = stripped.trim();
+
+    // Top-level stack_hints key (first indent level beneath stack_hints:).
+    // Track the first child indent we see — any line at that indent is a key.
+    if (currentKeyIndent === -1 || indent === currentKeyIndent) {
+      currentKeyIndent = indent;
+      const colonIdx = trimmed.indexOf(":");
+      if (colonIdx === -1) continue;
+      const key = trimmed.substring(0, colonIdx).trim();
+      const val = trimmed.substring(colonIdx + 1).trim();
+
+      if (!STACK_HINT_KEYS.includes(key)) {
+        recordUnknown(key);
+        currentKey = null;
+        currentSubMap = null;
+        continue;
+      }
+
+      currentKey = key;
+      if (val === "") {
+        // Expect a sub-map on following lines (e.g., gradle_tasks: / flutter_suites:)
+        currentSubMap = {};
+        block[key] = currentSubMap;
+      } else if (val.startsWith("[") && val.endsWith("]")) {
+        // Flow sequence: pytest_markers: [a, b]
+        const items = val
+          .slice(1, -1)
+          .split(",")
+          .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+          .filter((s) => s !== "");
+        // Validate shape: string[] only
+        const invalid = items.find((x) => typeof x !== "string");
+        if (invalid !== undefined) {
+          warnings.push(
+            `Invalid shape for 'tiers.stack_hints.${key}': expected array of strings.`
+          );
+        }
+        block[key] = items;
+        currentSubMap = null;
+      } else {
+        // Scalar value where an array or map was expected — shape error.
+        warnings.push(
+          `Invalid shape for 'tiers.stack_hints.${key}': expected ${
+            key === "pytest_markers" || key === "go_build_tags"
+              ? "array of strings"
+              : "map of { unit, integration, e2e }"
+          }, got scalar.`
+        );
+        block[key] = parseScalar(val);
+        currentSubMap = null;
+      }
+      continue;
+    }
+
+    // Nested sub-map entry (gradle_tasks / flutter_suites children).
+    if (indent > currentKeyIndent && currentKey && currentSubMap) {
+      const colonIdx = trimmed.indexOf(":");
+      if (colonIdx === -1) continue;
+      const k = trimmed.substring(0, colonIdx).trim();
+      const v = trimmed.substring(colonIdx + 1).trim();
+      // Only unit / integration / e2e are meaningful for tier maps, but we
+      // record whatever keys appear — downstream adapters pick the ones they need.
+      if (v === "") continue;
+      const parsed = parseScalar(v);
+      // For gradle_tasks / flutter_suites, values must be strings.
+      if (
+        (currentKey === "gradle_tasks" || currentKey === "flutter_suites") &&
+        typeof parsed !== "string"
+      ) {
+        warnings.push(
+          `Invalid shape for 'tiers.stack_hints.${currentKey}.${k}': expected string, got ${typeof parsed}.`
+        );
+      }
+      currentSubMap[k] = parsed;
+    }
+  }
+
+  return { raw: block, warnings };
+}
+
 // ─── Public API ─────────────────────────────────────────────────
 
 /**
@@ -285,8 +461,23 @@ export function validateTestEnvironment(content, options = {}) {
     }
   }
 
+  // E25-S6 / FR-312 / ADR-038 §10.20.11: validate `tiers.stack_hints` block.
+  // The generic parseSimpleYaml above only supports 2-level maps, so the
+  // nested stack_hints block is scanned directly from the raw text.
+  const stackHints = extractStackHints(content);
+  if (stackHints && stackHints.warnings.length > 0) {
+    warnings.push(...stackHints.warnings);
+  }
+
   return {
     valid: warnings.length === 0,
     warnings,
+    // Expose the parsed block for adapter consumers (AC3 wiring). Null when
+    // the block is absent — callers must fall back to adapter defaults.
+    stackHints: stackHints ? stackHints.raw : null,
   };
 }
+
+// E25-S6: exported for unit tests and downstream consumers that need direct
+// access to the scanner without running the full validator.
+export { extractStackHints, STACK_HINT_KEYS };

package/_gaia/core/workflows/bridge-toggle/checklist.md

@@ -0,0 +1,11 @@
+# Bridge Toggle — Post-Complete Checklist
+
+## Validation Items
+
+- [ ] `bridge_enabled` flag in global.yaml is in the target state (true for enable, false for disable)
+- [ ] All YAML comments in global.yaml are preserved after the write
+- [ ] No other keys in global.yaml were modified (only `bridge_enabled` value changed)
+- [ ] Idempotent behavior verified: invoking the same mode twice produces no write on the second invocation
+- [ ] Post-toggle summary was displayed with previous state, new state, and next-step suggestion
+- [ ] Summary includes reminder to run `/gaia-build-configs`
+- [ ] For disable mode: post-flip checks section was skipped entirely

package/_gaia/core/workflows/bridge-toggle/instructions.xml

@@ -0,0 +1,69 @@
+<workflow name="bridge-toggle">
+<critical>
+  <mandate>This workflow modifies global.yaml — preserve ALL comments, key ordering, and formatting.</mandate>
+  <mandate>Use regex-based in-place edit targeting ONLY the bridge_enabled line — never regenerate the full file.</mandate>
+  <mandate>Idempotent: if the flag is already in the target state, do NOT write the file.</mandate>
+</critical>
+
+<step n="1" title="Read Current Bridge State">
+  <action>Read {project-root}/_gaia/_config/global.yaml</action>
+  <action>Extract test_execution_bridge.bridge_enabled value</action>
+  <action>If the test_execution_bridge section is missing: treat bridge_enabled as false (AC3)</action>
+  <action>If the section exists but bridge_enabled key is missing: treat as false (AC3)</action>
+  <action>Capture the raw file bytes for idempotency verification</action>
+  <action>Report: "Current bridge state: {state}"</action>
+</step>
+
+<step n="2" title="Idempotency Check">
+  <action>Compare current state against target mode (enable → true, disable → false)</action>
+  <check if="current_state == target_state">
+    Report "Bridge already {enabled|disabled}" and exit with status ok.
+    Do NOT write global.yaml. A byte-level diff must show zero changes.
+  </check>
+</step>
+
+<step n="3" title="Write Updated State">
+  <action>Use regex-based in-place edit to update ONLY the bridge_enabled: line within the test_execution_bridge: section</action>
+  <action>Regex pattern: /^(\s+bridge_enabled:\s*)(true|false)/m — replace capture group 2 with target value</action>
+  <action>This preserves inline comments on the same line and all surrounding YAML content</action>
+  <action>If the test_execution_bridge section is missing: emit error "test_execution_bridge section not found in global.yaml — cannot toggle. Add the section first (see ADR-028 §10.20.7)."</action>
+  <action>Write the updated content back to global.yaml</action>
+</step>
+
+<!-- Step 4: Post-Flip Checks (Enable Mode Only) — E17-S22
+     Delivered by E17-S22. After the flag flip in Step 3, detect and validate
+     docs/test-artifacts/test-environment.yaml and produce a structured
+     `post_flip_result` object for Step 5's summary composer. This step is
+     skipped on disable mode (AC7) and when Step 3 was an idempotent no-op
+     (Test Scenario #6 — no state transition means no post-flip checks). -->
+<step n="4" title="Post-Flip Checks (Enable Only)">
+  <action if="mode == disable">Skip — disable mode does not perform post-flip checks (AC7). Set post_flip_result = {kind: "skipped", reason: "disable-mode"} and proceed to Step 5.</action>
+  <action if="mode == enable and not changed">Skip — no state transition occurred (bridge was already enabled). Set post_flip_result = {kind: "skipped", reason: "idempotent"} and proceed to Step 5.</action>
+  <action if="mode == enable and changed">Invoke runPostFlipChecks from {project-path}/src/bridge/bridge-post-flip-checks.js with {projectRoot, mode: "enable", changed: true, yolo: {yolo_mode}}. This module performs the filesystem stat of docs/test-artifacts/test-environment.yaml (resolved relative to {project-root}, NOT {project-path} — per AC) and calls into the existing E17-S7 validator at Gaia-framework/_gaia/core/validators/test-environment-validator.js. Capture its return value as post_flip_result.</action>
+  <action if="post_flip_result.kind == 'present_valid'">Collect post_flip_result.runners[] (name + tier) for inclusion in Step 5's summary. No prompt is shown. Proceed to Step 5.</action>
+  <action if="post_flip_result.kind == 'present_invalid'">Collect post_flip_result.errors[] as warnings for inclusion in Step 5's summary. Per AC5, do NOT roll back the bridge_enabled flag flip — the user can manually repair the manifest and re-run /gaia-build-configs. Proceed to Step 5.</action>
+  <action if="post_flip_result.kind == 'absent' and not yolo_mode">Render the 3-option prompt — options payload is available as post_flip_result.options (POST_FLIP_ABSENT_OPTIONS from bridge-post-flip-checks.js). Path A (ADR-028 §10.20.12.3): none of the options auto-invoke any sub-workflow. Present the three options exactly as written in the options list and ask the user to select one.</action>
+  <ask if="post_flip_result.kind == 'absent' and not yolo_mode">
+    `docs/test-artifacts/test-environment.yaml` was not found. The bridge is enabled, but Layer 1 will fail-fast at invocation time until the manifest is created. Select a next-step suggestion:
+
+    [a] Run `/gaia-brownfield` to auto-generate test-environment.yaml (next-step suggestion — NOT auto-invoked)
+    [b] Copy `docs/test-artifacts/test-environment.yaml.example` to `docs/test-artifacts/test-environment.yaml` and customize
+    [c] Skip — bridge is enabled but will fail-fast at Layer 1 with a clear error message until the manifest is created
+
+    Choose [a/b/c]:
+  </ask>
+  <action if="post_flip_result.kind == 'absent' and not yolo_mode">Record the user's selection as post_flip_result.choice (one of "a", "b", "c"). Per AC4, do NOT invoke any sub-workflow regardless of choice. Selection (a) does NOT run /gaia-brownfield; selection (b) does NOT copy the example file. Both are next-step suggestions the user must act on in the next conversation turn. Proceed to Step 5.</action>
+  <action if="post_flip_result.kind == 'absent' and yolo_mode">YOLO mode auto-selects option (c) Skip. runPostFlipChecks has already set post_flip_result.choice = "c" and post_flip_result.yoloAutoSkipped = true. Log a warning: "Bridge is enabled but docs/test-artifacts/test-environment.yaml is missing — Layer 1 will fail-fast until the manifest is created." Proceed to Step 5.</action>
+  <action>Pass post_flip_result to Step 5's summary composer (buildSummary receives it as the `postFlipResult` field).</action>
+</step>
+
+<step n="5" title="Post-Toggle Summary">
+  <action>Invoke buildSummary from {project-path}/src/bridge/bridge-toggle.js with {previousState, newState, mode, changed, postFlipResult} — the postFlipResult field is the structured object captured by Step 4 (or {kind: "skipped", ...} on disable / idempotent paths).</action>
+  <action>Display the returned summary. It always includes: previous state, new state, mode, and whether a write occurred.</action>
+  <action if="mode == enable and post_flip_result.kind == 'present_valid'">Summary includes the detected runners table (name + tier) produced by Step 4.</action>
+  <action if="mode == enable and post_flip_result.kind == 'present_invalid'">Summary includes the schema validation errors as warnings. The bridge_enabled flag is NOT rolled back (AC5).</action>
+  <action if="mode == enable and post_flip_result.kind == 'absent'">Summary includes the user's selected option (a/b/c) from Step 4, or — in YOLO mode — the auto-selected skip warning.</action>
+  <action>AC6: the summary always ends with the next-step suggestion "Run `/gaia-build-configs` to regenerate the resolved configs so the bridge_enabled change takes effect." — regardless of which Step 4 branch ran (present_valid, present_invalid, absent with any choice, skipped, or idempotent).</action>
+  <action if="mode == disable">Summary only confirms new state and reminds about /gaia-build-configs. No post-flip check output (AC7 — Step 4 was skipped).</action>
+</step>
+</workflow>