[Iteration] 2026-08 Stabilization — restore trusted main and adopt virtual dev team workflow

[fxbin]

Context

TopicEye has grown into a multi-layer product with FastAPI APIs, scheduler/background jobs, persistence, DuckDB fallback, LLM analysis and a frontend. The repository already documents strong engineering constraints in AGENTS.md, but the delivery loop is not consistently reflected in GitHub history.

This iteration applies fxbin/skill-hub/virtual-intelligent-dev-team as the delivery contract: Understand → Plan → Implement → Test → Verify → Integrate → Evolve, with meaningful changes going through Issue → branch → PR → independent Verifier → merge.

Evidence collected on 2026-08-15

• Current main SHA: 597fb2931ff9c69ccc12e077e4df320066982e6c.
• GitHub Actions run 31603354158 for that main commit is red.
• Current lint gate fails Ruff formatting on backend/tests/test_today_picks.py.
• Security gate reports 69 known-vulnerability findings across 7 resolved packages; observed affected packages include authlib, cryptography, pypdf, python-multipart, and starlette.
• Backend test job was cancelled after fail-fast; there is no valid evidence yet that the functional backend suite itself failed.
• Recent changes landed directly on main; repository history has little/no PR-driven iteration evidence.
• GitHub App cannot read branch-protection configuration (403), so this issue deliberately does not assume whether protection rules exist.

Iteration goals

1. Restore a green, trustworthy main baseline.
2. Remove or explicitly disposition dependency-security failures with compatibility tests.
3. Establish a reproducible bug inventory and regression matrix for critical product flows.
4. Harden scheduler/background-job/startup/shutdown reliability.
5. Make the virtual-dev-team GitHub workflow the default delivery path.
6. Produce planning truth in-repo and keep implementation auditable.

WorkOrder / role map

• Conductor / PM: maintain scope, priority and issue dependency graph.
• BA / Architect: turn bug reports into reproducible contracts and identify cross-layer impact.
• Worker (BE/FE): one issue per bounded change; no opportunistic refactors.
• QA / TDD Guide: failing regression first when practical; define smoke and integration matrix.
• Integration Verifier: independently review evidence and issue a DeliveryCycleReport.
• Git Workflow Guardian: enforce Issue → branch → PR → checks → verification → merge.

Definition of Done

• Main CI is green on a fresh run.
• Dependency audit has no unowned high-confidence failures; upgrades are covered by regression tests.
• Critical flows have a documented reproducibility/acceptance matrix.
• Each implementation item is linked to an issue and PR.
• Every implementation PR contains test evidence and a verifier verdict.
• Stabilization planning artifacts are committed under planning/2026-08-stabilization/.
• Final iteration DeliveryCycleReport records shipped, deferred, residual risks and next cycle.

Non-goals

• Large redesign unrelated to a reproduced defect.
• Feature expansion before baseline health is restored.
• Direct fixes on main.

Release strategy

Stabilize in thin vertical slices: CI baseline → security → regression/reproduction → runtime reliability → product bugs. Merge only when the slice has independent verification evidence.

[fxbin]

Stabilization execution graph is now materialized:

• [P0] Restore green main: fix current Ruff formatting gate and verify CI baseline #3 P0 — restore green main / current Ruff gate
• [P0] Remediate backend dependency vulnerabilities with compatibility coverage #4 P0 — dependency-security remediation
• [P1] Build a reproducible bug inventory and critical regression matrix #5 P1 — bug reproduction + critical regression matrix
• [P1] Harden scheduler, background jobs and lifecycle reliability #6 P1 — scheduler/background-job/lifecycle reliability
• [P1] Enforce Issue → branch → PR → Verifier delivery workflow #7 P1 — GitHub Issue → branch → PR → Verifier workflow
• Draft planning PR: plan: 2026-08 stabilization and virtual dev team workflow (#2) #8 (issue-2-2026-08-stabilization)

Execution order remains: #3 → #4, while #5/#7 may proceed in parallel; #6 consumes findings from #5. PR #8 is planning-only and awaits independent verification.