# Ferret Kernel System

> Ferret frozen-gate kernel system — how to invoke + why

- Skill: `mirage-project/ferret-kernel-system` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mirage-project/ferret-kernel-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mirage-project/ferret-kernel-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mirage-project (https://skillmd.com/u/mirage-project)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mirage-project/ferret-kernel-system

---


# Ferret frozen-gate kernel system — how to invoke + why

## The problem it solves (read first)
The OLD ferret wrote its OWN correctness test. It once shipped a DeepSeek-V3
attention kernel with SIMPLIFIED math (theta-10000 rope not YaRN, 1/sqrt(576) not
the YaRN mscale scale, head-sum o_proj skipping W_UV, no kv_a_layernorm) and
self-reported **cosine 1.0** — against its own simplified reference. Marking its
own homework. The refactor takes judging + constraints OUT of the optimizer.

## The 3 agents (in `.claude/agents/`)
| Agent | Role | You invoke? |
|---|---|---|
| **ferret-kernel-agent** (L1 dispatcher) | The ENTRY POINT. Pins ALL constraints, freezes the gate via the test-writer, runs the optimizer in-session, drives Codex review each round, does in-MPK faithful acceptance. | **YES — this is the only one you invoke directly.** |
| **ferret-test-writer** (L2a) | Writes the FROZEN, hash-locked gate vs a CANONICAL reference (never re-derived), checking INTERMEDIATE tensors. Spawned by L1, before the optimizer. | No (L1 spawns it) |
| **ferret-optimizer** (L2b) | In-session optimizer (replaces `claude -p`), judged ONLY by the frozen gate, can't simplify. Spawned by L1 each round. | No (L1 spawns it) |

## How to invoke (the main-thread → subagent contract)
Invoke the **ferret-kernel-agent** subagent (via the Agent tool) with a COMPLETE
constraint contract — this is where nothing gets missed and no simplification slips
in. Give it, explicitly:
1. **TARGET** — the exact MPK op + what it replaces; the baseline = the kernel being
   replaced, benched the way MPK calls it (not an external SOTA unless it's the consumer).
2. **REAL-MATH CONTRACT** — enumerate EVERY step the kernel must compute, NO
   simplification (the test-writer turns this into intermediate checks).
3. **SHAPES** — exact (M,K,N) at the real TP/EP regime (derive from the builder/weights).
4. **PRODUCTION COMPILE FLAGS** — `-rdc=true` / `MPK_FORCE_RDC_TRUE=1`, arch sm_100a,
   single-stream / no-CUDA-graph / no-cta_group::2. State that FINAL acceptance is the
   in-MPK faithful build; standalone `-rdc=true` is diagnostic only.
5. **ABI** — the `__device__ task_impl` signature + NS/NE.
6. **CANONICAL REFERENCE SOURCE** — the already-trusted oracle to compare against
   (the in-MPK task-chain output; the official HF model; an in-tree faithful test).
   NEVER "let the agent derive it."
If the gate already exists (hash-locked in the workspace), tell L1 to reuse it
(hash-verify) and go straight to the optimizer loop.

## The invariants that make it trustworthy (Codex-hardened — gate fidelity is load-bearing)
- The gate is built by the **independent test-writer**, not the optimizer.
- The reference is **CANONICAL** (validated against a trusted source), never re-derived.
- The gate checks **INTERMEDIATES** (golden vectors per stage), not just a final cosine
  — a deep simplification (a dropped layernorm, a wrong rope base) is caught at the
  first diverging stage (`first_failing_stage`), not washed out.
- Multiple metrics + edge cases (long-context, boundary positions).
- The gate is **sha256 hash-locked**; L1 re-verifies the hash before EVERY round
  (tamper = abort).
- The optimizer is judged ONLY by `gate/check.py`. **Codex** reviews each round on two
  axes — Integrity (did it simplify to pass?) + Plan (is the lever sound?).
- **FINAL acceptance = in-MPK faithful build** (`MPK_FORCE_RDC_TRUE=1`, compiled into
  the real megakernel). A standalone number never ships.
- **Early stop = round incomplete, never success.**

## Proof it works
Re-run on the simplified attention: the optimizer (judged by the frozen gate) built a
CORRECT real-DSv3 fused attention in round 1 — `GATE_RESULT {pass:true}` on all 5
cases / all intermediates, gate untouched, dump provenance verified (W_UV BMM present,
real mscale²/sqrt(192) scale), all 4 simplifications fixed, Codex Integrity+Plan PASS.
The old simplified-kernel failure is now structurally impossible.

## Reference
Full design + the /cd-mechanics + the hardening rationale: `DESIGN.md` (bundled
alongside this skill). The ferret runtime itself lives at
`~/ferret/` (its `CLAUDE.md` is the optimizer's methodology). Pre-authored task specs:
`~/ferret/tasks/`.