mirai-graph 1.3.0 → 2.1.0

package/docs/concept.md

@@ -1,109 +0,0 @@
-# Mirai Graph Concept
-
-Mirai Graph is an evolutionary graph operating model for managing the growth of
-complex systems.
-
-It starts from a practical problem: complex work is usually distributed across
-documents, chats, trackers, code repositories, policies, decisions and human
-memory. As the system grows, context becomes fragmented. AI assistants can help,
-but only when they receive the right working context and can distinguish facts,
-decisions, evidence, uncertainty and permitted actions.
-
-Mirai Graph addresses this by separating:
-
-- canonical graph state;
-- generated context packs;
-- evidence and provenance;
-- readiness and lifecycle state;
-- profiles;
-- governance gates;
-- implementation tooling.
-
-Mirai Graph is also the graph foundation for the broader Mirai direction:
-governed AI systems that do useful work without losing traceability, approval
-boundaries or process discipline.
-
-## Core Idea
-
-A complex system can be represented as an evolving graph where objects,
-relations, evidence, decisions and feedback loops are maintained as structured
-state.
-
-This graph is not only a knowledge map. It is an operating model:
-
-- it helps people and AI systems understand what exists;
-- it shows how parts depend on each other;
-- it records what is known, assumed, ready, blocked or disputed;
-- it generates context for specific tasks;
-- it defines where human approval or governance is required;
-- it supports controlled growth over time.
-
-For AI systems, this means an agent should not be modeled as only a prompt,
-persona or chat history. A governed AI agent should be modeled as graph-backed
-state plus runtime boundaries: roles, skills, knowledge, memory, tools,
-policies, workflows, actions, results, feedback and lessons.
-
-## Key Distinction
-
-Mirai Graph does not treat generated AI context as the source of truth.
-
-The source of truth is the canonical graph state. A generated context pack is a
-task-specific view derived from that state.
-
-This distinction matters because generated context can be useful but temporary,
-partial and task-dependent. The canonical graph is maintained with evidence,
-readiness and governance rules.
-
-## Minimal Flow
-
-```text
-source material -> graph seed -> graph embryo -> canonical graph state
-canonical graph state -> generated context pack -> task execution
-task result -> evidence / event / decision -> graph update gate
-```
-
-For governed work, the fuller loop is:
-
-```text
-intent -> graph state -> context -> launch -> transition -> evidence
--> technology quality feedback -> approval -> controlled update -> Kaizen
-```
-
-## What Mirai Graph Can Model
-
-- requirements;
-- features;
-- initiatives;
-- risks;
-- decisions;
-- evidence;
-- tasks;
-- policies;
-- stakeholders;
-- system components;
-- feedback signals;
-- governance gates;
-- maturity and readiness states.
-
-## Why Growth
-
-The model is called Mirai Graph because the main concern is controlled growth:
-
-- growth of a project from idea to system;
-- growth of product knowledge;
-- growth of an organization;
-- growth of human-AI operating capacity;
-- growth from raw information to governed action.
-
-The model should help a system evolve without losing traceability, context,
-evidence or control.
-
-## Evidence Level
-
-The current model is early. It is supported by internal case-study experience,
-conceptual modeling and synthetic public-safe examples. Broader external
-validity requires reproducible benchmarks, independent review and cross-domain
-replication.
-
-Do not treat Mirai Graph as universally validated until those validation steps
-exist.

package/docs/repository-purpose.md

@@ -1,422 +0,0 @@
-# Mirai Graph Repository Purpose
-
-Status: 1.0 release-candidate alignment brief
-
-## Mission
-
-Mirai Graph is an open research, standardization and developer-adoption
-repository for an evolutionary graph operating model that helps manage the
-growth of complex systems.
-
-The broader purpose is to make Mirai Graph the graph foundation of the Mirai
-direction: governed AI systems that can coordinate people, projects,
-organizations and AI employees through explicit state, evidence, approvals,
-feedback and controlled evolution.
-
-The repository should become the public source of truth for:
-
-- the Mirai Graph / EOG model;
-- the implementation-independent standard;
-- methodological materials;
-- reusable developer methods and libraries;
-- adoption profiles and step-by-step implementation guides;
-- synthetic benchmarks and playground materials;
-- publications, citations and research evidence.
-
-For the current stable release, "source of truth" means public
-standardization and reproducible examples. It does not mean that private
-project graphs, internal workflows or generated context packs are published
-here.
-
-## Strategic Goal
-
-Mirai Graph should become an open, verifiable and practical standard for
-governed AI work across projects, products, organizations, research programs
-and AI-employee systems.
-
-The standard should make this operating loop explicit:
-
-```text
-intent -> graph state -> generated context -> launch gate -> governed work
--> evidence -> technology quality feedback -> approval boundary
--> controlled graph update -> Kaizen learning
-```
-
-The intended end state is not a passive knowledge graph. It is a controlled
-operating substrate where humans and AI systems can:
-
-- understand the current state of a system;
-- decide what is ready, blocked, risky or uncertain;
-- generate task-specific context without replacing canonical truth;
-- execute bounded work only through declared gates;
-- capture results as evidence;
-- route feedback into review, proposal and Kaizen loops;
-- evolve the graph without silent self-modification.
-
-This goal keeps Mirai Graph useful for developers and product teams while also
-leaving a clear research path for EOG-style scientific evaluation.
-
-## Core Positioning
-
-Working public name:
-
-`Mirai Graph`
-
-Scientific continuity:
-
-`Evolutionary Object Graph (EOG)`
-
-Recommended description:
-
-```text
-Mirai Graph is an evolutionary graph operating model for managing the growth of
-complex systems, from projects and products to organizations and human-AI
-systems.
-```
-
-The model is not just a knowledge graph. It combines:
-
-- canonical graph state;
-- generated context packs;
-- typed objects and relations;
-- evidence and provenance;
-- readiness and lifecycle state;
-- profiles;
-- governance gates;
-- feedback loops;
-- implementation and adoption methods.
-- organization-governance coordination patterns.
-
-The stable 1.0 release also makes the operating model executable
-enough to test:
-
-- launch records define bounded work permission;
-- process transitions validate movement through a state machine;
-- negative fixtures prove false transitions fail closed;
-- recovery/resume records prevent chat-only continuation;
-- risk, coordination and source-boundary contracts make governance explicit;
-- Kaizen closure records reusable process learning without automatic canonical
-  update.
-
-## Primary Goals
-
-### 1. Describe The Standard And Model
-
-The repository must define the standard and all required model elements:
-
-- terminology;
-- object model;
-- relation model;
-- lifecycle and readiness model;
-- evidence and provenance rules;
-- generated context-pack rules;
-- profiles and extension points;
-- governance gates;
-- executable process-control contracts;
-- launch records and transition rules;
-- source-boundary and recovery rules;
-- conformance levels;
-- examples and anti-examples.
-
-### 2. Provide Methodological Materials
-
-The repository must explain how to work with the model in practice:
-
-- how to identify system objects;
-- how to form a graph seed;
-- how to grow a graph embryo;
-- how to maintain canonical graph state;
-- how to generate task-specific context packs;
-- how to evaluate readiness;
-- how to govern updates and actions;
-- how to use the model in research, product and organizational settings.
-
-### 3. Provide Reusable Methods And Libraries
-
-The repository should eventually include code that makes the standard easy to
-adopt:
-
-- schemas;
-- validators;
-- CLI tools;
-- context-pack generators;
-- benchmark runners;
-- import/export utilities;
-- reference implementations;
-- adapters for common project structures.
-
-The first code should be small and testable. The standard must not depend on
-one implementation.
-
-Current release-candidate tooling is a reference implementation, not the
-standard itself. It validates public-safe packages and examples so readers can
-inspect the model through executable checks.
-
-### 4. Provide Use Cases, Profiles And Adoption Guides
-
-The repository should include practical profiles and step-by-step guides for:
-
-- project management;
-- product development;
-- software specification;
-- AI-agent knowledge management;
-- organizational governance;
-- research-program management;
-- public-sector or country-scale governance as a future conceptual profile.
-
-Profiles should define how the core model is specialized without changing the
-standard itself.
-
-### 5. Provide Playground And Synthetic Evidence
-
-The repository should include public-safe materials that let users inspect and
-test the model:
-
-- synthetic datasets;
-- benchmark tasks;
-- expected context packs;
-- reproducible metric scripts;
-- playground examples;
-- tutorials;
-- limitations and threats to validity.
-
-Synthetic evidence must be clearly separated from real-world validation.
-
-In the stable release, `playground/` is an index of runnable CLI
-examples. A hosted or interactive playground is future work.
-
-### 6. Link Publications And Research Evidence
-
-The repository should maintain a research trail:
-
-- links to SSRN, preprints and future journal publications;
-- citation metadata;
-- publication-ready abstracts where appropriate;
-- reproducibility notes;
-- research roadmap;
-- validation results;
-- response-to-review notes if public.
-
-It may include publication texts only when licensing and venue policy allow it.
-
-The current scientific layer should be read as a research evidence package and
-program plan, not as peer-reviewed proof of broad effectiveness.
-
-## Intended Audiences
-
-### Researchers
-
-Need:
-
-- clear model definitions;
-- relationship to prior work;
-- reproducible experiments;
-- limitations;
-- citation and publication links.
-
-### Developers
-
-Need:
-
-- schemas;
-- examples;
-- libraries;
-- CLI commands;
-- integration guides;
-- tests and validation checks.
-
-### Product Teams
-
-Need:
-
-- adoption guides;
-- use-case profiles;
-- maturity levels;
-- operating procedures;
-- governance patterns.
-
-### Organizations
-
-Need:
-
-- governance model;
-- roles and responsibilities;
-- evidence and decision flows;
-- lifecycle/readiness rules;
-- implementation roadmap.
-
-## What This Repository Is
-
-- A public standardization workspace.
-- A developer adoption kit.
-- A research evidence and reproducibility hub.
-- A source of public terminology and examples.
-- A bridge between scientific publication and practical implementation.
-
-## What This Repository Is Not
-
-- A dump of the private `science` repository.
-- A publication of raw SIMAI, Larena, customer, employee or internal skill data.
-- A claim that the model is already universally validated.
-- A peer-reviewed journal publication by itself.
-- A single product implementation that defines the whole standard.
-- A place for secrets, private chats, internal access details or raw client work.
-
-## Public-Safe Source Policy
-
-The private `science` repository remains the internal research workspace.
-
-Materials may be copied into the Mirai Graph public repository only when they are:
-
-- public-safe;
-- generalized or synthetic;
-- free of private project names unless explicitly approved;
-- free of secrets and access details;
-- clear about evidence level;
-- licensed or authored for public release.
-
-Before copying from `science`, check:
-
-- no raw SIMAI or Larena source material;
-- no customer or employee data;
-- no internal chat fragments;
-- no private skill implementation details;
-- no overclaiming of external validity;
-- no SSRN preprint presented as peer-reviewed publication.
-
-## Repository Shape
-
-Recommended initial structure:
-
-```text
-README.md
-LICENSE
-LICENSE-DOCS
-CITATION.cff
-ROADMAP.md
-docs/
-  concept.md
-  repository-purpose.md
-  terminology.md
-  standard-roadmap.md
-  methodology/
-  adoption/
-  profiles/
-standard/
-  standard-v0.1.md
-  object-model.md
-  relation-model.md
-  lifecycle-readiness.md
-  evidence-provenance.md
-  governance.md
-  conformance-levels.md
-schemas/
-benchmarks/
-  synthetic-context-reduction-v0/
-examples/
-  synthetic-publishing-platform/
-packages/
-  cli/
-  js/
-  python/
-playground/
-publications/
-```
-
-## Development Phases
-
-### Phase 0: Public Foundation
-
-Done when:
-
-- README exists;
-- purpose brief exists;
-- license strategy exists;
-- citation metadata exists;
-- public-safe concept and standard roadmap exist.
-
-### Phase 1: Standard Draft
-
-Done when:
-
-- terminology exists;
-- object model exists;
-- relation model exists;
-- evidence/provenance rules exist;
-- governance and conformance sections exist;
-- examples and anti-examples exist.
-
-### Phase 2: Method And Adoption Kit
-
-Done when:
-
-- step-by-step adoption guide exists;
-- core profiles exist;
-- implementation checklist exists;
-- tutorial examples exist.
-
-### Phase 3: Reusable Tooling
-
-Done when:
-
-- schemas exist;
-- validator exists;
-- CLI can check a Mirai Graph package;
-- context-pack generation example exists;
-- tests are included.
-
-### Phase 4: Evidence And Playground
-
-Done when:
-
-- synthetic benchmark is public;
-- benchmark runner is reproducible;
-- playground is available;
-- limitations are documented;
-- validation roadmap is public.
-
-### Phase 5: Publication And Ecosystem
-
-Done when:
-
-- publications are linked;
-- citation metadata is maintained;
-- contributor guide exists;
-- roadmap separates research, standard and implementation tracks.
-
-## Open Decisions
-
-- Final public name: `Mirai Graph` is accepted as the working name, but a naming
-  and trademark/domain screen is still needed before strong branding.
-- License split: likely `MIT` for code and `CC BY 4.0` for documentation and
-  standard text, but this needs final confirmation.
-- First implementation language: JavaScript, Python or both.
-- Initial package format and schema format.
-- Whether to host a separate website later.
-- Whether standard text lives under `docs/`, `standard/` or both.
-
-## Immediate Next Artifacts
-
-1. `README.md`
-2. `ROADMAP.md`
-3. `LICENSE`
-4. `LICENSE-DOCS`
-5. `CITATION.cff`
-6. `docs/concept.md`
-7. `docs/terminology.md`
-8. `standard/object-model.md`
-9. `benchmarks/synthetic-context-reduction-v0/`
-
-## Success Criteria
-
-The repository is successful when a new researcher or developer can:
-
-1. Understand what Mirai Graph is.
-2. Understand how it differs from a normal knowledge graph.
-3. Read the standard elements.
-4. Follow an adoption guide.
-5. Run a synthetic benchmark or playground.
-6. Validate a simple Mirai Graph package.
-7. Cite the model and find related publications.
-8. Integrate the model into a real project without access to private SIMAI
-   materials.

package/docs/research/ai-work-field-instrumentation-bridge.md

@@ -1,126 +0,0 @@
-# AI Work Field Instrumentation Bridge
-
-Status: public-safe research bridge
-
-## Purpose
-
-This note connects Mirai Graph instrumentation with the AI Work Field research
-framing.
-
-The bridge is intentionally limited: it explains the public model, synthetic
-artifacts and evidence boundaries. Private pilot repositories, runtime traces,
-customer data, internal policies and unpublished handoff material are not
-published as Mirai Graph evidence.
-
-## Research Framing
-
-AI Work Field treats AI-assisted work as a governed trajectory through explicit
-state, constraints, evidence, feedback and cockpit signals.
-
-The public Mirai Graph standard maps that framing into reusable artifacts:
-
-- graph state: objects, relations, readiness and evidence;
-- process control: launch records, state machines and transition validation;
-- technology adherence: technology quality feedback;
-- instrumentation: development cockpit, feature implementation traceability
-  and multi-source quality feedback;
-- improvement loop: Kaizen findings, proposals and controlled updates.
-
-## Instrumentation Hypothesis
-
-The instrumentation layer supports this hypothesis:
-
-```text
-AI-assisted work becomes more controllable when feature intent, implementation
-evidence, technology adherence, cockpit signals and expert feedback are all
-represented as explicit graph-linked artifacts.
-```
-
-This is a research hypothesis, not a proven general law.
-
-## Public Evidence Levels
-
-### Synthetic Evidence
-
-Synthetic examples demonstrate schema shape, validator behavior and boundary
-rules. They can show that the process is executable and reproducible on toy
-cases.
-
-Current artifacts:
-
-- `examples/instrumentation-layer-minimal`;
-- `schemas/development-cockpit.schema.json`;
-- `schemas/feature-implementation-traceability.schema.json`;
-- `schemas/multi-source-quality-feedback.schema.json`;
-- `npm run validate:instrumentation-layer`.
-
-Synthetic evidence does not prove real productivity, quality improvement,
-production safety or external validity.
-
-### Private Pilot Evidence
-
-Private pilot work can inform the standard by revealing useful abstractions:
-
-- cockpit-style signals for trajectory, coverage, evidence, quality, drift and
-  next action;
-- feature-to-implementation traceability;
-- multi-source feedback from tests, validators, process checks, expert review
-  and Kaizen;
-- separation between readiness, execution, acceptance, release and canonical
-  updates.
-
-Private pilot evidence must be generalized before public transfer. Public Mirai
-Graph receives only the abstract pattern, synthetic examples and schemas.
-
-### Scientific Evidence
-
-Scientific evidence requires stronger protocols:
-
-- preregistered or clearly stated hypotheses;
-- reproducible datasets or public-safe fixtures;
-- metrics and measurement limits;
-- independent review or replication where possible;
-- limitations and threats-to-validity analysis.
-
-The current public repository supports preparation for that work. It does not
-claim peer-reviewed proof.
-
-## Measurement Candidates
-
-Future research can measure:
-
-- context reduction without losing required dependencies;
-- missing dependency rate;
-- unsupported assumption rate;
-- false progress claim rate;
-- evidence coverage;
-- transition violation detection;
-- reviewer correction rate before and after Kaizen;
-- feature implementation traceability coverage.
-
-## Boundary Rules
-
-The bridge preserves these Mirai Graph invariants:
-
-- generated context is not canonical state;
-- evidence is not approval;
-- tests are not acceptance;
-- cockpit metrics are not release permission;
-- feedback and proposals do not authorize canonical updates;
-- Kaizen can propose process changes, but controlled update still requires the
-  relevant approval path.
-
-## Reproducibility Path
-
-For public reproduction, use:
-
-```bash
-npm run validate:instrumentation-layer
-npm run validate:technology-quality-feedback
-npm run validate:process-transition
-npm run validate:baseline-comparison
-npm test
-```
-
-For publication work, pair these commands with the evidence packages and
-limitations documents already maintained under `docs/research/`.