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

rollout_cli-0.3.0/.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
+    }
+  ]
+}