| name | verification-loop |
| description | Run the full verification cycle before declaring work done: build, typecheck, lint, test, export review, diff review. Use when the user says "verify", "validate", "check everything passes", "run the full suite", "make sure it's ready", or before committing, opening a PR, or finishing a feature. Also use proactively after completing any non-trivial implementation work. |
Verification Loop
Run the full verification cycle before considering any feature, fix, or refactor complete. Each phase catches a different class of problem.
When to Activate
- After completing a feature or bug fix
- Before creating a commit
- After a refactor that touches multiple files
- When asked to verify or validate changes
Phases
Run these in order. Fix failures before proceeding to the next phase.
Phase 1: Build
bun run build
Catches: compilation errors, missing modules, broken imports, declaration generation failures. The build outputs to dist/ and includes both server (Bun target) and browser (browser target) entrypoints. It also runs the post-build distribution guard that rejects dangling relative .js specifiers in dist/, including extensionless directory re-export mistakes.
Phase 2: Typecheck
bun run typecheck
Catches: type errors across the full codebase that the build step may not surface (the build uses bun build which is less strict than tsc).
Phase 3: Lint
bun run lint
Catches: style violations, potential bugs, unused imports, promise handling mistakes, lint-disable policy drift, oversized unclassified implementation files, import cycles, internal-import boundary violations, operation-catalog drift, and type-ergonomics regressions. Uses Oxlint with type-aware rules and TypeScript/promise/unicorn/import plugins, then runs the repository's check scripts.
When a change adds, removes, or edits oxlint-disable directives, also run:
bun scripts/check-lint-disables.ts
The checker enforces the production-source suppression ceiling and the mechanical rationale length floor that bun run lint and the pre-commit hook rely on. Full rationale quality still belongs in pull request review.
When a change adds, splits, or newly classifies an implementation file near the 500-line ceiling, also run:
bun run scripts/check-implementation-file-sizes.ts
The file-size audit scans non-generated TypeScript/Svelte implementation files under src/, scripts, and tests; every file above 500 physical lines must either be split along an existing responsibility boundary or classified with a durable rationale in documentation/contributing/development-setup.md.
Phase 4: Test
bun test
Catches: regressions, broken behavior, incorrect logic. Tests use Bun's native test runner with colocated .test.ts files. The pre-commit hook wraps this through scripts/husky/run-tests.ts so failures include JUnit-derived testcase summaries and isolation rerun diagnostics; inspect that output before assuming a failure is non-reproducible.
For focused verification during development, run tests for just the affected area:
bun test src/core
bun test src/storage
bun test src/mcp
bun test src/server
bun test src/testing
Phase 5: Export Review
Check if src/index.ts was modified:
git diff src/index.ts
Every addition or removal in src/index.ts is a public API change. Verify:
- New exports are intentional and properly typed
- No internal types or implementation details leaked into the public surface
- Removed exports are truly unused by consumers
- Also check the secondary entrypoints:
./service-worker, ./storage/indexeddb, ./storage/text-value-store, ./storage/compressed, ./server, ./server/handler, ./mcp
- Directory re-exports target explicit
index.ts paths when they are part of the public root surface; do not rely on the build rewriter to guess a package-consumer contract.
Documentation Gates
Run these when documentation, examples, generated references, or public declarations changed:
bun run verify:documentation
bun run verify:markdown-doctests
bun run verify:jsdoc:doctests
Use bun run verify:jsdoc:full when exported declarations or public JSDoc changed.
When a release changes package.json or src/version.ts, also run:
bun run verify:release-version
The version gate keeps the package version, exported VERSION, and OpenAPI/OpenRPC/AsyncAPI/MCP discovery defaults in sync.
When Service Worker, IndexedDB, WebExtension, browser runtime recovery, or CI browser-gate wiring changes, run the real-browser smoke gate instead of relying only on fake-IndexedDB unit tests:
WEFT_BROWSER_SMOKE=1 bun test src/service-worker/service-worker-browser.test.ts
When touching gate orchestration, benchmark wiring, or generated gate output, run the focused gate tests before the broader loop:
bun test scripts/run-gates.test.ts
Keep benchmark-only commands out of publish gates unless a release workflow explicitly invokes them; prepack should prove package contents and consumer compatibility, not long-running benchmark health.
Package Gates
Run these when package exports, build exclusions, publish workflow, public subpaths, optional dependency isolation, JSDoc examples, or consumer install behavior changed:
bun run prepack
npm publish --dry-run --ignore-scripts
prepack is the repository package contract: build, export and portability checks, Markdown and JSDoc doctests, package-content validation, and packed-consumer checks. The publish dry run uses --ignore-scripts because the release workflow runs prepack explicitly before publishing with ignored package lifecycle scripts.
Release pipeline changes must also prove package.json.version, the exported VERSION, and the release tag agree with bun run scripts/verify-release-version.ts --tag=<tag>; the GitHub release workflow runs bun run validate before publish.
Phase 6: Diff Review
git diff
Check for:
- Leftover
console.log or debug statements
- Unrelated changes that crept in
- Hardcoded values that should be configurable
any types at trust boundaries (server routes, storage interfaces, public API)- Files that were accidentally modified
Quick Shortcut
For a single command that covers phases 1-4:
bun run validate
This runs lint + typecheck + test. Follow up with a manual export review and diff review (phases 5-6).
