fix(cli): tree-canonical range hash for CI verify

[chtnnh]

Summary

• Make range hashing tree-canonical (fromOid^{tree} → write-tree) so pass-time trailers match CI after know-code commit without trusting gitignored seals.
• Pin know-code CI/init workflow to the PR tip (head.sha), write requireTrailer: true, and add npm run smoke:verify (CI-shaped e2e).
• Document the verify contract in website/docs/verify.md; tighten ci.md / how-it-works.md.

Closes #8

Test plan

• npm test
• npm run smoke
• npm run smoke:verify
• Confirm GitHub know-code check is green on this PR (tip trailer = merge-base..HEAD)

[cursor]

PR Summary

Medium Risk
Changes the range diff hash formula and gate drift semantics, which can break PRs or local gates that relied on the old patch+staged hash; CI workflow checkout behavior also changes for all PR verify runs.

Overview
Range hashing is now tree-canonical (fromOid^{tree} → write-tree), so the pass-time Know-Code-Verified trailer still matches know-code verify after know-code commit without gitignored seals or commit-drift candidates. Local gate tests expect no commit drift when the gated tree is unchanged across staged → committed and pathspec slice commits.

CI and onboarding check out the PR tip (github.event.pull_request.head.sha), ensure requireTrailer: true in the monorepo workflow, and add npm run smoke:verify (scripts/smoke-verify-ci.sh) — full quiz flow, strip local artifacts, assert verify passes. init --workflow and the composite action description document the PR-tip checkout requirement.

Docs: new Verification design page (verify.md) plus updates to ci.md and how-it-works.md for grounded CI checks and tree-stable range hashes.

^{Reviewed by Cursor Bugbot for commit 9e1f785. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9e1f785. Configure here.}

[cursor]

Range hash skips lock-safe write-tree

Medium Severity

computeRangeDiffContext now depends on write-tree for the tree-canonical tip, but calls raw git write-tree with an EMPTY_TREE fallback instead of indexTreeOid. Under pre-commit index.lock, that failure yields a wrong range hash (empty-tree material) rather than the real index tree the rest of the gate path already resolves lock-safely.

 

^{Reviewed by Cursor Bugbot for commit 9e1f785. Configure here.}