mirai-graph 1.0.0-rc.1

package/benchmarks/synthetic-context-reduction-v0/reviews/semantic-completeness-review.json

@@ -0,0 +1,78 @@
+{
+  "schema_version": "0.1.0",
+  "review_id": "semantic_review.synthetic_context_reduction_v0.task_notify_after_approval",
+  "reviewed_at": "2026-05-28",
+  "reviewer": "Mirai Graph maintainers",
+  "protocol": "docs/research/semantic-completeness-review-protocol.md",
+  "target": {
+    "package_id": "package.synthetic_context_reduction_v0",
+    "context_pack": "benchmarks/synthetic-context-reduction-v0/results/context-pack.json",
+    "task_id": "task.notify_after_approval"
+  },
+  "verdict": "pass_with_notes",
+  "score_total": 15,
+  "score_max": 16,
+  "dimensions": [
+    {
+      "name": "task_relevance",
+      "score": 2,
+      "note": "The context pack is centered on notification after approval."
+    },
+    {
+      "name": "required_object_coverage",
+      "score": 2,
+      "note": "Notification delivery, workflow transition, scoped token, audit constraint and duplicate-notification risk are included."
+    },
+    {
+      "name": "required_relation_coverage",
+      "score": 2,
+      "note": "The included relations preserve dependency, evidence, blocking and generation paths needed for the task."
+    },
+    {
+      "name": "evidence_preservation",
+      "score": 2,
+      "note": "All source evidence referenced by included objects and relations is preserved."
+    },
+    {
+      "name": "risk_and_blocker_visibility",
+      "score": 2,
+      "note": "The audit-before-notify constraint and duplicate notification risk remain visible."
+    },
+    {
+      "name": "governance_gate_visibility",
+      "score": 1,
+      "note": "The package has no explicit governance gate object; the safety constraint is visible but not modeled as a gate."
+    },
+    {
+      "name": "omission_transparency",
+      "score": 2,
+      "note": "Omitted package-level objects are listed."
+    },
+    {
+      "name": "no_private_or_unsafe_leakage",
+      "score": 2,
+      "note": "The package is synthetic and contains no private material."
+    }
+  ],
+  "required_context_preserved": [
+    "pkg.notification_delivery",
+    "feature.workflow_transition",
+    "feature.scoped_api_token",
+    "constraint.audit_before_notify",
+    "risk.duplicate_notifications"
+  ],
+  "important_omissions": [
+    {
+      "object_id": "pkg.identity_access",
+      "impact": "low",
+      "note": "The scoped API token feature and source evidence are included, so the omitted package wrapper does not block this task."
+    }
+  ],
+  "limitations": [
+    "The review is performed on a synthetic package.",
+    "The review does not measure downstream implementation quality.",
+    "The package does not yet model governance gates as graph objects.",
+    "Selection scores are heuristic and do not prove semantic completeness."
+  ],
+  "claim_supported": "The generated context pack preserved task-relevant meaning under this review protocol."
+}

package/benchmarks/synthetic-context-reduction-v0/scripts/calculate-context-reduction.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const writeFlagIndex = process.argv.indexOf("--write");
+const outputPath = writeFlagIndex >= 0 ? process.argv[writeFlagIndex + 1] : null;
+const metricsPath = path.join(packageRoot, "metrics", "example-metrics.json");
+const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+
+const baseline = metrics.baseline.estimated_context_units;
+const graphContext = metrics.graph_context.estimated_context_units;
+
+if (!Number.isFinite(baseline) || baseline <= 0) {
+  throw new Error("baseline.estimated_context_units must be a positive number");
+}
+
+if (!Number.isFinite(graphContext) || graphContext < 0) {
+  throw new Error("graph_context.estimated_context_units must be a non-negative number");
+}
+
+const reductionPercent = ((baseline - graphContext) / baseline) * 100;
+
+const result = {
+  schema_version: "0.1.0",
+  task_id: metrics.task_id,
+  baseline_context_units: baseline,
+  graph_context_units: graphContext,
+  total_reduction_percent: Number(reductionPercent.toFixed(4)),
+  note: "Synthetic demonstration only; do not merge with internal empirical metrics."
+};
+
+const output = JSON.stringify(result, null, 2);
+
+if (outputPath) {
+  const resolvedOutputPath = path.resolve(outputPath);
+  fs.mkdirSync(path.dirname(resolvedOutputPath), { recursive: true });
+  fs.writeFileSync(resolvedOutputPath, `${output}\n`);
+}
+
+console.log(output);

package/benchmarks/synthetic-context-reduction-v0/source-corpus/audit-events.md

@@ -0,0 +1,8 @@
+# Audit Events Package
+
+The audit package stores append-only events for security-relevant actions and
+workflow transitions. Events must include actor identity, action type, target
+object and correlation identifier.
+
+Open issue: audit records should be queryable by administrators without
+exposing private draft content.

package/benchmarks/synthetic-context-reduction-v0/source-corpus/content-workflow.md

@@ -0,0 +1,8 @@
+# Content Workflow Package
+
+The workflow package manages draft, review, approved and published states.
+Every state transition must store actor, timestamp, previous state, next state
+and reason.
+
+Open issue: publication approval should trigger notifications, but only after
+audit events are persisted.

package/benchmarks/synthetic-context-reduction-v0/source-corpus/identity-access.md

@@ -0,0 +1,8 @@
+# Identity And Access Package
+
+The platform needs account registration, role assignment and scoped API tokens.
+Editors can create drafts, reviewers can approve publication and administrators
+can manage roles.
+
+Open issue: API tokens must be auditable because notification delivery may act
+on behalf of a user.

package/benchmarks/synthetic-context-reduction-v0/source-corpus/notification-delivery.md

@@ -0,0 +1,8 @@
+# Notification Delivery Package
+
+The notification package sends email and webhook messages when important
+workflow events occur. Delivery workers must use scoped tokens and must not send
+notifications until the triggering event has been audited.
+
+Open issue: retry behavior must avoid duplicate notifications for the same
+workflow transition.

package/benchmarks/synthetic-context-reduction-v0/tasks/tasks.json

@@ -0,0 +1,31 @@
+[
+  {
+    "id": "task.notify_after_approval",
+    "prompt": "Prepare the implementation context for sending notifications after content approval.",
+    "baseline_sources": [
+      "source-corpus/identity-access.md",
+      "source-corpus/content-workflow.md",
+      "source-corpus/audit-events.md",
+      "source-corpus/notification-delivery.md"
+    ],
+    "graph_seed_objects": [
+      "feature.workflow_transition",
+      "constraint.audit_before_notify",
+      "pkg.notification_delivery"
+    ],
+    "expected_context_objects": [
+      "pkg.content_workflow",
+      "feature.workflow_transition",
+      "pkg.audit_events",
+      "constraint.audit_before_notify",
+      "pkg.notification_delivery",
+      "feature.scoped_api_token",
+      "risk.duplicate_notifications"
+    ],
+    "acceptance_notes": [
+      "Context must include the audit-before-notify constraint.",
+      "Context must include scoped-token dependency.",
+      "Context must flag duplicate notification risk."
+    ]
+  }
+]

package/docs/adoption/adopter-kit.md

@@ -0,0 +1,179 @@
+# 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 repository
+based while npm publication is pending.
+
+## 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
+
+Until npm publication is complete, run commands from the repository checkout:
+
+```bash
+cd /path/to/mirai-graph
+npm install
+npm test
+```
+
+After npm publication, the same adopter path should be available through the
+published `mirai-graph` package.
+
+## One-Hour Adoption Path
+
+1. Choose a role:
+
+```bash
+node packages/cli/mirai-graph.js choose-profile
+```
+
+2. Print the role plan:
+
+```bash
+node packages/cli/mirai-graph.js adopter plan developer
+node packages/cli/mirai-graph.js adopter plan researcher
+node packages/cli/mirai-graph.js adopter plan ai_employee
+node packages/cli/mirai-graph.js adopter plan organization
+```
+
+3. Validate the closest starter:
+
+```bash
+node packages/cli/validate-mirai-graph.js templates/software-project-starter
+node packages/cli/validate-mirai-graph.js templates/research-program-starter
+node packages/cli/validate-mirai-graph.js templates/ai-employee-starter
+node packages/cli/validate-mirai-graph.js templates/character-layer-starter
+node packages/cli/validate-mirai-graph.js templates/organization-governance-starter
+```
+
+4. Generate a readable adopter report:
+
+```bash
+node packages/cli/mirai-graph.js adopter report templates/software-project-starter
+```
+
+5. Copy the starter into your own project and 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:
+
+- `mirai-graph-package.json` exists and points to graph, gates and profile.
+- `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/`
+
+## 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

@@ -0,0 +1,151 @@
+# AI Employee Graph Adoption
+
+Status: alpha 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.