通止规装配：配置段进 site.yaml + 中文手册 + 成败判定「不看 $?」

配置（site.yaml → gauge_assembly:，38 键全部带中文注释）
------------------------------------------------------
- 键名/单位/类型/交叉矛盾由 gauge_config.py 校验：拼错键名报错并给最相近的候选，
  单位后缀（_deg/_mm/_m/_s/_pct/_delta）逐条对表，`contact_safe_delta ≤
  contact_tangential_delta` 这类矛盾启动就拦（R1.2：没接线的键不许静默存在）。
- 借机清掉 4 个**没接线**的键（require_preview / track_*_s / hover_m：前两个是
  stage1 那层的、后两个是 servo 那层的，放在这里等于第二份真相），
  并把 contact_speed_m_s / coarse_timeout_s / 夹爪力速 真的接上。
- site.example.yaml 由 site.yaml 生成（gen_site_example.py --check 通过）。

成败判定：`ros2 launch` 的退出码**恒为 0**
------------------------------------------
实测（Humble）：子进程 exit 3，`ros2 launch` 仍返回 0。用 `$?` 判成败的脚本会把
"装配失败"记成"成功"——没人会去查一个说成功的脚本。改成：

- 节点把结论**落盘**（--result-file，默认 /tmp/gauge_assembly_result.json，原子写、
  先落盘再发话题），任何"没跑到收尾"的退出也会补一份 ok=false；
- 脚本读结论文件判成败：0=成功、1=失败、**文件不存在也算失败**并说清；
- 新增 test_gauge_result_gate.py：把脚本里那段判成败的 Python 抽出来，
  对成功/失败/干跑/缺文件/坏 JSON 五种输入断言退出码 —— 判据本身也有测试。

顺带修掉两个"看着像玄学"的现象
------------------------------
- **流程打完了终端不回提示符**：launch 里的静态 TF 发布者是常驻的，主节点退出
  带不走它 —— 挂 OnProcessExit → Shutdown。
- **"已装 1/2 孔"**：结果里 hole_index 是 0 基当前孔号，不是"装完几个"，
  新增 holes_done 给人和脚本看。

文档（全部中文，含"怎么调参/还没做"）
------------------------------------
- 新增 docs/GAUGE_ASSEMBLY.md：状态机全图、每步判据表、E1 掉件处理（**按实现**：
  掉件后该孔作废、换下一个孔；最后一个孔掉件则序号被夹住=重试本孔）、
  话题契约、调参顺序、验收命令、踩过的坑。
- FRAMEWORK_RULES 新增 R5.8（同一份数学只许一份 + 守卫测试）、R5.9（自检的
  期望类型与调用处同源）、R5.10（缺依赖 skip，别留常年红）、R6.9（硬退出前打
  traceback）、R6.10（ros2 launch 退出码恒 0）＋ R5.7 补真机/仿真"生效方式不同"
  （真机软链即改即生效，仿真拷贝必须重编）＋ 5 条症状反例、.cursor/rules 同步。
- WORKSPACE / INTERFACES / SITE_CONFIG / HANDBOOK / 两份 README 索引与决策表补齐。

验证（本机真跑）
----------------
  pytest（仿真环境）  436 passed, 14 skipped（缺 onnx 跳过）
  干跑 --sim --dry-run  → 脚本退出码 0，结论 ok=true  已装 2/2 孔
  不干跑 --sim          → 脚本退出码 1，S00 拦住，未发任何运动指令

Co-authored-by: Cursor <cursoragent@cursor.com>

config/site.example.yaml

@@ -450,6 +450,93 @@ hole_detect:
 # Orisys 视触觉（夹爪左右指摄像机，不是腕部 D405）。SDK 单独 pip 安装。
 #   bash ~/ros2/scripts/run_tactile.sh --cli
 #   bash ~/ros2/scripts/run_tactile.sh
+# =============================================================================
+# 通止规装配（看板 S00–S11）：bash ~/ros2/scripts/run_gauge_assembly.sh --arm 89
+#
+# 这一段全是**会动的量**，也是现场最常改的地方。改完不必改代码：
+# 解析在 arm_application/gauge_config.py（键名、单位、类型都在一张表里校验），
+# 拼错键名会直接报错并给出最相近的候选名，不会静默退回默认值。
+#
+# 单位体现在键名后缀上（_deg/_mm/_m/_s/_pct/_delta），三张表逐条校验；
+# 带 _delta 的是**力增量**（Orisys 读数是形变任意单位且基线会漂移，
+# 绝对值没有意义），必须现场标定：
+#     bash ~/ros2/scripts/run_tactile.sh --cli     # 看读数量级
+# 启动时节点会打印本段**实际生效**的值（含派生结论），先核对再上电。
+# =============================================================================
+gauge_assembly:
+  # ---- 总开关 ----
+  holes_total: 2             # 一次任务装几个孔（k1/k2）；--holes N 可临时覆盖
+  dry_run: false             # true = 只验编排与自检，不发任何运动指令
+  # E1（掉件）重放时等人工确认 /gauge/reload_ok 的最长时间 [s]。超时=中止。
+  # 不是"再等等"：臂停在 home，让人来处理比继续跑安全。
+  reload_timeout_s: 180.0
+  # S00 自检每项（相机/触觉/夹爪状态）等"第一帧真数据"的最长秒数。
+  # 只看话题名会假阳性（发布者不在也算在），所以必须等真数据。
+  boot_timeout_s: 30.0
+
+  # ---- S01 回 home 后按工具系逆时针预绕到极限角 ----
+  # 预绕是为了给 S08 的棘轮留出回转行程：不预绕，拧两圈就贴关节限位。
+  extreme_angle_deg: 150.0   # 想转多少度（按工具系逆时针）
+  extreme_speed_deg_s: 20.0  # 关节角速度 [deg/s]，慢一点防冲击
+  extreme_direction: 1       # +1=逆时针 / -1=顺时针（改符号，别去改代码）
+  extreme_margin_deg: 3.0    # 距关节限位留的余量 [deg]；撞限位不算失败（按 JOINT_LIMIT 继续）
+                             # 但余量太小会让规划器频繁拒收，表现为"偶尔转不到位"
+
+  # ---- S02 夹持确认（预留，默认跳过）----
+  # 现在的触觉判据与 D435 手眼都还没就绪，先留接口：开成 true 时，
+  # 夹爪状态字必须明确报"夹住了"，否则 S02 判失败并中止。
+  grip_check: false
+  grip_hold_s: 0.5           # 合爪后等多久再读状态 [s]
+
+  # ---- S03 手外粗定位（S04 跟踪的兜底：跟踪丢了才来）----
+  # 前提是手外相机做过 eye-to-hand 标定：handeye/results/<相机>_eye_to_hand.yaml。
+  # 没有那个文件时 S03 会明确报"缺哪个文件、怎么生成"并回 S04，不做假装成功的反投影。
+  coarse_enabled: true
+  coarse_camera: "d435"      # 手外相机命名空间（话题 /d435/...）
+  coarse_hover_m: 0.25       # 粗定位后悬停在工件上方多高 [m]（可调）
+  coarse_conf: 0.35          # 工件检测置信度阈值（0~1）
+  coarse_timeout_s: 20.0     # 等手外相机出图的最长秒数（相机刚起来要一两秒）
+
+  # ---- S05 精拍定位：等画面稳了再拍 ----
+  # 判据是"所有采样点到均值的距离 ≤ 容差"，不是"相邻两帧差 ≤ 容差"：
+  # 跟踪抖动是零均值的，相邻帧之差会在画面明明在晃时判成稳定，拍出糊图。
+  snap_stable_s: 1.0         # 连续观察多久 [s]
+  snap_tol_px: 2.0           # 允许的抖动半径 [px]（越小越严，越难满）
+  snap_min_frames: 6         # 至少采到多少帧才敢说"稳定"
+
+  # ---- S06 正悬停（悬停高度不在这里：见 servo.hole_hover_z_m）----
+  align_tol_mm: 1.0          # 对位残差容差 [mm]；超了回 S05 重拍（不是硬往下走）
+                             # 孔口径 mm 级时别放大这个值：放大=直接蹭孔壁
+
+  # ---- S07 柔顺接触：步进下压，切向力突变即停 ----
+  contact_speed_m_s: 0.02    # 每步下压速度 [m/s]；这一步必须慢，快了就是一次冲击
+  contact_step_mm: 0.5       # 每步下压量 [mm]（越大越快，越小越不会过冲）
+  contact_max_depth_mm: 25.0 # 最多下探多少 [mm]；到了还没接触判失败（不会一直压）
+  contact_tangential_delta: 300.0  # 接触判据：两路切向任一相对基线增量超过它 [任意单位]
+  contact_safe_delta: 2000.0       # 法向安全上限 [任意单位]：超了立刻抬起并中止(E2)
+                                   # 必须 > contact_tangential_delta，否则自检就报矛盾
+
+  # ---- S08 棘轮拧入（慢转 → 松爪 → 快回转 → 夹紧，循环）----
+  # 停止判据：切向力 > screw_shear_delta **且** 法向力突增 > screw_normal_delta。
+  screw_step_deg: 180.0      # 每次慢转多少度；要 ≤ 预绕角（否则第一轮就贴限位）
+  screw_speed_deg_s: 30.0    # 慢转速度 [deg/s]
+  screw_back_speed_deg_s: 120.0  # 松爪后的空转回转速度 [deg/s]（爪里没东西，可以快）
+  screw_max_cycles: 12       # 最多几轮（12×180°=2160°，够 M6 螺纹规走完）
+  screw_normal_delta: 400.0  # 拧到位时的法向力突增 [任意单位]（螺纹到底/顶住）
+  screw_shear_delta: 600.0   # 拧到位的切向力增量 [任意单位]
+  screw_grip_force_pct: 50.0 # 夹紧力百分比 [%]（**只有契约后端生效**：仿真/新驱动）
+  screw_grip_speed_pct: 50.0 # 夹紧速度百分比 [%]（同上；真机 dh_pgea 驱动不支持这两个参数）
+  screw_release_wait_s: 0.3  # 松爪后等多久再回转 [s]（等爪真的张开，否则会带着规磨）
+
+  # ---- S09 反向拧出 ----
+  unscrew_extra_cycles: 1     # 比拧入多转几轮，确保螺纹完全脱开
+
+  # ---- 力判据怎么调（现场最常问）----
+  # 1) 先看量级：bash ~/ros2/scripts/run_tactile.sh --cli，手压一下看读数变化；
+  # 2) S07 的接触判据是"相对基线的增量"，基线在 S06 悬停时（还没碰工件）测；
+  # 3) 太灵敏（刚靠近就停）→ 调大 contact_tangential_delta；
+  #    不灵敏（压很深才停）→ 调小；同时看启动日志里的基线/实测值再定。
+
 tactile:
   backend: "orisys"          # orisys | mock
   # 传感器型号。必须与 devices/sensors/orisys/models/ 下的子目录名一致。