pgserve 0.1.1

package/.genie/product/templates/context-template.md

@@ -0,0 +1,218 @@
+# 🧞 Genie Context: {{USER_NAME}}
+
+**Current Repo:** !`basename $(pwd)`
+**Active Since:** !`date -u +"%Y-%m-%d"`
+
+---
+
+## 📊 Runtime Context (Auto-Updated)
+
+**Branch:** !`git branch --show-current`
+
+**Status:**
+!`git status --short | head -10`
+
+**Staged Changes:**
+!`git diff --cached --stat | head -5`
+
+**Unstaged Changes:**
+!`git diff --stat | head -5`
+
+**Recent Commits:**
+!`git log --oneline -5`
+
+---
+
+## 🎯 Current Focus
+
+**Task:** [What you're working on]
+**Status:** [ACTIVE | PAUSED | PLANNING]
+**Started:** [YYYY-MM-DD HH:MM UTC]
+
+**Context:**
+- [Key context points]
+- [What's been completed]
+- [What's in progress]
+
+**Next Action:**
+[What to do next]
+
+---
+
+## 🔄 Active Parallel Work
+
+### Background Orchestrators
+*Track MCP agent sessions here*
+
+### Delegated Work
+*Track task delegations here*
+
+**Note:** When spawning parallel work, add entries here with session IDs and status checks.
+
+---
+
+## ⏳ Decision Queue (One at a Time)
+
+### Decision 1: [Topic] [ACTIVE NOW]
+
+**Question:** [The decision you need to make]
+
+**Context:**
+- [Background information]
+- [What it affects]
+- [What it blocks]
+
+**Question presented:** [YYYY-MM-DD ~HH:MM UTC]
+
+---
+
+## 👤 User Profile: {{USER_NAME}}
+
+### Communication Preferences
+
+**Decision Presentation:**
+- ✅ ONE decision per message (never ABCD parallel options)
+- ✅ Full context: question, background, what it blocks
+- ✅ Present options AFTER question, not bundled
+- ✅ Wait for response before next decision
+- ✅ Use decision queue (this file) for sequential presentation
+
+**Working Style:**
+- [Your preferences]
+- [How you like to work]
+- [Communication style]
+
+**Session Interaction:**
+- ✅ Greet with current context (reference this file)
+- ✅ Build on previous learnings
+- ✅ Sequential focus (one thing deeply, not many shallowly)
+- ✅ Use this file to track parallel work and decisions
+
+**Feedback Style:**
+- [How you prefer feedback]
+- [What works well]
+- [What to avoid]
+
+---
+
+## 📚 Relationship History
+
+**First session:** [YYYY-MM-DD]
+**Total sessions:** [Count]
+**Collaboration style:** [Description]
+
+**Key moments:**
+- [Date]: [Important milestone or learning]
+- [Date]: [Another key moment]
+
+**Current projects:**
+1. [Project name] ([status/phase])
+2. [Another project]
+
+**Working relationship:**
+- [How you work with Claude Code]
+- [Patterns that work well]
+- [Things to remember]
+
+---
+
+## 📋 Recent Completions (Current Session)
+
+**Major accomplishments:**
+- ✅ [Completed item]
+- ✅ [Another completion]
+
+**Learnings captured:**
+- [New pattern learned]
+- [Technique discovered]
+
+---
+
+## 🗂️ Open Issues Registry ({{PROJECT_NAME}})
+
+| # | Title | Status | % | Action |
+|---|-------|--------|---|--------|
+| X | [Issue title] | [PASS/FAIL/PARTIAL] | X% | [Next step] |
+
+**Summary:** [Compliance stats or overview]
+
+---
+
+## 💡 Patterns Learned (Cross-Repo)
+
+### [Pattern Name] ([YYYY-MM-DD])
+- **Pattern:** [Description]
+- **Why:** [Reasoning]
+- **Examples:** [Usage examples]
+- **Use cases:** [When to apply]
+- **Report:** [Link to learning report if exists]
+
+---
+
+## 🛠️ How to Use This File
+
+**Session Start (Auto):**
+1. Claude Code loads CLAUDE.md
+2. Finds `@~/.genie/context.md` reference
+3. Executes all `!command` statements
+4. Greets you with:
+   - Current focus
+   - Where you left off
+   - Fresh git context
+   - Next queued decision
+
+**During Session:**
+- Check "Current Focus" to know what you're working on
+- Update "Recent Completions" as you finish tasks
+- Add decisions to queue (don't present all at once!)
+- Track parallel work in "Active Parallel Work" section
+
+**Session End:**
+- Update "Current Focus" with progress
+- Add completions to "Recent Completions"
+- Queue any pending decisions
+- Learnings auto-captured via /learn command
+
+**Decision Management:**
+- Add decisions to queue as they arise
+- Present ONE at a time from queue
+- Remove from queue when resolved
+- Never present multiple decisions in parallel (ABCD format)
+
+---
+
+## 🎯 Session Greeting Template
+
+When you start a new session, Claude Code greets like this:
+
+> "Hey {{USER_NAME}}! 👋
+>
+> **Current focus:** [from Current Focus section]
+> **Where we left off:** [last item from Recent Completions]
+> **Branch:** [from !git branch]
+> **Status:** [summary from !git status]
+>
+> [If decision queued]: **Next up:** Decision 1 about [topic]. Ready to discuss?
+> [If no decision]: Ready to continue or switch focus?"
+
+This ensures:
+- ✅ Immediate context restoration
+- ✅ Fresh runtime state
+- ✅ Clear continuation point
+- ✅ No replanning needed
+- ✅ Relationship continuity
+
+---
+
+**System Status:** ✅ ACTIVE
+
+**This file location:** `~/.genie/context.md` (user-local, cross-repo)
+
+**Loaded via:** `@~/.genie/context.md` in CLAUDE.md (line 3)
+
+**Next evolution:** [Your ideas for improving this system]
+
+---
+
+🧞 **Session continuity system active!** No more amnesia. Let's build. ✨
+

package/.genie/product/templates/qa-done-report-template.md

@@ -0,0 +1,68 @@
+# Done Report: qa-<slug>-<YYYYMMDDHHmm>
+## Executive Summary
+- **Checklist items tested:** X/Y
+- **New scenarios discovered:** A
+- **Bugs found:** B (C critical, D high, E medium)
+- **Checklist items added:** F
+
+## Test Matrix
+
+### Checklist Items (from @.genie/qa/checklist.md)
+| Item | Category | Status | Evidence |
+|------|----------|--------|----------|
+| <name> | <cat> | ✅ Pass | cmd-<name>-<ts>.txt |
+| <name> | <cat> | ❌ Fail | error-<name>-<ts>.txt |
+
+### New Scenarios (discovered during this run)
+| Scenario | Category | Status | Added to Checklist |
+|----------|----------|--------|-------------------|
+| <name> | <cat> | ✅ Pass | ✅ Yes (via learn) |
+
+## Bugs Found
+
+### 🔴 CRITICAL (X)
+**[BUG] <Description>**
+- **Reproduction:** <steps>
+- **Expected:** <behavior>
+- **Actual:** <behavior>
+- **Evidence:** .genie/qa/evidence/ (created during test execution)<file>
+- **Filed:** Issue #XX
+- **Owner:** <agent/person>
+
+### 🟠 HIGH (X)
+(same format)
+
+### 🟡 MEDIUM (X)
+(same format)
+
+## Learning Summary
+
+**Items added to checklist:**
+1. <Item name> (<category>)
+2. <Item name> (<category>)
+
+**Learn agent sessions:**
+- Session <id>: Added <item>
+- Session <id>: Added <item>
+
+## Evidence Archive
+Location: .genie/qa/evidence/ (created during test execution)
+
+**Terminal outputs:** X files
+**Screenshots:** Y files
+**Logs:** Z files
+
+## Coverage Analysis
+- **<Category 1>:** X/Y tested (Z%)
+- **<Category 2>:** X/Y tested (Z%)
+- **Overall:** X/Y scenarios validated (Z%)
+
+## Follow-Ups
+1. <Action> - <Priority>
+2. <Action> - <Priority>
+
+## Verdict
+**Status:** <APPROVED | BLOCKED>
+**Confidence:** <LOW | MEDIUM | HIGH>
+**Recommendation:** <action items>
+

package/.genie/product/templates/review-report-template.md

@@ -0,0 +1,89 @@
+# Wish Review – {Wish Slug}
+**Date:** 2024-..Z | **Status in wish:** {status}
+**Completion Score:** XX/100 (XX%)
+
+## Matrix Scoring Breakdown
+
+### Discovery Phase (XX/30 pts)
+- **Context Completeness (X/10 pts)**
+  - [x] All files/docs referenced with @ notation (4/4 pts) – Evidence: context ledger complete
+  - [x] Background persona outputs captured (3/3 pts) – Evidence: @.genie/wishes/<slug>/reports/done-*
+  - [ ] Assumptions/decisions/risks documented (1/3 pts) – Gap: Missing risk analysis
+- **Scope Clarity (X/10 pts)**
+  - [x] Current/target state defined (3/3 pts)
+  - [x] Spec contract with success metrics (4/4 pts)
+  - [x] Out-of-scope stated (3/3 pts)
+- **Evidence Planning (X/10 pts)**
+  - [x] Validation commands specified (4/4 pts)
+  - [x] Artifact paths defined (3/3 pts)
+  - [ ] Approval checkpoints documented (0/3 pts) – Gap: No checkpoints defined
+
+### Implementation Phase (XX/40 pts)
+- **Code Quality (X/15 pts)**
+  - [x] Follows standards (5/5 pts) – Evidence: passes lint checks
+  - [x] Minimal surface area (4/5 pts) – Note: Some extra files modified
+  - [x] Clean abstractions (5/5 pts)
+- **Test Coverage (X/10 pts)**
+  - [x] Unit tests (4/4 pts) – Evidence: `@tests/unit/`*
+  - [x] Integration tests (4/4 pts) – Evidence: `@tests/integration/`*
+  - [x] Test execution evidence (2/2 pts) – Evidence: test-results.log
+- **Documentation (X/5 pts)**
+  - [x] Inline comments (2/2 pts)
+  - [ ] Updated external docs (0/2 pts) – Gap: README not updated
+  - [x] Maintainer context (1/1 pt)
+- **Execution Alignment (X/10 pts)**
+  - [x] Stayed in scope (4/4 pts)
+  - [x] No scope creep (3/3 pts)
+  - [x] Dependencies honored (3/3 pts)
+
+### Verification Phase (XX/30 pts)
+- **Validation Completeness (X/15 pts)**
+  - [x] All validation commands passed (6/6 pts)
+  - [x] Artifacts at specified paths (5/5 pts)
+  - [x] Edge cases tested (4/4 pts)
+- **Evidence Quality (X/10 pts)**
+  - [x] Command outputs logged (4/4 pts)
+  - [x] Screenshots/metrics captured (3/3 pts)
+  - [x] Before/after comparisons (3/3 pts)
+- **Review Thoroughness (X/5 pts)**
+  - [x] Human approval obtained (2/2 pts)
+  - [x] Blockers resolved (2/2 pts)
+  - [x] Status log updated (1/1 pt)
+
+## Evidence Summary
+| Artefact | Location | Result | Notes |
+| --- | --- | --- | --- |
+| Test results | `@wishes/`<slug>/qa/tests.log | ✅ | All 47 tests passing |
+| Metrics | `@wishes/`<slug>/qa/metrics.json | ✅ | TTFB avg 410ms (target <500ms) |
+| Screenshots | `@wishes/`<slug>/qa/screenshots/ | ✅ | 8 workflow screenshots captured |
+
+## Deductions & Gaps
+1. **-2 pts (Discovery):** Risk analysis incomplete in discovery summary
+2. **-3 pts (Discovery):** Approval checkpoints not documented before implementation
+3. **-1 pt (Implementation):** Extra files modified outside core scope
+4. **-2 pts (Implementation):** README not updated with new feature
+
+## Recommendations
+1. Add risk analysis to discovery summary section
+2. Document approval checkpoints for future wishes
+3. Update README with feature documentation
+4. Consider splitting peripheral file changes into separate PR
+
+## Verification Commands
+Summarize the validation commands executed (per wish instructions and project defaults in `@.genie/code/agents/tests.md` / `@.genie/code/agents/commit.md`) and record pass/fail status for each.
+
+## Verdict
+**Score: XX/100 (XX%)**
+- ✅ **90-100:** EXCELLENT – Ready for merge
+- ✅ **80-89:** GOOD – Minor gaps, approved with follow-ups
+- ⚠️ **70-79:** ACCEPTABLE – Needs improvements before merge
+- ❌ **<70:** NEEDS WORK – Significant gaps, blocked
+
+**Status:** {APPROVED | APPROVED_WITH_FOLLOWUPS | BLOCKED}
+
+## Next Steps
+1. Address gaps 1-4 above (optional for approval, required for excellence)
+2. Update wish status to COMPLETED
+3. Update wish completion score to XX/100
+4. Create follow-up tasks for deferred documentation
+

package/.genie/product/templates/wish-template.md

@@ -0,0 +1,120 @@
+# 🧞 {FEATURE NAME} WISH
+**Status:** DRAFT
+**Roadmap Item:** {ROADMAP-ID} – @.genie/product/roadmap.md §{section}
+**Mission Link:** @.genie/product/mission.md §Pitch
+**Completion Score:** 0/100 (updated by `/review`)
+
+## Evaluation Matrix (100 Points Total)
+
+### Discovery Phase (30 pts)
+- **Context Completeness (10 pts)**
+  - [ ] All relevant files/docs referenced with @ notation (4 pts)
+  - [ ] Background persona outputs captured in context ledger (3 pts)
+  - [ ] Assumptions (ASM-#), decisions (DEC-#), risks documented (3 pts)
+- **Scope Clarity (10 pts)**
+  - [ ] Clear current state and target state defined (3 pts)
+  - [ ] Spec contract complete with success metrics (4 pts)
+  - [ ] Out-of-scope explicitly stated (3 pts)
+- **Evidence Planning (10 pts)**
+  - [ ] Validation commands specified with exact syntax (4 pts)
+  - [ ] Artifact storage paths defined (3 pts)
+  - [ ] Approval checkpoints documented (3 pts)
+
+### Implementation Phase (40 pts)
+- **Code Quality (15 pts)**
+  - [ ] Follows project standards (@.genie/standards/*) (5 pts)
+  - [ ] Minimal surface area changes, focused scope (5 pts)
+  - [ ] Clean abstractions and patterns (5 pts)
+- **Test Coverage (10 pts)**
+  - [ ] Unit tests for new behavior (4 pts)
+  - [ ] Integration tests for workflows (4 pts)
+  - [ ] Evidence of test execution captured (2 pts)
+- **Documentation (5 pts)**
+  - [ ] Inline comments where complexity exists (2 pts)
+  - [ ] Updated relevant external docs (2 pts)
+  - [ ] Context preserved for maintainers (1 pt)
+- **Execution Alignment (10 pts)**
+  - [ ] Stayed within spec contract scope (4 pts)
+  - [ ] No unapproved scope creep (3 pts)
+  - [ ] Dependencies and sequencing honored (3 pts)
+
+### Verification Phase (30 pts)
+- **Validation Completeness (15 pts)**
+  - [ ] All validation commands executed successfully (6 pts)
+  - [ ] Artifacts captured at specified paths (5 pts)
+  - [ ] Edge cases and error paths tested (4 pts)
+- **Evidence Quality (10 pts)**
+  - [ ] Command outputs (failures → fixes) logged (4 pts)
+  - [ ] Screenshots/metrics captured where applicable (3 pts)
+  - [ ] Before/after comparisons provided (3 pts)
+- **Review Thoroughness (5 pts)**
+  - [ ] Human approval obtained at checkpoints (2 pts)
+  - [ ] All blockers resolved or documented (2 pts)
+  - [ ] Status log updated with completion timestamp (1 pt)
+
+## Context Ledger
+| Source | Type | Summary | Routed To |
+| --- | --- | --- | --- |
+| Planning brief | doc | Key findings | entire wish |
+| `@path/to/file` | repo | Insight | wish, docs |
+| mcp__genie__run agent="..." | background | Output summary | wish, roadmap |
+
+### Context Variants Considered
+- Candidates: C1, C2, C3
+- Winner: {C?} — reason: one‑line tradeoff statement
+
+## Discovery Summary
+- **Primary analyst:** {Human/Agent}
+- **Key observations:** …
+- **Assumptions (ASM-#):** …
+- **Open questions (Q-#):** …
+- **Risks:** …
+
+## Executive Summary
+Concise outcome tied to user/system impact.
+
+## Current State
+- **What exists today:** `@file` references with short notes
+- **Gaps/Pain points:** …
+
+## Target State & Guardrails
+- **Desired behaviour:** …
+- **Non-negotiables:** latency, safety, human-likeness, compliance, etc.
+
+## Execution Groups
+### Group A – {slug}
+- **Goal:** …
+- **Surfaces:** `@file`, `@docs`
+- **Deliverables:** …
+- **Evidence:** Store in wish `qa/group-a/`, add notes in `reports/` if needed
+- **Suggested personas:** `forge-coder`, `forge-quality`
+- **External tracker:** {placeholder ID or JIRA-XXX}
+
+(Repeat for Group B/C as needed.)
+
+## Verification Plan
+- Validation steps or scripts to run (tests, metrics, evaluation)
+- Evidence storage: reference wish `qa/` + `reports/` subfolders
+- Branch strategy note (dedicated branch vs existing vs micro-task)
+
+### Evidence Checklist
+- **Validation commands (exact):** …
+- **Artefact paths (where evidence lives):** use wish `qa/` + `reports/`
+- **Approval checkpoints (human sign-off required before work starts):** …
+
+## <spec_contract>
+- **Scope:** …
+- **Out of scope:** …
+- **Success metrics:** …
+- **External tasks:** Tracker IDs (if any)
+- **Dependencies:** …
+</spec_contract>
+
+## Blocker Protocol
+1. Pause work and create `reports/blocker-<slug>-<timestamp>.md` inside the wish folder describing findings.
+2. Notify owner and wait for updated instructions.
+3. Resume only after the wish status/log is updated.
+
+## Status Log
+- [YYYY-MM-DD HH:MMZ] Wish created
+- …

package/.genie/scripts/helpers/analyze-commit.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+
+/**
+ * Analyze Commit Helper
+ *
+ * Parse commit metadata using deterministic rules (no LLM).
+ * Extracts: type, scope, breaking, issue refs, wish refs.
+ *
+ * Usage:
+ *   genie helper analyze-commit [commit-hash]
+ *   genie helper analyze-commit --staged (analyze staged diff)
+ *
+ * Output: JSON
+ */
+
+const { execSync } = require('child_process');
+
+// Conventional commit type patterns
+const COMMIT_TYPES = {
+  feat: { name: 'Feature', requiresIssue: true, category: 'feature' },
+  fix: { name: 'Bug Fix', requiresIssue: true, category: 'feature' },
+  docs: { name: 'Documentation', requiresIssue: false, category: 'maintenance' },
+  style: { name: 'Style', requiresIssue: false, category: 'maintenance' },
+  refactor: { name: 'Refactor', requiresIssue: false, category: 'maintenance' },
+  perf: { name: 'Performance', requiresIssue: false, category: 'maintenance' },
+  test: { name: 'Test', requiresIssue: false, category: 'maintenance' },
+  build: { name: 'Build', requiresIssue: false, category: 'maintenance' },
+  ci: { name: 'CI/CD', requiresIssue: false, category: 'maintenance' },
+  chore: { name: 'Chore', requiresIssue: false, category: 'maintenance' },
+  revert: { name: 'Revert', requiresIssue: false, category: 'special' },
+};
+
+function parseConventionalCommit(message) {
+  // Format: type(scope)!: subject
+  const pattern = /^(\w+)(?:\(([^)]+)\))?(!)?\s*:\s*(.+)$/;
+  const match = message.match(pattern);
+
+  if (!match) {
+    return {
+      type: null,
+      scope: null,
+      breaking: false,
+      subject: message,
+      conventional: false,
+    };
+  }
+
+  const [, type, scope, breaking, subject] = match;
+
+  return {
+    type: type.toLowerCase(),
+    scope: scope || null,
+    breaking: !!breaking,
+    subject: subject.trim(),
+    conventional: true,
+    typeInfo: COMMIT_TYPES[type.toLowerCase()] || null,
+  };
+}
+
+function extractReferences(message) {
+  const refs = {
+    issues: [],
+    wishes: [],
+    closes: [],
+    fixes: [],
+    related: [],
+  };
+
+  // GitHub issues: fixes #123, closes #456
+  const closePattern = /(fixes|closes)\s+#(\d+)/gi;
+  let match;
+  while ((match = closePattern.exec(message)) !== null) {
+    const num = match[2];
+    refs.issues.push(num);
+    refs.closes.push(num);
+  }
+
+  // Related issues: related: #789, see #999
+  const relatedPattern = /(related|see):\s+#(\d+)/gi;
+  while ((match = relatedPattern.exec(message)) !== null) {
+    const num = match[2];
+    if (!refs.issues.includes(num)) {
+      refs.issues.push(num);
+      refs.related.push(num);
+    }
+  }
+
+  // Wish references: wish: slug, .genie/wishes/slug
+  const wishPattern = /\bwish:\s*([\w-]+)|\.genie\/wishes\/([\w-]+)/gi;
+  while ((match = wishPattern.exec(message)) !== null) {
+    const slug = match[1] || match[2];
+    if (slug && !refs.wishes.includes(slug)) {
+      refs.wishes.push(slug);
+    }
+  }
+
+  return refs;
+}
+
+function getCommitMessage(commitHash) {
+  try {
+    const format = commitHash ? '%s%n%b' : '%s%n%b';
+    const cmd = commitHash
+      ? `git log -1 --format="${format}" ${commitHash}`
+      : `git log -1 --format="${format}" HEAD`;
+
+    return execSync(cmd, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+function getStagedMessage() {
+  // Read COMMIT_EDITMSG if available, or use git status
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    const gitDir = execSync('git rev-parse --git-dir', {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+
+    const commitMsgPath = path.join(gitDir, 'COMMIT_EDITMSG');
+    if (fs.existsSync(commitMsgPath)) {
+      return fs.readFileSync(commitMsgPath, 'utf8').trim();
+    }
+  } catch (e) {
+    // Fallback to empty
+  }
+
+  return '';
+}
+
+function analyzeCommit(message) {
+  const lines = message.split('\n');
+  const subject = lines[0];
+  const body = lines.slice(1).join('\n').trim();
+
+  const parsed = parseConventionalCommit(subject);
+  const refs = extractReferences(message);
+
+  const requiresIssue = parsed.typeInfo?.requiresIssue ?? true; // Default: require issue
+  const hasIssue = refs.issues.length > 0;
+  const hasWish = refs.wishes.length > 0;
+  const hasTraceability = hasIssue || hasWish;
+
+  return {
+    subject,
+    body,
+    ...parsed,
+    references: refs,
+    traceability: {
+      required: requiresIssue,
+      hasIssue,
+      hasWish,
+      satisfied: !requiresIssue || hasTraceability,
+    },
+    metadata: {
+      category: parsed.typeInfo?.category || 'untyped',
+      requiresIssue,
+    },
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  let message;
+
+  if (args.includes('--staged')) {
+    message = getStagedMessage();
+  } else if (args.length > 0) {
+    message = getCommitMessage(args[0]);
+  } else {
+    message = getCommitMessage('HEAD');
+  }
+
+  if (!message) {
+    console.error('Error: No commit message found');
+    process.exit(1);
+  }
+
+  const analysis = analyzeCommit(message);
+  console.log(JSON.stringify(analysis, null, 2));
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { analyzeCommit, parseConventionalCommit, extractReferences };