# Audit

Housekeeping rules, structure and naming conventions, and budgets that keep the repository small, with what each one reports.

`bun run audit` reads the repository and reports findings at three severities. An error fails `bun run check` and CI; a warning or a note is reported and does not fail. `bun run audit --json` prints the same report as data, and the MCP tool `audit` returns it to an agent.

## Housekeeping rules

### Raw literals

A colour, size or spacing value written out in CSS or JSX outside the token files. An error in shared components, a warning in app shell files and in pieces. Reported as `raw-literal`, at error severity at most.

Use a token. If none fits, add one to the theme file; in a piece, list what stays bespoke in its frontmatter with a reason.

### Unused tokens

A token that no stylesheet, component, piece or other token references. A warning for semantic and component tokens; a note for primitive scale steps. Reported as `unused-token`, at warn severity at most.

Remove the token from every theme, or use it. Scale steps kept for completeness can stay.

### Unused shared components

A component exported from src/blocks that no other file imports, registers for MDX or uses. A barrel re-export does not count as a use. Reported as `unused-component`, at warn severity at most.

Delete it, or register it in src/blocks/mdx.tsx if pieces should use it.

### Unregistered block kinds

A block kind in the shared registry that no component declares as its `block`. Reported as `unused-block`, at warn severity at most.

Remove the kind from BLOCKS, or declare it on the component that implements it.

### Near-duplicate components

Two component files, shared or in pieces, that export the same name stem (FigureCard, FigureCardV2) or whose source is at least 80% alike by three-token shingles. Reported as `near-duplicate`, at warn severity at most.

Merge into one shared block. A bespoke component a second piece needs moves to the shared registry in that pull request.

### Orphaned assets

A file under public/ or in a piece folder whose name appears in no source or content file. Reported as `orphan-asset`, at warn severity at most.

Delete the file, or reference it from the piece that owns it.

### Piece boundaries

A piece importing from another piece's folder, or any file outside a piece folder (shared code under src/, scripts) importing from it. Reported as `piece-boundary`, at error severity at most.

Move what is shared into src/blocks and register it; a piece imports only from its own folder and from shared code.

### Pieces overriding shared styles

A piece that redefines a shared token (--ds-_, --lk-_, --color-fd-_) or restyles a layout-kit class (.lk-_) in its own stylesheet. Figure tokens (--pl-\*) may be set only inside the piece's own \[data-piece] scope. Reported as `piece-override`, at warn severity at most.

Change the token in the theme, or extend the shared block. A divergence that stays is listed in the piece's frontmatter with its reason.

### Figure styling written by hand

A stroke width, dash pattern, font size or hex colour written as a literal on an SVG element in a piece or in the plot kit. Drawings are SVG, and take pens, weights, dashes and type from the plot kit (PEN, WEIGHT, DASH, label). Reported as `figure-style`, at error severity at most.

Use WEIGHT, DASH, PEN and label() from src/blocks/plot. For an intended difference, set the --pl-\* token inside the piece's \[data-piece] scope and list it under bespoke in the frontmatter.

### Generated files out of date

A generated file (token CSS and JSON, the reference pages under content/docs/system) that differs from what its generator writes now. Reported as `stale-generated`, at error severity at most.

Run the command named in the finding and commit the result. Never edit a generated file by hand.

### Stale documentation

A hand-written docs page whose `covers` files changed in git after the page did, that covers nothing, or that names a path no file matches. Generated pages are exempt. Skipped in a shallow clone and where there is no git history. Reported as `stale-doc`, at warn severity at most.

Read the page against the changed files, correct what no longer holds, and commit the page. A page that needs no change is touched by a commit that says so.

### Budgets

A count over its budget in src/audit/config.ts: shared block kinds, tokens per tier, non-blank lines of bespoke code in one piece folder. Reported as `budget`, at error severity at most.

Consolidate until the count is under budget. Raising a budget is an edit to src/audit/config.ts, argued in the pull request.

### Shared unit without a spec

A shared block, layout or template with no spec in the catalog, or one missing its summary, use, avoid, inputs or example. Reported as `missing-spec`, at error severity at most.

Add the spec beside the unit (src/blocks/kit/specs.ts for blocks, layout-docs.ts for layouts, `docs` on a template) and fill every field.

### Compact without a short form

A block set compact (its own `size="compact"`, or inside a Section that is) whose text field is declared `require` in its spec and has no short form. Reported as `compact-short-form`, at warn severity at most.

Give the field a short form: `\{ full, short \}` on a prop, or `short` for a quote.

Two component files count as near-duplicates at 80% similarity. The MCP tool `find_similar` runs the same comparison against a proposed name, description or source before a block is added.

## Structure and naming

Each convention is one entry in `src/audit/structure.ts`, checked over tracked files.

### top-dirs

Top-level directories are content, src, scripts, public, plugin, .github and nothing else. Reported at error severity.

### src-dirs

Directories directly under src are app, auth, blocks, tokens, writing, templates, resume, mcp, audit, catalog, seo, lib.  is allowed at warn level until it is renamed to kit and blocks. Reported at error severity.

### content-dirs

Directories directly under content are docs, home, pieces, resume, ops, people. Reported at error severity.

### dir-name

A directory is one lowercase word where possible, kebab-case otherwise, at most 16 characters. Dot-directories and Next.js route folders under src/app are exempt. Reported at error severity.

### file-name

A file is kebab-case with a base name of at most 24 characters. Exempt: files under src/app (Next.js conventions), dotfiles, tool configuration (_.config._, \*.d.ts, bun.lock) and upper-case Markdown (README, PLAN, CLAUDE, SKILL). Reported at error severity.

### redundant-prefix

A file or directory does not repeat the name of the directory it is in: kit/layout-kit.css is wrong, kit/base.css is right. Reported at warn severity.

### generated-location

A generated file lives in a directory named gen, or is an MDX page that opens with a "Generated from" comment. A directory named generated is a warning until it is renamed. Reported at error severity.

### test-location

A test sits beside its source as \<name>.test.ts or \<name>.test.tsx. No **tests**, tests or test directories and no .spec files. A test with no source of the same name beside it is a warning. Reported at error severity.

### script-name

A file in scripts/ is \<verb>-\<noun>.ts with the verb one of gen, lint, audit, check, build. Reported at error severity.

### package-script

A package.json script is named verb or verb:noun, with the verb one of gen, lint, audit, check, build, dev, start, test, format, typecheck. Reported at error severity.

### piece-folder

A piece is content/pieces/\<slug>/ with an index.mdx; the slug is kebab-case, at most 24 characters. A part of an anthology is content/pieces/\<slug>/\<part>/index.mdx, named the same way, inside a piece that has its own index.mdx; parts do not nest further. Imports into a piece folder from outside it are reported by piece-boundary. Reported at error severity.

### src-depth

Directories nest at most 4 deep under src. Reported at error severity.

Known violations are reported as warnings until renamed.

| Rule                 | Path                         |
| -------------------- | ---------------------------- |
| `generated-location` | `public/tokens/default.json` |
| `generated-location` | `public/tokens/drksci.json`  |

## Budgets

A count over its budget is an error. Budgets are set in `src/audit/config.ts`; raising one is an edit to that file, argued in the pull request.

| Budget                                    | Maximum |
| ----------------------------------------- | ------- |
| Shared block kinds                        | 10      |
| Tokens, primitive tier                    | 48      |
| Tokens, semantic tier                     | 26      |
| Tokens, component tier                    | 85      |
| Lines of bespoke code in one piece folder | 11000   |