docs(ci): record why woodpecker-cli cannot be enrolled in image-automation

I proposed widening ImageUpdateAutomation's `update.path` to `./` and adding
a woodpecker-cli ImagePolicy so automation would own the lint pin the way it
owns the server and agent. Checking that before building it killed the plan,
and corrected two things I had asserted without evidence.

WRONG #1 — my reason for hesitating. I claimed the 7 ansible-vault encrypted
`.yml` files would break the walk and take all 33 automated images down with
them. That was a guess about kyaml I never verified. Objects that are not
Kubernetes manifests are SKIPPED, not fatal.

WRONG #2 — and this is the one that matters: the plan cannot work at all.
Image-automation only patches YAML that is a Kubernetes manifest. Maintainer,
fluxcd/flux2#2826: "Flux can only patch Kubernetes manifests. This means the
YAML manifest must have `apiVersion` and `kind` fields." The docs agree —
markers go "in any Kubernetes custom resource stored in Git". A Woodpecker
pipeline file is plain YAML with no apiVersion/kind, so a marker in it is
silently ignored.

That is a property of the FILE, not of `update.path`. Widening the path buys
exactly nothing and would drag 197 unrelated ansible/esphome YAMLs into the
walk. So no policy, no second automation, no path change — all three would
have been motion that looked like a fix and changed nothing. The failure mode
would have been the quiet kind this repo keeps getting bitten by: a marker
sitting in the file looking maintained, never once updated.

What actually closes the gap, given the pin must stay manual:

  * README gains a "Not enrolled (structurally impossible)" section holding
    the quote and the explicit "do not try widening the path" warning, so the
    next person does not re-derive this.
  * update-audit item 5 now covers `.woodpecker/*.yml` step images and is told
    to flag woodpecker-cli whenever it trails the DEPLOYED SERVER, not merely
    the newest CLI release — the server auto-bumps and the CLI does not, so
    that skew is the thing worth reporting. Also told to compare only the
    vX.Y.Z part (the tag carries `-alpine`; the plain tag is scratch with no
    shell and would break the step) and to ignore the `next-*`/`pull_*` dev
    tags, which are the newest by date on that repo and are not releases.
  * the step comment states the real constraint instead of my earlier wrong
    one, which told the reader that widening the path was the fix.

Verified: v3.16.0-alpine is the newest 3.x alpine release tag, and matches the
deployed server v3.16.0. Config still parses; step image unchanged.

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

.woodpecker/ci-manifests-test.yml

@@ -104,11 +104,24 @@ steps:
   # one it accepts, and the gate stops predicting what the server will do —
   # which is its only purpose.
   #
-  # DRIFT RISK: the server auto-bumps (image-automation), this pin does not.
-  # ImageUpdateAutomation is scoped to `update.path: ./kubernetes`, so it cannot
-  # maintain a tag in .woodpecker/. Widening that path would let a policy own
-  # this line the way it owns the server and agent; until then this is a manual
-  # bump and will lag a server upgrade.
+  # `-alpine` is required, not cosmetic: the plain vX.Y.Z CLI image is
+  # scratch-based (19 MB, 2 layers, no shell) and the loop below needs `for`,
+  # `sed` and `echo` around the binary.
+  #
+  # DRIFT RISK — accepted, and NOT fixable here. The server auto-bumps via
+  # image-automation; this pin cannot, so the two will drift apart.
+  # Image-automation can only patch YAML that is a Kubernetes manifest —
+  # fluxcd/flux2#2826: "Flux can only patch Kubernetes manifests. This means the
+  # YAML manifest must have `apiVersion` and `kind` fields." A Woodpecker
+  # pipeline file has neither, so an `$imagepolicy` marker here is silently
+  # ignored. That is a property of the FILE, not of `update.path`: widening the
+  # automation's path to `./` would buy nothing and would drag 197 unrelated
+  # ansible/esphome YAMLs into the walk. Do not try it — it looks like the fix
+  # and is not.
+  #
+  # So this bump is manual, and drift is caught by the update-audit agent
+  # (ci/agents/update-audit/prompt.md, item 5) which is told to flag this image
+  # whenever it trails the deployed server. If you bump the server, bump here.
   - name: woodpecker-lint
     # depends_on: [] so all four run in parallel and every failure shows in one
     # run. Sequential default would stop at the first, making a contributor

ci/agents/update-audit/prompt.md

@@ -59,6 +59,22 @@ For each, find the **current pin in the repo** (Read/Glob/Grep), then look up th
 5. **Images deliberately excluded from automation** — listed in the
    image-automation `README.md` (e.g. vsftpd, otbr, ical-proxy) and any image with
    no `# {"$imagepolicy": ...}` marker. Check whether a newer usable tag exists.
+   This includes **CI step images in `.woodpecker/*.yml`**, which are all manual:
+   image-automation cannot patch those files at all (they are not Kubernetes
+   manifests — no `apiVersion`/`kind` — so markers there are ignored), and no
+   amount of `update.path` widening changes that. Grep `.woodpecker/` for
+   `image:` and check each pin.
+
+   Give `woodpeckerci/woodpecker-cli` in `.woodpecker/ci-manifests-test.yml`
+   particular attention: the woodpecker **server** IS auto-bumped (`3.x`), the
+   CLI is not, so they silently drift apart. The CLI lints pipeline configs
+   against its own schema, so one behind the server can pass a config the server
+   then rejects — the gate stops predicting server behaviour. Report the CLI as
+   needing an update whenever it trails the server version, not only when it
+   trails the newest CLI release. Its tag carries an `-alpine` suffix (the plain
+   tag is scratch-based with no shell and would break the step) — compare the
+   `vX.Y.Z` part, and ignore the `next-*` / `pull_*` development tags, which are
+   the newest by date on that repo and are not releases.
 6. **Ansible roles & OpenTofu providers** — `ansible/requirements.yml` (Galaxy
    roles/collections) and `opentofu/providers.tf` + `opentofu/.terraform.lock.hcl`.
    Report any with a newer published version.

kubernetes/infrastructure/image-automation/README.md

@@ -55,6 +55,30 @@ existing `flux-system` GitRepository whose Secret was created by
 | mmwave-configurator | `2.x` | Plain 3-component filter (rejects `addon-`/`-armv7`/`-arm64`/`-amd64` variants) |
 | cnpg-barman-plugin | `0.x` | v-prefix filter; marker lives in upstream-imported manifest (see below) |
 
+## Not enrolled (structurally impossible)
+
+- `woodpeckerci/woodpecker-cli` — the lint image in
+  `.woodpecker/ci-manifests-test.yml`. It publishes a perfectly good
+  version stream (`v3.16.0-alpine`), so unlike the three below this is
+  **not** a tag-format problem. It cannot be enrolled because
+  **image-automation can only patch YAML that is a Kubernetes manifest** —
+  a maintainer states it plainly in fluxcd/flux2#2826: *"Flux can only
+  patch Kubernetes manifests. This means the YAML manifest must have
+  `apiVersion` and `kind` fields."* A Woodpecker pipeline file is plain
+  YAML with neither, so the marker would be silently ignored.
+
+  Note this is **not** fixable by widening `update.path`. The path only
+  controls which directory is walked; objects without `apiVersion`/`kind`
+  are skipped regardless. Widening the path to `./` buys nothing here and
+  puts 197 unrelated ansible/esphome YAML files in the walk, so don't.
+
+  Consequence: the CLI is a **manual** pin while the server and agent
+  auto-bump, so it *will* drift. That is a known, accepted gap, covered
+  by the update-audit agent (item 5) rather than by automation. When
+  bumping the server major/minor, bump this too — it must stay on the
+  latest stable like everything else, and a CLI behind the server can
+  pass a config the server then rejects.
+
 ## Not enrolled (deliberate)
 
 These three images publish no usable version stream — there is nothing