BUG-HUNT: [spec-alignment] Database schema documentation in specification is outdated #1289

Open
opened 2026-04-02 08:55:07 +00:00 by freemo · 0 comments
Owner

Bug Report: [spec-alignment] — Database schema documentation in specification is outdated

Severity Assessment

  • Impact: The specification gives a misleading picture of the database schema, which can confuse new developers and make it harder to understand the system architecture.
  • Likelihood: High. Anyone reading the specification will get an incorrect understanding of the database schema.
  • Priority: Low

Location

  • File: docs/specification.md
  • Section: Database Schema

Description

The specification states that the database consists of 12 tables corresponding to the core models. However, the actual implementation in src/cleveragents/infrastructure/database/models.py defines significantly more tables (around 39). The specification seems to be a high-level simplification that does not reflect the full complexity of the database schema, including legacy tables, relationship tables, and other auxiliary tables.

Evidence

A comparison between the specification's claim of 12 tables and the actual number of models defined in src/cleveragents/infrastructure/database/models.py.

Expected Behavior

The specification should provide a more accurate overview of the database schema, or at least acknowledge that the 12 tables are a simplification and that the actual schema is more complex. It could also point to the models.py file as the source of truth for the database schema.

Actual Behavior

The specification provides outdated and misleading information about the number of tables in the database.

Suggested Fix

Update the "Database Schema" section in docs/specification.md to reflect the actual database schema. This could be a more detailed table of models, or a note explaining that the list of 12 models is a high-level overview.

Category

spec-alignment


Metadata

  • Branch: fix/spec-alignment-database-schema-documentation
  • Commit Message: docs(specification): update database schema section to reflect actual model count
  • Milestone: v3.3.0
  • Parent Epic: #362

Subtasks

  • Audit src/cleveragents/infrastructure/database/models.py and enumerate all defined SQLAlchemy models/tables
  • Update the "Database Schema" section in docs/specification.md to accurately reflect the actual number of tables (approximately 39), categorised by purpose (core domain models, relationship/association tables, legacy tables, auxiliary tables)
  • Add a note in the specification directing readers to models.py as the authoritative source of truth for the full database schema
  • Run nox -e lint to confirm no documentation linting regressions
  • Run nox (all default sessions) and fix any errors

Definition of Done

  • The "Database Schema" section in docs/specification.md no longer claims 12 tables as the total count
  • The section either lists all current tables or explicitly acknowledges the 12-table list is a high-level domain overview and references models.py for the full schema
  • No other sections of docs/specification.md contain contradictory or outdated table-count claims
  • All nox stages pass
  • Coverage >= 97%
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Bug Report: [spec-alignment] — Database schema documentation in specification is outdated ### Severity Assessment - **Impact**: The specification gives a misleading picture of the database schema, which can confuse new developers and make it harder to understand the system architecture. - **Likelihood**: High. Anyone reading the specification will get an incorrect understanding of the database schema. - **Priority**: Low ### Location - **File**: `docs/specification.md` - **Section**: Database Schema ### Description The specification states that the database consists of 12 tables corresponding to the core models. However, the actual implementation in `src/cleveragents/infrastructure/database/models.py` defines significantly more tables (around 39). The specification seems to be a high-level simplification that does not reflect the full complexity of the database schema, including legacy tables, relationship tables, and other auxiliary tables. ### Evidence A comparison between the specification's claim of 12 tables and the actual number of models defined in `src/cleveragents/infrastructure/database/models.py`. ### Expected Behavior The specification should provide a more accurate overview of the database schema, or at least acknowledge that the 12 tables are a simplification and that the actual schema is more complex. It could also point to the `models.py` file as the source of truth for the database schema. ### Actual Behavior The specification provides outdated and misleading information about the number of tables in the database. ### Suggested Fix Update the "Database Schema" section in `docs/specification.md` to reflect the actual database schema. This could be a more detailed table of models, or a note explaining that the list of 12 models is a high-level overview. ### Category spec-alignment --- ## Metadata - **Branch**: `fix/spec-alignment-database-schema-documentation` - **Commit Message**: `docs(specification): update database schema section to reflect actual model count` - **Milestone**: v3.3.0 - **Parent Epic**: #362 ## Subtasks - [ ] Audit `src/cleveragents/infrastructure/database/models.py` and enumerate all defined SQLAlchemy models/tables - [ ] Update the "Database Schema" section in `docs/specification.md` to accurately reflect the actual number of tables (approximately 39), categorised by purpose (core domain models, relationship/association tables, legacy tables, auxiliary tables) - [ ] Add a note in the specification directing readers to `models.py` as the authoritative source of truth for the full database schema - [ ] Run `nox -e lint` to confirm no documentation linting regressions - [ ] Run `nox` (all default sessions) and fix any errors ## Definition of Done - [ ] The "Database Schema" section in `docs/specification.md` no longer claims 12 tables as the total count - [ ] The section either lists all current tables or explicitly acknowledges the 12-table list is a high-level domain overview and references `models.py` for the full schema - [ ] No other sections of `docs/specification.md` contain contradictory or outdated table-count claims - [ ] All nox stages pass - [ ] Coverage >= 97% - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.3.0 milestone 2026-04-02 08:55:44 +00:00
freemo self-assigned this 2026-04-02 18:45:25 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#1289
No description provided.