[Stelios Frantzeskakis (steliosfran)]

What changed and why

Checklist

• Tests are added or updated for the changes
• YARD docs are added or updated for the changes
• bundle exec rake passes locally (runs both the RSpec and Minitest suites)

[GH-9852] Introduce Rubyzen Rule API

[Copilot]

🟡 Changes recommended

Rule-based failure messages hide missing-block errors and negated matcher failure reasons, potentially misleading users; preserve the base message when classified details are absent and add specs for both cases.

1 open issue

• Preserve failure details when rule matcher has no classified violations · New

What changed in this PR

Introduces Rubyzen::Rule to give architectural lint failures structured descriptions, rationale, fix hints, and code examples across RSpec and Minitest.

Changes:

• Adds keyword and block-based rule construction with formatted failure messages.
• Integrates rule: into all three matchers and assertions while preserving custom-message precedence.
• Adds tests, sample usage, and documentation, and bumps the gem version to 0.4.0.

File	Description
test/​assertions/​assert_zen_true_test.rb	Tests rule messages, baselines, and message precedence.
test/​assertions/​assert_zen_false_test.rb	Tests rule messages, baselines, and message precedence.
test/​assertions/​assert_zen_empty_test.rb	Tests rule formatting, validation, and state isolation.
spec/​rule_spec.rb	Tests construction, normalization, and rendering.
spec/​matchers/​zen_true_matcher_spec.rb	Tests rule integration for zen_true.
spec/​matchers/​zen_false_matcher_spec.rb	Tests rule integration for zen_false.
spec/​matchers/​zen_empty_matcher_spec.rb	Tests rule integration and validation for zen_empty.
sample_project/​test/​controllers/​no_if_statements_in_controllers_test.rb	Adds a shared rule to Minitest examples.
sample_project/​spec/​controllers/​no_if_statements_in_controllers_lint_spec.rb	Adds a shared rule to RSpec examples.
README.md	Demonstrates structured rule explanations.
lib/​rubyzen/​version.rb	Bumps the version to 0.4.0.
lib/​rubyzen/​rule.rb	Implements rule construction and rendering.
lib/​rubyzen/​matchers/​zen_true_matcher.rb	Accepts and forwards rule explanations.
lib/​rubyzen/​matchers/​zen_false_matcher.rb	Accepts and forwards rule explanations.
lib/​rubyzen/​matchers/​zen_empty_matcher.rb	Accepts and forwards rule explanations.
lib/​rubyzen/​expectation_helpers.rb	Centralizes explanation validation and formatting.
lib/​rubyzen/​assertions/​assert_zen_true.rb	Adds the rule: option.
lib/​rubyzen/​assertions/​assert_zen_false.rb	Adds the rule: option.
lib/​rubyzen/​assertions/​assert_zen_empty.rb	Adds the rule: option.
CLAUDE.md	Documents rule architecture and usage.
CHANGELOG.md	Records the 0.4.0 additions.
.claude/​skills/​write-lint-rule/​SKILL.md	Adds guidance for explanatory rules.
.claude/​skills/​add-rubyzen-tests/​SKILL.md	Documents rule-related test coverage.

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Both predicate matchers discard the missing-block diagnostic when rule: is supplied, hiding a malformed assertion behind a misleading production-code fix hint.

1 open issue

• Preserve failure details when rule matcher has no classified violations

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues block the changes introducing structured explanations for architectural lint failures.

No open issues 🎉

1 resolved since last review

• Preserve failure details when rule matcher has no classified violations

_{Review effort: Balanced}