mirai-graph 1.0.0-rc.1

package/docs/research/practice-science-program.md

@@ -0,0 +1,232 @@
+# Mirai Graph Practice And Science Program
+
+Status: working program model
+
+## Purpose
+
+Mirai Graph should develop as both:
+
+- a practical graph methodology used in real AI-assisted work;
+- a scientific research program that produces publishable evidence, standards
+  and reproducible artifacts.
+
+The practical `$graph` skill is the implementation and methodology laboratory.
+The public Mirai Graph repository is the standardization, adoption and research
+artifact layer.
+
+## Operating Role
+
+The maintainer role is not only to write theory.
+
+The role is to act as a research engineer / scientific collaborator who:
+
+- observes practical graph use;
+- detects methodological gaps;
+- improves standard definitions;
+- helps implementation mature;
+- designs measurable experiments;
+- records evidence and limitations;
+- prepares publication-ready artifacts;
+- prevents overclaiming;
+- keeps public materials safe and reusable.
+
+## Three-Layer Model
+
+### 1. Practical Layer
+
+Source:
+
+`$graph` skill and real project usage.
+
+Purpose:
+
+- convert scattered information into object graphs;
+- build graph seeds and graph embryos;
+- generate AI context packs;
+- validate readiness;
+- run practical rollout workflows;
+- discover tooling and methodology gaps.
+
+Output examples:
+
+- object and relation candidates;
+- extraction reports;
+- generated context packs;
+- graph readiness dashboards;
+- benchmark runs;
+- method improvement candidates.
+
+### 2. Public Standard Layer
+
+Source:
+
+This repository.
+
+Purpose:
+
+- define implementation-independent terminology;
+- define schemas and conformance levels;
+- publish public-safe examples;
+- maintain adoption guides;
+- provide validators and reference tooling;
+- separate standard from one private implementation.
+
+Output examples:
+
+- standard sections;
+- schemas;
+- CLI validator;
+- examples;
+- synthetic benchmark packages;
+- profiles;
+- conformance reports.
+
+### 3. Scientific Layer
+
+Source:
+
+Research workspace, public-safe evidence and publications.
+
+Purpose:
+
+- formulate research questions;
+- design experiments;
+- compare baselines;
+- record evidence levels;
+- prepare manuscripts;
+- publish reproducibility packages;
+- handle limitations and reviewer objections.
+
+Output examples:
+
+- experiment protocols;
+- validation results;
+- evidence inventories;
+- literature maps;
+- preprints;
+- journal manuscripts;
+- response-to-review tables.
+
+The current public evidence framing is maintained in
+`docs/research/scientific-evidence-package.md`, with the current evidence index
+in `docs/research/evidence-package-v0.3.md`.
+
+## Core Development Loop
+
+Mirai Graph development should follow this loop:
+
+```text
+practical use
+-> observed gap
+-> classify gap
+-> update implementation, standard or research plan
+-> validate with tests or experiment
+-> publish public-safe artifact
+-> feed lessons back into practice
+```
+
+## Gap Classification
+
+Every significant finding should be classified as:
+
+- `local_gap`: specific to one project or example;
+- `profile_gap`: belongs to a Mirai Graph profile;
+- `standard_gap`: should change the public standard;
+- `tooling_gap`: needs validator, generator, migration or CLI work;
+- `research_gap`: needs protocol, evidence or independent validation;
+- `publication_gap`: needs clearer writing, citations, limitations or data.
+
+## Measurement Discipline
+
+Do not assume graph mode is better. Measure it.
+
+Recommended evaluation cycle:
+
+```text
+freeze benchmark
+-> measure current mode
+-> convert selected scope to graph mode
+-> measure graph mode
+-> compare
+-> optimize
+-> validate
+-> scale
+```
+
+Minimum metrics:
+
+- time to relevant context;
+- context size;
+- context precision;
+- missed dependencies;
+- wrong assumptions;
+- rework cycles;
+- evidence coverage;
+- time to done;
+- manual review overhead.
+
+## Research Artifact Policy
+
+Every important practical improvement should produce at least one durable
+research artifact:
+
+- experiment protocol;
+- benchmark fixture;
+- result note;
+- evidence table;
+- limitation note;
+- standard change proposal;
+- publication note.
+
+If no artifact is produced, the learning remains anecdotal.
+
+## Public Transfer Policy
+
+Not every practical `$graph` detail belongs in the public standard.
+
+Promote only material that is:
+
+- reusable beyond one private project;
+- public-safe;
+- evidence-bounded;
+- implementation-independent or clearly marked as reference tooling;
+- useful for adoption, validation or publication.
+
+Keep private:
+
+- raw project materials;
+- internal chats;
+- secrets;
+- customer or employee data;
+- private skill internals that are not approved for release.
+
+## Immediate Program Priorities
+
+1. Map existing `$graph` capabilities to Mirai Graph public standard sections.
+2. Identify which `$graph` features are standard concepts, profile concepts or
+   implementation details.
+3. Create a public-safe standard gap report.
+4. Add schemas for context packs and profiles.
+5. Create a benchmark protocol that compares text-first and graph-assisted
+   workflows.
+6. Prepare a validation roadmap for future publications.
+
+## Scientific Guardrails
+
+- Do not claim universal validity from internal use.
+- Do not treat synthetic benchmark results as field validation.
+- Do not confuse product usefulness with scientific proof.
+- Do not publish private implementation details without approval.
+- Do not describe a preprint as peer reviewed unless the venue confirms it.
+
+## Working Verdict
+
+Mirai Graph should be developed as a research-engineering program:
+
+```text
+practice-led, evidence-bounded, standard-oriented and publication-aware
+```
+
+The practical `$graph` skill is a source of real operational pressure and
+method gaps. The public Mirai Graph repository turns reusable lessons into a
+standard, tooling and scientific evidence.

package/docs/research/scientific-evidence-package.md

@@ -0,0 +1,154 @@
+# Mirai Graph Scientific Evidence Package
+
+Status: alpha evidence framing
+
+## Purpose
+
+This document defines how public Mirai Graph evidence should be read. It connects
+synthetic benchmarks, public pilots, reproducibility materials and publication
+notes without overclaiming scientific proof.
+
+## Current Research Hypotheses
+
+Mirai Graph is currently evaluated around these hypotheses:
+
+- Graph-structured project state can reduce task-context size while preserving
+  relevant dependencies.
+- Evidence-linked relations can reduce missed dependencies and unsupported
+  assumptions in AI-assisted work.
+- Launch records, process transitions and governance gates can reduce false
+  progress claims such as treating readiness as execution.
+- Recovery, source-boundary and Kaizen records can improve continuation across
+  long-running human-AI workflows.
+
+These are hypotheses and engineering claims under test, not settled scientific
+facts.
+
+## Evidence Levels
+
+### Synthetic Evidence
+
+Synthetic evidence uses public-safe examples and benchmarks.
+
+Current materials:
+
+- `benchmarks/synthetic-context-reduction-v0/`
+- `benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json`
+- `examples/federation-routing-smoke/`
+- `examples/process-transition-minimal/`
+- `examples/implementation-control-cycles/`
+- `examples/instrumentation-layer-minimal/`
+
+Use synthetic evidence to inspect method shape, validation behavior and
+reproducibility. Do not treat it as broad external validity.
+
+### Public Pilot Evidence
+
+Pilot evidence uses public-safe implementation packages and reports.
+
+Current materials:
+
+- `pilots/independent-implementation-001-conference-planning/`
+- `pilots/independent-implementation-002-software-specification/`
+- `pilots/independent-implementation-003-ai-employee-workflow/`
+- `pilots/independent-implementation-004-research-program/`
+- `pilots/independent-implementation-005-organization-governance/`
+
+Use pilot evidence to inspect whether the model can be applied outside the
+minimal examples. Pilot evidence still needs replication and independent
+review.
+
+### Scientific Evidence
+
+Scientific evidence requires explicit protocols, metrics, limitations and
+comparison baselines.
+
+Current supporting materials:
+
+- `docs/research/evidence-package-v0.3.md`
+- `docs/research/evidence-package-v0.2.md`
+- `docs/research/evidence-package-v0.1.md`
+- `docs/research/baseline-comparison-protocol.md`
+- `docs/research/limitations-and-threats.md`
+- `docs/research/practice-science-program.md`
+- `docs/research/ai-work-field-instrumentation-bridge.md`
+- `docs/research/independent-implementation-pilot-plan.md`
+- `docs/research/semantic-completeness-review-protocol.md`
+- `publications/README.md`
+- `publications/preprint-note.md`
+- `publications/preprint-outline.md`
+
+Use `docs/research/evidence-package-v0.3.md` as the current public evidence
+entrypoint. The v0.2 and v0.1 packages remain historical alpha evidence
+snapshots.
+
+## Metrics Under Development
+
+Recommended metrics:
+
+- context size reduction;
+- context precision;
+- missed dependency count;
+- unsupported assumption count;
+- evidence coverage;
+- rework cycles;
+- time to relevant context;
+- time to validated completion;
+- review overhead;
+- false-transition rejection rate.
+
+## Reproducibility Path
+
+Run:
+
+```bash
+npm run benchmark:synthetic
+npm run validate:context-packs
+npm run validate:profile-results
+npm run validate:process-transition
+npm run validate:process-transition-report
+npm run test:process-transition-negative
+npm run validate:instrumentation-layer
+npm run validate:baseline-comparison
+npm run validate:pilots
+npm run validate:templates
+npm run validate:cli-unified
+```
+
+Then inspect:
+
+- benchmark input package;
+- generated or expected context pack;
+- validator output;
+- profile conformance results;
+- limitations recorded in each result.
+
+## Claim Boundaries
+
+Mirai Graph public alpha may claim:
+
+- a public standard draft exists;
+- schemas, validators and examples are runnable;
+- synthetic and pilot evidence are separated;
+- baseline comparisons are public-safe and bounded by explicit limitations;
+- governance controls can be represented and tested in public-safe fixtures.
+- cockpit, traceability and multi-source feedback artifacts can be represented
+  and validated as bounded instrumentation inputs.
+- role-oriented adopter workflow evidence can connect templates, CLI checks and
+  public-safety boundaries into a reproducible first-use path.
+
+Mirai Graph public alpha must not claim:
+
+- peer-reviewed proof of effectiveness;
+- production safety for autonomous execution;
+- universal superiority over document-based workflows;
+- automatic correctness of generated context;
+- canonical update authorization from evidence, feedback or proposals.
+
+## Next Evidence Work
+
+- Add more independent public pilots.
+- Replicate baseline-vs-graph comparison reports across different domains.
+- Publish limitation tables per pilot.
+- Prepare publication-ready reproducibility bundles.
+- Record reviewer objections and response notes when publications exist.

package/docs/research/semantic-completeness-review-protocol.md

@@ -0,0 +1,70 @@
+# Semantic Completeness Review Protocol
+
+Status: initial public protocol
+
+## Purpose
+
+Context reduction is useful only if the reduced context preserves the meaning
+needed for the task.
+
+This protocol reviews whether a generated context pack is semantically complete
+enough for its declared task.
+
+## Research Question
+
+Does the generated context pack preserve the objects, relations, evidence,
+risks and governance constraints needed to perform the task?
+
+## Review Inputs
+
+- task definition;
+- canonical graph package;
+- generated context pack;
+- source corpus or source summary;
+- evidence references;
+- expected output or reviewer rubric.
+
+## Review Rubric
+
+Score each dimension from `0` to `2`:
+
+- `0`: missing or misleading;
+- `1`: partially present;
+- `2`: sufficient for the task.
+
+Dimensions:
+
+1. Task relevance.
+2. Required object coverage.
+3. Required relation coverage.
+4. Evidence preservation.
+5. Risk and blocker visibility.
+6. Governance gate visibility.
+7. Omission transparency.
+8. No private or unsafe leakage.
+
+## Verdicts
+
+- `pass`: sufficient for the task.
+- `pass_with_notes`: usable, but limitations must be recorded.
+- `needs_more_context`: important context is missing.
+- `semantic_regression`: context reduction changed or weakened meaning.
+- `unsafe_context`: context leaks private material or hides safety constraints.
+
+## Output Artifact
+
+Recommended output:
+
+```text
+benchmarks/<benchmark-id>/reviews/semantic-completeness-review.json
+```
+
+## Claim Rule
+
+Passing this review supports a limited claim:
+
+```text
+The generated context pack preserved task-relevant meaning under this review protocol.
+```
+
+It does not prove external validity or universal semantic completeness.

package/docs/terminology.md

@@ -0,0 +1,119 @@
+# Mirai Graph Terminology
+
+Status: initial draft
+
+## Mirai Graph
+
+An evolutionary graph operating model for managing the growth of complex
+systems.
+
+Mirai Graph combines canonical graph state, generated context packs, evidence,
+readiness, profiles and governance gates.
+
+## Evolutionary Object Graph
+
+The scientific continuity term used in earlier research materials. Mirai Graph is
+the public working name for the same model direction.
+
+## Complex System
+
+A system with many interacting parts, changing goals, dependencies, evidence,
+decisions and feedback loops.
+
+Examples include projects, products, organizations, research programs and
+human-AI systems.
+
+## Object
+
+A stable graph entity that represents something the system needs to track.
+
+Examples:
+
+- feature;
+- requirement;
+- decision;
+- component;
+- risk;
+- task;
+- evidence item;
+- governance gate.
+
+## Relation
+
+A typed connection between two objects.
+
+Examples:
+
+- depends on;
+- implements;
+- blocks;
+- supports;
+- contradicts;
+- evidences;
+- governs;
+- supersedes.
+
+## Canonical Graph State
+
+The maintained source-of-truth graph state. It should have stable object
+identity, typed relations, evidence links, lifecycle/readiness fields and
+governance rules.
+
+## Generated Context Pack
+
+A task-specific context package generated from canonical graph state.
+
+It helps a human or AI assistant perform a specific task, but it is not itself
+the canonical source of truth.
+
+## Graph Seed
+
+The smallest useful starting structure for a Mirai Graph model. A seed captures
+the initial objects, relations, evidence boundaries and intended growth path.
+
+## Graph Embryo
+
+An early graph state that has grown beyond a seed but is not yet mature enough
+to be treated as a stable canonical model.
+
+## Evidence
+
+Material that supports, explains or constrains a graph object, relation,
+decision or claim.
+
+Evidence can include documents, source records, experiments, reviews, logs,
+published sources or synthetic examples. Evidence level must be explicit.
+
+## Readiness
+
+A maturity state that indicates whether an object, relation, decision, context
+pack or standard section is draft, review-ready, accepted, blocked, deprecated
+or otherwise constrained.
+
+## Profile
+
+A domain-specific adaptation of the core Mirai Graph model.
+
+Profiles may define additional object kinds, relation types, readiness rules,
+governance gates and examples without changing the core standard.
+
+## Governance Gate
+
+A rule or checkpoint that controls whether a proposed update, claim, generated
+context pack or action may proceed.
+
+Governance gates separate:
+
+- suggestion from decision;
+- generated context from canonical state;
+- evidence from claim;
+- planning from action;
+- private material from public release.
+
+## Conformance Level
+
+A declared level showing how completely an implementation follows the Mirai Graph
+standard.
+
+Conformance levels should be testable with schemas, examples, fixtures and
+validation rules.

package/docs/transfer/ai-employee-profile-proposal.md

@@ -0,0 +1,119 @@
+# AI Employee Profile Proposal
+
+Status: alpha proposal
+
+## Purpose
+
+This proposal defines the public Mirai Graph direction for modeling an
+AI employee as a governed runtime over an evolutionary graph.
+
+The goal is to support systems such as Larena/AI without turning Mirai Graph
+into a single AI-agent framework or publishing private implementation details.
+
+## Core Thesis
+
+```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.
+```
+
+## Why A Separate Profile
+
+The existing profiles model projects and software specifications. An
+AI-employee system needs additional first-class concepts:
+
+- roles and departments;
+- skills and specializations;
+- knowledge and memory;
+- tools and capabilities;
+- workflows and automation rules;
+- policies and approval gates;
+- actions, results, feedback and lessons;
+- federation endpoints for multi-employee or multi-service systems.
+
+These concepts should not bloat the core standard. They belong in a profile
+that specializes Mirai Graph for agentic work while preserving the core
+governance model.
+
+## Public Scope
+
+The public standard may define:
+
+- graph object kinds for AI-employee modeling;
+- relation types for skill, tool, policy and delegation structure;
+- canonical state versus runtime/event boundaries;
+- feedback learning gates;
+- synthetic fixtures;
+- validation rules;
+- adoption guidance.
+
+The public standard must not define:
+
+- private Larena package internals;
+- SIMAI customer or employee data;
+- secret handling details beyond public-safe policy boundaries;
+- one mandatory LLM provider;
+- one mandatory runtime or queue implementation;
+- uncontrolled self-modifying behavior.
+
+## Larena/AI Boundary
+
+Mirai Graph should define the portable model. Larena/AI may implement runtime
+execution, UI, storage, queues, tools, permissions, audit logs and package
+integration.
+
+Portable Mirai Graph layer:
+
+- AI employee graph model;
+- object and relation semantics;
+- policy gates;
+- feedback learning lifecycle;
+- profile conformance fixtures.
+
+Larena/AI runtime layer:
+
+- authentication and authorization;
+- tool adapters;
+- execution queues;
+- event logs;
+- UI screens;
+- deployment topology;
+- provider-specific integration.
+
+## Minimal Alpha Scope
+
+The first public alpha should include:
+
+- `profiles/ai-employee/profile.json`;
+- `profiles/ai-employee/README.md`;
+- `standard/graph-as-ai-brain.md`;
+- `standard/action-runtime-boundary.md`;
+- `standard/feedback-learning-gate.md`;
+- `docs/adoption/ai-employee-graph.md`;
+- `examples/ai-employee-minimal/`;
+- validation through `npm run release:check`.
+
+## Safety Principles
+
+1. Feedback does not mutate canonical graph state directly.
+2. Generated context does not become authorization.
+3. Runtime decisions do not equal executed actions.
+4. Executed actions need audited results.
+5. High-risk actions require explicit policy and approval gates.
+6. Learning requires proposal, replay or evaluation, approval and canonical
+   update.
+7. Federation endpoints need compatibility and trust boundaries.
+
+## Claim Rule
+
+This proposal supports only this claim:
+
+```text
+Mirai Graph can model the public structure of an AI employee as a governed graph
+profile with explicit runtime, action and learning boundaries.
+```
+
+It does not prove that any runtime implementation is safe, autonomous or
+effective.