diff --git a/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md b/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md index 1928c6304..e17035e8a 100644 --- a/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md +++ b/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md @@ -235,8 +235,12 @@ examines what outlives them. In brief: Cameron (`da2ce7`), owner of EPIC #2003, answered the six open questions in [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664) (round 1). The answers are transcribed here at his request, for him to confirm against the review -text. Each is marked there as a decision for the EPIC owner to record; none has been recorded in -EPIC #2003, #2264, or #2278 yet. +text. The parts for EPIC #2264 are recorded under its +[Decisions Recorded on This EPIC](../../../issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md#decisions-recorded-on-this-epic) +section, the parts for EPIC #2278 under its +[Decision Record](../../../issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md#decision-record) +section, and the parts for EPIC #2003 in that EPIC's specification by its overhaul pull +request #2366. 1. **The four-aspect frame** is right for sorting proposals. The gates are the layer every aspect's contract is expressed through, not a fifth aspect. What the frame does not yet name is diff --git a/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md b/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md index 917b5d980..4a77f82f5 100644 --- a/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md +++ b/docs/discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md @@ -230,8 +230,10 @@ These are drafts for review. Cameron (`da2ce7`), owner of EPIC #2003 and #2264, answered the four open questions in [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664) (round 1). The answers are transcribed here at his request, for him to confirm against the review -text. Each is marked there as a decision for the EPIC owner to record; none has been recorded in -EPIC #2264 yet. +text. The four answers are recorded in EPIC #2264's specification under its +[Decisions Recorded on This EPIC](../../../issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md#decisions-recorded-on-this-epic) +section, with the Progress Log entry of 2026-10-04 and the order 5 and 7 cells carrying the +scope, as item 4 asks. 1. **Yes, start "Normalize the semantic-link model" with the inventory,** following #2264's own precedent of inventorying frontmatter before fixing its model. The inventory is a tracked diff --git a/docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md b/docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md index aa6683f6e..b2cf0a1f0 100644 --- a/docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md +++ b/docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md @@ -6,7 +6,7 @@ epic: 2003 github-issue: 2264 spec-path: docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md epic-owner: da2ce7 -last-updated-utc: "2026-10-03 20:43" +last-updated-utc: "2026-10-09 10:41" semantic-links: skill-links: - create-issue @@ -343,9 +343,9 @@ Status values: `TODO`, `IN_PROGRESS`, `BLOCKED`, `DONE`. | 2.2 | Frontmatter | [#2281 - Add frontmatter validator command and pre-commit rollout](../../closed/2281-2264-frontmatter-validator-command/ISSUE.md) | Read-only command for explicit paths, `--staged`, and whole-tree validation with NDJSON diagnostics, location-dependent severity, repository-aware checks for strict v1 specs, and a pre-commit step. | DONE | | 3 | Frontmatter | Extend strict profiles and author guidance | Add approved profiles for ADRs, skills, agents, evidence records, and other known classes; keep prose and editor/agent discovery derived from the canonical Rust model. Protect `docs/templates/` against drift from the v1 contract, which #2281 excludes from validation. | TODO | | 4 | Conventions | Split convention ownership and migration policy | Move mixed normative content to clearly owned convention documents without a repository-wide document migration. | TODO | -| 5 | Semantic links | Normalize the semantic-link model | Canonical relation and target types, graph semantics, accepted/rejected fixtures, and compatibility rules represented by the shared Rust model. | TODO | +| 5 | Semantic links | Normalize the semantic-link model | Canonical relation and target types, graph semantics, accepted/rejected fixtures, and compatibility rules represented by the shared Rust model. Starts with a tracked inventory script and its output pinned to a named `develop` commit; targets without a path take one `kind:value` form, and the `issue` sweep recounts its scope at its starting head (decided 2026-10-03; see Decisions Recorded on This EPIC). | TODO | | 6 | Semantic links | Design and implement semantic-link validation | Validate target syntax, type, existence where applicable, uniqueness, and invalid combinations through a replaceable check. | TODO | -| 7 | Path references | Decide path-reference scope and syntax | Decide whether machine-checkable prose paths are semantic links, a separate typed reference, or intentionally outside validation. | TODO | +| 7 | Path references | Decide path-reference scope and syntax | Decide whether machine-checkable prose paths are semantic links, a separate typed reference, or intentionally outside validation. Bounded by the 2026-10-03 decisions: targets without a path take one `kind:value` form, links are validated by the purpose of their field, and the graph reads tracked files only (see Decisions Recorded on This EPIC). | TODO | | 8 | Path references | Specify and implement path-reference validation | If the path-reference scope issue approves validation, define historical handling, exclusions, diagnostics, and staged enforcement. | TODO | | 9 | External links | Classify link importance and checker limitations | Use the #2185 handoff to decide whether link importance belongs in typed metadata, prose policy, or checker configuration. | TODO | | 10 | Integration | Reconcile validators with the #2003 architecture decision | Preserve domain semantics while migrating checks to the selected execution, output, policy, and caching architecture when required. | TODO | @@ -443,6 +443,14 @@ the residual report and the #2185 baseline as its evidence and may conclude that the answer is prose policy, a small typed annotation, or a different checker configuration; the EPIC does not presume which. +## Decisions Recorded on This EPIC + +- **Inventory first (2026-10-03, [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664), [Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md#outcome)).** Order 5, "Normalize the semantic-link model", starts with an inventory, following this EPIC's precedent of inventorying frontmatter before fixing its model. The inventory is a tracked script plus its output pinned to a named `develop` commit; it classifies the corpus by source document class and target kind, including the free-form values and the 48 dropped `issue` entries as candidate target kinds. +- **One `kind:value` form for targets without a path (2026-10-03, [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664), [Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md#outcome)).** In direction, every target without a path takes one `kind:value` form. A plain scalar such as `issue:2264` loads as written and matches this EPIC's candidate syntax, and the migration is mechanical even for the 48 damaged entries, whose numbers survive as YAML comments. The sweep's specification recounts its scope at the head it starts from, because the register records 53 entries in 34 files where the discussion and its review find 48 in 30. This changes the frozen v1 reference convention, which this EPIC reserves to its semantic-link subissues. +- **Tracked files only (2026-10-03, [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664), [Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md#outcome)).** The graph that gates and agents rely on reads tracked files only. GitHub-hosted records may enter as a separately derived data set stamped with its capture time; if the friction register's links are to feed the graph, a tracked, dated export serves it, as `docs/external-snapshots/` does for external sources. +- **Links validated by the purpose of their field (2026-10-03, [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664), [Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md#outcome)).** ADR links are context links, validated leniently, and the convention's existing rule is enforced: issue specifications are referenced by number, which would have kept three of the five broken ADR links valid. Historical records (ADRs, PR-review audits, closed specifications) carry context links checked for syntax only. The change-impact field definition in `docs/skills/semantic-skill-link-convention.md` is split from a context field, or qualified, as part of this EPIC's convention work. +- **Where these decisions are recorded (2026-10-03, [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664), [semantic-linking Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md#outcome), [goals-and-boundaries Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md#outcome)).** In this specification: this section, the Progress Log entry of 2026-10-04, and the Expected output cells of orders 5 and 7, which carry the scope changes. The four-aspect frame and the discussions convention are recorded on #2003 by its overhaul pull request #2366, and the audit-record contract on #2278; the discussions are not cited in place of these records. + ## Open Questions - Which existing frontmatter variations are intentional compatibility cases, and which are errors @@ -454,11 +462,11 @@ annotation, or a different checker configuration; the EPIC does not presume whic repository-aware validation? - Which generated schema format best serves editors and AI agents without becoming a second source of truth? -- Should semantic-link target types be URI-like strings, YAML maps, or both? +- Should semantic-link target types be URI-like strings, YAML maps, or both? *Answered in direction (2026-10-03):* one `kind:value` string form for every target without a path; see Decisions Recorded on This EPIC. - Should a file path be represented as `path:...`, a typed YAML object, or a plain string in selected fields? -- Which references should be considered knowledge-graph edges, and which are only validation aids? -- Should historical closed issues and PR review records be exempt from new reference syntax? +- Which references should be considered knowledge-graph edges, and which are only validation aids? *Answered in part (2026-10-03):* the graph that gates and agents rely on reads tracked files only, and GitHub-hosted records enter only as a dated derived export; see Decisions Recorded on This EPIC. +- Should historical closed issues and PR review records be exempt from new reference syntax? *Answered in part (2026-10-03):* historical records carry context links checked for syntax only, and issue specifications are referenced by number; see Decisions Recorded on This EPIC. - How should comments in Rust, shell, TOML, YAML, and Dockerfiles represent typed links without harming the host language parser? - Which OKF principles should be copied directly, adapted, or rejected for a repository whose @@ -626,6 +634,7 @@ For each completed subissue, the default completion policy is: - 2026-09-30 10:22 UTC - GitHub Copilot - Added the unordered Draft Subissue Proposals list with the maintainer-requested draft for multiple related PRs in issue frontmatter; its order in the table is left to the EPIC's planner. +- 2026-10-04 19:18 UTC - da2ce7 - Recorded the semantic-linking discussion's outcome and the goals-and-boundaries parts that name this EPIC (PR #2428, review 5400754664) under Decisions Recorded on This EPIC; marked the Open Questions they answer and noted the scope of orders 5 and 7 in the subissue table. ## Risks and Trade-offs diff --git a/docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md b/docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md index 7b4eff8f3..231b2d573 100644 --- a/docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md +++ b/docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md @@ -6,7 +6,7 @@ epic: 2003 github-issue: 2278 spec-path: docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md epic-owner: da2ce7 -last-updated-utc: "2026-10-08 17:28" +last-updated-utc: "2026-10-09 10:41" semantic-links: skill-links: - create-issue @@ -97,6 +97,13 @@ Decisions the matrix fixes and that subissues must respect: - the audit validator validates the audit body only; frontmatter and `review-finding:` target existence belong to EPIC #2264. +Decisions recorded from the PR #2428 discussions (2026-10-04; [goals-and-boundaries Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md#outcome), [review 5400754664](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5400754664) of 2026-10-03): + +- the audit record is contract: a gate checks it from tracked bytes and GitHub state, whatever tool produced it; +- copies of GitHub state: the record's identifiers stay, and every state it copies is stamped with its capture time or checked; that is the premise of the validator rows, and the record's thread states, which copy review-thread resolution, are already checked against thread captures; +- `epic-owner` copies the GitHub assignee: PR #2428 repaired it on this EPIC and #2264, and it drifts again unless a check is added or the field defers to the assignee; +- the specifications-and-rationale outcome sends no work to this EPIC: marking the issue template's optional and conditional sections is #2003's planning-template follow-up ([Outcome](../../../discussions/2003-overhaul-guardrails-and-automation/20261003-specifications-and-rationale/README.md#outcome), [review 5402713128](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5402713128), round 3). + ## Scope ### In Scope @@ -269,6 +276,7 @@ requests where possible; a fixture is used only when no real review produced the - 2026-09-26 09:46 UTC - GitHub Copilot - PR #2339 merged as `a20e8f3a` and closed #2333; order 4 is `DONE`, its specification is archived under `docs/issues/closed/`, and AC2 is `DONE`, completing Phase 1. Three review findings on PR #2339 were still unprocessed at merge; with maintainer approval () they are handled in a follow-up PR from `develop`, which also extends `process-pr-review`'s post-merge rule to findings unprocessed at merge. Orders 5 and 6 are unblocked. - 2026-09-26 13:33 UTC - GitHub Copilot - Maintainer set the order after Phase 1: order 6 next, then order 5 once PR #2344 merges and #2347 triage settles which audit-contract findings belong to it, because orders 5, #2344, and #2347 all edit `process-pr-review`. Maintainer approved the order 6 specification with the `no-stdout-result` output migration; created and linked subissue #2349 and moved its specification to `docs/issues/open/2349-2278-contract-checker-evidence-boundary/`. Spec-only PR pending. For order 7, #2266 recorded its placement decision (`contrib/dev-tools/checks/`, `cargo run --package`, `no-stdout-result`), so it is unblocked; the maintainer approved three decisions for its specification: keep `no-stdout-result` and record dropping the Python prototype's stdout JSON summary as a deliberate parity deviation; do not wait for #2281, adopting its NDJSON diagnostic catalog if it has merged when order 7 starts; and no pre-commit integration, because the validator needs `gh` and network access. - 2026-09-28 10:08 UTC - GitHub Copilot - #2347 triage settled which audit-contract findings belong where. None goes to order 5. `review-finding:pr-2313-f4`, `-f5`, `-f6`, `-f7`, and `-f9` go to the new order 11, which the maintainer approved; created and linked subissue #2362. `review-finding:pr-2300-f10` goes to order 8 (T3 approval ). +- 2026-10-04 19:18 UTC - da2ce7 - Recorded the audit-record decisions of the PR #2428 goals-and-boundaries discussion under Decision Record (review 5400754664): the record as contract, stamped-or-checked copies of GitHub state, and `epic-owner`; the specifications discussion (review 5402713128) sends no work to this EPIC. - 2026-10-08 16:50 UTC - da2ce7 - Recorded the six proposals of the PR #2484 review retrospective in the matrix: items 1 (the manual sweep) and 2 adopted for order 5, item 1's tool deferred to order 8, item 3 deferred to order 10, and items 4 to 6 left to EPIC #2003's register. No fixed decision of the Decision Record changes. - 2026-10-08 17:28 UTC - da2ce7 - Answered review 5460432014 on PR #2494: the Decision Record, AC1 and References now cover the PR #2484 retrospective, and the matrix's pre-push sweep fails only on a current reference to a deleted or renamed path, allowing references marked historical. diff --git a/docs/pr-reviews/pr-2434-review/PR-REVIEW.md b/docs/pr-reviews/pr-2434-review/PR-REVIEW.md new file mode 100644 index 000000000..8151911a1 --- /dev/null +++ b/docs/pr-reviews/pr-2434-review/PR-REVIEW.md @@ -0,0 +1,153 @@ +--- +semantic-links: + skill-links: + - process-pr-review + related-artifacts: + - .github/skills/dev/pr-reviews/process-pr-review/SKILL.md + - 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 + - docs/discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md +--- + + + +# PR #2434 Review Audit + +Source: pull-request reviews and inline review threads for . + +## Ownership + +The PR author owns this tracked audit record. Reviewers, including repository review agents, +deliver findings through GitHub and have no repository-artifact obligation. + +- Post-merge workflow approval: N/A + +## Status Values + +- Relationship: `ORIGINAL`, `RE_RAISE_OF:` +- Disposition: `FIXED`, `NO_ACTION`, `SUPERSEDED`, `FOLLOW_UP` +- Thread state: `OPEN`, `RESOLVED`, `NON_RESOLVABLE`, `SUPERSEDED`. `OPEN` applies prospectively + to audits created or updated for approved follow-up work; historical audits remain valid without + bulk migration. +- Severity: `Blocker`, `Major`, `Minor`, `Nit`, `Suggestion`; append `(inferred)` when derived + from free prose. +- Author class: `Copilot`, `Human`, `Unknown` +- Category: `link-integrity`, `formatting`, `metadata`, `testing`, `correctness`, + `documentation`, `maintainability`, `security`, `other` +- An outdated thread whose concern was fixed is `FIXED`/`RESOLVED`, even when GitHub marks the + original thread outdated after the push. For in-PR feedback, use `NO_ACTION`/`SUPERSEDED` only + for a duplicate, superseded, or no-change concern. A post-merge `NO_ACTION` requires maintainer + approval to decline the follow-up work. + +## Findings + +Copilot review 5407866771 (round 1, state `COMMENTED`, submitted 2026-10-04 19:48 UTC on the PR's opening head, "Balanced" effort) left one inline comment. Its body is an overview ("Changes recommended") that restates the inline finding, so it creates no additional finding. + +The comment opens with an explicit `[Major][F1]` bracket, so the row records `Major` from the bracket, and Copilot's ID is the audit-local ID. The overview's badge reads "Low severity"; the bracket governs, and it is what the validator checks. The record is committed after the fix and before the reply is posted: the thread state is `RESOLVED`, the value the skill prescribes for a concern a change fixed, and the Reply URL keeps the template's placeholder until the posted reply's URL is recorded. + +Review 5467876260 (round 2, josecelano, state `COMMENTED`, submitted 2026-10-09 08:50 UTC on head `d26ba356c`) reports no blocking issues and left four inline comments, each opening with an explicit bracket: `[Minor][R1]`, `[Minor][R2]`, `[Nit][R3]` and `[Nit][R4]`. The rows record those severities and keep the reviewer's IDs as the audit-local IDs. Its body lists the checks it ran and restates the four findings, so it creates no additional finding. As in round 1, the rows are committed after the fixes and before the replies are posted: the thread state is `RESOLVED`, the value the threads take when they are resolved after the push, and each Reply URL keeps the template's placeholder until the posted reply's URL is recorded. + +| Finding ID | Review finding reference | Author class | Severity | Category | Relationship | Disposition | Thread state | +| ---------- | ------------------------ | ------------ | -------- | -------- | ------------ | ----------- | ------------ | +| F1 | `review-finding:pr-2434-f1` | Copilot | Major | documentation | ORIGINAL | FIXED | RESOLVED | +| R1 | `review-finding:pr-2434-r1` | Human | Minor | documentation | ORIGINAL | FIXED | RESOLVED | +| R2 | `review-finding:pr-2434-r2` | Human | Minor | documentation | ORIGINAL | FIXED | RESOLVED | +| R3 | `review-finding:pr-2434-r3` | Human | Nit | formatting | ORIGINAL | FIXED | RESOLVED | +| R4 | `review-finding:pr-2434-r4` | Human | Nit | documentation | ORIGINAL | FIXED | RESOLVED | + +## Finding Details + +### F1 - The source Outcomes still say nothing is recorded and lack their backlinks + +- PR number: 2434 +- Source review ID: 5407866771 +- Reviewer finding ID: N/A +- Source URL: +- Concern: "Recording the canonical decisions here leaves both source Outcomes contradictory and without the required backlink: the semantic-linking Outcome still says nothing has been recorded in #2264 and explicitly requires this entry to be linked, while goals-and-boundaries still says nothing has been recorded in #2264 or #2278 and requires Outcomes to link their canonical records. Update both discussion Outcomes in this PR so their status and navigation remain accurate." +- Solution: Replaced each Outcome's status sentence, which said that none of its answers was recorded in an EPIC, with one naming where they are recorded. The semantic-linking Outcome links #2264's `Decisions Recorded on This EPIC` section and names the Progress Log entry of 2026-10-04 and the order 5 and 7 cells, as its item 4 asks. The goals-and-boundaries Outcome links that section and #2278's `Decision Record`, and names the overhaul pull request #2366 for the #2003 parts, because `develop` does not yet have that section; PR #2366 replaces the clause with a link when it lands. The discussions convention allows the edit: a discussion records its outcome and links the canonical document that carries it (`docs/discussions/AGENTS.md`, step 3), and is afterwards edited only to repair links. No other text changed. +- Current-tree verification: `git grep -n -e "none has been recorded" -e "decisions-recorded-on-this-epic" -e "EPIC.md#decision-record" -- docs/discussions/2003-overhaul-guardrails-and-automation` at the branch head prints three lines, the new links at `20261003-goals-and-boundaries/README.md:239` and `:241` and `20261003-semantic-linking-knowledge-graph/README.md:234`, and no "none has been recorded"; each link resolves from its README's folder, anchor included; the fix commit's diff changes only the two status sentences. +- Resolution reference: `docs(discussions): link the #2264 and #2278 records from their Outcomes` +- Follow-up PR URL: N/A +- Reply URL: + +### R1 - The #2264 record calls the #2003 parts recorded before PR #2366 lands + +- PR number: 2434 +- Source review ID: 5467876260 +- Reviewer finding ID: N/A +- Source URL: +- Concern: "This bullet says the #2003 parts are already recorded, but they are only in the open PR #2366." On `develop`, the #2003 EPIC has no `Decisions Recorded on This EPIC` section and does not mention the four-aspect frame, while the goals-and-boundaries Outcome edited in this pull request already hedges "by its overhaul pull request #2366". +- Solution: The sentence names the pull request that records the #2003 parts, in the reviewer's wording, which matches the Outcome's hedge and stays true once PR #2366 merges. No other text changed. +- Current-tree verification: in `docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md`, under "Decisions Recorded on This EPIC", the bullet "Where these decisions are recorded" reads "convention are recorded on #2003 by its overhaul pull request #2366, and the audit-record contract on #2278"; the phrase "convention are recorded on #2003, and" no longer occurs. +- Resolution reference: `docs(issues): [#2264] [#2278] hedge the #2003 record reference and cite the round-3 review` +- Follow-up PR URL: N/A +- Reply URL: + +### R2 - The specifications bullet and its log entry cite the round-1 review + +- PR number: 2434 +- Source review ID: 5467876260 +- Reviewer finding ID: N/A +- Source URL: +- Concern: "The fourth bullet comes from review 5402713128 (round 3), but this lead-in cites only review 5400754664." The specifications-and-rationale Outcome cites review 5402713128 (round 3, answer 4), and the Progress Log entry of 2026-10-04 19:18 UTC repeats the round-1 attribution. +- Solution: The fourth bullet cites review 5402713128 beside its own Outcome link, because the lead-in's review stays correct for the other three bullets, and the Progress Log entry names that review for the specifications discussion. +- Current-tree verification: in `docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/EPIC.md`, under "Decision Record", the bullet "the specifications-and-rationale outcome sends no work to this EPIC" ends "[review 5402713128](https://github.com/torrust/torrust-tracker/pull/2428#pullrequestreview-5402713128), round 3)."; under "Progress Log", the 2026-10-04 19:18 UTC entry reads "the specifications discussion (review 5402713128) sends no work to this EPIC"; `docs/discussions/2003-overhaul-guardrails-and-automation/20261003-specifications-and-rationale/README.md`, under "Outcome", cites "[review 5402713128]". +- Resolution reference: `docs(issues): [#2264] [#2278] hedge the #2003 record reference and cite the round-3 review` +- Follow-up PR URL: N/A +- Reply URL: + +### R3 - The #2264 Progress Log entry lacks its final period + +- PR number: 2434 +- Source review ID: 5467876260 +- Reviewer finding ID: N/A +- Source URL: +- Concern: "This Progress Log entry has no final period." The adjacent entries, and the matching #2278 entry added in this pull request, end with one. +- Solution: The entry ends with a period; its text is otherwise unchanged. +- Current-tree verification: in `docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md`, under "Progress Log", the 2026-10-04 19:18 UTC entry ends "noted the scope of orders 5 and 7 in the subissue table.". +- Resolution reference: `docs(issues): [#2264] [#2278] hedge the #2003 record reference and cite the round-3 review` +- Follow-up PR URL: N/A +- Reply URL: + +### R4 - The Processing Log does not record the F1 thread's resolution + +- PR number: 2434 +- Source review ID: 5467876260 +- Reviewer finding ID: N/A +- Source URL: +- Concern: "The Processing Log never records the F1 thread being resolved." The 19:59 entry says the thread is resolved after the gate of record passes, the thread is resolved on GitHub, and no later entry records it. +- Solution: An appended entry records the resolution: the F1 thread was resolved immediately after reply 4179101218 was posted at 2026-10-04 19:59:32 UTC, in the same action. The entry carries the time it was recorded, and names the event's own time in its text, because the log is append-only and its entries must stay chronological. +- Current-tree verification: in this record, under "Processing Log", the entry of 2026-10-09 10:42 UTC reads "the F1 thread was resolved immediately after reply 4179101218 was posted at 2026-10-04 19:59:32 UTC". +- Resolution reference: `docs(pr-reviews): [#2264] [#2278] record the maintainer's review of PR #2434` +- Follow-up PR URL: N/A +- Reply URL: + +## Processing Log + +- 2026-10-04 19:30 UTC - PR #2434 opened with two commits, `docs(issues): [#2264] record the semantic-linking and goals discussion outcomes` and `docs(issues): [#2278] record the audit-record decisions from the discussions`. +- 2026-10-04 19:48 UTC - Copilot review 5407866771 (`COMMENTED`, "Changes recommended") left one inline comment, 4179060807, bracketed `[Major][F1]`, on `docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md` line 448; its overview restates that finding, so the review normalizes to F1 alone. The thread capture shows one thread, `resolved=false`. +- 2026-10-04 19:57 UTC - Re-derived F1 at the branch head: both Outcome sections still said none of their answers was recorded. Committed the fix as `docs(discussions): link the #2264 and #2278 records from their Outcomes`. +- 2026-10-04 19:57 UTC - Recorded this audit with F1 `FIXED`/`RESOLVED`. The reply is prepared and is posted after the fix and this record are pushed; its URL replaces the Reply URL placeholder then, and the audit validator runs in the gate of record. +- 2026-10-04 19:59 UTC - Pushed the fix and this record; replied on the F1 thread (reply 4179101218) and recorded its URL; the thread is resolved after the gate of record passes. +- 2026-10-04 20:00 UTC - The Docs Lint workflow failed on the pushed head: cspell flagged `backlink` in F1's quoted concern. Added the word to `project-words.txt`; the concern text is the reviewer's and is not reworded. +- 2026-10-09 08:50 UTC - Review 5467876260 (josecelano, `COMMENTED`, on head `d26ba356c`) reported no blocking issues and left four inline comments, bracketed `[Minor][R1]`, `[Minor][R2]`, `[Nit][R3]` and `[Nit][R4]`; its body restates them with the checks it ran, so the review normalizes to R1 to R4. The thread capture shows the four new threads `resolved=false` and the F1 thread `resolved=true`. +- 2026-10-09 10:41 UTC - Re-derived R1 to R3 at the branch head and fixed them in one commit, `docs(issues): [#2264] [#2278] hedge the #2003 record reference and cite the round-3 review`. Both EPICs' `last-updated-utc` is that minute; neither file logs corrections of its own text, so no Progress Log entry was added. +- 2026-10-09 10:42 UTC - Recorded the F1 thread's resolution, which the entry of 2026-10-04 19:59 UTC expected after the gate of record: the F1 thread was resolved immediately after reply 4179101218 was posted at 2026-10-04 19:59:32 UTC, in the same action. Recorded R1 to R4 `FIXED`/`RESOLVED`; the replies are drafted for posting after the push, and their URLs replace the Reply URL placeholders then. + +## Completion Rules + +- Re-derive the reply claim against the current tree before replying or resolving a thread. +- Reply on every resolvable thread before resolving it. +- For an outdated thread whose concern was fixed, record `Disposition=FIXED` and + `Thread state=RESOLVED`, even if GitHub marks the thread outdated after the push. For a + duplicate, superseded, or no-change in-PR thread, reply exactly + `Superseded by : .`, record `Disposition=NO_ACTION` and + `Thread state=SUPERSEDED`, then resolve it. A post-merge `NO_ACTION` requires maintainer + approval to decline the follow-up work. +- A consolidated PR conversation response may cover multiple review rounds only when it names + every review ID and every finding ID with its disposition and resolution reference. Record its + durable URL in each related row. +- Cite a fix by its unique Conventional Commit subject or durable reply URL, never by a branch SHA + that can change after a rebase. +- Refresh review threads using GraphQL and confirm that no unresolved actionable thread remains. diff --git a/project-words.txt b/project-words.txt index 49fddc00b..f81ef7d26 100644 --- a/project-words.txt +++ b/project-words.txt @@ -157,6 +157,7 @@ autoclean autolinks automock autoremove +backlink backlinks backpressure bdecode