gaia-framework 1.61.0 → 1.63.0

package/CLAUDE.md

@@ -1,5 +1,5 @@
 
-# GAIA Framework v1.61.0
+# GAIA Framework v1.63.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.61.0"
+framework_version: "1.63.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.61.0"
+framework_version: "1.63.0"
 
 # User settings
 user_name: "jlouage"

package/_gaia/_config/manifest.yaml

@@ -7,7 +7,7 @@ modules:
     path: "_gaia/core"
     type: built-in
   - name: lifecycle
-    version: "1.38.0"
+    version: "1.40.0"
     path: "_gaia/lifecycle"
     type: built-in
   - name: dev

package/_gaia/_config/skill-manifest.csv

@@ -9,4 +9,4 @@ name,displayName,description,path,applicable_agents
 "security-basics","Security Basics","OWASP Top 10, input validation, secrets, CORS/CSRF","_gaia/dev/skills/security-basics.md","all-dev,architect,security,devops"
 "validation-patterns","Validation Patterns","Claim extraction, filesystem verification, cross-reference, severity classification, findings formatting","_gaia/lifecycle/skills/validation-patterns.md","validator"
 "ground-truth-management","Ground Truth Management","Entry structure, incremental/full refresh, conflict resolution, archival, token budget, brownfield extraction","_gaia/lifecycle/skills/ground-truth-management.md","validator"
-"memory-management","Memory Management","Session load/save, decision formatting, stale detection, deduplication, context summarization","_gaia/lifecycle/skills/memory-management.md","all"
+"memory-management","Memory Management","Session load/save, decision formatting, stale detection, deduplication, context summarization, cross-ref loading, budget-monitoring","_gaia/lifecycle/skills/memory-management.md","all"

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.40.0"
 
 planning_artifacts: "{project-root}/docs/planning-artifacts"
 implementation_artifacts: "{project-root}/docs/implementation-artifacts"

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

@@ -2,7 +2,7 @@
 name: memory-management
 version: '1.0'
 applicable_agents: [all]
-description: 'Session load/save, decision formatting, stale detection, deduplication, context summarization'
+description: 'Session load/save, decision formatting, stale detection, deduplication, context summarization, cross-ref loading, budget monitoring'
 ---
 
 <!-- SECTION: decision-formatting -->
@@ -320,3 +320,36 @@ After loading cross-references, record in the session checkpoint:
 
 This enables `/gaia-resume` to detect stale cross-references when resuming a session.
 <!-- END SECTION -->
+
+<!-- SECTION: budget-monitoring -->
+## Budget Monitoring
+
+Calculate and report token budget usage per agent sidecar. Reusable by any workflow that needs budget status.
+
+**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)
+
+**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)
+
+**Threshold classification:**
+- **OK:** below 80% of budget
+- **warning:** at or above 80%, below 90%
+- **critical:** at or above 90%, below 100%
+- **over-budget:** at or above 100% — triggers archival recommendation
+
+**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: report actual token count with "no budget enforced"
+
+**Output format (Token Budget Table):**
+
+| Agent | Tier | Files Scanned | Token Usage | Session Budget | GT Budget | % Used | Status |
+|-------|------|---------------|-------------|----------------|-----------|--------|--------|
+
+For Tier 3 and untiered agents, budget columns show "no budget enforced" with actual token count.
+<!-- END SECTION -->

package/_gaia/lifecycle/workflows/4-implementation/val-refresh-ground-truth/checklist.md

@@ -42,21 +42,6 @@ validation-target: 'Ground truth refresh workflow'
 - [ ] ground-truth-management sections loaded JIT
 - [ ] Sections: full-refresh, incremental-refresh, entry-structure, conflict-resolution, token-budget
 
-## --agent Parameter (E9-S11)
-- [ ] workflow.yaml declares agent parameter with flag --agent and allowed values [val, theo, derek, nate, all]
-- [ ] Default agent is val (backward compatible — no --agent behaves identically to pre-E9-S11)
-- [ ] Invalid agent names produce clear error with valid values list
-- [ ] Per-agent sidecar initialization creates missing ground-truth.md for any Tier 1 agent
-- [ ] Theo inventory scans filesystem structure + architecture.md
-- [ ] Derek inventory scans prd.md + epics-and-stories.md + sprint-status.yaml
-- [ ] Nate inventory scans sprint-status.yaml + story files in implementation-artifacts/
-- [ ] Val inventory uses existing 6-target scan (unchanged)
-- [ ] Decision log entries route to target agent's own decision-log.md
-- [ ] Per-agent ground_truth_budget enforced (Val 200K, Theo 150K, Derek 100K, Nate 100K)
-- [ ] --agent all runs val → theo → derek → nate sequentially
-- [ ] --agent all continues on per-agent failure and reports which succeeded/failed
-- [ ] --agent all presents combined summary with per-agent status
-
 ## Integration
 - [ ] Manifest entry exists in workflow-manifest.csv
 - [ ] Works identically standalone or as sub-step

package/_gaia/lifecycle/workflows/4-implementation/val-refresh-ground-truth/instructions.xml

@@ -7,166 +7,95 @@
   <mandate>Behavior must be identical whether called standalone or as sub-step from another workflow</mandate>
 </critical>
 
-<step n="1" title="Resolve Agent Target">
-  <action>Parse $ARGUMENTS for --agent value. If --agent is absent, default to "val" for backward compatibility.</action>
-  <action>Validate agent name against allowed values: val, theo, derek, nate, all.
-    If the agent name is not in the allowed values list: HALT with error:
-    "Unknown agent '{agent_name}'. Valid values: val, theo, derek, nate, all."</action>
-  <action>Resolve target sidecar path and inventory source files based on agent:
-    - val: sidecar = {memory_path}/validator-sidecar/, inventory = 6-target scan (existing)
-    - theo: sidecar = {memory_path}/architect-sidecar/, inventory = filesystem structure + {planning_artifacts}/architecture.md
-    - derek: sidecar = {memory_path}/pm-sidecar/, inventory = {planning_artifacts}/prd.md + {planning_artifacts}/epics-and-stories.md + {implementation_artifacts}/sprint-status.yaml
-    - nate: sidecar = {memory_path}/sm-sidecar/, inventory = {implementation_artifacts}/sprint-status.yaml + story files in {implementation_artifacts}/
-    - all: run sequentially for val, theo, derek, nate (see Step 13)</action>
-  <action if="agent == all">Set agent_queue = [val, theo, derek, nate]. Proceed to Step 13 for orchestration.</action>
+<step n="1" title="Initialize Validator Sidecar">
+  <action>Check if {memory_path}/validator-sidecar/ directory exists</action>
+  <action if="directory missing">Create {memory_path}/validator-sidecar/ directory</action>
+  <action if="ground-truth.md missing">Create {memory_path}/validator-sidecar/ground-truth.md with empty header containing last-refresh timestamp set to "never"</action>
+  <action if="decision-log.md missing">Create {memory_path}/validator-sidecar/decision-log.md with header: "# Val Decision Log" and empty entries</action>
+  <action if="conversation-context.md missing">Create {memory_path}/validator-sidecar/conversation-context.md with header: "# Val Conversation Context" and empty rolling state</action>
 </step>
 
-<step n="2" title="Initialize Agent Sidecar">
-  <action>Check if the resolved target sidecar directory exists (e.g., {memory_path}/validator-sidecar/ for val, {memory_path}/architect-sidecar/ for theo, {memory_path}/pm-sidecar/ for derek, {memory_path}/sm-sidecar/ for nate)</action>
-  <action if="directory missing">Create the resolved sidecar directory</action>
-  <action if="ground-truth.md missing">Create ground-truth.md in the resolved sidecar directory with empty header containing last-refresh timestamp set to "never"</action>
-  <action if="decision-log.md missing">Create decision-log.md in the resolved sidecar directory with header: "# {agent_display_name} Decision Log" and empty entries</action>
-  <action if="conversation-context.md missing">Create conversation-context.md in the resolved sidecar directory with header: "# {agent_display_name} Conversation Context" and empty rolling state</action>
-</step>
-
-<step n="3" title="Determine Refresh Mode">
+<step n="2" title="Determine Refresh Mode">
   <action>Check if --incremental flag was passed</action>
   <action if="incremental">Set mode to incremental — only scan files modified since last-refresh timestamp from ground-truth.md header</action>
   <action if="not incremental">Set mode to full — scan all targets completely. Full refresh catches deletions and renames that incremental would miss.</action>
 </step>
 
-<step n="4" title="Load Entry Structure">
+<step n="3" title="Load Entry Structure">
   <action>Load ground-truth-management skill section: entry-structure (JIT)</action>
   <action>Use entry-structure format for all ground truth entries written in subsequent steps</action>
 </step>
 
-<step n="5" title="Parse Previous State">
-  <action>Read existing ground-truth.md from the resolved target sidecar directory</action>
+<step n="4" title="Parse Previous State">
+  <action>Read existing {memory_path}/validator-sidecar/ground-truth.md</action>
   <action>Extract last-refresh timestamp from header</action>
   <action>Parse all existing entries into a lookup map keyed by file path for diff comparison</action>
   <action if="incremental mode">Filter scan targets to only files modified after last-refresh timestamp</action>
 </step>
 
-<step n="6" title="Scan Inventory Targets">
+<step n="5" title="Scan Inventory Targets">
   <action>Load ground-truth-management skill section based on mode: full-refresh or incremental-refresh (JIT)</action>
+  <action>Scan the following 6 inventory targets, showing section-by-section progress to the user after each target completes.</action>
 
-  <action if="agent == val">
-    Scan the following 6 inventory targets (existing Val scan — unchanged for backward compatibility), showing section-by-section progress to the user after each target completes.
-
-    <action title="Exclusion list">
-      ALWAYS exclude these directories and files from scanning — they are framework internals, not project code:
-      _gaia/, .claude/, bin/, _memory/, node_modules/, .git/, build/, dist/, .DS_Store, *.lock
-    </action>
-
-    <action title="Target 1: Project Source Files">
-      Scan {project-path}/**/* (excluding the exclusion list above)
-      Extract: file inventory, directory structure, languages used, entry points
-      Report progress: "Scanning project source files... found N files across N directories."
-    </action>
-
-    <action title="Target 2: Project Config Files">
-      Scan {project-path}/*.{json,yaml,yml,toml,xml,env.example} (root-level config files)
-      Extract: config keys, settings, dependency declarations
-      Report progress: "Scanning project config files... found N config files."
-    </action>
-
-    <action title="Target 3: Project Package Manifests">
-      Scan {project-path}/**/package.json, pubspec.yaml, pom.xml, build.gradle, requirements.txt, Cargo.toml, go.mod, Gemfile, *.csproj (whichever exist)
-      Extract: dependencies, versions, scripts, build targets
-      Report progress: "Scanning package manifests... found N manifests."
-    </action>
-
-    <action title="Target 4: Planning Artifacts">
-      Scan {project-root}/docs/planning-artifacts/*.md
-      Extract: artifact name, type, date
-      Report progress: "Scanning planning artifacts... found N artifacts."
-    </action>
-
-    <action title="Target 5: Implementation Artifacts">
-      Scan {project-root}/docs/implementation-artifacts/*.md
-      Extract: artifact name, type, story key if applicable
-      Report progress: "Scanning implementation artifacts... found N artifacts."
-    </action>
-
-    <action title="Target 6: Test Artifacts">
-      Scan {project-root}/docs/test-artifacts/*.md
-      Extract: artifact name, type, coverage area
-      Report progress: "Scanning test artifacts... found N artifacts."
-    </action>
+  <action title="Exclusion list">
+    ALWAYS exclude these directories and files from scanning — they are framework internals, not project code:
+    _gaia/, .claude/, bin/, _memory/, node_modules/, .git/, build/, dist/, .DS_Store, *.lock
   </action>
 
-  <action if="agent == theo">
-    Scan theo-specific inventory targets (architecture ground truth):
-
-    <action title="Target 1: Filesystem Structure">
-      Scan {project-path}/ for directory structure, file types, and project layout.
-      Extract: tech stack, components, module boundaries, entry points, build configuration.
-      Report progress: "Scanning filesystem structure for Theo... found N directories, N files."
-    </action>
+  <action title="Target 1: Project Source Files">
+    Scan {project-path}/**/* (excluding the exclusion list above)
+    Extract: file inventory, directory structure, languages used, entry points
+    Report progress: "Scanning project source files... found N files across N directories."
+  </action>
 
-    <action title="Target 2: Architecture Document">
-      Scan {planning_artifacts}/architecture.md
-      Extract: ADRs, architectural decisions, component diagrams, dependency info, integration points, tech stack decisions.
-      Report progress: "Scanning architecture.md for Theo... extracted N ADRs, N components."
-    </action>
+  <action title="Target 2: Project Config Files">
+    Scan {project-path}/*.{json,yaml,yml,toml,xml,env.example} (root-level config files)
+    Extract: config keys, settings, dependency declarations
+    Report progress: "Scanning project config files... found N config files."
   </action>
 
-  <action if="agent == derek">
-    Scan derek-specific inventory targets (product ground truth):
-
-    <action title="Target 1: Product Requirements">
-      Scan {planning_artifacts}/prd.md
-      Extract: functional requirements, non-functional requirements, user stories overview, feature list, product goals.
-      Report progress: "Scanning prd.md for Derek... extracted N requirements."
-    </action>
-
-    <action title="Target 2: Epics and Stories">
-      Scan {planning_artifacts}/epics-and-stories.md
-      Extract: epic list, story breakdown, acceptance criteria summaries, dependency graph, sizing data.
-      Report progress: "Scanning epics-and-stories.md for Derek... extracted N epics, N stories."
-    </action>
-
-    <action title="Target 3: Sprint Status">
-      Scan {implementation_artifacts}/sprint-status.yaml
-      Extract: current sprint state, story statuses, velocity data, blocked items, completion rates.
-      Report progress: "Scanning sprint-status.yaml for Derek... extracted sprint state."
-    </action>
+  <action title="Target 3: Project Package Manifests">
+    Scan {project-path}/**/package.json, pubspec.yaml, pom.xml, build.gradle, requirements.txt, Cargo.toml, go.mod, Gemfile, *.csproj (whichever exist)
+    Extract: dependencies, versions, scripts, build targets
+    Report progress: "Scanning package manifests... found N manifests."
   </action>
 
-  <action if="agent == nate">
-    Scan nate-specific inventory targets (sprint ground truth):
+  <action title="Target 4: Planning Artifacts">
+    Scan {project-root}/docs/planning-artifacts/*.md
+    Extract: artifact name, type, date
+    Report progress: "Scanning planning artifacts... found N artifacts."
+  </action>
 
-    <action title="Target 1: Sprint Status">
-      Scan {implementation_artifacts}/sprint-status.yaml
-      Extract: sprint metadata, story statuses, velocity metrics, blocked items, wave assignments.
-      Report progress: "Scanning sprint-status.yaml for Nate... extracted sprint state."
-    </action>
+  <action title="Target 5: Implementation Artifacts">
+    Scan {project-root}/docs/implementation-artifacts/*.md
+    Extract: artifact name, type, story key if applicable
+    Report progress: "Scanning implementation artifacts... found N artifacts."
+  </action>
 
-    <action title="Target 2: Story Files">
-      Scan all story files in {implementation_artifacts}/ matching pattern *-*.md (story files)
-      Extract: story statuses, completion rates, subtask progress, blockers, review gate states.
-      Report progress: "Scanning story files in implementation-artifacts for Nate... found N stories."
-    </action>
+  <action title="Target 6: Test Artifacts">
+    Scan {project-root}/docs/test-artifacts/*.md
+    Extract: artifact name, type, coverage area
+    Report progress: "Scanning test artifacts... found N artifacts."
   </action>
 </step>
 
-<step n="7" title="Compare and Detect Changes">
-  <action>Compare scan results against previous state from Step 5</action>
+<step n="6" title="Compare and Detect Changes">
+  <action>Compare scan results against previous state from Step 4</action>
   <action>Classify each entry as: ADDED (new file not in previous state), UPDATED (file exists but metadata changed), UNCHANGED (no changes detected)</action>
   <action if="full mode">For entries in previous state not found in scan results: mark as REMOVED with detection date (e.g., "REMOVED (file deleted, detected 2026-03-19)"). Do NOT silently delete entries.</action>
   <action if="incremental mode">Skip deletion detection — incremental mode cannot detect deletions. This is a documented limitation.</action>
   <action>Load ground-truth-management skill section: conflict-resolution (JIT) if any conflicts are detected between scan results and existing entries</action>
 </step>
 
-<step n="8" title="Write Ground Truth">
-  <action>Update ground-truth.md in the resolved target agent's sidecar directory with all scan results</action>
+<step n="7" title="Write Ground Truth">
+  <action>Update {memory_path}/validator-sidecar/ground-truth.md with all scan results</action>
   <action>Write header with last-refresh timestamp set to current date/time</action>
-  <action>Organize entries by category appropriate to the target agent</action>
+  <action>Organize entries by category: Agents, Workflows, Skills, Commands, Manifests, Config, Artifacts</action>
   <action>Include verified counts, locations, and structural patterns for each category</action>
   <action>Preserve REMOVED entries with their detection dates — do not purge</action>
 </step>
 
-<step n="9" title="Generate Diff Report">
+<step n="8" title="Generate Diff Report">
   <action>Generate diff/delta report summarizing changes since last refresh</action>
   <action>Include counts by category: added, removed, updated entries</action>
   <action>Include total entry count across all categories</action>
@@ -174,48 +103,23 @@
   <action>Present the full diff report to the user</action>
 </step>
 
-<step n="10" title="Log to Decision Log">
-  <action>Append the diff/delta report to the target agent's own decision-log.md in the resolved sidecar directory.
-    Route to the correct file based on resolved agent target:
-    - val: {memory_path}/validator-sidecar/decision-log.md
-    - theo: {memory_path}/architect-sidecar/decision-log.md
-    - derek: {memory_path}/pm-sidecar/decision-log.md
-    - nate: {memory_path}/sm-sidecar/decision-log.md
-    Never write to another agent's decision-log.md — this would violate cross-agent write isolation.</action>
-  <action>Include date, refresh mode (full or incremental), target agent name, and summary</action>
-  <action>Format: "## Refresh — {date} ({mode}) — Agent: {agent_name}\n{summary}"</action>
+<step n="9" title="Log to Decision Log">
+  <action>Append the diff/delta report to {memory_path}/validator-sidecar/decision-log.md</action>
+  <action>Include date, refresh mode (full or incremental), and summary</action>
+  <action>Format: "## Refresh — {date} ({mode})\n{summary}"</action>
 </step>
 
-<step n="11" title="Check Token Budget">
+<step n="10" title="Check Token Budget">
   <action>Load ground-truth-management skill section: token-budget (JIT)</action>
-  <action>Load the correct per-agent ground_truth_budget from {memory_path}/config.yaml based on target agent:
-    - Val: 200K (200,000 tokens)
-    - Theo: 150K (150,000 tokens)
-    - Derek: 100K (100,000 tokens)
-    - Nate: 100K (100,000 tokens)
-    These are distinct from the 300K session_budget — ground_truth_budget controls only ground-truth.md size.</action>
-  <action>Estimate token count of the target agent's ground-truth.md</action>
-  <action>If token count exceeds the per-agent budget threshold: trigger archival of oldest REMOVED entries per token-budget skill guidance</action>
-  <action if="agent == all">Report per-agent usage separately (e.g., "Theo: 42K/150K, Derek: 18K/100K")</action>
+  <action>Estimate token count of ground-truth.md</action>
+  <action>If token count exceeds budget threshold: trigger archival of oldest REMOVED entries per token-budget skill guidance</action>
   <action>Report token usage to user</action>
 </step>
 
-<step n="12" title="Present Results">
+<step n="11" title="Present Results">
   <template-output file="{memory_path}/validator-sidecar/ground-truth.md">
-    Ground truth refreshed for the target agent with verified inventory.
-    Output path is resolved at runtime based on --agent parameter (defaults to validator-sidecar).
+    Ground truth refreshed with verified inventory of all framework components.
     Includes last-refresh timestamp, categorized entries, and REMOVED markers for deleted files.
   </template-output>
 </step>
-
-<step n="13" title="Orchestrate --agent all" if="agent == all">
-  <action>Run refresh sequentially for each agent in order: val, theo, derek, nate.
-    Each agent's refresh completes fully (Steps 2-12) before the next begins.
-    No cross-contamination of sidecar writes — each agent writes only to its own sidecar.</action>
-  <action>On per-agent failure (e.g., missing source file like prd.md): log the error with reason, continue with remaining agents. Do not halt the entire sequence.</action>
-  <action>After all agents complete: present a combined summary with per-agent status:
-    - Which agents succeeded and their entry counts
-    - Which agents failed and the failure reasons
-    Format: "Refresh complete. Results: Val: OK (N entries), Theo: OK (N entries), Derek: FAILED (prd.md not found), Nate: OK (N entries)."</action>
-</step>
 </workflow>

package/_gaia/lifecycle/workflows/4-implementation/val-refresh-ground-truth/workflow.yaml

@@ -9,11 +9,6 @@ installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/val-r
 instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 parameters:
-  agent:
-    flag: "--agent"
-    description: "Which Tier 1 agent's ground truth to refresh. Defaults to val for backward compatibility."
-    default: "val"
-    allowed_values: [val, theo, derek, nate, all]
   incremental:
     flag: "--incremental"
     description: "Only scan files modified since last refresh timestamp. Full refresh is default."

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/lifecycle/workflows/anytime/memory-hygiene/instructions.xml

@@ -106,24 +106,14 @@
 </step>
 
 <step n="7" title="Token Budget Reporting">
-  <action>For each agent sidecar, calculate token usage:
-    - Sum file sizes in bytes across all sidecar files (from Step 2 inventory)
-    - Convert to approximate token count: file size in bytes / 4 (chars-per-token approximation from config archival.token_approximation)
-    - For Tier 1 agents: also calculate ground-truth.md token usage separately</action>
-  <action>Compare against budgets from {memory_path}/config.yaml:
-    - Tier 1 session budget: tiers.tier_1.session_budget (300K tokens)
-    - Tier 1 ground truth budget: agents.{agent}.ground_truth_budget (per-agent: Val 200K, Theo 150K, Derek 100K, Nate 100K)
-    - Tier 2 session budget: tiers.tier_2.session_budget (100K tokens)
-    - Tier 3: no budget enforced
-    - Untiered: no budget enforced</action>
-  <action>Apply threshold status indicators per archival config:
-    - OK: below 80% of budget
-    - warning: at or above 80% but below 90%
-    - critical: at or above 90% but below 100%
-    - over-budget: at or above 100%</action>
-  <action>Build Token Budget Table with columns:
-    | Agent | Tier | Files Scanned | Token Usage | Session Budget | GT Budget | % Used | Status |
-    For Tier 3 and untiered agents: budget column shows "no budget enforced" with actual token count reported</action>
+  <action>JIT-load the budget-monitoring section from {project-root}/_gaia/lifecycle/skills/memory-management.md
+    Load only the content between &lt;!-- SECTION: budget-monitoring --&gt; and &lt;!-- END SECTION --&gt; markers</action>
+  <action>Apply the budget-monitoring skill procedure using file sizes from Step 2 inventory and tier budgets from {memory_path}/config.yaml:
+    - Calculate token usage per agent (sum sidecar file sizes, convert via skill formula)
+    - Classify each agent by threshold status (OK / warning / critical / over-budget)
+    - For Tier 1 agents: also report ground truth budget usage separately
+    - For Tier 3 / untiered: report actual tokens with "no budget enforced"</action>
+  <action>Build Token Budget Table per the skill's output format</action>
 </step>
 
 <step n="8" title="Archival Recommendations">

package/gaia-install.sh

@@ -6,7 +6,7 @@ set -euo pipefail
 # Installs, updates, validates, and reports on GAIA installations.
 # ─────────────────────────────────────────────────────────────────────────────
 
-readonly VERSION="1.61.0"
+readonly VERSION="1.63.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.61.0",
+  "version": "1.63.0",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"