docs(issues): add specs for shutdown SI-17, SI-23, and SI-24

[josecelano]

Related to #2448, #2449, #2450, and EPIC #1488.

Spec-only PR. No code changes; implementation starts after this merges.

Changes

• SI-17 (Migrate standalone UDP environment and example to the token lifecycle #2448): refreshed the standalone UDP environment/example spec against the current code and SI-16's lessons, converted to the issue template, and moved it to docs/issues/open/. New facts: the library catches SIGINT and SIGTERM in the legacy launcher, a failed start leaks the three listeners, the token is reused across starts, the receive-loop drain is already bounded, and the 5 s stop timeout races the 5 s drain deadline (D5 removes it). The draft verification.md is removed; manual-verification-evidence.md is created from the template at T0, as in SI-16.
• SI-23 (Migrate the REST API test environment to the token lifecycle #2449) and SI-24 (Migrate the health-check API test environment to the token lifecycle #2450): new specs for the REST API and health-check API test environments, which still stop through the legacy Halted path and had no roadmap item. SI-18 and SI-19 cannot proceed until they move.
• EPIC Overhaul: Tracker Shutdown #1488: roadmap rows 13, 15, and 16 for the three issues; SI-18 to SI-21 renumbered 17 to 20; finding 2 and the ordering rationale updated.
• SI-18 and SI-19 drafts: new roadmap positions, and SI-23 and SI-24 added to their gates and dependencies.
• Link updates in the SI-22 EPIC and the SI-3 drafts. Closed specs keep the old draft path as history.

Validation

• linter all passes; pre-commit hook passes.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 2

Open (2)

• The term “registar” is ambiguous in prose (it reads like a typo of “registrar”) and it’s not… · New
• The parenthetical opened on line 95 isn’t closed, which makes the sentence hard to parse. Close the… · New

What changed in this PR

This PR adds/updates shutdown EPIC issue specs for migrating remaining test environments (UDP standalone, REST API, and health-check API) onto token-aware server lifecycles, and updates roadmap/linking docs accordingly.

Changes:

• Added new open issue specs for SI-23 (REST API test env) and SI-24 (health-check API test env), plus refreshed SI-17 (standalone UDP env/example) under docs/issues/open/.
• Updated EPIC #1488 roadmap sequencing/notes and updated cross-links from related EPIC/draft docs.
• Removed superseded SI-17 draft spec/verification docs and repointed references to the new open SI-17 spec.

File	Description
docs/​issues/​open/​2450-1488-si-24-migrate-health-check-api-test-environment/​ISSUE.md	Adds SI-24 spec for migrating the health-check API test environment to token lifecycle.
docs/​issues/​open/​2449-1488-si-23-migrate-rest-api-test-environment/​ISSUE.md	Adds SI-23 spec for migrating the REST API test environment to token lifecycle.
docs/​issues/​open/​2448-1488-si-17-migrate-standalone-udp-environment/​ISSUE.md	Adds refreshed SI-17 spec (UDP standalone env/example) in the open-issues folder.
docs/​issues/​open/​2410-1488-si-22-process-queued-events-before-listeners-stop/​EPIC.md	Updates link to SI-17 spec and refreshes metadata timestamp.
docs/​issues/​open/​1488-overhaul-tracker-shutdown/​ISSUE.md	Updates roadmap rows/ordering rationale and references SI-17/SI-23/SI-24.
docs/​issues/​drafts/​1488-si-3-fix-environment-stop/​verification.md	Updates SI-17 link to the new open spec location.
docs/​issues/​drafts/​1488-si-3-fix-environment-stop/​ISSUE.md	Updates SI-17 link to the new open spec location and refreshes timestamp.
docs/​issues/​drafts/​1488-si-19-remove-legacy-shutdown-api/​ISSUE.md	Updates roadmap position and adds SI-23/SI-24 as explicit gates/dependencies.
docs/​issues/​drafts/​1488-si-18-deprecate-legacy-shutdown-api/​ISSUE.md	Updates roadmap position and adds SI-23/SI-24 as explicit gates/dependencies.
docs/​issues/​drafts/​1488-si-17-migrate-standalone-udp-environment/​verification.md	Removes superseded SI-17 verification doc (draft).
docs/​issues/​drafts/​1488-si-17-migrate-standalone-udp-environment/​ISSUE.md	Removes superseded SI-17 draft spec (moved/refreshed into open issues).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[da2ce7]

Reviewed at 29e1ea072f10f6aaf74682b463db27a84427755c (round 1). Recomputed from the bytes at this head, against develop at d0c97baef.

One docs-only commit over d0c97baef (11 files, +937/−246, all under docs/issues/). It refreshes the SI-17 draft and promotes it to open/2448-…, adds planned specs for the REST API and health-check API test environments (SI-23, SI-24), and renumbers the EPIC #1488 roadmap around them. It also updates links and gates in the SI-3, SI-18 and SI-19 drafts and the SI-22 EPIC.

SI-17 promotion. Every draft item carries over: scope, the five constraints (now D1–D7), the ACs (now AC1–AC9), SI-14's Ctrl-C panic (fact 1), and the drain race (fact 5). D5 changes "raise the bound" to "no outer timeout, else above the drain deadline". The deleted verification.md was an unfilled template ("Not started"). Its checks map to the T1 tests (ISSUE.md:219-225), AC2/AC8 and M2–M4, and the evidence file is created at T0 (317-318). Facts 1–7 hold: udp-server/src/testing/environment.rs:24,74,103-138,189-214, server/launcher.rs:73,97-106,362-367,520-524, health-check tests/server/contract.rs:419-425, and 11 stop() calls under udp-server/tests.

New specs. All three carry every section create-issue/SKILL.md:118-131 requires: Commit Points, M-table status/evidence, Acceptance Verification, Implementation Completion Review, checkpoints and Progress Log. Frontmatter checks out: planned, epic: 1488, own github-issue, spec-path = path, related-pr: null, stamp 11:41 = last log entry, and every artifact exists. The code claims hold:

• REST: env environment.rs:20,28,88-104,121,131,147, 58 stop() calls, 90 s drain (server.rs:53).
• Health-check: env environment.rs:13-38,54-66,104-110, 8 env.state.binding reads, 8 stop() callers, 5 s drain (server.rs:37).
• Token-aware targets: ApiServer::start_with_cancellation (server.rs:230) and server::start_with_cancellation (server.rs:138), used by src/bootstrap/jobs/tracker_apis.rs:133 and health_check_api.rs:47.

EPIC roadmap. Rows 0–20 are contiguous. Promoted rows put #N in the Draft column, as the SI-16 and SI-22 rows do. All 7 new row links resolve, and the states are right. The SI-18/SI-19 drafts say steps 17/18, matching the table. All five files gate SI-18/SI-19 on SI-23/SI-24 consistently. Widened finding 2 holds, but finding 8 now contradicts it (F1). This legacy EPIC has no Progress Log to set the 11:41 stamp against.

Hygiene. One commit, docs(issues): [#1488] add specs for SI-17, SI-23, and SI-24 (#2448, #2449, #2450). Author = committer, no body, no trailer, no manifest or non-docs/issues/ path. The PR body uses the spec-only Related to form (open-pull-request/SKILL.md:124) and has no closing keyword. The PR title has no #N (open-pull-request/SKILL.md:98), like the merged shared SI-22 spec PR; noted, not raised. The orchestrator's git merge-tree of this head against the open PRs #2444, #2445, #2447 and the loop's open PRs is clean.

Findings

• F1 [Minor, blocking]: EPIC finding 8 still says only the legacy UDP stop path observes the OS signal.
• F2 [Minor]: SI-23 and SI-24 lack four create-issue items that SI-17 carries.
• F3 [Nit]: SI-24 D1 has an unclosed parenthesis.
• F4 [Nit]: SI-24 M1's "no Started usage" collides with the Started alias.

Checked, no finding

• No new text links a deleted drafts/ path. The old SI-17 path survives only in closed specs, which the validator exempts (frontmatter-validator/src/repository.rs:131-132,152-158).
• Spec branch: values use the implementation-branch form, as closed SI-16 does.
• SI-23/SI-24 record why no signal scenario applies, which EPIC ISSUE.md:268-269 allows for test-only work.
• SI-17 proves binding release with a T1 test (ISSUE.md:221-222) plus exit 0, as SI-16 did.
• Fact 1's signal set comes from docs/analysis/20260716-shutdown-process/README.md:167-209; the crate source is outside the tree.
• The SI-3 and SI-22 link edits resolve, and review-finding:pr-2439-f2 exists (docs/pr-reviews/pr-2439-review/PR-REVIEW.md:63).

Checks

On the loop's compute hub at this head, base develop d0c97baef (receipt server-gates-krkavec-86): pre-commit profile gate exit 0 (73 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 21 errors / 4 warnings at this head, equal to develop d0c97baef re-measured in the same run (21 / 4), so the PR adds none. GitHub checks at this head at posting time: completed/success Docs Lint. Copilot's review (12:05Z, two comments on SI-24) arrived after this round's capture; its unclosed-parenthesis comment is the same point as F3. At posting, this head merges cleanly onto develop and onto every other open PR.

[da2ce7]

Reviewed at 2dab46a2feaa2d20aa314d9af326f2202d2d1a5b (round 2). Recomputed from the bytes at this head, against develop at 427b39ac8.

A pass at the previous tip was superseded by a rebase-and-record push. This head is the round-1 commit and the five fixes, rebased onto the merged #2447, plus the audit record.

Rebase. range-diff of the round-2 tip's six commits over 29ef7cb80 against this head's first six over 427b39ac8 gives six =. The #2447 delta (29ef7cb80..427b39ac8, 5 files) shares no file with this PR.

Record (docs/pr-reviews/pr-2451-review/PR-REVIEW.md, new):

• Frontmatter: semantic-links only, like the merged #2445/#2447 records; all 5 artifacts exist.
• Rows: the six rows run in source-review order (Copilot 12:05:05Z, then da2ce7 12:08:38Z; process-pr-review/SKILL.md:57-61). Copilot takes the next free ids, F5/F6.
• Severities: F1/F2 Minor and F3/F4 Nit equal the bracket tags (SKILL.md:226). Copilot's are Minor (inferred). All six categories are in the list.
• F3: its reply begins exactly "Superseded by F6: …" and it is recorded RE_RAISE_OF:F6, NO_ACTION, SUPERSEDED, with a reply URL as its reference. That is what SKILL.md:64-69,89-91,197-199 prescribe for a later duplicate, with F6 owning the fix. It is consistent; there is no finding.
• URLs and references: every Source URL matches its review, and every Reply URL is on its own thread (12:33:04–12:33:12Z). The five FIXED references equal the five fix subjects on the branch.
• Log: the 12:31/12:33/12:34 entries are in order and match the events (fixes 12:22–12:28Z, push 12:31:15Z, replies 12:33Z, record commit 12:34:35Z; "28 commits behind" recomputes). The 12:41:12Z push is owed in this round's entry.
• Validator: "0 failures" is for the orchestrator's run at posting to confirm.
• One Nit (F7, inline): the current-tree verification lines name the previous tip's id.

Carried forward. Unchanged from round 2:

• F1–F4 and Copilot's two are fixed at the bytes: EPIC finding 8 at 91-94; SI-23/SI-24's four items; SI-24:98, 226, and 66-69/119-120.
• The round-1 results stand: the SI-17 promotion, the code claims, the roadmap, and the links.

Hygiene. 7 commits, author = committer, no bodies or trailers. Paths are only under docs/issues/ and docs/pr-reviews/; no manifest and no project-words.txt change; no banned token in 1,130 added lines. The record subject docs(pr-reviews): record Copilot and da2ce7 reviews on #2451 has no [#1488] tag, as other merged record commits have none.

Threads. All six are resolved.

Findings

• F7 [Nit]: the record's current-tree verification lines cite the previous tip's id. Non-blocking.

Checks

On the loop's compute hub at this head, base develop 427b39ac8 (receipt server-gates-krkavec-93): pre-commit profile gate exit 0 (140 s), tree clean after the gate; linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 20 errors / 4 warnings at this head against 20 / 4 at develop re-measured in the same run; validate-audit-record.py --pr-number 2451 over the live review comments at this head: 6 rows, 3 log entries, 0 failures. GitHub checks at this head at posting time: queued/null Docs Lint. At posting, this head merges cleanly onto develop.

[da2ce7]

ACK 2dab46a — the six round-2 commits rebase unchanged (six =) onto 427b39a, the F1–F4 and Copilot fixes still hold, and the pr-2451 audit record was verified against the capture (rows, severities, F3 re-raise, URLs, references, log order)

[josecelano]

ACK 7c90519

[da2ce7]

The loop's round 3 at 7c9051979b751ca75aba3ff5f6e11296c4658b24 was being written when the merge landed at 14:42:06Z, so it is not posted as a review. Two things it found at that head are still true on develop at 693162bb8 and are one-line fixes; they are left here for the post-merge triage, not as a change request.

docs/issues/open/2448-1488-si-17-migrate-standalone-udp-environment/ISSUE.md line 73

[Minor][F8] The merged #2444 made SI-17's "11 stop() calls" stale: this head has 12

This line says the package's integration tests make "11 stop() calls under packages/udp-server/tests/". At this head there are 12. #2444, merged into 7970cdf0a, added should_return_only_the_first_74_torrent_stats_when_the_request_has_75_info_hashes to packages/udp-server/tests/server/contract.rs. That test starts the UDP Started environment and ends in env.stop().await, so it is one more caller this migration moves.

The design is unaffected, but the spec now states a wrong fact about the current code. Write 12, or drop the number ("every stop() call under …"), which also survives later merges.

docs/pr-reviews/pr-2451-review/PR-REVIEW.md line 163

[Minor][F9] F7's verification line says the id appears once at the PR head; it appears twice

grep -c finds the rebased-away short id in two places at this head:

• line 160, the F7 Concern itself;
• line 172, the 12:31 Processing Log entry.

So "the id appears once at the PR head, in the 12:31 log entry" (this line) does not hold at the bytes. It was true when the reply was written at 14:32:21Z, before this commit added the Concern.

The same Concern calls that commit "the round-1 tip". This record (round-1 paragraph, line 45) places round 1 at another commit; the id is the head of the 12:31 push.

process-pr-review/SKILL.md:229-231 leaves current-tree verification claims to be checked by hand, against the same standard as the validator. Either drop the id from the Concern ("the head of the 12:31 push") so "once" holds, or say "twice: here and in the 12:31 log entry".

Everything else in the round held at the bytes: the seven round-2 commits rebased onto the merged #2444 unchanged (seven =), no file overlap with the #2444 delta, the five F7 verification lines fixed, and the record's F7 row and late log entries consistent with the events. On the loop's compute hub at that head, base develop 7970cdf0a (receipt server-gates-krkavec-97): pre-commit profile gate exit 0 (79 s); linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 20 errors / 4 warnings, identical to develop re-measured at 7970cdf0a; validate-audit-record.py --pr-number 2451 over the live review comments: 7 rows, 5 log entries, 0 failures.