docs: rules to stop the audit's failure modes recurring

[passcod]

Companion to the eight theme PRs (#137, #138, #139, #140, #141, #142, #143, #144) that close the logic bug audit. Those fix the instances; this is meant to stop the next one being written.

Why a separate PR

The rules are the durable half of this work. The 138 findings were not 138 unrelated mistakes — they were a handful of mistakes made repeatedly, in subsystems that share no code, by people who each had a locally sensible reason. Fixing the instances without writing down the pattern means the next instance lands in a file none of the eight PRs touch.

It sits on main and touches only AGENTS.md and a new doc, so it conflicts with none of the eight and can merge in any order relative to them.

What's here

docs/failure-modes.md — eight classes, grouped by the shape of the mistake rather than by subsystem, because that is how they recur. Each gives the rule, the concrete failure that motivated it, and what to check while writing or reviewing.

AGENTS.md — the short form, thirteen bullets, because that is the file actually read before every change. The doc is for when you want the worked example.

The one that matters most

Class 1, "could not determine" is not an answer, is the most repeated defect in the audit — and it kept reappearing inside the fixes for it during review of these very PRs. Four separate times: a withheld apply returning Ok(()) that the caller then read as success and used to clear a fault; a failed DB read producing an empty set that read as "teardown finished"; a failed ownership lookup treated as "not owned" by a destructive sweep; an unparseable name treated the same way.

That is the argument for writing it down. Each of those was written by someone who had just finished reading the analysis of exactly that bug class.

Honest caveat

The doc names crates/core/src/reserved.rs, defs::take, runtime::retry, file_once/sync_faults, the etc/ci/check-*.sh guards and the new spec items — all of which arrive with the theme PRs, not with this one. There's a note at the top of the doc saying so, and the link to the audit itself resolves once #115 merges. I'd rather ship the rules with forward references clearly marked than hold them until everything else lands, but if you'd prefer this merged last, that works too.

Not included

I left out rules that were really restatements of existing ones (the log-an-error/file-a-fault pairing is already in AGENTS.md), and anything that was a single bug rather than a pattern — a checklist nobody finishes reading is worse than a short one.

---

Generated by Claude Code

[github-code-quality]

Code Coverage Overview

Languages: TypeScript, Rust

TypeScript / code-coverage/vitest

The overall coverage in commit 6286480 in the claude/pr-115-theme-... branch remains at 66%, unchanged from commit c2f174b in the main branch.

Rust / code-coverage/rust

The overall coverage in commit 6286480 in the claude/pr-115-theme-... branch remains at 59%, unchanged from commit b383126 in the main branch.

---

_{Updated August 02, 2026 05:06 UTC}

[Copilot]

Pull request overview

Adds durable documentation of the recurring “logic bug audit” failure patterns and codifies them into a short checklist intended to be read before making changes in high-risk subsystems.

Changes:

• Introduces docs/failure-modes.md describing eight recurring failure classes and the rule/checklist to prevent each.
• Extends AGENTS.md with a condensed set of those rules and a pointer to read the full doc for relevant work.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
docs/failure-modes.md	New “failure modes” guide capturing recurring bug patterns and prevention rules.
AGENTS.md	Adds a short-form checklist referencing docs/failure-modes.md.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/failure-modes.md:8

• logic-bug-audit-2026-07.md is currently not present in the tree, so this creates a broken in-repo Markdown link on main until PR #115 merges. Since this doc explicitly allows forward references, consider making this a non-link path (or only linking to the PR) so readers don't hit a 404/broken link in the meantime.

These come from the July 2026 logic-bug audit
([PR](https://github.com/beyondessential/seedling/pull/115); once merged, also
[in tree](logic-bug-audit-2026-07.md)), which found
the same handful of mistakes repeated across unrelated subsystems. They are grouped by the

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/failure-modes.md:8

• docs/failure-modes.md links to logic-bug-audit-2026-07.md, but that file is not present in the tree in this PR, so the relative link will be broken until the audit PR lands (and may trip link-check tooling if added later). Consider making this a non-link path reference so it stays informative without creating a dead link.

These come from the July 2026 logic-bug audit
([PR](https://github.com/beyondessential/seedling/pull/115); once merged, also
[in tree](logic-bug-audit-2026-07.md)), which found
the same handful of mistakes repeated across unrelated subsystems. They are grouped by the