diff --git a/Conventions/CONVENTIONS.json b/Conventions/CONVENTIONS.json new file mode 100644 index 0000000..698a136 --- /dev/null +++ b/Conventions/CONVENTIONS.json @@ -0,0 +1,517 @@ +{ + "validation_patterns_file": "global_validation_patterns.yaml.md", + "conventions_version": "2025-08-01", + "comment_1a2b3c": "Schema version for the conventions specification.", + "sections": [ + { + "id": "db.audit", + "comment_2b3c4d": "Audit trail isolation and immutability.", + "title": "Audit Trail & Immutability", + "comment_3c4d5e": "Protect and isolate all audit data.", + "rules": [ + { + "id": "db.audit.schema", + "comment_4d5e6f": "Audit schema location.", + "statement": "All audit tables MUST reside in a dedicated schema named 'audit'.", + "applies_to": ["db"], + "comment_6f7a8b": "Ensures separation of audit data.", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["db-policy", "review"] + }, + { + "id": "db.audit.immutability", + "comment_4d5e6f": "Prevent modifications after insert.", + "statement": "Audit tables MUST be append-only and protected against UPDATE or DELETE.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "Implement via REVOKE, RLS, or equivalent.", + "comment_9c0d1e": "", + "enforced_by": ["db-policy", "ci"] + }, + { + "id": "db.audit.application", + "comment_4d5e6f": "Application-level enforcement.", + "statement": "No application or migration code MAY alter, update, or delete audit records.", + "applies_to": ["db", "code"], + "comment_6f7a8b": "", + "requirement_level": "MUST NOT", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["review", "ci"] + } + ], + "comment_1e2f3a": "End of rules array for Audit section." + }, + { + "id": "db.rel", + "comment_2b3c4d": "Foreign key, referential integrity, polymorphism.", + "title": "Relations & Integrity", + "comment_3c4d5e": "", + "rules": [ + { + "id": "db.rel.fk", + "comment_4d5e6f": "All FKs explicit and constrained.", + "statement": "All cross-table references MUST use explicit FOREIGN KEY constraints, each with ON DELETE/ON UPDATE policy and supporting INDEX.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["db-policy", "ci", "review"] + }, + { + "id": "db.rel.polymorphic", + "comment_4d5e6f": "Polymorphic link validation.", + "statement": "Polymorphic link tables MUST enforce validity of each (type, id) pair via trigger, test, or application logic.", + "applies_to": ["db", "code", "test"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["codebase_registry_template.json"], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["test", "ci"] + } + ], + "comment_1e2f3a": "End of rules for relations section." + }, + { + "id": "db.constraint", + "comment_2b3c4d": "Unique constraints, enums, JSON, versioning.", + "title": "Constraints & Field Types", + "comment_3c4d5e": "", + "rules": [ + { + "id": "db.constraint.unique", + "comment_4d5e6f": "DEFERRABLE unique constraints.", + "statement": "Unique constraints MUST be DEFERRABLE INITIALLY IMMEDIATE unless documented otherwise.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["review", "ci"] + }, + { + "id": "db.constraint.enum", + "comment_4d5e6f": "Enums for value fields.", + "statement": "All status/type/category fields MUST use explicit ENUM types.", + "applies_to": ["db", "ui", "code"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["ui_blocks_template.json"], + "comment_8b9c0d": "", + "notes": "Enums must be documented and UI-synced.", + "comment_9c0d1e": "", + "enforced_by": ["ci", "review"] + }, + { + "id": "db.constraint.enum_sync", + "comment_4d5e70": "ENUM value synchronization policy.", + "statement": "All ENUM value lists used in the database schema MUST be declared and maintained in a central canonical location (e.g., schema.sql or shared enums JSON). All dependent code and UI blocks MUST reference this location and be updated to match any changes. CI MUST validate that UI and code ENUM value lists are in sync with the database.", + "applies_to": ["db", "ui", "code"], + "requirement_level": "MUST", + "references": ["schema.sql", "ui_blocks_template.json"], + "notes": "Avoids UI drift and hardcoded mismatches. Exception must be documented.", + "enforced_by": ["ci", "review"] + }, + { + "id": "db.constraint.jsonb", + "comment_4d5e6f": "Validation for JSONB business data.", + "statement": "Any JSONB field with business data MUST be validated by CHECK, trigger, or tested application logic.", + "applies_to": ["db", "code", "test"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["codebase_registry_template.json"], + "comment_8b9c0d": "", + "notes": "Relaxed validation for log/debug fields is permitted with documentation.", + "comment_9c0d1e": "", + "enforced_by": ["test", "review"] + }, + { + "id": "db.constraint.timestamps", + "comment_4d5e6f": "Required timestamp and version columns.", + "statement": "All mutable/business tables MUST include created_at, updated_at, and version columns.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "Static lookup/reference tables are exempt. Exceptions must be documented.", + "comment_9c0d1e": "", + "enforced_by": ["review", "ci"] + } + ], + "comment_1e2f3a": "End of constraints section." + }, + { + "id": "db.index", + "comment_2b3c4d": "Indexing for FKs, frequent queries.", + "title": "Indexing", + "comment_3c4d5e": "", + "rules": [ + { + "id": "db.index.fk_and_query", + "comment_4d5e6f": "Indexes for FKs and query columns.", + "statement": "All FOREIGN KEY columns and columns used for frequent filter, sort, or join operations MUST be indexed.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["review", "ci"] + } + ], + "comment_1e2f3a": "End of indexing section." + }, + { + "id": "db.migration", + "comment_2b3c4d": "Schema change and migration policy.", + "title": "Schema Change Policy", + "comment_3c4d5e": "", + "rules": [ + { + "id": "db.migration.manual", + "comment_4d5e6f": "Manual schema changes only during MVP.", + "statement": "All schema changes MUST be performed via hand-written SQL executed on the development database and exported as schema.sql.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "No tool-managed migrations during MVP. schema.sql is canonical.", + "comment_9c0d1e": "", + "enforced_by": ["review"] + }, + { + "id": "db.migration.backup", + "comment_4d5e6f": "Backup before destructive operations.", + "statement": "Manual destructive database operations MUST be preceded by a verified backup.", + "applies_to": ["db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["review"] + } + ], + "comment_1e2f3a": "End of migration section." + }, + { + "id": "code.audit", + "comment_2b3c4d": "Audit coverage at code and test level.", + "title": "Audit Coverage", + "comment_3c4d5e": "", + "rules": [ + { + "id": "code.audit.emit", + "comment_4d5e6f": "Mutation triggers audit event.", + "statement": "Every mutation of a business table (INSERT, UPDATE, DELETE) MUST emit an audit record.", + "applies_to": ["code", "db", "test"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["test", "ci"] + } + ], + "comment_1e2f3a": "End of code audit section." + }, + { + "id": "test.validation", + "comment_2b3c4d": "Validation and test requirements.", + "title": "Validation & Testing", + "comment_3c4d5e": "", + "rules": [ + { + "id": "test.validation.automated", + "comment_4d5e6f": "Automated tests for constraints and triggers.", + "statement": "All constraints, triggers, and RLS policies MUST have automated tests; migrations MUST be validated before deployment.", + "applies_to": ["test", "db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["ci"] + } + ], + "comment_1e2f3a": "End of test validation section." + }, + { + "id": "meta.exception", + "comment_2b3c4d": "Exception handling and documentation.", + "title": "Exceptions", + "comment_3c4d5e": "", + "rules": [ + { + "id": "meta.exception.doc", + "comment_4d5e6f": "All deviations must be documented.", + "statement": "Any intentional deviation from these conventions MUST be documented with rationale, risks, and approval.", + "applies_to": ["all"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["exceptions"], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["review"] + }, + { + "id": "meta.exception.workflow", + "comment_new3": "Exceptions workflow.", + "statement": "Any new or amended exception MUST be created and linked to a corresponding code review or pull request (PR/issue) in the project tracking system before merging. The exception record MUST include the PR/issue reference and approval metadata.", + "applies_to": ["all"], + "requirement_level": "MUST", + "references": ["exceptions"], + "notes": "Ensures that all exceptions are traceable to formal review and approval.", + "enforced_by": ["review", "ci"] + } + ], + "comment_1e2f3a": "End of exceptions section." + }, + { + "id": "validation.patterns", + "comment_f1e2d3": "Enforce referencing of canonical regex patterns.", + "title": "Validation Patterns", + "rules": [ + { + "id": "validation.patterns.reference", + "comment_a4b5c6": "Reference canonical patterns", + "statement": "All pattern-based validations MUST reference a `pattern_id` from the canonical patterns file, not include inline regex.", + "applies_to": ["db", "ui", "code", "test"], + "requirement_level": "MUST", + "pattern_id": "", + "pattern_ref": "global_validation_patterns.yaml.md", + "references": ["validation_patterns_file"], + "notes": "Tests and application code MUST fetch the regex by pattern_id.", + "enforced_by": ["ci", "review"] + } + ], + "comment_2e3f4g": "End of validation.patterns section." + }, + { + "id": "ui.cross_module", + "comment_2b3c4d": "UI cross-module actions and dependencies.", + "title": "UI Block Cross-Module Dependencies", + "comment_3c4d5e": "", + "rules": [ + { + "id": "ui.cross_module.declare", + "comment_4d5e6f": "Declare module dependencies and function calls for cross-module UI actions.", + "statement": "All UI actions invoking business logic in another module MUST declare module_dependency and function_call fields and be routed through the owning module’s API.", + "applies_to": ["ui", "code"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["ui_blocks_template.json"], + "comment_8b9c0d": "", + "notes": "CI must validate all such specifications.", + "comment_9c0d1e": "", + "enforced_by": ["ci"] + } + ], + "comment_1e2f3a": "End of UI cross-module section." + }, + { + "id": "naming", + "comment_2b3c4d": "Naming conventions for all artifacts.", + "title": "Naming Conventions", + "comment_3c4d5e": "", + "rules": [ + { + "id": "naming.snake_case", + "comment_4d5e6f": "snake_case for db/file/var/function.", + "statement": "All table, column, index, constraint, file, module, variable, and function names MUST use snake_case.", + "applies_to": ["db", "code", "ui"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "Deviations must be documented in exceptions.", + "comment_9c0d1e": "", + "enforced_by": ["review", "ci"] + }, + { + "id": "naming.pascal_case", + "comment_4d5e6f": "PascalCase for Python class and DB models.", + "statement": "Class names (including DB model classes) MUST use PascalCase directly mapped from the table name.", + "applies_to": ["code"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["review"] + } + ], + "comment_1e2f3a": "End of naming conventions section." + }, + { + "id": "registry", + "comment_2b3c4d": "Module registry and source of truth.", + "title": "Module Registry", + "comment_3c4d5e": "", + "rules": [ + { + "id": "registry.canonical", + "comment_4d5e6f": "codebase_registry.json as canonical source.", + "statement": "codebase_registry.json MUST be the single authoritative registry for modules, interfaces, tables, UI pages, and dependencies.", + "applies_to": ["code", "spec"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["codebase_registry.json"], + "comment_8b9c0d": "", + "notes": "", + "comment_9c0d1e": "", + "enforced_by": ["ci", "review"] + }, + { + "id": "registry.ui_block", + "comment_new1": "Require explicit ui_block field in each module definition.", + "statement": "Each module definition in codebase_registry.json MUST include a ui_block field with a relative path to the owning module's UI block definition as per codebase_registry_template.json.", + "applies_to": ["code", "spec"], + "requirement_level": "MUST", + "references": ["codebase_registry_template.json", "ui_blocks_template.json"], + "notes": "Ensures registry and UI block specs stay in sync.", + "enforced_by": ["ci", "review"] + } + ], + "comment_1e2f3a": "End of registry section." + }, + { + "id": "ui.state_hooks", + "comment_2b3c4d": "Persistent UI state hooks.", + "title": "UI State Hooks", + "comment_3c4d5e": "", + "rules": [ + { + "id": "ui.state_hooks.implement", + "comment_4d5e6f": "State persistence hooks.", + "statement": "Every UI block or pane with persistent state MUST implement get_ui_state and set_ui_state hooks as defined in ui_blocks_template.json.", + "applies_to": ["ui", "code", "test"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": ["ui_blocks_template.json"], + "comment_8b9c0d": "", + "notes": "Automated tests or CI must verify presence. Omission must be justified in exceptions.", + "comment_9c0d1e": "", + "enforced_by": ["ci", "test"] + }, + { + "id": "ui.state_hooks.reference", + "comment_new2": "UI block definitions MUST reference their compliance with ui_blocks_template.json.", + "statement": "Each UI block JSON specification MUST include a $template_reference field explicitly referencing ui_blocks_template.json as the authoritative template for state hook structure.", + "applies_to": ["ui", "code", "test"], + "requirement_level": "MUST", + "references": ["ui_blocks_template.json"], + "notes": "This provides unambiguous linkage for automated checks.", + "enforced_by": ["ci", "review"] + } + ], + "comment_1e2f3a": "End of UI state hooks section." + }, + { + "id": "test.isolation", + "comment_2b3c4d": "Test isolation, rollback, idempotency.", + "title": "Test Isolation & Database Rollback", + "comment_3c4d5e": "", + "rules": [ + { + "id": "test.isolation.txn", + "comment_4d5e6f": "Transactional isolation for tests.", + "statement": "All tests interacting with the database MUST run inside a transaction that is rolled back after the test completes.", + "applies_to": ["test", "db"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "Persistent/integration tests must be marked and isolated.", + "comment_9c0d1e": "", + "enforced_by": ["ci", "test"] + } + ], + "comment_1e2f3a": "End of test isolation section." + }, + { + "id": "db.versioning", + "comment_2b3c4d": "Version field requirements.", + "title": "Incremental Version Bumping", + "comment_3c4d5e": "", + "rules": [ + { + "id": "db.versioning.bump", + "comment_4d5e6f": "version must increment on update.", + "statement": "The version column on mutable tables MUST increment by 1 on every UPDATE.", + "applies_to": ["db", "code", "test"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "Enforce via trigger or app logic. Exceptions must be documented.", + "comment_9c0d1e": "", + "enforced_by": ["test", "review", "ci"] + } + ], + "comment_1e2f3a": "End of versioning section." + }, + { + "id": "ops.secrets", + "comment_2b3c4d": "Secrets and configuration management.", + "title": "Secrets & Configuration", + "comment_3c4d5e": "", + "rules": [ + { + "id": "ops.secrets.exclude", + "comment_4d5e6f": "Secrets must not be committed.", + "statement": "All environment config files with secrets MUST be excluded from version control.", + "applies_to": ["ops", "code"], + "comment_6f7a8b": "", + "requirement_level": "MUST", + "references": [], + "comment_8b9c0d": "", + "notes": "Production secrets/credentials must not be stored or shared in plaintext.", + "comment_9c0d1e": "", + "enforced_by": ["review"] + } + ], + "comment_1e2f3a": "End of ops.secrets section." + } + ], + "comment_2e3f4a": "End of sections array.", + "exceptions": [ + { + "rule_id": "db.constraint.timestamps", + "comment_2f3a4b": "Timestamps/versions omitted for static reference table.", + "reason": "Static table; does not mutate.", + "comment_3a4b5c": "Reference/lookup tables don't need timestamps.", + "risks": "None for read-only tables.", + "comment_4b5c6d": "", + "approved_by": "lead-dev", + "comment_5c6d7e": "", + "date": "2025-08-01", + "comment_6d7e8f": "" + } + ], + "comment_7e8f9a": "End of conventions specification." +} diff --git a/Conventions/MVP_WORKFLOW_TEMPLATE.md b/Conventions/MVP_WORKFLOW_TEMPLATE.md new file mode 100644 index 0000000..da652f9 --- /dev/null +++ b/Conventions/MVP_WORKFLOW_TEMPLATE.md @@ -0,0 +1,17 @@ +# MVP Workflow (Narrative) + +This workflow narrative explicitly maps every step to the modules and tables from the current codebase registry. It describes the end-to-end user journey and data flow. + +--- + +## 1. {step description} + +* **Module:** {module_id} +* **Tables:** [tables] +* **Summary:** "summary" + + * step logic, events and actions + +--- + +**Ensure this document is updated in lockstep with `codebase_registry.json` and schema changes when requirements evolve.** diff --git a/Conventions/PROJECT_REQUIREMENTS_TEMPLATE.md b/Conventions/PROJECT_REQUIREMENTS_TEMPLATE.md new file mode 100644 index 0000000..1db3ddf --- /dev/null +++ b/Conventions/PROJECT_REQUIREMENTS_TEMPLATE.md @@ -0,0 +1,58 @@ +# PROJECT_REQUIREMENTS.md (Template) + +## 1. Purpose & Scope +- **Purpose**: What problem does this project solve and for whom? +- **Scope (MVP)**: Boundaries of the first release. + - **Core Features**: Bullet list of must-haves + - **Limitations/Out of Scope**: Explicit non-goals + +## 2. Stakeholders & Actors +- **Stakeholders**: Roles and responsibilities +- **Actors**: End-users or systems interacting with the product + +## 3. User Stories +- As a , I want so that . +- Acceptance criteria for each story + +## 4. Functional Requirements +- Feature A + - Description + - Triggers/Inputs + - Expected behavior + - Errors/edge cases + +## 5. Non-Functional Requirements +- Performance, scalability, availability +- Security and privacy requirements +- Observability (logs/metrics/alerts) + +## 6. Data Model Impact +- Entities/tables affected (reference `codebase_registry.json` and `schema.sql`) +- Enum lists and validation pattern IDs (reference `global_validation_patterns.yaml.md`) + +## 7. API & Interfaces +- Endpoints/functions (paths, methods, request/response schemas) +- Permissions (roles/capabilities) + +## 8. UI Pages & Blocks +- Pages/blocks (reference `ui_blocks_template.json`) +- State persistence (get_ui_state/set_ui_state) + +## 9. Dependencies +- Internal module dependencies (reference `codebase_registry.json`) +- External services/libraries + +## 10. Risks, Assumptions, Constraints +- Known risks and mitigations +- Assumptions that may change +- Constraints (legal, compliance, technical) + +## 11. Exceptions to Conventions +- Proposed exceptions (reference rule IDs from `CONVENTIONS.json`) +- Rationale, risks, approvals, PR/issue links + +## 12. Success Metrics +- KPIs, SLAs, or measurable outcomes for MVP + +## 13. Open Questions +- Outstanding decisions and owners \ No newline at end of file diff --git a/Conventions/atomic_conventions_list.md b/Conventions/atomic_conventions_list.md new file mode 100644 index 0000000..8c52610 --- /dev/null +++ b/Conventions/atomic_conventions_list.md @@ -0,0 +1,102 @@ +# Step 2: Pre-Review Decomposition (Atomic Statements) + +## Approach + +* Each section and sub-rule is broken into **atomic** statements and labeled for reference. +* This step enables precise cross-referencing for the later redundancy, overlap, and logic checks. + +--- + +## **Decomposition Table** + +``` +ID Atomic Rule Statement + +1.1 All audit tables must reside in `audit` schema. +1.2 Audit tables must be protected against modification after insert (REVOKE UPDATE/DELETE). +1.3 For Postgres 12+, enable RLS and policy for insert-only audit logs. +1.4 No application/migration code may alter, update, or delete audit records. +1.5 Audit schema changes must be reviewed/tested for immutability. +2.1 All cross-table references must use explicit FOREIGN KEY constraints. +2.2 Every FOREIGN KEY must specify ON DELETE/ON UPDATE policy. +2.3 All FK columns must have an INDEX. +3.1 Polymorphic link tables must enforce valid (type, id) pairs. +3.2 Use triggers or CI to validate (type, id) pairings. +3.3 Refer to codebase_registry_template.json for relation pattern. +4.1 Unique constraints must be DEFERRABLE INITIALLY IMMEDIATE unless justified. +4.2 Constraints on user/mutable fields must be unique as needed. +5.1 All mutable/business tables must include created_at, updated_at, version. +5.2 Version field must increment on every UPDATE (by app or trigger). +5.3 All module_data.json specs must declare a version field. +5.4 CI/tests must verify all business models/tables have version column and it increments. +5.5 Any mutable table w/o version requires documented exception per Section 12. +5.6 Static lookup/reference tables are exempt. +6.1 All domain value fields must use explicit ENUM types. +6.2 Enum values must be documented and UI-synced if practical. +6.3 Refer to ui_blocks_template.json for mapping. +7.1 JSONB business data must be validated by CHECK, trigger, or app+test. +7.2 Log/debug fields may have relaxed validation if documented. +7.3 Refer to codebase_registry_template.json/ui_blocks_template.json for validation_method. +8.1 All foreign key columns must have an INDEX. +8.2 All frequent filter/sort/join columns must be indexed. +8.3 Indexes must be reviewed with every schema update. +9.1 Each data model must have explicit owner module (see registry template). +9.2 All inter-table relations must be explicit (FK or linking table). +10.1 Every mutation on business table must emit audit record. +10.2 Audit coverage enforced by automated tests (CI fails if not present). +10.3 Refer to codebase_registry_template.json for test description. +11.1 All constraints, triggers, and RLS policies must have automated tests. +11.2 All migrations/schema updates must be validated before deployment. +12.1 Any deviation must be documented (rationale, risk, approval). +12.2 See exceptions array in both templates. +13.1 UI actions invoking cross-module logic must declare module_dependency and function_call. +13.2 Applies to all actions that interact with polymorphic linking or cross-entity relationships. +13.3 All such actions must route through owning module’s API. +13.4 ui_blocks_template.json must reflect these requirements. +13.5 CI must ensure all ui_block.json files conform to this. +13.6 Changes to dependencies must be reviewed for modularity/reuse. +14.1 All DB/table/column/index/constraint names must use snake_case. +14.2 PK columns named `id`. +14.3 FK columns named `_id`. +14.4 Indexes: `idx_
_`. +14.5 Constraints: PK, FK, UQ, CK prefixes as specified. +14.6 Filenames: lowercase, underscores. +14.7 Deviation must be documented/approved. +14.8 Python: Class names PascalCase, file/modules snake_case, functions/vars snake_case. +14.9 DB models use direct PascalCase mapping. +14.10 Non-compliant artifacts must be listed in exceptions. +15.1 All schema changes by hand-written SQL on DB. +15.2 After change, canonical schema dump as schema.sql. +15.3 schema.sql committed after every change. +15.4 No tool-managed migrations during MVP. +15.5 schema.sql is authoritative for code/specs. +15.6 Manual destructive ops require backup. +15.7 Never edit schema.sql directly; update DB then export. +15.8 If/when migration tool is adopted, update and retro-doc migrations. +16.1 Every UI pane/block with state must implement get_ui_state/set_ui_state. +16.2 These hooks must serialize/restore all UI configuration. +16.3 All UI specs must document state hook implementations. +16.4 Tests/CI must verify required hooks. +16.5 Omission must be justified in exceptions. +17.1 codebase_registry.json is authoritative registry. +17.2 All modules/interfaces/deps registered before implementation/spec. +17.3 Registry and codebase/specs must be strictly synced. +17.4 CI/code review must check for drift. +17.5 Major registry changes require approval/documented rationale. +18.1 All DB-interacting tests must run in rollbacked transaction. +18.2 Use fixture/context manager for test DB isolation. +18.3 Tests must be independently repeatable/idempotent. +18.4 Exceptions for integration/migration tests must be documented. +18.5 Persistent tests must be marked/run separately. +19.1 Version column on business tables must increment on UPDATE. +19.2 Enforcement method must be documented in module spec. +19.3 CI/tests verify version increments. +19.4 Exceptions must be documented/approved. +20.1 Env config files with secrets must be excluded from VCS. +20.2 Production secrets/creds never stored/repo/shared plaintext. +20.3 Local .env allowed, but never committed. +20.4 Exposed secrets must be rotated and incident documented. +20.5 Deviations must be approved/justified. +``` + +--- diff --git a/Conventions/codebase_registry_template.json b/Conventions/codebase_registry_template.json new file mode 100644 index 0000000..f5e41f0 --- /dev/null +++ b/Conventions/codebase_registry_template.json @@ -0,0 +1,59 @@ +{ + "$template_reference": "codebase_registry_template.json", + "version": "1.0.0", + "module_creation_order": ["", "", "..."], + "modules": { + "": { + "name": "Module Name", + "functionality": "One-line module description", + "registry": "./modules/.registry.json", + "data_model": "./modules/.data.json", + "logic": "./modules/.logic.md", + "pseudocode": "./modules/.pseudocode.md", + "tests_description": "./tests/.tests-description.md", + "tests_pseudocode": "./tests/.tests-pseudocode.md", + "ui_block": "./modules/.ui_block.json", + "interfaces": ["fn_1", "fn_2"], + "database_tables": ["table1", "table2"], + "ui_pages": ["page1", "page2"], + "dependencies": { + "internal": ["other_module_id"], + "external": ["external_service_name"] + }, + "events": { + "publishes": { + ".event_name": { + "payload": { "field": "type" }, + "when": "condition or trigger for this event" + } + }, + "subscribes": { + "other_module.event": { + "handler": "function_name" + } + } + }, + "permissions": { + "fn_1": "public", + "fn_2": "admin" + }, + "exceptions": [ + { + "rule_id": "conventions_rule_id", + "reason": "Justification for exception", + "risks": "Potential risks", + "approved_by": "approver_name", + "date": "YYYY-MM-DD" + } + ] + } + }, + "shared": { + "comment": "Cross-module data model registry", + "data_models": ["SharedModelA", "SharedModelB"], + "owned_by": { + "SharedModelA": "module_id_1", + "SharedModelB": "module_id_2" + } + } +} diff --git a/Conventions/conventions_template.json b/Conventions/conventions_template.json new file mode 100644 index 0000000..d61ba0f --- /dev/null +++ b/Conventions/conventions_template.json @@ -0,0 +1,50 @@ +{ + "$template_reference": "conventions_template.json", + "validation_patterns_file": "", + "comment_0a1b2c": "Filename for global validation patterns (if applicable).", + "conventions_version": "", + "comment_1a2b3c": "Schema version for the conventions specification.", + "sections": [ + { + "id": "", + "comment_2b3c4d": "Unique identifier for the section.", + "title": "", + "comment_3c4d5e": "Human-readable section title.", + "rules": [ + { + "id": "", + "comment_4d5e6f": "Unique rule identifier.", + "statement": "", + "comment_5e6f7a": "Atomic, concise rule statement using RFC 2119 language.", + "applies_to": [""], + "comment_6f7a8b": "Array of domains the rule applies to (e.g., db, ui, code, test, ops).", + "requirement_level": "", + "comment_7a8b9c": "RFC 2119 requirement level: MUST, SHOULD, MAY, etc.", + "references": [""], + "comment_8b9c0d": "Optional list of references to docs or templates.", + "notes": "", + "comment_9c0d1e": "Optional clarifications, rationale, or exceptions guidance.", + "enforced_by": [""], + "comment_0d1e2f": "Optional enforcement mechanisms (e.g., ci, review, db-policy)." + } + ], + "comment_1e2f3a": "End of rules array for this section." + } + ], + "comment_2e3f4a": "End of sections array.", + "exceptions": [ + { + "rule_id": "", + "comment_2f3a4b": "ID of rule this exception overrides.", + "reason": "", + "comment_3a4b5c": "Rationale for exception.", + "risks": "", + "comment_4b5c6d": "Potential risks of exception.", + "approved_by": "", + "comment_5c6d7e": "Name of approving party.", + "date": "", + "comment_6d7e8f": "Date of approval (YYYY-MM-DD)." + } + ], + "comment_7e8f9a": "End of conventions specification." +} diff --git a/Conventions/custom_instructions.md b/Conventions/custom_instructions.md new file mode 100644 index 0000000..a1d7e48 --- /dev/null +++ b/Conventions/custom_instructions.md @@ -0,0 +1,29 @@ +You are an experienced software engineer assisting in software development and code generation. Optimize for correctness, clarity, and speed of delivery. + +## Workflow + +1. **Plan**: Analyze each request; decompose into explicit, verifiable steps. +2. **Consult Specifications**: + - Use `CONVENTIONS.json` for policy, validation, testing, naming, and exception rules + - Use `codebase_registry_template.json` for module registration and structure + - Use `ui_blocks_template.json` for UI page/block requirements +3. **Execute**: Proceed autonomously when requirements are clear. If blocked by ambiguity or missing inputs, ask targeted questions. +4. **Validate**: + - Verify outputs strictly comply with referenced specs and conventions + - Cite the relevant file/section with every major output +5. **Iterate**: Incorporate feedback and repeat as needed. + +- If a deviation from conventions is required, collect explicit rationale and document it as an exception per `CONVENTIONS.json`. + +--- + +## Output & Formatting + +- Prefer **JSON** for all structured data. Avoid tables. +- YAML is permitted only for canonical pattern registries (e.g., `global_validation_patterns.yaml.md`) if already part of the project; prefer JSON elsewhere. +- Use Markdown (headings, bold, bullets) for explanations. +- Do not invent structure or logic not present in the spec files. + +--- + +**Reference, don’t copy.** Link to or cite spec sections rather than duplicating them. Ensure all implementation aligns with the latest project files. diff --git a/Conventions/global_validation_patterns.yaml.md b/Conventions/global_validation_patterns.yaml.md new file mode 100644 index 0000000..64a8a00 --- /dev/null +++ b/Conventions/global_validation_patterns.yaml.md @@ -0,0 +1,42 @@ +--- + +artifact_type: global_validation_patterns.yaml +module_name: system +version: 1.0 +created_date: 2025-07-24T01:00:00+03:00 + +email_patterns: + standard: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' + +# Matches typical [user@domain.com](mailto:user@domain.com) addresses + +phone_patterns: + international: '^\+[0-9]{1,3}[0-9]{4,14}$' + +# Matches +countrycode and national number (minimum 5 digits, max 17 total) + +date_patterns: + iso8601: '^\d{4}-\d{2}-\d{2}$' + +# Matches YYYY-MM-DD dates + +custom_patterns: + property_code: + regex: '^[A-Z0-9\-]{4,20}$' + description: > + Code assigned to a property (uppercase letters, digits, dashes, 4–20 chars) + examples: ['ABCD-1234', 'A1B2-3456-XYZ'] + counter_examples: ['abcd-1234', 'A!@#-1234'] + image_tag: + regex: '^[a-z0-9\-_ ]{2,50}$' + description: > + Lowercase, numbers, dash, underscore, space, 2–50 chars for tags/captions + examples: ['balcony view', 'kitchen_island', 'open-plan'] + counter_examples: ['BalconyView', '!!kitchen'] + +# validations: +# * Only patterns required by project entities and UI have been included. +# * Pattern names/descriptions conform to template. +# * No creative additions; structure matches framework artifact template. + +--- diff --git a/Conventions/module_specification_template.json b/Conventions/module_specification_template.json new file mode 100644 index 0000000..cb2c81e --- /dev/null +++ b/Conventions/module_specification_template.json @@ -0,0 +1,86 @@ +{ + "$template_reference": "module_specification_template.json", + "id": "module_id", + "name": "Module Name", + "summary": "1-2 sentence functional summary.", + "registry": "./modules/module_id.registry.json", + "data_model": "./modules/module_id.data.json", + "logic": "./modules/module_id.logic.md", + "pseudocode": "./modules/module_id.pseudocode.md", + "tests_description": "./tests/module_id.tests-description.md", + "tests_pseudocode": "./tests/module_id.tests-pseudocode.md", + "ui_block": "./modules/module_id.ui_block.json", + "interfaces": [ + { + "path": "string", + "comment_a1b2c3": "API endpoint (e.g., /api/capture, /api/items/:id).", + "method": "string", + "comment_b2c3d4": "HTTP method (GET, POST, PUT, DELETE).", + "request_schema": "object", + "comment_c3d4e5": "Request body/query params schema.", + "response_schema": "object", + "comment_d4e5f6": "Response body schema.", + "errors": [ + { + "code": "string or integer", + "message": "string", + "comment_e5f6g7": "Known/expected error." + } + ] + } + ], + "database_tables": [ + "string" + ], + "comment_0d1e2f": "List of database tables owned or updated by this module.", + "events": [ + { + "event": "string", + "comment_f6g7h8": "Event name (emitted, handled, or subscribed to).", + "payload_schema": "object" + } + ], + "dependencies": { + "internal": [ + "string" + ], + "external": [ + "string" + ] + }, + "comment_1e2f3a": "Module IDs or external libraries/services required.", + "exceptions": [ + { + "rule_id": "", + "comment_2f3a4b": "ID of rule this exception overrides.", + "reason": "", + "comment_3a4b5c": "Rationale for exception.", + "risks": "", + "comment_4b5c6d": "Potential risks of exception.", + "approved_by": "", + "comment_5c6d7e": "Name of approving party.", + "date": "", + "comment_6d7e8f": "Date of approval (YYYY-MM-DD)." + } + ], + "permissions": [ + { + "role": "string", + "comment_i9j0k1": "User role or capability name.", + "access": "string", + "comment_j0k1l2": "Allowed actions (e.g., read, write, admin)." + } + ], + "ui_pages": [ + "string" + ], + "comment_2f3a4b": "Screens/pages/routes this module powers.", + "edge_cases": [ + "string" + ], + "comment_3a4b5c": "(Optional) Description of tricky or non-obvious edge cases this module must handle.", + "conventions": [ + "string" + ], + "comment_4b5c6d": "Policy or conventions IDs/files this module follows (e.g., CONVENTIONS.json#db.constraint.timestamps)." +} diff --git a/Conventions/schema_template.sql b/Conventions/schema_template.sql new file mode 100644 index 0000000..bf373ea --- /dev/null +++ b/Conventions/schema_template.sql @@ -0,0 +1,100 @@ +-- ============================================== +-- comprehensive_schema_template.sql +-- SQL template following project conventions and schema structure +-- ============================================== + +-- 1. Enable required extensions +CREATE EXTENSION IF NOT EXISTS postgis; +CREATE EXTENSION IF NOT EXISTS pgcrypto; -- for gen_random_uuid() + +-- 2. Audit schema (db.audit.schema) +CREATE SCHEMA IF NOT EXISTS audit; + +-- 3. Common ENUM type definitions (db.constraint.enum) +-- Example: +-- CREATE TYPE {{enum_name}} AS ENUM ({{'value1', 'value2', ...}}); + +-- 4. Reusable trigger for timestamps and version bump (db.versioning.bump) +CREATE OR REPLACE FUNCTION trigger_{{table_name}}_timestamps_and_version() +RETURNS TRIGGER AS $$ +BEGIN + NEW.updated_at := now(); + NEW.version := OLD.version + 1; + RETURN NEW; +END; +$$ LANGUAGE plpgsql; + +-- 5. Table creation template with required conventions +-- Replace {{table_name}} and placeholder fields accordingly +CREATE TABLE {{table_name}} ( + -- Primary key + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), -- naming.snake_case + + -- Business fields (define your columns here) + -- column_name data_type [constraints], + + -- Standard audit columns (db.constraint.timestamps) + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), -- MUST include + updated_at TIMESTAMPTZ NOT NULL DEFAULT now(), -- MUST include + version INTEGER NOT NULL DEFAULT 1, -- MUST include + + -- Reference to user who created/owns record (db.rel.fk) + created_by UUID REFERENCES users(id) ON DELETE SET NULL, + + -- Unique constraint example (db.constraint.unique) + CONSTRAINT uq_{{table_name}}_{{unique_field}} UNIQUE ({{unique_field}}) DEFERRABLE INITIALLY IMMEDIATE, + + -- JSONB validation placeholder (db.constraint.jsonb) + -- Replace {{jsonb_field}} with your JSONB column name + CONSTRAINT ck_{{table_name}}_{{jsonb_field}}_jsonb_valid CHECK (jsonb_typeof({{jsonb_field}}) = 'object') +); + +-- 6. Attach trigger for update operations +CREATE TRIGGER trg_{{table_name}}_timestamps_and_version +BEFORE UPDATE ON {{table_name}} +FOR EACH ROW +EXECUTE FUNCTION trigger_{{table_name}}_timestamps_and_version(); + +-- 7. Index definitions (db.index.fk_and_query) +-- Create indexes for each FOREIGN KEY and frequent query columns +-- Example: +-- CREATE INDEX idx_{{table_name}}_{{column_name}} ON {{table_name}}({{column_name}}); + +-- 8. Audit table template (db.audit.immutability) +-- Copy and adapt for each business table if audit logs are required +CREATE TABLE audit.{{table_name}}_audit ( + operation_id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + table_name TEXT NOT NULL, + operation CHAR(1) NOT NULL CHECK (operation IN ('I','U','D')), + record_id UUID NOT NULL, + changed_data JSONB, + performed_by UUID REFERENCES users(id), + performed_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +-- 9. Polymorphic link table template (db.rel.polymorphic) +-- Define for linking multiple entity types via a single table +CREATE TABLE {{link_table_name}} ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + owner_type TEXT NOT NULL, + owner_id UUID NOT NULL, + item_type TEXT NOT NULL, + item_id UUID NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + created_by UUID REFERENCES users(id), + + -- Prevent duplicate links (db.constraint.unique) + CONSTRAINT uq_{{link_table_name}}_link UNIQUE (owner_type, owner_id, item_type, item_id) DEFERRABLE INITIALLY IMMEDIATE +); + +-- 10. Additional index templates +-- CREATE INDEX idx_{{link_table_name}}_owner ON {{link_table_name}}(owner_type, owner_id); +-- CREATE INDEX idx_{{link_table_name}}_item ON {{link_table_name}}(item_type, item_id); + +-- 11. Notes: +-- • Use snake_case for all identifiers (naming.snake_case). +-- • Document any deviations as exceptions (meta.exception.doc). +-- • Ensure ENUM values remain in sync across DB, code, and UI (db.constraint.enum_sync). +-- • Validate JSONB fields via CHECK, trigger, or tested application logic (db.constraint.jsonb). +-- • All schema changes MUST be hand-written and exported to schema.sql (db.migration.manual). +-- • Backup database prior to destructive operations (db.migration.backup). diff --git a/Conventions/ui_blocks_template.json b/Conventions/ui_blocks_template.json new file mode 100644 index 0000000..ebb3611 --- /dev/null +++ b/Conventions/ui_blocks_template.json @@ -0,0 +1,47 @@ +{ + "$template_reference": "ui_blocks_template.json", + "block_name": "string", + "layout": { + "type": "string", + "comment_layout_type_options": ["grid", "list", "card", "form"], + "structure": {} + }, + "actions": [ + { + "name": "string", + "module_dependency": "string", + "function_call": "string", + "type": "string", + "comment_action_type_options": ["click", "submit", "change", "load"], + "permissions_required": ["public"], + "comment_permissions_required_options": ["public", "authenticated", "admin"], + "validation_method": "CHECK|trigger|application", + "audit_required": true + } + ], + "fields": [ + { + "name": "string", + "type": "string", + "comment_field_type_options": ["string", "number", "enum", "bool", "jsonb"], + "enum_values": [], + "validation": [], + "comment_validation_options": ["required", "unique", "email", "custom"], + "validation_method": "CHECK|trigger|application", + "pattern_id": "string" + } + ], + "exceptions": [ + { + "rule_id": "conventions_rule_id", + "reason": "Why this block deviates from the rule", + "risks": "Risks of this deviation", + "approved_by": "approver_name", + "date": "YYYY-MM-DD" + } + ], + "state_hooks": { + "get_ui_state": { "description": "Return current pane state as a JSON-serializable dict" }, + "set_ui_state": { "description": "Restore pane state from a JSON-serializable dict" } + } +}