Codex/modeling relationship visual parity

README.md

@@ -252,6 +252,10 @@ pnpm test:frontend
 - 质量门禁：`pnpm --filter @text2sql/backend run lint && pnpm --filter @text2sql/backend run build && pnpm --filter @text2sql/backend run test`
 - R1 离线 Gate：`pnpm --filter @text2sql/backend exec jest test/e2e/stage1-acceptance.spec.ts --runInBand`
 - 术语 selected_context 门禁：`pnpm --filter @text2sql/backend test -- glossary-selected-context-gate.spec.ts --runInBand`
+- clarification hybrid balance gate：
+  - 观测模式：`pnpm --filter @text2sql/backend run collect:clarification-balance-gate`
+  - 强门禁模式（失败返回非 0）：`pnpm --filter @text2sql/backend run collect:clarification-balance-gate:strict`
+  - 样本定义：`apps/backend/test/fixtures/clarification-balance-cases.json`
 - modeling parity shadow gate：
   - 观测模式：`pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate`
   - 强门禁模式（失败返回非 0）：`pnpm --filter @text2sql/backend run collect:modeling-parity-shadow-gate:strict`
@@ -265,6 +269,24 @@ pnpm test:frontend
   - `GET /api/v1/settings/models`（管理员上下文）
 - CI 可参考：`.github/workflows/backend-prisma-quality.yml`
 
+## Clarification Hybrid Balanced Rollout Runbook
+
+1. 混合门控质量信号采集（观测）：
+```bash
+pnpm --filter @text2sql/backend run collect:clarification-balance-gate
+```
+2. 发布门禁（严格）：
+```bash
+pnpm --filter @text2sql/backend run collect:clarification-balance-gate:strict
+```
+3. 一键回退（rules-only）：
+  - 设置 `CLARIFICATION_HYBRID_KILL_SWITCH_RULES_ONLY=true`
+  - 重启后端
+4. 回退后验证：
+  - `node tests/smoke/nginx-dev-gateway-smoke.mjs`
+  - `pnpm --filter @text2sql/backend run collect:clarification-balance-gate:strict`
+5. 详细步骤与阈值说明：`docs/runbooks/clarification-hybrid-balanced-rollout.md`
+
 ## Modeling Parity Shadow Gate Rollout Runbook
 
 1. 采集并生成报告（观测模式）：

apps/backend/.env.example

@@ -26,6 +26,27 @@ LLM_TIMEOUT_MS=30000
 LLM_MOCK_MODE=false
 LLM_FALLBACK_PROVIDERS=siliconflow,minimax
 AGENT_PLANNING_SCAFFOLD_ENABLED=false
+
+# Clarification hybrid gate defaults:
+# - enabled by default
+# - one-click rollback via kill switch (rules-only)
+# - timeout fallback to rules-only path
+CLARIFICATION_HYBRID_ENABLED=true
+CLARIFICATION_HYBRID_KILL_SWITCH_RULES_ONLY=false
+CLARIFICATION_HYBRID_TIMEOUT_MS=1200
+
+# Clarification balance gate thresholds (collect-clarification-balance-gate.ts)
+# Strict mode returns non-zero when gate fails.
+CLARIFICATION_BALANCE_GATE_MIN_SAMPLES=4
+CLARIFICATION_BALANCE_GATE_MIN_TRIGGER_RATE=0.2
+CLARIFICATION_BALANCE_GATE_MAX_TRIGGER_RATE=0.8
+CLARIFICATION_BALANCE_GATE_MAX_FALSE_POSITIVE_RATE=0.2
+CLARIFICATION_BALANCE_GATE_MAX_FALSE_NEGATIVE_RATE=0.2
+CLARIFICATION_BALANCE_GATE_MIN_POST_CLARIFY_SEMANTIC_PASS_RATE=0.7
+CLARIFICATION_BALANCE_GATE_MAX_AVG_CLARIFICATION_ROUNDS=1.5
+CLARIFICATION_BALANCE_GATE_STRICT=false
+CLARIFICATION_BALANCE_GATE_REPORT_PATH=../../data/reports/clarification-hybrid-balance/gate-summary.json
+
 SQL_SAFETY_SOFT_WARN_MAX_LENGTH=600
 R1_GATE_WINDOW_MINUTES=60
 R1_GATE_MIN_SAMPLES=10

apps/backend/data/reports/modeling-parity-shadow/gate-summary.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-24T04:43:07.359Z",
+  "generatedAt": "2026-04-25T06:47:56.724Z",
   "inputs": {
     "relationshipPlatform": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/relationship-platform-shadow/samples.json",
     "semanticSpine": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/samples.json",
@@ -10,7 +10,7 @@
     "semanticSpine": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/gate-summary.json",
     "modelingWorkspace": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/modeling-parity-shadow/gate-summary.json"
   },
-  "strictMode": false,
+  "strictMode": true,
   "gatePass": false,
   "reasons": [
     "relationship_platform:sample_not_ready",

apps/backend/data/reports/relationship-platform-shadow/gate-summary.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-24T04:43:07.331Z",
+  "generatedAt": "2026-04-25T06:47:56.690Z",
   "inputPath": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/relationship-platform-shadow/samples.json",
   "thresholds": {
     "minSamples": 30,

apps/backend/data/reports/semantic-spine-shadow/gate-summary.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-24T04:43:07.354Z",
+  "generatedAt": "2026-04-25T06:47:56.719Z",
   "inputPath": "/Users/lienli/Documents/GitHub/text2sql/apps/backend/data/reports/semantic-spine-shadow/samples.json",
   "thresholds": {
     "minSamples": 30,

apps/backend/package.json

@@ -18,6 +18,8 @@
     "prisma:migrate": "node scripts/prisma-with-database-url.cjs migrate dev",
     "prisma:studio": "node scripts/prisma-with-database-url.cjs studio",
     "prisma:verify-empty-db": "node scripts/prisma-verify-empty-db.cjs",
+    "collect:clarification-balance-gate": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-clarification-balance-gate.ts",
+    "collect:clarification-balance-gate:strict": "TS_NODE_TRANSPILE_ONLY=1 ts-node --project tsconfig.json scripts/collect-clarification-balance-gate.ts --strict",
     "collect:modeling-parity-shadow-gate": "node scripts/collect-modeling-parity-shadow-gate.mjs",
     "collect:modeling-parity-shadow-gate:strict": "node scripts/collect-modeling-parity-shadow-gate.mjs --fail-on-gate"
   },