Archetype lint

Archetype Lint

An openEHR archetype linting engine. Evaluate archetypes against 22 normative rules. Classify each violation as ERROR, WARNING, or INFO. ERROR means the archetype is invalid or unsafe.

Step 1: Load Guides (MANDATORY)

guide_get("archetypes/rules")
guide_get("archetypes/structural-constraints")
guide_get("archetypes/anti-patterns")
guide_get("archetypes/terminology")

Step 2: Determine Mode

• STRICT: Zero WARNING tolerance. For publication candidates and CKM submissions.
• PERMISSIVE (default): WARNINGs allowed with justification. For early modeling iterations.

If the user does not specify a mode, use PERMISSIVE.

Step 3: Apply Lint Rules

The normative rule definitions live in the archetypes/rules guide loaded in Step 1 — that guide is the single source of truth. If this index ever disagrees with the loaded guide, the guide wins. Use the index below for rule numbering and severity; consult the guide for each rule's full definition, rationale, and worked examples before classifying a violation.

#	Rule	Severity	Group
1	Single Concept	ERROR	Core semantic
2	ENTRY Type Semantics	ERROR	Core semantic
3	Root RM Type Match	ERROR	Core semantic
4	Valid RM Attributes Only	ERROR	Core semantic
5	occurrences vs cardinality	ERROR	Core semantic
6	Specialisation Integrity	ERROR	Core semantic
7	Path Stability	ERROR	Core semantic
8	Term Definition Completeness	ERROR	Core semantic
9	Mandatory Data Justification	WARNING	Structural
10	Arbitrary Upper Bounds	WARNING	Structural
11	CLUSTER Semantics	WARNING	Structural
12	Slot Discipline	WARNING	Structural
13	Template Leakage	WARNING	Structural
14	Unconstrained Leaf Nodes	WARNING	ADL & AOM syntax
15	Attribute Multiplicity Compliance	ERROR	ADL & AOM syntax
16	Ontology Integrity	ERROR	ADL & AOM syntax
17	Terminology Neutrality	WARNING	Terminology
18	Semantic Binding Accuracy	WARNING	Terminology
19	Archetypable Demographics	INFO	Demographic
20	Identity vs Role Separation	ERROR	Demographic
21	Patch Version Discipline	ERROR	Versioning
22	Deprecation Handling	WARNING	Versioning

For rule 4, verify attribute names against the RM with type_specification_get when uncertain.

Offline fallback only: skills/openehr-assistant/reference/lint-rules-complete.md mirrors these definitions for the clinical-modeler agent (no MCP access). In the main session, always prefer the loaded archetypes/rules guide.

Avoid known false positives

• ITEM_TREE.items {0..*} is idiomatic — the established CKM convention for container attributes (e.g. the published ecg_result.v1). Do not flag it under rule 9 / structural-constraints when at least one contained ELEMENT is mandatory; reserve a finding for genuinely empty or all-optional containers. Flagging idiomatic items {0..*} is noise.

Step 4: Generate Report

Required Output Format

## Lint Report

**Archetype:** <archetype-id>
**Mode:** STRICT | PERMISSIVE
**Overall Status:** PASS | FAIL

### Violations

| # | Severity | Rule | Explanation | Suggested Fix |
|---|----------|------|-------------|---------------|
| 1 | ERROR    | R4   | Attribute `blood_pressure` is not a valid RM attribute on ITEM_TREE | Use `items` (valid RM path) |

### Summary
- ERRORs: N
- WARNINGs: N
- INFOs: N

Gating logic:

• Any ERROR -> overall status = FAIL
• STRICT mode: any WARNING -> overall status = FAIL
• PERMISSIVE mode: WARNINGs allowed if justified

Step 5: Fix Guidance (Optional)

If the user asks for fixes after linting, provide a minimal-diff fix plan:

• For each violation: which rule it resolves, whether it changes paths, whether it affects semantics
• Version bump recommendation (patch/minor/major) with justification
• Prefer template-level constraints over archetype constraints where applicable

Do NOT apply fixes automatically. Present the plan and wait for user approval.