sync: SHANGHAI-U9 2026-08-12

sim-rtl-flow/SKILL.md

@@ -82,7 +82,7 @@ graph skip work:
 
 | metadata field | effect if `false` / listed |
 |---|---|
-| `redo_fixed_point` | `false` → the `-q` stage is skipped entirely |
+| `redo_fixed_point` | `false` → the `-q` stage is skipped entirely. Before answering `false`, re-check the historic `-q` against the **current** word-length rule — widths that violate it, or a history doc that never recorded widths, mean `true` |
 | `redo_partition` + `partition_review_required` | both `false` → the **`functional_partition` human checkpoint is skipped** |
 | `reuse_modules` | listed module → its `native:M` + `ip_replace:M` are skipped; result recorded as `stage: history_reuse` |
 | `redo_modules` | listed module always re-runs, even if also in `reuse_modules` |
@@ -138,26 +138,34 @@ From `Notes/PR01.md` and `Notes/PR01-2.md`; the graph routes on these.
 1. **sim-golden is the only acceptance criterion.** `-q`, the partition, and every `-E`
    version must match the `-x` sim. If it doesn't, record `gate_passed: false` — never
    record a pass you didn't verify.
-2. **One `-E.slx` per RTL submodule**, saved separately (`<project>_A-E.slx`, …). Do not
+2. **The fixed-point word-length rule ranks alongside sim-golden.** Only multiplies and
+   adds of 16bit or less — after a 16×16 product, truncate back to 16bit before anything
+   downstream; widths must not accumulate stage by stage. The one exception is loop
+   accumulation: the accumulator is at least 32bit, and its result is truncated before it
+   feeds the rest of the design. `fixed_point#n` fails on a violation even when the
+   performance matches sim-golden, and `native:*`, `modify_e:*`, `sync_sim:*` may not
+   widen anything back. The rule and its machine-readable form arrive in every affected
+   task as `context.wordlength_rule` / `context.wordlength_limits`.
+3. **One `-E.slx` per RTL submodule**, saved separately (`<project>_A-E.slx`, …). Do not
    nativize all submodules in one Simulink model.
-3. **Never hand-edit MATLAB-generated RTL.** If IP replacement, Vivado timing, or HIL
+4. **Never hand-edit MATLAB-generated RTL.** If IP replacement, Vivado timing, or HIL
    needs a change there, return `change_scope: "simulink_module"` + `affected_modules`.
    The graph then forces `modify_e:* → sync_sim:*` before any RTL is regenerated.
-4. **Editing a `-E` model obliges you to sync the `-x`/`-q` model.** `modify_e:*` edits
+5. **Editing a `-E` model obliges you to sync the `-x`/`-q` model.** `modify_e:*` edits
    only the `-E`; the follow-up `sync_sim:*` uses **`simulink-rtl-redev`** to carry the
    same change into the simulation model and re-verify against sim-golden. The
    derivation script does *not* translate native-core edits into the m implementation,
    so changing one side alone means the RTL moved while the simulation still validates
    the old behaviour. If they don't align, the graph goes back to `modify_e:*` — it will
    **not** let you regenerate RTL.
-5. **Timing fixes change the RTL, not the constraints.** Prefer adding pipeline/delay
+6. **Timing fixes change the RTL, not the constraints.** Prefer adding pipeline/delay
    stages. Only touch timing constraints when the constraint itself is plainly wrong,
    and say why in `notes`.
-6. **HIL is strictly read-only.** `hil:*` arrives with `allow_code_changes=false`. Run
+7. **HIL is strictly read-only.** `hil:*` arrives with `allow_code_changes=false`. Run
    `fpga-imx6-flow` / `zynq-imx6-flow` for *diagnosis only*; the moment a code change is
    needed, stop that sub-flow and report it back here — the fix happens in the
    sim-rtl-flow main graph, then re-enters Vivado and HIL.
-7. **Skipping a step needs written evidence, and every run leaves some.** The only
+8. **Skipping a step needs written evidence, and every run leaves some.** The only
    grounds for not executing a stage are a history doc that records it as verified and
    unaffected. Every run ends by writing the next `sim-rtl-flow-<date>.md`; anything you
    could not verify goes in as *not verified*, so the next run redoes it.
@@ -239,7 +247,7 @@ keys with a default success — rehearsal only, and it refuses review keys.
 | `history_review#n` | read `sim-rtl-flow-<date>.md` + the requirement doc, decide what may be reused; verdict in `metadata` (**first task of every run that has a history doc**) | inline — read the files, don't guess |
 | `simulink_x#n` | build/revise the `-x` sim, document the performance envelope | MATLAB MCP + `model-based-design-core:building-simulink-models`, `simulating-simulink-models` |
 | `review:sim_performance#n` | **ask the user** to sign off on sim-golden | — (relay to user) |
-| `fixed_point#n` | `-q` fixed-point, compare to `-x` | same MATLAB skills |
+| `fixed_point#n` | `-q` fixed-point, compare to `-x`, **and hold the word-length rule** (mult/add ≤16bit with truncation after the product; loop accumulators ≥32bit then truncated). Report `metadata.{wordlength_compliant, wordlength_violations, wordlengths}` — a violation fails the gate even when the performance matches sim-golden | same MATLAB skills |
 | `partition#n` | pure-sim / RTL / SoC split, must not degrade sim-golden | same |
 | `interfaces#n` | RTL↔SoC interface doc — register-config or data-stream only | write the doc under `work_dir` |
 | `review:functional_partition#n` | **ask the user** to sign off on the split + interfaces | — (relay to user) |
@@ -252,7 +260,7 @@ keys with a default success — rehearsal only, and it refuses review keys.
 | `hil:fpga-imx6-flow#n` / `hil:zynq-imx6-flow#n` | HIL debug, **read-only** | `fpga-imx6-flow` / `zynq-imx6-flow` |
 | `timing_rework#n` | fix non-Simulink RTL / SoC / project timing | inline |
 | `hil_rework#n` | apply the code change HIL asked for | inline |
-| `design_summary#n` | write `<history_dir>/sim-rtl-flow-<YYYYMMDD-HH>.md` (path handed to you in `context.target_path`) covering every `-x`/`-q`/`-E` version, the partition, per-module status, Vivado/HIL verdicts, what was reused and what is still open; return the real path in `artifacts` (**last task of every run, success or failure**) | inline |
+| `design_summary#n` | write `<history_dir>/sim-rtl-flow-<YYYYMMDD-HH>.md` (path handed to you in `context.target_path`) covering every `-x`/`-q`/`-E` version, **the `-q` word lengths (multiplier/adder widths, truncation points, loop-accumulator widths) and whether they satisfy the word-length rule** — unrecorded widths force the next run to redo `-q` — the partition, per-module status, Vivado/HIL verdicts, what was reused and what is still open; return the real path in `artifacts` (**last task of every run, success or failure**) | inline |
 
 `#n` is the n-th time that key has been requested this run — retries and rework produce
 `#2`, `#3`, …
@@ -272,6 +280,7 @@ review:   {"approved": true, "notes": "", "metadata": {}}
 |---|---|
 | `success` + `gate_passed` | every design node — `false` → retry, then `failed` after 10 attempts |
 | `artifacts` | `simulink_x`'s first artifact **becomes sim-golden**; `vivado`'s go to HIL as the bitstream |
+| `metadata.wordlength_compliant` + `wordlength_violations` + `wordlengths` | `fixed_point` — a violation (or a bare `wordlength_compliant: false`) fails the gate on its own; `wordlengths` is what the history doc records |
 | `timing_met` | `vivado` only |
 | `hil_passed` | `hil:*` only |
 | `needs_code_change` + `change_scope` + `affected_modules` | `vivado` and `hil:*` — the rework router |