review: stop recommending gh aw update in the consumer README

.changeset/readme-no-gh-aw-update.md

@@ -0,0 +1,5 @@
+---
+"review": patch
+---
+
+Docs only: stop recommending `gh aw update` anywhere in this repo. The review-consumer-bump skill (Khan/actions#357) documents it failing twice against this repo's tag scheme, observed live on 2026-08-20: it treats `review-v<version>` as a branch and repins to main's head SHA, and its 3-way merge emptied a consumer's installed `review.md` to 0 bytes (gh-aw v0.85.4). The consumer-facing README recommended it in 4 places and the review-onboarding skill in another 4; all 8 now describe the maintainer-driven bump flow (a manual `git merge-file` 3-way merge, one PR per consumer) and the README names the failure modes plus the condition for revisiting the ban (neither failure is filed upstream yet). The shipped `review.md` changes only in a frontmatter comment (the observability local-edit note no longer names `gh aw update` as the merger); no behavior change.

.claude/skills/review-onboarding/SKILL.md

@@ -168,7 +168,9 @@ listing the secrets the workflow references. Review each one before passing
 
 ## Step 2: local edits to the installed `review.md`
 
-`gh aw update` preserves local edits via 3-way merge, so these survive upgrades.
+Upgrades preserve local edits via a 3-way merge (the manual `git merge-file`
+flow in `.claude/skills/review-consumer-bump/SKILL.md`, not `gh aw update`,
+which mishandles the `review-v*` tag scheme), so these survive version bumps.
 Label each one with a `<REPO> LOCAL OVERRIDE:` comment saying *why*, so the next
 reader and the next merge conflict both have the reasoning.
 
@@ -351,7 +353,7 @@ reviews nothing.
 
    | File | Lines | Regenerated by |
    | --- | --- | --- |
-   | `.github/workflows/review.md` | ~3000 | `gh aw update` (verbatim from the tag, except the local edits) |
+   | `.github/workflows/review.md` | ~3000 | 3-way merge per `review-consumer-bump` (verbatim from the tag, except the local edits) |
    | `.github/workflows/review.lock.yml` | ~1900 | `gh aw compile` — the workflow GitHub actually runs |
    | `.github/workflows/agentics-maintenance.yml` | ~600 | `gh aw compile` — gh-aw housekeeping |
    | `.github/aw/actions-lock.json` | ~15 | `gh aw compile` — third-party action SHA pins |
@@ -424,18 +426,24 @@ the diff shows what a version bump changed.
 
 ```sh
 cd <consumer-repo> && git switch -c bump-shared-pr-reviewer
-gh aw update                     # 3-way merge; preserves the Step 2 local edits
+# 3-way merge per .claude/skills/review-consumer-bump/SKILL.md -- NOT `gh aw update`,
+# which repins review-v* tags to main's head SHA and once emptied review.md to 0 bytes
+<STOP: run the 3-way merge from that skill and commit it before continuing>
 gh aw compile                    # --approve only after reviewing any new secret
 ```
 
+The merge mechanics, the compile side effects to keep or revert, and the
+full verification list live in `.claude/skills/review-consumer-bump/SKILL.md`;
+this section covers only what an update means for a repo this skill onboarded.
+
 Then, in this order, because each step can invalidate the next:
 
 1. **Read the release notes between the two versions**
    (`workflows/review/CHANGELOG.md` in `Khan/actions`, from the pinned version to
    the new one). Semver is a behaviour contract here: a minor can change what gets
    reviewed, what a label means, or what the router does with an existing `ROUTING`
    line. This is the step that tells you what to look for in the rest.
-2. **Confirm every local edit survived the merge.** `gh aw update` preserves them,
+2. **Confirm every local edit survived the merge.** The merge preserves them,
    but "preserved" is not "still correct", and a conflict resolved badly is silent.
    Diff the installed `review.md` against the new tag's copy and check that what
    differs is exactly the Step 2 list and nothing else:

.github/workflows/review.md

@@ -165,7 +165,7 @@ network:
 # Both secrets are hard-required while this block is present: a missing one compiles to
 # an empty value that the MCP gateway's OTLP config schema rejects, so the agent job
 # dies at startup instead of skipping trace export. A repo without them must comment
-# this block out in its installed review.md (a local edit `gh aw update` preserves)
+# this block out in its installed review.md (a local edit the 3-way merge update flow preserves)
 # and recompile.
 #
 # KHAN/ACTIONS LOCAL OVERRIDE: the `observability:` block is disabled here because this

workflows/review/README.md

@@ -178,13 +178,20 @@ gh aw add Khan/actions/workflows/review/review.md@review-v<major>.<minor>.<patch
 
 This copies `review.md` into the consuming repo's `.github/workflows/`, records a
 `source:` field pointing back here, and compiles `review.lock.yml`. Commit both,
-plus the consumer config files below. Pull future updates with `gh aw update`
-(a 3-way merge that preserves your local edits).
+plus the consumer config files below. Version bumps arrive as PRs from the
+maintainers: a manual `git merge-file` 3-way merge that preserves your local
+edits (the playbook is `.claude/skills/review-consumer-bump/SKILL.md` in this
+repo, landing via [Khan/actions#357](https://github.com/Khan/actions/pull/357)).
+Do not run `gh aw update` yourself: it treats `review-v*` tags as
+branches and repins to main's head commit as a raw SHA, and its own merge
+once emptied an installed `review.md` to 0 bytes (both observed on gh-aw
+v0.85.4; neither failure is filed upstream yet, so re-test both on a scratch
+install before trusting a newer gh-aw release with this).
 
 The tag is self-consistent: the `review.md` inside each `review-v<version>` tag
 pins its own `pre-agent-steps` checkout `ref:` to that same version (the release
-flow rewrites it; see [Versioning](#versioning)), so after `gh aw add` or
-`gh aw update` the imported file already fetches the matching lib code and needs
+flow rewrites it; see [Versioning](#versioning)), so after `gh aw add` or a
+version bump the imported file already fetches the matching lib code and needs
 no manual fix-up of the ref.
 
 ### Onboarding a whole repo
@@ -271,7 +278,7 @@ main workflow would override the import and discard your allowlist.
 
 Repo-specific frontmatter that imports can't merge (e.g. an `if:` condition to skip
 deploy/automation branches or forks) goes directly in your installed `review.md` as
-a local edit; `gh aw update` preserves it.
+a local edit; the bump merge preserves it.
 
 ### Per-lens payloads (`lenses/<lens>.md`)
 
@@ -790,7 +797,7 @@ Two known interactions:
   rejects it, and the agent job dies at startup instead of skipping trace
   export (observed on Khan/actions#241). A repo without these secrets must
   comment out the `observability:` block in its installed `review.md` as a
-  local edit (which `gh aw update` preserves) and recompile.
+  local edit (which the bump merge preserves) and recompile.
 
 Optional:
 

workflows/review/lib/check-consumer-config.ts

@@ -537,7 +537,7 @@ export const checkConsumerConfig = (
         if (installed.source === undefined) {
             warn(
                 "source-missing",
-                `${workflowPath} carries no \`source:\` field, so \`gh aw update\` cannot find its upstream.`,
+                `${workflowPath} carries no \`source:\` field, so the manual bump flow cannot tell which upstream release this install was copied from.`,
             );
         } else if (installed.pinnedRef === undefined) {
             warn(

workflows/review/review.md

@@ -158,7 +158,7 @@ network:
 # Both secrets are hard-required while this block is present: a missing one compiles to
 # an empty value that the MCP gateway's OTLP config schema rejects, so the agent job
 # dies at startup instead of skipping trace export. A repo without them must comment
-# this block out in its installed review.md (a local edit `gh aw update` preserves)
+# this block out in its installed review.md (a local edit the 3-way merge update flow preserves)
 # and recompile.
 observability:
   otlp: