mustflow 2.38.0 → 2.58.0

package/templates/default/locales/en/.mustflow/skills/deployment-rollout-safety-review/SKILL.md

@@ -0,0 +1,321 @@
+---
+mustflow_doc: skill.deployment-rollout-safety-review
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: deployment-rollout-safety-review
+description: Apply this skill when server, backend, worker, scheduler, queue consumer, cron, container, VM, serverless, migration, config, feature-flag, cache, deployment pipeline, canary, rollback, release envelope, image digest, deployment history, traffic rollback, health check, readiness/liveness/startup probe, graceful shutdown, artifact promotion, release observability, or post-deploy smoke behavior is created, changed, reviewed, or reported and the risk is whether a deployment can be rolled out, stopped, observed, or rolled back safely.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.deployment-rollout-safety-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Deployment Rollout Safety Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review a server deployment as a runtime state transition, not as "the build passed".
+
+Deployment failures usually come from changed ordering, config, data, cache, queues, rollback shape,
+permissions, and observability. Rollback is not just restarting an older container. It is the older
+release surviving today's data, config, cache, queue messages, external side effects, and traffic
+state. This skill makes the agent prove that a wrong deploy has small blast radius, is detected
+quickly, can be stopped quickly, and can be rolled back without inventing a recovery plan during the
+incident.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A change touches server deployment, backend runtime behavior, workers, schedulers, cron, queue
+  consumers, containers, VMs, serverless functions, Kubernetes manifests, process managers,
+  deployment pipelines, release gates, canaries, release envelopes, or rollback procedures.
+- A change touches DB migration order, config or env vars, feature flags, cache keys, queue or topic
+  message formats, external API dependencies, storage paths, startup probes, readiness probes,
+  liveness probes, graceful shutdown, worker drain, deployment locks, or post-deploy smoke checks.
+- A review needs to decide whether code, config, database, cache, queue, and scheduler changes can
+  coexist across old and new versions while traffic is still moving.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is primarily package publication, changelog, version metadata, or remote distribution
+  channel behavior; use `release-publish-change` first.
+- The task is primarily database migration design, schema compatibility, or data backfill behavior;
+  use `database-migration-change` first, then use this skill for the deploy sequence around it.
+- The task is primarily queue correctness or retry semantics inside worker code; use
+  `queue-processing-integrity-review` or `retry-policy-integrity-review` first, then use this skill
+  for deploy-time drain and compatibility.
+- The task is only incident diagnosis after the deploy has already failed; use
+  `incident-triage-review` first and return here only when changing the rollout guardrail.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Deployment resource ledger: every affected API route, web process, worker, scheduler, cron,
+  queue consumer, queue or topic, DB table or column, cache key, object-store path, external API,
+  environment variable, secret, permission, and feature flag.
+- Artifact identity: commit SHA, image tag or digest, config version, migration version, and feature
+  flag state that operators will see in logs and dashboards.
+- Release envelope: `release_id`, image digest, chart or manifest revision, values or config hash,
+  ConfigMap or Secret version, DB migration range, feature flag snapshot, traffic weight, deployer,
+  and deployment time when those concepts exist in the target platform.
+- Deployment model: environment order, artifact promotion path, rolling/blue-green/canary strategy,
+  traffic rollback path, old-version retention, deployment history retention, deployment
+  concurrency, and deployment lock owner.
+- Compatibility model: old code with old data, old code with new data, new code with old data, new
+  code with new data, N-1 message compatibility, cache key version, and rollback survivability.
+- Runtime control model: startup/liveness/readiness probes, graceful shutdown behavior, load
+  balancer connection draining, worker drain, cron duplicate guard, kill switch, safe flag defaults,
+  automatic stop conditions, synthetic transactions, and post-deploy observation window.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The deployment or rollout surface is in scope for the current task, or the remaining deployment
+  risk is explicitly being reviewed.
+- The affected runtime resources can be identified from code, config, docs, manifests, tests, or the
+  user's report. If they cannot, report the missing resource ledger as a finding.
+- The repository command contract has been checked; live deployment, production shell, migration,
+  cloud, and cluster commands remain out of scope unless a configured intent permits them.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or update deploy runbooks, release checklists, pipeline metadata, smoke tests, probe tests,
+  config validation, feature-flag defaults, rollback notes, canary gates, and deployment safety
+  tests when they match the repository style.
+- Add local code guards for startup config validation, readiness separation, shutdown handling,
+  worker drain, cache-key versioning, and deployment attribution when the task scope includes the
+  affected runtime code.
+- Do not run raw live deployment, production shell, migration, cluster, or cloud commands unless a
+  configured mustflow command intent explicitly permits them.
+- Do not start long-running servers, watchers, dashboards, or background deployment helpers.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build the deployment resource ledger.
+   List the actual runtime resources touched by the change. Include reads and writes separately:
+   API endpoints, workers, DB columns, cache keys, storage prefixes, queue messages, cron jobs,
+   external APIs, permissions, config, and feature flags. If the ledger is unknown, report that the
+   deployment blast radius is unknown instead of guessing.
+
+2. Build the release envelope.
+   Rollback needs more than an image tag. Bind image digest, chart or manifest revision, values
+   file hash, ConfigMap name or version, Secret version, migration range, feature flag snapshot,
+   ingress or router weight, deployer, and deployment time under one `release_id` when the platform
+   exposes those facts. If only a mutable tag such as `latest` identifies production, report that
+   rollback identity is not reproducible.
+
+3. Separate artifact promotion from environment rebuilds.
+   Verify whether staging and production receive the same artifact identity. Prefer promoting one
+   built artifact over rebuilding per environment. If per-environment rebuild is unavoidable, name
+   the drift risk and require commit SHA, dependency lock, image digest, and build input evidence.
+   Treat image tags as human labels and image digests as the rollback proof.
+
+4. Preserve rollback history and warm capacity.
+   For platform-managed rollbacks, check whether old revisions, ReplicaSets, Helm release history,
+   blue/green environments, or rollout controller history are retained long enough to be useful.
+   Do not treat a rollback path as safe if the old version is immediately scaled to zero, cold, or
+   deleted. Prefer traffic rollback to an already-warm old version before rebuilding or pulling a
+   replacement during an incident.
+
+5. Split deploy order from migration order.
+   For DB changes, check expand/migrate/read-write/switch/contract sequencing. New code must tolerate
+   old data, old code must tolerate expanded schema or new data, and contraction must wait until old
+   code is impossible. Check migration lock timeout, batch size, retryability, partial progress
+   markers, rollback preview evidence, point-in-time recovery practice, database config backup, and
+   rollback limits. Treat destructive rollback SQL as a data-loss risk, not a recovery guarantee.
+
+6. Treat config changes as code changes.
+   Diff config and environment variables. Require startup validation for missing, misspelled, empty,
+   malformed, or incompatible values. A service should fail fast before accepting traffic when a
+   required setting is unsafe. Prefer versioned or immutable config names over in-place config
+   mutation, and name whether env-var, mounted-file, or subpath-style config updates require pod or
+   process restart.
+
+7. Separate startup, liveness, and readiness.
+   Startup should protect slow boots, liveness should detect stuck processes, and readiness should
+   gate whether the instance can serve real dependencies. Do not count "process is running" as
+   deployment readiness. Keep liveness conservative enough that overload or long GC pauses do not
+   turn a recoverable incident into a restart loop.
+
+8. Check graceful shutdown before rolling traffic.
+   Verify SIGTERM or platform shutdown handling for in-flight requests, DB transactions, uploads,
+   payment or webhook callbacks, and streaming responses. The app shutdown timeout must be shorter
+   than load balancer connection draining.
+
+9. Drain workers deliberately.
+   Queue workers need a stop-accepting-new-work phase, a current-work completion or checkpoint phase,
+   and an idempotent retry path for interrupted work. Ack, delete, offset commit, and visibility
+   timeout behavior must match the shutdown path. Rollback should name consumer pause, in-flight
+   work completion, idempotency-key checks, and dead-letter or quarantine inspection for worker and
+   scheduler surfaces.
+
+10. Prove message compatibility.
+   Producers and consumers are rarely deployed at the exact same instant. Message format changes need
+   N-1 message compatibility, tolerant readers, versioned fields, defaults for missing data, and a
+   plan for queued old messages. Unknown event types should not crash old consumers; require
+   quarantine, dead-letter, or ignore policy that preserves investigation evidence.
+
+11. Design external side effects as compensation.
+    Emails, payment authorizations, third-party webhooks, provider state, and object-storage writes
+    do not disappear when code rolls back. Require outbox, idempotency key, state machine,
+    reconciliation, or compensation notes for side effects that cannot be undone by reverting code.
+
+12. Keep API compatibility wider than the deploy window.
+    Server versions and clients do not change at the same instant. Check N-1 and N+1 compatibility
+    for request fields, response fields, enum values, error codes, API versions, and mobile or SDK
+    clients. Removing fields, narrowing enums, or adding required inputs can make rollback fail even
+    when the old container starts.
+
+13. Add a kill switch, not just a flag.
+   Feature flags that only select a new path are not enough. Require a fast disable path, a safe
+   default when flag lookup fails, and an owner who can flip it during the observation window.
+
+14. Define the canary cohort.
+    Percent-only canaries can hide the exact risky traffic. Name which users, tenants, regions,
+    routes, worker partitions, queues, payment methods, or dependency paths receive the new version.
+    Prefer a cohort that exercises the changed behavior without making the blast radius vague.
+
+15. Measure canaries by version and by user harm.
+    A small canary can disappear in global averages. Require metrics split by service version,
+    release id, route, cohort, or worker partition where safe. Prefer user-impact signals such as
+    5xx, p95 or p99 latency, login failure, payment failure, order failure, queue backlog, or retry
+    explosion over CPU-only rollback triggers.
+
+16. Make automatic stop conditions numeric.
+    Before rollout, define stop or rollback thresholds for error rate, p95 or p99 latency, login or
+    payment failure, queue backlog, retry rate, dependency timeout, and saturation. "Watch it" is not
+    a stop condition.
+
+17. Verify read and write paths separately.
+    A read-only health check can pass while writes are broken. Add or identify smoke checks and
+    synthetic transactions that cover the changed read path, changed write path, and visible business
+    result without corrupting production data.
+
+18. Preserve release attribution in logs and telemetry.
+    Deployment logs and runtime logs should expose commit SHA, image tag or digest, config version,
+    chart or manifest revision, config version, migration version, feature flag state, deployment
+    environment, deployment id, service version, and instance. Log format changes must not silently
+    break alerts, dashboards, or search queries.
+
+19. Version cache keys and narrow invalidation.
+    Cache changes need cache key versioning or compatibility. Avoid blanket flushes unless the cold
+    DB load has been budgeted. Prefer narrow, gradual invalidation with fallback behavior named.
+    Old code must not deserialize new cache payloads without a compatibility plan.
+
+20. Guard scheduler duplication.
+    Cron and scheduled jobs can overlap during rolling deploys. Check singleton locks, leader
+    election, idempotency keys, deployment locks, and duplicate execution behavior for old and new
+    versions.
+
+21. Treat CRDs and operators as schema rollouts.
+    Custom resources, operators, storage versions, conversion strategies, and controller downgrade
+    behavior can block rollback even when application pods are healthy. When those surfaces change,
+    require stored-object migration, old-client compatibility, and operator downgrade notes.
+
+22. Use deployment locks per service and environment.
+    Two deploys, migrations, or production commands against the same service/environment need an
+    explicit conflict rule. Name the lock scope and the operator-visible owner.
+
+23. Make production commands boring.
+    Any production command touched by the change should have dry-run output, bounded target scope,
+    explicit confirmation or ticket reference, and refusal behavior for ambiguous environment,
+    tenant, region, or time range.
+
+24. Reserve post-deploy observation time.
+    Deployment is not done when traffic flips. Require a post-deploy observation window with owners
+    available, synthetic transaction results, dashboards, logs, queue backlog, dependency health, and
+    stop-condition status checked.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Deployment resources, rollout order, stop conditions, rollback limits, and manual deployment
+  boundaries are explicit.
+- Any missing resource ledger, missing configured verification, or production-only check is reported
+  instead of treated as complete.
+- Template, route, i18n, package, docs, and tests remain synchronized when this skill is edited or
+  installed.
+
+## Review Checklist
+
+- Deployment resource ledger is complete enough to name the blast radius.
+- Release envelope binds image digest, config, Secret, migration, flag, traffic, deployer, and time
+  under a stable release identity where those platform concepts exist.
+- Same artifact is promoted across environments or rebuild drift is explicitly controlled.
+- Rollback history is retained, the old version can stay warm when needed, and traffic rollback is
+  separated from rebuilding or repulling code.
+- DB migration, code deploy, data backfill, cache, queue, and rollback order are separated.
+- Required config is validated at startup and deployment config diff is inspectable.
+- Startup, liveness, and readiness probes answer different questions.
+- Graceful shutdown, load balancer connection draining, worker drain, and interrupted work retry are
+  compatible.
+- Queue messages, API payloads, and cache keys survive old/new producer, consumer, server, and
+  client overlap.
+- External side effects have idempotency, reconciliation, or compensation instead of rollback
+  overclaim.
+- Feature flag lookup failure chooses the safe default and a kill switch can stop the change.
+- Canary cohort, version-split telemetry, and automatic stop condition are concrete, numeric, and
+  tied to the changed flow.
+- Read smoke, write smoke, synthetic transaction, deployment logs, and post-deploy metrics are
+  defined before rollout.
+- Rollback notes say what code rollback cannot undo, especially migrations, cache, messages,
+  external side effects, and user-visible data.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Prefer the narrowest configured mustflow command intent that covers the changed surface:
+
+- `mf run test_related` for local tests around config validation, probes, shutdown, queue drain,
+  cache key behavior, migration compatibility, or smoke-check code.
+- `mf run build` or `mf run lint` when deployment metadata, generated code, or compile-time config
+  surfaces changed.
+- `mf run docs_validate_fast` when runbooks, skills, or deployment docs changed.
+- `mf run test_release` when package/template/release surfaces changed.
+- `mf run mustflow_check` before finishing broad mustflow-owned changes.
+
+Do not replace missing deploy safety proof with an unrelated full test suite. Report the missing
+configured intent or manual production verification boundary.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If strict mustflow validation says the skill is not listed, update both the prose trigger and the
+  route table row in `.mustflow/skills/INDEX.md`, then sync the template copy.
+- If validation says required section ids are missing, add the standard mustflow-section markers and
+  headings before changing command contracts or tests.
+- If a deployment-safety check cannot be executed locally, record the manual boundary and the
+  production evidence that must be collected during the observation window.
+- If rollback is unsafe because DB, cache, queue, external side effects, or user-visible data moved
+  forward, report roll-forward or mitigation work instead of claiming code rollback is sufficient.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+When reporting a review or change, include:
+
+- Skills used.
+- Deployment resources touched.
+- Rollout and rollback risks found or guarded.
+- Config, migration, cache, queue, probe, shutdown, canary, and observation decisions.
+- Verification commands run and their result.
+- Remaining manual deployment checks, especially production-only smoke, canary, and observation
+  steps that cannot be executed locally.

package/templates/default/locales/en/.mustflow/skills/desktop-auto-update-safety-review/SKILL.md

@@ -0,0 +1,265 @@
+---
+mustflow_doc: skill.desktop-auto-update-safety-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: desktop-auto-update-safety-review
+description: Apply this skill when desktop app automatic update behavior, Electron autoUpdater or electron-builder feeds, Squirrel.Windows first-run handling, Sparkle appcasts, Tauri updater configuration, macOS signed and notarized updates, Windows installers, Linux desktop packages, update metadata, latest.yml/latest.json/appcast.xml pointers, CDN caching, staged rollout percentages, alpha/beta/stable channels, update kill switches, artifact immutability, signatures, hash verification, signing-key custody, key rotation, certificate expiry, notarization gates, single-flight update checks, quit-and-install timing, old-version upgrade paths, rollback-forward fixes, updater telemetry, crash gates, or installed-app update smoke tests are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.desktop-auto-update-safety-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Desktop Auto Update Safety Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review desktop automatic updates as a remote code-execution supply chain, not a convenience button.
+
+The review question is not "does the new version download?" It is "can old installed clients
+discover, verify, stage, apply, relaunch, observe, stop, and recover from an update without mixing
+metadata, artifacts, signatures, channels, rollout cohorts, permissions, local data, or user work?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Electron `autoUpdater`, electron-builder update feeds, Squirrel.Windows, NSIS, MSIX, Sparkle,
+  Tauri updater, macOS appcasts, Windows installers, Linux desktop packages, updater endpoints,
+  release channels, or desktop installer metadata are created, changed, reviewed, or reported.
+- Code or docs touch update states such as check, download, verify, stage, apply, relaunch, rollback,
+  resume, retry, cancel, or post-relaunch health.
+- Release work touches immutable installer artifacts, `.sig`, `.blockmap`, `.yml`, `.json`,
+  `latest.yml`, `latest.json`, appcast XML, CDN cache policy, hashes, signatures, or channel
+  pointers that installed clients consume.
+- A desktop updater needs staged rollout, deterministic canary buckets, alpha/beta/stable channel
+  separation, kill switch, remote disable policy, crash gate, update telemetry, or emergency
+  forward-fix behavior.
+- A desktop update path depends on code signing, notarization, certificate expiry, signing-key
+  custody, key rotation, clean-machine install tests, old-version upgrade tests, migration
+  compatibility, or installed-app smoke tests.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only publishing a package, tag, registry version, GitHub Release, or generic release
+  asset without installed desktop updater behavior; use `release-publish-change`.
+- The task is only server, container, backend, worker, migration, feature-flag, or traffic rollout
+  safety; use `deployment-rollout-safety-review`.
+- The task is only background process crash recovery, leases, service supervision, sleep/resume, or
+  safe mode; use `desktop-background-process-stability-review`.
+- The task is only Tauri command permissions, capabilities, sidecars, opener, shell, CSP, or updater
+  endpoint trust inside a Tauri app; use `tauri-code-change` first, then return here for update
+  rollout and distribution behavior.
+- The task is only release notes wording without updater metadata, installed app behavior, or
+  release-channel claims; use `release-notes-authoring`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Updater stack ledger: framework, installer type, updater library, OS targets, install scope,
+  channel, feed URL, metadata format, signing model, update staging location, relaunch path, and
+  old-version support window.
+- State-machine ledger: check, download, verify, stage, apply, relaunch, first-run-after-update,
+  rollback or forward-fix, cancellation, retry, and failure states with user-visible outcomes.
+- Artifact ledger: immutable artifact names, platform assets, signatures, blockmaps or delta files,
+  hashes, sizes, metadata pointers, CDN cache policy, upload order, and remote publication status.
+- Trust ledger: code signing, notarization, updater signature, signing-key storage, key rotation,
+  certificate expiry gate, TLS expectations, metadata signing, and hash verification.
+- Rollout ledger: channel policy, staged percentage, deterministic bucket key, kill switch,
+  per-version deny or pause policy, OS or architecture gating, crash gate, and manual approval gate.
+- Installed-client ledger: oldest supported versions, skipped-version upgrade paths, data migration
+  compatibility, first-run locks, single-flight update checks, quit-and-install timing, user work
+  preservation, and clean-machine test matrix.
+- Observability ledger: check count, download start, download success, verification failure,
+  install start, install success, relaunch success, post-relaunch heartbeat, crash-free sessions,
+  update error codes, channel, version, OS, architecture, and cohort.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- Remote publication, live channel pointer changes, signing-key access, installer execution,
+  destructive asset deletion, yanking, or production kill-switch flips remain out of scope unless
+  explicitly authorized by the repository and host command contract.
+- If only static repository evidence is available, report installed-app, clean-machine, remote CDN,
+  signing, notarization, and update-smoke checks as manual or missing instead of implying they ran.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten update state machines, single-flight guards, staged rollout policy, deterministic
+  cohorting, kill-switch handling, remote updater policy, channel separation, signature and hash
+  checks, artifact upload ordering, cache headers, installed-client compatibility guards,
+  quit-and-install safety, migration idempotency notes, update telemetry, crash gates, and focused
+  tests or docs.
+- Update release checklists, updater runbooks, package metadata, template skills, installer docs,
+  test assertions, and release-sensitive fixtures that encode the desktop auto-update contract.
+- Do not overwrite an existing versioned artifact, reuse a broken version number as the fix, move a
+  stable channel to a beta feed, relax signature verification, store signing private keys on the
+  release server, or call an update complete from download completion alone.
+- Do not run raw installer, updater, signing, notarization, CDN, release, or OS lifecycle commands
+  outside configured command intents.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Define the updater as a state machine.
+   - Separate check, download, verify, stage, apply, relaunch, and post-relaunch health.
+   - Log or return stage-specific errors instead of a single "update failed" bucket.
+   - Preserve cancellation and retry behavior without corrupting staged files.
+2. Separate immutable artifacts from mutable pointers.
+   - Treat versioned installers, signatures, blockmaps, and platform assets as immutable.
+   - Change only the latest pointer, channel metadata, or staged rollout policy after all referenced
+     assets are uploaded and independently downloadable.
+   - Report any flow that overwrites `app-1.2.3`-style artifacts or edits a published version in
+     place.
+3. Enforce artifact-before-metadata ordering.
+   - Upload installers, `.sig`, `.blockmap`, `.yml`, `.json`, appcast, and platform assets before
+     changing `latest.yml`, `latest.json`, `appcast.xml`, or equivalent client-visible pointers.
+   - Give metadata short TTL or revalidation and give immutable artifacts long cache when safe.
+   - Treat mismatched metadata hash, size, signature, or URL as a live update-channel incident.
+4. Require trust verification.
+   - Verify code signing, notarization where applicable, updater signatures, file hashes, file sizes,
+     channel identity, and expected platform target before applying.
+   - Keep signing private keys off the release server and practice key rotation before an incident.
+   - Make certificate expiry, notarization failure, missing signature, or entitlement drift fail the
+     release gate before users see the update.
+5. Keep channels physically and logically separate.
+   - Separate alpha, beta, stable, canary, and enterprise channels by feed, metadata, or explicit
+     policy; do not rely only on version suffixes.
+   - Verify stable clients cannot accidentally consume beta or alpha metadata.
+   - Treat channel movement as a public release contract.
+6. Roll out by deterministic cohorts.
+   - Prefer install id, device id, account id, or another stable privacy-safe bucket key over
+     per-request randomness.
+   - Use staged rollout percentages with clear progression and stop rules.
+   - Add jitter and backoff so app start, network reconnect, or periodic checks do not stampede the
+     update server.
+7. Add server-side stop controls.
+   - Provide a kill switch or "no update" response for bad versions, OS targets, architectures,
+     cohorts, or channels without requiring a new app update.
+   - Preserve user-intentional pause, enterprise policy, and admin-managed update controls when the
+     product supports them.
+   - Do not make a broken updater fixable only by shipping another update through the broken path.
+8. Prevent duplicate update work.
+   - Guard update checks and downloads with a single-flight or mutex path.
+   - Handle app startup, menu-click, timer, network-reconnect, and background-triggered checks
+     converging on the same update state.
+   - Include Squirrel.Windows first-run or installer lock timing when the Windows stack can hold
+     files immediately after installation.
+9. Apply only when user work is safe.
+   - Gate quit-and-install, relaunch, or helper replacement on saved work, drained background tasks,
+     paused sync, and platform-specific quit events.
+   - Treat `before-quit-for-update`, preshutdown, app exit, and renderer close events as distinct
+     from ordinary shutdown when the framework exposes them.
+   - Report any forced restart path that can lose unsaved documents, recordings, uploads, database
+     sessions, or long local jobs.
+10. Test installed upgrade paths, not development mode.
+    - Prefer packaged, signed, installed-app update tests from older versions, clean users, clean
+      machines or VMs, and the install scopes users actually have.
+    - Include skipped-version paths from active old versions, not only previous-version to latest.
+    - Cover Windows user-wide versus machine-wide installs, macOS Intel versus Apple Silicon,
+      Gatekeeper, quarantine, app translocation, read-only mounts, and Linux package formats when
+      those targets exist.
+11. Make migrations update-safe.
+    - Support old data with new code, new data with old code when rollback or forward-fix overlap can
+      happen, and users who skip several app versions.
+    - Make local migrations idempotent with completion markers and partial-failure recovery.
+    - Prefer forward-fix with a higher version over attempting to repair a broken release by
+      republishing the same version.
+12. Keep old artifacts long enough.
+    - Retain full installers, deltas, signatures, metadata, and migration bridges needed by active
+      old clients.
+    - Do not delete old artifacts solely to reduce storage without checking active-version telemetry
+      and upgrade path coverage.
+13. Observe real update success.
+    - Count check, download, verify, install, relaunch, and post-relaunch heartbeat separately.
+    - Treat download completion as incomplete; success is the new version running and healthy after
+      relaunch.
+    - Split telemetry by version, channel, OS, architecture, cohort, installer type, and error code
+      while preserving privacy and redaction rules.
+14. Stop rollout automatically when harm appears.
+    - Define crash-free, verification-failure, install-failure, relaunch-failure, and support-ticket
+      thresholds that pause rollout or return "no update".
+    - Require operator-visible release id, channel, version, cohort, and artifact identity in update
+      logs or metrics.
+15. Report what cannot be proven locally.
+    - Name missing updater-smoke, clean-machine, signing, notarization, CDN-cache, staged-rollout,
+      crash-gate, or remote-feed verification instead of replacing it with unrelated unit tests.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Update state machine, immutable artifact policy, metadata pointer order, signatures, hashes,
+  key custody, certificate gates, channel separation, staged rollout, deterministic bucket, kill
+  switch, single-flight checks, first-run locks, quit-and-install safety, installed upgrade matrix,
+  migration compatibility, old artifact retention, update telemetry, crash gates, and manual remote
+  verification boundaries are explicit.
+- Mutable artifact overwrite, metadata-before-artifact publication, long-lived latest-pointer cache,
+  missing signatures, release-server private keys, unpracticed key rotation, expired certificate
+  surprise, random per-request canary, no kill switch, duplicate downloads, forced restart data loss,
+  development-mode-only update testing, same-version republish recovery, old artifact deletion, and
+  download-complete-as-success claims are fixed or reported.
+- Desktop updater safety claims are backed by configured tests, package or template checks, static
+  release evidence, installed-app smoke evidence, or clearly labeled as manual-only or missing.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer configured updater-smoke, package-inspection, signature, notarization, CDN, staged-rollout,
+install-smoke, or release-verification intents when the command contract exposes them. Do not infer
+raw signing, installer, CDN, release, updater, or OS commands from project files.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If metadata references missing artifacts, stale hashes, bad signatures, wrong channels, or broken
+  cache headers, treat the update channel as potentially live-broken and stop publication claims.
+- If an update was already visible to clients, prefer a new higher-version forward fix, kill switch,
+  or paused rollout over overwriting the same version.
+- If verification cannot run because signing keys, notarization, CDN, clean VMs, old installers, or
+  remote feeds are unavailable, report the exact missing evidence.
+- If automatic update safety conflicts with user data safety, signature security, enterprise policy,
+  least privilege, or rollback compatibility, keep the safer behavior and report the tradeoff.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Desktop auto-update boundary reviewed
+- Updater stack, state machine, artifact, trust, rollout, installed-client, migration, telemetry, and
+  kill-switch findings
+- Auto-update safety fixes made or recommended
+- Evidence level: configured-test evidence, package/release evidence, installed-app smoke evidence,
+  static updater risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped updater diagnostics and reasons
+- Remaining desktop auto-update risk