mirai-graph 1.4.0 → 2.1.0

package/docs/research/baseline-comparison-protocol.md

@@ -1,79 +0,0 @@
-# Mirai Graph Baseline Comparison Protocol
-
-Status: 1.0 release-candidate protocol
-
-## Purpose
-
-This protocol describes how to compare a document/chat/task-tracker workflow
-against a Mirai Graph-assisted workflow without overclaiming.
-
-## Comparison Setup
-
-Use the same task, source materials and reviewer criteria for both modes.
-
-Mode A:
-
-```text
-baseline documents/chats/task notes
-```
-
-Mode B:
-
-```text
-Mirai Graph package -> context pack -> governed process control
-```
-
-## Required Inputs
-
-- task statement;
-- source materials;
-- expected dependency list;
-- expected evidence list;
-- reviewer acceptance criteria;
-- timebox;
-- allowed tools;
-- recording template.
-
-## Measurements
-
-Record:
-
-- context size;
-- selected context precision;
-- missed dependencies;
-- unsupported assumptions;
-- evidence coverage;
-- false progress claims;
-- rework cycles;
-- time to relevant context;
-- time to validated completion;
-- review overhead.
-
-## Result Template
-
-```text
-task_id:
-baseline_context_units:
-mirai_graph_context_units:
-missed_dependencies_baseline:
-missed_dependencies_mirai_graph:
-unsupported_assumptions_baseline:
-unsupported_assumptions_mirai_graph:
-evidence_coverage_baseline:
-evidence_coverage_mirai_graph:
-reviewer_notes:
-limitations:
-verdict:
-```
-
-## Acceptance Rule
-
-A Mirai Graph result is stronger only when it improves at least one target metric
-without making critical safety, evidence or semantic-completeness metrics worse.
-
-## Boundaries
-
-- One task does not prove broad effectiveness.
-- A smaller context is not better if important dependencies are omitted.
-- Passing validators do not prove semantic completeness.
-- Human review remains required for scientific claims.

package/docs/research/evidence-package-v0.1.md

@@ -1,99 +0,0 @@
-# Mirai Graph Evidence Package v0.1
-
-Status: historical alpha research package
-
-Superseded by: [Evidence Package v0.2](evidence-package-v0.2.md) as the current
-public evidence entrypoint. This document remains a historical v0.1 snapshot.
-
-## Purpose
-
-This package defines the current public evidence base for Mirai Graph v0.1 alpha.
-It is designed for research review, publication preparation and reproducibility
-checks.
-
-It does not claim peer-reviewed proof of effectiveness.
-
-## Research Questions
-
-1. Can graph-structured project state reduce task-context size while preserving
-   relevant dependencies?
-2. Can evidence-linked relations reduce unsupported assumptions in
-   AI-assisted work?
-3. Can launch records and process transitions reduce false progress claims?
-4. Can recovery, source-boundary and Kaizen records improve continuation across
-   long-running workflows?
-
-## Evidence Inventory
-
-| Evidence type | Public artifact | Current role |
-|---|---|---|
-| Synthetic benchmark | `benchmarks/synthetic-context-reduction-v0/` | Reproducible context-reduction demonstration |
-| Context-pack validation | `benchmarks/synthetic-context-reduction-v0/results/context-pack.json` | Expected generated context example |
-| Baseline comparison result | `benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json` | Synthetic baseline-vs-Mirai Graph metric comparison |
-| Routing-control fixture | `examples/federation-routing-smoke/` | Explainable routing and regression shape |
-| Process-transition fixture | `examples/process-transition-minimal/` | False-transition guard demonstration |
-| Implementation-control cycle | `examples/implementation-control-cycles/` | Cycle and Kaizen transition model |
-| Public pilot 001 | `pilots/independent-implementation-001-conference-planning/` | Independent implementation package |
-| Public pilot 002 | `pilots/independent-implementation-002-software-specification/` | Software-specification package |
-| Public pilot 003 | `pilots/independent-implementation-003-ai-employee-workflow/` | AI employee workflow package |
-| Public pilot 004 | `pilots/independent-implementation-004-research-program/` | Research-program governance package |
-
-## Metrics
-
-Current metrics:
-
-- context size reduction;
-- context-pack validity;
-- profile conformance;
-- false-transition rejection;
-- evidence coverage;
-- readiness score.
-
-Planned metrics:
-
-- missed dependency count;
-- unsupported assumption count;
-- rework cycles;
-- time to relevant context;
-- time to validated completion;
-- manual review overhead.
-
-## Reproducibility Commands
-
-```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:baseline-comparison
-npm run playground:demo
-npm run playground:report
-```
-
-## Evidence Boundaries
-
-- Synthetic fixtures demonstrate method shape and executable validation.
-- Public pilots demonstrate applicability, not universal effectiveness.
-- Passing validators prove conformance to current alpha checks only.
-- Readiness scores are navigation signals, not approval.
-- Generated context is not canonical state.
-- Evidence and proposals do not authorize canonical updates.
-
-## Current Maturity Verdict
-
-Mirai Graph is ready for:
-
-- public alpha adoption;
-- internal and public-safe pilots;
-- developer integration experiments;
-- research protocol refinement;
-- preprint preparation.
-
-Mirai Graph is not yet ready for:
-
-- v1.0 stability claims;
-- production autonomous execution claims;
-- broad scientific effectiveness claims;
-- country-scale governance claims without further evidence.

package/docs/research/evidence-package-v0.2.md

@@ -1,150 +0,0 @@
-# Mirai Graph Evidence Package v0.2
-
-Status: historical alpha research package
-
-## Purpose
-
-This package is the current public evidence entrypoint for Mirai Graph alpha. It
-connects executable validation, synthetic baseline comparison, public-safe
-pilots and scientific claim boundaries.
-
-It does not claim peer-reviewed proof of effectiveness.
-
-## Hypotheses Under Test
-
-H1. Graph-structured project state can reduce task-context size while
-preserving relevant dependencies.
-
-H2. Evidence-linked relations can reduce missed dependencies and unsupported
-assumptions in AI-assisted work.
-
-H3. Launch records, process transitions and process-control gates can reduce
-false progress claims, especially treating readiness as execution.
-
-H4. Recovery, source-boundary and Kaizen records can improve continuation across
-long-running human-AI workflows.
-
-H5. Domain profiles can make Mirai Graph usable beyond software projects,
-including AI employees, research programs and organization governance.
-
-H6. Instrumentation artifacts can make AI-assisted work more observable by
-linking cockpit signals, feature implementation traceability and multi-source
-quality feedback to explicit transition decisions.
-
-## Evidence Inventory
-
-| Evidence type | Public artifact | Current role | Evidence level |
-| --- | --- | --- | --- |
-| Synthetic benchmark | `benchmarks/synthetic-context-reduction-v0/` | Context-reduction demonstration | Synthetic |
-| Context-pack result | `benchmarks/synthetic-context-reduction-v0/results/context-pack.json` | Expected context-pack shape | Synthetic |
-| Baseline comparison | `benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json` | Baseline-vs-Mirai Graph metrics | Synthetic |
-| Process-transition fixtures | `examples/process-transition-minimal/` | False-transition guard checks | Synthetic |
-| Instrumentation layer | `examples/instrumentation-layer-minimal/` | Cockpit, traceability and multi-source feedback shape | Synthetic |
-| Playground report | `playground/demo-report.md` | End-to-end local demo | Synthetic |
-| Pilot 001 | `pilots/independent-implementation-001-conference-planning/` | Project-management applicability | Public-safe pilot |
-| Pilot 002 | `pilots/independent-implementation-002-software-specification/` | Software-specification applicability | Public-safe pilot |
-| Pilot 003 | `pilots/independent-implementation-003-ai-employee-workflow/` | AI-employee applicability | Public-safe pilot |
-| Pilot 004 | `pilots/independent-implementation-004-research-program/` | Research-program applicability | Public-safe pilot |
-| Pilot 005 | `pilots/independent-implementation-005-organization-governance/` | Organization-governance applicability | Public-safe pilot |
-
-## Metrics
-
-Current executable metrics:
-
-- context units;
-- context reduction percent;
-- missed dependency count;
-- unsupported assumption count;
-- evidence coverage;
-- false progress claims;
-- process-transition validity;
-- missing transition evidence count;
-- profile conformance validity;
-- instrumentation report validity;
-- public-safety gate verdict.
-
-Metrics still needing stronger study:
-
-- time to relevant context;
-- time to validated completion;
-- reviewer effort;
-- rework cycles;
-- inter-reviewer agreement;
-- downstream implementation quality;
-- external adopter success rate.
-
-## Reproducibility Commands
-
-Run the current public evidence suite:
-
-```bash
-npm test
-npm run release:check
-```
-
-Run focused evidence commands:
-
-```bash
-npm run benchmark:synthetic
-npm run validate:baseline-comparison
-npm run validate:process-transition
-npm run validate:process-transition-report
-npm run validate:instrumentation-layer
-npm run validate:pilots
-npm run validate:profile-results
-npm run playground:report
-```
-
-Run unified CLI report commands:
-
-```bash
-node packages/cli/mirai-graph.js report validation examples/minimal-graph
-node packages/cli/mirai-graph.js explain process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
-node packages/cli/mirai-graph.js report playground
-```
-
-## Interpretation Rules
-
-- Synthetic evidence demonstrates method shape and validator behavior.
-- Public pilots demonstrate profile applicability, not universal
-  effectiveness.
-- Baseline comparison artifacts are bounded examples, not broad empirical
-  proof.
-- Passing validators prove conformance to current alpha checks only.
-- Generated context is not canonical state.
-- Evidence, feedback, runtime results and proposals do not authorize canonical
-  updates.
-
-## Current Evidence Verdict
-
-Mirai Graph alpha currently supports these claims:
-
-- a public executable standard draft exists;
-- schemas, validators, starter templates and examples are runnable;
-- process transitions can be explained and fail closed on known invalid
-  transitions;
-- instrumentation reports can connect cockpit signals, feature traceability and
-  multi-source feedback to transition decisions;
-- synthetic baseline comparison can record context, evidence and assumption
-  metrics;
-- public-safe pilots cover software, AI employee, research-program and
-  organization-governance scenarios.
-
-Mirai Graph alpha does not yet support these claims:
-
-- peer-reviewed effectiveness;
-- production autonomous execution safety;
-- universal superiority over documents, chats or task trackers;
-- country-scale governance validity;
-- external validity across unrelated organizations;
-- automatic correctness of generated context.
-
-## Next Evidence Work
-
-- Add at least one public-safe external adopter pilot outside the original
-  Mirai Graph authoring contour.
-- Add reviewer packets and inter-reviewer agreement records.
-- Replicate baseline comparison across research, organization governance and
-  product-roadmap scenarios.
-- Add limitation tables per pilot.
-- Prepare a publication-ready reproducibility bundle.

package/docs/research/evidence-package-v0.3.md

@@ -1,256 +0,0 @@
-# Mirai Graph Evidence Package v0.3
-
-Status: 1.0 release-candidate public evidence package
-
-## Purpose
-
-This package is the current public evidence entrypoint for Mirai Graph
-`1.0.0-rc.6`. It connects three evidence layers:
-
-1. Synthetic benchmark and baseline comparison.
-2. Executable instrumentation artifacts.
-3. Public-safe independent implementation pilots.
-
-It is designed for external readers who need to understand what Mirai Graph can
-currently demonstrate, what remains unproven and how to reproduce the public
-checks.
-
-It does not claim peer-reviewed proof of effectiveness.
-
-## Evidence Maturity Summary
-
-| Layer | What exists | What it supports | What it does not support |
-| --- | --- | --- | --- |
-| Synthetic benchmark | `benchmarks/synthetic-context-reduction-v0/` | bounded context reduction and dependency-preservation measurement | broad productivity or quality claims |
-| Baseline comparison | `results/baseline-comparison-result.json` | explicit baseline-vs-graph metrics on one public-safe task | external validity |
-| Process fixtures | `examples/process-transition-minimal/` | fail-closed transition validation and readable explanations | runtime execution safety |
-| Instrumentation | `examples/instrumentation-layer-minimal/` | cockpit, traceability and multi-source feedback shape | prediction of real production outcomes |
-| Character Layer | `examples/character-layer-readiness-1-0/` | reusable behavior-governance profile, integration shape and portability evidence format | proof of broad model equivalence or production replacement safety |
-| Dynamic Episode | `examples/dynamic-episode-minimal/` | event-to-decision trace shape, blocked alternatives and feedback routing | proof of reduced drift in real code generation |
-| Semantic Intent | `examples/semantic-intent-resolution-minimal/` | input-control shape for intent, scale, owner, missing context and safe default action | proof that all real requests are interpreted correctly |
-| Goal Vector | `examples/goal-vector-quality-control-minimal/` | final-outcome vector links, reverse audit and correction routing | proof of reduced real-world goal drift |
-| Technology Feedback | `examples/technology-quality-feedback-minimal/` | conformance-check shape and classified process findings | proof that real work always followed the technology |
-| Public pilots | `pilots/independent-implementation-001..005-*` | profile applicability across domains | proof of real-world effectiveness |
-| Adopter kit | `docs/adoption/adopter-kit.md` | repeatable first adoption path | successful adoption without review |
-
-## Hypotheses Under Test
-
-H1. Graph-structured state can reduce task-context size while preserving
-relevant dependencies.
-
-H2. Evidence-linked relations can reduce missed dependencies and unsupported
-assumptions in AI-assisted work.
-
-H3. Launch records, process transitions and technology quality feedback can
-reduce false progress claims, especially treating readiness as execution.
-
-H4. Development cockpit, traceability and multi-source feedback artifacts can
-make AI-assisted work more observable.
-
-H5. Domain profiles can make the same graph model usable across software,
-research, AI employee and organization-governance scenarios.
-
-H6. A role-oriented adopter kit can reduce first-use ambiguity for external
-evaluators.
-
-H7. Externalized Character Layer constraints can improve behavior portability
-across model backends when measured through the same graph context, task set and
-fixtures.
-
-H8. Semantic intent resolution plus goal-vector quality control can reduce
-wrong-start errors, goal drift and false completion claims in AI-assisted
-workflows.
-
-H9. Dynamic episode traces plus technology quality feedback can make
-AI-assisted work auditable enough to support replay, regression and Kaizen
-improvement loops.
-
-These are hypotheses and engineering claims under test, not settled scientific
-facts.
-
-## Public Evidence Inventory
-
-| Evidence | Artifact | Reproducibility command | Evidence level |
-| --- | --- | --- | --- |
-| Package validation | `examples/minimal-graph/` | `npm run validate:minimal` | Synthetic conformance |
-| Context reduction | `benchmarks/synthetic-context-reduction-v0/` | `npm run benchmark:synthetic` | Synthetic metric |
-| Baseline comparison | `benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json` | `npm run validate:baseline-comparison` | Synthetic comparison |
-| Process transition | `examples/process-transition-minimal/` | `npm run validate:process-transition` | Executable fixture |
-| Process explanation report | `examples/process-transition-minimal/results/` | `npm run validate:process-transition-report` | Executable fixture |
-| Technology feedback | `examples/technology-quality-feedback-minimal/` | `npm run validate:technology-quality-feedback` | Executable fixture |
-| Semantic intent | `examples/semantic-intent-resolution-minimal/` | `npm run validate:semantic-intent-resolution` | Executable fixture |
-| Goal vector quality | `examples/goal-vector-quality-control-minimal/` | `npm run validate:goal-vector-quality-control` | Executable fixture |
-| Instrumentation layer | `examples/instrumentation-layer-minimal/` | `npm run validate:instrumentation-layer` | Executable fixture |
-| Instrumentation report | `examples/instrumentation-layer-minimal/` | `npm run validate:instrumentation-report` | Readable report |
-| Character Layer readiness | `examples/character-layer-readiness-1-0/` | `npm run validate:character-layer-readiness` | Profile readiness |
-| Model portability evidence | `examples/model-portability-minimal/` | `npm run validate:model-portability-evidence` | Synthetic comparison shape |
-| Adopter workflow | `docs/adoption/adopter-kit.md` and templates | `npm run validate:adopter-workflow` | Adoption readiness |
-| Public pilots | `pilots/independent-implementation-*` | `npm run validate:pilots` | Public-safe pilot |
-| Full release check | repository root | `npm run release:check` | Integrated validation |
-
-## Pilot Coverage Matrix
-
-| Pilot | Domain | Profile | Main question | Current verdict |
-| --- | --- | --- | --- | --- |
-| 001 | Conference planning | `project_management` | Can public materials produce a valid small workflow package? | `pass_with_notes` |
-| 002 | Software specification | `software_specification` | Can public materials produce a valid software-specification package? | `pass_with_notes` |
-| 003 | AI employee workflow | `ai_employee` | Can the graph model an AI employee as governance surface, not prompt only? | validates with boundaries |
-| 004 | Research program | `project_management` | Can the graph model evidence, limitations and publication gates? | validates with boundaries |
-| 005 | Organization governance | `organization_governance` | Can the graph model strategy, controls, metrics, feedback and Kaizen? | validates with boundaries |
-
-## Current Measured Signals
-
-The public suite currently measures or validates:
-
-- package conformance;
-- profile conformance;
-- graph seed validity;
-- context-pack shape;
-- context units;
-- context reduction percent;
-- missed dependency count;
-- unsupported assumption count;
-- evidence coverage;
-- false progress claims;
-- process-transition validity;
-- missing transition evidence;
-- technology-feedback classification;
-- semantic-intent route decision shape;
-- goal-vector linkage and reverse-audit shape;
-- instrumentation report validity;
-- character-layer readiness;
-- model-portability evidence shape;
-- pilot package validity;
-- public-safety boundaries.
-
-The synthetic context-reduction benchmark currently records:
-
-- baseline context units: `620`;
-- Mirai Graph context units: `270`;
-- context reduction: `56.4516%`;
-- baseline missed dependencies: `2`;
-- Mirai Graph missed dependencies: `0`.
-
-These numbers are useful as a reproducible synthetic demonstration. They are
-not broad empirical proof.
-
-## Interpretation Rules
-
-- Synthetic evidence demonstrates method shape and validator behavior.
-- Public pilots demonstrate profile applicability and adoption shape.
-- Baseline comparison artifacts are bounded examples, not broad empirical
-  studies.
-- Passing validators prove conformance to current release-candidate checks
-  only.
-- Generated context is not canonical state.
-- Evidence, feedback, runtime results and proposals do not authorize canonical
-  updates.
-- Cockpit scores are steering signals, not release authorization.
-- A pilot report is evidence of a completed public-safe exercise, not proof of
-  real-world outcome improvement.
-
-## Reproducibility Bundle
-
-Run:
-
-```bash
-npm install
-npm run release:check
-```
-
-Focused checks:
-
-```bash
-npm run benchmark:synthetic
-npm run validate:baseline-comparison
-npm run validate:process-transition
-npm run validate:process-transition-report
-npm run validate:technology-quality-feedback
-npm run validate:instrumentation-layer
-npm run validate:instrumentation-report
-npm run validate:character-layer-readiness
-npm run validate:model-portability-evidence
-npm run validate:pilots
-npm run validate:profile-results
-npm run validate:adopter-workflow
-npm run playground:report
-```
-
-Readable reports:
-
-```bash
-node packages/cli/mirai-graph.js report validation examples/minimal-graph
-node packages/cli/mirai-graph.js explain process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
-node packages/cli/mirai-graph.js report instrumentation examples/instrumentation-layer-minimal
-node packages/cli/mirai-graph.js report playground
-```
-
-## Current Evidence Verdict
-
-Mirai Graph `1.0.0-rc.6` supports these bounded claims:
-
-- a public executable standard draft exists;
-- schemas, validators, templates, examples and pilots are runnable;
-- process transitions can be validated, explained and failed closed;
-- technology quality feedback can classify findings and block unsafe
-  acceptance;
-- instrumentation can connect cockpit signals, feature traceability and
-  multi-source feedback to transition decisions;
-- Character Layer can represent reusable behavior governance, cross-layer
-  integration and bounded model-portability evidence;
-- Dynamic Episode traces can record a selected path, blocked alternatives,
-  evidence refs, finding classification and feedback routing for one governed
-  episode;
-- Semantic Intent Resolution can represent and validate an intent, scale,
-  owner/process and safe-default-action decision before execution;
-- Goal Vector Quality Control can represent and validate final-outcome vector
-  links, reverse audit, drift findings and correction routes;
-- the current public anti-drift contour can be inspected as a connected
-  sequence of input control, process control, episode trace, goal-vector audit,
-  technology feedback and Kaizen/replay candidate;
-- synthetic baseline comparison can record context, evidence and assumption
-  metrics;
-- public-safe pilots cover project-management, software-specification,
-  AI-employee, research-program and organization-governance scenarios;
-- the adopter kit gives a reproducible first-use path.
-
-Mirai Graph `1.0.0-rc.6` does not yet support these claims:
-
-- peer-reviewed effectiveness;
-- production autonomous execution safety;
-- universal superiority over documents, chats or task trackers;
-- country-scale governance validity;
-- external validity across unrelated organizations;
-- automatic correctness of generated context;
-- automatic canonical update authorization from evidence, feedback or
-  proposals.
-- proven real-world reduction of wrong-start, goal drift or process violation
-  rates without pilot/replay/regression evidence.
-
-## Next Evidence Work
-
-- Finish npm publication so reproduction can use published package install
-  rather than repository checkout.
-- Add a public-safe pilot with an external reviewer packet and response notes.
-- Replicate baseline comparison across at least two more domains:
-  research-program and organization-governance.
-- Add pilot limitation tables with the same fields across all pilots.
-- Add reviewer-effort and time-to-relevant-context metrics.
-- Prepare a publication-ready reproducibility bundle that cites this package as
-  the current release-candidate evidence index.
-- Use the two article foundation packages in `publications/` to collect
-  sanitized pilot evidence and publication-ready limitations.
-
-## Public Safety Boundary
-
-This package intentionally excludes:
-
-- private project paths;
-- customer data;
-- credentials and tokens;
-- private handoffs;
-- internal runtime traces;
-- unpublished private evaluation payloads.
-
-Private pilots may inform future standard improvements, but public evidence
-must stay synthetic, public-safe, bounded and reproducible.

package/docs/research/independent-implementation-pilot-plan.md

@@ -1,74 +0,0 @@
-# Independent Implementation Pilot Plan
-
-Status: 1.0 release-candidate research plan
-
-## Purpose
-
-This plan defines the first public-safe path for testing whether Mirai Graph can
-be implemented outside its original practical `$graph` environment.
-
-## Research Question
-
-Can an independent implementer follow the public Mirai Graph standard and create
-a valid Level 1 package without access to private internal materials?
-
-## Hypothesis
-
-Given the public standard, schemas, examples and validator, an implementer can
-create a valid Mirai Graph package for a small project or workflow.
-
-## Pilot Scope
-
-Recommended first scope:
-
-- one small software project;
-- one project-management workflow;
-- one research-program workflow.
-
-Each pilot should produce:
-
-- `graph.json`;
-- `graph/objects.json`;
-- `graph/relations.json`;
-- optional `gates/results.json`;
-- validation output;
-- reviewer notes.
-
-## Procedure
-
-1. Provide only public Mirai Graph materials.
-2. Ask implementer to choose a small public-safe domain.
-3. Create a graph seed.
-4. Generate or manually draft a graph embryo.
-5. Review candidate objects and relations.
-6. Write canonical package files.
-7. Run validator.
-8. Record time, blockers, confusing sections and missing concepts.
-9. Produce a pilot report.
-
-## Metrics
-
-- time to first valid package;
-- validation errors;
-- warnings;
-- number of clarification questions;
-- missing standard sections;
-- object/relation quality review;
-- evidence boundary quality;
-- implementation confidence.
-
-## Acceptance
-
-Pilot passes when:
-
-- package validates;
-- implementer can explain object and relation choices;
-- evidence boundary is explicit;
-- no private material is included;
-- limitations are recorded.
-
-## Research Use
-
-This pilot can support claims about standard usability and implementation
-clarity. It cannot prove external effectiveness, runtime safety or universal
-validity.