diff --git a/conductor/tracks/code_path_analysis_20260507/index.md b/conductor/archive/code_path_analysis_20260507/index.md similarity index 100% rename from conductor/tracks/code_path_analysis_20260507/index.md rename to conductor/archive/code_path_analysis_20260507/index.md diff --git a/conductor/tracks/code_path_analysis_20260507/metadata.json b/conductor/archive/code_path_analysis_20260507/metadata.json similarity index 100% rename from conductor/tracks/code_path_analysis_20260507/metadata.json rename to conductor/archive/code_path_analysis_20260507/metadata.json diff --git a/conductor/tracks/code_path_analysis_20260507/plan.md b/conductor/archive/code_path_analysis_20260507/plan.md similarity index 100% rename from conductor/tracks/code_path_analysis_20260507/plan.md rename to conductor/archive/code_path_analysis_20260507/plan.md diff --git a/conductor/tracks/code_path_analysis_20260507/spec.md b/conductor/archive/code_path_analysis_20260507/spec.md similarity index 100% rename from conductor/tracks/code_path_analysis_20260507/spec.md rename to conductor/archive/code_path_analysis_20260507/spec.md diff --git a/conductor/tracks.md b/conductor/tracks.md index 35ad8bf..e68d59f 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -10,11 +10,19 @@ This file tracks all major tracks for the project. Each track has its own detail ### Analysis & Structural Review -1. [x] **Track: Code Path & Data Pipeline Analysis** - *Link: [./tracks/code_path_analysis_20260507/](./tracks/code_path_analysis_20260507/)* - *Goal: Comprehensive analysis of major processing routes in `./src` and `./simulation`. Identify data pipelines and responsibilities. Map core execution flows to inform curation efforts.* +1. [ ] **Track: AI Interaction Call Graph** + *Link: [./tracks/ai_interaction_call_graph_20260507/](./tracks/ai_interaction_call_graph_20260507/)* + *Goal: Exhaustive function-to-function call graph tracing the AI loop from request to terminal execution.* -2. [ ] **Track: Comprehensive Codebase Curation & Style Alignment** +2. [ ] **Track: Controller State Mutation Matrix** + *Link: [./tracks/controller_state_mutation_matrix_20260507/](./tracks/controller_state_mutation_matrix_20260507/)* + *Goal: Comprehensive map of all methods that modify the `AppController` and `App` state.* + +3. [ ] **Track: Source-Wide Redundancy Audit** + *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.* diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/index.md b/conductor/tracks/ai_interaction_call_graph_20260507/index.md new file mode 100644 index 0000000..19a71be --- /dev/null +++ b/conductor/tracks/ai_interaction_call_graph_20260507/index.md @@ -0,0 +1,5 @@ +# Track ai_interaction_call_graph_20260507 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/metadata.json b/conductor/tracks/ai_interaction_call_graph_20260507/metadata.json new file mode 100644 index 0000000..9560c8a --- /dev/null +++ b/conductor/tracks/ai_interaction_call_graph_20260507/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "ai_interaction_call_graph_20260507", + "type": "chore", + "status": "new", + "created_at": "2026-05-07T16:00:00Z", + "updated_at": "2026-05-07T16:00:00Z", + "description": "Exhaustive function-to-function call graph tracing the AI loop from request to terminal execution." +} diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/plan.md b/conductor/tracks/ai_interaction_call_graph_20260507/plan.md new file mode 100644 index 0000000..29c4f19 --- /dev/null +++ b/conductor/tracks/ai_interaction_call_graph_20260507/plan.md @@ -0,0 +1,11 @@ +# Implementation Plan: AI Interaction Call Graph (ai_interaction_call_graph_20260507) + +## Phase 1: Trace Mapping +- [ ] Task: Use `py_find_usages` to trace `ai_client.send` callers and callees. +- [ ] Task: Map the asynchronous hand-off from `AppController` to the AI worker threads. +- [ ] Task: Trace the recursion depth of the tool-call loop (`MAX_TOOL_ROUNDS`). + +## Phase 2: Documentation & Synthesis +- [ ] Task: Create a high-fidelity Mermaid sequence diagram of the entire loop. +- [ ] Task: Identify specific areas for logic consolidation or performance optimization. +- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/spec.md b/conductor/tracks/ai_interaction_call_graph_20260507/spec.md new file mode 100644 index 0000000..5fe137a --- /dev/null +++ b/conductor/tracks/ai_interaction_call_graph_20260507/spec.md @@ -0,0 +1,22 @@ +# Specification: AI Interaction Call Graph (ai_interaction_call_graph_20260507) + +## Overview +A low-level technical trace of the AI interaction loop. The goal is to map every single function call and data hand-off from the moment a user message is sent to the final terminal execution of a PowerShell script or tool result. + +## Scope +- **Entry Point:** `src/gui_2.py:App._render_discussion_panel` (Send button action). +- **Subsystems:** `ai_client.py`, `mcp_client.py`, `shell_runner.py`, `app_controller.py`. + +## Functional Requirements +1. **Call Graph Generation:** + - Document the sequence of synchronous and asynchronous calls. + - Identify thread boundaries (GUI thread vs. Background worker thread). +2. **Data Transformation Trace:** + - Track the transformation of a message: raw text -> GenerateRequest -> AI History -> Provider Prompt -> AI Response -> Tool Call -> PS Script. +3. **Error & Retry Paths:** + - Map how exceptions are caught, classified, and bubbled back to the UI. + +## Acceptance Criteria +- [ ] Detailed call graph in Mermaid format. +- [ ] List of all internal private methods involved in the loop. +- [ ] Identification of any blocking calls in the async pipeline. diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/index.md b/conductor/tracks/controller_state_mutation_matrix_20260507/index.md new file mode 100644 index 0000000..525f97c --- /dev/null +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/index.md @@ -0,0 +1,5 @@ +# Track controller_state_mutation_matrix_20260507 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/metadata.json b/conductor/tracks/controller_state_mutation_matrix_20260507/metadata.json new file mode 100644 index 0000000..66ce3cd --- /dev/null +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "controller_state_mutation_matrix_20260507", + "type": "chore", + "status": "new", + "created_at": "2026-05-07T16:00:00Z", + "updated_at": "2026-05-07T16:00:00Z", + "description": "Comprehensive map of all methods that modify the AppController and App state." +} diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md b/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md new file mode 100644 index 0000000..a97c735 --- /dev/null +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/plan.md @@ -0,0 +1,10 @@ +# Implementation Plan: Controller State Mutation Matrix (controller_state_mutation_matrix_20260507) + +## Phase 1: State Inventory +- [ ] Task: List all public and private properties in `AppController` and `App`. +- [ ] Task: Identify all threading locks and their current usage patterns. + +## Phase 2: Mutation Mapping +- [ ] Task: Use grep/AST tools to find all assignments to identified state fields. +- [ ] Task: Populate the mutation matrix table. +- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) diff --git a/conductor/tracks/controller_state_mutation_matrix_20260507/spec.md b/conductor/tracks/controller_state_mutation_matrix_20260507/spec.md new file mode 100644 index 0000000..84262c9 --- /dev/null +++ b/conductor/tracks/controller_state_mutation_matrix_20260507/spec.md @@ -0,0 +1,21 @@ +# Specification: Controller State Mutation Matrix (controller_state_mutation_matrix_20260507) + +## Overview +Mapping the state landscape of the Manual Slop application. We need to know exactly which methods have the authority to change global state, especially within `AppController` and `App`. + +## Scope +- **Classes:** `App`, `AppController`. +- **Target Fields:** `ai_status`, `mma_status`, `_pending_gui_tasks`, `disc_entries`, `config`, etc. + +## Functional Requirements +1. **Mutation Matrix:** + - Create a table: [Method Name] x [State Field Modified]. +2. **Lock Ownership Audit:** + - Document which locks (e.g., `_pending_gui_tasks_lock`) protect which fields. + - Identify potential race conditions or unprotected mutations. +3. **State Lifecycle:** + - Document how state is flushed to disk (autosave) vs. held in memory. + +## Acceptance Criteria +- [ ] Matrix table identifying every state mutation site. +- [ ] Audit report of thread-safety and lock usage. diff --git a/conductor/tracks/source_wide_redundancy_audit_20260507/index.md b/conductor/tracks/source_wide_redundancy_audit_20260507/index.md new file mode 100644 index 0000000..726ce0b --- /dev/null +++ b/conductor/tracks/source_wide_redundancy_audit_20260507/index.md @@ -0,0 +1,5 @@ +# Track source_wide_redundancy_audit_20260507 Context + +- [Specification](./spec.md) +- [Implementation Plan](./plan.md) +- [Metadata](./metadata.json) diff --git a/conductor/tracks/source_wide_redundancy_audit_20260507/metadata.json b/conductor/tracks/source_wide_redundancy_audit_20260507/metadata.json new file mode 100644 index 0000000..462e804 --- /dev/null +++ b/conductor/tracks/source_wide_redundancy_audit_20260507/metadata.json @@ -0,0 +1,8 @@ +{ + "track_id": "source_wide_redundancy_audit_20260507", + "type": "chore", + "status": "new", + "created_at": "2026-05-07T16:00:00Z", + "updated_at": "2026-05-07T16:00:00Z", + "description": "Deep file-by-file audit to identify unused methods, duplicate logic, and dead code." +} diff --git a/conductor/tracks/source_wide_redundancy_audit_20260507/plan.md b/conductor/tracks/source_wide_redundancy_audit_20260507/plan.md new file mode 100644 index 0000000..49e2ef5 --- /dev/null +++ b/conductor/tracks/source_wide_redundancy_audit_20260507/plan.md @@ -0,0 +1,10 @@ +# Implementation Plan: Source-Wide Redundancy Audit (source_wide_redundancy_audit_20260507) + +## Phase 1: Automated Scans +- [ ] Task: Run automated "Unused Code" scripts (if any) or use `py_find_usages` on every public symbol. +- [ ] Task: Compare functionally similar files (e.g., `aggregate.py` and `summarize.py` helpers). + +## Phase 2: Manual Review & Culling List +- [ ] Task: Review `models.py` against all consumer imports to find unused fields. +- [ ] Task: Finalize the "Culling Candidate" report. +- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) diff --git a/conductor/tracks/source_wide_redundancy_audit_20260507/spec.md b/conductor/tracks/source_wide_redundancy_audit_20260507/spec.md new file mode 100644 index 0000000..98dee1b --- /dev/null +++ b/conductor/tracks/source_wide_redundancy_audit_20260507/spec.md @@ -0,0 +1,22 @@ +# Specification: Source-Wide Redundancy Audit (source_wide_redundancy_audit_20260507) + +## Overview +The "Culling" phase of the curation. This track focuses on identifying everything in the codebase that doesn't need to be there. This includes dead functions, duplicate helper methods, and bloated data structures. + +## Scope +- **Directories:** `./src`, `./simulation`. + +## Functional Requirements +1. **Dead Code Identification:** + - Find methods and classes that are never imported or called. +2. **Logic Deduplication:** + - Identify functionally identical blocks (e.g., path resolution logic in multiple files). +3. **Data Bloat Audit:** + - Find unused fields in `models.py` dataclasses. +4. **Style Alignment Pre-check:** + - Flag files that significantly deviate from the "1-space indent" or "composition over inheritance" rules. + +## Acceptance Criteria +- [ ] List of "Culling Candidates" with justifications. +- [ ] Identification of logic that can be consolidated into shared utilities. +- [ ] Verification of `models.py` purity.