[P3.11] Dead/unused code and minor infra nits — batch cleanup

[frankbria]

Severity: low | Category: unfinished | Phase: P3.11

Problem

Documented-but-empty by_day; IssueGenerator exported but used by no product code (coverage measures dead code); claude-agent-sdk declared/installed but never imported; dead expression + unread isolate field; health-check timer fires at both 00:00 and 02:00; deploy.yml has no permissions: block and reseeds host keys via live ssh-keyscan; committed .py.backup/scratch/placeholder tests.

Evidence

codeframe/lib/metrics_tracker.py:664 (by_day no-op), codeframe/planning/issue_generator.py:110 (unused module), pyproject.toml:28 (claude-agent-sdk unused), codeframe/core/conductor.py:1537 (dead expr + unused isolate), systemd/codeframe-health-check.timer:7 (double OnCalendar), .github/workflows/deploy.yml:23 (no permissions block), .github/workflows/deploy.yml:57 (unverified ssh-keyscan), tracked tests/*.py.backup + tests/debug/ + tests/test_new_feature.py

Acceptance criteria

Remove or wire each dead item; add permissions: {contents: read} to deploy.yml; pin SSH_KNOWN_HOSTS; drop OnCalendar=daily; delete .backup/scratch/placeholder tests and add *.backup/*.log/coverage.json to .gitignore.

Dependencies

None

---

_{Filed from the SaaS launch-readiness audit. Atomic: one developer, one session. Work order: strictly P0.1 → P3.12 (no forward dependencies).}

[coderabbitai]

Coding Plan

Summary

• Resolve each confirmed dead item by removal (rather than wiring), including the by_day field, the orphaned IssueGenerator module and its test, the dead conductor expressions and unread isolate field, and the unused claude-agent-sdk dependency.
• Clean up repository hygiene by deleting tracked backup/scratch/placeholder test artifacts and adding generic *.backup/*.log/coverage.json ignore rules.
• Harden infrastructure by consolidating the systemd timer to a single 2 AM schedule and securing deploy.yml with a least-privilege permissions: contents: read block plus a pinned SSH_KNOWN_HOSTS secret replacing live ssh-keyscan.

Design Choices

Design Choice 1: Should each dead item be removed or wired into product code?

Options Considered:

1. Remove the dead items entirely (and their orphaned tests/exports).
2. Wire them into product flows (implement by_day aggregation, hook IssueGenerator into the CLI, branch on isolate).

Chosen Option: 1

Rationale: The ticket allows "remove or wire". None of by_day, IssueGenerator, or the boolean isolate field is consumed by any product code path; only test files and package re-exports reference them. Removal is the lowest-risk, in-scope resolution for a low-severity cleanup ticket; wiring would introduce net-new features and behavior beyond the audit's intent.

Design Choice 2: How should the SSH host key be pinned in `deploy.yml`?

Options Considered:

1. Introduce a new SSH_KNOWN_HOSTS secret containing pre-captured host key material, written directly to ~/.ssh/known_hosts.
2. Keep ssh-keyscan but compare its output against a pinned fingerprint before appending.

Chosen Option: 1

Rationale: No host-key pinning convention or secret currently exists in the repo (active or legacy docs). The ticket explicitly says "pin SSH_KNOWN_HOSTS"; writing a trusted, pre-vetted secret to known_hosts eliminates the live TOFU fetch entirely and matches the requested secret name.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Remove Dead Python Code and Unused Dependency

Eliminate the confirmed dead code paths in the application source and prune the unused package dependency. These changes are grouped because they all touch application Python source and its dependency manifest, and each has zero product-code consumers.

Task 1: Remove the no-op `by_day` field from metrics tracking

Drop the always-empty by_day output and its unfinished-feature scaffolding.

• In codeframe/lib/metrics_tracker.py, within MetricsTracker.get_token_usage_stats(), remove the "by_day": [] key from the returned result dict.
• Remove the by_day description from that method's docstring so documented output matches actual output.
• Delete the trailing TODO: Implement by_day aggregation comment block, since the field is being removed rather than deferred.

Task 2: Remove the orphaned `IssueGenerator` planning module

Delete the PRD→Issue generation module that no product code imports.

• Delete codeframe/planning/issue_generator.py (the IssueGenerator class plus the internal-only parse_prd_features and assign_priority helpers).
• Update codeframe/planning/__init__.py to remove the issue_generator imports and drop IssueGenerator, parse_prd_features, and assign_priority from __all__, leaving the still-used prd_templates exports intact.
• Delete the corresponding orphaned test module tests/planning/test_issue_generator.py, since it exercises only the removed code and would otherwise fail the suite.

Task 3: Remove the dead expressions and unread `isolate` field from the conductor

Clean up the batch-execution paths that superseded isolate with isolation.

• In codeframe/core/conductor.py, remove the standalone completed_count + failed_count + blocked_count statement in both _execute_serial (near line 1537) and _execute_parallel (near line 1725); the surrounding BatchStatus determination logic re-checks the individual counters and is unaffected.
• Remove the isolate: bool = True field from the BatchRun dataclass, the isolate parameter from start_batch(), and its assignment in the BatchRun construction, retaining the active isolation: str field that actually drives execution isolation.
• Update tests/core/test_worktrees.py to remove the TestBatchRunIsolate / TestStartBatchIsolate assertions (and any isolate= arguments), since they test the removed field.

Task 4: Remove the unused `claude-agent-sdk` dependency

Prune the installed-but-never-imported package from the manifest.

• Remove the "claude-agent-sdk>=0.1.10" entry from the dependencies list in pyproject.toml.
• Regenerate uv.lock (e.g., via uv lock) so the lockfile no longer resolves claude-agent-sdk; the working Anthropic integration in codeframe/adapters/llm/anthropic.py continues to rely on the retained anthropic package.

🤖 Prompt for AI agents

Implement Phase 1: remove confirmed dead code from the Python application source
and prune an unused dependency, since none of these items have any product-code
consumers.

1. In `codeframe/lib/metrics_tracker.py`, in
`MetricsTracker.get_token_usage_stats()`: remove the `"by_day": []` key from the
returned `result` dict, remove the `by_day` description from the method
docstring, and delete the trailing `TODO: Implement by_day aggregation` comment
block.

2. Delete the orphaned planning module `codeframe/planning/issue_generator.py`
(containing `IssueGenerator`, `parse_prd_features`, `assign_priority`). Update
`codeframe/planning/__init__.py` to remove the `issue_generator` imports and
drop `IssueGenerator`, `parse_prd_features`, and `assign_priority` from
`__all__`, while leaving the still-used `prd_templates` exports intact. Delete
the orphaned test file `tests/planning/test_issue_generator.py`.

3. In `codeframe/core/conductor.py`: remove the standalone dead expression
statement `completed_count + failed_count + blocked_count` in both
`_execute_serial` (near line 1537) and `_execute_parallel` (near line 1725) —
leave the surrounding `BatchStatus` determination logic untouched since it
re-checks the individual counters. Remove the `isolate: bool = True` field from
the `BatchRun` dataclass, remove the `isolate` parameter from `start_batch()`,
and remove its assignment in the `BatchRun` construction, while retaining the
active `isolation: str` field. Update `tests/core/test_worktrees.py` to remove
the `TestBatchRunIsolate` / `TestStartBatchIsolate` test assertions and any
`isolate=` arguments used in tests.

4. In `pyproject.toml`, remove the `"claude-agent-sdk>=0.1.10"` entry from
`dependencies`. Regenerate `uv.lock` (e.g. via `uv lock`) so the lockfile no
longer resolves `claude-agent-sdk`. Do not modify the retained `anthropic`
package usage in `codeframe/adapters/llm/anthropic.py`.

Phase 2: Repository Hygiene — Scratch Artifacts and Ignore Rules

Remove tracked backup/scratch/placeholder test artifacts and add ignore rules to prevent recurrence. Grouped as pure repository cleanup with no source-behavior impact.

Task 1: Delete tracked backup and scratch/placeholder test files

Remove stale artifacts that pollute the tree and coverage.

• Delete the tracked backup files tests/test_backend_worker_agent.py.backup and tests/test_test_worker_agent.py.backup.
• Delete the scratch/reference test files under tests/debug/ (test_simple_sanity.py and test_template.py), which are a throwaway sanity check and an AI-agent reference template rather than genuine application tests.
• Remove the root-level scratch artifacts referenced by the audit if present (coverage.json, loose *.log outputs such as test_output.log).

Task 2: Extend `.gitignore` to prevent future scratch commits

Add the generic ignore patterns called out in the acceptance criteria.

• Update .gitignore to add generic *.backup, *.log, and coverage.json rules.
• Remove the now-dead tests/test_new_feature.py ignore entry (the file no longer exists on disk or in git), since the placeholder it referenced is gone.

🤖 Prompt for AI agents

Implement Phase 2: perform pure repository hygiene cleanup with no
source-behavior impact, by deleting tracked backup/scratch/placeholder test
artifacts and updating `.gitignore`.

1. Delete the tracked backup files `tests/test_backend_worker_agent.py.backup`
and `tests/test_test_worker_agent.py.backup`.

2. Delete the scratch/reference test files under `tests/debug/`:
`test_simple_sanity.py` (throwaway sanity check) and `test_template.py`
(AI-agent reference template), since neither is a genuine application test.

3. Remove root-level scratch artifacts if present: `coverage.json` and loose
`*.log` outputs such as `test_output.log`.

4. Update `.gitignore` to add generic `*.backup`, `*.log`, and `coverage.json`
rules. Remove the now-dead `tests/test_new_feature.py` ignore entry since that
file no longer exists on disk or in git.

Phase 3: Infrastructure and CI/CD Hardening

Correct the systemd timer schedule and harden the deployment workflow. Grouped as deployment/infra configuration changes.

Task 1: Fix the health-check timer double schedule

Make the timer fire once at 2 AM as intended.

• In systemd/codeframe-health-check.timer, remove the additive OnCalendar=daily (midnight) directive so only the intended 02:00 schedule remains; consolidate into a single explicit OnCalendar=*-*-* 02:00:00 and keep OnBootSec / Persistent=true unchanged.

Task 2: Add a least-privilege permissions block to the deploy workflow

Scope GITHUB_TOKEN down for the deployment workflow.

• Add a top-level permissions: block with contents: read to .github/workflows/deploy.yml, following the release.yml convention; the deploy jobs only check out code and SSH outward, so no write scopes are required.

Task 3: Pin SSH host keys instead of live `ssh-keyscan`

Eliminate unverified trust-on-first-connect in both deploy jobs.

• In .github/workflows/deploy.yml, replace the "Add server to known hosts" step in both deploy-staging and deploy-production so that it writes a pre-vetted ${{ secrets.SSH_KNOWN_HOSTS }} value into ~/.ssh/known_hosts rather than running ssh-keyscan -H ${{ secrets.HOST }} at CI time.
• Document the new SSH_KNOWN_HOSTS secret expectation (populated with the captured host key/fingerprint output) alongside the existing deploy secrets so operators know to configure it.

🤖 Prompt for AI agents

Implement Phase 3: correct the systemd timer schedule and harden the deployment
CI/CD workflow.

1. In `systemd/codeframe-health-check.timer`, remove the additive
`OnCalendar=daily` (midnight) directive so only the intended `02:00` schedule
remains. Consolidate into a single explicit `OnCalendar=*-*-* 02:00:00`
directive, keeping `OnBootSec` and `Persistent=true` unchanged.

2. In `.github/workflows/deploy.yml`, add a top-level `permissions:` block with
`contents: read`, following the existing convention used in `release.yml`, since
the deploy jobs only check out code and SSH outward and require no write scopes.

3. In `.github/workflows/deploy.yml`, replace the "Add server to known hosts"
step in both the `deploy-staging` and `deploy-production` jobs: instead of
running `ssh-keyscan -H ${{ secrets.HOST }}` at CI time, write a pre-vetted `${{
secrets.SSH_KNOWN_HOSTS }}` secret value directly into `~/.ssh/known_hosts`.
Document the new `SSH_KNOWN_HOSTS` secret expectation (populated with the
captured host key/fingerprint output) alongside the existing deploy secrets so
operators know to configure it.

Research

CodeFRAME is a Python orchestration application (codeframe/) with clear layering: core/ (orchestration incl. conductor.py), lib/ (utilities incl. metrics_tracker.py), planning/ (PRD/issue tooling), and adapters/llm/ (the real Anthropic/OpenAI integration via the anthropic package). Dependencies are declared in pyproject.toml/uv.lock. CI/CD lives in .github/workflows/ (with release.yml/test.yml establishing the least-privilege permissions: convention), deployment host config in systemd/, and tests under tests/. All items in this ticket were independently confirmed as dead or misconfigured and have no product-code consumers.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: remove confirmed dead code from the Python application source
and prune an unused dependency, since none of these items have any product-code
consumers.

1. In `codeframe/lib/metrics_tracker.py`, in
`MetricsTracker.get_token_usage_stats()`: remove the `"by_day": []` key from the
returned `result` dict, remove the `by_day` description from the method
docstring, and delete the trailing `TODO: Implement by_day aggregation` comment
block.

2. Delete the orphaned planning module `codeframe/planning/issue_generator.py`
(containing `IssueGenerator`, `parse_prd_features`, `assign_priority`). Update
`codeframe/planning/__init__.py` to remove the `issue_generator` imports and
drop `IssueGenerator`, `parse_prd_features`, and `assign_priority` from
`__all__`, while leaving the still-used `prd_templates` exports intact. Delete
the orphaned test file `tests/planning/test_issue_generator.py`.

3. In `codeframe/core/conductor.py`: remove the standalone dead expression
statement `completed_count + failed_count + blocked_count` in both
`_execute_serial` (near line 1537) and `_execute_parallel` (near line 1725) —
leave the surrounding `BatchStatus` determination logic untouched since it
re-checks the individual counters. Remove the `isolate: bool = True` field from
the `BatchRun` dataclass, remove the `isolate` parameter from `start_batch()`,
and remove its assignment in the `BatchRun` construction, while retaining the
active `isolation: str` field. Update `tests/core/test_worktrees.py` to remove
the `TestBatchRunIsolate` / `TestStartBatchIsolate` test assertions and any
`isolate=` arguments used in tests.

4. In `pyproject.toml`, remove the `"claude-agent-sdk>=0.1.10"` entry from
`dependencies`. Regenerate `uv.lock` (e.g. via `uv lock`) so the lockfile no
longer resolves `claude-agent-sdk`. Do not modify the retained `anthropic`
package usage in `codeframe/adapters/llm/anthropic.py`.
===============================================================================

Task: 2

Implement Phase 2: perform pure repository hygiene cleanup with no
source-behavior impact, by deleting tracked backup/scratch/placeholder test
artifacts and updating `.gitignore`.

1. Delete the tracked backup files `tests/test_backend_worker_agent.py.backup`
and `tests/test_test_worker_agent.py.backup`.

2. Delete the scratch/reference test files under `tests/debug/`:
`test_simple_sanity.py` (throwaway sanity check) and `test_template.py`
(AI-agent reference template), since neither is a genuine application test.

3. Remove root-level scratch artifacts if present: `coverage.json` and loose
`*.log` outputs such as `test_output.log`.

4. Update `.gitignore` to add generic `*.backup`, `*.log`, and `coverage.json`
rules. Remove the now-dead `tests/test_new_feature.py` ignore entry since that
file no longer exists on disk or in git.
===============================================================================

Task: 3

Implement Phase 3: correct the systemd timer schedule and harden the deployment
CI/CD workflow.

1. In `systemd/codeframe-health-check.timer`, remove the additive
`OnCalendar=daily` (midnight) directive so only the intended `02:00` schedule
remains. Consolidate into a single explicit `OnCalendar=*-*-* 02:00:00`
directive, keeping `OnBootSec` and `Persistent=true` unchanged.

2. In `.github/workflows/deploy.yml`, add a top-level `permissions:` block with
`contents: read`, following the existing convention used in `release.yml`, since
the deploy jobs only check out code and SSH outward and require no write scopes.

3. In `.github/workflows/deploy.yml`, replace the "Add server to known hosts"
step in both the `deploy-staging` and `deploy-production` jobs: instead of
running `ssh-keyscan -H ${{ secrets.HOST }}` at CI time, write a pre-vetted `${{
secrets.SSH_KNOWN_HOSTS }}` secret value directly into `~/.ssh/known_hosts`.
Document the new `SSH_KNOWN_HOSTS` secret expectation (populated with the
captured host key/fingerprint output) alongside the existing deploy secrets so
operators know to configure it.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#246 - feat(agents): trigger multi-agent execution after task approval [merged]
#537 - feat(core): WorktreeRegistry, orphan cleanup, and get_base_branch (#533) [merged]
#612 - chore: remove vestigial v1 context-tier code (ContextTier, importance_scorer) and dead tests (#611) [merged]
#685 - ci(e2e): formally defer Playwright browser E2E + fix legacy comments (#647) [closed]
#697 - fix(ci): run full non-e2e suite, drop -m v2 blind spot (#669) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!