Below is a first‑pass spec for an Indigenous Ontology Development Kit (iODK), plus explicit TODOs for your local agents wherever actual repo/state inspection is needed.

I’ll assume:

• The TS/npm packages (medicine-wheel-*) are the primary source of ontology semantics.
• RSIS‑GitNexus and IAIP are the main early consumers.
• You want something “ODK‑like” in lifecycle, not in tech stack (no blind copy of their Java/Make universe).

---

1. Purpose and Scope#

1.1 Problem#

You already have:

• A de facto ontology in medicine-wheel-ontology-core (types, enums, validators).
• Application stacks (RSIS‑GitNexus, IAIP, mcp-medicine-wheel-ui) that depend on those concepts but treat them as “just TS types”.
• Governance and sovereignty logic (OCAP, protected paths, ceremony requirements) embedded in app configs and code.

What is missing is:

• A central, tool‑assisted lifecycle for that ontology:
  • Versioned releases with clear contracts.
  • Generated artefacts (JSON Schema, OWL/SHACL, docs).
  • Automated Quality Control (QC) of relational, ceremonial, and governance constraints.
  • Standardized templates for projects using the ontology.

1.2 Goal#

Create indigenous‑ontology‑development‑kit (iODK):

• A toolkit + repository pattern that:
  • Treats medicine‑wheel ontology as single source of truth.
  • Generates multi‑format artefacts (TS/JSON, JSON Schema, OWL/SHACL, Markdown docs).
  • Runs Indigenous‑aware QC (relational completeness, OCAP compliance, directional balance, ceremony provenance).
  • Provides templates and CLIs for new ontology‑using projects.
• Keeps ontology and governance in one place, with applications as consumers, not definers.

1.3 Non‑Goals (for v1)#

• Not a generic replacement for all of ODK.
• Not an interactive ontology editor UI.
• Not a complete formalization of all Indigenous worldviews; v1 focuses on your existing medicine‑wheel stack.

---

2. High‑Level Architecture#

2.1 Core Components#

1. Ontology Source Module

   • Lives in a dedicated repo (or subpackage) that is the canonical definition of:
     • Core types (RelationalNode, Relation, CeremonyLog, Inquiry, KinshipHub, OcapFlags, NarrativeBeat, etc.).
     • Directional enums, node kinds, ceremony types.
     • Governance metadata types (OCAP, consent events).
   • Implemented in TypeScript as today, but with clearer boundaries.

2. Artefact Generator

   • CLI/Node tool that reads the TS definitions and emits:
     • JSON Schemas for each entity.
     • OWL ontology and/or SHACL shapes expressing key constraints.
     • JSON‑LD contexts.
     • Markdown reference docs.

3. QC Engine

   • Library + CLI that can:
     • Validate graphs (JSON, DB snapshots) against JSON Schema & SHACL.
     • Run Indigenous‑specific checks (relational completeness, OCAP, directional metrics, Wilson alignment).
   • Designed so RSIS‑GitNexus and others can call it in CI or runtime.

4. Governance & Ceremony Layer

   • Conventions + helpers for:
     • .iODK-governance.json (global) and per‑project governance configs.
     • “Ceremony‑required” changes (ontology and application scope).
     • Logging of ceremony events around ontology changes.

5. Templates & Scaffolding

   • Project template(s) a bit like ODK:
     • Ontology‑only repo template.
     • Consumer project template (e.g., TS service or MCP server) pre‑wired to iODK.

6. Integration Adapters

   • Thin packages or modules for:
     • RSIS‑GitNexus (KuzuDB schema + checks).
     • IAIP / other MCP servers.
     • Frontend libraries (link generated schemas/docs into UI).

---

3. Repositories and Packages#

3.1 New Repo: indigenous-ontology-development-kit#

Purpose: Home of iODK core logic, CLIs, templates, and generated artefact pipelines.

Proposed structure:

indigenous-ontology-development-kit/
  packages/
    ontology-core-spec/        # Core TS types (imported / mirrored from medicine-wheel-ontology-core)
    artefact-generator/        # CLI/library to generate JSON Schema, OWL, SHACL, docs
    qc-engine/                 # QC library + CLI
    governance/                # Governance model, config schemas, helpers
    templates/                 # Cookiecutter-like templates for repos
  examples/
    rsis-gitnexus-integration/ # Example config + scripts for RSIS
    iaip-integration/          # Example config for IAIP
  scripts/
    generate-all.sh            # Runs all generators
  .github/workflows/
    ci.yml                     # Lint, test, generate+validate

Local agent TODOs#

• Decide whether ontology-core-spec depends on medicine-wheel-ontology-core or re‑homes the core types here and makes medicine-wheel-ontology-core a thin wrapper.
• Inspect current medicine-wheel-ontology-core to list all core types and validators; document which are ontology vs convenience helpers.
• Decide monorepo tooling (pnpm workspace, turborepo, nx, or bare npm workspaces) to match your existing stack.

3.2 Existing medicine-wheel-* packages#

Direction:

• Keep them focused on runtime semantics and app‑facing APIs:

  • ontology-core: runtime entities & helpers.
  • relational-query: traversal and audit.
  • narrative-engine: narratives and beats.
  • graph-viz, UI, ceremony‑protocol: visual and workflow bindings.

• Shift ontology lifecycle (artefacts, QC specs) into iODK, with those packages importing from or being generated by iODK where appropriate.

Local agent TODOs#

• For each package, map out:
  • Public types that are ontology‑critical.
  • Functions that encode constraints (e.g., checkOcapCompliance, relationalCompleteness).
• Mark which pieces should be “owned” by iODK vs staying purely application‑side.

---

4. Ontology Source Specification#

4.1 TS Source Format#

In packages/ontology-core-spec/src:

• Use pure type and schema definitions, no app logic:

// directions.ts
export enum DirectionName {
  EAST = 'EAST',
  SOUTH = 'SOUTH',
  WEST = 'WEST',
  NORTH = 'NORTH',
}

// node-types.ts
export enum NodeType {
  PERSON = 'PERSON',
  LAND = 'LAND',
  SPIRIT = 'SPIRIT',
  ANCESTOR = 'ANCESTOR',
  FUTURE_ENTITY = 'FUTURE_ENTITY',
  KNOWLEDGE_ENTITY = 'KNOWLEDGE_ENTITY',
  FILE = 'FILE',
  INQUIRY = 'INQUIRY',
  KINSHIP_HUB = 'KINSHIP_HUB',
  // ...
}

// relational-node.ts
export interface RelationalNode {
  id: string;
  name: string;
  type: NodeType;
  direction?: DirectionName;
  metadata?: Record<string, unknown>;
  createdAt: string;
  updatedAt: string;
  ocap?: OcapFlags;
}

• All interfaces paired with Zod (or similar) schemas for runtime validation.

4.2 Governance Types#

Add explicit types for:

• OcapFlags (existing).
• ConsentEvent (who, when, scope, revocation).
• GovernancePolicy for ontology changes.

export interface ConsentEvent {
  id: string;
  subjectNodeId: string;
  grantedBy: string;
  scope: 'ONTOLOGY' | 'DATASET' | 'REPO' | 'OTHER';
  grantedAt: string;
  expiresAt?: string;
  revokedAt?: string;
  notes?: string;
}

Local agent TODOs#

• Mine existing governance usage (.rsis-governance.json, OCAP helpers) to finalize OcapFlags and related governance models.
• Align ConsentEvent and related types with your current ceremonial practices and any OCAP/IDS commitments you have in other docs.

---

5. Artefact Generator#

5.1 CLI: mw-odk artefact (working name)#

Commands#

• mw-odk artefact json-schema
  Generate JSON Schemas for all ontology entities.

• mw-odk artefact owl
  Generate an OWL ontology file from TS definitions.

• mw-odk artefact shacl
  Generate SHACL shapes expressing constraints.

• mw-odk artefact docs
  Generate Markdown documentation for entities and relations.

• mw-odk artefact all
  Run all of the above.

Behaviour#

• Uses TypeScript reflection / AST tooling (e.g., ts-morph, ts-json-schema-generator) to generate schemas from ontology-core-spec.
• Defines mapping rules for OWL:
  • Entities → OWL classes.
  • Enums → OWL classes + individuals or SKOS concepts.
  • Relations (STEWARD, SERVES, ...) → OWL object properties.
  • Constraints (cardinality, value types) from decorators or schema metadata.

Local agent TODOs#

• Evaluate TS → JSON Schema tools (e.g., ts-json-schema-generator, typescript-json-schema) and pick one that works with current build pipeline.
• Decide OWL generation strategy:
  • Use a Node‑side RDF/OWL library (e.g., rdflib.js) vs. generating Turtle/RDFXML by string templates.
• Decide SHACL representation (Turtle vs JSON‑LD).

---

6. QC Engine#

6.1 QC Dimensions#

The QC engine should cover at least:

1. Schema validity

   • JSON instances match JSON Schema.
   • SHACL constraints satisfied by graph snapshots.

2. Relational completeness

   • Every Inquiry has at least one SERVES edge from a File.
   • Every File in certain scopes has a STEWARDS relation.
   • Every BORNFROM points to a valid CeremonyLog.

3. OCAP & Governance

   • Nodes in protected scopes must have OcapFlags.
   • Operations referencing certain nodes must have matching ConsentEvent records.
   • No traversal into indexExclusions.

4. Directional and ceremonial balance

   • For a given time window, detect extreme imbalance across DirectionName in NarrativeBeat or CeremonyLog.
   • Flag incomplete ceremony cycles (no closure, missing phases).

5. Wilson‑style alignment metrics

   • Use existing helpers (e.g., computeWilsonAlignment) to compute scores and thresholds, flag low scores.

6.2 CLI: mw-odk qc#

Commands#

• mw-odk qc schema --input <fileOrUrl>
  Validate JSON data against generated JSON Schemas.

• mw-odk qc shacl --graph <fileOrEndpoint>
  Run SHACL validation (possibly via a local SHACL engine or external tool).

• mw-odk qc relational --graph <graphDump>
  Apply relational completeness checks.

• mw-odk qc ocap --graph <graphDump> --governance <config>
  Check OCAP and governance constraints.

• mw-odk qc direction --graph <graphDump> --window <period>
  Compute direction distribution; flag extremes.

• mw-odk qc all ...
  Run all relevant checks.

Local agent TODOs#

• Define actual input formats:
  • JSON graph dump format from KuzuDB (RSIS) and other systems.
  • Mapping from your internal graph representation to the QC engine’s expected format.
• Investigate Node‑compatible SHACL engines or decide to shell out to a Java‑based SHACL validator (Docker), similar to how ODK shells out to ROBOT / OWL API.

---

7. Governance and Ceremony#

7.1 Configuration File#

Introduce .iODK-governance.json at ontology repo root:

{
  "protectedPaths": [
    "ontology-core-spec/src/governance/**"
  ],
  "ceremonyRequiredChanges": [
    {
      "pattern": "ontology-core-spec/src/**",
      "ceremonyType": "ONTOLOGY_SCHEMA_CHANGE",
      "requiredRoles": ["ELDER", "STEWARD"],
      "notificationChannels": ["email:stewards@...", "mcp:ceremony-log"]
    }
  ],
  "indexExclusions": [
    "examples/**"
  ]
}

7.2 Ceremony Hooks#

• iODK does not enforce ceremony itself; it provides hooks:
  • Pre‑commit / pre‑merge hooks that check whether a given change matches a ceremonyRequiredChanges pattern.
  • If so, it expects a linked CeremonyLog or ConsentEvent ID in the commit message or PR metadata.

Local agent TODOs#

• Decide how you want to store and reference ceremony records:
  • In a dedicated repo (e.g., ceremony-ledger) or within each project repo?
  • Using what IDs and formats?
• Design the commit/PR annotation convention, e.g., CEREMONY: <ceremonyLogId> in PR body.

---

8. RSIS‑GitNexus Integration#

8.1 Schema Generation#

• Treat the KuzuDB schema as a generated artefact from the ontology:

  • Maintain a mapping file in iODK (e.g., kuzu-mapping.yml) that maps ontology entities/relations to KuzuDB tables/columns.

  • Generate KuzuDB DDL (or KuzuDB migration scripts) from this mapping:

    mw-odk artefact kuzu-schema --mapping config/kuzu-mapping.yml --out schema.kuzu.sql
    

• RSIS‑GitNexus then imports schema.kuzu.sql into its migrations.

Local agent TODOs#

• Extract current KuzuDB schema from RSIS‑GitNexus and express it as a mapping back to ontology entities.
• Decide whether KuzuDB is the only DB target or you want multiple DB target mappings.

8.2 CI Integration#

• In RSIS‑GitNexus repo, add CI steps:

  - name: Generate ontology artefacts
    run: mw-odk artefact all
  
  - name: Validate relational graph snapshot
    run: |
      rsis-export-graph --out graph.json
      mw-odk qc all --graph graph.json --governance .rsis-governance.json
  

• Fail builds on QC violations; provide human‑readable reports.

Local agent TODOs#

• Implement rsis-export-graph command to output a consistent JSON view of the current graph.
• Decide how often QC should run (every PR, nightly, pre‑release only, etc.).

---

9. Templates and Scaffolding#

9.1 Ontology‑Only Repo Template#

Template for a new ontology project (e.g., medicine-wheel-ontology-core v2 or another nation‑specific module):

• Standard directory layout:

  • src/ontology/ for types.
  • src/qc/ for project‑specific rules (beyond generic ones).
  • config/governance.json.

• Prewired package.json scripts:

  {
    "scripts": {
      "build": "tsc -p tsconfig.json",
      "artefact": "mw-odk artefact all",
      "qc": "mw-odk qc all --graph ./samples/graph.json"
    }
  }
  

9.2 Application Template#

Template for a TS service / MCP server that:

• Imports artefacts (JSON Schemas, OWL) from iODK.
• Exposes endpoints or tools that can:
  • Validate data using iODK’s QC engine.
  • Respect governance config.

Local agent TODOs#

• Decide templating system (e.g., degit, Yeoman, npm init custom, or cookiecutter‑style).
• Implement one “golden path” example project that uses the template and passes all checks.

---

10. External Dependencies and Borrowed Ideas#

You likely want to reuse conceptually (and possibly programmatically) from ODK and friends:

• ODK Makefile patterns for:
  • “ontology → QC → release” pipelines.
  • Release tagging/versioning.
• GitHub Actions patterns (matrix builds, release artefact uploading).
• Possibly Docker images for:
  • SHACL / OWL reasoning (via ROBOT or similar).

Local agent TODOs#

• Clone INCATools/ontology-development-kit locally and:
  • Identify minimal subset of Make targets and workflows that are directly relevant to artefact building and QC.
  • Decide which bits to re‑implement in Node vs. which to keep via Docker calls.
• Catalogue any licenses and ensure compatibility with your repos.

---

11. Action‑Oriented Summary for Local Agents#

Concrete tasks your local agents can start on, in order:

1. Current state mapping

   • Inspect medicine-wheel-ontology-core and enumerate:
     • Core ontology types.
     • Validators and helper functions.
   • Extract RSIS‑GitNexus KuzuDB schema; map tables/columns to ontology entities/relations.
   • Gather all governance configs (.rsis-governance.json, OCAP helpers) in one place.

2. Bootstrapping iODK repo

   • Create indigenous-ontology-development-kit repo with workspace/monorepo layout.
   • Create packages/ontology-core-spec by either:
     • Importing types from medicine-wheel-ontology-core, or
     • Moving them here and exporting back from medicine-wheel-ontology-core.
   • Set up basic build tooling (TS, lint, test).

3. Artefact generation MVP

   • Implement mw-odk artefact json-schema for a subset of entities.
   • Implement mw-odk artefact docs to emit Markdown docs from TS types + JSDoc comments.
   • Wire these into GitHub Actions.

4. QC MVP

   • Implement mw-odk qc schema using generated JSON Schemas.
   • Implement one or two relational checks (e.g., every Inquiry has at least one SERVES relation).
   • Add a sample graph JSON + test that QC passes/fails as expected.

5. Governance integration

   • Define .iODK-governance.json schema.
   • Implement a small pre‑commit/pre‑merge check script that:
     • Reads .iODK-governance.json.
     • Flags ontology‑affecting changes that lack a CEREMONY: annotation.

6. RSIS‑GitNexus integration

   • Add iODK as a dev dependency in RSIS‑GitNexus.
   • Implement rsis-export-graph and run mw-odk qc all on its output in CI.
   • Compare QC reports to your existing medicine‑wheel audits to ensure semantic alignment.

7. Iterate and extend

   • Once JSON Schema and docs work, add OWL/SHACL exports.
   • Gradually move more RSIS / IAIP assumptions into iODK artefacts and QC rules, so apps become thinner.

https://www.perplexity.ai/search/5e53a6d4-6d65-4fe1-b55c-fc1d6eee2845