@penpair/web 0.3.0 → 0.3.1

package/README.md

@@ -51,9 +51,14 @@ Install one command package: `@penpair/web`, or `@penpair/docker` for a local in
 | [penpair-setup](packages/core/skills/penpair-setup/SKILL.md) | Connect or repair project setup |
 | [penpair-design](packages/core/skills/penpair-design/SKILL.md) | Inspect and operate on a design file |
 | [penpair-recipes](packages/core/skills/penpair-recipes/SKILL.md) | Compose a page with reviewed recipes |
-| [penpair-handoff](packages/core/skills/penpair-handoff/SKILL.md) | Implement from design evidence and compare |
+| [penpair-handoff](packages/core/skills/penpair-handoff/SKILL.md) | Map components and implement from design evidence |
+| [penpair-verify](packages/core/skills/penpair-verify/SKILL.md) | Compare the real frontend, inspect images and recheck fixes |
 | [design-judgment](packages/core/skills/design-judgment/SKILL.md) | Assess page structure and hierarchy |
 
+Check a consumer's Codex installation with `pnpm exec penpair skills check --json`.
+[Discovery diagnostics and behavior trials](docs/skill-validation.md) explain what
+that establishes and how to verify actual skill use.
+
 [Cookbook](docs/cookbook.md) · [MCP tools](docs/mcp.md) · [Format contracts](docs/formats.md) · [Compatibility](docs/compatibility.md) · [Recovery](docs/recovery.md) · [Living checklist](docs/improvements.md)
 
 See [CONTRIBUTING](CONTRIBUTING.md), [SECURITY](SECURITY.md), [release steps](docs/releasing.md), [CHANGELOG](CHANGELOG.md) and the [MIT licence](LICENSE). Comparison metrics supply evidence for review; they do not approve a design.

package/docs/adapters.md

@@ -39,10 +39,11 @@ First check your installed command version:
 pnpm exec penpair --version
 ```
 
-For a project already on **0.2.0**, install the matching companion:
+For example, a project whose command/core are **0.3.0** installs this matching
+companion. Use the actual installed version when it differs:
 
 ```sh
-pnpm add -D -E @penpair/reflection-check@0.2.0
+pnpm add -D -E @penpair/reflection-check@0.3.0
 ```
 
 Use the version printed above when it differs. In a pnpm workspace, use the existing dependency location (`-w` when installing at the workspace root). Upgrade directly installed Penpair packages together rather than mixing releases.
@@ -72,7 +73,13 @@ pnpm exec penpair reflection check --map design/implementation-cases.json --prov
 
 Use the [package reference](https://github.com/niklas-westman/penpair/blob/main/packages/reflection-check/README.md) for mapping/provider examples. Exit **0** means complete evidence within threshold, **2** means measured drift and **3** means missing/incomplete evidence. An install, a passing setup check or a stub provider is not a completed frontend comparison.
 
-The shared browser-provider starter is planned work. Until it ships, configure a real project provider or explicitly report that integration as pending. For simple legacy route/viewport checks, the existing generated `reflection-cases.json` and `visualSmoke` configuration remain available; richer cases require explicit setup and readback.
+The browser-provider starter ships with the command package; supply real project
+hooks or report integration as pending. The shipped
+[penpair-verify skill](../packages/core/skills/penpair-verify/SKILL.md) guides
+comparison, image inspection, implementation fixes and recapture. For simple
+legacy route/viewport checks, the existing generated `reflection-cases.json` and
+`visualSmoke` configuration remain available; richer cases require explicit setup
+and readback.
 
 ## Why explicit companions?
 

package/docs/conventions/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":templates/conventions.test.ts",{"duration":5.28132800000003,"failed":false}]]}
+{"version":"3.2.4","results":[[":templates/conventions.test.ts",{"duration":3.757374000000027,"failed":false}]]}

package/docs/plans/skill-workflow-readiness.md

@@ -0,0 +1,178 @@
+# Codex skill workflow readiness
+
+Created and last updated: 2026-10-23. Branch: `codex/skill-workflow-readiness`.
+Status: offline implementation complete. Current step: owner branch review and
+the separately pending acceptance trials below.
+
+## Living document
+
+Check an item only in the change that implements and verifies it. Commit each
+completed step before proceeding. Add a completion entry stating what changed,
+what it resolved, verification and remaining limits. Record newly discovered work
+and keep live acceptance unchecked until it actually runs.
+
+## Objective and evidence
+
+Make Penpair's skills easier for Codex to select and follow when working with
+Penpot designs, approved references and frontend comparison. Tradient's 0.3.0
+trial showed that skills were loaded but their design guidance was underapplied.
+Discovery, visible selection, evidence quality and human acceptance are separate.
+
+The installed skills are valid in `.agents/skills`; relative symlinks work.
+Codex selects implicitly from descriptions; optional `agents/openai.yaml` is not
+a prerequisite. Official reference: [Codex skills](https://developers.openai.com/codex/skills/).
+
+## Discovered project context
+
+| Area | Existing implementation / validation |
+| --- | --- |
+| Workspace | pnpm 10.12.1, six packages under `packages/`, all at 0.3.0 |
+| Skill sources | `packages/core/skills/` |
+| Installation / instructions | `packages/core/src/skills.ts`, `skill-instructions.ts` |
+| CLI | `packages/core/src/cli-main.ts`; versioned result envelopes |
+| Tests | Vitest; `packages/core/test/skills.test.ts`, `skill-instructions.test.ts` |
+| Style / full check | `pnpm format`, `pnpm check` |
+| Packaging | `pnpm smoke:package`; installs real tarballs in empty projects |
+| CI | `.github/workflows/ci.yml`, full check plus package smoke |
+
+## Boundaries
+
+- Neutral core and shipped skills; project/library knowledge stays in adapters
+  and consumer-owned facts. Preserve public imports and approval schemas.
+- Preserve owner instructions outside the installer-owned block, partial skill
+  installs, modified skill files and project-owned facts.
+- Skill selection grants no extra write permission. Preserve pinned targets,
+  positive independent readback, immutable approved baselines and owner approval.
+- Diagnostics are offline and read-only. They cannot prove what a Codex session
+  loaded, predict its selection, inspect credentials or certify design quality.
+- No version bumps, publication, merge or live Penpot writes in this work. The
+  owner authorized pushing the completed branch and opening its PR on 2026-10-23.
+- Writer-marker recovery, repeated archive flags, bounded state-variant runtime
+  operations and performance instrumentation remain separate feedback work.
+
+## Checklist and acceptance
+
+- [x] **S1 · Route tasks from generated instructions (P1).** Add concise,
+  actionable task-to-skill routing inside the owned instruction block. Include
+  only installed/selected skills, preserve custom text and relative links, and
+  load the applicable skill before tool work. Verify partial installs, nested
+  destinations, dry-run, repeated updates and existing preservation tests.
+- [x] **S2 · Improve skill selection descriptions (P1).** Use ordinary Penpot,
+  approved-design, state-variant and frontend requests with clear boundaries.
+  Validate frontmatter, names, packaged references and neutral content. Do not
+  claim that metadata validation proves model behavior.
+- [x] **S3 · Ship a focused verification skill (P1).** Add `penpair-verify` for
+  real frontend comparison, screenshot inspection, bounded fixes and reruns.
+  Route from design/handoff and retain separate readiness/approval stages. Fix
+  contradictory starter guidance. Verify installation and package enumeration.
+- [x] **S4 · Record comparative evidence before expansion (P1).** Add a reusable
+  project-owned checkpoint format and skill workflow for source evidence,
+  preserved/changed regions, a representative candidate, consequential findings,
+  next action and review status. Missing evidence must remain pending. Whole-page
+  pixel equality is unsuitable for intentionally different states. Verify the
+  example, reference paths and reuse through the installed skill pack.
+- [x] **S5 · Diagnose discovery and exercise realistic requests (P2).** Add
+  read-only `skills check` diagnostics for discoverable files, metadata, links
+  and project routing, with explicit limits. Cover missing, malformed, dangling,
+  divergent and disabled implicit invocation cases. Supply a reproducible prompt
+  trial matrix and record actual results separately from unevaluated fresh-model
+  trials. Test CLI results and ensure no connection/adapter execution or writes.
+- [x] **S6 · Make selected skills visible and finish review (P2).** Add useful
+  Codex display metadata/example prompts and a concise selection announcement.
+  Keep implicit invocation enabled. Validate metadata and installed copies; run
+  full checks and all package smoke installs. Record final results and limits.
+
+## Validation and failure protocol
+
+For each step, run the relevant existing tests plus meaningful regressions for
+changed runtime behavior. Run `pnpm format` and `pnpm check` before committing
+implementation. Run package smoke for the new skill and final package boundary.
+Docs/metadata checks validate syntax, resources and preservation; they do not
+substitute for observing a model handling a real request.
+
+If a check fails, repair that step before checking its box. If live evidence or
+an owner decision is unavailable, preserve the pending item and continue only
+independent authorized work. Do not weaken guards or simulate owner approval.
+
+## Live acceptance
+
+- [ ] Fresh Codex sessions: ordinary requests select the appropriate installed
+  skill and produce the required artifacts; record the actual loaded files.
+- [ ] A representative approved-reference variant is visually critiqued before
+  expansion; owner reviews the result in a disposable authorized Penpot file.
+- [ ] A consumer's implemented route completes real Reflection comparison with
+  approved references and independently observed browser state.
+
+Live trials remain pending by owner instruction. No extra agents or API-backed
+evaluation will be started without the required authorization.
+
+## Completion reports
+
+- **PR handoff authorized · 2026-10-23.** Owner requested the branch push after
+  the final readiness review. Local validation remains complete and main's SHA
+  matches the reviewed base. Remote CI and owner merge review remain pending;
+  no publication or live acceptance is implied by opening the PR.
+
+- **S6 completed · 2026-10-23.** Added Codex names, concise UI descriptions and
+  explicit starting prompts for all six skills, retaining implicit invocation.
+  Generated instructions ask for a brief selection announcement without treating
+  it as verification. Metadata parsing and installation checks pass; final package
+  smoke proves that metadata, checkpoint assets and `skills check` work from real
+  installed tarballs. Reviewed scope, neutral boundaries, preservation, approval
+  rules, local-command guidance and release notes. Final `pnpm check` passes
+  **680 package tests + 3 convention tests**; all six package smoke installs,
+  whitespace and exact-base PR release-note checks pass. Changesets proposes a
+  patch for all six packages; every actual version remains **0.3.0**. No push,
+  version bump, merge, publication, consumer modification or live Penpot write
+  occurred. Fresh-model and live acceptance remain unchecked above.
+
+- **S5 completed · 2026-10-23.** Added offline `skills check` with versioned CLI
+  results: valid project discovery/routing returns 0; incomplete readiness returns
+  3. Fourteen regressions cover partial and nested installs, instruction symlinks,
+  missing/malformed/oversized inputs, dangling/external links, conflicting copies,
+  modified files, disabled policy, resources, stale routes, no writes/extension
+  execution and no raw link-content echo. Added a nine-request natural-language
+  trial matrix and retained observed baseline skill reads separately from pending
+  fresh-model trials. A read-only Tradient check correctly reports its older
+  catalog-only routing and absent verification skill; no consumer files changed.
+  Full checks pass (679 package tests + 3 convention tests). Session selection,
+  global configuration and live visual quality are explicitly outside diagnostics.
+
+- **S4 completed · 2026-10-23.** Added a shared visual checkpoint template and
+  source/candidate review procedure, routed through design, recipes, handoff and
+  verification. It records preserved regions and intended changes, actual images,
+  consequential findings, readiness and next action. Missing evidence blocks
+  expansion in the skill workflow; no runtime command claims to measure taste or
+  attest that an image was seen. Full checks pass (665 package tests + 3 convention
+  tests), packaged links resolve, and a disposable install proved that a copied
+  project-owned checkpoint survives forced skill refresh. Live critique remains
+  pending.
+
+- **S3 completed · 2026-10-23.** Shipped `penpair-verify` as the sixth consumer
+  skill, with ordinary parity/fix triggers and design/handoff routing. It records
+  actual browser readiness, inspects images and recaptures scoped fixes without
+  changing references or granting approval. Corrected both stale claims that the
+  browser starter was still planned. Full checks pass (665 package tests + 3
+  convention tests); all six package smoke installs pass and the installed Codex
+  link resolves the new skill. Consumer browser/owner acceptance remains pending.
+
+- **S2 completed · 2026-10-23.** Front-loaded everyday task descriptions now
+  distinguish design operations, state construction, design judgment and frontend
+  implementation. Replaced the installer's line regex with bounded YAML data
+  parsing so quoted/folded descriptions work and malformed or mismatched metadata
+  fails clearly. Reused the workspace's pinned YAML version as a core dependency.
+  Full checks pass: 665 package tests plus 3 convention tests, including 9 metadata
+  and packaged-resource checks. No fresh-model selection claim is made.
+
+- **S1 completed · 2026-10-23.** Generated instructions now route matching tasks
+  to selected skills before tool work instead of presenting only a directory.
+  Partial installs emit no routes to unselected skills; nested encoded links
+  resolve, repeat installation is unchanged and owner text is preserved. Full
+  `pnpm check` passes: 656 package tests plus 3 convention tests. Selection and
+  correct application by a fresh model remain live acceptance, not a claim of
+  the installer.
+
+- **Plan prepared · 2026-10-23.** Created the branch from merged main and mapped
+  all six proposed improvements to acceptance criteria and verification. The
+  prior release cleanup is merged and its continuation workflow succeeded;
+  package versions remain 0.3.0. No skill implementation has been checked off.

package/docs/skill-installation.md

@@ -11,6 +11,27 @@ Without `--agents`, exactly one existing AGENTS.md or CLAUDE.md is selected. If
 
 The installer appends a skills section when needed or replaces only the contents between `<!-- penpair:skills:start -->` and `<!-- penpair:skills:end -->`. Existing text outside the owned region, including line endings, is preserved. Duplicate, reversed or unmatched markers stop installation before any skill files are written. An instruction file edited after planning is preserved; retry after reviewing its current contents. A repeat run with identical content is a no-op. Existing file permissions are retained.
 
+The owned block includes task-to-skill routing as well as a skill directory. It
+instructs the agent to read the relevant skill before tool work, and follows the
+selected skills when `--only` is used. Installation does not guarantee that a
+particular model will select or correctly apply a skill, and selecting a skill
+grants no additional write permission.
+
+Run `penpair skills check --json` for read-only Codex discovery/routing diagnostics
+after a reviewed installation. Use repeated `--only NAME` for a partial install
+and `--agents PATH` for its selected instruction destination. See
+[skill validation](skill-validation.md) for results, limits and realistic model
+invocation trials. Filesystem readiness does not prove correct agent behavior.
+
+Bundled `agents/openai.yaml` files provide readable skill names, descriptions and
+explicit starting prompts for Codex. Implicit invocation remains enabled; the
+metadata is optional for discovery. Generated project instructions ask the agent
+to briefly name the selected skill and its purpose. This makes intended use
+visible without claiming a host-specific badge or completed verification. If a
+new skill is absent from the host's available-skill list, check discovery first;
+Codex normally detects changes automatically, with a restart as a fallback when
+an update does not appear. See [official skill documentation](https://developers.openai.com/codex/skills/).
+
 Local outputs must remain inside the project after resolving existing symlinks. An instruction link escaping the project or a dangling link is refused. The resolved destination is shown so a project wrapper or shared in-project target is visible. These operations do not edit global agent configuration. Entry-point/output checks do not sandbox arbitrary extensions.
 
 Skill files modified by the project are kept unless `--force` is explicit. Project facts remain project-owned even with force, and rename migration preserves the prior facts. All writes are planned before execution, published as complete files, and instructions are written after skill copies/links. This is not a multi-file transaction: a filesystem failure or a concurrent owner edit can leave skill installation partly applied while preserving the instruction file. Review the report and rerun; unchanged files are skipped.

package/docs/skill-validation.md

@@ -0,0 +1,86 @@
+# Validate skill discovery and behavior
+
+Installation, selection, workflow application, browser evidence and owner
+acceptance are separate checks. Codex can load a skill without showing the
+selection in the way a person expects, and can read a skill but underapply it.
+
+## Offline discovery
+
+```sh
+pnpm exec penpair skills check --json
+pnpm exec penpair skills check --only penpair-verify --agents AGENTS.md --json
+```
+
+Exit 0 means the selected bundled skills have valid discoverable entrypoints,
+allowed implicit invocation, resolvable local entrypoint resources and matching
+links in the installer-owned task routes. Exit 3 means readiness is incomplete;
+exit 1 indicates invalid arguments or an execution/configuration error. `--only`
+can be repeated. Default selection is all bundled skills; partial installs should
+select their intended subset explicitly.
+
+The report distinguishes entrypoints matching the bundle from valid local
+customizations. Different independent installed copies require review. Missing
+optional `agents/openai.yaml` means implicit invocation is allowed by default;
+an explicit false policy leaves explicit invocation available. The check reads
+bounded regular project files, follows in-project links and refuses escapes.
+It does not load adapters/providers, connect to Penpot, read credentials, write
+repairs or inspect global agent settings.
+
+The instruction check recognizes Penpair's generated owned task routes. It does
+not interpret arbitrary custom routing prose. Preview updates with
+`skills install --agents AGENTS.md --dry-run`, preserve intentional customizations
+and project-owned facts, then apply the reviewed refresh. Diagnostics do not
+override owner choices or silently enable disabled skills.
+
+## Realistic invocation trials
+
+Run these in fresh Codex sessions in an authorized disposable consumer project.
+Do not append skill names to the natural request. Supply actual reference IDs,
+images, approved scope and case files where the task needs them. For a negative
+case, keep Penpot/provider work out of scope. Each trial uses the same fixture and
+records the actual outcome, including missing skills or unavailable tools.
+
+| Natural request | Expected primary skill | Observable result |
+| --- | --- | --- |
+| Connect this project to Penpot; doctor cannot reach the editor. | penpair-setup | Diagnose the failed check; preserve personal credentials. |
+| Inspect this Penpot frame and export its current design. | penpair-design | Pinned target, complete inspection and actual export. |
+| Create an empty state from this approved Penpot screen. | penpair-recipes | Source evidence, declared regions, representative candidate and critique before expansion. |
+| Implement this approved Penpot design in the frontend. | penpair-handoff | Explicit component mapping/unknowns and routed verification readiness. |
+| Compare this running route with its approved design and fix the visual mismatches. | penpair-verify | Actual case setup/readback, screenshots, findings, scoped fixes and rerun. |
+| Critique this screen's density and hierarchy. | design-judgment | Consequential findings grounded in the supplied image; no implicit Penpot writes. |
+| Fix a backend calculation with no UI change. | none of these | No Penpot or comparison work added. |
+| Explain this repository's release workflow. | none required | No design/browser workflow started. |
+| Explain what Reflection Check does; do not run anything. | none required | Explanation respects the requested scope; no provider execution. |
+
+For each case retain: request/context, visible skill catalog if available, actual
+SKILL.md reads, selection announcement, relevant output/checkpoint, command
+results and missing evidence. Record correct selection and correct application
+separately. A badge, a stated intention, a keyword match or valid YAML proves
+neither. If natural selection fails, repeat with explicit `$skill-name` to
+distinguish discovery/selection from problems following the workflow. Record the
+installed skill version; compare before/after under the same conditions.
+
+Do not run live writes just to measure invocation. A read-only plan can establish
+selection; authorized scratch trials establish mutation and visual behavior.
+Missing tools, design references, browser providers or owner approval remain
+pending instead of simulated success.
+
+## Results retained for this branch
+
+- Baseline evidence: the earlier consumer conversations **Investigate Coinbase
+  futures setup** and **Upgrade Penpair and run trial** contain actual reads of
+  design/recipe/handoff skills and selection announcements after ordinary user
+  requests. This establishes prior use, not correct application or new-version
+  performance. No raw private conversation logs are copied into the repository.
+- Automated tests cover successful and partial discovery, nested links, absent
+  files, malformed/oversized metadata, dangling/external links, conflicting copies,
+  preserved customization, disabled policy, missing resources and stale routing.
+  CLI results retain versioned envelopes and extension code remains unexecuted.
+- [ ] Fresh-session trials of the changed skill pack: pending.
+- [ ] Authorized live variant critique and real consumer browser comparison:
+  pending by owner instruction.
+
+The [living implementation checklist](plans/skill-workflow-readiness.md) records
+completed implementation, commands and remaining acceptance work. See
+[official Codex skill documentation](https://developers.openai.com/codex/skills/)
+for supported discovery locations, implicit selection and optional metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@penpair/web",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The penpair command for Penpot on the web (design.penpot.app or your team's own): guided setup, a safe write protocol, skills for AI agents. Includes everything in @penpair/core.",
   "license": "MIT",
   "repository": {
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@penpair/core": "0.3.0"
+    "@penpair/core": "0.3.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",