docs: Add Python 3.9+ requirement and DB pattern docs (#136)

[deucebucket]

Summary

• Added Python 3.9+ requirement comment to requirements.txt (needed for Path.is_relative_to())
• Documented the get_db() connection pattern in worker.py docstring to clarify that each call returns a fresh connection

Test plan

• ruff check . --select=F821 passes (no undefined names)
• Changes are documentation-only (comments), no logic affected

[bucket-agent]

🔍 Vibe Check Review

Context

PR #145 adds documentation for Python 3.9+ requirement and database connection patterns in response to Issue #136 tech debt.

Codebase Patterns I Verified

• ✅ get_db() in library_manager/database.py:221 - Confirmed it returns a NEW sqlite3 connection each call with timeout=30s
• ✅ Path.is_relative_to() used in 3 pipeline files - Confirmed Python 3.9+ is required
• ✅ Logging patterns in path_safety.py - Uses logger.debug() for OSError at line 342
• ✅ api_stats() at app.py:8554 - Already has Issue [BUG] Queue count mismatch and orphaned queue items after layer failures #131 comment at line 8562 explaining the query

✅ Good

• Accurate documentation: The get_db() comment correctly describes the Flask-SQLite pattern
• Clear Python requirement: Comment in requirements.txt directly references the reason (Path.is_relative_to())
• No breaking changes: Pure documentation PR, zero risk
• Clean commit: Only touches the 2 files mentioned, no scope creep

🚨 Issues Found

Severity	Location	Issue	Fix
SCOPE_PARTIAL	PR scope	PR only addresses 2 of 4 scope items	See Scope Verification below

📋 Scope Verification

Issue	Problem	Addressed?	Notes
#136	Document Python 3.9+ requirement	✅	Comment added to requirements.txt
#136	Document get_db() pattern in worker.py	✅	Clear docstring added explaining new connection per call
#136	Document api_stats() query complexity	⚠️	Comment ALREADY EXISTS at line 8562 from Issue #131 - may be sufficient
#136 Expansion	Change OSError logging to warning in find_existing_author_folder()	❌	NOT ADDRESSED - still using logger.debug() at path_safety.py:342
#136 Expansion	Add parameter type docs to find_existing_author_folder()	❌	NOT ADDRESSED - function at path_safety.py:318 has no parameter docs

Scope Status: SCOPE_PARTIAL

Missing Items:

1. path_safety.py:342 - OSError is logged at DEBUG level, scope says change to WARNING:

   # Current (line 342):
   logger.debug(f"Error listing library directory {lib_path}: {e}")
   
   # Scope says should be:
   logger.warning(f"Error listing library directory {lib_path}: {e}")

2. path_safety.py:318 - Function docstring missing parameter type documentation:

   # Current (line 318-330):
   def find_existing_author_folder(lib_path, target_author) -> Optional[str]:
       """Find an existing author folder that matches target_author (Issue #142).
       
       [Description of matching strategies]
       
       Returns the existing folder name if found, None otherwise.
       """
   
   # Scope says should document:
   # Args:
   #     lib_path: Path-like object to library directory
   #     target_author: str, author name to match

3. app.py:8562 - The api_stats() query already has a comment from Issue [BUG] Queue count mismatch and orphaned queue items after layer failures #131. The scope document says to "add comment at line 8562 explaining JOIN + filters" but this may already be satisfied. The existing comment reads: # Issue #131: Count only processable queue items (matching process_queue filters). This is arguably sufficient, but could be more detailed about the JOIN.

📝 Documentation Check

• CHANGELOG.md: N/A - docs: PRs don't require CHANGELOG entries
• README.md: N/A - Internal documentation changes only

🎯 Verdict

REQUEST_CHANGES

Required Changes:

1. ❌ MISSING: path_safety.py OSError logging - Change logger.debug() to logger.warning() at line 342
2. ❌ MISSING: path_safety.py parameter docs - Add Args: section to find_existing_author_folder() docstring at line 318
3. ⚠️ OPTIONAL: app.py api_stats comment - Consider making the existing Issue [BUG] Queue count mismatch and orphaned queue items after layer failures #131 comment more detailed about the JOIN purpose, OR confirm existing comment is sufficient

Why REQUEST_CHANGES:
The PR only delivers 50% of the documented scope (2/4 items). The "Scope Expansions" from Issue #136 are completely missing. While the changes made are good, the scope document explicitly lists these as part of #136 and they should be included in this PR.

Note to maintainer: If the scope expansions should be separate PRs, that's fine - but the PR description should note "partial implementation" and the issue should remain open until all items are completed.

[bucket-agent]

🔍 Vibe Check Review

Context

PR #145 addresses Issue #136 scope expansions: upgrades OSError logging from debug to warning in find_existing_author_folder() and adds parameter documentation to its docstring.

Codebase Patterns I Verified

• Logging: Uses logger = logging.getLogger(__name__) pattern throughout
• Logging levels: Checked library_manager/utils/ - uses logger.warning() for OSErrors, logger.debug() for verbose output, logger.error() for blocking issues
• Docstrings: Existing functions use Args/Returns sections with parameter descriptions
• Python 3.9+ requirement: Verified with grep - is_relative_to() used in 3 locations in pipeline layers, confirming the requirement

✅ Good

• Clean, focused scope expansion addressing vibe-check feedback from first [TECHDEBT] Document Python 3.9+ requirement and DB connection patterns #136 PR
• Logging level change is appropriate - OSErrors on library directory listing should be warnings, not hidden in debug logs
• Parameter documentation follows existing docstring style
• Python 3.9+ requirement documentation in requirements.txt is clear and references the actual usage

🚨 Issues Found

None found.

All changes are correct and match codebase patterns:

• Line 21 path_safety.py: logger.warning(...) matches pattern for filesystem errors
• Lines 9-11 path_safety.py: Args section follows existing docstring format
• Line 46 requirements.txt: Comment is accurate (verified is_relative_to() usage exists)
• Lines 34-37 worker.py: get_db() documentation accurately describes Flask-SQLite pattern

📋 Scope Verification

Issue	Problem	Addressed?	Notes
#136 (expansion 1)	Change OSError logging to warning	✅	path_safety.py:21 - Changed from debug to warning
#136 (expansion 2)	Add parameter type docs to find_existing_author_folder()	✅	path_safety.py:9-11 - Args section added
#136 (original - partial)	Document Python 3.9+ requirement	✅	requirements.txt:1 - Comment added (from first PR, commit 61778f2)
#136 (original - partial)	Document get_db() pattern	✅	worker.py:34-37 - Comment added (from first PR, commit 61778f2)
#136 (original - partial)	api_stats() query comment	✅	app.py:8555 - Already exists from Issue #131 (commit 2b8fe9f)

Scope Status: SCOPE_OK

Note: This is the SECOND PR for Issue #136. The first PR (commit 61778f2) added Python 3.9+ and get_db() documentation. This PR addresses scope expansions identified during vibe-check review of the first PR. The api_stats() comment mentioned in the scope was already added in an earlier commit (2b8fe9f) for Issue #131.

📝 Documentation Check

N/A - This is a fix: PR addressing code quality/documentation, not a feat: or security: PR requiring CHANGELOG updates.

🎯 Verdict

APPROVE

This PR correctly addresses the scope expansions from vibe-check review of the first #136 PR. All changes are appropriate, safe, and follow existing codebase patterns. No issues found.