tirtc-device-builder 0.7.2 → 0.7.3

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tirtc-device-builder",
-  "version": "0.7.2",
+  "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,16 @@
 
 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.

package/README.md

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

package/package.json

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

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

@@ -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

@@ -1 +1 @@
-0.7.2
+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.2 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.2 setup esp32 --install --force-skill
 本轮第一步先只读运行：
 
 ```bash
-npx --yes tirtc-device-builder@0.7.2 --version
-npx --yes tirtc-device-builder@0.7.2 setup esp32
+npx --yes tirtc-device-builder@0.7.3 --version
+npx --yes tirtc-device-builder@0.7.3 setup esp32
 ```
 
-必须根据命令的实际输出和本机文件确认：npm 包为 0.7.2、已安装 Skill 的 `VERSION` 为 0.7.2、所选 Device Kit 的 `manifest.json` 中 `kit_version` 为 1.1.1，并且 Doctor 对 `--expected-kit 1.1.1` 输出 `OVERALL: PASS`。Plugin manifest 不属于这种 npm 安装方式的运行时前置条件，不得把不可访问的 Plugin 版本当作阻塞项。如果版本不一致、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

@@ -58,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/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)