openehr-rails 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0bdb58aed10113d7fae2a48ef3819f0d999d8f9b5bc03adc8647eef8b357371
-  data.tar.gz: 78416c8a3208456cd7cc3d33a66354b623404a29044a78f94020d5098ac9faa0
+  metadata.gz: 69d9f917d3eb32a92e7d47aeb3f43bf8992a6a44f8ceb49320a1e5a6130ecebf
+  data.tar.gz: 1f39015dbd51241ea4dca624bd89e988a82bf62ef3a02964e54a343b6e8ccbf1
 SHA512:
-  metadata.gz: 4e2a343f8b63041b84dc4e364bb1f2d6a6bf4c586d377b43cd5e79c082dc7cb90c114084ddb325e3468d118b8d5fafef8c2171126d056ab02cf21282f2e0e2af
-  data.tar.gz: 6f90fd8358d753c85bcc3271830804e47837191c40b115058c75f1f53aae9995bc5f9e60919337df08d9367c81483fae3df5eec0b73084b0e94dc3277432ce17
+  metadata.gz: 5acec88b6d3dee1ab32167080639a81052911eee90043ae09474e083fa0c92e081da69dade909848da04743cffc96603e887765a8efaff29d6172f873e93a074
+  data.tar.gz: 1c134c5a1147f54ee8628b62efdcfcb867f257f634a5094a4f0aacb2af460ac28cfcaa011457017610262686437041ec85045186f9c05acb034ed4080e6ec793

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,49 @@
+---
+name: Bug report
+about: Something behaves incorrectly
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Summary
+
+<!-- One or two sentences: what's wrong. -->
+
+## Environment
+
+- `openehr-rails` version: <!-- e.g. 0.4.1 -->
+- `openehr` version: <!-- e.g. ~> 2.3 -->
+- Rails version: <!-- e.g. 8.1 -->
+- Ruby version: <!-- e.g. 3.3, 3.4, 4.0 -->
+- If the report involves an OPT/ADL file: the generating tool and its
+  version (e.g. Better Archetype Designer / Ocean Template Designer 2.6 /
+  ADL Workbench / LinkEHR / HMC).
+
+## Reproduction
+
+<!-- Minimal runnable code (a generator invocation, a snippet against a model, an
+     .opt/.adl fixture) that reproduces the bug from a clean checkout. -->
+
+```ruby
+```
+
+## Expected vs Actual
+
+- Expected:
+- Actual:
+
+## Root cause
+
+<!-- file:line, if known. Leave blank if not yet investigated -- explore/plan happens
+     after filing, not before. -->
+
+## Proposed fix
+
+<!-- Optional at filing time; fill in once a plan exists. -->
+
+## Acceptance criteria
+
+<!-- Spec-verifiable. E.g.: -->
+- [ ] A reproduction spec for this bug goes red on the current code, then green after
+      the fix (see CLAUDE.md's "Ticket-driven workflow": bug = red-first).

data/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

data/.github/ISSUE_TEMPLATE/enhancement.md

@@ -0,0 +1,37 @@
+---
+name: Enhancement
+about: Propose new behavior or a change to existing behavior
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Motivation
+
+<!-- Why this is needed -- what's painful or missing today, and for whom. -->
+
+## Current behavior
+
+<!-- What happens now. file:line references if known. -->
+
+## Proposed behavior
+
+<!-- What should happen instead/additionally. -->
+
+## Acceptance criteria
+
+<!-- Spec-verifiable. E.g.: -->
+- [ ] A spec for the new behavior goes red on the current code, then green once
+      implemented (see CLAUDE.md's "Ticket-driven workflow": enhancement = red-first).
+
+## Compatibility notes
+
+<!-- Surface this change touches -- check all that apply, and say how: -->
+- [ ] Runtime behavior
+- [ ] Public API
+- [ ] Install-time dependency (gemspec, supported Ruby/Rails versions)
+- [ ] Generator output (`lib/generators/**/templates/` -- migrations/scaffolding
+      shipped to and expanded inside host applications; counts as shipped product, see
+      CLAUDE.md)
+
+<!-- semver impact, if known: -->

data/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     env:
       BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/rails_${{ matrix.rails }}.gemfile
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}
@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: spec
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'
@@ -49,7 +49,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: spec
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'

data/.github/workflows/release.yml

@@ -12,20 +12,22 @@ jobs:
   ci:
     uses: ./.github/workflows/ci.yml
 
-  release:
-    name: Release to RubyGems
+  build:
+    name: Build gem artifact
     needs: ci
     runs-on: ubuntu-latest
-    permissions:
-      id-token: write # required for RubyGems Trusted Publishing (OIDC)
-      contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: '4.0'
           bundler-cache: true
       - name: release:check (clean tree, sibling-file tracking, gemspec validity)
         run: bundle exec rake release:check
-      - name: Release
-        uses: rubygems/release-gem@v1
+      - name: Build gem
+        run: bundle exec rake build
+      - name: Upload gem artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: gem
+          path: pkg/*.gem

data/CHANGELOG.md

@@ -7,8 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-08-26
+
+### Added
+- `OpenehrRails::Fhir::FshGenerator` renders one FHIR Shorthand profile per
+  openEHR entry, including metadata, archetype codes, value constraints,
+  component slicing, quantity units, fixed terminology codes, and required
+  external value-set bindings. Observation-mapped output is Sushi-verified;
+  multi-leaf non-Observation entries have a known structural gap tracked as #33.
+
+### Changed
+- `FshGenerator` no longer depends on `active_support/core_ext/string`; the
+  three String helpers it used are now small plain-Ruby private methods,
+  verified byte-identical output. Restores the Rails-independence this class
+  was designed for (see `anlage`'s `docs/design/fsh-plan.md`), so it can move
+  wholesale to a future satellite gem without a Rails dependency riding along.
+
+## [0.5.0] - 2026-08-25
+
+### Added
+- `FieldExtractor` fields now always include `value_set_uri` for external
+  `C_CODE_REFERENCE` value sets and `code_bindings` for ontology-level fixed-code
+  bindings. `OpenehrRails::Opt::Parser` temporarily enriches OPT terminology objects
+  with `term_bindings` until `skoba/openehr-ruby#31` is available upstream.
+
+### Fixed
+- `ProfileGenerator` now emits a required FHIR `binding.valueSet` for
+  `DV_CODED_TEXT` fields constrained by `C_CODE_REFERENCE`; these fields previously
+  received no binding. Existing local-code-list bindings remain strength-only. Host
+  applications must regenerate cached `app/fhir/profiles/*.json` files to receive
+  the new bindings.
+- For multi-alternative `value` constraints, `FieldExtractor` now prefers a
+  `C_CODE_REFERENCE`-backed alternative. This can change the extracted `rm_type` and
+  scaffold column behavior from `DV_TEXT` to `DV_CODED_TEXT` for affected templates.
+
+### Changed
+- Raised the `openehr` dependency floor to 2.3.1 because 2.3.0 cannot parse
+  `C_CODE_REFERENCE` constraints (`skoba/openehr-ruby#30`).
+
 ## [0.4.1] - 2026-08-22
 
+Errata: this release includes minor-level changes (Ruby >= 3.3 requirement,
+OpenehrRails namespace consolidation) and should be treated as a minor release
+when upgrading from 0.4.0.
+
 ### Fixed
 - `FieldExtractor` now resolves embedded-archetype element terminology in the nearest
   enclosing `C_ARCHETYPE_ROOT`, preventing both silent at-code collisions with the outer

data/CLAUDE.md

@@ -16,12 +16,111 @@ Follow the TDD framework as advocated by t-wada:
 - Write tests for areas of concern first
 - opt files must not be changed automatically.
 
+## Ticket-driven workflow
+
+- A change touching runtime behavior, public API, or install-time dependencies requires
+  a GitHub Issue filed before work starts — no code-change commit without one. Changes
+  limited to docs, CI, or dev-tooling config are Issue-optional.
+- **This repo's surface for that rule is not just `lib/`**: `lib/generators/**/templates/`
+  (the migrations and scaffolding code shipped to, and expanded inside, host
+  applications) is shipped product too. Changes there are Issue-required and subject to
+  the same semver judgment as any other runtime-behavior change.
+- Write Acceptance criteria in a spec-verifiable form.
+- Three resolution kinds, signaled in the PR body and in spec comments:
+  - **bug** — a reproduction spec goes red first, then gets fixed green.
+  - **enhancement** — a new-behavior spec goes red first, then gets implemented green.
+  - **pin/hardening** — fixing an existing property in place, where red isn't possible.
+    Mark this `regression pin` in a spec comment instead of staging a fake red.
+- 1 issue = 1 branch = 1 PR (reaffirms the existing convention); the PR closes with
+  `Fixes #N`. A `docs/design/` plan doc opens with the issue number.
+
 ## Working with implementation agents (e.g. Codex)
 
 Codex delivers only working-tree changes; it does not commit. Claude Code reviews the
 diff, then commits, recording the implementer in a commit message trailer (e.g.
 `Implemented-by: Codex`).
 
+## Release convention
+
+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.
+
+## Verification
+
+- **Verify against the repo before recording a fact in it**, even when a prompt or an
+  earlier report already stated it as true - a premise that went unverified once tends
+  to get repeated, not corrected, if the next write also skips checking (e.g. "CI is
+  unconfigured" repeated across two turns before anyone ran `gh run list`).
+- **The document a gate report points to must be pushed**, not just committed locally,
+  before the report is sent - a local-only SHA is unverifiable by anyone reading the
+  report. (Added 2026-08-25, after a gate report cited two docs-only commits - the #30
+  issue-filing log and its design doc - that were still local-only `master` commits,
+  not yet on `origin/master`.)
+- **After a git command appears to lose a file, search git's own storage
+  (`git stash show`/`stash@{n}^3`, `git reflog`, `git fsck --unreachable`) before
+  reconstructing content from memory.** Reconstruction from a model's own memory of
+  a file it recently read is a last resort, and if used, the result must be
+  independently diffed against the recovered original before trusting it - matching
+  by eye is not enough. (Added 2026-08-25, after a `git stash push -u` with a
+  multi-pathspec argument printed a pathspec error for one untracked file and that
+  file appeared to vanish from both the working tree and the stash's summary output;
+  it was in fact captured in the stash's untracked-files commit the whole time - the
+  error was cosmetic. The file was reconstructed from the session's own recent read
+  before that was confirmed, and only verified byte-identical against the actual
+  stashed copy afterward - the right outcome, but by the wrong order of operations.)
+
+## Repository-context-dependent commands confirm their target explicitly
+
+A command whose target (repository, branch, or resumed session) is decided by
+ambient state - cwd, current branch, or session history - rather than an
+explicit argument, must have that target pinned before it runs; never assume
+the shell or session is still where an earlier step left it.
+
+- If the tool has an explicit target option, always use it: `git` takes a `cd`
+  to the intended directory on the same command line (or `-C <path>`); `gh`
+  takes `-R <owner>/<repo>` (or `--repo`) on every invocation.
+- If the tool has no such option (e.g. `codex exec`, `codex exec resume`),
+  print `pwd` immediately before the call and confirm it names the intended
+  repository first.
+- Before adopting a new repository-context-dependent command for the first
+  time, decide how this principle applies to it before using it.
+
+(Generalized 2026-08-24, consolidating this repo's prior narrower
+`checkout`/`pull` rule with `openehr-ruby`'s branch-confirmation rule, after a
+third incident of the same class surfaced the need for one shared principle
+covering non-git tools too. Three incidents on record: (1) this repo,
+2026-08-22 - a mistaken `checkout`/`pull` ran against the wrong repo, caught
+and self-reported immediately, no lasting effect; (2) `openehr-ruby`,
+2026-08-23 - a docs-only commit intended for `master` landed on a
+checked-out PR feature branch instead; (3) `anlage`, 2026-08-24 - `codex exec
+resume --last`, run after cwd had silently drifted back to `openehr-ruby`,
+resumed an unrelated stale session in the wrong repo instead of the intended
+one; Codex itself detected the mismatch and made no changes, so there was no
+lasting effect, but the near-miss is what prompted this generalization. See
+`openehr-ruby`'s own copy of this rule and its `docs/backlog.md` entry
+logging the underlying structural fix under consideration - one
+worktree/session per repo instead of per-command vigilance.)
+
+## Cross-repository implementation work needs its own authorization gate
+
+The moment it becomes clear that the actual implementation target for a piece of
+work is a repository other than this one, stop before starting that work and insert
+a gate report confirming the implementation target, rather than sliding from
+read-only cross-repo reference (already permitted for design/evidence-gathering)
+into cross-repo write work on the strength of that same permission. Correctly
+targeting a command once you've decided to cross the boundary (the previous
+section's `cd`/`-C`/`-R` discipline) is a different concern from being authorized to
+cross it at all - following the operational convention precisely does not retroactively
+authorize the crossing.
+
+(Added 2026-08-26, alongside the `#32`/`#33` FSH-generator work continuation, to
+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.)
+
 ## Project Overview
 
 This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Template (`.opt`, ADL2/XML) into a working Rails resource in one command: `rails generate openehr:scaffold path/to/template.opt --fhir` emits a model, migration, controller, views, i18n locale, and (with `--fhir`) HL7 FHIR R5 `StructureDefinition` profiles. Generated models persist both as typed columns (for forms/search) and as full openEHR RM data (canonical JSON + a typed node graph with immutable-append versioning), and are queryable via a growing AQL surface. A mountable admin engine (`/openehr`) provides template upload/management, runtime scaffolding, and a FHIR R5 facade. Legacy ADL-archetype-only generators (model/controller/migration/helper/assets/i18n/template/template_model, based on `Openehr::Generators::ArchetypedBase`) have been removed — OPT is the only supported input format for scaffolding.
@@ -69,6 +168,28 @@ This is `openehr-rails`, a Rails engine gem that turns an openEHR Operational Te
 - `spec/openehr_rails/{opt,rm,fhir}/`, `spec/openehr_rails/*_spec.rb` - runtime library specs.
 - `spec/models/openehr_template_spec.rb`, `spec/unit/opt_parser_spec.rb` - registry model and parser specs.
 - OPT fixtures live in `spec/generators/templates/` and `spec/templates/`; do not hand-edit an existing `.opt` fixture (add a new one instead) — **opt files must not be changed automatically.**
+- Fixtures fall into four kinds; each fixture's leading comment must say which kind it is:
+  - **real** — a genuine artifact (CKM export, Archetype Designer output, a real host-app
+    template), used as-is.
+  - **reduced** — a trimmed-down real artifact; the comment must name the real source it
+    was reduced from.
+  - **synthetic** — hand-authored, not derived from any real artifact. real/reduced are
+    preferred by default; synthetic is only for structural test cases whose reproduction
+    conditions can't be controlled with a real artifact. The leading comment must say it's
+    synthetic and cite its design authority (e.g. a design doc section). Archetype
+    IDs/at-codes should use self-evidently invented names that can't be mistaken for real
+    ones — don't rename an existing fixture to fix this after the fact; its at-codes/
+    archetype IDs are reference anchors other specs/docs already point to, and freezing
+    those anchors takes priority.
+  - **security** — built to exercise an attack/abuse case; the comment must say it is not
+    a clinical artifact.
+  - A fixture's provenance comment must describe its lineage as measured (checked against
+    the actual design/implementation record), not as instructed — if an instructed lineage
+    doesn't match what actually went into the fixture, write it to match reality instead.
+  - Example: `spec/templates/lab_result_report_reduced.opt` is **synthetic** (design
+    authority: `docs/design/fix-terminology-scope-plan.md` §4; lineage confirmed
+    2026-08-22) — its filename says "reduced" for historical reasons, but per this
+    convention its actual kind is synthetic; the name stays as-is (reference anchor).
 
 ## Development Notes
 

data/docs/backlog.md

@@ -0,0 +1,157 @@
+# Backlog
+
+Non-blocking follow-ups noted during work on the upstream sprint queue. Not scheduled;
+pick up when the relevant gate opens or when convenient alongside other work in the same
+area. No code changes accompany entries here — this file is a record only.
+
+## CI status (verified, not a follow-up item)
+
+Both `.github/workflows/ci.yml` (`rspec` matrix on Ruby 3.3/3.4/4.0 x Rails
+7.2/8.0/8.1, plus `demo-smoke` and `application template smoke test` jobs; triggers
+on `push` to `master`, all `pull_request`s, and `workflow_call`) and
+`.github/workflows/release.yml` (triggers on `v*` tags, reuses `ci.yml` via
+`workflow_call`, then runs a RubyGems release job) exist on `master` — introduced at
+`412712d` (2026-08-12) and `2263298` (2026-08-13) respectively — and were confirmed
+actually running, not just present:
+
+- PR #26 (`fix/field-extractor-terminology-scope`): `pull_request` runs `32549486071`
+  and `32550157259` (2026-08-22, both success), post-merge `master` `push` run
+  `32550193330` (success). The merge landed (03:53:04Z) about 1m43s before the final
+  PR run finished (03:54:47Z) — CI ran and passed, but this doesn't demonstrate
+  merge-blocking enforcement.
+- Tag `v0.4.1`: `release.yml` run `32550344344` (2026-08-22T03:56:26Z) — all 11 reused
+  CI jobs green, but the run's overall conclusion is **failure**: the `Release to
+  RubyGems` job's `Release` step (`rubygems/release-gem@v1`) fails at "Configure
+  trusted publishing credentials" ("No trusted publisher configured for this workflow
+  found on https://rubygems.org for audience rubygems.org"); the actual gem-push
+  sub-steps are skipped, so CI never attempted to publish. rubygems.org's 0.4.1
+  listing was published by the human running `gem push` manually — no harm to the
+  actual release, only to the workflow run's color. Same failure shape on every tag
+  to date: v0.3.0 (runs `31655140867`, `31655495221`, `31655778244`) and v0.4.0 (run
+  `31660884406`), both failure. **This is structural, not incidental**: as long as
+  `release.yml` keeps a live RubyGems-publish step while the actual publish stays a
+  manual human `gem push` (the current, intended operating model), every future tag
+  push will reproduce the same red run. See "Release automation" below.
+- Most recent `master` push at the time of this record (`4055ec3`): CI run
+  `32569774700`, success.
+- **Tag `v0.5.0` (2026-08-25, #30): `release.yml` run
+  [32831263811](https://github.com/skoba/openehr-rails/actions/runs/32831263811) --
+  overall conclusion **success**, all 12 jobs green (9 reused `ci.yml` spec-matrix
+  jobs, `demo smoke`, `application template smoke test`, `Build gem artifact`).**
+  First fully-green tag-push run on record -- confirms the "Release automation fix
+  landed (2026-08-23, PR #28)" note below actually fixed the structural red
+  described above, not just that the workflow file changed (`v0.4.1`/`v0.4.0`/`v0.3.0`
+  were all red at the now-removed RubyGems-publish step; `v0.5.0` has no such step to
+  fail at). Downloaded the run's `gem` artifact and independently built
+  `pkg/openehr-rails-0.5.0.gem` locally at the same tagged commit (`69db63f`): both
+  197632 bytes, identical sha256
+  `e07815bd1c86736403cbb558fec869fbe04666f695e6cc12a41dad9be77230e6`. RubyGems
+  publish (human `gem push`, per "Release automation" below) confirmed complete via
+  `https://rubygems.org/api/v1/versions/openehr-rails.json`: version `0.5.0`,
+  `created_at: 2026-08-25T09:26:15.342Z`, published `sha` field matches the same
+  sha256 above exactly -- local build, CI artifact, and the published gem are all
+  byte-identical.
+
+Recorded here after this file previously claimed "this repo currently has no CI
+workflow gating pull requests" — wrong on both existence and execution. This file is
+the primary record for openehr-rails CI/release facts; openehr-ruby's own
+`docs/backlog.md` defers to it rather than duplicating (see that file's 2026-08-23
+correction, commit `bf17be7`) — do not duplicate this record back into openehr-ruby.
+
+**Release automation fix landed (2026-08-23, PR #28, `Fixes #27`)**: `release.yml`'s
+RubyGems-publish job is gone; tag pushes now run `ci` + `rake build` +
+`actions/upload-artifact` only (see "Release automation" below for the item this
+closes). Also bumped `actions/checkout` v4 -> v7 to clear the Node 20 deprecation
+warning noted in the v0.4.1 entry above. Verified, not just green: PR #28's own
+`pull_request` run `32611109196` — all 11 `ci.yml` jobs success, and the Node 20
+deprecation annotation is gone from every one of those 11 jobs (checked via the
+GitHub check-runs annotations API, not just the run log — each job's annotations
+array is empty, `[]`). Post-merge `master` `push` run `32611237453` — success. The
+renamed `build` job in `release.yml` (with `actions/checkout@v7` and the new
+`actions/upload-artifact@v7` step) is tag-triggered only and was not exercised by
+either of those runs; per PR #28's own body, no test tag was pushed to verify it —
+that verification is deferred to the next real release (>= 0.5.0), not simulated.
+
+## Release automation
+
+**Done (2026-08-23, PR #28)** — kept below for the original rationale; see the CI
+status entry above for verification details.
+
+- **Unify the release path**: remove `release.yml`'s RubyGems-publish job/step and
+  change tag-push handling to CI + `gem build` + artifact upload only, so the workflow
+  matches how releases are actually done today (human-gated `gem push`) and stops
+  going red on every tag for a step that was never meant to run automatically.
+  Automatic publishing via RubyGems Trusted Publishing can be re-evaluated when the
+  project's planned December public release and external-contributor model are
+  actually being designed — revisit the tag-before-inventory convention (`CLAUDE.md`'s
+  "Release convention" section) together with that decision at the same time, since
+  automatic publishing changes what "ready to tag" needs to mean. Timing: before the
+  next release (>= 0.5.0, per the "Versioning" item below). Out of scope for this
+  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.
+
+## From #25 / PR #26 (FieldExtractor terminology scope fix, 2026-08-22)
+
+- **Multi-level nesting regression test (CLUSTER in CLUSTER)**: the 0.4.1 fix and its
+  regression spec (`spec/openehr_rails/opt/field_extractor_embedded_archetype_spec.rb`)
+  cover one level of embedding (entry -> embedded CLUSTER). The underlying walk in
+  `FieldExtractor#collect_elements` is recursive and should handle a CLUSTER embedded
+  inside another embedded CLUSTER the same way, but this is currently unverified by any
+  test. Add a fixture/spec covering two levels of `C_ARCHETYPE_ROOT` nesting (openehr-ruby's
+  `spec/lib/openehr/opt_parser/eReferral.opt` already has a real two-level case:
+  `OBSERVATION.lab_test` -> `OBSERVATION.imaging` -> `CLUSTER.imaging`, per
+  `docs/design/fix-terminology-scope-plan.md` section 4). Suitable for a follow-on PR, not
+  urgent.
+
+## Compatibility
+
+- **STRICT-incompatible fixture: 1 known case** — `spec/templates/lab_result_report_reduced.opt`'s
+  leading comment uses `--` as an em dash (a double hyphen, invalid inside an XML comment);
+  under STRICT-mode XML parsing this file would fail to parse at all. See
+  openehr-ruby#36. Not fixed now — the current form is a live reproduction case for #36; if
+  #36 moves toward making STRICT the default, this comment's punctuation is the prerequisite
+  fix on this repo's side.
+
+## Fixture conventions
+
+- **Licensed terminology-code literals in spec expectations: keep minimal, cite the
+  source fixture's file:line.** Adopted from Anlage's C2 firewall precedent (SNOMED
+  CT is a licensed terminology; reproducing its codes verbatim in more places than
+  necessary widens exposure for no test-coverage benefit). Applies to SNOMED CT
+  specifically; **LOINC is exempt** (permissively licensed). Current count (#30,
+  2026-08-25): **2 SNOMED literal occurrences** in spec expectation code, both the
+  same code value `60621009`, both traceable to the same source fixture line --
+  `spec/openehr_rails/opt/field_extractor_binding_spec.rb:40` and
+  `spec/openehr_rails/opt/parser_term_bindings_spec.rb:28`, both citing
+  `spec/templates/bmi_calculation_without_uid.opt:1689` (and the identical
+  `spec/generators/templates/bmi_calculation.opt:1692`). No new SNOMED literal was
+  introduced by #30 -- reused the code already present in these existing fixtures.
+
+## Versioning
+
+- **Next release must be >= 0.5.0, regardless of its own content**, to retroactively
+  acknowledge in the version series that 0.4.1 was substantively a minor release (see the
+  errata in `CHANGELOG.md`'s `[0.4.1]` entry and the release convention added to
+  `CLAUDE.md`). Applies even if the next release's own changes would otherwise only
+  warrant a patch bump.
+
+## December public release prep
+
+- **Issue templates: done (2026-08-23, #29)** — `.github/ISSUE_TEMPLATE/` (bug_report,
+  enhancement, config.yml) is in place, along with `CLAUDE.md`'s "Ticket-driven
+  workflow" section.
+- **demo_assets README**: deferred to December prep. Note: no prior record of this
+  deferral was found anywhere in this repo's docs (`docs/`, `CLAUDE.md`,
+  `demo_assets/`) at the time of writing this entry — `demo_assets/` currently has no
+  README at all, only `demo_seed.rb` and `templates/`. Recording it here now as the
+  first record, not as confirmation of an earlier one.
+
+## Queue gating (do not start without an explicit go-ahead)
+
+- **#3** (registry checksum/version/status): gated on Anlage Slice 1 operational experience,
+  targeted around October.
+- **#4** (ValueBuilders extraction): gated on Anlage Slice 4 stabilizing and Anlage's
+  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.