gitgalaxy 2.2.1__tar.gz → 2.2.3__tar.gz

gitgalaxy-2.2.3/.github/workflows/gitgalaxy.yml

@@ -0,0 +1,72 @@
+name: GitGalaxy Zero-Trust Pipeline
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  vault-sentinel:
+    name: Vault Sentinel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: squid-protocol/gitgalaxy@v2.2.3
+        with:
+          tool: 'vault-sentinel'
+          target: '.'
+
+  xray-inspector:
+    name: X-Ray Inspector
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: squid-protocol/gitgalaxy@v2.2.3
+        with:
+          tool: 'xray-inspector'
+          target: '.'
+
+  supply-chain-firewall:
+    name: Supply Chain Firewall
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: squid-protocol/gitgalaxy@v2.2.3
+        with:
+          tool: 'supply-chain-firewall'
+          target: '.'
+
+  architectural-report:
+    name: LLM Structural Brief
+    needs: [vault-sentinel, xray-inspector, supply-chain-firewall]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Critical: Grants the Action permission to push to main
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate GalaxyScope LLM Brief
+        uses: squid-protocol/gitgalaxy@v2.2.3
+        with:
+          tool: 'galaxyscope'
+          target: '.'
+          args: '--llm-only'
+          full_precision: 'true'
+
+      - name: Commit and Push LLM Brief to Main
+        run: |
+          # Move the report to the docs folder for clean organization
+          mkdir -p docs
+          mv *_galaxy_llm.md docs/gitgalaxy_architecture_brief.md || true
+          
+          # Configure the GitHub Actions bot identity
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Stage the file
+          git add docs/gitgalaxy_architecture_brief.md
+          
+          # Only commit and push if there are actual changes to prevent pipeline failures
+          git diff --quiet && git diff --staged --quiet || (git commit -m "docs: auto-update LLM architectural brief" && git push)

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitgalaxy
-Version: 2.2.1
+Version: 2.2.3
 Summary: An AST-free, LLM-free zero-trust static analysis engine for mapping architectural risk, securing CI/CD pipelines, and modernizing legacy monoliths.
 Author: Joe Esquibel
 Project-URL: Homepage, https://gitgalaxy.io
@@ -19,12 +19,13 @@ Classifier: Intended Audience :: Information Technology
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
 Dynamic: license-file
 
 # GitGalaxy
 
 [![PyPI version](https://badge.fury.io/py/gitgalaxy.svg)](https://badge.fury.io/py/gitgalaxy)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 
 [![Engine](https://img.shields.io/badge/Engine-blAST-8A2BE2.svg)](#)
@@ -33,26 +34,25 @@ Dynamic: license-file
 [![Threat Hunting](https://img.shields.io/badge/Threat_Hunting-Behavioral-FF4500.svg)](#)
 [![Architecture](https://img.shields.io/badge/Architecture-Zero__Trust-teal.svg)](#)
 [![Coverage](https://img.shields.io/badge/Coverage-50%2B_Languages-00C957.svg)](#)
-[![Scale](https://img.shields.io/badge/Scale-100k%2B_LOC%2Fsec-00BFFF.svg)](#)
 
 [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)](https://pypi.org/project/gitgalaxy/)
 [![Airgap Ready](https://img.shields.io/badge/Security-Airgap_Ready-teal.svg)](#)
 [![Downloads](https://static.pepy.tech/badge/gitgalaxy)](https://pepy.tech/project/gitgalaxy)
-[![GitHub stars](https://img.shields.io/github/stars/squid-protocol/gitgalaxy?style=social)](https://github.com/squid-protocol/gitgalaxy/stargazers)
 
-### **AST-Free Static Analysis & Knowledge Graph Engine**
+### **Whole-Repository Understanding & DevSecOps Physics**
 
-The blAST (Bypassing LLMs and ASTs) engine is a custom-made knowledge graph engine that resolves repositories at the function level. It scores each function based on 50 unique metrics, rolls that data up to score the file, and finally summarizes the entire repository.
+Most tools analyze code line-by-line. GitGalaxy maps the entire architectural ecosystem. By tracking the exact flow of information across network dependencies, identifying local folder constraints, and natively recognizing 50+ languages—even mid-file—GitGalaxy provides a deterministic, 10,000-foot view of your software's physical architecture.
 
 ### Scanning Apollo-11 with the blAST Engine
 
 ![GitGalaxy CLI Scan](./docs/wiki/assets/apollo11_scan.gif)
 
-By utilizing a custom engine, we retain full control over the search space. We built it to be exceptionally fast, capable of assessing your entire repository without requiring compilable code—a fundamental limitation of standard Abstract Syntax Trees (ASTs). ASTs are great for finding missing commas and memory overflows, but they miss the forest for the trees when generating knowledge graphs. LLMs, on the other hand, suffer from hallucination during large context windows and yield probabilistic, fluctuating answers.
+**Why we built a custom physics engine:**
+Standard Abstract Syntax Trees (ASTs) are great for finding syntax errors, but they require compilable code and miss the forest for the trees when mapping massive-scale information flow. LLMs, on the other hand, suffer from severe hallucination when analyzing large context windows and yield probabilistic, fluctuating answers.
 
-The blAST engine solves this. Because all programming languages utilize keywords and functions, our engine treats code files as text, scanning for these structural anchors to build a deterministic 3D knowledge graph. It seamlessly handles mid-file language switching, assesses the architectural ratio of test files to logic, and extracts invaluable project structure data that ASTs ignore.
+The **blAST (Bypassing LLMs and ASTs) engine** solves this. It reads code as raw structural text, scanning for semantic anchors to build a deterministic 3D knowledge graph of your entire repository. It instantly calculates the ratio of test boundaries to core logic, maps network blast radiuses, and extracts the vital project structure data that rigid linters ignore.
 
-Every assumption our system makes has been abstracted into over 300 tunable variables. Think of GitGalaxy as a highly calibrated telescope. You can query the number of active API network nodes, isolate unique external imports, or highlight functions exhibiting extreme cognitive load—all adjusted via custom whitelists and blacklists to eliminate false-positive fatigue. Field-tested on over 1,000 repositories spanning 50+ languages and 250+ extensions, the engine comes equipped with smart defaults ready for immediate deployment.
+Think of GitGalaxy as a highly calibrated telescope for codebase risk. Every assumption the system makes is abstracted into over 300 tunable variables. You can query active API nodes, isolate supply chain threats, or highlight functions exhibiting extreme cognitive load—all adjusted via custom shields to eliminate false-positive fatigue. Field-tested on over 1,000 repositories, the engine comes equipped with enterprise-grade defaults ready for immediate CI/CD deployment.
 
 **Core Codebase Mapping Technology**
 * Bypasses LLMs and rigid ASTs.
@@ -89,6 +89,7 @@ GitGalaxy is backed by an academic-grade thesis detailing the equations powering
 **Installation & Usage**
 * Python-based: `pip install gitgalaxy`
 * CLI execution
+* CI/CD Integration: Native **[GitHub Action](github-action-read-me.md)** available for zero-trust DevSecOps pipelines.
 * Outputs forensic JSONs (optimized for AI-agent summary reports) and a native SQLite3 database for robust querying and storage.
 
 > **📖 Official Documentation:** Read the full technical specifications, architecture blueprints, and the Taxonomical Equivalence Map at **[squid-protocol.github.io/gitgalaxy](https://squid-protocol.github.io/gitgalaxy/)**.
@@ -116,8 +117,11 @@ galaxyscope /path/to/your/local/repo
 
 GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
 
-Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+**🚀 [View the Full GitHub Action Integration Guide](github-action-read-me.md)**
 
+Check out our comprehensive guide to set up the **"Golden Path" Pipeline** (Parallel Enforcement & Autonomous Reporting). It covers all available Sentinel tools, AI guardrails, and advanced configuration options like our hyper-sensitive `--paranoid` threat-hunting mode.
+
+*Minimal Example (Running a single Sentinel):*
 ```yaml
 name: GitGalaxy Security Audit
 
@@ -135,7 +139,7 @@ jobs:
       - name: Run GitGalaxy Supply Chain Firewall
         uses: squid-protocol/gitgalaxy@main
         with:
-          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          tool: 'supply-chain-firewall' # View the Integration Guide for the full tool directory
           target: '.'
 ```
 
@@ -162,7 +166,7 @@ A mathematical x-ray suite for sanitizing mainframe monoliths. It safely neutral
 * **Proven Metric:** The Graveyard Reaper engine extracted over 6,700 lines of dead execution blocks and orphaned variables from the standard IBM CICS benchmark app in seconds.
 
 ### [Software Supply Chain Security & Pre-Commit Firewalls](gitgalaxy/tools/supply_chain_security/)
-Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline.
+Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline. **[Deploy directly via our GitHub Action](github-action-read-me.md).**
 
 ### [Zero-Trust SBOM Generation & Dependency Auditing](gitgalaxy/tools/compliance/)
 A Zero-Trust Software Bill of Materials (SBOM) generator. It refuses to blindly trust `package.json` or `requirements.txt` files, instead locating the physical dependencies on disk, mathematically verifying their entropy and linguistic identity, and generating strict CycloneDX 1.4 JSON reports.

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/README.md

@@ -1,7 +1,7 @@
 # GitGalaxy
 
 [![PyPI version](https://badge.fury.io/py/gitgalaxy.svg)](https://badge.fury.io/py/gitgalaxy)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 
 [![Engine](https://img.shields.io/badge/Engine-blAST-8A2BE2.svg)](#)
@@ -10,26 +10,25 @@
 [![Threat Hunting](https://img.shields.io/badge/Threat_Hunting-Behavioral-FF4500.svg)](#)
 [![Architecture](https://img.shields.io/badge/Architecture-Zero__Trust-teal.svg)](#)
 [![Coverage](https://img.shields.io/badge/Coverage-50%2B_Languages-00C957.svg)](#)
-[![Scale](https://img.shields.io/badge/Scale-100k%2B_LOC%2Fsec-00BFFF.svg)](#)
 
 [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)](https://pypi.org/project/gitgalaxy/)
 [![Airgap Ready](https://img.shields.io/badge/Security-Airgap_Ready-teal.svg)](#)
 [![Downloads](https://static.pepy.tech/badge/gitgalaxy)](https://pepy.tech/project/gitgalaxy)
-[![GitHub stars](https://img.shields.io/github/stars/squid-protocol/gitgalaxy?style=social)](https://github.com/squid-protocol/gitgalaxy/stargazers)
 
-### **AST-Free Static Analysis & Knowledge Graph Engine**
+### **Whole-Repository Understanding & DevSecOps Physics**
 
-The blAST (Bypassing LLMs and ASTs) engine is a custom-made knowledge graph engine that resolves repositories at the function level. It scores each function based on 50 unique metrics, rolls that data up to score the file, and finally summarizes the entire repository.
+Most tools analyze code line-by-line. GitGalaxy maps the entire architectural ecosystem. By tracking the exact flow of information across network dependencies, identifying local folder constraints, and natively recognizing 50+ languages—even mid-file—GitGalaxy provides a deterministic, 10,000-foot view of your software's physical architecture.
 
 ### Scanning Apollo-11 with the blAST Engine
 
 ![GitGalaxy CLI Scan](./docs/wiki/assets/apollo11_scan.gif)
 
-By utilizing a custom engine, we retain full control over the search space. We built it to be exceptionally fast, capable of assessing your entire repository without requiring compilable code—a fundamental limitation of standard Abstract Syntax Trees (ASTs). ASTs are great for finding missing commas and memory overflows, but they miss the forest for the trees when generating knowledge graphs. LLMs, on the other hand, suffer from hallucination during large context windows and yield probabilistic, fluctuating answers.
+**Why we built a custom physics engine:**
+Standard Abstract Syntax Trees (ASTs) are great for finding syntax errors, but they require compilable code and miss the forest for the trees when mapping massive-scale information flow. LLMs, on the other hand, suffer from severe hallucination when analyzing large context windows and yield probabilistic, fluctuating answers.
 
-The blAST engine solves this. Because all programming languages utilize keywords and functions, our engine treats code files as text, scanning for these structural anchors to build a deterministic 3D knowledge graph. It seamlessly handles mid-file language switching, assesses the architectural ratio of test files to logic, and extracts invaluable project structure data that ASTs ignore.
+The **blAST (Bypassing LLMs and ASTs) engine** solves this. It reads code as raw structural text, scanning for semantic anchors to build a deterministic 3D knowledge graph of your entire repository. It instantly calculates the ratio of test boundaries to core logic, maps network blast radiuses, and extracts the vital project structure data that rigid linters ignore.
 
-Every assumption our system makes has been abstracted into over 300 tunable variables. Think of GitGalaxy as a highly calibrated telescope. You can query the number of active API network nodes, isolate unique external imports, or highlight functions exhibiting extreme cognitive load—all adjusted via custom whitelists and blacklists to eliminate false-positive fatigue. Field-tested on over 1,000 repositories spanning 50+ languages and 250+ extensions, the engine comes equipped with smart defaults ready for immediate deployment.
+Think of GitGalaxy as a highly calibrated telescope for codebase risk. Every assumption the system makes is abstracted into over 300 tunable variables. You can query active API nodes, isolate supply chain threats, or highlight functions exhibiting extreme cognitive load—all adjusted via custom shields to eliminate false-positive fatigue. Field-tested on over 1,000 repositories, the engine comes equipped with enterprise-grade defaults ready for immediate CI/CD deployment.
 
 **Core Codebase Mapping Technology**
 * Bypasses LLMs and rigid ASTs.
@@ -66,6 +65,7 @@ GitGalaxy is backed by an academic-grade thesis detailing the equations powering
 **Installation & Usage**
 * Python-based: `pip install gitgalaxy`
 * CLI execution
+* CI/CD Integration: Native **[GitHub Action](github-action-read-me.md)** available for zero-trust DevSecOps pipelines.
 * Outputs forensic JSONs (optimized for AI-agent summary reports) and a native SQLite3 database for robust querying and storage.
 
 > **📖 Official Documentation:** Read the full technical specifications, architecture blueprints, and the Taxonomical Equivalence Map at **[squid-protocol.github.io/gitgalaxy](https://squid-protocol.github.io/gitgalaxy/)**.
@@ -93,8 +93,11 @@ galaxyscope /path/to/your/local/repo
 
 GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
 
-Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+**🚀 [View the Full GitHub Action Integration Guide](github-action-read-me.md)**
 
+Check out our comprehensive guide to set up the **"Golden Path" Pipeline** (Parallel Enforcement & Autonomous Reporting). It covers all available Sentinel tools, AI guardrails, and advanced configuration options like our hyper-sensitive `--paranoid` threat-hunting mode.
+
+*Minimal Example (Running a single Sentinel):*
 ```yaml
 name: GitGalaxy Security Audit
 
@@ -112,7 +115,7 @@ jobs:
       - name: Run GitGalaxy Supply Chain Firewall
         uses: squid-protocol/gitgalaxy@main
         with:
-          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          tool: 'supply-chain-firewall' # View the Integration Guide for the full tool directory
           target: '.'
 ```
 
@@ -139,7 +142,7 @@ A mathematical x-ray suite for sanitizing mainframe monoliths. It safely neutral
 * **Proven Metric:** The Graveyard Reaper engine extracted over 6,700 lines of dead execution blocks and orphaned variables from the standard IBM CICS benchmark app in seconds.
 
 ### [Software Supply Chain Security & Pre-Commit Firewalls](gitgalaxy/tools/supply_chain_security/)
-Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline.
+Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline. **[Deploy directly via our GitHub Action](github-action-read-me.md).**
 
 ### [Zero-Trust SBOM Generation & Dependency Auditing](gitgalaxy/tools/compliance/)
 A Zero-Trust Software Bill of Materials (SBOM) generator. It refuses to blindly trust `package.json` or `requirements.txt` files, instead locating the physical dependencies on disk, mathematically verifying their entropy and linguistic identity, and generating strict CycloneDX 1.4 JSON reports.

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/gitgalaxy/README.md

@@ -16,7 +16,7 @@ When you trigger the `galaxyscope` command, the data flows through these five ph
 * **`/physics/` (The Math):** The heuristics engine. Contains the [Signal Processor](https://squid-protocol.github.io/gitgalaxy/02-09-signal-processing/) and [Neural Auditor](https://squid-protocol.github.io/gitgalaxy/02-19-neural-auditor/), which apply GitGalaxy mathematics to score O(N) complexity, topological blast radius, and state flux without using ASTs.
 * **`/recorders/` (The Exporters):** The translation layer. Converts the internal state maps into highly relational [SQLite Databases](https://squid-protocol.github.io/gitgalaxy/02-21-record-keeper/), AI-agent JSON tickets, and the final 3D WebGPU payload.
 * **`/security/` (The Sentinel):** The zero-trust validation layer. Contains the [Security Lens](https://squid-protocol.github.io/gitgalaxy/02-06-security-lens/) responsible for intercepting embedded malware, hardcoded secrets, and logic bombs on the fly.
-* **`/tools/` (The Spokes):** The enterprise automation layer. Contains specialized controllers for CI/CD pipelines—like the [Supply Chain Firewall](https://squid-protocol.github.io/gitgalaxy/04-03-supply-chain-firewall/) and [PII Leak Hunter](https://squid-protocol.github.io/gitgalaxy/04-06-pii-leak-hunter/)—that consume the core engine's telemetry.
+* **`/tools/` (The Spokes):** The enterprise automation layer. Contains specialized controllers for CI/CD pipelines—like the [Supply Chain Firewall](https://squid-protocol.github.io/gitgalaxy/04-03-supply-chain-firewall/) and [PII Leak Hunter](https://squid-protocol.github.io/gitgalaxy/04-06-pii-leak-hunter/)—that consume the core engine's telemetry. **These specialized tools power our official [Zero-Trust DevSecOps GitHub Action](../github-action-read-me.md).**
 
 ---
 
@@ -74,4 +74,4 @@ To fully understand how GalaxyScope processes data, maps files, and applies risk
 * 📖 **[GalaxyScope CLI Reference](https://squid-protocol.github.io/gitgalaxy/01-02-galaxyscope-cli-reference/)** (Flags, outputs, and behaviors)
 * 📖 **[The Data Pipeline Overview](https://squid-protocol.github.io/gitgalaxy/02-01-pipeline-overview/)** (Step-by-step breakdown of the runtime)
 * 📖 **[Risk Exposures & Methodology](https://squid-protocol.github.io/gitgalaxy/08-01-methodology/)** (The math behind the heuristics)
-* 🪐 **[Return to the Main GitGalaxy Hub](https://github.com/squid-protocol/gitgalaxy)**
+* 🪐 **[Return to the Main GitGalaxy Hub](https://github.com/squid-protocol/gitgalaxy)**

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/gitgalaxy/core/guidestar_lens.py

@@ -8,6 +8,7 @@
 # of this project, or at https://polyformproject.org/licenses/noncommercial/1.0.0/
 # ==============================================================================
 import re
+import os
 import json
 import logging
 import fnmatch
@@ -68,6 +69,9 @@ class GuideStarLens:
         # Pattern Prior Map for .gitattributes (e.g., *.h)
         self.pattern_priors: Dict[str, Dict[str, Any]] = {}
 
+        # Spatial Documentation Map: Dict[directory_path, shield_strength_float]
+        self.doc_umbrellas: Dict[str, float] = {}
+
         self.logger.debug(f"GuideStar Lens Online | Sector: {self.root.name}")
 
     def align_telescope(self):
@@ -83,8 +87,11 @@ class GuideStarLens:
         # 3. The Evasion Scout (.gitignore)
         self._survey_gitignore()
 
+        # 4. The Knowledge Scout (Documentation Umbrellas)
+        self._survey_knowledge_anchors()
+
         self.logger.info(
-            f"GuideStar: Alignment complete. Cached {len(self.priors)} intent priors and {len(self.pattern_priors)} pattern rules."
+            f"GuideStar: Alignment complete. Cached {len(self.priors)} intent priors, {len(self.pattern_priors)} pattern rules, and {len(self.doc_umbrellas)} documentation shields."
         )
 
     def get_intent_status(self, path: Union[str, Path]) -> Tuple[bool, Dict[str, Any]]:
@@ -425,3 +432,63 @@ class GuideStarLens:
 
         except Exception as e:
             self.logger.debug(f"GuideStar: Evasion inspection failed for .gitignore: {e}")
+
+    # ==============================================================================
+    # KNOWLEDGE ANCHORS (The Documentation Scout)
+    # ==============================================================================
+
+    def _survey_knowledge_anchors(self):
+        """
+        Scans the repository for high-value architectural literature.
+        Calculates the physical mass of the documentation to project a
+        defensive umbrella shield over the surrounding directory.
+        """
+        anchor_patterns = {
+            "README.md",
+            "README.txt",
+            "README.rst",
+            "ARCHITECTURE.md",
+            "DESIGN.md",
+            "SPEC.md",
+            "swagger.json",
+            "openapi.yaml",
+            "openapi.json",
+            "CONTRIBUTING.md",
+            "USAGE.md",
+        }
+
+        for root_dir, dirs, files in os.walk(self.root):
+            dir_path = Path(root_dir)
+
+            # Skip known black holes to avoid wasting I/O
+            if any(part in self._gs_config.get("BLACK_HOLES", set()) for part in dir_path.parts):
+                continue
+
+            local_shield_mass = 0
+
+            for file in files:
+                if file in anchor_patterns or file.lower().endswith(".md"):
+                    file_path = dir_path / file
+                    try:
+                        # Fetch the physical byte size of the documentation
+                        size_bytes = file_path.stat().st_size
+
+                        # Ignore stubs (e.g., "# Project Title" and nothing else)
+                        if size_bytes > 150:
+                            local_shield_mass += size_bytes
+                    except OSError:
+                        pass
+
+            if local_shield_mass > 0:
+                # Calculate Shield Strength:
+                # 3000+ bytes of documentation provides a 100% (1.0) shield for this folder.
+                shield_strength = min(local_shield_mass / 3000.0, 1.0)
+
+                rel_dir = str(dir_path.relative_to(self.root)).replace("\\", "/")
+                if rel_dir == ".":
+                    rel_dir = "__root__"
+
+                self.doc_umbrellas[rel_dir] = round(shield_strength, 3)
+                self.logger.debug(
+                    f"GuideStar: Projected {shield_strength*100:.1f}% Documentation Shield over '{rel_dir}'"
+                )

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/gitgalaxy/galaxyscope.py

@@ -44,6 +44,13 @@ from gitgalaxy.recorders.llm_recorder import LLMRecorder
 from gitgalaxy.recorders.record_keeper import RecordKeeper
 from gitgalaxy.security.security_lens import SecurityLens
 from gitgalaxy.security.security_auditor import SecurityAuditor, ML_AVAILABLE
+
+try:
+    import yaml
+    HAS_PYYAML = True
+except ImportError:
+    HAS_PYYAML = False
+
 from gitgalaxy.tools.ai_guardrails.dev_agent_firewall import DevAgentFirewall
 from gitgalaxy.tools.ai_guardrails.ai_appsec_sensor import AIAppSecSensor
 from gitgalaxy.standards.gitgalaxy_config import (
@@ -396,6 +403,15 @@ def _process_file_worker(rel_path: str) -> Dict[str, Any]:
                 if is_file_profiling:
                     phase_times["5_Logic_Splicer"] = time.perf_counter() - t_splicer
 
+                # ---> INJECT THE KNOWLEDGE SHIELD <---
+                dir_path = str(Path(rel_path).parent).replace("\\", "/")
+                if dir_path == ".":
+                    dir_path = "__root__"
+
+                if "metadata" not in logic_data:
+                    logic_data["metadata"] = {}
+                logic_data["metadata"]["doc_umbrella"] = guidestar.doc_umbrellas.get(dir_path, 0.0)
+
                 logger.debug(f"[WORKER-TRACE] <<< EXITING SPLICER: {rel_path}")
 
             # --- Phase 5.5: Security Lens (Passive Observers) ---
@@ -615,7 +631,7 @@ class Orchestrator:
         start_time = time.time()
         logger.info(f"--- MISSION_IGNITION: {self.root.name} (v{self.version}) ---")
 
-        if not HAS_NETWORKX or not HAS_TIKTOKEN or not ML_AVAILABLE:
+        if not HAS_NETWORKX or not HAS_TIKTOKEN or not ML_AVAILABLE or not HAS_PYYAML:
             missing_libs = []
             if not HAS_NETWORKX:
                 missing_libs.append("networkx")
@@ -623,6 +639,8 @@ class Orchestrator:
                 missing_libs.append("tiktoken")
             if not ML_AVAILABLE:
                 missing_libs.extend(["xgboost", "pandas", "numpy"])
+            if not HAS_PYYAML:
+                missing_libs.append("pyyaml")
 
             pip_cmd = f"pip install {' '.join(missing_libs)}"
 
@@ -637,6 +655,8 @@ class Orchestrator:
                 logger.warning(" ┃  - tiktoken (Absolute Token Mass, Financial Read Cost)                  ┃")
             if not ML_AVAILABLE:
                 logger.warning(" ┃  - xgboost, pandas (Advanced ML Threat Inference & Taxonomy)            ┃")
+            if not HAS_PYYAML:
+                logger.warning(" ┃  - pyyaml (Required for parsing .yaml/.yml Swagger/OpenAPI specs)       ┃")
             logger.warning(" ┃                                                                         ┃")
             logger.warning(" ┃ To unlock absolute precision, run:                                      ┃")
             logger.warning(f" ┃    {pip_cmd}".ljust(75) + "┃")
@@ -741,8 +761,9 @@ class Orchestrator:
                     "networkx": not HAS_NETWORKX,
                     "tiktoken": not HAS_TIKTOKEN,
                     "xgboost": not ML_AVAILABLE,
+                    "pyyaml": not HAS_PYYAML,
                 },
-                "zero_dependency_mode": (not HAS_NETWORKX or not HAS_TIKTOKEN or not ML_AVAILABLE),
+                "zero_dependency_mode": (not HAS_NETWORKX or not HAS_TIKTOKEN or not ML_AVAILABLE or not HAS_PYYAML),
             }
 
             if "unparsable_files" not in summary:
@@ -1433,6 +1454,45 @@ class Orchestrator:
             self.used_tokens.update(meta.get("named_tokens", []))
         # ==============================================================
 
+        # ==============================================================
+        # ---> NEW: CALCULATE INSTRUCTIONAL DENSITY MULTIPLIERS <---
+        # Aggregate markdown heuristics to upgrade the doc_umbrella shields
+        # ==============================================================
+        instructional_multipliers = {}
+        for rel_path, meta in self.cryolink.items():
+            if meta.get("lang_id") == "markdown":
+                folder = str(Path(rel_path).parent).replace("\\", "/")
+                if folder == ".":
+                    folder = "__root__"
+
+                eq = meta.get("equations", {})
+
+                # Instructional Mass = Diagrams (10x) + Code Blocks (5x) + Headers (1x) + Links (0.5x)
+                instructional_mass = (
+                    (eq.get("lit_diagrams", 0) * 10.0)
+                    + (eq.get("lit_code_blocks", 0) * 5.0)
+                    + (eq.get("lit_headers", 0) * 1.0)
+                    + (eq.get("lit_links", 0) * 0.5)
+                )
+
+                # Base Multiplier is 1.0. High-quality docs can double the shield (2.0)
+                multiplier = 1.0 + min(instructional_mass / 50.0, 1.0)
+
+                if folder not in instructional_multipliers or multiplier > instructional_multipliers.get(folder, 0.0):
+                    instructional_multipliers[folder] = multiplier
+
+        # Apply the multiplier to the existing doc_umbrellas
+        for rel_path, meta in self.cryolink.items():
+            folder = str(Path(rel_path).parent).replace("\\", "/")
+            if folder == ".":
+                folder = "__root__"
+
+            if "metadata" in meta and "doc_umbrella" in meta["metadata"]:
+                base_shield = meta["metadata"]["doc_umbrella"]
+                mult = instructional_multipliers.get(folder, 1.0)
+                meta["metadata"]["doc_umbrella"] = min(base_shield * mult, 1.0)
+        # ==============================================================
+
         for rel_path, meta in self.cryolink.items():
             loc = meta.get("coding_loc", 0)
             total_loc += loc

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/gitgalaxy/physics/signal_processor.py

@@ -683,7 +683,21 @@ class SignalProcessor:
                 popularity=popularity,
             )
 
-            doc_score = self._calc_documentation(loc, doc_lines, equations, fc, irc, mp_map.get("doc", 1.0), functions)
+            # Calculate Silo Risk early for the Documentation N-Dimensional Math
+            silo_exposure = self._calculate_silo_risk(meta.get("authors", {}))
+
+            doc_score = self._calc_documentation(
+                loc,
+                doc_lines,
+                equations,
+                fc,
+                irc,
+                mp_map.get("doc", 1.0),
+                functions,
+                doc_umbrella=ghost_meta.get("doc_umbrella", 0.0),
+                popularity=popularity,
+                silo_exposure=silo_exposure,
+            )
             spec_score = self._calc_spec_alignment(equations, mp_map.get("spec", 1.0))
 
             bureaucracy_dampener = min(loc / 15.0, 1.0)
@@ -1481,35 +1495,60 @@ class SignalProcessor:
         irc: int,
         mp: float,
         functions: List[Dict[str, Any]] = None,
+        doc_umbrella: float = 0.0,
+        popularity: int = 0,
+        silo_exposure: float = 0.0,
     ) -> float:
         t = self.risk_tuning.get("documentation", {})
-        weighted_points = (
+
+        # 1. THE DEFENSE (The Knowledge Shield)
+        # GuideStar Umbrella projection: 1.0 shield = 50 lines of virtual documentation
+        umbrella_defense = doc_umbrella * 50.0
+
+        defense_hits = (
             (eq.get("doc", 0) * t.get("doc_weight", 1.0))
             + (eq.get("ownership", 0) * t.get("ownership_weight", 0.5))
             + (doc_loc * t.get("doc_loc_weight", 0.33))
-        )
+            + umbrella_defense
+        ) * fc
+
+        # 2. THE RISK (Kinetic Blindness)
+        kinetic_blindness = 0.0
+        api_exposure = eq.get("api", 0) * 2.0
 
-        # ---> THE BLIND COMPLEXITY PENALTY <---
-        # If the file contains incredibly heavy logic blocks or bad Big-O
-        # but the specific functions lack docstrings, the baseline coverage is a lie.
-        blind_penalty = 0.0
         if functions:
             for func in functions:
-                if (func.get("impact", 0) > 50 or func.get("big_o_depth", 1) >= 3) and not func.get("docstring"):
-                    blind_penalty += 15.0  # Flat 15% risk penalty per undocumented God Function
+                impact = func.get("impact", 0.0)
+                big_o = func.get("big_o_depth", 1)
+
+                # If a load-bearing or deeply nested block lacks a semantic tether
+                if (impact > 50.0 or big_o >= 3) and not func.get("docstring"):
+                    kinetic_blindness += 5.0 + (math.log1p(impact) * (big_o * 0.5))
+
+        # Add Implicit Risk Correction (Opacity Tax) to the risk
+        risk_hits = kinetic_blindness + api_exposure + irc
+
+        # 3. UNIVERSAL DENSITY EQUATION
+        net_exposure = max(0.0, risk_hits - (defense_hits / 2.0))
+        density = (net_exposure / max(loc, 1)) * 100.0
+
+        # 4. THE MULTIPLIERS (Blast Radius & Bus Factor)
+        # Undocumented code is exponentially more dangerous if it is highly
+        # integrated (popularity) or siloed to a single developer.
+        network_multiplier = 1.0 + (popularity / 10.0)
+        silo_multiplier = 1.0 + (silo_exposure / 200.0)
 
-        density = (weighted_points / max(loc, 1)) * 100.0
+        final_multiplier = network_multiplier * silo_multiplier * mp
 
-        if loc <= 2 and doc_loc == 0:
-            return 0
+        threshold = t.get("threshold_base", 10.0)
 
-        threshold = (t.get("threshold_base", 10.0) + irc) * mp
         try:
-            raw_risk = 100.0 / (1.0 + math.exp(t.get("sigmoid_slope", 0.2) * (density - threshold)))
+            # We use a negative slope because high density = high risk exposure
+            raw_risk = 100.0 / (1.0 + math.exp(-t.get("sigmoid_slope", 0.2) * (density - threshold)))
         except OverflowError:
-            raw_risk = 0.0 if density > threshold else 100.0
+            raw_risk = 100.0 if density > threshold else 0.0
 
-        return min((raw_risk * (2.0 - fc)) + blind_penalty, 100.0)
+        return min(raw_risk * final_multiplier, 100.0)
 
     def _calc_verification(
         self,

{gitgalaxy-2.2.1 → gitgalaxy-2.2.3}/gitgalaxy/recorders/record_keeper.py

@@ -94,6 +94,10 @@ class RecordKeeper:
             "telemetry": "def_telemetry",
             "ownership": "def_ownership",
             "spec_exposure": "def_spec_exposure",
+            "lit_code_blocks": "lit_code_blocks",
+            "lit_diagrams": "lit_diagrams",
+            "lit_headers": "lit_headers",
+            "lit_links": "lit_links",
             "sec_private_info": "threat_private_info",
             "sec_tainted_injection": "threat_tainted_injection",
             "sec_heat_triggers": "threat_obfuscated",