@stackmemoryai/stackmemory 1.5.3 → 1.5.4

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)
+```

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

@@ -1,150 +1,115 @@
+```markdown
 # StackMemory - Project Configuration
 
-## Overview
+## Quick Reference
 
-StackMemory is an agent programming platform with CLI, MCP server, and Linear integration.
+**Entry points:** `src/cli/index.ts` · `src/integrations/mcp/server.ts`
+**Key files:** `src/core/context/frame-manager.ts` · `src/core/database/sqlite-adapter.ts` · `src/core/worktree/{capture,preflight}.ts` · `src/cli/commands/orchestrator.ts` · `src/core/utils/{git,text,fs}.ts`
 
-**Primary**: /Users/jwu/Dev/stackmemory  
-**Tech**: TypeScript, Node.js, SQLite, Vitest, ESLint, esbuild
+**Docs:** `agent_docs/` (quick ref) · `docs/` (full: principles, architecture, SPEC, API_REFERENCE, DEVELOPMENT, SETUP)
 
-## Architecture
+---
+
+## Project Structure
 
 ```
 src/
-  cli/           # CLI entry (index.ts)
-  core/          # Business logic
-    context/     # Frame management (frame-manager.ts)
-    database/    # Storage adapters (sqlite-adapter.ts)
+  cli/           # CLI commands and entry point
+  core/
+    context/     # Frame and context management
+    database/    # Database adapters (SQLite, ParadeDB)
     digest/      # Digest generation
-    query/       # Query routing
-  integrations/  # Linear, MCP (mcp/server.ts)
+    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
 ```
 
-## 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
+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
+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
 ```
 
-## Validation Checklist
+---
 
-After EVERY code change:
+## Validation (MUST DO)
 
-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
+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` — ensure compilation
+4. Run the code to verify it works
 
-**Test coverage**:
-- New features require tests in `src/**/__tests__/`
-- Maintain or improve coverage (no untested paths)
-- Critical: context management, handoff, Linear sync
+**Test coverage:** New features require tests in `src/**/__tests__/`. Maintain or improve coverage. Critical paths: context management, handoff, Linear sync.
 
-**Never**: Assume success | Skip testing | Use mock fallbacks
+Never: assume success · skip testing · use mock data as fallback
 
-## Git Workflow
+---
 
-**Commit format**: `type(scope): message`  
-**Branch naming**: `feature/STA-XXX-desc` | `fix/STA-XXX-desc` | `chore/desc`
+## Git Rules (CRITICAL)
 
-**Critical rules**:
-- NEVER use `--no-verify` on commit/push
-- ALWAYS fix lint/test errors before pushing
+- NEVER use `--no-verify` on git push or commit
+- ALWAYS fix lint/test errors before pushing; if pre-push hooks fail, fix the issue
 - Run `npm run lint && npm run test:run` before pushing
-- If pre-push hooks fail, fix the underlying issue
+- Commit: `type(scope): message`
+- Branch: `feature/STA-XXX-description` · `fix/STA-XXX-description` · `chore/description`
+
+---
 
 ## 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)
+| Tier | When | Gates |
+|------|------|-------|
+| **AUTOMATE** | CRUD, boilerplate, config additions, simple switch/case handlers | lint + test |
+| **STANDARD** | Features, bug fixes, refactoring, new tests, integration wiring | lint + test + build |
+| **CAREFUL** | API/schema changes, DB migrations, auth, MCP tools, frame-manager/sqlite-adapter/daemon lifecycle | Review approach first |
+| **ARCHITECT** | New service boundaries, FTS5/search perf, breaking MCP/CLI changes | Plan mode required |
+| **HUMAN** | Security decisions, secret handling, irreversible ops, publishing | Explicit approval |
+
+---
 
 ## 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); }
 ```
 
-**Env sources** (check in order):
-1. .env file
-2. .env.local
-3. ~/.zshrc
-4. Process environment
+Env lookup order: `.env` → `.env.local` → `~/.zshrc` → process env
+
+Block patterns: `lin_api_*` · `lin_oauth_*` · `sk-*` · `npm_*`
 
-**Block patterns**: lin_api_* | lin_oauth_* | sk-* | npm_*
+---
 
-## Deployment
+## Deploy
 
 ```bash
-# npm publish (uses NPM_TOKEN from .env, no OTP)
-git stash -- scripts/gepa/           # stash GEPA state
+# 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"
@@ -152,21 +117,22 @@ git stash pop                         # restore GEPA state
 
 # Railway
 railway up
-
-# Note: Pre-publish checks require clean git status
 ```
 
-## Task Management
+Pre-publish checks require clean git status — stash GEPA files first.
 
-- Use TodoWrite for 3+ steps or multiple requests
-- Keep one task in_progress at a time
-- Update status immediately on completion
+---
 
-## Workflow Tips
+## Workflow
 
-- Check .env for API keys before asking
+- Check `.env` for API keys before asking
+- Review recent commits and `stackmemory.json` on session start
+- Use subagents for multi-step tasks
 - 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)
+- Ask 1–3 clarifying questions for complex commands (one at a time)
+
+**Task management:** Use TodoWrite for 3+ steps. Keep one task `in_progress`. Update status immediately on completion.
+
+**Working directory:** PRIMARY `/Users/jwu/Dev/stackmemory` · TEMP `/tmp`
+```