♻️ Group workflow scripts under a create: prefix

`branch` and `release` were bare commands, but bare in this repo means
"how you invoke a tier" or "runs one tool" — neither fits a command that
opens or closes a unit of work. They get their own prefix now, since a
prefix is how this repo records _when_ a script runs.

`create:` because both members genuinely create something (a branch, a
release) and it is a plain verb rather than VCS slang. No bare `create`
aggregator: running "all the workflows" describes nothing anyone wants,
and `publish:*` already precedents a prefix without one.

The rule "reuse an existing prefix, never invent one" now says what it
actually means: a new prefix is allowed when the scripts belong in the
pipeline, provided it enters both lists in the same commit as its first
member. That is the lesson from `use:`, which is referenced by prose yet
in none of the lists — already tracked in backlog.tasks.

The bare-command sentence shrinks to `build`, `clean`, `verify`.
This commit is contained in:
tmu committed 2026-09-08 22:51:35 +02:00
1 parent 8c2855aa92
commit 844e80d650
5 files changed
+37 -23

No files matched your search

+26 -13
View File
@@ -2,7 +2,7 @@
set -eu
# Branch front-door. Run as `npm run branch -- <prefix>/<desc>`.
# 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
# clean, current `main`, and the type-driven loop only produces trustworthy
@@ -12,17 +12,30 @@ set -eu
# 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: a new `flow:` / `git:` prefix (CONTRIBUTING.md § Script prefix
# convention forbids inventing one, and `use:git-commit-message` shows what
# happens when a prefix is added without amending the vocabulary that declares
# them); `check:*` (read-only and aggregated by `check`, so CI would run a
# command that mutates repo state); `fix:*` (its review surface is a file diff,
# not a branch); `maintain:*` (advisory, never a gate — the inverse of this);
# `start` (npm reserves it for running the package); a full git-flow CLI wrapping
# the merge too (merging ends in "review the diff yourself", which is judgment,
# and only the start half carries a verification burden); and reusing `pubv`'s
# preflight (it is release-shaped, third-party, and would make branch start pay
# a build + pack it has no use for).
# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the
# thing named after them", so every script in the repo would fit under them and
# the taxonomy collapses); `git:` (names the tool, not the lifecycle moment, and
# 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 is the `use:` mistake this repo now carries in backlog.tasks.
# 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: a full git-flow CLI wrapping the merge too (merging ends in
# "review the diff yourself", which is judgment, and only the start half carries
# a verification burden); and reusing `pubv`'s preflight (release-shaped,
# third-party, and it would make branch start pay a build + pack it has no use
# for).
#
# 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
@@ -33,7 +46,7 @@ PREFIXES="feature fix chore"
NAME="${1:-}"
if [ -z "${NAME}" ]; then
echo "usage: npm run branch -- <prefix>/<desc> (prefix: ${PREFIXES})" >&2
echo "usage: npm run create:branch -- <prefix>/<desc> (prefix: ${PREFIXES})" >&2
exit 2
fi