rollout-cli 0.3.2__tar.gz → 0.4.2__tar.gz

{rollout_cli-0.3.2 → rollout_cli-0.4.2}/.claude/skills/ask-colleague/SKILL.md

@@ -7,18 +7,20 @@ description: >
   isn't a stronger model; it's a second, independent mind, and that diversity is
   the value: `ask-colleague review` gets a candid second opinion on a diff,
   `ask-colleague explore` gets a fresh read of an area, `ask-colleague write`
-  hands off a small implementation, and `ask-colleague feedback` grades a finished
-  work item (the ROI loop). Reach for it REFLEXIVELY, the way you'd lean over to the
+  hands off a small implementation, `ask-colleague feedback` grades a finished
+  work item (the ROI loop), and `ask-colleague clean` reaps stale/corrupt
+  `colleague/*` branches a crashed run left behind (which can break `git fetch`).
+  Reach for it REFLEXIVELY, the way you'd lean over to the
   teammate at the next desk — not only when asked: before you present or open a PR
   on a non-trivial committed diff, run `review` for a diverse second opinion; for a
   fresh read of an unfamiliar area whose answer is independent of your current
   context, run `explore`. Both are read-only — isolated in a throwaway git
-  worktree, zero side effects — so the reflex is always safe; the side-effecting
-  `write --apply` / `write --pr` still needs the user's go-ahead. Triggers when the
+  worktree, zero side effects to your tree/branch — so the reflex is always safe; the
+  side-effecting `write --apply` / `write --pr` still needs the user's go-ahead. Triggers when the
   user says "ask colleague", "ask a colleague to review/explore/write this", "have
   colleague take a look", "get a second opinion", "ask the other model", "rate that
-  work item" — and still on the legacy "outsource this". Colleague's output is a second
-  opinion to verify and own, never authority.
+  work item", "clean up a crashed colleague run" — and still on the legacy "outsource this".
+  Colleague's output is a second opinion to verify and own, never authority.
 ---
 
 # ask-colleague — lean on colleague as a different mind
@@ -95,10 +97,11 @@ else an install hint.
 
 | Verb | What it does | Side effects |
 |------|--------------|--------------|
-| `explore "<question or area>"` | Read-only investigation of the repo; the model reads and reports findings. | **None** — runs in a throwaway worktree at HEAD. |
-| `review "<what to focus on>" [--base main]` | A diverse second opinion on the **committed** diff (`<base>...HEAD`). | **None** — throwaway worktree; reviews committed changes only. |
-| `write "<task>" [--apply\|--pr]` | Implement a change. **Previews by default** (throwaway worktree, prints the would-be diff); `--apply` lands a work branch in place; `--pr` pushes + opens a PR. | **None** by default (preview); a `colleague/<id>` work branch / PR only with `--apply` / `--pr`. |
+| `explore "<question or area>"` | Read-only investigation of the repo; the model reads and reports findings. | **None** to your working tree / branch — runs in a throwaway worktree at HEAD; writes only a gradable run artifact under the gitignored `.colleague/` bookkeeping dir. |
+| `review "<what to focus on>" [--base main]` | A diverse second opinion on the **committed** diff (`<base>...HEAD`). | **None** to your working tree / branch — throwaway worktree, committed changes only; writes only a gradable run artifact under the gitignored `.colleague/` bookkeeping dir. |
+| `write "<task>" [--apply\|--pr]` | Implement a change. **Previews by default** (throwaway worktree, prints the would-be diff); `--apply` lands a work branch in place; `--pr` pushes + opens a PR. | **None** to your working tree / branch by default (preview); a `colleague/<id>` work branch / PR only with `--apply` / `--pr`. |
 | `feedback <id\|last> [--rating N]` | **Grade a finished work item** (the ROI loop). With `--rating N` (1–5, plus `--notes`) it records feedback; without, it shows the work item's existing feedback. `last` resolves the most recent work item in `--repo`. | Writes `.colleague/<id>.feedback.json` only when `--rating` is given; read-only otherwise. |
+| `clean [--dry-run]` | **Reap what a crashed run left behind** (#162): stale/corrupt `colleague/*` branches + orphaned 0-byte `.colleague/` artifacts that can wedge `git fetch`. Scoped strictly to `colleague/*` (never touches an unrelated branch); conservative with `.git/objects` (reports 0-byte loose objects + suggests `git prune`, never deletes them). A thin pass-through to `colleague clean`. | Deletes corrupt `colleague/<id>` refs + 0-byte `.colleague/` artifacts in `--repo`; `--dry-run` changes nothing. |
 
 ### Options
 
@@ -116,10 +119,15 @@ else an install hint.
 | `--rating N` | (`feedback`) record a 1–5 quality rating for the work item. |
 | `--notes "..."` | (`feedback`) free-text notes stored with the rating. |
 | `--by NAME` | (`feedback`) who is grading (default: colleague's resolved identity). |
+| `--dry-run` | (`clean`) report what would be reaped without changing anything. |
+| `--json` | (any verb) machine-readable output: stdout carries **only** the result JSON, every diagnostic/digest line goes to stderr. |
 
 The result printed to stdout is the work item's `TaskResult.summary` (plus
 `changed_files` / work branch for `write`), parsed from `colleague work
---json`. Per-step progress streams to stderr while it runs.
+--json`. Per-step progress streams to stderr while it runs. Pass `--json` to get
+the raw `TaskResult` on stdout instead of the human digest (the drive verbs emit
+the normalized `TaskResult`; `feedback` / `clean` forward `--json` to colleague),
+keeping stdout valid JSON for a machine consumer while diagnostics stay on stderr.
 
 ## When to reach for which verb
 
@@ -140,6 +148,11 @@ The result printed to stdout is the work item's `TaskResult.summary` (plus
   says how *good* it was — together they let you compute the **ROI of asking
   colleague** and decide whether to ask again (and which backend). Grade the most
   recent work item with `ask-colleague feedback last --rating 4 --notes "…"`.
+- **clean** — recovery, not routine. A crashed / interrupted `write --apply` can
+  leave a dangling `colleague/<id>` branch pointing at half-written (0-byte)
+  objects that **breaks `git fetch` / `git pull`**. Run `ask-colleague clean`
+  (or `colleague clean`) to reap it — start with `--dry-run` to see what it would
+  remove. It only ever touches `colleague/*` refs and `.colleague/` artifacts.
 
 ## Hard rules (do not violate)
 
@@ -168,11 +181,20 @@ The result printed to stdout is the work item's `TaskResult.summary` (plus
   uncommitted work, commit it first.
 - The default backend is whatever single model is running locally; a multi-model
   fleet (different model per verb) is separate infrastructure.
+- **Every verb writes bookkeeping under `.colleague/`** (run artifacts for
+  explore/review/write; feedback records; the `last_work` pointer) — none of it
+  in your tracked tree, but in a repo that does **not** already gitignore
+  `.colleague/` it shows up as untracked files. **Add `.colleague/` to your
+  `.gitignore`** (keep `!/.colleague/commands/` if you commit command templates).
+- **A crashed run can wedge `git fetch`.** A `write --apply` interrupted
+  mid-commit can leave a dangling `colleague/<id>` branch + 0-byte artifacts;
+  `ask-colleague clean` recovers it. A SIGKILL/OOM *during* the commit can still
+  corrupt git objects (git/filesystem durability, not the skill's to guarantee)
+  — which is exactly what `clean` is for.
 
 ## Provenance
 
 This is a **first-party** colleague skill — colleague is its origin. It is
-the inverse of the other skills under `.claude/skills/`, which
-rollout-cli vendors *from* guildmaster. See `docs/skill-sources.md`.
-The `cite, don't import` policy holds: downstream repos copy it, they don't
-symlink or depend on it.
+the inverse of the other skills under `.claude/skills/`, which rollout-cli
+vendors *from* guildmaster. See `docs/skill-sources.md`. The `cite, don't import`
+policy holds: downstream repos copy it, they don't symlink or depend on it.

{rollout_cli-0.3.2 → rollout_cli-0.4.2}/.claude/skills/ask-colleague/scripts/ask-colleague.sh

@@ -100,6 +100,8 @@ Options:
   --rating N         (feedback) record a 1-5 quality rating for the drive
   --notes "..."      (feedback) free-text notes to store with the rating
   --by NAME          (feedback) who is grading (default: colleague's resolved identity)
+  --json             Machine-readable output: stdout carries only the result JSON,
+                     every diagnostic/digest line goes to stderr (any verb)
 
 explore/review run in a throwaway git worktree at HEAD — they cannot touch your
 working tree or branch. review compares <base>...HEAD (committed changes only).
@@ -127,16 +129,23 @@ case "$VERB" in
         ;;
 esac
 
-# Required external tools — fail fast with a clear message, not an opaque
-# mid-run error, if the environment is missing one.
-require_tools() {
+# Verify the external tools a given verb path actually needs are on PATH — fail
+# fast with a clear message, not an opaque mid-run error. The required set is
+# verb-specific (the caller passes it once the verb + flags are known, below):
+# feedback/clean are thin pass-throughs to `colleague` plus the shared git
+# work-tree guard, so they need only git; the drive verbs (explore/review/write)
+# also render a prompt and parse colleague's --json result via python3, and the
+# worktree-isolated paths additionally need mktemp. grep is only used by the
+# uv-fallback resolver, which degrades to the clear "colleague not found" message
+# when absent, so it is not a hard requirement here.
+require_tools() {  # $@ = tool names this verb path needs
     local missing=() t
-    for t in python3 git grep mktemp; do
+    for t in "$@"; do
         command -v "$t" >/dev/null 2>&1 || missing+=("$t")
     done
     if [[ ${#missing[@]} -gt 0 ]]; then
         echo "error: missing required tool(s): ${missing[*]}" >&2
-        echo "hint: ask-colleague needs python3, git, grep, and mktemp on PATH." >&2
+        echo "hint: '$VERB' needs these on PATH: $*" >&2
         exit 2
     fi
 }
@@ -151,8 +160,6 @@ need_value() {  # $1 = remaining arg count ($#), $2 = flag name
     }
 }
 
-require_tools
-
 # ── defaults + flag parsing ─────────────────────────────────────────────────
 REPO="."
 BASE="main"
@@ -170,6 +177,7 @@ RATING=""
 NOTES=""
 BY=""
 ARG=""
+JSON_OUT=0
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
@@ -187,6 +195,7 @@ while [[ $# -gt 0 ]]; do
         --rating) need_value "$#" "$1"; RATING="$2"; shift 2 ;;
         --notes) need_value "$#" "$1"; NOTES="$2"; shift 2 ;;
         --by) need_value "$#" "$1"; BY="$2"; shift 2 ;;
+        --json) JSON_OUT=1; shift ;;
         -h | --help) usage; exit 0 ;;
         --) shift; while [[ $# -gt 0 ]]; do ARG="${ARG:+$ARG }$1"; shift; done ;;
         # unknown option -> user-input error (#161)
@@ -195,6 +204,23 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+# Now that the verb and its flags are known, require only the tools THIS path
+# uses. feedback/clean shell straight to `colleague` (+ the git work-tree guard
+# below), so they need only git — not python3/mktemp (qodo: the old blanket check
+# failed those verbs in minimal envs). write --apply/--pr lands in place with no
+# throwaway worktree, so it needs no mktemp either.
+case "$VERB" in
+    feedback | clean) require_tools git ;;
+    write)
+        if [[ "$APPLY" -eq 1 || "$OPEN_PR" -eq 1 ]]; then
+            require_tools git python3
+        else
+            require_tools git python3 mktemp  # preview runs in a throwaway worktree
+        fi
+        ;;
+    *) require_tools git python3 mktemp ;;  # explore / review
+esac
+
 # clean takes no description argument; every other verb requires one. (All of the
 # guards below are user-input errors -> exit 1, per the policy comment at the top.)
 if [[ "$VERB" == "clean" ]]; then
@@ -262,9 +288,10 @@ print_result() {
     # empty (its artifact was discarded with the worktree, so it is not gradable).
     # $3 (optional): exit code from the colleague drive command, propagated to
     # the caller when the drive itself failed.
-    ASK_COLLEAGUE_REAL_ARTIFACT_DIR="${1:-}" ASK_COLLEAGUE_GRADABLE="${2:-}" ASK_COLLEAGUE_DRIVE_RC="${3:-}" python3 -c '
+    ASK_COLLEAGUE_REAL_ARTIFACT_DIR="${1:-}" ASK_COLLEAGUE_GRADABLE="${2:-}" ASK_COLLEAGUE_DRIVE_RC="${3:-}" ASK_COLLEAGUE_JSON="${JSON_OUT:-0}" python3 -c '
 import sys, json, os
 raw = sys.stdin.read().strip()
+json_mode = os.environ.get("ASK_COLLEAGUE_JSON") == "1"
 if not raw:
     sys.stderr.write("error: colleague produced no result on stdout (see diagnostics above)\n")
     sys.exit(2)
@@ -275,40 +302,69 @@ except Exception:
     sys.stderr.write(raw[:2000] + "\n")
     sys.exit(2)
 ok = d.get("status") == "ok"
-out = sys.stdout if ok else sys.stderr
 tid = d.get("task_id") or ""
-print("status:", d.get("status"), file=out)
-if tid:
-    print("task:", tid, file=out)
+# Resolve the artifact path to the preserved copy when the drive ran in a
+# throwaway worktree (read-only verbs); the raw JSON points into the now-deleted
+# worktree, so both the digest and the --json output report the real location.
+ap = d.get("artifacts_path")
+real_dir = os.environ.get("ASK_COLLEAGUE_REAL_ARTIFACT_DIR") or ""
+if ap and real_dir:
+    ap = os.path.join(real_dir, os.path.basename(ap))
 # A drive that stopped without calling finish (colleague#142) or exhausted its
 # step budget did NOT deliver an authoritative result — its summary is the model
 # trailing off mid-task. Warn so the caller treats it as a partial, not a verdict.
-# The warning is a DIAGNOSTIC -> always stderr (never stdout), so a successful
-# drive keeps a clean, machine-readable stdout (no single quotes in this body).
+# The warning is a DIAGNOSTIC -> always stderr (never stdout), so both the digest
+# and --json keep a clean, machine-readable stdout (no single quotes in this body).
 if d.get("stopped_without_finish"):
     print("warning: drive ended without calling finish — treat the summary as a", file=sys.stderr)
     print("         partial (the model stopped mid-task), not an authoritative result.", file=sys.stderr)
 elif d.get("not_finished"):
     print("warning: drive ran out of steps without finishing — summary is partial.", file=sys.stderr)
-print(file=out)
-print((d.get("summary") or "").rstrip(), file=out)
-cf = d.get("changed_files") or []
-if cf:
-    print("\nchanged files:", ", ".join(cf), file=out)
-if d.get("branch"):
-    print("drive branch:", d["branch"], file=out)
-ap = d.get("artifacts_path")
-real_dir = os.environ.get("ASK_COLLEAGUE_REAL_ARTIFACT_DIR") or ""
-if ap and real_dir:
-    ap = os.path.join(real_dir, os.path.basename(ap))
-if ap and os.environ.get("ASK_COLLEAGUE_GRADABLE") == "1":
-    print("artifact:", ap, file=out)
-# A drive is gradable whenever its artifact survives — including a FAILED drive
-# (colleague writes an artifact on failure too, h5): a failure rated 1/5 is exactly
-# the ROI signal, so the hint must not be gated on `ok` (#139 qodo). It prints to
-# `out` (stderr on failure), matching the rest of the failure digest.
-if tid and os.environ.get("ASK_COLLEAGUE_GRADABLE") == "1":
-    print("grade:", "ask-colleague feedback", tid, "--rating N", file=out)
+if json_mode:
+    # --json contract: stdout carries ONLY the TaskResult JSON; every
+    # human/diagnostic line already went to stderr above. The exit code still
+    # reflects drive success/failure.
+    #
+    # artifacts_path mirrors the digest gate (ASK_COLLEAGUE_GRADABLE): it is only
+    # meaningful when the artifact SURVIVES. A preview (run_preview passes empty
+    # gradable) drives in a throwaway worktree the EXIT trap deletes, so the raw
+    # path points at a dir that is gone by the time the caller reads it — drop it
+    # rather than hand a machine consumer a dead path (#186 qodo finding-3). When
+    # gradable, rewrite it to the preserved copy in the real repo.
+    gradable = os.environ.get("ASK_COLLEAGUE_GRADABLE") == "1"
+    if not gradable:
+        d.pop("artifacts_path", None)
+    elif ap:
+        d["artifacts_path"] = ap
+    json.dump(d, sys.stdout)
+    sys.stdout.write("\n")
+    # The task:/grade: hints are diagnostics -> stderr (stdout stays pure JSON).
+    # task_id is already in the payload, but echoing the copy-paste grade hint
+    # keeps the convention every work item follows (rule 907536) without breaking
+    # the stdout contract. Gated on gradable, exactly like the digest below.
+    if tid and gradable:
+        print("task:", tid, file=sys.stderr)
+        print("grade:", "ask-colleague feedback", tid, "--rating N", file=sys.stderr)
+else:
+    out = sys.stdout if ok else sys.stderr
+    print("status:", d.get("status"), file=out)
+    if tid:
+        print("task:", tid, file=out)
+    print(file=out)
+    print((d.get("summary") or "").rstrip(), file=out)
+    cf = d.get("changed_files") or []
+    if cf:
+        print("\nchanged files:", ", ".join(cf), file=out)
+    if d.get("branch"):
+        print("drive branch:", d["branch"], file=out)
+    if ap and os.environ.get("ASK_COLLEAGUE_GRADABLE") == "1":
+        print("artifact:", ap, file=out)
+    # A drive is gradable whenever its artifact survives — including a FAILED
+    # drive (colleague writes an artifact on failure too, h5): a failure rated
+    # 1/5 is exactly the ROI signal, so the hint must not be gated on `ok` (#139
+    # qodo). It prints to `out` (stderr on failure), matching the failure digest.
+    if tid and os.environ.get("ASK_COLLEAGUE_GRADABLE") == "1":
+        print("grade:", "ask-colleague feedback", tid, "--rating N", file=out)
 if ok:
     sys.exit(0)
 else:
@@ -471,11 +527,15 @@ run_preview() {
     local prc=0
     printf '%s' "$out" | print_result "" "" "$rc" || prc=$?
     if [[ "$prc" -eq 0 ]]; then
+        # In --json mode stdout is reserved for the result JSON print_result just
+        # emitted, so the would-be patch is a diagnostic -> stderr (fd 2).
+        local diff_fd=1
+        [[ "$JSON_OUT" -eq 1 ]] && diff_fd=2
         if [[ -n "$patch" ]]; then
-            printf '\n--- preview diff (NOT applied — pass --apply to land it) ---\n'
-            printf '%s\n' "$patch"
+            printf '\n--- preview diff (NOT applied — pass --apply to land it) ---\n' >&"$diff_fd"
+            printf '%s\n' "$patch" >&"$diff_fd"
         else
-            printf '\n(preview: no file changes reported; NOT applied)\n'
+            printf '\n(preview: no file changes reported; NOT applied)\n' >&"$diff_fd"
         fi
     fi
     return "$prc"
@@ -543,6 +603,9 @@ run_feedback() {
         cmd+=(show "$ref")
     fi
     cmd+=(--repo "$REPO")
+    # colleague feedback supports --json natively; forward the operator's request
+    # so stdout stays machine-readable end-to-end.
+    [[ "$JSON_OUT" -eq 1 ]] && cmd+=(--json)
     "${cmd[@]}"
 }
 
@@ -556,6 +619,8 @@ run_feedback() {
 run_clean() {
     local cmd=("${COLLEAGUE[@]}" clean --repo "$REPO")
     [[ "$DRY_RUN" -eq 1 ]] && cmd+=(--dry-run)
+    # colleague clean supports --json natively; forward it for machine-readable output.
+    [[ "$JSON_OUT" -eq 1 ]] && cmd+=(--json)
     "${cmd[@]}"
 }
 

rollout_cli-0.4.2/.claude/skills/mass-update/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: mass-update
+type: command
+description: >
+  Propagate ONE deterministic change across many GitHub repos at once. Targets
+  are GitHub slugs (`owner/repo`), not local paths. For each target, mass-update
+  clones fresh into a scratch dir, applies a verbatim file drop (`--file`) or
+  anchored edit (`--edit`), and cleans up on exit. Default is PREVIEW (zero
+  outward effect); `--pr` pushes a branch, opens a PR, and files a companion
+  tracking issue. No LLM, no ask-colleague — increment 1 is deterministic only.
+  Triggers when the user says "mass update", "propagate this change across
+  repos", "apply X to all these repos", "roll this out to agentculture/foo", or
+  "relicense these repos". One call = one PR per repo; run it several times for
+  independent changes.
+---
+
+# mass-update — one deterministic change, many repos
+
+`mass-update` is a **deterministic** cross-repo propagator. It clones each target
+repo fresh into a scratch directory, applies verbatim file drops or anchored
+edits, and cleans up on exit. No LLM, no `ask-colleague`.
+
+## What changed
+
+mass-update previously drove `ask-colleague` against sibling local checkouts
+(worktrees, `colleague/<id>` branches, `--apply`/`--pr` landing). That flow is
+gone. The new mechanism:
+
+- **Targets are GitHub slugs** (`owner/repo`), not local paths. A local path is
+  rejected.
+- For each target it **clones fresh** into a gitignored scratch dir
+  (`.mass-update/clones/<owner>-<repo>/`) inside rollout-cli, branches off the
+  default branch, applies a deterministic change in the clone, and cleans the
+  clone up on exit (success or failure). `--keep-clone` retains it for debugging.
+- The cardinal rule: **rollout-cli never reaches beyond its own repo.** The
+  entire on-disk footprint stays inside rollout-cli; the only outward effects
+  are `git push` (the PR) and `/communicate` (the issue).
+- Increment 1 supports only deterministic ops: `--file` (verbatim) and
+  `--edit` (anchored unique-occurrence replace). Free-text described changes are
+  a deferred follow-up.
+
+## How to run
+
+```bash
+bash .claude/skills/mass-update/scripts/mass-update.sh \
+  --repos <owner/repo[,owner/repo...]> <ops> [--pr] [--keep-clone]
+```
+
+Run it from the rollout-cli repo root. `--repos` takes comma-separated GitHub
+slugs (e.g. `agentculture/widget-cli`).
+
+## Op shapes (combinable in one call)
+
+| Op | What it does |
+|----|--------------|
+| `--file DEST --from SRC` | Create/replace `DEST` in each clone with **exactly** `SRC`'s bytes (verbatim). Use this for content the model shouldn't regenerate — a `LICENSE`, a CI workflow, a config file. |
+| `--file DEST --content '...'` | Same, but the verbatim content is given inline. |
+| `--edit 'FILE: FIND => REPLACE'` | Replace the **unique** occurrence of `FIND` with `REPLACE` in `FILE`. Errors on 0 or >1 matches. Repeatable. |
+
+All ops given in one call are applied to each clone. At least one op is required.
+
+## Landing — preview or PR
+
+| Flag | Effect |
+|------|--------|
+| *(none)* | **PREVIEW.** Clone, apply ops, print diff, cleanup. **Zero outward effect.** Always start here. |
+| `--pr` | Clone, apply, commit, push, open PR, file a companion tracking issue via `communicate/scripts/post-issue.sh`, cleanup. Both the PR URL and issue URL are printed. |
+| `--keep-clone` | Retain the scratch clone on exit (debug). |
+
+## Worked example — propagate a LICENSE to a sibling repo
+
+Replace `agentculture/widget-cli`'s `LICENSE` with rollout-cli's own `LICENSE`,
+then open a PR and file a tracking issue:
+
+```bash
+bash .claude/skills/mass-update/scripts/mass-update.sh \
+  --repos agentculture/widget-cli \
+  --file LICENSE --from ./LICENSE \
+  --pr
+```
+
+Run it **without `--pr` first** to inspect the preview diff; re-run with `--pr`
+once the diff is correct.
+
+## Where it fits
+
+- **`rollout` engine** — deterministic recipes, reproducible, no model. Reach for
+  it for org-wide fan-out (`--org`) and exact, scriptable transforms.
+- **`mass-update`** — *this skill*: deterministic cross-repo propagation via
+  fresh clones, for verbatim file drops and anchored edits across a handful of
+  GitHub repos.
+
+## Honest limits
+
+- **Deterministic only (increment 1).** Free-text described changes are NOT
+  supported — they are a deferred follow-up that needs an `ask-colleague`
+  edit-in-place mode.
+- **One drive per target.** Each target succeeds or fails independently; a
+  non-zero exit means at least one target failed (others may have landed).
+  Re-run for the failures.
+- **Requires `gh` and `git`.** Both must be on PATH and authenticated
+  (`gh auth status` must succeed) before any clone begins.
+- **`--keep-clone`** retains the scratch directory for debugging; without it,
+  clones are cleaned up on both success and failure.
+
+## Provenance
+
+mass-update is a rollout-cli-local skill. The `cite, don't import` policy holds:
+downstream repos copy it, they don't symlink or depend on it.