xgauntlet 0.1.0

package/README.md

@@ -0,0 +1,286 @@
+<p align="center">
+  <a href="#-hurtig-start--installation"><b>🚀 Hurtig Start & Installation</b></a> •
+  <a href="#-pipeline-og-gates-sådan-virker-det"><b>🧭 Pipeline & Gates</b></a> •
+  <a href="#-arkitektur--designprincipper"><b>🎯 Arkitektur</b></a> •
+  <a href="#️-mappestruktur-package-by-feature"><b>🏗️ Mappestruktur</b></a> •
+  <a href="#️-fuld-cli-reference"><b>🛠️ CLI Reference</b></a> •
+  <a href="#-rust-api"><b>🦀 Rust API</b></a> •
+  <a href="#️-arkitektur-adrs"><b>🏛️ ADRs</b></a>
+</p>
+
+---
+
+<p align="center">
+  <h1 align="center">xGauntlet 🛡️</h1>
+</p>
+
+<p align="center">
+  <em>Universel multi-stack verifikations- og actionable diagnostics motor bygget på Robert C. Martin ("Uncle Bob") TDD, Clean Craftsmanship & Zero-Daemon WebAssembly</em>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/xgauntlet"><img src="https://img.shields.io/npm/v/xgauntlet.svg?color=blue" alt="NPM Version" /></a>
+  <a href="https://github.com/rolfmadsen/xGauntlet/actions/workflows/ci.yml"><img src="https://github.com/rolfmadsen/xGauntlet/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
+  <a href="docs/adr/0005-two-tier-verification-and-attestation-model.md"><img src="https://img.shields.io/badge/evidence-Two--Tier%20Trust%20Model-blue.svg" alt="Evidence Model" /></a>
+  <a href="wit/gauntlet_policy.wit"><img src="https://img.shields.io/badge/WASM-Zero%20Ambient%20Authority-purple.svg" alt="WASM Policy" /></a>
+  <a href="Cargo.toml"><img src="https://img.shields.io/badge/rust-2021%20edition-orange.svg" alt="Rust Version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+---
+
+**Dokumentation**: [Makro-Spec](spec.md) • [Domæne-Glossary](CONTEXT.md) • [Kodestandarder](CODING_STANDARDS.md) • [Arkitektur (ADRs)](docs/adr/)
+
+**Kildekode & Pakker**: [GitHub](https://github.com/rolfmadsen/xGauntlet) • [NPM Pakke](packages/cli)
+
+---
+
+**xGauntlet** omgiver AI-genereret kode med et kompromisløst verifikations-gauntlet (Linters, Type-checkere, Unit tests, Invariant-tests og Mutationsafprøvning), håndhæver en deterministisk **Zero Ambient Authority WebAssembly policy-kerne** (`wit/gauntlet_policy.wit`) og oversætter rå fejludskrifter til **Actionable Diagnostics** i et feedback-loop, som AI-agenter kan handle direkte på.
+
+Bygget i **Rust** for lynhurtig sub-3ms koldstart uden baggrundsdæmoner, og distribueret via **NPX** for øjeblikkelig brug på tværs af **Linux**, **macOS** og **Windows 11**.
+
+---
+
+## 🚀 Hurtig Start & Installation
+
+Kom i gang på under 10 sekunder uden forudgående installation via NPX:
+
+### 1. Initialiser dit projekt
+Stil dig i rodmappen på dit projekt (Rust, TypeScript, Python eller polyglot) og kør:
+
+```bash
+# Åbn dit projektkatalog
+cd ~/sti/til/dit-projekt
+
+# Scaffold samtlige in-repo styringsfiler direkte via NPX
+npx xgauntlet init
+```
+
+#### 📦 Hvad `xgauntlet init` opretter lokalt i projektet (In-Repo Single Source of Truth):
+| Fil / Mappe | Formål |
+|---|---|
+| [`gauntlet.toml`](gauntlet.toml) | Deklarativ konfiguration af lintere, typer, tests og verifikationslag |
+| [`CONTEXT.md`](CONTEXT.md) | Domæne-glossary for projektet (Aristoteles' *definitio per genus et differentiam*) |
+| [`CODING_STANDARDS.md`](CODING_STANDARDS.md) | Multi-stack kodestandarder og arkitekturinvarianter |
+| [`spec.md`](spec.md) | Makro-specifikation og system-invarianter |
+| [`tasks/001-bootstrap.md`](tasks/) | Opgavemappe til håndhævelse af task-kontrakter & acceptkriterier |
+| [`docs/adr/`](docs/adr/) | Architecture Decision Records (ADR) til projekt-specifikke beslutninger |
+| [`.agents/AGENTS.md`](.agents/AGENTS.md) | Retningslinjer for AI-agenter, Response HUD og task-management |
+| [`.agents/hooks.json`](.agents/hooks.json) | Pre-Invocation Hook til gatekeeperen |
+| [`CLAUDE.md`](CLAUDE.md) | Retningslinjer og sikkerhedsinvarianter for Claude Code |
+
+> [!TIP]
+> **🛡️ Ikke-destruktiv Garanti (Safety First):**  
+> `xgauntlet init` overskriver **aldrig** eksisterende filer i dit projekt, medmindre du udtrykkeligt angiver `--force`.
+
+### 2. Kør Verifikation & Tjek Evidens
+Når du eller agenten arbejder på en opgave i projektet, afvikles gauntlettet direkte:
+
+```bash
+# Kør gauntlet og forseg evidens for en opgave:
+npx xgauntlet verify --task-id 001-bootstrap
+
+# Valider kildetræets integritet mod rapporten (drift-kontrol):
+npx xgauntlet check-evidence
+
+# Valider opgavespecifikation og CONTEXT.md definitionsformat:
+npx xgauntlet check-spec
+
+# Kør miljø- og toolchain-diagnostik:
+npx xgauntlet doctor
+```
+
+> [!IMPORTANT]
+> **🚪 Zero Lock-in & Ren Afinstallation:**  
+> Alt ligger lokalt i dit Git-træ. xGauntlet efterlader ingen globale dæmoner, baggrundsprocesser eller systemændringer på din maskine.
+
+---
+
+## 🧭 Pipeline og Gates: Sådan virker det
+
+`xGauntlet` arbejder på to adskilte niveauer:
+1. **Metodiske retningslinjer (Agent Skills)**: Proceskrav (såsom sokratisk grilling, TDD-disciplin og arkitektur-review), som agenten instrueres i at følge (`grill-me`, `old-coder`, `code-review`).
+2. **Håndhævede software-gates (CLI & In-Memory WASM)**: Deterministiske kontrolpunkter i Rust-koden (`check-spec`, pre-invocation WASM hook, `verify`, `check-evidence` og `check-release`), der fysisk blokerer uautoriserede handlinger med exit-koder og multi-digest integritetskontrol.
+
+### Oversigt over udviklingsflowet
+
+```text
+[ 1. IDÉAFKLARING ]             ──► Metodisk skill (grill-me / grill-with-docs)
+         │                          (Opdaterer CONTEXT.md & docs/adr/)
+         ▼
+[ 2. SPECIFIKATION ]            ──► HÅRD GATE: xgauntlet check-spec
+         │                          (OKF metadata, formål, kriterier, Must NOT, Aristoteles-glossar)
+         ▼
+[ 3. TDD & KODNING ]            ──► HÅRD GATE: Zero-Ambient-Authority WASM Policy Hook
+         │                          (Kræver aktiv task for beskyttede stier, forhindrer git push)
+         ▼
+[ 4. FLERLAGS VERIFIKATION ]    ──► HÅRD GATE: xgauntlet verify
+         │                          (Kører linters, typer, tests; matematisk pre/post manifestkontrol)
+         ▼
+[ 5. KODESTANDARD-REVIEW ]      ──► Hybrid skill: code-review & udvikleraccept
+         │                          (Audit mod CODING_STANDARDS.md)
+         ▼
+[ 6. DRIFT-KONTROL ]            ──► HÅRD GATE: xgauntlet check-evidence
+         │                          (Verificerer at workspace matcher rapporten via Git OID hash)
+         ▼
+[ 7. RELEASE READINESS ]        ──► HÅRD GATE: xgauntlet check-release
+                                    (Versionssynkronisering, CHANGELOG.md og ADR-krydsreferencer)
+```
+
+### 👥 De 4 AI-roller & Session Handoff
+
+For at undgå uendelige review-loops (*bikeshedding*) og bevare et skarpt kontekstvindue, udleder `xGauntlet` automatisk den næste ingeniør-rolle:
+
+1. **`Senior Software Engineer (System Architecture & Requirements)`**:
+   * Aktiveres ved nye eller `DRAFT`-opgaver. Udfordrer antagelser, definerer negative invarianter (`## 🚫 Must NOT`) og eksekverbare kriterier via `xgauntlet check-spec`.
+2. **`Senior Software Engineer (Feature Implementation & Testing)`**:
+   * Aktiveres ved `ACTIVE`-opgaver. Driver TDD-cyklussen (`RED` $\to$ `GREEN` $\to$ `REFACTOR`) og forsegler evidens via `xgauntlet verify`.
+3. **`Senior Software Engineer (Independent Code Review & Audit)`**:
+   * Tager over i en frisk session. Udfører to-akset granskning langs **Akse A (Standarder)** jf. `CODING_STANDARDS.md` og **Akse B (Krav)** jf. `spec.md`/`tasks/`.
+4. **`Release & Operations Engineer (Release Attestation & Deployment)`**:
+   * Tager over når alle opgaver og audits er godkendt. Kører `xgauntlet check-release`, synkroniserer versioner og klargør release.
+
+---
+
+## 🎯 Arkitektur & Designprincipper
+
+1. **Uncle Bob Clean Architecture & TDD:**
+   * Forankret i de 3 Love for TDD, Transformation Priority Premise (TPP) og Single Responsibility Principle (SRP).
+2. **Package-by-Feature Struktur (Screaming Architecture):**
+   * Hver komponent er isoleret i en feature-underpakke under `crates/xgauntlet-core/src/features/` med høj sammenhørighed og lav kobling ([ADR 0001](docs/adr/0001-package-by-feature-architecture.md)).
+3. **Zero-Daemon & Sub-3ms Koldstart:**
+   * Pure native **Rust** eksekverbar binær. Ingen baggrundsdæmoner, ingen `systemd`/`launchd` services, ingen socket-nedbrud. Hver kommando udføres lynhurtigt in-process.
+4. **Nul Ambient Authority WebAssembly Policy Kerne ([ADR 0007](docs/adr/0007-local-transparent-supervisor-and-wasm-verifier.md)):**
+   * Policy-evaluering kompileres fra `wit/gauntlet_policy.wit` til `gauntlet_policy.wasm`.
+   * Eksekveres in-memory via indlejret **Wasmtime** med absolut nul adgang til filsystem, netværk, system-ur eller tilfældighedskilder.
+5. **Matematisk Anti-Tamper Manifest (Self-Mutation Invariant):**
+   * Pre- og post-test beregning af Git-tree/blob OID digests (immune over for Windows LF/CRLF konverteringer).
+   * Hvis kildekode eller testassertions muteres undervejs i testkørslen, afvises verifikationen øjeblikkeligt.
+6. **Two-Tier Evidens & Tillidsmodel ([ADR 0005](docs/adr/0005-two-tier-verification-and-attestation-model.md)):**
+   * `LOCAL_UNSUPERVISED`: Lokal deterministisk verifikationsrapport for hurtig feedback og matematisk drift-kontrol (`xgauntlet check-evidence`).
+   * `CI_ATTESTED`: Autoritativ, uafviselig Sigstore OIDC / in-toto attestation udstedt i et isoleret CI-miljø.
+7. **Multi-Harness Native Support ([ADR 0004](docs/adr/0004-harness-adapter-slices.md)):**
+   * Autonome vertikale slices for **Google Antigravity IDE**, **Claude Code** og **OpenAI Codex**.
+
+---
+
+## 🏗️ Mappestruktur (`Package-by-Feature`)
+
+```text
+xGauntlet/
+├── tasks/                        # Aktive og afsluttede opgavepakker (OKF v0.2)
+├── docs/adr/                     # Arkitekturbeslutninger (ADRs 0001-0007)
+├── CONTEXT.md                    # Domæne-glossary (Aristoteles' genus et differentiam)
+├── CODING_STANDARDS.md           # Multi-stack kodestandarder (Rust, TypeScript, Python)
+├── spec.md                       # Makro-specifikation & system-invarianter
+├── gauntlet.toml                 # Deklarativ multi-stack konfiguration
+├── wit/                          # WebAssembly Interface Types (gauntlet_policy.wit)
+├── Cargo.toml                    # Cargo Workspace root
+├── package.json                  # NPM Workspace root
+│
+├── crates/
+│   ├── gauntlet-policy-engine/   # Pure WASM component (wasm32-wasip1/wasip2)
+│   ├── xgauntlet-core/           # Portabel domænemotor (Package-by-Feature)
+│   │   └── src/features/
+│   │       ├── wasm/             # Embedded Wasmtime host integration
+│   │       ├── policy/           # Capability requests & trusted context
+│   │       ├── evidence/         # Git OID SHA-256 manifest & verification-report
+│   │       ├── gauntlet/         # Multi-layer runner, processtyring, timeouts
+│   │       ├── diagnostics/      # Actionable diagnostics parser
+│   │       ├── tasks/            # OKF v0.2 parser & check-spec
+│   │       ├── adapters/         # Vertikale harness-slices (Antigravity, Claude, Codex)
+│   │       ├── config/           # gauntlet.toml loader & schema
+│   │       ├── scaffold/         # Ikke-destruktiv init-motor
+│   │       └── doctor/           # Miljø- og toolchain-diagnostik
+│   │
+│   └── xgauntlet-cli/            # Native CLI executable (xgauntlet)
+│
+└── packages/
+    └── cli/                      # NPM distributionspakke (xgauntlet)
+        └── bin/xgauntlet.js      # Zero-dependency platform bootstrapper
+```
+
+---
+
+## 🛠️ Fuld CLI Reference
+
+### 1. Initialiser Workspace (`init`)
+```bash
+# Standard auto-detektering af stack
+xgauntlet init
+
+# Tving overskrivning af eksisterende skabeloner
+xgauntlet init --force
+```
+
+### 2. Kør Verifikations-Gauntlet (`verify`)
+Kør alle konfigurerede lag, udtræk actionable diagnostics og generer `verification-report.json` og `evidence.md`:
+```bash
+# Standard kørsel bundet til en opgave
+xgauntlet verify --task-id 001-bootstrap
+
+# Returner struktureret JSON med actionable diagnostics til LLM / AI-agenter
+xgauntlet verify --diagnostics-json
+```
+
+### 3. Validering af Evidens & Drift-kontrol (`check-evidence`)
+Verificerer at det aktuelle kildetræ matcher den lokale verifikationsrapport via Git-tree/blob OID digest:
+```bash
+xgauntlet check-evidence
+```
+
+### 4. Early-Phase Spec & Business Rules Gatekeeper (`check-spec`)
+Mekanisk validering af at opgavespecifikationer indeholder forretningsinvarianter (`Must NOT`), eksekverbare acceptkriterier og overholder [CONTEXT.md](CONTEXT.md) formatet:
+```bash
+xgauntlet check-spec
+```
+
+### 5. Release Readiness (`check-release`)
+Validerer at versioner matcher på tværs af manifests (`Cargo.toml`, `package.json`), `CHANGELOG.md` og ADR-krydsreferencer:
+```bash
+xgauntlet check-release
+```
+
+### 6. Workspace Diagnostik (`doctor`)
+Undersøg workspace-konfiguration, stakke og miljøforudsætninger på tværs af Linux, macOS og Windows:
+```bash
+xgauntlet doctor
+```
+
+---
+
+## 🦀 Rust API
+
+Du kan integrere `xgauntlet-core` direkte i dine egne Rust test-runners eller agent-værktøjer:
+
+```rust
+use std::path::Path;
+use xgauntlet_core::features::evidence::compute_workspace_manifest;
+
+// Beregn deterministisk kildemanifest (Git OID SHA-256 multi-digest)
+let manifest = compute_workspace_manifest(Path::new("."))?;
+println!("Source manifest digest: {}", &manifest.source_manifest_digest[..16]);
+```
+
+---
+
+## 🏛️ Arkitektur (ADRs)
+
+Projektets invariante tekniske valg og designprincipper er dokumenteret i [`docs/adr/`](docs/adr/):
+- 🏛️ **[ADR 0001](docs/adr/0001-package-by-feature-architecture.md)**: Package-by-Feature / Screaming Architecture
+- 🏛️ **[ADR 0002](docs/adr/0002-cryptographic-evidence-authority.md)**: Cryptographic Evidence Authority (Superseded by ADR 0005)
+- 🏛️ **[ADR 0003](docs/adr/0003-surgical-gatekeeper-and-no-remote-push.md)**: Surgical Gatekeeper and No Remote Push
+- 🏛️ **[ADR 0004](docs/adr/0004-harness-adapter-slices.md)**: Vertical Slice Harness Adapters
+- 🏛️ **[ADR 0005](docs/adr/0005-two-tier-verification-and-attestation-model.md)**: Two-Tier Verification and Attestation Model
+- 🏛️ **[ADR 0006](docs/adr/0006-multi-harness-policy-adapter-contract.md)**: Multi-Harness Policy Adapter Contract
+- 🏛️ **[ADR 0007](docs/adr/0007-local-transparent-supervisor-and-wasm-verifier.md)**: Zero-Daemon WASM Policy Verifier
+
+---
+
+## 🙏 Anerkendelse & Inspiration (Credits)
+
+`xGauntlet` bygger videre på idéer og pionerarbejde inden for stringent verifikation:
+- **[Robert C. Martin ("Uncle Bob")](https://x.com/unclebobmartin/status/2080257779395154409)**: For TDD, Clean Craftsmanship og idéen om at omgive koden med en uomgængelig *gauntlet*.
+- **[amazingang (old-coder)](https://github.com/amazingang/old-coder)**: For formuleringen af Evidence-First filosofien (*"Trust moves from inspection to constraints"*).
+- **[Matt Pocock](https://github.com/mattpocock)**: For sokratiske workflow-skills (`grill-me`, `grill-with-docs`, `code-review`).
+- **[Bytecode Alliance](https://bytecodealliance.org/)**: For Wasmtime og WebAssembly Component Model med formel Zero Ambient Authority.

package/bin/xgauntlet.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+/**
+ * xgauntlet - Universal cross-platform verification gauntlet for AI coding agents.
+ * Bootstrapper that resolves, caches, or downloads the native Rust engine binary.
+ */
+
+import { spawnSync, spawn, execFileSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgJsonPath = path.resolve(__dirname, '../package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+const VERSION = pkg.version;
+const REPO = 'rolfmadsen/xGauntlet';
+
+function getPlatformInfo() {
+  const platform = os.platform();
+  const arch = os.arch();
+  const isWindows = platform === 'win32';
+  const binName = isWindows ? 'xgauntlet.exe' : 'xgauntlet';
+
+  let archiveName = null;
+  if (platform === 'linux' && arch === 'x64') {
+    archiveName = 'xgauntlet-linux-x64.tar.gz';
+  } else if (platform === 'linux' && arch === 'arm64') {
+    archiveName = 'xgauntlet-linux-arm64.tar.gz';
+  } else if (platform === 'darwin' && arch === 'arm64') {
+    archiveName = 'xgauntlet-darwin-arm64.tar.gz';
+  } else if (platform === 'darwin' && arch === 'x64') {
+    archiveName = 'xgauntlet-darwin-x64.tar.gz';
+  } else if (platform === 'win32' && arch === 'x64') {
+    archiveName = 'xgauntlet-win32-x64.zip';
+  }
+
+  return { platform, arch, isWindows, binName, archiveName };
+}
+
+function getCacheDir() {
+  const { isWindows } = getPlatformInfo();
+  if (isWindows) {
+    const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    return path.join(base, 'xgauntlet', `v${VERSION}`);
+  }
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'xgauntlet', `v${VERSION}`);
+}
+
+function findLocalBinary() {
+  const { isWindows, binName } = getPlatformInfo();
+
+  // 1. Check Cargo target directory in local workspace
+  const devCandidates = [
+    path.resolve(__dirname, `../../../target/release/${binName}`),
+    path.resolve(__dirname, `../../../target/debug/${binName}`),
+  ];
+
+  for (const candidate of devCandidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  // 2. Check cached binary in ~/.cache/xgauntlet/vX.Y.Z/
+  const cacheDir = getCacheDir();
+  const cachedBin = path.join(cacheDir, binName);
+  if (fs.existsSync(cachedBin)) {
+    return cachedBin;
+  }
+
+  // 3. Check system PATH (making sure it's not this launcher)
+  try {
+    const checkCmd = isWindows ? 'where' : 'which';
+    const result = spawnSync(checkCmd, ['xgauntlet'], { encoding: 'utf8' });
+    if (result.status === 0 && result.stdout) {
+      const firstLine = result.stdout.trim().split(/\r?\n/)[0];
+      if (firstLine && fs.existsSync(firstLine)) {
+        const real = fs.realpathSync(firstLine);
+        if (real !== fs.realpathSync(__filename)) {
+          return firstLine;
+        }
+      }
+    }
+  } catch {
+    // Ignore error
+  }
+
+  return null;
+}
+
+async function downloadAndCacheBinary() {
+  const { platform, arch, isWindows, binName, archiveName } = getPlatformInfo();
+
+  if (!archiveName) {
+    throw new Error(`Unsupported platform or architecture: ${platform}-${arch}`);
+  }
+
+  const cacheDir = getCacheDir();
+  const targetBin = path.join(cacheDir, binName);
+
+  if (fs.existsSync(targetBin)) {
+    return targetBin;
+  }
+
+  const downloadUrl = `https://github.com/${REPO}/releases/download/v${VERSION}/${archiveName}`;
+  process.stderr.write(`[xgauntlet] Fetching native engine v${VERSION} for ${platform}-${arch}...\n`);
+
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const tempArchive = path.join(cacheDir, `temp-${Date.now()}-${archiveName}`);
+
+  try {
+    const res = await fetch(downloadUrl, { redirect: 'follow' });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+    }
+
+    const buffer = Buffer.from(await res.arrayBuffer());
+    fs.writeFileSync(tempArchive, buffer);
+
+    if (archiveName.endsWith('.tar.gz')) {
+      execFileSync('tar', ['-xzf', tempArchive, '-C', cacheDir], { stdio: 'pipe' });
+    } else if (archiveName.endsWith('.zip')) {
+      try {
+        execFileSync('tar', ['-xf', tempArchive, '-C', cacheDir], { stdio: 'pipe' });
+      } catch {
+        execFileSync('powershell', ['-NoProfile', '-Command', `Expand-Archive -Path '${tempArchive}' -DestinationPath '${cacheDir}' -Force`], { stdio: 'pipe' });
+      }
+    }
+
+    if (fs.existsSync(tempArchive)) {
+      fs.unlinkSync(tempArchive);
+    }
+
+    if (!isWindows && fs.existsSync(targetBin)) {
+      fs.chmodSync(targetBin, 0o755);
+    }
+
+    if (fs.existsSync(targetBin)) {
+      process.stderr.write(`[xgauntlet] Native engine v${VERSION} ready.\n`);
+      return targetBin;
+    } else {
+      throw new Error(`Extracted archive did not contain expected binary: ${binName}`);
+    }
+  } catch (err) {
+    if (fs.existsSync(tempArchive)) {
+      try { fs.unlinkSync(tempArchive); } catch {}
+    }
+    throw err;
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  let bin = findLocalBinary();
+
+  if (!bin) {
+    try {
+      bin = await downloadAndCacheBinary();
+    } catch (err) {
+      const { platform, arch } = getPlatformInfo();
+      if (args[0] === 'status' || args[0] === 'doctor') {
+        console.log('[xgauntlet] JavaScript Bootstrapper:');
+        console.log(`  Platform: ${platform} (${arch})`);
+        console.log(`  Version:  v${VERSION}`);
+        console.log(`  Engine:   NOT_FOUND (${err.message})`);
+        console.log('  Notice:   Run `cargo build --release` in xGauntlet repo or download v0.1.0 release.');
+        process.exit(0);
+      }
+
+      console.error(`\x1b[31m[xgauntlet] Error: Could not resolve native engine binary for ${platform}-${arch}.\x1b[0m`);
+      console.error(`  Details: ${err.message}`);
+      console.error(`  Tip: You can build it locally with: cargo build --release`);
+      console.error(`       Or install directly via Cargo: cargo install --path crates/xgauntlet-cli`);
+      process.exit(1);
+    }
+  }
+
+  const child = spawn(bin, args, { stdio: 'inherit' });
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "xgauntlet",
+  "version": "0.1.0",
+  "description": "Universal cross-platform verification gauntlet & tamper-proof policy sidecar for AI coding agents",
+  "bin": {
+    "xgauntlet": "bin/xgauntlet.js",
+    "xg": "bin/xgauntlet.js"
+  },
+  "type": "module",
+  "files": [
+    "bin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rolfmadsen/xGauntlet.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/rolfmadsen/xGauntlet/issues"
+  },
+  "homepage": "https://github.com/rolfmadsen/xGauntlet#readme",
+  "keywords": [
+    "ai-agent",
+    "verification",
+    "gauntlet",
+    "clean-craftsmanship",
+    "cross-platform",
+    "evidence"
+  ],
+  "author": "Antigravity Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}