feat(ops): Docker + CI/CD + tool-schema gate (Phase 5)

- Multi-stage Dockerfile (app/worker), mongodb-mcp/Dockerfile (HTTP, destructive
  tools disabled), docker-compose.yml (app + worker + postgres + redis + mongodb-mcp
  on a private network; Atlas external), .dockerignore.
- .github/workflows/ci.yml enforces isolation: PR/push -> lint + tool-schema gate +
  mocked tests (never deploys); main -> staging; release/dispatch -> prod behind a
  GitHub Environment approval.
- Tool-schema compatibility gate: tool_schema_gate.py derives a contract from
  ALL_TOOLS and diffs vs tool_schema.json baseline; scripts/check_tool_schema.py CLI
  fails CI on breaking changes (removed/renamed param, new required param, removed
  tool). +8 tests. Suite 154/154.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: HR-coding

.dockerignore

@@ -0,0 +1,16 @@
+.git
+.github
+**/__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+venv
+.venv
+.env
+env.txt
+credentials.json
+client_secret.json
+token.json
+docs
+*.md
+mongodb-mcp

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI/CD
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # (1) PRs + any push: lint + tool-schema gate + fully-mocked tests. NEVER deploys.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -r requirements.txt
+      - run: pip install ruff pytest
+      - name: Lint
+        run: ruff check app
+      - name: Tool-schema compatibility gate (blocks breaking tool-contract changes)
+        run: python scripts/check_tool_schema.py
+      - name: Tests (all MongoDB + Google calls mocked)
+        run: pytest app/tests -q
+
+  # (2) Merge to main -> auto-deploy to Staging.
+  deploy-staging:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build & deploy to staging
+        run: |
+          echo "Build images, push to registry, deploy to Cloud Run (staging),"
+          echo "and update the Vertex AI Agent Engine staging agent."
+          # gcloud auth + builds submit + run deploy + python -m app.orchestrator.agent_engine
+
+  # (3) GitHub Release OR manual dispatch -> Production, behind manual approval.
+  deploy-production:
+    needs: test
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment: production   # configure a required-reviewers protection rule on this env
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build & deploy to production
+        run: |
+          echo "Deploy to Cloud Run (prod) + Vertex AI Agent Engine (prod)."
+          # gcloud builds submit + run deploy + agent_engine deploy

Dockerfile

@@ -0,0 +1,16 @@
+# syntax=docker/dockerfile:1
+# Multi-stage build for the TaxAssist app (API + worker share this image).
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+FROM python:3.12-slim
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+COPY --from=builder /install /usr/local
+COPY app ./app
+EXPOSE 8080
+# API server. The worker runs the same image with:
+#   command: rq worker -u $REDIS_URL tax-agent
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

app/orchestrator/tool_schema.json

@@ -0,0 +1,217 @@
+{
+  "apply_extraction_tool": {
+    "params": {
+      "extraction_result": {
+        "annotation": "<class 'dict'>",
+        "required": true
+      },
+      "user_id": {
+        "annotation": "<class 'str'>",
+        "required": true
+      }
+    }
+  },
+  "ask_user_via_email_tool": {
+    "params": {
+      "question": {
+        "annotation": "<class 'str'>",
+        "required": true
+      },
+      "subject": {
+        "annotation": "<class 'str'>",
+        "required": false
+      },
+      "timeout_seconds": {
+        "annotation": "<class 'int'>",
+        "required": false
+      }
+    }
+  },
+  "calculate_itr1_tax_tool": {
+    "params": {
+      "advance_tax": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "deduction_80c": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "deduction_80ccd1b": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "deduction_80d": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "dividend_income": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "fd_interest": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "gross_salary": {
+        "annotation": "<class 'float'>",
+        "required": true
+      },
+      "savings_interest": {
+        "annotation": "<class 'float'>",
+        "required": false
+      },
+      "tax_regime": {
+        "annotation": "<class 'str'>",
+        "required": false
+      },
+      "tds_salary": {
+        "annotation": "<class 'float'>",
+        "required": false
+      }
+    }
+  },
+  "calculate_itr2_tax_tool": {
+    "params": {
+      "itr2_data": {
+        "annotation": "<class 'dict'>",
+        "required": true
+      }
+    }
+  },
+  "check_state_tool": {
+    "params": {
+      "user_id": {
+        "annotation": "<class 'str'>",
+        "required": true
+      }
+    }
+  },
+  "create_tax_reminder_tool": {
+    "params": {}
+  },
+  "export_findings_to_sheet_tool": {
+    "params": {
+      "extraction_result": {
+        "annotation": "<class 'dict'>",
+        "required": true
+      },
+      "tax_summary": {
+        "annotation": "<class 'dict'>",
+        "required": false
+      }
+    }
+  },
+  "get_document_tool": {
+    "params": {
+      "file_name": {
+        "annotation": "<class 'str'>",
+        "required": true
+      }
+    }
+  },
+  "process_document_tool": {
+    "params": {
+      "document_data": {
+        "annotation": "<class 'dict'>",
+        "required": true
+      },
+      "source_doc_id": {
+        "annotation": "<class 'str'>",
+        "required": false
+      }
+    }
+  },
+  "read_unvouched_transactions_tool": {
+    "params": {
+      "spreadsheet_id": {
+        "annotation": "<class 'str'>",
+        "required": false
+      }
+    }
+  },
+  "retrieve_tax_rules_tool": {
+    "params": {
+      "itr_type": {
+        "annotation": "<class 'str'>",
+        "required": false
+      },
+      "regime": {
+        "annotation": "<class 'str'>",
+        "required": false
+      }
+    }
+  },
+  "send_clarification_email_tool": {
+    "params": {
+      "body": {
+        "annotation": "<class 'str'>",
+        "required": true
+      },
+      "subject": {
+        "annotation": "<class 'str'>",
+        "required": true
+      },
+      "to_email": {
+        "annotation": "<class 'str'>",
+        "required": true
+      }
+    }
+  },
+  "update_verified_transaction_tool": {
+    "params": {
+      "row_index": {
+        "annotation": "<class 'int'>",
+        "required": true
+      },
+      "spreadsheet_id": {
+        "annotation": "<class 'str'>",
+        "required": false
+      },
+      "verified_amount": {
+        "annotation": "<class 'float'>",
+        "required": true
+      }
+    }
+  },
+  "write_state_tool": {
+    "params": {
+      "updates": {
+        "annotation": "<class 'dict'>",
+        "required": true
+      },
+      "user_id": {
+        "annotation": "<class 'str'>",
+        "required": true
+      }
+    }
+  },
+  "write_unvouched_transaction_tool": {
+    "params": {
+      "amount": {
+        "annotation": "<class 'float'>",
+        "required": true
+      },
+      "date": {
+        "annotation": "<class 'str'>",
+        "required": true
+      },
+      "description": {
+        "annotation": "<class 'str'>",
+        "required": true
+      },
+      "source": {
+        "annotation": "<class 'str'>",
+        "required": false
+      },
+      "spreadsheet_id": {
+        "annotation": "<class 'str'>",
+        "required": false
+      },
+      "transaction_type": {
+        "annotation": "<class 'str'>",
+        "required": true
+      }
+    }
+  }
+}

app/orchestrator/tool_schema_gate.py

@@ -0,0 +1,66 @@
+"""
+Tool-schema compatibility gate (CI).
+
+The agent's tool signatures are a contract: renaming/removing a parameter, or
+adding a required one, silently breaks the agent. This derives a JSON schema from
+ALL_TOOLS and diffs it against a committed baseline; the CI job fails on any
+*breaking* change (additive changes — new tools, new optional params — are fine).
+
+CLI lives in scripts/check_tool_schema.py.
+"""
+import os
+import json
+import inspect
+
+BASELINE_PATH = os.path.join(os.path.dirname(__file__), "tool_schema.json")
+
+
+def current_schema() -> dict:
+    """Derive {tool: {params: {name: {required, annotation}}}} from ALL_TOOLS."""
+    from app.orchestrator.tools import ALL_TOOLS
+    schema = {}
+    for fn in ALL_TOOLS:
+        params = {}
+        for name, p in inspect.signature(fn).parameters.items():
+            params[name] = {
+                "required": p.default is inspect.Parameter.empty,
+                "annotation": (str(p.annotation)
+                               if p.annotation is not inspect.Parameter.empty else "Any"),
+            }
+        schema[fn.__name__] = {"params": params}
+    return schema
+
+
+def diff(baseline: dict, current: dict) -> list:
+    """Return a list of BREAKING changes (empty == compatible)."""
+    breaking = []
+    for tool, b in baseline.items():
+        if tool not in current:
+            breaking.append(f"removed tool: {tool}")
+            continue
+        c = current[tool]
+        for pname, pb in b["params"].items():
+            if pname not in c["params"]:
+                breaking.append(f"{tool}: removed/renamed param '{pname}'")
+                continue
+            pc = c["params"][pname]
+            if pc["required"] and not pb["required"]:
+                breaking.append(f"{tool}: param '{pname}' became required")
+            if pc.get("annotation") != pb.get("annotation"):
+                breaking.append(
+                    f"{tool}: param '{pname}' type changed "
+                    f"{pb.get('annotation')} -> {pc.get('annotation')}")
+        for pname, pc in c["params"].items():
+            if pname not in b["params"] and pc["required"]:
+                breaking.append(f"{tool}: new REQUIRED param '{pname}'")
+    return breaking
+
+
+def load_baseline() -> dict:
+    with open(BASELINE_PATH, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save_baseline(schema: dict = None):
+    with open(BASELINE_PATH, "w", encoding="utf-8") as f:
+        json.dump(schema or current_schema(), f, indent=2, sort_keys=True)