mirai-graph 1.0.0 → 1.1.1

package/.github/workflows/ci.yml

@@ -7,6 +7,25 @@ on:
   pull_request:
 
 jobs:
+  context-traversal:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Verify deterministic context traversal
+        run: node packages/cli/validate-context-traversal.js
+
   release-check:
     runs-on: ubuntu-latest
 

package/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to Mirai Graph will be documented in this file.
 
 ## [Unreleased]
 
+## [1.1.1] - 2026-08-26
+
+### Fixed
+
+- Sequential context traversal now reads the accepted legacy aliases used by
+  existing `graph.json` 2.0.0 repositories (`type`, `from`, `to`,
+  `relation_type` and `status`) without requiring a graph rewrite.
+- Established structural and required relation names are projected onto the
+  public traversal vocabulary while preserving their direction and mandatory
+  closure semantics.
+- Existing accepted Mirai readiness levels and revision-bound objects without
+  an explicit historical readiness field remain usable; draft, seed, gap,
+  blocked, stale and deprecated states still fail closed.
+
+### Compatibility
+
+- This patch makes the 1.1.0 compatibility promise executable. It does not
+  change schema `2.0.0`, the Project Technology activation contract, provider
+  transport or write boundaries.
+
+## [1.1.0] - 2026-08-26
+
+### Added
+
+- Model-independent `discover`, `expand`, `compile` and `verify` phases for
+  progressively navigating Project Technology context.
+- Public JavaScript API and matching CLI for deterministic traversal,
+  mandatory dependency closure and usage verification.
+- One bounded context-traversal receipt contract and direct context-pack fields
+  for selection, completeness, exact sources and a stable digest.
+- Universal fixtures for software, research, organization, platform,
+  skill-like and multi-repository graphs, including macOS, Linux and Windows CI.
+
+### Safety Boundary
+
+- All traversal phases are read-only and generated context never authorizes a
+  write.
+- Required sources, processes and validators cannot be removed to meet a token
+  budget. Missing, stale, blocked, deprecated, conflicting, cyclic or tampered
+  context fails closed.
+- Access data is limited to safe references and availability metadata; secret
+  values and private source content are not included.
+
+### Compatibility
+
+- The public `graph.json` schema remains `2.0.0` and
+  `mirai.project_technology.contract_version` remains `1.0.0`.
+- Existing graphs need no migration, the original context command remains
+  available, and provider/consumer behavior is unchanged.
+
 ## [1.0.0] - 2026-08-17
 
 ### Changed

package/CITATION.cff

@@ -17,4 +17,5 @@ keywords:
   - complex systems
   - context engineering
   - systems engineering
-date-released: "2026-05-28"
+version: "1.1.0"
+date-released: "2026-08-26"

package/README.md

@@ -10,7 +10,7 @@ Use it when a software project has useful knowledge spread across README files,
 docs, issues, chats, code comments and AI prompts, and you need a small
 machine-readable map that developers and AI assistants can validate and reuse.
 
-Status: stable public `1.0.0` release.
+Status: stable public `1.1.0` release.
 
 ## What Problem Does It Solve?
 
@@ -42,7 +42,7 @@ Start with a normal repository and use Mirai Graph to:
 
 ## Current Installation Status
 
-The repository is ready as the stable `mirai-graph@1.0.0` package. To verify a
+The repository is ready as the stable `mirai-graph@1.1.0` package. To verify a
 repository checkout directly, use:
 
 ```bash
@@ -111,6 +111,25 @@ mirai-graph technology context . --task "implement the approved feature"
 mirai-graph technology verify . --significant-work
 ```
 
+For deeper graphs, the same `context` operation supports four read-only phases:
+
+```bash
+mirai-graph technology context . --phase discover --task "implement the approved feature"
+mirai-graph technology context . --phase expand --input receipt.json --select capability.delivery
+mirai-graph technology context . --phase compile --input receipt.json --selection selection.json
+mirai-graph technology context . --phase verify --packet context-pack.json --evidence usage-evidence.json
+```
+
+`discover` returns a bounded top-level choice. `expand` follows only selected
+branches. `compile` adds every required process, constraint and validator, and
+returns an immutable context pack only when the selection is complete.
+`verify` proves that required sources influenced a decision and a checked
+outcome; merely loading a document is not enough.
+
+The programmatic API exposes the same operations as `discoverContext`,
+`expandContext`, `compileContext` and `verifyContext`. Mirai Graph does not call
+or depend on a particular AI model.
+
 Changing operations return a preview unless `--apply` is explicit. See
 [Project Technology](standard/project-technology.md) for provider/consumer
 binding, local state and safety boundaries.

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # Mirai Graph Roadmap
 
-Status: 1.0 release-candidate roadmap
+Status: stable 1.1 roadmap
 
 ## Phase 0: Public Foundation
 
@@ -228,19 +228,14 @@ Planned artifacts:
 - release process;
 - public examples from approved external adopters.
 
-## Near-Term Work After 1.0 RC
-
-1. Execute the `1.0.0-rc.6` release: tag, GitHub Release and npm publication
-   only after release-state checks are accepted.
-2. Continue adopter workflow: import/export helper skeletons, richer report
-   formatting and more adoption recipes when they directly support self-service
-   adoption.
-3. Add one or two external public-safe pilots maintained outside the original
-   Mirai Graph authoring contour.
-4. Expand organization-governance validation reports and adoption recipes.
-5. Collect real multi-model Character Layer replay evidence before stronger
+## Near-Term Work After 1.1
+
+1. Validate sequential context traversal in independent adopter projects and
+   collect public-safe compatibility evidence.
+2. Continue adopter workflow with richer reports and domain-neutral recipes.
+3. Add external public-safe pilots maintained outside the original Mirai Graph
+   authoring contour.
+4. Collect real multi-model replay evidence before stronger effectiveness or
    portability claims.
-6. Explore a local interactive playground only after deterministic report
-   fixtures remain stable.
-7. Turn evidence package v0.3 and the two article foundations into a
-   publication-ready reproducibility bundle.
+5. Keep the deterministic CLI and public contracts stable while improving
+   ranking as a replaceable client-side concern.

package/docs/adoption/cli.md

@@ -1,6 +1,6 @@
 # Mirai Graph CLI
 
-Status: 1.0 release-candidate CLI guide
+Status: 1.1 stable CLI guide
 
 Mirai Graph keeps the reference scripts for direct automation. The
 `mirai-graph` entrypoint is the primary command surface for common checks and
@@ -82,6 +82,19 @@ npx mirai-graph release state --markdown
 npm run validate:release-state
 ```
 
+Discover and compile task context without writing files:
+
+```bash
+npx mirai-graph technology context . --phase discover --task "prepare the release"
+npx mirai-graph technology context . --phase expand --input receipt.json --select capability.release
+npx mirai-graph technology context . --phase compile --input receipt.json --selection selection.json
+npx mirai-graph technology context . --phase verify --packet context-pack.json --evidence usage-evidence.json
+```
+
+Omitting `--phase` keeps the original bounded context-discovery behavior.
+Receipt, selection, context-pack and usage-evidence files are caller-owned
+inputs and outputs; the command never stores them itself.
+
 ## Output Boundary
 
 - JSON output is intended for tools and CI.
@@ -97,6 +110,8 @@ npm run validate:release-state
   and npm auth state, but it does not publish or authorize a release.
 - Generated context, evidence, feedback and proposals do not authorize
   canonical updates.
+- Context traversal never reads secret values into its output. Access is
+  represented by a safe reference, availability and required permission.
 
 ## Command Aliases
 

package/examples/project-technology-context-traversal/README.md

@@ -0,0 +1,17 @@
+# Project Technology Context Traversal
+
+This synthetic example shows a domain-neutral release graph with a three-level
+path, mandatory rollback and validation dependencies, and one optional branch.
+
+Start with discovery:
+
+```bash
+mirai-graph technology context . --phase discover --task "prepare and verify a release"
+```
+
+Save the returned `traversal_receipt`, expand the selected capability and
+process, then copy the returned task and graph digests into
+`selection.example.json`. Compilation adds the rollback constraint and release
+smoke even if the selector did not name them.
+
+All operations are read-only. The example contains synthetic public data only.

package/examples/project-technology-context-traversal/graph/objects.json

@@ -0,0 +1,78 @@
+[
+  {
+    "id": "capability.release_delivery",
+    "kind": "capability",
+    "title": "Release delivery",
+    "summary": "Prepare a bounded and verifiable software release.",
+    "owner": "role.release_owner",
+    "readiness": "accepted",
+    "authority": "contract",
+    "expansion_policy": "expandable",
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "process.release_verification",
+    "kind": "process",
+    "title": "Release verification",
+    "summary": "Run the accepted release checks before publication.",
+    "owner": "role.release_owner",
+    "readiness": "accepted",
+    "authority": "contract",
+    "expansion_policy": "expandable",
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "source.release_guide",
+    "kind": "source",
+    "title": "Release guide",
+    "summary": "The authoritative local guide for the synthetic release.",
+    "owner": "role.release_owner",
+    "readiness": "accepted",
+    "authority": "source",
+    "expansion_policy": "terminal",
+    "source_refs": ["sources/release-guide.md"],
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "constraint.rollback_required",
+    "kind": "constraint",
+    "title": "Rollback is required",
+    "summary": "Publication must retain a tested rollback path.",
+    "owner": "role.release_owner",
+    "readiness": "accepted",
+    "authority": "contract",
+    "expansion_policy": "terminal",
+    "source_refs": ["sources/rollback-policy.md"],
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "check.release_smoke",
+    "kind": "check",
+    "title": "Release smoke",
+    "summary": "Verify the installed release identity and core behavior.",
+    "owner": "role.release_quality",
+    "readiness": "accepted",
+    "authority": "validator",
+    "expansion_policy": "terminal",
+    "source_refs": ["sources/release-smoke.md"],
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "capability.optional_announcement",
+    "kind": "capability",
+    "title": "Optional announcement",
+    "summary": "Prepare a public announcement only when requested.",
+    "owner": "role.communication",
+    "readiness": "accepted",
+    "authority": "reference",
+    "expansion_policy": "terminal",
+    "source_refs": ["sources/announcement.md"],
+    "evidence": [],
+    "profile": "core"
+  }
+]

package/examples/project-technology-context-traversal/graph/relations.json

@@ -0,0 +1,47 @@
+[
+  {
+    "id": "relation.capability.release_delivery.contains.process.release_verification",
+    "type": "contains",
+    "source": "capability.release_delivery",
+    "target": "process.release_verification",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "relation.process.release_verification.documented_by.source.release_guide",
+    "type": "documented_by",
+    "source": "process.release_verification",
+    "target": "source.release_guide",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "relation.process.release_verification.governed_by.constraint.rollback_required",
+    "type": "governed_by",
+    "source": "process.release_verification",
+    "target": "constraint.rollback_required",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "relation.process.release_verification.validated_by.check.release_smoke",
+    "type": "validated_by",
+    "source": "process.release_verification",
+    "target": "check.release_smoke",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "core"
+  },
+  {
+    "id": "relation.capability.release_delivery.contains.capability.optional_announcement",
+    "type": "contains",
+    "source": "capability.release_delivery",
+    "target": "capability.optional_announcement",
+    "readiness": "accepted",
+    "evidence": [],
+    "profile": "core"
+  }
+]

package/examples/project-technology-context-traversal/graph.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://mirai-graph.dev/schemas/graph-manifest.schema.json",
+  "format": "mirai-graph",
+  "schema_version": "2.0.0",
+  "id": "example.project_technology_context_traversal",
+  "aliases": [],
+  "title": "Project Technology Context Traversal Example",
+  "scope": "repository",
+  "kind": "project_graph",
+  "owner": "example.delivery_owner",
+  "profiles": [],
+  "graph": {
+    "root": "graph",
+    "source_of_truth": ["graph"],
+    "objects": ["graph/objects.json"],
+    "relations": ["graph/relations.json"],
+    "schemas": [],
+    "generated": [],
+    "raw_sources": ["sources"]
+  },
+  "imports": [],
+  "extensions": {
+    "mirai.project_technology": {
+      "contract_version": "1.0.0",
+      "enabled": true,
+      "context_policy": "task_scoped",
+      "source_boundary": "hybrid_sot"
+    }
+  }
+}

package/examples/project-technology-context-traversal/selection.example.json

@@ -0,0 +1,29 @@
+{
+  "selector": "human",
+  "task_digest": "replace-with-discover-task-digest",
+  "graph_digest": "replace-with-discover-graph-digest",
+  "result_owner_id": "role.release_owner",
+  "selected": [
+    {
+      "id": "capability.release_delivery",
+      "reason": "The requested outcome is a release.",
+      "confidence": 1
+    },
+    {
+      "id": "process.release_verification",
+      "reason": "The release must be verified before publication.",
+      "confidence": 1
+    },
+    {
+      "id": "source.release_guide",
+      "reason": "This is the accepted release source.",
+      "confidence": 1
+    }
+  ],
+  "rejected": [
+    {
+      "id": "capability.optional_announcement",
+      "reason": "An announcement was not requested."
+    }
+  ]
+}

package/examples/project-technology-context-traversal/sources/announcement.md

@@ -0,0 +1,3 @@
+# Optional announcement
+
+Publish an announcement only when it belongs to the accepted release scope.

package/examples/project-technology-context-traversal/sources/release-guide.md

@@ -0,0 +1,3 @@
+# Release guide
+
+Build once, verify the exact artifact, and publish only that artifact.

package/examples/project-technology-context-traversal/sources/release-smoke.md

@@ -0,0 +1,3 @@
+# Release smoke
+
+Check the installed version, package checksum and one representative operation.

package/examples/project-technology-context-traversal/sources/rollback-policy.md

@@ -0,0 +1,3 @@
+# Rollback policy
+
+Keep the previous immutable version available until the new version is verified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mirai-graph",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "private": false,
   "description": "An evolutionary graph operating model for managing the growth of complex systems.",
   "license": "MIT",
@@ -13,9 +13,10 @@
     "./project-technology": "./packages/project-technology/index.js"
   },
   "scripts": {
-    "pretest": "npm run test:project-technology",
+    "pretest": "npm run test:project-technology && npm run test:context-traversal && npm run validate:project-technology-schemas",
     "test:project-technology": "node packages/cli/validate-project-technology.js",
-    "validate:project-technology-schemas": "node -e \"JSON.parse(require('fs').readFileSync('schemas/project-technology-extension.schema.json')); JSON.parse(require('fs').readFileSync('schemas/project-technology-target-export.schema.json'))\"",
+    "test:context-traversal": "node packages/cli/validate-context-traversal.js",
+    "validate:project-technology-schemas": "node -e \"const fs=require('fs'); for (const file of ['project-technology-extension.schema.json','project-technology-target-export.schema.json','context-traversal-receipt.schema.json','context-pack.schema.json']) JSON.parse(fs.readFileSync('schemas/'+file))\"",
     "validate:graph-manifest": "node packages/cli/validate-graph-manifest-migration.js",
     "validate:minimal": "node packages/cli/validate-mirai-graph.js examples/minimal-graph",
     "validate:benchmark": "node packages/cli/validate-mirai-graph.js benchmarks/synthetic-context-reduction-v0",

package/packages/cli/project-technology.js

@@ -2,6 +2,7 @@
 
 "use strict";
 
+const fs = require("fs");
 const path = require("path");
 const { execute } = require("../project-technology");
 
@@ -12,6 +13,10 @@ function usage() {
   console.error("Options: --apply --task <text> --source <file> --target-id <id>");
   console.error("         --semantic-digest <sha256:...> --provider-revision <sha>");
   console.error("         --refresh-binding --significant-work --max-objects <count>");
+  console.error("Context: --phase discover --task <text>");
+  console.error("         --phase expand --input <receipt.json> --select <id> [--select <id>]");
+  console.error("         --phase compile --input <receipt.json> --selection <selection.json>");
+  console.error("         --phase verify --packet <context-pack.json> --evidence <usage-evidence.json>");
 }
 
 function parse(argv) {
@@ -20,31 +25,66 @@ function parse(argv) {
   let repository = ".";
   if (argv[0] && !argv[0].startsWith("--")) repository = argv.shift();
   const options = {};
-  const values = new Set(["--task", "--source", "--target-id", "--semantic-digest", "--provider-revision", "--max-objects"]);
+  const values = new Set(["--task", "--source", "--target-id", "--semantic-digest", "--provider-revision", "--max-objects", "--phase", "--input", "--select", "--selection", "--packet", "--evidence", "--selector", "--reason", "--confidence", "--context-budget"]);
   const flags = new Set(["--apply", "--refresh-binding", "--significant-work"]);
   const names = {
     "--task": "task", "--source": "source", "--target-id": "targetId",
     "--semantic-digest": "semanticDigest", "--provider-revision": "providerRevision",
     "--max-objects": "maxObjects", "--apply": "apply",
     "--refresh-binding": "refreshBinding", "--significant-work": "significantWork",
+    "--phase": "phase", "--input": "input", "--select": "selectedIds",
+    "--selection": "selectionFile", "--packet": "packetFile", "--evidence": "evidenceFile",
+    "--selector": "selector", "--reason": "reason", "--confidence": "confidence",
+    "--context-budget": "contextBudget",
   };
   while (argv.length) {
     const token = argv.shift();
     if (flags.has(token)) options[names[token]] = true;
     else if (values.has(token)) {
       if (!argv.length) throw new Error(`missing value for ${token}`);
-      options[names[token]] = argv.shift();
+      const value = argv.shift();
+      if (token === "--select") options.selectedIds = [...(options.selectedIds || []), value];
+      else options[names[token]] = value;
     } else throw new Error(`unsupported argument ${token}`);
   }
   return { operation, repository: path.resolve(repository), options };
 }
 
+function readJsonFile(file) {
+  const absolute = path.resolve(file);
+  if (!fs.existsSync(absolute) || fs.lstatSync(absolute).isSymbolicLink()) throw new Error(`unsafe or missing JSON input ${file}`);
+  return JSON.parse(fs.readFileSync(absolute, "utf8").replace(/^\uFEFF/, ""));
+}
+
+function hydrateContextOptions(request) {
+  if (request.operation !== "context" || !request.options.phase) return;
+  const phase = request.options.phase;
+  if (!new Set(["discover", "expand", "compile", "verify"]).has(phase)) throw new Error(`unsupported context phase ${phase}`);
+  if (["expand", "compile"].includes(phase)) {
+    if (!request.options.input) throw new Error(`${phase} requires --input`);
+    const payload = readJsonFile(request.options.input);
+    request.options.traversalReceipt = payload.traversal_receipt || payload;
+  }
+  if (phase === "compile") {
+    if (!request.options.selectionFile) throw new Error("compile requires --selection");
+    request.options.selection = readJsonFile(request.options.selectionFile);
+  }
+  if (phase === "verify") {
+    if (!request.options.packetFile || !request.options.evidenceFile) throw new Error("verify requires --packet and --evidence");
+    const packet = readJsonFile(request.options.packetFile);
+    request.options.contextPack = packet.context_pack || packet;
+    request.options.usageEvidence = readJsonFile(request.options.evidenceFile);
+  }
+}
+
 let request;
 try { request = parse(process.argv.slice(2)); }
 catch (error) {
   console.error(error.message); usage(); process.exit(1);
 }
 if (!request) { usage(); process.exit(1); }
+try { hydrateContextOptions(request); }
+catch (error) { console.error(error.message); usage(); process.exit(1); }
 
 let output;
 try { output = execute(request.operation, request.repository, request.options); }
@@ -61,4 +101,4 @@ catch (error) {
   };
 }
 process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
-process.exit(output.status === "fail" ? 1 : output.status === "blocked" ? 2 : 0);
+process.exitCode = output.status === "fail" ? 1 : ["blocked", "needs_more_discovery", "needs_decision"].includes(output.status) ? 2 : 0;