rollout-cli 0.2.1__tar.gz → 0.3.1__tar.gz

{rollout_cli-0.2.1 → rollout_cli-0.3.1}/.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.1/.devague/frames/rollout-cli-ships-rollout-define-an-org-wide-chang.json

@@ -0,0 +1,302 @@
+{
+  "slug": "rollout-cli-ships-rollout-define-an-org-wide-chang",
+  "title": "rollout-cli ships 'rollout': define an org-wide change once as a deterministic recipe, and it propagates across every target agent repo \u2014 branch, apply via scripts (not an agent hand-editing files), bump version, commit, push, and open one PR per repo with CI running, ready for a human squash-merge. The first recipe, apache-relicense, carries the exact MIT->Apache-2.0 change shape from rollout-cli's own #1 across the mesh.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-06-06T14:17:27Z",
+  "updated": "2026-06-06T14:30:37Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "rollout-cli ships 'rollout': define an org-wide change once as a deterministic recipe, and it propagates across every target agent repo \u2014 branch, apply via scripts (not an agent hand-editing files), bump version, commit, push, and open one PR per repo with CI running, ready for a human squash-merge. The first recipe, apache-relicense, carries the exact MIT->Apache-2.0 change shape from rollout-cli's own #1 across the mesh.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "The first recipe, apache-relicense, run across the confirmed target set, produces one PR per repo whose diff matches d27519f's shape, with CI running and no repo merged automatically.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "The org maintainer (Ori) who decides what change to roll out and does the squash-merges, plus the rollout-cli agent that authors/validates the recipe once and drives the per-repo loop.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "The two roles are real and distinct: the maintainer makes the go/no-go and does the squash-merges; the agent authors the recipe once and runs the deterministic loop \u2014 neither hand-edits files per repo.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "One declarative recipe is applied across an explicit set of target repos, producing one branch + one PR per repo, each with the same reviewable diff shape, CI running, awaiting human squash-merge. Deterministic scripts make the edits; the agent never hand-edits files across repos.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "After a run, each clean target has exactly one new branch and one open PR with the same diff shape, and no target's working files were edited by an agent.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "An org-wide change (e.g. relicensing) means either manually editing each of ~40 repos or having an agent open each repo and hand-edit files \u2014 slow, inconsistent, unreviewable, and error-prone.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h11",
+          "text": "Today there is no single command that applies one change across the org; doing it means N manual or agent-driven edits.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "A deterministic recipe is reviewable once, repeatable, idempotent, and auditable; the agent orchestrates rather than touching every file, so a 40-repo change is as trustworthy as a 1-repo change.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h12",
+          "text": "Because the change is a reviewed-once deterministic recipe, a 40-repo run produces diffs a human can audit identically to a 1-repo run.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "rollout-cli does NOT merge (human squash-merges), does not invent semantic refactors (deterministic recipes/refactor-cli actions only), is not a CI system (it relies on each repo's existing CI), and does not own the target repos' release policy beyond what the recipe declares.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h13",
+          "text": "rollout never merges a PR and never performs an edit not declared by a recipe; CI is each target repo's own.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "Running 'rollout apply apache-relicense --targets <set>' yields one branch+PR per target whose diff matches d27519f's shape (LICENSE, pyproject license+classifier, README license line, CHANGELOG entry, version bump), with CI triggered, and a single summary table of PR URLs + statuses.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h14",
+          "text": "The apache-relicense run emits a summary table of one PR URL per target, and each PR's diff equals d27519f's shape.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "A 'recipe' is the unit of change: a self-contained, version-controlled directory (deterministic apply script + manifest declaring touched files, version-bump level, and CHANGELOG text). Authored/reviewed ONCE; the same recipe runs unchanged against every target.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "A recipe applies with zero recipe-specific args beyond the target path; the apache-relicense recipe reproduces d27519f's diff shape exactly on a clean MIT repo.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "The per-repo loop is pure orchestration: locate/refresh repo -> create branch -> run recipe's apply script -> bump version + prepend CHANGELOG -> commit -> push -> open PR via devex. No LLM file edits in the loop.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "The apply loop contains no agent/LLM file-editing step \u2014 every file mutation originates in the recipe script or the deterministic version/CHANGELOG bumper.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "Targets are explicit and declared (a repo-list / filter over the org), never implicit. The set is shown and confirmed before any push.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "No branch/push/PR happens until the resolved target list has been printed and confirmed by the maintainer.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "requirement",
+      "text": "Two-phase execution: 'rollout plan' is a dry-run that produces per-repo diffs locally and a preflight report (applies cleanly? already done? conflicts?) with zero side effects; 'rollout apply' performs branch/commit/push/PR only on repos the plan marked clean.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "'rollout plan' creates no branches and writes to no remote; 'rollout apply' only acts on repos the plan marked clean.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "requirement",
+      "text": "Idempotent + resumable: a recipe re-run on an already-changed repo is a no-op (detects done-state, skips); a partial run can be resumed; each repo's outcome is independent (one failure does not abort the batch).",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "Re-running apply on a repo whose change already landed makes no new commit and opens no duplicate PR (done-state detected).",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "requirement",
+      "text": "Recipes that don't apply cleanly to a repo are surfaced as a per-repo 'needs attention' item (skipped, reported), NOT silently force-edited \u2014 that is the one place a human/agent steps in.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "A repo whose recipe preconditions fail is reported as needs-attention and skipped, never force-applied.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "decision",
+      "text": "Layering: refactor-cli owns the in-repo deterministic edit primitives (the apply script calls them); rollout-cli owns cross-repo orchestration (targets, branch, PR via devex, reporting). devex provides the PR lane; agtag/communicate the issue I/O.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c15",
+      "kind": "decision",
+      "text": "Local-checkout model: each target repo lives as a sibling checkout under /home/spark/git; rollout operates on these working copies and leaves each on its new branch (matching the user's 'each local repo will be on that new branch').",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c16",
+      "kind": "assumption",
+      "text": "Every target repo follows the shared agent baseline (pyproject + CHANGELOG + version-check CI + devex PR lane), so one recipe's file-shape assumptions hold across the set.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c17",
+      "kind": "requirement",
+      "text": "Branching is always cut from a freshly-fetched default branch (origin/main); a repo with a dirty working tree or unpushed local commits on the wrong branch is aborted and reported, never branched over or clobbered.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "On a repo with a dirty tree or local-only commits, 'rollout apply' aborts that one repo with a clear report and makes no branch/commit/push; clean repos in the same batch still proceed.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c18",
+      "kind": "decision",
+      "text": "Target resolution is a CLI input: an org/user plus a selector (all | explicit repo list), e.g. 'rollout apply <recipe> --org agentculture --all' or '--repos a,b,c'. agentculture-owned (excluding upstream forks) is the documented default. The resolved set is always printed for confirmation before any apply.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c19",
+      "kind": "decision",
+      "text": "A run stops at 'PR opened' and prints a summary table (repo, PR URL, status); the maintainer watches CI and squash-merges. A poll-CI summary mode is a deferred follow-up, not v1.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c20",
+      "kind": "decision",
+      "text": "The needs-attention seam delegates genuine agent work to the ask-colleague skill (a different backend, isolated git worktree, read-only by default) \u2014 the orchestrator never hand-edits files in place, preserving 'scripts, not an agent editing files all over'.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "How a recipe's preflight detects target repos that drift from the shared baseline (missing CHANGELOG, different pyproject license-field format) and routes them to needs-attention.",
+      "kind": "unknown_nonblocking",
+      "claim_id": null
+    }
+  ]
+}