mirai-graph 1.3.0 → 2.1.0

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.

package/standard/technology-quality-feedback.md

@@ -1,97 +0,0 @@
-# Technology Quality Feedback
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Technology quality feedback checks whether completed work followed the declared
-technology, process or method before that work can be accepted, released or
-used as evidence for canonical change.
-
-It exists because passing tests, producing artifacts or collecting evidence can
-still hide process drift. A team needs a separate review loop that asks:
-
-```text
-Did the work follow the technology it claimed to follow?
-```
-
-## Core Pattern
-
-```text
-technology contract
--> work evidence
--> technology quality feedback
--> finding classification
--> transition decision
--> Kaizen / proposal / fix route
-```
-
-The feedback report is a gate artifact. It classifies findings and routes the
-next transition, but it does not execute actions or update canonical state.
-
-## Required Rules
-
-- Passing tests do not mean accepted work.
-- Evidence does not authorize release or canonical update.
-- Generated context and proposals do not mutate canonical state.
-- Every finding must be classified.
-- `process_improvement` findings route to Kaizen.
-- `spec_gap` findings route back to planning, human review or graph sync
-  proposal.
-- Blocking findings stop acceptance and release transitions.
-
-## Classifications
-
-Public Mirai Graph uses universal classifications:
-
-- `accepted`;
-- `work_fix_required`;
-- `test_gap`;
-- `spec_gap`;
-- `graph_update_proposal`;
-- `process_improvement`;
-- `release_blocker`;
-- `security_blocker`;
-- `defer_with_reason`.
-
-Domain adapters may map narrower terms to these values. For example, a
-software-code review adapter may map `code_fix_required` to
-`work_fix_required`.
-
-## Review Dimensions
-
-A feedback report should choose dimensions that match the technology being
-checked. Common dimensions include:
-
-- scope;
-- architecture;
-- ownership;
-- security;
-- runtime;
-- tests;
-- evidence;
-- graph_drift;
-- release;
-- process_adherence.
-
-## Transition Boundary
-
-Technology feedback can support a process transition such as `review_ready`,
-`accepted`, `approved` or `released`. It must not be treated as the transition
-itself.
-
-Significant work should enter acceptance or release states only when the
-process-control contract requires and receives a passing technology quality
-feedback report.
-
-## Schema
-
-Machine-readable feedback reports can be validated with:
-
-```text
-schemas/technology-quality-feedback.schema.json
-```
-
-The schema validates public shape, finding classification and boundary rules.
-It does not prove semantic correctness, production safety or scientific
-effectiveness.

package/standard/test-suite.md

@@ -1,159 +0,0 @@
-# Mirai Graph Test Suite
-
-Status: 1.2 stable standard section
-
-## Purpose
-
-The Mirai Graph test suite verifies that examples, packages and implementations
-follow the standard.
-
-The test suite should cover structure, conformance, context-pack generation,
-governance gates and benchmark reproducibility.
-
-## Current Smoke Tests
-
-Run:
-
-```bash
-npm test
-```
-
-Current checks:
-
-- validate minimal graph package;
-- validate synthetic benchmark graph package;
-- validate public profile manifests;
-- validate public pilot packages;
-- validate dynamic episode traces and reject unsafe trace semantics;
-- validate goal-vector quality-control reports and reject false-progress
-  semantics;
-- run deterministic seed preview;
-- generate benchmark context pack;
-- score benchmark readiness;
-- run synthetic context-reduction calculation;
-- reject negative fixtures.
-- verify deterministic Project Technology context traversal across project,
-  research, organization, platform, skill-like and multi-repository scopes;
-- reject incomplete mandatory closure, stale nodes, conflicts, cycles,
-  tampered digests, secret-like evidence and context-budget shortcuts.
-- verify portable continuity for Git and non-Git projects, two independent
-  installations, idempotent repeats, stale receipts, CAS conflicts, secret
-  rejection, bounded proposals and two-case method promotion.
-
-## Structural Validation
-
-Structural validation checks:
-
-- required object fields;
-- required relation fields;
-- unique object ids;
-- unique relation ids;
-- relation source/target references;
-- readiness values;
-- evidence arrays;
-- optional package manifest;
-- optional gate result records.
-
-## Profile Conformance
-
-Profile conformance checks:
-
-- package object kinds are allowed by `manifest.profile`;
-- package relation types are allowed by `manifest.profile`;
-- relation ids agree with source, type and target fields.
-
-Fixture guide:
-
-```text
-docs/adoption/profile-conformance-fixtures.md
-```
-
-Current validator:
-
-```bash
-node packages/cli/validate-mirai-graph.js <package-dir>
-```
-
-## Dynamic Episode Validation
-
-Dynamic episode validation checks:
-
-- event presence;
-- source refs;
-- activated objects, relations, policies, gates and technology steps;
-- selected path;
-- blocked paths;
-- finding classifications;
-- feedback classifications;
-- Kaizen route for process improvements;
-- replay/regression placeholders;
-- `canonical_write_allowed=false`;
-- absence of evidence-as-authorization language.
-
-Current commands:
-
-```bash
-npm run validate:dynamic-episodes
-npm run validate:dynamic-episode-report
-npm run test:dynamic-episodes-negative
-```
-
-## Goal Vector Quality Control Validation
-
-Goal-vector validation checks:
-
-- final outcome and start state presence;
-- visible vector segments and batch vector links;
-- evidence before completion claims;
-- reverse audit before pass verdicts;
-- rejection of tests-as-acceptance language;
-- correction routes for drift findings;
-- `canonical_write_allowed=false`;
-- public-safety boundaries.
-
-Current commands:
-
-```bash
-npm run validate:goal-vector-quality-control
-npm run test:goal-vector-quality-control-negative
-```
-
-## Benchmark Reproducibility
-
-Synthetic benchmark:
-
-```bash
-node benchmarks/synthetic-context-reduction-v0/scripts/calculate-context-reduction.js
-```
-
-Expected result:
-
-```text
-56.4516%
-```
-
-This test verifies arithmetic reproducibility only. It does not validate
-semantic completeness or real-world performance.
-
-## Future Tests
-
-Planned:
-
-- context-pack metadata validation;
-- context-pack evidence preservation;
-- governance gate result validation;
-- package manifest validation;
-- semantic completeness review fixture validation;
-- cross-package import/export tests.
-
-## Test Result Policy
-
-Every test result should state:
-
-- command;
-- expected output;
-- actual output;
-- verdict;
-- limitations.
-
-Do not convert a passing smoke test into a stronger scientific claim.

package/standard/work-state-machine.md

@@ -1,62 +0,0 @@
-# Work State Machine
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Work state machines define allowed movement through a governed work lifecycle.
-They prevent false promotion from planning readiness to execution, from written
-work to implemented state, or from proposal to canonical update.
-
-## Core States
-
-Typical state sequence:
-
-```text
-planned
--> launch_ready
--> prepared
--> ready_to_execute
--> started
--> written
--> tests_recorded
--> evidence_recorded
--> sync_proposed
--> review_ready
--> changes_requested
--> approved
--> release_ready
--> released
--> feedback_recorded
--> evolution_proposed
-```
-
-Exceptional states:
-
-- `blocked`
-- `paused`
-- `abandoned`
-- `superseded`
-- `reverted`
-- `recovered`
-
-## Critical Rules
-
-- `ready_to_execute` is not `started`.
-- `ready_to_code` is not `implemented`.
-- `written` is not accepted implementation state.
-- `tests_recorded` without semantic evidence is not review acceptance.
-- `sync_proposed` does not update canonical graph state.
-- invalid transitions fail closed.
-- transitions may require a launch record when they cross from planning into
-  executable work.
-- terminal states require a Kaizen review or an explicit no-reusable-lessons
-  reason when the process is significant.
-
-## Schema
-
-Machine-readable state machines can be validated with:
-
-```text
-schemas/work-state-machine.schema.json
-```

package/templates/README.md

@@ -1,77 +0,0 @@
-# Mirai Graph Templates
-
-Status: 1.0 release-candidate starter kit
-
-These templates are small public-safe starter packages. They are intentionally
-complete enough to validate, but small enough to copy into a new project and
-replace with real public or private sources.
-
-For the full role-oriented starter path, use the
-[1.0 RC Adopter Kit](../docs/adoption/adopter-kit.md).
-
-For self-service onboarding in a project, prefer:
-
-```bash
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-```
-
-`init` copies only starter graph package files. It does not overwrite project
-README files and refuses to replace existing graph files unless `--force` is
-passed.
-
-## Starters
-
-| Template | Profile | Use when |
-| --- | --- | --- |
-| `software-project-starter/` | `software_specification` | Starting from features, requirements, components, tasks and risks. |
-| `research-program-starter/` | `project_management` | Starting from hypotheses, evidence, milestones, review gates and publication risks. |
-| `ai-employee-starter/` | `ai_employee` | Modeling an AI worker with role, skill, tool, policy, action and feedback gates. |
-| `character-layer-starter/` | `character_layer` | Reusing behavior constitution, role character profiles, reflection and correction boundaries. |
-| `organization-governance-starter/` | `organization_governance` | Modeling mission, strategy, departments, programs, policies, controls and metrics. |
-
-## One-Day Adoption Path
-
-1. Choose the closest starter profile.
-2. Copy the template into your project.
-3. Replace synthetic object titles and summaries with your domain objects.
-4. Keep private notes, secrets, raw logs and internal handoffs outside the
-   public graph package.
-5. Run:
-
-```bash
-npm run validate:templates
-node packages/cli/validate-mirai-graph.js templates/<template-name>
-```
-
-6. Add launch records, process transitions and evidence packs only after the
-   graph package shape validates.
-
-## Adopter Workflow Commands
-
-List the role/profile/starter map:
-
-```bash
-node packages/cli/mirai-graph.js choose-profile
-```
-
-Print a plan for a role or profile:
-
-```bash
-node packages/cli/mirai-graph.js adopter plan organization
-node packages/cli/mirai-graph.js adopter plan ai_employee
-```
-
-Generate a readable report for a starter:
-
-```bash
-node packages/cli/mirai-graph.js adopter report templates/organization-governance-starter
-```
-
-## Boundary
-
-Templates are starter packages, not adoption proof. Passing validation means
-only that the package follows the current release-candidate schema/profile
-shape.

package/templates/ai-employee-starter/README.md

@@ -1,9 +0,0 @@
-# AI Employee Starter
-
-Use this template for a governed AI employee graph.
-
-Validate:
-
-```bash
-node packages/cli/validate-mirai-graph.js templates/ai-employee-starter
-```

package/templates/ai-employee-starter/gates/results.json

@@ -1,12 +0,0 @@
-[
-  {
-    "id": "gate_result.template_ai_employee.public_safety",
-    "gate_id": "gate.public_safety",
-    "target_id": "package.template_ai_employee",
-    "verdict": "pass",
-    "summary": "Template uses only synthetic AI employee content and no private runtime traces.",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "reviewed_at": "2026-06-03",
-    "reviewer": "Mirai Graph template validator"
-  }
-]

package/templates/ai-employee-starter/graph/objects.json

@@ -1,90 +0,0 @@
-[
-  {
-    "id": "ai_employee.research_assistant",
-    "kind": "ai_employee",
-    "title": "Research Assistant",
-    "summary": "Synthetic AI employee used to demonstrate governed capability and feedback boundaries.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "role.research_support",
-    "kind": "role",
-    "title": "Research Support",
-    "summary": "Role responsible for summarizing evidence and preparing review queues.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "skill.evidence_summary",
-    "kind": "skill",
-    "title": "Evidence Summary",
-    "summary": "Summarize source evidence without turning suggestions into canonical updates.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "tool.search_index",
-    "kind": "tool",
-    "title": "Search Index",
-    "summary": "Synthetic tool placeholder for finding reviewed public sources.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "policy.human_approval",
-    "kind": "policy",
-    "title": "Human Approval",
-    "summary": "External action and behavior updates require human approval.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "action.prepare_summary",
-    "kind": "action",
-    "title": "Prepare Summary",
-    "summary": "Prepare a reviewable summary, not a canonical update.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "feedback.review_note",
-    "kind": "feedback",
-    "title": "Review Note",
-    "summary": "Feedback may create a proposal but cannot directly update behavior.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "evidence.synthetic_role_brief",
-    "kind": "evidence",
-    "title": "Synthetic Role Brief",
-    "summary": "Public-safe placeholder evidence for the starter template.",
-    "readiness": "accepted",
-    "evidence": [],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  }
-]

package/templates/ai-employee-starter/graph/relations.json

@@ -1,47 +0,0 @@
-[
-  {
-    "id": "relation.ai_employee.research_assistant.has_role.role.research_support",
-    "type": "has_role",
-    "source": "ai_employee.research_assistant",
-    "target": "role.research_support",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.ai_employee.research_assistant.has_skill.skill.evidence_summary",
-    "type": "has_skill",
-    "source": "ai_employee.research_assistant",
-    "target": "skill.evidence_summary",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.skill.evidence_summary.requires_capability.tool.search_index",
-    "type": "requires_capability",
-    "source": "skill.evidence_summary",
-    "target": "tool.search_index",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.action.prepare_summary.requires_approval.policy.human_approval",
-    "type": "requires_approval",
-    "source": "action.prepare_summary",
-    "target": "policy.human_approval",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.feedback.review_note.updates_behavior.policy.human_approval",
-    "type": "updates_behavior",
-    "source": "feedback.review_note",
-    "target": "policy.human_approval",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  }
-]