Verifying changes

Read this when you need to show that a change works before asking for review.

A passing build or an HTTP 200 alone is not proof. Show the user action, the visible result, any persisted or downstream effect, and the empty, failure or permission state the change could break. For a bug, reproduce it before you change anything.

Choose the journey

The verify-tadoku skill at .agents/skills/verify-tadoku/SKILL.md is the procedure for agents and humans. Start from its feature map, .agents/skills/verify-tadoku/references/features/README.md, find the user goal your change affects, and read only that area. The map lists entry points, synthetic accounts, seeded fixtures and known traps. Update the relevant map in the same pull request when navigation, prerequisites or observable behavior change. It is a verification aid, not a deployment catalog; Bazel owns service discovery.

Run it in the development environment

Start a dev-cli branch overlay as described in Development environment, then drive the journey in a real browser through the printed dev url links. Keep the real login, frontend, gateway and API path: no mocked API, injected identity or auth bypass.

• Before a write, check X-Dev-Selected on the API response for your route. A frontend-only branch uses the base API with its branch tenant; require an overlay X-Dev-Backend only when verifying changed API code. Confirm the persisted tenant when proving isolation. Use the matching branch app API host for authv2 or admin writes as well as the branch frontend hostname.
• Accounts belong to your branch tenant. Use its fixture accounts or disposable accounts you own without changing canonical credentials or roles. Change only your tenant's roles and Flipt namespace.
• Finish with dev down for your owner to remove its branch hosts.

Changes to dev-cli routing or synchronization must also pass the gates in .dev/acceptance.md, including affected-service discovery, manifest rendering, HMR, rebuild latency and owner-scoped teardown.

Checks before a pull request

Run the checks for what you changed. Toolchain and repository explains each command.

Changed	Run
Go code	gofmt -w services/, bazel run //:gazelle, bazel run //tools/ci/commentpolicy, then bazel build //services/... && bazel test //services/...
Go imports or packages	bazel run //:gazelle -- -mode=diff, ./scripts/check-tadoku-api-visibility.sh, ./tools/ci/check_tadoku_api_provider_deps.sh, bazel run //tools/ci/repopolicy, bazel build //services/tadoku-api/...
SQL queries	./scripts/generate-sqlc.sh and commit the full output
A TLA+ model, or code a model describes	Update the model, run bazel test //services/tadoku-api/spec/tla/..., and confirm each new property fails against a deliberate bug as described in TLA+ models
OpenAPI contract	Edit the fragments in services/tadoku-api/spec/openapi/, run ./scripts/generate-openapi.sh, then pnpm api:generate in docs/ and pnpm --filter api-client generate and pnpm --filter api-client test in frontend/; commit the bundled openapi.yaml and all generated outputs
Frontend	In frontend/: pnpm --filter <app> exec tsc --noEmit, pnpm --filter <app> lint, then pnpm build
Docs	In docs/: pnpm build and pnpm docs:check
Any file	./tools/ci/check_file_sizes.sh; see Splitting a long file

For tenant image, overlay or lifecycle changes, also run:

bazel build //.dev:tenant_image //services/tadoku-api:dev //services/tadoku-api:worker_dev
kubectl --context homelab-talos-dev kustomize k8s/dev/base |
  kubeconform -strict -summary -ignore-missing-schemas
docker build --platform linux/amd64 -f frontend/apps/authv2/Dockerfile -t tadoku-authv2:base-check frontend
TADOKU_BASE_AUTHV2_IMAGE=tadoku-authv2:base-check node k8s/dev/base/e2e.cjs /tmp/tadoku-base-evidence

The optional TADOKU_BASE_AUTHV2_IMAGE selects a locally built authv2 image for the disposable Docker proof before its first publication; the report records this boundary. It does not change any manifests or shared deployment.

Keep the report outside Git and complete the applicable live gates in .dev/acceptance.md.

Evidence on the pull request

.agents/skills/verify-tadoku/references/pr-evidence.md describes how to publish evidence. In short:

• Record the tested commit and any uncommitted diff, owner and branch, selected URLs, the backend identities you observed, the steps, and expected versus actual results. Name skipped tests, TLS bypasses and anything unverified.
• Put one evidence block in the PR description. Lead with a compact results table, then a visible GitHub coverage-limit warning. Put media and reproduction detail in collapsed sections. Keep failures and skipped checks visible.
• Attach screenshots, and a short recording for multi-step workflows, directly to the PR description with gh pr edit --attach. Inspect the media first and confirm the posted attachments render.
• Keep media and one-off capture scripts out of commits. Never include passwords, cookies, tokens or Secret contents.
• If the code changes after recording, rerun the affected checks or label the evidence with the commit it proves.