busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
34393adf7e437c5bd8cb969746b9dbff8bddbd43
ss-tools/docs/adr/ADR-0002-semantic-protocol.md
busya 24d3b7d1f9 refactor(task-manager): implement task resilience and execution lifecycle improvements 
Enhance the reliability and observability of the task execution engine
by introducing retry mechanisms, idempotency, and structured progress
tracking.

- Implement centralized retry logic with exponential backoff support
  in `JobLifecycle`.
- Add `retry_task` API endpoint and `TaskManager` method for manual
  task restarts.
- Introduce task idempotency using `_idempotency_key` to prevent
  duplicate executions.
- Add `retry_count`, `max_retries`, `last_error`, and `progress` fields
  to the `Task` model and ensure persistence via `TaskPersistenceService`.
- Upgrade `SchedulerService` to use differential synchronization with
  the persistent `SQLAlchemyJobStore` for better job durability.
- Implement structured heartbeat logging to support real-time progress
  updates.
- Update project documentation and ADRs to reflect the new plugin
  runtime and task resilience patterns.
- Add comprehensive unit and integration tests for the new task
  lifecycle features.
2026-07-12 15:31:56 +03:00

4.2 KiB
Raw Blame History

[DEF:ADR-0002: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 -> [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. 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:ADR-0002:ADR]