gaia-framework 1.64.0 → 1.65.1

package/_gaia/lifecycle/config.yaml

@@ -2,7 +2,7 @@
 inherits: "{project-root}/_gaia/_config/global.yaml"
 
 module_name: "lifecycle"
-module_version: "1.37.0"
+module_version: "1.37.2"
 
 planning_artifacts: "{project-root}/docs/planning-artifacts"
 implementation_artifacts: "{project-root}/docs/implementation-artifacts"

package/_gaia/lifecycle/module-help.csv

@@ -6,7 +6,7 @@ name,code,command,description,agent
 "advanced-elicitation","advanced-elicitation","gaia-advanced-elicitation","Deep requirements elicitation","orchestrator"
 "create-product-brief","product-brief","gaia-product-brief","Create a product brief","analyst"
 "create-prd","create-prd","gaia-create-prd","Create a PRD","pm"
-"validate-prd","validate-prd","gaia-validate-prd","Validate PRD against standards","pm"
+"validate-prd","validate-prd","gaia-validate-prd","DEPRECATED — Use /gaia-val-validate instead","pm"
 "edit-prd","edit-prd","gaia-edit-prd","Edit an existing PRD","pm"
 "create-ux-design","create-ux","gaia-create-ux","Create UX design specifications","ux-designer"
 "create-architecture","create-arch","gaia-create-arch","Design system architecture","architect"

package/_gaia/lifecycle/skills/document-rulesets.md

@@ -0,0 +1,166 @@
+---
+name: document-rulesets
+version: '1.0'
+applicable_agents: [validator]
+description: 'Document-specific validation rulesets for artifact type detection, structural quality checks per artifact type, and two-pass validation logic.'
+sections: [type-detection, prd-rules, arch-rules, ux-rules, test-plan-rules, epics-rules, two-pass-logic]
+---
+
+<!-- SECTION: type-detection -->
+## Artifact Type Detection
+
+### Path-to-Ruleset Mapping
+
+Detect the artifact type from the file path basename. Match against these patterns:
+
+| File Pattern | Ruleset ID | Description |
+|-------------|------------|-------------|
+| `prd.md` | prd-rules | Product Requirements Document |
+| `architecture.md` | arch-rules | Architecture Document |
+| `ux-design.md` | ux-rules | UX Design Specification |
+| `test-plan.md` | test-plan-rules | Test Plan |
+| `epics-and-stories.md` | epics-rules | Epics and Stories |
+
+### Detection Algorithm
+
+1. Extract the basename from the artifact path (e.g., `docs/planning-artifacts/prd.md` -> `prd.md`)
+2. Match basename against the mapping table above (case-insensitive)
+3. If a match is found, return the corresponding ruleset ID
+4. If no match is found, return `unknown` — skip document-specific rules, run factual claim verification only
+
+### Edge Cases and Fallback
+
+- **Nested directories**: Only the basename matters — `any/nested/path/prd.md` still matches prd-rules
+- **Custom paths**: Files with non-standard names (e.g., `custom-doc.md`) fall back to unknown/unrecognized type
+- **Case sensitivity**: Match is case-insensitive (`PRD.md` and `prd.md` both match prd-rules)
+- **Fallback**: When no ruleset matches, skip structural pass entirely and proceed to factual claims only
+<!-- END SECTION -->
+
+<!-- SECTION: prd-rules -->
+## PRD Validation Rules
+
+Structural quality checks for Product Requirements Documents. This ruleset absorbs and supersedes all checks from the standalone validate-prd workflow, enabling its deprecation.
+
+### Section Completeness Check
+
+Verify all required PRD sections exist: overview, personas, functional requirements, non-functional requirements, user journeys, data model, integrations, constraints, success criteria. Flag missing sections as CRITICAL.
+
+### FR/NFR Sequential Numbering
+
+Verify functional requirements use sequential numbering (FR-001, FR-002, ...). Verify non-functional requirements use sequential numbering (NFR-001, NFR-002, ...). Flag gaps or duplicates as WARNING.
+
+### Acceptance Criteria Quality
+
+For each requirement, verify acceptance criteria exist, are specific (not blank or generic), are testable, unambiguous, and measurable. Flag vague criteria (e.g., "fast", "easy to use" without quantification) as WARNING.
+
+### Priority Consistency
+
+Verify every requirement has a priority assigned (P0/P1/P2/P3 or Must/Should/Could/Won't). Check that priorities do not contradict across related requirements. Flag missing or contradictory priorities as WARNING.
+
+### Persona Cross-Reference
+
+Verify user personas referenced in requirements match personas defined in the personas section. Flag orphaned persona references (used but not defined) as WARNING.
+
+### Quality and Consistency
+
+Verify terminology is used consistently across sections. Cross-reference all sections for contradictions. Flag inconsistencies as WARNING.
+<!-- END SECTION -->
+
+<!-- SECTION: arch-rules -->
+## Architecture Validation Rules
+
+Structural quality checks for Architecture Documents.
+
+### Component Coverage
+
+Verify all system components mentioned in the system overview are covered in the detailed component descriptions. Check that the C4 diagrams (context, container, component) reference all declared components. Flag undocumented components as WARNING.
+
+### ADR Consistency
+
+Verify each ADR has: ID, Decision, Rationale, Status. Check ADR IDs are sequential (ADR-001, ADR-002, ...). Verify ADR status values are valid (Proposed, Active, Deprecated, Superseded). Check cross-references between ADRs and component descriptions are bidirectional. Flag inconsistencies as WARNING.
+
+### API Completeness
+
+Verify each declared API endpoint has: method, path, request/response schema, error codes. Check that APIs referenced in component descriptions exist in the API specification section. Flag incomplete API definitions as WARNING.
+<!-- END SECTION -->
+
+<!-- SECTION: ux-rules -->
+## UX Design Validation Rules
+
+Structural quality checks for UX Design Specifications.
+
+### Required Sections
+
+Verify presence of: design principles, user flows, wireframes/mockups, component library, accessibility requirements, responsive breakpoints. Flag missing sections as WARNING.
+
+### Flow Completeness
+
+Verify each user flow has: entry point, steps, decision points, exit conditions. Check that flows reference defined screens/components. Flag incomplete flows as WARNING.
+
+### Accessibility
+
+Verify WCAG compliance requirements are stated. Check color contrast ratios are specified. Verify keyboard navigation patterns are defined. Flag missing accessibility considerations as WARNING.
+<!-- END SECTION -->
+
+<!-- SECTION: test-plan-rules -->
+## Test Plan Validation Rules
+
+Structural quality checks for Test Plans.
+
+### Required Sections
+
+Verify presence of: test strategy, test scope, test types (unit, integration, e2e), entry/exit criteria, test environment, risk assessment. Flag missing sections as WARNING.
+
+### Coverage Mapping
+
+Verify each functional requirement has at least one mapped test case. Check that test case IDs are unique and sequential. Verify traceability links between requirements and test cases. Flag unmapped requirements as WARNING.
+
+### Environment Specification
+
+Verify test environments are fully specified (OS, browser, device matrix). Check that CI/CD integration is described. Flag underspecified environments as WARNING.
+<!-- END SECTION -->
+
+<!-- SECTION: epics-rules -->
+## Epics and Stories Validation Rules
+
+Structural quality checks for Epics and Stories documents.
+
+### Epic Structure
+
+Verify each epic has: ID, title, description, acceptance criteria, priority, stories list. Check epic IDs are sequential (E1, E2, ...). Flag incomplete epics as WARNING.
+
+### Story Structure
+
+Verify each story has: key, title, user story (As a/I want/So that), acceptance criteria, tasks, size estimate. Check story keys follow convention ({epic}-S{n}). Flag incomplete stories as WARNING.
+
+### Dependency Consistency
+
+Verify all `depends_on` and `blocks` references point to existing stories. Check for circular dependencies. Verify priority ordering respects dependency chains. Flag broken references as WARNING.
+<!-- END SECTION -->
+
+<!-- SECTION: two-pass-logic -->
+## Two-Pass Validation Logic
+
+### Pass Ordering
+
+Document-specific validation uses a two-pass approach:
+
+1. **Pass 1 — Structural Rules**: Run the document-specific ruleset matched by type detection. This checks internal document quality: section completeness, numbering, cross-references within the document itself. Produces structural findings.
+
+2. **Pass 2 — Factual Claims**: Run the standard factual claim extraction and filesystem verification (from validation-patterns skill). This checks external accuracy: file paths exist, counts match reality, references resolve. Produces factual findings.
+
+### Merge Strategy
+
+After both passes complete, merge findings into a single report:
+- Structural findings are tagged with source `[STRUCTURAL]`
+- Factual findings are tagged with source `[FACTUAL]`
+- Both use the same severity classification (CRITICAL/WARNING/INFO)
+- Findings are grouped by severity, then by source (structural first within each group)
+
+### Unknown Type Handling
+
+When the artifact type is unknown (no matching ruleset):
+- Skip Pass 1 entirely — no structural rules to apply
+- Run Pass 2 only — factual claim verification
+- Report notes: "No document-specific ruleset for this artifact type — factual verification only"
+<!-- END SECTION -->

package/_gaia/lifecycle/skills/memory-management-cross-agent.md

@@ -0,0 +1,218 @@
+---
+name: memory-management-cross-agent
+version: '1.0'
+applicable_agents: [all]
+description: 'Cross-agent memory extensions: cross-reference loading (ADR-015) and budget monitoring (ADR-014). Split from memory-management.md per 300-line skill limit.'
+---
+
+<!-- SECTION: cross-reference-loading -->
+## Cross-Reference Loading (ADR-015)
+
+Load another agent's sidecar files as read-only cross-references. All cross-ref loading is JIT (just-in-time) — never preloaded at session start.
+
+### Schema: `<memory-reads>` Tag
+
+Agent persona files declare cross-references using this XML schema inside the `<agent>` block:
+
+```xml
+<memory-reads>
+  <cross-ref agent="{agent-id}" file="{file-name}" mode="{recent|full|summary}" required="{true|false}" />
+</memory-reads>
+```
+
+**Attributes:**
+- `agent` (required) — the agent ID whose sidecar to read (e.g., "architect", "validator")
+- `file` (required) — the sidecar file to read (e.g., "decision-log", "ground-truth", "conversation-context")
+- `mode` (required) — loading mode: `recent`, `full`, or `summary`
+- `required` (optional, default: "true") — if "false", skip gracefully when the sidecar is absent
+
+### Read-Only Access: `load_cross_ref()`
+
+Cross-references are loaded through `load_cross_ref()`, which is a **read-only** path — separate from `load_own()` (the agent's own sidecar, which supports read/write).
+
+**Parameters:**
+- `sidecar_path` — absolute path to the **target** agent's sidecar directory (e.g., `_memory/architect-sidecar/`)
+- `file_name` — which file to read (e.g., "decision-log.md", "ground-truth.md")
+- `mode` — loading mode: `recent`, `full`, or `summary`
+- `budget_remaining` — remaining token budget for cross-references
+
+**Write-Guard:**
+Any attempt to write to a sidecar that is not the current agent's own sidecar MUST raise a **hard error** (not a warning). The write-guard blocks all write operations through `load_cross_ref()`. Only `load_own()` permits writes, and only to the agent's own sidecar directory.
+
+**Procedure:**
+1. Validate the target sidecar path is NOT the current agent's own sidecar (self-reference guard)
+2. Check budget_remaining BEFORE loading — if insufficient, apply progressive downgrade
+3. Read the target file from disk (read-only — no file creation, no modification)
+4. Apply mode filtering (see Loading Modes below)
+5. Calculate token estimate: character count / 4 (using `token_approximation` from `_memory/config.yaml`)
+6. Return filtered content as read-only data with token estimate for caller budget deduction
+
+### Loading Modes
+
+**`recent` mode** — Load entries from the last 2 sprints only:
+- Parse decision-log entries using ADR-016 format
+- Filter by Sprint field: keep entries where sprint matches current sprint or previous sprint
+- If sprint metadata is absent from entries, fall back to date-based filtering (last 30 days)
+- Approximate token cost: character count / 4
+
+**`full` mode** — Load the entire file content:
+- Read full file, respect budget cap
+- If file exceeds budget_remaining: truncate oldest entries first (keep most recent)
+- Approximate token cost: character count / 4
+
+**`summary` mode** — Load section headers only:
+- Parse the file for markdown headers (lines starting with `#`, `##`, `###`)
+- Stop at section boundaries — do not load body content
+- Minimal token cost
+
+### JIT Loading
+
+Cross-references are loaded **just-in-time** during workflow step execution — NOT at agent activation or session start. Loading is triggered only when a workflow step explicitly requires cross-agent context.
+
+**Trigger:** The workflow engine checks `<memory-reads>` declarations and loads cross-references only when the current step's execution context requires cross-agent data. No cross-references are preloaded eagerly.
+
+### Budget Enforcement
+
+**Pre-load budget check:** Before each cross-reference load, calculate:
+- Tokens already consumed by own sidecar
+- Tokens already consumed by previously loaded cross-references
+- Estimated tokens for the next cross-reference (based on mode and file size)
+
+**Per-agent `cross_ref_budget_cap`:** Some agents have a `cross_ref_budget_cap` in `_memory/config.yaml` (e.g., validator: 0.5). This caps cross-reference token consumption at that fraction of the agent's session budget. If loading would exceed the cap, halt loading and downgrade remaining cross-refs progressively.
+
+**Progressive downgrade chain:** When budget is insufficient for the requested mode:
+1. `full` → downgrade to `recent`
+2. `recent` → downgrade to `summary`
+3. `summary` → downgrade to `skip` (do not load, log warning)
+
+Log every downgrade as a warning in the session checkpoint:
+`"Cross-ref downgraded: {agent}/{file} from {original_mode} to {new_mode} — budget {used}/{total}"`
+
+**Val's 50% cross-ref budget cap:**
+Val (validator) has a `cross_ref_budget_cap` of 0.5 in `_memory/config.yaml`, meaning cross-references may consume at most 50% of Val's 300K session budget (= 150K tokens max for cross-refs). Val's load priority order: architect, pm, sm. If the 150K cap is hit mid-load, remaining cross-references are downgraded progressively.
+
+**Tier budget ceilings:**
+- Tier 1 agents: 300K session budget (own sidecar + cross-refs combined)
+- Tier 2 agents: 100K session budget (own sidecar + cross-refs combined)
+- Tier 3 agents: no explicit budget enforcement
+
+### Graceful Error Handling
+
+**Missing sidecar directory or file:**
+- If the target sidecar directory does not exist: log a warning ("Cross-ref skipped: {agent} sidecar directory not found"), skip this cross-reference, and continue workflow execution without error
+- If the target file within the sidecar does not exist: log a warning ("Cross-ref skipped: {agent}/{file} not found"), skip, continue
+
+**Empty sidecar directory:**
+- If the target sidecar directory exists but contains no files: return empty result gracefully with no error — matching the contract of the `session-load` section
+
+**Malformed or corrupt sidecar files:**
+- If the target file exists but cannot be parsed (malformed markdown, corrupt content, unparseable entries): log a warning ("Cross-ref skipped: {agent}/{file} is malformed"), skip this cross-reference, and continue
+- Never halt the workflow due to a cross-reference loading failure
+
+**Absent optional cross-references:**
+- If `<cross-ref required="false">` and the target is absent: skip silently (no warning)
+- If `<cross-ref required="true">` (default) and the target is absent: log warning but still continue
+
+**Agent not in cross-reference matrix:**
+- If the calling agent has no entry in `_memory/config.yaml` `cross_references`, return empty result with no error
+
+### Consistency Validation
+
+At session start, validate that agent persona `<memory-reads>` declarations are consistent with `_memory/config.yaml` cross_references matrix:
+
+1. Parse the agent's `<memory-reads>` block from the persona file
+2. Load the agent's entry from `_memory/config.yaml` → `cross_references.{agent_id}.reads_from`
+3. Compare: every entry in config.yaml should have a matching `<cross-ref>` in the persona file
+4. If mismatch found: produce a **warning** (not an error) — `_memory/config.yaml` is the authoritative source
+
+**Self-reference guard:**
+If an agent's `<memory-reads>` declares a `<cross-ref>` where the `agent` attribute matches the current agent's own ID, reject it with a validation error at session start. An agent must not reference its own sidecar as a cross-reference — own-sidecar access is through `load_own()`.
+
+### Checkpoint Provenance
+
+After loading cross-references, record in the session checkpoint:
+- Which cross-references were loaded (agent, file, mode)
+- File checksums (`shasum -a 256`) of each loaded cross-reference file
+- Any downgrades or skips that occurred
+- Total tokens consumed by cross-references
+
+This enables `/gaia-resume` to detect stale cross-references when resuming a session.
+<!-- END SECTION -->
+
+<!-- SECTION: budget-monitoring -->
+## Budget Monitoring (ADR-014)
+
+Shared utility for checking token budget usage against tier-defined thresholds. Used by `session-save` and other memory operations to determine when archival is needed.
+
+### Parameters
+
+- `sidecar_path` — absolute path to the agent's sidecar directory
+- `tier_budget` — session token budget for this agent's tier (from `_memory/config.yaml`). If null or absent, the agent is untiered.
+- `current_usage` — current token count (own sidecar files + cross-refs loaded in this session)
+- `projected_addition` — token count of content about to be written/loaded
+
+### Threshold Definitions (config-driven)
+
+All thresholds are read from `_memory/config.yaml` `archival` block at runtime. Never hardcode these values.
+
+- `budget_warn_at` — fraction of budget at which a warning is returned (e.g., 0.8 = 80%)
+- `budget_alert_at` — fraction of budget at which an alert is returned (e.g., 0.9 = 90%)
+- `budget_archive_at` — fraction of budget at which archival is triggered (e.g., 1.0 = 100%)
+- `token_approximation` — characters per token for size estimation (e.g., 4)
+- `archive_subdir` — subdirectory name within sidecar for archived entries (e.g., "archive")
+
+### Procedure
+
+1. Read `_memory/config.yaml` archival block to get threshold values
+2. Calculate `projected_total = current_usage + projected_addition`
+3. Calculate `usage_ratio = projected_total / tier_budget`
+4. Return threshold status:
+   - `usage_ratio < budget_warn_at` → status: `ok` (no action needed)
+   - `usage_ratio >= budget_warn_at AND < budget_alert_at` → status: `warn` ("approaching budget limit")
+   - `usage_ratio >= budget_alert_at AND < budget_archive_at` → status: `alert` ("near budget limit")
+   - `usage_ratio >= budget_archive_at` → status: `archive_needed` ("budget exceeded, archival required")
+
+### Archival Protocol
+
+When status is `archive_needed`:
+1. Identify the oldest N entries in `decision-log.md` that would free sufficient tokens
+2. Move those entries to `{sidecar_path}/{archive_subdir}/` (e.g., `_memory/architect-sidecar/archive/`)
+3. Create the archive subdirectory if it does not exist (`mkdir -p`)
+4. Use atomic read-modify-write pattern: read full file, remove archived entries, write full file back
+5. Re-check budget after archival — if still over budget, archive more entries (up to 3 iterations)
+6. Archive subdirectory is gitignored — archived entries are historical, not version-controlled
+
+### Token Estimation
+
+Token count is approximated using the `token_approximation` value from `_memory/config.yaml` (default: 4 chars per token). No tokenizer library is used — this aligns with ADR-005 (zero runtime dependencies).
+
+Formula: `tokens = character_count / token_approximation`
+
+### Running Session Total
+
+Track cumulative token usage across the session:
+- Own sidecar files loaded via `session-load`
+- Cross-references loaded via `cross-reference-loading`
+- New entries being written via `session-save`
+
+The combined total is checked against the tier budget ceiling.
+
+### Untiered Agent Handling
+
+If `tier_budget` is null, absent, or the agent has no tier assignment in `_memory/config.yaml` (applies to 9 untiered agents: analyst, data-engineer, performance, ux-designer, brainstorming-coach, design-thinking-coach, innovation-strategist, presentation-designer, problem-solver):
+- Skip all budget enforcement — no threshold checks, no archival trigger
+- Return status: `no_budget` with no error
+- This is a no-op: the caller proceeds without any budget constraint
+- Never raise an error for untiered agents
+
+### Return Value
+
+```yaml
+status: ok | warn | alert | archive_needed | no_budget
+usage_ratio: 0.75          # current usage as fraction of budget (null if no_budget)
+tokens_used: 225000        # current token count (null if no_budget)
+tokens_budget: 300000      # tier budget ceiling (null if no_budget)
+tokens_projected: 230000   # projected total after addition (null if no_budget)
+message: "Budget at 75% — no action needed"
+```
+<!-- END SECTION -->

package/_gaia/lifecycle/skills/memory-management.md

@@ -1,8 +1,8 @@
 ---
 name: memory-management
-version: '1.0'
+version: '1.1'
 applicable_agents: [all]
-description: 'Session load/save, decision formatting, stale detection, deduplication, context summarization'
+description: 'Core memory operations: session load/save, decision formatting, stale detection, deduplication, context summarization, budget monitoring. Cross-agent sections in memory-management-cross-agent.md.'
 ---
 
 <!-- SECTION: decision-formatting -->
@@ -96,13 +96,13 @@ Persist agent session data to sidecar files. Agent-agnostic — takes sidecar pa
    - Read entire file, replace in memory, write entire file back
 
 **Token budget enforcement (before write):**
-- Calculate projected file size after append (current size + new entries size)
-- Approximate tokens: character count / 4
-- If projected size exceeds `tier_budget`: warn with current/max budget and offer options:
-  - **Archive oldest entries** — move oldest N entries to `archive/` subdirectory to make room
-  - **Force save** — save anyway, exceeding the budget
+- Before writing, invoke the `budget-monitoring` section (from `memory-management-cross-agent.md`) to check projected usage against tier budget
+- Pass: sidecar_path, tier_budget, projected_size (current size + new entries size)
+- `budget-monitoring` returns the threshold status: ok, warn, alert, or archive_needed
+- If `archive_needed`: move oldest N entries to `{sidecar_path}/{archive_subdir}/` subdirectory to make room, then re-check
+- If user declines archival: force save anyway, exceeding the budget
 - Never silently truncate or block a save operation
-- Warn at 80% of budget ("approaching limit"), warn at 90% ("near limit"), trigger archival prompt at 100%
+- See `budget-monitoring` section in `memory-management-cross-agent.md` for threshold definitions and config source
 <!-- END SECTION -->
 
 <!-- SECTION: context-summarization -->
@@ -195,128 +195,38 @@ Detect and merge duplicate decision entries within a decision log.
 **Output:** List of duplicate pairs with recommended action (auto-archive or review).
 <!-- END SECTION -->
 
-<!-- SECTION: cross-ref-loading -->
-## Cross-Reference Loading (ADR-015)
+<!-- Cross-agent extensions (cross-reference-loading) are in memory-management-cross-agent.md -->
 
-Load another agent's sidecar files as read-only cross-references. All cross-ref loading is JIT (just-in-time) — never preloaded at session start.
+<!-- SECTION: budget-monitoring -->
+## Budget Monitoring
 
-### Schema: `<memory-reads>` Tag
+Calculate and report token budget usage per agent sidecar. Reusable by any workflow that needs budget status. All thresholds are config-driven — read from `_memory/config.yaml` archival block at runtime.
 
-Agent persona files declare cross-references using this XML schema inside the `<agent>` block:
+**Input:**
+- Agent sidecar file sizes (bytes) from filesystem scan
+- Tier budgets from `_memory/config.yaml`: `tiers.tier_1.session_budget` (300K), `tiers.tier_2.session_budget` (100K)
+- Per-agent ground truth budgets: `agents.{agent-id}.ground_truth_budget` (Tier 1 only)
 
-```xml
-<memory-reads>
-  <cross-ref agent="{agent-id}" file="{file-name}" mode="{recent|full|summary}" required="{true|false}" />
-  <!-- Additional cross-ref entries -->
-</memory-reads>
-```
-
-**Attributes:**
-- `agent` (required) — the agent ID whose sidecar to read (e.g., "architect", "validator")
-- `file` (required) — the sidecar file to read (e.g., "decision-log", "ground-truth", "conversation-context")
-- `mode` (required) — loading mode: `recent`, `full`, or `summary`
-- `required` (optional, default: "true") — if "false", skip gracefully when the sidecar is absent
-
-### Read-Only Access: `load_cross_ref()`
-
-Cross-references are loaded through `load_cross_ref()`, which is a **read-only** path — separate from `load_own()` (the agent's own sidecar, which supports read/write).
-
-**Parameters:**
-- `sidecar_path` — absolute path to the **target** agent's sidecar directory (e.g., `_memory/architect-sidecar/`)
-- `file_name` — which file to read (e.g., "decision-log.md", "ground-truth.md")
-- `mode` — loading mode: `recent`, `full`, or `summary`
-- `budget_remaining` — remaining token budget for cross-references
-
-**Write-Guard:**
-Any attempt to write to a sidecar that is not the current agent's own sidecar MUST raise a **hard error** (not a warning). The write-guard blocks all write operations through `load_cross_ref()`. Only `load_own()` permits writes, and only to the agent's own sidecar directory.
-
-**Procedure:**
-1. Validate the target sidecar path is NOT the current agent's own sidecar (self-reference guard — see Validation section below)
-2. Check budget_remaining BEFORE loading — if insufficient, apply progressive downgrade
-3. Read the target file from disk (read-only — no file creation, no modification)
-4. Apply mode filtering (see Loading Modes below)
-5. Return filtered content as read-only data
-
-### Loading Modes
-
-**`recent` mode** — Load entries from the last 2 sprints only:
-- Parse decision-log entries using ADR-016 format
-- Filter by Sprint field: keep entries where sprint matches current sprint or previous sprint
-- If sprint metadata is absent from entries, fall back to date-based filtering (last 30 days)
-- Approximate token cost: character count / 4
-
-**`full` mode** — Load the entire file content:
-- Read full file, respect budget cap
-- If file exceeds budget_remaining: truncate oldest entries first (keep most recent)
-- Approximate token cost: character count / 4
-
-**`summary` mode** — Load section headers only:
-- Parse the file for markdown headers (lines starting with `#`, `##`, `###`)
-- Stop at section boundaries — do not load body content
-- Minimal token cost
-
-### JIT Loading
-
-Cross-references are loaded **just-in-time** during workflow step execution — NOT at agent activation or session start. Loading is triggered only when a workflow step explicitly requires cross-agent context.
-
-**Trigger:** The workflow engine checks `<memory-reads>` declarations and loads cross-references only when the current step's execution context requires cross-agent data. No cross-references are preloaded eagerly.
-
-### Budget Enforcement
-
-**Pre-load budget check:** Before each cross-reference load, calculate:
-- Tokens already consumed by own sidecar
-- Tokens already consumed by previously loaded cross-references
-- Estimated tokens for the next cross-reference (based on mode and file size)
-
-**Progressive downgrade chain:** When budget is insufficient for the requested mode:
-1. `full` → downgrade to `recent`
-2. `recent` → downgrade to `summary`
-3. `summary` → downgrade to `skip` (do not load, log warning)
-
-Log every downgrade as a warning in the session checkpoint:
-`"Cross-ref downgraded: {agent}/{file} from {original_mode} to {new_mode} — budget {used}/{total}"`
-
-**Val's 50% cross-ref budget cap:**
-Val (validator) has a `cross_ref_budget_cap` of 0.5 in `_memory/config.yaml`, meaning cross-references may consume at most 50% of Val's 300K session budget (= 150K tokens max for cross-refs). Val's load priority order: architect → pm → sm. If the 150K cap is hit mid-load, remaining cross-references are downgraded progressively.
-
-**Tier budget ceilings:**
-- Tier 1 agents: 300K session budget (own sidecar + cross-refs combined)
-- Tier 2 agents: 100K session budget (own sidecar + cross-refs combined)
-- Tier 3 agents: no explicit budget enforcement
-
-### Graceful Error Handling
-
-**Missing sidecar directory or file:**
-- If the target sidecar directory does not exist: log a warning ("Cross-ref skipped: {agent} sidecar directory not found"), skip this cross-reference, and continue workflow execution
-- If the target file within the sidecar does not exist: log a warning ("Cross-ref skipped: {agent}/{file} not found"), skip, continue
-
-**Malformed or corrupt sidecar files:**
-- If the target file exists but cannot be parsed (malformed markdown, corrupt content, unparseable entries): log a warning ("Cross-ref skipped: {agent}/{file} is malformed"), skip this cross-reference, and continue
-- Never halt the workflow due to a cross-reference loading failure
-
-**Absent optional cross-references:**
-- If `<cross-ref required="false">` and the target is absent: skip silently (no warning)
-- If `<cross-ref required="true">` (default) and the target is absent: log warning but still continue
-
-### Consistency Validation
+**Token calculation:**
+- Approximate tokens = file size in bytes / 4 (chars-per-token convention)
+- Sum across all sidecar files per agent (decision-log.md + conversation-context.md + ground-truth.md)
 
-At session start, validate that agent persona `<memory-reads>` declarations are consistent with `_memory/config.yaml` cross_references matrix:
+**Threshold classification (config-driven from `_memory/config.yaml`):**
+- `budget_warn_at` — **warning:** at or above this fraction of budget (default: 0.8 = 80%)
+- `budget_alert_at` — **critical:** at or above this fraction (default: 0.9 = 90%)
+- `budget_archive_at` — **over-budget:** at or above this fraction (default: 1.0 = 100%) — triggers archival
 
-1. Parse the agent's `<memory-reads>` block from the persona file
-2. Load the agent's entry from `_memory/config.yaml` → `cross_references.{agent_id}.reads_from`
-3. Compare: every entry in config.yaml should have a matching `<cross-ref>` in the persona file
-4. If mismatch found: produce a **warning** (not an error) — `_memory/config.yaml` is the authoritative source. The persona file declaration should mirror it.
+When usage reaches `budget_archive_at`, archival is triggered: oldest entries are moved to `{sidecar_path}/archive/` to free budget.
 
-**Self-reference guard:**
-If an agent's `<memory-reads>` declares a `<cross-ref>` where the `agent` attribute matches the current agent's own ID, reject it with a validation error at session start. An agent must not reference its own sidecar as a cross-reference — own-sidecar access is through `load_own()`.
+**Tier handling:**
+- Tier 1: report session budget usage and ground truth budget usage separately
+- Tier 2: report session budget usage only (no ground truth file)
+- Tier 3 / untiered: skip all budget enforcement — no threshold checks, no archival trigger. Return no-op status with no error. Untiered agents proceed without any budget constraint.
 
-### Checkpoint Provenance
+**Output format (Token Budget Table):**
 
-After loading cross-references, record in the session checkpoint:
-- Which cross-references were loaded (agent, file, mode)
-- File checksums (`shasum -a 256`) of each loaded cross-reference file
-- Any downgrades or skips that occurred
-- Total tokens consumed by cross-references
+| Agent | Tier | Files Scanned | Token Usage | Session Budget | GT Budget | % Used | Status |
+|-------|------|---------------|-------------|----------------|-----------|--------|--------|
 
-This enables `/gaia-resume` to detect stale cross-references when resuming a session.
+For Tier 3 and untiered agents, budget columns show "no budget enforced" with actual token count.
 <!-- END SECTION -->

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

@@ -11,6 +11,7 @@ size: "{S/M/L/XL}"
 points: "{story_points}"
 risk: "{high/medium/low}"
 sprint_id: null
+priority_flag: null
 depends_on: []
 blocks: []
 traces_to: []

package/_gaia/lifecycle/workflows/1-analysis/create-product-brief/workflow.yaml

@@ -7,6 +7,7 @@ config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/1-analysis/create-product-brief"
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
+template: "{project-root}/_gaia/lifecycle/templates/product-brief-template.md"
 input_file_patterns:
   brainstorm:
     whole: "{planning_artifacts}/project-brainstorm.md"

package/_gaia/lifecycle/workflows/2-planning/create-prd/instructions.xml

@@ -63,7 +63,9 @@
   </template-output>
 </step>
 <step n="12" title="Adversarial Review">
-  <action>Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/prd.md. Target label: prd. Follow the task instructions EXACTLY." This is required — findings will be incorporated back into the PRD.</action>
+  <action>Read {project-root}/_gaia/_config/adversarial-triggers.yaml to evaluate trigger rules. Determine the current change_type: if this workflow was invoked with a change_type context (e.g., from add-feature triage), use that value. If no context is available (standalone PRD creation), default to "feature".</action>
+  <action>Look up the trigger rule for change_type + artifact "prd". If adversarial is false for this combination: skip the adversarial review — log "Adversarial review skipped: change_type={change_type} does not trigger for PRD per adversarial-triggers.yaml" and proceed to next step. Add a "## Review Findings Incorporated" section with "Adversarial review not triggered — change type: {change_type}".</action>
+  <action>If adversarial is true: Spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-adversarial.xml. Read its entire contents. Target: {planning_artifacts}/prd.md. Target label: prd. Follow the task instructions EXACTLY." This is required — findings will be incorporated back into the PRD.</action>
   <action>When subagent returns: verify adversarial-review-prd-{date}.md exists in {planning_artifacts}/</action>
 </step>
 <step n="13" title="Incorporate Adversarial Findings">
@@ -75,6 +77,6 @@
   </template-output>
 </step>
 <next-step source="lifecycle-sequence.yaml">
-  <primary command="/gaia-validate-prd">Validate the PRD against quality standards before proceeding</primary>
+  <primary command="/gaia-create-ux">Create UX design specifications for the validated PRD</primary>
 </next-step>
 </workflow>

package/_gaia/lifecycle/workflows/2-planning/create-prd/workflow.yaml

@@ -2,6 +2,7 @@ name: create-prd
 description: 'Create a Product Requirements Document from scratch'
 module: lifecycle
 agent: pm
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/create-prd.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/2-planning/create-prd"

package/_gaia/lifecycle/workflows/2-planning/create-ux-design/workflow.yaml

@@ -2,6 +2,7 @@ name: create-ux-design
 description: 'Plan UX patterns and design specifications'
 module: lifecycle
 agent: ux-designer
+val_validate_output: true
 config_resolved: "{installed_path}/.resolved/create-ux-design.yaml"
 config_source: "{project-root}/_gaia/lifecycle/config.yaml"
 installed_path: "{project-root}/_gaia/lifecycle/workflows/2-planning/create-ux-design"