Implementation Plan: Configurable Belief State Logging

Branch: 006-configurable-belief-logs | Date: 2025-12-26 | Spec: specs/006-configurable-belief-logs/spec.md Input: Feature specification from /specs/006-configurable-belief-logs/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/templates/commands/plan.md for the execution workflow.

Summary

Implement a configurable logging system with "Belief State" support (Entry, Action, Coherence, Exit). Approach: Use Python's logging module with a custom Context Manager (belief_scope) and extend GlobalSettings with a LoggingConfig model.

Technical Context

Language/Version: Python 3.9+ Primary Dependencies: FastAPI (Backend), Pydantic (Config), Svelte (Frontend) Storage: Filesystem (for log files), JSON (for configuration persistence) Testing: pytest (Backend), manual verification (Frontend) Target Platform: Linux server (primary), cross-platform compatible Project Type: Web application (Backend + Frontend) Performance Goals: Low overhead logging (<1ms per log entry), non-blocking for main thread (mostly) Constraints: Must use standard library logging where possible; Log rotation to prevent disk overflow Scale/Scope: Configurable log levels and retention policies

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Library-First: N/A (Core infrastructure)
CLI Interface: N/A (Configured via UI/API/JSON)
Test-First: Will require unit tests for belief_scope and config updates.
Integration Testing: Will require testing the settings API.
Observability: This feature is the observability enhancement.

Project Structure

Documentation (this feature)

specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)

Source Code (repository root)

backend/
├── src/
│   ├── core/
│   │   ├── config_models.py       # Add LoggingConfig
│   │   ├── config_manager.py      # Update config loading/saving
│   │   └── logger.py              # Add belief_scope and configure_logger
│   └── api/
│       └── routes/
│           └── settings.py        # Update GlobalSettings endpoint
└── tests/
    └── test_logger.py             # New tests for logger logic

frontend/
├── src/
│   ├── pages/
│   │   └── Settings.svelte        # Add logging UI controls
│   └── lib/
│       └── api.js                 # Update API calls if needed

Structure Decision: enhancing existing Backend/Frontend structure.

Complexity Tracking

Fill ONLY if Constitution Check has violations that must be justified

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

3.4 KiB Raw Blame History