<p align="center"> <img src=".github/social-preview.png" alt="Brutal Honesty Kit banner" width="820"> </p>

Brutal Honesty Kit

A drop-in package for installing the Brutal Honesty Convention in any software repo. The convention is a structural counter-measure to the same class of failure every codebase using an LLM coding assistant accumulates: scaffolds presented as features, mocks shipped to prod, docs promising behavior the code does not have, and "complete" PRs whose smoke command was never run.

The current kit ships everything needed to enforce the convention:

• the rulebook (v3.5/rulebook/)
• executable validators for PR-body structure, carried debt, drift, evidence, policy, lane consistency, and release-readiness surfaces
• a floor/ceiling smoke gate (v3.5/scripts/smoke.sh and v3.5/scripts/smoke.ps1)
• the v3.3 schema/prose/artifact drift validator, extended through the v3.5 closed-set artifact tree
• the v3.7.1 gate-skip loophole closure: L15/L16 plus R76/R77/R78/R79/R80
• a v3.7.1 Claude Code Stop-hook and /bhs-loop / /bhs-phased commands
• a CLAUDE.md portable block, CI workflow template, PR-body templates, and bundled regression tests

Current Release

v3.7.1 (2026-05-20) is the current public release.

The installable implementation still lives under v3.5/ because many scripts, templates, tests, docs, and runtime defaults intentionally contain literal v3.5/ paths. The public current-release index is v3.7.1/, which points to the compatibility implementation surface without breaking those path dependencies.

Read the current release overview at v3.7.1/README.md, the public changelog at CHANGELOG.md, and the detailed implementation history at v3.5/CHANGELOG.md.

Quickstart

For agent-assisted adoption, paste v3.7.1/ADOPT-PROMPT.md into your coding agent at the root of the target repo.

For a manual happy path:

git clone https://github.com/mattmre/Brutal-Honesty-Kit.git
cd Brutal-Honesty-Kit
python -m pip install -r v3.5/requirements.txt

Then follow v3.7.1/INSTALL.md. It gives the concise current-release path and routes implementation file copies through v3.5/.

Repo Map

Release Notes

• v3.7.1 release notes
• Root changelog
• Implementation-line changelog
• v3.7.1 changelog

Public Docs And Presentation

• Documentation index
• Version map
• Adoption quickstart
• Validator reference
• Hooks and commands
• Static presentation suite
• Browser-native slides
• Architecture
• Development guide
• Contributing
• Security
• Support

Adopting In Your Repo

The fastest path is to paste the contents of v3.7.1/ADOPT-PROMPT.md into Claude Code or another coding agent at the root of the target repo.

Manual installation is documented in v3.7.1/INSTALL.md. That file deliberately routes to the v3.5/ implementation directory and explains the path-compatibility boundary.

Versioning And Paths

Historical package cuts remain in their original directories (v3.2/, v3.3/, v3.5/). For v3.7.1, the public release version and the implementation directory name intentionally differ:

• v3.7.1/ is the current public release index.
• v3.5/ is the current installable implementation surface.

Do not rename v3.5/ as a casual release-label cleanup. It is a load-bearing path in validators, fixtures, docs, templates, output defaults, and examples. Historical notes that frame v3.7-final as terminal are superseded by v3.7.1.

What This Kit Is Not

• Not a content judge. The validators enforce structure, arithmetic, and declared artifact contracts. The operator and Tier B reviewer still judge whether evidence actually supports a production claim.
• Not a substitute for fresh-agent adversarial review. The rulebook requires a fresh reviewer to try to disprove completion. The validator enforces the declared fields; it cannot perform the review by itself.
• Not a substitute for honest cycle-wrap. The block-flag script cannot know whether a Carried Debt item has actually survived a cycle unless the operator maintains the cycle state honestly.

License

MIT.