agentleFS
The-40-ThievesThe-40-Thieves/obsidian-tc/.claude/skills/gates/SKILL.md

gates

Skill13 starsChanged 5 days agoApache-2.0View on GitHub

Run this repo's verification gates before opening a PR — enumerates them from the CI workflows rather than from memory, because several have confusingly adjacent names.

10 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use release.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • MicrosoftSkill

    release

    Use ONLY when the user explicitly asks to cut/publish a Huabu desktop release or tag a version. Performs an outward action — bumps the version in apps/desktop/package.json, commits + annotated-tags vX.Y.Z, and pushes the branch + tag. That tag push auto-builds the macOS/Windows installers and publishes a GitHub Release. Provides `status`, `bump`, `tag-push`, and a one-command `run` (bump → tag-push).

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 9 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Don't trust a number written here — the set changes.

    line 124
  2. Very specific:

    All four build-test legs are required, including ubuntu-24.04-arm — the repo ships an aarch64 binary and production runs Ampere, and vec.ts …

    line 131
  3. Distinctive:

    every required check PRESENT — a path-filtered-away required check reads as clean but never ran

    line 137
  4. Very specific:

    If gh pr merge reports BLOCKED with every real signal green, that is a stale cached verdict (cli/cli#13388).

    line 147

“Common” is measured: kept by at least 6 in 10 of the 9 edited versions of this file we could read. “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

gates

Enumerate from .github/workflows/, never from recall. This repo has 9 bespoke check:* scripts, 5 docgen:* scripts, and 3 generator --check scripts across 18 workflows. Two pairs have names close enough to substitute for each other by mistake:

looks like the same thingis not
check:config-pathssweeps prose for config keys that no longer resolve
config:schema:checkregenerates and diffs docs/reliquary-tc.config.schema.json

Running the first and believing it covered the second cost a full CI round on PR #513. That is the reason this skill exists.

Get the authoritative list

# every gate CI actually runs, from the workflows themselves
rg -n 'run: (bun|node|npx)' .github/workflows/*.yml

drift-gate alone is five steps (ci-docgen.yml) — read them, don't assume.

The usual pre-PR set

bun run lint is ONLY biome check. CI's lint job runs eight steps, and the seven beyond biome are where the interesting failures live. Running the script and believing it covered the job cost a CI round on a past incident. Run the loop:

for g in lint check:boundaries check:dev-dep-imports check:perf-timing-scope \
         check:ingest-telemetry-wiring check:config-paths check:duplicate-exports \
         check:duplication; do
  bun run "$g" > "/tmp/gate-${g//:/-}.log" 2>&1; echo "$g exit=$?"
done

check:boundaries (dependency-cruiser) is the one that catches what typecheck cannot: it rejects an import cycle even when the import is type-only and erased at runtime. Adding a CLI command is the usual way to trip it — put the command's shape inline in the CliCommand union in cli/args.ts and have the command module use Cmd<"my-command"> from cli/shared.ts, never the reverse.

check:comment-style is a ratchet on the COUNT of files with >= 120 comment lines (scripts/comment-style-baseline.json's maxFiles), not a per-file cap — a file may carry a long comment block, it just can't grow the number of such files. On failure it lists every offending file with its current count, worst first, and marks each one NOT already over the threshold on origin/main as new, with main's count:

comment-style gate: 35 file(s) >= 120 comment lines (baseline 34). New since main:
  133  packages/plugin/src/main.ts  (main: 41)
  128  packages/server/src/search/vec.ts

An unannotated line was already over on main — it isn't what regressed the ratchet, don't spend time on it. The main-side count comes from git show origin/main:<file>, so on a shallow clone where origin/main hasn't been fetched yet (this repo's own CI runs test:scripts and check:comment-style before the fetch parity baseline step creates that ref) every file prints (main: ?) instead — the gate still runs and still fails correctly, it just cannot say which offenders are new until the ref exists.

Then the rest, which live in other jobs:

bun run typecheck                  # all 4 workspaces
cd packages/server && node ./node_modules/vitest/vitest.mjs run

bun run check:version
bun run map:check                  # TREE.md + docs/dependency-graph.json
bun run config:schema:check        # NOT check:config-paths
bun run migrations:embed:check
cd packages/server && bun run docgen:render -- --check
cd packages/server && bun run docgen:facts-check

map and map:check derive their inputs from git ls-files; untracked build output such as packages/*/dist and *.tsbuildinfo does not change their output. The dependency-cruiser config also pins workspace resolution to tracked source, so running a build first is safe.

Offload the full suite — don't run it locally

This repo is developed on a 4-core host that also runs ~43 containers, Falco and a remote desktop. A local full-suite run costs the whole box; two at once have driven it to load 28, and a past incident measured an overlapping run reading throughput 51% low while the gate still passed.

Standard GitHub-hosted runners are free and unmetered for public repositories, and this repo is public. The suite that already runs on every PR can be triggered directly:

gh workflow run ci-server.yml --ref <branch>
gh run watch $(gh run list -w ci-server.yml -L1 --json databaseId --jq '.[0].databaseId')

That runs lint, build-test on ubuntu/windows/macos, and bun-smoke on dedicated hardware — and catches the platform-specific failures a Linux-only local run cannot (a chmod 000 test passed on ubuntu and macos and failed only on windows, because Windows has no POSIX mode bits).

perf deliberately does not run on dispatch — it is gated on github.event_name == 'push' because it lives in the non-ref-scoped perf-exclusive group, and ad-hoc runs would cancel main's pending perf jobs.

Keep targeted vitest local. A single test file is faster than a round trip and saturates nothing. What must run locally should go through scripts/with-host-budget.sh (or bun run test:local), which serialises via flock and caps at 2.5 cores.

Never pipe a gate through tail or head

bun run lint 2>&1 | tail -20      # WRONG — $? is the pipe's status
bun run lint > /tmp/lint.log 2>&1; echo "exit=$?"   # right

A pipeline reports the pipe's exit code. This has masked both a failing suite and a failing lint in this repo. Redirect to a uniquely-named log and check $? separately.

Required status checks

Don't trust a number written here — the set changes. Read it:

gh api repos/The-40-Thieves/reliquary-tc/branches/main/protection/required_status_checks \
  --jq '.contexts[]' | sort

All four build-test legs are required, including ubuntu-24.04-arm — the repo ships an aarch64 binary and production runs Ampere, and vec.ts documents a measured retrieval divergence between aarch64 and x86_64 (nDCG@10 0.8028 vs 0.8414 on the same commit).

Green locally is not the merge floor. Gate a merge on:

  1. every required check PRESENT — a path-filtered-away required check reads as clean but never ran
  2. zero in flight
  3. no CANCELLED or TIMED_OUT anywhere, required or not

CANCELLED is a completed conclusion, so "no failures and nothing pending" lets it through. The perf job sits in a non-ref-scoped perf-exclusive concurrency group and loses its run whenever PRs overlap.

perf is deliberately not required — it is push-only and requiring it would deadlock every PR.

If gh pr merge reports BLOCKED with every real signal green, that is a stale cached verdict (cli/cli#13388). Merge via the REST API — not --admin:

SHA=$(gh pr view <N> --json headRefOid --jq .headRefOid)
gh api -X PUT repos/The-40-Thieves/reliquary-tc/pulls/<N>/merge \
  -f merge_method=squash -f sha="$SHA"

Passing sha matters: it refuses if the head moved since you checked. "Green" is a property of a commit, not of a PR.

Adding a gate

A gate that has never failed proves nothing. Before trusting a new one:

  1. Assert a non-empty floor first — expect(files.length).toBeGreaterThan(N). Without it a broken directory walk makes every later assertion pass vacuously.
  2. Watch it fail. Mutate the thing it guards, confirm red, revert, confirm green. Verify the mutation actually applied — a no-op mutation that "passes" is the exact trap.
  3. Normalize path separators — abs.slice(root.length + 1).split(sep).join("/"), or it passes on Linux and fails only on build-test (windows-latest).
  4. Prefer a compile-time gate. Record<K, V> (not Partial) makes an omission fail to compile, which strictly dominates a runtime scan.

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.