Skip to content

docs(issues): [#2003] overhaul the EPIC specification after the hand-off - #2366

Merged
josecelano merged 10 commits into
torrust:developfrom
da2ce7:2003-overhaul-epic-spec
Oct 13, 2026
Merged

josecelano merged 10 commits into
torrust:developfrom
da2ce7:2003-overhaul-epic-spec

Conversation

@da2ce7

@da2ce7 da2ce7 commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

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). 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.

Copilot AI lite review requested due to automatic review settings September 28, 2026 16:48

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Unresolved documentation inconsistencies include stale statuses, paths, counts, scope, and history details.

Review effort: Lite
Findings: 3 Low severity

Open (3)
What changed in this PR

Overhauls EPIC #2003 with updated ownership, subissues, decisions, friction-register evidence, progress history, and verification guidance.

Changes:

  • Updates frontmatter, ownership, and semantic links.
  • Adds subissue tracking, follow-ups, risks, and progress entries.
  • Documents friction-register rules, issue mirroring, and references.
File Description
docs/​issues/​open/​2003-overhaul-guardrails-and-automation/​EPIC.md Expanded EPIC specification and tracking data.

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

Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md Outdated
Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md Outdated
Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md Outdated
@josecelano

Copy link
Copy Markdown
Member

@da2ce7, for when you record the #2003 decisions: PR #2428 is merged into develop. Its Outcome sections hold your answers, which you confirmed in review 5407197495 (round 4):

  • docs/discussions/2003-overhaul-guardrails-and-automation/20261003-goals-and-boundaries/README.md: your round-1 answers on the four-aspect frame, the gates, contract versus technique, coordination claims, copies of GitHub state, and the discussions convention. Several are for this EPIC's "Decisions Recorded on This EPIC".
  • docs/discussions/2003-overhaul-guardrails-and-automation/20261003-semantic-linking-knowledge-graph/README.md: the answers for Refactor Semantic Link and Frontmatter Conventions #2264.
  • docs/discussions/2003-overhaul-guardrails-and-automation/20261003-specifications-and-rationale/README.md: your round-3 answers, revised in round 4 to point to docs/issues/drafts/adopt-prose-tests-as-executable-specification/ISSUE.md.

Each Outcome says none of these is recorded in an EPIC yet. Recording them here, in #2264 and in #2278, and linking each record back to its Outcome, is yours. No change to this PR is asked.

@da2ce7

da2ce7 commented Oct 4, 2026

Copy link
Copy Markdown
Contributor Author

@josecelano, recorded, in three places:

Each record links its Outcome by path; the Outcomes themselves are not edited, so the link back from each Outcome to its record is the discussions' own follow-up once these land.

da2ce7 added a commit to da2ce7/torrust-tracker that referenced this pull request Oct 4, 2026
…m their Outcomes

Both Outcome sections said none of their answers was recorded in an EPIC,
which stops being true once this pull request records them in EPICs torrust#2264
and torrust#2278. The discussions convention has a discussion record its outcome
and link the canonical document that carries it (docs/discussions/AGENTS.md,
step 3), and the goals-and-boundaries Outcome itself records that a
discussion is afterwards edited only to repair links. Each status sentence
now names where its answers are recorded instead: the semantic-linking
Outcome links the Decisions Recorded on This EPIC section of EPIC torrust#2264, and
the goals-and-boundaries Outcome links that section and the Decision Record
of EPIC torrust#2278. The EPIC torrust#2003 parts are on its overhaul pull request torrust#2366,
which replaces that clause with a link when it lands. No other text changes.

This fixes review-finding:pr-2434-f1 from Copilot review 5407866771.
@da2ce7
da2ce7 force-pushed the 2003-overhaul-epic-spec branch 2 times, most recently from f311afc to fa18f45 Compare October 8, 2026 12:07
@da2ce7

da2ce7 commented Oct 8, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto develop at 1d116fbfa (the #2485 merge). Since this branch's previous base, 050726d46, the maintainer changed the EPIC twice on develop: #2473 became row 15 of the Subissues table and was then marked done, with two Progress Log entries and last-updated-utc set to "2026-10-08 09:12". Each of my four commits conflicted with those lines.

  • Head f311afc0f811965ac5a4225239dc0e83aff28e89 → fa18f45edb33c1686586b45564578fdef58e6e91, four commits, same order and messages; only the EPIC file changes.
  • git range-diff 050726d46..f311afc0f 1d116fbfa..fa18f45edb33c1686586b45564578fdef58e6e91 marks all four commits !, and each differs only by those maintainer lines: no line of my own changes moved.
  • Resolution: row 15 follows row 14 in my table's form: the issue title and path as on develop, DONE in the Status column rather than in the title, and under Notes the maintainer's description followed by its dependency as the last sentence. The two log entries follow my last entry with their words unchanged, each on one line. last-updated-utc takes the later value, "2026-10-08 09:12", and the rebase adds no log entry of its own.
  • Gates at this head on the compute pod, base develop 1d116fbfa: pre-commit profile gate exit 0 (79 s); linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all with the same repository-wide counts as develop (19 errors, 4 warnings on unrelated specs); the eleven relative links in the EPIC resolve at this head. The Overhaul: Automation Tools and AI Agent Guardrails #2003 issue body is re-derived from this head.

Ready for re-review.

@da2ce7

da2ce7 commented Oct 8, 2026

Copy link
Copy Markdown
Contributor Author

One commit added on top of fa18f45ed: e0c938d668986ac59310b8002257663d1b9c45d8, docs(issues): [#2003] record the PR #2484 retrospective dispositions. The PR #2484 review retrospective asked the owner of this EPIC to decide which of its six proposals enter this EPIC or #2278; the Friction Register gains a dated paragraph recording where each lands (the author-side items in #2278's improvement matrix, the spec-log stamp rule and the restructuring step as notes on their existing labels, one session per pull-request branch as a new label against the orchestration guide), with a Progress Log entry and last-updated-utc set to the decision's time.

  • Five commits now, the four reviewed ones unchanged (git range-diff 1d116fbfa..fa18f45ed 1d116fbfa..e0c938d66 marks them =); only the EPIC file changes.
  • Gates at this head on the compute pod, base develop 1d116fbfa (this branch's merge base; git merge-tree against develop at 554c47f67 is clean): pre-commit profile gate exit 0 (76 s); linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all with the same repository-wide counts as the base (19 errors, 4 warnings on unrelated specs). The Overhaul: Automation Tools and AI Agent Guardrails #2003 issue body is re-derived from this head.
  • The Strengthen PR review author self-audit and evidence generation #2278 side of the same decisions is a separate pull request on that EPIC's matrix.

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 josecelano self-assigned this Oct 9, 2026

@josecelano josecelano left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Requesting changes for R1 and R2. Otherwise, the merged result passes linter markdown, cspell and lychee, and frontmatter-validator --all reports nothing for this EPIC. Every cited path resolves, the subissue statuses match GitHub, and the issue #2003 body matches the derived file (only one blank line differs). Please also make sure #2494 merges before this PR (R3).

Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md Outdated
Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md Outdated
Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md
Comment thread docs/issues/open/2003-overhaul-guardrails-and-automation/EPIC.md Outdated
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.
da2ce7 added a commit to da2ce7/torrust-tracker that referenced this pull request Oct 9, 2026
da2ce7 added a commit to da2ce7/torrust-tracker that referenced this pull request Oct 9, 2026
…cord reference and cite the round-3 review

The torrust#2264 record said the four-aspect frame and the discussions
convention are recorded on torrust#2003, which holds only through that EPIC's
open overhaul pull request torrust#2366; it now names that pull request, as
the goals-and-boundaries Outcome does. The torrust#2278 record attributed its
specifications-and-rationale bullet to review 5400754664, while that
Outcome cites review 5402713128 (round 3); the bullet and its Progress
Log entry now cite it. The torrust#2264 Progress Log entry gains the final
period its neighbours have.
josecelano added a commit that referenced this pull request Oct 9, 2026
…dispositions in the matrix

99ae7d4 docs(pr-reviews): [#2278] record the PR #2494 reply URLs (Cameron Garnham)
3ab7f90 docs(pr-reviews): [#2278] add the PR #2494 review audit (Cameron Garnham)
17a83b7 docs(issues): [#2278] cover the PR #2484 retrospective in the EPIC's scope and qualify the path sweep (Cameron Garnham)
27ead58 docs(issues): [#2278] record the PR #2484 retrospective dispositions in the matrix (Cameron Garnham)

Pull request description:

  ## 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.md` and `retrospective-improvement-matrix.md` under `docs/issues/open/2278-2003-strengthen-pr-review-author-self-audit/`, and the audit record `docs/pr-reviews/pr-2494-review/PR-REVIEW.md`.

  ### `caa7818f7` docs(issues): [#2278] record the PR #2484 retrospective dispositions in the matrix

  `retrospective-improvement-matrix.md`:

  - Six rows with source `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 each `Current-tree verification` to 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 #2484 Items Left to Other Owners, for the spec-log stamp rule, the restructuring step for `create-issue`, and one session per pull-request branch (Out of scope, EPIC #2003 and `docs/agents/orchestration.md`).
  - The introduction names the fourth source retrospective, and the note on the `Owner task` columns says the new rows name the subissue order directly.
  - `related-artifacts` gains `docs/pr-reviews/pr-2484-review/review-retrospective.md`, and `last-updated-utc` is the time of the decision.

  `EPIC.md`:

  - Rows 5, 8 and 10 of the Subissues table name what they gained from the retrospective.
  - A Progress Log entry records the triage; `last-updated-utc` matches it.

  ### `05660e36a` docs(issues): [#2278] cover the PR #2484 retrospective in the EPIC's scope and qualify the path sweep

  Answers 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 #2484; a Progress Log entry records the change.
  - `retrospective-improvement-matrix.md`: the PR #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 #2264's distinction between current and historical paths.

  ### `cf2c60ce3` docs(pr-reviews): [#2278] add the PR #2494 review audit

  `docs/pr-reviews/pr-2494-review/PR-REVIEW.md` records 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.

  ### `53a49579c` docs(pr-reviews): [#2278] record the PR #2494 reply URLs

  The 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-artifacts` entry names the PR #2484 retrospective. PR #2484 merged on 2026-10-08 and the retrospective is on `develop`, 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 `develop` `41add51ab` at the maintainer's request, with no content change: `git range-diff` shows the four commits as equal, and the head is `99ae7d401`. 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 lychee` exit 0; `frontmatter-validator --all` 19 errors / 4 warnings at the head and at `develop`; `validate-audit-record.py --pr-number 2494` 0 failures.

  In a Linux container with the workspace nightly toolchain at `53a49579c`, base `develop` `554c47f67`: 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 19 / 4 at `develop` re-measured; `validate-audit-record.py --pr-number 2494` exit 0; `git diff --check` clean.

ACKs for top commit:
  josecelano:
    ACK 99ae7d4

Tree-SHA512: d17f6b9f734071cfd09ea8279a16d61d4177898b72d262ac887a479f9556399a7238170c9dec65326f181c3dfd2e0017405d70e5495803048036ca6260dd72e9
da2ce7 added a commit to da2ce7/torrust-tracker that referenced this pull request Oct 9, 2026
…m their Outcomes

Both Outcome sections said none of their answers was recorded in an EPIC,
which stops being true once this pull request records them in EPICs torrust#2264
and torrust#2278. The discussions convention has a discussion record its outcome
and link the canonical document that carries it (docs/discussions/AGENTS.md,
step 3), and the goals-and-boundaries Outcome itself records that a
discussion is afterwards edited only to repair links. Each status sentence
now names where its answers are recorded instead: the semantic-linking
Outcome links the Decisions Recorded on This EPIC section of EPIC torrust#2264, and
the goals-and-boundaries Outcome links that section and the Decision Record
of EPIC torrust#2278. The EPIC torrust#2003 parts are on its overhaul pull request torrust#2366,
which replaces that clause with a link when it lands. No other text changes.

This fixes review-finding:pr-2434-f1 from Copilot review 5407866771.
da2ce7 added a commit to da2ce7/torrust-tracker that referenced this pull request Oct 9, 2026
…cord reference and cite the round-3 review

The torrust#2264 record said the four-aspect frame and the discussions
convention are recorded on torrust#2003, which holds only through that EPIC's
open overhaul pull request torrust#2366; it now names that pull request, as
the goals-and-boundaries Outcome does. The torrust#2278 record attributed its
specifications-and-rationale bullet to review 5400754664, while that
Outcome cites review 5402713128 (round 3); the bullet and its Progress
Log entry now cite it. The torrust#2264 Progress Log entry gains the final
period its neighbours have.
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
josecelano
josecelano previously approved these changes Oct 13, 2026

@josecelano josecelano left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved at 5dd98ecd0. R1, R2 and R4 are fixed as described, and I accept R3's no-change answer now that PR #2494 has merged (2026-10-09 11:09 UTC), so the sentence about #2278's improvement matrix is true on develop.

Before merge, please rebase onto current develop again. The branch is 185 commits behind, and develop now has further #2003 work: the AI model provenance discussion rounds (PRs #2486 and #2502). After the rebase, please check whether the EPIC needs any of that (Decisions Recorded on This EPIC, Progress Log, last-updated-utc), then re-run validation at the new head and re-derive the #2003 issue body under the Issue Body Mirror rule. #2003 was last updated on 2026-10-11, after your last re-derivation. If the rebase changes only the base, this approval stands; I'll re-check the new head before merging.

Non-blocking: "index v31" in the Friction Register can't be traced. No index comment carries a version number, and GitHub's edit counts for the four comments are 33, 25, 11 and 2. The timestamp alone identifies the revision, so consider dropping "v31".

da2ce7 added 10 commits October 13, 2026 16:24
…e hand-off

This revision also carries the follow-up correction the PR review found (the torrust#2281 status and the register count) and, from develop, the torrust#2375 row and the owner metadata that landed while the branch was open.
…ecord the torrust#2375 scheduling

Two draft sub-issue specifications landed on develop under this EPIC: the mining of AI agent memories (from PR torrust#2388) and the separation of the AI-harness Cargo workspace (from PR torrust#2385). The Subissues table lists only created issues, so a "Drafts Awaiting Issues" subsection now places each draft in the plan: the memories draft proceeds under the Scope exception and feeds Proposed Subissues 1 and 2; the harness-workspace draft is an implementation subissue gated on the five decisions it lists, which the EPIC records before its issue is created. The order 14 row (torrust#2375) states the scheduling position: implementation starts after a fresh review of the spec against the current tree, which settles the two open points from the torrust#2377 review, and the name check's placement follows torrust#2264. The Decisions section carries the placement and the progress log the edit.
Records the Outcome sections of the goals-and-boundaries and specifications-and-rationale discussions (docs/discussions/2003-overhaul-guardrails-and-automation/, merged in PR torrust#2428) under Decisions Recorded on This EPIC: the four-aspect frame, the gates as the enforcement layer, contract versus technique, coordination claims, copies of GitHub state, the discussions convention, and the four specifications answers as revised in round 4. Each decision links its Outcome and names the review that holds it. A Progress Log entry and the update stamp follow; the semantic-linking outcome and the per-EPIC parts are recorded on torrust#2264 and torrust#2278.

Related to torrust#2003
… under the EPIC

PR torrust#2437 moved the prose-tests ADR draft under this EPIC, to
docs/issues/drafts/2003-adopt-prose-tests-as-executable-specification/,
at the EPIC owner's acceptance. The specifications-and-rationale
decision names the draft's path, so it now links the draft where it
lives. Drafts Awaiting Issues lists every 2003- draft on develop, so
the prose-tests draft joins the memories and harness-workspace drafts
there, under the Scope exception, until its issue is created.
… dispositions

The PR torrust#2484 review retrospective asks the owner of this EPIC to decide
which of its six proposals enter this EPIC or torrust#2278. The author-side
items go to torrust#2278's improvement matrix; the friction register records
where the rest land: the stamp rule for spec progress logs and the
restructuring step for create-issue as notes on their existing labels,
one session per pull-request branch as a new label against the
orchestration guide, and the sweep's tree-wide path and line-width
checks on the citation and wrapping labels. The progress log records
the triage.
…d the checkpoint range

The Friction Register section still described the index as two
comments, with the former-number map, the counts and the method in part
2, while the live index spans four comments and keeps those in part 3;
the introduction counted 127 frictions, and the counts table of
2026-09-28 read as current. The section now describes each of the four
parts at index v31 with its totals, points to part 3 for the live
counts, and keeps the 2026-09-28 table as a dated snapshot, which stays
true as later batches change the counts. The introduction no longer
carries a count.

The checkpoint and the Delivery Strategy named the early-implementation
orders as 1 to 14 while the Subissues table runs to 15; both drop the
range so they do not go stale with the next row.
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.
…ase, and drop the index version

The branch was rebased onto develop at the maintainer's request after
his approval. The AI-model-provenance discussion gained two rounds
there, but its Outcome is pending, so no decision enters the EPIC and
only the Progress Log records them. The Friction Register named its
index revision by a version no index comment carries; the timestamp
alone now identifies it.
…mments at its 2026-10-11 revision

Batch 32 laid the register's index out in five comments, so the
Friction Register's stamped state line, its part bullets and the
References link list described a layout that no longer exists; they now
describe the live index at its 2026-10-11 09:08 UTC revision.
@da2ce7

da2ce7 commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto develop 5d05fefdd as asked: the eight reviewed commits are unchanged (git range-diff all equal), and two commits follow them. The first records on the EPIC what the 185 commits brought: the two rounds of the AI-model-provenance discussion are on develop with the Outcome pending, so only the Progress Log carries them; it also drops the untraceable "v31" from the Friction Register sentence. The second brings that sentence, the part bullets and the References links to the register's live index, which batch 32 laid out in five comments on 2026-10-11 (13 artifact groups, 255 labels). The #2003 issue body is re-derived from the new head under the Issue Body Mirror rule and patched. The new head is 27ddb0ab632faf3d3257a60ced0673f35afc7040; the gate at it is in the description's Validation section. The two new commits change the EPIC's content, so I leave the re-check to you.

@josecelano

Copy link
Copy Markdown
Member

ACK 27ddb0a

@josecelano
josecelano merged commit 1c5939c into torrust:develop Oct 13, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants