[josecelano]

Related to #2429

Summary

Opens a design discussion for issue #2429, "Templated Documentation", instead of adopting the EPIC proposed in PR #2430. Jose Celano reviewed the proposal and likes the idea, especially for output-only documents such as docs/adrs/index.md, but an EPIC with a binding design is premature: the Torrust Index and Torrust Tracker AI harnesses have diverged, there are open questions, and the proposal combines well with the existing typed-frontmatter approach. Implementation waits until after the v4.0.0 release and the current work in progress.

This is the opening round under docs/discussions/AGENTS.md. Cameron's proposal is linked, not copied, so it belongs in his own round.

Changes

• docs/discussions/2429-templated-documentation/20261009-templated-documentation-design/README.md: context (the proposal, why a discussion, evidence checked against develop 41add51ab), nine topics (Q1 to Q9), and positions by Jose Celano on Q1, Q2, Q3, Q5, Q7, Q8, and Q9. Q4 (committed JSON datasets) and Q6 (forge captures) are open questions for the author. The Outcome is pending.
• maintainer-review-session.md in the same folder: Jose Celano's edited record of the maintainer review session (not a verbatim transcript). Its questions are numbered S1 to S9 to avoid colliding with the topic IDs.
• docs/index.md: discussion entry.

Drift fixes cited by the discussion (each in its own commit; the discussion's evidence stays anchored at 41add51ab):

• docs/adrs/index.md: add the missing row for the sccache ADR.
• docs/index.md: list the two missing templates (MANUAL-VERIFICATION-EVIDENCE.md, PR-REVIEW-RETROSPECTIVE.md).
• docs/skills/semantic-skill-link-convention.md: align the issue and EPIC frontmatter field lists with the validator's strict v1 profiles.
• docs/issues/open/2491-i2p-peer-support/EPIC.md and its discussion README: point the v4.0.0 references at the v4.0.0 milestone instead of Release v4.0.0-rc.1 #1659, the closed v4.0.0-rc.1 release issue, and rewrap the affected lines.

Review processing:

• docs/pr-reviews/pr-2501-review/PR-REVIEW.md: audit of Copilot review round 1 (F1 to F3) and Cameron Garnham's reviews rounds 2 and 3 (F4 to F8), all fixed; every review thread is replied to and resolved (F7 came from the review body and has no thread).

Notable facts recorded in the discussion

• At 41add51ab, docs/adrs/index.md had no row for the sccache ADR, the template table in docs/index.md omitted two templates, and the semantic-link convention's spec field lists disagreed with the validator; this PR fixes all three.
• The frontmatter validator already verifies restated facts in living documents (spec-path against the location, status against the lifecycle folder).
• The generated-schema precedent cited by the proposal (frontmatter-schema check) is not invoked by any hook, workflow, or test.
• 13 tracked Markdown files contain {{, 10 of them as GitHub Actions expressions, which matters for the choice of template delimiters.

Validation

• Pre-commit hook passed (frontmatter validator, linter all, doc tests).
• Pre-push hook passed (nightly checks and the full stable test suite).

AI assistance

Researched and drafted with an AI assistant using the Copilot SDK in VS Code (Claude Opus 5.5); reviewed and adopted by Jose Celano.

[Copilot]

🟡 Changes recommended

The discussion contains inaccurate proposal characterizations and does not preserve source material as required.

3 open findings

• Do not present unresolved template granularity as settled · New
• Tooling phase also changes workspace metadata · New
• Preserve source material or label it as an authored summary · New

What changed in this PR

Opens an attributed design discussion for templated documentation rather than adopting PR #2430’s binding EPIC design.

Changes:

• Adds nine design topics and maintainer positions.
• Preserves the related review session.
• Registers the discussion in the documentation index.

File	Description
docs/​index.md	Adds the discussion entry.
README.md	Defines the discussion context, topics, and positions.
maintainer-review-session.md	Records the review-session material.

🧠 Review effort: Balanced

---

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

[da2ce7]

Reviewed at db3974d9c177247148883879c2e8be4d94eea2d6 (round 2; round 1 at 23fb13343 was not posted because the head moved). Recomputed from the bytes at this head, against the merge base 41add51ab; develop is now 686a42f45 and the merge is clean.

The PR now touches eight files: the discussion README and its session record, a row in docs/adrs/index.md, three rows in docs/index.md, the spec field lists in docs/skills/semantic-skill-link-convention.md, the I2P EPIC and I2P discussion README, and the audit record docs/pr-reviews/pr-2501-review/PR-REVIEW.md.

Delta (nine commits). The three automated-review fixes hold: Q3 (README:128-136) quotes EPIC:120 "how many templates, per package or per concept" and EPIC:137 "Each of the 29 becomes a template" verbatim at 6535ce21e; Q8 (README:211-215) rests on Cargo.toml:130 "Every in-repo crate is listed explicitly"; the record header (record:3-9) says "Edited session record, not source material and not policy", README:48-50 matches it, and "full session" is gone. The drift fixes hold: 53ed29d94 puts the sccache row between 20260603000000 and 20260617093046 with the ADR's H1 and date (34 of 34 root ADRs listed); 1118e27d6 lists the two templates with descriptions matching docs/templates/README.md:28,30 (15 of 15); 0e6a93280 makes both lists equal, in order, to ISSUE_FIELDS, EPIC_FIELDS and STATUS_VALUES (profile.rs:182-209) and to the templates' frontmatter; 4f8382b69's third drift holds at 41add51ab and eb96d2957. 75627c801 repoints the I2P v4.0.0 references: #1659 is "Release v4.0.0-rc.1", closed; the EPIC frontmatter changes only related-artifacts and last-updated-utc; the new log entry keeps the earlier entries' person-and-assistant form, and the earlier entry stays as written. db3974d9c adds the audit record (F6).

README and template. Round 1 stands: seven rows in the template's order; the Decision owner row's facts hold; Q1–Q9 in order, entries at 98, 118, 140, 170, 202, 219, 236 in the heading form with the AI-assistance sentence; Q4 and Q6 "No entries yet."; Outcome is the template's text; anchors unique; S-pointers resolve (record:171-615).

Frontmatter. Stands: the README's seven paths exist, the record needs none, and the audit record's skill link and paths resolve.

Claims. Round 1's recomputations stand; the Evidence stays anchored at 41add51ab. F4 and F5 carry over from round 1 unchanged.

Positions. The seven entries are byte-identical to 23fb13343. The Q3 and Q8 lead paragraphs are the opener's own topic text.

Session record. Now labelled as the opener's edited record, so AGENTS.md:34 no longer applies; Part 3 and the paths and counts as in round 1.

Index and hygiene. Discussion row unchanged; template rows sit beside related rows (the table has no ordering rule); project-words.txt untouched. Conventional subjects; docs(adrs), docs(index), docs(skills) carry no issue tag, which commit-changes/SKILL.md does not require. "Addresses review-finding:pr-2501-fN" follows semantic-skill-link-convention.md:55-57. Author = committer, ascending times, one trailer line naming a co-author per commit; bodies match diffs; git diff --check clean; no banned token. Reported: EPIC lines 41 and 62 and I2P README line 41 run to 155–167 columns in files wrapped near 100 (MD013 off).

Audit record. Ownership (placeholder filled), Status Values and Completion Rules equal the template; rows F1–F3 match review 5469176634, the brackets, the replies and the resolved threads; the verification greps reproduce; validate-audit-record.py --pr-number 2501 --base work/develop on the captured comments prints {"status": "ok", "rows": 3, "log_entries": 5, "failures": 0}, exit 0.

I2P. The I2P README has four entries, all by josecelano, at 41add51ab and 686a42f45; the change is the opener's own Context (line 41) and frontmatter, so no other participant's content is touched.

#2430 consistency. Unchanged (not graded).

Findings

• F4 [Minor] README:183 quote is not the EPIC's wording
• F5 [Nit] README:230 omits "another canonical document"
• F6 [Minor] audit record:98 stamped after its commit

Checked, no finding: Q3's "only its root-ADR subissue" reading (EPIC:108's "Converting a document to a template" is for the rounds); the PR body's new sections (reported); the milestone number behind milestone/5 (not checkable offline).

Checks

On the loop's compute hub at this head, merge base 41add51ab (develop is 686a42f45; git merge-tree clean; receipt server-gates-krkavec-233): pre-commit profile gate exit 0 (75 s); linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at 41add51ab re-measured; validate-audit-record.py --pr-number 2501 against the review comments captured at 11:17Z: 3 rows, 5 log entries, 0 failures. GitHub checks at this head at posting time: "Docs Lint: completed/success". At posting, develop is 686a42f45.

[da2ce7]

ACK db3974d — the discussion and its edited session record, the four drift fixes, the I2P milestone repoint and the audit record recomputed against 41add51ab, eb96d2957 and 6535ce21e, with no blocking item standing

[da2ce7]

Reviewed at c6007053af4745d7fe0aa576b02d6ed379d58cd9 (round 3; round 2 at db3974d9c was approved). Recomputed from the bytes at this head, against the merge base f960c78d7; develop is f960c78d7 and the merge is clean.

Delta. The branch is rebased onto f960c78d7: git range-diff marks the twelve earlier commits =, and the PR's eight files at the rebased twelfth commit equal db3974d9c. The develop commits under the rebase (PR #2494, PR #2434) touch none of the PR's files. Of what the README cites, #2264's row 7 is still "Decide path-reference scope and syntax", TODO, and the knowledge-graph README's [[...]] line is unchanged, so Q7 still holds. Five commits follow: 5d06f429c (F4), 310426804 (F5), a3e1c39a8 (rewrap), 71b03c72f (F6), c6007053a (round-2 audit rows).

F4 — fixed. Q6 (README:183-184) now quotes ("frontmatter, paths, links, committed captures and check results"), which is EPIC:74 verbatim at 6535ce21e. The quoted "committed check results" has 0 hits in the README and in the record, whose line 565 now uses the words unquoted.

F5 — fixed. Q9 (README:230-231) says conclusions "take effect when recorded in the owning issue or EPIC specification, an ADR, or another canonical document", matching docs/discussions/AGENTS.md:7-9.

F6 — fixed. The correction (audit:157, stamped 2026-10-10 11:15) names the 2026-10-09 11:09 entry and keeps it as written. It gives the audit commit's author time as 11:08:50 UTC, which git log confirms (the committer date moved to 2026-10-10 with the rebase). The correction is not later than its own commit (71b03c72f, authored 11:15:02, committed 11:16:07 UTC). It was the last entry when the reply was posted, and the two round-2 entries appended after it keep the log in order.

Rewrap and audit rows. a3e1c39a8 changes only the wrapping and adds "see the" before each milestone link, as its body says; the Out of Scope bullet also moves the parenthesis after "is released". Frontmatter, last-updated-utc and the Progress Log are unchanged, and the I2P lines now stay within the widths the files already had (110 and 112 columns). The audit record's fixed blocks still equal the template. Rows F4–F6 match review 5469401053, its brackets, the replies 4237435459, 4237435519 and 4237435582, and the resolved threads. F7 records round 2's width point as review-anchored and NON_RESOLVABLE. The verification lines reproduce. validate-audit-record.py --pr-number 2501 --base work/merge-base on the captured comments prints {"status": "ok", "rows": 7, "log_entries": 8, "failures": 0} and exits 0. The seven discussion entries hash identical to round 2, and neither discussion README edits another participant's content.

Findings

• F8 [Minor] audit:158 misstates the rebased commits' committer dates (numbered F8 because the audit record already assigns F7)

Checked, no finding: Conventional subjects with [#2429]/[#2491]; "Addresses review-finding" lines on the four fixes; one trailer line naming a co-author per commit; author = committer identity; git diff --check clean; no banned token; the I2P EPIC frontmatter still has the Epic profile's fields with blocked; the PR body now covers round 2 and the rewrap (reported); review 5469401053 has been shown as dismissed since the force-push at 11:17:10Z (data); milestone 5 is not checkable offline.

Checks

On the loop's compute hub at this head, merge base f960c78d7 (develop is f960c78d7; git merge-tree clean; receipt server-gates-krkavec-238): pre-commit profile gate exit 0 (96 s); linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at f960c78d7 re-measured; validate-audit-record.py --pr-number 2501 against the review comments captured at 08:17Z: 7 rows, 8 log entries, 0 failures. GitHub checks at this head at posting time: "Docs Lint: completed/success". At posting, develop is f960c78d7.

[da2ce7]

ACK c600705 — the rebase onto f960c78d7, the fixes for F4 to F6, the I2P rewrap and the audit record's round-2 rows recomputed from the bytes, with no blocking item standing

[josecelano]

ACK 505fa57

[da2ce7]

Reviewed at 9fdc9c169b632efd9ab3882c650c0875f432b531 (round 4; round 3 at c6007053a was approved). Recomputed from the bytes at this head, against the merge base f960c78d7; develop is f960c78d7 and the merge is clean.

Delta. git range-diff marks the seventeen round-3 commits =, followed by two new ones: 505fa5745 (the F8 correction) and the head commit (the round-3 audit rows). Between the two heads only the audit record changes, by 19 added lines and no deletions. The other seven files and the seven discussion entries hash identical to round 3.

F8 — fixed. The correction (audit:176, stamped 2026-10-11 10:07) names the 2026-10-10 11:18 entry and keeps it byte-identical. Its range holds: the twelve rebased commits run from 11:12:52 (cdf376df9) to 11:12:57 UTC (100b06e40), and exactly the last three fall in 11:12:56–57. Its stamp is not later than its commit (505fa5745, authored and committed 10:07:05 UTC). It follows the append rule at docs/templates/PR-REVIEW-TEMPLATE.md:112-113, and the thread is resolved.

Round-3 rows. The fixed blocks still equal the template, and rows F1–F7 with their details are unchanged. The round-3 paragraph matches review 5482535188 (08:23:14Z, on c6007053a, one inline comment) and the reason for the F8 number. The F8 row and detail match comment 4240860083, reply 4241168839, the correction's bytes and a commit subject on the branch. The detail's verification command, run here with develop = f960c78d7, prints 11:12:52 first and 11:12:57 twelfth. Both 10:09 entries sit in the head commit (10:09:29 UTC), and the times they give hold against git log and the reply's created_at. validate-audit-record.py --pr-number 2501 --base work/merge-base on the captured comments prints {"status": "ok", "rows": 8, "log_entries": 11, "failures": 0} and exits 0. The entry's recorded result had 10 log entries because the run came before its own entry was appended.

Findings: none.

Checked, no finding: Conventional [#2429] subjects; "Addresses review-finding:pr-2501-f8" on the fix and none on the record commit; author = committer; times ascending after c6007053a; one trailer line naming a co-author each; every added paragraph and item is one line; git diff --check clean; no banned token; the PR body's review-processing item now names rounds 2 and 3 (reported). Reported as data: plain git log --format=%cd prints the commits' +0100 offset even under TZ=UTC, so the method named in the correction and the reply shows 12:12:52 +0100, the same instants as stated; the record's own verification line uses --date=format-local and prints UTC.

Checks

On the loop's compute hub at this head, merge base f960c78d7 (develop is f960c78d7; git merge-tree clean; receipt server-gates-krkavec-243): pre-commit profile gate exit 0 (75 s); linter markdown, linter cspell, linter lychee exit 0; frontmatter-validator --all: 19 errors / 4 warnings at this head and 19 / 4 at f960c78d7 re-measured; validate-audit-record.py --pr-number 2501 against the review comments captured at 10:25Z: 8 rows, 11 log entries, 0 failures. GitHub checks at this head at posting time: "Docs Lint: completed/success". At posting, develop is f960c78d7.

[da2ce7]

ACK 9fdc9c1 — the F8 correction, the audit record's round-3 rows and its validator run recomputed from the bytes, with the other seven files and the discussion entries unchanged since c6007053a and no blocking item standing

[josecelano]

ACK 9fdc9c1