Skip to main content

Maya Verification Guide

This guide documents the stable build, verification, evidence, and release-gate contract for the workspace. Detailed assertion inventories live beside the scripts and evidence fixtures that own them; this document should stay small enough to read before running a release.

Command Roles​

  • pnpm build builds the composition, Claude workspace, Data Lab sample module, protocol, UI, Docusaurus docs site, web, and backend packages.
  • pnpm typecheck builds the workspace packages and then runs TypeScript checks for composition, Claude workspace, Data Lab sample module, protocol, UI, web, Docusaurus docs, and backend. pnpm typecheck:all assumes the required package build output already exists.
  • pnpm verify builds the workspace packages and then runs pnpm verify:built.
  • pnpm verify:built runs protocol contract checks, package-boundary checks, request-key guards, UI surface parity checks, UI unit, story coverage, token platform, token contract, Storybook build, visual matrix, a11y, bundle, and render gates, evidence safety checks, runtime reliability guards, and verification-document consistency checks against the current built package output.
  • pnpm verify:full runs pnpm build, web/UI bundle budgets, UI render budgets, and then pnpm verify:built, so bundle budgets and protocol/UI/evidence parity checks use the same production build.
  • pnpm verify:a11y-keyboard builds package/backend prerequisites and runs the keyboard plus structural axe Playwright suite. pnpm verify:a11y-keyboard:built assumes those prerequisites are already built.
  • pnpm release:gate runs a frozen install, early clean/source-boundary gates, package build and boundary checks, TypeScript checks, web/backend builds, bundle budgets, Playwright Chromium install, built verification, built keyboard/a11y checks, package dry-run, consumer smoke, docs/DX checks, supply-chain checks, and the final git diff plus untracked-file clean check. It intentionally does not run evidence:* capture scripts or visual evidence refresh smokes, so CI cannot refresh committed evidence records.

The command graph is centralized in tools/gate-commands.mjs; package scripts call tools/run-gate.mjs instead of restating long command chains.

Evidence Refresh​

  • pnpm evidence:visual refreshes the Chat, Projects, Customize, and Settings browser visual smoke evidence (smoke:chat, smoke:projects, smoke:customize:reuse, and smoke:settings).
  • pnpm evidence:all runs pnpm build, the protocol/action capture scripts, and then pnpm evidence:visual, preventing stale build artifacts from being captured.
  • pnpm evidence:official-live-shape -- --id <id> --surface <surface> --route <route> writes guarded official browser/CDP shape-only evidence from stdin. The writer preserves endpoint/status/header-name/visible-rect metadata and rejects persisted request bodies, response bodies, header values, browser storage, profile data, and unredacted dynamic challenge tokens.

Regenerated evidence belongs under projects/claude-protocol/protocol-captures/actions or the guarded .sessions locations referenced by the verifiers. Capture scripts must keep credential values, browser profile data, and browser storage out of committed evidence.

Surface Verification​

  • pnpm verify:chat-surface compares controlled local Chat create/follow-up browser smoke evidence with the protocol request keys, SSE lifecycle, transcript DOM/layout, responsive viewport matrix, and source-level render guards.
  • pnpm verify:customize-surface verifies the standalone Customize routes while reusing the single Projects browser smoke walker for shared Directory interactions.
  • pnpm verify:projects-protocol, pnpm verify:projects-visual, pnpm verify:settings-surface, and pnpm verify:sidebar-surface own their corresponding evidence matrices and source guards.
  • pnpm verify:surface-migration-map validates the WCP-014 source-level map from current Claude UI surfaces to contribution descriptors, explicit v0 gaps, and the first safe visual parity milestone.
  • Chat, Projects, Customize, and Settings responsive visual-smoke checks derive the viewport matrix from officialResponsiveViewportMatrix.

Coverage details and evidence ids are intentionally not duplicated here. Use projects/claude-protocol/protocol-captures/COVERAGE_MATRIX.md, each action directory's notes.md, and the matching tools/verify-*.mjs script as the source of truth for exact cases.

Evidence Safety​

  • pnpm verify:evidence scans protocol captures, guarded official replication evidence, app sources, capture scripts, and root package scripts for credential-bearing headers, browser profile artifacts, browser storage, raw trace/session identifiers, and copied client identifiers.
  • pnpm verify:evidence-structure validates action evidence JSON/NDJSON shape, screenshot provenance metadata, focused network records, screenshot file references, SSE event shape, and safe official/local origin flags.
  • Screenshot evidence must carry action.screenshot.path, route, source, origin, and officialClaudeAi. Local localhost-controlled screenshots use origin: local-localhost-controlled and officialClaudeAi: false; official screenshots must opt into origin: official-claude-ai and officialClaudeAi: true.

Evidence verifiers should be updated when a new evidence shape is introduced. The verification guide should only gain durable rules, not one-off case inventories.

Package And Release Boundary​

  • pnpm verify:package-boundary builds composition, Claude workspace, Data Lab sample module, protocol, and UI packages and verifies the machine-readable package registry, headless composition boundaries, namespace/conflict fixtures, WCP-010 policy fixture diagnostics, WCP-011 composition golden fixtures, WCP-013 Claude built-in descriptor fixtures, WCP-015/WCP-016 render runtime foundation, coverage validation, and behavior tests, WCP-018 AssistantWorkspace composition rendering, WCP-020 focused Vitest coverage for default Claude route inventory rendering, selector-miss route fallback, and built-in-only path matchers, WCP-019 Claude workspace runtime builder, WCP-021 first-party Data Lab sample module, WCP-022 module conformance checklist and sample-module failure fixtures, Claude built-in route/settings parity, public exports, declaration specifiers, public .d.ts release-impact classification including the highest required level, style scoping, asset freshness, and single implementation boundaries.
  • pnpm verify:docs-dx expands to node tools/verify-docs-structure.mjs, pnpm verify:surface-migration-map, node tools/verify-docs-api-parity.mjs, node tools/verify-agent-capability-map.mjs, and pnpm verify:docs-site.
  • pnpm pack:dry-run packs composition/protocol/UI tarballs without installing a temp consumer and writes .tmp/reports/pack-dry-run.json.
  • pnpm verify:package-registry checks that every apps/* and projects/* package is classified in tools/workspace-package-registry.mjs, root gates cover registered build/typecheck/package-boundary commands, public ABI snapshots exist where declared, and publishable metadata matches the npm release policy.
  • pnpm smoke:consumer packs composition/protocol/UI tarballs, installs them into temporary external consumers, runs tsc --noEmit and Vite build, verifies duplicate package docs are absent, checks that UI public types and install metadata stay protocol-free while using @maya/assistant-composition as an explicit peer, compiles the WCP-023 guide consumer without source-path imports, and runs the WCP-025 product-kit consumer through createClaudeWorkspaceRuntime plus an explicit AssistantWorkspace composition/render-runtime path. When run standalone from a clean workspace, run pnpm build:packages first so workspace-private Claude workspace and Data Lab dist entrypoints exist. The WCP-023 guide consumer and WCP-025 product-kit consumer are workspace-private package consumers for Claude workspace and Data Lab until their publishability is explicitly opened.
  • Canonical package docs stay in .docs. Docs/API parity is enforced by node tools/verify-docs-api-parity.mjs, pnpm verify:claude-workspace-runtime guards the WCP-019 product-kit builder boundary, pnpm verify:sample-module guards the WCP-021 first-party module happy path, pnpm verify:sample-module:conformance runs WCP-022 black-box failure fixtures, and pnpm verify:module-conformance guards the WCP-022 module conformance checklist wiring while invoking the same failure fixtures. The WCP-023 happy path guide lives under .docs/guides and is validated by pnpm smoke:consumer. Package tarballs intentionally exclude package-root README.md, dist/docs/*, and docs/* copies so there is no second documentation truth.

CI Policy​

.github/workflows/release-gate.yml delegates to pnpm release:gate, uses read-only contents permissions, disables checkout credential persistence, and uploads ignored .tmp/reports plus a11y artifacts with missing files treated as warnings so report upload never masks an earlier gate failure. Required gates must not run evidence capture or committed evidence refresh scripts in CI.