verification-loop

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        # Core engine tests
bun test src/storage     # Storage backend tests
bun test src/mcp         # MCP transport tests
bun test src/server      # Server API tests
bun test src/testing     # Testing infrastructure tests

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).