@kujolang/paperclip 0.1.4 → 0.1.6

package/docs/MAINTENANCE_HANDOFF.md

@@ -0,0 +1,237 @@
+# Paperclip maintenance handoff
+
+Updated September 3, 2026.
+
+## Current state
+
+`@kujolang/paperclip` is ready for public use within its documented scope. Version
+`0.1.6` is published on npm and GitHub. The released plugin:
+
+- works in Paperclip's current task view without requiring the Classic Task Interface;
+- provides Review, Context, and Failure Evidence workflows in the inline workspace and
+  the shared Kujo detail tab;
+- uses the official Kujo logomark;
+- protects both UI surfaces with browser behavior, accessibility, responsive, and
+  visual-regression checks;
+- bundles checksummed Kujo components for every supported platform; and
+- publishes through GitHub Actions with npm trusted publishing and provenance.
+
+No known plugin defect blocks normal public use. The remaining work is upstream or
+distribution work: the host-version change is waiting on Paperclip maintainers, and
+catalog distribution is not available yet.
+
+## At a glance
+
+| Work | State | Next action |
+| --- | --- | --- |
+| Exact scoped-version install | Upstream PR ready and green | Get Paperclip PR #12745 reviewed and merged |
+| Real minimum host version | Externally blocked | Wait for a Paperclip release containing PR #12745 |
+| Browser/UI regression coverage | Complete | Maintain the approved baselines with UI changes |
+| Dependency updates | Complete | Continue normal Dependabot review |
+| Paperclip catalog listing | Not currently available | Recheck when Paperclip publishes a marketplace process |
+| Kujo plugin release | Complete | Verify and retain the v0.1.6 release evidence |
+
+## Work queue
+
+### 1. Fix pinned scoped-package installs in Paperclip
+
+**Priority:** High  
+**Owner:** Paperclip host CLI, not this plugin
+
+**State:** Implemented in a green upstream PR awaiting maintainer review
+
+The Paperclip CLI currently misparses an exact scoped npm package reference:
+
+```bash
+npx paperclipai plugin install @kujolang/paperclip@0.1.6
+```
+
+It looks for a directory named `@kujolang/paperclip@0.1.6` after npm installs the
+package. Installing the current version without a version suffix works:
+
+```bash
+npx paperclipai plugin install @kujolang/paperclip
+```
+
+The fix is implemented and pushed from the isolated worktree
+`/Users/robertdevore/2026/paperclip-kujo-fixes` on branch
+`codex/kujo-plugin-host-fixes`. The upstream pull request is
+[paperclipai/paperclip#12745](https://github.com/paperclipai/paperclip/pull/12745).
+It adds a shared npm-package-spec parser, CLI and server regression tests, and real
+host-version detection. Local targeted verification passed 59 tests across four test
+files, plus shared, CLI, and direct server TypeScript checks. The complete upstream CI
+matrix, Greptile, Snyk, Socket, policy, and automated review checks passed. The PR is
+ready for maintainer review.
+
+Next steps:
+
+1. Address any maintainer review request.
+2. Merge through the upstream project's normal process.
+3. Verify a clean exact-version install from the first Paperclip release containing
+   the change.
+
+Acceptance criteria:
+
+- `@scope/name@version` installs the requested exact version;
+- unscoped, scoped-without-version, file, and directory installs still work;
+- regression tests cover scoped exact versions; and
+- Kujo's upgrade and rollback documentation is retested and updated.
+
+Tracking evidence: SignalBox capture
+`cap_2bb9af3e-0a67-4b90-b242-d8edf54d3448` and signal
+`sig_9bac6b5c-871d-42e0-91a2-7bd99f78f3c0`.
+
+### 2. Restore the real minimum-host manifest constraint
+
+**Priority:** High  
+**Owner:** Paperclip host integration, followed by this plugin
+
+**State:** Blocked until the upstream fix is released
+
+Paperclip `2026.831.1` reported host version `0.0.0` to the plugin loader. The plugin
+therefore keeps `MINIMUM_HOST_VERSION = "0.0.0"` in `src/config/defaults.ts` as a
+temporary loader workaround. Documentation and CI enforce the actual supported floor,
+Paperclip `2026.824.1`.
+
+PR #12745 includes the host-version reporting fix, but the published Kujo plugin must
+keep the temporary `0.0.0` manifest value until that change reaches a public Paperclip
+release. Raising the floor earlier would reject users on the current host even though
+their Paperclip version is otherwise supported.
+
+After the upstream release:
+
+1. set the manifest minimum to the real supported host floor;
+2. update `tests/plugin.spec.ts` and `docs/COMPATIBILITY.md`;
+3. run the full verification matrix;
+4. install the packed plugin on the declared minimum and latest Paperclip versions; and
+5. issue a patch release if the published manifest changes.
+
+Acceptance criteria: a compatible host loads the plugin, an older host rejects it with
+a clear message, and no `0.0.0` compatibility exception remains.
+
+### 3. Add automated browser coverage for both UI surfaces
+
+**Priority:** Medium  
+**Owner:** Plugin repository
+
+**State:** Complete in plugin PR #11
+
+The UI has contract tests, manual browser evidence, and automated browser and visual
+regression coverage for:
+
+- the inline current-task workspace registered through `taskDetailView`;
+- the shared `detailTab` on project, issue, and run pages;
+- Review, Context, and Failure Evidence actions and result states;
+- the official Kujo mark and accessible labels; and
+- light and dark themes at desktop and narrow widths.
+
+The implementation uses Playwright with a deterministic SDK fixture. It covers the
+current-task surface, the project and issue detail tabs, the read-only run detail tab,
+all three primary actions, the official mark, accessible labels, and approved
+desktop-light and narrow-dark screenshots. The `browser-ui` CI job installs its own
+Chromium build and uploads the Playwright report on failure.
+
+The hosted Linux browser job passed before merge. Pull requests and releases fail if
+either surface disappears, loses its primary actions, or exceeds the approved visual
+baseline tolerance. Lens also passed its full desktop/mobile accessibility and link
+check with no findings at warning or higher.
+
+### 4. Review the open dependency pull requests
+
+**Priority:** Medium  
+**Owner:** Plugin maintainers
+
+**State:** Complete
+
+The four reviewed Dependabot pull requests were [artifact attestation
+#1](https://github.com/kujolang/paperclip/pull/1), [the grouped development update
+#2](https://github.com/kujolang/paperclip/pull/2), [Zod
+#3](https://github.com/kujolang/paperclip/pull/3), and [dependency review
+#4](https://github.com/kujolang/paperclip/pull/4). All four are merged.
+
+The grouped TypeScript 7 update initially failed because compiler types were implicit.
+The repaired branch declares Node and React types explicitly. Local verification and
+the complete hosted compatibility matrix passed before merge.
+
+### 5. Submit to the Paperclip catalog
+
+**Priority:** Medium  
+**Owner:** Release or ecosystem maintainer
+
+**State:** Waiting for an upstream submission channel
+
+Paperclip's current implementation specification explicitly keeps a public plugin
+marketplace and packaged public distribution out of scope. No official catalog
+submission path is present in the upstream repository as of this update. Do not invent
+an unofficial submission process.
+
+Keep [CATALOG_SUBMISSION.md](CATALOG_SUBMISSION.md) ready as the evidence brief. When
+Paperclip publishes a submission channel, attach the tagged release, npm provenance,
+cross-platform checks, permissions summary, and current UI screenshots.
+
+This is a distribution task, not a prerequisite for installing the public npm package.
+
+### 6. Cut the next release only after plugin-owned work lands
+
+**Priority:** Medium
+
+**Owner:** Plugin release maintainer
+
+**State:** v0.1.6 released
+
+Version 0.1.6 consolidates the browser coverage and dependency maintenance. Its tagged
+workflow runs the full repository, browser, compatibility, supply-chain, packaging,
+and clean-install gates before publication through npm trusted publishing.
+
+## Recommended next-agent sequence
+
+1. Monitor upstream PR #12745 through review and merge; do not change the published
+   minimum-host constraint yet.
+2. After an upstream Paperclip release contains the host fix, restore the real host
+   floor and run minimum/latest clean-install tests.
+3. Publish a follow-up patch only if restoring the manifest floor changes the package.
+
+The catalog task stays parked until Paperclip exposes an official public submission
+process.
+
+## Optional business work
+
+The repository documents secure operation and incident response, but it does not promise
+an SLA. If the plugin will be sold as an enterprise-supported product, define support
+ownership, response targets, vulnerability intake, data-processing posture, and any
+required compliance evidence. These are commercial-operating commitments, not missing
+plugin functionality.
+
+## Guardrails
+
+- Keep the plugin a thin integration over the pinned Kujo components. Do not duplicate
+  their implementations in TypeScript.
+- Do not add a generic command runner or accept arbitrary workspace paths.
+- Preserve bounded output, redaction, canonical workspace checks, and the two-stage
+  Context Pack read boundary.
+- Do not add a Classic Task Interface requirement.
+- Keep npm publishing tokenless through trusted publishing; do not add repository npm
+  tokens.
+- Do not claim suggested checks ran unless the plugin has execution evidence.
+
+## Agent start checklist
+
+1. Read `AGENTS.md`, `README.md`, this handoff, and the document for the selected task.
+2. Confirm `git status --short --branch` is clean and create a focused branch.
+3. Run `npm ci --ignore-scripts` and `npm run verify` before changing behavior.
+4. Inspect current GitHub issues, pull requests, and workflow results.
+5. Make small signed commits, push them, and use required pull-request checks.
+6. For a release, follow [RELEASE_READINESS.md](RELEASE_READINESS.md), test a clean
+   public install, and verify the npm and GitHub artifacts after publication.
+
+## Completion standard
+
+A maintenance item is complete only when its tests, documentation, compatibility
+evidence, and hosted checks agree; the branch is merged; and the working tree is clean.
+A version change is complete only after the signed tag, GitHub release, npm package,
+provenance, and clean public install are all verified.
+
+## Release evidence
+
+- GitHub release: <https://github.com/kujolang/paperclip/releases/tag/v0.1.6>
+- npm package: <https://www.npmjs.com/package/@kujolang/paperclip/v/0.1.6>

package/docs/README.md

@@ -14,5 +14,6 @@ Start with [Installation](INSTALLATION.md), then [Usage](USAGE.md).
 | [Release readiness](RELEASE_READINESS.md) | Release order, test matrix, and operator checks. |
 | [Operations](OPERATIONS.md) | Health, audit, retention, upgrades, rollback, recovery, and incident response. |
 | [Catalog submission](CATALOG_SUBMISSION.md) | Paperclip catalog metadata and review evidence. |
+| [Maintenance handoff](MAINTENANCE_HANDOFF.md) | Current release state, remaining work, priorities, and completion criteria. |
 
 Repository policy lives in [SECURITY.md](../SECURITY.md), [CONTRIBUTING.md](../CONTRIBUTING.md), and [AGENTS.md](../AGENTS.md).

package/docs/RELEASE_READINESS.md

@@ -6,6 +6,7 @@
 | --- | --- |
 | TypeScript strict typecheck | automated by `npm run verify` |
 | Unit/contract tests | automated by Vitest |
+| Browser behavior and visual baselines | automated by Playwright in `browser-ui` CI |
 | Official Paperclip SDK worker harness | automated by Vitest |
 | Real ChangeBucket/PatchBrief fixture | automated by Vitest |
 | Real CaseFile redaction fixture | automated by Vitest |
@@ -27,7 +28,7 @@ The release order is platform runtime packages, neutral `@kujolang/kujo-runtime`
 
 The runtime release workflows build and smoke macOS arm64/x64, Linux arm64/x64, and Windows x64. Paperclip CI tests those five targets. A separate compatibility matrix tests Node.js 24.11 and current Node.js 24 against the minimum, locked, and latest compatible Paperclip SDK versions. Local plugin feature execution is verified on the developer host; every supported target is exercised during a tagged release.
 
-The tag workflow accepts only an annotated tag with a GitHub-verified SSH or PGP signature whose name matches `package.json`. It verifies the repository, packs once, attests that tarball, publishes that exact file through npm trusted publishing with short-lived OIDC credentials, and attaches its checksum, CycloneDX SBOM, component lock, and JSON schemas to the GitHub release. Package settings require two-factor authentication and disallow traditional token publishing.
+The tag workflow accepts only an annotated tag with a GitHub-verified SSH or PGP signature whose name matches `package.json`. It verifies the repository and browser UI, packs once, attests that tarball, publishes that exact file through npm trusted publishing with short-lived OIDC credentials, and attaches its checksum, CycloneDX SBOM, component lock, and JSON schemas to the GitHub release. Package settings require two-factor authentication and disallow traditional token publishing.
 
 ## Performance bounds
 
@@ -39,8 +40,8 @@ The tag workflow accepts only an annotated tag with a GitHub-verified SSH or PGP
 - context file: 2 KB during selection and 1 MB hard read refusal
 - Review file rows retained by canonical output; UI eagerly renders at most 20 context entries and 12 suggested tests
 
-The v0.1 deterministic suite remains in Vitest because these contracts combine the Paperclip SDK harness, native-process bounds, filesystem escape checks, and JSON assertions directly. Kujo Spec/Eval would add a second runner without improving determinism for this release; the versioned schemas and fixture cases are ready to export into Eval when the plugin adds executable verification.
+The v0.1 deterministic contract suite remains in Vitest because these contracts combine the Paperclip SDK harness, native-process bounds, filesystem escape checks, and JSON assertions directly. Playwright separately renders both registered UI surfaces in a deterministic SDK fixture, exercises every primary action, verifies the project, issue, and read-only run states, and compares desktop-light and narrow-dark screenshots. Kujo Spec/Eval would add a second contract runner without improving determinism for this release; the versioned schemas and fixture cases are ready to export into Eval when the plugin adds executable verification.
 
 ## Release decision
 
-SHIP only after the protected-branch checks pass, the compatibility workflow passes, the signed-tag workflow succeeds, the seven runtime/plugin npm names are available, a clean-room npm install passes, and a real Paperclip host loads the published package and exercises its tools.
+SHIP only after the protected-branch checks, browser UI suite, and compatibility workflow pass; the signed-tag workflow succeeds; the seven runtime/plugin npm names are available; a clean-room npm install passes; and a real Paperclip host loads the published package and exercises its tools.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kujolang/paperclip",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Make Paperclip agent work easier to scope, review, reproduce, and verify.",
   "license": "MIT",
   "homepage": "https://github.com/kujolang/paperclip#readme",
@@ -37,6 +37,7 @@
     "build": "node esbuild.config.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:ui": "playwright test",
     "test:watch": "vitest",
     "components:sync": "node scripts/sync-components.mjs --local-root ..",
     "components:verify": "node scripts/verify-components.mjs",
@@ -44,13 +45,13 @@
     "supply-chain:verify": "node scripts/verify-supply-chain.mjs",
     "verify": "npm run repository:verify && npm run typecheck && npm test && npm run components:verify && npm run supply-chain:verify && npm run build && npm run pack:verify",
     "pack:verify": "node scripts/verify-package.mjs",
-    "release:dry-run": "npm run verify",
+    "release:dry-run": "npm run verify && npm run test:ui",
     "prepublishOnly": "npm run verify"
   },
   "dependencies": {
     "@kujolang/kujo-runtime": "1.2.2",
     "@paperclipai/plugin-sdk": "2026.824.1",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   },
   "peerDependencies": {
     "react": ">=18"
@@ -61,13 +62,16 @@
     }
   },
   "devDependencies": {
-    "@types/node": "24.0.0",
-    "@types/react": "19.2.0",
+    "@playwright/test": "1.62.1",
+    "@types/node": "26.4.0",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
     "esbuild": "0.28.2",
-    "react": "19.1.1",
-    "rollup": "4.62.4",
-    "typescript": "5.9.2",
-    "vitest": "4.1.10"
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "rollup": "4.63.1",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
   },
   "publishConfig": {
     "access": "public",