mirai-graph 1.4.0 → 2.1.0

package/standard/governance.md

@@ -1,137 +0,0 @@
-# Mirai Graph Governance
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Governance rules define how Mirai Graph controls updates, generated context,
-public claims and action-capable workflows.
-
-The central distinction is:
-
-```text
-suggestion != decision
-generated context != canonical state
-evidence != claim
-plan != action
-private material != public material
-```
-
-## Governance Gate
-
-A governance gate is a rule or checkpoint that decides whether something may
-proceed.
-
-Gate examples:
-
-- accept object into canonical graph;
-- accept relation into canonical graph;
-- publish material;
-- execute action;
-- generate external-facing context;
-- claim validation;
-- migrate from one standard version to another.
-
-## Gate Record
-
-A gate record should include:
-
-```json
-{
-  "id": "gate.public_release.synthetic_benchmark",
-  "kind": "governance_gate",
-  "title": "Public release check for synthetic benchmark",
-  "summary": "Checks that benchmark material is synthetic and public-safe before release.",
-  "readiness": "accepted",
-  "evidence": [],
-  "profile": "core"
-}
-```
-
-Future schemas may define a separate gate-result structure.
-
-## Update Governance
-
-Canonical graph updates should be gated when they:
-
-- change accepted objects;
-- change accepted relations;
-- resolve or introduce contradictions;
-- affect public claims;
-- affect action permissions;
-- change conformance status.
-
-Generated suggestions may propose updates, but they do not become canonical
-state until accepted through the appropriate gate.
-
-## Action Governance
-
-If a Mirai Graph implementation supports actions, it must separate:
-
-- proposed action;
-- authorized action;
-- executed action;
-- action evidence;
-- rollback or recovery path.
-
-Action-capable implementations need stricter gates than documentation-only
-implementations.
-
-## Public Release Governance
-
-Before public release, check:
-
-- no private source material;
-- no secrets;
-- no customer or employee data;
-- no private repository paths;
-- no unsupported validation claims;
-- licensing is clear;
-- synthetic materials are marked as synthetic.
-
-## Claim Governance
-
-Claims must be gated by evidence level.
-
-Example:
-
-- `The synthetic benchmark calculation is reproducible` may be claimed after a
-  passing benchmark run.
-- `Mirai Graph improves real-world productivity` requires real-world validation
-  evidence.
-- `Mirai Graph is universally valid` should not be claimed without broad
-  independent replication.
-
-## Human Oversight
-
-Mirai Graph can support AI-assisted work, but governance-sensitive operations
-should have human oversight.
-
-Human oversight is especially important for:
-
-- public claims;
-- external publication;
-- irreversible actions;
-- permission changes;
-- legal, financial, safety or privacy-sensitive decisions.
-
-## Failure Handling
-
-A governance gate may produce:
-
-- `pass`;
-- `pass_with_notes`;
-- `blocked`;
-- `rejected`;
-- `needs_more_evidence`.
-
-Blocked items should remain traceable. Do not delete a blocked element merely to
-make the graph look clean.
-
-## Anti-Patterns
-
-- Letting generated AI output directly mutate canonical state.
-- Treating approval for one profile as approval for all profiles.
-- Publishing synthetic evidence as real-world proof.
-- Hiding governance failures.
-- Combining private implementation notes with public standard text.

package/standard/graph-as-ai-brain.md

@@ -1,81 +0,0 @@
-# Graph As AI Brain
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-This section defines how Mirai Graph can model the stable brain of an AI
-employee without turning the standard into one specific AI-agent runtime.
-
-## Core Principle
-
-```text
-AI employee is not a prompt.
-AI employee is a governed runtime over an evolutionary graph.
-The graph is the canonical brain/state/control model.
-The runtime executes through tools, policies, approvals and audit.
-```
-
-## Brain Model
-
-In this model, the graph stores durable state:
-
-- identity of the AI employee;
-- department and role;
-- skills and specializations;
-- knowledge and memory references;
-- tools and capabilities;
-- policies and approval gates;
-- workflows and automation rules;
-- actions, results, feedback and lessons;
-- federation endpoints.
-
-The graph does not directly execute actions. It provides the structured state
-used by an implementation to generate context, select policies, request
-approval, call tools and record results.
-
-## Runtime Model
-
-An implementation may run an AI employee using:
-
-- an LLM or another reasoning engine;
-- a tool adapter layer;
-- queue or event processing;
-- policy evaluation;
-- approval workflows;
-- audit logging;
-- feedback evaluation.
-
-These runtime choices are outside the core standard. Mirai Graph standardizes
-the graph shape and safety boundaries that make implementations inspectable.
-
-## Required Distinctions
-
-An AI-employee implementation should keep these states separate:
-
-- canonical graph state;
-- generated context;
-- runtime decision;
-- proposed action;
-- approved action;
-- executed action;
-- audited result;
-- feedback;
-- accepted lesson or behavior update.
-
-Merging these states makes it difficult to audit why the employee acted, which
-policy applied, whether approval was required and what changed after feedback.
-
-## Anti-Patterns
-
-- Treating a prompt as the entire AI employee.
-- Letting generated context mutate canonical graph state.
-- Treating a runtime decision as permission to execute.
-- Recording only the final result without proposed action, policy and approval
-  trace.
-- Learning from feedback without replay, evaluation and approval.
-
-## Profile Link
-
-The `ai_employee` profile provides the first public object and relation set for
-this model.

package/standard/graph-dna-alignment.md

@@ -1,50 +0,0 @@
-# Graph DNA Alignment
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Graph DNA alignment keeps components, work batches, generated projections and
-runtime feedback aligned with the larger system purpose.
-
-It prevents local optimization: a component can be internally detailed but still
-harm the parent graph if it owns the wrong scope, violates invariants or drifts
-from the evolution vector.
-
-## Core Pattern
-
-```text
-parent DNA
--> component DNA
--> ownership boundary
--> invariants
--> anti-patterns
--> success criteria
--> alignment result
-```
-
-## Minimum Concepts
-
-- parent system DNA: mission, evolution vector and non-negotiable principles;
-- component DNA: why the component exists and what value it creates;
-- owns: responsibilities the component is allowed to own;
-- must not own: responsibilities that must stay elsewhere;
-- invariants: properties that must remain true during change;
-- anti-patterns: recurring shapes that indicate drift;
-- success criteria: observable evidence that the component serves the parent.
-
-## Rules
-
-- A component must not redefine the parent system direction.
-- A component that conflicts with parent DNA needs a proposal or a blocker.
-- Generated projections can reveal DNA gaps but cannot change DNA by
-  themselves.
-- Implementation work should load relevant DNA before crossing a launch gate.
-
-## Schema
-
-Machine-readable alignment results can be validated with:
-
-```text
-schemas/graph-dna-alignment.schema.json
-```

package/standard/graph-dna.md

@@ -1,70 +0,0 @@
-# Mirai Graph DNA
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Mirai Graph DNA defines why a graph exists, what it should become and which
-principles must guide its growth.
-
-Without DNA, a graph can collect objects and relations but still drift into an
-uncontrolled archive. DNA keeps growth aligned with purpose.
-
-## Definition
-
-Graph DNA is the development contract of a graph.
-
-It answers:
-
-- why the graph exists;
-- what larger system it serves;
-- what kind of growth it should enable;
-- which principles cannot be violated;
-- which object families belong inside the graph;
-- which entity families should become separate graphs;
-- how success will be recognized.
-
-## Minimum Fields
-
-```json
-{
-  "schema_version": "0.1.0",
-  "graph_id": "example.graph",
-  "purpose": "Why this graph exists.",
-  "parent_dna_ref": null,
-  "evolution_vector": "Where the graph should develop.",
-  "non_negotiable_principles": [],
-  "allowed_entity_families": [],
-  "success_criteria": []
-}
-```
-
-## Alignment Rule
-
-Every significant accepted object should be able to explain:
-
-- how it serves the graph purpose;
-- what it contributes to the evolution vector;
-- what would be harmed if it were missing;
-- whether it belongs in this graph or should become a separate graph.
-
-If an object cannot answer these questions, keep it as a draft idea or separate
-graph candidate.
-
-## Relationship To Graph Seed
-
-Graph DNA defines what the graph must become.
-
-Graph Seed defines how the first controlled growth step should start.
-
-```text
-Graph DNA -> Graph Seed -> Graph Embryo -> Canonical Graph State
-```
-
-## Anti-Patterns
-
-- Creating many objects without a purpose.
-- Treating every related entity as part of the same graph.
-- Adding relation types that do not support the evolution vector.
-- Optimizing for local detail while losing the larger system goal.
-- Changing DNA silently after downstream artifacts depend on it.

package/standard/graph-embryo.md

@@ -1,69 +0,0 @@
-# Mirai Graph Embryo
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-A Graph Embryo is the first candidate graph state generated from a Graph Seed.
-
-It is reviewable and disposable until accepted. It should be small enough for
-human review and structured enough to show the likely growth direction.
-
-## Definition
-
-A Graph Embryo contains candidate graph elements before canonical write:
-
-- candidate objects;
-- candidate relations;
-- uncertain objects;
-- missing evidence;
-- rejected or deferred candidates;
-- review questions;
-- growth-gap notes.
-
-## Relationship To Canonical State
-
-The embryo is not canonical state.
-
-Flow:
-
-```text
-Graph Seed -> Graph Embryo -> Review -> Accepted Canonical Graph State
-```
-
-Only reviewed and accepted candidates should move into canonical graph state.
-
-## Minimum Embryo Metadata
-
-```json
-{
-  "schema_version": "0.1.0",
-  "embryo_id": "embryo.example",
-  "seed_id": "seed.example",
-  "generated_at": "2026-05-28",
-  "candidate_objects": [],
-  "candidate_relations": [],
-  "uncertain_items": [],
-  "review_questions": [],
-  "stop_conditions_triggered": []
-}
-```
-
-## Review Questions
-
-A useful embryo should help reviewers answer:
-
-- Which candidate objects belong in the graph?
-- Which candidates should be rejected or deferred?
-- Which relations are unsupported?
-- Which evidence is missing?
-- Which stop conditions were triggered?
-- What should be accepted into canonical state?
-
-## Anti-Patterns
-
-- Treating the embryo as accepted graph state.
-- Generating too many candidates for practical review.
-- Hiding uncertain or rejected candidates.
-- Dropping evidence gaps.
-- Using embryo output as runtime context before review.

package/standard/graph-seed.md

@@ -1,122 +0,0 @@
-# Mirai Graph Seed
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-A Graph Seed is the controlled starting package for growing a Mirai Graph model.
-
-Complex systems should not start as large hand-authored graphs. They should
-start from a small seed that defines purpose, source boundaries, growth rules,
-review gates and stop conditions.
-
-## Definition
-
-A Graph Seed is a machine-readable growth contract.
-
-It answers:
-
-- what graph should exist;
-- why it should exist;
-- which profile shapes it;
-- what sources may be used;
-- which object and relation families are allowed;
-- what must be reviewed before canonical write;
-- when growth should stop.
-
-## Growth Flow
-
-```text
-graph seed
--> profile expansion
--> candidate extraction
--> graph embryo
--> review packet
--> canonical accept
--> generated indexes/context/reports
--> readiness score
--> seed evolution
-```
-
-## Minimum Seed Fields
-
-```json
-{
-  "schema_version": "0.1.0",
-  "seed_id": "seed.example",
-  "target_graph_id": "example.graph",
-  "purpose": "Why this graph should exist.",
-  "target_profile": "profile.software_specification",
-  "target_mode": "discovery",
-  "graph_dna": {
-    "purpose": "Parent DNA draft.",
-    "evolution_vector": "How the graph should develop.",
-    "non_negotiable_principles": []
-  },
-  "source_boundaries": {
-    "allowed_sources": [],
-    "excluded_sources": [],
-    "canonical_write_allowed": false
-  },
-  "growth_rules": {
-    "allowed_object_families": [],
-    "allowed_relation_families": [],
-    "max_initial_objects": 20,
-    "depth_mode": "light"
-  },
-  "review_gates": [
-    "human_review_before_canonical_write",
-    "validate_before_generated_context"
-  ],
-  "generated_views": [
-    "seed_preview",
-    "candidate_object_list",
-    "growth_gap_report"
-  ],
-  "stop_conditions": []
-}
-```
-
-## Target Modes
-
-Initial target modes:
-
-- `discovery`: understand a messy domain;
-- `canonical`: prepare reviewed canonical graph state;
-- `pilot`: support measured pilot work;
-- `controlled_runtime`: support bounded runtime use with fallback;
-- `production_runtime`: broad runtime use after repeated evidence.
-
-## Human Control Rule
-
-The user should not need to inspect the full graph first.
-
-The seed should produce controlled views:
-
-- seed summary;
-- candidate objects;
-- candidate relations;
-- evidence gaps;
-- risk view;
-- readiness view;
-- next-action view.
-
-## Stop Conditions
-
-Stop seed expansion when:
-
-- purpose is vague;
-- target profile is missing;
-- source boundaries are unclear;
-- candidate count exceeds growth budget;
-- relation families are invented ad hoc;
-- generated preview cannot explain why objects belong;
-- canonical write is requested before review.
-
-## Anti-Patterns
-
-- Starting with the whole organization as one graph.
-- Letting AI extraction write directly to canonical state.
-- Expanding sources beyond the seed boundary.
-- Treating a seed as the full graph.
-- Ignoring stop conditions because the generated output looks useful.

package/standard/hybrid-source-of-truth.md

@@ -1,91 +0,0 @@
-# Hybrid Source Of Truth
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Mirai Graph can act as the first machine-readable layer for routing, context,
-capability discovery, readiness, gates and evidence. That does not mean the
-graph replaces every original source.
-
-Hybrid Source Of Truth defines how a Mirai Graph implementation can use graph
-state for operational control while keeping domain source material authoritative
-for meaning, judgement and sensitive procedures.
-
-## Core Rule
-
-```text
-graph = routing, context, control, readiness and evidence layer
-raw source = authoritative methodology, judgement and sensitive rules
-```
-
-A generated graph view may select what to read first. It must not silently
-erase the authority of the source that created the meaning.
-
-## Source Classes
-
-A Mirai Graph implementation should classify sources before using them:
-
-- `canonical`: approved source material or canonical graph state;
-- `raw`: original source material that contains authoritative domain meaning;
-- `generated`: derived context, report, dashboard or proposal;
-- `evidence`: material used to support a claim or gate result;
-- `draft`: working material that may be useful but is not authoritative;
-- `deprecated`: material retained only for traceability.
-
-## Authority Boundary
-
-Canonical graph state may contain:
-
-- stable object identifiers;
-- typed relations;
-- readiness state;
-- evidence links;
-- governance gates;
-- adoption status;
-- runtime policy references;
-- generated view references.
-
-Raw sources remain authoritative for:
-
-- domain judgement;
-- long-form procedures;
-- sensitive runtime rules;
-- safety constraints;
-- legal, commercial or production-specific exceptions;
-- source-writing permission.
-
-Generated artifacts remain advisory unless an implementation explicitly accepts
-them through a governance gate.
-
-## Required Safeguards
-
-A Hybrid Source Of Truth implementation should preserve these safeguards:
-
-- generated context is not authorization;
-- a runtime decision is not an executed action;
-- feedback is not a canonical update;
-- profile conformance is not semantic preservation;
-- semantic preservation is not proof of effectiveness;
-- effectiveness is not runtime safety.
-
-## Graph-First Does Not Mean Graph-Only
-
-Graph-first operation is allowed only when the graph is used as the first
-navigation layer for a bounded task. It still requires fallback to raw sources
-when coverage is missing, the task is sensitive, or the runtime policy requires
-original source review.
-
-Graph-only runtime should be treated as unsafe by default.
-
-## Limited Claim
-
-Passing a Hybrid Source Of Truth gate supports this limited claim:
-
-```text
-The Mirai Graph implementation preserves the authority boundary between graph
-state, generated context and raw domain sources for the declared scope.
-```
-
-It does not prove semantic completeness, operational effectiveness or runtime
-safety.