mirai-graph 1.3.0 → 2.1.0

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

@@ -1,40 +0,0 @@
-# Mirai Graph Limitations And Threats To Validity
-
-Status: 1.0 release-candidate 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."

package/docs/research/practice-science-program.md

@@ -1,232 +0,0 @@
-# Mirai Graph Practice And Science Program
-
-Status: working program model
-
-## Purpose
-
-Mirai Graph should develop as both:
-
-- a practical graph methodology used in real AI-assisted work;
-- a scientific research program that produces publishable evidence, standards
-  and reproducible artifacts.
-
-The practical `$graph` skill is the implementation and methodology laboratory.
-The public Mirai Graph repository is the standardization, adoption and research
-artifact layer.
-
-## Operating Role
-
-The maintainer role is not only to write theory.
-
-The role is to act as a research engineer / scientific collaborator who:
-
-- observes practical graph use;
-- detects methodological gaps;
-- improves standard definitions;
-- helps implementation mature;
-- designs measurable experiments;
-- records evidence and limitations;
-- prepares publication-ready artifacts;
-- prevents overclaiming;
-- keeps public materials safe and reusable.
-
-## Three-Layer Model
-
-### 1. Practical Layer
-
-Source:
-
-`$graph` skill and real project usage.
-
-Purpose:
-
-- convert scattered information into object graphs;
-- build graph seeds and graph embryos;
-- generate AI context packs;
-- validate readiness;
-- run practical rollout workflows;
-- discover tooling and methodology gaps.
-
-Output examples:
-
-- object and relation candidates;
-- extraction reports;
-- generated context packs;
-- graph readiness dashboards;
-- benchmark runs;
-- method improvement candidates.
-
-### 2. Public Standard Layer
-
-Source:
-
-This repository.
-
-Purpose:
-
-- define implementation-independent terminology;
-- define schemas and conformance levels;
-- publish public-safe examples;
-- maintain adoption guides;
-- provide validators and reference tooling;
-- separate standard from one private implementation.
-
-Output examples:
-
-- standard sections;
-- schemas;
-- CLI validator;
-- examples;
-- synthetic benchmark packages;
-- profiles;
-- conformance reports.
-
-### 3. Scientific Layer
-
-Source:
-
-Research workspace, public-safe evidence and publications.
-
-Purpose:
-
-- formulate research questions;
-- design experiments;
-- compare baselines;
-- record evidence levels;
-- prepare manuscripts;
-- publish reproducibility packages;
-- handle limitations and reviewer objections.
-
-Output examples:
-
-- experiment protocols;
-- validation results;
-- evidence inventories;
-- literature maps;
-- preprints;
-- journal manuscripts;
-- response-to-review tables.
-
-The current public evidence framing is maintained in
-`docs/research/scientific-evidence-package.md`, with the current evidence index
-in `docs/research/evidence-package-v0.3.md`.
-
-## Core Development Loop
-
-Mirai Graph development should follow this loop:
-
-```text
-practical use
--> observed gap
--> classify gap
--> update implementation, standard or research plan
--> validate with tests or experiment
--> publish public-safe artifact
--> feed lessons back into practice
-```
-
-## Gap Classification
-
-Every significant finding should be classified as:
-
-- `local_gap`: specific to one project or example;
-- `profile_gap`: belongs to a Mirai Graph profile;
-- `standard_gap`: should change the public standard;
-- `tooling_gap`: needs validator, generator, migration or CLI work;
-- `research_gap`: needs protocol, evidence or independent validation;
-- `publication_gap`: needs clearer writing, citations, limitations or data.
-
-## Measurement Discipline
-
-Do not assume graph mode is better. Measure it.
-
-Recommended evaluation cycle:
-
-```text
-freeze benchmark
--> measure current mode
--> convert selected scope to graph mode
--> measure graph mode
--> compare
--> optimize
--> validate
--> scale
-```
-
-Minimum metrics:
-
-- time to relevant context;
-- context size;
-- context precision;
-- missed dependencies;
-- wrong assumptions;
-- rework cycles;
-- evidence coverage;
-- time to done;
-- manual review overhead.
-
-## Research Artifact Policy
-
-Every important practical improvement should produce at least one durable
-research artifact:
-
-- experiment protocol;
-- benchmark fixture;
-- result note;
-- evidence table;
-- limitation note;
-- standard change proposal;
-- publication note.
-
-If no artifact is produced, the learning remains anecdotal.
-
-## Public Transfer Policy
-
-Not every practical `$graph` detail belongs in the public standard.
-
-Promote only material that is:
-
-- reusable beyond one private project;
-- public-safe;
-- evidence-bounded;
-- implementation-independent or clearly marked as reference tooling;
-- useful for adoption, validation or publication.
-
-Keep private:
-
-- raw project materials;
-- internal chats;
-- secrets;
-- customer or employee data;
-- private skill internals that are not approved for release.
-
-## Immediate Program Priorities
-
-1. Map existing `$graph` capabilities to Mirai Graph public standard sections.
-2. Identify which `$graph` features are standard concepts, profile concepts or
-   implementation details.
-3. Create a public-safe standard gap report.
-4. Add schemas for context packs and profiles.
-5. Create a benchmark protocol that compares text-first and graph-assisted
-   workflows.
-6. Prepare a validation roadmap for future publications.
-
-## Scientific Guardrails
-
-- Do not claim universal validity from internal use.
-- Do not treat synthetic benchmark results as field validation.
-- Do not confuse product usefulness with scientific proof.
-- Do not publish private implementation details without approval.
-- Do not describe a preprint as peer reviewed unless the venue confirms it.
-
-## Working Verdict
-
-Mirai Graph should be developed as a research-engineering program:
-
-```text
-practice-led, evidence-bounded, standard-oriented and publication-aware
-```
-
-The practical `$graph` skill is a source of real operational pressure and
-method gaps. The public Mirai Graph repository turns reusable lessons into a
-standard, tooling and scientific evidence.

package/docs/research/scientific-evidence-package.md

@@ -1,188 +0,0 @@
-# Mirai Graph Scientific Evidence Package
-
-Status: 1.0 release-candidate evidence framing
-
-## Purpose
-
-This document defines how public Mirai Graph evidence should be read. It connects
-synthetic benchmarks, public pilots, reproducibility materials and publication
-notes without overclaiming scientific proof.
-
-## Current Research Hypotheses
-
-Mirai Graph is currently evaluated around these hypotheses:
-
-- Graph-structured project state can reduce task-context size while preserving
-  relevant dependencies.
-- Evidence-linked relations can reduce missed dependencies and unsupported
-  assumptions in AI-assisted work.
-- Launch records, process transitions and governance gates can reduce false
-  progress claims such as treating readiness as execution.
-- Recovery, source-boundary and Kaizen records can improve continuation across
-  long-running human-AI workflows.
-- Semantic intent resolution can reduce wrong-start errors by making intent,
-  scale, owner, missing context and safe default action explicit before
-  execution starts.
-- Goal-vector quality control can reduce goal drift and false completion claims
-  by requiring each meaningful batch to link to the final outcome and pass
-  reverse audit before completion is claimed.
-- Dynamic episode traces and technology quality feedback can make AI-assisted
-  work more observable by separating what should have happened, what actually
-  happened, why paths were selected or blocked and where correction should
-  route.
-
-These are hypotheses and engineering claims under test, not settled scientific
-facts.
-
-## Evidence Levels
-
-### Synthetic Evidence
-
-Synthetic evidence uses public-safe examples and benchmarks.
-
-Current materials:
-
-- `benchmarks/synthetic-context-reduction-v0/`
-- `benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json`
-- `examples/federation-routing-smoke/`
-- `examples/process-transition-minimal/`
-- `examples/implementation-control-cycles/`
-- `examples/instrumentation-layer-minimal/`
-- `examples/semantic-intent-resolution-minimal/`
-- `examples/goal-vector-quality-control-minimal/`
-- `examples/dynamic-episode-minimal/`
-- `examples/technology-quality-feedback-minimal/`
-
-Use synthetic evidence to inspect method shape, validation behavior and
-reproducibility. Do not treat it as broad external validity.
-
-### Public Pilot Evidence
-
-Pilot evidence uses public-safe implementation packages and reports.
-
-Current materials:
-
-- `pilots/independent-implementation-001-conference-planning/`
-- `pilots/independent-implementation-002-software-specification/`
-- `pilots/independent-implementation-003-ai-employee-workflow/`
-- `pilots/independent-implementation-004-research-program/`
-- `pilots/independent-implementation-005-organization-governance/`
-
-Use pilot evidence to inspect whether the model can be applied outside the
-minimal examples. Pilot evidence still needs replication and independent
-review.
-
-### Scientific Evidence
-
-Scientific evidence requires explicit protocols, metrics, limitations and
-comparison baselines.
-
-Current supporting materials:
-
-- `docs/research/evidence-package-v0.3.md`
-- `docs/research/evidence-package-v0.2.md`
-- `docs/research/evidence-package-v0.1.md`
-- `docs/research/baseline-comparison-protocol.md`
-- `docs/research/limitations-and-threats.md`
-- `docs/research/practice-science-program.md`
-- `docs/research/ai-work-field-instrumentation-bridge.md`
-- `docs/research/independent-implementation-pilot-plan.md`
-- `docs/research/semantic-completeness-review-protocol.md`
-- `publications/README.md`
-- `publications/preprint-note.md`
-- `publications/preprint-outline.md`
-- `publications/semantic-intent-goal-vector-control/README.md`
-- `publications/observable-self-correcting-ai-workflows/README.md`
-
-Use `docs/research/evidence-package-v0.3.md` as the current public evidence
-entrypoint. The v0.2 and v0.1 packages remain historical alpha evidence
-snapshots.
-
-## Metrics Under Development
-
-Recommended metrics:
-
-- context size reduction;
-- context precision;
-- missed dependency count;
-- unsupported assumption count;
-- evidence coverage;
-- rework cycles;
-- time to relevant context;
-- time to validated completion;
-- review overhead;
-- false-transition rejection rate.
-- wrong-start rate;
-- goal-drift finding count;
-- false-completion claim count;
-- missing reverse-audit count;
-- process-violation classification count;
-- correction-route coverage;
-- replay/regression pass rate.
-
-## Reproducibility Path
-
-Run:
-
-```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:instrumentation-layer
-npm run validate:dynamic-episodes
-npm run validate:semantic-intent-resolution
-npm run validate:goal-vector-quality-control
-npm run validate:technology-quality-feedback
-npm run validate:baseline-comparison
-npm run validate:pilots
-npm run validate:templates
-npm run validate:cli-unified
-```
-
-Then inspect:
-
-- benchmark input package;
-- generated or expected context pack;
-- validator output;
-- profile conformance results;
-- limitations recorded in each result.
-
-## Claim Boundaries
-
-Mirai Graph public alpha may claim:
-
-- a public standard draft exists;
-- schemas, validators and examples are runnable;
-- synthetic and pilot evidence are separated;
-- baseline comparisons are public-safe and bounded by explicit limitations;
-- governance controls can be represented and tested in public-safe fixtures.
-- cockpit, traceability and multi-source feedback artifacts can be represented
-  and validated as bounded instrumentation inputs.
-- role-oriented adopter workflow evidence can connect templates, CLI checks and
-  public-safety boundaries into a reproducible first-use path.
-- semantic intent, dynamic episode, goal-vector and technology-feedback
-  artifacts can be represented as one anti-drift / quality-control contour.
-
-Mirai Graph public alpha must not claim:
-
-- peer-reviewed proof of effectiveness;
-- production safety for autonomous execution;
-- universal superiority over document-based workflows;
-- automatic correctness of generated context;
-- canonical update authorization from evidence, feedback or proposals.
-- real-world drift reduction without pilot/replay/regression evidence.
-
-## Next Evidence Work
-
-- Add more independent public pilots.
-- Replicate baseline-vs-graph comparison reports across different domains.
-- Publish limitation tables per pilot.
-- Prepare publication-ready reproducibility bundles.
-- Record reviewer objections and response notes when publications exist.
-- Run sanitized baseline-vs-graph-controlled episodes for software-generation
-  and research/governance tasks.
-- Package the two article candidates under `publications/` with metrics,
-  limitations and artifact maps.

package/docs/research/semantic-completeness-review-protocol.md

@@ -1,70 +0,0 @@
-# Semantic Completeness Review Protocol
-
-Status: 1.0 release-candidate public protocol
-
-## Purpose
-
-Context reduction is useful only if the reduced context preserves the meaning
-needed for the task.
-
-This protocol reviews whether a generated context pack is semantically complete
-enough for its declared task.
-
-## Research Question
-
-Does the generated context pack preserve the objects, relations, evidence,
-risks and governance constraints needed to perform the task?
-
-## Review Inputs
-
-- task definition;
-- canonical graph package;
-- generated context pack;
-- source corpus or source summary;
-- evidence references;
-- expected output or reviewer rubric.
-
-## Review Rubric
-
-Score each dimension from `0` to `2`:
-
-- `0`: missing or misleading;
-- `1`: partially present;
-- `2`: sufficient for the task.
-
-Dimensions:
-
-1. Task relevance.
-2. Required object coverage.
-3. Required relation coverage.
-4. Evidence preservation.
-5. Risk and blocker visibility.
-6. Governance gate visibility.
-7. Omission transparency.
-8. No private or unsafe leakage.
-
-## Verdicts
-
-- `pass`: sufficient for the task.
-- `pass_with_notes`: usable, but limitations must be recorded.
-- `needs_more_context`: important context is missing.
-- `semantic_regression`: context reduction changed or weakened meaning.
-- `unsafe_context`: context leaks private material or hides safety constraints.
-
-## Output Artifact
-
-Recommended output:
-
-```text
-benchmarks/<benchmark-id>/reviews/semantic-completeness-review.json
-```
-
-## Claim Rule
-
-Passing this review supports a limited claim:
-
-```text
-The generated context pack preserved task-relevant meaning under this review protocol.
-```
-
-It does not prove external validity or universal semantic completeness.

package/docs/terminology.md

@@ -1,119 +0,0 @@
-# Mirai Graph Terminology
-
-Status: 1.0 release-candidate terminology
-
-## Mirai Graph
-
-An evolutionary graph operating model for managing the growth of complex
-systems.
-
-Mirai Graph combines canonical graph state, generated context packs, evidence,
-readiness, profiles and governance gates.
-
-## Evolutionary Object Graph
-
-The scientific continuity term used in earlier research materials. Mirai Graph is
-the public working name for the same model direction.
-
-## Complex System
-
-A system with many interacting parts, changing goals, dependencies, evidence,
-decisions and feedback loops.
-
-Examples include projects, products, organizations, research programs and
-human-AI systems.
-
-## Object
-
-A stable graph entity that represents something the system needs to track.
-
-Examples:
-
-- feature;
-- requirement;
-- decision;
-- component;
-- risk;
-- task;
-- evidence item;
-- governance gate.
-
-## Relation
-
-A typed connection between two objects.
-
-Examples:
-
-- depends on;
-- implements;
-- blocks;
-- supports;
-- contradicts;
-- evidences;
-- governs;
-- supersedes.
-
-## Canonical Graph State
-
-The maintained source-of-truth graph state. It should have stable object
-identity, typed relations, evidence links, lifecycle/readiness fields and
-governance rules.
-
-## Generated Context Pack
-
-A task-specific context package generated from canonical graph state.
-
-It helps a human or AI assistant perform a specific task, but it is not itself
-the canonical source of truth.
-
-## Graph Seed
-
-The smallest useful starting structure for a Mirai Graph model. A seed captures
-the initial objects, relations, evidence boundaries and intended growth path.
-
-## Graph Embryo
-
-An early graph state that has grown beyond a seed but is not yet mature enough
-to be treated as a stable canonical model.
-
-## Evidence
-
-Material that supports, explains or constrains a graph object, relation,
-decision or claim.
-
-Evidence can include documents, source records, experiments, reviews, logs,
-published sources or synthetic examples. Evidence level must be explicit.
-
-## Readiness
-
-A maturity state that indicates whether an object, relation, decision, context
-pack or standard section is draft, review-ready, accepted, blocked, deprecated
-or otherwise constrained.
-
-## Profile
-
-A domain-specific adaptation of the core Mirai Graph model.
-
-Profiles may define additional object kinds, relation types, readiness rules,
-governance gates and examples without changing the core standard.
-
-## Governance Gate
-
-A rule or checkpoint that controls whether a proposed update, claim, generated
-context pack or action may proceed.
-
-Governance gates separate:
-
-- suggestion from decision;
-- generated context from canonical state;
-- evidence from claim;
-- planning from action;
-- private material from public release.
-
-## Conformance Level
-
-A declared level showing how completely an implementation follows the Mirai Graph
-standard.
-
-Conformance levels should be testable with schemas, examples, fixtures and
-validation rules.