feat(routines): validate semantic RDF with SHACL Core (#76)

Add a governed, offline SHACL Core gate for the RDF projections of the synthetic routine semantic fixtures.

Pin pySHACL 0.31.0, normalize deterministic diagnostics, and preserve the non-production validation boundary.

Author: jscott3201

SCHEMA.md

@@ -229,6 +229,12 @@ software-signal, derived-signal, aggregate, derivation, and policy terms used by
 the governed fixtures. It has no imports. Its SHA-256 is part of the pin record;
 changing the Turtle bytes requires updating that hash in the same change.
 
+`routines/ontology/shacl/open-control-routine-shapes.ttl` is the governed SHACL
+Core graph for the two synthetic semantic fixtures. Shape identifiers use
+`urn:open-control-library:shacl:routine:`; every OCL term in the graph MUST be
+declared by `ocl-vocabulary.ttl`. The graph defines no SPARQL constraints,
+SHACL-AF rules, or SHACL-JS. Validation performs no imports or inference.
+
 #### Routine semantic profiles (`cxf-library/routine-semantic-profile/v1`)
 
 A semantic profile has a stable JSON-LD `@id`, type
@@ -304,12 +310,20 @@ added to a registry, coverage claim, source inventory, book, or production
 catalog destination.
 
 `tools/lint/routine_semantics.py` checks the closed pin record, recomputes the
-local-vocabulary hash, parses the Turtle from local bytes, applies the same
-six-resource in-memory schema registry, rejects unsafe JSON-LD constructs before
-RDFLib parsing, and validates semantic and derivation cross-document rules. Its
-two fixtures under `tools/lint/tests/fixtures/routine_semantics/` are synthetic.
-Their point references are syntax examples and are not resolved against
-production dictionaries or routine interfaces.
+local-vocabulary hash, parses local Turtle bytes, applies the same six-resource
+in-memory schema registry, and rejects unsafe JSON-LD constructs before RDFLib
+parsing. It passes each fixture's parsed graph independently to pySHACL 0.31.0
+with imports, inference, advanced features, JavaScript, and in-place mutation
+disabled. SHACL reports are normalized into sorted diagnostics; Python retains
+the uniqueness, member, unit-policy, and cross-document checks.
+
+The SHACL graph checks the RDF projection's expected local classes and
+predicates, nested node/cardinality/datatype/class structure, and closed current
+entities. It does not duplicate every JSON Schema lexical rule or the Python
+checks above. The two fixtures under
+`tools/lint/tests/fixtures/routine_semantics/` are synthetic. Their point
+references are syntax examples and are not resolved against production
+dictionaries or routine interfaces.
 
 No external ontology is vendored or fetched. Brick, S223, and QUDT CURIE checks
 therefore prove closed syntax and selected S223 class and aspect policy, not that

routines/README.md

@@ -21,7 +21,8 @@ routine inventories:
 - `ontology/ontology-pins.json` fixes the Brick 1.4.4, ASHRAE 223
   1.0.0-ppr.2.1 compatibility, QUDT 3.1.4, and local OCL identities.
   `ontology/ocl-vocabulary.ttl` is the hashed Library-owned vocabulary for
-  software and derivation concepts.
+  software and derivation concepts. `ontology/shacl/` contains the SHACL Core
+  graph used against the synthetic fixtures' RDF projections.
 
 `g36/coverage.json` references the scope manifest, remains `planned`, and makes
 no implementation or completeness claims.
@@ -54,7 +55,7 @@ python3 tools/lint/g36_source.py --check \
 Run the remaining catalog gates from the repository root:
 
 `requirements-routine-schemas.txt` pins `jsonschema==4.26.0`,
-`referencing==0.37.0`, and `rdflib==7.1.4`.
+`pyshacl==0.31.0`, `referencing==0.37.0`, and `rdflib==7.1.4`.
 
 ```sh
 python3 -m venv /tmp/cxf-routine-schemas
@@ -82,14 +83,16 @@ specializations, generated deployments, or executable CXF.
 
 The semantic and derivation schemas are exercised only by synthetic fixtures
 under `tools/lint/tests/fixtures/routine_semantics/`. Validation is local and
-network-free. It checks closed syntax, local OCL terms, connector semantic-role,
-mapping-status and topology obligations, selected S223 class and aspect policy,
-member references, the shared ontology-pin authority, and the
-profile-to-derivation relationship. Connector dataflow does not reclassify an
-S223 property as observable or actuatable. The topology strings are authoring
-requirements, not building-instance certification. Validation does not certify
-external ontology term existence, resolve fixture point references against
-production dictionaries, compare a profile to a production interface, or
-validate a building instance. Production semantic profiles, derivation
-manifests, point migrations, SHACL certification, and routine classes remain
-deferred.
+network-free. JSON Schema and Python checks own closed JSON syntax, policy,
+uniqueness, references, and the profile-to-derivation relationship. The SHACL
+Core graph validates each RDF projection independently: expected local classes
+and predicates, nested node/cardinality/datatype/class structure, and closed
+current entities. It does not mirror every JSON lexical or cross-document rule.
+
+Connector dataflow does not reclassify an S223 property as observable or
+actuatable. Topology strings are authoring requirements, not building-instance
+certification. Validation does not certify external ontology term existence,
+resolve fixture point references against production dictionaries, compare a
+profile to a production interface, or validate a building instance. Production
+semantic profiles, derivation manifests, point migrations, building-instance
+SHACL certification, and routine classes remain deferred.