feat(openlabel-v2): migrate PAS 1883 to ISO 3450x with improved SHACL messages (#70)

* chore(linkml): pin submodule to feat/envited-x-pipeline

Pin linkml submodule to the consolidated feature branch containing
all ENVITED-X pipeline enhancements:

- feat(generators): deterministic RDFC-1.0 output with WL hashing
- feat(generators): --normalize-prefixes flag
- feat(generators): --default-language flag
- feat(gen-shacl): --message-template for sh:message
- feat(gen-shacl): sh:sparql from rules + exclusive-value patterns
- fix(owlgen): covering axiom edge cases
- fix(shaclgen): minCount/maxCount 0 for zero cardinality
- fix(shaclgen): sh:pattern in any_of
- fix(generators): normalize trailing newline in serialization
- fix(generators): bundle rdf_canonicalize in linkml package

Pin: 3d3a52a3

* feat(openlabel-v2): migrate PAS 1883:2020 to ISO 34503/34504

Migrate the openlabel-v2 LinkML schema from PAS 1883:2020 to the
published ISO 34503:2023 and ISO 34504:2023 standards.

Schema updates:
- Rename Road/Lane enums to match ISO 34503/34504 terminology
- Add EdgeNone mutual exclusion SPARQL rule
- Add correct-spelling alias for IntersectionGradeSeperated
- Add {comments} to SHACL --message-template for richer messages
- Strip trailing blank lines from generator output in Makefile

Artifacts:
- Regenerate OWL, SHACL, and JSON-LD context with new compiler

Test improvements:
- Add comprehensive valid instances for openlabel-v2
- Add cross-domain test instance
- Add fail12_edge_none_mutual_exclusion invalid test
- Update .expected files for improved SHACL messages

Documentation:
- Add linkml-modelling-guidelines.md for future reference
- Update agent instruction files

* fix(build): use POSIX-compatible sed for trailing newline removal

The inline sed pattern `sed '${/^$/d}'` can fail on macOS BSD sed.
Split into multiple -e expressions which is guaranteed POSIX-compliant
and works on both GNU sed (Linux) and BSD sed (macOS).

---------

Signed-off-by: Carlo van Driesten <carlo.van-driesten@bmw.de>

Author: jdsika

.github/copilot-instructions.md

@@ -123,6 +123,48 @@ Read these BEFORE making changes:
 - ❌ **Don't silently return `None`** - Raise specific exceptions
 - ❌ **Don't use `print()` for logging** - Use `logger` from `core/logging.py`
 - ❌ **Don't duplicate path normalization** - Use `normalize_paths_to_list()` or `normalize_path_for_display()`
+- ❌ **Don't commit with `--no-verify` without verifying** - If you must skip hooks (e.g., Windows CRLF loop), manually ensure generated artifacts have LF line endings and no trailing empty lines in `.context.jsonld`
+- ❌ **Don't assume generator output is CI-ready on Windows** - LinkML generators produce CRLF on Windows; CI runs on Linux with LF
+
+## Generated Artifacts & Line Endings (Windows/Linux CI)
+
+CI verifies that committed artifacts exactly match `make generate` output on Linux.
+On Windows, LinkML generators produce CRLF and trailing newlines that differ.
+
+**The CRLF commit loop on Windows:**
+1. `generate-linkml` hook produces CRLF → reports "files modified" → commit fails
+2. `mixed-line-ending` hook fixes to LF → reports "files modified" → commit fails
+3. Retrying repeats the cycle endlessly
+
+**Correct workflow on Windows:**
+
+```bash
+# Generate, then normalize before staging
+make generate DOMAIN=openlabel-v2
+
+# Fix CRLF → LF in generated files
+python -c "
+import glob
+for f in glob.glob('artifacts/openlabel-v2/*'):
+    with open(f, 'rb') as fh: c = fh.read()
+    c = c.replace(b'\r\n', b'\n')
+    with open(f, 'wb') as fh: fh.write(c)
+"
+
+# Remove trailing empty line from .context.jsonld (pretty-format-json removes it)
+python -c "
+f = 'artifacts/openlabel-v2/openlabel-v2.context.jsonld'
+with open(f, 'rb') as fh: c = fh.read()
+c = c.rstrip() + b'\n'
+with open(f, 'wb') as fh: fh.write(c)
+"
+
+# Now commit normally (hooks should pass)
+git add artifacts/ && git commit -s -S -m "feat: ..."
+```
+
+If hooks still fail, `--no-verify` is acceptable but **verify CI passes after push**.
+The committed state must be byte-identical to Linux `make generate` + hook normalization.
 
 ## Git Commit Policy
 

AGENTS.md

@@ -48,6 +48,62 @@ Read these before making changes; they are authoritative for repo workflows.
 - `registry_updater.py` writes catalogs (and is the only place using `file_collector.py`); `registry_resolver.py` reads catalogs.
 - Missing catalog entries should fail fast with clear errors; no silent fallbacks.
 
+## Generated Artifacts & Line Endings (Windows/Linux CI)
+
+This repo's CI runs on Linux and verifies that committed artifacts exactly match
+`make generate` output. When developing on **Windows**, the LinkML generators
+(`gen-owl`, `gen-shacl`, `gen-jsonld-context`) produce CRLF line endings and
+sometimes trailing newlines that differ from Linux output.
+
+**Pre-commit hooks involved:**
+- `generate-linkml` — regenerates artifacts (produces CRLF on Windows)
+- `mixed-line-ending` — normalizes to LF
+- `pretty-format-json` — reformats `.context.jsonld` (may add/remove trailing newline)
+
+**The problem:** On Windows, committing triggers a loop:
+1. `generate-linkml` hook produces CRLF artifacts → hook reports "files modified"
+2. `mixed-line-ending` fixes to LF → hook reports "files modified"
+3. Commit fails because hooks modified files; retry triggers step 1 again
+
+**Correct workflow when committing generated artifacts on Windows:**
+
+```bash
+# 1. Generate artifacts
+make generate DOMAIN=openlabel-v2
+
+# 2. Normalize line endings manually (Python one-liner)
+python -c "
+import glob
+for f in glob.glob('artifacts/openlabel-v2/*'):
+    with open(f, 'rb') as fh: c = fh.read()
+    c = c.replace(b'\r\n', b'\n')
+    with open(f, 'wb') as fh: fh.write(c)
+"
+
+# 3. For .context.jsonld specifically: ensure no trailing empty line
+#    (gen-jsonld-context adds one; pretty-format-json removes it)
+python -c "
+f = 'artifacts/openlabel-v2/openlabel-v2.context.jsonld'
+with open(f, 'rb') as fh: c = fh.read()
+c = c.rstrip() + b'\n'
+with open(f, 'wb') as fh: fh.write(c)
+"
+
+# 4. Stage and commit (hooks should now pass cleanly)
+git add artifacts/
+git commit -s -S -m "feat: ..."
+```
+
+**If hooks still loop**, use `--no-verify` but then immediately verify:
+```bash
+git commit -s -S --no-verify -m "feat: ..."
+# Push and check that CI "Generate Artifacts" job passes
+```
+
+**Key rule:** The committed state must be byte-identical to what Linux
+`make generate` + pre-commit normalization produces. CI enforces this via
+the "Verify no changes" step.
+
 ## Commit & Pull Request Guidelines
 
 - Recent history favors short, imperative subjects with optional prefixes like `feat:`, `fix:`, `docs:`, or scoped forms like `feat(ontology): ...`.

CLAUDE.md

@@ -256,3 +256,44 @@ Update both files **before** presenting the final result to the user. If a sessi
 - Silent `None` returns instead of raising exceptions
 - Using `print()` for internal progress (use `logger`)
 - Leaking absolute paths in output (use `normalize_path_for_display`)
+- Committing generated artifacts with CRLF or trailing newlines on Windows (CI fails)
+
+## Generated Artifacts & Line Endings (Windows/Linux CI)
+
+CI regenerates artifacts on Linux and diffs against the committed state. On Windows,
+LinkML generators (`gen-owl`, `gen-shacl`, `gen-jsonld-context`) produce CRLF line
+endings, causing pre-commit hooks to enter an infinite fix-loop.
+
+**Symptoms:**
+- Pre-commit hooks report "files were modified" on every attempt
+- `generate-linkml` → CRLF → `mixed-line-ending` fixes → hooks fail → repeat
+- CI "Generate Artifacts" job fails with "make generate produced different artifacts"
+
+**Fix (Windows development):**
+
+```bash
+# After generating artifacts, normalize before committing:
+python -c "
+import glob
+for f in glob.glob('artifacts/<domain>/*'):
+    with open(f, 'rb') as fh: c = fh.read()
+    c = c.replace(b'\r\n', b'\n')
+    with open(f, 'wb') as fh: fh.write(c)
+"
+
+# For .context.jsonld: strip trailing empty line (CI doesn't produce one)
+python -c "
+f = 'artifacts/<domain>/<domain>.context.jsonld'
+with open(f, 'rb') as fh: c = fh.read()
+c = c.rstrip() + b'\n'
+with open(f, 'wb') as fh: fh.write(c)
+"
+```
+
+**Key invariant:** Committed artifacts must be byte-identical to what Linux
+`make generate` + pre-commit normalization produces. When in doubt, use
+`--no-verify` to commit and verify that CI's "Generate Artifacts" job passes.
+
+**Root cause:** Python's LinkML generators inherit the platform's default line
+separator. The repo has no `.gitattributes` forcing `eol=lf` on generated files
+(potential future fix).

Makefile

@@ -208,9 +208,9 @@ _generate_default:
 	for domain in $$DOMAINS_TO_BUILD; do \
 		echo "  Processing $$domain..."; \
 		mkdir -p artifacts/$$domain; \
-		"$(GEN_OWL)" --deterministic --normalize-prefixes --xsd-anyuri-as-iri --no-metadata --default-language en --ontology-uri-suffix "" linkml/$$domain/$$domain.yaml 2>/dev/null | tr -d '\r' > artifacts/$$domain/$$domain.owl.ttl; \
-		"$(GEN_SHACL)" --deterministic --normalize-prefixes --no-metadata --default-language en --message-template "{name} ({class}): {description}" linkml/$$domain/$$domain.yaml 2>/dev/null | tr -d '\r' > artifacts/$$domain/$$domain.shacl.ttl; \
-		"$(GEN_JSONLD_CONTEXT)" --deterministic --normalize-prefixes --no-metadata --exclude-external-imports --xsd-anyuri-as-iri linkml/$$domain/$$domain.yaml 2>/dev/null | tr -d '\r' > artifacts/$$domain/$$domain.context.jsonld; \
+		"$(GEN_OWL)" --deterministic --normalize-prefixes --xsd-anyuri-as-iri --no-metadata --default-language en --ontology-uri-suffix "" linkml/$$domain/$$domain.yaml 2>/dev/null | tr -d '\r' | sed -e '$${' -e '/^$$/d' -e '}' > artifacts/$$domain/$$domain.owl.ttl; \
+		"$(GEN_SHACL)" --deterministic --normalize-prefixes --no-metadata --default-language en --message-template "{name} ({class}): {description} {comments}" linkml/$$domain/$$domain.yaml 2>/dev/null | tr -d '\r' | sed -e '$${' -e '/^$$/d' -e '}' > artifacts/$$domain/$$domain.shacl.ttl; \
+		"$(GEN_JSONLD_CONTEXT)" --deterministic --normalize-prefixes --no-metadata --exclude-external-imports --xsd-anyuri-as-iri linkml/$$domain/$$domain.yaml 2>/dev/null | tr -d '\r' | sed -e '$${' -e '/^$$/d' -e '}' > artifacts/$$domain/$$domain.context.jsonld; \
 	done
 	@echo "[OK] Artifacts generated"