@stackmemoryai/stackmemory 1.2.1 → 1.2.4

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

@@ -1,237 +1,266 @@
-# CLAUDE.md [compact]
+# StackMemory - Project Configuration
+
+## Project Structure
 
-## Refs
 ```
-~/.claude/MCP.md|PERSONAS.md|STACKMEMORY.md
-~/.claude/agent_docs/*.compact.md (on-demand)
+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
+
+## Detailed Guides
+
+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
-```
-build|lint|lint:fix|test|test:run
-git status|diff|log --oneline -10
-npx tsc --noEmit|npm run format
+
+```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
 ```
 
-## Core
-[PRINCIPLE]code>docs|simple→complex|security first|evidence-based
-[COMM]concise|symbols>prose|bullets>paragraphs|<4 lines
-[WORKFLOW]TodoWrite(3+)→execute→update
-[GIT]clean commits|type(scope): message|feature/|fix/|chore/ prefix
-[STACK]React/TS/Vite|Node/Express/PG|Git/ESLint/Jest
-
-## Think
-[NONE]single file,<10 lines
-[THINK]multi-file,standard|~4K
-[HARD]architecture,complex|~10K
-[ULTRA]critical redesign|~32K
-
-## Critical [C:10]
-[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
+## Working Directory
 
-<example>
-❌ BAD:
-```js
-db.query(`SELECT * FROM users WHERE id = ${userId}`)
-```
-✅ GOOD:
-```js
-db.query('SELECT * FROM users WHERE id = $1', [userId])
-```
-</example>
+- PRIMARY: /Users/jwu/Dev/stackmemory
+- ALLOWED: All subdirectories
+- TEMP: /tmp for temporary operations
+
+## Validation (MUST DO)
 
-[ESM]add .js to relative imports|use ts-node-lint-fixer agent on ERR_MODULE_NOT_FOUND
+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
 
 <example>
-❌ BAD:
-```ts
-import { foo } from './bar'
-```
-✅ GOOD:
-```ts
-import { foo } from './bar.js'
-```
+# After adding a new MCP tool handler
+npm run lint && npm run test:run && npm run build
+# Then test the tool:
+echo '{"method":"tools/call","params":{"name":"your_tool"}}' | node dist/integrations/mcp/server.js
 </example>
 
-[ERROR]return undefined>throw|log+continue>crash|filter nulls
+Test coverage:
+- New features require tests in `src/**/__tests__/`
+- Maintain or improve coverage (no untested code paths)
+- Critical paths: context management, handoff, Linear sync
 
 <example>
-❌ BAD:
-```js
-function getUser(id) {
-  if (!id) throw new Error('No ID')
-  return users.find(u => u.id === id)
-}
-```
-✅ GOOD:
-```js
-function getUser(id) {
-  if (!id) return undefined
-  return users.find(u => u.id === id)
-}
-```
+# New feature: src/core/context/frame-deduplicator.ts
+# Required: src/core/context/__tests__/frame-deduplicator.test.ts
+# Test both happy path and edge cases (empty input, duplicates, conflicts)
 </example>
 
-[CODE]no emojis|comments only complex logic|short names
+Never: Assume success | Skip testing | Use mock data as fallback
 
-<example>
-❌ BAD:
-```js
-// This function gets the user from the database
-function getUserFromDatabase(userId) { ... }
-```
-✅ GOOD:
-```js
-function getUser(id) { ... }
-// Only comment complex parts:
-const hash = await bcrypt.hash(pwd, 10) // 10 rounds for security/perf balance
-```
-</example>
+## Git Rules (CRITICAL)
 
-## High [H:8-9]
-[EFFICIENCY]do>explain|action>ceremony|parallel>sequential
+- 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`
 
 <example>
-❌ BAD: "I'll read file A, then file B, then file C..."
-✅ GOOD: [Read A, Read B, Read C in parallel]
+# Good commits:
+feat(mcp): add search_frames tool for context retrieval
+fix(linear): handle null assignee in webhook handler
+chore(deps): upgrade better-sqlite3 to 11.8.0
+
+# Good branches:
+feature/STA-123-add-digest-export
+fix/STA-456-frame-timestamp-parsing
+chore/upgrade-typescript-5.3
 </example>
 
-[GIT]status→branch→fetch→pull --rebase|type(scope): message
+## Task Management
+
+- Use TodoWrite for 3+ steps or multiple requests
+- Keep one task in_progress at a time
+- Update task status immediately on completion
 
 <example>
-✅ GOOD commit messages:
-- feat(auth): add JWT token refresh
-- fix(api): handle null responses
-- chore(deps): bump express to 4.18
+# Multi-step task requires TodoWrite:
+User: "Add Graphiti integration with Linear bridge"
+1. Create TodoWrite with 4 tasks:
+   - Research Graphiti API patterns
+   - Implement LinearGraphitiBridge class
+   - Add webhook handler for Linear events
+   - Write integration tests
+2. Mark task 1 in_progress, complete it
+3. Mark task 2 in_progress, etc.
 </example>
 
-[RECOVERY]try alt→explain→suggest next|never silent fail
+## Security
+
+NEVER hardcode secrets - use process.env with dotenv/config
 
 <example>
-❌ BAD: Test fails → retry same command → retry again
-✅ GOOD: Test fails → check logs → try different approach → explain issue
+// ✓ CORRECT
+import 'dotenv/config';
+const API_KEY = process.env.LINEAR_API_KEY;
+if (!API_KEY) {
+  console.error('LINEAR_API_KEY not set');
+  process.exit(1);
+}
+
+// ✗ WRONG
+const API_KEY = 'lin_api_abc123def456';
 </example>
 
-[SESSION]track edits/corrections/paths|cache versions/locations
+Environment sources (check in order):
+1. .env file
+2. .env.local
+3. ~/.zshrc
+4. Process environment
 
-## Standards
-[TASK]TodoWrite 3+|one in_progress|update immediate
+Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
 
 <example>
-✅ GOOD workflow:
-1. User asks to add feature
-2. TodoWrite: ["Design API", "Implement handler", "Add tests", "Update docs"]
-3. TaskUpdate task1 → in_progress
-4. Complete work
-5. TaskUpdate task1 → completed
-6. TaskUpdate task2 → in_progress
+# If you see this pattern, STOP and use env vars:
+const token = 'lin_api_...';
+const apiKey = 'sk-...';
+const npmToken = 'npm_...';
 </example>
 
-[DESIGN]KISS|YAGNI|SOLID|<20 lines/fn|<5 complexity
+## Deploy
 
-<example>
-❌ BAD:
-```js
-function processUserDataWithValidationAndTransformation(user, options) {
-  // 50 lines of mixed concerns
-}
-```
-✅ GOOD:
-```js
-function validateUser(user) { ... }     // 8 lines
-function transformUser(user) { ... }   // 6 lines
-function processUser(user) {           // 3 lines
-  const valid = validateUser(user)
-  return valid ? transformUser(user) : null
-}
+```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
+
+# Railway
+railway up
+
+# Pre-publish checks require clean git status — stash GEPA files first
 ```
-</example>
 
-[FILES]read before write|edit>write|no docs unless asked
+## Task Delegation Model
 
-<example>
-❌ BAD: User asks to update function → Write entire new file
-✅ GOOD: User asks to update function → Read file → Edit specific function
-</example>
+Route effort by task complexity — not all code changes deserve equal scrutiny:
 
-[VALIDATE]lint→test→build→run|never assume success
+**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)
 
 <example>
-✅ GOOD workflow:
-1. Edit code
-2. `npm run lint` → check output
-3. `npm test` → verify passing
-4. `npm run build` → ensure clean build
-5. Only then mark task complete
+# AUTOMATE tier example:
+User: "Add a new MCP tool for listing frames by tag"
+Action: Add case to server.ts switch, follow existing pattern, lint+test
 </example>
 
-[COVERAGE]maintain or improve test coverage|no untested code paths
+**STANDARD** — Normal workflow, lint+test+build:
+- Feature implementation, bug fixes, refactoring
+- New test coverage, documentation updates
+- Integration wiring (adding handler to server.ts dispatch)
 
 <example>
-❌ BAD: Add new route without tests
-✅ GOOD: Add new route + unit test + integration test
+# STANDARD tier example:
+User: "Fix the digest generation to include frame metadata"
+Action: Modify digest-generator.ts, add tests, lint+test+build, verify output
 </example>
 
-## Style
-[OUTPUT]concise|structured|actionable
+**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
 
 <example>
-❌ BAD: "I've made some changes to the authentication system to improve security..."
-✅ GOOD: "Added JWT refresh tokens in src/auth/tokens.js:45"
+# CAREFUL tier example:
+User: "Add a new column to frames table for priority scoring"
+Action: Read schema, check migrations, discuss ALTER TABLE vs rebuild, plan rollback
 </example>
 
-[PUSHBACK]"Simpler: X"|"Risk: Y"|"Consider: Z"
+**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
 
 <example>
-User: "Add Redis caching to all endpoints"
-✅ GOOD response: "Risk: premature optimization. Consider: profile first, cache hot paths only"
+# ARCHITECT tier example:
+User: "Integrate Graphiti knowledge graph with existing frame storage"
+Action: EnterPlanMode, explore frame-manager.ts, research Graphiti API, design bridge layer
 </example>
 
-[QUESTIONS]1-3 clarifying|one at a time|no time estimates
+**HUMAN** — Explicit user approval before any changes:
+- Security-critical decisions, secret handling
+- Irreversible operations (data migrations, schema drops)
+- Publishing (npm publish, Railway deploy)
 
 <example>
-❌ BAD: "This will take 2-3 hours. Should I add error handling, logging, tests, docs, and type safety?"
-✅ GOOD: "Add error handling for network failures?"
+# HUMAN tier example:
+User: "Publish v1.3.0 to npm"
+Action: Ask "Ready to publish? This will run npm publish with NPM_TOKEN." Wait for approval.
 </example>
 
-## Summary Format
-```
-Session: actual vs estimated|variance %
-Completed: N/M tasks|files modified|commits
-Outcomes: deliverables|blockers|next actions
-```
+Quality gates scale with tier — don't over-engineer AUTOMATE tasks, don't under-review CAREFUL ones.
 
-<example>
-✅ GOOD summary:
-```
-Completed: 3/4 tasks | 7 files | 2 commits
-Outcomes: Auth refresh implemented, tests passing
-Blockers: Redis connection requires env var
-Next: Add REDIS_URL to .env, deploy to staging
-```
-</example>
+## Workflow
 
-## Auto-Activate
-[FILES]*.tsx→frontend|*.sql→data|Docker→devops|*.test→qa
-[KEYWORDS]bug/error→debugger|optimize→perf|secure→security
+- 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)
 
 <example>
-User shares error.tsx → automatically apply frontend patterns
-User mentions "slow query" → automatically consider performance context
+# Session start workflow:
+1. Read stackmemory.json for project state
+2. Run: git log --oneline -5
+3. Check git status for uncommitted work
+4. If user mentions Linear task, run: npm run linear:sync
+5. Proceed with user request
 </example>
 
-## Expand (read on match)
-[AGENTIC]multi-agent→AGENTIC_CODING.compact.md
-[CONTEXT]token budget→CONTEXT_MANAGEMENT.compact.md
-[TOOLS]parallel tools→TOOL_USE.compact.md
-[HORIZON]multi-session→LONG_HORIZON.compact.md
-[PROMPTS]prompt design→PROMPT_ENGINEERING.compact.md
-[BUILD]npm build|esbuild|tsc→building_the_project.md
-[CODE]conventions|naming|imports→code_conventions.md
-[TEST]vitest|jest|test:run→running_tests.md
-[OVERVIEW]agent docs|guides→OVERVIEW.md
-
-~150t|v4.4.0-compact
+<example>
+# Complex command clarification:
+User: "Optimize the search performance"
+Response: "Which search path should I focus on? (1) FTS5 queries, (2) Hybrid search scoring, or (3) Database indexes?"
+# Wait for answer before proceeding
+</example>

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

@@ -1,61 +1,142 @@
-# ProvenantAI
+# StackMemory - Project Configuration
+
+## Project Structure
 
-## Refs
 ```
-AGENTS.md                                # Agent workflow + guardrails
-PROMPT_PLAN.md                           # 20 staged prompts
-docs/STYLE.md                            # Design system (Hatchet + Outliner)
-docs/business/ONE_PAGER.md|VISION.md     # Executive summary + vision
-DEV_SPEC.md                              # Developer spec
-docs/reference/PROJECT.md                # Quick reference
-docs/architecture/SYSTEM_INTEGRATION.md  # System connections
-docs/architecture/HEARTBEAT_DESIGN.md|WEBHOOK_SYSTEM_DESIGN.md
-docs/nudge-engine-design.md              # Proactive alerts
-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 | 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 run dev|test|lint|migrate
-docker-compose up -d; railway up         # Local DBs; Deploy
+# 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
 ```
 
-## Stack
-Node/Express/PostgreSQL/Redis | Railway | Stripe/Salesforce/QuickBooks
+## Task Delegation Model
 
-## Structure
-src/api|core|features|shared|integrations | docs/ | scripts/ | docker/
+Route effort by complexity:
 
-## Key Context
-- Provenance tracking: source + timestamp + lineage on all data
-- Multi-tenant container isolation
-- Investigation replays: data/investigation-replays/
-- StackMemory: security layer (future session/entity context bridge on KG)
+**AUTOMATE** — Execute immediately, lint+test sufficient:
+- CRUD, boilerplate, formatting, simple transforms
+- Tool handler following existing pattern
+- Config additions (env var, feature flag)
 
-## Git
-- No "Co-Authored-By" lines
-- Pre-commit: lint + test (3 parallel suites: unit/core/integrations)
-- Commit format: type(scope): message
+**STANDARD** — Normal workflow, lint+test+build:
+- Features, bug fixes, refactoring
+- Tests, docs, integration wiring
 
-## Critical Rules
-[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
+**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
 
-[ESM] Add .js to relative imports | use ts-node-lint-fixer on ERR_MODULE_NOT_FOUND
-[ERROR] return undefined>throw | log+continue>crash | filter nulls
-[CODE] no emojis | comments only complex logic | short names
+**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
-[EFFICIENCY] do>explain | action>ceremony | parallel>sequential
-[TASK] TodoWrite 3+ | one in_progress | update immediate
-[DESIGN] KISS|YAGNI|SOLID | <20 lines/fn | <5 complexity
-[FILES] read before write | edit>write | no docs unless asked
-[VALIDATE] lint→test→build→run | never assume success
-[COVERAGE] maintain or improve | no untested paths
-
-## Style
-[OUTPUT] concise | structured | actionable | <4 lines default
-[PUSHBACK] "Simpler: X" | "Risk: Y" | "Consider: Z"
-[QUESTIONS] 1-3 clarifying | one at a time | no time estimates
+
+- 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)