Stage closure 2026-08-18: suite green, INDEX-DIM active, CI matrix fixed

.env.example

@@ -1,30 +1,49 @@
-# GraceKelly is the default local orchestrator. Start D:\GraceKelly on this URL first.
+# Optional GraceKelly orchestrator. Used only by explicit GraceKelly profiles.
 GRACEKELLY_BASE_URL=http://127.0.0.1:8011
 GRACEKELLY_API_KEY=
 GRACEKELLY_API_KEY_ENV=GRACEKELLY_API_KEY
 GRACEKELLY_HEALTH_CHECK_TIMEOUT_SEC=2.0
 GRACEKELLY_REQUEST_TIMEOUT_SEC=30.0
 FAILOVER_CHAIN_ENABLED=true
 FAILOVER_FALLBACK_CACHE_SECONDS=300
-# Provider registry and routing profile. `gracekelly-primary` is the default path.
-# Use `local-first` only for explicit local-only Ollama mode.
+# Provider registry and routing profile. `local-first` is the default Ollama path.
+# Use `external-mistral` or a GraceKelly profile only as an explicit opt-in.
 PROVIDER_REGISTRY_PATH=config/providers.yml
-LLM_PROVIDER_PROFILE=gracekelly-primary
-# Optional Ollama settings for explicit `local-first` mode or GraceKelly fallback.
+LLM_PROVIDER_PROFILE=local-first
+# Ollama settings for the default `local-first` mode or GraceKelly fallback.
 # In Docker Compose use http://ollama:11434
 OLLAMA_BASE_URL=http://localhost:11434
 OLLAMA_MODEL_NAME=qwen2.5:7b
 # Benchmarks stay mock-only unless you explicitly allow paid provider calls.
 LLM_BENCHMARK_ALLOW_PAID_APIS=false
 # Fail fast when paid-provider spend for the current UTC day reaches this limit.
 DAILY_COST_LIMIT_USD=5.0
-# Paid-provider credentials. Placeholder values such as `changeme` are treated as missing.
+# External-provider credentials. Placeholder values such as `changeme` are treated as missing.
 MISTRAL_API_KEY=changeme
+# OpenCode Zen free models are temporary trials; never send personal or confidential data.
+OPENCODE_ZEN_API_KEY=changeme
 # Model routing: fast model for simple questions, strong model for complex ones
 MODEL_ROUTING_ENABLED=false
 OLLAMA_FAST_MODEL_NAME=llama3.2:3b
 # Ingestion auto-categorizer model. Override when the default is not pulled locally.
 INGESTION_CATEGORIZER_MODEL=llama3.2:3b
+# Durable async ingestion job lease / heartbeat / reaper (plan step 4.3).
+# Heartbeat must be positive and strictly shorter than the lease.
+INGESTION_JOB_LEASE_SEC=120
+INGESTION_JOB_HEARTBEAT_INTERVAL_SEC=30
+# Queued async jobs older than this become terminal failures (seconds).
+INGESTION_JOB_QUEUED_STALE_SEC=900
+# Pre-lease async running rows (no lease_token) reaped after this age (seconds).
+INGESTION_JOB_LEGACY_RUNNING_STALE_SEC=1800
+# FastAPI-process reaper interval; runs independently of the Celery worker.
+INGESTION_JOB_REAPER_INTERVAL_SEC=60
+# Bounded broker publish-only retry for async /api/upload (plan step 4.4 core).
+# Does not enable Celery worker/task autoretry after load/index begins.
+INGESTION_PUBLISH_MAX_RETRIES=2
+INGESTION_PUBLISH_RETRY_DELAY_SEC=0.2
+# Maximum wait for the per-tenant PostgreSQL advisory index lock (seconds).
+# A timeout or unavailable lock database fails the rebuild closed.
+INGESTION_TENANT_LOCK_WAIT_SEC=30
 # Default token pricing used when a model is not listed in LLM_MODEL_PRICES.
 LLM_INPUT_PRICE_PER_1M_TOKENS=0.0
 LLM_OUTPUT_PRICE_PER_1M_TOKENS=0.0
@@ -42,8 +61,11 @@ RAG_EMBEDDING_REMOTE_MODEL=mistral-embed
 RAG_EMBEDDING_REMOTE_API_KEY_ENV=MISTRAL_API_KEY
 RAG_EMBEDDING_REMOTE_BATCH=32
 RAG_EMBEDDING_REMOTE_TIMEOUT_SEC=60
+# Declared remote embedding vector dimension (must match the remote model; mistral-embed=1024)
+RAG_EMBEDDING_REMOTE_DIMENSION=1024
 # Cross-encoder reranker model used to reorder retrieved documents
 # (multilingual, pairs with BGE-M3; ms-marco is English-only and degrades RU retrieval)
+# Leave empty on memory-constrained hosts to disable the reranker.
 RAG_RERANKER_MODEL=BAAI/bge-reranker-v2-m3
 # Inference device for embedder + reranker: auto (cuda->mps->cpu) | cpu | cuda | cuda:0 | mps
 RAG_DEVICE=auto
@@ -119,8 +141,14 @@ REGRESSION_GATE_MAX_REGRESSIONS=2
 REGRESSION_GATE_MIN_PASS_RATE=0.85
 # Vector database backend to use for document storage
 RAG_VECTOR_BACKEND=chroma
+# Optional Chroma persistence directory. Blank keeps <repo>/data/vectordb/chroma.
+# Use a new empty directory when changing embedding model or vector dimension.
+VECTORDB_CHROMA_DIR=
 # Chroma collection prefix; full name = {prefix}_{tenant_id}
 VECTORDB_COLLECTION_PREFIX=rag_docs
+# Validated per-tenant version budget (active + previous at minimum).
+# Runtime retention execution is not wired yet; this must be an integer >= 2.
+VECTORDB_RETENTION_MAX_VERSIONS=2
 # Backend used to store escalations for human support
 SUPPORT_SINK_BACKEND=local
 # Bitrix24 webhook URL for sending escalations when Bitrix backend is enabled
@@ -131,9 +159,9 @@ TELEGRAM_BOT_TOKEN=
 LANGFUSE_PUBLIC_KEY=
 LANGFUSE_SECRET_KEY=
 LANGFUSE_HOST=https://cloud.langfuse.com
-# Fail fast on startup if Ollama is unavailable. Set true only for explicit local-first mode.
+# Fail fast on startup if the default local Ollama provider is unavailable.
 REQUIRE_OLLAMA=false
-# Circuit breaker for Ollama - fast-fail when explicit local/fallback Ollama is unhealthy
+# Circuit breaker for Ollama - fast-fail when local/fallback Ollama is unhealthy
 CIRCUIT_BREAKER_ENABLED=true
 CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
 CIRCUIT_BREAKER_RESET_TIMEOUT_SEC=30

.github/workflows/ci.yml

@@ -312,10 +312,16 @@ jobs:
           list-files: shell
           filters: |
             regression:
-              - 'agent/prompts.py'
+              - 'agent/**'
+              - 'api/routers/conversation.py'
+              - 'cache/**'
               - 'config/settings.py'
-              - 'evaluation/curated_cases.jsonl'
-              - 'evaluation/experiments/*.yaml'
+              - 'config/providers.yml'
+              - 'evaluation/**'
+              - 'ingestion/**'
+              - 'llm/**'
+              - 'scripts/regression_eval.py'
+              - 'vectordb/**'
 
       - name: Skip when regression inputs did not change
         if: steps.regression_changes.outputs.regression != 'true'
@@ -353,7 +359,12 @@ jobs:
         if: steps.regression_changes.outputs.regression == 'true' && !hashFiles('evaluation/curated_cases.jsonl')
         run: echo "evaluation/curated_cases.jsonl is missing; skipping informational regression run."
 
-      - name: Run regression eval
+      # Smoke-only: mock expected-copy is NOT release evidence (plan §7.2).
+      # Exit follows metrics smoke; do not pass --release-gate here.
+      # Release evidence requires real pipeline/provider runs without mock.
+      # Plan §7.5: publish a durable baseline artifact from this smoke run so the
+      # merge-base compare path is wired in CI (write → upload → require load).
+      - name: Run regression eval (smoke, write baseline artifact)
         if: steps.regression_changes.outputs.regression == 'true' && hashFiles('evaluation/curated_cases.jsonl')
         run: >
           python scripts/regression_eval.py
@@ -365,3 +376,30 @@ jobs:
           --seed 42
           --mock-experiment-runtime
           --no-persist
+          --write-baseline-artifact reports/regression/ci-baseline-artifact.json
+
+      - name: Upload regression baseline artifact
+        if: steps.regression_changes.outputs.regression == 'true' && hashFiles('evaluation/curated_cases.jsonl')
+        uses: actions/upload-artifact@v4
+        with:
+          name: regression-baseline-artifact
+          path: reports/regression/ci-baseline-artifact.json
+          if-no-files-found: error
+
+      # Plan §7.5: re-compare candidate against the written artifact with
+      # --require-baseline-artifact (fail-closed if missing/unusable).
+      # Still mock → still smoke; does not claim release PASS (plan §7.2).
+      - name: Regression compare against baseline artifact (require wire)
+        if: steps.regression_changes.outputs.regression == 'true' && hashFiles('evaluation/curated_cases.jsonl')
+        run: >
+          python scripts/regression_eval.py
+          --baseline merge-base
+          --candidate ${{ steps.regression_target.outputs.candidate }}
+          --dataset evaluation/curated_cases.jsonl
+          --tenant all
+          --max-cases 100
+          --seed 42
+          --mock-experiment-runtime
+          --no-persist
+          --baseline-artifact reports/regression/ci-baseline-artifact.json
+          --require-baseline-artifact

.github/workflows/docs-site.yml

@@ -47,17 +47,12 @@ jobs:
 
       - name: Audit npm dependencies
         working-directory: docs-site
-        # The deployed artifact is fully static (HTML/CSS/JS/woff2/SVG) — no npm
-        # package executes at runtime. The current moderate/high advisories
-        # (esbuild dev-server & Deno installer; dompurify/js-yaml, used only while
-        # building mermaid diagrams and parsing config) have no runtime exposure
-        # and no non-breaking fix in the Astro 6 dependency tree (`npm audit fix`
-        # is a no-op; `--force` would downgrade Astro and break the build).
-        # Report everything for visibility, but only fail the deploy on a critical
-        # supply-chain advisory. Revisit when Astro/vite ship patched esbuild.
+        # Plan DEP-01 (2026-08-07): fail-closed on high/critical after lock refresh.
+        # Residual moderate/low require dated reachability exceptions in
+        # docs-site/npm-audit-exceptions.json (no blanket `|| true`).
         run: |
-          npm audit --audit-level=moderate || true
-          npm audit --audit-level=critical
+          npm audit --audit-level=high
+          npm run audit:deps
 
       - name: Type-check docs site
         working-directory: docs-site

.github/workflows/live-provider-gate.yml

@@ -0,0 +1,96 @@
+# Plan §7.6: scheduled live provider / independent-judge gate scaffold.
+#
+# Separated from PR/master smoke in ci.yml (mock allowed there; never release
+# evidence). This workflow defaults to readiness-only — no live provider calls
+# and no release PASS claim — unless workflow_dispatch enable_live=true AND
+# repository secrets / RAG_LIVE_PROVIDER_GATE opt-in are present.
+name: Live Provider Gate
+
+on:
+  schedule:
+    # Weekly Monday 06:00 UTC — readiness probe by default.
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+    inputs:
+      enable_live:
+        description: "Opt-in live providers (requires secrets; never default)"
+        required: false
+        default: false
+        type: boolean
+      max_cases:
+        description: "Max curated cases for a live attempt"
+        required: false
+        default: "20"
+        type: string
+      execute:
+        description: "When live ready, actually run regression_eval (default false)"
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  live-provider-gate:
+    name: live-provider-gate
+    runs-on: ubuntu-latest
+    env:
+      PYTHONPATH: ${{ github.workspace }}
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: |
+            requirements-dev.lock
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --require-hashes -r requirements-dev.lock
+
+      # Always: readiness scaffold (no live calls, not release evidence).
+      - name: Live gate readiness (scaffold, no live calls)
+        run: >
+          python scripts/live_provider_gate.py
+          --mode readiness
+          --max-cases ${{ github.event.inputs.max_cases || '20' }}
+          --write-report reports/regression/live-provider-gate-readiness.json
+
+      # Opt-in live path: workflow_dispatch + enable_live only.
+      # Secrets mapped only when present; missing keys → fail-closed (exit 1).
+      # --execute stays false unless explicitly requested so schedule never
+      # burns paid API quota by default.
+      - name: Live gate opt-in attempt
+        if: github.event_name == 'workflow_dispatch' && inputs.enable_live == true
+        env:
+          RAG_LIVE_PROVIDER_GATE: "1"
+          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
+          GRACEKELLY_API_KEY: ${{ secrets.GRACEKELLY_API_KEY }}
+          OPENCODE_ZEN_API_KEY: ${{ secrets.OPENCODE_ZEN_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          EXTRA=""
+          if [ "${{ inputs.execute }}" = "true" ]; then
+            EXTRA="--execute"
+          fi
+          python scripts/live_provider_gate.py \
+            --mode live \
+            --live \
+            --max-cases ${{ inputs.max_cases || '20' }} \
+            --write-report reports/regression/live-provider-gate-result.json \
+            $EXTRA
+
+      - name: Upload live gate reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: live-provider-gate-reports
+          path: |
+            reports/regression/live-provider-gate-readiness.json
+            reports/regression/live-provider-gate-result.json
+          if-no-files-found: warn

.github/workflows/live-quality-metrics-gate.yml

@@ -0,0 +1,99 @@
+# Plan §5.5: scheduled live quality metrics gate scaffold (×3 DoD).
+#
+# Separated from PR/master smoke in ci.yml. Defaults to readiness-only —
+# no live provider calls and no release PASS claim — unless workflow_dispatch
+# enable_live=true AND repository secrets / RAG_LIVE_QUALITY_METRICS_GATE.
+name: Live Quality Metrics Gate
+
+on:
+  schedule:
+    # Weekly Monday 07:00 UTC — readiness probe by default (after provider gate).
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+    inputs:
+      enable_live:
+        description: "Opt-in live multi-run metrics (requires secrets; never default)"
+        required: false
+        default: false
+        type: boolean
+      max_cases:
+        description: "Max curated cases per run"
+        required: false
+        default: "20"
+        type: string
+      runs:
+        description: "Repeated runs (plan min 3)"
+        required: false
+        default: "3"
+        type: string
+      execute:
+        description: "When live ready, actually run multi-seed regression_eval"
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  live-quality-metrics-gate:
+    name: live-quality-metrics-gate
+    runs-on: ubuntu-latest
+    env:
+      PYTHONPATH: ${{ github.workspace }}
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: |
+            requirements-dev.lock
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --require-hashes -r requirements-dev.lock
+
+      # Always: readiness scaffold (no live calls, not release evidence).
+      - name: Quality metrics gate readiness (scaffold, no live calls)
+        run: >
+          python scripts/live_quality_metrics_gate.py
+          --mode readiness
+          --runs ${{ github.event.inputs.runs || '3' }}
+          --max-cases ${{ github.event.inputs.max_cases || '20' }}
+          --write-report reports/regression/live-quality-metrics-gate-readiness.json
+
+      # Opt-in live path: workflow_dispatch + enable_live only.
+      - name: Quality metrics gate opt-in attempt
+        if: github.event_name == 'workflow_dispatch' && inputs.enable_live == true
+        env:
+          RAG_LIVE_QUALITY_METRICS_GATE: "1"
+          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
+          GRACEKELLY_API_KEY: ${{ secrets.GRACEKELLY_API_KEY }}
+          OPENCODE_ZEN_API_KEY: ${{ secrets.OPENCODE_ZEN_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          EXTRA=""
+          if [ "${{ inputs.execute }}" = "true" ]; then
+            EXTRA="--execute"
+          fi
+          python scripts/live_quality_metrics_gate.py \
+            --mode live \
+            --live \
+            --runs ${{ inputs.runs || '3' }} \
+            --max-cases ${{ inputs.max_cases || '20' }} \
+            --write-report reports/regression/live-quality-metrics-gate-result.json \
+            $EXTRA
+
+      - name: Upload quality metrics gate reports
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: live-quality-metrics-gate-reports
+          path: |
+            reports/regression/live-quality-metrics-gate-readiness.json
+            reports/regression/live-quality-metrics-gate-result.json
+          if-no-files-found: warn

.gitignore

@@ -48,3 +48,6 @@ reports/ragas/*.md
 
 # Ad-hoc QA screenshots at repo root (per-session captures, not committed assets)
 /*.png
+
+# pytest basetemp trees (local test-run artifacts, never evidence)
+.pytest_tmp*/