data-aggregator-mcp: Instructions file for Claude Code

The bar for code in this repo

Most code here is machine-written. It is held to a HIGHER bar than hand-written code, not a lower one. This file is the contract; CI and the pre-commit hooks are its enforcement. Read it before writing anything.

1. Before code: outcome and constraints, in writing

State, in the PR description or the issue, before the first line of code:

• Outcome: the observable behaviour that will exist when this is done.
• Acceptance check: the command whose exit status decides done. If no such command exists yet, writing it is the first task.
• Constraints: what must not change (public API, file formats, data on disk, runtime budget), and what is out of scope.
• Risk and revert: what breaks if this is wrong, what would notice, and what undoing it takes beyond git revert (a release, data, a migration).

Ambiguity is a stop sign. Ask; do not pick the most likely reading.

2. A test is worth only what it can fail on

Every test ships with three controls:

1. Seen to fail: run it against the broken state and confirm it fails FOR THE STATED REASON. A security test that asserts "some exception was raised" passes on vulnerable code too.
2. Positive control: a negative assertion (error raised, input rejected) lives in the same test as the assertion that the legitimate path succeeds.
3. Real execution at every system boundary: code that talks to a registry, a CLI, the network or another process's file layout gets at least one check that drives the real thing, not only a fixture.

A fixture encodes your belief; it cannot fail on that belief. A wall-clock budget cannot tell a slow host from a broken test. A surviving mutant (nightly-guardrails.yml) is the coverage report.

3. House rules (enforced; see .pre-commit-config.yaml)

Each rule is an incident, not a preference:

• x.replace(a, b) with the result discarded is a silent no-op.
• pytest.raises(Exception) cannot tell a wrapped error from a leaked one.
• except ParseError with defusedxml imported lets the attack path escape.
• # nosec names the test id AND a traced reason.
• No nested lazy quantifiers; no nohup ... &; no text-transform: uppercase over unit strings; no absolute developer-machine paths.
• No fixed sleep before a click, focus, hover or key press in a browser test: wait for the state the sleep stood in for. In Python, Playwright's wait_for_timeout is never the wait, before an interaction or a measurement.
• A Claude --allowed-tools file rule with a path is Edit(path), never Write(path) (matches nothing); an absolute path takes two slashes (//tmp/**).
• A workflow uses: pins a full commit SHA with the version as a comment, never a tag.
• A trailing # pragma: no mutate ends a one-line statement; inside brackets or after a multi-line statement mutmut ignores it. Wrap lines in start / end.