Optimize ROADMAP.md for AI coding agents with structured task definitions

[Copilot]

User description

The roadmap needed restructuring to be usable by AI coding agents. The original document was prose-heavy and lacked the structured format agents need to parse and execute tasks effectively.

Changes

New Documentation Files

• TASKS.md: 17 task definitions with IDs (BUG-001, FEATURE-002, etc.), acceptance criteria, dependencies, and test commands
• SPECIFICATIONS.md: Full code specs for new classes (BaseDownloader, DownloadQueue, RateLimiter, AppConfig) with copy-paste implementations
• POTENTIAL_ISSUES.md: Known blockers (rate limiting, Cloudflare, CTk limitations, thread safety) mapped to affected tasks

ROADMAP.md Restructured

• Added task index table at top with priority icons (🔴🟠🟡🟢), files, and complexity
• Reformatted tasks with machine-parseable structure:

PRIORITY: 🔴 CRITICAL
FILE: downloader/downloader.py
PROBLEM: ...
SOLUTION: ...
FIND THIS CODE: ...
REPLACE WITH: ...
DONE WHEN:
- [ ] Acceptance criterion
TEST: python main.py

README.md Updated

• Added "Contributing with AI Coding Agents" section with prompt templates:

Read ROADMAP.md and implement task BUG-001.
Context: Python desktop app using CustomTkinter.
Follow the FIND/REPLACE instructions in the task.

Documentation Structure

File	Purpose
ROADMAP.md	Task index + quick-reference format
TASKS.md	Detailed breakdowns with context
SPECIFICATIONS.md	New class/function implementations
POTENTIAL_ISSUES.md	Known blockers per task

Original prompt

On ROADMAP.md, Checl the roadmap and begin inrpoving boyh the layout but also optmize to be used for Cod ing amd agents using ot has work. When complete make the roadmaps and new features into separate tasks so iy easy yo read and make notes of thongsthat MIGHT not qork

Custom agent used: clever-coder
Senior-level coding agent that plans first, explains decisions briefly, fixes issues safely, and continuously suggests improvements

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

PR Type

Documentation, Enhancement

---

Description

• Restructured ROADMAP.md with machine-parseable task format for AI agents

• Created TASKS.md with 17 detailed task definitions and acceptance criteria

• Created SPECIFICATIONS.md with full code specifications for new classes

• Created POTENTIAL_ISSUES.md documenting known blockers and edge cases

• Added AI agent prompting guide to README.md with copy-paste templates

---

Diagram Walkthrough

flowchart LR
  A["Original ROADMAP.md<br/>Prose-heavy"] -->|Restructure| B["ROADMAP.md<br/>Task Index + Quick Ref"]
  A -->|Extract Details| C["TASKS.md<br/>17 Task Definitions"]
  A -->|Extract Specs| D["SPECIFICATIONS.md<br/>Class/Function Specs"]
  A -->|Extract Issues| E["POTENTIAL_ISSUES.md<br/>Known Blockers"]
  B -->|Reference| C
  B -->|Reference| D
  B -->|Reference| E
  F["README.md"] -->|Add| G["Agent Prompting Guide<br/>Copy-paste Templates"]
  B -.->|Links to| G

Loading

File Walkthrough

Relevant files

Documentation

ROADMAP.md Restructure roadmap for AI agent parsing and execution      ROADMAP.md Restructured from prose-heavy format to machine-parseable task index with priority icons Added Quick Start for Agents section with file structure reference Created Task Index table with 17 tasks (BUG, REFACTOR, FEATURE, ARCH, TEST) Reformatted each task with PRIORITY, FILE, PROBLEM, SOLUTION, FIND/REPLACE, DONE WHEN, TEST sections Added Agent-Optimized Task Format Reference section Added Quick Copy-Paste Prompts for common agent workflows +523/-13 TASKS.md Create detailed task definitions with acceptance criteria TASKS.md New file with 17 detailed task definitions (T001-T017) Each task includes: problem description, context, requirements, implementation hints, acceptance criteria, estimated effort Organized by category: Critical Bug Fixes (T001-T003), Medium Priority Fixes (T004-T007), Feature Tasks (T008-T017) Includes task dependency graph showing prerequisite relationships Added notes for AI agents on code style, testing, and completion verification +595/-0  SPECIFICATIONS.md Provide full code specifications for new features                SPECIFICATIONS.md New file with 1794 lines of implementation specifications Includes 5 new classes: BaseDownloader (abstract), DownloaderFactory, DownloadQueue, RateLimiter, AppConfig Provides complete copy-paste implementations with docstrings and type hints Includes data classes: DownloadOptions, DownloadResult, MediaItem, QueueItem, NetworkConfig, DownloadConfig, UIConfig Specifies new functions for URL validation, file naming, and utilities Defines UI module structure and component specifications Documents configuration schema (settings.json) and database schema updates Includes API contracts for downloader callbacks +1794/-0 POTENTIAL_ISSUES.md Document known blockers and edge cases                                      POTENTIAL_ISSUES.md New file documenting 6 major issues with quick reference table Details for each issue: problem description, impact, workarounds, agent instructions Issues covered: rate limiting, Cloudflare protection, CTk limitations, thread safety, database locking, translation system Task-specific issues section for FEATURE-001, FEATURE-002, FEATURE-003, ARCH-001 Testing limitations and environment-specific issues (Windows, macOS, Linux) Guidelines for reporting new issues with standard format +334/-0  README.md Add AI agent contribution guide with prompt templates        README.md Added "Contributing with AI Coding Agents" section (94 lines) Created documentation structure table mapping files to use cases Added example prompts for bug fixes, new features, and refactoring tasks Included best practices for agent prompts with 5 key guidelines Added example workflow showing step-by-step agent usage Created task priority guide with icons and agent instructions Provided quick agent commands as copy-paste templates +103/-0

---

[primoscope]

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Sensitive data exposure Description: The specifications introduce persisting potentially sensitive user data (e.g., proxy credentials in AppConfig fields proxy_username/proxy_password and constructing authenticated proxy URLs, plus queue persistence of user-provided URLs via DownloadQueue.QUEUE_FILE) to plaintext JSON under resources/config/, which can lead to local sensitive information exposure if the config directory is readable by other users/processes or accidentally committed/backed up. SPECIFICATIONS.md [776-899] Referred Code @dataclass class NetworkConfig: """Network-related settings.""" proxy_enabled: bool = False proxy_type: str = "http" # http, socks4, socks5 proxy_host: str = "" proxy_port: int = 8080 proxy_username: str = "" proxy_password: str = "" bandwidth_limit_kbps: int = 0 # 0 = unlimited connection_timeout: int = 30 read_timeout: int = 60 @dataclass class DownloadConfig: """Download-related settings.""" max_concurrent_downloads: int = 3 max_retries: int = 3 retry_interval: float = 2.0 chunk_size: int = 1048576 # 1MB ... (clipped 103 lines)
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
🔴	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Secrets in proxy URL: The new AppConfig.get_proxies() specification builds proxy URLs embedding proxy_username and proxy_password, which can easily end up in logs/debug output and is not structured or redacted. Referred Code def get_proxies(self) -> Optional[Dict[str, str]]: """ Get proxy configuration for requests library. Returns: Proxy dict for requests, or None if disabled """ if not self.network.proxy_enabled or not self.network.proxy_host: return None auth = "" if self.network.proxy_username: auth = f"{self.network.proxy_username}:{self.network.proxy_password}@" proxy_url = f"{self.network.proxy_type}://{auth}{self.network.proxy_host}:{self.network.proxy_port}" return { 'http': proxy_url, 'https': proxy_url, } Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Plaintext secret storage: The proposed settings.json schema and AppConfig model include storing proxy_password in plaintext under resources/config/settings.json without any secure storage/encryption guidance. Referred Code @dataclass class NetworkConfig: """Network-related settings.""" proxy_enabled: bool = False proxy_type: str = "http" # http, socks4, socks5 proxy_host: str = "" proxy_port: int = 8080 proxy_username: str = "" proxy_password: str = "" bandwidth_limit_kbps: int = 0 # 0 = unlimited connection_timeout: int = 30 read_timeout: int = 60 @dataclass class DownloadConfig: """Download-related settings.""" max_concurrent_downloads: int = 3 max_retries: int = 3 retry_interval: float = 2.0 chunk_size: int = 1048576 # 1MB ... (clipped 870 lines) Learn more about managing compliance generic rules or creating your own custom rules
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Audit logging unspecified: The new specifications define generic log_callback usage but do not specify logging critical actions with required context like user ID, timestamp, and outcome. Referred Code log_callback: Optional[Callable[[str], None]] = None, progress_callback: Optional[Callable[[int, int, Dict[str, Any]], None]] = None, global_progress_callback: Optional[Callable[[int, int], None]] = None, ): """ Initialize the downloader. Args: download_folder: Path to save downloaded files options: Download configuration options log_callback: Function to call with log messages progress_callback: Function to call with per-file progress (downloaded, total, metadata) global_progress_callback: Function to call with overall progress (completed, total) """ self.download_folder = download_folder self.options = options or DownloadOptions() self.log_callback = log_callback self.progress_callback = progress_callback self.global_progress_callback = global_progress_callback # Cancellation mechanism - use Event for thread safety ... (clipped 76 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Generic exception handling: The added sample implementations catch broad exceptions and handle failures by print(...) warnings without a structured logging/monitoring strategy or clear recovery behavior. Referred Code def _load(self) -> None: """Load queue from disk.""" if self.QUEUE_FILE.exists(): try: with open(self.QUEUE_FILE, 'r') as f: data = json.load(f) self._items = [QueueItem.from_dict(item) for item in data] except (json.JSONDecodeError, KeyError) as e: print(f"Warning: Could not load queue: {e}") self._items = [] def _save(self) -> None: """Save queue to disk.""" self.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True) with open(self.QUEUE_FILE, 'w') as f: json.dump([item.to_dict() for item in self._items], f, indent=2) def _notify_change(self) -> None: """Notify listeners of queue change.""" self._save() if self._on_change: ... (clipped 336 lines) Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Exception details printed: The added example code prints raw exception messages (e.g., config/queue load failures), which may expose internal details in user-visible consoles depending on how the app is distributed. Referred Code def _load(self) -> None: """Load queue from disk.""" if self.QUEUE_FILE.exists(): try: with open(self.QUEUE_FILE, 'r') as f: data = json.load(f) self._items = [QueueItem.from_dict(item) for item in data] except (json.JSONDecodeError, KeyError) as e: print(f"Warning: Could not load queue: {e}") self._items = [] Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Avoid embedding implementation code in documentation Avoid embedding full code implementations in documentation files like SPECIFICATIONS.md. This practice creates a dual source of truth, making maintenance difficult. Instead, implement features directly in Python files. Examples: SPECIFICATIONS.md [21-280] ### 1. BaseDownloader (Abstract Base Class) **File**: `downloader/base.py` (NEW FILE) **Purpose**: Standardize all downloader implementations with a common interface. ```python """ Base downloader class that all site-specific downloaders must inherit from. """ ... (clipped 250 lines) ROADMAP.md [76-106] ### BUG-001: Fix undefined `log_message` variable PRIORITY: 🔴 CRITICAL FILE: downloader/downloader.py LOCATION: safe_request() method, exception handler for status codes 429, 500-504 PROBLEM: The variable log_message is used before being defined in the exception handler. This causes NameError when the server returns 429/500-504 status codes. ... (clipped 21 lines) </details> ### Solution Walkthrough: #### Before: ```markdown // In SPECIFICATIONS.md ### 1. BaseDownloader (Abstract Base Class) **File**: `downloader/base.py` (NEW FILE) ```python from abc import ABC, abstractmethod # ... (many lines of code) class BaseDownloader(ABC): """ Abstract base class for all site-specific downloaders. """ # ... (full implementation) 2. DownloaderFactory File: downloader/factory.py (NEW FILE) # ... (many lines of code) class DownloaderFactory: # ... (full implementation) #### After: ```markdown // In downloader/base.py (NEW FILE) from abc import ABC, abstractmethod # ... (many lines of code) class BaseDownloader(ABC): """ Abstract base class for all site-specific downloaders. """ # ... (full implementation) // In SPECIFICATIONS.md (MODIFIED) ### 1. BaseDownloader (Abstract Base Class) **File**: `downloader/base.py` **Purpose**: Standardize all downloader implementations. **Key Methods**: - `supports_url(url)` - `download(url)` **Note**: See `downloader/base.py` for the full implementation. Suggestion importance[1-10]: 9 __ Why: This suggestion correctly identifies a critical architectural flaw in the PR's approach, as embedding full implementations in markdown files like SPECIFICATIONS.md creates a severe maintenance burden and a dual source of truth.	High
Possible issue	Implement atomic file write operation Implement an atomic write in the _save method by writing to a temporary file and then renaming it to prevent data corruption in queue.json. SPECIFICATIONS.md [513-517] def _save(self) -> None: - """Save queue to disk.""" + """Save queue to disk atomically.""" self.QUEUE_FILE.parent.mkdir(parents=True, exist_ok=True) - with open(self.QUEUE_FILE, 'w') as f: + temp_file = self.QUEUE_FILE.with_suffix('.tmp') + with open(temp_file, 'w') as f: json.dump([item.to_dict() for item in self._items], f, indent=2) + temp_file.rename(self.QUEUE_FILE) Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a potential data corruption issue in the _save method and proposes an atomic write as a robust solution, which is a critical improvement for data integrity.	Medium
	Prevent potential race condition on destroy Prevent a race condition in QueueDialog by initializing self._refresh_job to None in init and checking for it in destroy before cancellation. SPECIFICATIONS.md [1609-1618] +def __init__( + self, + parent, + queue: DownloadQueue, + on_item_action: Optional[Callable[[str, str], None]] = None, + translations: Optional[dict] = None, + **kwargs +): + """ + Initialize the queue dialog. + ... + """ + super().__init__(parent, **kwargs) + + self.queue = queue + self.on_item_action = on_item_action + self.tr = translations or {} + self._refresh_job = None + + self.title(self.tr.get("download_queue", "Download Queue")) + self.geometry("600x400") + + self._create_widgets() + self._refresh() + + # Set up auto-refresh + self._refresh_job = self.after(1000, self._auto_refresh) + def _auto_refresh(self): """Auto-refresh every second.""" self._refresh() self._refresh_job = self.after(1000, self._auto_refresh) def destroy(self): """Clean up when closing.""" - if hasattr(self, '_refresh_job'): + if self._refresh_job: self.after_cancel(self._refresh_job) super().destroy() [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential race condition that could lead to an AttributeError and provides a valid fix by initializing _refresh_job to None, which improves the robustness of the dialog's cleanup logic.	Medium
General	Perform atomic write for configuration Implement an atomic write for saving the settings file by using a temporary file and os.replace to prevent data corruption. app/models/config.py [868-877] def save(self) -> None: - """Save configuration to file.""" + """Save configuration to file atomically.""" self.CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True) data = { 'network': asdict(self.network), 'download': asdict(self.download), 'ui': asdict(self.ui), } - with open(self.CONFIG_PATH, 'w', encoding='utf-8') as f: + temp_path = self.CONFIG_PATH.with_suffix('.tmp') + with open(temp_path, 'w', encoding='utf-8') as f: json.dump(data, f, indent=4) + os.replace(temp_path, self.CONFIG_PATH) [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: This suggestion correctly identifies a critical data integrity issue where the settings file could be corrupted and proposes a robust atomic write solution, significantly improving the application's reliability.	Medium
	Add lock around queue save and notify Wrap the _save() and _on_change() calls in _notify_change with self._lock to ensure thread safety and prevent race conditions. app/models/download_queue.py [519-523] def _notify_change(self) -> None: - """Notify listeners of queue change.""" - self._save() - if self._on_change: - self._on_change() + """Notify listeners of queue change in a thread-safe manner.""" + with self._lock: + self._save() + if self._on_change: + self._on_change() [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential race condition in _notify_change and proposes using a lock to ensure thread safety, which is a good practice for concurrent operations.	Medium
More

[Copilot]

Pull request overview

This PR restructures the project's documentation to make it more accessible and actionable for AI coding agents. The changes transform prose-heavy documentation into machine-parseable, task-oriented formats with clear acceptance criteria, dependencies, and test instructions.

Key changes:

• Created structured task definitions (TASKS.md) with 17 tasks organized by priority
• Added comprehensive implementation specifications (SPECIFICATIONS.md) with copy-paste-ready code for new classes
• Restructured ROADMAP.md with a task index table and standardized task format featuring FIND/REPLACE instructions
• Enhanced README.md with AI agent prompting guidelines and examples
• Added POTENTIAL_ISSUES.md documenting known blockers and edge cases

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
TASKS.md	New file providing 17 detailed task definitions with IDs, acceptance criteria, dependencies, and effort estimates
SPECIFICATIONS.md	New file containing full code specifications for new classes (BaseDownloader, DownloadQueue, RateLimiter, AppConfig) with implementation details
ROADMAP.md	Restructured with task index table, agent-optimized format with FIND/REPLACE instructions, and quick-reference sections
README.md	Added "Contributing with AI Coding Agents" section with prompt templates and best practices for using the documentation
POTENTIAL_ISSUES.md	New file documenting known issues like rate limiting, Cloudflare protection, CTk limitations, and threading concerns

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Inconsistent naming: The file uses both "agent-optimized" (lowercase in body) and "Agent-Optimized" (title case in section heading at line 1353). Consider standardizing to one style for consistency throughout the document.

Suggested change

	## Agent-Optimized Task Format Reference
	## agent-optimized Task Format Reference

[Copilot]

The "Last updated" timestamp at line 595 and 1794 shows "December 2024", but the PR metadata indicates the current date is December 27, 2025. This timestamp is over a year in the past and should be updated to reflect the actual date of these changes.

Suggested change

	*Last updated: December 2024*
	*Last updated: December 27, 2025*

[Copilot]

The "Last updated" timestamp shows "December 2024", but the PR metadata indicates the current date is December 27, 2025. This timestamp is over a year in the past and should be updated to reflect the actual date of these changes.

Suggested change

	*Last updated: December 2024*
	*Last updated: December 27, 2025*

[Copilot]

The "Last updated" timestamp at lines 1456-1457 shows "December 2024", but the PR metadata indicates the current date is December 27, 2025. This timestamp is over a year in the past and should be updated to reflect the actual date of these changes.

Suggested change

	*Last updated: December 2024*
	*Last updated: December 27, 2025*

[Copilot]

The "Last updated" timestamp shows "December 2024", but the PR metadata indicates the current date is December 27, 2025. This timestamp is over a year in the past and should be updated to reflect the actual date of these changes.

Suggested change

	*Last updated: December 2024*
	*Last updated: December 27, 2025*

[Copilot]

The DownloadQueue class uses Path("resources/config/queue.json") as QUEUE_FILE on line 488. This hardcoded path may cause issues if the working directory changes or if the application is run from a different location. Consider using a path relative to the module location or making it configurable.

Suggested change

	QUEUE_FILE = Path("resources/config/queue.json")
	QUEUE_FILE = (Path(__file__).resolve().parent / "resources" / "config" / "queue.json")

[Copilot]

In the DownloadQueue._save() method on lines 513-517, writing directly to the queue file could result in data corruption if the application crashes during the write operation. Consider using atomic writes (write to a temporary file, then rename) to prevent corruption, as mentioned in POTENTIAL_ISSUES.md line 239.

Suggested change

	with open(self.QUEUE_FILE, 'w') as f:
	json.dump([item.to_dict() for item in self._items], f, indent=2)
	import os
	import tempfile
	tmp_dir = self.QUEUE_FILE.parent
	with tempfile.NamedTemporaryFile(
	mode='w',
	dir=tmp_dir,
	prefix=self.QUEUE_FILE.name,
	suffix='.tmp',
	delete=False,
	encoding='utf-8',
	) as tmp_file:
	json.dump([item.to_dict() for item in self._items], tmp_file, indent=2)
	tmp_file.flush()
	os.fsync(tmp_file.fileno())
	Path(tmp_file.name).replace(self.QUEUE_FILE)

[Copilot]

The error handling in DownloadQueue._load() on lines 509-510 prints a warning to stdout but doesn't log it through a proper logging system. This makes it difficult to diagnose issues in production. Consider using Python's logging module or providing a callback for error reporting.

Suggested change

	print(f"Warning: Could not load queue: {e}")
	import logging
	logging.getLogger(__name__).warning(
	"Could not load download queue from %s: %s",
	self.QUEUE_FILE,
	e,
	)

[Copilot]

The AppConfig._from_dict() method on lines 861-866 doesn't validate that the nested dictionaries contain valid data before passing them to the dataclass constructors. If the configuration file contains invalid data types or missing required fields, this could raise unexpected exceptions. Consider adding validation or using a try-except block with more specific error handling.

Suggested change

	network = NetworkConfig(**data.get('network', {}))
	download = DownloadConfig(**data.get('download', {}))
	ui = UIConfig(**data.get('ui', {}))
	# Ensure nested sections are dictionaries before unpacking into dataclasses.
	network_data = data.get('network') or {}
	if not isinstance(network_data, dict):
	print("Warning: Invalid 'network' section in config; using defaults.")
	network_data = {}
	download_data = data.get('download') or {}
	if not isinstance(download_data, dict):
	print("Warning: Invalid 'download' section in config; using defaults.")
	download_data = {}
	ui_data = data.get('ui') or {}
	if not isinstance(ui_data, dict):
	print("Warning: Invalid 'ui' section in config; using defaults.")
	ui_data = {}
	# Construct section configs with per-section error handling so that
	# a malformed section does not prevent loading the entire config.
	try:
	network = NetworkConfig(**network_data)
	except (TypeError, ValueError) as e:
	print(f"Warning: Could not load 'network' config: {e}; using defaults.")
	network = NetworkConfig()
	try:
	download = DownloadConfig(**download_data)
	except (TypeError, ValueError) as e:
	print(f"Warning: Could not load 'download' config: {e}; using defaults.")
	download = DownloadConfig()
	try:
	ui = UIConfig(**ui_data)
	except (TypeError, ValueError) as e:
	print(f"Warning: Could not load 'ui' config: {e}; using defaults.")
	ui = UIConfig()

[Copilot]

The QueueDialog._auto_refresh() method creates an infinite loop of after() calls that's only stopped when the dialog is destroyed. If destroy() is not called properly or if there's an exception before destroy() completes, the after() job may continue running indefinitely, causing a resource leak. Consider adding error handling to ensure the refresh job is cancelled in all code paths.

Suggested change

	self._refresh()
	self._refresh_job = self.after(1000, self._auto_refresh)
	def destroy(self):
	"""Clean up when closing."""
	if hasattr(self, '_refresh_job'):
	self.after_cancel(self._refresh_job)
	try:
	# If the widget has been destroyed, do not schedule further refreshes.
	if not self.winfo_exists():
	return
	self._refresh()
	except Exception:
	# Best-effort cancellation of any pending refresh job before propagating the error.
	if hasattr(self, '_refresh_job'):
	try:
	self.after_cancel(self._refresh_job)
	except Exception:
	pass
	else:
	self._refresh_job = None
	raise
	else:
	self._refresh_job = self.after(1000, self._auto_refresh)
	def destroy(self):
	"""Clean up when closing."""
	if hasattr(self, '_refresh_job') and self._refresh_job is not None:
	try:
	self.after_cancel(self._refresh_job)
	except Exception:
	# If cancellation fails (e.g., job already executed), ignore and proceed.
	pass
	finally:
	self._refresh_job = None