AGENTS.md ยท diff

git:20261005.23ade00 to git:20261026.7e3146b

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# Working in this repo
## The twin rule
The `la-*`/`dr-*` commands have one contract and one implementation per ecosystem: the PyPI package in
`python/` (Python target repos) and the npm package in `node/` (TS/JS target repos). Every behaviour observable through a command must be identical in both twins for the languages they
share. The conformance corpus decides: an output that differs from its golden is a bug in the twin, never
in the golden.
Only `shared/` is the source of truth for parameters, defaults, user-facing texts and command surfaces.
Code never hard-codes them; each twin loads its vendored copy of `shared/` at runtime.
## Changing a parameter, finding, flag or rule
1. Edit `shared/`: a schema under `schema/`, a template in `findings.yaml`, a command in `cli.yaml`, a rule
in `conventions.yaml`, a language fact in `languages.yaml`, or a script under `scripts/`.
- 2. Run `scripts/sync-shared` to refresh every twin's snapshot (and the vendored `README.md`/`LICENSE`).
+ 2. Run `scripts/sync-shared` to refresh every twin's snapshot.
A drift test fails until you do.
3. Update every twin's code to match.
4. Add or adjust a conformance case under `conformance/cases/` and list it in `conformance/INVENTORY.md`.
Every `findings.yaml` template must be produced by at least one golden.
## Conformance case kinds
- **neutral**: one expected output, run by every twin.
- **paired**: a per-language fixture overlay (`python/`, `node/`); goldens shared or per language
(`stdout.<language>`).
- **adapter**: one language only.
A case may pin the invoking twin (`twin:`); otherwise its output must not depend on which twin runs it. The
case format is in `conformance/README.md`.
## Goldens
Write goldens only with `LA_UPDATE_GOLDENS=1`, and only with a stated reason in the commit message (a
deliberate behaviour change, or a new case). Review the golden diff like code. Never regenerate a golden to
absorb a difference you cannot explain. Cases marked `golden: manual` pin new behaviour and are edited by
hand. The update mode always runs serially, even with `-n`.
## Versions and the contract hash
The package versions (`python/pyproject.toml`, `node/package.json`) and
`plugin/.claude-plugin/plugin.json` always move together; skills read the expected version from `plugin.json` (`la-doctor --plugin`). Each
snapshot's `CONTRACT_HASH` must equal the hash of `shared/`; `la-doctor --contract-hash` prints the bundled
one. Release only when every twin's version and contract hash agree.
## Dev and test commands
Python twin, in `python/`:
```bash
uv sync
uv run pytest -q # full suite in parallel (-n auto), including the conformance corpus
uv run ruff check src tests
uv run basedpyright src tests
```
npm twin, in `node/` (the conformance runner is the Python one, so it needs `uv sync` in `python/`):
```bash
npm ci
npm run lint && npm run typecheck
npm test # Vitest, including the npm pack smoke test
npm run build && npm run conformance # the corpus through the npm twin's bins
```
Repo-wide: `scripts/sync-shared [--check]`, `scripts/conformance-cross [--twin <python|typescript>]` (every
case through both twins, or through one), `la-arch-check` (this repo's own architecture, from either twin), and
`npx -y @anthropic-ai/claude-code plugin validate plugin`.
Tests run in parallel by default; pass `-n 0` to pytest (also through `npm run conformance` and
`scripts/conformance-cross`) to debug serially. A test never writes to a shared checkout path or a fixed
external path, only under its own temporary directory.
Both twins implement the `dr-*` commands natively for their own language and route each input by its file
language: the other language's files run in the other twin (found by `la-doctor --twin` on `PATH`, else
`uvx`/`npx`), whose output is captured and printed as its block in registry order; `dr-refactor` on the other
language's source hands its raw arguments to that twin. `la-check-conventions` and `la-count-comments` are
neutral: the other language's files come back as a conventions-facts document (`la-check-conventions --language
L --emit facts`, paths on stdin).
`la-typecheck` runs the other language's section as `la-typecheck --language L` in its twin.
Integration tests run a real checker and are deselected by default: `uv run pytest -m integration` in
`python/`, `npm run build && npm run test:integration` in `node/`.