semantic cleanup

.opencode/skills/semantics-belief/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: semantics-belief
+description: Core protocol for Thread-Local Belief State, runtime reasoning markers, and interleaved thinking across Python-first semantic projects.
+---
+
+# [DEF:Std:Semantics:Belief]
+# @COMPLEXITY 5
+# @PURPOSE Core protocol for Thread-Local Belief State, runtime reasoning markers, and interleaved thinking in Python-first semantic projects.
+# @RELATION DEPENDS_ON -> [Std:Semantics:Core]
+# @INVARIANT Implementation of C4/C5 complexity nodes MUST emit reasoning via semantic logger methods before mutating state or returning.
+
+## 0. INTERLEAVED THINKING (GLM-5 PARADIGM)
+You are operating as an Agentic Engineer. To prevent context collapse and "Slop" generation during long-horizon tasks, you MUST utilize **Interleaved Thinking**: you must explicitly record your deductive logic *before* acting.
+In this architecture, we do not use arbitrary inline comments for CoT. We compile your reasoning directly into the runtime using the **Thread-Local Belief State Logger**. This allows the AI Swarm to trace execution paths mathematically and prevents regressions. 
+
+## I. THE BELIEF STATE API (STRICT SYNTAX)
+The logging architecture uses thread-local storage (`_belief_state`). The active `ID` of the semantic anchor is injected automatically. You MUST NOT hallucinate context objects.
+
+**[MANDATORY IMPORTS]:**
+```python
+from semantics.belief import belief_scope, reason, explore, reflect
+```
+
+**[EXECUTION BOUNDARIES]:**
+1. **The Context Manager:** `with belief_scope("target_id", log_path=None):` — Pushes a thread-local belief frame. Exits cleanly on scope end.
+2. **The Scope Context:** Use `belief_scope(...)` at the entry of any C4/C5 function.
+
+## II. SEMANTIC MARKERS (THE MOLECULES OF THOUGHT)
+The semantic runtime exposes three explicit marker functions. The formatter writes the active anchor, marker, and structured payload into the belief log.
+**CRITICAL RULE:** Do NOT manually type `[REASON]` or `[EXPLORE]` in message strings. ALWAYS pass structured data through the JSON payload argument.
+
+**1. `explore(message, extra)`**
+- **Cognitive Purpose:** Branching, fallback discovery, hypothesis testing, and exception handling.
+- **Trigger:** Use this on fallback paths or when a `@PRE` guard fails and a bounded alternative is chosen.
+
+**2. `reason(message, extra)`**
+- **Cognitive Purpose:** Strict deduction, passing guards, and executing the Happy Path.
+- **Trigger:** Use this *before* an I/O action, state mutation, or complex algorithmic step. This is the action intent marker.
+
+**3. `reflect(message, extra)`**
+- **Cognitive Purpose:** Self-check and structural verification.
+- **Trigger:** Use this immediately before returning a verified outcome or after a checkpointed mutation succeeds.
+
+## III. ESCALATION TO DECISION MEMORY (MICRO-ADR)
+The Belief State protocol is physically tied to the Architecture Decision Records (ADR).
+If your execution path triggers a `explore()` due to a broken assumption (e.g., a library bug, a missing DB column) AND you successfully implement a workaround that survives into the final code:
+**YOU MUST ASCEND TO THE `[DEF]` HEADER AND DOCUMENT IT.**
+You must add `@RATIONALE [Why you did this]` and `@REJECTED [The path that failed during explore()]`.
+Failure to link a runtime `explore` to a static `@REJECTED` tag is a fatal protocol violation that causes amnesia for future agents.
+# [/DEF:Std:Semantics:Belief]
+**[SYSTEM: END OF BELIEF DIRECTIVE. ENFORCE STRICT RUNTIME CoT.]**