Make the Crabbox skill portable and sync the ClawSweeper snapshot

[hxy91819]

Problem

openclaw/agent-skills is the canonical source for the shared Crabbox skill, but downstream repositories can retain stale, hand-copied snapshots:

• openclaw/openclaw currently matches the canonical Crabbox skill.
• openclaw/clawsweeper originally copied the OpenClaw snapshot in chore: add constrained Crabbox setup clawsweeper#172 and later needed a downstream-only provider-routing correction in docs: honor resolved Crabbox provider configuration clawsweeper#675.
• The current canonical skill references OpenClaw-specific scripts and workflows that do not all exist in ClawSweeper, so blindly replacing the downstream file is not compatibility-safe.

This leaves no deterministic provenance, drift check, or reviewed update path for downstream snapshots.

Scope

This issue specifically tracks making the canonical Crabbox skill safely consumable by openclaw/clawsweeper and automating the checked-in ClawSweeper snapshot at .agents/skills/crabbox. openclaw/openclaw is the reference consumer whose snapshot currently matches canonical; it is not the primary downstream target of this issue.

Goal

Keep one portable canonical Crabbox skill and provide deterministic, reviewable synchronization into the zero-setup openclaw/clawsweeper repository.

Proposed work

• Separate shared Crabbox policy from repository-specific commands, or make command selection portable across supported repositories.
• Define a machine-readable downstream provenance/pin containing the canonical repository, path, and exact commit SHA.
• Provide a deterministic sync command that copies the canonical skill at the pinned SHA.
• Add downstream CI that verifies the checked-in snapshot matches its pinned SHA rather than moving main.
• Add an updater workflow that detects a newer canonical revision and opens a downstream PR; do not push directly to downstream default branches.
• Synchronize and validate the snapshot in openclaw/clawsweeper; confirm openclaw/openclaw remains compatible as the reference consumer.
• Document ownership, compatibility review, rollback, and how downstream repositories intentionally opt into a repo-specific override when exact synchronization is impossible.

Acceptance criteria

• The canonical skill remains the only hand-edited source of shared Crabbox guidance.
• A downstream snapshot can be reproduced from its recorded canonical SHA.
• Downstream CI fails on unrecorded drift but does not fail merely because canonical main advanced.
• Upstream updates create reviewable downstream PRs with the old and new canonical SHAs.
• Every command and referenced path in a synchronized snapshot is valid for each consumer, or repository-specific material lives outside the shared snapshot.
• Automation uses least-privilege credentials and cannot directly merge cross-repository changes.

Non-goals

• Direct cross-repository writes to a default branch.
• Treating local-container execution as equivalent to required remote proof.
• Maintaining independent hand-edited copies of the same shared policy.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 2, 2026, 3:15 PM ET / 19:15 UTC.

Summary
Keep open for an explicit ownership and security-boundary decision. Current main still embeds OpenClaw-specific commands in the canonical Crabbox guidance and does not provide the requested immutable downstream pin, drift verifier, or reviewable updater; the member-authored, security-sensitive cross-repository design should not be auto-closed or routed to an autonomous repair.

Reproducibility: not applicable. this is a design and automation feature request rather than a report of a failing existing user path. Current source does confirm the portability gap because the shared skill invokes OpenClaw-specific commands.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Maintainer decision needed

Question	Recommendation
Should the canonical skill repository own a stable export contract for downstream snapshots, or should each consumer repository own its own pin, verifier, and update workflow?	Make synchronization downstream-owned: Keep only consumer-neutral Crabbox policy here, while ClawSweeper owns its immutable pin, drift check, update PR workflow, credentials, and documented override.

Why: The choice determines where repository-specific commands, persistent provenance, and any cross-repository credentials live; current VISION.md requires a narrow ownership model and isolation proof before privileged automation.

Next step
A maintainer must choose the shared-versus-downstream ownership model and least-privilege credential boundary before this feature can be split into safe implementation work.

Security
Needs attention: The proposed cross-repository updater and CI need a maintainer-approved least-privilege credential, ownership, and isolation design before implementation.

Review details

Best possible solution:

Keep Crabbox’s portable proof policy in this repository, and have ClawSweeper own any pinned snapshot verifier and review-only updater after maintainers approve a least-privilege cross-repository credential and override model.

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

Not applicable: this is a design and automation feature request rather than a report of a failing existing user path. Current source does confirm the portability gap because the shared skill invokes OpenClaw-specific commands.

Is this the best way to solve the issue?

No: implementing the whole proposed synchronization system in this repository would conflict with the documented boundary against bundling distribution infrastructure and requires an unresolved cross-repository security decision.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A shared updater or cross-repository workflow could require credentials and write authority beyond the current skill boundary; its trust model, token scope, and isolation proof are not yet defined.
• A direct exact-copy snapshot would preserve commands that assume OpenClaw scripts and environment variables, risking invalid downstream instructions unless repository-specific material is separated first.

Codex review notes: model internal, reasoning high; reviewed against 95e443f7275d.

Label changes

Label justifications:

• P2: This is a bounded but unresolved cross-repository workflow and portability improvement rather than an active user-facing outage.
• impact:security: The requested updater and downstream CI explicitly involve least-privilege credentials and cross-repository automation boundaries.

Evidence reviewed

Security concerns:

• [medium] Define cross-repository credential boundaries first
  A workflow that detects canonical revisions and opens downstream pull requests needs carefully scoped repository access; the issue does not yet establish token ownership, permitted operations, or end-to-end isolation proof.
  Confidence: 0.95

What I checked:

• Current canonical guidance is not portable as proposed: The current Crabbox preflight invokes an OpenClaw repository script and its trusted-test commands use OpenClaw-specific environment variables and package commands; no consumer-neutral command boundary is present in this skill. (skills/crabbox/SKILL.md:42, 95e443f7275d)
• Shared-skill boundary does not include downstream synchronization: The skill explicitly limits Crabbox to generic lease, sync, command, logs, results, timing, and cleanup, and assigns OpenClaw setup to repository scripts; the requested pin, CI, and updater are not implemented on current main. (skills/crabbox/SKILL.md:351, 95e443f7275d)
• Repository vision requires a narrow cross-repository ownership model: VISION.md permits portable workflows but says external repositories, credentials, and privileged automation require narrow ownership and end-to-end isolation proof; it also says not to bundle distribution infrastructure merely to publish one skill. (VISION.md:32, 95e443f7275d)
• Current Crabbox provenance: The available file history and blame attribute the current canonical preflight content to Peter Steinberger in commit 98122a3, dated 2026-07-16T09:07:41-07:00. (skills/crabbox/SKILL.md:42, 98122a3c3148)
• Maturity scorecard unavailable: The required maturity helper could not locate qa/maturity-scores.yaml in this checkout, so no maturity label is applied.

Likely related people:

• Peter Steinberger: Available git history and blame attribute the current Crabbox preflight and command-boundary content to this commit. (role: current canonical Crabbox contributor; confidence: high; commits: 98122a3c3148; files: skills/crabbox/SKILL.md)

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.