Scope retained G2 evidence validity to the attested contract surface

[BunsDev]

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.

[BunsDev]

Candidate trust-root implementation opened

Draft PR #17 is now open at exact candidate head 54eee3a51da7b257d397e523c4a2ade10de83bc1.

The candidate:

• preserves the original checker core byte-for-byte as scripts/check-g2-evidence-v1.py;
• adds psyche.g2-attestation-scope/v1 with default: protected;
• permits only ten exact readiness/governance paths with constrained operations and Git modes;
• compares exact tree entries locally and through GitHub commit/tree APIs;
• rejects protected/unknown changes, deletions, mode changes, symlinks, submodules, renames, copies, duplicate/unsafe paths, and truncated trees;
• adds a focused 15-case regression suite and one reviewed CI step;
• leaves docs/G2-SCOPE-EVIDENCE.md at candidate until the complete exact-head workflow passes.

No Rust, protocol, schema, migration, fixture, dependency, lockfile, toolchain, test-manifest, or historic G2 evidence content changed.

The issue remains open. Required next gate: candidate CI success across all Rust/platform, conformance, crash/migration, evidence, supply-chain, secret, and npm jobs; then an evidence-only scope attestation commit and a second complete run.