mirai-graph 1.0.0-rc.1

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

@@ -0,0 +1,99 @@
+# Mirai Graph Evidence Package v0.1
+
+Status: 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

@@ -0,0 +1,150 @@
+# Mirai Graph Evidence Package v0.2
+
+Status: 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

@@ -0,0 +1,226 @@
+# 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.1`. 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 |
+| 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.
+
+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 |
+| 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;
+- 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.1` 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;
+- 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.1` 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.
+
+## 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.
+
+## 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

@@ -0,0 +1,74 @@
+# Independent Implementation Pilot Plan
+
+Status: initial 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:
+
+- `mirai-graph-package.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.

package/docs/research/limitations-and-threats.md

@@ -0,0 +1,40 @@
+# Mirai Graph Limitations And Threats To Validity
+
+Status: alpha limitation table
+
+## Known Limitations
+
+| Area | Limitation | Mitigation |
+|---|---|---|
+| Synthetic benchmarks | Public examples are simplified | Add more independent public-safe pilots |
+| Context generation | Alpha generator uses simple matching and relation expansion | Add semantic review and baseline comparison |
+| Validation | Validators check declared shape, not full truth | Keep evidence and reviewer checks separate |
+| Readiness score | Score is a navigation signal | Do not use readiness as approval |
+| Process control | State-machine validation can miss domain meaning | Require domain review and evidence |
+| Scientific evidence | Current evidence is not peer-reviewed proof | Maintain protocols, limitations and reproducibility |
+| External validity | Most examples are maintained by the project author | Add third-party or independently produced pilots |
+
+## Threats To Validity
+
+- Selection bias in chosen examples.
+- Overfitting fixtures to current validators.
+- Measuring context reduction without measuring missed dependencies.
+- Treating public-safe simplification as real-world complexity.
+- Treating AI-assisted review output as ground truth.
+- Confusing governance conformance with operational safety.
+
+## Required Claim Discipline
+
+Allowed:
+
+- "Mirai Graph alpha provides runnable schemas, validators and public-safe
+  examples."
+- "Synthetic benchmark results demonstrate the method on a controlled fixture."
+- "Public pilots provide early applicability evidence."
+
+Not allowed:
+
+- "Mirai Graph is scientifically proven."
+- "Mirai Graph is production-safe for autonomous execution."
+- "Mirai Graph replaces human governance."
+- "Generated context is canonical truth."