feat(skills): add gates skill for verification-gate discipline #1309
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,95 @@ | ||
| --- | ||
| name: gates | ||
| description: Pick the smallest correct verification gate for a change in this repo, and prove it actually ran before calling it green. Use before running any `npm run verify:*` or `check:*` command, before reporting a gate as passing, when a gate finishes suspiciously fast or clean, and before trusting any agent or bot claim that a fix landed. | ||
| --- | ||
|
|
||
| # gates — prove it ran, then report it | ||
|
|
||
| A green exit code is not proof. Contended gates can wait a long time before failing, early stops | ||
| leave later checks unrun, and a stale worktree makes healthy-looking runs meaningless. This skill | ||
| exists because those failures have cost real time more than once. | ||
|
|
||
| **Rule: never report a gate as passing without quoting the line that proves it ran.** | ||
|
|
||
| ## The false-green traps | ||
|
|
||
| Check these before believing any result. | ||
|
|
||
| - **`verify:ui` under heavy-lock contention waits, then fails — it does not soft-skip green.** When | ||
| another worktree holds the exclusive lease, `acquireHeavyRunLock` queues Playwright admission for | ||
| up to 15 minutes and throws on timeout; `run-playwright.mjs` catches that error and exits `1`. Do | ||
| not treat a long wait or a red contention timeout as a false-green soft-skip. When the gate does | ||
| run, grep the output for the `N passed` line — exit `0` alone is never proof. | ||
| - **A stale worktree makes every downstream gate a lie.** `check:installed-lock-parity` fails closed | ||
| for exactly this reason — if installed packages do not match `package-lock.json`, treat any test, | ||
| lint, or typecheck result as void until `npm ci` has run. Its own failure message says as much. | ||
| - **`verify:cheap` stops at the first failing check.** Everything after that point never ran. Do not | ||
| describe the change as broadly verified when the gate died at check 2 of 26. | ||
| - **`format:check` is required in CI but is not part of `verify:cheap`.** A locally green | ||
| `verify:cheap` can still fail CI on formatting. Run `npx prettier --write <changed files>` before | ||
| pushing — scoped to your files, never `prettier --write .`, which sweeps the whole tree. | ||
|
Comment on lines
+29
to
+30
Contributor
There was a problem hiding this comment. 🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
file=".claude/skills/gates/SKILL.md"
echo "== line count =="
wc -l "$file"
echo
echo "== relevant excerpt =="
sed -n '1,120p' "$file" | cat -n
echo
echo "== references to prettier/npx/install/lease =="
rg -n "npx|prettier|lease|install" "$file"Repository: BigSimmo/Database Length of output: 8116 🏁 Script executed: #!/bin/bash
set -euo pipefail
python3 - <<'PY'
import subprocess, sys, textwrap, json, os
# Check npm/npx help text if available, without running repository code.
for cmd in [
["npx", "--help"],
["npm", "exec", "--help"],
]:
print(f"\n== {' '.join(cmd)} ==")
try:
out = subprocess.check_output(cmd, stderr=subprocess.STDOUT, text=True, timeout=20)
print(out[:4000])
except Exception as e:
print(f"ERROR: {e}")
PYRepository: BigSimmo/Database Length of output: 3000 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== package files mentioning prettier =="
rg -n '"prettier"|prettier' package.json package-lock.json .npmrc .claude -g 'package*.json' -g '.npmrc' -g '*.md'
echo
echo "== package.json excerpt =="
sed -n '1,220p' package.json | cat -nRepository: BigSimmo/Database Length of output: 20641 Use a local-only Prettier invocation here. 🧰 Tools🪛 SkillSpector (2.3.11)[warning] 29: [RP1] null: npx commands without a version suffix (e.g. Remediation: Pin the version: npx (MCP Rug Pull (RP1)) [warning] 42: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries. Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content. (Memory Poisoning (MP2)) [warning] 43: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries. Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content. (Memory Poisoning (MP2)) [warning] 46: [MP2] Context Window Stuffing: Skill attempts to fill the context window with filler content, displacing legitimate instructions and safety constraints. This can degrade agent performance or bypass safety boundaries. Remediation: Implement context-window management that detects and rejects padding or stuffing attempts. Prioritize system instructions over user-injected content. (Memory Poisoning (MP2)) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||
| - **Piping a gate into `tail` or `head` masks its exit code.** In Bash, capture `${PIPESTATUS[0]}`, | ||
| or check the exit status before piping. | ||
|
|
||
| ## Pick the smallest gate that can fail | ||
|
|
||
| Match the gate to what actually changed. Running a broader gate is not more rigorous if it cannot | ||
| observe the change; running a narrower one is not sloppy if it can. | ||
|
|
||
| | Change | Gate that can actually fail | | ||
| | ----------------------------- | --------------------------------------------------------------- | | ||
| | Markdown / docs only | `prettier --check`, `docs:check-links`, `docs:check-index` | | ||
| | Source, config, tests | `verify:cheap` | | ||
| | Before PR handoff | `verify:pr-local` | | ||
| | UI, styling, routing, a11y | `npm run ensure` then `verify:ui` | | ||
| | Phone chrome | `verify:phone-chrome` (narrower than `verify:ui`; run it first) | | ||
| | Release or handoff confidence | `verify:release` | | ||
|
|
||
| `lint`, `typecheck`, and `test` cannot observe a markdown-only change. Say so rather than running | ||
| them for appearance. | ||
|
|
||
| ## Before any heavy run or install | ||
|
|
||
| The repository run coordinator serialises heavy work across worktrees. Leases live at | ||
| `<os.tmpdir()>/clinical-kb-heavy-locks/<repoId>.lock/leases/`; each holds an `owner.json` with pid, | ||
| mode, and command. | ||
|
|
||
| - An **exclusive** lease means full Vitest, coverage, lint, build, Playwright, or live-provider work | ||
| is running. Do not install and do not start another heavy gate. | ||
| - Never `npm ci` or `npm install` while any repository test, build, lint, typecheck, or server | ||
| command is active — including in another worktree. | ||
| - Never kill a lease-holding process that belongs to another worktree or another agent's session. | ||
| - Check the lease directory rather than scanning the repo tree; ~40 worktrees make recursive scans | ||
| slow and noisy. Do not print raw process command lines. | ||
|
|
||
| ## Provider boundary | ||
|
|
||
| Never run provider-backed gates without explicit user confirmation: `eval:rag`, `eval:quality`, | ||
| `eval:retrieval:quality`, `verify:release`, `check:supabase-project`, `test:live`, and any GitHub, | ||
| Supabase, OpenAI, or hosted-CI call. Report the command and ask instead of running it. | ||
|
|
||
| The only standing exception is the user typing `Run PR`, and that authorises only the GitHub actions | ||
| enumerated in the `run-pr` skill, for that sweep alone. | ||
|
|
||
| ## Third-party claims are not evidence | ||
|
|
||
| A bot or agent saying it fixed something is a claim, not a result. | ||
|
|
||
| - Verify against the actual ref content before repeating it as fact. Prefer refs already available | ||
| locally (`git log`, `git show`); fetching from the remote is a network action subject to the | ||
| provider boundary above. | ||
| - A squash merge breaks ancestry. `git merge-base --is-ancestor` returning false does **not** mean | ||
| the work is missing — compare file content on `origin/main` instead. | ||
| - Absence of evidence in one place is not proof. Grepping `.github/workflows` for `auto-merge` | ||
| returns nothing even though GitHub's per-PR auto-merge is in active use here, because that setting | ||
| is not a workflow file. | ||
|
|
||
| ## Reporting | ||
|
|
||
| State what ran, what passed, and what never ran. | ||
|
|
||
| - Paste the decisive line: `42 passed`, `docs link check passed: 1287 …`, not "gate green". | ||
| - Name the gates that were skipped and why. | ||
| - Separate verified from assumed. If a claim came from memory or a prior session rather than this | ||
| run, say so. | ||
| - Never let output-style compression drop this section. Brevity applies to prose, never to proof. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.