docs(readme): make its claims true, and pin them to the code (3.6.2)

[tmoody1973]

Ran /readme against the current codebase. The README is deliberately voiced for its audience, so this updates what today's four releases made stale rather than regenerating it. One of those updates is a real defect.

The README promised something the code did not do

"The readiness coach's script needs Python 3.9 or newer, no packages to install. It stops with a clear message on anything older."

$ grep -rn "version_info\|MIN_PYTHON\|python_requires" scripts/ skills/*/scripts/
  NONE FOUND

There was no guard. On Python 3.8 the reader gets this, from an import, before any code of ours runs:

TypeError: 'type' object is not subscriptable

That is not a message. And the audience for this toolkit is frequently on the macOS system python3, which is exactly the case the sentence was written for.

A promise in a document that the software does not keep is the same defect this toolkit exists to find. So the guard now exists rather than the sentence being deleted:

error: this script needs Python 3.9 or newer, and you are running 3.8.10.
On macOS the built-in python3 is usually older than the one you installed.
Try `python3.12` or `python3.11` in place of `python3`, or install a current
Python from python.org or with `brew install python`.

Exits 2, the code documented in 3.6.1 for "could not run". It sits above the from audit. imports, because below them it could never fire.

Four tests so this cannot drift again

Test	Catches
Guard sits above the imports	someone moving it down, silently disabling it
README's stated version == MIN_PYTHON	the doc and the code disagreeing
README's "six skills and three commands" == disk	a stale count after adding a skill
Every relative README link resolves	a dead link

The third and fourth are the general form of the bug: a number in a document that nothing checks.

Also updated

• Exit codes are in the README, with the command to gate CI on the audit. 3.6.1 put them in --help and SKILL.md, neither of which is where someone wiring a pipeline looks.
• docs/decisions is linked, and appears in the repository layout. Nine decisions have been written and nothing pointed at them.

What I deliberately did not change

The README's voice, structure, the week-with-the-toolkit narrative, the CI explainer, the waivers section, and the four rules. It is written for vibe coders, not for the generic tech-stack template, and replacing it would have been a downgrade.

Test plan

• 122 tests pass (was 118)
• ./scripts/validate-toolkit.sh green
• coverage_grid.py --fail-under 100 exits 0
• --fail-on critical on this repo, exit 0
• Script still runs on the current Python after the guard
• No em or en dashes in the README
• Version bumped in plugin.json and marketplace.json (x2), CHANGELOG entry
• CI green on this PR

[coderabbitai]

Warning

Review limit reached

@tmoody1973, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 15 minutes

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5d2084b5-2a16-4760-bd69-1274c840531e

📥 Commits

Reviewing files that changed from the base of the PR and between f594e5e and fdc7946.

📒 Files selected for processing (6)

• .claude-plugin/marketplace.json
• .claude-plugin/plugin.json
• CHANGELOG.md
• README.md
• skills/prod-readiness-coach/scripts/prod_audit.py
• skills/prod-readiness-coach/tests/test_prod_audit.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}