mirai-graph 1.4.0 → 2.1.0

package/standard/technology-quality-feedback.md

@@ -1,97 +0,0 @@
-# Technology Quality Feedback
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Technology quality feedback checks whether completed work followed the declared
-technology, process or method before that work can be accepted, released or
-used as evidence for canonical change.
-
-It exists because passing tests, producing artifacts or collecting evidence can
-still hide process drift. A team needs a separate review loop that asks:
-
-```text
-Did the work follow the technology it claimed to follow?
-```
-
-## Core Pattern
-
-```text
-technology contract
--> work evidence
--> technology quality feedback
--> finding classification
--> transition decision
--> Kaizen / proposal / fix route
-```
-
-The feedback report is a gate artifact. It classifies findings and routes the
-next transition, but it does not execute actions or update canonical state.
-
-## Required Rules
-
-- Passing tests do not mean accepted work.
-- Evidence does not authorize release or canonical update.
-- Generated context and proposals do not mutate canonical state.
-- Every finding must be classified.
-- `process_improvement` findings route to Kaizen.
-- `spec_gap` findings route back to planning, human review or graph sync
-  proposal.
-- Blocking findings stop acceptance and release transitions.
-
-## Classifications
-
-Public Mirai Graph uses universal classifications:
-
-- `accepted`;
-- `work_fix_required`;
-- `test_gap`;
-- `spec_gap`;
-- `graph_update_proposal`;
-- `process_improvement`;
-- `release_blocker`;
-- `security_blocker`;
-- `defer_with_reason`.
-
-Domain adapters may map narrower terms to these values. For example, a
-software-code review adapter may map `code_fix_required` to
-`work_fix_required`.
-
-## Review Dimensions
-
-A feedback report should choose dimensions that match the technology being
-checked. Common dimensions include:
-
-- scope;
-- architecture;
-- ownership;
-- security;
-- runtime;
-- tests;
-- evidence;
-- graph_drift;
-- release;
-- process_adherence.
-
-## Transition Boundary
-
-Technology feedback can support a process transition such as `review_ready`,
-`accepted`, `approved` or `released`. It must not be treated as the transition
-itself.
-
-Significant work should enter acceptance or release states only when the
-process-control contract requires and receives a passing technology quality
-feedback report.
-
-## Schema
-
-Machine-readable feedback reports can be validated with:
-
-```text
-schemas/technology-quality-feedback.schema.json
-```
-
-The schema validates public shape, finding classification and boundary rules.
-It does not prove semantic correctness, production safety or scientific
-effectiveness.

package/standard/test-suite.md

@@ -1,159 +0,0 @@
-# Mirai Graph Test Suite
-
-Status: 1.2 stable standard section
-
-## Purpose
-
-The Mirai Graph test suite verifies that examples, packages and implementations
-follow the standard.
-
-The test suite should cover structure, conformance, context-pack generation,
-governance gates and benchmark reproducibility.
-
-## Current Smoke Tests
-
-Run:
-
-```bash
-npm test
-```
-
-Current checks:
-
-- validate minimal graph package;
-- validate synthetic benchmark graph package;
-- validate public profile manifests;
-- validate public pilot packages;
-- validate dynamic episode traces and reject unsafe trace semantics;
-- validate goal-vector quality-control reports and reject false-progress
-  semantics;
-- run deterministic seed preview;
-- generate benchmark context pack;
-- score benchmark readiness;
-- run synthetic context-reduction calculation;
-- reject negative fixtures.
-- verify deterministic Project Technology context traversal across project,
-  research, organization, platform, skill-like and multi-repository scopes;
-- reject incomplete mandatory closure, stale nodes, conflicts, cycles,
-  tampered digests, secret-like evidence and context-budget shortcuts.
-- verify portable continuity for Git and non-Git projects, two independent
-  installations, idempotent repeats, stale receipts, CAS conflicts, secret
-  rejection, bounded proposals and two-case method promotion.
-
-## Structural Validation
-
-Structural validation checks:
-
-- required object fields;
-- required relation fields;
-- unique object ids;
-- unique relation ids;
-- relation source/target references;
-- readiness values;
-- evidence arrays;
-- optional package manifest;
-- optional gate result records.
-
-## Profile Conformance
-
-Profile conformance checks:
-
-- package object kinds are allowed by `manifest.profile`;
-- package relation types are allowed by `manifest.profile`;
-- relation ids agree with source, type and target fields.
-
-Fixture guide:
-
-```text
-docs/adoption/profile-conformance-fixtures.md
-```
-
-Current validator:
-
-```bash
-node packages/cli/validate-mirai-graph.js <package-dir>
-```
-
-## Dynamic Episode Validation
-
-Dynamic episode validation checks:
-
-- event presence;
-- source refs;
-- activated objects, relations, policies, gates and technology steps;
-- selected path;
-- blocked paths;
-- finding classifications;
-- feedback classifications;
-- Kaizen route for process improvements;
-- replay/regression placeholders;
-- `canonical_write_allowed=false`;
-- absence of evidence-as-authorization language.
-
-Current commands:
-
-```bash
-npm run validate:dynamic-episodes
-npm run validate:dynamic-episode-report
-npm run test:dynamic-episodes-negative
-```
-
-## Goal Vector Quality Control Validation
-
-Goal-vector validation checks:
-
-- final outcome and start state presence;
-- visible vector segments and batch vector links;
-- evidence before completion claims;
-- reverse audit before pass verdicts;
-- rejection of tests-as-acceptance language;
-- correction routes for drift findings;
-- `canonical_write_allowed=false`;
-- public-safety boundaries.
-
-Current commands:
-
-```bash
-npm run validate:goal-vector-quality-control
-npm run test:goal-vector-quality-control-negative
-```
-
-## Benchmark Reproducibility
-
-Synthetic benchmark:
-
-```bash
-node benchmarks/synthetic-context-reduction-v0/scripts/calculate-context-reduction.js
-```
-
-Expected result:
-
-```text
-56.4516%
-```
-
-This test verifies arithmetic reproducibility only. It does not validate
-semantic completeness or real-world performance.
-
-## Future Tests
-
-Planned:
-
-- context-pack metadata validation;
-- context-pack evidence preservation;
-- governance gate result validation;
-- package manifest validation;
-- semantic completeness review fixture validation;
-- cross-package import/export tests.
-
-## Test Result Policy
-
-Every test result should state:
-
-- command;
-- expected output;
-- actual output;
-- verdict;
-- limitations.
-
-Do not convert a passing smoke test into a stronger scientific claim.

package/standard/work-state-machine.md

@@ -1,62 +0,0 @@
-# Work State Machine
-
-Status: 1.0 release-candidate standard section
-
-## Purpose
-
-Work state machines define allowed movement through a governed work lifecycle.
-They prevent false promotion from planning readiness to execution, from written
-work to implemented state, or from proposal to canonical update.
-
-## Core States
-
-Typical state sequence:
-
-```text
-planned
--> launch_ready
--> prepared
--> ready_to_execute
--> started
--> written
--> tests_recorded
--> evidence_recorded
--> sync_proposed
--> review_ready
--> changes_requested
--> approved
--> release_ready
--> released
--> feedback_recorded
--> evolution_proposed
-```
-
-Exceptional states:
-
-- `blocked`
-- `paused`
-- `abandoned`
-- `superseded`
-- `reverted`
-- `recovered`
-
-## Critical Rules
-
-- `ready_to_execute` is not `started`.
-- `ready_to_code` is not `implemented`.
-- `written` is not accepted implementation state.
-- `tests_recorded` without semantic evidence is not review acceptance.
-- `sync_proposed` does not update canonical graph state.
-- invalid transitions fail closed.
-- transitions may require a launch record when they cross from planning into
-  executable work.
-- terminal states require a Kaizen review or an explicit no-reusable-lessons
-  reason when the process is significant.
-
-## Schema
-
-Machine-readable state machines can be validated with:
-
-```text
-schemas/work-state-machine.schema.json
-```

package/templates/README.md

@@ -1,77 +0,0 @@
-# Mirai Graph Templates
-
-Status: 1.0 release-candidate starter kit
-
-These templates are small public-safe starter packages. They are intentionally
-complete enough to validate, but small enough to copy into a new project and
-replace with real public or private sources.
-
-For the full role-oriented starter path, use the
-[1.0 RC Adopter Kit](../docs/adoption/adopter-kit.md).
-
-For self-service onboarding in a project, prefer:
-
-```bash
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-```
-
-`init` copies only starter graph package files. It does not overwrite project
-README files and refuses to replace existing graph files unless `--force` is
-passed.
-
-## Starters
-
-| Template | Profile | Use when |
-| --- | --- | --- |
-| `software-project-starter/` | `software_specification` | Starting from features, requirements, components, tasks and risks. |
-| `research-program-starter/` | `project_management` | Starting from hypotheses, evidence, milestones, review gates and publication risks. |
-| `ai-employee-starter/` | `ai_employee` | Modeling an AI worker with role, skill, tool, policy, action and feedback gates. |
-| `character-layer-starter/` | `character_layer` | Reusing behavior constitution, role character profiles, reflection and correction boundaries. |
-| `organization-governance-starter/` | `organization_governance` | Modeling mission, strategy, departments, programs, policies, controls and metrics. |
-
-## One-Day Adoption Path
-
-1. Choose the closest starter profile.
-2. Copy the template into your project.
-3. Replace synthetic object titles and summaries with your domain objects.
-4. Keep private notes, secrets, raw logs and internal handoffs outside the
-   public graph package.
-5. Run:
-
-```bash
-npm run validate:templates
-node packages/cli/validate-mirai-graph.js templates/<template-name>
-```
-
-6. Add launch records, process transitions and evidence packs only after the
-   graph package shape validates.
-
-## Adopter Workflow Commands
-
-List the role/profile/starter map:
-
-```bash
-node packages/cli/mirai-graph.js choose-profile
-```
-
-Print a plan for a role or profile:
-
-```bash
-node packages/cli/mirai-graph.js adopter plan organization
-node packages/cli/mirai-graph.js adopter plan ai_employee
-```
-
-Generate a readable report for a starter:
-
-```bash
-node packages/cli/mirai-graph.js adopter report templates/organization-governance-starter
-```
-
-## Boundary
-
-Templates are starter packages, not adoption proof. Passing validation means
-only that the package follows the current release-candidate schema/profile
-shape.

package/templates/ai-employee-starter/README.md

@@ -1,9 +0,0 @@
-# AI Employee Starter
-
-Use this template for a governed AI employee graph.
-
-Validate:
-
-```bash
-node packages/cli/validate-mirai-graph.js templates/ai-employee-starter
-```

package/templates/ai-employee-starter/gates/results.json

@@ -1,12 +0,0 @@
-[
-  {
-    "id": "gate_result.template_ai_employee.public_safety",
-    "gate_id": "gate.public_safety",
-    "target_id": "package.template_ai_employee",
-    "verdict": "pass",
-    "summary": "Template uses only synthetic AI employee content and no private runtime traces.",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "reviewed_at": "2026-06-03",
-    "reviewer": "Mirai Graph template validator"
-  }
-]

package/templates/ai-employee-starter/graph/objects.json

@@ -1,90 +0,0 @@
-[
-  {
-    "id": "ai_employee.research_assistant",
-    "kind": "ai_employee",
-    "title": "Research Assistant",
-    "summary": "Synthetic AI employee used to demonstrate governed capability and feedback boundaries.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "role.research_support",
-    "kind": "role",
-    "title": "Research Support",
-    "summary": "Role responsible for summarizing evidence and preparing review queues.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "skill.evidence_summary",
-    "kind": "skill",
-    "title": "Evidence Summary",
-    "summary": "Summarize source evidence without turning suggestions into canonical updates.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "tool.search_index",
-    "kind": "tool",
-    "title": "Search Index",
-    "summary": "Synthetic tool placeholder for finding reviewed public sources.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "policy.human_approval",
-    "kind": "policy",
-    "title": "Human Approval",
-    "summary": "External action and behavior updates require human approval.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "action.prepare_summary",
-    "kind": "action",
-    "title": "Prepare Summary",
-    "summary": "Prepare a reviewable summary, not a canonical update.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "feedback.review_note",
-    "kind": "feedback",
-    "title": "Review Note",
-    "summary": "Feedback may create a proposal but cannot directly update behavior.",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  },
-  {
-    "id": "evidence.synthetic_role_brief",
-    "kind": "evidence",
-    "title": "Synthetic Role Brief",
-    "summary": "Public-safe placeholder evidence for the starter template.",
-    "readiness": "accepted",
-    "evidence": [],
-    "profile": "ai_employee",
-    "created_at": "2026-06-03",
-    "updated_at": "2026-06-03"
-  }
-]

package/templates/ai-employee-starter/graph/relations.json

@@ -1,47 +0,0 @@
-[
-  {
-    "id": "relation.ai_employee.research_assistant.has_role.role.research_support",
-    "type": "has_role",
-    "source": "ai_employee.research_assistant",
-    "target": "role.research_support",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.ai_employee.research_assistant.has_skill.skill.evidence_summary",
-    "type": "has_skill",
-    "source": "ai_employee.research_assistant",
-    "target": "skill.evidence_summary",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.skill.evidence_summary.requires_capability.tool.search_index",
-    "type": "requires_capability",
-    "source": "skill.evidence_summary",
-    "target": "tool.search_index",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.action.prepare_summary.requires_approval.policy.human_approval",
-    "type": "requires_approval",
-    "source": "action.prepare_summary",
-    "target": "policy.human_approval",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  },
-  {
-    "id": "relation.feedback.review_note.updates_behavior.policy.human_approval",
-    "type": "updates_behavior",
-    "source": "feedback.review_note",
-    "target": "policy.human_approval",
-    "readiness": "draft",
-    "evidence": ["evidence.synthetic_role_brief"],
-    "profile": "ai_employee"
-  }
-]

package/templates/ai-employee-starter/graph.json

@@ -1,37 +0,0 @@
-{
-  "$schema": "https://mirai-graph.dev/schemas/graph-manifest.schema.json",
-  "format": "mirai-graph",
-  "schema_version": "2.0.0",
-  "id": "package.template_ai_employee",
-  "aliases": [],
-  "title": "AI Employee Starter",
-  "scope": "package",
-  "kind": "graph_package",
-  "owner": "mirai-graph",
-  "profiles": [
-    "ai_employee"
-  ],
-  "graph": {
-    "root": "graph",
-    "source_of_truth": [
-      "graph"
-    ],
-    "objects": [
-      "graph/objects.json"
-    ],
-    "relations": [
-      "graph/relations.json"
-    ],
-    "schemas": [],
-    "generated": [],
-    "raw_sources": [
-      "README.md"
-    ]
-  },
-  "imports": [],
-  "version": "0.1.0",
-  "conformance_level": "level_1",
-  "description": "Synthetic starter package for a governed AI employee Mirai Graph.",
-  "license": "CC-BY-4.0",
-  "public_safety": "synthetic_public"
-}

package/templates/character-layer-starter/README.md

@@ -1,39 +0,0 @@
-# Character Layer Starter
-
-Use this template when a project, AI employee, research workflow or governed
-runtime needs a reusable Character Layer package.
-
-The starter provides:
-
-- base character constitution;
-- reusable behavior principles;
-- character virtues;
-- hard character boundaries;
-- reflection protocol;
-- role character profiles;
-- violation patterns;
-- owner-reviewed correction loop;
-- public-safety and review-boundary gates.
-
-Validate:
-
-```bash
-node packages/cli/validate-mirai-graph.js templates/character-layer-starter
-```
-
-## Adaptation Path
-
-1. Keep the base constitution unless a project has a stronger reviewed
-   constitution.
-2. Select the closest `role_character_profile`.
-3. Add project-specific boundaries only when they are evidence-backed.
-4. Keep tool permission, runtime authorization and external action policy in
-   runtime/process layers, not in this profile.
-5. Add fixtures for every behavior that must remain stable across model
-   backends.
-
-## Boundary
-
-This starter is a behavior-governance template. It does not train a model,
-grant runtime permissions, authorize external actions or prove scientific
-effectiveness.

package/templates/character-layer-starter/gates/results.json

@@ -1,20 +0,0 @@
-[
-  {
-    "id": "gate_result.template_character_layer.public_safety",
-    "gate_id": "public_safety_before_release",
-    "target_id": "package.template_character_layer",
-    "verdict": "pass_with_notes",
-    "summary": "Template uses only synthetic public-safe character content and no private runtime traces.",
-    "reviewed_at": "2026-06-12",
-    "evidence": ["evidence.character_starter_brief"]
-  },
-  {
-    "id": "gate_result.template_character_layer.owner_review_boundary",
-    "gate_id": "human_review_before_canonical_write",
-    "target_id": "correction_loop.owner_reviewed_character_update",
-    "verdict": "pass_with_notes",
-    "summary": "The correction loop keeps behavior changes as proposals until owner review.",
-    "reviewed_at": "2026-06-12",
-    "evidence": ["evidence.character_starter_brief"]
-  }
-]