5.0 KiB
5.0 KiB
[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.