Upstream contribution roadmap: PR waves independent of enhanced YouTube API access

[djbclark]

Goal

Upstream generally useful SuperBrain changes—including changes that support YouTube-related workflows—as small, independently reviewable pull requests while holding back features that depend on YouTube approving enhanced YouTube Data API access or increased quota.

This replaces the earlier broad upstream PR approach with fresh branches based on sidinsearch/superbrain:main. Each PR should contain one behavior, focused tests, and no unrelated fork/operator configuration.

Wave 1 — independent correctness fixes

• Separate the live backend API probe from unit-test discovery.
• Make mobile delta sync consume every backend page before advancing its sync cursor.

These PRs are independent and may be reviewed in parallel. They support the reliability of YouTube-oriented SuperBrain workflows but do not call or require enhanced access to the YouTube Data API.

Wave 2 — persistence and worker safety

• Extract generic SQLite concurrency hardening: per-thread connections, WAL/busy-timeout behavior, atomic work claiming, stale-work recovery, and focused generic tests.

Submit this after the delta-sync PR to avoid overlapping database changes. Keep it focused on generic database and worker safety; exclude OAuth, subscription discovery, playlist synchronization, quota handling, and other approval-dependent API functionality.

Wave 3 — configurable taxonomy

Because this is a major feature, first open an upstream design issue and obtain maintainer direction. Then submit sequentially:

• Configurable taxonomy core, validation, classifier integration, fallback behavior, and focused tests.
• Dynamic taxonomy endpoint and Android category UI, after the core merges.
• Metadata-only recategorization with dry-run/apply, filters, backups, and concise documentation, after the core merges.

These taxonomy changes can organize YouTube content, but they remain independent of enhanced YouTube Data API quota or approval.

Enhanced-API work explicitly held back

Upstream design discussion: sidinsearch/superbrain#6 — opt-in YouTube subscription organization and private category playlist sync.

Do not include any of the following in upstream PRs until the enhanced YouTube API-access proposal has been discussed with upstream and the required Google/YouTube approvals are ready:

• YouTube OAuth secrets, consent/connection flows, or subscription discovery.
• Category-to-YouTube-playlist creation, bulk backfill, quota waiting, or automatic activation.
• YouTube API privacy/terms/compliance pages and screenshots.

Also deferred to keep contribution scope focused

• WebSub/reconciliation, Watch Later or browser-cookie playlist import, and transcript downloading may be reconsidered later only as cleanly decoupled contributions with their own policy and scope review.
• Fork-specific omlx/reference-database behavior and opinionated provider/model defaults remain out of scope for upstream PRs.

The production/multi-user YouTube work remains tracked separately in #1 and #2. It is not a dependency for contributions that are technically and operationally independent of enhanced YouTube API approval.

Submission rules

• Start each branch from the then-current upstream main; do not reuse the mixed historical branch.
• Keep no more than two independent PRs open at once.
• Include focused automated tests and the exact verification commands/results in every PR.
• Scan each diff for OAuth, quota, credentials, compliance, or other approval-dependent API functionality before pushing.
• Mark a PR ready for review only after its focused checks pass, its final diff has been reviewed for scope, and it no longer carries known follow-up edits.

[djbclark]

Wave 1 deployed

• Upstream PR #4 — move the live API probe out of unit discovery
• Upstream PR #5 — paginate mobile delta sync

Both are one-commit PRs based directly on current upstream main, report a clean merge state, and exclude functionality that depends on enhanced YouTube Data API access, increased quota, or related Google/YouTube approval. They were opened as drafts, then marked ready for review after focused backend checks, mobile type checking, final scope review, and a three-page /sync integration smoke test. The roadmap checkboxes should remain open until the PRs merge.

[djbclark]

Biome tooling queued

Prepared branch prep/biome-tooling at commit b5301e8 for the next available upstream PR slot. It is one commit and four files based directly on current upstream main.

It fixes the invalid indentStyle, pins Biome 1.9.4, aligns JavaScript formatter settings with the existing source style, adds reproducible lint/type-check scripts, and adds a pull-request workflow. Existing legacy rule violations remain visible as warnings; all other recommended-rule errors fail CI.

Verification: clean npm ci; npm run check passes across 28 source files.

No upstream PR has been opened because #4 and #5 are still active. A full formatter baseline is deliberately deferred: it would mechanically touch 26 source files and roughly 3,100 changed lines, so it should not be bundled with this small tooling gate.

[djbclark]

Automatic status monitoring enabled

The upstream activity workflow now runs hourly on GitHub Actions and sends direct Telegram notifications without requiring a Mac or Hermes process.

It watches upstream PRs #4 and #5 for new or edited external comments, reviews, requested changes, and state changes. When the queued prep/biome-tooling branch becomes an upstream PR, it is discovered and monitored automatically. Notifications include the current next action, and open PRs receive a follow-up nudge after three inactive days (repeated no more than every three days).

The initial manual verification run completed successfully and delivered the baseline status report.