mirai-graph 1.0.0-rc.1

package/standard/conformance-levels.md

@@ -0,0 +1,133 @@
+# Mirai Graph Conformance Levels
+
+Status: initial public draft
+
+## 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

@@ -0,0 +1,141 @@
+# Mirai Graph Context-Pack Generation
+
+Status: initial public draft
+
+## 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
+```
+
+## 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.
+
+## 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.
+
+## 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

@@ -0,0 +1,67 @@
+# 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/evidence-provenance.md

@@ -0,0 +1,128 @@
+# Mirai Graph Evidence And Provenance
+
+Status: initial public draft
+
+## Purpose
+
+Evidence and provenance rules explain how Mirai Graph links graph state to the
+materials, observations, decisions and reviews that justify it.
+
+Mirai Graph does not require every early idea to be fully proven. It does require
+important claims, accepted objects, accepted relations and public validation
+statements to make their evidence boundary explicit.
+
+## Evidence Object
+
+Evidence may be represented as a first-class object:
+
+```json
+{
+  "id": "source.example_note",
+  "kind": "evidence",
+  "title": "Example source note",
+  "summary": "A public-safe note used as evidence for a synthetic example.",
+  "readiness": "accepted",
+  "evidence": [],
+  "profile": "software_specification",
+  "source_path": "source-corpus/example.md"
+}
+```
+
+## Evidence Reference
+
+Objects and relations reference evidence by stable id:
+
+```json
+{
+  "id": "feature.example",
+  "evidence": ["source.example_note"]
+}
+```
+
+For mature Mirai Graph packages, evidence references should resolve to evidence
+objects or declared external sources.
+
+## Evidence Levels
+
+Initial evidence levels:
+
+- `synthetic`: artificial example or benchmark material;
+- `internal_case`: internal project or operational evidence;
+- `public_source`: public document, paper, repository or standard;
+- `experiment`: structured experiment result;
+- `review`: expert or peer review record;
+- `decision`: accepted governance or owner decision.
+
+Future schemas may add an explicit `evidence_level` field.
+
+## Provenance Questions
+
+For important graph state, a reviewer should be able to answer:
+
+- Where did this object or relation come from?
+- Is the source public, private, synthetic or experimental?
+- Who accepted it into canonical state?
+- What changed since the previous version?
+- Can this evidence be used publicly?
+- Does the evidence support the claim being made?
+
+## Public-Safe Evidence Rules
+
+Public Mirai Graph repositories should not include:
+
+- private source chats;
+- raw internal company materials;
+- customer or employee data;
+- secrets or access details;
+- private repository paths;
+- unpublished client work;
+- private metrics without approval and redaction.
+
+Use synthetic data or generalized public-safe summaries when public evidence is
+needed.
+
+## Claim Discipline
+
+Evidence must match claim strength.
+
+Synthetic benchmark evidence can support:
+
+- method inspection;
+- reproducibility of an example calculation;
+- schema and tooling demonstration.
+
+Synthetic benchmark evidence cannot support:
+
+- external validity;
+- real-world productivity improvement;
+- universal superiority claims;
+- agent safety claims.
+
+Internal case evidence can support:
+
+- case-study claims;
+- design feasibility;
+- observed workflow patterns.
+
+Internal case evidence cannot be treated as public reproducibility unless the
+data boundary and redaction plan are public and approved.
+
+## Provenance In Generated Context Packs
+
+A generated context pack should preserve evidence references for the objects and
+relations it includes.
+
+If context is compressed, the pack should still make clear:
+
+- what canonical objects it uses;
+- what evidence supports them;
+- what was omitted;
+- what the task boundary is.
+
+## Anti-Patterns
+
+- Treating a citation as evidence for a claim it does not support.
+- Treating synthetic examples as real-world validation.
+- Copying private source material into public examples.
+- Losing evidence references during context-pack generation.
+- Marking a public claim as validated before review.

package/standard/feature-implementation-traceability.md

@@ -0,0 +1,68 @@
+# Feature Implementation Traceability
+
+Feature Implementation Traceability is a Mirai Graph pattern for connecting feature intent to implementation, tests, evidence, documentation, and review.
+
+It answers a simple governance question:
+
+```text
+For each feature, what proves where it is implemented, how it was tested, what remains incomplete, and which transition decision it supports?
+```
+
+## Scope
+
+The traceability layer is useful for software products, AI employees, research systems, organizational processes, and other projects where generated or human plans must be tied to delivered work.
+
+It should track:
+
+- feature or capability reference;
+- owning component or package;
+- implementation mapping;
+- dependency mapping;
+- test and validation evidence;
+- documentation evidence;
+- review status;
+- known gaps and blockers;
+- supported transition or release decision.
+
+## Required Separation
+
+Mirai Graph keeps these states separate:
+
+- `specified`: the feature is described;
+- `mapped`: the feature is connected to expected implementation locations or work items;
+- `implemented`: the work has concrete implementation evidence;
+- `tested`: validation evidence exists;
+- `reviewed`: semantic or human review exists;
+- `accepted`: the relevant gate accepted the work;
+- `released`: release or publication gate passed.
+
+`specified`, `mapped`, `ready_to_execute`, and `ready_to_code` are not implementation.
+
+## Mapping Rules
+
+Every mapping should declare:
+
+- `feature_ref`;
+- `implementation_refs`;
+- `test_refs`;
+- `evidence_refs`;
+- `review_refs`;
+- `documentation_refs`;
+- `status`;
+- `confidence`;
+- `known_gaps`.
+
+An implementation mapping without evidence should stay below accepted readiness.
+
+## Governance Use
+
+Traceability supports:
+
+- cockpit instrumentation;
+- process-transition validation;
+- release readiness review;
+- technology quality feedback;
+- drift detection;
+- Kaizen classification.
+
+It does not create approval. It gives reviewers and validators a reproducible path from intent to work evidence.

package/standard/federation-health.md

@@ -0,0 +1,42 @@
+# Federation Health
+
+Status: alpha standard section
+
+## Purpose
+
+Federation health summarizes whether a graph-managed federation is routable,
+explainable and safe to use as a context/control layer.
+
+## Health Signals
+
+A health dashboard should include:
+
+- skill or capability count;
+- runtime-ready count;
+- stale graph count;
+- watch conflict count;
+- unresolved conflict count;
+- failed fixture count;
+- high-risk routes without explanation;
+- fallback-required route count;
+- blocked route count;
+- route regression status;
+- pending learning proposals;
+- conflict details with severity and next action.
+
+## Conflict Details
+
+Counts are not enough. A useful dashboard should identify:
+
+- conflict family id;
+- affected capabilities;
+- failed fixture ids;
+- latest route explanation references;
+- required owner review;
+- next action;
+- severity.
+
+## Boundary
+
+Health dashboards are evidence and control surfaces. They do not grant runtime
+authorization or canonical write permission.

package/standard/feedback-learning-gate.md

@@ -0,0 +1,101 @@
+# Feedback Learning Gate
+
+Status: alpha standard draft
+
+## Purpose
+
+This section defines how feedback can improve a Mirai Graph-modeled AI employee
+without allowing uncontrolled self-modification.
+
+## Core Flow
+
+```text
+feedback -> proposal -> replay/evaluation -> approval -> canonical graph update
+```
+
+## Feedback
+
+Feedback is an observation, review, correction, rating, error report or outcome
+signal.
+
+Feedback may come from:
+
+- a human reviewer;
+- an audited result;
+- a failed action;
+- a successful action;
+- a monitoring signal;
+- a peer AI employee;
+- an external evaluation.
+
+Feedback is evidence. It is not automatically a behavior change.
+
+## Learning Proposal
+
+A learning proposal describes what should change in the graph.
+
+It may propose:
+
+- updating a policy;
+- adding or changing a lesson;
+- changing a workflow;
+- changing a skill description;
+- adding a risk;
+- changing a delegation rule;
+- adding a new approval requirement.
+
+## Replay Or Evaluation
+
+Before acceptance, the proposal should be evaluated.
+
+Evaluation may include:
+
+- replaying the failed scenario;
+- comparing expected and actual result;
+- checking policy impact;
+- checking safety or public-release risk;
+- checking whether the lesson is too broad;
+- checking whether the change conflicts with existing graph state.
+
+## Approval
+
+Learning changes that affect future behavior should pass a governance gate.
+
+Examples:
+
+- `feedback_learning_before_behavior_update`;
+- `human_review_before_canonical_write`;
+- `public_safety_before_release`;
+- `approval_before_external_action`.
+
+## Canonical Update
+
+After approval, a canonical graph update may add, deprecate or change objects
+and relations.
+
+The update should preserve:
+
+- feedback evidence;
+- proposal id or source;
+- approval record;
+- affected object and relation ids;
+- limitation or rollback note when relevant.
+
+## Anti-Patterns
+
+- Treating every feedback item as a permanent lesson.
+- Letting a failed action automatically rewrite policy.
+- Updating behavior without preserving evidence.
+- Merging runtime logs directly into canonical memory.
+- Accepting broad lessons from one narrow example.
+
+## Claim Rule
+
+Passing through a feedback learning gate supports this limited claim:
+
+```text
+The behavior update was proposed, evaluated and accepted through a recorded
+governance process.
+```
+
+It does not prove the updated behavior is universally correct.