mirai-graph 1.0.0-rc.1

package/standard/object-model.md

@@ -0,0 +1,152 @@
+# Mirai Graph Object Model
+
+Status: initial public draft
+
+## Purpose
+
+The object model defines the stable entities that a Mirai Graph implementation
+tracks inside canonical graph state.
+
+Objects are not free-form notes. They are addressable units of system state
+that can be linked, evidenced, reviewed, matured and governed.
+
+## Object
+
+An object is a stable graph entity.
+
+Examples:
+
+- project;
+- product;
+- requirement;
+- feature;
+- decision;
+- risk;
+- task;
+- component;
+- policy;
+- stakeholder;
+- evidence item;
+- governance gate.
+
+## Minimum Fields
+
+A Mirai Graph object should include:
+
+```json
+{
+  "id": "object.unique_id",
+  "kind": "feature",
+  "title": "Short human-readable title",
+  "summary": "Brief description of the object",
+  "readiness": "draft",
+  "evidence": [],
+  "profile": "core",
+  "created_at": "2026-05-28",
+  "updated_at": "2026-05-28"
+}
+```
+
+## Field Semantics
+
+### `id`
+
+A stable unique identifier. The identifier should remain stable across file
+moves, generated context packs and implementation exports.
+
+### `kind`
+
+The object category. Core kinds should be standardized; profiles may add
+domain-specific kinds.
+
+### `title`
+
+A short label for humans.
+
+### `summary`
+
+A concise explanation of what the object represents.
+
+### `readiness`
+
+The maturity state of the object. Early values may include:
+
+- `draft`;
+- `review_ready`;
+- `accepted`;
+- `blocked`;
+- `deprecated`.
+
+### `evidence`
+
+References to evidence records or source materials. Evidence links should not
+embed private data directly in public examples.
+
+### `profile`
+
+The profile that defines or specializes the object. The default profile is
+`core`.
+
+### `created_at` And `updated_at`
+
+Dates or timestamps used for lifecycle tracking.
+
+## Core Object Kinds
+
+Initial core kinds:
+
+- `system`;
+- `goal`;
+- `requirement`;
+- `feature`;
+- `decision`;
+- `risk`;
+- `task`;
+- `component`;
+- `evidence`;
+- `context_pack`;
+- `governance_gate`;
+- `profile`.
+
+## Object Boundary Rules
+
+An object should be created when the item needs at least one of:
+
+- stable identity;
+- relations to other objects;
+- evidence;
+- readiness tracking;
+- governance control;
+- generated context inclusion;
+- reuse across tasks.
+
+An object should not be created for:
+
+- a one-off sentence with no reuse value;
+- raw private data copied without review;
+- generated AI text that has not been accepted into canonical state;
+- a vague idea with no boundary or owner.
+
+## Public Example
+
+```json
+{
+  "id": "feature.notify_after_approval",
+  "kind": "feature",
+  "title": "Notify after approval",
+  "summary": "Send a notification when a content item is approved.",
+  "readiness": "draft",
+  "evidence": ["source.content_workflow"],
+  "profile": "software_specification",
+  "created_at": "2026-05-28",
+  "updated_at": "2026-05-28"
+}
+```
+
+## Open Questions
+
+- Should `owner`, `status` and `readiness` be separate fields?
+- Should evidence be modeled as first-class objects only, or also as inline
+  references?
+- Which object kinds belong to `core` and which belong to profiles?
+- Should timestamps be ISO dates or full date-time strings?

package/standard/organization-governance.md

@@ -0,0 +1,84 @@
+# Organization Governance
+
+Status: alpha standard section
+
+## Purpose
+
+Organization governance extends Mirai Graph from project-level coordination to
+organization-level control. It describes how mission, strategy, portfolios,
+departments, policies, decision rights, risks, metrics, feedback and Kaizen can
+be connected without turning the graph into an unapproved command system.
+
+## Model
+
+```text
+mission
+-> strategy
+-> portfolio
+-> department/program/project
+-> policy and decision rights
+-> risk controls
+-> evidence and metrics
+-> feedback
+-> kaizen proposal
+-> governed update
+```
+
+The graph is the coordination surface. It records dependencies, boundaries and
+evidence. It does not itself authorize organizational action.
+
+## Core Concepts
+
+- `mission`: durable reason for the organization to exist.
+- `strategy`: selected direction for allocating attention and resources.
+- `portfolio`: grouped initiatives, products, programs or projects.
+- `department`: accountable organizational unit.
+- `decision_right`: explicit owner of a decision class.
+- `policy`: rule or constraint that governs decisions and actions.
+- `risk`: possible organizational failure mode.
+- `control`: preventive, detective or corrective measure.
+- `metric`: signal used to review progress or risk.
+- `feedback`: observed response from operations, users, teams or environment.
+- `kaizen_item`: proposed process or governance improvement.
+
+## Required Boundaries
+
+Organization-governance graphs must preserve these boundaries:
+
+- generated context is not canonical organizational state;
+- evidence is not authorization;
+- feedback is not an automatic policy update;
+- readiness is not execution;
+- decision rights must be explicit before policy or portfolio changes;
+- high-impact changes require evidence and owner approval.
+
+## Minimum Gates
+
+- strategy alignment before portfolio change;
+- decision-right review before policy change;
+- risk-control review before cross-department action;
+- evidence review before governance decision;
+- Kaizen review before process promotion.
+
+## Use Cases
+
+- align projects with organization strategy;
+- show which department owns which capability or policy;
+- make decision rights and escalation paths explicit;
+- connect risks to controls and evidence;
+- route feedback into reviewed Kaizen items;
+- prepare organization-level status or governance context packs.
+
+## Non-Goals
+
+This alpha section is not:
+
+- a legal governance framework;
+- a replacement for corporate bylaws, public law or audit requirements;
+- proof that Mirai Graph can govern a country-scale system;
+- an autonomous management system.
+
+## Example
+
+See [Organization Governance Minimal](../examples/organization-governance-minimal/README.md).
+

package/standard/process-control-contract.md

@@ -0,0 +1,53 @@
+# Process Control Contract
+
+Status: initial public standard note
+
+## Purpose
+
+A process-control contract binds implementation-control cycles to executable
+state machines, launch-record policy, evidence requirements, recovery behavior,
+risk controls, validators and Kaizen policy.
+
+It is the public Mirai Graph bridge between standards and fail-closed process
+validation.
+
+## Required Contract
+
+A process-control contract must define:
+
+- process id;
+- cycle id;
+- state machine id;
+- launch-record policy;
+- evidence requirements;
+- recovery behavior;
+- risk controls;
+- validators;
+- Kaizen policy;
+- technology quality feedback policy when significant work may move into
+  acceptance, approval or release states;
+- evidence references;
+- limitations.
+
+## Boundary
+
+The contract validates process movement. It must not execute destructive
+actions, grant release approval, perform canonical updates or treat generated
+context as authorization.
+
+Tests and evidence do not prove that the declared technology was followed. For
+significant work, the contract should require a technology quality feedback
+gate before transitions such as `review_ready`, `accepted`, `approved` or
+`released`.
+
+Technology quality feedback classifies process and work findings. It supports
+transition decisions, but it does not replace owner approval or canonical
+promotion.
+
+## Schema
+
+Machine-readable contracts can be validated with:
+
+```text
+schemas/process-control-contract.schema.json
+```

package/standard/profiles.md

@@ -0,0 +1,233 @@
+# Mirai Graph Profiles
+
+Status: initial public draft
+
+## Purpose
+
+Profiles adapt Mirai Graph to domains without changing the core standard.
+
+A profile may define additional object kinds, relation types, readiness rules,
+governance gates, examples and adoption guidance.
+
+## Profile
+
+A profile is a named specialization of Mirai Graph.
+
+Example profiles:
+
+- `core`;
+- `software_specification`;
+- `project_management`;
+- `implementation_control`;
+- `product_development`;
+- `organization_governance`;
+- `research_program`;
+- `human_ai_system`;
+- `ai_employee`;
+- `public_sector_governance`.
+
+## Profile Rules
+
+A profile may extend:
+
+- object kinds;
+- relation types;
+- evidence levels;
+- readiness policies;
+- governance gates;
+- examples;
+- validation fixtures.
+
+A profile should not:
+
+- override core semantics silently;
+- weaken public-safety rules;
+- claim conformance without tests;
+- mix private domain material into public examples.
+
+## Core Profile
+
+The `core` profile contains model elements expected across implementations:
+
+- stable objects;
+- typed relations;
+- evidence;
+- readiness;
+- generated context packs;
+- governance gates;
+- conformance levels.
+
+## Software Specification Profile
+
+Initial example profile used by the synthetic benchmark.
+
+Possible object kinds:
+
+- package;
+- feature;
+- requirement;
+- constraint;
+- risk;
+- component;
+- task;
+- evidence.
+
+Possible relation types:
+
+- implements;
+- depends_on;
+- blocks;
+- evidences;
+- generates;
+- related_to.
+
+## AI Employee Profile
+
+Initial alpha profile for modeling AI employees as governed runtimes over an
+evolutionary graph.
+
+Possible object kinds:
+
+- ai_employee;
+- ai_department;
+- role;
+- skill;
+- knowledge;
+- memory;
+- tool;
+- capability;
+- policy;
+- workflow;
+- action;
+- result;
+- feedback;
+- lesson;
+- governance_gate;
+- federation_endpoint.
+
+Possible relation types:
+
+- has_role;
+- has_skill;
+- uses_knowledge;
+- requires_capability;
+- can_execute;
+- requires_approval;
+- triggered_by;
+- responds_to;
+- learns_from;
+- updates_behavior;
+- belongs_to_department;
+- federates_with.
+
+## Skill Runtime Profile
+
+Initial alpha profile for modeling a governed skill, capability module or
+service as a Hybrid Source Of Truth runtime context.
+
+Possible object kinds:
+
+- skill;
+- capability;
+- activity;
+- rule;
+- owner_domain;
+- source_boundary;
+- raw_source;
+- runtime_context;
+- projection_view;
+- quality_gate;
+- adoption_report;
+- effectiveness_report;
+- semantic_review;
+- runtime_policy;
+- fallback;
+- handoff;
+- learning_proposal;
+- federation_contract.
+
+Possible relation types:
+
+- owns_domain;
+- has_capability;
+- supports_activity;
+- uses_rule;
+- requires_gate;
+- requires_fallback;
+- reads_source;
+- generates_context;
+- projects_view;
+- preserves_semantics;
+- measures_effectiveness;
+- routes_to;
+- hands_off_to;
+- exports_contract;
+- proposes_learning.
+
+## Implementation Control Profile
+
+Initial public profile for governing movement from graph baselines, generated
+human projections and implementation plans into bounded work, evidence, sync
+proposals, approval gates, controlled updates and process learning.
+
+Possible object kinds:
+
+- implementation_baseline;
+- projection_view;
+- semantic_review;
+- implementation_cycle;
+- graph_dna;
+- component_dna;
+- dna_alignment;
+- source_boundary_contract;
+- work_state_machine;
+- recovery_record;
+- risk_control;
+- coordination_contract;
+- workflow_batch;
+- launch_gate;
+- evidence_pack;
+- sync_proposal;
+- approval_gate;
+- controlled_update;
+- implementation_state;
+- drift_check;
+- kaizen_item.
+
+Possible relation types:
+
+- derives_projection;
+- reviews_projection;
+- aligns_with;
+- defines_boundary;
+- transitions_to;
+- resumes_from;
+- controls_risk;
+- reserves_scope;
+- requires_gate;
+- launches_batch;
+- produces_evidence;
+- proposes_update;
+- approves_update;
+- updates_baseline;
+- checks_drift;
+- progresses_to;
+- improves_process.
+
+## Profile Conformance
+
+Profile conformance should be declared separately from core conformance.
+
+Example:
+
+```text
+Core conformance: Level 1
+Profile conformance: software_specification Level 1
+```
+
+## Open Questions
+
+- Should profiles have machine-readable manifests?
+- Should profiles declare allowed object kinds and relation types?
+- Should profile validation be strict by default or advisory?
+- How should cross-profile conflicts be resolved?

package/standard/projection-views.md

@@ -0,0 +1,69 @@
+# Projection Views
+
+Status: alpha standard section
+
+## Purpose
+
+A full Mirai Graph can become too dense for direct human review. Projection views
+are bounded generated views that expose the part of the graph needed for a
+specific decision, task or review.
+
+Projection views are control surfaces. They help people and AI systems inspect
+readiness, risk, evidence and next actions without treating the generated view
+as the source of truth.
+
+## Common View Types
+
+- `readiness_view`: current readiness and blockers;
+- `risk_view`: risks, unsafe actions and required gates;
+- `owner_routing_view`: owner domains, capabilities and routing paths;
+- `evidence_view`: evidence coverage and unsupported claims;
+- `gate_view`: governance gates, verdicts and missing approvals;
+- `adoption_view`: Mirai Graph adoption level and next action;
+- `runtime_view`: runtime policy status, fallback and context refs;
+- `learning_view`: feedback, proposals, evaluations and approved updates.
+
+## Required Fields
+
+A projection view should record:
+
+- `id`;
+- `view_type`;
+- `source_graph`;
+- `generated_at`;
+- `purpose`;
+- `included_objects`;
+- `included_relations`;
+- `evidence`;
+- `limitations`;
+- `next_actions`.
+
+## Authority Boundary
+
+A projection view is generated context. It should not become canonical graph
+state unless an implementation explicitly records an approved update.
+
+Projection views may reveal gaps. They should not silently fill those gaps.
+
+## User Value
+
+Projection views are important because they make Mirai Graph usable for repeated
+management work:
+
+- what is ready;
+- what is blocked;
+- who owns the next step;
+- which evidence supports a claim;
+- which gate must happen before action;
+- what changed since the previous review.
+
+## Limited Claim
+
+A projection view supports this limited claim:
+
+```text
+The implementation generated a bounded, task-specific view from graph state.
+```
+
+It does not prove that the graph is complete or that the recommended action is
+safe to execute.

package/standard/recovery-resume.md

@@ -0,0 +1,49 @@
+# Recovery And Resume
+
+Status: initial public standard note
+
+## Purpose
+
+Recovery and resume rules make governed work resumable after interruption,
+context loss, failed commands, dirty worktrees, missing access or failed
+validation without relying on chat memory.
+
+## Resume Principle
+
+Resume from durable artifacts:
+
+- workflow or process record;
+- launch or reservation record;
+- branch and commit state;
+- validation result;
+- evidence pack;
+- sync proposal;
+- blockers;
+- next safe command;
+- rollback option.
+
+Do not resume by guessing from conversation history.
+
+## Required Resume Record
+
+A resume record should include:
+
+- current state;
+- last good commit or durable checkpoint;
+- current branch or workspace id;
+- target object or work scope;
+- launch/reservation reference;
+- last validation result;
+- evidence status;
+- blockers;
+- next safe command;
+- rollback option;
+- whether human confirmation is required.
+
+## Schema
+
+Machine-readable resume records can be validated with:
+
+```text
+schemas/recovery-resume-record.schema.json
+```