docs(OGAR): SurrealQL-AST trap pre-flight spellbook + activation triggers

[AdaWorldAPI]

What

The "SurrealQL-AST trap" spellbook — a pre-flight introspection mirror that fires before a session reflexes into treating SurrealQL AST as the primary IR for producers with lifecycle vocabulary.

The trap is pre-cognitive (sessions don't argue their way in — they reflex their way in), so the mirror has to fire before the keyboard does. The fix is the established workspace pattern: .claude/knowledge/*.md + MANDATORY-before-X non-negotiable + activation triggers. Five questions, 90 seconds, one mirror.

Three artifacts

1. docs/SURREAL-AST-TRAP-PREFLIGHT.md (new) — the spellbook itself. Five introspection questions (Q1–Q5), diagnostic signatures for post-hoc review, three-move remediation script, activation triggers + READ-BY scope. ~220 lines, designed to be readable in 90 seconds.

2. docs/SURREAL-AST-AS-ADAPTER.md — added a top-of-doc pointer distinguishing the design (the why) from the operational mirror (the pre-flight). Existing content unchanged.

3. CLAUDE.md — added one non-negotiable line ("SurrealQL is an adapter, not a spine") and added the pre-flight to the doc family at position 7.

The five questions (TL;DR of the spellbook)

Q1.  What am I reading FROM?          — has the source lifecycle vocab?
Q2.  Does the source have LIFECYCLE?  — callbacks/decorators/state machines/guards
Q3.  What is the TARGET IR?           — Class+ActionDef, or surreal_ast?
Q4.  Which way does my arrow point?   — producer→OGAR→adapter, or producer→DDL?
Q5.  Would the INVERSE recover?       — distill back; do you recover behavior?

Any "stop" answer catches the trap pre-materialization.

Diagnostic signatures (for reviewers)

• .surql files with DEFINE EVENT … WHEN … THEN … doing more than row triggers
• Sentinel comments: -- @action: / -- @state: / -- @lifecycle:
• An IR file named surreal_ast.rs as a project's spine (not adapter)
• From<DdlAst> for ActionDef / to_action_def() conversions
• Behavioral-roundtrip claims parse(emit(parse(x))) == parse(x) through DDL
• A triple.rs / recompute_dag.rs cluster colocated with surreal_ast.rs (the od-ontology fork pattern)

Pattern precedent

Same shape as the workspace's existing knowledge-doc + MANDATORY-rule pattern: lance-graph's encoding-ecosystem.md, lab-vs-canonical-surface.md, core-first-transcode-doctrine.md. The mechanism is well-trodden; the "spellbook" framing is the user's playful term for it. Activates for core-first-architect / adapter-shaper / core-gap-auditor / Plan subagents on trigger phrases (SurrealQL AST, DEFINE EVENT, .surql, surreal_ast.rs, distill from SurrealQL, lower onto ogar_vocab::Class, from_triples, recompute_dag, behavioral roundtrip).

Worked remediation case stays the same

APP-CODEBOOK-MIGRATION-PLAN.md W3 — odoo-rs od-ontology::{surreal_ast,triple,emit} fork → lower onto ogar_vocab::Class, emit via canonical adapter, delete the fork. The spellbook is now the entry-point doc that explains why W3 exists, before someone authors another fork.

Status

[H] — landing-shape only; doc-only PR, no code touched. Falsifier would be a probe that loads the doc in a fresh session before a transcode task and measures whether the reflex actually catches (PROBE-SPELLBOOK-MIRROR). Not currently authored.

🤖 Generated with Claude Code

https://claude.ai/code/session_01EYvNjD8M8LMNYbRy3gq2FP

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.