Merge pull request #47 from NatLabRockies/develop

Release v0.9.0

Author: brianlball

.claude/skills/add-hvac/SKILL.md

@@ -51,6 +51,14 @@ Guide the user through selecting and applying an HVAC system to their model.
 
 6. Report what was created: system name, zones served, equipment types, plant loops.
 
+## Custom HVAC Wiring
+
+For custom HVAC configurations beyond the baseline templates:
+```
+search_wiring_patterns("DOAS")                     # get working Ruby wiring code
+search_api("CoilCoolingFourPipeBeam")              # verify SDK method names
+```
+
 ## Notes
 
 - Get all zone names from `list_thermal_zones()` — names must match exactly

.claude/skills/energy-report/SKILL.md

@@ -12,17 +12,28 @@ Extract all result categories from a completed simulation and present a structur
 
 1. Identify the run. If user provides a run_id, use it. Otherwise check for the most recent simulation.
 
-2. Extract all result categories:
+2. For an HTML report with ~25 sections (fastest):
+   ```
+   generate_results_report(run_id=<id>)
+   ```
+
+3. Or extract individual categories for custom analysis:
    ```
    extract_summary_metrics(run_id=<id>)
    extract_end_use_breakdown(run_id=<id>)
    extract_envelope_summary(run_id=<id>)
    extract_hvac_sizing(run_id=<id>)
    extract_zone_summary(run_id=<id>)
    extract_component_sizing(run_id=<id>)
+   extract_simulation_errors(run_id=<id>)
+   ```
+
+4. For before/after comparison:
+   ```
+   compare_runs(baseline_run_id=<id1>, retrofit_run_id=<id2>)
    ```
 
-3. Optionally run QA/QC:
+5. Optionally run QA/QC:
    ```
    run_qaqc_checks()
    ```

.claude/skills/new-building/SKILL.md

@@ -68,13 +68,13 @@ Step 3 — Typical building (same as Workflow B step 4)
 
 For fully custom buildings not matching DOE prototypes:
 
-1. `create_example_osm(name="<name>")` or `create_baseline_osm(name="<name>")`
-2. Create geometry with `create_space_from_floor_print` + `match_surfaces`
+1. `load_osm_model` an empty model, or start with `create_bar_building` for basic geometry
+2. Create/refine geometry with `create_space_from_floor_print` + `match_surfaces`
 3. Add glazing with `set_window_to_wall_ratio`
 4. Create materials/constructions/loads manually
 5. Add HVAC with `add_baseline_system`
-6. Set weather + design days
-7. Simulate
+6. Set weather with `change_building_location`
+7. Check with `validate_model`, then simulate
 
 ## Simulation
 

.claude/skills/openstudio-patterns/SKILL.md

@@ -32,7 +32,7 @@ Weather (EPW + design days, needed before simulation)
 
 ## Typical Model Build Order
 
-1. **Create or load model** — `create_example_osm` / `create_baseline_osm` / `load_osm_model`
+1. **Create or load model** — `create_new_building` (recommended) / `load_osm_model` / `create_bar_building`
 2. **Geometry** — `create_space_from_floor_print` (preferred) or `create_space` + `create_surface`
 3. **Match surfaces** — `match_surfaces` after all spaces created (finds shared walls)
 4. **Thermal zones** — `create_thermal_zone` with `space_names`
@@ -84,11 +84,29 @@ Weather (EPW + design days, needed before simulation)
 
 | Goal | Tool | Notes |
 |------|------|-------|
-| Quick test model (1 zone) | `create_example_osm` | Minimal geometry, no HVAC |
-| Baseline with HVAC (10 zones) | `create_baseline_osm` | Includes ASHRAE system, geometry, schedules |
-| Custom geometry | `create_space_from_floor_print` | Preferred — auto-creates walls, floor, ceiling from polygon |
-| Explicit surfaces | `create_surface` | Use only when floor print extrusion won't work |
-| Typical building (standards-based) | `create_typical_building` | ComStock measure, adds constructions + loads + HVAC + schedules |
+| Production building model | `create_new_building` | End-to-end: geometry + weather + HVAC + loads. Recommended starting point. |
+| Custom geometry only | `create_bar_building` | Bar geometry from building type/area. Follow with `create_typical_building` for loads+HVAC. |
+| Custom floor plan | `create_space_from_floor_print` | Extrude polygon into 3D space. Use for non-rectangular geometry. |
+| Standards template on existing geometry | `create_typical_building` | Adds constructions + loads + HVAC + schedules to model with geometry. |
+| Import from FloorSpaceJS | `import_floorspacejs` | Load custom geometry JSON, then `create_typical_building` for loads+HVAC. |
+| Quick test (1 zone, no HVAC) | `create_example_osm` | Testing/demos only. |
+| Baseline test (10 zones) | `create_baseline_osm` | Testing/demos only. |
+
+## Pre-Simulation Checklist
+
+Before `run_simulation`, call `validate_model` to verify:
+- Weather file set (EPW)
+- Design days present (from DDY)
+- HVAC assigned to zones
+- Constructions on surfaces
+
+## HVAC Measure Authoring
+
+Before writing measures that create HVAC objects:
+```
+search_api("CoilCoolingFourPipeBeam")       # verify real method names
+search_wiring_patterns("four pipe beam")     # get working connection code
+```
 
 ## Common Error Patterns
 

.claude/skills/qaqc/SKILL.md

@@ -9,13 +9,19 @@ Inspect the current model for common issues before running a simulation.
 
 ## Steps
 
-1. Get model overview:
+1. Quick automated check:
+   ```
+   validate_model()
+   ```
+   Checks weather, design days, HVAC, constructions in one call.
+
+2. Get model overview:
    ```
-   inspect_osm_summary()
    get_model_summary()
+   get_building_info()
    ```
 
-2. Check for missing critical elements:
+3. Check for missing critical elements:
    - **Zones without HVAC:** `list_thermal_zones()` — look for zones with no equipment
    - **Spaces without zones:** `list_spaces()` — look for spaces not assigned to a thermal zone
    - **Missing constructions:** `list_surfaces()` — look for surfaces without constructions

.claude/skills/retrofit/SKILL.md

@@ -65,10 +65,11 @@ extract_end_use_breakdown(run_id=<retrofit_id>)
 ```
 
 ### 5. Compare Results
-Present side-by-side comparison:
-- EUI change (absolute and percentage)
-- End-use breakdown delta (which categories improved)
-- Unmet hours change (ensure comfort wasn't sacrificed)
+```
+compare_runs(baseline_run_id=<baseline_id>, retrofit_run_id=<retrofit_id>)
+```
+Returns EUI delta, per-fuel end-use breakdown, and unmet hours change.
+For manual comparison, use `extract_summary_metrics` on both runs.
 
 ## Notes
 

.claude/skills/tool-workflows/SKILL.md

@@ -120,6 +120,12 @@ extract_summary_metrics(run_id=<retrofit_id>)
 
 See the `measure-authoring` skill for run_body patterns and language guidance.
 
+For HVAC measures, verify methods exist and get wiring code first:
+```
+search_api("CoilCoolingFourPipeBeam")             # check real setter/getter names
+search_wiring_patterns("four pipe beam")           # get working Ruby wiring code
+```
+
 ## Write and Apply a Custom ReportingMeasure
 
 ReportingMeasures run after simulation to analyze SQL results.

.claude/skills/troubleshoot/SKILL.md

@@ -58,6 +58,14 @@ query_timeseries(run_id=..., variable_name="Zone Mean Air Temperature",
     frequency="Hourly", key_value="Zone 1")
 ```
 
+## Verify SDK Methods
+
+If a measure fails due to nonexistent API methods:
+```
+search_api("CoilCoolingFourPipeBeam")              # list real setters/getters
+search_api("BoilerHotWater", method_pattern="Efficiency")
+```
+
 ## Quick Fixes
 
 | Problem | Tool |

.github/workflows/ci.yml

@@ -62,17 +62,17 @@ jobs:
           case ${{ matrix.shard }} in
             1)
               # sim test + component/weather + loop ops + skill_retrofit
-              FILES="tests/test_example_workflows.py tests/test_component_properties.py tests/test_comstock.py tests/test_weather.py tests/test_mcp_seb4.py tests/test_create_constructions.py tests/test_loop_operations.py tests/test_plant_loop_demand.py tests/test_sizing_properties.py tests/test_skill_retrofit.py tests/test_integration.py"
+              FILES="tests/test_example_workflows.py tests/test_component_properties.py tests/test_comstock.py tests/test_weather.py tests/test_weather_files.py tests/test_mcp_seb4.py tests/test_create_constructions.py tests/test_loop_operations.py tests/test_plant_loop_demand.py tests/test_sizing_properties.py tests/test_skill_retrofit.py tests/test_integration.py"
               EXTRA_ENV="-e MCP_OSW_PATH=tests/assets/SEB_model/SEB4_baseboard/workflow.osw -e EXPECTED_EUI=1.8750760248144998 -e EXPECTED_EUI_RTOL=0.02 -e EXPECTED_EUI_ATOL=0.0"
               ;;
             2)
-              # common_measures, hvac_systems, geometry, zone terminal, skill_energy_report, hvac_validation (consolidated)
-              FILES="tests/test_common_measures.py tests/test_hvac_systems.py tests/test_replace_zone_terminal.py tests/test_geometry.py tests/test_bar_building.py tests/test_skill_energy_report.py tests/test_hvac_validation.py"
+              # common_measures, hvac_systems, geometry, zone terminal, skill_energy_report
+              FILES="tests/test_common_measures.py tests/test_hvac_systems.py tests/test_replace_zone_terminal.py tests/test_geometry.py tests/test_skill_energy_report.py"
               EXTRA_ENV=""
               ;;
             3)
               # controls, object mgmt, loads, building, doas, hvac, measures, measure_authoring, skill_qaqc, hvac_supply_wiring
-              FILES="tests/test_component_controls.py tests/test_object_management.py tests/test_generic_access.py tests/test_create_loads.py tests/test_building.py tests/test_doas_system.py tests/test_hvac.py tests/test_measures.py tests/test_measure_authoring.py tests/test_skill_qaqc.py tests/test_hvac_supply_wiring.py tests/test_validate_model.py"
+              FILES="tests/test_component_controls.py tests/test_object_management.py tests/test_generic_access.py tests/test_create_loads.py tests/test_building.py tests/test_doas_system.py tests/test_hvac.py tests/test_measures.py tests/test_measure_authoring.py tests/test_skill_qaqc.py tests/test_hvac_supply_wiring.py tests/test_validate_model.py tests/test_api_reference.py"
               EXTRA_ENV=""
               ;;
             4)
@@ -81,8 +81,8 @@ jobs:
               EXTRA_ENV=""
               ;;
             5)
-              # HVAC supply wiring simulation smoke tests (DOAS, radiant, district, beams)
-              FILES="tests/test_hvac_supply_sim.py"
+              # HVAC supply sim smoke tests + hvac_validation + bar_building + concurrent regression
+              FILES="tests/test_hvac_supply_sim.py tests/test_hvac_validation.py tests/test_bar_building.py tests/test_concurrent_tools.py"
               EXTRA_ENV=""
               ;;
           esac

CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## [0.9.0] - 2026-04-10
+
+### Added
+- **Geometry tools**: `create_bar_building`, `create_new_building`, `import_floorspacejs` for model creation from DOE prototypes and FloorSpaceJS JSON
+- **Generic object access**: `get_object_fields`, `set_object_property`, dynamic `list_model_objects` for any OpenStudio type
+- **Measure authoring skill**: `create_measure`, `edit_measure`, `test_measure` with ReportingMeasure support
+- **Tool routing**: `search_api` (OpenStudio SDK search), `recommend_tools`, `search_wiring_patterns` (24 HVAC wiring recipes)
+- **HVAC components**: FourPipeBeam and CooledBeam air terminals, `set_zone_equipment_priority`
+- **LLM test suite**: 170+ tests across 5 tiers with progressive difficulty (L1 vague / L2 moderate / L3 explicit), cross-model benchmark sweeps (sonnet/opus/haiku), CodeMode A/B comparison
+- **Concurrent tool regression test**: validates MCP responses under concurrent tool calls
+- **Stdout purity test**: validates no C-level pollution on complex 44-zone models
+- **Response-size guardrails**: `max_results` + filters on all list tools, brief mode for large responses
+- **Agent guardrails**: anti-loop instructions in MCP server, tool-bypass prevention
+- Tags on all 142 tools for ToolSearch discovery
+- Enriched tool descriptions for better LLM tool selection
+- `list_weather_files` tool, `validate_model` tool, `extract_simulation_errors` tool
+- `compare_runs` tool for two-simulation comparison
+- CI expanded to 5 shards, ~450+ integration tests
+
+### Fixed
+- **Concurrent tool timeout (issue #42)**: permanent fd redirect replaces racy global middleware — C stdout goes to stderr once at startup, Python sys.stdout gets private fd to MCP client
+- **Polyhedron stdout leak**: OpenStudio geometry engine C++ diagnostics no longer corrupt JSON-RPC stream
+- SWIG memory leak warnings fully suppressed across all callsites
+- Measure XML stale checksums causing OS App rejection
+- Choice-type measure argument validation in wrappers
+- JSON-string list params across 9 affected tools (`parse_str_list()`)
+- `conditioned_floor_area` computed from model instead of hardcoded
+- EUI units now report MJ/m2 + kBtu/ft2 alongside GJ/m2
+
+### Changed
+- `list_files` hardened to `/inputs` + `/runs` only
+- `change_building_location` preferred over `set_weather_file` (sets EPW+DDY+CZ in one call)
+- Consolidated 4 HVAC validation test files into single `test_hvac_validation.py`
+- Consolidated integration tests: -8 files, -57 Docker sessions
+
+## [0.8.2] - 2026-03-28
+
+### Added
+- Tool description enrichment for all 142 tools
+- CodeMode toggle (default off) with LLM harness support
+
+## [0.8.0] - 2026-03-13
+
+### Added
+- Measure authoring skill with test framework
+- SWIG stdout suppression middleware (replaced in 0.9.0)
+- Phase 10 results tools: `extract_simulation_errors`, `list_output_variables`, `compare_runs`
+
+## [0.7.0] - 2026-03-07
+
+### Added
+- LLM agent test suite (170+ tests, local-only)
+- Geometry workflows (FloorSpaceJS import, bar building)
+
+## [0.6.0] - 2026-02-28
+
+### Added
+- Response-size guardrails on all list tools
+- Generic object access (Phase C)
+
+## [0.5.0] - 2026-02-21
+
+### Added
+- Agent guardrails (anti-loop, tool-bypass prevention)
+- Weather file improvements
+
+## [0.4.0] - 2026-02-14
+
+### Added
+- Common measures integration (20 measures, 11 wrapper tools)
+- Context reduction (auto-load, brief mode, batch removal)
+
+## [0.3.0] - 2026-02-07
+
+### Added
+- Initial skills architecture (22 skills, 126 tools)
+- 5-shard CI pipeline
+- OpenStudio SDK 3.11.0 integration