gaia-framework 1.65.1 → 1.66.0

package/_gaia/lifecycle/templates/platform-prd-template.md

@@ -0,0 +1,431 @@
+---
+template: 'platform-prd'
+version: 1.0.0
+used_by: ['create-prd']
+domain: '{domain}'
+---
+
+# Platform PRD: {product_name}
+
+> **Project:** {project_name}
+> **Domain:** {domain}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Status:** Draft | In Review | Approved
+> **Project Type:** Platform (application + infrastructure)
+
+> Requirement IDs use prefixes to disambiguate scope: FR-### and NFR-### for application requirements, IR-###, OR-###, and SR-### for infrastructure requirements. IDs are globally unique within a project — each prefix defines a separate namespace.
+
+---
+
+# Part I: Application Requirements
+
+## 1. Overview
+
+{Brief product overview and context. What is being built and why.}
+
+## 2. Goals and Non-Goals
+
+### Goals
+- {Goal 1}
+- {Goal 2}
+
+### Non-Goals
+- {Explicitly out of scope item 1}
+
+## 3. User Stories
+
+| ID | As a... | I want to... | So that... | Priority |
+|----|---------|-------------|-----------|----------|
+| US-01 | {role} | {action} | {benefit} | {P0-P3} |
+
+## 4. Functional Requirements
+
+### 4.1 {Feature Area}
+
+- **FR-01:** {Requirement description}
+- **FR-02:** {Requirement description}
+
+## 5. Non-Functional Requirements
+
+| ID | Category | Requirement | Target |
+|----|----------|------------|--------|
+| NFR-001 | Performance | {requirement} | {target} |
+| NFR-002 | Security | {requirement} | {target} |
+| NFR-003 | Accessibility | {requirement} | {target} |
+
+## 6. Out of Scope
+
+| Exclusion | Reason |
+|-----------|--------|
+| {feature or integration} | {deferred / not needed / separate product} |
+
+## 7. UX Requirements
+
+{Key interaction patterns, wireframe references, accessibility needs.}
+
+## 8. Technical Constraints
+
+- {Platform, language, or integration constraint}
+
+## 9. Dependencies
+
+| Dependency | Type | Failure Mode | Fallback Behavior | SLA Expectation |
+|------------|------|-------------|-------------------|-----------------|
+| {service or system} | {API / Database / Message Queue / CDN / Auth Provider} | {What happens when it's unavailable} | {Graceful degradation / Retry / Queue / Circuit breaker / Hard fail} | {Expected uptime / latency / throughput} |
+
+## 10. Milestones
+
+| Milestone | Target Date | Deliverables |
+|-----------|------------|-------------|
+| {milestone} | {date} | {deliverables} |
+
+---
+
+# Part II: Infrastructure Requirements
+
+## 11. Platform Overview & Scope
+
+{Platform purpose, target environments, and team ownership.}
+
+### Platform Purpose
+
+{What this infrastructure provides and why it exists.}
+
+### Target Environments
+
+| Environment | Purpose | Region(s) | Owner |
+|-------------|---------|-----------|-------|
+| {env_name} | {purpose} | {regions} | {team} |
+
+### Team Ownership
+
+| Component | Owning Team | Escalation |
+|-----------|-------------|------------|
+| {component} | {team} | {contact} |
+
+## 12. Platform Capabilities
+
+{What the infrastructure enables. Each capability follows the format below.}
+
+| ID | Capability | SLO |
+|----|-----------|-----|
+| PC-01 | Enable {team/service} to {capability} with {SLO} | {target} |
+| PC-02 | Enable {team/service} to {capability} with {SLO} | {target} |
+
+## 13. Resource Specifications
+
+{Compute, storage, networking, IAM provisioning. Per-environment breakdown.}
+
+### Compute
+
+| Resource | Environment | Spec | Scaling |
+|----------|-------------|------|---------|
+| {resource} | {env} | {cpu/memory} | {auto/manual, min-max} |
+
+### Storage
+
+| Store | Type | Size | IOPS | Backup |
+|-------|------|------|------|--------|
+| {store} | {block/object/file} | {size} | {iops} | {policy} |
+
+### Networking
+
+| Component | CIDR/Range | Protocol | Purpose |
+|-----------|-----------|----------|---------|
+| {component} | {cidr} | {protocol} | {purpose} |
+
+### IAM Provisioning
+
+| Role/Policy | Scope | Permissions | Lifecycle |
+|-------------|-------|-------------|-----------|
+| {role} | {scope} | {permissions} | {create/rotate/revoke} |
+
+### State Management
+
+{State backend strategy — e.g., Terraform remote state, locking, encryption.}
+
+| Backend | Lock Provider | Encryption | Workspace Strategy |
+|---------|--------------|------------|-------------------|
+| {backend} | {lock} | {encryption} | {workspace} |
+
+### Data Persistence Requirements
+
+| Data Store | Durability | Replication | Retention |
+|------------|-----------|-------------|-----------|
+| {store} | {durability} | {replication} | {retention} |
+
+## 14. Operational SLOs
+
+{Availability targets, MTTR, RTO/RPO, error budgets, resource utilization targets.}
+
+### Availability & Recovery
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Availability | {99.x%} | {how measured} |
+| MTTR | {minutes} | {how measured} |
+| RTO | {minutes} | {recovery time objective} |
+| RPO | {minutes} | {recovery point objective} |
+| Error Budget | {x% per month} | {how calculated} |
+
+### Resource Utilization Targets
+
+| Resource | Target Utilization | Alert Threshold |
+|----------|-------------------|-----------------|
+| CPU | {target%} | {alert%} |
+| Memory | {target%} | {alert%} |
+| Storage IOPS | {target} | {threshold} |
+| Network Bandwidth | {target Gbps} | {threshold} |
+| Network Latency | {target ms} | {threshold} |
+
+## 15. Security Posture
+
+{Security requirements tailored for infrastructure projects.}
+
+### IAM/RBAC
+
+{Identity and access management, role-based access control policies.}
+
+| Principal | Role | Scope | MFA Required | Review Cadence |
+|-----------|------|-------|-------------|----------------|
+| {principal} | {role} | {scope} | {yes/no} | {quarterly/annually} |
+
+### Network Segmentation
+
+{Network isolation, security groups, firewall rules, zero-trust boundaries.}
+
+| Zone | CIDR | Ingress Rules | Egress Rules | Purpose |
+|------|------|---------------|-------------|---------|
+| {zone} | {cidr} | {rules} | {rules} | {purpose} |
+
+### Secrets Management
+
+{Secrets storage, rotation, injection, and audit strategy.}
+
+| Secret Type | Store | Rotation | Injection Method |
+|-------------|-------|----------|-----------------|
+| {type} | {vault/kms/ssm} | {cadence} | {env var/sidecar/init container} |
+
+### Image Provenance
+
+{Container image signing, scanning, and supply chain verification.}
+
+| Registry | Signing | Scanning | Admission Policy |
+|----------|---------|----------|-----------------|
+| {registry} | {cosign/notary} | {trivy/grype} | {policy} |
+
+### Compliance Mapping
+
+{Regulatory and compliance framework alignment.}
+
+| Framework | Controls | Evidence | Audit Frequency |
+|-----------|----------|----------|----------------|
+| {SOC2/HIPAA/PCI/ISO} | {control IDs} | {how demonstrated} | {cadence} |
+
+## 16. Environment Strategy & Developer Experience
+
+{Environment parity, promotion pipeline, drift detection, self-service provisioning.}
+
+### Environment Parity
+
+| Dimension | Dev | Staging | Production |
+|-----------|-----|---------|-----------|
+| {dimension} | {dev config} | {staging config} | {prod config} |
+
+### Promotion Pipeline
+
+{How changes flow from dev to production.}
+
+```
+{dev} → {staging} → {production}
+```
+
+### Drift Detection
+
+{How configuration drift is detected and remediated.}
+
+| Tool | Schedule | Remediation | Notification |
+|------|----------|-------------|-------------|
+| {tool} | {cron} | {auto/manual} | {channel} |
+
+### Self-Service Provisioning
+
+{Developer self-service capabilities and guardrails.}
+
+| Capability | Interface | Guardrails | Approval |
+|------------|-----------|-----------|----------|
+| {capability} | {CLI/portal/API} | {policy} | {auto/manual} |
+
+### Onboarding
+
+{New team member and new service onboarding procedures.}
+
+### Observability
+
+{Monitoring, logging, tracing, and alerting strategy.}
+
+| Signal | Tool | Retention | Alerting |
+|--------|------|-----------|---------|
+| Metrics | {prometheus/cloudwatch} | {retention} | {pagerduty/slack} |
+| Logs | {elk/cloudwatch} | {retention} | {rules} |
+| Traces | {jaeger/xray} | {retention} | {rules} |
+
+## 17. Dependencies & Provider Constraints
+
+{Cloud provider limits, Terraform provider versions, upstream service contracts.}
+
+### Cloud Provider Limits
+
+| Provider | Service | Limit | Current Usage | Headroom |
+|----------|---------|-------|--------------|----------|
+| {provider} | {service} | {limit} | {current} | {remaining} |
+
+### Terraform Provider Versions
+
+| Provider | Version | Constraint | Notes |
+|----------|---------|-----------|-------|
+| {provider} | {version} | {~> x.y} | {notes} |
+
+### Upstream Service Contracts
+
+| Service | SLA | API Version | Deprecation |
+|---------|-----|------------|-------------|
+| {service} | {sla} | {version} | {date or N/A} |
+
+## 18. Cost Model
+
+{Per-environment resource cost estimates, scaling cost projections, and cost-per-unit efficiency metrics.}
+
+### Per-Environment Resource Cost Estimates
+
+| Resource | Dev (monthly) | Staging (monthly) | Production (monthly) |
+|----------|--------------|-------------------|---------------------|
+| Compute | ${cost} | ${cost} | ${cost} |
+| Storage | ${cost} | ${cost} | ${cost} |
+| Networking | ${cost} | ${cost} | ${cost} |
+| Monitoring | ${cost} | ${cost} | ${cost} |
+| **Total** | **${total}** | **${total}** | **${total}** |
+
+### Scaling Cost Projections
+
+| Scenario | Trigger | Additional Cost | Timeline |
+|----------|---------|----------------|----------|
+| {scenario} | {trigger condition} | ${projection} | {timeframe} |
+
+### Cost-Per-Unit Efficiency Metrics
+
+| Metric | Current | Target | Optimization |
+|--------|---------|--------|-------------|
+| Cost per request | ${cost} | ${target} | {strategy} |
+| Cost per GB stored | ${cost} | ${target} | {strategy} |
+| Cost per environment | ${cost} | ${target} | {strategy} |
+
+## 19. Verification Strategy
+
+{Policy-as-code (OPA/Rego, Checkov, tfsec), plan validation, smoke tests, drift detection, chaos testing.}
+
+### Policy-as-Code
+
+| Tool | Scope | Rules | Enforcement |
+|------|-------|-------|-------------|
+| OPA/Rego | {scope} | {rule count} | {warn/deny} |
+| Checkov | {scope} | {rule count} | {warn/deny} |
+| tfsec | {scope} | {rule count} | {warn/deny} |
+
+### Plan Validation
+
+{Terraform plan review, cost estimation, blast radius analysis.}
+
+| Check | Tool | Gate | Threshold |
+|-------|------|------|-----------|
+| {check} | {tool} | {CI/manual} | {threshold} |
+
+### Smoke Tests
+
+{Post-deployment verification tests.}
+
+| Test | Target | Expected | Timeout |
+|------|--------|----------|---------|
+| {test} | {endpoint/resource} | {result} | {timeout} |
+
+### Drift Detection
+
+{Scheduled plan diffs, state file monitoring, compliance scanning.}
+
+### Chaos Testing
+
+{Failure injection, resilience validation.}
+
+| Experiment | Target | Hypothesis | Blast Radius |
+|-----------|--------|-----------|-------------|
+| {experiment} | {target} | {hypothesis} | {scope} |
+
+## 20. Operational Runbooks
+
+{Scaling, failover, incident response, rollback procedures.}
+
+### Scaling Procedures
+
+| Trigger | Action | Rollback | Owner |
+|---------|--------|----------|-------|
+| {trigger} | {action} | {rollback} | {team} |
+
+### Failover Procedures
+
+| Scenario | Detection | Response | RTO |
+|----------|-----------|----------|-----|
+| {scenario} | {detection} | {response steps} | {rto} |
+
+### Incident Response
+
+| Severity | Notification | Escalation | Runbook |
+|----------|-------------|------------|---------|
+| P1 | {channel} | {escalation path} | {link} |
+| P2 | {channel} | {escalation path} | {link} |
+
+### Rollback Procedures
+
+| Change Type | Rollback Method | Verification | Duration |
+|-------------|----------------|-------------|----------|
+| {type} | {method} | {verification} | {estimate} |
+
+---
+
+# Part III: Combined Requirements Summary
+
+## 21. Requirements Summary
+
+> IDs are globally unique within a project. The prefix disambiguates the requirement scope: FR/NFR for application, IR/OR/SR for infrastructure.
+
+### Application Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| FR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| NFR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Infrastructure Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| IR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| IR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Operational Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| OR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| OR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Security Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| SR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| SR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+## 22. Open Questions
+
+- [ ] {Unresolved question}

package/_gaia/lifecycle/templates/prd-template.md

@@ -81,3 +81,73 @@ used_by: ['create-prd']
 ## 12. Open Questions
 
 - [ ] {Unresolved question}
+
+<!-- BROWNFIELD-ONLY-START -->
+
+## Gap Analysis Summary
+
+| Category | Critical | High | Medium | Low | Total |
+|----------|----------|------|--------|-----|-------|
+| Config Contradictions | {count} | {count} | {count} | {count} | {count} |
+| Dead Code & Dead State | {count} | {count} | {count} | {count} | {count} |
+| Hard-Coded Business Logic | {count} | {count} | {count} | {count} | {count} |
+| Security Endpoints | {count} | {count} | {count} | {count} | {count} |
+| Runtime Behaviors | {count} | {count} | {count} | {count} | {count} |
+| Documentation Drift | {count} | {count} | {count} | {count} | {count} |
+| Integration Seams | {count} | {count} | {count} | {count} | {count} |
+| **Overall** | **{count}** | **{count}** | **{count}** | **{count}** | **{count}** |
+
+## Gap Analysis by Category
+
+### Config Contradictions (`configuration`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Dead Code & Dead State (`functional`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Hard-Coded Business Logic (`functional`, `behavioral`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Security Endpoints (`security`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Runtime Behaviors (`behavioral`, `operational`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Documentation Drift (`documentation`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Integration Seams (`data-integrity`, `operational`)
+
+| ID | Severity | Title | Description | Evidence | Recommendation | Verified By | Confidence |
+|----|----------|-------|-------------|----------|----------------|-------------|------------|
+| — | — | No gaps detected in this category. | — | — | — | — | — |
+
+### Verified By Legend
+
+| Value | Description |
+|-------|-------------|
+| `machine-detected` | Gap found by automated scan subagent |
+| `adversarial-review-detected` | Gap found during adversarial review |
+| `code-verified` | Gap confirmed by code-verified review step |
+| `human-reported` | Gap reported manually by a human reviewer |
+
+<!-- BROWNFIELD-ONLY-END -->

package/_gaia/lifecycle/workflows/4-implementation/add-feature/checklist.md

@@ -32,7 +32,7 @@ validation-target: 'Feature/Enhancement/Patch Triage and Cascade'
 - [ ] Failed steps handled with retry/skip/abort options
 - [ ] Checkpoint saved for /gaia-resume recovery
 ## Story
-- [ ] Implementation stories created (or patch story recommended)
+- [ ] Implementation stories created (patch, enhancement, and feature all create stories via subagent)
 - [ ] Story keys captured
 ## Assessment Doc
 - [ ] Assessment document generated at {planning_artifacts}/add-feature-{feature_id}.md

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

@@ -148,7 +148,7 @@
   <action>If classification is 'feature' or 'enhancement': spawn subagent to create implementation stories.</action>
   <action>Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/4-implementation/add-stories/workflow.yaml as workflow-config. Run in YOLO mode. Context: {classification} — {description}. New requirements: {prd_diff}. Architecture changes: {arch_diff}. Feature ID: {feature_id}."</action>
   <action>When subagent returns: capture new story keys and epic assignments.</action>
-  <action>If classification is 'patch': create a single fix story inline or recommend /gaia-create-story.</action>
+  <action>If classification is 'patch': spawn subagent to create a fix story. Spawn subagent: "Load {project-root}/_gaia/core/engine/workflow.xml, then process {project-root}/_gaia/lifecycle/workflows/4-implementation/create-story/workflow.yaml as workflow-config. Run in YOLO mode. Context: patch fix — {description}. Feature ID: {feature_id}." When subagent returns: capture the new story key.</action>
   <action>Priority flag integration: if the feature driver is high-urgency (P0 priority, business-critical, or regulatory driver), set priority_flag: "next-sprint" in each created story's frontmatter. This signals sprint planning to auto-include these stories in the next sprint cycle. For non-urgent features, priority_flag remains null (default).</action>
 </step>
 
@@ -181,8 +181,7 @@
   <action>Present summary and recommended next actions based on classification and outcome:
 
   **Patch:**
-  - If story created: "Run /gaia-dev-story {story_key} to implement the fix."
-  - If no story: "The patch is straightforward — apply directly or create a story with /gaia-create-story."
+  - "Run `/gaia-dev-story {story_key}` to implement the fix."
 
   **Enhancement:**
   - "New stories created: {story_keys}. Run /gaia-sprint-plan or /gaia-correct-course to schedule."

package/_gaia/lifecycle/workflows/4-implementation/add-stories/checklist.md

@@ -22,6 +22,11 @@ validation-target: 'Updated epics-and-stories.md'
 - [ ] Source: CR-{cr_id} added (if change request linked)
 ## Change Log
 - [ ] Change log entry added with date, feature name, and CR ID
+## Inline Validation
+- [ ] Inline validation invoked for each new story
+- [ ] Fix loop executed if CRITICAL/WARNING findings found (max 3 attempts)
+- [ ] Validation results recorded per story (validated / validating / degraded)
+- [ ] Graceful degradation handled if Val unavailable (prerequisites missing or invocation failure)
 ## Existing Content
 - [ ] Existing stories not modified
 - [ ] Existing epic structure preserved

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-story/instructions.xml

@@ -92,7 +92,7 @@
   <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>Populate ALL YAML frontmatter fields from epics-and-stories.md data:
     - key: story key from epics (e.g., E1-S1)

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}/_gaia/_config/agents/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs.
+       - If 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 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"