Skip to content

Reduce release approval ceremony - #41

Merged
raghubetina merged 1 commit into
mainfrom
codex/reduce-defensive-ceremony
Aug 19, 2026
Merged

Reduce release approval ceremony#41
raghubetina merged 1 commit into
mainfrom
codex/reduce-defensive-ceremony

Conversation

@raghubetina

Copy link
Copy Markdown
Contributor

Why

The 0.1.2 release workflow accumulated repeated authorization prompts and evaluator-driven defensive ceremony before we had real-world feedback to justify it.

What changed

  • let one explicit approval cover a named release sequence
  • retry controlled setup failures before Compile or external mutation without a new approval
  • replace exhaustive semantic recitation with a compact Plan-SHA-bound summary
  • allow bounded report-only status follow-up and straightforward local validator discovery
  • preserve exact approval before Compile, protected release identities, serialized public mutations, and fail-closed ambiguity recovery

Verification

  • Node 24.18 npm run check: 70/70
  • exact package check with released CLI d37d8b6775a0b97ce10bd651485bd308fed1dda2
  • strict Skill validation
  • independent ordinary and adversarial documentation reviews
  • packed 0.1.2 SHA-256: 24be4d4ea73d0d21aeed6248b72a775b4aba89c30180ccc6a69af13907b8b9ec

Historical evidence is unchanged.

Let one explicit approval cover a named release sequence and allow setup failures to be retried before any external mutation. Replace the exhaustive read-back with a compact, SHA-bound semantic summary while preserving approval, recovery, and immutable release boundaries.
@raghubetina
raghubetina merged commit 638264b into main Aug 19, 2026
2 checks passed
@raghubetina
raghubetina deleted the codex/reduce-defensive-ceremony branch August 19, 2026 15:24
@raghubetina

Copy link
Copy Markdown
Contributor Author

Post-merge review; hosted CI green (70/70 checks, strict Skill validation) and both documentation reviews ran
per the PR body.

The loosening is well-aimed. Every removed ceremony was process (re-approval per step, user recitation of
SHAs, exhaustive read-back), and every retained line is a real boundary: exact approval before Compile,
no byte reuse under an existing identity, serialized mutations through one operator, fail-closed on ambiguity,
and the new sentence doing the most work, "completing an approved step does not expand the remaining scope."
Identity resolution moving to the operator while intent approval stays with the user is the right division; a
human re-typing a digest was never a control, just friction.

The replay exception is scoped the way an exception should be. Unchanged bytes, same Publication singleton,
only after the prior invocation exits with a Publication-phase unknown or status timeout, and never for an
ambiguous Plan push. That is a resume, not a retry, and the text says so in all three documents consistently
(AGENTS.md, RELEASING.md recovery section, and the smoke procedure).

One observation, logged only: "named release sequence" carries the whole authorization model but its
minimum granularity is not defined. Step 2's phrasing implies the sequence enumerates its mutations; a loose
reading of AGENTS.md's "named promotion sequence" could treat "release 0.1.2" as naming everything through
latest. If an operator ever stretches it, the fix is one sentence stating that a sequence names its steps.
Not worth tightening before it bites, per the current velocity calibration.

The candidate digest change (901d5b to 24be4d) is a pre-release revision of an unpublished candidate, which the
byte-reuse rule explicitly permits. Consistent.

@raghubetina

Copy link
Copy Markdown
Contributor Author

This PR edits no code. It edits the rules an AI operator follows when releasing software, and the interesting
part is what it teaches about designing approval systems, which applies equally to human runbooks.

The starting problem. The release process had accumulated a prompt at every step: publish to next?
Approve. Promote the catalog? Approve again. Move latest? Approve again. Each approval also expected the
human to recite exact commit SHAs and package digests. When every step demands a ceremony, approvals become
rubber stamps, which is the opposite of control. Alert fatigue is the same failure in monitoring.

The redesign keeps one distinction sharp: intent versus identity. The human still approves intent, and one
approval can now cover a named sequence ("publish 0.1.2 under next, qualify, promote catalog, move latest").
The operator resolves and reports the exact identities (SHAs, digests) before touching anything, because
looking up exact values is what machines are good at. The guard against scope creep is explicit: finishing an
approved step never adds an unapproved one.

The subtle gem is the ambiguous-outcome rule. When a publish or push times out, you often cannot know
whether it happened. The old rule said reconcile read-only before retrying. The new rule is stricter and
smarter: reconcile read-only and do not repeat the mutation, with exactly one documented exception, a replay
that is safe because it is conditional on unchanged bytes and an existing server-side singleton. That is the
distributed-systems lesson in miniature: you cannot retry a non-idempotent operation after an unknown outcome,
you can only resume something designed to be resumable. The Plan push was not designed that way, so it is
explicitly excluded from the exception.

Why digests appear everywhere. "Never reuse a published version for different bytes" plus content hashes
means every artifact is identified by what it is, not what it is called. When a later commit changes only docs,
the rule says re-verify the packed digest reproduces, and skip re-running the product smoke. The hash equality
is what makes that skip safe rather than lazy.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant