Files

busya 731aaaa8df feat(mcp): 050 unified MCP interface — parity tools, durable gates, authoring E2E, assistant decommission

044 provider runtime completion (pre-staged workstream): capacity/operator
stores, provider ops/protocol/reconciler/dispatch revalidation, exploration
sandbox runtime, alembic 0014-0016, live canary evidence (browser provider
6/6 against the live stand).

050 Phases 0-2: RBAC FastMCP server with a 45-tool explicit catalog,
OAuth/DCR transport guards with bounded bodies, per-call provenance
(McpToolInvocationRecord), durable ActionApprovalGate + CAS decide +
leased/fenced poller, authoring workspace ops, bounded-response discipline,
hidden-vs-gated matrices.

Parity domains (T012-T014): gated git/deploy/migration/backup/llm tools with
reviewed dispatch adapters in explicit poll chains; Superset reads/writes with
a dedicated plugin:superset_sql risk class (terminal PROD denial via the
canonical execution-policy criterion, hardened danger-SQL guard covering
INTO/CALL/SET/REFRESH/file primitives/multi-statement); baseline 037 tools
over the shared REST-surface services.

Evidence (T016/T023/T028): REST-vs-MCP field parity on shared 037 fixtures;
vertical E2E from tools/list through registry revision activation with real
scenario:EDIT RBAC; sandbox-to-revision promotion E2E with unsafe-payload and
caller-digest rejection; dispatcher soak (three poll cycles, exactly-once).

Orthogonal QA+security audit hardening: enforced response_limit fail-closed
envelope, poisoned-exploration fail-closed (EXPLORATION_TARGET_UNRESOLVED),
sha256 exploration evidence digests, actor-UUID task ownership, is_active
guard on baseline consume, 038 resolver description=None selector fix.

Phase 3/4 decommission: HandoffSurface behind the MCP_DECOMMISSION flag,
then unconditional removal — agent/ service tree, chat components/models/
stores/types, gradio proxies (vite + nginx), agent service in run.sh,
docker-compose profiles, build.sh bundles; /agent renders the handoff only.
Docs: AGENTS.md/INSTALL.md two-service rewrite; 036-047 drift amendments
marked done; WORKSTATE checkpoints with all evidence.

Suites: backend 11199 passed / 240 skipped / 1 xpassed; frontend 3454 passed
(197 files), lint 0 errors, build OK; browser E2E login+handoff 6/6 twice on
the isolated compose stack (no 7860); ruff/compileall clean.

Misc: gitignore hardening (tmp/, tool model cache); E2E selector repairs
(nav strict-mode, invalid-credentials passthrough detail).

2026-09-03 07:37:14 +03:00

5.2 KiB

Raw Blame History

@{ Doc.Adr.ADR0002 [C:1] [TYPE ADR]

@STATUS ACCEPTED

@BRIEF 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]

@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.

@REJECTED Treating typical C4/C5 tags as required, and filling `@RATIONALE`/`@PRE`/`@BRIEF` to silence audits — rejected because synthetic markup poisons navigation more than a bare anchor (INV_9).

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. .axiom/axiom_config.yaml is a projection of semantics-core (index paths, tag catalog) and MUST NOT introduce required-tag gates that the SSOT marks as advisory.

Runtimes: Axiom MCP (search / audit) when those tools are connected (OpenCode). Grok TUI and any session without Axiom uses zombie-mode from semantics-core §VIII (grep on [SEMANTICS, #region pairs). Both are first-class.

INV_9: a missing @-tag is valid; a synthetic tag is a defect. Decision memory and every other metadata tag are written only when a local fact exists.

Doxygen navigation: generated HTML/maps are a two-level agent graph — modules (root.map, \defgroup) then functions (module map @FUNCTIONS, \ingroup). make docs-nav. Not a flat axiom_*.html dump.

When an agent needs to know what tags are typical at C4, it reads semantics-core. Nothing is required by tier. When it needs to know why this project chose GRACE, 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 authentic @RATIONALE and @REJECTED decisions unless a successor ADR explicitly changes them. Synthetic tags are removed, not rewritten. This ADR does not treat missing-tag audits as a merge gate.

5.2 KiB Raw Blame History Unescape Escape