git:20260702.0356cda to git:20260703.aaa9f67

- # CLAUDE.md

-

- Operational guidance for AI assistants (and humans) working **on** this

- repository. This is the SOTA-skills library — Markdown skills that an AI

- assistant reads to build and audit software. There is no application to run;

- changes are edits to Markdown held to a few hard invariants. See

- [CONTRIBUTING.md](CONTRIBUTING.md) for the full conventions.

-

- ## Landing a change

-

- `main` is a protected branch and **direct pushes are rejected for everyone**

- (admin enforcement is on). Every change goes through a pull request:

-

- 1. `git checkout -b <branch>`

- 2. make the edit, then run `./scripts/check-invariants.sh`

- (and optionally `pre-commit run --all-files`)

- 3. push the branch and open a PR

- 4. both required checks must pass, then squash-merge

-

- ## Invariants (enforced in pre-commit and CI)

-

- `scripts/check-invariants.sh` fails the build on:

-

- 1. any tracked `*.md` over **500 lines**;

- 2. any `skills/*/rules/*.md` whose **last `## ` heading isn't

- `## Audit checklist`** (the checklist must end the file);

- 3. an **internal-name denylist** — the library must stay generic. The private

- patterns are deliberately untracked (git-ignored `.denylist.local` locally,

- `SOTA_DENYLIST` secret in CI); without them only the generic

- reader-assumption phrases are checked, e.g. on external fork PRs;

- 4. any `skills/*/SKILL.md` **`description` over 1024 characters** — the Agent

- Skills spec cap; loaders silently skip a skill whose description exceeds it

- — or an unquoted inline description containing `: ` (invalid YAML; strict

- loaders reject the skill — use `description: >-`).

- (Needs `python3`; skipped with a warning if absent locally, enforced in CI.)

-

- Secrets are scanned by **gitleaks** (`.gitleaks.toml`, which disables only the

- noisy entropy-based `generic-api-key` rule so the security skills' intentional

- secret-shaped examples don't false-positive). CI scans the **full git history**

- (`gitleaks git` on a `fetch-depth: 0` checkout), not just the working tree; the

- pre-commit hook scans each commit locally.

-

- ## Conventions that matter

-

- - **Keep it generic.** Never commit personal or company-specific stacks or

- project names, and never phrase guidance as an assumption about the reader's

- setup. Products appear only as neutral examples ("e.g. PostgreSQL").

- Personalization lives in a local `profiles/<you>.md`, which is git-ignored

- (`profiles/*` except `profiles/example.md.template`) and must never be

- committed.

- - **Verify claims.** Fast-moving facts (versions, specs, advisories) are checked

- against a primary source and cited; uncertain items are marked

- "needs verification", never asserted.

- - **Skill anatomy.** `skills/sota-<domain>/SKILL.md` (two-field frontmatter —

- `name` + `description`; BUILD/AUDIT workflows; top-10 non-negotiables; a rules

- index) plus `rules/NN-topic.md` files, each ≤ 500 lines and ending in an

- `## Audit checklist`. Audit findings use the format

- `file:line | rule | severity | effort | fix`.

-

- ## Pointers

-

- - [CONTRIBUTING.md](CONTRIBUTING.md) — full contribution guide and PR checklist

- - [RELEASING.md](RELEASING.md) — how to cut a release, including every

- version- and count-bearing surface (README, router, manifests, social

- preview)

- - [SECURITY.md](SECURITY.md) — reporting bad guidance or a leaked secret

- - [CHANGELOG.md](CHANGELOG.md) — release history (top entry = current version;

- also mirrored in `VERSION`)

-