Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/user/cli-reference.md`:
- Around line 2654-2656: Add the missing blank line before the fenced synopsis
block in the evidence sign section so the Markdown follows the
blanks-around-fences rule. Update the nearby “Synopsis” content in the docs to
place an empty line between the bold label and the ```shell fence, keeping the
existing `aicr evidence sign <pointer> [flags]` snippet unchanged.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pkg/cli/evidence.go`:
- Around line 40-47: The top-level evidence usage summary is missing the new
sign subcommand, so update the usage/help text in the evidence command setup to
list sign alongside digest, publish, and verify. Make sure the string that feeds
aicr evidence --help is kept in sync with the Commands slice in the evidence
command definition, including evidenceSignCmd().

In `@pkg/evidence/attestation/emit.go`:
- Around line 389-392: The comment around PointerSignerFromSignature and the
helper’s own docstring are inaccurate about zero-Rekor handling; update both to
match the actual behavior that only RekorLogIndex values greater than 0 are
preserved and index 0 is treated the same as absent. Use the
PointerSignerFromSignature helper and the in.Signer assignment in emit.go to
locate the wording, and revise the text so it no longer claims index 0 is
distinguished from “no Rekor entry.”

In `@pkg/evidence/attestation/sign.go`:
- Around line 78-91: `SignExisting` in `pkg/evidence/attestation/sign.go` still
allows mutating `Attestations[0]` without enforcing the unsigned
single-attestation invariant. Add input validation in `SignExisting` (and/or its
helper path) to reject more than one attestation, reject any existing signer,
and require a non-empty `Bundle.Digest` before proceeding; keep the checks
alongside the existing `opts.Pointer`, `PointerPath`, and `Artifact` validations
so non-CLI callers cannot accidentally clobber provenance.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pkg/evidence/attestation/pointer.go`:
- Around line 89-96: WritePointerFile currently uses os.WriteFile, which can
leave a partially written Pointer file if the process or filesystem fails
mid-write. Update WritePointerFile to write MarshalPointer(p) to a temp file in
the same directory, ensure the temp file is closed with Close() error checking,
then atomically replace the target with rename and preserve the existing error
wrapping in the WritePointerFile path.

---

Outside diff comments:
In `@pkg/cli/evidence.go`:
- Around line 28-43: Update the parent help text in the evidence CLI to match
the current behavior of sign and publish. In the Cobra command setup for the
evidence command, adjust the Description sentence that currently says only
publish reaches the OCI registry and Sigstore so it also mentions sign, keeping
the summary consistent with the subcommand list and the sign/publish flow.

---

Duplicate comments:
In `@pkg/evidence/attestation/sign.go`:
- Around line 92-100: The signing flow in sign.Bundle should validate that the
pointer bundle digest matches opts.Artifact.Digest before proceeding, since
BuildArtifactStatement and AttachSigstoreBundleAsReferrer currently sign the
artifact descriptor while leaving att.Bundle.Digest unchanged. Add a digest
equality check in the existing precondition block, returning an invalid request
error when att.Bundle.Digest and opts.Artifact.Digest differ, so only matching
pointer/artifact pairs can be signed and attached.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pkg/cli/evidence_sign.go`:
- Around line 98-102: The evidence signing command currently only reads
cmd.Args().First() in evidence_sign.go, so extra positional arguments are
ignored and can lead to signing the wrong pointer. Update the argument
validation in the sign command to enforce exactly one positional argument before
proceeding, and return an invalid-request error when the arg count is not one so
the ArgsUsage contract for a single <pointer> is respected.

In `@pkg/evidence/attestation/sign_test.go`:
- Around line 61-70: The negative-path tests in SignExisting currently only
check for a non-nil error, which can miss regressions in validation behavior.
Update the table-driven cases in sign_test.go to include the expected structured
error code for each scenario, then assert the returned error with errors.Is(...)
in the SignExisting test cases rather than only calling t.Fatalf on nil. Use the
existing SignExisting, SignExistingOptions, and the test case fields around
tt.name, tt.pointer, and tt.path to locate and extend the assertions.

---

Duplicate comments:
In `@pkg/evidence/attestation/sign.go`:
- Around line 92-108: SignExisting currently checks that both the pointer bundle
digest and the artifact descriptor digest are present, but it does not verify
they refer to the same artifact before signing. In sign.go, update SignExisting
to compare att.Bundle.Digest against opts.Artifact.Digest (using the existing
digest normalization style in this flow) and return an invalid-request error
when they differ, before loadOnDiskBundle and BuildArtifactStatement are used.
Keep the check close to the existing validation for reference, digest, and
artifact descriptor so mismatches are rejected before any signing or referrer
attachment happens.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pkg/cli/evidence_sign.go`:
- Around line 167-188: Move the signable-pointer validation out of the CLI
layer: `assertUnsignedSignable` in `pkg/cli/evidence_sign.go` duplicates the
invariant already enforced by `attestation.SignExisting`. Add or export a
validator from `pkg/evidence/attestation` (near `SignExisting` in `sign.go`) and
make the CLI call that shared check instead of maintaining its own business
rule. Keep `pkg/cli` focused on wiring, and update any CLI tests to exercise the
shared attestation validation path.

In `@pkg/evidence/attestation/sign.go`:
- Around line 145-148: Avoid updating opts.Pointer.Attestations[0].Signer before
WritePointerFile succeeds, because signPointer currently mutates the caller’s
in-memory pointer too early. In signPointer, keep the patched signer in a
temporary local copy, write that copy through WritePointerFile, and only assign
back to opts.Pointer after the write completes successfully. Make sure the retry
path and the att.Signer nil guard remain based on the original pointer state
until persistence is confirmed.

---

Duplicate comments:
In `@pkg/evidence/attestation/sign.go`:
- Around line 92-109: Reject pointer/artifact digest mismatches in the signing
flow by validating that opts.Artifact.Digest matches att.Bundle.Digest before
BuildArtifactStatement or any referrer attachment in sign.go; if they differ,
return an invalid request error and avoid signing. Keep the check near the
existing bundle/artifact validation in the sign path so the pointer updated by
the caller remains consistent with the artifact actually signed.