ci: publish ontology through GitHub Pages

.github/workflows/ontology-pages.yml

@@ -0,0 +1,135 @@
+name: Ontology Pages
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/ontology/**"
+      - "scripts/build_ontology_site.py"
+      - "scripts/publish_ontology_site.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"
+      - "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
+          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/0131-published-ontology-pages.md

@@ -0,0 +1,109 @@
+# ADR 0131 — 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

@@ -12,15 +12,23 @@
 - **Multiple Project Extraction**: (Resolved) LLM prompt updated to request key_events as objects with project_name, separating events correctly.
 - **5W1H Missing**: (Resolved) LLM prompt updated to explicitly request 5W1H evidence items in the JSON output array.
 - **R&R and Keyman Missing**: (Resolved) LLM prompt updated to explicitly instruct using actual stated names rather than collective titles.
-- **Entity Resolution / Searxng**: Abbreviations like "한전" and "한국전력" are not mapped properly using Searxng and KG corroboration. 
+- **Entity Resolution / Searxng**: Abbreviations like "한전" and "한국전력" are not mapped properly using Searxng and KG corroboration.
 - **Meso-level Team Mapping**: (Resolved) Checked extraction logic; `team` mapping logic is present and correct, but LLM needed better explicit instruction which is covered by R&R resolution.
 - **Base64 Image Omni-modal**: Current text-only embedding fails on images. Omni-modal LLM processing is required for images to capture layout, font size, colors, and spatial meaning.
 
 ## 3. General Architecture Gaps
 - **DB Architecture**: Ensure PostgreSQL is strictly used (no file DBs), 3rd normal form is maintained, and Hot Partitions are handled. DB locks must be managed (or use read/write replicas).
 - **Zotero Integration**: Papers and standards referenced by TEPP must be synced via Local Zotero API (http://localhost:23119/api/) and cited using APA 7th edition in docstrings.
 - **Testing**: We need actual testing of Psychometrics (Fast-MLSIRM parameter calibration, RMSE of estimates, Fixed-Item Parameter Calibration, CAT) against synthetic/demo data.
-- **Security & Compliance**: PII masking cannot break the system. Need SOC 2 and CSAP compliance alternatives to blind PII masking. 
+- **Security & Compliance**: PII masking cannot break the system. Need SOC 2 and CSAP compliance alternatives to blind PII masking.
 - **LLM Orchestration**: Ensure ALL LLM calls route through `contextual-orchestrator` utilizing API keys (BYTEZ, NVIDIA, OPENROUTER, OPENAI) with auto model discovery and optimal reasoning effort allocation (Fugu/Conductor/TRINITY research).
 
+## 4. Public Ontology Publication Gap
+- **Observed gap**: `https://contextualwisdomlab.github.io/LineageWeave/ontology#` has no deployed public resource even though the authoritative OWL/RDFS/SKOS Turtle ontology already exists in `docs/ontology/lineageweave-kg.ttl`.
+- **Active remediation — PR #373**: Add a deterministic GitHub Pages renderer, fail-closed publication boundary, and protected deployment workflow that publishes fragment-addressable HTML, byte-identical Turtle, isomorphic JSON-LD and N-Triples, the PROV-O support profile, and a source-digest manifest. PR #373 supersedes the contaminated predecessor PR #371 with a clean one-commit, eight-file diff.
+- **Publication safety**: The deployment path rejects duplicate term fragments, linked RDF IRIs outside HTTP(S), symlink outputs, source-overlapping output paths, and replacement of directories not marked as generated. Pull requests validate only; only `main` may publish, and an in-progress deployment is not cancelled by a newer run.
+- **Namespace boundary**: The knowledge-graph ontology/runtime use a lowercase `lineageweave` namespace while the PROV-O support profile uses repository-case `LineageWeave`. PR #373 does not silently rewrite either semantic identity. Issue #372 owns the inventory, canonical namespace decision, compatibility vocabulary, deprecation window, stored-data migration, and downstream consumer verification.
+- **Completion criteria**: Exact-head ontology/publication tests pass; owned renderer and publication-boundary statement/branch coverage is 100%; required security and repository Checks reach terminal success; an independent approval exists; the repository Pages source is GitHub Actions; the protected `main` deployment succeeds; and the requested URL resolves with stable anchors such as `#Post`.
+- **Current truth**: Until PR #373 is merged and the `main` Pages deployment is verified, the URL remains unbuilt and must not be reported as live.
+
 *This document is continuously updated by the hourly automated agent loop.*