feat: limit Featured to eight selections per catalog

[Patrick-Erichsen]

What Problem This Solves

Featured has no per-catalog size limit, and keeping an existing selection rewrites its timestamp and audit history.

User Impact

Featured permits eight plugins and eight skills. A ninth addition explains that an existing selection must be removed first; keeping a selection preserves its position and history. Experimental Claws do not consume plugin slots.

Why This Change Was Made

The canonical publication mutations enforce the cap transactionally, including admin and maintenance entry points. Existing membership bypasses insertion and audit/scheduling work. Skill webhook scheduling is now awaited by its mutation owner.

Evidence

Before: the ninth grant succeeded; retaining rewrote state, and an unrelated Claw could consume a plugin slot. After: UI/admin/maintenance reject the ninth, remove-then-add succeeds, each catalog is independent, and retained badge/audit/scheduler state is byte-equivalent. Actual native Convex proof independently accepts eighth, rejects ninth, and preserves the retained timestamp.

Production +57 net lines for the shared transactional cap and mutation ownership; tests/support +225. No schema or configuration changes.

Validation at the complete stack: static, 6,903 unit tests, types/build, package verification, and HTTP/CLI e2e all passed. Native Convex and authenticated browser checks use isolated labeled fixtures; production Featured and digest delivery remain unchanged.

Related: CLAW-724.

Review follow-up: 94b6bcad62 revalidates legacy membership at the maintenance mutation before applying new-selection admission. Nine legacy selections restore completely, later records still process, replay is idempotent, and new UI/maintenance grants remain blocked. Paired reproduction: before 1 failed/2 passed; after 48 publication/maintenance tests passed. Existing over-cap catalogs retain membership for curator review; no automatic removal. The accepted transition is recorded in CLAW-724 and the stack’s existing search-intelligence specification.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clawhub	Ready	Preview	Sep 16, 2026 3:23am UTC

[clawsweeper]

Codex review: blocked before merge. Reviewed September 15, 2026, 11:14 PM ET / September 16, 2026, 03:14 UTC.

ClawSweeper review

What this changes

Limit new Featured selections to eight plugins and eight skills, preserve retained selections and their history, and await skill notification scheduling.

Regression provenance

Possible regression — suspected (reviewed change). No predecessor PR is attributed.

Merge readiness

⛔ Blocked before merge - 3 items remain

The change remains useful and is not implemented on current main, but the new capacity check also interrupts restoration of existing legacy Featured selections. This collaborator-authored PR should remain open.

Priority: P2
Reviewed head: 01db8d52031e8ed93ecc00bc718697bd4599c02f

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The focused implementation and regression coverage are useful, but the legacy restoration defect prevents approval.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator exemption applies. The body reports native Convex checks of the changed publication mutations, but those claims do not establish legacy-backfill upgrade coverage.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator exemption applies. The body reports native Convex checks of the changed publication mutations, but those claims do not establish legacy-backfill upgrade coverage.
Evidence reviewed	8 items	Verified introduced scope: The verified test merge has the pinned main and PR head as its two raw parents. Its comparison against main contains only the six introduced Convex files; unrelated main-branch changes are preserved. Current-main behavior: Current main still updates the highlighted badge, skill timestamp and audit history on repeated selection; the shared capacity policy is absent. Introduced backfill failure: The new guard rejects insertion whenever eight highlighted table records exist, without distinguishing a new selection from restoration of an existing legacy selection.
Findings	1 actionable finding	[P1] Preserve legacy selections when backfilling badge records
Security	None	None.

How this fits together

ClawHub’s Featured catalog uses staff-managed badge records to curate plugins and skills. Browser and admin requests update those records through Convex mutations, which feed catalog listings and skill notifications.

flowchart TD
  A[Staff browser or admin request] --> B[Authenticated publication mutation]
  B --> C{Already selected?}
  C -->|Yes| D[Preserve selection and history]
  C -->|No| E[Check catalog capacity]
  F[Legacy badge backfill] --> E
  E --> G[Badge records and audit history]
  G --> H[Catalog listings and notifications]

Loading

Before merge

• Preserve legacy selections when backfilling badge records (P1) - This mutation is also called by backfillSkillBadgeTableInternalHandler, which restores existing membership from skill.badges.highlighted or batch === "highlighted". With nine legacy selections and an empty badge table, the first eight restorations commit and this guard rejects the ninth, aborting the action before later records are processed. These are existing selections, not new grants. Distinguish verified legacy restoration from new selection admission and add an over-cap backfill regression.
• Resolve merge risk (P1) - The supplied validation does not establish upgrade behavior for catalogs with more than eight legacy selections; affected backfills would stop after partial progress unless restoration is handled separately.
• Complete next step (P2) - Repair legacy badge restoration, add an over-cap upgrade regression, and document how existing selections transition to the new cap.

Findings

• [P1] Preserve legacy selections when backfilling badge records — convex/maintenance.ts:1938

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Diff size	+246/-13 across 6 files	The introduced change is confined to Convex publication logic and tests.
Production versus tests	Production +49 net lines; tests +184 net lines	Production growth is justified by the shared cap and idempotent publication behavior.

Merge-risk options

Maintainer options:

1. Preserve legacy restoration (recommended)
   Distinguish restoration of stored Featured membership from new grants, and verify both over-cap upgrades and normal eighth/ninth selection behavior.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Preserve existing legacy Featured membership during badge backfill without permitting genuinely new selections to bypass the eight-item cap; add fresh-state and over-cap legacy regression coverage and document the transition in specs.

Technical review

Best possible solution:

Enforce the cap on new selections while preserving restoration of existing membership, with documented transition rules and upgrade regression coverage.

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

Yes, from source: backfilling nine skills with legacy highlighted membership and no badge-table rows commits eight restorations, then throws on the ninth. This path was inspected, not executed.

Is this the best way to solve the issue?

Not fully: shared transactional enforcement is the right layer and avoids UI-only bypasses, but applying new-selection admission rules to legacy restoration is too broad.

Full review comments:

• [P1] Preserve legacy selections when backfilling badge records — convex/maintenance.ts:1938
  This mutation is also called by backfillSkillBadgeTableInternalHandler, which restores existing membership from skill.badges.highlighted or batch === "highlighted". With nine legacy selections and an empty badge table, the first eight restorations commit and this guard rejects the ninth, aborting the action before later records are processed. These are existing selections, not new grants. Distinguish verified legacy restoration from new selection admission and add an over-cap backfill regression.
  Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.95

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 5bf0026d8f6f.

Labels

Label changes:

• add P2: This is a bounded staff-curation improvement with an upgrade-path defect, rather than an urgent general-user outage.
• add merge-risk: 🚨 compatibility: The introduced guard can interrupt the existing legacy badge backfill after earlier records have already committed.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The collaborator exemption applies. The body reports native Convex checks of the changed publication mutations, but those claims do not establish legacy-backfill upgrade coverage.

Label justifications:

• P2: This is a bounded staff-curation improvement with an upgrade-path defect, rather than an urgent general-user outage.
• merge-risk: 🚨 compatibility: The introduced guard can interrupt the existing legacy badge backfill after earlier records have already committed.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The collaborator exemption applies. The body reports native Convex checks of the changed publication mutations, but those claims do not establish legacy-backfill upgrade coverage.

Evidence

Acceptance criteria:

• [P1] bunx vitest run convex/featuredPublication.runtime.test.ts convex/maintenance.test.ts.
• [P1] bun run ci:static.
• [P1] bun run ci:unit.
• [P1] bun run ci:types-build.
• [P1] bunx tsc -p packages/schema/tsconfig.json --noEmit.

What I checked:

• Verified introduced scope: The verified test merge has the pinned main and PR head as its two raw parents. Its comparison against main contains only the six introduced Convex files; unrelated main-branch changes are preserved. (32cead7f23ac)
• Current-main behavior: Current main still updates the highlighted badge, skill timestamp and audit history on repeated selection; the shared capacity policy is absent. (convex/skills.ts:10879, 5bf0026d8f6f)
• Introduced backfill failure: The new guard rejects insertion whenever eight highlighted table records exist, without distinguishing a new selection from restoration of an existing legacy selection. (convex/maintenance.ts:1938, 01db8d52031e)
• Legacy restoration caller: backfillSkillBadgeTableInternalHandler derives membership from stored badges.highlighted or batch=highlighted, then invokes the guarded mutation separately for each record. A rejection leaves prior mutations committed and prevents processing subsequent records. (convex/maintenance.ts:2112, 01db8d52031e)
• Proof and validation scope: The complete captured PR body reports native Convex eighth/ninth/retain checks and successful broader validation. The added convex-test cases cover new grants, replacement and retained state, but not restoration of more than eight legacy selections. No tests were executed during this read-only review. (convex/featuredPublication.runtime.test.ts:60, 01db8d52031e)
• Related work remains distinct: feat: recommend complete Featured lineups for both catalogs #3726 remains open and explicitly provides advisory lineups without publishing Featured selections; it does not replace this mutation-level change. (ea41d09efe1c)

Likely related people:

• Patrick-Erichsen: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Shadow: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Preserve legacy badge restoration while retaining the cap for new grants.
• Add regression coverage and a spec note for catalogs already above eight selections.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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 status: review started.

I am starting a fresh review of this pull request: feat: limit Featured to eight selections per catalog This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.