feat(email-writing): add hardened contextual-orchestrator boundary

.github/workflows/email-writing-orchestrator-hardening-tdd.yml

@@ -0,0 +1,39 @@
+name: Email Writing Orchestrator Hardening TDD
+
+on:
+  push:
+    branches:
+      - feat/llm-email-writing-orchestrator-task5
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: email-writing-orchestrator-hardening-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  PYTHONWARNINGS: error
+  DISABLE_BACKGROUND_WORKERS: "1"
+
+jobs:
+  regressions:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: backend/requirements-hashes.txt
+      - run: python -m pip install --disable-pip-version-check --require-hashes -r backend/requirements-hashes.txt
+      - name: Run hardening regressions
+        run: |
+          cd backend
+          python -m pytest -q tests/test_contextual_orchestrator_hardening.py

.github/workflows/email-writing-orchestrator-tdd.yml

@@ -0,0 +1,145 @@
+name: Email Writing Orchestrator TDD
+
+on:
+  push:
+    branches:
+      - feat/llm-email-writing-orchestrator-task5
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: email-writing-orchestrator-tdd-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  PYTHONWARNINGS: error
+  DISABLE_BACKGROUND_WORKERS: "1"
+
+jobs:
+  task5-contracts:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: backend/requirements-hashes.txt
+      - name: Install hash-locked application dependencies
+        run: python -m pip install --disable-pip-version-check --require-hashes -r backend/requirements-hashes.txt
+      - name: Install hash-verified coverage tool
+        run: |
+          set -euo pipefail
+          mkdir -p /tmp/coverage-wheel
+          cat >/tmp/coverage-lock.txt <<'EOF'
+          coverage==7.15.2 --hash=sha256:eb6bcae8d1a9d305351ecb108232441d11c5cfe9de840a04388ba5d2db8d735c
+          EOF
+          python -m pip download \
+            --disable-pip-version-check \
+            --require-hashes \
+            --no-deps \
+            --only-binary=:all: \
+            --platform any \
+            --python-version 3.14 \
+            --implementation py \
+            --abi none \
+            --dest /tmp/coverage-wheel \
+            -r /tmp/coverage-lock.txt
+          python -m pip install --disable-pip-version-check --no-deps \
+            /tmp/coverage-wheel/coverage-7.15.2-py3-none-any.whl
+      - name: Run Task 5 contracts and hardening regressions
+        run: |
+          cd backend
+          python -m pytest -q \
+            tests/test_contextual_orchestrator_client.py \
+            tests/test_contextual_orchestrator_hardening.py \
+            tests/test_email_writing_orchestrator_module_boundary.py \
+            tests/test_email_writing_orchestrator_scope.py \
+            tests/test_email_writing_orchestrator_migration.py \
+            tests/test_email_writing_orchestrator_config_api.py \
+            tests/test_email_writing_orchestrator_terminal_coverage.py
+      - name: Verify Task 5 statement and branch coverage
+        run: |
+          cd backend
+          python -m coverage erase
+          python -m coverage run --branch \
+            --include='api/email_writing_orchestrator_config.py,db/email_writing_orchestrator_config.py,services/contextual_orchestrator_client.py,services/email_writing_orchestrator_port.py,services/tenant_config_scope.py,alembic/versions/20260813_0001_add_email_writing_orchestrator_config.py' \
+            -m pytest -q \
+            tests/test_contextual_orchestrator_client.py \
+            tests/test_contextual_orchestrator_hardening.py \
+            tests/test_email_writing_orchestrator_module_boundary.py \
+            tests/test_email_writing_orchestrator_scope.py \
+            tests/test_email_writing_orchestrator_migration.py \
+            tests/test_email_writing_orchestrator_config_api.py \
+            tests/test_email_writing_orchestrator_terminal_coverage.py
+          python -m coverage report --show-missing --fail-under=100 \
+            api/email_writing_orchestrator_config.py \
+            db/email_writing_orchestrator_config.py \
+            services/contextual_orchestrator_client.py \
+            services/email_writing_orchestrator_port.py \
+            services/tenant_config_scope.py \
+            alembic/versions/20260813_0001_add_email_writing_orchestrator_config.py
+      - name: Verify shipped Python docstrings
+        run: |
+          cd backend
+          python - <<'PY'
+          import ast
+          from pathlib import Path
+
+          paths = [
+              Path("api/email_writing_orchestrator_config.py"),
+              Path("db/email_writing_orchestrator_config.py"),
+              Path("services/contextual_orchestrator_client.py"),
+              Path("services/email_writing_orchestrator_port.py"),
+              Path("services/tenant_config_scope.py"),
+              Path(
+                  "alembic/versions/"
+                  "20260813_0001_add_email_writing_orchestrator_config.py"
+              ),
+          ]
+          missing: list[str] = []
+          for path in paths:
+              tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+              if ast.get_docstring(tree) is None:
+                  missing.append(f"{path}:<module>")
+              for node in ast.walk(tree):
+                  if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+                      if ast.get_docstring(node) is None:
+                          missing.append(f"{path}:{node.lineno}:{node.name}")
+          if missing:
+              raise SystemExit("Missing shipped docstrings:\n" + "\n".join(missing))
+          print(f"Docstring gate passed for {len(paths)} shipped modules")
+          PY
+      - name: Lint Task 5 source and tests
+        run: |
+          cd backend
+          python -m ruff check \
+            api/email_writing_orchestrator_config.py \
+            db/email_writing_orchestrator_config.py \
+            services/contextual_orchestrator_client.py \
+            services/email_writing_orchestrator_port.py \
+            services/tenant_config_scope.py \
+            alembic/versions/20260813_0001_add_email_writing_orchestrator_config.py \
+            tests/test_contextual_orchestrator_client.py \
+            tests/test_contextual_orchestrator_hardening.py \
+            tests/test_email_writing_orchestrator_module_boundary.py \
+            tests/test_email_writing_orchestrator_scope.py \
+            tests/test_email_writing_orchestrator_migration.py \
+            tests/test_email_writing_orchestrator_config_api.py \
+            tests/test_email_writing_orchestrator_terminal_coverage.py
+      - name: Compile Task 5 source
+        run: |
+          python -m compileall -q \
+            backend/api/email_writing_orchestrator_config.py \
+            backend/db/email_writing_orchestrator_config.py \
+            backend/services/contextual_orchestrator_client.py \
+            backend/services/email_writing_orchestrator_port.py \
+            backend/services/tenant_config_scope.py \
+            backend/alembic/versions/20260813_0001_add_email_writing_orchestrator_config.py

backend/alembic/env.py

@@ -8,13 +8,14 @@
 
 from core.config import settings
 from db.email_writing_evidence import EmailReviewSession
+from db.email_writing_orchestrator_config import EmailWritingOrchestratorConfig
 
 config = context.config
 
 if config.config_file_name is not None:
     fileConfig(config.config_file_name)
 
-target_metadata = EmailReviewSession.__table__.metadata
+target_metadata = EmailWritingOrchestratorConfig.__table__.metadata
 
 
 def _database_url() -> str:

backend/alembic/versions/20260813_0001_add_email_writing_orchestrator_config.py

@@ -0,0 +1,22 @@
+"""Add the owner-scoped email-writing orchestration table."""
+
+from __future__ import annotations
+
+from alembic import op
+
+from db.email_writing_orchestrator_config import EmailWritingOrchestratorConfig
+
+revision = "20260813_email_orchestrator"
+down_revision = "20260812_email_writing_evidence"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create the configuration table and its indexes."""
+    EmailWritingOrchestratorConfig.__table__.create(op.get_bind(), checkfirst=True)
+
+
+def downgrade() -> None:
+    """Drop only the configuration table introduced by this revision."""
+    EmailWritingOrchestratorConfig.__table__.drop(op.get_bind(), checkfirst=True)