Add guidance governance module and drift gates

.github/workflows/ci.yml

@@ -39,6 +39,26 @@ jobs:
         run: |
           python -m goblin.validate --data samples/goblin-sample.ttl
 
+      - name: Generate guidance governance module (RDFLib)
+        run: |
+          python tools/generate_guidance_governance_module.py
+
+      - name: Verify generated guidance module is committed
+        run: |
+          python tools/generate_guidance_governance_module.py --check
+
+      - name: Validate SHACL on guidance governance sample
+        run: |
+          python -m goblin.validate \
+            --data samples/guidance-governance-sample.ttl \
+            --shapes goblin-guidance-shapes.ttl
+
+      - name: Enforce guidance conflict gate
+        run: |
+          python tools/report_guidance_conflicts.py \
+            --data samples/guidance-governance-sample.ttl \
+            --ontology goblin-guidance-ontology.ttl
+
       - name: Lint DOT (render to SVG)
         run: |
           dot -Tsvg goblin-map.dot -o /tmp/goblin-map.svg
@@ -47,4 +67,3 @@ jobs:
         run: |
           curl -I --fail https://service.tib.eu/webvowl/
 
-

CONTRIBUTING.md

@@ -6,6 +6,7 @@ Thank you for helping improve the Goblin ontology and visualizations.
 - Problem instances MUST use `ui:ProblemClass` (or a subclass) and SHOULD have a `ui:goblinScore` in [0,1].
 - UI-closure problems MUST include `ui:goblinScore` (enforced by SHACL).
 - Dimensions SHOULD include `ui:dimensionIndex` and `ui:energyRelevanceScore`.
+- Guidance requirements MUST use normalized topic + modality + provenance fields (see `goblin-guidance-ontology.ttl` and `goblin-guidance-shapes.ttl`).
 - Use `ui:hasScoreComponent` to attach per-dimension components (`ui:ScoreComponent`) with `ui:componentValue` in [0,1].
 - Use `ui:WeightAssignment` with `ui:forDimension` and `ui:hasWeight` for weight vectors. Prefer one canonical assignment (e.g. `ui:DefaultWeights`).
 - Optional relations between problem classes:
@@ -16,6 +17,7 @@ Thank you for helping improve the Goblin ontology and visualizations.
 
 ## Validation
 All changes are checked in CI via SHACL (pySHACL). Pushes/PRs must pass.
+Guidance-governance modules are generated via RDFLib; do not hand-edit generated module files.
 
 ## Visualization outputs
 The pipeline generates:
@@ -27,10 +29,11 @@ The pipeline generates:
 ## Contribution workflow
 1. Fork and branch from `main`.
 2. Update `goblin-ontology.ttl` (and `goblin-shapes.ttl` if adding constraints).
-3. Run local checks if possible (`tools/validate_shapes.py`).
-4. Open a PR with a summary of ontology changes.
+3. If guidance-governance terms/shapes change, update `tools/generate_guidance_governance_module.py` and regenerate:
+   - `python tools/generate_guidance_governance_module.py`
+4. Run local checks if possible (`tools/validate_shapes.py` plus guidance sample validation).
+5. Open a PR with a summary of ontology changes.
 
 ## Versioning
 We tag semantic versions for ontology releases and maintain a `CHANGELOG.md`.
 
-

README.md

@@ -7,6 +7,8 @@ This bundle contains:
 
 - `goblin-ontology.ttl` — OWL ontology defining Goblin score (SCIG), problem classes, dimensions, and example domains.
 - `goblin-shapes.ttl` — SHACL shapes constraining Goblin score usage.
+- `goblin-guidance-ontology.ttl` — OWL module for normalized guidance requirements (topics/modality/provenance).
+- `goblin-guidance-shapes.ttl` — SHACL module constraining guidance requirement instances.
 - `goblin-map.dot` — Graphviz DOT file for a "Goblin map" of common domains.
 - `goblin-agent-lim42.md` — lim42-ready agent spec for computing Goblin scores.
 - `goblin-energy-gradient.md` — energy gradient interpretation with simple flow equations.
@@ -19,6 +21,14 @@ Then validate data against the bundled shapes (after installation):
 python -m goblin.validate --data samples/goblin-sample.ttl
 ```
 
+Guidance-governance module:
+
+```bash
+python tools/generate_guidance_governance_module.py
+python -m goblin.validate --data samples/guidance-governance-sample.ttl --shapes goblin-guidance-shapes.ttl
+python tools/report_guidance_conflicts.py --data samples/guidance-governance-sample.ttl --ontology goblin-guidance-ontology.ttl
+```
+
 ## Meme / Usage
 
 Because "SCIG" is overloaded in Google (subcutaneous immunoglobulin), we use the meme name:
@@ -68,4 +78,3 @@ Use the existing lim42 agent prompt (`goblin-agent-lim42.md`) and weights to go
 
 - [SVG](docs/goblin-map.svg) — scalable version from the DOT source (`goblin-map.dot`).
 - To produce a PNG locally (not checked into the repo), run `dot -Tpng goblin-map.dot -o docs/goblin-map.png`.
-

docs/guidance_governance_additions_2026-03-07.md

@@ -0,0 +1,21 @@
+# Guidance Governance Additions (2026-03-07)
+
+Based on real failures encountered in cross-repo agent guidance work, Goblin now includes baseline support for guidance-governance modeling and drift checks:
+
+1. RDFLib-generated ontology module: `goblin-guidance-ontology.ttl`
+2. RDFLib-generated SHACL module: `goblin-guidance-shapes.ttl`
+3. Sample governed data: `samples/guidance-governance-sample.ttl`
+4. Conflict drift report tool: `tools/report_guidance_conflicts.py`
+5. CI enforcement for generation, SHACL validation, and conflict gate.
+
+## Why this was added
+
+- We observed policy drift when guidance was split across model-driven and hand-maintained sources.
+- We observed semantic overlap and conflicting clauses hidden by prose.
+- We observed conflict-prone merges in high-churn policy files.
+
+## Immediate next candidates
+
+- Add explicit precedence/authority modeling (for conflict resolution beyond polarity checks).
+- Add owner metadata for each requirement topic and enforcement policy.
+- Add baseline-vs-head conflict growth checks against repository history for real guidance datasets.

docs/guidance_model_pathology_2026-03-07.md

@@ -0,0 +1,55 @@
+# Guidance Model Pathology Note (2026-03-07)
+
+## Context
+
+Observed while tightening agent-governance gates in `eudorus`, but applicable to Goblin-style guidance systems.
+
+## Pathology
+
+A recurrent failure mode appears when guidance is partly model-driven and partly hand-maintained prose:
+
+1. Policy clauses are duplicated across multiple artifacts.
+2. Semantic coupling is implicit (inferred from wording), not explicit in a canonical model.
+3. Projection/generation covers only a subset of guidance surfaces.
+4. CI validates syntax/format but not cross-artifact semantic overlap.
+
+This yields "goblin-class" drift:
+- overlapping or contradictory norms,
+- frequent merge conflicts in high-churn policy files,
+- partial refactors leaving dead or inconsistent logic paths,
+- policy intent ambiguity during enforcement.
+
+## Triggering Example
+
+- Introduced stricter ontology-exemption governance and typo-only semantics.
+- Concurrent branch evolution changed adjacent exemption/authenticity policy text.
+- A code path introduced richer change-status parsing but still used synthetic status in enforcement.
+- Result: merge conflict + semantic ambiguity + inconsistent enforcement intent.
+
+## Hypothesis
+
+The root issue is under-modeled guidance dimensions, not just bad merge hygiene.
+
+Missing/weak dimensions usually include:
+- topic (normalized policy domain),
+- modality (`must`, `must_not`, `should`, `should_not`),
+- scope/target surface,
+- precedence/authority,
+- enforcement level,
+- provenance and ownership.
+
+## Recommended Controls
+
+1. Maintain a canonical normalized requirement model for guidance artifacts.
+2. Project host-specific guidance from model where possible.
+3. Add drift gates:
+   - fail on conflict-risk growth relative to base,
+   - fail on mixed-modality drift for key topics.
+4. Require explicit concept IDs for policy clauses to reduce inferred coupling.
+
+## Follow-up Work for Goblin
+
+- Add a first-class guidance ontology/schema for policy dimensions.
+- Add deterministic extraction from markdown/yaml guidance into that schema.
+- Add CI checks for topic-level modality conflicts and precedence violations.
+- Build a dashboard/report for conflict hotspots by topic and source file.

goblin-guidance-ontology.ttl

@@ -0,0 +1,68 @@
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix ui: <https://nkllon.com/ui#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ui:Must a ui:NormativeModality ;
+    rdfs:label "must" .
+
+ui:MustNot a ui:NormativeModality ;
+    rdfs:label "must_not" .
+
+ui:Policy a ui:NormativeModality ;
+    rdfs:label "policy" .
+
+ui:Should a ui:NormativeModality ;
+    rdfs:label "should" .
+
+ui:ShouldNot a ui:NormativeModality ;
+    rdfs:label "should_not" .
+
+ui:Topic_Branching a ui:GuidanceTopic ;
+    rdfs:label "branching" .
+
+ui:Topic_GitHubAuth a ui:GuidanceTopic ;
+    rdfs:label "github.auth" .
+
+ui:Topic_OntologyGovernance a ui:GuidanceTopic ;
+    rdfs:label "ontology.governance" .
+
+ui:Topic_QueuePrioritization a ui:GuidanceTopic ;
+    rdfs:label "queue.prioritization" .
+
+ui:enforcementLevel a owl:DatatypeProperty ;
+    rdfs:label "enforcement level" ;
+    rdfs:domain ui:GuidanceRequirement ;
+    rdfs:range xsd:string .
+
+ui:hasGuidanceTopic a owl:ObjectProperty ;
+    rdfs:label "has guidance topic" ;
+    rdfs:domain ui:GuidanceRequirement ;
+    rdfs:range ui:GuidanceTopic .
+
+ui:hasModality a owl:ObjectProperty ;
+    rdfs:label "has modality" ;
+    rdfs:domain ui:GuidanceRequirement ;
+    rdfs:range ui:NormativeModality .
+
+ui:sourceArtifact a owl:DatatypeProperty ;
+    rdfs:label "source artifact" ;
+    rdfs:domain ui:GuidanceRequirement ;
+    rdfs:range xsd:string .
+
+ui:sourceLine a owl:DatatypeProperty ;
+    rdfs:label "source line" ;
+    rdfs:domain ui:GuidanceRequirement ;
+    rdfs:range xsd:integer .
+
+ui:GuidanceRequirement a owl:Class ;
+    rdfs:label "Guidance Requirement" ;
+    rdfs:comment "Normalized governance requirement extracted from guidance artifacts." .
+
+ui:GuidanceTopic a owl:Class ;
+    rdfs:label "Guidance Topic" ;
+    rdfs:comment "Normalized topic for cross-artifact drift checks." .
+
+ui:NormativeModality a owl:Class ;
+    rdfs:label "Normative Modality" .
+

goblin-guidance-shapes.ttl

@@ -0,0 +1,53 @@
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix sh: <http://www.w3.org/ns/shacl#> .
+@prefix ui: <https://nkllon.com/ui#> .
+@prefix uiSh: <https://nkllon.com/ui/shapes#goblin#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+uiSh:GuidanceRequirementShape a sh:NodeShape ;
+    sh:property uiSh:Prop_enforcementLevel,
+        uiSh:Prop_hasGuidanceTopic,
+        uiSh:Prop_hasModality,
+        uiSh:Prop_sourceArtifact,
+        uiSh:Prop_sourceLine ;
+    sh:targetClass ui:GuidanceRequirement .
+
+uiSh:In_hasModality rdf:first ui:Must ;
+    rdf:rest uiSh:In_hasModality_0 .
+
+uiSh:In_hasModality_0 rdf:first ui:MustNot ;
+    rdf:rest uiSh:In_hasModality_1 .
+
+uiSh:In_hasModality_1 rdf:first ui:Should ;
+    rdf:rest uiSh:In_hasModality_2 .
+
+uiSh:In_hasModality_2 rdf:first ui:ShouldNot ;
+    rdf:rest uiSh:In_hasModality_3 .
+
+uiSh:In_hasModality_3 rdf:first ui:Policy ;
+    rdf:rest () .
+
+uiSh:Prop_enforcementLevel sh:datatype xsd:string ;
+    sh:message "GuidanceRequirement MUST define enforcementLevel." ;
+    sh:minCount 1 ;
+    sh:path ui:enforcementLevel .
+
+uiSh:Prop_hasGuidanceTopic sh:message "GuidanceRequirement MUST define hasGuidanceTopic." ;
+    sh:minCount 1 ;
+    sh:path ui:hasGuidanceTopic .
+
+uiSh:Prop_hasModality sh:in uiSh:In_hasModality ;
+    sh:message "GuidanceRequirement MUST define hasModality." ;
+    sh:minCount 1 ;
+    sh:path ui:hasModality .
+
+uiSh:Prop_sourceArtifact sh:datatype xsd:string ;
+    sh:message "GuidanceRequirement MUST define sourceArtifact." ;
+    sh:minCount 1 ;
+    sh:path ui:sourceArtifact .
+
+uiSh:Prop_sourceLine sh:datatype xsd:integer ;
+    sh:message "GuidanceRequirement MUST define sourceLine." ;
+    sh:minCount 1 ;
+    sh:path ui:sourceLine .
+

samples/guidance-governance-sample.ttl

@@ -0,0 +1,24 @@
+@prefix ui: <https://nkllon.com/ui#> .
+@prefix ex: <https://nkllon.com/example#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+ex:req1 a ui:GuidanceRequirement ;
+    ui:hasGuidanceTopic ui:Topic_GitHubAuth ;
+    ui:hasModality ui:Must ;
+    ui:sourceArtifact "AGENTS.md" ;
+    ui:sourceLine "42"^^xsd:integer ;
+    ui:enforcementLevel "hard" .
+
+ex:req2 a ui:GuidanceRequirement ;
+    ui:hasGuidanceTopic ui:Topic_OntologyGovernance ;
+    ui:hasModality ui:Must ;
+    ui:sourceArtifact "AGENTS.md" ;
+    ui:sourceLine "355"^^xsd:integer ;
+    ui:enforcementLevel "hard" .
+
+ex:req3 a ui:GuidanceRequirement ;
+    ui:hasGuidanceTopic ui:Topic_QueuePrioritization ;
+    ui:hasModality ui:Should ;
+    ui:sourceArtifact "AGENTS.md" ;
+    ui:sourceLine "30"^^xsd:integer ;
+    ui:enforcementLevel "soft" .