[josecelano-bot]

Specification-only pull request for #2801 (SI-19, roadmap row 19 of EPIC #1488). Related to #2801. It contains no implementation.

Summary

• Opens SI-19 as issue Remove legacy shutdown API and library OS signals #2801: the breaking removal of what SI-18 (Deprecate legacy shutdown API #2751) deprecated, namely the Halted-based shutdown API, the legacy start/stop entry points, the root HaltSignal and NestedServerTask, and library-level OS-signal subscriptions. The Started API stays.
• Refreshes the draft after SI-18 closed: the start gate carries evidence for each item, checked against develop at 1df1ecdf0.
• Records the maintainer's approval (chat, 2026-11-10) that ends the torrust-server-lib 0.5.x window, with 0.6.0 as the library removal release and 4.0.0 as the root release target.
• Records that the last gate item is met: torrust-server-lib 0.6.0 is published (Remove the legacy shutdown API deprecated in 0.5.0 and release 0.6.0 torrust-server-lib#5, PR feat(signals)!: remove legacy shutdown API and release 0.6.0 torrust-server-lib#6, max_version 0.6.0 on crates.io). It is an external dependency this task waits for. The bump lands with the removals in T4, because 0.6.0 removes Halted and an earlier bump would not build.
• Splits the supervisor consolidation out of scope (a refactor, and Removal Constraint 1 forbids widening the breaking surface).
• Adds the template sections (architectural decisions, design and ownership review, implementation plan T1 to T6, commit points, progress tracking, verification plan, acceptance verification, risks, completion review, references) and renames verification.md to manual-verification-evidence.md.
• Adds the review audit record docs/pr-reviews/pr-2803-review/PR-REVIEW.md.

Files touched

• docs/issues/open/2801-1488-si-19-remove-legacy-shutdown-api/ (moved from docs/issues/drafts/1488-si-19-remove-legacy-shutdown-api/): ISSUE.md and manual-verification-evidence.md.
• docs/issues/open/1488-overhaul-tracker-shutdown/ISSUE.md: roadmap row 19 now links the open spec.
• The closed SI-23 and SI-24 specs: related-artifact paths updated to the new location.
• docs/pr-reviews/pr-2803-review/PR-REVIEW.md: the audit of the reviews of this pull request.

Validation

• linter markdown, linter cspell and the pre-commit hooks (including the frontmatter validator) pass; the diff contains only Markdown files.

🤖 Generated with Claude Code

[da2ce7]

Reviewed at 2da190d1aab1b94631443f6e206c6d74f66001a3. Recomputed from the bytes at this head, against the merge base 1df1ecdf0; git merge-tree against develop 1df1ecdf0 writes a tree identical to the head tree, with no conflicts.

Process: a spec-only PR, governed by the create-issue and open-pull-request skills. The draft moved to open/ under both issue numbers; spec-path, branch (the head branch), status: planned, the skill link and every related artifact satisfy the frontmatter validator's rules as read; the description says Related to #2801, and no closing keyword appears in the title, description or commit messages; the PR-branch commit-id check prints nothing.

The change against its claim: the description matches the diff (draft moved, evidence file renamed, EPIC row 19 linked, SI-23 and SI-24 artifact paths updated). The gate evidence recomputes: the merges of #2752, #2793 and #2797 are on develop; #1588, SI-16, SI-17, SI-23 and SI-24 are closed specs; the four bootstrap jobs call start_with_cancellation; every Halted use carries a reasoned #[allow(deprecated)]; the workspace pins torrust-server-lib 0.5.0; docs/containers.md has the cited heading; both ADRs and the migration guide exist.

Consistency: no live reference to the old draft path remains (three hits are immutable review records); the EPIC link resolves. Hygiene: both commits are Conventional docs(issues), the second with [#2801]; their bodies hold one attribution footer each, which no rule in the tree forbids; author equals committer; git diff --check is clean.

Findings: F1 to F6 Minor, F7 Nit, none blocking: the scope list called SI-18's is incomplete; the T1 commit point bumps what T4 bumps; publishing 0.6.0 is both part of the task and out of scope; the 14:00 UTC stamps postdate the commits; the verification plan, acceptance verification and completion review sections are missing; the evidence file still asks for a window end date; one gate item cites a session label.

Checked, no finding: legacy_stop_requested and halt_requested are private helpers of deprecated paths, so removing them does not widen the breaking surface; the parent EPIC is named as in the SI-18 spec; the words the change adds already occur in the tree's Markdown.

Checks

On the loop's compute node at this head, against the merge base 1df1ecdf0 (receipt server-gates-kranich-588): the repository's pre-commit gate exit 0 (62 s), clippy-allow-reasons against the base exit 0, and the tree left clean; linter markdown, linter cspell, linter lychee (offline links) exit 0; frontmatter-validator --all showed no new error against the base. Context for T1: torrust-server-lib 0.6.0 (its PR 6, merged today) removes Halted, and the tracker at develop 1df1ecdf0 with its requirements raised to 0.6.0 stops at torrust-tracker-axum-server on the unresolved signals::Halted and signals::shutdown_signal_with_message, measured on the same node. The forge reports this head as mergeable. GitHub checks at this head at posting time: "Docs Lint: completed/success". At posting, develop is 1df1ecdf0.

[da2ce7]

ACK 2da190d — the SI-19 spec move, its start-gate evidence, paths, links and frontmatter were recomputed at this head with only Minor and Nit findings

[Copilot]

🟡 Changes recommended

The plan places the dependency bump before legacy consumer removals, creating an unbuildable intermediate commit, and omits the required implementation-discovery review and retrospective decision before closure.

2 open issues

• Defer the dependency bump until consumer removals are complete · New
• Require an implementation-completion review before closing · New

What changed in this PR

This documentation-only PR promotes SI-19 to issue #2801 within the shutdown overhaul (#1488). It plans removal of the legacy shutdown API after SI-18’s deprecation, while preserving token-based shutdown and the Started API.

Changes:

• Records release gates, including the pending torrust-server-lib 0.6.0 publication.
• Adds implementation tasks, commit points, and verification requirements; excludes supervisor consolidation.
• Moves the specification into open issues and updates related references.

File	Description
docs/​issues/​open/​2801-1488-si-19-remove-legacy-shutdown-api/​manual-verification-evidence.md	Carries forward the evidence placeholder with normalized punctuation.
docs/​issues/​open/​2801-1488-si-19-remove-legacy-shutdown-api/​ISSUE.md	Defines removal scope, release gates, implementation tasks, and verification.
docs/​issues/​open/​1488-overhaul-tracker-shutdown/​ISSUE.md	Links roadmap row 19 to #2801 and marks it planned.
docs/​issues/​drafts/​1488-si-19-remove-legacy-shutdown-api/​ISSUE.md	Removes the draft superseded by the open specification.
docs/​issues/​closed/​2450-1488-si-24-migrate-health-check-api-test-environment/​ISSUE.md	Updates the related-artifact path to the open specification.
docs/​issues/​closed/​2449-1488-si-23-migrate-rest-api-test-environment/​ISSUE.md	Updates the related-artifact path to the open specification.

_{Review effort: Balanced}

[da2ce7]

Reviewed at d8436d5fe5c3ba0a26918b18c06e81327845acee. Recomputed from the bytes at this head, against the previous round's head 2da190d1a and the merge base 1df1ecdf0; git merge-tree against develop af8d84d25 writes a tree with no conflicts, in which the PR's files are byte-identical to this head.

What moved: 4026002d7 and d8436d5fe fast-forward 2da190d1a and touch only the spec and its evidence file; the other 2445 paths are byte-identical, so the previous round's conclusions on them stand.

Previous findings:

• F1 fixed: T2 to T4 name all 27 shutdown-related #[deprecated] items.
• F2 fixed: T1 is wait-only with no commit; the bump is in T4.
• F3 fixed within the spec (see F11).
• F4 partly fixed (inline).
• F5 fixed: the four missing sections are present.
• F6 fixed: no end date; SI-23 and SI-24 linked.
• F7 fixed: the item cites the companion issue and PR.

The new commits: global_shutdown_signal is used only in udp-server (launcher.rs:19, :520); SI-18's three PRs, SI-23 and SI-24, both templates, Q3 to Q5, the containers anchor and the EPIC protocol resolve. The upstream merge id and the registry's 0.6.0 are external and not checkable offline. The commit-id check prints nothing.

Hygiene: Conventional docs(issues) subjects with [#2801]; each body is one attribution footer, which no rule in the tree forbids; author equals committer; git diff --check is clean.

Findings: F8 to F11 Minor, F12 Nit, F4's residue Minor; none blocks on its own. No audit record; replies cite branch commit ids; the description still calls 0.6.0 an open gate item; "not part of this task" departs from SI-18; SI-18's list is not the complete list. The verdict is COMMENT because the audit validator cannot pass at this head without the record (F8).

Checked, no finding: Not applicable in the Design and Ownership Review is allowed by the template; the bump-order note matches the plan; nothing is renamed.

Checks

On the loop's compute node at this head, against the merge base 1df1ecdf0 (receipt server-gates-kranich-592): the repository's pre-commit gate exit 0 (37 s), clippy-allow-reasons against the base exit 0, and the tree left clean; linter markdown, linter cspell, linter lychee (offline links) exit 0; frontmatter-validator --all showed no new error against the base. No review audit record exists at this head (docs/pr-reviews/pr-2803-review/PR-REVIEW.md), so this round is a COMMENT with no ACK until it lands. The forge reports this head as mergeable. GitHub checks at this head at posting time: "Docs Lint: completed/success". At posting, develop is af8d84d25.

[josecelano-bot]

Second review round (da2ce7 review 5842998748, findings F8 to F12 and the residue of F4, recorded as F13) processed. F9: the nine earlier replies were edited to cite commit subjects instead of branch commit ids, and the replies of this round cite subjects. F10: the PR description was edited to say that 0.6.0 is published and an external dependency, that the bump lands in T4, and to list all the added sections and the audit record. The other findings are fixed in the commit "docs(issues): [#2801] reconcile the SI-19 spec with the second review" and the audit record in "docs(pr-reviews): [#2803] add the review audit record", each with a reply on its thread.

[da2ce7]

Reviewed at fbef08dd2abe09f2822c8fa29e144d327ee2f34c. Recomputed from the bytes at this head, against the previous round's head d8436d5fe and the merge base 1df1ecdf0; git merge-tree against develop af8d84d25 writes a tree with no conflicts, in which the PR's paths are byte-identical to this head and develop's own changes (docs only) touch none of them.

What moved: 4b90bc82a and fbef08dd2 fast-forward d8436d5fe, editing the spec and adding the audit record; the other 2446 paths are byte-identical.

Previous findings:

• F3 fixed: with F11, the spec gives one account of 0.6.0.
• F8 fixed: the audit exists, and the validator's logic, run offline on the captured comments, passes.
• F9 fixed: the nine replies cite subjects (but see F13).
• F10 fixed: the description states the met gate, the T4 bump and every added section.
• F11 fixed: the gate item and Out of scope match SI-18's Versioning Decisions (ISSUE.md:122-124 there).
• F12 fixed: of 36 #[deprecated] attributes in Rust files, 9 are EPIC #1669 re-exports and 27 are shutdown-related, the same at af8d84d25.

The new commits: the private HTTP Launcher::start carries only #[allow(deprecated)] (axum-http-server/src/server.rs:168-173) while the REST one is deprecated (axum-rest-api-server/src/server.rs:527); the audit's rows, review ids, reply threads, severities and subjects match the capture, and its fixed sections match the template. The commit-id check prints one id (F13).

Hygiene: Conventional subjects; each body is one attribution footer, which no rule in the tree forbids; author equals committer; git diff --check is clean.

Findings: F4's residue, F13 and F14 Minor; F15 and F16 Nit; none blocks.

Checked, no finding: the 13:06 entry follows 13:30 because the template appends (docs/templates/ISSUE.md:152); [#2803] names the PR where sibling audit commits name the issue, which no rule fixes; nothing is renamed.

Checks

On the loop's compute node at this head, against the merge base 1df1ecdf0 (receipt server-gates-kranich-597): the repository's pre-commit gate exit 0, clippy-allow-reasons against the base exit 0, and the tree left clean; linter markdown, linter cspell, linter lychee (offline links) exit 0; frontmatter-validator --all showed no new error against the base; the repository's audit validator on pr-2803-review exit 0 (15 rows, 4 log entries, no failures). The forge reports this head as mergeable. GitHub checks at this head at posting time: "". At posting, develop is af8d84d25.

[da2ce7]

ACK fbef08d — the SI-19 spec's reconciled 0.6.0 wording, its 27-attribute removal list and the new review audit record were recomputed at this head, with the audit validator's logic passing offline and only Minor and Nit findings standing

[da2ce7]

Reviewed at f46af575f7ac3fc946d31b8a213d78c800efb85d. Recomputed from the bytes at this head, against the previous round's head fbef08dd2 and the merge base 1df1ecdf0; git merge-tree against develop af8d84d25 writes a tree with no conflicts, in which the PR's paths are byte-identical to this head and develop's own changes (19 Markdown files) touch none of them.

What moved: 21fd02188 and f46af575f fast-forward fbef08dd2, editing the spec (+5/-4) and the audit (+76/-5); the other 2446 paths are byte-identical.

Previous findings (the other eleven stand, their bytes unchanged):

• F4 fixed: last-updated-utc and the new entry read 14:25, the time of 21fd02188, the last commit to touch the spec; the second-round entry reads 13:59, 4b90bc82a's time.
• F13 fixed: the open-pull-request commit-id check, run verbatim, prints nothing.
• F14 fixed: the round 1 entry reads 13:37, when the last reply was posted (13:37:27).
• F15 fixed: ISSUE.md:108-109 names the HTTP and REST Running structs, as SI-18's list warrants (:177-183 there).
• F16 fixed: both commands print ### Acceptance Verification (:275), the checkpoint (:224) and the heading (:298).

The new commits: rows F14 to F18 match the round's five comments in review, thread, severity and subject; the validator's logic, run offline on the captured comments, passes (20 rows, 5 log entries); the new entry's times match the forge (14:23:15, 14:25:40 to 14:25:50).

Hygiene: Conventional subjects; 21fd02188 has no body and f46af575f's body is one attribution footer, which no rule in the tree forbids; author equals committer; git diff --check is clean.

Findings: F17 and F18 Nit; none blocks.

Checked, no finding: three replies (14:25:42 to 14:25:50) name the audit commit authored 14:26:16, true at this head as with the earlier F8 reply; the 14:26 entry takes that commit's author time (committed 14:27:56); the approval was dismissed on push (14:30:18, no message); nothing is renamed.

Checks

On the loop's compute node at this head, against the merge base 1df1ecdf0 (receipt server-gates-kranich-600): the repository's pre-commit gate exit 0 (39 s), clippy-allow-reasons against the base exit 0, and the tree left clean; linter markdown, linter cspell, linter lychee (offline links) exit 0; frontmatter-validator --all showed no new error against the base; the repository's audit validator on pr-2803-review exit 0 (20 rows, 5 log entries, no failures). The forge reports this head as mergeable. GitHub checks at this head at posting time: "". At posting, develop is af8d84d25.

[da2ce7]

ACK f46af57 — the SI-19 spec's corrected stamps and Running wording and the audit's five new rows were recomputed at this head, with the commit-id check printing nothing, the audit validator's logic passing offline and only Nit findings standing

[da2ce7]

Reviewed at db644e5532289d71cd8401381c34b52886cdc680. Recomputed from the bytes at this head, against the previous round's head f46af575f and the merge base 1df1ecdf0; git merge-tree against develop af8d84d25 writes a tree with no conflicts, in which the PR's paths are byte-identical to this head and develop's own changes (19 Markdown files) touch none of them.

What moved: db644e553 fast-forwards f46af575f and edits only the audit (+31/-2); the other 2447 paths are byte-identical.

Previous findings (the other sixteen stand, their bytes unchanged):

• F17 fixed: PR-REVIEW.md:289 names only the open-pull-request commit-id check, which, run verbatim, prints nothing; no nine-hex grep remains.
• F18 fixed: :44 says the third round reused F4 and F13, which became F14 and F15, so its F14 to F16 became F16 to F18.

The new commit: rows F19 and F20 match the round's two comments in review, thread, severity and reviewer ID, in source order, and each reply answers its own thread; the validator's logic, run offline on the captured comments, passes (22 rows, 6 log entries); every backticked verification command in the audit prints what its row says. The new log entry's stamp is F19 below.

Hygiene: Conventional subject; the body is one attribution footer, which no rule in the tree forbids; author equals committer; git diff --check is clean.

Findings: F19 Minor; none blocks.

Checked, no finding: the fourth-round sentence (F18 then F17 became F19 and F20) follows source order; the two replies (14:47:28, 14:47:30) name the commit authored at 14:47:54, true at this head as in the previous round; the approval was dismissed on push (14:51:18, no message); nothing is renamed.

Checks

On the loop's compute node at this head, against the merge base 1df1ecdf0 (receipt server-gates-kranich-602): the repository's pre-commit gate exit 0 (112 s), clippy-allow-reasons against the base exit 0, and the tree left clean; linter markdown, linter cspell, linter lychee (offline links) exit 0; frontmatter-validator --all showed no new error against the base; the repository's audit validator on pr-2803-review exit 0 (22 rows, 6 log entries, no failures). The forge reports this head as mergeable. GitHub checks at this head at posting time: "". At posting, develop is af8d84d25.

[da2ce7]

ACK db644e5 — the one new audit commit fast-forwards f46af57 and closes F17 and F18, its rows and replies match the captured forge data, the audit validator's logic and the verbatim commit-id check pass at this head, and the merge into develop af8d84d is conflict-free

[josecelano]

ACK 752fc2e

[da2ce7]

Reviewed at 752fc2e9fa9eaa1f6366dc13f2bb18a16b03a53a. Recomputed from the bytes at this head, against the previous round's head db644e553 and the merge base 1df1ecdf0; git merge-tree against develop af8d84d25 writes a tree with no conflicts, in which the PR's six present paths are byte-identical to this head, the moved draft is absent, and develop's own changes (19 Markdown files) touch none of the PR's paths.

What moved: 752fc2e9f fast-forwards db644e553 and edits only the audit (+17/-2); the other 2447 paths are byte-identical.

Previous findings (F1 to F18 stand fixed, their bytes unchanged):

• F19 fixed: PR-REVIEW.md:380 stamps the round-4 entry 14:47, no earlier than its replies (14:47:28, 14:47:30) and no later than its commit (14:47:54).

The new commit: row F21 and its details match the round's one comment in review, thread, severity, reviewer ID and heading, and the reply answers its own thread; :44 gives the colliding F19 the next free ID (process-pr-review/SKILL.md:60-64); the validator's logic, run offline on the captured comments, passes (23 rows, 7 log entries); the verbatim open-pull-request commit-id check prints nothing. The round-5 entry's stamp, 15:06, lies between the reply (15:06:16) and the commit (15:06:31); its approval time is F20 below.

Hygiene: Conventional subject that matches the diff; the body is one attribution footer, which no rule in the tree forbids; author equals committer (15:06:31); git diff --check is clean.

Findings: F20 Nit; none blocks.

Checked, no finding: the reply names the fix commit's subject 15 s before that commit, true at this head, as in earlier rounds; the approval was dismissed on push (15:09:52, no message); every backticked verification command in the audit prints what its row says; nothing is renamed, and the only links added are discussion URLs present in the capture.

Checks

On the loop's compute node at this head, against the merge base 1df1ecdf0 (receipt server-gates-kranich-604): the repository's pre-commit gate exit 0 (57 s), clippy-allow-reasons against the base exit 0, and the tree left clean; linter markdown, linter cspell, linter lychee (offline links) exit 0; frontmatter-validator --all showed no new error against the base; the repository's audit validator on pr-2803-review exit 0 (23 rows, 7 log entries, no failures). The forge reports this head as mergeable. GitHub checks at this head at posting time: "Docs Lint: in_progress/pending". At posting, develop is af8d84d25.

[da2ce7]

[Nit][F20] The approval is 15:04:09, not 15:04:08.

The forge records review 5844068957's submission, and the timeline's reviewed event, at 15:04:09 UTC; 15:04:08 is the creation time of its one inline comment. The round-3 entry (line 379) takes its approval time from the review's submission (14:23:15, while that review's comments were created at 14:23:14). "approval at 15:04:09 UTC" closes it.

[da2ce7]

ACK 752fc2e — the one new audit commit fast-forwards db644e5 and closes F19, its F21 row, details, reply and log stamps match the captured forge data, the audit validator's logic and the verbatim commit-id check pass at this head, and the merge into develop af8d84d is conflict-free