On this page

• Rule zero: Promote is operator-hand
• The ladder is configuration
• The rungs, in order
• Failing after advance
• Autoclean
• The audited override (FEAT-046)
• Rollback
• Container deployment and the signed version manifest
• Related skills

Rule zero: Promote is operator-hand

A promotion moves code onto a running environment, restarts processes, and can apply schema migrations. An agent must not run one. Read the ladder, explain a halt, prepare the commit, and hand the decision to the operator. A dry run (dryRun: true) is the agent-safe path: it mutates nothing and stops after the plan rung. The dirty-tree override in particular requires a human reason that is recorded in deployment history — supplying one on an operator's behalf defeats the control.

The ladder is configuration

A project's deploy_config.promotion.stages is an ordered array of {name, branch, path, pm2?, health?, migrate?}. Fewer than two stages, an unknown stage name, or a stage missing branch/path is a 400. Promotion climbs exactly one rung: demotion and rung-skipping are refused 400 with the ladder printed. GET /api/projects/:id/promotion-status reads state without touching anything: per stage sha, checkedOut, dirty/dirtyFiles/ dirtyTotal, declared pm2/health, lastDeploy from the journal; and per adjacent pair a rung with state of up-to-date, ahead (with ahead count), behind, diverged or unknown.

The rungs, in order

Every rung is a hard gate that reports its own step ({name, ok, detail}) and halts with an HTTP status; nothing proceeds on a failure, and nothing runs automatically — the route is explicit-trigger only.

On success a commander.deployments row records version (source sha), source and target env, triggered_by, the reason, the full step log and the commit list. A failure records a failed row too — except a dry run, which never writes history.

Failing after advance

Once advance is green the target checkout has already moved, so a later halt returns an explicit rollback object: the previous head and the exact commands that restore it (git -C <stage path> reset --hard <prevHead>, plus a pm2 restart when the stage declares one). The ladder never leaves a target silently half-promoted.

Autoclean

A promotion target legitimately accumulates install artifacts. Before calling a target dirty, the verify rung restores allowlisted, tracked-modified paths to HEAD (named default: the lockfile) and emits an explicit verify-autoclean step — the cleanup is never silent. Anything else dirty (untracked, added, deleted, renamed, or a non-allowlisted path) still halts, and a failed restore halts too. Autoclean never applies to the source: a dirty source is uncommitted work.

The audited override (FEAT-046)

override: {dirty: true} with a non-empty reason lets an authenticated operator pass a dirty-tree verify halt. The contract:

• Disabled on the instance → 403. Missing reason → 400.
• The halt response already says whether an override would apply

(overridable: true) and, when it would not, overrideBlockedBy.

• The fast-forward safety recheck is never overridable: if a dirty file on the

target is also changed by the promoted delta, the merge would refuse or clobber it, so the halt stands regardless of intent. Unparseable or quoted porcelain paths also keep the halt, because the conflict check cannot prove it saw every path.

• A used override emits its own verify-override step and the reason lands in

deployment history. Source dirt never rides a promotion — only committed HEAD moves.

Structural refusals (wrong branch, no repo, non-fast-forwardable) have no override at all.

Rollback

GET /api/projects/:id/rollback-candidates lists recent commits on a stage's own branch, annotated from the deployment journal so previously deployed shas stand out. POST …/rollback rewinds that stage with the same reset the promote engine prescribes, then re-runs the post-landing rungs. A rewound stage stays an ancestor of its upstream rung, so the next promotion fast-forwards straight back over it; revert commits on the target branch would break that invariant. Discarded commits remain reachable through the reflog. Rollback is operator-hand.

Container deployment and the signed version manifest

deploy/ holds the tenant image and its contract: a Dockerfile, a tenant compose file, an env example, and version-manifest.schema.json — JSON Schema draft 2020-12, $id under the vendor schema namespace. One manifest is one immutable release. Required: schemaVersion: 1, service (commander or guardian), version as SemVer 2.0 core, image.repository plus an image.digest of the form sha256:<64 hex> (an OCI digest, not a mutable tag), versionLock pinning the Claude Code, Node and PostgreSQL majors, migrations.from/ to, a non-empty preflight[] of {id, kind, severity} checks from a fixed kind set with severity block or warn, a rollout.strategy of blue-green or recreate, and the freshness/binding claims iat, exp and tenant that make replay, downgrade and cross-tenant reuse detectable.

The manifest is signed into a compact JWS (RFC 7515) with alg: EdDSA and a kid that is the RFC 7638 thumbprint of the public key; the payload is the manifest object, not a JWT claims wrapper, so a verifier checks the signature and then parses the payload. The deploy signing key is deliberately separate from the agent-manifest key: a deploy manifest authorizes pulling an image and swapping a live container, so a leaked agent-manifest key must not be able to sign one. The signer validates before signing and refuses both an invalid manifest and a non-Ed25519 key; Guardian holds the public key by kid and verifies before applying. scripts/release-catalog.mjs publishes a commit to the build catalog behind its own gates — clean tree, SemVer, duplicate check, per-file digests plus migrations and build info, then the record, the artifact and a listing verification. Both scripts are operator-hand.

Related skills

commander-observability (dependency locks, process and health signals), commander-security (why the ladder is server-side and what else is operator-hand).