♻️ Move script-header rationale into development/

branch.sh, finish.sh, release.sh, runner-image.sh and release-notes.sh
carried multi-paragraph 'how we got here / rejected' essays in comments. They
now live in the matching development/ category file, and each script keeps a
one-line pointer so the rationale is single-homed and cannot drift.

scripts/branch.sh

@@ -4,43 +4,13 @@ set -eu
 
 # Branch front-door. Run as `npm run create:branch -- <prefix>/<desc>`.
 #
-# How we got here (short): the branching model says every change starts from a
+# Asserts the branch preconditions — clean tree, no in-progress operation,
-# clean, current `main`, and the type-driven loop only produces trustworthy
+# current `main`, green baseline — and only then creates the branch, so the
-# results if the baseline was green *before* the first edit. Both facts were
+# expensive `npm run test` is not paid on a tree that was never eligible.
-# prose. Prose rots silently — a rule nobody checks is a suggestion — so the
-# precondition became this script: it asserts, then branches, and the branch
-# only appears if the assertions passed. Cheap checks run first, `npm run test`
-# runs last: the expensive gate is not paid on a tree that was never eligible.
 #
-# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the
+# Why the front door exists, the rejected prefix names, and the `create:`
-# thing named after them", so every script in the repo would fit under them and
+# decision: development/workflow.md § Branching model and § Script prefix
-# the taxonomy collapses); `git:` (names the tool, not the lifecycle moment, and
+# convention.
-# advertises passthrough aliases); `start:` (describes this half, not the
-# release); `cut:` (idiomatic for both, but it needs VCS slang to decode, and a
-# signpost that has to be explained is not one); `flow:` (overloaded in a library
-# about type-level matching); and the existing families — `check:*` is read-only
-# and aggregated by `check`, so CI would run a command that mutates repo state;
-# `fix:*`'s review surface is a file diff, not a branch; `maintain:*` is advisory
-# and explicitly never a gate.
-#
-# `create:` was kept because both members really do create something: a branch,
-# a release. It was added to both prefix lists in CONTRIBUTING.md in the same
-# commit as its first members, because a prefix missing from those lists is
-# invisible — which was the `use:` mistake this repo carried in backlog.tasks (since retired into `setup:`).
-# There is deliberately no bare `create` aggregator: "run all the workflows"
-# describes nothing anyone wants, and `publish:*` already sets the precedent for
-# a prefix without one.
-#
-# Also rejected here: reusing `pubv`'s preflight (release-shaped, third-party,
-# and it would make branch start pay a build + pack it has no use for). The
-# merge half was originally rejected too ("review the diff yourself" is
-# judgment), but it now has its own front door — `create:finish` — which owns
-# the merge-side preconditions and the post-merge `verify`, so the start half
-# does not have to carry that burden.
-#
-# Every refusal is non-mutating except the baseline test, which runs on `main`
-# after we switch there — so a red `main` restores the branch you started on
-# rather than stranding you on it.
 
 BASE="main"
 PREFIXES="feature fix chore"

scripts/finish.sh

@@ -4,29 +4,14 @@ set -eu
 
 # Feature-finish front door. Run as `npm run create:finish`.
 #
-# Why this exists: `create:branch` opens a unit of work, but the close half
+# Mirror image of `create:branch`: asserts the merge-side preconditions, merges
-# (`git checkout main && git merge --no-ff <branch>`) stayed prose in the
+# the current `feature/`/`fix/`/`chore/` branch into `main` with `--no-ff`,
-# branching model, so it drifted per contributor and per session. This is the
+# proves the result with `npm run verify`, and only then deletes the branch. The
-# mirror image of `create:branch`: it asserts the same preconditions (clean
+# push is owned by `create:release`, so the merge stays local and reviewable.
-# tree, no in-progress operation, `main` matching its upstream), merges the
+# On a conflict it aborts and returns to the feature branch.
-# current `feature/`/`fix/`/`chore/` branch into `main`, proves the result with
-# `npm run verify`, and only then deletes the branch.
 #
-# `create:branch`'s comment argued against wrapping the merge as "judgment —
+# Rationale and the rejected alternatives: development/workflow.md § Branching
-# review the diff yourself". That judgment still lives here, just moved: the
+# model.
-# maintainer reviews the handover *before* invoking this, and the script only
-# commits the merge, never the push. The push is owned by `create:release`, so
-# the release commit and its tag leave together and a local merge stays
-# reviewable (and can be reverted with `git revert -m 1`) until then. `--no-ff`
-# keeps the unit of work visible in `git log`.
-#
-# Unlike `create:branch` a stale `main` is fast-forwarded instead of refused:
-# the tree is clean (checked above) and `main` is not the checked-out branch
-# yet, so there is no local state to lose. True divergence (local commits *and*
-# upstream commits) is still refused — that needs a human.
-#
-# On a merge conflict we abort and return to the feature branch, so a failed
-# finish never strands you on a half-merged `main`.
 
 BASE="main"
 PREFIXES="feature fix chore"

scripts/precompress.ts

@@ -9,6 +9,9 @@ import zlib from "node:zlib";
  * matching `Accept-Encoding` and falls back to the original for the rest.
  *
  * Usage: node --strip-types scripts/precompress.ts <dir> [<dir>...]
+ *
+ * Why sidecars rather than per-request compression: development/ci.md § Coverage
+ * serving.
  */
 
 /**

scripts/release-notes.sh

@@ -9,6 +9,8 @@ set -eu
 # `v1.2.3` and `1.2.3` match the `## [1.2.3]` heading. Prints to stdout and
 # exits non-zero when the tag has no section, so a release can never publish
 # with an empty body.
+#
+# Why: development/publishing.md § Release notes are extracted from the changelog.
 
 TAG="${1:-}"
 CHANGELOG="${CHANGELOG:-CHANGELOG.md}"

scripts/release.sh

@@ -4,29 +4,13 @@ set -eu
 
 # Release front-door. Run as `npm run create:release`.
 #
-# How we got here (short): we want hand-written Keep-a-Changelog notes, an
+# Graduates the [Unreleased] changelog notes, bumps package.json + the lockfile,
-# [Unreleased] -> "## [x.y.z] - DATE" graduation, and a tag that marks the exact
+# and commits then tags the exact SHA that CI publishes. The notes are finalized
-# commit on main that gets published. No single tool did BOTH the [Unreleased]
+# in VS Code before pubv because pubv's bump heuristic reads the [Unreleased]
-# graduation AND the package.json bump. So split by strength: `pubv` (tiny,
+# body.
-# changelog-driven) owns preflight + the interactive major/minor/patch heuristic
-# + graduating/committing CHANGELOG.md (no tag, no push); `npm version` syncs
-# package.json + the lockfile; `--amend` folds them into pubv's single commit;
-# tag AFTER the amend (so the tag is never orphaned) and push.
 #
-# The notes are finalized in VS Code *before* pubv: the [Unreleased] body is
+# Tooling rationale, the rejected alternatives, and the version source of truth:
-# what pubv's bump heuristic reads, so editing afterwards would inform the
+# development/publishing.md.
-# changelog only, not the version choice. pubv refuses a dirty tree, so that
-# edit is committed as a staging commit and folded back into the single release
-# commit below.
-#
-# Rejected: the conventional-commits family (our history is gitmoji, not
-# Conventional; and we want hand-written notes); changesets/rtk (config + a
-# heavier version/publish flow that fights our CI-only publish); knope/kacl/
-# bestikk (changelog-only — don't bump package.json; plus 5yr/2yr/brand-new
-# maintenance); pubv alone (verified it never writes package.json). We also
-# tried `versions` (silverwind) — great Gitea support — but pairing it with a
-# hand-rolled promote became a ~180-line script we'd have to maintain, which is
-# exactly what this ~30-line version replaces.
 
 CHANGELOG="CHANGELOG.md"
 BASE="main"

scripts/runner-image.sh

@@ -8,6 +8,9 @@ set -euo pipefail
 # pulls the image by name.
 #
 # Usage: scripts/runner-image.sh [--push]
+#
+# Why the image is baked, its two invariants, and the coordinated Node-bump
+# steps: development/ci.md.
 
 IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci"