mirai-graph 1.4.0 → 2.1.0

package/standard/relation-model.md

@@ -1,149 +0,0 @@
-# Mirai Graph Relation Model
-
-Status: 1.1 stable standard section
-
-## 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`.
-
-Project Technology context traversal also standardizes:
-
-- structure: `contains`, `specializes`;
-- mandatory closure: `requires`, `governed_by`, `validated_by`;
-- sources: `documented_by`, `implemented_by`;
-- interaction: `hands_off_to`, `conflicts_with`.
-
-These names are domain-neutral. A consumer may present them with its own user
-vocabulary, but canonical traversal uses the shared relation types.
-
-## 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

@@ -1,53 +0,0 @@
-# Risk Control Matrix
-
-Status: 1.0 release-candidate standard section
-
-## 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

@@ -1,35 +0,0 @@
-# Route Explanation
-
-Status: 1.0 release-candidate 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

@@ -1,33 +0,0 @@
-# Route Regression
-
-Status: 1.0 release-candidate 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

@@ -1,54 +0,0 @@
-# Routing Fixtures
-
-Status: 1.0 release-candidate 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

@@ -1,85 +0,0 @@
-# Runtime Enablement
-
-Status: 1.0 release-candidate 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/semantic-intent-resolution.md

@@ -1,91 +0,0 @@
-# Semantic Intent Resolution
-
-Status: 1.0 release-candidate extension contract
-
-## Purpose
-
-Semantic Intent Resolution is an input-control contract for turning a free-form
-human request into a governed work decision before execution starts.
-
-It answers:
-
-- what the user likely wants;
-- what scale the work has;
-- which process and owner should handle it;
-- what context is missing;
-- whether execution can start;
-- which gates and evidence are required.
-
-This is not a standalone Mirai Graph profile. It is an extension contract that
-composes existing project, implementation, AI employee, technology feedback and
-dynamic episode layers.
-
-## Control Pattern
-
-```text
-request
--> intent hypothesis
--> work scale
--> owner/process decision
--> context-slot check
--> clarification, brief, workflow restore or safe execution
--> process control
--> evidence, episode trace and technology quality feedback
-```
-
-## Boundary
-
-Semantic Intent Resolution does not authorize action.
-
-```text
-semantic confidence != approval
-generated brief != authorization
-proposal != canonical update
-episode trace != permission to execute
-```
-
-High confidence in a route or intent still cannot bypass policy, approval,
-security, live-operation, data-mutation, Git-history or destructive-action
-gates.
-
-## Required Fields
-
-- `user_request`
-- `intent_hypothesis`
-- `confidence`
-- `work_scale`
-- `selected_chain_id`
-- `process_model_id`
-- `owner_role`
-- `required_context_slots`
-- `missing_context_slots`
-- `safe_default_action`
-- `execution_allowed`
-- `evidence_requirements`
-
-## Decision Rules
-
-- Low confidence blocks execution and requires review.
-- Missing required context for significant work blocks execution or creates a
-  clarification/brief path.
-- Track-level work must not be collapsed into one batch.
-- Goal-level work requires goal evidence such as Done When, stages, batches,
-  gates or evidence plan.
-- Risky work requires the relevant gates even when intent confidence is high.
-- Generated outputs do not update canonical graph state.
-
-## Integration Points
-
-- `project_management`: classifies work scale and track/goal/batch boundary.
-- `implementation_control`: decides readiness before execution.
-- `ai_employee`: selects role, owner and action boundary.
-- `technology_quality_feedback`: checks whether intake followed the approved
-  work technology.
-- `dynamic_episode_layer`: records why a path was selected, blocked or
-  clarified.
-
-## Public Safety
-
-Public examples must be synthetic. Do not publish private requests, customer
-messages, runtime traces, internal handoff payloads, access details, tokens,
-private policies or raw logs.

package/standard/source-boundary-contract.md

@@ -1,49 +0,0 @@
-# Source Boundary Contract
-
-Status: 1.0 release-candidate standard section
-
-## 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

@@ -1,132 +0,0 @@
-# Mirai Graph Standard v0.1 Draft
-
-Status: historical v0.1 standard 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.