mirai-graph 1.3.0 → 2.1.0

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`.

package/standard/profiles.md

@@ -1,253 +0,0 @@
-# Mirai Graph Profiles
-
-Status: 1.0 release-candidate standard section
-
-## 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.
-
-Before adding a profile, use [Profile Boundaries](profile-boundaries.md).
-Mirai Graph prefers extension of existing profiles before introducing new
-profile names.
-
-## Profile
-
-A profile is a named specialization of Mirai Graph.
-
-Release-candidate profiles:
-
-- `software_specification`;
-- `project_management`;
-- `implementation_control`;
-- `ai_employee`;
-- `character_layer`;
-- `skill_runtime`;
-- `organization_governance`.
-
-Proposal/experimental profiles:
-
-- `societal_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.
-- duplicate an existing profile with a more attractive name;
-- store bulk source content that belongs in source systems;
-- turn generated context, evidence, feedback or episode traces into
-  authorization.
-
-## 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.
-
-## New Profile Decision
-
-New profile ideas are `proposal_only` until they answer:
-
-1. What new behavior does this add?
-2. Which existing profiles were considered?
-3. Why is an extension not enough?
-4. How does it preserve Hybrid Source Of Truth?
-5. What validator, fixture, report, pilot or experiment can check it?
-6. Why is it needed now?
-
-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/project-technology.md

@@ -1,186 +0,0 @@
-# Project Technology
-
-Status: 1.3 stable standard; activation contract remains 1.0.0
-
-Project Technology is the shared executable mechanism of Mirai Graph. It is
-not a profile, a second graph or a source of domain methodology.
-
-## One Mechanism, Different Graphs
-
-The root `graph.json` declares the repository scope and profiles. The same
-Project Technology operations therefore work for:
-
-- an ordinary project;
-- a skill using `skill_runtime`;
-- a technology platform;
-- a federation or another multi-repository system.
-
-Each graph keeps its own objects and relations. Project Technology only
-standardizes safe inventory, task context, accepted-target binding, freshness
-and verification.
-
-## Immutable Artifact Releases
-
-Project Technology can preserve versioned file bundles without turning their
-contents into graph data:
-
-```text
-inspect -> release preview -> transactional release -> compare -> verify
-```
-
-The generic CLI is:
-
-```bash
-mirai-graph technology artifact inspect . --input incoming.zip
-mirai-graph technology artifact release . --input incoming.zip --matter-id agreement-main --direction inbound
-mirai-graph technology artifact release . --input incoming.zip --matter-id agreement-main --direction inbound --apply
-mirai-graph technology artifact compare . --matter-id agreement-main --base-release 20260828-01 --target-release 20260828-02
-mirai-graph technology artifact verify . --matter-id agreement-main --release-id 20260828-02
-```
-
-The programmatic API exposes `inspectArtifactBundle`,
-`createArtifactRelease`, `compareArtifactReleases` and
-`verifyArtifactRelease`.
-
-Each immutable release keeps the original input, a normalized package, a
-hash-bound manifest and a technical comparison. The portable registry at
-`graph/specs/artifact-releases.json` stores only opaque matter/release ids,
-relative or provider refs, lineage, state and digests. Raw files, document
-contents, party names and private discussion remain in the protected artifact
-store.
-
-Direct files, directories, ZIP, TAR and TAR.GZ are supported. Unsafe paths,
-links, encrypted archives, executable or macro-enabled files, nested archives,
-normalized path collisions and configured archive limits fail closed. RAR and
-7z need an explicitly supplied safe provider.
-
-Creation uses a lease, compare-and-swap registry digest, temporary assembly,
-atomic activation and readback. Repeating the same release returns
-`changed=false`. Domain consumers own the meaning of release states; Mirai
-Graph owns only generic identity, lineage, integrity and technical comparison.
-
-## Portable Project Continuity
-
-Project Technology preserves verified project experience at task boundaries:
-
-```text
-task context -> verified outcome -> semantic candidate -> graph/specs
-             -> next task context -> usage verification
-```
-
-`graph/specs` is the portable authority. Chat history and local workflow files
-are not required by another person or installation. Mutable receipts and
-rollback data are stored outside the project in a host-local directory keyed by
-`graph.id`.
-
-The existing `sync` operation accepts `task_start`, `stage_complete` and
-`task_complete`. Task start is read-only. A completed stage or task requires a
-verified, requirement-bound input and records accepted evidence plus one
-reusable regression case. New goals, architectural decisions and ownership
-changes remain proposals.
-
-Two independent verified cases with the same signature may promote a method
-lesson when they do not change architecture. Repeated input is byte-identical
-and returns `changed=false`. Shared folders without Git additionally use a
-lease, compare-and-swap graph digest, backup, atomic write and readback.
-
-## Sequential Context Traversal
-
-Project Technology exposes one model-independent navigation protocol:
-
-```text
-discover -> expand -> compile -> verify
-```
-
-- `discover` ranks a bounded set of top-level candidates for a task.
-- `expand` reveals the accepted children of one or more selected nodes.
-- `compile` validates the client's structured selection and adds the mandatory
-  closure over `requires`, `governed_by` and `validated_by`.
-- `verify` checks that the resulting sources and rules were connected to a
-  decision, a surface, a validator and an outcome.
-
-The caller may be a human, an AI model or a deterministic rule. Mirai Graph
-does not select or invoke a model. Sequential and batched expansion of the same
-nodes produces the same receipt digest.
-
-The universal relation vocabulary for traversal is:
-
-- structure: `contains`, `specializes`;
-- mandatory closure: `requires`, `governed_by`, `validated_by`;
-- sources: `documented_by`, `implemented_by`;
-- interaction: `hands_off_to`, `conflicts_with`.
-
-Consumer-specific names such as skills, companions or product commands are not
-part of this protocol. Consumers map their own domain vocabulary to ordinary
-owners, roles, capabilities, processes, resources, checks and access
-requirements.
-
-## Public Contract
-
-The only manifest extension key is `mirai.project_technology`:
-
-```json
-{
-  "contract_version": "1.0.0",
-  "enabled": true,
-  "context_policy": "task_scoped",
-  "source_boundary": "hybrid_sot",
-  "continuity_policy": "task_boundary"
-}
-```
-
-Canonical graph objects remain in `graph/specs`. Exact external revisions
-remain in `graph.lock.json`. Mutable continuity state is host-local and keyed
-by graph identity; project-local runtime directories are not continuity
-authority.
-
-The only generated provider artifact is:
-
-```text
-graph/generated/project-technology/target-provider-export.json
-```
-
-It contains target identity, exact provider revision, decision and goal
-references, Done When, requirements and acceptance references, constraints,
-non-goals, deferred boundaries, approved repository/owner/package/file/action
-scope, the accepted architecture boundary and a contract digest.
-
-The architecture boundary carries exact component, package and capability
-identities, ownership for data/access/lifecycle/interface/runtime, required and
-forbidden relations, and dependency constraints. This keeps an imported target
-executable without copying the provider's private source or full graph.
-
-## Hybrid Source Of Truth
-
-Project Technology may select graph objects and point to raw sources. It must
-not copy private source, complete documents, code or long owner methodology
-into the graph or provider export.
-
-The graph answers "what applies and where is the authority?". The raw owner
-source still answers "how should the domain work be done?".
-
-## Safety Rules
-
-- Read-only commands never write.
-- Changing commands return preview unless `--apply` is explicit.
-- Significant work fails closed when the target binding is missing, stale,
-  disabled, conflicting, incomplete or tampered.
-- Refresh-binding accepts only a forward provider revision with the same target,
-  semantic digest and complete execution-contract digest.
-- Repeated sync, connect or refresh produces `changed=false` when nothing
-  changed.
-- A blocked repository still supports narrow `explain`, `status`, `plan` and
-  diagnostic `verify` calls.
-- Context traversal is read-only in every phase and never grants write
-  authority.
-- Chat text, secrets, private source, user paths and unverified assumptions are
-  rejected from portable continuity.
-- Significant work with an enabled continuity policy fails closed when its
-  terminal receipt is missing or stale.
-- Artifact inspection, comparison and verification are read-only. Release
-  creation is preview-only without `--apply`.
-- An artifact manifest or generated export never proves legal, business or
-  domain acceptance.
-- A context pack is not ready while a required branch, source, access boundary
-  or validator is missing, stale, blocked, deprecated, conflicting or
-  digest-mismatched.