ralph-flow-pi 0.1.0

package/skills/c-to-rust-implement/references/c-to-rust-patterns.md

@@ -0,0 +1,86 @@
+# C→Rust 惯用模式转换表
+
+C 语义到 Rust 惯用模式的专家级对照。实现 C 到 Rust 翻译时的权威参考。
+
+## 内存管理
+
+| C 模式 | Rust 翻译 | 说明 |
+|--------|----------|------|
+| `T* p = malloc(n * sizeof(T))` | `let p: Vec<T> = vec![T::default(); n]` 或 `Vec::with_capacity(n)` | Vec 管理堆内存 |
+| `free(p)` | 让 `Drop` 自动处理——返回有主类型，不存裸指针 | 析构自动调用 |
+| `memcpy(dst, src, n)` | `dst[..n].copy_from_slice(&src[..n])` | 前提：dst/src 是切片 |
+| `memset(p, 0, n)` | `p[..n].fill(0)` | 或直接用 `vec![0u8; n]` |
+| `realloc(p, new_sz)` | 新建 Vec，复制旧内容，丢弃旧 | 在安全 Rust 中无直接等价物 |
+| `memcmp(a, b, n)` | `a[..n] == b[..n]` | 切片比较，短路求值 |
+
+## 错误处理
+
+| C 模式 | Rust 翻译 | 说明 |
+|--------|----------|------|
+| `return -1` / `return ERR_CODE` | `Err(Error::ErrCode)` | 枚举变体对应错误码 |
+| `if (ret < 0) goto cleanup` | `let result = fallible_op()?;` | `?` 操作符自动传播错误 |
+| `errno = EINVAL` | `Err(Error::InvalidInput { details })` | 带上下文 |
+| 出参传错误 `int* err` | 返回 `Result<T, Error>`，无出参 | 多返回值用元组 |
+| `goto cleanup` 集中清理 | RAII：`Drop` 处理清理 | 作用域退出自动执行 |
+
+## 数据结构
+
+| C 模式 | Rust 翻译 | 说明 |
+|--------|----------|------|
+| 柔性数组 `struct { int len; T data[]; }` | `struct { data: Vec<T> }` | len 由 `data.len()` 派生 |
+| 标签联合 `struct { int type; union { A a; B b; }; }` | `enum { VariantA(A), VariantB(B) }` | 穷尽匹配，无隐式 fallthrough |
+| 链表 `struct node { T data; node* next; }` | `std::collections::LinkedList<T>` 或 `Vec<T>` | 大多数情况 Vec 更高效 |
+| 不透明句柄 `typedef struct ctx ctx_t;` | `pub struct Ctx { /* 私有字段 */ }` + `impl Ctx` | 封装 |
+| 位域 `struct { unsigned flag : 1; }` | `bitflags` crate 或手动位运算 + 命名常量 | Rust 无原生位域 |
+
+## 控制流
+
+| C 模式 | Rust 翻译 | 说明 |
+|--------|----------|------|
+| `for (int i = 0; i < n; i++)` | `for item in &slice` 或 `for (i, item) in slice.iter().enumerate()` | 迭代器 |
+| `while (*p != '\0') p++` | `s.find('\0')` 或 `s.bytes().position(\|b\| b == 0)` | 不用手动推进指针 |
+| `switch(val) { case X: ... }` | `match val { X => ..., Y => ... }` | 穷尽匹配，无 fallthrough |
+| 函数指针表 / vtable | `trait` + `Box<dyn Trait>` 或 `enum` 分发 | trait 更安全 |
+| `goto` 错误处理 | RAII + `?` 操作符 | Rust 无 goto |
+
+## 并发与状态
+
+| C 模式 | Rust 翻译 | 说明 |
+|--------|----------|------|
+| `static mut STATE: T` | `static STATE: OnceLock<Mutex<T>>` | 线程安全全局状态 |
+| `pthread_mutex_lock/unlock` | `std::sync::Mutex<T>` 的 `.lock().unwrap()` | 自动释放 |
+| 线程局部 `__thread T x` | `std::cell::RefCell` + `thread_local!` 宏 | 线程局部可变 |
+| 一次性初始化 `if (!init) { init(); init=1; }` | `OnceLock::get_or_init(\|\| { ... })` | 线程安全 |
+
+## 转换示例
+
+```rust
+// C 源码:
+// int codec_encode(const uint8_t* in, size_t in_len, uint8_t* out, size_t* out_len) {
+//     if (!in || !out || !out_len) return CODEC_ERR_INVALID;
+//     if (*out_len < in_len + 4) return CODEC_ERR_OVERFLOW;
+//     // ... 编码逻辑 ...
+//     *out_len = encoded_len;
+//     return 0;
+// }
+
+// Rust 实现：
+pub fn encode(input: &[u8], output: &mut [u8]) -> Result<usize, Error> {
+    // if (!in) → 切片引用不可能为 null（由类型系统保证）
+    if output.len() < input.len() + 4 {
+        return Err(Error::Overflow);
+    }
+    // ... 编码逻辑（原样翻译算法，但用 Rust 语法）...
+    Ok(encoded_len)
+}
+```
+
+## 常见陷阱
+
+- C 的 int 返回 0=成功 / -1=失败 → Rust 的 `Result<(), Error>`
+- C 的 size_t 出参 → Rust 的 `Result<usize, Error>` 直接返回长度
+- C 的 NULL 检查 → Rust 引用不可能为 null，去掉所有 `if (!ptr)` 检查
+- C 的数组 + 长度参数对 → Rust 切片 `&[T]`，长度由 `.len()` 获取
+- C 的 void* 泛型 → Rust 泛型 `<T>` 或 trait bound
+- C 的 #ifdef 条件编译 → Rust 的 `#[cfg(...)]` 或 feature flag
+- C 的宏函数 → Rust 的 `macro_rules!` 或普通泛型函数

package/skills/c-to-rust-implement/references/conditional-compilation.md

@@ -0,0 +1,47 @@
+# 条件编译翻译指南
+
+C 项目中的 `#ifdef` / `#ifndef` / `#if` 翻译为 Rust 的 `#[cfg(...)]` 或 feature flag。
+
+## 简单映射
+
+| C 预处理 | Rust 等价 |
+|----------|----------|
+| `#ifdef _WIN32` | `#[cfg(target_os = "windows")]` |
+| `#ifdef __linux__` | `#[cfg(target_os = "linux")]` |
+| `#ifdef __APPLE__` | `#[cfg(target_os = "macos")]` |
+| `#ifdef __x86_64__` | `#[cfg(target_arch = "x86_64")]` |
+| `#ifdef __aarch64__` | `#[cfg(target_arch = "aarch64")]` |
+| `#ifdef DEBUG` | `#[cfg(debug_assertions)]` |
+| `#ifdef FEATURE_X` | `#[cfg(feature = "x")]` + Cargo.toml `[features]` |
+| `#if !defined(X)` | `#[cfg(not(feature = "x"))]` |
+| `#if defined(A) && !defined(B)` | `#[cfg(all(feature = "a", not(feature = "b")))]` |
+| `#if defined(A) \|\| defined(B)` | `#[cfg(any(feature = "a", feature = "b"))]` |
+| `#else` | 单独的 `#[cfg(not(...))]` 块 |
+| `#if VERSION >= 3` | 无法直接映射——用 feature flag 替代 |
+
+## 多条件互斥编译
+
+C 代码 `#if defined(A) ... #elif defined(B) ... #else ...`：
+
+```rust
+#[cfg(feature = "a")]
+fn platform_impl() { /* A 实现 */ }
+
+#[cfg(all(not(feature = "a"), feature = "b"))]
+fn platform_impl() { /* B 实现 */ }
+
+#[cfg(all(not(feature = "a"), not(feature = "b")))]
+fn platform_impl() { /* 默认实现 */ }
+```
+
+## Feature Flag 声明
+
+在 `Cargo.toml` 中声明：
+```toml
+[features]
+default = []
+a = []
+b = []
+```
+
+**注意**：plan.json 的 api_inventory 会记录条件编译影响哪些函数——实现时确保所有条件路径都有对应的 Rust 分支。

package/skills/c-to-rust-implement/references/crate-reference.md

@@ -0,0 +1,15 @@
+# Rust Crate 速查表
+
+根据 C 模式选择合适的 Rust crate。仅在 C 源码中有对应模式时引入，优先用标准库。
+
+| C 模式 | 推荐 crate | Cargo.toml | 使用场景 |
+|--------|-----------|-----------|---------|
+| 位域/标志位 | `bitflags` | `bitflags = "2"` | `struct { unsigned flag : 1; }` |
+| 安全 transmute | `bytemuck` | `bytemuck = { version = "1", features = ["derive"] }` | 字节流到 struct 的安全转换 |
+| 小数组/VLA | `smallvec` | `smallvec = "1"` | 栈优先的变长数组 |
+| 解析器/编解码 | `winnow` | `winnow = "0.6"` | 逐字节推进的解析循环 |
+| 低级网络 | `socket2` | `socket2 = "0.5"` | socket/bind/accept 等 |
+| FFI 边界 | `libc` | `libc = "0.2"` | 仅在 FFI 边界，包裹在 unsafe 块中 |
+| 零拷贝 | `zerocopy` | `zerocopy = "0.7"` | 从字节切片安全读取 struct |
+
+**原则**：如果 C 项目本身不依赖外部 C 库，优先用标准库——不引入额外依赖。

package/skills/c-to-rust-implement/references/error-strategies.md

@@ -0,0 +1,80 @@
+# Error Type Composition Strategies
+
+Two strategies for composing error types across Rust modules during C-to-Rust translation.
+
+## Strategy A — Layered Error (Recommended for shallow dependency chains)
+
+Each module defines its own `Error` enum. Upper layers compose lower layers via `#[from]`.
+
+**选择条件（满足全部即可选 A）**：
+- 依赖深度 ≤ 3（Error 嵌套从 A→B→C 不超过 3 层）
+- 模块间无同名错误类别（如两个模块都有 `Io(std::io::Error)`）
+- main.rs 不需要统一处理所有错误
+
+```rust
+// src/codec.rs
+#[derive(Error, Debug, PartialEq)]
+pub enum Error {
+    #[error("codec: invalid input")]
+    InvalidInput,
+    #[error("codec: output buffer overflow")]
+    Overflow,
+}
+
+// src/storage.rs — depends on codec
+use crate::codec;
+
+#[derive(Error, Debug, PartialEq)]
+pub enum Error {
+    #[error("storage: IO error: {0}")]
+    Io(String),
+    #[error(transparent)]
+    Codec(#[from] codec::Error),  // transparent forward
+    #[error("storage: data corruption")]
+    Corruption,
+}
+```
+
+`lib.rs` re-exports:
+```rust
+pub use error::Error;
+pub mod codec;
+pub mod storage;
+```
+
+Cross-module `?` operator auto-converts via `#[from]`, no manual `map_err` needed.
+
+## Strategy B — Flat Error (Recommended for deep dependency chains)
+
+When dependency chains are deep or multiple modules share error categories, layered Error nesting becomes verbose. Use a single top-level unified Error:
+
+```rust
+// src/error.rs
+#[derive(Error, Debug)]
+pub enum AppError {
+    #[error("codec: {0}")]
+    Codec(#[from] codec::Error),
+    #[error("storage: {0}")]
+    Storage(#[from] storage::Error),
+    #[error("network: {0}")]
+    Network(#[from] network::Error),
+    #[error("internal: {0}")]
+    Internal(String),
+}
+```
+
+### When to Choose Strategy B (any one condition is sufficient)
+
+- **Dependency depth > 3**（Error 从 A→B→C→D 嵌套超过 3 层时，调用方需写 4+ 层 `map_err`）
+- **Multiple modules share the same error category**（如两个模块都产生 IO/Parse 类错误，用 Flat Error 避免重复定义）
+- **Main.rs / top-level needs to handle all errors uniformly**（统一错误处理，不分模块来源）
+- **Module count > 10**（辅助指标，仅当同时满足前面任一条件时才作为决定因素）
+
+### Decision Table
+
+| 依赖深度 | 同名错误类别 | 模块数 | 推荐策略 |
+|---------|------------|-------|---------|
+| ≤ 3 | 0 | ≤ 10 | Strategy A |
+| ≤ 3 | ≥ 1 | any | Strategy B |
+| > 3 | any | any | Strategy B |
+| any | any | > 10 | 倾向 Strategy B |

package/skills/c-to-rust-implement/references/inline-asm.md

@@ -0,0 +1,37 @@
+# 内联汇编处理策略
+
+C 项目中的内联汇编（`__asm__` / `__asm` / `asm`）需要特殊处理。
+
+## 检测命令
+
+```bash
+grep -rn '__asm__\|__asm\b\|asm[ \t]*(' <source_c_dir>/src/ --include='*.c'
+grep -rn '__asm__\|__asm\b\|asm[ \t]*(' <source_c_dir>/inc/ --include='*.h'
+grep -rn '__asm\b' <source_c_dir>/src/ --include='*.c'  # MSVC 语法
+```
+
+## 评估替代方案（按优先级）
+
+1. **Rust 标准库内联函数**：`std::arch::x86_64::*`（如 `_mm_add_ps`）——稳定、安全
+2. **`core::arch::asm!()` 宏**：需 nightly Rust + `#![feature(asm)]`
+3. **FFI 桥接**：将汇编提取为独立 C 文件，通过 FFI 调用
+
+## asm!() 使用规范
+
+若必须使用 `asm!()`：
+- 包裹在最小 `unsafe` 块中，写清 `// SAFETY:` 注释
+- 汇编操作数约束完整（in/out/lateout/clobber）
+- 在 plan.json 对应模块的 notes 中记录
+- 供 validate Gate 2 审计
+
+## SIMD 优化
+
+若汇编用于 SIMD 性能优化：
+- 优先尝试 `std::simd`（nightly）或 `std::arch` 内联函数
+- 提供纯 Rust fallback：`#[cfg(not(target_feature = "..."))]`
+
+## 标记规则
+
+- plan.json 中对应模块标记 `difficulty: "global"` + `notes: "含内联汇编"`
+- plan.json 的 `inline_asm_modules` 数组包含该模块名
+- `recommended_crates` 中添加 `"asm-shim"` 标记

package/skills/c-to-rust-plan/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: c-to-rust-plan
+description: 分析 C 项目，探测真实布局/测试框架/构建系统，提取 API，划分依赖分层，产出 plan.json、api-inventory.md 和 function-contracts.md。在 c-to-rust 工作流的 analyze 步骤触发。
+---
+
+你是接手一个陌生 C 代码库的工程师。目标：先**探测**项目的真实形态（不要假设目录结构），再产出机器可读的实现计划（plan.json）、人类可读的 API 参考（api-inventory.md）和语义参考（function-contracts.md）。这份计划驱动后续全部步骤：测试基线、TDD 实现顺序、独立审查、最终验收。
+
+## 输入 / 输出
+
+> `<产出目录>` = DO 提示词「产出目录」一节给出的路径（形如 `.ralph-flow/artifacts/<任务摘要>-<后缀>/`）。
+
+- 输入：C 项目路径（source_c_dir）、输出项目名（默认 = 源码目录名 + `_rust`）
+- 输出：
+  - `<产出目录>/plan.json` — 探测结果 + 模块/分层/API/难度/crate
+  - `<产出目录>/api-inventory.md` — 人类可读：每个 C 公开函数 → 拟议 Rust 签名
+  - `<产出目录>/function-contracts.md` — 复杂函数的语义要点，给后续 audit 步骤用
+
+## 核心原则
+
+- **先探测再假设** — 目录布局、测试框架、构建系统都从项目实际情况探测，不硬编码 `src/`、`inc/`、`test_`
+- **头文件是公开 API 的权威来源**；**源文件是内部(static)函数的权威来源**
+- **按内聚性分组** — 共享类型/数据结构的函数归入同一 Rust 模块
+- **简单模块优先** — 无依赖的纯数据变换放 layer 1，先积累惯性
+- **传递闭包** — 递归解析 #include 链构建依赖图
+- **优先标准库** — 能用 std 就不引外部 crate
+
+## 执行流程
+
+所有探测/提取的精确命令见 **[references/detection-commands.md](references/detection-commands.md)**。下面只讲每步要产出什么。
+
+### 1. 探测项目布局（不要假设）
+
+用 find 列出真实的源/头/测试文件位置，归纳出源码目录、头文件目录、测试目录（可能是 `src/`+`include/`、`lib/`、扁平根目录等任意组合），写入 `project_layout`。测试文件特征：在 `test/`、`tests/`、`t/` 目录或文件名含 `test`/`spec`/`check`。
+
+### 2. 探测测试框架（决定 baseline 如何移植测试）
+
+grep 框架特征识别 Unity / CMocka / Check / CuTest / 自定义 main / 朴素 `test_` 约定，写入 plan.json `test_framework`：
+`{ "name": "unity|cmocka|check|cutest|custom|plain", "test_files": [...], "assert_macros": [...], "test_decl_pattern": "...", "runner_entry": "..." }`。
+
+### 3. 探测构建系统（决定如何编译 C 测试）
+
+识别 Makefile / CMake / meson 等，写入 plan.json `build_system`：`{ "type", "build_cmd", "test_cmd", "test_binary", "include_flags", "cc" }`。无构建系统则给出手动编译命令（含正确的 `-I<headerdir>`）。
+
+### 4. 提取公开 API（从头文件）
+
+ctags 主方案 + grep 兜底，对探测到的头文件目录提取每个公开函数：名称、返回类型、参数、错误约定（返回码 / errno / 出参）。额外识别回调签名（函数指针类型）和条件编译块（`#ifdef`/`#if`，记录宏名）。
+
+### 5. 提取内部函数 + 检测高级特性
+
+grep 提取 static 内部函数；检测内联汇编（→ difficulty=global，记入 inline_asm_modules）与 C11/C17 高级特性（_Generic/_Atomic/_Alignas/restrict/setjmp/longjmp/alloca/VLA/volatile/signal）。结果记入每个模块的 `c_advanced_features`（见第 8 步 schema）。
+
+### 6. 构建模块依赖图
+
+按 .c 的 `#include` 关系建有向图：A.c include B.h ⇒ A 直接依赖 B；取传递闭包。
+叶子模块（无人 include 其头）→ layer 1；只依赖 layer 1 → layer 2；以此类推。无环。
+
+### 7. 难度分级 + crate 推荐
+
+| 难度 | C 特征 | 实现顺序 |
+|------|--------|---------|
+| **trivial** | 纯数据变换，无堆分配无状态 | 最先 |
+| **owned** | malloc/free 对，单一所有者 → Box/Vec/Drop | 早期 |
+| **stateful** | init/deinit + 内部状态 → struct+Drop | 中期 |
+| **callback** | 函数指针控制反转 → FnMut/trait 对象 | 后期 |
+| **global** | static 可变 / 内联汇编 → OnceLock/Mutex 或重构 | 最后 |
+
+crate 仅在 C 源码存在对应模式时引入，优先 std：位域→`bitflags`；字节转换→`bytemuck`；小数组/VLA→`smallvec`；解析器→`winnow` 或手写；FFI 边界→`libc`（仅 FFI 用）。
+
+### 8. 写出 plan.json
+
+```json
+{
+  "output_name": "<project>_rust",
+  "output_dir": "<projectDir 下的绝对路径>/<project>_rust",
+  "source_c_dir": "/abs/path/C-project",
+  "c_test_dir": "/abs/path/探测到的测试目录",
+  "project_layout": {
+    "source_dirs": ["src"], "header_dirs": ["include"], "test_dirs": ["tests"]
+  },
+  "test_framework": {
+    "name": "unity", "test_files": ["tests/test_codec.c"],
+    "assert_macros": ["TEST_ASSERT_EQUAL", "TEST_ASSERT_TRUE"],
+    "test_decl_pattern": "void test_<name>(void)", "runner_entry": "RUN_TEST"
+  },
+  "build_system": {
+    "type": "make", "build_cmd": "make clean && make", "test_cmd": "./test_runner",
+    "test_binary": "./test_runner", "include_flags": "-Iinclude", "cc": "gcc"
+  },
+  "layers": [["codec"], ["storage", "network"], ["api"]],
+  "modules": [
+    {
+      "name": "codec", "c_files": ["src/codec.c"], "c_headers": ["include/codec.h"],
+      "target_file": "src/codec.rs", "layer": 1,
+      "depends_on": [], "transitive_depends_on": [],
+      "difficulty": "trivial",
+      "public_functions": ["encode", "decode", "checksum"],
+      "internal_functions": ["validate_header", "calc_padding"],
+      "types": ["codec_ctx_t"],
+      "error_codes": ["CODEC_ERR_INVALID", "CODEC_ERR_OVERFLOW"],
+      "recommended_crates": [],
+      "c_advanced_features": {
+        "has_generic": false, "has_atomic": false, "has_alignas": false,
+        "has_restrict": false, "has_setjmp": false, "has_alloca": false,
+        "has_vla": false, "has_volatile": false, "has_signal": false
+      },
+      "notes": ""
+    }
+  ],
+  "api_inventory": [
+    {
+      "c_name": "codec_encode", "rust_name": "encode",
+      "c_signature": "int codec_encode(const uint8_t* in, size_t in_len, uint8_t* out, size_t* out_len)",
+      "rust_signature": "fn encode(input: &[u8], output: &mut [u8]) -> Result<usize, CodecError>",
+      "module": "codec", "error_variants": ["CodecInvalid", "CodecOverflow"],
+      "condition": null, "notes": "in_len/out_len 由切片长度替代"
+    }
+  ],
+  "conditional_compilation": {
+    "detected_macros": ["_WIN32", "__linux__", "USE_SSL"],
+    "feature_flags": { "use_ssl": { "c_macro": "USE_SSL", "rust_cfg": "feature = \"ssl\"" } }
+  },
+  "inline_asm_modules": [],
+  "completed_modules": []
+}
+```
+
+字段约束：
+- 所有路径绝对路径；`output_dir` 必须在工作区（projectDir）下，确保后续步骤可访问
+- `layers`：数组的数组，下标 0 = layer 1（无依赖），每个模块名恰好出现在一层
+- `depends_on` 只引用更低层（无环）；`transitive_depends_on` 是传递闭包
+- `difficulty` ∈ {trivial, owned, stateful, callback, global}
+- `internal_functions`：该模块全部 static 函数名（可空）
+- `c_advanced_features`：全部字段初始化为布尔
+- `project_layout`、`test_framework`、`build_system` 必须反映**探测结果**，非默认值
+- `completed_modules` 初始化为空数组
+- modules 覆盖每个非测试、非 vendor/third_party 的 .c
+
+### 9. 写出 api-inventory.md
+
+人类可读表格：公开 API 表（C 签名 → Rust 签名 → 错误变体）、内部函数表、推荐 crate 表、依赖分层表。
+
+### 10. 写出 function-contracts.md
+
+对 difficulty 为 **stateful**、**callback**、**global** 的模块中**最有翻译风险的函数**，记录其语义要点。不必逐函数全部记录——关注那些逻辑复杂、有多阶段操作、有非平凡状态转换、或有容易遗漏的错误路径的函数。
+
+对每个记录的函数，包含：
+- **做什么**（一句话）
+- **核心逻辑**（自然的语言描述，不是伪代码）
+- **关键不变性**（该函数保证的、调用方依赖的）
+- **错误/异常分支**（不只是 happy path）
+- **与其他函数的协作**（谁调用它、它调用谁、共享什么状态）
+
+trivial 和 owned 难度的模块通常不需要逐函数记录，模块级概述即可。
+
+这个文件是给后续 audit 步骤用的——让审计师知道 "这个函数应该做什么"，然后去 Rust 实现中验证它确实做了这些。
+
+## 完成标准
+
+- plan.json 合法 JSON，modules 覆盖所有非测试/非 vendor 的 .c
+- 每模块含 public_functions、internal_functions、difficulty、recommended_crates、transitive_depends_on、c_advanced_features
+- plan.json 含 output_name、output_dir(工作区内绝对路径)、source_c_dir、c_test_dir、project_layout、test_framework、build_system、conditional_compilation、inline_asm_modules、completed_modules
+- project_layout/test_framework/build_system 来自真实探测
+- 依赖分层无环，传递闭包正确
+- api-inventory.md 列出所有 C 公开函数及拟议 Rust 签名
+- function-contracts.md 对复杂函数记录了语义要点
+- 三个文件写入 `<产出目录>/`

package/skills/c-to-rust-plan/references/detection-commands.md

@@ -0,0 +1,66 @@
+# 探测命令参考（c-to-rust-plan）
+
+## 目录
+
+- 1. 项目布局探测
+- 2. 测试框架探测
+- 3. 构建系统探测
+- 4. 公开 API 提取（头文件）
+- 5. 内部函数 + 高级特性检测
+
+## 1. 项目布局探测
+
+```bash
+find <source_c_dir> -name '*.c' -not -path '*/vendor/*' -not -path '*/third_party/*' -not -path '*/3rd*/*'
+find <source_c_dir> -name '*.h' -not -path '*/vendor/*' -not -path '*/third_party/*'
+```
+
+由实际结果归纳源码目录、头文件目录、测试目录。布局可能是 `src/`+`include/`、`lib/`、扁平根目录或任意组合。
+测试文件特征：在 `test/`、`tests/`、`t/` 目录，或文件名含 `test`/`spec`/`check`。
+
+## 2. 测试框架探测
+
+```bash
+grep -rln 'unity.h\|UNITY_BEGIN\|RUN_TEST\|TEST_ASSERT' <test_dir>      # Unity
+grep -rln 'cmocka.h\|cmocka_unit_test\|assert_int_equal' <test_dir>    # CMocka
+grep -rln '<check.h>\|START_TEST\|ck_assert' <test_dir>                 # Check
+grep -rln 'CuTest\|CuAssert' <test_dir>                                 # CuTest
+grep -rln 'int main' <test_dir>                                         # 自定义 main + assert()
+grep -rln 'void test_\|static void test_' <test_dir>                    # 朴素 test_ 约定
+```
+
+## 3. 构建系统探测
+
+```bash
+ls <source_c_dir>/{Makefile,makefile,CMakeLists.txt,configure,meson.build,*.mk} 2>/dev/null
+grep -rn 'cc\|gcc\|clang\|-I' <source_c_dir>/Makefile* 2>/dev/null | head
+```
+
+记录 type、build_cmd、test_cmd、test_binary、include_flags（正确的 `-I<headerdir>`）、cc。无构建系统则给手动编译命令。
+
+## 4. 公开 API 提取（头文件）
+
+ctags 主方案（处理函数指针返回值、多行声明），grep 兜底：
+
+```bash
+ctags -x --c-kinds=pf --format=2 <header_dir>/*.h 2>/dev/null   # 函数原型/定义
+ctags -x --c-kinds=stue --format=2 <header_dir>/*.h 2>/dev/null  # struct/typedef/union/enum
+ctags -x --c-kinds=d --format=2 <header_dir>/*.h 2>/dev/null     # 宏常量
+grep -nE '^\s*\w+(\s+\*?\s*\w+)+\([^)]*\)\s*;' <header_dir>/*.h   # grep 兜底
+```
+
+每个公开函数提取：名称、返回类型、参数、错误约定（返回码 / errno / 出参）。
+额外识别回调签名（函数指针类型）和条件编译块（`#ifdef`/`#if`，记录宏名）。
+
+## 5. 内部函数 + 高级特性检测
+
+```bash
+grep -rnE '^\s*static\s+\w+\s+\w+\(' <source_dir>            # static 内部函数
+grep -rn '__asm__\|__asm\b\|\basm[ \t]*(' <source_dir> <header_dir>   # 内联汇编 → difficulty=global
+# C11/C17 特性（Rust 无直接等价，提前发现避免返工）
+grep -rn '_Generic(\|_Atomic\b\|_Alignas\b\|\brestrict\b\|setjmp\|longjmp\|alloca(\|\bvolatile\b\|\bsignal\b' <source_dir> <header_dir>
+grep -rnE '[a-zA-Z_]\s+[a-zA-Z_]+\[[a-zA-Z_]+\]\s*;' <source_dir>     # 变长数组 VLA
+```
+
+每个特性结果记入模块 `c_advanced_features` 的对应布尔字段：
+has_generic / has_atomic / has_alignas / has_restrict / has_setjmp / has_alloca / has_vla / has_volatile / has_signal。

package/skills/c-to-rust-test-gen/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: c-to-rust-test-gen
+description: 创建 C-to-Rust 迁移的 TDD 红阶段基线：Rust binary 骨架、API 桩、按 C 测试框架移植全部测试、属性测试。在 c-to-rust 工作流的 baseline 步骤触发。
+---
+
+你在搭 TDD 的红阶段。产出一个 Rust 项目：每个 C 测试都有对应的 Rust `#[test]`，所有 API 桩编译通过，测试因 `todo!()` 而运行时失败。这个基线是**契约**——实现正确时测试自动转绿。
+
+## 输入 / 输出
+
+> `<产出目录>` = DO 提示词「产出目录」一节给出的路径（形如 `.ralph-flow/artifacts/<任务摘要>-<后缀>/`）。
+
+- 输入：`plan.json`（含 project_layout、test_framework、build_system）、C 源码与测试
+- 输出：
+  - `<output_name>_rust/` — Cargo binary 项目：`src/main.rs`、`src/lib.rs`、`src/types.rs`（完整定义）、
+    `src/error.rs`、`src/<module>.rs`（桩）、`tests/oracle_*.rs`、`tests/prop_*.rs`
+  - 状态：`cargo build` 通过，`cargo test` 有 FAILED（红阶段，todo!() panic）
+
+## 核心原则（superpower TDD）
+
+- **先看 C 测试变绿** — 移植前用 build_system 跑通 C 测试套件；红阶段的"红"必须来自我们的 Rust 桩，不是来自坏掉的 C 基线
+- **100% 测试覆盖移植** — 每个 C 测试用例 → 一个 Rust `#[test]`，断言含义逐一保留
+- **API 签名在此确定** — 桩签名是给实现阶段的契约。若实现中发现签名确需调整，那是正常工程演进，直接改签名并同步更新依赖它的测试与 plan.json（不必推倒重来）
+- **错误路径必须测** — 每个 Err 变体都有触发场景
+- **属性测试兜底** — 对数据变换函数用 roundtrip/确定性/空输入不崩溃做 proptest；对有状态 API 用操作序列状态机保证不 panic
+
+## 执行流程
+
+复制此清单并随进度勾选：
+
+```
+RED 基线进度：
+- [ ] 1. C 测试套件确认全绿
+- [ ] 2. cargo new binary 项目，Cargo.toml 配好依赖
+- [ ] 3. types.rs / error.rs 完整定义；lib.rs 声明全部模块
+- [ ] 4. 每个公开函数 + internal_function 建 todo!("module::fn") 桩
+- [ ] 5. 按框架移植全部 C 测试 → oracle_*.rs（断言精度保留）
+- [ ] 6. 补属性测试 prop_*.rs
+- [ ] 7. 验证红阶段：cargo build 通过、cargo test FAILED、桩数≥函数数
+```
+
+### 1. 确认 C 测试套件全绿
+
+用 plan.json `build_system` 的命令编译并运行 C 测试：
+
+```bash
+cd <source_c_dir>
+<build_cmd> && <test_cmd>; echo "exit=$?"
+```
+
+退出码必须为 0。若不通过：先修 C 项目，或在 plan.json 标注排除的损坏测试（记 notes）。
+
+### 2. 初始化 Rust binary 项目
+
+```bash
+cargo new <output_name>_rust            # 在工作区内，cargo 会自动 git init
+cd <output_name>_rust
+```
+
+`Cargo.toml`：
+```toml
+[package]
+name = "<output_name>_rust"
+edition = "2021"
+
+[dependencies]
+thiserror = "1"
+# 仅在 plan.json recommended_crates 出现时才加（bitflags/bytemuck/smallvec/...）
+
+[dev-dependencies]
+proptest = "1"
+rstest = "0.18"
+```
+
+`src/main.rs`：薄入口，解析 `--help` 与子命令，转调 lib。
+`src/lib.rs`：`pub mod` 声明 plan.json 的全部模块。
+
+### 3. 定义共享类型与错误（完整，非桩）
+
+- `src/types.rs`：把头文件中跨模块共享的 struct/enum 翻译成完整 Rust 定义。模块私有类型放各自模块文件。
+- `src/error.rs`：从 plan.json `api_inventory[].error_variants` 汇总，thiserror 派生：
+
+```rust
+use thiserror::Error;
+#[derive(Error, Debug, PartialEq)]
+pub enum AppError {
+    #[error("codec: invalid input")] CodecInvalid,
+    #[error("codec: output buffer overflow")] CodecOverflow,
+    // 每个 C 错误码一个变体
+}
+```
+
+### 4. 创建 API 桩
+
+每个模块 `src/<module>.rs`：用 plan.json `api_inventory[].rust_signature` 写正确签名，函数体 = `todo!("<module>::<fn>")`。internal_functions 同样建桩。桩签名是契约。
+
+### 5. 按测试框架移植 C 测试
+
+读 plan.json `test_framework`，把每个 C 测试用例映射成 `tests/oracle_<module>.rs` 里的 `#[test]`。
+各框架的用例声明、断言宏，以及"断言语义精确归一表"（精度不降级）见
+**[references/test-porting.md](references/test-porting.md)**。
+错误路径：对每个 error_variant，确认至少一个测试触发它。
+
+### 6. 属性测试
+
+`tests/prop_<module>.rs`：数据变换函数 → roundtrip / 确定性 / 空输入不崩溃；有状态 API → 操作序列状态机 proptest（保证不 panic）。
+模板与模式见 **[references/proptest-patterns.md](references/proptest-patterns.md)**。
+
+### 7. 验证红阶段状态
+
+```bash
+cargo build      # 必须通过——所有桩编译
+cargo test 2>&1  # 必须出现 FAILED——红阶段（todo!() panic，不是编译错误）
+
+# 红阶段完整性：桩数 ≥ 函数数
+TODO_COUNT=$(grep -rc 'todo!' src/ --include='*.rs' | awk -F: '{s+=$2} END{print s}')
+FUNC_COUNT=$(jq '[.api_inventory|length] + [.modules[].internal_functions|length] | add' <产出目录>/plan.json)
+echo "stubs=$TODO_COUNT funcs=$FUNC_COUNT"   # 需 TODO_COUNT >= FUNC_COUNT
+```
+
+若 `cargo test` 全绿，说明桩写错了（应有 `todo!()`）。每个 `todo!()` 必须含 `"module::fn"` 标签便于实现阶段定位。
+
+## 完成标准
+
+- `cargo build` 通过；`cargo test` 有 FAILED（todo!() panic，非编译错误）
+- Cargo.toml 是 binary target，含 thiserror + proptest/rstest
+- `src/main.rs`、`src/lib.rs`（声明全部模块）、`src/types.rs`（字段完整）、`src/error.rs` 存在
+- 每个 C 测试用例都有对应 Rust `#[test]`，断言精度保留
+- `TODO_COUNT >= FUNC_COUNT`，每个 `todo!()` 含 `module::fn` 标签
+- 每个公开函数至少被一个 oracle 或 property 测试覆盖；每个 error_variant 至少有一个触发测试
+- 每个模块有对应的 `tests/oracle_<module>.rs` 和 `tests/prop_<module>.rs`