Scope retained G2 evidence validity to the attested contract surface #16

Outcome

Preserve the integrity of Psyche's retained G2 attestation while allowing unrelated repository-readiness, governance, and operational documentation to evolve.

Parent roadmap: #9
Blocks: #10 and draft PR #15
Related governance: #14
Priority: P0 correctness blocker
Accountable owner: @BunsDev

Defect observed on 2026-08-26

Draft PR #15 changes only repository onboarding, roadmap, ownership, governance, metadata, and verification-wrapper files. Rust formatting, clippy, workspace tests, state-machine tests, reusable conformance, migrations, crash recovery, fault-injection clippy, evidence-checker unit tests, npm distribution, dependency audit, and secret scanning pass on the tested jobs.

The G2 evidence relationships step fails because the passed-evidence verifier requires the historic tested source commit to be the pull-request head's merge-base and requires the entire tested-source-to-head diff to contain exactly one modified file: docs/G2-EVIDENCE.md.

That rule correctly protected the original evidence-only attestation PR, but when applied forever it prevents every later non-evidence repository change. It binds the historic G2 attestation to the entire future repository tree rather than the contract surface the attestation actually proves.

Required security property

Do not disable or bypass G2 validation.

A retained G2 attestation remains valid only when every attested source, schema, test, migration, fixture, manifest, workflow, checker, toolchain, dependency, and relevant architecture/evidence artifact remains unchanged from the tested source.

Changes outside that explicitly reviewed scope may coexist with the historic attestation, but must not be described as covered by it.

Proposed design

Introduce a versioned, fail-closed G2 attestation-scope manifest and make the relationship verifier compare the tested commit to the current terminal commit by scope:

• protected path patterns enumerate the complete G2-attested contract surface;
• explicitly unscoped operational/readiness paths may change without refreshing G2 evidence;
• new or unmatched paths default to protected unless explicitly classified;
• the scope manifest, checker, checker tests, workflow, evidence document, test manifest, toolchain, lockfile, and dependency policy are themselves protected;
• any protected-path change invalidates Status: passed until a new candidate/attestation replaces it;
• changing only the evidence document remains subject to the original exact evidence-only relationship rules;
• local and GitHub Actions verification use the same classification logic;
• diagnostics list the protected paths that invalidated the attestation without leaking protected contents.

A smaller equivalent design is acceptable only if it preserves the same fail-closed guarantees and is comprehensively tested.

Initial protected surface

At minimum, classify as G2-protected:

• crates/**;
• packages/psyche-npm/** where included in the attested CI contract;
• .github/workflows/ci.yml;
• Cargo.toml, Cargo.lock, rust-toolchain.toml, deny.toml;
• scripts/check-g2-evidence.py;
• scripts/check-g2-evidence-test.py;
• scripts/g2-test-manifest.json;
• the scope manifest itself;
• docs/G2-EVIDENCE.md;
• the approved G2 plan and protocol/schema/testing/architecture documents referenced by the checker;
• all golden fixtures and migration fixtures.

The implementation must derive the exact list from the current checker, manifest, workflow, and repository tree rather than relying solely on this issue's examples.

Acceptance criteria

• A focused test reproduces the current freeze: an unrelated readiness file causes the old relationship rule to fail.
• A focused test proves an explicitly unscoped readiness/governance-only delta preserves the historic G2 attestation.
• Mutations to psyche-core, store/migrations, Coven bindings, test support/conformance, golden fixtures, CI, workflow setup/actions, lock/toolchain/dependency policy, the evidence checker, its tests, its manifest, or the scope policy invalidate the attestation.
• An unknown/new path defaults to protected or is rejected until explicitly classified.
• Renames, deletes, copies, submodule changes, and truncated compare responses fail closed.
• Pull-request and local verification agree.
• The original evidence-only attestation path remains valid and tested.
• docs/G2-EVIDENCE.md continues to identify the exact historic source commit and CI run; it is not silently rewritten to bless unrelated changes.
• The checker still validates every existing source hash, command, matrix row, workflow invariant, manifest relationship, CI attestation, and evidence field.
• Draft PR Establish Psyche roadmap and agent-readiness foundation #15 passes this gate without claiming its new files were covered by G2.
• Exact-head CI is green on Linux, macOS, and Windows.

Non-goals

• Re-attesting G2 merely because onboarding docs changed.
• Treating all documentation as safe by default.
• Removing remote provenance validation.
• Weakening source hashes, command hashes, workflow hashes, conformance vectors, or negative tests.
• Folding the protocol-v1 publication work from Publish Psyche protocol v1 schemas, golden vectors, and conformance runner #11 into this repair.

Delivery and review

Implement as a separate focused PR from #15 because this change touches the evidence trust root. Link the failing run, focused regression tests, scope inventory, exact-head CI, and final reviewed commit here. After merge, rebase/re-run #15 and reconcile #10/#14.