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

{rollout_cli-0.4.1 → 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.4.1 → 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.1 → rollout_cli-0.4.2}/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.4.2] - 2026-06-13
+
+### Changed
+
+- ask-colleague: sync SKILL.md + script to the canonical colleague source (documents the `clean` verb; script +137 lines). rollout-cli's copy was stale vs its origin (agentculture/colleague). Provenance line kept repo-correct.
+
 ## [0.4.1] - 2026-06-13
 
 ### Fixed

{rollout_cli-0.4.1 → rollout_cli-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rollout-cli
-Version: 0.4.1
+Version: 0.4.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.4.1 → rollout_cli-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rollout-cli"
-version = "0.4.1"
+version = "0.4.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.4.1 → rollout_cli-0.4.2}/recipes/ask-colleague-revendor/apply.sh

@@ -1,12 +1,12 @@
 #!/usr/bin/env bash
-# apply.sh — re-vendor the ask-colleague skill wrapper from colleague (#183).
+# apply.sh — re-vendor the ask-colleague skill wrapper from its canonical
+# colleague source.
 # 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.
+#   * Existing install  — overwrite scripts/ask-colleague.sh ONLY (wrapper-only
+#     re-vendor); 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
@@ -18,7 +18,7 @@ DEST="${REPO}/.claude/skills/ask-colleague"
 
 mkdir -p "${DEST}/scripts" "${DEST}/prompts"
 
-# (1) Wrapper — always overwrite verbatim (the #183 payload).
+# (1) Wrapper — always overwrite verbatim (the canonical wrapper payload).
 cp "${SRC}/scripts/ask-colleague.sh" "${DEST}/scripts/ask-colleague.sh"
 chmod 0755 "${DEST}/scripts/ask-colleague.sh"
 

{rollout_cli-0.4.1 → rollout_cli-0.4.2}/recipes/ask-colleague-revendor/check.sh

@@ -2,7 +2,7 @@
 # check.sh — classify a target repo for the ask-colleague-revendor recipe.
 # Usage: check.sh [REPO_DIR]   (default: current directory)
 # Prints exactly one status word to stdout and exits 0:
-#   "done"            — wrapper already byte-matches the vendored #183 wrapper
+#   "done"            — wrapper already byte-matches the vendored canonical wrapper
 #   "ok"              — wrapper missing or stale (recipe adds / refreshes it)
 #   "needs-attention" — not a version-bumpable agent repo (no pyproject version)
 set -euo pipefail

{rollout_cli-0.4.1 → rollout_cli-0.4.2}/recipes/ask-colleague-revendor/files/SKILL.md.tmpl

@@ -120,10 +120,14 @@ else an install hint.
 | `--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
 

{rollout_cli-0.4.1 → rollout_cli-0.4.2}/recipes/ask-colleague-revendor/files/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/recipes/ask-colleague-revendor/manifest.toml

@@ -0,0 +1,27 @@
+name = "ask-colleague-revendor"
+# The wrapper is always rewritten. The remaining paths are written only on a
+# fresh add (skill absent); declared here so recipe introspection covers every
+# file apply.sh may touch.
+touched_files = [
+    ".claude/skills/ask-colleague/scripts/ask-colleague.sh",
+    ".claude/skills/ask-colleague/SKILL.md",
+    ".claude/skills/ask-colleague/prompts/explore.md",
+    ".claude/skills/ask-colleague/prompts/review.md",
+    ".claude/skills/ask-colleague/prompts/write.md",
+]
+bump_level = "patch"
+changelog_text = """\
+### Changed
+
+- **Re-vendored the `ask-colleague` skill wrapper from its canonical colleague
+  source** (`.claude/skills/ask-colleague/scripts/ask-colleague.sh`): the wrapper
+  now supports `--json` machine-readable output — stdout carries **only** the
+  result JSON (the drive verbs emit the normalized `TaskResult`; `feedback` /
+  `clean` forward `--json` to colleague) while every diagnostic/digest line goes
+  to stderr, keeping stdout valid JSON for a machine consumer. This supersedes the
+  earlier wrapper-only colleague#183 snapshot (which predated `--json`). The
+  bundled `SKILL.md` template documents the new verb/flag; an existing downstream
+  `SKILL.md` is left untouched (it carries a repo-specific provenance token and
+  may diverge). Where the skill was absent, it is added fresh (wrapper +
+  `SKILL.md` + prompts).
+"""

{rollout_cli-0.4.1 → rollout_cli-0.4.2}/uv.lock

@@ -430,7 +430,7 @@ wheels = [
 
 [[package]]
 name = "rollout-cli"
-version = "0.4.1"
+version = "0.4.2"
 source = { editable = "." }
 
 [package.dev-dependencies]

rollout_cli-0.4.1/recipes/ask-colleague-revendor/manifest.toml

@@ -1,25 +0,0 @@
-name = "ask-colleague-revendor"
-# The wrapper is always rewritten. The remaining paths are written only on a
-# fresh add (skill absent); declared here so recipe introspection covers every
-# file apply.sh may touch.
-touched_files = [
-    ".claude/skills/ask-colleague/scripts/ask-colleague.sh",
-    ".claude/skills/ask-colleague/SKILL.md",
-    ".claude/skills/ask-colleague/prompts/explore.md",
-    ".claude/skills/ask-colleague/prompts/review.md",
-    ".claude/skills/ask-colleague/prompts/write.md",
-]
-bump_level = "patch"
-changelog_text = """\
-### Changed
-
-- **Re-vendored the `ask-colleague` skill wrapper from colleague#183**
-  (`.claude/skills/ask-colleague/scripts/ask-colleague.sh`): `resolve_colleague()`
-  now honors `--repo` for the `uv` local-dev fallback, the `colleague drive`
-  tri-state exit code (0/1/2) propagates end-to-end instead of collapsing to 1,
-  and a non-preserved read-only run no longer prints a dead `artifact:` line into
-  a throwaway worktree. Wrapper-only — an existing `SKILL.md` and prompt
-  templates are left untouched (they carry a repo-specific provenance token and
-  may diverge). Where the skill was absent, it is added fresh (wrapper +
-  `SKILL.md` + prompts). Refs: colleague#183, #180, #181.
-"""