Scenario workflow: 1. plan for developing the Scenario workflow

[JieXiong9119]

PR 1-4 Summary

This PR set lays the foundation for translating BuildingSync PackageOfMeasures scenarios into OpenStudio workflows. It does not change the current baseline-only workflow behavior yet. BOSS still writes and runs baseline/in.osw as before.

PR 1: Scenario Workflow Plan

Added a roadmap for scenario workflow translation.

The plan defines:

• What the first scenario workflow release should support.
• What is intentionally out of scope, including result writeback.
• The expected output layout for future scenario OSWs.
• The mapping approach for BuildingSync measures to OpenStudio measures.
• The PR sequence for future implementation work.

PR 2: Scenario Discovery

Added reader support for discovering report-level scenarios from the first facility.

BOSS can now read package-of-measures scenario data, including:

• Scenario ID and name.
• Temporal status.
• Source report ID.
• Package ID.
• Reference case ID.
• Referenced MeasureID values.
• Linked premises references.

This keeps existing reader behavior unchanged while exposing the scenario data needed by later PRs.

PR 3: Measure Index

Added reader support for indexing measures from the first facility.

BOSS can now look up measures by ID and read useful measure metadata, including:

• Measure name and custom measure name.
• System category affected.
• Technology category.
• Linked premises references.
• Cost and savings metadata.
• Implementation status.

Missing optional fields return nil or empty arrays instead of breaking parsing.

PR 4: Parser Warnings

Added a structured warning contract for incomplete or unusable scenario and measure data.

Warnings now cover cases such as:

• Missing scenario, package, or measure IDs.
• Packages with no MeasureID references.
• Packages that reference unknown measures.
• Measures missing names or categories.
• Packages with no parser-usable measures.

These warnings are returned as structured data, so later mapping and workflow code can handle them consistently.

Verification

Focused reader tests were added or updated for PRs 2-4.

Verified with:

• bundle exec rspec spec/tests/unit/buildingsync_reader_spec.rb

Latest focused unit result:

• 33 examples, 0 failures

RuboCop was also checked on the changed reader/spec files. It still reports existing style debt and new-cop configuration warnings, but no new functional blocker was identified for the PR scope.