Update README with detailed explanation of health shields and their maintenance

Author: DerekGooding

GEMINI.md

@@ -14,8 +14,15 @@ This document contains foundational mandates for the AI assistant (Gemini) durin
 - **Validation:** No logic changes are complete without corresponding unit tests. For complex system interactions, utilize `Mythril.Headless` scenario-based tests. For UI components, use `bUnit` tests.
 - **Documentation:** Keep documentation synchronized with code changes. Staleness is tracked locally by file modification times.
 - **Source Control Awareness:** All changes must be properly committed with clear, descriptive messages.
-- **Feedback Integrity:** User feedback must be technically resolved, not just dismissed. Every cleared item in `docs/feedback/` or `docs/errors/` must have a corresponding technical resolution file in `docs/resolution/`.
-- **Credential Protection:** Never log, print, or commit secrets, API keys, or sensitive URLs.
+- **Feedback Integrity**: User feedback must be technically resolved, not just dismissed. Every cleared item in `docs/feedback/` or `docs/errors/` must have a corresponding technical resolution file in `docs/resolution/`.
+- **AI Guidance System**: When facing architectural or strategic ambiguity, agents must:
+    1. Consult `docs/guidence_knowledge_base.md` for existing decisions.
+    2. If no guidance exists, create a new request in `docs/guidence/` using the template in `docs/guidence.md`.
+    3. **Granularity**: Each high-level question or distinct topic must be its own file to facilitate focused discussion and tracking. Group questions into a single file only if they are tightly coupled.
+    4. Naming convention: `YYYY-MM-DD_topic.md`.
+    4. Wait for human developer response before implementing high-level structural changes.
+- **Credential Protection**: Never log, print, or commit secrets, API keys, or sensitive URLs.
+
 - **Agentic DevOps:** The AI is responsible for the entire DevOps lifecycle within the project scope.
 - **Source Control Submission:** Always commit changes to the git repository **and push to the remote origin** upon completing a task. Push directly to the `main` branch.
 

README.md

@@ -55,6 +55,16 @@ We maintain project health through a custom automated suite (`scripts/check_heal
 - **Documentation Integrity**: Automated staleness tracking via local file modification times.
 - **Feedback Integrity**: Monitoring of pending user feedback and runtime errors in `docs/feedback/`.
 
+### 🛡️ Health Shield Guide
+All badges are automatically updated by `scripts/check_health.py` on every commit:
+- **Tests**: Status of the entire MSTest suite. Fails if any unit test is broken.
+- **Coverage**: Total line coverage percentage. Must remain above 70% overall.
+- **Monoliths**: A count of source files exceeding 250 lines. Aiming for 0 for maximum maintainability.
+- **Docs**: Staleness indicator. Flags documentation if more than 10 source changes occur without a doc update.
+- **UI Integrity**: Validates bUnit test presence, `@key` usage in loops, and stable `data-testid` anchors.
+- **Reachability**: Result of the Game Graph Simulation. Verifies all content is mathematically attainable.
+- **Optimal Completion**: The minimum real-world time required to finish the current endgame content.
+
 ## 🚀 Getting Started
 1. **Build**: `dotnet build`
 2. **Test**: `dotnet test`

docs/guidence/2026-03-04_architectural_complexity.md

@@ -0,0 +1,13 @@
+# Guidance Request: Architectural Philosophy (Complexity vs. Performance)
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+Many proposed suggestions (Dungeons, Base Building) add significant state complexity and potential performance overhead.
+
+## Questions
+1. Should we prioritize horizontal expansion (more locations/cadences with simple logic) or vertical depth (more complex, interconnected systems per character)?
+
+## Human Guidance
+These are equally important. Do both in tandem. 

docs/guidence/2026-03-04_automation_philosophy.md

@@ -0,0 +1,13 @@
+# Guidance Request: Automation Philosophy
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+"Logistics" and "AutoQuest" systems allow for increasing levels of idleness.
+
+## Questions
+1. How "idle" should the game be? Should "Logistics" eventually reach a point where the entire party can run autonomously, or should there always be a manual bottleneck (e.g. manual restart required for certain tiers)?
+
+## Human Guidance
+[BLANK]

docs/guidence/2026-03-04_character_identity.md

@@ -0,0 +1,13 @@
+# Guidance Request: Character Narrative Identity
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+Currently, the three party members are identical except for their names.
+
+## Questions
+1. Do you want characters to remain "blank slates" for the user to customize, or should they have fixed narrative roles/starting passives that influence their optimal builds?
+
+## Human Guidance
+[BLANK]

docs/guidence/2026-03-04_equipment_system.md

@@ -0,0 +1,14 @@
+# Guidance Request: Equipment System Implementation
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+Proposed equipment slots for Weapons and Armor.
+
+## Questions
+1. Should equipment be consumed (like magic in refinements) or permanent items?
+2. How does this balance with the existing "Junctioning is everything" design philosophy?
+
+## Human Guidance
+[BLANK]

docs/guidence/2026-03-04_progression_wall.md

@@ -0,0 +1,13 @@
+# Guidance Request: Progression Pacing (The Wall)
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+Balancing the transition from early to mid-game.
+
+## Questions
+1. At what point in real-world time (e.g. 2 hours, 10 hours) should the player hit the first significant "grind" where they must optimize junctions to proceed?
+
+## Human Guidance
+[BLANK]

docs/guidence/2026-03-04_resource_scarcity.md

@@ -0,0 +1,13 @@
+# Guidance Request: Resource Scarcity
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+Mythril Spark is currently a rare one-time reward.
+
+## Questions
+1. Should rare resources remain strictly one-time rewards to gate progression, or should there be an extremely difficult recurring path to obtain them?
+
+## Human Guidance
+[BLANK]

docs/guidence/2026-03-04_stat_caps.md

@@ -0,0 +1,13 @@
+# Guidance Request: Stat Caps and Scaling
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+With the new simulation tool, we see stats reaching 100-200.
+
+## Questions
+1. Is there a mathematical "ceiling" we should aim for, or should stat requirements and junction bonuses scale infinitely?
+
+## Human Guidance
+[BLANK]

docs/guidence/2026-03-04_visual_aesthetic.md

@@ -0,0 +1,13 @@
+# Guidance Request: Visual Aesthetic Direction
+
+**Date:** 2026-03-04
+**Agent:** Gemini CLI
+
+## Context
+The UI is currently a minimalist dashboard.
+
+## Questions
+1. Should we stick to the clean minimalist look, or should we introduce more illustrative elements such as character portraits, map icons, or item sprites?
+
+## Human Guidance
+[BLANK]