Create scenario_workflow_translation_plan.md

Author: JieXiong9119

docs/scenario_workflow_translation_plan.md

@@ -0,0 +1,210 @@
+# Scenario Workflow Translation Plan
+
+This document is the guiding plan for adding BuildingSync scenario workflow translation to BOSS. It is intended to be merged first, then used as the source of truth for a sequence of focused implementation PRs.
+
+## Goal
+
+Add first-class support for translating BuildingSync `PackageOfMeasures` scenarios into OpenStudio workflows and running those workflows alongside the baseline workflow generated by BOSS today.
+
+The first functional release will:
+
+- Discover BuildingSync package scenarios from `Reports/Report/Scenarios/Scenario/ScenarioType/PackageOfMeasures`.
+- Resolve each package's `MeasureID` references against `Facilities/Facility/Measures/Measure`.
+- Map supported BuildingSync measures to OpenStudio measure steps through a BOSS-owned JSON mapping file.
+- Write the existing baseline workflow plus one scenario workflow for each package scenario with at least one mapped measure.
+- Run baseline and scenario workflows through `OpenStudio::Extension::Runner`.
+- Warn and skip unmapped measures without failing the whole translation.
+
+## Non-Goals
+
+The first release will not:
+
+- Write simulated OpenStudio results back into BuildingSync `ResourceUses`, `AllResourceTotals`, or final XML.
+- Add full multi-facility or multi-site selection beyond the current BOSS assumptions.
+- Dynamically introspect every OpenStudio measure argument.
+- Treat reported BuildingSync savings or costs as simulation inputs unless a mapping explicitly defines that behavior.
+- Add user-supplied mapping files as a required feature.
+
+## Current BOSS Anchors
+
+- Baseline OSW writing starts in `BOSS::Boss.write_baseline_osw` in `lib/BOSS/boss.rb`.
+- Baseline execution starts in `BOSS::Boss.run_baseline_osw` in `lib/BOSS/boss.rb`.
+- BuildingSync XML parsing is centralized in `BOSS::BuildingSyncReader` in `lib/BOSS/buildingsync_reader/buildingsync_reader.rb`.
+- Baseline OpenStudio steps are assembled in `lib/BOSS/osw_arg_populator.rb`.
+- The CLI is Thor-based in `lib/boss_cli.rb`.
+- Existing baseline integration coverage is in `spec/tests/integration/write_and_run_osws_spec.rb`.
+
+## BuildingSync Data Model
+
+Scenario translation should use the first facility supported by BOSS today.
+
+Scenario source:
+
+```text
+BuildingSync/Facilities/Facility/Reports/Report/Scenarios/Scenario
+```
+
+Package source inside a scenario:
+
+```text
+Scenario/ScenarioType/PackageOfMeasures
+```
+
+Measure source:
+
+```text
+BuildingSync/Facilities/Facility/Measures/Measure
+```
+
+Each package scenario should capture at least:
+
+- Scenario ID
+- Scenario name
+- Temporal status
+- Source report ID
+- Package ID
+- Reference case ID, when present
+- Package `MeasureID` IDrefs
+- Linked premises IDrefs, when present
+
+Each measure should capture at least:
+
+- Measure ID
+- `SystemCategoryAffected`
+- Technology category element name
+- `MeasureName`
+- `CustomMeasureName`
+- Linked premises IDrefs
+- Useful cost and savings metadata
+- Implementation status
+
+## Workflow Output Layout
+
+The existing baseline workflow output must remain unchanged:
+
+```text
+<output_path>/baseline/in.osw
+```
+
+Scenario workflows should be written under a dedicated scenario directory:
+
+```text
+<output_path>/scenarios/<scenario_id>/in.osw
+```
+
+Scenario workflows should deep-copy the baseline-generation workflow and append mapped retrofit measure steps. This makes every scenario OSW independently runnable and keeps scenario runs parallel-friendly.
+
+## Mapping Policy
+
+Mappings live in a new BOSS-owned JSON file, planned as:
+
+```text
+lib/BOSS/scenario_measure_map.json
+```
+
+The mapper should prefer this lookup order:
+
+1. `SystemCategoryAffected` plus `MeasureName`
+2. Technology category element plus `MeasureName`, when `SystemCategoryAffected` is absent or unusable
+
+Initial mappings may use the legacy BuildingSync-gem `workflow_maker.json` as background information, but every included measure directory and argument must be verified against BOSS's current OpenStudio measure dependencies before merge.
+
+Conditional arguments should be data-driven. The first supported conditions should come from reader-derived context such as standards building type and principal HVAC/system type. Avoid per-measure Ruby `if`/`elsif` chains.
+
+## Warning Policy
+
+The implementation should return structured warnings and log them consistently. These conditions are warnings, not fatal translation errors:
+
+- Package has no `MeasureIDs`.
+- Package references an unknown measure ID.
+- Measure is missing `SystemCategoryAffected`.
+- Measure is missing a usable technology category.
+- Measure is missing `MeasureName`.
+- Measure category/name cannot be mapped to OpenStudio steps.
+
+If a scenario has at least one mapped measure, write its OSW and include warnings for skipped measures. If a scenario has zero mapped measures, skip that scenario OSW and report the reason clearly.
+
+## PR Sequence
+
+Each PR should be independently reviewable and should not implement later PR scope early unless it is necessary to keep the current PR coherent.
+
+| PR | Title | Scope | Depends On | Green Light | Red Light |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Guiding plan doc | Add this repository plan document. | None | The doc directs PRs 2-18, names acceptance gates, and keeps first-release scope clear. | The doc leaves scenario selection, mapping ownership, warning behavior, or result writeback scope ambiguous. |
+| 2 | Scenario data model and discovery | Add reader-returned structures for first-facility report-level package scenarios. Extract scenario ID, name, temporal status, report ID, package ID, reference case ID, measure IDrefs, and linked premises. | PR 1 | Unit tests prove `building_151.xml` discovers baseline plus all package scenarios and existing reader behavior remains unchanged. | Parser assumes a hardcoded namespace, reads the wrong scenario path, or breaks existing reader tests. |
+| 3 | Facility measure index | Index facility measures by ID and extract category/name metadata plus linked premises, cost/savings fields, and implementation status. | PR 2 | Tests resolve package `MeasureID` references in `building_151.xml` to parsed measure metadata. | Unresolved refs are silently dropped or measures without `TechnologyCategories` crash parsing. |
+| 4 | Parser warning contract | Add structured warnings for missing IDs, unresolved refs, empty packages, missing names, missing categories, and packages with no usable measures. | PR 3 | Tests cover warning cases using `BuildingEQ-1.0.0.xml`, `Golden Test File.xml`, and no-measure fixtures. | Warnings only print to stdout or malformed package data aborts all discovery. |
+| 5 | Initial mapping JSON | Add `lib/BOSS/scenario_measure_map.json` with verified mappings for an initial supported set from `building_151.xml`. | PR 1 | Mapping JSON is valid, and every included entry has source category/name, target `measure_dir_name`, and arguments. | Legacy mappings are copied blindly without checking current OpenStudio measure dirs/args. |
+| 6 | Basic `ScenarioMeasureMapper` | Load JSON, normalize lookup keys, and map one parsed BuildingSync measure to OpenStudio step specs using `SystemCategoryAffected` plus `MeasureName`. | PRs 3, 5 | Mapper unit tests return expected steps and structured unmapped warnings. | Mapper mutates reader data, raises on unmapped measures, or hardcodes rules outside JSON. |
+| 7 | Technology category fallback | Add fallback lookup by technology category plus `MeasureName`. | PR 6 | Tests show fallback mapping works when `SystemCategoryAffected` is absent, while normal lookup priority is preserved. | Fallback changes normal category/name lookup behavior. |
+| 8 | Conditional mapping rules | Add data-driven conditional argument support for building type and principal HVAC/system context. | PR 6 | Tests prove conditions include and exclude arguments predictably. | Implementation becomes a per-measure Ruby condition chain. |
+| 9 | Structured mapping results | Return mapped steps, skipped measure IDs, warnings, and scenario-level write/skip status. | PRs 6-8 | Scenarios with mapped measures are writable; zero-mapped scenarios are skipped with clear warnings. | Callers must infer status from logs or empty arrays. |
+| 10 | Baseline OSW builder refactor | Refactor baseline writing into an internal baseline OSW builder while preserving public behavior. | PR 1 | Existing baseline integration tests pass and generated baseline OSW steps are unchanged. | Existing API, CLI, or baseline output changes unexpectedly. |
+| 11 | Scenario OSW writer API | Add an API that writes baseline plus scenario OSWs for package scenarios with at least one mapped measure. | PRs 9, 10 | Generation tests show expected directories and skipped-scenario reporting. | API writes OSWs for zero-mapped scenarios or disturbs baseline output. |
+| 12 | Scenario workflow step assembly | Deep-copy baseline OSW and append mapped retrofit steps in deterministic order. | PR 11 | OSW tests assert baseline steps plus expected mapped measure steps and arguments. | Scenario workflows omit baseline creation steps, mutate baseline OSW, or use nondeterministic step order. |
+| 13 | Generic OSW step helpers | Centralize mapped step appending and `OpenStudio::Extension.set_measure_argument` use. | PR 12 | Tests prove boolean, numeric, and string arguments serialize correctly. | Baseline populator methods are broadly rewritten or baseline JSON changes unintentionally. |
+| 14 | Generalized runner | Run `baseline/in.osw` and `scenarios/**/in.osw`; keep `run_baseline_osw` intact. | PR 11 | Tests or smoke run show the correct OSW list and baseline-only compatibility. | Runner includes skipped or missing OSWs, or removes baseline-only behavior. |
+| 15 | CLI command | Add a Thor command for baseline plus all package scenarios using existing output, weather, standard, and run options. | PRs 11, 14 | CLI help documents the command, write-only mode produces OSWs, and run mode invokes the generalized runner. | Existing `write_baseline_osw` or `run_osw` behavior changes unexpectedly. |
+| 16 | User documentation | Update README or user docs with scenario path, output layout, mapping policy, warning behavior, and CLI examples. | PR 15 | Docs match implemented command names/options and include one known fixture example. | Docs promise result writeback or unsupported mapping coverage. |
+| 17 | Mapper unit test expansion | Add focused tests for mapped, conditional, fallback, and unmapped cases. | PRs 5-9 | Mapper behavior is covered without relying only on slow integration tests. | Important mapper paths only have integration coverage. |
+| 18 | Scenario generation and integration coverage | Add OSW generation tests and focused write/run integration for a small known-translatable scenario subset. | PRs 11-15, 17 | Focused commands pass; supported scenario `out.osw` files show `completed_status: Success`. | Tests run every package scenario by default, are too slow for CI, or hide failures behind broad skips. |
+
+## Verification Commands
+
+Use the narrowest command that verifies the current PR. Broader commands should be run before merging larger integration PRs.
+
+```bash
+bundle exec rspec spec/tests/unit/buildingsync_reader_spec.rb
+bundle exec rspec spec/tests/unit/scenario_measure_mapper_spec.rb
+bundle exec rspec spec/tests/integration/write_and_run_osws_spec.rb
+bundle exec rake
+```
+
+After the CLI PR, manually smoke-test the new command against these fixtures:
+
+- `spec/files/v2.7.0/building_151.xml` for package scenarios with known translatable measures.
+- `spec/files/v2.7.0/BuildingEQ-1.0.0.xml` for unmapped warning behavior.
+- `spec/files/v2.7.0/Golden Test File.xml` for package/reference edge cases.
+
+## Planned Files
+
+New files expected during the PR sequence:
+
+- `docs/scenario_workflow_translation_plan.md`
+- `lib/BOSS/scenario_measure_mapper.rb`
+- `lib/BOSS/scenario_measure_map.json`
+- `spec/tests/unit/scenario_measure_mapper_spec.rb`
+
+Existing files likely to change in later PRs:
+
+- `lib/BOSS/boss.rb`
+- `lib/BOSS/osw_arg_populator.rb`
+- `lib/BOSS/buildingsync_reader/buildingsync_reader.rb`
+- `lib/BOSS/constants.rb`
+- `lib/boss_cli.rb`
+- `spec/tests/unit/buildingsync_reader_spec.rb`
+- `spec/tests/integration/write_and_run_osws_spec.rb`
+- `README.md`
+
+## How Future Sessions Should Resume
+
+At the start of any future implementation session:
+
+1. Read this document first.
+2. Check the git state and recent commits to determine which PR steps have already landed.
+3. Start with the first PR in the sequence whose green-light criteria are not yet satisfied.
+4. Keep the change scoped to that PR unless a small supporting edit is necessary to make the PR coherent.
+5. Use the green-light criteria as the definition of done and the red-light criteria as merge blockers.
+6. Run the narrowest verification command that proves the current PR, then run broader compatibility checks before larger integration PRs.
+7. If implementation reveals a better order or a changed decision, update this plan in the same PR so later sessions inherit the new truth.
+
+## Review Checklist
+
+Before merging any implementation PR, confirm:
+
+- The PR implements only its planned scope or explicitly explains why a small dependency is included.
+- Existing baseline behavior remains compatible unless the PR explicitly updates it.
+- New behavior has focused tests or a documented manual verification path.
+- Warnings are structured and visible to callers.
+- Unmapped BuildingSync measures do not crash the whole translation.
+- The plan document remains accurate; update it in the same PR if a later implementation decision changes the roadmap.