# Decision Room · Project Rails

Decision Room is an open-source experiment in proof-carrying project execution. It turns a Project Passport into a dependency-aware task graph, compares only receipt-backed providers, records route approvals, and keeps artifacts, verification, and checkpoints visible to both people and AI agents.

Live Site: <https://decision-room.metaversebldr7.chatgpt.site>

Public source: <https://github.com/metaversebldr7-web/decision-room-project-rails>

## What is real in this release

- A browser workspace for a Project Passport, task graph, provider catalog, route scoring, human approvals, artifacts, verification records, and handoff checkpoint history.
- Twelve page-defined WebMCP tools, including the read-only `read_project_rails` tool and the receipt-gated `record_provider_handshake` tool.
- A public Streamable HTTP MCP endpoint at `/api/mcp` that exposes **only** `read_project_rails`.
- Owner-gated, revision-checked shared-state writes. Anonymous visitors can inspect a Project Passport only while its sensitivity is `Public`; shared writes require the configured Site owner to sign in with ChatGPT. Owner saves are serialized in one page, stale-tab writes receive `409`, and a failed shared save is immediately preserved as a browser-local draft.
- A fail-closed route gate: a provider must be `Connected`, carry a recent passed capability-scoped handshake attestation, attest the task's required capabilities, and have evidence for every numeric routing score. Hard criteria must be scored; optional unknowns remain absent rather than becoming fabricated zeroes. Route comparison discloses weighted evidence coverage and ranks coverage before point score. Route coverage requires an actual assignment, and finalization requires a separate human approval for every current route.
- Status proof gates: `Complete` requires a named artifact with a durable location; `Verified` additionally requires a passing verification method and observable evidence. Imported unsupported claims are downgraded.
- A tested two-plane event contract: mergeable working events are non-authoritative; proof events form an append-only hash chain.
- A local fixture execution proof with artifacts, hashes, verification receipts, and a handoff checkpoint.

The server-rendered root exposes visible links to the public Project Passport JSON, read-only MCP endpoint, and MIT source repository so non-JavaScript agents and crawlers can discover the rails. This is discoverability evidence, not a claim that any particular third-party client is compatible.

The public release has dated receipts for the deployed source version, anonymous page and API access, defensive response headers, anonymous-write denial, a real browser-agent WebMCP read, a deployed remote MCP initialize → list → read call, the public MIT-licensed source repository, and a signed-in owner write. They are kept under `receipts/`; each receipt states its own limits. An earlier production account-selection attempt reached the authentication callback, but returned the application's `404` surface and left the root `public-read`; that negative result remains preserved. Sites version 11 subsequently deployed the dispatch-owned ChatGPT sign-in integration. Fresh anonymous, remote-MCP, and browser-WebMCP checks passed, followed by a successful owner session, two bounded `PUT /api/project-rails` responses at `200`, and an anonymous persistence check of the resulting receipt-backed artifact.

## What this release does not claim

Decision Room does not call Cursor, Grok/xAI, Claude, ChatGPT APIs, Meshy, Base44, Visual Studio, or a private server in this release. Documentation, a product subscription, a supplied receipt reference, or a visible UI is not independent replay of a connection test. `Connected` means a dated, capability-scoped handshake attestation was recorded; each receipt states what was actually observed. Prices remain unknown unless a dated source was recorded. A route assignment is a decision record, not proof that external work ran.

The browser loads the public shared rail by default. A public visitor's first edit creates an explicitly labeled browser-local draft, and refreshing the shared rail does not silently overwrite that draft. Only the signed-in owner can sync owner-rail edits into D1. The public remote MCP endpoint is deliberately read-only. Route-proposal tools cannot self-record human approval.

## Architecture

```text
Browser / WebMCP tools ── local Project Passport
          │
          ├── signed-in owner ── PUT /api/project-rails ── D1 shared rail
          └── public visitor ─── GET /api/project-rails ── public data only

External MCP client ───── POST /api/mcp ── read_project_rails only

Proof core ── working events + append-only proof ledger + provider/approval gate
```

## Local development

Requirements: Node.js 22.13 or newer.

```bash
npm ci
npm run dev
```

The official Sites development plugin provides a simulated ChatGPT user, `seedy@sites.test`. Set `OWNER_EMAIL=seedy@sites.test` in an ignored local environment file to test owner-gated shared writes. Never commit a real owner email, API key, OAuth token, password, or server credential.

## Verification

```bash
npm run release:check
```

The release check runs lint, TypeScript type-checking, a production build, UI tests, the event-contract and provider-gate suite, owner-access and stale-write tests, and a built-worker MCP initialize → list → read call.

After deployment, run the no-dependency remote probe:

```bash
MCP_ENDPOINT=https://your-site.example/api/mcp npm run probe:mcp
```

The probe hashes the responses and session identifier; it does not print or persist authorization material.

## WebMCP tool catalog

- `read_project_rails`
- `set_project_passport`
- `add_or_update_project_task`
- `add_or_update_capability_provider`
- `attach_provider_evidence`
- `record_provider_handshake`
- `score_provider_for_task`
- `assign_project_route`
- `record_project_artifact`
- `record_task_verification`
- `create_project_checkpoint`
- `finalize_project_route`

## Proof artifacts

- `contracts/decision-room-event-contract.json` — machine-readable two-plane event contract.
- `contracts/project-rails-routing-policy-v2.json` — versioned policy for optional unknowns, evidence coverage, and coverage-first comparison; the historical event-contract v1 bytes remain unchanged.
- `src/decision-room-core.mjs` — dependency-free reference gate and ledger implementation.
- `receipts/` — handshake, approval, execution, verification, and proof-ledger receipts.
- `receipts/webmcp-browser-call-2026-08-30.json` — real page WebMCP discovery and read call.
- `receipts/webmcp-browser-call-hardened-2026-08-30.json` — post-hardening 12-tool catalog and real read call, including the route-approval schema check.
- `receipts/remote-mcp-public-read-2026-08-30.json` — deployed `/api/mcp` initialize, one-tool discovery, and read call.
- `receipts/remote-mcp-public-read-hardened-2026-08-30.json` — post-hardening `/api/mcp` initialize, one-tool discovery, and read call.
- `receipts/public-access-owner-gate-2026-08-30.json` — anonymous page/API read plus anonymous shared-write denial.
- `receipts/sites-public-deployment-hardened-2026-08-30.json` — public Sites version 10 bound to the deployed source commit.
- `receipts/post-deploy-public-surface-2026-08-30.json` — anonymous route, policy, CSP, HSTS, and write-denial observations.
- `receipts/github-public-repository-2026-08-30.json` — anonymous repository, exact `main` commit, MIT license, and scrubbed hosting-metadata observations.
- `receipts/owner-write-bypass-negative-2026-08-30.json` — negative control showing that an identity-less Sites bypass token did not satisfy the application owner gate.
- `receipts/chatgpt-auth-callback-negative-2026-08-30.json` — sanitized negative authentication result: account selection reached `/callback`, the application returned `404`, public-read access remained in effect, and no owner identity or write was proven.
- `receipts/sites-public-deployment-v11-auth-2026-08-30.json` — Sites version 11 deployment plus post-deployment anonymous page, API, crawler-policy, defensive-header, and write-denial checks.
- `receipts/remote-mcp-public-read-v11-2026-08-30.json` — version-11 `/api/mcp` initialize, exactly-one-tool discovery, and public Project Passport read.
- `receipts/webmcp-browser-call-v11-2026-08-30.json` — version-11 browser-agent discovery of all 12 WebMCP tools and a real public Project Passport read.
- `receipts/chatgpt-owner-auth-write-v11-2026-08-30.json` — sanitized proof that version-11 sign-in entered the owner rail, bounded writes returned `200`, and an anonymous read observed the persisted artifact without retaining identity or credential material.
- `receipts/public-release-checkpoint-v11-2026-08-30.json` — final public-rail state: all six release tasks Verified, one unchanged receipt-backed provider, two unchanged unapproved routes, three recovery checkpoints, and no route finalization claim.
- `implementation-checkpoint-2026-08-30-local-e2e.json` — recovery checkpoint for the local proof.
- `docs/PROVIDER_RAILS_CONTRACT.md` — adapter, work-order, and receipt boundaries.
- `docs/PUBLIC_QA_RECONCILIATION_2026-08-30.md` — independent public-review findings reconciled against direct receipts and release fixes.

`decision-room-project-passport.json` is the hash-linked **historical pre-public local proof snapshot** used by the dated event-contract receipts; it is not the current live Project Passport. The current public truth is the Site's shared rail together with the dated deployment, access, WebMCP, and remote-MCP receipts.

## Public deployment safety

Production requires `OWNER_EMAIL` as a server-side secret. The `oai-authenticated-user-email` request header is trusted only behind the Sites identity dispatcher; a standalone deployment must replace this with its own authenticated identity boundary. The application hides non-public shared state from anonymous HTTP and MCP readers, requires the current revision ETag for owner writes, limits Project Passport writes to 1 MB, serves CSP/HSTS and related defensive headers, and publishes an explicit allow-all `robots.txt`. The public MCP is a bounded read-only experiment and currently has no application-level rate limiter; sustained use needs platform monitoring and a rate-control decision. Public release data must not contain local filesystem paths, private identifiers, secrets, or records marked `Internal`, `Sensitive`, or `Restricted`.

See [SECURITY.md](SECURITY.md) for the threat boundary and [CONTRIBUTING.md](CONTRIBUTING.md) for contribution requirements.

## License

MIT. See [LICENSE](LICENSE).