@cldmv/git-embedded 1.0.0

package/docs/use-case-private-tests.md

@@ -0,0 +1,97 @@
+# Use case: private tests for public OSS code
+
+The motivating use case for `@cldmv/git-embedded` is open-source software that wants comprehensive test coverage running in CI but cannot afford to publish the full test suite. This document describes the threat model, the strategy, and the licensing considerations.
+
+## The threat model
+
+Comprehensive tests are a high-fidelity behavioral specification of the code under test. A test that asserts "given input X, the function produces output Y" describes a fact about the API at a level of abstraction far more compact and reusable than the source code itself. With AI tools that can convert behavioral specifications into working implementations, comprehensive tests become a near-complete substitute for the source code in the hands of someone who wants to reimplement the software.
+
+The classical clean-room reimplementation defense — used most famously by Phoenix in 1984 to clone the IBM PC BIOS — relies on a two-team structure. A "dirty team" reads the original and produces a functional specification that strips protectable expression and retains only ideas, methods, and observable behaviors. A "clean team" implements from the spec without ever having seen the original. The output is functionally equivalent but legally non-derivative because no protected expression was copied.
+
+The defense is strong when the dirty team is genuinely good at abstraction. It is weak when the "spec" they hand off is mostly the original code transliterated into prose — that intermediate spec is itself a derivative work, and so is the downstream output. Humans trained as engineers tend to be careful at this; large language models tend not to be, paraphrasing more than abstracting.
+
+Comprehensive tests bypass the dirty team entirely. They are already a behavioral specification — that's their entire purpose — and they were written to be implementation-independent. A test file is *not* a derivative work of the implementation in any meaningful sense; courts have held repeatedly that purely functional descriptions, API surfaces, and behavioral specifications are not protectable expression (Google v. Oracle 2021, Computer Associates v. Altai 1992, Sega v. Accolade 1992). The output produced by an AI given test files as input is not, on its face, substantially similar to the original code — especially if the reimplementation is in a different programming language.
+
+The threat is therefore:
+
+1. **Tests describe behavior, not expression** — they are exactly the kind of artifact that strips protectable expression while retaining functional content.
+2. **Cross-language reimplementation collapses substantial-similarity arguments** — the output isn't even textually similar to the original.
+3. **No attribution falls out naturally** — there is no claim of copying, so there is nothing to attribute.
+4. **Scale** — one operator can reproduce a project in hours that took years to build.
+
+For a project whose test suite is comprehensive (high line and branch coverage, configuration-matrix tests, edge cases worked out over time), publishing the tests publicly is materially equivalent to publishing the implementation behavioral spec. The current state of AI-copyright law (Doe v. GitHub, NYT v. OpenAI, Bartz v. Anthropic — see references at the end of this document) does not provide meaningful protection against this kind of laundering. Hiding the tests is the most direct mitigation.
+
+## The strategy
+
+The strategy this package supports has four components.
+
+**Code in a public repository under an open-source license.** Default choice is whatever fits the project — MIT, Apache-2.0, or AGPL-3.0 if the project wants the strongest copyleft compatible with OSI's Open Source Definition. The code is publicly visible, freely cloneable, and openly contributable.
+
+**Tests in a separate private repository under a more restrictive license.** Typical choice is a custom license that explicitly forbids use as AI training data, fine-tuning input, prompt input, runtime context, or any other machine-learning-pipeline ingestion. This is what shifts the legal posture from "you had no rights and ignored none of mine" to "you had to actively breach a stated term." See the licensing strategy section below.
+
+**Public CI runs whatever public test surface exists** — lint, build, type-check, smoke tests, integration tests intended for community contributors. Fork pull requests run only this surface, by GitHub Actions' default behavior (secrets are not exposed to fork-PR workflow runs, which is the correct security posture).
+
+**Private CI runs the full suite after merge to integration branches.** Workflows triggered by pushes to internal branches (`next`, `hotfixes`, release branches) have access to the secrets needed to clone the private tests repo, and run the full suite. If the full suite fails on an integration branch, the merge is reverted — a recoverable outcome, and secrets never touch fork-PR code.
+
+The `@cldmv/git-embedded` hooks are what make this strategy ergonomic for maintainers locally. Without them, the maintainer's local clone has to manually keep the tests directory in sync with the parent on every checkout, switch, and bisect. With them, the standard git workflow works as expected — `git checkout <release-branch>` updates both the code and the tests to the snapshot that was tested against, and `git bisect` walks both repos correctly in lockstep.
+
+## Why anonymous gitlinks specifically
+
+Several alternatives were considered for tracking the pinned tests version:
+
+- **A plain pin file** (`.tests-pin` committed in the parent containing the expected child SHA). Works, but the file's contents are publicly visible, and updating the pin requires a hook that rewrites the file before every commit. Standard git tooling (`git status`, `git bisect`) doesn't understand the file and won't help.
+- **Git notes** on parent commits recording the child SHA. Most private — git notes are not displayed by GitHub or GitLab UIs, only via the CLI to someone who has explicitly fetched the notes ref. But notes require an extra push (`git push origin refs/notes/*`) on every change, and CI has to fetch and parse them.
+- **A submodule with a real URL** in `.gitmodules`. Standard git automation works, but the child's URL is publicly advertised — the exact privacy leak the strategy is designed to avoid.
+- **A submodule with a fake URL** in `.gitmodules`, overridden locally via `.git/config`. Git automation works because the registry entry exists; the URL leak is reduced because the public URL is a non-resolving decoy. But the decoy itself advertises "we are deliberately hiding the real URL," which signals more intent than no entry at all.
+- **An anonymous gitlink** (gitlink in the tree with no `.gitmodules` entry). Most opaque — the public parent shows the gitlink and SHA but no URL, which could plausibly be a leftover, mistake, or any other innocuous explanation. Loses git's automation, which is the gap this package fills with its hooks.
+
+The choice is partly aesthetic but mostly about how the parent repo presents itself to outside observers. The anonymous gitlink presents minimum signal: an embedded reference whose target is not declared, the way most other features in a repo work (you can see *that* something exists without being told everything about *what* it is).
+
+## Licensing strategy
+
+The hooks themselves are infrastructure. The licensing question is what to do with the actual tests in the private repo, which is where the bulk of the engineering investment lives.
+
+A few practical points:
+
+**Different licenses for different parts of a single repo are valid.** Copyright attaches at the file level; nothing in copyright law requires one license per repository. The standard mechanism is the [REUSE specification](https://reuse.software/) from FSF Europe, which puts a license header at the top of every file and a `LICENSES/` directory containing the full text of each license used.
+
+**OSI's Open Source Definition (clause 6) forbids use-based restrictions.** "No discrimination against fields of endeavor" means "no AI training" is not, by OSI's definition, an open-source restriction. A custom license that includes such a clause is **source-available** rather than open source, and the project should describe itself accordingly.
+
+**AGPL-3.0 is the strongest OSI-compliant copyleft.** It does not mention AI training, but its broad copyleft language plausibly catches AI-augmented derivative works. AGPL-licensed code can be argued to require any model trained on it to be released under AGPL, an argument AI companies dispute and which is not yet tested in court. Combined with explicit non-consent records, it is the best the OSI-compliant landscape currently offers.
+
+**OpenRAIL family licenses** (BigCode OpenRAIL-M for code, BigScience RAIL for models) include AI-misuse clauses and downstream propagation requirements. They are explicitly not OSI open source but are well-defined and widely understood in the AI ecosystem.
+
+**EU CDSM Article 4** gives rightsholders a legally-enforceable opt-out from text-and-data-mining in EU jurisdictions. Combined with a machine-readable opt-out signal (TDMRep, robots.txt, `noai` meta tags), it provides a concrete legal hook absent from US copyright law's current state.
+
+A reasonable layering for the private tests repo is therefore:
+
+1. AGPL-3.0 or a custom source-available license for the tests themselves
+2. Explicit AI-training-and-derivation prohibition clause in the license text
+3. Acceptable Use Policy on the project website documenting non-consent
+4. REUSE-spec headers on every file
+5. EU TDM opt-out signals on any hosted version
+
+None of these provide certainty against the threat model, but they collectively shift the legal posture as far as currently available tools allow.
+
+## What this package does not provide
+
+- **A solution to the broader AI-and-copyright problem.** The hooks make a specific defensive posture (hide the tests) more ergonomic. They do not stop anyone who has already obtained the tests from doing whatever they want with them. They do not protect the public code from AI training (which is a separate question with separate answers).
+- **Watermarking, canary tokens, or AI-output traceability.** Some practitioners embed unique identifiers in tests to detect if those tests later appear in model outputs. That is a complementary defense; this package neither implements nor opposes it.
+- **Legal advice.** This document describes a strategy and references public cases. It is not a substitute for consultation with a lawyer for any specific situation.
+
+## CI integration
+
+The corresponding CI behavior — auto-detecting embedded gitlinks in workflow runs, cloning the corresponding private repos via the org bot App, running the full test suite — is provided by the CLDMV reusable workflows. See [`docs/conventions/embedded-tests-ci.md`](https://github.com/CLDMV/.github/blob/master/docs/conventions/embedded-tests-ci.md) in `CLDMV/.github` for the workflow design: the opt-in input (`enable_embedded_tests: true`), the two convention-only URL mappings (primary per-path `<repo>-<path-with-dashes>` and secondary consolidated `<repo>-embedded`), fork-PR silent-skip behavior, and the failure modes. The CLI in this package handles the local-machine side; the CLDMV workflows handle the CI side. Both work off the same anonymous-gitlink signal in the parent's tree. No tracked config file is involved on either side — keeping the mapping convention-only is what preserves the privacy intent of using anonymous gitlinks in the first place.
+
+## References
+
+- **Phoenix Technologies IBM PC BIOS clone (1984)** — the canonical clean-room reimplementation. Never actually litigated; the technique deterred IBM from suing.
+- **Computer Associates v. Altai, 982 F.2d 693 (2d Cir. 1992)** — established the abstraction-filtration-comparison test still used today for evaluating substantial similarity in software.
+- **Sega v. Accolade, 977 F.2d 1510 (9th Cir. 1992)** — reverse engineering for interoperability is fair use.
+- **Sony v. Connectix, 203 F.3d 596 (9th Cir. 2000)** — reverse engineering the PlayStation BIOS to build an emulator was legal.
+- **Google LLC v. Oracle America, Inc., 593 U.S. 1 (2021)** — API declarations are subject to fair use even when reimplemented.
+- **Doe v. GitHub** (N.D. Cal., filed November 2022) — anonymous developers v. GitHub/Microsoft/OpenAI over Copilot training on open-source code. Most copyright claims dismissed over 2023-2024 on substantial-similarity grounds.
+- **The New York Times v. Microsoft and OpenAI** (S.D.N.Y., filed December 2023) — NYT sued over training on its content; NYT demonstrated verbatim regurgitation, breaking the Copilot-style "no substantial similarity" defense. Ongoing as of writing.
+- **Bartz v. Anthropic** (N.D. Cal., filed August 2024) — authors v. Anthropic over training on pirated book datasets. Mid-2025 ruling split the question: training on legitimately purchased books was fair use; using pirated copies was infringement.
+- **REUSE Specification** (FSF Europe) — `https://reuse.software/`
+- **EU CDSM Directive Article 4** — text-and-data-mining opt-out mechanism.

package/hooks/_dispatch.template

@@ -0,0 +1,67 @@
+#!/bin/sh
+#
+# Global git hook dispatcher (canonical, policy-free).
+#
+# Installed by `git embedded install-hooks` when no prior hook setup is
+# detected. The installer:
+#   1. Writes this script to the user's chosen hooks directory (default
+#      ~/.config/git/hooks/_dispatch).
+#   2. Links every standard hook name (applypatch-msg, commit-msg,
+#      post-applypatch, post-checkout, post-commit, post-merge,
+#      post-rewrite, pre-applypatch, pre-auto-gc, pre-commit,
+#      pre-merge-commit, pre-push, pre-rebase, prepare-commit-msg,
+#      reference-transaction) to this script — symlink on Linux/macOS,
+#      hard link on Windows (with --no-symlinks), or copy as fallback.
+#   3. Sets `git config --global core.hooksPath` to the chosen directory.
+#
+# Behavior at hook-fire time:
+#   1. (Optional) apply user-added global policy below.
+#   2. Chain to the per-repo `.git/hooks/<hook-name>` if one exists.
+#      This is what makes a global `core.hooksPath` coexist with per-repo
+#      hooks — without the chain, per-repo hooks would be silently
+#      shadowed.
+#
+# Customizing:
+#   Add your own policies in the `--- global policy ---` block below.
+#   `$hook` holds the hook name (e.g. `commit-msg`, `pre-push`).
+#   `$1`...`$N` and stdin are the hook's native arguments / input per
+#   the git hooks documentation.
+#   Exit non-zero from a case branch to reject the operation.
+#
+# DO NOT EDIT the chain-to-repo-hook block at the bottom unless you
+# understand the consequences. It's load-bearing for `git-embedded`'s
+# own hooks (post-checkout, post-merge, post-rewrite,
+# reference-transaction) to reach the per-repo `.git/hooks/` directory
+# where they're installed.
+
+hook=$(basename "$0")
+
+# --- global policy --------------------------------------------------------
+# Add your hook-event-specific logic here. Example template:
+#
+# case "$hook" in
+# commit-msg)
+#     # $1 is the path to the proposed commit message file.
+#     # if grep -qiE 'YOUR_PATTERN' "$1"; then
+#     #     echo >&2 "✗ commit rejected: <reason>"
+#     #     exit 1
+#     # fi
+#     ;;
+# pre-push)
+#     # stdin has one line per ref:
+#     #   <local_ref> <local_sha> <remote_ref> <remote_sha>
+#     # while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
+#     #     ...
+#     # done
+#     ;;
+# esac
+
+# --- chain to the repository's own hook, if any --------------------------
+# (Load-bearing for git-embedded; do not remove.)
+git_dir=$(git rev-parse --absolute-git-dir 2>/dev/null) || exit 0
+repo_hook="$git_dir/hooks/$hook"
+if [ -x "$repo_hook" ] && [ "$repo_hook" != "$0" ]; then
+    exec "$repo_hook" "$@"
+fi
+
+exit 0

package/hooks/reference-transaction

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# reference-transaction
+#
+# Refuses HEAD-moving git operations if any embedded git repo in the parent's
+# tree has uncommitted changes. Without this, a `git checkout B` in the parent
+# would silently leave the child stale (with the post-checkout updater unable
+# to update over dirty state), producing a confusing inconsistent state.
+#
+# Requires git 2.28+ (released July 2020, when reference-transaction was
+# introduced).
+#
+# Phases (passed as $1 by git):
+#   - prepared:  updates queued, not yet applied. Exiting non-zero ABORTS the
+#                transaction. This is the only phase we act on.
+#   - committed: updates already applied (informational; we ignore).
+#   - aborted:   updates rejected by some other handler (informational).
+#
+# The hook reads proposed ref updates from stdin, one per line:
+#   <old_sha> <new_sha> <ref-name>
+#
+# We filter to HEAD updates with old != new (an actual HEAD move). Other ref
+# updates (branch fast-forwards from fetch, stash refs, tag creation, etc.)
+# don't touch the working tree and shouldn't be guarded.
+
+# Only the 'prepared' phase can reject the transaction.
+[ "$1" = "prepared" ] || exit 0
+
+# Detect whether any update in this transaction moves HEAD.
+moving_head=0
+while read old_sha new_sha ref; do
+    [ "$ref" = "HEAD" ] || continue
+    [ "$old_sha" = "$new_sha" ] && continue
+    moving_head=1
+done
+
+# Nothing to check if HEAD is not moving.
+[ "$moving_head" = "1" ] || exit 0
+
+# Walk every gitlink in the current HEAD and check for dirty state.
+# A gitlink is a tree entry with type 'commit' (mode 160000). The path is
+# the directory in the parent's working tree that holds the embedded repo.
+while read mode type sha path; do
+    [ "$type" = "commit" ] || continue
+    [ -d "$path/.git" ] || [ -f "$path/.git" ] || continue
+
+    # Refuse if there are uncommitted changes inside the embedded repo.
+    if ! (cd "$path" && git diff-index --quiet HEAD --) 2>/dev/null; then
+        echo "git-embedded: ✗ $path has uncommitted changes" >&2
+        echo "  commit or stash inside $path/ before moving HEAD here" >&2
+        exit 1
+    fi
+done < <(git ls-tree -r HEAD 2>/dev/null)
+
+exit 0

package/hooks/update-embedded-repos

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# update-embedded-repos
+#
+# Generic gitlink updater: finds every embedded git repo (gitlink with a
+# working .git/ in the parent's tree) and updates it to the pinned SHA recorded
+# in the parent's HEAD. Uses the child's own remote config — does NOT read or
+# require .gitmodules.
+#
+# Install as post-checkout, post-merge, AND post-rewrite to cover the full
+# set of standard checkout-flavored git operations (checkout, switch, bisect,
+# pull, merge, rebase, cherry-pick). The script is identical for each hook
+# name; link or copy to the right names.
+#
+# Exit status:
+#   - Always 0. This hook runs AFTER the parent operation has completed, so
+#     signalling failure here cannot undo the parent move. The companion
+#     reference-transaction hook is what prevents unsafe moves in the first
+#     place; this hook only carries out the working-tree side of the work.
+#   - A failure to update a single child is reported to stderr and the script
+#     continues to the next child.
+
+# Walk every gitlink in the current HEAD and update the embedded child.
+# Tree entries from `git ls-tree -r HEAD`:
+#   <mode> SP <type> SP <sha> TAB <path>
+# Bash 'read' splits on $IFS (whitespace), so the four fields land in the
+# four variables below. A path with a tab in it would split further; gitlink
+# paths in practice are directory names and don't contain tabs.
+while read mode type sha path; do
+    [ "$type" = "commit" ] || continue
+    [ -d "$path/.git" ] || [ -f "$path/.git" ] || continue
+
+    # Skip if already at the pinned SHA — idempotent re-runs are no-ops.
+    current=$(cd "$path" && git rev-parse HEAD 2>/dev/null) || continue
+    [ "$current" = "$sha" ] && continue
+
+    # Fetch from the child's own origin if the pinned SHA isn't local.
+    # The child has its own remote config (set up at clone time); no need
+    # to consult .gitmodules for the URL.
+    if ! (cd "$path" && git cat-file -e "${sha}^{commit}" 2>/dev/null); then
+        if ! (cd "$path" && git fetch --quiet 2>/dev/null); then
+            echo "git-embedded: warning: $path: fetch from child's own remote failed" >&2
+            echo "  (cannot resolve pinned SHA $sha)" >&2
+            continue
+        fi
+    fi
+
+    # Detached HEAD on the pinned SHA. The parent pins a commit, not a branch,
+    # so the child ends up detached after each parent operation. Re-attach to
+    # a branch manually inside the child if you intend to make changes there.
+    if ! (cd "$path" && git checkout --quiet --detach "$sha" 2>/dev/null); then
+        echo "git-embedded: warning: $path: could not check out $sha" >&2
+        echo "  (parent at this commit pins $path to $sha — resolve manually in $path/)" >&2
+    fi
+done < <(git ls-tree -r HEAD 2>/dev/null)
+
+exit 0

package/messages/setup-bare-githooks.md

@@ -0,0 +1,25 @@
+## Bare `.githooks/` directory detected
+
+This repo has `core.hooksPath` set to an in-repo path (typically `.githooks/`) containing hook scripts directly — no dispatcher script, no symlinks. The directory is tracked, so the hooks travel with the repo. This is the "hand-rolled, minimum dependency" setup.
+
+`git-embedded` could install its scripts into this directory, but doing so means the scripts become tracked files in your repo. That is a deliberate choice the maintainer should make, not something the CLI should do silently.
+
+## Why the CLI will not auto-install
+
+Tracked files alter the repo's content and history. The decision to commit `git-embedded`'s scripts into the repo (vs keeping them as an install-time artifact via the npm dependency) is a project-level call about how the hooks are sourced. The CLI defers this.
+
+## Integration options
+
+**Option 1: commit the scripts into the tracked `.githooks/` directory.**
+
+Run `git embedded copy-hooks-to .githooks/` (or whatever path your `core.hooksPath` points at). The CLI copies the four hook scripts into that directory. You then `git add .githooks/ && git commit`. From that point, the scripts ship with the repo — `npm install` is not required to get them.
+
+Tradeoff: a copy of the scripts lives in your repo's history, separately from the npm-tracked version. Updates require re-running `copy-hooks-to` and committing.
+
+**Option 2: convert to the dispatcher pattern.**
+
+If you want a cleaner separation between "infrastructure that ships with the repo" and "policies the dispatcher enforces," the canonical dispatcher pattern gives you that: a small `_dispatch` script installed at `~/.config/git/hooks/` runs global policy and chains to whatever per-repo hooks each project ships. The bare `.githooks/` becomes a `.d/`-style directory underneath. `git embedded install-hooks` after the switch will detect the new dispatcher and install cleanly without committing files to the repo.
+
+**Option 3: bring-your-own mode.**
+
+`git embedded print-hook-script <name>` outputs each script's content. Paste them into your `.githooks/` files yourself, however you'd like to combine them with any existing hooks there.

package/messages/setup-dispatcher-canonical-complete.md

@@ -0,0 +1,30 @@
+## Dispatcher pattern detected — ready to install
+
+This machine has the canonical dispatcher pattern installed at the path printed above. The dispatcher chains to per-repo hooks at `.git/hooks/<name>` after running any global policy, and all required hook symlinks are present.
+
+## What the CLI will do
+
+- Install `git-embedded`'s hook scripts into this repo's `.git/hooks/` directory:
+  - `post-checkout` — updates embedded children after checkout-style operations
+  - `post-merge` — updates embedded children after merges
+  - `post-rewrite` — updates embedded children after rebases
+  - `reference-transaction` — refuses HEAD-moving operations when any embedded child is dirty
+- Set the executable bit on each script.
+- Log the install to the transaction file so it can be reversed with `git embedded uninstall-hooks`.
+
+No global state is modified. The dispatcher you already have activates the new scripts automatically.
+
+## After install
+
+Test the setup:
+
+```bash
+# Should report all four hooks installed and active
+git embedded doctor
+```
+
+To remove later:
+
+```bash
+git embedded uninstall-hooks
+```

package/messages/setup-dispatcher-missing-symlinks.md

@@ -0,0 +1,56 @@
+## Dispatcher pattern detected — missing required hook entries
+
+This machine has a dispatcher script at the path printed above, but the dispatcher directory is missing one or more entries (symlink, hard link, or copy) needed for `git-embedded` to function.
+
+The required hook events are:
+
+- `post-checkout`
+- `post-merge`
+- `post-rewrite`
+- `reference-transaction`
+
+Any missing entry means git skips that hook event entirely — even if the per-repo `.git/hooks/<name>` exists, git never reaches it because the dispatcher directory has nothing to invoke.
+
+## What the CLI proposes
+
+Heal the dispatcher by creating the missing entries — symlinks by default, or hard links if you pass `--no-symlinks`. On Windows without elevation, creating symlinks requires UAC; the CLI requests elevation and creates all missing entries in one batch when you accept. Declining the UAC prompt exits the CLI without changes; use `--no-symlinks` if you want the no-prompt hard-link path instead.
+
+The dispatcher script itself is not modified — only missing entries are added.
+
+This is a global change to `core.hooksPath`'s directory. It will affect all repos that use this dispatcher, but only by enabling hook events that were previously disabled. Existing entries are not touched.
+
+## After healing
+
+The CLI will then install `git-embedded`'s hook scripts into this repo's `.git/hooks/`, and the now-complete dispatcher will activate them.
+
+## Decline
+
+If you decline the heal, the CLI exits without changes. You can heal manually:
+
+**Linux / macOS (symlinks, no elevation needed):**
+```bash
+ln -sf _dispatch <dispatcher-dir>/post-checkout
+ln -sf _dispatch <dispatcher-dir>/post-merge
+ln -sf _dispatch <dispatcher-dir>/post-rewrite
+ln -sf _dispatch <dispatcher-dir>/reference-transaction
+```
+
+**Windows (symlinks, run from an elevated Command Prompt):**
+```cmd
+mklink "<dispatcher-dir>\post-checkout" "<dispatcher-dir>\_dispatch"
+mklink "<dispatcher-dir>\post-merge" "<dispatcher-dir>\_dispatch"
+mklink "<dispatcher-dir>\post-rewrite" "<dispatcher-dir>\_dispatch"
+mklink "<dispatcher-dir>\reference-transaction" "<dispatcher-dir>\_dispatch"
+```
+
+**Windows (hard links, no elevation needed — alternative if you don't want to elevate):**
+```cmd
+mklink /H "<dispatcher-dir>\post-checkout" "<dispatcher-dir>\_dispatch"
+mklink /H "<dispatcher-dir>\post-merge" "<dispatcher-dir>\_dispatch"
+mklink /H "<dispatcher-dir>\post-rewrite" "<dispatcher-dir>\_dispatch"
+mklink /H "<dispatcher-dir>\reference-transaction" "<dispatcher-dir>\_dispatch"
+```
+
+(Hard links work on NTFS without elevated permissions. If your dispatcher dir is on a non-NTFS volume, copy `_dispatch` to each missing name instead.)
+
+Re-run `git embedded install-hooks` after healing.

package/messages/setup-dispatcher-non-conforming.md

@@ -0,0 +1,35 @@
+## Non-conforming dispatcher detected
+
+This machine has `core.hooksPath` pointed at a directory that contains a dispatcher-style script (multiple hook names redirect to one common script), but that dispatcher does NOT chain to per-repo hooks.
+
+That means anything `git-embedded` places in `.git/hooks/<name>` is never reached. The dispatcher swallows each hook event without falling through to per-repo customization.
+
+## Why the CLI will not modify the dispatcher
+
+Even with consent, rewriting someone else's dispatcher script is too invasive. The dispatcher enforces policies that may be load-bearing for other tools, security workflows, or team agreements. Modifying it risks breaking those.
+
+## Integration options
+
+**Option 1: modify the dispatcher to chain to per-repo hooks.**
+
+Add a block at the end of the dispatcher script that exec's the per-repo hook:
+
+```sh
+# --- chain to the repository's own hook, if any ---
+git_dir=$(git rev-parse --absolute-git-dir 2>/dev/null) || exit 0
+repo_hook="$git_dir/hooks/$(basename "$0")"
+if [ -x "$repo_hook" ] && [ "$repo_hook" != "$0" ]; then
+    exec "$repo_hook" "$@"
+fi
+exit 0
+```
+
+Once added, re-run `git embedded install-hooks`. The dispatcher becomes conforming and the install proceeds normally.
+
+**Option 2: switch to the canonical dispatcher pattern.**
+
+If your dispatcher's policies are simple enough to port, the canonical dispatcher pattern (a small `_dispatch` script at `~/.config/git/hooks/` plus one symlink per standard hook name, chaining to per-repo hooks at the end) is a drop-in replacement. `git embedded install-hooks` after the switch will detect the new dispatcher and install cleanly.
+
+**Option 3: bring-your-own mode.**
+
+Run `git embedded print-hook-script <name>` for each hook event you want to enable. Paste the contents into the body of your dispatcher at the appropriate spot, gated by `basename "$0"` matching the hook name. Your dispatcher then runs the `git-embedded` logic inline instead of via chaining.

package/messages/setup-husky.md

@@ -0,0 +1,35 @@
+## Husky detected
+
+This repo uses [Husky](https://github.com/typicode/husky) for git hook management. Signals: `.husky/` directory at repo root, `"prepare": "husky"` script in `package.json`, and local `core.hooksPath` set to `.husky`.
+
+Husky writes hook scripts directly into `.husky/<name>`. Those scripts shadow anything in `.git/hooks/`, so `git-embedded` cannot install via the normal per-repo path.
+
+## Why the CLI will not auto-integrate
+
+Husky re-runs its setup on every `npm install` via the `prepare` lifecycle script. Files we write into `.husky/` could be overwritten or moved by Husky's reinstall, depending on Husky version and project configuration. Auto-edits to `.husky/<name>` files also lack a reliable rollback path if Husky's behavior changes between versions.
+
+## Manual integration options
+
+**Option 1: append our invocation to Husky's hook files.**
+
+Each `.husky/<name>` file is a plain shell script. Append a call to our hook script at the end (after Husky's own setup line, if present):
+
+```sh
+# .husky/post-checkout
+. "$(dirname -- "$0")/_/husky.sh"   # Husky v8 only; omit on v9+
+
+# ... any existing Husky-managed commands ...
+
+# --- git-embedded: update embedded repos ---
+npx git-embedded run-hook post-checkout "$@"
+```
+
+Repeat for `post-merge`, `post-rewrite`, and `reference-transaction`. Husky's setup typically does not regenerate the body of hook files once they exist, so your additions persist — but verify on your specific Husky version.
+
+**Option 2: replace Husky with the dispatcher pattern.**
+
+The canonical dispatcher pattern (a small `_dispatch` script installed at `~/.config/git/hooks/`) covers the same ground as Husky — managed hooks plus per-repo extension — without the npm `prepare`-script execution path, which is a smaller supply-chain surface. Replacing Husky removes the `.husky/` directory, unsets local `core.hooksPath`, installs the dispatcher globally, and reruns `git embedded install-hooks`.
+
+**Option 3: bring-your-own mode.**
+
+Run `git embedded print-hook-script <name>` to get the script content, paste it inline into the relevant `.husky/<name>` file. Same as Option 1 but with the body inlined rather than invoked via `npx`.

package/messages/setup-init-templatedir.md

@@ -0,0 +1,21 @@
+## `init.templateDir` detected
+
+`git config --global init.templateDir` is set on this machine to the path printed above. That directory's contents are copied into `.git/` of every newly-created or freshly-cloned repository, including any hook scripts in `<template>/hooks/`.
+
+This is complementary to per-repo hook installation, not a conflict. New repos start with whatever's in the template; existing repos are unaffected.
+
+## What the CLI offers
+
+In addition to installing hooks into this repo's `.git/hooks/` normally, the CLI can copy `git-embedded`'s hook scripts into `<template>/hooks/` so that **future** new and cloned repos start with the hooks already in place. This is opt-in and requires confirmation because it modifies global state.
+
+If you accept, the four hook scripts (`post-checkout`, `post-merge`, `post-rewrite`, `reference-transaction`) are written into the template's `hooks/` directory. The next `git init` or `git clone` on this machine copies them into the new repo automatically.
+
+## Caveats
+
+- **Templates are copied, not symlinked.** Updates to the scripts in the template do not propagate to existing repos. To update, re-run `git embedded install-template` after updating the package; old repos retain whatever was in their template at clone time.
+- **Doesn't fix existing repos.** Only future ones benefit. Run `git embedded install-hooks` per-repo for repos that already exist.
+- **Per-repo install is still recommended** even with template install set up. The template install only matters at `git init` / `git clone` time. If you `git init` and forget the package was supposed to be installed, you still get the hooks. But if you clone an existing repo, the template still applies — which may or may not be what you want for repos that don't actually use `git-embedded`.
+
+## Decline
+
+If you decline, nothing changes globally. The CLI proceeds with per-repo install only, which is the safer default.

package/messages/setup-lefthook.md

@@ -0,0 +1,48 @@
+## Lefthook detected
+
+This repo uses [Lefthook](https://github.com/evilmartians/lefthook) for git hook management. Signals: `lefthook.yml` (or `.lefthook.yml`, `lefthook.yaml`, `.lefthook.yaml`) at repo root, hook files in `.git/hooks/` with a Lefthook-generated header.
+
+Lefthook writes hook files into `.git/hooks/` from its YAML config and may overwrite them on the next `lefthook install`. `git-embedded` cannot install into `.git/hooks/` without risk of being overwritten.
+
+## Why the CLI will not auto-integrate
+
+Lefthook is the source of truth for `.git/hooks/` content in projects that use it. Editing those files directly is undone the next time Lefthook regenerates. Modifying `lefthook.yml` is the correct integration path, but parsing and editing arbitrary user YAML reliably (preserving comments, formatting, ordering) is too easy to get wrong for an automated tool to do silently.
+
+## Manual integration
+
+Edit `lefthook.yml` to add `git-embedded`'s scripts as commands under each relevant hook event:
+
+```yaml
+# lefthook.yml
+
+post-checkout:
+  commands:
+    git-embedded:
+      run: npx git-embedded run-hook post-checkout {1} {2} {3}
+
+post-merge:
+  commands:
+    git-embedded:
+      run: npx git-embedded run-hook post-merge {1}
+
+post-rewrite:
+  commands:
+    git-embedded:
+      run: npx git-embedded run-hook post-rewrite {1}
+
+reference-transaction:
+  commands:
+    git-embedded:
+      run: npx git-embedded run-hook reference-transaction {1}
+      # NOTE: lefthook's support for reference-transaction may vary by version.
+      # If your lefthook version doesn't list reference-transaction as a
+      # supported event, install that one hook outside of lefthook (directly
+      # into .git/hooks/reference-transaction) and lefthook will leave it
+      # alone.
+```
+
+Then run `lefthook install` to regenerate `.git/hooks/` from the updated config. Run `git embedded doctor` to confirm the hooks are wired correctly.
+
+## Bring-your-own mode
+
+`git embedded print-hook-script <name>` outputs the script body. You can inline it inside a lefthook `run:` block, or put it in a script file in the repo and reference that file from `lefthook.yml`.

package/messages/setup-none.md

@@ -0,0 +1,27 @@
+## No hook setup detected
+
+This machine has no `core.hooksPath` set at any scope (system, global, or local), and the repo's `.git/hooks/` directory holds only git's default `.sample` files.
+
+That means git is using its out-of-the-box per-repo hooks model — hooks placed in `.git/hooks/` will run, but they don't travel with a clone, and there's no shared infrastructure for global policy (commit-message validation, push-time checks, etc.).
+
+## Recommended: install the dispatcher pattern globally
+
+The dispatcher pattern is a one-time setup that benefits every repo on this machine. It:
+
+- Adds a small dispatcher script to `~/.config/git/hooks/` (or a path of your choice).
+- Creates a symlink for each standard hook name pointing at the dispatcher. On Linux and macOS this requires no special permissions. On Windows it requires admin elevation — the CLI requests UAC and creates all symlinks in one batch on accept. If you prefer to avoid the elevation prompt, pass `--no-symlinks` to use hard links instead (works on NTFS without elevation).
+- Sets `git config --global core.hooksPath` to that directory.
+- The dispatcher chains to each repo's `.git/hooks/<name>` after running any global policy, so per-repo hooks keep working everywhere.
+
+Once installed, `git-embedded` can install its scripts into the current repo's `.git/hooks/` and the global dispatcher activates them automatically. Future repos work the same way with no per-repo setup beyond running `git embedded install-hooks` once.
+
+## Alternative: install scripts into this repo only
+
+If you don't want a global change, the CLI will install hooks directly into the current repo's `.git/hooks/`. Limitations:
+
+- Hooks don't travel with the repo (`.git/` is not tracked). Other developers cloning this repo need to install separately.
+- No global policy hooks are available (commit-msg, pre-push). Only what `git-embedded` provides will fire.
+
+## Bring-your-own mode
+
+If you have a different setup in mind, run `git embedded print-hook-script <hook-name>` to see the script content and wire it in however you like.

package/messages/setup-pre-commit.md

@@ -0,0 +1,47 @@
+## pre-commit detected
+
+This repo uses [pre-commit](https://pre-commit.com/) for git hook management. Signals: `.pre-commit-config.yaml` at repo root, `.git/hooks/<name>` files with a `# File generated by pre-commit` header.
+
+pre-commit writes wrapper scripts into `.git/hooks/` and regenerates them on `pre-commit install`. `git-embedded` cannot install into `.git/hooks/` without risk of being overwritten.
+
+## Why the CLI will not auto-integrate
+
+pre-commit's `.pre-commit-config.yaml` is the source of truth. The right integration is to add `git-embedded` as a local hook entry. As with Lefthook, parsing and editing user YAML reliably is too easy to get wrong for automated tooling.
+
+## Manual integration
+
+Add a `local` hook block to `.pre-commit-config.yaml`:
+
+```yaml
+# .pre-commit-config.yaml
+
+repos:
+  - repo: local
+    hooks:
+      - id: git-embedded-update
+        name: git-embedded — update embedded repos
+        entry: npx git-embedded run-hook
+        language: system
+        pass_filenames: false
+        stages: [post-checkout, post-merge, post-rewrite]
+        verbose: true
+
+      - id: git-embedded-guard
+        name: git-embedded — guard HEAD moves when children are dirty
+        entry: npx git-embedded run-hook reference-transaction
+        language: system
+        pass_filenames: false
+        stages: [reference-transaction]   # support for this stage depends on
+                                          # the pre-commit version
+        verbose: true
+```
+
+Then `pre-commit install --hook-type post-checkout --hook-type post-merge --hook-type post-rewrite --hook-type reference-transaction` to wire all four event types.
+
+## Caveat about reference-transaction
+
+`reference-transaction` is a relatively new git hook (2020) and pre-commit's stage coverage varies by version. Check your pre-commit version's documentation. If it doesn't support `reference-transaction`, install that one hook manually into `.git/hooks/reference-transaction` outside pre-commit; pre-commit will not regenerate hook files it didn't create.
+
+## Bring-your-own mode
+
+`git embedded print-hook-script <name>` outputs the script body. You can drop the script into a tracked file in the repo and reference it from the `entry:` field instead of `npx git-embedded run-hook`, removing the indirection through `npx`.