[mforce]

Follow-up to #700 (#508), at the owner's direction after the retrospective. Documentation only — no code, no tests, no schema.

Three changes, each one a thing the slice learned that would otherwise live only in a plan document nobody reads next time:

1. AGENTS.md now names the new ordering key. The audit trail gained Sequence in #700 and the rule set said nothing about it, so the next person reasoning about audit ordering would have read AGENTS.md and missed it entirely. The new bullet states the three things most likely to be re-derived wrongly: the counter is global, not per-account (so it is never a per-farm revision number), ordering still leads with OccurredAtUtc (so a clock rollback is unhandled), and rows predating the migration have no recoverable write order.

2. AGENTS.md gains a guard lesson that cost a full implementer stop. SchemaDocsTests.PostgresImagePin_IsOneIdenticalStringAcrossEveryTrackedFile fired on a plan document, because its prose named a bare image tag while describing a probe. The document was untracked while it was written and tracked one commit later — the guard's scope changed under an artifact nobody thinks of as code. The bullet also records the resolution, which is not obvious: a guard firing on a copied document's content is a defect in the source document. Fix it there and re-copy; never edit the committed copy, and never allow-list the file, because that relaxes a pin guard to spare a comment.

3. A stale count in the #508 contract. It said "13 sibling ThenBy(x => x.Id) sites" in two places. The real number is 38 across 16 files — my original count came from a truncated grep, and the correction is noted inline so the next reader knows which number to trust.

Nothing here changes behaviour, so there is no test to add. AGENTS.md is not read by any gate.

Summary by CodeRabbit

• Documentation
  • Added guidance for maintaining global monotonic ordering of audit events, including shadow identity sequencing and known ordering limitations.
  • Added review guidance for checking tracked-file content against repository-wide safeguards before committing documentation.
  • Updated delivery-scope documentation to reflect 38 sibling paging tiebreak locations across 16 files; audit-event export remains out of scope.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: da677a0d-76de-41bf-b604-d8ac53647728

📥 Commits

Reviewing files that changed from the base of the PR and between 8fcf084 and 497e6e3.

📒 Files selected for processing (2)

• AGENTS.md
• docs/plans/508-audit-monotonic-order/00-delivery-contract.md

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds AuditEvents ordering guidance, updates the documented paging-tiebreak scope, and defines source-first handling for tracked-file guard violations.

Changes

Audit ordering documentation

Layer / File(s)	Summary
Audit ordering scope and contract AGENTS.md, docs/plans/508-audit-monotonic-order/00-delivery-contract.md	The documentation defines the Sequence shadow property for timestamp ties and updates excluded sibling paging tiebreak sites from 13 to 38 across 16 files.
Tracked-file guard guidance AGENTS.md	The guidance requires document violations to be fixed in source documents before copied versions are regenerated.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 497e6

This updates audit-ordering and documentation-maintenance guidance without changing runtime behavior, data, schemas, or public interfaces. No merge-readiness risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise, conventional, and accurately summarizes the main documentation changes. It does not mention the stale count correction, but the title need not cover every detail.
Description check	✅ Passed	The description clearly explains the purpose, scope, and three documentation changes. It is documentation-only and on-topic. It does not include the template's exact verification section, commands, or…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/508-followup-agents-md

---

_{Comment @coderabbitai help to get the list of available commands.}