From 275383244bc6a30400a3e068e295089d973e16d1 Mon Sep 17 00:00:00 2001 From: jnasbyupgrade Date: Fri, 31 Jul 2026 15:13:40 -0500 Subject: [PATCH] Maintain HISTORY.asc fixed-issues line per-commit; never force-push a PR Commit skill (step 3b, new): whenever a commit's `Fixes #N` closes a pgxntool issue, add it to the STABLE section's fixed-issues line immediately, even when the underlying change is too minor for its own narrative entry -- these are independent decisions. Previously this line was only compiled once, at release time, by scanning all merged PRs since the last release; that's now downgraded to an audit/safety net for anything that slipped through the per-commit step, rather than the primary mechanism. Release skill and the commit-message-format guide updated to match. Commit skill: made the existing "never force push" rule unambiguous -- it applies even to your own unreviewed draft PR branch, even for something as minor as fixing a HISTORY.asc entry. Add a new commit instead unless the user explicitly asks for a force-push/amend. Changes only in pgxntool-test. No related changes in pgxntool. Co-Authored-By: Claude Sonnet 5 --- .claude/skills/commit/SKILL.md | 22 +++++++++++++++++-- .../commit/guides/commit-message-format.md | 10 +++++++++ .claude/skills/release/SKILL.md | 18 ++++++++++++--- 3 files changed, 45 insertions(+), 5 deletions(-) diff --git a/.claude/skills/commit/SKILL.md b/.claude/skills/commit/SKILL.md index ea560f4..21e873a 100644 --- a/.claude/skills/commit/SKILL.md +++ b/.claude/skills/commit/SKILL.md @@ -17,11 +17,11 @@ Create git commits following project standards and safety protocols for pgxntool | Rule | Details | |------|---------| -| **Git Safety** | Never update git config. Never force push. Never skip hooks unless requested. | +| **Git Safety** | Never update git config. Never force push -- not even to your own already-open/draft PR branch to fix something minor (a typo, a HISTORY.asc trim) -- unless the user explicitly tells you to force-push. Add a new commit instead. Never skip hooks unless requested. | | **Attribution** | No "Generated with Claude Code" in body. Co-Authored-By trailer is OK. | | **Multi-Repo** | Commit BOTH repos if both have changes (unless told otherwise). No empty commits. Never create a branch on a repo that has no changes. | | **Testing** | ALL tests must pass. ANY failure = STOP and ask user. No rationalizing failures. | -| **HISTORY.asc** | Update for significant user-visible pgxntool changes. Propose entry, get confirmation. | +| **HISTORY.asc** | Update for significant user-visible pgxntool changes. Propose entry, get confirmation. Separately and always: any `Fixes #N`/`Closes #N`/`Resolves #N` for a pgxntool issue must be added to the running "Issues fixed" line, even when the change is too minor for its own bullet (see step 3b). | ## Workflow @@ -72,6 +72,23 @@ If update needed: [existing content...] ``` +### 3b. Update the "Issues fixed" line (pgxntool changes only, whenever an issue is fixed) + +Independent of the bullet-entry decision above: if this commit's message +contains a `Fixes #N` / `Closes #N` / `Resolves #N` for a pgxntool issue, that +issue number belongs on the STABLE section's running fixed-issues line -- +even when the change is too minor to warrant its own `==` entry. Don't defer +this to release time; maintain it incrementally, one commit at a time. (The +`/release` skill's own "Compile the complete fixed-issues line" step is a +final audit/safety net for anything that slipped through this per-commit +step -- e.g. a commit made outside this skill -- not the primary mechanism.) + +- Line lives at the end of the STABLE section (last line before the next + version's heading), format: `Issues fixed in this release: #7, #14, #19` +- If it doesn't exist yet, create it. If it exists, add the new number(s), + keep the list deduped and in ascending numeric order. +- pgxntool issues only -- pgxntool-test has no equivalent list. + ### 4. Draft Commit Messages Read the format guide for detailed templates and rules: @@ -140,5 +157,6 @@ Check both repos if both were pushed. Report any CI failures to the user immedia ## Restrictions - DO NOT push unless explicitly asked +- DO NOT force-push a PR branch unless the user explicitly asks you to -- including your own unreviewed draft PR. If a pushed commit needs correcting, add a new commit; don't amend and force-push on your own initiative. - DO NOT commit files with secrets (.env, credentials.json) - Never use `-i` flags (git commit -i, git rebase -i) diff --git a/.claude/skills/commit/guides/commit-message-format.md b/.claude/skills/commit/guides/commit-message-format.md index 9453086..5ee9281 100644 --- a/.claude/skills/commit/guides/commit-message-format.md +++ b/.claude/skills/commit/guides/commit-message-format.md @@ -23,6 +23,16 @@ Incorrect: Fixes #7, #14, #19. ``` +## Maintaining the HISTORY.asc fixed-issues line (pgxntool changes) + +Whenever a commit's `Fixes #N` / `Closes #N` / `Resolves #N` refers to a +pgxntool issue, add that issue number to the STABLE section's fixed-issues +line in `../pgxntool/HISTORY.asc` -- regardless of whether the change is +significant enough for its own narrative `==` entry. These are two separate +decisions: "does this need a bullet explaining what changed" (maybe not) vs +"was a numbered issue closed" (if yes, it always goes on the list). See the +commit skill's step 3b for the mechanics. + ## Item Ordering (CRITICAL) Order all items (changes, bullet points) by **decreasing importance**: diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index 451379b..6310664 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -321,6 +321,16 @@ genuinely unclear, ask the user rather than guessing. ### Compile the complete fixed-issues line +The `/commit` skill (step 3b) now maintains this line incrementally, one +commit at a time, whenever a commit's message carries a `Fixes #N` for a +pgxntool issue -- so by release time the STABLE section's fixed-issues line +should already list most or all of what belongs here. This step is the +**audit/safety net**, not the primary mechanism: it catches anything that +slipped through the per-commit step (a commit made outside `/commit`, a +`Fixes #N` added to a PR body after the commit landed, manual edits, etc.) +and re-derives the complete, authoritative list from `release..HEAD` history +to verify against what's already in the file. + Independent of the individual STABLE entries above (which only narrate changes important enough to write up), compile one line listing *every* pgxntool issue actually closed by a commit in `release..HEAD` -- including @@ -339,10 +349,12 @@ issues GitHub's auto-close silently failed to close: issues #14, #19, #50, and #53 all genuinely fixed by one PR whose body read `Fixes #7, #14, #19, #28, #50, #53` -- only #7 auto-closed, and the other four sat open on GitHub until caught by a manual post-release audit. -3. Union both sources per PR, then union across all PRs in the release. +3. Union both sources per PR, then union across all PRs in the release, then + union with whatever the per-commit step has already put in the file. -Append the result as a single line at the end of the STABLE section (after -the last `==` entry, before the next version's heading), e.g.: +Reconcile against the existing fixed-issues line at the end of the STABLE +section (after the last `==` entry, before the next version's heading) -- +add anything this audit found that isn't already there, e.g.: ```text Issues fixed in this release: #7, #14, #19, #28, #46, #50, #53, #54, #57, #62, #65