openehr-specs: README.adoc to README.md, no BMM work in the ITS repos, load every included BMM (#10)

[sebastian-iancu]

Fixes #10.

Summary

Scaffold template set revision 4 (unreleased, so it carries all three changes): README.adoc becomes README.md, BMM work stays out of the ITS repositories, and the class-table command loads every schema the BMM includes (#10). main, with #11, is merged in.

1. A root README.adoc becomes README.md

• README.adoc no longer stands in for README.md (it moves from alternatives to the new convert_from). The plan reports a new action, convert: a rewrite when README.md is missing, a merge-and-delete when both exist. README, README.rst and README.txt are still accepted as they are, and a repo with no README still gets one created.
• The script cannot translate AsciiDoc, so it writes nothing for this. The skill runs git mv README.adoc README.md to keep the history, then rewrites the markup by hand following the new scaffold/references/readme-markdown.md. That reference maps every construct the 13 existing README.adoc files use: titles, URL[text] and link: links, listings, admonitions, bold, one table and bullets. The rewrite must keep all content, and other files that name README.adoc are updated too.
• Nothing in specifications-AA_GLOBAL's publishing tooling reads a component's README.adoc, so the rename is safe for publishing.

2. ITS-XML, ITS-BMM, ITS-JSON and ITS-REST are excluded from BMM work

These repos hold no model of their own. ITS-BMM republishes the component repos' JSON and generates its ODIN and YAML with its own Makefile. ITS-XML holds XSDs, ITS-JSON JSON Schema (draft-07) files and ITS-REST OpenAPI, and bmm-publisher has no writer for any of those formats.

• scaffold: the bmm file gets excluded_components. Those repos are never offered a computable/BMM schema, even in init mode, and Docker is never asked. A non-empty bmm_schema_id or bmm_dependencies is reported as invalid there.
• bmm-authoring ("Where It Applies", plus a description anti-trigger), class-generation (Guardrails, workflow step 1) and regen-classes (new step 1): stop in those repos. They edit no schema there and run no bmm-publisher command, and they point to the component repo, or to ITS-BMM's make generate.
• scripts/validate.py: fails when any of these four skills does not name every id in files[bmm].excluded_components, so the prose cannot drift from the template set. For the scaffold the rule is enforced in code. For the other three it is an instruction the model follows.

3. #10: the class-table command loads every included schema

The AGENTS.md command loaded only BASE with -d. AM 2.4.0 also includes LANG, so its LANG types (STATEMENT_SET, ASSERTION, EXPR_LEAF, ...) came out as dangling /classes/<Type> links.

• New variable bmm_dependencies. It is comma-separated and worked out once bmm_schema_id is known, from that schema's includes (or the bundled copy's, for a new repo).
  • Order: BASE first for every component but BASE, using the version the schema includes when ../specifications-BASE holds it, else the highest there. Then every other included id, from ../specifications-<COMPONENT>/computable/BMM/ (openehr_lang_1.1.0 → LANG).
  • A missing clone is left out, with a warning.
  • BASE stays a default even without an include. TERM includes nothing, and without -d BASE its String links render as link:/classes/String (checked with bmm-publisher 0.12.0).
• Read from the repo on every run. A new variable flag, prefer_inferred, puts the inferred value ahead of the recorded one, so an include added later is picked up. An explicit --var still wins.
• base_bmm_schema_id is now derived from the list, for the empty-schema template's includes. Passing it with --var is an "unknown variable" error, as it is for every derived variable. The SKILL now lists bmm_dependencies among the values to confirm.
• Template engine: {{#each name}}…{{/each}} repeats its body per comma-separated item as {{item}}; a block nested inside it is rejected. A new component filter maps a schema id to its clone. The build region emits one -v mount and one -d per dependency. Unmodified AGENTS.md build regions update on the next run. For RM and TERM only the comment line changes, because their single BASE dependency gives the same mount and -d lines as before.
• Not followed transitively: each schema's own includes is read. That suffices today, because LANG includes only BASE. This is listed in maintaining.md in place of the old "One BMM dependency" limit.

Verification

• 261 unit tests pass. New ones cover convert (3), the ITS exclusion (3), and 11 dependency cases: the include order, TERM's default BASE, the included BASE version against the highest, a missing clone, a later include, an explicit empty list, a hyphenated component, the bundled copy's includes, a stale list dropped, and the rejected --var. Five {{#each}} engine tests cover the filter, empty lists, nesting, escaping and {{item}} outside a loop. validate.py and scaffold.py check pass; the new validator check failed on all four skills before their text was added.
• Read-only plan and render against the real sibling clones left every working tree unchanged:

Repo	readme	bmm	bmm_dependencies
AM	convert	exists (1.4.0, 2.4.0)	openehr_base_1.3.0, openehr_lang_1.1.0
RM	—	exists	openehr_base_1.3.0
TERM	—	exists	openehr_base_1.3.0
ITS-REST / ITS-JSON	convert	skipped	—
ITS-BMM	exists (already README.md)	skipped	—

• AM, end to end: I ran the class-table command that render writes into AM's AGENTS.md, unchanged. It mounts BASE and LANG and exits 0. The "not defined in any loaded schema" warnings drop from 5 (BASE only) to 1.

Out of scope: one AM type LANG 1.1.0 does not define

The remaining warning is EL_BOOLEAN_EXPRESSION. AM 2.4.0 uses it, but openehr_lang_1.1.0 does not define it; only LANG 1.0.0 and the 1.1.0 BMM3 overlay do. That is a gap in the AM/LANG models, not in the scaffold, and it belongs in a SPECAM or SPECLANG ticket.

Checklist

• python3 scripts/validate.py and python3 -m unittest discover -s scripts -p 'test_*.py' pass
• Skill triggering tested locally in Claude Code: not done. Only bmm-authoring's description changed, by one anti-trigger clause. The scaffold script was exercised against real repos as described above, but not through /openehr-specs:scaffold, and no README.adoc conversion was run end to end.
• Cursor install tested locally: not done. No manifest changes.
• Both marketplaces: not applicable, no plugin metadata changed
• CHANGELOG.md updated under Unreleased (Changed, plus a Fixed entry for scaffold: class-table command in AGENTS.md supports only one BMM dependency (AM 2.x also includes LANG) #10); no version bump
• Content grounded in the specifications and the repos as they are: the ITS repos' contents, bmm-publisher's commands and output, every schema's includes, and the README constructs were each checked against the clones

🤖 Generated with Claude Code