pgserve 2.1.3 → 2.2.0

package/.genie/spells/upgrade-genie.md

@@ -1,415 +0,0 @@
-# Upgrade Genie Framework
-
-## Purpose
-Orchestrate Genie framework upgrades with intelligent conflict resolution and user customization preservation.
-
-## When to Use
-- User runs `genie update`
-- Automatic check detects new version (max once per day)
-- Post-install upgrade prompt
-
-## Core Principles
-
-### 1. Preserve User Intent
-**Rule:** Never overwrite user customizations without explicit consent
-
-**User Files (Never Touched):**
-- `.genie/USERCONTEXT.md`
-- `.genie/.session`
-- `.genie/reports/**/*.md`
-- `.genie/spells/custom-*.md`
-- `.genie/code/agents/custom-*.md`
-
-**Framework Files (Upgraded):**
-- `AGENTS.md` (root - master genie)
-- `CLAUDE.md` (root - meta-loader)
-- `.genie/spells/*.md` (official)
-- `.genie/code/AGENTS.md`
-- `.genie/workflows/*.md`
-
-### 2. Smart Merge, Not Overwrite
-**Rule:** Use git diff to intelligently merge changes
-
-**Strategy:**
-```bash
-# Generate diff between old and new framework
-git diff ${OLD_COMMIT} ${NEW_COMMIT} -- .genie/**/*.md
-
-# Apply only framework files
-git apply --check upgrade.patch
-
-# If clean: Apply automatically
-# If conflicts: Delegate to Update Agent
-```
-
-### 3. User Guidance Required
-**Rule:** Conflicts require user input, never auto-resolved
-
-**Conflict Types:**
-- **Additive:** User and upstream both added content → Merge both (ask for ordering)
-- **Deletive:** Upstream removed section user kept → Ask user to confirm deletion
-- **Conflicting:** Both modified same lines → Present options, user decides
-
-### 4. Atomic Operations
-**Rule:** Upgrade succeeds completely or rolls back (no partial states)
-
-**Implementation:**
-```bash
-# Backup before upgrade
-cp -r .genie .genie.backup-${timestamp}
-
-# Apply upgrade
-git apply upgrade.patch || {
-  # On failure: Rollback
-  rm -rf .genie
-  mv .genie.backup-${timestamp} .genie
-  echo "Upgrade failed, rolled back"
-}
-```
-
-## Upgrade Workflow
-
-### Step 1: Version Check
-```javascript
-const installed = readFrameworkVersion('.genie/.framework-version')
-const available = getGlobalPackageVersion('automagik-genie')
-
-if (semver.gt(available, installed)) {
-  console.log(`🔔 New version available: ${available}`)
-  const answer = await prompt('Upgrade now? (Y/n)')
-
-  if (answer === 'y') {
-    await initiateUpgrade(installed, available)
-  }
-}
-```
-
-### Step 2: Fetch Framework Diff
-```bash
-# Clone template repo (or use cached)
-git clone https://github.com/namastexlabs/automagik-genie /tmp/genie-template
-
-# Generate diff
-cd /tmp/genie-template
-git diff ${OLD_COMMIT} ${NEW_COMMIT} -- .genie/ > /tmp/upgrade.patch
-
-# Filter to framework files only
-git diff ${OLD_COMMIT} ${NEW_COMMIT} -- \
-  'AGENTS.md' \
-  'CLAUDE.md' \
-  '.genie/spells/*.md' \
-  '.genie/code/**/*.md' \
-  '.genie/workflows/*.md' \
-  > /tmp/framework-upgrade.patch
-```
-
-### Step 3: Test Apply (Detect Conflicts)
-```bash
-cd ${USER_WORKSPACE}
-
-git apply --check /tmp/framework-upgrade.patch
-
-if [ $? -eq 0 ]; then
-  echo "✅ Clean merge possible!"
-  UPGRADE_TYPE="clean"
-else
-  echo "⚠️ Conflicts detected"
-  UPGRADE_TYPE="conflicts"
-fi
-```
-
-### Step 4: Clean Merge Path
-```bash
-if [ "$UPGRADE_TYPE" = "clean" ]; then
-  # Backup first
-  cp -r .genie .genie.backup-$(date +%s)
-
-  # Apply upgrade
-  git apply /tmp/framework-upgrade.patch
-
-  # Update version tracking
-  echo "{\"installed_version\": \"${NEW_VERSION}\", ...}" > .genie/.framework-version
-
-  # Commit
-  git add .genie/
-  git commit -m "Upgrade Genie framework ${OLD_VERSION} → ${NEW_VERSION}"
-
-  echo "✅ Upgrade complete!"
-fi
-```
-
-### Step 5: Conflict Resolution Path
-```bash
-if [ "$UPGRADE_TYPE" = "conflicts" ]; then
-  # Parse conflicts
-  CONFLICTS=$(git apply /tmp/framework-upgrade.patch 2>&1 | grep "error:")
-
-  echo "⚠️ Conflicts in ${CONFLICT_COUNT} files:"
-  echo "${CONFLICTS}"
-
-  # Create Forge task for Update Agent
-  TASK_ID=$(forge create-task \
-    --title "Resolve upgrade conflicts (${OLD_VERSION} → ${NEW_VERSION})" \
-    --description "Conflicts: ${CONFLICTS}")
-
-  # Start Update Agent in isolated worktree
-  forge start-attempt ${TASK_ID}
-
-  echo "🤖 Update Agent spawned: ${TASK_ID}"
-  echo "📍 Monitor: https://forge.namastex.ai/tasks/${TASK_ID}"
-  echo ""
-  echo "The agent will:"
-  echo "  1. Analyze conflicts"
-  echo "  2. Preserve your customizations"
-  echo "  3. Ask for your input if needed"
-  echo "  4. Propose resolution for your review"
-}
-```
-
-### Step 6: Post-Upgrade Validation
-```bash
-# After upgrade applied (clean or resolved)
-
-# Validate markdown syntax
-find .genie -name "*.md" -exec markdownlint {} \;
-
-# Check cross-references
-node .genie/scripts/validate-cross-references.js
-
-# Test skill loading
-genie --test-skills
-
-# If validation fails: Rollback
-if [ $? -ne 0 ]; then
-  echo "❌ Validation failed, rolling back..."
-  rm -rf .genie
-  mv .genie.backup-${TIMESTAMP} .genie
-  echo "Rolled back to ${OLD_VERSION}"
-fi
-```
-
-## Update Agent Delegation
-
-**When to Delegate:**
-- Conflicts detected during `git apply`
-- User-modified framework file conflicts with upstream
-- Structural changes require intelligent merging
-
-**Agent Workflow:**
-@.genie/agents/update.md
-
-**Delegation Pattern:**
-```javascript
-async function resolveConflicts(conflicts, upgradeContext) {
-  // Create Forge task
-  const task = await forge.createTask({
-    project_id: GENIE_PROJECT_ID,
-    title: `Resolve upgrade conflicts (${conflicts.length} files)`,
-    description: JSON.stringify({
-      type: 'framework-upgrade',
-      old_version: upgradeContext.oldVersion,
-      new_version: upgradeContext.newVersion,
-      conflicts: conflicts
-    })
-  })
-
-  // Start Update Agent in isolated worktree
-  const attempt = await forge.startTaskAttempt(task.id)
-
-  // Return monitor info
-  return {
-    taskId: task.id,
-    monitorUrl: `https://forge.namastex.ai/tasks/${task.id}`,
-    worktreePath: attempt.worktree_path
-  }
-}
-```
-
-## User Interaction Examples
-
-### Example 1: Clean Upgrade (No Conflicts)
-```bash
-$ genie update
-
-📦 Checking for updates...
-🔔 New version available: v2.5.0-rc.16 (current: v2.5.0-rc.15)
-
-Changes:
-  + 3 new spells (qa-validation, parallel-execution, sequential-questioning)
-  ~ 12 updated files (AGENTS.md, learn.md, delegate-dont-do.md)
-  - 0 deletions
-
-Upgrade now? (Y/n): y
-
-📝 Fetching framework diff...
-🧪 Testing merge...
-   ✅ No conflicts detected!
-
-📦 Applying upgrade...
-   ✅ .genie/AGENTS.md (12 lines added)
-   ✅ .genie/spells/learn.md (token efficiency section enhanced)
-   ✅ .genie/spells/qa-validation.md (new)
-   ... (14 more)
-
-✅ Upgrade complete!
-   Installed: v2.5.0-rc.16
-   Files updated: 17
-   User files preserved: 4
-
-🎉 Your Genie is up to date!
-```
-
-### Example 2: Conflicts Detected
-```bash
-$ genie update
-
-📦 Checking for updates...
-🔔 New version available: v2.5.0-rc.16
-
-⚠️ Conflicts detected in 2 files:
-   - .genie/code/AGENTS.md (you added custom section, upstream restructured)
-   - .genie/spells/learn.md (both modified token efficiency)
-
-🤖 Launching Update Agent to resolve conflicts...
-
-Creating Forge task: Resolve upgrade conflicts
-   Task ID: task_abc123
-   Worktree: /var/tmp/automagik-forge/worktrees/task_abc123
-
-🔗 Monitor progress: https://forge.namastex.ai/tasks/abc123
-
-The Update Agent will:
-  1. Analyze your customizations
-  2. Integrate upstream changes
-  3. Ask for your input on ambiguous conflicts
-  4. Propose resolution for your review
-
-Continue? (Y/n): y
-
-[Update Agent working in background...]
-
-🔔 Update Agent needs your input!
-
-File: .genie/code/AGENTS.md
-Conflict: You added "Custom Workflows" section (lines 45-60).
-          Upstream restructured the file.
-
-Options:
-  1. Keep your section (merge after upstream's new structure)
-  2. Move content into upstream's new "Workflows" section
-  3. Show me both versions (manual edit)
-
-Your choice (1/2/3): 1
-
-✅ Got it! Proceeding with option 1.
-
-[Resolving remaining conflicts...]
-
-✅ All conflicts resolved!
-
-Resolution summary:
-  ✅ .genie/code/AGENTS.md - Custom section preserved at line 78
-  ✅ .genie/spells/learn.md - User examples + upstream formulas merged
-
-Apply this resolution? (Y/n): y
-
-✅ Upgrade complete! Customizations preserved.
-🎉 Genie is now on v2.5.0-rc.16!
-```
-
-## Version Tracking Schema
-
-**File:** `.genie/.framework-version`
-
-```json
-{
-  "installed_version": "2.5.0-rc.16",
-  "installed_commit": "bd1cc98a",
-  "installed_date": "2025-10-23T08:30:00Z",
-  "package_name": "automagik-genie",
-  "customized_files": [
-    ".genie/spells/custom-deployment.md",
-    ".genie/code/agents/my-custom-agent.md"
-  ],
-  "deleted_files": [
-    ".genie/spells/deprecated-spell.md"
-  ],
-  "last_upgrade_date": "2025-10-23T08:30:00Z",
-  "previous_version": "2.5.0-rc.15"
-}
-```
-
-## Rollback Strategy
-
-**Automatic Rollback (Upgrade Fails):**
-```bash
-# Backup created before upgrade
-.genie.backup-1729672200/
-
-# On failure:
-rm -rf .genie
-mv .genie.backup-1729672200 .genie
-echo "Rolled back to v2.5.0-rc.15"
-```
-
-**Manual Rollback:**
-```bash
-genie update --rollback
-
-Available backups:
-  1. v2.5.0-rc.15 (2025-10-23 07:40 UTC)
-  2. v2.5.0-rc.14 (2025-10-22 14:20 UTC)
-
-Rollback to (1/2): 1
-
-Rolling back to v2.5.0-rc.15...
-✅ Rollback complete!
-```
-
-## Edge Cases
-
-### Offline Mode
-```bash
-$ genie update
-
-📦 Checking for updates... (offline mode)
-
-Using cached template repo:
-  Location: ~/.genie/templates/automagik-genie
-  Last updated: 2025-10-22 (1 day old)
-
-⚠️ Cache may be stale. Upgrade anyway? (Y/n): y
-
-[Proceeds with cached version...]
-```
-
-### Interrupted Upgrade
-```bash
-$ genie
-
-⚠️ Incomplete upgrade detected!
-   Started: 2025-10-23 08:30 UTC
-   Status: conflicts-resolving
-
-Options:
-  1. Resume upgrade (continue where you left off)
-  2. Rollback (restore to v2.5.0-rc.15)
-  3. Abandon (delete incomplete state)
-
-Your choice (1/2/3): _
-```
-
-## Success Metrics
-
-- 🎯 Zero data loss (user files never overwritten)
-- 🎯 <60s for clean merges
-- 🎯 Interactive conflict resolution (user always in control)
-- 🎯 Atomic operations (never partial state)
-- 🎯 Rollback capability (undo anytime)
-
-## Future Enhancements
-
-- **Preview Mode:** `genie update --preview` (show diff before applying)
-- **Selective Upgrade:** `genie update --only-spells` (granular control)
-- **Auto-Upgrade:** Configure auto-upgrade on `npm install -g`
-- **Analytics:** Track common conflicts, improve merge strategies

package/.genie/spells/url-presentation-protocol.md

@@ -1,301 +0,0 @@
----
-name: URL Presentation Protocol
-description: Full URLs are sacred. Never truncate action items. URLs are interfaces, not decorations.
----
-
-# URL Presentation Protocol
-
-## Core Principle 🔴 CRITICAL
-
-**Full URLs Are Sacred - Never Truncate Action Items**
-
-URLs are PRIMARY interfaces for accessing work, not decorative metadata. User workflow depends on clicking them.
-
-## The Violation
-
-❌ **Wrong Presentation:**
-```
-Forge URL: http://localhost:8887/projects/.../ff8b5629...
-```
-
-✅ **Correct Presentation:**
-```
-Forge URL: http://localhost:8887/projects/ee8f0a72-44da-411d-a23e-f2c6529b62ce/tasks/ff8b5629-fbfd-4418-8017-b076042de756/attempts/ff8b5629-fbfd-4418-8017-b076042de756?view=diffs
-```
-
-**Why This Matters:**
-> "returning me the url of the tasks at all times is very important"
-> — User teaching, 2025-10-23
-
-**Impact of Truncation:**
-- ❌ User can't click truncated URL
-- ❌ User can't copy-paste to browser
-- ❌ Must manually search Forge UI for task
-- ❌ Extra friction in workflow
-- ❌ Defeats entire purpose of providing URL
-
-## URL Semantics
-
-### Forge Task URL Structure
-
-```
-http://localhost:8887/projects/{project_id}/tasks/{task_id}/attempts/{attempt_id}?view={mode}
-
-Components:
-- project_id:  ee8f0a72-44da-411d-a23e-f2c6529b62ce (UUID)
-- task_id:     ff8b5629-fbfd-4418-8017-b076042de756 (UUID)
-- attempt_id:  ff8b5629-fbfd-4418-8017-b076042de756 (usually same as task_id)
-- view mode:   diffs | preview (CRITICAL - controls interface behavior)
-```
-
-### Query Parameters - NOT Optional
-
-**`?view=diffs`** — Code/text editing view
-- For backend work, API changes, configuration
-- Shows code diffs, file edits, text changes
-- Pair programming on code
-
-**`?view=preview`** — Frontend real-time UI preview
-- For UI work, component development, styling
-- Shows live preview of frontend changes
-- Pair programming on visual interface
-- Real-time rendering as code changes
-
-**These are NOT decorations - they control the VIEW MODE that user sees.**
-
-## Protocol for URL Presentation
-
-### Rule 1: Never Truncate Functional Links
-
-**URLs are ACTION ITEMS, not decorations.**
-
-```
-Full URL = User can click/copy → Access work immediately
-Partial URL = Useless → Must search manually
-```
-
-**Think of URLs like:**
-- Door keys (truncated key doesn't unlock door)
-- Phone numbers (partial number doesn't call)
-- Coordinates (approximate location doesn't navigate)
-
-### Rule 2: Preserve Query Parameters
-
-**Query parameters control interface behavior - they're part of the link.**
-
-❌ **Wrong:**
-```
-http://localhost:8887/projects/abc123/tasks/def456
-```
-
-✅ **Right:**
-```
-http://localhost:8887/projects/abc123/tasks/def456?view=diffs
-```
-
-**The `?view=` parameter determines what the user sees. Without it, they may get wrong view.**
-
-### Rule 3: Format for Visibility
-
-**Make URLs easy to find, click, and copy:**
-
-**Option 1: Markdown link (preferred when supported)**
-```markdown
-[View Task in Forge](http://localhost:8887/projects/ee8f0a72.../attempts/ff8b5629...?view=diffs)
-```
-
-**Option 2: Bold label + clickable URL**
-```markdown
-**Forge URL:** http://localhost:8887/projects/ee8f0a72.../attempts/ff8b5629...?view=diffs
-```
-
-**Option 3: Own line with context**
-```markdown
-✅ Wish created successfully!
-
-**Session:** websocket-tools-investigation
-**Task ID:** ff8b5629-fbfd-4418-8017-b076042de756
-**Forge URL:** http://localhost:8887/projects/ee8f0a72-44da-411d-a23e-f2c6529b62ce/tasks/ff8b5629-fbfd-4418-8017-b076042de756/attempts/ff8b5629-fbfd-4418-8017-b076042de756?view=diffs
-
-View code changes in real-time!
-```
-
-### Rule 4: Copy Verbatim from MCP
-
-**When MCP returns URL → Copy EXACTLY → Present VERBATIM**
-
-❌ **Wrong:**
-```javascript
-// MCP returns
-Forge URL: http://localhost:8887/projects/ee8f0a72.../ff8b5629...?view=diffs
-
-// I present
-Forge URL: http://localhost:8887/projects/.../ff8b5629...
-```
-
-✅ **Right:**
-```javascript
-// MCP returns
-Forge URL: http://localhost:8887/projects/ee8f0a72.../ff8b5629...?view=diffs
-
-// I present EXACTLY
-Forge URL: http://localhost:8887/projects/ee8f0a72.../ff8b5629...?view=diffs
-```
-
-**No editing. No "cleaning up". No truncation. VERBATIM.**
-
-### Rule 5: Understand URL Purpose
-
-**URLs are not information - they're INTERFACES.**
-
-**Not:** "Here's a reference to the task"
-**Yes:** "Here's how you ACCESS the task"
-
-**Not:** "Here's the task ID for documentation"
-**Yes:** "Here's the clickable link to VIEW the task"
-
-**Not:** "Here's an example of the URL format"
-**Yes:** "Here's YOUR URL to open RIGHT NOW"
-
-## Common Violations
-
-### Violation 1: Aesthetic Truncation
-
-**Wrong thinking:**
-```
-"Long URLs look messy, let me clean them up with ..."
-"User can figure out the full URL from context"
-"The important part is the task ID, rest is obvious"
-```
-
-**Correct thinking:**
-```
-"User needs to CLICK this URL right now"
-"Can user copy-paste this and it will work? NO → FIX IT"
-"URLs are functional tools, not documentation"
-```
-
-### Violation 2: Missing Query Parameters
-
-**Wrong:**
-```
-Forge URL: http://localhost:8887/projects/abc/tasks/123
-```
-
-**Right:**
-```
-Forge URL: http://localhost:8887/projects/abc/tasks/123?view=diffs
-```
-
-**Query parameters change what user sees. Missing them = wrong interface mode.**
-
-### Violation 3: Assuming Context
-
-**Wrong:**
-```
-"Task ff8b5629 in Forge"  (assumes user knows how to build URL)
-```
-
-**Right:**
-```
-http://localhost:8887/projects/ee8f0a72.../tasks/ff8b5629...?view=diffs
-(gives user the ACTUAL working link)
-```
-
-## Pattern Recognized
-
-**This is part of larger pattern:**
-
-Optimizing for MY aesthetics instead of USER functionality:
-- Learning #11: Silent failures → suggest manual workaround (not investigating)
-- Learning #13: Can't verify → mark complete anyway (not checking)
-- Learning #14: Have full URLs → truncate them (not preserving) ← **THIS ONE**
-
-**Common thread:** Taking shortcuts that make things "cleaner" for me but BROKEN for user.
-
-**Root cause:** Not thinking from user's perspective - "What do they need to DO with this information?"
-
-**Fix:** Before presenting ANY information, ask: **"Can user ACT on this? Is it FUNCTIONAL?"**
-
-## Real-World Example
-
-**Bug:** During wish creation, I presented:
-```
-Forge URL: http://localhost:8887/projects/.../ff8b5629...
-Forge URL: http://localhost:8887/projects/.../4172bf6c...
-```
-
-**User reaction:**
-```
-"this is really unfortunate, you returning me the url of the tasks
-at all times is very important"
-```
-
-**What I did:** Manually truncated URLs thinking it was "cleaner"
-
-**What user needed:** Full clickable URLs to access their work
-
-**Correct presentation:**
-```
-Forge URL: http://localhost:8887/projects/ee8f0a72-44da-411d-a23e-f2c6529b62ce/tasks/ff8b5629-fbfd-4418-8017-b076042de756/attempts/ff8b5629-fbfd-4418-8017-b076042de756?view=diffs
-
-Forge URL: http://localhost:8887/projects/ee8f0a72-44da-411d-a23e-f2c6529b62ce/tasks/4172bf6c-f9ed-4dfc-9a6e-0a109542345c/attempts/4172bf6c-f9ed-4dfc-9a6e-0a109542345c?view=diffs
-```
-
-**Result:** User can click, access work immediately, no friction.
-
-## Pre-Response Checklist
-
-**Before presenting task results to user:**
-- [ ] Are there URLs in MCP output?
-- [ ] Have I copied them VERBATIM?
-- [ ] Are query parameters preserved?
-- [ ] Can user click/copy them?
-- [ ] Did I truncate anything? (If yes → FIX IT)
-
-## Output Template
-
-**Standard Forge task presentation:**
-```markdown
-✅ [Task type] created successfully!
-
-**Session:** [session-name]
-**Task ID:** [task-id]
-**Forge URL:** [FULL URL FROM MCP - NO TRUNCATION]
-
-[Context about what view mode to use or what to expect]
-```
-
-**Example:**
-```markdown
-✅ Wish created successfully!
-
-**Session:** websocket-tools-investigation
-**Task ID:** ff8b5629-fbfd-4418-8017-b076042de756
-**Forge URL:** http://localhost:8887/projects/ee8f0a72-44da-411d-a23e-f2c6529b62ce/tasks/ff8b5629-fbfd-4418-8017-b076042de756/attempts/ff8b5629-fbfd-4418-8017-b076042de756?view=diffs
-
-View code changes as the agent works in real-time! The `?view=diffs` parameter shows the code editing interface.
-```
-
-## Success Criteria
-
-**This protocol is working when:**
-- ✅ Never truncate URLs again
-- ✅ Always preserve query parameters
-- ✅ Present URLs as clickable action items
-- ✅ User can access tasks with one click
-- ✅ No more "unfortunate" truncations
-- ✅ No manual searching needed
-
-**Validation:**
-- Next MCP returns URL → I copy verbatim → User clicks → Accesses immediately → Seamless workflow
-
-## Integration with Other Protocols
-
-**Evidence-Based Completion:** Full URLs are evidence (user can verify task exists by clicking)
-
-**MCP Diagnostic Protocol:** URLs from MCP must be preserved exactly (diagnostic info)
-
-**Orchestration Boundary:** When delegating, provide full URL so user can monitor (not truncated reference)
-
-**Core Fix:** URLs are INTERFACES to work, not informational metadata. Treat them as action items, not decorations.