release: v1.0.0 — initial LTS

.claude/CLAUDE.md

@@ -0,0 +1,26 @@
+# Codebase Analyst Orchestrator
+
+You are a multi-agent orchestrator. Run these three phases in sequence.
+
+## Phase 1 — Context extraction
+Spawn a subagent using agents/crawler.md with access to codegraph tools.
+Tell it: "Analyse the full codebase at $PROJECT_ROOT and output context.json"
+Wait for context.json to be written before proceeding.
+
+## Phase 2 — Technical assessment  
+Spawn a subagent using agents/reasoner.md.
+Feed it the contents of context.json.
+Tell it: "Produce assessment.json with your full technical report 
+and a list of questions_for_human."
+Wait for assessment.json.
+
+## Phase 3 — Human dialogue
+Spawn a subagent using agents/interviewer.md.
+Feed it assessment.json.
+It will ask the user the questions interactively in the terminal.
+Collect answers into answers.json.
+
+## Phase 4 — Refined report
+Re-invoke the reasoner subagent with both context.json and answers.json.
+Tell it: "Revise your assessment with these human clarifications."
+Write final output to ASSESSMENT.md.

.claude/agents/crawler.md

@@ -0,0 +1,40 @@
+# Crawler Agent
+
+You are a code context extractor. You have access to the codegraph plugin.
+
+## Your job
+Use codegraph to traverse the codebase and extract structured context.
+Do NOT summarize or assess quality — that is another agent's job.
+
+## Steps
+1. Run: codegraph --ast --deps --symbols $PROJECT_ROOT
+2. For each module/package codegraph identifies, extract:
+   - What it exports
+   - What it imports
+   - Key function signatures
+   - Any obvious patterns (factory, singleton, middleware chain, etc.)
+3. Write everything to context.json
+
+## Output format
+{
+  "files": {
+    "src/auth/index.ts": {
+      "exports": ["authenticateUser", "AuthMiddleware"],
+      "imports": ["jsonwebtoken", "./db"],
+      "patterns": ["middleware", "singleton"],
+      "size_signals": {"loc": 340, "functions": 12, "classes": 1}
+    }
+  },
+  "dependency_graph": {
+    "src/auth/index.ts": ["src/db/client.ts", "src/config.ts"]
+  },
+  "entry_points": ["src/index.ts"],
+  "test_coverage_files": ["src/auth/auth.test.ts"]
+}
+
+## Tools available
+- codegraph (AST traversal, dependency graph, symbol extraction)
+- Read files (for sampling source when codegraph output needs clarification)
+- Write files (to produce context.json)
+
+Do not call any LLM for summarization. Just extract structure.

.claude/agents/interviewer.md

@@ -0,0 +1,30 @@
+# Human-in-the-loop Interviewer
+
+You receive assessment.json. Your job is to have a conversation 
+with the developer to fill in the gaps the reasoner couldn't know.
+
+## How to run the interview
+
+Present each question conversationally, not as a numbered list.
+React to their answers — if they reveal something that recontextualizes
+an earlier question, say so and adjust.
+
+Example flow:
+  You: "The auth system uses session tokens stored in Redis — 
+        was that a deliberate choice for horizontal scaling, 
+        or did it just land that way?"
+
+  Dev: "It landed that way, we don't actually need Redis."
+
+  You: "Good to know — that simplifies things significantly. 
+        On that note, what's your actual scale target? 
+        That changes what we'd recommend for several things."
+
+## Also ask
+At the end, always ask:
+- "What does success look like in 6 months for this project?"
+- "What's the one thing you most want to clean up but haven't had time for?"
+
+## Output
+Write answers.json with the full Q&A captured as context 
+for the reasoner's second pass.

.claude/agents/reasoner.md

@@ -0,0 +1,47 @@
+# Technical Reasoner Agent
+
+You are a senior staff engineer doing a deep technical audit.
+You receive context.json from a codebase AST analysis.
+
+## Your assessment covers
+
+### 1. Project overview
+One sharp paragraph. What does this actually do, who would use it, 
+what's the core technical bet.
+
+### 2. What's implemented well
+Specific praise with file references. Things like:
+- Clean separation of concerns
+- Good use of a pattern for the domain
+- Well-placed abstractions
+
+### 3. Over-engineering (be direct)
+Call out things that add complexity without proportional value:
+- Abstraction layers that don't earn their keep
+- Premature generalization
+- Framework sprawl
+- "Enterprise patterns" on a 2-person codebase
+
+### 4. Needs improvement
+Things that are actually wrong or risky:
+- Missing error handling at I/O boundaries
+- Hardcoded config that will break in production
+- No observability
+- Tight coupling that will hurt when requirements change
+
+### 5. Productization gaps
+What needs to exist before this is a product, not a project:
+- Auth/authz
+- Rate limiting
+- Secrets management
+- Migration strategy
+- Graceful degradation
+
+### 6. Questions for the human
+Things you genuinely don't know without intent context.
+Ask about WHY decisions were made, not just what they are.
+Max 6 questions. Make them count.
+
+## Output
+Write assessment.json with all sections as structured data.
+Be specific: cite file names and function names. Never generalize.

.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "agents": {
+    "crawler": {
+      "model": "claude-haiku-4-5-20251001",
+      "note": "mostly tool calls, minimal reasoning needed"
+    },
+    "reasoner": {
+      "model": "claude-opus-4-8",
+      "note": "deep assessment, use the best model"
+    },
+    "interviewer": {
+      "model": "claude-sonnet-4-6",
+      "note": "conversational, needs to be good but not Opus"
+    },
+    "orchestrator": {
+      "model": "claude-sonnet-4-6",
+      "note": "routing only, Sonnet is fine"
+    }
+  }
+}
+

.codegraph/.gitignore

@@ -0,0 +1,16 @@
+# CodeGraph data files
+# These are local to each machine and should not be committed
+
+# Database
+*.db
+*.db-wal
+*.db-shm
+
+# Cache
+cache/
+
+# Logs
+*.log
+
+# Hook markers
+.dirty

.env.example

@@ -0,0 +1,93 @@
+# ─── Runtime ──────────────────────────────────────────────────────────────────
+# Current environment: development | staging | production
+ENV=development
+
+# ─── Server ───────────────────────────────────────────────────────────────────
+HOST=0.0.0.0
+PORT=5010
+
+# ─── Database ─────────────────────────────────────────────────────────────────
+# Docker Compose: DB_HOST=postgres
+# Local dev (no compose): DB_HOST=localhost
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=mpiper
+DB_PASSWORD=changeme
+DB_NAME=mpiper
+# DB_SSL_MODE defaults to "disable" in the API server
+# DB_SSL_MODE=require
+# DB_SSL_CERT_PATH=/path/to/cert.pem     # Python worker only
+
+# Connection pool (Python worker)
+DB_POOL_SIZE=10
+DB_POOL_TIMEOUT=30
+DB_MAX_RETRIES=5
+DB_RETRY_DELAY=5
+
+# ─── Redis ────────────────────────────────────────────────────────────────────
+# Docker Compose: REDIS_CONNECTION_STRING=redis://redis:6379/0
+# Local dev (no compose): REDIS_CONNECTION_STRING=redis://localhost:6379/0
+REDIS_CONNECTION_STRING=redis://localhost:6379/0
+
+# Connection pool (Python worker)
+REDIS_POOL_SIZE=10
+REDIS_POOL_TIMEOUT=30
+REDIS_MAX_RETRIES=5
+REDIS_RETRY_DELAY=5
+REDIS_CONNECT_TIMEOUT=10
+REDIS_READ_TIMEOUT=10
+REDIS_WRITE_TIMEOUT=10
+
+# ─── Security ─────────────────────────────────────────────────────────────────
+# AES-256 key — must be exactly 32 characters
+ENCRYPTION_KEY=LKyGslR3InLES/EYQiJZcW06KFNMoevUd6kehjtrxPA=
+
+# ─── Storage ──────────────────────────────────────────────────────────────────
+# Set BUCKET_PROVIDER to "gcs" or "s3"
+BUCKET_PROVIDER=gcs
+
+# Bucket name — required for both providers
+BUCKET_NAME=my-media-bucket
+
+# GCS (when BUCKET_PROVIDER=gcs)
+# Path to the GCS service-account JSON key file. The Go API reads GCS_SA_PATH;
+# the Python worker reads BUCKET_SA_PATH — keep both pointing at the same file.
+GCS_SA_PATH=.secrets/service-account.json
+BUCKET_SA_PATH=.secrets/service-account.json
+
+# S3 / S3-compatible (when BUCKET_PROVIDER=s3) — not yet implemented (sub-project 4)
+# BUCKET_REGION=us-east-1
+# BUCKET_ACCESS_KEY=
+# BUCKET_SECRET_KEY=
+# BUCKET_ENDPOINT_URL=          # optional — for MinIO or S3-compatible endpoints
+
+# ─── OpenTelemetry ────────────────────────────────────────────────────────────
+OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:4317
+# Defaults to plaintext gRPC (true) when unset — matches the bundled collector.
+# Set to "false" only if your collector endpoint terminates real TLS.
+OTEL_TLS_INSECURE=true
+DEPLOYMENT_ENV=development
+TRACE_SAMPLING_RATE=0.1
+SERVICE_NAME=mpiper-api
+SERVICE_VERSION=dev
+
+# ─── CORS ─────────────────────────────────────────────────────────────────────
+# Comma-separated list of allowed origins (defaults to http://localhost:5173)
+CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
+
+# ─── Logging ──────────────────────────────────────────────────────────────────
+# DEBUG | INFO | WARN | ERROR | FATAL
+LOG_LEVEL=INFO
+
+# ─── Migrations ───────────────────────────────────────────────────────────────
+# Set to "true" to run DB migrations on startup
+AUTO_MIGRATE=false
+# Python worker: override default migrations directory
+# MIGRATIONS_DIR=/path/to/migrations
+
+# ─── Worker ───────────────────────────────────────────────────────────────────
+WORKER_ID=
+MAX_CONCURRENT_JOBS=5
+JOB_POLL_INTERVAL=10
+STREAM_NAME=media:jobs
+CONSUMER_GROUP=worker-group

.github/slack/failure.json

@@ -0,0 +1,105 @@
+{
+    "blocks": [
+        {
+            "type": "header",
+            "text": {
+                "type": "plain_text",
+                "text": "❌ Build Failed — ${GITHUB_REPOSITORY}",
+                "emoji": true
+            }
+        },
+        {
+            "type": "section",
+            "fields": [
+                {
+                    "type": "mrkdwn",
+                    "text": "*Repository:*\n<https://github.com/${GITHUB_REPOSITORY}|${GITHUB_REPOSITORY}>"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": "*Branch:*\n`${GITHUB_REF_NAME}`"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": "*Commit:*\n<https://github.com/${GITHUB_REPOSITORY}/commit/${GITHUB_SHA}|${GITHUB_SHA_SHORT}>"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": "*Triggered by:*\n${GITHUB_ACTOR}"
+                }
+            ]
+        },
+        {
+            "type": "section",
+            "text": {
+                "type": "mrkdwn",
+                "text": "⚠️ *The build failed during the CI/CD pipeline. Please review the logs and fix the issue before retrying.*"
+            }
+        },
+        {
+            "type": "section",
+            "text": {
+                "type": "mrkdwn",
+                "text": "*💥 Failure Details:*\n```${FAILURE_REASON}```"
+            }
+        },
+        {
+            "type": "divider"
+        },
+        {
+            "type": "section",
+            "fields": [
+                {
+                    "type": "mrkdwn",
+                    "text": "*⏱️ Failed at:*\n${BUILD_TIMESTAMP}"
+                },
+                {
+                    "type": "mrkdwn",
+                    "text": "*🔄 Run:*\n<https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}|#${GITHUB_RUN_NUMBER}>"
+                }
+            ]
+        },
+        {
+            "type": "actions",
+            "elements": [
+                {
+                    "type": "button",
+                    "text": {
+                        "type": "plain_text",
+                        "text": "View Failed Run",
+                        "emoji": true
+                    },
+                    "url": "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}",
+                    "style": "danger"
+                },
+                {
+                    "type": "button",
+                    "text": {
+                        "type": "plain_text",
+                        "text": "View Logs",
+                        "emoji": true
+                    },
+                    "url": "https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}/logs"
+                },
+                {
+                    "type": "button",
+                    "text": {
+                        "type": "plain_text",
+                        "text": "View Commit",
+                        "emoji": true
+                    },
+                    "url": "https://github.com/${GITHUB_REPOSITORY}/commit/${GITHUB_SHA}"
+                }
+            ]
+        },
+        {
+            "type": "context",
+            "elements": [
+                {
+                    "type": "mrkdwn",
+                    "text": "🔴 Build failed at ${BUILD_TIMESTAMP} on branch `${GITHUB_REF_NAME}`"
+                }
+            ]
+        }
+    ]
+}