mirai-graph 1.0.0-rc.1

package/docs/adoption/getting-started.md

@@ -0,0 +1,169 @@
+# Getting Started With Mirai Graph
+
+Status: initial adoption guide
+
+## Goal
+
+This guide helps a team create a first Mirai Graph package for a project,
+product, organization or human-AI workflow.
+
+For a shorter role-oriented entry point, start with the
+[1.0 RC Adopter Kit](adopter-kit.md).
+
+## Step 1: Choose The System Boundary
+
+Define what the graph will manage.
+
+Examples:
+
+- one product;
+- one software project;
+- one research program;
+- one organizational process;
+- one AI-assisted workflow.
+
+Avoid starting with the whole organization unless the immediate scope is clear.
+
+Then choose the closest profile:
+
+- software project or package -> `software_specification`;
+- research or cross-functional work -> `project_management`;
+- governed AI worker -> `ai_employee`;
+- organization, department or portfolio governance -> `organization_governance`.
+
+Use [Choose A Mirai Graph Profile](choose-profile.md) for the full profile and
+starter-template map.
+
+## Step 2: Create A Graph Seed
+
+Start with a small seed:
+
+- 3-10 objects;
+- the most important relations;
+- evidence boundaries;
+- one target task;
+- one readiness policy.
+
+Do not try to model everything at once.
+
+## Step 3: Create Package Files
+
+Recommended minimal structure:
+
+```text
+mirai-graph-package.json
+graph/
+  objects.json
+  relations.json
+gates/
+  results.json
+```
+
+Use `examples/minimal-graph/` as a minimal reference or start from one of the
+starter templates in `templates/`.
+
+## Step 4: Define Objects
+
+Create objects for things that need stable identity:
+
+- goals;
+- requirements;
+- features;
+- decisions;
+- risks;
+- tasks;
+- components;
+- evidence;
+- governance gates.
+
+Each object should have:
+
+- `id`;
+- `kind`;
+- `title`;
+- `summary`;
+- `readiness`;
+- `evidence`;
+- `profile`.
+
+## Step 5: Define Relations
+
+Add relations only when the connection changes understanding, execution or
+governance.
+
+Common relation types:
+
+- `depends_on`;
+- `supports`;
+- `blocks`;
+- `implements`;
+- `evidences`;
+- `governs`;
+- `generates`;
+- `related_to`.
+
+## Step 6: Validate The Package
+
+Run:
+
+```bash
+node packages/cli/validate-mirai-graph.js <package-dir>
+```
+
+Example:
+
+```bash
+node packages/cli/validate-mirai-graph.js examples/minimal-graph
+```
+
+For a role-oriented starter workflow, run:
+
+```bash
+node packages/cli/mirai-graph.js choose-profile
+node packages/cli/mirai-graph.js adopter plan developer
+node packages/cli/mirai-graph.js adopter report templates/software-project-starter
+```
+
+## Step 7: Generate A Context Pack
+
+For the first iteration, write a simple manual context pack:
+
+- task;
+- included objects;
+- included relations;
+- evidence;
+- assumptions;
+- omissions;
+- limitations.
+
+Later, automate generation from the canonical graph.
+
+## Step 8: Review Governance
+
+Before using the graph for decisions or action, check:
+
+- What is draft?
+- What is accepted?
+- What is blocked?
+- What evidence is missing?
+- What requires human approval?
+- What cannot be published?
+
+## Step 9: Grow Iteratively
+
+Mirai Graph works best as an iterative model:
+
+```text
+seed -> embryo -> reviewed graph -> context packs -> task results -> graph updates
+```
+
+Keep each growth step reviewable.
+
+## Common Mistakes
+
+- Modeling too much too early.
+- Treating generated context as canonical state.
+- Adding relations without evidence or direction.
+- Publishing private material in examples.
+- Claiming validation before tests exist.
+- Skipping governance gates for action-capable workflows.

package/docs/adoption/mirai-graph-transition.md

@@ -0,0 +1,64 @@
+# Mirai Graph Naming Transition
+
+Status: alpha.9 transition note
+
+Mirai Graph has completed its public naming transition. This document records
+the current naming model and the boundaries for adopters.
+
+The current naming model is:
+
+- `Mirai` is the broader AI direction.
+- `Mirai Graph` is the public standard, model and methodology.
+- `mirai-graph` is the repository, package and primary CLI slug.
+- `EOG` remains a scientific continuity term for earlier research framing.
+
+The strategic goal of the rename is not cosmetic. It separates the future-facing
+Mirai direction from earlier working labels and positions Mirai Graph as the
+public graph standard for governed AI work: AI employees, projects,
+organizations and research systems coordinated through state, evidence, gates,
+feedback and controlled evolution.
+
+## What Changed
+
+- Package name: `mirai-graph`.
+- Primary CLI: `node packages/cli/mirai-graph.js`.
+- Preferred package manifest: `mirai-graph-package.json`.
+- Public docs and examples use Mirai Graph naming.
+
+## Current Command Surfaces
+
+The supported alpha.9 local command surfaces are:
+
+- `node packages/cli/mirai-graph.js`
+- `node packages/cli/mirai_graph.js`
+- `node packages/cli/validate-mirai-graph.js`
+- `mirai-graph-package.json`
+
+The underscore CLI is an alias for local environments that prefer identifier
+style command names. It is not a separate standard.
+
+## Migration Steps
+
+1. Use `mirai-graph-package.json` for package manifests.
+2. Use direct validator calls with
+   `node packages/cli/validate-mirai-graph.js`.
+3. Use unified CLI calls with `node packages/cli/mirai-graph.js`.
+4. Keep generated reports as historical evidence; do not rewrite evidence
+   payloads unless they are regenerated by the current tooling.
+
+## Schema Namespace
+
+Existing schema `$id` values may still use the previous namespace during the
+transition. Mirai Graph will move schema namespaces only after the public domain
+decision is confirmed. Schema `$id` changes should be treated as a compatibility
+event, not as a cosmetic text edit.
+
+## Boundary
+
+The rename does not change the standard semantics:
+
+- generated context is not canonical state;
+- evidence and proposals do not authorize canonical updates;
+- feedback does not automatically change behavior;
+- readiness is not execution;
+- command aliases are not new standards.

package/docs/adoption/profile-conformance-fixtures.md

@@ -0,0 +1,112 @@
+# Profile Conformance Fixtures
+
+Status: initial public guide
+
+## Purpose
+
+Profile conformance fixtures show how Mirai Graph validates that a package follows
+the object kinds and relation types declared by its profile.
+
+They are not scientific proof of real-world usefulness. They are executable
+examples for implementers and regression checks for the public standard.
+
+## Positive Fixtures
+
+Positive fixtures are packages expected to pass validation.
+
+| Fixture | Profile | Purpose |
+| --- | --- | --- |
+| `pilots/independent-implementation-001-conference-planning/` | `project_management` | Small workflow package using goals, tasks, decisions, risks and governance gates. |
+| `pilots/independent-implementation-002-software-specification/` | `software_specification` | Small software package using requirements, features, components, tasks, risks, constraints and decisions. |
+| `pilots/independent-implementation-003-ai-employee-workflow/` | `ai_employee` | Small governed AI employee workflow package using roles, tools, policies, actions, feedback and learning gates. |
+| `pilots/independent-implementation-004-research-program/` | `project_management` | Small research-program governance package using evidence, milestones, publication gates, risks and decisions. |
+| `pilots/independent-implementation-005-organization-governance/` | `organization_governance` | Small organization governance package using mission, strategy, decision rights, controls, metrics, feedback and Kaizen. |
+| `benchmarks/synthetic-context-reduction-v0/` | `software_specification` | Synthetic benchmark package for context-pack generation and semantic review. |
+| `examples/ai-employee-minimal/` | `ai_employee` | Synthetic AI employee package using role, skill, knowledge, tool, policy, action boundary, feedback and learning gate. |
+| `examples/skill-runtime-minimal/` | `skill_runtime` | Synthetic governed skill package using Hybrid SOT, runtime policy, fallback, projection view and federation contract boundaries. |
+| `examples/minimal-graph/` | `core` | Minimal core package shape. |
+
+Stored positive result artifacts:
+
+- `examples/minimal-graph/results/profile-conformance-result.json`;
+- `examples/ai-employee-minimal/results/profile-conformance-result.json`;
+- `examples/skill-runtime-minimal/results/profile-conformance-result.json`;
+- `benchmarks/synthetic-context-reduction-v0/results/profile-conformance-result.json`;
+- `pilots/independent-implementation-001-conference-planning/results/profile-conformance-result.json`;
+- `pilots/independent-implementation-002-software-specification/results/profile-conformance-result.json`;
+- `pilots/independent-implementation-003-ai-employee-workflow/results/profile-conformance-result.json`;
+- `pilots/independent-implementation-004-research-program/results/profile-conformance-result.json`.
+- `pilots/independent-implementation-005-organization-governance/results/profile-conformance-result.json`.
+
+## Negative Fixtures
+
+Negative fixtures are packages expected to fail validation.
+
+| Fixture | Expected failure |
+| --- | --- |
+| `examples/invalid-missing-relation-target/` | Relation target references a missing object. |
+| `examples/invalid-relation-id-mismatch/` | Relation id disagrees with source, type and target fields. |
+| `examples/invalid-profile-object-kind/` | Object kind is not allowed by the package profile. |
+| `examples/invalid-profile-relation-type/` | Relation type is not allowed by the package profile. |
+
+## Commands
+
+Run the full conformance smoke suite:
+
+```bash
+npm run release:check
+```
+
+Run only public pilot validation:
+
+```bash
+npm run validate:pilots
+```
+
+Run positive fixture result checks:
+
+```bash
+npm run validate:profile-results
+```
+
+Run negative fixture checks:
+
+```bash
+npm run test:negative
+```
+
+## Current Validator Scope
+
+The validator currently checks:
+
+- required package, object, relation and gate-result fields;
+- unique object and relation ids;
+- relation source and target existence;
+- relation id consistency with source, type and target;
+- readiness and gate verdict values;
+- profile object-kind conformance;
+- profile relation-type conformance.
+
+## Current Limits
+
+The fixtures do not yet prove:
+
+- semantic completeness;
+- real-world productivity;
+- downstream AI task performance;
+- runtime safety;
+- external validity.
+
+Semantic completeness is reviewed separately through
+`docs/research/semantic-completeness-review-protocol.md`.
+
+## Claim Rule
+
+Passing profile conformance supports this limited claim:
+
+```text
+The package follows the declared Mirai Graph profile shape checked by the current validator.
+```
+
+It does not support claims about correctness, usefulness or completeness of the
+modeled domain.

package/docs/adoption/seed-to-validated-package.md

@@ -0,0 +1,121 @@
+# From Graph Seed To Validated Package
+
+Status: worked tutorial
+
+## Goal
+
+This tutorial shows the basic Mirai Graph adoption path:
+
+```text
+graph seed -> graph embryo preview -> graph package -> validation -> context pack -> readiness score
+```
+
+It uses the synthetic conference planning pilot.
+
+## 1. Validate The Seed
+
+```bash
+node packages/cli/validate-mirai-graph.js seed pilots/independent-implementation-001-conference-planning/graph-seed.json
+```
+
+Expected:
+
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": []
+}
+```
+
+## 2. Generate A Graph Embryo Preview
+
+```bash
+node packages/cli/seed-preview.js pilots/independent-implementation-001-conference-planning/graph-seed.json
+```
+
+The embryo is a reviewable candidate state. It is not canonical graph state.
+
+## 3. Create Package Files
+
+Minimum package shape:
+
+```text
+mirai-graph-package.json
+graph/
+  objects.json
+  relations.json
+gates/
+  results.json
+```
+
+Use the pilot package as an example:
+
+```text
+pilots/independent-implementation-001-conference-planning/
+```
+
+## 4. Validate The Package
+
+```bash
+node packages/cli/validate-mirai-graph.js pilots/independent-implementation-001-conference-planning
+```
+
+Expected:
+
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": []
+}
+```
+
+## 5. Generate A Context Pack
+
+```bash
+node packages/cli/context-pack.js pilots/independent-implementation-001-conference-planning --task-id task.prepare_speaker_schedule
+```
+
+Current release-candidate behavior:
+
+The generator uses token matching and one-hop relation expansion. It remains an
+alpha generator and does not prove semantic completeness.
+
+## 6. Score Readiness
+
+```bash
+node packages/cli/readiness-score.js pilots/independent-implementation-001-conference-planning --target-mode pilot
+```
+
+Interpretation:
+
+Readiness score is a navigation signal, not approval. Synthetic-only evidence
+and missing benchmark evidence cap the score.
+
+## 7. Record Findings
+
+Write a pilot report:
+
+```text
+pilots/<pilot-id>/reports/pilot-report.md
+```
+
+At minimum record:
+
+- domain;
+- research question;
+- validation result;
+- readiness score;
+- what worked;
+- gaps found;
+- supported claims;
+- unsupported claims.
+
+## Common Mistakes
+
+- Treating embryo output as canonical graph state.
+- Skipping public-safety gate results.
+- Creating relations to missing objects.
+- Using readiness score as approval.
+- Claiming practical improvement without a baseline comparison.

package/docs/concept.md

@@ -0,0 +1,109 @@
+# 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.