[PMAT-254] README derived + enforced by pv contract and SHACL shape

[noahgift]

Refs #254. Operator: "fix README.md via SHACL/pv enforce it is shambolic".

What changed

• README.md rewritten (117 lines). Every version, MSRV, example, command and link in it is extracted into contracts/ruchy-readme-claims.json. The following wrong claims are removed:
  • ruchy wasm compile|run: these subcommands do not exist.
  • cargo install ruchy was presented as installing 5.x; it installs 4.2.1.
  • The hand-typed 16,102 test count.
  • An async/http example that did not run.
  • MCP described as if on by default; it needs --features mcp.
• Examples now live in examples/readme/*.ruchy, each with a .expected output file. The README fences are byte-identical to those files.
• contracts/ruchy-readme-v1.yaml: pv contract with an ONT-001 SHACL shape (closed; pattern/in/min/max) over the claims JSON. pv validate passes with 0 errors and 0 warnings. pv lint contracts --gate shapes returns Pass with 0 violations.
• src/readme_contract.rs (lib, 7 tests). This is the half that runs in sovereign-ci. It checks:
  • the claims JSON is fresh against the README;
  • version and MSRV equal Cargo's values;
  • each example matches its file and evaluates;
  • links resolve;
  • claims conform to the same YAML shape, graded in-process;
  • the README has no hand-typed counts;
  • a positive control: the shape rejects planted claims.
• tests/readme_contract.rs (binary, 3 tests) runs against the ruchy built from HEAD:
  • each example's stdout equals its .expected;
  • every Quick start line exits 0, and the compiled binary prints the expected output;
  • every Commands-table entry is listed in ruchy --help, and <cmd> --help succeeds;
  • bare ruchy starts the REPL.
• CI: a new readme-contract job. gate now needs both ci and readme-contract.
• rust-version.workspace = true on the ruchy package. Without it CARGO_PKG_RUST_VERSION was empty, so the MSRV claim had no source to check against.

Defects found (filed, not hidden)

• ruchy fmt corrupts files and ruchy compile drops loop labels / mistypes str params (found by README verification) #255: ruchy fmt produces invalid code: {x:?} becomes {x::?}, mut is dropped, and the trailing newline is dropped. ruchy compile drops loop labels and types an untyped string parameter as i32. Until ruchy fmt corrupts files and ruchy compile drops loop labels / mistypes str params (found by README verification) #255 is fixed, the README does not show fmt and shows compile only on an example that works.
• Needs an operator ruling: Cargo declares MIT OR Apache-2.0, but only MIT license files exist in the repo. The README says MIT. Cargo.toml is unchanged in this PR.

Mutation proof (restore trapped first)

10 plants (the commit message for a14f517 says 11; it is 10). Exit codes: 0 green, non-zero RED, - means that gate was not run for the plant. Script and table: docs/audits/readme-mutation-PMAT-254.{sh,txt}.

M0   baseline (no plant)                          lib=0 bin=0 pv=0
M1a  wrong MSRV number, claims NOT re-blessed     lib=101 bin=- pv=-
M1b  wrong MSRV number, claims re-blessed         lib=101 bin=- pv=0
M1c  hand-typed test count                        lib=101 bin=- pv=-
M2a  broken example path in Quick start           lib=0 bin=101 pv=-
M2b  broken example path on an Examples block     lib=101 bin=- pv=-
M3   example output drift (.expected)             lib=- bin=101 pv=-
M4   example no longer runs (README+file)         lib=101 bin=101 pv=-
M5   required section removed                     lib=101 bin=- pv=1
M6   Commands table names a missing subcommand    lib=0 bin=101 pv=0
M7   dead relative link                           lib=101 bin=- pv=0
M8   baseline after restore                       lib=0 bin=0 pv=0

The first run left M4 green on the lib gate. The cause: Interpreter::eval_string parses only the first expression. a14f517 changed the gate to parse the whole file, and M4 is now RED on both gates. M2a and M6 are caught only by the binary gate, and the gate job requires readme-contract.

Quorum

• Round 1 on d738779: claude-sonnet-5, agy gemini-3.1-pro-high and claude-haiku-4-5 all PASS (docs/audits/quorum-PMAT-254.json).
• Delta round on a14f517: 3/3 PASS.
• The author is claude-opus-5-5 and sat on neither round. Two of the three lanes are Claude-family, so the rounds are marked degraded: same-family.

🤖 Generated with Claude Code

[noahgift]

quorum-review (AD-04): three PASS — agreed (auto_merge: checked=true was_armed=false disarmed=false)

{
 "ticket": "PMAT-254",
 "head": "d7387791ad0e2c8834e37e1e0d0035bf92f103fd",
 "width": 1,
 "executor": "agy",
 "agreed": true,
 "auto_merge": {
  "checked": true,
  "was_armed": false,
  "disarmed": false,
  "note": "auto-merge not armed"
 },
 "lanes": [
  {
   "lane": 1,
   "verdict": "PASS",
   "findings": 0
  }
 ]
}

[noahgift]

Delta quorum on a14f517 (diff d738779..a14f517): claude-sonnet-5 PASS, agy gemini-3.1-pro-high PASS (model measured from the agy log), claude-haiku-4-5 PASS. Sonnet noted that the commit message says 11 plants when there are 10. That is corrected in the PR body. Author claude-opus-5-5 is excluded. Marked degraded: same-family.