mirai-graph 1.0.0-rc.1

package/standard/relation-model.md

@@ -0,0 +1,139 @@
+# Mirai Graph Relation Model
+
+Status: initial public draft
+
+## Purpose
+
+The relation model defines typed links between Mirai Graph objects.
+
+Relations make system dependencies, evidence links, governance boundaries and
+growth paths explicit.
+
+## Relation
+
+A relation is a typed directional connection from one object to another.
+
+Example:
+
+```json
+{
+  "id": "relation.feature.notify_after_approval.depends_on.feature.approval_flow",
+  "type": "depends_on",
+  "source": "feature.notify_after_approval",
+  "target": "feature.approval_flow",
+  "readiness": "draft",
+  "evidence": ["source.notification_delivery"],
+  "profile": "software_specification"
+}
+```
+
+## Minimum Fields
+
+A Mirai Graph relation should include:
+
+```json
+{
+  "id": "relation.unique_id",
+  "type": "depends_on",
+  "source": "object.source_id",
+  "target": "object.target_id",
+  "readiness": "draft",
+  "evidence": [],
+  "profile": "core"
+}
+```
+
+## Field Semantics
+
+### `id`
+
+A stable identifier for the relation.
+
+### `type`
+
+The relation category. Core relation types should be standardized; profiles may
+add domain-specific relation types.
+
+### `source`
+
+The object where the directed relation starts.
+
+### `target`
+
+The object where the directed relation ends.
+
+### `readiness`
+
+The maturity state of the relation.
+
+### `evidence`
+
+Evidence supporting the relation.
+
+### `profile`
+
+The profile that defines or specializes the relation.
+
+## Core Relation Types
+
+Initial core relation types:
+
+- `depends_on`;
+- `supports`;
+- `blocks`;
+- `implements`;
+- `evidences`;
+- `contradicts`;
+- `governs`;
+- `requires_approval_from`;
+- `generates`;
+- `derived_from`;
+- `supersedes`;
+- `belongs_to`;
+- `related_to`.
+
+## Relation Boundary Rules
+
+A relation should be created when the connection changes how the system is
+understood, governed, implemented or evaluated.
+
+A relation should not be created when:
+
+- the link is merely decorative;
+- the relation type is unclear;
+- there is no source and target object;
+- it embeds a private source detail that should remain outside public graph
+  state;
+- it is generated but not accepted into canonical state.
+
+## Directionality
+
+Relations should be directional unless the relation type explicitly defines
+symmetry.
+
+Example:
+
+`feature.notify_after_approval depends_on feature.approval_flow`
+
+does not mean:
+
+`feature.approval_flow depends_on feature.notify_after_approval`
+
+## Evidence And Confidence
+
+The initial draft requires evidence links but does not yet define a confidence
+field. Future versions may add:
+
+- confidence;
+- review status;
+- reviewer;
+- source type;
+- extraction method.
+
+## Open Questions
+
+- Should relation confidence be required?
+- Should relation IDs be generated or human-authored?
+- Should `related_to` be allowed in mature canonical graphs, or only during
+  early graph-seed work?
+- How should contradictory relations be represented and resolved?

package/standard/risk-control-matrix.md

@@ -0,0 +1,53 @@
+# Risk Control Matrix
+
+Status: initial public standard note
+
+## Purpose
+
+A risk control matrix maps known risks to detection signals, prevention
+mechanisms, gates, evidence requirements, recovery actions, escalation rules
+and owner roles.
+
+It is designed for graph-governed projects where AI-assisted or multi-agent work
+can otherwise create false readiness, source-of-truth drift, unsafe runtime
+behavior or conflicting changes.
+
+## Required Shape
+
+Every risk row should include:
+
+- risk id and description;
+- severity;
+- detection signal;
+- prevention mechanism;
+- gate or validator;
+- evidence requirement;
+- recovery action;
+- escalation rule;
+- owner role.
+
+## Severity Model
+
+- `critical`: can compromise safety, source of truth, ownership or release.
+- `high`: can break architecture, boundaries or implementation claims.
+- `medium`: can cause rework, stale planning or evidence gaps.
+- `low`: can confuse review without blocking work by itself.
+
+## Default Recovery Pattern
+
+```text
+stop writes
+-> capture current state
+-> identify last good checkpoint
+-> classify risk
+-> restore scope or evidence
+-> escalate if ownership is unclear
+```
+
+## Schema
+
+Machine-readable risk matrices can be validated with:
+
+```text
+schemas/risk-control-matrix.schema.json
+```

package/standard/route-explanation.md

@@ -0,0 +1,35 @@
+# Route Explanation
+
+Status: alpha standard section
+
+## Purpose
+
+A route explanation records why a graph-managed federation selected a primary
+owner, companion capabilities, gates and fallbacks for a request.
+
+It is meant to make routing auditable before any runtime action starts.
+
+## Required Meaning
+
+A route explanation should include:
+
+- request summary;
+- primary owner;
+- companion capabilities;
+- rejected nearby candidates with reasons;
+- required gates;
+- required raw-source fallbacks;
+- route execution evidence reference;
+- confidence and known gaps;
+- runtime preflight reference when the route is high-risk.
+
+## Boundary
+
+Route explanation is not authorization.
+
+```text
+explained route != permission to execute
+explained route != permission to rewrite canonical sources
+```
+
+High-risk routes should link to a runtime preflight result before execution.

package/standard/route-regression.md

@@ -0,0 +1,33 @@
+# Route Regression
+
+Status: alpha standard section
+
+## Purpose
+
+Route regression compares router behavior before and after a learning proposal,
+router update or federation graph change.
+
+## Result Shape
+
+A route regression result should include:
+
+- before route result reference;
+- after route result reference;
+- diff summary;
+- per-fixture route diffs;
+- regression status.
+
+Recommended statuses:
+
+```text
+improved
+unchanged
+regressed
+blocked
+insufficient_evidence
+```
+
+## Boundary
+
+Route regression is evidence for review. It does not prove semantic completeness
+or authorize graph-only runtime.

package/standard/routing-fixtures.md

@@ -0,0 +1,54 @@
+# Routing Fixtures
+
+Status: alpha standard section
+
+## Purpose
+
+Routing fixtures test whether a graph-managed router selects the expected
+owner, companions, gates and fallback behavior for known scenarios.
+
+They are especially useful for negative routing cases where a nearby generic
+owner would be unsafe.
+
+## Negative Fixtures
+
+Fixtures should cover routes that must not collapse into a simpler route:
+
+- production or live infrastructure;
+- customer-visible writes;
+- credentials, secrets or private data;
+- legal, commercial or scientific claims;
+- owner-source rewrites;
+- platform architecture or migration decisions.
+
+## Forbidden Route Shapes
+
+Use `forbidden_route_shapes` when a skill can be a valid primary owner but
+must not be selected alone.
+
+Example:
+
+```json
+{
+  "primary_skill": "generic_development",
+  "without_companions": ["operations", "qa"],
+  "reason": "Production deployment requires runtime and acceptance gates."
+}
+```
+
+## Boundary
+
+Fixture evidence may support learning proposals. It must not directly rewrite
+source-of-truth files.
+
+## Evidence
+
+A fixture run should preserve one evidence pack per fixture:
+
+- parsed route result;
+- execution evidence with command, working directory, exit code and output
+  hashes;
+- stdout/stderr references;
+- route explanation reference for high-risk routes.
+
+High-risk fixtures should fail when the route explanation is missing.

package/standard/runtime-enablement.md

@@ -0,0 +1,85 @@
+# Runtime Enablement
+
+Status: alpha standard section
+
+## Purpose
+
+Mirai Graph can generate context for humans, agents and software runtimes. Runtime
+enablement defines when graph-mode may be used as the primary context layer for
+a specific task.
+
+This section generalizes the boundary:
+
+```text
+generated context != authorization
+runtime decision != executed action
+feedback != canonical update
+```
+
+## Runtime Question
+
+The runtime gate answers one narrow question:
+
+```text
+Can this specific task use graph-mode as the primary context layer?
+```
+
+It does not answer whether the task should be executed, whether the graph should
+be rewritten, or whether the generated context is complete.
+
+## Runtime Modes
+
+- `blocked`: graph-mode must not be used for the task.
+- `fallback_required`: graph-mode may help, but raw sources, runbooks or
+  approvals are mandatory.
+- `graph_context_allowed`: graph-mode can be the primary context for the
+  declared measured scope.
+- `no_match`: no policy covers the requested task.
+
+## Safe Defaults
+
+Implementations should use these defaults:
+
+- compact context first;
+- broader context only when justified by evidence;
+- no canonical writes through runtime policy;
+- raw-source fallback for sensitive work;
+- gap recording when graph coverage is missing.
+
+## Mandatory Fallback Triggers
+
+Fallback should be required for:
+
+- unmeasured scenarios;
+- destructive actions;
+- production or live infrastructure;
+- credentials, secrets or private data;
+- legal, commercial or financial risk;
+- customer-visible writes;
+- irreversible changes;
+- safety-critical operations.
+
+## Runtime Preflight
+
+A runtime preflight artifact should include:
+
+- task;
+- target object or profile;
+- selected context profile;
+- status;
+- required fallbacks;
+- blocking gaps;
+- generated context references;
+- raw source references that must still be read;
+- limitations.
+
+## Limited Claim
+
+Passing a runtime enablement gate supports this limited claim:
+
+```text
+Graph-mode may be used as the primary context layer for the declared task and
+scope, subject to recorded fallbacks and limitations.
+```
+
+It does not authorize execution or canonical graph updates.

package/standard/source-boundary-contract.md

@@ -0,0 +1,49 @@
+# Source Boundary Contract
+
+Status: initial public standard note
+
+## Purpose
+
+Source boundary contracts define which repository or graph areas are canonical,
+generated, curated for human review, evidence, workflow records, legacy context,
+tooling or local scratch.
+
+They prevent generated artifacts, review notes or implementation repositories
+from silently becoming source of truth.
+
+## Source Roles
+
+- `canonical`: reviewed source-of-truth data or rules.
+- `generated`: reproducible output from canonical or evidence sources.
+- `curated_human`: reviewed human-readable projection or explanation.
+- `workflow`: process, planning, launch, recovery or coordination record.
+- `evidence`: reviewed support material for a claim.
+- `legacy`: historical material preserved for traceability.
+- `tooling`: validators, generators, schemas or support scripts.
+- `local_scratch`: ignored local intake or temporary workspace.
+
+## Synchronization Flow
+
+```text
+canonical sources
+-> tooling
+-> generated and curated views
+-> human review or implementation planning
+-> accepted proposals
+-> canonical update
+-> regenerated views
+```
+
+## Promotion Rule
+
+If generated output, human review, workflow records or evidence contain a new
+important fact, that fact must be promoted through an explicit proposal before
+it becomes canonical state.
+
+## Schema
+
+Machine-readable source boundary contracts can be validated with:
+
+```text
+schemas/source-boundary-contract.schema.json
+```

package/standard/standard-v0.1.md

@@ -0,0 +1,132 @@
+# Mirai Graph Standard v0.1 Draft
+
+Status: initial public draft
+
+## Purpose
+
+This document defines the first public draft of the Mirai Graph standard: an
+implementation-independent graph operating model for managing the growth of
+complex systems.
+
+The draft is intentionally incomplete. It establishes the core sections,
+normative direction and conformance path for future implementation pilots.
+
+## Normative Language
+
+This draft uses plain language. Future versions may adopt RFC-style terms such
+as `MUST`, `SHOULD` and `MAY` after the object, relation and conformance models
+are stable.
+
+## Standard Scope
+
+Mirai Graph standardizes:
+
+- canonical graph state;
+- object identity and object kinds;
+- typed relations;
+- evidence and provenance;
+- readiness and lifecycle state;
+- generated context packs;
+- profiles;
+- governance gates;
+- conformance levels;
+- validation fixtures.
+
+## Non-Scope
+
+Mirai Graph does not standardize:
+
+- one database engine;
+- one programming language;
+- one UI;
+- one AI-agent framework;
+- one organizational management methodology;
+- private project data;
+- claims of universal validity.
+
+## Core Model
+
+A Mirai Graph implementation maintains a canonical graph state and can generate
+task-specific context packs from that state.
+
+The canonical graph state contains:
+
+- objects;
+- relations;
+- evidence links;
+- readiness/lifecycle fields;
+- profile metadata;
+- governance records where applicable.
+
+A generated context pack is a temporary, task-specific view. It helps a human
+or AI system act with relevant context, but it is not the source of truth.
+
+## Required Standard Sections
+
+The public standard is expected to contain:
+
+- [Object Model](object-model.md)
+- [Relation Model](relation-model.md)
+- [Graph DNA](graph-dna.md)
+- [Graph Seed](graph-seed.md)
+- [Graph Embryo](graph-embryo.md)
+- [Lifecycle And Readiness](lifecycle-readiness.md)
+- [Evidence And Provenance](evidence-provenance.md)
+- `context-pack-generation.md`
+- [Governance](governance.md)
+- [Hybrid Source Of Truth](hybrid-source-of-truth.md)
+- [Adoption Levels](adoption-levels.md)
+- [Projection Views](projection-views.md)
+- [Runtime Enablement](runtime-enablement.md)
+- [Graph As AI Brain](graph-as-ai-brain.md)
+- [Action Runtime Boundary](action-runtime-boundary.md)
+- [Feedback Learning Gate](feedback-learning-gate.md)
+- [Profiles](profiles.md)
+- [Conformance Levels](conformance-levels.md)
+- [Test Suite](test-suite.md)
+
+Only the first sections are drafted in this initial public batch.
+
+## Minimum Implementation Idea
+
+A minimal Mirai Graph package should be able to represent:
+
+1. A set of stable objects.
+2. Typed relations between those objects.
+3. Evidence references for important claims.
+4. Readiness state for objects or decisions.
+5. A generated context pack for one task.
+6. A boundary between canonical state and generated context.
+
+## Conformance Direction
+
+Future conformance levels:
+
+- Level 0: terminology alignment;
+- Level 1: canonical graph state;
+- Level 2: context-pack generation;
+- Level 3: governance-gated operation;
+- Level 4: profiled multi-domain operation.
+
+Conformance must be testable with schemas, fixtures and examples.
+
+## Current Readiness
+
+Verdict: `not_standard_ready`
+
+Reason:
+
+The repository now contains the public foundation, terminology, initial object
+model, initial relation model, lifecycle/readiness, evidence/provenance,
+graph DNA, graph seed, graph embryo, context-pack generation, profiles,
+governance, Hybrid Source Of Truth, adoption levels, projection views,
+runtime enablement, conformance levels, test-suite direction, initial schemas,
+a validator, a minimal example and a synthetic benchmark.
+
+Next required sections:
+
+1. CLI seed preview and embryo generation;
+2. stricter context-pack schema;
+3. profile manifest schema;
+4. richer negative fixtures;
+5. independent implementation pilot.

package/standard/technology-quality-feedback.md

@@ -0,0 +1,97 @@
+# Technology Quality Feedback
+
+Status: initial public standard note
+
+## Purpose
+
+Technology quality feedback checks whether completed work followed the declared
+technology, process or method before that work can be accepted, released or
+used as evidence for canonical change.
+
+It exists because passing tests, producing artifacts or collecting evidence can
+still hide process drift. A team needs a separate review loop that asks:
+
+```text
+Did the work follow the technology it claimed to follow?
+```
+
+## Core Pattern
+
+```text
+technology contract
+-> work evidence
+-> technology quality feedback
+-> finding classification
+-> transition decision
+-> Kaizen / proposal / fix route
+```
+
+The feedback report is a gate artifact. It classifies findings and routes the
+next transition, but it does not execute actions or update canonical state.
+
+## Required Rules
+
+- Passing tests do not mean accepted work.
+- Evidence does not authorize release or canonical update.
+- Generated context and proposals do not mutate canonical state.
+- Every finding must be classified.
+- `process_improvement` findings route to Kaizen.
+- `spec_gap` findings route back to planning, human review or graph sync
+  proposal.
+- Blocking findings stop acceptance and release transitions.
+
+## Classifications
+
+Public Mirai Graph uses universal classifications:
+
+- `accepted`;
+- `work_fix_required`;
+- `test_gap`;
+- `spec_gap`;
+- `graph_update_proposal`;
+- `process_improvement`;
+- `release_blocker`;
+- `security_blocker`;
+- `defer_with_reason`.
+
+Domain adapters may map narrower terms to these values. For example, a
+software-code review adapter may map `code_fix_required` to
+`work_fix_required`.
+
+## Review Dimensions
+
+A feedback report should choose dimensions that match the technology being
+checked. Common dimensions include:
+
+- scope;
+- architecture;
+- ownership;
+- security;
+- runtime;
+- tests;
+- evidence;
+- graph_drift;
+- release;
+- process_adherence.
+
+## Transition Boundary
+
+Technology feedback can support a process transition such as `review_ready`,
+`accepted`, `approved` or `released`. It must not be treated as the transition
+itself.
+
+Significant work should enter acceptance or release states only when the
+process-control contract requires and receives a passing technology quality
+feedback report.
+
+## Schema
+
+Machine-readable feedback reports can be validated with:
+
+```text
+schemas/technology-quality-feedback.schema.json
+```
+
+The schema validates public shape, finding classification and boundary rules.
+It does not prove semantic correctness, production safety or scientific
+effectiveness.