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

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

@@ -11,6 +11,7 @@
 #   ask-colleague write   "<task>" [--apply]     implement a change (preview by default)
 #   ask-colleague feedback <id|last> --rating N  grade a past drive (ROI loop); no rating -> show
 #   ask-colleague feedback list                  list every recorded drive by request + grade
+#   ask-colleague clean                          reap stale colleague/* branches + artifacts (#162)
 #
 # explore/review run in a throwaway `git worktree` at HEAD, so they can never
 # touch your working tree or branch (any stray write is discarded). write also
@@ -22,6 +23,18 @@
 # most recent consequential write. Grade a probe by its printed task-id (every
 # drive prints `task:` and a `grade:` hint), or find it with `feedback list`.
 #
+# A crashed/interrupted `write --apply` can leave a dangling colleague/<id>
+# branch (and 0-byte .colleague/ artifacts) that breaks `git fetch`. The
+# EXIT-trap cleanup below only reaps the *current* read-only run's worktree, not
+# a *prior* crashed run — `ask-colleague clean` (which shells out to `colleague
+# clean`) reaps those, scoped strictly to colleague/* so an unrelated branch is
+# never touched.
+#
+# Exit-code policy (matches colleague's CLI contract, #161): 0 success · 1
+# user-input error (bad/missing verb, flag, arg, or path; dirty-tree state guard
+# — same class as the runtime's EXIT_USER_ERROR guard) · 2 environment/setup
+# error (missing required tool, colleague CLI not found, missing prompt template).
+#
 set -euo pipefail
 
 SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -29,24 +42,28 @@ PROMPTS_DIR="$SKILL_DIR/prompts"
 
 # ── resolve the colleague CLI (installed, then local-dev fallback) ─────────
 COLLEAGUE=()
-resolve_colleague() {
-    if command -v colleague >/dev/null 2>&1; then
-        COLLEAGUE=(colleague)        # installed tool — the normal case
-        return 0
-    fi
-    # Local-dev fallback: inside the colleague checkout, run via uv.
-    local dir="$PWD"
+
+_colleague_via_uv() {
+    local dir="$1"
     while [[ -n "$dir" ]] && [[ "$dir" != "/" ]]; do
         if [[ -f "$dir/pyproject.toml" ]] \
             && grep -q '^name = "colleague"' "$dir/pyproject.toml" 2>/dev/null; then
-            if command -v uv >/dev/null 2>&1; then
-                COLLEAGUE=(uv run colleague)
-                return 0
-            fi
-            break
+            command -v uv >/dev/null 2>&1 || return 1
+            COLLEAGUE=(uv run --project "$dir" colleague)
+            return 0
         fi
         dir=$(dirname "$dir")
     done
+    return 1
+}
+
+resolve_colleague() {
+    if command -v colleague >/dev/null 2>&1; then
+        COLLEAGUE=(colleague)        # installed tool — the normal case
+        return 0
+    fi
+    _colleague_via_uv "$PWD"  && return 0
+    _colleague_via_uv "$REPO" && return 0
     cat >&2 <<'EOF'
 error: colleague CLI not found.
 hint: install it with `uv tool install colleague` (or `pipx install colleague`),
@@ -66,9 +83,11 @@ Usage:
   ask-colleague write   "<task>" [--apply|--pr]  Implement a change (preview by default; --apply lands it)
   ask-colleague feedback <id|last> [--rating N]  Grade a past drive (ROI loop); with --rating records, without shows
   ask-colleague feedback list                    List every recorded drive by request + grade (find one by its request)
+  ask-colleague clean [--dry-run]                Reap stale/corrupt colleague/* branches + orphaned .colleague/ artifacts (#162)
 
 Options:
   --repo PATH        Target repo (default: .)
+  --dry-run          (clean) report what would be reaped without changing anything
   --base BRANCH      Base for `review` diff (default: main)
   --engine NAME      Backend plugin (default: $COLLEAGUE_ENGINE or vllm-openai)
   --model NAME       Model (default: $COLLEAGUE_MODEL or sakamakismile/Qwen3.6-27B-Text-NVFP4-MTP)
@@ -89,19 +108,22 @@ feedback grades a finished drive: stats (in the artifact) say what it cost,
 feedback says how good it was — together, the ROI of outsourcing. explore/review
 do not move `last` (they are read-only) — grade them by their printed task-id, or
 run `ask-colleague feedback list` to find a drive by its request.
+clean recovers a repo a crashed run wedged: it reaps stale/corrupt colleague/*
+branches + orphaned .colleague/ artifacts (scoped to colleague/* only). For the
+full flag set (--merged / --older-than) call `colleague clean` directly.
 EOF
 }
 
 # ── parse the verb ──────────────────────────────────────────────────────────
 VERB="${1:-}"
 case "$VERB" in
-    explore | review | write | feedback) shift ;;
+    explore | review | write | feedback | clean) shift ;;
     -h | --help) usage; exit 0 ;;
-    "") usage >&2; exit 2 ;;
+    "") usage >&2; exit 1 ;;  # missing arg -> user-input error (#161)
     *)
-        echo "error: unknown verb '$VERB' (expected explore|review|write|feedback)" >&2
+        echo "error: unknown verb '$VERB' (expected explore|review|write|feedback|clean)" >&2
         echo "hint: run 'ask-colleague --help'" >&2
-        exit 2
+        exit 1  # bad verb -> user-input error (#161)
         ;;
 esac
 
@@ -125,7 +147,7 @@ need_value() {  # $1 = remaining arg count ($#), $2 = flag name
     [[ "$1" -ge 2 ]] || {
         echo "error: $2 requires a value" >&2
         echo "hint: run 'ask-colleague --help'" >&2
-        exit 2
+        exit 1  # missing flag value -> user-input error (#161)
     }
 }
 
@@ -143,6 +165,7 @@ TIMEOUT="${COLLEAGUE_TIMEOUT:-${CONVERTIBLE_TIMEOUT:-300}}"
 ALLOW_DIRTY=0
 APPLY=0
 OPEN_PR=0
+DRY_RUN=0
 RATING=""
 NOTES=""
 BY=""
@@ -160,33 +183,41 @@ while [[ $# -gt 0 ]]; do
         --apply) APPLY=1; shift ;;
         --allow-dirty) ALLOW_DIRTY=1; shift ;;
         --pr) OPEN_PR=1; shift ;;
+        --dry-run) DRY_RUN=1; shift ;;
         --rating) need_value "$#" "$1"; RATING="$2"; shift 2 ;;
         --notes) need_value "$#" "$1"; NOTES="$2"; shift 2 ;;
         --by) need_value "$#" "$1"; BY="$2"; shift 2 ;;
         -h | --help) usage; exit 0 ;;
         --) shift; while [[ $# -gt 0 ]]; do ARG="${ARG:+$ARG }$1"; shift; done ;;
-        -*) echo "error: unknown option '$1'" >&2; echo "hint: run 'ask-colleague --help'" >&2; exit 2 ;;
+        # unknown option -> user-input error (#161)
+        -*) echo "error: unknown option '$1'" >&2; echo "hint: run 'ask-colleague --help'" >&2; exit 1 ;;
         *) ARG="${ARG:+$ARG }$1"; shift ;;
     esac
 done
 
-[[ -n "$ARG" ]] || { echo "error: $VERB needs a description argument" >&2; usage >&2; exit 2; }
-[[ -d "$REPO" ]] || { echo "error: --repo is not a directory: $REPO" >&2; exit 2; }
+# 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
+    [[ -z "$ARG" ]] || { echo "error: clean takes no description argument" >&2; exit 1; }
+else
+    [[ -n "$ARG" ]] || { echo "error: $VERB needs a description argument" >&2; usage >&2; exit 1; }
+fi
+[[ -d "$REPO" ]] || { echo "error: --repo is not a directory: $REPO" >&2; exit 1; }
 REPO="$(cd "$REPO" && pwd)"
 
 # One git-repo guard for every verb: --repo is a runtime target like `git -C`, but
 # it must at least be a real git work tree. Fail fast with a clear message instead
-# of an opaque mid-drive error (and every verb here needs git: read-only verbs add
-# a worktree, write commits a drive branch).
+# of an opaque mid-drive error (read-only verbs add a worktree, write commits a
+# drive branch, clean reaps colleague/* refs).
 git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1 \
-    || { echo "error: --repo is not a git repository: $REPO" >&2; exit 2; }
+    || { echo "error: --repo is not a git repository: $REPO" >&2; exit 1; }
 
 # review interpolates --base into the LLM instruction ("git diff $BASE...HEAD"),
 # so reject a value that is not a real commit/ref before it is rendered into the
 # prompt — fail fast rather than hand the model a bogus (or injected) ref.
 if [[ "$VERB" == "review" ]]; then
     git -C "$REPO" rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null 2>&1 \
-        || { echo "error: --base is not a valid commit/ref in $REPO: $BASE" >&2; exit 2; }
+        || { echo "error: --base is not a valid commit/ref in $REPO: $BASE" >&2; exit 1; }
 fi
 
 resolve_colleague || exit 2
@@ -229,7 +260,9 @@ print_result() {
     # real repo) -> print a copy-paste `grade:` hint with the explicit task-id, so
     # the caller never has to rely on `last` (issue #132). A preview leaves it
     # empty (its artifact was discarded with the worktree, so it is not gradable).
-    ASK_COLLEAGUE_REAL_ARTIFACT_DIR="${1:-}" ASK_COLLEAGUE_GRADABLE="${2:-}" python3 -c '
+    # $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 '
 import sys, json, os
 raw = sys.stdin.read().strip()
 if not raw:
@@ -268,7 +301,7 @@ 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:
+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
@@ -276,7 +309,14 @@ if ap:
 # `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)
-sys.exit(0 if ok else 1)
+if ok:
+    sys.exit(0)
+else:
+    rc = os.environ.get("ASK_COLLEAGUE_DRIVE_RC")
+    if rc in ("1", "2"):
+        sys.exit(int(rc))
+    else:
+        sys.exit(1)
 '
 }
 
@@ -394,8 +434,8 @@ _add_worktree() {
 run_readonly() {
     local instruction="$1"
     _add_worktree
-    local out
-    out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$_WT" --no-pr "${COMMON_FLAGS[@]}")" || true
+    local out rc=0
+    out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$_WT" --no-pr "${COMMON_FLAGS[@]}")" || rc=$?
     _DRIVE_BRANCH="$(printf '%s' "$out" | _extract_branch)"
     # Preserve the artifact to the real repo BEFORE the EXIT trap removes the
     # worktree, so the drive can be graded by its task-id (`ask-colleague feedback
@@ -409,7 +449,7 @@ run_readonly() {
         real_dir="$REPO/.colleague"
         gradable="1"
     fi
-    printf '%s' "$out" | print_result "$real_dir" "$gradable"
+    printf '%s' "$out" | print_result "$real_dir" "$gradable" "$rc"
 }
 
 # ── write preview (default): drive in a throwaway worktree, show the would-be ──
@@ -418,8 +458,8 @@ run_readonly() {
 run_preview() {
     local instruction="$1"
     _add_worktree
-    local out
-    out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$_WT" --no-pr "${COMMON_FLAGS[@]}")" || true
+    local out rc=0
+    out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$_WT" --no-pr "${COMMON_FLAGS[@]}")" || rc=$?
     _DRIVE_BRANCH="$(printf '%s' "$out" | _extract_branch)"
 
     # Capture the would-be patch before _cleanup_worktree deletes the drive branch.
@@ -428,9 +468,9 @@ run_preview() {
         patch="$(git -C "$REPO" diff "HEAD..$_DRIVE_BRANCH" 2>/dev/null || true)"
     fi
 
-    local rc=0
-    printf '%s' "$out" | print_result || rc=$?
-    if [[ "$rc" -eq 0 ]]; then
+    local prc=0
+    printf '%s' "$out" | print_result "" "" "$rc" || prc=$?
+    if [[ "$prc" -eq 0 ]]; then
         if [[ -n "$patch" ]]; then
             printf '\n--- preview diff (NOT applied — pass --apply to land it) ---\n'
             printf '%s\n' "$patch"
@@ -438,7 +478,7 @@ run_preview() {
             printf '\n(preview: no file changes reported; NOT applied)\n'
         fi
     fi
-    return "$rc"
+    return "$prc"
 }
 
 # ── write verb: preview by default; --apply lands a drive branch; --pr opens a ─
@@ -454,7 +494,10 @@ run_write() {
         && [[ -n "$(git -C "$REPO" status --porcelain 2>/dev/null)" ]]; then
         echo "error: working tree is dirty — commit/stash first, or pass --allow-dirty" >&2
         echo "hint: 'colleague drive --no-pr' commits uncommitted edits onto the drive branch" >&2
-        exit 2
+        # User-fixable state guard -> exit 1, matching the runtime's own
+        # dirty-tree guard (colleague/handoff.py _guard_clean_tree =
+        # EXIT_USER_ERROR), not exit 2 (#161).
+        exit 1
     fi
     # The runtime now enforces its own dirty-tree guard (colleague#149); pass
     # --allow-dirty through so an operator opt-in here isn't re-refused by the
@@ -462,20 +505,22 @@ run_write() {
     # top — read-only/preview verbs run in a clean worktree and must not get it),
     # which sidesteps the `set -u` empty-array expansion hazard.
     [[ "$ALLOW_DIRTY" -eq 1 ]] && COMMON_FLAGS+=(--allow-dirty)
-    # `|| true`: a failed drive (`colleague drive` returns 1 when status != ok,
-    # printing the result JSON to stdout) must still flow into print_result so the
-    # digest is emitted (to stderr) and the wrapper exits non-zero — not aborted by
-    # `set -e` at the assignment, which would swallow the digest. Matches the
-    # read-only / preview paths, which already guard this way.
-    local out
+    # `|| rc=$?`: a failed drive (`colleague drive` exits non-zero, printing the
+    # result JSON to stdout) must still flow into print_result so the digest is
+    # emitted (to stderr) and the wrapper propagates the drive's real exit code.
+    # The rc is captured (declaration split from the assignment so `local` doesn't
+    # mask it) rather than discarded with `|| true`, which would have collapsed the
+    # tri-state rc; `set -e` does not abort at the assignment. Matches the
+    # read-only / preview paths, which guard this way.
+    local out rc=0
     if [[ "$OPEN_PR" -eq 1 ]]; then
-        out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$REPO" "${COMMON_FLAGS[@]}")" || true
+        out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$REPO" "${COMMON_FLAGS[@]}")" || rc=$?
     else
-        out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$REPO" --no-pr "${COMMON_FLAGS[@]}")" || true
+        out="$("${COLLEAGUE[@]}" drive "$instruction" --repo "$REPO" --no-pr "${COMMON_FLAGS[@]}")" || rc=$?
     fi
     # A landed write persists its artifact in the real repo and moves `last`, so it
     # is gradable — print the `grade:` hint (with the explicit task-id).
-    printf '%s' "$out" | print_result "" "1"
+    printf '%s' "$out" | print_result "" "1" "$rc"
 }
 
 # ── feedback verb: grade a finished drive (the ROI loop) ────────────────────
@@ -501,9 +546,23 @@ run_feedback() {
     "${cmd[@]}"
 }
 
+# ── clean verb: recover a repo a crashed run wedged (#162) ──────────────────
+# A thin pass-through to `colleague clean`: the runtime reaps stale/corrupt
+# colleague/* branches + orphaned .colleague/ artifacts, scoped strictly to
+# colleague/* (so an unrelated branch is never touched) and conservative with
+# .git/objects. No worktree, no engine — colleague owns the reap + its own
+# stdout/stderr/exit. The full flag set (--merged / --older-than) lives on
+# `colleague clean`; the skill forwards the common --dry-run.
+run_clean() {
+    local cmd=("${COLLEAGUE[@]}" clean --repo "$REPO")
+    [[ "$DRY_RUN" -eq 1 ]] && cmd+=(--dry-run)
+    "${cmd[@]}"
+}
+
 case "$VERB" in
     explore) run_readonly "$(render_prompt explore)" ;;
     review) run_readonly "$(render_prompt review)" ;;
     write) run_write "$(render_prompt write)" ;;
     feedback) run_feedback "$ARG" ;;
+    clean) run_clean ;;
 esac

{rollout_cli-0.3.0 → rollout_cli-0.3.2}/.markdownlint-cli2.yaml

@@ -23,6 +23,9 @@ ignores:
   - ".teken/**"
   # Vendored skills are cited verbatim from guildmaster — do not reformat them.
   - ".claude/skills/**"
+  # Recipe payload snapshots are cited verbatim (cite-don't-import) and copied
+  # into target repos byte-for-byte — do not reformat them.
+  - "recipes/**/files/**"
   # devague-generated convergence artifacts (the exact `devague export` output;
   # headings carry the announcement verbatim and claims embed <placeholder>s).
   - "docs/specs/**"

rollout_cli-0.3.2/AGENTS.colleague.md

@@ -0,0 +1,11 @@
+# Colleague Resident
+
+You are a colleague resident — a long-lived mesh peer that works alongside
+other agents in the AgentCulture IRC mesh.  Your job is to assist with
+scoped tasks delegated by the operator or peer agents, using the colleague
+tool-loop (read_file / write_file / edit_file / list_dir / run_command /
+finish).
+
+Follow the operator's AGENTS.md instructions and the skills loaded from
+.colleague/skills/ when present.  Prefer small, reversible steps; handoff
+via finish when done.

{rollout_cli-0.3.0 → rollout_cli-0.3.2}/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-06-13
+
+### Added
+
+- Promoted into the Culture mesh as colleague resident `rollout-cli` (culture.yaml backend colleague, AGENTS.colleague.md)
+
+### Changed
+
+- Rewrote CLAUDE.md from the /init seed into a full runtime prompt: cardinal no-foreign-edits rule (ship outside only via /mass-update or /communicate), mechanism-picking guidance, and the devex/agex .gitignore rollout playbook
+
+## [0.3.1] - 2026-06-12
+
+### Added
+
+- **`ask-colleague-revendor` recipe** (`recipes/ask-colleague-revendor/`) —
+  propagates an upstream `ask-colleague` wrapper change from its origin
+  (colleague) to downstream consumers, and adds the skill fresh where absent.
+  Existing installs get `scripts/ask-colleague.sh` overwritten **only**
+  (wrapper-only, matching colleague#183; a consumer's `SKILL.md` provenance
+  token is never clobbered); absent installs get the full skill with the repo
+  nick substituted in. The recipe `README.md` carries the **downstream-consumer
+  ledger** and the **reconciliation procedure**, making rollout-cli the owner of
+  that propagation contract — closes #3.
+
+### Changed
+
+- Re-vendored rollout-cli's own `ask-colleague` wrapper from colleague#183
+  (`resolve_colleague()` honors `--repo`; `drive` tri-state exit propagated;
+  no dead `artifact:` line). `SKILL.md`/prompts untouched.
+- `.markdownlint-cli2.yaml` ignores `recipes/**/files/**` — recipe payload
+  snapshots are cited verbatim and must not be reformatted.
+- `docs/skill-sources.md` points to the recipe as the owner of downstream
+  `ask-colleague` propagation + consumer tracking.
+
+### Fixed
+
+- Hardened the `ask-colleague-revendor` recipe after review (Qodo on #5):
+  `check.sh` now requires a **quoted semver** `version` line and an existing
+  `CHANGELOG.md` (matching what `apply` actually needs, so a repo can't pass
+  `plan` then fail mid-`apply`; also drops a commented-`version` false positive);
+  `apply.sh` escapes `sed` replacement metacharacters in the repo nick; and
+  `manifest.toml` `touched_files` now declares the `SKILL.md`/prompt paths that
+  a fresh add writes.
+
 ## [0.3.0] - 2026-06-06
 
 ### Added

rollout_cli-0.3.2/CLAUDE.md

@@ -0,0 +1,79 @@
+# CLAUDE.md — rollout-cli
+
+This repository hosts the **rollout-cli** agent: a cross-repo
+**change-propagation engine**. Its job is to take one scoped change and land it
+across many sibling repos — deterministically where the change is scriptable,
+or via a different-backend colleague where the change is easier to describe than
+to script.
+
+## The cardinal rule — never touch another repo directly
+
+**rollout-cli only ever edits its own working tree.** It does **not** open files
+in sibling repos and edit them, run `Write`/`Edit` against paths outside this
+repo, or `git commit` in another checkout. Making a change *outside this repo*
+has exactly **two** acceptable channels, and nothing else:
+
+| Channel | Skill | Use it to… |
+|---------|-------|------------|
+| **Ship code** | **`/mass-update`** | Propagate an actual code/file change to one or more sibling repos. It drives `ask-colleague` per target in a throwaway worktree (preview), then lands a `colleague/<id>` branch (`--apply`) or opens a PR (`--pr`). One call → one PR per repo. |
+| **Ship a request** | **`/communicate`** | File a tracked GitHub issue on a sibling repo, pull a sibling issue into context, or send a message to a Culture mesh channel — when the right move is to *ask the owning repo* rather than push a diff (e.g. the change can't land as a PR there, or needs that repo's judgment). |
+
+In-repo work (this `CLAUDE.md`, recipes under the rollout engine, skills under
+`.claude/skills/`, docs, tests) is normal — edit freely. The rule is only about
+**reaching outside**: if a change belongs in another repo, it goes through
+`/mass-update` or `/communicate`. No exceptions, no "just this once" direct edits.
+
+## Picking a mechanism
+
+- **Deterministic `rollout` recipe engine** — for a *fixed, scriptable* transform
+  (drop an exact file, flip a config line) reproduced identically across repos.
+  Preferred when the content needs no model judgment; reproducible, no LLM. This
+  is rollout-cli's core engine (`rollout` recipes + `plan`/`apply`).
+- **`/mass-update`** — the LLM-driven layer on `ask-colleague`, for a *described*
+  change across a handful of named repos (`--repos a,b,c`). Even here, prefer a
+  deterministic `--file DEST --content/--from` op (verbatim bytes the model must
+  not regenerate) over free-text when the content is fixed.
+- **`/communicate`** — when no diff should land (the target can't accept it, or it
+  needs the owner's call). File an issue instead of forcing a PR.
+
+Always **preview first** (mass-update/ask-colleague default: throwaway worktree,
+zero side effects), then `--pr`. Colleague's output is a second opinion to
+verify and own, never authority. Confirm before opening PRs across many repos.
+
+## Identity
+
+`culture.yaml` declares this agent as `suffix: rollout-cli`, `backend: colleague`
+(promoted into the Culture mesh via `colleague promote`; owns `#rollout-cli`). The
+resident runtime prompt is `AGENTS.colleague.md`.
+
+## Rollout playbook: devex/agex data-dir `.gitignore`
+
+A worked example of the discovery-before-fan-out discipline.
+
+`devex doctor` warns when a repo's devex data dir is missing its `.gitignore`
+(`⚠️ .devex/.gitignore missing — data/ may end up tracked`). The fix is a fixed
+two-line file:
+
+```text
+# Managed by devex — do not edit.
+data/
+```
+
+**Do not blind-fan-out.** The data dir is `.devex/` in some repos and `.agex/`
+in others, and the fix is only real where the data dir is **git-tracked**. Scan
+first: for each sibling with a `<datadir>/data/` but no `<datadir>/.gitignore`,
+check whether the *target file path* is already ignored —
+`git check-ignore -q <datadir>/.gitignore`:
+
+- **Not ignored → REAL target.** The `.gitignore` is a genuine, trackable fix;
+  ship it via `/mass-update --file <datadir>/.gitignore --content '…'`
+  (one mass-update call per distinct `<datadir>`, since the DEST differs).
+- **Already ignored → not a target.** The whole data dir is ignored at the repo
+  root, so `data/` is *already* protected and git refuses to track a
+  `<datadir>/.gitignore` there — a PR would land nothing. The doctor warning is a
+  false positive. Don't PR it; if it's worth flagging, `/communicate` an issue to
+  that repo (e.g. guildmaster, where `.gitignore` already ignores `.agex/`).
+
+Note: `devex`'s own self-heal (`devex overview`/`devex init`) bootstraps `.devex/`
+only — it will **not** restore an `.agex/.gitignore`, so for `.agex` repos the
+file must be supplied verbatim.

{rollout_cli-0.3.0 → rollout_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rollout-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: Cross-repo propagation workflow built on refactor-cli — apply a transformation across many repos at once.
 Project-URL: Homepage, https://github.com/agentculture/rollout-cli
 Project-URL: Issues, https://github.com/agentculture/rollout-cli/issues

rollout_cli-0.3.2/culture.yaml

@@ -0,0 +1,4 @@
+agents:
+- suffix: rollout-cli
+  backend: colleague
+  model: sakamakismile/Qwen3.6-27B-Text-NVFP4-MTP

{rollout_cli-0.3.0 → rollout_cli-0.3.2}/docs/skill-sources.md

@@ -105,6 +105,12 @@ cp -R ../colleague/.claude/skills/ask-colleague .claude/skills/
 Once guildmaster re-broadcasts `ask-colleague`, switch the upstream column back
 to `../guildmaster/.claude/skills/ask-colleague/` and re-sync from there.
 
+The procedure above re-syncs *this* repo's own copy. Propagating an upstream
+`ask-colleague` change **out to the other downstream consumers** — and the
+ledger of who those consumers are — is owned by the
+[`ask-colleague-revendor`](../recipes/ask-colleague-revendor/README.md) rollout
+recipe (rollout-cli#3).
+
 ## Tooling prerequisites
 
 - **`devex`** (>=0.21) on PATH — `cicd` delegates the PR lifecycle to `devex pr`.

{rollout_cli-0.3.0 → rollout_cli-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rollout-cli"
-version = "0.3.0"
+version = "0.3.2"
 description = "Cross-repo propagation workflow built on refactor-cli — apply a transformation across many repos at once."
 readme = "README.md"
 license = "Apache-2.0"

rollout_cli-0.3.2/recipes/ask-colleague-revendor/README.md

@@ -0,0 +1,84 @@
+# ask-colleague-revendor
+
+Propagate an upstream `ask-colleague` wrapper change from its origin repo
+(**colleague**) to every downstream repo that vendors the skill, and add the
+skill fresh where it is absent.
+
+This recipe is also rollout-cli's answer to
+[agentculture/rollout-cli#3](https://github.com/agentculture/rollout-cli/issues/3):
+the **reconciliation procedure** and the **downstream-consumer ledger** live
+here, in the propagation tool, rather than as an outbound ledger forced into the
+origin repo (colleague).
+
+## What it does
+
+`ask-colleague` is first-party to **colleague**; downstream repos vendor it
+`cite, don't import`. The wrapper (`scripts/ask-colleague.sh`) is meant to be
+**verbatim** across consumers; the `SKILL.md` is **not** — each consumer
+substitutes its own nick into one provenance clause
+(`which <nick> vendors *from* guildmaster`) and may lag the origin on prose.
+
+So the recipe is deliberately split:
+
+- **Existing install** → overwrite `scripts/ask-colleague.sh` **only**. This
+  matches how upstream changes land (colleague#183 was wrapper-only) and never
+  clobbers a consumer's `SKILL.md` provenance token or local divergence.
+- **Skill absent** → lay down the full skill (`wrapper` + `SKILL.md` +
+  `prompts/`), substituting the target repo's nick into the `SKILL.md`
+  provenance line via the `__REPO_NICK__` token in `files/SKILL.md.tmpl`.
+
+`check.sh` classifies a repo `done` (wrapper already byte-matches the vendored
+snapshot), `ok` (wrapper missing or stale → apply), or `needs-attention` (no
+version-bumpable `pyproject.toml`).
+
+## Downstream-consumer ledger
+
+Origin: **colleague** (`agentculture/colleague`,
+`.claude/skills/ask-colleague/`). Known consumers that re-vendor the wrapper:
+
+| Consumer | Repo | Vendoring | Notes |
+|----------|------|-----------|-------|
+| culture | `agentculture/culture` | re-vendor wrapper | merged at pre-#183; carries `which culture …` token |
+| agentirc | `agentculture/agentirc` | re-vendor wrapper | merged at pre-#183; no `culture.yaml` (identity differs) |
+| steward | `agentculture/steward` | re-vendor wrapper | merged at pre-#183; carries `which steward …` token |
+| rollout-cli | `agentculture/rollout-cli` | re-vendor wrapper | this repo ("self"); carries `which rollout-cli …` token |
+| dgx-spark-cli | `agentculture/dgx-spark-cli` | fresh add | skill was absent |
+| reterminal-cli | `agentculture/reterminal-cli` | re-vendor wrapper | merged at pre-#183 |
+
+Keep this table current when a consumer is added or dropped.
+
+## Reconciliation procedure (when colleague lands an upstream change)
+
+1. **Refresh the snapshot** from the origin checkout so the recipe carries the
+   new wrapper (and, for fresh-adds, current `SKILL.md`/prompts):
+
+   ```bash
+   O=../colleague/.claude/skills/ask-colleague
+   cp "$O/scripts/ask-colleague.sh" recipes/ask-colleague-revendor/files/scripts/
+   cp "$O"/prompts/*.md            recipes/ask-colleague-revendor/files/prompts/
+   cp "$O/SKILL.md"                recipes/ask-colleague-revendor/files/SKILL.md.tmpl
+   # re-apply the token: in SKILL.md.tmpl, `which colleague vendors *from*`
+   #   → `which __REPO_NICK__ vendors *from*`
+   ```
+
+2. **Dry-run** the classification across consumers:
+
+   ```bash
+   uv run rollout-cli plan ask-colleague-revendor \
+     --repos culture,agentirc,steward,dgx-spark-cli,reterminal-cli --base <clones-dir>
+   ```
+
+3. **Apply** — branch, patch wrapper, bump version, open one PR per repo
+   (operator squash-merges; rollout never merges):
+
+   ```bash
+   uv run rollout-cli apply ask-colleague-revendor \
+     --repos culture,agentirc,steward,dgx-spark-cli,reterminal-cli --base <clones-dir> --yes
+   ```
+
+   Run against **fresh clones** (not live agent checkouts) so a running agent is
+   never disrupted; rollout requires each target clean and on `main`.
+
+4. Update the consumer ledger above if the set changed.
+
+Refs: colleague#183 (wrapper fixes), colleague#180/#181, rollout-cli#3.

rollout_cli-0.3.2/recipes/ask-colleague-revendor/apply.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# apply.sh — re-vendor the ask-colleague skill wrapper from colleague (#183).
+# Usage: apply.sh [REPO_DIR]   (default: current directory)
+#
+# Idempotent. Two cases, one code path:
+#   * Existing install  — overwrite scripts/ask-colleague.sh ONLY. This mirrors
+#     colleague#183, which was wrapper-only; a downstream's SKILL.md carries a
+#     repo-specific provenance token (and may intentionally diverge), so it is
+#     never clobbered here.
+#   * Skill absent       — lay down the full skill (wrapper + SKILL.md + prompts),
+#     substituting the target repo's nick into SKILL.md's provenance line.
+set -euo pipefail
+
+REPO="${1:-.}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SRC="${SCRIPT_DIR}/files"
+DEST="${REPO}/.claude/skills/ask-colleague"
+
+mkdir -p "${DEST}/scripts" "${DEST}/prompts"
+
+# (1) Wrapper — always overwrite verbatim (the #183 payload).
+cp "${SRC}/scripts/ask-colleague.sh" "${DEST}/scripts/ask-colleague.sh"
+chmod 0755 "${DEST}/scripts/ask-colleague.sh"
+
+# (2) SKILL.md — only when absent (fresh add); preserve an existing copy.
+if [ ! -f "${DEST}/SKILL.md" ]; then
+    nick="$(basename "$(cd "${REPO}" && pwd)")"
+    # Escape sed replacement metacharacters (& \ and the / delimiter) so a repo
+    # basename containing them can't corrupt or break the substitution.
+    nick_esc="$(printf '%s' "${nick}" | sed -e 's/[&/\\]/\\&/g')"
+    sed "s/__REPO_NICK__/${nick_esc}/g" "${SRC}/SKILL.md.tmpl" > "${DEST}/SKILL.md"
+fi
+
+# (3) Prompts — only when absent (fresh add); never disturb existing ones.
+for p in explore review write; do
+    if [ ! -f "${DEST}/prompts/${p}.md" ]; then
+        cp "${SRC}/prompts/${p}.md" "${DEST}/prompts/${p}.md"
+    fi
+done