mirai-graph 1.4.0 → 2.1.0

package/schemas/work-state-machine.schema.json

@@ -1,34 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://mirai-graph.dev/schemas/work-state-machine.schema.json",
-  "title": "Mirai Graph Work State Machine",
-  "type": "object",
-  "additionalProperties": true,
-  "required": ["schema_version", "id", "profile", "public_safety", "states", "transitions", "false_transition_guards", "evidence_refs", "limitations"],
-  "properties": {
-    "schema_version": { "type": "string", "minLength": 1 },
-    "id": { "type": "string", "minLength": 1 },
-    "profile": { "const": "implementation_control" },
-    "public_safety": { "const": "synthetic_public" },
-    "states": { "type": "array", "minItems": 2, "items": { "type": "string", "minLength": 1 } },
-    "terminal_states": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-    "transitions": {
-      "type": "array",
-      "minItems": 1,
-      "items": {
-        "type": "object",
-        "required": ["from", "to", "requires_evidence"],
-        "properties": {
-          "from": { "type": "string", "minLength": 1 },
-          "to": { "type": "string", "minLength": 1 },
-          "requires_evidence": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-          "requires_launch_record": { "type": "boolean" },
-          "terminal_requires_kaizen": { "type": "boolean" }
-        }
-      }
-    },
-    "false_transition_guards": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
-    "evidence_refs": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
-    "limitations": { "type": "array", "items": { "type": "string" } }
-  }
-}

package/standard/action-runtime-boundary.md

@@ -1,99 +0,0 @@
-# Action Runtime Boundary
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-This section defines the boundary between Mirai Graph canonical state and
-action-capable runtime behavior.
-
-The boundary is required for AI employees, automation systems and any
-Mirai Graph implementation that can affect external systems.
-
-## State Sequence
-
-Action-capable implementations should preserve this sequence:
-
-```text
-canonical graph state
--> generated context
--> runtime decision
--> proposed action
--> approval gate
--> executed action
--> audited result
-```
-
-## Canonical Graph State
-
-Canonical graph state is the source of truth for durable objects, relations,
-policies, evidence, readiness and governance records.
-
-It may say that an AI employee has a role, can use a tool or follows a policy.
-It does not prove that a particular runtime action should execute now.
-
-## Generated Context
-
-Generated context is a task-bounded view derived from canonical state.
-
-It helps a human or AI system reason about a task. It is not authorization.
-
-## Runtime Decision
-
-A runtime decision is a transient conclusion produced by an implementation.
-
-It may recommend an action, escalation, delegation or no-op. It should record
-the context, policy and evidence it used.
-
-## Proposed Action
-
-A proposed action describes what the runtime wants to do before execution.
-
-It should include:
-
-- action id;
-- actor;
-- target system or object;
-- required capability;
-- applicable policy;
-- approval requirement;
-- expected result;
-- rollback or recovery note when relevant.
-
-## Approval Gate
-
-An approval gate decides whether a proposed action may execute.
-
-Approval may be automatic for low-risk actions when policy allows it. It should
-be explicit for external, irreversible, sensitive, permission-changing or
-public-facing actions.
-
-## Executed Action
-
-An executed action records that a runtime operation actually happened.
-
-It should not be represented only as an intended task. It needs execution
-evidence, timestamp or version reference, status and actor/runtime identity
-where available.
-
-## Audited Result
-
-An audited result records the observed outcome and whether it matched the
-expected result.
-
-Results may produce feedback, lessons, risks or follow-up actions. They should
-not silently update canonical behavior without a learning gate.
-
-## Minimum Safety Rule
-
-```text
-generated context != authorization
-runtime decision != executed action
-feedback != canonical update
-```
-
-## Implementation Note
-
-Mirai Graph can model this boundary. The runtime implementation remains
-responsible for authentication, authorization, tool sandboxing, retries,
-timeouts, logging, rollback and operational security.

package/standard/adoption-levels.md

@@ -1,69 +0,0 @@
-# Mirai Graph Adoption Levels
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Mirai Graph adoption is not binary. A repository, project, product, AI employee
-or skill can contain valid graph artifacts without being ready for runtime use
-or source-of-truth migration.
-
-Adoption levels define a staged path from no graph artifacts to a governed
-graph-first source candidate.
-
-## Levels
-
-| Level | Name | Meaning |
-| --- | --- | --- |
-| GGA0 | `not_started` | No Mirai Graph artifacts are present. |
-| GGA1 | `inventoried` | Sources, owner boundaries and target scope are identified. |
-| GGA2 | `seeded` | A Graph Seed exists and validates. |
-| GGA3 | `embryo_reviewable` | Graph Embryo and initial projection views exist. |
-| GGA4 | `scored` | Readiness, quality or control dashboard evidence exists. |
-| GGA5 | `proposal_gated` | Candidate graph changes pass through proposal, review and apply gates. |
-| GGA6 | `semantically_preserved` | Meaning-preservation review passed for the declared scope. |
-| GGA7 | `effectiveness_checked` | Representative tasks show non-regressed or improved operation. |
-| GGA8 | `federation_ready` | Bounded federation export or contract is valid. |
-| GGA9 | `federation_integrated` | The graph participates in a larger graph, skill mesh or service federation. |
-| GGA10 | `graph_first_source_candidate` | A separate decision allows graph-first source planning or dry-run work. |
-
-## Sequential Gate Rule
-
-Later levels should not skip earlier gates. A system should not claim `GGA8`
-if semantic preservation and effectiveness evidence are missing.
-
-`GGA10` does not grant canonical write permission. It only means graph-first
-source planning or dry-run work may start under a separate decision artifact.
-
-## Required Evidence
-
-An adoption report should record:
-
-- target scope;
-- source classes;
-- owner boundary;
-- profile;
-- latest level;
-- level evidence;
-- blockers;
-- next action;
-- gate results;
-- limitations.
-
-## Anti-Claims
-
-Do not claim that a graph is migrated because:
-
-- JSON validates;
-- a seed exists;
-- a context pack was generated;
-- a dashboard is green;
-- a profile conformance fixture passed.
-
-Those are useful signals, not full adoption.
-
-## Limited Claim
-
-Passing a level supports only the claim attached to that level. For example,
-`GGA2` supports the claim that a Graph Seed validates. It does not support a
-claim that the graph preserved domain meaning or improved work.

package/standard/conformance-levels.md

@@ -1,133 +0,0 @@
-# Mirai Graph Conformance Levels
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Conformance levels describe how completely an implementation follows the
-Mirai Graph standard.
-
-Conformance must be testable. A project should not claim a level without
-evidence, fixtures or validation output.
-
-## Level 0: Terminology Alignment
-
-The implementation uses Mirai Graph terminology consistently but does not yet
-provide a complete canonical graph package.
-
-Expected evidence:
-
-- terminology map;
-- declared deviations;
-- no claim of full implementation.
-
-Useful for:
-
-- early documentation;
-- research discussion;
-- internal planning.
-
-## Level 1: Canonical Graph State
-
-The implementation maintains objects and relations in a structured graph
-package.
-
-Minimum requirements:
-
-- object ids are stable;
-- relation ids are stable;
-- relation source and target resolve to existing objects;
-- readiness values are present;
-- evidence boundaries are explicit;
-- package passes the validator.
-
-Current validator:
-
-```bash
-node packages/cli/validate-mirai-graph.js <package-dir>
-```
-
-Useful for:
-
-- structured specification work;
-- simple examples;
-- early integration pilots.
-
-## Level 2: Context-Pack Generation
-
-The implementation can generate task-specific context packs from canonical
-graph state.
-
-Minimum requirements:
-
-- context pack declares task boundary;
-- included objects and relations are traceable;
-- evidence references are preserved;
-- omitted context is explainable;
-- generated context is not treated as canonical state.
-
-Useful for:
-
-- AI-assisted work;
-- context engineering;
-- task-specific review and implementation.
-
-## Level 3: Governance-Gated Operation
-
-The implementation uses governance gates for accepted graph updates, public
-claims or action-capable workflows.
-
-Minimum requirements:
-
-- governance gates are defined;
-- gate results are recorded;
-- blocked items remain traceable;
-- action-capable workflows separate proposed, authorized and executed action;
-- public claims are evidence-gated.
-
-Useful for:
-
-- organizational workflows;
-- public documentation;
-- safety-sensitive AI-assisted work;
-- product or project governance.
-
-## Level 4: Profiled Multi-Domain Operation
-
-The implementation supports profiles and profile boundaries.
-
-Minimum requirements:
-
-- at least two profiles exist;
-- profile-specific object kinds or relation types are documented;
-- cross-profile conflicts are handled;
-- conformance evidence is recorded per profile;
-- core standard remains stable across profiles.
-
-Useful for:
-
-- multi-project systems;
-- organizational adoption;
-- cross-domain research;
-- public-sector or country-scale conceptual modeling.
-
-## Current Repository Conformance
-
-Current status:
-
-`Level 1 partial`
-
-Evidence:
-
-- minimal graph package validates;
-- synthetic benchmark package validates;
-- schemas and validator exist;
-- standard sections are still incomplete.
-
-Not yet present:
-
-- full context-pack generation standard;
-- governance gate result schema;
-- profile conformance tests;
-- package manifest schema;
-- independent implementation pilot.

package/standard/context-pack-generation.md

@@ -1,184 +0,0 @@
-# Mirai Graph Context-Pack Generation
-
-Status: 1.2 stable standard section
-
-## Purpose
-
-Context-pack generation defines how a Mirai Graph implementation produces
-task-specific working context from canonical graph state.
-
-A generated context pack helps a human or AI assistant perform a task. It does
-not replace canonical graph state.
-
-## Context Pack
-
-A context pack is a task-bounded view of the graph.
-
-It should include:
-
-- task id or task description;
-- included objects;
-- included relations;
-- evidence references;
-- assumptions;
-- omissions or excluded context;
-- generation method;
-- relevance scores and selection explanations when generated by tooling;
-- timestamp or version reference;
-- limitations.
-
-## Minimum Context-Pack Metadata
-
-```json
-{
-  "id": "context_pack.notify_after_approval",
-  "task_id": "task.notify_after_approval",
-  "source_graph": "package.synthetic_context_reduction_v0",
-  "generated_at": "2026-05-28",
-  "included_objects": [],
-  "included_relations": [],
-  "evidence": [],
-  "selection": {
-    "method": "token_matching_one_hop_relation_expansion_safety_shared_evidence",
-    "task_tokens": ["task", "notify", "after", "approval"],
-    "object_explanations": [],
-    "relation_explanations": []
-  },
-  "limitations": []
-}
-```
-
-## Generation Flow
-
-```text
-task -> select relevant objects -> select relevant relations
-     -> include evidence references -> record omissions
-     -> generate context pack -> review/use for task
-```
-
-Project Technology implements this as a deterministic four-phase protocol:
-
-```text
-discover -> expand -> compile -> verify
-```
-
-The traversal receipt binds the task digest, graph digest and revision to the
-visited nodes. The client records selected and rejected nodes, reasons,
-confidence and selector type. Compilation then adds the mandatory dependency
-closure and returns one of `needs_more_discovery`, `needs_decision`, `blocked`
-or `ready`.
-
-`ready` requires a result owner, terminal sources with exact revision and
-SHA-256, all mandatory processes and validators, explicit reasons for omitted
-branches, no required dependency cycle and no access or readiness conflict.
-The context budget may remove optional material only; it must never remove the
-mandatory closure.
-
-The compiled pack adds selected and rejected paths, visited nodes, stop
-reasons, mandatory closure, terminal sources, processes, constraints,
-validators, completeness and `context_pack_digest`. These fields extend this
-single context-pack contract; there is no parallel pack format.
-
-## Selection Rules
-
-A context pack should include:
-
-- objects directly required by the task;
-- relations needed to understand dependencies and blockers;
-- evidence supporting included claims;
-- governance gates relevant to the task;
-- known risks or limitations;
-- safety, security, privacy or public-release constraints that share evidence
-  with the selected task context, even when they are not lexical task matches.
-
-## Selection Explanations
-
-Generated context packs should explain why each included object and relation was
-selected.
-
-Object explanations should include:
-
-- object id;
-- relevance score or equivalent ranking signal;
-- reasons such as exact token match, one-hop relation expansion, safety-context
-  inclusion or evidence preservation.
-
-Relation explanations should include:
-
-- relation id;
-- reason for inclusion;
-- source and target ids when available.
-
-Scores are implementation signals. They help review the generated context, but
-they do not prove semantic completeness.
-
-## Usage Evidence
-
-Loading a source is not proof that it was used. For each significant rule,
-usage evidence connects:
-
-```text
-source -> applied rule -> decision -> changed or checked surface
-       -> validator -> outcome
-```
-
-Verification fails when the evidence belongs to another context pack, skips a
-mandatory source, process or validator, uses stale or tampered content, exposes
-private material or treats generated context as write authorization.
-
-## Validation
-
-Context-pack validation should check both shape and graph references:
-
-- required metadata fields are present;
-- `source_graph` matches the package manifest id;
-- included object ids exist in the source graph;
-- included relation ids exist and connect included objects;
-- evidence ids exist in the source graph;
-- selection explanations cover every included object and relation;
-- relation explanations identify source and target ids.
-
-A context pack should exclude:
-
-- unrelated graph areas;
-- private material outside the task boundary;
-- deprecated objects unless needed for historical context;
-- generated claims not accepted into canonical state.
-
-## Evidence Preservation
-
-Generated context should preserve evidence references. If a context pack
-summarizes an object, it should still identify the source object and evidence
-ids.
-
-## Omissions
-
-Omissions are part of responsible context generation.
-
-Each non-trivial context pack should state:
-
-- what was excluded;
-- why it was excluded;
-- whether exclusion creates risk;
-- when a broader context review is needed.
-
-## Generated Context Is Not Canonical State
-
-Generated context packs may be reviewed and then used as evidence or source
-material for graph updates. They do not automatically mutate canonical graph
-state.
-
-With `continuity_policy: task_boundary`, accepted continuity objects in
-`graph/specs` participate in the same traversal as every other graph object.
-Relevant previous cases can therefore be found without reading chat history or
-requiring a user to say "continue". Host-local receipts never enter a context
-pack and never become portable authority.
-
-## Anti-Patterns
-
-- Treating a generated context pack as the graph.
-- Removing evidence references during summarization.
-- Using one task pack for a different task without review.
-- Omitting governance gates to make a task easier.
-- Omitting safety constraints because they do not share task keywords.
-- Generating public context from private material without a release gate.

package/standard/development-cockpit.md

@@ -1,67 +0,0 @@
-# Development Cockpit
-
-Development Cockpit is a Mirai Graph instrumentation layer for steering governed work by observable signals instead of chat memory or informal confidence.
-
-It does not replace tests, review, approval, release gates, or canonical graph updates. It aggregates evidence-backed indicators so a coordinator can see whether a work system is on course, drifting, blocked, or ready for the next governed transition.
-
-## Purpose
-
-Development Cockpit is used when a project needs a compact operating view over:
-
-- trajectory toward the current goal;
-- graph coverage and implementation coverage;
-- evidence confidence;
-- documentation and code-location traceability;
-- quality and architecture integrity;
-- security, drift, blockers, dependencies, and next action.
-
-The cockpit is intentionally an instrument panel. It can recommend a next action, but it cannot authorize execution, approval, release, or canonical update by itself.
-
-## Required Model
-
-A cockpit report must declare:
-
-- `subject_ref`: the project, package, process, or work batch being observed;
-- `generated_at`: when the report was produced;
-- `instruments`: observable indicators with score, band, status, reason, and evidence references;
-- `readiness`: separated readiness signals for developer testing, product maturity, production, and external user testing;
-- `next_best_action`: a bounded recommended action with target cycle and required gates;
-- `blocking_rules`: conditions that stop transition even when aggregate scores look high;
-- `limitations`: boundary language that prevents confusing metrics with acceptance.
-
-## Instrument Rules
-
-Each instrument should be evidence-backed. Missing evidence is a signal, not a reason to fabricate confidence.
-
-Recommended instrument families:
-
-- `trajectory`: alignment with goal, DNA, scope, and current milestone;
-- `graph_coverage`: whether relevant objects, relations, dependencies, and lifecycle states are represented;
-- `implementation_coverage`: whether planned work maps to concrete implementation and evidence;
-- `evidence_confidence`: whether evidence is current, reproducible, and tied to the right claims;
-- `traceability`: whether features connect to specs, code, tests, documentation, and review;
-- `quality`: test health, semantic review, technology adherence, and defect patterns;
-- `architecture`: ownership boundaries, dependency shape, and source-boundary conformance;
-- `risk`: blockers, drift, security findings, release risks, and recovery options.
-
-## Transition Boundary
-
-Development Cockpit can support a transition decision only when paired with the relevant gate:
-
-```text
-cockpit signal -> transition request -> required evidence -> gate validation -> decision
-```
-
-High cockpit readiness is not execution, implementation, acceptance, release, or approval.
-
-## Kaizen Use
-
-Cockpit signals should feed Kaizen when they reveal repeatable process issues:
-
-- repeated missing evidence;
-- recurring dependency drift;
-- frequent reviewer corrections;
-- weak traceability between feature intent and implementation;
-- mismatch between tests and semantic acceptance.
-
-The Kaizen output is a classified improvement or proposal, not an automatic canonical update.

package/standard/dynamic-episode-layer.md

@@ -1,113 +0,0 @@
-# Dynamic Episode Layer
-
-Status: proposal/experimental standard section
-
-## Purpose
-
-The Dynamic Episode Layer records how a concrete event moves through a Mirai
-Graph system and why the system reacted the way it did.
-
-Existing technology chains define how work should be performed. Dynamic
-episodes record what actually happened for one event:
-
-```text
-event
--> activated graph objects and relations
--> selected workflow and technology chain
--> selected path
--> blocked alternatives
--> gates
--> result
--> findings
--> feedback route
--> Kaizen or graph proposal
-```
-
-This layer is designed for AI employees, AI-assisted code generation,
-governance simulations, project control and other systems where a result is not
-enough. A reviewer must be able to inspect why a path was selected, why other
-paths were blocked and which evidence supports the decision.
-
-## Core Rule
-
-```text
-canonical graph state != runtime trace != generated explanation != approval
-```
-
-A dynamic episode may create evidence, explanations, audit records, feedback
-and proposals. It must not mutate canonical graph state or authorize execution
-by itself.
-
-## Required Boundaries
-
-- An episode trace is evidence, not authorization.
-- Generated context is not canonical state.
-- Feedback is not an automatic graph update.
-- Passing tests do not mean acceptance.
-- Blocked paths must remain blocked until an owner-approved process changes the
-  gate, policy or graph relation.
-- Private event contents must not be copied into public examples or research
-  packages.
-
-## Record Levels
-
-The layer distinguishes four record levels:
-
-- `debug_log`: temporary implementation troubleshooting, short retention.
-- `episode_trace`: structured record explaining one event reaction.
-- `audit_record`: compact accountability record for later review.
-- `research_dataset`: sanitized, public-safe evidence derived from traces.
-
-## Dynamic Episode Lifecycle
-
-```text
-event_received
--> source_refs_loaded
--> graph_activation_recorded
--> workflow_selected
--> selected_path_recorded
--> blocked_paths_recorded
--> gates_evaluated
--> result_recorded
--> findings_classified
--> feedback_routed
--> kaizen_or_replay_candidate_recorded
-```
-
-## Required Fields
-
-A valid dynamic episode trace must identify:
-
-- event;
-- source references;
-- activated objects, relations, policies, gates and technology steps;
-- selected path;
-- blocked paths;
-- findings and classifications;
-- result;
-- evidence references;
-- limitations;
-- explicit `canonical_write_allowed=false`.
-
-## Relationship To Other Standard Sections
-
-- `implementation-control` defines process state and false-transition guards.
-- `technology-quality-feedback` checks whether the approved work technology was
-  followed.
-- `context-pack-generation` turns traces into bounded explanations.
-- `feedback-learning-gate` governs proposal and learning updates.
-- `action-runtime-boundary` prevents traces, evidence and proposals from
-  becoming unauthorized actions.
-
-## Conformance
-
-This proposal starts at synthetic conformance:
-
-- `D0_concept`: standard text only.
-- `D1_synthetic_episode`: synthetic example and validator.
-- `D2_internal_pilot`: internal project episode traces.
-- `D3_replay_regression`: replay and regression evidence.
-- `D4_audited_runtime`: operational audit records and retention policy.
-
-The current public layer should claim no more than `D1_synthetic_episode` until
-real pilots are validated.