From f2207209c040bd2936d444d3785caa648c6f472a Mon Sep 17 00:00:00 2001 From: AlexPaiva Date: Tue, 21 Jul 2026 16:02:30 +0100 Subject: [PATCH 1/2] docs: add a contents index, a use-it-on-your-project guide, and sell the model roles Add a table of contents to the README, a developer-facing "Use it on your own project" section with a use-case to command table pointing at ADOPTION, and a lead paragraph on GPT-5.6 and Codex that states why each model is load-bearing and how self-grading is designed out. Rename the model section heading for a clean anchor. Docs only. No product, verifier, evaluator, evidence, or model-boundary change. --- README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bdb31b7..c88eb54 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ A human approves the exact patch. An unchanged deterministic verifier decides wh --- +**Contents:** [The 30-second version](#the-30-second-version) · [See the proof](#see-the-proof) · [The problem](#the-problem) · [Who decides it is fixed](#who-decides-it-is-fixed) · [Try it yourself](#try-it-yourself) · [Use it on your own project](#use-it-on-your-own-project) · [How it works](#how-it-works) · [GPT-5.6 and Codex](#gpt-56-and-codex) · [Architecture](#architecture) · [Limitations](#limitations) + ## The 30-second version 1. **A user turned personalization off.** The interface, the browser storage, and the backend all reported the same thing: off. @@ -131,6 +133,19 @@ npm run promiseproof -- check \ Swap in the committed `artifacts/verify/broken-off.example.json` and `gate` returns `BROKEN_PROMISE` (exit 2). No `init`, no scaffolding, no key. Full CLI, exit codes, and exact scope are in [PromiseProof Verify](#try-promiseproof-verify) below. +## Use it on your own project + +You already have the inputs this needs: a user-facing promise, evidence from your app, and a CI pipeline. Pick the surface that fits how you work. + +| You want to | Do this | +| --- | --- | +| Try it with zero setup | Open the [hosted verifier](https://promiseproof.alex0paiva0.workers.dev/verify/?judge=1), then load your own OFF and ON bundles under "Bring your own evidence" | +| Gate a change locally | `npm run promiseproof -- gate --off off.json --on on.json` | +| Reproduce a report from evidence | `npm run promiseproof -- check --report report.json --off off.json --on on.json` | +| Fail CI on a broken promise | Add the [GitHub Action](#try-it-yourself) step, pinned to `@submission-rc-03` | + +The evidence envelope, the report format, exit codes, and the trust boundaries are all in [ADOPTION.md](ADOPTION.md). One contract family is supported today, `activity-personalization/v1`, and that guide shows the exact bundle shape and how to produce it. + ## What was built in one Build Week PromiseProof is new work, built July 14 to July 21, 2026, with a linear history a judge can walk from tag to tag: @@ -288,7 +303,9 @@ The investigation makes **exactly two provider calls and at most one replay exec GPT-5.6 never receives the selected fixture, source paths, logs, screenshots, or root-cause labels. Deterministic TypeScript and Playwright alone decide whether the promise passed. -## GPT-5.6 + Codex +## GPT-5.6 and Codex + +PromiseProof is built on exactly what these models are good at, and bounded by exactly what you should not trust them with. GPT-5.6's structured reasoning and strict function-calling are what make the investigation both capable and safe: the model reasons over a sanitized dossier and ranks competing causes, yet it can act only through one strict tool call into a fixed allowlist, and its result schema has no field in which to write a verdict. The usual worry about an LLM, that it grades its own work, is designed out rather than hoped away. Codex's agentic, multi-file editing is what turns a diagnosis into a real fix: a constrained two-file source patch plus a focused regression test, prepared in isolation. The models do the open-ended reasoning and code work; a deterministic evaluator, not either model, keeps the verdict. **GPT-5.6** is part of the runtime product architecture. It receives a sanitized, versioned dossier, proposes and ranks diagnostic hypotheses, and selects exactly one allowlisted factual replay through a strict function call. After deterministic code runs that replay, it may update only the existing hypothesis IDs using allowlisted evidence references. It cannot run an arbitrary command, choose an unregistered replay, or determine the product verdict. From ab0c4bf4bf33a6ec6f1179b59e72444cb07196a6 Mon Sep 17 00:00:00 2001 From: AlexPaiva Date: Tue, 21 Jul 2026 16:14:14 +0100 Subject: [PATCH 2/2] docs: tighten the adoption intro and the model-authority wording State the evidence precondition for adopting the verifier instead of implying any app already emits compatible evidence, and describe the investigation as capable with bounded authority rather than "safe." --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c88eb54..d02c5f1 100644 --- a/README.md +++ b/README.md @@ -135,7 +135,7 @@ Swap in the committed `artifacts/verify/broken-off.example.json` and `gate` retu ## Use it on your own project -You already have the inputs this needs: a user-facing promise, evidence from your app, and a CI pipeline. Pick the surface that fits how you work. +If your app can emit the supported OFF and ON evidence for this contract, pick the surface that fits how you work. The evidence shape is defined in [ADOPTION.md](ADOPTION.md). | You want to | Do this | | --- | --- | @@ -305,7 +305,7 @@ GPT-5.6 never receives the selected fixture, source paths, logs, screenshots, or ## GPT-5.6 and Codex -PromiseProof is built on exactly what these models are good at, and bounded by exactly what you should not trust them with. GPT-5.6's structured reasoning and strict function-calling are what make the investigation both capable and safe: the model reasons over a sanitized dossier and ranks competing causes, yet it can act only through one strict tool call into a fixed allowlist, and its result schema has no field in which to write a verdict. The usual worry about an LLM, that it grades its own work, is designed out rather than hoped away. Codex's agentic, multi-file editing is what turns a diagnosis into a real fix: a constrained two-file source patch plus a focused regression test, prepared in isolation. The models do the open-ended reasoning and code work; a deterministic evaluator, not either model, keeps the verdict. +PromiseProof is built on exactly what these models are good at, and bounded by exactly what you should not trust them with. GPT-5.6's structured reasoning and strict function-calling are what make the investigation capable while keeping its authority bounded: the model reasons over a sanitized dossier and ranks competing causes, yet it can act only through one strict tool call into a fixed allowlist, and its result schema has no field in which to write a verdict. The usual worry about an LLM, that it grades its own work, is designed out rather than hoped away. Codex's agentic, multi-file editing is what turns a diagnosis into a real fix: a constrained two-file source patch plus a focused regression test, prepared in isolation. The models do the open-ended reasoning and code work; a deterministic evaluator, not either model, keeps the verdict. **GPT-5.6** is part of the runtime product architecture. It receives a sanitized, versioned dossier, proposes and ranks diagnostic hypotheses, and selects exactly one allowlisted factual replay through a strict function call. After deterministic code runs that replay, it may update only the existing hypothesis IDs using allowlisted evidence references. It cannot run an arbitrary command, choose an unregistered replay, or determine the product verdict.