tirtc-device-builder 0.7.1 → 0.7.3

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 This project follows Semantic Versioning.
 
+## 0.7.3
+
+- Make source export reject missing or Git-ignored Hardware IR, requested-feature
+  contracts, dependency locks, custom partition tables, and retained build
+  artifacts.
+- Support frame-compatible paired standard/TDM full-duplex audio and validate
+  hardware-reference AEC microphone/reference slot mapping.
+- Document ESP32-S3 FPU task affinity, watchdog fairness, software-encoder task
+  isolation, and PSRAM DMA staging as distinct bring-up risks.
+
+## 0.7.2
+
+- Require the selected managed ESP32 Device Kit manifest to match the pinned Kit version; ignore stale managed references instead of reporting an older structurally complete Kit as ready.
+- Make Doctor validate an exact `--expected-kit` version and persist the version actually read from the selected Kit rather than the desired version.
+- Ship a verifiable Skill `VERSION` marker, include it in setup readiness and package tests, and remove the inapplicable Plugin-version prerequisite from the portable clean-room prompt.
+
 ## 0.7.1
 
 - Split clean-room bootstrap from Skill execution: install or replace the pinned Skill before Codex starts, restart the session, then run read-only version and Doctor checks before generation.

package/README.md

@@ -881,8 +881,8 @@ metadata 中的版本、标签、上游 commit 和期望 SHA-256 必须与本地
 
 ```bash
 npm test
-git tag -a v0.7.1 -m "v0.7.1"
-git push origin v0.7.1
+git tag -a v0.7.3 -m "v0.7.3"
+git push origin v0.7.3
 ```
 
 不要重复发布已经存在的 npm 版本。版本变化同步更新 `package.json`、`.codex-plugin/plugin.json` 和发布说明。

package/bin/setup-esp32.js

@@ -33,6 +33,8 @@ const REQUIRED_SDK_FILES = [
   join("lib", "libTiRTC.a"),
   join("manifest", "build-contract.env"),
 ];
+const DEVICE_KIT_MANIFEST = "manifest.json";
+const SKILL_VERSION_FILE = "VERSION";
 
 function setupRootFrom(environment) {
   return resolve(
@@ -199,14 +201,71 @@ function discoverThingConnectRoot(start) {
   }
 }
 
-function thingConnectReady(root) {
-  if (!root || !existsSync(join(root, GENERATOR_PATH))) {
-    return false;
+function readTrimmedFile(path) {
+  if (!existsSync(path)) {
+    return null;
   }
-  const sdk = join(root, SDK_PATH);
-  return REQUIRED_SDK_FILES.every((relative) =>
-    existsSync(join(sdk, relative)),
+  try {
+    const value = readFileSync(path, "utf8").trim();
+    return value || null;
+  } catch {
+    return null;
+  }
+}
+
+export function inspectDeviceKit(root) {
+  const manifestPath = root ? join(root, DEVICE_KIT_MANIFEST) : null;
+  let manifestPresent = false;
+  let version = null;
+  let manifestError = null;
+  if (manifestPath && existsSync(manifestPath)) {
+    manifestPresent = true;
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (
+        manifest &&
+        typeof manifest === "object" &&
+        typeof manifest.kit_version === "string" &&
+        manifest.kit_version.trim()
+      ) {
+        version = manifest.kit_version.trim();
+      } else {
+        manifestError = "manifest.json does not declare kit_version";
+      }
+    } catch (error) {
+      manifestError = `invalid manifest.json: ${
+        error instanceof Error ? error.message : String(error)
+      }`;
+    }
+  }
+
+  const generatorReady = Boolean(
+    root && existsSync(join(root, GENERATOR_PATH)),
   );
+  const sdk = root ? join(root, SDK_PATH) : null;
+  const sdkReady = Boolean(
+    sdk &&
+      REQUIRED_SDK_FILES.every((relative) => existsSync(join(sdk, relative))),
+  );
+  const structureReady = generatorReady && sdkReady;
+  const versionCompatible =
+    !manifestPresent ||
+    (manifestError === null && version === ESP32_KIT.version);
+
+  return {
+    expectedVersion: ESP32_KIT.version,
+    manifestError,
+    manifestPath,
+    manifestPresent,
+    ready: structureReady && versionCompatible,
+    structureReady,
+    version,
+    versionCompatible,
+  };
+}
+
+export function readSkillVersion(skillRoot) {
+  return readTrimmedFile(join(skillRoot, SKILL_VERSION_FILE));
 }
 
 function readConfig(path) {
@@ -358,7 +417,7 @@ function writeManagedEnvironment(context, packageVersion) {
     idf_version: PINNED_IDF_VERSION,
     idf_dir: context.idfDir,
     idf_tools_path: context.idfToolsPath,
-    device_kit_version: ESP32_KIT.version,
+    device_kit_version: context.deviceKit.version,
     device_kit_root: context.thingConnectRoot,
     thing_connect_root: context.thingConnectRoot,
     skills_dir: context.skillsDir,
@@ -418,11 +477,31 @@ function setupContext(options, runtime) {
       requestedThingConnect = managedThingConnect;
     }
   }
-  const normalizedThingConnect = normalizeThingConnectRoot(
+  let normalizedThingConnect = normalizeThingConnectRoot(
     requestedThingConnect,
   );
-  const thingConnectRoot =
+  let thingConnectRoot =
     normalizedThingConnect || resolve(requestedThingConnect);
+  let deviceKit = inspectDeviceKit(thingConnectRoot);
+  let thingConnectFallback = null;
+  const versionedKitMismatch =
+    deviceKit.manifestPresent && !deviceKit.versionCompatible;
+  const staleManagedReference =
+    (thingConnectSource === "TIRTC_THING_CONNECT_ROOT" ||
+      thingConnectSource === "managed config") &&
+    !deviceKit.structureReady;
+  if (
+    thingConnectSource !== "explicit --thing-connect-root" &&
+    (versionedKitMismatch || staleManagedReference)
+  ) {
+    thingConnectFallback = `${thingConnectSource}: ${thingConnectRoot}`;
+    requestedThingConnect = managedThingConnect;
+    thingConnectSource = "managed Device Kit";
+    normalizedThingConnect = normalizeThingConnectRoot(requestedThingConnect);
+    thingConnectRoot =
+      normalizedThingConnect || resolve(requestedThingConnect);
+    deviceKit = inspectDeviceKit(thingConnectRoot);
+  }
 
   const active = currentIdf(environment);
   let idfDir;
@@ -459,6 +538,8 @@ function setupContext(options, runtime) {
     ? { ...active, directoryReady: directoryIdf.ready }
     : { ...directoryIdf, root: idfDir, directoryReady: directoryIdf.ready };
 
+  const skillTarget = join(options.skillsDir, runtime.platform.skill);
+  const skillVersion = readSkillVersion(skillTarget);
   return {
     activeIdf: active,
     configPath,
@@ -468,9 +549,17 @@ function setupContext(options, runtime) {
     idfToolsPath,
     managedThingConnect,
     rootDir: options.rootDir,
-    skillTarget: join(options.skillsDir, runtime.platform.skill),
+    deviceKit,
+    skillReady:
+      existsSync(join(skillTarget, "SKILL.md")) &&
+      skillVersion === runtime.packageVersion,
+    skillTarget,
+    skillVersion,
     skillsDir: options.skillsDir,
-    thingConnectReady: thingConnectReady(thingConnectRoot),
+    thingConnectFallback,
+    thingConnectManaged:
+      resolve(thingConnectRoot) === resolve(managedThingConnect),
+    thingConnectReady: deviceKit.ready,
     thingConnectRoot,
     thingConnectSource,
   };
@@ -479,15 +568,29 @@ function setupContext(options, runtime) {
 function printState(context, runtime) {
   printCheck("INFO", "setup root", context.rootDir);
   printCheck(
-    existsSync(join(context.skillTarget, "SKILL.md")) ? "PASS" : "MISS",
+    context.skillReady ? "PASS" : "MISS",
     "Codex Skill",
-    context.skillTarget,
+    `${context.skillTarget} (version ${
+      context.skillVersion || "missing"
+    }; expected ${runtime.packageVersion})`,
   );
+  const kitVersion = context.deviceKit.manifestPresent
+    ? context.deviceKit.version || "invalid manifest"
+    : "legacy workspace (unversioned)";
   printCheck(
     context.thingConnectReady ? "PASS" : "MISS",
     "ESP32 Device Kit",
-    `${context.thingConnectRoot} (${context.thingConnectSource})`,
+    `${context.thingConnectRoot} (${context.thingConnectSource}; version ${
+      kitVersion
+    }; expected ${ESP32_KIT.version})`,
   );
+  if (context.thingConnectFallback) {
+    printCheck(
+      "INFO",
+      "ignored stale Kit reference",
+      context.thingConnectFallback,
+    );
+  }
   printCheck(
     context.idf.ready ? "PASS" : "MISS",
     "ESP-IDF",
@@ -534,10 +637,19 @@ function printSystemDependencyHelp(missing) {
 
 function installSkill(options, context, runtime) {
   const present = existsSync(join(context.skillTarget, "SKILL.md"));
-  if (present && !options.forceSkill) {
-    console.log(`SKIP  Codex Skill already exists: ${context.skillTarget}`);
+  if (present && context.skillReady && !options.forceSkill) {
+    console.log(
+      `SKIP  Codex Skill ${runtime.packageVersion} already exists: ${context.skillTarget}`,
+    );
     return;
   }
+  if (present && !options.forceSkill) {
+    throw new Error(
+      `Codex Skill at ${context.skillTarget} has version ${
+        context.skillVersion || "missing"
+      }, expected ${runtime.packageVersion}; rerun with --force-skill to replace it`,
+    );
+  }
   const args = [
     runtime.cliPath,
     "install",
@@ -560,9 +672,14 @@ function installDeviceKit(options, context, runtime) {
     );
     return context.thingConnectRoot;
   }
-  if (context.thingConnectSource !== "managed Device Kit") {
+  if (!context.thingConnectManaged) {
+    const reason =
+      context.deviceKit.manifestError ||
+      (context.deviceKit.manifestPresent
+        ? `version ${context.deviceKit.version || "missing"}; expected ${ESP32_KIT.version}`
+        : "missing generator or TiRTC SDK");
     throw new Error(
-      `${context.thingConnectSource} does not contain a complete ESP32 Device Kit: ${context.thingConnectRoot}`,
+      `${context.thingConnectSource} is not a compatible ESP32 Device Kit (${reason}): ${context.thingConnectRoot}`,
     );
   }
   if (existsSync(context.managedThingConnect)) {
@@ -577,9 +694,10 @@ function installDeviceKit(options, context, runtime) {
   }
   runOrThrow(process.execPath, args, { environment: runtime.environment });
   const root = normalizeThingConnectRoot(context.managedThingConnect);
-  if (!thingConnectReady(root)) {
+  const installedKit = inspectDeviceKit(root);
+  if (!installedKit.ready || installedKit.version !== ESP32_KIT.version) {
     throw new Error(
-      `installed ESP32 Device Kit is missing its generator or TiRTC SDK: ${context.managedThingConnect}`,
+      `installed ESP32 Device Kit is incomplete or has the wrong version: ${context.managedThingConnect}`,
     );
   }
   return root;
@@ -658,6 +776,9 @@ function runDoctor(context, runtime) {
     context.thingConnectRoot,
     "--require-workspace",
   ];
+  if (context.deviceKit.manifestPresent) {
+    args.push("--expected-kit", ESP32_KIT.version);
+  }
   let result;
   if (context.idfDir && existsSync(join(context.idfDir, "export.sh"))) {
     result = activatedResult(
@@ -691,7 +812,7 @@ function runDoctor(context, runtime) {
 
 function isReady(context) {
   return (
-    existsSync(join(context.skillTarget, "SKILL.md")) &&
+    context.skillReady &&
     context.thingConnectReady &&
     context.idf.ready
   );
@@ -729,7 +850,7 @@ export function runEsp32Setup(args, input) {
     if (!isReady(context)) {
       console.log("OVERALL: NEEDS_SETUP");
       console.log(
-        "NEXT: npx tirtc-device-builder@latest setup esp32 --install",
+        `NEXT: npx tirtc-device-builder@${runtime.packageVersion} setup esp32 --install`,
       );
       return 1;
     }
@@ -756,7 +877,12 @@ export function runEsp32Setup(args, input) {
   try {
     installSkill(options, context, runtime);
     const thingConnectRoot = installDeviceKit(options, context, runtime);
-    context = { ...context, thingConnectRoot, thingConnectReady: true };
+    context = {
+      ...context,
+      deviceKit: inspectDeviceKit(thingConnectRoot),
+      thingConnectRoot,
+      thingConnectReady: true,
+    };
     installIdf(context, runtime);
     context = setupContext(options, {
       ...runtime,

package/package.json

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

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

@@ -9,9 +9,9 @@ Turn board evidence into an evidence-backed ESP-IDF project. Treat the Hardware
 
 ## Start
 
-1. Read [environment.md](references/environment.md). For a first-time setup or a request to check/install prerequisites, prefer `npx tirtc-device-builder@latest setup esp32`. Run its `--install` mode only when the user explicitly authorizes installation at the displayed destinations. The installer may create user-space files but never grants permission for `sudo` or persistent shell-profile edits.
-2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. Treat its manifest and packaged protocol documents as the generation facts. If the user explicitly supplies a full ThingConnect source workspace, also read its applicable `AGENTS.md`.
-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.
+1. Read this Skill's `VERSION` file and [environment.md](references/environment.md). Record the `VERSION` value as the installed Skill version; never infer it from the prompt or an npm command run elsewhere. For a first-time setup or a request to check/install prerequisites, prefer `npx tirtc-device-builder@latest setup esp32`. Run its `--install` mode only when the user explicitly authorizes installation at the displayed destinations. The installer may create user-space files but never grants permission for `sudo` or persistent shell-profile edits.
+2. Locate the versioned ESP32 Device Kit root containing `device-sim/` using the explicit input, `TIRTC_THING_CONNECT_ROOT`, the managed setup configuration, or workspace discovery. For a managed Kit, read `manifest.json`, require its exact expected `kit_version`, and treat its manifest and packaged protocol documents as generation facts. An older but structurally complete Kit is not compatible. If the user explicitly supplies an unversioned full ThingConnect source workspace, treat it as legacy input and also read its applicable `AGENTS.md`.
+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 `--expected-kit <kit-version> --require-workspace` for managed-Kit generation; 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 --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.
@@ -40,4 +40,4 @@ For HIL assessment, run `hardware_ir.py assess --phase hil --artifact-sha256 <sh
 
 ## Finish
 
-After the final assessment, remove the machine-bound `build/` tree without rebuilding, then run `project_portability.py <project> --export` against the source plus the project-relative `artifacts/` copies. 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.
+After the final assessment, remove the machine-bound `build/` tree without rebuilding, then run `project_portability.py <project> --export` against the source plus the project-relative `artifacts/` copies. Resolve every missing or Git-ignored required input reported by that check; local intermediate artifacts may remain ignored, but retained build evidence must survive export. 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/VERSION

@@ -0,0 +1 @@
+0.7.3

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

@@ -40,6 +40,7 @@
   "shared_clock": {
     "gpios": [38, 14, 13],
     "directions_simultaneous": false,
+    "paired_channels": false,
     "handoff": "release_before_claim"
   },
   "implementation_assertions": [

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

@@ -7,7 +7,7 @@ $tirtc-esp32-builder
 前置条件（必须由开发者在启动本次 Codex 会话前完成，不属于本提示词内的操作）：
 
 ```bash
-npx --yes tirtc-device-builder@0.7.1 setup esp32 --install --force-skill
+npx --yes tirtc-device-builder@0.7.3 setup esp32 --install --force-skill
 ```
 
 该命令只允许在当前用户目录安装固定版本的 Skill、managed ESP32 Device Kit、ESP-IDF 和工具链；禁止 sudo、系统级包变更和修改 shell profile。安装完成后，开发者必须关闭原 Codex 会话，再从本 clean-room 工作区启动一个新会话，然后粘贴本提示词。
@@ -15,11 +15,11 @@ npx --yes tirtc-device-builder@0.7.1 setup esp32 --install --force-skill
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.7.1 --version
-npx --yes tirtc-device-builder@0.7.1 setup esp32
+npx --yes tirtc-device-builder@0.7.3 --version
+npx --yes tirtc-device-builder@0.7.3 setup esp32
 ```
 
-必须确认 npm 包/Plugin/Skill 为 0.7.1、Device Kit 为 1.1.1，且 Doctor `OVERALL: PASS`。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
+必须根据命令的实际输出和本机文件确认：npm 包为 0.7.3、已安装 Skill 的 `VERSION` 为 0.7.3、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、Skill 是在当前会话启动后才安装，或环境检查未通过，停止并报告前置条件不成立；不要在当前会话中替换 Skill 后继续生成工程。
 
 工作区与 clean-room 边界：
 - 将启动 Codex 时的当前目录定义为 `WORKSPACE_ROOT`。

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

@@ -10,12 +10,32 @@ 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;
+- per-direction slot count and slot bit width when simultaneous directions use
+  different framing modes;
 - 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;
+- paired-channel ownership and equal BCLKs per frame when one controller runs
+  simultaneous standard TX and TDM RX;
+- when AEC is selected, the hardware sample rate plus distinct microphone and
+  playback-reference slots/signals;
 - 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.
 
+Simultaneous directions do not have to use the same ESP-IDF mode name. A valid
+mixed-mode topology must set `shared_clock.paired_channels=true`, use the same
+controller, and provide `slot_count` plus `slot_bit_width` for both directions;
+their products must match. For example, four 16-bit TDM RX slots and two 32-bit
+standard TX slots both consume 64 BCLKs per frame. This exception does not allow
+two independent masters to drive shared clock GPIOs.
+
+For hardware-reference AEC, add `echo_cancellation` with `enabled`,
+`sample_rate_hz`, `microphone_slot`/`microphone_signal`, and
+`reference_slot`/`reference_signal`. The gate verifies that AEC runs while both
+directions are active, uses the hardware clock rate, and maps two distinct TDM
+signals. Implementation assertions must still bind the contract to the paired
+channel setup, AEC library configuration, and exact slot extraction code.
+
 ## Mandatory gate
 
 Run the gate before claiming an audio-capable build:
@@ -44,8 +64,10 @@ 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.
+4. simultaneous mixed framing has equal BCLKs per frame and any AEC reference is
+   mapped to a distinct evidenced slot;
+5. its adapter assertions pass;
+6. the gate is part of the ordinary build;
+7. the exact BIN/ELF is hashed after that build.
 
 Compilation without this gate is `COMPILE_PASS`, not audio `BUILD_VERIFIED`.

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

@@ -16,7 +16,7 @@ The automatic branch never runs `sudo` or modifies a persistent shell profile. W
 When `<setup-root>/env.sh` exists, use it only as an activation prefix for the current command:
 
 ```bash
-bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --target esp32s3 --require-workspace'
+bash -lc '. "<setup-root>/env.sh" && python3 "<skill-dir>/scripts/doctor.py" --expected-idf 5.5 --expected-kit 1.1.1 --target esp32s3 --require-workspace'
 ```
 
 The helper contains paths, not device or network credentials. Read `<setup-root>/config.json` when exact managed paths are needed; the environment helper does not authorize unrelated downloads, shell-profile changes, flashing, or credential writes.
@@ -26,6 +26,7 @@ Run the doctor before generation, build, flash, or monitor:
 ```bash
 python3 <skill-dir>/scripts/doctor.py \
   --expected-idf 5.5 \
+  --expected-kit 1.1.1 \
   --target esp32s3 \
   --require-workspace
 ```
@@ -34,7 +35,11 @@ Add `--project <generated-project>` after generation so the doctor can compare `
 
 ## ESP32 Device Kit
 
-The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. Resolve the generation root in this order:
+The automatic setup downloads a versioned minimal Kit instead of cloning the ThingConnect server repository. A managed Kit is ready only when its generator and SDK files exist and `manifest.json` declares the exact pinned `kit_version`. A stale environment or managed configuration that points at an older Kit is ignored in favor of the current versioned managed path. The setup configuration records the version read from that manifest; it never substitutes the desired version for the actual one.
+
+The installed Skill has its own `<skill-dir>/VERSION` marker. Setup requires it to equal the npm package version and reports both values. Replacing a missing or mismatched marker requires the explicit `--install --force-skill` flow and a new Codex session.
+
+For an explicitly selected legacy workspace, omit `--expected-kit`; otherwise resolve the generation root in this order:
 
 1. an explicit `--thing-connect-root <path>`;
 2. `TIRTC_THING_CONNECT_ROOT`;
@@ -53,6 +58,13 @@ python3 <skill-dir>/scripts/project_portability.py <generated-project> --export
 
 Copy source inputs only. Never export `build/`: CMake caches absolute source, toolchain, and Python paths from the originating machine. `managed_components/` may be regenerated from the committed `dependencies.lock`; the bundled `third_party/tirtc` SDK and its build contract must remain in the source package. CMake must invoke shell gates through `bash <script>` so the build does not depend on archive- or filesystem-specific executable bits.
 
+The export check also requires Hardware IR, every requested-feature semantic
+contract, `sdkconfig.defaults`, a referenced custom partition table, and each
+artifact retained in `build_evidence.artifacts[]`. Inside a Git worktree these
+inputs must not be untracked files hidden by `.gitignore`. Ignore local build
+trees and intermediate firmware snapshots, then explicitly include the exact
+validated release bundle used by retained evidence.
+
 ## Required checks
 
 - `python3`, `git`, `idf.py`, and the target compiler are available in the active shell;

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

@@ -10,6 +10,11 @@ python3 <skill-dir>/scripts/hardware_ir.py init <output>/hardware-ir.json
 
 The initializer creates schema v2. The validator still accepts schema v1 for existing H.264-only projects; update new or materially changed boards to v2.
 
+Schema v1 cannot represent an MJPEG/H.265 selection, semantic-contract paths,
+or artifact-bound v2 HIL. If an existing v1 project requests H5 video without
+an available H.264 path, migrate it to v2 rather than interpreting the legacy
+H.264 assessment failure as a board or platform codec failure.
+
 ## Evidence rules
 
 - Give every source a stable `id`, `kind`, `location`, and revision when available.

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

@@ -13,6 +13,17 @@ Record the selected video profile, audio formats and stream IDs, duplex/AEC poli
 - I2S/audio: record controller, GPIO, master/slave mode, clocks, DMA, channel/TDM slot to physical-signal mapping, and shared-signal handoff. A codec name or I2C address does not prove the audio path.
 - Realtime camera path: record DMA/event queues, task core/priority, and competing Wi-Fi work. Treat queue overflows as scheduling or throughput evidence, then change one variable per HIL comparison.
 
+Distinguish the camera driver's event task from an adapter-owned software
+JPEG/H.26x task. Core isolation of the driver does not prove that a CPU-bound
+encoder is isolated. On ESP32-S3, code using floating point can cause an
+unpinned task to become pinned to the first core where it uses the FPU; AEC and
+other DSP tasks therefore need intentional affinity when they would otherwise
+land on the Wi-Fi core. A DMA-fed loop or software encoder that can remain
+continuously runnable must block on a queue/semaphore or yield at a bounded
+frame boundary. Keep the idle-task watchdog enabled, and expose maximum
+processing time plus deadline misses instead of hiding starvation by widening
+or disabling the watchdog.
+
 Turn every discovered invariant that can regress into a focused test or post-link gate. Generate board-specific values with the project; keep the Skill generic.
 
 ## Wi-Fi credentials and device binding
@@ -38,6 +49,13 @@ Platform service discovery and the TiRTC SDK service endpoint are different sett
 
 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.
 
+Treat PSRAM framebuffer placement, direct peripheral DMA into PSRAM, and an
+internal-DMA staging buffer as three separate facts. PSRAM capacity does not
+prove DMA compatibility or frame integrity for a sensor/pixel format. Promote
+direct PSRAM DMA only after artifact-bound HIL checks image boundaries and line
+integrity; otherwise retain the evidenced staging path and budget its internal
+DMA reserve explicitly.
+
 ## Network and media evidence
 
 Disable Wi-Fi power saving for the realtime baseline unless the product contract says otherwise. Record BSSID, channel, RSSI, reconnect/roaming events, media counters, queue watermarks, camera overflows, internal heap, and largest block. Establish a strong, stable AP baseline before controlled weak-network testing.
@@ -47,3 +65,10 @@ Confirm SDK send return semantics and callback payload lifetimes from the select
 ## Artifact discipline
 
 Record BIN/ELF SHA-256 for every build used in HIL. Runtime evidence applies only to the exact artifact. Diagnose one failing invariant, make the smallest correction, rerun that layer, and preserve the comparison in the report.
+
+Local intermediate snapshots may be ignored, but the Hardware IR, semantic
+contracts, `dependencies.lock`, custom partition input, and the artifact named
+by retained build evidence must survive the chosen export mechanism. Broad
+`*.json`, `*.csv`, or `artifacts/` ignore rules are invalid when they hide an
+untracked required input; `project_portability.py --export` checks this when the
+project is inside a Git worktree.

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

@@ -192,18 +192,114 @@ def check_topology(contract: dict[str, Any], errors: list[str]) -> None:
         )
     if simultaneous is False and handoff == "none":
         errors.append("half-duplex shared clocks require an explicit handoff")
+    if simultaneous is True and handoff != "none":
+        errors.append("simultaneous directions must not use a clock handoff")
+    paired_channels = shared.get("paired_channels", False)
+    if not isinstance(paired_channels, bool):
+        errors.append("shared_clock.paired_channels must be true or false")
+        paired_channels = False
+
+    mixed_paired_ok = False
     if simultaneous is True and capture.get("mode") != playback.get("mode"):
-        errors.append("simultaneous directions cannot use different I2S modes")
+        if paired_channels is not True:
+            errors.append(
+                "simultaneous mixed I2S modes require shared_clock.paired_channels=true"
+            )
+        if capture.get("controller") != playback.get("controller"):
+            errors.append(
+                "simultaneous mixed I2S modes require paired directions on one controller"
+            )
+        frame_bits: dict[str, int] = {}
+        for endpoint, label in ((capture, "capture"), (playback, "playback")):
+            slots = require_positive_int(
+                endpoint.get("slot_count"), f"{label}.slot_count", errors
+            )
+            width = require_positive_int(
+                endpoint.get("slot_bit_width"),
+                f"{label}.slot_bit_width",
+                errors,
+            )
+            if slots is not None and width is not None:
+                frame_bits[label] = slots * width
+        if len(frame_bits) == 2 and frame_bits["capture"] != frame_bits["playback"]:
+            errors.append(
+                "simultaneous mixed I2S modes require equal BCLKs per frame: "
+                f"capture={frame_bits['capture']} playback={frame_bits['playback']}"
+            )
+        mixed_paired_ok = (
+            paired_channels is True
+            and capture.get("controller") == playback.get("controller")
+            and len(frame_bits) == 2
+            and frame_bits["capture"] == frame_bits["playback"]
+        )
     if (
         capture.get("controller") == playback.get("controller")
         and capture.get("mode") != playback.get("mode")
+        and not mixed_paired_ok
         and handoff != "delete_recreate"
     ):
         errors.append(
             "one I2S controller cannot retain different capture/playback modes; "
-            "use distinct controllers or delete_recreate handoff"
+            "use paired frame-compatible directions, distinct controllers, or "
+            "delete_recreate handoff"
         )
 
+    aec_value = contract.get("echo_cancellation")
+    if aec_value is None:
+        return
+    aec = require_mapping(aec_value, "echo_cancellation", errors)
+    enabled = aec.get("enabled")
+    if not isinstance(enabled, bool):
+        errors.append("echo_cancellation.enabled must be true or false")
+        return
+    if not enabled:
+        return
+    if simultaneous is not True:
+        errors.append("echo cancellation requires simultaneous capture and playback")
+    if capture_mode != "tdm":
+        errors.append("echo cancellation reference mapping requires TDM capture")
+    sample_rate = require_positive_int(
+        aec.get("sample_rate_hz"), "echo_cancellation.sample_rate_hz", errors
+    )
+    clock = contract.get("clock", {})
+    if sample_rate is not None and sample_rate != clock.get("sample_rate_hz"):
+        errors.append("echo cancellation sample rate must match the hardware clock")
+
+    microphone_slot = aec.get("microphone_slot")
+    reference_slot = aec.get("reference_slot")
+    microphone_signal = require_nonempty_string(
+        aec.get("microphone_signal"), "echo_cancellation.microphone_signal", errors
+    )
+    reference_signal = require_nonempty_string(
+        aec.get("reference_signal"), "echo_cancellation.reference_signal", errors
+    )
+    slot_signals = capture.get("slot_signals")
+    slot_count = capture.get("slot_count")
+    for slot, signal, label in (
+        (microphone_slot, microphone_signal, "microphone"),
+        (reference_slot, reference_signal, "reference"),
+    ):
+        if (
+            isinstance(slot, bool)
+            or not isinstance(slot, int)
+            or slot < 0
+            or not isinstance(slot_count, int)
+            or slot >= slot_count
+        ):
+            errors.append(
+                f"echo_cancellation.{label}_slot must select an available TDM slot"
+            )
+        elif isinstance(slot_signals, list) and slot < len(slot_signals):
+            if signal != slot_signals[slot]:
+                errors.append(
+                    f"echo_cancellation.{label}_signal does not match "
+                    f"capture.slot_signals at slot {slot}"
+                )
+    if microphone_slot == reference_slot:
+        errors.append("echo cancellation microphone and reference slots must differ")
+    if microphone_signal is not None and microphone_signal == reference_signal:
+        errors.append("echo cancellation microphone and reference signals must differ")
+
 
 def check_assertions(
     project: Path,
@@ -277,11 +373,15 @@ def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
     check_topology(contract, errors)
     check_assertions(project, contract, errors, inputs)
     clock = contract.get("clock", {})
+    shared = contract.get("shared_clock", {})
+    aec = contract.get("echo_cancellation", {})
     return {
         "ok": not errors,
         "summary": (
             f"sample_rate={clock.get('sample_rate_hz')}Hz "
-            f"mclk={clock.get('mclk_hz')}Hz ratio={clock.get('mclk_ratio')}"
+            f"mclk={clock.get('mclk_hz')}Hz ratio={clock.get('mclk_ratio')} "
+            f"simultaneous={shared.get('directions_simultaneous')} "
+            f"aec={aec.get('enabled', False)}"
         ),
         "inputs": inputs,
         "errors": errors,

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

@@ -27,6 +27,7 @@ GENERATOR_RELATIVE_PATH = Path("device-sim/scripts/create_esp32_project.py")
 DEFAULT_SDK_RELATIVE_PATH = Path(
     "device-sim/sdk/espressif-esp32s3/2.3.0"
 )
+DEVICE_KIT_MANIFEST = "manifest.json"
 
 
 def check(name: str, status: str, detail: str, required: bool = True) -> dict[str, Any]:
@@ -166,6 +167,43 @@ def normalize_thing_connect_root(candidate: Path) -> Path | None:
     return None
 
 
+def inspect_device_kit(root: Path | None) -> dict[str, str | bool | None]:
+    """Read the managed Kit identity without rejecting legacy workspaces."""
+    if root is None:
+        return {
+            "manifest_present": False,
+            "version": None,
+            "error": "Device Kit root is unresolved",
+        }
+    manifest_path = root / DEVICE_KIT_MANIFEST
+    if not manifest_path.is_file():
+        return {
+            "manifest_present": False,
+            "version": None,
+            "error": None,
+        }
+    try:
+        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {
+            "manifest_present": True,
+            "version": None,
+            "error": f"invalid {manifest_path}: {exc}",
+        }
+    version = payload.get("kit_version") if isinstance(payload, dict) else None
+    if not isinstance(version, str) or not version.strip():
+        return {
+            "manifest_present": True,
+            "version": None,
+            "error": f"{manifest_path} does not declare kit_version",
+        }
+    return {
+        "manifest_present": True,
+        "version": version.strip(),
+        "error": None,
+    }
+
+
 def find_thing_connect_root(
     explicit: Path | None,
     project: Path | None,
@@ -273,27 +311,51 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
         args.thing_connect_root,
         args.project,
     )
-    workspace_status = "PASS" if thing_connect_root else (
-        "FAIL" if args.require_workspace else "WARN"
-    )
+    kit_identity = inspect_device_kit(thing_connect_root)
+    kit_error = kit_identity["error"]
+    actual_kit = kit_identity["version"]
+    if thing_connect_root is None:
+        workspace_status = "FAIL" if args.require_workspace or args.expected_kit else "WARN"
+        workspace_detail = (
+            f"not found; pass --thing-connect-root or set {THING_CONNECT_ENV}"
+        )
+    elif args.expected_kit and not kit_identity["manifest_present"]:
+        workspace_status = "FAIL"
+        workspace_detail = (
+            f"{thing_connect_root} ({thing_connect_source}) is an unversioned legacy "
+            f"workspace; expected managed Device Kit {args.expected_kit}"
+        )
+    elif kit_error:
+        workspace_status = "FAIL"
+        workspace_detail = str(kit_error)
+    elif args.expected_kit and actual_kit != args.expected_kit:
+        workspace_status = "FAIL"
+        workspace_detail = (
+            f"version {actual_kit or 'missing'} at {thing_connect_root} "
+            f"({thing_connect_source}); expected {args.expected_kit}"
+        )
+    else:
+        workspace_status = "PASS"
+        version_detail = (
+            f"version {actual_kit}"
+            if actual_kit
+            else "unversioned legacy workspace"
+        )
+        workspace_detail = (
+            f"{version_detail} at {thing_connect_root} ({thing_connect_source})"
+        )
     checks.append(
         check(
             "ESP32 Device Kit",
             workspace_status,
-            (
-                f"{thing_connect_root} ({thing_connect_source})"
-                if thing_connect_root
-                else (
-                    f"not found; pass --thing-connect-root or set {THING_CONNECT_ENV}"
-                )
-            ),
-            required=args.require_workspace,
+            workspace_detail,
+            required=args.require_workspace or bool(args.expected_kit),
         )
     )
-    if args.require_workspace and thing_connect_root is None:
+    if (args.require_workspace or args.expected_kit) and workspace_status == "FAIL":
         next_actions.append(
-            "Run setup esp32 --install or pass an existing Device Kit path with "
-            "--thing-connect-root."
+            "Run setup esp32 --install to select the pinned managed Device Kit, or "
+            "pass a matching Kit path with --thing-connect-root."
         )
 
     sdk_dir, sdk_source = resolve_sdk_dir(
@@ -390,6 +452,8 @@ def diagnose(args: argparse.Namespace) -> dict[str, Any]:
     return {
         "overall": overall,
         "expected_idf": args.expected_idf,
+        "expected_kit": args.expected_kit,
+        "device_kit_version": actual_kit,
         "target": args.target,
         "thing_connect_root": (
             str(thing_connect_root) if thing_connect_root is not None else None
@@ -414,6 +478,10 @@ def parse_args() -> argparse.Namespace:
         description="Check ESP-IDF, target tools, TiRTC SDK, project contract, and serial access."
     )
     parser.add_argument("--expected-idf", default="5.5")
+    parser.add_argument(
+        "--expected-kit",
+        help="require an exact managed ESP32 Device Kit manifest version",
+    )
     parser.add_argument("--target", default="esp32s3")
     parser.add_argument("--idf-py", type=Path)
     parser.add_argument("--thing-connect-root", type=Path)

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

@@ -6,6 +6,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any
@@ -13,8 +14,30 @@ from typing import Any
 
 ABSOLUTE_PATH = re.compile(r"(?:^|[\s\"'])(?:/home/|/root/|[A-Za-z]:[\\/])")
 BUILD_INPUT_NAMES = {"CMakeLists.txt", "idf_component.yml", "idf_component.yaml"}
-BUILD_INPUT_SUFFIXES = {".c", ".h", ".cmake", ".py", ".sh"}
+BUILD_INPUT_SUFFIXES = {
+    ".c",
+    ".cmake",
+    ".csv",
+    ".defaults",
+    ".env",
+    ".h",
+    ".json",
+    ".lock",
+    ".py",
+    ".sh",
+    ".txt",
+    ".yaml",
+    ".yml",
+}
 SKIP_PARTS = {"build", "managed_components", ".git"}
+REQUIRED_PROJECT_INPUTS = {
+    "dependencies.lock",
+    "hardware-ir.json",
+    "sdkconfig.defaults",
+}
+PARTITION_FILE_RE = re.compile(
+    r'^CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="([^"]+)"$', re.MULTILINE
+)
 
 
 def source_files(project: Path):
@@ -26,13 +49,156 @@ def source_files(project: Path):
             yield path
 
 
+def project_file(
+    project: Path, value: Any, label: str, errors: list[str]
+) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{label} must be a non-empty project-relative path")
+        return None
+    relative = Path(value)
+    if relative.is_absolute():
+        errors.append(f"{label} must be project-relative, got {value!r}")
+        return None
+    resolved = (project / relative).resolve()
+    if project != resolved and project not in resolved.parents:
+        errors.append(f"{label} escapes project root: {value!r}")
+        return None
+    return resolved
+
+
+def load_hardware_ir(project: Path, errors: list[str]) -> dict[str, Any] | None:
+    path = project / "hardware-ir.json"
+    if not path.is_file():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        errors.append(f"hardware-ir.json is invalid: {exc}")
+        return None
+    if not isinstance(data, dict):
+        errors.append("hardware-ir.json root must be an object")
+        return None
+    return data
+
+
+def required_project_files(
+    project: Path, export: bool, errors: list[str]
+) -> set[Path]:
+    required = {(project / relative).resolve() for relative in REQUIRED_PROJECT_INPUTS}
+    ir = load_hardware_ir(project, errors)
+    if ir is not None:
+        schema_version = ir.get("schema_version")
+        requested = ir.get("features", {}).get("requested", [])
+        if schema_version == 2:
+            resources = ir.get("hardware_resources")
+            if not isinstance(resources, dict):
+                errors.append("hardware-ir.json hardware_resources must be an object")
+            else:
+                contract_fields = ["runtime_semantic_contract"]
+                if {"h5_live_audio", "h5_talkback", "ai_talk"}.intersection(
+                    requested
+                ):
+                    contract_fields.append("audio_semantic_contract")
+                if "h5_live_video" in requested:
+                    contract_fields.append("video_semantic_contract")
+                for field in contract_fields:
+                    path = project_file(
+                        project,
+                        resources.get(field),
+                        f"hardware_resources.{field}",
+                        errors,
+                    )
+                    if path is not None:
+                        required.add(path)
+        elif (
+            schema_version == 1
+            and "h5_live_video" in requested
+            and ir.get("camera", {}).get("h264", {}).get("available") is not True
+        ):
+            errors.append(
+                "schema v1 can only export the legacy H.264 video contract; "
+                "migrate Hardware IR to schema v2 for MJPEG or H.265"
+            )
+
+        if export:
+            artifacts = ir.get("build_evidence", {}).get("artifacts")
+            if not isinstance(artifacts, list) or not artifacts:
+                errors.append(
+                    "hardware-ir.json build_evidence.artifacts must retain at least "
+                    "one verified deliverable for export"
+                )
+            else:
+                for index, record in enumerate(artifacts):
+                    if not isinstance(record, dict):
+                        errors.append(
+                            f"build_evidence.artifacts[{index}] must be an object"
+                        )
+                        continue
+                    path = project_file(
+                        project,
+                        record.get("path"),
+                        f"build_evidence.artifacts[{index}].path",
+                        errors,
+                    )
+                    if path is not None:
+                        required.add(path)
+
+    for config_name in ("sdkconfig.defaults", "sdkconfig"):
+        config = project / config_name
+        if not config.is_file():
+            continue
+        text = config.read_text(encoding="utf-8", errors="replace")
+        match = PARTITION_FILE_RE.search(text)
+        if match:
+            path = project_file(
+                project,
+                match.group(1),
+                f"{config_name} custom partition table",
+                errors,
+            )
+            if path is not None:
+                required.add(path)
+    return required
+
+
+def git_root(project: Path) -> Path | None:
+    result = subprocess.run(
+        ["git", "-C", str(project), "rev-parse", "--show-toplevel"],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+    return Path(result.stdout.strip()).resolve()
+
+
+def git_ignored(root: Path, path: Path) -> bool:
+    try:
+        relative = path.relative_to(root)
+    except ValueError:
+        return False
+    result = subprocess.run(
+        ["git", "-C", str(root), "check-ignore", "--quiet", "--", relative.as_posix()],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        check=False,
+    )
+    return result.returncode == 0
+
+
 def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
     project = project_path.expanduser().resolve()
     errors: list[str] = []
     if not (project / "CMakeLists.txt").is_file():
         return {"ok": False, "errors": ["CMakeLists.txt is missing"]}
-    if not (project / "dependencies.lock").is_file():
-        errors.append("dependencies.lock is missing")
+    required = required_project_files(project, export, errors)
+    for path in sorted(required):
+        if not path.is_file():
+            errors.append(
+                f"required portable input is missing: {path.relative_to(project)}"
+            )
     sdk_required = (
         project / "third_party" / "tirtc" / "include" / "tirtc" / "tiRTC.h",
         project / "third_party" / "tirtc" / "lib" / "libTiRTC.a",
@@ -43,6 +209,15 @@ def check_project(project_path: Path, export: bool = False) -> dict[str, Any]:
         errors.append("bundled TiRTC SDK is incomplete: " + ", ".join(missing_sdk))
     if export and (project / "build").exists():
         errors.append("export source contains a machine-bound build/ directory")
+    if export:
+        root = git_root(project)
+        if root is not None:
+            for path in sorted(required):
+                if path.is_file() and git_ignored(root, path):
+                    errors.append(
+                        "required portable input is ignored by Git: "
+                        f"{path.relative_to(project)}"
+                    )
 
     for path in source_files(project):
         relative = path.relative_to(project)