<p align="center">
  <img
    src="Assets/project-relay-assets/logo/headers/wordmark-lockup-readme.svg"
    alt="Project Relay — One record · Many minds"
    width="480"
  />
</p>

# Project Relay

Project Relay is an evidence-governed coordination layer for multiple AI systems and human reviewers. It uses a Git repository as a shared, inspectable record while MCP provides a provider-neutral integration surface.

> **Status:** pre-alpha M1 candidate. The name is a working title, the protocol is unstable, and no production deployment is implied.

## Why it exists

Multi-model work usually fragments across chats, vendors, local tools, and copied prompts. Relay gives that work a common protocol:

- one explicit question per task;
- named owners, reviewers, and decision authorities;
- immutable evidence references and reproducible commands;
- independent review before acceptance;
- recorded disagreement instead of silent consensus;
- human approval for consequential decisions;
- no requirement for every model to share one vendor API.

Relay coordinates work. It does **not** decide whether a scientific claim is true, replace peer review, or make model output trustworthy by default.

## Architecture at a glance

```text
AI clients / humans / IDE agents
              |
          MCP interface
              |
     Relay protocol + policy
              |
 append-only events and evidence
              |
        Git repository
              |
 read-only web console / GitHub UI
```

The canonical record is validated JSON plus referenced artifacts in Git history. Issues, labels, dashboards, and the Pages console are projections of that record, never alternate sources of truth.

## Current public milestone

The local M1 vertical slice and the network-free M2 adapter contract now include:

- JSON Schemas for tasks, events, evidence, reviews, and decisions;
- deterministic canonicalisation and SHA-256 provenance helpers;
- append-only event-chain verification plus policy-checked task transitions;
- an evidence-bundle CLI that hashes declared artifacts without executing commands;
- a read-only MCP server with tools, a task resource, and an independent-review prompt;
- a deterministic static console projection of state, history, and gate results;
- a synthetic submission, review, remediation, resubmission, and human-decision fixture;
- a deterministic GitHub mutation proposal contract with content-addressed inputs;
- a memory-only fake GitHub adapter covering conflicts, retries, partial failure,
  idempotent replay, concurrency, authorization failure, and redaction;
- Windows and Linux CI conformance coverage plus a public-boundary scanner.

Authenticated GitHub writes, remote MCP deployment, and hosted multi-tenant
operation remain deliberately deferred until their threat models and approval
boundaries are reviewed.

## Quick start

Requires Node.js 24 or newer.

```bash
npm install
npm run check
npm run mcp
```

Check direct dependency versions without changing the repository:

```bash
npm run versions:check
```

Run the offline local doctor for measured runtime, Git, lockfile, workspace, and worktree checks:

```bash
npm run doctor
```

To review conservative updates and receive an interactive `[y/N]` installation prompt:

```bash
npm run versions:update
```

The MCP process uses stdio and reads the workspace specified by `RELAY_WORKSPACE` (the current directory by default):

```json
{
  "mcpServers": {
    "project-relay": {
      "command": "npm",
      "args": ["--prefix", "/absolute/path/to/Project-Relay", "run", "mcp"],
      "env": {
        "RELAY_WORKSPACE": "/absolute/path/to/a/relay-workspace"
      }
    }
  }
}
```

Use `examples/m1` to inspect the complete local remediation loop. `examples/minimal` remains the smallest M0 kernel fixture.

Create a validated evidence bundle from an explicit manifest:

```bash
npm run evidence:create -- --manifest path/to/manifest.json --output path/to/bundle.json
```

The command reads and hashes declared artifacts. It does not execute the commands recorded in the manifest.

## Safety and publication boundary

This public repository must never contain credentials, private datasets, unpublished ITSM material, personal information, confidential prompts, or commercial records. `.gitignore` is not a security boundary: releases must be exported from a separate private workspace using an explicit allowlist and reviewed as if every commit were permanent.

See [Publication Boundary](docs/PUBLICATION_BOUNDARY.md) and [Security](SECURITY.md) before contributing.

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Protocol and decision gates](docs/PROTOCOL.md)
- [Public/private publication boundary](docs/PUBLICATION_BOUNDARY.md)
- [Version maintenance](docs/VERSION_MAINTENANCE.md)
- [Antigravity handoff](docs/ANTIGRAVITY_HANDOFF.md)
- [Antigravity integration guide](docs/clients/antigravity.md)
- [Roadmap](docs/ROADMAP.md)
- [Contributing](CONTRIBUTING.md)
- [Licence status](LICENSE-STATUS.md)

## Licence status

Project Relay is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) and [LICENSE-STATUS.md](LICENSE-STATUS.md) for details.