@stackmemoryai/stackmemory 1.5.4 → 1.5.5

package/scripts/gepa/generations/gen-001/baseline.md

@@ -1,180 +1,144 @@
-# StackMemory - Project Configuration
+# CLAUDE.md
 
-## Project Structure
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-```
-src/
-  cli/           # CLI commands and entry point
-  core/          # Core business logic
-    context/     # Frame and context management
-    database/    # Database adapters (SQLite, ParadeDB)
-    digest/      # Digest generation
-    query/       # Query parsing and routing
-  integrations/  # External integrations (Linear, MCP)
-  services/      # Business services
-  skills/        # Claude Code skills
-  utils/         # Shared utilities
-scripts/         # Build and utility scripts
-config/          # Configuration files
-docs/            # Documentation
-```
-
-## Key Files
+## Project Overview
 
-- Entry: src/cli/index.ts
-- MCP Server: src/integrations/mcp/server.ts
-- Frame Manager: src/core/context/frame-manager.ts
-- Database: src/core/database/sqlite-adapter.ts
-- Snapshot: src/core/worktree/capture.ts
-- Preflight: src/core/worktree/preflight.ts
-- Conductor: src/cli/commands/orchestrator.ts
-- Shared Utils: src/core/utils/{git,text,fs}.ts
+Sol is the monorepo for **Rize**, an automatic time tracking application. The stack consists of:
+- **api/** - Rails 7.1 GraphQL backend (Ruby 3.3.5)
+- **web/** - Next.js 14 React web app (Node 22)
+- **electron/** - Electron desktop app (Node 22)
+- **services/** - Bun-based TypeScript event consumers/workers
+- **vanity/** - Webflow marketing site scripts (deprecated)
+- **voyager/** - Marketing website for home and landing pageas (Next.js)
+- **puppet/** - Puppeteer server for images/PDFs
+- **chrome/** - Chrome browser extension
+- **docs/** - Docusaurus documentation site
+- **zapier/** - Zapier integration
 
-## Detailed Guides
+## Development Commands
 
-Quick reference (agent_docs/):
-- linear_integration.md - Linear sync
-- mcp_server.md - MCP tools
-- database_storage.md - Storage
-- claude_hooks.md - Hooks
-
-Full documentation (docs/):
-- principles.md - Agent programming paradigm
-- architecture.md - Extension model and browser sandbox
-- SPEC.md - Technical specification
-- API_REFERENCE.md - API docs
-- DEVELOPMENT.md - Dev guide
-- SETUP.md - Installation
-
-## Commands
+### Starting Development Environment
+```bash
+# Start all services (requires iTerm2 on macOS)
+./scripts/run-dev.sh
+
+# Or start individually:
+cd api && hivemind Procfile.dev     # Rails + AnyCable + Sidekiq + Clockwork
+cd web && npm run dev               # Next.js dev server
+cd electron && npm run dev          # Electron with hot reload
+cd services && hivemind Procfile.dev # Bun services
+```
 
+### Docker Dependencies (api/docker-compose.yml)
 ```bash
-npm run build          # Compile TypeScript (esbuild)
-npm run lint           # ESLint check
-npm run lint:fix       # Auto-fix lint issues
-npm test               # Run Vitest (watch)
-npm run test:run       # Run tests once
-npm run linear:sync    # Sync with Linear
-
-# StackMemory CLI
-stackmemory capture    # Save session state for handoff
-stackmemory restore    # Restore from captured state
-stackmemory snapshot save  # Post-run context snapshot (alias: snap)
-stackmemory snapshot list  # List recent snapshots
-stackmemory preflight      # File overlap check for parallel tasks (alias: pf)
-stackmemory conductor start  # Autonomous Linear→worktree→agent orchestrator
+cd api && docker-compose up -d
+# TimescaleDB: localhost:15432
+# Redis: localhost:16379
+# Kafka: localhost:9092
+# MySQL: localhost:13306
 ```
 
-## Working Directory
+### Testing
+```bash
+# API (RSpec)
+cd api && bundle exec rspec
+cd api && bundle exec rspec spec/path/to/file_spec.rb      # Single file
+cd api && bundle exec rspec spec/path/to/file_spec.rb:42   # Single test at line
 
-- PRIMARY: /Users/jwu/Dev/stackmemory
-- ALLOWED: All subdirectories
-- TEMP: /tmp for temporary operations
+# Electron (Jest)
+cd electron && npm test
+cd electron && npm run test:watch
+cd electron && npm run test:coverage
 
-## Validation (MUST DO)
+# Web - no active tests (exits 0)
+```
 
-After code changes:
-1. `npm run lint` - fix any errors AND warnings
-2. `npm run test:run` - verify no regressions
-3. `npm run build` - ensure compilation
-4. Run code to verify it works
+### Building
+```bash
+cd api && bundle install && rake db:migrate
+cd web && npm run build       # Runs gql-gen, tailwind, next build
+cd electron && npm run build  # Electron Forge make
+cd services && bun install
+```
 
-Test coverage:
-- New features require tests in `src/**/__tests__/`
-- Maintain or improve coverage (no untested code paths)
-- Critical paths: context management, handoff, Linear sync
+### GraphQL Code Generation
+```bash
+cd web && npm run build       # Includes gql codegen
+cd electron && npm run dev    # Runs gql codegen as part of dev
+```
 
-Never: Assume success | Skip testing | Use mock data as fallback
+## Architecture
 
-## Git Rules (CRITICAL)
+### GraphQL API Structure
+The API exposes two GraphQL endpoints:
+- **api/v1** - Public API (OAuth consumers, Zapier)
+- **private/v1** - Private API (web, electron apps)
 
-- NEVER use `--no-verify` on git push or commit
-- ALWAYS fix lint/test errors before pushing
-- If pre-push hooks fail, fix the underlying issue
-- Run `npm run lint && npm run test:run` before pushing
-- Commit message format: `type(scope): message`
-- Branch naming: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
+Located at `api/app/graphql/{api,private}/v1/`
 
-## Task Management
+### Real-time Communication
+- **AnyCable** WebSocket server for subscriptions
+- ActionCable channels in `api/app/channels/`
+- WebSocket config: `api/config/cable.yml` and `api/config/anycable.yml`
 
-- Use TodoWrite for 3+ steps or multiple requests
-- Keep one task in_progress at a time
-- Update task status immediately on completion
+### Background Jobs
+- **Sidekiq** for async job processing (`api/config/sidekiq.yml`)
+- **Clockwork** for scheduled jobs (`api/config/clock.rb`)
 
-## Security
+### Event Streaming
+- **Kafka** for event publishing/consumption
+- Services consume events via `services/consumers/`
+- Kafka config: `api/config/initializers/kafka.rb`
 
-NEVER hardcode secrets - use process.env with dotenv/config
+### Databases
+- **Primary PostgreSQL** - Main application data
+- **TimescaleDB** - Time-series data (separate connection in `database.yml`)
+- **MySQL** - Legacy/external integrations
+- **Redis** - Caching, ActionCable, Sidekiq
 
-```javascript
-import 'dotenv/config';
-const API_KEY = process.env.LINEAR_API_KEY;
-if (!API_KEY) {
-  console.error('LINEAR_API_KEY not set');
-  process.exit(1);
-}
-```
+## Style Guidelines
 
-Environment sources (check in order):
-1. .env file
-2. .env.local
-3. ~/.zshrc
-4. Process environment
+### JavaScript/TypeScript
+- Use `test()` instead of `it()` in tests
+- Use `toBeCalled()` instead of `toHaveBeenCalledWith()` in jest assertions
 
-Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
+## LSP Setup (Code Intelligence)
 
-## Deploy
+Claude Code uses LSP plugins for go-to-definition, find-references, and real-time diagnostics.
 
-```bash
-# npm publish (uses NPM_TOKEN from .env, no OTP needed)
-git stash -- scripts/gepa/           # stash GEPA state (dirties working tree)
-NPM_TOKEN=$(grep '^NPM_TOKEN=' .env | cut -d= -f2) \
-  npm publish --registry https://registry.npmjs.org/ \
-  --//registry.npmjs.org/:_authToken="$NPM_TOKEN"
-git stash pop                         # restore GEPA state
+### Installed Plugins
+- **vtsls** (JS/TS) - `vtsls@claude-code-lsps` from boostvolt marketplace
+- **ruby-lsp** (Ruby) - `ruby-lsp@ruby-skills` + `ruby-skills@ruby-skills` from st0012 marketplace
 
-# Railway
-railway up
+### Prerequisites
+```bash
+# TypeScript/JS language server
+npm install -g @vtsls/language-server
 
-# Pre-publish checks require clean git status — stash GEPA files first
+# Ruby language server (use rbenv gem, not system)
+/Users/jwu/.rbenv/versions/3.3.5/bin/gem install ruby-lsp
 ```
 
-## Task Delegation Model
-
-Route effort by task complexity — not all code changes deserve equal scrutiny:
-
-**AUTOMATE** — Execute immediately, lint+test is sufficient:
-- CRUD operations, boilerplate, formatting, simple transforms
-- Adding a tool handler following existing switch/case pattern
-- Config additions (new env var, feature flag)
+### Known Issues
+- Official `typescript-lsp@claude-plugins-official` is broken (missing plugin.json) — use `vtsls@claude-code-lsps` instead
+- Ruby LSP launch script patched at `~/.claude/plugins/cache/ruby-skills/ruby-lsp/1.0.0/scripts/launch-ruby-lsp.sh` — macOS lacks GNU `timeout` which breaks the version manager detection. Patch hardcodes rbenv PATH.
+- Plugin auto-updates may overwrite the patch — re-apply if Ruby LSP stops working
 
-**STANDARD** — Normal workflow, lint+test+build:
-- Feature implementation, bug fixes, refactoring
-- New test coverage, documentation updates
-- Integration wiring (adding handler to server.ts dispatch)
-
-**CAREFUL** — Review approach before implementation:
-- API/schema changes, database migrations, auth flows
-- New integration patterns (MCP tools, webhook handlers)
-- Changes to frame-manager, sqlite-adapter, or daemon lifecycle
-- Anything touching error handling chains
-
-**ARCHITECT** — Plan mode required, explore existing patterns first:
-- New service boundaries, system integrations
-- Performance-critical paths (FTS5 queries, search scoring)
-- Breaking changes to MCP protocol or CLI interface
-
-**HUMAN** — Explicit user approval before any changes:
-- Security-critical decisions, secret handling
-- Irreversible operations (data migrations, schema drops)
-- Publishing (npm publish, Railway deploy)
+### Reinstall Commands
+```bash
+claude plugin marketplace add boostvolt/claude-code-lsps
+claude plugin install vtsls@claude-code-lsps
 
-Quality gates scale with tier — don't over-engineer AUTOMATE tasks, don't under-review CAREFUL ones.
+claude plugin marketplace add st0012/ruby-skills
+claude plugin install ruby-lsp@ruby-skills
+claude plugin install ruby-skills@ruby-skills
+```
 
-## Workflow
+## Key Configuration Files
 
-- Check .env for API keys before asking
-- Run npm run linear:sync after task completion
-- Use browser MCP for visual testing
-- Review recent commits and stackmemory.json on session start
-- Use subagents for multi-step tasks
-- Ask 1-3 clarifying questions for complex commands (one at a time)
+- `api/config/database.yml` - Database connections (primary + timescale)
+- `api/config/cable.yml` - AnyCable WebSocket config
+- `api/Procfile.dev` - Development processes (rails, anycable, sidekiq, clockwork)
+- `sol.code-workspace` - VS Code multi-folder workspace
+- Each project requires its own `.env` file (not in repo)

package/scripts/gepa/generations/gen-001/variant-a.md

@@ -1,176 +1 @@
-# StackMemory - Project Configuration
-
-## Project Structure
-
-```
-src/
-  cli/           # CLI commands and entry point
-  core/          # Core business logic
-    context/     # Frame and context management
-    database/    # Database adapters (SQLite, ParadeDB)
-    digest/      # Digest generation
-    query/       # Query parsing and routing
-  integrations/  # External integrations (Linear, MCP)
-  services/      # Business services
-  skills/        # Claude Code skills
-  utils/         # Shared utilities
-scripts/         # Build and utility scripts
-config/          # Configuration files
-docs/            # Documentation
-```
-
-## Key Files
-
-- Entry: `src/cli/index.ts`
-- MCP Server: `src/integrations/mcp/server.ts`
-- Frame Manager: `src/core/context/frame-manager.ts`
-- Database: `src/core/database/sqlite-adapter.ts`
-- Snapshot: `src/core/worktree/capture.ts`
-- Preflight: `src/core/worktree/preflight.ts`
-- Conductor: `src/cli/commands/orchestrator.ts`
-- Shared Utils: `src/core/utils/{git,text,fs}.ts`
-
-## Reference Docs
-
-Quick reference (`agent_docs/`):
-- `linear_integration.md` — Linear sync
-- `mcp_server.md` — MCP tools
-- `database_storage.md` — Storage
-- `claude_hooks.md` — Hooks
-
-Full docs (`docs/`):
-- `principles.md` — Agent programming paradigm
-- `architecture.md` — Extension model and browser sandbox
-- `SPEC.md` — Technical specification
-- `API_REFERENCE.md` — API docs
-- `DEVELOPMENT.md` — Dev guide
-- `SETUP.md` — Installation
-
-## Commands
-
-```bash
-npm run build          # Compile TypeScript (esbuild)
-npm run lint           # ESLint check
-npm run lint:fix       # Auto-fix lint issues
-npm test               # Run Vitest (watch)
-npm run test:run       # Run tests once
-npm run linear:sync    # Sync with Linear
-
-# StackMemory CLI
-stackmemory capture          # Save session state for handoff
-stackmemory restore          # Restore from captured state
-stackmemory snapshot save    # Post-run context snapshot (alias: snap)
-stackmemory snapshot list    # List recent snapshots
-stackmemory preflight        # File overlap check for parallel tasks (alias: pf)
-stackmemory conductor start  # Autonomous Linear→worktree→agent orchestrator
-```
-
-## Working Directory
-
-- PRIMARY: `/Users/jwu/Dev/stackmemory`
-- ALLOWED: All subdirectories
-- TEMP: `/tmp`
-
-## Validation (REQUIRED after every code change)
-
-1. `npm run lint` — fix all errors and warnings
-2. `npm run test:run` — confirm no regressions
-3. `npm run build` — confirm compilation succeeds
-4. Run the code to verify behavior
-
-Test coverage rules:
-- New features require tests in `src/**/__tests__/`
-- Maintain or improve coverage — no untested code paths
-- Critical paths: context management, handoff, Linear sync
-
-Do not: assume success | skip testing | use mock data as fallback
-
-## Git Rules (CRITICAL)
-
-- NEVER pass `--no-verify` to `git push` or `git commit`
-- Fix lint/test errors before pushing — never bypass pre-push hooks
-- Run `npm run lint && npm run test:run` before every push
-- Commit format: `type(scope): message`
-- Branch format: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
-
-## Task Management
-
-- Use TodoWrite for tasks with 3+ steps or multiple requests
-- Keep exactly one task `in_progress` at a time
-- Mark tasks complete immediately when done
-
-## Security
-
-Never hardcode secrets. Always use `process.env` with dotenv:
-
-```javascript
-import 'dotenv/config';
-const API_KEY = process.env.LINEAR_API_KEY;
-if (!API_KEY) {
-  console.error('LINEAR_API_KEY not set');
-  process.exit(1);
-}
-```
-
-Check env sources in order:
-1. `.env`
-2. `.env.local`
-3. `~/.zshrc`
-4. Process environment
-
-Block these patterns: `lin_api_*` | `lin_oauth_*` | `sk-*` | `npm_*`
-
-## Deploy
-
-```bash
-# npm publish (NPM_TOKEN from .env, no OTP required)
-git stash -- scripts/gepa/           # stash GEPA state (dirties working tree)
-NPM_TOKEN=$(grep '^NPM_TOKEN=' .env | cut -d= -f2) \
-  npm publish --registry https://registry.npmjs.org/ \
-  --//registry.npmjs.org/:_authToken="$NPM_TOKEN"
-git stash pop                         # restore GEPA state
-
-# Railway
-railway up
-
-# Note: pre-publish checks require clean git status — stash GEPA files first
-```
-
-## Task Delegation Model
-
-Match scrutiny to complexity:
-
-**AUTOMATE** — Run immediately; lint+test is enough:
-- CRUD, boilerplate, formatting, simple transforms
-- Adding a tool handler to an existing switch/case
-- Config additions (env vars, feature flags)
-
-**STANDARD** — Normal workflow; lint+test+build:
-- Feature work, bug fixes, refactoring
-- New tests, doc updates
-- Integration wiring (e.g., adding handler to `server.ts`)
-
-**CAREFUL** — Confirm approach before implementing:
-- API/schema changes, DB migrations, auth flows
-- New MCP tools or webhook handlers
-- Changes to `frame-manager`, `sqlite-adapter`, or daemon lifecycle
-- Any error handling chain modifications
-
-**ARCHITECT** — Enter plan mode; read existing patterns first:
-- New service boundaries or system integrations
-- Performance-critical paths (FTS5 queries, search scoring)
-- Breaking changes to MCP protocol or CLI interface
-
-**HUMAN** — Get explicit user approval before touching:
-- Security decisions, secret handling
-- Irreversible operations (data migrations, schema drops)
-- Publishing (`npm publish`, Railway deploy)
-
-## Workflow
-
-- Check `.env` for API keys before asking the user
-- Run `npm run linear:sync` after completing tasks
-- Use browser MCP for visual testing
-- On session start: review recent commits and `stackmemory.json`
-- Use subagents for multi-step tasks
-- Ask at most 1–3 clarifying questions for complex requests, one at a time
+API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"You have reached your specified API usage limits. You will regain access on 2026-04-01 at 00:00 UTC."},"request_id":"req_011CYrHCd5bajfrRXjhYqSFH"}