[da2ce7]

Related to #2429

Summary

This pull request no longer proposes an EPIC specification. As the decision owner asked in review 5469057611, it is reworked into my contribution round on the templated documentation discussion opened in PR #2501, at docs/discussions/2429-templated-documentation/20261009-templated-documentation-design/. Implementation waits until after the v4.0.0 release.

Changes

• docs/discussions/2429-templated-documentation/20261009-templated-documentation-design/initial-proposal.md (new): the EPIC text, kept as written with its frontmatter, under a note that marks it as source material. The EPIC specification at docs/issues/open/2429-templated-documentation/EPIC.md is no longer added.
• docs/discussions/2429-templated-documentation/20261009-templated-documentation-design/README.md: my entries under Q1 to Q9, appended after the decision owner's entries, or in place of "No entries yet." under Q4 and Q6. No other line of the discussion changes, and no topic is added.
• docs/pr-reviews/pr-2430-review/PR-REVIEW.md: the audit record of this pull request, now with review 5469057611 (F4 to F7), the review bot's review 5506433536 (F8, a re-raise of F4, and F9) and the rework in its Processing Log.

My positions in brief

• Q1: the line falls per fact; the restated parts of a living document are rendered as generated regions rather than verified by a second tool.
• Q2: a generated region is the default; a whole-file rendering only where a document is restated facts apart from a fixed preamble.
• Q3: no per-document templates for living documents; the data generator reads frontmatter from the file people edit, and a managed output enters the census only by its declared template, so no loop can form.
• Q4: committed datasets stay, introduced per aggregate, the ADR census first.
• Q5: hooks on the staged snapshot run check only, never write.
• Q6: a capture is refreshed with the row it feeds, its "as of" stamp is rendered beside the value, and the gate fails past a declared window.
• Q7: a placeholder produces presentation text only and never mints a semantic link.
• Q8: after the v4.0.0 release; the tooling could land earlier without converting any document if an earlier review is wanted.
• Q9: this round is the first instance of the path from discussion to feature, EPIC and subissues.

History

I rewrote the branch history during the review of this pull request. To rework it into my discussion round, I rebuilt the branch from develop instead of rebasing it, so the three commits of the previous head are no longer on the branch. AGENTS.md asks a rewrite to keep every step; these three steps are not kept as commits, but their content is preserved:

Commit of the previous head	Where its content is now
docs(issues): [#2429] add the templated documentation EPIC specification	The EPIC text is initial-proposal.md in the discussion folder, unchanged apart from the source-material note.
docs(issues): [#2429] anchor the counts to the develop head	The round-1 fix (F1): the anchored sentence is carried verbatim at initial-proposal.md:59.
docs(pr-reviews): [#2429] add the PR #2430 review audit record	Round 1 (F1 to F3) is in the audit record, docs/pr-reviews/pr-2430-review/PR-REVIEW.md, whose Processing Log records the rebuild.

The audit record cites the previous head by its last commit's subject, docs(pr-reviews): [#2429] add the PR #2430 review audit record, and never by its id.

Validation

• initial-proposal.md with its eight-line note removed is byte-identical to the EPIC text this pull request proposed before the rework.
• With my nine entries removed and "No entries yet." restored under Q4 and Q6, the discussion README is byte-identical to its version on develop; every link and heading anchor in the new text resolves.
• validate-audit-record.py --pr-number 2430 --base 9c8bcdf8a against the review comments as captured after the F10 reply: 10 rows, 16 log entries, 0 failures.
• git diff --check over the branch: clean.
• On the loop's compute hub at the head whose last commit is docs(pr-reviews): [#2429] record review 5535382217 and F10 in the PR #2430 audit (merge base 9c8bcdf8a; develop is 3195b8b60 and the merge is clean): the pre-commit profile passes; linter markdown, linter cspell and linter lychee pass; frontmatter-validator --all reports 19 errors and 4 warnings at this head and the same 19 and 4 at 9c8bcdf8a, none in the files this pull request touches.

Not in this pull request

• Issue Templated documentation #2429 is retitled and its EPIC label removed alongside this rework (F6).
• The link to my own implementation of the approach waits until it is published (F7).

[da2ce7]

@josecelano this PR adds the specification for EPIC #2429, "Templated Documentation": every fact a Markdown document restates from elsewhere becomes a rendering of committed data, through a four-stage pipeline (schema-checked TOML inputs, a Rust data generator emitting JSON datasets under a namespace-and-version envelope, a document generator with a staleness gate, and the existing linters over the committed renderings), converting the root ADRs first and treating each conversion as an editorial pass over the document.

If you like the concept, one question for you: is this work for now, or for after version 4?

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

Review effort: Lite
Findings: 3

Open (3)

• This sentence includes several concrete counts (e.g., 970 files, 272 specs) without anchoring them… · New
• The table rows start with ||, which Markdown interprets as an extra empty leading column. This… · New
• Same Markdown table issue as the Subissues table: || introduces an unintended empty first column… · New

What changed in this PR

Adds an EPIC specification document for issue #2429 (“Templated Documentation”), describing a staged pipeline for generating committed datasets and rendering Markdown with staleness gates.

Changes:

• Add EPIC.md spec under docs/issues/open/2429-templated-documentation/ describing goal/scope/design/subissues/acceptance criteria.
• Document a four-stage (inputs → dataset generator → doc generator → lint) fixed-point workflow with committed outputs and regenerate-and-compare gates.

File	Description
docs/​issues/​open/​2429-templated-documentation/​EPIC.md	Introduces the EPIC specification for templated documentation, including design, subissues, and acceptance criteria.

---

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

[josecelano]

Thanks, Cameron. I reviewed the EPIC with an AI assistant and I like the idea, especially for output-only documents such as docs/adrs/index.md. However, I think an EPIC with a binding design is premature: the Index and Tracker AI harnesses have diverged, I have many questions, and I think the proposal combines well with the typed-frontmatter approach we already use. To answer your question: after the v4.0.0 release and after the current work in progress is finished.

I opened a discussion instead: #2501. My proposal:

1. Rework this PR into your round of that discussion: add the EPIC text verbatim as initial-proposal.md in the discussion folder, remove docs/issues/open/2429-templated-documentation/EPIC.md, and add your positions on Q1 to Q9 (and new topics if you want).
2. Retitle #2429 and drop its EPIC label; it stays the issue the discussion informs.
3. Link your Index implementation once it is published; it would be very useful evidence for the discussion.

[josecelano]

@da2ce7 the discussion is merged in #2501 (77aab116c): docs/discussions/2429-templated-documentation/20261009-templated-documentation-design/. Thanks for the four review rounds.

When you have time, could you rebase this branch onto develop and rework it into your round of that discussion?

1. Add the EPIC text verbatim as initial-proposal.md in the discussion folder, marked as source material, and remove docs/issues/open/2429-templated-documentation/EPIC.md.
2. Add your positions under Q1 to Q9, and new topics from Q10 if you like.
3. Retitle the PR to match, for example docs(discussions): [#2429] add my round on templated documentation.
4. Retitle Templated documentation #2429 and drop its EPIC label.
5. Link your Index implementation once it is published.

No rush: implementation waits until after v4.0.0.

[Copilot]

🔵 Needs a closer look

The maintainer-requested discussion rework is absent, and the review audit omits subsequent actionable feedback.

0 open findings

3 resolved since last review

• Same Markdown table issue as the Subissues table: || introduces an unintended empty first column…
• The table rows start with ||, which Markdown interprets as an extra empty leading column. This…
• This sentence includes several concrete counts (e.g., 970 files, 272 specs) without anchoring them…

Previously missed (2)

In code that hasn't changed since last review

Remove rejected binding EPIC and preserve it as initial proposal

docs/​issues/​open/​2429-templated-documentation/​EPIC.md:69

The maintainer’s current direction supersedes this binding EPIC. Review 5469057611 and the October 13 PR comment explicitly request removing this file, preserving its text as initial-proposal.md in the merged #2501 discussion folder, adding the author’s Q1–Q9 positions, and retitling the PR. Keeping the design binding here would merge the artifact the maintainer rejected instead of the requested discussion contribution.

Track maintainer review findings and required rework in the audit

docs/​pr-reviews/​pr-2430-review/​PR-REVIEW.md:50

This audit is no longer complete: GitHub now contains maintainer review 5469057611 (CHANGES_REQUESTED, submitted October 9) and an October 13 maintainer comment with actionable rework instructions, but the findings table stops at the October 3 Copilot review. The process-pr-review workflow requires every actionable review-body assertion to be normalized and tracked. Add the human findings, details, dispositions, and append-only processing entries after the requested rework is handled.

🧠 Review effort: Balanced

[da2ce7]

Reworked at 57d81d2d0 as asked in review 5469057611: the branch is rebuilt on develop (9c8bcdf8a) as three commits, and the earlier EPIC commits leave it.

• F4 (keep the EPIC text as the discussion's initial proposal, remove the EPIC specification): fixed by docs(discussions): [#2429] keep the EPIC text as the proposal's source material. initial-proposal.md in the discussion folder carries the EPIC text as written, under a note marking it as source material; the EPIC specification is no longer added.
• F5 (positions on Q1 to Q9): fixed by docs(discussions): [#2429] add my round on templated documentation. Nine entries, one per topic, after the existing entries; no new topic.
• F6 (retitle Templated documentation #2429 and drop its EPIC label): done on the issue at 2026-10-15 11:32 UTC: title Templated documentation, the EPIC label removed, the body replaced with a pointer to the discussion. This pull request is retitled to match.
• F7 (link the implementation once published): follow-up. It is not published yet; the link comes in a later round.
• Review 5506433536 (the review bot): F8 restates F4 and is fixed by the same commit; F9 (record the review and the rework in the audit) is fixed by docs(pr-reviews): [#2429] record the rework of PR #2430 in its audit.

The audit record cites this comment for F4 to F9 in a follow-up commit; review is re-requested after that push.

[josecelano]

Reviewed at 8b9367049. The round is sound under the discussion merge gate: initial-proposal.md is the EPIC text unchanged apart from the source-material note, your entries are the only additions to the README (Q1 to Q9, no topic added, nothing else changed), the linters, frontmatter validator and audit validator pass, and #2429 is renamed. Thanks for engaging every topic. I'll answer the open points, especially Q4, in my next round.

[da2ce7]

Response to @josecelano's review 5535382217 (approved, 1 finding). The fix for F10 is outside the repository tree:

• F10. The PR description now has a ## History section, before ## Validation, saying that I rewrote the branch history during review. I rebuilt the branch from develop instead of rebasing it, so the three commits of the previous head are no longer on the branch: docs(issues): [#2429] add the templated documentation EPIC specification, docs(issues): [#2429] anchor the counts to the develop head and docs(pr-reviews): [#2429] add the PR #2430 review audit record. The section says where each one's content is now: the EPIC text in initial-proposal.md, the round-1 fix verbatim at initial-proposal.md:59, and round 1 in the audit record. It also says that the audit record cites the previous head by its last commit's subject. The commits are not restored, as the finding does not ask for that.

The audit record carries F10 as review-finding:pr-2430-f10, with this comment as its resolution reference, in docs(pr-reviews): [#2429] record review 5535382217 and F10 in the PR #2430 audit.

[josecelano]

ACK ff8015a