From a277c5cf65f9cbb9599f36cfac2bbc997c6d4594 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Sat, 18 Jul 2026 13:39:12 -0600 Subject: [PATCH 1/3] Create scenario_workflow_translation_plan.md --- docs/scenario_workflow_translation_plan.md | 210 +++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 docs/scenario_workflow_translation_plan.md diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md new file mode 100644 index 0000000..ef4ca33 --- /dev/null +++ b/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 +/baseline/in.osw +``` + +Scenario workflows should be written under a dedicated scenario directory: + +```text +/scenarios//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. \ No newline at end of file From af63961a9130758cfd4bf5844afe91c2d40cd34a Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Mon, 20 Jul 2026 17:24:08 -0600 Subject: [PATCH 2/3] Create copilot-instructions.md --- .github/copilot-instructions.md | 109 ++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..287c30e --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,109 @@ +# GitHub Copilot Instructions for BOSS + +These instructions apply to AI-assisted work in this repository. Keep changes small, reviewable, and grounded in the repo's plan documents and tests. + +## Repository Context + +BOSS translates BuildingSync XML into OpenStudio workflows. The current production behavior is baseline-only: write `baseline/in.osw`, then run that baseline workflow. Preserve that behavior unless the current task explicitly changes it. + +Important project context lives in: + +- `README.md` — setup, CLI use, current baseline workflow, and test commands. +- `docs/scenario_workflow_translation_plan.md` — source of truth for the scenario workflow translation roadmap. +- `spec/files/v2.7.0/` — BuildingSync fixtures used by unit and integration tests. +- `spec/tests/` — existing RSpec coverage patterns. + +## Related Repositories and Dependencies + +BOSS sits between BuildingSync XML data and OpenStudio workflow execution. Several sibling repositories are useful for context, but this repository should remain the implementation target unless the user explicitly asks for cross-repo edits. + +- `../schema` — BuildingSync schema source and examples. Use it to verify XML structure, element names, `ScenarioType`, `PackageOfMeasures`, `Measure`, `MeasureID`, and schema-version behavior. Do not change schema files while working on BOSS unless the task explicitly requests schema work. +- `../BuildingSync-gem` — legacy Ruby translator with older scenario-to-OpenStudio workflow behavior. Use it as historical reference for workflow sequencing, scenario/result concepts, and mapping ideas. Do not copy code or mappings blindly; verify every behavior against current BOSS dependencies and BuildingSync v2.7 fixtures. +- `../buildingsync-measures-gem` — related BuildingSync/OpenStudio measure work. Use it to understand existing measures and BuildingSync-oriented OpenStudio measure patterns when mapping scenarios. Treat it as reference unless the user asks for changes there. +- `../openstudio-standards` — OpenStudio standards logic used by the `openstudio-standards` gem. BOSS currently depends on the gem version declared in `BOSS.gemspec`; do not edit the sibling standards repo as part of BOSS work unless the issue is proven to belong upstream and the user asks for a cross-repo change. +- OpenStudio measure gems declared in `BOSS.gemspec` — `openstudio-common-measures`, `openstudio-ee`, `openstudio-extension`, `openstudio-model-articulation`, and `openstudio-standards`. These define the measure directories, arguments, runner behavior, and standards templates BOSS can rely on. When adding scenario mappings, verify target measure names and arguments against the installed gem versions used by BOSS. + +Rule of thumb: inspect sibling repos freely for context; keep BOSS PRs scoped to BOSS files. If a required fix appears to belong in a sibling repo or upstream gem, record that clearly as follow-up work instead of mixing it into a BOSS PR. + +## Scenario Workflow Translation Work + +For any work related to translating BuildingSync `PackageOfMeasures` scenarios into OpenStudio workflows: + +1. Read `docs/scenario_workflow_translation_plan.md` before editing code. +2. Check the git state and recent commits to determine which PR steps have already landed. +3. Start with the first PR step in the plan whose green-light criteria are not satisfied. +4. Keep changes scoped to that PR step unless a small supporting edit is necessary to make the step coherent. +5. Treat each step's green-light criteria as the definition of done and red-light criteria as merge blockers. +6. Preserve existing baseline-only API, CLI behavior, output layout, and integration tests unless the current PR step explicitly changes them. +7. If implementation decisions change the roadmap, update `docs/scenario_workflow_translation_plan.md` in the same PR. + +Do not jump ahead to later PR steps just because the code is nearby. If a later concern is discovered, record it in the plan or final notes and keep the current PR focused. + +## Scope Discipline + +Before opening or finalizing a PR: + +- Review every changed file and drop exploratory edits that are not load-bearing. +- Keep generated outputs, local run artifacts, and unrelated formatting churn out of the PR. +- Prefer existing project patterns over new abstractions unless the new abstraction clearly removes repeated complexity. +- If a change is documentation-only, say so and do not run unnecessary simulation tests. + +## Tests and Verification + +Whenever you make code changes, decide whether the change is unit-testable. If it is, add or update focused tests in the same PR. + +Use the narrowest useful command first, then broaden as risk increases: + +```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 +``` + +If a test cannot be run locally because dependencies, OpenStudio, weather files, or runtime are unavailable, state that clearly and name the command that should be run later. + +## Ruby and Style Checks + +For Ruby code changes, run project commands through the bundle when possible: + +```bash +bundle exec rubocop +``` + +If RuboCop or the bundle is unavailable locally, do not guess. Say what failed and what the reviewer should run after dependencies are available. + +## Documentation and Comments + +Write for maintainers first. + +- Keep comments short and focused on non-obvious behavior. +- Do not narrate what the next line of code already says. +- Put roadmap, rationale, and cross-PR history in `docs/scenario_workflow_translation_plan.md`, not in source comments. +- Keep README updates matched to implemented behavior; do not document future result writeback or mapping coverage until it exists. + +## Pull Request Description Template + +Use a short, plain-language PR body: + +```md +## Why do we need this PR + + +## Core change explanation + + +## Which files are affected +- `path/to/file_or_folder` + +## What kind of tests are done +- +``` + +Optional `Out of scope` or `Follow-up work` sections are useful when they prevent reviewer confusion. Keep deep evidence and long reasoning in the plan doc instead of the PR body. + +## CI and Merge Hygiene + +- Treat green local tests as necessary but not always sufficient; CI may catch clean-environment issues. +- If a workflow fails, inspect the failing job logs before suggesting fixes. +- When a scenario workflow PR changes the roadmap or PR boundaries, update `docs/scenario_workflow_translation_plan.md` so future sessions inherit the current truth. \ No newline at end of file From 7a8281473a9b6b11f11d0e2d9c980327afb0fbe4 Mon Sep 17 00:00:00 2001 From: JieXiong9119 <69597597+JieXiong9119@users.noreply.github.com> Date: Mon, 20 Jul 2026 17:32:16 -0600 Subject: [PATCH 3/3] add tracking, add reference to buildingsync-gem --- docs/scenario_workflow_translation_plan.md | 84 ++++++++++++++++------ 1 file changed, 64 insertions(+), 20 deletions(-) diff --git a/docs/scenario_workflow_translation_plan.md b/docs/scenario_workflow_translation_plan.md index ef4ca33..6504705 100644 --- a/docs/scenario_workflow_translation_plan.md +++ b/docs/scenario_workflow_translation_plan.md @@ -111,6 +111,28 @@ Initial mappings may use the legacy BuildingSync-gem `workflow_maker.json` as ba 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. +## Using the Legacy BuildingSync-gem Work + +The legacy `../BuildingSync-gem` repository is an important reference, but it should not become a runtime dependency of BOSS. Use it to understand proven workflow concepts, then re-implement the needed behavior in BOSS using current dependencies and BuildingSync v2.7 fixtures. + +Legacy references to inspect: + +- `../BuildingSync-gem/lib/buildingsync/report.rb` — how reports group current-building, measured, and package-of-measures scenarios. +- `../BuildingSync-gem/lib/buildingsync/scenario.rb` — how a scenario exposes `MeasureID` references, owns an OSW, and later gathers results. +- `../BuildingSync-gem/lib/buildingsync/model_articulation/measure.rb` — simple measure wrapper concept. +- `../BuildingSync-gem/lib/buildingsync/makers/workflow_maker.rb` — scenario workflow sequence: deep-copy workflow, resolve package measures, configure steps, write OSWs, run OSWs. +- `../BuildingSync-gem/lib/buildingsync/makers/workflow_maker.json` — seed ideas for category/name to OpenStudio measure mappings. + +How to leverage it by PR: + +- PRs 2-4 may borrow the report/scenario/measure concepts, but should keep parsing in `BOSS::BuildingSyncReader` and keep namespace handling compatible with current BOSS fixtures. +- PRs 5-9 may use `workflow_maker.json` as a mapping seed, but every measure directory and argument must be verified against the OpenStudio gem versions declared in `BOSS.gemspec` before it is added to BOSS. +- PRs 8-9 may borrow the idea of conditional arguments, but should express conditions through mapping data and context values rather than a per-measure Ruby `if`/`elsif` chain. +- PRs 11-14 may borrow the deep-copy/write/run workflow shape, but should preserve BOSS's current baseline OSW generation and output layout. +- Result writeback ideas from the legacy gem are intentionally future work; do not include them in this first release unless this plan is explicitly updated. + +Do not copy blindly from the legacy gem. It targets older BuildingSync schema versions and older OpenStudio gems, so stale measure names, arguments, assumptions, and failure checks are expected. Any BOSS mapping or workflow behavior inspired by the legacy gem needs a current fixture test or a clear manual verification note. + ## Warning Policy The implementation should return structured warnings and log them consistently. These conditions are warnings, not fatal translation errors: @@ -128,26 +150,48 @@ If a scenario has at least one mapped measure, write its OSW and include warning 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. | +| PR | Status | Delivered By | Title | Scope | Depends On | Green Light | Red Light | +| --- | --- | --- | --- | --- | --- | --- | --- | +| 1 | In Progress | Current docs PR | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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 | Planned | - | 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. | + +## Progress Tracking Protocol + +The PR sequence table is the tracker. Keep it current so future sessions can trust it without reconstructing history from memory. + +Allowed status values: + +- `Planned` — not started. +- `In Progress` — actively being implemented on a branch. +- `Done` — merged or otherwise delivered; green-light criteria satisfied. +- `Blocked` — cannot proceed without a decision, dependency, or external fix. +- `Closed` — intentionally no longer needed; keep the reason in the row or nearby note. + +When a PR step is completed or merged: + +1. Change its `Status` in the table. +2. Fill `Delivered By` with the PR number, commit SHA, or short note that identifies what delivered it. +3. Confirm the row's green-light criteria were met. +4. If scope or order changed, update the affected rows and explain the change in this document. +5. Leave future `Planned` rows in place so later sessions can find the next unfinished step. + +When starting a future session, check this table first, then verify against `git log` and the current file tree. If the table is stale, update it before doing implementation work. ## Verification Commands