feat: hybrid AGC (FPGA phases 1-3 + GUI phase 6) with timing fix

FPGA:
- rx_gain_control.v rewritten: per-frame peak/saturation tracking,
  auto-shift AGC with attack/decay/holdoff, signed gain -7 to +7
- New registers 0x28-0x2C (agc_enable/target/attack/decay/holdoff)
- status_words[4] carries AGC metrics (gain, peak, sat_count, enable)
- DIG_5 GPIO outputs saturation flag for STM32 outer loop
- Both USB interfaces (FT601 + FT2232H) updated with AGC status ports

Timing fix (WNS +0.001ns -> +0.045ns, 45x improvement):
- CIC max_fanout 4->16 on valid pipeline registers
- +200ps setup uncertainty on 400MHz domain
- ExtraNetDelay_high placement + AggressiveExplore routing

GUI:
- AGC opcodes + status parsing in radar_protocol.py
- AGC control groups in both tkinter and V7 PyQt dashboards
- 11 new AGC tests (103/103 GUI tests pass)

Cross-layer:
- AGC opcodes/defaults/status assertions added (29/29 pass)
- contract_parser.py: fixed comment stripping in concat parser

All tests green: 25 FPGA + 103 GUI + 29 cross-layer = 157 pass

9_Firmware/tests/cross_layer/contract_parser.py

@@ -527,6 +527,8 @@ def parse_verilog_status_word_concats(
     ):
         idx = int(m.group(1))
         expr = m.group(2)
+        # Strip single-line comments before normalizing whitespace
+        expr = re.sub(r'//[^\n]*', '', expr)
         # Normalize whitespace
         expr = re.sub(r'\s+', ' ', expr).strip()
         results[idx] = expr

9_Firmware/tests/cross_layer/tb_cross_layer_ft2232h.v

@@ -86,6 +86,10 @@ module tb_cross_layer_ft2232h;
     reg  [4:0]  status_self_test_flags;
     reg  [7:0]  status_self_test_detail;
     reg         status_self_test_busy;
+    reg  [3:0]  status_agc_current_gain;
+    reg  [7:0]  status_agc_peak_magnitude;
+    reg  [7:0]  status_agc_saturation_count;
+    reg         status_agc_enable;
 
     // ---- Clock generators ----
     always #(CLK_PERIOD / 2)    clk    = ~clk;
@@ -130,7 +134,11 @@ module tb_cross_layer_ft2232h;
         .status_range_mode      (status_range_mode),
         .status_self_test_flags (status_self_test_flags),
         .status_self_test_detail(status_self_test_detail),
-        .status_self_test_busy  (status_self_test_busy)
+        .status_self_test_busy  (status_self_test_busy),
+        .status_agc_current_gain    (status_agc_current_gain),
+        .status_agc_peak_magnitude  (status_agc_peak_magnitude),
+        .status_agc_saturation_count(status_agc_saturation_count),
+        .status_agc_enable          (status_agc_enable)
     );
 
     // ---- Test bookkeeping ----
@@ -188,6 +196,10 @@ module tb_cross_layer_ft2232h;
             status_self_test_flags  = 5'b00000;
             status_self_test_detail = 8'd0;
             status_self_test_busy   = 1'b0;
+            status_agc_current_gain     = 4'd0;
+            status_agc_peak_magnitude   = 8'd0;
+            status_agc_saturation_count = 8'd0;
+            status_agc_enable           = 1'b0;
             repeat (6) @(posedge ft_clk);
             reset_n    = 1;
             ft_reset_n = 1;
@@ -605,6 +617,10 @@ module tb_cross_layer_ft2232h;
         status_self_test_flags  = 5'b10101;
         status_self_test_detail = 8'hA5;
         status_self_test_busy   = 1'b1;
+        status_agc_current_gain     = 4'd7;
+        status_agc_peak_magnitude   = 8'd200;
+        status_agc_saturation_count = 8'd15;
+        status_agc_enable           = 1'b1;
 
         // Pulse status_request and capture bytes IN PARALLEL
         // (same reason as Exercise B — write FSM starts before CDC wait ends)

9_Firmware/tests/cross_layer/test_cross_layer_contract.py

@@ -100,6 +100,11 @@ GROUND_TRUTH_OPCODES = {
     0x25: ("host_cfar_enable", 1),
     0x26: ("host_mti_enable", 1),
     0x27: ("host_dc_notch_width", 3),
+    0x28: ("host_agc_enable", 1),
+    0x29: ("host_agc_target", 8),
+    0x2A: ("host_agc_attack", 4),
+    0x2B: ("host_agc_decay", 4),
+    0x2C: ("host_agc_holdoff", 4),
     0x30: ("host_self_test_trigger", 1),  # pulse
     0x31: ("host_status_request", 1),     # pulse
     0xFF: ("host_status_request", 1),     # alias, pulse
@@ -124,6 +129,11 @@ GROUND_TRUTH_RESET_DEFAULTS = {
     "host_cfar_enable": 0,
     "host_mti_enable": 0,
     "host_dc_notch_width": 0,
+    "host_agc_enable": 0,
+    "host_agc_target": 200,
+    "host_agc_attack": 1,
+    "host_agc_decay": 1,
+    "host_agc_holdoff": 4,
 }
 
 GROUND_TRUTH_PACKET_CONSTANTS = {
@@ -604,6 +614,10 @@ class TestTier2VerilogCosim:
         #   status_self_test_flags = 5'b10101 = 21
         #   status_self_test_detail = 0xA5
         #   status_self_test_busy = 1
+        #   status_agc_current_gain = 7
+        #   status_agc_peak_magnitude = 200
+        #   status_agc_saturation_count = 15
+        #   status_agc_enable = 1
 
         # Words 1-5 should be correct (no truncation bug)
         assert sr.cfar_threshold == 0xABCD, f"cfar_threshold: 0x{sr.cfar_threshold:04X}"
@@ -618,6 +632,12 @@ class TestTier2VerilogCosim:
         assert sr.self_test_detail == 0xA5, f"self_test_detail: 0x{sr.self_test_detail:02X}"
         assert sr.self_test_busy == 1, f"self_test_busy: {sr.self_test_busy}"
 
+        # AGC fields (word 4)
+        assert sr.agc_current_gain == 7, f"agc_current_gain: {sr.agc_current_gain}"
+        assert sr.agc_peak_magnitude == 200, f"agc_peak_magnitude: {sr.agc_peak_magnitude}"
+        assert sr.agc_saturation_count == 15, f"agc_saturation_count: {sr.agc_saturation_count}"
+        assert sr.agc_enable == 1, f"agc_enable: {sr.agc_enable}"
+
         # Word 0: stream_ctrl should be 5 (3'b101)
         assert sr.stream_ctrl == 5, (
             f"stream_ctrl: {sr.stream_ctrl} != 5. "