docs: sync README to current contract + surface bench + P11 cross-ref (0.23.2)

[broomva]

Summary

Post-ship documentation audit (after BRO-1205 bench MVP + BRO-1211 Databricks live mode). The canonical surfaces were already current — SKILL.md, references/provider-standards.md, CHANGELOG, specs/bench-skill-evolution.md, and the KG research entities all document the bench/provider work. The gap was the public README.md, frozen at the P11 era.

This is a docs-only PR. No code, no behavior change.

What changed

README.md — synced to SKILL.md (the authoritative source per CLAUDE.md Self-Documenting Standards rule #3):

• "Eleven irreducible primitives" → twenty; primitive table extended P1–P11 → full P1–P20
• "28 curated skills" → 30 (intro + Stack-layers header + bootstrap description)
• Commands section was six (bootstrap/doctor/repair/status/validate/revamp); now also documents bench, wave, crystallize, metrics, skills under an "Orchestration & observability" subsection (bench links to references/provider-standards.md)
• Reasoning-enforced set corrected (P6, P9–P20) vs mechanism-enforced (P1, P2, P4, P5, P7, P8); closing narrative "eleven" → "twenty"

references/primitives.md — P11 Empirical Feedback Loop section now lists bstack bench as the dedicated P11 measurement substrate (validation-surface table row + paragraph), cross-referencing provider-standards.md + the bench spec.

CHANGELOG.md + VERSION — 0.23.1 → 0.23.2 docs patch release (matches the established docs-patch convention; 0.23.1 was itself a docs: release).

Why

bstack doctor does not lint the README, so this drift was invisible to CI — pure quality debt. The "eleven primitives" headline in a 20-primitive workspace is a rule #3 violation, and bench (BRO-1205/1211) was one of 5 commands missing from the public front door.

Companion artifact (workspace repo, not this PR)

research/entities/pattern/openai-compatible-provider-abstraction.md — P6 KG entity documenting the reusable provider-abstraction architecture BRO-1211 introduced (lint-clean).

Out of scope

Deeper skill-count reconciliation: SKILL.md says 30 curated; companion-skills.yaml lists 65 (full roster incl. optional). README follows SKILL.md per rule #1; the 30-vs-65 question is a separate audit.

Validation

• grep -niE "eleven|28 skills|six commands" README.md → clean
• bash scripts/doctor.sh --quiet → 96/97 (the 1 gap is a pre-existing compute-budget-status item, unrelated)
• No stale strings; bench/wave/crystallize/P12–P20 all present

Ticket: BRO-1376

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

• Updated documentation reflecting expanded primitive set (11→20 primitives, 28→30 skills)
• Enhanced command reference with new commands: wave, crystallize, metrics, skills, bench
• Reorganized command sections into Lifecycle and Orchestration & observability categories
• Added specification for P11 skill-evolution benchmark substrate
• Version bumped to 0.23.2

[linear]

BRO-1376

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c7d66411-f119-4026-80ad-64216b43c78c

📥 Commits

Reviewing files that changed from the base of the PR and between 80b396c and 1d1b5fb.

📒 Files selected for processing (4)

• CHANGELOG.md
• README.md
• VERSION
• references/primitives.md

---

📝 Walkthrough

Walkthrough

This PR bumps the release version to 0.23.2 and synchronizes documentation across README, CHANGELOG, and primitives reference to reflect expanded primitive scope (eleven to twenty primitives) and extended command surface with new orchestration capabilities, while explicitly documenting that no code or behavior changed.

Changes

Version 0.23.2 Documentation Synchronization

Layer / File(s)	Summary
Version bump and release notes VERSION, CHANGELOG.md	Version bumped to 0.23.2 with release notes documenting documentation-only updates: README primitive/skill count synchronization, command section reorganization with new observability commands, and P11 benchmark substrate specification.
README scope and primitives documentation README.md	Intro copy and section headers updated from eleven to twenty primitives and 28 to 30 skills; primitives table expanded with P12–P20 entries; reasoning-enforced vs mechanism-enforced narrative clarified with specific primitive subset; reference link to references/primitives.md added.
Commands reorganization and benchmark documentation README.md, references/primitives.md	README "Once installed" section reorganized into "Lifecycle" and "Orchestration & observability" subsections with new bench, wave, crystallize, metrics, and skills commands; P11 "Skill-evolution benchmark" paragraph added to references/primitives.md specifying bstack bench as the P11 measurement substrate with cold→warm runs, pluggable LLM-judge evaluation, and provider isolation gate.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

• broomva/life#1597: Documentation edits directly address README sync from eleven to twenty primitives, new commands (bench, wave, crystallize, metrics, skills), and P11 measurement substrate specification.

Possibly related PRs

• broomva/bstack#4: Both PRs modify references/primitives.md under the P11 "Empirical Feedback Loop" section; the related PR establishes the P1–P11 primitives reference, while this PR adds the bstack bench "Skill-evolution benchmark" paragraph.

Poem

🐰 Documentation blooms with twenty shining lights,
From eleven primitives to scope expanded wide,
New commands orchestrate the observability nights,
While bstack bench judges skills with methodical pride—
No code changed, but oh, how the vision rides! ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/bro-1376-readme-sync

---

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 and usage tips.}