tirtc-device-builder 0.4.0 → 0.5.0

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 This project follows Semantic Versioning.
 
+## 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

@@ -90,8 +90,8 @@ Skill 在 Codex 会话启动时被发现。安装完成后，关闭当前 Codex
 
 工程：<输出目录或现有工程的绝对路径>
 
-请先运行 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 阶段评估，并输出 TIRTC_PORTING_REPORT.md。
+本轮不访问串口、不烧录、不擦除 NVS；缺少串口只让 L2-L7 记为 SKIP，不得阻止 L0/L1。不要把任何凭证写入源码或报告。
 ```
 
 手头只有型号也可以开始：
@@ -450,26 +450,33 @@ 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 --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
 ```
 
@@ -750,7 +757,7 @@ WSL 默认不一定能看到 USB 设备。按 [Microsoft WSL USB 连接说明](h
 
 ### Hardware IR 一直是 `NEEDS_CONFIRMATION`
 
-先查看各个未知项要求什么来源。常见缺口包括准确的 PCB 版本、摄像头数据格式、所选视频 profile 的完整输出路径、Codec 时钟、功放使能脚、配网方法和可工作的厂商示例。不要从相似开发板复制管脚来填补这些信息。
+先确认当前运行的是 intake、build 还是 hil 阶段，再标记每个未知项的下一证据来源。资料/固定源码可解决的事实继续检查；adapter 或 ELF 可解决的事实进入对应实现/构建层；运行指标留到 HIL。只有准确 PCB 版本、关键连接、器件身份、产品合同或不可用 SDK 等无法安全推导的事实需要用户补充。不要从相似开发板复制管脚来填补这些信息。
 
 ### 工程能编译，浏览器没有画面
 
@@ -874,8 +881,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.5.0 -m "v0.5.0"
+git push origin v0.5.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.5.0",
   "description": "Install and run TiRTC device-development skills for Codex.",
   "license": "MIT",
   "author": {

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

@@ -14,7 +14,9 @@ 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
 
@@ -26,11 +28,15 @@ Keep the Skill board-agnostic. The prompt supplies product intent and artifact l
 
 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.
 
+After a successful build, promote only facts actually established by source, compile, or post-link gates to `build_verified`. Hash the exact BIN/ELF and run `hardware_ir.py assess --phase build --artifact-sha256 <sha256> --strict`. A design plan at `corroborated` can pass intake but cannot pass the build phase.
+
 ## 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
 

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/developer-intake-prompt.md

@@ -30,10 +30,12 @@ $tirtc-esp32-builder
 
 执行要求：
 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. 移植前核对媒体合同、板级资源、静态内存预算、配网和绑定状态。构建后只把源代码、锁定依赖、编译或 post-link 门禁实际证明的事实升级为 build_verified。
+5. 记录 BIN/ELF 路径、大小和 SHA-256，运行 build 阶段评估并输出 TIRTC_PORTING_REPORT.md。编译结果必须与 L2-L7 实机验收分开。
+6. 本轮不访问串口、不烧录、不擦除 NVS；因此缺少启动、浏览器、实体声音和运行时资源数据时，把相应 L2-L7 标为 SKIP，不得阻止 L0/L1。
+7. Wi-Fi 密码、设备密钥、token、私钥和用户音视频不能写入工程或报告。
 ```
 
 ## 只有已知时才补充
@@ -46,5 +48,6 @@ $tirtc-esp32-builder
 - 凭证保存与重配方式、已有绑定处理和独立清除入口；
 - 已知资料矛盾、实机 PID、串口日志或已知良好固件 SHA-256；
 - 非默认 ESP-IDF、TiRTC SDK、Device Kit、服务发现地址或 HTTP/HTTPS 分阶段要求。
+- 若用于 clean-room 验证，明确允许的资料根目录，并列出不得读取的历史工程或旧 artifact。
 
 直接把它们追加在提示词末尾即可，不必逐项填表。

package/skills/tirtc-esp32-builder/references/capability-rules.md

@@ -1,6 +1,6 @@
 # Capability rules
 
-Run `hardware_ir.py assess --strict` before generation. Hardware IR v2 validates the selected product contract rather than assuming one video codec or provisioning method. Schema v1 remains readable for existing H.264 projects.
+Run `hardware_ir.py assess --phase intake --strict` before generation. Hardware IR v2 validates the selected product contract rather than assuming one video codec or provisioning method. Schema v1 remains readable for existing H.264 projects.
 
 ## Current starter contract
 
@@ -11,7 +11,9 @@ Run `hardware_ir.py assess --strict` before generation. Hardware IR v2 validates
 | `h5_talkback` | G.711 A-law, 8 kHz downlink decode and speaker path for stream 14; audio controller/GPIO ownership and memory budget resolved |
 | `ai_talk` | A-law 8 kHz microphone and speaker paths for AI stream 1, started only after `start_session`; audio ownership/channel mapping and memory budget resolved |
 
-The complete media path must be at least `corroborated` to become `READY_TO_PORT`. A path with unknown facts is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`.
+Hardware identity, wiring, the selected media contract, and the adapter/resource design must be at least `corroborated` to become `READY_TO_PORT`. At intake, `available=true` means a pinned source path can implement the selected profile; it does not claim that the final adapter or physical media path has run. Implementation composition, final ELF policy, runtime memory margin, browser media, and stability belong to the build or HIL phases.
+
+A design fact that is still unknown is `NEEDS_CONFIRMATION`; a confirmed missing or incompatible resource is `BLOCKED`. Facts that can be resolved safely through source inspection, adapter implementation, compilation, or post-link inspection should be resolved in that layer rather than converted into a request for HIL evidence.
 
 ## Selected video profiles
 
@@ -25,14 +27,16 @@ Hardware IR v2 stores one or more `camera.video_profiles` and exactly one select
 
 Available but unselected profiles do not satisfy or block the selected contract. Stream IDs and codec support must come from the applicable ThingConnect/H5 contract, not this table alone.
 
-## Project gates
+## Phased project gates
 
-Schema v2 also requires:
+The intake phase requires:
 
-- one evidenced I2C driver family when I2C is used;
+- one selected and evidenced I2C driver-family plan when I2C is used;
 - a selected Wi-Fi credential method that is available, reprovisionable, and keeps credentials outside source control;
 - one evidenced binding method—verification code, factory-bound identity, development credentials, or documented custom flow—plus stored-binding behavior and reset control;
-- feature-specific I2S/GPIO ownership, channel/TDM mapping, realtime camera policy, and startup/media memory budget.
+- feature-specific I2S/GPIO ownership plans, channel/TDM mapping, realtime camera policy, and a static startup/media memory budget.
+
+At intake, `corroborated` on these fields means the design is resolved from authoritative sources and is safe to implement. After compilation, promote a field to `build_verified` only when the generated source, component lock, compile result, or post-link gate establishes it. The build phase requires an exact artifact SHA-256 and returns `BUILD_VERIFIED`. Runtime measurements never need to be invented to pass intake or build.
 
 SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, factory NVS, development configuration, or a documented custom method can satisfy intake when the selected path is evidenced. Committed plaintext credentials are always `BLOCKED`.
 
@@ -43,7 +47,7 @@ SoftAP is one Wi-Fi option, not a universal requirement. BLE, SmartConfig, facto
 - Start AI media only after the successful `start_session` response; stop and flush media before disconnecting.
 - Copy SDK callback payloads into bounded queues before returning. Perform decoding, playback, HTTP, and lifecycle changes outside callbacks.
 - Use monotonic timestamps and session generation to reject stale frames and delayed callbacks.
-- Record runtime evidence with the exact BIN/ELF SHA-256. Use `assess --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.
+- Record runtime evidence with the exact BIN/ELF SHA-256. Use `assess --phase hil --artifact-sha256 <sha>`; documentation verification alone never becomes v2 `HIL_VERIFIED`.
 
 ## Typical blocked cases
 

package/skills/tirtc-esp32-builder/references/hardware-ir.md

@@ -27,6 +27,8 @@ Verification levels are ordered:
 4. `hardware_verified`: the local peripheral works on the exact board revision.
 5. `hil_verified`: retained for legacy facts; schema v2 feature HIL additionally requires matching artifact evidence.
 
+Use the same fact across phases without overstating it. `corroborated` means authoritative sources establish an implementable design; `build_verified` means the generated source, locked dependencies, compile, or post-link gates establish that implementation; runtime behavior requires matching artifact evidence. For example, a corroborated single-I2C-family field records a dependency plan, while its build-verified form records the final ELF audit.
+
 ## Schema v2 contracts
 
 The IR contains:
@@ -46,11 +48,22 @@ The selected video profile controls assessment. An unselected H.264 fallback can
 
 ## Artifact-bound HIL
 
+Run the phase gates in order:
+
+```bash
+python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
+  --phase intake --strict
+python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
+  --phase build --artifact-sha256 <64-character-sha256> --strict
+```
+
+The intake phase returns `READY_TO_PORT`; the build phase returns `BUILD_VERIFIED`. Missing serial or browser access does not block either phase.
+
 Run:
 
 ```bash
 python3 <skill-dir>/scripts/hardware_ir.py assess hardware-ir.json \
-  --artifact-sha256 <64-character-sha256> --strict
+  --phase hil --artifact-sha256 <64-character-sha256> --strict
 ```
 
 H5 features require matching L5 evidence; AI requires matching L6 evidence. Evidence from an older firmware remains provenance but does not verify the current artifact.

package/skills/tirtc-esp32-builder/references/porting-risks.md

@@ -36,7 +36,7 @@ For every method, keep device credentials outside source control, handle an alre
 
 Platform service discovery and the TiRTC SDK service endpoint are different settings. Record both. HTTPS requires valid time, DNS, certificate validation, TLS client/TLS 1.2, and enough contiguous internal memory.
 
-Before sizing TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates. A larger queue can prevent drops, exhaust startup memory, or add buffer latency. If an authorized HTTP baseline exists, stage transport changes separately from media changes and retain the HTTPS requirements as a pending acceptance item.
+Define a conservative static budget before implementation using the locked SDK contract, framebuffer geometry, DMA/queue bounds, task stacks, and an internal-memory reserve. Before claiming runtime margin or tuning TiRTC buffers, measure internal free/largest blocks, PSRAM, frame size distribution, queue watermarks, and send/drop rates on the exact artifact. A larger queue can prevent drops, exhaust startup memory, or add buffer latency. If an authorized HTTP baseline exists, stage transport changes separately from media changes and retain the HTTPS requirements as a pending acceptance item.
 
 ## Network and media evidence
 

package/skills/tirtc-esp32-builder/references/reporting.md

@@ -16,11 +16,13 @@ Use [the report template](../assets/report-template.md) and preserve separate `P
 | L6 AI | Token, WHIP, `start_session`, bidirectional audio, stop, and H5 recovery work |
 | L7 Stability | Requested weak-network, repeated-session, resource, and soak criteria pass |
 
+Run and record the intake assessment before L0, the build assessment with the exact artifact SHA-256 at L1, and the HIL assessment only when matching runtime evidence exists. Missing serial or browser access is a `SKIP` for the affected L2-L7 levels, not an L0/L1 failure.
+
 ## Evidence
 
 Record exact board revision, selected media, Wi-Fi, and binding profiles, toolchain and SDK versions, source/adapter revisions, commands, return codes, firmware size and SHA-256, serial port/chip, sanitized log paths, browser or platform observations, and every unavailable dependency.
 
-Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --artifact-sha256 <sha> --strict`.
+Runtime evidence belongs to one artifact. Label superseded artifacts and keep their observations as history; do not promote them to the current BIN/ELF. For HIL assessment, add the full SHA-256 to `runtime_evidence` and run `hardware_ir.py assess --phase hil --artifact-sha256 <sha> --strict`.
 
 For L3-L7 media runs, capture the signals that distinguish software regressions from environment changes: onboarding/binding state, BSSID/channel/RSSI, reconnect or roaming events, audio/video send/receive/drop/error counters, queue watermarks, camera overflow count, internal heap/largest block, PSRAM, and measured latency when available. Never record credential values.
 

package/skills/tirtc-esp32-builder/references/workflow.md

@@ -23,8 +23,8 @@ Use this branch when the user supplies a board model, vendor URL, schematic, BOM
 3. Prefer official schematic/BOM and BSP facts. For a PDF schematic, inspect page labels and net names; prefer an exported netlist, pin CSV, or vendor board definition when available.
 4. Cross-check critical pins, clocks, power enables, reset lines, sensor/codec variants, ESP-IDF version, resource ownership, and onboarding behavior across at least two independent artifacts when possible.
 5. Create the Hardware IR v2. Use `null` for unknown facts and retain contradictory values as an explicit issue instead of selecting one silently. Store concrete board values in the IR/adapter rather than Skill files.
-6. Validate and assess requested features. Ask only for unresolved facts that block the next safe step. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
-7. When all requirements reach `READY_TO_PORT`, generate the starter and implement the board adapter. When requirements remain blocked, generate only the IR, capability report, and an optional compile-safe skeleton if requested.
+6. Validate and run the intake assessment. Classify unresolved facts by their next evidence source: source, implementation, build, HIL, or user input. Ask only for `user_blocked` facts that prevent a safe design. SoftAP is optional when another evidenced Wi-Fi credential method is available, keeps credentials outside source, and defines reprovisioning.
+7. When hardware identity, wiring, product contracts, and an evidenced resource plan reach `READY_TO_PORT`, generate the starter and implement the board adapter. Generate a compile-safe adapter by default when remaining uncertainty is implementation-, build-, or HIL-resolvable. Stop at the IR/report only when missing user evidence or an incompatible dependency makes a safe implementation impossible.
 
 The branch is complete when every supplied artifact maps to an IR fact, provenance entry, contradiction, or declared irrelevant item.
 
@@ -68,4 +68,12 @@ The stable modules own stream IDs, negotiated/contracted formats, TiRTC callback
 
 Use a bounded loop per layer: diagnose one failing invariant, make the smallest correction, and rerun that layer before moving forward. Change one high-risk variable per HIL comparison. Turn reusable invariants into tests or post-link gates. Stop and report when the remaining failure requires unavailable hardware, credentials, a new SDK binary, a public protocol change, or a user choice.
 
+Run the assessor once per layer:
+
+- `--phase intake`: corroborated design evidence; success is `READY_TO_PORT`.
+- `--phase build --artifact-sha256 <sha>`: compile/post-link evidence; success is `BUILD_VERIFIED`.
+- `--phase hil --artifact-sha256 <sha>`: matching L5/L6 runtime evidence; success is `HIL_VERIFIED`.
+
+No serial authorization is required for L0/L1. When serial, browser, account, service, or network access is unavailable, complete the safe build work and report the affected L2-L7 levels as `SKIP`.
+
 Do not use successful compilation as evidence for camera frames, speaker output, Web rendering, AI audio, or long-run stability. Bind every runtime conclusion to the tested firmware SHA-256.

package/skills/tirtc-esp32-builder/scripts/hardware_ir.py

@@ -25,7 +25,12 @@ VERIFICATION_LEVELS = {
     "hardware_verified": 4,
     "hil_verified": 5,
 }
-READY_STATUSES = {"READY_TO_PORT", "HIL_VERIFIED"}
+ASSESSMENT_PHASES = {"intake", "build", "hil"}
+PHASE_SUCCESS_STATUSES = {
+    "intake": {"READY_TO_PORT", "HIL_VERIFIED"},
+    "build": {"BUILD_VERIFIED", "HIL_VERIFIED"},
+    "hil": {"HIL_VERIFIED"},
+}
 VIDEO_CONTRACTS = {
     "mjpeg": "jpeg_complete_frames",
     "h264": "h264_annex_b_access_units",
@@ -482,7 +487,15 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
     return errors
 
 
-def codec_requirement(media: dict[str, Any], section: str) -> Requirement:
+def minimum_verification_for_phase(phase: str) -> str:
+    if phase == "intake":
+        return "corroborated"
+    return "build_verified"
+
+
+def codec_requirement(
+    media: dict[str, Any], section: str, minimum_verification: str = "corroborated"
+) -> Requirement:
     present = media.get("present")
     if present is None:
         return "NEEDS_CONFIRMATION", f"{section} presence is unknown", 0
@@ -496,17 +509,20 @@ def codec_requirement(media: dict[str, Any], section: str) -> Requirement:
             continue
         verification = codec.get("verification")
         level = VERIFICATION_LEVELS.get(verification, 0)
-        if level < VERIFICATION_LEVELS["corroborated"]:
+        if level < VERIFICATION_LEVELS[minimum_verification]:
             return (
                 "NEEDS_CONFIRMATION",
-                f"{section} A-law 8 kHz path is only {verification}",
+                f"{section} A-law 8 kHz path is only {verification}; "
+                f"{minimum_verification} is required",
                 level,
             )
         return "SATISFIED", f"{section} provides A-law 8 kHz", level
     return "BLOCKED", f"{section} has no A-law 8 kHz path", 0
 
 
-def legacy_video_requirement(camera: dict[str, Any]) -> Requirement:
+def legacy_video_requirement(
+    camera: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     present = camera.get("present")
     if present is None:
         return "NEEDS_CONFIRMATION", "camera presence is unknown", 0
@@ -530,10 +546,11 @@ def legacy_video_requirement(camera: dict[str, Any]) -> Requirement:
         return "BLOCKED", "key-frame requests cannot reach the encoder", 0
     verification = h264.get("verification")
     level = VERIFICATION_LEVELS.get(verification, 0)
-    if level < VERIFICATION_LEVELS["corroborated"]:
+    if level < VERIFICATION_LEVELS[minimum_verification]:
         return (
             "NEEDS_CONFIRMATION",
-            f"H.264 Annex-B path is only {verification}",
+            f"H.264 Annex-B path is only {verification}; "
+            f"{minimum_verification} is required",
             level,
         )
     return "SATISFIED", "camera provides H.264 Annex-B and IDR control", level
@@ -548,7 +565,9 @@ def selected_item(items: Any, selected_id: Any) -> dict[str, Any] | None:
     return None
 
 
-def video_requirement_v2(camera: dict[str, Any]) -> Requirement:
+def video_requirement_v2(
+    camera: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     present = camera.get("present")
     if present is None:
         return "NEEDS_CONFIRMATION", "camera presence is unknown", 0
@@ -585,10 +604,11 @@ def video_requirement_v2(camera: dict[str, Any]) -> Requirement:
         return "BLOCKED", "H5 refresh requests cannot reach the media pipeline", 0
     verification = profile.get("verification")
     level = VERIFICATION_LEVELS.get(verification, 0)
-    if level < VERIFICATION_LEVELS["corroborated"]:
+    if level < VERIFICATION_LEVELS[minimum_verification]:
         return (
             "NEEDS_CONFIRMATION",
-            f"selected {codec} path is only {verification}",
+            f"selected {codec} path is only {verification}; "
+            f"{minimum_verification} is required",
             level,
         )
     return (
@@ -599,7 +619,10 @@ def video_requirement_v2(camera: dict[str, Any]) -> Requirement:
 
 
 def verified_bool_requirement(
-    section: dict[str, Any], field: str, label: str
+    section: dict[str, Any],
+    field: str,
+    label: str,
+    minimum_verification: str = "corroborated",
 ) -> Requirement:
     value = section.get(field)
     if value is None:
@@ -608,12 +631,18 @@ def verified_bool_requirement(
         return "BLOCKED", f"{label} is unresolved", 0
     verification = section.get("verification")
     level = VERIFICATION_LEVELS.get(verification, 0)
-    if level < VERIFICATION_LEVELS["corroborated"]:
-        return "NEEDS_CONFIRMATION", f"{label} is only {verification}", level
+    if level < VERIFICATION_LEVELS[minimum_verification]:
+        return (
+            "NEEDS_CONFIRMATION",
+            f"{label} is only {verification}; {minimum_verification} is required",
+            level,
+        )
     return "SATISFIED", f"{label} is resolved", level
 
 
-def i2c_requirement(resources: dict[str, Any]) -> Requirement:
+def i2c_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     i2c = resources.get("i2c", {})
     used = i2c.get("used")
     if used is None:
@@ -626,11 +655,16 @@ def i2c_requirement(resources: dict[str, Any]) -> Requirement:
     if family == "none":
         return "BLOCKED", "I2C is used but no driver family is selected", 0
     return verified_bool_requirement(
-        i2c, "single_driver_family", f"single {family} I2C driver family"
+        i2c,
+        "single_driver_family",
+        f"single {family} I2C driver family plan",
+        minimum_verification,
     )
 
 
-def i2s_requirement(resources: dict[str, Any]) -> Requirement:
+def i2s_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     i2s = resources.get("i2s", {})
     used = i2s.get("used")
     if used is None:
@@ -640,11 +674,14 @@ def i2s_requirement(resources: dict[str, Any]) -> Requirement:
     return verified_bool_requirement(
         i2s,
         "controller_and_gpio_ownership_resolved",
-        "I2S controller and GPIO ownership",
+        "I2S controller and GPIO ownership plan",
+        minimum_verification,
     )
 
 
-def audio_mapping_requirement(resources: dict[str, Any]) -> Requirement:
+def audio_mapping_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     channel = resources.get("audio_channel_mapping", {})
     required = channel.get("required")
     if required is None:
@@ -652,23 +689,32 @@ def audio_mapping_requirement(resources: dict[str, Any]) -> Requirement:
     if required is False:
         return "SATISFIED", "audio channel/TDM mapping is not required", 2
     return verified_bool_requirement(
-        channel, "resolved", "audio channel/TDM mapping"
+        channel,
+        "resolved",
+        "audio channel/TDM mapping",
+        minimum_verification,
     )
 
 
-def camera_realtime_requirement(resources: dict[str, Any]) -> Requirement:
+def camera_realtime_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     return verified_bool_requirement(
         resources.get("camera_realtime", {}),
         "pipeline_safe",
-        "camera DMA/task realtime policy",
+        "camera DMA/task realtime policy design",
+        minimum_verification,
     )
 
 
-def memory_requirement(resources: dict[str, Any]) -> Requirement:
+def memory_requirement(
+    resources: dict[str, Any], minimum_verification: str = "corroborated"
+) -> Requirement:
     return verified_bool_requirement(
         resources.get("memory", {}),
         "startup_and_media_budgeted",
-        "startup and media memory budget",
+        "static startup and media memory budget",
+        minimum_verification,
     )
 
 
@@ -750,7 +796,9 @@ def binding_requirement(onboarding: dict[str, Any]) -> Requirement:
 
 
 def combine_requirements(
-    requirements: list[Requirement], legacy_hil_from_levels: bool = False
+    requirements: list[Requirement],
+    success_status: str = "READY_TO_PORT",
+    legacy_hil_from_levels: bool = False,
 ) -> dict[str, Any]:
     reasons = [reason for _, reason, _ in requirements]
     states = {state for state, _, _ in requirements}
@@ -766,7 +814,7 @@ def combine_requirements(
     ):
         status = "HIL_VERIFIED"
     else:
-        status = "READY_TO_PORT"
+        status = success_status
     return {"status": status, "reasons": reasons}
 
 
@@ -839,9 +887,32 @@ def matching_runtime_evidence(
     return None
 
 
+def artifact_requirement(artifact_sha256: str | None) -> Requirement:
+    if artifact_sha256 is None:
+        return "NEEDS_CONFIRMATION", "exact build artifact SHA-256 is missing", 0
+    if not SHA256_RE.fullmatch(artifact_sha256):
+        return "BLOCKED", "build artifact SHA-256 is invalid", 0
+    return (
+        "SATISFIED",
+        f"build evidence is bound to artifact {artifact_sha256}",
+        VERIFICATION_LEVELS["build_verified"],
+    )
+
+
 def assess_ir(
-    data: dict[str, Any], artifact_sha256: str | None = None
+    data: dict[str, Any],
+    artifact_sha256: str | None = None,
+    phase: str | None = None,
 ) -> dict[str, Any]:
+    selected_phase = phase or ("hil" if artifact_sha256 else "intake")
+    if selected_phase not in ASSESSMENT_PHASES:
+        raise ValueError(
+            f"assessment phase must be one of {', '.join(sorted(ASSESSMENT_PHASES))}"
+        )
+    minimum_verification = minimum_verification_for_phase(selected_phase)
+    success_status = (
+        "READY_TO_PORT" if selected_phase == "intake" else "BUILD_VERIFIED"
+    )
     schema_version = data.get("schema_version")
     requested = data["features"]["requested"]
     audio_input = data["audio_input"]
@@ -858,7 +929,7 @@ def assess_ir(
         onboarding = data["onboarding"]
         project.extend(
             [
-                i2c_requirement(resources),
+                i2c_requirement(resources, minimum_verification),
                 wifi_requirement(onboarding),
                 binding_requirement(onboarding),
             ]
@@ -875,73 +946,101 @@ def assess_ir(
     else:
         resources = {}
 
+    if selected_phase in {"build", "hil"}:
+        project.append(artifact_requirement(artifact_sha256))
+
     for feature in requested:
         if schema_version == 1:
             if feature == "h5_live_audio":
-                requirements = [codec_requirement(audio_input, "audio_input")]
+                requirements = [
+                    codec_requirement(
+                        audio_input, "audio_input", minimum_verification
+                    )
+                ]
             elif feature == "h5_live_video":
-                requirements = [legacy_video_requirement(camera)]
+                requirements = [
+                    legacy_video_requirement(camera, minimum_verification)
+                ]
             elif feature == "h5_talkback":
-                requirements = [codec_requirement(audio_output, "audio_output")]
+                requirements = [
+                    codec_requirement(
+                        audio_output, "audio_output", minimum_verification
+                    )
+                ]
             else:
                 requirements = [
-                    codec_requirement(audio_input, "audio_input"),
-                    codec_requirement(audio_output, "audio_output"),
+                    codec_requirement(
+                        audio_input, "audio_input", minimum_verification
+                    ),
+                    codec_requirement(
+                        audio_output, "audio_output", minimum_verification
+                    ),
                 ]
             result[feature] = combine_requirements(
-                requirements, legacy_hil_from_levels=True
+                requirements,
+                success_status=success_status,
+                legacy_hil_from_levels=(selected_phase == "intake"),
             )
             continue
 
         if feature == "h5_live_audio":
             requirements = [
-                codec_requirement(audio_input, "audio_input"),
-                i2s_requirement(resources),
-                audio_mapping_requirement(resources),
-                memory_requirement(resources),
+                codec_requirement(audio_input, "audio_input", minimum_verification),
+                i2s_requirement(resources, minimum_verification),
+                audio_mapping_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
             ]
         elif feature == "h5_live_video":
             requirements = [
-                video_requirement_v2(camera),
-                camera_realtime_requirement(resources),
-                memory_requirement(resources),
+                video_requirement_v2(camera, minimum_verification),
+                camera_realtime_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
             ]
         elif feature == "h5_talkback":
             requirements = [
-                codec_requirement(audio_output, "audio_output"),
-                i2s_requirement(resources),
-                memory_requirement(resources),
+                codec_requirement(audio_output, "audio_output", minimum_verification),
+                i2s_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
             ]
         else:
             requirements = [
-                codec_requirement(audio_input, "audio_input"),
-                codec_requirement(audio_output, "audio_output"),
-                i2s_requirement(resources),
-                audio_mapping_requirement(resources),
-                memory_requirement(resources),
+                codec_requirement(audio_input, "audio_input", minimum_verification),
+                codec_requirement(audio_output, "audio_output", minimum_verification),
+                i2s_requirement(resources, minimum_verification),
+                audio_mapping_requirement(resources, minimum_verification),
+                memory_requirement(resources, minimum_verification),
             ]
-        result[feature] = combine_requirements(requirements)
+        result[feature] = combine_requirements(
+            requirements, success_status=success_status
+        )
 
     project_gate = combine_requirements(
-        project, legacy_hil_from_levels=(schema_version == 1)
+        project,
+        success_status=success_status,
+        legacy_hil_from_levels=(schema_version == 1 and selected_phase == "intake"),
     )
     evidence = matching_runtime_evidence(data, artifact_sha256)
-    if schema_version == 2 and evidence is not None:
-        evidence_features = set(evidence.get("features", []))
-        evidence_levels = set(evidence.get("acceptance_levels", []))
-        for feature, assessment in result.items():
-            if (
-                assessment["status"] == "READY_TO_PORT"
-                and feature in evidence_features
-                and FEATURE_HIL_LEVEL[feature] in evidence_levels
-            ):
-                assessment["status"] = "HIL_VERIFIED"
-                assessment["reasons"].append(
-                    f"artifact {artifact_sha256} passed {FEATURE_HIL_LEVEL[feature]}"
+    if schema_version == 2 and selected_phase == "hil":
+        evidence_features = set(evidence.get("features", [])) if evidence else set()
+        evidence_levels = (
+            set(evidence.get("acceptance_levels", [])) if evidence else set()
+        )
+        for feature, feature_assessment in result.items():
+            if feature_assessment["status"] != "BUILD_VERIFIED":
+                continue
+            required_level = FEATURE_HIL_LEVEL[feature]
+            if feature in evidence_features and required_level in evidence_levels:
+                feature_assessment["status"] = "HIL_VERIFIED"
+                feature_assessment["reasons"].append(
+                    f"artifact {artifact_sha256} passed {required_level}"
+                )
+            else:
+                feature_assessment["reasons"].append(
+                    f"artifact {artifact_sha256} has no matching {required_level} runtime evidence"
                 )
         if result and all(
             item["status"] == "HIL_VERIFIED" for item in result.values()
-        ):
+        ) and project_gate["status"] == "BUILD_VERIFIED":
             project_gate["status"] = "HIL_VERIFIED"
             project_gate["reasons"].append(
                 f"all requested features have matching artifact evidence for {artifact_sha256}"
@@ -949,6 +1048,7 @@ def assess_ir(
 
     assessment: dict[str, Any] = {
         "schema_version": schema_version,
+        "phase": selected_phase,
         "board_id": data["board"]["id"],
         "hardware_revision": data["board"]["hardware_revision"],
         "project_gate": project_gate,
@@ -1005,12 +1105,26 @@ def command_assess(args: argparse.Namespace) -> int:
         for error in errors:
             print(f"error: {error}", file=sys.stderr)
         return 2
-    assessment = assess_ir(data, artifact_sha256=args.artifact_sha256)
+    if args.artifact_sha256 is not None and not SHA256_RE.fullmatch(
+        args.artifact_sha256
+    ):
+        print("error: --artifact-sha256 must be a 64-character SHA-256", file=sys.stderr)
+        return 2
+    try:
+        assessment = assess_ir(
+            data,
+            artifact_sha256=args.artifact_sha256,
+            phase=args.phase,
+        )
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
     print(json.dumps(assessment, ensure_ascii=False, indent=2))
     if args.strict:
         statuses = {item["status"] for item in assessment["features"].values()}
         statuses.add(assessment["project_gate"]["status"])
-        if not statuses.issubset(READY_STATUSES):
+        allowed_statuses = PHASE_SUCCESS_STATUSES[assessment["phase"]]
+        if not statuses.issubset(allowed_statuses):
             return 3
     return 0
 
@@ -1036,11 +1150,16 @@ def parse_args() -> argparse.Namespace:
     assess_parser.add_argument(
         "--strict",
         action="store_true",
-        help="return non-zero unless every requested feature is ready or HIL verified",
+        help="return non-zero unless every requested feature passes the selected phase",
+    )
+    assess_parser.add_argument(
+        "--phase",
+        choices=sorted(ASSESSMENT_PHASES),
+        help="assessment phase; defaults to intake, or hil when an artifact SHA is supplied",
     )
     assess_parser.add_argument(
         "--artifact-sha256",
-        help="bind HIL status to runtime evidence for this exact firmware artifact",
+        help="bind build or HIL assessment to this exact firmware artifact",
     )
     assess_parser.set_defaults(handler=command_assess)
     return parser.parse_args()