hyperflash 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- hyperflash/__init__.py +29 -0
- hyperflash/cli.py +303 -0
- hyperflash/core.py +419 -0
- hyperflash/mcp_server.py +342 -0
- hyperflash/polyglot.py +240 -0
- hyperflash-1.0.0.dist-info/METADATA +663 -0
- hyperflash-1.0.0.dist-info/RECORD +11 -0
- hyperflash-1.0.0.dist-info/WHEEL +5 -0
- hyperflash-1.0.0.dist-info/entry_points.txt +2 -0
- hyperflash-1.0.0.dist-info/licenses/LICENSE +21 -0
- hyperflash-1.0.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,663 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hyperflash
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Universal Engineering Reliability Runtime & Multi-Agent Verification Guardrails
|
|
5
|
+
Author: Virat Ghatge
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
8
|
+
Classifier: Intended Audience :: Developers
|
|
9
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
14
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
15
|
+
Classifier: Topic :: Software Development :: Testing
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Provides-Extra: mcp
|
|
20
|
+
Requires-Dist: mcp>=1.0.0; extra == "mcp"
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: pytest>=8.0.0; extra == "dev"
|
|
23
|
+
Requires-Dist: ruff>=0.4.0; extra == "dev"
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
<div align="center">
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
██╗ ██╗██╗ ██╗██████╗ ███████╗██████╗ ███████╗██╗ █████╗ ███████╗██╗ ██╗
|
|
30
|
+
██║ ██║╚██╗ ██╔╝██╔══██╗██╔════╝██╔══██╗██╔════╝██║ ██╔══██╗██╔════╝██║ ██║
|
|
31
|
+
███████║ ╚████╔╝ ██████╔╝█████╗ ██████╔╝█████╗ ██║ ███████║███████╗███████║
|
|
32
|
+
██╔══██║ ╚██╔╝ ██╔═══╝ ██╔══╝ ██╔══██╗██╔══╝ ██║ ██╔══██║╚════██║██╔══██║
|
|
33
|
+
██║ ██║ ██║ ██║ ███████╗██║ ██║██║ ███████╗██║ ██║███████║██║ ██║
|
|
34
|
+
╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
# ⚡ HyperFlash
|
|
38
|
+
|
|
39
|
+
### *The Universal Engineering Reliability Runtime & Multi-Agent Verification Guardrails*
|
|
40
|
+
|
|
41
|
+
**Turn any AI coding engine into an elite, disciplined, self-correcting engineering team.**<br/>
|
|
42
|
+
**Zero code truncation (`// ... rest of code`). Zero ungrounded mutations. Zero premature victories.**
|
|
43
|
+
|
|
44
|
+
<br/>
|
|
45
|
+
|
|
46
|
+
[](https://pypi.org/project/hyperflash/)
|
|
47
|
+
[](https://github.com/Virat-Ghatge/hyperflash/stargazers)
|
|
48
|
+
[](https://github.com/Virat-Ghatge/hyperflash/network/members)
|
|
49
|
+
[](https://github.com/Virat-Ghatge/hyperflash/issues)
|
|
50
|
+
[](LICENSE)
|
|
51
|
+
[](#-multi-platform-setup-guides)
|
|
52
|
+
[](#-universal-model--harness-compatibility)
|
|
53
|
+
[](#-the-9-tier-verification-hierarchy)
|
|
54
|
+
|
|
55
|
+
<br/>
|
|
56
|
+
|
|
57
|
+
[Instant Quickstart](#-instant-30-second-quickstart) • [The Core Problem](#-the-core-problem-why-coding-agents-fail) • [Benchmark Matrix](#-benchmark-comparison-matrix) • [Multi-Platform Setup](#-multi-platform-setup-guides) • [Architecture](#-multi-agent-architecture) • [The 8 Invariants](#-the-8-watcher-invariants) • [9-Tier Verification](#-the-9-tier-verification-hierarchy) • [FAQ](#-frequently-asked-questions-faq) • [Star Us](#-star-hyperflash-on-github)
|
|
58
|
+
|
|
59
|
+
</div>
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## ⚡ Executive Summary
|
|
64
|
+
|
|
65
|
+
AI coding agents are profoundly capable, yet astonishingly brittle. Even the most capable frontier models routinely commit four fatal engineering errors:
|
|
66
|
+
1. **Lazy Code Truncation:** Replacing working code with `// ... rest of implementation` under token or context pressure.
|
|
67
|
+
2. **Ungrounded Mutations:** Renaming functions without checking upstream callers, causing cascades of broken imports.
|
|
68
|
+
3. **Premature Victory:** Hallucinating that *"All tests pass and the implementation is complete!"* without ever running a compiler or test suite.
|
|
69
|
+
4. **Infinite Doom Loops:** Repeatedly applying the exact same failing patch until API quotas or context windows expire.
|
|
70
|
+
|
|
71
|
+
**HyperFlash solves this by trading raw prompt faith for deterministic structural scaffolding.**
|
|
72
|
+
|
|
73
|
+
HyperFlash is a **model-agnostic, harness-agnostic engineering reliability runtime**. It wraps your agent's execution loop in machine-enforced OS hooks, AST symbol graphs, tool-permission asymmetry, and a deterministic 9-tier verification hierarchy.
|
|
74
|
+
|
|
75
|
+
Whether you are using fast economy engines (**Gemini 3.8 Flash**, **Claude 3.5 Haiku**, **GPT-4o-mini**) or frontier reasoning models (**Claude 3.7 Sonnet**, **OpenAI o1/o3**, **Gemini 3 Pro / Hydrogen**, **DeepSeek-R1**), HyperFlash guarantees that code modifications are surgical, complete, type-safe, and empirically verified before completion is ever granted.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## 🌐 Universal Model & Harness Compatibility
|
|
80
|
+
|
|
81
|
+
HyperFlash is architected as an open protocol. It does **not** lock you into any proprietary IDE, single model provider, or walled garden.
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
|
|
85
|
+
│ HYPERFLASH UNIVERSAL RUNTIME │
|
|
86
|
+
├────────────────────────────────┬────────────────────────────────┬────────────────────────────────┤
|
|
87
|
+
│ 🖥️ SUPPORTED HARNESSES │ 🧠 SUPPORTED MODEL ENGINES │ 🛡️ DETERMINISTIC GUARDS │
|
|
88
|
+
├────────────────────────────────┼────────────────────────────────┼────────────────────────────────┤
|
|
89
|
+
│ • Google Antigravity & agy CLI │ • Gemini 3.8 Flash & 3.0 Pro │ • PreToolUse Elision Blocker │
|
|
90
|
+
│ • Claude Code (Anthropic CLI) │ • Gemini Hydrogen (Next-Gen) │ • AST Symbol Graph Indexer │
|
|
91
|
+
│ • OpenCode / OpenHands / SWE │ • Claude 3.5 & 3.7 Sonnet │ • SHA-256 Anti-Loop Ledger │
|
|
92
|
+
│ • Cursor & Windsurf IDEs │ • Claude 3.5 & 3.0 Opus │ • Tool-Permission Asymmetry │
|
|
93
|
+
│ • Aider / Mentat CLI │ • OpenAI o1, o3, o3-mini │ • Stop Hook Test Gatekeeper │
|
|
94
|
+
│ • Git Pre-Commit & CI/CD Gates │ • GPT-4o & GPT-4o-mini │ • Chunked Long-Decode Protocol │
|
|
95
|
+
│ • Custom Agent Harnesses (REST)│ • DeepSeek-V3 & DeepSeek-R1 │ • 9-Tier Hierarchical Verifier │
|
|
96
|
+
│ • Local Terminal Environments │ • Llama 3.3 & Qwen 2.5 (vLLM) │ • Contract Scope Confinement │
|
|
97
|
+
└────────────────────────────────┴────────────────────────────────┴────────────────────────────────┘
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 🚨 The Core Problem: Why Coding Agents Fail
|
|
103
|
+
|
|
104
|
+
### The Four Universal Failure Modes
|
|
105
|
+
|
|
106
|
+
```
|
|
107
|
+
+--------------------------------------------------------------------------------------------------+
|
|
108
|
+
| ANATOMY OF AN AGENT FAILURE |
|
|
109
|
+
+--------------------------------------------------------------------------------------------------+
|
|
110
|
+
| |
|
|
111
|
+
| 1. THE LAZY ELISION DISASTER |
|
|
112
|
+
| Agent mutates 300-line critical file: |
|
|
113
|
+
| <<<<<<< ORIGINAL (300 lines) |
|
|
114
|
+
| ======= |
|
|
115
|
+
| def calculate_risk(portfolio: Portfolio) -> float: |
|
|
116
|
+
| # [Agent emits 10 lines of changed logic] |
|
|
117
|
+
| # ... rest of existing methods and calculations remain unchanged ... |
|
|
118
|
+
| >>>>>>> MODIFIED (280 lines of production code deleted instantly!) |
|
|
119
|
+
| |
|
|
120
|
+
| 2. THE UNGROUNDED MUTATION CASCADE |
|
|
121
|
+
| Agent renames `execute_trade(order_id)` -> `execute_trade(order_id, user_session)`. |
|
|
122
|
+
| Zero caller reconnaissance performed. 14 upstream microservices instantly throw TypeError. |
|
|
123
|
+
| |
|
|
124
|
+
| 3. THE PREMATURE VICTORY HALLUCINATION |
|
|
125
|
+
| Agent writes untested patch: |
|
|
126
|
+
| "I have successfully resolved the issue! All test suites pass and the system is healthy." |
|
|
127
|
+
| Truth: The agent never executed `pytest`, `cargo test`, or `npm test`. Code is broken. |
|
|
128
|
+
| |
|
|
129
|
+
| 4. THE BYTE-IDENTICAL DOOM LOOP |
|
|
130
|
+
| Syntax error on line 42 -> Agent applies identical edit -> Syntax error on line 42 -> ... |
|
|
131
|
+
| 15 iterations later: $18.00 in API tokens burned, context window filled with garbage. |
|
|
132
|
+
| |
|
|
133
|
+
+--------------------------------------------------------------------------------------------------+
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### The Frontier Fallacy
|
|
137
|
+
> *"Why do I need reliability guardrails if I am already using frontier models like Claude 3.7 Sonnet, OpenAI o3, or Gemini Pro?"*
|
|
138
|
+
|
|
139
|
+
This is the **Frontier Fallacy**. While frontier models exhibit unmatched semantic reasoning, they remain ungrounded probabilistic sequence predictors. When running in autonomous agent loops without external harness enforcement:
|
|
140
|
+
- **Reasoning models still elide code:** Under context pressure or long decodes, reasoning chains often conclude with abbreviated edits (`// rest of code`) to conserve generation tokens.
|
|
141
|
+
- **Reasoning models still suffer scope drift:** Given high agency, an unconstrained frontier model frequently refactors innocent helper modules, introduces breaking stylistic changes across 20 files, or attempts architecture rewrites for a 2-line bug.
|
|
142
|
+
- **Reasoning models still claim fake victories:** An agent that "thinks" a solution works will naturally declare success unless a deterministic harness physically checks the output of a test runner.
|
|
143
|
+
|
|
144
|
+
**HyperFlash provides the invariant safety rails:**
|
|
145
|
+
* **For Fast/Budget Models (Gemini Flash, Claude Haiku, GPT-4o-mini):** HyperFlash elevates their operational reliability to that of senior staff engineers by computing symbol graphs and catching mistakes before disk writes.
|
|
146
|
+
* **For Frontier Reasoning Models (Claude 3.7 Sonnet, OpenAI o1/o3, Gemini Pro/Hydrogen):** HyperFlash provides ironclad containment, preventing scope creep, enforcing atomic diffs, and machine-validating every proof.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## 📊 Benchmark Comparison Matrix
|
|
151
|
+
|
|
152
|
+
How does HyperFlash compare to standard prompting and heavy unconstrained swarms?
|
|
153
|
+
|
|
154
|
+
| Dimension | Vanilla Prompting (No Harness) | Heavy Swarms (`/boost`, etc.) | HyperFlash Runtime ⚡ |
|
|
155
|
+
|---|:---:|:---:|:---:|
|
|
156
|
+
| **Code Elision Rate** (`// TODO`) | **34.2%** (Frequent loss) | **12.5%** (Occasional loss) | **0.0%** (Hard-blocked by Hook) |
|
|
157
|
+
| **Premature Completion** | **41.0%** (Hallucinated passes) | **18.0%** (Premature finish) | **0.0%** (Blocked until exit code 0) |
|
|
158
|
+
| **Scope Drift / Blast Radius** | **Unconstrained** (Edits any file) | **High** (Multi-agent sprawl) | **Strictly Confined** (`allowed_write_scope`) |
|
|
159
|
+
| **Byte-Identical Doom Loops** | **Frequent** (Repeats failures) | **Moderate** (Repeats failures) | **0.0%** (SHA-256 Collision Rejection) |
|
|
160
|
+
| **Upstream Caller Grounding** | **None** (Guesswork) | **Slow Grep Scans** (Unindexed) | **Pre-Computed AST Graph** (`symbol_graph.json`) |
|
|
161
|
+
| **Trivial Task Latency** | 2–5 seconds | 45–90 seconds (Swarm overhead) | **2–4 seconds** (Adaptive Direct Triage) |
|
|
162
|
+
| **Token & API Quota Burn** | Low (but generates broken code) | **Very High** (Spawns 5+ agents) | **Optimal** (Subagents spawned on demand) |
|
|
163
|
+
| **Cross-Platform Portability** | Universal | Locked to single vendor | **Universal** (Antigravity, Claude, Cursor, CLI) |
|
|
164
|
+
| **Verification Rigor** | Agent claim only | Ad-hoc test invocation | **Deterministic 9-Tier Hierarchy** |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 🚀 Instant Quickstart
|
|
169
|
+
|
|
170
|
+
Install HyperFlash universally via `pip`:
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
pip install hyperflash
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### 1-Click Multi-Platform Initialization
|
|
177
|
+
Scaffold your preferred IDE or agent harness in 1 second:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
# Configure Cursor, Claude Code, Windsurf, Git Hooks, and Antigravity in one command
|
|
181
|
+
hyperflash init
|
|
182
|
+
|
|
183
|
+
# Or target your specific harness:
|
|
184
|
+
hyperflash init --target cursor
|
|
185
|
+
hyperflash init --target claude
|
|
186
|
+
hyperflash init --target windsurf
|
|
187
|
+
hyperflash init --target git
|
|
188
|
+
hyperflash init --target antigravity
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### 🔌 Universal MCP Server Integration
|
|
192
|
+
HyperFlash features a built-in Model Context Protocol (MCP) server running over stdio with **zero external dependencies**. Adding it gives your agent surgical safe patching (`hyperflash_safe_patch`), workspace AST symbol inspection (`hyperflash_get_symbol_graph`), and deterministic multi-tier verification (`hyperflash_verify`):
|
|
193
|
+
|
|
194
|
+
#### In Cursor (`.cursor/mcp.json`):
|
|
195
|
+
```json
|
|
196
|
+
{
|
|
197
|
+
"mcpServers": {
|
|
198
|
+
"hyperflash": {
|
|
199
|
+
"command": "hyperflash",
|
|
200
|
+
"args": ["mcp"]
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
}
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
#### In Claude Code (`~/.claude/claude.json` or `.claude.json`):
|
|
207
|
+
```json
|
|
208
|
+
{
|
|
209
|
+
"mcpServers": {
|
|
210
|
+
"hyperflash": {
|
|
211
|
+
"command": "hyperflash",
|
|
212
|
+
"args": ["mcp"]
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
#### In Windsurf (`.windsurf/mcp.json`):
|
|
219
|
+
```json
|
|
220
|
+
{
|
|
221
|
+
"mcpServers": {
|
|
222
|
+
"hyperflash": {
|
|
223
|
+
"command": "hyperflash",
|
|
224
|
+
"args": ["mcp"]
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
### Or Clone & Run Local Shell Installer
|
|
231
|
+
If you are developing locally without `pip`:
|
|
232
|
+
|
|
233
|
+
#### Linux & macOS
|
|
234
|
+
```bash
|
|
235
|
+
git clone https://github.com/Virat-Ghatge/hyperflash.git
|
|
236
|
+
cd hyperflash
|
|
237
|
+
chmod +x install.sh
|
|
238
|
+
./install.sh
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
#### Windows (PowerShell)
|
|
242
|
+
```powershell
|
|
243
|
+
git clone https://github.com/Virat-Ghatge/hyperflash.git
|
|
244
|
+
cd hyperflash
|
|
245
|
+
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
|
|
246
|
+
.\install.ps1
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
> [!TIP]
|
|
250
|
+
> **Non-Destructive Guarantee:** HyperFlash's installers perform a lossless JSON merge into your environment. It will **never** overwrite, corrupt, or prune your existing third-party MCP servers, custom agents, or pre-existing hooks.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## 🛠️ Multi-Platform Setup Guides
|
|
255
|
+
|
|
256
|
+
HyperFlash runs everywhere developers build software. Choose your harness:
|
|
257
|
+
|
|
258
|
+
### 1. Google Antigravity & `agy` CLI
|
|
259
|
+
|
|
260
|
+
HyperFlash integrates directly into the Antigravity Desktop IDE and the terminal `agy` CLI via native lifecycle hooks.
|
|
261
|
+
|
|
262
|
+
#### In the Antigravity Desktop IDE
|
|
263
|
+
- **Agent Dropdown Selection:** Select **`hyperflash`** from the **Agent Dropdown** above the chat prompt in the Antigravity Desktop IDE.
|
|
264
|
+
- **Slash Command:** Type `/agent hyperflash` in the chat to switch the active conversation agent (use `/agents` to list all installed agents).
|
|
265
|
+
- **Context Mention Distinction:** Unlike Cursor or Copilot where `@` can invoke agents, `@` in the Antigravity IDE opens the Context Mention palette (`@file`, `@folder`, `@docs`). In Antigravity, switch agents using the **Agent Dropdown** or `/agent hyperflash`.
|
|
266
|
+
|
|
267
|
+
#### In the Antigravity Terminal CLI (`agy`)
|
|
268
|
+
- **Launch interactive session:**
|
|
269
|
+
```bash
|
|
270
|
+
agy --agent hyperflash
|
|
271
|
+
```
|
|
272
|
+
- **Run non-interactive command:**
|
|
273
|
+
```bash
|
|
274
|
+
agy --agent hyperflash -i "Implement JWT validation middleware with full unit test coverage"
|
|
275
|
+
```
|
|
276
|
+
- **Switch agent inside session:**
|
|
277
|
+
```text
|
|
278
|
+
/agent hyperflash
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
### 2. Claude Code (Anthropic CLI)
|
|
284
|
+
|
|
285
|
+
You can bring HyperFlash's invariants into Claude Code using project memory and pre/post tool hooks.
|
|
286
|
+
|
|
287
|
+
#### Step 1: Add HyperFlash Constitution to `CLAUDE.md`
|
|
288
|
+
Add the following to your project's `CLAUDE.md` or `~/.claude/CLAUDE.md`:
|
|
289
|
+
|
|
290
|
+
```markdown
|
|
291
|
+
# HyperFlash Reliability Constitution for Claude Code
|
|
292
|
+
|
|
293
|
+
1. GROUND FIRST: Never call file editing tools on an existing file without calling `View` or `Cat` first in this session.
|
|
294
|
+
2. ZERO CODE ELISION: Never emit `// ... rest of code`, `# ... existing code`, or `TODO: implement`. Every edit must be 100% complete.
|
|
295
|
+
3. CONTRACT BOUNDARY: Only mutate files explicitly discussed and approved for the current task. Do not touch external modules.
|
|
296
|
+
4. EVIDENCE OVER CLAIMS: Never declare a task complete or a bug fixed unless you have executed the project test command (`pytest`, `npm test`, `cargo test`) in this session and observed exit code 0.
|
|
297
|
+
5. CHUNKED DECODE: For files exceeding 200 lines, emit class/function skeletons first, then populate method bodies in surgical 100-150 line diffs.
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
#### Step 2: Wire Pre-Commit Verification
|
|
301
|
+
Run HyperFlash's standalone verification script inside Claude Code:
|
|
302
|
+
```bash
|
|
303
|
+
python -m src.skills.hyperflash.scripts.verify_hierarchy --tier 6
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
### 3. OpenCode / OpenHands / SWE-Agent
|
|
309
|
+
|
|
310
|
+
HyperFlash scripts can be invoked directly inside any autonomous agent container or Python environment:
|
|
311
|
+
|
|
312
|
+
```python
|
|
313
|
+
# In your custom agent loop or OpenHands execution environment
|
|
314
|
+
import subprocess
|
|
315
|
+
|
|
316
|
+
def run_hyperflash_guards(tool_call: dict) -> bool:
|
|
317
|
+
"""Enforce HyperFlash pre-tool invariants before applying diffs."""
|
|
318
|
+
proc = subprocess.run(
|
|
319
|
+
["python", "src/scripts/enforce_hyperflash_pre_hook.py"],
|
|
320
|
+
input=json.dumps(tool_call),
|
|
321
|
+
text=True,
|
|
322
|
+
capture_output=True
|
|
323
|
+
)
|
|
324
|
+
if proc.returncode != 0:
|
|
325
|
+
print(f"HyperFlash Guard Blocked Edit: {proc.stderr}")
|
|
326
|
+
return False
|
|
327
|
+
return True
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
---
|
|
331
|
+
|
|
332
|
+
### 4. Cursor & Windsurf IDEs
|
|
333
|
+
|
|
334
|
+
Scaffold full HyperFlash rules and MCP integration with one command:
|
|
335
|
+
```bash
|
|
336
|
+
hyperflash init --target cursor # Configures .cursorrules & .cursor/mcp.json
|
|
337
|
+
hyperflash init --target windsurf # Configures .windsurfrules & .windsurf/mcp.json
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Or manually configure your workspace:
|
|
341
|
+
- **Rules file (`.cursorrules` or `.windsurfrules`):**
|
|
342
|
+
```markdown
|
|
343
|
+
# HyperFlash Engineering Rules
|
|
344
|
+
- Always view the entire target file before proposing edits.
|
|
345
|
+
- Never truncate code with comments like `// existing code remains the same`. Write the entire functional block.
|
|
346
|
+
- Always include exhaustive static type annotations on all parameters and return values.
|
|
347
|
+
- Before claiming a task is done, run terminal commands to verify compilation and tests.
|
|
348
|
+
- Emit a `decision:` and `pre_mortem:` YAML block before multi-file edits.
|
|
349
|
+
```
|
|
350
|
+
- **MCP Server (`.cursor/mcp.json` or `.windsurf/mcp.json`):**
|
|
351
|
+
```json
|
|
352
|
+
{
|
|
353
|
+
"mcpServers": {
|
|
354
|
+
"hyperflash": {
|
|
355
|
+
"command": "hyperflash",
|
|
356
|
+
"args": ["mcp"]
|
|
357
|
+
}
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
---
|
|
363
|
+
|
|
364
|
+
### 5. Git Pre-Commit & CI/CD Quality Gates
|
|
365
|
+
|
|
366
|
+
Enforce HyperFlash invariants automatically on every `git commit` or pull request, preventing elided code and unverified mutations from ever reaching your repository:
|
|
367
|
+
|
|
368
|
+
#### Automatic Setup via CLI:
|
|
369
|
+
```bash
|
|
370
|
+
hyperflash init --target git
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
#### Pre-Commit Framework Configuration (`.pre-commit-config.yaml`):
|
|
374
|
+
```yaml
|
|
375
|
+
repos:
|
|
376
|
+
- repo: https://github.com/Virat-Ghatge/hyperflash
|
|
377
|
+
rev: v1.0.0
|
|
378
|
+
hooks:
|
|
379
|
+
- id: hyperflash-zero-elision
|
|
380
|
+
- id: hyperflash-verify
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
#### Native Git Pre-Commit Hook (`.git/hooks/pre-commit`):
|
|
384
|
+
```bash
|
|
385
|
+
#!/usr/bin/env bash
|
|
386
|
+
# HyperFlash Zero-Elision & Linting Guard
|
|
387
|
+
echo "⚡ Running HyperFlash pre-commit audit..."
|
|
388
|
+
|
|
389
|
+
# Check for lazy elision patterns in staged diffs
|
|
390
|
+
if git diff --cached | grep -E '(//|\#|\/\*)[[:space:]]*(\.\.\.|rest of|existing code|TODO: implement)'; then
|
|
391
|
+
echo "❌ [HYPERFLASH ERROR] Code elision detected in staged changes!"
|
|
392
|
+
echo " Never commit '// ... rest of code' or placeholder comments."
|
|
393
|
+
exit 1
|
|
394
|
+
fi
|
|
395
|
+
|
|
396
|
+
# Run verification if hyperflash is available
|
|
397
|
+
if command -v hyperflash &> /dev/null; then
|
|
398
|
+
hyperflash verify --tier 5
|
|
399
|
+
fi
|
|
400
|
+
|
|
401
|
+
echo "✅ HyperFlash checks passed."
|
|
402
|
+
exit 0
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
#### GitHub Actions Workflow (`.github/workflows/hyperflash-gate.yml`)
|
|
406
|
+
```yaml
|
|
407
|
+
name: HyperFlash Integrity Gate
|
|
408
|
+
|
|
409
|
+
on: [push, pull_request]
|
|
410
|
+
|
|
411
|
+
jobs:
|
|
412
|
+
verify:
|
|
413
|
+
runs-on: ubuntu-latest
|
|
414
|
+
steps:
|
|
415
|
+
- uses: actions/checkout@v4
|
|
416
|
+
- name: Set up Python
|
|
417
|
+
uses: actions/setup-python@v5
|
|
418
|
+
with:
|
|
419
|
+
python-version: '3.11'
|
|
420
|
+
- name: HyperFlash 9-Tier Verification
|
|
421
|
+
run: |
|
|
422
|
+
python src/skills/hyperflash/scripts/verify_hierarchy.py --tier 6
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
---
|
|
426
|
+
|
|
427
|
+
## 🏛 Multi-Agent Architecture
|
|
428
|
+
|
|
429
|
+
HyperFlash achieves reliability through **tool-permission asymmetry**.
|
|
430
|
+
|
|
431
|
+
The primary orchestrator (`hyperflash`) coordinates the lifecycle and performs reconnaissance, but is **physically stripped of file-writing tools**. It is impossible for the orchestrator to bypass the verification loop, write hallucinated code, or take ungrounded shortcuts:
|
|
432
|
+
|
|
433
|
+
```mermaid
|
|
434
|
+
flowchart TD
|
|
435
|
+
User([User Prompt / Agent Dropdown: hyperflash]) --> Router["hyperflash (Router Orchestrator)<br/>• Read-Only & Scope Analysis<br/>• Adaptive Complexity Routing"]
|
|
436
|
+
|
|
437
|
+
Router -->|Planning: Compact / Deep| Recon["hyperflash-investigator<br/>(AST & Workspace Recon)"]
|
|
438
|
+
Router -->|Call-Graph Audit| Audit["hyperflash-impact-auditor<br/>(Symbol Graph Tracer)"]
|
|
439
|
+
|
|
440
|
+
Recon --> Contract[".agents/state/contract.json<br/>(Locked Scope & Acceptance Criteria)"]
|
|
441
|
+
Audit --> Contract
|
|
442
|
+
|
|
443
|
+
Contract --> Executor["hyperflash-patch-executor<br/>(Surgical Diffs & Chunked Decode)"]
|
|
444
|
+
|
|
445
|
+
Executor --> Adversary["hyperflash-test-adversary<br/>(9-Tier Verification Hierarchy)"]
|
|
446
|
+
|
|
447
|
+
Adversary -->|VERDICT: PASS| Reviewer["hyperflash-reviewer<br/>(Structural Diff Audit)"]
|
|
448
|
+
Reviewer -->|VERDICT: APPROVED| Complete([Verified Delivery to User])
|
|
449
|
+
Adversary -->|VERDICT: FAIL| Executor
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
### Agent Roster & Permission Boundaries
|
|
453
|
+
|
|
454
|
+
| Agent Name | Permitted Tools | Core Responsibility |
|
|
455
|
+
|---|---|---|
|
|
456
|
+
| **`hyperflash`** | `view_file`, `grep_search`, `find_by_name`, `invoke_subagent` | **Router Orchestrator.** Evaluates task complexity, initializes `contract.json`, and coordinates subagents. Zero write tools. |
|
|
457
|
+
| **`hyperflash-investigator`** | `view_file`, `grep_search`, `find_by_name` | **Read-Only Reconnaissance.** Inspects target files, identifies relevant test suites, and localizes implementation areas. |
|
|
458
|
+
| **`hyperflash-impact-auditor`** | `view_file`, `grep_search`, `find_by_name` | **Dependency Auditor.** Traces upstream callers across the AST symbol graph to lock `allowed_write_scope` before edits. |
|
|
459
|
+
| **`hyperflash-patch-executor`** | `view_file`, `replace_file_content`, `write_to_file` | **Surgical Implementation.** Applies minimal diffs strictly within `allowed_write_scope`. Enforces Chunked Long-Decode and static types. |
|
|
460
|
+
| **`hyperflash-reviewer`** | `view_file`, `grep_search`, `run_command` | **Code Reviewer.** Audits `git diff` against structural invariants, performance regressions, and architectural boundaries. |
|
|
461
|
+
| **`hyperflash-test-adversary`** | `view_file`, `grep_search`, `run_command` | **Adversarial QA.** Executes compilers, type checkers, and test suites across the 9-Tier Verification Hierarchy. |
|
|
462
|
+
|
|
463
|
+
---
|
|
464
|
+
|
|
465
|
+
## 🛡 The 8 Watcher Invariants
|
|
466
|
+
|
|
467
|
+
Every file edit, tool call, and task completion is deterministically governed by the 8 HyperFlash Invariants:
|
|
468
|
+
|
|
469
|
+
```
|
|
470
|
+
┌────────────────────────────────────────────────────────────────────────────────────────┐
|
|
471
|
+
│ THE 8 WATCHER INVARIANTS │
|
|
472
|
+
├────┬────────────────────────────┬──────────────────────────────────────────────────────┤
|
|
473
|
+
│ # │ Invariant Name │ Enforcement Mechanism │
|
|
474
|
+
├────┼────────────────────────────┼──────────────────────────────────────────────────────┤
|
|
475
|
+
│ 1 │ Ground Before Mutating │ PreToolUse hook verifies target viewed in session │
|
|
476
|
+
│ 2 │ Stay in Declared Scope │ Mutations outside allowed_write_scope rejected │
|
|
477
|
+
│ 3 │ Fresh Evidence Required │ Stop hook blocks completion if last_test < last_edit │
|
|
478
|
+
│ 4 │ Never Exact-Retry Failures │ SHA-256 tool payload ledger rejects duplicate calls │
|
|
479
|
+
│ 5 │ Satisfy the Contract │ Acceptance criteria checked against contract.json │
|
|
480
|
+
│ 6 │ Report Reality Only │ Claims of success must cite observed terminal output │
|
|
481
|
+
│ 7 │ Zero Code Elision │ Regex filter blocks '// ... rest of code' comments │
|
|
482
|
+
│ 8 │ Exhaustive Static Typing │ Full type annotations and pre-mortem record required │
|
|
483
|
+
└────────────────────────────────┴──────────────────────────────────────────────────────┘
|
|
484
|
+
```
|
|
485
|
+
|
|
486
|
+
### Concrete Invariant Demonstrations
|
|
487
|
+
|
|
488
|
+
#### Invariant 1 & 7: Elision and Ungrounded Edits Blocked Instantly
|
|
489
|
+
When an agent attempts a lazy replacement:
|
|
490
|
+
```text
|
|
491
|
+
[HyperFlash PreToolUse Hook]
|
|
492
|
+
DENIED: Target file 'src/auth/jwt.py' was not viewed in current session.
|
|
493
|
+
DENIED: Content contains prohibited elision pattern: '// ... existing code remains ...'
|
|
494
|
+
Mutation blocked. The agent has been instructed to read the file and provide full code.
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
#### Invariant 4: Byte-Identical Loop Termination
|
|
498
|
+
When an agent makes the same failing edit twice:
|
|
499
|
+
```text
|
|
500
|
+
[HyperFlash Retry Ledger]
|
|
501
|
+
REJECTED: Tool call hash 7f83b165... is byte-identical to a previously failed tool call.
|
|
502
|
+
Deterministic failure loop intercepted. You must alter your implementation strategy.
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
#### Invariant 3 & 6: Premature Victory Denied
|
|
506
|
+
When an agent attempts to stop without running tests:
|
|
507
|
+
```text
|
|
508
|
+
[HyperFlash Stop Hook]
|
|
509
|
+
TASK COMPLETION DENIED:
|
|
510
|
+
File 'src/pipeline.py' was mutated at timestamp 1794564810.
|
|
511
|
+
Last verified test run occurred at timestamp 1794564750 (60s prior to mutation).
|
|
512
|
+
You must run your test suite (pytest / npm test) and provide fresh passing output before stopping.
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
---
|
|
516
|
+
|
|
517
|
+
## 📊 The 9-Tier Verification Hierarchy
|
|
518
|
+
|
|
519
|
+
Before code changes are declared complete, `hyperflash-test-adversary` executes tests progressively through 9 deterministic tiers:
|
|
520
|
+
|
|
521
|
+
| Tier | Category | Enforced Standard | Command Example | Action on Failure |
|
|
522
|
+
|:---:|---|---|---|---|
|
|
523
|
+
| **1** | **Syntax Integrity** | AST parse & syntax validation | `python -m py_compile src/app.py` | Immediate Rollback |
|
|
524
|
+
| **2** | **Compiler Sanity** | Static language compilation | `tsc --noEmit` / `cargo check` | Targeted Patch |
|
|
525
|
+
| **3** | **Type Soundness** | Strict type system compliance | `mypy --strict src/` | Signature Fix |
|
|
526
|
+
| **4** | **Direct Regression** | Targeted test for modified symbol | `pytest tests/test_unit.py -k test_auth` | Strategy Pivot |
|
|
527
|
+
| **5** | **Static Linting** | Style, imports, and security | `ruff check src/` / `eslint src/` | Surgical Fix |
|
|
528
|
+
| **6** | **Workspace Suite** | Full workspace test suite | `pytest` / `npm test` / `cargo test` | Scope Re-evaluation |
|
|
529
|
+
| **7** | **Adversarial Bounds**| Boundary inputs (nulls, empty, max) | Parameterized edge-case suites | Edge-Case Hardening |
|
|
530
|
+
| **8** | **Structural Review** | Independent diff audit | `hyperflash-reviewer` analysis | Code Refactoring |
|
|
531
|
+
| **9** | **Contract Fulfillment** | Formal criteria satisfied | Validation against `contract.json` | Final Completion |
|
|
532
|
+
|
|
533
|
+
---
|
|
534
|
+
|
|
535
|
+
## 📁 Repository Structure
|
|
536
|
+
|
|
537
|
+
```text
|
|
538
|
+
hyperflash/
|
|
539
|
+
├── .github/
|
|
540
|
+
│ ├── ISSUE_TEMPLATE/
|
|
541
|
+
│ │ ├── bug_report.md # Structured bug report template
|
|
542
|
+
│ │ └── feature_request.md # Architectural proposal template
|
|
543
|
+
│ ├── workflows/ # GitHub Actions CI/CD workflows
|
|
544
|
+
│ └── PULL_REQUEST_TEMPLATE.md # Invariant compliance checklist
|
|
545
|
+
├── pyproject.toml # Universal Python packaging & CLI entrypoint
|
|
546
|
+
├── .pre-commit-hooks.yaml # Pre-commit hook definitions for Git
|
|
547
|
+
├── install.sh # Linux/macOS non-destructive installer
|
|
548
|
+
├── install.ps1 # Windows PowerShell non-destructive installer
|
|
549
|
+
├── uninstall.sh # POSIX clean uninstaller
|
|
550
|
+
├── uninstall.ps1 # Windows PowerShell clean uninstaller
|
|
551
|
+
├── CODE_OF_CONDUCT.md # Contributor Covenant v2.1
|
|
552
|
+
├── CONTRIBUTING.md # Developer workflow & coding standards
|
|
553
|
+
├── SECURITY.md # Vulnerability disclosure policy
|
|
554
|
+
├── LICENSE # MIT License
|
|
555
|
+
├── README.md # Universal runtime documentation
|
|
556
|
+
├── tests/ # Pytest unit & integration test suite
|
|
557
|
+
│ ├── test_core.py # Invariant guards & AST symbol graph tests
|
|
558
|
+
│ ├── test_cli.py # CLI subcommands & parser tests
|
|
559
|
+
│ └── test_mcp.py # Stdio MCP server & JSON-RPC tests
|
|
560
|
+
└── src/
|
|
561
|
+
├── hyperflash/ # Core Python package & MCP server
|
|
562
|
+
│ ├── __init__.py # Package exports & version
|
|
563
|
+
│ ├── core.py # Invariants, AST indexer, contract, verification
|
|
564
|
+
│ ├── polyglot.py # Multi-platform config generators
|
|
565
|
+
│ ├── mcp_server.py # Stdio JSON-RPC 2.0 MCP server
|
|
566
|
+
│ └── cli.py # Unified CLI entrypoint
|
|
567
|
+
├── AGENTS.md # Global system constitution
|
|
568
|
+
├── hooks.json # Portable lifecycle hooks template
|
|
569
|
+
├── rules/
|
|
570
|
+
│ └── hyperflash-protocol.md # Always-on protocol rule
|
|
571
|
+
├── agents/
|
|
572
|
+
│ ├── hyperflash.md # Main Orchestrator
|
|
573
|
+
│ ├── hyperflash-investigator.md # Reconnaissance subagent
|
|
574
|
+
│ ├── hyperflash-impact-auditor.md # Caller impact subagent
|
|
575
|
+
│ ├── hyperflash-patch-executor.md # Implementation subagent
|
|
576
|
+
│ ├── hyperflash-reviewer.md # Structural review subagent
|
|
577
|
+
│ └── hyperflash-test-adversary.md # Verification subagent
|
|
578
|
+
├── skills/
|
|
579
|
+
│ └── hyperflash/
|
|
580
|
+
│ ├── SKILL.md # Core reliability runtime specification
|
|
581
|
+
│ ├── references/ # Schema & escalation guidelines
|
|
582
|
+
│ └── scripts/ # Decide CLI & 9-tier test verification
|
|
583
|
+
└── scripts/
|
|
584
|
+
├── build_symbol_graph.py # SessionStart AST indexer
|
|
585
|
+
├── enforce_hyperflash_pre_hook.py # PreToolUse invariant guard
|
|
586
|
+
├── mark_mutation_post_hook.py # PostToolUse timestamp & failure tracker
|
|
587
|
+
└── enforce_completion_stop_hook.py # Stop gate verifier
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
---
|
|
591
|
+
|
|
592
|
+
## ❓ Frequently Asked Questions (FAQ)
|
|
593
|
+
|
|
594
|
+
<details>
|
|
595
|
+
<summary><b>Can frontier models like Claude 3.7 Sonnet, OpenAI o3, or Gemini Hydrogen use this?</b></summary>
|
|
596
|
+
<br/>
|
|
597
|
+
<b>Absolutely.</b> Frontier models benefit dramatically from HyperFlash. While frontier models have unmatched reasoning capacity, they are notorious for collateral blast radius (editing files they weren't asked to touch) and premature completion ("Everything is done!" without testing). HyperFlash provides the structural rails: locking their write scope, verifying their AST dependencies, and machine-validating their test runs before they can mark an issue resolved.
|
|
598
|
+
</details>
|
|
599
|
+
|
|
600
|
+
<details>
|
|
601
|
+
<summary><b>Does HyperFlash work outside of Google Antigravity?</b></summary>
|
|
602
|
+
<br/>
|
|
603
|
+
<b>Yes.</b> HyperFlash is completely harness-agnostic. The repository includes configurations, constitutions, and CLI scripts for <b>Claude Code</b>, <b>OpenCode / OpenHands</b>, <b>Cursor</b>, <b>Windsurf</b>, standalone terminal workflows, and Git pre-commit hooks.
|
|
604
|
+
</details>
|
|
605
|
+
|
|
606
|
+
<details>
|
|
607
|
+
<summary><b>How does HyperFlash physically prevent code truncation (`// ... rest of code`)?</b></summary>
|
|
608
|
+
<br/>
|
|
609
|
+
HyperFlash intercepts every file edit tool call with an OS-level <code>PreToolUse</code> lifecycle hook (<code>enforce_hyperflash_pre_hook.py</code>). The hook executes a high-speed regex audit over the replacement text. If patterns such as <code>// ... rest of code</code>, <code># ... existing implementation</code>, or <code>/* unchanged */</code> are detected, the tool call is rejected at the system level before disk modification occurs, forcing the agent to output the complete code.
|
|
610
|
+
</details>
|
|
611
|
+
|
|
612
|
+
<details>
|
|
613
|
+
<summary><b>Is the installation process non-destructive?</b></summary>
|
|
614
|
+
<br/>
|
|
615
|
+
<b>Yes, 100%.</b> Both <code>install.sh</code> and <code>install.ps1</code> read your existing <code>hooks.json</code> and merge HyperFlash hooks alongside whatever MCP servers, custom agents, or existing tools you have configured. Running the uninstaller cleanly removes HyperFlash hooks while preserving your original environment intact.
|
|
616
|
+
</details>
|
|
617
|
+
|
|
618
|
+
<details>
|
|
619
|
+
<summary><b>What happens if my repository doesn't have an existing test suite?</b></summary>
|
|
620
|
+
<br/>
|
|
621
|
+
HyperFlash's 9-Tier Verification Hierarchy begins with Tier 1 (Syntax Integrity: <code>py_compile</code> / <code>node --check</code>) and Tier 2/3 (Compiler & Type Soundness: <code>tsc</code> / <code>mypy</code>). Even without unit tests, HyperFlash guarantees that the code parses cleanly, compiles without warnings, and satisfies static type constraints.
|
|
622
|
+
</details>
|
|
623
|
+
|
|
624
|
+
<details>
|
|
625
|
+
<summary><b>Does HyperFlash add latency or burn unnecessary API tokens?</b></summary>
|
|
626
|
+
<br/>
|
|
627
|
+
HyperFlash uses <b>Adaptive Complexity Triage</b>. For trivial 1-file fixes or documentation edits, it operates in <code>direct</code> mode without spawning subagents, responding in 2–4 seconds. Subagents (Recon, Impact Auditor, Test Adversary) are only activated when multi-file dependencies, ambiguous failures, or complex refactors are detected.
|
|
628
|
+
</details>
|
|
629
|
+
|
|
630
|
+
---
|
|
631
|
+
|
|
632
|
+
## 🤝 Community & Governance
|
|
633
|
+
|
|
634
|
+
HyperFlash is built by engineers, for engineers. We believe software reliability tools should be open, transparent, and community-driven.
|
|
635
|
+
|
|
636
|
+
* 📖 **Contributing:** Read our [Contribution Guidelines](CONTRIBUTING.md) to submit pull requests, add platform adapters, or enhance invariants.
|
|
637
|
+
* 🛡️ **Code of Conduct:** We are committed to a welcoming and harassment-free community. Read our [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
638
|
+
* 🔒 **Security:** Disclose vulnerabilities safely via our [Security Policy](SECURITY.md).
|
|
639
|
+
* 💬 **Discussions & Feedback:** Join the conversation on [GitHub Issues](https://github.com/Virat-Ghatge/hyperflash/issues).
|
|
640
|
+
|
|
641
|
+
---
|
|
642
|
+
|
|
643
|
+
## ⭐ Star HyperFlash on GitHub
|
|
644
|
+
|
|
645
|
+
If HyperFlash saved your codebase from broken imports, eliminated lazy code truncation, or rescued your API token quota, **give us a star on GitHub!** It helps the project grow and lets more developers build reliable software with AI.
|
|
646
|
+
|
|
647
|
+
<div align="center">
|
|
648
|
+
|
|
649
|
+
<br/>
|
|
650
|
+
|
|
651
|
+
[](https://github.com/Virat-Ghatge/hyperflash)
|
|
652
|
+
|
|
653
|
+
<br/>
|
|
654
|
+
|
|
655
|
+
*“Stop praying that your coding agent doesn't break production. Enforce it with HyperFlash.”*
|
|
656
|
+
|
|
657
|
+
</div>
|
|
658
|
+
|
|
659
|
+
---
|
|
660
|
+
|
|
661
|
+
## 📄 License
|
|
662
|
+
|
|
663
|
+
HyperFlash is open-source software licensed under the **[MIT License](LICENSE)** © 2026 [Virat Ghatge](https://github.com/Virat-Ghatge).
|