Design: what should verified mean on a squash-merging repository?

[0xLeif]

Note

Resolved for verification.commit. This is answered on main: verified means content agreement — the recorded plan and tree still match what was verified — and commit ancestry was never load-bearing on the readiness path. Fixed in #689, merged in #695, on main and not yet in a tagged release candidate.

Two claims in the original text below are now refuted, not merely stale: "there is currently no configuration that avoids it", and "the fix is a semantics decision, not a bug fix". ship_status_report was simply the last caller still asking a history question that every other currency path had already stopped asking.

What remains open is #694 — what a check should report when it cannot run. The options listed further down apply to #694 only, and two of the three have since been ruled out. That issue's own framing has also been substantially corrected against measurement; see the correction comment there.

The question

verification.commit is checked with merge-base --is-ancestor. A squash-merge rewrites that hash, so a change reads as unverified the moment its own PR lands.

Measured on an adopting repository: three invalidations of one change in a single day (CorvidLabs/site#244, #246, #247 — that repository's numbering, not this one's). Each one forced a full re-verify and a fresh independent review — the one step in the lifecycle that structurally requires a human.

There is currently no configuration that avoids it. On that repo:

mergeCommitAllowed: false
rebaseMergeAllowed:  false
squashMergeAllowed:  true

Rebase-merge is disabled at the repository level, and gh pr merge --rebase silently falls back to squash — no error, no warning. So an adopter can follow a documented "use rebase-merge" instruction exactly, believe they complied, and still land a squash.

Squash-only is a common posture for GitHub organisations. This is not an exotic configuration.

Tracked as #689, since fixed. It was framed here as a semantics decision rather than a bug fix; that framing was wrong, and the note at the top records why.

What has to be decided

verification.json already records content-addressed evidence alongside the hash:

{
  "commit":                  "f127446a...",   <- destroyed by squash
  "workspace_digest":        "1bbcc8e1...",   <- survives
  "acceptance_input_digest": "2b71cbcf...",   <- survives
  "acceptance_manifest": { "entries": [
      { "path": "specs/validator/context.md", "payload_digest": "c6b7498a..." }
  ]}
}

So the material for a content-based answer is already on disk. Feasibility is not the question. The question is what verified should mean.

basis	proves	survives squash
commit ancestry	verification ran at a reachable point in history	no
content agreement	the inputs are unchanged	yes

These are not equivalent guarantees. An attacker who can rewrite history cannot forge the first. The second is weaker.

But on a squash-only repository the first is unobtainable, so the real choice is weaker guarantee vs. no guarantee — not weaker vs. stronger.

Three options

1. Re-anchor on merge. When the recorded commit is unreachable but the recorded content still matches the tree, accept and rewrite the anchor. Keeps the strongest claim that survives a squash.
2. Content fallback. Treat workspace_digest / manifest agreement as sufficient freshness whenever ancestry is unavailable. Simpler, concedes the same thing more broadly.
3. Stop binding freshness to a hash at all, keeping commit as an informational correlation key. Cleanest model, largest change, concedes the most.

Precedent, and why this is not hypothetical

#677 corrected the archive anchor predicate for exactly this cause: it looked for .specsync/changes/<id>/state.json on the default branch, which a squash-merged workflow-v2 change never has, because finalize archives inside the same PR.

Measured across this repository's own history: 83 of 178 archives had the active path; 178 of 178 had the archive path. The fix asked the question that could actually be answered.

verification.commit ancestry is a different check with the same flaw from the same cause, and it has not been touched.

What would help

• If you run spec-sync on a squash-merging repo, does this match what you see?
• Does anyone rely on the history-reachability guarantee specifically, rather than on freshness generally? That is the thing option 1 preserves and option 3 gives up.
• Is there a fourth option — e.g. re-anchoring at merge time via a hook — that keeps the stronger guarantee rather than trading it away?

Interested in the security-model view most of all. The trade is small in code and large in meaning.

[0xLeif]

Correcting this post: the framing was wrong

I opened this asking which of two guarantees to keep, and asked for a security-model opinion on the trade. There is no trade. Two things settle it, and one of them was measurable from inside this repository the entire time.

1. This repository is squash-only, so the stronger option was never available here

I wrote the configuration block above as a property of an adopting repository. It is also a property of this one:

$ gh api repos/CorvidLabs/spec-sync --jq '{merge:.allow_merge_commit,squash:.allow_squash_merge,rebase:.allow_rebase_merge}'
{"merge":false,"rebase":false,"squash":true}

Re-measured against this repository's own archives just now:

archived changes citing a verification commit : 176
  reachable from origin/main                  :  19   (11%)
  cited object no longer in the object store  :   3
merge commits on origin/main                  :   3 of 495

#689 recorded 19 of 178 yesterday. The numerator has not moved; only the denominator has.

So the table row labelled commit ancestry / survives squash: no is not a stronger guarantee we would be conceding. It describes a property this project has held one time in nine across its whole history, and never once by design. The choice is not weaker versus stronger. It is weaker versus none.

I also had that 11% figure before writing this post, and used it to justify the #677 fix, and still framed the same cause as an adopter's configuration when it appeared on verification.commit.

2. The readiness half was not a semantics decision either

I wrote that "the fix is a semantics decision, not a bug fix, and it should not be made by whoever happens to be implementing." Also wrong. change.rs had already removed the ancestry walk from its currency paths, with the reasoning recorded inline at src/change.rs:5808:

Commit identity and ancestry are deliberately not checked here. verification.commit remains recorded as an informational correlation key [...] It is also what made squash-merged changes permanently unfinalizable.

verification_is_current has answered the content question ever since. ship_status_report was the one caller that never got the change. There was no semantics to decide, only a caller to fix.

An adversarial survey run alongside that fix also established that verification.commit ancestry is not load-bearing for trust on this path: it is a self-declared string, never resolved to a tree, never compared against workspace_digest, checked for membership of a set whose contents an attacker chooses. Nothing was conceded because nothing was there.

The fix is merged in #695, on main and not yet in a tagged release candidate. Measured across all three merge strategies:

strategy	verification commit still an ancestor	ship-status
squash	no	ready to finalize
rebase	yes	ready to finalize
merge commit	yes	ready to finalize

Rebase and merge-commit are the control, not the fix. They show that nothing which worked was broken.

What is still open is narrower, and it is #694

Options 1 to 3 in the post above should now be read as applying only to that issue, because the check it concerns is genuinely different from the one I was writing about.

review_commit_is_current_checked (src/change.rs:5687) is not ancestry wearing a trust costume. It walks every commit between review.implementation_commit and HEAD and requires every changed path to sit under this change's own workspace:

let allowed_prefix = git_repo_relative_path(root, &format!("{CHANGES_PATH}/{}/", record.id))?;

So it proves that between the review and HEAD, nothing moved except this change's own lifecycle records. That covers .specsync/changes/ and .specsync/archive/, which is precisely the region project_input_is_volatile (src/change.rs:10493) excludes from workspace_digest. Content digests cannot see it, by design. Delete the walk and that guarantee disappears silently.

The defect is not "which guarantee do we keep". A squash destroys review.implementation_commit, so the walk cannot run at all. The guarantee is not violated, it is unavailable, and the code treats those two states as identical and fails closed forever.

Measured here: 0 of 107 passing (2 reachable) archived reviews cite an implementation commit reachable from origin/main. The walk has been inert for 100% of this repository's history already. It simply fails loudly instead of admitting it cannot answer.

It also wedges. record_scoped_review requires Verifying (src/change.rs:5849), so a squash-merged change that has already reached accepted has no forward verb at all. That is #690.

The question I should have asked

Not what should verified mean. That one is answered: content, because ancestry is unavailable here by default and was never load-bearing on the readiness path.

The open question is what a check should report when it cannot run. Three candidates on #694, none chosen:

1. Fall back to the content checks that do still run, and state plainly that the descendant guarantee was unavailable. An unavailable guarantee reported as a satisfied one is worse than the current failure.
2. Re-anchor the review at finalize, as accept_change_with_gate (src/change.rs:5934) already does for verification.commit under allow_verified_tree_adoption. That keeps a walk, but over a window that no longer spans the reviewed work, so what the window still proves needs establishing rather than assuming.
3. Move the region into a scoped digest. .specsync/changes/ and .specsync/archive/ are volatile by design, but a digest scoped to other changes' records may be tractable, and would survive any merge strategy.

If you run spec-sync anywhere, the useful data point is no longer "does this match what you see". It is whether option 1's disclosure would be enough for you, or whether you rely on the guarantee itself and would accept option 3's cost to keep it.

---

Correction (later). Two things above have been overtaken by measurement. The scoped-review walk does not merely fail sometimes on a squash repository — it passes 0 of 107 archived reviews, because archiving relocates the workspace out from under the walk's own path allowlist, so every change that ships fails its own walk forever after. And the walk never reads a blob: its whole vocabulary is rev-parse, merge-base --is-ancestor, rev-list and diff-tree --name-only, so it asserts history shape, not content — the same signature used to convict verification.commit in #689. Re-running change review also does re-anchor, so the "no forward verb" claim was wrong. Full correction on #694.

[0xLeif]

The readiness half is no longer "on main and not yet in a tagged release candidate." It is in 6.0.0, tagged 2026-09-09 (#689 / #695).

Nothing in the correction comment above has been un-corrected. verified on the readiness path means content agreement. Ancestry was never load-bearing there. Squash, rebase, and merge-commit all reach ready to finalize.

What remains is still #694, and the options in the original post should not be used to decide it. The issue's correction comment ruled out options 2 and 3 against measurement:

• the walk passes 0 of 106 archived reviews, because archiving relocates the workspace out from under its own allowlist — inert by construction, not "inert for 98%"
• it never reads a blob, so it is verification.commit ancestry is incompatible with squash-only repositories, and there is no available workaround #689's history-shape check again, not a different kind of guarantee
• re-anchoring at finalize (option 2) makes the window HEAD..HEAD, a check that cannot fail
• a scoped digest (option 3) is forbidden by Invariant 22 in as many words

The option that is actually left was not in this thread: bind the delta bodies into the review digest (option 4 on #694). That is the one property the walk uniquely protected, the walk does not actually protect it, and a digest over those bodies survives every merge strategy without claiming a topology it cannot see.

If you run spec-sync on a squash-merging repo and you were waiting on this thread to tell you whether 6.0 is safe to adopt: the readiness trap this post opened with does not fire on 6.0.0. Archive on the PR before you merge; that rule did not go away. The remaining question is whether option 4 is enough for the review guarantee, and that question belongs on #694 rather than here.