@stackmemoryai/stackmemory 1.5.2 → 1.5.4

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

@@ -25,6 +25,10 @@ docs/            # Documentation
 - 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
 
 ## Detailed Guides
 
@@ -55,6 +59,10 @@ 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
@@ -72,10 +80,11 @@ After code changes:
 4. Run code to verify it works
 
 <example>
-# 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
+# Correct validation sequence after editing src/core/context/frame-manager.ts:
+$ npm run lint        # → 0 errors, 0 warnings
+$ npm run test:run    # → all tests pass (including search-benchmark smoke)
+$ npm run build       # → dist/ updated, no TS errors
+$ stackmemory snapshot save  # → verify feature works end-to-end
 </example>
 
 Test coverage:
@@ -84,9 +93,14 @@ Test coverage:
 - Critical paths: context management, handoff, Linear sync
 
 <example>
-# 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)
+# New feature: adding a getFrameCount() method to FrameManager
+# → requires test in src/core/context/__tests__/frame-manager.test.ts
+it('getFrameCount returns correct count after adding frames', () => {
+  const mgr = new FrameManager(db);
+  mgr.addFrame({ content: 'a' });
+  mgr.addFrame({ content: 'b' });
+  expect(mgr.getFrameCount()).toBe(2);
+});
 </example>
 
 Never: Assume success | Skip testing | Use mock data as fallback
@@ -101,15 +115,20 @@ Never: Assume success | Skip testing | Use mock data as fallback
 - Branch naming: `feature/STA-XXX-description` | `fix/STA-XXX-description` | `chore/description`
 
 <example>
-# 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
+# Good commit messages:
+feat(mcp): add get_frame_count tool to server
+fix(sqlite): correct BM25 score negation in hybrid search
+chore(deps): bump better-sqlite3 to 9.4.3
+refactor(context): extract frame deduplication to utils
+
+# Good branch names:
+feature/STA-123-fts5-hybrid-search
+fix/STA-456-timer-leak-promise-race
+chore/update-vitest-config
+
+# Bad — never do these:
+git commit --no-verify -m "wip"
+git push --force origin main
 </example>
 
 ## Task Management
@@ -119,32 +138,37 @@ chore/upgrade-typescript-5.3
 - Update task status immediately on completion
 
 <example>
-# 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.
+# User asks: "Add FTS5 search, wire it to MCP, and write tests"
+# → 3+ steps: use TodoWrite
+TodoWrite([
+  { id: '1', content: 'Add FTS5 search method to sqlite-adapter', status: 'pending' },
+  { id: '2', content: 'Wire search to MCP tool handler in server.ts', status: 'pending' },
+  { id: '3', content: 'Write tests in __tests__/sqlite-adapter.test.ts', status: 'pending' },
+])
+# Complete step 1 → update status to 'completed' before starting step 2
 </example>
 
 ## Security
 
 NEVER hardcode secrets - use process.env with dotenv/config
 
-<example>
-// ✓ CORRECT
+```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);
 }
+```
 
-// ✗ WRONG
-const API_KEY = 'lin_api_abc123def456';
+<example>
+// BAD — never do this:
+const client = new LinearClient({ apiKey: 'lin_api_abc123xyz' });
+
+// GOOD:
+const apiKey = process.env.LINEAR_API_KEY;
+if (!apiKey) throw new Error('LINEAR_API_KEY not set');
+const client = new LinearClient({ apiKey });
 </example>
 
 Environment sources (check in order):
@@ -155,13 +179,6 @@ Environment sources (check in order):
 
 Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
 
-<example>
-# If you see this pattern, STOP and use env vars:
-const token = 'lin_api_...';
-const apiKey = 'sk-...';
-const npmToken = 'npm_...';
-</example>
-
 ## Deploy
 
 ```bash
@@ -188,9 +205,10 @@ Route effort by task complexity — not all code changes deserve equal scrutiny:
 - Config additions (new env var, feature flag)
 
 <example>
-# 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
+# AUTOMATE: adding a new MCP tool that follows the existing switch/case pattern
+case 'get_frame_by_id':
+  return { frame: await frameManager.getById(args.id) };
+# → just add the case, lint, test. No design review needed.
 </example>
 
 **STANDARD** — Normal workflow, lint+test+build:
@@ -199,9 +217,8 @@ Action: Add case to server.ts switch, follow existing pattern, lint+test
 - Integration wiring (adding handler to server.ts dispatch)
 
 <example>
-# STANDARD tier example:
-User: "Fix the digest generation to include frame metadata"
-Action: Modify digest-generator.ts, add tests, lint+test+build, verify output
+# STANDARD: fixing a bug where snapshot list shows stale entries
+# → read the relevant files, understand root cause, fix, lint+test+build
 </example>
 
 **CAREFUL** — Review approach before implementation:
@@ -211,9 +228,10 @@ Action: Modify digest-generator.ts, add tests, lint+test+build, verify output
 - Anything touching error handling chains
 
 <example>
-# 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
+# CAREFUL: adding a new column to the frames table
+# → read sqlite-adapter.ts and schema_version migration pattern first
+# → plan the migration (increment schema_version, ALTER TABLE or recreate)
+# → confirm approach with user if destructive
 </example>
 
 **ARCHITECT** — Plan mode required, explore existing patterns first:
@@ -222,9 +240,10 @@ Action: Read schema, check migrations, discuss ALTER TABLE vs rebuild, plan roll
 - Breaking changes to MCP protocol or CLI interface
 
 <example>
-# ARCHITECT tier example:
-User: "Integrate Graphiti knowledge graph with existing frame storage"
-Action: EnterPlanMode, explore frame-manager.ts, research Graphiti API, design bridge layer
+# ARCHITECT: replacing LIKE-based search with hybrid FTS5+BM25
+# → enter plan mode, read sqlite-adapter.ts + search-benchmark.test.ts
+# → understand current scoring thresholds, BM25 sign conventions
+# → design schema migration, write plan, get approval before coding
 </example>
 
 **HUMAN** — Explicit user approval before any changes:
@@ -233,9 +252,9 @@ Action: EnterPlanMode, explore frame-manager.ts, research Graphiti API, design b
 - Publishing (npm publish, Railway deploy)
 
 <example>
-# 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.
+# HUMAN: "drop the old digest_cache table and run npm publish"
+# → STOP. Confirm with user: "This will permanently delete digest_cache
+#    and publish to npm. Proceed?" — wait for explicit yes.
 </example>
 
 Quality gates scale with tier — don't over-engineer AUTOMATE tasks, don't under-review CAREFUL ones.
@@ -250,17 +269,12 @@ Quality gates scale with tier — don't over-engineer AUTOMATE tasks, don't unde
 - Ask 1-3 clarifying questions for complex commands (one at a time)
 
 <example>
-# 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>
-
-<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
+# Session start checklist:
+$ git log --oneline -10          # understand recent context
+$ cat stackmemory.json           # check current config/state
+$ cat .env | grep -v '^#'        # verify which API keys are present
+
+# After completing a Linear task:
+$ npm run linear:sync            # update issue status in Linear
+$ stackmemory snapshot save      # capture context for next session
 </example>

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

@@ -1,3 +1,4 @@
+```markdown
 # StackMemory - Project Configuration
 
 ## Project Structure
@@ -5,7 +6,7 @@
 ```
 src/
   cli/           # CLI commands and entry point
-  core/          # Core business logic
+  core/
     context/     # Frame and context management
     database/    # Database adapters (SQLite, ParadeDB)
     digest/      # Digest generation
@@ -15,78 +16,72 @@ src/
   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
+- 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`
 
-## Documentation
+## Docs
 
-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
+- `agent_docs/`: linear_integration.md | mcp_server.md | database_storage.md | claude_hooks.md
+- `docs/`: principles.md | architecture.md | SPEC.md | API_REFERENCE.md | DEVELOPMENT.md
 
 ## Commands
 
 ```bash
-npm run build|lint|lint:fix|test|test:run|linear:sync
-stackmemory capture|restore    # Session state handoff
+npm run build          # Compile TypeScript (esbuild)
+npm run lint           # ESLint check
+npm run lint:fix       # Auto-fix lint issues
+npm run test:run       # Run tests once
+npm run linear:sync    # Sync with Linear
+
+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 (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
+After code changes: `npm run lint && npm run test:run && npm run build`
 
-Test coverage:
 - New features require tests in `src/**/__tests__/`
-- Maintain or improve coverage (no untested code paths)
+- 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
+- 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`
+- NEVER `--no-verify` on push or commit — fix the underlying issue
+- Commit: `type(scope): message` | Branch: `feature/STA-XXX-description` | `fix/` | `chore/`
 
 ## Security
 
-NEVER hardcode secrets - use process.env with dotenv/config
+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);
-}
+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_*
+Env sources (order): `.env` → `.env.local` → `~/.zshrc` → process env  
+Block patterns: `lin_api_*` | `lin_oauth_*` | `sk-*` | `npm_*`
 
 ## Deploy
 
 ```bash
-# npm publish (uses NPM_TOKEN from .env)
+# npm publish
 git stash -- scripts/gepa/
 NPM_TOKEN=$(grep '^NPM_TOKEN=' .env | cut -d= -f2) \
   npm publish --registry https://registry.npmjs.org/ \
@@ -95,48 +90,33 @@ git stash pop
 
 # Railway
 railway up
-
-# Pre-publish requires clean git — stash GEPA files first
 ```
 
-## Task Delegation Model
-
-Route effort by complexity:
+Pre-publish requires clean git status — stash GEPA files first.
 
-**AUTOMATE** — Execute immediately, lint+test sufficient:
-- CRUD, boilerplate, formatting, simple transforms
-- Tool handler following existing pattern
-- Config additions (env var, feature flag)
+## Task Delegation Model
 
-**STANDARD** — Normal workflow, lint+test+build:
-- Features, bug fixes, refactoring
-- Tests, docs, integration wiring
+**AUTOMATE** — lint+test sufficient:
+- CRUD, boilerplate, config additions, simple switch/case handlers
 
-**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
+**STANDARD** — lint+test+build:
+- Feature impl, bug fixes, refactoring, new tests, integration wiring
 
-**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
+**CAREFUL** — review approach first:
+- API/schema changes, DB migrations, auth flows, MCP/webhook handlers
+- Changes to frame-manager, sqlite-adapter, daemon lifecycle, error chains
 
-**HUMAN** — Explicit approval required:
-- Security decisions, secret handling
-- Irreversible operations (migrations, schema drops)
-- Publishing (npm, Railway)
+**ARCHITECT** — plan mode required:
+- New service boundaries, FTS5/search performance, breaking MCP/CLI changes
 
-Quality gates scale with tier — don't over-engineer AUTOMATE, don't under-review CAREFUL.
+**HUMAN** — explicit approval required:
+- Secret handling, data migrations/schema drops, npm publish, Railway deploy
 
 ## 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)
+- Check `.env` for API keys before asking
+- Run `npm run linear:sync` after task completion
+- Review recent commits on session start
+- Use subagents for multi-step tasks
+- Ask 1–3 clarifying questions for complex commands (one at a time)
+```