tirtc-device-builder 0.4.0 → 0.6.0

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Codex workflows for building and validating TiRTC device firmware across supported chip platforms.",
   "author": {
     "name": "TangeAI",

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 This project follows Semantic Versioning.
 
+## 0.6.0
+
+- Add project-local audio and video semantic contracts that verify codec clock tables, I2S/TDM topology, selected video framing, dependency locks, scheduler isolation, sensor policy, and memory/backpressure before an artifact can reach `BUILD_VERIFIED`.
+- Require build assessment hashes to match `build_evidence.artifacts[]`, and propagate requested-feature failures to the project gate without downgrading an existing `BLOCKED` result.
+- Add portable CMake gate installers, source-export checks, a clean-room LCKFB ESP32-S3 prompt, and regression coverage for MJPEG, H.264, and H.265 video contracts.
+- Distinguish compiler success from capability verification and document source-only transfer to another machine.
+
+## 0.5.0
+
+- Split Hardware IR assessment into explicit `intake`, `build`, and `hil` phases so implementation- and build-resolvable facts do not require runtime proof before adapter work begins.
+- Add `BUILD_VERIFIED` with exact artifact SHA-256 binding, while keeping L5/L6 runtime evidence exclusive to `HIL_VERIFIED`.
+- Classify unresolved facts by their next evidence source and stop pre-build work only for facts that genuinely require user input, unavailable hardware/SDK, or a public-contract decision.
+- Update the developer intake prompt and reporting guidance so missing serial access produces L2-L7 `SKIP` results without blocking L0/L1.
+- Add phase regression coverage while retaining schema v1 compatibility and independent MJPEG, H.264, and H.265 profile validation.
+
 ## 0.4.0
 
 - Add Hardware IR v2 with selected MJPEG, H.264, or H.265 video profiles while retaining schema v1 compatibility.

package/README.md

@@ -70,7 +70,7 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 
 ### 4. 把板卡和目标告诉 Codex
 
-把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。路径请使用绝对路径，不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
+把你已经掌握的信息填进下面的提示词即可，不用先查齐所有硬件参数。先指定工作区根目录，本地路径尽量相对工作区填写；不确定的内容写“未知”。可直接复制的版本见[开发板接入提示词](skills/tirtc-esp32-builder/assets/developer-intake-prompt.md)。
 
 ```text
 请使用 $tirtc-esp32-builder 完成这块开发板的 TiRTC 移植。
@@ -79,6 +79,8 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 - 厂商、完整型号、PCB/硬件版本：<填写>
 - 资料与手中实物是否对应：<是/否/未知>
 
+工作区：<本机目录；以下本地路径均相对此目录>
+
 资料：
 - <原理图、BSP/厂商示例、数据手册或产品页；一行一个>
 
@@ -88,10 +90,10 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 - Wi-Fi：<指定方案/根据 BSP 选择>
 - 设备绑定：<指定方案/根据平台合同选择>
 
-工程：<输出目录或现有工程的绝对路径>
+工程：<输出目录或现有工程的工作区相对路径>
 
-请先运行 Doctor，分析全部资料并生成 Hardware IR v2。资料不足时列出最小补充项；达到 READY_TO_PORT 后再生成、适配和编译，并输出 TIRTC_PORTING_REPORT.md。
-本轮不访问串口、不烧录、不擦除 NVS，也不要把任何凭证写入源码或报告。
+请先运行 Doctor，分析全部资料并生成 Hardware IR v2。把未知项区分为可由资料、实现、构建或 HIL 解决，以及必须由用户补充的阻塞项。READY_TO_PORT 表示资料足以开始设计，不要求最终 ELF；随后生成、适配和编译，运行项目内音视频语义门禁，把 artifact SHA-256 写入 build_evidence 后执行 build 阶段评估，并输出 TIRTC_PORTING_REPORT.md。
+本轮不访问串口、不烧录、不擦除 NVS；缺少串口只让 L2-L7 记为 SKIP，不得阻止 L0/L1。不要把任何凭证写入源码或报告。
 ```
 
 手头只有型号也可以开始：
@@ -450,26 +452,34 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py init \
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py validate \
   /absolute/path/hardware-ir.json
 
-python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess --strict \
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
+  --phase intake --strict \
   /absolute/path/hardware-ir.json
 ```
 
-能力门禁有四种状态：
+能力门禁有五种状态：
 
 | 状态 | 含义 | 怎么处理 |
 |---|---|---|
-| `NEEDS_CONFIRMATION` | 关键事实未知、冲突或只有单一来源 | 补原理图、BSP、数据手册或实测证据 |
+| `NEEDS_CONFIRMATION` | 当前阶段的关键事实未知、冲突或证据等级不足 | 按资料、实现、构建、HIL 或用户输入来源继续闭环 |
 | `BLOCKED` | 现有硬件或 SDK 已确认不满足 | 更换硬件，补编码/播放路径，或取得匹配 SDK |
 | `READY_TO_PORT` | 资料足以开始生成和板级实现 | 进入工程生成与编译 |
+| `BUILD_VERIFIED` | 精确 artifact 通过源码、音视频语义、编译和 post-link 门禁 | 记录 BIN/ELF SHA-256；按授权进入实机验收 |
 | `HIL_VERIFIED` | 已完成端到端实机验证 | 固定版本并保存证据 |
 
 `assess --strict` 在条件不足时返回非零，这是门禁在阻止过早生成，不代表脚本损坏。
 
-Hardware IR v2 只有在运行证据绑定到同一固件 SHA-256 时才会给出 `HIL_VERIFIED`：
+构建后运行 build 阶段；只有运行证据绑定到同一固件 SHA-256 时，hil 阶段才会给出 `HIL_VERIFIED`：
 
 ```bash
 python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
   /absolute/path/hardware-ir.json \
+  --phase build --project /absolute/path/generated-project \
+  --artifact-sha256 <64-character-sha256> --strict
+
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/hardware_ir.py assess \
+  /absolute/path/hardware-ir.json \
+  --phase hil \
   --artifact-sha256 <64-character-sha256> --strict
 ```
 
@@ -496,14 +506,19 @@ python3 ~/.codex/skills/tirtc-esp32-builder/scripts/doctor.py \
   --project /absolute/path/my-esp32-device
 ```
 
-`TiRTC build contract` 为 `PASS` 后编译：
+`TiRTC build contract` 为 `PASS` 后，先执行 `idf.py reconfigure` 锁定依赖。根据 [音频合同](skills/tirtc-esp32-builder/references/audio-contract.md) 和 [视频合同](skills/tirtc-esp32-builder/references/video-contract.md) 生成、核验并安装请求能力对应的项目内门禁，再编译：
 
 ```bash
 cd /absolute/path/my-esp32-device
 idf.py set-target esp32s3
+idf.py reconfigure
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/install_audio_gate.py .
+python3 ~/.codex/skills/tirtc-esp32-builder/scripts/install_video_gate.py .
 idf.py build
 ```
 
+只安装实际请求能力的门禁。编译后把 BIN/ELF 的路径、大小和 SHA-256 写入 Hardware IR 的 `build_evidence.artifacts[]`，再运行 build 阶段评估。编译成功但语义门禁缺失或失败时只能记录 `COMPILE_PASS / CAPABILITY_BLOCKED`。
+
 生成器会把 TiRTC SDK 复制到工程的 `third_party/tirtc/`。此后工程不再依赖 `tirtc-server-example`，但换机编译仍需准备兼容的 ESP-IDF 5.5.x 工具链。
 
 检查尚未完成的产品适配点：
@@ -599,7 +614,7 @@ Wi-Fi 配网和 ThingConnect 设备绑定是两套独立流程。绑定可以选
 |---|---|
 | L-1 Environment | Doctor 必需项和项目构建契约通过 |
 | L0 Generate | 新工程和 Hardware IR 存在，没有覆盖旧目录 |
-| L1 Build | `idf.py build` 成功，固件和 SHA-256 已记录 |
+| L1 Build | 请求能力的语义门禁与 `idf.py build` 均成功，固件和已登记 SHA-256 通过 build assessment |
 | L2 Boot | 指定串口烧录成功，无 panic 或反复重启 |
 | L3 Online | 所选 Wi-Fi 凭证和设备绑定流程、MQTT 与 TiRTC 就绪 |
 | L4 Media | 摄像头、麦克风、扬声器的本地路径和计数正常 |
@@ -620,6 +635,8 @@ Wi-Fi 配网和 ThingConnect 设备绑定是两套独立流程。绑定可以选
 
 任务只做到生成和编译时，报告应明确停在 L1。
 
+换机前先创建排除 `build/`、`managed_components/` 和 `.git` 的源码交付副本，再运行 `project_portability.py <source-only-export> --export`。只交付源码、依赖锁和工程内 TiRTC SDK，不携带包含原机器绝对路径的构建缓存。
+
 ## 常见问题
 
 ### 找不到 `node`、`npm` 或 `npx`
@@ -750,7 +767,7 @@ WSL 默认不一定能看到 USB 设备。按 [Microsoft WSL USB 连接说明](h
 
 ### Hardware IR 一直是 `NEEDS_CONFIRMATION`
 
-先查看各个未知项要求什么来源。常见缺口包括准确的 PCB 版本、摄像头数据格式、所选视频 profile 的完整输出路径、Codec 时钟、功放使能脚、配网方法和可工作的厂商示例。不要从相似开发板复制管脚来填补这些信息。
+先确认当前运行的是 intake、build 还是 hil 阶段，再标记每个未知项的下一证据来源。资料/固定源码可解决的事实继续检查；adapter 或 ELF 可解决的事实进入对应实现/构建层；运行指标留到 HIL。只有准确 PCB 版本、关键连接、器件身份、产品合同或不可用 SDK 等无法安全推导的事实需要用户补充。不要从相似开发板复制管脚来填补这些信息。
 
 ### 工程能编译，浏览器没有画面
 
@@ -874,8 +891,8 @@ gh release create kit-esp32s3-v1.0.0 \
 
 ```bash
 npm test
-git tag -a v0.4.0 -m "v0.4.0"
-git push origin v0.4.0
+git tag -a v0.6.0 -m "v0.6.0"
+git push origin v0.6.0
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {

package/skills/tirtc-esp32-builder/SKILL.md

@@ -14,24 +14,30 @@ Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware
 3. Run the Doctor through the managed environment helper when one exists; otherwise run `python3 <skill-dir>/scripts/doctor.py --expected-idf 5.5 --target esp32s3`. Add `--require-workspace` when generation or repository reference documents are needed; a self-contained generated project can instead resolve its bundled SDK through `--project`. Resolve every required failure before claiming build readiness.
 4. Read [workflow.md](references/workflow.md). Select the registered-board, new-board intake, or existing-project branch. The branch is selected when every supplied artifact has been accounted for and the exact board revision is known or explicitly unresolved.
 5. Read [hardware-ir.md](references/hardware-ir.md) when a Hardware IR must be created or updated. New intake uses schema v2; schema v1 remains readable for existing H.264 projects. Record a source and verification level for every hardware fact that affects a requested feature.
-6. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --strict`. Generation may proceed for a requested feature only when it is `READY_TO_PORT` or `HIL_VERIFIED`; otherwise report the exact missing evidence and continue with safe discovery or scaffolding only.
+6. Run `python3 <skill-dir>/scripts/hardware_ir.py validate <hardware-ir.json>` and then `assess --phase intake --strict`. `READY_TO_PORT` means the evidence is sufficient to design the adapter without guessing wiring or changing an unapproved public contract; it does not require a final ELF or runtime measurements.
+
+Before stopping on `NEEDS_CONFIRMATION`, classify every unresolved fact as `source_resolvable`, `implementation_resolvable`, `build_resolvable`, `hil_resolvable`, or `user_blocked`. Resolve source facts by inspection. For implementation/build facts, record the evidenced design plan at `corroborated`, generate a compile-safe adapter, and verify it at L1. Defer HIL-only measurements to L2-L7 when hardware access is unavailable. Stop before implementation only for `user_blocked` facts such as unknown wiring or identity, a missing product choice, an unavailable SDK, or a required public-contract change.
 
 ## Build the project
 
 Run `<device-kit-root>/device-sim/scripts/create_esp32_project.py` for the current ESP32-S3 H5/AI starter. Keep ThingConnect onboarding, H5, AI, TiRTC lifecycle, callback, stream, and generation behavior in the existing deep modules. Put board-specific camera, microphone, encoder, codec, amplifier, GPIO, DMA, and task behavior behind the `starter_media` seam or a board media adapter owned by it.
 
-Before changing media code, read [capability-rules.md](references/capability-rules.md) and [porting-risks.md](references/porting-risks.md), then read the repository documents they route to. A camera sensor alone does not establish H5 video support; validate the user-selected MJPEG, H.264, or H.265 profile end to end. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
+Before changing media code, read [capability-rules.md](references/capability-rules.md) and [porting-risks.md](references/porting-risks.md), then read the repository documents they route to. For requested audio, read [audio-contract.md](references/audio-contract.md); for requested video, read [video-contract.md](references/video-contract.md). Complete every applicable project-local semantic gate. A camera sensor alone does not establish H5 video support; validate the selected MJPEG, H.264, or H.265 profile end to end. Choose half duplex for AI when the supplied hardware and BSP do not establish a usable full-duplex/AEC path.
 
 Keep the Skill board-agnostic. The prompt supplies product intent and artifact locations; Hardware IR stores evidence; the generated board adapter owns concrete sensors, codecs, pins, clocks, slots, DMA, and task allocation. Never add one board's values to Skill defaults to make an assessment pass.
 
-Run focused tests before ESP-IDF build. Resolve the TiRTC SDK target and `manifest/build-contract.env` against the generated `sdkconfig`; a mismatched precompiled SDK is a blocked build, not a code-generation problem.
+Run focused tests before ESP-IDF build. Resolve the TiRTC SDK target and `manifest/build-contract.env` against the generated `sdkconfig`; a mismatched precompiled SDK is a blocked build, not a code-generation problem. Resolve managed components with `idf.py reconfigure`, then validate and install every applicable audio/video contract gate. A value copied from a “typical” header comment or a different sample rate is not clock evidence. A self-declared camera realtime or memory boolean is not video evidence.
+
+After a successful build, promote only facts actually established by source, compile, semantic, or post-link gates to `build_verified`. Hash the exact BIN/ELF, record that exact hash under `build_evidence.artifacts[]`, and run `hardware_ir.py assess --phase build --project <project> --artifact-sha256 <sha256> --strict`. The assessment must reject a well-formed but unrecorded hash. A design plan at `corroborated` can pass intake but cannot pass the build phase. Report a successful compiler invocation as `COMPILE_PASS` when any requested feature gate is blocked; project-wide `BUILD_VERIFIED` requires every requested feature to pass.
 
 ## Flash and verify
 
 Flash only when the user requested hardware mutation and the exact serial port and chip have been resolved. When more than one candidate device exists, obtain the target choice before writing. Keep credentials outside generated files and redact device keys, Wi-Fi passwords, MQTT/WHIP tokens, and user media from logs and reports.
 
-Read [reporting.md](references/reporting.md) before end-to-end verification. Report every acceptance level as `PASS`, `FAIL`, or `SKIP`, with commands and evidence. Bind HIL observations to the exact firmware SHA-256 with `assess --artifact-sha256`; an older artifact cannot verify a newer build. A build-only result is not H5 or AI completion; missing hardware, browser, account, service, or network evidence remains an explicit `SKIP` or blocker.
+Read [reporting.md](references/reporting.md) before end-to-end verification. Report every acceptance level as `PASS`, `FAIL`, or `SKIP`, with commands and evidence. Bind HIL observations to the exact firmware SHA-256 with `assess --phase hil --artifact-sha256`; an older artifact cannot verify a newer build. A build-only result is not H5 or AI completion; missing hardware, browser, account, service, or network evidence remains an explicit `SKIP` or blocker.
+
+For HIL assessment, run `hardware_ir.py assess --phase hil --artifact-sha256 <sha256> --strict`. The HIL phase first requires build-verified paths, then promotes only features whose L5/L6 runtime evidence matches that exact artifact.
 
 ## Finish
 
-Return the generated project path, Hardware IR, capability assessment, build artifacts, flash record when applicable, and `TIRTC_PORTING_REPORT.md`. The task is complete only when every requested feature is either verified at the requested level or named as a blocker with the smallest next action that can resolve it.
+Run `project_portability.py <project> --export` against the source-only deliverable; do not ship a machine-bound `build/` tree. Return the generated project path, Hardware IR, capability assessment, build artifacts, flash record when applicable, and `TIRTC_PORTING_REPORT.md`. The task is complete only when every requested feature is either verified at the requested level or named as a blocker with the smallest next action that can resolve it.

package/skills/tirtc-esp32-builder/USAGE.md

@@ -25,7 +25,7 @@ $tirtc-esp32-builder
 Wi-Fi 与设备绑定：<指定方案/根据 BSP 和平台合同选择>
 工程：<输出目录或现有工程的绝对路径>
 
-先运行 Doctor，再生成 Hardware IR v2。达到 READY_TO_PORT 后完成板级适配和编译，输出 TIRTC_PORTING_REPORT.md。
+先运行 Doctor，再生成 Hardware IR v2。READY_TO_PORT 只表示资料足以设计板级适配；随后完成适配和编译，以精确 artifact SHA-256 运行 build 阶段评估并输出 TIRTC_PORTING_REPORT.md。
 本轮不访问串口、不烧录、不擦除 NVS，也不把凭证写入源码或报告。
 ```
 
@@ -92,10 +92,14 @@ python3 <skill-dir>/scripts/doctor.py \
 ```bash
 python3 <skill-dir>/scripts/hardware_ir.py init /tmp/hardware-ir.json
 python3 <skill-dir>/scripts/hardware_ir.py validate /tmp/hardware-ir.json
-python3 <skill-dir>/scripts/hardware_ir.py assess --strict /tmp/hardware-ir.json
+python3 <skill-dir>/scripts/hardware_ir.py assess --phase intake --strict /tmp/hardware-ir.json
+python3 <skill-dir>/scripts/hardware_ir.py assess --phase build \
+  --artifact-sha256 <64-character-sha256> --strict /tmp/hardware-ir.json
+python3 <skill-dir>/scripts/hardware_ir.py assess --phase hil \
+  --artifact-sha256 <64-character-sha256> --strict /tmp/hardware-ir.json
 ```
 
-`init` 默认创建 schema v2；v1 仅用于兼容已有 H.264 IR。`BLOCKED` 表示资料已确认硬件/合同/资源或凭证策略不满足；`NEEDS_CONFIRMATION` 表示仍有未知项或只有单一来源；`READY_TO_PORT` 表示可以生成并实现板级适配；`HIL_VERIFIED` 还要求 `--artifact-sha256` 匹配该固件的 L5/L6 运行证据。
+`init` 默认创建 schema v2；v1 仅用于兼容已有 H.264 IR。`BLOCKED` 表示资料已确认硬件/合同/资源或凭证策略不满足；`NEEDS_CONFIRMATION` 表示当前阶段仍有未知项或证据不足；`READY_TO_PORT` 表示可以生成并实现板级适配；`BUILD_VERIFIED` 表示精确 artifact 已通过源码、编译和 post-link 门禁；`HIL_VERIFIED` 还要求同一 SHA-256 的 L5/L6 运行证据。
 
 ## 当前边界
 

package/skills/tirtc-esp32-builder/assets/board-audio-contract.example.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": 1,
+  "evidence": [
+    "exact-board-schematic",
+    "official-codec-datasheet",
+    "official-board-peripheral-example"
+  ],
+  "clock": {
+    "sample_rate_hz": 8000,
+    "mclk_ratio": 512,
+    "mclk_hz": 4096000,
+    "codec_tables": [
+      {
+        "codec": "ES7210",
+        "source": "managed_components/espressif__es7210/es7210.c"
+      },
+      {
+        "codec": "ES8311",
+        "source": "managed_components/espressif__es8311/es8311.c"
+      }
+    ]
+  },
+  "capture": {
+    "controller": 0,
+    "role": "master",
+    "mode": "tdm",
+    "tdm_enabled": true,
+    "slot_count": 4,
+    "slot_order": ["CH1", "CH3", "CH2", "CH4"],
+    "slot_signals": ["MIC1", "PLAYBACK_REFERENCE", "MIC2", "GROUND"],
+    "selected_slot": 0,
+    "selected_signal": "MIC1",
+    "mapping_evidence": "ES7210 Rev 9.1 Figure 2e plus the exact PCB schematic"
+  },
+  "playback": {
+    "controller": 1,
+    "role": "master",
+    "mode": "standard"
+  },
+  "shared_clock": {
+    "gpios": [38, 14, 13],
+    "directions_simultaneous": false,
+    "handoff": "release_before_claim"
+  },
+  "implementation_assertions": [
+    {
+      "file": "components/starter_media/src/starter_media.c",
+      "contains": [],
+      "contains_compact": [
+        "#defineAUDIO_SAMPLE_RATE_HZ8000U",
+        "#defineAUDIO_MCLK_MULTIPLE512U",
+        "#defineI2S_CAPTURE_PORTI2S_NUM_0",
+        "#defineI2S_PLAYBACK_PORTI2S_NUM_1",
+        "#defineES7210_MIC1_TDM_INDEX0U",
+        ".flags.tdm_enable=true",
+        "I2S_TDM_SLOT0|I2S_TDM_SLOT1|I2S_TDM_SLOT2|I2S_TDM_SLOT3",
+        "i2s_channel_reconfig_tdm_gpio",
+        "i2s_channel_reconfig_std_gpio"
+      ],
+      "absent": [],
+      "absent_compact": [
+        ".flags.tdm_enable=false"
+      ]
+    }
+  ]
+}

package/skills/tirtc-esp32-builder/assets/board-video-contract.example.json

@@ -0,0 +1,94 @@
+{
+  "schema_version": 1,
+  "evidence": [
+    "lckfb-schematic-v1.0.1",
+    "lckfb-camera-example",
+    "locked-esp32-camera-source",
+    "managed-device-kit-contract"
+  ],
+  "dependencies": {
+    "espressif/esp32-camera": "2.1.7",
+    "idf": "5.5.4"
+  },
+  "scheduler": {
+    "wifi_core": 0,
+    "camera_core": 1,
+    "config_files": [
+      "sdkconfig.defaults",
+      "sdkconfig"
+    ],
+    "wifi_config_files": [
+      "sdkconfig"
+    ]
+  },
+  "camera": {
+    "codec": "mjpeg",
+    "stream_id": 11,
+    "media": "TIRTC_VIDEO_JPEG",
+    "complete_jpeg_per_send": true,
+    "frame_buffers": 2,
+    "accepted_sensor_pids": [
+      155,
+      8517
+    ],
+    "unknown_sensor_policy": "reject"
+  },
+  "memory": {
+    "max_send_buffer_bytes": 262144,
+    "max_complete_jpeg_bytes": 196608,
+    "video_backpressure_bytes": 196608
+  },
+  "implementation_assertions": [
+    {
+      "file": "main/app_main.c",
+      "contains": [],
+      "contains_compact": [
+        ".max_send_buffer_bytes=256U*1024U"
+      ],
+      "absent": [],
+      "absent_compact": [
+        ".max_send_buffer_bytes=1024U*1024U"
+      ]
+    },
+    {
+      "file": "components/starter_media/src/starter_media.c",
+      "contains": [],
+      "contains_compact": [
+        "#defineVIDEO_BACKPRESSURE_BYTES(192U*1024U)",
+        "#defineVIDEO_MAX_COMPLETE_JPEG_BYTES(192U*1024U)",
+        "starter_tirtc_send_buffer_used()>VIDEO_BACKPRESSURE_BYTES",
+        "jpeg_length>VIDEO_MAX_COMPLETE_JPEG_BYTES",
+        "starter_tirtc_send_mjpeg((uint32_t)now_ms,jpeg,jpeg_length)>=0",
+        ".pixel_format=PIXFORMAT_RGB565",
+        ".fb_count=2",
+        "frame2jpg(frame,CAMERA_JPEG_QUALITY,&jpeg,&jpeg_length)"
+      ],
+      "absent": [],
+      "absent_compact": []
+    },
+    {
+      "file": "components/starter_media/include/starter_media_camera_policy.h",
+      "contains": [],
+      "contains_compact": [
+        "returnpid==GC0308_PID||pid==GC2145_PID;"
+      ],
+      "absent": [],
+      "absent_compact": []
+    },
+    {
+      "file": "components/starter_tirtc/src/starter_tirtc.c",
+      "contains": [],
+      "contains_compact": [
+        ".stream_id=H5_VIDEO_STREAM",
+        ".media=TIRTC_VIDEO_JPEG",
+        "jpeg[0]!=0xffU",
+        "jpeg[1]!=0xd8U",
+        "jpeg[length-2U]!=0xffU",
+        "jpeg[length-1U]!=0xd9U",
+        "returnTiRtcSendVideoStream(connection,&frame,data);"
+      ],
+      "absent": [],
+      "absent_compact": []
+    }
+  ]
+}

package/skills/tirtc-esp32-builder/assets/developer-intake-prompt.md

@@ -13,8 +13,11 @@ $tirtc-esp32-builder
 - 厂商、完整型号、PCB/硬件版本：<填写>
 - 资料与手中实物是否对应：<是/否/未知>
 
+工作区：
+- 根目录：<本机路径；以下本地路径均相对此目录>
+
 资料：
-- <原理图、BSP/厂商示例、数据手册、产品页等本地绝对路径或固定链接；一行一个>
+- <原理图、BSP/厂商示例、数据手册、产品页等工作区相对路径或固定链接；一行一个>
 
 目标：
 - <例如：H5 实时视频和声音、H5 语音对讲、AI 双向语音对讲>
@@ -26,14 +29,16 @@ $tirtc-esp32-builder
 - 设备绑定：<选择一种，或写“根据平台合同选择”>
 
 工程：
-- 输出目录或现有工程：<绝对路径>
+- 输出目录或现有工程：<工作区相对路径；Skill 在报告中记录解析后的绝对路径>
 
 执行要求：
 1. 先运行 Device Kit Doctor，读完全部资料，再生成 Hardware IR v2。没有证据的器件、GPIO 和媒体能力保持未知。
-2. 资料不足时，列出矛盾、缺失项和最小补充动作；达到 READY_TO_PORT 后再生成板级 adapter、编译并记录 BIN/ELF SHA-256。
-3. 移植前核对媒体合同、板级资源、内存预算、配网和绑定状态。具体板卡参数只写入该板的 Hardware IR 和 adapter。
-4. 输出 TIRTC_PORTING_REPORT.md，并把编译结果与 L2-L7 实机验收分开记录。
-5. 本轮不访问串口、不烧录、不擦除 NVS。Wi-Fi 密码、设备密钥、token、私钥和用户音视频也不能写入工程或报告。
+2. 把每个未知项标为 source_resolvable、implementation_resolvable、build_resolvable、hil_resolvable 或 user_blocked。先通过资料和固定版本源码解决 source_resolvable；只有 user_blocked 会阻止开始 adapter 开发。
+3. READY_TO_PORT 表示硬件身份、连接、媒体合同和资源设计已经有证据，足以开始实现；它不要求最终 ELF 或实机数据。可通过实现或构建解决的项目必须继续生成 compile-safe adapter、锁定依赖、运行门禁并编译。
+4. 移植前核对媒体合同、板级资源、静态内存预算、配网和绑定状态。音频工程必须生成项目内 `board-audio-contract.json`，在依赖解析后核验每个 codec 的 `(MCLK, sample rate)` 表、I2S mode/controller、TDM slot/物理信号和共享 GPIO handoff；视频工程必须生成项目内 `board-video-contract.json`，核验锁定 camera 组件、传感器白名单、Wi-Fi/camera CPU 隔离、完整帧边界、frame buffers、TiRTC send buffer 和 backpressure。两个门禁都要接入普通 `idf.py build`。`resolved=true`、`pipeline_safe=true` 或编译成功不能替代门禁。
+5. 记录 BIN/ELF 路径、大小和 SHA-256，将所评估的 SHA 写入 Hardware IR 的 `build_evidence.artifacts[]`，再使用 `--project` 运行 build 阶段评估并输出 TIRTC_PORTING_REPORT.md。区分 `COMPILE_PASS`、请求能力 `BUILD_VERIFIED` 和 L2-L7 实机验收。
+6. 本轮不访问串口、不烧录、不擦除 NVS；因此缺少启动、浏览器、实体声音和运行时资源数据时，把相应 L2-L7 标为 SKIP，不得阻止 L0/L1。
+7. Wi-Fi 密码、设备密钥、token、私钥和用户音视频不能写入工程或报告。
 ```
 
 ## 只有已知时才补充
@@ -46,5 +51,6 @@ $tirtc-esp32-builder
 - 凭证保存与重配方式、已有绑定处理和独立清除入口；
 - 已知资料矛盾、实机 PID、串口日志或已知良好固件 SHA-256；
 - 非默认 ESP-IDF、TiRTC SDK、Device Kit、服务发现地址或 HTTP/HTTPS 分阶段要求。
+- 若用于 clean-room 验证，明确允许的资料根目录，并列出不得读取的历史工程或旧 artifact。
 
 直接把它们追加在提示词末尾即可，不必逐项填表。

package/skills/tirtc-esp32-builder/assets/hardware-ir-v2.example.json

@@ -75,6 +75,8 @@
       "controller_and_gpio_ownership_resolved": null,
       "verification": "extracted"
     },
+    "audio_semantic_contract": "board-audio-contract.json",
+    "video_semantic_contract": "board-video-contract.json",
     "audio_channel_mapping": {
       "required": null,
       "resolved": null,
@@ -110,6 +112,9 @@
       "board-materials"
     ]
   },
+  "build_evidence": {
+    "artifacts": []
+  },
   "runtime_evidence": [],
   "features": {
     "requested": [

package/skills/tirtc-esp32-builder/assets/lckfb-szpi-esp32s3-portable-prompt.md

@@ -0,0 +1,51 @@
+$tirtc-esp32-builder
+
+请在一台全新电脑上完成立创·实战派 ESP32-S3 的 ThingConnect TiRTC clean-room L-1/L0/L1 接入。允许访问外网，并允许 `npx tirtc-device-builder@latest setup esp32 --install` 在当前用户目录安装固定版本的 Device Kit、ESP-IDF 和 Skill；禁止 sudo、系统级包变更和修改 shell profile。无需重复询问该用户目录安装权限。
+
+工作区：
+- 将本提示词所在资料包目录作为 `WORKSPACE_ROOT`。
+- 所有本地输入和输出均相对 `WORKSPACE_ROOT` 解析；报告中再记录规范化绝对路径。
+
+证据边界：
+- 只使用 `docs/`、其中的厂商示例、厂商官方资料和 managed Device Kit。
+- 不读取工作区外的历史工程、日志或 artifact。
+- 不使用任何真实 Wi-Fi、设备、MQTT、WHIP 或 AI 凭证。
+
+开发板：
+- 立创·实战派 ESP32-S3，PCB V1.0.1。
+- ESP32-S3-WROOM-1-N16R8，16 MB Flash、8 MB Octal PSRAM。
+- `docs/立创实战派ESP32-S3开发板原理图.pdf` 对应手中实物。
+- 厂商标称 GC0308，实物 PID `0x2145`/GC2145；保留矛盾，只允许有精确证据的 PID，拒绝未知 PID。
+
+资料：
+- `docs/立创实战派ESP32-S3开发板原理图.pdf`
+- `docs/02-芯片手册/`
+- `docs/szpi-s3-esp/`
+- https://wiki.lckfb.com/zh-hans/szpi-esp32s3/
+
+目标：
+- H5 MJPEG 实时视频和声音、H5 双向语音、AI 双向语音。
+- 每次视频发送一张完整 JPEG。
+- 音频 G.711 A-law、8 kHz、mono。
+- stream：H5 上行 10、视频 11、下行 14、AI 1。
+- 初版允许半双工；不声明未实测的全双工或 AEC。
+
+接入：
+- SoftAP 配网，凭证保存 NVS。
+- 验证码绑定，复用已有绑定。
+- 分别提供 `wifi-clear` 和 `tirtc-clear`。
+- 平台发现先用 HTTP；HTTPS 后续独立验收。
+
+输出：
+- `lckfb-szpi-esp32s3-tirtc/`
+
+强制门禁：
+1. 运行 Device Kit Doctor并固定 ESP-IDF、Kit、TiRTC SDK、生成器和组件版本。
+2. 从不存在的输出目录开始生成 Hardware IR v2 和工程；不得读取或复制任何既有 adapter、历史工程、`build/`、日志或 artifact。所有具体 clock、I2S mode/controller、TDM slot、物理信号、shared-GPIO handoff、camera task/core、frame buffer 和 memory/backpressure 值都要引用来源。
+3. 音频必须生成项目内 `board-audio-contract.json`。`idf.py reconfigure` 后，使用 Skill 的 `audio_contract.py` 直接查询锁定 codec driver table；所选 `(MCLK, sample rate)` 必须被所有相关 codec 支持。
+4. 视频必须生成项目内 `board-video-contract.json` 并使用 `video_contract.py` 核对锁定组件、CPU 隔离、完整 JPEG、PID 白名单、frame buffers、TiRTC send buffer 和 backpressure。此板初版合同必须包含 camera event CPU1、Wi-Fi CPU0、两个 PSRAM frame buffers、256 KiB max send buffer、192 KiB backpressure、stream 11 和 `TIRTC_VIDEO_JPEG`；esp32-camera 固定官方 2.1.7 legacy-I2C 配置。
+5. 音频和视频合同都必须和 adapter 源码核对，并分别通过 `install_audio_gate.py`、`install_video_gate.py` 接入每次 `idf.py build`。任何缺失或失败都只能记为 `COMPILE_PASS / CAPABILITY_BLOCKED`，不得写 `BUILD_VERIFIED`。
+6. build assessment 必须提供 `--project` 和当前 artifact SHA-256，并重新运行两个语义合同；任一 requested feature 阻塞时，project gate 也必须阻塞。
+7. 输出 Hardware IR、两个合同、依赖锁、可独立构建工程、门禁证据、BIN/ELF 大小与 SHA-256，以及 `TIRTC_PORTING_REPORT.md`。
+8. 对源码交付物运行 `project_portability.py --export`；不得携带旧 `build/`，CMake 中的 shell 门禁必须显式通过 `bash` 调用。
+9. 本轮不访问串口、不烧录、不 monitor、不擦除 NVS；L2-L7 记为 SKIP，不得把 L1 编译表述为实机已有图像或声音。

package/skills/tirtc-esp32-builder/assets/report-template.md

@@ -28,6 +28,17 @@
 | H5 talkback |  |  |
 | AI intercom |  |  |
 
+## Semantic build gates
+
+- Audio contract path/SHA-256: `{{AUDIO_CONTRACT}}`
+- Codec clock-table result: `{{AUDIO_CLOCK_GATE}}`
+- I2S mode/controller/slot/handoff result: `{{AUDIO_TOPOLOGY_GATE}}`
+- Video contract path/SHA-256: `{{VIDEO_CONTRACT}}`
+- Camera lock/PID/CPU/frame/backpressure result: `{{VIDEO_GATE}}`
+- Final ELF I2C driver-family result: `{{I2C_ELF_GATE}}`
+- Build artifact present in Hardware IR evidence: `{{BUILD_ARTIFACT_BINDING}}`
+- Compiler result versus requested-feature result: `{{COMPILE_VS_CAPABILITY}}`
+
 ## Acceptance
 
 | Level | PASS/FAIL/SKIP | Command and evidence |

package/skills/tirtc-esp32-builder/references/audio-contract.md

@@ -0,0 +1,51 @@
+# Audio semantic contract
+
+Read this reference whenever a requested feature uses microphone capture or speaker playback. Its purpose is to turn codec clocks, I2S modes, channel mapping, and shared-signal ownership into one deterministic build gate.
+
+## Project contract
+
+Create `board-audio-contract.json` in the generated project. Start from `assets/board-audio-contract.example.json`, but replace every board value and evidence ID from the exact schematic, official BSP/example, datasheet, and locked component source. Keep every path project-relative.
+
+The contract must describe:
+
+- the PCM sample rate, MCLK ratio, resulting MCLK, and every clocked codec driver table;
+- capture/playback controller, role, and standard/TDM/DSP/PCM mode;
+- TDM enable, slot count/order, physical signal at each slot, selected slot, and mapping evidence when TDM is used;
+- shared clock GPIOs, whether directions are simultaneous, and the release/recreate handoff;
+- source assertions tying the normalized contract to the actual adapter implementation.
+
+A generic header comment such as “typically 256” is not coefficient evidence. After `idf.py reconfigure` resolves managed components, the selected `(MCLK, sample rate)` pair must exist in every locked codec table named by the contract.
+
+## Mandatory gate
+
+Run the gate before claiming an audio-capable build:
+
+```bash
+python3 <skill-dir>/scripts/audio_contract.py \
+  <project>/board-audio-contract.json \
+  --project <project> \
+  --evidence-out <project>/build/audio-contract-evidence.json
+```
+
+Then install it into every subsequent `idf.py build`:
+
+```bash
+python3 <skill-dir>/scripts/install_audio_gate.py <project>
+```
+
+The installer copies the verifier into the project and adds an `ALL` CMake dependency for the ELF. A moved project therefore retains its semantic gate without requiring the Skill installation path.
+
+Set `hardware_resources.audio_semantic_contract` to `board-audio-contract.json`. Build assessment must pass `--project <project>`; the assessor reruns the gate and blocks every requested audio feature when the contract is missing or fails.
+
+## Completion criterion
+
+Audio reaches `BUILD_VERIFIED` only when all of these are true:
+
+1. the contract has at least two authoritative source IDs;
+2. its arithmetic and codec table lookups pass;
+3. its topology, TDM mapping, and handoff are internally consistent;
+4. its adapter assertions pass;
+5. the gate is part of the ordinary build;
+6. the exact BIN/ELF is hashed after that build.
+
+Compilation without this gate is `COMPILE_PASS`, not audio `BUILD_VERIFIED`.