mirai-graph 1.3.0 → 2.1.0

package/docs/adoption/adopter-kit.md

@@ -1,187 +0,0 @@
-# Mirai Graph 1.0 RC Adopter Kit
-
-Status: 1.0 release-candidate adoption kit
-
-This kit is the shortest public path from "I want to try Mirai Graph" to a
-validated local graph package. It is intentionally CLI-first and works through
-the published `mirai-graph` package or a repository checkout.
-
-## What This Kit Gives You
-
-- A role-to-profile map.
-- Starter templates for common adoption paths.
-- A validation sequence that catches schema, profile and process mistakes.
-- A minimal operating loop from graph seed to evidence and feedback.
-- Safety boundaries for private data, generated context and canonical updates.
-
-It does not prove that a project is correct, complete or scientifically
-validated. It proves that the adopter has a structured, reviewable starting
-package that follows the current 1.0 release-candidate shape.
-
-## Start By Role
-
-| Role | Start with | Template | Main checks |
-| --- | --- | --- | --- |
-| Developer | `software_specification` | `templates/software-project-starter/` | package validation, process transition, technology feedback |
-| Researcher | `project_management` | `templates/research-program-starter/` | seed validation, evidence boundaries, reproducibility notes |
-| AI product team | `ai_employee` | `templates/ai-employee-starter/` | role/skill/tool/policy graph, approval gates, feedback |
-| Behavior governance | `character_layer` | `templates/character-layer-starter/` | constitution, role character profiles, reflection, correction loops |
-| Organization | `organization_governance` | `templates/organization-governance-starter/` | goals, departments, policies, controls, metrics |
-
-## Local Setup
-
-Install in the project you want to connect:
-
-```bash
-npm install -D mirai-graph
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-```
-
-For repository checkout development:
-
-```bash
-cd /path/to/mirai-graph
-npm install
-npm test
-```
-
-`detect` is read-only. `bootstrap --mode suggest` writes proposal/evidence only
-and does not create canonical graph files.
-
-## One-Hour Adoption Path
-
-1. Choose a role:
-
-```bash
-npx mirai-graph choose-profile
-```
-
-2. Print the role plan:
-
-```bash
-npx mirai-graph adopter plan developer
-npx mirai-graph adopter plan researcher
-npx mirai-graph adopter plan ai_employee
-npx mirai-graph adopter plan organization
-```
-
-3. Initialize the closest starter in your project:
-
-```bash
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-```
-
-4. Generate a readable adopter report:
-
-```bash
-npx mirai-graph report validation .
-```
-
-5. Replace synthetic objects with your real public-safe or private source
-material.
-
-6. Run validation again in the copied package before adding runtime evidence.
-
-## One-Day Adoption Path
-
-Use the one-hour path, then add the executable-process layer:
-
-```text
-graph seed
--> package validation
--> context pack
--> launch record
--> process transition explanation
--> technology quality feedback
--> evidence update
--> Kaizen item
-```
-
-Recommended checks:
-
-```bash
-npm run validate:templates
-npm run validate:launch-record
-npm run validate:process-transition
-npm run validate:technology-quality-feedback
-npm run validate:instrumentation-layer
-npm run validate:adopter-workflow
-```
-
-## Acceptance Checklist
-
-A 1.0 release-candidate adopter package is ready for first internal use when:
-
-- root `graph.json` v2 exists and points to graph sources and profiles.
-- `graph/objects.json` has stable object ids, kinds, summaries and readiness.
-- `graph/relations.json` has directed relations with valid source/target ids.
-- `gates/results.json` records at least the initial validation gate.
-- Private logs, credentials, customer data and internal handoffs are outside
-  the public graph package.
-- Generated context is treated as derived output, not canonical state.
-- Evidence and feedback do not authorize canonical updates by themselves.
-- Significant action paths have launch records, approval gates and technology
-  quality feedback.
-- Blocking findings stop release or acceptance transitions.
-- Kaizen items are routed as proposals, not silent process rewrites.
-
-## Recommended First Packages
-
-Use these examples as references before creating your own package:
-
-- `examples/minimal-graph/`
-- `examples/implementation-control-minimal/`
-- `examples/process-transition-minimal/`
-- `examples/technology-quality-feedback-minimal/`
-- `examples/instrumentation-layer-minimal/`
-- `examples/organization-governance-minimal/`
-
-Use these starters for new work:
-
-- `templates/software-project-starter/`
-- `templates/research-program-starter/`
-- `templates/ai-employee-starter/`
-- `templates/character-layer-starter/`
-- `templates/organization-governance-starter/`
-
-Use [Connect A Project In 15 Minutes](connect-project-15-minutes.md) for a
-complete self-service walkthrough.
-
-## Public Safety Boundary
-
-Do not publish:
-
-- credentials, tokens, cookies or `.env` values;
-- customer-private logs or payloads;
-- private handoff texts;
-- internal runtime traces;
-- unpublished research claims as proof;
-- organization-specific policies that are not meant to be public.
-
-Use Mirai Graph to structure the boundary:
-
-```text
-canonical graph state
--> generated context
--> runtime decision
--> evidence
--> feedback
--> proposal
--> approval
--> controlled update
-```
-
-Only the controlled update changes canonical state.
-
-## What To Do After The First Package Validates
-
-1. Add a launch record for the first real work cycle.
-2. Run a process-transition explanation before implementation.
-3. Capture evidence and technology quality feedback after the work.
-4. Add Kaizen findings for reusable process improvements.
-5. Keep a short pilot report that separates observed evidence from claims.
-
-The next maturity step is not more theory; it is a small, repeatable pilot with
-clear evidence, limits and replayable validation commands.

package/docs/adoption/ai-employee-graph.md

@@ -1,151 +0,0 @@
-# AI Employee Graph Adoption
-
-Status: 1.0 release-candidate adoption guide
-
-## Purpose
-
-This guide explains how to start modeling an AI employee with Mirai Graph.
-
-It is intended for teams that want an AI employee to have explicit roles,
-skills, knowledge, tools, policies, workflows, feedback and learning gates.
-
-## Step 1: Define The Employee Boundary
-
-Start with one AI employee.
-
-Define:
-
-- employee id;
-- department;
-- role;
-- allowed task area;
-- forbidden task area;
-- owner or reviewer;
-- public/private data boundary.
-
-Do not start with a broad autonomous agent. Start with a bounded employee.
-
-## Step 2: Model Roles And Skills
-
-Add:
-
-- `role` objects for responsibilities;
-- `skill` objects for capabilities that require knowledge or tools;
-- `specialization` objects only when a role needs a narrower durable area.
-
-Useful relations:
-
-```text
-ai_employee -> has_role -> role
-role -> has_skill -> skill
-role -> has_specialization -> specialization
-```
-
-## Step 3: Add Knowledge And Memory
-
-Use:
-
-- `knowledge` for reviewed reference material;
-- `memory` for durable but reviewable learned context;
-- `evidence` for source support.
-
-Memory should not be an uncontrolled transcript dump. It should preserve source
-and readiness.
-
-Useful relations:
-
-```text
-skill -> uses_knowledge -> knowledge
-skill -> uses_knowledge -> memory
-```
-
-## Step 4: Add Tools And Capabilities
-
-Use:
-
-- `tool` for the runtime adapter;
-- `capability` for what the tool can safely do;
-- `policy` for the rule that constrains use.
-
-Useful relations:
-
-```text
-action -> requires_capability -> capability
-tool -> can_execute -> action
-policy -> governs -> governance_gate
-```
-
-## Step 5: Add Policy And Approval Gates
-
-Every external, user-visible, irreversible, permission-changing or sensitive
-action should have a governance gate.
-
-Useful relation:
-
-```text
-action -> requires_approval -> governance_gate
-```
-
-Approval can be automatic only when a policy explicitly allows it.
-
-## Step 6: Model Runtime Boundary
-
-Keep runtime states separate:
-
-```text
-canonical graph state
--> generated context
--> runtime decision
--> proposed action
--> approval gate
--> executed action
--> audited result
-```
-
-The graph can describe the states. The runtime implementation executes and
-audits them.
-
-## Step 7: Add Feedback And Lessons
-
-Feedback should produce a proposed lesson, not an automatic behavior change.
-
-Useful relations:
-
-```text
-feedback -> responds_to -> result
-lesson -> learns_from -> feedback
-lesson -> updates_behavior -> workflow
-```
-
-Then apply the feedback learning gate:
-
-```text
-feedback -> proposal -> replay/evaluation -> approval -> canonical graph update
-```
-
-## Step 8: Validate
-
-Use the minimal example:
-
-```bash
-node packages/cli/validate-mirai-graph.js examples/ai-employee-minimal
-```
-
-Use the full release gate:
-
-```bash
-npm run release:check
-```
-
-## What This Does Not Prove
-
-A valid AI employee graph does not prove:
-
-- the runtime is safe;
-- the AI employee is effective;
-- the tool adapter is secure;
-- the policy is sufficient;
-- the employee can act without oversight.
-
-It proves only that the package follows the declared profile shape checked by
-the current validator.

package/docs/adoption/character-layer.md

@@ -1,196 +0,0 @@
-# Character Layer Adoption
-
-Status: 1.0 release-candidate profile guide
-
-## Purpose
-
-The Character Layer profile defines a public Mirai Graph vocabulary for
-model-independent AI character governance.
-
-It is intended for systems that need to represent:
-
-- character constitutions;
-- principles and character virtues;
-- character boundaries;
-- role-specific character profiles;
-- reflection protocols;
-- evaluation fixtures;
-- violation patterns;
-- correction loops;
-- evidence and governance gates.
-
-## Profile Boundary
-
-Character Layer stores canonical character state and review structure in a
-graph package. Runtime systems can project that graph into task context, but
-generated context remains separate from authorization, external action and
-canonical updates.
-
-Recommended boundary:
-
-```text
-canonical character graph
--> generated character context
--> runtime reflection
--> proposed answer or action
--> policy or action gate
--> output or execution
--> reviewed result
--> feedback
--> correction proposal
--> owner-approved canonical update
-```
-
-## Relationship To AI Employee
-
-Use `character_layer` when the main object is behavior governance: principles,
-boundaries, reflection, fixtures, violations and correction loops.
-
-Use `ai_employee` when the main object is an executable AI worker model: roles,
-skills, tools, capabilities, workflows, actions, feedback and lessons.
-
-The profiles can be composed by a system design, but the first Character Layer
-profile is separate and does not modify `profiles/ai-employee/`.
-
-Typical composition:
-
-```text
-ai_employee -> has_role -> role
-role_character_profile -> governs_role -> role
-role_character_profile -> governs_employee -> ai_employee
-role_character_profile -> specializes_character -> character_constitution
-role_character_profile -> uses_reflection_protocol -> reflection_protocol
-character_boundary -> requires_escalation_to -> governance_gate
-correction_loop -> updates_character -> role_character_profile|character_principle|character_boundary
-```
-
-## Minimal Package
-
-The minimal package is:
-
-```text
-examples/character-layer-minimal/
-```
-
-It includes:
-
-- one public-safe character constitution;
-- principles for uncertainty, authority boundaries and evidence reporting;
-- character virtues for evidence honesty and boundary discipline;
-- character boundaries for generated authorization and secret exposure;
-- a reflection protocol;
-- a role character profile;
-- a fixture, violation pattern and correction loop;
-- gate results for public safety, canonical writes, external actions, feedback
-  learning and scientific claims.
-
-## Starter Pack
-
-For new projects, start from the reusable starter:
-
-```text
-templates/character-layer-starter/
-```
-
-It expands the minimal fixture into a base character constitution, reusable
-principles, character virtues, hard boundaries, reflection protocol, several
-role character profiles, violation patterns and an owner-reviewed correction
-loop.
-
-Use it when the same behavior governance layer should be reused across AI
-employees, project roles or model backends.
-
-## Cross-Layer Integration
-
-Character Layer should compose with other layers through an integration artifact
-rather than by mixing all profile vocabularies into one package.
-
-Minimal synthetic integration example:
-
-```text
-examples/character-layer-integration-minimal/
-```
-
-It links:
-
-- `role_character_profile` to AI employee and role references;
-- launch record and process-control contract references;
-- technology quality feedback;
-- runtime generated context boundary;
-- reflection protocol;
-- required gates for approval, review and technology feedback.
-
-## Model Portability Evidence
-
-To test whether a new neural model backend preserves behavior, compare model
-runs against the same task set, graph context and character profile.
-
-Minimal synthetic evidence shape:
-
-```text
-examples/model-portability-minimal/
-```
-
-This records fixture results, boundary violations, comparison metrics and a
-bounded verdict such as `portable_within_fixture_limits`. It does not prove
-broad model equivalence or production replacement readiness.
-
-## 1.0 Readiness Consolidation
-
-The Character Layer 1.0 readiness artifact is:
-
-```text
-examples/character-layer-readiness-1-0/
-```
-
-It consolidates profile vocabulary, minimal fixture, starter pack, semantic
-anti-fixtures, cross-layer integration, model portability evidence shape,
-validation commands, claim boundaries and remaining limits.
-
-## Validation
-
-From the repository root:
-
-```bash
-node packages/cli/validate-mirai-graph.js profile profiles/character-layer/profile.json
-node packages/cli/validate-mirai-graph.js examples/character-layer-minimal
-node packages/cli/validate-mirai-graph.js templates/character-layer-starter
-node packages/cli/validate-mirai-graph.js character-layer-integration examples/character-layer-integration-minimal/results/character-layer-integration.json
-node packages/cli/validate-mirai-graph.js model-portability-evidence examples/model-portability-minimal/results/model-portability-evidence.json
-node packages/cli/validate-mirai-graph.js character-layer-readiness examples/character-layer-readiness-1-0/results/character-layer-readiness.json
-npm run validate:character-layer
-npm run validate:character-layer-starter
-npm run validate:character-layer-integration
-npm run validate:model-portability-evidence
-npm run validate:character-layer-readiness
-```
-
-## Evidence Limits
-
-The current profile and example provide structural conformance evidence for the
-Mirai Graph package shape. Scientific effectiveness claims require separate
-research design, measurements and review.
-
-The current release-candidate profile does not claim improvements in trust, safety,
-auditability, consistency or employee performance.
-
-## Public Safety
-
-Public examples should use synthetic or public-safe content only.
-
-Do not include:
-
-- private operational constitutions;
-- customer data;
-- credentials, tokens or private keys;
-- private runtime logs;
-- organization-specific instructions that should stay internal.
-
-## Adoption Checklist
-
-- Choose `character_layer` only when behavior-governance objects are central.
-- Keep canonical graph state separate from generated runtime context.
-- Keep generated context separate from authorization.
-- Add gate results for public safety and canonical-write boundaries.
-- Mark scientific or product-effectiveness claims as out of scope until
-  supported by research evidence.

package/docs/adoption/choose-profile.md

@@ -1,106 +0,0 @@
-# Choose A Mirai Graph Profile
-
-Status: 1.0 release-candidate adopter workflow
-
-## Purpose
-
-Use this guide when you want to start a Mirai Graph package and need to choose
-the first profile, starter template and validation path.
-
-Start narrow. A useful first package should model one bounded system, not the
-entire organization.
-
-If a new idea appears to need a new profile, first read
-[Profile Boundaries](../../standard/profile-boundaries.md). Mirai Graph uses
-`extension before profile`: prefer an existing profile object, relation, gate,
-validator or proposal before adding a new profile name.
-
-## Quick Choice
-
-| You are modeling | Start with profile | Starter template | Validate with |
-| --- | --- | --- | --- |
-| Software product, feature or package | `software_specification` | `templates/software-project-starter` | `npm run validate:templates` |
-| Research program or evidence workflow | `project_management` | `templates/research-program-starter` | `npm run validate:templates` |
-| AI employee, agent workflow or governed AI role | `ai_employee` | `templates/ai-employee-starter` | `npm run validate:templates` |
-| AI behavior constitution, role character or reflection boundary | `character_layer` | `templates/character-layer-starter` | `npm run validate:templates` |
-| Organization, department, portfolio or governance system | `organization_governance` | `templates/organization-governance-starter` | `npm run validate:templates` |
-
-## Decision Rules
-
-Choose `software_specification` when the graph needs to manage requirements,
-features, components, dependencies, implementation tasks and technical risks.
-
-Choose `project_management` when the graph needs to coordinate goals,
-milestones, tasks, decisions, risks, evidence and review gates across a bounded
-initiative.
-
-Choose `ai_employee` when the graph needs to describe an AI worker as a governed
-system with role, skill, tool, policy, action, result, feedback and learning
-boundaries.
-
-Choose `character_layer` when the graph needs to describe model-independent AI
-behavior governance: constitution, principles, character virtues, boundaries,
-reflection protocols, violation patterns and correction loops.
-
-Choose `organization_governance` when the graph needs to model mission,
-strategy, departments, programs, policies, controls, metrics, delegated
-responsibility and governance risks.
-
-If two profiles seem valid, choose the profile that matches the first decision
-you need to make:
-
-- build or change software -> `software_specification`;
-- coordinate work -> `project_management`;
-- govern an AI worker -> `ai_employee`;
-- govern behavior across AI roles or model backends -> `character_layer`;
-- govern an organization or portfolio -> `organization_governance`.
-
-## First-Day Workflow
-
-```text
-choose profile -> copy starter -> replace synthetic objects -> validate -> generate report -> add launch/evidence/kaizen controls
-```
-
-1. Copy the closest starter template into your project.
-2. Keep the same file layout for the first iteration.
-3. Replace synthetic object titles and summaries with your real public-safe or
-   private project objects.
-4. Keep private notes, credentials, customer data and raw logs outside public
-   graph packages.
-5. Run package validation.
-6. Generate a Markdown report for human review.
-7. Add launch records, process transitions, evidence packs and Kaizen only
-   after the package shape validates.
-
-## Commands
-
-Profile map:
-
-```bash
-node packages/cli/mirai-graph.js choose-profile
-```
-
-Adopter plan for a role or profile:
-
-```bash
-node packages/cli/mirai-graph.js adopter plan developer
-node packages/cli/mirai-graph.js adopter plan ai_employee
-```
-
-Readable report for a starter:
-
-```bash
-node packages/cli/mirai-graph.js adopter report templates/software-project-starter
-```
-
-## Boundaries
-
-- A selected profile is a starting point, not a claim of complete governance.
-- Passing validation means the package follows current release-candidate shape
-  rules.
-- Generated context, evidence, feedback and proposals do not authorize
-  canonical updates.
-- Production execution stays outside the public alpha adopter workflow.
-- Full documents, articles, code and raw logs should stay in source systems.
-  Mirai Graph stores references, governable meaning, gates and evidence links,
-  not bulk content.