632b730fff
Systematic rename of all semantic anchors (#region, [DEF], @RELATION) across 1400+ files — backend Python, frontend Svelte/TS, specs, docs: - Flat anchors become Namespace.Module.Entity - @RELATION references updated to match new anchor paths - Zero business logic changes
38 lines
4.2 KiB
Markdown
38 lines
4.2 KiB
Markdown
# [DEF:Doc.Adr.ADR0002:ADR]
|
||
# @STATUS ACCEPTED
|
||
# @PURPOSE Establish the version-controlled semantic skills and source contracts as the governance mechanism for source code and agent workflows in this repository.
|
||
# @RELATION DEPENDS_ON -> [Doc.Adr.ADR0001: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. Skills are version-controlled in this repository and must be loaded from their current locations.
|
||
# @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 semantic protocol implemented by version-controlled
|
||
skills in `.agents/skills/` (mirrored for compatible OpenCode workflows under
|
||
`.opencode/skills/`):
|
||
|
||
| Skill | File | Role in this project |
|
||
|-------|------|---------------------|
|
||
| `semantics-core` | `.agents/skills/semantics-core/SKILL.md` | Anchor syntax, complexity scale, global invariants, tag inventory |
|
||
| `semantics-contracts` | `.agents/skills/semantics-contracts/SKILL.md` | Design by Contract, Decision Memory, anti-erosion rules |
|
||
| `semantics-python` | `.agents/skills/semantics-python/SKILL.md` | Python/FastAPI conventions and belief-runtime patterns |
|
||
| `semantics-svelte` | `.agents/skills/semantics-svelte/SKILL.md` | Svelte 5 UX state and component conventions |
|
||
| `semantics-testing` | `.agents/skills/semantics-testing/SKILL.md` | Test constraints and invariant traceability |
|
||
|
||
**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
|
||
|
||
Agent commands and reviews load the relevant skills before changing a contracted module.
|
||
Feature specs reference this ADR and the relevant skill when they introduce C4/C5
|
||
contracts. Code review preserves declared `@RATIONALE` and `@REJECTED` decisions
|
||
unless a successor ADR explicitly changes them. This ADR deliberately does not
|
||
claim a verifier that is absent from the repository.
|
||
|
||
# [/DEF:Doc.Adr.ADR0002:ADR]
|