From a9686fe517f94231f7f492e6d9e9a0fdf3ba4780 Mon Sep 17 00:00:00 2001
From: sksizer <shane@sizerllc.com>
Date: Tue, 7 Apr 2026 13:51:00 -0500
Subject: [PATCH] feat(scripts): add cousin workflow for opted-in Rust subpaths
 in third-party repos
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Introduces the concept of 'cousin' repositories — third-party projects
that contain Rust code in explicitly whitelisted subpaths, but are not
forks of this template. Cousins follow their own conventions and may
have unrelated tooling (Bazel, custom CI, etc.), so the workflow is
hyper-conservative: nothing is touched unless it is explicitly opted-in
in scripts/cousins.json, and a 'forbidden_paths' hard deny list acts as
a belt-and-suspenders safety net.

Schema (scripts/cousins.json):
- cousins[].name / url / notes
- cousins[].targets[].path / applies[] / check (per-crate)
- cousins[].global_applies[] (rare; repo-root files)
- cousins[].forbidden_paths[] (glob deny list)

Four new scripts:
- cousin_review.sh / cousin_review_all.sh — read-only, produce a markdown
  report classifying diffs as SUGGEST-ADOPT, SUGGEST-NEW-FILE, KEEP-COUSIN,
  or NOT-APPLICABLE. Allowed tools: Read Bash. Never modifies anything.
- cousin_apply.sh / cousin_apply_all.sh — write mode. Clones the cousin
  fresh into a tempdir, copies template bytes verbatim into opted-in slots
  only (no retyping via Write), runs per-target checks with priority
  1) targets[].check 2) 'cargo check --manifest-path <target>/Cargo.toml'
  3) skip, reverts failed targets, and opens a single PR per cousin.

Reuses scripts/lib/pr_prompt.sh for deferred PR URL prompting. A new
scripts/lib/cousins.sh helper handles jq parsing and cousin lookup.

justfile: adds cousin-review (cr), cousin-review-all (cra),
cousin-apply (ca), cousin-apply-all (caa).
---
 justfile                      |  24 ++++++
 scripts/cousin_apply.sh       | 137 ++++++++++++++++++++++++++++++++++
 scripts/cousin_apply/role.md  |   3 +
 scripts/cousin_apply/task.md  | 108 +++++++++++++++++++++++++++
 scripts/cousin_apply_all.sh   |  81 ++++++++++++++++++++
 scripts/cousin_review.sh      | 131 ++++++++++++++++++++++++++++++++
 scripts/cousin_review/role.md |   5 ++
 scripts/cousin_review/task.md | 118 +++++++++++++++++++++++++++++
 scripts/cousin_review_all.sh  |  79 ++++++++++++++++++++
 scripts/cousins.json          |  22 ++++++
 scripts/lib/cousins.sh        |  30 ++++++++
 11 files changed, 738 insertions(+)
 create mode 100755 scripts/cousin_apply.sh
 create mode 100644 scripts/cousin_apply/role.md
 create mode 100644 scripts/cousin_apply/task.md
 create mode 100755 scripts/cousin_apply_all.sh
 create mode 100755 scripts/cousin_review.sh
 create mode 100644 scripts/cousin_review/role.md
 create mode 100644 scripts/cousin_review/task.md
 create mode 100755 scripts/cousin_review_all.sh
 create mode 100644 scripts/cousins.json
 create mode 100644 scripts/lib/cousins.sh

diff --git a/justfile b/justfile
index 5b57e1d..6900bad 100644
--- a/justfile
+++ b/justfile
@@ -158,3 +158,27 @@ alias tb := template-backport
 template-backport-all *args:
     bash scripts/template_backport_all.sh {{args}}
 alias tba := template-backport-all
+
+# ---------------------------------------------------------------------------- #
+#                                   COUSINS                                    #
+# ---------------------------------------------------------------------------- #
+
+# Review one cousin repo (by name from scripts/cousins.json) for template-sourced improvements (dry-run by default; --execute to run)
+cousin-review *args:
+    bash scripts/cousin_review.sh {{args}}
+alias cr := cousin-review
+
+# Review every cousin in scripts/cousins.json in parallel (dry-run by default; --execute to run)
+cousin-review-all *args:
+    bash scripts/cousin_review_all.sh {{args}}
+alias cra := cousin-review-all
+
+# Apply template-sourced changes to a cousin's opted-in paths and open a PR (dry-run by default; --execute to run)
+cousin-apply *args:
+    bash scripts/cousin_apply.sh {{args}}
+alias ca := cousin-apply
+
+# Apply changes to every cousin, one PR each (dry-run by default; --execute to run)
+cousin-apply-all *args:
+    bash scripts/cousin_apply_all.sh {{args}}
+alias caa := cousin-apply-all
diff --git a/scripts/cousin_apply.sh b/scripts/cousin_apply.sh
new file mode 100755
index 0000000..9dc6cf2
--- /dev/null
+++ b/scripts/cousin_apply.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROMPT_DIR="${SCRIPT_DIR}/cousin_apply"
+DEFAULT_TEMPLATE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# shellcheck source=lib/cousins.sh
+source "${SCRIPT_DIR}/lib/cousins.sh"
+# shellcheck source=lib/pr_prompt.sh
+source "${SCRIPT_DIR}/lib/pr_prompt.sh"
+cousins__require_jq
+
+# --- Locate a JS package runner (pnpm dlx preferred, npx fallback) ----------
+find_runner() {
+    if command -v pnpm &>/dev/null; then
+        echo "pnpm dlx"
+    elif command -v npx &>/dev/null; then
+        echo "npx"
+    else
+        echo "Error: neither pnpm nor npx found. Install one of them first." >&2
+        exit 1
+    fi
+}
+RUNNER="$(find_runner)"
+
+# --- Parse arguments --------------------------------------------------------
+EXECUTE=false
+COUSIN_NAME=""
+
+usage() {
+    cat >&2 <<EOF
+Usage: $0 [--execute] --cousin <name>
+
+Applies high-confidence template-sourced changes to a cousin's opted-in paths,
+runs per-target checks, and opens a single PR against the cousin repo.
+
+This script ALWAYS clones the cousin fresh into a tempdir so your local
+working copies are never touched. There is no local-path override.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --execute) EXECUTE=true; shift ;;
+        --cousin)  COUSIN_NAME="$2"; shift 2 ;;
+        -h|--help) usage; exit 0 ;;
+        *)         echo "Unknown arg: $1" >&2; usage; exit 2 ;;
+    esac
+done
+
+if [[ -z "$COUSIN_NAME" ]]; then
+    usage
+    exit 2
+fi
+
+CONFIG_PATH="$(cousins_config_path "$SCRIPT_DIR")"
+if [[ ! -f "$CONFIG_PATH" ]]; then
+    echo "Error: cousins config not found at ${CONFIG_PATH}" >&2
+    exit 1
+fi
+
+COUSIN_CONFIG_JSON="$(cousins_get_by_name "$CONFIG_PATH" "$COUSIN_NAME")"
+if [[ -z "$COUSIN_CONFIG_JSON" ]]; then
+    echo "Error: no cousin named '${COUSIN_NAME}' in ${CONFIG_PATH}" >&2
+    exit 1
+fi
+
+# Refuse to run if the cousin has no opted-in targets — this is a no-op.
+TARGET_COUNT="$(jq '(.targets // []) | length + ((.global_applies // []) | length)' <<<"$COUSIN_CONFIG_JSON")"
+if [[ "$TARGET_COUNT" -eq 0 ]]; then
+    echo "Cousin '${COUSIN_NAME}' has no targets or global_applies — nothing to do."
+    exit 0
+fi
+
+COUSIN_URL="$(jq -r '.url' <<<"$COUSIN_CONFIG_JSON")"
+TEMPLATE_DIR="${TEMPLATE_DIR:-$DEFAULT_TEMPLATE_DIR}"
+
+compose_prompt() {
+    local prompt=""
+    if [[ -f "${PROMPT_DIR}/role.md" ]]; then
+        prompt+="$(cat "${PROMPT_DIR}/role.md")"
+        prompt+=$'\n\n'
+    fi
+    for f in "${PROMPT_DIR}"/*.md; do
+        [[ "$(basename "$f")" == "role.md" ]] && continue
+        prompt+="$(cat "$f")"
+        prompt+=$'\n\n'
+    done
+    echo "$prompt"
+}
+PROMPT="$(compose_prompt)"
+
+# Apply mode: Claude edits files, runs checks, and creates a PR via gh.
+ALLOWED_TOOLS="Read Edit Write Bash"
+
+if [[ "$EXECUTE" == true ]]; then
+    WORK_DIR="$(mktemp -d)"
+    CLONE_PATH="${WORK_DIR}/${COUSIN_NAME}"
+    echo "Runner:        ${RUNNER}"
+    echo "Cousin:        ${COUSIN_NAME} (${COUSIN_URL})"
+    echo "Clone path:    ${CLONE_PATH}"
+    echo "Template:      ${TEMPLATE_DIR}"
+    echo "Prompt length: ${#PROMPT} chars"
+    echo "Allowed tools: ${ALLOWED_TOOLS}"
+    echo "---"
+
+    git clone --quiet "$COUSIN_URL" "$CLONE_PATH"
+
+    cd "$CLONE_PATH"
+    export TEMPLATE_DIR COUSIN_CONFIG_JSON COUSIN_NAME
+    OUTPUT="$(echo "${PROMPT}" | ${RUNNER} @anthropic-ai/claude-code --print \
+        --allowed-tools ${ALLOWED_TOOLS})"
+    echo "$OUTPUT"
+
+    PR_URL="$(pr_prompt_extract_url "$OUTPUT")"
+    if [[ -n "$PR_URL" ]]; then
+        pr_prompt_finalize "$PR_URL"
+    else
+        echo "No PR opened (no changes survived, or run was a no-op)."
+    fi
+
+    echo "Clone left at: ${CLONE_PATH}"
+else
+    echo "=== DRY RUN ==="
+    echo
+    echo "${PROMPT}"
+    echo "---"
+    echo "Runner:        ${RUNNER}"
+    echo "Cousin:        ${COUSIN_NAME} (${COUSIN_URL})"
+    echo "Template:      ${TEMPLATE_DIR}"
+    echo "Config:        ${CONFIG_PATH}"
+    echo "Prompt length: ${#PROMPT} chars"
+    echo "Allowed tools: ${ALLOWED_TOOLS}"
+    echo
+    echo "Pass --execute to actually run (clones the cousin fresh into a tempdir)."
+fi
diff --git a/scripts/cousin_apply/role.md b/scripts/cousin_apply/role.md
new file mode 100644
index 0000000..dc46c6b
--- /dev/null
+++ b/scripts/cousin_apply/role.md
@@ -0,0 +1,3 @@
+You are a pragmatic senior Rust engineer applying a small number of template-sourced improvements to explicitly-whitelisted Rust subpaths inside a third-party "cousin" repository.
+
+The cousin is NOT a fork of the template. It is its own project with its own conventions. You are a guest here. You may only touch files that the cousin's config file has explicitly opted-in, and you must never touch anything outside those slots. When in doubt, SKIP — it is much better to open a tiny, obviously-correct PR than a large or ambiguous one.
diff --git a/scripts/cousin_apply/task.md b/scripts/cousin_apply/task.md
new file mode 100644
index 0000000..da2dbd9
--- /dev/null
+++ b/scripts/cousin_apply/task.md
@@ -0,0 +1,108 @@
+## Context
+
+You are running inside a **clone of a cousin repository** (your current working directory). Your job is to apply a small set of high-confidence, template-sourced improvements — limited strictly to the opted-in slots in `COUSIN_CONFIG_JSON` — and open a single PR for this cousin containing all surviving changes.
+
+Environment variables:
+
+- `TEMPLATE_DIR` — absolute path to a local checkout of the template repo (the source of bytes to copy).
+- `COUSIN_CONFIG_JSON` — full JSON object describing THIS cousin. Schema documented in `scripts/cousin_review/task.md`.
+- `COUSIN_NAME` — short name, safe for branch names and PR titles.
+
+## Hard safety rules
+
+1. **Opt-in only.** The only file slots you may read, diff, or modify:
+   - For each `targets[i]`: files listed in `targets[i].applies`, resolved at path `targets[i].path/<file>` inside the cousin.
+   - Files in `global_applies`, resolved at the cousin repo root.
+   Anything else is off-limits. Do not edit, delete, rename, or create anything outside these slots.
+
+2. **Forbidden paths win.** If a candidate path matches any pattern in `forbidden_paths`, drop it immediately.
+
+3. **Never retype bytes.** Propagate changes by `cp "$TEMPLATE_DIR/<file>" "<cousin target path>/<file>"`. Never use the `Write` tool to reconstruct a template file from memory — that produces bogus full-file diffs from subtle formatting drift.
+
+4. **One PR per cousin, total.** All surviving changes across all targets go in a single branch and a single PR.
+
+5. **If a check fails, revert the offending change.** Do not try to "fix up" the cousin's surrounding code. Your mandate is limited to the opted-in slots.
+
+## Task
+
+### 1. Parse the config and verify constraints
+
+```
+echo "$COUSIN_CONFIG_JSON" | jq .
+```
+
+Build two flat lists:
+- `SLOTS` — the full set of allowed file slots from rule 1 above, as absolute paths inside the cousin.
+- `FORBIDDEN` — the `forbidden_paths` globs.
+
+Remove any SLOT whose path matches any FORBIDDEN glob. If the SLOTS list is now empty, print `No opted-in slots for ${COUSIN_NAME}.` and exit without branching or committing.
+
+### 2. Diff each slot against the template
+
+For each slot, run:
+
+```
+diff -u "<cousin slot path>" "$TEMPLATE_DIR/<template file>"
+```
+
+Decide per slot:
+
+- **APPLY** — the template version is clearly better and low-risk for this cousin. ~95% confidence bar.
+- **SKIP** — anything else. Log the reason.
+
+Use the cousin's `notes` field as context for judging applicability. If notes say "Bazel-managed, no Cargo", do not apply template files that assume Cargo/just tooling.
+
+### 3. Apply surviving changes
+
+For every APPLY slot, copy bytes verbatim:
+
+```
+mkdir -p "$(dirname "<cousin slot path>")"
+cp "$TEMPLATE_DIR/<template file>" "<cousin slot path>"
+```
+
+Use `cp` for full-file replacements. Use surgical `Edit` hunks ONLY if the cousin's existing file has project-specific content you must preserve — and even then, change as few lines as possible.
+
+### 4. Run per-target checks
+
+For each `targets[i]` whose files you modified, determine the check command using this priority order:
+
+1. If `targets[i].check` is set in the JSON, run exactly that command from the cousin repo root.
+2. Otherwise, if a `Cargo.toml` declares a package at `targets[i].path`, run `cargo check --manifest-path "targets[i].path/Cargo.toml"`.
+3. Otherwise, skip checks for that target and note it in the PR body as "unchecked".
+
+If a check fails, revert every change you made inside that target (`git checkout -- <slot path>`) and record the target under "reverted" in your notes. Do NOT attempt to fix the cousin's surrounding code.
+
+`global_applies` changes are not checked here — the cousin's CI will catch anything broken when the PR lands.
+
+### 5. Decide whether to PR
+
+After reverts, run `git status`. If nothing is modified, print `No cousin changes survived checks for ${COUSIN_NAME}.` and exit without branching or committing.
+
+### 6. Branch, commit, push, single PR
+
+```
+git checkout -b chore/template-sync-$(date +%Y-%m-%d)
+git add -A
+git commit -m "$(cat <<'MSG'
+chore: sync opted-in Rust files from shared template
+
+Applied the following template-sourced changes to opted-in paths:
+- <slot> — <what changed, one line>
+
+Skipped (with reason):
+- <slot> — <reason>
+
+Reverted after failed checks:
+- <target> — <reason>, or "None"
+MSG
+)"
+git push -u origin HEAD
+```
+
+Open a single PR with:
+
+- Title: `chore: sync opted-in Rust files from shared template`
+- Body: a markdown summary grouping applied changes by target, plus a "Skipped" section explaining what was considered but not applied, and a "Checks" section listing which command ran against which target (or "unchecked").
+
+Print the PR URL on the final line of your output.
diff --git a/scripts/cousin_apply_all.sh b/scripts/cousin_apply_all.sh
new file mode 100755
index 0000000..64a9dd4
--- /dev/null
+++ b/scripts/cousin_apply_all.sh
@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COUSIN_APPLY="${SCRIPT_DIR}/cousin_apply.sh"
+
+# shellcheck source=lib/cousins.sh
+source "${SCRIPT_DIR}/lib/cousins.sh"
+# shellcheck source=lib/pr_prompt.sh
+source "${SCRIPT_DIR}/lib/pr_prompt.sh"
+cousins__require_jq
+
+# Children must not prompt — only this driver does, once, at the end.
+export PR_PROMPT_SUPPRESS=1
+
+CONFIG_PATH="$(cousins_config_path "$SCRIPT_DIR")"
+if [[ ! -f "$CONFIG_PATH" ]]; then
+    echo "Error: cousins config not found at ${CONFIG_PATH}" >&2
+    exit 1
+fi
+
+ARGS=("$@")
+
+NAMES=()
+while IFS= read -r name; do
+    [[ -n "$name" ]] && NAMES+=("$name")
+done < <(cousins_list_names "$CONFIG_PATH")
+if [[ ${#NAMES[@]} -eq 0 ]]; then
+    echo "No cousins defined in ${CONFIG_PATH}."
+    exit 0
+fi
+
+WORK_DIR="$(mktemp -d)"
+echo "Work dir: ${WORK_DIR}"
+echo "Cousins:  ${NAMES[*]}"
+
+PIDS=()
+LOG_FILES=()
+
+for name in "${NAMES[@]}"; do
+    LOG_FILE="${WORK_DIR}/${name}.log"
+    echo "Applying to cousin: ${name}"
+    (
+        bash "$COUSIN_APPLY" --cousin "$name" ${ARGS[@]+"${ARGS[@]}"} \
+            >"$LOG_FILE" 2>&1
+    ) &
+    PIDS+=($!)
+    LOG_FILES+=("$LOG_FILE")
+done
+
+FAILED=0
+for i in "${!PIDS[@]}"; do
+    echo
+    echo "════════════════════════════════════════════════════════════════"
+    echo "  ${NAMES[$i]}"
+    echo "════════════════════════════════════════════════════════════════"
+    if wait "${PIDS[$i]}"; then
+        cat "${LOG_FILES[$i]}"
+    else
+        echo "FAILED:" >&2
+        cat "${LOG_FILES[$i]}" >&2 || true
+        FAILED=$((FAILED + 1))
+    fi
+done
+
+echo
+echo "---"
+echo "Finished: $((${#PIDS[@]} - FAILED))/${#PIDS[@]} succeeded"
+echo "Work dir left at: ${WORK_DIR}"
+
+# Collect PR URLs from each cousin's log and prompt once at the end.
+PR_URLS=()
+for LOG_FILE in "${LOG_FILES[@]}"; do
+    [[ -f "$LOG_FILE" ]] || continue
+    URL="$(pr_prompt_extract_url "$(cat "$LOG_FILE")")"
+    [[ -n "$URL" ]] && PR_URLS+=("$URL")
+done
+unset PR_PROMPT_SUPPRESS
+pr_prompt_finalize "${PR_URLS[@]}"
+
+exit $FAILED
diff --git a/scripts/cousin_review.sh b/scripts/cousin_review.sh
new file mode 100755
index 0000000..674f37a
--- /dev/null
+++ b/scripts/cousin_review.sh
@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROMPT_DIR="${SCRIPT_DIR}/cousin_review"
+DEFAULT_TEMPLATE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# shellcheck source=lib/cousins.sh
+source "${SCRIPT_DIR}/lib/cousins.sh"
+cousins__require_jq
+
+# --- Locate a JS package runner (pnpm dlx preferred, npx fallback) ----------
+find_runner() {
+    if command -v pnpm &>/dev/null; then
+        echo "pnpm dlx"
+    elif command -v npx &>/dev/null; then
+        echo "npx"
+    else
+        echo "Error: neither pnpm nor npx found. Install one of them first." >&2
+        exit 1
+    fi
+}
+RUNNER="$(find_runner)"
+
+# --- Parse arguments --------------------------------------------------------
+EXECUTE=false
+COUSIN_NAME=""
+CLONE_PATH=""
+
+usage() {
+    cat >&2 <<EOF
+Usage: $0 [--execute] --cousin <name> [<local_clone_path>]
+
+Reviews one cousin repo defined in scripts/cousins.json (or COUSINS_CONFIG
+override) for template-sourced improvements scoped to its opted-in paths.
+
+If <local_clone_path> is omitted, the cousin's 'url' is cloned into a tempdir.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --execute) EXECUTE=true; shift ;;
+        --cousin)  COUSIN_NAME="$2"; shift 2 ;;
+        -h|--help) usage; exit 0 ;;
+        *)         CLONE_PATH="$1"; shift ;;
+    esac
+done
+
+if [[ -z "$COUSIN_NAME" ]]; then
+    usage
+    exit 2
+fi
+
+CONFIG_PATH="$(cousins_config_path "$SCRIPT_DIR")"
+if [[ ! -f "$CONFIG_PATH" ]]; then
+    echo "Error: cousins config not found at ${CONFIG_PATH}" >&2
+    exit 1
+fi
+
+COUSIN_CONFIG_JSON="$(cousins_get_by_name "$CONFIG_PATH" "$COUSIN_NAME")"
+if [[ -z "$COUSIN_CONFIG_JSON" ]]; then
+    echo "Error: no cousin named '${COUSIN_NAME}' in ${CONFIG_PATH}" >&2
+    exit 1
+fi
+
+COUSIN_URL="$(jq -r '.url' <<<"$COUSIN_CONFIG_JSON")"
+
+TEMPLATE_DIR="${TEMPLATE_DIR:-$DEFAULT_TEMPLATE_DIR}"
+
+# --- Compose the prompt from markdown files ---------------------------------
+compose_prompt() {
+    local prompt=""
+    if [[ -f "${PROMPT_DIR}/role.md" ]]; then
+        prompt+="$(cat "${PROMPT_DIR}/role.md")"
+        prompt+=$'\n\n'
+    fi
+    for f in "${PROMPT_DIR}"/*.md; do
+        [[ "$(basename "$f")" == "role.md" ]] && continue
+        prompt+="$(cat "$f")"
+        prompt+=$'\n\n'
+    done
+    echo "$prompt"
+}
+PROMPT="$(compose_prompt)"
+
+# Read-only review: no Edit/Write, no git mutations.
+ALLOWED_TOOLS="Read Bash"
+
+if [[ "$EXECUTE" == true ]]; then
+    # Obtain a clone if one wasn't provided.
+    OWN_CLONE=false
+    if [[ -z "$CLONE_PATH" ]]; then
+        WORK_DIR="$(mktemp -d)"
+        CLONE_PATH="${WORK_DIR}/${COUSIN_NAME}"
+        git clone --quiet "$COUSIN_URL" "$CLONE_PATH"
+        OWN_CLONE=true
+    else
+        CLONE_PATH="$(cd "$CLONE_PATH" && pwd)"
+    fi
+
+    echo "Runner:        ${RUNNER}"
+    echo "Cousin:        ${COUSIN_NAME} (${COUSIN_URL})"
+    echo "Target:        ${CLONE_PATH}"
+    echo "Template:      ${TEMPLATE_DIR}"
+    echo "Prompt length: ${#PROMPT} chars"
+    echo "Allowed tools: ${ALLOWED_TOOLS}"
+    echo "---"
+
+    cd "$CLONE_PATH"
+    export TEMPLATE_DIR COUSIN_CONFIG_JSON COUSIN_NAME
+    echo "${PROMPT}" | ${RUNNER} @anthropic-ai/claude-code --print \
+        --allowed-tools ${ALLOWED_TOOLS}
+
+    if [[ "$OWN_CLONE" == true ]]; then
+        echo "Clone left at: ${CLONE_PATH}"
+    fi
+else
+    echo "=== DRY RUN ==="
+    echo
+    echo "${PROMPT}"
+    echo "---"
+    echo "Runner:        ${RUNNER}"
+    echo "Cousin:        ${COUSIN_NAME} (${COUSIN_URL})"
+    echo "Template:      ${TEMPLATE_DIR}"
+    echo "Config:        ${CONFIG_PATH}"
+    echo "Prompt length: ${#PROMPT} chars"
+    echo "Allowed tools: ${ALLOWED_TOOLS}"
+    echo
+    echo "Pass --execute to actually run (will clone the cousin if no path given)."
+fi
diff --git a/scripts/cousin_review/role.md b/scripts/cousin_review/role.md
new file mode 100644
index 0000000..45af7b8
--- /dev/null
+++ b/scripts/cousin_review/role.md
@@ -0,0 +1,5 @@
+You are a pragmatic senior Rust engineer reviewing a third-party "cousin" repository that happens to contain Rust code in specific, explicitly-whitelisted subpaths.
+
+Your job is to identify improvements from a shared Rust template that might be worth applying to those subpaths — and ONLY those subpaths — while being extremely careful not to recommend anything that would damage the surrounding (non-Rust or differently-structured) project.
+
+You are conservative by default. The cousin's own conventions always win. When in doubt, skip. Your output is a concise, actionable report. You do NOT modify files, create branches, or open PRs.
diff --git a/scripts/cousin_review/task.md b/scripts/cousin_review/task.md
new file mode 100644
index 0000000..3461b86
--- /dev/null
+++ b/scripts/cousin_review/task.md
@@ -0,0 +1,118 @@
+## Context
+
+You are running inside a **clone of a cousin repository** (your current working directory). It is NOT a fork of the template; it is an independent project whose structure, CI, and conventions may be very different. You are here only to suggest improvements for explicitly opted-in Rust code within it.
+
+Environment variables:
+
+- `TEMPLATE_DIR` — absolute path to a local checkout of the template repo (the "source of ideas").
+- `COUSIN_CONFIG_JSON` — a JSON string describing THIS cousin only. Schema:
+
+  ```
+  {
+    "name": "<short name>",
+    "url": "<git url>",
+    "notes": "<free-form context>",
+    "targets": [
+      {
+        "path": "<relative path inside the cousin repo, e.g. crates/foo>",
+        "applies": ["<file relative to template root>", ...],
+        "check": "<optional shell command for this target>"
+      }
+    ],
+    "global_applies": ["<file relative to template root>", ...],
+    "forbidden_paths": ["<glob>", ...]
+  }
+  ```
+
+- `COUSIN_NAME` — same as `.name` above, pre-extracted for convenience.
+
+## Safety rules — these are not guidelines
+
+1. **Opt-in only.** You may ONLY examine and discuss these file slots:
+   - For each `targets[i]`: the files listed in `targets[i].applies`, evaluated at path `targets[i].path/<file>` inside the cousin.
+   - Each file in `global_applies`, evaluated at the cousin repo root.
+   - Anything else is off-limits — do not diff it, do not open it, do not recommend touching it.
+
+2. **Forbidden paths win.** If a file slot derived from rule 1 matches any pattern in `forbidden_paths`, drop it immediately. Forbidden paths are a hard deny list and always take precedence.
+
+3. **Respect the cousin's conventions.** Read the cousin's own `notes` field carefully. If the cousin says "Bazel-managed", do not recommend changes that assume Cargo/just. If the cousin uses a different formatter style, note it but do not recommend clobbering it.
+
+4. **Never recommend repo-wide changes.** The template is not authoritative here — it is only a source of suggestions scoped to the opted-in slots.
+
+## Task
+
+### 1. Parse the config
+
+```
+echo "$COUSIN_CONFIG_JSON" | jq .
+```
+
+Extract `targets`, `global_applies`, `forbidden_paths`, and `notes`. If `targets` is empty and `global_applies` is empty, print `No opted-in paths for ${COUSIN_NAME}.` and exit.
+
+### 2. For each opted-in file slot, diff against the template
+
+Walk each `targets[i]`:
+
+```
+# For each file in targets[i].applies:
+diff -u "./${targets[i].path}/<file>" "$TEMPLATE_DIR/<file>"
+```
+
+…and each `global_applies` entry:
+
+```
+diff -u "./<file>" "$TEMPLATE_DIR/<file>"
+```
+
+If the cousin file does not exist at the expected location, note it as a **candidate new file** rather than a diff.
+
+Before opening any path, verify it does not match `forbidden_paths`. If it does, log "forbidden: <path>" and skip it entirely.
+
+### 3. Classify each diff
+
+For every non-empty diff, decide:
+
+- **SUGGEST-ADOPT** — the template version is clearly better for this target, and the cousin's surrounding project would tolerate the change. Must be ~95% confident. Consider: does the cousin already have this file? Is the diff small and low-risk? Does the cousin's notes field contradict this?
+- **SUGGEST-NEW-FILE** — the cousin doesn't have this file at all and would benefit from it. Even more conservative: only recommend if the file is clearly standalone (e.g. a per-crate `rustfmt.toml`) and the target crate path exists.
+- **KEEP-COUSIN** — the cousin's version is fine or better; no change recommended.
+- **NOT-APPLICABLE** — the diff exists but the change doesn't make sense in this cousin (e.g. the template assumes tooling the cousin doesn't have).
+
+Check the cousin's git history for intent where helpful:
+
+```
+git log --oneline -5 -- "<path>"
+```
+
+A commit like "match internal style guide" is a strong KEEP-COUSIN signal.
+
+### 4. Produce the report
+
+Print a single markdown report to stdout with this exact structure:
+
+```
+# Cousin Review: <COUSIN_NAME>
+
+## Summary
+<one-line summary — candidate count and any high-level observations>
+
+## Suggestions
+
+### <target path or "(global)"> — <file>
+**Classification:** SUGGEST-ADOPT | SUGGEST-NEW-FILE
+**What changes:** <1-2 sentence description>
+**Why it might help:** <reason scoped to this target>
+**Risk to surrounding project:** <specific things the reviewer should double-check>
+**Suggested action:** <"copy file verbatim" | "merge hunk" | "adapt idea">
+
+<repeat per suggestion>
+
+## Considered but skipped
+- <target path> — <file>: KEEP-COUSIN / NOT-APPLICABLE — <one-line reason>
+<repeat, or omit section if empty>
+
+## Forbidden paths honored
+- <path>: skipped because it matched <pattern>
+<repeat, or omit section if empty>
+```
+
+If there are no suggestions, still print the report with an empty Suggestions section and a clear summary line. Do not create any files, branches, or PRs. Do not modify the working tree.
diff --git a/scripts/cousin_review_all.sh b/scripts/cousin_review_all.sh
new file mode 100755
index 0000000..a56f242
--- /dev/null
+++ b/scripts/cousin_review_all.sh
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COUSIN_REVIEW="${SCRIPT_DIR}/cousin_review.sh"
+
+# shellcheck source=lib/cousins.sh
+source "${SCRIPT_DIR}/lib/cousins.sh"
+cousins__require_jq
+
+CONFIG_PATH="$(cousins_config_path "$SCRIPT_DIR")"
+if [[ ! -f "$CONFIG_PATH" ]]; then
+    echo "Error: cousins config not found at ${CONFIG_PATH}" >&2
+    exit 1
+fi
+
+ARGS=("$@")
+
+NAMES=()
+while IFS= read -r name; do
+    [[ -n "$name" ]] && NAMES+=("$name")
+done < <(cousins_list_names "$CONFIG_PATH")
+if [[ ${#NAMES[@]} -eq 0 ]]; then
+    echo "No cousins defined in ${CONFIG_PATH}. Add entries under '.cousins' (see \$example key for schema)."
+    exit 0
+fi
+
+WORK_DIR="$(mktemp -d)"
+echo "Work dir: ${WORK_DIR}"
+echo "Cousins:  ${NAMES[*]}"
+
+PIDS=()
+LOG_FILES=()
+
+for name in "${NAMES[@]}"; do
+    LOG_FILE="${WORK_DIR}/${name}.log"
+    echo "Reviewing cousin: ${name}"
+    (
+        bash "$COUSIN_REVIEW" --cousin "$name" ${ARGS[@]+"${ARGS[@]}"} \
+            >"$LOG_FILE" 2>&1
+    ) &
+    PIDS+=($!)
+    LOG_FILES+=("$LOG_FILE")
+done
+
+FAILED=0
+for i in "${!PIDS[@]}"; do
+    echo
+    echo "════════════════════════════════════════════════════════════════"
+    echo "  ${NAMES[$i]}"
+    echo "════════════════════════════════════════════════════════════════"
+    if wait "${PIDS[$i]}"; then
+        cat "${LOG_FILES[$i]}"
+    else
+        echo "FAILED:" >&2
+        cat "${LOG_FILES[$i]}" >&2 || true
+        FAILED=$((FAILED + 1))
+    fi
+done
+
+# Aggregate into a single report for convenience.
+AGGREGATE="${WORK_DIR}/REVIEW.md"
+{
+    echo "# Cousin Review — $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo
+    for i in "${!NAMES[@]}"; do
+        echo "---"
+        echo "## ${NAMES[$i]}"
+        echo
+        cat "${LOG_FILES[$i]}"
+        echo
+    done
+} >"$AGGREGATE"
+
+echo
+echo "---"
+echo "Finished: $((${#PIDS[@]} - FAILED))/${#PIDS[@]} succeeded"
+echo "Aggregate report: ${AGGREGATE}"
+exit $FAILED
diff --git a/scripts/cousins.json b/scripts/cousins.json
new file mode 100644
index 0000000..9683fc7
--- /dev/null
+++ b/scripts/cousins.json
@@ -0,0 +1,22 @@
+{
+  "$schema_doc": "See scripts/cousin_review/task.md for the full schema. Each entry in 'cousins' describes a third-party repo that contains Rust code in explicitly whitelisted subpaths. Nothing is touched unless it is opted-in via 'targets[].applies' or 'global_applies'. 'forbidden_paths' is a belt-and-suspenders hard deny list. 'targets[].check' overrides the default check command for that subpath.",
+  "$example": {
+    "name": "acme-monorepo",
+    "url": "git@github.com:acme/monorepo.git",
+    "notes": "Bazel-based monorepo. CI is Bazel-managed — never touch .github or root configs.",
+    "targets": [
+      {
+        "path": "backend/services/auth",
+        "applies": ["rustfmt.toml", "clippy.toml"],
+        "check": "bazel test //backend/services/auth/..."
+      },
+      {
+        "path": "libs/core",
+        "applies": ["rustfmt.toml"]
+      }
+    ],
+    "global_applies": ["CLAUDE.md"],
+    "forbidden_paths": [".github/**", "Cargo.toml", "justfile", "WORKSPACE", "MODULE.bazel"]
+  },
+  "cousins": []
+}
diff --git a/scripts/lib/cousins.sh b/scripts/lib/cousins.sh
new file mode 100644
index 0000000..794a8a9
--- /dev/null
+++ b/scripts/lib/cousins.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Shared helpers for reading cousins.json. Source this file — don't execute it.
+
+cousins__require_jq() {
+    if ! command -v jq &>/dev/null; then
+        echo "Error: jq is required but not installed. Install with: brew install jq" >&2
+        exit 1
+    fi
+}
+
+# Print the path to cousins.json, respecting an optional override via
+# COUSINS_CONFIG env var.
+cousins_config_path() {
+    local default="$1"   # caller passes scripts dir
+    echo "${COUSINS_CONFIG:-${default}/cousins.json}"
+}
+
+# Print the JSON object for a single cousin by .name, or empty string if not
+# found. Arg 1: path to cousins.json, arg 2: cousin name.
+cousins_get_by_name() {
+    local config_path="$1"
+    local name="$2"
+    jq -c --arg n "$name" '.cousins[] | select(.name == $n)' "$config_path"
+}
+
+# Print all cousin names, one per line. Arg 1: path to cousins.json.
+cousins_list_names() {
+    local config_path="$1"
+    jq -r '.cousins[].name' "$config_path"
+}