From e07cfaa6d1bf979826999621b51238c5dbe05277 Mon Sep 17 00:00:00 2001
From: bowei <bowei.song@gmail.com>
Date: Mon, 10 Aug 2026 20:05:04 +0800
Subject: [PATCH] =?UTF-8?q?sync:=20WIN-BOWEI=202026-08-10=20fpga=5Fflash?=
 =?UTF-8?q?=20=E5=A2=9E=20Zynq=20BOOT.bin/QSPI=20=E8=84=9A=E6=9C=AC?=
 =?UTF-8?q?=EF=BC=8Crtl-ip-replace=20=E4=B8=8E=20sim-rtl-flow=20=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- fpga_flash: 新增 build_zynq_boot.py / program_zynq_qspi.py（bootgen + program_flash，
  含备份、SHA-256/容量/marker 守卫）；vivado_env.py 增 resolve_sdk_dir（SDK_ROOT/SDK_PATH）；
  SKILL.md 补 Zynq 烧写流程，示例去掉写死的 D:\Xilinx\SDK\2018.1，改由 skills_env.md 解析。
- rtl-ip-replace: gen_ip.tcl / namespace_ip.py 更新。
- sim-rtl-flow: SKILL.md 与 run_sim_rtl_flow.py 更新。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 fpga_flash/SKILL.md                      | 159 ++++++++++++++++++++-
 fpga_flash/scripts/build_zynq_boot.py    | 168 +++++++++++++++++++++++
 fpga_flash/scripts/program_zynq_qspi.py  | 166 ++++++++++++++++++++++
 fpga_flash/scripts/vivado_env.py         |  20 +++
 rtl-ip-replace/scripts/gen_ip.tcl        |  63 +++++++--
 rtl-ip-replace/scripts/namespace_ip.py   |  35 ++++-
 sim-rtl-flow/SKILL.md                    |  94 +++++++++++--
 sim-rtl-flow/scripts/run_sim_rtl_flow.py |  38 ++++-
 8 files changed, 712 insertions(+), 31 deletions(-)
 create mode 100644 fpga_flash/scripts/build_zynq_boot.py
 create mode 100644 fpga_flash/scripts/program_zynq_qspi.py

diff --git a/fpga_flash/SKILL.md b/fpga_flash/SKILL.md
index ad66db1..dc4549c 100644
--- a/fpga_flash/SKILL.md
+++ b/fpga_flash/SKILL.md
@@ -1,13 +1,13 @@
----
+---
 name: fpga_flash
 description: |
-  烧写 Artix-7 系列 FPGA 的外部 Flash（SPI NOR Flash）。适用于 EMV7.1 等 Artix-7 板卡，支持 Micron mt25ql128 和 Winbond w25q128bv 两种 Flash 型号。
+  按开发板/器件架构选择正确的 Flash 固化方式。支持 EMV7.1 等 Artix-7 板卡的 MCS/cfgmem 流程，以及 HJX9009（XC7Z100/Zynq-7000）将 FSBL、PL bitstream、PS ELF 打包为 BOOT.bin 后写入双并行 QSPI 的流程。
   当用户提到"烧写 flash"、"flash 编程"、"固化 bit 文件"、"下载到 flash"、"program flash"、"write flash"、"burn flash"、"Vivado flash"、"SPI flash 烧写"时，必须触发此 skill。
 ---
 
-# FPGA Flash 烧写流程（Artix-7 / EMV7.1）
+# FPGA Flash 固化流程（按开发板路由）
 
-本 skill 由 Claude **全自动执行**完整的 Flash 烧写流程。除了向用户确认必要信息外，所有操作（文件检查、CSV 修改、Vivado 命令执行、硬件编程）均由 Claude 直接完成，不要求用户手动执行任何命令。
+本 skill 由 Claude **全自动执行**完整的 Flash 固化流程。除了向用户确认必要信息外，所有操作（文件检查、备份、哈希/容量/内容守卫、工具调用、硬件编程）均由 Claude 直接完成，不要求用户手动执行任何命令。执行前必须先识别开发板与 FPGA/SoC 类型；不得把 Artix-7 的 `.mcs/cfgmem` 流程用于 Zynq，也不得把 Zynq 的 `BOOT.bin/program_flash` 流程用于普通 Artix-7。
 
 ---
 
@@ -34,6 +34,9 @@ scripts/
   program_flash.py       # 第四、五步：连接目标板并烧写 Flash
   step3_write_mcs.tcl    # gen_mcs.py 使用的 Tcl 模板（勿手动修改）
   step4_5_program.tcl    # program_flash.py 使用的 Tcl 模板（勿手动修改）
+  build_zynq_boot.py     # Zynq：FSBL + bit + PS ELF 生成受保护的 BOOT.bin
+  program_zynq_qspi.py   # Zynq：哈希/容量/marker 守卫后烧写并强制 verify
+  vivado_env.py          # 解析 Vivado/SDK 工具路径
 ```
 
 **调用方式（Bash 工具）：**
@@ -41,10 +44,153 @@ scripts/
 python "$USERPROFILE/.claude/skills/fpga_flash/scripts/<script>.py" [参数...]
 ```
 
-各脚本通过命令行参数接受变量（Vivado 安装目录、工程名、bit 文件路径、mcs 文件路径等），内部调用 Vivado `-mode batch -source <tcl模板> -tclargs <参数>` 完成执行，全程不产生临时文件。
+各脚本通过命令行参数接受变量（Vivado/SDK 安装目录、bit/ELF/MCS/BOOT 路径、容量和 marker 等）。Artix-7 脚本内部调用 Vivado `-mode batch -source <tcl模板> -tclargs <参数>`；Zynq 脚本调用 SDK 的 `bootgen`/`program_flash`。工程路径和板级文件均由参数传入，不在 skill 中硬编码。
 
 ---
 
+## 第零步：识别板卡并选择唯一流程
+
+先用工程名、器件型号、原理图/板卡说明和现有部署资料交叉确认，不允许只根据输出文件扩展名猜测。
+
+| 板卡/器件 | 固化容器 | 写入工具与接口 | 选择的流程 |
+|---|---|---|---|
+| HJX9009、`xc7z100`、Zynq-7000（PS+PL） | `BOOT.bin`，顺序为启动 FSBL + PL `.bit` + PS `.elf` | SDK `bootgen` + `program_flash -flash_type qspi_dual_parallel` | 本文“Zynq/HJX9009”流程 |
+| EMV7.1、`xc7a*`、Artix-7（纯 PL） | `.mcs` | Vivado `write_cfgmem` + Hardware Manager cfgmem | 本文“Artix-7/EMV7.1”流程 |
+
+硬阻断规则：
+
+- 发现 `xc7z*`、PS7、FSBL、PS ELF 或工程明确写明 Zynq 时，禁止运行 `gen_mcs.py`、`program_flash.py` 或 `create_hw_cfgmem`。
+- 发现 `xc7a*` 且无 PS/FSBL 时，禁止生成 `BOOT.bin`。
+- 板型、Flash 拓扑或容量不明确时，先查原理图/现有已验证部署记录；不得试烧。
+- HJX9009 已验证为两片 `s25fl128s` 双并行 QSPI，总容量 32 MiB，必须使用 `qspi_dual_parallel`，不能退化为 `qspi_single`。
+
+---
+
+## Zynq/HJX9009：同时固化 PS 与 PL
+
+### Z1. 输入与两个 FSBL 角色
+
+生成冷启动镜像需要三个输入，BIF 中顺序不可改变：
+
+```text
+the_ROM_image:
+{
+    [bootloader]<boot_fsbl.elf>
+    <implemented_pl.bit>
+    <ps_application.elf>
+}
+```
+
+必须区分两个角色不同的 FSBL：
+
+- **启动 FSBL**：封装在 `BOOT.bin` 第一分区，板卡冷启动时由 BootROM 加载，随后配置 PL 并启动 PS 应用。
+- **JTAG 烧写辅助 FSBL**：由 `program_flash -fsbl` 临时下载到 OCM，用于初始化当前板卡的 QSPI MIO/控制器并完成写入。它不等于、也不能默认替换 `BOOT.bin` 内的启动 FSBL。
+
+对 HJX9009，必须使用已验证能初始化该板 QSPI MIO 的参考 JTAG 辅助 FSBL。若项目提供其期望 SHA-256/MD5，必须作为守卫验证。错误的辅助 FSBL 可能读出 JEDEC `00,00,00`，造成表面执行但没有可靠写入。
+
+HJX9009 当前工程部署记录中的参考辅助 FSBL 指纹为 MD5 `14232757864453B418E67D63457EE24F`。这只是板级身份参考，不应写死进通用脚本；实际执行仍应从当前项目部署清单取得文件并同时记录 SHA-256。
+
+### Z2. 安全预检与备份顺序
+
+执行顺序固定如下：
+
+1. 确认本次 PS ELF、时序通过的 PL bitstream、启动 FSBL 和 JTAG 辅助 FSBL 的绝对路径。
+2. 记录四个输入的 SHA-256、字节数和修改时间；若有 `.ltx`，另记录其 SHA-256，确保它与 bitstream 同次构建。
+3. 在覆盖部署目录中的任何已有 `BOOT.bin`、BIF、FSBL、bit 或 ELF 前，复制到带时间戳的备份目录并写 manifest。不得删除已知可回退镜像。
+4. 对源文件和 staging 副本逐个比较 SHA-256，任一不一致立即停止。
+5. 为新固件指定至少一个能区分版本的 ASCII marker，并在 PS ELF 和生成的 `BOOT.bin` 中检查。marker 不匹配立即停止。
+6. 生成后要求 `BOOT.bin` 严格小于物理 QSPI 容量；HJX9009 上限为 33,554,432 字节。
+7. 记录最终 `BOOT.bin` 的 SHA-256 和精确长度；烧写命令必须重新校验这两个值，防止旧镜像或 TOCTOU 误烧。
+
+### Z3. 生成 BOOT.bin
+
+调用参数化脚本；示例只表示参数结构，实际路径和 marker 必须来自当前项目。
+Xilinx SDK 安装根目录由脚本自行解析（`SDK_ROOT` / `SDK_PATH`：先查环境变量，再查
+`~\skills_env.md`），只有需要临时覆盖时才显式传 `--sdk-dir`：
+
+```powershell
+python "$env:USERPROFILE\.claude\skills\fpga_flash\scripts\build_zynq_boot.py" `
+  --boot-fsbl "<cold-boot-fsbl.elf>" `
+  --bit-file "<implemented-top.bit>" `
+  --app-elf "<ps-application.elf>" `
+  --boot-bin "<deployment-dir>\BOOT.bin" `
+  --bif-file "<deployment-dir>\boot.bif" `
+  --capacity-bytes 33554432 `
+  --require-marker "<build-identity-marker>"
+```
+
+脚本会备份已有 BOOT/BIF、生成候选镜像、执行容量与 marker 守卫、原子替换最终镜像，并输出 JSON manifest。成功标志为：
+
+```text
+ZYNQ_BOOTGEN_PASS size=<n> sha256=<64 hex>
+```
+
+如果工程采用 staging 目录，复制 FSBL/bit/ELF 后仍要逐项重算并对比 SHA-256。`BOOT.bin` 约 18 MiB 只是 HJX9009 的常见值，不是成功判据。
+
+### Z4. 启动 Vivado hw_server 并确认 JTAG
+
+HJX9009 当前机器上必须由 **Vivado** 的 `hw_server` 给 Platform Cable USB II 加载固件；SDK 自带 hw_server 可能无法完成该动作。先启动并等待枚举出 `xc7z100`：
+
+```powershell
+& '<Vivado-root>\bin\hw_server.bat' -s tcp::3121
+```
+
+保持服务运行，确认 `tcp:127.0.0.1:3121` 可连接且 JTAG 链中只有预期目标。若 3121 被未知进程占用、目标器件不是 `xc7z100`、板卡掉电或线缆未枚举，停止，不得烧写。
+
+### Z5. 写入 HJX9009 双并行 QSPI 并强制 verify
+
+从 Z3 的输出/manifest 复制**精确** SHA-256 和长度后执行：
+
+```powershell
+python "$env:USERPROFILE\.claude\skills\fpga_flash\scripts\program_zynq_qspi.py" `
+  --image "<deployment-dir>\BOOT.bin" `
+  --jtag-fsbl "<verified-jtag-helper-fsbl.elf>" `
+  --expect-sha256 "<exact-BOOT.bin-sha256>" `
+  --expect-size <exact-byte-length> `
+  --capacity-bytes 33554432 `
+  --flash-type qspi_dual_parallel `
+  --hw-server-url tcp:127.0.0.1:3121 `
+  --expect-jtag-fsbl-sha256 "<exact-helper-FSBL-sha256>" `
+  --require-marker "<build-identity-marker>" `
+  --log-file "<deployment-dir>\program_flash.log"
+```
+
+安全约束：
+
+- offset 必须为 `0`；HJX9009 的 Flash 类型必须保持 `qspi_dual_parallel`。
+- 参数顺序必须是 `-verify` 在 `-fsbl` 前，`-cable ...` 最后；参数化脚本已固定此顺序。
+- 擦除、编程、回读校验可能超过 10 分钟；期间禁止断电、拔 JTAG、关闭 hw_server 或终止进程。
+- 不信任包装层退出码。已验证存在“无法连接 hw_server 但返回码仍为 0”的情况。
+
+真正成功必须在同一次日志中同时出现：
+
+```text
+Erase Operation successful
+Program Operation successful
+Verify Operation successful
+Flash Operation Successful
+ZYNQ_QSPI_FLASH_VERIFY_PASS
+```
+
+若出现 `Verify Operation unsuccessful`、`Flash Operation Failed`，或缺少任一成功行，一律判失败。`End of startup status: HIGH` 只证明易失配置完成，不能证明 Flash 已写入。
+
+### Z6. 完全断电冷启动与 COM5 验收
+
+烧写成功后还必须验证自主启动：
+
+1. 保存烧写日志、BOOT manifest、bit/LTX/ELF 哈希和回退镜像位置。
+2. 关闭板卡主电源及可能通过 JTAG 反向供电的接口，静置至少 30 秒；JTAG 枚举异常时按板级规程全断 90 秒。
+3. 保持 JTAG 断开，重新打开主电源，让板卡只从 QSPI 启动。
+4. 打开 COM5（115200、8N1、无流控），保存带时间戳的启动日志。
+5. 要求看到本次 PS 固件的唯一 marker/banner，并执行项目定义的只读状态命令。HJX9009 当前固件通常用 `HELP`、`?`，随后按项目规程输入 `R`；验收期望状态和命令必须以本次固件文档为准。
+6. 若 marker 不匹配、COM5 无输出、PL/PS 版本不一致或只能在重新接入 JTAG 后工作，判定冷启动失败并使用已备份的已知良好镜像回退。
+
+只有“写入日志完整成功 + verify 成功 + 完全断电后 COM5 确认本次固件自主启动”三者同时成立，才可以向用户报告 HJX9009 PS+PL 已固化。
+
+---
+
+## Artix-7/EMV7.1：MCS/cfgmem 流程（保留）
+
 ## 第一步：检查并修复 Vivado Flash 器件表
 
 **Claude 自动执行：**
@@ -156,3 +302,6 @@ ILA core 的 `Dropping logic core` WARNING 是正常现象（载入 loader/golde
 | DONE 灯不亮 | 启动模式跳线错误 | 检查 MODE 引脚电平，确认为 SPI 启动模式 |
 | 烧写后板卡跑旧程序 | Flash 未完全擦除 | 确认 `PROGRAM.ERASE 1` 已设置后重新执行 |
 | `PermissionError` 写 CSV | 权限不足 | 提示用户以管理员身份运行 Claude Code |
+| Zynq `program_flash` 返回 0 但无成功行 | hw_server 未连接或工具包装层假成功 | 按日志判失败；要求 erase/program/verify/Flash 四组成功标志齐全 |
+| HJX9009 JEDEC 为 `00,00,00` | JTAG 辅助 FSBL 未正确初始化 QSPI MIO | 使用项目已验证的参考辅助 FSBL并核对哈希，保持 `qspi_dual_parallel` |
+| `BOOT.bin` 可写但冷启动无 COM5 | 启动 FSBL/PS ELF/PL 不匹配或未自主启动 | 完全断电、断开 JTAG，从 QSPI 冷启动并核对固件 marker；失败则回退备份 |
diff --git a/fpga_flash/scripts/build_zynq_boot.py b/fpga_flash/scripts/build_zynq_boot.py
new file mode 100644
index 0000000..1fdc1d9
--- /dev/null
+++ b/fpga_flash/scripts/build_zynq_boot.py
@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Build a guarded Zynq-7000 BOOT.bin from FSBL + PL bit + PS ELF.
+
+The output is generated as a candidate, checked for capacity and required
+ASCII build markers, then atomically promoted. Existing BOOT.bin/BIF files are
+backed up before replacement. This script does not program hardware.
+"""
+import argparse
+import datetime as dt
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from vivado_env import resolve_sdk_dir
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest().upper()
+
+
+def require_file(label: str, value: str) -> Path:
+    path = Path(value).expanduser().resolve()
+    if not path.is_file():
+        raise SystemExit(f"ERROR: missing {label}: {path}")
+    return path
+
+
+def bif_path(path: Path) -> str:
+    return path.as_posix()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Build guarded Zynq BOOT.bin (boot FSBL + PL bit + PS ELF)"
+    )
+    parser.add_argument("--sdk-dir", help="Xilinx SDK root containing bin/bootgen.bat")
+    parser.add_argument("--boot-fsbl", required=True, help="FSBL executed at cold boot")
+    parser.add_argument("--bit-file", required=True, help="implemented PL .bit file")
+    parser.add_argument("--app-elf", required=True, help="PS application ELF")
+    parser.add_argument("--boot-bin", required=True, help="final BOOT.bin path")
+    parser.add_argument("--bif-file", help="persistent BIF path; default beside BOOT.bin")
+    parser.add_argument("--capacity-bytes", type=int, default=32 * 1024 * 1024)
+    parser.add_argument(
+        "--require-marker", action="append", default=[],
+        help="ASCII marker that must exist in the generated image; repeatable",
+    )
+    parser.add_argument(
+        "--backup-dir",
+        help="backup root; default <BOOT.bin directory>/flash_backups",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="validate and print only")
+    args = parser.parse_args()
+
+    boot_fsbl = require_file("boot FSBL", args.boot_fsbl)
+    bit_file = require_file("PL bitstream", args.bit_file)
+    app_elf = require_file("PS application ELF", args.app_elf)
+    boot_bin = Path(args.boot_bin).expanduser().resolve()
+    bif_file = (
+        Path(args.bif_file).expanduser().resolve()
+        if args.bif_file else boot_bin.with_suffix(".bif")
+    )
+    if args.capacity_bytes <= 0:
+        raise SystemExit("ERROR: --capacity-bytes must be positive")
+    try:
+        marker_bytes = [(marker, marker.encode("ascii")) for marker in args.require_marker]
+    except UnicodeEncodeError:
+        raise SystemExit("ERROR: --require-marker values must be ASCII")
+    app_bytes = app_elf.read_bytes()
+    missing_app_markers = [marker for marker, raw in marker_bytes if raw not in app_bytes]
+    if missing_app_markers:
+        raise SystemExit(
+            "ERROR: PS application ELF lacks required markers: " + repr(missing_app_markers)
+        )
+
+    sdk_dir = Path(resolve_sdk_dir(args.sdk_dir)).expanduser().resolve()
+    bootgen = sdk_dir / "bin" / "bootgen.bat"
+    if not bootgen.is_file():
+        raise SystemExit(f"ERROR: bootgen not found: {bootgen}")
+
+    bif_text = (
+        "the_ROM_image:\n"
+        "{\n"
+        f"    [bootloader]{bif_path(boot_fsbl)}\n"
+        f"    {bif_path(bit_file)}\n"
+        f"    {bif_path(app_elf)}\n"
+        "}\n"
+    )
+    candidate = boot_bin.with_name(f"{boot_bin.name}.candidate.{os.getpid()}")
+    cmd = [
+        str(bootgen), "-image", str(bif_file), "-arch", "zynq",
+        "-o", str(candidate), "-w", "on",
+    ]
+    print(f"[build_zynq_boot] boot FSBL: {boot_fsbl} sha256={sha256(boot_fsbl)}")
+    print(f"[build_zynq_boot] PL bit   : {bit_file} sha256={sha256(bit_file)}")
+    print(f"[build_zynq_boot] PS ELF   : {app_elf} sha256={sha256(app_elf)}")
+    print(f"[build_zynq_boot] output   : {boot_bin}")
+    print(f"[build_zynq_boot] capacity : {args.capacity_bytes}")
+    print("[build_zynq_boot] command  : " + subprocess.list2cmdline(cmd))
+    if args.dry_run:
+        print("DRY_RUN_OK: no files changed and bootgen was not executed")
+        return
+
+    boot_bin.parent.mkdir(parents=True, exist_ok=True)
+    bif_file.parent.mkdir(parents=True, exist_ok=True)
+    stamp = dt.datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_root = (
+        Path(args.backup_dir).expanduser().resolve()
+        if args.backup_dir else boot_bin.parent / "flash_backups"
+    )
+    existing = [path for path in (boot_bin, bif_file) if path.exists()]
+    if existing:
+        backup = backup_root / stamp
+        backup.mkdir(parents=True, exist_ok=False)
+        for path in existing:
+            shutil.copy2(path, backup / path.name)
+        print(f"[build_zynq_boot] backup   : {backup}")
+
+    bif_file.write_text(bif_text, encoding="utf-8", newline="\n")
+    try:
+        result = subprocess.run(cmd, check=False)
+        if result.returncode != 0 or not candidate.is_file():
+            raise RuntimeError(f"bootgen failed, rc={result.returncode}")
+        size = candidate.stat().st_size
+        if size >= args.capacity_bytes:
+            raise RuntimeError(
+                f"candidate size {size} is not below capacity {args.capacity_bytes}"
+            )
+        image = candidate.read_bytes()
+        missing = [marker for marker, raw in marker_bytes if raw not in image]
+        if missing:
+            raise RuntimeError("candidate lacks required markers: " + repr(missing))
+        candidate_hash = sha256(candidate)
+        os.replace(candidate, boot_bin)
+    except Exception as exc:
+        if candidate.exists():
+            candidate.unlink()
+        raise SystemExit(f"ERROR: {exc}")
+
+    manifest = {
+        "format": "zynq-7000-boot-bin",
+        "created": dt.datetime.now().astimezone().isoformat(),
+        "capacity_bytes": args.capacity_bytes,
+        "required_markers": args.require_marker,
+        "components": {
+            "boot_fsbl": {"path": str(boot_fsbl), "sha256": sha256(boot_fsbl)},
+            "pl_bit": {"path": str(bit_file), "sha256": sha256(bit_file)},
+            "ps_elf": {"path": str(app_elf), "sha256": sha256(app_elf)},
+        },
+        "boot_bin": {"path": str(boot_bin), "size": size, "sha256": candidate_hash},
+    }
+    manifest_path = boot_bin.with_suffix(boot_bin.suffix + ".manifest.json")
+    manifest_path.write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    print(f"ZYNQ_BOOTGEN_PASS size={size} sha256={candidate_hash}")
+    print(f"MANIFEST={manifest_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/fpga_flash/scripts/program_zynq_qspi.py b/fpga_flash/scripts/program_zynq_qspi.py
new file mode 100644
index 0000000..46850be
--- /dev/null
+++ b/fpga_flash/scripts/program_zynq_qspi.py
@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Guard and program a Zynq BOOT.bin through Xilinx program_flash.
+
+Success requires erase, program, verify, and the final Xilinx success marker;
+the process exit code alone is deliberately not trusted.
+"""
+import argparse
+import hashlib
+import os
+import re
+import socket
+import subprocess
+import sys
+from pathlib import Path
+
+from vivado_env import resolve_sdk_dir
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest().upper()
+
+
+def parse_server(url: str):
+    match = re.fullmatch(r"tcp:([^:]+):(\d+)", url)
+    if not match:
+        raise SystemExit("ERROR: --hw-server-url must look like tcp:127.0.0.1:3121")
+    return match.group(1), int(match.group(2))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Program and verify Zynq QSPI BOOT.bin")
+    parser.add_argument("--sdk-dir", help="Xilinx SDK root containing bin/program_flash.bat")
+    parser.add_argument("--image", required=True, help="BOOT.bin to program at offset 0")
+    parser.add_argument("--jtag-fsbl", required=True, help="helper FSBL loaded to OCM for programming")
+    parser.add_argument("--expect-sha256", required=True, help="exact expected BOOT.bin SHA-256")
+    parser.add_argument("--expect-size", type=int, help="exact expected BOOT.bin byte length")
+    parser.add_argument("--capacity-bytes", type=int, default=32 * 1024 * 1024)
+    parser.add_argument("--expect-jtag-fsbl-sha256", help="optional exact helper FSBL SHA-256")
+    parser.add_argument(
+        "--require-marker", action="append", default=[],
+        help="ASCII marker required in BOOT.bin; repeatable",
+    )
+    parser.add_argument(
+        "--flash-type",
+        choices=["qspi_single", "qspi_x1_single", "qspi_x2_single",
+                 "qspi_dual_parallel", "qspi_dual_stacked",
+                 "qspi_x1_dual_stacked", "qspi_x2_dual_stacked"],
+        default="qspi_dual_parallel",
+    )
+    parser.add_argument("--offset", default="0")
+    parser.add_argument("--hw-server-url", default="tcp:127.0.0.1:3121")
+    parser.add_argument("--log-file", help="write complete program_flash output here")
+    parser.add_argument("--dry-run", action="store_true", help="run guards and print command only")
+    args = parser.parse_args()
+
+    image = Path(args.image).expanduser().resolve()
+    jtag_fsbl = Path(args.jtag_fsbl).expanduser().resolve()
+    for label, path in (("BOOT.bin", image), ("JTAG helper FSBL", jtag_fsbl)):
+        if not path.is_file():
+            raise SystemExit(f"ERROR: missing {label}: {path}")
+    if args.capacity_bytes <= 0:
+        raise SystemExit("ERROR: --capacity-bytes must be positive")
+    if not re.fullmatch(r"[0-9A-Fa-f]{64}", args.expect_sha256):
+        raise SystemExit("ERROR: --expect-sha256 must contain exactly 64 hex digits")
+    if (args.expect_jtag_fsbl_sha256 and
+            not re.fullmatch(r"[0-9A-Fa-f]{64}", args.expect_jtag_fsbl_sha256)):
+        raise SystemExit(
+            "ERROR: --expect-jtag-fsbl-sha256 must contain exactly 64 hex digits"
+        )
+    try:
+        if int(args.offset, 0) != 0:
+            raise ValueError
+    except ValueError:
+        raise SystemExit("ERROR: Zynq BOOT.bin must be programmed at offset 0")
+
+    image_size = image.stat().st_size
+    image_hash = sha256(image)
+    expected_hash = args.expect_sha256.upper()
+    if image_hash != expected_hash:
+        raise SystemExit(f"ERROR: BOOT.bin SHA256 {image_hash} != expected {expected_hash}")
+    if args.expect_size is not None and image_size != args.expect_size:
+        raise SystemExit(
+            f"ERROR: BOOT.bin size {image_size} != expected {args.expect_size}"
+        )
+    if image_size >= args.capacity_bytes:
+        raise SystemExit(
+            f"ERROR: BOOT.bin size {image_size} is not below capacity {args.capacity_bytes}"
+        )
+    try:
+        marker_bytes = [(marker, marker.encode("ascii")) for marker in args.require_marker]
+    except UnicodeEncodeError:
+        raise SystemExit("ERROR: --require-marker values must be ASCII")
+    image_bytes = image.read_bytes()
+    missing = [marker for marker, raw in marker_bytes if raw not in image_bytes]
+    if missing:
+        raise SystemExit("ERROR: BOOT.bin lacks required markers: " + repr(missing))
+
+    helper_hash = sha256(jtag_fsbl)
+    if (args.expect_jtag_fsbl_sha256 and
+            helper_hash != args.expect_jtag_fsbl_sha256.upper()):
+        raise SystemExit(
+            f"ERROR: JTAG helper FSBL SHA256 {helper_hash} != expected "
+            f"{args.expect_jtag_fsbl_sha256.upper()}"
+        )
+
+    sdk_dir = Path(resolve_sdk_dir(args.sdk_dir)).expanduser().resolve()
+    program_flash = sdk_dir / "bin" / "program_flash.bat"
+    if not program_flash.is_file():
+        raise SystemExit(f"ERROR: program_flash not found: {program_flash}")
+    cmd = [
+        str(program_flash), "-f", str(image), "-offset", args.offset,
+        "-flash_type", args.flash_type, "-verify", "-fsbl", str(jtag_fsbl),
+        "-cable", "type", "xilinx_tcf", "url", args.hw_server_url,
+    ]
+    print(f"[program_zynq_qspi] image       : {image}")
+    print(f"[program_zynq_qspi] size/sha256 : {image_size} / {image_hash}")
+    print(f"[program_zynq_qspi] helper FSBL : {jtag_fsbl} / {helper_hash}")
+    print(f"[program_zynq_qspi] flash/server: {args.flash_type} / {args.hw_server_url}")
+    print("[program_zynq_qspi] command     : " + subprocess.list2cmdline(cmd))
+    if args.dry_run:
+        print("DRY_RUN_OK: guards passed; hardware was not touched")
+        return
+
+    host, port = parse_server(args.hw_server_url)
+    try:
+        with socket.create_connection((host, port), timeout=3):
+            pass
+    except OSError as exc:
+        raise SystemExit(f"ERROR: hw_server is not reachable at {host}:{port}: {exc}")
+
+    result = subprocess.run(cmd, capture_output=True, text=True, errors="replace")
+    combined = (result.stdout or "") + (result.stderr or "")
+    sys.stdout.write(combined)
+    print(f"PROGRAM_FLASH_EXIT={result.returncode}")
+    if args.log_file:
+        log_path = Path(args.log_file).expanduser().resolve()
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        log_path.write_text(combined, encoding="utf-8", errors="replace")
+        print(f"PROGRAM_FLASH_LOG={log_path}")
+
+    required = [
+        "Erase Operation successful",
+        "Program Operation successful",
+        "Verify Operation successful",
+        "Flash Operation Successful",
+    ]
+    missing_success = [marker for marker in required if marker not in combined]
+    explicit_failure = re.search(
+        r"(Verify Operation unsuccessful|Flash Operation Failed|Program Operation unsuccessful)",
+        combined, re.IGNORECASE,
+    )
+    if result.returncode != 0 or missing_success or explicit_failure:
+        raise SystemExit(
+            "ERROR: flash not proven successful; rc={} missing={} explicit_failure={}".format(
+                result.returncode, missing_success, bool(explicit_failure)
+            )
+        )
+    print("ZYNQ_QSPI_FLASH_VERIFY_PASS")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/fpga_flash/scripts/vivado_env.py b/fpga_flash/scripts/vivado_env.py
index d805951..6932d5f 100644
--- a/fpga_flash/scripts/vivado_env.py
+++ b/fpga_flash/scripts/vivado_env.py
@@ -56,3 +56,23 @@ def resolve_vivado_exe(cli_value=None):
     if exe:
         return exe
     return os.path.join(resolve_vivado_dir(), "bin", "vivado.bat")
+
+
+def resolve_sdk_dir(cli_value=None):
+    """Xilinx SDK install ROOT (the dir containing bin/bootgen.bat).
+
+    Precedence matches the Vivado resolver: explicit CLI value, SDK_ROOT,
+    SDK_PATH, then the same keys in ~/skills_env.md.
+    """
+    if cli_value:
+        return cli_value
+    root = env_lookup("SDK_ROOT")
+    if root:
+        return root
+    exe = env_lookup("SDK_PATH")
+    if exe:
+        return os.path.dirname(os.path.dirname(exe))
+    sys.exit(
+        "Xilinx SDK path not configured. Add `SDK_ROOT = <install root>` to "
+        "~/skills_env.md, set it as an env var, or pass --sdk-dir."
+    )
diff --git a/rtl-ip-replace/scripts/gen_ip.tcl b/rtl-ip-replace/scripts/gen_ip.tcl
index 09e334e..b6adf96 100644
--- a/rtl-ip-replace/scripts/gen_ip.tcl
+++ b/rtl-ip-replace/scripts/gen_ip.tcl
@@ -32,22 +32,58 @@ foreach ip $ips {
     }
     switch -- $c(type) {
         dist_mem_gen {
+            # mode {rom} (default) -- constant lookup table, asynchronous read.
+            # mode {dual_port_ram} -- LUTRAM, port A = write + async read (spo),
+            #   port B = async read (dpo), NO output registers.  Use this (not
+            #   blk_mem_gen) whenever the generated RAM needs a DEFINED read of
+            #   the pre-write word while the other port writes the same address:
+            #   a block-RAM primitive leaves the opposite port's read data
+            #   undefined on such a collision (PG058), distributed RAM does not.
+            #   The output registers / write-first read-back stay in the RTL
+            #   wrapper so latency and enb gating remain cycle-identical.
+            set dmode [opt c mode {rom}]
             create_ip -name dist_mem_gen -vendor xilinx.com -library ip -version 8.0 \
                 -module_name $name -dir $ipdir
-            set_property -dict [list \
-                CONFIG.memory_type        {rom} \
-                CONFIG.data_width         $c(width) \
-                CONFIG.depth              $c(depth) \
-                CONFIG.coefficient_file   $c(coe) \
-            ] [get_ips $name]
+            if {$dmode eq "dual_port_ram"} {
+                set_property -dict [list \
+                    CONFIG.memory_type        {dual_port_ram} \
+                    CONFIG.data_width         $c(width) \
+                    CONFIG.depth              $c(depth) \
+                    CONFIG.input_options      {non_registered} \
+                    CONFIG.output_options     {non_registered} \
+                    CONFIG.dual_port_address  {non_registered} \
+                    CONFIG.input_clock_enable {false} \
+                    CONFIG.default_data       {0} \
+                ] [get_ips $name]
+            } else {
+                set_property -dict [list \
+                    CONFIG.memory_type        {rom} \
+                    CONFIG.data_width         $c(width) \
+                    CONFIG.depth              $c(depth) \
+                    CONFIG.coefficient_file   $c(coe) \
+                ] [get_ips $name]
+            }
         }
         blk_mem_gen {
-            # SDP, common clock, READ_FIRST on the write port, no output register,
-            # ENA/ENB pins -- matches SimpleDualPortRAM_generic semantics exactly.
+            # mode {sdp_readfirst_commonclk} (default): SDP, common clock,
+            #   READ_FIRST on the write port, no output register, ENA/ENB pins --
+            #   matches SimpleDualPortRAM_generic semantics exactly.
+            # mode {tdp_writefirst_commonclk}: TRUE dual port, port A
+            #   WRITE_FIRST (write with read-back), port B READ_FIRST.
+            #   CAUTION: a BRAM primitive does NOT define the port-B read data
+            #   when port A writes the same address in the same cycle; only use
+            #   this when the design provably never collides.
+            set bmode [opt c mode {sdp_readfirst_commonclk}]
+            set mtype {Simple_Dual_Port_RAM}
+            set opa   {READ_FIRST}
+            if {$bmode eq "tdp_writefirst_commonclk"} {
+                set mtype {True_Dual_Port_RAM}
+                set opa   {WRITE_FIRST}
+            }
             create_ip -name blk_mem_gen -vendor xilinx.com -library ip -version 8.4 \
                 -module_name $name -dir $ipdir
             set_property -dict [list \
-                CONFIG.Memory_Type                {Simple_Dual_Port_RAM} \
+                CONFIG.Memory_Type                $mtype \
                 CONFIG.Assume_Synchronous_Clk     {true} \
                 CONFIG.Use_Byte_Write_Enable      {false} \
                 CONFIG.Write_Width_A              $c(width) \
@@ -55,12 +91,19 @@ foreach ip $ips {
                 CONFIG.Read_Width_A               $c(width) \
                 CONFIG.Write_Width_B              $c(width) \
                 CONFIG.Read_Width_B               $c(width) \
-                CONFIG.Operating_Mode_A           {READ_FIRST} \
+                CONFIG.Operating_Mode_A           $opa \
                 CONFIG.Enable_A                   {Use_ENA_Pin} \
                 CONFIG.Enable_B                   {Use_ENB_Pin} \
                 CONFIG.Register_PortB_Output_of_Memory_Primitives {false} \
                 CONFIG.Register_PortB_Output_of_Memory_Core       {false} \
             ] [get_ips $name]
+            if {$bmode eq "tdp_writefirst_commonclk"} {
+                set_property -dict [list \
+                    CONFIG.Operating_Mode_B {READ_FIRST} \
+                    CONFIG.Register_PortA_Output_of_Memory_Primitives {false} \
+                    CONFIG.Register_PortA_Output_of_Memory_Core       {false} \
+                ] [get_ips $name]
+            }
         }
         fifo_generator {
             # guided: mode field carries standard|fwft; depth/width from manifest
diff --git a/rtl-ip-replace/scripts/namespace_ip.py b/rtl-ip-replace/scripts/namespace_ip.py
index 0e5d521..87094ff 100644
--- a/rtl-ip-replace/scripts/namespace_ip.py
+++ b/rtl-ip-replace/scripts/namespace_ip.py
@@ -8,7 +8,27 @@ coexist in one xsim `work` library for the dual-DUT cycle-true comparison.
   left untouched -- they are not declared here.
 
 Run LAST, after rom_to_ip.py / ram_to_ip.py / any hand edits (CORDIC, FIFO).
-Idempotent: modules already ending in _IP are skipped.
+Idempotent: a name already ending in _IP is never suffixed twice.
+
+INCREMENTAL RUNS -- THE BUG THIS DOCSTRING USED TO DESCRIBE AS A FEATURE.
+The rename set used to be "modules declared here whose name does NOT already end
+in _IP", i.e. it treated an already-suffixed declaration as nothing left to do.
+That is wrong the moment incr_plan.py restores previously-rewritten files and
+drops ONE freshly regenerated file beside them, which is the normal incremental
+case:
+
+    EncAddr.v    restored from the last run  ->  declares EncAddr_IP
+    DpdTrain.v   freshly generated           ->  declares DpdTrain, instantiates EncAddr
+
+`EncAddr` was no longer in the rename set, so the new DpdTrain.v kept its bare
+`EncAddr u_EncAddr (...)` while the file that defines it had been renamed away.
+The delivery then elaborated only because the dual-DUT bench compiled the GOLDEN
+tree into the same work library, where a bare `EncAddr` still exists; synthesis,
+which sees the delivery alone, failed with "module 'EncAddr' not found".
+
+The rename set is therefore built from the BASE NAME of every declaration --
+X_IP counts as X -- so a regenerated file is namespaced against the whole
+delivery, not just against the part of it that has not been namespaced yet.
 """
 import argparse, os, re
 
@@ -19,13 +39,20 @@ def main():
     d = os.path.abspath(a.rtl_ip_dir)
     files = [os.path.join(d, f) for f in os.listdir(d) if f.endswith('.v')]
 
-    mods = []
+    mods, already = [], []
     for p in files:
         for m in re.finditer(r'^\s*module\s+(\w+)', open(p, encoding='utf-8', errors='replace').read(), re.M):
-            if not m.group(1).endswith('_IP'):
-                mods.append(m.group(1))
+            n = m.group(1)
+            if n.endswith('_IP'):
+                already.append(n[:-3])
+                mods.append(n[:-3])      # base name: a restored file still OWNS this name
+            else:
+                mods.append(n)
     mods = sorted(set(mods), key=len, reverse=True)
     print('modules:', mods)
+    if already:
+        print('already namespaced (kept in the rename set as base names):',
+              sorted(set(already)))
 
     for p in files:
         txt = open(p, encoding='utf-8', errors='replace').read()
diff --git a/sim-rtl-flow/SKILL.md b/sim-rtl-flow/SKILL.md
index 4139b8c..bb7f3fb 100644
--- a/sim-rtl-flow/SKILL.md
+++ b/sim-rtl-flow/SKILL.md
@@ -2,14 +2,18 @@
 name: sim-rtl-flow
 description: >
   Run the sim-rtl-flow LangGraph workflow at E:\LangGraph_Design\sim-rtl-flow — the
-  Simulink-to-RTL-to-hardware design pipeline: Simulink -x principle sim (sim-golden) →
-  HUMAN sign-off on simulation performance → optional -q fixed-point → parallel
-  functional partition + RTL/SoC interface spec → HUMAN sign-off on the partition →
-  per-module -E.slx nativization and Xilinx-IP replacement (parallel Send fanout) →
-  Vivado build + timing → hardware-in-the-loop via fpga-imx6-flow or zynq-imx6-flow.
-  It drives the compiled graph in-process (no langgraph dev server) and hands every
-  subagent task back to THIS Claude session — and every human checkpoint to the USER —
-  through a record/replay ledger stored in the design project being worked on.
+  Simulink-to-RTL-to-hardware design pipeline: read the previous run's design history
+  doc sim-rtl-flow-<date>.md to decide what may be reused → Simulink -x principle sim
+  (sim-golden) → HUMAN sign-off on simulation performance → optional -q fixed-point →
+  parallel functional partition + RTL/SoC interface spec → HUMAN sign-off on the
+  partition (skippable when history says the partition is unchanged) → per-module
+  -E.slx nativization and Xilinx-IP replacement (parallel Send fanout, modules the
+  history proved good are skipped) → Vivado build + timing → hardware-in-the-loop via
+  fpga-imx6-flow or zynq-imx6-flow → write a fresh sim-rtl-flow-<date>.md summarising
+  every -x / -q / -E version. It drives the compiled graph in-process (no langgraph dev
+  server) and hands every subagent task back to THIS Claude session — and every human
+  checkpoint to the USER — through a record/replay ledger stored in the design project
+  being worked on.
 
   ALWAYS use this skill whenever the user wants to run, start, drive, resume or continue
   the sim-rtl-flow workflow / Simulink→RTL design flow, or says things like "启动
@@ -22,7 +26,7 @@ description: >
 
 ## What this skill does
 
-Drives the **sim-rtl-flow** graph (21 top-level nodes + a 3-node per-module subgraph,
+Drives the **sim-rtl-flow** graph (25 top-level nodes + a 5-node per-module subgraph,
 1:1 with `Notes/PR01-1.md`, `Notes/PR01-2.md` and `Notes/PR01_sim_rtl_flow.drawio`).
 
 The graph contains **no** agent logic — it talks to the outside world through two
@@ -60,6 +64,50 @@ export PYTHONIOENCODING=utf-8
 The driver resolves the workflow checkout from `SIM_RTL_FLOW_ROOT` in
 `~\skills_env.md`, so no path is baked into this skill.
 
+## 📄 The design history doc `sim-rtl-flow-<date>.md`
+
+Every run **reads** the newest history doc and **writes** a new one. That doc is the
+only mechanism stopping the flow from re-doing — and thereby re-breaking — design work
+that a previous run already validated.
+
+| | |
+|---|---|
+| Location | `<work_dir>/<history_dir>/`, where `history_dir` defaults to the folder holding `requirements_path` (usually `Notes`) |
+| Name | `sim-rtl-flow-<YYYYMMDD-HH>.md` — date **and hour**, zero-padded, so name order == time order |
+| Read | `start` freezes the newest matching file into `input.json` as `history_path`; the `history_review#1` task interprets it |
+| Written | the `design_summary#1` task, at the end of **every** run — completed *and* failed |
+
+`history_review` returns its verdict in `metadata`, and that verdict is what lets the
+graph skip work:
+
+| metadata field | effect if `false` / listed |
+|---|---|
+| `redo_fixed_point` | `false` → the `-q` stage is skipped entirely |
+| `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` |
+
+**Every default is "redo".** Omit a field and the stage runs. Fail the
+`history_review` gate (`gate_passed: false`) and *nothing* is skipped. Recording a skip
+you did not verify means a later gate — Vivado, HIL, sim-golden — validates a design
+nobody checked this run.
+
+Four things force everything back to redo, regardless of the history doc:
+
+1. `simulink_x` running a second time (a rejected `sim_performance`, or a retry) —
+   sim-golden may have moved, so the history describes a *different* `-x`;
+2. `partition#n` returning `metadata.partition_changed: true` — the human checkpoint
+   comes back even if history said to skip it;
+3. any module named by Vivado or HIL rework — the reuse pool is consumed after the
+   first module round and never applies to a rework round;
+4. the user having already answered `functional_partition` once — a rejection can never
+   be swallowed by a later "history says skip it".
+
+When you write the summary, `artifacts[0]` must be the real path you wrote. If the
+summary cannot be written after `--max-attempts`, the run is reported **failed** even
+if the design itself passed — because the next run would silently lose its basis for
+skipping anything.
+
 ## ⚠️ The two human checkpoints are the user's decision, not yours
 
 The graph stops at two points that **an agent may not decide**:
@@ -67,7 +115,7 @@ The graph stops at two points that **an agent may not decide**:
 | checkpoint | where | what the user confirms |
 |---|---|---|
 | `sim_performance` | after step 1 | the `-x` sim meets the requirement and may be frozen as **sim-golden** |
-| `functional_partition` | after step 3 | the pure-sim / RTL / SoC split and the RTL↔SoC interface doc |
+| `functional_partition` | after step 3 | the pure-sim / RTL / SoC split and the RTL↔SoC interface doc — **skipped** only when the history doc says the partition is unchanged (see above) |
 
 When one comes up the driver prints a `!!!` banner. **Relay the question and its context
 to the user verbatim, then wait.** Do not approve on your own judgement, do not infer
@@ -109,6 +157,10 @@ From `Notes/PR01.md` and `Notes/PR01-2.md`; the graph routes on these.
    `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
+   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.
 
 ## Run (agent path)
 
@@ -140,6 +192,8 @@ EOF
 | `fixed_point_required` | `false` skips the `-q` stage |
 | `rtl_modules` | submodule names; each gets its own parallel `native → ip_replace` chain. Non-empty. |
 | `soc_modules` | MCU/SoC-side modules (interface-spec input) |
+| `history_dir` | optional — folder holding `sim-rtl-flow-<date>.md`; defaults to the folder of `requirements_path` |
+| `history_path` | optional — pin one history doc. Omit and `start` fills in the newest it finds; set `""` to declare "no history, do everything". |
 
 ### 2. Start — exits 10 with a handoff
 
@@ -182,6 +236,7 @@ keys with a default success — rehearsal only, and it refuses review keys.
 
 | key | what you actually do | which skill to use |
 |---|---|---|
+| `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 |
@@ -197,6 +252,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 |
 
 `#n` is the n-th time that key has been requested this run — retries and rework produce
 `#2`, `#3`, …
@@ -238,9 +294,12 @@ A failing `ip_replace:<M>` (cycle-true mismatch) enters the same chain on its ow
 | stage | keys handed over at once |
 |---|---|
 | after `-x` / `-q` | `interfaces#1` **and** `partition#1` |
-| module fanout | one `native:<M>#1` per module (3 for `["A","B","C"]`) |
+| module fanout | one `native:<M>#1` per module (3 for `["A","B","C"]`) — **minus any module reused from history** |
 | next module stage | one `ip_replace:<M>#1` per module |
 
+`history_review#1` and `design_summary#1` are always single-task batches, at the very
+start and the very end of the run.
+
 Work batched tasks in any order; record all, then `resume`.
 
 ## Rehearsal without touching hardware
@@ -311,6 +370,19 @@ Global flags go **before** the subcommand: `--project`, `--work-dir`, `--thread-
   are fine on Windows; a relative `"."` resolves against wherever the driver was
   launched — always use an absolute path.
 - **`start` wipes the ledger** unless `--keep-ledger`. Use a fresh `--thread-id` per run.
+- **`start` freezes `history_path` into `input.json`.** It must not be re-scanned on
+  every `resume`: the run itself writes a *newer* `sim-rtl-flow-<date>.md` at the end,
+  and a re-scan would make a later replay reference a different history doc than the
+  one already recorded in the ledger. Pinning it also makes `resume` after
+  `WORKFLOW FINISHED` a no-op instead of a spurious new handoff.
+- **A reused module produces no `native:`/`ip_replace:` keys at all.** If you expected
+  three modules and only got one task, check the `modules_reused_from_history` event —
+  that is the graph honouring your own `history_review` verdict, not a lost module.
+- **`design_summary` is the deliverable, not a formality.** Record it only after the
+  file really exists on disk with real content; `artifacts[0]` must be its path.
+- **The summary can fail an otherwise-good run.** `status: failed` with
+  `运行已结束但历史设计说明文件 … 未能生成` means the design work passed but the history
+  doc did not get written — fix that and re-run the summary, don't ignore it.
 
 ## Troubleshooting
 
diff --git a/sim-rtl-flow/scripts/run_sim_rtl_flow.py b/sim-rtl-flow/scripts/run_sim_rtl_flow.py
index 3584966..4d88e24 100644
--- a/sim-rtl-flow/scripts/run_sim_rtl_flow.py
+++ b/sim-rtl-flow/scripts/run_sim_rtl_flow.py
@@ -119,6 +119,10 @@ def _bootstrap(project: Path):
         SubagentResult,
     )
     from sim_rtl_flow.graph import WorkflowContext, build_workflow  # noqa: E402
+    from sim_rtl_flow.history import (  # noqa: E402
+        discover_history_doc,
+        history_dir_for,
+    )
     from sim_rtl_flow.review import ReviewDecision, ScriptedReviewGate  # noqa: E402
 
     return {
@@ -128,6 +132,8 @@ def _bootstrap(project: Path):
         "ReviewDecision": ReviewDecision,
         "WorkflowContext": WorkflowContext,
         "build_workflow": build_workflow,
+        "discover_history_doc": discover_history_doc,
+        "history_dir_for": history_dir_for,
     }
 
 
@@ -395,7 +401,20 @@ def _print_final(state: Any, replayed: list[str]) -> None:
             review = state.get(key)
             if review:
                 mark = "批准" if review.get("approved") else "驳回"
+                if (review.get("metadata") or {}).get("skipped_by_history"):
+                    mark = "按历史设计说明文件跳过"
                 print(f"{label} : {mark} {review.get('notes', '')}".rstrip())
+        plan = state.get("history_plan") or {}
+        print(f"历史文件 · 参考 : {plan.get('history_path') or '(none)'}")
+        if plan.get("history_path"):
+            print(
+                "历史文件 · 沿用 : "
+                f"重做定点化={plan.get('redo_fixed_point')} "
+                f"重做功能划分={plan.get('redo_partition')} "
+                f"沿用子模块={plan.get('reuse_modules')}"
+            )
+        written = state.get("history_doc_written")
+        print(f"历史文件 · 本次 : {written or '(未生成！下次运行将失去跳步依据)'}")
         print(f"modules        : {state.get('rtl_modules')}")
         for item in state.get("module_results", []):
             print(
@@ -452,7 +471,20 @@ def _invoke(run: RunDir, api: dict[str, Any], args) -> int:
 def cmd_start(args, api) -> int:
     payload = json.loads(Path(args.input).read_text(encoding="utf-8"))
     payload.pop("outcomes", None)
-    run = RunDir(_resolve_work_dir(args, payload), args.thread_id)
+    payload.pop("reviews", None)
+    work_dir = _resolve_work_dir(args, payload)
+    # 把"参考哪一份历史设计说明文件"冻结进 input.json：本次运行结束时会写出一份
+    # 新的 sim-rtl-flow-<date>.md，若每次 resume 都重新扫描目录，replay 就会在
+    # 半路换掉参考文件，走出一条与已记录 ledger 不同的路。
+    if "history_path" not in payload:
+        history_dir = api["history_dir_for"](
+            payload.get("history_dir"), payload.get("requirements_path", "")
+        )
+        payload["history_dir"] = history_dir
+        payload["history_path"] = api["discover_history_doc"](
+            str(work_dir), history_dir
+        )
+    run = RunDir(work_dir, args.thread_id)
     run.set_input(payload)
     if not args.keep_ledger:
         run.set_ledger({})
@@ -460,6 +492,10 @@ def cmd_start(args, api) -> int:
     print(f"work dir : {run.work_dir}")
     print(f"run dir  : {run.path}")
     print(f"thread   : {run.thread_id}")
+    print(
+        "history  : "
+        + (payload.get("history_path") or "(none — 首次设计，全部步骤实打实执行)")
+    )
     print("input    : " + json.dumps(payload, ensure_ascii=False))
     return _invoke(run, api, args)