# EL-JEFFE 4B

**A local-first, mobile-native 4B executive intelligence with trained judgment, deterministic runtime control, private retrieval, signed adapters, and receipts.**

This repository is a specification-and-build-control package. It is designed so a human team or coding agents can implement EL-JEFFE in phases without blurring the boundary between model capability and runtime machinery.

The package does **not** contain model weights, training data, application secrets, or a finished mobile application. It contains the contracts, plans, schemas, agent guidance, verification scripts, evaluation suites, design brief, and release gates required to build those assets safely.

## Product thesis

Train into the 4B checkpoint:

- Glyph fluency and semantic compression;
- authority, modality, scope, and substitution judgment;
- evidence discipline;
- bounded operational decisions;
- structured action generation;
- routing, abstention, repair, and escalation.

Keep outside the checkpoint:

- personal memory and accepted project truth;
- live facts and retrieval indexes;
- OS permissions, secrets, and capability leases;
- deterministic validation and policy enforcement;
- tool execution, rollback, receipts, adapter verification, and hardware scheduling.

The model proposes. Jefe Core validates. The device executes. Receipts prove what happened.

## Repository status

This package starts at **Phase 0: specification lock and build-control harness**. Every later phase requires a dated ExecPlan, machine-readable evidence, and a passing phase gate.

`EL-JEFFE 4B` is a research codename until the trained checkpoint clears the model gates. `The Boss of 4B` is prohibited in public claims until all canon gates and an independent reproduction pass.

## Preferred implementation architecture

| Layer | Initial choice | Reason |
|---|---|---|
| Deterministic core | Rust | Memory safety, portable libraries, strict types, reproducible validation |
| Mobile UI | SwiftUI and Jetpack Compose | Native accessibility, performance, platform trust surfaces |
| Primary model runtime | ExecuTorch | Sovereign deployment, mobile APIs, shared foundation weights with separately packaged LoRA programs |
| Benchmark runtime | LiteRT-LM on Android; optional MLC spike | Hardware comparison and fallback; not treated as parity until adapter and backend gates pass |
| Training and evals | Python, PyTorch, Transformers/PEFT-compatible tooling | Mature fine-tuning, quantization, and experiment ecosystem |
| Local store | SQLite + encrypted blobs + optional vector index | Inspectable, transactional, offline-first state |
| Protocol | JSON Schema during v0; compact binary encoding only after semantic gates | Auditability before compression cleverness |

Backend choice remains behind an `InferenceBackend` contract. No mobile framework receives architectural immunity from benchmark results.

## Quick start

Requirements for the specification harness:

- Python 3.12 or newer;
- Git;
- optional: `uv`, `pre-commit`, Claude Code, Cursor, Codex, GitHub Copilot.

Run:

```bash
python3 scripts/verify_repo.py
python3 scripts/gate_runner.py \
  --gates config/gates.json \
  --metrics examples/benchmark-result.example.json \
  --out artifacts/gate-report.example.json \
  --allow-incomplete
```

Or:

```bash
make verify
make test
make lint
make example-gates
```

The example metrics are deliberately incomplete and must never be interpreted as achieved results.

The verification harness also runs unit tests that prove complete synthetic metrics can evaluate to PASS, missing metrics remain INCOMPLETE, and any failed zero-tolerance authority check forces overall FAIL. See `PHASE_0_VERIFICATION.md` for the executed control-package evidence.

## Ask Claude to design the interface

Review the brief first:

```text
docs/design/CLAUDE_INTERFACE_DESIGN_REQUEST.md
```

Then run:

```bash
make claude-design
```

The script invokes the project-level `interface-designer` Claude subagent and instructs it to write design work only under:

```text
docs/design/claude-output/
prototype/design/
```

The design request demands information architecture, flows, tokens, components, native platform adaptations, trust surfaces, accessibility, motion, and a prototype/handoff plan. It explicitly rejects cowboy caricature, generic chat bubbles, decorative cyberpunk, and hidden permissions.

## Phases

| Phase | Purpose | Hard exit condition |
|---|---|---|
| 0 | Spec lock, agent controls, schemas, gate harness | `make verify` passes and all canonical docs are owned |
| 1 | Deterministic Glyph protocol, validator, receipts | Property tests and schema compatibility pass |
| 2 | Reference inference harness and baselines | Reproducible A/B/C/D comparison matrix runs |
| 3 | Data program and first EL-JEFFE training | Dataset cards, contamination checks, model card, reproducible train run |
| 4 | Prove trained weights matter | Model gates G01–G05 pass against the same base/runtime |
| 5 | Android sovereign runtime | Sustained device evidence and action-path demo pass |
| 6 | iOS sovereign runtime | Same protocol and security behavior; iOS performance evidence passes |
| 7 | Jefe Vault, FOVEA retrieval, private memory | Retrieval, privacy, and context-movement gates pass |
| 8 | Tools, approvals, rollback, and bounded loops | Zero unauthorized consequential actions in suite |
| 9 | Dynamic adapter supply chain | Adapter size, speed, compatibility, signature, and regression gates pass |
| 10 | Production interface implementation | Design acceptance, accessibility, and end-to-end task flows pass |
| 11 | Red-team, thermal, battery, and beta hardening | Security, reliability, and sustained mobile gates pass |
| 12 | Canon review and release | Independent reproduction and release council approval |

See `docs/PHASED_BUILD_PLAN.md` for entry criteria, deliverables, tests, and rollback conditions.

## Build protocol for humans and agents

1. Read `AGENTS.md`, the nearest nested `AGENTS.md`, `CLAUDE.md` when applicable, and the relevant specification.
2. Create an ExecPlan under `plans/active/` for work that crosses modules, changes a schema, modifies security behavior, or is expected to take more than one focused session.
3. Change one phase boundary at a time. Do not implement future-phase abstractions without an ADR and an immediate test.
4. Add or update tests before claiming a gate.
5. Run `make verify` and the narrowest relevant test command.
6. Write evidence under `artifacts/evidence/<phase-or-gate>/`; never edit generated evidence to make a gate pass.
7. Invoke the `benchmark-gatekeeper` or `security-auditor` agent for independent review when required.
8. Move an ExecPlan to `plans/completed/` only after acceptance criteria are demonstrated.

## Agent configuration included

- `AGENTS.md` and nested `AGENTS.md` files for Codex and compatible tools;
- `CLAUDE.md`, scoped `.claude/rules/`, specialized `.claude/agents/`, deterministic `.claude/hooks/`, and project settings;
- current `.cursor/rules/*.mdc` plus a legacy `.cursorrules` mirror;
- `.github/copilot-instructions.md` and path-specific Copilot instructions;
- portable Agent Skills under `.agents/skills/`;
- `GEMINI.md` for Gemini CLI;
- `.windsurf/` plus `.devin/rules/` compatibility controls and workflows;
- `.roomodes`, `.roorules`, and mode-scoped Roo instructions;
- `PLANS.md`, a drafted Phase 1 ExecPlan, and implementation/release templates;
- CI workflows, issue forms, pull-request template, pre-commit hooks, governance checks, and repository verification scripts.

All agent instructions are guidance. Hooks, tests, schemas, and CI are enforcement.

## Canonical source hierarchy

When documents disagree, use this order:

1. `docs/SECURITY_AND_AUTHORITY_INVARIANTS.md`;
2. approved ADRs in `docs/adr/`;
3. JSON Schemas in `schemas/`;
4. `docs/SYSTEM_ARCHITECTURE.md`;
5. `docs/PRODUCT_SPEC.md`;
6. phase ExecPlan;
7. agent instruction files;
8. generated design or implementation notes.

No agent may resolve a conflict by silently choosing the newest file. It must report the conflict.

## Absolute invariants

- A model-generated proposal never becomes accepted truth without a deterministic state transition.
- `PREFER` never becomes `REQUIRE`; `PROPOSE` never becomes `EXECUTE`.
- Identity-sensitive substitution requires explicit permission or approval.
- Exact evidence remains linked to exact source spans and hashes.
- Consequential actions require a capability lease, validator approval, execution result, and receipt.
- Personal content is local by default and never enters training artifacts.
- Adapters cannot override base authority, privacy, or receipt policy.
- No benchmark claim may omit device, OS, backend, quantization, context, thermal window, and artifact hashes.
- A gate cannot be passed by changing its threshold in the same pull request as the implementation under evaluation.

## Key documents

- `docs/PRODUCT_SPEC.md`
- `docs/SYSTEM_ARCHITECTURE.md`
- `docs/MODEL_TRAINING_SPEC.md`
- `docs/RUNTIME_SPEC.md`
- `docs/GLYPH_PROTOCOL.md`
- `docs/BENCHMARK_GATES.md`
- `docs/PHASED_BUILD_PLAN.md`
- `docs/THREAT_MODEL.md`
- `docs/design/CLAUDE_INTERFACE_DESIGN_REQUEST.md`
- `docs/research/AGENT_TOOLING_RESEARCH.md`
- `docs/AGENT_OPERATIONS.md`
- `docs/TEST_STRATEGY.md`
- `PHASE_0_VERIFICATION.md`
- `PACKAGE_CONTENTS.md`

## Licensing and model selection

No base model is selected by this package. Phase 2 must produce a signed decision record covering model license, architecture, tokenizer behavior, export support, multimodality, quantization quality, adapter support, safety obligations, and measured mobile performance.

Do not add a model or dataset to the repository until its license and redistribution constraints are documented.