mirai-graph 1.0.0-rc.1

package/docs/adoption/character-layer.md

@@ -0,0 +1,196 @@
+# Character Layer Adoption
+
+Status: alpha 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

@@ -0,0 +1,98 @@
+# Choose A Mirai Graph Profile
+
+Status: alpha.10 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.
+
+## 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.

package/docs/adoption/cli.md

@@ -0,0 +1,78 @@
+# Mirai Graph CLI
+
+Status: alpha unified entrypoint
+
+Mirai Graph keeps the reference scripts for direct automation. The
+`mirai-graph` entrypoint is the primary command surface for common checks and
+reports.
+
+## Commands
+
+List profile choices:
+
+```bash
+node packages/cli/mirai-graph.js choose-profile
+```
+
+Print an 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 organization_governance
+```
+
+Generate a readable adopter report for a starter template:
+
+```bash
+node packages/cli/mirai-graph.js adopter report templates/software-project-starter
+```
+
+Validate a package:
+
+```bash
+node packages/cli/mirai-graph.js validate examples/minimal-graph
+```
+
+Generate a Markdown validation report:
+
+```bash
+node packages/cli/mirai-graph.js report validation examples/minimal-graph
+```
+
+Explain a process transition:
+
+```bash
+node packages/cli/mirai-graph.js explain process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
+```
+
+Generate the playground report:
+
+```bash
+node packages/cli/mirai-graph.js report playground
+```
+
+Check the external release state without publishing:
+
+```bash
+node packages/cli/mirai-graph.js release state --markdown
+npm run validate:release-state
+```
+
+## Output Boundary
+
+- JSON output is intended for tools and CI.
+- Markdown output is intended for human review.
+- Adopter workflow output is a starting aid, not adoption proof.
+- A passing report is evidence for the checked artifact only.
+- A release-state report checks package, git tag, GitHub Release, npm registry
+  and npm auth state, but it does not publish or authorize a release.
+- Generated context, evidence, feedback and proposals do not authorize
+  canonical updates.
+
+## Command Aliases
+
+The `mirai_graph` entrypoint is an underscore alias for environments where a
+hyphenated command name is inconvenient. New documentation and automation
+should prefer
+`node packages/cli/validate-mirai-graph.js <package-dir>` or
+`node packages/cli/mirai-graph.js ...`.

package/docs/adoption/developer-integration-guide.md

@@ -0,0 +1,93 @@
+# Mirai Graph Developer Integration Guide
+
+Status: 1.0 release-candidate developer guide
+
+## Purpose
+
+This guide shows how to use Mirai Graph validation in a developer workflow or CI
+pipeline.
+
+Mirai Graph tooling is a reference implementation. The standard remains the
+source of the model; the CLI helps teams check public-safe graph packages,
+profiles, context packs and process-control artifacts.
+
+## Install
+
+For the current release candidate, run commands from the repository root:
+
+```bash
+npm install
+```
+
+## Validate A Package
+
+JSON output is the default:
+
+```bash
+node packages/cli/validate-mirai-graph.js examples/minimal-graph
+```
+
+Human-readable Markdown output:
+
+```bash
+node packages/cli/validate-mirai-graph.js --markdown examples/minimal-graph
+```
+
+## Validate Process Control
+
+Use process-transition validation when work moves through an executable state
+machine:
+
+```bash
+node packages/cli/validate-mirai-graph.js process-transition \
+  examples/process-transition-minimal/state-machine.json \
+  examples/process-transition-minimal/transition-request.json
+```
+
+Use process-control contract validation when a project binds cycles, state
+machine, launch policy, evidence, recovery and Kaizen policy:
+
+```bash
+node packages/cli/validate-mirai-graph.js process-control-contract \
+  examples/process-control-contract-minimal/results/process-control-contract.json
+```
+
+## CI Example
+
+Minimal GitHub Actions step:
+
+```yaml
+- name: Validate Mirai Graph examples
+  run: |
+    npm ci
+    npm run release:check
+```
+
+Targeted package check:
+
+```yaml
+- name: Validate Mirai Graph package
+  run: |
+    node packages/cli/validate-mirai-graph.js path/to/package
+```
+
+Markdown report artifact:
+
+```yaml
+- name: Generate Mirai Graph validation report
+  run: |
+    node packages/cli/validate-mirai-graph.js --markdown path/to/package > mirai-graph-report.md
+```
+
+## Exit Codes
+
+- `0`: validation passed.
+- `1`: validation failed or an input file could not be read.
+- `2`: command usage error.
+
+## Boundaries
+
+- A passing validation report is evidence for the selected check only.
+- Generated context is not canonical graph state.
+- Evidence and proposals do not authorize canonical updates.
+- Readiness states do not imply execution or release.

package/docs/adoption/end-to-end-control-loop.md

@@ -0,0 +1,168 @@
+# End-To-End Mirai Graph Control Loop
+
+Status: alpha tutorial
+
+## Purpose
+
+This tutorial shows the public alpha control loop:
+
+```text
+seed -> graph -> context -> launch -> transition -> evidence -> kaizen
+```
+
+It uses existing public-safe examples. It does not require private project data
+and does not grant automatic permission to change canonical graph state.
+
+## 1. Start With A Seed
+
+A graph seed defines the first bounded system shape before a full graph exists.
+
+Run:
+
+```bash
+node packages/cli/validate-mirai-graph.js seed examples/graph-seed-minimal/graph-seed.json
+node packages/cli/seed-preview.js examples/graph-seed-minimal/graph-seed.json
+```
+
+Read:
+
+- `standard/graph-seed.md`
+- `examples/graph-seed-minimal/README.md`
+
+## 2. Validate A Graph Package
+
+A package stores graph objects, relations and gate results.
+
+Run:
+
+```bash
+node packages/cli/validate-mirai-graph.js examples/minimal-graph
+```
+
+Read:
+
+- `standard/object-model.md`
+- `standard/relation-model.md`
+- `standard/evidence-provenance.md`
+
+## 3. Generate Or Inspect Task Context
+
+Context packs select task-relevant graph material. They are generated context,
+not canonical state.
+
+Run:
+
+```bash
+node packages/cli/context-pack.js benchmarks/synthetic-context-reduction-v0 --task-id task.notify_after_approval
+node packages/cli/validate-mirai-graph.js context-pack benchmarks/synthetic-context-reduction-v0 benchmarks/synthetic-context-reduction-v0/results/context-pack.json
+```
+
+Read:
+
+- `standard/context-pack-generation.md`
+- `benchmarks/synthetic-context-reduction-v0/README.md`
+
+## 4. Prepare A Launch Record
+
+A launch record defines a bounded work batch, required gates, allowed scope and
+evidence expectations. It is not proof that the work has been executed.
+
+Run:
+
+```bash
+node packages/cli/validate-mirai-graph.js examples/launch-record-minimal
+node packages/cli/validate-mirai-graph.js launch-record examples/launch-record-minimal/results/launch-record.json
+```
+
+Read:
+
+- `standard/launch-record.md`
+- `examples/launch-record-minimal/README.md`
+
+## 5. Validate A Process Transition
+
+Process transitions move through executable state-machine states. Human stages
+and documentation can explain the movement, but the transition request must
+pass validator checks.
+
+Run:
+
+```bash
+node packages/cli/validate-mirai-graph.js process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
+node packages/cli/validate-mirai-graph.js process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request-skip-kaizen.json
+```
+
+Negative fixtures intentionally fail:
+
+```bash
+npm run test:process-transition-negative
+```
+
+Read:
+
+- `standard/work-state-machine.md`
+- `standard/process-control-contract.md`
+- `examples/process-transition-minimal/README.md`
+
+## 6. Record Evidence
+
+Evidence links claims to sources, gates, validation results and limitations. It
+does not approve canonical updates by itself.
+
+Run:
+
+```bash
+npm run validate:implementation-control
+npm run validate:process-control
+```
+
+Read:
+
+- `standard/evidence-provenance.md`
+- `standard/implementation-control.md`
+- `examples/process-control-contract-minimal/README.md`
+
+## 7. Close With Kaizen
+
+Significant work should end with a Kaizen review or an explicit
+`no_reusable_lessons` reason. Kaizen findings become classified improvement
+inputs, not automatic rewrites.
+
+Run:
+
+```bash
+npm run validate:implementation-control-cycles
+```
+
+Read:
+
+- `standard/implementation-control-cycles.md`
+- `examples/implementation-control-cycles/README.md`
+
+## Full Smoke Check
+
+Run the current release-candidate test suite:
+
+```bash
+npm test
+```
+
+Generate the playground report for this loop:
+
+```bash
+npm run playground:demo
+```
+
+For release readiness:
+
+```bash
+npm run release:check
+```
+
+## Boundaries
+
+- Generated context is not canonical state.
+- Evidence is not approval.
+- A proposal is not a canonical update.
+- `ready_to_execute` is not execution.
+- Synthetic benchmarks are method demonstrations, not broad scientific proof.