refactor: migrate Markdown to AsciiDoc

.claude/CLAUDE.generated.adoc

@@ -0,0 +1,302 @@
+== PanLL — AI Coordination Rules
+
+____
+*Auto-generated from `+coordination.k9+`* — do not edit directly.
+Re-generate with:
+`+deno run --allow-read --allow-write generate.js coordination.k9+`
+Source of truth: `+coordination.k9+` in repository root.
+____
+
+=== Project
+
+Neurosymbolic IDE built on the Binary Star model — human (symbolic,
+Panel-L) and machine (neural, Panel-N) orbiting a shared world state
+(Panel-W). 106 panels, custom TEA runtime, Gossamer desktop backend.
+
+*Languages:* ReScript, Rust, Elixir, JavaScript *License:* MPL-2.0
+*Build system:* just *Runtime:* deno
+
+=== Build Commands
+
+[cols=",",options="header",]
+|===
+|Command |Description
+|`+just build+` |Full build (ReScript + CSS + bundle)
+|`+just res+` |ReScript compile only
+|`+just bundle+` |esbuild bundle
+|`+just css+` |Build CSS
+|`+just dev+` |Start dev server on port 8000
+|`+just test+` |Run test suite (979 tests, 41 suites)
+|`+just coverage+` |Run tests with coverage
+|`+just lint+` |Lint ReScript source
+|`+just doctor+` |Run project health checks
+|===
+
+=== INVARIANTS — Do Not Violate
+
+These rules are non-negotiable. Violating them will break the project or
+contradict deliberate architectural decisions.
+
+==== [CRITICAL] custom-tea-runtime
+
+*Rule:* The custom TEA runtime in src/tea/ (18 modules) must NEVER be
+replaced with rescript-tea or any other library
+
+*Why:* rescript-tea was deliberately evaluated and rejected. The custom
+TEA runtime handles PanLL-specific needs: Anti-Crash circuit breaking,
+Vexometer cognitive load adaptation, OrbitalSync multi-panel state
+coherence, and panel lifecycle management. It is not legacy — it is the
+architecture.
+
+==== [CRITICAL] no-typescript
+
+*Rule:* Do not introduce TypeScript files — ReScript is the frontend
+language
+
+*Why:* ReScript provides better type safety with less overhead. This is
+a deliberate, ecosystem-wide decision.
+
+==== [CRITICAL] no-tauri
+
+*Rule:* Do not introduce Tauri references or dependencies — Gossamer is
+the desktop backend
+
+*Why:* PanLL was migrated FROM Tauri 2.0 TO Gossamer. This migration is
+complete and intentional.
+
+==== [CRITICAL] tea-pattern-only
+
+*Rule:* All state management uses TEA (Model -> Msg -> Update -> View) —
+no MVC, Redux, hooks, or other patterns
+
+*Why:* TEA is foundational to PanLL’s architecture. Model.res holds all
+state, Msg.res defines all messages, Update.res is the state transition
+kernel.
+
+==== [CRITICAL] all-state-in-model
+
+*Rule:* ALL application state lives in Model.model — no global mutable
+state, no module-level state, no window.* state
+
+*Why:* TEA requires single state tree. Anti-Crash and OrbitalSync depend
+on this invariant for correctness.
+
+==== [CRITICAL] no-npm-bun
+
+*Rule:* No npm, Bun, pnpm, or yarn — Deno is the orchestrator
+
+*Why:* npm is used ONLY for the ReScript compiler (which requires it).
+All other tooling uses Deno. Do not add npm dependencies.
+
+==== [CRITICAL] anticrash-validates-all
+
+*Rule:* Anti-Crash circuit breaker validates ALL neural tokens before
+symbolic execution — never bypass this
+
+*Why:* Safety-critical: prevents untrusted neural output from corrupting
+symbolic state. The validation path exists for a reason.
+
+==== [HIGH] panels-not-panes
+
+*Rule:* UI elements are called '`panels`', NEVER '`panes`', '`tabs`', or
+'`windows`'
+
+*Why:* PanLL naming convention — '`panels`' is the correct term
+everywhere in code, docs, and communication
+
+==== [CRITICAL] no-bulk-panel-deletion
+
+*Rule:* Do not delete more than 2 panel files in a single operation
+without explicit user approval
+
+*Why:* 106 panels have complex interdependencies. Bulk deletion can
+cascade and break OrbitalSync.
+
+==== [HIGH] gossamer-bridge-pattern
+
+*Rule:* Gossamer commands in src/commands/ are invoke wrappers only — do
+not put business logic there
+
+*Why:* Business logic belongs in Update.res. Commands are thin bridges
+to the Gossamer backend.
+
+==== [CRITICAL] binary-star-model
+
+*Rule:* The Binary Star architecture (Panel-L symbolic + Panel-N neural
++ Panel-W world) is deliberate — do not flatten into a single panel type
+
+*Why:* The three panel types serve fundamentally different roles. This
+is the core design of PanLL.
+
+==== [CRITICAL] rescript-core-team
+
+*Rule:* The project owner is on the ReScript core team — do not suggest
+migrating away from ReScript
+
+*Why:* ReScript is not a temporary choice. The owner contributes to
+ReScript itself.
+
+=== Protected Files and Directories
+
+Do NOT delete, reorganise, or replace these without explicit user
+approval:
+
+[width="100%",cols="43%,57%",options="header",]
+|===
+|Path |Reason
+|`+src/tea/+` |Custom TEA runtime — 18 modules. NEVER replace with
+rescript-tea.
+
+|`+src/Model.res+` |Single state tree — all application state lives here
+
+|`+src/Msg.res+` |Message type definitions — the TEA message catalogue
+
+|`+src/Update.res+` |State transition kernel — ~7500 lines, the heart of
+PanLL
+
+|`+src/View.res+` |Root view renderer
+
+|`+src/App.res+` |Application entry point
+
+|`+src/core/+` |Core engines — AntiCrash, OrbitalSync, Contractiles,
+TypeLLEngine, VabEngine
+
+|`+src/components/+` |106 panel views — do not bulk-delete
+
+|`+src/commands/+` |Gossamer bridge commands — thin wrappers only
+
+|`+src/modules/+` |Module registry + TypeLLService — cross-panel type
+intelligence
+
+|`+src-gossamer/+` |Rust backend (WebKitGTK) — Gossamer desktop
+integration
+
+|`+beam/+` |Elixir/BEAM API layer
+
+|`+tests/+` |979 tests, 41 suites — never delete tests
+
+|`+.machine_readable/+` |Canonical location for A2ML state files — MUST
+stay here
+
+|`+coordination.k9+` |This file — source of truth for AI coordination
+|===
+
+=== Architecture Decisions (Deliberate)
+
+These choices may look unusual but are intentional:
+
+==== gossamer-not-tauri
+
+*Decision:* Gossamer (Zig + WebKitGTK) is the desktop backend —
+migration from Tauri 2.0 is complete
+
+*Why:* Gossamer is the hyperpolymath desktop runtime. Tauri was used
+previously but replaced.
+
+*Rejected alternatives:* Tauri 2.0, Electron, native GTK
+
+==== custom-tea-not-rescript-tea
+
+*Decision:* Custom TEA runtime (src/tea/, 18 modules) instead of the
+rescript-tea library
+
+*Why:* PanLL needs Anti-Crash integration, OrbitalSync, Vexometer hooks,
+and panel lifecycle — none available in rescript-tea
+
+*Rejected alternatives:* rescript-tea, Redux, MobX, React hooks pattern
+
+==== deno-npm-hybrid
+
+*Decision:* Deno orchestrates everything, but npm is used solely for the
+ReScript compiler
+
+*Why:* ReScript compiler requires npm — this is the ONLY permitted npm
+usage. Do not extend npm’s role.
+
+==== binary-star
+
+*Decision:* Four panel types: Panel-A (ambient/substrate), Panel-L
+(logic/symbolic), Panel-N (neural/machine), Panel-W (world/shared)
+
+*Why:* L + N orbit W in the Binary Star core (clear separation of human
+reasoning, machine inference, and shared world state); Panel-A surrounds
+as ambient substrate for persistent context and ergonomic support.
+
+==== vexometer-cognitive-load
+
+*Decision:* Vexometer monitors operator stress and adapts UI detail
+density
+
+*Why:* HTI (Human-Tool Interaction) principle — the IDE adapts to the
+human, not vice versa
+
+==== anticrash-circuit-breaker
+
+*Decision:* Anti-Crash validates all neural tokens before they enter the
+symbolic pipeline
+
+*Why:* Safety boundary between neural and symbolic systems — prevents
+hallucinated code from corrupting state
+
+=== Do NOT Create
+
+These files, patterns, or systems must NOT be introduced:
+
+* ****/*.ts** — TypeScript is banned — use ReScript
+* *Dockerfile* — Use Containerfile (Podman, not Docker)
+* ****/*.py** — Python is banned — use ReScript, Rust, or Elixir
+* *A replacement TEA runtime or state management library* — src/tea/ is
+the TEA runtime — it is custom, deliberate, and must not be replaced
+* *REST API endpoints parallel to existing Groove protocol endpoints* —
+Groove is the inter-service communication protocol — do not create REST
+alternatives
+* *A new panel type beyond Panel-L, Panel-N, Panel-W* — Binary Star
+model has exactly three types — adding more would break OrbitalSync
+* *Direct Tauri imports or tauri.conf.json* — Tauri migration to
+Gossamer is complete — do not reintroduce
+
+=== Terminology
+
+Use the correct terms for this project:
+
+* Say *"`panels`"*, NOT "`panes`", "`tabs`", "`windows`"
+** PanLL UI elements are always called panels — this is enforced
+everywhere
+* Say *"`Binary Star`"*, NOT "`dual-pane`", "`split-view`",
+"`two-panel`"
+** The architectural model is Binary Star (Panel-L + Panel-N orbiting
+Panel-W)
+* Say *"`Anti-Crash`"*, NOT "`validator`", "`sanitizer`", "`filter`"
+** The neural token validation system is called Anti-Crash
+* Say *"`Vexometer`"*, NOT "`stress meter`", "`load indicator`",
+"`fatigue tracker`"
+** The cognitive load monitoring system is called Vexometer
+* Say *"`OrbitalSync`"*, NOT "`state sync`", "`panel sync`", "`sync
+engine`"
+** The multi-panel state coherence system is called OrbitalSync
+
+=== Port Assignments
+
+[cols=",",options="header",]
+|===
+|Service |Port
+|dev-server |8000
+|echidna |9000
+|verisim |8080
+|boj-server |7700
+|typell |7800
+|===
+
+=== Ecosystem Context
+
+*Depends on:* - *gossamer* — Desktop backend runtime (Zig + WebKitGTK) -
+*verisim* — Persistent storage layer - *typell* — Type intelligence
+engine — cross-panel type checking - *boj-server* — MCP server — all
+external tool integration
+
+*Consumed by:* - *idaptik* — Uses PanLL as level editor for game content
+
+*Related projects:* - *echidna* — Proof engine — formal verification
+integration - *hypatia* — Neurosymbolic CI/CD scanning - *panic-attack*
+— Security scanning tool - *gitbot-fleet* — Bot orchestration (rhodibot,
+echidnabot, etc.) - *proven* — Formally verified alternatives library