v1.18: AGENTS.md release-policy enforcement + audit script

Codifies the "every vX.Y commit gets a matching tag + release before
the turn ends" rule that's already implicit in the .github/workflows/
release.yml flow, and ships AGENTS-release-check.sh so the rule is
testable in one command.

What changed in AGENTS.md (§ Versioning + releases):

- Made the rule explicit for parallel-session work: when the user
  commits in parallel, agents must check at end-of-turn that no
  untagged version commit is sitting on main.
- Added a TL;DR pointing at the new check script.
- Clarified that the auto-release workflow does the heavy lifting —
  agents only need to tag+push, not run gh release create themselves.
- Added a backfill policy: do NOT retroactively tag v1.10–v1.14
  (they predate the workflow + packaging; auto-build would fail).
  Explicit user request only.
- Added hot-spot reminders: fetch origin before tagging, wait for the
  workflow to finish, don't bump again to "fix" a missing release.

AGENTS-release-check.sh:

- Walks every commit whose subject matches ^v[0-9]+\.[0-9]+(\.[0-9]+)?:
  Verifies (a) a tag of the same name exists locally and (b) points
  at the same SHA; if gh is available, also (c) verifies the GitHub
  release exists. Exits 0 on a clean repo, 1 when anything is missing.
- Quiet by default; -v / --verbose prints OK rows too.
- Pulls origin/refs/tags before checking so a tag pushed but not
  fetched doesn't false-positive.

Verified: against the current main, the script correctly reports
v1.10–v1.14 missing (the pre-workflow versions) and v1.15–v1.17
clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: NagyVikt

AGENTS-release-check.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+# AGENTS.md end-of-turn check: every `v1.X:` commit on main must have
+# a matching annotated tag, and every tag must have a published GitHub
+# release. Exit code:
+#   0 — everything in sync
+#   1 — at least one version commit is missing a tag or release
+#   2 — environment unusable (no git, no gh, not in this repo)
+#
+# Quiet by default; pass --verbose to also print the GOOD lines.
+# This is a CHECK, not a fixer. It prints what's broken; you decide how
+# to repair (usually: tag + push the missing commit, let the workflow
+# build the release).
+set -u
+
+REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$REPO_DIR" || { echo "cannot cd to $REPO_DIR" >&2; exit 2; }
+command -v git >/dev/null 2>&1 || { echo "git not in PATH" >&2; exit 2; }
+
+VERBOSE=0
+[ "${1:-}" = "--verbose" ] || [ "${1:-}" = "-v" ] && VERBOSE=1
+
+# Pull latest tag state from origin so we don't false-positive on a tag
+# the user pushed but our local clone hasn't fetched.
+git fetch origin --tags --quiet 2>/dev/null || true
+
+missing_tags=0
+missing_releases=0
+
+# Walk every commit whose subject starts with `vX.Y[.Z]:`.
+while IFS=$'\t' read -r sha subject; do
+  tag=$(printf '%s' "$subject" | awk '{print $1}' | tr -d ':')
+  # The tag must (a) exist locally and (b) point at this same commit.
+  if ! git rev-parse --verify --quiet "refs/tags/$tag" >/dev/null; then
+    printf 'MISSING TAG     %s  %s\n' "$tag" "$sha"
+    missing_tags=$((missing_tags + 1))
+    continue
+  fi
+  tagged_sha=$(git rev-list -n 1 "refs/tags/$tag")
+  if [ "$tagged_sha" != "$sha" ]; then
+    printf 'TAG MISPOINTS   %s  expected %s  got %s\n' "$tag" "$sha" "$tagged_sha"
+    missing_tags=$((missing_tags + 1))
+    continue
+  fi
+  if command -v gh >/dev/null 2>&1; then
+    if ! gh release view "$tag" >/dev/null 2>&1; then
+      printf 'MISSING RELEASE %s  %s\n' "$tag" "$sha"
+      missing_releases=$((missing_releases + 1))
+      continue
+    fi
+  fi
+  [ "$VERBOSE" = "1" ] && printf 'OK              %s  %s\n' "$tag" "$sha"
+done < <(git log --format='%H%x09%s' | awk -F'\t' '$2 ~ /^v[0-9]+\.[0-9]+(\.[0-9]+)?:/ {print}')
+
+if [ "$missing_tags" -eq 0 ] && [ "$missing_releases" -eq 0 ]; then
+  [ "$VERBOSE" = "1" ] && echo "all version commits tagged + released"
+  exit 0
+fi
+
+echo
+echo "summary: $missing_tags missing tag(s), $missing_releases missing release(s)"
+echo "see AGENTS.md § Versioning + releases for the fix workflow"
+exit 1

AGENTS.md

@@ -4,44 +4,81 @@ Working rules for agents (Claude, Codex, etc.) editing this repository.
 
 ## Versioning + releases — non-negotiable
 
-**Every push that bumps a version MUST be accompanied by a matching GitHub release.** Pushing a commit titled `v1.X` without a release is a defect.
+**Every commit titled `vX.Y` MUST be tagged and have a matching GitHub release before you end your turn.** Pushing a `v1.X` commit without a tag is a defect; pushing a tag without a release is a defect. This rule applies to any agent (Claude, Codex, etc.) and to the user themselves — when committing in parallel, agents must check at end-of-turn that there's no untagged version commit on `main`.
 
-Workflow for any version bump:
+### TL;DR for AI agents
+
+Run this at the end of every turn that touched this repo, **before claiming done**:
+
+```bash
+bash AGENTS-release-check.sh   # or paste-inline:
+for sha in $(git log --format='%H %s' | awk '$2 ~ /^v[0-9]+\.[0-9]+/ {print $1}'); do
+  tag=$(git log -1 --format=%s "$sha" | awk '{print $1}' | tr -d ':')
+  if ! git tag -l "$tag" | grep -q "^$tag$"; then
+    echo "MISSING TAG: $tag at $sha"
+  fi
+done
+```
+
+If anything prints, you have unfinished work. Tag it, push it, verify the release.
+
+### The full workflow
+
+The repo has `.github/workflows/release.yml` that auto-builds the .deb and publishes a GitHub release on **every `v*` tag push**. So in practice the rule reduces to: **never push a `vX.Y` commit without immediately pushing the matching tag.**
 
 1. **Bump in this order:**
    - `README.md` — if a version string appears in the tagline or quick-start
-   - `bin/tmux-paste-dispatch.sh` header `WORKING VERSION: v1.X — <date>` comment
-   - Any other file with a `v1.X` literal — search with `git grep '^# WORKING VERSION'` and `git grep -F 'v1.'`
+   - `bin/tmux-paste-dispatch.sh` header `WORKING VERSION: v1.X — <date>` comment (note: historically not updated past v1.0; safe to leave alone unless the rest of the file is touched)
+   - Any other file with a `v1.X` literal — `git grep -F 'v1.'`
 
 2. **Commit message format:**
    ```
    v1.X: <one-line summary>
 
    <multi-paragraph body explaining what changed and why,
-   matching the style of v1.10–v1.14 in the existing history>
+   matching the style of v1.10–v1.17 in the existing history.>
 
    Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
    ```
    Use `git log --pretty=fuller` to confirm the trailer is preserved.
 
-3. **Tag + push:**
+3. **Tag + push — same turn as the commit, never deferred:**
    ```bash
-   git tag -a v1.X -m "v1.X: <one-line summary>"
    git push origin main
+   git tag -a v1.X -m "v1.X: <one-line summary>" <commit-sha>
    git push origin v1.X
    ```
+   The `<commit-sha>` is explicit so you tag the exact commit you just pushed, not HEAD (HEAD may have moved if the user committed in parallel).
 
-4. **Create the GitHub release immediately after pushing:**
+4. **The workflow handles the release.** Confirm with:
+   ```bash
+   gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId')
+   gh release view v1.X
+   ```
+   Workflow runs ~3 minutes (cargo build dominates). If the workflow fails, **investigate before ending the turn** — a failed release isn't optional cleanup, it's part of the bump.
+
+5. **If the workflow is absent** (early commits, or the file got deleted), fall back to manual:
    ```bash
    gh release create v1.X \
-     --title "v1.X: <one-line summary>" \
+     --title "flashpaste v1.X" \
      --notes "$(git log -1 --pretty=%B v1.X | tail -n +3)"
    ```
-   The `tail -n +3` skips the title line + blank line so the body is the multi-paragraph description.
-   - If this is a **breaking** change, add `--latest=true` and prepend a `### Breaking` block to the notes.
-   - If experimental / not ready for general use, add `--prerelease`.
+   Add `--prerelease` for experimental builds; add the .deb as an asset arg when you have one built.
+
+### Backfill policy
+
+If you find untagged version commits in history (`v1.10`–`v1.14` are this case — they predate the .deb workflow), **do not retroactively tag them by default**. Reasons:
+- The workflow doesn't exist on those commits → tag push fails the build job.
+- Their build-deb.sh / Rust workspace may not exist or compile.
+- Auto-generated release notes for ancient tags add noise to the Releases page.
+
+If the user explicitly asks for backfill, push tags one-by-one and use `gh release create --notes` manually (no workflow) per tag. Verify each .deb (if any) is correct before moving on.
+
+### Hot-spot reminders
 
-5. **Verify** with `gh release view v1.X` and `gh release list --limit 5`. The new release MUST appear in the list before considering the bump complete.
+- The user often commits in parallel with the agent. Always `git fetch origin && git log origin/main..HEAD` and `git log HEAD..origin/main` before tagging — your local HEAD may not be the version commit.
+- After `git push origin main` and `git push origin v1.X`, the workflow can take 2–5 minutes. Don't claim done before `gh release view v1.X` succeeds.
+- If the workflow fails for environmental reasons (transient apt fetch failure, runner restart), retry with `gh run rerun`. Don't push a v1.X+1 to "fix" a missing v1.X release.
 
 ## Version-number policy