pgserve 2.1.2 → 2.2.0

package/.genie/spells/wish-initiation.md

@@ -1,158 +0,0 @@
-# Rule #2: Wish Initiation (Behavioral Spell)
-
-
-**CRITICAL RULE:** All significant work must start with a wish document. Work done without a wish = framework violation.
-
-## What Qualifies as "Significant"
-
-Work is significant if ANY of these apply:
-- ✅ Multi-part tasks (≥2 distinct groups)
-- ✅ Multi-file changes (≥3 files touched)
-- ✅ Architectural decisions (routing, priorities, structure)
-- ✅ Time investment (≥1 hour estimated)
-- ✅ Framework changes (affects multiple agents/workflows)
-- ✅ User request explicitly scoped (clear goals/outputs)
-
-## Why This Rule Exists
-
-**Problem it solves:**
-1. **Evidence tracking:** Wish documents preserve execution groups, decisions, outcomes
-2. **Context preservation:** Session restart doesn't lose work progress
-3. **Audit trail:** Clear proof of what was done, why, and evidence
-4. **Streamlined workflow:** Plan → Wish → Forge → Review becomes automatic
-5. **Team visibility:** Other agents know what's in progress
-
-**What happens without it:**
-- ❌ Work scattered across session (no formal grouping)
-- ❌ Context lost on session restart
-- ❌ No evidence aggregation (efforts forgotten)
-- ❌ Framework workflow broken (skipped Wish phase)
-- ❌ No Done Report (completion not documented)
-
-## How to Apply This Rule
-
-### BEFORE Starting Work
-
-**Checklist:**
-- [ ] Is this significant? (check list above)
-- [ ] If YES → Create wish FIRST
-- [ ] If NO → Continue with simple task
-
-**Creating a wish:**
-```bash
-mkdir -p .genie/wishes/<slug>/
-cat > .genie/wishes/<slug>/<slug>-wish.md << 'EOF'
-# Wish: [Title]
-
-## Context Ledger
-- Problem: [what needs fixing]
-- Goal: [what we'll deliver]
-- Timeline: [estimate]
-
-## Execution Groups
-### Group A: [Phase 1]
-- Task 1
-- Task 2
-
-### Group B: [Phase 2]
-- Task 1
-
-## Evidence Checklist
-- [ ] Deliverable 1
-- [ ] Deliverable 2
-EOF
-```
-
-### AFTER Work Completes
-
-**Update wish with:**
-- [x] All groups marked completed
-- [x] Evidence checklist filled
-- [x] Done Report path documented
-- [x] Lessons learned section updated
-
-## Examples
-
-### ✅ CORRECT: Wish Created First
-
-```
-User: "I want to analyze and prioritize our 30 spells"
-Me: "Great! Let me create a wish for this..."
-[Create: spells-prioritization-wish.md]
-"I've set up groups: Analysis, Automation, Docs, Testing"
-[Execute groups]
-[Close wish with evidence]
-```
-
-### ❌ WRONG: Work Done, Then Wish Created
-
-```
-User: "I want to analyze and prioritize our 30 spells"
-Me: [Works for 2 hours]
-[Creates wish AFTER work is done]
-← VIOLATION: Broke Plan → Wish → Forge → Review flow
-```
-
-### ✅ CORRECT: Simple Task (No Wish Needed)
-
-```
-User: "What's the token count for AGENTS.md?"
-Me: "Let me check..."
-[runs: genie helper count-tokens AGENTS.md]
-Me: "5,686 tokens (23KB, 618 lines) using tiktoken cl100k_base encoding"
-← No wish needed: simple informational task
-```
-
-## Validation Before Committing
-
-**Never commit work without verifying:**
-- [ ] Wish created (if significant)
-- [ ] All execution groups documented
-- [ ] Evidence checklist completed
-- [ ] Done Report path in wish
-- [ ] Lessons learned section filled
-- [ ] No framework violations
-
-**If wish missing on significant work:**
-1. Create wish retroactively (acknowledge violation)
-2. Document why (learning entry)
-3. Invoke learn agent to propagate lesson
-4. Commit with violation note
-
-## Example Violation & Fix
-
-**Violation (2025-10-18):**
-- Spells prioritization work executed for 2+ hours
-- No wish created at start
-- Evidence scattered across session
-
-**Fix:**
-- Created wish: `.genie/wishes/spells-prioritization/spells-prioritization-wish.md`
-- Documented all groups and deliverables
-- Added lessons learned: Rule #2 violation
-- Invoked learn agent → created this spell
-- Committed: "feat: document Rule #2 + fix spells prioritization violation"
-
-## Anti-Patterns to Avoid
-
-❌ **"It's just a quick thing"** → If it touches >2 files, create wish
-❌ **"I'll create the wish after"** → Defeats the purpose (context already lost)
-❌ **"No one will notice"** → Framework depends on this discipline
-❌ **"This is too simple for a wish"** → If ≥2 hours or ≥3 files, document it
-❌ **"I'll remember what we did"** → Session ends, memory lost
-
-## Integration with Framework
-
-**This spell is:**
-- **Tier 3 (System Coordination):** Auto-loaded every session
-- **Enforced by:** Meta-learn protocol (corrections documented)
-- **Verified by:** Review + qa agents
-- **Result:** All significant work has formal tracking
-
----
-
-**Status:** Active behavioral rule (all future work must follow)
-**Violation handling:** Retroactive wish + learn agent invocation
-**Framework impact:** CRITICAL - enables streamlined Plan → Wish → Forge → Review
-
-**Remember:** The Genie framework depends on this. Every user request must streamline through the wish system. No exceptions.

package/.genie/spells/wish-issue-linkage.md

@@ -1,410 +0,0 @@
-# Rule #6: Wish-Issue Linkage (Behavioral Spell)
-
-**Created:** 2025-10-20
-**Priority:** CRITICAL
-**Learn Session:** c873572f-fd95-4ea0-a0c9-cdaed1dda898
-
-**CRITICAL RULE:** Every wish MUST link to a GitHub issue. No issue → no wish creation.
-
----
-
-## The Core Principle
-
-**Before ANY wish document is created:**
-1. GitHub issue MUST exist
-2. Issue number MUST be validated
-3. Issue link MUST be in wish front-matter
-
-**No exceptions.** This is mandatory for all wish workflows.
-
----
-
-## Why This Rule Exists
-
-### Problem it Solves
-
-**Without issue linkage:**
-- ❌ No team visibility (non-Genie users don't know what's planned)
-- ❌ No approval checkpoint (work may be rejected after implementation)
-- ❌ No audit trail (work history scattered across systems)
-- ❌ No search/discovery (GitHub search can't find wishes)
-- ❌ No permalink stability (wishes live in .genie/, may move)
-
-**With issue linkage:**
-- ✅ Team visibility (everyone sees what's being worked on)
-- ✅ Approval gates (issue discussion before implementation starts)
-- ✅ Complete audit trail (issue → wish → forge task → PR → merge)
-- ✅ Searchable history (GitHub search finds all work)
-- ✅ Stable permalinks (issue #XXX never changes)
-
-### Architectural Hierarchy
-
-```
-GitHub Issue (Public, Permanent)
-    ↓
-Wish Document (Internal Planning)
-    ↓
-Forge Task (Execution Tracking)
-    ↓
-Git Branch + Worktree (Implementation)
-    ↓
-Pull Request (Review + Merge)
-```
-
-**Each level links to parent:**
-- Wish → Issue #XXX
-- Forge task → Issue #XXX + Wish path
-- Branch → forge/XXXX-kebab-case (derived from task)
-- PR → Closes #XXX
-
----
-
-## How To Apply This Rule
-
-### Step 1: Issue Validation (BEFORE Discovery)
-
-**When user requests wish creation:**
-
-```typescript
-// Genie MUST check:
-const issueProvided = userInput.includes('#') || userInput.includes('issue');
-
-if (!issueProvided) {
-  // Ask user for issue number
-  await ask("Is there a GitHub issue for this? If yes, provide #XXX. If no, I'll create one.");
-}
-
-// Validate issue exists
-const issue = await gh.issue.get(issueNumber);
-if (!issue) {
-  // Route to issue creation workflow
-  await createIssueFirst();
-}
-```
-
-**BLOCK wish creation until issue confirmed.**
-
-### Step 2: Issue Creation (If Missing)
-
-If no issue exists, route to issue creation:
-
-```markdown
-**Issue Creation Checklist:**
-1. Ask user: "Should I create GitHub issue first?"
-2. Gather context:
-   - Title (clear, actionable)
-   - Description (context ledger summary)
-   - Labels (wish, enhancement, bug, etc.)
-   - Acceptance criteria
-3. Create issue via GitHub API:
-   \`gh issue create --title "..." --body "..." --label wish\`
-4. Extract issue number from response
-5. THEN proceed to wish creation
-```
-
-### Step 3: Wish Document Linkage
-
-Every wish document MUST include issue reference:
-
-```markdown
-# Wish: <Title>
-
-**GitHub Issue:** #152  <-- MANDATORY FIELD
-**Status:** Discovery
-**Created:** !`date -u +"%Y-%m-%d"`
-**Forge Task:** (filled after task creation)
-
-## Context Ledger
-
-**Origin:** GitHub Issue #152
-**Problem:** [from issue description]
-...
-```
-
-### Step 4: Forge Task Linkage
-
-When creating wish with task:
-
-```typescript
-await mcp__genie__create_wish({
-  feature: "MCP Server Authentication",
-  github_issue: 152  // Issue number required!
-});
-
-// Or run forge task directly:
-await mcp__genie__run_forge({
-  agent: "implementor",
-  prompt: `
-    **GitHub Issue:** #152
-    **Wish Document:** @.genie/wishes/mcp-auth/mcp-auth-wish.md
-
-    [Full wish context from issue]
-  `
-});
-```
-
----
-
-## Integration With Existing Workflows
-
-### Wish Workflow Enhancement
-
-**Add Step 0 (NEW) before Discovery:**
-
-```markdown
-### Step 0: Issue Validation
-**Goal:** Ensure GitHub issue exists before starting wish dance
-
-**Process:**
-1. Check if user provided issue number
-2. If YES:
-   - Validate issue exists: \`gh issue view #XXX\`
-   - Extract context from issue
-   - Proceed to Step 1 (Discovery)
-3. If NO:
-   - Ask: "Should I create a GitHub issue first?"
-   - If user says yes → delegate to issue-creation workflow
-   - If user says no → BLOCK wish creation, explain rule
-
-**Delegation:**
-\`\`\`
-mcp__genie__run with agent="issue-check" prompt="Validate issue #XXX exists"
-\`\`\`
-
-**Output:** Issue number + issue context + "Ready for discovery?"
-```
-
-### Blueprint Workflow Enhancement
-
-**Update wish document template:**
-
-```markdown
-**Required front-matter fields:**
-- GitHub Issue: #XXX  <-- MUST be filled
-- Forge Task: <task_id>  <-- Auto-filled after creation
-- Status: Discovery/In-Progress/Review/Done
-- Created: !`date`
-```
-
----
-
-## Enforcement Mechanism
-
-### Pre-Creation Check
-
-**In wish.md orchestrator:**
-```typescript
-// BEFORE starting wish dance
-async function validateIssueExists(userRequest: string): Promise<IssueValidation> {
-  const issueMatch = userRequest.match(/#(\d+)/);
-
-  if (!issueMatch) {
-    return {
-      valid: false,
-      reason: "No issue number provided",
-      action: "prompt_user_for_issue"
-    };
-  }
-
-  const issueNumber = issueMatch[1];
-  const issue = await gh.issue.get(issueNumber);
-
-  if (!issue) {
-    return {
-      valid: false,
-      reason: `Issue #${issueNumber} does not exist`,
-      action: "create_issue_first"
-    };
-  }
-
-  return {
-    valid: true,
-    issue: issue,
-    issueNumber: issueNumber
-  };
-}
-```
-
-### Post-Creation Validation
-
-**In review.md agent:**
-```typescript
-// Validate wish document has issue link
-async function validateWishDocument(wishPath: string): Promise<boolean> {
-  const content = await fs.readFile(wishPath, 'utf-8');
-  const hasIssueLink = /\*\*GitHub Issue:\*\* #\d+/.test(content);
-
-  if (!hasIssueLink) {
-    throw new Error(`Wish ${wishPath} missing GitHub issue link! Rule #6 violation.`);
-  }
-
-  return true;
-}
-```
-
----
-
-## Examples
-
-### ✅ CORRECT: Issue First, Then Wish
-
-```
-User: "I want to add MCP authentication"
-
-Genie: "Great idea! Is there a GitHub issue for this?"
-User: "Yes, #152"
-
-Genie: [Validates #152 exists]
-Genie: "Perfect! Issue #152 confirmed. Let's start the wish dance..."
-[Creates wish with GitHub Issue: #152]
-[Links Forge task to #152]
-```
-
-### ✅ CORRECT: Create Issue First
-
-```
-User: "I want to unify the naming taxonomy"
-
-Genie: "Excellent! I don't see a GitHub issue for this. Should I create one first?"
-User: "Yes please"
-
-Genie: [Creates issue #155 via gh CLI]
-Genie: "Issue #155 created! Now let's create the wish..."
-[Creates wish with GitHub Issue: #155]
-```
-
-### ❌ WRONG: Wish Without Issue
-
-```
-User: "Create a wish for voice agent transformation"
-
-Genie: [Creates wish document immediately]  <-- VIOLATION!
-Genie: [No issue link in wish]  <-- VIOLATION!
-
-← This breaks Rule #6. MUST validate/create issue FIRST.
-```
-
----
-
-## Spell Metadata
-
-**Spell Type:** Behavioral (Tier 6 - Workflow & State Management)
-**Auto-loaded:** YES (every session)
-**Enforced by:** wish.md orchestrator, review.md validator
-**Violation handling:** BLOCK wish creation, route to issue-creation
-**Related spells:**
-- Rule #2: Wish Initiation (`@.genie/spells/wish-initiation.md`)
-- Wish Document Management (`@.genie/spells/wish-lifecycle.md`)
-- Persistent Tracking Protocol (`@.genie/spells/track-long-running-tasks.md`)
-
----
-
-## Anti-Patterns To Avoid
-
-❌ **"The issue is implied"** → No. Explicit link required.
-❌ **"I'll create issue after wish"** → No. Issue FIRST, always.
-❌ **"This is internal work, no issue needed"** → No. All wishes need issues.
-❌ **"Issue creation slows me down"** → Good. Approval gate is intentional.
-❌ **"I forgot to link the issue"** → Fix immediately (retroactive linking).
-
----
-
-## Retroactive Fixes
-
-**If wish exists without issue:**
-1. Create GitHub issue immediately
-2. Update wish document with issue #
-3. Update Forge task title/description with issue #
-4. Add violation note to learn session
-5. Document in meta-learn protocol
-
-**Example:**
-```bash
-# Create missing issue
-gh issue create --title "Wish: Voice Agent Transformation" \
-  --body "$(cat .genie/wishes/voice-agent/voice-agent-wish.md)" \
-  --label wish
-
-# Extract issue number
-ISSUE_NUM=$(gh issue list --limit 1 --json number --jq '.[0].number')
-
-# Update wish document
-sed -i "s/\*\*GitHub Issue:\*\* TBD/**GitHub Issue:** #$ISSUE_NUM/" \
-  .genie/wishes/voice-agent/voice-agent-wish.md
-
-# Document violation
-echo "Rule #6 violation: Retroactively linked issue #$ISSUE_NUM" >> \
-  .genie/reports/learn-wish-issue-amendment-20251020.md
-```
-
----
-
-## MCP Integration
-
-### Genie Spell Execution Pattern
-
-**Goal:** Genie MCP executes spells dynamically (lighter base prompts)
-
-**How this works:**
-1. Base Genie prompt = thin orchestrator
-2. Spells loaded as @ references (not full content in base prompt)
-3. When wish requested → Genie dynamically loads wish-issue-linkage-rule.md
-4. Spell execution = read file, apply rules, validate
-
-**Benefits:**
-- Lighter base prompts (token efficiency)
-- Spells updated independently (no base prompt changes)
-- Clear separation of concerns (orchestration vs execution)
-
-**Implementation:**
-```typescript
-// In wish.md orchestrator
-async function ensureIssueExists(userRequest: string) {
-  // Load spell dynamically
-  const spell = await loadSkill('@.genie/spells/wish-issue-linkage.md');
-
-  // Execute spell logic
-  const validation = await spell.validateIssue(userRequest);
-
-  if (!validation.valid) {
-    // Route to issue creation
-    return await spell.createIssueFirst(userRequest);
-  }
-
-  return validation.issueNumber;
-}
-```
-
----
-
-## Summary
-
-**Rule #6 in one sentence:**
-> No GitHub issue = no wish creation. Issue first, always.
-
-**Why it matters:**
-- Team visibility (public tracking)
-- Approval gates (discussion before work)
-- Audit trail (complete history)
-- Search/discovery (GitHub search works)
-- Permalink stability (issue # never changes)
-
-**How to follow:**
-1. Check if issue exists
-2. If not → create issue first
-3. Link issue # in wish front-matter
-4. Link issue # in Forge task
-5. Close issue when PR merges
-
-**Enforcement:**
-- wish.md blocks creation without issue
-- review.md validates issue link exists
-- Meta-learn tracks violations
-
----
-
-**Status:** Active behavioral rule (all future wishes must follow)
-**Violation handling:** BLOCK + route to issue creation
-**Framework impact:** CRITICAL - enables public visibility + audit trail
-
-**Remember:** GitHub is source of truth. Wishes are implementation plans. Forge tasks are execution. All three MUST link together.

package/.genie/spells/wish-lifecycle.md

@@ -1,100 +0,0 @@
----
-name: Wish Document Management
-description: Keep wishes as living blueprints with orchestration strategy and evidence
----
-
-# Wish Document Management
-
-**Purpose:** Wish documents are living blueprints; maintain clarity from inception to closure.
-
-## Success Criteria
-
-✅ Wish contains orchestration strategy, agent assignments, evidence log.
-✅ Done Report references appended with final summary + remaining risks.
-✅ No duplicate wish documents created.
-
-## Multi-Stage Investigation Pattern (RECOMMENDED)
-
-**Pattern:** Investigation → Pre-Wish → Wish Creation
-
-**When to use:** Complex features requiring architectural decisions, risk assessment, or significant implementation effort.
-
-**Benefits:**
-- Surface all risks, benefits, and trade-offs BEFORE committing to implementation
-- Pre-wish summary provides TL;DR + decision matrix for stakeholder buy-in
-- Wish document becomes comprehensive single source of truth
-- Learn task tracks knowledge gained throughout investigation
-
-### Phase 1: Investigation
-**Objective:** Deep analysis and proof-of-concept validation
-
-**Deliverables:**
-- Multiple investigation reports (API validation, comparisons, strategies, test plans)
-- Proof-of-concept implementation (if applicable)
-- Risk assessment and trade-off analysis
-- Technical feasibility validation
-
-**Example (Issue #120):**
-- 7 investigation reports (~5,000 lines total)
-- POC: forge-executor.ts (300 lines, working implementation)
-- Risk/benefit analysis across multiple dimensions
-
-### Phase 2: Pre-Wish Summary
-**Objective:** Decision-making checkpoint with stakeholder visibility
-
-**Deliverables:**
-- TL;DR executive summary (2-3 paragraphs)
-- Decision matrix (pros/cons/risks/benefits)
-- Go/No-Go recommendation with confidence score
-- Resource requirements and timeline estimate
-
-**Decision Matrix Elements:**
-- Ease analysis: How difficult is the change?
-- Replacement mapping: What gets deleted, what gets added?
-- Risk assessment: What could go wrong?
-- Benefit quantification: What improves and by how much?
-
-### Phase 3: Wish Creation
-**Objective:** Comprehensive implementation blueprint
-
-**Deliverables:**
-- Complete wish document with multiple implementation groups
-- Phased rollout strategy (Group A → B → C → D)
-- Timeline with milestones
-- Success criteria and validation checkpoints
-
-**Example Structure (Issue #120):**
-- 4 implementation groups (A: Core, B: Streaming, C: Advanced, D: Testing)
-- 4-week timeline with phased rollout
-- Clear success metrics per group
-
-## Evidence Tracking
-
-**During Investigation:**
-- Document all findings in `.genie/reports/` with descriptive names
-- Track investigation progress in learning task (Forge)
-- Update pre-wish summary as understanding evolves
-
-**During Wish Creation:**
-- Reference investigation reports in wish document
-- Include decision rationale with evidence pointers
-- Document assumptions and risks with supporting evidence
-
-**After Implementation:**
-- Append Done Report to wish with final outcomes
-- Document deviations from plan with justification
-- Record lessons learned for future similar wishes
-
-## Anti-Patterns
-
-❌ **Jumping to Wish without investigation:** Creates incomplete requirements, missed risks
-❌ **Investigation without decision checkpoint:** Wastes effort on exploratory work without commitment
-❌ **Wish creation without stakeholder buy-in:** Implementation starts without alignment
-❌ **No evidence tracking:** Decisions lack justification, can't validate assumptions later
-
-## Evidence
-
-**Pattern discovered:** Issue #120 investigation → wish creation flow (2025-10-18 09:00-13:15 UTC)
-- Learn task session tracked entire investigation process
-- Pre-wish summary enabled quick decision (9.2/10 - STRONG YES)
-- Comprehensive wish enabled focused implementation planning

package/.genie/state/provider-status.json

@@ -1,3 +0,0 @@
-{
-  "entries": []
-}

package/.genie/state/version.json

@@ -1,16 +0,0 @@
-{
-  "version": "2.5.27-rc.4",
-  "installedAt": "2025-11-23T13:42:06.789Z",
-  "updatedAt": "2025-11-23T13:42:06.789Z",
-  "commit": "98eb883",
-  "packageName": "automagik-genie",
-  "customizedFiles": [],
-  "deletedFiles": [],
-  "lastUpgrade": null,
-  "previousVersion": null,
-  "upgradeHistory": [],
-  "migrationInfo": {
-    "backupId": "n/a",
-    "claudeBackedUp": false
-  }
-}