gaia-framework 1.60.0 → 1.62.0

package/CLAUDE.md

@@ -1,5 +1,5 @@
 
-# GAIA Framework v1.60.0
+# GAIA Framework v1.62.0
 
 This project uses the **GAIA** (Generative Agile Intelligence Architecture) framework — an AI agent framework for Claude Code that orchestrates software product development through 26 specialized agents, 65 workflows, and 8 shared skills.
 

package/README.md

@@ -460,7 +460,7 @@ The single source of truth is `_gaia/_config/global.yaml`:
 
 ```yaml
 framework_name: "GAIA"
-framework_version: "1.60.0"
+framework_version: "1.62.0"
 user_name: "your-name"
 project_name: "your-project"
 ```

package/_gaia/_config/global.yaml

@@ -3,7 +3,7 @@
 # After modifying this file, run /gaia-build-configs to regenerate resolved configs.
 
 framework_name: "GAIA"
-framework_version: "1.60.0"
+framework_version: "1.62.0"
 
 # User settings
 user_name: "jlouage"

package/_gaia/_config/manifest.yaml

@@ -3,11 +3,11 @@
 
 modules:
   - name: core
-    version: "1.13.0"
+    version: "1.12.0"
     path: "_gaia/core"
     type: built-in
   - name: lifecycle
-    version: "1.38.0"
+    version: "1.39.0"
     path: "_gaia/lifecycle"
     type: built-in
   - name: dev

package/_gaia/core/config.yaml

@@ -2,7 +2,7 @@
 inherits: "{project-root}/_gaia/_config/global.yaml"
 
 module_name: "core"
-module_version: "1.13.0"
+module_version: "1.12.0"
 
 engine_path: "{project-root}/_gaia/core/engine/workflow.xml"
 tasks_path: "{project-root}/_gaia/core/tasks"

package/_gaia/core/engine/workflow.xml

@@ -68,17 +68,8 @@ execution modes (normal/yolo/planning), checkpoints, and quality gates.
     <action if="agent is 'dev-*' (wildcard)">Check if workflow.yaml declares agent_auto_detect: true. If true, execute the agent_auto_detect_strategy from workflow.yaml to determine the stack. If auto-detection succeeds, resolve to {project-root}/_gaia/dev/agents/{detected_stack}-dev.md and inform user: "Auto-detected developer: {agent_name} based on {detection_source}." If auto-detection fails or agent_auto_detect is false/absent: ask user which stack developer to use (typescript, angular, flutter, java, python, mobile, go), then resolve to {project-root}/_gaia/dev/agents/{stack}-dev.md</action>
     <action if="agent file resolved">Read the agent persona file — adopt its persona, name, communication style, rules, and domain knowledge for the duration of this workflow</action>
     <action if="agent file resolved">Do NOT execute the agent's activation protocol, greeting, or menu — the workflow engine controls step execution</action>
+    <action if="agent file resolved">Do NOT load the agent's memory sidecar — the workflow engine manages its own checkpoints</action>
     <action if="agent file resolved">Check for {project-root}/_gaia/_config/agents/{agent-id}.customize.yaml. If found, load and merge overrides (persona_overrides, menu_additions, menu_removals, skill_additions, rule_additions, skill_overrides, skill_section_overrides). For dev agents, also check all-dev.customize.yaml and merge (agent-specific takes precedence over all-dev).</action>
-
-    <!-- Memory Load Protocol (E9-S7) — Load agent memory sidecar files after persona, before instructions -->
-    <action if="agent file resolved">Read {project-root}/_memory/config.yaml to resolve agent tier and sidecar path. If the file does not exist, log "Memory config not found — skipping memory loading." and skip all remaining memory load actions in this step.</action>
-    <action if="agent file resolved">Resolve the agent's tier classification: look up the resolved agent ID in _memory/config.yaml tier lists — check tiers.tier_1.agents, tiers.tier_2.agents, and tiers.tier_3.agents in that order. If the agent ID is not found in any tier list (untiered), treat as Tier 3 by default — load decision-log.md only if it exists, with no budget enforcement.</action>
-    <action if="agent file resolved">Resolve sidecar path: read agents.{agent-id}.sidecar from _memory/config.yaml, construct absolute path as {project-root}/_memory/{sidecar_value}/. If the agent entry is not found in the agents section, construct path as {project-root}/_memory/{agent-id}-sidecar/.</action>
-    <action if="agent file resolved">Check if the sidecar directory exists. If the directory does not exist or is empty, skip all file loading silently — no error, no warning. Proceed to Step 4.</action>
-    <action if="agent file resolved and tier == 1">Load canonical sidecar files (silently skip any that do not exist): ground-truth.md, decision-log.md, conversation-context.md (3 files). These provide the agent's persistent ground truth, decision history, and recent conversation context.</action>
-    <action if="agent file resolved and tier == 2">Load canonical sidecar files (silently skip any that do not exist): decision-log.md, conversation-context.md (2 files). Tier 2 agents do not have ground-truth.md.</action>
-    <action if="agent file resolved and tier == 3 or untiered">Load canonical sidecar file (silently skip if it does not exist): decision-log.md (1 file). Tier 3 and untiered agents receive minimal memory context.</action>
-    <action if="agent file resolved and tier in [1, 2]">Estimate token budget usage: sum the byte lengths of all loaded sidecar files, divide by the token_approximation value (default: 4 chars per token, from _memory/config.yaml archival.token_approximation). Compare against the agent's session_budget from the tier definition in _memory/config.yaml. If usage reaches or exceeds the budget_warn_at threshold (0.8 / 80% from _memory/config.yaml archival.budget_warn_at): display warning "Memory budget at {N}% for {agent_name} — {used}K of {budget}K tokens." For Tier 3 and untiered agents (session_budget: null), skip the token budget check entirely.</action>
   </step>
 
   <step n="4" title="Load Instructions">

package/_gaia/lifecycle/config.yaml

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

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

@@ -1,8 +1,8 @@
 ---
 name: memory-management
-version: '1.1'
+version: '1.0'
 applicable_agents: [all]
-description: 'Core memory operations: session load/save, decision formatting, stale detection, deduplication, context summarization. Cross-agent sections in memory-management-cross-agent.md.'
+description: 'Session load/save, decision formatting, stale detection, deduplication, context summarization'
 ---
 
 <!-- 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):**
-- 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
+- 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
 - Never silently truncate or block a save operation
-- See `budget-monitoring` section in `memory-management-cross-agent.md` for threshold definitions and config source
+- Warn at 80% of budget ("approaching limit"), warn at 90% ("near limit"), trigger archival prompt at 100%
 <!-- END SECTION -->
 
 <!-- SECTION: context-summarization -->
@@ -195,4 +195,128 @@ Detect and merge duplicate decision entries within a decision log.
 **Output:** List of duplicate pairs with recommended action (auto-archive or review).
 <!-- END SECTION -->
 
-<!-- Cross-agent extensions (cross-reference-loading, budget-monitoring) are in memory-management-cross-agent.md -->
+<!-- SECTION: cross-ref-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}" />
+  <!-- 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
+
+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. The persona file declaration should mirror it.
+
+**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 -->

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

@@ -82,7 +82,7 @@
   /gaia-review-api (optional, if APIs) → /gaia-adversarial → /gaia-test-design → /gaia-test-framework (optional) → /gaia-create-epics → /gaia-threat-model → /gaia-infra-design → /gaia-trace → /gaia-ci-setup → /gaia-readiness-check</action>
 </step>
 
-<step n="7" title="Bootstrap Val Ground Truth" optional="true">
+<step n="7" title="Bootstrap Agent Ground Truth" optional="true">
   <action>Check if Val is installed: verify {project-root}/_gaia/lifecycle/agents/validator.md exists AND {memory_path}/validator-sidecar/ directory exists</action>
   <check if="validator.md not found OR validator-sidecar/ not found">Skip Step 7 silently — Val is not installed. Brownfield onboarding continues without ground truth bootstrap.</check>
 
@@ -102,6 +102,74 @@
 
   <action>Write extracted project facts to {memory_path}/validator-sidecar/ground-truth.md. If ground-truth.md already exists with content: merge new facts with existing entries — add new facts, update changed facts, flag removed facts — never destructive overwrite. Follow merge semantics from ground-truth-management conflict-resolution section. If ground-truth.md is empty or new: write all extracted facts as initial seed entries with verification count = 1.</action>
   <action>Report: "Seeded {N} ground-truth entries from brownfield artifacts + filesystem scan"</action>
+
+  <!-- Step 7d/7e/7f: Tier 1 Agent Ground Truth Bootstrap (E9-S12) -->
+
+  <ask>Bootstrap Tier 1 agent ground truth (Theo, Derek, Nate)? [y/n]</ask>
+
+  <action>JIT load ground-truth-management skill sections from {project-root}/_gaia/lifecycle/skills/ground-truth-management.md: entry-structure, conflict-resolution, brownfield-extraction. All ground-truth entries must follow the canonical entry format from the entry-structure section. When the same fact appears in multiple source documents with conflicting values (e.g., different version numbers), annotate the entry with "conflicting sources: {source1} says X, {source2} says Y" and use the higher-precedence source (brownfield-assessment.md > project-documentation.md for tech stack facts).</action>
+
+  <!-- Step 7d: Theo (Architect) ground truth extraction (AC1) -->
+  <action>Step 7d — Theo ground truth extraction.
+    Read {planning_artifacts}/architecture.md and extract:
+    — Tech stack (languages, frameworks, runtime versions) → variable-inventory entries
+    — ADRs (architecture decision records — ID, title, status, rationale) → structural-pattern entries
+    — Component inventory (modules, packages, services) → file-inventory entries
+    — Dependency map (internal and external dependencies) → cross-reference entries
+
+    If {planning_artifacts}/architecture.md does not exist: fall back to {planning_artifacts}/brownfield-assessment.md for Theo. Extract tech stack, file counts, and project structure from the brownfield assessment instead.
+
+    Token budget guard: Theo has a 150K token budget (150,000 tokens). Estimate extraction size (characters / 4). If estimated tokens exceed 60% threshold (90,000 tokens), trim to highest-signal entries — prioritize ADRs and tech stack over detailed file inventories.
+
+    Write extracted entries to {memory_path}/architect-sidecar/ground-truth.md.
+    If the {memory_path}/architect-sidecar/ directory does not exist, create it along with a new ground-truth.md file with standard headers.
+    If ground-truth.md already exists with content: follow merge semantics from the conflict-resolution section — add new entries, update changed entries, preserve existing entries. Never perform a destructive overwrite.</action>
+
+  <!-- Step 7e: Derek (Product Manager) ground truth extraction (AC2) -->
+  <action>Step 7e — Derek ground truth extraction.
+    Read {planning_artifacts}/prd.md and extract:
+    — Functional requirements (feature list, requirement IDs) → structural-pattern entries
+    — User stories and acceptance criteria summaries → cross-reference entries
+
+    If {planning_artifacts}/prd.md does not exist: fall back to {planning_artifacts}/prd-brownfield-gaps.md as the alternate PRD path for Derek.
+
+    Read {planning_artifacts}/epics-and-stories.md and extract for Derek:
+    — Epic overview (epic IDs, titles, story counts) → file-inventory entries
+    — Story-to-epic mappings → cross-reference entries
+
+    Read {test_artifacts}/nfr-assessment.md (if present) and extract for Derek:
+    — Quality baselines (performance targets, security posture, test coverage) → variable-inventory entries
+    If {test_artifacts}/nfr-assessment.md does not exist: log warning "nfr-assessment.md not found in test_artifacts — skipping quality baselines for Derek" and continue without error.
+
+    Token budget guard: Derek has a 100K token budget (100,000 tokens). Estimate extraction size (characters / 4). If estimated tokens exceed 60% threshold (60,000 tokens), trim to highest-signal entries — prioritize functional requirements and epic summaries over detailed story mappings.
+
+    Write extracted entries to {memory_path}/pm-sidecar/ground-truth.md.
+    If the {memory_path}/pm-sidecar/ directory does not exist, create it along with a new ground-truth.md file with standard headers.
+    If ground-truth.md already exists with content: follow merge semantics from the conflict-resolution section — add new entries, update changed entries, preserve existing entries. Never perform a destructive overwrite.</action>
+
+  <!-- Step 7f: Nate (Scrum Master) ground truth extraction (AC3) -->
+  <action>Step 7f — Nate ground truth extraction.
+    Read {implementation_artifacts}/sprint-status.yaml (if it exists) and extract for Nate:
+    — Current sprint ID, story count, points total → variable-inventory entries
+    — Story status distribution → structural-pattern entries
+
+    Read {memory_path}/sm-sidecar/velocity-data.md (if it exists) and extract for Nate:
+    — Velocity history (sprint-over-sprint) → variable-inventory entries
+    — Capacity data → variable-inventory entries
+
+    If neither {implementation_artifacts}/sprint-status.yaml nor {memory_path}/sm-sidecar/velocity-data.md exists: complete this step gracefully with a log message "insufficient sprint data, velocity unavailable" and write ground-truth.md omitting velocity entries. Do not raise an error.
+
+    Token budget guard: Nate has a 100K token budget (100,000 tokens). Estimate extraction size (characters / 4). If estimated tokens exceed 60% threshold (60,000 tokens), trim to highest-signal entries — prioritize current sprint status over historical velocity data.
+
+    Write extracted entries to {memory_path}/sm-sidecar/ground-truth.md.
+    If the {memory_path}/sm-sidecar/ directory does not exist, create it along with a new ground-truth.md file with standard headers.
+    If ground-truth.md already exists with content: follow merge semantics from the conflict-resolution section — add new entries, update changed entries, preserve existing entries. Never perform a destructive overwrite.</action>
+
+  <!-- Summary report (AC6) -->
+  <action>After all Tier 1 extractions complete, output a summary report:
+    "Seeded {N} entries for Theo, {M} entries for Derek, {K} entries for Nate"
+    If sprint data was absent for Nate, append a note: "(sprint data absent — velocity entries omitted)"
+    Include token budget status for each agent (GREEN/YELLOW/RED).</action>
 </step>
 
 <next-step command="/gaia-review-api">

package/gaia-install.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 # Installs, updates, validates, and reports on GAIA installations.
 # ─────────────────────────────────────────────────────────────────────────────
 
-readonly VERSION="1.60.0"
+readonly VERSION="1.62.0"
 readonly GITHUB_REPO="https://github.com/jlouage/Gaia-framework.git"
 readonly MANIFEST_REL="_gaia/_config/manifest.yaml"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-framework",
-  "version": "1.60.0",
+  "version": "1.62.0",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"

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

@@ -1,218 +0,0 @@
----
-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 -->