Lamprey-Harness

How changes are classified, gated, approved, committed, and shipped in the Lamprey Harness repo. Load this BEFORE making any change — code, docs, config, or release — or when you see terms like P-SPR, STS, verify gate, era-lock, commit trailer, push policy, or when a commit/push is rejected by a hook.

How Lamprey runs and ships — run modes, userData layout, Windows release artifacts, the one-command "Bucket" pipeline, macOS/Linux CI mirroring, GitHub publication, CDN purge, and failure recovery. Load when the user says "ship", "release", "tag it", "Bucket", or when a release step fails partway.

The multi-provider LLM domain pack for Lamprey — OpenAI-compatible streaming across 17 built-in providers (frontier labs, open-source hosts, keyless local runtimes) plus user-defined custom endpoints, per-provider quirks (reasoning field names, Anthropic's compat-layer limits, base-URL overrides), capability flags, the native-vs-fallback tool-calling contract, retry/backoff, retired-model handling, and the checklists for adding a model or a provider. Load when touching electron/services/providers/, debugging provider HTTP errors, or adding/retiring models.

Lamprey's load-bearing design decisions, the invariants that must hold, what was deliberately deleted, and the honestly-stated weak points. Load before modifying electron/ipc, electron/services, the provider or tool layers, or the renderer stores — or when you need to know WHY the system is shaped the way it is.

Recreate the Lamprey dev environment from scratch and get past its known traps — Node/Electron/better-sqlite3 ABI story, the ELECTRON_EXEC_PATH dev-server workaround, esbuild antivirus blocks, the tsconfig node/web split, electron-vite and electron-builder specifics. Load when setting up a machine, when npm install / dev server / build fails, or before touching build configuration.

Catalog of every Lamprey configuration axis — AppSettings keys with defaults and readers, inert retired keys, keychain/keys.json, custom models, loop and timeout knobs, environment variables, per-conversation runtime state — plus the exact checklist for adding a setting without breaking the parity-lock test. Load when reading/changing settings.json, adding a setting, or wondering what a flag does or whether anything still reads it.

The Lamprey data layer in depth — lamprey.db schema init and the migration ledger (v1–v18), the safe-migration checklist written in the shadow of the v0.9.2 crash, transactional guarantees, FTS5, the RAG store and sqlite-vec, retention sweeps, backups, and atomic JSON persistence. Load before touching schema-init.ts, db-migrations.ts, conversation-store.ts, rag/store.ts, or when investigating any data corruption/loss.

Symptom-to-triage playbook for the Lamprey Harness's real failure modes — chat sends failing with SQL errors, hung or ghosted turns, loops misfiring or duplicating, provider HTTP errors, malformed tool calls, silently skipping tests, vanished keys/settings, renderer state bleed, dev server exiting instantly. Load when something is broken and you need the fastest discriminating check.

How to MEASURE Lamprey instead of eyeballing it — verify-proof and its skip accounting, the smoke scripts, streaming vitals, the events/tool_calls audit tables, the reasoning trace surface, prompt byte measurement, token accounting — plus tested read-only inspection scripts (db-health.cjs, loop-state.cjs) shipped in this skill's scripts/ directory. Load when you need numbers, evidence, or an incident timeline rather than an impression.

Maintaining Lamprey's documents of record — CLAUDE.md, DEVLOG.md, README.md, ARCHITECTURE/, PLANNING/ — with the exact DEVLOG entry template, the README-on-every-ship checklist, commit-message house style, the no-slop/no-fake-polish doctrine, and the rules for what may be claimed publicly. Load when writing any DEVLOG/README/plan/commit text, wrapping a phase, or making public claims about the project.

The chronicle of every major Lamprey investigation, incident, dead end, rejected fix, and deletion — symptom, root cause, evidence, resolution, status — so nobody re-fights a settled battle or rebuilds something that was deliberately removed. Load when a bug looks familiar, when you find code or docs referencing subsystems you can't locate, or before proposing a fix for anything.

The executable, decision-gated campaign for Lamprey's hardest live problem — proving loop autonomy (interval / self-paced / autonomous backlog) reliable in real use. Numbered phases with exact commands, expected observations at every gate, a ranked solution menu for failures, fenced-off wrong paths, and a promotion protocol through change control. Load for any loop work: testing, debugging, hardening, or the endurance soak.

Lamprey's first-principles analysis recipes — "prove it, don't just install it" — each with a worked example from this repo's history: source-lock test construction, documented-vs-wired audits, prompt byte measurement, behavioral smoke playbook design, causal-chain postmortems, native-binding probing, adversarial test inversion, and BASELINE/AFTER measurement docs. Load when you need to establish that something is true (or was never true) rather than assume it.

The two open problems where Lamprey could advance the state of the art — the cheap-model harness thesis (harness engineering makes budget models perform like frontier models) and safe local autonomy (unattended desktop loops with hard ceilings and full local audit) — with why current SOTA fails, this repo's specific assets, the first three concrete steps for each, and falsifiable "you have a result when…" milestones. Load when planning research-flavored work or deciding what is worth proving next.

The discipline that turns a hunch into an accepted result in Lamprey — the evidence bar (one mechanism explains all observations including negatives, and survives refutation), numbers predicted before running, the full idea lifecycle from hunch to adopted change or documented retirement, and where good ideas historically came from. Load when starting any investigation or improvement effort, or when tempted to act on a hypothesis that hasn't earned it yet.

What counts as evidence in Lamprey — the layered verify gate, current baseline numbers, the source-lock test pattern, native-skip accounting, the LL and LP smoke playbooks, and the checklist for adding tests. Load before claiming anything works, when writing or modifying tests, when interpreting test/skip counts, or when a gate fails.

Perform a code-review pass focused on bugs and ship readiness. Use for "review this", "before I ship", "code review", and PR checks.

Gather repository context before answering or editing. Use for "what is this repo", "orient me", "preflight", and unfamiliar codebases.

Reproduce, isolate, fix, and verify bugs. Use for "debug", "this is broken", "fix the bug", and failing tests.

Use single-model sub-agents for independent angles. Use for "in parallel", "multiple angles", "compare approaches", and broad analysis.

Exercise local UI changes in the in-app browser. Use for "test the UI", "check the page", "screenshot this", and layout QA.

Plan coding work before editing. Use for "make a plan for", "plan this", "decompose", and similar requests.

Verify recent changes with the right checks. Use for "verify", "did it work", "check the change", and pre-commit validation.

Demonstrates the directory-mode skill format with a sibling reference file. Used as a template for richer skills that ship supporting docs alongside.