docs(design): define current failure supersession

[munezaclovis]

What changed

• Define current failures as unresolved episodes for typed diagnostic subjects.
• Keep daemon jobs immutable as historical records for pv jobs.
• Require successful recorded work coverage, or a matching newer healthy observation, before a failure is superseded.
• Specify the real coverage of system, Project, Gateway, backing-resource, and update jobs.
• Prevent no-op update system jobs from hiding reconciliation or runtime failures.
• Define recurrence after repair as a new current failure.
• Require focused repair advice based on the failed subject and condition.

Why

Aggregate status currently treats retained failed jobs as permanently current. A scope-only replacement rule would also be unsafe: Project reconciliation really covers the global Gateway, while a no-op update performs no reconciliation at all.

The contract makes actual verified coverage authoritative while preserving complete job history.

Checks

• git diff --check
• Documentation-only change; no runtime behavior changed, so tests were not run.

Refs #307

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3edae6bd-2dc5-4fa7-b898-94a962511a20

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 7 untouched benchmarks

---

_{Comparing agent/design-current-failure-semantics (6192479) with main (058373c)}