feat(e2e): teach the porting workflow object-model design + a11y locators

[stephenliang]

Improves the agentic Cucumber→Playwright porting workflow (.claude/), distilling lessons from porting platform/global_edition/region_select. The first pass produced a single scenario-shaped POM with assertions buried in it and CSS locators; these changes make the workflow design a proper object model, assert in the spec, and locate by accessibility role/name — so less hand-rework per port. No application or runtime code changes; only the porting agents + workflow.

Object-model design (Scout — the keystone)

Scout now plans the object model instead of a single POM:

• Replaced the singular targetPom with a pageObjects array (one per page/route, each with extends, kebab-case path, reused) and sharedChrome (global UI that belongs once on a shared base class).
• New STEP 4b — Design the object model, framing structure explicitly as test design.

This is the shape the workflow now aims for:

classDiagram
  BasePage <|-- SignInPage
  BasePage <|-- LegacyBlocklyLab
  LegacyBlocklyLab <|-- ArtistLab
  class BasePage {
    global chrome (locale switcher, header)
  }
  class SignInPage {
    page-specific
  }
  class LegacyBlocklyLab {
    lab-wide
  }
  class ArtistLab {
    one route
  }

Loading

A scenario spanning pages is coordinated in the spec, never modeled as an XyzPage.

Generator conventions

• POM encapsulation: page objects expose readonly Locators and own interactions; the spec performs the assertions on those locators. No single-assertion POM wrappers (expectXVisible()); a reused composite assertion lives in the spec file.
• Accessibility-first locators: drive locator choice from the a11y tree (browser_snapshot) — prefer getByRole/getByLabel by accessible name; CSS only when there is no accessible name, or the name is the text under test (e.g. a tab whose label localizes).
• kebab-case filenames (sign-in.ts, artist-lab.ts), never PascalCase.

Reviewer enforcement

The reviewer's BEST PRACTICES dimension now flags: scenario-as-page (BLOCKING), single-assertion POM wrappers, locators constructed in the spec from page, and undocumented CSS where an accessible name exists.

Links

• Jira:

Testing story

• node --check on the workflow script; the pre-commit lint hook passes on all three files.
• These are agent/workflow prompts (no runtime suite applies). The conventions were validated empirically by the region_select port that motivated them — its spec is green under the 5×/all-browser stress gate and follows exactly this shape (BasePage → SignInPage / LegacyBlocklyLab → ArtistLab; locators exposed; assertions in the spec; role/name locators).
• The gitignored playwright-best-practices skill (skill-lock installed) is intentionally unchanged; the conventions live in the agent defs, which carry their own copy.