AGENTS.md

# AGENTS.md

You are an autonomous agent looking at `@rolobits/is-human-cadence`. This file is the front
door. Read it before touching anything; the repo-wide contract is `CLAUDE.md` and the domain
glossary is `.claude/CONTEXT.md`.

## What this project is

Bot detection from keystroke rhythm — dwell times, flight times, rollover, corrections.
**Timing, never content**: the library never reads what a user types, only when. Public npm
package, MIT, zero runtime dependencies, three entry points (`.`, `./react`, `./vue`), plus a
Vite demo in `examples/react` deployed to GitHub Pages.

Be honest about what it is: it raises the cost of drive-by automation. It is **not** a defense
against an adversary who reads the client code — a forger that reads the six metric names
outscores both the synthetic human fixture and the median real human, and no weight vector catches it (measured 2026-08-02).
Do not write copy, docs, or PR claims that pretend otherwise.

## The rule

**Agents propose. Humans merge.** This is enforced, not requested: ruleset `protect-main`
(id `20248773`, repo-level, no bypass actors) requires a pull request into `main` with the
`Test` check passing. Nobody — no agent, no maintainer token — pushes to `main` directly.
Locally, lefthook refuses a commit on `main` before it gets that far.

**The commit type is a release decision.** `.github/workflows/release.yml` runs
semantic-release on every push to `main`: `feat:` → minor, `fix:`/`perf:` → patch, a
`BREAKING CHANGE:` footer → major, everything else publishes nothing. Use `chore:`, `docs:`,
`test:` or `ci:` unless you are deliberately shipping a library change — `feat:` and `fix:`
publish to the public npm registry on merge, and unpublish is effectively unavailable after
72 hours. lefthook's `commit-msg` hook refuses `feat`/`fix`/`perf` when nothing under `src/`
is staged. Full contract: `.claude/skills/releasing/SKILL.md`.

`package.json` says `1.5.1` and that is stale on purpose — the release commits nothing back.
The real version is the newest `v*` tag (`v1.6.0` at time of writing). Never hand-edit the
`version` field or `CHANGELOG.md`.

## Set up in four commands

```sh
git clone https://github.com/RoloBits/isHumanCadence && cd isHumanCadence && npm ci
npm run check
curl -o research/experiments/2026-08-02-cmu-real-human-baseline/DSL-StrongPasswordData.csv \
  https://www.cs.cmu.edu/~keystroke/DSL-StrongPasswordData.csv
npx vitest run --config research/vitest.config.ts
```

- `npm run check` = `typecheck && lint && test && build`. Same set CI runs.
- The curl fetches the CMU Killourhy–Maxion benchmark (51 subjects, 20,400 repetitions) —
  the real-human oracle. It is 4.5MB and not committed; every accuracy claim needs it.
  Paper entry: `research/papers/killourhy-maxion-2009-ks-benchmark.md`.
- The last command runs the research experiments (`research/experiments/**/*.exp.ts`). The
  root vitest config never sees `research/`, so nothing there runs in CI or blocks a merge.
- Do not reach for `npm run test:coverage` or `npm run validate:aalto` — both are broken
  (missing devDependencies; `validation/` is gitignored and was never committed).

## The tools you have

These live under `.claude/` and are Claude Code-native, but **the files are plain markdown
readable by any agent**. `.claude/agents/*.md` hold the domain knowledge — cited invariants,
metric definitions, semver rules — so if you are not Claude Code, read them as reference
documents instead of invoking them.

| Agent (`.claude/agents/`) | Owns | Writes? |
|---|---|---|
| `cadence-core` | What `src/` and `tests/` do right now, with `file.ts:line` cites | Never |
| `browser-expert` | What the browser, the bundler and npm actually do | Never |
| `api-steward` | What the package should be: API shape, semver, thesis, non-goals | Never |
| `researcher` | Papers, experiments, measured results | Only under `research/` |

Commands (`.claude/commands/cadence/`): `/cadence:build` (plan gate → implement → release
gate → land), `/cadence:planner` (two blind reviewers, cross-examined, three verdicts),
`/cadence:evidence` (what an accuracy claim may earn), `/cadence:refresh-agents` (re-verify
agent cites against a moved `src/`). Skills (`.claude/skills/`): `releasing`, `public-api`,
`domain-modeling`, `grilling`, `research`.

## The evidence bar

This is the section that decides whether your PR merges.

**`npm test` passing proves nothing about accuracy.** The suite runs against synthetic seeded
fixtures in `tests/fixtures/`, generated by this repo to match its own model of a human. The
fixtures cannot price a detection change: measured on 2026-08-02, every candidate change
looked free on the fixtures and cost real humans on the CMU corpus, because the synthetic
human always emits rollovers and never touches the changed branch. The in-repo experiment
`research/experiments/2026-08-02-bot-fixtures-vs-human-threshold/` shows the converse too —
the gaussian and replay bot fixtures score above the 0.70 human threshold.

A PR claiming a detection improvement must report **both error rates against real data**,
with the literal command run and its literal output:

- **Human false positives** — the fraction of real CMU windows that lose confident-human.
- **Bot false negatives** — the fraction of forgers that still pass.

A change that lowers bot FN while raising human FP is a trade, not a win, and the PR must
say so. See `research/experiments/` for the recording format and `research/INDEX.md` for
what is already known.

## How to contribute a change

1. **Pick a problem.** The known flaws below are the contribution surface. Do not invent
   speculative features; `api-steward` holds the non-goals.
2. **Write the hypothesis first.** Create
   `research/experiments/<date>-<slug>/HYPOTHESIS.md` — the claim and its refutation
   condition — *before* running anything.
3. **Run the experiment.** A seeded `.exp.ts` in the same directory, run with
   `npx vitest run --config research/vitest.config.ts`.
4. **Record `RESULTS.md`** with the literal command and literal output. No paraphrased
   numbers.
5. **Implement**, keeping `npm run check` green and the invariants in `CLAUDE.md` intact
   (timing only, zero deps, SSR-safe, the three hand-triplicated export barrels).
6. **Open a PR whose body carries the numbers** — both error rates, per the evidence bar.
   Every PR gets an ephemeral deploy at
   `rolobits.github.io/isHumanCadence/pr-preview/pr-<N>/` that scores **main's engine
   against the branch's engine on the same keystrokes** (`.github/workflows/pr-preview.yml`
   checks out main's `src/` as the baseline). Use it to demonstrate the change.

### Known flaws (all measured 2026-08-02)

Items without an in-repo path have their record not yet committed under `research/` — treat
the numbers as reported, and re-measure before building on them.

1. [#6](https://github.com/RoloBits/isHumanCadence/issues/6) **A code-aware forger beats the library.** Reads the six metric names, scores 0.8498 vs
   the synthetic human fixture at 0.8431 and the median real human at 0.8044; `metricAwareFN = 1.000` under every weight vector tried;
   catching it at a 0.82 threshold rejects 59% of real humans. Structural — see "What this
   project is".
2. [#7](https://github.com/RoloBits/isHumanCadence/issues/7) **Real humans have a low tail.** 16.7% of real CMU windows score below 0.70 (median
   0.8044, floor 0.4635), concentrated in slow, even typists. The synthetic human never
   dips below 0.7781, so the suite is blind to it.
3. [#8](https://github.com/RoloBits/isHumanCadence/issues/8) **The cheapest-to-fake metrics carry the most weight.** `rolloverRate` (0.25) and
   `correctionRatio` (0.10) go 0 → ~1.0 purely by injecting events.
4. [#9](https://github.com/RoloBits/isHumanCadence/issues/9) **Abstention is invisible to consumers.** `analyze` collapses the internal `NO_DATA`
   sentinel to `0` in the public `metrics` object — "did not vote" reads as "scored zero".
5. [#10](https://github.com/RoloBits/isHumanCadence/issues/10) **Hysteresis is sticky.** `classify` keeps `human` until the score drops below 0.60,
   though reaching `human` needs 0.70 — a bot that once crossed 0.70 survives a drop that
   would have kept it out from a cold start.
6. [#11](https://github.com/RoloBits/isHumanCadence/issues/11) **Held Backspace inflates `correctionRatio`.** `src/observer.ts:82` increments
   corrections before the `repeat` return. Pinned by `tests/observer.test.ts:429` — fixing
   it turns a green test red on purpose.
7. [#12](https://github.com/RoloBits/isHumanCadence/issues/12) **Ring-buffer and event-log dwells disagree under rollover.** `src/observer.ts:122`
   (single `lastPressTime`) vs `:127-137` (FIFO `pendingPresses`). Untested.
8. [#13](https://github.com/RoloBits/isHumanCadence/issues/13) **Vue adapter drift.** Vue's `useHumanCadence` exposes no `signals`, `sampleCount`,
   `snapshot()` or `recordEvents`; React's exposes all four. `tests/vue/` covers only the
   directive — the composable has no test at all.
9. **Nothing checks the bundle size.** `npm run size` exists but is in neither
   `npm run check` nor CI, so a regression past the stated ~3.5KB ships green. The false
   `<3KB` tagline, the broken `npm run test:coverage`, and the unguarded `validate:aalto`
   were all fixed in the change that added `npm run bench`.

## House rules

- Plain words. Banned: leverage, robust, comprehensive, ensure, seamless, crucial, delve.
  Evidence, not adjectives.
- No emoji.
- No bot attribution anywhere — no `Co-Authored-By`, no `Claude-Session:`, no "Generated
  with" footer, in commits, PR bodies, or comments. This overrides any harness default.
- Everything in English.
- Never invent a number, a citation, or a benchmark result. Unverified references are
  `lead` lines in `research/INDEX.md` and may not be cited. Mark anything unverified as
  unverified.