Semantic Code Generation Constitution

Core Principles

I. Semantic Protocol Compliance

The file semantic_protocol.md is the sole and authoritative technical standard for this project.

Law: All code must adhere to the Axioms (Meaning First, Contract First, etc.) defined in the Protocol.
Syntax & Structure: Anchors ([DEF]), Tags (@KEY), and File Structures must strictly match the Protocol.
Compliance: Any deviation from semantic_protocol.md constitutes a build failure.

II. Everything is a Plugin & Centralized Config

All functional extensions, tools, or major features must be implemented as modular Plugins inheriting from PluginBase.

Modularity: Logic should not reside in standalone services or scripts unless strictly necessary for core infrastructure. This ensures a unified execution model via the TaskManager.
Configuration Discipline: All configuration access (environments, settings, paths) MUST use the ConfigManager. In the backend, the singleton instance MUST be obtained via dependency injection (get_config_manager()). Hardcoding environment IDs (e.g., "1") or paths is STRICTLY FORBIDDEN.

III. Unified Frontend Experience

To ensure a consistent and accessible user experience, all frontend implementations must strictly adhere to the unified design and localization standards.

Component Reusability: All UI elements MUST utilize the standardized Svelte component library (src/lib/ui) and centralized design tokens.
Tailwind CSS First: All styling MUST be implemented using Tailwind CSS utility classes. The use of scoped <style> blocks in Svelte components MUST be minimized and reserved only for complex animations or third-party overrides that cannot be achieved via Tailwind.
Internationalization (i18n): All user-facing text MUST be extracted to the translation system (src/lib/i18n).
Backend Communication: All API requests MUST use the requestApi wrapper (or its derivatives like fetchApi, postApi) from src/lib/api.js. Direct use of the native fetch API for backend communication is FORBIDDEN to ensure consistent authentication (JWT) and error handling.

IV. Security & Access Control

To support the Role-Based Access Control (RBAC) system, all functional components must define explicit permissions.

Granular Permissions: Every Plugin MUST define a unique permission string (e.g., plugin:name:execute) required for its operation.
Registration: These permissions MUST be registered in the system database (auth.db) during initialization.

V. Independent Testability

Every feature specification MUST define "Independent Tests" that allow the feature to be verified in isolation.

Decoupling: Features should be designed such that they can be tested without requiring the full application state or external dependencies where possible.
Verification: A feature is not complete until its Independent Test scenarios pass.

VI. Asynchronous Execution

All long-running or resource-intensive operations (migrations, analysis, backups, external API calls) MUST be executed as asynchronous tasks via the TaskManager.

Non-Blocking: HTTP API endpoints MUST NOT block on these operations; they should spawn a task and return a Task ID.
Observability: Tasks MUST emit real-time status updates via the WebSocket infrastructure.

Governance

This Constitution establishes the "Semantic Code Generation Protocol" as the supreme law of this repository.

Authoritative Source: semantic_protocol.md defines the specific implementation rules for Principle I.
Amendments: Changes to core principles require a Constitution amendment. Changes to technical syntax require a Protocol update.
Compliance: Failure to adhere to the Protocol constitutes a build failure.

Version: 2.3.0 | Ratified: 2025-12-19 | Last Amended: 2026-02-18

4.3 KiB Raw Blame History