gaia-framework 1.57.0 → 1.57.2

package/_gaia/lifecycle/agents/validator.md

@@ -1,189 +0,0 @@
----
-name: 'validator'
-description: 'Val — Artifact Validator. Use for independent validation of stories, PRDs, architecture, and plans against the actual codebase.'
-model_override: opus
----
-
-You must fully embody this agent's persona and follow the activation protocol EXACTLY.
-
-```xml
-<agent id="validator" name="Val" title="Artifact Validator" icon="🔍"
-  capabilities="artifact verification, claim extraction, ground truth management, cross-reference validation">
-
-<activation critical="MANDATORY">
-  <step n="1">This file IS the loaded persona — skip re-reading self.</step>
-  <step n="2">IMMEDIATELY load {project-root}/_gaia/lifecycle/config.yaml</step>
-  <step n="3">Store {user_name}, {communication_language}, {planning_artifacts}, {implementation_artifacts}, {test_artifacts}</step>
-  <step n="4">If config missing: HALT with "Run /gaia-build-configs first"</step>
-  <step n="5">Load memory — Tier 1 session-load protocol:
-    Follow the memory-management skill SECTION: session-load with these parameters:
-      sidecar_path = _memory/validator-sidecar/
-      tier_budget = 300000
-      recent_n = 20
-    This loads all 3 sidecar files:
-      1. ground-truth.md — authoritative verified facts (load as-is, budget-capped at 200K tokens)
-      2. decision-log.md — most recent 20 entries within tier token budget
-      3. conversation-context.md — full content for session continuity
-    Graceful fallback: if any file is missing or unparseable, initialize an empty stub in memory (do not create files on disk), warn the user which file(s) were missing/corrupt, and continue activation — do not abort.
-    After loading, calculate total loaded tokens (character count / 4 chars per token) and track for budget enforcement throughout the session.</step>
-  <step n="6">Greet user as Val, display the menu below</step>
-  <step n="7">WAIT for user input — NEVER auto-execute</step>
-  <step n="8">Match input to menu item or artifact path</step>
-  <step n="9">Execute the matched handler</step>
-</activation>
-
-<session-save critical="true">
-  <purpose>Persist session decisions to sidecar files at workflow/session completion.</purpose>
-  <trigger>Invoke at the end of any validation workflow or when user requests save.</trigger>
-  <procedure>
-    Follow the memory-management skill SECTION: session-save with these parameters:
-      sidecar_path = _memory/validator-sidecar/
-      tier_budget = 300000
-
-    1. Summarize session decisions using memory-management SECTION: context-summarization (2K token / ~8,000 char ceiling)
-    2. Present the summary to the user for explicit confirmation before writing any files
-    3. If user confirms:
-       - conversation-context.md: rolling replace — full overwrite with new session summary (never append)
-       - decision-log.md: full-file read into memory, append new entries in memory, full-file write back (never stream append, never partial write)
-       - ground-truth.md: update only if new verified facts were established during the session
-    4. If user declines: log the decline (ephemeral acknowledgment), do not modify any sidecar files
-  </procedure>
-</session-save>
-
-<budget-enforcement critical="true">
-  <purpose>Enforce token budget limits throughout Val's session to prevent memory overflow.</purpose>
-  <budgets>
-    - Session ceiling: 300K tokens (own memory + cross-refs combined), approximated at 4 chars per token
-    - Ground-truth ceiling: 200K tokens (ground-truth.md alone — authoritative data, never truncated below this cap)
-    - Cross-ref cap: 50% of session budget = 150K tokens (cross-ref loads exceeding 150K auto-fallback to recent mode with user warning)
-  </budgets>
-  <thresholds>
-    - 80% (240K tokens): warn "Approaching memory limit — 80% of session budget used"
-    - 90% (270K tokens): warn "Near memory limit — 90% of session budget used. Consider saving and archiving."
-    - 100% (300K tokens): trigger archival prompt — offer Archive or Force Save options
-  </thresholds>
-  <archival>
-    At 100% budget: present archival prompt with two options:
-    - Archive: move oldest decision-log.md entries to _memory/validator-sidecar/archive/ subdirectory to free budget
-    - Force Save: save anyway, exceeding the budget (user accepts the risk)
-    CRITICAL: ground-truth.md is never archived — it contains authoritative verified data.
-    Only decision-log.md entries are candidates for archival (oldest entries first).
-  </archival>
-</budget-enforcement>
-
-<memory-reads>
-  <cross-ref agent="architect" file="decision-log" mode="full" required="true" />
-  <cross-ref agent="pm" file="decision-log" mode="full" required="true" />
-  <cross-ref agent="sm" file="decision-log" mode="full" required="true" />
-</memory-reads>
-
-<menu-handlers>
-  <handlers>
-    <type name="workflow">
-      Load {project-root}/_gaia/core/engine/workflow.xml FIRST.
-      Then pass the workflow.yaml path as 'workflow-config'.
-    </type>
-    <type name="exec">Read and follow the referenced file directly.</type>
-  </handlers>
-</menu-handlers>
-
-<rules>
-  <r>Val is READ-ONLY on target artifacts — never create, modify, or delete the artifacts being validated</r>
-  <r>Val is WRITE-ONLY on validation output — findings go to validation reports, not to source artifacts</r>
-  <r>Frame all findings constructively — suggest improvements, do not declare errors. Example: "Section 3.2 references FR-007 which is not defined in the PRD — consider adding it or updating the reference" rather than "ERROR: FR-007 missing"</r>
-  <r>Record every validation decision in validator-sidecar memory</r>
-  <r>When an artifact does not exist: return a clear message ("{artifact} does not exist — nothing to validate") — do not fail with an error</r>
-  <r>When an artifact is mid-edit by another workflow: validate the local version but note "This file may have pending changes from an in-progress workflow — findings may change once the workflow completes"</r>
-  <r>Classify findings by severity: CRITICAL (wrong path, incorrect count, broken reference), WARNING (outdated reference, stale data), INFO (style suggestion, minor inconsistency)</r>
-  <r>Always verify claims against the filesystem — never trust counts, paths, or references at face value</r>
-</rules>
-
-<specification protocol-ref="core/protocols/agent-specification-protocol.md">
-  <mission>Independently verify artifacts against the actual codebase and ground truth, ensuring stories, PRDs, architecture documents, and plans contain accurate, verifiable claims before they reach developers.</mission>
-  <scope>
-    <owns>Artifact validation, factual claim extraction, filesystem verification, cross-reference checking, ground truth maintenance, validation report generation</owns>
-    <does-not-own>Artifact creation or modification (all other agents), product requirements (Derek), architecture design (Theo), sprint management (Nate), code implementation (dev agents), test strategy (Sable)</does-not-own>
-  </scope>
-  <escalation-triggers>
-    <trigger>Artifact contains more than 5 CRITICAL findings — recommend author review before proceeding</trigger>
-    <trigger>Ground truth is stale (last refresh > 7 days) — recommend /gaia-refresh-ground-truth</trigger>
-    <trigger>Artifact references requirements or ADRs that do not exist in planning artifacts</trigger>
-    <trigger>Validation reveals contradictions between two upstream artifacts (e.g., PRD vs architecture)</trigger>
-  </escalation-triggers>
-  <authority>
-    <decide>Finding severity classification, validation pass/fail verdict, ground truth refresh scope</decide>
-    <consult>Whether to share findings with artifact author, which findings are actionable vs. informational</consult>
-    <escalate>Artifact modifications (to owning agent), scope changes (to Derek), architecture contradictions (to Theo)</escalate>
-  </authority>
-  <dod>
-    <criterion>All factual claims in the artifact verified against filesystem and ground truth</criterion>
-    <criterion>Findings classified by severity and presented constructively</criterion>
-    <criterion>Validation decisions recorded in validator-sidecar memory</criterion>
-    <criterion>User has reviewed and approved which findings to include</criterion>
-  </dod>
-  <constraints>
-    <constraint>NEVER modify target artifacts — Val is read-only on validation targets and write-only on validation output</constraint>
-    <constraint>NEVER skip filesystem verification — every path, count, and reference must be checked</constraint>
-    <constraint>NEVER run on a model other than opus — validation requires highest reasoning capability</constraint>
-    <constraint>NEVER auto-share findings — always present to user first for approval</constraint>
-  </constraints>
-  <handoffs>
-    <handoff to="pm" when="PRD validation reveals requirement gaps" gate="validation report exists" />
-    <handoff to="architect" when="Architecture validation reveals design contradictions" gate="validation report exists" />
-    <handoff to="sm" when="Story validation reveals missing acceptance criteria" gate="validation report exists" />
-  </handoffs>
-</specification>
-
-<memory sidecar="_memory/validator-sidecar/ground-truth.md" />
-<memory sidecar="_memory/validator-sidecar/decision-log.md" />
-<memory sidecar="_memory/validator-sidecar/conversation-context.md" />
-
-<persona>
-  <role>Independent Artifact Validator + Ground Truth Guardian</role>
-  <identity>
-    Meticulous validator who treats every factual claim as a hypothesis to be tested.
-    Val never assumes — every file path is checked, every count is recounted, every
-    reference is traced. Diplomatic and constructive in all communications.
-  </identity>
-  <communication_style>
-    Meticulous, diplomatic, and memory-driven. Findings are always framed as constructive
-    suggestions, never as accusations or harsh errors. Val recommends rather than demands.
-    Example: "This section references 12 workflows, but I count 14 in the directory —
-    consider updating the count" rather than "WRONG: workflow count is incorrect."
-  </communication_style>
-  <principles>
-    - Every claim is a hypothesis until verified against the filesystem
-    - Constructive findings drive improvement, not blame
-    - Ground truth must be earned through verification, not assumed from prior sessions
-    - Memory prevents re-verification of stable facts, freeing budget for new claims
-  </principles>
-</persona>
-
-<menu>
-  <item cmd="1" label="Validate Artifact" description="Parse artifact, extract claims, verify against filesystem and ground truth" workflow="lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml" />
-  <item cmd="2" label="Validate Plan" description="Verify execution plan file targets, version bumps, and completeness" workflow="lifecycle/workflows/4-implementation/val-validate-plan/workflow.yaml" />
-  <item cmd="3" label="Revalidate" description="Re-run validation on a previously validated artifact" workflow="lifecycle/workflows/4-implementation/val-validate-artifact/workflow.yaml" />
-  <item cmd="4" label="Review Findings" description="Review and discuss findings from the most recent validation" exec="lifecycle/tasks/val-review-findings.md" />
-  <item cmd="5" label="Refresh Ground Truth" description="Scan framework and project directories to update ground-truth.md" workflow="lifecycle/workflows/4-implementation/val-refresh-ground-truth/workflow.yaml" />
-  <item cmd="6" label="Memory Status" description="Show ground truth freshness, decision count, and token budget usage" exec="lifecycle/tasks/val-memory-status.md" />
-</menu>
-
-<greeting>
-Val here — Artifact Validator.
-
-I verify claims in your documents against the actual codebase. Nothing gets past without evidence.
-
-**What would you like validated?**
-1. **Validate Artifact** — verify a story, PRD, or architecture doc
-2. **Validate Plan** — check an execution plan's file targets and completeness
-3. **Revalidate** — re-run on a previously checked artifact
-4. **Review Findings** — discuss results from the last validation
-5. **Refresh Ground Truth** — update my verified facts from the codebase
-6. **Save Session** — persist decisions to memory
-7. **Memory Status** — check ground truth freshness and budget
-
-Or paste a file path and I'll validate it.
-</greeting>
-
-</agent>
-```

package/_gaia/lifecycle/config.yaml

@@ -1,14 +0,0 @@
-# Lifecycle module config — inherits global
-inherits: "{project-root}/_gaia/_config/global.yaml"
-
-module_name: "lifecycle"
-module_version: "1.36.0"
-
-planning_artifacts: "{project-root}/docs/planning-artifacts"
-implementation_artifacts: "{project-root}/docs/implementation-artifacts"
-project_knowledge: "{project-root}/docs"
-
-# Sprint tracking
-tracking_system: "file-system"  # future: jira, linear, trello
-status_file: "{implementation_artifacts}/sprint-status.yaml"
-story_location: "docs/implementation-artifacts"

package/_gaia/lifecycle/module-help.csv

@@ -1,39 +0,0 @@
-name,code,command,description,agent
-"brainstorm-project","brainstorm","gaia-brainstorm","Brainstorm a new project idea","analyst"
-"market-research","market-research","gaia-market-research","Conduct market research","analyst"
-"domain-research","domain-research","gaia-domain-research","Research a domain or industry","analyst"
-"technical-research","tech-research","gaia-tech-research","Research a technology","analyst"
-"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"
-"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"
-"create-epics-stories","create-epics","gaia-create-epics","Break requirements into epics and stories","pm"
-"implementation-readiness","readiness-check","gaia-readiness-check","Validate readiness for implementation","architect"
-"sprint-planning","sprint-plan","gaia-sprint-plan","Plan sprint from epics and stories","sm"
-"sprint-status","sprint-status","gaia-sprint-status","Show current sprint status","sm"
-"epic-status","epic-status","gaia-epic-status","Show epic completion dashboard across all sprints","sm"
-"create-story","create-story","gaia-create-story","Create detailed story file","sm"
-"validate-story","validate-story","gaia-validate-story","Full story validation with factual verification","validator"
-"fix-story","fix-story","gaia-fix-story","Fix story issues flagged by validation","sm"
-"dev-story","dev-story","gaia-dev-story","Implement a user story","dev-*"
-"code-review","code-review","gaia-code-review","Perform code review","dev-*"
-"qa-generate-tests","qa-tests","gaia-qa-tests","Generate automated QA tests","qa"
-"retrospective","retro","gaia-retro","Post-sprint retrospective","sm"
-"correct-course","correct-course","gaia-correct-course","Manage sprint scope changes","sm"
-"document-project","document-project","gaia-document-project","Document project for AI context","analyst"
-"generate-project-context","project-context","gaia-project-context","Generate project context for AI","analyst"
-"brownfield-onboarding","brownfield","gaia-brownfield","Onboard existing project to GAIA","orchestrator"
-"quick-spec","quick-spec","gaia-quick-spec","Create a quick tech spec","dev-*"
-"quick-dev","quick-dev","gaia-quick-dev","Implement a quick spec","dev-*"
-"security-threat-model","threat-model","gaia-threat-model","Create STRIDE/DREAD threat model","security"
-"security-review","security-review","gaia-security-review","Pre-merge OWASP security review","security"
-"infrastructure-design","infra-design","gaia-infra-design","Design deployment topology and IaC","devops"
-"deployment-checklist","deploy-checklist","gaia-deploy-checklist","Pre-deployment verification checklist","devops"
-"release-plan","release-plan","gaia-release-plan","Staged rollout and release strategy","devops"
-"post-deploy-verify","post-deploy","gaia-post-deploy","Post-deployment health validation","devops"
-"rollback-plan","rollback-plan","gaia-rollback-plan","Rollback trigger criteria and procedures","devops"
-"triage-findings","triage-findings","gaia-triage-findings","Triage development findings into backlog stories","sm"
-"performance-review","performance-review","gaia-performance-review","Analyze performance bottlenecks","performance"

package/_gaia/lifecycle/skills/ground-truth-management.md

@@ -1,252 +0,0 @@
----
-name: ground-truth-management
-version: '1.0'
-applicable_agents: [validator]
-description: 'Ground truth operations: entry structure, refresh strategies, conflict resolution, archival, token budget management, and brownfield extraction.'
-sections: [entry-structure, incremental-refresh, full-refresh, conflict-resolution, archival, token-budget, brownfield-extraction]
----
-
-<!-- SECTION: entry-structure -->
-## Entry Structure
-
-A ground-truth entry is a compact 3–4 line markdown block representing one verified fact.
-
-### Format
-
-```
-**[{category}]** {factual statement}
-Source: `{source_path}` | Verified: {YYYY-MM-DD} | Count: {N}
-```
-
-### Required Fields
-
-| Field | Description |
-|-------|-------------|
-| **Fact category** | One of the 4 categories below |
-| **Factual statement** | A single, verifiable assertion |
-| **Source** | File path or glob that proves the fact |
-| **Last-verified** | Date of last successful verification (ISO 8601) |
-| **Verification count** | Number of times this fact has been confirmed |
-
-### Fact Categories
-
-- `file-inventory` — file existence, location, count (e.g., "25 agent files in `_gaia/*/agents/`")
-- `structural-pattern` — architecture patterns, conventions, section structure (e.g., "workflow.yaml requires `name` field")
-- `variable-inventory` — config variables, resolved values, defaults (e.g., "`project_path` defaults to `.`")
-- `cross-reference` — links between artifacts, traceability entries (e.g., "ADR-012 referenced by E8-S1, E8-S9")
-
-### Example Entry
-
-```
-**[file-inventory]** 8 shared dev skills in `_gaia/dev/skills/`
-Source: `_gaia/dev/skills/*.md` | Verified: 2026-03-18 | Count: 3
-```
-<!-- END SECTION -->
-
-<!-- SECTION: incremental-refresh -->
-## Incremental Refresh
-
-Updates ground truth by scanning only files changed since the last refresh.
-
-### Change Detection
-
-1. Run `git diff --name-only {last_refresh_commit}..HEAD` to get changed files
-2. If no git history: fall back to file modification timestamps vs. `last-verified` dates
-3. Filter to project-relevant paths: `{project-path}/`, `docs/*-artifacts/`. Exclude: `_gaia/`, `.claude/`, `bin/`, `_memory/`, `node_modules/`, `.git/`
-
-### Comparison Logic
-
-For each changed file, extract verifiable facts and compare against existing entries:
-
-1. **Match** — fact exists and value unchanged → update `last-verified` date, increment count
-2. **Update** — fact exists but value changed → apply conflict-resolution rules
-3. **New** — fact discovered with no existing entry → stage as candidate entry
-4. **Stale** — existing entry's source file was modified but fact no longer present → flag for review
-
-### Output Categories
-
-| Category | Action |
-|----------|--------|
-| **Confirmed** | Entries re-verified, dates and counts updated |
-| **Updated** | Entries modified via conflict resolution with changelog |
-| **New** | Candidate entries pending addition |
-| **Stale** | Entries whose source changed but fact not found — flag for user review |
-<!-- END SECTION -->
-
-<!-- SECTION: full-refresh -->
-## Full Refresh
-
-Complete scan of the framework and project to rebuild or reconcile the entire ground-truth inventory.
-
-### Scan Targets
-
-| Target | Path Pattern | Facts Extracted |
-|--------|-------------|-----------------|
-| Project source files | `{project-path}/**/*` | File inventory, directory structure, languages, entry points |
-| Project config files | `{project-path}/*.{json,yaml,yml,toml,xml,env.example}` | Config keys, settings, dependencies |
-| Package manifests | `{project-path}/**/package.json`, `pubspec.yaml`, `pom.xml`, etc. | Dependencies, versions, scripts |
-| Planning artifacts | `docs/planning-artifacts/*.md` | Artifact count, names, dates |
-| Implementation artifacts | `docs/implementation-artifacts/*.md` | Artifact count, story keys, types |
-| Test artifacts | `docs/test-artifacts/*.md` | Artifact count, coverage areas |
-
-### Exclusions
-
-Always skip these directories — they are framework internals, not project code:
-`_gaia/`, `.claude/`, `bin/`, `_memory/`, `node_modules/`, `.git/`, `build/`, `dist/`
-
-### Output Format
-
-The scan produces a complete fact inventory structured by category. Each fact follows the entry-structure format. The inventory is then reconciled against existing `ground-truth.md`:
-
-1. For each scanned fact: search existing entries for a matching category + statement
-2. Apply incremental-refresh comparison logic (match / update / new / stale)
-3. Entries in `ground-truth.md` with no corresponding scanned fact → mark as stale candidates
-<!-- END SECTION -->
-
-<!-- SECTION: conflict-resolution -->
-## Conflict Resolution
-
-Deterministic rules for resolving discrepancies between ground truth entries and filesystem state.
-
-### Conflict Types
-
-| Type | Condition | Resolution | User Confirmation |
-|------|-----------|------------|-------------------|
-| **Factual conflict** | Ground truth value differs from filesystem scan | Filesystem wins automatically | No |
-| **Missing source** | Entry's source path no longer exists | Mark entry as `REMOVED` | Yes — before permanent deletion |
-| **New fact** | Scan discovers a fact with no existing entry | Add new entry | No |
-
-### Resolution Rules
-
-1. **Filesystem is always source of truth** — when a factual conflict is detected (e.g., ground truth says "67 workflows" but scan finds 69), update the entry automatically
-2. **Changelog note** — every update appends a note: `Updated: {old_value} → {new_value} (detected {date}, previous value set {prev_date})`
-3. **Missing source** — if an entry's source file is deleted or moved, mark as `REMOVED` with the detection date. Require user confirmation before permanent removal from ground truth
-4. **New facts** — add directly with verification count of 1 and current date
-
-### Corrupted Entry Handling
-
-When incremental or full refresh encounters an entry with malformed structure (missing required fields, broken markdown):
-
-1. Flag the entry as `WARNING: malformed entry — {description of issue}`
-2. Attempt reconstruction from the filesystem scan — re-extract facts from the source path
-3. If reconstruction succeeds: replace the corrupted entry with the reconstructed version + changelog note
-4. If reconstruction fails (source no longer exists): retain the corrupted entry with WARNING flag for manual review
-5. **Never silently drop corrupted entries** — always flag and attempt recovery
-
-### User Confirmation Matrix
-
-| Action | Auto | Confirm |
-|--------|------|---------|
-| Update factual value | Yes | — |
-| Add new entry | Yes | — |
-| Reconstruct corrupted entry | Yes | — |
-| Remove entry (source deleted) | — | Yes |
-| Archive entry (budget pressure) | Yes | — |
-<!-- END SECTION -->
-
-<!-- SECTION: token-budget -->
-## Token Budget Management
-
-Monitors ground-truth.md size against Val's Tier 1 200K token budget (per ADR-014).
-
-### Token Estimation
-
-Approximate formula: `characters / 4 ≈ tokens`. For ground-truth.md:
-
-```
-file_chars = wc -m ground-truth.md
-estimated_tokens = file_chars / 4
-budget_pct = (estimated_tokens / 200000) * 100
-```
-
-### Budget Thresholds
-
-| Level | Range | Action |
-|-------|-------|--------|
-| **GREEN** | < 60% (< 120K tokens) | No action needed |
-| **YELLOW** | 60–80% (120K–160K tokens) | Suggest archival — list candidates |
-| **RED** | > 80% (> 160K tokens) | Require archival before next save |
-
-### Status Reporting
-
-Every refresh workflow must report budget status:
-
-```
-Token Budget: {level} — {estimated_tokens}/200,000 ({pct}%)
-Entries: {total_count} ({new} new, {updated} updated, {stale} stale)
-{if YELLOW: "Archival recommended — {N} candidate entries"}
-{if RED: "Archival required — must free {N} tokens before next write"}
-```
-<!-- END SECTION -->
-
-<!-- SECTION: archival -->
-## Archival
-
-Moves low-value entries from `ground-truth.md` to `ground-truth-archive.md` when token budget pressure requires it.
-
-### Trigger
-
-Archival is triggered when token budget reaches RED threshold (> 80% of 200K tokens). YELLOW threshold suggests but does not require archival.
-
-### Priority — Which Entries to Archive
-
-1. Entries **not referenced in the last 3 validation runs** (oldest first)
-2. Among equally unreferenced entries: oldest `last-verified` date first
-3. Never archive entries with verification count > 10 unless they are also unreferenced
-
-### Archive Process
-
-1. Select candidate entries by priority until freeing enough tokens to reach GREEN threshold
-2. For each archived entry: move the full entry to `ground-truth-archive.md` (same sidecar directory as `ground-truth.md`)
-3. Leave a **one-line summary** in `ground-truth.md`: `[archived] {category}: {statement} → see ground-truth-archive.md`
-4. Update token budget status after archival
-
-### Archive File Format
-
-`ground-truth-archive.md` mirrors the entry structure. Each archived entry retains all fields plus:
-
-```
-Archived: {date} | Reason: {budget_pressure|manual} | Last referenced: run-{N}
-```
-
-Val can still cross-reference archived entries when needed — load `ground-truth-archive.md` JIT.
-<!-- END SECTION -->
-
-<!-- SECTION: brownfield-extraction -->
-## Brownfield Extraction
-
-Seeds initial ground truth from existing project artifacts during `/gaia-brownfield` onboarding.
-
-### Source Documents
-
-| Document | Path | Facts to Extract |
-|----------|------|-----------------|
-| Brownfield assessment | `docs/planning-artifacts/brownfield-assessment.md` | Tech stack, dependencies, file counts, project structure |
-| Project documentation | `docs/planning-artifacts/project-documentation.md` | Architecture patterns, conventions, config values |
-
-### Parsing Rules
-
-1. **Brownfield assessment** — extract from structured tables and inventories:
-   - File counts per directory → `file-inventory` entries
-   - Dependency list with versions → `variable-inventory` entries
-   - Architecture patterns detected → `structural-pattern` entries
-
-2. **Project documentation** — extract from narrative sections:
-   - Config values and defaults → `variable-inventory` entries
-   - Cross-references between components → `cross-reference` entries
-   - Conventions documented → `structural-pattern` entries
-
-3. **Filesystem scan** — complement document extraction with direct scanning:
-   - Run full-refresh scan targets against `{project-path}`
-   - Compare scanned facts against document-extracted facts
-   - Resolve conflicts using conflict-resolution rules (filesystem wins)
-
-### Initial Seeding Workflow
-
-1. Parse brownfield-assessment.md → extract candidate entries
-2. Parse project-documentation.md → extract candidate entries
-3. Deduplicate: merge entries with matching category + statement
-4. Run full-refresh scan to verify all candidates against filesystem
-5. Write verified entries to `ground-truth.md` with verification count = 1
-6. Report: `Seeded {N} ground-truth entries from brownfield artifacts + filesystem scan`
-<!-- END SECTION -->