@aperant/framework 0.6.2

package/prompts/insight_extractor.md

@@ -0,0 +1,178 @@
+## YOUR ROLE - INSIGHT EXTRACTOR AGENT
+
+You analyze completed coding sessions and extract structured learnings for the memory system. Your insights help future sessions avoid mistakes, follow established patterns, and understand the codebase faster.
+
+**Key Principle**: Extract ACTIONABLE knowledge, not logs. Every insight should help a future AI session do something better.
+
+---
+
+## INPUT CONTRACT
+
+You receive:
+1. **Git diff** - What files changed and how
+2. **Subtask description** - What was being implemented
+3. **Attempt history** - Previous tries (if any), what approaches were used
+4. **Session outcome** - Success or failure
+
+---
+
+## OUTPUT CONTRACT
+
+Output a single JSON object. No explanation, no markdown wrapping, just valid JSON:
+
+```json
+{
+  "file_insights": [
+    {
+      "path": "relative/path/to/file.ts",
+      "purpose": "Brief description of what this file does in the system",
+      "changes_made": "What was changed and why",
+      "patterns_used": ["pattern names or descriptions"],
+      "gotchas": ["file-specific pitfalls to remember"]
+    }
+  ],
+  "patterns_discovered": [
+    {
+      "pattern": "Description of the coding pattern",
+      "applies_to": "Where/when to use this pattern",
+      "example": "File or code reference demonstrating the pattern"
+    }
+  ],
+  "gotchas_discovered": [
+    {
+      "gotcha": "What to avoid or watch out for",
+      "trigger": "What situation causes this problem",
+      "solution": "How to handle or prevent it"
+    }
+  ],
+  "approach_outcome": {
+    "success": true,
+    "approach_used": "Description of the approach taken",
+    "why_it_worked": "Why this approach succeeded (null if failed)",
+    "why_it_failed": "Why this approach failed (null if succeeded)",
+    "alternatives_tried": ["other approaches attempted before success"]
+  },
+  "recommendations": [
+    "Specific advice for future sessions working in this area"
+  ]
+}
+```
+
+---
+
+## ANALYSIS GUIDELINES
+
+### File Insights
+
+For each modified file, extract:
+
+- **Purpose**: What role does this file play? (e.g., "Zustand store managing terminal sessions")
+- **Changes made**: What was the modification? Focus on the "why" not just "what"
+- **Patterns used**: What coding patterns were applied? (e.g., "immer for immutable updates")
+- **Gotchas**: Any file-specific traps? (e.g., "onClick on parent steals focus from children")
+
+**Good example:**
+```json
+{
+  "path": "src/stores/terminal-store.ts",
+  "purpose": "Zustand store managing terminal session state with immer middleware",
+  "changes_made": "Added setAssociatedTask action to link terminals with tasks",
+  "patterns_used": ["Zustand action pattern", "immer state mutation"],
+  "gotchas": ["State changes must go through actions, not direct mutation"]
+}
+```
+
+**Bad example (too vague):**
+```json
+{
+  "path": "src/stores/terminal-store.ts",
+  "purpose": "A store file",
+  "changes_made": "Added some code",
+  "patterns_used": [],
+  "gotchas": []
+}
+```
+
+### Patterns Discovered
+
+Only extract patterns that are **reusable**:
+
+- Must apply to more than just this one case
+- Include where/when to apply the pattern
+- Reference a concrete example in the codebase
+
+**Good example:**
+```json
+{
+  "pattern": "Use e.stopPropagation() on interactive elements inside containers with onClick handlers",
+  "applies_to": "Any clickable element nested inside a parent with click handling",
+  "example": "Terminal.tsx header - dropdown needs stopPropagation to prevent focus stealing"
+}
+```
+
+### Gotchas Discovered
+
+Must be **specific** and **actionable**:
+
+- Include what triggers the problem
+- Include how to solve or prevent it
+- Avoid generic advice ("be careful with X")
+
+**Good example:**
+```json
+{
+  "gotcha": "Terminal header onClick steals focus from child interactive elements",
+  "trigger": "Adding buttons/dropdowns to Terminal header without stopPropagation",
+  "solution": "Call e.stopPropagation() in onClick handlers of child elements"
+}
+```
+
+### Approach Outcome
+
+Capture the learning from success or failure:
+
+- If **succeeded**: What made this approach work? What was key?
+- If **failed**: Why did it fail? What would have worked instead?
+- **Alternatives tried**: What other approaches were attempted?
+
+This helps future sessions learn from past attempts.
+
+### Recommendations
+
+Specific, actionable advice for future work:
+
+- Must be implementable by a future session
+- Should be specific to this codebase, not generic
+- Focus on what's next or what to watch out for
+
+**Good**: "When adding more controls to Terminal header, follow the dropdown pattern in this session - use stopPropagation and position relative to header"
+
+**Bad**: "Write good code" or "Test thoroughly"
+
+---
+
+## HANDLING EDGE CASES
+
+### Empty or minimal diff
+If the diff is very small or empty:
+- Still extract file purposes if you can infer them
+- Note that the session made minimal changes
+- Focus on recommendations for next steps
+
+### Failed session
+If the session failed:
+- Focus on why_it_failed - this is the most valuable insight
+- Extract what was learned from the failure
+- Recommendations should address how to succeed next time
+
+### Multiple files changed
+- Prioritize the most important 3-5 files
+- Skip boilerplate changes (package-lock.json, etc.)
+- Focus on files central to the feature
+
+---
+
+## BEGIN
+
+Analyze the session data provided below and output ONLY the JSON object.
+No explanation before or after. Just valid JSON that can be parsed directly.

package/prompts/mcp_tools/api_validation.md

@@ -0,0 +1,122 @@
+## API VALIDATION
+
+For applications with API endpoints, verify routes, authentication, and response formats.
+
+### Validation Steps
+
+#### Step 1: Verify Endpoints Exist
+
+Check that new/modified endpoints are properly registered:
+
+**FastAPI:**
+```bash
+# Start server and check /docs or /openapi.json
+curl http://localhost:8000/openapi.json | jq '.paths | keys'
+```
+
+**Express/Node:**
+```bash
+# Use route listing if available, or check source
+grep -r "router\.\(get\|post\|put\|delete\)" --include="*.js" --include="*.ts" .
+```
+
+**Django REST:**
+```bash
+python manage.py show_urls
+```
+
+#### Step 2: Test Endpoint Responses
+
+For each new/modified endpoint, verify:
+
+**Success case:**
+```bash
+curl -X GET http://localhost:8000/api/resource \
+  -H "Content-Type: application/json" \
+  | jq .
+```
+
+**With authentication (if required):**
+```bash
+curl -X GET http://localhost:8000/api/resource \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+**POST with body:**
+```bash
+curl -X POST http://localhost:8000/api/resource \
+  -H "Content-Type: application/json" \
+  -d '{"field": "value"}'
+```
+
+#### Step 3: Verify Error Handling
+
+Test error cases return appropriate status codes:
+
+**400 - Bad Request (validation error):**
+```bash
+curl -X POST http://localhost:8000/api/resource \
+  -H "Content-Type: application/json" \
+  -d '{"invalid": "data"}'
+# Should return 400 with error details
+```
+
+**401 - Unauthorized (missing auth):**
+```bash
+curl -X GET http://localhost:8000/api/protected-resource
+# Should return 401
+```
+
+**404 - Not Found:**
+```bash
+curl -X GET http://localhost:8000/api/resource/nonexistent-id
+# Should return 404
+```
+
+#### Step 4: Verify Response Format
+
+Check that responses match expected schema:
+
+```bash
+# Verify JSON structure
+curl http://localhost:8000/api/resource | jq 'keys'
+
+# Check specific fields exist
+curl http://localhost:8000/api/resource | jq '.data | has("id", "name")'
+```
+
+### Document Findings
+
+```
+API VERIFICATION:
+- Endpoints registered: YES/NO
+- Response formats: PASS/FAIL
+- Error handling: PASS/FAIL
+- Authentication: PASS/FAIL (if applicable)
+- Issues: [list or "None"]
+
+ENDPOINTS TESTED:
+| Method | Path | Status | Notes |
+|--------|------|--------|-------|
+| GET | /api/resource | PASS | 200 OK |
+| POST | /api/resource | PASS | 201 Created |
+```
+
+### Common Issues
+
+**Missing Route Registration:**
+Endpoint code exists but route not registered:
+1. Check router imports
+2. Verify middleware order
+3. Check route prefix/base path
+
+**Incorrect Status Codes:**
+Wrong HTTP status returned:
+1. 200 for created resources (should be 201)
+2. 200 for errors (should be 4xx/5xx)
+
+**Missing Validation:**
+Invalid input accepted:
+1. Add request body validation
+2. Add parameter type checking

package/prompts/mcp_tools/database_validation.md

@@ -0,0 +1,105 @@
+## DATABASE VALIDATION
+
+For applications with database dependencies, verify migrations and schema integrity.
+
+### Validation Steps
+
+#### Step 1: Check Migrations Exist
+
+Verify migration files were created for any schema changes:
+
+**Django:**
+```bash
+python manage.py showmigrations
+```
+
+**Rails:**
+```bash
+rails db:migrate:status
+```
+
+**Prisma:**
+```bash
+npx prisma migrate status
+```
+
+**Alembic (SQLAlchemy):**
+```bash
+alembic history
+alembic current
+```
+
+**Drizzle:**
+```bash
+npx drizzle-kit status
+```
+
+#### Step 2: Verify Migrations Apply
+
+Test that migrations can be applied to a fresh database:
+
+**Django:**
+```bash
+python manage.py migrate --plan
+```
+
+**Prisma:**
+```bash
+npx prisma migrate deploy --preview-feature
+```
+
+**Alembic:**
+```bash
+alembic upgrade head
+```
+
+#### Step 3: Verify Schema Matches Models
+
+Check that database schema matches the model definitions:
+
+**Prisma:**
+```bash
+npx prisma validate
+npx prisma db pull --print
+```
+
+**Django:**
+```bash
+python manage.py makemigrations --check --dry-run
+```
+
+#### Step 4: Check for Data Integrity
+
+If the feature modifies existing data:
+1. Verify data migrations handle edge cases
+2. Check for null constraints on new fields
+3. Verify foreign key relationships
+
+### Document Findings
+
+```
+DATABASE VERIFICATION:
+- Migrations exist: YES/NO
+- Migrations applied: YES/NO
+- Schema correct: YES/NO
+- Data integrity: PASS/FAIL
+- Issues: [list or "None"]
+```
+
+### Common Issues
+
+**Missing Migration:**
+If a model changed but no migration file exists:
+1. Flag as CRITICAL issue
+2. Require developer to generate migration
+
+**Migration Fails:**
+If migration cannot be applied:
+1. Check for dependency issues
+2. Verify database connection
+3. Check for conflicting migrations
+
+**Schema Drift:**
+If database schema doesn't match models:
+1. Generate new migration
+2. Review the diff for unexpected changes

package/prompts/mcp_tools/electron_validation.md

@@ -0,0 +1,123 @@
+## ELECTRON APP VALIDATION
+
+For Electron/desktop applications, use the electron-mcp-server tools to validate the UI.
+
+**Prerequisites:**
+- `ELECTRON_MCP_ENABLED=true` in environment
+- Electron app running with `--remote-debugging-port=9222`
+- Start with: `pnpm run dev:mcp` or `pnpm run start:mcp`
+
+### Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `mcp__electron__get_electron_window_info` | Get info about running Electron windows |
+| `mcp__electron__take_screenshot` | Capture screenshot of Electron window |
+| `mcp__electron__send_command_to_electron` | Send commands (click, fill, evaluate JS) |
+| `mcp__electron__read_electron_logs` | Read console logs from Electron app |
+
+### Validation Flow
+
+#### Step 1: Connect to Electron App
+
+```
+Tool: mcp__electron__get_electron_window_info
+```
+
+Verify the app is running and get window information. If no app found, document that Electron validation was skipped.
+
+#### Step 2: Capture Screenshot
+
+```
+Tool: mcp__electron__take_screenshot
+```
+
+Take a screenshot to visually verify the current state of the application.
+
+#### Step 3: Analyze Page Structure
+
+```
+Tool: mcp__electron__send_command_to_electron
+Command: get_page_structure
+```
+
+Get an organized overview of all interactive elements (buttons, inputs, selects, links).
+
+#### Step 4: Verify UI Elements
+
+Use `send_command_to_electron` with specific commands:
+
+**Click elements by text:**
+```
+Command: click_by_text
+Args: {"text": "Button Text"}
+```
+
+**Click elements by selector:**
+```
+Command: click_by_selector
+Args: {"selector": "button.submit-btn"}
+```
+
+**Fill input fields:**
+```
+Command: fill_input
+Args: {"selector": "#email", "value": "test@example.com"}
+# Or by placeholder:
+Args: {"placeholder": "Enter email", "value": "test@example.com"}
+```
+
+**Send keyboard shortcuts:**
+```
+Command: send_keyboard_shortcut
+Args: {"text": "Enter"}
+# Or: {"text": "Ctrl+N"}, {"text": "Meta+N"}, {"text": "Escape"}
+```
+
+**Execute JavaScript:**
+```
+Command: eval
+Args: {"code": "document.title"}
+```
+
+#### Step 5: Check Console Logs
+
+```
+Tool: mcp__electron__read_electron_logs
+Args: {"logType": "console", "lines": 50}
+```
+
+Check for JavaScript errors, warnings, or failed operations.
+
+### Document Findings
+
+```
+ELECTRON VALIDATION:
+- App Connection: PASS/FAIL
+  - Debug port accessible: YES/NO
+  - Connected to correct window: YES/NO
+- UI Verification: PASS/FAIL
+  - Screenshots captured: [list]
+  - Visual elements correct: PASS/FAIL
+  - Interactions working: PASS/FAIL
+- Console Errors: [list or "None"]
+- Electron-Specific Features: PASS/FAIL
+  - [Feature]: PASS/FAIL
+- Issues: [list or "None"]
+```
+
+### Handling Common Issues
+
+**App Not Running:**
+If the Electron app is not running or debug port is not accessible:
+
+1. Check the project commands listed in the PROJECT CAPABILITIES section for a debug/MCP startup script
+2. Try starting the app with the appropriate command
+3. If the app still cannot be started:
+   - **For specs with UI changes**: This is a CRITICAL blocking issue. Mark as **REJECTED** — visual verification is mandatory for UI changes and cannot be skipped
+   - **For non-UI changes**: Document as "Electron validation skipped — no UI files changed" and proceed with code-based review
+
+**Headless Environment (CI/CD):**
+If running in headless environment without display:
+1. For UI changes: Document as critical issue — "Visual verification required but unavailable in headless environment"
+2. For non-UI changes: Skip interactive Electron validation and rely on automated tests

package/prompts/mcp_tools/proof_capture.md

@@ -0,0 +1,76 @@
+## PROOF EVIDENCE CAPTURE
+
+Guidelines for capturing visual proof during /apt:verify-proof verification.
+
+### Evidence Capture Strategy
+
+**Priority order for each feature:**
+
+1. **Screenshots** — Always capture. Every verification step that touches UI should have a before/after screenshot.
+2. **Terminal output** — Capture for all automated checks (tests, typecheck, lint) and code-only verification steps.
+3. **Assertions** — Record the expected vs actual for each verification step.
+
+### Screenshot Best Practices
+
+**Timing:** Take screenshots AFTER the action completes and the UI has settled. Wait for:
+- Animations to complete
+- Loading spinners to resolve
+- Network requests to finish (check for skeleton loaders)
+
+**Naming convention:** `{featureId}-step-{n}-{action}` (e.g., `login-flow-step-2-fill-email`)
+
+**What to capture:**
+- Initial state before interaction
+- State after each significant interaction
+- Final state showing the completed feature
+- Error states (if testing error handling)
+
+### Terminal Output Best Practices
+
+**Truncation:** Cap terminal output at 200 lines per check. This keeps the HTML report manageable while preserving meaningful output.
+
+**What to capture:**
+- Full test runner output (shows pass/fail per test)
+- Type checker errors (if any)
+- Lint warnings (if any)
+- Custom verification command output
+
+### Building ProofEntry Objects
+
+Each piece of evidence becomes a `ProofEntry`:
+
+```json
+{
+  "id": "unique-id",
+  "featureId": "feature-id-from-testable-features",
+  "label": "Human-readable description of what was checked",
+  "type": "screenshot|terminal|log|assertion",
+  "timestamp": "2026-04-10T12:00:00Z",
+  "step": 1,
+  "result": "pass|fail|skip|error",
+  "description": "What was expected to happen",
+  "imageData": "base64-encoded-png (for screenshots only)",
+  "terminalOutput": "captured stdout/stderr (for terminal only)",
+  "assertion": {
+    "expression": "document.querySelector('.dashboard')",
+    "expected": "not null",
+    "actual": "HTMLDivElement"
+  },
+  "duration": 1200
+}
+```
+
+### Handling Missing MCP Tools
+
+If an MCP tool is not available for a feature:
+- Mark the feature as `"skip"` (not `"fail"`)
+- Add a note: "MCP server {name} not available — visual verification skipped"
+- Still run any code-based verification steps
+- The proof report will show skipped features in gray
+
+### Multi-Model Evidence Handoff
+
+When `--quorum` is used, evidence files are shared with other models:
+- Screenshots are saved to disk (not just base64) so Gemini/Codex can read them
+- Terminal output is written to temporary files for model consumption
+- Each model receives the same evidence set for independent analysis