mirai-graph 1.0.0-rc.1

package/packages/cli/validate-process-transition-report.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const { spawnSync } = require("child_process");
+
+const stateMachine = "examples/process-transition-minimal/state-machine.json";
+const fixtures = [
+  "examples/process-transition-minimal/results/transition-explanation-valid.json",
+  "examples/process-transition-minimal/results/transition-explanation-invalid-ready-to-written.json"
+];
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function runValidator(args) {
+  return spawnSync(process.execPath, ["packages/cli/validate-mirai-graph.js", ...args], {
+    encoding: "utf8"
+  });
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortJson);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, sortJson(value[key])])
+    );
+  }
+  return value;
+}
+
+function stable(value) {
+  return JSON.stringify(sortJson(value));
+}
+
+const errors = [];
+
+for (const fixturePath of fixtures) {
+  const fixture = readJson(fixturePath);
+  const run = runValidator(["process-transition", stateMachine, fixture.request_ref]);
+  let output;
+  try {
+    output = JSON.parse(run.stdout);
+  } catch (error) {
+    errors.push(`${fixturePath}: validator did not emit parseable JSON`);
+    continue;
+  }
+
+  if (output.valid !== fixture.expected_valid) {
+    errors.push(`${fixturePath}: expected valid=${fixture.expected_valid}, got ${output.valid}`);
+  }
+
+  if (fixture.expected_valid && run.status !== 0) {
+    errors.push(`${fixturePath}: expected validator exit 0, got ${run.status}`);
+  }
+
+  if (!fixture.expected_valid && run.status === 0) {
+    errors.push(`${fixturePath}: expected validator to fail`);
+  }
+
+  if (!output.explanation || typeof output.explanation !== "object") {
+    errors.push(`${fixturePath}: missing explanation object`);
+    continue;
+  }
+
+  if (stable(output.explanation) !== stable(fixture.explanation)) {
+    errors.push(`${fixturePath}: explanation does not match committed fixture`);
+  }
+
+  if (fixture.expected_error && !output.errors.includes(fixture.expected_error)) {
+    errors.push(`${fixturePath}: expected error not found`);
+  }
+}
+
+const markdown = runValidator([
+  "--markdown",
+  "process-transition",
+  stateMachine,
+  "examples/process-transition-minimal/transition-request.json"
+]);
+if (markdown.status !== 0) {
+  errors.push(`markdown report failed with exit ${markdown.status}`);
+}
+for (const requiredText of [
+  "Process Transition Decision Report",
+  "Transition: `release_ready -> released`",
+  "Kaizen decision: `satisfied`",
+  "Missing Evidence"
+]) {
+  if (!markdown.stdout.includes(requiredText)) {
+    errors.push(`markdown report missing ${requiredText}`);
+  }
+}
+
+const output = {
+  mode: "process_transition_report",
+  valid: errors.length === 0,
+  checked_files: fixtures,
+  errors
+};
+
+console.log(JSON.stringify(output, null, 2));
+process.exit(output.valid ? 0 : 1);

package/packages/cli/validate-profile-results.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+
+const resultFiles = [
+  "examples/minimal-graph/results/profile-conformance-result.json",
+  "examples/ai-employee-minimal/results/profile-conformance-result.json",
+  "examples/skill-runtime-minimal/results/profile-conformance-result.json",
+  "examples/organization-governance-minimal/results/profile-conformance-result.json",
+  "benchmarks/synthetic-context-reduction-v0/results/profile-conformance-result.json",
+  "pilots/independent-implementation-001-conference-planning/results/profile-conformance-result.json",
+  "pilots/independent-implementation-002-software-specification/results/profile-conformance-result.json",
+  "pilots/independent-implementation-003-ai-employee-workflow/results/profile-conformance-result.json",
+  "pilots/independent-implementation-004-research-program/results/profile-conformance-result.json",
+  "pilots/independent-implementation-005-organization-governance/results/profile-conformance-result.json"
+];
+
+const errors = [];
+
+for (const file of resultFiles) {
+  let result;
+  try {
+    result = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    errors.push(`${file}: cannot read JSON: ${error.message}`);
+    continue;
+  }
+
+  if (result.valid !== true) {
+    errors.push(`${file}: valid must be true`);
+  }
+
+  if (!Array.isArray(result.errors) || result.errors.length !== 0) {
+    errors.push(`${file}: errors must be an empty array`);
+  }
+
+  if (typeof result.profile !== "string" || result.profile.trim() === "") {
+    errors.push(`${file}: profile must be a non-empty string`);
+  }
+
+  if (
+    typeof result.command !== "string" ||
+    !result.command.includes("validate-mirai-graph.js")
+  ) {
+    errors.push(`${file}: command must reference validate-mirai-graph.js`);
+  }
+
+  if (
+    typeof result.claim_supported !== "string" ||
+    !result.claim_supported.includes("declared Mirai Graph profile shape")
+  ) {
+    errors.push(`${file}: claim_supported must stay limited to profile shape conformance`);
+  }
+}
+
+const output = {
+  mode: "profile_conformance_results",
+  valid: errors.length === 0,
+  checked_files: resultFiles,
+  errors
+};
+
+console.log(JSON.stringify(output, null, 2));
+process.exit(output.valid ? 0 : 1);

package/packages/cli/validate-release-state.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+const node = process.execPath;
+const releaseState = path.join(root, "packages", "cli", "release-state.js");
+
+const args = process.argv.slice(2);
+const requireGitTag = args.includes("--require-git-tag");
+const requireGithubRelease = args.includes("--require-github-release");
+const requireNpmPublished = args.includes("--require-npm-published");
+const releaseStateArgs = [
+  ...(requireGitTag ? ["--require-git-tag"] : []),
+  ...(requireGithubRelease ? ["--require-github-release"] : []),
+  ...(requireNpmPublished ? ["--require-npm-published"] : [])
+];
+
+const result = spawnSync(node, [releaseState, ...releaseStateArgs], {
+  cwd: root,
+  encoding: "utf8"
+});
+
+const errors = [];
+let state = null;
+
+if (result.status !== 0) {
+  errors.push(`release-state command failed with exit ${result.status}`);
+}
+
+try {
+  state = JSON.parse(result.stdout);
+} catch (error) {
+  errors.push("release-state output is not valid JSON");
+}
+
+if (state) {
+  if (state.report_type !== "mirai_graph_release_state") {
+    errors.push("unexpected report_type");
+  }
+  if (!state.package || state.package.name !== "mirai-graph") {
+    errors.push("package name must be mirai-graph");
+  }
+  if (!state.package || !state.package.version) {
+    errors.push("package version is required");
+  }
+  if (requireGitTag && (!state.git || !state.git.tag_exists)) {
+    errors.push("current package version must have a local git tag");
+  }
+  if (requireGithubRelease && (!state.github_release || !state.github_release.found)) {
+    errors.push("matching GitHub Release must exist");
+  }
+  if (!state.npm || !state.npm.package || typeof state.npm.package.version_published !== "boolean") {
+    errors.push("npm package publication state must be reported");
+  }
+  if (!state.npm || typeof state.npm.authenticated !== "boolean") {
+    errors.push("npm authentication state must be reported");
+  }
+  if (!Array.isArray(state.blockers)) {
+    errors.push("blockers must be an array");
+  }
+  if (!Array.isArray(state.boundary) || !state.boundary.some((item) => item.includes("does not publish"))) {
+    errors.push("release-state boundary must state that the report does not publish");
+  }
+}
+
+const markdown = spawnSync(node, [releaseState, "--markdown", ...releaseStateArgs], {
+  cwd: root,
+  encoding: "utf8"
+});
+
+if (markdown.status !== 0) {
+  errors.push(`release-state markdown command failed with exit ${markdown.status}`);
+} else {
+  for (const expected of ["Mirai Graph Release State", "GitHub Release", "NPM Package", "Blockers"]) {
+    if (!markdown.stdout.includes(expected)) {
+      errors.push(`markdown report missing ${expected}`);
+    }
+  }
+}
+
+const validation = {
+  mode: "release_state",
+  valid: errors.length === 0,
+  checked_version: state && state.package && state.package.version || null,
+  require_git_tag: requireGitTag,
+  require_github_release: requireGithubRelease,
+  require_npm_published: requireNpmPublished,
+  npm_version_published: state && state.npm && state.npm.package && state.npm.package.version_published,
+  npm_authenticated: state && state.npm && state.npm.authenticated,
+  blockers: state && state.blockers || [],
+  errors
+};
+
+console.log(JSON.stringify(validation, null, 2));
+
+if (errors.length > 0) {
+  process.exit(1);
+}

package/packages/cli/validate-routing-control-examples.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const exampleDir = path.join("examples", "federation-routing-smoke");
+const requiredFiles = [
+  "routing-fixtures.json",
+  "routing-fixture-run.json",
+  "route-explanation.json",
+  "route-regression-result.json",
+  "federation-health-dashboard.json"
+];
+
+const errors = [];
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    errors.push(`${file}: cannot read JSON: ${error.message}`);
+    return null;
+  }
+}
+
+for (const fileName of requiredFiles) {
+  const file = path.join(exampleDir, fileName);
+  if (!fs.existsSync(file)) {
+    errors.push(`${file}: missing`);
+  }
+}
+
+const fixtures = readJson(path.join(exampleDir, "routing-fixtures.json"));
+const run = readJson(path.join(exampleDir, "routing-fixture-run.json"));
+const explanation = readJson(path.join(exampleDir, "route-explanation.json"));
+const regression = readJson(path.join(exampleDir, "route-regression-result.json"));
+const health = readJson(path.join(exampleDir, "federation-health-dashboard.json"));
+
+if (fixtures) {
+  if (fixtures.canonical_write_allowed !== false) errors.push("routing-fixtures.json: canonical_write_allowed must be false");
+  if (!Array.isArray(fixtures.fixtures) || fixtures.fixtures.length < 2) errors.push("routing-fixtures.json: must include at least two synthetic fixtures");
+}
+
+if (run) {
+  if (run.canonical_write_allowed !== false) errors.push("routing-fixture-run.json: canonical_write_allowed must be false");
+  if (!run.summary || run.summary.fixture_count !== 2 || run.summary.passed !== 2) errors.push("routing-fixture-run.json: expected two passing fixtures");
+  for (const result of run.results || []) {
+    if (!result.execution_evidence_ref) errors.push(`${result.fixture_id}: execution_evidence_ref is required`);
+    if (!result.route_result_ref) errors.push(`${result.fixture_id}: route_result_ref is required`);
+    if (result.high_risk_route && !result.route_explanation_ref) errors.push(`${result.fixture_id}: high-risk route requires route_explanation_ref`);
+  }
+}
+
+if (explanation) {
+  if (explanation.canonical_write_allowed !== false) errors.push("route-explanation.json: canonical_write_allowed must be false");
+  if (!explanation.route_evidence_ref) errors.push("route-explanation.json: route_evidence_ref is required");
+  if (explanation.explanation_source !== "synthetic_example") errors.push("route-explanation.json: explanation_source must be synthetic_example");
+}
+
+if (regression) {
+  if (regression.regression_status !== "unchanged") errors.push("route-regression-result.json: regression_status must be unchanged");
+  if (regression.canonical_write_allowed !== false) errors.push("route-regression-result.json: canonical_write_allowed must be false");
+}
+
+if (health) {
+  if (health.watch_conflict_count < 1) errors.push("federation-health-dashboard.json: watch_conflict_count should expose watched conflict families");
+  if (health.high_risk_without_explanation_count !== 0) errors.push("federation-health-dashboard.json: high_risk_without_explanation_count must be zero");
+  if (health.canonical_write_allowed !== false) errors.push("federation-health-dashboard.json: canonical_write_allowed must be false");
+}
+
+const output = {
+  mode: "routing_control_examples",
+  valid: errors.length === 0,
+  checked_files: requiredFiles.map((fileName) => path.join(exampleDir, fileName)),
+  errors
+};
+
+console.log(JSON.stringify(output, null, 2));
+process.exit(output.valid ? 0 : 1);

package/pilots/independent-implementation-001-conference-planning/README.md

@@ -0,0 +1,40 @@
+# Independent Implementation Pilot 001: Conference Planning
+
+Status: pilot fixture
+
+## Purpose
+
+This pilot tests whether a valid Mirai Graph package can be created using only
+the public repository materials.
+
+## Domain
+
+Synthetic conference planning workflow.
+
+No private company, customer, employee or internal project material is used.
+
+## Research Question
+
+Can a developer create a valid Level 1 Mirai Graph package for a small workflow
+using only public Mirai Graph docs, schemas and examples?
+
+## Files
+
+- `graph-seed.json`
+- `mirai-graph-package.json`
+- `graph/objects.json`
+- `graph/relations.json`
+- `gates/results.json`
+- `results/`
+- `reports/pilot-report.md`
+
+## Commands
+
+Run from repository root:
+
+```bash
+node packages/cli/validate-mirai-graph.js seed pilots/independent-implementation-001-conference-planning/graph-seed.json
+node packages/cli/validate-mirai-graph.js pilots/independent-implementation-001-conference-planning
+node packages/cli/readiness-score.js pilots/independent-implementation-001-conference-planning --target-mode pilot
+node packages/cli/context-pack.js pilots/independent-implementation-001-conference-planning --task-id task.prepare_speaker_schedule
+```

package/pilots/independent-implementation-001-conference-planning/gates/results.json

@@ -0,0 +1,12 @@
+[
+  {
+    "id": "gate_result.conference_planning.public_safety",
+    "gate_id": "gate.public_safety",
+    "target_id": "package.conference_planning_pilot_001",
+    "verdict": "pass",
+    "summary": "The pilot uses synthetic public-safe conference planning material only.",
+    "evidence": ["source.conference_brief"],
+    "reviewed_at": "2026-05-28",
+    "reviewer": "Mirai Graph maintainers"
+  }
+]

package/pilots/independent-implementation-001-conference-planning/graph/objects.json

@@ -0,0 +1,74 @@
+[
+  {
+    "id": "source.conference_brief",
+    "kind": "evidence",
+    "title": "Synthetic conference brief",
+    "summary": "A public-safe synthetic brief for a one-day community conference.",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "project_management"
+  },
+  {
+    "id": "system.community_conference",
+    "kind": "system",
+    "title": "Community Conference",
+    "summary": "A synthetic one-day conference planning workflow.",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "goal.publish_reliable_schedule",
+    "kind": "goal",
+    "title": "Publish reliable schedule",
+    "summary": "Prepare and publish a reliable speaker schedule for the conference.",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "task.collect_session_proposals",
+    "kind": "task",
+    "title": "Collect session proposals",
+    "summary": "Collect proposed talks and workshops before schedule planning.",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "task.confirm_room_capacity",
+    "kind": "task",
+    "title": "Confirm room capacity",
+    "summary": "Confirm available room capacity before assigning sessions.",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "decision.schedule_publish_gate",
+    "kind": "decision",
+    "title": "Schedule publish gate",
+    "summary": "The schedule may be published only after owner review.",
+    "readiness": "draft",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "risk.session_room_mismatch",
+    "kind": "risk",
+    "title": "Session room mismatch",
+    "summary": "A popular session may be assigned to a room that is too small.",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "gate.owner_schedule_approval",
+    "kind": "governance_gate",
+    "title": "Owner schedule approval",
+    "summary": "Owner approval is required before schedule publication.",
+    "readiness": "accepted",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  }
+]

package/pilots/independent-implementation-001-conference-planning/graph/relations.json

@@ -0,0 +1,56 @@
+[
+  {
+    "id": "relation.system.community_conference.supports.goal.publish_reliable_schedule",
+    "type": "supports",
+    "source": "system.community_conference",
+    "target": "goal.publish_reliable_schedule",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "relation.task.collect_session_proposals.supports.goal.publish_reliable_schedule",
+    "type": "supports",
+    "source": "task.collect_session_proposals",
+    "target": "goal.publish_reliable_schedule",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "relation.task.confirm_room_capacity.blocks.risk.session_room_mismatch",
+    "type": "blocks",
+    "source": "task.confirm_room_capacity",
+    "target": "risk.session_room_mismatch",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "relation.risk.session_room_mismatch.blocks.goal.publish_reliable_schedule",
+    "type": "blocks",
+    "source": "risk.session_room_mismatch",
+    "target": "goal.publish_reliable_schedule",
+    "readiness": "review_ready",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "relation.gate.owner_schedule_approval.governs.decision.schedule_publish_gate",
+    "type": "governs",
+    "source": "gate.owner_schedule_approval",
+    "target": "decision.schedule_publish_gate",
+    "readiness": "accepted",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  },
+  {
+    "id": "relation.decision.schedule_publish_gate.depends_on.task.confirm_room_capacity",
+    "type": "depends_on",
+    "source": "decision.schedule_publish_gate",
+    "target": "task.confirm_room_capacity",
+    "readiness": "draft",
+    "evidence": ["source.conference_brief"],
+    "profile": "project_management"
+  }
+]

package/pilots/independent-implementation-001-conference-planning/graph-seed.json

@@ -0,0 +1,65 @@
+{
+  "schema_version": "0.1.0",
+  "seed_id": "seed.conference_planning",
+  "target_graph_id": "graph.conference_planning",
+  "purpose": "Create a Mirai Graph package for managing a small public conference planning workflow.",
+  "target_profile": "profile.project_management",
+  "target_mode": "pilot",
+  "graph_dna": {
+    "purpose": "Keep conference goals, planning tasks, decisions, risks and governance checks connected.",
+    "evolution_vector": "Grow from a small planning map into a reviewed conference operations graph.",
+    "non_negotiable_principles": [
+      "The package must remain synthetic and public-safe.",
+      "Schedule decisions require owner review before they are treated as accepted."
+    ]
+  },
+  "source_boundaries": {
+    "allowed_sources": [
+      "synthetic conference planning brief",
+      "synthetic organizer notes"
+    ],
+    "excluded_sources": [
+      "real attendee data",
+      "private sponsor contracts",
+      "personal speaker contact details"
+    ],
+    "canonical_write_allowed": false
+  },
+  "growth_rules": {
+    "allowed_object_families": [
+      "system",
+      "goal",
+      "task",
+      "decision",
+      "risk",
+      "evidence",
+      "governance_gate"
+    ],
+    "allowed_relation_families": [
+      "depends_on",
+      "blocks",
+      "supports",
+      "evidences",
+      "governs",
+      "belongs_to"
+    ],
+    "max_initial_objects": 12,
+    "depth_mode": "light"
+  },
+  "review_gates": [
+    "human_review_before_canonical_write",
+    "public_safety_before_release",
+    "owner_approval_before_schedule_publish"
+  ],
+  "generated_views": [
+    "seed_summary",
+    "candidate_object_list",
+    "risk_view",
+    "next_action_view"
+  ],
+  "stop_conditions": [
+    "real_personal_data_requested",
+    "schedule_publish_requested_before_owner_approval",
+    "candidate_count_exceeds_budget"
+  ]
+}

package/pilots/independent-implementation-001-conference-planning/mirai-graph-package.json

@@ -0,0 +1,14 @@
+{
+  "id": "package.conference_planning_pilot_001",
+  "name": "Conference Planning Pilot 001",
+  "version": "0.1.0",
+  "profile": "project_management",
+  "conformance_level": "level_1",
+  "description": "A synthetic independent implementation pilot for a conference planning workflow.",
+  "license": "CC-BY-4.0",
+  "public_safety": "synthetic_public",
+  "graph": {
+    "objects": "graph/objects.json",
+    "relations": "graph/relations.json"
+  }
+}