@penpair/core 0.3.0 → 0.3.3

package/skills/penpair-verify/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: penpair-verify
+description: Verify a frontend against an approved Penpot design using Penpair Reflection Check. Use to check visual parity, investigate design mismatches or recheck an implementation after fixes with real browser screenshots and observed application state.
+---
+
+# Frontend verification
+
+Compare the real implementation with the exact approved design case. Use the
+project's configured browser provider and component library. A captured design,
+an installed adapter and a passing build each establish different facts.
+
+Continue the project's existing comparative checkpoint, or create a project-owned
+case report outside installed skill folders. Retain source/candidate identities,
+preserved and changed regions, actual image paths, observed setup, consequential
+findings and the next action. If `penpair-recipes` is installed, its
+`references/visual-checkpoint.md` and template supply the common format.
+
+1. **Establish readiness.** Inspect the installed command and adapter versions,
+   the project's existing verification scripts, approved reference and explicit
+   case mapping. Use the local command (`pnpm exec penpair` in pnpm projects).
+   Report installed, registered, references approved, cases mapped, provider
+   configured, browser verified and owner reviewed separately. Keep unavailable
+   stages pending; do not invent approval or replace an unimplemented setup.
+2. **Plan the case.** Run `penpair reflection plan --map FILE`. Confirm the
+   reference identity/hash and intended route, viewport, theme, state, fixture and
+   fonts. Start with one representative case before expanding the matrix. For
+   browser evidence requirements, read [browser-evidence.md](references/browser-evidence.md).
+3. **Run the real browser.** Start or reuse the authorized local application and
+   run `penpair reflection check --map FILE --provider FILE`. The project module
+   must activate and independently observe the requested application state.
+   Exit 0 means complete evidence within thresholds; 2 means measured drift;
+   3 means incomplete evidence. An execution error establishes no comparison.
+4. **Inspect and repair.** Look at the approved image and actual browser image;
+   inspect a diff image when the checker produces one. Record consequential
+   findings as location, impact, evidence, proposed fix and rerun case. Fix
+   implementation mismatches within scope, then recapture affected cases. Do
+   not overwrite approved references, change case intent or loosen thresholds
+   merely to pass. A design change goes back through design review and approval.
+5. **Checkpoint and report.** If repeated failures or substantial tooling work
+   prevent a representative visual result, report the evidence and revised
+   approach before expanding tools or cases. Retain case IDs, image paths,
+   findings and the next action so another agent can continue. Report **Changed**,
+   **Validated**, **Risks**, separating comparison, visual critique, accessibility
+   checks and owner approval. A low pixel ratio does not establish any of the last
+   three.
+
+For a new implementation or missing component mapping, use `penpair-handoff` when
+installed. For Penpot changes, use `penpair-design` when installed and retain the
+project's write protocol. Reading a skill never authorizes an extra live write.

package/skills/penpair-verify/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Penpair Verify"
+  short_description: "Compare browser UI with approved designs"
+  default_prompt: "Use $penpair-verify to compare this running frontend with its approved design, inspect the images and recheck scoped fixes."
+policy:
+  allow_implicit_invocation: true

package/skills/penpair-verify/references/browser-evidence.md

@@ -0,0 +1,33 @@
+# Real browser evidence
+
+The optional `@penpair/reflection-check` adapter connects approved design cases to
+a trusted project module exporting `async runCase(test)`. Match its version to
+the installed command/core and preserve existing adapter entries. Read the
+[adapter guide](https://github.com/niklas-westman/penpair/blob/main/docs/adapters.md#check-the-frontend-against-the-design)
+for installation and the current provider contract.
+
+The command package ships `examples/reflection-browser/`: for a web installation,
+start at `node_modules/@penpair/web/examples/reflection-browser/README.md`. The
+starter supplies browser capture and pixel comparison plumbing. Project hooks
+still own the actual route, state setup, fixture, theme observation, capture root
+and expected fonts. The standalone Reflection application is optional; a pinned
+browser dependency and working provider are still required in the project.
+
+Before claiming a comparison, retain the case ID, approved reference/hash, setup
+name, provider identity/version and actual browser observation. Check viewport,
+theme, state, fixture, loaded fonts, PNG dimensions and scale. Missing state
+hooks, placeholder routes or echoed test inputs leave verification pending.
+Inspect pointer/hover, scroll/sticky behavior, occlusion and capture-root bounds
+when they can explain a mismatch. Do not hide them by changing the reference.
+
+Use the project's existing verification command or pass its explicit mapping and
+provider to the installed `penpair reflection` command. Providers execute trusted
+project code, not sandboxed data. Preserve approved baseline bytes before and
+after running them. Browser state and screenshots must be independently observed;
+an adapter accepts an evidence contract but cannot attest that a provider is
+honest.
+
+Keep the result and screenshots in a project-owned report. Distinguish measured
+drift, a visual finding, behavior/accessibility checks and owner acceptance.
+Design-to-design state variants need a source/candidate critique, not an
+implementation parity score against intentionally different content.