Align Questionnaire Catalog with Grove FHIR

.github/workflows/verify-study-bundle.yml

@@ -33,5 +33,7 @@ jobs:
       contents: read
     with:
       runs_on_labels: '["ubuntu-latest"]'
-      # Swift 6.4's default build engine ignores transitive platform conditions (Grove#105).
+      # Swift 6.4.0's default build engine ignores transitive platform conditions,
+      # which ends up compiling Grove's Apple-only targets on Linux
+      # (Grove#105 and swiftlang/swift-package-manager#10538)
       build_flags: '--build-system native'

Package.swift

@@ -26,8 +26,12 @@ let package = Package(
         .executable(name: "MHCStudyDefinitionExporterCLI", targets: ["MHCStudyDefinitionExporterCLI"])
     ],
     dependencies: [
-        .package(url: "https://github.com/SchmiedmayerLab/Grove.git", exact: "0.3.0-beta.8"),
-        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.6.2")
+        .package(
+            url: "https://github.com/SchmiedmayerLab/Grove.git",
+            revision: "6e40cfbffcecafd59b253d6d1d9e2cfbdc89b1d0"
+        ),
+        .package(url: "https://github.com/apple/swift-argument-parser.git", from: "1.6.2"),
+        .package(url: "https://github.com/apple/swift-crypto.git", "4.0.0"..<"6.0.0")
     ],
     targets: [
         .target(
@@ -66,7 +70,13 @@ let package = Package(
             dependencies: [
                 "MHCStudyDefinition",
                 "MHCStudyDefinitionExporter",
-                .product(name: "GroveStudyDefinition", package: "Grove")
+                .product(name: "GroveStudyDefinition", package: "Grove"),
+                .product(name: "GroveFHIRContract", package: "Grove"),
+                .product(name: "GroveQuestionnaireExtraction", package: "Grove"),
+                .product(name: "Crypto", package: "swift-crypto", condition: .when(platforms: [.linux])),
+                // Grove's questionnaire authoring products do not build on the Linux CI leg.
+                .product(name: "GroveQuestionnaire", package: "Grove", condition: .when(platforms: [.macOS])),
+                .product(name: "GroveQuestionnaireFHIR", package: "Grove", condition: .when(platforms: [.macOS]))
             ]
         )
     ]

README.md

@@ -1,3 +1,3 @@
 <!--
 
 This source file is part of the My Heart Counts Study Definitions open-source project
@@ -26,6 +26,33 @@
 Note that the package does not make the actual study definition available as an SPM package; this is intentional.
 Instead, the package only implements the code that exports the study bundle, in a format the MHC app can then download from a server and consume.
 
+## Questionnaire Conventions
+
+The instruments are authored under `Sources/MHCStudyDefinitionExporter/Resources/questionnaire/` as `en-US`/`es-US` pairs, each declaring its own `language`.
+The pair must stay structurally identical, with the same `url` and `version`: only the display text and the locale metadata differ, and the contract suite compares the two projections to enforce it.
+The export merges each pair into one multilingual Questionnaire: the `en-US` source supplies the base strings and `language`, and every `es-US` string becomes a `translation` extension on the string it translates.
+The study bundle therefore carries exactly one Questionnaire per instrument, which is what a `QuestionnaireResponse` references and what the app loads and renders in the participant's language.
+
+Any change to instrument content bumps `studyRevision` in `Study.swift` together with the pinned expectation in the tests.
+Every change to the exported content also increments that instrument's `Questionnaire.version` in both sources, because `url|version` names one immutable definition.
+That covers anything that alters how a response is interpreted — item meaning, datatype, answer choices, required state, a condition, a constraint, the hierarchy, or an extraction marking — and any added, removed or changed translation.
+
+`linkId`s are persisted identifiers.
+Submitted `QuestionnaireResponse`s reference them, so a `linkId` is renamed only with a migration, never for tidiness.
+Question items use UUIDs; structural anchors that other layers reason about — the HeartRisk wrapper group and its blood-pressure panel — use readable kebab-case names instead.
+HeartRisk keeps exactly one top-level group because Grove renders every top-level group as its own section, so flattening the wrapper would split the instrument across three pages.
+
+### Marking Measurements for Extraction
+
+A marked item is extracted into a profiled Observation, following [Grove's measurement extraction guide](https://schmiedmayerlab.github.io/grove-fhir/questionnaire/ci-build/measurements.html).
+Marking one takes an `sdc-questionnaire-observationExtract` extension, a single coded `item.code` naming the measurement, and a UCUM `questionnaire-unitOption` for quantities.
+A panel is a group carrying the panel LOINC and `valueBoolean: true`; each of its question children carries its own component LOINC and `valueCode: "component"`.
+When the target profile fixes a category — the blood-pressure panel's `vital-signs`, for instance — the item must also carry `sdc-questionnaire-observation-extract-category`, or the extracted Observation does not conform.
+Measurements whose profile fixes no category, such as blood glucose, deliberately declare none.
+
+An unmarked quantity item is intentionally not extracted; in HeartRisk that covers the second blood-pressure reading, HbA1C, and the cholesterol values, which are collected for the study's own scoring rather than for the measurement exchange.
+
+
 ## Study variants
 
 The exporter produces separate Stanford and Imperial bundles. The CLI defaults to Stanford; select Imperial explicitly: