feat: add backlog-core module — dependency analysis and command suites

[djm81]

Description

Implements OpenSpec change backlog-core-01-dependency-analysis-commands (and aligned ceremony command topology updates) to deliver provider-agnostic backlog dependency analysis and project integration workflows.

Scope delivered:

• Added backlog-core module package with provider-agnostic graph models, builders, analyzers, and command surfaces.
• Added backlog command suites under common backlog topology:
  • backlog analyze-deps
  • backlog trace-impact
  • backlog sync
  • backlog verify-readiness
  • backlog diff
  • backlog promote
  • backlog generate-release-notes
  • backlog delta status|impact|cost-estimate|rollback-analysis
• Added project backlog integration commands:
  • project link-backlog
  • project health-check
  • project devops-flow
  • project snapshot
  • project regenerate (--strict, --verbose behavior)
  • project export-roadmap
• Updated docs for command discoverability and ceremony-first entrypoints.
• Version bumped to 0.31.0 and changelog aligned.

Fixes #116

New Features #116

Contract References:

• Runtime contracts and type guards in backlog-core command/analyzer entrypoints (@icontract + @beartype).
• Project backlog integration helpers updated with contract-compliant invocation path (module-boundary-safe dispatch for enforce sdd).

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

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: Contracts enforce API/type invariants in module command/analyzer APIs; integration and unit tests cover dependency graph build/analyze flows, delta commands, project command integrations, and ceremony command grouping behavior.

Manual Testing

• Tested CLI commands manually
• Verified rich console output
• Tested with different input scenarios
• 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

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)
• 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)

CLI validation excerpts observed during implementation:

• hatch run specfact backlog -h shows grouped ceremony/delta/backlog commands.
• hatch run specfact project health-check shows backlog graph health table + cross checks.
• Full test run result shared by authoring workflow: 2639 passed, 1 skipped after boundary fix.