feat(history): git-history overlay on copy-mode bindings

[srnnkls]

Summary

Adds an opt-in git-history overlay for copy-mode target bindings. The deployment stays a normal copy artifact — staged, hashed, verified, pruned by the existing machinery — and phora additionally writes the git admin overlay so git log, git blame, and git status work inside the deployment.

• Binding-local history = true, keyed per target binding; one source can be ordinary for one target and history-enabled for another
• phora add --history <source> --to <target> and phora bind <source> --history --to a --to b
• Whole-root projection, mirror administration, and pin refs backed by the shared bare mirror
• Overlay observation, reporting in list/verify, and an overlay-only rewrite action
• Full lifecycle: prune, eject-detach, fast-forward drop, history on/off reshape, rebuild, and mirror sweep
• README documentation covering the model, examples, and limitations

[Copilot]

🟡 Changes recommended

The new history overlay path validation rejects std::path::Component::Prefix(_), which breaks all absolute paths on Windows and likely prevents history overlays from working cross-platform.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Implements an opt-in “history overlay” for copy-mode bindings so deployments remain content-verified artifacts while also exposing Git metadata (worktree admin + .git link) enabling git log/blame/status inside the deployed directory.

Changes:

• Adds Binding.history and a Materialization::WholeRoot path to deploy the full repo at the binding identity and manage a linked-worktree overlay lifecycle (observe/rewrite/retire/prune/sweep).
• Extends sync state/verification to track entry kinds (file vs symlink) and to report overlay health separately from content verification.
• Updates CLI (add --history, bind --history --to ...) plus extensive tests and README docs.

File summaries

File	Description
tests/worktree_observation_contract.rs	New tests for lock-less/stale observation behavior.
tests/sync_request_contract.rs	Updates SyncRequest fixtures and warning-shape contract for history warnings.
tests/state_store_contract.rs	Updates ArtifactRecord fixtures for new history address fields.
tests/stage_relocation_equivalence.rs	Adds history flag + whole-root materialization handling in relocation tests.
tests/stage_contract.rs	Updates staged-file expectations to include manifest entry kind.
tests/source_compat_gate.rs	Expands SourceStore trait method compatibility gate for worktree APIs.
tests/scrut/history.md	New scrut doc test for history overlay UX (list/verify/preview).
tests/reconcile_matrix_contract.rs	Adds overlay-stale reconciliation matrix coverage and RewriteOverlay change.
tests/reconcile_contract.rs	Updates ManagedArtifact fixtures for overlay staleness flag.
tests/projection_contract.rs	Updates projection fixtures for new history input.
tests/orchestration_reconcile.rs	Updates orchestration fixtures for overlay staleness flag.
tests/inspect_contract.rs	Updates inspection fixtures for entry-kind + history fields.
tests/history_overlay_spike.rs	End-to-end integration tests for deployed overlays and lifecycle (sync/verify/prune).
tests/conflict_kind_contract.rs	Updates conflict fixtures for overlay staleness flag.
tests/compat/staging/allowed_symlink.golden	Adjusts golden output for new manifest-file accounting.
tests/compat_serialized.rs	Updates compat tests for history input + whole-root materialization behavior.
tests/compat_recovery.rs	Updates recovery fixtures for entry-kind and history address fields.
src/sync/verify.rs	Adds overlay findings and entry-kind verification; verify now requires backend.
src/sync/transitive.rs	Rejects history in imported/transitive target bindings.
src/sync/target.rs	Core deployment changes: whole-root, overlay publish/rewrite/retire, removal handling.
src/sync/state/mod.rs	Re-exports new state types (ManifestEntryKind, NewHistoryRecord).
src/sync/state/file.rs	Persists history address fields + entry kinds; record construction updated.
src/sync/stage.rs	Stages symlinks as first-class manifest entries with kind/hash/mtime.
src/sync/scan.rs	Adds link-target hashing helper for consistent verify/rebuild behavior.
src/sync/request.rs	Adds applied/skipped change variants and HistoryContentFilter warning.
src/sync/reconcile.rs	Emits RewriteOverlay when overlay is stale while content is clean.
src/sync/rebuild.rs	Rebuild now preserves entry kinds and can reconstruct history records.
src/sync/prune.rs	Prune/removal now detaches overlays and uses projected artifacts directly.
src/sync/preview.rs	Includes history in projections and renders whole-root items for preview.
src/sync/plan.rs	Threads binding-level history into projection inputs.
src/sync/observe.rs	Observes overlay health + detects history retirements for conflict handling.
src/sync/model.rs	Adds overlay_stale to ManagedArtifact and RewriteOverlay change variant.
src/sync/mod.rs	Orchestrates overlay sweep/retirement flow; updates lockless mutation logic.
src/sync/inspect.rs	Inspects symlinks by kind and excludes history .git overlay from drift.
src/sync/hooks.rs	Uses record-relative destinations (history-aware) when computing changed paths.
src/sync/confine.rs	Adds removal confinement helper using current vs persisted anchors.
src/sync/apply.rs	Adds post-swap hook (used for publishing overlays) with rollback-on-failure.
src/source/snapshot.rs	Extends SourceStore trait with default worktree admin/observation APIs.
src/source/router.rs	Routes new worktree APIs through git backend.
src/source/mod.rs	Exposes worktree_deploy API types; adds MirrorKey FromStr.
src/source/git.rs	Implements worktree lock/observe APIs and improves mirror refresh error handling.
src/source/cache.rs	Adds per-key mirror locking + mitigates fetch failures via detaching worktree HEADs.
src/source/worktree_deploy.rs	New implementation for publishing/removing/sweeping worktree overlays.
src/projection/model.rs	Adds WholeRoot materialization and threads history through binding inputs.
src/projection/collapse.rs	Supports WholeRoot materialization in collapse ordering keys.
src/projection/build.rs	Projects history bindings as a single WholeRoot artifact; adds projected_artifacts helper.
src/config/tests.rs	Adds validation tests for history binding rules and export-policy behavior.
src/config/target.rs	Adds Binding.history and threads it into resolved bindings.
src/config/source.rs	Makes export policy history-aware (symlink/VCS opt-in).
src/config/mod.rs	Adds validation rejecting incompatible history combinations.
src/cli/sync.rs	Renders overlay rewrite actions and warnings in sync output.
src/cli/render.rs	Prints entry-kind mismatches and overlay findings in verify output.
src/cli/query.rs	History-aware list/target show status labels with overlay observation.
src/cli/mod.rs	Adds CLI flags for history on add/bind; threads backend into eject/verify/show paths.
src/cli/config_edit.rs	Persists binding history = true in config edits and merges refinements safely.
src/cli/bind.rs	Supports repeated --to targets and validates merged config including history rules.
src/cli/add.rs	Introduces AddRequest struct and supports add --history binding behavior.
scripts/arch-check.sh	Adds new worktree deploy module to architecture checks.
README.md	Documents history overlay model, usage, and constraints.
.gitignore	Adds .peer/ ignore entry.

Review details

• Files reviewed: 61/62 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.