Add a history-tidying rule and tooling for agents

[Reefact]

Summary

This repository merges pull requests with a merge commit, so every commit a
branch carries lands in main's history — a messy branch is not squashed away
on merge. This PR makes an agent tidy a branch's history on its own initiative
before a pull request: it adds the rule to AGENTS.md (essentials inlined in
CLAUDE.md) and the Claude Code mechanics that carry it out. The rule is
advisory and the rewrite always waits for an explicit go-ahead — no agent
rewrites a branch's endpoint any more than it merges one.

Type of change

• Bug fix
• New feature
• Breaking change
• Refactoring
• Analyzer / diagnostic change
• Tests
• Documentation
• Build / CI / tooling

Changes

• AGENTS.md — new section "Tidying history before a pull request (acting
  agent)": read origin/main..HEAD before opening a PR and after pushing more
  commits to an open one; propose a cleanup when the history is messy (pending
  fixup!/squash!, non-conforming headers, wip/typo/review-fix commits, one
  change split across non-standalone commits or two folded into one); rewrite
  only while the branch is yours alone, after an explicit go-ahead, with
  git push --force-with-lease, leaving the diff against origin/main
  unchanged.
• CLAUDE.md — the same rule inlined as one essentials bullet, linking the
  AGENTS.md section and the /tidy-history command.
• .claude/commands/tidy-history.md — a /tidy-history slash command packaging
  the assess → propose → (on approval) rewrite → verify → publish procedure.
• .claude/hooks/history-hygiene.sh + .claude/settings.json — a hook that
  reuses the repository's own commit linter
  (tools/commit-lint/lint-commit-message.sh), so it never disagrees with the
  commit-msg hook or the CI gate. It blocks pull-request creation on CI-fatal
  history (fixup!/squash! placeholders, headers the lint rejects) and prints
  an advisory reminder after a committing or pushing git command. It only reads
  and reminds; it never rewrites anything.

Testing

No .NET production code is touched (only .claude/ tooling and repository docs),
so the solution build and test suite are not exercised by this change:

• dotnet build FirstClassErrors.sln — not run (no .NET code changed)
• dotnet test FirstClassErrors.sln — not run (no .NET code changed)
• Analyzer tests (FirstClassErrors.Analyzers.UnitTests) — not run (no analyzer changed)

Run instead:

• sh -n on the hook (syntax) and functional runs in a throwaway git repo — on
  a messy branch pre-pr blocks and lists the CI-fatal commits and
  post-commit reminds; on a clean branch and one even with main, both are
  silent (exit 0). The hook's pre-pr check also passes on this very branch.
• Both commits pass the repository's commit linter in CI mode
  (tools/commit-lint/lint-commit-message.sh --ci -).

Documentation

This PR is a documentation + tooling change. AGENTS.md and CLAUDE.md carry
the rule; no public API, README, doc/, or user-facing library behavior
changes, so the French translation needs no sync.

• Public API / error documentation updated — n/a
• README / doc/ updated — n/a
• French translation (doc/handwritten/for-users/README.fr.md) updated — n/a (no user-facing behavior change)
• No documentation change required — n/a (this PR is the documentation change, in AGENTS.md/CLAUDE.md)

Architecture decisions

Checked against the ADR base. This PR adds an agent/contributor process
convention and its tooling — not a public API contract, a cross-cutting code
invariant, a supported-platform floor, or a dependency/security policy — so I
judge it embarks no architectural decision. Flagging for the maintainer to
overrule if the agent-governance rule is considered ADR-worthy.

• No architectural decision in this pull request

Related issues

None — this originated from a maintainer request, not a tracked issue.

🤖 Generated with Claude Code

https://claude.ai/code/session_01197kHcdbAr9Q547gef8Cpy

---

Generated by Claude Code