docs: clarify same-PR changelog preparation

[jamesreimer]

Change

Refs #23 — reconcile the published same-PR changelog clarification within the Planner's authorized two-file scope. Contributors can retain a final PR reference for the current change, and maintainers can prepare its release section in that PR once version, scope, and intended UTC date are established. Complete release-delta accounting happens before merge in that path. Corrections follow the actual before-merge, after-merge/pre-tag, or post-publication state.

Authority is the user's settled Planning → Implementation contract for #23. This is implementation of that contract, not a new architectural decision. Only CONTRIBUTING.md and MAINTAINING.md change. Independent review remains required and separate from Implementation. No merge, release selection, tagging, publication, host mutation, issue closure, source-pin change, or downstream adoption is authorized here.

Reconciliation evidence

Verified source: jamesreimer/repo-template, issue #57, implementation PR #58.

• Exact upstream published commit: 75251599d49baa89f8f9b2bdf2347b4c8682c903.
• Exact upstream tree: 02d7b8e748b46e2b2ecf2a6e6ee388f9ef2913fa.
• Upstream PR #58 is MERGED, with that merge commit, at 2026-10-05T17:56:14Z. Read-back of upstream main resolved to that commit; compare API reported identical. A separate bare Git clone verified the commit/tree and consumed file objects. Fetching PR #58 head verified 3aa7652c8acac888a1c569b66fc06d3137e7ebb6 has that same tree and an empty diff to the published commit.
• Consumed upstream blobs: CONTRIBUTING.md = e067c23bf015973a879f6c68d153817c17413a1e; MAINTAINING.md = a1a79084704db8cf75c0c9718cd5386a9457b1f5.
• Verified downstream planning/comparison base: 417e2120f56c828c13b8c7d6a5228b8ecb7e2007; local HEAD and freshly fetched origin/main both matched before mutation. Worktree was clean and origin identified the intended repository.

Applicable upstream rule	Disposition and downstream correspondence
Common Changelog commit requirement and example-based PR interpretation	Consumed in CONTRIBUTING Changelog, expressly as Agent Workflows' interpretation; checked against Common Changelog §2.4.2. No claim to change the external format.
Cite an already-canonical commit; include associated PR where useful	Consumed in CONTRIBUTING Changelog.
Same-PR reference is final, with no later supplementation/replacement solely for the new canonical commit	Consumed in CONTRIBUTING Changelog, naming the eventual squash commit.
Exclude identities absent from published history	Adapted to pre-squash PR-head identities absent from canonical main. Historical/navigation references explicitly do not replace immutable reviewed candidate, canonical published SHA, or correspondence evidence.
Same-PR release section requires version, scope, intended UTC publication date	Consumed in MAINTAINING preparation step 2.
Complete release-delta verification before that PR merges	Consumed in step 2: every applicable change since previous release, retained summaries, and accuracy of the whole intended delta; existing notable-change curation remains.
Accurate mixed canonical-commit/current-PR references	Consumed in step 2.
Separate preparation for missing release facts, merged PR without section, or after-merge correction; aggregation alone insufficient	Consumed in step 2, including establishment of release facts in the later PR.
Generic merge/squash/rebase reference cases	Squash rule applied to verified effective local protection. Generic merge/rebase alternatives are non-applicable to this protected-branch procedure and intentionally omitted; no host change or new generic merge mandate.
Before-merge correction, including UTC midnight, and ordinary re-review	Consumed in step 2; explicitly retain qualification of the revised exact candidate and include version/scope/date/entry changes.
After-merge/pre-tag reviewed correction and resulting-commit validation	Adapted to a new reviewed PR, new canonical main SHA, re-established reviewed/published correspondence, and full qualification; no rewriting merged history.
Post-publication successor correction, actual publishedAt check, immutable published state	Preserved and made explicit in step 2; existing publication procedure remains byte-identical. Successor release needs its own authority.
Partial publication stop-and-inspect	Existing procedure preserved and expressly distinguished from pre-tag correction when a tag is already pushed.
Canonical merged-state checks, qualification, annotated tag, remote object/peeled-target checks, Release metadata/archive verification	Existing preparation step 3 onward is byte-identical. Preparation timing grants no publication authority.

All applicable rules are consumed or locally adapted as described; no applicable clarification is deferred. This is correspondence of the two adapted surfaces, not repository-wide byte identity or a permanent baseline ledger. The existing local release model requires stronger independent review, human authorization, exact candidates, and reviewed/published correspondence; these explain the intentional source differences. Source-pin ownership, pre-1.0 semantics, issue-closure safeguards, roles/handoffs/workflows, and downstream authority remain intact.

Host verification

GitHub effective rules/branches/main and independently read ruleset 23862052 (Protect default branch) show active enforcement on the default branch with no bypass actors, deletion/non-fast-forward protection, required PRs, squash as the only allowed landing method, resolved review threads, and strict Repository validation from GitHub Actions integration 15368. Host required approval count is zero; this does not waive the contract's independent review. Repository-wide merge/rebase toggles are true, but the effective branch rule restricts landing to squash. No settings changed.

The unchanged .github/workflows/validate.yml triggers on pull requests and pushes to main, produces Repository validation, and checks out github.event.pull_request.head.sha || github.sha explicitly. Final hosted exact-candidate evidence and the newly observed audit condition are recorded below.

Changelog

Notable for a future release. Proposed summary:

Clarify same-PR changelog preparation and durable-reference selection while preserving Agent Workflows' reviewed-to-published correspondence and publication safeguards.

Supporting reference: this PR and descriptive issue #23. Standing alone this is a compatible procedural clarification, PATCH-class under current pre-1.0 policy. The complete unreleased delta determines the eventual version. No version/date was selected and CHANGELOG.md is unchanged.

Consumer impact and boundaries

Repository contributors and maintainers gain explicit preparation and correction instructions. Reusable roles, handoffs, workflows, validator architecture, dependency resolution, source pins, and downstream consumers are unchanged. Consumer updates still require their own deliberate authority. No deviation from the accepted Planning scope or architecture.

Validation

• Exact immutable candidate: 9f01b96e3f403bf2e66d880b47fd9d4f6e026b51; tree 2346dcff91ec7550f6f35f7d5b109d79a02ee519.
• Candidate blobs: CONTRIBUTING ee1e1d0fdfd4d5b626d2dfc89a46b7a1c14826fb; MAINTAINING 7bbd17de9679a2d840cb43a5552e1222483d740b.
• Exact changed files from base: CONTRIBUTING.md, MAINTAINING.md. Reviewed staged bytes were committed without further changes; worktree/index are clean. Object comparison confirms maintenance authority/reconciliation/version sections and preparation step 3 through publication are byte-identical to base.
• Environment: Node v24.18.1, npm 11.19.0, pre-commit 4.6.2.
• npm ci --ignore-scripts: exit 0; lockfile-resolved installation, no dependency edits.
• .venv/bin/pre-commit run --all-files --show-diff-on-failure: exit 0. All applicable hooks passed: merge conflicts, JSON/YAML/TOML, case conflicts, private keys, EOF/whitespace/line endings, Markdownlint, Markdown authoring regressions, offline links, link validation regressions, Ruff check/format, actionlint, canonical artifact validator and tests. Broken-symlink hook skipped because no applicable files exist; expected selection, not unresolved validation.
• git diff --check and git diff --cached --check: exit 0.
• python3 scripts/validate_local.py: exit 0.
• python3 -m unittest discover -s tests: exit 0, 5 tests passed.
• Manual implementor inspection covered final PR references, earlier canonical references, squash identity, mixed references, all three release prerequisites, complete pre-merge delta, each separate-preparation trigger, UTC midnight, three correction windows, and partial publication. Protected publication text and all out-of-scope files remain unchanged. No prose-mirroring tests or validator changes were added. These checks do not substitute for independent review.

Original local audit limitation (retained evidence)

npm audit --json returned exit 1, with five high-severity affected-package entries rooted in the single already-known advisory GHSA-vfj7-8cjw-p6xm: braces, micromatch, fast-glob, globby, and markdownlint-cli2. This is not a clean or passed audit, a harmlessness determination, or a suppression.

repo-template#56 is the generic upstream owner; it remains OPEN with no newer comments/disposition. The original qualification advisory read-back reported affected braces <=3.0.3 and no patched version; npm then reported latest braces 3.0.3. The offered semver-major downgrade to markdownlint-cli2 0.0.4 was not applied. No new advisory, changed dependency graph, materially changed finding, or newly viable remedy was found in these checks. This bounded disposition is expressly provided by the Planning contract; dependency remediation remains outside #23.

Candidate dependency blobs equal the base: package.json = 4959950f0c4dc0dc979de0f03c0de247839531e2; package-lock.json = de95bd520ed401ee1b992061dd907c22b357f0ab; requirements-dev.txt = 23705400953a7a671c2c42dd1439aee2f62c689d. Clean lockfile installation and npm ls confirm markdownlint-cli2 0.23.3 → micromatch 4.0.8 → braces 3.0.3, also through globby 16.2.4 / fast-glob 3.3.3. This PR changes neither dependency files nor resolution.

Hosted validation — SUCCESS on unchanged candidate

The authorized retry used gh run rerun 37369705801 --repo jamesreimer/agent-workflows; no commit or repository configuration changed.

• Run 37369705801, attempt 2: completed, SUCCESS.
• Required Repository validation job 112074990325: completed, SUCCESS at 2026-10-06T02:17:45Z.
• Run head and the required check from Actions integration 15368 both identify 9f01b96e3f403bf2e66d880b47fd9d4f6e026b51.
• Checkout log records that exact ref, fetch, checkout, and final git log -1 --format=%H output. This is evidence of the actual checked-out candidate, not merely the run label.
• Every listed workflow step, including setup, dependency installation, repository checks, post steps, and completion, finished successfully. All applicable pre-commit hooks passed. The broken-symlink hook alone reports “no files to check”; that is the expected no-applicable-files selection. No unexpected skip or unresolved hosted step remains.
• Attempt 1 remains historical non-success: run failure, job 111963514784 cancelled without steps, and log retrieval returned HTTP 404 / BlobNotFound. No validation ran in that attempt, so it did not establish a candidate defect.

Current audit — non-clean; Planning disposition permits independent review

Full inspection of attempt 2 exposed a material change from the earlier bounded audit evidence: the npm ci --ignore-scripts log reports 9 affected-package entries (3 low, 1 moderate, 5 high). A read-only npm audit --json on the unchanged local candidate confirmed those counts and returned exit 1. The original audit had five high entries rooted in braces alone.

Newly reported advisories:

• katex@0.16.47: GHSA-238p-pmpm-9mq7, low severity, “Existing prototype pollution can bypass trust restrictions”; audit affected range >=0.11.0 <0.18.2. Dependency path: markdownlint-cli2 0.23.3 → markdownlint 0.41.1 → micromark-extension-math 3.1.0 → katex 0.16.47. This adds low entries for katex, micromark-extension-math, and markdownlint.
• smol-toml@1.8.0: GHSA-r4xh-jqrq-34v2, moderate severity, “Quadratic-time parse() from parseKey rescanning to end of document on each key line”; audit affected range <=1.8.0. Dependency path: markdownlint-cli2 0.23.3 → smol-toml 1.8.0.

The existing braces advisory and its five high affected-package entries remain. npm's proposed semver-major markdownlint-cli2 downgrade also changed from 0.0.4 to 0.21.0. That suggestion was not applied or established as viable remediation. No practical-exploitability or harmlessness claim is made.

The original contract required return to Planning for a new advisory or materially changed finding. Implementation made that return without changing the candidate. Planning has now explicitly dispositioned the findings in the user's continuation instruction for #23: they are separately owned and non-blocking to independent review of this exact documentation candidate. This supersedes the earlier pending-Planning status; it does not characterize the audit as passing.

Separate durable owners:

• repo-template#56 remains the existing generic braces owner. Its responsibility is not broadened.
• repo-template#59 — Assess new markdownlint dependency advisories for KaTeX and smol-toml owns assessment of GHSA-238p-pmpm-9mq7 and its affected path, GHSA-r4xh-jqrq-34v2, appropriate generic remediation, the changed npm remediation suggestion, and eventual downstream reconciliation consequences. Both owner issues were read back as OPEN.

The complete current recorded audit result remains exit 1, with 9 affected-package entries: 0 informational, 3 low, 1 moderate, 5 high, 0 critical. The five high entries are braces, micromatch, fast-glob, globby, and markdownlint-cli2; the three low entries are katex, micromark-extension-math, and markdownlint; the moderate entry is smol-toml. These are affected-package entries arising from three advisory identities, not nine independent advisories. The current recorded audit metadata reports 181 total dependencies (prod 126, dev 56, optional 0, peer 0, peerOptional 0; npm's category counts are reproduced as reported). The earlier five-high result is historical evidence only.

Planning's rationale is bounded: #24 changes only CONTRIBUTING.md and MAINTAINING.md; dependency files and installed resolution are unchanged; the advisories were not introduced by #24; required exact-candidate repository validation succeeded; and generic remediation is durably owned by #56 and #59. Dependency remediation is outside #23. No clean-audit claim, advisory waiver, harmlessness determination, audit suppression, approval of npm's proposed downgrade, or permission to modify dependencies follows from this disposition.

Planning explicitly accepts run 37369705801 attempt 2 and required job 112074990325 as successful exact-candidate validation. The cancelled first attempt remains historical non-success and does not establish a candidate defect. All required applicable hosted steps completed successfully.

Local HEAD and remote PR head remain 9f01b96e3f403bf2e66d880b47fd9d4f6e026b51; the worktree/index are clean and the diff from base remains exactly the two authorized documentation files. Base/candidate dependency blob identity and the upstream commit/tree/consumed-blob identities were rechecked during this evidence-only completion. The successful local qualification and recorded installed-resolution evidence remain applicable to the unchanged candidate. No repeat qualification or new audit was needed for this PR-description-only update; the current audit result above is the retained resumption result, not a claimed new scan.

Implementation return: complete and ready for independent review, returned to Planning first. The completed Implementation → Review handoff is prepared for Claude; it has not been sent directly to Claude and no independent-review conclusion is claimed. Independent review remains outstanding. No other unresolved implementation condition was identified. No new commit, merge, tag, publication, issue closure, settings/workflow change, dependency mutation, or candidate-content change was made. Planning controls the next role transfer and any later authorization.