openehr-rails 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69d9f917d3eb32a92e7d47aeb3f43bf8992a6a44f8ceb49320a1e5a6130ecebf
-  data.tar.gz: 1f39015dbd51241ea4dca624bd89e988a82bf62ef3a02964e54a343b6e8ccbf1
+  metadata.gz: 065a9ba44f893adaea9e6c0ccf6f3c5f8a0af8c8c3897379cd008e5642e99a7a
+  data.tar.gz: 98f81ad0baf2b086e2193102c25804b3affcd2fa1ffb4c0730952d6a916e3a58
 SHA512:
-  metadata.gz: 5acec88b6d3dee1ab32167080639a81052911eee90043ae09474e083fa0c92e081da69dade909848da04743cffc96603e887765a8efaff29d6172f873e93a074
-  data.tar.gz: 1c134c5a1147f54ee8628b62efdcfcb867f257f634a5094a4f0aacb2af460ac28cfcaa011457017610262686437041ec85045186f9c05acb034ed4080e6ec793
+  metadata.gz: 42353942db8a02b901e3727a85446fe1995f3c953fd33f3da2dfea68d7018b533de95b97494db856593df77ccbacd8d57f0f4bb4cdcedee086da6c4e44035a04
+  data.tar.gz: 4fd7e793d2d77230e585dcf06204147926d3b36a86a576525614d19395930f80b4fe38bc0b534de5a0f6b26e98e0859d5c8275ce865a1efedf3aa942dc1d272e

data/CHANGELOG.md

@@ -7,8 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-10
+
+> **Upgrade note.** Regenerate `app/fhir/profiles/*.json`. `Condition.component`
+> slices are gone; anything reading them must move to the mapped elements
+> (`category` slice `ckm`, `code`, `onsetDateTime`, `recordedDate`,
+> `abatementDateTime`, `verificationStatus`), and an entry with no mapping onto
+> a non-`Observation` resource now appears in the generator's `#skipped` list
+> instead of producing a profile.
+
+### Changed
+- **Breaking for consumers of generated FHIR profiles.** `EVALUATION` entries no
+  longer produce `Condition.component` slices, which FHIR R5 `Condition` does not
+  have. Each leaf now maps onto the real `Condition` element that means the same
+  thing — `code` (bound to the leaf's value set), `onsetDateTime`,
+  `recordedDate`, `abatementDateTime`, `verificationStatus` — and the archetype
+  anchor moves from `Condition.code` to a `Condition.category` slice (`ckm`,
+  `1..1`, pattern-discriminated on `$this`, so an instance keeps room for its
+  other categories), since `code` is now the diagnosis itself. `recordedDate`
+  carries an `ElementDefinition.comment` stating that it approximates at0003
+  (date/time clinically recognised). `ProfileGenerator` (JSON) and
+  `FshGenerator` generate from one table in `TypeMap`, so the two outputs cannot
+  disagree. Generated FSH for `problem_list.opt` goes from 29 Sushi errors to 0.
+  Host apps must regenerate cached `app/fhir/profiles/*.json`; anything reading
+  the old `Condition.component` slices must be updated (#33). Currently mapped:
+  `openEHR-EHR-EVALUATION.problem_diagnosis.v1`. A multi-leaf entry mapped to
+  `ServiceRequest`/`Procedure`/`Encounter` without a mapping-table row is now
+  skipped and reported (see Added) instead of producing `component` constraints
+  those resources do not have; its mapping table remains reserved as #35.
+- Value-set canonicals on mapped leaves no longer carry OPT's `terminology:`
+  prefix, in either output.
+
+### Added
+- `ProfileGenerator#skipped` and `FshGenerator#skipped`: the entries left out of
+  `#profiles` / `#to_fsh_files`, each as an
+  `OpenehrRails::Fhir::UnsupportedProfileError` (`archetype_id`,
+  `resource_type`, `leaf_count`) in template order. An entry is skipped when it
+  has more than one leaf, maps to a resource without `component`, and has no row
+  in `TypeMap::ENTRY_ELEMENT_MAPS`; the rest of the template still generates.
+  `rails g openehr:fhir_profile` and `openehr:scaffold --fhir` print each skip
+  (#33).
+
+### Removed
+- `TypeMap.value_element`, dead since it was added — its ternary returned the
+  same string on both branches and nothing called it. Its intended
+  resource-type branch is now the mapping table (#33).
+
+### Fixed
+- `templates/openehr_template.rb` pins `json < 3` in the generated app's
+  `Gemfile`. `json` 3.0 (2026-09-08) changed `JSON.parse`'s arity and
+  `ActiveSupport::JSON.decode` as of activesupport 8.1.3.1 still passes options
+  positionally, so a freshly generated host app failed at `db:seed` on its first
+  json-column write (`ArgumentError: wrong number of arguments (given 2, expected
+  1)`). Temporary: remove once a Rails patch release carries the fix. This
+  repo's own `Gemfile` and `script/build_demo.sh` carry the same dev-only pin.
+- `release:check` now fails when a tag matching the gemspec version exists and
+  `HEAD` is not that tag's commit. `gem.files` comes from `git ls-files`, so a
+  gem built at a later commit ships different bytes under the same version
+  number — the defect that let 0.6.0 be published as a `master`-HEAD build
+  (#34). The check stays silent when the version has no tag yet, so ordinary
+  pre-release development is unaffected.
+
 ## [0.6.0] - 2026-08-26
 
+> **Published artifact note.** The gem published to RubyGems for this version
+> was built from `master` HEAD rather than the `v0.6.0` tag, so it contains the
+> tagged tree plus two documentation files added after the tag
+> (`docs/design/multi-leaf-non-observation-plan.md`, and this project's
+> `docs/reports/fsh-generator-log.md` carrying its R6 entry). `lib/` is
+> byte-identical to the tag artifact and version, runtime dependencies and
+> `required_ruby_version` are unchanged, so the published gem is functionally
+> identical to what CI built and verified at the tag; it was accepted rather
+> than yanked. Published sha256
+> `223e3b3897f85c38eaffe7ea39bd7c2acf4c5de9cab7d50fe38f754ff9d65db6`; tag-build
+> sha256 `08cdd14ab1f3890b0c6b5f0ae0d5ca55615f0b4874ed5efb0cd4d7bda9e573ca`.
+> Full measurements: `docs/reports/fsh-generator-log.md` R8. Prevention:
+> `skoba/openehr-rails#34`.
+
 ### Added
 - `OpenehrRails::Fhir::FshGenerator` renders one FHIR Shorthand profile per
   openEHR entry, including metadata, archetype codes, value constraints,

data/CLAUDE.md

@@ -46,6 +46,37 @@ Before tagging, make the final semver determination from the actual content of
 `[Unreleased]`, not from a pre-assigned version number. If the instructed version number
 contradicts the actual content, stop instead of tagging and ask for re-arbitration.
 
+**Publish only the CI artifact itself.** `gem push` takes the `.gem` downloaded
+from the tag's Release run (`gh run download <run-id> -n gem`), after its sha256
+has been compared against the value recorded for that run - never a locally built
+`pkg/*.gem`. `gem.files` comes from `git ls-files`, so a build made at any commit
+other than the tag ships different bytes under the same version number, and a
+stale `pkg/` artifact from unrelated local work is indistinguishable by filename
+from a release build.
+
+(Added 2026-08-27, from the 0.6.0 publish: the gem that reached RubyGems was a
+`master`-HEAD build left in `pkg/` by an unrelated verification run, not the
+CI-verified `v0.6.0` artifact. Accepted rather than yanked - the delta was two
+documentation files and `lib/` was byte-identical - but nothing in the release
+path caught it. Measurements in `docs/reports/fsh-generator-log.md` R8; the
+matching `release:check` guard is `skoba/openehr-rails#34`.)
+
+**Confirm publication by checksum, not by version number.** RubyGems publishes
+the sha256 it recorded at push time (`/api/v1/gems/openehr-rails.json` `sha`, and
+the `checksum:` field in `https://index.rubygems.org/info/openehr-rails`). The
+post-push confirmation compares that value against the sha256 the tag's Release
+run recorded for its artifact - the same value already compared before the push.
+Seeing the version number appear is not the check; it only shows that *a* gem
+landed under that number. (Ported 2026-09-10 from openehr-ruby's 2.4.3 release,
+where CI run, downloaded artifact and published gem all agreed on one sha256.)
+
+**RubyGems API propagation lag.** `/api/v1/versions/openehr-rails.json` can lag
+the push by minutes; do not read the new version's absence there as a failed
+publish, and do not re-push. Confirm with
+`/api/v1/versions/openehr-rails/latest.json`, `/api/v1/gems/openehr-rails.json`,
+or the compact index `https://index.rubygems.org/info/openehr-rails`, which
+updated first in that same 2.4.3 run.
+
 ## Verification
 
 - **Verify against the repo before recording a fact in it**, even when a prompt or an
@@ -119,7 +150,8 @@ name explicitly a distinction that the existing repository-context rule left
 implicit: it governs *how* to target a cross-repo command correctly, not *whether*
 crossing into implementation work on another repository has actually been
 authorized for the task at hand. A matching line is planned for `anlage`'s own
-`CLAUDE.md` in a later batch - not yet added there as of this entry.)
+`CLAUDE.md` in a later batch - not yet added there as of this entry. Update
+2026-09-04: added there as 絶対規律 item 9.)
 
 ## Project Overview
 
@@ -200,4 +232,4 @@ This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Te
 - Guard setup available for TDD workflow
 - RuboCop Rails linting configured
 - SimpleCov for test coverage
-- `openehr` gem dependency; see the gem's own README/CHANGELOG for OPT-parser and AQL-engine capabilities and known gaps before relying on either.
+- `openehr` gem dependency; see the gem's own README/CHANGELOG for OPT-parser and AQL-engine capabilities and known gaps before relying on either.

data/Gemfile

@@ -1,3 +1,10 @@
 source 'https://rubygems.org'
 
 gemspec
+
+# json 3.0 (released 2026-09-09) changed JSON.parse's arity; ActiveSupport::JSON.decode
+# as of activesupport 8.1.3.1 still passes its options positionally, so reading any
+# json column raises ArgumentError (wrong number of arguments (given 2, expected 1)).
+# Dev/test-only pin -- the gemspec is untouched, host apps resolve their own json.
+# Drop once a Rails patch release carries the fix (docs/backlog.md, "Dependencies").
+gem 'json', '< 3'

data/docs/backlog.md

@@ -90,6 +90,13 @@ status entry above for verification details.
   docs-only pass — implementing the workflow change goes through an Issue (once
   ticket-driven work applies to it) plus the normal explore → plan → approval gate,
   not a direct docs commit.
+  - A point in Trusted Publishing's favour, measured 2026-08-27: the gem build is
+    byte-identical across machines and Ruby installs for a given commit — `4080053`
+    (the `v0.6.0` tag) produced sha256 `08cdd14a…` from CI, from the old machine
+    (R5), and from a rebuild on the replacement machine under local ruby 4.0.6 vs
+    CI's `ruby/setup-ruby@v1` ruby 4.0. So a CI- or Trusted-Publishing-published
+    artifact stays independently verifiable against a local rebuild
+    (`docs/reports/fsh-generator-log.md` R8).
 
 ## From #25 / PR #26 (FieldExtractor terminology scope fix, 2026-08-22)
 
@@ -155,3 +162,18 @@ status entry above for verification details.
   duplicate-method inventory being produced first.
 - **#2** (constraint -> HTML attribute mapping extraction): gated on a generality decision
   after Anlage Slice 4; whether to even start is undecided.
+
+## Dependencies
+
+- **Remove the `json < 3` pins once Rails ships the fix.** Added 2026-09-10 in
+  three places: `Gemfile` (dev/test), `script/build_demo.sh` (the demo app's
+  Gemfile), `templates/openehr_template.rb` (the generated host app's Gemfile).
+  Cause: `json` 3.0 (3.0.1 on 2026-09-08, 3.0.2 on 2026-09-09) changed
+  `JSON.parse`'s arity and `ActiveSupport::JSON.decode` as of activesupport
+  8.1.3.1 still passes options positionally, so every json-column read raises
+  `ArgumentError: wrong number of arguments (given 2, expected 1)`. Measured on
+  PR #39's CI run `34423912397` (62 failures, all RM-graph/AQL specs) and
+  reproduced locally with `bundle update` on `master`; with the pin and a fresh
+  resolve, 295 examples / 0 failures. Removal condition: an activesupport release
+  whose `JSON.decode` accepts json 3 (check the Rails CHANGELOG), then delete the
+  three pins in one docs+tooling commit and let CI resolve fresh.

data/docs/design/multi-leaf-non-observation-plan.md

@@ -1,6 +1,6 @@
 # Fix: multi-leaf non-Observation entries constrain a nonexistent `component`
 
-- Status: draft, awaiting approval
+- Status: **ruled 2026-08-27 — option (d), proper mapping, adopted. §§2-6 below are superseded; §8 is the normative spec, as corrected by §9 (the ruling's four corrections, applied 2026-09-10).**
 - Target: `openehr-rails` (this repo). No cross-repo work.
 - Issue: [#33](https://github.com/skoba/openehr-rails/issues/33)
 - Log: `docs/reports/fsh-generator-log.md` (continuing R1-R5)
@@ -178,3 +178,190 @@ this repo's division of labor, or directly if the change is judged small enough
 skip that split — decide at approval time), Claude Code review, full
 `bundle exec rspec` + full-repo `rubocop` + `sushi` re-verification for
 `bmi_calculation.opt`, commit(s), `docs/reports/fsh-generator-log.md` entry.
+
+
+---
+
+# 8. RULING (2026-08-27): option (d), proper mapping to `Condition`
+
+The recommendation in §3 — option (c), restrict multi-leaf non-`Observation`
+entries and raise — **was not adopted**. The ruling directs a *proper mapping*:
+`problem_diagnosis`'s leaves land on the real `Condition` elements that mean the
+same thing. §§2-6 are kept for the record but are superseded by this section.
+
+**This table is the single specification for both outputs.** `ProfileGenerator`
+(the JSON facade) and `FshGenerator` both generate from it; neither may carry a
+mapping decision the other doesn't.
+
+## 8.1 Mapping table — `openEHR-EHR-EVALUATION.problem_diagnosis.v1` → `Condition` (FHIR R5)
+
+Measured, not assumed: leaves are `FieldExtractor#entries` output for
+`spec/templates/problem_list.opt`; every target element was compiled against
+`hl7.fhir.r5.core#5.0.0` with `sushi` 3.16.0 (**0 Errors**) before this table was
+written.
+
+| openEHR leaf | Label (fixture, ja) | RM type | → `Condition` element | Rationale |
+|---|---|---|---|---|
+| *(archetype anchor)* | — | — | `category` — fixed coding `CKM#openEHR-EHR-EVALUATION.problem_diagnosis.v1` | The anchor cannot stay on `code`: under a proper mapping `code` is claimed by at0002, the diagnosis itself. `category` is R5's 0..* CodeableConcept for "what kind of Condition record is this", with an *example* binding, so a fixed archetype coding is legal there. |
+| `at0002` | プロブレム・診断名 | `DV_CODED_TEXT`, value set `http://id.who.int/icd/release/11/mms` | `code` 0..1, `only CodeableConcept`, `from <ICD-11 MMS> (required)` | `Condition.code` is "identification of the condition, problem or diagnosis" — the direct counterpart. Its base binding is *example*, so a profile may tighten it to *required*. |
+| `at0077` | 発症日時 | `DV_DATE_TIME` | `onsetDateTime` 0..1, `only dateTime` | `onset[x]` is the date/time the condition began; the `dateTime` choice matches `DV_DATE_TIME` exactly. (`sushi` normalises the path to `Condition.onset[x]` with `type: [dateTime]` — that is the shape the JSON facade emits.) |
+| `at0003` | 臨床的に認識された日時 | `DV_DATE_TIME` | `recordedDate` 0..1, `only dateTime` | Nearest R5 element. **Approximation, recorded as such**: `recordedDate` is "when this Condition record was created in the system", which is not a synonym for "clinically recognised". No closer element exists in R5; the gap is written down here rather than implied by the mapping. |
+| `at0030` | 治癒日時 | `DV_DATE_TIME` | `abatementDateTime` 0..1, `only dateTime` | `abatement[x]` is "the date the condition resolved or went into remission" — the direct counterpart. |
+| `at0073` | 診断確度 (`at0074` 疑い / `at0075` 推定 / `at0076` 確定) | `DV_CODED_TEXT`, `terminology_id = "local"` | `verificationStatus` 0..1, `only CodeableConcept`, **no value-set binding emitted** | `verificationStatus` (unconfirmed \| provisional \| differential \| confirmed \| refuted \| entered-in-error) is the semantic counterpart of 診断確度. See 8.2 for why the local codes are deliberately *not* bound. |
+
+**Nothing in this archetype is unmappable** — all five leaves land. What is
+deliberately *not* emitted is in 8.2.
+
+## 8.2 Deliberate omissions
+
+- **`at0073`'s local code list (`at0074`/`at0075`/`at0076`) is not bound.**
+  `Condition.verificationStatus` has a **required** binding to
+  `http://hl7.org/fhir/ValueSet/condition-ver-status`; binding an archetype's
+  local at-codes there would be invalid. Translating 疑い/推定/確定 into
+  `provisional`/`confirmed`/etc. is a `ConceptMap` concern, outside what a
+  `StructureDefinition` can express. The profile therefore constrains the
+  element's cardinality and type only. This means the current
+  `apply_value_constraints` behaviour — emitting
+  `binding: { strength: 'required' }` for any `DV_CODED_TEXT` carrying a local
+  `code_list` — must **not** apply to a mapped leaf.
+- **Multi-leaf non-`Observation` entries with no mapping table entry keep their
+  current behaviour.** The ruling scopes this fix to `problem_diagnosis`; the
+  `INSTRUCTION`→`ServiceRequest` case (`request-referral`, arriving with
+  referral v2) is reserved as its own Issue rather than generalised here.
+
+## 8.3 Where the table lives
+
+In `TypeMap`, next to `ENTRY_RESOURCES`, keyed by archetype id — the existing
+RM-type→FHIR-resource mechanism, not a new conditional scattered across the two
+generators. Both generators ask `TypeMap` the same question. The dead
+`TypeMap.value_element` (§1) is removed as part of this: it was a stub for
+exactly this resource-type branch and never implemented it.
+
+## 8.4 TDD
+
+- **Red**: `problem_list.opt`'s generated FSH under `sushi` 3.16.0 — measured
+  **29 Errors** today (all `No element found at path component…`). Pinned as the
+  starting measurement.
+- **Green**: the same fixture compiles with **0 Errors**. The exact rule set the
+  implementation must emit was pre-verified against
+  `hl7.fhir.r5.core#5.0.0` before implementation began.
+- **JSON facade**: `profile_generator_spec.rb` gains expectations for the mapped
+  `Condition` elements, and asserts no `Condition.component` element is produced
+  — the original complaint in #33.
+- **Regression pin**: `bmi_calculation.opt` (multi-leaf `Observation`) is
+  untouched by the new branch and must stay green, `component` slicing intact.
+
+## 8.5 Semver
+
+**Minor.** The JSON facade's output shape changes for `EVALUATION` entries
+(`Condition.component` slices disappear, real `Condition` elements appear), which
+is observable to any host app consuming `app/fhir/profiles/*.json`. Ships with
+`#34`'s `release:check` change; version finalised at release inventory, 0.7.0
+expected.
+
+# 9. RULING FOLLOW-UP (2026-09-10): the four corrections to §8, applied
+
+The 2026-08-27 ruling approved §8 **with four corrections**: (1) the archetype
+anchor is a *slice* of `category`, (2) `at0003`'s approximation is stated on the
+element as a `^comment`, (3) unmapped multi-leaf non-`Observation` entries are
+*skipped and reported* per entry, (4) through a named exception class. The
+implementation commit `01f31f3` (2026-08-27 12:38 JST) landed 21 minutes after §8
+itself (`07767cc`, 12:17 JST) and carries none of them; this repository held no
+record of the four points until this section. Applied under the reopened #33.
+Everything below was measured against `hl7.fhir.r5.core#5.0.0` with `sushi`
+3.16.0 before the code was written, as §8 was.
+
+## 9.1 Correction 1 — the anchor is a slice of `category`
+
+- **Before**: `* category.coding.system = "…"` / `* category.coding.code = #…`
+  (JSON: one `Condition.category` element with `patternCodeableConcept`).
+- **Why that was wrong**: `Condition.category` is `0..*`. Fixing the coding on the
+  element constrains *every* repetition, so a conforming instance could not also
+  carry e.g. `problem-list-item` beside the archetype coding.
+- **After**: pattern slicing on `$this`, `rules = #open`, `contains ckm 1..1`,
+  `category[ckm] = http://openehr.org/ckm/archetypes#<archetype id>` (FSH
+  assignment to a `CodeableConcept` is a `patternCodeableConcept`, the same shape
+  the JSON facade emits). JSON: two `Condition.category` elements — the slicing
+  root (`discriminator: [{type: pattern, path: $this}]`, `rules: open`) and the
+  `ckm` slice (`min 1`, `max "1"`, `patternCodeableConcept`). The slice name
+  reuses the name the FSH output already gives the CKM coding slice on
+  `code.coding`; it is `TypeMap::ANCHOR_SLICE` so both generators share it.
+- **Measured**: the candidate rule set compiled to **0 Errors** before
+  implementation; the generator's own output afterwards byte-matches the golden
+  and compiles to **0 Errors** together with `bmi_calculation.opt`.
+
+## 9.2 Correction 2 — `at0003` carries a `^comment`
+
+§8.1 records `at0003` → `recordedDate` as an approximation in this document only;
+the profile now says so itself. `ENTRY_ELEMENT_MAPS` gains a `:comment` key on
+the leaf, emitted as `* recordedDate ^comment = "…"` (FSH) and
+`ElementDefinition.comment` (JSON) — table-driven, so the two outputs cannot
+differ on the wording. Text: *Approximation: openEHR at0003 (Date/time clinically
+recognised) has no exact counterpart in FHIR R5 Condition; recordedDate is when
+this Condition record was created in the system. See
+docs/design/multi-leaf-non-observation-plan.md section 8.1.*
+
+## 9.3 Corrections 3 and 4 — skip-and-report, `UnsupportedProfileError`
+
+These answer §6's open questions 2 and 3.
+
+- **Condition**: an entry with **more than one leaf**, whose base resource is
+  **not `Observation`**, and which has **no row** in `ENTRY_ELEMENT_MAPS`. Before
+  this section such an entry silently took the `component` path — the original
+  #33 defect, still live for `ServiceRequest`/`Procedure`/`Encounter` (the
+  `[Unreleased]` CHANGELOG said as much).
+- **One decision point** (§3): `TypeMap.assert_supported!(entry)` raises
+  `OpenehrRails::Fhir::UnsupportedProfileError` (`archetype_id`, `resource_type`,
+  `leaf_count`, and a message naming all three plus #33/#35). Both generators
+  call it; neither carries its own conditional.
+- **Skip-and-report per entry, not raise-through** (Q2): `ProfileGenerator` and
+  `FshGenerator` partition entries at construction, generate for the supported
+  ones, and expose the errors in template order through `#skipped`. The batch
+  never aborts on one bad entry. The Rails generators (`openehr:fhir_profile`,
+  `openehr:scaffold --fhir`) print each skip as `say_status :skip, …, :yellow` —
+  the report reaches the person running the generator, and a library caller that
+  wants a hard failure re-raises from `#skipped`.
+- **Class** (Q3): `OpenehrRails::Fhir::UnsupportedProfileError < StandardError`,
+  in `lib/openehr_rails/fhir/unsupported_profile_error.rb`, required before
+  `type_map`.
+- **Not covered, deliberately**: single-leaf entries. The ruling's wording is
+  多葉 (multi-leaf); the single-leaf non-`Observation` path has its own defect,
+  recorded in 9.5 rather than folded in here.
+
+## 9.4 TDD (resolution shape (b) enhancement for all four)
+
+- **Red**: specs written first in `fsh_generator_spec.rb` and
+  `profile_generator_spec.rb` (slice, `^comment`/`comment`, skip-and-report,
+  `#skipped` empty for an all-`Observation` template) plus the regenerated
+  golden: **36 examples, 12 failures** on the pre-correction code.
+- **Green**: `spec/openehr_rails/fhir/`: **48 examples, 0 failures**; full suite
+  **304 examples, 0 failures** (295 before).
+- **Synthetic entry, spec-level, not a fixture file**: no real multi-leaf
+  `INSTRUCTION` OPT exists in this repo (#35 is blocked on exactly that), so the
+  skip-and-report specs stub `FieldExtractor` to return `problem_list.opt`'s real
+  entry plus one invented `INSTRUCTION` entry
+  (`openEHR-EHR-INSTRUCTION.synthetic_unmapped_test.v1`, two of the real leaves
+  relabelled). The id is self-evidently invented; the spec comment says so and
+  points here.
+- **Golden**: regenerated from the corrected generator, diffed against the
+  pre-verified candidate (identical), then compiled again: **0 Errors**.
+
+## 9.5 Residual found while measuring 9.1 — not fixed here
+
+A single-leaf non-`Observation` entry still takes the legacy path and emits
+`* value[x] 0..1` (FSH) / `<Resource>.value[x]` (JSON). `Condition` has no
+`value[x]` either: a hand-written probe (`Parent: Condition`, `* value[x] 0..1`)
+compiled under the same `sushi` run to **1 Error**, `No element found at path
+value[x] for CardRule`. No fixture in this repository reaches that path
+(`problem_list.opt` is 5-leaf; every single-leaf fixture entry is
+`OBSERVATION`), so nothing observable regressed. Outside the ruling's scope
+(多葉); filed as its own bug Issue rather than widened into #33 — the natural fix
+is to extend `assert_supported!` to it, but that is a second contract change and
+gets its own red spec.
+
+## 9.6 Semver
+
+Still **minor**, on top of §8.5: `#skipped` and `UnsupportedProfileError` are
+new public API; the `category` anchor and the `comment` change the JSON facade's
+shape again for `EVALUATION` entries. `CHANGELOG.md` `[Unreleased]` updated in
+the same change.