fix(update): safely replace reviewed local drift

[Wibias]

Summary

Fix self-update handling for managed installations with local drift.

Two safe paths are added:

1. Automatic target convergence: a local regular file that differs from the installed manifest no longer blocks a newer release when its current SHA-256 already exactly matches the same path in the verified target release.
2. Explicit reviewed replacement: remaining local modifications still block by default, but the user may intentionally choose the verified target with:
   npx github-delivery update --apply --replace-local-modifications

The explicit path keeps --force disabled and uses the existing staged install + full-installation backup/rollback machinery.

Why

The uploaded installation showed a mixed state: the compatibility redirect files already match changes shipped in 1.5.4, while the main installed SKILL.md is an intermediate local state rather than byte-identical to the current release. Treating every installed-manifest mismatch as permanently unreplaceable leaves such installations unable to return to the verified release line.

Safety boundary

Default behavior remains fail-closed.

Automatic convergence requires:

• a newer verified release
• modification reason changed or local_file
• a regular local file
• the same path in the verified target manifest
• exact SHA-256 equality with that target entry

Missing files, mode changes, non-regular substitutions, target-absent files, and different content remain blocking.

The explicit replacement flag:

• is valid only for update --apply
• is rejected for dry-run or ordinary install
• works only after the stable release candidate has passed the existing release verification path
• never sets installer force
• preserves the complete previous target as the normal update backup before replacement

TDD evidence

Initial RED on 132d103cd3b75090750bd5b785d8887af67652c5:

• verified target manifest was not passed into update planning
• target-identical local drift still returned blocked_local_modifications
• blocking/converged classifications did not exist
• 1951 tests passed, 3 expected regressions failed, 1 skipped

Explicit-authorization RED on 1d7a8f3b53209a7d9775fa8ad42d53879799ec0d:

• public parser rejected --replace-local-modifications
• installed parser rejected the flag
• bootstrap did not forward it
• blocked local drift could not reach the verified installer
• the normal default-blocking regression remained intact

Current implementation head: 308222e86b43be4505e7cf38d10d178b8fb88e74.

Current verification:

• canonical repository checks / Node 24: success
• Node 22 compatibility: success
• Node 26 compatibility: success
• Dependency Review: success
• Windows trace bins: success
• CodeRabbit: success
• CodeQL: pending on the final head

Release impact

Because this PR adds the new supported public CLI option --replace-local-modifications, its highest observable SemVer impact is MINOR. The follow-up release after v1.5.4 is therefore 1.6.0, not 1.5.5. PR #458 is also unreleased and belongs in that same release delta.

Scope

Self-update planning, explicit update authorization wiring, focused regressions, and user-facing update documentation.

No merge, tag, GitHub Release, npm publication, or release publication is authorized by this PR.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: a7b02a5a-f2bd-4218-84a8-4b2fab41b4e4

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}