@stackmemoryai/stackmemory 1.2.1 → 1.2.2

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

@@ -1,119 +1,172 @@
-# ProvenantAI — CLAUDE.md
+# StackMemory - Project Configuration
+
+## Overview
+
+StackMemory is an agent programming platform with CLI, MCP server, and Linear integration.
+
+**Primary**: /Users/jwu/Dev/stackmemory  
+**Tech**: TypeScript, Node.js, SQLite, Vitest, ESLint, esbuild
+
+## Architecture
 
-## Quick Reference
 ```
-AGENTS.md                                # TDD workflow, checklists, guardrails
-docs/STYLE.md                            # Design system (Hatchet + Outliner)
-docs/business/ONE_PAGER.md               # Executive summary
-docs/business/VISION.md                  # Product vision + self-learning thesis
-DEV_SPEC.md|PROMPT_PLAN.md               # Dev spec + 20 staged prompts
-docs/architecture/{SYSTEM_INTEGRATION,HEARTBEAT_DESIGN,WEBHOOK_SYSTEM_DESIGN}.md
-docs/nudge-engine-design.md              # Proactive alerts
-docs/VALUES.md                           # Company values
-docs/reference/PROJECT.md                # Quick reference (sync with verbose docs)
+src/
+  cli/           # CLI entry (index.ts)
+  core/          # Business logic
+    context/     # Frame management (frame-manager.ts)
+    database/    # Storage adapters (sqlite-adapter.ts)
+    digest/      # Digest generation
+    query/       # Query routing
+  integrations/  # Linear, MCP (mcp/server.ts)
+  services/      # Business services
+  skills/        # Claude Code skills
+  utils/         # Shared utilities
 ```
 
-## Stack & Commands
+## Documentation
+
+**Quick reference** (agent_docs/):
+- linear_integration.md
+- mcp_server.md
+- database_storage.md
+- claude_hooks.md
+
+**Full docs** (docs/):
+- principles.md - Agent paradigm
+- architecture.md - Extension model
+- SPEC.md - Technical spec
+- API_REFERENCE.md
+- DEVELOPMENT.md
+- SETUP.md
+
+## Commands
+
 ```bash
-# Stack: Node/Express/PostgreSQL/Redis | Railway | Stripe/Salesforce/QuickBooks
-npm run dev|test|lint|migrate
-docker-compose up -d                # Local DBs
-railway up --detach                 # Deploy
-```
+# Build & Quality
+npm run build          # Compile (esbuild)
+npm run lint           # Check
+npm run lint:fix       # Auto-fix
+npm test               # Watch mode
+npm run test:run       # Run once
 
-## Core Principles [C:10]
-**Code First**: code>docs | simple→complex | action>explanation | do>plan
-**Security**: NEVER commit secrets|exec untrusted|expose PII|force push
-  ALWAYS validate input|parameterized queries|hash passwords
-  BLOCK ~/.ssh|~/.aws|/api[_-]?key|token|secret/i
-**ESM**: add .js to relative imports | use ts-node-lint-fixer on ERR_MODULE_NOT_FOUND
-**Reliability**: return undefined>throw | log+continue>crash | filter nulls
-**Style**: no emojis | comments only for complex logic | short names | concise output
-
-## Workflow [H:8-9]
-**Tasks**: TodoWrite for 3+ steps | one in_progress | update immediately
-**Files**: read before write | edit>write | no docs unless asked
-**Git**: status→branch→fetch→pull --rebase | clean commits | type(scope): message
-  Branches: feature/|fix/|chore/ prefix
-  NO Co-Authored-By lines
-**Validate**: lint→test→build→run | never assume success | maintain test coverage
-**Parallel**: independent tool calls in one message | sequential only for dependencies
-**Recovery**: try alt→explain→suggest | never silent fail
+# Integration
+npm run linear:sync    # Sync Linear
 
-## Architecture
-**Core** (src/core/): monitoring-service|cache-service|queue-service|master-agent|api-validation
-**Structure**: src/{api,core,features,shared,integrations} | docs/ | scripts/ | docker/
-**Patterns**: DI via deps objects | Mock providers in tests | Bull queues | AES-256-GCM KMS
-**Provenance**: every data point = source + timestamp + lineage | multi-tenant isolation
-**SSE**: adapter.streamLLM() → query/stream → frontend ReadableStream
-**Graph**: optional graphService in query router (null when GRAPHITI_URL unset)
-
-## Standards [H:8]
-**Design**: KISS|YAGNI|SOLID | <20 lines/fn | <5 complexity
-**Testing**: Jest+SWC | @jest/globals imports | DB/fetch mocks via DI
-  Supertest: pass Express app (NOT server)
-  Redis: skip connect in NODE_ENV=test
-  afterAll: Promise.race + .unref() timer
-  Parallel suites: test:unit|test:core|test:integrations (~9s vs 18s)
-  **After code changes**: run targeted sub-suite in background
-**Coverage**: maintain or improve | no untested paths
-
-## Key Context
-- All 20 PROMPT_PLAN.md prompts complete | 80 suites, 1547 tests passing
-- KG: FalkorDB port 6380 + Graphiti MCP port 8100 | MCP protocol (not REST)
-- @provenantai/cli@1.0.0 published | Railway deployed | Bundle: 236KB+346KB
-- Stripe: Growth (prod_TyNYCJmlKbMdlz) $1499/mo | Scale (prod_TyNY5SGKvVlbpo) $4499/mo
-- Clerk: test keys active | production validator: scripts/setup-clerk-production.sh
-- Dashboard: /app/ base | SSE to /api/v1/query | Sidebar in localStorage
-- Slack: OAuth v2 (migration 030) | delivery.js listens nudge:created | demo: seed-demo-data.js
-
-## Key Files
-```
-src/graph/{client.ts,service.ts}         # MCP client + graph logic
-src/llm/adapter.js                       # SYSTEM_PROMPT + streaming
-src/routes/query.js                      # Query + KG enrichment
-src/auth/auth.middleware.js              # Clerk + API key + test mode
-src/nudge/{rule-engine,nudge-engine,delivery}.js  # Rules + lifecycle + Slack
-src/integrations/slack/app.js            # OAuth v2 + token mgmt
-scripts/{create-stripe-products,seed-demo-data}.js
-dashboard-app/src/pages/{pricing/PricingPage,checkout/*}.tsx
-docs/content/{linkedin-pillar1-drafts,gtm-launch-materials}.md
-docs/business/{CONTENT_INBOUND_STRATEGY,FRACTIONAL_CMO_AGENT}.md
+# CLI
+stackmemory capture    # Save session state
+stackmemory restore    # Restore session
 ```
 
-## Design System (docs/STYLE.md)
-- Layout: 208px sidebar | inset shadow main | shadow-soft variants
-- Type: 10-24px (no text-lg+ in app) | tabular-nums | Inter/SF Mono | font-mono headers
-- Color: slate/zinc | brand-600 blue | rose accent CTAs
-- Anti-patterns: no @apply sprawl | no inline hex | no shadow-md+ | max rounded-xl
+## Validation Checklist
+
+After EVERY code change:
+
+1. **Lint**: `npm run lint` - fix ALL errors AND warnings
+2. **Test**: `npm run test:run` - verify no regressions
+3. **Build**: `npm run build` - ensure compilation
+4. **Run**: Execute code to verify functionality
+
+**Test coverage**:
+- New features require tests in `src/**/__tests__/`
+- Maintain or improve coverage (no untested paths)
+- Critical: context management, handoff, Linear sync
+
+**Never**: Assume success | Skip testing | Use mock fallbacks
+
+## Git Workflow
+
+**Commit format**: `type(scope): message`  
+**Branch naming**: `feature/STA-XXX-desc` | `fix/STA-XXX-desc` | `chore/desc`
+
+**Critical rules**:
+- NEVER use `--no-verify` on commit/push
+- ALWAYS fix lint/test errors before pushing
+- Run `npm run lint && npm run test:run` before pushing
+- If pre-push hooks fail, fix the underlying issue
+
+## Task Delegation Model
 
-## Output Format
-**Session Summary**:
+Route effort by complexity:
+
+### AUTOMATE
+Execute immediately, lint+test is sufficient:
+- CRUD, boilerplate, formatting, simple transforms
+- Tool handler following existing switch/case
+- Config additions (env var, feature flag)
+
+### STANDARD
+Normal workflow, lint+test+build:
+- Features, bug fixes, refactoring
+- Test coverage, documentation
+- Integration wiring (server.ts dispatch)
+
+### CAREFUL
+Review approach before implementation:
+- API/schema changes, database migrations, auth
+- New integration patterns (MCP tools, webhooks)
+- Changes to frame-manager, sqlite-adapter, daemon lifecycle
+- Error handling chains
+
+### ARCHITECT
+Plan mode required, explore patterns first:
+- New service boundaries, system integrations
+- Performance-critical (FTS5 queries, search scoring)
+- Breaking changes (MCP protocol, CLI interface)
+
+### HUMAN
+Explicit approval before changes:
+- Security decisions, secret handling
+- Irreversible operations (migrations, schema drops)
+- Publishing (npm, Railway)
+
+## 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);
+}
 ```
-Actual vs estimated | variance %
-Completed: N/M tasks | files modified | commits
-Deliverables | blockers | next actions
+
+**Env sources** (check in order):
+1. .env file
+2. .env.local
+3. ~/.zshrc
+4. Process environment
+
+**Block patterns**: lin_api_* | lin_oauth_* | sk-* | npm_*
+
+## Deployment
+
+```bash
+# npm publish (uses NPM_TOKEN from .env, no OTP)
+git stash -- scripts/gepa/           # stash GEPA state
+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
 ```
-**Communication**: concise | bullets>paragraphs | <4 lines | structured
-**Pushback**: "Simpler: X" | "Risk: Y" | "Consider: Z"
-**Questions**: 1-3 max | one at a time | no time estimates
-
-## Token Budget (Think Mode)
-[NONE] single file, <10 lines
-[THINK] multi-file, standard | ~4K
-[HARD] architecture, complex | ~10K
-[ULTRA] critical redesign | ~32K
-
-## Auto-Activate
-[FILES] *.tsx→frontend | *.sql→data | Docker→devops | *.test→qa
-[KEYWORDS] bug/error→debugger | optimize→perf | secure→security
-
-## Next Priorities (Memory)
-- Commit uncommitted agent work (SlackSettings, Nudges polish, smoke tests)
-- Clerk: swap to production keys (user action in dashboard)
-- Slack: create app at api.slack.com, run migration 030
-- Content: schedule pillar posts in Typefully, record Loom demo
-- Design partners: outreach to 3-5 ICP companies
-- Ad platform connectors: Google Ads / Meta for attribution story
-
-<!-- Update docs/reference/PROJECT.md when verbose docs change -->
+
+## Task Management
+
+- Use TodoWrite for 3+ steps or multiple requests
+- Keep one task in_progress at a time
+- Update status immediately on completion
+
+## Workflow Tips
+
+- 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)

package/scripts/gepa/hooks/reflect.js

@@ -9,9 +9,51 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { execSync } from 'child_process';
+import { spawn } from 'child_process';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = path.resolve(__dirname, '../../..');
+
+// Load .env from project root
+const envPath = path.join(PROJECT_ROOT, '.env');
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+    const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+    if (match && !process.env[match[1]]) {
+      process.env[match[1]] = match[2].replace(/^["']|["']$/g, '');
+    }
+  }
+}
+
+/**
+ * Call Claude CLI via spawn (stdin pipe, no shell interpolation)
+ */
+function spawnClaude(prompt) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('claude', ['--print'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env },
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (d) => (stdout += d));
+    child.stderr.on('data', (d) => (stderr += d));
+
+    child.on('close', (code) => {
+      if (code !== 0 && !stdout)
+        return reject(new Error(stderr || `claude exited ${code}`));
+      resolve(stdout);
+    });
+
+    child.on('error', reject);
+
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
 const GEPA_DIR = path.join(__dirname, '..');
 const RESULTS_DIR = path.join(GEPA_DIR, 'results');
 const GENERATIONS_DIR = path.join(GEPA_DIR, 'generations');
@@ -212,10 +254,7 @@ Format as JSON:
 }`;
 
   try {
-    const result = execSync(
-      `echo ${JSON.stringify(reflectionPrompt)} | claude --print`,
-      { encoding: 'utf8', maxBuffer: 10 * 1024 * 1024 }
-    );
+    const result = await spawnClaude(reflectionPrompt);
 
     // Parse JSON from response
     const jsonMatch = result.match(/\{[\s\S]*\}/);