feat: debug logs under ~/.specfact/logs and release 0.26.13

[djm81]

Description

When --debug is enabled, debug output is now written to both console and a persistent log file at ~/.specfact/logs/specfact-debug.log. This branch adds:

• User-level log directory: get_specfact_home_logs_dir() in logger_setup.py; ~/.specfact/logs created with mode 0o755 on first use.
• Runtime: debug_print() and debug_log_operation() in runtime.py; after set_debug_mode(True), init_debug_log_file() prepares the log file. Log lines use timestamp | caller | message and structured JSON for operations.
• Adapters: ADO (WIQL, Work Items GET/PATCH) and GitHub (API GET) log operation metadata when debug is on.
• Commands: Consistent started → success/failed debug log entries across commands (analyze, auth, backlog, contract, drift, enforce, generate, import, init, migrate, plan, project, repro, sdd, spec, sync, update, validate). Upgrade “up to date” path now logs success to the file (parity with “installed” path).
• Docs: docs/reference/debug-logging.md, troubleshooting and directory-structure updates, OpenSpec change add-debug-logs-specfact-home.
• Tests: Unit tests for get_specfact_home_logs_dir, plain_text_for_debug_log, format_debug_log_message, and runtime debug file/print behaviour.
• Release: Version 0.26.13; CHANGELOG entries for 0.26.12 (debug logs) and 0.26.13 (upgrade log parity).

New Features #158

Closes #158

Contract References: No new @icontract decorators; existing command contracts unchanged. debug_log_operation / debug_print are no-ops when debug is off.

Type of Change

Please check all that apply:

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔒 Contract enforcement (adding/updating @icontract decorators)
• 🧪 Test enhancement (scenario tests, property-based tests)
• 🔧 Refactoring (code improvement without functionality change)

Contract-First Testing Evidence

Required for all changes affecting CLI commands or public APIs:

Contract Validation

• Runtime contracts added/updated (@icontract decorators on public APIs)
• Type checking enforced (@beartype decorators applied)
• CrossHair exploration completed: hatch run contract-test-exploration
• Contract violations reviewed and addressed (no new contracts; existing ones unchanged)

Test Execution

• Contract validation: hatch run contract-test-contracts ✅
• Contract exploration: hatch run contract-test-exploration ✅
• Scenario tests: hatch run contract-test-scenarios ✅
• Full test suite: hatch run contract-test-full ✅

Test Quality

• CLI commands tested with typer test client
• Edge cases covered with Hypothesis property tests
• Error handling tested with invalid inputs
• Rich console output verified manually or with snapshots

How Has This Been Tested?

Contract-First Approach: Changes are additive (debug-only code paths); contract tests and scenario tests continue to pass. New unit tests cover logger_setup helpers and runtime debug file/print behaviour.

Manual Testing

• Tested CLI commands manually (specfact --debug sdd list --repo ., specfact --debug upgrade --check-only)
• Verified rich console output and log file at ~/.specfact/logs/specfact-debug.log
• Tested with different input scenarios (success, up-to-date, none found)
• Checked error messages for clarity

Automated Testing

• Contract validation passes
• Property-based tests cover edge cases
• Scenario tests cover user workflows
• All existing tests still pass

Test Environment

• Python version: 3.12
• OS: Linux (Ubuntu)

Checklist

• My code follows the style guidelines (PEP 8, ruff format, isort)
• I have performed a self-review of my code
• I have added/updated contracts (@icontract, @beartype) — N/A for debug helpers
• I have added/updated docstrings (Google style)
• I have made corresponding changes to documentation
• My changes generate no new warnings (basedpyright, ruff, pylint)
• All tests pass locally
• I have added tests that prove my fix/feature works
• Any dependent changes have been merged

Quality Gates Status

• Type checking ✅ (hatch run type-check)
• Linting ✅ (hatch run lint)
• Contract validation ✅ (hatch run contract-test-contracts)
• Contract exploration ✅ (hatch run contract-test-exploration)
• Scenario tests ✅ (hatch run contract-test-scenarios)

Screenshots/Recordings (if applicable)

Log file sample after specfact --debug sdd list --repo . and specfact --debug upgrade --check-only:

2026-01-29 13:26:46 | debug_log_operation {"operation": "command", "target": "sdd list", "status": "started", ...}
2026-01-29 13:26:46 | specfact_cli.commands.sdd:sdd_list | sdd list: started
2026-01-29 13:26:46 | debug_log_operation {"operation": "command", "target": "sdd list", "status": "success", "extra": {"count": 0, "reason": "none_found"}}
2026-01-29 13:26:47 | debug_log_operation {"operation": "command", "target": "upgrade", "status": "success", "extra": {"reason": "up_to_date", "version": "0.26.12"}}
2026-01-29 13:26:47 | specfact_cli.commands.update:upgrade | upgrade: success (up to date)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[github-actions]

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 42.45s
Checks: 4 total (4 passed)

[github-actions]

SpecFact CLI Validation Report

✅ All validations passed!
Duration: 42.05s
Checks: 4 total (4 passed)