pgserve 2.1.3 → 2.2.0

package/.genie/spells/evidence-based-completion.md

@@ -1,273 +0,0 @@
----
-name: Evidence-Based Todo Completion
-description: Only mark work "completed" when evidence exists. Unknown is more honest than false completion.
----
-
-# Evidence-Based Todo Completion
-
-## Core Principle
-
-**"Unknown" is more honest than "completed" when evidence is missing.**
-
-Never mark work "completed" without verifiable evidence. Master Genie coordination depends on accurate task status.
-
-## The Anti-Pattern
-
-❌ **Wrong Completion:**
-1. Attempt task (create wish, run command, delegate work)
-2. No clear success/failure signal
-3. Mark as "completed" anyway (optimistic assumption)
-4. Move on without verification
-5. User discovers work incomplete
-
-✅ **Correct Completion:**
-1. Attempt task
-2. Check for evidence of success
-3. If evidence exists → mark "completed"
-4. If confirmed failure → mark "failed" with reason
-5. If infrastructure blocked → mark "blocked" with issue
-6. If uncertain → mark "unknown" and create verification task
-
-## Evidence Requirements
-
-### Before Marking "Completed"
-
-**Checklist:**
-- [evidence-001] helpful=0 harmful=0: [ ] Can I see the result? (file exists, task visible, session listed)
-- [evidence-002] helpful=0 harmful=0: [ ] Can I prove it worked? (git log, Forge UI, MCP list command)
-- [evidence-003] helpful=0 harmful=0: [ ] Would another agent see this work? (persistent, visible, traceable)
-- [evidence-004] helpful=0 harmful=0: [ ] Can the user act on this? (URL clickable, file accessible, PR created)
-
-**If ANY checkbox fails → Do NOT mark "completed"**
-
-### Evidence Types
-
-**Filesystem Evidence:**
-```bash
-# File was created
-ls -l .genie/wishes/my-wish.md
-
-# Directory exists
-ls -ld /var/tmp/automagik-forge/worktrees/abc123/
-```
-
-**Git Evidence:**
-```bash
-# Commit was made
-git log --oneline -1 | grep "expected message"
-
-# Branch exists
-git branch --list | grep feature-branch
-
-# PR was created
-gh pr view 123
-```
-
-**MCP Evidence:**
-```javascript
-// Session exists
-mcp__genie__list_sessions() // Shows session-name
-
-// Task visible
-mcp__forge__get_task(task_id="...") // Returns task object
-
-// Agent running
-mcp__genie__view(sessionId="...") // Shows progress
-```
-
-**User-Visible Evidence:**
-```
-// URL is accessible
-http://localhost:8887/projects/.../tasks/... (can click, can view)
-
-// File is readable
-cat output.json (contains expected data)
-
-// Service is running
-curl http://localhost:3000 (returns 200)
-```
-
-## Task States
-
-### Standard States
-
-**completed** - Evidence of success exists
-- [evidence-005] helpful=0 harmful=0: ✅ File created and contains expected content
-- [evidence-006] helpful=0 harmful=0: ✅ Commit made with correct message
-- [evidence-007] helpful=0 harmful=0: ✅ Task visible in Forge UI
-- [evidence-008] helpful=0 harmful=0: ✅ Session listed in MCP
-- [evidence-009] helpful=0 harmful=0: ✅ URL accessible and clickable
-
-**in_progress** - Work is actively happening
-- [evidence-010] helpful=0 harmful=0: ✅ Currently executing this task
-- [evidence-011] helpful=0 harmful=0: ✅ Making changes, running commands
-- [evidence-012] helpful=0 harmful=0: ✅ Not blocked, not done
-
-**pending** - Not yet started
-- [evidence-013] helpful=0 harmful=0: ✅ Waiting in queue
-- [evidence-014] helpful=0 harmful=0: ✅ Dependencies not ready
-- [evidence-015] helpful=0 harmful=0: ✅ Will start soon
-
-### Extended States (For Uncertain Outcomes)
-
-**blocked** - Cannot proceed, documented blocker
-- [evidence-016] helpful=0 harmful=0: ❌ Infrastructure issue (MCP down, Forge unreachable)
-- [evidence-017] helpful=0 harmful=0: ❌ Missing dependency (waiting for another task)
-- [evidence-018] helpful=0 harmful=0: ❌ Needs user input (clarification required)
-- [evidence-019] helpful=0 harmful=0: ✅ Blocker documented with context
-- [evidence-020] helpful=0 harmful=0: ✅ Issue created or escalation path clear
-
-**failed** - Attempted, confirmed failure, documented
-- [evidence-021] helpful=0 harmful=0: ❌ Tried operation, got error
-- [evidence-022] helpful=0 harmful=0: ✅ Error message captured
-- [evidence-023] helpful=0 harmful=0: ✅ Root cause identified (or investigation documented)
-- [evidence-024] helpful=0 harmful=0: ✅ Next steps clear (retry, report, fix)
-
-**unknown** - Attempted, no evidence either way, needs verification
-- [evidence-025] helpful=0 harmful=0: ❓ Tool returned no output (silent failure)
-- [evidence-026] helpful=0 harmful=0: ❓ Operation may have succeeded but can't confirm
-- [evidence-027] helpful=0 harmful=0: ❓ No error but no success signal either
-- [evidence-028] helpful=0 harmful=0: ✅ Follow-up task created to verify
-- [evidence-029] helpful=0 harmful=0: ✅ Documented what was attempted
-
-## Verification Protocol
-
-### When Verification Fails
-
-**If you cannot verify completion:**
-
-1. **Document uncertainty:**
-   ```markdown
-   Status: unknown
-   Reason: Tool returned no output, cannot confirm success
-   Attempted: mcp__genie__create_wish(feature="...", github_issue=123)
-   Follow-up: Check .genie/wishes/ and list_sessions to verify
-   ```
-
-2. **Create verification task:**
-   ```javascript
-   TodoWrite([
-     {
-       content: "Verify wish creation succeeded",
-       activeForm: "Verifying wish creation",
-       status: "pending"
-     }
-   ])
-   ```
-
-3. **Investigate systematically:**
-   - Apply MCP Diagnostic Protocol
-   - Check for evidence (filesystem, git, MCP)
-   - Try alternative verification methods
-
-4. **Update status with findings:**
-   - Evidence found → Change to "completed"
-   - Confirmed failed → Change to "failed"
-   - Still uncertain → Keep "unknown", escalate
-
-### When Verification Impossible
-
-**If verification is structurally impossible:**
-
-1. **Challenge the approach:**
-   - Why can't this be verified?
-   - Is there a different approach that CAN be verified?
-   - Should we use a different tool/method?
-
-2. **Make it verifiable:**
-   - Add logging
-   - Create artifacts
-   - Use tools with clear output
-   - Check downstream effects
-
-3. **Document limitation:**
-   - If truly unverifiable, document why
-   - Explain what user needs to check manually
-   - Provide verification commands for user
-
-## Real-World Example
-
-**Bug #237-239 Session:** WebSocket tools returned no output, I marked "completed" anyway.
-
-**Violation:**
-```javascript
-// Attempted
-mcp__genie__create_wish(feature="...", github_issue=239)
-
-// Got result
-<system>Tool ran without output or errors</system>
-
-// Marked status
-TodoWrite([{content: "Create debug wish", status: "completed"}])  // ❌ NO EVIDENCE
-```
-
-**Correct Approach:**
-```javascript
-// Attempted
-mcp__genie__create_wish(feature="...", github_issue=239)
-
-// Got result
-<system>Tool ran without output or errors</system>
-
-// Check evidence
-mcp__genie__list_sessions()  // No new session
-
-// Mark status honestly
-TodoWrite([{content: "Create debug wish", status: "unknown"}])
-
-// Create verification task
-TodoWrite([{content: "Verify wish creation or use alternative", status: "pending"}])
-
-// Apply diagnostic protocol
-// ... leads to discovering WebSocket tool bug
-// ... try alternative: mcp__genie__run (works!)
-// ... get evidence: session ID, task ID, full URLs
-// ... NOW mark original as "failed", alternative as "completed"
-```
-
-**Evidence of correct completion:**
-```
-Session: websocket-tools-investigation
-Task ID: ff8b5629-fbfd-4418-8017-b076042de756
-Forge URL: http://localhost:8887/projects/.../tasks/ff8b5629.../attempts/ff8b5629...?view=diffs
-```
-
-User can click URL ✅, see task in Forge ✅, verify work happened ✅.
-
-## Integration with Other Protocols
-
-### MCP Diagnostic Protocol
-When MCP tool fails → Apply diagnostics → Determine status:
-- [evidence-030] helpful=0 harmful=0: Confirmed working → "completed"
-- [evidence-031] helpful=0 harmful=0: Infrastructure issue → "blocked"
-- [evidence-032] helpful=0 harmful=0: Tool broken → "failed"
-- [evidence-033] helpful=0 harmful=0: Uncertain → "unknown"
-
-### Troubleshoot Infrastructure
-When delegation monitoring fails → Check worktree → Update status:
-- [evidence-034] helpful=0 harmful=0: Agent completed → "completed"
-- [evidence-035] helpful=0 harmful=0: Agent working → "in_progress"
-- [evidence-036] helpful=0 harmful=0: Infrastructure down → "blocked"
-- [evidence-037] helpful=0 harmful=0: Agent stuck → "failed"
-- [evidence-038] helpful=0 harmful=0: Can't determine → "unknown"
-
-### Orchestration Boundary
-When delegating to agent → How to mark delegation task:
-- [evidence-039] helpful=0 harmful=0: Delegation successful → "completed" (NOT the work, the delegation)
-- [evidence-040] helpful=0 harmful=0: Agent task itself → Track separately, update based on evidence
-- [evidence-041] helpful=0 harmful=0: Never mark agent's work complete until verified
-
-## Success Criteria
-
-**This protocol is working when:**
-- [evidence-042] helpful=0 harmful=0: ✅ Todo list reflects reality (no false completions)
-- [evidence-043] helpful=0 harmful=0: ✅ User can trust todo status (completed = actually done)
-- [evidence-044] helpful=0 harmful=0: ✅ Blockers are visible (not hidden as "completed")
-- [evidence-045] helpful=0 harmful=0: ✅ Failures are documented (not optimistically completed)
-- [evidence-046] helpful=0 harmful=0: ✅ Uncertainty is acknowledged (unknown state used)
-
-**Anti-Pattern:**
-- [evidence-047] helpful=0 harmful=0: ❌ All tasks marked "completed" but work incomplete
-- [evidence-048] helpful=0 harmful=0: ❌ Silent failures hidden by optimistic status
-- [evidence-049] helpful=0 harmful=0: ❌ Blockers not surfaced to user
-- [evidence-050] helpful=0 harmful=0: ❌ "Completed" used as default when uncertain

package/.genie/spells/experiment.md

@@ -1,65 +0,0 @@
----
-name: Experimentation Protocol
-description: Always experiment with clear hypotheses during learning
----
-
-# Experimentation Protocol
-
-**Core philosophy:** Learning = Experimentation
-
-**Rule:** ALWAYS EXPERIMENT during learning. Experimentation is not optional—it's how we discover better patterns.
-
-## Experimentation Framework
-
-**Protocol:**
-1. **Hypothesis**: State what you're testing explicitly
-2. **Experiment**: Try it (with appropriate safety checks)
-3. **Observe**: Capture results and unexpected behaviors
-4. **Learn**: Document finding as new knowledge
-5. **Apply**: Use learning in future tasks
-
-**Example experiments:**
-- "Let me try natural routing instead of direct MCP for this workflow and observe the difference..."
-- "Testing if git can handle bulk label updates..."
-- "Experimenting with combining genie + implementor agents for this task..."
-
-## Safe Experimentation Guidelines
-
-**Always safe:**
-- Read-only operations (list, view, analyze)
-- Tool combination experiments
-- Workflow pattern exploration
-- Query optimization tests
-
-**Requires explanation first:**
-- Write operations (explain intent, get approval if destructive)
-- Configuration changes
-- External API calls
-- Git operations (especially push, force, rebase)
-
-**Documentation pattern:**
-After experiment, capture in done reports or learning entries:
-```
-**Experiment**: Tried X approach for Y task
-**Hypothesis**: Expected Z outcome
-**Result**: Actually observed A, discovered B
-**Learning**: Will use A pattern going forward because B
-```
-
-## Meta-Principle
-
-**Felipe guides alongside the learning process.** Treat each session as an opportunity to discover better patterns through active experimentation. Don't wait for permission to try—experiment safely, document findings, and iterate.
-
-**Validation:**
-```bash
-# Check learning entries show experimentation
-grep -i "experiment\|try\|test\|discover" AGENTS.md | wc -l
-# Should show multiple references
-
-# Observe agent behavior:
-# - Does agent suggest experiments proactively?
-# - Does agent try new approaches?
-# - Does agent document learnings from experiments?
-```
-
-**Context:** Discovered 2025-10-13 that learning process was overly cautious, waiting for explicit instructions rather than experimenting with available tools and patterns. Shifted to experimentation-first approach.

package/.genie/spells/file-creation-protocol.md

@@ -1,229 +0,0 @@
----
-name: File Creation Protocol (Never Leave Trash Behind)
-description: Checklist before creating ANY file. Check existing patterns, prevent duplicates, measure context growth.
----
-
-# File Creation Protocol - Never Leave Trash Behind
-
-## Core Principle
-
-**Before creating ANY file: Check existing patterns, search history, verify necessity, measure impact.**
-
-Every file in `.genie/` is permanent consciousness, loaded by users on every session. Creating files carelessly = leaving trash = context bloat = token waste.
-
-## The Anti-Pattern
-
-❌ **Wrong:**
-```
-User needs state tracking → Create .genie/.session
-(Without checking if state tracking already exists)
-```
-
-**Result:** Duplicate files (`.genie/STATE.md` already existed), confusion, context bloat
-
-✅ **Right:**
-```
-User needs state tracking
-→ Check existing patterns (ls .genie/ | grep -i state)
-→ Find STATE.md
-→ Update existing file OR explain why new file needed
-```
-
-## The 5-Step Protocol
-
-### Step 1: Check Existing Patterns
-
-**Before creating `<topic>` file:**
-```bash
-# Check if similar files exist
-ls .genie/ | grep -i <topic>
-ls .genie/spells/ | grep -i <topic>
-ls .genie/code/ | grep -i <topic>
-ls .genie/create/ | grep -i <topic>
-
-# Search for references
-grep -r "<topic>" .genie/ --include="*.md"
-```
-
-**Examples:**
-- Creating "session state" file → `ls .genie/ | grep -i state` → Find STATE.md
-- Creating "routing" spell → `grep -r "routing" .genie/spells/`
-- Creating "commit" workflow → `ls .genie/code/workflows/ | grep -i commit`
-
-### Step 2: Search Git History
-
-**Check if file existed before (deleted, renamed, moved):**
-```bash
-# Find deleted files matching pattern
-git log --all --full-history --diff-filter=D --summary | grep <filename>
-
-# Check if file was renamed/moved
-git log --all --follow -- <potential-path>
-
-# See file history if exists
-git log --oneline -- .genie/<file>
-```
-
-**Why:** Prevents recreating deleted files, reveals past decisions
-
-### Step 3: Check References in Framework
-
-**Search core files for mentions:**
-```bash
-# Check AGENTS.md
-grep -i "<topic>" AGENTS.md
-
-# Check CLAUDE.md
-grep -i "<topic>" CLAUDE.md
-
-# Check all @ references
-grep "@.*<topic>" .genie/**/*.md
-```
-
-**Why:** File may be referenced but not exist (intentional), or exist under different name
-
-### Step 4: Verify Necessity
-
-**Ask before creating:**
-- ✅ Can I update an existing file instead?
-- ✅ Is this a duplicate of existing content?
-- ✅ Does this belong in an existing spell/agent/workflow?
-- ✅ Is this temporary (should go to `/tmp/genie/` instead)?
-- ✅ Will this be loaded every session (permanent) or once (ephemeral)?
-
-**Classification:**
-- **Permanent consciousness** → `.genie/` (committed, loaded by users)
-- **Scratch thinking** → `/tmp/genie/` (never committed, deleted after session, organized)
-- **Evidence/reports** → `.genie/reports/` (committed, loaded on-demand only)
-
-### Step 5: Measure Context Impact
-
-**Calculate lines added:**
-```bash
-# Before creating file
-wc -l .genie/**/*.md | tail -1  # Total lines
-
-# After creating file
-wc -l .genie/**/*.md | tail -1  # New total
-
-# Difference = your impact
-```
-
-**Token count (REQUIRED):**
-```bash
-# NEVER manually calculate tokens - use the helper
-genie helper count-tokens <new-file>.md
-
-# Compare against current total
-genie helper count-tokens --before=old-version.md --after=new-file.md
-```
-
-**Uses tiktoken (cl100k_base)** - Same encoding Claude uses for accurate counts.
-
-**Quality gate:** If adding >500 lines or >4000 tokens, justify why this much context is needed
-
-## Real-World Violation
-
-**Context:** Creating `.genie/.session` for session state tracking
-
-**What Happened:**
-```bash
-# Genie created new file without checking
-touch .genie/.session
-# Wrote session state content
-```
-
-**User feedback:** "i didnt know this file existed, you mustve migrated it while i was out... dont leave trash behind.. you must keep track of your context growth"
-
-**What Should Have Happened:**
-```bash
-# Step 1: Check existing patterns
-ls .genie/ | grep -i state
-# Output: STATE.md
-
-# Step 2: Read existing file
-cat .genie/STATE.md
-# Discovery: Session state already tracked here!
-
-# Step 3: Decision
-# Update STATE.md instead of creating .genie/.session
-```
-
-**Result:** No duplicate file, no confusion, no context bloat
-
-## Checklist Before Creating ANY File
-
-- [ ] **Step 1:** Did I check existing patterns with `ls` and `grep`?
-- [ ] **Step 2:** Did I search git history for deleted/renamed versions?
-- [ ] **Step 3:** Did I check AGENTS.md/CLAUDE.md for references?
-- [ ] **Step 4:** Can I update existing file instead of creating new one?
-- [ ] **Step 5:** Did I measure context impact (lines/tokens added)?
-- [ ] **Classification:** Is this permanent (`.genie/`) or scratch (`/tmp/genie/`)?
-- [ ] **Justification:** Can I explain why this NEW file is necessary?
-
-## Special Cases
-
-### Creating Reports
-
-**Reports are evidence, not documentation:**
-```bash
-# ✅ Right place
-.genie/reports/learn/<topic>-YYYYMMDD.md  # Evidence of learning
-.genie/qa/evidence/<test>-YYYYMMDD.md    # Evidence of QA run
-
-# ❌ Wrong place
-.genie/<topic>-report.md                  # Not a report, it's documentation
-```
-
-**Why:** Reports are timestamped artifacts, documentation is living content
-
-### Creating Spells vs Workflows
-
-**Spell = behavioral pattern (on-demand):**
-```
-.genie/spells/delegate-dont-do.md         # Load when needed
-```
-
-**Workflow = deterministic sequence (auto-loaded):**
-```
-.genie/code/workflows/wish.md             # Always loaded for code collective
-```
-
-**Check before creating:**
-- Is this on-demand knowledge (spell) or always-needed process (workflow)?
-- Does a similar spell/workflow already exist?
-
-## Context Growth Tracking
-
-**Measure growth over time:**
-```bash
-# See file size trends
-git log --oneline --stat -- .genie/ | grep -E 'files? changed'
-
-# Find largest files
-find .genie/ -name "*.md" -exec wc -l {} \; | sort -rn | head -20
-
-# Calculate total token count (NEVER manually estimate)
-genie helper count-tokens <file>.md
-
-# Or check entire codebase token usage
-node .genie/scripts/token-efficiency/count-tokens.cjs
-# Generates: .genie/state/token-usage.json
-```
-
-**Amendment #6 (Token Efficiency):** Stay lean or nobody wants me
-
-**Token Counting Rule:** ALWAYS use `genie helper count-tokens` - NEVER manually calculate tokens
-
-## Evidence
-
-**Origin:** Learning #4 from `learn.md` lines 123-128
-**Teaching:** "dont leave trash behind.. you must keep track of your context growth, as well as code growth, it should be perfectly organized no duplicates, redundancies"
-**Violation:** Creating `.genie/.session` without checking for existing state tracking (`.genie/STATE.md`)
-**Evidence:** `.genie/reports/learn/never-leave-trash-behind-20251023.md`
-
-## Related
-
-- `AGENTS.md` Amendment #6 - Token Efficiency (Fast, Fit, Smart, Sexy)
-- `AGENTS.md` Amendment #8 - File Creation Discipline (to be added)
-- `.genie/spells/learn.md` - Surgical edits, anti-patterns section