@penpair/web 0.3.1 → 0.3.4

package/docs/plans/registry-polling-fix.md

@@ -1,101 +0,0 @@
-# Registry visibility polling — 2026-10-22
-
-Branch: `codex/release-registry-polling`. Base: reviewed 0.3.0 release on main,
-`4ea9975`. Repository package versions remain 0.3.0.
-
-## Failure and evidence
-
-The [publish job](https://github.com/niklas-westman/penpair/actions/runs/39801876697/job/119904592523)
-accepted `@penpair/core@0.3.0` at 15:17:02 UTC with signed provenance. npm explicitly
-reported that processing could take a few minutes. The script exhausted twelve
-five-second visibility checks and stopped at 15:18:05 UTC. No subsequent package
-was published by that run.
-
-An independent registry check then found core 0.3.0 visible, with Docker, the token
-adapter, the comparison adapter and web still absent. This establishes a
-processing-delay failure after an accepted upload; increasing a publish timeout
-or retrying the upload is unnecessary.
-
-## Completed checklist
-
-- [x] Extract a focused post-publish visibility helper. It checks immediately and
-  then at minute intervals within a ten-minute deadline for each uploaded package.
-- [x] Count registry query time toward the deadline and report elapsed time and
-  the next check/deadline in workflow logs.
-- [x] Bound each npm metadata process and HTTP request to 30 seconds or the
-  remaining deadline, with hidden npm retries disabled.
-- [x] Retain errors for failed lookups, explicit interrupted-release continuation,
-  dependency-order publishing and the configured short-name exception. The
-  visibility helper never uploads a package.
-- [x] Add virtual-clock tests for immediate/delayed visibility, exact minute
-  cadence, query duration, ten-minute expiry, remaining query budget, late
-  observations and registry errors. Query-boundary tests cover 404, authentication,
-  network errors and killed processes without touching npm.
-- [x] Document recovery and the order of operations before merging a tooling fix.
-
-## Validation
-
-- `pnpm check`: **658 tests** pass, including 15 new polling/query tests, along
-  with builds, typechecks, style/path checks and the six-package version guard.
-- `pnpm smoke:package`: all six tarballs install and run.
-- Final polling/logging tests pass independently using virtual time. No real
-  ten-minute sleeps or npm publication were used for testing.
-- `git diff --check` passes. The empty Changeset records repository tooling work
-  and does not propose a package version bump.
-
-## Current release recovery and remaining risk
-
-- [ ] On current `main`, dispatch **Publish reviewed Penpair release** with
-  `version=0.3.0` and `continue_release=true`, then approve `npm-release`.
-- [ ] Verify all five required scoped versions and provenance. The `penpair`
-  wrapper remains explicitly excluded.
-- [x] Polling fix merged as PR #5 before recovery completed; the early-merge recovery below supersedes the original merge order.
-
-The current main workflow still has its original one-minute visibility wait. If
-another accepted upload exceeds it, inspect the registry and explicitly continue
-the same version again. Rerunning the failed push workflow does not select
-continuation automatically.
-
-Finish recovery before merging this branch: its pending Changeset would block the
-manual release gate on main. This preserves the existing guard rather than
-changing it to accommodate an interrupted release. Ten minutes is a bounded
-window, not a guarantee that npm finishes processing; a failed lookup or an
-expired deadline still stops for inspection.
-
-## Early merge recovery
-
-PR #5 was merged on 2026-10-22 as `d339a19` while the 0.3.0 release remained
-interrupted. The new minute polling is now on main. The remaining pending note
-`bounded-registry-polling` has an empty release list and requests no version bump.
-The version-PR workflow therefore created no release PR. Manual continuation is
-blocked until that metadata has been consumed.
-
-The post-merge push workflow separately hit a GitHub API HTTP 500 while reading
-associated PRs; its publish job was skipped. That API error is distinct from the
-pending-note check. Manual dispatch uses the explicit-version path.
-
-- [x] Reproduce Changesets' consumption in an isolated workspace: only the empty
-  note is removed and every package stays at 0.3.0.
-- [x] Use the same Changesets CLI operation on the cleanup branch. Confirm no
-  package manifest, source version, lockfile, script or workflow changes.
-- [x] Run the unchanged `checkReleaseCommit` and manual workflow gate against the
-  resulting tree: both accept 0.3.0 with no pending notes. No publish command runs.
-- [x] Pass style/path checks and 47 existing Changesets, release-guard, polling,
-  registry-query and documentation tests. The cleanup changes only metadata/docs;
-  the previous 658-test run and six-package smoke cover the retained polling code.
-- [ ] Review/merge the metadata-only cleanup PR and pass its CI.
-- [ ] On the resulting main, dispatch **Publish reviewed Penpair release** with
-  `version=0.3.0`, `continue_release=true`, and approve `npm-release`.
-- [ ] Verify all five scoped packages and their provenance before marking the
-  release complete; the short-name exception remains enabled.
-
-The consumed tooling note is preserved here:
-
-> Allow npm processing time after successful uploads: check visibility immediately
-> and then once per minute within a ten-minute deadline per package. Bound metadata
-> queries and retain explicit recovery for interrupted releases. This changes
-> repository release tooling only.
-
-This cleanup completes an empty metadata item through Changesets. Package release
-notes and release guards remain intact; the interrupted version remains 0.3.0,
-with core skipped by explicit continuation once independently observed on npm.

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

@@ -1,178 +0,0 @@
-# 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/plans/tradient-feedback-0.2.0.md

@@ -1,209 +0,0 @@
-# Tradient feedback: execution plan
-
-Created: 2026-10-22. Status: **phases 0–6 delivered and verified offline; final offline review complete; live Penpot gates and PP-07 causality remain open**.
-
-Goal: make the ordinary Penpair workflow complete the observed trial without a custom SDK host, then reduce the project glue needed for comparison and theme previews.
-
-Source: `feedback-0.2.0-2026-10-22.md` and its linked evidence in Tradient's `docs/penpair/`. The original report is outside this repository; phase 0 records a redacted, portable reproduction here. No consumer files are changed by this plan.
-
-## Defaults and constraints
-
-- Cover all eight findings in phases. Milestone A is reliability; milestone B is comparison and preview capability. Use `codex/tradient-feedback`, with small verified commits. Milestone boundaries permit review; they do not authorize pushes, merges or publication.
-- Live acceptance uses a dedicated disposable copy, confirmed by its public file ID. No file has been selected or authorized by this plan. Until then, implement and test offline and leave the live boxes unchecked. Do not repurpose Tradient's existing file or its other pages implicitly.
-- Keep the core neutral. Library recipes, ownership migration and library-specific previews belong in adapters. Tradient's screen, trading data and theme names remain consumer-owned.
-- Retain file pins, one-shot writes, independent readback, uncertain journals and exact-artifact approval. Geometry stability is not pixel approval, font readiness or native component parity.
-- No token changes, native component generation, whole-file restore claim, two-person acceptance claim or edits to the adopting application are implicit in this work.
-- Preserve compatible public interfaces and result envelopes. Add optional evidence fields rather than renaming existing fields or changing their meaning. New commands/options require matching help, schemas where applicable, and negative parsing tests.
-- Use Changesets for release notes. All six repository package versions move together; the existing publishing exception may still skip only the unscoped wrapper. Do not bump versions during implementation.
-
-## Repository and validation
-
-Baseline inspected: `main` at `57f9782`, all six packages at **0.2.0**. pnpm **10.12.1**, TypeScript **5.6.3**, Vitest **3.2.4**. Tests live in each package's `test/` directory. There is no repository lint script.
-
-| Purpose | Command |
-| --- | --- |
-| Build, types, tests and package-version/config rules | `pnpm check` |
-| Six tarballs installed and exercised in clean consumers | `pnpm smoke:package` |
-| Fast version/config guard | `pnpm check:versions` |
-| Targeted regression | `pnpm --filter PACKAGE exec vitest run test/FILE.test.ts` |
-| Whitespace | `git diff --check` |
-
-Run the relevant targeted suite while developing each phase, then `pnpm check` before committing it. Run package smoke after changes to shipped commands, adapters, skills/examples or dependencies and at final handoff. Do not substitute fake-provider tests for a real-browser acceptance result.
-
-Planning validation (2026-10-22): 73 existing targeted tests passed across core, adapter and comparison packages; the version/config guard, local document links and single-Now rule passed. Full `pnpm check` and package smoke were not rerun for this documentation-only change. These baseline results do not verify the proposed fixes or any live acceptance gate.
-
-### Completion protocol
-
-Check a task only when its stated output is built and verified. Record offline and live status separately. Keep exactly one `Now` in `PLAN.md`; update it and the change log with each completed phase. If evidence changes the diagnosis, update this guide before implementing a different solution.
-
-After every phase, append a report below with **Resolved / Changed / Validated / Risks / Next**, date, commit, commands/results, and links to reviewed evidence. For investigations, distinguish **investigated** from **resolved**. A blocked live check never becomes a passing checkbox through elapsed time or synthetic evidence.
-
-## Milestone A — reliable default workflow
-
-### Phase 0 — reproduce and preserve the baseline
-
-- [x] Record the feedback version, package/agent/runtime versions and the relevant reproduction sources. Extract only credential-free minimal fixtures; do not copy the whole consumer runner or unreviewed logs.
-- [x] Run the existing layout/kit, migration, doctor, coordination and structural-snapshot suites. Record pre-existing failures separately.
-- [x] Add failing regressions before behavioral changes: native wait times out while geometry is stable; metadata-only snapshot migration; delayed own-lease save versus a real external edit; page switching delayed past the initial read.
-- [x] Prepare a public-ID-only scratch fixture manifest with two pages, one flex/text/token example and expected preservation checks. Keep credentials and private journals ignored.
-
-Tests: core `settle-integration.test.ts`, `kit.test.ts`, `external.test.ts`, `coordination.test.ts`, `journal.test.ts`, `structure-snapshot.test.ts`; adapter `migration.test.ts`, `commands.test.ts`.
-
-Exit: the confirmed layout and migration failures reproduce in controlled tests. PP-07/08 fixtures state which behavior is confirmed and which causal claim still needs live tracing. Lack of a live target does not prevent phase 1.
-
-### Phase 1 — bounded layout fallback (PP-01, P1)
-
-Entry points: `packages/core/src/layout.ts`, `kit-source.ts`, operation settling and stable export callers.
-
-- [x] Extend `LayoutOptions` and kit `settle`/`flush` options with `strategy: auto | native | geometry`, default `auto`. Add `--layout auto|native|geometry` to `run-file`, `export` and `shots`; omit any unverified `off` mode. Existing SDK `layout:false` stays an explicit advanced-caller contract, not a suggested CLI workaround.
-- [x] Use one shared policy definition for host and kit behavior. Preserve existing total deadlines; cap an automatic native attempt at the smaller of **500 ms** and **one quarter of the remaining budget**. Leave time for geometry fallback rather than spending the full deadline on native waiting.
-- [x] In `auto`, fall back after an unsupported native API or an observed native wait failure when execution and target identity remain valid. A lost transport response, cancellation, changed target, malformed data or exhausted budget must not become success or trigger a write replay.
-- [x] Require three consecutive complete, equal geometry samples in geometry mode, with stable IDs/hierarchy and finite measurements; use the existing host/kit poll intervals. Duplicate IDs, cycles, truncation and node-budget excess refuse. In `native`, propagate native failure without fallback.
-- [x] Add optional attempt diagnostics to `LayoutResult`: selected strategy, native outcome, fallback reason and elapsed time. Preserve `stable`, `method` and `samples` meanings. Report verification failure after a partial flush through the existing journal/readback path.
-
-Tests: successful native path; unsupported/timed-out native with stable geometry; continually moving geometry; malformed/truncated samples; changed file/page; cancellation/deadline; bindings recorded only after valid settling; equivalent host/kit policy; CLI option rejection; stable PNG export still requires independent matching renders.
-
-Exit: core `native-api`, `settle-integration`, `kit`, `kit-integration`, `run-file`, `export` and `shots` tests pass, followed by full checks/package smoke.
-
-- [ ] **Live acceptance:** the shipped CLI and kit build the small scratch example, verify actual bindings and produce two stable exports without a consumer SDK runner. Repeating retains owned IDs and adds no duplicates. Look at the images; record native/fallback evidence.
-
-### Phase 2 — explain upgrades and prove readiness (PP-02/03, P2)
-
-- [x] Add additive snapshot-check reason codes for missing snapshot, schema migration, missing ownership, content drift and metadata/hash mismatch. A stale result must always include a reason, even when the value diff is identical. Preserve stale/error exit-code distinctions.
-- [x] Reuse the existing `tokens migrate --from FILE --ownership FILE` preview and `--out NEW_FILE` write path. Diagnostics must point to that workflow, explain the schema change and request explicit classification of every legacy set. Do not invent ownership or regenerate away original provenance.
-- [x] Strengthen the existing doctor execution read rather than creating a duplicate readiness command. Add `doctor --timeout-ms N`, default **5000 ms**, valid **1000–30000 ms**, bounding origin, connection and execution work with cancellation.
-- [x] Generate a fresh challenge for the editor to echo with file/page identity. Report origin reachability, transport connection, fresh execution and file-pin match separately, with observed time/duration. Only measured layers may be healthy; unavailable heartbeat/version evidence stays unknown. Extend existing doctor JSON checks additively and keep endpoint redaction.
-
-Tests: adapter `migration`, `commands`, `command-contract`; core `external`, `connect`, `http-client`, `command-result`. Include old schema with unchanged values, missing ownership, invalid map, preserved provenance, stale challenge, wrong file, sleeping editor, timeout and secret-bearing failure text. Migration must require no live connection.
-
-Exit: the retained schema-1 fixture explains its failure and migrates without value/theme/provenance loss; doctor cannot report unqualified readiness from stale or incomplete execution evidence.
-
-- [ ] **Live acceptance:** compare responsive, foregrounded and deliberately disconnected scratch-editor states. Verify a new challenge and useful bounded failure messages. Do not deliberately interrupt a mutation for this test.
-
-### Phase 3 — coordination evidence and page-aware snapshots (PP-07/08)
-
-- [x] Add redacted optional journal trace events around lease acquisition/check/release, inspection and observed revisions. Record source identities and timing without credentials, document text or whole catalogs in logs.
-- [x] Reproduce delayed lease persistence separately from external shape/token edits. First make no-op/reconciliation behavior observable; do not replace guards with sleeps or automatically ignore revision differences.
-- [x] **PP-07 decision gate:** if causal attribution is proven, fix the ordering of lease acquisition, target capture and inspection so the operation starts from its own independently read post-acquisition revision, while preserving conflict detection during inspection and before mutation. Test an external edit in each interval. If attribution remains unproven, deliver tracing/reproducer and retain PP-07 as unresolved; changing revision policy then requires a separately reviewed plan amendment.
-- [x] Replace the fixed page-switch sleep in `runOnPage` with bounded polling of the expected page ID: default **5000 ms**, **100 ms** intervals, limited by the enclosing command's remaining budget. Resolve a unique name once to an ID. A timeout identifies expected/observed page and stage.
-- [x] Serialize page-sensitive work on the same client through a shared page-session mechanism. Whole-file snapshots hold that session for the collection, capture pages sequentially, and restore the original visible page in `finally`. Unexpected external navigation causes a clear failure rather than silent mixing.
-- [x] Record per-page progress and timings. Preserve the original snapshot manifest on failure; diagnostic partial observations must never be assembled across revisions or published as a complete snapshot. Keep the original error if restoring the visible page also fails, and report both.
-
-Tests: core `coordination`, `journal`, `operation-recovery`, `operation`, `inspection`, `structure-snapshot`; add delayed page-switch and concurrent same-client collector tests. Include duplicate page names, removed pages, manual navigation, mid-capture file/token edits, deadline exhaustion and restoration after failure.
-
-Exit: multi-page fixtures succeed sequentially with correct identities and restore their starting page; failures preserve prior artifacts and identify the exact failed stage. PP-07 is either causally fixed with safety regressions or explicitly still unresolved.
-
-- [ ] **Live acceptance:** idle sequential operations, a controlled external scratch edit and a two-page snapshot. Confirm preservation of token definitions/order, global theme selections and unrelated objects.
-
-### Phase 4 — help and composition guidance (PP-06, P3)
-
-- [x] Adapter-discovery slice: promote both companion roles in the README/setup guides and recommend the comparison adapter in shipped setup/handoff skills, with distinct installation and browser-readiness stages. This independent documentation slice does not complete the runtime help/composition work below.
-
-- [x] Group installed help around connect/diagnose, build, inspect/spec, snapshot/diff, capture/approve and compare. Include examples of actual installed syntax and link to limitations; do not invent new aliases merely to reorganize help.
-- [x] Add a short pre-build composition checklist to the design/recipe skills: primary user task, chosen existing reference, hierarchy, useful context, responsive/focus order, and a small first-frame critique before expanding variants. This records a design decision; it does not manufacture owner approval.
-- [x] Document migration previews, settling modes, doctor layers and snapshot recovery; remove suggestions to work around these with arbitrary waits.
-
-Tests: core `docs`, `skill-instructions`, `skills`, CLI help assertions and installed-package smoke. Verify instructions survive idempotent installation and no project names enter the neutral core.
-
-Exit: the inspect → spec → snapshot/diff → comparison path is discoverable from installed help; one trial can follow documented commands without reading package source.
-
-## Milestone B — reduce consumer integration work
-
-### Phase 5 — real browser comparison starter (PP-05, P2)
-
-- [x] Add a neutral example provider under `examples/reflection-browser/` for the existing `ImplementationProvider.runCase` contract. Use the adopter's pinned Playwright installation; no browser dependency or application framework enters the core. Ship it with the existing web documentation/examples mechanism and verify the installed path.
-- [x] Require project hooks for route, fixture, theme, state, capture root and expected fonts. Read actual state and loaded font faces/weights; never echo requested inputs as observed evidence.
-- [x] Park the pointer outside the capture region and verify no relevant hovered controls. Capture with explicit viewport, device scale **1** by default and a root bounding box after scroll/sticky layout settles. Round the box outward to whole CSS pixels and record the rule; do not resize images to improve a metric.
-- [x] Preserve the current schema-1 provider fields. Add optional capture metadata for root/clip, scale, browser version, font evidence and pointer checks; old providers remain readable. The example requires its complete metadata and flags missing evidence instead of substituting defaults silently.
-- [x] Validate paths/hashes and compare through the existing adapter. Retain `owner-review-required`; a pixel score never approves a baseline. Unapproved trial captures may test the capture helper, but the approval gate for `reflection check` stays intact.
-
-Tests: adapter `integration.test.ts` plus new provider/capture fixtures for wrong state/theme, delayed/missing fonts, hover contamination, sticky shell, fractional crop boundaries, unchanged baseline bytes and dimension/scale mismatch. Exercise a real local example in the browser at desktop/mobile × light/dark × loaded/empty; unit stubs alone do not complete this phase.
-
-Exit: an adopter can supply explicit setup hooks and run a genuine comparison without rewriting capture plumbing. No Tradient route/provider is registered by modifying its repository here.
-
-### Phase 6 — explicit, isolated theme previews (PP-04, P2)
-
-- [x] Record the pinned API's frame-level theme capabilities with links and observed proof. Do not expose native per-frame binding as supported based on an API name or projected appearance.
-- [x] Deliver a deterministic offline preview first: neutral token-projection logic plus adapter command `penpair marwes tokens preview --from SNAPSHOT --theme NAME [--out FILE]`. Resolve the selected declared theme using existing token precedence/alias rules; ambiguous names, missing dependencies or unsupported values produce errors/explicit unknowns.
-- [x] Return a versioned preview with source hash, selected theme/set identities, resolved values/unknowns and `kind: projected-theme-preview`. `--out` writes only a project-bound artifact. It does not mutate Penpot, switch global themes or imply native bindings.
-- [x] Supply a scratch example applying projected color values to owned roots, with projection metadata retained separately from actual typography/spacing/radius bindings. Native frame-mode support remains a separate acceptance gate if it cannot be proved on the pinned version.
-
-Tests: adapter preview/command-contract tests and neutral resolver tests: multiple themes, ordering, aliases/cycles, composite values, ambiguous names and missing values. Before/after scratch checks must show identical global selections, catalog values/order and unrelated objects.
-
-Exit: simultaneous light/dark preview artifacts are reproducible and accurately labeled. Native component anatomy, override preservation and native per-frame color bindings remain unclaimed unless independently proven.
-
-## Final integration and release gate
-
-- [ ] Re-run the eight-case scratch trial using shipped CLI/kit paths, a repeat build and one heading change. Compare IDs, bindings, geometry, native/browser images and changed fields. Record observed timings, unknowns and interventions.
-- [ ] Confirm no consumer-side timeout bypass, fixed inter-operation sleep or fabricated provider evidence is needed for the covered paths.
-- [x] Run `pnpm check`, `pnpm smoke:package` and whitespace checks. Record the actual final test count and installed-package results; do not assume the 0.2.0 baseline count remains current.
-- [x] Add Changesets per package behavior: fixes as patch, new public options/provider/preview capabilities as minor. The generated version PR selects the highest bump for every package; no manual version bump or release activation change belongs here.
-- [x] Review the branch, evidence and remaining PP-07/native-mode/live gates; see the [branch review and acceptance checklist](tradient-feedback-review.md).
-- [ ] Obtain owner decisions before any push/PR, merge, publish or non-scratch write.
-
-If the scratch target is unavailable, code may be reviewed with live checks still pending, but the release must not claim those checks passed. No rollback or exactly-once guarantee is introduced. On an uncertain write: stop, retain the journal, inspect independently, reconcile only owned changes and resume explicitly. After repeated failure, record the trace and narrow the reproducer; never relax a guard to get a green report.
-
-## Completion tracker and reports
-
-| Phase | Status | Offline evidence | Live evidence | Completed |
-| --- | --- | --- | --- | --- |
-| 0 Baseline/reproducers | Complete offline | 587 tests; explicit expected-failure reproducers | Target pending | 2026-10-22 |
-| 1 Layout | Complete offline | 597 tests; six-package smoke pass | Pending | 2026-10-22 |
-| 2 Migration/readiness | Complete offline | 607 tests; six-package smoke pass | Pending | 2026-10-22 |
-| 3 Coordination/snapshots | Offline delivery complete; PP-07 unresolved | 614 tests; six-package smoke pass | Pending | 2026-10-22 |
-| 4 Help/skills | Complete | 615 tests; six-package smoke pass | Not applicable | 2026-10-22 |
-| 5 Browser starter | Complete | 616 tests; package smoke; 8 real-browser cases + negative cases | Local Chromium trial complete; Penpot pending | 2026-10-22 |
-| 6 Theme previews | Complete offline | 622 tests; six-package smoke pass | Scratch/native capability pending | 2026-10-22 |
-| Final trial/release review | Offline review complete; owner/live pending | 630 tests; six-package smoke; real browser matrix | Penpot target pending | 2026-10-22 (offline) |
-
-Append phase reports here during execution. Update the table and relevant `PLAN.md` checkbox in the same verified change.
-
-### 2026-10-22 — Companion discovery (phase 4 documentation slice)
-
-**Resolved:** Readers and agents can now discover why to add the library and frontend-comparison adapters, with Reflection Check recommended when implementing and verifying frontend code.
-
-**Changed:** Added a companion selection/setup/readiness guide, promoted both roles in README and onboarding docs, updated shipped setup/handoff/recipe skills and project-facts guidance, and added a matching-version registration path. Kept adapter dependencies explicit and the browser starter planned. No runtime help/composition or reliability fix is claimed by this documentation slice.
-
-**Validated:** `pnpm check` passes (583 tests), including navigation/anchors, core/skill neutrality and skill installation. All six package smoke installs pass; the command tarball includes the new adapter guide. Added patch changesets for the affected shipped packages.
-
-**Risks:** These guidance changes need the next reviewed release and skill refresh to reach existing installations. Browser verification still requires approved baseline/case evidence and a real provider; automatic bundling/setup was not added. No version bump, push, merge or publish was performed.
-
-**Next:** Phase 0 remains the runtime entry point; phase 5 supplies the real-browser starter. Phase 4's help/composition tasks remain unchecked.
-
-### Phase 0 report — 2026-10-22
-
-**Resolved:** portable, credential-free reproductions now distinguish confirmed defects from suspected live causes. **Changed:** [baseline evidence](../fixtures/feedback-reproductions.md), scratch manifest template, native timeout/metadata/delayed-page expected-failure tests and conservative delayed-revision fixture. **Validated:** existing targeted suites: 55 tests; reproducers: 4 tests; `pnpm check`: 587 tests pass, including three explicitly expected failures. **Risks:** expected-failure tests demonstrate missing behavior; they do not verify fixes. No live target or lease causality proof. **Next:** phase 1 shared layout fallback. Commit: `test: preserve adoption failure reproductions`.
-
-### Phase 1 report — 2026-10-22
-
-**Resolved:** idle native failure no longer blocks the default workflow when independent complete geometry settles. **Changed:** one static host/kit policy, bounded native attempts, three equal hierarchy-aware samples, diagnostics and CLI `--layout`; no write retry. **Validated:** native success/failure/hang, node overflow/cycles, target/transport refusal, kit binding and stable-render tests; `pnpm check` passes 597 tests and six-package smoke passes. **Risks:** geometry is neither visual approval nor font readiness; live CLI/kit build remains pending. **Next:** migration explanations and bounded doctor readiness. Commit: `feat: share bounded layout fallback across host and kit`.
-
-### Phase 2 report — 2026-10-22
-
-**Resolved:** metadata-only stale snapshots now explain schema/ownership/hash causes; transport connection alone cannot prove editor readiness. **Changed:** additive reason codes and existing migration guidance; bounded origin/transport/challenge execution/file-pin layers, timestamps and duration, default 5 s doctor with 1–30 s option. Docker uses the same fresh-read proof. **Validated:** 74 targeted tests, stale/missing challenges, wrong file, sleeping origin/editor, timeout validation and secret redaction; `pnpm check` 607 tests and six-package smoke pass. **Risks:** real background/disconnected editor tests remain pending; heartbeat/version are unknown unless observed. **Next:** coordination trace and serialized page sessions. Commit: `feat: explain migration drift and prove fresh doctor readiness`.
-
-### Phase 3 report — 2026-10-22
-
-**Resolved:** delayed synthetic navigation and overlapping same-client collectors now use observed IDs and serialized sessions, restoring the starting page. **Changed:** page/session guards shared by derived clients, bounded polling, per-page progress and separate restoration errors; optional `--trace --apply` journal lease/revision events (also token pushes). **Validated:** real plugin bodies cover delayed switches, concurrent collectors, manual navigation, removed/ambiguous pages, revision changes, restoration failure and cross-client writer contention; `pnpm check` 614 tests and six-package smoke pass. **Risks:** PP-07 remains **unresolved**: delayed own saves and external edits cannot be causally distinguished with current evidence. Revision guards are unchanged. Live sequential/external-edit tests pending. **Next:** installed help and composition guidance. Commit: `feat: serialize observed page sessions and trace writer revisions`.
-
-- [ ] PP-07 follow-up: obtain scratch trace proving delayed writer-marker persistence, then separately review any change to revision ordering. Tracing and conservative conflict refusal are delivered; no race fix is claimed.
-
-### Phase 4 report — 2026-10-22
-
-**Resolved:** installed help now exposes the full inspect/spec/snapshot/capture/compare workflow; composition guidance catches under-designed first frames before multiplying variants. **Changed:** task-grouped actual command examples, composition checklist in shipped skills, and migration/layout/doctor/snapshot/recovery docs. Corrected old help wording that implied updating an image alone approves it. **Validated:** help, docs, neutral-core and idempotent skill installation tests; `pnpm check` 615 tests and six-package smoke pass. **Risks:** composition remains a human/agent judgment step; a checklist does not establish visual quality or owner approval. **Next:** real-browser comparison starter. Commit: `docs: expose the complete workflow and first-frame composition checks`.
-
-### Phase 5 report — 2026-10-22
-
-**Resolved:** adopters can reuse real capture plumbing with explicit project hooks rather than rewrite fonts/scroll/hover/cropping logic. **Changed:** shipped browser provider, independent DOM state and loaded font/weight evidence, outward CSS clipping, hover/occlusion checks, optional schema-1 metadata validation and installed-example smoke. **Validated:** `pnpm check` 616 tests and six-package smoke pass; eight real local browser cases plus wrong theme, missing face/weight, delayed font load, scale mismatch, hover and sticky-shell refusal. Actual screenshots were inspected; a sticky header initially obscured the heading and the new guard/scroll hook corrected it. [Portable browser evidence](../fixtures/browser-capture-2026-10-22.json) records Chromium 148.0.7778.96, bundled Playwright 1.62.1, unchanged reference bytes and owner-review-required. MCP could inspect the fixture but could not import modules; the real provider ran with the bundled runtime and cached Chromium. **Risks:** references are explicitly unapproved synthetic browser fixtures, not approved Penpot designs; sampled occlusion still requires image inspection. No consumer provider was registered. **Next:** offline projected themes and pinned native capability evidence. Commit: `feat: ship a verified real-browser comparison starter`.
-
-### Phase 6 report — 2026-10-22
-
-**Resolved:** independent light/dark artifacts can be generated without switching live themes or falsely claiming native frame modes. **Changed:** bounded neutral projection resolver shared with mode verification; adapter `tokens preview --from --theme [--out]`, discoverable artifact schema, source/theme/set provenance and owned scratch example. **Validated:** ordered precedence, aliases/arithmetic, composites, ambiguous/missing themes/sets, cyclic/budget failures, project-bound output and preservation through actual sandbox example bodies; `pnpm check` 622 tests and six-package smoke pass. **Risks:** [pinned capability evidence](../theme-previews.md#pinned-native-capability-evidence) is source-based; the hosted API version is distinct. Native frame themes, component parity/overrides and live projection preservation remain unproved. **Next:** full branch review, final browser/package validation and explicit live checklist. Commit: `feat: project declared themes without changing live selection`.
-
-### Final boundary review report — 2026-10-22
-
-**Resolved:** cancelling a queued collector no longer opens a parallel page queue while its predecessor is still active. **Changed:** deferred queue cleanup, stricter geometry/hierarchy and doctor identity validation, correct doctor range text, bounded browser animation-frame waits. **Validated:** the queue regression failed before the fix and passes afterward; cancellation after a delivered read performs no second observation. Malformed native/geometry/root/sibling evidence refuses. `pnpm check`: 630 tests; all six package smoke installs; eight real local browser cases plus six rejection cases and delayed fonts pass. **Risks:** live gates and PP-07 causality remain open. **Next:** owner branch review and separately authorized scratch acceptance. Commit: `fix: preserve cancellation and evidence boundaries`.
-
-### Final handoff — 2026-10-22
-
-**Resolved:** all authorized code phases and offline/local-browser acceptance are complete on the review branch. **Changed:** [consolidated branch report](tradient-feedback-review.md) maps every finding to its delivered outcome, evidence and remaining live checks. **Validated:** 630 tests, six installed package families, eight real browser cases and six rejection cases; build/types/version/whitespace checks pass. **Risks:** PP-07 causality, live Penpot build/repeat/heading and multi-page trials, native frame-theme proof and owner release decisions remain unchecked. **Next:** owner branch review and confirmed disposable-file acceptance; no credentials are requested and no publication was attempted.

package/docs/plans/tradient-feedback-review.md

@@ -1,83 +0,0 @@
-# Adoption feedback branch review
-
-Date: 2026-10-22. Branch: `codex/tradient-feedback`. Base: `57f9782`.
-
-Code phases 0–6 are implemented and verified. The branch is ready for owner review. Live Penpot acceptance remains pending; the lease/save race is investigated rather than claimed fixed. The owner has authorized pushing this branch and opening its feature PR. No version bump, merge or publication was performed. All six repository versions remain 0.2.0.
-
-## What each update resolves
-
-| Finding | Delivered result | Verification and limit |
-| --- | --- | --- |
-| PP-01: native layout timeout blocks default build | Shared bounded auto/native/geometry policy for SDK and kit; CLI selection; three complete matching geometry/hierarchy samples | Native success/failure/hang, transport/cancellation/malformed/target refusal and independent matching exports tested; real Penpot build pending |
-| PP-02: unexplained metadata-only token drift | Stable reason codes and explicit existing ownership migration guidance | Legacy values unchanged while schema/hash differs reproduces and explains staleness; migration preserves provenance |
-| PP-03: readiness is unclear | Bounded origin, transport, fresh execution challenge, file/page identity and file-pin evidence | Sleeping origin/editor, stale/malformed challenge, wrong pin and redaction tested; real editor state trials pending |
-| PP-04: simultaneous theme preview needs custom glue | Offline versioned projection, shared ordered alias resolver, adapter command and owned-root example | Precedence, composites, unknowns and sandbox preservation tested; native frame themes remain unproved |
-| PP-05: real comparison provider is missing | Packaged browser starter with project hooks, actual state/fonts, pointer, occlusion and crop evidence | Eight real local Chromium cases, delayed fonts and six rejection cases; unapproved synthetic references do not establish Penpot parity |
-| PP-06: workflow/companions are hard to discover | Companion setup guide, grouped installed help and first-frame composition checklist | Help, docs, core neutrality and idempotent installed skills tested; composition still requires judgment |
-| PP-07: suspected self-save revision conflict | Optional redacted lease/inspection/revision traces and conservative reproducer | **Unresolved causality.** Own delayed persistence and external edits still conflict; no revision guard was relaxed |
-| PP-08: multi-page snapshots fail | Observed page-ID polling, serialized sessions, per-page progress and starting-page restoration | Delayed/concurrent collectors, manual navigation, source edits and restoration failures tested; real multi-page trial pending |
-
-The final review also reproduced and fixed cancellation allowing a third collector to bypass an active session. Queue order now survives cancellation. Layout and doctor reject malformed evidence, and browser frame sampling has a deadline.
-
-## Repository readability follow-up
-
-Biome 2.6.2 supplies a separately committed formatting baseline (`b1a9445`).
-[Conventions and executable examples](../conventions/README.md), an `AGENTS.md`
-reference and the repository-local coding skill now guide naming and module
-boundaries. `pnpm check` also enforces formatting, focused lint rules, kebab-case
-code paths and checked templates. The comparison adapter is split into focused
-modules with its existing public entrypoint intact. The
-[completion checklist/report](../conventions/completion-2026-10-22.md) explains
-what each change resolves and the remaining formatter/review limits.
-
-## Validation
-
-- `pnpm check`: **643 tests** pass (core 498, Docker 28, token adapter 99, comparison adapter 15, convention examples 3), style/path checks, build/typecheck and six-package version guard pass.
-- `pnpm smoke:package`: all **six tarballs** install and run in clean consumers. Installed help, skills, adapter documentation and browser starter are verified, including the comparison adapter's preserved runtime exports and public TypeScript declarations.
-- Real browser trial: bundled Playwright **1.62.1**, cached Chromium **148.0.7778.96**; desktop/mobile × light/dark × loaded/empty. Missing/wrong font face/weight, wrong theme, scale mismatch, hover contamination and sticky occlusion refuse; delayed font loading succeeds. Baseline bytes remain unchanged and verdict stays `owner-review-required`.
-- Actual captures were visually inspected. That inspection found a sticky header hiding the heading; an occlusion guard and explicit project scroll hook corrected it. [Portable evidence](../fixtures/browser-capture-2026-10-22.json) records the cases without machine paths or credentials.
-- `git diff --check` passes. Changesets cover fixes and new public capabilities; repository versions are unchanged.
-
-## Commits
-
-| Step | Commit |
-| --- | --- |
-| Baseline/reproductions | `cc65514` |
-| Bounded layout | `2c60ac5` |
-| Migration/readiness | `b985dc2` |
-| Coordination/snapshots | `b51ad30` |
-| Help/composition | `81f20d3` |
-| Browser starter | `79e8c8e` |
-| Projected themes | `415b291` |
-| Final boundary fixes | `5bcc687` |
-
-## Remaining acceptance
-
-- [x] Owner authorizes pushing the branch and opening its feature PR (2026-10-22).
-- [ ] Owner reviews the branch before merge or release work.
-- [ ] Owner confirms a disposable Penpot copy by public file ID; populate the [scratch manifest](../fixtures/feedback-scratch.template.json). No credentials belong in it.
-- [ ] Run shipped CLI/kit build, repeat it and change one heading across the eight cases; independently compare IDs, bindings, geometry and two inspected exports.
-- [ ] Verify fresh doctor reads with responsive/background/disconnected scratch editor states.
-- [ ] Capture idle/no-op and controlled external-edit traces; establish PP-07 causality before reviewing a revision-order change.
-- [ ] Run a two-page snapshot with restoration and projected-color preservation checks for global selections, catalog/order and unrelated objects.
-- [ ] Prove any native frame-theme or component override capability separately; projected appearance is insufficient.
-- [ ] After owner review and acceptance decisions, prepare the release through Changesets and existing protected publication workflow.
-
-The [living execution guide](tradient-feedback-0.2.0.md) contains the per-phase Resolved / Changed / Validated / Risks / Next reports. Pending live items remain unchecked; this branch does not claim rollback, exactly-once writes, native component parity or human visual approval.
-
-## Release readiness check — 2026-10-22
-
-- [x] Working branch is based on remote main (`57f9782`) verified during the readiness check.
-- [x] Pending Changesets plan **0.3.0 for all six packages** without changing versions on this feature branch.
-- [x] GitHub has both release activation variables set to `true`, and `CHANGESETS_PR_TOKEN` is present. Both release workflows are active; recent version-PR workflow runs succeeded.
-- [x] `npm-release` allows the `main` branch and requires the owner as reviewer, with self-review allowed.
-- [x] The temporary `PENPAIR_RELEASE_EXCLUDE_PENPAIR=true` exception remains enabled: all six repository versions advance together, while the five scoped packages must publish and verify.
-- [x] Remove trailing whitespace from the added font license without changing its text, and replace stale hardcoded versions in the release guide. Branch whitespace checks and current style checks pass.
-- [ ] Push/open the feature PR and pass its remote CI before merging.
-- [ ] Review/merge the generated **Release Penpair** version PR, approve the environment and verify the five required registry versions/provenance.
-
-The code is ready for a feature PR with the live acceptance limits above visible.
-Its merge does not publish: it creates/updates the version PR. Publication runs
-after that separate PR is merged and the environment is approved. The recent
-publish workflows were skipped; this check verifies repository configuration,
-not a completed npm OIDC publication or npm account publisher permissions.