fix(commerce-pdp-management): resolve scope-only rules, debounce product picker, fix review queue filter

[plsrd]

What this PR does

Fixes three bugs from the internal review of the commerce-pdp-management starter: attribute rules that only appear in a product-type scope were silently dropped by the resolver, the Studio product picker could show stale Shopify results, and a rule sent back to draft after approval never reappeared in the Review queue. Docs are updated where the behavior an editor relies on changed.

Changes

1. Scope-only attribute rules resolve instead of being dropped

What was wrong: selectPriorityList built its id map from the global controlPlane.priorityList only, and the controlPlaneQuery projected each productTypeScope as bare ruleIds. A rule referenced only by a scope was looked up in a map it was never in, so it vanished with no signal to the merchandiser.

What changed:

• frontend/sanity/queries.ts dereferences each scope's priorityList with the same rule projection as the global list.
• ProductTypeScope now carries priorityList: Array<AttributeRule | null> (GROQ returns null for a deleted or unpublished reference), and ControlPlane.priorityList is typed the same way.
• resolvePdp.ts puts the scope's own rules first (in scope order, including scope-only rules) and appends the remaining global rules. Unresolvable entries are skipped with a console.warn naming the list they came from.
• packages/@starter/sanity-types/sanity.types.ts regenerated for the new query shape.

2. Product picker search is debounced and sequenced

What was wrong: ProductPickerInput called searchShopify directly on every keystroke with no debounce or request ordering, so a slow earlier response could overwrite the suggestions for a later, more specific term.

What changed: New studio/hooks/useDebouncedSearch.ts (no existing debounce utility in this starter to reuse) debounces keystrokes (250ms), numbers each request, aborts the previous one via AbortController, and only applies the result for the latest request. searchShopify takes the signal; the component now just calls search(term). studio/tsconfig.json includes the new hooks/ dir.

3. Review queue shows everything not yet approved; review-stamp resets

What was wrong: The Review queue filtered attributeRule on status == "in-review" only, so flipping an approved rule back to draft removed it from the queue entirely. Meanwhile skuEnrichment used draft as its queue state, so the two types behaved inconsistently. The README describes the queue as where "drafts land ... before anything reaches a customer", so the queue now matches that.

What changed:

• studio/structure.ts filter is _type in ["attributeRule", "skuEnrichment"] && status != "approved".
• functions/review-stamp/index.ts now also clears aiEnrichment.reviewedAt when a rule leaves approved, so a re-approval gets a fresh timestamp instead of keeping the old one. Both patches are guarded on current state so neither re-fires itself. The blueprint event filter already covered all published attributeRule updates; no blueprint change needed.
• AGENT.md documents the status flow, the new queue semantics, scope resolution, and the picker hook.

Testing

Run from commerce-pdp-management/ with dummy SANITY_STUDIO_PROJECT_ID / SANITY_STUDIO_DATASET set:

• pnpm typegen — regenerated types (3 queries, 23 schema types)
• pnpm -r typecheck — passes in functions, packages/@starter/commerce, studio, frontend
• pnpm lint — clean
• pnpm format:check — clean (root npx oxfmt also run via the pre-commit hook)
• pnpm --filter @starter/functions build — both bundles build
• pnpm validate — template validated
• Ad-hoc node:test suite against resolveAttributeRules (not committed; the starter has no test runner): scope-only rule resolves and wins its category, non-matching product type falls back to global, scope reorders shared rules and appends unscoped globals, null refs skipped with one warning per list, null/empty control plane yields []. 5/5 pass.

Not verified live: the Studio picker UI against a real Shopify store, and the review-stamp Function against a deployed dataset (logic is a straightforward extension of the existing guarded patch).

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated
agentic-localization	Ready	Preview	Sep 3, 2026 7:29pm UTC
ai-shopping-assistant	Ready	Preview	Sep 3, 2026 7:29pm UTC
commerce-pdp-starter	Ready	Preview	Sep 3, 2026 7:29pm UTC
commerce-plp-starter	Ready	Preview	Sep 3, 2026 7:29pm UTC
content-analytics-starter	Ready	Preview	Sep 3, 2026 7:29pm UTC

[cursor]

Approved. Cursor Bugbot was not present after the first check poll, so that automated-review signal was skipped; no approval policy required human review. Reviewers were not assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Approver}

[jarodreyes]

Looks good @plsrd !