@stackmemoryai/stackmemory 1.2.0 → 1.2.2

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

@@ -0,0 +1,142 @@
+# 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
+
+## Documentation
+
+Quick reference (agent_docs/): linear_integration.md | mcp_server.md | database_storage.md | claude_hooks.md
+
+Full docs (docs/): principles.md | architecture.md | SPEC.md | API_REFERENCE.md | DEVELOPMENT.md | SETUP.md
+
+## Commands
+
+```bash
+npm run build|lint|lint:fix|test|test:run|linear:sync
+stackmemory capture|restore    # Session state handoff
+```
+
+## Working Directory
+
+PRIMARY: /Users/jwu/Dev/stackmemory | ALLOWED: All subdirectories | TEMP: /tmp
+
+## Validation (MUST DO)
+
+After code changes:
+1. `npm run lint` - fix errors AND warnings
+2. `npm run test:run` - verify no regressions
+3. `npm run build` - ensure compilation
+4. Run code to verify it works
+
+Test coverage:
+- New features require tests in `src/**/__tests__/`
+- Maintain or improve coverage (no untested code paths)
+- Critical paths: context management, handoff, Linear sync
+
+Never: Assume success | Skip testing | Use mock data as fallback
+
+## Git Rules (CRITICAL)
+
+- NEVER use `--no-verify` on commit/push
+- ALWAYS fix lint/test errors before pushing
+- Run `npm run lint && npm run test:run` before pushing
+- Commit format: `type(scope): message`
+- Branch naming: `feature/STA-XXX-desc` | `fix/STA-XXX-desc` | `chore/desc`
+
+## 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);
+}
+```
+
+Environment sources (check in order): .env | .env.local | ~/.zshrc | process.env
+
+Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
+
+## Deploy
+
+```bash
+# npm publish (uses NPM_TOKEN from .env)
+git stash -- scripts/gepa/
+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
+
+# Railway
+railway up
+
+# Pre-publish requires clean git — stash GEPA files first
+```
+
+## Task Delegation Model
+
+Route effort by complexity:
+
+**AUTOMATE** — Execute immediately, lint+test sufficient:
+- CRUD, boilerplate, formatting, simple transforms
+- Tool handler following existing pattern
+- Config additions (env var, feature flag)
+
+**STANDARD** — Normal workflow, lint+test+build:
+- Features, bug fixes, refactoring
+- Tests, docs, integration wiring
+
+**CAREFUL** — Review approach before implementation:
+- API/schema changes, migrations, auth flows
+- New integration patterns (MCP, 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 paths (FTS5, search scoring)
+- Breaking changes to MCP protocol or CLI
+
+**HUMAN** — Explicit approval required:
+- Security decisions, secret handling
+- Irreversible operations (migrations, schema drops)
+- Publishing (npm, Railway)
+
+Quality gates scale with tier — don't over-engineer AUTOMATE, don't under-review CAREFUL.
+
+## Workflow
+
+- 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 TodoWrite for 3+ steps or multiple requests
+- Keep one task in_progress at a time
+- Update task status immediately on completion
+- Ask 1-3 clarifying questions for complex commands (one at a time)

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

@@ -0,0 +1,172 @@
+# 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
+
+```
+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
+```
+
+## 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
+# 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
+
+# Integration
+npm run linear:sync    # Sync Linear
+
+# CLI
+stackmemory capture    # Save session state
+stackmemory restore    # Restore session
+```
+
+## 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
+
+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);
+}
+```
+
+**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
+```
+
+## 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]*\}/);