Document Audita's annotated tag delivery failure

docs/roadmap/audita-bug-report.md

@@ -0,0 +1,109 @@
+# Audita Bug Report: Annotated Tag IDs in Woodpecker Delivery Examples
+
+**Status:** Reported; upstream correction requested.
+**Reviewed release:** ReleaseKit v0.4.1, commit
+`2d5a8110c61e31daf8698766114ae305d0e0e469`.
+**Affected consumer:** Audita v3.1.0.
+
+## Summary and Impact
+
+Audita copied ReleaseKit's module-selected Woodpecker delivery example. Its
+v3.1.0 delivery pipeline stopped during bootstrap because the example assumes
+`CI_COMMIT_SHA` always names a commit. In this Gitea/Woodpecker tag event, that
+value named the annotated tag object instead. Comparing it directly with the
+tag's peeled commit failed under `set -e`.
+
+The failure occurred before Go bootstrap or ReleaseKit execution. This is a
+workflow/example integration defect; ReleaseKit's `ci-deliver --commit` contract
+correctly expects the source commit ID. Source publication succeeded; binary
+delivery did not begin.
+
+## Verified Evidence
+
+The clone log fetched and reset the checkout using object
+`473d29007172cdb0a928e1dcc0556d3e8f469931`. Inspection of Audita's published tag
+confirmed:
+
+| Identity | Object ID |
+| --- | --- |
+| Annotated `v3.1.0` tag object | `473d29007172cdb0a928e1dcc0556d3e8f469931` |
+| Source commit identified by that tag | `2d41748006d785bc3ee1350927ed5424feaf294b` |
+
+`git cat-file -t` identifies the first object as `tag`.
+`git rev-parse 'v3.1.0^{commit}'` returns the second object. The authoritative
+remote's tag and peeled-tag refs agree with these values.
+
+The existing example assigns `expected_commit` from the raw lowercased event
+ID, then compares it with `refs/tags/${CI_COMMIT_TAG}^{commit}`. Consequently,
+the script compares two different object identities and exits with status 1.
+Its multiline log contains the script text without an explanatory error from
+the failed `test`, which initially made the failure location unclear.
+
+## Minimal Reproduction
+
+In a checkout containing Audita's published `v3.1.0` tag:
+
+```sh
+CI_COMMIT_TAG=v3.1.0
+CI_COMMIT_SHA=473d29007172cdb0a928e1dcc0556d3e8f469931
+tag_commit=$(git rev-parse "refs/tags/${CI_COMMIT_TAG}^{commit}")
+expected_commit=$(printf '%s' "$CI_COMMIT_SHA" | tr '[:upper:]' '[:lower:]')
+test "$tag_commit" = "$expected_commit"
+```
+
+The final command fails. Resolving `${CI_COMMIT_SHA}^{commit}` instead returns
+the same source commit as the tag and makes the comparison succeed.
+
+## Recommended Correction
+
+After fetching the event tag, resolve the event object to its commit before
+comparison:
+
+```sh
+expected_commit=$(git rev-parse --verify "$${CI_COMMIT_SHA}^{commit}")
+```
+
+Continue comparing the event's resolved commit with the selected tag's peeled
+commit and checking the detached HEAD and clean worktree. Pass the resolved
+value to ReleaseKit:
+
+```sh
+--commit "$${expected_commit}"
+```
+
+The doubled dollar signs above preserve Woodpecker's existing interpolation
+escaping. Peeling the event ID independently preserves the mismatch check;
+simply replacing it with the selected tag's commit would discard that check.
+Both annotated tag object IDs and commit IDs resolve through this approach.
+ReleaseKit's CLI/API need no broader interpretation of `--commit`.
+
+Apply the correction consistently to:
+
+- [Module-selected tag delivery](../../examples/woodpecker/tag-delivery.yml),
+  the example Audita adopted.
+- [ReleaseKit source delivery](../../examples/woodpecker/releasekit-source-delivery.yml).
+- [Multi-module Woodpecker delivery](../../examples/multi-module/woodpecker.yml).
+- [Delivery consumer guidance](../consumers/delivery.md#woodpecker-tag-workflows),
+  including the separately installed-tool example that passes the raw event ID.
+  Review other maintained copies of the same bootstrap when implementing.
+
+## Verification and Consumer Resolution
+
+Use an offline Git fixture to execute the example bootstrap with an annotated
+tag-object event, an annotated tag's commit event, and a lightweight tag's commit
+event. Verify that the delivery invocation receives the peeled source commit
+and that an unrelated event commit is rejected before delivery. Stub tool
+bootstrap/delivery at the external boundary; hosted uploads or real credentials
+are unnecessary for this regression.
+
+Audita implemented this correction in commit
+[`7cd5edd65027c25fd3d1fd927695d403e9dd8311`](https://gitea.maximumdirect.net/eric/audita/src/commit/7cd5edd65027c25fd3d1fd927695d403e9dd8311).
+Its executable-workflow regression reproduced the annotated-tag failure before
+the fix, passed afterward, and retained the unrelated-commit rejection. The
+complete offline Audita suite also passed.
+
+Published tags and tagged workflows remain unchanged. Future consumers should
+receive corrected examples; retrying an existing tag's unchanged faulty workflow
+will still fail. Existing artifacts can be delivered from the original tagged
+source using the resolved commit ID through the documented delivery path,
+without moving the source tag or replacing published contents.