1. The Four-Tiered Truth Hierarchy & Autonomous Exporters
Per TSD-SCRIBE Addendum 29, 30 and 35, all forensic audit deliverables are fully packed inside this single, self-contained file (_DeScribe_Audit.html). No internet connection or cloud servers are needed. You can view, export, or print any artifact on demand from the Menu (☰ MENU) on the left or the Docked Bottom Bar.
| Deliverable | Who Is It For? | What Is It & When Do You Use It? |
Executive Scorecard _Tearsheet.html / PDF |
Founders, CTOs, Investors, M&A Buyers |
A clean, high-level 2-page diligence summary. Gives you the repository's overall letter credit rating, total hours required to clean up technical debt, and a ranked list of the Top 10 worst refactoring hotspots. Perfect for board meetings or investor due diligence. |
Autonomous Cockpit _DeScribe_Audit.html |
Lead Architects, Dev Teams, Tech Leads |
The interactive visual command center you are looking at right now. Lets you visually explore every folder, click to trace dependency wires, find circular deadlocks, inspect deep syntax metrics, and filter components via the interactive Workspace Tree. |
AI Navigation Manifest atlas.json |
AI Coding Agents (Claude, Cursor, Copilot) |
A machine-readable roadmap designed specifically for AI models. It maps out the exact public interfaces, file relationships, and boundary contracts across every folder. Feed this into your AI agent so it can refactor your codebase without getting lost or hallucinating non-existent files. |
Technical Blueprint _DeScribe_Document.md |
Staff Engineers, Compliance Auditors |
A complete, permanent Markdown ledger documenting every single file in the repository. Lists all mathematical metrology scores, cyclomatic nesting depths, detected code liabilities, and full file inventories. Ideal for repo documentation and compliance records. |
Evolution Ledger metrology_ledger.csv |
CI/CD Pipelines, Data Analysts |
A raw spreadsheet ledger that records cryptographic commit hashes, ARX integrity parity seals, and code scores over time. Plug this into your automated build pipeline to track whether code quality is improving or rotting with each pull request. |
Clean File Map file_map.txt |
Developers, Build Scripts |
A simple, plain-text tree breakdown of all indexed project files, sanitized and organized by their subsystem groupings. |
2. Cockpit Navigation, Controls & Interaction Mechanics
RESPONSIVE DUAL PUSH-DRAWERS
Clicking MENU on the top-left or INSPECTOR on the top-right slides the drawers in and out. Unlike floating popups that block your view, these panels actively push and squeeze the topology canvas inward. When both drawers are closed, the canvas expands to 100% full-screen width.
SINGLE LEFT-CLICK: TURN BOX ON
Clicking any card turns it ON (highlighted with maroon border) and loads its detailed metrics into the AST Inspector on the right. It does not draw any arrows. The rest of your canvas and all existing wires stay exactly as they are.
SINGLE RIGHT-CLICK: TURN BOX OFF
Right-clicking any card turns it OFF (fades it out to gray) and deletes any arrows connected to it. Right-clicking anywhere on the empty canvas background clears all active selections and restores the default view.
RAPID DOUBLE LEFT-CLICK: ARROWS ON
Double-clicking any card turns its dependency arrows ON. Red arrows point to files it imports, and amber arrows point from files that consume it. Any closed folder containers holding destination files will automatically expand so you can see where the arrows land.
RAPID DOUBLE RIGHT-CLICK: ARROWS OFF
Double-right-clicking a card turns OFF its arrows only. The card itself stays selected and active in the AST Inspector, but its arrows disappear cleanly from the canvas.
MULTI-CARD WORKFLOW CHAINING
You can turn on File A, then File B, then File C. Each file keeps its arrows visible simultaneously, allowing you to visually map and inspect custom multi-step data pipelines across your entire project.
CTRL + CLICK: CHAIN REACTION SWEEPS
Ctrl + Left-Click traces the entire downstream family tree (File A → B → C → D...), turns all those cards ON, and expands their folders. Ctrl + Right-Click turns OFF and grays out the entire downstream family tree in a single click.
SUBSYSTEM [RESET] BUTTON
Found in every folder box header. Clicking RESET ensures all files in that grouping are visible on the canvas, removes any active arrows, and sets all cards in that folder to grayed out, giving you a fresh slate.
FILE RATIO & DYNAMIC HIDDEN BADGES
Each folder header shows its file count (e.g., 33/33 files). If any files in that folder are hidden (unchecked in the Workspace Tree), an alert badge (e.g., 2 hidden) appears so you immediately know why a file isn't visible on the canvas.
INTERACTIVE LIABILITIES BADGE
Clicking the X liabilities badge in a folder header automatically opens the box and lights up all cards carrying code defects while dimming healthy files for instant triage.
DOCKED BOTTOM CONTROL TOOLBAR
The floating toolbar at the bottom gives you 1-click access to zoom in/out, centering the camera, fitting the whole map to screen, switching view modes (Macro, Expand All, Code Only, Hotspots), and clearing selections.
1-CLICK OFFLINE SCREENSHOT (PNG)
Click 📸 SNAPSHOT on the bottom bar to download a high-resolution PNG image of your custom card layout and active arrows directly to your machine. 100% offline with zero external cloud dependencies.
CIRCULAR LOOP BEAD-CHAINS
When two files import each other in a circle ($A \leftrightarrow B$), DeScribe draws a distinctive violet beaded loop with round dot markers on both ends to highlight the mutual deadlock.
WORKSPACE TREE & GHOST STUBS
Use the WORKSPACE TREE tab in the right sidebar to search or uncheck folders. If an arrow points to a file you unchecked, a slate-gray "Ghost Stub" appears in the inspector with a [+] button to quickly pop it back onto the canvas.
3. Plain-English Metrology Glossary
| Metric Coordinate | What It Measures & What It Means in Simple English |
Maintainability Index (MI) Range: 0.0 to 100.0 |
The architectural credit rating of your code. Think of it like a vehicle safety rating or credit score:
- 85 – 100 (Clean / Green): Well-structured, easy to read, easy to modify, low risk of bugs.
- 65 – 84 (Moderate Debt / Amber): Workable code that needs some routine hygiene and cleaning.
- 40 – 64 (High Risk / Orange): Structural knots and spaghetti code. Touching this code often breaks other things.
- Below 40 (Critical Debt / Red): Danger zone. Bloated files doing too many things at once, highly prone to crash regressions.
|
Remediation Effort Calculated in Hours |
The estimated real-world engineering hours required to refactor, untangle, and clean up the file to bring it up to a solid, healthy 85.0 MI score. |
Length Enthalpy (H) Code Mass & Bloat |
Measures whether code is lean or bloated. High enthalpy means the file is stuffed with copy-pasted logic, repetitive boilerplate, and excessive bulk that could be streamlined. |
Shannon Entropy (S) Chaos & Unpredictability |
Measures how scattered and unpredictable the code is. High entropy means a file mixes too many unrelated concepts together, making it difficult for both human developers and AI assistants to follow the logic without making mistakes. |
Syntax Strain (σ) Mental Fatigue & Nesting |
Measures cognitive load and deep nesting. When code has if inside for inside while inside switch past 5 or 6 levels deep, the strain spikes. High strain means high developer brain fatigue and a high likelihood of logic slip-ups. |
Privilege Rings (0 to 3) Architectural Defense Layers |
Separation of concerns across 4 security rings:
- Ring 0 (Persistence): Database tables, raw disk storage, core data models.
- Ring 1 (Domain Core): Core business logic, rules, and mathematical engines.
- Ring 2 (Routing & Controllers): API endpoints, request dispatchers, controllers.
- Ring 3 (Peripheral & UI): Web interfaces, buttons, client views, utility scripts.
|
Privilege Inversion Architectural Layer Violation |
A boundary violation where an outer layer skips middle layers (for example, a Ring 3 button directly modifying a Ring 0 database record without passing through Ring 1 business logic). |
4. Architectural Liabilities & Defect Directory
| Liability Flag | Plain-English Meaning & Recommended Action |
| God Component / Monolith |
A file that has grown too massive and taken over too many responsibilities. Action: Break it apart into smaller, single-purpose helper modules. |
| Deep Cyclomatic Nesting |
Code buried deep inside nested loops and conditional statements (maze code). Action: Use early returns (guard clauses) and extract sub-functions to flatten the logic. |
| Circular Dependency Loop |
File A imports File B, but File B also imports File A. This creates mutual locks that confuse compilers, bundlers, and AI models. Action: Move the shared data types or functions into a neutral third file. |
| Passive Asset Classification |
Files that do not contain executable code (such as JSON schemas, Markdown specs, icons, images, or documentation). DeScribe marks these with a clean gray badge so you know they carry zero technical debt. |
5. The Calculator Principle (JUS-BRAND-v5.2.0)
DeScribe does not judge, lecture, or enforce personal style preferences. Like an industrial digital caliper, optical comparator, or medical X-ray machine, it reads raw code on disk via read-only handles (O_RDONLY) and reports mathematical ground truth. It runs completely offline, uses zero telemetry, requires no cloud servers or subscriptions, and produces verified, air-gapped forensic engineering deliverables.