mirai-graph 1.0.0-rc.1

package/README.md

@@ -0,0 +1,270 @@
+# Mirai Graph
+
+Mirai Graph is an evolutionary graph operating model for managing the growth of
+complex systems.
+
+It defines how projects, products, organizations and human-AI systems can use
+canonical graph state, generated context packs, evidence, readiness and
+governance gates to coordinate knowledge, decisions and action.
+
+Mirai Graph is the graph foundation of the broader Mirai direction: governed AI
+systems that can work with people, projects and organizations through explicit
+state, evidence, approval gates, feedback loops and controlled evolution.
+
+## Why Mirai Graph
+
+Many teams use documents, chats, task trackers and isolated knowledge bases as
+their main working substrate. This becomes fragile when the system grows:
+requirements change, decisions depend on each other, evidence is scattered and
+AI assistants receive incomplete context.
+
+Mirai Graph treats the working system as an evolving graph:
+
+- objects represent the system state;
+- relations make dependencies explicit;
+- evidence links claims to sources;
+- readiness records maturity and uncertainty;
+- generated context packs provide task-specific AI context;
+- governance gates separate suggestions, decisions and actions;
+- profiles adapt the model to domains without changing the core standard.
+
+## Strategic Goal
+
+The long-term goal is to make Mirai Graph an open, verifiable and practical
+standard for governed AI work. A Mirai Graph system should make it possible to
+move from idea to action without losing context, ownership, evidence, process
+discipline or human control.
+
+In this framing, an AI agent is not just a prompt or chat session. It is a
+governed graph-backed operating process: context, tools, policies, actions,
+results, feedback and learning are connected through explicit state and
+approval boundaries.
+
+## Current Status
+
+Status: public 1.0 release candidate.
+
+This repository is being prepared as the public source of truth for the
+Mirai Graph model, standard, methods, examples and reproducibility materials.
+
+The model is related to the `Evolutionary Object Graph (EOG)` research program.
+The current public name is `Mirai Graph`; `EOG` remains the scientific continuity
+term for earlier preprint materials.
+
+Current release candidate:
+[v1.0.0-rc.1](releases/1.0.0-rc.1.md). This candidate consolidates the
+validator-backed public standard across the core model, profiles, executable
+process control, instrumentation, Character Layer, adopter kit and evidence
+boundaries.
+
+## Intended Audiences
+
+- Researchers who need a clear model, reproducible experiments and citation
+  trail.
+- Developers who need schemas, validators, examples and integration methods.
+- Product teams that need adoption guides, profiles and operating procedures.
+- Organizations that need governance patterns for complex human-AI systems.
+
+## Repository Map
+
+```text
+docs/          Concept, terminology, methodology, adoption and research guides.
+standard/      Implementation-independent standard sections.
+schemas/       Machine-readable schemas and validation rules.
+benchmarks/    Synthetic benchmarks and reproducibility packages.
+examples/      Public-safe examples and anti-examples.
+packages/      Reference tooling, libraries and CLI packages.
+playground/    Runnable demo index backed by examples and CLI commands.
+profiles/      Domain profiles for project, software, AI and process use cases.
+pilots/        Public-safe pilot packages and reports.
+publications/  Publication links, citation notes and reproducibility records.
+```
+
+## Start Here
+
+Start by role:
+
+- Researchers: [Practice And Science Program](docs/research/practice-science-program.md),
+  [Scientific Evidence Package](docs/research/scientific-evidence-package.md),
+  [Evidence Package v0.3](docs/research/evidence-package-v0.3.md),
+  [Evidence Package v0.2](docs/research/evidence-package-v0.2.md),
+  [Evidence Package v0.1](docs/research/evidence-package-v0.1.md),
+  [Publications](publications/README.md).
+- Developers: [Getting Started](docs/adoption/getting-started.md),
+  [1.0 RC Adopter Kit](docs/adoption/adopter-kit.md),
+  [Choose A Profile](docs/adoption/choose-profile.md),
+  [End-To-End Tutorial](docs/adoption/end-to-end-control-loop.md),
+  [Developer Integration Guide](docs/adoption/developer-integration-guide.md),
+  [Mirai Graph CLI](docs/adoption/cli.md),
+  [Test Suite](standard/test-suite.md).
+- Product teams: [Managed Project Control Loop Example](examples/managed-project-control-loop/README.md),
+  [Implementation Control](standard/implementation-control.md),
+  [Implementation Control Cycles](standard/implementation-control-cycles.md),
+  [Development Cockpit](standard/development-cockpit.md),
+  [Feature Implementation Traceability](standard/feature-implementation-traceability.md).
+- Organizations and AI systems: [Graph As AI Brain](standard/graph-as-ai-brain.md),
+  [AI Employee Graph Adoption](docs/adoption/ai-employee-graph.md),
+  [Character Layer Adoption](docs/adoption/character-layer.md),
+  [Organization Governance](standard/organization-governance.md),
+  [Process Control Contract](standard/process-control-contract.md),
+  [Multi-Source Quality Feedback](standard/multi-source-quality-feedback.md).
+
+Core references:
+
+- [Repository Purpose](docs/repository-purpose.md)
+- [Roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+- [Release Process](releases/README.md)
+- [Concept](docs/concept.md)
+- [Terminology](docs/terminology.md)
+- [Standard v0.1 Draft](standard/standard-v0.1.md)
+- [Profiles](profiles/README.md)
+- [Templates](templates/README.md)
+- [1.0 RC Adopter Kit](docs/adoption/adopter-kit.md)
+- [Mirai Graph To Mirai Graph Transition](docs/adoption/mirai-graph-transition.md)
+- [Alpha.10 Adopter Workflow](releases/0.1.0-alpha.10.md)
+- [Alpha.11 Instrumentation Layer](releases/0.1.0-alpha.11.md)
+- [1.0 Release Candidate](releases/1.0.0-rc.1.md)
+- [Evidence Package v0.3](docs/research/evidence-package-v0.3.md)
+
+Current 1.0 release-candidate standard areas:
+
+- [Object Model](standard/object-model.md)
+- [Relation Model](standard/relation-model.md)
+- [Lifecycle Readiness](standard/lifecycle-readiness.md)
+- [Evidence Provenance](standard/evidence-provenance.md)
+- [Context Pack Generation](standard/context-pack-generation.md)
+- [Governance](standard/governance.md)
+- [Graph Seed](standard/graph-seed.md)
+- [Graph Embryo](standard/graph-embryo.md)
+- [Hybrid Source Of Truth](standard/hybrid-source-of-truth.md)
+- [Graph DNA Alignment](standard/graph-dna-alignment.md)
+- [Implementation Control](standard/implementation-control.md)
+- [Launch Record](standard/launch-record.md)
+- [Work State Machine](standard/work-state-machine.md)
+- [Process Control Contract](standard/process-control-contract.md)
+- [Technology Quality Feedback](standard/technology-quality-feedback.md)
+- [Development Cockpit](standard/development-cockpit.md)
+- [Feature Implementation Traceability](standard/feature-implementation-traceability.md)
+- [Multi-Source Quality Feedback](standard/multi-source-quality-feedback.md)
+- [Organization Governance](standard/organization-governance.md)
+- [Recovery Resume](standard/recovery-resume.md)
+- [Risk Control Matrix](standard/risk-control-matrix.md)
+- [Multi-Agent Coordination](standard/multi-agent-coordination.md)
+- [Source Boundary Contract](standard/source-boundary-contract.md)
+- [Route Explanation](standard/route-explanation.md)
+- [Routing Fixtures](standard/routing-fixtures.md)
+- [Federation Health](standard/federation-health.md)
+- [Route Regression](standard/route-regression.md)
+- [Conformance Levels](standard/conformance-levels.md)
+- [Test Suite](standard/test-suite.md)
+
+Runnable materials:
+
+- [Playground](playground/README.md)
+- [1.0 RC Adopter Kit](docs/adoption/adopter-kit.md)
+- [Minimal Graph Example](examples/minimal-graph/README.md)
+- [Minimal Implementation Control Example](examples/implementation-control-minimal/README.md)
+- [Implementation Control Cycles Example](examples/implementation-control-cycles/README.md)
+- [Launch Record Example](examples/launch-record-minimal/README.md)
+- [Process Transition Example](examples/process-transition-minimal/README.md)
+- [Process Control Contract Example](examples/process-control-contract-minimal/README.md)
+- [Technology Quality Feedback Example](examples/technology-quality-feedback-minimal/README.md)
+- [Instrumentation Layer Example](examples/instrumentation-layer-minimal/README.md)
+- [Organization Governance Example](examples/organization-governance-minimal/README.md)
+- [Federation Routing Smoke Example](examples/federation-routing-smoke/README.md)
+- [Synthetic Context-Reduction Benchmark](benchmarks/synthetic-context-reduction-v0/README.md)
+- [Independent Implementation Pilot 001](pilots/independent-implementation-001-conference-planning/reports/pilot-report.md)
+- [Independent Implementation Pilot 002](pilots/independent-implementation-002-software-specification/reports/pilot-report.md)
+- [Independent Implementation Pilot 003](pilots/independent-implementation-003-ai-employee-workflow/reports/pilot-report.md)
+- [Independent Implementation Pilot 004](pilots/independent-implementation-004-research-program/reports/pilot-report.md)
+- [Independent Implementation Pilot 005](pilots/independent-implementation-005-organization-governance/reports/pilot-report.md)
+
+## Validate A Graph Package
+
+Run the initial validator:
+
+```bash
+node packages/cli/validate-mirai-graph.js examples/minimal-graph
+node packages/cli/validate-mirai-graph.js benchmarks/synthetic-context-reduction-v0
+node packages/cli/validate-mirai-graph.js examples/ai-employee-minimal
+node packages/cli/validate-mirai-graph.js examples/skill-runtime-minimal
+node packages/cli/validate-mirai-graph.js seed examples/graph-seed-minimal/graph-seed.json
+node packages/cli/validate-mirai-graph.js profile profiles/software-specification/profile.json
+node packages/cli/validate-mirai-graph.js profile profiles/skill-runtime/profile.json
+node packages/cli/validate-mirai-graph.js context-pack benchmarks/synthetic-context-reduction-v0 benchmarks/synthetic-context-reduction-v0/results/context-pack.json
+node packages/cli/validate-mirai-graph.js launch-record examples/launch-record-minimal/results/launch-record.json
+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-control-contract examples/process-control-contract-minimal/results/process-control-contract.json
+node packages/cli/validate-mirai-graph.js technology-quality-feedback examples/technology-quality-feedback-minimal/results/technology-quality-feedback.json
+node packages/cli/validate-mirai-graph.js development-cockpit examples/instrumentation-layer-minimal/results/development-cockpit.json
+node packages/cli/validate-mirai-graph.js feature-implementation-traceability examples/instrumentation-layer-minimal/results/feature-implementation-traceability.json
+node packages/cli/validate-mirai-graph.js multi-source-quality-feedback examples/instrumentation-layer-minimal/results/multi-source-quality-feedback.json
+node packages/cli/validate-mirai-graph.js graph-dna-alignment examples/graph-dna-alignment-minimal/results/graph-dna-alignment.json
+node packages/cli/validate-mirai-graph.js work-state-machine examples/work-recovery-minimal/results/work-state-machine.json
+node packages/cli/validate-mirai-graph.js recovery-resume-record examples/work-recovery-minimal/results/recovery-resume-record.json
+node packages/cli/validate-mirai-graph.js risk-control-matrix examples/risk-and-coordination-minimal/results/risk-control-matrix.json
+node packages/cli/validate-mirai-graph.js source-boundary-contract examples/source-boundary-minimal/results/source-boundary-contract.json
+node packages/cli/validate-mirai-graph.js examples/organization-governance-minimal
+node packages/cli/seed-preview.js examples/graph-seed-minimal/graph-seed.json
+node packages/cli/context-pack.js benchmarks/synthetic-context-reduction-v0 --task-id task.notify_after_approval
+node packages/cli/readiness-score.js benchmarks/synthetic-context-reduction-v0 --target-mode pilot
+node packages/cli/validate-process-transition-report.js
+node packages/cli/validate-baseline-comparison.js benchmarks/synthetic-context-reduction-v0/results/baseline-comparison-result.json
+node packages/cli/playground-demo.js
+node packages/cli/instrumentation-report.js examples/instrumentation-layer-minimal
+node packages/cli/mirai-graph.js validate examples/minimal-graph
+node packages/cli/mirai-graph.js report validation examples/minimal-graph
+node packages/cli/mirai-graph.js explain process-transition examples/process-transition-minimal/state-machine.json examples/process-transition-minimal/transition-request.json
+node packages/cli/mirai-graph.js report technology-quality-feedback examples/technology-quality-feedback-minimal/results/technology-quality-feedback.json
+node packages/cli/mirai-graph.js report instrumentation examples/instrumentation-layer-minimal
+node packages/cli/mirai-graph.js release state --markdown
+```
+
+The supported 1.0 release-candidate command surfaces are `mirai-graph`,
+`packages/cli/mirai-graph.js`, `packages/cli/mirai_graph.js`,
+`packages/cli/validate-mirai-graph.js` and `mirai-graph-package.json`.
+
+Or run the current smoke checks:
+
+```bash
+npm test
+npm run playground:report
+npm run validate:playground-report
+npm run validate:baseline-comparison
+npm run validate:technology-quality-feedback
+npm run validate:instrumentation-layer
+npm run validate:instrumentation-report
+npm run validate:adopter-workflow
+npm run validate:release-state
+```
+
+Adopter workflow commands:
+
+```bash
+node packages/cli/mirai-graph.js choose-profile
+node packages/cli/mirai-graph.js adopter plan developer
+node packages/cli/mirai-graph.js adopter report templates/software-project-starter
+```
+
+## What This Repository Is Not
+
+This repository is not a dump of private research, company or client material.
+Private project data, internal chats, internal skill sources, secrets and raw
+customer or employee data do not belong here.
+
+Synthetic examples and benchmarks are clearly marked as synthetic. They support
+method inspection and reproducibility, not broad external validity claims.
+
+## License
+
+- Code is licensed under the MIT License. See [LICENSE](LICENSE).
+- Documentation, standard text and research materials are licensed under
+  Creative Commons Attribution 4.0 International. See
+  [LICENSE-DOCS](LICENSE-DOCS).
+
+## Citation
+
+Use [CITATION.cff](CITATION.cff) for citation metadata. Publication links will
+be maintained in `publications/`.

package/ROADMAP.md

@@ -0,0 +1,225 @@
+# Mirai Graph Roadmap
+
+Status: 1.0 release-candidate roadmap
+
+## Phase 0: Public Foundation
+
+Goal: make the repository understandable, safe to open and ready for structured
+growth.
+
+1.0 RC status: implemented.
+
+Done when:
+
+- README exists;
+- repository purpose is documented;
+- license strategy is explicit;
+- citation metadata exists;
+- initial concept and terminology exist;
+- no private source material is present.
+
+Initial artifacts:
+
+- `README.md`
+- `docs/repository-purpose.md`
+- `docs/concept.md`
+- `docs/terminology.md`
+- `ROADMAP.md`
+- `LICENSE`
+- `LICENSE-DOCS`
+- `CITATION.cff`
+
+## Phase 1: Standard Draft
+
+Goal: define the implementation-independent Mirai Graph standard.
+
+1.0 RC status: implemented with notes. The repository now contains the core
+object/relation/readiness/evidence/governance standard plus validator-backed
+sections for graph seed, hybrid source of truth, profiles, implementation
+control, routing control, source boundaries, recovery, risk, process control,
+instrumentation and Character Layer.
+
+Planned artifacts:
+
+- `standard/standard-v0.1.md`
+- `standard/object-model.md`
+- `standard/relation-model.md`
+- `standard/lifecycle-readiness.md`
+- `standard/evidence-provenance.md`
+- `standard/context-pack-generation.md`
+- `standard/governance.md`
+- `standard/profiles.md`
+- `standard/conformance-levels.md`
+- `standard/test-suite.md`
+
+Additional 1.0 RC artifacts now present:
+
+- graph seed and graph embryo;
+- hybrid source of truth;
+- graph-as-AI-brain;
+- action/runtime boundary;
+- implementation-control cycles;
+- launch record;
+- work state machine;
+- process-control contract;
+- technology quality feedback;
+- recovery/resume;
+- risk-control matrix;
+- multi-agent coordination;
+- source-boundary contract;
+- route explanation, fixtures, regression and federation health.
+- development cockpit, feature implementation traceability and multi-source
+  quality feedback;
+- Character Layer profile, starter pack, integration evidence, portability
+  evidence shape and 1.0 readiness artifact.
+
+Readiness target:
+
+`1_0_release_candidate_ready_with_notes` for public review and implementation
+pilots.
+
+## Phase 2: Method And Adoption Kit
+
+Goal: help teams use Mirai Graph in real work.
+
+1.0 RC status: implemented with notes. The current repository includes getting
+started material, profile conformance fixtures, AI employee adoption, seed to
+validated package tutorial, implementation-control examples, managed-project
+examples, Character Layer adoption, starter templates and public-safe transfer
+notes.
+
+Planned artifacts:
+
+- adoption guide;
+- project profile;
+- product profile;
+- software-specification profile;
+- organization-governance profile;
+- human-AI system profile;
+- implementation checklist;
+- examples and anti-examples.
+
+Post-1.0 gaps:
+
+- final npm publication and GitHub Release execution after release-state
+  approval;
+- import/export helpers for starter packages;
+- stronger non-software adoption recipes;
+- external adopter feedback from independent pilots.
+
+Implemented adopter-workflow focus:
+
+- profile-selection guide;
+- starter-template happy path;
+- human-readable validation reports for adopter workflows;
+- packaged adopter command sequence;
+- organization-governance adoption report.
+
+Initial implementation:
+
+- `docs/adoption/choose-profile.md`;
+- `mirai-graph choose-profile`;
+- `mirai-graph adopter plan <role-or-profile>`;
+- `mirai-graph adopter report <template-dir>`;
+- `validate:adopter-workflow`.
+
+## Phase 3: Reusable Tooling
+
+Goal: make adoption practical for developers.
+
+1.0 RC status: implemented with notes. The CLI validates packages, profiles,
+context packs, graph seeds, implementation-control cycles, launch records,
+process transitions, process-transition decision reports, process-control
+contracts, technology quality feedback reports, DNA alignment, work state,
+recovery, risk, coordination, source boundaries, routing-control examples and
+baseline-comparison artifacts, instrumentation artifacts and Character Layer
+readiness.
+
+Planned artifacts:
+
+- JSON schemas;
+- validator;
+- CLI package;
+- reference context-pack generator;
+- import/export helpers;
+- test fixtures.
+
+Post-1.0 gaps:
+
+- package and publish the CLI as a cleaner public developer interface;
+- add import/export helpers;
+- extend human-readable reports beyond process-transition and instrumentation
+  checks;
+- add process-control explanation output and richer report formatting.
+- add adoption recipes for technology quality feedback in non-software
+  workflows.
+
+Current tooling target:
+
+```text
+choose profile -> starter template -> validate -> report -> launch/evidence/kaizen
+```
+
+The standard must remain implementation-independent. Tooling validates and
+demonstrates the standard; it does not replace the standard.
+
+## Phase 4: Evidence And Playground
+
+Goal: provide reproducible public-safe demonstrations.
+
+1.0 RC status: implemented with notes. Synthetic benchmark, baseline-comparison
+artifact, pilot packages, profile conformance results and runnable CLI examples
+exist. The playground is a deterministic local report package rather than a
+hosted interactive app.
+
+Planned artifacts:
+
+- synthetic context-reduction benchmark;
+- benchmark runner;
+- playground;
+- semantic-completeness review protocol;
+- limitations and threats-to-validity notes.
+
+Post-1.0 gaps:
+
+- separate synthetic evidence, pilot evidence and scientific claims more
+  visibly;
+- connect instrumentation reports to reproducibility packages and pilot
+  protocols without exposing private runtime traces;
+- add more independent implementation pilots;
+- explore an interactive playground after CLI-first reports stabilize.
+
+Synthetic materials must remain clearly separated from real-world validation.
+
+## Phase 5: Publication And Ecosystem
+
+Goal: connect the repository to research publications and external adoption.
+
+1.0 RC status: early. Citation metadata, publication notes and evidence package
+v0.3 exist, but the project still needs public publication records, stronger
+reviewer protocols and external adoption evidence before making broad
+scientific claims.
+
+Planned artifacts:
+
+- publication index;
+- citation notes;
+- reproducibility records;
+- contributor guide;
+- release process;
+- public examples from approved external adopters.
+
+## Near-Term Work After 1.0 RC
+
+1. Execute the `1.0.0-rc.1` release: tag, GitHub Release and npm publication
+   only after release-state checks are accepted.
+2. Continue adopter workflow: import/export helper skeletons and richer report
+   formatting 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
+   portability claims.
+6. Explore a local interactive playground only after deterministic report
+   fixtures remain stable.
+7. Turn evidence package v0.3 into a publication-ready reproducibility bundle.

package/benchmarks/protocols/measure-convert-optimize.md

@@ -0,0 +1,131 @@
+# Measure-Convert-Optimize Protocol
+
+Status: initial public protocol
+
+## Purpose
+
+Mirai Graph adoption must be measured, not assumed to be better.
+
+This protocol defines how to compare a current workflow with a Mirai Graph-assisted
+workflow.
+
+## Cycle
+
+```text
+freeze benchmark
+-> measure current mode
+-> convert selected scope to Mirai Graph
+-> measure graph mode
+-> compare
+-> optimize
+-> validate
+-> scale
+```
+
+## 1. Freeze Benchmark
+
+Before converting a target scope, freeze:
+
+- benchmark suite;
+- dataset;
+- task ids;
+- expected outputs;
+- acceptance criteria;
+- review policy;
+- metrics.
+
+Do not change the suite after current-mode baseline if direct comparison is
+required.
+
+## 2. Measure Current Mode
+
+Record:
+
+- materials read;
+- context size;
+- time to relevant context;
+- time to done;
+- wrong assumptions;
+- missed dependencies;
+- user corrections;
+- rework cycles;
+- evidence references used;
+- final result;
+- reviewer notes.
+
+## 3. Convert Selected Scope
+
+Convert only a small scope first:
+
+- goals;
+- objects;
+- relations;
+- evidence;
+- readiness;
+- governance gates;
+- context-pack boundary.
+
+Do not convert a whole organization before validating a local graph.
+
+## 4. Measure Graph Mode
+
+Record:
+
+- profile;
+- graph depth;
+- objects considered;
+- relations traversed;
+- generated context size;
+- context pack contents;
+- stale findings;
+- warnings;
+- final result;
+- reviewer notes.
+
+## 5. Compare
+
+Compare only when:
+
+- suite version matches;
+- dataset version matches;
+- task list matches;
+- acceptance criteria match;
+- review policy matches.
+
+If these changed, start a new experiment series.
+
+## 6. Optimize
+
+Use comparison results:
+
+- low precision -> improve object selection;
+- low recall -> improve relations or extraction;
+- negative context reduction -> narrow context profile;
+- missed dependencies -> improve impact traversal;
+- high review overhead -> simplify graph granularity;
+- weak evidence coverage -> improve evidence modeling.
+
+## 7. Validate
+
+Use a separate evaluation set where possible.
+
+Do not tune only on the same tasks used for final claims.
+
+## Minimum Metrics
+
+- `time_to_context`;
+- `context_units`;
+- `context_precision`;
+- `missed_dependencies`;
+- `wrong_assumptions`;
+- `rework_cycles`;
+- `evidence_coverage`;
+- `time_to_done`;
+- `manual_review_overhead`.
+
+## Claim Rule
+
+Use results only for claims supported by the protocol.
+
+A local pilot can support local usefulness. It does not prove universal
+validity.

package/benchmarks/synthetic-context-reduction-v0/README.md

@@ -0,0 +1,70 @@
+# Synthetic Mirai Graph Benchmark v0
+
+Status: draft synthetic package for public-method inspection
+
+This package is artificial. It does not contain private project, customer, employee, source-chat or private skill material.
+
+## Purpose
+
+The package demonstrates the structure of the Mirai Graph context-selection
+method on a small synthetic software-specification scenario.
+It is intended for public inspection of the method, not for empirical claims
+about external performance.
+
+## Scenario
+
+A fictional modular publishing platform is planning four related packages:
+
+- identity and access;
+- content workflow;
+- audit events;
+- notification delivery.
+
+Feature notes, graph objects, relations and context-selection tasks are
+provided as small files that mimic the shape of an evolving specification
+workspace.
+
+## Files
+
+- `source-corpus/`: synthetic source notes.
+- `graph/objects.json`: graph objects extracted from the source corpus.
+- `graph/relations.json`: typed relations between graph objects.
+- `tasks/tasks.json`: sample context-selection tasks.
+- `expected/context-pack-compact.md`: expected compact context package for one
+  task.
+- `metrics/example-metrics.json`: illustrative metric calculation.
+- `scripts/calculate-context-reduction.js`: repeatable calculation for the
+  illustrative synthetic metric.
+
+The graph files are normalized to the initial Mirai Graph v0.1 draft object and
+relation shape.
+
+## Limits
+
+This package supports reproducibility of the method structure only. It does not
+validate external generalization, agent safety or task success.
+
+An initial semantic-completeness review is available at:
+
+`reviews/semantic-completeness-review.json`
+
+## Example Calculation
+
+Run from this package directory:
+
+```bash
+node scripts/calculate-context-reduction.js
+```
+
+Expected result:
+
+```json
+{
+  "schema_version": "0.1.0",
+  "task_id": "task.notify_after_approval",
+  "baseline_context_units": 620,
+  "graph_context_units": 270,
+  "total_reduction_percent": 56.4516,
+  "note": "Synthetic demonstration only; do not merge with internal empirical metrics."
+}
+```