# Commit-bound plugin verification

This reference summarizes the official verification model observed on 2026-08-21. Always refresh `VERIFICATION.md`, `SUBMISSION.md`, and the live verification issue template before acting.

## Meaning and boundary

Verification binds marketplace evidence to one exact repository commit. It is not a security audit, certification, warranty, endorsement, or guarantee that a plugin is safe. Community plugins remain unsandboxed third-party code.

A branch name, release name, version string, or current repository state is not a substitute for the required full 40-character commit SHA.

## New listing

A correctly formatted submission triggers compatibility validation and an Automated Security Baseline against the exact validated commit without executing plugin code.

Current baseline outcomes:

- `passed` — complete scan with no findings or review capabilities;
- `review-required` — current policy permits a narrowly scoped maintainer review of the exact reported capabilities and non-blocking findings;
- `needs-fixes` — repository changes and a newly validated commit are required;
- scan error, stale report, or evidence mismatch — fail closed.

A new listing is published only through the current `approved-and-verified` workflow. A clean current `passed` result can become Verified automatically through that publication path. A selective `review-required` result needs an authorized maintainer's exact-evidence acceptance. Blocking findings and incomplete scans prevent publication.

The historical `approved-for-listing` label does not publish new submissions.

## Verify a currently listed snapshot

Use **Verify the currently listed snapshot** only when targeting the exact commit already stored as `listingValidatedCommit`.

Required values:

- exact existing plugin ID;
- existing public GitHub repository root URL;
- full recorded `listingValidatedCommit`.

A clean complete result can publish snapshot verification automatically. Capability-only `review-required` may require the narrowly authorized `maintainer-verified` path. Findings, scan failures, stale evidence, or mismatches remain Unverified. Unverified is not an assertion that the plugin is malicious.

## Publish a newer upstream commit

Use **Verify and publish a newer upstream commit** for an existing listing whose repository HEAD should replace the marketplace snapshot.

Required values:

- exact existing plugin ID;
- existing public GitHub repository root URL;
- full 40-character current repository HEAD SHA.

The configured plugin ID set must remain unchanged. Multi-plugin repositories are promoted source-wide. The existing marketplace snapshot remains active while the update is pending.

Validation and the baseline scan the requested commit. Publication performs a fresh scan and requires exact agreement across repository, plugin set, policy, outcome, findings, capabilities, report, approval event, and reviewer evidence. Successful promotion atomically replaces the current snapshot while retaining superseded evidence in history.

## Update-unverified state

Scheduled catalog refreshes may observe that repository branch HEAD differs from the verified snapshot. The marketplace can display `Update unverified`; existing verification evidence continues to describe only the previously approved exact commit.

Use the newer-upstream verification action to promote the changed commit. Do not imply that an old verification result covers new code.

## Handling failures

- Read the current bot-authored validation, baseline, and publication comments.
- Do not open duplicate issues for retries.
- Fix the repository or existing issue, commit and push, then capture the new SHA.
- Obtain owner approval before editing an issue to trigger another run.
- Confirm that reports and approval events bind to the same intended commit.
- If registration succeeded but deployment or issue finalization failed, ask a maintainer to retry the publication phase; do not resubmit or reapply approval blindly.