Skip to content

feat: add monthly daily and stable release policy#95613

Open
kevinlin-openai wants to merge 19 commits into
openclaw:mainfrom
kevinslin:dev/kevinlin/stable-release-version-metadata
Open

feat: add monthly daily and stable release policy#95613
kevinlin-openai wants to merge 19 commits into
openclaw:mainfrom
kevinslin:dev/kevinlin/stable-release-version-metadata

Conversation

@kevinlin-openai

@kevinlin-openai kevinlin-openai commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

What Problem This Solves

OpenClaw cannot safely operate the new monthly daily/stable npm release model because release class, selector intent, protected policy authority, stable-line state, and publication evidence are not yet bound into one fail-closed contract.

Why This Change Was Made

This adds the YYYY.M.PATCH release classifier, strict selector policy, immutable policy/publish/postpublish evidence, authenticated exact-ref verification, and stable-line lifecycle tooling for npm releases.

The scope is intentionally npm-only:

  • Strict stable candidates use a policy-only preflight and reject Windows release inputs.
  • The candidate helper emits no macOS or other platform-release handoff.
  • The macOS workflow is unchanged by this PR.
  • Strict v2 stable closeout is explicitly deferred so it cannot enter the legacy platform-dependent closeout path; legacy closeout behavior remains unchanged.
  • Stable publication for macOS, Windows, GitHub Release assets, and other platforms is not introduced here.

The authoritative release/stable-lines.json genesis remains deferred to the July bootstrap PR, so strict stable npm publication remains blocked until that metadata exists and a fresh candidate preflight is run.

User Impact

Maintainers can run daily npm releases with latest while preparing a trailing-month stable npm line from stable/YYYY.M.33. Daily releases cannot accidentally advance the stable selector, and strict stable work fails closed unless the protected policy, source branch, tag, workflow runs, and immutable evidence agree.

Existing legacy and non-stable platform release behavior is preserved.

Evidence

  • Automated: 279 focused tests pass across candidate CLI behavior, workflow consumers, npm policy/publish contracts, immutable evidence, stable-line classification, and closeout routing.
  • Automated: strict stable candidate coverage proves no Windows input is required, Windows input is rejected, no macOS handoff is emitted, and no publish command is derived from the policy-only preflight.
  • Automated: closeout coverage proves strict v2 stable evidence is stopped before the legacy platform-dependent closeout path while v1 legacy behavior is preserved.
  • Automated: scoped oxfmt checks and git diff --check pass.
  • Downstream fork rehearsal: a 2026.6.33 stable line derived from this policy foundation completed an authenticated dry run and a publishing rehearsal from stable/2026.6.33, produced checksummed evidence assets, and installed the generated tarball in an isolated prefix.
  • Manual: exercise the official July npm-only stable preflight after authoritative stable-line metadata lands.
  • Manual: obtain release-manager signoff for the fail-closed npm rollout contract.

No authoritative stable-lines file is added by this PR.

@kevinlin-openai
kevinlin-openai requested a review from a team as a code owner June 21, 2026 21:59
@openclaw-barnacle openclaw-barnacle Bot added scripts Repository scripts size: XL maintainer Maintainer-authored PR labels Jun 21, 2026
@clawsweeper

clawsweeper Bot commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs real behavior proof before merge. Reviewed July 2, 2026, 10:38 PM ET / 02:38 UTC.

Summary
The branch changes release workflows, release candidate/policy scripts, release docs, and focused tests to add npm-only YYYY.M.PATCH daily/stable release classification, strict selector policy, immutable evidence, and stable-line lifecycle tooling.

PR surface: Source +15, Tests +2939, Docs +4, Config +1568, Other +3635. Total +8161 across 33 files.

Reproducibility: not applicable. This PR adds release-policy and workflow capability rather than fixing a user-reported runtime bug. The reviewable behavior is source-checkable through workflow, policy, evidence, and test surfaces.

Review metrics: 2 noteworthy metrics.

  • Release workflow input surface: 15 added, 2 changed workflow_dispatch inputs. Operator-facing release dispatch inputs are compatibility-sensitive because release managers may replay documented, saved, or scripted commands.
  • Stable-line metadata dependency: 1 deferred authoritative metadata file. Strict stable behavior depends on release/stable-lines.json metadata that this PR intentionally leaves to a later bootstrap gate.

Stored data model
Persistent data-model change detected: database schema: scripts/verify-release-operation.mjs, migration/backfill/repair: .github/workflows/full-release-validation.yml, migration/backfill/repair: .github/workflows/openclaw-npm-release.yml, migration/backfill/repair: .github/workflows/openclaw-release-publish.yml, serialized state: test/stable-release-lines.test.ts, vector/embedding metadata: test/stable-release-lines.test.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: canonical
Canonical: #95613
Summary: This PR is the canonical release-policy foundation; the only evidenced related item is adjacent stable-backport workflow work that depends on this metadata rather than replacing it.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🐚 platinum hermit
Result: blocked until stronger real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P1] Add redacted official OpenClaw strict npm preflight, Full Release Validation, and publish-path artifacts, or record a release-owner waiver.
  • [P1] Obtain release-manager signoff for the fail-closed npm rollout contract and stable-line bootstrap plan.
  • [P1] Rerun or clear the current failing required checks after proof and signoff are settled.

Proof guidance:

  • [P1] Needs stronger real behavior proof before merge: Linked fork artifacts show a useful after-fix rehearsal, but they do not show the official OpenClaw npm, Full Release Validation, stable-line bootstrap, or real-token release path; add redacted official logs/artifacts or a release-owner waiver before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Risk before merge

  • [P1] The PR changes workflow_dispatch inputs, release selector semantics, and fail-closed release behavior, so saved or scripted release-manager dispatches need explicit upgrade handling and signoff.
  • [P1] The fork rehearsal proves a useful stable-base dry run, but it does not prove official OpenClaw npm publication, Full Release Validation handoff, stable-line bootstrap, or real-token cross-repository release consumers.
  • [P1] Strict stable remains blocked until authoritative release/stable-lines.json metadata lands and the official July npm-only stable preflight is exercised or explicitly waived.
  • The current head still has failing CI checks, so merge readiness needs a green rerun or maintainer-owned waiver after proof and signoff are settled.

Maintainer options:

  1. Require official release proof and signoff (recommended)
    Before merge, collect redacted official OpenClaw output or artifacts for strict npm preflight, Full Release Validation handoff, publish evidence, and release-manager signoff on the fail-closed rollout contract.
  2. Accept a release-owner waiver
    Maintainers may explicitly waive part of the official proof gate if they own the operational risk and record which unexercised paths remain blocked until bootstrap.
  3. Pause or split bootstrap-dependent stable work
    If official-token proof and stable-line genesis cannot happen now, pause this PR or split a narrower daily-release foundation that avoids strict stable operator contract changes.

Next step before merge

  • [P1] Protected maintainer handling, release-manager signoff, official proof or waiver, and current CI state make this a human release-owner review item rather than an automated repair candidate.

Security
Needs attention: Needs attention because the diff changes release authority and artifact verification boundaries, and official release proof or a release-owner waiver remains needed before merge.

Review details

Best possible solution:

Merge the npm-only strict policy foundation only after release-manager signoff, redacted official proof or an explicit waiver, stable-line bootstrap handling, and green or intentionally waived required checks.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this PR adds release-policy and workflow capability rather than fixing a user-reported runtime bug. The reviewable behavior is source-checkable through workflow, policy, evidence, and test surfaces.

Is this the best way to solve the issue?

Mostly yes: the implementation centralizes release intent and evidence behind dedicated release scripts and keeps credentialed publish behind policy gates. It is not the best merge state until release owners sign off and official proof or a waiver covers the remaining token-bound paths.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8d535fb039c5.

Label changes

Label justifications:

  • P2: This is normal-priority release infrastructure work with meaningful maintainer/operator impact but no active end-user outage.
  • merge-risk: 🚨 compatibility: The PR changes release workflow inputs, selector semantics, and fail-closed behavior that existing release operators may rely on.
  • merge-risk: 🚨 automation: The diff rewires release orchestration, child workflow evidence, artifact handoffs, and stable closeout automation beyond what green unit tests alone settle.
  • merge-risk: 🚨 security-boundary: The diff changes how release authority is authenticated through protected refs, workflow runs, artifacts, digests, and token-bound release consumers.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: Linked fork artifacts show a useful after-fix rehearsal, but they do not show the official OpenClaw npm, Full Release Validation, stable-line bootstrap, or real-token release path; add redacted official logs/artifacts or a release-owner waiver before merge. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed

PR surface:

Source +15, Tests +2939, Docs +4, Config +1568, Other +3635. Total +8161 across 33 files.

View PR surface stats
Area Files Added Removed Net
Source 1 16 1 +15
Tests 16 2950 11 +2939
Docs 1 7 3 +4
Config 5 1623 55 +1568
Generated 0 0 0 0
Other 10 3696 61 +3635
Total 33 8292 131 +8161

Security concerns:

  • [medium] Prove the official release authority handoff — .github/workflows/openclaw-release-publish.yml:92
    The patch adds strict release policy and publish evidence gates while the PR body still leaves official bootstrap, npm publication, Full Release Validation, and real-token cross-repository consumer proof unchecked; release/security owners need redacted live proof or an explicit waiver.
    Confidence: 0.84

What I checked:

  • Repository policy read: Root AGENTS.md and scoped guides for scripts, docs, agents, channels, and tests were read; release workflow input changes and fail-closed release behavior are compatibility, automation, and security-boundary sensitive under the repo policy. (AGENTS.md:1, 8d535fb039c5)
  • Current main lacks the requested policy surface: Current main still has required choice-based npm_dist_tag release inputs and no policy_mode or release_selector in the release publish path, so this PR is not obsolete on main. (.github/workflows/openclaw-release-publish.yml:30, 8d535fb039c5)
  • PR head adds operator-visible release policy ingress: The PR makes npm_dist_tag optional, adds policy_mode and release_selector, and adds a release_policy job before the credentialed publish path. (.github/workflows/openclaw-release-publish.yml:30, 2198c7421449)
  • Strict selector contract is centralized: validateStrictPublishPolicy enforces closed strict inputs, rejects numeric correction releases, and maps stable-base/stable-patch to the stable selector. (scripts/lib/release-version-policy.mjs:61, 2198c7421449)
  • Strict stable remains policy-only in the candidate path: The candidate helper rejects Windows input for strict npm-only stable preflight, marks stable policy as nonpublishable, and requires legacy finals to keep the old Windows-source input. (scripts/release-candidate-checklist.mjs:315, 2198c7421449)
  • Stable metadata is an authenticated dependency: The verifier requires stable release metadata for stable-base or stable-patch, validates canonical serialization, and carries a stable-lines digest only for stable classes. (scripts/verify-release-operation.mjs:527, 2198c7421449)

Likely related people:

  • vincentkoc: Recent release workflow, release policy, candidate checklist, and monthly patch-version history is concentrated in this area, including monthly patch numbering and release-gate hardening. (role: recent release workflow contributor; confidence: high; commits: f5a7f613ee4d, abb6f04e0cac, 78a8caef381e; files: .github/workflows/openclaw-npm-release.yml, .github/workflows/openclaw-release-publish.yml, scripts/release-candidate-checklist.mjs)
  • steipete: Earlier release publish/preflight validation, npm dist-tag, evidence, and release docs work repeatedly touched the same workflows and runbook. (role: release automation history contributor; confidence: medium; commits: 6330fe607d03, 55c275b00aa1, c4d8e0be1815; files: .github/workflows/openclaw-npm-release.yml, .github/workflows/openclaw-release-publish.yml, docs/reference/RELEASING.md)
  • fuller-stack-dev: Recent stable release work added Windows companion asset gates that this PR intentionally preserves for legacy/platform release paths while narrowing strict stable to npm-only. (role: adjacent stable release gate contributor; confidence: medium; commits: 8ae1adfdccce; files: .github/workflows/openclaw-release-publish.yml, scripts/release-candidate-checklist.mjs, docs/reference/RELEASING.md)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. labels Jun 21, 2026
@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from 421c8ee to 7aa9540 Compare June 22, 2026 02:57
@kevinlin-openai

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Addressed the operator-contract finding: release:candidate now authenticates the exact npm tag-preflight producer and artifact, emits every required public macOS validation input, supports the canonical strict alpha branch, and the release runbook documents the same closed handoff. Focused verification: 53 tests, workflow checks, lint, formatting, and diff checks passed.

@clawsweeper

clawsweeper Bot commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@openclaw-barnacle openclaw-barnacle Bot added the docs Improvements or additions to documentation label Jun 22, 2026
@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from 7aa9540 to 3e195b5 Compare June 22, 2026 03:02
@kevinlin-openai

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Rebased onto current main (a182811070) with personal-authored commits preserved. The authenticated macOS handoff fix remains unchanged; post-rebase focused verification passed 71 tests plus workflow, formatting, and diff checks.

@clawsweeper

clawsweeper Bot commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from 3e195b5 to 735b931 Compare June 22, 2026 03:14
@kevinlin-openai

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Addressed the legacy compatibility finding at current head: omitted or empty legacy npm_dist_tag normalizes to beta at each policy ingress, all downstream jobs consume the normalized output, and strict stable retains an explicit empty tag. Verification passed 51 workflow-contract/package-acceptance tests plus workflow, formatting, and diff checks.

@clawsweeper

clawsweeper Bot commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling extensions: codex labels Jun 22, 2026
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 22, 2026
@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from d1baf46 to 8ada708 Compare June 22, 2026 04:22
@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from 8ada708 to 11c8826 Compare June 22, 2026 04:43
@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from 1f84894 to cfcedbd Compare July 3, 2026 01:58
@kevinslin

Copy link
Copy Markdown
Contributor

@clawsweeper re-review

The current head cfcedbdfbb8 addresses the prior internal-validation finding: validateReleaseOperationResult() now has an explicit internal-validation target branch that requires releaseTag: null, and focused coverage exercises the exact payload. The simplification amendment also binds the authenticated Actions run head to the independently expected target SHA and enforces stable-line digest applicability.

Verification: 326 changed-surface tests passed before the conflict-free rebase; post-rebase checks passed 89 policy/evidence tests, 40 package-acceptance workflow tests, workflow validation, docs/MDX/link audits, oxfmt, oxlint, and diff checks. The PR body has current proof.

@clawsweeper

clawsweeper Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from bd3d19b to 734186c Compare July 3, 2026 02:13
@kevinslin

Copy link
Copy Markdown
Contributor

@clawsweeper re-review

Current head 734186c834f preserves the fix for the prior internal-validation finding and is rebased onto main@8d535fb039c, absorbing the upstream Telegram boundary repair that caused the previous head's inherited boundary failure.

Post-rebase verification: 89 policy/evidence tests, type-aware lint on the changed release modules, workflow validation, docs/MDX/link/map audits, oxfmt, and diff checks pass. The full boundary command cannot run against this checkout's intentionally shared, different-lock node_modules; the new dependency-authoritative CI run is the final boundary proof.

@clawsweeper

clawsweeper Bot commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels Jul 3, 2026
@kevinslin
kevinslin force-pushed the dev/kevinlin/stable-release-version-metadata branch from 734186c to 2198c74 Compare July 3, 2026 02:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation maintainer Maintainer-authored PR merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 security-boundary 🚨 May affect sandboxing, authorization, credentials, or sensitive data. P2 Normal backlog priority with limited blast radius. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. scripts Repository scripts size: XL status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants