mirai-graph 1.0.0-rc.1

package/packages/cli/mirai-graph.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+const node = process.execPath;
+
+function usage() {
+  console.error("Usage:");
+  console.error("  mirai-graph validate <package-dir>");
+  console.error("  mirai-graph choose-profile");
+  console.error("  mirai-graph adopter plan <role-or-profile>");
+  console.error("  mirai-graph adopter report <template-dir>");
+  console.error("  mirai-graph report validation <package-dir>");
+  console.error("  mirai-graph report process-transition <state-machine-file> <transition-request-file>");
+  console.error("  mirai-graph report technology-quality-feedback <feedback-file>");
+  console.error("  mirai-graph report instrumentation [package-dir]");
+  console.error("  mirai-graph explain process-transition <state-machine-file> <transition-request-file>");
+  console.error("  mirai-graph report playground");
+  console.error("  mirai-graph release state [--markdown] [--require-git-tag] [--require-github-release] [--require-npm-published]");
+  console.error("");
+  console.error("Boundary:");
+  console.error("  Reports explain validation decisions. They do not authorize canonical updates.");
+}
+
+function run(script, args) {
+  const result = spawnSync(node, [path.join(root, script), ...args], {
+    cwd: root,
+    stdio: "inherit"
+  });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+  usage();
+  process.exit(args.length === 0 ? 1 : 0);
+}
+
+const [command, subcommand, ...rest] = args;
+
+if (command === "validate") {
+  if (!subcommand) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/validate-mirai-graph.js", [subcommand, ...rest]);
+}
+
+if (command === "choose-profile") {
+  if (subcommand || rest.length !== 0) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/adopter-workflow.js", ["choose-profile"]);
+}
+
+if (command === "adopter" && subcommand === "plan") {
+  if (rest.length !== 1) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/adopter-workflow.js", ["plan", rest[0]]);
+}
+
+if (command === "adopter" && subcommand === "report") {
+  if (rest.length !== 1) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/adopter-workflow.js", ["report", rest[0]]);
+}
+
+if (command === "report" && subcommand === "validation") {
+  if (rest.length !== 1) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/validate-mirai-graph.js", ["--markdown", rest[0]]);
+}
+
+if ((command === "report" || command === "explain") && subcommand === "process-transition") {
+  if (rest.length !== 2) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/validate-mirai-graph.js", ["--markdown", "process-transition", rest[0], rest[1]]);
+}
+
+if (command === "report" && subcommand === "technology-quality-feedback") {
+  if (rest.length !== 1) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/validate-mirai-graph.js", ["--markdown", "technology-quality-feedback", rest[0]]);
+}
+
+if (command === "report" && subcommand === "instrumentation") {
+  if (rest.length > 1) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/instrumentation-report.js", rest);
+}
+
+if (command === "report" && subcommand === "playground") {
+  if (rest.length !== 0) {
+    usage();
+    process.exit(1);
+  }
+  run("packages/cli/playground-demo.js", []);
+}
+
+if (command === "release" && subcommand === "state") {
+  run("packages/cli/release-state.js", rest);
+}
+
+usage();
+process.exit(1);

package/packages/cli/mirai_graph.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("./mirai-graph.js");

package/packages/cli/playground-demo.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function countItems(filePath) {
+  const value = readJson(filePath);
+  return Array.isArray(value) ? value.length : 0;
+}
+
+const packageDir = "benchmarks/synthetic-context-reduction-v0";
+const objectsCount = countItems(`${packageDir}/graph/objects.json`);
+const relationsCount = countItems(`${packageDir}/graph/relations.json`);
+const contextPack = readJson(`${packageDir}/results/context-pack.json`);
+const launchRecord = readJson("examples/launch-record-minimal/results/launch-record.json");
+const transition = readJson("examples/process-transition-minimal/transition-request.json");
+const transitionExplanation = readJson("examples/process-transition-minimal/results/transition-explanation-valid.json");
+const processControl = readJson("examples/process-control-contract-minimal/results/process-control-contract.json");
+const baselineComparison = readJson(`${packageDir}/results/baseline-comparison-result.json`);
+const cockpit = readJson("examples/instrumentation-layer-minimal/results/development-cockpit.json");
+const traceability = readJson("examples/instrumentation-layer-minimal/results/feature-implementation-traceability.json");
+const feedback = readJson("examples/instrumentation-layer-minimal/results/multi-source-quality-feedback.json");
+
+const lines = [
+  "# Mirai Graph Playground Demo Report",
+  "",
+  "Status: deterministic 1.0.0-rc.1 demo",
+  "",
+  "## Control Loop",
+  "",
+  "```text",
+  "seed -> graph -> context -> launch -> transition explanation -> cockpit -> traceability -> multi-source feedback -> evidence -> kaizen -> baseline comparison",
+  "```",
+  "",
+  "## Demo Inputs",
+  "",
+  `- Synthetic package: \`${packageDir}\``,
+  `- Objects: \`${objectsCount}\``,
+  `- Relations: \`${relationsCount}\``,
+  `- Context pack: \`${contextPack.id}\``,
+  `- Launch record: \`${launchRecord.id}\``,
+  `- Transition request: \`${transition.id}\``,
+  `- Transition explanation: \`${transitionExplanation.fixture_id}\``,
+  `- Process-control contract: \`${processControl.id}\``,
+  `- Development cockpit: \`${cockpit.id}\``,
+  `- Feature traceability: \`${traceability.id}\``,
+  `- Multi-source feedback: \`${feedback.id}\``,
+  `- Baseline comparison: \`${baselineComparison.id}\``,
+  "",
+  "## Commands",
+  "",
+  "```bash",
+  "npm run validate:minimal",
+  "npm run seed:preview",
+  "npm run context:generate",
+  "npm run validate:launch-record",
+  "npm run validate:process-transition",
+  "npm run validate:process-transition-report",
+  "npm run validate:process-control",
+  "npm run validate:instrumentation-layer",
+  "npm run validate:instrumentation-report",
+  "npm run validate:implementation-control-cycles",
+  "npm run validate:baseline-comparison",
+  "```",
+  "",
+  "## Transition Explanation",
+  "",
+  `- Requested transition: \`${transitionExplanation.explanation.current_state} -> ${transitionExplanation.explanation.target_state}\``,
+  `- Matched transition: \`${transitionExplanation.explanation.matched_transition ? "true" : "false"}\``,
+  `- Required evidence: \`${transitionExplanation.explanation.required_evidence.join(", ")}\``,
+  `- Missing evidence: \`${transitionExplanation.explanation.missing_evidence.length}\``,
+  `- Kaizen decision: \`${transitionExplanation.explanation.kaizen_decision.status}\``,
+  "",
+  "## Instrumentation",
+  "",
+  `- Cockpit production readiness: \`${cockpit.readiness.production_readiness}\``,
+  `- Cockpit next action: \`${cockpit.next_best_action.action}\``,
+  `- Feature mappings: \`${traceability.coverage_summary.mapped_feature_count}\``,
+  `- Evidence-backed mappings: \`${traceability.coverage_summary.evidence_backed_mapping_count}\``,
+  `- Multi-source feedback verdict: \`${feedback.verdict}\``,
+  `- Blocking findings: \`${feedback.blocking_findings.length}\``,
+  `- Kaizen refs: \`${feedback.kaizen_refs.join(", ")}\``,
+  "",
+  "## Baseline Comparison",
+  "",
+  `- Baseline context units: \`${baselineComparison.baseline.context_units}\``,
+  `- Mirai Graph context units: \`${baselineComparison.mirai_graph.context_units}\``,
+  `- Context reduction: \`${baselineComparison.outcome.context_reduction_percent}%\``,
+  `- Baseline missed dependencies: \`${baselineComparison.baseline.missed_dependencies}\``,
+  `- Mirai Graph missed dependencies: \`${baselineComparison.mirai_graph.missed_dependencies}\``,
+  `- Verdict: \`${baselineComparison.outcome.verdict}\``,
+  "",
+  "## What This Demonstrates",
+  "",
+  "- Mirai Graph can validate a graph package.",
+  "- Mirai Graph can generate task-specific context from graph state.",
+  "- Launch records describe bounded work permission.",
+  "- Process transitions are checked and explained against an executable state machine.",
+  "- Process-control contracts bind launch, evidence, recovery and Kaizen policy.",
+  "- Instrumentation connects cockpit signals, feature traceability and multi-source feedback.",
+  "- Baseline comparison records synthetic measurement boundaries.",
+  "",
+  "## Boundaries",
+  "",
+  "- This is a public-safe synthetic demo.",
+  "- Generated context is not canonical state.",
+  "- Evidence and proposals do not authorize canonical updates.",
+  "- Synthetic evidence is not broad scientific proof."
+];
+
+console.log(lines.join("\n"));

package/packages/cli/readiness-score.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function usage() {
+  console.error("Usage: node packages/cli/readiness-score.js <package-dir> [--target-mode discovery|canonical|pilot|controlled_runtime|production_runtime] [--write <output-file>]");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function findManifestPath(packageDir) {
+  return path.join(packageDir, "mirai-graph-package.json");
+}
+
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+function scorePackage(packageDir, targetMode) {
+  const manifestPath = findManifestPath(packageDir);
+  const graphObjectsPath = path.join(packageDir, "graph", "objects.json");
+  const graphRelationsPath = path.join(packageDir, "graph", "relations.json");
+  const gateResultsPath = path.join(packageDir, "gates", "results.json");
+
+  const evidence = [];
+  const blockers = [];
+  const manifest = exists(manifestPath) ? readJson(manifestPath) : null;
+  let score = 0;
+
+  if (manifest) {
+    score += 10;
+    evidence.push("package manifest exists");
+  } else {
+    blockers.push("missing package manifest");
+  }
+
+  if (exists(graphObjectsPath) && exists(graphRelationsPath)) {
+    const objects = readJson(graphObjectsPath);
+    const relations = readJson(graphRelationsPath);
+    if (Array.isArray(objects) && objects.length > 0) {
+      score += 15;
+      evidence.push(`objects exist: ${objects.length}`);
+    }
+    if (Array.isArray(relations)) {
+      score += 10;
+      evidence.push(`relations exist: ${relations.length}`);
+    }
+    const evidenceObjects = Array.isArray(objects)
+      ? objects.filter((object) => object.kind === "evidence").length
+      : 0;
+    if (evidenceObjects > 0) {
+      score += 15;
+      evidence.push(`evidence objects exist: ${evidenceObjects}`);
+    }
+    const acceptedObjects = Array.isArray(objects)
+      ? objects.filter((object) => object.readiness === "accepted").length
+      : 0;
+    if (acceptedObjects > 0) {
+      score += 10;
+      evidence.push(`accepted objects exist: ${acceptedObjects}`);
+    }
+  } else {
+    blockers.push("missing graph objects or relations");
+  }
+
+  if (exists(gateResultsPath)) {
+    const gateResults = readJson(gateResultsPath);
+    if (Array.isArray(gateResults) && gateResults.length > 0) {
+      score += 15;
+      evidence.push(`gate results exist: ${gateResults.length}`);
+    }
+  }
+
+  const contextPackPath = path.join(packageDir, "expected", "context-pack-compact.md");
+  if (exists(contextPackPath)) {
+    score += 10;
+    evidence.push("context pack example exists");
+  }
+
+  const metricsPath = path.join(packageDir, "metrics", "example-metrics.json");
+  if (exists(metricsPath)) {
+    score += 10;
+    evidence.push("benchmark metric example exists");
+  }
+
+  const caps = [];
+  if (blockers.length > 0) {
+    caps.push({ reason: "structural blockers exist", max_score: 39 });
+  }
+  if (targetMode !== "discovery" && !exists(gateResultsPath)) {
+    caps.push({ reason: "no gate results for non-discovery target", max_score: 59 });
+  }
+  if (["pilot", "controlled_runtime", "production_runtime"].includes(targetMode) && !exists(metricsPath)) {
+    caps.push({ reason: "no benchmark evidence for pilot/runtime target", max_score: 69 });
+  }
+  if (
+    manifest &&
+    typeof manifest.public_safety === "string" &&
+    manifest.public_safety.includes("synthetic") &&
+    ["pilot", "controlled_runtime", "production_runtime"].includes(targetMode)
+  ) {
+    caps.push({ reason: "synthetic-only evidence cannot exceed pilot-ready navigation score", max_score: 69 });
+  }
+  if (["controlled_runtime", "production_runtime"].includes(targetMode)) {
+    caps.push({ reason: "runtime policy is not implemented in public alpha", max_score: 74 });
+  }
+
+  for (const cap of caps) {
+    score = Math.min(score, cap.max_score);
+  }
+
+  return {
+    schema_version: "0.1.0",
+    target_mode: targetMode,
+    score,
+    band: score < 20
+      ? "G0_raw"
+      : score < 40
+        ? "G1_extracted"
+        : score < 60
+          ? "G2_canonical"
+          : score < 75
+            ? "G3_pilot_ready"
+            : score < 90
+              ? "G4_controlled_runtime_candidate"
+              : "G5_runtime_stable",
+    evidence,
+    blockers,
+    caps,
+    note: "Release-candidate readiness score; use as navigation, not approval."
+  };
+}
+
+const packageDir = process.argv[2];
+const targetModeIndex = process.argv.indexOf("--target-mode");
+const writeFlagIndex = process.argv.indexOf("--write");
+const targetMode = targetModeIndex >= 0 ? process.argv[targetModeIndex + 1] : "discovery";
+const outputPath = writeFlagIndex >= 0 ? process.argv[writeFlagIndex + 1] : null;
+
+if (!packageDir || (targetModeIndex >= 0 && !targetMode) || (writeFlagIndex >= 0 && !outputPath)) {
+  usage();
+  process.exit(2);
+}
+
+try {
+  const result = scorePackage(path.resolve(packageDir), targetMode);
+  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);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}