Repository navigation
docs(issues): [#2278] record the PR #2484 retrospective dispositions in the matrix - #2494
Merged
josecelano merged 4 commits intoOct 9, 2026
Merged
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
The EPIC retains stale three-retrospective scope, and the path sweep needs a historical-reference exception.
2 open findings
What changed in this PR
Records dispositions for the six PR #2484 retrospective proposals within EPIC #2278.
Changes:
- Adds PR #2484 decisions to the improvement matrix.
- Routes adopted, deferred, and out-of-scope items to their owners.
- Updates affected subissues and the progress log.
| File | Description |
|---|---|
retrospective-improvement-matrix.md |
Adds six retrospective dispositions and ownership. |
EPIC.md |
Updates subissue scope, metadata, and progress. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 8, 2026
Review 5460432014 raised two Minor findings on this pull request: the EPIC's scope text omitted the PR torrust#2484 retrospective (F1), and the pre-push sweep's path rule also rejected references kept as history (F2). The record carries both rows with their sources, the fix that answers them and verifications anchored to headings and quoted phrases, so they hold when the files move again. The reply URLs are filled in once the replies are posted after the push.
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 8, 2026
Contributor
Author
|
Three commits added on top of
Ready for review. |
josecelano
added a commit
that referenced
this pull request
Oct 8, 2026
…2482 2b8f981 docs(pr-reviews): [#2482] record the PR #2484 round-6 approval and F23 (Jose Celano) 43cd0f4 docs(pr-reviews): [#2482] correct the F18 solution's adoption claim (Jose Celano) 5317582 docs(pr-reviews): [#2482] credit #2278's adoption of event-derived log stamps (Jose Celano) 2f22dc7 docs(pr-reviews): [#2482] rewrap the 12:42 audit log entry to 100 columns (Jose Celano) 9bc4dc6 docs(pr-reviews): [#2482] record the PR #2484 round-5 findings (Jose Celano) 47d34ba docs(pr-reviews): [#2482] scope the retrospective to rounds 1-4 and record the #2003 triage (Jose Celano) 8acb54a docs(pr-reviews): [#2482] name the head each old line range held at (Jose Celano) 87339ea docs(pr-reviews): [#2482] rewrap the What Went Well item to 100 columns (Jose Celano) a1890d6 docs(pr-reviews): [#2482] note that F9 and F10 shared one fix commit (Jose Celano) e65afd3 docs(pr-reviews): [#2482] drop the claim that a derived-stamp rule exists (Jose Celano) f398a1b docs(pr-reviews): [#2482] trace F8's long line to the round-1 log entry (Jose Celano) b8ccf72 docs(pr-reviews): [#2482] say which approvals the round-3 and round-4 fixes cost (Jose Celano) 04626f4 docs(pr-reviews): [#2482] place round 1's F2 in the spec, not the inventory (Jose Celano) 08be871 docs(pr-reviews): [#2482] record the PR #2484 round-4 approval and F14 (Jose Celano) 25430e9 docs(pr-reviews): [#2482] add the PR #2484 review retrospective (Jose Celano) 974a556 docs(pr-reviews): [#2482] cite the EPIC passages by section in the PR #2484 audit (Jose Celano) 9e403e1 docs(pr-reviews): [#2482] record the PR #2484 round-3 approval and F13 (Jose Celano) c8a4da8 docs(issues): [#2482] say subissue 1's spec will carry the ownership review (Jose Celano) c9a2872 docs(pr-reviews): [#2482] record the PR #2484 round-2 findings (Jose Celano) c321929 docs(pr-reviews): [#2482] point the PR #2484 audit at EPIC.md (Jose Celano) 26e5185 docs(issues): [#2482] date the sub-EPIC conversion at 12:53 in EPIC #1669 (Jose Celano) 47b48b2 docs(issues): [#2482] carry the environment ownership rule into D2 (Jose Celano) 6e28df9 docs(issues): [#2482] rewrap the round-1 log entry to 100 columns (Jose Celano) d7ee188 docs(issues): [#2482] convert the issue into a sub-EPIC of #1669 (Jose Celano) 38b7b0b docs(pr-reviews): [#2482] add the PR #2484 review audit (Jose Celano) 1bd4721 docs(issues): [#2482] log the round-1 review fixes (Jose Celano) 345e938 docs(issues): [#2482] rewrap the publishing paragraph to the file's line width (Jose Celano) 913abbe docs(issues): [#2482] scope the publishing plan to members without publish = false (Jose Celano) fe4351d docs(issues): [#2482] name the open #1488 subissues that change the environments (Jose Celano) 707678e docs(issues): [#2482] state how the inventory counts intra-doc links (Jose Celano) caab189 docs(issues): [#2482] say only two environments alias Unstarted (Jose Celano) 20532a8 docs(issues): [#2482] say which tracker-core test modules stay public (Jose Celano) 7bd808b docs(issues): [#2482] drop torrust-info-hash from the udp module's dependencies (Jose Celano) 0bdad9f docs(issues): [#2482] date the test-helpers dependency growth in two steps (Jose Celano) 96f5421 docs(issues): [#2482] broaden the spec to how packages share test support code (Jose Celano) 540856b docs(issues): [#2482] run the root test targets instead of a removed integration target (Jose Celano) 292bf4e docs(issues): [#2482] add issue specification for the test-helpers decoupling (Jose Celano) Pull request description: ## Summary Spec-only PR for #2482, now a **sub-EPIC of EPIC #1669**. No code changes. At the maintainer's request, #2482 was first broadened from "move the `http`/`udp` helpers out of `test-helpers`" to deciding how workspace packages share test support code, and then converted from a task into a sub-EPIC: it decides the rules (one ADR) in its first subissue and then applies them package by package in later subissues. The goal is that no shared crate becomes a coupling hub and test-only code and dependencies stay out of production builds unless a consumer opts in. Related to #2482 Related to #1669 ## Changes - `docs/issues/open/2482-1669-reorganize-shared-test-support/` (moved from `docs/issues/drafts/1669-decouple-test-helpers-from-unpublished-crates/`, then renamed from `2482-1669-decouple-test-helpers-from-unpublished-crates`): - `EPIC.md` (was `ISSUE.md`): goal, why, why a sub-EPIC, criteria, options (O1 `testing` feature, O2 separate support crate, O3 `tests/common/`, O4 leaf `test-helpers`, O5 `#[cfg(test)]`, O6 keep DEC-13), and: - **Subissues**: subissue 1 decides (tasks D1 to D5: Cargo rule experiments MV1 to MV3, ADR, DEC-13 amendment, migration drafts, report links); provisional subissues 2 to 8, one per inventory item, with ordering notes. - **How we work in this EPIC**: decision first; one subissue at a time, each with its own GitHub sub-issue, spec-only PR and implementation PR; naming (`{issue}-2482-{slug}`, `epic: 2482`); behaviour unchanged by moves; environment moves after the EPIC #1488 subissues that change the same environments (#2449, #2450, #2471); the inventory as a living document. - **Closing the EPIC**, epic acceptance criteria and risks. Earlier progress-log entries are kept. - `test-support-inventory.md` (new): the five test support patterns found across the 31 workspace members, with their consumers and the dependencies they force: - A. Public `testing`/`environment` modules in four server packages, compiled into every build, forcing 9 normal dependency edges that production code does not use. - B. The shared `test-helpers` crate, whose `http`/`udp` modules have one consumer (finding 1). - C. Crate-private `#[cfg(test)]` helpers in `tracker-core` declared `pub mod`. - D. Unconditional `#[automock]` mocks in `tracker-core` (`mockall` as a normal dependency). - E. Per-package `tests/common/` folders. - The draft for finding 2 (`docs/issues/drafts/1669-gate-server-testing-modules-behind-feature/`) is removed and folded in; its feature-gating plan is option O1 and its coupling tool change is provisional subissue 8. - `docs/issues/open/1669-overhaul-packages/EPIC.md`: one quick-list entry and one Details row for the sub-EPIC (its subissues are tracked in its own `EPIC.md`), Specs Index link, and progress-log entries. - `workspace-coupling-report-2026-10-06.md`: findings 1 and 2 link the sub-EPIC. - Round-1 review (`da2ce7`, review 5454599321): all seven findings fixed and recorded in `docs/pr-reviews/pr-2484-review/PR-REVIEW.md`; the sub-EPIC conversion came after and keeps those fixes. - `docs/pr-reviews/pr-2484-review/review-retrospective.md`: a review retrospective of rounds 1 to 4, written at the maintainer's request. Rounds 2 to 4 came from the author's own edits; it proposes six process improvements, which the EPIC #2003 owner triaged in this PR's conversation (dispositions in PRs #2494 and #2366). - Review rounds 1 to 5 (`da2ce7`) are all fixed and recorded in the audit record above. On GitHub, #2482 now carries the `EPIC` label instead of `task`, and its body describes the sub-EPIC. The branch keeps its original name; renaming it would require a new PR. Pre-commit and pre-push checks passed. ACKs for top commit: josecelano: ACK 2b8f981 da2ce7: ACK 2b8f981 — F23 fixed at the bytes and its audit row and the F18 correction verified against review 5460915644, its reply, the #2278 matrix row and the template at this head Tree-SHA512: 6592e5561f51974fc68ee84b3576525a294bc0ef52c791e4ad9214386ee4d1e463ea4a42ce99f0b8fa825ef50cd01ffa8fdd029f27e4fa8c5646cc4df54eb428
josecelano
approved these changes
Oct 9, 2026
josecelano
left a comment
josecelano
left a comment
Member
There was a problem hiding this comment.
Approved at 53a49579c. The six matrix rows match the retrospective's triage paragraph and the #2003 owner's triage comment (issuecomment-6064986152); F1 and F2 are fixed, replied to, and resolved, and the audit's reply URLs match the posted replies. PR #2484 has merged, so the merge-order condition is met.
[Minor][R1] Please update the PR description before merge; editing it does not dismiss this approval. It still says "One commit, two files", but the PR now has four commits and also adds docs/pr-reviews/pr-2494-review/PR-REVIEW.md, and the Validation section reports results at caa7818f7 only. The merge tool copies the description into the merge commit, so it becomes permanent develop history. Please describe the current scope and state the validation at the current head.
The three inline findings (R2 to R4) are non-blocking: please do not push for them now, because a push would dismiss this approval. Carry R2 and R4 in the next #2278 change that touches these files (order 5 is the natural carrier); R3 is a note only.
Member
|
ACK 53a4957 |
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 9, 2026
Review 5468071770 raised four findings on this pull request, which had no audit record yet. The record lists them with their dispositions: R1 and R2 are fixed in the tree, R3 needs no change because the sentence holds once PR torrust#2494 merges first, and R4 is answered by the replaced description. The reply URLs are placeholders until the replies are posted, so the validator passes only after they are recorded.
Member
|
@da2ce7 thank you for the replies; R2 to R4 are resolved and the updated description covers R1. One step remains before merge: GitHub's merge ref for this PR is still based on The push will dismiss the approval ( |
… dispositions in the matrix The PR torrust#2484 review retrospective proposes six improvements and asks the owner of EPIC torrust#2003 to decide which enter it or this child EPIC. The matrix is this EPIC's decision input, so each proposal gets a row in its form: the manual pre-push sweep and anchoring verifications to headings or quoted phrases are adopted for order 5, the sweep's tool is deferred to order 8 for its audit-body part, deferring non-blocking findings after an approval is deferred to order 10, and the spec-template, create-issue and session items are left to EPIC torrust#2003's register. Orders 5, 8 and 10 name what they gained, and the progress log records the decision. No fixed decision of the Decision Record changes.
…in the EPIC's scope and qualify the path sweep The PR torrust#2484 rows made the retrospective a decision source, but the Decision Record still said the matrix maps "the three retrospectives", AC1 required only PRs torrust#2270 to torrust#2272, and References listed those three. The Decision Record now names the retrospectives the matrix lists, so it stays true when another arrives; AC1, its verification and References cover PR torrust#2484, whose retrospective reaches develop when that PR merges. The sweep's path check failed any tracked file naming a deleted or renamed path, including references that record history on purpose. It now fails only on a current reference (a live link, a related-artifacts entry, a verification claim about the current tree) and allows references marked historical, keeping EPIC torrust#2264's distinction between current and historical paths.
Review 5460432014 raised two Minor findings on this pull request: the EPIC's scope text omitted the PR torrust#2484 retrospective (F1), and the pre-push sweep's path rule also rejected references kept as history (F2). The record carries both rows with their sources, the fix that answers them and verifications anchored to headings and quoted phrases, so they hold when the files move again. The reply URLs are filled in once the replies are posted after the push.
da2ce7
force-pushed
the
2278-2484-retrospective-dispositions
branch
from
October 9, 2026 10:59
53a4957 to
99ae7d4
Compare
Contributor
Author
|
Rebased onto |
Member
|
ACK 99ae7d4 |
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 9, 2026
…red R2 and R4 into the order-5 change Review 5467975631 approved PR torrust#2494 and deferred two non-blocking findings to the next torrust#2278 change touching these files, because a push would have dismissed the approval. R2: the References line still said the PR torrust#2484 retrospective reaches develop when PR torrust#2484 merges, which has happened, so the clause goes. R4: the PR torrust#2484 sweep row's Disposition read "Defer (tool)", while its rationale defers only the audit-body check and assigns the tree-wide checks to other owners; in the matrix's vocabulary those are Out of scope, so the cell now says so. A Progress Log entry records the carry.
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 9, 2026
…ix assigns to order 5 PR torrust#2494 added the PR torrust#2484 retrospective's rows to the torrust#2278 matrix and assigned two of them to order 5: a manual sweep before each push to a reviewed branch, and anchoring each Current-tree verification to a heading or quoted phrase. The order-5 draft predates them and named neither, so the order would have closed without delivering two adopted items. The draft now carries both in its Background, Scope table, tasks and acceptance criteria, citing the matrix rows by source PR and quote, and its Progress Log records that they entered with this round.
josecelano
added a commit
that referenced
this pull request
Oct 10, 2026
…omes from PR #2428 072cc27 docs(pr-reviews): [#2264] [#2278] record the PR #2434 round 2 reply URLs (Cameron Garnham) 4edf187 docs(pr-reviews): [#2264] [#2278] record the maintainer's review of PR #2434 (Cameron Garnham) 6b006f7 docs(issues): [#2264] [#2278] hedge the #2003 record reference and cite the round-3 review (Cameron Garnham) b7cc3f0 chore(spelling): add backlink to the project dictionary (Cameron Garnham) eb036e3 docs(pr-reviews): record the F1 reply URL on PR #2434 (Cameron Garnham) f7bcc43 docs(pr-reviews): add the PR #2434 review audit record (Cameron Garnham) e3337c2 docs(discussions): link the #2264 and #2278 records from their Outcomes (Cameron Garnham) 99c5ebc docs(issues): [#2278] record the audit-record decisions from the discussions (Cameron Garnham) 714fcd1 docs(issues): [#2264] record the semantic-linking and goals discussion outcomes (Cameron Garnham) Pull request description: Related to #2264 Related to #2278 ## Summary PR #2428 merged three design discussions under `docs/discussions/2003-overhaul-guardrails-and-automation/`, each ending in an Outcome section that transcribes the EPIC owner's answers and notes that none of them is recorded in an EPIC yet. This documentation-only PR records the parts that belong to EPICs #2264 and #2278 in their specifications, each record linking its Outcome section by path and naming the review that holds it. The #2003 parts are recorded on the EPIC's own open PR #2366. - **EPIC #2264.** A new `Decisions Recorded on This EPIC` section, placed before `Open Questions`, records the semantic-linking discussion's four answers (inventory first, pinned to a named `develop` commit; one `kind:value` form for every target without a path, with the recount at the sweep's starting head and the note that this touches the frozen v1 convention; tracked files only, with GitHub-hosted records as a dated derived export; where the decisions are recorded) and the goals-and-boundaries parts that name this EPIC (links validated by the purpose of their field; the change-impact field definition split or qualified). The three Open Questions these answer are marked as answered in direction or in part, with a pointer, and the Expected output cells of orders 5 and 7 carry the scope the decisions set. One Progress Log entry and the update stamp. - **EPIC #2278.** A dated sub-list under `Decision Record` records the audit-record parts of the goals-and-boundaries Outcome: the record as contract, stamped-or-checked copies of GitHub state as the premise of the validator rows, and `epic-owner`; it also records that the specifications-and-rationale Outcome, from review 5402713128 (round 3), sends no work to this EPIC. One Progress Log entry and the update stamp. ## Files Touched - `docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md` - `docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md` - `docs/discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md` and `…/20261003-goals-and-boundaries/README.md` (round 1: the Outcome status sentences now link their records) - `docs/pr-reviews/pr-2434-review/PR-REVIEW.md` (new: the review audit record, extended in round 2) - `project-words.txt` (one word, `backlink`, which a reviewer finding quoted in the record uses) ## Review round 1 F1 (Major) of review 5407866771 is fixed: the two merged discussion Outcomes said none of their answers was recorded in an EPIC and lacked the backlink the convention asks for. `docs(discussions): link the #2264 and #2278 records from their Outcomes` replaces each Outcome's status sentence with the links to #2264's `Decisions Recorded on This EPIC` and #2278's `Decision Record`; the #2003 parts are named as recorded by the overhaul pull request #2366, which replaces that clause with the link when it lands. The audit record carries F1 as FIXED and RESOLVED with its reply URL. The Docs Lint workflow failed on the first pushed head of that round on the word `backlink` inside the quoted finding; the word is added to the project dictionary rather than rewording the reviewer's text. ## Review round 2 Review 5467876260 found no blocking issues and left four non-blocking findings, all fixed in two commits on top of `d26ba356c`: - `docs(issues): [#2264] [#2278] hedge the #2003 record reference and cite the round-3 review` fixes R1 to R3. R1 (Minor): #2264's "Where these decisions are recorded" bullet now says the four-aspect frame and the discussions convention "are recorded on #2003 by its overhaul pull request #2366", the goals-and-boundaries Outcome's hedge, because `develop` does not yet carry them. R2 (Minor): #2278's specifications-and-rationale bullet cites review 5402713128 (round 3) beside its Outcome link, and the 2026-10-04 Progress Log entry names it for that discussion. R3 (Nit): #2264's 2026-10-04 Progress Log entry gains its final period. Both EPICs' `last-updated-utc` is bumped; neither file logs corrections of its own text, so no Progress Log entry is added. - `docs(pr-reviews): [#2264] [#2278] record the maintainer's review of PR #2434` fixes R4 (Nit) and records the round: rows and detail blocks for R1 to R4, and appended Processing Log entries, one of which records that the F1 thread was resolved immediately after its reply was posted at 2026-10-04 19:59:32 UTC. The log is append-only and checked for chronological order, so that entry carries the time it was recorded and states the resolution's time in its text. A third commit, `docs(pr-reviews): [#2264] [#2278] record the PR #2434 round 2 reply URLs`, names the four posted replies in the record; the four threads are resolved. ## Rebase after PR #2494 PR #2494 merged into `develop` at `686a42f45` and also changed `docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md`, so this branch was rebased onto it; every other file merged cleanly, and the nine commits keep their content apart from that file. The conflict is resolved by keeping both sides: PR #2494's changes to the EPIC (the Decision Record's wording, the notes on rows 5, 8 and 10, AC1, References and its two 2026-10-08 Progress Log entries) and this branch's Decision Record sub-list, with review 5402713128 cited on the specifications-and-rationale bullet, and its 2026-10-04 Progress Log entry, which now sits before the 2026-10-08 entries so the log stays chronological. `last-updated-utc` is this branch's 2026-10-09 10:41, the round-2 fix, which is later than every entry. ## Validation At this head: In a Linux container with the workspace nightly toolchain, at the rebased head `072cc27d2`, base `develop` `686a42f45`: pre-commit profile gate exit 0 (74 s); `linter markdown`, `linter cspell`, `linter lychee` exit 0; `frontmatter-validator --all` 19 errors / 4 warnings at this head and at `develop` re-measured; `validate-audit-record.py --pr-number 2434` against the review comments captured after the round-2 replies: 5 rows, 9 log entries, 0 failures; `git range-diff` against the pre-rebase head shows seven commits equal and two differing only in the resolved EPIC hunks. The earlier heads' results: at `75a7682ee` and `ebe5e0138` (base `39e5b1b8c`), pre-commit profile gate exit 0 (119 s and 147 s), the three linters exit 0, `frontmatter-validator --all` 22 / 4 at each head and at the base, the audit validator 0 failures at `ebe5e0138`. ACKs for top commit: josecelano: ACK 072cc27 Tree-SHA512: b5494a7dcdb275084bafb1e4da5a0ca5b95ad6fa402628558c0f34fae6e6eba1c28ae76c875ae914d593551b7bc7a9ce848e7827ca3c6c02601e22176fc86d22
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 11, 2026
…red R2 and R4 into the order-5 change Review 5467975631 approved PR torrust#2494 and deferred two non-blocking findings to the next torrust#2278 change touching these files, because a push would have dismissed the approval. R2: the References line still said the PR torrust#2484 retrospective reaches develop when PR torrust#2484 merges, which has happened, so the clause goes. R4: the PR torrust#2484 sweep row's Disposition read "Defer (tool)", while its rationale defers only the audit-body check and assigns the tree-wide checks to other owners; in the matrix's vocabulary those are Out of scope, so the cell now says so. A Progress Log entry records the carry.
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 11, 2026
…ix assigns to order 5 PR torrust#2494 added the PR torrust#2484 retrospective's rows to the torrust#2278 matrix and assigned two of them to order 5: a manual sweep before each push to a reviewed branch, and anchoring each Current-tree verification to a heading or quoted phrase. The order-5 draft predates them and named neither, so the order would have closed without delivering two adopted items. The draft now carries both in its Background, Scope table, tasks and acceptance criteria, citing the matrix rows by source PR and quote, and its Progress Log records that they entered with this round.
4 of 45 tasks
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 13, 2026
…red R2 and R4 into the order-5 change Review 5467975631 approved PR torrust#2494 and deferred two non-blocking findings to the next torrust#2278 change touching these files, because a push would have dismissed the approval. R2: the References line still said the PR torrust#2484 retrospective reaches develop when PR torrust#2484 merges, which has happened, so the clause goes. R4: the PR torrust#2484 sweep row's Disposition read "Defer (tool)", while its rationale defers only the audit-body check and assigns the tree-wide checks to other owners; in the matrix's vocabulary those are Out of scope, so the cell now says so. A Progress Log entry records the carry.
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 13, 2026
…ix assigns to order 5 PR torrust#2494 added the PR torrust#2484 retrospective's rows to the torrust#2278 matrix and assigned two of them to order 5: a manual sweep before each push to a reviewed branch, and anchoring each Current-tree verification to a heading or quoted phrase. The order-5 draft predates them and named neither, so the order would have closed without delivering two adopted items. The draft now carries both in its Background, Scope table, tasks and acceptance criteria, citing the matrix rows by source PR and quote, and its Progress Log records that they entered with this round.
josecelano
added a commit
that referenced
this pull request
Oct 13, 2026
…specification 29b87d8 docs(pr-reviews): [#2278] record the PR #2431 round 2 reply URLs (Cameron Garnham) cf4b1b3 docs(pr-reviews): [#2278] record the maintainer's round 2 on PR #2431 (Cameron Garnham) 452a5ca docs(issues): [#2278] restate the #2362 overlap on current develop (Cameron Garnham) 0242f53 docs(issues): [#2278] cover the PR #2484 items the matrix assigns to order 5 (Cameron Garnham) 066dd18 docs(issues): [#2278] cite the skill, template, matrix and EPIC by stable references (Cameron Garnham) 79613e7 docs(issues): [#2278] carry the PR #2494 review's deferred R2 and R4 into the order-5 change (Cameron Garnham) a5130aa docs(pr-reviews): [#2278] add the PR #2431 review audit record (Cameron Garnham) bed38f9 docs(issues): [#2278] record a comparison base per historical audit (Cameron Garnham) 355e9c4 docs(issues): [#2278] specify the pre-posting pass of the self-audit gate (Cameron Garnham) b8d4397 docs(issues): [#2278] draft the order 5 self-audit gate specification (Cameron Garnham) Pull request description: Related to #2278 ## Summary This spec-only PR drafts EPIC #2278 order 5, "Add the author self-audit gate to `process-pr-review`". It contains planning documentation only: no skill, template, validator or workflow change. - **Draft specification for order 5.** New folder-style draft at `docs/issues/drafts/2278-author-self-audit-gate/ISSUE.md`. The order is docs only. It takes its content from the EPIC's retrospective-improvement matrix: the rows routed to the self-audit gate (run the validator when it can run and do its checks by hand otherwise, re-derive everything after a second re-raise and after context compaction, corrections re-derived from named Git or GitHub commands, command and result before narrative, no self-referential counts, one fix per commit, `git show --stat` on cited commits, log stamps from Git and GitHub timestamps), the F65 counterpart to "update progressively", the manual part of F55, and the two PR #2484 items the matrix assigns to order 5 (a manual sweep before each push to a reviewed branch, and anchoring each `Current-tree verification` to a heading or quoted phrase). Each gate pass is recorded as one append-only Processing Log entry naming the gated event and the commands run; no helper is a prerequisite and no per-finding field is added. Four commit points: the skill's gate section, template guidance, two checklist items, and the evidence with the EPIC row. - **Stable references.** The draft names matrix rows by F-ID or by source PR and a short quote, and cites the skill, the template, the validator and the EPIC by section heading or quote, so later merges into those files do not move its citations. The skill is at version 1.5 on `develop` `686a42f45`; order 5 bumps it from there, or from the version #2362 leaves. - **EPIC bookkeeping.** Progress Log lines record the draft and the carried review items; row 5 keeps its `TODO` status and placeholder path until the issue exists. ## Requested Maintainer Decisions The maintainer agreed with the draft's proposed answers to questions 2 to 5 in review 5469277375; question 1 waits on the restated #2362 overlap below. 1. Sequencing with #2362 (pending confirmation). Re-derived by quote on `develop` `686a42f45`, #2362 rewrites, in the skill, Workflow step 7's superseded-thread sentence, step 8 ("Consolidate review bodies"), the Detail-Entry Fields sentence on `FIXED` resolution references, and the Completion Checklist item on consolidated responses; in the template, the Status Values bullet on outdated threads, the `Resolution reference` placeholder and the guidance paragraph after it, and the Completion Rules bullets on outdated threads, consolidated responses and citing a fix. This order rewrites none of those passages, so no sentence is changed by both. Both edit three of the same sections (Workflow step 7, the Completion Checklist, and the template guidance beside Finding Details), where this order inserts next to #2362's passages, and both bump the skill version. The rule for a fix outside the tree, already on `develop`, is the text #2362's F5 and F6 wording starts from. Which lands first? The second rebases over the first's text in those three sections and takes the next skill version. 2. The copied `## Completion Rules` section carries no gate bullet, because every new record would copy it and order 8 would byte-diff it. Agreed as proposed. 3. One gate pass may precede several replies posted together when it covers every replied row. Agreed as proposed. 4. F75 (`RE_RAISE_OF` does not say whose finding ID it takes) keeps its wording with order 8, where the register places it. Agreed as proposed. 5. The EPIC's order-10 row lists "F55 as a self-audit step" while the matrix's F55 row places the manual step in T2; the draft keeps it here in its own commit so it can move unchanged. Agreed as proposed. 6. On approval, the GitHub issue is created, the draft moves to `docs/issues/open/` with its number, and row 5 links to it. ## Files Touched - `docs/issues/drafts/2278-author-self-audit-gate/ISSUE.md` (new) - `docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md` (one Progress Log line for the draft; with the carry commit, the References line, a second Progress Log line and the frontmatter stamp) - `docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/retrospective-improvement-matrix.md` (the carry commit: one Disposition cell and the frontmatter stamp) - `docs/pr-reviews/pr-2431-review/PR-REVIEW.md` (new: the review audit record, rounds 1 and 2) ## Rebase, carried items and round 2 PR #2494 merged into `develop` at `686a42f45` and also changed the #2278 EPIC, so this branch was rebased onto it; every other file merged cleanly. The EPIC conflict is resolved by keeping both sides: PR #2494's changes, including its two 2026-10-08 Progress Log entries, and this branch's 2026-10-03 entry for the draft, placed before them so the log stays chronological. `docs(issues): [#2278] carry the PR #2494 review's deferred R2 and R4 into the order-5 change` applies the two non-blocking findings that review 5467975631 deferred to this change: the References line drops the clause on when the PR #2484 retrospective reaches `develop`, and the PR #2484 sweep row's Disposition reads "Adopt (manual sweep); Defer (audit-body tool check); Out of scope (tree-wide tool checks)". Review 5469277375 is answered by `docs(issues): [#2278] cite the skill, template, matrix and EPIC by stable references` (F3, F4), `docs(issues): [#2278] restate the #2362 overlap on current develop` (F5) and this description (F6). `docs(issues): [#2278] cover the PR #2484 items the matrix assigns to order 5` adds the two items the matrix has assigned to this order since PR #2494, and `docs(pr-reviews): [#2278] record the maintainer's round 2 on PR #2431` records the round. After PR #2434 merged, the branch was rebased again, onto `develop` `f960c78d7`; its ten commits keep their content, and the #2278 EPIC conflict is resolved as the maintainer asked. ## Merge order PR #2434 merged into `develop` at `f960c78d7`, and this branch is rebased onto it. The rebase touched only the #2278 EPIC's frontmatter stamp and the position of one Progress Log entry, resolved as the maintainer asked: both sides' entries are kept, this branch's 2026-10-03 17:09 entry sits before `develop`'s 2026-10-04 19:18 entry, and `last-updated-utc` stays "2026-10-09 11:16", the stamp of the merged log's latest entry. PR #2486 then merged into `develop` at `7711ade56`, and this branch is rebased onto it at the maintainer's request; no file conflicted, so every commit is unchanged in content (`git range-diff` against `284095128`: 10 commits equal). ## Validation At this head: In a Linux container with the workspace nightly toolchain, at the rebased head `29b87d8ef`, base `develop` `7711ade56` (the merge base): pre-commit profile gate exit 0 (79 s); `linter markdown`, `linter cspell`, `linter lychee` exit 0; `frontmatter-validator --all` 19 errors / 4 warnings at the head and 19 / 4 at `develop` re-measured; `validate-audit-record.py --pr-number 2431` against the review comments captured after the round-2 replies were posted: 6 rows, 12 log entries, 0 failures; `git range-diff` against `284095128` shows all 10 commits equal (the previous rebase's range-diff against `7b7348dbf`: 8 equal, 2 differing only in the resolved EPIC hunks). ACKs for top commit: josecelano: ACK 29b87d8 Tree-SHA512: fe6f791a4761f4b835d1c8c44df3e605182301606c9e6226b3f31b65f60eaa614ad210f881193d50f895420d6f7305a1df27092a3932661dbb7a59850756dd20
da2ce7
added a commit
to da2ce7/torrust-tracker
that referenced
this pull request
Oct 13, 2026
Review 5468071770 raised four findings on this pull request, which had no audit record yet. The record lists them with their dispositions: R1 and R2 are fixed in the tree, R3 needs no change because the sentence holds once PR torrust#2494 merges first, and R4 is answered by the replaced description. The reply URLs are placeholders until the replies are posted, so the validator passes only after they are recorded.
josecelano
added a commit
that referenced
this pull request
Oct 13, 2026
…ter the hand-off 27ddb0a docs(issues): [#2003] describe the register's index as five comments at its 2026-10-11 revision (Cameron Garnham) 48a5d0e docs(issues): [#2003] record the provenance rounds and the rebase, and drop the index version (Cameron Garnham) 3ffa0f5 docs(pr-reviews): [#2003] record the PR #2366 reply URLs (Cameron Garnham) 2e27966 docs(pr-reviews): [#2003] add the PR #2366 review audit (Cameron Garnham) 5ae74fb docs(issues): [#2003] refresh the friction register section and the checkpoint range (Cameron Garnham) 7356602 docs(issues): [#2003] record the PR #2484 retrospective dispositions (Cameron Garnham) 914f8ae docs(issues): [#2003] follow the prose-tests draft's placement under the EPIC (Cameron Garnham) 3fa09ac docs(issues): [#2003] record the discussion outcomes on the EPIC (Cameron Garnham) 20c2d33 docs(issues): [#2003] place the two draft specifications and record the #2375 scheduling (Cameron Garnham) f95f26d docs(issues): [#2003] overhaul the EPIC specification after the hand-off (Cameron Garnham) Pull request description: ## Summary Overhauls the EPIC #2003 specification so the file carries what the issue's comment thread established since July, and hands the EPIC to its new owner. Ten commits: six change the EPIC, the seventh adds this pull request's review audit record, the eighth records the reply URLs in it, the ninth records what the rebase onto current `develop` brought, and the tenth describes the register's index as the five comments it now spans. The GitHub issue body mirrors the EPIC under the Issue Body Mirror rule in its Verification Plan and is re-derived from this head (see Validation). Related to #2003 ## Files touched - `docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md` (commits 1 to 6, 9 and 10) - `docs/pr-reviews/pr-2366-review/PR-REVIEW.md` (commit 7, new) ## First commit: the overhaul after the hand-off `docs(issues): [#2003] overhaul the EPIC specification after the hand-off` The GitHub issue body was updated first (2026-09-28 16:39 UTC) and mirrored this file exactly; 42 of the issue's 46 comments were then minimized because the text carries them, and only the friction register index (two comments at the time) and the ownership record stayed visible. What the revision adds: an owner line; the Subissues table through order 13 in the template's columns (statuses, notes, the two child EPICs, #2347 and #2360); the order-12 close-out list; the follow-up owners created by #2347; the five undecided improvement candidates from the #2347 retrospective; a "Decisions Recorded on This EPIC" section (interim formatter, author-side register items to #2278, semantic labels, ownership); a "Friction Register" section with the labelling rule, the closed F series, the disposition precedence, the in-place filing rule and the per-group counts of 2026-09-28; the findings without an owning subissue; dated progress-log entries; an "Issue Body Mirror" rule under Verification Plan; four new risks; and reference lines for the index, the ownership record and the inventory measurements. Sections that were already current are unchanged apart from reflowing each paragraph, list item and table row onto one line. Frontmatter: `epic-owner` is `da2ce7`; `status` stays `planned`; `last-updated-utc` is the quoted UTC minute of the last edit and equals the last progress-log entry; the semantic links gain `process-pr-review` and the child-EPIC, #2347 and schema artifacts. ## Second commit: the draft specifications and the #2375 scheduling `docs(issues): [#2003] place the two draft specifications and record the #2375 scheduling` Places the two draft specifications that landed on `develop` (the AI-agent memories draft and the AI-harness workspace draft) under a new "Drafts Awaiting Issues" subsection, records the #2375 scheduling position in its row, and adds the placement decision and a progress-log line. ## Third commit: the discussion outcomes `docs(issues): [#2003] record the discussion outcomes on the EPIC` After PR #2428 merged the three design discussions, records under `Decisions Recorded on This EPIC` the goals-and-boundaries decisions (the four-aspect frame, the gates, contract versus technique, coordination claims, copies of GitHub state, the discussions convention) and the four specifications-and-rationale answers as revised in review round 4, each linking its Outcome section by path and naming the review that holds it, with a Progress Log entry and the update stamp. The parts that belong to #2264 and #2278 are recorded in PR #2434. ## Fourth commit: the prose-tests draft's placement `docs(issues): [#2003] follow the prose-tests draft's placement under the EPIC` Follows the prose-tests ADR draft's placement under this EPIC, merged by PR #2437. The specifications-and-rationale decision links the draft at `docs/issues/drafts/2003-adopt-prose-tests-as-executable-specification/ISSUE.md`, and Drafts Awaiting Issues lists it beside the memories and harness-workspace drafts, under the Scope exception until its issue is created. ## Fifth commit: the PR #2484 retrospective dispositions `docs(issues): [#2003] record the PR #2484 retrospective dispositions` The PR #2484 review retrospective asks this EPIC's owner to decide which of its six proposals enter this EPIC or #2278. A Friction Register paragraph records where each lands: items 1 to 3 in #2278's improvement matrix (orders 5, 8 and 10, added by PR #2494); item 4 (one stamp per event in spec progress logs) on `issue-template-log-correction-rule-unstated`; item 5 (a step for restructuring a spec under review) on `create-issue-issue-to-epic-conversion-unstated`; item 6 (one session per pull-request branch) as a new label against `docs/agents/orchestration.md`; and item 1's tree-wide path sweep and line-width check on `linter-path-citations-unchecked` and `write-markdown-docs-line-wrap-rule-unstated`. A Progress Log entry stamped 2026-10-08 16:50 UTC records the triage, and `last-updated-utc` matches it. ## Sixth commit: the friction register section and the checkpoint range `docs(issues): [#2003] refresh the friction register section and the checkpoint range` Answers R1 and R2 of review 5468071770: - The Friction Register describes the register's index as the four comments it now spans: at index v31 (2026-10-08 13:31 UTC) they hold 12 artifact groups and 238 labels, 236 frictions and two CI findings, with a bullet per part naming its groups, and part 3 carries the live counts. The bullet on the closed F series points to the former-number map in part 3. - The counts table of 2026-09-28 is kept as a dated snapshot rather than refreshed, because a stamped copy of GitHub state stays true as later batches change the counts; its caption says so and points to part 3, and the clusters sentence speaks of that revision. - The introduction no longer carries a friction count, for the same reason. - The Delivery Strategy and the Workflow Checkpoints drop the "orders 1–14" range, so neither goes stale with the next Subissues row. - A Progress Log entry records the round, and `last-updated-utc` matches it. ## Seventh commit: the review audit `docs(pr-reviews): [#2003] add the PR #2366 review audit` Adds `docs/pr-reviews/pr-2366-review/PR-REVIEW.md` from the repository's audit template: R1 (Major), R2 (Minor), R3 (Minor) and R4 (Nit) of review 5468071770, each with its source thread, concern, solution, current-tree verification and resolution reference, and a Processing Log. R1 and R2 are fixed by the sixth commit; R3 needs no change, as the Merge order below explains; R4 is answered by this description. ## Eighth commit: the reply URLs `docs(pr-reviews): [#2003] record the PR #2366 reply URLs`: the audit record's four Reply URL fields, and the Resolution reference of R3 and R4, name the posted replies on the four threads, which are resolved. ## Ninth commit: the provenance rounds, the rebase and the index revision `docs(issues): [#2003] record the provenance rounds and the rebase, and drop the index version` After the rebase onto `develop` `5d05fefdd`, the 185 commits that arrived were checked against every section of the EPIC. Two of the merged pull requests are rounds of the AI-model-provenance discussion under this EPIC: PR #2486 (the decision owner's round on Q1 to Q11) and PR #2502 (the opening author's reply on Q1 and Q11 with a new Q12). Its Outcome is pending, so nothing enters Decisions Recorded on This EPIC, and the EPIC lists discussions only through their recorded Outcomes. The other merged work changes no fact the EPIC states: every path it names still resolves, and the subissue rows, drafts, follow-up owners and open findings hold as written. A Progress Log entry records the rebase and the two rounds, and `last-updated-utc` matches it. The Friction Register names the index revision by its timestamp alone, as review 5505015377 suggests, because no index comment carries a version number; the 2026-10-09 log entry that mentions the version stays as written. ## Tenth commit: the register's index as five comments `docs(issues): [#2003] describe the register's index as five comments at its 2026-10-11 revision` Batch 32 laid the register's index out in five comments on 2026-10-11 at 09:08 UTC ([comment 6107435063](#2003 (comment))). The Friction Register's stamped state line now describes that revision: five comments holding 13 artifact groups and 255 labels, 253 frictions and two CI findings, counted from the five comments' bodies. Each part's bullet names the groups it holds now, with a new bullet for part 5 (the hooks, linters and maintenance skills, and the archiving skill `cleanup-completed-issues`). References links all five parts, and a Progress Log entry records the change with `last-updated-utc` matching it. ## Merge order PR #2494 merged on 2026-10-09 at 11:09 UTC as `686a42f45`, so the Friction Register paragraph saying the PR #2484 retrospective's six proposals are dispositioned in #2278's improvement matrix is true on `develop`. **Rebase.** After review 5505015377 approved this pull request at `5dd98ecd0`, the branch was 185 commits behind `develop`; at the reviewer's request it was rebased onto `develop` `5d05fefdd` with no conflict, and `git range-diff` shows all eight commits equal. The ninth commit records what the rebase brought. ## Validation In a Linux container with the workspace nightly toolchain, at the fixes head `cc6dee1e3` and again at the reply-URL head `5dd98ecd0`, base `1d116fbfa` (this branch's merge base with `develop`): pre-commit profile gate exit 0 (76 s and 130 s); `linter markdown`, `linter cspell`, `linter lychee` exit 0; `frontmatter-validator --all` 19 errors / 4 warnings at each head and 19 / 4 at the base re-measured; `validate-audit-record.py --pr-number 2366` at `5dd98ecd0`, against the review comments captured after the replies were posted: 4 rows, 3 log entries, 0 failures (at `cc6dee1e3` the only failures were the placeholder Reply URL and Resolution reference fields then pending). The issue body was re-derived from this head by the Issue Body Mirror rule (drop the frontmatter, the skill-link marker and the title line, keep the rest byte for byte) and compared with the live body: the only differences are the sixth commit's changes below the frontmatter, nine lines changed and three added (the introduction, the Friction Register paragraph and its four index bullets, two of them new, the F-series bullet, the counts caption, the clusters sentence, the Delivery Strategy sentence, the checkpoint line and the new Progress Log entry). The live body was replaced by the derived text on 2026-10-09 10:43 UTC. At the new head, base `develop` `5d05fefdd`: In a Linux container with the workspace nightly toolchain, at the rebased head `27ddb0ab6`, base `develop` `5d05fefdd` (the merge base): pre-commit profile gate exit 0 (76 s); `linter markdown`, `linter cspell`, `linter lychee` exit 0; `frontmatter-validator --all` 19 errors / 4 warnings at the head and the same at `develop` re-measured; `validate-audit-record.py --pr-number 2366` against the review comments captured on 2026-10-13: 4 rows, 3 log entries, 0 failures; `git merge-tree` against `develop` clean; `git range-diff` against `5dd98ecd0` shows the eight earlier commits equal. The issue body was re-derived from the new head by the Issue Body Mirror rule and compared with the live body, last edited on 2026-10-11. The only differences are the ninth and tenth commits' changes below the frontmatter (the Friction Register sentence and its part bullets, the References line, and the two new Progress Log entries) and one trailing blank line that the live body carries and the rule does not produce. ACKs for top commit: josecelano: ACK 27ddb0a Tree-SHA512: a7b1c468c7e89794c638ef235dd44c28e6c96b5fe0dc5cfd48c144c0423c04072b466f9f0f27a40fe6dfa065ab0ae315e7004c7879ae73c92b2cc0fe54b96eb0
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
EPIC #2278's improvement matrix is the approved decision input for its subissues. The PR #2484 review retrospective proposes six improvements and asks the owner of EPIC #2003 to decide which enter that EPIC or this child EPIC; this change records those decisions, in the matrix's own vocabulary and within the fixed decisions of the Decision Record, which do not change.
Related to #2278
Changes
Four commits and three files:
EPIC.mdandretrospective-improvement-matrix.mdunderdocs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/, and the audit recorddocs/pr-reviews/pr-2494-review/PR-REVIEW.md.caa7818f7docs(issues): [#2278] record the PR #2484 retrospective dispositions in the matrixretrospective-improvement-matrix.md:PR #2484, one per proposal, in the matching sections: the manual pre-push sweep (Adopt, order 5; its tool deferred to order 8 for the audit-body part) and anchoring eachCurrent-tree verificationto a heading or quoted phrase (Adopt, order 5) under Author Verification and Convergence; deferring non-blocking findings after an approval (Defer, order 10) under the proportionate-evidence section; and a new section, PR docs(issues): [#2482] add the sub-EPIC specification for #2482 #2484 Items Left to Other Owners, for the spec-log stamp rule, the restructuring step forcreate-issue, and one session per pull-request branch (Out of scope, EPIC Overhaul: Automation Tools and AI Agent Guardrails #2003 anddocs/agents/orchestration.md).Owner taskcolumns says the new rows name the subissue order directly.related-artifactsgainsdocs/pr-reviews/pr-2484-review/review-retrospective.md, andlast-updated-utcis the time of the decision.EPIC.md:last-updated-utcmatches it.05660e36adocs(issues): [#2278] cover the PR #2484 retrospective in the EPIC's scope and qualify the path sweepAnswers review 5460432014 (F1 and F2):
EPIC.md: the Decision Record maps the proposals of "the PR review retrospectives its introduction lists", so it stays true when another arrives; AC1, its Acceptance Verification row and the References entry "Source retrospectives" cover PR docs(issues): [#2482] add the sub-EPIC specification for #2482 #2484; a Progress Log entry records the change.retrospective-improvement-matrix.md: the PR docs(issues): [#2482] add the sub-EPIC specification for #2482 #2484 sweep row fails only when a tracked file still names a deleted or renamed path as a current reference, keeps references marked historical, and its rationale cites EPIC Refactor Semantic Link and Frontmatter Conventions #2264's distinction between current and historical paths.cf2c60ce3docs(pr-reviews): [#2278] add the PR #2494 review auditdocs/pr-reviews/pr-2494-review/PR-REVIEW.mdrecords F1 and F2 of review 5460432014 (both Minor,FIXED/RESOLVED), each with its source thread, concern, solution, current-tree verification and resolution reference, and a Processing Log.53a49579cdocs(pr-reviews): [#2278] record the PR #2494 reply URLsThe audit record's two Reply URL fields name the posted replies on the F1 and F2 threads.
The #2003 side of the same decisions (the register notes and the new label) travels with PR #2366, the open overhaul of that EPIC's specification.
Merge order
The matrix's new
related-artifactsentry names the PR #2484 retrospective. PR #2484 merged on 2026-10-08 and the retrospective is ondevelop, so the condition is met and this pull request can merge. PR #2366 merges after this one, because its EPIC text cites these matrix rows.Validation
On 2026-10-09 the branch was rebased onto
develop41add51abat the maintainer's request, with no content change:git range-diffshows the four commits as equal, and the head is99ae7d401. At that head, in a Linux container with the workspace nightly toolchain: pre-commit profile gate exit 0 (75 s);linter markdown,linter cspell,linter lycheeexit 0;frontmatter-validator --all19 errors / 4 warnings at the head and atdevelop;validate-audit-record.py --pr-number 24940 failures.In a Linux container with the workspace nightly toolchain at
53a49579c, basedevelop554c47f67: pre-commit profile gate exit 0 (74 s);linter markdown,linter cspell,linter lycheeexit 0;frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 atdevelopre-measured;validate-audit-record.py --pr-number 2494exit 0;git diff --checkclean.