tasks ready

docs/adr/ADR-0002-semantic-protocol.md

@@ -0,0 +1,39 @@
+# [DEF:ADR-0002:ADR]
+# @STATUS ACTIVE
+# @PURPOSE Mandate the GRACE skill set (`.opencode/skills/`) as the single semantic governance authority for all source files and AI‑agent workflows in this repository. This ADR is the adoption decision — the protocol mechanics live exclusively in the skills; this ADR records *why* the skills are non‑optional for this project.
+# @RELATION DEPENDS_ON -> [ADR-0001:ADR]
+# @RATIONALE A multi‑platform repository (Python/FastAPI + SvelteKit) served by multiple AI agents (backend‑coder, frontend‑coder, qa‑tester, semantic‑curator, …) requires a single, machine‑parseable contract language that works identically across both platforms. Without it, agents produce inconsistent annotations, the semantic index (`semantic_map.json`) degrades, and long‑horizon agent sessions (50+ commits) accumulate invisible architectural drift.
+# @RATIONALE GRACE was chosen over lightweight alternatives because this project has specific stressors that only a full protocol addresses: (a) two platforms with different comment syntax — GRACE provides platform‑specific anchor forms under one unified graph, (b) long‑horizon agent sessions — GRACE Decision Memory (`@RATIONALE`/`@REJECTED`) prevents agents from re‑exploring already‑rejected paths, (c) complex orchestration flows (plugin execution, backup pipelines) — GRACE belief‑state markers make side‑effect‑heavy code auditable and debuggable, (d) enterprise deployment requirements — fractal limits (module <400 lines, `[DEF]` <150 lines) enforce structural hygiene critical for audit‑ready code.
+# @RATIONALE Skills are the canonical source rather than this ADR because protocol details (complexity scale, tag inventory, syntax variants) evolve. Duplicating them here creates a fork that will inevitably desynchronise — agents would face two competing versions and inevitably read the stale one. Skills are version‑controlled in the same repo and loaded dynamically via `skill({name="..."})`, ensuring agents always receive the current protocol.
+# @REJECTED Plain docstring conventions (Google/NumPy style) — rejected because free‑text docstrings are invisible to the semantic index and cannot express relations, pre/post conditions, or rejected paths in a machine‑queryable form.
+# @REJECTED Decorator‑based contracts (`@contract`, `@pre`, `@post`) — rejected because they are Python‑only, cannot annotate Svelte components or TypeScript, and break the unified semantic graph spanning both platforms.
+# @REJECTED JSDoc/TSDoc for the frontend — rejected because it would create a second annotation language, fragmenting the semantic graph into two incompatible halves and forcing agents to master two different contract systems.
+# @REJECTED Embedding protocol rules directly in ADRs (the previous version of this document) — rejected because it duplicates the skill content and inevitably diverges. Agents receiving both the skill and the ADR would face conflicting versions; the skill is the single source of truth.
+
+## Decision
+
+This repository adopts the **GRACE-Poly v2.4 protocol** as implemented by five skills:
+
+| Skill | File | Role in this project |
+|-------|------|---------------------|
+| `semantics-core` | `.opencode/skills/semantics-core/SKILL.md` | Anchor syntax, complexity scale (C1‑C5), global invariants, tag inventory |
+| `semantics-contracts` | `.opencode/skills/semantics-contracts/SKILL.md` | Design by Contract, Decision Memory (ADR chain, `@RATIONALE`/`@REJECTED`), anti‑erosion rules |
+| `semantics-belief` | `.opencode/skills/semantics-belief/SKILL.md` | Belief‑state runtime markers (`belief_scope`, `reason`, `reflect`, `explore`) for C4/C5 Python flows |
+| `semantics-testing` | `.opencode/skills/semantics-testing/SKILL.md` | Test constraints, invariant traceability, anti‑tautology rules |
+| `semantics-frontend` | `.opencode/skills/semantics-frontend/SKILL.md` | Svelte 5 UX contracts (`@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`) |
+
+**Key principle:** Skills are the protocol. This ADR is the adoption record. When an agent needs to know *what tags are required at C4*, it reads `semantics-core`. When it needs to know *why this project chose C4 annotations at all*, it reads this ADR.
+
+## Enforcement
+
+All speckit commands (`.opencode/command/speckit.*.md`) load the skill set as part of their execution flow:
+
+- **`/speckit.plan`** — reads skills to validate contract designs against the complexity scale.
+- **`/speckit.implement`** — requires `[DEF]` anchors and complexity‑appropriate metadata; rejects naked code.
+- **`/speckit.test`** — audits semantic compliance and decision‑memory continuity per skill rules.
+- **`/speckit.semantics`** — reindexes and audits the entire workspace against the skill‑defined protocol.
+- **`/speckit.analyze`** — checks for decision‑memory drift and rejected‑path scheduling.
+
+Static verification (`python3 scripts/static_verify.py`) performs offline checks for broken anchors, missing complexity metadata, and orphan relations.
+
+# [/DEF:ADR-0002:ADR]