feat: full bounty validation system with CI, Docker, Watchtower

Complete implementation of GitHub issue validation service:
- SQLite persistence (8 tables), Redis distributed locking
- Validation pipeline: intake, media, spam, duplicate, edit-history
- LLM scoring (Gemini 3.1 Pro Custom Tools) + embeddings (Qwen3)
- GitHub mutations (labels, comments, close/reopen)
- Queue processor with dead-letter and requeue recovery
- HMAC auth for Atlas inter-service communication
- CI workflow (lint, test, Docker build+push to GHCR)
- Watchtower auto-update every 60s
- Comprehensive docs (API, Architecture, Detection, Deployment)
- 149 tests passing

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: echobt

.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  lint-typecheck:
+    name: Lint & Typecheck
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Typecheck
+        run: npx tsc --noEmit
+      - name: Lint
+        run: npm run lint
+
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    services:
+      redis:
+        image: redis:7-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: Run tests
+        run: npx vitest run
+        env:
+          REDIS_URL: redis://localhost:6379
+
+  docker:
+    name: Build & Push Docker Image
+    needs: [lint-typecheck, test]
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=sha
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

Dockerfile

@@ -0,0 +1,44 @@
+# Bounty-bot Service - Dockerfile
+# GitHub bounty validation service, controlled by Atlas via REST API
+
+FROM node:22-slim
+
+# Install system dependencies for better-sqlite3 native module and health checks
+RUN apt-get update && apt-get install -y \
+    python3 \
+    make \
+    g++ \
+    sqlite3 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create app directory
+WORKDIR /app
+
+# Copy package files first for better Docker layer caching
+COPY package*.json ./
+
+# Install dependencies with native build flags
+RUN npm ci --unsafe-perm || npm install --unsafe-perm
+
+# Copy TypeScript config and source
+COPY tsconfig.json ./
+COPY src/ ./src/
+
+# Build TypeScript
+RUN npm run build
+
+# Create required directories
+RUN mkdir -p /app/data
+
+# Environment defaults
+ENV NODE_ENV=production
+ENV PORT=3235
+ENV DATA_DIR=/app/data
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:3235/health || exit 1
+
+# Run the service
+CMD ["node", "dist/index.js"]

README.md

@@ -1,17 +1,150 @@
-# Bounty Bot
+# Bounty-bot
 
-GitHub bounty validation bot - controlled by Atlas via API.
+Automated GitHub bounty issue validation service. Bounty-bot receives GitHub webhook events (or polls for missed issues), runs every submission through a multi-stage detection pipeline — media checks, spam analysis, duplicate detection, edit-history fraud, and LLM-assisted scoring — then publishes a verdict back to GitHub with labels, comments, and issue state changes.
+
+Controlled by **Atlas** via a REST API with HMAC authentication. Callbacks are sent to Atlas on completion or failure.
 
 ## Architecture
 
-- Controlled by [PlatformNetwork/atlas](https://github.com/PlatformNetwork/atlas)
-- REST API on port 3235
-- SQLite persistence
-- GitHub integration for issue validation
+```mermaid
+flowchart TD
+    GH[GitHub Webhook] -->|issues.opened| WH[Webhook Receiver]
+    POLL[Poller] -->|missed events| INT[Intake]
+    ATLAS[Atlas API call] -->|trigger| INT
+    WH --> INT
+    INT -->|filter ≥ #41000| Q[Queue]
+    Q --> PIPE[Validation Pipeline]
+
+    subgraph Pipeline
+        PIPE --> MEDIA[Media Check]
+        MEDIA --> SPAM[Spam Detection]
+        SPAM --> DUP[Duplicate Detection]
+        DUP --> EDIT[Edit History]
+        EDIT --> LLM[LLM Validity Gate]
+    end
+
+    LLM --> VERD[Verdict Engine]
+    VERD -->|labels + comment| GH_MUT[GitHub Mutations]
+    VERD -->|webhook callback| ATLAS_CB[Atlas Callback]
+    VERD -->|persist| DB[(SQLite)]
+
+    Q -->|max retries| DL[Dead Letter]
+```
+
+## Quick Start
+
+### Prerequisites
+
+| Dependency | Version |
+|---|---|
+| Node.js | ≥ 20 |
+| Redis | any (default port 3231) |
+| Docker + Compose | optional, for containerised deployment |
+
+### Environment Variables
+
+Create a `.env` file (see [Configuration](#configuration) for the full list):
+
+```env
+GITHUB_TOKEN=ghp_...
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+INTER_SERVICE_HMAC_SECRET=shared-secret-with-atlas
+REDIS_URL=redis://localhost:3231
+OPENROUTER_API_KEY=sk-or-...
+ATLAS_WEBHOOK_URL=http://localhost:3230/webhooks
+TARGET_REPO=PlatformNetwork/bounty-challenge
+```
+
+### Docker Compose
+
+```bash
+docker compose up -d
+```
+
+The service starts on **port 3235** with SQLite data persisted in a Docker volume.
+
+### Development Mode
+
+```bash
+npm install
+npm run dev          # tsx hot-reload on src/index.ts
+npm run build        # compile TypeScript
+npm start            # run compiled output
+```
+
+## API Reference
+
+All `/api/v1/*` endpoints (except webhooks) require HMAC authentication via `X-Signature` and `X-Timestamp` headers.
+
+| Method | Endpoint | Auth | Description |
+|---|---|---|---|
+| `POST` | `/api/v1/validation/trigger` | HMAC | Trigger validation for an issue |
+| `GET` | `/api/v1/validation/:issue_number/status` | HMAC | Get processing status and verdict |
+| `POST` | `/api/v1/validation/:issue_number/requeue` | HMAC | Requeue for re-validation (24 h max, once per issue) |
+| `POST` | `/api/v1/validation/:issue_number/force-release` | HMAC | Clear a stale processing lock |
+| `GET` | `/api/v1/dead-letter` | HMAC | List dead-lettered items |
+| `POST` | `/api/v1/dead-letter/:id/recover` | HMAC | Re-enqueue a dead-letter item |
+| `POST` | `/api/v1/webhooks/github` | GitHub signature | Receive GitHub webhook events |
+| `GET` | `/health` | none | Liveness probe |
+| `GET` | `/ready` | none | Readiness probe |
+
+See [docs/API.md](docs/API.md) for full request/response schemas.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `3235` | API listen port |
+| `DATA_DIR` | `./data` | SQLite data directory |
+| `SQLITE_PATH` | `<DATA_DIR>/bounty-bot.db` | Database file path |
+| `REDIS_URL` | `redis://localhost:3231` | Redis connection URL |
+| `GITHUB_TOKEN` | — | GitHub PAT for API requests |
+| `GITHUB_WEBHOOK_SECRET` | — | Secret for verifying GitHub webhook signatures |
+| `INTER_SERVICE_HMAC_SECRET` | — | Shared HMAC secret for Atlas ↔ bounty-bot auth |
+| `ATLAS_WEBHOOK_URL` | `http://localhost:3230/webhooks` | Atlas callback endpoint |
+| `TARGET_REPO` | `PlatformNetwork/bounty-challenge` | GitHub repo to validate (owner/repo) |
+| `OPENROUTER_API_KEY` | — | OpenRouter key for LLM scoring and embeddings |
+| `OPENROUTER_BASE_URL` | `https://openrouter.ai/api/v1` | OpenRouter API base URL |
+| `EMBEDDING_MODEL` | `qwen/qwen3-embedding-8b` | Model for semantic embeddings |
+| `LLM_SCORING_MODEL` | `google/gemini-3.1-pro-preview-customtools` | Model for issue evaluation |
+| `POLLER_INTERVAL` | `60000` | Missed-webhook poller interval (ms) |
+| `MAX_RETRIES` | `3` | Queue retry limit before dead-lettering |
+| `ISSUE_FLOOR` | `41000` | Minimum issue number to process |
+| `SPAM_THRESHOLD` | `0.7` | Spam score threshold (0–1) |
+| `DUPLICATE_THRESHOLD` | `0.75` | Duplicate similarity threshold (0–1) |
+| `REQUEUE_MAX_AGE_MS` | `86400000` | Max issue age for requeue eligibility (24 h) |
+| `WEBHOOK_MAX_RETRIES` | `3` | Atlas callback retry attempts |
+| `WEBHOOK_RETRY_DELAY_MS` | `1000` | Base delay between callback retries (ms) |
+
+## LLM Integration
+
+Bounty-bot uses two AI models via [OpenRouter](https://openrouter.ai) (OpenAI-compatible API):
+
+### Gemini 3.1 Pro Custom Tools — Issue Evaluation
+
+Model: `google/gemini-3.1-pro-preview-customtools`
+
+Used for full issue evaluation and borderline spam scoring. The model receives a system prompt describing the evaluation criteria and is forced to call a `deliver_verdict` function via OpenAI-style tool/function calling. Returns a structured verdict (`valid` / `invalid` / `duplicate`), confidence score, reasoning, and a public-facing recap.
+
+### Qwen3 Embedding 8B — Semantic Duplicate Detection
+
+Model: `qwen/qwen3-embedding-8b`
+
+Generates high-dimensional embedding vectors for issue text. These vectors are stored in SQLite and compared via cosine similarity to detect semantic duplicates that lexical fingerprinting might miss. The final duplicate score is a hybrid: `0.4 × Jaccard + 0.6 × cosine`.
+
+Both models gracefully degrade: if `OPENROUTER_API_KEY` is unset, the system falls back to lexical-only detection and skips LLM scoring.
+
+## Testing
+
+```bash
+npm test             # run all 149 tests (vitest)
+npm run typecheck    # TypeScript type checking
+npm run lint         # ESLint
+```
 
-## Endpoints
+## Further Documentation
 
-- `GET /health` - Health check
-- `POST /api/validate` - Trigger validation (Atlas → Bounty-bot)
-- `GET /api/status/:issue` - Check validation status
-- `POST /api/requeue` - Requeue issue for validation
+- [Architecture](docs/ARCHITECTURE.md) — system design, module graph, sequence diagrams, database schema
+- [API Reference](docs/API.md) — full REST API with request/response schemas
+- [Detection Engine](docs/DETECTION.md) — spam, duplicate, edit-history, and LLM scoring details
+- [Deployment](docs/DEPLOYMENT.md) — Docker, Redis, health checks, Atlas integration

docker-compose.yml

@@ -0,0 +1,99 @@
+# Bounty-bot Service - Docker Compose
+# Port allocation: 3235-3239 (Bounty-bot services)
+# Atlas uses 3230-3234 separately
+#
+# Watchtower polls GHCR every 60s and auto-restarts on new images.
+# CI pushes ghcr.io/platformnetwork/bounty-bot:latest on main.
+
+services:
+  bounty-bot:
+    image: ghcr.io/platformnetwork/bounty-bot:latest
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: bounty-bot
+    restart: unless-stopped
+    ports:
+      - "3235:3235"
+    environment:
+      - NODE_ENV=production
+      - PORT=3235
+      - DATA_DIR=/app/data
+      - REDIS_URL=redis://redis:6379
+      - TZ=UTC
+    volumes:
+      - bounty-data:/app/data
+    depends_on:
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3235/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
+    networks:
+      - bounty-network
+    labels:
+      - "com.centurylinklabs.watchtower.enable=true"
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+        reservations:
+          memory: 256M
+
+  redis:
+    image: redis:7-alpine
+    container_name: bounty-redis
+    restart: unless-stopped
+    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
+    volumes:
+      - redis-data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 5s
+    networks:
+      - bounty-network
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+        reservations:
+          memory: 64M
+
+  watchtower:
+    image: containrrr/watchtower:latest
+    container_name: bounty-watchtower
+    restart: unless-stopped
+    environment:
+      - WATCHTOWER_POLL_INTERVAL=60
+      - WATCHTOWER_CLEANUP=true
+      - WATCHTOWER_LABEL_ENABLE=true
+      - WATCHTOWER_ROLLING_RESTART=true
+      - WATCHTOWER_INCLUDE_RESTARTING=true
+      - WATCHTOWER_REVIVE_STOPPED=true
+      - WATCHTOWER_NOTIFICATIONS=shoutrrr
+      - WATCHTOWER_LIFECYCLE_HOOKS=true
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /root/.docker/config.json:/config.json:ro
+    networks:
+      - bounty-network
+    deploy:
+      resources:
+        limits:
+          memory: 128M
+
+networks:
+  bounty-network:
+    driver: bridge
+
+volumes:
+  bounty-data:
+    name: bounty-bot-data
+  redis-data:
+    name: bounty-redis-data