diff --git a/conductor/archive/codebase_curation_20260507/CURATION_PROTOCOL.md b/conductor/archive/codebase_curation_20260507/CURATION_PROTOCOL.md new file mode 100644 index 0000000..1955951 --- /dev/null +++ b/conductor/archive/codebase_curation_20260507/CURATION_PROTOCOL.md @@ -0,0 +1,26 @@ +# Granular Review Protocol: Codebase Curation + +This protocol defines the mandatory procedure for auditing and modifying files during the Phase 5 Heavy Curation. It is designed to minimize entropy and prevent regression propagation. + +## 1. File-by-File Audit Cycle + +For every `.py` file identified for curation: + +1. **Dependency Check:** Use `derive_code_path` and `py_get_imports` to identify all upstream and downstream dependencies. +2. **State Verification:** Consult the `MUTATION_MATRIX_PHASE5.md` to identify any global state modifications performed by the file. +3. **Redundancy Identification:** Cross-reference the file against `CULLING_CANDIDATES_PHASE5.md`. +4. **Proposed Change Log:** Before editing, document the specific lines/symbols to be removed or refactored and the technical justification (e.g., "Superseded by theme_2.py"). +5. **Surgical Edit:** Use the `replace` tool for targeted deletions. Avoid bulk file overwrites. +6. **Style Verification:** Immediately run `scripts/ai_style_formatter.py` on the modified file to ensure indentation and formatting standards are maintained. + +## 2. Regression Guardrails + +- **Functional Parity:** After every major deletion (e.g., removing a redundant module), run the associated unit tests (if any). +- **Simulation Verification:** For changes to core pipelines (AI loop, Aggregation), run at least one relevant simulation (e.g., `simulation/ping_pong.py`) to verify end-to-end behavior. +- **Human-in-the-Loop:** Significant refactors (e.g., the `aggregate.py` rework) MUST be presented to the user with a detailed diff before final commitment. + +## 3. Culling Justification Standards + +- **"Unused"**: Symbol has 0 project-wide references in the audit. +- **"Redundant"**: Logic exists in a superior or more modern form elsewhere (e.g., `theme.py`). +- **"Slop"**: Code that adds complexity without contributing to performance, configuration, or a specified feature. diff --git a/conductor/archive/codebase_curation_20260507/index.md b/conductor/archive/codebase_curation_20260507/index.md new file mode 100644 index 0000000..c4baf94 --- /dev/null +++ b/conductor/archive/codebase_curation_20260507/index.md @@ -0,0 +1,5 @@ +# Track codebase_curation_20260507 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/archive/codebase_curation_20260507/metadata.json b/conductor/archive/codebase_curation_20260507/metadata.json new file mode 100644 index 0000000..106359c --- /dev/null +++ b/conductor/archive/codebase_curation_20260507/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "codebase_curation_20260507", + "type": "chore", + "status": "new", + "created_at": "2026-05-07T15:00:00Z", + "updated_at": "2026-05-07T15:00:00Z", + "description": "Exhaustive review of all .py files. Remove redundancies, eliminate unnecessary code/data/processing, and strictly align with project standards." +} diff --git a/conductor/archive/codebase_curation_20260507/plan.md b/conductor/archive/codebase_curation_20260507/plan.md new file mode 100644 index 0000000..a084fe6 --- /dev/null +++ b/conductor/archive/codebase_curation_20260507/plan.md @@ -0,0 +1,29 @@ +# Implementation Plan: Comprehensive Codebase Curation & Style Alignment (codebase_curation_20260507) + +## Phase 0: Context Integration & Strategy +- [x] Task: Review all Phase 5 analysis reports in `./docs` to internalize the curation roadmap. +- [x] Task: Define a "Granular Review Protocol" for file-by-file auditing and culling. +- [x] Task: Conductor - User Manual Verification 'Curation Strategy' (Protocol in workflow.md) + +## Phase 1: Automated Standardization & Audit +- [~] Task: Run `scripts/ai_style_formatter.py` and `scripts/force_1space.py` on all files in `./src` and `./simulation`. +- [ ] Task: Conduct an automated entropy audit to identify potential redundancy "hotspots". +- [ ] Task: Conductor - User Manual Verification 'Standardization' (Protocol in workflow.md) + +## Phase 2: Surgical Curation of `./src` +- [ ] Task: Comprehensive rework of `src/aggregate.py`. Modernize context assembly to leverage MCP tools, snapshots, and file caching. Consolidate tier-specific boilerplate. +- [ ] Task: Review and trim `gui_2.py` and `app_controller.py` based on pipeline maps. +- [ ] Task: Consolidate data models in `models.py` and remove redundant state in `aggregate.py`. +- [ ] Task: Refactor `ai_client.py` to ensure lean processing of provider responses. +- [ ] Task: Conductor - User Manual Verification 'Source Curation' (Protocol in workflow.md) + +## Phase 3: Surgical Curation of `./simulation` +- [ ] Task: Review and trim `./simulation/` base classes and utility scripts. +- [ ] Task: Eliminate redundant setup logic in `sim_context.py` and `workflow_sim.py`. +- [ ] Task: Conductor - User Manual Verification 'Simulation Curation' (Protocol in workflow.md) + +## Phase 4: Final Integrity Pass +- [ ] Task: Verify all tests pass with the trimmed codebase. +- [ ] Task: Final comparison against `product-guidelines.md` for architectural purity. +- [ ] Task: Final performance baseline check to ensure no regressions. +- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) diff --git a/conductor/archive/codebase_curation_20260507/spec.md b/conductor/archive/codebase_curation_20260507/spec.md new file mode 100644 index 0000000..38c5356 --- /dev/null +++ b/conductor/archive/codebase_curation_20260507/spec.md @@ -0,0 +1,35 @@ +# Specification: Comprehensive Codebase Curation & Style Alignment (codebase_curation_20260507) + +## Overview +Aggressive pruning, optimization, and standardization of the codebase. This track uses the findings from the Code Path Analysis and other Phase 5 audits to trim away non-essential logic, data, and processing while strictly enforcing the project's technical integrity standards. + +## Foundational Context (MANDATORY REVIEW) +All curation efforts MUST be informed by the following Phase 5 analysis reports: +- `docs/PIPELINE_ANALYSIS_PHASE5_INIT.md`: Processing route and pipeline mapping. +- `docs/STATE_INVENTORY_PHASE5.md`: Core data structure and property inventory. +- `docs/MUTATION_MATRIX_PHASE5.md`: Thread-safe state modification and lock map. +- `docs/CULLING_CANDIDATES_PHASE5.md`: Identified redundant symbols, modules, and structures. + +## Granular Care & Regression Guardrails +- **Surgical Execution:** Changes must be applied file-by-file with extreme granularity. No bulk culling without individual justification. +- **Regression Monitoring:** Continuous verification of behavioral integrity. Any unintended entropy or performance degradation must trigger an immediate halt and review. +- **Traceability:** Every removed line must be cross-referenced against the culling audit or pipeline map. + +## Scope +- **Target Files:** All `.py` files in `./src` and `./simulation`. +- **Primary Goal:** Trimming the "slop" (redundancies, dead code, excessive complexity). + +## Functional Requirements +1. **Redundancy Pruning:** Eliminate duplicate logic across different data pipelines. +2. **Dead Code Removal:** Strip out legacy "just-in-case" code and unused processing paths. +3. **Strict Style Enforcement:** + - Universal 1-space indentation. + - CRLF line endings. + - Standardized type hinting. +4. **Guideline Alignment:** Refactor any code that deviates from `product-guidelines.md` (e.g., ensuring explicit composition over complex inheritance). +5. **Validation:** Ensure no loss of functionality or performance degradation. + +## Acceptance Criteria +- [ ] Significant reduction in total codebase line count (where applicable). +- [ ] 100% pass on style audit (`scripts/ai_style_formatter.py`). +- [ ] All remaining code is mapped to a necessary functional requirement or performance goal. diff --git a/conductor/tracks.md b/conductor/tracks.md index 374c903..70df9ca 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -22,9 +22,25 @@ This file tracks all major tracks for the project. Each track has its own detail *Link: [./tracks/source_wide_redundancy_audit_20260507/](./tracks/source_wide_redundancy_audit_20260507/)* *Goal: Deep file-by-file audit to identify unused methods, duplicate logic, and dead code.* -4. [~] **Track: Comprehensive Codebase Curation & Style Alignment** - *Link: [./tracks/codebase_curation_20260507/](./tracks/codebase_curation_20260507/)* - *Goal: Exhaustive review of all `.py` files. Remove redundancies, eliminate unnecessary code/data/processing, and strictly align with `product-guidelines.md` and the Python style guide. Focus on performance and maintainability.* +4. [ ] **Track: Curate Provider Registries** + *Link: [./tracks/curate_provider_registries_20260507/](./tracks/curate_provider_registries_20260507/)* + *Goal: Move the PROVIDERS list to models.py and update all references to use this single source of truth.* + +5. [ ] **Track: Encapsulate AppController Status** + *Link: [./tracks/encapsulate_appcontroller_status_20260507/](./tracks/encapsulate_appcontroller_status_20260507/)* + *Goal: Convert ai_status and mma_status to properties with thread-safe setters.* + +6. [ ] **Track: Decouple GUI Log Loading** + *Link: [./tracks/decouple_gui_log_loading_20260507/](./tracks/decouple_gui_log_loading_20260507/)* + *Goal: Move Tkinter directory selection out of AppController and into gui_2.py.* + +7. [ ] **Track: Refactor Context Aggregation Pipeline** + *Link: [./tracks/refactor_context_aggregation_pipeline_20260507/](./tracks/refactor_context_aggregation_pipeline_20260507/)* + *Goal: Modernize src/aggregate.py and consolidate legacy tier builders.* + +8. [ ] **Track: Cull Unused Symbols** + *Link: [./tracks/cull_unused_symbols_20260507/](./tracks/cull_unused_symbols_20260507/)* + *Goal: Safely remove the 27 dead symbols identified in the redundancy audit.* --- diff --git a/conductor/tracks/cull_unused_symbols_20260507/index.md b/conductor/tracks/cull_unused_symbols_20260507/index.md new file mode 100644 index 0000000..7c3f967 --- /dev/null +++ b/conductor/tracks/cull_unused_symbols_20260507/index.md @@ -0,0 +1 @@ +# Track cull_unused_symbols_20260507 Context\n\n- [Specification](./spec.md)\n- [Implementation Plan](./plan.md)\n- [Metadata](./metadata.json)\n \ No newline at end of file diff --git a/conductor/tracks/cull_unused_symbols_20260507/metadata.json b/conductor/tracks/cull_unused_symbols_20260507/metadata.json new file mode 100644 index 0000000..d1a8ec9 --- /dev/null +++ b/conductor/tracks/cull_unused_symbols_20260507/metadata.json @@ -0,0 +1,6 @@ +{ + "track_id": "cull_unused_symbols_20260507", + "type": "chore", + "status": "new", + "description": "Safely remove the 27 dead symbols identified in the redundancy audit." +} \ No newline at end of file diff --git a/conductor/tracks/cull_unused_symbols_20260507/plan.md b/conductor/tracks/cull_unused_symbols_20260507/plan.md new file mode 100644 index 0000000..0d8c0e1 --- /dev/null +++ b/conductor/tracks/cull_unused_symbols_20260507/plan.md @@ -0,0 +1 @@ +# Implementation Plan: Cull Unused Symbols\n\n## Phase 1: Execution\n- [ ] Task: Remove unused aggregation and AI helpers\n- [ ] Task: Remove unused UI and diff viewer helpers\n- [ ] Task: Remove unused infrastructure and file cache helpers\n- [ ] Task: Run full test suite\n- [ ] Conductor - User Manual Verification (Protocol in workflow.md)\n \ No newline at end of file diff --git a/conductor/tracks/cull_unused_symbols_20260507/spec.md b/conductor/tracks/cull_unused_symbols_20260507/spec.md new file mode 100644 index 0000000..aeb4095 --- /dev/null +++ b/conductor/tracks/cull_unused_symbols_20260507/spec.md @@ -0,0 +1 @@ +# Specification: Cull Unused Symbols\n\n## Overview\nSafely remove the 27 dead symbols identified in the redundancy audit.\n\n## Acceptance Criteria\n- [ ] All tasks completed without breaking the test suite.\n \ No newline at end of file diff --git a/conductor/tracks/curate_provider_registries_20260507/index.md b/conductor/tracks/curate_provider_registries_20260507/index.md new file mode 100644 index 0000000..509c14f --- /dev/null +++ b/conductor/tracks/curate_provider_registries_20260507/index.md @@ -0,0 +1 @@ +# Track curate_provider_registries_20260507 Context\n\n- [Specification](./spec.md)\n- [Implementation Plan](./plan.md)\n- [Metadata](./metadata.json)\n \ No newline at end of file diff --git a/conductor/tracks/curate_provider_registries_20260507/metadata.json b/conductor/tracks/curate_provider_registries_20260507/metadata.json new file mode 100644 index 0000000..7bc1826 --- /dev/null +++ b/conductor/tracks/curate_provider_registries_20260507/metadata.json @@ -0,0 +1,6 @@ +{ + "track_id": "curate_provider_registries_20260507", + "type": "chore", + "status": "new", + "description": "Move the PROVIDERS list to models.py and update all references to use this single source of truth." +} \ No newline at end of file diff --git a/conductor/tracks/curate_provider_registries_20260507/plan.md b/conductor/tracks/curate_provider_registries_20260507/plan.md new file mode 100644 index 0000000..68771fc --- /dev/null +++ b/conductor/tracks/curate_provider_registries_20260507/plan.md @@ -0,0 +1 @@ +# Implementation Plan: Curate Provider Registries\n\n## Phase 1: Execution\n- [ ] Task: Define PROVIDERS in models.py\n- [ ] Task: Remove PROVIDERS list from AppController and App\n- [ ] Task: Update all provider loop references in gui_2.py and app_controller.py\n- [ ] Task: Run full test suite\n- [ ] Conductor - User Manual Verification (Protocol in workflow.md)\n \ No newline at end of file diff --git a/conductor/tracks/curate_provider_registries_20260507/spec.md b/conductor/tracks/curate_provider_registries_20260507/spec.md new file mode 100644 index 0000000..8f46e53 --- /dev/null +++ b/conductor/tracks/curate_provider_registries_20260507/spec.md @@ -0,0 +1 @@ +# Specification: Curate Provider Registries\n\n## Overview\nMove the PROVIDERS list to models.py and update all references to use this single source of truth.\n\n## Acceptance Criteria\n- [ ] All tasks completed without breaking the test suite.\n \ No newline at end of file diff --git a/conductor/tracks/decouple_gui_log_loading_20260507/index.md b/conductor/tracks/decouple_gui_log_loading_20260507/index.md new file mode 100644 index 0000000..f23fd80 --- /dev/null +++ b/conductor/tracks/decouple_gui_log_loading_20260507/index.md @@ -0,0 +1 @@ +# Track decouple_gui_log_loading_20260507 Context\n\n- [Specification](./spec.md)\n- [Implementation Plan](./plan.md)\n- [Metadata](./metadata.json)\n \ No newline at end of file diff --git a/conductor/tracks/decouple_gui_log_loading_20260507/metadata.json b/conductor/tracks/decouple_gui_log_loading_20260507/metadata.json new file mode 100644 index 0000000..72783a1 --- /dev/null +++ b/conductor/tracks/decouple_gui_log_loading_20260507/metadata.json @@ -0,0 +1,6 @@ +{ + "track_id": "decouple_gui_log_loading_20260507", + "type": "chore", + "status": "new", + "description": "Move Tkinter directory selection out of AppController and into gui_2.py." +} \ No newline at end of file diff --git a/conductor/tracks/decouple_gui_log_loading_20260507/plan.md b/conductor/tracks/decouple_gui_log_loading_20260507/plan.md new file mode 100644 index 0000000..68223bf --- /dev/null +++ b/conductor/tracks/decouple_gui_log_loading_20260507/plan.md @@ -0,0 +1 @@ +# Implementation Plan: Decouple GUI Log Loading\n\n## Phase 1: Execution\n- [ ] Task: Remove Tkinter imports and hide_tk_root from app_controller.py\n- [ ] Task: Remove Tkinter logic from AppController.cb_load_prior_log\n- [ ] Task: Implement cb_load_prior_log wrapper in gui_2.py App class\n- [ ] Task: Run full test suite\n- [ ] Conductor - User Manual Verification (Protocol in workflow.md)\n \ No newline at end of file diff --git a/conductor/tracks/decouple_gui_log_loading_20260507/spec.md b/conductor/tracks/decouple_gui_log_loading_20260507/spec.md new file mode 100644 index 0000000..d2a146c --- /dev/null +++ b/conductor/tracks/decouple_gui_log_loading_20260507/spec.md @@ -0,0 +1 @@ +# Specification: Decouple GUI Log Loading\n\n## Overview\nMove Tkinter directory selection out of AppController and into gui_2.py.\n\n## Acceptance Criteria\n- [ ] All tasks completed without breaking the test suite.\n \ No newline at end of file diff --git a/conductor/tracks/encapsulate_appcontroller_status_20260507/index.md b/conductor/tracks/encapsulate_appcontroller_status_20260507/index.md new file mode 100644 index 0000000..ab880c8 --- /dev/null +++ b/conductor/tracks/encapsulate_appcontroller_status_20260507/index.md @@ -0,0 +1 @@ +# Track encapsulate_appcontroller_status_20260507 Context\n\n- [Specification](./spec.md)\n- [Implementation Plan](./plan.md)\n- [Metadata](./metadata.json)\n \ No newline at end of file diff --git a/conductor/tracks/encapsulate_appcontroller_status_20260507/metadata.json b/conductor/tracks/encapsulate_appcontroller_status_20260507/metadata.json new file mode 100644 index 0000000..f7a68a8 --- /dev/null +++ b/conductor/tracks/encapsulate_appcontroller_status_20260507/metadata.json @@ -0,0 +1,6 @@ +{ + "track_id": "encapsulate_appcontroller_status_20260507", + "type": "chore", + "status": "new", + "description": "Convert ai_status and mma_status to properties with thread-safe setters." +} \ No newline at end of file diff --git a/conductor/tracks/encapsulate_appcontroller_status_20260507/plan.md b/conductor/tracks/encapsulate_appcontroller_status_20260507/plan.md new file mode 100644 index 0000000..e45074d --- /dev/null +++ b/conductor/tracks/encapsulate_appcontroller_status_20260507/plan.md @@ -0,0 +1 @@ +# Implementation Plan: Encapsulate AppController Status\n\n## Phase 1: Execution\n- [ ] Task: Add private _ai_status and _mma_status to AppController.__init__\n- [ ] Task: Implement @property and @setter for ai_status and mma_status\n- [ ] Task: Replace all legacy _set_status calls with direct property assignment\n- [ ] Task: Run full test suite\n- [ ] Conductor - User Manual Verification (Protocol in workflow.md)\n \ No newline at end of file diff --git a/conductor/tracks/encapsulate_appcontroller_status_20260507/spec.md b/conductor/tracks/encapsulate_appcontroller_status_20260507/spec.md new file mode 100644 index 0000000..e9ad693 --- /dev/null +++ b/conductor/tracks/encapsulate_appcontroller_status_20260507/spec.md @@ -0,0 +1 @@ +# Specification: Encapsulate AppController Status\n\n## Overview\nConvert ai_status and mma_status to properties with thread-safe setters.\n\n## Acceptance Criteria\n- [ ] All tasks completed without breaking the test suite.\n \ No newline at end of file diff --git a/conductor/tracks/refactor_context_aggregation_pipeline_20260507/index.md b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/index.md new file mode 100644 index 0000000..bdf0793 --- /dev/null +++ b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/index.md @@ -0,0 +1 @@ +# Track refactor_context_aggregation_pipeline_20260507 Context\n\n- [Specification](./spec.md)\n- [Implementation Plan](./plan.md)\n- [Metadata](./metadata.json)\n \ No newline at end of file diff --git a/conductor/tracks/refactor_context_aggregation_pipeline_20260507/metadata.json b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/metadata.json new file mode 100644 index 0000000..69cf3b9 --- /dev/null +++ b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/metadata.json @@ -0,0 +1,6 @@ +{ + "track_id": "refactor_context_aggregation_pipeline_20260507", + "type": "chore", + "status": "new", + "description": "Modernize src/aggregate.py and consolidate legacy tier builders." +} \ No newline at end of file diff --git a/conductor/tracks/refactor_context_aggregation_pipeline_20260507/plan.md b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/plan.md new file mode 100644 index 0000000..8d41d70 --- /dev/null +++ b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/plan.md @@ -0,0 +1 @@ +# Implementation Plan: Refactor Context Aggregation Pipeline\n\n## Phase 1: Execution\n- [ ] Task: Remove unused build_tier1_context and build_tier2_context\n- [ ] Task: Refactor build_tier3_context to use standard formatting\n- [ ] Task: Consolidate build_markdown and build_markdown_from_items\n- [ ] Task: Run full test suite\n- [ ] Conductor - User Manual Verification (Protocol in workflow.md)\n \ No newline at end of file diff --git a/conductor/tracks/refactor_context_aggregation_pipeline_20260507/spec.md b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/spec.md new file mode 100644 index 0000000..28e64ff --- /dev/null +++ b/conductor/tracks/refactor_context_aggregation_pipeline_20260507/spec.md @@ -0,0 +1 @@ +# Specification: Refactor Context Aggregation Pipeline\n\n## Overview\nModernize src/aggregate.py and consolidate legacy tier builders.\n\n## Acceptance Criteria\n- [ ] All tasks completed without breaking the test suite.\n \ No newline at end of file