# Feature Specification: Configurable Belief State Logging **Feature Branch**: `006-configurable-belief-logs` **Created**: 2025-12-26 **Status**: Draft **Input**: User description: "Меня не устраивает текущее состояния логов проекта, которые я получаю после запуска run.sh. Нужно продумать систему хранения логов, которая будет настраиваемой, включать логирование belief state агента разработки (смотри semantic_protocol.md) и гибко настраиваемой." ## Clarifications ### Session 2025-12-26 - Q: Log rotation policy? → A: Size-based rotation (e.g., 10MB limit, 5 backups). - Q: Belief State disabled behavior? → A: Smart Filter (Suppress Entry/Exit; keep Action/Coherence as standard logs). - Q: Implementation pattern? → A: Context Manager (e.g., `with belief_scope("ID"):`) to auto-handle Entry/Exit/Error. ## User Scenarios & Testing ### User Story 1 - Structured Belief State Logging (Priority: P1) As a developer or AI agent, I want logs to clearly indicate the execution flow and internal state ("Belief State") of the system using a standardized format, so that I can easily debug logic errors and verify semantic coherence. **Why this priority**: This is the core requirement to align with the `semantic_protocol.md` and improve debugging capabilities for the AI agent. **Independent Test**: Trigger an action in the system (e.g., running a migration) and verify that the logs contain entries formatted as `[ANCHOR_ID][STATE] Message`, representing the entry, action, and exit states of the code blocks. **Acceptance Scenarios**: 1. **Given** a function wrapped with a Belief State logger, **When** the function is called, **Then** a log entry `[ANCHOR_ID][Entry] ...` is generated. 2. **Given** a function execution, **When** the core logic is executed, **Then** a log entry `[ANCHOR_ID][Action] ...` is generated. 3. **Given** a function execution completes successfully, **When** it returns, **Then** a log entry `[ANCHOR_ID][Coherence:OK]` and `[ANCHOR_ID][Exit]` are generated. 4. **Given** a function execution fails, **When** an exception is raised, **Then** a log entry `[ANCHOR_ID][Coherence:Failed]` is generated. --- ### User Story 2 - Configurable Logging Settings (Priority: P2) As a user, I want to be able to configure log levels, formats, and destinations via the application settings, so that I can control the verbosity and storage of logs without changing code. **Why this priority**: Provides the "flexible" and "customizable" aspect of the requirement, allowing users to adapt logging to their needs (dev vs prod). **Independent Test**: Change the log level in the settings (e.g., from INFO to DEBUG) and verify that debug messages start appearing in the output. **Acceptance Scenarios**: 1. **Given** the application is running, **When** I update the log level to "DEBUG" in the settings, **Then** debug-level logs are captured and displayed. 2. **Given** the application is running, **When** I enable "File Logging" in settings, **Then** logs are written to the specified file path. 3. **Given** the application is running, **When** I disable "Belief State" logs in settings, **Then** "Entry" and "Exit" logs are suppressed, while "Action" and "Coherence" logs are retained as standard log entries. --- ### Edge Cases - **Invalid Configuration**: What happens if the user provides an invalid log level (e.g., "SUPER_LOUD")? The system should fallback to a safe default (e.g., "INFO") and log a warning. - **File System Errors**: What happens if the configured log file path is not writable? The system should fallback to console logging and alert the user. - **High Volume**: What happens if "Belief State" logging generates too much noise? The system should remain performant, and users should be able to toggle it off easily. ## Requirements ### Functional Requirements - **FR-001**: The system MUST support a `LoggingConfig` structure within the global configuration to store settings for level, format, file path, and belief state enablement. - **FR-002**: The logging system MUST implement a standard format for "Belief State" logs as defined in the system protocols: `[{ANCHOR_ID}][{STATE}] {Message}`. - **FR-003**: The system MUST provide a standard mechanism to easily generate Belief State logs without repetitive boilerplate code, specifically using a **Context Manager** pattern. - **FR-004**: The supported Belief States MUST include: `Entry`, `Action`, `Coherence:OK`, `Coherence:Failed`, `Exit`. - **FR-005**: The system MUST allow dynamic reconfiguration of the logger (e.g., changing levels) when settings are updated. - **FR-006**: The real-time log stream MUST preserve the structured format of Belief State logs so the frontend can potentially render them specially. - **FR-007**: Logs MUST optionally be persisted to a file if configured. - **FR-008**: The file logging system MUST implement size-based rotation (default: 10MB limit, 5 backups) to prevent disk saturation. - **FR-009**: When `enable_belief_state` is False, the logger MUST suppress `Entry` and `Exit` states but retain `Action` and `Coherence` states (stripping the structured prefix if necessary or keeping it as standard info). - **FR-010**: The Context Manager MUST automatically log `[Entry]` on start, `[Exit]` on success, and `[Coherence:Failed]` if an exception occurs (re-raising the exception). ### Key Entities - **LoggingConfig**: A configuration object defining `level` (text), `file_path` (text), `format` (structure), `enable_belief_state` (boolean). - **BeliefStateAdapter**: A component that enforces the semantic protocol format for log entries. ## Success Criteria ### Measurable Outcomes - **SC-001**: Developers can trace the execution flow of a specific task using only the `[ANCHOR_ID]` filtered logs. - **SC-002**: Changing the log level in the configuration file or API immediately (or upon restart) reflects in the log output. - **SC-003**: All "Belief State" logs strictly follow the `[ID][State]` format, allowing for regex parsing. - **SC-004**: System supports logging to both console and file simultaneously if configured. ## Assumptions - The existing real-time streaming mechanism can be adapted or chained with the new logging configuration. - The system protocol definition of states is the source of truth.