4 Commits

19 changed files with 292 additions and 9 deletions
+4 -1
View File
@@ -1,14 +1,17 @@
# Project Context
## Definition
- [Product Definition](./product.md)
- [Product Guidelines](./product-guidelines.md)
- [Tech Stack](./tech-stack.md)
## Workflow
- [Workflow](./workflow.md)
- [Code Style Guides](./code_styleguides/)
## Management
- [Tracks Registry](./tracks.md)
- [Tracks Directory](./tracks/)
- [Tracks Directory](./tracks/)
+3
View File
@@ -1,15 +1,18 @@
# Product Guidelines: Manual Slop
## Documentation Style
- **Strict & In-Depth:** Documentation must follow an old-school, highly detailed technical breakdown style (similar to VEFontCache-Odin). Focus on architectural design, state management, algorithmic details, and structural formats rather than just surface-level usage.
## UX & UI Principles
- **USA Graphics Company Values:** Embrace high information density and tactile interactions.
- **Arcade Aesthetics:** Utilize arcade game-style visual feedback for state updates (e.g., blinking notifications for tool execution and AI responses) to make the experience fun, visceral, and engaging.
- **Explicit Control & Expert Focus:** The interface should not hold the user's hand. It must prioritize explicit manual confirmation for destructive actions while providing dense, unadulterated access to logs and context.
- **Multi-Viewport Capabilities:** Leverage dockable, floatable panels to allow users to build custom workspaces suitable for multi-monitor setups.
## Code Standards & Architecture
- **Strict State Management:** There must be a rigorous separation between the Main GUI rendering thread and daemon execution threads. The UI should *never* hang during AI communication or script execution. Use lock-protected queues and events for synchronization.
- **Comprehensive Logging:** Aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs to ensure total transparency and debuggability.
- **Dependency Minimalism:** Limit external dependencies where possible. For instance, prefer standard library modules (like `urllib` and `html.parser` for web tools) over heavy third-party packages.
+6 -1
View File
@@ -1,17 +1,21 @@
# Technology Stack: Manual Slop
## Core Language
- **Python 3.11+**
## GUI Frameworks
- **Dear PyGui:** For immediate/retained mode GUI rendering and node mapping.
- **ImGui Bundle (`imgui-bundle`):** To provide advanced multi-viewport and dockable panel capabilities on top of Dear ImGui.
## AI Integration SDKs
- **google-genai:** For Google Gemini API interaction and explicit context caching.
- **anthropic:** For Anthropic Claude API interaction, supporting ephemeral prompt caching.
## Configuration & Tooling
- **tomli-w:** For writing TOML configuration files.
- **psutil:** For system and process monitoring (CPU/Memory telemetry).
- **uv:** An extremely fast Python package and project manager.
@@ -19,4 +23,5 @@
- **ApiHookClient:** A dedicated IPC client for automated GUI interaction and state inspection.
## Architectural Patterns
- **Event-Driven Metrics:** Uses a custom `EventEmitter` to decouple API lifecycle events from UI rendering, improving performance and responsiveness.
- **Event-Driven Metrics:** Uses a custom `EventEmitter` to decouple API lifecycle events from UI rendering, improving performance and responsiveness.
+15
View File
@@ -17,3 +17,18 @@ This file tracks all major tracks for the project. Each track has its own detail
- [~] **Track: get gui_2 working with latest changes to the project.**
*Link: [./tracks/gui2_feature_parity_20260223/](./tracks/gui2_feature_parity_20260223/)*
---
- [ ] **Track: Move discussion histories to their own toml to prevent the ai agent from reading it (will be on a blacklist).**
*Link: [./tracks/history_segregation_20260224/](./tracks/history_segregation_20260224/)*
---
- [ ] **Track: Update ./docs/* & ./Readme.md, review ./MainContext.md significance (should we keep it..).**
*Link: [./tracks/documentation_refresh_20260224/](./tracks/documentation_refresh_20260224/)*
---
- [ ] **Track: Investigate differences left between gui.py and gui_2.py. Needs to reach full parity, so we can sunset guy.py**
*Link: [./tracks/gui2_parity_20260224/](./tracks/gui2_parity_20260224/)*
@@ -0,0 +1,5 @@
# Track documentation_refresh_20260224 Context
- [Specification](./spec.md)
- [Implementation Plan](./plan.md)
- [Metadata](./metadata.json)
@@ -0,0 +1,8 @@
{
"track_id": "documentation_refresh_20260224",
"type": "chore",
"status": "new",
"created_at": "2026-02-24T18:35:00Z",
"updated_at": "2026-02-24T18:35:00Z",
"description": "Update ./docs/* & ./Readme.md, review ./MainContext.md significance (should we keep it..)."
}
@@ -0,0 +1,34 @@
# Implementation Plan: Documentation Refresh and Context Cleanup
This plan follows the project's standard task workflow to modernize documentation and decommission redundant context files.
## Phase 1: Context Cleanup
Permanently remove redundant files and update project-wide references.
- [ ] Task: Audit references to `MainContext.md` across the project.
- [ ] Task: Write failing test that verifies the absence of `MainContext.md` and related broken links.
- [ ] Task: Delete `MainContext.md` and update any identified references.
- [ ] Task: Verify that all internal links remain functional.
- [ ] Task: Conductor - User Manual Verification 'Context Cleanup' (Protocol in workflow.md)
## Phase 2: Core Documentation Refresh
Update the Architecture and Tools guides to reflect recent architectural changes.
- [ ] Task: Audit `docs/guide_architecture.md` against current code (e.g., `EventEmitter`, `ApiHookClient`, Conductor).
- [ ] Task: Update `docs/guide_architecture.md` with current Conductor-driven architecture and dual-GUI structure.
- [ ] Task: Audit `docs/guide_tools.md` for toolset accuracy.
- [ ] Task: Update `docs/guide_tools.md` to include API hook client and performance monitoring documentation.
- [ ] Task: Verify documentation alignment with actual implementation.
- [ ] Task: Conductor - User Manual Verification 'Core Documentation Refresh' (Protocol in workflow.md)
## Phase 3: README Refresh and Link Validation
Modernize the primary project entry point and ensure documentation integrity.
- [ ] Task: Audit `Readme.md` for accuracy of setup instructions and feature highlights.
- [ ] Task: Write failing test (or link audit) that identifies outdated setup steps or broken links.
- [ ] Task: Update `Readme.md` with `uv` setup, current project vision, and feature lists (Conductor, GUI 2.0).
- [ ] Task: Perform a project-wide link validation of all Markdown files in `./docs/` and the root.
- [ ] Task: Verify setup instructions by performing a manual walkthrough of the Readme steps.
- [ ] Task: Conductor - User Manual Verification 'README Refresh and Link Validation' (Protocol in workflow.md)
---
[checkpoint: (SHA will be recorded here)]
@@ -0,0 +1,38 @@
# Specification: Documentation Refresh and Context Cleanup
## Overview
This track aims to modernize the project's documentation suite (Architecture, Tools, README) to reflect recent significant architectural additions, including the Conductor framework, the development of `gui_2.py`, and the API hook verification system. It also includes the decommissioning of `MainContext.md`, which has been identified as redundant in the current project structure.
## Functional Requirements
1. **Architecture Update (`docs/guide_architecture.md`):**
- Incorporate descriptions of the Conductor framework and its role in spec-driven development.
- Document the dual-GUI structure (`gui.py` and `gui_2.py`) and their respective development stages.
- Detail the `EventEmitter` and `ApiHookClient` as core architectural components.
2. **Tools Update (`docs/guide_tools.md`):**
- Refresh documentation for the current MCP toolset.
- Add documentation for the API hook client and automated GUI verification tools.
- Update performance monitoring tool descriptions.
3. **README Refresh (`Readme.md`):**
- Update setup instructions (e.g., `uv`, `credentials.toml`).
- Highlight new features: Conductor integration, GUI 2.0, and automated testing capabilities.
- Ensure the high-level project vision aligns with the current state.
4. **Context Cleanup:**
- Permanently remove `MainContext.md` from the project root.
- Update any internal references pointing to `MainContext.md`.
## Non-Functional Requirements
- **Link Validation:** All internal documentation links must be verified as valid.
- **Code-Doc Alignment:** Architectural descriptions must accurately reflect the current code structure.
- **Clarity & Brevity:** Documentation should remain concise and targeted at expert-level developers.
## Acceptance Criteria
- [ ] `MainContext.md` is deleted from the project.
- [ ] `docs/guide_architecture.md` is updated and reviewed for accuracy.
- [ ] `docs/guide_tools.md` is updated and reviewed for accuracy.
- [ ] `Readme.md` setup and feature sections are current.
- [ ] All internal links between `Readme.md` and the `./docs/` folder are functional.
## Out of Scope
- Automated documentation generation (e.g., Sphinx, Doxygen).
- In-depth documentation for features still in early prototyping stages.
- Creating new video or visual walkthroughs.
@@ -0,0 +1,5 @@
# Track gui2_parity_20260224 Context
- [Specification](./spec.md)
- [Implementation Plan](./plan.md)
- [Metadata](./metadata.json)
@@ -0,0 +1,8 @@
{
"track_id": "gui2_parity_20260224",
"type": "feature",
"status": "new",
"created_at": "2026-02-24T18:38:00Z",
"updated_at": "2026-02-24T18:38:00Z",
"description": "Investigate differences left between gui.py and gui_2.py. Needs to reach full parity, so we can sunset guy.py"
}
@@ -0,0 +1,40 @@
# Implementation Plan: GUI 2.0 Feature Parity and Migration
This plan follows the project's standard task workflow to ensure full feature parity and a stable transition to the ImGui-based `gui_2.py`.
## Phase 1: Research and Gap Analysis
Identify and document the exact differences between `gui.py` and `gui_2.py`.
- [ ] Task: Audit `gui.py` and `gui_2.py` side-by-side to document specific visual and functional gaps.
- [ ] Task: Map existing `EventEmitter` and `ApiHookClient` integrations in `gui.py` to `gui_2.py`.
- [ ] Task: Write failing tests in `tests/test_gui2_parity.py` that identify missing UI components or broken hooks in `gui_2.py`.
- [ ] Task: Verify failing parity tests.
- [ ] Task: Conductor - User Manual Verification 'Phase 1: Research and Gap Analysis' (Protocol in workflow.md)
## Phase 2: Visual and Functional Parity Implementation
Address all identified gaps and ensure functional equivalence.
- [ ] Task: Implement missing panels and UX nuances (text sizing, font rendering) in `gui_2.py`.
- [ ] Task: Complete integration of all `EventEmitter` hooks in `gui_2.py` to match `gui.py`.
- [ ] Task: Verify functional parity by running `tests/test_gui2_events.py` and `tests/test_gui2_layout.py`.
- [ ] Task: Address any identified regressions or missing interactive elements.
- [ ] Task: Conductor - User Manual Verification 'Phase 2: Visual and Functional Parity Implementation' (Protocol in workflow.md)
## Phase 3: Performance Optimization and Final Validation
Ensure `gui_2.py` meets performance requirements and passes all quality gates.
- [ ] Task: Conduct performance benchmarking (FPS, CPU, Frame Time) for both `gui.py` and `gui_2.py`.
- [ ] Task: Optimize rendering and docking logic in `gui_2.py` if performance targets are not met.
- [ ] Task: Verify performance parity using `tests/test_gui2_performance.py`.
- [ ] Task: Run full suite of automated GUI tests with `live_gui` fixture on `gui_2.py`.
- [ ] Task: Conductor - User Manual Verification 'Phase 3: Performance Optimization and Final Validation' (Protocol in workflow.md)
## Phase 4: Deprecation and Cleanup
Finalize the migration and decommission the original `gui.py`.
- [ ] Task: Rename `gui.py` to `gui_legacy.py`.
- [ ] Task: Update project entry point or documentation to point to `gui_2.py` as the primary interface.
- [ ] Task: Final project-wide link validation and documentation update.
- [ ] Task: Conductor - User Manual Verification 'Phase 4: Deprecation and Cleanup' (Protocol in workflow.md)
---
[checkpoint: (SHA will be recorded here)]
@@ -0,0 +1,29 @@
# Specification: GUI 2.0 Feature Parity and Migration
## Overview
The project is transitioning from `gui.py` (Dear PyGui-based) to `gui_2.py` (ImGui Bundle-based) to leverage advanced multi-viewport and docking features not natively supported by Dear PyGui. This track focuses on achieving full visual, functional, and performance parity between the two implementations, ultimately enabling the decommissioning of the original `gui.py`.
## Functional Requirements
1. **Visual Parity:**
- Ensure all panels, layouts, and interactive elements in `gui_2.py` match the established UX of `gui.py`.
- Address nuances in UX, such as text panel sizing and font rendering, to ensure a seamless transition for existing users.
2. **Functional Parity:**
- Verify that all backend hooks (API metrics, context management, MCP tools, shell execution) work identically in `gui_2.py`.
- Ensure all interactive controls (buttons, inputs, dropdowns) trigger the correct application state changes.
3. **Performance Parity:**
- Benchmark `gui_2.py` against `gui.py` for FPS, frame time, and CPU/memory usage.
- Optimize `gui_2.py` to meet or exceed the performance metrics of the original implementation.
## Non-Functional Requirements
- **Multi-Viewport Stability:** Ensure the ImGui-bundle implementation is stable across multiple windows and docking configurations.
- **Deprecation Workflow:** Establish a clear path for renaming `gui.py` to `gui_legacy.py` for a transition period.
## Acceptance Criteria
- [ ] `gui_2.py` successfully passes the full suite of GUI automated verification tests (e.g., `test_gui2_events.py`, `test_gui2_layout.py`).
- [ ] A side-by-side audit confirms visual and functional parity for all core Hub panels.
- [ ] Performance benchmarks show `gui_2.py` is within +/- 5% of `gui.py` metrics.
- [ ] `gui.py` is renamed to `gui_legacy.py`.
## Out of Scope
- Introducing new UI features or backend capabilities not present in `gui.py`.
- Modifying the core `EventEmitter` or `AiClient` logic (unless required for GUI hook integration).
@@ -0,0 +1,5 @@
# Track history_segregation_20260224 Context
- [Specification](./spec.md)
- [Implementation Plan](./plan.md)
- [Metadata](./metadata.json)
@@ -0,0 +1,8 @@
{
"track_id": "history_segregation_20260224",
"type": "feature",
"status": "new",
"created_at": "2026-02-24T18:28:00Z",
"updated_at": "2026-02-24T18:28:00Z",
"description": "Move discussion histories to their own toml to prevent the ai agent from reading it (will be on a blacklist)."
}
@@ -0,0 +1,30 @@
# Implementation Plan: Discussion History Segregation and Blacklisting
This plan follows the Test-Driven Development (TDD) workflow to move discussion history into a dedicated sibling TOML file and enforce a strict blacklist against AI agent tool access.
## Phase 1: Foundation and Migration Logic
This phase focuses on the structural changes needed to handle dual-file project configurations and the automatic migration of legacy history.
- [ ] Task: Research existing `ProjectManager` serialization and tool access points in `mcp_client.py`.
- [ ] Task: Write TDD tests for migrating the `discussion` key from `manual_slop.toml` to a new sibling file.
- [ ] Task: Implement automatic migration in `ProjectManager.load_project()`.
- [ ] Task: Update `ProjectManager.save_project()` to persist history separately.
- [ ] Task: Verify that existing history is correctly migrated and remains visible in the GUI.
- [ ] Task: Conductor - User Manual Verification 'Foundation and Migration' (Protocol in workflow.md)
## Phase 2: Blacklist Enforcement
This phase ensures the AI agent is strictly prevented from reading the history source files through its tools.
- [ ] Task: Write failing tests that attempt to read a known history file via the `mcp_client.py` and `aggregate.py` logic.
- [ ] Task: Implement hardcoded exclusion for `*_history.toml` and `history.toml` in `mcp_client.py`.
- [ ] Task: Implement hardcoded exclusion in `aggregate.py` to prevent history from being added as a raw file context.
- [ ] Task: Verify that tool-based file reads for the history file return a "Permission Denied" or "Blacklisted" error.
- [ ] Task: Conductor - User Manual Verification 'Blacklist Enforcement' (Protocol in workflow.md)
## Phase 3: Integration and Final Validation
This phase validates the full lifecycle, ensuring the application remains functional and secure.
- [ ] Task: Conduct a full walkthrough using the simulation scripts to verify history persistence across turns.
- [ ] Task: Verify that the AI can still use the *curated* history provided in the prompt context but cannot access the raw file.
- [ ] Task: Run full suite of automated GUI and API hook tests.
- [ ] Task: Conductor - User Manual Verification 'Integration and Final Validation' (Protocol in workflow.md)
@@ -0,0 +1,32 @@
# Specification: Discussion History Segregation and Blacklisting
## Overview
Currently, `manual_slop.toml` stores both project configuration and the entire discussion history. This leads to redundancy and potential context bloat if the AI agent reads the raw TOML file via its tools. This track will move the discussion history to a dedicated sibling TOML file (`history.toml`) and strictly blacklist it from the AI agent's file tools to ensure it only interacts with the curated context provided in the prompt.
## Functional Requirements
1. **File Segregation:**
- Create a dedicated history file (e.g., `manual_slop_history.toml`) in the same directory as the main project configuration.
- The main `manual_slop.toml` will henceforth only store project settings, tracked files, and system prompts.
2. **Automatic Migration:**
- On application startup or project load, detect if the `discussion` key exists in `manual_slop.toml`.
- If found, automatically migrate all discussion entries to the new history sibling file and remove the key from the original file.
3. **Strict Blacklisting:**
- Hardcode the exclusion of the history TOML file in `mcp_client.py` and `aggregate.py`.
- The AI agent must be prevented from reading this file using the `read_file` or `search_files` tools.
4. **Backend Integration:**
- Update `ProjectManager` in `project_manager.py` to manage two distinct TOML files per project.
- Ensure the GUI correctly loads history from the new file while maintaining existing functionality.
## Non-Functional Requirements
- **Data Integrity:** Ensure no history is lost during the migration process.
- **Performance:** Minimize I/O overhead when saving history entries after each AI turn.
## Acceptance Criteria
- [ ] `manual_slop.toml` no longer contains the `discussion` array.
- [ ] A sibling `history.toml` (or similar) contains all historical and new discussion entries.
- [ ] The AI agent cannot access the history TOML file via its file tools (verification via tool call test).
- [ ] Discussion history remains visible in the GUI and is correctly included in the AI prompt context.
## Out of Scope
- Customizable blacklist via the UI.
- Support for cloud-based history storage.
+22 -6
View File
@@ -33,7 +33,7 @@ All tasks follow a strict lifecycle:
- Rerun tests to ensure they still pass after refactoring.
6. **Verify Coverage:** Run coverage reports using the project's chosen tools. For example, in a Python project, this might look like:
```bash
```powershell
pytest --cov=app --cov-report=html
```
Target: >80% coverage for new code. The specific tools and commands will vary by language and framework.
@@ -53,7 +53,7 @@ All tasks follow a strict lifecycle:
- **Step 9.1: Get Commit Hash:** Obtain the hash of the *just-completed commit* (`git log -1 --format="%H"`).
- **Step 9.2: Draft Note Content:** Create a detailed summary for the completed task. This should include the task name, a summary of changes, a list of all created/modified files, and the core "why" for the change.
- **Step 9.3: Attach Note:** Use the `git notes` command to attach the summary to the commit.
```bash
```powershell
# The note content from the previous step is passed via the -m flag.
git notes add -m "<note content>" <commit_hash>
```
@@ -164,21 +164,24 @@ Before marking any task complete, verify:
**AI AGENT INSTRUCTION: This section should be adapted to the project's specific language, framework, and build tools.**
### Setup
```bash
```powershell
# Example: Commands to set up the development environment (e.g., install dependencies, configure database)
# e.g., for a Node.js project: npm install
# e.g., for a Go project: go mod tidy
```
### Daily Development
```bash
```powershell
# Example: Commands for common daily tasks (e.g., start dev server, run tests, lint, format)
# e.g., for a Node.js project: npm run dev, npm test, npm run lint
# e.g., for a Go project: go run main.go, go test ./..., go fmt ./...
```
### Before Committing
```bash
```powershell
# Example: Commands to run all pre-commit checks (e.g., format, lint, type check, run tests)
# e.g., for a Node.js project: npm run check
# e.g., for a Go project: make check (if a Makefile exists)
@@ -187,18 +190,21 @@ Before marking any task complete, verify:
## Testing Requirements
### Unit Testing
- Every module must have corresponding tests.
- Use appropriate test setup/teardown mechanisms (e.g., fixtures, beforeEach/afterEach).
- Mock external dependencies.
- Test both success and failure cases.
### Integration Testing
- Test complete user flows
- Verify database transactions
- Test authentication and authorization
- Check form submissions
### Mobile Testing
- Test on actual iPhone when possible
- Use Safari developer tools
- Test touch interactions
@@ -208,6 +214,7 @@ Before marking any task complete, verify:
## Code Review Process
### Self-Review Checklist
Before requesting review:
1. **Functionality**
@@ -246,6 +253,7 @@ Before requesting review:
## Commit Guidelines
### Message Format
```
<type>(<scope>): <description>
@@ -255,6 +263,7 @@ Before requesting review:
```
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
@@ -264,7 +273,8 @@ Before requesting review:
- `chore`: Maintenance tasks
### Examples
```bash
```powershell
git commit -m "feat(auth): Add remember me functionality"
git commit -m "fix(posts): Correct excerpt generation for short posts"
git commit -m "test(comments): Add tests for emoji reaction limits"
@@ -288,6 +298,7 @@ A task is complete when:
## Emergency Procedures
### Critical Bug in Production
1. Create hotfix branch from main
2. Write failing test for bug
3. Implement minimal fix
@@ -296,6 +307,7 @@ A task is complete when:
6. Document in plan.md
### Data Loss
1. Stop all write operations
2. Restore from latest backup
3. Verify data integrity
@@ -303,6 +315,7 @@ A task is complete when:
5. Update backup procedures
### Security Breach
1. Rotate all secrets immediately
2. Review access logs
3. Patch vulnerability
@@ -312,6 +325,7 @@ A task is complete when:
## Deployment Workflow
### Pre-Deployment Checklist
- [ ] All tests passing
- [ ] Coverage >80%
- [ ] No linting errors
@@ -321,6 +335,7 @@ A task is complete when:
- [ ] Backup created
### Deployment Steps
1. Merge feature branch to main
2. Tag release with version
3. Push to deployment service
@@ -330,6 +345,7 @@ A task is complete when:
7. Monitor for errors
### Post-Deployment
1. Monitor analytics
2. Check error logs
3. Gather user feedback
-1
View File
@@ -1 +0,0 @@
Get-Content .env | ForEach-Object { $name, $value = $_.Split('=', 2); [Environment]::SetEnvironmentVariable($name, $value, "Process") }
View File