From ca9d7d9e900881096990da273e9d29917961a210 Mon Sep 17 00:00:00 2001 From: sstent Date: Thu, 18 Dec 2025 13:21:54 -0800 Subject: [PATCH] Complete spec: Code alignment and documentation cleanup - Ensure code aligns with CentralDB models - Document code alignment with CentralDB models - Remove informal reference documents (data-model.md, DB_API_SPEC.json, GARMINSYNC_SPEC.md) - Run linters and formatters (black, isort, mypy) - Update project configuration files - Add .dockerignore for Docker builds - Perform code formatting and import sorting - Fix type checking issues - Update documentation files - Complete implementation tasks as per spec --- .dockerignore | 20 ++ .flake8 | 3 + .kilocode/workflows/speckit.analyze.md | 8 +- .kilocode/workflows/speckit.checklist.md | 37 ++- .kilocode/workflows/speckit.clarify.md | 72 +++-- .kilocode/workflows/speckit.constitution.md | 11 +- .kilocode/workflows/speckit.implement.md | 88 ++++-- .kilocode/workflows/speckit.plan.md | 13 +- .kilocode/workflows/speckit.specify.md | 84 ++++- .kilocode/workflows/speckit.tasks.md | 108 ++++--- .kilocode/workflows/speckit.taskstoissues.md | 30 ++ .qwen/commands/speckit.analyze.toml | 188 +++++++++++ .qwen/commands/speckit.checklist.toml | 298 ++++++++++++++++++ .qwen/commands/speckit.clarify.toml | 185 +++++++++++ .qwen/commands/speckit.constitution.toml | 86 +++++ .qwen/commands/speckit.implement.toml | 139 ++++++++ .qwen/commands/speckit.plan.toml | 93 ++++++ .qwen/commands/speckit.specify.toml | 262 +++++++++++++++ .qwen/commands/speckit.tasks.toml | 141 +++++++++ .qwen/commands/speckit.taskstoissues.toml | 34 ++ DB_API_SPEC.json | 1 - GEMINI.md | 60 +++- README.md | 58 ++++ backend/=0.8.0 | 14 + backend/data/activity_20669357248.fit | Bin 0 -> 210164 bytes backend/data/activity_20679068540.fit | Bin 0 -> 409427 bytes backend/data/activity_20711083888.fit | Bin 0 -> 105535 bytes backend/pyproject.toml | 2 +- backend/src/api/garmin_auth.py | 41 +-- backend/src/api/garmin_sync.py | 20 +- backend/src/config.py | 4 +- backend/src/models/central_db_models.py | 66 ++++ backend/src/models/sync_job.py | 3 +- backend/src/schemas.py | 3 +- backend/src/services/central_db_service.py | 18 +- .../src/services/garmin_activity_service.py | 32 +- backend/src/services/garmin_auth_service.py | 32 +- backend/src/services/garmin_health_service.py | 107 +++++-- .../src/services/garmin_workout_service.py | 26 +- backend/src/services/sync_manager.py | 15 +- backend/tests/api/test_garmin_auth_api.py | 12 +- backend/tests/api/test_garmin_sync_api.py | 3 +- .../integration/test_central_db_service.py | 63 ++++ .../test_garmin_authentication_flow.py | 12 +- backend/tests/unit/test_auth_service.py | 9 +- backend/tests/unit/test_central_db_models.py | 73 +++++ backend/tests/unit/test_central_db_service.py | 1 - .../tests/unit/test_garmin_auth_service.py | 12 +- backend/tests/unit/test_rate_limiter.py | 2 +- backend/tests/unit/test_sync_manager.py | 40 ++- data-model.md | 130 -------- mypy.ini | 3 + pytest.ini | 2 + .../checklists/requirements.md | 34 ++ specs/005-ensure-the-current/plan.md | 66 ++++ specs/005-ensure-the-current/research.md | 12 + specs/005-ensure-the-current/spec.md | 133 ++++++++ specs/005-ensure-the-current/tasks.md | 94 ++++++ 58 files changed, 2726 insertions(+), 377 deletions(-) create mode 100644 .dockerignore create mode 100644 .flake8 create mode 100644 .kilocode/workflows/speckit.taskstoissues.md create mode 100644 .qwen/commands/speckit.analyze.toml create mode 100644 .qwen/commands/speckit.checklist.toml create mode 100644 .qwen/commands/speckit.clarify.toml create mode 100644 .qwen/commands/speckit.constitution.toml create mode 100644 .qwen/commands/speckit.implement.toml create mode 100644 .qwen/commands/speckit.plan.toml create mode 100644 .qwen/commands/speckit.specify.toml create mode 100644 .qwen/commands/speckit.tasks.toml create mode 100644 .qwen/commands/speckit.taskstoissues.toml delete mode 100644 DB_API_SPEC.json create mode 100644 backend/=0.8.0 create mode 100644 backend/data/activity_20669357248.fit create mode 100644 backend/data/activity_20679068540.fit create mode 100644 backend/data/activity_20711083888.fit create mode 100644 backend/src/models/central_db_models.py create mode 100644 backend/tests/integration/test_central_db_service.py create mode 100644 backend/tests/unit/test_central_db_models.py delete mode 100644 backend/tests/unit/test_central_db_service.py delete mode 100644 data-model.md create mode 100644 mypy.ini create mode 100644 pytest.ini create mode 100644 specs/005-ensure-the-current/checklists/requirements.md create mode 100644 specs/005-ensure-the-current/plan.md create mode 100644 specs/005-ensure-the-current/research.md create mode 100644 specs/005-ensure-the-current/spec.md create mode 100644 specs/005-ensure-the-current/tasks.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..1f31f73 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,20 @@ +node_modules/ +.git/ +*.log* +.env* +coverage/ +__pycache__/ +*.pyc +.DS_Store +Thumbs.db +*.tmp +*.swp +.vscode/ +.idea/ +build/ +dist/ +*.egg-info/ +.pytest_cache/ +.mypy_cache/ +.venv/ +venv/ \ No newline at end of file diff --git a/.flake8 b/.flake8 new file mode 100644 index 0000000..513d01e --- /dev/null +++ b/.flake8 @@ -0,0 +1,3 @@ +[flake8] +exclude = .venv,examples,backend/src/central_db_client +max-line-length = 120 diff --git a/.kilocode/workflows/speckit.analyze.md b/.kilocode/workflows/speckit.analyze.md index 8e510de..98b04b0 100644 --- a/.kilocode/workflows/speckit.analyze.md +++ b/.kilocode/workflows/speckit.analyze.md @@ -12,13 +12,13 @@ You **MUST** consider the user input before proceeding (if not empty). ## Goal -Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`. +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. ## Operating Constraints **STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). -**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`. +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. ## Execution Steps @@ -154,9 +154,9 @@ Output a Markdown report (no file writes) with the following structure: At end of report, output a concise Next Actions block: -- If CRITICAL issues exist: Recommend resolving before `/implement` +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions -- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" ### 8. Offer Remediation diff --git a/.kilocode/workflows/speckit.checklist.md b/.kilocode/workflows/speckit.checklist.md index 5417f6a..970e6c9 100644 --- a/.kilocode/workflows/speckit.checklist.md +++ b/.kilocode/workflows/speckit.checklist.md @@ -7,12 +7,14 @@ description: Generate a custom checklist for the current feature based on user r **CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. **NOT for verification/testing**: + - ❌ NOT "Verify the button clicks correctly" - ❌ NOT "Test error handling works" - ❌ NOT "Confirm the API returns 200" - ❌ NOT checking if code/implementation matches the spec **FOR requirements quality validation**: + - ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) - ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) - ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) @@ -77,7 +79,7 @@ You **MUST** consider the user input before proceeding (if not empty). - spec.md: Feature requirements and scope - plan.md (if exists): Technical details, dependencies - tasks.md (if exists): Implementation tasks - + **Context Loading Strategy**: - Load only necessary portions relevant to active focus areas (avoid full-file dumping) - Prefer summarizing long sections into concise scenario/requirement bullets @@ -88,7 +90,7 @@ You **MUST** consider the user input before proceeding (if not empty). - Create `FEATURE_DIR/checklists/` directory if it doesn't exist - Generate unique checklist filename: - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) - - Format: `[domain].md` + - Format: `[domain].md` - If file exists, append to existing file - Number items sequentially starting from CHK001 - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) @@ -100,7 +102,7 @@ You **MUST** consider the user input before proceeding (if not empty). - **Consistency**: Do requirements align with each other? - **Measurability**: Can requirements be objectively verified? - **Coverage**: Are all scenarios/edge cases addressed? - + **Category Structure** - Group items by requirement quality dimensions: - **Requirement Completeness** (Are all necessary requirements documented?) - **Requirement Clarity** (Are requirements specific and unambiguous?) @@ -111,14 +113,14 @@ You **MUST** consider the user input before proceeding (if not empty). - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) - **Dependencies & Assumptions** (Are they documented and validated?) - **Ambiguities & Conflicts** (What needs clarification?) - + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: - + ❌ **WRONG** (Testing implementation): - "Verify landing page displays 3 episode cards" - "Test hover states work on desktop" - "Confirm logo click navigates home" - + ✅ **CORRECT** (Testing requirements quality): - "Are the exact number and layout of featured episodes specified?" [Completeness] - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] @@ -127,7 +129,7 @@ You **MUST** consider the user input before proceeding (if not empty). - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] - "Are loading states defined for asynchronous episode data?" [Completeness] - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] - + **ITEM STRUCTURE**: Each item should follow this pattern: - Question format asking about requirement quality @@ -135,28 +137,28 @@ You **MUST** consider the user input before proceeding (if not empty). - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] - Reference spec section `[Spec §X.Y]` when checking existing requirements - Use `[Gap]` marker when checking for missing requirements - + **EXAMPLES BY QUALITY DIMENSION**: - + Completeness: - "Are error handling requirements defined for all API failure modes? [Gap]" - "Are accessibility requirements specified for all interactive elements? [Completeness]" - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" - + Clarity: - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" - + Consistency: - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" - "Are card component requirements consistent between landing and detail pages? [Consistency]" - + Coverage: - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" - + Measurability: - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" @@ -192,7 +194,7 @@ You **MUST** consider the user input before proceeding (if not empty). - ❌ "Click", "navigate", "render", "load", "execute" - ❌ Test cases, test plans, QA procedures - ❌ Implementation details (frameworks, APIs, algorithms) - + **✅ REQUIRED PATTERNS** - These test requirements quality: - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" - ✅ "Is [vague term] quantified/clarified with specific criteria?" @@ -222,6 +224,7 @@ To avoid clutter, use descriptive types and clean up obsolete checklists when do **UX Requirements Quality:** `ux.md` Sample items (testing the requirements, NOT the implementation): + - "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" - "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" - "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" @@ -232,6 +235,7 @@ Sample items (testing the requirements, NOT the implementation): **API Requirements Quality:** `api.md` Sample items: + - "Are error response formats specified for all failure scenarios? [Completeness]" - "Are rate limiting requirements quantified with specific thresholds? [Clarity]" - "Are authentication requirements consistent across all endpoints? [Consistency]" @@ -241,6 +245,7 @@ Sample items: **Performance Requirements Quality:** `performance.md` Sample items: + - "Are performance requirements quantified with specific metrics? [Clarity]" - "Are performance targets defined for all critical user journeys? [Coverage]" - "Are performance requirements under different load conditions specified? [Completeness]" @@ -250,6 +255,7 @@ Sample items: **Security Requirements Quality:** `security.md` Sample items: + - "Are authentication requirements specified for all protected resources? [Coverage]" - "Are data protection requirements defined for sensitive information? [Completeness]" - "Is the threat model documented and requirements aligned to it? [Traceability]" @@ -279,9 +285,10 @@ Sample items: ``` **Key Differences:** + - Wrong: Tests if the system works correctly - Correct: Tests if the requirements are written correctly - Wrong: Verification of behavior - Correct: Validation of requirement quality -- Wrong: "Does it do X?" +- Wrong: "Does it do X?" - Correct: "Is X clearly specified?" diff --git a/.kilocode/workflows/speckit.clarify.md b/.kilocode/workflows/speckit.clarify.md index 4a704fa..6b28dae 100644 --- a/.kilocode/workflows/speckit.clarify.md +++ b/.kilocode/workflows/speckit.clarify.md @@ -1,5 +1,9 @@ --- description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... --- ## User Input @@ -84,50 +88,63 @@ Execution steps: 3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - Maximum of 10 total questions across the whole session. - Each question must be answerable with EITHER: - * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR - * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). - - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. - - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. - - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). - - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. - - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. 4. Sequential questioning loop (interactive): - Present EXACTLY ONE question at a time. - - For multiple‑choice questions render options as a Markdown table: + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: | Option | Description | |--------|-------------| | A |