mirai-graph 1.0.0-rc.1

package/standard/test-suite.md

@@ -0,0 +1,105 @@
+# Mirai Graph Test Suite
+
+Status: initial public draft
+
+## 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;
+- run deterministic seed preview;
+- generate benchmark context pack;
+- score benchmark readiness;
+- run synthetic context-reduction calculation;
+- reject negative fixtures.
+
+## 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>
+```
+
+## 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

@@ -0,0 +1,62 @@
+# Work State Machine
+
+Status: initial public standard note
+
+## 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

@@ -0,0 +1,64 @@
+# 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).
+
+## 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

@@ -0,0 +1,9 @@
+# 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

@@ -0,0 +1,12 @@
+[
+  {
+    "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

@@ -0,0 +1,90 @@
+[
+  {
+    "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

@@ -0,0 +1,47 @@
+[
+  {
+    "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"
+  }
+]

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

@@ -0,0 +1,14 @@
+{
+  "id": "package.template_ai_employee",
+  "name": "AI Employee Starter",
+  "version": "0.1.0",
+  "profile": "ai_employee",
+  "conformance_level": "level_1",
+  "description": "Synthetic starter package for a governed AI employee Mirai Graph.",
+  "license": "CC-BY-4.0",
+  "public_safety": "synthetic_public",
+  "graph": {
+    "objects": "graph/objects.json",
+    "relations": "graph/relations.json"
+  }
+}

package/templates/character-layer-starter/README.md

@@ -0,0 +1,39 @@
+# Character Layer Starter
+
+Use this template when a project, AI employee, research workflow or governed
+runtime needs a reusable Character Layer package.
+
+The starter provides:
+
+- base character constitution;
+- reusable behavior principles;
+- character virtues;
+- hard character boundaries;
+- reflection protocol;
+- role character profiles;
+- violation patterns;
+- owner-reviewed correction loop;
+- public-safety and review-boundary gates.
+
+Validate:
+
+```bash
+node packages/cli/validate-mirai-graph.js templates/character-layer-starter
+```
+
+## Adaptation Path
+
+1. Keep the base constitution unless a project has a stronger reviewed
+   constitution.
+2. Select the closest `role_character_profile`.
+3. Add project-specific boundaries only when they are evidence-backed.
+4. Keep tool permission, runtime authorization and external action policy in
+   runtime/process layers, not in this profile.
+5. Add fixtures for every behavior that must remain stable across model
+   backends.
+
+## Boundary
+
+This starter is a behavior-governance template. It does not train a model,
+grant runtime permissions, authorize external actions or prove scientific
+effectiveness.

package/templates/character-layer-starter/gates/results.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "gate_result.template_character_layer.public_safety",
+    "gate_id": "public_safety_before_release",
+    "target_id": "package.template_character_layer",
+    "verdict": "pass_with_notes",
+    "summary": "Template uses only synthetic public-safe character content and no private runtime traces.",
+    "reviewed_at": "2026-06-12",
+    "evidence": ["evidence.character_starter_brief"]
+  },
+  {
+    "id": "gate_result.template_character_layer.owner_review_boundary",
+    "gate_id": "human_review_before_canonical_write",
+    "target_id": "correction_loop.owner_reviewed_character_update",
+    "verdict": "pass_with_notes",
+    "summary": "The correction loop keeps behavior changes as proposals until owner review.",
+    "reviewed_at": "2026-06-12",
+    "evidence": ["evidence.character_starter_brief"]
+  }
+]