medicine-wheel

Medicine Wheel — System RISE Specification

Relational software framework for Four-Directions inquiry, ceremony-aware development, narrative continuity, persistence, governance, and interactive tooling. The system keeps relational accountability visible across ontology, storage, orchestration, interfaces, and agent-facing surfaces.

Version: 0.6.3
Document ID: rispec-@medicine-wheel/system-v2
Parity Baseline: 2026-08-19

Desired Outcome

Users create relationally accountable software systems in which ontology, persistence, narrative, ceremony, inquiry, infrastructure, and interfaces can evolve without becoming disconnected islands.

The framework should make relations, consent, provenance, direction, ceremony, and uncertainty visible at the points where software would otherwise flatten them into generic records or invisible implementation detail.

Current Reality

The repository is no longer the fifteen-package system described by the earlier specification.

The current release line contains:

The system specification must therefore describe the architecture that exists now, not preserve an earlier package count as doctrine.

Structural Tension

Desired state: each package can deepen one domain while still participating in a coherent relational system.

Current pressure: rapid experimentation naturally produces parallel vocabularies, duplicated persistence paths, stale package maps, and interfaces that lag behind engines.

Natural resolution: preserve small canonical contracts at the seams — ontology-core for shared relational meaning, storage-provider for persistence meaning, explicit phase vocabularies, and agent/UI surfaces that invoke rather than bypass the domain engines.

Current Workspace Architecture

Workspace order is dependency-sensitive. The architecture is better read as layers than as one flat package list.

Foundation and environment

Ceremony and persistence

Narrative, perception, and knowledge

Orientation, review, and governance

Ceremony adapters and agent surfaces

Canonical Seams

1. Ontology seam

ontology-core is the shared relational grammar.

The top-level NodeType union remains six values: human, land, spirit, ancestor, future, knowledge. Domain-specific kinds such as production, infrastructure, and academic entities ride existing nodes through typed discriminators and bindings.

Relations remain first-class and can carry obligations, OCAP governance, Wilson accountability, ceremony context, authorization context, and governed kinship names.

2. Persistence seam

storage-provider is the cross-backend runtime persistence contract.

Implemented provider behavior:

Historical Redis and Postgres packages remain useful boundaries but do not supersede the provider contract.

3. Narrative seam

Narrative beats carry direction, act, ceremonies, learnings, relational honoring, optional cycle membership, telescoping lineage, and origin/provenance.

A surface that creates beats should pass through the narrative engine’s validation/authoring semantics rather than writing around them.

4. Ceremony seam

The system contains multiple legitimate phase vocabularies and must not collapse them:

Shared words do not imply one universal state machine.

5. Surface seam

Web, CLI, REST, MCP, and external consumers should expose domain capabilities without silently bypassing the rules those capabilities exist to enforce.

A feature is not complete merely because an internal engine exists. The serving surface is part of the system contract.

Persistence and Registry Families

The current storage-provider contract includes more than generic graph records.

Core families:

Registered families:

Capture registration stores records and URIs, never media bytes. Family-specific filtering, merging, provenance, and refusal behavior should remain centralized instead of being reimplemented independently by each backend or route.

API/Observability Invariants

The current system distinguishes a page from a total. Collection reads can be limited; whole-store counts use dedicated provider operations.

Filtering must not silently ignore unsupported parameters. When a route claims to filter, either the requested filter is actually applied or the request fails visibly.

Mutation failures should preserve their meaning. A node that still holds relations is a relational refusal, not merely a generic storage error and never an invitation to cascade-delete silently.

Core Conceptual Vocabularies

Four Directions

East   — vision, emergence, inquiry
South  — relationship, learning, preparation
West   — implementation, validation, embodied work
North  — integration, reflection, wisdom

Different packages may apply direction at different altitudes. Ceremonial teaching constants and working-session guidance are related vocabularies, not interchangeable fields.

Wilson’s Three R’s

The system can track these relationally and aggregate alignment, but the numbers do not replace human or community judgement.

OCAP®

Ownership, Control, Access, and Possession are held as governance information on relations. Consent additionally carries current state and affirmation timing where available.

Structural Tension

Creative advancement is represented through a desired outcome held together with current reality, producing action without replacing the tension with a problem-only frame.

Creative Advancement Scenarios

Scenario: A new domain enters without widening the ontology

Desired Outcome: Represent a new class of beings in a specialized domain.
Current Reality: The six core node kinds do not name that domain directly.
Natural Progression: Define a typed domain discriminator and binding onto existing node kinds; add specialized facets or relations outside the foundational enum.
Resolution: The domain becomes first-class enough to validate and query while the core ontology remains stable.

Scenario: Local persistence becomes hosted persistence

Desired Outcome: Move a working installation from local JSONL to hosted Postgres.
Current Reality: Application behavior already depends on provider-level operations.
Natural Progression: Select Neon through the canonical provider contract and validate observable parity.
Resolution: Location changes without rewriting domain semantics.

Scenario: An engine becomes reachable

Desired Outcome: Let a user or agent actually perform a domain capability.
Current Reality: Internal package logic exists but no reliable CLI/REST/MCP/UI path reaches it.
Natural Progression: Add a serving surface that invokes the same engine/validation path rather than duplicating or bypassing it.
Resolution: The capability becomes operational without creating a second interpretation of its rules.

Specification Parity Law

A RISE specification is not considered current because its prose remains philosophically aligned.

Parity requires checking at least:

  1. package/workspace existence and version line;
  2. exported domain types and runtime schemas;
  3. canonical provider or orchestration boundary;
  4. implemented versus deferred capabilities;
  5. REST/CLI/MCP/UI surfaces that materially change user-visible behavior;
  6. migration, pagination, filtering, refusal, and compatibility semantics where they are load-bearing;
  7. renamed concepts and deliberate aliases;
  8. recent changes that alter an invariant even if the package name did not change.

Implementation evidence may be listed in an appendix so the main RISE contract remains re-implementable without confusing current file paths with the conceptual design.

Quality Criteria

Implementation Evidence Appendix

This site is open source. Improve this page.