docs(issues): [#2454] add issue specification for #2454

[josecelano]

Related to #2454

Spec-only PR: adds the issue specification for #2454 so its scope can be reviewed before implementation starts. This PR does not close the issue.

What the spec covers

#2454 applies the EPIC #1669 Pre-publish API checklist (ADR 20261005145329, from #2435): before each crate's first crates.io publish, every public error enum with real variants is marked #[non_exhaustive], derives are limited to those every future variant can keep, and placeholders such as Result<_, Infallible> or an empty error enum are ruled out.

Inventory at develop, to be confirmed in T1: no item in the workspace uses #[non_exhaustive]; rg finds 61 public enums named *Error* across 18 crates, including the root crate; and torrust-tracker-configuration's Error has an Infallible variant, which checklist item 3 asks to evaluate.

Plan: T1 inventory (maintainer-reviewed), T2 decide how to guard the property, T3 apply the attribute crate by crate (one commit each, including the downstream wildcard arms it forces), T4 resolve placeholder and derive findings, T5 close the checklist in the EPIC.

Changes

• New spec: docs/issues/open/2454-1669-mark-public-error-enums-non-exhaustive/ISSUE.md
• EPIC Overhaul: Packages #1669: Mark public error enums #[non_exhaustive] before first publish #2454 added to the tracked items, the specs index and the Details table, and linked from the Pre-publish API checklist; the checklist lead-in now also covers later publishes of a package whose public error API changed, and new item 4 requires a semver-major bump (minor for 0.x) for a crate whose public error enum gained #[non_exhaustive] since its last publish; plus progress-log entries
• Review workflow (learned while processing this PR's reviews): .github/skills/dev/pr-reviews/process-pr-review/SKILL.md and docs/templates/PR-REVIEW-TEMPLATE.md now say that a FIXED audit row whose fix lives outside the repository tree (for example a PR or issue body edit) cites the durable URL of the PR conversation response that states it
• Review audit: docs/pr-reviews/pr-2456-review/PR-REVIEW.md

#2454 is linked as a GitHub sub-issue of #1669.

Settled in review

Manual verification is mandatory: scenario M1 (a scratch crate showing that a downstream exhaustive match is rejected, and accepted with a _ arm) must be executed and recorded. Version bumps belong to the release paths of ADR 20260629000000 (the tracker application release for the root crate, the per-package publish for the others); the spec's inventory records the required bump.

Verification

• linter markdown, linter cspell, linter lychee: pass
• Pre-commit and pre-push hooks: pass

[Copilot]

Copilot review overview

🟡 Changes recommended

The specification leaves mandatory verification, SemVer ownership, and placeholder-variant scope unresolved.

Review effort: Balanced
Findings: 3

Open (3)

• Separate placeholder variant handling from checklist item 3 · New
• Assign SemVer major bump and dependency updates to a task · New
• Make manual verification mandatory with issue-local evidence · New

What changed in this PR

Adds the spec for issue #2454 and integrates it into EPIC #1669’s pre-publish API checklist.

Changes:

• Defines the error-enum audit and implementation plan.
• Links #2454 throughout EPIC #1669.

File	Description
docs/​issues/​open/​2454-1669-mark-public-error-enums-non-exhaustive/​ISSUE.md	Adds the issue specification.
docs/​issues/​open/​1669-overhaul-packages/​EPIC.md	Registers and links the new subissue.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[da2ce7]

Reviewed at c9d515351e8e914fb5c208bc454dbd90839ff157 (round 1). Recomputed from the bytes at this head, against develop at 9be79fc5a.

The PR. One commit over 9be79fc5a, two files, +225/−1, documents only: a planned task spec for marking public error enums #[non_exhaustive] before each crate's first publish, registered in EPIC #1669 as a tracked item, a specs-index entry, a sentence under the Pre-publish API checklist and a Progress Log entry.

Spec vs create-issue and docs/templates/ISSUE.md. Every template section is present with content. Frontmatter is complete: spec-path is the file's own path, branch follows create-issue/SKILL.md:286-288 and equals the PR head ref, last-updated-utc 16:05 equals the last log entry, all five related-artifacts exist, and both skill-links resolve (frontmatter-only is allowed by docs/skills/semantic-skill-link-convention.md:180-181). Design and Ownership, Bug-Fix Process and Regression Test Strategy say Not applicable, as ISSUE.md:69/86/96 allow for non-bug work. Commit Points map T1–T5. Gaps: F1, F2, F3, F4.

Open question (manual-verification waiver). The skill has no waiver: create-issue/SKILL.md:135 makes the scenarios "Mandatory", :336 says "manual validation is required", and ISSUE.md:187 says "Manual verification is mandatory even when automated tests pass." The #2435 waiver (closed spec :180, :231) was a maintainer decision recorded during implementation, not a skill rule. M1 already meets SKILL.md:327-328 and is the real downstream use of the change, so the answer is to run it: make it unconditional and restore the template's AC line (F1).

Claims vs code and documents. No #[non_exhaustive] attribute in packages/, console/, src/, contrib/ or tests/ (only finish_non_exhaustive() at packages/udp-server/src/server/bound_socket.rs:138). ^\s*pub enum \w*Error\w*\b outside tests/ and benches/ finds 61 in packages/, console/ and src/ across 18 crates including the root: 11/10/7/6/4/3, then eight crates with two and four with one, exactly the spec's :50-52 (contrib/dev-tools adds two). Infallible is at packages/configuration/src/lib.rs:339-340, message verbatim. ADR :79-84 and EPIC :791-795 are restated faithfully; torrust-tracker-configuration 3.0.0 is published per EPIC :121; udp-server/src/event.rs:124-145 matches udp-core and tracker-core errors exhaustively, as cited. All relative links resolve.

EPIC #1669 edits. Row :668 has the form of :666 (checkbox, link, title, italic qualifier); index entry :735 resolves and matches :734; the checklist sentence at :797-798 and the log entry at :964-965 agree with the 16:05 stamp. Actor names mix "GitHub Copilot" and "Copilot" since :952; docs/templates/EPIC.md:94 has only {Role/Agent}, so no finding. The EPIC has no publish-order table or per-crate checklist to reference the issue from; the registration convention is the quick list, Details table and index, as for the SI-01 baseline issue (:666, :687, :734), and the Details row is missing (F5).

Hygiene. One commit, parent 9be79fc5a, author = committer, no trailer, no manifest change, no banned token. The subject follows open-pull-request/SKILL.md:98-103 and the merged #2447 form (#2451's commits bracketed their EPIC, #1488); the body is true to the diff. The PR body uses Related to #2454 (open-pull-request/SKILL.md:124) with no closing keyword; its Verification claims are reported, not recomputed. One slip: "18 crates plus the root crate" should be 18 crates including the root. The orchestrator's git merge-tree of this head against the loop's six open PRs is clean.

Findings (inline): F1 Major; F2, F3 and F4 Minor, each making the spec wrong, so they block with F1; F5 Minor, non-blocking; F6 Suggestion.

Checked, no finding: frontmatter fields and values; draft and open folder names (create-issue/SKILL.md:74, :260); parent line under the title (:208); workflow checkpoints against the log; Acceptance Verification rows; Risks; References; the issue body against the spec (same goal, scope and five tasks); M1's E0004 claim.

Note on ids: Copilot's review of 16:30:53Z carries its own F1–F3; the ids above are this review's and were assigned independently, so the audit record reassigns on collision as process-pr-review/SKILL.md prescribes.

Checks

On the loop's compute hub at this head, base develop 9be79fc5a (receipt server-gates-krkavec-103): pre-commit profile gate exit 0 (74 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and the same 19 / 4 at develop 9be79fc5a re-measured, so no new frontmatter finding. GitHub checks at this head at posting time: 1 completed/success. At posting, develop is 9be79fc5a, this head's base.

[da2ce7]

Reviewed at b7dc05e1d3237bd9cec57c88a8ca5faba126788d (round 2). Recomputed from the bytes at this head, against develop at 460385256.

The push. The round-1 commit rebased onto 460385256 unchanged (range-diff =), plus eight commits that fix the six round-1 findings, add the SemVer handling (AC6, EPIC checklist item 4) and log the round; develop's move touched neither file.

Round-1 findings at this head.

• F1: M1 unconditional with the positive half (:193); the waiver paragraph is the template's sentence (:188, ISSUE.md:187); the AC line equals ISSUE.md:162 (:168).
• F2: :181-184 states the toolchain rule in the #2446 form with rustc --version, naming M1's E0004 text and the pre-push runs (create-issue/SKILL.md:136).
• F3: Background :54-59 and In Scope :73-77 cite handle-errors-in-code/SKILL.md:110; Out of Scope :86-87 exempts the approved removal, so T4/AC4 no longer conflict. Infallible still occurs only at packages/configuration/src/lib.rs:340.
• F4: T3 :120 uses dependency order; per-crate completion lives in the T1 inventory (:118), linked by T5 (:122); In Scope :78, AC5 :164, AV :207 and Commit Points :132 agree.
• F5: EPIC :728 follows "UDP type consolidation" with the siblings' five columns and width, a resolving link and TODO.
• F6: T2 :119 names write-unit-test (.github/skills/dev/testing/write-unit-test/SKILL.md) and the design review before T3.

Additions. Out of Scope :88-89 matches ADR 20260629000000 :29-30 and :42 (independent versions; one crate per deployment-packages.yaml publish). Item 4 (EPIC :797-799), AC6 (:165), Risks (:212-216) and AV :208 agree, and AC6 is testable; a minor bump for 0.x is Cargo's rule that 0.x to 0.(x+1) is incompatible. Gaps: the published-crate list (F7) and item 4's lead-in (F8).

Stamps and record. Spec :12 20:31 equals its last log entry (:156), which covers each of the eight commits, at or before the last author time (20:31:31Z). EPIC :9 20:06 equals its new entry (:970) and its commit (20:06:58Z); the Details-row commit (20:30:43Z) is later, but semantic-skill-link-convention.md:150 and :161 fix only the stamp's format, so no finding. docs/pr-reviews/pr-2456-review/PR-REVIEW.md, cited by the replies and by :156, is absent at this head. process-pr-review/SKILL.md:101-102 has the audit updated progressively and committed separately, :286 validated against the committed audit, and its rows cite reply URLs that exist only after replying; nothing requires it in the fix push, so I expect it in the next push.

Hygiene. Nine commits, author = committer, author times 16:09Z–20:31Z ascending, committer times 06:02Z; Conventional subjects with [#2454], each true to its diff; no trailer, manifest change or banned token. The PR body is unchanged, so its "18 crates plus the root crate" remains (18 including the root). The live issue body (updated 2026-10-07 06:00:59Z) now says "dependency order (a crate before its dependents)" with per-crate completion in the step 1 inventory, as the F4 reply states.

Findings (inline): F7 Minor, blocking; F8 Suggestion. The maintainer's audit series (my findings as its F4–F9) is its own numbering; F7 and F8 continue mine. My six round-1 threads are fixed and may be resolved.

Checked, no finding: range-diff and overlap; frontmatter unchanged but for the stamps; relative links in the changed lines; Status values and table shapes; enum recount (61 across 18 crates).

Checks

On the loop's compute hub at this head, base develop 460385256 (receipt server-gates-krkavec-125): pre-commit profile gate exit 0 (75 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at develop 460385256 re-measured, so no new frontmatter finding. GitHub checks at this head at posting time: "1 completed/success". At posting, develop is 460385256, this head's base.

[da2ce7]

ACK ef28a96 — the F7, F8 and F9 fixes, the audit record of Copilot's review and my three rounds with the review-body rows F13 and F14 and my round-3 finding as F12, and the process-pr-review rule for out-of-tree fixes, verified on the rebase onto 30e6b71

[josecelano]

ACK 8f5115e

[da2ce7]

Reviewed at 8f5115efe71e8f5b9d5ed47d2028806812eb4b70 (round 5). Recomputed from the bytes at this head, against develop at 24bf4746a.

The push. The seventeen round-4 commits rebased onto 24bf4746a with unchanged content (seventeen =; develop's move touches none of the five files), plus 8f5115efe: the F15 row, section and log entry.

F10. The PR body's Changes section now lists the rule change (".github/skills/dev/pr-reviews/process-pr-review/SKILL.md and docs/templates/PR-REVIEW-TEMPLATE.md now say that a FIXED audit row whose fix lives outside the repository tree … cites the durable URL of the PR conversation response that states it") and "Review audit: docs/pr-reviews/pr-2456-review/PR-REVIEW.md". Fixed. Row F15 (:71, :300-315): source r4205803261 in review 5440981761, Reviewer finding ID F10, Minor as my bracket, reply r4206002378 on that thread, thread resolved; the 10:52 entry is not later than the reply (10:52:58Z) or the commit (10:53:50Z). It cites the thread reply as its resolution, which is true and durable; only the rule's wording lags (F11). Offline validator: {"status": "ok", "rows": 15, "log_entries": 15, "failures": 0}.

Hygiene. Eighteen commits, author = committer, author times ascending to 10:53:50Z, committer times 10:59:27Z to 10:59:34Z; the new subject is Conventional and true to its diff (+21); no trailer, manifest change or banned token.

Findings (inline): F11 Suggestion, non-blocking. All thirteen threads are resolved; none of mine is open.

Checked, no finding: range-diff and content; the PR body's "Settled in review" note against the spec.

Checks

On the loop's compute hub at this head, base develop 24bf4746a (receipt server-gates-krkavec-149): pre-commit profile gate exit 0 (74 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at develop 24bf4746a re-measured, so no new frontmatter finding; validate-audit-record.py --pr-number 2456 over the live review comments: 15 rows, 15 log entries, 0 failures. GitHub checks at this head at posting time: "1 check, Docs Lint completed/success". At posting, develop is 24bf4746a, this head's base.

[da2ce7]

[Suggestion][F11] Name the thread reply in the out-of-tree rule, or have F15 cite a conversation response

This rule has a FIXED row whose fix lives outside the tree cite "the durable URL of the PR conversation response that states it". The skill's own vocabulary separates a thread "reply" (step 7) from a "PR conversation response" (step 8), and the record's F15 (:313) cites the review-thread reply discussion_r4206002378. The reply is durable, states the fix and sits on the finding's own thread, so F15 is true; only the wording lags. Suggest "the durable URL of the PR conversation response or review-thread reply that states it" here and in docs/templates/PR-REVIEW-TEMPLATE.md:100-102. Non-blocking.

[da2ce7]

ACK 8f5115e — the F15 record row and the PR-body fix for my round-4 F10 verified, with the eighteen commits (spec, EPIC, record, skill rule) carried unchanged onto 24bf474

[josecelano]

ACK 8f5115e