@stackmemoryai/stackmemory 1.2.1 → 1.2.2

package/scripts/gepa/evals/stackmemory-tasks.jsonl

@@ -0,0 +1,8 @@
+{"id": "sm-001", "name": "add_mcp_tool_handler", "prompt": "Add a new MCP tool handler called 'get_frame_summary' that takes a frameId (required string) and returns { frameId, name, status, eventCount }. Follow the existing switch/case dispatch pattern in server.ts. Include Zod input validation.", "input_file": "fixtures/mcp-dispatch-stub.ts", "expected": {"has_switch_case": true, "has_zod_schema": true, "validates_input": true, "returns_typed_response": true, "handles_not_found": true}, "weight": 1.5}
+{"id": "sm-002", "name": "fix_fts5_trigger_bug", "prompt": "The FTS5 DELETE trigger is missing — when a frame is deleted from the frames table, the frames_fts index is not updated. Add the missing AFTER DELETE trigger following the pattern of the existing INSERT and UPDATE triggers.", "input_file": "fixtures/fts5-triggers.sql", "expected": {"has_delete_trigger": true, "uses_fts_delete_syntax": true, "references_old_row": true, "matches_column_list": true}, "weight": 1.8}
+{"id": "sm-003", "name": "daemon_service_lifecycle", "prompt": "This daemon service has a timer leak — when updateConfig() restarts the service, the old interval is not cleared before creating a new one if start() is called while already running. Fix the bug and add a getState() method that returns { isRunning, intervalMs, lastRunTime, errorCount }.", "input_file": "fixtures/leaky-service.ts", "expected": {"clears_old_interval": true, "prevents_double_start": true, "has_getstate_method": true, "returns_correct_state_shape": true}, "weight": 1.5}
+{"id": "sm-004", "name": "webhook_payload_validation", "prompt": "This webhook handler is vulnerable to prototype pollution and has no input length limits. Fix the validation to: 1) reject __proto__ and constructor keys, 2) limit title to 500 chars, 3) limit description to 5000 chars, 4) validate that action is one of create/update/remove.", "input_file": "fixtures/unsafe-webhook.ts", "expected": {"blocks_proto_pollution": true, "limits_title_length": true, "limits_description_length": true, "validates_action_enum": true, "returns_null_on_invalid": true}, "weight": 2.0}
+{"id": "sm-005", "name": "error_handling_chain", "prompt": "Wrap this database operation in proper StackMemory error handling: use DatabaseError with appropriate ErrorCode, preserve the cause chain, set isRetryable based on error type (connection errors are retryable, constraint violations are not), and log with structured context.", "input_file": "fixtures/unwrapped-db-op.ts", "expected": {"uses_database_error": true, "preserves_cause": true, "sets_retryable_correctly": true, "has_structured_logging": true, "catches_unknown_type": true}, "weight": 1.3}
+{"id": "sm-006", "name": "integration_graceful_degradation", "prompt": "This integration handler crashes the MCP server when the external API is down. Refactor it to degrade gracefully: catch connection errors, return a user-friendly MCPResponse with metadata.unavailable=true, log at debug level (not error), and don't retry on 4xx errors.", "input_file": "fixtures/brittle-integration.ts", "expected": {"catches_connection_errors": true, "returns_mcp_response": true, "sets_unavailable_metadata": true, "logs_at_debug": true, "no_retry_on_4xx": true}, "weight": 1.5}
+{"id": "sm-007", "name": "sqlite_migration_safety", "prompt": "Write a safe SQLite migration that adds a 'tags' TEXT column to the frames table. The migration must: 1) check if column already exists first (idempotent), 2) wrap in a transaction, 3) update the schema_version table, 4) handle the case where schema_version table doesn't exist yet.", "expected": {"checks_column_exists": true, "uses_transaction": true, "updates_schema_version": true, "is_idempotent": true, "handles_missing_version_table": true}, "weight": 1.5}
+{"id": "sm-008", "name": "review_pr_security", "prompt": "Review this PR diff and identify all security issues, performance problems, and code quality concerns. Provide actionable feedback for each issue found.", "input_file": "fixtures/pr-diff.txt", "expected": {"identifies_sql_injection": true, "identifies_plaintext_password": true, "identifies_credential_logging": true, "identifies_weak_session": true, "provides_fix_suggestions": true}, "weight": 2.0}

package/scripts/gepa/generations/gen-000/baseline.md

@@ -1,159 +1,172 @@
-AGENTS.md
-
-Purpose
-- A minimal, agent-friendly reference so code-generation agents (Codex, Claude Code, etc.) can work effectively in this repository.
-- Explains key docs, the /designs/ folder, agent responsibilities, and quick operational notes (how to run tests, what to update, and commit expectations).
-
-Repo doc descriptions
-- prompt_plan.md
-  - The agent-driven plan that sequences work into small, testable prompts and steps.
-  - Contains per-step prompts, expected artifacts, tests, rollback/idempotency notes, and a TODO checklist using Markdown checkboxes.
-  - This is the canonical agent workflow driver — update it as you make progress (see Agent responsibility rules below).
-
-- spec.md
-  - The minimal functional & technical specification that defines APIs, data models, and acceptance criteria.
-  - Includes the concise Definition of Done that must be satisfied for each plan step before marking it complete.
-
-- idea.md
-  - Free-form brainstorming, assumptions, notes, research links, and open questions.
-  - Useful for context but not authoritative — always follow spec.md and prompt_plan.md for implementation decisions.
-
-- idea_one_pager.md
-  - A short summary / one‑pager capturing Problem, Audience, Platform, Core Flow, and MVP Features (and optional Non‑Goals).
-  - Good for quick alignment and to confirm that work stays within scope.
-
-What lives in /designs/
-- UI/UX artifacts and visual assets that inform implementation:
-  - wireframes (PNG/SVG), Figma exports (.fig, .pdf), sequence diagrams, architecture diagrams (PNG/PDF/SVG), and annotated screenshots.
-  - Naming conventions: keep filenames short, include version/date and owner, e.g., dashboard_v1_2025-11-01.png or seq_query_flow_v2.pdf.
-  - Large source Figma files may live externally; include an export + a small README describing where the canonical design is stored and any viewing permissions required.
-
-How agents should interact (summary)
-- Treat prompt_plan.md as the authoritative workflow: follow the listed prompts in order and mark checklist items as you finish them.
-- Always follow TDD: write tests first, make the minimal change to pass tests, then refactor while keeping tests green.
-- After any code/test change, update the matching TODO checkbox in prompt_plan.md using the same Markdown checkbox format ('- [x]') and commit the change alongside code and tests.
-- Make the smallest change that passes tests and improves code. Do not introduce new public APIs without updating spec.md and tests.
-- Don't duplicate templates/files to work around errors — fix the original.
-- Suggest a clear manual test path for every change (even when tests cover it).
-- If you cannot open a file or content is missing, say so explicitly and stop. Do not guess.
-
-Quick operational commands (expect these to exist; if not, ask)
-- npm run dev — start local dev server
-- npm test — run unit + integration test suite
-- npm run lint — run linting
-- npm run build — build TypeScript
-- npm run migrate:up / migrate:down — database migrations
-
-Commit & PR expectations
-- Each prompt/plan step should result in a single, focused commit/PR with:
-  - Code + tests + prompt_plan.md checklist update.
-  - A short, copy-pasteable commit summary in the prompt_plan.md step completion entry.
-  - Clear CHANGELOG or Release notes entry if user-facing behavior changed (or explicitly state "No user-facing changes").
-- Use atomic commits. Include test run results in PR description.
-
-Include this governance / workflow block verbatim (do not modify)
-## Repository docs
-- 'ONE_PAGER.md' - Captures Problem, Audience, Platform, Core Flow, MVP Features; Non-Goals optional.
-- 'DEV_SPEC.md' - Minimal functional and technical specification consistent with prior docs, including a concise **Definition of Done**.
-- 'PROMPT_PLAN.md' - Agent-Ready Planner with per-step prompts, expected artifacts, tests, rollback notes, idempotency notes, and a TODO checklist using Markdown checkboxes. This file drives the agent workflow.
-- 'docs/STYLE.md' - Unified design system reference. Typography, layout, color tokens, component patterns. Inspired by Hatchet (structural layout, inset panels) and Outliner (clean hierarchy, whitespace). **All dashboard UI changes must follow this guide.**
-- 'AGENTS.md' - This file.
-
-### Agent responsibility
-- After completing any coding, refactor, or test step, **immediately update the corresponding TODO checklist item in 'prompt_plan.md'**.
-- Use the same Markdown checkbox format ('- [x]') to mark completion.
-- When creating new tasks or subtasks, add them directly under the appropriate section anchor in 'prompt_plan.md'.
-- Always commit changes to 'prompt_plan.md' alongside the code and tests that fulfill them.
-- Do not consider work "done" until the matching checklist item is checked and all related tests are green.
-- When a stage (plan step) is complete with green tests, update the README "Release notes" section with any user-facing impact (or explicitly state "No user-facing changes" if applicable).
-- Even when automated coverage exists, always suggest a feasible manual test path so the human can exercise the feature end-to-end.
-- After a plan step is finished, document its completion state with a short checklist. Include: step name & number, test results, 'prompt_plan.md' status, manual checks performed (mark as complete only after the human confirms they ran to their satisfaction), release notes status, and an inline commit summary string the human can copy & paste.
-
-#### Guardrails for agents
-- Make the smallest change that passes tests and improves the code.
-- Do not introduce new public APIs without updating 'spec.md' and relevant tests.
-- Do not duplicate templates or files to work around issues. Fix the original.
-- If a file cannot be opened or content is missing, say so explicitly and stop. Do not guess.
-- Respect privacy and logging policy: do not log secrets, prompts, completions, or PII.
-
-#### Deferred-work notation
-- When a task is intentionally paused, keep its checkbox unchecked and prepend '(Deferred)' to the TODO label in 'prompt_plan.md', followed by a short reason.
-- Apply the same '(Deferred)' tag to every downstream checklist item that depends on the paused work.
-- Remove the tag only after the work resumes; this keeps the outstanding scope visible without implying completion.
-
-
-
-#### When the prompt plan is fully satisfied
-- Once every Definition of Done task in 'prompt_plan.md' is either checked off or explicitly marked '(Deferred)', the plan is considered **complete**.
-- After that point, you no longer need to update prompt-plan TODOs or reference 'prompt_plan.md', 'spec.md', 'idea_one_pager.md', or other upstream docs to justify changes.
-- All other guardrails, testing requirements, and agent responsibilities in this file continue to apply unchanged.
-
-
----
-
-## Testing policy (non-negotiable)
-- Tests **MUST** cover the functionality being implemented.
-- **NEVER** ignore the output of the system or the tests - logs and messages often contain **CRITICAL** information.
-- **TEST OUTPUT MUST BE PRISTINE TO PASS.**
-- If logs are **supposed** to contain errors, capture and test it.
-- **NO EXCEPTIONS POLICY:** Under no circumstances should you mark any test type as "not applicable". Every project, regardless of size or complexity, **MUST** have unit tests, integration tests, **AND** end-to-end tests. If you believe a test type doesn't apply, you need the human to say exactly **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
-
-### TDD (how we work)
-- Write tests **before** implementation.
-- Only write enough code to make the failing test pass.
-- Refactor continuously while keeping tests green.
-
-**TDD cycle**
-1. Write a failing test that defines a desired function or improvement.
-2. Run the test to confirm it fails as expected.
-3. Write minimal code to make the test pass.
-4. Run the test to confirm success.
-5. Refactor while keeping tests green.
-6. Repeat for each new feature or bugfix.
-
----
-
-## Important checks
-- **NEVER** disable functionality to hide a failure. Fix root cause.
-- **NEVER** create duplicate templates or files. Fix the original.
-- **NEVER** claim something is "working" when any functionality is disabled or broken.
-- If you can't open a file or access something requested, say so. Do not assume contents.
-- **ALWAYS** identify and fix the root cause of template or compilation errors.
-- If git is initialized, ensure a '.gitignore' exists and contains at least:
-
-  .env
-  .env.local
-  .env.*
-
-  Ask the human whether additional patterns should be added, and suggest any that you think are important given the project.
-
-## When to ask for human input
-Ask the human if any of the following is true:
-- A test type appears "not applicable". Use the exact phrase request: **"I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME"**.
-- Required anchors conflict or are missing from upstream docs.
-- You need new environment variables or secrets.
-- An external dependency or major architectural change is required.
-- Design files are missing, unsupported or oversized
-
-(End of verbatim block)
-
-Minimal examples for checklist updates (copy/pasteable)
-- After completing a prompt step, add an entry under that step in prompt_plan.md similar to:
-  - [x] Step 5 — Implement POST /api/v1/query — tests green — manual checks: cURL example tested — README Release Notes updated — commit: "query: add /api/v1/query route, adapter integration, tests"
-- If pausing work:
-  - - [ ] (Deferred) Step 7.3 — Implement real Pinecone adapter — blocked on PINECONE_API_KEY (reason: waiting for dev key from infra)
-
-If anything is missing
-- If you cannot open prompt_plan.md, spec.md, idea.md, idea_one_pager.md, or any design file, stop and report exactly which file and why (permission/absent/parse error).
-- Ask for required secrets or permissions rather than guessing. Use the "When to ask for human input" rules above.
-
-Contact & escalation
-- When blocked on infra/secrets/design files, create a short note in prompt_plan.md under the current step and ping the human with:
-  - What I need: (e.g., PINECONE_API_KEY, AWS dev creds)
-  - Why I need it: (which step/blocker)
-  - Recommended minimal next action & fallback
-
-Notes
-- Keep AGENTS.md and the rest of the repo docs in sync. Update this file if workflow expectations change.
-
-End.
+# 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
+
+## 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
+
+```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
+```
+
+## Working Directory
+
+- PRIMARY: /Users/jwu/Dev/stackmemory
+- ALLOWED: All subdirectories
+- TEMP: /tmp for temporary operations
+
+## Validation (MUST DO)
+
+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
+
+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 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`
+
+## Task Management
+
+- Use TodoWrite for 3+ steps or multiple requests
+- Keep one task in_progress at a time
+- Update task status immediately on completion
+
+## 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):
+1. .env file
+2. .env.local
+3. ~/.zshrc
+4. Process environment
+
+Secret patterns to block: lin_api_* | lin_oauth_* | sk-* | npm_*
+
+## Deploy
+
+```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
+```
+
+## Task Delegation Model
+
+Route effort by task complexity — not all code changes deserve equal scrutiny:
+
+**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)
+
+**STANDARD** — Normal workflow, lint+test+build:
+- Feature implementation, bug fixes, refactoring
+- New test coverage, documentation updates
+- Integration wiring (adding handler to server.ts dispatch)
+
+**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
+
+**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
+
+**HUMAN** — Explicit user approval before any changes:
+- Security-critical decisions, secret handling
+- Irreversible operations (data migrations, schema drops)
+- Publishing (npm publish, Railway deploy)
+
+Quality gates scale with tier — don't over-engineer AUTOMATE tasks, don't under-review CAREFUL ones.
+
+## 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 subagents for multi-step tasks
+- Ask 1-3 clarifying questions for complex commands (one at a time)