pgserve 2.1.2 → 2.2.0

package/.genie/product/cli-automation.md

@@ -1,359 +0,0 @@
-# Genie CLI Automation Guide
-
-Complete reference for using Genie CLI in automated workflows (cron, CI/CD, scripts).
-
-## Quick Reference Table
-
-| Command | Mode | Output | Use Case |
-|---------|------|--------|----------|
-| `genie task` | Headless | JSON | Fire-and-forget tasks |
-| `genie run` | Foreground | JSON/Text | Wait for completion |
-| `genie run --background` | Headless | URL | Same as task |
-| `genie task monitor <id>` | Foreground | Live logs | Monitor background task |
-| `genie list tasks` | Query | Table | Task status check |
-| `genie view <id>` | Query | Transcript | Get task output |
-| `genie resume <id>` | Interactive | JSON | Continue conversation |
-| `genie stop <id>` | Control | - | Kill running task |
-| `genie status` | Health | Status | System health check |
-
----
-
-## 1. Fire-and-Forget Tasks (Cron/Background)
-
-**Command:** `genie task`
-- Starts task immediately
-- Returns task ID
-- No browser, no waiting
-- Perfect for cron
-
-### Basic Usage
-```bash
-# Default: JSON output with task info
-genie task code/explore "Check system health"
-
-# Output:
-{
-  "task_id": "abc-123...",
-  "task_url": "http://localhost:8887/...",
-  "agent": "code/explore",
-  "executor": "CLAUDE_CODE:DEFAULT",
-  "status": "started"
-}
-```
-
-### Quiet Mode (No Warnings)
-```bash
-# Suppress version warnings (clean cron logs)
-genie task --quiet code/explore "Silent task"
-```
-
-### Cron Examples
-```bash
-# Every 5 minutes - health check
-*/5 * * * * genie task --quiet code/explore "Health check" >> /var/log/genie.log 2>&1
-
-# Daily at 3 AM - cleanup
-0 3 * * * genie task --quiet code/code-garbage-collector "Daily cleanup" >> /var/log/cleanup.log 2>&1
-
-# Hourly - save task ID for later monitoring
-0 * * * * genie task --quiet code/explore "Hourly scan" | jq -r '.task_id' > /var/log/last-task-id.txt 2>&1
-```
-
----
-
-## 2. Wait for Completion (Synchronous)
-
-**Command:** `genie run`
-- Waits for task to finish
-- Returns output when done
-- Opens browser (unless --background)
-
-### Basic Usage
-```bash
-# Wait for completion, see output
-genie run code/explore "Analyze codebase"
-
-# Output: Full results JSON with status
-```
-
-### Background Mode
-```bash
-# Same as 'genie task' (no waiting)
-genie run --background code/explore "Background task"
-```
-
-### Automation Examples
-```bash
-# CI/CD: Run tests and capture results
-genie run --quiet code/tests "Run all tests" > test-results.json
-
-# Script: Wait for analysis, then act on results
-genie run --quiet code/analyze "Check dependencies" > deps.json
-if grep -q "vulnerable" deps.json; then
-  echo "Security issues found!"
-  exit 1
-fi
-```
-
----
-
-## 3. Monitor Background Tasks
-
-**Command:** `genie task monitor <task-id>`
-- Attach to running task
-- Stream live logs
-- Wait for completion
-
-### Usage
-```bash
-# Start task in background
-TASK_ID=$(genie task --quiet code/explore "Long analysis" | jq -r '.task_id')
-
-# Monitor it later
-genie task monitor $TASK_ID
-```
-
-### Automation Example
-```bash
-# Cron: Start task, then monitor in separate job
-# Job 1 (every hour): Start task
-0 * * * * genie task --quiet code/explore "Hourly check" | jq -r '.task_id' > /tmp/task-id.txt
-
-# Job 2 (5 mins later): Monitor completion
-5 * * * * genie task monitor $(cat /tmp/task-id.txt) >> /var/log/monitored.log 2>&1
-```
-
----
-
-## 4. Query Task Status
-
-### List All Tasks
-```bash
-# Show all tasks (table format)
-genie list tasks
-
-# Sample output:
-| Task ID      | Agent        | Status  | Executor         |
-|--------------|--------------|---------|------------------|
-| abc-123...   | code/explore | running | CLAUDE_CODE/DEFAULT |
-```
-
-### View Task Output
-```bash
-# Get full transcript
-genie view <task-id>
-
-# Live view (auto-refresh)
-genie view --live <task-id>
-
-# Full history
-genie view --full <task-id>
-```
-
-### Automation Examples
-```bash
-# Check if any tasks are still running
-if genie list tasks | grep -q "running"; then
-  echo "Tasks still in progress"
-fi
-
-# Get specific task result
-genie view abc-123 > task-output.txt
-```
-
----
-
-## 5. Task Control
-
-### Stop Running Task
-```bash
-genie stop <task-id>
-```
-
-### Resume Conversation
-```bash
-# Continue from previous task
-genie resume <task-id> "Follow-up question"
-```
-
----
-
-## 6. System Health Checks
-
-### Check Genie Status
-```bash
-genie status
-
-# Output:
-🧞 GENIE STATUS
-📦 Forge Backend: 🟢 Running
-📡 MCP Server: ...
-```
-
-### Automation Example
-```bash
-# Pre-flight check before running tasks
-if ! genie status | grep -q "🟢 Running"; then
-  echo "Forge not running, starting..."
-  genie &  # Start Genie server
-  sleep 5
-fi
-
-# Now safe to run tasks
-genie task code/explore "Check system"
-```
-
----
-
-## 7. Executor Control
-
-### Override Default Executor
-```bash
-# Use specific executor
-genie task -x OPENCODE code/explore "Use OpenCode"
-genie task --executor GEMINI code/explore "Use Gemini"
-
-# Use specific model
-genie task -m "gpt-4" code/explore "Use GPT-4"
-```
-
-### Automation Example
-```bash
-# Distribute load across executors
-for executor in CLAUDE_CODE OPENCODE GEMINI; do
-  genie task -x $executor code/explore "Check $executor" &
-done
-wait  # Wait for all background tasks
-```
-
----
-
-## 8. Advanced Patterns
-
-### Parallel Execution
-```bash
-# Run multiple tasks simultaneously
-genie task code/explore "Task 1" &
-genie task code/analyze "Task 2" &
-genie task code/tests "Task 3" &
-wait  # Wait for all to finish
-```
-
-### Error Handling
-```bash
-# Capture exit code
-genie run --quiet code/tests "Run tests"
-EXIT_CODE=$?
-
-if [ $EXIT_CODE -ne 0 ]; then
-  echo "Task failed with code $EXIT_CODE"
-  # Notify, retry, etc.
-fi
-```
-
-### Task Chaining
-```bash
-# Sequential tasks with error checking
-TASK1=$(genie task --quiet code/explore "Step 1" | jq -r '.task_id')
-genie task monitor $TASK1 || exit 1
-
-TASK2=$(genie task --quiet code/analyze "Step 2" | jq -r '.task_id')
-genie task monitor $TASK2 || exit 1
-
-echo "Pipeline complete!"
-```
-
-### Retry Logic
-```bash
-# Retry failed tasks
-MAX_RETRIES=3
-RETRY=0
-
-while [ $RETRY -lt $MAX_RETRIES ]; do
-  genie run --quiet code/tests "Run tests" && break
-  RETRY=$((RETRY + 1))
-  echo "Retry $RETRY/$MAX_RETRIES"
-  sleep 10
-done
-```
-
----
-
-## 9. CI/CD Integration
-
-### GitHub Actions Example
-```yaml
-- name: Run Genie Analysis
-  run: |
-    genie task --quiet code/analyze "Analyze PR changes" > task.json
-    TASK_ID=$(jq -r '.task_id' task.json)
-    genie task monitor $TASK_ID
-```
-
-### Jenkins Example
-```groovy
-stage('Genie Quality Check') {
-  steps {
-    sh 'genie run --quiet code/code-quality "Check code quality" > report.json'
-    archiveArtifacts 'report.json'
-  }
-}
-```
-
----
-
-## 10. Logging & Output
-
-### Structured Logging
-```bash
-# JSON output for parsing
-genie task code/explore "Check" | jq '.task_id'
-
-# Human-readable output
-genie run code/explore "Generate report" | tee report.json
-```
-
-### Log Rotation
-```bash
-# Cron with log rotation
-*/15 * * * * genie task --quiet code/explore "Check" >> /var/log/genie/$(date +\%Y\%m\%d).log 2>&1
-
-# Keep last 7 days
-find /var/log/genie/ -name "*.log" -mtime +7 -delete
-```
-
----
-
-## Best Practices
-
-1. **Use `--quiet`** in cron to suppress version warnings
-2. **Use `jq`** to extract specific fields from JSON output
-3. **Check `genie status`** before heavy automation
-4. **Save task IDs** for later monitoring/debugging
-5. **Use JSON output** for programmatic parsing
-6. **Set explicit executor** if you need consistency
-7. **Monitor long tasks** via `genie task monitor`
-8. **Handle errors** - check exit codes in scripts
-
----
-
-## Common Issues
-
-**Workspace Version Warning:**
-```bash
-⚠️  Workspace behind: workspace 2.5.19 ← global 2.5.20
-```
-Solution: Use `--quiet` flag or run `genie` once to sync.
-
-**Forge Not Running:**
-```bash
-❌ Forge backend unreachable
-```
-Solution: Start Forge with `genie` (no args) or check `genie status`.
-
-**Task Stuck:**
-```bash
-genie stop <task-id>  # Kill stuck task
-genie list tasks      # Check status
-```
-

package/.genie/product/environment.md

@@ -1,60 +0,0 @@
-# Genie Dev Environment Configuration
-Genie Dev relies on a small set of environment variables to steer the CLI, model selection, and self-improvement experiments. Configure these in a local `.env` and load them before running the CLI.
-
-## Conventions
-- Names: UPPER_SNAKE_CASE
-- Types: string | int (ms) | bool (`0/1` or `true/false`)
-- Scope legend: [required], [optional], [experimental]
-
-## Core CLI
-- APP_NAME [optional]: defaults to `Genie Dev`
-- APP_ENV [optional]: `dev|staging|prod` (default `dev`)
-- GENIE_BRANCH [optional]: branch name used for wish/forge guidance (default `genie-dev`)
-- LOG_LEVEL [optional]: `trace|debug|info|warn|error` (default `info`)
-
-## Genie Runtime
-- GENIE_MODEL [required]: model identifier used by agents (e.g., `gpt-5`)
-- GENIE_APPROVAL_POLICY [optional]: `on-request|on-failure|never|untrusted` (default approval behavior)
-- GENIE_SANDBOX_MODE [optional]: `workspace-write|read-only|danger-full-access` (default sandbox mode)
-- GENIE_CLI_STYLE [optional]: `plain|compact|art` (default `compact`)
-
-Note: Agent-specific sandbox and approval settings in frontmatter override these defaults.
-
-## Provider Credentials
-- OPENAI_API_KEY or ALTERNATE_PROVIDER_KEY [required]: API key for the LLM provider
-- PROVIDER_ENDPOINT [optional]: override base URL when pointing at non-default gateways
-- PROVIDER_REGION [optional]: specify regional routing if required by service policy
-
-## Experiment Toggles
-- ENABLE_LEARN_SYNC [optional]: `0|1` (default `1`) — when disabled, learn updates are reported but not auto-applied
-- ENABLE_TWIN_DEFAULT [optional]: `0|1` (default `0`) — automatically schedule twin audits for high-risk wishes
-- DONE_REPORT_DIR [optional]: overrides `.genie/wishes/<slug>/reports/` when storing experiment evidence elsewhere
-
-## Safety Limits
-- MAX_CONCURRENT_AGENTS [optional]: limit parallel CLI sessions (default `5`)
-- SESSION_TIMEOUT_SECONDS [optional]: auto-stop background sessions after N seconds (default `3600`)
-- RATE_LIMIT_RPS [optional]: throttles outbound provider calls (default `60`)
-
-## Example .env (development)
-```env
-APP_NAME="Genie Dev"
-APP_ENV=dev
-GENIE_BRANCH=genie-dev
-LOG_LEVEL=debug
-
-GENIE_MODEL=gpt-5
-GENIE_APPROVAL_POLICY=on-request
-GENIE_SANDBOX_MODE=workspace-write
-GENIE_CLI_STYLE=compact
-
-OPENAI_API_KEY=replace_me
-ENABLE_SELF_LEARN_SYNC=1
-ENABLE_TWIN_DEFAULT=0
-MAX_CONCURRENT_AGENTS=5
-SESSION_TIMEOUT_SECONDS=3600
-```
-
-## Notes
-- Never commit real API keys or secrets; rely on `.env` files and secret managers
-- Keep experimental toggles disabled by default when preparing release candidates for downstream repos
-- Align CLI harness configuration with the approval policy documented in active wishes to avoid mismatched expectations

package/.genie/product/mission.md

@@ -1,60 +0,0 @@
-# Genie Dev Mission
-## Pitch
-
-Genie Dev is the self-development branch of the Genie framework. It turns the template into a living meta-agent that can audit, upgrade, and validate its own workflow stack while remaining installable in any host repository.
-
-## Users
-
-### Primary Customers
-
-- **Framework Maintainers:** Steer the Genie prompt stack and CLI toward higher autonomy without losing human oversight.
-- **Power Users / Partner Teams:** Pilot emerging self-improvement patterns and feed structured evidence back into the core templates.
-
-### User Personas
-
-**Meta-Orchestrator**
-- **Role:** Maintains Genie agents and safeguards guardrails
-- **Context:** Needs rapid iteration on prompts, policies, and diagnostics without destabilizing downstream repos
-- **Pain Points:** Slow feedback loops, fragmented experiments, weak traceability when agents evolve themselves
-- **Goals:** Tighten validation loops, capture every change rationale, and publish upgrade paths that downstream repos can adopt deliberately
-
-**Pilot Squad Lead**
-- **Role:** Early adopter embedding Genie into complex delivery environments
-- **Context:** Validates new meta-agent behaviours before they ship broadly
-- **Pain Points:** Unclear upgrade guidance, lack of proof that automation changes are safe, difficulty reporting outcomes
-- **Goals:** Receive pre-baked playbooks, evidence kits, and rollback guidance for every self-improvement release
-
-## The Problem
-
-### Self-Evolving Agents Need Structure
-Genie’s templates must improve themselves without eroding trust or breaking installs across diverse projects.
-
-**Our Approach:** Codify meta-agent upgrades as wishes with verifiable evidence, ensuring every prompt or workflow change is paired with metrics and rollback hooks.
-
-### Feedback Loops Are Opaque
-Learnings often stay buried in session transcripts, delaying improvements to prompts and guardrails.
-
-**Our Approach:** Promote learnings into persistent documentation, align them with experiments, and surface them in done reports so humans can audit evolution.
-
-### Downstream Risk Management
-Branch experimentation can create surprises for adopters if success criteria are not explicit.
-
-**Our Approach:** Treat this branch as the proving ground for phased releases, publish adoption kits, and require validation evidence before merging into the canonical template.
-
-## Differentiators
-
-### Meta-Agent Feedback Harness
-Purpose-built to let Genie run experiments on itself, capture the outcomes, and decide what ships.
-
-### Evidence-First Governance
-Every change must tie back to a wish, a forge plan, validation commands, and a done report stored under `.genie/wishes/<slug>/reports/`.
-
-### Human-in-the-Loop Control
-Automation never bypasses human approval gates; new capabilities arrive with clear opt-in guidance and rollback instructions.
-
-## Key Focus Areas
-
-- **Self-Audit Loops:** Plan → Wish → Forge cycles targeted at the prompt stack, CLAUDE/AGENTS guardrails, and CLI behaviours.
-- **Learning Propagation:** Promote validated learnings into `.genie/instructions/` and agent briefs so changes stick.
-- **Tooling Diagnostics:** Expand test harnesses and smoke commands that ensure the CLI behaves before releases.
-- **Adoption Playbooks:** Provide branch-to-main migration guides, change logs, and decision records for every improvement wave.

package/.genie/product/roadmap.md

@@ -1,44 +0,0 @@
-# Genie Dev Roadmap
-The genie-dev branch is the laboratory for Genie’s self-improvement program. Phases are sequenced to keep downstream adopters safe while we iterate quickly.
-
-## Phase 0 — Baseline Capture (✅ complete)
-- Neutralize template placeholders and document the current mission, tech stack, and guardrails
-- Inventory existing behavioural learnings and confirm they are enforced across agents
-- Establish `pnpm run build:genie` + smoke tests as the minimum verification gate
-
-## Phase 1 — Instrumentation & Telemetry (in progress)
-- Treat the wish **Evidence Checklist** as the gating deliverable before other instrumentation tasks proceed (see ).
-- Add branch-specific checklists to every wish to log evidence paths and validation commands
-- Expand done-report coverage so each experiment stores scope, risks, and follow-ups
-- Wire CLI diagnostics to surface missing sessions or misconfigured presets
-
-## Phase 2 — Guided Self-Improvement
-- Author wishes that target prompt quality, guardrail clarity, and CLI usability
-- Pair each wish with twin audits and validation scripts before merging back to `main`
-- Promote validated learnings into `.genie/instructions/` and agent briefs
-
-## Phase 3 — Adoption Kits for Downstream Repos
-- Package upgrade notes, migration diffs, and rollback guidance for every major change
-- Publish branch-to-main release checklist (Plan → Wish → Forge coverage, tests, done report link)
-- Partner with pilot teams to trial upgrades and capture their feedback in structured templates
-
-## Phase 4 — Automation & CI Integration
-- Land GitHub Actions pipeline that runs build + smoke tests and attaches artefacts to PRs
-- Add regression checks for behavioural rules (learn, guardrail compliance)
-- Introduce metrics capture (latency, wish completion velocity) with reporting hooks
-
-## Success Metrics
-- 100% of genie-dev wishes include validation commands and evidence links
-- Smoke suite (`pnpm run test:genie`) passing before merge on every PR
-- Documented learnings promoted within 48 hours of validation
-- Downstream adopters report <5% rollback rate on genie-dev releases
-
-## Dependencies & Enablers
-- Maintainers available for twin reviews and manual approvals
-- Access to GPT-5 class models (configurable via `GENIE_MODEL`)
-- Stable sandboxed environment mirroring production guardrails
-
-## Risk Log (actively monitored)
-- **Automation drift:** self-improvement scripts may bypass approval gates → mitigate with review checklist baked into wishes
-- **Telemetry gaps:** missing evidence makes regression root-cause harder → mitigate by enforcing done report template updates
-- **Adopter fatigue:** too many upgrades without guides → mitigate by bundling changes into release kits with opt-in toggles

package/.genie/product/tech-stack.md

@@ -1,34 +0,0 @@
-# Genie Dev Technical Stack
-Genie Dev extends the core Genie template with diagnostics and automation focused on self-evolution. The stack stays lightweight so downstream repos can still install it cleanly.
-
-## Core CLI
-- **Runtime:** Node.js 20.x managed with `pnpm`
-- **Language:** TypeScript 5.9 (compiled via `src/cli/tsconfig.json`)
-- **UI:** `ink` + `react` for interactive CLI flows
-- **Formatting & Parsing:** `yaml` for agent metadata, native fs/stream tooling for logs
-
-## Agent Assets
-- **Prompts:** Markdown agents under `.genie/agents/` with shared personas in `.genie/agents/core/`
-- **Project Overrides:** Add a short "Project Notes" section inside relevant agent or spell docs (no separate `custom/` directory)
-- **State:** Session and ledger files stored in `.genie/state/` (never edit manually; inspect via MCP genie tools: `mcp__genie__list_sessions`, `mcp__genie__view`)
-
-## Testing & Validation
-- **Smoke Suite:** `tests/genie-cli.test.js` exercises CLI commands and prompt loading
-- **Identity Check:** `tests/identity-smoke.sh` ensures guardrails match expectations
-- **Recommended Checks:** `pnpm run build:genie` followed by `pnpm run test:genie` before publishing upgrades
-
-## Meta-Agent Instrumentation
-- **Done Reports:** `.genie/wishes/<slug>/reports/` captures experiment evidence and upgrade readiness
-- **Learning Ledger:** `.genie/instructions/*` houses behavioural overrides promoted from experiments
-- **Genie Orchestrator:** `.genie/agents/orchestrator.md` powers second-opinion audits before adopting risky changes
-
-## Toolchain Integrations
-- **Version Control:** Git-driven; branch `genie-dev` serves as the experimental lane
-- **CI Hooks (planned):** GitHub Actions pipeline to run build + smoke tests and publish artefacts for review
-- **Optional Runtimes:** Node/TS remains primary; Rust components can be referenced via `vendors/` for cross-language experiments
-
-## Observability
-- **Logs:** CLI captures command transcripts under `.genie/state/logs/`
-- **Metrics (manual):** Encourage recording latency/quality metrics inside wish evidence tables until automated collectors land
-
-This stack keeps Genie fast to iterate while providing the hooks required for self-auditing and safe downstream adoption.