Add semantic fallback gap audit and budget gate (sprints 236-237)

docs/constructive_editing_runtime_plan.md

@@ -150,8 +150,13 @@ Parallel planning tranche (active):
   - `logs/taskitem_runs/TEST_ONLY_spec_planning_baseline_20260226/deterministic_spec_readiness.json`
 
 Planning runtime controls (active):
-- `sprint232_plan.md` to `sprint235_plan.md`
+- `sprint232_plan.md` to `sprint237_plan.md`
 - semantic bridge + intake augmentation + requirement injection + expansion gating are wired into:
   - `tools/mcp/run_sprint_taskitem_pipeline.sh`
 - current policy default is native-first semantic fallback:
   - `WSTONE_SEMANTIC_TASK_EXPANSION_MODE=fallback_only`
+- fallback diagnostics + remediation metadata are emitted by:
+  - `tools/mcp/analyze_semantic_fallback_gaps.py`
+- fallback budget gating is available via:
+  - `tools/mcp/check_semantic_fallback_budget.py`
+  - `tools/mcp/run_semantic_fallback_budget_gate.sh`

docs/generator_readiness_gap_registry_2026-02-26.md

@@ -46,6 +46,7 @@ This is the canonical dated registry for "not production-ready" generator gaps.
 | GR-017 | Full-stack contract propagation gap | `docs/gap_hunt_fullstack_multifile_2026-02-26.md`, `logs/taskitem_runs/challenging_fullstack_multifile_20260226_r5/fullstack_contract_closure.json` | `partial` | Full-stack contract packet + strict validation added in benchmark orchestration and summary aggregation. Contract invalid rate is `0%` on valid catalog, but cross-layer semantic consistency is not yet equivalence-verified. | Semantic propagation verifier sprint |
 | GR-018 | Performance/security/rollout constrained refactor enforcement gap | `docs/gap_hunt_fullstack_multifile_2026-02-26.md`, `logs/taskitem_runs/challenging_fullstack_multifile_20260226_r5/results.jsonl` | `partial` | Hard checks now enforce migration rollback + data-loss policy, security deny-by-default, SLO p95 presence, and rollout staged+abort policy. Enforcement is contract-level; generator capability under these constraints is still weak in C++ AB path. | Constraint-aware generation follow-up |
 | GR-019 | Parity-blocked readiness load (gating without capability closure) | `logs/taskitem_runs/challenging_fullstack_multifile_20260226_r7/summary.json`, `logs/taskitem_runs/challenging_subset_prod_20260226_r7/summary.json`, `docs/sprint225_227_execution_tracker_2026-02-26.md` | `partial` | Sprint 225-227 reduced blocked parity load from `6` to `0` on both tracked hard catalogs while keeping unresolved divergence at `0`. This closes immediate safety debt for current corpora, but robustness is still contingent on pattern-driven repair classes. | Generalize repairs beyond queue-shaped transpile outputs |
+| GR-020 | Semantic fallback overuse masks weak native decomposition | `logs/taskitem_runs/TEST_ONLY_sprint236_semantic_fallback_audit_20260226/semantic_fallback_summary.json`, `logs/taskitem_runs/TEST_ONLY_sprint237_semantic_fallback_gate_fail_20260226/semantic_fallback_budget_gate.json`, `docs/sprint236_execution_tracker_2026-02-26.md`, `docs/sprint237_execution_tracker_2026-02-26.md` | `partial` | Sprint 236 added deterministic fallback-gap auditing with tool + constraint metadata. Sprint 237 added fallback-budget hard gate (`max-fallback-rate`) and produced expected fail/pass artifacts. Current measured slice remains `fallback_rate=1.0`, so gating now detects but does not yet fix root capability gaps. | Native decomposition upgrade + semantic rationale enforcement |
 
 ## What Was Covered Today (Sprints 175-184)
 

docs/progress_log_2026-02-26.md

@@ -123,3 +123,27 @@
   - `logs/taskitem_runs/TEST_ONLY_sprint235_probe_20260226_144846/00_summary.json`
   - `logs/taskitem_runs/TEST_ONLY_sprint235_probe_20260226_144854/00_summary.json`
   - `logs/taskitem_runs/TEST_ONLY_sprint235_richspec_20260226_144902/00_summary.json`
+
+## Sprint 236 Added (Same Day)
+
+- Added semantic fallback gap audit tool:
+  - `tools/mcp/analyze_semantic_fallback_gaps.py`
+- Emits per-run metadata for remediation routing:
+  - `recommended_tools`
+  - `recommended_taskitem_constraints`
+- Generated dated audit bundle:
+  - `logs/taskitem_runs/TEST_ONLY_sprint236_semantic_fallback_audit_20260226/semantic_fallback_summary.json`
+  - `logs/taskitem_runs/TEST_ONLY_sprint236_semantic_fallback_audit_20260226/semantic_fallback_tooling_recommendations.json`
+- Current measured signal on sprint 235 sample runs:
+  - `fallback_rate=1.0`
+  - dominant root cause: `native_decomposition_and_semantic_signal_deficit`
+
+## Sprint 237 Added (Same Day)
+
+- Added semantic fallback budget gate:
+  - `tools/mcp/check_semantic_fallback_budget.py`
+- Added single-command audit+gate wrapper:
+  - `tools/mcp/run_semantic_fallback_budget_gate.sh`
+- Dated pass/fail artifacts captured:
+  - fail (strict budget): `logs/taskitem_runs/TEST_ONLY_sprint237_semantic_fallback_gate_fail_20260226/semantic_fallback_budget_gate.json`
+  - pass (relaxed budget): `logs/taskitem_runs/TEST_ONLY_sprint237_semantic_fallback_gate_pass_20260226/semantic_fallback_budget_gate.json`

docs/sprint236_execution_tracker_2026-02-26.md

@@ -0,0 +1,34 @@
+# Sprint 236 Execution Tracker - 2026-02-26
+
+## Scope
+- `sprint236_plan.md`
+
+## Implemented
+
+- Added semantic fallback audit tool:
+  - `tools/mcp/analyze_semantic_fallback_gaps.py`
+- Analyzer outputs:
+  - `semantic_fallback_records.jsonl`
+  - `semantic_fallback_summary.json`
+  - `semantic_fallback_tooling_recommendations.json`
+- Added deterministic root-cause classes:
+  - `native_decomposition_too_shallow`
+  - `semantic_rationale_missing`
+  - `native_decomposition_and_semantic_signal_deficit`
+- Added per-run remediation metadata:
+  - `recommended_tools`
+  - `recommended_taskitem_constraints`
+
+## Baseline Audit Artifact
+
+- `logs/taskitem_runs/TEST_ONLY_sprint236_semantic_fallback_audit_20260226/semantic_fallback_summary.json`
+- `logs/taskitem_runs/TEST_ONLY_sprint236_semantic_fallback_audit_20260226/semantic_fallback_tooling_recommendations.json`
+
+Observed in this slice:
+- `record_count=5`
+- `fallback_rate=1.0`
+- dominant root cause: `native_decomposition_and_semantic_signal_deficit`
+
+## Explicit Completion Signal
+
+- Sprint 236: `DONE` (implemented + audit generated + dated metadata captured)

docs/sprint237_execution_tracker_2026-02-26.md

@@ -0,0 +1,26 @@
+# Sprint 237 Execution Tracker - 2026-02-26
+
+## Scope
+- `sprint237_plan.md`
+
+## Implemented
+
+- Added gate checker:
+  - `tools/mcp/check_semantic_fallback_budget.py`
+- Added wrapper for audit+gate:
+  - `tools/mcp/run_semantic_fallback_budget_gate.sh`
+- Added policy controls:
+  - `WSTONE_SEMANTIC_MAX_FALLBACK_RATE` (default `0.35`)
+  - `WSTONE_SEMANTIC_FALLBACK_MIN_RECORDS` (default `5`)
+  - `WSTONE_SEMANTIC_FALLBACK_INCLUDE_GLOB` (run selection)
+
+## Baseline Gate Artifacts
+
+- expected fail (strict budget):
+  - `logs/taskitem_runs/TEST_ONLY_sprint237_semantic_fallback_gate_fail_20260226/semantic_fallback_budget_gate.json`
+- expected pass (relaxed budget):
+  - `logs/taskitem_runs/TEST_ONLY_sprint237_semantic_fallback_gate_pass_20260226/semantic_fallback_budget_gate.json`
+
+## Explicit Completion Signal
+
+- Sprint 237: `DONE` (implemented + pass/fail gate smoke verified)