busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: amend constitution to v2.0.0 (delegate semantics to protocol + add async/testability principles)

Browse Source
This commit is contained in:
busya
2026-01-28 18:48:43 +03:00
parent b2bbd73439
commit d4109e5a03
1 changed files with 26 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

73
.specify/memory/constitution.md
View File

@@ -1,8 +1,12 @@
<!-- <!--
SYNC IMPACT REPORT SYNC IMPACT REPORT
Version: 1.9.0 (Security & RBAC Mandate) Version: 2.0.0 (Protocol Alignment & Spec Consolidation)
Changes: Changes:
- Added Principle IX: Security & Access Control (Mandating granular permissions for plugins). - Refactored Principle I: Consolidated all semantic/structural rules into a single reference to `semantic_protocol.md`.
- Removed Principles II-VI (Redundant with Protocol).
- Renumbered remaining principles.
- Added Principle V: Independent Testability (Derived from Specs 015-017).
- Added Principle VI: Asynchronous Execution (Derived from Specs 009, 017).
Templates Status: Templates Status:
- .specify/templates/plan-template.md: ✅ Aligned. - .specify/templates/plan-template.md: ✅ Aligned.
- .specify/templates/spec-template.md: ✅ Aligned. - .specify/templates/spec-template.md: ✅ Aligned.
@@ -13,64 +17,39 @@ Templates Status:
## Core Principles ## Core Principles
### I. Semantic Protocol Compliance ### I. Semantic Protocol Compliance
The file `semantic_protocol.md` is the **authoritative technical standard** for this project. All code generation, refactoring, and architecture must strictly adhere to the standards, syntax, and workflows defined therein. The file `semantic_protocol.md` is the **sole and authoritative technical standard** for this project.
- **Syntax**: `[DEF]` anchors, `@RELATION` tags, and metadata must match the Protocol specification. - **Law**: All code must adhere to the Axioms (Meaning First, Contract First, etc.) defined in the Protocol.
- **Structure**: File layouts and headers must follow the "File Structure Standard". - **Syntax & Structure**: Anchors (`[DEF]`), Tags (`@KEY`), and File Structures must strictly match the Protocol.
- **Workflow**: The technical steps for generating code must align with the Protocol. - **Compliance**: Any deviation from `semantic_protocol.md` constitutes a build failure.
### II. Causal Validity (Contracts First) ### II. Everything is a Plugin
As defined in the Protocol, Semantic definitions (Contracts) must ALWAYS precede implementation code. Logic is downstream of definition. We define the structure and constraints (`[DEF]`, `@PRE`, `@POST`) before writing the executable logic.
### III. Immutability of Architecture
Architectural decisions in the Module Header (`@LAYER`, `@INVARIANT`, `@CONSTRAINT`) are treated as immutable constraints. Changes to these require an explicit refactoring step, not ad-hoc modification during implementation.
### IV. Design by Contract (DbC)
Contracts are the Source of Truth. Functions and Classes must define their purpose, specifications, and constraints in the metadata block before implementation, strictly following the **Contracts (Section IV)** standard in `semantic_protocol.md`.
### V. Belief State Logging
Agents must maintain belief state logs for debugging and coherence checks, strictly following the **Logging Standard (Section V)** defined in `semantic_protocol.md`.
### VI. Fractal Complexity Limit
To maintain semantic coherence, code must adhere to the complexity limits (Module/Function size) defined in the **Fractal Complexity Limit (Section VI)** of `semantic_protocol.md`.
### VII. Everything is a Plugin
All functional extensions, tools, or major features must be implemented as modular Plugins inheriting from `PluginBase`. Logic should not reside in standalone services or scripts unless strictly necessary for core infrastructure. This ensures a unified execution model via the `TaskManager`, consistent logging, and modularity. All functional extensions, tools, or major features must be implemented as modular Plugins inheriting from `PluginBase`. Logic should not reside in standalone services or scripts unless strictly necessary for core infrastructure. This ensures a unified execution model via the `TaskManager`, consistent logging, and modularity.
### VIII. Unified Frontend Experience ### 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. 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. Ad-hoc styling and hardcoded values are prohibited. - **Component Reusability**: All UI elements MUST utilize the standardized Svelte component library (`src/lib/ui`) and centralized design tokens.
- **Internationalization (i18n)**: All user-facing text MUST be extracted to the translation system (`src/lib/i18n`). Hardcoded strings in the UI are prohibited. - **Internationalization (i18n)**: All user-facing text MUST be extracted to the translation system (`src/lib/i18n`).
### IX. Security & Access Control ### IV. Security & Access Control
To support the Role-Based Access Control (RBAC) system, all functional components must define explicit permissions. 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. - **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 during initialization or plugin loading to ensure they are available for role assignment in the Admin UI. - **Registration**: These permissions MUST be registered in the system database (`auth.db`) during initialization.
## File Structure Standards ### V. Independent Testability
Refer to **Section III (File Structure Standard)** in `semantic_protocol.md` for the authoritative definitions of: Every feature specification MUST define "Independent Tests" that allow the feature to be verified in isolation.
- Python Module Headers (`.py`) - **Decoupling**: Features should be designed such that they can be tested without requiring the full application state or external dependencies where possible.
- Svelte Component Headers (`.svelte`) - **Verification**: A feature is not complete until its Independent Test scenarios pass.
## Generation Workflow ### VI. Asynchronous Execution
The development process follows a streamlined single-phase workflow: 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.
### 1. Code Generation Phase (Mode: `code`) - **Observability**: Tasks MUST emit real-time status updates via the WebSocket infrastructure.
**Input**: `tasks.md`
**Responsibility**:
- Select task from `tasks.md`.
- Generate Scaffolding (`[DEF]` anchors, Headers, Contracts) AND Implementation in one pass.
- Ensure strict adherence to Protocol Section IV (Contracts) and Section VII (Generation Workflow).
- **Output**: Working code with passing tests.
### 2. Validation
If logic conflicts with Contract -> Stop -> Report Error.
## Governance ## Governance
This Constitution establishes the "Semantic Code Generation Protocol" as the supreme law of this repository. 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 these Principles. - **Authoritative Source**: `semantic_protocol.md` defines the specific implementation rules for Principle I.
- **Automated Enforcement**: Tools must validate adherence to the `semantic_protocol.md` syntax.
- **Amendments**: Changes to core principles require a Constitution amendment. Changes to technical syntax require a Protocol update. - **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. - **Compliance**: Failure to adhere to the Protocol constitutes a build failure.
**Version**: 1.9.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2026-01-27 **Version**: 2.0.0 | **Ratified**: 2025-12-19 | **Last Amended**: 2026-01-28