--- name: release-manager description: > Interactive release gatekeeper for letterbox — runs one tick of the release dashboard, then prompts to push / defer / cancel each ready service, auto-files a bead on CI failure, enforces deploy order, watches rollouts, syncs k8s config and schedules the restarts that applied config needs, and nudges feature toggles. Drive it on a loop with /watch-release. Advisory: it only pushes after you explicitly choose "push". allowed-tools: "Read,Write,Skill,AskUserQuestion,Bash(./scripts/release-digest:*),Bash(make feature-toggles-disabled:*),Bash(make git-push:*),Bash(make k8s-sync:*),Bash(kubectl rollout restart:*),Bash(./scripts/mgit log:*),Bash(./scripts/release-order:*),Bash(./scripts/release-ci:*),Bash(./scripts/contract-check:*),Bash(bd create:*),Bash(bd list:*)" model-tier: standard model: sonnet effort: medium version: "1.12.0" author: "flurdy" --- # Release Manager The interactive gatekeeper. One invocation = one **tick**: gather release state, evaluate gates, take care of CI failures, and prompt you for a decision on anything that's ready to ship. Designed to run on a loop in a dedicated tab via `/watch-release`. It is **advisory and explicit**: nothing gets pushed unless you choose `push` at the prompt (honors the project rule "never auto-push, always ask"). The one thing it does autonomously is **file a bead when CI is red** — deduplicated, so it never double-files. ## When to Use - Driven by `/watch-release` (adaptive cadence — step 8b's `next-tick:` line paces the loop) in a kitty tab during parallel work. - Ad-hoc, when you want to be walked through what's ready to push/release right now. For a passive look with no prompts, use `/release-status`. For a deep gate on a single service, use `/ready-to-release `. ## Usage ``` /release-manager # one tick across all services /release-manager dispatch # one tick scoped to a service ``` ## Setup This skill ships two project-facing authorities: - `release-order` resolves the effective deploy-order graph for /release-manager, /release-status, and /ready-to-release. - `release-ci` resolves read-only CI evidence for the exact upstream revision of each requested service. It has built-in adapters for CircleCI, GitHub Actions, Google Cloud Build, and `none`. On first run, ensure both project commands resolve to the installed skill: ```bash ln -sfn "$SKILLS_DIR/release-manager/scripts/release-order" ./scripts/release-order ln -sfn "$SKILLS_DIR/release-manager/scripts/release-ci" ./scripts/release-ci chmod +x ./scripts/release-order ./scripts/release-ci ``` Where `$SKILLS_DIR` resolves to the installed shared skill root. Both authorities find a multi-repo root from `RELEASE_PROJECT_ROOT`, `.mgit.conf`, a release manifest, or a Git root. `release-order` selects the pact provider when live pact edges or a generated pact block exist, uses `order.manual` for a plain manifest-declared graph, and returns an empty graph when neither source exists. An accepted generated block remains effective until you explicitly reconcile provider drift. Manual edges and suppressions use the same flow-list map shape. `release-ci` selects exactly one project provider from `docs/release-manifest.yaml`. Provider settings live under the same declaration; repository identity, upstream ref, and expected revision come from each verified checkout rather than hardcoded repository prefixes: ```yaml ci: provider: circleci # circleci | github-actions | cloud-build | none circleci: token_env: CIRCLECI_TOKEN token_account: example-account # optional secret-api-key fallback cloud-build: project: example-project region: global order: manual: web: [api] suppress: web: [legacy] ``` The CI authority emits `---SOURCE---` metadata (`provider`, `availability=available|partial|unavailable`, and manifest presence), then bounded `---CI---` rows: ```text service|status|ref|revision|expectedRevision|url|reason ``` `status` is `success|failed|running|error|unknown`. A successful native result is reported as `success` only when its provider revision exactly equals the checkout's upstream revision. Missing configuration, credentials, checkout, upstream, provider command, malformed response, timeout, or revision mismatch produces explicit unknown/unavailable evidence and never triggers or retries CI. `docs/release-manifest.yaml` and `.release-state.json` stay project-local. ## State file Per-item decisions persist in `.release-state.json` at the repo root (gitignored) so the watcher doesn't re-nag every tick. Create it if missing. Schema: ```json { "deferred": { "dispatch": { "untilEpochTick": false } }, "cancelled": { "web": { "sha": "" } }, "ciBeads": { "account@master": "letterbox-xyz" }, "rolloutWatch": { "dispatch": { "sha": "", "fromTag": "" } }, "configApply": { "letterbox-app-config": { "baseline": "", "consumers": ["web"], "syncedSha": "" } }, "restartPending": { "web": { "config": "letterbox-app-config", "appliedRV": "" } }, "restartWatch": { "web": { "for": "letterbox-app-config", "ageBaseline": "" } }, "quietStreak": 0 } ``` - `deferred` — snoozed this session; cleared and re-prompted on the next tick (defer = "ask me again later"). - `cancelled` — suppressed until the service's unpushed HEAD sha changes (new commits arrive). - `ciBeads` — dedup map of auto-filed beads → bead id. Keys: `@` for red CI runs; `coverage:` for contract-coverage gaps. Drop a key when its problem clears. - `quietStreak` — count of consecutive **cold** ticks (nothing in flight, nothing queued). Drives the adaptive back-off in step 8: reset to 0 on any hot/warm tick, incremented on a cold one. Ignored entirely under a fixed-interval loop. - `rolloutWatch` — services pushed in a prior tick, awaiting their new tag in K8s. `fromTag` is the live deploy tag captured **at push time** (the pre-push baseline). The exact post-push tag cannot be predicted because the build system assigns it only after the push. Confirmation (step 4) is therefore "the live tag has moved **off** `fromTag`", not an exact-tag match. `fromTag` may be `null` if deploy-status was unavailable at push — step 4 then falls back to the older heuristic. - `configApply` / `restartPending` / `restartWatch` — the **config-restart state machine**. Every service reads its ConfigMaps/Secrets only at startup, so a synced config change does NOT take effect until its consumers get a `kubectl rollout restart` — and only *after* Flux has applied it (restarting sooner just reloads the old config). The consumer set is **derived, never curated**: the digest's `---CONFIG---` `restart` column (deployment yamls for who mounts the map; per-key source grep to narrow shared maps), minus `manifest.config_restarts.suppress`. Three states, each a separate tick, mirroring `rolloutWatch`'s push→confirm pattern: - `configApply` — config synced via `make k8s-sync` (step 5b) and awaiting Flux. `baseline` is the resource's live `resourceVersion` captured **at sync time** (the pre-apply baseline, exactly like `fromTag`); step 4b confirms apply when it moves **off** `baseline`. `consumers` = the derived restart set frozen at sync time (`["?"]` if underivable); `syncedSha` = the k8s repo sha that shipped it. - `restartPending` — Flux applied the config (step 4b saw `resourceVersion` move); the listed services now await a restart decision. Survives a `defer` so it re-prompts next tick. `appliedRV` is the resourceVersion observed at apply (audit/debug only). - `restartWatch` — restart issued (step 7b ran `kubectl rollout restart`); awaiting pod cycle. `ageBaseline` is the pod age at restart time — step 4b confirms when pods show fresh + ready. ## Command discipline Every Bash call in a tick must match `allowed-tools` **as written** — a plain invocation of one listed script/command. Never wrap them in `for` loops, variable expansion, command substitution, or pipes (`| head`, `| grep`): the composed command can't match `Bash(./scripts/mgit log:*)`, so it stalls the whole watcher loop on a permission prompt until a human answers. If you want the same fact for several services, that's a sign it belongs in the digest — and the per-service basics (`unpushed`, `head`, …) already do: read the columns, don't shell out. The one sanctioned drill-down is the step-7 `why?` flow — run `./scripts/mgit log --oneline @{u}..HEAD` as one plain call per service (parallel calls are fine; loops are not). ## Per-tick flow 1. **Gather.** Run the shared mechanical digest — it keeps raw kubectl, CI-provider, and Git output out of this loop's context by emitting only a compact parsed result, so no subagent is needed: ```bash ./scripts/release-digest # all services (or pass a service arg to scope the tick) ``` Parse the delimited sections: - `---META---`: `context=`, `ciProvider=`, and `ci=`. Missing or degraded provider evidence leaves affected service `ci` fields `unknown`. - `---SERVICES---`: one pipe-delimited line per service after the header line: `service|unpushed|uncommitted|ci|ciBranch|gitBranch|head|deploy|tag|age|ciRevision|ciExpectedRevision`. - `unpushed` (int), `uncommitted` (`true|false`), `head` = short sha of the current local HEAD (`-` if no checkout) — the tip identity for every sha comparison/record this tick (step 6 `cancelled` check, step 7 `rolloutWatch.sha`); never run per-service git commands to re-derive it. - `ci` ∈ `success|failed|running|error|unknown`; `ciBranch` and `ciRevision` identify the provider run, while `ciExpectedRevision` is the exact upstream revision that the authority gated. `gitBranch` is the service checkout's current branch (what `git push` sends). The original columns retain their order; revision evidence is appended for existing consumers. - `deploy` = a Deployment's `/` (e.g. `1/1`, `0/1`); for **CronJob-backed services** (digest, patrol, reconciler) it is a marker, not replicas: `cron` = the service's CronJobs all share one image (settled) and `cron:rollout` = images differ (Flux mid-bump). Also `notfound`/`unknown`. `tag` = live image tag, `age` = pod age (Deployment) or most-recent run age (CronJob). Treat tag-movement (not ready replicas) as the rollout signal for CronJob services in steps 4 and 6. - `---TOGGLES---`: `FLAG=value` lines — **compact by default**: only false-valued flags and those referenced in the manifest's `toggles:`/`parked:` sections (so an already-flipped dark-release flag still shows its live value). A trailing `# compact: …` line notes how many were hidden. This is exactly what steps 5/5b need. For the complete map (all true flags + membership tiers), run `./scripts/release-digest --full-toggles`; for the disabled-only view, `make feature-toggles-disabled`. - `---K8S---`: state of the `kubernetes` GitOps repo (which ships via `make k8s-sync`, not as a `---SERVICES---` entry): `present=`, then when present `branch`, `head` (short sha), `unpushed` (int), `uncommitted` (bool), `behind` (int, from the last-known remote ref — may be stale). Consumed by step 5b. - `---CONFIG---`: one pipe-delimited line per ConfigMap/Secret referenced by a Deployment in the `kubernetes` GitOps repo, after the header: `name|kind|resourceVersion|changed|mounts|restart`. All **derived** by the digest (deployment yamls for who-mounts-what; per-key source grep for shared maps) — nothing curated. `kind` ∈ `configmap|secret|notfound`; `resourceVersion` is the live value (or `-`) — the apply baseline steps 5b/4b watch; `changed` (`true|false`) means a file defining this resource is in the repo's unpushed diff, i.e. `make k8s-sync` ships it **this** tick; `mounts` = comma-list of Deployment services mounting it (CronJob services never appear — no restart needed); `restart` = the derived restart set for this change: `-` (not changed), a comma-list of services, or `?` (changed but underivable — warn, don't guess). Consumed by steps 5b (register) and 4b (confirm apply). 1b. **Scan dependencies + contract coverage** (cheap, no subagent needed — compact output): ```bash ./scripts/release-order # effective deploy-order authority ./scripts/contract-check coverage # CI verification coverage ``` If `./scripts/release-order` is missing, create the symlink first (see Setup). From `release-order`: `---SOURCE---` (`provider=pact|manifest|none` and `graph=generated|live|manual|none`), `---GRAPH---` (the accepted effective `consumer: [providers]` map), and `---DRIFT---`. From `contract-check coverage`: per-provider `GAP`/`OK` lines. Keep these for steps 2b, 6, 6b. (`release-order` = ordering; `contract-check` = contract health.) 2. **Load context.** Read `.release-state.json` (create `{}`-shaped default if absent). If `docs/release-manifest.yaml` is absent, use empty defaults for `toggles`, `parked`, `ignore`, `non_deploying`, and `config_restarts.suppress`; ordering still comes from `release-order`. Otherwise read those sections from the manifest. Use `---GRAPH---` as the effective dependency map; do not rebuild or reinterpret ordering in the skill. 2b. **Dependency drift reconcile.** Only `new:` or `removed:` lines in `---DRIFT---` are reconcilable pact drift. Print those edges, then prompt once (AskUserQuestion): *"Reconcile dependency map into the manifest?"* — `reconcile` / `skip`. - `reconcile` → `./scripts/release-order --write` (rewrites the generated provider block), then note any **new** edges so you can decide whether any belong in `order.suppress` (backward-compatible, shouldn't gate). Re-run `release-order` after writing. - `skip` → leave it; drift resurfaces next tick. - `in-sync`, `unmanaged`, and `not-applicable` statuses never prompt. `unmanaged` means the live pact graph remains usable but has no generated manifest block to reconcile. 3. **CI failures → auto-bead (dedup).** For each service whose `ci` is `failed`/`error`: - Compute key `@`. If it's already in `state.ciBeads`, skip (already filed). - Otherwise verify no open bead exists: `bd list --status=open` and grep for a matching `CI FAILED: ` title. If none, file one: ```bash bd create --title="CI FAILED: " --type=bug --priority=1 --labels "" \ --description="CI run failed on at . Detected by /release-manager." ``` - Record `state.ciBeads["@"] = `. Print `🔴 CI FAILED → filed `. - When that service's CI later goes green, drop the key from `ciBeads` so a future failure re-files. 4. **Rollout confirmation.** For each entry in `state.rolloutWatch`, compare the live deploy `tag` against the recorded `fromTag` baseline (the tag that was live when you pushed). Rollout is confirmed when the live tag has **moved off** `fromTag` — Flux has applied the new image: - **Deployment service:** confirmed when the live `tag` differs from `fromTag` **and** it's `ready` (e.g. `1/1`). Print `✅ ROLLED OUT ` (was ``) and remove it. - **CronJob service** (`deploy` is `cron`/`cron:rollout`): no ready replicas — confirmed when the live `tag` differs from `fromTag` **and** the marker is `cron` (settled, not `cron:rollout`). Print `✅ ROLLED OUT ` (was ``) and remove it. - **`fromTag` is `null`** (deploy-status was unavailable at push): fall back to the older heuristic — tag looks advanced from what you'd expect **and** the pod/last-run age is fresh (recent). Less precise; note `…rolling out (no baseline)`. - Otherwise (live tag still equals `fromTag`, or not yet ready/settled) leave it — optionally note `…rolling out `. 4b. **Config-apply & restart confirmation.** Two follow-on confirmations for the config-restart machine (both read this tick's `---CONFIG---` and `---SERVICES---`): - **`configApply` → `restartPending` (Flux applied the config).** For each `state.configApply` entry, look up the resource's current `resourceVersion` in `---CONFIG---`. If it has **moved off** `baseline`, Flux has applied the synced change. Print `✅ CONFIG APPLIED `. If `consumers` is `["?"]` (derivation failed at sync time), don't guess: print `⚠️ applied — consumers underivable, restart manually if a service reads it` and just remove the entry. Otherwise, for each `consumer`, queue a restart — `state.restartPending[] = { config: , appliedRV: }` — **unless** that consumer's new pods will already pick the config up on their own, in which case skip it (no restart needed): - consumer is in `state.rolloutWatch`, or has `unpushed > 0`, or shows `deploy` mid-rollout — it's deploying anyway; its fresh pods read the applied config. Note `… deploying — picks up without a restart`. Then remove the `configApply` entry. If `resourceVersion` is still `baseline` (or `-`/notfound), leave it — note `…config applying `. (Over-registration is harmless: a config that didn't actually change never moves off `baseline`, so it just sits until you sync something — prune stale entries if a `syncedSha` is long gone.) - **`restartWatch` → done (pods cycled).** For each `state.restartWatch` entry, the restart is confirmed when the service shows `deploy` ready (e.g. `1/1`) with a **freshly-aged** pod (the `age` in `---SERVICES---` is younger than `ageBaseline` — pods were replaced). A config restart does **not** move the image `tag`, so age-reset + ready is the signal (not tag movement like step 4). Print `✅ RESTARTED (config )` and remove. Otherwise leave it — note `…restarting `. (Heuristic, like step 4's `fromTag: null` fallback: if age is ambiguous, prefer leaving it one more tick over a false confirm.) 5. **Toggle readiness.** For each `manifest.toggles` entry: if its `service` is rolled out (a Deployment showing `deploy ready`, or a CronJob service showing the settled `cron` marker) AND the live flag value is still `false`, print `🚩 TOGGLE READY — `. (Informational; flipping happens via the K8s repo, not here.) Also flag toggles that are referenced in code/manifest but missing from prod if you spot them. Exceptions: - A toggle with `status: dark-release` is in a deliberate shadow launch — print `🌓 DARK RELEASE — flip is a manual call once validated`, do NOT nudge it as ready. - **Skip `manifest.parked` flags entirely** — they are deliberately off (e.g. superseded by another path); never nudge them. At most show once as a footnote (` parked — superseded by ; reconsider_if `). 5b. **K8s config sync watch.** The `kubernetes` GitOps repo ships via `make k8s-sync` (pull `--rebase` + push → Flux applies to the cluster), **never** `make git-push` — so it's in `manifest.ignore` and is *not* a step-6 push candidate. But committed-but-unsynced config there is a frequent **prerequisite** for a service deploy: ship the service while its ConfigMap / Secret / manifest change is still local and the release breaks. So the gatekeeper watches its state even though it never `git-push`es it. Read the digest's `---K8S---` section: `present`, and (when present) `unpushed`, `uncommitted`, `behind`. If `present=false`, skip silently. If `unpushed=0` **and** `uncommitted=false` **and** `behind=0`, the repo is in sync — skip silently. Otherwise it has **pending config**. Surface it prominently (this is high-signal — it gates real deploys): ``` ⚠️ KUBERNETES UNSYNCED — unpushed, , behind on ; run `make k8s-sync` ``` Then prompt **once** (AskUserQuestion), *before* the step-7 service-push prompts so config lands first: *"Sync the kubernetes config now?"* - `sync` → run `make k8s-sync`. On success print `✅ k8s-synced`; the change is now en route to the cluster via Flux. On failure (rebase conflict, push rejected — `make k8s-sync` does `pull --rebase` then push), surface stderr verbatim and **do not retry** — a conflict is a human call. `make k8s-sync` never edits the repo or force-pushes. **Then register restart watches:** for each `---CONFIG---` line with `changed=true` (it was part of the commits just synced), unless the name is in `manifest.config_restarts.suppress`, record `state.configApply[] = { baseline: , consumers: , syncedSha: }`. The `resourceVersion` read *now* (before Flux applies) is the pre-apply baseline step 4b watches to move off — exactly like `fromTag` at push. A `restart` of `?` still registers (with consumers `["?"]`) so the apply gets confirmed — step 4b then warns instead of queuing restarts. Print `🔁 watching restart for → `. - `skip` → leave it. It resurfaces next tick (no state recorded — git is the source of truth), and step 7 carries the caution into any push prompt below. `uncommitted=true` means there are **uncommitted** edits in the k8s repo — `make k8s-sync` won't ship those (only committed commits push). Note that explicitly: `…uncommitted edits won't sync until committed`. Carry an `k8sUnsynced` boolean (true when pending config exists and wasn't just synced) into step 7 and the step-8b cadence. 6. **Evaluate ready-to-push.** Build the candidate set: anything with `unpushed > 0`, excluding `manifest.ignore`, excluding `cancelled` whose stored sha still matches the digest's `head` column (a moved `head` means new commits landed — the cancel expires; this is a pure data comparison, no git commands). Then **partition** it: - **Non-deploying repos** (in `manifest.non_deploying`, e.g. root, functional-tests) do not have a deployment pipeline or rollout to gate. **Skip every gate below** (CI/ref/revision, deploy-order, contract staleness/coverage) — none of their assumptions apply. Mark each `📦 READY (non-deploying)` and carry it straight to step 7 with the non-deploying label. Do **not** treat their `ci=unknown` as a stop; `unknown` there is expected, not a risk. - **Deploying services** (everything else) run the full gate sequence below. For each: - **Pre-push verification gate (safety-critical — evaluate FIRST, before any other gate).** `make git-push ` pushes the unpushed commits straight to the service's remote, whose configured pipeline may deploy to **production** on green. There is no further human gate after the push, so a service is only a push candidate when its current upstream revision is known-good. Two facts matter: 1. The normalized CI row describes the exact **upstream** revision already on the remote. It cannot describe the candidate commits because those commits are still unpushed and no remote provider has seen them. 2. Therefore exact upstream CI success is necessary-but-not-sufficient, while failed, running, unavailable, stale, malformed, or mismatched evidence is a hard stop. Apply, in order, and **drop from the prompt set** (print the line, don't ask) on any stop: - **Ref and revision match.** Require `ciBranch == gitBranch`, and require non-`-` `ciRevision == ciExpectedRevision`. Any missing or mismatched value means the evidence is for another ref/revision; treat it as `unknown` below even if its native status was green. - `ci` = `failed`/`error` → mark `🔴 CI RED — not offering push` and drop. The exact upstream tip is broken; pushing risks a bad production deploy. (Step 3 already filed the bead.) - `ci` = `running` → mark `⏳ CI RUNNING — wait` and drop this tick. The exact upstream tip is unsettled; it resurfaces next tick. - `ci` = `unknown`, or any ref/revision mismatch above → mark `❔ CI UNKNOWN — not offering push` and drop. Local tests do not replace missing remote evidence for the exact upstream revision; the service resurfaces when the authority can prove it. - `ci` = `success` with matching ref and exact revision → the upstream tip is green. Keep it, but the candidate is **still remotely unverified** because its unpushed commits have not run remotely. Carry this caveat into the step-7 prompt. - **Deploy order (the rate limiter).** Look up the service's prereqs in the effective dependency map. A prereq P **blocks** this consumer only if P is *co-changing* — any of: (a) P has `unpushed > 0`, (b) P is mid-rollout — a Deployment showing `deploy` `N/M` (N` and drop from the prompt set (print the line, don't ask). A stable, already-live prereq does NOT block — its contract is already satisfied. > This is what paces releases: pushing a provider this tick auto-defers its consumers to > a later tick, because the consumer can't clear this gate until the provider leaves > `rolloutWatch` (step 4 confirms its rollout). The dependency graph IS the rate limit. - **Contract staleness.** If the service touches connectors/contracts, run `Skill /contract-check status` (NOT a normalize/`--check` proxy — that only checks file formatting, not verification). If pacts are out of sync, mark `CONTRACTS STALE` and warn (don't offer push until resolved). - **Contract coverage.** Cross-reference step 1b's `contract-check coverage` output: if the service is a provider with a `GAP` line, warn `⚠️ contract coverage gap (not-verified=<…>)` — its change may not be verified against all consumers. Don't hard-block, but make it loud in the prompt. - Otherwise it's **READY**. 6b. **Contract coverage beads (dedup).** For each `contract-check coverage` `GAP` line, treat it like a CI failure for tracking: key `coverage:`. If not already in `state.ciBeads` and no open bead titled `CONTRACT COVERAGE: ` exists (`bd list --status=open`), file one: ```bash bd create --title="CONTRACT COVERAGE: " --type=bug --priority=2 --labels "" \ --description=" CI does not verify all consumer contracts (not-verified=<…>). Detected by /release-manager via ./scripts/contract-check coverage." ``` Record `state.ciBeads["coverage:"] = `; drop it when the gap later clears. 7. **Prompt per READY service, capped at 3 this tick.** Order candidates **providers/leaves first** — a service that others depend on (appears as a provider in the effective map) before its consumers — so the safe-to-ship-first work surfaces first; sort any **non-deploying repos last** (they carry no deploy risk). Take the first 3; if more remain, print `… N more ready — re-run /release-manager for the rest`. Prompt each (AskUserQuestion, one question per item, options `push` / `defer` / `cancel` / `why?`). Each question must state the push consequence plainly, and the wording depends on the kind: - **Deploying service:** *"push deploys N unpushed commit(s) to prod on CI-green; remote CI has not verified these commits (its green is for the last pushed SHA)."* - **Non-deploying repo:** *"push sends N unpushed commit(s) to the remote — no CI gate, no prod deploy, no rollout to watch."* - **When `k8sUnsynced` (step 5b) and the candidate is a deploying service:** append a caution to the push consequence — *"⚠️ kubernetes has unsynced config (`make k8s-sync` not yet run) — if this deploy depends on it, sync first or the release may break."* This is a caution, **not a hard block** — the skill can't know whether *this* service needs *that* config, so it surfaces the risk and leaves the call to you. (A hard prerequisite belongs in the manifest's `order`, not here.) - `push` → `make git-push `; print `⬆️ pushed `. On success, **for a deploying service** add it to `state.rolloutWatch` as `{ sha: , fromTag: }`. `fromTag` is the pre-push baseline step 4 watches to move off (the exact post-push tag isn't knowable at push — see the State file note); use `null` only if deploy-status had no tag for the service. A **non-deploying repo** is NOT added to `rolloutWatch` (there is no rollout) — it just disappears from the candidate set once pushed. - `defer` → add to `state.deferred`; it'll resurface next tick. - `cancel` → add to `state.cancelled` with current HEAD short sha; stays quiet until new commits. - `why?` → show `./scripts/mgit log --oneline @{u}..HEAD` (the unpushed commits) plus the gate reasoning (CI/contract/coverage/order), then re-ask the same question for that service. 7b. **Restart prompt per `restartPending` service.** These are services whose startup config Flux applied (step 4b queued them); they need a `kubectl rollout restart` to read the new values. For each `state.restartPending` entry: - **Re-check it's still needed first.** If the service has since deployed a new image (it left `rolloutWatch`, or its `tag` advanced this tick), its fresh pods already loaded the applied config — drop the entry silently (print `… redeployed — config picked up, no restart`) and skip the prompt. This guards the case where a normal deploy overtakes the config restart. - Otherwise prompt (AskUserQuestion, one per service, options `restart` / `defer` / `skip`). State the consequence plainly: *"restart deployment/ to load applied config — brief rolling pod cycle, **no new image**, no CI gate, no prod deploy."* CronJob-backed services never appear here (the digest derives mounts from `deployment.yaml`s only — CronJobs read fresh config each run); if one somehow does, skip it with that note. - `restart` → run `kubectl rollout restart deployment/ -n apps`; print `🔄 restarted `. On success move it from `restartPending` to `state.restartWatch[] = { for: , ageBaseline: `. Step 4b confirms the cycle (age resets + ready). - `defer` → leave it in `restartPending`; it re-prompts next tick. - `skip` → remove from `restartPending` (you've decided this service doesn't need the kick — e.g. it actually re-reads config live). It will not re-prompt unless a future sync re-queues it. This is the one prod action beyond push/sync; like them it's **confirm-gated** — never an autonomous restart. 8. **Persist & summarise.** Write the updated `.release-state.json`. Print a one-line tick summary: e.g. `tick: 2 pushed, 1 restarted, 1 config applying, 1 deferred, 1 waiting, 1 CI bead, 1 coverage gap, 1 toggle ready`. 8b. **Adaptive cadence recommendation.** Classify this tick so an adaptive watcher (`/watch-release`, default mode) can pace the next run. A fixed-interval loop ignores this line. Pick the **first** bucket that matches: - **hot** — something is *in flight or imminent*: `state.rolloutWatch` is non-empty (a push is mid-rollout — the live tag could move any tick), **or** `state.configApply` is non-empty (Flux mid-apply — `resourceVersion` could move any tick), **or** `state.restartWatch` is non-empty (pods mid-cycle), **or** a candidate's `ci=running`, **or** a service was pushed or restarted *this* tick. External events that resolve in minutes; check again soon to catch them. → **~180s** (3 min — inside the prompt-cache window, but not so tight it burns the cache several times per CI run). - **warm** — nothing in flight, but *pending work*: `state.deferred` non-empty, `state.restartPending` non-empty (config applied, awaiting your restart answer), unreconciled dependency drift (step 2b skipped), `k8sUnsynced` (step 5b — pending config not yet synced), or ready candidates still awaiting your push/defer answer, or any `unpushed > 0` not yet actioned. → **~600s** (10 min). - **cold** — fully settled: no `rolloutWatch`, no `configApply`/`restartPending`/`restartWatch`, no running CI, nothing pushed or restarted this tick, nothing deferred, nothing unpushed, no ready candidates. → escalating back-off: **1200s** first cold tick, **1500s** second, **1800s** (30 min) third and beyond. Maintain `state.quietStreak`: **cold** → increment, then `seconds = min(1800, 1200 + 300 × (quietStreak − 1))`; **hot/warm** → reset to 0. Persist it alongside the rest of the state in step 8. Print one machine-readable line **last**, after the tick summary, so the watcher can parse it: ``` next-tick: {hot|warm|cold} (~{seconds}s) — {one-clause reason} ``` e.g. `next-tick: hot (~180s) — dispatch mid-rollout` / `next-tick: cold (~1500s) — all settled, 2 quiet ticks`. The seconds are a recommendation; the adaptive loop clamps to `[60, 3600]`. Never let a hot recommendation drop below ~120s — CI runs take minutes, so tighter polling just burns the cache without catching the rollout sooner. ## Caveats - On a `/loop`, an AskUserQuestion **blocks the tick until you answer** — intended for an attended watcher tab, but an unattended tab will pause at the first prompt. If you want it to run unattended, prefer `/release-status` (no prompts) on the loop and act manually. - `push` runs `make git-push `, which may trigger a production deploy through the project's configured CI provider. The prompt is the explicit authorization; there is no auto-push. The step-6 pre-push gate withholds the prompt while exact upstream evidence is red/running/unknown or identifies another ref/revision. - **K8s config (step 5b) is watched but never `git-push`ed.** The `kubernetes` repo is in `manifest.ignore` so it's never a `make git-push` candidate — but the skill still reads its state from the digest's `---K8S---` section and, when it has unsynced config, warns and offers `make k8s-sync` (on explicit confirm — it's prod-affecting via Flux, same "always ask" rule as service pushes). It's a **caution, not a hard gate** on dependent service pushes: the skill can't know which service needs which config. A true ordering prerequisite belongs in the manifest's `order`. - **Config restarts (steps 5b→4b→7b) are spread across ticks, never bundled.** A synced ConfigMap/ Secret only restarts a startup-reading service after Flux *applies* it — restarting in the same tick as the sync would just reload the **old** config (Flux hasn't reconciled yet). So the machine runs sync (register) → confirm apply (`resourceVersion` moves off baseline) → confirm-gated `kubectl rollout restart` → confirm pod cycle, one hop per tick, mirroring `rolloutWatch`. The restart is the third prod action (after `make git-push` / `make k8s-sync`), and like them it's **confirm-gated** — never autonomous. The restart set is **derived, never curated** (the digest reads the GitOps repo's deployment yamls for who mounts each map, and narrows shared maps per changed env-var key by grepping each mounting service's source — keys are referenced verbatim, e.g. `${?FT_SES_API}`); `manifest.config_restarts.suppress` is the only human knob (veto). When derivation can't resolve a change (`restart=?`), the skill warns "restart manually" rather than guessing. CronJob-backed services are excluded by construction (mounts come from `deployment.yaml`s only — they read fresh config on their next run). Apply-confirm uses `resourceVersion` movement; restart-confirm uses pod age-reset (a config restart doesn't move the image tag), so it's heuristic — it prefers waiting a tick over a false confirm. - **Remote CI never verifies the candidate.** `release-ci` verifies the checkout's exact upstream revision, so it cannot have run the unpushed candidate commits. A green CI result describes the already-remote tip, not what you are about to push; the only verification of the candidate is local testing before push (or the post-push run after the commits land). The gate uses failed/running/error/unknown or mismatched evidence as a hard stop and surfaces "candidate remotely unverified" even when the exact upstream revision is green. - CI credentials/tooling for the selected provider and the project's Kubernetes context are needed for full data. Missing configuration, auth, commands, checkouts, upstream revisions, or provider responses degrade to `unknown` rather than failing the tick. - `.release-state.json` is gitignored and local — defer is per-session, cancel persists until new commits land on that service. - The deploy-order gate only blocks on *co-changing* providers (unpushed / mid-rollout / in `rolloutWatch`), never on stable live ones — so it paces same-tick provider+consumer pushes without permanently withholding independent work. The 3-per-tick cap is a separate backstop against prompt overload; together they keep each tick small and dependency-safe. - `./scripts/release-order` is pure-filesystem (no tokens/network) and is the only effective-map authority. Its pact provider owns the manifest's generated block; humans own `order.manual` / `order.suppress`. `--write` is only invoked via the step 2b reconcile prompt — never silently.