docs(issues): [#2446] establish the workspace baseline analysis

[josecelano]

Summary

Implements #2446 (SI-01 of EPIC #1669): refreshes the workspace baseline analysis for the post-#1938 workspace and records its findings as draft subissues. Documentation only.

Closes #2446

Changes

• T9, coupling report: new docs/issues/open/1669-overhaul-packages/workspace-coupling-report-2026-10-06.md, generated by cargo run -p workspace-coupling, covering all 31 workspace members. Its Observations compare against the 2026-06-10 report (the June prioritization items are all resolved) and record three findings.
• T10, README audit: readme-audit.md now has exactly the 25 audited tracker packages (root crate, console/tracker-client, 23 packages/*): seven stale rows removed, six added, names updated, a missing rating added, and the Summary corrected (4 good, 12 minimal, 9 stub).
• T11, dependency diagram: docs/media/packages/dependencies-workspace-packages.md regenerated from cargo metadata (153 normal torrust* edges): rest-api-core removed, the three REST API packages added, torrust-server-lib shown as external.
• T12, draft subissues (approved by the maintainer, listed in the EPIC; GitHub issues to be created when each is picked up):
  • docs/issues/drafts/1669-decouple-test-helpers-from-unpublished-crates/: published test-helpers now depends on unpublished client-lib and the protocol crates.
  • docs/issues/drafts/1669-gate-server-testing-modules-behind-feature/: the servers' public testing modules turn test-only edges into runtime dependencies (DEC-13 follow-up).
  • docs/issues/drafts/1669-coupling-tool-resolve-lib-names-and-renames/: the tool misses renamed dependencies and custom library names (four false "no references" edges).
• T13, EPIC Overhaul: Packages #1669: SI-01 marked done, AC1 ticked, first-cycle status recorded.
• Spec docs/issues/open/2446-1669-establish-baseline-analysis/ISSUE.md: tasks, acceptance criteria and verification completed; no retrospective needed (reason in the progress log).

Validation

• Manual verification MV1 to MV4 recorded in manual-verification-evidence.md (rerun on the rebased head): report package set equals cargo metadata; regeneration differs only in the timestamp; the diagram's 153 edges equal cargo metadata; one correct README audit row per audited package.
• Mermaid diagram syntax validated.
• Pre-commit (including linter all) passed on every commit; pre-push passed.
• After rebasing onto develop, the report was regenerated in its own commit: a few import paths changed in six edges, no dependency edge changed.

[Copilot]

Copilot review overview

🟡 Changes recommended

Verification evidence is incomplete, and several draft specifications contain contradictory or unmet completion requirements.

Review effort: Balanced
Findings: 4 · 4

Open (8)

• Follow the required bug reproduction and recheck workflow · New
• Require actual test-helpers decoupling and publishability · New
• Align optional dependency handling with report classification · New
• Add reproducible MV3 metadata comparison evidence · New
• Use a stable issue reference instead of the open-spec path · New
• Correct the off-by-one dependency comparison · New
• Clarify AC1 to match its evidence scope · New
• Correct architecture diagram layer classifications · New

What changed in this PR

Refreshes EPIC #1669’s workspace baseline analysis and records follow-up work.

Changes:

• Regenerates dependency, coupling, and README analyses.
• Marks baseline tasks complete with verification evidence.
• Adds three draft follow-up issue specifications.

File	Description
docs/​media/​packages/​dependencies-workspace-packages.md	Refreshes the dependency diagram.
docs/​issues/​open/​2446-1669-establish-baseline-analysis/​manual-verification-evidence.md	Records baseline validation.
docs/​issues/​open/​2446-1669-establish-baseline-analysis/​ISSUE.md	Marks implementation and criteria complete.
docs/​issues/​open/​1669-overhaul-packages/​workspace-coupling-report-2026-10-06.md	Adds the current coupling report.
docs/​issues/​open/​1669-overhaul-packages/​readme-audit.md	Updates the package README audit.
docs/​issues/​open/​1669-overhaul-packages/​EPIC.md	Records baseline completion and follow-ups.
docs/​issues/​drafts/​1669-gate-server-testing-modules-behind-feature/​ISSUE.md	Drafts testing-feature work.
docs/​issues/​drafts/​1669-decouple-test-helpers-from-unpublished-crates/​ISSUE.md	Drafts test-helper decoupling work.
docs/​issues/​drafts/​1669-coupling-tool-resolve-lib-names-and-renames/​ISSUE.md	Drafts coupling-tool corrections.

---

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

[da2ce7]

Reviewed at 211c49f1bdf5a54062fc06d44b72ebaed296326f (round 1). Recomputed from the bytes at this head, against its base 3efbc28ce; develop is 604b26c6c and the merge is clean.

This PR implements SI-01 of EPIC #1669 for issue #2446. It adds a 2026-10-06 coupling report with Observations, refreshes the README audit, regenerates the dependency diagram, drafts three subissues, marks the baseline done in the EPIC, and completes the spec and its evidence. It is documents only (9 files, +2280/−178, 12 commits). The two later develop merges touch none of its files, and a git merge-tree of this head against develop and against six other open PRs is clean.

Spec transition. status: in-progress under open/ matches cleanup-completed-issues (done is set at archive, :179-183) and how recent implementation merges left their specs. related-pr: null breaks no rule. The 16:25 stamp equals the last log entry, and the last two commits do not touch the spec. Not needed with a logged reason is what docs/templates/ISSUE.md:239-240 and create-issue:141-143 allow. The spec-only PR merged at 12:31Z, before the first commit at 12:56Z. Every AV link resolves.

Coupling report. The manifests give 31 members. The report covers exactly those (11 leaves + 20 sections), and its 92 [normal] workspace edges equal the manifests' 92. The comparison table, the June deltas, the resolved June items and the thin-edge list hold, except F5 and F8.

Diagram. The manifests give 153 torrust* normal edges (92 internal, 61 external). The diagram draws all 153, none missing, plus server-lib --> net-prim (F9). Its layering contradicts the architecture docs (F6).

README audit. There are 25 rows: the root crate, console/tracker-client and the 23 packages/*. Crate names equal [package].name, line counts equal wc -l, and 4/12/9/0 matches the rows. The seven removed and six added rows match the base table.

Evidence file. The toolchain is recorded and MV2 and MV4 reproduce. MV3 does not (F1). The rebased-head rerun is recorded, and the regular-expression surprise is at :207-209.

Drafts. The code claims hold: the publication state at EPIC.md:121; the testing-only imports; main.rs:124-126 deriving the module from the package name. The plans do not: F2, F3, F4 and F7.

EPIC. The done row, the draft rows, the #TBD Details rows and the spec-index links follow the existing forms and resolve. The 16:21 stamp equals its log entry, AC1's three links resolve, and the first-cycle exit criteria get a Status line.

Hygiene. All twelve commits have Conventional subjects with [#2446], author = committer, ascending author times and no trailers. None changes a manifest or project-words.txt. Each body matches its diff: the post-rebase regeneration changes import lists in six edges and no dependency heading. docs(packages) fits commit-changes:41, and Closes #2446 is right for an implementation PR (open-pull-request:125,151).

Findings

Blocking: F1, F2, F3, F4 (Major); F5, F6 (Minor). Non-blocking: F7 (Minor); F8, F9, F10 (Nit); F11 (Suggestion).

Checked, no finding

• The frontmatter stamps of the spec (16:25), EPIC (16:21), evidence file (16:47) and drafts (16:01) each equal their last log entry or run time.
• The report table (25→31, 24→25, 1→6, 7→11, 15→16) holds, and so does the six-package torrust-server-lib drop.
• The thin edges carry one import each, as stated, and deny.toml:52-57 allows the adapter → udp-server edge.
• The audit's 14 links to the root crate's docs.rs page and its three wrong titles hold.
• test-helpers' helpers are used only through tests/common/mod.rs:31-34; DEC-13's release-build note is at DECISIONS.md:314.
• All 110 relative links in the changed files resolve, 39 of them new, anchors included.

On Copilot's findings

• F1: holds in part. The generated lines say 13→14; 12→13 is the distinct-crate count. Nit (F8).
• F2: holds. The expected list is never printed, so identical cannot be derived (template :12-13, :54, :60). Major (F1).
• F3: holds. Options 2 and 3 cannot meet the Goal (:33-35), and AC2/AC4 still close. Major (F3).
• F4: holds. main.rs:62-66,128-134 classifies by kind only, and src/testing/ imports cannot be dev-dependencies. Major (F2).
• F5: holds and binds the draft now: fix-bug:130-131 says "while drafting the spec, before asking the maintainer to review it". Major (F4).
• F6: holds as a preference ("prefer", convention :188-191), and the archive skill's Step 4 repairs live references. Suggestion (F11).
• F7: holds (packages/AGENTS.md:19-20, docs/packages.md:85-88). Minor (F6).
• F8: holds literally, but the AV row and the 16:25 log entry state the qualification. Nit (F10).

Checks

On the loop's compute hub at this head, base develop 460385256 at gate time (receipt server-gates-krkavec-124; the PR's base 3efbc28ce is now two merges behind, #2457 and #2459, neither touching any of this PR's nine files, and the merge of this head onto the current develop 604b26c6c is clean by git merge-tree): pre-commit profile gate exit 0 (76 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. Regeneration with the committed tool (cargo run -q -p workspace-coupling -- <path>, 9 s) and a line diff against the committed workspace-coupling-report-2026-10-06.md: 126 differing lines, all in the hand-written parts (the ten-line frontmatter, the Generated: stamp, and the Observations section, which the tool emits as a placeholder) — the generated sections are identical. cargo metadata --no-deps at this head: 31 workspace members; 153 normal torrust* dependency edges. GitHub checks at this head at posting time: "1 check, Docs Lint completed/success". At posting, develop is 604b26c6c.

[da2ce7]

Reviewed at 16e682999a39b077ca05a9ee7dab63aec93d6be1 (round 3). Recomputed from the bytes at this head, against develop at 7836471b3.

The push adds one commit, 16e682999, which creates docs/pr-reviews/pr-2462-review/PR-REVIEW.md (335 lines). The range-diff shows the 24 earlier commits as =. My round-2 review approved the round-2 tip, but it was not posted because the head moved during that lane; its result is carried into this round.

F1–F11. The 24 fix-bearing commits are unchanged, and the new commit touches no file they concern, so all eleven remain fixed as verified at the round-2 tip. That includes MV1/MV3 reproduced from the manifests, the bug draft's R1 listing reproduced, five mis-resolved edges, 153 + 1 diagram edges, REST nodes in their own layers, and the three drafts' plans and completion-review conditions. The record's numbering is its own: Copilot's F1–F8 keep their ids, and my F1–F11 become F9–F19, with the original id in Reviewer finding ID.

The record.

• Shape: headings match docs/templates/PR-REVIEW-TEMPLATE.md. Ownership (with N/A), Status Values (template :28-43) and Completion Rules (:115-130) are verbatim.
• Rows: all 19 have:
  • the right Source URL and Source review ID (5432054524 for F1–F8; 5439725107 for F9–F19, roots 4204784906 … 4204784977);
  • a Reply URL on the same thread (09:45:26–57Z);
  • severity equal to each bracket, and well-formed references;
  • a Resolution reference that names a subject on the branch.
• Relationships: the eight RE_RAISE_OF rows (F9→F2, F10→F4, F11→F3, F12→F5, F14→F7, F16→F1, F18→F8, F19→F6) were raised against the same unfixed head and discharged by the same commit. FIXED/RESOLVED follows the first clause of Completion Rules :119-121. The Superseded by clause fits a re-raise that needs no change of its own, as #2461 used it.
• Thread state: RESOLVED matches the capture, where all 19 threads are resolved.
• Processing Log: three entries in order, none later than the 09:51:32Z commit, and both review entries match reviews.json.
• Validator: the repository's validate-audit-record.py, run offline with the captured comments and --base 7836471b3, returns ok (19 rows, 0 failures).
• One false cell: F8's Solution (F15).

Round-2 items. My round-2 review was never posted, so its findings are restated here, re-checked at this head:

• F12 (stamps and logs trailing edits) stands.
• F13 (missing audit record) is fixed by this record, which also resolves the bare "finding F" ids in the logs: F8, F4, F3 and F5 now name the audit's rows.
• F14 (stale "four" wording) stands.

Hygiene.

• All 25 commits have author = committer. 16e682999 was authored at 09:51:32Z, after 09:25:15Z.
• docs(pr-reviews): [#2446] … matches its diff, and the scope matches the #2461 audit commits.
• No trailers, no manifest or project-words.txt change, and git diff --check is clean.

Findings

Blocking: F15 (Minor). Non-blocking: F12 and F14 (Nit).

Checked, no finding

• The Copilot rows use Reviewer finding ID N/A, because their ids were not reassigned (process-pr-review :218-219).
• Every category is from the allowed set, and each re-raise shares the category of its original.
• The record's frontmatter cites "issue #2446".
• The record contains no relative links, and no banned token.

Checks

On the loop's compute hub at this head, base develop 7836471b3 (receipt server-gates-krkavec-138): pre-commit profile gate exit 0 (76 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 7836471b3 re-measured, so no new frontmatter finding. Regeneration with the committed tool (cargo run -q -p workspace-coupling -- <path>, 5 s) and a line diff against the committed workspace-coupling-report-2026-10-06.md: 127 differing lines, all in the hand-written parts (the frontmatter, the Generated: stamp, and the thin-dependencies and Observations sections, which the tool emits as placeholders) — the generated sections are identical. cargo metadata --no-deps at this head: 31 workspace members; 153 normal torrust* dependency edges. validate-audit-record.py --pr-number 2462 over the live review comments: 19 rows, 3 log entries, 0 failures. GitHub checks at this head at posting time: "1 check, Docs Lint completed/success". At posting, develop is 30e6b7127 (the merge of #2438, which touches none of this PR's files), and the merge of this head onto it is clean by git merge-tree.

[da2ce7]

Reviewed at 3f42841ef211a7fc8194342bd2e2b609b46b0f54 (round 4). Recomputed from the bytes at this head, against develop at c7cb2b3fa.

Two pushes are covered here. The first rebased the 25 round-3 commits onto c7cb2b3fa, resolving the conflict on the 1669 EPIC, and added three fixes for my round-3 findings. The second added the record rows for that review. My review of the round-4 tip 5bf2ca74f was superseded before posting; its result is carried here, and its F16 (missing rows) is answered by 3f42841ef.

Rebase.

• The range-diff of the round-3 commits gives 23 =. Commits 7 (0dd1ba6f5) and 9 (174260529) differ only in context the merge of #2456 added: the #2454 line and the 16:05 and 20:06 log entries.
• The PR's 23 own changed lines in EPIC.md are unchanged. Its last-updated-utc edit gave way to develop's later 2026-10-07 08:04, which equals the EPIC's last log entry, and the PR's 16:21 entry sits in order between 16:05 and 20:06.
• Between the round-3 tip and the round-4 tip, the PR's paths differ only by develop's EPIC delta and the three fixes. All 28 round-4 commits are =, and this head adds only the record commit.

F1–F11. Their commits are unchanged, so they remain fixed.

F14. The bug draft :68-69 now says finding 3 "now lists all five", and finding 3 (workspace-coupling-report-2026-10-06.md:1215-1222) does list five.

F12.

• The spec's Progress Log adds 08:56 (AC2 row) and 09:11 (AC5 row) entries, backfilled at 12:39 (:314-318). Each draft adds a 09:25 completion-review entry, and the bug draft also adds 12:29.
• The entry times equal the fix commits' author times, every log is chronological, and all four stamps read 2026-10-07 12:39, no earlier than any entry.

F15.

• The record's F8 Solution (:165) now says AC1 "limits the no-mention requirement to the generated sections (everything before ## Observations)". That is what AC1 states (spec :336-339): "its generated sections (everything before ## Observations) no longer mention rest-api-core".
• No reproduction claim remains, and F18 inherits the corrected cell.

Record.

• 22 rows. F20, F21 and F22 are my F12 (Nit), F14 (Nit) and F15 (Minor), each sourced from review 5440778746 with its Reviewer finding ID, ORIGINAL, FIXED with the fix subject on the branch, and its 13:08:45–49Z reply on the same thread. RESOLVED matches the capture, where all 22 threads are resolved.
• The 10:10 log entry matches the review: CHANGES_REQUESTED at 10:10:04Z on 16e682999, with three findings. The 13:08 entry logs the fixes, the rebase, the push and the replies, and no stamp is later than the 13:16:08Z commit.
• Status Values and Completion Rules equal the template at c7cb2b3fa.
• The docs' "finding F20/F21" now resolve. The validator, run offline with --base c7cb2b3fa, returns ok (22 rows, 0 failures).

Hygiene.

• 29 commits, all with author = committer. Committer times run 12:54:23Z–13:16:08Z, ascending and after the 12:50Z merge. The three fixes were authored at 12:31–12:44Z, the usual shape of a rebase.
• Subjects are docs(issues|packages|pr-reviews): [#2446] … and match their diffs. There are no trailers.
• No manifest or project-words.txt change, git diff --check is clean, and the record has no relative links.

Findings

None.

Checked, no finding

• F16 (round 4, unposted) is fixed by 3f42841ef.
• The 13:08 log entry's "keeping both sides" holds for the quick-list and log lines. The stamp took develop's later value, which is the correct resolution.

Checks

On the loop's compute hub at this head, base develop c7cb2b3fa (receipt server-gates-krkavec-153): pre-commit profile gate exit 0 (78 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 c7cb2b3fa re-measured, so no new frontmatter finding. Regeneration with the committed tool (cargo run -q -p workspace-coupling -- <path>, 5 s) and a line diff against the committed workspace-coupling-report-2026-10-06.md: 127 differing lines, all in the hand-written parts (the frontmatter, the Generated: stamp, and the thin-dependencies and Observations sections, which the tool emits as placeholders) — the generated sections are identical, as at the round-3 head. cargo metadata --no-deps at this head: 31 workspace members; 153 normal torrust* dependency edges. validate-audit-record.py --pr-number 2462 over the live review comments captured after the maintainer's replies: 22 rows, 5 log entries, 0 failures. GitHub checks at this head at posting time: "1 check runs, 1 success (Docs Lint success)". At posting, develop is c7cb2b3fa (the merge of #2456, whose edit of the #1669 EPIC this head carries after the rebase), and the merge of this head onto it is clean by git merge-tree.

[da2ce7]

ACK 3f42841 — F12, F14 and F15 verified fixed at the bytes; record rows F20–F22 verified; the 1669 EPIC conflict is resolved, with the PR's own lines intact and develop's later stamp kept; the 25 round-3 commits are carried onto c7cb2b3

[josecelano]

ACK 1c9b209

[da2ce7]

Reviewed at 1c9b2098bb376205857e0f3426eb7d3aab209f6f (round 5). Recomputed from the bytes at this head, against develop at a43bebea9.

The push is a rebase only: the 29 round-4b commits onto a43bebea9. Because it was a force-push, it dismissed the round-4 approval.

Range-diff and develop delta.

• The range-diff from the round-4b tip 3f42841ef gives 29 =, matching the capture.
• develop's delta c7cb2b3fa..a43bebea9 touches only docs/issues/open/2411-spam-and-abuse-resistance/EPIC.md and docs/pr-reviews/pr-2469-review/PR-REVIEW.md, neither of them among this PR's 11 paths.
• The diff from 3f42841ef to this head, restricted to the PR's paths, is empty.

Hygiene.

• 29 commits, all with author = committer. Author identities, author times, subjects and bodies are unchanged.
• Committer times run 13:43:55Z–13:44:06Z, ascending and after a43bebea9 (committed at 13:42:51Z).
• No trailers, no banned token, no manifest or project-words.txt change, and git diff --check is clean.

Findings

None.

Checked, no finding

• The round-4b verification stands unchanged for every carried commit: the rebase onto c7cb2b3fa, F12/F14/F15, and the record rows F20–F22.

Checks

On the loop's compute hub at this head, base develop a43bebea9 (receipt server-gates-krkavec-159): pre-commit profile gate exit 0 (79 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 a43bebea9 re-measured, so no new frontmatter finding. Regeneration with the committed tool (cargo run -q -p workspace-coupling -- <path>, 5 s) and a line diff against the committed workspace-coupling-report-2026-10-06.md: 127 differing lines, all in the hand-written parts (the frontmatter, the Generated: stamp, and the thin-dependencies and Observations sections, which the tool emits as placeholders) — the generated sections are identical, as at the round-3 head. cargo metadata --no-deps at this head: 31 workspace members; 153 normal torrust* dependency edges. validate-audit-record.py --pr-number 2462 over the live review comments captured after the maintainer's replies: 22 rows, 5 log entries, 0 failures. GitHub checks at this head at posting time: "2 check runs, 2 success (Docs Lint success; Docs Lint success)". At posting, develop is a43bebea9 (this head's base after the rebase), and the merge of this head onto it is clean by git merge-tree.

[da2ce7]

ACK 1c9b209 — the 29 verified commits are carried unchanged onto a43bebe (29 identical in the range-diff, no PR path changed), so the round-4b verification stands