mirai-graph 1.0.0-rc.1

package/docs/transfer/skill-graph-standard-harvest-2026-05-31.md

@@ -0,0 +1,113 @@
+# Skill Graph Standard Harvest
+
+Date: 2026-05-31
+Status: public-safe transfer note
+
+## Purpose
+
+This note records which reusable patterns from graph-managed skill work were
+converted into public Mirai Graph standard artifacts.
+
+It does not publish private skill internals, customer material, internal
+runtime paths, private metrics or implementation playbooks.
+
+## Transferred Patterns
+
+### Hybrid Source Of Truth
+
+Graph-managed skills need a boundary between generated graph context and raw
+owner sources. The public standard now records this as
+[Hybrid Source Of Truth](../../standard/hybrid-source-of-truth.md).
+
+Reusable idea:
+
+```text
+graph = routing, context, control, readiness and evidence layer
+raw source = authoritative methodology, judgement and sensitive rules
+```
+
+### Adoption Levels
+
+Practical graph adoption is staged. Valid JSON, a seed or a context pack is not
+enough to claim migration. The public standard now records staged Mirai Graph
+Adoption Levels in [Adoption Levels](../../standard/adoption-levels.md).
+
+Reusable idea:
+
+```text
+inventory -> seed -> embryo -> scored -> gated -> semantic review
+-> effectiveness -> federation -> graph-first source candidate
+```
+
+### Runtime Enablement
+
+Graph context can support runtime tasks only when the task is measured, bounded
+and covered by policy. Sensitive work still requires raw-source fallback. The
+public standard now records this in
+[Runtime Enablement](../../standard/runtime-enablement.md).
+
+Reusable idea:
+
+```text
+generated context != authorization
+runtime decision != executed action
+feedback != canonical update
+```
+
+### Projection Views
+
+Dense graphs need user-facing generated views for readiness, risk, owner
+routing, gates, evidence, adoption and runtime policy. The public standard now
+records this in [Projection Views](../../standard/projection-views.md).
+
+### Skill Runtime Profile
+
+The profile-level pattern is now captured in
+[Skill Runtime](../../profiles/skill-runtime/README.md) with an executable
+synthetic fixture at:
+
+```text
+examples/skill-runtime-minimal/
+```
+
+The profile is for governed skills, capability modules and services. It is
+not specific to one organization, one AI framework or one internal skill set.
+
+## Public Artifacts Added
+
+- `standard/hybrid-source-of-truth.md`;
+- `standard/adoption-levels.md`;
+- `standard/runtime-enablement.md`;
+- `standard/projection-views.md`;
+- `profiles/skill-runtime/profile.json`;
+- `profiles/skill-runtime/README.md`;
+- `examples/skill-runtime-minimal/`.
+
+## Claims Preserved
+
+The new artifacts support only limited claims:
+
+- profile shape conformance;
+- public-safe representation of runtime boundaries;
+- staged adoption terminology;
+- Hybrid Source Of Truth boundary;
+- synthetic example validity.
+
+They do not prove:
+
+- semantic completeness;
+- operational effectiveness;
+- runtime safety;
+- graph-only source-of-truth readiness;
+- universal validity.
+
+## Verification
+
+The added profile and fixture are covered by:
+
+```bash
+npm run validate:profiles
+npm run validate:skill-runtime
+npm run validate:profile-results
+npm run release:check
+```

package/docs/transfer/standard-gap-report-2026-05-28.md

@@ -0,0 +1,208 @@
+# Mirai Graph Standard Gap Report
+
+Date: 2026-05-28
+
+Status: initial public-safe comparison
+
+Historical note:
+
+This report is retained as the initial transfer baseline. The current public
+capability map is `docs/transfer/graph-capability-map-2026-05-29.md`.
+
+## Purpose
+
+This report compares the practical `$graph` skill methodology with the public
+Mirai Graph repository.
+
+The goal is not to copy private implementation details. The goal is to identify
+which reusable concepts should become public standard sections, schemas,
+profiles, tooling, experiments or publication artifacts.
+
+## Sources Compared
+
+Practical source:
+
+`$graph` skill methodology and public-safe reference names.
+
+Public target:
+
+Mirai Graph public repository after `0.1.0-alpha.0` plus the practice/science bridge.
+
+## Summary Verdict
+
+Mirai Graph public repository status:
+
+`foundation_ready_with_major_method_gaps`
+
+Reason:
+
+The public repository now has a coherent foundation: standard draft, schemas,
+validator, examples, synthetic benchmark, adoption guide and research/practice
+program framing. However, the practical `$graph` skill contains more mature
+methodology for graph seed growth, human control surfaces, readiness scoring,
+rollout, runtime gating, migration, federation and measured conversion.
+
+The next phase should transfer the reusable parts into public-safe Mirai Graph
+standard sections and tooling.
+
+## Gap Classes
+
+### Class A: Standard Gaps
+
+These are reusable model concepts that should become public standard sections.
+
+| Gap | Practical `$graph` capability | Current Mirai Graph status | Recommended public artifact |
+| --- | --- | --- | --- |
+| Graph DNA | Defines why the graph exists, its evolution vector and non-negotiable principles. | Mentioned indirectly only. | `standard/graph-dna.md` |
+| Graph Seed | Controlled growth contract for starting complex graphs safely. | Mentioned in docs, not standardized. | `standard/graph-seed.md`, `schemas/graph-seed.schema.json` |
+| Graph Embryo | Reviewable candidate graph before canonical write. | Not defined as standard artifact. | `standard/graph-embryo.md`, `schemas/graph-embryo.schema.json` |
+| Projection Views | Human-facing slices such as readiness, risk, impact and approval queue. | Not present. | `standard/projection-views.md` |
+| Proposal/Approval Flow | Generated analysis -> proposal -> review -> dry-run -> approved apply -> validate. | Governance is conceptual only. | `standard/proposal-approval.md` |
+| Readiness Score | Target-mode readiness bands and caps. | Conformance exists, but no GRS. | `standard/readiness-score.md`, schema |
+| Content Quality Score | Separate content fitness from graph structure. | Not present. | `standard/content-quality.md` or profile note |
+| Impact Review | Relation impact traversal for changed objects. | Relation model is basic. | Expand `standard/relation-model.md` |
+| Schema Migrations | Versioning, migration dry-run, reports and review gates. | Not present. | `standard/versioning-migrations.md` |
+| Federation | Cross-graph export, handshake, query and compatibility. | Not present. | Later `standard/federation.md` |
+
+### Class B: Tooling Gaps
+
+These should become validators, generators, schemas or CLI commands.
+
+| Gap | Current Public State | Recommended Tooling |
+| --- | --- | --- |
+| Context-pack generation | Documented, not generated. | `mirai-graph context generate` |
+| Graph seed validation | Not present. | `mirai-graph seed validate` |
+| Embryo preview | Not present. | `mirai-graph seed preview` |
+| Readiness scoring | Not present. | `mirai-graph readiness --target-mode` |
+| Proposal bundle | Not present. | `mirai-graph proposal bundle/review/apply` |
+| Migration dry-run | Not present. | `mirai-graph migrate --dry-run` |
+| Benchmark runner output | Only simple synthetic metric script. | Machine-readable benchmark result writer |
+| Negative fixtures | Not present. | `examples/invalid-*` fixtures |
+| Profile validation | Profiles are descriptive only. | `profile.schema.json` and strict profile fixtures |
+
+### Class C: Research Gaps
+
+These gaps need experiment design before strong scientific claims.
+
+| Research Gap | Why It Matters | Recommended Artifact |
+| --- | --- | --- |
+| Current-mode vs graph-mode comparison | Need measured improvement, not assumption. | `benchmarks/protocols/measure-convert-optimize.md` |
+| Semantic completeness | Context reduction may lose meaning. | semantic review rubric and EXP-002 |
+| Ablation | Need know which layers matter. | EXP-003 protocol |
+| Cross-domain replication | Need evidence beyond one internal domain. | EXP-004 protocol |
+| Runtime safety | Action-capable graph use needs gates. | EXP-007 protocol |
+| Human control surface quality | Dense graphs need usable projection views. | user-review protocol |
+
+### Class D: Profile Gaps
+
+These are domain adaptations that should not bloat the core standard.
+
+| Profile | Current State | Recommended Next Step |
+| --- | --- | --- |
+| `software_specification` | Synthetic benchmark uses it informally. | Create profile manifest and allowed object/relation list. |
+| `project_management` | Mentioned only. | Draft profile with goals, tasks, risks, milestones, decisions. |
+| `organization_governance` | Mentioned only. | Draft governance-oriented object/relation families. |
+| `research_program` | Implied by this work. | Draft profile for experiments, evidence, manuscripts and publications. |
+| `human_ai_system` | Mentioned only. | Draft profile for agents, roles, tools, context packs and gates. |
+
+### Class E: Private Or Implementation-Only Areas
+
+These should not be copied directly into the public standard.
+
+- private project materials;
+- raw skill internals not approved for release;
+- internal rollout records;
+- customer or employee data;
+- secret-handling implementation details;
+- private runtime paths;
+- organization-specific policies that are not generalized.
+
+Public Mirai Graph can define the abstract standard and public-safe tooling
+without publishing private operational material.
+
+## Priority Transfer Plan
+
+### P0: Make Public Mirai Graph A Better Standard
+
+1. `standard/graph-dna.md`
+2. `standard/graph-seed.md`
+3. `standard/graph-embryo.md`
+4. `standard/projection-views.md`
+5. `standard/readiness-score.md`
+
+Why first:
+
+These explain how a graph grows and how humans control it. Without them,
+Mirai Graph looks like a static knowledge-graph format rather than an operating
+model for managed growth.
+
+### P1: Make Public Mirai Graph More Usable
+
+1. `schemas/graph-seed.schema.json`
+2. `schemas/graph-embryo.schema.json`
+3. `schemas/projection-view.schema.json`
+4. CLI seed validation.
+5. CLI readiness scoring.
+
+Why second:
+
+The repository should not only describe the method. Developers should be able
+to test and use it.
+
+### P2: Make Public Mirai Graph Research-Ready
+
+1. Measure-convert-optimize public protocol.
+2. Semantic completeness review rubric.
+3. Benchmark result writer.
+4. Negative fixtures.
+5. Experiment backlog in public form.
+
+Why third:
+
+Scientific claims require measurement and repeatable evidence packages.
+
+### P3: Prepare Profiles
+
+1. `profiles/software-specification/`
+2. `profiles/project-management/`
+3. `profiles/research-program/`
+4. `profiles/organization-governance/`
+
+Why fourth:
+
+Profiles make the standard adoptable without turning the core into a giant
+domain-specific document.
+
+## Immediate Next Batch
+
+Recommended next implementation batch:
+
+1. Add `standard/graph-dna.md`.
+2. Add `standard/graph-seed.md`.
+3. Add `standard/graph-embryo.md`.
+4. Add `schemas/graph-seed.schema.json`.
+5. Add `examples/graph-seed-minimal/`.
+6. Extend CLI with seed validation.
+
+Acceptance:
+
+- `npm test` passes;
+- minimal seed fixture validates;
+- standard links updated;
+- no private implementation material is copied.
+
+## Publication Use
+
+This report can support future scientific work by showing:
+
+- the distinction between practical implementation and public standard;
+- the gap between current tooling and publishable evidence;
+- the plan for converting operational lessons into reproducible artifacts;
+- the need for measured validation before stronger claims.
+
+Potential manuscript use:
+
+- methodology maturation section;
+- limitations and future work;
+- standardization roadmap;
+- validation plan for v1.4 or a follow-up paper.

package/examples/ai-employee-minimal/README.md

@@ -0,0 +1,53 @@
+# Minimal AI Employee Example
+
+Status: synthetic alpha fixture
+
+## Purpose
+
+This example shows how the `ai_employee` profile can model a governed AI
+employee without treating the graph as an uncontrolled runtime.
+
+The fixture includes:
+
+- one AI employee;
+- one department and role;
+- one skill;
+- knowledge and memory references;
+- a tool and required capability;
+- an external-action policy and approval gate;
+- a workflow and proposed action;
+- an audited result;
+- feedback and a proposed lesson;
+- a federation endpoint placeholder.
+
+## Safety Boundary
+
+The fixture preserves this distinction:
+
+```text
+canonical graph state
+-> generated context
+-> runtime decision
+-> proposed action
+-> approval gate
+-> executed action
+-> audited result
+-> feedback
+-> learning proposal
+-> canonical graph update
+```
+
+It does not include real users, customer tickets, credentials, private runtime
+paths or provider-specific implementation details.
+
+## Validate
+
+```bash
+node packages/cli/validate-mirai-graph.js examples/ai-employee-minimal
+```
+
+Or run the full suite:
+
+```bash
+npm run release:check
+```

package/examples/ai-employee-minimal/gates/results.json

@@ -0,0 +1,35 @@
+[
+  {
+    "id": "gate_result.ai_employee_minimal.public_safety",
+    "gate_id": "public_safety_before_release",
+    "target_id": "package.ai_employee_minimal",
+    "verdict": "pass_with_notes",
+    "summary": "The fixture is synthetic and contains no private runtime, customer, employee or secret material.",
+    "reviewed_at": "2026-05-29",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ]
+  },
+  {
+    "id": "gate_result.ai_employee_minimal.action_boundary",
+    "gate_id": "approval_before_external_action",
+    "target_id": "action.propose_status_update",
+    "verdict": "pass_with_notes",
+    "summary": "The proposed action is modeled as requiring an approval gate before execution.",
+    "reviewed_at": "2026-05-29",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ]
+  },
+  {
+    "id": "gate_result.ai_employee_minimal.feedback_learning",
+    "gate_id": "feedback_learning_before_behavior_update",
+    "target_id": "lesson.require_clear_status_reason",
+    "verdict": "needs_more_evidence",
+    "summary": "The lesson is represented as a review-ready proposal, not an automatically accepted behavior update.",
+    "reviewed_at": "2026-05-29",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ]
+  }
+]

package/examples/ai-employee-minimal/graph/objects.json

@@ -0,0 +1,187 @@
+[
+  {
+    "id": "evidence.ai_employee_brief",
+    "kind": "evidence",
+    "title": "Synthetic AI Employee Brief",
+    "summary": "Public-safe synthetic brief for the minimal AI employee profile fixture.",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "department.support",
+    "kind": "ai_department",
+    "title": "Support Department",
+    "summary": "Synthetic department that owns the AI support employee.",
+    "readiness": "accepted",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "employee.support_assistant",
+    "kind": "ai_employee",
+    "title": "Support Assistant",
+    "summary": "Synthetic AI employee that helps triage support requests through governed actions.",
+    "readiness": "accepted",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "role.support_triage",
+    "kind": "role",
+    "title": "Support Triage Role",
+    "summary": "Role responsible for classifying requests, preparing answers and escalating risky cases.",
+    "readiness": "accepted",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "skill.ticket_classification",
+    "kind": "skill",
+    "title": "Ticket Classification",
+    "summary": "Skill for classifying support requests by topic, urgency and required owner.",
+    "readiness": "accepted",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "knowledge.support_policy",
+    "kind": "knowledge",
+    "title": "Support Policy Knowledge",
+    "summary": "Knowledge object that references the public-safe support policy used by the AI employee.",
+    "readiness": "review_ready",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "memory.recent_ticket_patterns",
+    "kind": "memory",
+    "title": "Recent Ticket Patterns",
+    "summary": "Memory object for reviewed patterns from recent support work.",
+    "readiness": "draft",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "tool.ticket_api",
+    "kind": "tool",
+    "title": "Ticket API",
+    "summary": "Tool adapter used by runtime to read and update support tickets.",
+    "readiness": "review_ready",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "capability.update_ticket_status",
+    "kind": "capability",
+    "title": "Update Ticket Status",
+    "summary": "Capability required before the runtime may update a ticket status through the Ticket API.",
+    "readiness": "review_ready",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "policy.approval_before_external_action",
+    "kind": "policy",
+    "title": "Approval Before External Action",
+    "summary": "Policy requiring approval before the AI employee performs external or user-visible actions.",
+    "readiness": "accepted",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "gate.external_action_approval",
+    "kind": "governance_gate",
+    "title": "External Action Approval Gate",
+    "summary": "Governance gate that separates proposed actions from executed actions.",
+    "readiness": "accepted",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "workflow.ticket_triage",
+    "kind": "workflow",
+    "title": "Ticket Triage Workflow",
+    "summary": "Workflow for classifying a support ticket, preparing a proposed action and recording the result.",
+    "readiness": "review_ready",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "action.propose_status_update",
+    "kind": "action",
+    "title": "Propose Status Update",
+    "summary": "Proposed runtime action to update a support ticket status after policy and approval checks.",
+    "readiness": "review_ready",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "result.status_update_audited",
+    "kind": "result",
+    "title": "Status Update Audited Result",
+    "summary": "Audited result recording whether the approved status update matched the expected outcome.",
+    "readiness": "draft",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "feedback.status_update_review",
+    "kind": "feedback",
+    "title": "Status Update Review Feedback",
+    "summary": "Feedback from reviewing the audited result of the ticket status update.",
+    "readiness": "draft",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "lesson.require_clear_status_reason",
+    "kind": "lesson",
+    "title": "Require Clear Status Reason",
+    "summary": "Proposed lesson that future ticket status updates should include a clear user-visible reason.",
+    "readiness": "review_ready",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  },
+  {
+    "id": "endpoint.ai_service_federation",
+    "kind": "federation_endpoint",
+    "title": "AI Service Federation Endpoint",
+    "summary": "Placeholder endpoint showing how this AI employee could federate with another AI service.",
+    "readiness": "draft",
+    "evidence": [
+      "evidence.ai_employee_brief"
+    ],
+    "profile": "ai_employee"
+  }
+]