qed-standard 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KeelBismarck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/QED.lite.md

@@ -0,0 +1,45 @@
+# Q.E.D. Lite — Machine Instruction Set
+*Token-optimized (~450 tokens) engineering standard for AI coding agents.*
+
+You are bound by the **Q.E.D. High-Assurance Engineering Standard**.
+
+## 0. Hard Invariants
+1. **Evidence Before Assertions**: Never claim code works, is fixed, or passes without executing real test/build commands in the terminal and verifying clean output.
+2. **Root Cause Only**: Ban on empty catch blocks, fake sleep/timeouts, and loose `any` casts.
+3. **Pristine Root**: Zero scratch files, test dumps, or temporary scripts in project root.
+4. **Dual Modes**: Mode A (Default: Quality > Speed — full TDD, verification gate); Mode B (Speed > Quality — only on explicit prompt: "quick", "draft", "prototype", "быстро" — requires debt disclosure).
+
+## 1. Specification, Anti-Duplication & Blast Radius
+- **Search Before Create**: Grep the repository before creating any helper, hook, or type. Always reuse existing code.
+- **Blast Radius**: Map direct callers and transitive impact (API contracts, DB schemas, caches) before modifying shared code.
+- **Zero Secret Leaks**: No hardcoded secrets. Maintain `.env.example`. Parameterized queries only.
+- **Resource Hygiene**: Bounded LRU cache (`maxSize` + `ttlMs`). Scoped temp file cleanup in `try...finally`. Atomic file writes (`file.tmp` -> `file`). Streams for >10MB.
+- **Data Fetching**: Mandatory `AbortSignal.timeout(ms)`. Ban on `as TargetType` casts (runtime schema validation). Keyset pagination for >1k rows. Safe retries with jitter (`Idempotency-Key` for POST). Scope queries by tenant (IDOR defense). Singleflight deduplication.
+
+## 2. Adversarial QA, 4 States & Visual Anti-Slop
+Every UI flow and data route must handle:
+1. **Empty State**: Clear UI/payload when 0 items exist + next steps.
+2. **Loading State**: Predictable indicator preventing layout shift (CLS).
+3. **Error State**: Actionable, human-friendly error message with retry mechanism.
+4. **Degraded / Offline State**: Graceful fallback under timeouts or partial failure.
+5. **Visual Anti-Slop & Signature Spark**: The Archaeologist Invariant: preserve unique interactive mechanics while stripping card bloat (unboxed by default); ban Type 2 sterile brutalism; form follows data topology; zero UI emojis; 100% human-domain utility.
+6. **Workflow Ergonomics**: State-in-URL (filters/tabs); auto-save form drafts; semantic links (`<a>`) for navigation; never block paste; 1-click copy with feedback; undo toasts over modal popups; validate on blur.
+7. **Errors, Telemetry & DB**: Zero empty catches (chain `cause`); structured JSON logs with traceId & PII scrub; Expand/Contract for DB migrations (never drop columns in same release; `CREATE INDEX CONCURRENTLY`; `lock_timeout = '2s'`).
+
+## 3. Ironclad TDD & The 3 AM Test
+- **Reproduction First**: For bugs, write failing reproduction test (Red) -> minimal fix (Green) -> refactor. Features: tests before code.
+- **Testing Rules**: Zero placebo mocks; zero flaky `sleep()`; cover boundary matrix (0, 1, N, Max, null, hostile Unicode `👨‍👩‍👧‍👦`, double-clicks in 50ms).
+- **The 3 AM Test**: Flat guard clauses, early returns, clear intermediate variables.
+- **Semantic Rigor**: Positive booleans (`isActive`), units in numbers (`timeoutMs`), contract verbs (`get`, `create`). Comment WHY, not WHAT. Actionable `TODO(#issueId)` only.
+
+## 4. Verification Gate
+Before declaring completion:
+1. Pre-commit purge: remove debug prints (`console.log`, `print`, `debugger`), temp files, dead imports.
+2. Run typecheck (`tsc`, `mypy`), linter (`eslint`, `ruff`), and full test suite.
+3. Verify 100% pass and clean `git diff`.
+
+## 5. Context Economics (Token Hygiene)
+- **Surgical Edits**: Targeted diffs only; ban full-file rewrites when modifying <20% lines.
+- **Progressive Inspection**: Grep & read bounded line intervals; never dump 1000L files into context.
+- **Log Pruning**: Run tests with `qed exec <cmd>` or `--only-failures`; ban flooding context with green dots.
+- **Zero Filler**: No conversational padding in responses. Evidence before assertions.

package/README.md

@@ -1,3 +1,341 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/banner.svg" alt="Q.E.D. Banner" width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://github.com/keelbismark/qed/actions/workflows/ci.yml"><img src="https://github.com/keelbismark/qed/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/keelbismark/qed/releases/tag/v1.0.0"><img src="https://img.shields.io/badge/release-v1.0.0-blue.svg?style=flat-square" alt="Release: v1.0.0"></a>
+  <a href="package.json"><img src="https://img.shields.io/badge/pkg-qed--standard-cb3837.svg?style=flat-square&logo=npm" alt="Package: qed-standard"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3b82f6.svg?style=flat-square" alt="License: MIT"></a>
+  <a href="docs/harnesses.md"><img src="https://img.shields.io/badge/harnesses-20%20platforms-8b5cf6.svg?style=flat-square" alt="Harnesses: 20 Platforms"></a>
+  <a href="core/CONSTITUTION.md"><img src="https://img.shields.io/badge/standards-16%20core%20specs-10b981.svg?style=flat-square" alt="Standards: 16 Core Specs"></a>
+  <a href="core/CONSTITUTION.lite.md"><img src="https://img.shields.io/badge/edition-Q.E.D.%20Lite%20(<500%20tokens)-ec4899.svg?style=flat-square" alt="Edition: Q.E.D. Lite"></a>
+  <a href="tests/verify-adapters.ps1"><img src="https://img.shields.io/badge/tests-36%2F36%20passing-38bdf8.svg?style=flat-square" alt="Verification: 100% Passing"></a>
+  <a href="llms.txt"><img src="https://img.shields.io/badge/agent-llms.txt-f59e0b.svg?style=flat-square" alt="LLM Entrypoint: llms.txt"></a>
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#the-problem-codebase-erosion">The Problem</a> •
+  <a href="#framework-architecture">Architecture</a> •
+  <a href="#the-16-pillars-of-qed">The 16 Pillars</a> •
+  <a href="#mechanical-verification-gate-qed-check">Mechanical Gate</a> •
+  <a href="#how-it-works">Lifecycle</a> •
+  <a href="#20-supported-platforms">20 Platforms</a> •
+  <a href="llms.txt">llms.txt</a>
+</p>
+
+---
+
+## The Problem: Codebase Erosion
+
+AI pair-programming promised a 10x engineer. In practice, it frequently feels like reviewing PRs from an overcaffeinated junior developer:
+
+> *"I've resolved the issue!"* — the agent announces.  
+> You pull the branch. It never ran the tests. It broke three database queries. It hallucinated a deprecated library version. It created a second `formatDateHelper.ts` in another directory. And it silenced a fatal defect with `catch (e) {}`.
+
+Code generated without physical boundaries is technical debt accumulating compound interest. We call it **codebase erosion**.
+
+**Q.E.D.** (*Latin: "quod erat demonstrandum" — which was to be demonstrated*) is an open-source, high-assurance engineering standard and configuration layer for AI coding environments. It replaces vibes, guesses, and unverified assertions with deterministic engineering discipline.
+
+---
+
+## Framework Architecture
+
+Q.E.D. organizes engineering discipline across three coordinated tiers: **Universal Invariants**, the **4-Phase Verification Engine**, and the **External Trust Contract**.
+
+<p align="center">
+  <img src="assets/framework.svg" alt="Q.E.D. Architectural Framework" width="100%">
+</p>
+
+---
+
+## Before & After: Real-World Evidence
+
+```typescript
+// [WITHOUT Q.E.D.] Standard AI Generative Output
+// Silent error swallowing, loose typing, happy-path assumption, zero tests executed
+async function checkout(cart: any) {
+  try {
+    if (cart.items) {
+      const total = cart.items.reduce((a: any, b: any) => a + b.price, 0);
+      return await api.charge(total); // Floating point bug: 0.1 + 0.2 !== 0.3! No idempotency!
+    }
+  } catch (e) {
+    console.log("error"); // Swallowed failure. UI hangs indefinitely.
+  }
+}
+```
+
+```typescript
+// [WITH Q.E.D.] High-Assurance Output
+// Guard clauses, integer minor units, 4 states handled, reproduction test verified RED first
+async function checkout(cart: Cart): Promise<CheckoutResult> {
+  if (!cart.items || cart.items.length === 0) {
+    return { status: "empty", message: "Cart is empty" };
+  }
+  
+  // Reused existing helper (Anti-Duplication) & Integer Minor Units (No floating-point currency)
+  const totalMinorUnits = calculateCartTotalMinorUnits(cart.items);
+  if (totalMinorUnits <= 0) {
+    throw new InvalidOrderError("Total amount must be greater than zero");
+  }
+
+  // Idempotent charge with explicit timeout and retry boundary (Chaos Monkey verified)
+  return await paymentGateway.chargeWithIdempotency({
+    amountMinorUnits: totalMinorUnits,
+    currency: cart.currency, // ISO 4217 Invariant
+    idempotencyKey: cart.idempotencyKey,
+  });
+}
+```
+
+---
+
+## How It Works: The 4-Phase Verification Loop
+
+Every task executed under Q.E.D. traverses an ironclad, evidence-backed lifecycle:
+
+<p align="center">
+  <img src="assets/pipeline.svg" alt="Q.E.D. Verification Pipeline" width="100%">
+</p>
+
+### Execution Trace Example
+
+```text
+$ qed "Add idempotent debit to wallet API"
+
+[1/4] SPECIFICATION, ANTI-DUPLICATION & BLAST RADIUS
+      -> Grepping codebase for existing wallet balance helpers...
+      -> Found 'db.wallets.updateBalance()' in src/services/wallet.ts (reused).
+      -> Callers: CheckoutController, SubscriptionCron (Blast Risk: Medium).
+
+[2/4] ADVERSARIAL QA & 4 MANDATORY STATES
+      -> Mapping edge cases: double-click in 50ms, expired JWT, zero balance, timeout.
+      -> Implementing: Empty, Loading, Error (retryable), Degraded states.
+
+[3/4] IRONCLAD TDD (REPRODUCTION FIRST)
+      -> Authoring reproduction test: test/wallet.test.ts:42
+      $ npm test -- test/wallet.test.ts
+      FAIL: Concurrent duplicate debit executed twice. Expected 1 charge.
+      -> Red state verified.
+      -> Implementing minimal fix (row lock + unique idempotency constraint)...
+      $ npm test -- test/wallet.test.ts
+      PASS: 2 concurrent calls -> 1 debit, 1 cached response (Green verified).
+
+[4/4] THE 3 AM AUDIT, SANITIZATION & VERIFICATION GATE
+      -> Refactored nested if/else pyramids into early return guard clauses.
+      -> Sanitization sweep: 0 console.log, 0 throwaway scripts, 0 dead imports.
+      -> Static Typecheck: OK (0 errors).
+      -> Linter: OK (0 warnings).
+      -> Full Regression Suite: 64/64 passed (100% green).
+      -> Commit: feat(wallet): implement idempotent debit with distributed lock
+```
+
+---
+
+## The 16 Pillars of Q.E.D.
+
+The standard is codified in 16 formal specification documents under [`core/`](core/):
+
+| # | Pillar & Specification | Core Invariant | Risk Eliminated |
+| :-: | :--- | :--- | :--- |
+| **0** | **[Universal Constitution](core/CONSTITUTION.md)** | Quality > Speed by default; evidence before assertions; root cause only. | Speculative coding, cosmetic hacks, placebo fixes. |
+| **1** | **[Testing Philosophy](core/testing-philosophy.md)** | Zero placebo mocks; mandatory boundary matrix; reproduction RED $\rightarrow$ GREEN. | Testing mocks instead of real software; flaky tests. |
+| **2** | **[Adaptive Architecture](core/adaptive-architecture.md)** | Earned complexity; form follows data flow; pristine root; 10-second entrypoint. | Enterprise boilerplate on small tools; cluttered project roots. |
+| **3** | **[Dependency Philosophy](core/dependency-philosophy.md)** | Build vs. Buy matrix; 4-pillar package health audit; The Wrapper Invariant. | Supply chain trojans, bloatware, unmaintained micro-packages. |
+| **4** | **[Threat-Adaptive Security](core/security-philosophy.md)** | 4 Security Tiers; tenant-isolated IDOR checks; anti-security-theater UX (NIST 800). | IDOR leaks, mass assignment, user-hostile login barriers. |
+| **5** | **[Earned Regionality & I18n](core/regionality-and-i18n.md)** | Level 0 baseline (UTF-8, UTC, integer money); native `Intl`; sovereign data residency. | Timezone shift bugs, float money bugs, GDPR fines. |
+| **6** | **[Cache & Resource Hygiene](core/cache-memory-and-file-hygiene.md)** | Bounded LRU cache + TTL; tenant cache isolation; streams for >10MB; scoped temp cleanup. | Out-of-memory (OOM) crashes, 100% disk exhaustion, ghost data. |
+| **7** | **[Data Fetching Philosophy](core/data-fetching-philosophy.md)** | Mandatory `AbortSignal` timeout; anti-`as` boundary parsing; Keyset pagination; Singleflight. | Hanging socket leaks, contract drift crashes, waterfall lag, IDOR. |
+| **8** | **[Visual Anti-Slop Standard](core/visual-anti-slop-standard.md)** | The Archaeologist Invariant (preserve the Signature Spark); unboxed by default; anti-Bento; zero emojis. | Type 1 synthetic plastic carnival, Type 2 sterile hospital sheet brutalism. |
+| **9** | **[Workflow Ergonomics](core/workflow-ergonomics-and-affordances.md)** | State-in-URL; auto-save drafts; native links; never block paste; 1-click copy; Undo toasts. | Lost form inputs, modal blindness, broken back-buttons, copy-paste friction. |
+| **10** | **[Error Handling Philosophy](core/error-handling-philosophy.md)** | 4 Operational Tiers; Result<T,E>; error cause chaining; boundary masking with Correlation ID. | Silent catch rot, unmasked stack trace leaks, double logging. |
+| **11** | **[Observability, Telemetry & RCA](core/observability-and-rca.md)** | Structured JSON logging; traceId propagation; automated PII redaction; blameless 5 Whys RCA. | Unsearchable text logs, PII credential leaks, repeat production outages. |
+| **12** | **[Database Evolution & Migrations](core/database-evolution-and-migrations.md)** | Expand/Contract pattern; non-blocking DDL (`CREATE INDEX CONCURRENTLY`, `lock_timeout = '2s'`). | Locked production tables, failed deployments, corrupted data. |
+| **13** | **[Git & Pragmatic Versioning](core/git-and-versioning.md)** | Git change ledger $\neq$ Versioning trust contract; Bisect Invariant; changelog split. | Broken git bisect, unearned deprecation, leaked security flaws. |
+| **14** | **[Naming & Semantics](core/naming-philosophy.md)** | Scope-proportional length; positive predicates; contract verbs (`get` vs `fetch`). | Ambiguous names (`data`, `temp`, `res`), misleading predicates. |
+| **15** | **[Hygiene & Pre-Commit Sweep](core/hygiene-and-cleanup.md)** | Zero debug prints; throwaway script purge; clean git status before commit. | Production debug logs, leaked tokens, commit pollution. |
+
+---
+
+## Quickstart
+
+Install Q.E.D. into your project in seconds:
+
+### Windows (PowerShell)
+```powershell
+irm https://raw.githubusercontent.com/keelbismark/qed/main/install.ps1 | iex
+```
+
+### Linux / macOS (Bash)
+```bash
+curl -fsSL https://raw.githubusercontent.com/keelbismark/qed/main/install.sh | bash
+```
+
+### Targeted Platform Setup
+Install configurations for a specific AI harness only:
+
+```bash
+./install.sh cursor      # Cursor AI (.cursorrules & modern .cursor/rules/*.mdc)
+./install.sh claude      # Claude Code (CLAUDE.md, slash commands, skills)
+./install.sh deepseek    # DeepSeek Harness (dsh) & Continue.dev
+./install.sh roo         # Roo Code custom modes (Architect, TDD, Reviewer)
+./install.sh global all  # Machine-wide installation across user profile
+```
+
+### Q.E.D. Lite (Token-Optimized Edition)
+For fast or token-constrained models (**Claude 3.5 Haiku, Gemini Flash, GPT-4o-mini, local LLMs via Ollama/Llama 3/Qwen**), install the ultra-dense Lite edition (<500 tokens, ~80% token reduction) without sacrificing any core engineering invariants:
+
+```bash
+# Linux / macOS
+./install.sh --lite             # Install Lite for all harnesses
+./install.sh --lite claude      # Install Lite for Claude Code (CLAUDE.md)
+./install.sh --lite cursor      # Install Lite for Cursor (.cursorrules)
+
+# Windows (PowerShell)
+.\install.ps1 -Lite             # Install Lite for all harnesses
+.\install.ps1 -Lite -Harness claude
+.\install.ps1 cursor -Lite
+```
+
+*Distinct Lite manifests are also directly available in the repository root and harness folders (`QED.lite.md`, `core/CONSTITUTION.lite.md`, `adapters/*/GEMINI.lite.md`, `CLAUDE.lite.md`, `.cursorrules.lite`).*
+
+---
+
+## Mechanical Verification Gate (`qed check` & Pre-Commit Hook)
+
+To eliminate reliance on an AI agent's "honor system", Q.E.D. includes a standalone mechanical linter and Git pre-commit gate that automatically blocks commits containing standard violations:
+
+```bash
+# Run mechanical compliance check across the repository
+./bin/qed check              # Linux / macOS
+.\bin\qed.ps1 check          # Windows (PowerShell)
+node bin/qed-engine.js check # Node.js (cross-platform, zero dependencies)
+
+# Run full health & invariant audit (git cleanliness, hooks, remote CI, AST)
+node bin/qed-engine.js doctor
+
+# Install automated Git pre-commit & pre-push hooks
+./bin/qed hook               # Linux / macOS
+.\bin\qed.ps1 hook           # Windows (PowerShell)
+
+# Run cross-platform multi-OS test matrix (PowerShell + POSIX Bash)
+npm test                     # or node bin/qed-engine.js test
+
+# Run empirical LLM slop eradication benchmark
+npm run evals                # or node evals/run-benchmark.js
+```
+
+The mechanical gate automatically scans and enforces:
+1. **Pristine Root Invariant**: Zero temporary scratch files (`temp_*`, `scratch.*`, `*.tmp`, `*.log`, `test_dump*`).
+2. **Zero-Debug Print Invariant**: Zero leftover `console.log(`, `debugger;`, `print(`, or `fmt.Println(`.
+3. **Environment Synchronization**: Every environment variable referenced in code must be documented in `.env.example`.
+4. **Type Safety & AST Analysis**: Zero loose `as any` casts in TypeScript/JavaScript (lexically masked and TypeScript AST verified).
+5. **Network Deadlines**: Mandatory `AbortSignal.timeout` on all `fetch()` operations.
+6. **Bounded Caches**: Zero unbounded module-level `new Map()` exports.
+7. **Zero Table-Locking DDL**: Enforces `CREATE INDEX CONCURRENTLY` in SQL migrations.
+
+---
+
+## Empirical Benchmark & Proof Matrix
+
+We don't guess whether Q.E.D. makes AI code better — we measure it scientifically. The included automated benchmark suite (`evals/run-benchmark.js`) executes 6 standardized engineering challenges against unconstrained LLMs versus Q.E.D.:
+
+| Scenario ID | Engineering Domain | Vanilla Baseline | Under Q.E.D. Standard | Result |
+| :--- | :--- | :---: | :---: | :---: |
+| **SCN-01-CACHE** | Bounded Memory / LRU | 1 defect (`new Map()`) | **0 defects** | **PASSED** |
+| **SCN-02-FETCH** | Network Resilience / Deadlines | 1 defect (naked `fetch`) | **0 defects** | **PASSED** |
+| **SCN-03-ERROR** | Error Chaining & Fallbacks | 1 defect (swallowed `catch`) | **0 defects** | **PASSED** |
+| **SCN-04-TYPES** | Runtime Type Invariants | 1 defect (`as any` cast) | **0 defects** | **PASSED** |
+| **SCN-05-DDL** | Database Zero-Downtime | 1 defect (table-lock DDL) | **0 defects** | **PASSED** |
+| **SCN-06-UI** | Human Affordances / Anti-Slop | 1 defect (emoji button salad) | **0 defects** | **PASSED** |
+
+- **Slop Eradication Rate**: **100.0%** of mechanical flaws eliminated.
+- **Vanilla Gate Pass Rate**: **0.0%** (all unconstrained code failed mechanical verification).
+- **Q.E.D. Gate Pass Rate**: **100.0%** (high-assurance compliance).
+
+[View Full Empirical Methodology & Telemetry Data →](docs/evals.md)
+
+---
+
+## 20 Supported Platforms
+
+Q.E.D. provides native drop-in adapters and configuration manifests tailored to each tool's architecture:
+
+| Environment | Primary Manifest | Key Capabilities |
+| :--- | :--- | :--- |
+| **Cursor AI** | `.cursorrules`, `.cursor/rules/*.mdc` | Modern MDC rules with YAML frontmatter for TDD and Blast Radius |
+| **Claude Code** | `CLAUDE.md`, `.claude/commands/` | Slash commands (`/boost`, `/qed-verify`, `/qed-review`), skills |
+| **Google Antigravity** | `GEMINI.md`, `.antigravity-plugin/` | Multi-agent orchestration, Evidence Before Assertions |
+| **DeepSeek (dsh & Continue)**| `DEEPSEEK.md`, `.dsh/`, `.continue/` | R1 Chain-of-Thought directives, safety presets, slash commands |
+| **Roo Code & Cline** | `.roomodes`, `.clinerules` | 3 custom roles: `Architect`, `TDD Engineer`, and `Reviewer` |
+| **Windsurf Cascade** | `.windsurfrules`, workflows | Interactive workflows (`qed-boost`, `qed-tdd-cycle`) |
+| **Aider** | `.aider.conventions.md` | Auto-test on commit (`auto-test: true`), Conventional Commits |
+| **GitHub Copilot** | `copilot-instructions.md`, prompts | Instructions and prompt templates (`qed-boost`, `qed-spec`) |
+| **OpenCode** | `opencode.json`, `plugins/qed.js` | In-process V1/V2 lifecycle plugin, sandbox constraints |
+| **Codex, Grok, Kimi, Pi, Devin...** | Native manifests & configs | Full parity across 20 environments |
+
+[View Full Harness Details & Manual Configurations →](docs/harnesses.md)
+
+---
+
+## Dual Execution Modes
+
+Q.E.D. adapts to your velocity requirements:
+
+* **Mode A (Production Mode — Default: `Quality > Speed`)**  
+  Full engineering rigor. Red-Green-Refactor TDD cycles, blast radius calculation, adversarial testing, and verification gate before declaring work complete.
+* **Mode B (Speed Mode — On-Demand: `Speed > Quality`)**  
+  Triggered when you explicitly ask for speed (*"quick"*, *"prototype"*, *"draft"*, *"быстро"*, *"набросок"*). Delivers a working proof-of-concept immediately, accompanied by an explicit report detailing shortcuts taken and required hardening steps.
+
+---
+
+## Comparison Matrix
+
+| Capability | Q.E.D. | GitHub Spec-Kit | obra/superpowers | BMad Method | Default AI |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **Evidence Before Assertions** | **Enforced** | Partial | Enforced | Partial | None |
+| **Blast Radius Analysis** | **Yes** | No | No | No | No |
+| **Anti-Duplication Radar** | **Mandatory** | No | No | No | No |
+| **Threat-Adaptive Security (4 Tiers)**| **Enforced** | No | No | No | None |
+| **Earned Regionality & I18n** | **Enforced** | No | No | No | None |
+| **Bounded Caches & Resource Hygiene**| **Enforced** | No | No | No | None |
+| **4 Mandatory States** | **Enforced** | Partial | No | Partial | None |
+| **3 AM Readability Test** | **Enforced** | No | Partial | No | None |
+| **Chaos Monkey Edge Cases** | **Standard** | No | Partial | No | None |
+| **Supported Platforms** | **20** | 1 | 20 | 2 | None |
+| **Context Overhead** | **Minimal** | Minimal | Minimal | Heavy | Uncontrolled |
+
+---
+
+## Specification & Standards Library
+
+* **[Universal Constitution](core/CONSTITUTION.md)** — Foundational articles governing agent behavior.
+* **[Testing Philosophy](core/testing-philosophy.md)** — Zero placebo mocks, boundary matrix, mutation testing.
+* **[Adaptive Architecture](core/adaptive-architecture.md)** — Anti-template dogmatism, earned complexity.
+* **[Dependency Philosophy](core/dependency-philosophy.md)** — Build vs. Buy, 4-pillar audit, Wrapper Invariant.
+* **[Threat-Adaptive Security](core/security-philosophy.md)** — 4 Security Tiers, NIST 800-63B, Tenant Isolation.
+* **[Earned Regionality & I18n](core/regionality-and-i18n.md)** — Level 0-3 ladder, UTC wire, minor integer money.
+* **[Cache, Memory & Resource Hygiene](core/cache-memory-and-file-hygiene.md)** — Bounded LRU, leak-free streams, temp cleanup.
+* **[Data Fetching Philosophy](core/data-fetching-philosophy.md)** — Transport deadlines, boundary schema validation, Keyset pagination.
+* **[Visual Anti-Slop & Human Interface](core/visual-anti-slop-standard.md)** — Unboxed by default, form follows data, zero UI emojis, anti-cyber slop.
+* **[Workflow Ergonomics & Human Affordances](core/workflow-ergonomics-and-affordances.md)** — State-in-URL, draft auto-save, focus return, Undo toasts.
+* **[Error Handling Philosophy](core/error-handling-philosophy.md)** — 4 operational tiers, Result<T,E>, cause chaining, boundary masking.
+* **[Observability & Incident RCA](core/observability-and-rca.md)** — Structured JSON logging, trace context, PII scrubbing, 5 Whys.
+* **[Database Evolution & Migrations](core/database-evolution-and-migrations.md)** — Expand/Contract, non-blocking DDL, batched backfills.
+* **[Git & Pragmatic Versioning](core/git-and-versioning.md)** — Change ledger vs. trust contract, Bisect Invariant.
+* **[Naming & Semantics](core/naming-philosophy.md)** — Scope-proportional names, positive predicates, contract verbs.
+* **[Hygiene & Pre-Commit Sweep](core/hygiene-and-cleanup.md)** — Zero-debug print invariant, dead code elimination.
+* **[Comment Philosophy & Anti-Noise](core/comment-philosophy.md)** — Ban on syntax echo noise, Why-over-What rules.
+* **[Documentation & Visual Standards](core/documentation-and-visuals.md)** — Human vs. AI separation, responsive SVG graphics.
+* **[AI Agent Guide (llms.txt)](llms.txt)** — High-density machine entrypoint for LLMs.
+* **[Harness Guide](docs/harnesses.md)** — Setup reference for all 20 platforms.
+* **[Templates](templates/)** — Templates for Specs, Architecture Decision Records (ADRs), and Plans.
+* **[End-to-End Walkthrough](examples/full-lifecycle-walkthrough.md)** — Real-world example building a feature under Q.E.D.
+
+---
+
+## License
+
+MIT License. Copyright (c) 2026 KeelBismarck.

package/adapters/aider/.aider.conf.yml

@@ -0,0 +1,30 @@
+# Q.E.D. High-Assurance Configuration for Aider
+# Place this file as .aider.conf.yml in your repository root
+
+# Automatically load the Q.E.D. engineering conventions into context
+read: .aider.conventions.md
+
+# Enforce automatic execution of verification tests after code edits
+auto-test: true
+
+# Enable automatic git commits adhering to Conventional Commits
+auto-commits: true
+
+# Clean git commit metadata (do not inject promotional commit author tags)
+attribute-author: false
+attribute-committer: false
+
+# Example test commands (uncomment and adjust for your tech stack):
+# test-cmd: npm test
+# test-cmd: pytest
+# test-cmd: cargo test
+# test-cmd: go test ./...
+
+# Example lint commands:
+# lint-cmd: npm run lint
+# lint-cmd: ruff check .
+# lint-cmd: cargo clippy
+
+# Formatting and diff options
+stream: true
+pretty: true

package/adapters/aider/.aider.conventions.lite.md

@@ -0,0 +1,16 @@
+# Q.E.D. Lite Conventions for Aider
+# Drop as .aider.conventions.md or .aider.conventions.lite.md in repo root
+
+Directives:
+- Prime Directive: Evidence Before Assertions. Never state code works without executing terminal tests.
+- Mode A (Default: Quality > Speed): TDD, Blast Radius, 4 States, Verification Gate. Mode B (Speed Mode): Only on explicit request ("quick", "draft", "prototype", "быстро"). Disclose technical debt.
+- Root Cause Only: Ban on empty catch blocks, fake timeouts, and loose `any` casts.
+- Pristine Root: Zero scratch files or temporary dumps in root.
+- Anti-Duplication: Search repo before introducing any new function, hook, or type. Always reuse existing code.
+- Blast Radius: Map direct callers and transitive API/DB/cache impact before modifying shared code.
+- Security & Hygiene: Never commit secrets; update `.env.example`; bounded LRU caches (`maxSize` + `ttlMs`); cleanup temp files in `try...finally`.
+- 4 Mandatory States: Implement Empty (0 items + CTA), Loading (no CLS), Error (actionable + retry), Degraded/Offline (timeout fallback).
+- Ironclad TDD: Reproduction test first for bugs (Red -> Green -> Refactor). Zero placebo mocks; zero flaky `sleep()`; cover boundary matrix (0, 1, N, Max, null, hostile Unicode `👨‍👩‍👧‍👦`, double-clicks in 50ms).
+- The 3 AM Test: Early returns, flat guard clauses, descriptive variables, positive predicates (`isActive`), units in numbers (`timeoutMs`), contract verbs (`get`, `create`). Comment WHY, not WHAT. Actionable `TODO(#issueId)`.
+- Commits: Use Conventional Commits (`feat:`, `fix:`, `test:`, `refactor:`, `docs:`, `chore:`). Keep commits atomic.
+- Verification Gate: Purge debug prints and scratch files; run typecheck, linter, and full test suite before completion.

package/adapters/aider/.aider.conventions.md

@@ -0,0 +1,75 @@
+# Q.E.D. Engineering Conventions for Aider
+# Place this file as .aider.conventions.md in your repository root
+
+You are an expert pair-programmer operating under the **Q.E.D. (Quod Erat Demonstrandum)** High-Assurance Engineering Standard.
+Your prime directive is: **Evidence Before Assertions**.
+
+---
+
+## 0. Fundamental Directive: Quality > Speed
+
+1. **Evidence Before Assertions**:
+   - Never claim code is working, tested, or complete without running the tests (via `/test` or configured `test-cmd`) and inspecting output.
+2. **Root Cause Only**:
+   - Never suppress errors with empty catch blocks, fake timeouts, or type casts (`any`). Resolve the actual underlying defect.
+3. **Zero Secret Leaks**:
+   - Never hardcode credentials, tokens, or API keys. Update `.env.example` when adding environment variables.
+
+---
+
+## 1. Conventional Commits Discipline
+
+All git commit messages MUST adhere to the Conventional Commits specification:
+- `feat: <description>` for new user-facing functionality
+- `fix: <description>` for bug fixes
+- `test: <description>` for adding or correcting tests
+- `refactor: <description>` for internal restructuring without behavioral change
+- `docs: <description>` for documentation and ADR updates
+- `chore: <description>` for dependency updates and build maintenance
+
+Rules:
+- Keep commits atomic and self-contained.
+- Use imperative mood ("add", "fix", "refactor", not "added", "fixed").
+
+---
+
+## 2. Anti-Duplication, Dependencies & Blast Radius
+
+- **Dependency Discipline & The Wrapper Invariant**:
+  - Battle-tested standards for crypto/auth/protocols (never DIY). Standard library for trivial helpers (no micro-packages for clamps/slugs).
+  - 4-Pillar audit: transitive dependency tree, maintenance vitality, native types, permissive license (MIT/Apache 2.0).
+  - Wrap external dependencies behind internal facades. Never leak 3rd-party types across call sites.
+- **Context-Driven Security & Anti-Security-Theater**:
+  - Match security to runtime tier (Tier 1 CLI path/exec safety, Tier 2 web bundle/XSS, Tier 3 multi-tenant IDOR/error masking, Tier 4 FinTech timing/audit).
+  - Never block paste (support password managers); silent refresh & draft preservation; ban captive captchas on initial logins.
+- **Earned Regionality & Temporal Integrity**:
+  - Level 0: UTF-8, UTC in DB/wire, integer minor units + ISO 4217 for money, flexible names. Scale to ICU dictionaries and sovereign multi-region DBs (152-ФЗ, GDPR) only when earned.
+- **Cache, Memory & Resource Hygiene**:
+  - Mandatory bounded LRU caches (`maxSize`) and TTL (`ttlMs`); tenant-scoped cache keys; invalidate on DB mutation.
+  - Guaranteed temp file cleanup (`try...finally`); atomic file writes (`file.tmp` -> `file`); streams with backpressure for payloads > 10MB.
+- **Search Before You Create**: Grep the existing files in the repo before adding a new utility, helper function, hook, or model. Always reuse or extend existing code.
+- **Blast Radius Analysis**: Inspect all files referencing a symbol before modifying shared signatures. Keep changes backward-compatible whenever possible.
+
+---
+
+## 3. The 4 Mandatory States & The 3 AM Test
+
+- **The 4 States**: Every user flow and API route must handle:
+  1. Empty State (clear CTA when 0 items exist)
+  2. Loading State (predictable skeleton/spinner)
+  3. Error State (actionable error message with retry)
+  4. Degraded / Offline State (graceful fallback)
+- **The 3 AM Test**:
+  - Prefer early returns and flat guard clauses over nested `if/else` ladders.
+  - Use descriptive intermediate variables instead of opaque multi-level chained expressions.
+  - Eradicate AI generative slop: do not write gratuitous helper classes or bloated factory patterns.
+
+---
+
+## 4. Test-Driven Development (TDD) & Chaos Monkey
+
+- When fixing bugs: write a reproduction test first -> observe failure -> fix -> observe pass.
+- When writing tests, include Chaos Monkey edge cases:
+  - Empty and boundary inputs
+  - Hostile Unicode strings and special characters
+  - Rapid repeated invocations (debouncing/idempotency)

package/adapters/antigravity/.antigravity-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "qed",
+  "displayName": "Q.E.D. Engineering Standard",
+  "version": "1.0.0",
+  "description": "High-Assurance Engineering Standard: Evidence Before Assertions, Blast Radius Analysis, Anti-Duplication, and Ironclad TDD.",
+  "logo": "https://www.gstatic.com/antigravity/logos/antigravity-icon__full-color.png",
+  "suggestedPrompts": [
+    "Check the blast radius before implementing this change",
+    "Run the Q.E.D. verification gate and show evidence"
+  ],
+  "category": "Developer Tools",
+  "keywords": [
+    "antigravity",
+    "qed",
+    "tdd",
+    "blast-radius",
+    "anti-duplication",
+    "verification-gate",
+    "quality-over-speed"
+  ],
+  "author": {
+    "name": "Q.E.D. Engineering Team",
+    "url": "https://github.com/keelbismark/qed"
+  },
+  "homepage": "https://github.com/keelbismark/qed",
+  "repository": "https://github.com/keelbismark/qed",
+  "license": "MIT"
+}

package/adapters/antigravity/GEMINI.lite.md

@@ -0,0 +1,36 @@
+# Q.E.D. Lite for Google Antigravity
+# Drop as GEMINI.md or GEMINI.lite.md in repo root or ~/.gemini/
+
+This agent operates strictly under the Q.E.D. High-Assurance Engineering Standard:
+
+## 0. Prime Directive: Evidence Before Assertions
+- Never declare a task complete without executing verification tests and verifying clean output via tool commands.
+- Root Cause Only: Zero empty catch blocks, zero arbitrary timeouts, zero loose `any` casts.
+- Pristine Root Invariant: Zero scratch files or temporary dumps in root directory.
+- Dual Modes: Mode A (Default: Quality > Speed — full TDD & verification); Mode B (Speed > Quality — only on explicit request: "quick", "prototype", "draft", "быстро" — requires debt disclosure).
+
+## 1. Specification, Anti-Duplication & Blast Radius
+- Search Before Create: Grep codebase before introducing any new helper, utility, or type. Always reuse existing abstractions.
+- Blast Radius: Map direct callers and transitive API/DB/cache impact before modifying shared code.
+- Zero Secret Leaks: Never hardcode credentials. Keep `.env.example` updated. Parameterized queries only.
+- Resource Hygiene: Bounded LRU cache (`maxSize` + `ttlMs`). Scoped temp file deletion in `try...finally`. Atomic file writes (`file.tmp` -> `file`). Streams for >10MB.
+
+## 2. Adversarial QA & The 4 Mandatory States
+Every UI view and API route must implement:
+1. Empty State (0 items + clear next step)
+2. Loading State (predictable indicator, zero CLS)
+3. Error State (actionable message + retry button)
+4. Degraded / Offline State (graceful fallback under network timeout/partition)
+
+## 3. Ironclad TDD & The 3 AM Test
+- Bugs: Write reproduction test first -> verify Red -> minimal fix -> verify Green -> refactor.
+- Features: Unit/integration tests reflecting acceptance criteria before code.
+- Testing Rules: Zero placebo mocks; zero flaky `sleep()`; cover boundary matrix (0, 1, N, Max, null, hostile Unicode `👨‍👩‍👧‍👦`, double-clicks in 50ms).
+- The 3 AM Test: Early returns, flat guard clauses, descriptive intermediate variables.
+- Semantic Naming & Clean Comments: Positive booleans (`isActive`), units in numbers (`timeoutMs`), contract verbs (`get`, `create`). Comment WHY, never WHAT. Actionable `TODO(#issueId)` only.
+
+## 4. Verification Gate
+Before declaring completion:
+1. Pre-commit sweep: purge debug prints (`console.log`, `print`, `debugger`), temp files, dead imports.
+2. Run typecheck, linter, and full test suite.
+3. Verify 100% pass and clean git diff matching acceptance criteria.