ci: publish ontology through GitHub Pages

.github/workflows/ontology-pages.yml

@@ -0,0 +1,138 @@
+name: Ontology Pages
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/ontology/**"
+      - "scripts/build_ontology_site.py"
+      - "scripts/publish_ontology_site.py"
+      - "scripts/ontology_site_contract.py"
+      - "tests/test_ontology.py"
+      - "tests/test_ontology_site.py"
+      - "tests/test_publish_ontology_site.py"
+      - ".github/workflows/ontology-pages.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+  push:
+    branches: [main]
+    paths:
+      - "docs/ontology/**"
+      - "scripts/build_ontology_site.py"
+      - "scripts/publish_ontology_site.py"
+      - "scripts/ontology_site_contract.py"
+      - "tests/test_ontology.py"
+      - "tests/test_ontology_site.py"
+      - "tests/test_publish_ontology_site.py"
+      - ".github/workflows/ontology-pages.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate ontology publication
+    if: github.event_name == 'pull_request'
+    concurrency:
+      group: ontology-pages-validation-${{ github.event.pull_request.number || github.ref }}
+      cancel-in-progress: true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Set up locked Python dependency manager
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.28"
+          enable-cache: false
+
+      - name: Install committed dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Verify ontology and publication contracts
+        run: |
+          uv run --frozen python -m pytest -q tests/test_ontology.py
+          uv run --frozen python -m coverage run --branch \
+            -m pytest -q tests/test_ontology_site.py tests/test_publish_ontology_site.py
+          uv run --frozen python -m coverage report \
+            --include=scripts/build_ontology_site.py,scripts/publish_ontology_site.py \
+            --fail-under=100
+
+      - name: Build static ontology site
+        run: uv run --frozen python scripts/publish_ontology_site.py --output-dir _site
+
+      - name: Compile owned Python surface
+        run: >-
+          uv run --frozen python -m compileall -q
+          scripts/build_ontology_site.py scripts/publish_ontology_site.py
+          scripts/ontology_site_contract.py
+          tests/test_ontology_site.py tests/test_publish_ontology_site.py
+
+  publish:
+    name: Publish ontology to GitHub Pages
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    concurrency:
+      group: ontology-pages-publication
+      cancel-in-progress: false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Set up locked Python dependency manager
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.11.28"
+          enable-cache: false
+
+      - name: Install committed dependencies
+        run: uv sync --frozen --extra dev
+
+      - name: Verify exact protected source before publication
+        run: |
+          uv run --frozen python -m pytest -q tests/test_ontology.py
+          uv run --frozen python -m coverage run --branch \
+            -m pytest -q tests/test_ontology_site.py tests/test_publish_ontology_site.py
+          uv run --frozen python -m coverage report \
+            --include=scripts/build_ontology_site.py,scripts/publish_ontology_site.py \
+            --fail-under=100
+
+      - name: Build deterministic publication artifact
+        run: uv run --frozen python scripts/publish_ontology_site.py --output-dir _site
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: _site
+
+      - name: Deploy GitHub Pages artifact
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

CHANGELOG.d/2.12.7-ontology-pages.md

@@ -0,0 +1,12 @@
+## Added
+
+- Added a deterministic GitHub Pages publication pipeline for the public
+  ontology documentation URL, with fragment-addressable terms and Turtle,
+  JSON-LD, N-Triples, PROV-O profile, and source-digest artifacts.
+- Added semantic round-trip, byte-determinism, fail-closed source, CLI, and
+  100% statement/branch coverage tests for the ontology site renderer.
+- Added a fail-closed publication boundary that prevents duplicate public
+  fragments, unsafe linked IRI schemes, symlink or source-overlapping outputs,
+  and deletion of output directories not marked as generated.
+- Restricted Pages deployment to `main`, preserved non-cancelling publication
+  concurrency, and kept all third-party Actions pinned by full commit SHA.

docs/adr/0154-published-ontology-pages.md

@@ -0,0 +1,109 @@
+# ADR 0154 — Publish the ontology namespace as a deterministic GitHub Pages artifact
+
+**Decision status:** Accepted
+**Date:** 2026-08-21
+
+## Context
+
+ADR 0004 established `docs/ontology/lineageweave-kg.ttl` as the formal,
+machine-validated OWL 2 / RDF Schema / SKOS vocabulary for LineageWeave. The
+repository already verifies that the ontology and relational controlled
+vocabulary do not drift. However, the product-facing URL
+`https://contextualwisdomlab.github.io/LineageWeave/ontology#` returned no
+published resource, so ontology terms shown to buyers and external consumers
+did not lead to a documentation endpoint.
+
+Publishing the authenticated LineageWeave application itself is not the right
+fix. The ontology is a public specification artifact. It must remain usable
+without tenant credentials, runtime APIs, PostgreSQL, contextual-orchestrator,
+or any private source data.
+
+A second concern is namespace identity. The knowledge-graph Turtle and runtime
+lookup predicate use the lowercase semantic namespace
+`https://contextualwisdomlab.github.io/lineageweave/ontology#`, while the
+committed PROV-O support profile and its contract test use the repository-case
+namespace `https://contextualwisdomlab.github.io/LineageWeave/ontology#`.
+GitHub Pages paths are case-sensitive. Silently rewriting either form would be
+a breaking ontology migration, not a deployment repair. Issue #372 therefore
+owns the inventory, canonical-namespace decision, compatibility vocabulary,
+and consumer migration plan.
+
+## Decision
+
+1. Add a deterministic Python renderer, `scripts/build_ontology_site.py`, that
+   reads the authoritative Turtle source and emits a static Pages tree.
+2. Publish a fragment-addressable HTML vocabulary at
+   `https://contextualwisdomlab.github.io/LineageWeave/ontology`, with one
+   stable anchor for every documented class, property, concept scheme, and
+   concept. A resource with more than one documented RDF type is rendered once
+   with one anchor.
+3. Publish equivalent machine-readable artifacts beside the HTML:
+   `ontology.ttl`, `ontology.jsonld`, `ontology.nt`, the PROV-O support profile,
+   and a source-digest manifest.
+4. Preserve `lineageweave-kg.ttl` byte-for-byte as the published Turtle
+   artifact. JSON-LD and N-Triples are generated from a canonicalized RDF graph
+   and are tested for semantic isomorphism with the source.
+5. Do not add a build timestamp. The same source tree must produce the same
+   artifact bytes. The manifest records the source SHA-256 instead.
+6. Run publication through `scripts/publish_ontology_site.py`, a fail-closed
+   boundary that rejects duplicate HTML fragments, non-HTTP(S) linked IRIs,
+   symlink outputs, source-overlapping outputs, and replacement of directories
+   that do not contain the generator marker. This prevents ontology data from
+   becoming executable links and prevents a misconfigured output path from
+   deleting unrelated files.
+7. Validate publication behavior on pull requests, including 100% statement
+   and branch coverage for both the renderer and publication boundary. Deploy
+   only from `main`; a manual dispatch from any other ref is not a publication
+   path.
+8. Pin every third-party GitHub Action by full commit SHA and grant Pages and
+   OIDC permissions only to the deployment job. Pull-request validation may
+   cancel superseded runs, while the single publication concurrency group does
+   not cancel an in-progress deployment.
+9. Keep existing semantic IRIs unchanged in this deployment PR. The Pages
+   document distinguishes the public documentation endpoint from the semantic
+   identifier. Issue #372 and a future versioned ADR must govern any namespace
+   migration, compatibility mappings, deprecation interval, and stored-data
+   migration.
+10. The repository must have Pages source set to **GitHub Actions** once. After
+    that administrative enablement, publication is entirely workflow-driven.
+
+## Consequences
+
+- The requested URL becomes a stable public specification surface after this
+  change reaches `main`, the repository Pages source is configured for GitHub
+  Actions, and the Pages environment completes successfully.
+- External consumers can inspect human-readable terms or download equivalent
+  RDF serializations without running LineageWeave.
+- A changed ontology cannot publish if its lookup-code contract, semantic
+  round-trip, deterministic-build contract, public-link safety, unique-fragment
+  contract, filesystem replacement boundary, or coverage gate fails.
+- GitHub Pages remains a static documentation host; it does not provide HTTP
+  content negotiation or become a graph database, SPARQL endpoint, or source
+  of runtime truth.
+- No private tenant data, runtime secrets, model output, or authenticated UI is
+  present in the artifact.
+- The existing case-distinct namespace forms remain a tracked interoperability
+  gap rather than being hidden by this deployment change.
+
+## Related decisions and work
+
+- [ADR 0004](0004-knowledge-graph-ontology.md): ontology and relational
+  vocabulary contract.
+- [ADR 0011](0011-prov-o-standard-relations.md): standard PROV-O relations.
+- [ADR 0065](0065-prov-o-provenance-boundary.md): provenance authority
+  boundary.
+- Issue #372: reconcile lowercase and repository-case public namespace IRIs.
+- PR #349: authenticated Ontology Explorer consumer surface.
+
+## References — APA 7th
+
+GitHub. (2026). *Using custom workflows with GitHub Pages*.
+https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages
+
+Sauermann, L., & Cyganiak, R. (2008). *Cool URIs for the Semantic Web*.
+World Wide Web Consortium. https://www.w3.org/TR/cooluris/
+
+Villazón-Terrazas, B., Vilches-Blázquez, L. M., Corcho, O., & Gómez-Pérez, A.
+(2011). Methodological guidelines for publishing government linked data. In
+D. Wood (Ed.), *Linking government data* (pp. 27–49). Springer.
+https://doi.org/10.1007/978-1-4614-1767-5_2

docs/product-technical-gap-baseline.md

@@ -65,8 +65,23 @@ corpus acceptance or protected release.
 | Accessibility and responsive UX | Unit coverage exists for major buyer surfaces | Keyboard, screen-reader, mobile, and authenticated Playwright acceptance on the exact release head |
 | External integrations | SearXNG, Zotero, calendar, and downstream consumer contracts are bounded | Provider conformance, failure/reconciliation behavior, and provenance-bearing integration evidence |
 | Release quality | Local focused/full suites have passed on individual PR heads | Repository-wide coverage, docstrings, Storybook, security, browser, and release evidence on one exact head |
+| Public ontology | PR #373 contains the deterministic Pages publication path | Protected merge, GitHub Actions Pages source, successful main deployment, and stable term-fragment dereference evidence |
 
-## 4. Evidence boundaries
+## 4. Public ontology publication boundary
+
+- PR #373 publishes fragment-addressable HTML, byte-identical Turtle,
+  isomorphic JSON-LD and N-Triples, the PROV-O support profile, and a
+  source-digest manifest from the authoritative ontology.
+- Pull requests validate only. Only protected `main` may publish, and the
+  generated-directory marker, linked-IRI, duplicate-fragment, symlink, and
+  source-overlap checks fail closed.
+- The lowercase knowledge-graph namespace and repository-case support-profile
+  namespace remain distinct until issue #372 delivers a versioned migration
+  and compatibility decision; this publication PR rewrites neither identity.
+- Until the protected deployment and exact URL checks succeed, the public
+  ontology endpoint remains unavailable and must not be represented as live.
+
+## 5. Evidence boundaries
 
 - Never add a real record, title, name, identifier, screenshot, log, benchmark
   artifact, or documentation example to this repository.
@@ -79,7 +94,7 @@ corpus acceptance or protected release.
 - Re-fetch base/head SHAs, checks, review threads, approvals, rulesets, and the
   merge SHA immediately before any lifecycle claim.
 
-## 5. Next acceptance loop
+## 6. Next acceptance loop
 
 1. Complete the in-flight Strix rerun on PR #387 at the same exact head and
    verify the merged central scope repair removed the false finding.