gaia-framework 1.105.1 → 1.127.2

package/_gaia/lifecycle/templates/test-gap-analysis-template.md

@@ -0,0 +1,221 @@
+---
+mode: coverage
+date: "{date}"
+project: "{project_name}"
+story_count: 0
+gap_count: 0
+---
+
+# Test Gap Analysis — {date}
+
+> **Schema version:** 1.0.0
+> **Traces to:** FR-223, ADR-030 §10.22
+> **Story:** E19-S3
+> **Template location:** `_gaia/lifecycle/templates/test-gap-analysis-template.md`
+>
+> Standardized output schema for the `/gaia-test-gap-analysis` workflow.
+> This template scaffolds the `test-gap-analysis-{date}.md` artifact written by
+> the workflow in both `coverage` and `verification` modes. Downstream tools and
+> agents parse this file — keep the schema stable and bump the schema version on
+> any breaking change.
+
+## Schema Definition
+
+The output file consists of five mandatory sections, in this order:
+
+1. **YAML frontmatter** — five required fields (see below)
+2. **Executive Summary** — high-level narrative and headline numbers
+3. **Gap Table** — one row per gap, four columns
+4. **Per-Story Detail** — one subsection per story with gaps
+5. **Recommendations** — prioritized remediation actions
+
+### YAML Frontmatter
+
+Five required fields, parsed by `js-yaml` without error (AC4):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mode` | enum | `coverage` or `verification` — matches the workflow mode that produced the file |
+| `date` | string | ISO-8601 date the gap analysis was run (e.g., `2026-04-09`) |
+| `project` | string | Project name (from `global.yaml` `project_name`) |
+| `story_count` | integer | Number of stories analyzed in this run |
+| `gap_count` | integer | Total number of gaps detected across all stories |
+
+All five fields are required. Missing any field MUST be flagged by Val as a
+WARNING (AC6). The frontmatter block MUST be delimited by `---` lines at the
+top of the file and MUST parse cleanly with any standards-compliant YAML
+parser.
+
+### Gap Type Enum (closed)
+
+Gap types are drawn from a fixed, **closed** enum. No extension is permitted
+without a schema version bump (AC2).
+
+| Value | Description |
+|-------|-------------|
+| `missing-test` | An acceptance criterion or requirement has no associated test case in `test-plan.md` |
+| `unexecuted` | A test case exists but was never run (no JUnit, LCOV, or E17 evidence) |
+| `uncovered-ac` | An acceptance criterion on a story is not referenced by any test case ID |
+| `missing-edge-case` | The test plan references the story but fails to cover a required edge case documented in story Test Scenarios or ATDD |
+
+Any value outside this enum MUST be flagged by Val as CRITICAL.
+
+### Severity Enum
+
+Severity values are also fixed (AC3):
+
+| Value | Description |
+|-------|-------------|
+| `critical` | Blocks release — high-risk story with no coverage |
+| `high` | Significant coverage gap requiring prompt attention |
+| `medium` | Moderate gap, should be addressed in the current sprint |
+| `low` | Minor gap, can be deferred |
+
+Any value outside this enum MUST be flagged by Val as CRITICAL.
+
+## Executive Summary
+
+{1-3 sentence narrative summarizing the run.}
+
+- **Stories analyzed:** {story_count}
+- **Gaps detected:** {gap_count}
+- **Overall coverage rate:** {aggregate_coverage_pct}%
+- **Generated vs Executed:** {total_executed}/{total_generated} ({aggregate_exec_ratio}%)
+- **Mode:** {mode}
+
+If `gap_count` is 0, state `No coverage gaps detected.` explicitly.
+
+The **Generated vs Executed** row (E19-S7, FR-226) reports the aggregate
+number of generated test cases vs. the number actually executed across all
+stories. It is rendered as `{total_executed}/{total_generated} ({aggregate_exec_ratio}%)`.
+When `total_generated` is 0, the row renders as `0/0 (0.0%)` — no
+division-by-zero error. The aggregate is computed by summing per-story
+`generated` and `executed` counts from the Per-Story Detail section.
+
+The `Overall coverage rate` is the aggregate `(tested_acs / total_acs) * 100`
+computed across all included epics by the Per-Module Coverage step (E19-S6,
+FR-225). It replaces any prior per-story averaged figure and is rounded to one
+decimal place.
+
+## Per-Module Coverage
+
+> **Traces to:** FR-225, ADR-030 §10.22
+> **Story:** E19-S6
+>
+> Per-epic coverage percentage calculated as `(tested_acs / total_acs) * 100`,
+> rounded to one decimal place. Rows sorted by `coverage_pct` ascending (lowest
+> coverage first); ties broken by `module` key lexicographical ascending. Epics
+> with zero story files are excluded from the table — a footnote reports how
+> many were excluded when that count is non-zero.
+
+| module | total_acs | tested_acs | coverage_pct | gap_count |
+|--------|-----------|------------|--------------|-----------|
+| E19 | 24 | 18 | 75.0% | 6 |
+| E1  | 12 |  6 | 50.0% | 6 |
+
+> _{N} epics with no story files were excluded._
+
+When every included epic has zero ACs (the workflow finds story files but no
+acceptance criteria items), render a single row reading
+`| — | 0 | 0 | 0.0% | 0 |` and keep the aggregate `aggregate_coverage_pct`
+at `0.0%`. The calculation is deterministic — identical inputs always produce
+byte-identical rows and aggregate values (AC5).
+
+## Gap Table
+
+Flat table of every gap in this run. Columns (in this order) are canonical:
+
+| story_key | gap_type | severity | description |
+|-----------|----------|----------|-------------|
+| E1-S1 | uncovered-ac | high | AC3 has no matching test case in test-plan.md |
+| E1-S2 | missing-edge-case | medium | Test scenario 4 (empty input) is not exercised |
+
+- `story_key` — the canonical story key (e.g., `E19-S3`)
+- `gap_type` — one of the four values from the closed enum above
+- `severity` — one of the four values from the severity enum above
+- `description` — one-line summary of the gap (keep under 120 chars)
+
+If no gaps exist, render the table header alone with a single row reading
+`| — | — | — | No gaps detected |`.
+
+## Per-Story Detail
+
+One subsection per story that has one or more rows in the Gap Table.
+
+### {story_key} — {story_title}
+
+- **Total ACs:** {count}
+- **Covered ACs:** {count}
+- **Uncovered ACs:** {list of AC identifiers}
+- **Missing tests:** {list of test case IDs or descriptions}
+- **generated:** {count of generated test cases for this story}
+- **executed:** {count of executed test cases for this story}
+- **exec_ratio:** {executed / generated * 100, one decimal}% (E19-S7, FR-226)
+- **Remediation:** {1-2 sentence suggested action}
+
+Stories with zero gaps MAY be omitted from this section to keep the document
+focused. The Gap Table is the canonical list.
+
+The `generated`, `executed`, and `exec_ratio` fields are required on every
+story subsection that reports verification results (E19-S7, FR-226). When
+`generated` is 0, render `exec_ratio` as `0.0%` with a note rather than
+raising a division-by-zero error. When `executed` is 0 and `generated > 0`,
+the story MUST be flagged as `HIGH` gap priority in the Gap Table and in
+the per-story remediation line.
+
+## Recommendations
+
+Prioritized list of concrete next steps, ordered by severity:
+
+1. **{critical|high|medium|low}** — {action} — owner: {agent or team}
+2. ...
+
+Each recommendation SHOULD map to one or more Gap Table rows so downstream
+tools can generate traceability.
+
+## Frontend Dimensions
+
+> **Traces to:** FR-224, ADR-030 §10.22.3
+> **Story:** E19-S5
+>
+> Six-dimension test-type breakdown for frontend projects. This section is
+> **present only when** the workflow detects the scanned project as a
+> frontend stack (Angular, Flutter, React, Vue, Svelte, or a generic
+> `src/app/` layout). For non-frontend projects the section is **omitted
+> entirely** — no empty table, no error, no warning.
+
+| Dimension | Gap Count | Coverage Score | Top-3 Uncovered |
+|-----------|-----------|----------------|-----------------|
+| Unit Tests | {count} | {0-100}% | {list or "—"} |
+| E2E Tests | {count} | {0-100}% | {list or "—"} |
+| Cross-browser | {count} | {0-100}% | {list or "—"} |
+| Accessibility | {count} | {0-100}% | {list or "—"} |
+| Visual Regression | {count} | {0-100}% | {list or "—"} |
+| Responsive | {count} | {0-100}% | {list or "—"} |
+
+**Detection signals** (per architecture §10.22.3):
+
+- **Unit Tests** — `*.test.{ts,js}` / `*.spec.{ts,js}` in `src/`; gap if coverage < 60%
+- **E2E Tests** — Playwright or Cypress spec files; gap if none found
+- **Cross-browser** — browser matrix in `playwright.config.{ts,js}` or `cypress.config.{ts,js}`; gap if `browsers: [chromium]` only or absent
+- **Accessibility** — `axe-core`, `jest-axe`, `@testing-library/jest-axe`, `@axe-core/playwright`, or `cypress-axe` in package.json; gap if none installed
+- **Visual Regression** — Percy, Chromatic, or `playwright-visual-comparisons` in package.json; gap if none configured
+- **Responsive** — viewport resize tests, `--viewport` flag in Playwright, or `cy.viewport` in Cypress; gap if absent from test files
+
+Per-dimension coverage scores feed into E19-S6's overall coverage percentage
+calculation. A non-frontend project's output skips this section entirely and
+E19-S6 falls back to the generic Gap Table totals.
+
+---
+
+## Notes
+
+- This template is read by `/gaia-test-gap-analysis` in both coverage and
+  verification modes. The workflow populates placeholder values and writes
+  the result to `{test_artifacts}/test-gap-analysis-{date}.md`.
+- The gap type enum is **closed**. Adding a new gap type is a breaking change
+  and requires a schema version bump in the `Schema version` header above.
+- Val validates output files against this schema via the
+  `gap-analysis-output` ruleset in `_memory/validator-sidecar/ground-truth.md`.
+- Per ADR-020, projects MAY override this template by placing a file at
+  `custom/templates/test-gap-analysis-template.md`.

package/_gaia/lifecycle/workflows/4-implementation/check-review-gate/checklist.md

@@ -8,7 +8,7 @@ validation-target: 'Composite review gate evaluation and status transition'
 - [ ] Story file found and loaded
 - [ ] Story status is review or done
 - [ ] Review Gate table has exactly 6 rows
-- [ ] All 6 review statuses parsed (PASSED/FAILED/PENDING)
+- [ ] All 6 review statuses parsed (UNVERIFIED/PASSED/FAILED)
 - [ ] Shared protocol review-gate-check.xml loaded and executed
 - [ ] DoD validation performed before transition
 - [ ] Status transition applied correctly (or blocked with reason)

package/_gaia/lifecycle/workflows/4-implementation/check-review-gate/instructions.xml

@@ -13,41 +13,41 @@
 <step n="2" title="Evaluate Review Gate">
   <action>Load and execute the shared protocol: {project-root}/_gaia/core/protocols/review-gate-check.xml</action>
   <action>Parse the Review Gate table — verify exactly 6 rows exist (Code Review, QA Tests, Security Review, Test Automation, Test Review, Performance Review)</action>
-  <action>Classify each row as PASSED, FAILED, or PENDING</action>
+  <action>Classify each row as UNVERIFIED, PASSED, or FAILED</action>
   <action>If any row is missing or has an invalid status, flag it as an error</action>
 </step>
 <step n="3" title="Execute Gate Transition">
   <action>If ALL 6 rows PASSED AND all Definition of Done items checked AND story status is 'review': transition story status to 'done' in story file frontmatter ONLY</action>
   <action>If ALL 6 rows PASSED but DoD incomplete: log "BLOCKED: DoD incomplete" — do NOT transition</action>
   <action>If ALL 6 rows PASSED AND story already 'done': log "Story already done. No update needed."</action>
-  <action>If any row FAILED or PENDING: do NOT change story status</action>
+  <action>If any row FAILED or UNVERIFIED: do NOT change story status</action>
 </step>
 <step n="4" title="Generate Gate Status Report">
   <action>Append Gate Status Report at the END of the story file, after a horizontal rule (---) separator</action>
   <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
     Append a section titled "## Review Gate Status Report" at the very end of the story file, preceded by a --- separator. Include:
     - Date of check
-    - Overall verdict: ALL PASSED | HAS FAILURES | HAS PENDING
+    - Overall verdict: ALL PASSED | HAS FAILURES | HAS UNVERIFIED
     - Gate summary table:
 
     | Review | Status | Report |
     |--------|--------|--------|
-    | Code Review | PASSED/FAILED/PENDING | link or — |
-    | QA Tests | PASSED/FAILED/PENDING | link or — |
-    | Security Review | PASSED/FAILED/PENDING | link or — |
-    | Test Automation | PASSED/FAILED/PENDING | link or — |
-    | Test Review | PASSED/FAILED/PENDING | link or — |
-    | Performance Review | PASSED/FAILED/PENDING | link or — |
+    | Code Review | UNVERIFIED/PASSED/FAILED | link or — |
+    | QA Tests | UNVERIFIED/PASSED/FAILED | link or — |
+    | Security Review | UNVERIFIED/PASSED/FAILED | link or — |
+    | Test Automation | UNVERIFIED/PASSED/FAILED | link or — |
+    | Test Review | UNVERIFIED/PASSED/FAILED | link or — |
+    | Performance Review | UNVERIFIED/PASSED/FAILED | link or — |
 
     - Transition result: what action was taken (transitioned to done / blocked by DoD / no change)
     - If FAILED: list failed reviews and recommend re-running them individually
-    - If PENDING: list pending reviews and recommend running them or /gaia-run-all-reviews
+    - If UNVERIFIED: list unverified reviews and recommend running them or /gaia-run-all-reviews
     - If ALL PASSED: confirm story is done
   </template-output>
   <next-step>
     <on_all_passed>Story is done — proceed to /gaia-sprint-status to update sprint tracking</on_all_passed>
     <on_failures>Re-run failed reviews individually, then run /gaia-check-review-gate again</on_failures>
-    <on_pending>Run /gaia-run-all-reviews to complete remaining reviews</on_pending>
+    <on_unverified>Run /gaia-run-all-reviews to complete remaining reviews</on_unverified>
   </next-step>
 </step>
 </workflow>

package/_gaia/lifecycle/workflows/4-implementation/code-review/instructions.xml

@@ -50,7 +50,7 @@
 <step n="7" title="Update Review Gate and Transition">
   <action>Read story file, locate Review Gate table</action>
   <action>If APPROVE: update Code Review row status to PASSED, link report file</action>
-  <action>If REQUEST_CHANGES: update Code Review row status to REQUEST_CHANGES, link report file. Do NOT change story status — the review-gate-check protocol or run-all-reviews orchestrator handles status transitions.</action>
+  <action>If REQUEST_CHANGES: update Code Review row status to FAILED, link report file. The machine-readable verdict keyword (APPROVE/REQUEST_CHANGES) remains in the review report body for the dev agent to parse — only the Review Gate row uses the canonical vocabulary {UNVERIFIED, PASSED, FAILED}. Do NOT change story status — the review-gate-check protocol or run-all-reviews orchestrator handles status transitions.</action>
   <template-output file="{implementation_artifacts}/{story_key}-*.md">
     Update story file Review Gate table with code review result and report link.
   </template-output>

package/_gaia/lifecycle/workflows/4-implementation/create-story/instructions.xml

@@ -89,8 +89,79 @@
   <action>Define subtasks for implementation</action>
 
   <!-- Edge Case Size Gate (E19-S8, FR-227, FR-228) -->
-  <check if="size == 'S'">Skip edge case analysis sub-step — story is small enough that edge case analysis would waste token budget. Log to Dev Notes: "Edge case analysis: skipped (size=S)"</check>
-  <check if="size in ['M', 'L', 'XL']">Edge case analysis sub-step is mandatory for this story size. Proceed with edge case analysis. Log to Dev Notes: "Edge case analysis: completed (size={size})"</check>
+  <check if="size == 'S'">Skip edge case analysis sub-step — story is small enough that edge case analysis would waste token budget. Log to Dev Notes: "Edge case analysis: skipped (size=S)". Set edge_case_results = [].</check>
+  <check if="size in ['M', 'L', 'XL']">Edge case analysis sub-step is mandatory for this story size. Proceed to Step 4b (Edge Case Analysis Sub-Step) below. Log to Dev Notes: "Edge case analysis: completed (size={size})"</check>
+</step>
+<step n="4b" title="Edge Case Analysis Sub-Step (M/L/XL only)">
+  <critical>
+    <mandate>This sub-step implements FR-227: /gaia-create-story MUST invoke the edge-cases skill as a mandatory sub-step for M+ stories after acceptance criteria are drafted. The sub-step runs in-context — it does NOT use invoke-workflow or invoke-task. It is a JIT skill load only.</mandate>
+    <mandate>Token budget: the entire sub-step (input context + skill output) MUST stay within 8K tokens (NFR-042). If the budget is exceeded, truncate results with a warning logged to Dev Notes.</mandate>
+    <mandate>Sub-step failure is NON-BLOCKING: if the edge case skill fails, times out, or returns malformed output, log a warning and continue story creation with edge_case_results = []. Story file write MUST NOT be blocked by edge case sub-step failure.</mandate>
+  </critical>
+  <check if="size == 'S'">Skip this entire step — the size gate in Step 4 already excluded S-sized stories. Proceed to Step 5.</check>
+  <action>JIT-load the edge case analysis skill from {project-root}/_gaia/dev/skills/edge-cases.md. Do NOT use invoke-workflow or invoke-task — this is a direct skill load in the current create-story context. The skill file must exist at that path; if missing, log warning "Edge case skill not loaded — continuing without edge cases", set edge_case_results = [], and proceed to Step 5 (non-blocking).</action>
+  <action>Build the input context for the edge-cases skill per its input-contract section: story_key, story_title, story_description, acceptance_criteria (the list drafted in Step 4), size, and an optional architecture_excerpt (only if directly relevant). Keep the input context under 5K tokens to stay within the NFR-042 8K total budget.</action>
+  <action>Invoke the edge case analysis inline, following the edge-cases.md skill heuristics. Generate a structured list of edge cases using the skill's output-schema. Each edge case MUST include all five required fields: id, scenario, input, expected, category. The id uses EC-{N} sequential numbering (EC-1, EC-2, ...). The category field uses one of the enum values defined in edge-cases.md (boundary, error, timing, concurrency, integration, security, data, environment).</action>
+  <action>Store the skill's structured output in a named runtime variable `edge_case_results` — a list of objects each with {id, scenario, input, expected, category}. This variable MUST be captured and stored BEFORE the Step 6 template-output writes the story file to disk, satisfying the completion gate (AC5). Example: edge_case_results = [{id: "EC-1", scenario: "...", input: "...", expected: "...", category: "boundary"}, ...].</action>
+  <action>Validate the structured output: confirm every entry has all five required fields (id, scenario, input, expected, category). If any entry is missing a required field, treat the output as malformed per the skill's failure-handling section — log warning "Edge case output schema invalid — continuing without edge cases", set edge_case_results = [], and proceed (non-blocking).</action>
+  <action>TOKEN BUDGET CHECK (NFR-042): After the skill returns, estimate the total tokens consumed by (input context + skill output). If the total exceeds the 8K NFR-042 token budget, truncate edge_case_results — drop lower-priority entries (keep boundary + error + security first) and log warning to Dev Notes: "Edge case output truncated at 8K tokens — N results dropped". If token usage reaches 80% of budget (6.4K) without exceeding, log a note to Dev Notes: "Edge case sub-step token usage: {used}K / 8K".</action>
+  <action>TIMEOUT / FAILURE GUARD (AC6): Wrap the entire edge case sub-step invocation in an error handler. If the skill fails for ANY reason — skill file not found, timeout (> 30s wall clock), exception during analysis, malformed output, or token budget blowout — log a warning "Edge case analysis failed: {reason} — continuing without edge cases", set edge_case_results = [], and proceed to Step 5. This sub-step is explicitly non-blocking: edge case failure MUST NOT halt story creation. This is the only place in create-story where a sub-step failure is allowed to warn-and-continue instead of HALT.</action>
+  <action>COMPLETION GATE (AC5): Confirm that edge_case_results has been captured (either as a populated list or as an empty list after failure). Only after this confirmation may the workflow proceed to Step 5 and eventually Step 6's template-output. If edge_case_results is unset (not merely empty), treat as a malformed invocation and reset to []. Log to Dev Notes: "Edge case sub-step complete: {count} results captured".</action>
+  <action>Persist edge_case_results into the story for traceability: the Step 6 template-output appends a summary of the captured edge cases into the story's Test Scenarios section (or Dev Notes if Test Scenarios is not applicable). Each edge case is rendered as a row with its id, scenario, input, expected, and category — preserving the structured shape.</action>
+</step>
+<step n="4c" title="Append Edge Case Results to Acceptance Criteria (FR-229)">
+  <critical>
+    <mandate>This sub-step implements FR-229: edge case results captured by Step 4b MUST be appended to the story's Acceptance Criteria section as AC-EC{N} items BEFORE Step 6 writes the story file to disk. This ensures edge cases are formally tracked and verifiable at review time.</mandate>
+    <mandate>Primary ACs are IMMUTABLE at this point — never modify, never reorder, never insert between existing primary ACs. AC-EC items are append-only, added AFTER the last primary AC in the Acceptance Criteria section. This is the AC4 safety guarantee.</mandate>
+    <mandate>AC-EC numbering restarts from 1 per story. Each story's AC-EC counter is independent of other stories and independent of the primary AC numbers — there is no collision because the AC-EC prefix is distinct.</mandate>
+  </critical>
+  <check if="size == 'S'">Skip this entire step — Step 4's size gate already excluded S-sized stories from edge case analysis. Proceed to Step 5.</check>
+  <action>SNAPSHOT PRIMARY ACs (AC4): Before processing edge_case_results, capture the list of primary ACs drafted in Step 4 into a frozen variable primary_acs_snapshot. This snapshot is read-only for the remainder of the workflow. After the AC-EC append completes, verify that the first len(primary_acs_snapshot) entries in the Acceptance Criteria list still match the snapshot exactly (same order, same text). If any primary AC text or order has changed, HALT with "AC4 violation: primary AC list was modified during edge case append." This safety check ensures primary ACs are never touched.</action>
+  <action>ZERO-RESULT FAST PATH (AC5): If edge_case_results is empty (length == 0 or the list is []) — either because the edge case sub-step returned no results, failed non-blocking, or was skipped — do NOT add any AC-EC items to the Acceptance Criteria section. Append the note "No edge cases identified." to the story's Dev Notes section and proceed to Step 5. The Acceptance Criteria section remains exactly as drafted in Step 4.</action>
+  <action>FORMAT EACH EDGE CASE AS AC-EC (AC1, AC2, AC3): For each entry in edge_case_results, format a new acceptance criterion using the canonical AC-EC rendering template:
+    - [ ] **AC-EC{N}:** {scenario} — Expected: {expected} [category: {category}]
+    where:
+      - {N} is a sequential counter starting at 1 for this story (AC-EC1, AC-EC2, AC-EC3, ...). The counter restarts from 1 for every story — there is no global AC-EC numbering and no collision with primary AC numbers because the "AC-EC" prefix is distinct from the primary "AC" prefix.
+      - {scenario} is the scenario field from the edge case result (a short natural-language description of the edge case).
+      - {expected} is the expected field from the edge case result (the observable outcome that verifies the edge case is handled).
+      - {category} is the category field from the edge case result (one of the enum values: boundary, error, timing, concurrency, integration, security, data, environment).
+    The rendered line must include all three fields (scenario, expected, category) in exactly this order. The bracketed `[category: {category}]` tag is part of the canonical format so reviewers can quickly triage edge-case ACs by category.</action>
+  <action>APPEND AFTER LAST PRIMARY AC (AC4): Insert the formatted AC-EC lines immediately AFTER the last primary AC in the Acceptance Criteria section — never before, never between primary ACs, never in a separate section. The final Acceptance Criteria list order is: [all primary ACs in their original order, then AC-EC1, AC-EC2, ..., AC-ECn]. Do NOT renumber or rewrite any primary AC. Do NOT alter the spacing, formatting, or text of any primary AC. The append is strictly additive.</action>
+  <action>NUMBERING CONSISTENCY (Task 4): Confirm the AC-EC counter started from 1 for this story and that no AC-EC number collides with a primary AC number (e.g., if the story has primary ACs AC1..AC5, the edge case ACs are AC-EC1..AC-ECn, NOT AC6..). The "AC-EC" prefix is the canonical disambiguator — never drop it, never merge AC-EC numbering into the primary AC sequence.</action>
+  <action>DEV NOTES LOG: Append to the story's Dev Notes section: "Edge case AC append: {count} AC-EC items added (FR-229)". If count is 0, the zero-result fast path above has already logged "No edge cases identified." — do not double-log.</action>
+  <action>POST-APPEND PRIMARY AC VERIFICATION (AC4): Re-read the Acceptance Criteria section after the append and compare the first len(primary_acs_snapshot) items against primary_acs_snapshot. They MUST match exactly. If not, HALT with "AC4 violation: primary ACs were modified during AC-EC append." This is the final safety gate before the workflow proceeds to Step 5.</action>
+</step>
+<step n="4d" title="Append Edge Case Results to Test Plan (FR-230)">
+  <critical>
+    <mandate>This sub-step implements FR-230: edge case results captured by Step 4b MUST be appended to {test_artifacts}/test-plan.md as new rows BEFORE Step 6 writes the story file to disk. This ensures edge case scenarios are captured in the test artifact, not only in the story file.</mandate>
+    <mandate>Sub-step failure is NON-BLOCKING (AC4): if test-plan.md does not exist, log a note in the story's Dev Notes and continue without error. Story creation MUST NOT be blocked by a missing test-plan.md.</mandate>
+    <mandate>Idempotency is REQUIRED (AC5): re-running create-story for the same story_key MUST NOT duplicate edge case rows in the test plan. Dedup key = (story_key, scenario).</mandate>
+  </critical>
+  <check if="size == 'S'">Skip this entire step — Step 4's size gate already excluded S-sized stories from edge case analysis. Proceed to Step 5.</check>
+  <action>ZERO-RESULT FAST PATH: If edge_case_results is empty (length == 0) — either because the edge case sub-step returned no results, failed non-blocking, or was skipped — do NOT open or modify test-plan.md. Proceed to Step 5. No-op, no dev note (the AC-EC append step 4c already logged "No edge cases identified.").</action>
+  <action>FILE EXISTENCE CHECK (AC4): Check whether {test_artifacts}/test-plan.md exists. If the file does not exist (file absent, path not found, or the directory is missing), log a note in the story's Dev Notes section — exactly "Edge case test plan append: skipped — test-plan.md not found at {test_artifacts}/test-plan.md (non-blocking)." Do NOT raise an error, do NOT create test-plan.md, do NOT halt. Proceed to Step 5. This is the non-blocking fallback path.</action>
+  <action>READ TEST PLAN: Read {test_artifacts}/test-plan.md into memory. The content is the authoritative target for both the existing-section locate and the highest-TC-ID scan below.</action>
+  <action>LOCATE STORY SECTION (AC1): Search the test-plan.md content for a heading or row that references this story_key. Locate the story's section via any of: (a) a markdown heading containing the story_key (e.g., "### E19-S11 — ..." or "## {story_key}"); (b) an existing table row in the test-plan.md whose trailing cell contains the story_key. If a section is found, remember the insertion point (immediately after the last existing row of that section). If no section is found, the insertion point is the end of the file — a new section will be created.</action>
+  <action>TC ID NUMBERING (AC3): Scan the entire test-plan.md content for the highest existing test case ID. Match the canonical TC ID patterns used by the test plan (e.g., TC-{N}, TGA-{N}, ECI-{N}, and any other prefix already present in the file). For the purposes of this append, find the highest numeric suffix among all IDs sharing the same prefix the story's Dev Notes declares (e.g., ECI-13 for E19-S11 → next is ECI-14). If no prefix is declared in Dev Notes, default to TC-{N} and auto-increment from the highest existing TC-{N}. If no TC IDs exist at all, start at TC-1. The next TC ID assigned to the first new edge case row is (highest + 1), and subsequent edge cases increment sequentially.</action>
+  <action>IDEMPOTENCY / DEDUP CHECK (AC5): Before appending any row, scan the test-plan.md content for existing rows that match this (story_key, scenario) pair. A row is considered a duplicate if its trailing cell contains the story_key AND its scenario cell contains the exact scenario text from the current edge_case_results entry. For each edge case result: if a duplicate row exists, SKIP that entry (do not append); otherwise, mark it for append. Track the count of skipped duplicates and the count of new rows to append. The dedup key is (story_key, scenario) — this makes re-runs of create-story for the same story_key idempotent.</action>
+  <action>FORMAT ROWS (AC2): For each non-duplicate edge case result, format a new test-plan row using the canonical row format:
+    | {tc_id} | {scenario} | edge-case | {severity} | {story_key} |
+    where:
+      - {tc_id} is the auto-incremented test case ID from the numbering step above (e.g., ECI-14, ECI-15).
+      - {scenario} is the scenario field from the edge case result (verbatim from edge_case_results).
+      - edge-case is the literal tag string — never replaced, never translated, never lower/upper-cased differently.
+      - {severity} is derived from the edge case category: boundary/data → medium; error/integration → high; security → high; timing/concurrency → high; environment → low. If category is missing or unmapped, default to medium.
+      - {story_key} is the current story's key (e.g., E19-S11) — this is the dedup key used in AC5.
+    The row columns MUST appear in exactly this order: tc_id | scenario | edge-case | severity | story_key. Never reorder.</action>
+  <action>APPEND ROWS: If the story section was found, append the formatted rows immediately after the last existing row of that section. If no story section was found, append a new section at the end of the test-plan.md file:
+    ### {story_key} — {story_title}
+    | ID | Scenario | Type | Severity | Story |
+    |----|----------|------|----------|-------|
+    {formatted rows}
+    The new section uses the same table header as existing sections so renderers and scanners keep working.</action>
+  <action>WRITE TEST PLAN: Write the updated test-plan.md content back to {test_artifacts}/test-plan.md. Preserve the original file's trailing newline convention and do not touch any content outside the insertion point. If the write fails for any reason (permission denied, disk full, etc.), log a warning to Dev Notes "Edge case test plan append: write failed — {error}. Scenarios preserved in story file only." and proceed non-blockingly.</action>
+  <action>DEV NOTES LOG: Append to the story's Dev Notes section exactly: "Edge case test plan append: {new_count} rows added, {dup_count} duplicates skipped (FR-230)". If both counts are zero (everything was a duplicate on a re-run), the line is still logged so the idempotency path is observable.</action>
+  <action>COMPLETION GATE: Confirm the test plan append step has run to completion (either by appending rows, skipping on missing file, skipping on zero results, or logging a write failure). Only after this confirmation may the workflow proceed to Step 5.</action>
 </step>
 <step n="5" title="Definition of Done">
   <action>Append DoD checklist: all AC met, tests pass, code reviewed, docs updated</action>

package/_gaia/lifecycle/workflows/4-implementation/dev-story/instructions.xml

@@ -8,6 +8,29 @@
   <mandate>All tests must pass before marking complete</mandate>
   <mandate>When reading or running application source code, use {project-path} as the base directory — NOT {project-root}. {project-path} is resolved by the engine from global.yaml.</mandate>
 </critical>
+<!--
+  Test Execution Bridge — Layer 3 integration (E17-S10, FR-194, FR-197, FR-198, NFR-034, ADR-028)
+
+  After the GREEN phase's test run, when test_execution_bridge.bridge_enabled is true in global.yaml, the
+  workflow invokes Bridge Layer 3 (src/bridge/layer-3-result-parsing.js) on the captured Layer 2 output
+  { stdout, stderr, exit_code } to parse results and generate the evidence file. Layer 3 supports Vitest
+  TAP, Jest JSON, and BATS TAP runner outputs; unknown formats fall back to a minimal evidence record with
+  parse_error: true and the first 2KB captured as raw_output_snippet.
+
+  Layer 3 writes the evidence file to docs/test-artifacts/test-results/{story_key}-execution.json using
+  the FR-194 / FR-197 schema: { schema_version, story_key, runner, mode, executed_at, duration_seconds,
+  summary: { total, passed, failed, skipped }, tests: [ { name, status, duration_ms, failure_message? } ],
+  truncated }. When serialized size exceeds 500KB, Layer 3 truncates the tests array (NFR-034 size cap)
+  and sets truncated: true while preserving the summary block intact.
+
+  The evidence file path (returned by writeEvidence) MUST be reported to the user after Layer 3 writes
+  the file, and a linked reference to the evidence file path MUST be added to the story's Review Gate
+  section so downstream review workflows and the review-gate-check protocol can discover the evidence.
+
+  The review-gate-check protocol (§10.20.6) reads this execution.json and derives PASSED / FAILED /
+  UNVERIFIED from the evidence summary. Stories without an execution.json report UNVERIFIED (not FAILED)
+  for backward compatibility with pre-bridge workflows.
+-->
 <step n="1" title="Load Story File">
   <action>Read story .md file, parse YAML frontmatter</action>
   <action>Extract: key, status, acceptance criteria, subtasks, dependencies</action>
@@ -351,9 +374,9 @@
   <check if="pr_merge_dod_item_unchecked">HALT: Cannot transition {story_key} to `review`: DoD item 'PR merged to {branch}' is not satisfied. Re-run Step 16 (Merge PR) or resolve manually before retrying the status transition.</check>
   <invoke-protocol ref="status-sync" story_key="{story_key}" new_status="review" source_workflow="dev-story" />
   <action>Append files changed list to story file</action>
-  <action>Initialize Review Gate section in story file: set all six rows (Code Review, QA Tests, Security Review, Test Automation, Test Review, Performance Review) to PENDING with report link "—". If Review Gate section already exists, reset all rows to PENDING.</action>
+  <action>Initialize Review Gate section in story file: set all six rows (Code Review, QA Tests, Security Review, Test Automation, Test Review, Performance Review) to UNVERIFIED with report link "—". If Review Gate section already exists, reset all rows to UNVERIFIED.</action>
   <template-output file="{implementation_artifacts}/{story_key}-*.md">
-    Update story file with status change to 'review', list of files changed, and initialized Review Gate table (all 6 rows PENDING).
+    Update story file with status change to 'review', list of files changed, and initialized Review Gate table (all 6 rows UNVERIFIED).
   </template-output>
 </step>
 <step n="19" title="Auto-Run Reviews (YOLO only)">

package/_gaia/lifecycle/workflows/4-implementation/retrospective/instructions.xml

@@ -10,7 +10,7 @@
   <action>Calculate: stories completed, stories invalid, stories carried over, velocity (points delivered vs planned)</action>
   <action>Read ALL story files for this sprint (from sprint-status.yaml story list). For each story extract:
     - Status (done, review, in-progress, invalid)
-    - Review Gate table results (which reviews PASSED/FAILED/PENDING)
+    - Review Gate table results (which reviews UNVERIFIED/PASSED/FAILED)
     - Findings table (count and types of findings)
     - Definition of Done checklist results</action>
   <action>Read {memory_path}/validator-sidecar/decision-log.md — extract all entries for this sprint's stories (validation attempts, findings counts, pass/fail results)</action>

package/_gaia/lifecycle/workflows/4-implementation/run-all-reviews/instructions.xml

@@ -63,16 +63,139 @@
   <action>When subagent returns: read story file, check Performance Review row status. Log result.</action>
 </step>
 
-<step n="8" title="Review Summary and Status Transition">
-  <action>Read story file — parse full Review Gate table</action>
-  <action>Generate summary table: review name | verdict | report link</action>
-  <action>If ALL 6 PASSED: invoke the review-gate-check protocol to evaluate DoD and transition story to 'done' if appropriate.</action>
-  <action>If any FAILED:
-    <invoke-protocol ref="status-sync" story_key="{story_key}" new_status="in-progress" source_workflow="run-all-reviews" />
-    List failed reviews with report links. Report: "Story {story_key} moved to in-progress — fix issues and re-run failed reviews."</action>
-  <invoke-protocol name="review-gate-check" file="{project-root}/_gaia/core/protocols/review-gate-check.xml" />
+<step n="8" title="Generate Review Summary and Transition Status">
+  <critical>
+    <mandate>This step MUST write the {story_key}-review-summary.md file BEFORE invoking the review-gate-check protocol. The protocol's hard gate (E17-S15 / A-050) checks that the summary exists as a prerequisite for the review→done transition — if the template-output is skipped or ordered after the protocol invocation, every story will HALT at the gate.</mandate>
+    <mandate>The summary file MUST aggregate the 6 review verdicts — do NOT regenerate or re-run the reviews here. Read each review report's Review Gate row and consolidate.</mandate>
+  </critical>
+  <action>Read story file — parse the full Review Gate table. Extract each of the 6 rows: Code Review, QA Tests, Security Review, Test Automation, Test Review, Performance Review — with status (UNVERIFIED / PASSED / FAILED) and report link.</action>
+  <action>Resolve report paths for each review (used in the aggregate summary body):
+    - Code Review: {implementation_artifacts}/{story_key}-review.md
+    - Security Review: {implementation_artifacts}/{story_key}-security-review.md
+    - QA Tests: {test_artifacts}/{story_key}-qa-tests.md
+    - Test Automation: {test_artifacts}/{story_key}-test-automation.md
+    - Test Review: {test_artifacts}/{story_key}-test-review.md
+    - Performance Review: {implementation_artifacts}/{story_key}-performance-review.md</action>
+  <action>Compute overall_status: if ALL 6 rows show PASSED → overall_status = "PASSED". If ANY row shows FAILED → overall_status = "FAILED". If ANY row is still UNVERIFIED → overall_status = "INCOMPLETE".</action>
+  <action>Build the review-summary.md content and aggregate the verdicts using this exact schema (AC5). Frontmatter carries story_key, date, overall_status, and reviewers. The body has one section per review (verdict + report link + one-line synopsis) and a final aggregate Gate Status table:
+    ```
+    ---
+    story_key: {story_key}
+    date: {date}
+    overall_status: {overall_status}
+    reviewers: [code-review, qa-tests, security-review, test-automate, test-review, review-perf]
+    ---
+
+    # Review Summary: {story_key}
+
+    > Aggregate of the 6-review gate for {story_key}. This file does NOT regenerate reviews — it consolidates existing verdicts from the 6 individual review reports.
+
+    ## Code Review
+    **Verdict:** {code_review_status}
+    **Report:** [{code_review_report_relpath}]({code_review_report_relpath})
+    **Synopsis:** {one_line_synopsis_or_"See report for details"}
+
+    ## QA Tests
+    **Verdict:** {qa_tests_status}
+    **Report:** [{qa_tests_report_relpath}]({qa_tests_report_relpath})
+    **Synopsis:** {one_line_synopsis}
+
+    ## Security Review
+    **Verdict:** {security_review_status}
+    **Report:** [{security_review_report_relpath}]({security_review_report_relpath})
+    **Synopsis:** {one_line_synopsis}
+
+    ## Test Automation
+    **Verdict:** {test_automation_status}
+    **Report:** [{test_automation_report_relpath}]({test_automation_report_relpath})
+    **Synopsis:** {one_line_synopsis}
+
+    ## Test Review
+    **Verdict:** {test_review_status}
+    **Report:** [{test_review_report_relpath}]({test_review_report_relpath})
+    **Synopsis:** {one_line_synopsis}
+
+    ## Performance Review
+    **Verdict:** {performance_review_status}
+    **Report:** [{performance_review_report_relpath}]({performance_review_report_relpath})
+    **Synopsis:** {one_line_synopsis}
+
+    ## Aggregate Gate Status
+
+    | Review | Verdict | Report |
+    |---|---|---|
+    | Code Review | {code_review_status} | [link]({code_review_report_relpath}) |
+    | QA Tests | {qa_tests_status} | [link]({qa_tests_report_relpath}) |
+    | Security Review | {security_review_status} | [link]({security_review_report_relpath}) |
+    | Test Automation | {test_automation_status} | [link]({test_automation_report_relpath}) |
+    | Test Review | {test_review_status} | [link]({test_review_report_relpath}) |
+    | Performance Review | {performance_review_status} | [link]({performance_review_report_relpath}) |
+
+    **Overall Status:** {overall_status}
+    ```
+  </action>
   <template-output file="{implementation_artifacts}/{story_key}-review-summary.md">
-    Generate review summary: story key, date, all 6 review verdicts with report links, final story status, and next actions if any reviews failed.
+    Write the aggregated review summary per the schema above. Frontmatter fields: story_key, date, overall_status, reviewers. Body: 6 review sections with verdict + report link + one-line synopsis, plus a final aggregate Gate Status table. This template-output MUST execute before the review-gate-check protocol invocation below so the hard gate can find the summary file.
   </template-output>
+  <action>After the summary file is written, handle the status transition:
+    - If ALL 6 PASSED: invoke the review-gate-check protocol to evaluate DoD and transition story to 'done' if appropriate. The protocol's hard gate will find the summary file we just wrote and pass.
+    - If any FAILED:
+      <invoke-protocol ref="status-sync" story_key="{story_key}" new_status="in-progress" source_workflow="run-all-reviews" />
+      List failed reviews with report links. Report: "Story {story_key} moved to in-progress — fix issues and re-run failed reviews."</action>
+  <action>PROGRESSIVE NUDGE BLOCK (E17-S3 / FR-193 / AC1-AC6): After the review summary file has been written and the status transition (if any) has been invoked, render a Progressive Nudge Block directly in the conversation. The nudge block is additive — it does not replace or block the existing completion output and the review summary template-output above. The nudge block MUST render in all execution modes (both normal and YOLO) — it is unconditional of execution_mode. The block has three parts:
+
+    1. GATE SUMMARY TABLE — render a markdown table with columns (gate name, status, linked report) containing one row per review gate using the six rows previously parsed from the story's Review Gate table. The linked report column uses the resolved report paths resolved earlier in this step (code-review report, qa-tests report, security-review report, test-automation report, test-review report, performance-review report). Format the table as:
+
+    | Gate | Status | Report |
+    |---|---|---|
+    | Code Review | {code_review_status} | [report]({code_review_report_relpath}) |
+    | QA Tests | {qa_tests_status} | [report]({qa_tests_report_relpath}) |
+    | Security Review | {security_review_status} | [report]({security_review_report_relpath}) |
+    | Test Automation | {test_automation_status} | [report]({test_automation_report_relpath}) |
+    | Test Review | {test_review_status} | [report]({test_review_report_relpath}) |
+    | Performance Review | {performance_review_status} | [report]({performance_review_report_relpath}) |
+
+    2. OVERALL OUTCOME LINE — classify the gate results using the same overall_status already computed for the review summary file and render one of three classification strings:
+       - "ALL PASSED" when all 6 rows are PASSED
+       - "N FAILED" when any row is FAILED (substitute N with the actual count of FAILED rows)
+       - "N UNVERIFIED" when no FAILED rows but at least one row is still UNVERIFIED (substitute N with the actual count of UNVERIFIED rows)
+       When both FAILED and UNVERIFIED rows exist, render both classification strings on separate lines (FAILED first) so the developer sees the full picture. Render as: "**Overall:** {classification(s)}".
+
+    3. SUGGESTED NEXT COMMAND — based on the overall outcome, render exactly one "Suggested next:" line using the branching rules below. This is the progressive nudge payload that tells the developer exactly what to do next without re-reading gate documentation:
+
+       ALL PASSED BRANCH (AC2): When all 6 rows are PASSED, render "Suggested next: /gaia-check-review-gate {story_key}" to confirm the advancement to `done`. Substitute {story_key} with the actual story key.
+
+       FAILED BRANCH (AC3): When any row is FAILED, collect the failed gate names into a list and render:
+       "Failed gates: {comma-separated list of failed gate names}"
+       "Suggested next: /gaia-correct-course {story_key} — return to in-progress and fix the failed review(s)"
+
+       UNVERIFIED BRANCH (AC4): When no rows are FAILED but one or more rows are still at UNVERIFIED, collect the unrun (UNVERIFIED, not yet run) gate names and for each, render the individual review command that would run it. The six canonical per-gate commands are:
+         - Code Review → /gaia-code-review {story_key}
+         - QA Tests → /gaia-qa-tests {story_key}
+         - Security Review → /gaia-security-review {story_key}
+         - Test Automation → /gaia-test-automate {story_key}
+         - Test Review → /gaia-test-review {story_key}
+         - Performance Review → /gaia-review-perf {story_key}
+       Render:
+       "Unrun gates ({count}): {comma-separated list of unrun gate names}"
+       "Suggested next: run the following review(s) individually:"
+       followed by a bulleted list of the matching commands above, one per unrun gate.
+
+       MIXED BRANCH: If the run has both FAILED and UNVERIFIED rows, the FAILED branch takes precedence for the "Suggested next:" line (correct-course is more urgent than re-running unrun reviews), but still list the unrun gates under an "Also unrun:" label so the developer can address both.
+
+    NUDGE BLOCK RENDER TEMPLATE — wrap the three parts in a visually distinct block so it is easy to spot in the conversation:
+
+    ```
+    --- Review Gate Nudge ---
+    {gate summary table}
+
+    **Overall:** {classification}
+
+    {suggested next section based on branch}
+    ---
+    ```
+
+    The nudge MUST be rendered regardless of whether the status transition above succeeded — even if the review-gate-check protocol advanced the story to done, the nudge still shows the final gate state and the /gaia-check-review-gate suggestion for transparency. The nudge is additive to existing output — it does not remove, replace, or block the review summary template-output, the status transition, or the review-gate-check protocol invocation.</action>
+  <invoke-protocol name="review-gate-check" file="{project-root}/_gaia/core/protocols/review-gate-check.xml" />
 </step>
 </workflow>

package/_gaia/lifecycle/workflows/4-implementation/security-review/checklist.md

@@ -25,5 +25,7 @@ required-inputs:
 - [ ] If PASSED: Security Review row shows PASSED with report link
 - [ ] If FAILED: Security Review row shows FAILED, story status set to in-progress
 - [ ] Review gate check protocol invoked
+## Bridge Security
+- [ ] Bridge remote executors MUST use argv-array spawn with `shell: false`
 ## Output Verification
 - [ ] Report generated with findings table