mirai-graph 1.4.0 → 2.1.0

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,215 +0,0 @@
-# Project Technology
-
-Status: 1.4 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.
-
-## Executable Technologies And Course Projections
-
-An executable technology is an accepted graph of reusable operations and
-user-facing scenarios. It is suitable for a long method that has both an
-end-to-end path and independently useful parts. Each operation binds its owner,
-capability, prerequisites, inputs, outputs, checks, stop conditions, rollback
-and exact raw source references.
-
-A scenario names an outcome and selects the operations needed to reach it.
-Project Technology calculates prerequisite closure, so a course or executor
-cannot silently omit a required safety step.
-
-```bash
-mirai-graph technology course compile . --technology graph/specs/technology.json
-mirai-graph technology course compile . --technology graph/specs/technology.json --scenario scenario.recovery
-mirai-graph technology course verify . --course-pack course-pack.json
-mirai-graph technology course reconcile . --course-pack course-pack.json --projection edited-course.json
-```
-
-The JavaScript API exposes `compileTechnologyCourse`,
-`verifyTechnologyCourse` and `reconcileTechnologyCourse`.
-
-A Course Pack is hash-bound to the normalized technology, chosen scenarios,
-sources and revisions. It may be rendered into a document, learning system or
-documentation site. It remains a projection: editorial changes may be routed
-to the documentation owner, while changed prerequisites, owners, checks, stop
-conditions, rollback or scope become semantic proposals. Reconciliation never
-writes them into the accepted technology automatically.
-
-## 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.

package/standard/projection-views.md

@@ -1,69 +0,0 @@
-# Projection Views
-
-Status: 1.0 release-candidate 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

@@ -1,49 +0,0 @@
-# Recovery And Resume
-
-Status: 1.0 release-candidate standard section
-
-## 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
-```