agentleFS
ai-ecoverseai-ecoverse/slicc/.agents/skills/verifying-before-push/SKILL.md

verifying-before-push

Skill37 starsChanged 20 days agoApache-2.0View on GitHub

Use when committing, pushing, opening or updating a PR, or when CI fails on lint, typecheck, build, or coverage. Covers the full verification pass (lint → typecheck → test → coverage → build), lint:ci strictness, the boy-scout debt gate (check-touched-exemptions.mjs — complexity, promise safety, and ui back-edges; not part of npm run lint, easy to miss locally), and coverage floors. Also triggered by CI error strings like 'check-touched-exemptions' failure, 'biome found errors', or 'below configured minimum coverage'.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 6 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run the full verification pass before committing, pushing, or opening or updating a PR.

    line 9
  2. Very specific:

    Run npm run verify first because formatting is the most common CI failure.

    line 26
  3. Distinctive:

    Run every command in order:

    line 48
  4. Very specific:

    Run npm run lint. It runs biome check --write .

    line 65
  5. Very specific:

    When the gate trips, run the report script and read dist/jscpd/ to find the clone pairs.

    line 116
  6. Distinctive:

    Every shipped app has a hard gate that fails when a declared dependency is not actually used.

    line 131
  7. Distinctive:

    If the merge-base cannot be built (shallow clone, unknown ref) the delta is reported as SKIPPED and only the ceilings are enforced, so you …

    line 202
  8. Distinctive:

    Run this separate gate after lint:

    line 239
  9. Distinctive:

    When a PR touches any file still on one of those debt lists, this gate fails unless, in the same change, you pay the file's debt down and …

    line 271
  10. Distinctive:

    Treat all seven as one-way ratchets: never add a file to a debt list to silence it — the gate also fails when a PR grows any list vs the …

    line 287
  11. Very specific:

    Run npm run test:coverage to enforce the per-package floors from coverage-thresholds.json.

    line 303
  12. Very specific:

    If local checks pass but CI still fails, inspect .github/workflows/ci.yml.

    line 399

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

verifying-before-push

Run the full verification pass before committing, pushing, or opening or updating a PR. These commands mirror the CI gates in .github/workflows/ci.yml; running them locally first is the fastest way to avoid a red PR.

Quick Reference

npm run verify
npm run typecheck
npm run test
npm run test:coverage
npm run build
npm run bundle-size
node packages/dev-tools/tools/check-touched-exemptions.mjs

Run npm run verify first because formatting is the most common CI failure. Do not omit the separate check-touched-exemptions.mjs command: npm run verify does not include it. npm run bundle-size needs the build to have run first — it measures files in dist/.

Pre-push lint gate (automatic)

The .husky/pre-push hook runs the full CI lint gate automatically before every push to a feature branch. It mirrors every check from the CI lint job — biome, prettier, custom lint scripts, complexity gate, manifest justifications, and knip dead-code detection — all in parallel (~6 s wall-clock), then the autofix-drift check (below) serially, because it writes.

You can also run it manually:

npm run verify                         # Same gate, run on demand

Escape hatch: git push --no-verify bypasses the gate when needed.

The standard pass

Run every command in order:

npm run verify                         # Lint gate (mirrors CI lint job)
node packages/dev-tools/tools/check-touched-exemptions.mjs  # NOT in npm run verify — easy to miss
npm run typecheck
npm run test
npm run test:coverage                  # Enforces minimum coverage thresholds
npm run build
npm run bundle-size                    # Bundle budgets; needs the build above

The check-touched-exemptions.mjs gate runs right after lint because it catches grandfathered debt that lint alone misses. See the section below for details.

Lint

Run npm run lint. It runs biome check --write . over JS/TS/JSON/CSS and prettier --write . over the remaining doc / config-text formats (Markdown, YAML, HTML), then lint:docs (CLAUDE.md size limits), lint:skills (tessl SKILL.md lint), lint:skill-router (developer-skill router and alias sync), lint:no-innerhtml, lint:layer-back-edges (no new imports pointing up a per-package layer stack — baseline-ratcheted; fix the layering, never grow layer-back-edge-baseline.json or layer-back-edge-baseline-{node-server,cloudflare-worker}.json), lint:no-float-probes (the ten names in check-no-float-probes.mjs's FLOAT_PROBE_NAMES — isExtensionRealm, isChromeExtensionRealm, hasLocalNodeServer, resolveFloatTopology, getChromeExtensionRealm, setChromeExtensionRealm, hasChromeRuntimeConnect, canConnectToChromeRuntime, getExtensionDelegateId, setExtensionDelegateId — plus the raw __slicc_connect_mode global-bag key; no new read under scoops/, tools/, kernel/ except kernel/host.ts / kernel/kernel-worker.ts — baseline-ratcheted, starts empty; ask the injected CapabilityBroker instead, never grow float-probe-baseline.json), lint:record-string-unknown (no new Record<string, unknown> in non-test source — baseline-ratcheted; name the shape, or suppress a genuinely untyped payload with // biome-ignore lint/plugin: <reason>, never grow record-string-unknown-baseline.json), lint:patches, lint:swift-pins (GitHub SPM packages dual-pinned in Package.swift and xcodegen project.yml must overlap — see packages/dev-tools/swift-pin-reconcile/), lint:swift-deps (SPM unused-dependency gate — see below), lint:swift-forbidden-imports (widget hosts / SliccWidgetKit must not import WebRTC — see below), lint:dead-flags (registry vs isFeatureEnabled / getFeatureValue / Cherry host / worker overlay keys; waiver // unused-flag-ok), and lint:duplication.

CI runs the check-only/strict equivalents (npm run lint:ci) as a hard gate and will reject any unformatted code. This is the most common CI failure — do not skip it.

CI then runs npm run lint:autofix-drift, which fails if biome check --write changes any file. biome check only fails on errors, but --write applies every safe fix, including those of warn/info rules, so a violation of one of those passes lint:ci yet gets rewritten by every local npm run lint — re-dirtying every worktree. Such violations land through commits that skip the pre-commit hook (GitHub web UI, Copilot Autofix). Fix: npm run lint, commit.

Duplicate-code gate (lint:duplication)

npm run lint:duplication runs jscpd against jscpd.json and fails when total duplicated lines exceed the threshold there. It is chained into both lint and lint:ci, so the CI lint job and the pre-push gate both enforce it — there is no separate CI job.

Coverage spans all seven shipped applications: TypeScript/JS for packages/webapp, packages/node-server and packages/cloudflare-worker, Swift for packages/swift-launcher, packages/swift-server and packages/ios-app, and Go for packages/slicc-cli.

npm run lint:duplication               # The gate (silent unless over threshold)
npm run lint:duplication:report        # Browsable HTML + JSON clone report in dist/jscpd/

When the gate trips, run the report script and read dist/jscpd/ to find the clone pairs.

The threshold is a one-way ratchet, held just above the measured baseline in the same spirit as coverage-thresholds.json. Lower it as duplication is paid down; never raise it to turn a red run green.

packages/dev-tools/tools/duplication-config.test.mjs guards the config itself: it asserts every application path is still scanned with a non-zero file count, so an over-broad ignore entry cannot silently drop an app from the signal.

jscpd's config parser prints a harmless unknown field '$comment' warning for the rationale key in jscpd.json. That is expected — do not silence it by deleting the key.

Unused-dependency gates (all three toolchains)

Every shipped app has a hard gate that fails when a declared dependency is not actually used. Run the one for the tree you touched:

npm run deadcode                       # knip: TS/JS workspaces (unused + unlisted deps)
npm run lint:swift-deps                # SPM: packages/*/Package.swift vs the import graph
cd packages/go-optel  && make tidy-check   # go mod tidy -diff
cd packages/slicc-cli && make tidy-check   # go mod tidy -diff

lint:swift-deps (check-swift-unused-deps.mjs) is chained into lint / lint:ci, so the CI lint job enforces it with no Swift toolchain needed — the manifests are parsed as text. It reports unused-package-dependency, unused-target-dependency, and unlisted-dependency (a module imported but reached only transitively — declare it on the target that imports it). Fix the manifest rather than the gate; a product that is genuinely linked without being imported gets a // unused-dep-ok: <reason> annotation on its declaration line. Full semantics: dev-tools-details.md#swift-unused-dependency-gate.

lint:swift-forbidden-imports (check-swift-forbidden-imports.mjs) is the Swift/iOS layering gate: SPM modules are the stack, public is the cross-module surface, and widget hosts / SliccWidgetKit must not import WebRTC (or SliccTrayFollower / SliccTrayVFS / SliccTrayKit). Also chained into lint / lint:ci. Full semantics: dev-tools-details.md#swift-forbidden-import-gate.

The Go tidy-check targets also run inside each module's make check, which is what the go-optel and slicc-cli CI jobs invoke.

Bundle-size budgets (bundle-size)

npm run bundle-size runs size-limit for the Vite-bundled webapp. Budgets live in the size-limit block of packages/webapp/package.json, next to the code they guard, and are measured on raw (non-brotli) bytes.

The webapp size script also runs packages/dev-tools/tools/check-total-js-size.mjs, which compares all emitted JS with the merge-base on the same machine. Its 128 KiB per-change allowance in packages/webapp/total-js-budget.json flags large new dependencies or duplicate chunks, while the 27 MiB size-limit cap is the absolute backstop. The 2026-09-25 measured output was 25,707,983 B across the whole webapp, leaving 2,603,569 B (9.2%) under that cap. When the absolute cap needs adjustment, reset it with meaningful headroom rather than rounding it up by a few bytes; document the measured output and reason in the PR body.

The script then runs packages/dev-tools/tools/check-first-load-size.mjs, which measures the EAGER import closures fetched on a cold-cache boot (the page entry graph and the kernel-worker graph). A static import that hoists an existing lazy chunk into the boot graph fails this gate even though no single file grew — make the import dynamic.

This check is relative, not an absolute budget. It builds your change's merge-base in a throwaway git worktree (your working tree is never touched) and compares, so it fails only when your change grows a graph by more than maxDeltaKb in packages/webapp/first-load-budget.json. You will not inherit someone else's regression, and the number reproduces locally: both sides are built on the same machine in the same run, which cancels the ~1 kB difference between a Linux CI build and a macOS one. The baseline costs ~4 s: the worktree gets a dependency tree whose workspace packages point at its OWN source (never the caller's, or a webcomponents change would measure as 0 kB), then the same prerequisite workspace builds the root postinstall runs, then the webapp build.

node packages/dev-tools/tools/check-first-load-size.mjs                    # vs origin/main
node packages/dev-tools/tools/check-first-load-size.mjs --baseline=none    # ceilings only
node packages/dev-tools/tools/check-first-load-size.mjs --json             # just measure
node packages/dev-tools/tools/check-total-js-size.mjs --json              # total JS bytes and file count

If the merge-base cannot be built (shallow clone, unknown ref) the delta is reported as SKIPPED and only the ceilings are enforced, so you are not blocked locally. In CI on a pull request that same condition is a hard failure — the merge queue deliberately does not re-check the delta, so a PR whose baseline could not be built must not be waved through with its growth unmeasured. Re-run if it looks transient. os/cpu-constrained native binaries the change removes, or that npm does not install on the measuring host, do not count toward that guard. A reviewed dependency-family upgrade that exceeds the baseline's 25-package realignment guard may pin its exact lockfile SHA-256 in both webapp budget files, with a written reason; only that guard failure can then use the absolute caps in CI. Verify this path with GITHUB_EVENT_NAME=pull_request GITHUB_BASE_REF=main npm run bundle-size, and remove the exception after the upgrade merges.

On merge_group the delta is deliberately not applied. A queue branch is cumulative — it carries every PR up to its position — so its delta is the SUM of the batch, not one change's growth, and a per-change allowance would fail on queue depth (observed batches hit +3.8 kB while their individual PRs measured 0.1-1.9 kB). The ceilings are the right check there, and every PR in the batch was already delta-gated against its own merge-base.

The *EagerCeilingKb values in the same file are the absolute backstop, since a delta gate alone would let many small under-threshold changes creep upward forever. They are a deliberate cold-boot limit, not a number to nudge when a build goes red: tighten them freely as payloads shrink, and raise one only with a reason in the PR body.

It reads built output, so run npm run build first. CI enforces it in the bundle-size job, which builds the webapp itself.

The size-limit budgets are ratchets like the duplication threshold: tighten them as payloads shrink. Raising one needs a justification in the PR body.

Renovate PRs are the exception: nobody edits them, so a bump that overshoots a tight budget (e.g. the extension service worker) would stall red. .github/workflows/renovate-bundle-size-reconcile.yml builds each npm Renovate PR and runs packages/dev-tools/tools/bundle-budget-reconcile.mjs --write, which raises an exceeded budget to the measured size (rounded up, same unit) when the overshoot is ≤ 50 kB, and comments/fails for a human above that.

Boy-scout debt gate (check-touched-exemptions.mjs)

Run this separate gate after lint:

node packages/dev-tools/tools/check-touched-exemptions.mjs

CI's lint job runs this step after lint:ci. It is not part of npm run lint, so it is easy to miss locally.

The gate enforces seven "debt lists" of files grandfathered out of a rule:

  • complexity.noExcessiveCognitiveComplexity (biome.json overrides; cap: cognitive complexity ≤ 25)
  • complexity.noExcessiveLinesPerFunction (biome.json overrides; cap: ≤ 150 lines per function)
  • nursery.noFloatingPromises (biome.json overrides; promises must be awaited, returned, or explicitly handled)
  • nursery.noMisusedPromises (biome.json overrides; promises cannot stand in for synchronous callbacks or conditions)
  • Layer-stack back-edges (packages/dev-tools/tools/layer-back-edge-baseline.json and layer-back-edge-baseline-{node-server,cloudflare-worker}.json; cap: 0 new imports pointing up the matching stack — webapp fs → shell/git → cdp → tools → core → scoops → ui, node-server transport → services → entry, cloudflare-worker shared/links/auth → routes → entry)
  • Float/topology probes (packages/dev-tools/tools/float-probe-baseline.json; cap: 0 reads of the ten names in check-no-float-probes.mjs's FLOAT_PROBE_NAMES plus the raw __slicc_connect_mode global-bag key, under scoops/, tools/, kernel/ except kernel/host.ts / kernel/kernel-worker.ts — ask the injected CapabilityBroker instead)
  • Untyped string-keyed bags (packages/dev-tools/tools/record-string-unknown-baseline.json; cap: 0 Record<string, unknown> in non-test source)

When a PR touches any file still on one of those debt lists, this gate fails unless, in the same change, you pay the file's debt down and remove its entry:

  • Biome lists: fix every violation of the named rule, then delete the file's entry from the corresponding biome.json overrides block.
  • Back-edge baseline: remove every up-the-stack import from the file (move the pure helper into the lower layer), then run node packages/dev-tools/tools/check-layer-back-edges.mjs --update.
  • Float-probe baseline: ask the injected CapabilityBroker (or take a composition-time answer) instead of reading the probe directly, then run node packages/dev-tools/tools/check-no-float-probes.mjs --update.
  • Record<string, unknown> baseline: replace every occurrence in the file with a named type for the shape you actually accept (or, for a genuinely untyped payload, a // biome-ignore lint/plugin: <reason> line), then run node packages/dev-tools/tools/check-record-string-unknown.mjs --update.

Treat all seven as one-way ratchets: never add a file to a debt list to silence it — the gate also fails when a PR grows any list vs the base ref. The gate auto-skips on merge_group / push events (it resolves the merge-base against $GITHUB_BASE_REF), so always run it locally before pushing if you touched a listed file.

For warning-only cleanup PRs, this means "lint warning count down" is not enough: if you touch a debt-listed file, you must fully pay down that file's debt in the same PR or avoid touching that file.

To check whether a file is exempt, search biome.json for its path under a single-rule "off" override, and layer-back-edge-baseline.json / layer-back-edge-baseline-*.json / float-probe-baseline.json / record-string-unknown-baseline.json for its path key.

Coverage

Run npm run test:coverage to enforce the per-package floors from coverage-thresholds.json. See writing-slicc-tests → Enforce Coverage for how the floors are maintained by the nightly ratchet and for the per-package and Swift commands.

Native gates (Swift / Go)

npm run verify covers only the JS/TS tree. The five native CI jobs (swift-server, swift-optel, swift-launcher, ios-app, slicc-cli) have their own gates; run them when you touched a native package:

npm run lint:swift                     # SwiftLint across all four Swift/iOS packages
npm run lint:swift:format              # swift format lint --strict (config: root .swift-format)
npm run format:swift                   # swift format --in-place (fixes the above)
npm run deadcode:swift                 # Periphery on the 3 SPM packages (informational)
npm run lint:swift-deps                # SPM unused-dependency gate (hard gate, in lint:ci)
npm run lint:swift-forbidden-imports   # widget WebRTC denylist (hard gate, in lint:ci)
cd packages/slicc-cli && make check    # gofmt + tidy-check + vet + golangci-lint + race + coverage

ios-app has no package.json, so its Periphery scan lives only in its CI job — knip.json (off-limits to hand-edits here) does not allow periphery as a root-script binary, unlike the per-package scripts, which sit inside knip's ignore list.

swift format ships with the Swift 6+ toolchain — no install step. It is a formatter; SwiftLint remains the linter, and the two configs are deliberately consistent (4-space indentation, 160-column lines).

Swift coverage floors come from the same coverage-thresholds.json as the TypeScript ones:

./packages/dev-tools/tools/swift-coverage-check.sh packages/swift-server SliccServerPackageTests
./packages/dev-tools/tools/swift-coverage-check.sh packages/swift-optel SwiftOptelPackageTests
./packages/dev-tools/tools/swift-coverage-check.sh packages/swift-traykit SliccTrayVFSPackageTests
./packages/dev-tools/tools/swift-coverage-check.sh packages/swift-launcher SliccstartPackageTests
./packages/dev-tools/tools/swift-coverage-check.sh --xcodebuild SliccFollower packages/ios-app SliccFollower

ios-app cannot use swift test (its WebRTC dependency is iOS-only), so it takes the script's --xcodebuild mode, which runs xcodebuild test on a simulator and reports over the same llvm-cov path as the SPM packages. See packages/ios-app/CLAUDE.md for the simulator prerequisites.

Stacked PRs

A PR whose base is another topic branch (not main) now gets verification CI on every push. ci.yml's pull_request trigger has no branch filter, so every base runs the workflow.

What runs on a stack:

  • The same path-filtered jobs as a main-based PR, including the cheap swift-* coverage/lint jobs and ios-app (SwiftLint + swift format).
  • Not ios-app-tests (the 4-way simulator matrix). Those 15–38 min cells stay main-only so a stack does not burn simulator minutes or wait for a macOS runner. After you retarget to main, they run there.
  • Not staging mutation. The deploy lives in ci.yml's cloudflare-worker job (RUN_CLOUDFLARE_STAGING), not only in worker-staging.yml. Stacked runs still build, dry-run, typecheck, and coverage-gate the Worker; they skip turnstyle, R2 archive, deploy, secrets, and smoke. worker-staging.yml stays branches: [main].

CI measures a stacked PR's first-load delta against its own base (origin/<base>). Locally on a stack, pass --baseline=origin/<parent> to check-first-load-size.mjs — the workspace size script does not forward extra args.

The aggregate job reports as ci-stack, not ci. The ruleset on main requires exactly one context, ci. Documented GitHub behaviour is that a required check skipped by if: still satisfies branch protection (status checks); this change does not rely on that — stacked runs never mint a check named ci. After a retarget, a stacked SHA that had carried ci could otherwise reach main with the simulators never run anywhere (merge-queue non-leaders already skip every macOS job and rely on the PR-level run).

edited is not a trigger. concurrency.cancel-in-progress: true would cancel an in-flight run on a title/body edit, and a no-op run could mint a skipped ci. After you retarget a stack to main, a later synchronize (new commit or rebase/force-push) starts the full main-based set. Close + reopen is the recommended recipe when you have no code change:

gh pr close <n> && gh pr reopen <n>

A PATCH base=main alone does not start CI.

delete_branch_on_merge is false on this repo (owner decision, not part of the stacked-CI change). GitHub therefore does not auto-retarget a child when its parent merges — retarget the child yourself, then close + reopen or push.

Other CI-only gates

If local checks pass but CI still fails, inspect .github/workflows/ci.yml. The cloudflare-worker job runs wrangler deploy --dry-run. This rarely trips for typical changes but lives in .github/workflows/ci.yml if you need it. The bundle-size job is the other CI-only gate; reproduce it locally with npm run bundle-size after the build. All other lint-job gates (knip dead-code) are now covered by the pre-push lint gate (npm run verify).

Trusted runs put most Linux jobs on the org's Cloud Run pools, which have no sudo. A new root-only step must skip itself when id -u / sudo -n true fails, and a new job must be added to the runner lists in ci-critical-path.test.mjs. See docs/verification.md.

Knip fixture exclusion

The dead-code gate uses knip --production to detect test-only dead files. Keep test fixtures out of the production graph without triggering knip's own Remove unused ignore warning. Two mechanisms exist; only one works cleanly:

  • ignoreFiles with !-suffix patterns — does NOT work. The ! suffix is passed directly to picomatch and is not treated as a negation. Using it both fails to exclude the file from the dead-files report and may produce Remove unused ignore hints in the default gate.
  • Negated project patterns in knip.json — the correct approach. Add "!tests/some-fixture.mjs" to the workspace's project array to keep the file out of the production dependency graph and avoid the Remove unused ignore hint in both the default and --production gates.

Whenever a new test fixture triggers a knip dead-file warning, add a negated entry to the relevant workspace's project list in knip.json, not to ignoreFiles.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.