gaia-framework 1.65.1 → 1.83.2

package/_gaia/lifecycle/workflows/4-implementation/add-stories/instructions.xml

@@ -88,9 +88,81 @@
     If new epic: include epic header with name, description, goal, success criteria before its stories.
     Prepend a Change Log entry if not already present.
   </template-output>
+  <action>Recount epic overview table story counts and update in-place:
+    1. Parse all `### Story (E\d+)-S\d+:` headers in the saved epics-and-stories.md file
+    2. Group and count story headers per epic key (E1, E2, etc.)
+    3. Locate the Epic Overview table in epics-and-stories.md (the markdown table with columns: epic ID, name, goal, count, priority)
+    4. For each epic row in the table, update the count column to match the actual count of story headers for that epic
+    5. If a new epic was created in Step 4 and does not yet have a row in the Epic Overview table, insert a new row with the correct initial story count
+    6. If an existing epic row in the overview table has zero matching story headers after recount, preserve the row as-is (do not delete it) — log a warning: "Epic {EN} has 0 story headers but overview row preserved"
+    7. Table format: `| E{N} | {name} | {goal} | {count} | {priority} |` — only the `{count}` column cell is updated; do not modify other columns
+    8. Save the updated epics-and-stories.md file</action>
 </step>
 
-<step n="8" title="Next Steps">
+<step n="8" title="Inline Validation">
+  <action>Check Val prerequisites: verify {project-root}/_gaia/lifecycle/agents/validator.md exists AND {project-root}/_memory/validator-sidecar/ directory exists. If either prerequisite is missing, log warning "Val prerequisites unavailable — skipping inline validation. Stories will be marked as validating." Set val_available = false.</action>
+
+  <action>For each newly created story from Step 5 (batch iteration — each story validated independently):
+    Set story_validation_status = "pending"
+    Set validation_attempt = 0
+
+    If val_available == false:
+      Set story_validation_status = "degraded"
+      Mark story status as 'validating' in the story entry
+      Log: "Story {story_key}: Val unavailable — marked as validating"
+      Continue to next story
+    End If
+
+    VALIDATION LOOP (maximum 3 attempts):
+      Increment validation_attempt
+
+      Invoke Val validation directly within workflow context (no subagent nesting — works at both standalone level 1 and subagent level 2 from add-feature, never exceeding 2-level nesting max):
+      <invoke-workflow
+        target="{project-root}/_gaia/lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml"
+        input_artifact="{planning_artifacts}/epics-and-stories.md"
+        story_scope="{story_key}"
+        on_error="warn_and_continue" />
+
+      If Val invocation fails (timeout, context overflow, crash, or missing prerequisites):
+        Log warning: "Val validation failed for {story_key}: {reason}"
+        Set story_validation_status = "degraded"
+        Mark story status as 'validating'
+        Break loop — continue to next story
+      End If
+
+      Separate findings by severity:
+        - CRITICAL and WARNING findings → actionable_findings (trigger fix loop)
+        - INFO findings → info_findings (do not trigger fix loop, non-blocking — log only)
+
+      Log all INFO findings to output (INFO does not block progression and does not trigger re-validation)
+
+      If actionable_findings is empty:
+        Set story_validation_status = "validated"
+        Note story as "validated" in output validation summary
+        Break loop — continue to next story
+      End If
+
+      If validation_attempt less than 3:
+        Auto-fix each CRITICAL and WARNING finding in the story content
+        Re-invoke Val validation (loop continues)
+      Else (validation_attempt == 3, maximum reached):
+        Set story_validation_status = "failed"
+        Mark story status as 'validating' (not 'ready-for-dev')
+        Log remaining unresolved findings
+        Break loop — continue to next story
+      End If
+    END VALIDATION LOOP
+  End For Each
+
+  Report batch validation summary:
+    - Stories validated successfully: {count} ({list})
+    - Stories marked validating (failed after 3 attempts): {count} ({list})
+    - Stories marked validating (Val unavailable/degraded): {count} ({list})
+    - INFO findings logged: {count}
+  </action>
+</step>
+
+<step n="9" title="Next Steps">
   <action>Report summary: new epic(s) created (if any), stories added with IDs and epic assignments</action>
   <action>For each new story: "Run /gaia-create-story {story_key} to elaborate before development"</action>
   <action>If stories should enter current sprint: "Run /gaia-correct-course to inject into sprint"</action>

package/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/checklist.md

@@ -0,0 +1,25 @@
+---
+title: 'Create Stakeholder Validation'
+validation-target: 'Stakeholder file'
+---
+## Structure
+- [ ] workflow.yaml present with agent: orchestrator
+- [ ] instructions.xml present with sequential steps
+- [ ] checklist.md present
+- [ ] Registered in workflow-manifest.csv
+- [ ] Slash command file exists at .claude/commands/gaia-create-stakeholder.md
+## Input Collection
+- [ ] Required fields prompted: name, role, expertise, personality
+- [ ] Optional fields prompted: perspective, tags
+- [ ] Required field validation (non-empty check)
+## Validation Guards
+- [ ] 50-file cap enforced before file creation
+- [ ] Case-insensitive duplicate name detection against existing stakeholder name frontmatter
+- [ ] custom/stakeholders/ directory auto-created if missing
+## Output
+- [ ] Filename is kebab-case slug of name with .md extension
+- [ ] File written to custom/stakeholders/{slug}.md
+- [ ] YAML frontmatter includes all required fields
+- [ ] Optional fields included only when provided
+- [ ] Markdown body with ## Background section
+- [ ] File does not exceed 100 lines

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

@@ -0,0 +1,79 @@
+<workflow name="create-stakeholder">
+<critical>
+  <mandate>Stakeholder files are written to custom/stakeholders/ — never to _gaia/</mandate>
+  <mandate>The 50-file cap and 100-line limit are hard gates (FR-164)</mandate>
+  <mandate>Duplicate name detection is case-insensitive against the name frontmatter field (FR-157)</mandate>
+</critical>
+
+<step n="1" title="Ensure Directory Exists">
+  <action>Check if {project-root}/custom/stakeholders/ directory exists</action>
+  <action if="directory does not exist">Create {project-root}/custom/stakeholders/ directory (and {project-root}/custom/ if needed)</action>
+  <action>Confirm directory is ready for writing</action>
+</step>
+
+<step n="2" title="Collect Required Inputs">
+  <ask>Provide the following required fields for the new stakeholder:
+
+  **Name** (display name, e.g., "Maria Santos"):
+  **Role** (title/function, e.g., "Housekeeper Manager"):
+  **Expertise** (domain skills, e.g., "Room turnover logistics"):
+  **Personality** (traits, e.g., "Pragmatic, detail-oriented"):
+  </ask>
+  <check if="any required field is empty">HALT: All four fields (name, role, expertise, personality) are required. Please provide all values.</check>
+</step>
+
+<step n="3" title="Collect Optional Inputs">
+  <ask>Optionally provide these additional fields (press Enter to skip):
+
+  **Perspective** (viewpoint/biases, e.g., "Focuses on operational efficiency"):
+  **Tags** (comma-separated, e.g., "operations, hospitality"):
+  </ask>
+</step>
+
+<step n="4" title="Validate Against Cap and Duplicates">
+  <action>Count existing .md files in {project-root}/custom/stakeholders/ directory</action>
+  <check if="count >= 50">HALT: The 50-file cap has been reached in custom/stakeholders/ (FR-164). There are already {count} stakeholder files. Remove unused stakeholders before creating new ones.</check>
+  <action>Scan all existing stakeholder files in custom/stakeholders/*.md — read the name field from each file's YAML frontmatter</action>
+  <action>Compare each existing name against the new stakeholder name using case-insensitive comparison</action>
+  <check if="duplicate name found (case-insensitive match)">HALT: A stakeholder with the name "{existing_name}" already exists at custom/stakeholders/{existing_file}. Name collision detected (case-insensitive). Choose a different name.</check>
+</step>
+
+<step n="5" title="Generate Filename Slug">
+  <action>Convert the stakeholder name to a kebab-case slug:
+    1. Convert to lowercase
+    2. Replace spaces with hyphens
+    3. Strip all characters that are not alphanumeric or hyphens
+    4. Collapse multiple consecutive hyphens into a single hyphen
+    5. Trim leading/trailing hyphens
+    6. Append .md extension
+  </action>
+  <action>Example: "Maria Santos" → "maria-santos.md", "Jean-Pierre O'Brien III" → "jean-pierre-obrien-iii.md"</action>
+  <action>Set output path: {project-root}/custom/stakeholders/{slug}.md</action>
+  <check if="file already exists at output path">HALT: File custom/stakeholders/{slug}.md already exists. This may indicate a slug collision from a different display name. Choose a different name or remove the existing file.</check>
+</step>
+
+<step n="6" title="Generate and Write Stakeholder File">
+  <action>Generate the stakeholder file with YAML frontmatter and Markdown body:
+
+  ```
+  ---
+  name: "{name}"
+  role: "{role}"
+  expertise: "{expertise}"
+  personality: "{personality}"
+  perspective: "{perspective}"    # Only include if provided
+  tags: [{tags_as_yaml_array}]    # Only include if provided
+  ---
+
+  ## Background
+
+  {A 2-3 sentence description synthesized from the provided fields, describing this stakeholder's viewpoint and discussion style.}
+  ```
+  </action>
+  <action>Verify the generated file does not exceed 100 lines. If it does, trim the Background section to fit within the limit.</action>
+  <action>Write the file to {project-root}/custom/stakeholders/{slug}.md</action>
+  <template-output file="{project-root}/custom/stakeholders/{slug}.md">
+    Stakeholder file with YAML frontmatter (name, role, expertise, personality, and optionally perspective and tags) plus a Markdown Background section.
+  </template-output>
+</step>
+</workflow>

package/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/workflow.yaml

@@ -0,0 +1,22 @@
+name: create-stakeholder
+description: 'Scaffold a new stakeholder file for Party Mode discussions'
+module: lifecycle
+agent: orchestrator
+config_resolved: "{installed_path}/.resolved/create-stakeholder.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/create-stakeholder"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+quality_gates:
+  pre_start: []
+  post_complete:
+    - check: "stakeholder_file_line_count_valid == true"
+      on_fail: "HALT: Stakeholder file exceeds 100-line limit (FR-164). Edit {project-root}/custom/stakeholders/{slug}.md to reduce content or re-run /gaia-create-stakeholder."
+    - check: "stakeholder_count_in_directory_valid == true"
+      on_fail: "HALT: custom/stakeholders/ has more than 50 files (FR-164). Remove unused stakeholders from {project-root}/custom/stakeholders/ first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{project-root}/custom/stakeholders/{slug}.md"

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

@@ -92,8 +92,16 @@
   <action>Append DoD checklist: all AC met, tests pass, code reviewed, docs updated</action>
 </step>
 <step n="6" title="Generate Output">
-  <action>Read the story template from {project-root}/_gaia/lifecycle/templates/story-template.md</action>
+  <action>Read the story template from the engine-resolved template path. The engine resolves this in Step 1 (Load and Resolve Config): if {project-root}/custom/templates/story-template.md exists and is non-empty, the custom template is used; otherwise it falls back to {project-root}/_gaia/lifecycle/templates/story-template.md. Use whichever path the engine resolved.</action>
   <action>Read sizing_map from {project-root}/_gaia/_config/global.yaml to resolve T-shirt size to story points (S→2, M→5, L→8, XL→13).</action>
+  <action>Detect invocation context to determine origin fields:
+    If invoked from problem-solving routing (E16-S3): set origin="problem-solving" and origin_ref to the path of the Problem Brief or problem-solving checkpoint artifact (e.g., docs/creative-artifacts/problem-solving-YYYY-MM-DD.md).
+    If invoked from triage routing: set origin="triage" and origin_ref to the triage artifact path.
+    If invoked from add-feature routing: set origin="add-feature" and origin_ref to the source artifact path.
+    If invoked from sprint-planning: set origin="sprint-planning" and origin_ref to the sprint plan artifact path.
+    If invoked with explicit origin parameters from caller: use the provided origin and origin_ref values.
+    If invoked normally (no routing context): set origin=null and origin_ref=null (planned work default).
+  </action>
   <action>Populate ALL YAML frontmatter fields from epics-and-stories.md data:
     - key: story key from epics (e.g., E1-S1)
     - title: story title
@@ -110,6 +118,8 @@
     - date: current date
     - author: agent name (e.g., "Nate (Scrum Master)")
     - priority_flag: null (default — set to "next-sprint" by add-feature for high-urgency stories)
+    - origin: workflow origin (null for planned work, "problem-solving" from problem-solving routing, "triage" from triage, "add-feature" from add-feature routing, "sprint-planning" from sprint planning, "manual" for explicit manual creation)
+    - origin_ref: path to source artifact that triggered story creation (null when origin is null)
   </action>
   <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
     Generate the story file following the story-template.md structure. The filename must use the story key and slugified title (e.g., E1-S1-user-login.md). Include complete YAML frontmatter with ALL 15 fields populated. Fill all template sections: User Story, Acceptance Criteria, Tasks/Subtasks (linked to AC numbers), Dev Notes, Technical Notes, Dependencies, Test Scenarios, Project Structure Notes, References, Dev Agent Record, and Estimate. IMPORTANT: The body "**Status:**" line MUST match the frontmatter status field exactly. Both must say the same status value.

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

@@ -96,7 +96,27 @@
   <action>For each related skill, propose a concrete addition or modification: what section should change, what content to add, and why (link back to the retro finding)</action>
   <action if="yolo_mode">In YOLO mode: auto-approve all recommended skill improvements. Skip the user prompt below.</action>
   <ask>Here are the proposed skill improvements based on this sprint's findings. Approve, modify, or skip each. [approve all / select / skip]</ask>
-  <action>If approved: append to the relevant skill file with comment: "<!-- Added from retro-{sprint_id}: {reason} -->"</action>
+  <action>If approved: write the skill improvement to {project-root}/custom/skills/{skill-name}.md (NOT _gaia/dev/skills/).
+    Follow this sequence for each approved skill improvement:
+
+    1. Ensure directory exists: create {project-root}/custom/skills/ if it does not already exist (mkdir -p equivalent).
+
+    2. Base-skill copy guard: check if {project-root}/custom/skills/{skill-name}.md already exists.
+       - If the custom skill file does NOT exist: copy the base skill from _gaia/dev/skills/{skill-name}.md (resolved at {project-root}) to {project-root}/custom/skills/{skill-name}.md, preserving all &lt;!-- SECTION: xxx --&gt; markers intact. This ensures the engine's sectioned loading continues to work for the custom copy.
+       - If the base skill does NOT exist at _gaia/dev/skills/{skill-name}.md (e.g., removed in a framework update): log a warning ("Base skill {skill-name} not found at _gaia/dev/skills/ — creating custom skill from scratch") and write the improvement content directly to custom/skills/{skill-name}.md without a base copy.
+       - If the custom skill file already exists: preserve existing content and apply the improvement on top.
+
+    3. Apply the improvement: append to or modify the relevant section in custom/skills/{skill-name}.md with comment "<!-- Added from retro-{sprint_id}: {reason} -->".
+
+    4. Register in .customize.yaml: after writing the custom skill file, register it in {project-root}/custom/skills/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs (ADR-020 — customization registries live alongside custom skills in custom/skills/).
+       - If custom/skills/all-dev.customize.yaml does not exist: create it with proper YAML structure:
+         ```yaml
+         skill_overrides:
+           {skill-name}:
+             source: "custom/skills/{skill-name}.md"
+         ```
+       - If custom/skills/all-dev.customize.yaml already exists: read current content, check if a skill_overrides entry for this skill already exists. If it does not exist, append the new entry under skill_overrides. Preserve all existing entries — only add the new one. If it already exists (duplicate), skip registration to prevent duplicate entries.
+  </action>
   <action>If no skill improvements identified, state: "No skill improvements identified this sprint."</action>
 </step>
 <step n="7" title="Cross-Retro Pattern Detection">

package/_gaia/lifecycle/workflows/4-implementation/retrospective/workflow.yaml

@@ -28,4 +28,4 @@ output:
   sidecar_updates:
     - "{memory_path}/*-sidecar/*.md"
   skill_updates:
-    - "{project-root}/_gaia/dev/skills/*.md"
+    - "{project-root}/custom/skills/*.md"

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

@@ -45,6 +45,17 @@
       (file paths, component references, API endpoints, dependency versions).
       Verify against filesystem and ground truth (if available).
       Classify findings as CRITICAL (broken reference), WARNING (outdated), INFO (style).
+
+  (g) Origin Field Validation (optional fields — backward compatible):
+      The origin and origin_ref fields are OPTIONAL — stories without these fields
+      are valid (backward compatibility). Missing origin/origin_ref fields do NOT
+      cause errors and are accepted without warnings.
+      If the origin field IS present, validate:
+        - origin must be one of: "manual", "problem-solving", "triage", "add-feature",
+          "sprint-planning", or null. An invalid origin enum value is a CRITICAL finding.
+        - If origin is non-null, origin_ref must be non-empty (not null, not empty string).
+          A non-null origin with empty or null origin_ref is a WARNING finding.
+      If origin is null or absent, origin_ref is not validated (orphaned refs are acceptable).
   </action>
 </step>
 <step n="3" title="Validation Fix Loop">

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/checklist.md

@@ -18,6 +18,18 @@ validation-target: 'Brownfield onboarding output'
 - [ ] Event catalog subagent completed (if has_events) — {planning_artifacts}/event-catalog.md exists
 - [ ] All API docs use Swagger/OpenAPI format
 - [ ] All diagrams use Mermaid syntax
+## Step 2.5: Deep Analysis Subagents
+- [ ] Config contradiction scanner subagent completed — {planning_artifacts}/brownfield-scan-config-contradiction.md exists
+- [ ] Scanner detected all supported config file types (.yaml, .yml, .json, .env, .toml, .ini, .properties, .xml)
+- [ ] Stack-aware patterns applied based on {tech_stack}
+- [ ] Gap entries conform to standardized schema (gap-entry-schema.md)
+- [ ] Budget control enforced — max ~70 gap entries per scanner
+## Step 2.75: Test Execution During Discovery
+- [ ] Test execution subagent completed — {planning_artifacts}/brownfield-scan-test-execution.md exists (or warning logged if no test suite)
+- [ ] Test runner auto-detection ran for supported runners (npm, pytest, Maven, Gradle, Go, Flutter)
+- [ ] Test failures converted to gap entries conforming to E11-S1 schema
+- [ ] Infrastructure errors distinguished from test failures
+- [ ] Test execution non-blocking — failures did not halt workflow
 ## Step 3: NFR Assessment & Performance Test Plan
 - [ ] NFR assessment subagent completed — {test_artifacts}/nfr-assessment.md exists
 - [ ] NFR baseline summary table has real measured values (not placeholders)

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/instructions.xml

@@ -17,9 +17,23 @@
   <action>Frontend Detection: scan for React, Angular, Vue, Flutter, SwiftUI, UI frameworks, CSS/styling. Set {has_frontend} flag (true/false)</action>
   <action>Testing infrastructure: identify test framework, coverage config, test count, test patterns</action>
   <action>CI/CD: identify GitHub Actions, Jenkins, Docker, Terraform, or other pipeline files</action>
-  <action>Generate brownfield assessment: read {installed_path}/../../templates/brownfield-assessment-template.md — capture component inventory, technical debt, migration constraints, coexistence strategy, and adoption path. Output to {planning_artifacts}/brownfield-assessment.md</action>
+  <action>Project Type Detection (ADR-022 Template Discriminator Pattern): scan {project-path} for infrastructure file patterns across 6 marker categories to determine {project_type}. Each category is independently detected:
+    — Terraform: *.tf, *.tfvars
+    — Docker: Dockerfile, docker-compose.yml
+    — Helm: helm/, Chart.yaml, values.yaml
+    — Kubernetes: k8s/, kustomization.yaml
+    — Pulumi: Pulumi.yaml
+    — CloudFormation: cloudformation*.yaml
+  If ANY infrastructure marker is detected, set {has_infra} = true.</action>
+  <action>Application code detection: scan for framework imports (Express, Spring Boot, Django, FastAPI, Angular, React, Next.js, NestJS, Flask, Gin, Fiber) in source files (*.ts, *.js, *.java, *.py, *.go, *.dart). If framework imports found, set {has_app_code} = true.</action>
+  <action>Classification decision tree — set {project_type}:
+    — If {has_infra} = true AND {has_app_code} = true → {project_type} = platform (infrastructure and application code both present)
+    — If {has_infra} = true AND {has_app_code} = false → {project_type} = infrastructure
+    — If {has_infra} = false → {project_type} = application (default — standard software project)
+  The {project_type} variable is set here in Step 1 so it is available before E11 scanners execute in Step 2.5.</action>
+  <action>Generate brownfield assessment: read {installed_path}/../../templates/brownfield-assessment-template.md — capture component inventory, technical debt, migration constraints, coexistence strategy, and adoption path. Include {project_type} in the assessment output. Output to {planning_artifacts}/brownfield-assessment.md</action>
   <template-output file="{planning_artifacts}/project-documentation.md">
-    Generate enhanced project documentation following the project documentation conventions. Include all standard sections plus: detected capability flags (has_apis, has_events, has_external_deps, has_frontend), testing infrastructure summary, and CI/CD pipeline summary.
+    Generate enhanced project documentation following the project documentation conventions. Include all standard sections plus: detected capability flags (has_apis, has_events, has_external_deps, has_frontend), {project_type}, testing infrastructure summary, and CI/CD pipeline summary.
   </template-output>
 </step>
 
@@ -36,14 +50,158 @@
   </template-output>
 </step>
 
+<step n="2.5" title="Deep Analysis Subagents (Infra-Aware)">
+  <action>Spawn deep analysis scan subagents in parallel using the Agent tool with multiple calls in a single message. These run alongside the Step 2 documentation subagents to detect gaps that structural analysis misses. Each scan subagent receives {tech_stack} (from Step 1), {project-path}, and {project_type} as context variables. When {project_type} is `infrastructure` or `platform`, infra-specific detection patterns are applied alongside application patterns. When {project_type} is `application`, only application patterns are applied.</action>
+
+  <action>Spawn subagent — Config Contradiction Scanner (infra-aware): "Read the config contradiction scan prompt template at {project-root}/_gaia/lifecycle/knowledge/brownfield/config-contradiction-scan.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also apply infra-specific config contradiction patterns for terraform.tfvars, values.yaml, and kustomize overlays as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-config-contradiction.md"</action>
+
+  <action>Spawn subagent — Dead Code &amp; Dead State Scanner: "Read the dead code scan prompt template at {project-root}/_gaia/lifecycle/knowledge/brownfield/dead-code-scan.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. Output to {planning_artifacts}/brownfield-scan-dead-code.md"</action>
+
+  <action>Spawn subagent — Hard-Coded Logic Detector (infra-aware): "Read the hard-coded logic scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-hardcoded-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also detect hard-coded IPs, magic ports, embedded secrets/AMI IDs, and hard-coded resource limits in IaC files as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-hardcoded.md"</action>
+
+  <action>Spawn subagent — Security Endpoint Audit (infra-aware): "Read the security scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-security-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also detect exposed ports in k8s manifests, permissive ingress rules, overly broad RBAC bindings, and missing NetworkPolicy as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-security.md"</action>
+
+  <action>Spawn subagent — Runtime Behavior Inventory (infra-aware): "Read the runtime behavior scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-runtime-behavior-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also catalog CronJobs, DaemonSets, init containers, sidecar patterns, and health probes as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-runtime-behavior.md"</action>
+
+  <action>Spawn subagent — Documentation-Code Mismatch Scanner: "Read the doc-vs-code scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-doc-code-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. Output to {planning_artifacts}/brownfield-scan-doc-code.md"</action>
+
+  <action>Spawn subagent — Integration Seam Analyzer (infra-aware): "Read the integration seam scan prompt template at {project-root}/_gaia/lifecycle/templates/brownfield-scan-integration-seam-prompt.md. Follow the prompt instructions EXACTLY. Use tech stack: {tech_stack}. Project type: {project_type}. Scan the project at {project-path}. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. If project_type is infrastructure or platform: also map service mesh topology, ingress/egress routes, and cross-namespace dependencies as specified in the prompt template. Output to {planning_artifacts}/brownfield-scan-integration-seam.md"</action>
+
+  <action>Wait for all deep analysis subagents to complete. Verify output files exist at {planning_artifacts}/: brownfield-scan-config-contradiction.md, brownfield-scan-dead-code.md, brownfield-scan-hardcoded.md, brownfield-scan-security.md, brownfield-scan-runtime-behavior.md, brownfield-scan-doc-code.md, and brownfield-scan-integration-seam.md.</action>
+  <action>If any subagent failed to write its output file: log a warning and continue — individual scan failures should not block the overall brownfield workflow.</action>
+
+  <!-- Gap-to-Requirement Mapping Reference (E12-S6, ADR-022 §10.16.5)
+       When {project_type} is infrastructure or platform, infra gap categories
+       map to infra PRD sections as follows:
+
+       | Gap Category       | Infra PRD Section          |
+       |--------------------|----------------------------|
+       | resource-drift     | Resource Specifications    |
+       | config-sprawl      | Environment Strategy & DX  |
+       | secret-exposure    | Security Posture           |
+       | missing-policy     | Verification Strategy      |
+       | environment-skew   | Environment Strategy & DX  |
+
+       Application gap categories map to standard PRD sections:
+       | Gap Category          | PRD Section              |
+       |-----------------------|--------------------------|
+       | functional            | Resource Specifications  |
+       | behavioral            | Operational SLOs         |
+       | security              | Security Posture         |
+       | operational           | Operational Runbooks     |
+       | documentation         | Overview & Scope         |
+       | configuration         | Environment Strategy & DX|
+       | data-integrity        | Resource Specifications  |
+
+       This mapping is consumed by the gap consolidation step (E11-S10/S12)
+       and the PRD generation step (Step 4) to route gap findings to the
+       correct sections of the generated PRD. -->
+</step>
+
+<step n="2.75" title="Test Execution During Discovery">
+  <action>After all Step 2/2.5 parallel scan subagents complete, execute the existing test suite at {project-path} to capture test failures as gap entries. This step is non-blocking — test execution failures must not halt the overall brownfield onboarding workflow.</action>
+  <action>Spawn subagent — Test Execution Scanner: "Read the test execution scan prompt template at {project-root}/_gaia/lifecycle/knowledge/brownfield/test-execution-scan.md. Follow the prompt instructions EXACTLY. Scan the project at {project-path} for test runners. Reference the gap entry schema at {project-root}/_gaia/lifecycle/templates/gap-entry-schema.md for output formatting. Auto-detect test runners (package.json with test script, pytest, Maven, Gradle, Go, Flutter) in priority order. Execute each detected runner with a 5-minute timeout. Parse test output for metrics (total, passing, failing, skipped). Convert failing tests to gap entries with severity mapped by test type (unit=medium, integration=high, e2e=critical). Detect infrastructure errors (ECONNREFUSED, missing env vars) and log as warning gaps instead of test failure gaps. For monorepo/polyglot projects, execute all detected runners sequentially and aggregate results. Truncate output per NFR-024 token budget if needed. If no test suite is detected, log an info-level gap entry GAP-TEST-INFO-001. Output to {planning_artifacts}/brownfield-scan-test-execution.md"</action>
+  <action>When subagent returns: verify output file exists at {planning_artifacts}/brownfield-scan-test-execution.md.</action>
+  <action>If the subagent failed to write its output file: log a warning and continue — test execution scan failures should not block the overall brownfield workflow.</action>
+</step>
+
 <step n="3" title="NFR Assessment &amp; Performance Test Plan">
   <action>Spawn a subagent — "Analyze the codebase at {project-path} for non-functional requirements. Read {installed_path}/../../templates/nfr-assessment-template.md for the output format. Assess: code quality (linting, complexity, duplication), security posture (dependency vulnerabilities, secrets handling, auth quality — load security-basics skill section vulnerability-scanning if needed), performance (bundle size if frontend, query patterns, caching, resource management), accessibility (ARIA, semantic HTML, keyboard nav if frontend), test coverage (framework, count, coverage %, untested areas, quality), CI/CD (build pipeline, deploy strategy, environments, IaC). Create NFR Baseline Summary Table with measured values (not placeholders). Output to {test_artifacts}/nfr-assessment.md. Then create a performance test plan: load {project-root}/_gaia/testing/knowledge/performance/k6-patterns.md for load testing patterns. If {has_frontend}: also load {project-root}/_gaia/testing/knowledge/performance/lighthouse-ci.md. Define performance budgets (P50/P95/P99) based on NFR baselines, load test scenarios (gradual, spike, soak), backend profiling targets (slow queries, N+1, connection pools), CI performance gates. If {has_frontend}: define Core Web Vitals targets (LCP under 2.5s, INP under 200ms, CLS under 0.1). Output to {test_artifacts}/performance-test-plan-{date}.md"</action>
   <action>When subagent returns: verify both {test_artifacts}/nfr-assessment.md and {test_artifacts}/performance-test-plan-{date}.md exist. If the subagent failed to write files, the orchestrator MUST write them to {test_artifacts}/ as declared in workflow.yaml output.artifacts — do NOT fall back to {planning_artifacts}/.</action>
 </step>
 
+<step n="3.5" title="Gap Consolidation &amp; Deduplication">
+  <action>Spawn a subagent using the Agent tool with this prompt:
+
+  "You are the Gap Consolidation subagent. Your task is to load all scan results, deduplicate them, rank them, and produce a single consolidated output file.
+
+  **Context:**
+  - Planning artifacts directory: {planning_artifacts}/
+  - Test artifacts directory: {test_artifacts}/
+  - Gap schema reference: {installed_path}/../../templates/gap-entry-schema.md
+  - Tech stack: {tech_stack}
+
+  **Step 1 — Load all scan outputs:**
+  Load gap entries from ALL of the following sources. For each file, if it exists, parse YAML gap entries matching the schema from gap-entry-schema.md. If a file is empty or missing, log a warning noting which scanner produced no results and continue processing the remaining files without error.
+
+  Deep analysis scan outputs (7 files — Step 2.5):
+  - {planning_artifacts}/brownfield-scan-config-contradiction.md
+  - {planning_artifacts}/brownfield-scan-dead-code.md
+  - {planning_artifacts}/brownfield-scan-hardcoded.md
+  - {planning_artifacts}/brownfield-scan-security.md
+  - {planning_artifacts}/brownfield-scan-runtime-behavior.md
+  - {planning_artifacts}/brownfield-scan-doc-code.md
+  - {planning_artifacts}/brownfield-scan-integration-seam.md
+
+  Test execution scan output (1 file — Step 2.75):
+  - {planning_artifacts}/brownfield-scan-test-execution.md (failing tests as gap entries)
+
+  Step 2 documentation subagent outputs (4 files):
+  - {planning_artifacts}/api-documentation.md (API gaps)
+  - {planning_artifacts}/event-catalog.md (event/messaging gaps)
+  - {planning_artifacts}/ux-design.md (frontend/UX gaps)
+  - {planning_artifacts}/dependency-map.md (dependency gaps)
+
+  Step 3 NFR assessment:
+  - {test_artifacts}/nfr-assessment.md (NFR gap findings)
+
+  **Step 2 — Validate entries against schema:**
+  For each parsed gap entry, validate that all required fields are present: id, category, severity, title, description (or evidence), evidence_file, evidence_line, recommendation. Entries missing any required field are logged as warnings (noting the source file and which field is missing) and skipped from consolidation rather than causing a failure.
+
+  **Step 3 — Deduplicate:**
+  Group gap entries by evidence_file + evidence_line (exact match on both fields). For each group of duplicates:
+  a. Retain the entry with the highest severity (critical > high > medium > low)
+  b. Merge recommendations from all duplicate entries into the retained entry
+  c. Add a merged_from field listing all original gap IDs that were merged
+  d. If duplicates have different categories, retain the primary category from the highest-severity entry and note the alternate category in the description
+
+  **Step 4 — Rank:**
+  Sort the deduplicated gaps by:
+  1. severity DESC (critical first, then high, medium, low)
+  2. confidence DESC (high first, then medium, low)
+  3. category alphabetical within each severity+confidence tier
+  Assign final sequential numbering to the ranked list.
+
+  **Step 5 — Budget check:**
+  Estimate the token count of the output (~100 tokens per gap entry). If the estimated total exceeds the 40K token budget, truncate low-severity and info entries with a count summary: 'N additional low/info gaps omitted for budget'. Ensure the output stays within budget.
+
+  **Step 6 — Generate consolidated output:**
+  Write consolidated-gaps.md to {planning_artifacts}/ using the consolidated output format from gap-entry-schema.md. Include summary statistics at the top:
+  - Total raw gaps (pre-dedup count)
+  - Duplicates removed
+  - Final unique count
+  - Breakdown by category (all categories found)
+  - Breakdown by severity (critical, high, medium, low)
+  - Per-scanner source counts
+
+  Output to {planning_artifacts}/consolidated-gaps.md"
+  </action>
+  <action>When subagent returns: verify {planning_artifacts}/consolidated-gaps.md exists. If the subagent failed to write the file, log error and halt.</action>
+  <template-output file="{planning_artifacts}/consolidated-gaps.md">
+    Consolidated gap analysis with deduplicated, ranked gaps in standardized schema format. Includes summary statistics header.
+  </template-output>
+</step>
+
 <step n="4" title="Create PRD for Gaps">
-  <action>Read the PRD template from {installed_path}/../../templates/prd-template.md</action>
+  <action>Select PRD template based on {project_type} (set by Step 1 discovery). Template selection is a simple lookup — no template inheritance or composition at runtime:
+
+  | project_type     | Template File              | Requirement ID Scheme                        |
+  |------------------|----------------------------|----------------------------------------------|
+  | application      | prd-template.md            | FR-###, NFR-###                              |
+  | infrastructure   | infra-prd-template.md      | IR-###, OR-###, SR-###                       |
+  | platform         | platform-prd-template.md   | FR-###, NFR-### and IR-###, OR-###, SR-###   |
+
+  Resolve template path: {installed_path}/../../templates/{selected_template}.
+  Verify the selected template file exists before proceeding. If the template file is missing, HALT with: "Template {selected_template} not found at {installed_path}/../../templates/. Ensure E12-S2 (infra) or E12-S3 (platform) templates are installed."
+  If {project_type} is not set or unrecognized, default to application (prd-template.md) for backward compatibility.</action>
+  <action>Read the selected PRD template from {installed_path}/../../templates/{selected_template}</action>
+  <action>Set requirement ID scheme based on {project_type}:
+  — If application: use FR-### for functional requirements and NFR-### for non-functional requirements (existing behavior, backward compatible)
+  — If infrastructure: use IR-### for infrastructure requirements, OR-### for operational requirements, and SR-### for security requirements exclusively. Do NOT use FR/NFR prefixes.
+  — If platform: use BOTH ID scheme families — FR-###/NFR-### for application-layer requirements and IR-###/OR-###/SR-### for infrastructure-layer requirements. All requirement IDs are globally unique within the project — the prefix disambiguates (e.g., FR-001 and IR-001 are distinct, no collision).</action>
   <action>Read upstream artifacts to inform gap analysis:</action>
+  <action>— project-documentation.md → project context: tech stack, architecture patterns, conventions, detected capability flags, CI/CD summary. Use for PRD Overview section (existing project summary) and to ground gap requirements in the actual project structure.</action>
+  <action>— consolidated-gaps.md → primary input: deduplicated, ranked, and code-verified gap list from Steps 3.5 and 5.5. If a '## Verification Corrections for PRD' section exists, use it to correct factual errors from contradicted claims.</action>
   <action>— nfr-assessment.md → NFR section gets real "Current Baseline" and "Target" columns</action>
   <action>— api-documentation.md (if exists) → extract API gaps (undocumented endpoints, missing validation)</action>
   <action>— event-catalog.md (if exists) → extract messaging gaps (missing DLQ, missing schemas)</action>
@@ -73,6 +231,92 @@
   </template-output>
 </step>
 
+<step n="5.5" title="Code-Verified Review">
+  <action>Spawn a subagent using the Agent tool with this prompt:
+
+  "You are the Code-Verified Review subagent. Your task is to verify every factual claim in the consolidated gap entries against the actual codebase, classify each gap, and update the consolidated output.
+
+  **Context:**
+  - Consolidated gaps file: {planning_artifacts}/consolidated-gaps.md
+  - Codebase root: {project-path}
+  - Tech stack: {tech_stack}
+  - Gap schema reference: {installed_path}/../../templates/gap-entry-schema.md
+
+  **Step 1 — Load and parse consolidated-gaps.md:**
+  Read {planning_artifacts}/consolidated-gaps.md. Parse all YAML gap entries matching the standardized gap schema. If the file is empty or contains zero parseable gap entries, output a summary stating '0 gaps to verify' and exit gracefully without error, producing an empty verification report.
+
+  Handle malformed gap entries: if a gap entry is missing required fields (id, category, severity, title, description, evidence_file, recommendation), log a warning noting which field is missing and which entry, skip the entry, and include it in the summary as a skipped entry.
+
+  **Step 2 — Extract verifiable claims from each gap entry:**
+  For each valid gap entry, extract all machine-verifiable claims:
+  a. File existence: extract the `evidence_file` field — this is a relative path from {project-path} that should exist in the codebase.
+  b. Line range validity: extract the `evidence_line` field — this line number must be within the file's total line count.
+  c. Pattern/string presence: extract patterns, strings, or code snippets from the `description` and `recommendation` fields that claim specific code patterns exist in the referenced file.
+  d. Configuration key existence: for gaps in the `configuration` category, extract config key paths claimed to exist in YAML/JSON config files.
+
+  For gap entries with no verifiable claims (purely subjective descriptions with no file/line/pattern references), classify as `unverifiable` with reason 'No machine-verifiable claims'.
+
+  **Step 3 — Verify each claim against the codebase at {project-path}:**
+  Use grep, glob, and read tools for all verification (not shell commands). For each claim:
+
+  a. File existence check: Use glob/read to check if {project-path}/{evidence_file} exists.
+     - If the file does not exist: classify the gap as `contradicted` with reason 'Referenced file not found: {evidence_file}'. Preserve the original gap with downgraded confidence.
+     - If the file is a binary file (detected by extension: .png, .jpg, .gif, .woff, .ttf, .ico, .pdf, .zip, .tar, .gz, .exe, .dll, .so, .dylib): classify as `unverifiable` with reason 'Binary file — cannot verify textual claims'.
+
+  b. Line range validation: Read the file and count total lines. Compare against `evidence_line`.
+     - If evidence_line exceeds the file's total line count: classify as `contradicted` with reason 'Line {evidence_line} exceeds file length ({actual_lines} lines)'. Flag the entry for correction.
+
+  c. Pattern search: Use grep to search for stated patterns in the referenced file. Handle regex special characters safely by escaping them.
+     - If the pattern is found: this claim is confirmed.
+     - If the pattern is not found: this contributes to a `contradicted` classification.
+
+  d. Config key verification: For configuration-category gaps, parse YAML/JSON config files and check for key existence at the stated paths.
+     - If the key exists: claim confirmed.
+     - If the key does not exist: contributes to `contradicted` classification.
+
+  **Step 4 — Apply tristate classification to each gap:**
+  Based on the verification results from Step 3:
+  - **verified**: All verifiable claims in the gap entry are confirmed by evidence in the codebase. Set `verification_status: verified`.
+  - **unverifiable**: Claims cannot be confirmed or denied from code alone (e.g., runtime behavior, subjective assessments, binary files, no verifiable claims). Set `verification_status: unverifiable`.
+  - **contradicted**: Evidence in the codebase directly contradicts one or more claims. Set `verification_status: contradicted`.
+
+  For contradicted gaps:
+  - Downgrade the confidence of the original gap entry.
+  - Attach a `reason` string explaining exactly what was contradicted and what was found instead.
+  - Generate a new gap entry using the standardized gap schema with:
+    - `id`: GAP-VERIFIED-{seq}
+    - `category`: preserved from original gap
+    - `severity`: inherited from original gap
+    - `verified_by: "code-verified"`
+    - `description`: details of the contradiction and the actual state found in codebase
+
+  **Step 5 — Update consolidated-gaps.md:**
+  Write back to {planning_artifacts}/consolidated-gaps.md with the following additions to each gap entry:
+  - `verification_status`: verified | unverifiable | contradicted
+  - `verified_by: "code-verified"`
+  Preserve all existing fields on each entry — do not remove or overwrite original data.
+  Append new gap entries generated from contradicted claims at the end of the file.
+
+  **Step 6 — Generate verification summary:**
+  Output a summary report including:
+  - Total gaps processed
+  - Verified count
+  - Unverifiable count
+  - Contradicted count
+  - New gap entries generated from contradicted claims
+  - Skipped entries (malformed) count
+
+  **Step 7 — Feed contradicted claims back to Step 4:**
+  Contradicted claims must be fed back to Step 4 (PRD generation) for correction. Write the list of contradicted entries and their reasons to a section at the top of consolidated-gaps.md marked '## Verification Corrections for PRD'. This section will be read by Step 4 when the PRD is regenerated to correct factual errors.
+
+  Output to {planning_artifacts}/consolidated-gaps.md"
+  </action>
+  <action>When subagent returns: verify {planning_artifacts}/consolidated-gaps.md has been updated with verification_status fields. If the subagent failed, log error and halt.</action>
+  <template-output file="{planning_artifacts}/consolidated-gaps.md">
+    Code-verified consolidated gaps with verification_status and verified_by fields on each entry. Includes verification summary and corrections section for PRD feedback.
+  </template-output>
+</step>
+
 <step n="6" title="Architecture">
   <action>Architecture is created using the Phase 3 workflow which auto-detects brownfield mode from the PRD "Mode: Brownfield" header set in step 4.</action>
   <action>If {planning_artifacts}/architecture.md already exists: WARN user — "An architecture document already exists. Continuing will overwrite it with the brownfield version. Choose: (a) overwrite, (b) save as architecture-brownfield.md instead." If user chooses (b), instruct the subagent to output to {planning_artifacts}/architecture-brownfield.md.</action>
@@ -92,7 +336,7 @@
   <check if="refresh-ground-truth workflow directory not found">Val ground truth bootstrap skipped — refresh-ground-truth workflow not available. Run /gaia-refresh-ground-truth manually after E8-S9 is implemented. Brownfield onboarding completes successfully.</check>
 
   <action>Invoke /gaia-refresh-ground-truth to scan the filesystem and populate framework inventory facts (workflows, agents, skills, commands) into ground-truth.md</action>
-  <invoke-workflow ref="refresh-ground-truth" mode="yolo" />
+  <invoke-workflow ref="val-refresh-ground-truth" mode="yolo" />
 
   <action>Load brownfield-extraction section of ground-truth-management skill JIT from {project-root}/_gaia/lifecycle/skills/ground-truth-management.md</action>
   <action>Read available brownfield artifacts and extract project-specific facts. For each artifact, check if the file exists before reading — skip missing artifacts without error: