mirai-graph 1.3.0 → 2.1.0

package/docs/adoption/for-developers.md

@@ -1,210 +0,0 @@
-# Mirai Graph For Developers
-
-Status: 1.0 release-candidate developer guide
-
-## Why A Developer Would Use This
-
-Use Mirai Graph when a repository has important project knowledge spread across
-README files, tickets, docs, code comments, decisions and AI chats.
-
-Mirai Graph does not replace your code, issue tracker or documentation. It adds
-a small graph package that describes:
-
-- what the important project objects are;
-- how features, requirements, risks and decisions connect;
-- what evidence supports a claim;
-- what is blocked or uncertain;
-- what an AI assistant should know before helping with implementation.
-
-The goal is practical: make the project easier to understand, validate and hand
-to an AI assistant without dumping the whole repository into a prompt.
-
-## Common Developer Use Cases
-
-### 1. Project Onboarding
-
-Create a graph package that helps a new developer answer:
-
-- What are the main features?
-- What depends on what?
-- What risks or blockers exist?
-- Which decisions matter?
-- Which evidence or validation exists?
-
-### 2. AI-Assisted Development
-
-Use the graph as structured context for AI:
-
-- relevant features;
-- required constraints;
-- related risks;
-- accepted decisions;
-- evidence and missing evidence;
-- process gates before claiming work is done.
-
-### 3. Requirement Traceability
-
-Connect requirements to implementation objects, decisions and evidence:
-
-```text
-requirement -> feature -> component -> test/evidence -> release gate
-```
-
-This makes it easier to explain why a change exists and what should be checked
-before it is accepted.
-
-### 4. Dependency And Risk Map
-
-Use relations such as `depends_on`, `blocks`, `implements`, `evidences` and
-`governs` to show why a task is not isolated.
-
-### 5. CI Validation
-
-Run validation in CI to make sure graph package structure and profile rules do
-not silently break.
-
-Validation does not prove the project is correct. It checks that the graph
-package remains structurally usable.
-
-## What You Get
-
-A starter software graph usually looks like this:
-
-```text
-graph.json
-graph/
-  objects.json
-  relations.json
-gates/
-  results.json
-```
-
-Example object:
-
-```json
-{
-  "id": "feature.user_notifications",
-  "kind": "feature",
-  "title": "User notifications",
-  "summary": "Notify users when important workflow events happen.",
-  "readiness": "draft",
-  "profile": "software_specification",
-  "evidence": ["docs/product-notifications.md"]
-}
-```
-
-Example relation:
-
-```json
-{
-  "id": "relation.user_notifications.depends_on.event_log",
-  "type": "depends_on",
-  "source": "feature.user_notifications",
-  "target": "feature.event_log",
-  "summary": "Notifications require event records before delivery."
-}
-```
-
-## Quick Start
-
-The intended npm workflow is:
-
-```bash
-npm install -D mirai-graph
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-```
-
-Current release-candidate note: if the npm package is not published yet, use the
-repository checkout path:
-
-```bash
-git clone https://github.com/zabarov/mirai-graph.git
-cd mirai-graph
-npm install
-node packages/cli/mirai-graph.js validate examples/minimal-graph
-```
-
-## What The Commands Mean
-
-### `detect`
-
-Read-only scan. It reports:
-
-- whether a graph package already exists;
-- which profile is recommended;
-- which files are missing;
-- what the next safe action is.
-
-### `bootstrap --mode suggest`
-
-Creates a generated proposal. It does not update canonical graph files.
-
-Use this when you want Mirai Graph to suggest what the project graph could look
-like before committing to a starter package.
-
-### `init`
-
-Creates the starter package files.
-
-For most software projects, start with:
-
-```bash
-npx mirai-graph init . --profile software_specification
-```
-
-### `validate`
-
-Checks package structure, object/relation references, profile rules and known
-semantic guardrails.
-
-## First Useful Graph
-
-Do not try to model the whole system on day one.
-
-Start with:
-
-- 3-5 features;
-- 2-3 requirements;
-- 1-2 risks;
-- 1-2 decisions;
-- evidence links for the most important claims;
-- a few relations that change how the project should be understood.
-
-That is enough to make the graph useful for onboarding and AI context.
-
-## How This Helps AI Work
-
-Without a graph, an AI assistant often receives scattered context:
-
-```text
-README + issue + old chat + partial code + developer note
-```
-
-With Mirai Graph, the assistant can receive a structured map:
-
-```text
-task -> relevant features -> dependencies -> risks -> evidence -> gates
-```
-
-This reduces missing context and makes it easier to detect false progress, such
-as "tests exist" being treated as "work is accepted".
-
-## Boundaries
-
-- Mirai Graph validation is not proof that your software is correct.
-- Generated proposals do not update canonical graph state.
-- Evidence does not authorize release by itself.
-- Feedback does not automatically change the graph.
-- Private data, secrets and customer logs should stay outside public graph
-  packages.
-
-## Next Steps
-
-- Follow [Connect A Project In 15 Minutes](connect-project-15-minutes.md).
-- Read the [CLI Guide](cli.md).
-- Add CI with the GitHub Action starter.
-- Use [Developer Integration Guide](developer-integration-guide.md) when you
-  want to integrate validation into a real repository workflow.

package/docs/adoption/getting-started.md

@@ -1,192 +0,0 @@
-# Getting Started With Mirai Graph
-
-Status: 1.0 release-candidate adoption guide
-
-## Goal
-
-This guide helps a team create a first Mirai Graph package for a project,
-product, organization or human-AI workflow.
-
-For the fastest path from an existing project, use
-[Connect A Project In 15 Minutes](connect-project-15-minutes.md). For a
-developer-focused explanation of what problem Mirai Graph solves, start with
-[Mirai Graph For Developers](for-developers.md). For a shorter role-oriented
-entry point, start with the [1.0 RC Adopter Kit](adopter-kit.md).
-
-## NPM-First Quick Start
-
-From the project you want to connect:
-
-```bash
-npm install -D mirai-graph
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-```
-
-Release-candidate note: `mirai-graph@1.0.0-rc.6` is not published on npm yet.
-Until npm publication is complete, use the repository checkout path and run the
-same commands through `node packages/cli/mirai-graph.js`.
-
-Use `detect` first when you are unsure which profile to use. `detect` is
-read-only. `bootstrap --mode suggest` creates proposal/evidence only. `init`
-creates the starter package after you choose a profile.
-
-## 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
-graph.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
-npx mirai-graph validate <package-dir>
-```
-
-Example:
-
-```bash
-node packages/cli/validate-mirai-graph.js examples/minimal-graph
-```
-
-For a role-oriented starter workflow, run:
-
-```bash
-npx mirai-graph choose-profile
-npx mirai-graph adopter plan developer
-npx mirai-graph 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

@@ -1,67 +0,0 @@
-# Mirai Graph Naming Transition
-
-Status: historical naming 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: `mirai-graph`.
-- Canonical workspace and package manifest: root `graph.json` schema `2.0.0`.
-- `mirai-graph-package.json` and `graph/graph.json` are read-only legacy inputs during the compatibility window.
-- Public docs and examples use Mirai Graph naming.
-
-## Current Command Surfaces
-
-The supported current command surfaces are:
-
-- `npx mirai-graph ...` for adopter projects;
-- `node packages/cli/mirai-graph.js ...` for repository checkout maintenance;
-- `node packages/cli/mirai_graph.js ...` as an underscore alias;
-- `node packages/cli/validate-mirai-graph.js ...` for direct validator calls;
-- `graph.json` plus `graph.lock.json` for immutable external pins
-
-The underscore CLI is an alias for local environments that prefer identifier
-style command names. It is not a separate standard.
-
-## Migration Steps
-
-1. Run `mirai-graph migrate .` for a read-only plan and add `--apply` only after review.
-2. Keep exactly one root `graph.json`; do not write a second manifest into `graph/`.
-3. Use `npx mirai-graph validate .` in adopter projects.
-4. Use direct validator calls from repository checkout only when maintaining
-   Mirai Graph itself.
-5. 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

@@ -1,112 +0,0 @@
-# Profile Conformance Fixtures
-
-Status: 1.0 release-candidate 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

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