[Harry-kp]

What & why

An audit for over-engineering, plus the agent instructions file the repo never had. The audit's main finding was that this repo did not need restructuring — it is a published Rails engine, so its paths are API and its depth is framework convention. Nothing moved. What it did surface was three real defects and two genuine duplicates.

bin/setup never worked from a fresh clone. It ran app:db:test:prepare, which loads test/dummy/db/schema.rb — gitignored, so nothing exists to load until something has migrated. It died with schema.rb doesn't exist yet. The clone-to-green path in CONTRIBUTING.md could not have worked; it only appeared to because anyone running it already had a schema dump on disk. It now migrates like CI does.

A stale schema.rb silently fails all 339 tests. Rails' maintain_test_schema loads that dump over your migrations, so a copy left from before the workflows→approvals rename produces UnknownAttributeError / UndefinedTable everywhere — errors that read like broken code, not a stale database. This cost the most to diagnose (first baseline run: 282 errors). Guarded in bin/setup, documented first in AGENTS.md.

CONTRIBUTING.md told contributors Ruby 3.1 while the gemspec has required >= 3.2.0 since 1.0 — anyone who believed it could not bundle install. .rubocop.yml targeted 3.1 too, suppressing 3.2 idioms.

The launch drafts claimed, in the author's name, that he had written this code at three jobs. That was invented for voice, not reported. The existing warning sat in a sibling README while the claim sat in the text you paste, and cited line numbers that had already drifted. All 8 instances are now [YOUR STORY] markers naming what each claimed; checklist.md gates on the grep returning nothing.

How

Two SSOT extractions, both verified behaviour-preserving:

• approvals_required_is_valid was three byte-identical copies across Approval, Step and TemplateStep — error string included → ConsensusValidatable.
• emit_outbox was two copies that had already drifted (Step's dropped the reason argument) → Outboxable. ApprovalBuilder.build_quarantine_approval! still writes inline: it emits on behalf of an approval from outside the model, and folding it in would mean widening a private method to public on a published gem.

Four same-name pairs were read and deliberately left alone — guard_consensus!, actor_label, target_label, current_tenant, approvable_models are each two different jobs, and merging them would have been a bug. No dead code existed; ModelExtensions is wired dynamically at engine.rb:8 and a naive grep would have called it dead.

AGENTS.md is 55 lines, with CLAUDE.md as a one-line import so there is one source of truth. Every command in it was run against this repo. Neither file ships in the gem — the gemspec uses an explicit allowlist.

Verification

Final run was from a dropped database with no schema.rb — a real clone simulation, not an incremental re-run.

	Before	After
Tests	339 runs, 1070 assertions, 0 failures	identical
Rubocop	82 files clean	84 files clean, at a stricter TargetRubyVersion
gem build	1.1.0 OK	1.1.0 OK
bin/setup from fresh clone	broken	works

Coverage measured at 96.5% line / 81.8% branch.

Checklist

• Tests added/updated (bin/rails app:test is green)
• bundle exec rubocop is clean
• CHANGELOG.md updated under "Unreleased"
• Docs/README/cookbook updated if behavior changed — no behaviour changed; CONTRIBUTING and the launch docs corrected

Note for the author

docs/launch/posts.md now has 8 [YOUR STORY] slots waiting on you. The Short Ruby blurb is flagged hardest — it is third person and goes to an editor who may print it as sent. Where a neutral true alternative existed (the r/rails title) it is offered inline.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.