40 lines
5.0 KiB
Markdown
40 lines
5.0 KiB
Markdown
# [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]
|