feat: package ontology + validators, docs, examples, and CI

.github/workflows/ci.yml

@@ -59,6 +59,7 @@ jobs:
           npm run build
 
       - name: Upload artifact (docs)
+        if: ${{ env.ACT != 'true' }}
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs
@@ -77,5 +78,3 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
-
-

.github/workflows/js.yml

@@ -0,0 +1,28 @@
+name: JS Build and Checks
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  js:
+    name: Build JS package
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: js/goblin-ontology
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: js/goblin-ontology/package.json
+      - name: Install
+        run: npm ci || npm i
+      - name: Typecheck
+        run: npm run typecheck
+      - name: Build
+        run: npm run build
+      - name: Test
+        run: npm test

.github/workflows/validate.yml

@@ -0,0 +1,69 @@
+name: Validate Ontology and Docs
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  python-validate:
+    name: Python SHACL validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install rdflib pyshacl
+      - name: Validate sample JSON-LD against SHACL
+        run: |
+          python - << 'PY'
+          from rdflib import Graph
+          from pyshacl import validate
+          data = Graph()
+          data.parse("examples/sample_score.json", format="json-ld")
+          shapes = Graph()
+          shapes.parse("goblin-shapes.ttl", format="turtle")
+          conforms, report_graph, report_text = validate(data_graph=data, shacl_graph=shapes, inference='rdfs', advanced=True)
+          print(report_text)
+          assert conforms, "SHACL validation failed"
+          PY
+  dot-check:
+    name: Render DOT and check committed artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Graphviz
+        run: sudo apt-get update && sudo apt-get install -y graphviz
+      - name: Render goblin-map
+        run: |
+          dot -Tsvg goblin-map.dot -o docs/goblin-map.svg.new
+          dot -Tpng goblin-map.dot -o docs/goblin-map.png.new
+      - name: Fail if diffs vs committed images
+        run: |
+          set -e
+          if ! cmp --silent docs/goblin-map.svg docs/goblin-map.svg.new; then
+            echo "docs/goblin-map.svg differs from generated. Please regenerate and commit."
+            exit 1
+          fi
+          if ! cmp --silent docs/goblin-map.png docs/goblin-map.png.new; then
+            echo "docs/goblin-map.png differs from generated. Please regenerate and commit."
+            exit 1
+          fi
+  docs-link:
+    name: Verify docs links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check docs/kg.html references
+        run: |
+          set -e
+          test -f docs/goblin-map.svg
+          test -f docs/goblin-map.png
+          test -f goblin-ontology.ttl
+          test -f goblin-shapes.ttl
+          grep -q "goblin-map.svg" docs/kg.html
+          grep -q "goblin-ontology.ttl" docs/kg.html
+          grep -q "goblin-shapes.ttl" docs/kg.html

.gitignore

@@ -158,5 +158,3 @@ web/node_modules/
 *.egg-info/
 *.tar.gz
 *.zip
-
-

.pre-commit-config.yaml

@@ -0,0 +1,82 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+
+  # Local hooks mirroring GitHub Actions using Docker images (parity across machines).
+  - repo: local
+    hooks:
+      - id: python-validate
+        name: Python SHACL validation (mirrors validate.yml/python-validate and ci.yml)
+        language: system
+        entry: |
+          bash -lc '
+            docker run --rm \
+              -v "$PWD":/work -w /work \
+              python:3.11-slim \
+              sh -lc "apt-get update && apt-get install -y --no-install-recommends graphviz && python -m pip install --no-cache-dir -q rdflib pyshacl graphviz pydot && python tools/validate_shapes.py"
+          '
+        pass_filenames: false
+        require_serial: true
+        stages: [push]
+
+      - id: python-export
+        name: Export DOT/images and web JSON (mirrors ci.yml exporters)
+        language: system
+        entry: |
+          bash -lc '
+            docker run --rm \
+              -v "$PWD":/work -w /work \
+              python:3.11-slim \
+              sh -lc "apt-get update && apt-get install -y --no-install-recommends graphviz && python -m pip install --no-cache-dir -q rdflib graphviz pydot && python tools/export_instances_dot.py && python tools/export_web_json.py"
+            git diff --quiet -- docs/ || { echo ":: docs changed, commit generated artifacts"; git status --short docs/; exit 1; }
+          '
+        pass_filenames: false
+        require_serial: true
+        stages: [push]
+
+      - id: dot-committed-diff
+        name: Check goblin-map images up-to-date (mirrors validate.yml/dot-check)
+        language: system
+        entry: |
+          bash -lc '
+            docker run --rm \
+              -v "$PWD":/work -w /work \
+              debian:stable-slim \
+              sh -lc "set -e; apt-get update && apt-get install -y --no-install-recommends graphviz diffutils && dot -Tsvg goblin-map.dot -o docs/goblin-map.svg.new && dot -Tpng goblin-map.dot -o docs/goblin-map.png.new"
+            cmp -s docs/goblin-map.svg docs/goblin-map.svg.new && cmp -s docs/goblin-map.png docs/goblin-map.png.new
+          '
+        pass_filenames: false
+        require_serial: true
+        stages: [push]
+
+      - id: js-package
+        name: JS package typecheck/build/test (mirrors js.yml)
+        language: system
+        entry: |
+          bash -lc '
+            docker run --rm \
+              -v "$PWD":/work -w /work/js/goblin-ontology \
+              node:20 \
+              sh -lc "(npm ci || npm i) && npm run typecheck && npm run build && npm test"
+          '
+        pass_filenames: false
+        stages: [push]
+
+      - id: web-build
+        name: Web build to docs (mirrors ci.yml web build)
+        language: system
+        entry: |
+          bash -lc '
+            docker run --rm \
+              -v "$PWD":/work -w /work/web \
+              node:20 \
+              sh -lc "(npm ci || npm i) && npm run build"
+          '
+        pass_filenames: false
+        stages: [push]

CHANGELOG.md

@@ -15,4 +15,9 @@ All notable changes to this project will be documented in this file.
 ### Notes
 - Semantic versioning will track ontology schema changes going forward.
 
-
+## Unreleased
+### Fixed
+- SHACL failures due to `ui:forDimension` declaring a dual `rdfs:domain` of both `ui:ScoreComponent` and `ui:WeightAssignment`, which inferred nodes into both classes. Removed the domain to avoid unintended inference; SHACL now passes.
+- Regenerated `docs/goblin-map.svg` and `docs/goblin-map.png` from `goblin-map.dot` to match CI dot-check.
+### JS
+- Corrected `rdf-validate-shacl` dependency to `^0.6.5` and adjusted TS config/imports to pass typecheck and build under Node 20.

CONTRIBUTING.md

@@ -32,5 +32,3 @@ The pipeline generates:
 
 ## Versioning
 We tag semantic versions for ontology releases and maintain a `CHANGELOG.md`.
-
-

Makefile

@@ -0,0 +1,45 @@
+.PHONY: python-validate python-export dot-check js web ci ci-docker
+
+python-validate:
+	python tools/validate_shapes.py
+
+python-export:
+	python tools/export_instances_dot.py
+	python tools/export_web_json.py
+
+dot-check:
+	@set -e; \
+	dot -Tsvg goblin-map.dot -o docs/goblin-map.svg.new; \
+	dot -Tpng goblin-map.dot -o docs/goblin-map.png.new; \
+	cmp -s docs/goblin-map.svg docs/goblin-map.svg.new; \
+	cmp -s docs/goblin-map.png docs/goblin-map.png.new
+
+js:
+	cd js/goblin-ontology && (npm ci || npm i) && npm run typecheck && npm run build && npm test
+
+web:
+	cd web && (npm ci || npm i) && npm run build
+
+ci: python-validate python-export dot-check js web
+
+ci-docker:
+	docker compose run --rm python-validate
+	docker compose run --rm python-export
+	docker compose run --rm dot-check
+	docker compose run --rm js-package
+	docker compose run --rm web-build
+
+.PHONY: hooks hooks-push
+hooks:
+	pre-commit run --all-files --show-diff-on-failure
+
+hooks-push:
+	pre-commit run --all-files --hook-stage push --show-diff-on-failure
+
+.PHONY: act-ci-ghcr act-job-ghcr
+act-ci-ghcr:
+	bash tools/ci/run_act_ghcr.sh
+
+# Run a single job with GHCR-backed act, e.g.: make act-job-ghcr JOB=js
+act-job-ghcr:
+	bash -lc 'tools/ci/ghcr_login.sh && docker pull ghcr.io/nektos/act:latest >/dev/null && docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$$PWD":/github/workspace -v "$$HOME/.act":/root/.act -w /github/workspace ghcr.io/nektos/act:latest pull_request -P ubuntu-latest=catthehacker/ubuntu:act-latest -j "$${JOB}"'

README.md

@@ -11,6 +11,11 @@ This bundle contains:
 - `goblin-agent-lim42.md` — lim42-ready agent spec for computing Goblin scores.
 - `goblin-energy-gradient.md` — energy gradient interpretation with simple flow equations.
 
+## Quick links
+
+- Goblin map (rendered): see `docs/goblin-map.svg` and `docs/goblin-map.png`
+- Ontology visualization (WebVOWL): open `docs/kg.html`
+
 ## Meme / Usage
 
 Because "SCIG" is overloaded in Google (subcutaneous immunoglobulin), we use the meme name:
@@ -30,3 +35,76 @@ The Goblin score is defined in the ontology as `ui:goblinScore` and is an alias
 - Push this bundle into `nkllon/goblin` as initial commit.
 - Wire `goblin-agent-lim42.md` into lim42 as a reusable agent profile.
 - Render `goblin-map.dot` with Graphviz to produce a PNG/SVG for documentation.
+
+## CI parity (local)
+
+You can reproduce GitHub Actions locally in two ways:
+
+1) Docker Compose (dev-friendly)
+
+- Build/run the same steps as CI:
+
+```
+make ci-docker
+```
+
+- Or individual steps:
+
+```
+docker compose run --rm python-validate
+docker compose run --rm python-export
+docker compose run --rm dot-check
+docker compose run --rm js-package
+docker compose run --rm web-build
+```
+
+2) act (exact workflow runner)
+
+- Install: `brew install act` (macOS)
+- Run specific jobs matching `.github/workflows/*.yml`:
+
+```
+act pull_request -j validate-and-build
+act pull_request -j js
+act pull_request -j python-validate
+act pull_request -j dot-check
+act pull_request -j docs-link
+```
+
+3) act via GHCR (uses gh CLI for token at runtime)
+
+- Ensure GitHub CLI is logged in and has `read:packages`:
+
+```
+gh auth status
+gh auth refresh -h github.com -s read:packages
+```
+
+- Run all CI jobs via GHCR-backed act:
+
+```
+make act-ci-ghcr
+```
+
+- Run a single job:
+
+```
+make act-job-ghcr JOB=js
+```
+
+## Pre-commit (mirrors CI)
+
+Install pre-commit and enable hooks:
+
+```
+python3 -m pip install --user pre-commit
+pre-commit install
+pre-commit install --hook-type pre-push
+```
+
+Run all hooks (heavy, uses Docker to ensure parity):
+
+```
+pre-commit run --all-files --show-diff-on-failure
+pre-commit run --all-files --hook-stage push --show-diff-on-failure
+```