Add guardrail for functionalities

Author: yanyanzhu-pnnl

comcheck_api/ai/skill/SKILL.md

@@ -2,10 +2,19 @@
 name: comcheck-api
 description: Use this skill when the user is writing Python code that uses
   the comcheck_api package to build COMcheck project JSON, run compliance
-  simulations against the PNNL COMcheck Web API, or work with envelope,
-  lighting, mechanical, or building-area operations. Triggers on imports
-  of `comcheck_api`, mentions of COMcheck/ASHRAE 90.1/IECC compliance,
-  or requests to validate building energy code compliance.
+  simulations against the PNNL COMcheck Web API, or work with envelope
+  or building-area operations. Triggers on imports of `comcheck_api`,
+  mentions of COMcheck/ASHRAE 90.1/IECC compliance, or requests to
+  validate building energy code compliance.
+
+  NOTE: implemented surface area is the `COMcheckClient` user
+  methods (`list_projects`, `get_project`, `update_project`,
+  `start_run_simulation`, `get_simulation_status`,
+  `get_simulation_result`, `set_api_key`) plus the project-mutation
+  operations for **building areas** and **envelope**. Interior-
+  lighting fixtures (under `activityUse[]`), exterior lighting,
+  mechanical/HVAC, and renewable-energy operations are not
+  available — do not write code that adds, updates, or removes them.
 ---
 
 # COMcheck API Python Client Skill
@@ -30,6 +39,13 @@ Triggers:
   `envelope`, `lighting` (which contains `wholeBldgUse[]` — the
   building areas), `hvac`, `renewable`, and `control` (energy code).
   No `Project`/`Control` PascalCase aliases exist.
+  The fields `hvac`, `renewable`, and the **interior-lighting fixtures
+  inside `activityUse[]`**, plus exterior lighting (`exteriorUse[]`)
+  and the shared `fixtureSchedule[]`, exist on the model but have
+  **no operation functions** — leave them at template defaults. Only
+  `lighting.wholeBldgUse[]` (building areas, including each area's
+  own `interiorLightingSpace` singleton) is mutable, via
+  `project_building_area_operations`.
 - **Operation modules (functional)**: building areas and envelope
   components are added/updated/removed via free functions in
   `project_building_area_operations` and `project_envelope_operations`.
@@ -133,6 +149,21 @@ print(result["performanceRating"])
   bypass the validation logic in the operation modules. Always go
   through `project_envelope_operations` and
   `project_building_area_operations` instead.
+- Don't add, update, or remove interior lighting (the
+  `activityUse[]` fixtures), exterior lighting (`exteriorUse[]`,
+  `fixtureSchedule[]`), HVAC/mechanical, or renewable-energy
+  components — no operations exist for them. The whole-building
+  `interiorLightingSpace` singleton on each `WholeBldgUse` *is*
+  editable through `project_building_area_operations`; the per-
+  activity lighting nested under `activityUse[]` is not. The
+  `COMcheckClient` user methods (`list_projects`, `get_project`,
+  `update_project`, `start_run_simulation`, `get_simulation_status`,
+  `get_simulation_result`, `set_api_key`) are fully supported and
+  fine to use. If asked for an unsupported mutation area, tell the
+  user it's not implemented and offer building-area / envelope /
+  simulation instead. Confirm operation scope with
+  `comcheck_api.list_operations()` (only `building_area` and
+  `envelope` groups exist).
 
 ## Common patterns
 
@@ -228,6 +259,9 @@ else:
 
 ## When you need more detail
 
+- For the authoritative list of what's implemented → call
+  `comcheck_api.list_operations()`. Only operations it returns are
+  supported.
 - For envelope assemblies (roof, walls, floor, windows, doors,
   skylights, thermal bridges) → read `reference/operations.md`.
 - For Pydantic model field-level details → read `reference/types.md`.

comcheck_api/ai/skill/reference/types.md

@@ -13,9 +13,9 @@ aliases exist).
 | `project` | `Project` | Project metadata. Title is `project.project.projectTitle`; address fields use `projectAddress` / `projectCity` / etc. |
 | `location` | `Location` | State, city, climate zone. |
 | `envelope` | `Envelope` | Roofs (`roof[]`), AG walls (`agWall[]`), BG walls (`bgWall[]`), floors, windows, doors, skylights. |
-| `lighting` | `Lighting` | Holds `wholeBldgUse[]` — the **building areas / zones**. Also holds exterior lighting fields. |
-| `hvac` | `HVAC` | Mechanical systems. |
-| `renewable` | `Renewable` | Renewable energy systems. |
+| `lighting` | `Lighting` | Holds `wholeBldgUse[]` — the **building areas / zones**. `wholeBldgUse[]` (including each area's `interiorLightingSpace` singleton) is operable; `activityUse[]`, `exteriorUse[]`, and `fixtureSchedule[]` have no operations. |
+| `hvac` | `HVAC` | Mechanical systems — no operations; not editable via this SDK. |
+| `renewable` | `Renewable` | Renewable energy systems — no operations; not editable via this SDK. |
 | `control` | `Control` | Energy code (`control.code`, e.g. `CEZ_IECC2018`, `CEZ_90_1_2022`). |
 
 Building areas (`WholeBldgUse`) are **not top-level** — they live
@@ -42,13 +42,16 @@ them.
 | Model | Purpose |
 |---|---|
 | `WholeBldgUse` | One building area / zone. Lives in `project.lighting.wholeBldgUse[]`. Has `key`, `areaDescription`, `floorArea`, `ceilingHeight`, `interiorLightingSpace`, etc. |
-| `InteriorLightingSpace` | Lighting configuration for one area. |
+| `InteriorLightingSpace` | Lighting configuration for one area. The singleton attached directly to a `WholeBldgUse` is editable via `update_building_area_in_project`; the same model nested under `activityUse[]` is **not** operable (interior-lighting fixtures live there). |
 
 Every envelope component has a `bldgUseKey` field that ties it to
 one of these area keys.
 
 ## HVAC
 
+⚠️ Documented for shape only — no add/update/remove operations exist
+for any of these models. Leave `project.hvac` at its template default.
+
 | Model | Purpose |
 |---|---|
 | `HVAC` | Container. |

comcheck_api/ai/skill/scripts/validate_code.py

@@ -28,12 +28,58 @@ def _read_input(arg: str) -> str:
     return Path(arg).read_text()
 
 
+UNSUPPORTED_PROJECT_ATTRS = {"hvac", "renewable"}
+UNSUPPORTED_LIGHTING_ATTRS = {
+    "activityUse",
+    "exteriorUse",
+    "fixtureSchedule",
+}
+
+
+def _supported_operation_names() -> set[str]:
+    """Live set of supported operation function names from the SDK."""
+    try:
+        from comcheck_api import list_operations
+    except Exception:  # noqa: BLE001
+        return set()
+    return {op.name for op in list_operations()}
+
+
+def _is_attr_chain(node, head: str, tail: str) -> bool:
+    """True if `node` is `<head>.<tail>` — e.g. `project.hvac`."""
+    import ast
+
+    return (
+        isinstance(node, ast.Attribute)
+        and node.attr == tail
+        and isinstance(node.value, ast.Name)
+        and node.value.id == head
+    )
+
+
+def _is_lighting_chain(node, attr: str) -> bool:
+    """True if `node` is `project.lighting.<attr>`."""
+    import ast
+
+    return (
+        isinstance(node, ast.Attribute)
+        and node.attr == attr
+        and isinstance(node.value, ast.Attribute)
+        and node.value.attr == "lighting"
+        and isinstance(node.value.value, ast.Name)
+        and node.value.value.id == "project"
+    )
+
+
 def validate(code: str) -> dict:
     """Compile-check the provided code and report errors as a dict.
 
-    This is intentionally limited to syntax + import checks for now.
-    Runtime validation (executing the code against a mocked SDK client)
-    is added in a follow-up phase, where the sandbox is hardened.
+    Runs three passes:
+    1. Syntax check via :func:`compile`.
+    2. Import check on every imported module name.
+    3. Scope check that the code only uses operations actually exposed
+       by the SDK and does not mutate the unsupported `hvac`,
+       `renewable`, or non-`wholeBldgUse` lighting subtrees.
     """
     errors: list[dict] = []
 
@@ -68,6 +114,85 @@ def validate(code: str) -> dict:
             except ImportError as e:
                 errors.append({"kind": "import", "module": mod, "message": str(e)})
 
+    # 3. Scope check: cross-reference symbols against list_operations()
+    #    so the guard auto-tracks SDK growth, and forbid direct mutation
+    #    of the unsupported subtrees.
+    supported_ops = _supported_operation_names()
+
+    # Collect the local names that resolve into the operation modules.
+    op_module_aliases: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and node.module == "comcheck_api":
+            for alias in node.names:
+                if alias.name in {
+                    "project_envelope_operations",
+                    "project_building_area_operations",
+                }:
+                    op_module_aliases.add(alias.asname or alias.name)
+        elif isinstance(node, ast.ImportFrom) and node.module == (
+            "comcheck_api.project_operations"
+        ):
+            for alias in node.names:
+                if alias.name in {
+                    "project_envelope_operations",
+                    "project_building_area_operations",
+                }:
+                    op_module_aliases.add(alias.asname or alias.name)
+
+    for node in ast.walk(tree):
+        # Forbid `project.hvac` / `project.renewable` access in any context.
+        if isinstance(node, ast.Attribute) and any(
+            _is_attr_chain(node, "project", attr) for attr in UNSUPPORTED_PROJECT_ATTRS
+        ):
+            errors.append(
+                {
+                    "kind": "unsupported-scope",
+                    "line": node.lineno,
+                    "message": (
+                        f"`project.{node.attr}` has no operations in this SDK; "
+                        "leave it at template defaults."
+                    ),
+                }
+            )
+
+        # Forbid `project.lighting.<unsupported>`.
+        if isinstance(node, ast.Attribute) and any(
+            _is_lighting_chain(node, attr) for attr in UNSUPPORTED_LIGHTING_ATTRS
+        ):
+            errors.append(
+                {
+                    "kind": "unsupported-scope",
+                    "line": node.lineno,
+                    "message": (
+                        f"`project.lighting.{node.attr}` has no operations; "
+                        "only `lighting.wholeBldgUse[]` is editable."
+                    ),
+                }
+            )
+
+        # Calls of the form `<op_module>.<name>(...)` must hit a real op.
+        if (
+            supported_ops
+            and isinstance(node, ast.Call)
+            and isinstance(node.func, ast.Attribute)
+            and isinstance(node.func.value, ast.Name)
+            and node.func.value.id in op_module_aliases
+        ):
+            fn_name = node.func.attr
+            if fn_name not in supported_ops and not fn_name.startswith("_"):
+                errors.append(
+                    {
+                        "kind": "unknown-operation",
+                        "line": node.lineno,
+                        "operation": fn_name,
+                        "message": (
+                            f"`{node.func.value.id}.{fn_name}` is not a supported "
+                            "operation. Run comcheck_api.list_operations() for the "
+                            "current set."
+                        ),
+                    }
+                )
+
     return {"ok": not errors, "errors": errors}