bb-rtl-coder

<DEFAULTS> output_dir: ./rtl language: sv auto_approve: false project_dir: auto-detect module_id: all parallel: 4 dry_run: false resume: false full: false synthesis_tool: generic </DEFAULTS>

Pipeline Position

spec_mas/ ──→ [bb-rtl-coder] ──→ rtl/ ──→ bb-code-review ──→ synthesis
      INPUT_DIR          OUTPUT_DIR        AUTO

---

HARD-GATE 定义

<HARD-GATE>
在任何 RTL 生成操作前，必须完成以下步骤：

1. 定位 INPUT_DIR + 验证必需文档（MANDATORY）
   - 若用户提供路径，验证存在
   - 否则自动检测最新子目录
   - 每个模块必须有 MAS.md（至少有接口定义）
   - 叶子模块必须有 FSM.md 和 datapath.md

2. 创建工作目录（MANDATORY）
   ```bash
   mkdir -p {{ OUTPUT_DIR }}
   mkdir -p {{ CHECKPOINT_DIR }}
   mkdir -p {{ PROGRESS_DIR }}

3. 运行 Change Detection（MANDATORY） → 决定 full run 或 incremental run

禁止行为（在完成初始化前）：

• 加载 spec_mas 输入
• 启动 RTL 模块树生成
• 输出 RTL 文件 </HARD-GATE>

---

## 铁律（违反即停止）

> 以下规则不受 auto_approve 影响，任何模式下均不得绕过。

| 铁律 | 检查点 | 失败动作 |
|------|--------|----------|
| **Spec 先行铁律** | MAS 文件 < 2 份 | 拒绝执行，返回 bb-mas 阶段 |
| **叶子优先铁律** | 子模块 RTL 未完成 | 禁止开始父模块 RTL |
| **可综合性铁律** | RTL 有不可综合构造 | 立即修复，不继续 |
| **端口一致铁律** | 端口 ≠ MAS.md §2.1 | 立即修复，不继续 |
| **状态机编码铁律** | FSM 状态编码 ≠ FSM.md | 立即修复，不继续 |
| **并行上限铁律** | 子 agent > 6 | 拆分批次执行 |

---

## Global Paths

PROJECT_DIR = {{ project_dir 参数 或 auto-detect }} INPUT_DIR = {{ PROJECT_DIR }}/spec_mas OUTPUT_DIR = {{ PROJECT_DIR }}/rtl TEMPLATE_DIR = ~/.claude/skills/bb-rtl-coder/templates REFERENCE_DIR = ~/.claude/skills/bb-rtl-coder/references SCRIPT_DIR = ~/.claude/skills/bb-rtl-coder/scripts PROJECT_SCRIPTS = {{ PROJECT_DIR }}/scripts PROGRESS_DIR = {{ OUTPUT_DIR }}/.progress CHECKPOINT_DIR = {{ OUTPUT_DIR }}/.checkpoint SKILL_FILE = ~/.claude/skills/bb-rtl-coder/SKILL.md EVOLUTION_FRAMEWORK = ~/.claude/evolution-framework

---

## 增量更新机制

当 `/bb-mas` 重新生成或更新 `spec_mas/` 后再次执行 `/bb-rtl-coder`，自动检测变更并仅更新受影响模块。

### Spec Snapshot

每次成功执行后，将所有 spec 文件的哈希存入 `${CHECKPOINT_DIR}/spec_snapshot.json`：

```json
{
  "snapshot_time": "2026-05-16T12:00:00+08:00",
  "files": {
    "module_tree.md": "<sha256>",
    "M01/MAS.md": "<sha256>",
    "M01/FSM.md": "<sha256>",
    "M01/datapath.md": "<sha256>",
    "M02/MAS.md": "<sha256>"
  }
}

Change Detection

在 Prerequisites 段自动执行：

IF spec_snapshot.json 不存在 → FULL RUN（首次执行）
IF spec_snapshot.json 存在 → 逐文件比较哈希：
  ├─ module_tree.md 变更 → 解析新增/删除/重组的模块
  ├─ M*/MAS.md 变更       → 标记该模块为 modified
  ├─ M*/FSM.md 变更       → 标记该模块为 modified
  ├─ M*/datapath.md 变更  → 标记该模块为 modified
  └─ 全部文件哈希一致    → SKIP（输出 "No spec changes detected"）

Impact Classification

分类	触发条件	处理方式
added	module_tree.md 中新增的模块	完整 RTL 生成流程
removed	module_tree.md 中删除的模块	归档 RTL 到 temp/deleted/
modified	MAS/FSM/datapath 哈希变更	完整 RTL 重写
cascade	依赖 modified 模块的父模块	重新检查端口连接
unchanged	无变更且不依赖变更模块	跳过

---

规模感知执行模式

在读取 module_tree.md 后，统计总模块数并选择编排模式：

# 读取 SessionStart hook 预生成的上下文预算
cat ~/.claude/ctx_budget.env 2>/dev/null || echo "SAFE_TOKENS=100000"

SAFE_TOKENS=$(grep SAFE_TOKENS ~/.claude/ctx_budget.env | cut -d= -f2)
TOTAL_MODULES=$(grep -c "^- M" "${INPUT_DIR}/module_tree.md" 2>/dev/null || echo 0)

INLINE_MODULE_MAX=$(python3 -c "t=$SAFE_TOKENS; print(min(t//1000,30))")
BATCHED_MODULE_MAX=$(python3 -c "t=$SAFE_TOKENS; print(min(t//300,80))")

if   [ "$TOTAL_MODULES" -le "$INLINE_MODULE_MAX" ];  then MODE="inline"
elif [ "$TOTAL_MODULES" -le "$BATCHED_MODULE_MAX" ];  then MODE="batched"
else                                                        MODE="delegated"
fi

echo "Modules: $TOTAL_MODULES  inline≤$INLINE_MODULE_MAX  batched≤$BATCHED_MODULE_MAX → MODE=$MODE"

模式	适用规模	Orchestrator context 策略
inline	≤ 30 模块	所有模块追踪在当前 context
batched	30 < modules ≤ 80	每批完成后 /compact，状态依赖 checkpoint
delegated	> 80 模块	每层派发 subagent，主 context 只追踪层级进度

Context Budget 控制

• 每完成一个批次（4-8 模块）→ 执行 /compact
• /compact 前确保进度已写入 ${CHECKPOINT_DIR}/*.done
• /compact 后从 checkpoint 文件恢复状态继续

---

Execution Flow（MANDATORY）

全程自动执行，无需用户确认。 从叶子模块到父模块 + 综合检查 + 自动 impl-review + Fix Issues + Push。

Phase 1–4: RTL Generation（叶子→父） → Phase 5: Synthesis Check
      │
      ↓
Phase 6: Auto code-review（自动调用 bb-code-review）
      │ → 输出: ${OUTPUT_DIR}/.review/issues.md
      │
      ↓
Phase 7: Fix Issues（自动修复所有 CRITICAL/HIGH）
      │ → 修复 → 重检 → 迭代（最多 3 轮）
      │
      ↓
Phase 8: Push to Remote
      │
      ↓
Final Report 输出

---

Phase 1：构建 RTL 模块树

1.1 输入规模检测

MAS_COUNT=$(find ${INPUT_DIR} -name "MAS.md" | wc -l)
FSM_COUNT=$(find ${INPUT_DIR} -name "FSM.md" | wc -l)

if [ "$MAS_COUNT" -lt 2 ]; then
    echo "ERROR: MAS 文件不足 2 份，返回 bb-mas 阶段"
    exit 1
fi

1.2 解析模块树

从 spec_mas/module_tree.md 读取模块层级结构：

M01_ALU/
├── M01a_IntegerALU/
│   └── M01a1_Adder/
│   └── M01a1_Multiplier/
├── M01b_FloatALU/

1.3 创建 RTL 目录结构

mkdir -p {{ OUTPUT_DIR }}/M01_ALU/src
mkdir -p {{ OUTPUT_DIR }}/M01_ALU/tb
mkdir -p {{ OUTPUT_DIR }}/M01a_IntegerALU/src
mkdir -p {{ OUTPUT_DIR }}/M01a_IntegerALU/tb

1.4 输出 RTL 模块树文档

写入 {{ OUTPUT_DIR }}/rtl_tree.md

---

Phase 2：叶子模块 RTL 编写（并行）

子 agent 指令模板

## 任务：编写叶子模块 RTL

**路径规范**：
- 输入目录：{{ INPUT_DIR }}/{{ MODULE_PATH }}
- 输出文件：{{ OUTPUT_DIR }}/{{ MODULE_PATH }}/src/{{ MODULE_NAME }}.sv
- 参考文档：{{ REFERENCE_DIR }}/sv_coding_style.md

**输入文件**：
1. MAS.md — 接口定义、时序规格
2. FSM.md — 状态机定义
3. datapath.md — 数据通路结构
4. regmap.md — 寄存器映射定义（可选，有寄存器接口的模块必须提供）

**Traceability 注入规则**：

**A. Spec Header（模块级摘要）**：

每个 RTL 文件头部必须包含 Spec Header，为 AI agent 和人工 reviewer 提供快速上下文：

```systemverilog
//==============================================================================
// Module: {{ MODULE_NAME }}
// 
// SPEC HEADER
// ─────────────────────────────────────────────────────────────────────────────
// Source:       spec/MAS/{{ MODULE_ID }}_{{ MODULE_NAME }}/MAS.md
// Version:      {{ SPEC_VERSION }}
// Status:       {{ DRAFT|REVIEW|FROZEN }}
// Spec Hash:    {{ sha256:xxxxxxxxxxxx }}  ← 由 scripts/compute_spec_hash.py 计算
// REQ Coverage: REQ-{{ MODULE_ID }}-F01 ~ REQ-{{ MODULE_ID }}-F{{ MAX_F }}
// 
// Purpose:
//   {{ 一行描述模块功能 }}
// 
// Key Constraints:
//   [C1] {{ 关键约束 1，如：最大同时调度线程数: 2 }}
//   [C2] {{ 关键约束 2，如：op_valid → op_ready 响应时间: 1-5 cycles }}
//   [C3] {{ 关键约束 3，如：复位后 syst_mode = 0 }}
// 
// Dependencies:
//   - {{ 依赖模块 1，如：M02_SRAM (存储接口) }}
//   - {{ 依赖模块 2，如：M06_ClockManager (时钟源) }}
// 
// Traceability:
//   PRD:  spec/PRD/PRD.md §{{ SECTION }}
//   ARCH: spec/ARCH/{{ FILE }}.md §{{ SECTION }}
//   MAS:  spec/MAS/{{ MODULE_ID }}_{{ MODULE_NAME }}/MAS.md
//   REGMAP: spec/MAS/{{ MODULE_ID }}_{{ MODULE_NAME }}/regmap.md  ← 若有寄存器定义
// 
// Change Log:
//   {{ VERSION }} - {{ DATE }}: {{ CHANGE_DESCRIPTION }}
//==============================================================================

B. REQ_ID 标注：

1. 从 MAS.md §10 提取 REQ_ID 列表（REQ-M##-F## 格式）
2. 模块声明前添加：// @requirement REQ-M##-F01, REQ-M##-F02 @auto:rtl-gen
3. 选择性内联（避免过度标注）：

代码块类型	必须标注	示例
Module 声明	✅	module M01_DataflowController
FSM (always_ff with case)	✅	状态机实现
协议握手逻辑	✅	handshake, AXI, APB
关键计算路径	✅	datapath, pipeline stages
寄存器阵列	✅	reg_file, context storage
简单赋值 (assign)	❌	assign valid = en && ready;
端口声明	❌	input logic clk;
参数定义	❌	parameter WIDTH = 32;

4. SVA 断言必须包含 @verifies + @spec_ref + @constraint 注释：

// @verifies REQ-M##-F04
// @spec_ref MAS/{{ MODULE_ID }}/datapath.md §{{ SECTION }}
// @constraint {{ 自然语言约束说明 }}
property p_xxx;
    ...
endproperty
assert property (p_xxx)
    else $error("[SPEC §x.x] {{ 失败描述 }}");

SVA 生成规则：

1. 从 verification.md §3 断言列表读取断言规格（ID、条件、严重性）
2. 将每条断言转换为 SystemVerilog concurrent assertion
3. 每个 SVA 前添加 @verifies REQ-M##-F## 和 @requirement REQ-M##-F##
4. 断言失败时使用 $error 输出断言 ID 和描述

示例：

//==============================================================================
// Module: M01_DataflowController
// 
// SPEC HEADER
// ─────────────────────────────────────────────────────────────────────────────
// Source:       spec/MAS/M01_DataflowController/MAS.md
// Version:      1.2
// Status:       FROZEN
// Spec Hash:    sha256:abc123def456
// REQ Coverage: REQ-M01-F01 ~ REQ-M01-F12
// 
// Purpose:
//   NPU 数据流控制器，协调 systolic array 的运算调度。
// 
// Key Constraints:
//   [C1] 最大同时调度线程数: 2
//   [C2] op_valid → op_ready 响应时间: 1-5 cycles
//   [C3] 复位后 syst_mode = 0 (inference mode)
// 
// Dependencies:
//   - M02_SRAM (存储接口)
//   - M06_ClockManager (时钟源)
// 
// Traceability:
//   PRD:  spec/PRD/PRD.md §3.1
//   ARCH: spec/ARCH/block_diagram.md §2
//   MAS:  spec/MAS/M01_DataflowController/MAS.md
//==============================================================================

// @requirement REQ-M01-F01, REQ-M01-F02 @auto:rtl-gen
module M01_DataflowController (
    input  logic clk,
    input  logic rst_n,
    ...
);

    // @requirement REQ-M01-F03
    always_ff @(posedge clk or negedge rst_n) begin
        ...
    end

    // @verifies REQ-M01-F04
    // @spec_ref MAS/M01/datapath.md §3.2
    // @constraint 握手协议: valid 拉高后，ready 必须在 1-5 个周期内响应
    property p_handshake;
        @(posedge clk) disable iff (!rst_n)
        valid |-> ##[1:5] ready;
    endproperty
    p_handshake_check: assert property (p_handshake)
        else $error("[SPEC §3.2] Handshake protocol violation: valid without ready");

    // @verifies REQ-M01-F05
    // @spec_ref MAS/M01/datapath.md §3.3
    // @constraint FIFO 不溢出: full 时禁止写入
    property p_fifo_no_overflow;
        @(posedge clk) disable iff (!rst_n)
        (fifo_full && wr_en) |-> ##0 1'b0;
    endproperty
    p_fifo_no_overflow_check: assert property (p_fifo_no_overflow)
        else $error("[SPEC §3.3] FIFO overflow: write when full");

endmodule

RTL 质量要求：

1. 端口定义：与 MAS.md §2.1 完全一致
2. 状态机：与 FSM.md 状态编码一致
3. 数据通路：实现 datapath.md 流水线结构
4. 可综合性：无 initial 块（除 testbench）、无 delay、无递归
5. 时钟域：单一时钟域；CDC 模块需标注
6. Traceability：每个功能块必须有 @requirement 注释

禁止事项：

• 禁止使用 initial（testbench除外）
• 禁止使用 #delay
• 禁止使用 force/release
• 禁止使用递归模块实例化
• 禁止使用 wait 语句
• 禁止省略 @requirement 注释

寄存器接口生成（当模块有 regmap.md 时）：

1. 从 regmap.md §1 读取寄存器列表，实现 APB 寄存器读写逻辑：

   • RW 寄存器：写更新、读返回当前值
   • RO 寄存器：写忽略、读返回硬件状态
   • W1C 寄存器：写 1 清零对应位
   • RESERVED 位：写入忽略

2. 生成寄存器文档和 SVA 断言：

   uv run $PROJECT_SCRIPTS/generate_regmap_doc.py \
       --regmap spec/MAS/{{ MODULE_ID }}/regmap.md \
       --output doc/regmap/
   
   uv run $PROJECT_SCRIPTS/generate_regmap_assertions.py \
       --regmap spec/MAS/{{ MODULE_ID }}/regmap.md \
       --output {{ OUTPUT_DIR }}/{{ MODULE_PATH }}/src/{{ MODULE_NAME }}_regmap_assertions.sv
   

3. 在 RTL 中 bind 生成的断言模块：

   // 在 {{ MODULE_NAME }}.sv 末尾
   `ifdef FORMAL
   bind {{ MODULE_NAME }} {{ MODULE_NAME }}_regmap_assertions u_regmap_assertions (
       .clk(clk), .rst_n(rst_n),
       .addr(paddr), .sel(psel), .enable(penable),
       .write(pwrite), .wdata(pwdata), .rdata(prdata)
   );
   `endif
   

### 叶子模块 RTL 结构

```systemverilog
// {{ MODULE_NAME }}.sv
// Generated by rtl-coder from spec_mas/{{ MODULE_PATH }}

module {{ MODULE_NAME }} (
    // Clock & Reset
    input  logic        clk,
    input  logic        rst_n,
    
    // Input Ports (from MAS.md §2.1)
    input  logic [WIDTH-1:0]  {{ port_name }},
    ...
    
    // Output Ports (from MAS.md §2.1)
    output logic [WIDTH-1:0]  {{ port_name }},
    ...
);

    // FSM States (from FSM.md)
    typedef enum logic [N-1:0] {
        IDLE    = {{ encoding }},
        ACTIVE  = {{ encoding }},
        ...
    } state_t;
    
    state_t current_state, next_state;
    
    // Datapath Registers (from datapath.md)
    logic [WIDTH-1:0] {{ reg_name }};
    ...
    
    // FSM Sequential Logic
    always_ff @(posedge clk or negedge rst_n) begin
        if (!rst_n) begin
            current_state <= IDLE;
            {{ reset_values }}
        end else begin
            current_state <= next_state;
            {{ sequential_updates }}
        end
    end
    
    // FSM Combinational Logic
    always_comb begin
        next_state = current_state;
        {{ default_outputs }}
        
        case (current_state)
            IDLE: begin
                if ({{ condition }}) begin
                    next_state = ACTIVE;
                    {{ state_outputs }}
                end
            end
            ...
        endcase
    end
    
    // Datapath Logic (from datapath.md)
    {{ datapath_logic }}
    
endmodule

---

Phase 3：父模块 RTL 编写（逐层上卷）

从最深的父模块开始，逐层向上编写。

父模块 RTL 特殊内容

module {{ PARENT_MODULE }} (
    // Top-level Ports (from MAS.md)
    ...
);

    // Sub-module Instantiations
    {{ SUB_MODULE_1 }} u_{{ SUB_MODULE_1 }} (
        .clk   (clk),
        .rst_n (rst_n),
        {{ port_connections }}
    );
    
    {{ SUB_MODULE_2 }} u_{{ SUB_MODULE_2 }} (
        ...
    );
    
    // Inter-module Connections
    logic [WIDTH-1:0] {{ interconnect_signal }};
    
    // Top-level FSM Coordination (if applicable)
    {{ top_fsm }}
    
endmodule

端口连接原则

• 子模块输出 → 父模块内部信号
• 子模块输入 → 父模块内部信号或顶层端口
• 端口位宽必须匹配

---

Phase 4：Testbench 生成

Testbench 结构

// tb_{{ MODULE_NAME }}.sv
// Testbench for {{ MODULE_NAME }}

`timescale 1ns/1ps

module tb_{{ MODULE_NAME }};
    
    // Clock & Reset Generation
    logic clk;
    logic rst_n;
    
    initial begin
        clk = 0;
        forever #{{ CLOCK_PERIOD }} clk = ~clk;
    end
    
    initial begin
        rst_n = 0;
        #{{ RESET_PERIOD }};
        rst_n = 1;
    end
    
    // DUT Instance
    {{ MODULE_NAME }} dut (
        .clk   (clk),
        .rst_n (rst_n),
        {{ port_connections }}
    );
    
    // Test Sequences (from verification.md)
    initial begin
        {{ test_sequence_1 }}
        {{ test_sequence_2 }}
        ...
        $finish;
    end
    
    // Assertions (from verification.md)
    {{ assertions }}
    
    // Waveform Dump
    initial begin
        $dumpfile("{{ MODULE_NAME }}.vcd");
        $dumpvars(0, tb_{{ MODULE_NAME }});
    end
    
endmodule

---

Phase 5：综合性检查（MANDATORY）

5.1 可综合性规则检查

python3 {{ SCRIPT_DIR }}/synthesis_check.py \
    --input {{ OUTPUT_DIR }}/{{ MODULE_PATH }}/src \
    --report {{ OUTPUT_DIR }}/{{ MODULE_PATH }}/syn_check.json

规则	描述	严重性
NO_INITIAL	禁止 initial 块（TB除外）	CRITICAL
NO_DELAY	禁止 #delay 语句	CRITICAL
NO_FORCE	禁止 force/release	CRITICAL
NO_WAIT	禁止 wait 语句	CRITICAL
NO_RECURSION	禁止递归实例化	CRITICAL
NO_LATCH	禁止锁存器生成	HIGH
SINGLE_CLOCK	单时钟域检查	HIGH
PORT_WIDTH	端口位宽一致性	HIGH
FSM_ENCODING	FSM 状态编码一致性	HIGH

5.2 Gap Analysis（类似 Coverage Gap Analysis）

若检查发现问题，必须执行以下步骤：

1. 识别问题位置

   python3 -c "import json; r=json.load(open('syn_check.json')); print([i for i in r['issues'] if i['severity']=='CRITICAL'])"
   

2. 问题分类处理

   类型	处理方式
   不可综合构造	立即删除/替换
   锁存器生成	添加默认值/完整分支
   端口不匹配	调整位宽/添加显式转换
   状态编码错误	复制 FSM.md 编码

3. 修复验证循环

   • 修复 → 重检 → 直到无 CRITICAL/HIGH

禁止行为：

• ❌ 跳过问题分析
• ❌ 声称"只有一个 latch 问题不大"
• ❌ 在有 CRITICAL问题时继续下一阶段

---

Phase 6：自动 impl-review（MANDATORY AUTO）

自动执行，无需用户确认。 调用 bb-code-review 进行对抗性评审：

Skill(skill="bb-code-review", args="--spec_path ${INPUT_DIR} --code_dir ${OUTPUT_DIR}")

# 等待评审完成，读取问题清单
issues_file = "${OUTPUT_DIR}/.review/issues.md"

若评审失败 → 报告错误并终止。

---

Phase 7：Fix Issues（MANDATORY AUTO）

自动执行，无需用户确认。 根据 impl-review 输出的问题清单自动修复。

7.1 问题加载与分级处理

ISSUES_FILE="${OUTPUT_DIR}/.review/issues.md"
python3 - <<'EOF'
import re, pathlib
content = pathlib.Path("${ISSUES_FILE}").read_text()
issues = re.findall(r'###\s+\[([A-Z]+-\d+)\].*?Severity:\s+(CRITICAL|HIGH|MEDIUM|LOW)', content, re.DOTALL)
critical = [i for i in issues if i[1] == 'CRITICAL']
high = [i for i in issues if i[1] == 'HIGH']
print(f"CRITICAL: {len(critical)}, HIGH: {len(high)}")
EOF

7.2 修复执行顺序

修复优先级：CRITICAL → HIGH → MEDIUM
每个问题修复后立即运行综合检查验证

7.3 修复迭代与重审

• 若仍有 CRITICAL/HIGH 问题 → 重复 Phase 7（最多 3 轮）
• 若 3 轮后仍有 CRITICAL/HIGH → 标记 blocked，请求用户介入

7.4 修复完成标准

标准	要求
CRITICAL issues	0
HIGH issues	0
MEDIUM issues	允许存在（输出警告）
Synthesis check	无 CRITICAL/HIGH

---

Phase 8：Traceability CSV 生成 + Push to Remote

8.1 生成 impl phase CSV

从 RTL 文件中的 @requirement 注释扫描 REQ_ID，生成 traceability/requirements_matrix.impl.csv：

uv run $PROJECT_SCRIPTS/babel_traceability.py impl
uv run $PROJECT_SCRIPTS/babel_traceability.py src

8.2 唯一性检查

uv run $PROJECT_SCRIPTS/check_req_uniqueness.py --check-deleted

8.3 Push

git push

---

Error Handling

Scenario	Action	Skip?
MAS 文件 < 2	拒绝执行，返回 bb-mas	❌ NO
子模块未完成	禁止父模块	❌ NO
综合检查 CRITICAL	立即修复	❌ NO
端口定义不一致	立即修复	❌ NO
FSM 编码不一致	立即修复	❌ NO
impl-review 执行失败	报告错误，终止	❌ NO
Fix Issues 测试失败	Debug loop (max 5)	❌ NO
Fix Issues 3 轮仍有 CRITICAL/HIGH	Mark blocked, ask user	⚠️ Ask
Debug > 10 still FAIL	Mark blocked, ask user	⚠️ Ask

---

Commit Strategy

Per-module commits（granular for rollback）：

git commit -m "feat({{ MODULE_ID }}): implement {{ MODULE_ID }} RTL

Leaf-to-parent complete
Synthesis check: passed
Checklist: {{ ITEMS_PASSED }}/total"

---

Module Complete Checkpoint

touch {{ CHECKPOINT_DIR }}/{{ MODULE_ID }}.done

写入 progress JSON 到 {{ PROGRESS_DIR }}/{{ MODULE_ID }}.json

---

最终验证清单

• 所有叶子模块 RTL 文件存在
• 端口定义与 MAS.md §2.1 一致
• FSM 状态编码与 FSM.md 一致
• 综合性检查通过（无 CRITICAL/HIGH）
• Testbench 文件存在
• impl-review 无 CRITICAL/HIGH 问题
• frontmatter 格式正确

---

Key Principles

Principle	Level
全程自动执行，不在 phase/batch 间暂停确认	🔴 MANDATORY
叶子优先执行顺序	🔴 MANDATORY
可综合性检查必须通过	🔴 MANDATORY
Gap Analysis + 死代码检测（synthesis）	🔴 MANDATORY
Debug iteration（no skip/bypass）	🔴 MANDATORY
彻底完成，不接受"足够好"	🔴 MANDATORY
同层并行（无冲突）	🟢 RECOMMENDED
冲突检测后再并行	🔴 MANDATORY
Per-module checkpoint	🔴 MANDATORY
Per-module commit	🔴 MANDATORY
Spec snapshot after successful run	🔴 MANDATORY
增量更新 via change detection	🔴 MANDATORY
/compact after each batch	🟡 RECOMMENDED
自动调用 bb-code-review	🔴 MANDATORY
自动修复所有 CRITICAL/HIGH 问题	🔴 MANDATORY

---

Output Structure

PROJECT_DIR/
├── spec_mas/            # INPUT_DIR
├── rtl/                 # OUTPUT_DIR
│   ├── .checkpoint/     # Module checkpoints (.done files)
│   ├── .progress/       # Progress tracking (.json files)
│   ├── .review/         # impl-review output
│   ├── M01/src/         # RTL source files
│   ├── M01/tb/          # Testbench files
│   └── rtl_tree.md      # RTL module tree
└── temp/deleted/        # Archived removed modules

---

参考文档

详见 references/ 目录：

• sv_coding_style.md — SystemVerilog 编码规范
• synthesizable_rules.md — 可综合性指南

项目级 Coding Style 参考：

• wiki/codingstyle/systemverilog_styleguide.md — SystemVerilog Style Guide (systemverilog.io)
• wiki/codingstyle/freescale_verilog_standard.md — Freescale Verilog HDL Coding Standard SRS V3.2

---

辅助脚本

详见 scripts/ 目录：

• synthesis_check.py — 综合性检查

---

常见陷阱

详见 Gotcha/ 目录：

• rtl_pitfalls.md — RTL 编码常见陷阱

---

常见借口（均无效）

Agent 的借口	为什么错
"这个模块很简单，不需要 FSM"	没有 FSM 意味着状态逻辑隐藏，调试困难
"initial 块只是用来初始化寄存器"	综合工具忽略 initial，仿真与综合不一致
"delay 语句用于仿真调试"	delay 导致仿真时序与实际硬件不一致
"先写 RTL，再回过头补充 testbench"	无 testbench 无法验证功能正确性
"父模块可以先写，子模块并行实现"	父模块端口连接依赖子模块接口定义
"只有一个 latch 问题不大"	锁存器会导致时序分析和功耗问题

---

Evolution Trigger Point

When any Phase fails or user triggers /evolve:

1. Detect failure: Read {{ OUTPUT_DIR }}/execution.log
2. Invoke framework:

   bash {{ EVOLUTION_FRAMEWORK }}/evolve.sh \
     --skill "{{ SKILL_FILE }}" \
     --output "{{ OUTPUT_DIR }}" \
     --failure-phase "{{ FAILED_PHASE }}"
   

3. Framework handles: Analyze, modify, validate, rollback
4. Retry or escalate