v1.12.1 to v2.0.0

- Interactive letterbox release gatekeeper — runs one tick, prompts to push/defer/cancel

- ready services, auto-files beads on CI failure, enforces deploy order,

- watches rollouts and restarts. Only pushes on explicit choice; loop with /watch-release.

- 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:*)"

- version: "1.12.1"

- 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 <service>`.

- ```

- /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:

-

- 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:

- "deferred": { "dispatch": { "untilEpochTick": false } },

- "cancelled": { "web": { "sha": "<short sha when cancelled>" } },

- "ciBeads": { "account@master": "letterbox-xyz" },

- "rolloutWatch": { "dispatch": { "sha": "<pushed sha>", "fromTag": "<live tag at push time>" } },

- "configApply": { "letterbox-app-config": { "baseline": "<resourceVersion at sync time>", "consumers": ["web"], "syncedSha": "<k8s repo sha>" } },

- "restartPending": { "web": { "config": "letterbox-app-config", "appliedRV": "<resourceVersion when Flux applied>" } },

- "restartWatch": { "web": { "for": "letterbox-app-config", "ageBaseline": "<pod age at restart>" } },

- "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: `<service>@<ref>` for red CI

- runs; `coverage:<provider>` 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 <service> --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=<kubectl ctx>`, `ciProvider=<circleci|github-actions|cloud-build|none>`,

- and `ci=<available|partial|unavailable>`. 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 `<ready>/<desired>` (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=<true|false>`, 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):

- ./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 `<service>@<ref>`. 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: <service>` title. If none, file one:

- ```bash

- bd create --title="CI FAILED: <service>" --type=bug --priority=1 --labels "<service>" \

- --description="CI run failed on <ref> at <ciRevision>. Detected by /release-manager."

- ```

- - Record `state.ciBeads["<service>@<ref>"] = <new bead id>`. Print `🔴 CI FAILED <service> → filed <bead id>`.

- - 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 <service> <tag>` (was `<fromTag>`) 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 <service> <tag>` (was `<fromTag>`) 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 <service> (no baseline)`.

- - Otherwise (live tag still equals `fromTag`, or not yet ready/settled) leave it — optionally

- note `…rolling out <service>`.

-

- 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 <name>`. If

- `consumers` is `["?"]` (derivation failed at sync time), don't guess: print

- `⚠️ <name> applied — consumers underivable, restart manually if a service reads it` and just

- remove the entry. Otherwise, for each `consumer`, queue a restart —

- `state.restartPending[<consumer>] = { config: <name>, appliedRV: <new resourceVersion> }` —

- **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 `…<consumer> deploying —

- picks up <name> without a restart`.

- Then remove the `configApply` entry. If `resourceVersion` is still `baseline` (or `-`/notfound),

- leave it — note `…config applying <name>`. (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 <service> (config <for>)` and remove. Otherwise leave it — note

- `…restarting <service>`. (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 <flag> — <flip_when>`. (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 <flag> — 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

- (`<flag> parked — superseded by <x>; reconsider_if <y>`).

-

- 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> unpushed, <uncommitted?>, <behind> behind on <branch>; 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[<name>] = { baseline: <its resourceVersion from THIS tick's ---CONFIG--->,

- consumers: <its restart column, split on commas>, syncedSha: <the `head` from this tick's

- ---K8S--- — pre-sync, fine for this audit-only field> }`. 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 <name> → <consumers>`.

- - `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 <service>` 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<M),

- or a CronJob service showing `cron:rollout` (its CronJobs not yet on one tag) — or (c) P is in

- `state.rolloutWatch` (pushed but rollout not yet confirmed). If any prereq blocks, mark

- `WAITING ON <prereq>` 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 `⚠️ <svc> 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:<provider>`. If not already in

- `state.ciBeads` and no open bead titled `CONTRACT COVERAGE: <provider>` exists

- (`bd list --status=open`), file one:

- ```bash

- bd create --title="CONTRACT COVERAGE: <provider>" --type=bug --priority=2 --labels "<provider>" \

- --description="<provider> CI does not verify all consumer contracts (not-verified=<…>). Detected by /release-manager via ./scripts/contract-check coverage."

- ```

- Record `state.ciBeads["coverage:<provider>"] = <id>`; 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 <repo> 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 <service>`; print `⬆️ pushed <service>`. On success, **for a

- deploying service** add it to `state.rolloutWatch` as `{ sha: <the service's `head` from the

- step-1 digest>, fromTag: <the service's current live deploy tag from the step-1 digest> }`. `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 <service> --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 `…<service> 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/<service> to load applied config <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/<service> -n apps`; print

- `🔄 restarted <service>`. On success move it from `restartPending` to

- `state.restartWatch[<service>] = { for: <config>, ageBaseline: <the service's current pod age

- from this tick's ---SERVICES--->`. 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 <service>`, 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.