Merge pull request #4 from AlexPaiva/feature/final-visual-story

docs: visual judge proof and finished Build Week summary

Author: AlexPaiva

.github/actions/verify/README.md

@@ -40,7 +40,7 @@ Reproduce a report from its evidence:
     on_evidence: artifacts/personalization-on.json
 ```
 
-After a release tag contains the Action, replace `@main` with that immutable tag.
+The examples pin `@submission-rc-03`, the immutable release that contains this Action. Use `@main` only if you intentionally want to track later changes on the default branch.
 
 ## Inputs
 

ADOPTION.md

@@ -124,6 +124,37 @@ npm run promiseproof -- check \
 
 `check` also accepts a single report with `--report ... --evidence ...`.
 
+## Committed examples
+
+The repository ships a ready evidence set under `artifacts/verify/`, so you can reproduce a result without scaffolding anything first:
+
+- `passing-off.example.json`, `passing-on.example.json`: a passing OFF and ON pair.
+- `passing-gate.report.json`, `passing-gate.report.md`: the sealed gate report for that pair.
+- `broken-off.example.json`: an OFF bundle that breaks the promise.
+
+```bash
+# Regenerate the sealed report byte for byte:
+npm run promiseproof -- check \
+  --report artifacts/verify/passing-gate.report.json \
+  --off artifacts/verify/passing-off.example.json \
+  --on artifacts/verify/passing-on.example.json   # BOUND_AND_REPRODUCED (exit 0)
+
+# Watch a broken bundle fail the gate:
+npm run promiseproof -- gate \
+  --off artifacts/verify/broken-off.example.json \
+  --on artifacts/verify/passing-on.example.json   # BROKEN_PROMISE (exit 2)
+```
+
+## Programmatic use
+
+PromiseProof does not publish an npm package, and the verdict is not hidden behind a service. Inside a checkout, the entire verdict comes from one pure function, `evaluatePromise(evidence)` in `src/shared/evaluator.ts`: no network, no state, no model. This deterministic function is the authority that owns the verdict. The CLI, the GitHub Action, and the hosted browser verifier all call it, which is why their results are identical, and the models never call it or produce its output.
+
+```ts
+import { evaluatePromise } from "./src/shared/evaluator";
+
+const evaluation = evaluatePromise(evidence); // deterministic verdict, clause results, and violations
+```
+
 ## Reports
 
 `verify` and `gate` write two files to `--out`:

BUILD_WEEK.md

@@ -1,5 +1,47 @@
 # PromiseProof Build Week Log
 
+## What PromiseProof shipped by 2026-07-21
+
+PromiseProof is a new OpenAI Build Week project, built July 14 to July 21, 2026. This section summarizes the finished release. The dated milestone log that follows is the original historical record.
+
+The finished release carries one broken product promise from symptom to proof:
+
+- a synthetic reference product with a real browser-to-backend HTTP boundary;
+- one user-facing "off means off" promise that crosses UI, storage, network, and backend;
+- two independent seeded defects that produce different evidence and different violation codes, so one flag cannot explain both and one fix cannot silence the other;
+- a bounded GPT-5.6 investigation over a sanitized, versioned dossier;
+- two allowlisted deterministic factual replays;
+- an authentic, human-approved Codex source repair;
+- exact, digest-bound human approval of the patch;
+- application only in a fresh disposable git worktree;
+- an unchanged deterministic verifier that alone decides PASS;
+- a five-stage hosted walkthrough of the recorded run;
+- external, evidence-only verification through a repository-local CLI;
+- deterministic JSON and Markdown reports, bound to the evaluator source by digest;
+- complete report reproduction that recomputes the report, not only its hashes;
+- a hosted semantic tamper challenge that runs entirely in the browser;
+- a reusable GitHub Action exercised on Windows, Ubuntu, and macOS runners;
+- public judge and adoption documentation.
+
+Timeline, tag by tag:
+
+- **Jul 14** baseline, the deterministic initialization-race proof, and the propagation-failure defect (`build-week-baseline`, `milestone-02-deterministic-foundation`).
+- **Jul 15** the bounded GPT-5.6 investigation layer (`milestone-03-gpt56-investigation`).
+- **Jul 16** the authentic Codex repair with human approval (`milestone-04-authentic-repair-proof`, `submission-hardening-01`).
+- **Jul 17** CI hardening and the judge experience (`ci-green-01`, `judge-rehearsal-01`, `judge-experience-01`).
+- **Jul 20 to 21** the public product: hosted verifier and CLI (PR #1), the reusable GitHub Action (PR #2), and the judge package (PR #3), tagged `submission-rc-01` through `submission-rc-03`.
+
+**Why one week matters.** Building this in a single week demonstrates execution speed and architectural closure: the complete working lifecycle, its tests, the authentic repair proof, the hosted product, the CLI, and the CI integration were all built and verified inside the submission period. It is not a claim of production maturity or third-party adoption. The honest scope and limitations are recorded below and in the [README](README.md#limitations).
+
+Start here:
+
+- [JUDGE_START_HERE.md](JUDGE_START_HERE.md)
+- [ADOPTION.md](ADOPTION.md)
+- Hosted walkthrough: https://promiseproof.alex0paiva0.workers.dev/walkthrough/
+- Hosted verifier: https://promiseproof.alex0paiva0.workers.dev/verify/?judge=1
+- Pull requests: [#1](https://github.com/AlexPaiva/PromiseProof/pull/1), [#2](https://github.com/AlexPaiva/PromiseProof/pull/2), [#3](https://github.com/AlexPaiva/PromiseProof/pull/3)
+- Submission tags: `submission-rc-01`, `submission-rc-02`, `submission-rc-03`
+
 ## Project baseline — 2026-07-14
 
 PromiseProof begins as a new OpenAI Build Week project. `AGENTS.md` is the canonical product and engineering specification.

JUDGE_START_HERE.md

@@ -35,6 +35,18 @@ A bundled Action that runs the same verifier in CI with no `npm install`, no bro
 | Human | Yes | No | Yes | No |
 | Unchanged verifier | No | No | No | Yes |
 
+## The model cannot award itself PASS
+
+This split is enforced in code and covered by tests, not merely asserted:
+
+- **No verdict field exists.** The final investigation contract in `src/investigation/contracts.ts` has no overall-verdict field; the only verdict-adjacent limitation code is `diagnostic_not_verdict` ("Diagnostic hypotheses do not determine the product promise verdict.").
+- **Verdict language from the model is rejected.** `tests/investigation/investigation.unit.ts` asserts `PP_INV_VERDICT_LANGUAGE_REJECTED` when model output uses reserved verdict wording.
+- **A claimed model verdict is ignored by the matrix.** `tests/judge/rehearsal.unit.ts`, "verification matrix rejects missing propagation control, browser errors, and model verdict claims," proves a supplied `modelVerificationVerdict` cannot turn a fail into a pass.
+- **Approval is human and digest-bound.** `tests/repair/artifact-approval.unit.ts`, "accepts only the exact APPROVE or REJECT phrase for the current digest," proves the patch is approved by a human against its exact fingerprint, and the lifecycle records `modelVerdictUsed: false`.
+- **The verdict path needs no model at all.** `tests/judge/rehearsal.unit.ts`, "offline rehearsal environment removes model credentials and Codex configuration," runs the whole verification with no model present.
+
+This is deterministic, code-level separation. It is not a formal or mathematical proof.
+
 ## Recorded versus fresh
 
 - **Recorded and authentic:** the GPT-5.6 investigation, the Codex source repair, and the five-stage walkthrough that presents them. These happened once and are replayed, not re-run live.