feat: Governance schema extensions for agentic framework

[glandua]

Summary

Governance LinkML schemas for the agentic framework, based on @DarrenZal's work in #50 with security and schema review fixes applied.

• 5 new LinkML schemas: Agent, WorkOrder, GovernanceDecision, VoiceCouncilSession, CoherenceCheck
• Extended Entity.yaml with AGENT entityType
• Extended taxonomy.yaml with governance enums (GovernanceLayer, GovernanceActionType, AgentCapabilityType)
• Instance examples in playground/Governance/
• Updated scripts for KOI Fuseki triplestore integration
• New upload-ontology.sh script and Makefile targets

Review fixes applied (supersedes #50)

Security (Critical/High):

• Fixed command injection (RCE) in update-graph.sh and upload-ontology.sh: FUSEKI_GRAPH was shell-interpolated into Python strings. Now uses os.environ for safe access.
• Fixed argument injection in curl commands: $AUTH converted from string to bash array with "${AUTH[@]}" expansion (4 instances in update-graph.sh)

Schema (Medium/P2):

• Renamed evidenceIRIs → evidence in WorkOrder.yaml for consistency with GovernanceDecision.yaml and CoherenceCheck.yaml
• Changed CoherenceCheck.subjectId type from uriorcurie → string to match GovernanceDecision.subjectId and example data (bare IDs like WO-001)

CI note

Cloudflare Pages deploy check fails due to missing apiToken repo secret — this is a pre-existing infrastructure issue, not related to this PR. The Validate and Convert data check passes.

Test plan

• linkml-lint passes on all 5 new schemas
• linkml-validate passes on all 5 instance examples
• Existing schemas still validate (no regressions)
• make in schema/ completes without errors

Closes #50

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @glandua, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the system's governance capabilities by introducing a comprehensive set of LinkML schemas designed for an agentic framework. It enables the definition and tracking of agents, work orders, governance decisions, voice council sessions, and coherence checks. Alongside these new features, critical security vulnerabilities related to script execution and argument handling have been patched, and schema consistency has been improved, ensuring a more robust and secure data infrastructure for managing complex governance workflows.

Highlights

• New Governance Schemas: Introduced five new LinkML schemas (Agent, WorkOrder, GovernanceDecision, VoiceCouncilSession, CoherenceCheck) to support the agentic framework, enabling detailed definition and tracking of governance processes.
• Critical Security Fixes: Addressed command and argument injection vulnerabilities in update-graph.sh and upload-ontology.sh scripts, enhancing the security of triplestore interactions by safely handling environment variables and curl arguments.
• Schema Enhancements and Consistency: Extended Entity.yaml with an AGENT entity type and taxonomy.yaml with new governance-related enums (GovernanceLayer, GovernanceActionType, AgentCapabilityType). Also, schema consistency fixes were applied, such as standardizing subjectId types and slot names.
• Improved Triplestore Integration: Added dedicated update-fuseki and upload-ontology Makefile targets and updated scripts for more robust and secure integration with Apache Jena Fuseki triplestores.
• Instance Examples: Provided concrete instance examples for each new governance schema in the playground/Governance/ directory, aiding in understanding and validation.

Changelog

• schema/Makefile
  • Added update-fuseki target to update the graph specifically for Fuseki.
  • Added upload-ontology target to upload the OWL ontology.
• schema/data/playground/Governance/Agent-AGENT-001.yaml
  • Added an example instance for the new Agent schema, detailing a 'Registry Reviewer' agent.
• schema/data/playground/Governance/CoherenceCheck-CC-001.yaml
  • Added an example instance for the new CoherenceCheck schema, demonstrating an 'OPAL Check on WO-001'.
• schema/data/playground/Governance/GovernanceDecision-GD-001.yaml
  • Added an example instance for the new GovernanceDecision schema, illustrating a 'C09 Credit Class Recommendation'.
• schema/data/playground/Governance/VoiceCouncilSession-VCS-001.yaml
  • Added an example instance for the new VoiceCouncilSession schema, outlining a 'Weekly Governance Call - C09 Review'.
• schema/data/playground/Governance/WorkOrder-WO-001.yaml
  • Added an example instance for the new WorkOrder schema, defining a 'C09 Credit Class Review' work order.
• schema/scripts/update-graph.sh
  • Implemented set -euo pipefail for safer script execution.
  • Introduced a TARGET variable to differentiate between Oxigraph (default) and Fuseki uploads.
  • Added a dedicated section for Fuseki uploads, requiring specific environment variables (FUSEKI_GRAPH, FUSEKI_USER, FUSEKI_PASSWORD, FUSEKI_URL, FUSEKI_DATASET).
  • Fixed command injection vulnerability by using python3 -c "import urllib.parse, os; print(urllib.parse.quote(os.environ['FUSEKI_GRAPH'], safe=''))" for URL encoding FUSEKI_GRAPH.
  • Fixed argument injection vulnerability in curl commands by converting $AUTH to a bash array "${AUTH[@]}".
  • Modified the success message for graph deletion.
• schema/scripts/upload-ontology.sh
  • Added a new script to generate and upload the LinkML-generated OWL ontology to Fuseki.
  • Includes similar security fixes for environment variable handling and curl arguments as update-graph.sh.
• schema/src/Agent.yaml
  • Added a new LinkML schema defining the Agent class, including AgentCapability and GovernanceConfig classes, and AgentType and AgentStatus enums.
• schema/src/CoherenceCheck.yaml
  • Added a new LinkML schema defining the CoherenceCheck class, including OPALDimension and CoherenceThreshold classes, and CoherenceSubjectType and OPALDimensionType enums.
  • Ensured subjectId type is string for consistency with GovernanceDecision.subjectId and example data.
• schema/src/Entity.yaml
  • Extended the EntityType enum with a new AGENT value.
• schema/src/GovernanceDecision.yaml
  • Added a new LinkML schema defining the GovernanceDecision class, including GovernanceProcess and GovernanceStage classes, and DecisionType and GovernanceCategory enums.
  • Ensured evidence slot is used for consistency.
• schema/src/VoiceCouncilSession.yaml
  • Added a new LinkML schema defining the VoiceCouncilSession class, including Participant, SessionStage, and SessionSummary classes, and SessionType, SessionStageType, and SessionStatus enums.
• schema/src/WorkOrder.yaml
  • Added a new LinkML schema defining the WorkOrder class, including WorkOrderSpecification and WorkOrderResult classes, and WorkOrderType , WorkOrderStatus, and WorkOrderOutcome enums.
  • Ensured evidence slot is used for consistency, replacing evidenceIRIs.
• schema/src/schema.yaml
  • Updated to import the five new governance-related LinkML schemas.
• schema/src/taxonomy.yaml
  • Added new enums: GovernanceLayer, GovernanceActionType, and AgentCapabilityType.

Activity

• This pull request incorporates and supersedes the work from feat: Governance schema extensions for agentic framework #50, specifically addressing security and schema review feedback.
• Critical security fixes for command and argument injection in shell scripts have been applied.
• Schema consistency issues, such as renaming evidenceIRIs to evidence and standardizing subjectId types, have been resolved.
• The Cloudflare Pages deploy check is noted to be failing due to a pre-existing infrastructure issue (missing apiToken repo secret), which is unrelated to the changes in this PR.
• The Validate and Convert data CI check is passing.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant extension to the governance schemas for the agentic framework, adding five new LinkML schemas and corresponding example data. It also includes important security fixes and improvements to the data upload scripts for Fuseki and Oxigraph integration.

The new schemas for Agent, WorkOrder, GovernanceDecision, VoiceCouncilSession, and CoherenceCheck are well-defined and consistently structured. The example data files are helpful for understanding their usage.

The script updates are a major improvement. The security vulnerabilities related to command and argument injection have been correctly addressed by using bash arrays for arguments and safe environment variable access in Python.

I've added a couple of minor suggestions to the shell scripts to improve consistency and robustness. Overall, this is a high-quality contribution.