docs(templates): consumer bootstrap kit and enforcement map

[weijia-89]

Summary

Automated SDK weekend worker + _sdk_verify_and_pr.sh verification.

SDK code review (trainer → form-check + review-rigor)

Verdict: APPROVE
Queue: playwrighter-consumer-kit
Branch: feat/consumer-kit-sdk · Repo: weijia-89/playwrighter

• Local artifact: localonly/sdk-reviews/playwrighter-consumer-kit-feat-consumer-kit-sdk.md
• Playground mirror: cursor-sdk-playground/prompts/reviews/playwrighter-consumer-kit-feat-consumer-kit-sdk.md

Summary

• Scope: Docs-only PR — CHANGELOG.md, root README.md enforcement map, and templates/README.md consumer bootstrap. No runtime/tool code changes.
• COR audit: Enforcement map rows were checked against tools/validate-suite.sh (check_error / check_warning) and tools/score-tests.js (rubric comment + scoreFile()). Penalties, severities, and "—" cells match source (including .toBeTruthy() error-only in validate vs both in score, CSS class-only warnings in validate vs class/id in score, and score-only rows for TC IDs, tags, fixtures import, file size).
• Bootstrap flow: Copy commands align with templates/package.json scripts (validate = check-tools → validate-suite → lint → typecheck; score = check-tools → score-tests --threshold=80), templates/scripts/check-tools.js, and fixtures.ts ./pages/ import layout when pages land under tests/pages/.
• Links: ARCH.MD#enforcement-pipeline, skill/SKILL.md#mandatory-workflow, and root README.md § Integration anchors exist. "23 pattern files" matches patterns/*.md count.
• Verify: _sdk_playwrighter_verify.sh (syntax-check + northwind-qa dogfood validate/score) is appropriate for a docs change that documents those tools; ran clean (exit 0).
• Residual: Pre-existing Quick Setup block (unchanged) still copies pages flat into tests/ — incompatible with fixtures.ts — while new Consumer bootstrap uses the correct tests/pages/ layout.

Full ranked findings are in the PR review comment posted by the SDK hook.

---

Posted by _sdk_verify_and_pr.sh after _sdk_trainer_codereview.sh. Merge still requires CI green and human review; BLOCK / REQUEST_CHANGES (with SDK_CODEREVIEW_STRICT=1) stop the hook before push.

Test plan

• bash "/Users/wjia/Projects/cursor-sdk-playground/scripts/_sdk_playwrighter_verify.sh" "/Users/wjia/Projects/playwrighter/.worktrees/worktree-consumer-kit"
• trainer codereview gate (unless SDK_CODEREVIEW_SKIP=1)
• CI green
• Human review

[weijia-89]

SDK code review (trainer → form-check + review-rigor)

Verdict: APPROVE
Queue: playwrighter-consumer-kit
Branch: feat/consumer-kit-sdk · Repo: weijia-89/playwrighter

• Local artifact: localonly/sdk-reviews/playwrighter-consumer-kit-feat-consumer-kit-sdk.md
• Playground mirror: cursor-sdk-playground/prompts/reviews/playwrighter-consumer-kit-feat-consumer-kit-sdk.md

Summary

• Scope: Docs-only PR — CHANGELOG.md, root README.md enforcement map, and templates/README.md consumer bootstrap. No runtime/tool code changes.
• COR audit: Enforcement map rows were checked against tools/validate-suite.sh (check_error / check_warning) and tools/score-tests.js (rubric comment + scoreFile()). Penalties, severities, and "—" cells match source (including .toBeTruthy() error-only in validate vs both in score, CSS class-only warnings in validate vs class/id in score, and score-only rows for TC IDs, tags, fixtures import, file size).
• Bootstrap flow: Copy commands align with templates/package.json scripts (validate = check-tools → validate-suite → lint → typecheck; score = check-tools → score-tests --threshold=80), templates/scripts/check-tools.js, and fixtures.ts ./pages/ import layout when pages land under tests/pages/.
• Links: ARCH.MD#enforcement-pipeline, skill/SKILL.md#mandatory-workflow, and root README.md § Integration anchors exist. "23 pattern files" matches patterns/*.md count.
• Verify: _sdk_playwrighter_verify.sh (syntax-check + northwind-qa dogfood validate/score) is appropriate for a docs change that documents those tools; ran clean (exit 0).
• Residual: Pre-existing Quick Setup block (unchanged) still copies pages flat into tests/ — incompatible with fixtures.ts — while new Consumer bootstrap uses the correct tests/pages/ layout.

Findings (ranked)

F1 · P4 · ARC · conf 78%

Dual onboarding paths — Quick Setup vs Consumer bootstrap

templates/README.md adds a correct Consumer bootstrap (tests/pages/ + tests/specs/), but the unchanged Quick Setup section still runs cp -r templates/pages your-project/tests/, which places POMs at tests/login-page.ts while templates/fixtures.ts imports ./pages/login-page (lines 11–12). Agents following Quick Setup will hit module-not-found errors; Consumer bootstrap avoids this.

Downstream consequence: Future SDK/agents may copy the shorter Quick Setup block and fail before validate gates — undermining the PR's consumer-kit goal.

Remediation (human follow-on): Either deprecate Quick Setup in favor of Consumer bootstrap, or fix Quick Setup paths to match bootstrap (tests/pages/, tests/specs/).

Scorecard (S1–S7): S1 evidence ✓ (read fixtures.ts + both README sections) · S2 root cause ✓ (path layout) · S3 blast radius medium for new consumers · S4 fix scoped · S5 not introduced by this diff · S6 verify N/A · S7 tier-appropriate P4.

---

F2 · P4 · COR · conf 72%

CI wording — consumer npm run validate vs playwrighter dogfood workflow

Consumer bootstrap (line 70) says CI should run npm run validate then npm run score, "same order as dogfood workflow." Dogfood (.github/workflows/dogfood-northwind-qa.yml lines 36–42) runs only validate-suite.sh then score-tests.js — no check-tools.js, ESLint, or typecheck. Tool ordering (suite lint before score) is consistent; pipeline equivalence is not.

Downstream consequence: Low — consumers get stricter gates than dogfood, which is desirable. Wording may confuse maintainers comparing CI matrices.

Remediation: Optional one-line qualifier: "dogfood runs the validate-suite + score subset; consumer npm run validate adds check-tools, ESLint, and typecheck."

Scorecard: S1 ✓ · S2 ✓ · S3 low · S4 trivial edit · S5 pre-existing pattern · S6 N/A · S7 P4.

---

F3 · P4 · ARC · conf 65%

Order of Operations summary vs bootstrap step numbering

The new cross-link to Consumer bootstrap helps, but the Order of Operations numbered list still reads as a parallel path without explicitly stating that tools/ must be present before first npm run validate. Bootstrap step 3→4 makes this clear; summary list does not.

Downstream consequence: Minimal — check-tools.js fails fast with copy instructions if tools/ is missing.

Scorecard: S1 ✓ · S2 ✓ · S3 low · S4 optional doc tweak · S5 nit · S6 N/A · S7 P4.

Merge recommendation

Merge. The enforcement map and consumer bootstrap materially improve SDK consumability and are factually aligned with tooling source. Address F1 (Quick Setup path drift) in a follow-up PR to avoid two conflicting onboarding paths.

---

Posted by _sdk_verify_and_pr.sh after _sdk_trainer_codereview.sh. Merge still requires CI green and human review; BLOCK / REQUEST_CHANGES (with SDK_CODEREVIEW_STRICT=1) stop the hook before push.