mirai-graph 1.3.0 → 2.1.0

package/CITATION.cff

@@ -1,21 +0,0 @@
-cff-version: 1.2.0
-title: "Mirai Graph"
-message: "If you use Mirai Graph in research or software, please cite this repository."
-type: software
-authors:
-  - family-names: "Zabarov"
-    given-names: "Rim"
-    orcid: "https://orcid.org/0009-0004-8605-5594"
-abstract: "Mirai Graph is an evolutionary graph operating model for managing the growth of complex systems."
-repository-code: "https://github.com/zabarov/mirai-graph"
-license: "MIT"
-keywords:
-  - graph operating model
-  - knowledge graph
-  - AI-assisted work
-  - governance
-  - complex systems
-  - context engineering
-  - systems engineering
-version: "1.2.0"
-date-released: "2026-08-27"

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Rim Zabarov
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/LICENSE-DOCS

@@ -1,26 +0,0 @@
-Creative Commons Attribution 4.0 International Public License
-
-Documentation, standard text, examples and research materials in this
-repository are licensed under the Creative Commons Attribution 4.0
-International License, unless a file states otherwise.
-
-License URL:
-
-https://creativecommons.org/licenses/by/4.0/
-
-You are free to:
-
-- Share: copy and redistribute the material in any medium or format.
-- Adapt: remix, transform and build upon the material for any purpose, even
-  commercially.
-
-Under the following terms:
-
-- Attribution: you must give appropriate credit, provide a link to the license
-  and indicate if changes were made. You may do so in any reasonable manner,
-  but not in any way that suggests the licensor endorses you or your use.
-
-No additional restrictions:
-
-You may not apply legal terms or technological measures that legally restrict
-others from doing anything the license permits.

package/README.md

@@ -1,351 +0,0 @@
-# Mirai Graph
-
-Make your project understandable to humans and AI.
-
-Mirai Graph turns scattered project knowledge into a structured graph of
-features, requirements, dependencies, risks, decisions, evidence and process
-gates.
-
-Use it when a software project has useful knowledge spread across README files,
-docs, issues, chats, code comments and AI prompts, and you need a small
-machine-readable map that developers and AI assistants can validate and reuse.
-
-Status: stable public `1.3.0` release.
-
-## What Problem Does It Solve?
-
-- New developers need too much time to understand the project.
-- AI assistants miss important constraints because context is scattered.
-- Feature dependencies live in people's heads or old tickets.
-- Requirements, implementation decisions and evidence are hard to trace.
-- Work is marked "done" before the process, tests, review or evidence are clear.
-- Project knowledge improves in chats but does not become reusable structure.
-- AI-assisted work produces results without a durable trace of why a path was
-  selected or blocked.
-
-Mirai Graph gives the project a reviewable graph package: objects, relations and
-gates that describe what exists, how it connects, what is blocked, what is
-evidenced and what needs approval.
-
-## What Can A Developer Do With It?
-
-Start with a normal repository and use Mirai Graph to:
-
-- detect whether the project already has a graph package;
-- generate a bootstrap proposal without changing canonical graph files;
-- create a starter graph for features, requirements, risks and decisions;
-- validate the graph locally or in CI;
-- give AI assistants a cleaner project map instead of dumping full docs into a
-  prompt;
-- grow the graph later into process control, AI employee workflows or
-  organization governance.
-
-## Current Installation Status
-
-The repository provides the stable `mirai-graph@1.3.0` package. To verify a
-repository checkout directly, use:
-
-```bash
-git clone https://github.com/zabarov/mirai-graph.git
-cd mirai-graph
-npm install
-npm run release:check
-```
-
-External projects use:
-
-```bash
-npm install -D mirai-graph
-```
-
-## Connect A Project In 10 Minutes
-
-From the project you want to connect, the intended workflow is:
-
-```bash
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-npx mirai-graph migrate .
-```
-
-What each command does:
-
-- `detect` is read-only and reports what kind of project you have.
-- `bootstrap --mode suggest` creates proposal/evidence only.
-- `init` creates starter graph files after you choose a profile.
-- `validate` checks the graph package structure and profile rules.
-- `migrate` shows a read-only plan; add `--apply` only after reviewing it.
-
-If you are using a repository checkout before npm publication, run the same
-commands through `node packages/cli/mirai-graph.js` from this repository.
-
-## Project Technology
-
-Project Technology is the executable part of Mirai Graph. It gives ordinary
-projects, skills, platforms and federations one safe way to build task context,
-bind an accepted target and verify that work still follows it.
-
-Enable it in the existing root manifest:
-
-```json
-{
-  "extensions": {
-    "mirai.project_technology": {
-      "contract_version": "1.0.0",
-      "enabled": true,
-      "context_policy": "task_scoped",
-      "source_boundary": "hybrid_sot",
-      "continuity_policy": "task_boundary"
-    }
-  }
-}
-```
-
-Read-only operations never need `--apply`:
-
-```bash
-mirai-graph technology explain .
-mirai-graph technology status .
-mirai-graph technology context . --task "implement the approved feature"
-mirai-graph technology verify . --significant-work
-```
-
-For deeper graphs, the same `context` operation supports four read-only phases:
-
-```bash
-mirai-graph technology context . --phase discover --task "implement the approved feature"
-mirai-graph technology context . --phase expand --input receipt.json --select capability.delivery
-mirai-graph technology context . --phase compile --input receipt.json --selection selection.json
-mirai-graph technology context . --phase verify --packet context-pack.json --evidence usage-evidence.json
-```
-
-`discover` returns a bounded top-level choice. `expand` follows only selected
-branches. `compile` adds every required process, constraint and validator, and
-returns an immutable context pack only when the selection is complete.
-`verify` proves that required sources influenced a decision and a checked
-outcome; merely loading a document is not enough.
-
-The programmatic API exposes the same operations as `discoverContext`,
-`expandContext`, `compileContext` and `verifyContext`. Mirai Graph does not call
-or depend on a particular AI model.
-
-Verified project experience can be saved without storing a chat transcript:
-
-```bash
-mirai-graph technology sync . --boundary task_complete --evidence continuity-evidence.json
-mirai-graph technology sync . --boundary task_complete --evidence continuity-evidence.json --apply
-```
-
-Accepted facts and reusable cases live in `graph/specs`; mutable receipts and
-rollback data stay host-local. The same contract works in Git repositories and
-ordinary shared folders.
-
-Project Technology can also preserve immutable releases of file bundles:
-
-```bash
-mirai-graph technology artifact inspect . --input incoming.zip
-mirai-graph technology artifact release . --input incoming.zip --matter-id agreement-main --direction inbound
-mirai-graph technology artifact release . --input incoming.zip --matter-id agreement-main --direction inbound --apply
-mirai-graph technology artifact compare . --matter-id agreement-main --base-release 20260828-01 --target-release 20260828-02
-mirai-graph technology artifact verify . --matter-id agreement-main --release-id 20260828-02
-```
-
-The protected files remain outside graph data. The graph keeps only safe
-identity, lineage, state, references and checksums. Mirai Graph performs
-technical integrity checks; a domain owner decides what a version means.
-
-Changing operations return a preview unless `--apply` is explicit. See
-[Project Technology](standard/project-technology.md) for provider/consumer
-binding, local state and safety boundaries.
-
-## What Files Will Be Created?
-
-For a typical software project, `init` creates:
-
-```text
-graph.json
-graph/
-  objects.json      # features, requirements, risks, decisions, evidence
-  relations.json    # depends_on, implements, blocks, evidences, governs
-gates/
-  results.json      # validation and readiness checks
-```
-
-`bootstrap --mode suggest` creates proposal/evidence separately:
-
-```text
-mirai-graph/
-  bootstrap-proposal/
-    bootstrap-proposal.json
-```
-
-Generated proposals do not update canonical graph state by themselves.
-
-For the guided path, use
-[Connect A Project In 15 Minutes](docs/adoption/connect-project-15-minutes.md)
-or the developer-focused guide
-[Mirai Graph For Developers](docs/adoption/for-developers.md).
-
-## What Should I Read First?
-
-| If you are... | Start here | Then read |
-| --- | --- | --- |
-| Trying Mirai Graph in a project | [Connect A Project In 15 Minutes](docs/adoption/connect-project-15-minutes.md) | [Mirai Graph For Developers](docs/adoption/for-developers.md), [CLI](docs/adoption/cli.md) |
-| A developer integrating validation | [Mirai Graph For Developers](docs/adoption/for-developers.md) | [Developer Integration Guide](docs/adoption/developer-integration-guide.md), [Test Suite](standard/test-suite.md) |
-| A researcher evaluating the model | [Scientific Evidence Package](docs/research/scientific-evidence-package.md) | [Practice And Science Program](docs/research/practice-science-program.md), [Publications](publications/README.md) |
-| Building an AI employee | [AI Employee Graph Adoption](docs/adoption/ai-employee-graph.md) | [Character Layer Adoption](docs/adoption/character-layer.md), [Graph As AI Brain](standard/graph-as-ai-brain.md) |
-| Managing an organization or program | [Organization Governance](standard/organization-governance.md) | [Project Management Profile](profiles/project-management/README.md), [Process Control Contract](standard/process-control-contract.md) |
-| Looking for the full map | [Documentation Map](docs/README.md) | [Roadmap](ROADMAP.md), [Release Process](releases/README.md) |
-
-## How It Helps AI Assistants
-
-LLMs are useful, but they depend on the context they receive. If the project
-context is incomplete, the assistant can miss constraints, invent assumptions or
-ignore the team's working process.
-
-Mirai Graph gives AI assistants structured context:
-
-- stable objects instead of loose paragraphs;
-- explicit dependency and evidence links;
-- readiness and uncertainty;
-- process gates that separate suggestion, approval and action;
-- technology-quality feedback when work did not follow the declared process.
-
-In this framing, an AI employee is not just a prompt. It is a governed process:
-context, tools, policies, actions, results, feedback and learning are connected
-through explicit state and approval boundaries.
-
-## Repository Map
-
-```text
-docs/          Concept, terminology, adoption and research guides.
-standard/      Implementation-independent standard sections.
-schemas/       Machine-readable schemas.
-examples/      Public-safe examples and anti-examples.
-templates/     Starter graph packages.
-packages/      Reference CLI and validators.
-playground/    Deterministic local demo report.
-profiles/      Domain profiles.
-pilots/        Public-safe pilot packages and reports.
-publications/  Citation notes and publication materials.
-releases/      Release notes and release process.
-```
-
-## Core Standard Areas
-
-- [Object Model](standard/object-model.md)
-- [Relation Model](standard/relation-model.md)
-- [Lifecycle Readiness](standard/lifecycle-readiness.md)
-- [Evidence Provenance](standard/evidence-provenance.md)
-- [Context Pack Generation](standard/context-pack-generation.md)
-- [Governance](standard/governance.md)
-- [Hybrid Source Of Truth](standard/hybrid-source-of-truth.md)
-- [Profile Boundaries](standard/profile-boundaries.md)
-- [Implementation Control](standard/implementation-control.md)
-- [Process Control Contract](standard/process-control-contract.md)
-- [Technology Quality Feedback](standard/technology-quality-feedback.md)
-- [Dynamic Episode Layer](standard/dynamic-episode-layer.md)
-- [Semantic Intent Resolution](standard/semantic-intent-resolution.md)
-- [Goal Vector Quality Control](standard/goal-vector-quality-control.md)
-- [Character Layer Profile](profiles/character-layer/README.md)
-- [Organization Governance](standard/organization-governance.md)
-
-Additional standard sections, profiles, examples and research materials are
-listed in the [Documentation Map](docs/README.md).
-
-## Profiles
-
-Current release-candidate profiles:
-
-- [Software Specification](profiles/software-specification/README.md)
-- [Project Management](profiles/project-management/README.md)
-- [AI Employee](profiles/ai-employee/README.md)
-- [Character Layer](profiles/character-layer/README.md)
-- [Skill Runtime](profiles/skill-runtime/README.md)
-- [Implementation Control](profiles/implementation-control/README.md)
-- [Organization Governance](profiles/organization-governance/README.md)
-
-Proposal/experimental profile:
-
-- [Societal Governance](profiles/societal-governance/README.md)
-
-Proposal/experimental standard layer:
-
-- [Dynamic Episode Layer](standard/dynamic-episode-layer.md)
-- [Episode Trace](standard/episode-trace.md)
-- [Dynamic Layer For AI-Assisted Code Generation](standard/dynamic-layer-code-generation.md)
-
-## Validate And Explore
-
-Common commands:
-
-```bash
-npx mirai-graph validate .
-npx mirai-graph report validation .
-npx mirai-graph report dynamic-episode examples/dynamic-episode-minimal/results/dynamic-episode-trace.json
-npx mirai-graph choose-profile
-npx mirai-graph report playground
-```
-
-Repository checkout checks:
-
-```bash
-npm test
-npm run release:check
-```
-
-For the full command surface, see [Mirai Graph CLI](docs/adoption/cli.md) and
-[Test Suite](standard/test-suite.md).
-
-## Evidence Boundary
-
-Mirai Graph validation checks graph package structure, profile rules, process
-artifacts and public-safe examples. It does not prove that a project is correct,
-scientifically validated, production-ready or authorized for release.
-
-Generated context, evidence, feedback, cockpit metrics and proposals do not
-authorize canonical updates by themselves. Controlled updates require explicit
-governance gates.
-
-Mirai Graph also does not store bulk source content as canonical graph state.
-Documents, code, CMS records, tickets and databases remain source systems. The
-graph stores governable meaning: object ids, relations, summaries, source refs,
-evidence refs, owners, readiness, gates, decisions, episode metadata and Kaizen
-routes. See [Profile Boundaries](standard/profile-boundaries.md).
-
-## Release Candidate
-
-The stable 1.0 release consolidates the validator-backed public standard
-across the core model, profiles, executable process control, instrumentation,
-Character Layer, adopter kit and evidence boundaries.
-
-`1.0.0-rc.6` specifically presents the anti-drift / quality-control contour as
-one coherent review surface:
-
-```text
-semantic intent
--> process and technology control
--> dynamic episode trace
--> goal-vector reverse audit
--> technology quality feedback
--> Kaizen / replay / regression candidate
-```
-
-See [v1.0.0-rc.6](releases/1.0.0-rc.6.md) and the
-[Release Process](releases/README.md).
-
-## What This Repository Is Not
-
-This repository is not a dump of private research, company or client material.
-Private project data, internal chats, internal skill sources, secrets and raw
-customer or employee data do not belong here.
-
-Synthetic examples and benchmarks are marked as synthetic. They support method
-inspection and reproducibility, not broad external validity claims.
-
-## License
-
-- Code is licensed under the MIT License. See [LICENSE](LICENSE).
-- Documentation is licensed separately. See [LICENSE-DOCS](LICENSE-DOCS).

package/ROADMAP.md

@@ -1,241 +0,0 @@
-# Mirai Graph Roadmap
-
-Status: stable 1.1 roadmap
-
-## Phase 0: Public Foundation
-
-Goal: make the repository understandable, safe to open and ready for structured
-growth.
-
-1.0 RC status: implemented.
-
-Done when:
-
-- README exists;
-- repository purpose is documented;
-- license strategy is explicit;
-- citation metadata exists;
-- initial concept and terminology exist;
-- no private source material is present.
-
-Initial artifacts:
-
-- `README.md`
-- `docs/repository-purpose.md`
-- `docs/concept.md`
-- `docs/terminology.md`
-- `ROADMAP.md`
-- `LICENSE`
-- `LICENSE-DOCS`
-- `CITATION.cff`
-
-## Phase 1: Standard Draft
-
-Goal: define the implementation-independent Mirai Graph standard.
-
-1.0 RC status: implemented with notes. The repository now contains the core
-object/relation/readiness/evidence/governance standard plus validator-backed
-sections for graph seed, hybrid source of truth, profiles, implementation
-control, routing control, source boundaries, recovery, risk, process control,
-instrumentation and Character Layer.
-
-Planned artifacts:
-
-- `standard/standard-v0.1.md`
-- `standard/object-model.md`
-- `standard/relation-model.md`
-- `standard/lifecycle-readiness.md`
-- `standard/evidence-provenance.md`
-- `standard/context-pack-generation.md`
-- `standard/governance.md`
-- `standard/profiles.md`
-- `standard/conformance-levels.md`
-- `standard/test-suite.md`
-
-Additional 1.0 RC artifacts now present:
-
-- graph seed and graph embryo;
-- hybrid source of truth;
-- profile boundaries and the extension-before-profile rule;
-- graph-as-AI-brain;
-- action/runtime boundary;
-- implementation-control cycles;
-- launch record;
-- work state machine;
-- process-control contract;
-- technology quality feedback;
-- semantic intent resolution;
-- goal vector quality control;
-- recovery/resume;
-- risk-control matrix;
-- multi-agent coordination;
-- source-boundary contract;
-- route explanation, fixtures, regression and federation health.
-- development cockpit, feature implementation traceability and multi-source
-  quality feedback;
-- Character Layer profile, starter pack, integration evidence, portability
-  evidence shape and 1.0 readiness artifact.
-- proposal/experimental Dynamic Episode Layer, episode trace schema and
-  synthetic code-generation trace example;
-- `1.0.0-rc.6` anti-drift / quality-control contour that connects semantic
-  intent, process control, dynamic episode tracing, goal-vector reverse audit,
-  technology quality feedback and Kaizen/replay follow-up.
-
-Readiness target:
-
-`1_0_release_candidate_ready_with_notes` for public review and implementation
-pilots.
-
-## Phase 2: Method And Adoption Kit
-
-Goal: help teams use Mirai Graph in real work.
-
-1.0 RC status: implemented with notes. The current repository includes
-npm-first self-service onboarding, getting started material, profile
-conformance fixtures, AI employee adoption, seed to validated package tutorial,
-implementation-control examples, managed-project examples, Character Layer
-adoption, starter templates and public-safe transfer notes.
-
-Planned artifacts:
-
-- adoption guide;
-- project profile;
-- product profile;
-- software-specification profile;
-- organization-governance profile;
-- human-AI system profile;
-- implementation checklist;
-- examples and anti-examples.
-
-Post-1.0 gaps:
-
-- final npm publication and GitHub Release execution after release-state
-  approval;
-- import/export helpers for starter packages;
-- stronger non-software adoption recipes;
-- external adopter feedback from independent pilots.
-- sanitized pilot/replay evidence for the anti-drift contour before claiming
-  real-world drift reduction.
-
-Implemented adopter-workflow focus:
-
-- profile-selection guide;
-- starter-template happy path;
-- human-readable validation reports for adopter workflows;
-- packaged adopter command sequence;
-- organization-governance adoption report.
-- self-service onboarding with `detect`, `bootstrap` and `init`;
-- 15-minute project connection tutorial;
-- GitHub Action starter for validation.
-
-Initial implementation:
-
-- `docs/adoption/choose-profile.md`;
-- `mirai-graph choose-profile`;
-- `mirai-graph adopter plan <role-or-profile>`;
-- `mirai-graph adopter report <template-dir>`;
-- `validate:adopter-workflow`.
-
-## Phase 3: Reusable Tooling
-
-Goal: make adoption practical for developers.
-
-1.0 RC status: implemented with notes. The CLI validates packages, profiles,
-context packs, graph seeds, implementation-control cycles, launch records,
-process transitions, process-transition decision reports, process-control
-contracts, technology quality feedback reports, DNA alignment, work state,
-recovery, risk, coordination, source boundaries, routing-control examples and
-baseline-comparison artifacts, instrumentation artifacts and Character Layer
-readiness.
-
-Planned artifacts:
-
-- JSON schemas;
-- validator;
-- CLI package;
-- reference context-pack generator;
-- import/export helpers;
-- test fixtures.
-
-Post-1.0 gaps:
-
-- publish the prepared CLI package after release-state approval;
-- add import/export helpers;
-- extend human-readable reports beyond process-transition and instrumentation
-  checks;
-- add process-control explanation output and richer report formatting.
-- add adoption recipes for technology quality feedback in non-software
-  workflows.
-- evolve dynamic episode traces from synthetic validation to replay/regression
-  support for internal pilots.
-- add optional validator/report warnings for profile overlap and bulk-content
-  drift.
-
-Current tooling target:
-
-```text
-choose profile -> starter template -> validate -> report -> launch/evidence/kaizen
-```
-
-The standard must remain implementation-independent. Tooling validates and
-demonstrates the standard; it does not replace the standard.
-
-## Phase 4: Evidence And Playground
-
-Goal: provide reproducible public-safe demonstrations.
-
-1.0 RC status: implemented with notes. Synthetic benchmark, baseline-comparison
-artifact, pilot packages, profile conformance results and runnable CLI examples
-exist. The playground is a deterministic local report package rather than a
-hosted interactive app.
-
-Planned artifacts:
-
-- synthetic context-reduction benchmark;
-- benchmark runner;
-- playground;
-- semantic-completeness review protocol;
-- limitations and threats-to-validity notes.
-
-Post-1.0 gaps:
-
-- separate synthetic evidence, pilot evidence and scientific claims more
-  visibly;
-- connect instrumentation reports to reproducibility packages and pilot
-  protocols without exposing private runtime traces;
-- add dynamic episode trace datasets for public-safe code-generation drift
-  experiments;
-- add more independent implementation pilots;
-- explore an interactive playground after CLI-first reports stabilize.
-
-Synthetic materials must remain clearly separated from real-world validation.
-
-## Phase 5: Publication And Ecosystem
-
-Goal: connect the repository to research publications and external adoption.
-
-1.0 RC status: early. Citation metadata, publication notes and evidence package
-v0.3 exist, but the project still needs public publication records, stronger
-reviewer protocols and external adoption evidence before making broad
-scientific claims.
-
-Planned artifacts:
-
-- publication index;
-- citation notes;
-- reproducibility records;
-- contributor guide;
-- release process;
-- public examples from approved external adopters.
-
-## Near-Term Work After 1.1
-
-1. Validate sequential context traversal in independent adopter projects and
-   collect public-safe compatibility evidence.
-2. Continue adopter workflow with richer reports and domain-neutral recipes.
-3. Add external public-safe pilots maintained outside the original Mirai Graph
-   authoring contour.
-4. Collect real multi-model replay evidence before stronger effectiveness or
-   portability claims.
-5. Keep the deterministic CLI and public contracts stable while improving
-   ranking as a replaceable client-side concern.