[narenaryan]

Summary

Related to #58. Adds an opt-in --verify-provenance path shared by audit, autofix, upgrade and upgrade-all-sha. Existing immutability-only defaults remain unchanged.

• Resolve exact refs and annotated tags; retain canonical repository name and stable numeric repository ID.
• Verify full-SHA reachability from a current upstream branch snapshot. A successful commit lookup or a tag alone is never membership proof.
• Keep versioned historical observations separately from the ordinary SHA cache; report identity mismatch, old/new ref movement, resolved namespace, check time and exact supporting refs.
• Explain expected forward major-tag/branch advancement while requiring review for identity replacement, force movement, patch-tag changes and tag/branch namespace changes.
• Bound API requests, response sizes, pagination, redirects, tag peeling and timeouts. Offline, unavailable and stale evidence stay unverified.
• Audit existing pins and preserve evidence in human, JSON and SARIF output. Preflight autofix/upgrade provenance before writing workflow changes.

Validation

Run with the approved official Go 1.26.9 toolchain:

• gofmt on changed Go files; formatting check clean
• go test ./... passed across all six packages
• go vet ./... passed
• go test -race ./... passed across all six packages
• go build ./... passed
• git diff --check passed
• 22 HTTP-fake resolver tests, 16 scanner tests and 10 CLI tests added
• Independent static review findings corrected and re-reviewed, including cross-ref identity binding and tag-to-branch substitution
• Published Git tree matched the exact tested local tree: 57a0ca9cec1d6e0a0cfacd88bfaa0a832dfeecc7

goimports, golangci-lint and govulncheck were unavailable and were not downloaded. Their checks have not run locally. The initial head passed GitHub Actions unit tests, Semgrep, binary-size comparison and Semaphore's Scharf CI pipeline. The revised head below is being checked separately.

Deliberate limits / review points

Verification means point-in-time reachability from current upstream branch histories, not benign code or trusted maintainers. Tag-only releases and deleted/rewritten histories can remain unverified. Identity history is trust-on-first-use in the local observation file. Suspicious re-baselining remains a manual review step.

This covers directly scanned workflow references. Recursive dependency provenance and combining verification with the separately proposed dependency-graph audit are unsupported; integration of the parallel #56 work must retain an explicit combined-mode guard.

See docs/provenance.md and ADR 005 for the evidence model, limits and review process. Keep this PR in draft for maintainer review; this description intentionally does not auto-close #58.

AI bug-pattern reassessment (October 8, 2026)

Applied ai-bug-patterns to TOCTOU, fail-closed, cache/history and alternate command paths. Two reproduced bug classes are fixed:

• Workflow files could change during network verification: autofix accepted unchecked additions and upgrade-all overwrote concurrent edits. The complete scanned file set and bytes are now revalidated before planned writes, including dry runs, with per-file rechecks.
• Repository owner/name paths could be replaced after the first stable-ID read, mixing one repository's identity with another's branch evidence. Requested and distinct canonical paths are now rechecked within existing budgets before evidence is persisted or accepted.

33 regression scenarios cover stale/added/removed workflows, requested/canonical identity replacement, final-check failures, history preservation and exhausted request budgets. Full unit/race tests, vet, build, module verification, formatting and whitespace checks pass on tree c1562a3ed121bea85bcab396dbe08b650d68eca1. Revised head e6e3ce17be51a5bf09209b244eee57184721dd63 passed GitHub unit tests, Semgrep, binary-size comparison and Semaphore.

Limits remain explicit: GitHub API calls are not an atomic snapshot and cannot detect an ABA identity transition between reads; filesystem checks do not lock the working tree or make multi-file writes transactional. No live action payload was executed or additional tool installed.

The revised #61/#62 heads also form conflict-free local merge-tree 7d43701bcf888efe312e26ac33c98f436c2cef29, which passed unit tests, race tests and vet, plus an archive build with -buildvcs=false. This is integration evidence only; no PR was merged.