feat(hooks): guard modes (precise/strict/off) + pin-publication pre-push check

[Shinrai]

Two hook problems surfaced by real multi-repo parent use (a 26-child workspace), fixed with configurable behavior.

1. The dirty-child guard fired on plain commits — and its doc was wrong

A plain git commit also emits a HEAD update line in the reference transaction (HEAD's reflog records the new commit), so the guard's "HEAD moved" filter matched every parent commit. Result: any one dirty child froze all parent commits — including pin bumps for unrelated children. The design doc claimed commits weren't caught; the plumbing says otherwise.

The hook now reasons about what the move would actually do to each child, with a mode knob (git config embedded.guard):

• precise (default) — block only a move that would re-pin a dirty child (new pin ≠ child HEAD — exactly when update-embedded-repos would touch it). Catches the drifted-dirty-child case a naive pin-delta rule misses; never blocks on unrelated dirt.
• strict — everything-synced policy: any dirty child blocks any move, and appends (classified by parentage against the resolved pre-move HEAD — a detach's transaction line reads null on the old side and can't be trusted) additionally require every pin to equal its child's current HEAD, so a parent commit can never ship a stale pin.
• off — no guarding.

2. Nothing stopped publishing pins to unpushed child commits

A committed-but-unpushed child is clean — the old guard waved it through, and a pushed parent then dangled for every other machine (restore → pinned-mismatch). New pre-push hook (embedded.pushRecurse = check|on-demand|off, default check): rejects a parent push whose newly-introduced pins are unreachable from the child's own origin — the analog of git push --recurse-submodules=check, which stock git can't provide without .gitmodules registration. Only newly-introduced pins are verified (plus the full tree on ref creation), so a clone that never restored its children still pushes pin-less commits fine. on-demand publishes the child's current branch first when it contains the pin.

Config shape

Two-part embedded.* keys — structurally collision-free with the three-part per-child registry entries (embedded.<path>.url/.branch). Local overrides global; one-shot via git -c.

Tests

13 new behavior tests drive real git operations with the hooks installed (tests/hook-guards.test.mjs): precise allow/block/drift cases, strict dirty/stale-pin/jump cases, off, and pre-push check/publish/off/children-less-clone/blind-pin cases. install-hooks log-count updated 4→5 for the new hook (intentional). Suite 28 passing.

Docs

design.md: guard section rewritten around the transaction-line fact (correcting the wrong "commit is not caught" claim), modes documented, new pre-push section. README: knob table.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T9qCSCACxt2H2JG7YSDzdk

[Copilot]

Pull request overview

This PR extends git-embedded’s hook system to better support large multi-repo workspaces by (1) making the reference-transaction guard configurable (embedded.guard = precise|strict|off) and (2) adding a new pre-push hook to prevent publishing parent pins that reference child commits not yet reachable from the child’s origin.

Changes:

• Add guard modes to hooks/reference-transaction with updated decision logic based on the new commit’s pins and append-vs-jump classification.
• Add hooks/pre-push plus installer/CLI support (install-hooks and print-hook-script) for pin-publication verification (embedded.pushRecurse = check|on-demand|off).
• Add a new Vitest behavior test suite driving real git operations, and update documentation in README/design doc.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tests/install-hooks.test.mjs	Updates install log-count expectation for the newly installed pre-push hook.
tests/hook-guards.test.mjs	Adds behavior tests for guard modes and the new pre-push pin-publication checks.
src/api/install/hooks.mjs	Adds pre-push to the packaged hook installation map and clarifies install docstring.
src/api/cli/print-hook-script.mjs	Allows printing the packaged pre-push hook script.
README.md	Documents new configuration knobs (embedded.guard, embedded.pushRecurse).
hooks/reference-transaction	Reworks guard logic to support modes and to correctly handle commit-vs-checkout plumbing behavior.
hooks/pre-push	New hook implementing pin-publication verification (and optional on-demand child publishing).
docs/design.md	Updates design doc for modes and adds pre-push rationale/mechanism details.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

hooks/pre-push:147

• The (pin, path) re-read loop uses default IFS splitting (read -r pin path), which strips leading IFS characters from path. If an embedded repo directory name starts with a space, the serialized line (<pin> <path>) will be parsed with the leading space dropped and the hook will look for the child in the wrong location (false “child repo is not present”). This is avoidable by reading each line as a whole (preserving whitespace) and then splitting off the fixed-width SHA prefix.

    while read -r pin path; do
        [ -n "$pin" ] && [ -n "$path" ] || continue
        case "$checked" in *"|$path=$pin|"*) continue ;; esac
        checked="$checked|$path=$pin|"
        verify_pin "$path" "$pin" || block=1