Epic: codebase health improvements — 2026-07 review (15 issues, ordered)

[justin808]

Tracking issue for the 15 improvements from the 2026-07-02 automated codebase health review (tooling run: rubocop clean, offline unit suite 256/256, shellcheck, docs check; plus architecture/test/CI analysis — all findings verified against 7c96df9, one reproduced live). Composite health score at baseline: 8.4/10 (weakest dimensions: test strategy and error handling).

Each issue is scoped to one small, reviewable PR (or a short series). Solid arrows below are hard blockers; dashed are sequencing preferences.

All issues by priority

Issue	Pri	Size	Blocked by	Theme
#372 cpflow crashes on non-UTF-8 locales	P1 (bug)	S	—	correctness
#373 Unit specs can't run without CPLN_ORG	P1	S–M	—	test strategy
#374 Schedule the :slow suite	P1	S	—	CI coverage
#375 CI hygiene: action pinning + shellcheck	P2	S	—	CI
#376 Ruby support policy (gemspec vs CI matrix)	P2	S	— (coordinate w/ release)	policy
#378 SimpleCov minimum coverage floor	P2	S	#373 (soft)	test strategy
#379 Specs for nine untested lib/ files	P2	M	#373	test strategy
#380 Shell.abort → typed exceptions	P2	M	#373 (soft)	error handling
#381 Harden command construction (args_join TODO)	P2	M	#373 (soft)	correctness
#383 HTTP retry/backoff + remove @@api_token	P2	M	#380	reliability
#377 Trim post_install_message	P3	S	—	polish (good first issue)
#382 Flakiness hygiene (retries/ordering/timeouts)	P3	S–M	#373	test strategy
#384 Refactor Command::Base (700 lines)	P3	M	#380, #381	architecture
#385 Refactor Core::Controlplane + apply parsing	P3	L	#380, #383	architecture
#386 Dedupe maintenance_/ps_ families	P3	M	#384 (soft)	architecture

Dependency graph

graph TD
  I372["#372 UTF-8 crash (P1 bug)"]
  I374["#374 schedule :slow (P1)"]
  I375["#375 CI hygiene (P2)"]
  I376["#376 Ruby policy (P2)"]
  I377["#377 post_install (P3)"]
  I373["#373 offline unit specs (P1)"]
  I378["#378 coverage floor (P2)"]
  I379["#379 missing specs (P2)"]
  I380["#380 abort→exceptions (P2)"]
  I381["#381 args hardening (P2)"]
  I382["#382 flakiness (P3)"]
  I383["#383 HTTP retry (P2)"]
  I384["#384 Base refactor (P3)"]
  I385["#385 Controlplane refactor (P3)"]
  I386["#386 family dedupe (P3)"]
  I373 -.-> I378
  I373 --> I379
  I373 -.-> I380
  I373 -.-> I381
  I373 --> I382
  I380 --> I383
  I380 --> I384
  I381 --> I384
  I380 --> I385
  I383 --> I385
  I384 -.-> I386

Loading

Suggested execution order

1. Now, in parallel (all independent): cpflow crashes at startup on systems without a UTF-8 locale (File.read without encoding in Command::Base.all_commands) #372, Test suite cannot load without CPLN_ORG — even pure unit specs require live-org configuration #373, Schedule the :slow integration suite — domain-mutating specs currently run only on manual dispatch #374, CI hygiene: replace deprecated upload-artifact@master, standardize action pinning, add shellcheck gate #375, Ruby support policy: gemspec allows >= 3.0 (EOL) but CI tests only 3.2 #376, Trim the 17-line post_install_message in cpflow.gemspec #377
2. After Test suite cannot load without CPLN_ORG — even pure unit specs require live-org configuration #373: Enforce a SimpleCov minimum coverage floor in CI #378, Add specs for nine untested lib/ files (shell.rb, controlplane_api.rb, update_github_actions.rb, ...) #379, Replace Shell.abort/exit in library code with typed exceptions handled at the CLI boundary #380, Harden CLI command construction: resolve args_join quote-escaping TODO, prefer array-form subprocess args #381, Test flakiness hygiene: scope retries to live-API specs, enable random ordering, tier timeouts #382
3. After Replace Shell.abort/exit in library code with typed exceptions handled at the CLI boundary #380: Add HTTP retry/backoff to ControlplaneApiDirect and remove @@api_token class-level state #383
4. After Replace Shell.abort/exit in library code with typed exceptions handled at the CLI boundary #380 + Harden CLI command construction: resolve args_join quote-escaping TODO, prefer array-form subprocess args #381 (+Add HTTP retry/backoff to ControlplaneApiDirect and remove @@api_token class-level state #383): Refactor Command::Base (700 lines): extract option factories and step/retry runner #384, Refactor Core::Controlplane (575 lines): resource-scoped managers + structured apply-result parsing #385
5. Last: Deduplicate the maintenance_* and ps_* command families #386

Progress

• cpflow crashes at startup on systems without a UTF-8 locale (File.read without encoding in Command::Base.all_commands) #372
• Test suite cannot load without CPLN_ORG — even pure unit specs require live-org configuration #373
• Schedule the :slow integration suite — domain-mutating specs currently run only on manual dispatch #374
• CI hygiene: replace deprecated upload-artifact@master, standardize action pinning, add shellcheck gate #375
• Ruby support policy: gemspec allows >= 3.0 (EOL) but CI tests only 3.2 #376
• Trim the 17-line post_install_message in cpflow.gemspec #377
• Enforce a SimpleCov minimum coverage floor in CI #378
• Add specs for nine untested lib/ files (shell.rb, controlplane_api.rb, update_github_actions.rb, ...) #379
• Replace Shell.abort/exit in library code with typed exceptions handled at the CLI boundary #380
• Harden CLI command construction: resolve args_join quote-escaping TODO, prefer array-form subprocess args #381
• Test flakiness hygiene: scope retries to live-API specs, enable random ordering, tier timeouts #382
• Add HTTP retry/backoff to ControlplaneApiDirect and remove @@api_token class-level state #383
• Refactor Command::Base (700 lines): extract option factories and step/retry runner #384
• Refactor Core::Controlplane (575 lines): resource-scoped managers + structured apply-result parsing #385
• Deduplicate the maintenance_* and ps_* command families #386

Review notes

• One candidate finding was dropped as a false positive during verification: "SQLite generator scaffold missing Dockerfile/entrypoint.sh" — generate.rb always copies the common files (Dockerfile, entrypoint.sh) from the base template dir, so SQLite projects are complete.
• Verification loop used throughout: bundle exec rubocop (200 files, 0 offenses) and the offline unit subset (CPLN_ORG=dummy-org bundle exec rspec spec/core spec/patches spec/rakelib spec/support_specs spec/github_workflows_spec.rb spec/readme_heroku_command_mapping_spec.rb spec/command/*_unit_spec.rb → 256 examples, 0 failures). Test suite cannot load without CPLN_ORG — even pure unit specs require live-org configuration #373 makes that loop credential-free.