mirai-graph 1.3.0 → 2.1.0

package/docs/adoption/cli.md

@@ -1,134 +0,0 @@
-# Mirai Graph CLI
-
-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
-reports.
-
-## Commands
-
-Detect an existing project without writing files:
-
-```bash
-npx mirai-graph detect . --markdown
-```
-
-Create a bootstrap proposal without canonical writes:
-
-```bash
-npx mirai-graph bootstrap . --mode suggest --markdown
-```
-
-Initialize a starter package:
-
-```bash
-npx mirai-graph init . --profile software_specification
-```
-
-List profile choices:
-
-```bash
-npx mirai-graph choose-profile
-```
-
-Print an adopter plan for a role or profile:
-
-```bash
-npx mirai-graph adopter plan developer
-npx mirai-graph adopter plan organization_governance
-```
-
-Generate a readable adopter report for a starter template:
-
-```bash
-npx mirai-graph adopter report templates/software-project-starter
-```
-
-Validate a package:
-
-```bash
-npx mirai-graph validate examples/minimal-graph
-```
-
-Generate a Markdown validation report:
-
-```bash
-npx mirai-graph report validation examples/minimal-graph
-```
-
-Explain a process transition:
-
-```bash
-npx mirai-graph explain process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
-```
-
-Generate a dynamic episode trace report:
-
-```bash
-npx mirai-graph report dynamic-episode examples/dynamic-episode-minimal/results/dynamic-episode-trace.json
-```
-
-Generate the playground report:
-
-```bash
-npx mirai-graph report playground
-```
-
-Check the external release state without publishing:
-
-```bash
-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
-```
-
-Versioned file bundles use the same Project Technology entrypoint:
-
-```bash
-npx mirai-graph technology artifact inspect . --input incoming.zip
-npx mirai-graph technology artifact release . --input incoming.zip --matter-id agreement-main --direction inbound
-npx mirai-graph technology artifact release . --input incoming.zip --matter-id agreement-main --direction inbound --apply
-npx mirai-graph technology artifact compare . --matter-id agreement-main --base-release 20260828-01 --target-release 20260828-02
-npx mirai-graph technology artifact verify . --matter-id agreement-main --release-id 20260828-02
-```
-
-Inspection, comparison and verification are read-only. Release creation is a
-preview until `--apply` is present.
-
-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.
-- Markdown output is intended for human review.
-- `detect` is read-only.
-- `bootstrap --mode suggest` writes proposal/evidence only.
-- `init` creates starter graph files and refuses to overwrite by default.
-- Adopter workflow output is a starting aid, not adoption proof.
-- Dynamic episode reports explain operational behavior. They do not expose
-  hidden model reasoning and do not authorize canonical updates.
-- A passing report is evidence for the checked artifact only.
-- A release-state report checks package, git tag, GitHub Release, npm registry
-  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
-
-The `mirai_graph` entrypoint is an underscore alias for environments where a
-hyphenated command name is inconvenient. New documentation and automation
-should prefer `npx mirai-graph ...` for adopter projects and
-`node packages/cli/mirai-graph.js ...` for repository checkout maintenance.

package/docs/adoption/connect-project-15-minutes.md

@@ -1,122 +0,0 @@
-# Connect A Project In 15 Minutes
-
-Status: 1.0 release-candidate tutorial
-
-This tutorial starts from an existing project and creates a first validated
-Mirai Graph package. It is intentionally small: the goal is a reviewable
-starter graph, not a complete model of the project.
-
-If you want the developer-facing rationale first, read
-[Mirai Graph For Developers](for-developers.md).
-
-## 1. Install
-
-From the project you want to connect:
-
-```bash
-npm install -D mirai-graph
-```
-
-Release-candidate note: `mirai-graph@1.0.0-rc.6` is not published on npm yet.
-Until npm publication is complete, use a repository checkout and run the same
-commands through `node packages/cli/mirai-graph.js`.
-
-You can also run without saving the dependency:
-
-```bash
-npx mirai-graph detect . --markdown
-```
-
-## 2. Detect The Project
-
-Run read-only detection:
-
-```bash
-npx mirai-graph detect . --markdown
-```
-
-Detection reports whether a Mirai Graph package already exists, which profile
-is recommended, which artifacts are missing and what the next safe action is.
-Detection does not write files.
-
-## 3. Generate A Bootstrap Proposal
-
-Create a proposal without changing canonical graph files:
-
-```bash
-npx mirai-graph bootstrap . --mode suggest --markdown
-```
-
-The proposal is written to:
-
-```text
-mirai-graph/bootstrap-proposal/
-```
-
-It keeps `canonical_write_allowed=false`.
-
-## 4. Initialize The Starter Graph
-
-After reviewing the recommendation, create a starter package:
-
-```bash
-npx mirai-graph init . --profile software_specification
-```
-
-Use another profile when detection recommends it:
-
-```bash
-npx mirai-graph init . --profile project_management
-npx mirai-graph init . --profile ai_employee
-npx mirai-graph init . --profile character_layer
-npx mirai-graph init . --profile organization_governance
-```
-
-`init` creates:
-
-```text
-graph.json
-graph/objects.json
-graph/relations.json
-gates/results.json
-```
-
-It refuses to overwrite existing graph files unless `--force` is passed.
-
-## 5. Validate
-
-Run:
-
-```bash
-npx mirai-graph validate .
-```
-
-For a human-readable report:
-
-```bash
-npx mirai-graph report validation .
-```
-
-## 6. Add CI
-
-Copy the GitHub Action starter from:
-
-```text
-.github/workflows/mirai-graph-validate.yml
-```
-
-Use this command in CI:
-
-```bash
-npx mirai-graph validate .
-```
-
-Adjust `.` if your package root is somewhere else.
-
-## Boundaries
-
-- A starter graph is not proof that the project is correct.
-- Generated proposals do not update canonical graph state.
-- Evidence and feedback do not authorize production changes.
-- Private data, credentials and customer logs should stay outside public graph
-  packages.

package/docs/adoption/developer-integration-guide.md

@@ -1,122 +0,0 @@
-# Mirai Graph Developer Integration Guide
-
-Status: 1.0 release-candidate developer guide
-
-## Purpose
-
-This guide shows how to use Mirai Graph validation in a developer workflow or
-CI pipeline.
-
-Mirai Graph tooling is a reference implementation. The standard remains the
-source of the model; the CLI helps teams check graph packages, profiles,
-context packs and process-control artifacts.
-
-## Install In A Project
-
-Use the npm package in the project you want to connect:
-
-```bash
-npm install -D mirai-graph
-```
-
-Detect the project and create a proposal before adding canonical graph files:
-
-```bash
-npx mirai-graph detect . --markdown
-npx mirai-graph bootstrap . --mode suggest --markdown
-```
-
-After reviewing the proposal, initialize and validate the starter graph:
-
-```bash
-npx mirai-graph init . --profile software_specification
-npx mirai-graph validate .
-npx mirai-graph report validation .
-```
-
-Use another profile when appropriate:
-
-```bash
-npx mirai-graph init . --profile project_management
-npx mirai-graph init . --profile ai_employee
-npx mirai-graph init . --profile character_layer
-npx mirai-graph init . --profile organization_governance
-```
-
-## Contributor Checkout
-
-Use repository checkout commands when changing Mirai Graph itself:
-
-```bash
-cd /path/to/mirai-graph
-npm install
-npm test
-```
-
-Direct script calls are mainly for maintainers and validators:
-
-```bash
-node packages/cli/validate-mirai-graph.js examples/minimal-graph
-node packages/cli/validate-mirai-graph.js --markdown examples/minimal-graph
-```
-
-## CI Example
-
-Minimal GitHub Actions step for an adopter project:
-
-```yaml
-- name: Validate Mirai Graph package
-  run: npx mirai-graph validate .
-```
-
-Markdown report artifact:
-
-```yaml
-- name: Generate Mirai Graph validation report
-  run: npx mirai-graph report validation . > mirai-graph-report.md
-```
-
-Repository maintainers can use the full release-candidate suite:
-
-```yaml
-- name: Validate Mirai Graph repository
-  run: |
-    npm ci
-    npm run release:check
-```
-
-## Process-Control Checks
-
-Use process-transition validation when work moves through an executable state
-machine:
-
-```bash
-npx mirai-graph explain process-transition \
-  examples/process-transition-minimal/state-machine.json \
-  examples/process-transition-minimal/transition-request.json
-```
-
-Use process-control contract validation from a repository checkout when a
-project binds cycles, state machine, launch policy, evidence, recovery and
-Kaizen policy:
-
-```bash
-node packages/cli/validate-mirai-graph.js process-control-contract \
-  examples/process-control-contract-minimal/results/process-control-contract.json
-```
-
-## Exit Codes
-
-- `0`: validation passed.
-- `1`: validation failed or an input file could not be read.
-- `2`: command usage error.
-
-## Boundaries
-
-- `detect` is read-only.
-- `bootstrap --mode suggest` writes proposal/evidence only.
-- `init` creates starter graph files and refuses to overwrite by default.
-- A passing validation report is evidence for the selected check only.
-- Generated context is not canonical graph state.
-- Evidence and proposals do not authorize canonical updates.
-- Readiness states do not imply execution or release.

package/docs/adoption/end-to-end-control-loop.md

@@ -1,168 +0,0 @@
-# End-To-End Mirai Graph Control Loop
-
-Status: 1.0 release-candidate tutorial
-
-## Purpose
-
-This tutorial shows the public alpha control loop:
-
-```text
-seed -> graph -> context -> launch -> transition -> evidence -> kaizen
-```
-
-It uses existing public-safe examples. It does not require private project data
-and does not grant automatic permission to change canonical graph state.
-
-## 1. Start With A Seed
-
-A graph seed defines the first bounded system shape before a full graph exists.
-
-Run:
-
-```bash
-node packages/cli/validate-mirai-graph.js seed examples/graph-seed-minimal/graph-seed.json
-node packages/cli/seed-preview.js examples/graph-seed-minimal/graph-seed.json
-```
-
-Read:
-
-- `standard/graph-seed.md`
-- `examples/graph-seed-minimal/README.md`
-
-## 2. Validate A Graph Package
-
-A package stores graph objects, relations and gate results.
-
-Run:
-
-```bash
-node packages/cli/validate-mirai-graph.js examples/minimal-graph
-```
-
-Read:
-
-- `standard/object-model.md`
-- `standard/relation-model.md`
-- `standard/evidence-provenance.md`
-
-## 3. Generate Or Inspect Task Context
-
-Context packs select task-relevant graph material. They are generated context,
-not canonical state.
-
-Run:
-
-```bash
-node packages/cli/context-pack.js benchmarks/synthetic-context-reduction-v0 --task-id task.notify_after_approval
-node packages/cli/validate-mirai-graph.js context-pack benchmarks/synthetic-context-reduction-v0 benchmarks/synthetic-context-reduction-v0/results/context-pack.json
-```
-
-Read:
-
-- `standard/context-pack-generation.md`
-- `benchmarks/synthetic-context-reduction-v0/README.md`
-
-## 4. Prepare A Launch Record
-
-A launch record defines a bounded work batch, required gates, allowed scope and
-evidence expectations. It is not proof that the work has been executed.
-
-Run:
-
-```bash
-node packages/cli/validate-mirai-graph.js examples/launch-record-minimal
-node packages/cli/validate-mirai-graph.js launch-record examples/launch-record-minimal/results/launch-record.json
-```
-
-Read:
-
-- `standard/launch-record.md`
-- `examples/launch-record-minimal/README.md`
-
-## 5. Validate A Process Transition
-
-Process transitions move through executable state-machine states. Human stages
-and documentation can explain the movement, but the transition request must
-pass validator checks.
-
-Run:
-
-```bash
-node packages/cli/validate-mirai-graph.js process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
-node packages/cli/validate-mirai-graph.js process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request-skip-kaizen.json
-```
-
-Negative fixtures intentionally fail:
-
-```bash
-npm run test:process-transition-negative
-```
-
-Read:
-
-- `standard/work-state-machine.md`
-- `standard/process-control-contract.md`
-- `examples/process-transition-minimal/README.md`
-
-## 6. Record Evidence
-
-Evidence links claims to sources, gates, validation results and limitations. It
-does not approve canonical updates by itself.
-
-Run:
-
-```bash
-npm run validate:implementation-control
-npm run validate:process-control
-```
-
-Read:
-
-- `standard/evidence-provenance.md`
-- `standard/implementation-control.md`
-- `examples/process-control-contract-minimal/README.md`
-
-## 7. Close With Kaizen
-
-Significant work should end with a Kaizen review or an explicit
-`no_reusable_lessons` reason. Kaizen findings become classified improvement
-inputs, not automatic rewrites.
-
-Run:
-
-```bash
-npm run validate:implementation-control-cycles
-```
-
-Read:
-
-- `standard/implementation-control-cycles.md`
-- `examples/implementation-control-cycles/README.md`
-
-## Full Smoke Check
-
-Run the current release-candidate test suite:
-
-```bash
-npm test
-```
-
-Generate the playground report for this loop:
-
-```bash
-npm run playground:demo
-```
-
-For release readiness:
-
-```bash
-npm run release:check
-```
-
-## Boundaries
-
-- Generated context is not canonical state.
-- Evidence is not approval.
-- A proposal is not a canonical update.
-- `ready_to_execute` is not execution.
-- Synthetic benchmarks are method demonstrations, not broad scientific proof.