mirai-graph 1.0.0-rc.1

package/packages/cli/adopter-workflow.js

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+
+const profiles = [
+  {
+    role: "developer",
+    aliases: ["developer", "software", "software_specification", "engineer"],
+    profile: "software_specification",
+    starter: "templates/software-project-starter",
+    useWhen: "features, requirements, components, implementation tasks and technical risks",
+    nextCommands: [
+      "node packages/cli/mirai-graph.js validate templates/software-project-starter",
+      "node packages/cli/mirai-graph.js report validation templates/software-project-starter",
+      "node packages/cli/mirai-graph.js adopter report templates/software-project-starter"
+    ]
+  },
+  {
+    role: "researcher",
+    aliases: ["researcher", "research", "science", "project_management"],
+    profile: "project_management",
+    starter: "templates/research-program-starter",
+    useWhen: "hypotheses, evidence, milestones, review gates and publication risks",
+    nextCommands: [
+      "node packages/cli/mirai-graph.js validate templates/research-program-starter",
+      "node packages/cli/mirai-graph.js report validation templates/research-program-starter",
+      "node packages/cli/mirai-graph.js adopter report templates/research-program-starter"
+    ]
+  },
+  {
+    role: "ai-employee",
+    aliases: ["ai-employee", "ai_employee", "agent", "ai", "employee"],
+    profile: "ai_employee",
+    starter: "templates/ai-employee-starter",
+    useWhen: "AI worker roles, skills, tools, policies, actions, feedback and learning gates",
+    nextCommands: [
+      "node packages/cli/mirai-graph.js validate templates/ai-employee-starter",
+      "node packages/cli/mirai-graph.js report validation templates/ai-employee-starter",
+      "node packages/cli/mirai-graph.js adopter report templates/ai-employee-starter"
+    ]
+  },
+  {
+    role: "character-layer",
+    aliases: ["character-layer", "character_layer", "character", "behavior", "behaviour", "behavior-governance"],
+    profile: "character_layer",
+    starter: "templates/character-layer-starter",
+    useWhen: "behavior constitution, role character profiles, reflection, violation patterns and correction loops",
+    nextCommands: [
+      "node packages/cli/mirai-graph.js validate templates/character-layer-starter",
+      "node packages/cli/mirai-graph.js report validation templates/character-layer-starter",
+      "node packages/cli/mirai-graph.js adopter report templates/character-layer-starter"
+    ]
+  },
+  {
+    role: "organization",
+    aliases: ["organization", "org", "governance", "organization_governance"],
+    profile: "organization_governance",
+    starter: "templates/organization-governance-starter",
+    useWhen: "mission, strategy, departments, programs, policies, controls and metrics",
+    nextCommands: [
+      "node packages/cli/mirai-graph.js validate templates/organization-governance-starter",
+      "node packages/cli/mirai-graph.js report validation templates/organization-governance-starter",
+      "node packages/cli/mirai-graph.js adopter report templates/organization-governance-starter"
+    ]
+  }
+];
+
+function usage() {
+  console.error("Usage:");
+  console.error("  adopter-workflow choose-profile");
+  console.error("  adopter-workflow plan <role-or-profile>");
+  console.error("  adopter-workflow report <template-dir>");
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function resolveProfile(input) {
+  const normalized = String(input || "").trim().toLowerCase().replace(/_/g, "-");
+  return profiles.find((item) => {
+    if (item.role === normalized) return true;
+    if (item.profile.replace(/_/g, "-") === normalized) return true;
+    return item.aliases.some((alias) => alias.replace(/_/g, "-") === normalized);
+  });
+}
+
+function printProfileMap() {
+  console.log("# Mirai Graph Profile Selection");
+  console.log("");
+  console.log("| Role | Profile | Starter | Use when |");
+  console.log("| --- | --- | --- | --- |");
+  for (const item of profiles) {
+    console.log(`| ${item.role} | \`${item.profile}\` | \`${item.starter}\` | ${item.useWhen} |`);
+  }
+  console.log("");
+  console.log("Boundary: profile selection is a starting point, not adoption proof.");
+}
+
+function printPlan(input) {
+  const item = resolveProfile(input);
+  if (!item) {
+    console.error(`Unknown role or profile: ${input}`);
+    console.error(`Known roles: ${profiles.map((profile) => profile.role).join(", ")}`);
+    process.exit(1);
+  }
+
+  console.log(`# Mirai Graph Adopter Plan: ${item.role}`);
+  console.log("");
+  console.log(`- Profile: \`${item.profile}\``);
+  console.log(`- Starter: \`${item.starter}\``);
+  console.log(`- Use when: ${item.useWhen}.`);
+  console.log("");
+  console.log("## First Workflow");
+  console.log("");
+  console.log("```text");
+  console.log("choose profile -> copy starter -> replace synthetic objects -> validate -> report -> launch/evidence/kaizen");
+  console.log("```");
+  console.log("");
+  console.log("## Commands");
+  console.log("");
+  console.log("```bash");
+  for (const command of item.nextCommands) {
+    console.log(command);
+  }
+  console.log("```");
+  console.log("");
+  console.log("## Review Boundary");
+  console.log("");
+  console.log("- Validation confirms the current release-candidate package shape only.");
+  console.log("- Reports support review; they do not authorize canonical updates.");
+  console.log("- Add launch, evidence and Kaizen controls before using the package for governed work.");
+}
+
+function templateReport(templateDir) {
+  const absTemplate = path.resolve(root, templateDir);
+  const manifestPath = path.join(absTemplate, "mirai-graph-package.json");
+  const objectsPath = path.join(absTemplate, "graph", "objects.json");
+  const relationsPath = path.join(absTemplate, "graph", "relations.json");
+  const gatesPath = path.join(absTemplate, "gates", "results.json");
+
+  const missing = [manifestPath, objectsPath, relationsPath].filter((filePath) => !fs.existsSync(filePath));
+  if (missing.length > 0) {
+    console.error(`Template is missing required files: ${missing.map((filePath) => path.relative(root, filePath)).join(", ")}`);
+    process.exit(1);
+  }
+
+  const manifest = readJson(manifestPath);
+  const objects = readJson(objectsPath);
+  const relations = readJson(relationsPath);
+  const gates = fs.existsSync(gatesPath) ? readJson(gatesPath) : [];
+  const profile = profiles.find((item) => item.profile === manifest.profile);
+
+  console.log(`# Mirai Graph Adopter Report: ${manifest.name}`);
+  console.log("");
+  console.log(`- Package: \`${manifest.id}\``);
+  console.log(`- Profile: \`${manifest.profile}\``);
+  console.log(`- Conformance: \`${manifest.conformance_level || "unspecified"}\``);
+  console.log(`- Public safety: \`${manifest.public_safety || "unspecified"}\``);
+  console.log(`- Objects: \`${objects.length}\``);
+  console.log(`- Relations: \`${relations.length}\``);
+  console.log(`- Gate results: \`${gates.length}\``);
+  console.log("");
+
+  if (profile) {
+    console.log("## Recommended Next Commands");
+    console.log("");
+    console.log("```bash");
+    for (const command of profile.nextCommands) {
+      console.log(command.replace(profile.starter, templateDir));
+    }
+    console.log("```");
+    console.log("");
+  }
+
+  console.log("## Adoption Checklist");
+  console.log("");
+  console.log("- Replace synthetic objects with project-specific objects.");
+  console.log("- Keep private source material outside public graph packages.");
+  console.log("- Run validation before adding launch or process-control artifacts.");
+  console.log("- Add evidence references before promoting readiness.");
+  console.log("- Add launch/evidence/Kaizen controls before governed execution.");
+  console.log("");
+  console.log("## Boundary");
+  console.log("");
+  console.log("This report is an adoption aid. It does not prove completeness, authorize production execution or update canonical graph state.");
+}
+
+const [command, ...args] = process.argv.slice(2);
+
+if (!command || command === "--help" || command === "-h") {
+  usage();
+  process.exit(command ? 0 : 1);
+}
+
+if (command === "choose-profile") {
+  if (args.length !== 0) {
+    usage();
+    process.exit(1);
+  }
+  printProfileMap();
+  process.exit(0);
+}
+
+if (command === "plan") {
+  if (args.length !== 1) {
+    usage();
+    process.exit(1);
+  }
+  printPlan(args[0]);
+  process.exit(0);
+}
+
+if (command === "report") {
+  if (args.length !== 1) {
+    usage();
+    process.exit(1);
+  }
+  templateReport(args[0]);
+  process.exit(0);
+}
+
+usage();
+process.exit(1);

package/packages/cli/context-pack.js

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function usage() {
+  console.error("Usage: node packages/cli/context-pack.js <package-dir> --task-id <task-id> [--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 normalizeToken(token) {
+  const normalized = token.toLowerCase();
+  const replacements = new Map([
+    ["notification", "notify"],
+    ["notifications", "notify"],
+    ["notifying", "notify"],
+    ["approval", "approve"],
+    ["approved", "approve"],
+    ["approving", "approve"],
+    ["schedule", "schedule"],
+    ["speaker", "speaker"],
+    ["session", "session"],
+    ["sessions", "session"]
+  ]);
+  if (replacements.has(normalized)) {
+    return replacements.get(normalized);
+  }
+  return normalized
+    .replace(/[^a-z0-9_]+/g, "")
+    .replace(/(ing|ed|ions|ion|s)$/u, "");
+}
+
+function tokenize(text) {
+  return String(text)
+    .split(/[^a-zA-Z0-9]+/u)
+    .map(normalizeToken)
+    .filter((token) => token.length >= 3);
+}
+
+function objectText(object) {
+  return [
+    object.id,
+    object.kind,
+    object.title,
+    object.summary,
+    object.profile
+  ].join(" ");
+}
+
+function addReason(selectionReasons, objectId, reason) {
+  if (!selectionReasons.has(objectId)) {
+    selectionReasons.set(objectId, new Set());
+  }
+  selectionReasons.get(objectId).add(reason);
+}
+
+function hasSharedEvidence(object, evidenceIds) {
+  return Array.isArray(object.evidence) && object.evidence.some((id) => evidenceIds.has(id));
+}
+
+function isSafetyContextObject(object) {
+  if (!["constraint", "risk", "governance_gate"].includes(object.kind) && !object.id.startsWith("gate.")) {
+    return false;
+  }
+  const text = tokenize(objectText(object));
+  const safetyTokens = new Set([
+    "credential",
+    "leak",
+    "log",
+    "permission",
+    "privacy",
+    "public",
+    "safety",
+    "secret",
+    "security",
+    "token"
+  ]);
+  return text.some((token) => safetyTokens.has(token));
+}
+
+function scoreObject(object, taskTokens) {
+  const text = tokenize(objectText(object));
+  const textSet = new Set(text);
+  let score = 0;
+  const reasons = [];
+  for (const token of taskTokens) {
+    if (textSet.has(token)) {
+      score += 3;
+      reasons.push(`exact token match: ${token}`);
+    } else if (text.some((candidate) => candidate.includes(token) || token.includes(candidate))) {
+      score += 1;
+      reasons.push(`partial token match: ${token}`);
+    }
+  }
+  if (object.kind === "evidence") {
+    score -= 1;
+    reasons.push("evidence object penalty until linked by selected graph context");
+  }
+  if (object.kind === "governance_gate" || object.id.startsWith("gate.")) {
+    score += 1;
+    reasons.push("governance gate boost");
+  }
+  return { score, reasons };
+}
+
+function buildContextPack(packageDir, taskId) {
+  const manifestPath = findManifestPath(packageDir);
+  const manifest = fs.existsSync(manifestPath) ? readJson(manifestPath) : null;
+  const objectsPath = manifest
+    ? path.join(packageDir, manifest.graph.objects)
+    : path.join(packageDir, "graph", "objects.json");
+  const relationsPath = manifest
+    ? path.join(packageDir, manifest.graph.relations)
+    : path.join(packageDir, "graph", "relations.json");
+  const objects = readJson(objectsPath);
+  const relations = readJson(relationsPath);
+  const taskTokens = tokenize(taskId);
+  const scoredObjects = objects.map((object) => ({
+    object,
+    ...scoreObject(object, taskTokens)
+  }));
+  const directMatches = objects
+    .map((object) => scoredObjects.find((entry) => entry.object.id === object.id))
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .map((entry) => entry.object);
+
+  const selectedIds = new Set(directMatches.map((object) => object.id));
+  const selectionReasons = new Map();
+  const objectScores = new Map(scoredObjects.map((entry) => [entry.object.id, entry.score]));
+
+  for (const entry of scoredObjects) {
+    if (entry.score > 0) {
+      for (const reason of entry.reasons) {
+        addReason(selectionReasons, entry.object.id, reason);
+      }
+    }
+  }
+
+  const relevantRelations = relations.filter((relation) => (
+    selectedIds.has(relation.source) || selectedIds.has(relation.target)
+  ));
+  const relevantRelationIds = new Set(relevantRelations.map((relation) => relation.id));
+
+  for (const relation of relevantRelations) {
+    if (!selectedIds.has(relation.source)) {
+      addReason(selectionReasons, relation.source, `one-hop relation expansion from ${relation.id}`);
+    }
+    if (!selectedIds.has(relation.target)) {
+      addReason(selectionReasons, relation.target, `one-hop relation expansion from ${relation.id}`);
+    }
+    selectedIds.add(relation.source);
+    selectedIds.add(relation.target);
+  }
+
+  const selectedEvidenceIds = new Set(
+    objects
+      .filter((object) => selectedIds.has(object.id))
+      .flatMap((object) => object.evidence || [])
+  );
+
+  for (const object of objects) {
+    if (isSafetyContextObject(object) && hasSharedEvidence(object, selectedEvidenceIds)) {
+      if (!selectedIds.has(object.id)) {
+        addReason(selectionReasons, object.id, "safety-sensitive object with shared evidence");
+      }
+      selectedIds.add(object.id);
+    }
+  }
+
+  const expandedRelations = relations.filter((relation) => (
+    selectedIds.has(relation.source) && selectedIds.has(relation.target)
+  ));
+
+  const selectedObjects = objects.filter((object) => (
+    selectedIds.has(object.id) ||
+    (object.kind === "evidence" && objects.some((selected) => (
+      selectedIds.has(selected.id) && Array.isArray(selected.evidence) && selected.evidence.includes(object.id)
+    )))
+  ));
+  for (const object of selectedObjects) {
+    if (object.kind === "evidence" && !selectedIds.has(object.id)) {
+      addReason(selectionReasons, object.id, "evidence referenced by selected object");
+    }
+  }
+  const selectedObjectIds = selectedObjects.map((object) => object.id);
+  const relationIds = expandedRelations.map((relation) => relation.id);
+  const relationExplanations = expandedRelations.map((relation) => ({
+    id: relation.id,
+    reason: relevantRelationIds.has(relation.id)
+      ? "one-hop relation expansion from direct object match"
+      : "connects selected objects after safety/evidence expansion",
+    source: relation.source,
+    target: relation.target
+  }));
+  const objectExplanations = selectedObjects.map((object) => ({
+    id: object.id,
+    relevance_score: objectScores.get(object.id) || 0,
+    reasons: Array.from(selectionReasons.get(object.id) || ["included as selected graph context"])
+  }));
+  const evidence = Array.from(new Set([
+    ...selectedObjects.flatMap((object) => object.evidence || []),
+    ...expandedRelations.flatMap((relation) => relation.evidence || [])
+  ]));
+  const omittedObjects = objects
+    .filter((object) => !selectedObjectIds.includes(object.id))
+    .map((object) => object.id);
+
+  return {
+    id: `context_pack.${taskId.replace(/[^a-zA-Z0-9_]+/g, "_")}`,
+    task_id: taskId,
+    source_graph: manifest ? manifest.id : packageDir,
+    generated_at: new Date().toISOString(),
+    included_objects: selectedObjectIds,
+    included_relations: relationIds,
+    evidence,
+    selection: {
+      method: "token_matching_one_hop_relation_expansion_safety_shared_evidence",
+      task_tokens: taskTokens,
+      object_explanations: objectExplanations,
+      relation_explanations: relationExplanations
+    },
+    assumptions: [
+      "Alpha generator uses token matching plus one-hop relation expansion.",
+      "Safety-sensitive constraints and risks with shared evidence are included."
+    ],
+    omissions: omittedObjects,
+    limitations: [
+      "Generated context pack is not canonical state.",
+      "This alpha generator does not prove semantic completeness."
+    ]
+  };
+}
+
+const packageDir = process.argv[2];
+const taskIndex = process.argv.indexOf("--task-id");
+const writeIndex = process.argv.indexOf("--write");
+const taskId = taskIndex >= 0 ? process.argv[taskIndex + 1] : null;
+const outputPath = writeIndex >= 0 ? process.argv[writeIndex + 1] : null;
+
+if (!packageDir || !taskId || (writeIndex >= 0 && !outputPath)) {
+  usage();
+  process.exit(2);
+}
+
+try {
+  const contextPack = buildContextPack(path.resolve(packageDir), taskId);
+  const output = JSON.stringify(contextPack, 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);
+}

package/packages/cli/instrumentation-report.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function list(items, emptyText) {
+  if (!items || items.length === 0) {
+    return `- ${emptyText}`;
+  }
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+const packageDir = process.argv[2] || "examples/instrumentation-layer-minimal";
+const resultsDir = path.join(packageDir, "results");
+const cockpit = readJson(path.join(resultsDir, "development-cockpit.json"));
+const traceability = readJson(path.join(resultsDir, "feature-implementation-traceability.json"));
+const feedback = readJson(path.join(resultsDir, "multi-source-quality-feedback.json"));
+
+const cockpitInstruments = cockpit.instruments.map(
+  (instrument) => `\`${instrument.id}\` ${instrument.family}: ${instrument.score}/${100} (${instrument.band})`
+);
+const mappings = traceability.implementation_mappings.map(
+  (mapping) => `\`${mapping.feature_ref}\` -> ${mapping.implementation_refs.length} implementation refs, ${mapping.test_refs.length} test refs, ${mapping.evidence_refs.length} evidence refs`
+);
+const findings = feedback.findings.map(
+  (finding) => `\`${finding.id}\` ${finding.classification}, severity ${finding.severity}, blocking ${finding.blocking ? "true" : "false"}, route ${finding.next_route}`
+);
+
+const lines = [
+  "# Mirai Graph Instrumentation Report",
+  "",
+  `- Package: \`${packageDir}\``,
+  `- Cockpit: \`${cockpit.id}\``,
+  `- Traceability: \`${traceability.id}\``,
+  `- Multi-source feedback: \`${feedback.id}\``,
+  `- Transition verdict: \`${feedback.verdict}\``,
+  `- Next transition: \`${feedback.next_transition}\``,
+  "",
+  "## Control Pattern",
+  "",
+  "```text",
+  "feature intent -> implementation traceability -> cockpit signals -> multi-source feedback -> transition decision -> Kaizen route",
+  "```",
+  "",
+  "## Cockpit",
+  "",
+  `- Subject: \`${cockpit.subject_ref}\``,
+  `- Production readiness: \`${cockpit.readiness.production_readiness}\``,
+  `- Next action: \`${cockpit.next_best_action.action}\``,
+  `- Target cycle: \`${cockpit.next_best_action.target_cycle}\``,
+  "",
+  "### Instruments",
+  "",
+  list(cockpitInstruments, "No cockpit instruments declared."),
+  "",
+  "### Required Gates",
+  "",
+  list(cockpit.next_best_action.required_gates, "No required gates declared."),
+  "",
+  "## Traceability",
+  "",
+  `- Features: \`${traceability.coverage_summary.feature_count}\``,
+  `- Mapped features: \`${traceability.coverage_summary.mapped_feature_count}\``,
+  `- Evidence-backed mappings: \`${traceability.coverage_summary.evidence_backed_mapping_count}\``,
+  `- Accepted features: \`${traceability.coverage_summary.accepted_feature_count}\``,
+  "",
+  "### Mappings",
+  "",
+  list(mappings, "No mappings declared."),
+  "",
+  "## Multi-Source Feedback",
+  "",
+  `- Sources: \`${feedback.sources.length}\``,
+  `- Findings: \`${feedback.findings.length}\``,
+  `- Blocking findings: \`${feedback.blocking_findings.length}\``,
+  "",
+  "### Findings",
+  "",
+  list(findings, "No findings declared."),
+  "",
+  "### Kaizen Refs",
+  "",
+  list(feedback.kaizen_refs, "No Kaizen refs declared."),
+  "",
+  "## Boundary",
+  "",
+  "- Cockpit scores are not acceptance.",
+  "- Feature mappings are not implementation by themselves.",
+  "- Tests and evidence do not authorize canonical updates.",
+  "- Multi-source feedback calibrates transition decisions; blocking findings stop the transitions they block."
+];
+
+console.log(lines.join("\n"));