Repository navigation
docs(issues): [#2264] draft row 3 spec and order related-PRs as row 2.3 - #2425
Conversation
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The draft has unresolved bug-workflow evidence, acceptance-criterion, and verification-plan issues.
Review effort: Balanced
Findings: 3
Open (5)
What changed in this PR
Drafts EPIC #2264’s row 3 implementation plan and orders the related-PR proposal as row 2.3.
Changes:
- Adds the strict-profile and author-guidance specification.
- Updates EPIC ownership, sequencing, and progress tracking.
| File | Description |
|---|---|
docs/issues/drafts/2264-extend-strict-profiles-and-author-guidance/ISSUE.md |
Defines scope, decisions, tasks, and verification. |
docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md |
Adds row 2.3 and records row 3 planning. |
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Record Copilot review 5400517694 on the spec-only PR for EPIC torrust#2264 row 3 as five tracked findings, F1-F5, with their immutable review-finding references, severities from each comment's own bracket, categories, current-tree verification, and the fixing commit subject for each. All five are fixed. The thread replies are recorded in the Processing Log for posting; until they are posted the threads stay OPEN and the Reply URL fields are pending, which is the only state the audit validator still reports.
The pre-commit spell check rejects "unsuffixed" in the PR torrust#2425 audit. Reword the audit's own F1 Solution clause to "the name without the suffix", and log that the F1 reply will be posted with the reworded clause. The word also appears in Copilot's F1 comment, which the audit quotes verbatim, and in the append-only Processing Log entry that recorded the earlier reply text; neither may be rewritten, so the record carries a file-local cspell:ignore for it, as other PR review audits do for words in quoted reviewer text, instead of a project dictionary entry for a word the repository does not otherwise use.
torrust#2425 audit The F2 Solution and verification described B1 as Infeasible with a follow-up still to come. The follow-up commit now records the pod run as Reproduced, so the audit names that commit, updates the F2 lines, and logs the updated F2 reply for posting; the F2 row keeps its original resolution reference. The new draft Progress Log line also moved AC3 and M6 down one line each, so the F4 and F5 verification lines and the recorded F4 and F5 replies now cite the current line numbers.
…s and thread resolution The five round-1 replies are now posted on their threads, so each finding's Reply URL names its posted reply and each tracking row moves from OPEN to RESOLVED, the state process-pr-review prescribes for a fixed concern whose thread is resolved after its reply. The Processing Log records the five reply URLs and that the threads are resolved right after this commit reaches the PR, and the Findings preamble no longer describes the pending state.
Record Copilot review 5400517694 on the spec-only PR for EPIC torrust#2264 row 3 as five tracked findings, F1-F5, with their immutable review-finding references, severities from each comment's own bracket, categories, current-tree verification, and the fixing commit subject for each. All five are fixed. The thread replies are recorded in the Processing Log for posting; until they are posted the threads stay OPEN and the Reply URL fields are pending, which is the only state the audit validator still reports.
41aa572 to
93cb89b
Compare
The pre-commit spell check rejects "unsuffixed" in the PR torrust#2425 audit. Reword the audit's own F1 Solution clause to "the name without the suffix", and log that the F1 reply will be posted with the reworded clause. The word also appears in Copilot's F1 comment, which the audit quotes verbatim, and in the append-only Processing Log entry that recorded the earlier reply text; neither may be rewritten, so the record carries a file-local cspell:ignore for it, as other PR review audits do for words in quoted reviewer text, instead of a project dictionary entry for a word the repository does not otherwise use.
torrust#2425 audit The F2 Solution and verification described B1 as Infeasible with a follow-up still to come. The follow-up commit now records the pod run as Reproduced, so the audit names that commit, updates the F2 lines, and logs the updated F2 reply for posting; the F2 row keeps its original resolution reference. The new draft Progress Log line also moved AC3 and M6 down one line each, so the F4 and F5 verification lines and the recorded F4 and F5 replies now cite the current line numbers.
…s and thread resolution The five round-1 replies are now posted on their threads, so each finding's Reply URL names its posted reply and each tracking row moves from OPEN to RESOLVED, the state process-pr-review prescribes for a fixed concern whose thread is resolved after its reply. The Processing Log records the five reply URLs and that the threads are resolved right after this commit reaches the PR, and the Findings preamble no longer describes the pending state.
|
Rebased onto |
josecelano
left a comment
There was a problem hiding this comment.
Review round 1 (maintainer): request changes for R1-R3; R4-R7 are optional.
Verified: all 11 commits are signed and show as verified; the PR merges cleanly with develop; every code symbol and path the spec cites exists on develop; I reproduced B1 independently and got exactly the recorded output; frontmatter-validator passes on the 4 PR files (exit 0); linter markdown, linter cspell, and linter lychee pass; and validate-audit-record.py --pr-number 2425 passes with 0 failures.
The maintainer decisions requested in the PR body (D2/D3/D5/D6, the row 2.3 placement, and the EPIC owner) remain open and will be answered separately.
…torrust#2425 Record maintainer review 5468099277 as seven tracked findings, R1-R7, with their review-finding references, the severity of each comment's bracket, a category, a verbatim excerpt of the concern, the change and its current-tree verification, and the fixing commit subject. Each row records the thread state after its reply is posted and the thread is resolved; the Reply URL fields stay pending until the replies exist, and the Processing Log holds the reply texts for posting. The F2 Solution now uses the same portable term for the B1 environment as the evidence file; earlier log entries keep their wording.
5f6ef0e to
c1d6b45
Compare
Record Copilot review 5400517694 on the spec-only PR for EPIC torrust#2264 row 3 as five tracked findings, F1-F5, with their immutable review-finding references, severities from each comment's own bracket, categories, current-tree verification, and the fixing commit subject for each. All five are fixed. The thread replies are recorded in the Processing Log for posting; until they are posted the threads stay OPEN and the Reply URL fields are pending, which is the only state the audit validator still reports.
The pre-commit spell check rejects "unsuffixed" in the PR torrust#2425 audit. Reword the audit's own F1 Solution clause to "the name without the suffix", and log that the F1 reply will be posted with the reworded clause. The word also appears in Copilot's F1 comment, which the audit quotes verbatim, and in the append-only Processing Log entry that recorded the earlier reply text; neither may be rewritten, so the record carries a file-local cspell:ignore for it, as other PR review audits do for words in quoted reviewer text, instead of a project dictionary entry for a word the repository does not otherwise use.
torrust#2425 audit The F2 Solution and verification described B1 as Infeasible with a follow-up still to come. The follow-up commit now records the pod run as Reproduced, so the audit names that commit, updates the F2 lines, and logs the updated F2 reply for posting; the F2 row keeps its original resolution reference. The new draft Progress Log line also moved AC3 and M6 down one line each, so the F4 and F5 verification lines and the recorded F4 and F5 replies now cite the current line numbers.
…s and thread resolution The five round-1 replies are now posted on their threads, so each finding's Reply URL names its posted reply and each tracking row moves from OPEN to RESOLVED, the state process-pr-review prescribes for a fixed concern whose thread is resolved after its reply. The Processing Log records the five reply URLs and that the threads are resolved right after this commit reaches the PR, and the Findings preamble no longer describes the pending state.
…torrust#2425 Record maintainer review 5468099277 as seven tracked findings, R1-R7, with their review-finding references, the severity of each comment's bracket, a category, a verbatim excerpt of the concern, the change and its current-tree verification, and the fixing commit subject. Each row records the thread state after its reply is posted and the thread is resolved; the Reply URL fields stay pending until the replies exist, and the Processing Log holds the reply texts for posting. The F2 Solution now uses the same portable term for the B1 environment as the evidence file; earlier log entries keep their wording.
|
Rebased onto |
|
@da2ce7 I've reviewed the 2026-10-11 rebase ( The branch is now 57 commits behind |
josecelano
left a comment
There was a problem hiding this comment.
Approved. R1-R7 are resolved, and the 2026-10-11 rebase checks out. This approval accepts the decisions requested in the PR body: the row 2.3 placement, D1-D8 as recommended, the stale field lists handled as bug work under fix-bug, and da2ce7 as EPIC owner. Please rebase onto current develop before merging.
…s row 2.3 EPIC row 3 (extend strict profiles and author guidance) is the next Frontmatter step, and the EPIC asks whoever plans it to triage the unordered draft proposals first. Draft its specification under the parent-EPIC prefix: the v1 contract defers profiles for ADRs, skills, agents, and evidence records to this row, the validator command excludes docs/templates/ so template drift goes undetected, and the convention's duplicated issue and EPIC field lists already disagree with the v1 model. The draft proposes a maintainer-approved profile catalog, additive profiles under schema-version 1 with an explicit doc-type opt-in, an extension profile for skill and agent metadata, a placeholder-aware template mode, and author guidance that points to the generated schema instead of repeating it. Place the multiple-related-PRs proposal as row 2.3 rather than inside row 3: it changes the existing issue and EPIC profiles, while row 3 adds profiles for other document classes. Record the EPIC owner and log that the row 3 draft awaits maintainer approval before its GitHub issue is created.
…raft
The create-issue spec-only workflow names the branch
{issue-number}-{short-description}-spec, reserves the unsuffixed name
for implementation, and sets the spec's frontmatter branch to the same
-spec name. The draft's decision D1 already follows that workflow, but
its branch field pointed at the reserved implementation branch.
Addresses review-finding:pr-2425-f1.
…ttempt for row 3 The row 3 draft invokes fix-bug for the stale issue and EPIC field lists in the semantic-link convention, and fix-bug requires the reproduction to be attempted while drafting, before maintainer review, with its outcome classified in issue-local manual-verification-evidence.md. Add that record: two disposable specs written from the convention's list, the validator commands, and a field-by-field comparison with the strict issue profile. The drafting environment has no Rust toolchain, so the outcome is Infeasible with that comparison as the substitute evidence; running the recorded commands with the toolchain moves it to Reproduced. Addresses review-finding:pr-2425-f2.
…red, fix, and green tasks fix-bug requires the implementation plan to carry a regression-test task whose expected output is the recorded red run before the fix, followed by separate fix and green-plus-recheck tasks. The draft folded the stale-guidance correction into one task and argued that prose cannot carry a test. Name the maintained test that can fail for this defect: a crate test that validates every issue and EPIC frontmatter example in the semantic-link convention in the template mode of D6. Split the work into T7a (add the test and record it red), T7b (fix the convention and the other guidance), and T7c (green run and like-for-like recheck), and align the Bug-Fix Process, Regression Test Strategy, Commit Points, and AC9 with that sequence. Addresses review-finding:pr-2425-f3.
…row 3 AC3 AC3 required every existing library and command test to pass unmodified, but it_should_skip_excluded_paths_in_every_mode in the validator's CLI tests asserts that docs/templates/ is skipped in every mode, which T6 and AC7 deliberately reverse. Keep AC3 for the tests that assert issue and EPIC outcomes, name the exclusion test as the one that changes into template-mode coverage while it keeps asserting the fixtures exclusion, and record that change in T6. Addresses review-finding:pr-2425-f4.
…o trigger a finding M6 validated the existing historical folders, but that cannot exercise the warning conversion it claims to prove: the tracked closed refactor plans carry no schema-version: 1 and stay permissive, and valid closed issue specs produce no structural finding. Inject one unprefixed unknown field into a copy of a passing record in each historical location that has a strict profile, and expect exactly one warning and exit 0 for each copy. Addresses review-finding:pr-2425-f5.
Record Copilot review 5400517694 on the spec-only PR for EPIC torrust#2264 row 3 as five tracked findings, F1-F5, with their immutable review-finding references, severities from each comment's own bracket, categories, current-tree verification, and the fixing commit subject for each. All five are fixed. The thread replies are recorded in the Processing Log for posting; until they are posted the threads stay OPEN and the Reply URL fields are pending, which is the only state the audit validator still reports.
The pre-commit spell check rejects "unsuffixed" in the PR torrust#2425 audit. Reword the audit's own F1 Solution clause to "the name without the suffix", and log that the F1 reply will be posted with the reworded clause. The word also appears in Copilot's F1 comment, which the audit quotes verbatim, and in the append-only Processing Log entry that recorded the earlier reply text; neither may be rewritten, so the record carries a file-local cspell:ignore for it, as other PR review audits do for words in quoted reviewer text, instead of a project dictionary entry for a word the repository does not otherwise use.
… for row 3 The B1 reproduction was recorded as Infeasible while drafting because the drafting environment has no Rust toolchain. Its recorded commands then ran unchanged on the loop's compute pod with the workspace nightly toolchain and printed exactly the predicted records: legacy-shape for a spec written from the convention's issue field list, and missing-required-field for epic once schema-version: 1 is added, each with exit 1. Record the toolchain, the observed records, and the exit codes in section B1, keep the prediction table as the analysis, and move the outcome to Reproduced in the evidence file, the draft's Bug-Fix Process and Workflow Checkpoint, and its Progress Log. Follows review-finding:pr-2425-f2.
torrust#2425 audit The F2 Solution and verification described B1 as Infeasible with a follow-up still to come. The follow-up commit now records the pod run as Reproduced, so the audit names that commit, updates the F2 lines, and logs the updated F2 reply for posting; the F2 row keeps its original resolution reference. The new draft Progress Log line also moved AC3 and M6 down one line each, so the F4 and F5 verification lines and the recorded F4 and F5 replies now cite the current line numbers.
…s and thread resolution The five round-1 replies are now posted on their threads, so each finding's Reply URL names its posted reply and each tracking row moves from OPEN to RESOLVED, the state process-pr-review prescribes for a fixed concern whose thread is resolved after its reply. The Processing Log records the five reply URLs and that the threads are resolved right after this commit reaches the PR, and the Findings preamble no longer describes the pending state.
…t with rows 3 and 4 The multiple-related-PRs draft was ordered as row 2.3 and still listed under the unordered Draft Subissue Proposals, so it read as both ordered and unordered. Remove it from that list, which is now empty, and move the triage reason into the Progress Log entry that records the triage, wrapped like its neighbours. The row 3 draft said neither issue depends on the other, while the triage reason orders row 2.3 first so the issue-profile change settles. Both hold in part: row 3's profiles do not read related-pr, but both rows change profile.rs and the generated schema, and D2 assumes the new profiles can join schema-version 1, which row 2.3 may revisit. State that soft preference and its reason in the row 3 risk, and say in row 2.3 that it is BLOCKED until row 4 is done if it needs a new schema-version, while row 3 proceeds without it. Addresses review-finding:pr-2425-r1, review-finding:pr-2425-r2, and review-finding:pr-2425-r4.
…n the placeholder syntax D4 described implementation-retrospective, agent-review-reports, and security-report (and, by the same reading, adr) as produced by their templates, but those templates declare no doc-type on develop; only issue, epic, manual-verification-evidence, and refactor-plan are emitted today. Mark the others as proposed new values that their templates must start emitting (T4, AC8), so the producer criterion is not read as already met, and have T1 and AC1 record a disposition for every file in docs/templates/, including the ones D4 does not name. The templates also spell enumerated placeholders two ways, with and without spaces around the bar. Pin the accepted syntax in D6 and make template mode report other spellings as drift rather than normalise them. The baseline counts drift as the repository grows, so state that T1 re-measures them before the catalog is proposed. Addresses review-finding:pr-2425-r3, review-finding:pr-2425-r5, and review-finding:pr-2425-r7.
…d toolchain The B1 evidence named the reproduction environment with a term that nothing in the repository explains, prepared its commands for the stable toolchain although the run used nightly, and described the first observed record's provenance only loosely. Describe the environment as a Linux container with the workspace nightly toolchain, align step 3 with that toolchain, and state exactly which parts of the first record come from the transcript of the run and which were completed from the validator's legacy_shape string, which the maintainer's independent rerun on the PR head has since confirmed. The draft's Bug-Fix Process step 2 follows, and its Progress Log maps the earlier entry's wording to the portable term. Addresses review-finding:pr-2425-r6.
…torrust#2425 Record maintainer review 5468099277 as seven tracked findings, R1-R7, with their review-finding references, the severity of each comment's bracket, a category, a verbatim excerpt of the concern, the change and its current-tree verification, and the fixing commit subject. Each row records the thread state after its reply is posted and the thread is resolved; the Reply URL fields stay pending until the replies exist, and the Processing Log holds the reply texts for posting. The F2 Solution now uses the same portable term for the B1 environment as the evidence file; earlier log entries keep their wording.
c1d6b45 to
6c7b54e
Compare
|
Rebased onto |
|
ACK 6c7b54e — the rebase onto |
|
ACK 6c7b54e |


Related to #2264
Summary
This spec-only PR plans the next Frontmatter step of EPIC #2264. It contains planning documentation and its review audit only: no validator, template, skill, or schema change.
docs/issues/drafts/2264-extend-strict-profiles-and-author-guidance/ISSUE.md(status: draft,github-issue: null). It extends the canonical Rust frontmatter model beyond the strict issue and EPIC profiles to the classes the v1 contract defers (ADRs, Agent Skills and agent profiles, evidence and plan records), protectsdocs/templates/against drift from the contract (the validator command excludes that folder today), and replaces duplicated field lists in author guidance with references to the generated schema. It proposes decisions D1-D8 with recommendations and alternatives, names the EPIC Open Questions it answers or defers, and plans tasks T1-T9 with commit points, acceptance criteria AC1-AC10, and manual scenarios M1-M7. Implementation starts with an approval checkpoint for an issue-local profile catalog.BLOCKEDuntil row 4 is done if it needs a newschema-version; the Draft Subissue Proposals list now reads "None pending.", and the Progress Log entry that records the triage carries its reason.developalready carriesepic-owner: da2ce7and a laterlast-updated-utc. Row 3 staysTODOuntil its GitHub issue exists.docs/pr-reviews/pr-2425-review/PR-REVIEW.md; their replies are posted and their threads resolved. The stale convention field lists stay under thefix-bugworkflow, and the reproduction recorded in section B1 of the draft'smanual-verification-evidence.mdisReproduced.Maintainer Review Round 1 (review 5468099277)
All seven findings are fixed, R1-R3 as requested and R4-R7 as suggested, in these commits:
docs(issues): [#2264] order the row 2.3 draft once and align it with rows 3 and 4(R1, R2, R4): the triaged draft leaves the unordered proposals list, and its reason moves into the triage's Progress Log entry. The row 3 risk "Ordering after EPIC row 2.3" states the soft preference to start after row 2.3, with its reasons, and row 2.3 isBLOCKEDuntil row 4 is done if it needs a newschema-version, while row 3 proceeds without it.docs(issues): [#2264] mark the D4 doc-types as proposed and pin the placeholder syntax(R3, R5, R7): D4 marksadr,implementation-retrospective,agent-review-reports, andsecurity-reportas proposeddoc-typevalues that their templates must start emitting. T1 and AC1 record a disposition for every file indocs/templates/. D6 pins the enumerated-placeholder syntax and reports other spellings as drift. A note under the baseline table says T1 re-measures the counts.docs(issues): [#2264] state the B1 reproduction environment and toolchain(R6): section B1 names the environment as a Linux container with the workspace nightly toolchain, aligns step 3 with that toolchain, and states which parts of the first observed record come from the transcript of the run and which were completed from the validator source.docs(pr-reviews): [#2264] record the maintainer's round 1 on PR #2425: rows R1-R7 with their verifications and the reply texts for posting.docs(pr-reviews): [#2264] record the PR #2425 round 2 reply URLs: the seven Reply URL fields name the posted replies, and the seven threads are resolved.Requested Maintainer Decisions
schema-version: 1as additive profiles), D3 (explicitdoc-typeopt-in rather than path-based classes), D4 (the candidate catalog and the producer criterion), D5 (an extension-only profile for Agent Skills and agent profiles), and D6 (a placeholder-aware template mode instead of excludingdocs/templates/).fix-bug(Bug-Fix Process, evidence section B1, and tasks T7a-T7c) rather than as a documentation-only task.docs/issues/open/with its issue number, and row 3 links to it. The spec's "Spec reviewed and approved by user/maintainer" checkpoint stays unchecked until then.da2ce7as the EPIC owner.Files Touched
docs/issues/drafts/2264-extend-strict-profiles-and-author-guidance/ISSUE.md(new)docs/issues/drafts/2264-extend-strict-profiles-and-author-guidance/manual-verification-evidence.md(new)docs/issues/open/2264-2003-refactor-semantic-link-conventions/EPIC.md(Progressive Subissues table, Draft Subissue Proposals list, Progress Log)docs/pr-reviews/pr-2425-review/PR-REVIEW.md(new)Rebase
PR #2434 merged into
developatf960c78d7and also changed the #2264 EPIC, so this branch is rebased onto it; every other file merged cleanly, and the sixteen commits keep their content apart from that file. The conflict is resolved by keeping both sides' Progress Log entries in stamp order: this branch's 2026-10-03 10:56 entry,develop's 2026-10-04 19:18 entry, then this branch's 2026-10-09 10:25 entry, each with its existing wrapping.last-updated-utckeepsdevelop's "2026-10-09 10:41", the time of PR #2434's edit to this file, which is later than every entry. The base is nowf960c78d7.After the maintainer's approval the branch was 57 commits behind
developagain, and it is rebased fromf960c78d7ontodevelopatf7380a4d4at the maintainer's request; no file conflicted, andgit range-diff f960c78d7..c1d6b4572 f7380a4d4..6c7b54eacreports all sixteen commits as unchanged. The base is nowf7380a4d4.Validation
In a Linux container with the workspace nightly toolchain, at the rebased head
c1d6b4572, basedevelopf960c78d7(the merge base): pre-commit profile gate exit 0 (80 s);linter markdown,linter cspell,linter lycheeexit 0;frontmatter-validator --all19 errors / 4 warnings at the head and 19 / 4 atdevelopre-measured;git range-diffagainst5f6ef0e73shows 14 commits equal and 2 differing only in the resolved EPIC hunks.At the rebased head
6c7b54eac, basedevelopf7380a4d4(the merge base): pre-commit profile gate exit 0 (84 s);linter markdown,linter cspell,linter lycheeexit 0;frontmatter-validator --all19 errors / 4 warnings at the head and 19 / 4 atdevelopre-measured;validate-audit-record.py --pr-number 2425against the review comments captured on 2026-10-13: 12 rows, 27 log entries, 0 failures;git merge-treeagainstdevelopclean.markdownlint-cli2with the repository.markdownlint.json) on all four files: 0 errors.git diff --check: clean.validate-audit-record.py --pr-number 2425at the rebased head, against the review comments captured after the replies were posted: 12 rows, 27 log entries, 0 failures.docs/issues/drafts/2264-extend-strict-profiles-and-author-guidance/manual-verification-evidence.md):Reproducedin a Linux container with the workspace nightly toolchain; the maintainer's independent rerun on the PR head printed the same records; the rebase leaves the draft and its evidence unchanged.