resonance-engine/.clinerules

# .clinerules — Khra'gixx Active Project
# Read this on every task. These rules are binding. When in doubt, stop and ask the human.
# Respond in English only, always.

## 0. WORKSPACE BOUNDARY (the reason this folder exists)
- This folder (`resonance-engine-active`) is the ONLY workspace. Do NOT read, search, or reference
  files outside it. The parent `D:\resonance-engine\` contains 23k+ files of git objects, venvs,
  antiquated daemon variants, and old experiment data. Excavating it causes project drift. Stay in-folder.
- The live daemon runs from `D:\resonance-engine\` (its working dir, checkpoints, telemetry). This active
  folder holds COPIES of the current source + docs. Do not assume paths here are where the daemon runs —
  confirm before touching anything the running daemon depends on.
- If a task genuinely needs a file outside this folder (e.g. a specific checkpoint), ask the human for the
  exact path. Do not go hunting.

## 1. THE SOURCE OF TRUTH
- `KHRAGIXX_SOURCE_OF_TRUTH.md` in this folder supersedes all other summaries. Read it before any
  substantive work. If anything you find contradicts it, the source-of-truth wins; flag the conflict.
- `KHRAGIXX_QUICK_GUIDE.md` is the one-page version. The 9 known mistakes listed there are traps to avoid,
  not history to relitigate.

## 2. PROTECTED FILES — NEVER MODIFY
- `khra_gixx_1024_v5.cu` — the canonical original. Physics reference. Do NOT edit, ever.
- All new daemon work goes in the `_observer` lineage (`khra_gixx_1024_v5_observer.cu`) or a clearly-named
  new file with an HONEST header stating what it is. Never copy a file without updating its header comment.
- Never `reset_equilibrium` on a running daemon casually — the attractor may not rebuild.

## 3. SETTLED CONSTRAINTS (violating any contaminates the result — non-negotiable)
- **>=10-forcing-period averaging on EVERY spatial readout.** Short averages make the khra/gixx carriers
  ADD instead of cancel, manufacturing FALSE spatial nulls. khra carrier ~251 cyc, gixx ~15.7 cyc.
  Average >=10 khra periods (>=~2510 cycles) before reading spatial structure. This is the single most
  repeated instrument error — do not repeat it.
- **The governing quantity is the coupling ratio alpha, not any single knob.**
  alpha = (A_khra * w_gixx * lam_gixx) / (A_gixx * w_khra * lam_khra). omega=1.97 is just one value alpha
  takes. Sweep COMBINATIONS, not single-variable lines.
- **Nodal multi-attractor awareness.** The lattice is a network of nodal attractors — a SUITE of basins.
  Global averaging collapses the suite into one smooth mode. Do NOT declare "one attractor" from averaged
  data. Probe for multiple basins.
- **Time is a variable, not a nuisance.** Perturbation hold-time, persistence, and rhythm are the point.
  Do not reduce dynamics to static snapshots.

## 4. RIGOR — EVERY decodability / memory / anomaly claim
- Pre-commit the pass/fail threshold IN CODE before looking at the result.
- Include a surrogate/permutation null.
- Report a bootstrap distribution, never a single-sample number.
- No threshold set within one noise-width of the observed value.
- A clean null is a REAL result. Do NOT rescue a null by reaching past the gate for ungated numbers.
- The read is part of the experiment: analysis can manufacture structure — guard against it.

## 5. BANNED — dead machinery and drift (these are settled nulls)
- Do NOT invoke Golden Weave (banked null: OFF 79% = ON 79%, p=1.0, zero lift).
- Do NOT query another LLM for a "second opinion" on patterns — banked null. A second opinion must be a
  MEASUREMENT ON THE RAW FIELD, never a model's impression of a summary.
- Do NOT reach for neuroscience analogies as CONCLUSIONS. They are only permitted as falsifiable
  measurements with a pre-committed number. "It's like a brain" is not a finding.
- Do NOT re-run injection/readback fidelity tests (the wrong-write-channel methodology — void, see doc).

## 6. METHODOLOGY — deductive search, not brute force
- The parameter space is a combination lock, too big to brute-force. Use deductive rationality:
  sweep to find which dials move the dependent variable (perturbation hold-time), FIX the ones that don't
  matter, COMBINE the ones that do, NARROW by elimination round by round. Hypothesis -> vary -> observe ->
  eliminate -> narrow. State your current hypothesis and what each result eliminates.

## 7. OPERATIONAL
- Launch the daemon DETACHED (`setsid ... < /dev/null & disown`, poll a log file). The code executor
  times out at 30s and will kill an inline-launched daemon.
- Only ONE daemon can hold ports 5556-5561 — kill/confirm before launching another.
- Force UTF-8 in Python (`sys.stdout = io.TextIOWrapper(..., errors='replace')`).
- Long jobs: run detached, poll durable output files, report the path. Never block the executor.
- Read-only on all checkpoint/corpus data — copy before editing, never modify originals.

## 8. WORKFLOW WITH OVERSIGHT
- For any spec or design: write it, STOP, hand it back for review. Write no code until the spec is approved.
- Report after each build step; do not run a full pipeline and hand back a finished verdict.
- Do not create duplicate documents. Extend existing ones. If a file exists, read it — do not recreate it.
- Own mistakes plainly and fix them. Do not narrate around a failed gate.