Verify Paperclip

Read the map contract, then use the feature map to select user verification recipes. For API/agent access, read the same-named agent access companion and use the actual permitted agent identity, target and work mode. Follow existing API/runner/MCP fixtures for access proof; a board request does not prove agent access. Report recipe or access drift with evidence; map updates belong to maintain-verification-skill. Read development instructions for current commands.

Select the verification target

State what is being tested before starting. Use the requested target; for ordinary feature development, default to the current checkout on the current host with isolated data. Expand into cross-platform or release qualification only when requested or needed to reproduce the problem.

Record these independent dimensions together:

• Artifact: source checkout (path, commit, dirty state), published npm package (requested channel and resolved exact version), or deployed image/release.
• Environment: local, staging, or production; target URL and intended company or workspace; board/user/agent identity and authentication mode.
• Starting data: fresh and unonboarded, freshly seeded, cloned, or reused; embedded versus external PostgreSQL; configuration/data location or a redacted database identifier. Never record credentials or connection strings.
• Platform: server OS/architecture, Node/npm versions, and browser/client OS when relevant. A Mac browser against a Linux server is Linux server evidence; WSL is Linux evidence, not native Windows evidence.
• Journey: first installation/onboarding, an existing-user feature, upgrade, or a live agent run; expected outcome and real versus simulated dependencies.

Fresh data does not imply a fresh install. A seeded test drive does not prove onboarding. A source build does not prove npm packaging. A passing staging check does not prove production, and a production Cloud stack does not prove the stable npm install. Report only the combinations actually exercised.

Deployment handoff

When a requested revision must first be built or deployed, use the skills in the private paperclip-cloud repo:

• deploy-paperclip-stack at .agents/skills/deploy-paperclip-stack/SKILL.md for a tenant workspace or an explicitly scoped fleet rollout.
• deploy-cloud-harness at .agents/skills/deploy-cloud-harness/SKILL.md for the Cloud control plane itself.

Locate the authorized Cloud checkout or installed skill by name; do not assume a sibling directory exists. Those skills own build preparation, deployment, migrations, and rollout recovery. Return here with environment, target, resolved source SHA, release/image identity, deployment result, and evidence link. If private access is unavailable, report that prerequisite as blocked and continue checks possible on the supplied target without inventing deploy commands.

A verification request alone does not authorize deployment, npm publication, fleet-default changes, or a production rollout. Preserve explicit deployment instructions already given. Publishing npm packages belongs to the existing release skill; installing one does not require publishing it.

Launch an empty checkout instance

Run from the repository root with Node 24.11+, Python 3, lsof, and dependencies installed with pnpm install --frozen-lockfile. Browser driving uses the existing @playwright/test dependency. If Chromium is unavailable, run node node_modules/@playwright/test/cli.js install chromium, or select an installed browser with PAPERCLIP_PLAYWRIGHT_CHANNEL=chrome.

Create separate, unique data and evidence directories. Keep the evidence outside the data directory:

VERIFY_DATA_DIR=$(mktemp -d "${TMPDIR:-/tmp}/paperclip-verify-XXXXXX")
VERIFY_EVIDENCE_DIR=$(mktemp -d "${TMPDIR:-/tmp}/paperclip-proof-XXXXXX")
python3 .agents/skills/verify-paperclip/scripts/launch.py \
  --data-dir "$VERIFY_DATA_DIR" --evidence-dir "$VERIFY_EVIDENCE_DIR"

Keep this command in a foreground terminal/session. The helper runs the supported onboard --yes --bind loopback --no-install-service --run command, with isolated embedded PostgreSQL, a free loopback port, no inherited instance routing or cwd .env, and no automatic browser opening. It records launch.json in the evidence directory. Source startup builds its required shared/plugin packages and migrates the empty database; readiness can take longer on the first run.

This path starts an empty instance without model credentials. Create company and agent state through the journey being checked. A UI check that stops before model execution does not prove an agent run. For a preconfigured company/CEO and live model work, use the documented test-drive command with an authorized environment-backed credential and --no-browser. Record its printed data directory, URL, runtime PID and commit before driving; never use a fake credential to claim provider verification.

For Paperclip-managed reusable services, follow dev-workspace run/verify/fix instead of launching a second server. Its cloned-data/login requirements differ from this empty local instance.

Doctor (owned checkout helper only)

The doctor/stop commands require the real launch.json created by launch.py. Do not fabricate one for dev servers, npm installs, test drives, or hosted stacks. Use their own readiness and lifecycle procedures instead.

After startup, and again after any surprising behavior, run:

python3 .agents/skills/verify-paperclip/scripts/doctor.py \
  --evidence-dir "$VERIFY_EVIDENCE_DIR"

This read-only check compares the recorded launcher, runtime PID, port owner, process cwd, configuration, served Git commit, health/bootstrap readiness, root HTML response, and company-list access. It writes doctor.json or exits nonzero. Do not trust a root 200 or CLI doctor output alone. The CLI doctor checks whether the port is available before startup; it is not proof of a running server's ownership. Browser readiness still requires the expected visible page. Reset or relaunch a wedged browser even when the process health passes.

Drive

Use accessible roles, labels, and placeholders from the latest page state. Existing Playwright specs in tests/e2e/ supply recipes and selectors; their configured servers and fixtures are separate from this live instance. Run a named suite through its own configuration only when that is the evidence needed.

The executable onboarding smoke drives onboarding.md / web-wizard: open /onboarding in the disposable self-hosted instance, enter a unique organization name, choose Continue, reach the agent-name field, reopen /<company-prefix>/onboarding, reload, and corroborate the saved company through read-only API checks:

node .agents/skills/verify-paperclip/scripts/onboarding-smoke.mjs \
  --evidence-dir "$VERIFY_EVIDENCE_DIR"

This covers company creation and setup resumption, with no mocked responses or provider calls. Hiring, first task execution, and the alternate CLI entry remain separate journeys. The script requires an empty instance and refuses a non-owned or non-loopback target. For other features, reuse the owned URL and follow the map's entry points. Company routes normally require the selected company's issuePrefix, for example /<PREFIX>/goals; use current navigation rather than guessing resource URLs. The unprefixed /onboarding route starts naming; use the company-prefixed onboarding route to resume its agent setup. Check relevant experimental gates and actor permissions.

For source-checkout CLI checks, discover exact flags with node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts <command> --help, then select the disposable data directory/API/company explicitly. For published npm checks, use the installed version’s CLI and help instead. API reads can corroborate UI writes; API-created state does not prove a creation UI.

Evidence

Include the target dimensions above, then record feature file, sub-feature and entry-point ID, commit/dirty state, target URL, company/user, flags, runtime/harness, live versus simulated dependencies, command, exit code, expected and observed behavior, and evidence links. Report each entry as passed, failed, blocked with its prerequisite, or not run.

The smoke saves before/after/reload screenshots, visible-page text, a Playwright trace, and result.json with company ID and API corroboration. On failure it retains the trace, visible state, and failure result; rerun doctor before retrying. Preserve launch output and relevant application logs without secrets. Reopen or reload changed state and verify persistence/continuation, not just a success toast. One passing sub-feature does not certify the entire feature family or other surfaces. A full maintenance pass must exercise every mapped feature or report incomplete coverage.

For Paperclip-assigned work, attach important proof through the artifact workflow. Keep runtime results in the evidence directory or issue, not in the map. The generated maps/generated/coverage.json lists page references, not live test health.

Preserve failures through acceptance

A successful retry establishes that a later attempt succeeded. Retain earlier material failures in the verification record, including the failed requirement, relevant logs, and what changed before the retry. Use a focused comparison or reproduction to determine whether the change caused the failure. When useful, check the unchanged baseline under comparable conditions. If the cause remains unknown, state that uncertainty; do not infer an infrastructure fault from a passing retry alone.

Report recovery and resolution separately. A later passing journey can show recovery without explaining the earlier failure. Do not describe acceptance as complete while a relevant requirement remains unverified. Record the remaining gap and the next discriminating check instead of repeating retries until green.

Apply this to failures that bear on the changed behavior or requested acceptance criteria. Independently established infrastructure failures can be tracked separately, with supporting evidence and any checks they prevented still marked blocked or not run. This does not require investigating every unrelated failure.

Cleanup

Close the browser context you created (the smoke does this in finally). Leave shared dev, staging, and production services running. The remaining cleanup steps in this section apply only to launch.py instances; use the selected target’s procedure for other launchers. Stop the helper-owned runtime with:

python3 .agents/skills/verify-paperclip/scripts/stop.py \
  --evidence-dir "$VERIFY_EVIDENCE_DIR"

The helper verifies the runtime's port, cwd, and launch ancestry before sending SIGTERM to that PID, then waits for runtime exit and checks that its HTTP listener and embedded database have stopped. Signaling the runtime PID lets the server drain before stopping PostgreSQL; a terminal group interrupt can reach the database first. Do this after failed drives as well as successful runs. If startup fails before a runtime record exists, stop only the foreground session you created and inspect its recorded data directory for residue. Never kill by process name or stop another checkout's server.

Verify the recorded HTTP port has no listener and the owned runtime PID has exited. Embedded PostgreSQL should stop with the server; inspect only the recorded data directory if shutdown is incomplete. Retain the data directory for diagnosis until no owned process uses it; remove only that exact temporary directory when it is no longer useful. Never delete the evidence directory during teardown. Confirm screenshots, trace, result.json, launch.json, and doctor.json still exist after shutdown. A failed launch leaves its evidence intact.

Helpers

All helper invocations are shown above. launch.py, doctor.py, and stop.py use Python's standard library and the repo CLI; onboarding-smoke.mjs uses the repo's existing Playwright dependency. They introduce no new package dependency or test framework.

Helper safety check

Run the standard-library ownership test before changing launch/doctor/stop helpers:

python3 -m unittest discover -s .agents/skills/verify-paperclip/tests -v

It starts an owned fixture in another temporary checkout and confirms that both doctor and stop reject its claimed port/PID without stopping the server. A second fixture closes its listener before exiting and proves that cleanup waits for runtime exit. These checks do not qualify Paperclip startup, database readiness, or onboarding.