tirtc-device-builder 0.5.0 → 0.6.0

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

@@ -0,0 +1,320 @@
+#!/usr/bin/env python3
+"""Verify an ESP32 board audio contract against locked source and adapter files."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+
+PAIR_PATTERN = re.compile(r"\{\s*(\d+)\s*,\s*(\d+)\s*,")
+AUDIO_MODES = {"standard", "tdm", "dsp", "pcm"}
+HANDOFF_POLICIES = {"none", "release_before_claim", "delete_recreate"}
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def project_file(project: Path, value: Any, label: str) -> Path:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{label} must be a non-empty project-relative path")
+    relative = Path(value)
+    if relative.is_absolute():
+        raise ValueError(f"{label} must be project-relative, got {value!r}")
+    resolved = (project / relative).resolve()
+    if project != resolved and project not in resolved.parents:
+        raise ValueError(f"{label} escapes project root: {value!r}")
+    return resolved
+
+
+def require_mapping(value: Any, label: str, errors: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        errors.append(f"{label} must be an object")
+        return {}
+    return value
+
+
+def require_positive_int(value: Any, label: str, errors: list[str]) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        errors.append(f"{label} must be a positive integer")
+        return None
+    return value
+
+
+def require_nonempty_string(value: Any, label: str, errors: list[str]) -> str | None:
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{label} must be a non-empty string")
+        return None
+    return value
+
+
+def check_clock(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    clock = require_mapping(contract.get("clock"), "clock", errors)
+    sample_rate = require_positive_int(
+        clock.get("sample_rate_hz"), "clock.sample_rate_hz", errors
+    )
+    ratio = require_positive_int(clock.get("mclk_ratio"), "clock.mclk_ratio", errors)
+    mclk = require_positive_int(clock.get("mclk_hz"), "clock.mclk_hz", errors)
+    if None not in (sample_rate, ratio, mclk) and sample_rate * ratio != mclk:
+        errors.append(
+            "clock tuple is inconsistent: "
+            f"{sample_rate}Hz x {ratio} != {mclk}Hz"
+        )
+
+    tables = clock.get("codec_tables")
+    if not isinstance(tables, list) or not tables:
+        errors.append("clock.codec_tables must list every clocked codec driver table")
+        return
+    if sample_rate is None or mclk is None:
+        return
+
+    for index, item in enumerate(tables):
+        label = f"clock.codec_tables[{index}]"
+        table = require_mapping(item, label, errors)
+        codec = require_nonempty_string(table.get("codec"), f"{label}.codec", errors)
+        try:
+            source = project_file(project, table.get("source"), f"{label}.source")
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not source.is_file():
+            errors.append(f"{label}.source does not exist: {source}")
+            continue
+        text = source.read_text(encoding="utf-8", errors="replace")
+        pairs = {(int(first), int(second)) for first, second in PAIR_PATTERN.findall(text)}
+        inputs[str(source.relative_to(project))] = sha256_file(source)
+        if not pairs:
+            errors.append(f"{label} contains no C initializer clock pairs")
+        elif (mclk, sample_rate) not in pairs:
+            errors.append(
+                f"{codec or label} rejects selected clock tuple: "
+                f"sample_rate={sample_rate}Hz mclk={mclk}Hz"
+            )
+
+
+def check_endpoint(
+    value: Any,
+    label: str,
+    errors: list[str],
+) -> dict[str, Any]:
+    endpoint = require_mapping(value, label, errors)
+    controller = endpoint.get("controller")
+    if isinstance(controller, bool) or not isinstance(controller, int) or controller < 0:
+        errors.append(f"{label}.controller must be an integer >= 0")
+    mode = endpoint.get("mode")
+    if mode not in AUDIO_MODES:
+        errors.append(f"{label}.mode must be one of {', '.join(sorted(AUDIO_MODES))}")
+    role = endpoint.get("role")
+    if role not in {"master", "slave"}:
+        errors.append(f"{label}.role must be master or slave")
+    return endpoint
+
+
+def check_topology(contract: dict[str, Any], errors: list[str]) -> None:
+    capture = check_endpoint(contract.get("capture"), "capture", errors)
+    playback = check_endpoint(contract.get("playback"), "playback", errors)
+
+    capture_mode = capture.get("mode")
+    tdm_enabled = capture.get("tdm_enabled")
+    if not isinstance(tdm_enabled, bool):
+        errors.append("capture.tdm_enabled must be true or false")
+    elif (capture_mode == "tdm") != tdm_enabled:
+        errors.append("capture.mode and capture.tdm_enabled disagree")
+
+    if capture_mode == "tdm":
+        slot_count = require_positive_int(
+            capture.get("slot_count"), "capture.slot_count", errors
+        )
+        slot_order = capture.get("slot_order")
+        slot_signals = capture.get("slot_signals")
+        selected_slot = capture.get("selected_slot")
+        selected_signal = capture.get("selected_signal")
+        if not isinstance(slot_order, list) or not slot_order:
+            errors.append("capture.slot_order must be a non-empty array in TDM mode")
+        if not isinstance(slot_signals, list) or not slot_signals:
+            errors.append("capture.slot_signals must be a non-empty array in TDM mode")
+        if slot_count is not None:
+            if isinstance(slot_order, list) and len(slot_order) != slot_count:
+                errors.append("capture.slot_order length must equal capture.slot_count")
+            if isinstance(slot_signals, list) and len(slot_signals) != slot_count:
+                errors.append("capture.slot_signals length must equal capture.slot_count")
+        if (
+            isinstance(selected_slot, bool)
+            or not isinstance(selected_slot, int)
+            or selected_slot < 0
+            or slot_count is None
+            or selected_slot >= slot_count
+        ):
+            errors.append("capture.selected_slot must select an available TDM slot")
+        elif isinstance(slot_signals, list) and selected_slot < len(slot_signals):
+            if selected_signal != slot_signals[selected_slot]:
+                errors.append(
+                    "capture.selected_signal does not match capture.slot_signals at "
+                    "capture.selected_slot"
+                )
+        require_nonempty_string(
+            capture.get("mapping_evidence"), "capture.mapping_evidence", errors
+        )
+    else:
+        require_nonempty_string(
+            capture.get("mapping_evidence"), "capture.mapping_evidence", errors
+        )
+
+    shared = require_mapping(contract.get("shared_clock"), "shared_clock", errors)
+    gpios = shared.get("gpios")
+    if not isinstance(gpios, list) or not gpios or any(
+        isinstance(gpio, bool) or not isinstance(gpio, int) or gpio < 0 for gpio in gpios
+    ):
+        errors.append("shared_clock.gpios must be a non-empty array of GPIO numbers")
+    simultaneous = shared.get("directions_simultaneous")
+    if not isinstance(simultaneous, bool):
+        errors.append("shared_clock.directions_simultaneous must be true or false")
+    handoff = shared.get("handoff")
+    if handoff not in HANDOFF_POLICIES:
+        errors.append(
+            "shared_clock.handoff must be one of "
+            + ", ".join(sorted(HANDOFF_POLICIES))
+        )
+    if simultaneous is False and handoff == "none":
+        errors.append("half-duplex shared clocks require an explicit handoff")
+    if simultaneous is True and capture.get("mode") != playback.get("mode"):
+        errors.append("simultaneous directions cannot use different I2S modes")
+    if (
+        capture.get("controller") == playback.get("controller")
+        and capture.get("mode") != playback.get("mode")
+        and handoff != "delete_recreate"
+    ):
+        errors.append(
+            "one I2S controller cannot retain different capture/playback modes; "
+            "use distinct controllers or delete_recreate handoff"
+        )
+
+
+def check_assertions(
+    project: Path,
+    contract: dict[str, Any],
+    errors: list[str],
+    inputs: dict[str, str],
+) -> None:
+    assertions = contract.get("implementation_assertions")
+    if not isinstance(assertions, list) or not assertions:
+        errors.append("implementation_assertions must be a non-empty array")
+        return
+    for index, item in enumerate(assertions):
+        label = f"implementation_assertions[{index}]"
+        assertion = require_mapping(item, label, errors)
+        try:
+            source = project_file(project, assertion.get("file"), f"{label}.file")
+        except ValueError as exc:
+            errors.append(str(exc))
+            continue
+        if not source.is_file():
+            errors.append(f"{label}.file does not exist: {source}")
+            continue
+        text = source.read_text(encoding="utf-8", errors="replace")
+        compact = re.sub(r"\s+", "", text)
+        inputs[str(source.relative_to(project))] = sha256_file(source)
+        for field, haystack, present in (
+            ("contains", text, True),
+            ("contains_compact", compact, True),
+            ("absent", text, False),
+            ("absent_compact", compact, False),
+        ):
+            needles = assertion.get(field, [])
+            if not isinstance(needles, list) or any(
+                not isinstance(needle, str) or not needle for needle in needles
+            ):
+                errors.append(f"{label}.{field} must be an array of non-empty strings")
+                continue
+            for needle in needles:
+                found = needle in haystack
+                if found != present:
+                    verb = "missing" if present else "contains forbidden"
+                    errors.append(f"{label} {verb} {field} token: {needle}")
+
+
+def verify_contract(contract_path: Path, project_path: Path) -> dict[str, Any]:
+    project = project_path.expanduser().resolve()
+    contract_file = contract_path.expanduser().resolve()
+    errors: list[str] = []
+    inputs: dict[str, str] = {}
+    if not project.is_dir():
+        return {"ok": False, "errors": [f"project directory does not exist: {project}"]}
+    if not contract_file.is_file():
+        return {"ok": False, "errors": [f"audio contract does not exist: {contract_file}"]}
+    if project != contract_file and project not in contract_file.parents:
+        return {"ok": False, "errors": ["audio contract must be inside the project"]}
+    try:
+        contract = json.loads(contract_file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return {"ok": False, "errors": [f"invalid audio contract: {exc}"]}
+    if not isinstance(contract, dict):
+        return {"ok": False, "errors": ["audio contract root must be an object"]}
+    if contract.get("schema_version") != 1:
+        errors.append("schema_version must be 1")
+    evidence = contract.get("evidence")
+    if not isinstance(evidence, list) or len(evidence) < 2 or any(
+        not isinstance(item, str) or not item for item in evidence
+    ):
+        errors.append("evidence must contain at least two non-empty source IDs")
+    inputs[str(contract_file.relative_to(project))] = sha256_file(contract_file)
+    check_clock(project, contract, errors, inputs)
+    check_topology(contract, errors)
+    check_assertions(project, contract, errors, inputs)
+    clock = contract.get("clock", {})
+    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')}"
+        ),
+        "inputs": inputs,
+        "errors": errors,
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Verify codec clocks, I2S topology, channel mapping, and adapter assertions."
+    )
+    parser.add_argument("contract", type=Path)
+    parser.add_argument("--project", type=Path, required=True)
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--evidence-out", type=Path)
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    result = verify_contract(args.contract, args.project)
+    if args.evidence_out is not None:
+        output = args.evidence_out.expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif result["ok"]:
+        print(f"PASS: audio semantic contract: {result['summary']}")
+    else:
+        for error in result["errors"]:
+            print(f"FAIL: {error}", file=sys.stderr)
+    return 0 if result["ok"] else 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -11,6 +11,9 @@ import sys
 from pathlib import Path
 from typing import Any
 
+from audio_contract import verify_contract as verify_audio_contract
+from video_contract import verify_contract as verify_video_contract
+
 
 FEATURES = {
     "h5_live_audio",
@@ -18,6 +21,8 @@ FEATURES = {
     "h5_talkback",
     "ai_talk",
 }
+AUDIO_FEATURES = {"h5_live_audio", "h5_talkback", "ai_talk"}
+VIDEO_FEATURES = {"h5_live_video"}
 VERIFICATION_LEVELS = {
     "extracted": 1,
     "corroborated": 2,
@@ -220,6 +225,26 @@ def validate_hardware_resources(
     validate_verification(
         i2s.get("verification"), "hardware_resources.i2s.verification", errors
     )
+    audio_contract = resources.get("audio_semantic_contract")
+    nullable_string(
+        audio_contract,
+        "hardware_resources.audio_semantic_contract",
+        errors,
+    )
+    if isinstance(audio_contract, str) and Path(audio_contract).is_absolute():
+        errors.append(
+            "hardware_resources.audio_semantic_contract must be project-relative"
+        )
+    video_contract = resources.get("video_semantic_contract")
+    nullable_string(
+        video_contract,
+        "hardware_resources.video_semantic_contract",
+        errors,
+    )
+    if isinstance(video_contract, str) and Path(video_contract).is_absolute():
+        errors.append(
+            "hardware_resources.video_semantic_contract must be project-relative"
+        )
 
     mapping_section = mapping(
         resources.get("audio_channel_mapping"),
@@ -396,6 +421,27 @@ def validate_runtime_evidence(
         validate_source_refs(record, prefix, source_ids, errors)
 
 
+def validate_build_evidence(data: dict[str, Any], errors: list[str]) -> None:
+    if "build_evidence" not in data:
+        return
+    evidence = mapping(data.get("build_evidence"), "build_evidence", errors)
+    artifacts = evidence.get("artifacts")
+    if not isinstance(artifacts, list):
+        errors.append("build_evidence.artifacts must be an array")
+        return
+    for index, item in enumerate(artifacts):
+        prefix = f"build_evidence.artifacts[{index}]"
+        record = mapping(item, prefix, errors)
+        path_value = record.get("path")
+        nonempty_string(path_value, f"{prefix}.path", errors)
+        if isinstance(path_value, str) and Path(path_value).is_absolute():
+            errors.append(f"{prefix}.path must be project-relative")
+        positive_int(record.get("size_bytes"), f"{prefix}.size_bytes", errors)
+        sha = record.get("sha256")
+        if not isinstance(sha, str) or not SHA256_RE.fullmatch(sha):
+            errors.append(f"{prefix}.sha256 must be a 64-character SHA-256")
+
+
 def validate_ir(data: dict[str, Any]) -> list[str]:
     errors: list[str] = []
     schema_version = data.get("schema_version")
@@ -483,6 +529,7 @@ def validate_ir(data: dict[str, Any]) -> list[str]:
     if schema_version == 2:
         validate_hardware_resources(data, source_ids, errors)
         validate_onboarding(data, source_ids, errors)
+        validate_build_evidence(data, errors)
         validate_runtime_evidence(data, source_ids, errors)
     return errors
 
@@ -818,6 +865,24 @@ def combine_requirements(
     return {"status": status, "reasons": reasons}
 
 
+def constrain_project_gate(
+    project_gate: dict[str, Any], feature_assessments: dict[str, dict[str, Any]]
+) -> None:
+    """Prevent a project-level pass while a requested feature is unresolved."""
+    feature_states = {item["status"] for item in feature_assessments.values()}
+    if "BLOCKED" in feature_states:
+        project_gate["status"] = "BLOCKED"
+        project_gate["reasons"].append("at least one requested feature is blocked")
+    elif (
+        "NEEDS_CONFIRMATION" in feature_states
+        and project_gate["status"] != "BLOCKED"
+    ):
+        project_gate["status"] = "NEEDS_CONFIRMATION"
+        project_gate["reasons"].append(
+            "at least one requested feature still needs confirmation"
+        )
+
+
 def project_requirements(data: dict[str, Any]) -> list[Requirement]:
     requirements: list[Requirement] = []
     revision = data["board"]["hardware_revision"].strip().lower()
@@ -887,11 +952,40 @@ def matching_runtime_evidence(
     return None
 
 
-def artifact_requirement(artifact_sha256: str | None) -> Requirement:
+def matching_build_artifact(
+    data: dict[str, Any], artifact_sha256: str | None
+) -> dict[str, Any] | None:
+    if artifact_sha256 is None:
+        return None
+    normalized = artifact_sha256.lower()
+    build_evidence = data.get("build_evidence", {})
+    if not isinstance(build_evidence, dict):
+        return None
+    artifacts = build_evidence.get("artifacts", [])
+    if not isinstance(artifacts, list):
+        return None
+    for record in artifacts:
+        if (
+            isinstance(record, dict)
+            and str(record.get("sha256", "")).lower() == normalized
+        ):
+            return record
+    return None
+
+
+def artifact_requirement(
+    data: dict[str, Any], 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
+    if matching_build_artifact(data, artifact_sha256) is None:
+        return (
+            "BLOCKED",
+            f"artifact {artifact_sha256} is not present in build_evidence.artifacts",
+            0,
+        )
     return (
         "SATISFIED",
         f"build evidence is bound to artifact {artifact_sha256}",
@@ -903,6 +997,8 @@ def assess_ir(
     data: dict[str, Any],
     artifact_sha256: str | None = None,
     phase: str | None = None,
+    audio_gate: Requirement | None = None,
+    video_gate: Requirement | None = None,
 ) -> dict[str, Any]:
     selected_phase = phase or ("hil" if artifact_sha256 else "intake")
     if selected_phase not in ASSESSMENT_PHASES:
@@ -947,7 +1043,7 @@ def assess_ir(
         resources = {}
 
     if selected_phase in {"build", "hil"}:
-        project.append(artifact_requirement(artifact_sha256))
+        project.append(artifact_requirement(data, artifact_sha256))
 
     for feature in requested:
         if schema_version == 1:
@@ -1010,6 +1106,24 @@ def assess_ir(
                 audio_mapping_requirement(resources, minimum_verification),
                 memory_requirement(resources, minimum_verification),
             ]
+        if feature in AUDIO_FEATURES and selected_phase in {"build", "hil"}:
+            requirements.append(
+                audio_gate
+                or (
+                    "NEEDS_CONFIRMATION",
+                    "audio semantic gate was not executed for this project",
+                    0,
+                )
+            )
+        if feature in VIDEO_FEATURES and selected_phase in {"build", "hil"}:
+            requirements.append(
+                video_gate
+                or (
+                    "NEEDS_CONFIRMATION",
+                    "video semantic gate was not executed for this project",
+                    0,
+                )
+            )
         result[feature] = combine_requirements(
             requirements, success_status=success_status
         )
@@ -1019,6 +1133,7 @@ def assess_ir(
         success_status=success_status,
         legacy_hil_from_levels=(schema_version == 1 and selected_phase == "intake"),
     )
+    build_artifact = matching_build_artifact(data, artifact_sha256)
     evidence = matching_runtime_evidence(data, artifact_sha256)
     if schema_version == 2 and selected_phase == "hil":
         evidence_features = set(evidence.get("features", [])) if evidence else set()
@@ -1046,6 +1161,8 @@ def assess_ir(
                 f"all requested features have matching artifact evidence for {artifact_sha256}"
             )
 
+    constrain_project_gate(project_gate, result)
+
     assessment: dict[str, Any] = {
         "schema_version": schema_version,
         "phase": selected_phase,
@@ -1059,7 +1176,8 @@ def assess_ir(
         assessment["selected_wifi_method"] = selected_wifi
         assessment["selected_binding_method"] = selected_binding
         assessment["artifact_sha256"] = artifact_sha256
-        assessment["artifact_evidence_matched"] = evidence is not None
+        assessment["build_artifact_evidence_matched"] = build_artifact is not None
+        assessment["runtime_artifact_evidence_matched"] = evidence is not None
     return assessment
 
 
@@ -1110,15 +1228,111 @@ def command_assess(args: argparse.Namespace) -> int:
     ):
         print("error: --artifact-sha256 must be a 64-character SHA-256", file=sys.stderr)
         return 2
+    selected_phase = args.phase or (
+        "hil" if args.artifact_sha256 is not None else "intake"
+    )
+    project = (args.project or args.path.parent).expanduser().resolve()
+    audio_gate: Requirement | None = None
+    audio_gate_result: dict[str, Any] | None = None
+    if (
+        data.get("schema_version") == 2
+        and selected_phase in {"build", "hil"}
+        and AUDIO_FEATURES.intersection(data["features"]["requested"])
+    ):
+        relative_contract = data["hardware_resources"].get(
+            "audio_semantic_contract"
+        )
+        if not isinstance(relative_contract, str) or not relative_contract:
+            audio_gate = (
+                "NEEDS_CONFIRMATION",
+                "hardware_resources.audio_semantic_contract is missing",
+                0,
+            )
+            audio_gate_result = {
+                "ok": False,
+                "errors": ["audio semantic contract is missing"],
+            }
+        else:
+            contract = (project / relative_contract).resolve()
+            if project != contract and project not in contract.parents:
+                audio_gate_result = {
+                    "ok": False,
+                    "errors": ["audio semantic contract escapes project root"],
+                }
+            else:
+                audio_gate_result = verify_audio_contract(contract, project)
+            if audio_gate_result["ok"]:
+                audio_gate = (
+                    "SATISFIED",
+                    "audio semantic gate passed: "
+                    + str(audio_gate_result.get("summary", "verified")),
+                    VERIFICATION_LEVELS["build_verified"],
+                )
+            else:
+                audio_gate = (
+                    "BLOCKED",
+                    "audio semantic gate failed: "
+                    + "; ".join(audio_gate_result.get("errors", [])),
+                    0,
+                )
+    video_gate: Requirement | None = None
+    video_gate_result: dict[str, Any] | None = None
+    if (
+        data.get("schema_version") == 2
+        and selected_phase in {"build", "hil"}
+        and VIDEO_FEATURES.intersection(data["features"]["requested"])
+    ):
+        relative_contract = data["hardware_resources"].get(
+            "video_semantic_contract"
+        )
+        if not isinstance(relative_contract, str) or not relative_contract:
+            video_gate = (
+                "NEEDS_CONFIRMATION",
+                "hardware_resources.video_semantic_contract is missing",
+                0,
+            )
+            video_gate_result = {
+                "ok": False,
+                "errors": ["video semantic contract is missing"],
+            }
+        else:
+            contract = (project / relative_contract).resolve()
+            if project != contract and project not in contract.parents:
+                video_gate_result = {
+                    "ok": False,
+                    "errors": ["video semantic contract escapes project root"],
+                }
+            else:
+                video_gate_result = verify_video_contract(contract, project)
+            if video_gate_result["ok"]:
+                video_gate = (
+                    "SATISFIED",
+                    "video semantic gate passed: "
+                    + str(video_gate_result.get("summary", "verified")),
+                    VERIFICATION_LEVELS["build_verified"],
+                )
+            else:
+                video_gate = (
+                    "BLOCKED",
+                    "video semantic gate failed: "
+                    + "; ".join(video_gate_result.get("errors", [])),
+                    0,
+                )
     try:
         assessment = assess_ir(
             data,
             artifact_sha256=args.artifact_sha256,
-            phase=args.phase,
+            phase=selected_phase,
+            audio_gate=audio_gate,
+            video_gate=video_gate,
         )
     except ValueError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    if audio_gate_result is not None:
+        assessment["audio_semantic_gate"] = audio_gate_result
+    if video_gate_result is not None:
+        assessment["video_semantic_gate"] = video_gate_result
     print(json.dumps(assessment, ensure_ascii=False, indent=2))
     if args.strict:
         statuses = {item["status"] for item in assessment["features"].values()}
@@ -1161,6 +1375,11 @@ def parse_args() -> argparse.Namespace:
         "--artifact-sha256",
         help="bind build or HIL assessment to this exact firmware artifact",
     )
+    assess_parser.add_argument(
+        "--project",
+        type=Path,
+        help="generated project root; defaults to the Hardware IR directory",
+    )
     assess_parser.set_defaults(handler=command_assess)
     return parser.parse_args()