@stackmemoryai/stackmemory 1.2.1 → 1.2.4

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

@@ -1,166 +1,176 @@
-# ProvenantAI
+# StackMemory - Project Configuration
+
+## Project Structure
 
-## Reference Docs
 ```
-AGENTS.md                                # TDD workflow, checklists, guardrails
-PROMPT_PLAN.md                           # 20 implementation prompts
-docs/STYLE.md                            # Design system (Hatchet + Outliner)
-docs/business/ONE_PAGER.md               # Executive summary
-DEV_SPEC.md                              # Developer spec
-docs/reference/PROJECT.md                # Quick reference
-docs/business/VISION.md                  # Product vision + self-learning + model router
-docs/architecture/SYSTEM_INTEGRATION.md  # System connections (events, flows)
-docs/architecture/HEARTBEAT_DESIGN.md    # Task health + recovery
-docs/nudge-engine-design.md              # Proactive scanner alerts
-docs/architecture/WEBHOOK_SYSTEM_DESIGN.md  # External event publishing
-docs/VALUES.md                           # Company values
+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
+
+## Documentation
+
+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 dev|test|lint|migrate           # Development tasks
-docker-compose up -d                    # Start local DBs
-railway up                              # Deploy to Railway
+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
 ```
 
-## Stack
-Node.js + Express + PostgreSQL + Redis | Railway | Stripe + Salesforce + QuickBooks
+## Working Directory
 
-## Core Services (src/core/)
-monitoring-service | cache-service | queue-service | master-agent | api-validation
+- PRIMARY: /Users/jwu/Dev/stackmemory
+- ALLOWED: All subdirectories
+- TEMP: /tmp for temporary operations
 
-## Directory Structure
-```
-src/
-  api/ core/ features/ shared/ integrations/
-docs/ scripts/ docker/
-```
+## Required Validation
 
-## Git Workflow
-- **NEVER add Co-Authored-By lines** to commits
-- Pre-commit: runs lint + test suite
-- Commit format: `type(scope): message`
-- Deploy: `railway up --detach`
+After every code change:
+1. `npm run lint` - fix all errors AND warnings
+2. `npm run test:run` - verify no regressions
+3. `npm run build` - confirm compilation succeeds
+4. Execute code to confirm functionality
 
-## Architecture
-- **Provenance tracking**: every data point includes source + timestamp + lineage
-- **Multi-tenant**: container isolation per org
-- **Investigation replays**: stored in `data/investigation-replays/`
-- **StackMemory**: session/entity context layer (repurpose when KG lands)
+Test coverage requirements:
+- Write tests in `src/**/__tests__/` for all new features
+- Maintain or improve coverage - no untested code paths
+- Critical paths require tests: context management, handoff, Linear sync
 
-## Key Implementation Files
-```
-src/graph/client.ts                     # MCP client for Graphiti
-src/graph/service.ts                    # Graph ingest + enrich + search
-src/llm/adapter.js                      # LLM streaming + SYSTEM_PROMPT
-src/routes/query.js                     # Query endpoint + KG enrichment
-src/auth/auth.middleware.js             # Clerk + API key + test mode
-src/nudge/rule-engine.js                # 13 default rules + CRUD + eval
-src/nudge/nudge-engine.js               # Lifecycle + state machine + events
-src/nudge/delivery.js                   # Slack Block Kit + delivery
-src/integrations/slack/app.js           # OAuth v2 + token management
-scripts/create-stripe-products.js       # Stripe product creation
-scripts/seed-demo-data.js               # Demo nudge data
-dashboard-app/src/pages/pricing/        # 4-tier pricing UI
-```
+Do NOT: assume success | skip testing | use mock data as fallback
 
-## Current State
-- **20 prompts complete** (PROMPT_PLAN.md)
-- **80 test suites, 1547 tests** - all passing (37 unit, 30 core, 13 integrations)
-- **KG integrated** - commit 917f31e (FalkorDB + Graphiti MCP)
-- **Published**: @provenantai/cli@1.0.0
-- **Deployed**: Railway (health OK, DB connected)
-- **Bundle**: 236KB main + 346KB vendor (lazy routes)
-- **Pricing**: Free | Growth $999-1499 | Scale $2999-4499 | Enterprise custom
-- **Slack**: wired in index.js (conditional on SLACK_CLIENT_ID)
-- **Dashboard**: SlackSettings + Nudges page + E2E smoke tests
-
-## Knowledge Graph
-- **FalkorDB**: `falkordb/falkordb:latest` port 6380 (Redis-compatible)
-- **Graphiti**: `zepai/knowledge-graph-mcp:standalone` port 8100
-- **Protocol**: MCP Streamable HTTP (JSON-RPC + SSE) - NOT REST
-- **Ingestion**: fire-and-forget via `add_memory`, extraction runs in background
-- **Config**: `config/graphiti-falkordb.yaml` - Claude Haiku for LLM
-- **Performance**: 34ms avg, $0.00056/event
-- **Query integration**: GraphService.enrichRetrieval() when GRAPHITI_URL set
-- **Graph context**: prepended as first context_document, graceful fallback
-
-## Stripe Products (LIVE)
-```
-Growth:  prod_TyNYCJmlKbMdlz
-  Monthly $1,499:    price_1T0Qn8BjaxUVbh5VjC7BP0cS
-  Quarterly $2,997:  price_1T0Qn9BjaxUVbh5VYmugdPrF
-Scale:   prod_TyNY5SGKvVlbpo
-  Monthly $4,499:    price_1T0Qn9BjaxUVbh5ViK6vRmgn
-  Quarterly $8,997:  price_1T0Qn9BjaxUVbh5V1mBcTAJ0
+## Git Rules (CRITICAL)
+
+NEVER:
+- Use `--no-verify` on git push or commit
+- Push without fixing lint/test errors
+- Skip validation when pre-push hooks fail
+
+ALWAYS:
+- Fix underlying issues when hooks fail
+- Run `npm run lint && npm run test:run` before pushing
+- Use commit format: `type(scope): message`
+- Use branch naming: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
+
+## Task Management
+
+- Create TodoWrite for 3+ steps or multiple requests
+- Work on one task at a time (keep one in_progress)
+- Update task status immediately on completion
+
+## Security
+
+NEVER hardcode secrets. Use process.env with dotenv/config:
+
+```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);
+}
 ```
-Price IDs in `.env` + `dashboard-app/.env` (VITE_STRIPE_PRICE_*)
-
-## Clerk Auth
-- **Current**: test keys (pk_test_*, sk_test_*)
-- **Production setup**: `bash scripts/setup-clerk-production.sh`
-- **Webhook**: /api/webhooks/clerk (Svix verification required in prod)
-- **Status**: code production-ready, test mode blocked in production
-
-## Dashboard
-- **Chat**: `/api/v1/query` with SSE streaming
-- **Sidebar**: toggleable, time-grouped, backend persistence
-- **localStorage**: `provenantai:conversationId`, `sidebarOpen`, `onboarded`
-- **Vite**: `base: '/app/'` + BrowserRouter `basename="/app"`
-- **Dev auth**: `X-Test-Mode: true` bypasses Clerk
-- **Express**: `node src/index.js` on PORT=8080 (3000 = Rails)
-- **Build**: `bash -c 'cd dashboard-app && npx vite build'`
-
-## Slack Integration
-- **OAuth flow**: GET /api/integrations/slack/install → consent → callback
-- **DB**: `slack_installations` table (migration 030) - per-org bot tokens
-- **Service**: `src/integrations/slack/app.js` - createSlackAppService
-- **Delivery**: `src/nudge/delivery.js` - nudge:created listener, Block Kit formatter
-- **Routes**: install, callback, status, channel config, revoke
-- **Env**: SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_REDIRECT_URI
-- **Demo data**: `node scripts/seed-demo-data.js` (10 nudges)
-
-## Architecture Patterns
-- **DI**: all route factories accept `deps` objects
-- **Mocks**: MockPineconeAdapter, MockGmailConnectorClient, stub embeddings
-- **Queues**: Bull (not BullMQ)
-- **KMS**: AES-256-GCM shim via LOCAL_KMS_KEY
-- **Streaming**: adapter.streamLLM() → query/stream → ReadableStream
-- **Graph**: optional graphService dep, null when GRAPHITI_URL unset
-
-## Testing
-- **Framework**: Jest + SWC (`@swc/jest`), `@jest/globals` imports
-- **Mocks**: `mockDb = { query: jest.fn() }` via DI
-- **Fetch**: `global.fetch = mockFetch` + `jsonResponse()` helper
-- **Pre-commit**: lint + parallel test suite via concurrently
-- **Timeout guard**: Promise.race + .unref() timer in test/setup.js
-- **Supertest**: pass Express app directly (NOT server) - avoids port contention
-- **Redis**: skip eager connect in NODE_ENV=test; disconnect in afterAll
-
-### Parallel Test Execution
+
+Environment sources (check in order):
+1. .env file
+2. .env.local
+3. ~/.zshrc
+4. Process environment
+
+Block secret patterns: lin_api_* | lin_oauth_* | sk-* | npm_*
+
+## Deploy
+
 ```bash
-npm test                                 # 3 parallel processes (~9s vs 18s)
-test:unit       (37 suites, 615 tests)  # test/ dir
-test:core       (30 suites, 643 tests)  # src/(api|auth|billing|core|...)
-test:integrations (13 suites, 289 tests)  # src/integrations/
-test:all        (single-process, 4 workers)  # fallback
-```
-**After code changes**: run targeted sub-suite in background via Bash `run_in_background`
+# 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
 
-## GTM Content
-```
-docs/content/linkedin-pillar1-drafts.md          # 5 problem posts (ready)
-docs/content/gtm-launch-materials.md             # Schedule + Loom + outreach
-docs/business/CONTENT_INBOUND_STRATEGY.md        # Content/inbound playbook
-docs/business/FRACTIONAL_CMO_AGENT.md            # CMO Agent product brief
+# Railway
+railway up
+
+# Pre-publish checks require clean git status — stash GEPA files first
 ```
 
-## Next Actions
-1. Commit: SlackSettings, Nudges polish, smoke tests
-2. Clerk: swap to production keys (requires Clerk dashboard action)
-3. Slack: create app at api.slack.com, run migration 030
-4. Content: schedule posts in Typefully, record Loom demo
-5. Design partners: outreach to 3-5 ICP companies
-6. Attribution: add Google Ads + Meta connectors
+## Task Delegation Model
+
+Match effort to complexity:
+
+**AUTOMATE** — Execute immediately, lint+test only:
+- CRUD operations, boilerplate, formatting, simple transforms
+- Adding tool handler following existing switch/case pattern
+- Config additions (env var, feature flag)
+
+**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 coding:
+- API/schema changes, database migrations, auth flows
+- New integration patterns (MCP tools, webhook handlers)
+- Changes to frame-manager, sqlite-adapter, daemon lifecycle
+- Error handling chain modifications
+
+**ARCHITECT** — Plan mode required, explore 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 required:
+- Security-critical decisions, secret handling
+- Irreversible operations (data migrations, schema drops)
+- Publishing (npm publish, Railway deploy)
+
+Scale quality gates to tier. Don't over-engineer AUTOMATE tasks or under-review CAREFUL ones.
+
+## Workflow
 
-<!-- Sync docs/reference/PROJECT.md when verbose docs change -->
+- Check .env for API keys before asking user
+- Run `npm run linear:sync` after task completion
+- Use browser MCP for visual testing
+- Review recent commits and stackmemory.json at session start
+- Use subagents for multi-step tasks
+- Ask 1-3 clarifying questions for complex commands (one at a time)