Rename the scripts that update the policy files

script/commit-current-upstream-policy-docs is now
script/write-upstream-policy-files: it writes the policy files and
commits nothing. script/update-policy is now
script/commit-upstream-policy-files, and make update-policy is now
make commit-upstream-policy-files. test/update-policy.sh follows.
Behaviour is unchanged.

Model: opus-5-5

Dockerfile

@@ -42,7 +42,7 @@ RUN script/bootstrap
 
 COPY . .
 
-RUN timeout 90 test/update-policy.sh
+RUN timeout 90 test/commit-upstream-policy-files.sh
 
 # Development environment, and the last stage: a plain `docker build .`
 # names no target and so builds this one. Nothing is wanted from the two

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks commit-current-upstream-policy-docs update-policy
+.PHONY: bootstrap setup test lint fmt fmt-check check docker hooks write-upstream-policy-files commit-upstream-policy-files
 
 # Makefile targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -31,8 +31,8 @@ docker:
 hooks:
 	@script/install-precommit
 
-commit-current-upstream-policy-docs:
+write-upstream-policy-files:
-	@script/commit-current-upstream-policy-docs
+	@script/write-upstream-policy-files
 
-update-policy:
+commit-upstream-policy-files:
-	@script/update-policy
+	@script/commit-upstream-policy-files

README.md

@@ -119,7 +119,7 @@ alpine. We provide:
 - `script/test` —
   `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target test --output type=cacheonly .`,
   building the `test` phase of the `Dockerfile`, which runs
-  `test/update-policy.sh`, without writing an image
+  `test/commit-upstream-policy-files.sh`, without writing an image
 - `script/lint` —
   `docker build --build-arg CACHEBUST="$(date +%s)-$$" --target lint --output type=cacheonly .`,
   building the `lint` phase, which runs prettier over the markdown files,
@@ -141,14 +141,14 @@ alpine. We provide:
   `script/check`
 - `script/install-precommit` — installs the git pre-commit hook (our own
   extension); `make hooks` shims to it
-- `script/commit-current-upstream-policy-docs` — fetch the vendored policy files
+- `script/write-upstream-policy-files` — fetch the vendored policy files from
-  from this repo over HTTP and write them into a repo (our own extension). It
+  this repo over HTTP and write them into a repo (our own extension). It writes
-  writes into the repo given as its argument, or its own repo with no argument.
+  into the repo given as its argument, or its own repo with no argument. It
-  It stops when its target is this repo.
+  stops when its target is this repo.
-- `script/update-policy` — fetch the current
+- `script/commit-upstream-policy-files` — fetch the current
-  `script/commit-current-upstream-policy-docs`, run it on its own repo and
+  `script/write-upstream-policy-files`, run it on its own repo and commit the
-  commit the result without pushing (our own extension). It is for the repos
+  result without pushing (our own extension). It is for the repos that vendor
-  that vendor the policy files. It stops when run here.
+  the policy files. It stops when run here.
 
 `make hooks` installs the pre-commit hook that runs `script/precommit`.
 

prompts/EXISTING_REPO_CHECKLIST.md

@@ -205,28 +205,30 @@ with your task.
 - [ ] `Makefile` exists in root — reference
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`
 - [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
-      `hooks`, `update-policy`
+      `hooks`, `commit-upstream-policy-files`
 - [ ] Target implementations live in `script/` (scripts-to-rule-them-all);
       Makefile targets are thin shims calling them — model scripts at
       `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`
 - [ ] `script/precommit` exists and the pre-commit hook (installed by
       `script/install-precommit`, shimmed by `make hooks`) runs it
-- [ ] `script/commit-current-upstream-policy-docs` and `script/update-policy`
+- [ ] `script/write-upstream-policy-files` and
-      exist, identical to the model scripts, and `make update-policy` shims to
+      `script/commit-upstream-policy-files` exist, identical to the model
-      `script/update-policy`. `make update-policy` commits without pushing, so a
+      scripts, and `make commit-upstream-policy-files` shims to
-      person reviews and pushes the commit. A `.gitignore` or `.dockerignore`
+      `script/commit-upstream-policy-files`. `make commit-upstream-policy-files`
-      without the comment that ends the canonical file needs no preparation. The
+      commits without pushing, so a person reviews and pushes the commit. A
-      script moves each line the canonical file has never held to below the
+      `.gitignore` or `.dockerignore` without the comment that ends the
-      canonical content. Blank lines and comments are dropped. Before its first
+      canonical file needs no preparation. The script moves each line the
-      use, add that comment to an `.editorconfig` that has lines of its own, and
+      canonical file has never held to below the canonical content. Blank lines
-      put those lines below it. Otherwise the script stops before it writes
+      and comments are dropped. Before its first use, add that comment to an
-      anything, naming the file and each line. In a file that has the comment,
+      `.editorconfig` that has lines of its own, and put those lines below it.
-      an entry above it which the canonical file has never held also stops the
+      Otherwise the script stops before it writes anything, naming the file and
-      script. It stops the same way on a line in `.golangci.yml` that the
+      each line. In a file that has the comment, an entry above it which the
-      canonical file has never held, apart from comments and the repo's entries
+      canonical file has never held also stops the script. It stops the same way
-      in the `deny` list of the `test-support` rule. It also stops on a repo's
+      on a line in `.golangci.yml` that the canonical file has never held, apart
-      own `script/commit-current-upstream-policy-docs` or
+      from comments and the repo's entries in the `deny` list of the
-      `script/update-policy`.
+      `test-support` rule. It also stops on a repo's own
+      `script/write-upstream-policy-files` or
+      `script/commit-upstream-policy-files`.
 - [ ] README has an **Entrypoints** section documenting the `script/`
       entrypoints and linking the standard
 - [ ] `script/lint` and `script/test` each run

prompts/NEW_REPO_CHECKLIST.md

@@ -266,12 +266,13 @@ are thin shims calling them. Model scripts:
 - [ ] `script/install-precommit` — installs the pre-commit hook that runs
       `script/precommit`
 - [ ] `make hooks` — shims to `script/install-precommit`
-- [ ] `script/commit-current-upstream-policy-docs` — fetches the vendored policy
+- [ ] `script/write-upstream-policy-files` — fetches the vendored policy files
-      files from the `prompts` repo over HTTP and writes them into the repo;
+      from the `prompts` repo over HTTP and writes them into the repo; identical
-      identical across repos
+      across repos
-- [ ] `script/update-policy` / `make update-policy` — fetches the current
+- [ ] `script/commit-upstream-policy-files` /
-      `script/commit-current-upstream-policy-docs`, runs it on the repo and
+      `make commit-upstream-policy-files` — fetches the current
-      commits the result without pushing; identical across repos
+      `script/write-upstream-policy-files`, runs it on the repo and commits the
+      result without pushing; identical across repos
 - [ ] README **Entrypoints** section documents the scripts and links the
       standard
 

prompts/REPO_POLICIES.md

@@ -93,7 +93,8 @@ style conventions are in separate documents:
     - `make check` (runs `test`, `lint`, `fmt-check`)
     - `make docker`
     - `make hooks` (installs pre-commit hook)
-    - `make update-policy` (brings the repo up to standards and commits)
+    - `make commit-upstream-policy-files` (brings the repo up to standards and
+      commits)
 
     A model Makefile is at
     `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`.
@@ -110,8 +111,8 @@ style conventions are in separate documents:
     - `script/fmt-check`
     - `script/check`
     - `script/docker`
-    - `script/commit-current-upstream-policy-docs`
+    - `script/write-upstream-policy-files`
-    - `script/update-policy`
+    - `script/commit-upstream-policy-files`
 
     The scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they
     run in minimal containers; alpine images, for example, have no bash. Locate
@@ -191,13 +192,13 @@ style conventions are in separate documents:
       `script/check`.
     - `script/install-precommit` installs the git pre-commit hook. The
       `make hooks` target shims to it.
-    - `script/commit-current-upstream-policy-docs` fetches the vendored policy
+    - `script/write-upstream-policy-files` fetches the vendored policy files
-      files from the `prompts` repo over HTTP and writes them into the repo it
+      from the `prompts` repo over HTTP and writes them into the repo it is
-      is given, or its own repo with no argument.
+      given, or its own repo with no argument.
-    - `script/update-policy` fetches the current
+    - `script/commit-upstream-policy-files` fetches the current
-      `script/commit-current-upstream-policy-docs` from the `prompts` repo, runs
+      `script/write-upstream-policy-files` from the `prompts` repo, runs it on
-      it on its own repo and commits the result. It does not push. The
+      its own repo and commits the result. It does not push. The
-      `make update-policy` target shims to it.
+      `make commit-upstream-policy-files` target shims to it.
     - `script/projectname` (literally that filename) simply outputs the
       project's name.
 
@@ -937,21 +938,22 @@ style conventions are in separate documents:
 - Make all changes on a feature branch. You can do whatever you want on a
   feature branch.
 
-- One command brings a repo up to standards: `make update-policy`. It runs
+- One command brings a repo up to standards:
-  `script/update-policy`, which fetches the current
+  `make commit-upstream-policy-files`. It runs
-  `script/commit-current-upstream-policy-docs` from the head of `main` in the
+  `script/commit-upstream-policy-files`, which fetches the current
-  `prompts` repo and runs it on the repo. It then commits the files that changed
+  `script/write-upstream-policy-files` from the head of `main` in the `prompts`
-  and does not push, so a person reviews and pushes the commit.
+  repo and runs it on the repo. It then commits the files that changed and does
+  not push, so a person reviews and pushes the commit.
 
-    `script/commit-current-upstream-policy-docs` fetches each vendored file from
+    `script/write-upstream-policy-files` fetches each vendored file from
     `prompts` over HTTP and writes it into the repo. It skips a language's files
     when git tracks no source file of that language. A file the repo lacks is
     written whole. A `prompts/NAME.md` goes to `docs/NAME.md`, unless the repo
-    keeps it at `NAME.md`. It also writes
+    keeps it at `NAME.md`. It also writes `script/write-upstream-policy-files`
-    `script/commit-current-upstream-policy-docs` and `script/update-policy` into
+    and `script/commit-upstream-policy-files` into the repo, so a repo updated
-    the repo, so a repo updated once can update itself. The list of vendored
+    once can update itself. The list of vendored files is at the top of
-    files is at the top of `script/commit-current-upstream-policy-docs`. The
+    `script/write-upstream-policy-files`. The script replaces each file and
-    script replaces each file and keeps only the repo's own entries:
+    keeps only the repo's own entries:
     - in `.gitignore`, `.editorconfig` and `.dockerignore`: the lines below the
       comment that ends the canonical file
     - in a `.gitignore` or `.dockerignore` lacking that comment: every entry the
@@ -1184,8 +1186,8 @@ style conventions are in separate documents:
     - `Makefile`
     - `script/` entrypoints (`bootstrap`, `setup`, `projectname`, `test`,
       `lint`, `fmt`, `fmt-check`, `check`, `docker`, `cibuild`, `precommit`,
-      `install-precommit`, `commit-current-upstream-policy-docs`,
+      `install-precommit`, `write-upstream-policy-files`,
-      `update-policy`)
+      `commit-upstream-policy-files`)
     - `Dockerfile`, `.dockerignore`
     - `.gitea/workflows/check.yml`
     - Go: `go.mod`, `go.sum`, `.golangci.yml`

script/commit-upstream-policy-files

@@ -0,0 +1,45 @@
+#!/bin/sh
+# script/commit-upstream-policy-files: bring this repo up to standards.
+# It fetches the current script/write-upstream-policy-files from the
+# prompts repo over HTTP, runs it on this repo and commits the files it
+# wrote. It does not push. Identical in all repos. Our own extension to
+# scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+WRITE_UPSTREAM_POLICY_FILES_URL="https://git.eeqj.de/sneak/prompts/raw/branch/main/script/write-upstream-policy-files"
+
+die() {
+    echo "commit-upstream-policy-files: $*" >&2
+    exit 1
+}
+
+main() {
+    [ "$#" -eq 0 ] || die "usage: script/commit-upstream-policy-files"
+
+    cd "$ROOT"
+
+    tmp="$(mktemp -d)"
+    trap 'rm -rf "$tmp"' EXIT
+
+    curl --fail --silent --show-error --max-time 60 \
+        --output "$tmp/write-upstream-policy-files" \
+        "$WRITE_UPSTREAM_POLICY_FILES_URL" ||
+        die "cannot fetch $WRITE_UPSTREAM_POLICY_FILES_URL"
+
+    sh "$tmp/write-upstream-policy-files" "$ROOT" > "$tmp/written"
+    commit="$(head -n 1 "$tmp/written")"
+    paths="$(tail -n +2 "$tmp/written")"
+
+    for path in $paths; do
+        git add -- "$path"
+    done
+
+    if git diff --cached --quiet -- $paths; then
+        echo "commit-upstream-policy-files: already at prompts $commit, nothing to commit"
+    else
+        git commit -m "Update policy files from prompts $commit" -- $paths
+    fi
+}
+
+main "$@"

script/update-policy

@@ -1,45 +0,0 @@
-#!/bin/sh
-# script/update-policy: bring this repo up to standards. It fetches the
-# current script/commit-current-upstream-policy-docs from the prompts
-# repo over HTTP, runs it on this repo and commits the files it wrote.
-# It does not push. Identical in all repos. Our own extension to
-# scripts-to-rule-them-all.
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
-COMMIT_CURRENT_UPSTREAM_POLICY_DOCS_URL="https://git.eeqj.de/sneak/prompts/raw/branch/main/script/commit-current-upstream-policy-docs"
-
-die() {
-    echo "update-policy: $*" >&2
-    exit 1
-}
-
-main() {
-    [ "$#" -eq 0 ] || die "usage: script/update-policy"
-
-    cd "$ROOT"
-
-    tmp="$(mktemp -d)"
-    trap 'rm -rf "$tmp"' EXIT
-
-    curl --fail --silent --show-error --max-time 60 \
-        --output "$tmp/commit-current-upstream-policy-docs" \
-        "$COMMIT_CURRENT_UPSTREAM_POLICY_DOCS_URL" ||
-        die "cannot fetch $COMMIT_CURRENT_UPSTREAM_POLICY_DOCS_URL"
-
-    sh "$tmp/commit-current-upstream-policy-docs" "$ROOT" > "$tmp/written"
-    commit="$(head -n 1 "$tmp/written")"
-    paths="$(tail -n +2 "$tmp/written")"
-
-    for path in $paths; do
-        git add -- "$path"
-    done
-
-    if git diff --cached --quiet -- $paths; then
-        echo "update-policy: already at prompts $commit, nothing to commit"
-    else
-        git commit -m "Update policy files from prompts $commit" -- $paths
-    fi
-}
-
-main "$@"

script/write-upstream-policy-files

@@ -1,10 +1,10 @@
 #!/bin/sh
-# script/commit-current-upstream-policy-docs: write the current policy
+# script/write-upstream-policy-files: write the current policy files
-# files from the prompts repo into a repo clone, over HTTP. It commits
+# from the prompts repo into a repo clone, over HTTP. It commits
-# nothing; script/update-policy does that. Identical in all repos. Our
+# nothing; script/commit-upstream-policy-files does that. Identical in
-# own extension to scripts-to-rule-them-all.
+# all repos. Our own extension to scripts-to-rule-them-all.
 #
-# Usage: script/commit-current-upstream-policy-docs [path of a repo clone]
+# Usage: script/write-upstream-policy-files [path of a repo clone]
 # Without a path it updates the repo this script sits in.
 #
 # Standard output is the full hash of the prompts commit, then each path
@@ -50,12 +50,12 @@ prompts/GO_HTTP_SERVER_CONVENTIONS.md
 prompts/LLM_PROSE_TELLS.md
 prompts/NEW_REPO_CHECKLIST.md
 prompts/REPO_POLICIES.md
-script/commit-current-upstream-policy-docs
+script/write-upstream-policy-files
-script/update-policy
+script/commit-upstream-policy-files
 "
 
 die() {
-    echo "commit-current-upstream-policy-docs: $*" >&2
+    echo "write-upstream-policy-files: $*" >&2
     exit 1
 }
 
@@ -227,7 +227,7 @@ $own"
 
 main() {
     [ "$#" -le 1 ] ||
-        die "usage: script/commit-current-upstream-policy-docs [path of a repo clone]"
+        die "usage: script/write-upstream-policy-files [path of a repo clone]"
 
     target="${1:-$(dirname "$0")/..}"
     cd "$target" || die "no such directory: $target"
@@ -285,8 +285,8 @@ main() {
         mkdir -p "$(dirname "$path")"
         case "$path" in
             script/*)
-                # A new name and mv, because script/update-policy may
+                # A new name and mv, because the script running may be
-                # be the script running.
+                # script/commit-upstream-policy-files.
                 cp "$tmp/$path" "$path.new"
                 chmod 755 "$path.new"
                 mv "$path.new" "$path"

test/commit-upstream-policy-files.sh

@@ -1,14 +1,15 @@
 #!/bin/sh
-# test/update-policy.sh: test script/commit-current-upstream-policy-docs
+# test/commit-upstream-policy-files.sh: test
-# and script/update-policy on throwaway repos. Each scenario gets one
+# script/write-upstream-policy-files and script/commit-upstream-policy-files
-# temp directory holding a repo, its local bare origin, a local git
+# on throwaway repos. Each scenario gets one temp directory holding a
-# repository of the canonical files in place of prompts, and a stub curl
+# repo, its local bare origin, a local git repository of the canonical
-# that serves them, so nothing touches the network.
+# files in place of prompts, and a stub curl that serves them, so nothing
+# touches the network.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd -P)/script"
-COMMIT_CURRENT_UPSTREAM_POLICY_DOCS="$SCRIPT_DIR/commit-current-upstream-policy-docs"
+WRITE_UPSTREAM_POLICY_FILES="$SCRIPT_DIR/write-upstream-policy-files"
-UPDATE_POLICY="$SCRIPT_DIR/update-policy"
+COMMIT_UPSTREAM_POLICY_FILES="$SCRIPT_DIR/commit-upstream-policy-files"
 
 dir=""
 trap 'rm -rf "$dir"' EXIT
@@ -60,8 +61,8 @@ case "$url" in
                 "$HASH" 0000000000000000000000000000000000000000 > "$output"
         fi
         ;;
-    "$site/raw/branch/main/script/commit-current-upstream-policy-docs")
+    "$site/raw/branch/main/script/write-upstream-policy-files")
-        serve_file script/commit-current-upstream-policy-docs
+        serve_file script/write-upstream-policy-files
         ;;
     "$site/compare/$first...$HASH.patch")
         git -C "$canonical" format-patch --stdout --root "$HASH" > "$output"
@@ -79,7 +80,7 @@ EOF
 
 write_canonical_files() {
     mkdir -p "$dir/canonical/prompts" "$dir/canonical/script"
-    cp "$COMMIT_CURRENT_UPSTREAM_POLICY_DOCS" "$UPDATE_POLICY" \
+    cp "$WRITE_UPSTREAM_POLICY_FILES" "$COMMIT_UPSTREAM_POLICY_FILES" \
         "$dir/canonical/script/"
     cat > "$dir/canonical/.gitignore" << 'EOF'
 *.log
@@ -209,7 +210,7 @@ start_scenario() {
     git -C "$dir/repo" remote add origin "$dir/origin.git"
 
     mkdir "$dir/repo/script"
-    cp "$COMMIT_CURRENT_UPSTREAM_POLICY_DOCS" "$UPDATE_POLICY" \
+    cp "$WRITE_UPSTREAM_POLICY_FILES" "$COMMIT_UPSTREAM_POLICY_FILES" \
         "$dir/repo/script/"
     printf '#!/bin/sh\necho example\n' > "$dir/repo/script/projectname"
     chmod +x "$dir/repo/script/projectname"
@@ -257,18 +258,19 @@ remove_from_fixture() {
     before="$(git -C "$dir/repo" rev-parse HEAD)"
 }
 
-run_update_policy() {
+run_commit_upstream_policy_files() {
     status=0
     (cd "$dir/repo" && PATH="$dir/bin:$PATH" TMPDIR="$dir/tmp" \
-        script/update-policy "$@") > "$dir/output" 2>&1 || status=$?
+        script/commit-upstream-policy-files "$@") > "$dir/output" 2>&1 ||
+        status=$?
 }
 
-# run_commit_current_upstream_policy_docs <arguments>: run the script in
+# run_write_upstream_policy_files <arguments>: run the script in this
-# this source tree, from outside the repo it updates.
+# source tree, from outside the repo it updates.
-run_commit_current_upstream_policy_docs() {
+run_write_upstream_policy_files() {
     status=0
     (cd "$dir" && PATH="$dir/bin:$PATH" TMPDIR="$dir/tmp" \
-        "$COMMIT_CURRENT_UPSTREAM_POLICY_DOCS" "$@") > "$dir/output" 2>&1 ||
+        "$WRITE_UPSTREAM_POLICY_FILES" "$@") > "$dir/output" 2>&1 ||
         status=$?
 }
 
@@ -345,7 +347,7 @@ test_own_entries_kept() {
     start_scenario "own entries kept in all four files"
     commit_and_push_fixture .gitignore .dockerignore .editorconfig \
         .golangci.yml .prettierrc REPO_POLICIES.md
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
 
     expect_file .gitignore << 'EOF'
@@ -414,7 +416,7 @@ test_files_the_repo_lacks_are_written_whole() {
     remove_from_fixture REPO_POLICIES.md .gitignore .golangci.yml .gitea \
         docs/API_POLICIES.md docs/CODE_STYLEGUIDE_GO.md \
         docs/CODE_STYLEGUIDE_JS.md docs/CODE_STYLEGUIDE_PYTHON.md
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
 
     expect_same_as_canonical .gitignore
@@ -446,7 +448,7 @@ test_language_files_need_a_source_file() {
     remove_from_fixture cmd .golangci.yml docs/CODE_STYLEGUIDE_GO.md \
         docs/GO_HTTP_SERVER_CONVENTIONS.md docs/CODE_STYLEGUIDE_JS.md \
         docs/CODE_STYLEGUIDE_PYTHON.md
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
     expect_absent .golangci.yml
     expect_absent docs/CODE_STYLEGUIDE_GO.md
@@ -462,7 +464,7 @@ test_javascript_source_brings_its_styleguide() {
         echo "export {}" > "$dir/repo/web.$extension"
         commit_and_push_fixture "web.$extension"
         remove_from_fixture docs/CODE_STYLEGUIDE_JS.md
-        run_update_policy
+        run_commit_upstream_policy_files
         expect_success
         expect_file docs/CODE_STYLEGUIDE_JS.md << 'EOF'
 new CODE_STYLEGUIDE_JS
@@ -475,37 +477,37 @@ test_nothing_changed() {
     start_scenario "nothing changed"
     cp "$dir/canonical/.prettierrc" "$dir/repo/.prettierrc"
     commit_and_push_fixture .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
     expect_output "nothing to commit"
     expect_nothing_written
 }
 
-test_target_lacking_commit_current_upstream_policy_docs_gets_both_scripts() {
+test_target_lacking_write_upstream_policy_files_gets_both_scripts() {
-    start_scenario "a repo lacking script/commit-current-upstream-policy-docs gets it, and the current script/update-policy, in the commit"
+    start_scenario "a repo lacking script/write-upstream-policy-files gets it, and the current script/commit-upstream-policy-files, in the commit"
-    rm "$dir/repo/script/commit-current-upstream-policy-docs"
+    rm "$dir/repo/script/write-upstream-policy-files"
-    echo "# An older version." >> "$dir/repo/script/update-policy"
+    echo "# An older version." >> "$dir/repo/script/commit-upstream-policy-files"
     commit_and_push_fixture .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
-    expect_same_as_canonical script/commit-current-upstream-policy-docs
+    expect_same_as_canonical script/write-upstream-policy-files
-    expect_same_as_canonical script/update-policy
+    expect_same_as_canonical script/commit-upstream-policy-files
-    expect_committed_executable script/commit-current-upstream-policy-docs
+    expect_committed_executable script/write-upstream-policy-files
-    expect_committed_executable script/update-policy
+    expect_committed_executable script/commit-upstream-policy-files
     expect_new_commit_not_pushed
-    [ "$(files_in_commit)" = ".prettierrc script/commit-current-upstream-policy-docs script/update-policy " ] ||
+    [ "$(files_in_commit)" = ".prettierrc script/commit-upstream-policy-files script/write-upstream-policy-files " ] ||
         fail "the commit holds other files: $(files_in_commit)"
 }
 
 # The shell reads a script in blocks, so the padding makes it read the
 # last line only after main has returned. It finds that line only if
-# script/commit-current-upstream-policy-docs left the old file in place
+# script/write-upstream-policy-files left the old file in place under a
-# under a new name. The old file is an earlier canonical version, so
+# new name. The old file is an earlier canonical version, so
-# script/commit-current-upstream-policy-docs replaces it.
+# script/write-upstream-policy-files replaces it.
-test_update_policy_replaces_itself() {
+test_commit_upstream_policy_files_replaces_itself() {
-    start_scenario "script/update-policy replaces its own file and still exits 0"
+    start_scenario "script/commit-upstream-policy-files replaces its own file and still exits 0"
     {
-        cat "$dir/repo/script/update-policy"
+        cat "$dir/repo/script/commit-upstream-policy-files"
         i=0
         while [ "$i" -lt 2000 ]; do
             echo "# Padding."
@@ -513,61 +515,62 @@ test_update_policy_replaces_itself() {
         done
         echo "echo 'the old file ran to its end'"
     } > "$dir/merged"
-    cp "$dir/merged" "$dir/canonical/script/update-policy"
+    cp "$dir/merged" "$dir/canonical/script/commit-upstream-policy-files"
     commit_canonical
-    cp "$UPDATE_POLICY" "$dir/canonical/script/update-policy"
+    cp "$COMMIT_UPSTREAM_POLICY_FILES" \
+        "$dir/canonical/script/commit-upstream-policy-files"
     commit_canonical
-    mv "$dir/merged" "$dir/repo/script/update-policy"
+    mv "$dir/merged" "$dir/repo/script/commit-upstream-policy-files"
-    chmod 755 "$dir/repo/script/update-policy"
+    chmod 755 "$dir/repo/script/commit-upstream-policy-files"
     commit_and_push_fixture
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
     expect_output "the old file ran to its end"
-    expect_same_as_canonical script/update-policy
+    expect_same_as_canonical script/commit-upstream-policy-files
-    expect_executable script/update-policy
+    expect_executable script/commit-upstream-policy-files
     expect_new_commit_not_pushed
 }
 
-test_commit_current_upstream_policy_docs_with_path_commits_nothing() {
+test_write_upstream_policy_files_with_path_commits_nothing() {
-    start_scenario "script/commit-current-upstream-policy-docs with a path writes into that clone and commits nothing"
+    start_scenario "script/write-upstream-policy-files with a path writes into that clone and commits nothing"
-    rm "$dir/repo/script/commit-current-upstream-policy-docs" \
+    rm "$dir/repo/script/write-upstream-policy-files" \
-        "$dir/repo/script/update-policy"
+        "$dir/repo/script/commit-upstream-policy-files"
     commit_and_push_fixture .prettierrc
-    run_commit_current_upstream_policy_docs "$dir/repo"
+    run_write_upstream_policy_files "$dir/repo"
     expect_success
     expect_file .prettierrc << 'EOF'
 { "tabWidth": 4 }
 EOF
-    expect_same_as_canonical script/commit-current-upstream-policy-docs
+    expect_same_as_canonical script/write-upstream-policy-files
-    expect_same_as_canonical script/update-policy
+    expect_same_as_canonical script/commit-upstream-policy-files
-    expect_executable script/commit-current-upstream-policy-docs
+    expect_executable script/write-upstream-policy-files
-    expect_executable script/update-policy
+    expect_executable script/commit-upstream-policy-files
     expect_no_commit
     [ "$(head -n 1 "$dir/output")" = "$HASH" ] ||
         fail "the first line of output is not the hash"
-    expect_output "script/commit-current-upstream-policy-docs"
+    expect_output "script/write-upstream-policy-files"
     [ -z "$(ls -A "$dir/tmp")" ] || fail "a temporary directory is left"
 }
 
-test_commit_current_upstream_policy_docs_without_script_directory() {
+test_write_upstream_policy_files_without_script_directory() {
-    start_scenario "script/commit-current-upstream-policy-docs with a path writes both scripts into a clone with no script directory"
+    start_scenario "script/write-upstream-policy-files with a path writes both scripts into a clone with no script directory"
     commit_and_push_fixture .prettierrc
     remove_from_fixture script
-    run_commit_current_upstream_policy_docs "$dir/repo"
+    run_write_upstream_policy_files "$dir/repo"
     expect_success
-    expect_same_as_canonical script/commit-current-upstream-policy-docs
+    expect_same_as_canonical script/write-upstream-policy-files
-    expect_same_as_canonical script/update-policy
+    expect_same_as_canonical script/commit-upstream-policy-files
-    expect_executable script/commit-current-upstream-policy-docs
+    expect_executable script/write-upstream-policy-files
-    expect_executable script/update-policy
+    expect_executable script/commit-upstream-policy-files
     expect_no_commit
 }
 
-test_commit_current_upstream_policy_docs_without_argument_updates_own_repo() {
+test_write_upstream_policy_files_without_argument_updates_own_repo() {
-    start_scenario "script/commit-current-upstream-policy-docs with no argument updates the repo it sits in"
+    start_scenario "script/write-upstream-policy-files with no argument updates the repo it sits in"
     commit_and_push_fixture .prettierrc
     status=0
     (cd "$dir" && PATH="$dir/bin:$PATH" \
-        repo/script/commit-current-upstream-policy-docs) \
+        repo/script/write-upstream-policy-files) \
         > "$dir/output" 2>&1 || status=$?
     expect_success
     expect_file .prettierrc << 'EOF'
@@ -576,19 +579,19 @@ EOF
     expect_no_commit
 }
 
-test_commit_current_upstream_policy_docs_bad_target() {
+test_write_upstream_policy_files_bad_target() {
-    start_scenario "script/commit-current-upstream-policy-docs refuses a path that is not the top of a clone"
+    start_scenario "script/write-upstream-policy-files refuses a path that is not the top of a clone"
     commit_and_push_fixture .prettierrc
-    run_commit_current_upstream_policy_docs "$dir/repo/script"
+    run_write_upstream_policy_files "$dir/repo/script"
     expect_failure
     expect_output "not the top of a git clone"
-    run_commit_current_upstream_policy_docs "$dir/bin"
+    run_write_upstream_policy_files "$dir/bin"
     expect_failure
     expect_output "not the top of a git clone"
-    run_commit_current_upstream_policy_docs "$dir/no-such-directory"
+    run_write_upstream_policy_files "$dir/no-such-directory"
     expect_failure
     expect_output "no such directory"
-    run_commit_current_upstream_policy_docs "$dir/repo" extra
+    run_write_upstream_policy_files "$dir/repo" extra
     expect_failure
     expect_output "usage:"
     expect_nothing_written
@@ -597,13 +600,13 @@ test_commit_current_upstream_policy_docs_bad_target() {
 test_failed_fetch_stops() {
     for url in \
         "/api/v1/repos/sneak/prompts/branches/main" \
-        "/raw/branch/main/script/commit-current-upstream-policy-docs" \
+        "/raw/branch/main/script/write-upstream-policy-files" \
         "/compare/" \
         "/raw/commit/"; do
         start_scenario "a failed fetch of $url stops with nothing written"
         commit_and_push_fixture .gitignore .prettierrc REPO_POLICIES.md
         FAIL_URL="$url"
-        run_update_policy
+        run_commit_upstream_policy_files
         expect_failure
         expect_output "cannot fetch"
         expect_nothing_written
@@ -614,7 +617,7 @@ test_one_missing_file_stops_all() {
     start_scenario "one file missing from prompts stops before any file is written"
     rm "$dir/canonical/prompts/REPO_POLICIES.md"
     commit_and_push_fixture .prettierrc REPO_POLICIES.md
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output "cannot fetch"
     expect_nothing_written
@@ -624,7 +627,7 @@ test_branch_response_without_hash_stops() {
     start_scenario "a branch response with no commit hash stops"
     commit_and_push_fixture .prettierrc
     BAD_BRANCH_JSON=yes
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output "no commit hash"
     expect_nothing_written
@@ -642,7 +645,7 @@ test_own_entry_above_closing_comment() {
         mv "$dir/merged" "$dir/repo/$file"
         commit_and_push_fixture .gitignore .dockerignore .editorconfig \
             .prettierrc REPO_POLICIES.md
-        run_update_policy
+        run_commit_upstream_policy_files
         expect_failure
         expect_output "$file has entries"
         expect_output "/myapp"
@@ -656,7 +659,7 @@ test_uncommitted_change_stops() {
     start_scenario "a carried file with uncommitted changes stops"
     commit_and_push_fixture .prettierrc REPO_POLICIES.md
     echo "uncommitted" >> "$dir/repo/REPO_POLICIES.md"
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output "REPO_POLICIES.md has uncommitted changes"
     expect_file REPO_POLICIES.md << 'EOF'
@@ -667,14 +670,14 @@ EOF
 }
 
 test_untracked_script_stops() {
-    start_scenario "an untracked script/commit-current-upstream-policy-docs is not overwritten"
+    start_scenario "an untracked script/write-upstream-policy-files is not overwritten"
-    rm "$dir/repo/script/commit-current-upstream-policy-docs"
+    rm "$dir/repo/script/write-upstream-policy-files"
     commit_and_push_fixture .prettierrc
-    echo "our own script" > "$dir/repo/script/commit-current-upstream-policy-docs"
+    echo "our own script" > "$dir/repo/script/write-upstream-policy-files"
-    run_commit_current_upstream_policy_docs "$dir/repo"
+    run_write_upstream_policy_files "$dir/repo"
     expect_failure
-    expect_output "script/commit-current-upstream-policy-docs has uncommitted changes"
+    expect_output "script/write-upstream-policy-files has uncommitted changes"
-    expect_file script/commit-current-upstream-policy-docs << 'EOF'
+    expect_file script/write-upstream-policy-files << 'EOF'
 our own script
 EOF
     expect_no_commit
@@ -686,7 +689,7 @@ test_ignored_file_stops() {
     remove_from_fixture docs/API_POLICIES.md
     echo "docs/API_POLICIES.md" >> "$dir/repo/.git/info/exclude"
     echo "our own notes" > "$dir/repo/docs/API_POLICIES.md"
-    run_commit_current_upstream_policy_docs "$dir/repo"
+    run_write_upstream_policy_files "$dir/repo"
     expect_failure
     expect_output "docs/API_POLICIES.md is ignored by git"
     expect_file docs/API_POLICIES.md << 'EOF'
@@ -696,12 +699,12 @@ EOF
 }
 
 test_own_script_stops() {
-    for script in script/commit-current-upstream-policy-docs \
+    for script in script/write-upstream-policy-files \
-        script/update-policy; do
+        script/commit-upstream-policy-files; do
         start_scenario "a tracked $script with a line the canonical file has never held stops"
         echo "echo our own script" >> "$dir/repo/$script"
         commit_and_push_fixture .prettierrc
-        run_update_policy
+        run_commit_upstream_policy_files
         expect_failure
         expect_output "$script has lines"
         expect_output "echo our own script"
@@ -713,7 +716,7 @@ test_gitignore_lacks_canonical_last_line() {
     start_scenario ".gitignore lacking the canonical last line keeps the repo's own line below the canonical content"
     printf '*.log\n\n# A comment of our own.\n/myapp\n' > "$dir/repo/.gitignore"
     commit_and_push_fixture .gitignore .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
     expect_file .gitignore << 'EOF'
 *.log
@@ -736,7 +739,7 @@ test_editorconfig_lacks_canonical_last_line() {
     start_scenario ".editorconfig lacking the canonical last line with a line of its own stops"
     printf 'root = true\n[*.py]\nindent_size = 2\n' > "$dir/repo/.editorconfig"
     commit_and_push_fixture .editorconfig .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output ".editorconfig lacks this line"
     expect_output "[*.py]"
@@ -766,7 +769,7 @@ linters:
             - pkg: example.com/other
 EOF
     commit_and_push_fixture .golangci.yml .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output "no deny list in its test-support rule"
     expect_nothing_written
@@ -781,7 +784,7 @@ test_own_golangci_setting_stops() {
         - pattern: model.Operator
 EOF
     commit_and_push_fixture .golangci.yml .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output ".golangci.yml has lines"
     expect_output "forbidigo:"
@@ -795,7 +798,7 @@ test_source_repo_stops() {
     mkdir "$dir/repo/prompts"
     echo "policy" > "$dir/repo/prompts/REPO_POLICIES.md"
     commit_and_push_fixture .prettierrc prompts/REPO_POLICIES.md
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output "this repo is the source of the policy files"
     expect_nothing_written
@@ -806,7 +809,7 @@ test_staged_file_stays_out_of_commit() {
     commit_and_push_fixture .prettierrc
     echo "notes" > "$dir/repo/notes.txt"
     git -C "$dir/repo" add notes.txt
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
     [ "$(files_in_commit)" = ".prettierrc " ] ||
         fail "the commit holds more than the policy file"
@@ -814,10 +817,10 @@ test_staged_file_stays_out_of_commit() {
         fail "notes.txt is no longer staged"
 }
 
-test_update_policy_takes_no_argument() {
+test_commit_upstream_policy_files_takes_no_argument() {
-    start_scenario "script/update-policy refuses an argument"
+    start_scenario "script/commit-upstream-policy-files refuses an argument"
     commit_and_push_fixture .prettierrc
-    run_update_policy "$HASH"
+    run_commit_upstream_policy_files "$HASH"
     expect_failure
     expect_output "usage:"
     expect_nothing_written
@@ -836,7 +839,7 @@ expect_former_canonical_line_replaced() {
     mv "$dir/merged" "$dir/repo/$1"
     commit_and_push_fixture "$1" .prettierrc
 
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_success
     if grep -q -F -x -e "$2" "$dir/repo/$1"; then
         fail "$1 still has: $2"
@@ -855,10 +858,10 @@ test_former_canonical_gitignore_line_replaced() {
 }
 
 test_former_canonical_script_line_replaced() {
-    start_scenario "a script/commit-current-upstream-policy-docs line an earlier canonical commit held is replaced"
+    start_scenario "a script/write-upstream-policy-files line an earlier canonical commit held is replaced"
     expect_former_canonical_line_replaced \
-        script/commit-current-upstream-policy-docs "echo an older version"
+        script/write-upstream-policy-files "echo an older version"
-    expect_same_as_canonical script/commit-current-upstream-policy-docs
+    expect_same_as_canonical script/write-upstream-policy-files
 }
 
 # A line another file's history removed does not count as held by this
@@ -873,7 +876,7 @@ test_line_removed_from_another_file_still_stops() {
     { echo "*.old"; cat "$dir/repo/.gitignore"; } > "$dir/merged"
     mv "$dir/merged" "$dir/repo/.gitignore"
     commit_and_push_fixture .gitignore .prettierrc
-    run_update_policy
+    run_commit_upstream_policy_files
     expect_failure
     expect_output ".gitignore has entries"
     expect_output "*.old"
@@ -886,12 +889,12 @@ main() {
     test_language_files_need_a_source_file
     test_javascript_source_brings_its_styleguide
     test_nothing_changed
-    test_target_lacking_commit_current_upstream_policy_docs_gets_both_scripts
+    test_target_lacking_write_upstream_policy_files_gets_both_scripts
-    test_update_policy_replaces_itself
+    test_commit_upstream_policy_files_replaces_itself
-    test_commit_current_upstream_policy_docs_with_path_commits_nothing
+    test_write_upstream_policy_files_with_path_commits_nothing
-    test_commit_current_upstream_policy_docs_without_script_directory
+    test_write_upstream_policy_files_without_script_directory
-    test_commit_current_upstream_policy_docs_without_argument_updates_own_repo
+    test_write_upstream_policy_files_without_argument_updates_own_repo
-    test_commit_current_upstream_policy_docs_bad_target
+    test_write_upstream_policy_files_bad_target
     test_failed_fetch_stops
     test_one_missing_file_stops_all
     test_branch_response_without_hash_stops
@@ -908,12 +911,12 @@ main() {
     test_own_golangci_setting_stops
     test_source_repo_stops
     test_staged_file_stays_out_of_commit
-    test_update_policy_takes_no_argument
+    test_commit_upstream_policy_files_takes_no_argument
     test_former_canonical_golangci_line_replaced
     test_former_canonical_gitignore_line_replaced
     test_former_canonical_script_line_replaced
     test_line_removed_from_another_file_still_stops
-    echo "update-policy tests passed"
+    echo "commit-upstream-policy-files tests passed"
 }
 
 main "$@"