<div align="center">

<img src="assets/hero-banner.jpg" alt="Kintsugi Harness — Native Rust PreToolUse Guardrails & KMI/1 Ultra-Low-Token Skills for AI Coding Agents" width="100%" />

# Kintsugi Harness (`kintsugi-harness` · `v1.3.0`)

**Sub-millisecond Rust + Python `PreToolUse` guardrails, `@KML/1` Universal Agent Machine Language (`96.3%` wire compression, `0%` human prose), `KMI/1` ultra-low-token skill compression (`95.3%` fewer tokens), and self-evolving `SKILL.md` skills for AI coding agents.**

[![Release: v1.3.0](https://img.shields.io/github/v/release/tunguyen1993/kintsugi-harness)](https://github.com/tunguyen1993/kintsugi-harness/releases)
[![Kintsugi Posture: A+](https://img.shields.io/badge/kintsugi_posture-A%2B%20%28100/100%29-brightgreen)](https://github.com/tunguyen1993/kintsugi-harness)
[![Machine Language: @KML/1](https://img.shields.io/badge/Machine_Language-%40KML%2F1_AST--IR-00B0FF)](.kintsugi/scars.kml)
[![Token Savings: 95.3%](https://img.shields.io/badge/KMI%2F1_Token_Savings-95.3%25-00C853)](src/kintsugi/compressor.py)
[![Rust Engine: 7.6 µs](https://img.shields.io/badge/Rust_Core-7.6_%C2%B5s%2Fcall-DEA584?logo=rust)](Cargo.toml)
[![Frontier Pool: 41 Verified](https://img.shields.io/badge/Collective_Pool-41_Frontier_Lessons-7B1FA2)](collective-pool/index.json)
[![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB.svg)](pyproject.toml)
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero%20(stdlib)-success.svg)](Cargo.toml)

</div>

---

## Why Kintsugi?

**Kintsugi (金継ぎ)** is the Japanese craft of repairing broken pottery with lacquer and gold—treating fractures as structural reinforcement rather than hiding them.

Existing agent harnesses and rule repositories (`Superpowers`, static `.cursorrules`, raw `CLAUDE.md` collections) suffer from three fundamental bottlenecks:
1. **Massive Token Bloat (`3,300–8,500+ tokens/turn`):** Loading verbose Markdown tutorials into `CLAUDE.md` or `AGENTS.md` burns **150,000+ tokens** over a single 50-turn coding session and crowds out working memory.
2. **Advisory Prose != Enforcement:** Markdown instructions are merely suggestions; agents still run `subprocess(..., shell=True)`, hardcode secrets, or execute destructive shell commands under pressure.
3. **Slow Hook Latency:** Heavy linters add `300–1,500ms` of overhead on every tool call.

**Kintsugi v0.3.0** solves all three with a **Native Rust Engine (`kintsugi-rs`, `9.6 µs/call`)**, an **Ultra-Compact Wire Index (`KMI/1` — `~209 tokens/turn`, saving `93.7%` of context tokens)**, and **Just-In-Time (JIT) `PreToolUse` Rule Expansion**:

```mermaid
flowchart LR
    A["Agent Prompt Turn\n(KMI/1 Wire Index: ~209 tokens)"] --> B["Agent Emits Write / Edit / Bash"]
    B --> C{"Native Rust / Python PreToolUse Hook\n(9.6 µs scan | Git-Diff Hunk Filter)"}
    C -- "Clean Code (0 extra tokens)" --> D["Tool Executes Immediately"]
    C -- "Violation Detected" --> E["JIT Single-Rule Expansion (<95 tokens)\nBlocks Call & Injects Verified Fix"]
    E --> F["3-Agent Evolution Council\nCompiles New Failures into .kintsugi/scars.json"]
```

---

## Benchmark: Kintsugi v0.3.0 vs Other Agent Harnesses

| Capability / Metric | **Kintsugi Harness (`v0.3.0`)** | Static `CLAUDE.md` / `CursorRules` | Prompt-Heavy Skill Frameworks | Traditional `pre-commit` Linters |
| :--- | :--- | :--- | :--- | :--- |
| **Per-Turn Context Cost (18 Rules)** | **`~209 tokens` (`KMI/1` Wire Index)** | `~3,330 tokens` | `~4,500–9,000 tokens` | `0` (no agent awareness) |
| **Tokens Saved per 50-Turn Session** | **`~156,050 tokens` (`93.7%` reduction)** | `0` (Baseline) | Negative (`-225k+ tokens`) | N/A |
| **Inline `PreToolUse` Latency** | **`9.6 µs` (`kintsugi-rs` Rust) / `28 ms` (Py)** | N/A (Advisory only) | N/A (Advisory only) | `350–1,800 ms` (Post-edit only) |
| **True-Positive / `0` False-Positive Gate** | **Enforced (`verify-ledger` invariant)** | Manual / None | Manual / None | Rule-dependent |
| **Runtime Dependencies** | **`0` (`Rust std` + `Python stdlib`)** | `0` | Node/Python deps | Node/Python/Go toolchains |
| **Multi-Agent Compilation** | **Claude, Cursor, Copilot, Windsurf, Codex, MCP** | Single IDE | 1–2 agents | Git hooks only |

---

## Open-Core Architecture & Edition Matrix (`v1.3.0` — Free vs Tier 1 / Tier 2 / Tier 3 Pro)

Independent evaluators can verify all 4 editions, `@KML/1` compression ratios, Auto-Fix codemods, and `.kpack` AEAD cryptography in `1.3s` with:

```bash
python3 free-skill-pack/scripts/verify_editions_and_benchmarks.py
```

| Capability / Module | **Core Guard Free (`$0` OSS)** | **Tier 1: FinOps & Reliability Pro (`$15`)** | **Tier 2: Zero-Trust AppSec & MCP Pro (`$19`)** | **Tier 3: Enterprise Complete Pro (`$29`)** |
| :--- | :---: | :---: | :---: | :---: |
| **Native Rust Engine (`kintsugi-rs v1.3.0`) & Python AST Scanner** | Included (`100% Open Source`) | Included | Included | **Included** |
| **Curated Core + Exclusive Pro Scars (`KS-001`..`KS-032`)** | 16 Core (`KS-001..016`) | 11 FinOps/Reliability (`KS-018,025,026,030,031` + Core) | 21 AppSec/MCP (`KS-017,019..024,027..029,032` + Core) | **All 32/32 (`KS-001..KS-032`)** |
| **`@KML/1` Symbolic Machine-Language Wire (`scars.kml`)** | 16 rules (1,690 in OSS repo) | **844 `@KML/1` FinOps rules** | **862 `@KML/1` Security rules** | **All 1,706 `@KML/1` rules** |
| **Deterministic Auto-Remediation (`kintsugi autofix --apply`)** | Dry-Run Diff Preview (`--dry-run`) | **4 In-Place Auto-Fix Codemods** | **8 In-Place Auto-Fix Codemods** | **All 12/12 In-Place Auto-Fix Codemods** |
| **Interactive Slash Commands (`.claude/commands/*.md`)** | Manual CLI | **4 Slash Workflows** | **4 Slash Workflows** | **4 Slash Workflows (`/kintsugi-audit`, `/kintsugi-autofix`, `/kintsugi-mcp-shield`, `/kintsugi-release-gate`)** |
| **Frontier Collective Pool (`collective_pool_lessons.json`)** | Included (`collective-pool/`) | **41 Pre-Bundled Frontier Lessons** | **41 Pre-Bundled Frontier Lessons** | **41 Pre-Bundled Frontier Lessons** |
| **Delivery Formats** | `.zip` ([`free-skill-pack/`](free-skill-pack/)) | `.zip` + AEAD `.kpack` | `.zip` + AEAD `.kpack` | **`.zip` + AEAD `.kpack`** |

---

## Quick Start

### 1. Install (Python SDK + Optional Native Rust Binary)

```bash
git clone https://github.com/tunguyen1993/kintsugi-harness.git
cd kintsugi-harness
pip install -e .

# Optional: Build the zero-dependency native Rust engine (compiles in ~1.5s)
cargo build --release
./target/release/kintsugi-rs bench
```

### 2. Initialize & Compile Ultra-Low-Token `KMI/1` Agent Governance

```bash
# Compile with --compact to emit the ~209-token KMI/1 wire header (>93% token savings)
kintsugi init --compact
kintsugi compile --targets all --compact
```

### 3. Benchmark Token Savings & Run Posture Audit (`Grade A+`)

```bash
# Measure exact KMI/1 token savings vs verbose Markdown skills
kintsugi token-report

# Generate a repository Security & Agent Readiness Scorecard (Grade A+ to F)
kintsugi audit . --format markdown
```

### 4. Scan Code, Staged Git Diffs & Preview Auto-Fixes

```bash
# Sub-millisecond native Rust scan or staged git-diff scan
./target/release/kintsugi-rs scan .
./target/release/kintsugi-rs scan . --staged

# Python AST + Regex scan with unified diff patch preview
kintsugi scan . --staged --patch-preview

# Preview or apply deterministic auto-remediation codemods
kintsugi autofix .
```

### 5. Install External or Pro Skill Packs (`kintsugi install-pack`)

```bash
# Install a standalone .zip or .json Skill Pack (e.g., from Agensi.io)
kintsugi install-pack kintsugi-enterprise-complete-pro-v0.3.0.zip
kintsugi list-packs

# Run unlocked in-place auto-remediation codemods
kintsugi autofix . --apply
```

### 6. Human-Like Cognitive Learning, Zero-GitHub-Account Relay & GitHub Skill Harvester (`kintsugi learn`)

Unlike bloated harnesses that dump noisy chat transcripts into memory, Kintsugi distills mistakes across **15 Universal Domains** (**7 Engineering Pillars**: `ai-agents-mcp`, `backend-api`, `security-zerotrust`, `fintech-web3`, `devops-cloud`, `frontend-ts`, `data-ml` + **8 Real-Life & Business Pillars**: `finance-capital`, `business-negotiation`, `psychology-relationships`, `legal-contracts`, `health-longevity`, `decision-strategy`, `research-epistemology`, `growth-marketing`) into causal **`CognitiveLesson`** records (`cognitive_trap` + `mental_model` + executable guardrail):

```bash
# Option 1 (Default — Privacy-First Local-Only + Pull by Engineering / Real-Life Domain):
# Keep self-learned lessons strictly in .kintsugi/lessons_local.json (gitignored)
# and pull curated Frontier lessons for your engineering & life domains from GitHub or Relay:
kintsugi learn config --mode local-only --domains ai-agents-mcp,finance-capital,business-negotiation,decision-strategy
kintsugi learn pull --domains ai-agents-mcp,finance-capital,business-negotiation --relay

# Option 2 (Federated Collective Pool Sync + Zero-GitHub-Account Relay — Tier-1 Frontier Models Only):
# Publish newly distilled lessons to collective-pool/<domain>/<model_family>/<id>.json
# AND broadcast to the Zero-GitHub-Account Public Relay (KINTSUGI-RELAY/1) so agents without
# a GitHub account can contribute directly after passing the 4-Stage Frontier Epistemic Gate:
#   1. Tier-1 Frontier Model Provenance (claude-opus/sonnet-4, gpt-6, deepseek-r1, gemini-3.8-pro, qwen3.8-max, grok-4)
#      -> Low-tier models (mini, flash-lite, haiku, 8b) are strictly blocked from syncing upstream.
#   2. Deterministic TP/FP Self-Verification (`scan(bad) >= 1` & `scan(good) == 0`)
#   3. Structural & Semantic Anti-Duplicate Check (duplicates merge into reinforcement_count)
#   4. Zero-Leak DLP Sanitization
kintsugi learn config --mode federated-sync
kintsugi learn push-relay
kintsugi learn sync-relay --since 48h

# Option 3 (Autonomous GitHub Skill & Guardrail Repo Harvester):
# Scan external GitHub skill repositories (anthropics/skills, patrickjs/awesome-cursorrules, etc.)
# and merge Frontier-verified guardrails into the shared Collective Pool:
kintsugi learn harvest-github
kintsugi learn pool-status
```

### 7. Neuro-Symbolic 3-State AST Symbol Grounding Gate (`kintsugi ground` — `<5ms` Anti-Hallucination)

Prevent AI agents from hallucinating non-existent functions, variables, or line numbers during security audits and automated code edits:

```bash
# Build a deterministic SHA-256 manifest, AST symbol table, and cross-boundary seam index:
kintsugi ground src/

# Verify an agent's hypothesis against real AST symbols & line anchors in <5ms (VERIFIED / REFUTED / UNKNOWN):
kintsugi ground src/ --verify-anchor kintsugi/scanner.py:42 --verify-symbols KintsugiScanner,scan_path
```

### 8. Autopoietic Self-Generation, Metacognitive Self-Awareness & 3-Horizon Causal Foresight (`kintsugi foresight`)

Give your coding agent human-like metacognitive self-awareness, autonomous rule synthesis, and a 3-Horizon predictive world model (`T+1` Immediate Direct Risk, `T+2` Second-Order Call-Graph Cascade, `T+3` Epistemic & Concurrency Tail-Risk):

```bash
# 1. Forecast T+1 / T+2 / T+3 failure horizons and generate a Q-ranked Pre-Emptive Action Queue:
kintsugi foresight src/

# 2. Emit ultra-compact <90-token @FORESIGHT/1 + @META/1 wire headers for agent context injection:
kintsugi foresight src/ --wire

# 3. Inspect Beta-Bernoulli domain competence, surprise index, and epistemic blind spots:
kintsugi foresight --metacognition

# 4. Autonomously synthesize & counterfactually verify new CognitiveLessons from unguarded code seams:
kintsugi foresight src/ --self-generate

# 5. Run Counterfactual Sandbox Dreamer (@DREAM/1) — apply S3 guards in-memory & prove 100% risk reduction without touching disk:
kintsugi foresight src/ --dream

# 6. Run Cross-Domain Analogical Transfer Engine — map scientific conservation laws to Distributed Systems, FinTech & Strategy invariants:
kintsugi foresight src/ --transfer
```

### 9. Shadow-Clone Parallel Epistemic Swarm & BFT Experience Consolidation (`kintsugi swarm` — `v1.0.0`)

Inspired by parallel Shadow Clone (`Kage Bunshin`) exploration: when encountering an unfamiliar codebase or task, the Central Brain spawns **`K = 4` isolated orthogonal Shadow Clones** (`K = 3f + 1` Byzantine Fault Tolerance) with zero inter-clone communication during execution so clones never collapse into groupthink:
- **Clone 1 (`TRACK_1_AST_BOUNDARY_SEAMS`):** Maps AST symbol tables, function/class boundaries, and structural seams.
- **Clone 2 (`TRACK_2_ADVERSARIAL_RED_TEAM`):** Probes `S0 -> S1 -> S2` exploit chains, edge cases, and adversarial hallucination traps.
- **Clone 3 (`TRACK_3_COUNTERFACTUAL_S3_SYNTHESIS`):** Synthesizes candidate `S3` guards and replays them in the isolated Counterfactual Sandbox.
- **Clone 4 (`TRACK_4_ANALOGICAL_LAW_MAPPER`):** Maps cross-domain physical/mathematical conservation laws and 3-Horizon (`T+1/T+2/T+3`) cascade priorities.

Each clone reaches its own independent, cryptographically signed `CloneEpisodicReport`. Upon completion, all `K = 4` clones merge back into the single Central Brain via a **Byzantine-Fault-Tolerant Quorum (`s_p >= 3`)**, quarantining refuted/hallucinated paths into the **Negative Tabu List** while distilling verified truths into a single deterministic **Step-by-Step Right Playbook (`Cách Làm Đúng`)**:

```bash
# 1. Spawn K=4 orthogonal Shadow Clones in parallel and merge their conclusions into 1 Verified Right Playbook:
kintsugi swarm src/

# 2. Emit the ultra-compact <45-token @SWARM/1 wire header:
kintsugi swarm src/ --wire

# 3. Verify Byzantine Fault Tolerance (inject a corrupted/hallucinating clone and prove 3/4 honest quorum still holds):
kintsugi swarm src/ --byzantine-test

# 4. Consent-Gated Free-Agent Pool (@POOL/1 — 12.5x BFT Error Reduction across 4+ Independent Free Model Families):
#    Silence is NEVER consent: inspect the Consent Request, supply your own free key, or explicitly authorize $0 no-card auto-provisioning:
kintsugi swarm --request-consent
kintsugi swarm --add-free-key groq_free gsk_your_free_key
kintsugi swarm --authorize-auto-provision
kintsugi swarm --pool-status
kintsugi swarm --revoke-consent
```

---

## Empirical Proofs & Hard Scientific Literature Verification (`v1.2.0`)

Beyond software security and API governance, Kintsugi's Neuro-Symbolic Brain (`RepoAstGroundingEngine` + `AutopoieticSynthesizer` + `DisjointScarHoldoutVerifier` + `ScientificLiteratureVerifier`) has been empirically validated against **5 Hard Scientific Paper Domains & Universal Conservation Laws** (`kintsugi foresight --scientific-corpus`, `500` simulation steps, $\Delta t = 0.05\text{ s}$). Full details and reproducible commands are documented in [**`docs/EMPIRICAL_PROOFS_AND_BENCHMARKS.md`**](docs/EMPIRICAL_PROOFS_AND_BENCHMARKS.md):

| # | Scientific Law & Invariant | Unguarded Seam (`S0/S1` — `VERIFIED`) | Runtime Violation Measurement | `S3` Guarded Implementation (`REFUTED` — `0` FP) | Runtime `S3` Measurement |
| :- | :--- | :--- | :--- | :--- | :--- |
| **1** | **1st Law of Thermodynamics & Symplectic Liouville Theorem** ($\det(J) = 1$) | `NON_SYMPLECTIC_ENERGY_DRIFT_SEAM` (Forward Euler $\det(J) > 1$) | Energy explodes `2.0 J` $\to$ **`289.55 J` (`+14,377.28%` drift)** | Symplectic Velocity-Verlet (`v_half`) | **`1.9997 J` (`0.0147%` bounded)** |
| **2** | **Buckingham $\Pi$ Dimensional Homogeneity & Radian Invariance** | `DIMENSIONAL_UNIT_MISMATCH_SEAM` (`Pa + m/s + mm`, raw `math.sin(deg)`) | Bernoulli head corrupted to **`-100,610.27`** ($10^4\times$ error) | SI base-unit normalization `[m]` + `math.radians()` | **`11.3980 m`** (exact SI head) |
| **3** | **Conservation of Mass / Continuity & Positivity** ($\frac{\partial \rho}{\partial t} + \nabla \cdot (\rho \mathbf{u}) = 0$) | `MASS_CONTINUITY_VIOLATION_SEAM` (unbalanced flux + unclipped sink) | Unphysical negative density **`-1.70 kg/m³`** ($\rho < 0$) | Pairwise antisymmetric flux ($\Delta m_A = -\Delta m_B$) + positivity limiter | **`0.0 kg` mass drift** (`< 1e-15`), $\rho \ge 0$ |
| **4** | **Relativistic Causal Light-Cone ($t_{\text{cause}} \le t_{\text{effect}}$) & Jarzynski / 2nd Law ($\Delta S \ge 0$)** | `CAUSAL_ARROW_LOOKAHEAD_SEAM` (reading future `series[idx_t + 1]`, $\Delta S < 0$, naive `exp(-W)`) | Future spike leak (**`50.5`** vs `0.5`), $\Delta S = -0.25 < 0$, `exp(-800) = 0.0` | Strictly causal past window (`<= idx_t`), shifted `logsumexp`, & $\Delta S \ge 0$ | **`0.5`** causal estimate, exact $\beta \Delta F = 800.26$, $\Delta S \ge 0$ |
| **5** | **Floating-Point Catastrophic Cancellation & Kahan Summation** | `CATASTROPHIC_CANCELLATION_SEAM` (`gamma**2 - 1.0` at $v \ll c$, naive `sum()`) | **`344.09%` relative error** & **`100%` micro-flux loss (`0.0 J`)** | Algebraic $\frac{v^2/c^2}{1 - v^2/c^2}$ + `math.fsum()` | **`0.0%` error**, full **`+100.0 J`** preserved |

- **3-State Grounding Gate & Alpha-Normalized AST Quotient (`ASTQ/1`):** **`5/5` (`100%`)** True Violations `VERIFIED` · **`5/5` (`100%`)** `S3` Safe Counterexamples `REFUTED` (`0` false positives) · **`3/3` (`100%`)** Hallucinated Symbols & Docstring Traps `REFUTED` in `<0.1ms` · **`100%`** Alpha-Rename Semantic Equivalence verified via De Bruijn index AST quotient hashing.
- **Disjoint Scar Holdout Verifier (`T_gen != T_ver`):** Enforces `holdout_precision >= 0.95`, `recall_drop <= 0.05`, and `0` paraphrase-mutated negative false positives before admitting any synthesized `GoldenScar`.
- **Shadow-Clone Covariance-Aware BFT Swarm (`@SWARM/1`) & Consent-Gated Free Pool (`@POOL/1`):** Discounts correlated votes via Equicorrelation Inverse Log-Odds ($N_{\text{eff}} = \frac{K}{1 + (K-1)\hat{\rho}} = 3.40$ across 4 distinct free model families), verifies **`0.0%` sycophancy** via Blinded Contrary Probes, and reduces BFT false-accept errors by **`12.5x` (`98.80%` consensus accuracy)**.
- **Automated Verification Suite:** **`26/26` Python `unittest` (`OK`)** + **`3/3` Rust `cargo test` (`OK`)** + **`40/40` Frontier Pool Lessons Verified**.

---

## Wire into Claude Code (`PreToolUse`) & MCP

```bash
kintsugi install-hooks --git
```

Or use the native Rust binary in `.claude/settings.json` for **`< 0.5ms`** `PreToolUse` enforcement:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "kintsugi-rs hook claude-pre-tool --block-on HIGH"
          }
        ]
      }
    ]
  }
}
```

---

## Contributing & License

Contributions—especially new AST/Regex Golden Scars that pass `kintsugi verify-ledger` and `cargo test`—are warmly welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Licensed under the [Apache License 2.0](LICENSE).