### Run Version-Agnostic Example Test

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Execute the version-agnostic example test, which covers both DSTU3 and R4 FHIR versions.

```bash
# Run version-agnostic example (tests both DSTU3 and R4)
mvn test -Dtest=VersionAgnosticDefAssertionExampleTest
```

--------------------------------

### Run DSTU3 Example Test

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Execute the DSTU3-specific additional data definition assertion example test.

```bash
# Run DSTU3 example only
mvn test -Dtest=AdditionalDataDefAssertionExampleTest
```

--------------------------------

### Build the Project with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/README.MD

Use this command to build the entire project, including running all tests. Ensure Java 17 is installed.

```bash
./gradlew build
```

--------------------------------

### Run R4 Example Test

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Execute the R4-specific continuous variable definition assertion example test.

```bash
# Run R4 example only
mvn test -Dtest=ContinuousVariableDefAssertionExampleTest
```

--------------------------------

### Build Documentation Locally with MkDocs

Source: https://github.com/cqframework/clinical-reasoning/blob/main/CLAUDE.md

Build the project documentation locally. This requires Python 3 and MkDocs. Install dependencies using 'pip3', then serve the documentation locally.

```bash
# Build documentation locally (requires Python 3 and MkDocs)
cd docs/src/doc
pip3 install -r requirements.txt
mkdocs serve  # Browse at http://127.0.0.1:8000/
```

--------------------------------

### MeasureReport Scoring Usage Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/integrate-measure-def-scorer-part1-foundation.md

Demonstrates the transition from version-specific MeasureReport scoring to the new version-agnostic approach using MeasureReportScoringFhirAdapter.score().

```java
// Before (version-specific):
public void scoreMeasureReport(Measure theMeasure, MeasureReport theMeasureReport) {
    R4MeasureDefBuilder measureDefBuilder = new R4MeasureDefBuilder();
    R4MeasureReportScorer scorer = new R4MeasureReportScorer();
    scorer.score(theMeasure.getUrl(), measureDefBuilder.build(theMeasure), theMeasureReport);
}

// After (version-agnostic):
public void scoreMeasureReport(Measure theMeasure, MeasureReport theMeasureReport) {
    MeasureReportScoringFhirAdapter.score(theMeasure, theMeasureReport);
}
```

--------------------------------

### Enhance StratumPopulationDef with PopulationDef Reference (BEFORE)

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

This 'BEFORE' example shows the old `StratumPopulationDef` record using a String ID for lookup, which is less type-safe.

```java
public record StratumPopulationDef(
    String id,  // String-based lookup
    Set<String> subjectsQualifiedOrUnqualified,
    // ...
)
```

--------------------------------

### Backward Compatibility Delegation Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/enhanced-test-framework-def-integration.md

Illustrates the use of delegation methods in the Then class to maintain backward compatibility. Existing tests that use patterns like .firstGroup().population('numerator').hasCount(7) will continue to function without modification.

```java
.then()
    .firstGroup()
        .population("numerator")
            .hasCount(7)
```

--------------------------------

### Enhance StratumPopulationDef with PopulationDef Reference (AFTER)

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

This 'AFTER' example demonstrates the refactored `StratumPopulationDef` record, which now uses a direct `PopulationDef` reference for improved type safety and direct object matching.

```java
public record StratumPopulationDef(
    PopulationDef populationDef,  // Direct reference
    Set<String> subjectsQualifiedOrUnqualified,
    // ...
) {
    @Nullable
    public String id() {
        return populationDef != null ? populationDef.id() : null;
    }
}
```

--------------------------------

### R4 Measure DSL - Before Enhancement

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/enhanced-test-framework-def-integration.md

Example of the R4 Measure DSL before enhancements, focusing on basic measure evaluation and MeasureReport assertions.

```java
Measure.given().repositoryFor("ContinuousVariableMeasure")
    .when()
        .measureId("EXM55-FHIR")
        .periodStart("2024-01-01")
        .periodEnd("2024-12-31")
        .subject("Patient/patient-1")
        .evaluate()
    .then()
        // Currently: Only MeasureReport assertions
        .firstGroup()
            .population("measure-population")
                .hasCount(1);
```

--------------------------------

### Multi-Measure Def Access Pattern Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/enhanced-test-framework-def-integration.md

Demonstrates the URL-based access pattern for multi-measure definitions within the test framework. This approach is recommended for its explicitness and robustness compared to index-based access.

```java
.then()
    .def("http://example.com/Measure1")
        .hasNoErrors()
        .up()
    .def("http://example.com/Measure2")
        .hasNoErrors()
        .up()
```

--------------------------------

### Unified Test DSL - Given Clause

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Initializes the test context by setting up the repository and auto-detecting the FHIR version. This is the starting point for defining test scenarios.

```java
public static class Given {
        public Given repositoryFor(String repositoryPath) {
            // Auto-detect FHIR version from repository
            this.context = FhirVersionTestContext.forRepository(path);
        }

        public When when() {
            return new When(context.createMeasureService());
        }
    }
```

--------------------------------

### Multi-Measure Test Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Illustrates testing with multiple measures. It specifies multiple measure IDs, captures definitions, evaluates them, and then asserts the total number of measure reports and specific definitions for each measure.

```java
// Multi-measure
Fhir2DefUnifiedMeasureTestHandler.given()
    .repositoryFor("MinimalMeasureEvaluation")
.when()
    .measureId("Measure1")
    .measureId("Measure2")
    .captureDef()
    .evaluate()
.then()
    .hasMeasureReportCount(2)
    .def("http://example.com/Measure/Measure1")
        .firstGroup()...
```

--------------------------------

### Illustrate PopulationDef.subjectResources Data Structure

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

This example demonstrates the nested Map and Set structure of `subjectResources` within `PopulationDef`, highlighting the subject ID as the outer map key and observation IDs within inner maps.

```java
Map<String, Set<Object>> subjectResources

Where:
- Outer Map key: Subject ID (e.g., "p1", "p2", "p3")
- Outer Map value: Set of observation objects
- Each observation object: Map<String, QuantityDef> where inner map key is observation ID

Example:
subjectResources = {
    "p1" -> Set[ Map{"obs-num-1" -> QuantityDef(10.0)} ],
    "p2" -> Set[ Map{"obs-num-2" -> QuantityDef(20.0)} ],
    "p3" -> Set[ Map{"obs-num-3" -> QuantityDef(30.0)} ]
}
```

--------------------------------

### Single-Measure Test Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Demonstrates a typical test case for a single measure. It initializes the test context, specifies the measure, captures its definitions, evaluates it, and then asserts properties of the first group's numerator population.

```java
// Single-measure (auto-detects FHIR version)
Fhir2DefUnifiedMeasureTestHandler.given()
    .repositoryFor("MinimalMeasureEvaluation")
.when()
    .measureId("MinimalProportionMeasure")
    .captureDef()
    .evaluate()
.then()
    .def()
        .firstGroup()
            .population("numerator").hasSubjectCount(7);
```

--------------------------------

### Build and Run the Fat JAR

Source: https://github.com/cqframework/clinical-reasoning/blob/main/cqf-fhir-cr-dev-server/README.md

Instructions for building the fat JAR and running the CQF FHIR CR Dev Server. Includes a smoke test command.

```bash
# Build the fat JAR
./gradlew :cqf-fhir-cr-dev-server:bootJar

# Run it
java -jar cqf-fhir-cr-dev-server/build/libs/cqf-fhir-cr-dev-server-*.jar

# Smoke test
curl http://localhost:8080/fhir/metadata
```

--------------------------------

### Current Test for ContinuousVariableResourceMeasureObservation

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/enhanced-test-framework-def-integration.md

An example of a current test case using the Fhir2DefUnifiedMeasureTestHandler for continuous variable measures.

```java
@Test
void testContinuousVariableWithDefCapture() {
    Fhir2DefUnifiedMeasureTestHandler.given()
        .repositoryFor("ContinuousVariableMeasure")
    .when()
        .measureId("EXM55-FHIR")
        .periodStart("2024-01-01")
        .periodEnd("2024-12-31")
        .subject("Patient/patient-1")
        .captureDef()
        .evaluate()
    .then()
        .def()
            .hasNoErrors()
            .firstGroup()
                .population("measure-population")
                    .hasSubjectCount(1);
```

--------------------------------

### ImplementationGuide/$data-requirements

Source: https://github.com/cqframework/clinical-reasoning/blob/main/docs/src/doc/docs/operations.md

Analyzes an ImplementationGuide (IG) and produces a module-definition Library listing all its dependencies. It classifies dependencies as 'key' or 'default' and walks ValueSet compose chains to discover transitive CodeSystem and ValueSet dependencies.

```APIDOC
## ImplementationGuide/$data-requirements

### Description
Analyzes an IG and produces a module-definition Library listing all dependencies. Dependencies are classified as `key` or `default` based on key element analysis of profiles. ValueSet compose chains are walked to discover transitive CodeSystem and ValueSet dependencies.

### Parameters
#### Query Parameters
- **artifactEndpointConfiguration** (endpoint configuration) - Required - endpoint configuration for resolving canonical artifacts
- **terminologyEndpoint** (endpoint) - Required - endpoint for resolving terminology resources not available locally
```

--------------------------------

### Get MEASUREOBSERVATION Populations from Group

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

Retrieves all MEASUREOBSERVATION type populations from a given group definition. This is a version-agnostic helper.

```java
private List<PopulationDef> getMeasureObservations(GroupDef groupDef) {
        return groupDef.populations().stream()
                .filter(t -> t.type().equals(MeasurePopulationType.MEASUREOBSERVATION))
                .toList();
    }
```

--------------------------------

### Configure Linked Builds with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/AGENTS.md

Set up linked builds for cross-repo development by copying and editing the 'local.properties.example' file. This allows building against local checkouts of dependencies like CQL Engine.

```bash
# Copy the template and set paths to your local checkouts
cp local.properties.example local.properties

# Edit local.properties — uncomment and set the path:
# cql.engine.path=../clinical_quality_language/Src/java

# Build as normal — the settings plugin detects local.properties and includes the linked build
./gradlew build
```

--------------------------------

### Define Patient Age

Source: https://github.com/cqframework/clinical-reasoning/blob/main/cqf-fhir-cr-hapi/src/test/resources/org/opencds/cqf/fhir/cr/hapi/dstu3/hedis-ig/library-asf-cql.txt

Defines a condition to check if the patient is 65 years or older at the start of the measurement period.

```cql
define "Patient is 65 or Over":
  AgeInYearsAt(start of "Measurement Period")>= 65
```

--------------------------------

### Run with Live Reload

Source: https://github.com/cqframework/clinical-reasoning/blob/main/cqf-fhir-cr-dev-server/README.md

Use the bootRun Gradle task for live-reloading development.

```bash
./gradlew :cqf-fhir-cr-dev-server:bootRun
```

--------------------------------

### Code Formatting and Quality Checks with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/AGENTS.md

Ensure code quality and formatting using Gradle. 'spotlessCheck' verifies formatting, while 'spotlessApply' fixes formatting issues. Checkstyle also runs automatically during the build.

```bash
# Check code formatting (runs in CI on PRs)
./gradlew spotlessCheck

# Apply code formatting fixes
./gradlew spotlessApply

# This project uses Palantir Java Format (configured in buildSrc convention plugins)
# Checkstyle runs automatically as part of the build
```

--------------------------------

### Define Stratifier 3 (Age 65+)

Source: https://github.com/cqframework/clinical-reasoning/blob/main/cqf-fhir-cr-hapi/src/test/resources/org/opencds/cqf/fhir/cr/hapi/dstu3/hedis-ig/library-asf-cql.txt

Defines a stratifier for patients aged 65 or older at the start of the measurement period.

```cql
define "Stratifier 3":
  AgeInYearsAt(start of "Measurement Period")>= 65
```

--------------------------------

### Define Stratifier 2 (Age 45-64)

Source: https://github.com/cqframework/clinical-reasoning/blob/main/cqf-fhir-cr-hapi/src/test/resources/org/opencds/cqf/fhir/cr/hapi/dstu3/hedis-ig/library-asf-cql.txt

Defines a stratifier for patients aged 45 to 64 at the start of the measurement period.

```cql
define "Stratifier 2":
  AgeInYearsAt(start of "Measurement Period")in Interval[45, 64]
```

--------------------------------

### Build Project with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/AGENTS.md

Use these Gradle commands to build the project. The full build includes tests, while 'assemble' builds without tests. 'compileJava' compiles only the Java code. Parallel builds are enabled by default.

```bash
# Full build with tests
./gradlew build

# Build without tests
./gradlew assemble

# Compile only
./gradlew compileJava

# Parallel build (enabled by default via gradle.properties)
./gradlew build
```

--------------------------------

### Other Useful Gradle Commands

Source: https://github.com/cqframework/clinical-reasoning/blob/main/AGENTS.md

Perform various tasks with Gradle, including generating Javadocs, building a CLI fat JAR, publishing to a local Maven repository, and building documentation locally using MkDocs.

```bash
# Generate Javadocs
./gradlew javadoc

# Build CLI fat JAR
./gradlew :cqf-fhir-cr-cli:bootJar

# Publish to local Maven repository
./gradlew publishToMavenLocal

# Build documentation locally (requires Python 3 and MkDocs)
cd docs/src/doc
pip3 install -r requirements.txt
mkdocs serve  # Browse at http://127.0.0.1:8000/
```

--------------------------------

### Define Stratifier 1 (Age 18-44)

Source: https://github.com/cqframework/clinical-reasoning/blob/main/cqf-fhir-cr-hapi/src/test/resources/org/opencds/cqf/fhir/cr/hapi/dstu3/hedis-ig/library-asf-cql.txt

Defines a stratifier for patients aged 18 to 44 at the start of the measurement period.

```cql
define "Stratifier 1":
  AgeInYearsAt(start of "Measurement Period")in Interval[18, 44]
```

--------------------------------

### Deprecate R4MeasureReportScorer

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/integrate-measure-def-scorer-part1-foundation.md

Apply deprecation annotations and JavaDoc to R4MeasureReportScorer to signal its upcoming removal and guide users to new APIs.

```java
/**
 * Evaluation of Measure Report Data showing raw CQL criteria results compared to resulting Measure Report.
 *
 * @deprecated This class is deprecated and will be removed in a future release.
 *             For external consumers (e.g., cdr-cr project), use
 *             {@link MeasureReportScoringFhirAdapter#score(IBaseResource, IBaseResource)}
 *             for version-agnostic post-hoc scoring.
 *             For internal use, this class will be replaced by {@link MeasureDefScorer}
 *             integrated into the evaluation workflow in Part 2.
 *             See: integrate-measure-def-scorer-part2-integration PRP
 */
@Deprecated(since = "3.x.x", forRemoval = true)
@SuppressWarnings("squid:S1135")
public class R4MeasureReportScorer extends BaseMeasureReportScorer<MeasureReport> {
    // ... existing implementation unchanged ...
}
```

--------------------------------

### Generate Javadocs and Build CLI JAR with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/CLAUDE.md

Generate Javadocs for API documentation using the 'javadoc' task. Build a CLI fat JAR using the 'bootJar' task for the CLI module.

```bash
# Generate Javadocs
./gradlew javadoc

# Build CLI fat JAR
./gradlew :cqf-fhir-cr-cli:bootJar
```

--------------------------------

### Direct Constructor Usage for PopulationDef

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

Demonstrates direct constructor usage for PopulationDef when helper methods are insufficient. Includes adding resources to the population definition.

```java
// Direct Constructor Usage (when helpers don't fit):
//
// - PopulationDef: new PopulationDef(id, code, type, expression)
//   Then call pop.addResource(subjectId, resource) for each subject
```

--------------------------------

### Snapshot Creation Callback Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

This code demonstrates how to invoke the onDefCaptured callback after measure processing is complete, passing an immutable snapshot of the MeasureDef.

```java
// After processResults() completes, callback invoked:
callback.onDefCaptured(measureDef.createSnapshot());
```

--------------------------------

### R4MeasureProcessor Initialization

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/integrate-measure-def-scorer-part2-integration.md

Demonstrates how R4MeasureProcessor now initializes and holds an instance of MeasureEvaluationResultHandler, passing necessary dependencies during construction.

```java
public class R4MeasureProcessor {
    private final MeasureEvaluationResultHandler measureEvaluationResultHandler;

    public R4MeasureProcessor(
            IRepository repository,
            MeasureEvaluationOptions measureEvaluationOptions,
            MeasureProcessorUtils measureProcessorTimeUtils) {
        // ...
        this.measureEvaluationResultHandler =
                new MeasureEvaluationResultHandler(
                    this.measureEvaluationOptions,
                    new R4PopulationBasisValidator());
    }

    // Call sites updated (2 locations):
    // Line 188: measureEvaluationResultHandler.processResults(fhirContext, results, measureDef, evaluationType);
    // Line 240: measureEvaluationResultHandler.processResults(fhirContext, resultForThisMeasure, measureDef, evaluationType);
}
```

--------------------------------

### Indirect Count Retrieval from FHIR MeasureReport

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/refactor-count-retrieval-in-scorer.md

This example illustrates the anti-pattern where counts are read from FHIR components, requiring unnecessary data round-tripping.

```java
getCountFromGroupPopulation(mrgc.getPopulation(), NUMERATOR) // Reads from FHIR component
```

--------------------------------

### Format and Check Code Style

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/quantity-def-for-measure-scoring.md

Use these Maven commands to format your code according to project standards and to check for style violations.

```bash
# Format code
mvn spotless:apply
```

```bash
# Check style
mvn checkstyle:check
```

--------------------------------

### Direct Count Retrieval from StratumPopulationDef

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/refactor-count-retrieval-in-scorer.md

This example shows the preferred pattern of directly setting the count from the StratumPopulationDef class, avoiding FHIR object manipulation.

```java
sgpc.setCount(stratumPopulationDef.getCount()); // Direct from Def class
```

--------------------------------

### Get Stratum-Filtered Resources

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

Filters all subject resources from a population definition to include only those belonging to subjects within a specific stratum. Handles Map-based resources.

```java
private static Collection<Object> getResultsForStratum(
            PopulationDef populationDef,
            StratumPopulationDef stratumPopulationDef) {

        if (stratumPopulationDef == null) {
            return List.of();
        }

        // Get all subject resources from the population
        Collection<Object> allResources = populationDef.getAllSubjectResources();

        // Filter to only resources that belong to subjects in this stratum
        Set<String> stratumSubjects = stratumPopulationDef.subjectsQualifiedOrUnqualified();

        return allResources.stream()
            .filter(resource -> {
                if (resource instanceof Map<?, ?> map) {
                    // Check if any key in the map belongs to a stratum subject
                    return map.keySet().stream()
                        .anyMatch(key -> stratumSubjects.contains(String.valueOf(key)));
                }
                return false; // Or handle other resource types if necessary
            });
    }
```

--------------------------------

### Direct Constructor Usage for StratifierDef

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

Demonstrates direct constructor usage for StratifierDef, including its ID, code, expression, and type. Also shows how to add multiple strata to the stratifier definition.

```java
// - StratifierDef: new StratifierDef(id, code, expression, stratifierType)
//   Then call stratifierDef.addAllStratum(List.of(stratum1, stratum2, ...))
```

--------------------------------

### Verify Part 1 Files Exist

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/integrate-measure-def-scorer-part2-integration.md

Check for the existence of specific Part 1 Java files in the project.

```bash
# Verify Part 1 files exist
ls cqf-fhir-cr/.../common/MeasureReportDefScorer.java
ls cqf-fhir-cr/.../common/MeasureReportScoringFhirAdapter.java
```

--------------------------------

### Create PopulationDef with MEASUREOBSERVATION (Continuous Variable)

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

This example demonstrates creating a PopulationDef for MEASUREOBSERVATION with continuous variable scoring, including adding multiple observations per subject.

```java
PopulationDef measureObsPop = new PopulationDef(
    "measure-obs-1",
    new ConceptDef(List.of(new CodeDef("http://terminology.hl7.org/CodeSystem/measure-population", "measure-observation")), "measure-observation"),
    MeasurePopulationType.MEASUREOBSERVATION,
    "MeasureObservationExpression",
    null,  // criteriaReference
    ContinuousVariableObservationAggregateMethod.SUM
);

// Add observations for each subject
Map<String, QuantityDef> patient1Obs = new HashMap<>();
p রোগীর1Obs.put("obs-1", new QuantityDef(10.0));
p patient1Obs.put("obs-2", new QuantityDef(20.0));
measureObsPop.addResource("patient1", patient1Obs);

Map<String, QuantityDef> patient2Obs = new HashMap<>();
p patient2Obs.put("obs-3", new QuantityDef(15.0));
measureObsPop.addResource("patient2", patient2Obs);
```

--------------------------------

### After Optimization: Scoring Operations

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/prp-measure-observation-stratum-scoring-optimization.md

Illustrates the optimized scoring process, highlighting O(1) field accesses after pre-computation. The expensive lookups are moved to construction time.

```plaintext
At construction (once):
1. buildMeasureObservationCacheIfApplicable per stratum
   - Performs same lookups but ONCE per stratum

At scoring (per stratum):
1. getMeasureObservationCache(): O(1) field access
2. Extract numeratorObservation(): O(1) record accessor
3. Extract denominatorObservation(): O(1) record accessor

Total at scoring: 2 × 3 O(1) = 6 field accesses (vs 10 filter operations)
```

--------------------------------

### Assemble Project Artifacts with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/README.MD

This command builds the project artifacts without executing the tests. It's useful for faster builds when tests are not immediately needed.

```bash
./gradlew assemble
```

--------------------------------

### R4 Measure DSL - Enhanced with Dual Assertions

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/enhanced-test-framework-def-integration.md

Example of the enhanced R4 Measure DSL after Phase 3, demonstrating dual assertions for both MeasureDef (pre-scoring) and MeasureReport (post-scoring).

```java
Measure.given().repositoryFor("ContinuousVariableMeasure")
    .when()
        .measureId("EXM55-FHIR")
        .periodStart("2024-01-01")
        .periodEnd("2024-12-31")
        .subject("Patient/patient-1")
        .evaluate()
    .then()
        // NEW: MeasureDef assertions (pre-scoring)
        .def()
            .hasNoErrors()
            .firstGroup()
                .population("measure-population")
                    .hasSubjectCount(1)
                    .up()
                .hasNullScore()  // Pre-scoring state
                .up()
            .up()
        // MeasureReport assertions (post-scoring)
        .report()
            .firstGroup()
                .population("measure-population")
                    .hasCount(1)
                    .up()
                // TODO: Add scoring assertion in subsequent measure scoring refactoring PR
                .up()
            .up();
```

--------------------------------

### Example Terminology Endpoint Configuration

Source: https://github.com/cqframework/clinical-reasoning/blob/main/docs/src/doc/docs/operations.md

This JSON object defines a FHIR Endpoint resource for a terminology server. It specifies the connection type, authentication headers, address, and payload type.

```json
{
    "resourceType": "Endpoint",
    "status": "active",
    "connectionType": {
        "system": "http://hl7.org/fhir/ValueSet/endpoint-connection-type",
        "code": "hl7-fhir-rest"
    },
    "header": [
        "Authorization: Basic <base64-encoded credentials>"
    ],
    "address": "https://cts.nlm.nih.gov/fhir",
    "payloadType": [
        {
            "system": "http://hl7.org/fhir/ValueSet/endpoint-payload-type",
            "code": "any"
        }
    ]
}
```

--------------------------------

### Run Tests with Gradle

Source: https://github.com/cqframework/clinical-reasoning/blob/main/AGENTS.md

Execute tests using Gradle. You can run all tests, tests in a specific module, a single test class, or a single test method. Integration tests can also be run separately.

```bash
# Run all tests
./gradlew test

# Run tests in a specific module
./gradlew :cqf-fhir-cr:test

# Run a single test class
./gradlew :MODULE:test --tests ClassName

# Run a single test method
./gradlew :MODULE:test --tests "ClassName.methodName"

# Run integration tests
./gradlew integrationTest

# Skip tests
./gradlew assemble
```

--------------------------------

### Single Measure via Multi-Service Test Example

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-def-capture-framework.md

Shows how to explicitly force multi-measure evaluation for a single measure. This is useful for testing the multi-measure service path even when only one measure is involved.

```java
// Single measure via multi-service (explicit)
Fhir2DefUnifiedMeasureTestHandler.given()
    .repositoryFor("MinimalMeasureEvaluation")
.when()
    .measureId("Measure1")
    .evaluateAsMulti()  // Force multi-service
    .captureDef()
    .evaluate()
.then()
    .hasMeasureReportCount(1)
    .def()...
```

--------------------------------

### Upgrade Gradle Wrapper

Source: https://github.com/cqframework/clinical-reasoning/blob/main/README.MD

Update the Gradle Wrapper to a new version. Replace '<new-version>' with the desired Gradle version. Commit all changed files after running.

```bash
./gradlew wrapper --gradle-version <new-version>
```

--------------------------------

### Create StratumDef with StratumPopulationDef

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

This snippet shows how to create a StratumDef, including defining stratum population details and value definitions.

```java
StratumPopulationDef stratumPopDef = new StratumPopulationDef(
    "num-1",  // ID matching the PopulationDef
    Set.of("male1", "male2", "male3"),  // Subjects in this stratum
    Set.of(),  // populationDefEvaluationResultIntersection
    List.of(),  // resourceIdsForSubjectList
    MeasureStratifierType.VALUE,
    new CodeDef("http://hl7.org/fhir/ValueSet/measure-population", "boolean")
);

StratumDef stratumDef = new StratumDef(
    List.of(stratumPopDef),  // stratumPopulations
    Set.of(new StratumValueDef("male", "gender")),  // valueDefs
    Set.of("male1", "male2", "male3")  // subjectIds
);
```

--------------------------------

### Compile and Verify

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/version-agnostic-measure-report-scorer.md

Compiles the project and verifies that no breaking changes have been introduced. This is a standard step in ensuring code stability during development.

```bash
mvn clean compile
```

--------------------------------

### Code Style and Formatting Checks

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/refactor-count-retrieval-in-scorer.md

Maven commands to apply code formatting and check for style violations. `spotless:apply` formats the code, and `checkstyle:check` reports any style issues.

```bash
mvn spotless:apply
mvn checkstyle:check
```

--------------------------------

### R4MeasureService evaluateMeasureCaptureDefs

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/enhanced-test-framework-def-integration.md

This method in R4MeasureService orchestrates the evaluation of measure capture definitions. It includes validation, setup, calls the processor's test-visible method, and performs post-processing on the MeasureReport, such as adding product line extensions and subject references.

```java
@VisibleForTesting
MeasureDefAndR4MeasureReport evaluateMeasureCaptureDefs(...) {
    // Validation and setup
    measurePeriodValidator.validatePeriodStartAndEnd(periodStart, periodEnd);
    var processor = new R4MeasureProcessor(...);

    // ... subject resolution, context setup ...

    // Call processor's test-visible method
    MeasureDefAndR4MeasureReport result = processor.evaluateMeasureCaptureDefs(...);

    // Post-processing (product line, subject reference)
    MeasureReport measureReport = r4MeasureServiceUtils.addProductLineExtension(result.measureReport(), productLine);
    measureReport = r4MeasureServiceUtils.addSubjectReference(measureReport, practitioner, subjectId);

    // Return new record with updated MeasureReport
    return new MeasureDefAndR4MeasureReport(result.measureDef(), measureReport);
}

public MeasureReport evaluate(...) {
    return evaluateMeasureCaptureDefs(...).measureReport();
}
```

--------------------------------

### QuantityDef Creation and Assertion

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/quantity-def-for-measure-scoring.md

Demonstrates the creation of a QuantityDef object with value, unit, system, and code, and asserts its properties.

```java
package org.opencds.cqf.fhir.cr.measure.common;

import static org.junit.jupiter.api.Assertions.*;

import org.junit.jupiter.api.Test;

// Generated by Claude Sonnet 4.5 on 2025-11-27
class QuantityDefTest {

    @Test
    void testQuantityDefCreation() {
        QuantityDef qd = new QuantityDef(42.5, "mg", "http://unitsofmeasure.org", "mg");

        assertEquals(42.5, qd.value());
        assertEquals("mg", qd.unit());
        assertEquals("http://unitsofmeasure.org", qd.system());
        assertEquals("mg", qd.code());
    }

    @Test
    void testQuantityDefWithValueOnly() {
        QuantityDef qd = new QuantityDef(100.0);

        assertEquals(100.0, qd.value());
        assertNull(qd.unit());
        assertNull(qd.system());
        assertNull(qd.code());
    }
}
```

--------------------------------

### Add Global Trust Rules for Sources and Javadoc JARs

Source: https://github.com/cqframework/clinical-reasoning/blob/main/PRPs/fix-intellij-gradle-sync-verification-metadata.md

Add two `<trust file>` entries with regex patterns to globally trust all `-sources.jar` and `-javadoc.jar` files. This is a proactive measure to avoid future failures.

```xml
<configuration>
   <verify-metadata>true</verify-metadata>
   <verify-signatures>false</verify-signatures>
   <trusted-artifacts>
      <trust group="org.jetbrains" name="annotations"/>
      <trust group="org.jetbrains.kotlin" name=".*" regex="true"/>
      <trust group="org.jetbrains.kotlinx" name=".*" regex="true"/>
      <trust file=".*-sources\.jar" regex="true"/>
      <trust file=".*-javadoc\.jar" regex="true"/>
   </trusted-artifacts>
</configuration>
```