Daily Backlog BurnerResearch, Roadmap and Plan

[github-actions[bot]]

Backlog Research Summary — March 2, 2026

I've completed a fresh comprehensive analysis of the ctrld-sync repository backlog. Previous planning discussion #221 expired and was closed on Feb 21, 2026.

---

Project Overview

Control D Sync is a Python 3.13+ CLI utility (~3,200 lines in main.py) that synchronizes Control D DNS filtering folders with remote JSON block-lists. Key characteristics:

• Single-file architecture: All logic lives in main.py; refactoring toward modules is a recognized future goal
• Well-tested: 29 test files in tests/ plus test_main.py, covering security, performance, cache, config, SSRF, CSV injection, and more
• Security-focused: Bandit + Codacy scanning; sanitize_for_log(), SSRF guards, CSV injection prevention
• Heavily automated: 9+ GitHub Actions workflows (daily QA, perf improver, backlog burner, task miner, repo status, workflow updater, bandit, codacy, sync)
• Active CI: test.yml, sync.yml, performance.yml, bandit.yml, codacy.yml all running

---

Current Backlog — Full Inventory

Open Pull Requests (1)

PR	Title	Status	Action
#491	chore: remove stale performance.yml.orig backup file	Draft, from Daily QA	Review & merge — low risk, no functional change

Open Issues — Actionable (3)

Issue	Title	Priority	Notes
#490	Fix SECURITY.md placeholder version table	High → Stale	SECURITY.md is already correct (v0.1.x, proper reporting) — issue can be closed
#489	Add performance regression benchmark suite (pytest-benchmark)	Medium	pytest-benchmark already in pyproject.toml and tests/test_benchmarks.py exists — issue needs verification and close/update
#473	Extract config module from main.py	Medium	Mentioned in #489; main.py at 3,200 lines — modularization would improve maintainability

Open Issues — Automated Trackers (Do Not Close Manually)

Issue	Title	Notes
#206	[agentics] Failed runs	Auto-managed agentic failure tracker
#225	[agentics] No-Op Runs	Auto-managed agentic no-op tracker
#228	Daily Perf Improver — Research and Plan	Perf workflow tracker (open issue, not a PR)

Plus ~10 additional sub-issues from task-mining and perf-improver automation workflows.

---

Key Findings Since Previous Plan (#221)

Already Resolved (from previous plan's High Priority list):

1. ✅ SECURITY.md — already updated to v0.1.x with proper vulnerability reporting
2. ✅ pytest-benchmark — already added to pyproject.toml dev deps
3. ✅ test_benchmarks.py — benchmark test file already created in tests/
4. ✅ CLI formatting (PR 🎨 Palette: Improve CLI output formatting #217) — merged
5. ✅ README dependency docs — README now uses uv sync --all-extras consistently

Still Open / Actionable:

1. 🔴 main.py is 3,200 lines — single-file architecture creates maintainability risk; extracting modules (config, API client, validation, cache) would improve testability
2. 🟡 PR chore: remove stale performance.yml.orig backup file #491 — stale .orig file should be merged (cleanup, no risk)
3. 🟡 Issue [Code Quality] Fix SECURITY.md placeholder version table and reporting instructions #490 — stale issue; SECURITY.md is already fixed; should be closed with a note
4. 🟡 Issue [Code Quality] Add performance regression benchmark suite with pytest-benchmark #489 — benchmark suite task is largely done; should be closed or updated
5. 🟢 Error message quality — some API error paths could surface more actionable guidance
6. 🟢 CHANGELOG.md — missing; would help track version history

---

Prioritized Roadmap

🔴 High Priority — Code Quality & Maintainability

1. Begin modularizing main.py (Issue #473 area)

• Effort: Medium (2-4 hours per module)
• Impact: High — 3,200 lines is hard to navigate and test
• Strategy: Extract in stages: config.py → api_client.py → validation.py → cache.py
• Risk: Medium — imports and test mocks need updating
• First step: Extract load_config() / config-loading logic into config.py

🟡 Medium Priority — Cleanup & Documentation

2. Merge PR #491 (remove performance.yml.orig)

• Effort: 5 minutes
• Impact: Low — removes a confusing artifact
• Risk: None — no functional change

3. Close stale task-mined issues (#490, #489 with explanations)

• Effort: 10 minutes
• Impact: Reduces noise in the issue tracker

4. Add CHANGELOG.md

• Effort: 30 minutes
• Impact: Medium — documents what changed between versions
• Risk: None

🟢 Low Priority — Future Enhancements

5. Multi-profile parallel sync improvements

• Already supports comma-separated profiles; could add better progress reporting

6. Structured logging option

• Add JSON log output mode for observability pipelines

7. Dry-run diff output

• Show what rules would change in --dry-run mode

---

Patterns & Themes Identified

1. Automated workflows are doing their job well — task mining, perf analysis, QA are all generating actionable issues
2. Issues lag behind code — several open issues describe work already completed (SECURITY.md, benchmarks)
3. Main bottleneck is main.py size — future work should focus on modularization
4. Test coverage is strong — 29 dedicated test modules; adding tests for new features should be easy
5. No blocking bugs identified — the tool appears stable and well-maintained

---

How to Control this Workflow

Add comments to this discussion to provide feedback or adjust the plan. You can also use these commands:

# Disable the workflow
gh aw disable daily-backlog-burner --repo abhimehro/ctrld-sync

# Enable the workflow
gh aw enable daily-backlog-burner --repo abhimehro/ctrld-sync

# Run the workflow manually (optionally with repeats)
gh aw run daily-backlog-burner --repo abhimehro/ctrld-sync --repeat (number-of-repeats)

# View workflow logs
gh aw logs daily-backlog-burner --repo abhimehro/ctrld-sync

Providing Feedback:

• Comment here to reprioritize items, flag constraints, or add new issues to the list
• Comments will be reviewed before Phase 2 work begins

---

What Happens Next

Phase 2 begins on the next workflow run:

1. Goal Selection: Highest-priority actionable item from this plan (currently: begin config module extraction from main.py, or close stale issues and merge PR chore: remove stale performance.yml.orig backup file #491)
2. Implementation: Create a branch, make targeted changes
3. Testing: Ensure existing tests pass; add new tests where appropriate
4. Pull Request: Submit draft PR with full description
5. Results: Post progress comment back here

Repeat Mode: If running with --repeat, the workflow will continue working through items automatically.

Your Input: Feel free to comment with priority adjustments before Phase 2 proceeds.

AI generated by Daily Backlog Burner

• expires on Mar 9, 2026, 7:21 AM UTC

[abhimehro]

This is a solid backlog report. Clean structure, good prioritization, and the findings are well-documented! A few notes and suggestions from my end:

---

Feedback on the Plan

Priorities Look Right

The modularization of main.py (#473) being flagged as the top priority makes sense. 3,200 lines in a single file is the kind of thing that feels fine until you need to onboard someone new or debug something at 2 AM. Starting with config extraction is the right call since it's the most self-contained slice.

Quick Wins First

Before touching main.py, I'd knock out the 15-minute items to clear the noise:

1. Merge PR chore: remove stale performance.yml.orig backup file #491, no functional change, just cleanup
2. Close [Code Quality] Fix SECURITY.md placeholder version table and reporting instructions #490 with a note, SECURITY.md is already correct
3. Close or update [Code Quality] Add performance regression benchmark suite with pytest-benchmark #489, benchmark suite is largely in place

This tightens the backlog before the heavier lift begins, and it gives the tracker a cleaner signal-to-noise ratio.

A Few Additions to Consider

• CHANGELOG.md (item 🎨 Palette: Add sync summary table and fix syntax error #4) is worth doing sooner rather than later. Once modularization starts, we’ll want a record of structural changes. Even a lightweight Keep a Changelog format would work.
• On the modularization strategy, the staged approach (config -> api_client -> validation -> cache) is smart. One thing to watch: make sure each extraction PR is independently mergeable and doesn't create a "mega-refactor" branch that drifts from main. Small, reviewable PRs are the move here.
• Error message quality (the green item) could pair naturally with the API client extraction. When you pull out api_client.py, that's a good moment to audit error paths and surface better guidance.

On the Automated Trackers

The note about issues lagging behind code is a pattern worth watching. If the task-mining and QA workflows are generating issues for work that's already done, it might be worth adding a pre-check step that verifies whether the flagged file or feature already exists before opening an issue. That would cut down on the stale issue accumulation.

---

Suggested Phase 2 Sequence

1. Merge PR chore: remove stale performance.yml.orig backup file #491
2. Close [Code Quality] Fix SECURITY.md placeholder version table and reporting instructions #490 and [Code Quality] Add performance regression benchmark suite with pytest-benchmark #489 with explanations
3. Start CHANGELOG.md (capture current state as v0.1.x baseline)
4. Begin config.py extraction from main.py ([Code Quality] Extract config loading/validation from main.py into config.py module #473), small PR, tests updated, draft first

[github-actions[bot]]

Phase 2 update — CHANGELOG.md 📋

Worked on: replacing the auto-generated CHANGELOG.md with a proper [Keep a Changelog]((keepachangelog.com/redacted) format (closes #513), and added a CHANGELOG update step to CONTRIBUTING.md.

Draft PR created: docs/add-keep-a-changelog-format — 367 noisy auto-generated lines replaced with 81 clean, human-readable lines covering the [0.1.0] baseline (core features, security hardening, testing infra, CI) plus an [Unreleased] section ready for the modularisation PRs (#473) to populate.

Generated by Daily Backlog Burner

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-backlog-burner.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb

[github-actions[bot]]

Phase 2 update — cache.py sanitization alignment 🔒

Worked on: aligning cache.py's sanitization with the api_client.py injection pattern (closes #536). Replaced the local _sanitize_for_log() function with a _sanitize_fn injection hook (defaulting to repr), and wired main.sanitize_for_log into it at startup — consistent with the existing api_client._sanitize_fn injection. Added 5 new tests in TestCacheSanitizeFnInjection.

Draft PR created: fix/cache-sanitize-fn-injection-536 — 3 files changed (cache.py, main.py, tests/test_disk_cache.py), no functional behaviour changes.

Generated by Daily Backlog Burner

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-backlog-burner.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• pypi.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "pypi.org"

See Network Configuration for more information.

[github-actions[bot]]

Phase 2 update — _SERVER_ERROR_HINT for 5xx responses 🔔

Worked on: adding actionable operator guidance for 5xx HTTP server errors in api_client._retry_request() (closes #561). Added _SERVER_ERROR_HINT constant, exported it via __all__, updated the hint-selection ternary to cover status_code >= 500, and added 4 new tests in TestServerErrorHint — completing the hint coverage matrix (timeouts → _TIMEOUT_HINT, 4xx → _4XX_HINTS, 5xx → _SERVER_ERROR_HINT).

Draft PR: feat/server-error-hint-561

Generated by Daily Backlog Burner

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-backlog-burner.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• pypi.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "pypi.org"

See Network Configuration for more information.

[github-actions[bot]]

Phase 2 update — deduplicate 4xx hint messages 🔧

Worked on: eliminating hint message drift between main._STATUS_HINTS and api_client._4XX_HINTS for HTTP 401/403/404 (closes #584). Replaced the three hardcoded entries in _STATUS_HINTS with **api_client._4XX_HINTS — making api_client the single source of truth. Added test_4xx_hints_are_single_source_of_truth to enforce the invariant going forward.

Draft PR created: fix/deduplicate-status-hints-584 — 2 files changed (main.py +3/-3, tests/test_status_hints.py +9 lines), no functional behaviour changes.

Generated by Daily Backlog Burner

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-backlog-burner.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• pypi.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "pypi.org"

See Network Configuration for more information.

[github-actions[bot]]

Phase 2 update — _CONNECT_ERROR_HINT for network error handlers 🔌

Worked on: adding _CONNECT_ERROR_HINT to the four main.py error handlers that previously only hinted for TimeoutException (closes #593). The four functions check_api_access(), list_existing_folders(), verify_access_and_get_folders(), and delete_folder() now emit _CONNECT_ERROR_HINT on httpx.ConnectError, consistent with how _retry_request() already surfaces it. Added 9 new tests in TestConnectErrorHint covering positive and negative cases for all four functions.

Generated by Daily Backlog Burner

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/daily-backlog-burner.md@69b5e3ae5fa7f35fa555b0a22aee14c36ab57ebb

Warning

⚠️ Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• pypi.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "pypi.org"

See Network Configuration for more information.