Release 0.137.9: Breaking the Chains - A Clean Break from Legacy Patterns

(Updated: )
Release Notes
, , , ,

Introduction

Version 0.137.9 marks a significant milestone in the Screeps GPT project’s evolution. This release represents a deliberate step toward cleaner, more maintainable code by removing deprecated features and backward compatibility layers that had accumulated over previous versions. While this is a breaking release, it streamlines the codebase and eliminates technical debt, positioning the project for more robust future development.

Breaking Changes

This release introduces three breaking changes, all focused on removing deprecated code that had been marked for removal in previous releases:

1. Deprecated GitHub Label System Removed

What Changed: The legacy label system (bug, enhancement, severity/*) has been completely removed from .github/labels.yml.

Why This Decision: The repository transitioned to a standardized three-tier labeling system (state/type/priority) in version 0.7.1 to improve issue management and automation workflows. The old labels were maintained for backward compatibility, but as a single-user repository with no external contributors, maintaining dual label systems created unnecessary complexity without providing value.

Migration Path: Use the new standardized labels instead:

  • bug → type/bug
  • enhancement → type/enhancement
  • severity/* → priority/* (critical, high, medium, low, none)

Impact: Any automation workflows, issue templates, or scripts referencing the old labels will need to be updated. The standardized system provides clearer semantic meaning and better integrates with GitHub Copilot automation workflows.

2. Logger Backward Compatibility Wrapper Removed

What Changed: Removed the Logger backward compatibility wrapper at packages/bot/src/runtime/utils/Logger.ts.

Why This Decision: The Logger functionality was extracted into a dedicated package (@ralphschuler/screeps-logger) as part of the monorepo restructuring in version 0.47.1. The wrapper was initially maintained to provide a seamless transition, but keeping it added an unnecessary layer of indirection that complicated the codebase and made it harder to track actual Logger usage.

Migration Path: Import Logger directly from the package:

1
2
3
4
5
// Old (removed):
import { Logger } from './runtime/utils/Logger';

// New (required):
import { Logger } from '@ralphschuler/screeps-logger';

Impact: All internal imports have been updated. External consumers of the bot runtime (if any) will need to update their import paths. This change aligns with the project’s move toward package-based architecture where shared utilities live in dedicated packages rather than the bot runtime.

3. Deprecated getTaskQueue() Function Removed

What Changed: Removed the deprecated getTaskQueue() function from BehaviorController.

Why This Decision: This function was identified as unused during code audits and was marked for removal in previous releases. Keeping unused functions increases maintenance burden and can create confusion about the intended API surface. The task system has evolved to use different access patterns through TaskManager, making this function obsolete.

Migration Path: No migration needed—the function was unused throughout the codebase. If external code was relying on this function, use TaskManager APIs instead.

Impact: None expected since the function had no active usage. This removal reduces the API surface area of BehaviorController and makes the code easier to understand.

Documentation Updates

To support these breaking changes, comprehensive documentation updates were included:

Legacy References Removed

Files Updated:

  • docs/automation/label-system.md - Removed backward compatibility migration sections
  • AGENTS.md - Removed references to deprecated labels in agent guidelines
  • .github/copilot-instructions.md - Removed backward compatibility notes

Rationale: Clean documentation is crucial for both human developers and AI agents. By removing references to deprecated features, we ensure that GitHub Copilot agents and human contributors always work with current patterns rather than potentially implementing obsolete approaches. This is especially important in an autonomous development environment where agents rely heavily on documentation to make decisions.

Technical Context: The documentation cleanup follows the project’s documentation-first philosophy. Each removed reference was carefully evaluated to ensure no active functionality was documented. Cross-references to the new standardized systems were verified to provide complete migration guidance.

Design Rationale

The Cost of Backward Compatibility

Backward compatibility is valuable in libraries with many consumers, but it comes with significant costs:

  1. Increased Cognitive Load: Developers and AI agents must understand both old and new patterns
  2. Testing Complexity: Tests must cover both deprecated and current implementations
  3. Maintenance Burden: Bug fixes and updates must be applied to multiple code paths
  4. Delayed Innovation: New features must work with legacy constraints

Single-User Repository Context

As a single-user research repository focused on autonomous bot development, Screeps GPT has different constraints than typical open-source projects:

  • No External Breaking Changes: There are no external consumers to disrupt
  • Rapid Iteration: The project benefits from quick pivots and clean architecture
  • AI Agent Collaboration: Simpler codebases reduce agent confusion and errors
  • Living Documentation: The repository serves as a learning platform where clean examples matter

This context informed the decision to remove deprecated code aggressively rather than maintaining compatibility layers indefinitely.

Deprecation Strategy

This release builds on the comprehensive deprecation strategy established in version 0.51.3, which introduced:

  • Formal deprecation policy at docs/development/deprecation-policy.md
  • Deprecation registry tracking all active deprecations
  • ESLint rules warning about deprecated API usage
  • CI workflow for automated deprecation checks

The 2-3 release cycle deprecation timeline proved sufficient for identifying unused code and validating that no active consumers existed before removal.

Technical Details

Repository Structure Impact

These changes touched several key areas of the repository:

Label System (/.github/labels.yml):

  • Removed 3 deprecated labels and their color/description definitions
  • Maintained 35+ standardized labels across state/type/priority/workflow/domain categories
  • Label sync workflow continues to operate unchanged

Bot Runtime (packages/bot/src/):

  • Removed runtime/utils/Logger.ts file entirely
  • Updated import statements in dependent files to use @ralphschuler/screeps-logger
  • No functional changes to Logger behavior—only import path updates

Behavior System (packages/bot/src/runtime/behavior/):

  • Removed getTaskQueue() method from BehaviorController class
  • Reduced API surface area without impacting functionality
  • Task system continues to function through TaskManager interfaces

Build System Validation

All changes were validated through the existing quality gate system:

  • 783 unit tests passing - No functional regressions introduced
  • Lint checks passing - Code style maintained throughout changes
  • Build succeeds - No TypeScript compilation errors
  • Format checks passing - Documentation formatting validated

The comprehensive test suite provided confidence that removals did not break active functionality.

Impact on Development Workflow

For Human Developers

  • Clearer Codebase: Reduced confusion by eliminating deprecated patterns
  • Simpler Onboarding: New contributors see only current best practices
  • Faster Development: Less code to maintain and test

For AI Agents

The cleanup particularly benefits GitHub Copilot agents working autonomously:

  • Reduced Ambiguity: Agents no longer encounter conflicting patterns
  • Better Suggestions: Training data aligns with current implementation
  • Fewer Errors: Simpler code paths reduce agent mistakes

For the Bot Runtime

  • Smaller Bundle Size: Removed code doesn’t get deployed to Screeps
  • Improved Performance: Fewer code paths to execute at runtime
  • Better Type Safety: TypeScript has fewer surfaces to validate

What’s Next

With technical debt cleaned up, the project can focus on:

Immediate Priorities

  • Enhanced Task System: Building on the cleaner BehaviorController API
  • Performance Optimization: Profiler integration for identifying bottlenecks
  • Multi-Room Coordination: Scaling beyond single-room operation

Future Breaking Changes

The deprecation registry currently tracks:

  • Role-Based Behavior System: Scheduled for removal as task-based system matures
  • Legacy Memory Structures: Candidates for schema migration as usage decreases

These will follow the same 2-3 release deprecation timeline established in this release.

Conclusion

Version 0.137.9 demonstrates that breaking changes, when well-justified and properly executed, can significantly improve codebase health. By removing deprecated features that provided no active value, this release streamlines the development experience for both human and AI contributors while maintaining all essential functionality.

The comprehensive documentation updates ensure that the rationale behind these changes is preserved for future reference, embodying the project’s documentation-first philosophy. This release proves that a single-user research repository can benefit from aggressive deprecation practices that might be impractical in larger open-source projects.

As Screeps GPT continues to evolve as an autonomous AI development platform, maintaining a clean, well-documented codebase becomes increasingly important. This release takes a significant step in that direction.

Full Changelog: View the complete changelog at CHANGELOG.md

Upgrade Guide: For detailed migration instructions, see the Deprecation Registry