docs(skills): require evidence-driven backport audits (#112506)

2026-08-12 21:53:00 -06:00 · 2026-07-22 13:28:50 +09:00
parent e81a2ce657
commit 8d3d472cbe
4 changed files with 160 additions and 17 deletions
@@ -33,6 +33,12 @@ a workflow fix that the existing parent run cannot consume.
 ## Respect release guardrails

 - Do not change version numbers without explicit operator approval.
+- When normal beta/stable release planning includes a backport audit, read
+  `references/backport-discovery.md` before selecting commits. Freeze the
+  release baseline and main SHA, complete the durable candidate ledger, and get
+  approval for its categorized set before mutating the release branch. This
+  audit is required for discovery; it does not authorize optional backports on
+  an already-frozen candidate.
 - Versions use `YYYY.M.PATCH`, where `PATCH` is the sequential release-train number within the month, not the calendar day.
 - Choose a new beta train from stable and beta releases only. Alpha-only tags do not consume or advance the beta/stable patch number. Continue the highest existing unpublished/published beta train with the next `beta.N` when appropriate; otherwise increment the highest stable/beta patch by one and start at `beta.1`.
 - Example: after stable `2026.6.5`, the next new beta train is `2026.6.6-beta.1`, even if automated alpha-only tags such as `2026.6.10-alpha.1` exist.
@@ -211,8 +217,9 @@ prepare-run <PR>`.

 When asked to create the initial `.33` extended-stable line or a later
 maintenance patch, read
-`references/extended-stable-backports.md` and follow it before version, tag, or
-publication work. Treat backport discovery and preparation as an ability of
+`references/backport-discovery.md` and
+`references/extended-stable-backports.md` and follow both before version, tag,
+or publication work. Treat backport discovery and preparation as an ability of
 this release skill, not as a separate release workflow.

 The backport ability owns the complete mainline inventory, private-security
@@ -0,0 +1,85 @@
+# Evidence-Driven Backport Discovery
+
+Use this before selecting backports for any OpenClaw release line: regular
+beta/stable, extended-stable, alpha/nightly when it reuses an older release
+base, or a release-repair branch. It is an audit before the candidate is
+mutated, not a title search and not permission to expand a frozen release.
+
+## Freeze the Audit
+
+1. Pin the exact maintenance-line baseline and the exact `origin/main` SHA.
+   Use the release branch/tag/package baseline that users run, not a moving
+   local branch.
+2. Resolve the last accepted, auditable scan cursor. If none exists, use the
+   merge base of that baseline and the pinned main SHA. Histories without an
+   auditable cursor or merge base require maintainer direction; never guess
+   from dates, PR titles, or a previous abandoned release PR.
+3. Enumerate every main commit since that cursor, then remove only commits
+   proven patch-equivalent to the baseline. Account for merge, squash, direct,
+   reordered, and companion commits; `git cherry` is evidence, not the final
+   answer.
+4. Reconcile authorized public and private security advisories before calling
+   the inventory complete. Use the approved private advisory workflow for
+   unpublished details. The public record may say only `pending` or `cleared`.
+
+Keep a durable unreleased backport ledger with the staging evidence: scan
+bounds and pinned SHAs, baseline identity, total/equivalent/non-equivalent
+counts, filters, every candidate decision, applicability result, exclusions,
+dependency groups, and carry-forward blocked items. Security rows in public
+evidence must remain opaque; retain private identifiers only in the approved
+security record. The next accepted audit uses this ledger's `scan_end` as its
+cursor.
+
+## Find Reliability and Security Candidates
+
+Do not use commit subjects, labels, or PR visibility as an inclusion gate.
+Classify every non-equivalent commit in the ledger, and inspect the full
+production diff for every security- or reliability-signalled item.
+
+Search beyond explicit security terms. Separately review conventional
+`fix`, `perf`, and `doctor` commits whose production paths touch execution,
+authentication, sandboxing, networking, persistence, delivery, gateway,
+configuration, plugins, or major channels. Benign titles, dependency bumps,
+missing PRs, and broad batches can conceal operational fixes; they require a
+decision with evidence, not a cursory skip.
+
+For each such production diff, mechanically probe applicability in a temporary
+detached worktree at the pinned baseline before judging it:
+
+```bash
+audit_root=$(mktemp -d)
+git worktree add --detach "$audit_root/baseline" "$baseline_sha"
+(
+  cd "$audit_root/baseline"
+  git cherry-pick --no-commit "$candidate_sha"
+  git diff --check
+  git reset --hard HEAD
+)
+git worktree remove --force "$audit_root/baseline"
+rmdir "$audit_root"
+```
+
+Record whether the probe was clean, conflicted, empty/already-covered, or
+failed, along with the exact reason. A clean probe is triage evidence only; it
+does not approve a backport. If the commit needs companions, probe and assess
+the smallest ordered final fix rather than treating each clean commit as an
+independent candidate.
+
+## Decide and Present the Set
+
+For every proposed backport, inspect the complete change, baseline behavior,
+callers, callees, sibling surfaces, tests, dependency contracts, security
+impact, and the release publication surface. Collapse overlapping or dependent
+commits to the smallest final fix. Mark already-covered, not-affected,
+out-of-scope, and blocked items with the evidence that led to the decision.
+
+Exclude features, migrations, new configuration, new runtime requirements, and
+broad redesigns unless a maintainer explicitly approves their inclusion. Do not
+substitute convenient dependency bumps for a complete candidate audit.
+
+Before changing release refs, present the complete categorized ledger and the
+proposed set for maintainer approval. After approval, backport with provenance,
+update the ledger, run focused proof plus the release-appropriate validation,
+and keep the final branch/tag/version/SHA identity in that record. Dispatch npm
+preflight only after the canonical release branch or tag has that exact final
+version and SHA.
@@ -5,6 +5,11 @@ Discover the complete candidate set, obtain maintainer approval, and prepare
 the approved commits as one coordinated PR. Treat commits as canonical; use
 PRs, issues, ClawSweeper reports, and advisories as supporting context.

+Read `backport-discovery.md` first. Its evidence-driven inventory, detached
+baseline applicability probes, advisory reconciliation, and durable unreleased
+ledger are mandatory for this maintenance line; this reference adds the
+extended-stable package and publication constraints.
+
 ## Boundaries

 - Read `docs/reference/RELEASING.md`,
@@ -19,8 +24,9 @@ PRs, issues, ClawSweeper reports, and advisories as supporting context.
  exact version.
 - Exclude ClawHub publication, GitHub Releases, native apps, Docker images,
  mobile artifacts, website downloads, and private-repository dist-tags.
- Review the complete mainline delta. Do not stop after the first obvious
-  fixes or consider public PRs the complete source set.
+- Review the complete mainline delta using the shared evidence-driven audit.
+  Do not stop after the first obvious fixes or consider public PRs, titles, or
+  dependency bumps the complete source set.
 - Present the full proposed release set before changing release refs.
 - Never push directly to the canonical branch, create a release tag, publish a
  package, or mutate an npm dist-tag during discovery or staging.
@@ -112,9 +118,12 @@ git cherry "<canonical-extended-stable-ref>" "$scan_end" "$scan_start"

 If no auditable start exists, stop rather than guessing from dates or titles.

-Create an uncommitted scratch ledger with one row per non-equivalent commit.
-Process deterministic batches of at most 100 commits. Record each SHA, subject,
-changed paths, first-pass decision, and missing evidence.
+Create the durable unreleased backport ledger required by
+`backport-discovery.md`, with one row per non-equivalent commit. Process
+deterministic batches of at most 100 commits. Record each SHA, subject, changed
+paths, first-pass decision, applicability result, exclusions, and missing
+evidence. Keep public security rows opaque and private advisory detail only in
+the approved security record.

 ```bash
 ledger_dir=$(mktemp -d)
@@ -125,10 +134,13 @@ split -l 100 "$ledger_dir/all-commits.txt" "$ledger_dir/batch-"
 ```

 Review every ledger entry's subject and changed-file summary. Inspect the full
-diff and surrounding code for every plausible security or reliability fix.
-Account for merges, squash commits, direct commits, reordered patches,
-branch-specific equivalents, and companion commits that `git cherry` misses.
-Do not finish while any entry remains unclassified.
+diff and surrounding code for every plausible security or reliability fix, and
+mechanically probe each security- or reliability-signalled production diff in a
+detached baseline worktree as required by `backport-discovery.md`. Separately
+review conventional `fix`, `perf`, and `doctor` commits in the high-risk paths
+named there. Account for merges, squash commits, direct commits, reordered
+patches, branch-specific equivalents, and companion commits that `git cherry`
+misses. Do not finish while any entry remains unclassified.

 Also inspect direct maintainer/security commits, linked PRs and issues,
 ClawSweeper findings, companion fixes, callers, siblings, tests, and dependency
@@ -195,7 +207,8 @@ Classify each plausible fix as:

 Do not infer that a clean cherry-pick is safe. Treat config/default, persisted
 state, plugin/API boundary, protocol, dependency, packaging, installer, and
-cross-repository changes as high risk requiring maintainer judgment.
+cross-repository changes as high risk requiring maintainer judgment. Collapse
+overlapping or dependent commits to the smallest final fix before proposing it.

 ## Present the Full Release Set

@@ -211,8 +224,8 @@ affected core/plugin packages, out-of-scope publication surfaces, and
 confidential security status.

 Use PR links when they exist, but retain source commit identities in internal
-evidence. Obtain explicit maintainer approval for the complete release set
-before changing branches.
+evidence. Obtain explicit maintainer approval for the complete categorized
+ledger and release set before changing branches.

 ## Prepare the Approved Patch Set

@@ -240,8 +253,10 @@ before changing branches.
 The PR body must list the intended maintenance tag, exact npm publication
 inventory, every source commit and optional PR, impact, adaptations, focused
 and combined proof, security status, rollback considerations, and exact scan
-bounds. Record unresolved blocked candidates so the next run carries them
-forward.
+bounds. Update the durable ledger with branch/tag/version/SHA provenance and
+unresolved blocked candidates so the next run carries them forward. Dispatch
+npm preflight only after the canonical branch or tag has that exact final
+version and SHA.

 ## Handoff

@@ -19,6 +19,38 @@ Use for Tideclaw/OpenClaw alpha/nightly release automation, manual alpha trigger
 - Forward-port PRs contain only reusable fixes needed to make nightly/release checks pass. They must not contain alpha version bumps, release notes, changelog release entries, tags, generated artifacts, or state-file updates.
 - Keep only alpha/nightly branches from the last 3 days, plus any branch with an active run, open PR, or release tag.
 - Never run broad env/token dumps. For GitHub writes on the Tideclaw host, use the Tideclaw `gh` write wrapper below.
+- When an alpha, beta, or repair branch needs to discover or reuse backports
+  beyond its pinned base, complete the self-contained audit below before
+  mutating the candidate. Starting an alpha directly from the current pinned
+  `origin/main` does not create a backport audit by itself.
+
+## Audit Nightly Backports
+
+For any backport discovery, pin the exact release baseline and source main SHA.
+Start from the last accepted audit cursor or, when none exists, their merge
+base. Enumerate every non-patch-equivalent source commit, reconcile authorized
+public and private advisories, and record the bounds, counts, filters,
+applicability results, decisions, exclusions, dependencies, and blocked items
+in the existing alpha state file.
+
+Titles are signals, never gates. Classify the complete inventory, inspect every
+security- or reliability-signalled production diff, and separately review
+conventional `fix`, `perf`, and `doctor` commits in execution, authentication,
+sandboxing, networking, persistence, delivery, gateway, configuration, plugin,
+and major-channel paths. Mechanically try each such diff against a detached
+baseline worktree and record whether it is clean, conflicted,
+empty/already-covered, or failed. A clean patch is triage evidence, not an
+automatic backport.
+
+For every proposed item, inspect the complete change, baseline behavior,
+callers, callees, siblings, tests, dependency contracts, security impact, and
+publication surface. Collapse overlapping or dependent commits to the smallest
+final fix. Exclude features, migrations, new configuration or runtime
+requirements, and broad redesigns unless a maintainer explicitly approves them.
+Present the complete categorized set for approval before changing the candidate;
+then keep provenance in that state file, run focused proof and release
+validation, and dispatch npm preflight only after the canonical branch/tag has
+the exact final version and SHA.

 ## Identity

@@ -136,7 +168,11 @@ git for-each-ref refs/remotes/origin/tideclaw/alpha --format='%(refname:short) %
 git log --no-merges --reverse --format='%H%x09%s' origin/main..origin/tideclaw/alpha/YYYY-MM-DD-HHMMZ
 ```

-5. Cherry-pick only real stabilization fixes that still apply to the new alpha branch. Prefer commits recorded as `fixCommitShas` in the state file.
+5. Cherry-pick only real stabilization fixes that still apply to the new alpha
+   branch. When this is discovery rather than reuse of an already approved
+   state-file fix, apply the nightly backport audit before
+   selecting it; a clean cherry-pick or a benign title is not approval. Prefer
+   commits recorded as `fixCommitShas` in the state file.
 6. Skip version bumps, changelog release entries, tag artifacts, generated release notes, state-file-only commits, and one-off debug instrumentation.
 7. If a cherry-pick conflicts, inspect whether current main already contains an equivalent fix. If not, resolve minimally and keep the commit message clear.
 8. Record reused commit SHAs separately from newly authored fix SHAs in the alpha state and final Discord summary.