Feature/honest readmes

.github/workflows/deploy-docs.yml

@@ -27,7 +27,7 @@ jobs:
           git config user.email 41898282+github-actions[bot]@users.noreply.github.com
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 #
         with:
           python-version: "3.x"
 

.github/workflows/smoke-test.yml

@@ -26,7 +26,7 @@ jobs:
           persist-credentials: false
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 #
         with:
           python-version: ${{ matrix.python-version }}
 

action.yml

@@ -32,7 +32,7 @@ runs:
   using: "composite"
   steps:
     - name: Set up Python
-      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+      uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 #
       with:
         python-version: '3.10'
 

docs/gitgalaxy_architecture_brief.md

@@ -4,7 +4,7 @@
 ## 0. FORENSIC TRACEABILITY
 | Metadata | Value |
 |---|---|
-| **Engine** | `GitGalaxy Scope v6.2.0 (Delta Mode)` |
+| **Engine** | `GitGalaxy Scope (Delta Mode)` |
 | **Target Path** | `/home/runner/work/gitgalaxy/gitgalaxy` |
 | **Timestamp** | `2026-07-17T22:27:12.798136+00:00` |
 | **Scan Duration** | `6.34s` |

docs/wiki/02-08-the-detector.md

@@ -4,7 +4,7 @@
 >
 > Before the Splicer spends computational energy carving a logic stream, it performs a strict physical viability check. If a file enters the Splicer with a structural confidence score below `0.42`, it triggers the **Singularity Bypass**, safely relegating the file to "Dark Matter" (unparsed mass). Similarly, files explicitly verified as `markdown` or `plaintext` trigger a Prose Deflection, routing them entirely to "Ghost Mass."
 >
-> **The Ecosystem Gravity Override:** In the v6.3.0 Protocol, a critical exception was introduced for highly contested, declarative files—most notably C/C++ header files (`.h`). Pure-macro headers often lack the standard functional logic (braces, loops, branches) required to pass the 0.42 confidence floor naturally, causing vital architectural maps to vanish into Dark Matter.
+> **The Ecosystem Gravity Override:** In the Protocol, a critical exception was introduced for highly contested, declarative files—most notably C/C++ header files (`.h`). Pure-macro headers often lack the standard functional logic (braces, loops, branches) required to pass the 0.42 confidence floor naturally, causing vital architectural maps to vanish into Dark Matter.
 >
 > To solve this, the Splicer now implements an **Ecosystem Gravity Override**. If the upstream Language Lens previously utilized ecosystem mass to safely lock a file into a C-family orbit (`c`, `cpp`, or `objective-c`), the Splicer trusts that macro-level gravity. It artificially boosts the file's parsing confidence to `1.0`, ensuring these critical structural components are fully mapped and integrated into the final spatial cartography.
 
@@ -14,7 +14,7 @@ Strings and text literals are the natural enemies of structural parsers. A stray
 
 To prevent this "Quote Desynchronization," the Splicer utilizes the **Atomic Literal Shield**, an advanced pre-processing engine that securely masks disruptive text *without* altering the physical line counts or character indexing of the original file. This ensures the parsed logic perfectly maps 1:1 with the original source code.
 
-The v6.3.0 Protocol introduces heavily upgraded, language-aware shielding:
+The Protocol introduces heavily upgraded, language-aware shielding:
 
 * **Advanced Atomic Quotes:** The shield processes multi-character sequence markers strictly *before* single quotes. This surgical ordering correctly masks C++ Raw String Literals (e.g., `R"EOF(...)EOF"`) and Python Triple Quotes (`"""` / `'''`) without prematurely triggering on standard double quotes contained within them.
 * **Heredoc Isolation:** For scripting languages (Shell, Bash, Ruby, Perl, Elixir), standard regex is insufficient. The Splicer deploys a line-by-line state machine to isolate complex Heredoc logic (e.g., `<<-EOF`), safely blanking out massive text blocks that frequently contain rogue bash characters or unescaped quotes.
@@ -28,7 +28,7 @@ To maintain absolute mathematical integrity, the GitGalaxy Splicer strictly enfo
 By routing the pre-split streams into distinct analysis engines, GitGalaxy guarantees that structural metrics and human intent are measured independently.
 
 ### 1. Coding Analysis (The 51-Element Schema Guarantee)
-The `coding_analysis` engine is responsible for measuring the raw physical properties of the Active Matter (branches, IO operations, memory manipulations). In the v6.3.0 Protocol, this engine was upgraded to enforce absolute schema rigidity:
+The `coding_analysis` engine is responsible for measuring the raw physical properties of the Active Matter (branches, IO operations, memory manipulations). In the Protocol, this engine was upgraded to enforce absolute schema rigidity:
 * **Anti-Hallucination Binding:** The engine initializes its counting dictionary directly from the `UNIVERSAL_METRICS_SCHEMA`. If a custom language definition attempts to inject an unregistered rule, the Splicer actively ignores it.
 * **Deterministic Output:** This strict bounding guarantees that the resulting metrics dictionary is *exactly* 51 elements long, in the exact same order, every single time. This absolute consistency is vital for preventing schema drift and ensuring downstream risk algorithms (which rely on fixed-length arrays) never crash or misalign.
 * **Indentation Signatures:** Alongside regex matching, the coding analyzer also calculates the physical indentation density (Tabs vs. Spaces) to help downstream models identify the formatting culture of the logic block.
@@ -47,11 +47,11 @@ Even if a file is relegated to Dark Matter (failing the 0.42 structural confiden
 Because programming languages adhere to vastly different structural physics, a one-size-fits-all regex approach is mathematically impossible. To solve this, the `_function_slice` Master Dispatcher analyzes the language's lexical family and dynamically routes the Active Matter into one of five highly specialized extraction algorithms (Integration Modes).
 
 * **Mode A: Label-Based Scan (Legacy Species)** Used for legacy procedural languages like Assembly, AGC, and COBOL, which lack traditional scoping mechanisms. The Splicer uses a greedy, label-based scan (`_slice_by_labels`). It searches for functional start tags or labels and captures the entire block of logic until it encounters the next start tag or a definitive return instruction (e.g., `RET`, `GOBACK`, `END-PERFORM`), successfully isolating the structural satellite.
-* **Mode B: Recursive Scope Analysis (C-Family & Lisp)** The standard algorithm for languages relying on braces `{}` or parentheses `()`. The v6.3.0 Protocol heavily fortifies this brace-tracking engine against syntax desynchronization:
+* **Mode B: Recursive Scope Analysis (C-Family & Lisp)** The standard algorithm for languages relying on braces `{}` or parentheses `()`. The Protocol heavily fortifies this brace-tracking engine against syntax desynchronization:
   * **The Atomic Alternation Shield:** Evaluates double quotes, single quotes, and backticks simultaneously. This prevents complex string manipulation from confusing the scanner and falsely collapsing the closing braces.
   * **The C++ Preprocessor Brace Shield:** C/C++ macros frequently contain raw floating braces (e.g., `#else {`), which historically shattered scope stacks. The Splicer now implements a preprocessor shield that safely blinds the parser to duplicate or floating braces trapped inside dead structural branches (`#elif`, `#else`) and multi-line `#define` macros.
 * **Mode C: Density Stratification (Python & YAML)** Languages that rely on whitespace require a topographical approach. Using `_slice_by_indentation`, the engine identifies a structural igniter (like `def` or `class`) and calculates its base indentation level. It then scans forward, line-by-line, through the code's density. The scope block is naturally terminated the moment the engine encounters a line of active code that drops back to or below the base indentation level.
-* **Mode D: Semantic Handshake Stack (Keyword Scoping)** A major addition in the v6.3.0 Protocol, Mode D (`_slice_by_keywords`) is explicitly designed for non-brace scripting languages like Shell, Ruby, Lua, and Elixir.
+* **Mode D: Semantic Handshake Stack (Keyword Scoping)** A major addition in the Protocol, Mode D (`_slice_by_keywords`) is explicitly designed for non-brace scripting languages like Shell, Ruby, Lua, and Elixir.
   * Powered by the new `SemanticScopeRegistry`, this engine tracks structural depth via text keywords rather than symbols. It identifies specific *openers* (`if`, `def`, `case`) and *closers* (`fi`, `end`, `esac`) to manage the scope stack.
   * It includes specialized heuristics, such as the **Ruby Inline Modifier Guard**, which prevents single-line modifiers (e.g., `return true if x`) from falsely incrementing the depth stack.
 * **Mode E: Terminator Cleaving (Declarative Architectures)** Designed for declarative and query languages like SQL, Erlang, and Prolog (`_slice_by_terminator`). Rather than tracking nested scope, this mode monitors the stream for an **Igniter** keyword (e.g., `SELECT`, `CREATE`, or an Erlang function head) to start orbiting a new logic block. The block remains open until the engine detects the language's specific **Terminator** token (like a semicolon `;` or a period `.`), at which point the "guillotine drops," cleaving the statement into a measurable satellite.
@@ -68,7 +68,7 @@ The `_process_satellite_physics` method analyzes the raw string of the isolated
   (Highly linear functions branch at steep 90° angles; highly complex functions branch at wide 22.5° angles).
 * **Magnitude (`mag`):** The final physical mass of the block, calculated as: 
   $$\text{Magnitude} = (\text{branches} + 1) \times (\text{args} + 1) + (0.05 \times \text{loc})$$
-* *Note on Arguments:* The v6.3.0 Protocol upgraded the argument counter to recognize space-separated arguments, ensuring languages like Lisp, Scheme, and Shell calculate accurate magnitudes alongside comma-separated C-family languages.
+* *Note on Arguments:* The Protocol upgraded the argument counter to recognize space-separated arguments, ensuring languages like Lisp, Scheme, and Shell calculate accurate magnitudes alongside comma-separated C-family languages.
 
 ### 2. The Naming Shields
 Extracting a function name from raw text is notoriously difficult; naive regex frequently destroys complex C++ signatures or Objective-C methods. To guarantee pristine architectural labeling, GitGalaxy utilizes a gauntlet of **Naming Shields**:
@@ -83,7 +83,7 @@ Finally, the satellite is assigned a *texture* (its functional classification: `
 
 ## 2.3.5.E. The Cartographer: Fractal Fibonacci Positioning
 
-The Cartographer transforms flat file lists into a deterministic 3D star map. By applying procedurally generated patterns to digital architecture, it ensures the visual layout reflects the structural hierarchy and "gravitational" importance of the repository's components. Under the v6.3.0 Protocol, the engine utilizes a collision-aware packing algorithm to create organic, repeatable, and dense volumetric galaxies.
+The Cartographer transforms flat file lists into a deterministic 3D star map. By applying procedurally generated patterns to digital architecture, it ensures the visual layout reflects the structural hierarchy and "gravitational" importance of the repository's components. Under the Protocol, the engine utilizes a collision-aware packing algorithm to create organic, repeatable, and dense volumetric galaxies.
 
 ### 1. Sectorization & Hull Calculation (The Bounding Boxes)
 Before spatial coordinates are assigned, the engine must calculate the physical footprint of every folder (Constellation).

docs/wiki/02-12-audit-recorder.md

@@ -21,7 +21,7 @@ Here is the structural blueprint of the final output. This template exactly matc
 
 ```json
 {
-  "Audit Protocol": "GitGalaxy v6.3.2-Audit",
+  "Audit Protocol": "GitGalaxy",
   "1. Forensic Trail (Traceability)": {
     "Analysis Context": {
       "Engine Identity": "",

docs/wiki/cookbook/generate-llm-architecture-briefs.md

@@ -82,7 +82,7 @@ If you paste this exact text into an LLM like Claude 3.5 Sonnet or GPT-4o, it wi
 ## 0. FORENSIC TRACEABILITY
 | Metadata | Value |
 |---|---|
-| **Engine** | `GitGalaxy Scope v6.2.0 (Delta Mode)` |
+| **Engine** | `GitGalaxy Scope (Delta Mode)` |
 | **Target Path** | `/srv/storage_16tb/projects/gitgalaxy/data/abap-cleaner` |
 | **Scan Duration** | `2.38s` |
 | **Git Branch** | `main` |

gitgalaxy/README.md

@@ -8,6 +8,23 @@ Welcome to the internal source code for the **GitGalaxy Core Engine**.
 
 This directory contains the central orchestrator—**GalaxyScope**—alongside the core structural mechanics, lexical routing, and mathematical heuristics that power the entire DevSecOps ecosystem. If you are a developer looking to contribute, understand the data pipeline, or run the primary CLI, here is your architectural map.
 
+**Why we built a custom parsing engine:**
+Abstract Syntax Trees (ASTs) are excellent for catching syntax errors, but they require fully compilable code and a dedicated parser per language — both of which break down at the scale and polyglot mess of a real enterprise monolith. LLMs solve the language-coverage problem but introduce their own limits: context windows too small for million-line codebases, and probabilistic output that isn't the same twice.
+
+The **blAST (Bypassing LLMs and ASTs) engine** takes a third path, borrowed from a specific insight in computational biology: BLAST proved that a fast heuristic search — willing to accept a small, bounded margin of error — beats an exhaustive, mathematically perfect one once a database gets large enough. GitGalaxy applies that same tradeoff to source code. Instead of compiling a full parse tree, it scans raw text for **Structural Signatures**: bounded, ReDoS-safe regex patterns that mark the boundaries of functions, control flow, I/O, state mutation, and dozens of other structural and security-relevant behaviors — the same way a conserved sequence motif can imply a protein's function without anyone solving its 3D structure.
+
+The result is a deterministic knowledge graph of the repository, built without ever requiring the code to compile. It calculates the ratio of test code to core logic, maps each file's downstream "blast radius" through the dependency graph, and surfaces project-structure signal that line-by-line linters miss entirely. Per-file signal extraction runs in time linear to codebase size; repository-level graph metrics (centrality, community detection) use standard network-analysis algorithms with explicit sampling bounds on very large graphs.
+
+*(Note: raw structural signatures are just counts. The risk scores GitGalaxy reports are derived metrics — density-normalized against file size and weighted by network centrality — not raw hit counts.)*
+
+Think of GitGalaxy as a highly configurable macro-analyzer for codebase risk. Every assumption the system makes is exposed as one of 300+ tunable variables. You can query active API nodes, isolate supply chain threats, or highlight functions exhibiting extreme cognitive load — all adjusted via custom thresholds to reduce false-positive fatigue. Field-tested on over 1,000 repositories, the engine ships with enterprise-oriented defaults ready for CI/CD integration.
+
+* **Heuristic Structural Scanning:** Bypasses LLMs and rigid ASTs. Reads code as raw text without requiring it to compile.
+* **Deterministic Signal Extraction:** Maps code using a 97-point structural signal schema (I/O intent, state mutation, execution wrappers, security-relevant patterns, and more), rolled up into 19 aggregate risk categories.
+* **Taxonomical Classification:** These structural profiles let us cluster functions, files, and entire repositories into distinct architectural archetypes.
+* **Topological Cartography:** Builds a full dependency graph from imports and dynamic execution markers, with PageRank-style centrality and blast-radius scoring.
+* **No LLM in the Analysis Loop:** The core mapping and risk-scoring engine makes no calls to any language model — output is fully deterministic and reproducible run over run. (Some optional legacy-migration tools, like COBOL-to-Java translation, do use AI to translate isolated business logic; the analysis engine itself does not.)
+
 ### 🗺️ The Developer Map (How the Pipeline Flows)
 
 When you trigger the `galaxyscope` command, the data flows through these physical directories:

gitgalaxy/core/aperture.py

@@ -16,7 +16,7 @@
 
 # ==============================================================================
 # GitGalaxy Phase 0.1: Ingestion & Filtering (The Aperture Filter)
-# Strategy: v6.3.1 (Monolith Ceilings, Array Shields & Intent Overrides)
+# Strategy: (Monolith Ceilings, Array Shields & Intent Overrides)
 # Architecture: Path Evaluation -> Intent Resolution -> Content Validation
 # ==============================================================================
 

gitgalaxy/core/detector.py

@@ -46,7 +46,7 @@ def get_token_mass(text: str, deep_scan: bool = False) -> Optional[int]:
 
 # galaxyscope:ignore sec_high_risk_execution
 # GitGalaxy Phase 2.5 & 7.5: Logic Splicer & Topological Mapper
-# Strategy v6.3.0 Protocol: Fluid-State Counters, Language Sliding & Semantic Modes
+# Strategy Protocol: Fluid-State Counters, Language Sliding & Semantic Modes
 # ==============================================================================
 
 # galaxyscope:ignore sec_high_risk_execution
@@ -94,7 +94,7 @@ class FunctionNode(TypedDict, total=False):
 
 
 class LogicData(TypedDict, total=False):
-    """The standardized output schema for Strategy v6.2.0+ compliance."""
+    """The standardized output schema for Strategy compliance."""
 
     equations: Dict[str, int]
     functions: List[FunctionNode]

gitgalaxy/core/guidestar_lens.py

@@ -27,7 +27,7 @@
 
 # galaxyscope:ignore sec_io, llm_hooks
 # GitGalaxy Phase 0.5: Sector Intelligence (The GuideStar Lens)
-# Strategy: v6.3.0 (Deep Manifest Inspection & Evidence Hierarchy)
+# Strategy: (Deep Manifest Inspection & Evidence Hierarchy)
 # ==============================================================================
 
 # galaxyscope:ignore sec_io, llm_hooks

gitgalaxy/core/prism.py

@@ -14,7 +14,7 @@
 
 # ==============================================================================
 # GitGalaxy Phase 2: Payload & Surface Splitter (The Prism)
-# Strategy v6.2.0 Protocol: Safe Delimiter Extraction & Format Bypasses
+# Strategy Protocol: Safe Delimiter Extraction & Format Bypasses
 # ==============================================================================
 
 
@@ -56,7 +56,7 @@ class Prism:
     compilable code. To achieve polyglot velocity and prioritize functional intent across
     50+ languages, the Prism utilizes highly bounded, ReDoS-proof regular expressions.
 
-    PIPELINE RULES (v6.2.0):
+    PIPELINE RULES:
     1. Format Bypass: Respects 'undeterminable' files by passing them untouched to prevent pipeline stalls.
     2. Dynamic Regex Matrix: Pre-compiles standard comment rules at runtime based on the JSON configuration.
     3. O(1) String Literal Masking: Temporarily masks string literals to prevent the scanner from

gitgalaxy/galaxyscope.py

@@ -588,7 +588,7 @@ def __init__(
         self,
         target_input: Union[str, Path],
         config: Dict[str, Any],
-        version: str = "6.2.0",
+        version: str = "latest",
     ):
         self.config = config
         self.version = version