The Git Snapshot Behind a Code Quiz

I captured a pending push check, edited the source file, and staged the edit. The original snapshot still validated. Then I committed the edit. Validation returned false.

For a pending commit check, the boundary was different. An unstaged source edit preserved validity; staging that edit invalidated the check. These results are consistent with what Git would send or commit. The directory on screen is not the operation's entire input.

Sphinx uses a model to ask developers questions about agent-assisted changes before a protected Git operation continues. Its interesting engineering is beneath that questionnaire: a completion belongs to particular Git content, a destination, and an effective local policy. Treating a passing answer as a reusable boolean would lose those boundaries.

I examined version 0.1.4 at revision 4767df03ef5ab8234b10f11094c56a1885e6be1a. The replay used Linux, Node 24.19.0, and Git 2.52.0. All source changes below are synthetic local fixtures. No reviewer model, browser questionnaire, or external model account participated.

Capture the Operation Before Asking Questions

The implementation separates Git evidence, session persistence, hook installation, presentation, and model evaluation. It includes browser and native-client integrations, provider transports, and a substantial test directory. This is executable workflow code rather than only a questionnaire prompt.

The package manifest requires Node 22.19.0 or newer and pins two Pi dependencies to 1.2.0. Those dependencies serve the model path. The snapshot module and its three local dependencies use Node built-ins, so the narrow replay needed no package installation. I retrieved the pinned source files directly and executed them unchanged.

For a push, pushSnapshots consumes Git's four-field pre-push input:

<local-ref> <local-object> <destination-ref> <destination-object>

The destination branch decides whether the policy applies. Pushing a feature branch into a protected main is different from pushing main into an unprotected preview branch. Deletions, unchanged object IDs, and non-branch destinations are skipped by this collector.

For an existing destination, Sphinx compares its supplied old object directly with the new head. It does not substitute a merge base. If the destination commit is unavailable locally, collection fails with fetch instructions instead of quietly changing the comparison. Initial pushes use an empty-tree comparison.

The snapshot records paths and counts without eagerly loading the patch. Source inspection shows Git invocations disable external diff and text conversion. Later reviewer tools operate against the captured evidence boundary; the initial snapshot is not a dump of the developer's working directory.

Identity Includes More Than the Tree

The version-two identifier hashes a structure containing repository identity, event, destination, base, head, tree, effective policy, ignore-policy hash, and project-context hash. Repository identity comes from the common Git directory, so this is local checkpoint state rather than a portable certificate.

That design makes two pushes of the same commit distinct when their destination branch or URL differs. It also prevents a changed review policy from silently inheriting a completion created under the old policy.

For pre-commit checks, Sphinx reconstructs staged entries and records an index identity. It checks that HEAD and the staged inventory stayed stable during collection. This handles partial staging: the source file visible in an editor may already contain changes that are absent from the index.

The replay probe verifies SHA-256 hashes for the four snapshot-path modules, creates a temporary repository, and asserts ten results. From the portfolio checkout, I ran:

node public/blog/git-snapshot-behind-code-quiz/snapshot-probe.mjs /tmp/sphinx-note

It exited zero. The fixture starts with two commits to app.js, captures a push from the first to the second, and then changes one input at a time:

Mutation or comparison	Observed result
Original push, unchanged inputs	Valid
Same content, destination main changed to master	Different snapshot ID
Same content, different destination URL	Different snapshot ID
Ordinary source edited but not staged	Push remains valid
Ordinary source staged but not committed	Push remains valid
Ordinary source edited after a commit snapshot	Commit remains valid
That edit then staged	Commit snapshot becomes invalid
Effective policy level changed	Push snapshot becomes invalid
Project-context file added	Push snapshot becomes invalid
Source branch advanced by a new commit	Push snapshot becomes invalid

The destination URL strings are synthetic identity inputs; this probe never contacts a remote. “Valid” here means revalidateSnapshot() returned true. It does not mean the developer answered a question or received approval.

Selected terminal output was:

Node 24.19.0; git version 2.52.0
unstaged source edit keeps push valid: true
staged source edit keeps push valid: true
unstaged source edit keeps commit valid: true
index edit keeps commit valid: false
advanced source ref keeps push valid: false
PASS: 10 snapshot assertions

Project context is a deliberate exception to ordinary unstaged source behavior. .sphinxcontext.md helps define the review, so changing its effective contents invalidates a pending snapshot even without a new commit. The ignore policy is similarly part of the checkpoint contract.

A Finished Form Is Only a Wake-Up Signal

In the Git gate, a questionnaire result of passed does not directly release the operation. The final loop reloads configuration, revalidates each original snapshot, and asks the session store for a valid completion. This includes destinations that were already approved before another destination's questionnaire began.

That is a code-inspection finding. It is an important separation: presentation tells the waiting process to look again; persisted state authorizes continuation. The session store checks passed status, matching policy, and receipt expiry. Its approval read uses the same assessment lock as the writer, preventing a reader from observing a transient receipt while cancellation rolls it back.

I ran the focused upstream tests with Node's test isolation disabled so the individual results were visible:

cd /tmp/sphinx-note
node --test --test-isolation=none --test-reporter=spec \
  test/git.test.js test/receipt-race.test.js

ℹ tests 25
ℹ pass 25
ℹ fail 0

The command exited zero. These are 24 Git snapshot tests and one receipt-race test. They cover destination identity, staged content, context changes, filtering, and the receipt read/write boundary. The receipt test injects generation and grading functions; it does not use a real model.

The Wider Hook Run Was Not Green

I also ran test/git-continuation.test.js with the same runner options. That command exited one, reporting 22 tests, nine passes, and 13 failures, including nested test results. The fixtures use temporary repositories and local bare remotes with a simulated questionnaire and approval store.

Some failures expected a diagnostic that was missing from captured stderr. For example, the source-change case saw a failed push but did not see the expected changed while Git was waiting text. Other failures occurred when pre-commit fixtures exited before the questionnaire opened. I did not establish the cause, so these results do not support calling the installed hook flow fully validated in this environment.

The narrower finding still holds: the unchanged snapshot helpers distinguish committed content from the index and ordinary working-tree edits, and the focused receipt-race test passes. Full installation behavior, native-client handoffs, and model grading remain outside that successful verification.

A code quiz also cannot prove unaided understanding. The project's own documentation describes local bypasses and warns that the examiner can be wrong. The useful contract is more modest: when a completion is reused, the system can identify which content and destination it belongs to. That is a concrete property to preserve even when the questions themselves remain probabilistic.