feat: deliver monthly Featured lineups with search intelligence

[Patrick-Erichsen]

Related: CLAW-724

What Problem This Solves

ClawHub's monthly Featured report has sixteen slots per catalog, which the existing eight-slot receiver rejects.

User Impact

The weekly digest shows every plugin and skill recommendation, pending editorial slot, rationale, monthly/final-seven-day install count and metadata freshness. Existing search totals, source counts, coverage, company opportunities, official gaps and movers remain separate from install ranking.

Deploy this receiver before enabling ClawHub's v4 sender. This PR does not send a digest or change Featured selections. Actual Discord delivery remains untested in this task; all transport proof used local fixtures.

Why This Change Was Made

V4 validates the complete monthly contract and renders bounded Carbon messages without dropping selected identities or pending reasons. Reports fitting one message stay together; longer reports use deterministic parts. The existing weekly key freezes the full payload and rendered-part hashes, and each part reuses the existing atomic claim, nonce and uncertain-send reconciliation owner. Overall success requires every part's receipt. Confirmed parts never repost; uncertain parts require reconciliation before delivery continues.

Frozen v1/v2/v3 validation, rendering and receipts remain unchanged. The existing proof script now follows multipart receipts. No new D1 table, configuration or dependency is introduced.

Runtime growth is +421 net lines for the v4 contract, sixteen-slot rendering and multipart receipt ownership; tests add 447 net lines, the proof tool 27, and docs 37. Reusing the existing message owner avoids a second retry/recovery implementation.

Evidence

Boundary	Before	After
Monthly payload	HTTP 400	Every slot retained; delivery and replay HTTP 200
Actual local ClawHub producer → receiver	Unsupported v4	All 32 IDs in three parts, 3556/3680/1503 text characters, six components each, no mentions or duplicate posts
Existing proof-script reader	Exit 1 after successful multipart delivery; read no message receipts	Exit 0; read all three confirmed parts from the same unchanged weekly receipt

• Exact-head CI on 99d7a44: bun run test passed all 369 tests across 39 files (185,546 assertions). All 39 receiver tests also passed locally; the unchanged actual producer replay again retained all 32 IDs in three parts.
• bun run typecheck and bun run deploy:dry-run: passed.
• Public-handler tests use SQLite-backed D1 and real Carbon serialization, replacing only Discord transport. Cover concurrency, confirmed rejection, uncertain middle-part recovery, final receipt-write failure, privacy/slot/period validation and frozen older weeks.
• Actual producer proof uses loopback HTTP. Proof-reader regression uses persistent local Wrangler D1 with Carbon's network executor replaced by a closed fixture transport; zero real Discord sends. The reader-only final delta also passes typecheck.
• Independent lead review inspected the full delivery, validation and rendering owners plus dependency contracts.

Review disposition

The ClawSweeper truncation finding is fixed. Four public-handler cases cover each flag independently and their combination: three failed before the fix, all four pass afterward. The catalog warning describes bounded adoption metadata inspection, not a capped monthly numeric census. The global warning describes omitted supporting evidence while preserving all proposed slots.

The requested live Discord send/readback proof is intentionally not performed under this task's explicit no-send instruction. Local HTTP, real Carbon serialization, SQLite-backed D1 and persistent native Wrangler D1 prove payload bounds, receipts, replay and recovery; Discord acceptance and visible rendering remain unverified. Receiver deployment will be verified read-only before enabling the v4 sender. This is an explicit proof limitation, not a claim that real Discord delivery passed.

[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.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 16, 2026, 4:38 PM ET / 20:38 UTC.

ClawSweeper review

What this changes

Adds sixteen-slot monthly Featured reports, bounded multipart Discord delivery, durable per-part receipts, and matching validation, tests, documentation, and proof-reader support.

Merge readiness

⛔ Blocked before merge - 3 items remain

This remains useful work: current main rejects v4 reports, and the earlier merged lineup work covers only eight selections per catalog. One display defect and the real-behavior proof gate remain unresolved.

Priority: P2
Reviewed head: 13bc03c2bdcf1f09ec801f2caf2f380598cd9453

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The implementation has substantial focused coverage, but a display defect and mocked Discord proof prevent merge readiness.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The supplied producer, D1, and proof-reader results exercise useful local boundaries, but delivery.ts and monthly.ts have only fixture Discord transport evidence. Real acceptance, message readback, and replay of the multipart report remain unproven. 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.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The supplied producer, D1, and proof-reader results exercise useful local boundaries, but delivery.ts and monthly.ts have only fixture Discord transport evidence. Real acceptance, message readback, and replay of the multipart report remain unproven. 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	7 items	Repository policy: Read the full root AGENTS.md; no nested AGENTS.md files were found. Applied Carbon component guidance and kept the checkout read-only. No maintainer-notes directory was present. Current main does not accept v4: The pinned main parser accepts only search_intelligence_weekly_v2 and v3; full lineups remain limited to eight recommendations per catalog. This establishes a distinct capability missing from main. Dropped completeness warnings: The new monthly renderer never reads digest.truncated or catalog.adoption.truncated, although both remain accepted by validation. Existing v3 rendering labels capped adoption and compacted evidence, and the v2 tests explicitly assert an input-capped warning.
Findings	1 actionable finding	[P2] Preserve truncation warnings in monthly reports
Security	None	None.

How this fits together

Hermit receives authenticated search-intelligence reports from ClawHub and posts advisory Featured recommendations to a configured Discord review channel. ClawHub owns selection and ranking; Hermit validates, renders, and records delivery without publishing Featured selections.

flowchart TD
  A[ClawHub frozen report] --> B[Authentication and validation]
  B --> C[Monthly report layout]
  C --> D[Bounded message parts]
  D --> E[Durable delivery receipts]
  E --> F[Discord review channel]
  F --> G[Replay and reconciliation]
  G --> E

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The supplied producer, D1, and proof-reader results exercise useful local boundaries, but delivery.ts and monthly.ts have only fixture Discord transport evidence. Real acceptance, message readback, and replay of the multipart report remain unproven. 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.
• Preserve truncation warnings in monthly reports (P2) - A valid v4 report can set digest.truncated or catalog.adoption.truncated, but this renderer reads neither flag. Consequently, capped adoption input and compacted search evidence look identical to complete input when time coverage is otherwise complete. Earlier rendering explicitly exposes these caveats. Add visible warnings for both flags and regression coverage so reviewers do not treat a partial report as complete.
• Complete next step (P2) - Restore truncation warnings and add real Discord delivery/replay proof. Screenshots or video are preferred for visible output; terminal output and logs also count. Redact credentials, IP addresses, phone numbers, private endpoints, and other private details. Update the PR body to trigger review; if needed, ask a maintainer to comment @clawsweeper re-review.

Findings

• [P2] Preserve truncation warnings in monthly reports — src/clawhubSearchIntelligence/monthly.ts:211-214

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Net code growth	Production +417 lines; tests +407; proof script +27; docs +37	The PR justifies production growth through the v4 contract and multipart receipts while reusing the existing recovery owner.

Technical review

Best possible solution:

Deliver complete advisory lineups with visible completeness caveats, preserved legacy receipts, and verified multipart delivery before enabling the v4 sender.

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

Yes for the display defect: a valid v4 payload with either truncation flag set passes validation, but the monthly renderer never reads those flags. This is source-established; no runtime reproduction was executed.

Is this the best way to solve the issue?

The versioned receiver and shared delivery owner are a reasonable approach, but the new layout must retain completeness warnings before it is an acceptable replacement for earlier report formats.

Full review comments:

• [P2] Preserve truncation warnings in monthly reports — src/clawhubSearchIntelligence/monthly.ts:211-214
  A valid v4 report can set digest.truncated or catalog.adoption.truncated, but this renderer reads neither flag. Consequently, capped adoption input and compacted search evidence look identical to complete input when time coverage is otherwise complete. Earlier rendering explicitly exposes these caveats. Add visible warnings for both flags and regression coverage so reviewers do not treat a partial report as complete.
  Confidence: 0.97

Overall correctness: patch is incorrect
Overall confidence: 0.94

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 0f3b5f801e67.

Labels

Label changes:

• add P2: This is a bounded enhancement to advisory reports with a completeness-warning defect, rather than an urgent failure of existing delivery.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The supplied producer, D1, and proof-reader results exercise useful local boundaries, but delivery.ts and monthly.ts have only fixture Discord transport evidence. Real acceptance, message readback, and replay of the multipart report remain unproven. 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.

Label justifications:

• P2: This is a bounded enhancement to advisory reports with a completeness-warning defect, rather than an urgent failure of existing delivery.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The supplied producer, D1, and proof-reader results exercise useful local boundaries, but delivery.ts and monthly.ts have only fixture Discord transport evidence. Real acceptance, message readback, and replay of the multipart report remain unproven. 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

What I checked:

• Repository policy: Read the full root AGENTS.md; no nested AGENTS.md files were found. Applied Carbon component guidance and kept the checkout read-only. No maintainer-notes directory was present. (AGENTS.md:5, 13bc03c2bdcf)
• Current main does not accept v4: The pinned main parser accepts only search_intelligence_weekly_v2 and v3; full lineups remain limited to eight recommendations per catalog. This establishes a distinct capability missing from main. (src/clawhubSearchIntelligence/evidence.ts:390, 0f3b5f801e67)
• Dropped completeness warnings: The new monthly renderer never reads digest.truncated or catalog.adoption.truncated, although both remain accepted by validation. Existing v3 rendering labels capped adoption and compacted evidence, and the v2 tests explicitly assert an input-capped warning. (src/clawhubSearchIntelligence/monthly.ts:213, 13bc03c2bdcf)
• Receipt compatibility and failure coverage: The new report receipt freezes payload and ordered rendering hashes while individual parts reuse the existing message owner. Added tests cover concurrent requests, rejected parts, uncertain middle-part recovery, final receipt-write failure, and rejection of a v4 replacement for an already-sent v3 week. Tests were inspected, not executed. (tests/searchIntelligenceApi.test.ts:570, 13bc03c2bdcf)
• Supplied proof explicitly replaces Discord transport: The captured PR body reports local producer-to-receiver success and persistent Wrangler D1 proof-reader coverage, but explicitly states that Carbon's network executor was replaced and zero real Discord sends occurred. A live GitHub read returned the same body and pinned head. Captured context sourceRevision: 0989dea2441acbe6c248e918d9e6eea635a766a1d6e6f1fcd24c94a5e7beecb7. (13bc03c2bdcf)
• Prior merged work and routing: GitHub verifies feat: deliver complete Featured lineups for both catalogs #45 as merged at this commit; its body specifies eight selections per catalog and advisory approval. Repository history also connects the same contributor to the prior receiver and evidence work. Deeper local blame/follow inspection encountered unavailable historical blobs, so no source-line introduction attribution is asserted. (src/clawhubSearchIntelligence/evidence.ts, 911c819bc68f)

Likely related people:

• Patrick-Erichsen: 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.

• Render and test both input-truncation warnings in v4.
• Provide redacted real Discord multipart delivery and replay evidence showing all selections, pending reasons, and confirmed receipts.

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: deliver monthly Featured lineups with search intelligence 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.