# Lesson 07 exercise: checks a reviewer can actually rerun

**Torque & Tokens Radar · 100x Engineering curriculum.** All files here are ILLUSTRATIVE training artifacts. BRK-2210, ECR-0417, the requirements, test reports and names are invented. No CAD, CAE or PLM licence is needed: each "tool export" is a small JSON file you can open in any editor.

You need Python 3.8+ (standard library only). Or open `exercise.html` in a browser: it runs the same rules (`checker.js`) without a terminal.

## The scenario

A front radar sensor gets a larger housing. Its bracket BRK-2210 goes from rev C to rev D. Five requirements are affected: clearance to the fascia, mass, first natural frequency, shock stress and random-vibration evidence. A generator agent has already written `artifacts/agent_summary.md`: *"All five requirements are met … ready for release."*

Your job is to check whether a reviewer could rerun that claim.

## Files

- `artifacts/baseline.json`: the pinned baseline (part, revision, previous revision, CAD config, sim deck, unit system, test plan)
- `artifacts/verification_map.json`: claim → requirement → source → check or judgment → evidence artifact → named reviewer, plus the release gate
- `artifacts/*.json`: tool exports (CAD clearance and mass, modal and shock simulation, vibration test report)
- `contracts.json`: source contract, branch and join contracts, decision record rules, rework limit and release gate
- `verify.py`: the independent checker · `checker.js`: the same rules for the browser · `exercise.html`: built from both by `build_html.py`
- `fixes/`: corrected exports, an example REJECT decision and an example ACCEPT decision
- `tests/test_verify.py`: 31 regression cases; runs Python and, if Node is installed, the browser checker on the same files and compares them

## What the checker enforces

- **Source contract.** Every input is compared field by field with the pinned baseline: part, revision, CAD configuration, comparison revision, simulation deck, unit system, test plan, wherever the field applies. A matching revision on the wrong part still stops. The evidence file lists each comparison it made; nothing is stamped "baseline" without being compared.
- **Judgments stay judgments.** A test run on rev C hardware is not rejected automatically. It needs one explicit decision: `ACCEPT` or `REJECT`, by the reviewer named in that map row, with a rationale, a date, and `bound_to` the exact part, baseline revision, report and tested revision. Change the report or the baseline and the decision goes stale. A test run on rev D needs no judgment.
- **Missing or malformed inputs hold the branch** with the reason. Nothing passes silently and nothing crashes (exit code 2).
- **Map integrity.** A judgment relabelled "executable", a pre-set `approved`, a deleted or duplicated row or a blank reviewer holds the join.
- **Bounded rework.** Two failed attempts per branch, then ESCALATED to the named reviewer. Waiting for a decision doesn't count as an attempt.

**Limit, on purpose:** `decided_by` is a name typed into an editable JSON file. The checker matches it against the map; it cannot authenticate a person or a signature. Real gates take identity and signature from your PLM or e-signature records. This is a training tool, not a security control.

## Steps

1. **Run the checker as delivered.**
   `python3 verify.py`
   Expect `JOIN HELD: 3 of 5`: a stale-revision stop (clearance export is rev C), a unit-system stop (shock load case is SI) and an open engineering judgment (vibration test on rev C). Open `evidence/` and read the comparisons each branch made.
2. **Explain the shock result.** The summary quoted 0.16 MPa as a comfortable pass. Compare the unit systems in `sim_shock_loadcase.json` and `sim_shock_result.json`. Why is a result that low a warning sign, not good news?
3. **Fix the inputs, not the checker.**
   `cp fixes/cad_clearance_export.revD.json artifacts/cad_clearance_export.json`
   `cp fixes/sim_shock_loadcase.mmts.json artifacts/sim_shock_loadcase.json`
   `cp fixes/sim_shock_result.rerun.json artifacts/sim_shock_result.json`
   Rerun. Clearance now passes at 2.1 mm, close to the 2.0 mm limit; the re-run shock stress is 148.6 MPa (illustrative). Note both margins in your report.
4. **Make the judgment explicit.** Write `decisions.json` in the shape of `fixes/decisions.example.json` as the named test and validation owner, then run
   `python3 verify.py --decisions decisions.json`
   The example rejects the rev C test, so the branch stays blocked until rev D is retested. That's a correct outcome. `fixes/decisions.accept-example.json` shows a complete ACCEPT; its rationale is invented, and a real owner has to argue their own.
5. **Try to cheat.** Blank `decided_by`, put in another name, point `bound_to.report_id` at another report, change the mass export to `"part": "OTHER-999"`, relabel the vibration entry `"kind": "executable"`, or set `"approved": true`. What does the checker do? Which of these would your real change board catch, and how?
6. **Run it three times without fixing anything.** Watch `evidence/rework-attempts.json` and the ESCALATED status after the rework limit. Delete `evidence/` to start fresh.

To check the checker: `python3 -m unittest tests/test_verify.py -v`. After editing `checker.js` or the artifacts, run `python3 build_html.py` to rebuild the browser page.

## Done when

- you can name, for every claim, the exact source and its pinned fields, the check or the judgment, the evidence file and the reviewer,
- no branch passes on a stale revision, the wrong part, configuration or deck, or a unit conflict,
- every judgment has a complete, current decision by its named owner,
- the release gate is still a person's decision.

## Then measure your own baseline

Pick 5 to 10 closed change requests of this size. For each, record hands-on hours, queue time (waiting for data, people, reviews), first-pass acceptance at the review and errors found after release. Build a verification map for the same change type and run the next ones through it, with the same rubric and the same reviewers. Compare like with like. Don't count agents; count accepted changes, review loops and escaped errors.