forgedock 1.0.0

package/docs/CODEX.md

@@ -0,0 +1,92 @@
+# Codex Support
+
+Forge now has an additive Codex-native install path. The goal is to preserve Forge behavior without regressing the existing Claude setup.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the workflow spec for both runtimes
+
+Claude wrapper:
+- `install.sh` symlinks command files into `~/.claude/commands`
+
+Codex wrapper:
+- `install-codex.sh` generates namespaced skills in `~/.codex/skills`
+- each installed skill adapts one shared command spec for Codex-native execution
+- if a matching repo-local skill exists under `.agents/skills/<command>/SKILL.md`, the installer points the installed wrapper at that repo-local adapter instead of the generic wrapper
+
+This is intentionally a wrapper architecture, not a duplicate command tree.
+
+## Install
+
+From the repo root:
+
+```bash
+./install-codex.sh
+```
+
+The installer creates:
+- `~/.codex/skills/forge/SKILL.md`
+- `~/.codex/skills/forge-*/SKILL.md` for each command file under `commands/`, excluding internal catalog files that are read on demand
+
+It does not overwrite unrelated global Codex skills.
+
+## Skill Naming
+
+Command files map to installed Codex skill names using:
+- `forge-` prefix
+- `/` replaced by `-`
+- `.md` removed
+
+Examples:
+
+| Shared command spec | Installed Codex skill |
+|---|---|
+| `commands/work-on.md` | `forge-work-on` |
+| `commands/review-pr.md` | `forge-review-pr` |
+| `commands/orchestrate.md` | `forge-orchestrate` |
+| `commands/work-on/investigate.md` | `forge-work-on-investigate` |
+| `commands/work-on/build/context.md` | `forge-work-on-build-context` |
+
+`commands/review-pr-agents.md` is excluded because it is a read-on-demand catalog, not a standalone entrypoint.
+
+## How the Adapter Works
+
+Each generated skill instructs Codex to:
+- read the shared command spec from `commands/`
+- translate Claude-specific workflow assumptions into Codex-native tools
+- preserve GitHub labels, structured comments, worktree conventions, and workflow sequencing
+- continue with the closest Codex-native execution path when a Claude-only affordance does not exist
+
+Translation rules:
+- Claude slash command invocation -> installed `forge-*` skill
+- `Skill("x")` -> corresponding `forge-*` skill when available, otherwise direct continuation from the referenced source file
+- `Agent(...)` / `Task(...)` -> Codex sub-agents when the source workflow genuinely benefits from orchestration
+- `Bash`, `Read`, `Grep`, `Glob` -> Codex shell/file tools with `gh`, `git`, `rg`, `sed`, `find`, and repo scripts
+- `WebFetch` -> web tooling or API calls via `gh` / `curl`
+
+When a repo-local adapter exists under `.agents/skills/`, it becomes authoritative for that command in this repo. Use that layer for repo-specific overrides such as:
+- different default GitHub repo resolution
+- Codex-native worktree roots
+- Forge-specific review heuristics
+- best-effort handling of project-board steps that are AlterLab-specific upstream
+
+## Trust and Global Config
+
+Codex may require the repo directory to be trusted in `~/.codex/config.toml`.
+
+If Forge is not already trusted, add a project entry like:
+
+```toml
+[projects."/absolute/path/to/forge"]
+trust_level = "trusted"
+```
+
+The installer does not modify global trust settings automatically.
+
+## Usage Notes
+
+- Use the installed `forge` skill as the overview/router entrypoint.
+- Use command-specific skills such as `forge-work-on` or `forge-review-pr` when the task is already clear.
+- Keep `CLAUDE.md` and `AGENTS.md` aligned; Claude and Codex can differ at the wrapper layer, but not on Forge workflow invariants.
+- For workflow paths that have repo-local adapters, prefer those adapters over the generic generated behavior.

package/docs/WORKFLOW.md

@@ -0,0 +1,104 @@
+# Workflow Reference
+
+Canonical reference for field IDs, option IDs, and integration constants used by Forge commands.
+
+---
+
+## Project Board Integration
+
+**Project ID**: `PVT_kwHOCx3gR84BSK2L`
+
+All commands that add issues to the GitHub Project board use the field and option IDs below.
+Reference this document rather than hardcoding values inline.
+
+### Field IDs
+
+| Field | Field ID |
+|-------|----------|
+| Status | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E` |
+| Lane | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF98` |
+| Component | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o` |
+| Priority | `PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o` |
+| Workflow | `PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA` |
+
+### Status Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E`)
+
+| Value | Option ID |
+|-------|-----------|
+| Todo | `f75ad846` |
+| In Progress | _(query live if needed)_ |
+| Done | `98236657` |
+
+### Lane Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF98`)
+
+| Value | Option ID |
+|-------|-----------|
+| Fast | `62864af4` |
+| Feature | `4ff6f9e6` |
+| Sync | `c0c37d33` |
+
+### Component Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o`)
+
+| Value | Option ID | Repo |
+|-------|-----------|------|
+| Platform | `214c4d65` | `RapierCraft/AlterLab` |
+| MCP Server | _(query live if needed)_ | `RapierCraft/alterlab-mcp-server` |
+| n8n Node | _(query live if needed)_ | `RapierCraft/n8n-nodes-alterlab` |
+| Python SDK | _(query live if needed)_ | `RapierCraft/alterlab-python` |
+| Node SDK | _(query live if needed)_ | `RapierCraft/alterlab-node` |
+
+### Priority Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o`)
+
+| Value | Option ID |
+|-------|-----------|
+| P0 | _(query live if needed)_ |
+| P1 | _(query live if needed)_ |
+| P2 | `4d95eef3` |
+| P3 | _(query live if needed)_ |
+
+### Workflow Field Options (`PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA`)
+
+| Value | Option ID |
+|-------|-----------|
+| Investigating | _(query live if needed)_ |
+| Building | _(query live if needed)_ |
+| In Review | _(query live if needed)_ |
+| Merged | `b510c537` |
+
+### Usage Pattern
+
+```bash
+# Add issue to project board and set initial fields
+ITEM_ID=$(gh project item-add PVT_kwHOCx3gR84BSK2L --owner RapierCraft --url "$ISSUE_URL" --format json --jq '.id')
+
+# Set Status=Todo
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id f75ad846 2>/dev/null || true
+
+# Set Lane (Fast=62864af4, Feature=4ff6f9e6, Sync=c0c37d33)
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF98 --single-select-option-id 62864af4 2>/dev/null || true
+
+# Set Component=Platform
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF-o --single-select-option-id 214c4d65 2>/dev/null || true
+
+# Set Priority (P2=4d95eef3)
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF8o --single-select-option-id 4d95eef3 2>/dev/null || true
+
+# On merge: set Status=Done and Workflow=Merged
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yF6E --single-select-option-id 98236657 2>/dev/null || true
+gh project item-edit --project-id PVT_kwHOCx3gR84BSK2L --id "$ITEM_ID" \
+  --field-id PVTSSF_lAHOCx3gR84BSK2Lzg_yGAA --single-select-option-id b510c537 2>/dev/null || true
+```
+
+### Querying Unknown Option IDs
+
+For option IDs marked "_(query live if needed)_", use:
+
+```bash
+gh project field-list PVT_kwHOCx3gR84BSK2L --owner RapierCraft --format json \
+  --jq '.fields[] | select(.name == "Status") | .options'
+```

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "forgedock",
+  "version": "1.0.0",
+  "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
+  "bin": {
+    "forgedock": "./bin/forgedock.mjs"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "autonomous-coding",
+    "github-automation",
+    "developer-tools",
+    "ai-pipeline",
+    "code-review",
+    "llm",
+    "knowledge-graph",
+    "claude",
+    "anthropic",
+    "agentic-ai",
+    "devtools",
+    "automation"
+  ],
+  "author": "RapierCraft Studios",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RapierCraftStudios/ForgeDock.git"
+  },
+  "homepage": "https://github.com/RapierCraftStudios/ForgeDock",
+  "bugs": {
+    "url": "https://github.com/RapierCraftStudios/ForgeDock/issues"
+  },
+  "files": [
+    "bin/",
+    "commands/",
+    "docs/",
+    "scripts/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/verify-env-vars.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+# verify-env-vars.sh — Check that new environment variables are properly wired
+#
+# Usage: verify-env-vars.sh <pr_diff_file> <repo_root>
+#   pr_diff_file: path to file containing unified diff output (or "-" for stdin)
+#   repo_root: path to the repository root
+#
+# Output: Structured findings (one per line, prefixed with severity)
+#   BLOCKING: <message>  — must fix before merge
+#   WARNING:  <message>  — likely issue, verify manually
+#   OK:       <message>  — check passed
+#
+# Exit codes: 0 = all checks passed, 1 = blocking findings, 2 = warnings only
+
+set -euo pipefail
+
+DIFF_INPUT="${1:--}"
+REPO_ROOT="${2:-.}"
+
+if [ "$DIFF_INPUT" = "-" ]; then
+    DIFF_CONTENT=$(cat)
+else
+    DIFF_CONTENT=$(cat "$DIFF_INPUT")
+fi
+
+BLOCKING=0
+WARNINGS=0
+
+# Extract new env var references from added lines in the diff (Python + Node.js)
+NEW_ENVS=$(echo "$DIFF_CONTENT" | grep -E "^\+" | grep -oE 'os\.getenv\("[^"]+"\)|os\.environ\["[^"]+"\]|os\.environ\.get\("[^"]+"\)|process\.env\.[A-Z_]+' | sort -u)
+
+# --- Docker Compose entrypoint/command env var wiring check ---
+# When docker-compose files change entrypoint: or command: to reference shell vars,
+# those vars must be available inside the container via environment: or env_file:.
+# Compose interpolation (${VAR} in YAML) happens at parse time on the host.
+# Shell vars (${VAR} in entrypoint scripts) need runtime injection via environment:.
+# Mixing these up causes silent failures — the var is empty inside the container.
+#
+# This check was added after the Redis incident (forge #185): PR #14554 migrated Redis
+# from command: args (Compose interpolation) to entrypoint.sh (container runtime),
+# but never added environment: to pass REDIS_PASSWORD into the container.
+
+COMPOSE_ENV_BLOCKING=0
+COMPOSE_FILES=$(echo "$DIFF_CONTENT" | grep -E "^\+\+\+ b/" | grep -oE 'docker-compose[^[:space:]]*\.yml' | sort -u)
+
+if [ -n "$COMPOSE_FILES" ]; then
+    echo "=== Docker Compose Entrypoint/Command Env Var Wiring ==="
+
+    for compose_file in $COMPOSE_FILES; do
+        COMPOSE_PATH="$REPO_ROOT/$compose_file"
+        [ -f "$COMPOSE_PATH" ] || continue
+
+        # Find services that have entrypoint: or command: referencing scripts
+        # (not inline ${VAR} which is Compose interpolation — those are fine)
+        # We look for entrypoint lines pointing to .sh files
+        ENTRYPOINT_SCRIPTS=$(grep -A1 'entrypoint:' "$COMPOSE_PATH" 2>/dev/null \
+            | grep -oE '/[a-zA-Z0-9_./-]+\.sh' | sort -u)
+
+        for script_ref in $ENTRYPOINT_SCRIPTS; do
+            # Find the script file in the repo
+            SCRIPT_PATH=$(find "$REPO_ROOT" -path "*${script_ref}" -type f 2>/dev/null | head -1)
+            [ -n "$SCRIPT_PATH" ] || continue
+
+            # Extract ${VAR} and $VAR references from the script (skip comments)
+            SCRIPT_VARS=$(grep -v '^\s*#' "$SCRIPT_PATH" 2>/dev/null \
+                | grep -oE '\$\{?[A-Z][A-Z_0-9]{2,}\}?' \
+                | sed 's/[${}]//g' \
+                | sort -u)
+
+            [ -n "$SCRIPT_VARS" ] || continue
+
+            # Determine which service this entrypoint belongs to
+            # (search backward from the entrypoint line to find the service name)
+            SERVICE_NAME=$(awk "/entrypoint:.*$(basename "$script_ref")/{found=1} found && /^  [a-z]/{print; exit}" "$COMPOSE_PATH" 2>/dev/null \
+                | sed 's/://; s/^  //' || echo "unknown")
+            # Fallback: extract service by finding the indented block containing this entrypoint
+            if [ "$SERVICE_NAME" = "unknown" ] || [ -z "$SERVICE_NAME" ]; then
+                SERVICE_NAME=$(awk '/^  [a-z_-]+:/{svc=$1} /entrypoint:.*'"$(basename "$script_ref")"'/{print svc; exit}' "$COMPOSE_PATH" 2>/dev/null \
+                    | sed 's/://')
+            fi
+
+            # Extract vars from this service's environment: section
+            SERVICE_ENV_VARS=$(awk "/^  ${SERVICE_NAME}:/,/^  [a-z]/" "$COMPOSE_PATH" 2>/dev/null \
+                | awk '/environment:/,/^    [a-z]|^  [a-z]/' \
+                | grep -oE '[A-Z][A-Z_0-9]{2,}' \
+                | sort -u)
+
+            # Also check env_file: — if present, vars come from .env or specified file
+            HAS_ENV_FILE=$(awk "/^  ${SERVICE_NAME}:/,/^  [a-z]/" "$COMPOSE_PATH" 2>/dev/null \
+                | grep -c 'env_file:' || true)
+
+            for var in $SCRIPT_VARS; do
+                # Skip common shell vars that aren't env config
+                case "$var" in
+                    PATH|HOME|USER|SHELL|PWD|TERM|HOSTNAME|LANG) continue ;;
+                esac
+
+                IN_ENV=$(echo "$SERVICE_ENV_VARS" | grep -cx "$var" || true)
+
+                if [ "$IN_ENV" -eq 0 ] && [ "$HAS_ENV_FILE" -eq 0 ]; then
+                    echo "BLOCKING: $var used in entrypoint $script_ref (service: ${SERVICE_NAME:-unknown}) but NOT in service environment: section of $compose_file — container will not receive this var at runtime"
+                    COMPOSE_ENV_BLOCKING=$((COMPOSE_ENV_BLOCKING + 1))
+                elif [ "$IN_ENV" -eq 0 ] && [ "$HAS_ENV_FILE" -gt 0 ]; then
+                    echo "WARNING: $var used in entrypoint $script_ref (service: ${SERVICE_NAME:-unknown}) — not in explicit environment: but service has env_file: — verify var is in the referenced env file"
+                    WARNINGS=$((WARNINGS + 1))
+                else
+                    echo "OK: $var — in environment: section of service ${SERVICE_NAME:-unknown}"
+                fi
+            done
+        done
+    done
+
+    if [ "$COMPOSE_ENV_BLOCKING" -eq 0 ] && [ -n "$COMPOSE_FILES" ]; then
+        echo "OK: No docker-compose entrypoint env var wiring issues found"
+    fi
+    echo ""
+fi
+
+BLOCKING=$((BLOCKING + COMPOSE_ENV_BLOCKING))
+
+if [ -z "$NEW_ENVS" ] && [ "$COMPOSE_ENV_BLOCKING" -eq 0 ]; then
+    echo "OK: No new environment variable references detected in diff"
+    exit 0
+fi
+
+if [ -n "$NEW_ENVS" ]; then
+    echo "=== New Environment Variable References ==="
+    echo "$NEW_ENVS"
+    echo ""
+fi
+
+# Extract just the variable names from Python/Node references
+VAR_NAMES=$(echo "$NEW_ENVS" | grep -oE '[A-Z][A-Z_0-9]{2,}' | sort -u)
+
+# If no Python/Node env vars found, skip to summary (compose checks already ran above)
+if [ -z "$VAR_NAMES" ]; then
+    echo ""
+    echo "=== Summary ==="
+    echo "Python/Node vars checked: 0"
+    echo "Compose entrypoint vars blocking: $COMPOSE_ENV_BLOCKING"
+    echo "Blocking: $BLOCKING"
+    echo "Warnings: $WARNINGS"
+
+    if [ "$BLOCKING" -gt 0 ]; then
+        exit 1
+    elif [ "$WARNINGS" -gt 0 ]; then
+        exit 2
+    fi
+    exit 0
+fi
+
+for var in $VAR_NAMES; do
+    echo "--- Checking: $var ---"
+    FOUND_IN=""
+
+    # Check .env.example
+    if [ -f "$REPO_ROOT/.env.example" ] && grep -q "$var" "$REPO_ROOT/.env.example" 2>/dev/null; then
+        FOUND_IN="${FOUND_IN} .env.example"
+    fi
+
+    # Check docker-compose.yml
+    if [ -f "$REPO_ROOT/docker-compose.yml" ] && grep -q "$var" "$REPO_ROOT/docker-compose.yml" 2>/dev/null; then
+        FOUND_IN="${FOUND_IN} docker-compose.yml"
+    fi
+
+    # Check docker-compose.prod.yml
+    if [ -f "$REPO_ROOT/docker-compose.prod.yml" ] && grep -q "$var" "$REPO_ROOT/docker-compose.prod.yml" 2>/dev/null; then
+        FOUND_IN="${FOUND_IN} docker-compose.prod.yml"
+    fi
+
+    # Check env_validation.py (Python API vars)
+    if [ -f "$REPO_ROOT/services/api/app/core/env_validation.py" ] && grep -q "$var" "$REPO_ROOT/services/api/app/core/env_validation.py" 2>/dev/null; then
+        FOUND_IN="${FOUND_IN} env_validation.py"
+    fi
+
+    # Check decrypt-secrets.sh (SOPS mapping)
+    if [ -f "$REPO_ROOT/scripts/decrypt-secrets.sh" ] && grep -q "$var" "$REPO_ROOT/scripts/decrypt-secrets.sh" 2>/dev/null; then
+        FOUND_IN="${FOUND_IN} decrypt-secrets.sh"
+    fi
+
+    if [ -z "$FOUND_IN" ]; then
+        echo "BLOCKING: $var — not found in .env.example, docker-compose.yml, or env_validation.py"
+        BLOCKING=$((BLOCKING + 1))
+    else
+        echo "OK: $var — found in:$FOUND_IN"
+    fi
+done
+
+echo ""
+echo "=== Summary ==="
+echo "Variables checked: $(echo "$VAR_NAMES" | wc -w)"
+echo "Blocking: $BLOCKING"
+echo "Warnings: $WARNINGS"
+
+# --- Exit code ---
+if [ "$BLOCKING" -gt 0 ]; then
+    exit 1
+elif [ "$WARNINGS" -gt 0 ]; then
+    exit 2
+fi
+exit 0

package/scripts/verify-host-headers.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# verify-host-headers.sh — Check that shell scripts using curl/wget set proper Host headers
+#
+# Usage: verify-host-headers.sh <changed_files_file> <repo_root>
+#   changed_files_file: path to a file listing changed shell scripts (one per line), or "-" for stdin
+#   repo_root: path to the repository root
+#
+# Output: Structured findings (one per line, prefixed with severity)
+#   BLOCKING: <message>  — must fix before merge
+#   WARNING:  <message>  — likely issue, verify manually
+#   OK:       <message>  — check passed
+#
+# Exit codes: 0 = all checks passed, 1 = blocking findings, 2 = warnings only
+
+set -euo pipefail
+
+CHANGED_FILES="${1:--}"
+REPO_ROOT="${2:-.}"
+
+if [ "$CHANGED_FILES" = "-" ]; then
+    FILES=$(cat)
+else
+    FILES=$(cat "$CHANGED_FILES")
+fi
+
+# Filter to only shell scripts
+SHELL_FILES=$(echo "$FILES" | grep -E '\.(sh|bash)$' || true)
+
+if [ -z "$SHELL_FILES" ]; then
+    echo "OK: No shell scripts in changed files"
+    exit 0
+fi
+
+BLOCKING=0
+WARNINGS=0
+
+# Internal service patterns — requests to these need explicit Host headers
+INTERNAL_PATTERNS="localhost|127\.0\.0\.1|api-|worker-|alterlab-|172\.[0-9]+\.[0-9]+\.[0-9]+|\\\$\{?[a-z_]*ip|\\\$\{?[A-Z_]*IP"
+
+echo "$SHELL_FILES" | while read -r f; do
+    FILEPATH="$REPO_ROOT/$f"
+    if [ ! -f "$FILEPATH" ]; then
+        continue
+    fi
+
+    # Find curl/wget commands targeting internal services
+    CURL_LINES=$(grep -nE "(curl|wget)" "$FILEPATH" 2>/dev/null | grep -E "$INTERNAL_PATTERNS" || true)
+
+    if [ -z "$CURL_LINES" ]; then
+        echo "OK: $f — no internal service HTTP calls found"
+        continue
+    fi
+
+    echo "=== Checking: $f ==="
+    echo "$CURL_LINES" | while IFS= read -r line; do
+        LINENO=$(echo "$line" | cut -d: -f1)
+        CONTENT=$(echo "$line" | cut -d: -f2-)
+
+        # Check if a Host header is explicitly set
+        if echo "$CONTENT" | grep -qE "\-H\s+[\"']Host:"; then
+            echo "OK: $f:$LINENO — Host header explicitly set"
+        elif echo "$CONTENT" | grep -qE "\-\-header\s+[\"']Host:"; then
+            echo "OK: $f:$LINENO — Host header explicitly set (--header)"
+        else
+            echo "BLOCKING: $f:$LINENO — curl/wget to internal service without explicit Host header. TrustedHostMiddleware will reject raw IP as Host value."
+            echo "  Line: $CONTENT"
+            echo "  Fix: Add -H 'Host: localhost' (or appropriate allowed host from services/api/app/main.py allowed_hosts)"
+            BLOCKING=$((BLOCKING + 1))
+        fi
+    done
+done || true
+
+# --- Client-side proxy bypass check ---
+# Check frontend files for direct /api/v1/ calls (bypasses Next.js auth proxy)
+FRONTEND_FILES=$(echo "$FILES" | grep -E '\.(tsx?|jsx?)$' | grep -v 'route\.ts$' | grep -v '\.d\.ts$' || true)
+
+if [ -n "$FRONTEND_FILES" ]; then
+    echo ""
+    echo "=== Client-Side Proxy Bypass Check ==="
+    echo "$FRONTEND_FILES" | while read -r f; do
+        FILEPATH="$REPO_ROOT/$f"
+        if [ ! -f "$FILEPATH" ]; then
+            continue
+        fi
+
+        # Check for direct /api/v1/ calls in fetch/useSWR/apiFetch
+        DIRECT_CALLS=$(grep -nE "(fetch|useSWR|apiFetch|adminFetcher)\s*[(<]\s*[\`\"']/api/v1/" "$FILEPATH" 2>/dev/null || true)
+        if [ -z "$DIRECT_CALLS" ]; then
+            # Also check template literals
+            DIRECT_CALLS=$(grep -nE '`/api/v1/' "$FILEPATH" 2>/dev/null | grep -vE '^\s*//' || true)
+        fi
+
+        if [ -n "$DIRECT_CALLS" ]; then
+            echo "BLOCKING: $f — direct /api/v1/ call bypasses Next.js proxy (auth will fail)"
+            echo "$DIRECT_CALLS" | while IFS= read -r match; do
+                echo "  $match"
+            done
+            echo "  Fix: Use /api/* proxy routes instead of /api/v1/* direct FastAPI calls"
+            BLOCKING=$((BLOCKING + 1))
+        else
+            echo "OK: $f — no direct backend calls"
+        fi
+    done
+fi
+
+echo ""
+echo "=== Summary ==="
+echo "Blocking: $BLOCKING"
+echo "Warnings: $WARNINGS"
+
+# --- Exit code ---
+if [ "$BLOCKING" -gt 0 ]; then
+    exit 1
+elif [ "$WARNINGS" -gt 0 ]; then
+    exit 2
+fi
+exit 0

package/scripts/verify-route-registration.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# verify-route-registration.sh — Check that route handlers and API routers are registered
+#
+# Usage: verify-route-registration.sh <changed_files_file> <repo_root>
+#   changed_files_file: path to a file listing changed files (one per line)
+#   repo_root: path to the repository root
+#
+# Output: Structured findings (one per line, prefixed with severity)
+#   BLOCKING: <message>  — must fix before merge
+#   WARNING:  <message>  — likely issue, verify manually
+#   OK:       <message>  — check passed
+#
+# Exit codes: 0 = all checks passed, 1 = blocking findings, 2 = warnings only
+
+set -euo pipefail
+
+CHANGED_FILES="${1:--}"
+REPO_ROOT="${2:-.}"
+
+if [ "$CHANGED_FILES" = "-" ]; then
+    FILES=$(cat)
+else
+    FILES=$(cat "$CHANGED_FILES")
+fi
+
+BLOCKING=0
+WARNINGS=0
+
+# --- Next.js Route Handler registration check ---
+echo "$FILES" | grep -E "^web/src/app/api/.*route\.ts$" | while read -r f; do
+    URL_PATH=$(echo "$f" | sed 's|^web/src/app||; s|/route\.ts$||; s|\[.*\]|*|g')
+    ROUTE_SEGMENT=$(echo "$URL_PATH" | sed 's|/api/v1/||; s|/.*||')
+
+    # Check if next.config.js has a rewrite that might shadow this route
+    if [ -f "$REPO_ROOT/web/next.config.js" ]; then
+        if grep -q "$ROUTE_SEGMENT" "$REPO_ROOT/web/next.config.js" 2>/dev/null; then
+            echo "WARNING: Route handler $f ($URL_PATH) — next.config.js references '$ROUTE_SEGMENT', may shadow this route"
+            WARNINGS=$((WARNINGS + 1))
+        else
+            echo "OK: Route handler $f ($URL_PATH) — no shadowing rewrites found in next.config.js"
+        fi
+    fi
+
+    # Check if nginx routes this path to Next.js or directly to backend
+    if [ -f "$REPO_ROOT/infra/nginx/nginx.conf" ]; then
+        if grep -q "location.*$ROUTE_SEGMENT" "$REPO_ROOT/infra/nginx/nginx.conf" 2>/dev/null; then
+            echo "WARNING: Route handler $f ($URL_PATH) — nginx.conf has a location block for '$ROUTE_SEGMENT', may bypass Next.js"
+            WARNINGS=$((WARNINGS + 1))
+        fi
+    fi
+done || true
+
+# --- Python API Router registration check ---
+echo "$FILES" | grep -E "^services/api/app/routers/.*\.py$" | while read -r f; do
+    ROUTER_NAME=$(basename "$f" .py)
+    MAIN_PY="$REPO_ROOT/services/api/app/main.py"
+
+    if [ -f "$MAIN_PY" ]; then
+        if grep -q "$ROUTER_NAME" "$MAIN_PY" 2>/dev/null; then
+            echo "OK: API Router '$ROUTER_NAME' ($f) — registered in main.py"
+        else
+            echo "BLOCKING: API Router '$ROUTER_NAME' ($f) — NOT found in main.py. Router will not be reachable."
+            BLOCKING=$((BLOCKING + 1))
+        fi
+    else
+        echo "WARNING: Cannot verify router registration — main.py not found at $MAIN_PY"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done || true
+
+# --- Python Middleware registration check ---
+echo "$FILES" | grep -E "^services/api/app/middleware/.*\.py$" | while read -r f; do
+    MIDDLEWARE_NAME=$(basename "$f" .py)
+    MAIN_PY="$REPO_ROOT/services/api/app/main.py"
+
+    if [ -f "$MAIN_PY" ]; then
+        if grep -q "$MIDDLEWARE_NAME" "$MAIN_PY" 2>/dev/null; then
+            echo "OK: Middleware '$MIDDLEWARE_NAME' ($f) — registered in main.py"
+        else
+            echo "WARNING: Middleware '$MIDDLEWARE_NAME' ($f) — not found in main.py. May not be active."
+            WARNINGS=$((WARNINGS + 1))
+        fi
+    fi
+done || true
+
+# --- Shared module import check ---
+echo "$FILES" | grep -E "^shared/.*\.py$" | while read -r f; do
+    MODULE_NAME=$(basename "$f" .py)
+
+    IMPORTERS=$(grep -rl "$MODULE_NAME" "$REPO_ROOT/services/api/" "$REPO_ROOT/services/worker/" 2>/dev/null | head -5)
+    if [ -n "$IMPORTERS" ]; then
+        echo "OK: Shared module '$MODULE_NAME' ($f) — imported by services"
+    else
+        echo "WARNING: Shared module '$MODULE_NAME' ($f) — no imports found in services/api/ or services/worker/"
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done || true
+
+# --- Component import check ---
+echo "$FILES" | grep -E "^web/src/components/.*\.tsx$" | while read -r f; do
+    COMPONENT_NAME=$(basename "$f" .tsx)
+
+    IMPORTERS=$(grep -rl "$COMPONENT_NAME" "$REPO_ROOT/web/src/app/" "$REPO_ROOT/web/src/components/" 2>/dev/null | grep -v "$f" | head -3)
+    if [ -n "$IMPORTERS" ]; then
+        echo "OK: Component '$COMPONENT_NAME' ($f) — imported by other files"
+    else
+        echo "WARNING: Component '$COMPONENT_NAME' ($f) — no imports found. May be unused or new."
+        WARNINGS=$((WARNINGS + 1))
+    fi
+done || true
+
+# --- Exit code ---
+if [ "$BLOCKING" -gt 0 ]; then
+    exit 1
+elif [ "$WARNINGS" -gt 0 ]; then
+    exit 2
+fi
+exit 0