mirai-graph 1.4.0 → 2.1.0

package/standard/object-model.md

@@ -1,167 +0,0 @@
-# Mirai Graph Object Model
-
-Status: 1.1 stable standard section
-
-## 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`;
-- `owner`, `role`;
-- `capability`, `process`;
-- `resource`, `source`;
-- `check`, `gate`, `constraint`;
-- `access_requirement`.
-- `project_dna`, `stage`, `batch`;
-- `method`, `lesson`, `regression_case`.
-
-The additional domain-neutral kinds support Project Technology traversal. A
-consumer may display them using its own vocabulary without changing their
-canonical meaning.
-
-Portable continuity uses these existing domain-neutral kinds. A verified task
-result is evidence plus a regression case; an inferred reusable method remains
-a lesson proposal until its promotion rule is satisfied.
-
-## 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

@@ -1,83 +0,0 @@
-# Organization Governance
-
-Status: 1.0 release-candidate 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

@@ -1,53 +0,0 @@
-# Process Control Contract
-
-Status: 1.0 release-candidate standard section
-
-## 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/profile-boundaries.md

@@ -1,225 +0,0 @@
-# Profile Boundaries
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Mirai Graph uses profiles and layers to keep graph-governed work understandable.
-This document defines how those profiles fit together and how to decide whether
-a new idea should become a new profile, an extension of an existing profile, a
-validator rule, a proposal or no change.
-
-The goal is to protect Mirai Graph from abstraction creep. A useful standard
-does not add a new layer for every useful concept. It adds structure only when
-the structure changes behavior in a way that can be validated.
-
-## Layer Map
-
-Mirai Graph layers should be read from source to action:
-
-```text
-source systems
--> core graph model
--> domain profiles
--> project and governance control
--> implementation/process control
--> technology quality feedback
--> dynamic episode evidence
--> Kaizen and proposal loops
--> AI employee / skill runtime use
-```
-
-Each layer answers a different question.
-
-| Layer | Question it answers | What it should contain | What it should not contain |
-| --- | --- | --- | --- |
-| Source systems | Where does the full truth live? | Files, docs, code, CMS, DB, tickets, workflow, raw evidence | Duplicate bulk content in graph state |
-| Core graph model | What exists and how is it connected? | Objects, relations, evidence refs, readiness, governance boundaries | Domain-specific workflow semantics |
-| Domain profiles | What type of system is this? | Profile-specific object kinds, relation types, examples, conformance rules | Everything from every other profile |
-| Project/governance control | What are we trying to move and who owns it? | Goals, decisions, risks, roles, policies, metrics, responsibilities | Runtime event traces |
-| Implementation/process control | How is work allowed to move? | Launch records, states, transitions, gates, evidence requirements | Business meaning that belongs in a domain profile |
-| Technology quality feedback | Did work follow the approved technology? | Classified findings, blocking/non-blocking verdicts, routes to fix or Kaizen | General testing claims without process conformance |
-| Dynamic episode evidence | What happened in this specific event and why? | Trigger, activated objects, selected path, blocked alternatives, evidence, feedback route | Authorization or canonical graph mutation |
-| Kaizen/proposal loops | What should improve? | Lessons, process improvements, graph proposals, follow-up routes | Automatic canonical updates |
-| AI employee / skill runtime | Who or what uses the graph at runtime? | Roles, skills, tools, policies, context, fallback, runtime contracts | Source-of-truth replacement for owner methods |
-
-## Current Status Classes
-
-Mirai Graph documents and profiles should make their status visible:
-
-- `core`: part of the release-candidate standard and expected to remain stable.
-- `release-candidate profile`: validated public profile for adopter use.
-- `proposal`: public-safe design direction that is not yet core.
-- `experimental`: validated or documented exploration that still requires
-  stronger evidence, replay/regression or adopter feedback.
-- `private pilot evidence`: internal or private evidence that must not be
-  copied into public examples without approval and sanitization.
-
-## Current Profile Boundaries
-
-| Profile or layer | Owns | Does not own |
-| --- | --- | --- |
-| `software_specification` | Requirements, features, components, dependencies, implementation traceability | Project governance, AI worker behavior, process authorization |
-| `project_management` | Goals, stages, tasks, decisions, risks, metrics, evidence and delivery movement | Detailed software object semantics or runtime event traces |
-| `implementation_control` | Launch records, work states, transitions, evidence, approval, drift, recovery and controlled update | Domain facts that belong to software, AI employee or organization profiles |
-| `technology_quality_feedback` | Whether the declared work technology was followed and how findings are routed | Unit-test success by itself, general acceptance, or release authorization |
-| `dynamic_episode_layer` | What happened in a concrete event, why a path was selected and which alternatives were blocked | Canonical updates, permissions or durable source-of-truth content |
-| `goal_vector_quality_control` | Extension contract for checking whether work advances a visible final-outcome vector and passes reverse audit | Authorization, release approval, production permission or a new core profile |
-| `ai_employee` | AI worker model: role, skill, tools, policy, actions, results, feedback and lessons | Model-independent character principles or organization-wide governance |
-| `character_layer` | Stable behavior governance independent of model backend | Tool permissions, runtime authorization or employee memory store |
-| `skill_runtime` | Hybrid SOT runtime context for skills, fallback and federation contracts | Rewriting owner skill methodology as graph-only runtime |
-| `organization_governance` | Departments, responsibility, policies, controls, strategy, programs, metrics and organization-scale feedback | Country-scale civic governance as a core 1.0 claim |
-| `societal_governance` | Proposal/experimental public governance modeling | Core 1.0 release-candidate conformance |
-
-`mirai.project_technology` is an extension shared by `project_management`,
-`implementation_control` and `skill_runtime`. It executes inventory, context,
-target binding and verification. It does not add another profile or take
-ownership of any profile's domain objects.
-
-## Extension Before Profile
-
-Use this sequence before creating a new profile:
-
-```text
-existing field
--> existing object or relation
--> validator or gate rule
--> synthetic example
--> proposal document
--> new profile only if existing profiles cannot express the behavior
-```
-
-A new profile is justified only when all are true:
-
-- it adds new verifiable behavior, not just a new name;
-- it does not duplicate an existing profile;
-- it strengthens Hybrid SOT;
-- it helps make a decision, gate, transition, feedback route, audit,
-  replay/regression result or Kaizen improvement;
-- it can be checked by a validator, fixture, report, pilot or experiment;
-- it is needed now, not merely interesting.
-
-If those conditions are not met, keep the idea as `proposal`, `experimental`,
-`extension_only` or `reject`.
-
-## Anti-RAG And Anti-Bulk-Content Boundary
-
-Mirai Graph is not a RAG index, CMS, search engine or bulk document store.
-
-Source systems keep full content:
-
-- files and documentation;
-- source code;
-- CMS records;
-- database records;
-- tickets, issues and workflow files;
-- search and vector indexes when a product needs them.
-
-Canonical graph state should keep only governable meaning:
-
-- stable object ids;
-- typed relations;
-- short summaries;
-- source and evidence references;
-- readiness and lifecycle state;
-- owner and responsibility links;
-- rules, constraints and gates;
-- transition, feedback, episode, replay and Kaizen metadata.
-
-This keeps graph packages small, reviewable and source-owned. If an application
-needs full-text search or semantic retrieval, use a search/index layer and let
-Mirai Graph enrich it with status, evidence, validity, ownership, gates and
-relations.
-
-## Practical Scenarios
-
-### Projects
-
-Use:
-
-```text
-project_management
-+ implementation_control
-+ technology_quality_feedback
-+ dynamic_episode_layer when action traceability matters
-```
-
-The graph should show where goals, decisions, risks, evidence and process
-states live. It should not store every project document body.
-
-### AI Employees
-
-Use:
-
-```text
-ai_employee
-+ character_layer
-+ implementation_control
-+ technology_quality_feedback
-+ dynamic_episode_layer
-```
-
-The graph should govern role, tools, policies, behavior, actions and feedback.
-It should not make generated context or character profiles into authorization.
-
-### Skills
-
-Use:
-
-```text
-skill_runtime
-+ source-boundary contract
-+ process-control gates
-+ federation evidence/proposals
-```
-
-The graph should route skills, expose runtime context and preserve Hybrid SOT.
-Raw skill sources remain authoritative for methodology and judgment.
-
-### Organizations
-
-Use:
-
-```text
-organization_governance
-+ project_management
-+ implementation_control
-+ technology_quality_feedback
-+ dynamic_episode_layer for important events
-```
-
-The graph should model responsibility, policy, controls, metrics, decisions and
-feedback. It should not jump directly to state/country-scale claims without
-organization-level evidence.
-
-## Refactoring Policy
-
-When profiles overlap, prefer boundary clarification over schema churn.
-
-Safe refactoring:
-
-- improve profile documentation;
-- add examples and anti-examples;
-- add validator warnings;
-- add adoption guidance;
-- mark proposal/experimental status explicitly.
-
-Risky refactoring:
-
-- rename object kinds without migration;
-- merge profiles with different owners;
-- move source content into graph state;
-- treat episode/evidence/proposals as authorization;
-- claim scientific or production proof from synthetic fixtures.
-
-## Minimum Review For New Ideas
-
-Every new profile/layer proposal should include:
-
-- problem statement;
-- existing profiles considered;
-- new behavior that existing profiles cannot express;
-- Hybrid SOT impact;
-- validation or pilot plan;
-- public/private boundary;
-- decision: `accept`, `revise`, `extension_only`, `proposal_only` or `reject`.