Skip to content

Commit 63da333

Browse files
authored
docs(agents): drop the fact-placement convention from AGENTS.md (#188)
Where a fact goes, its admission check, the ADR references and the PR-body spec rule all go; doc placement is a domain-modeling convention. The INVARIANT: docstring shape stays.
1 parent 69af309 commit 63da333

1 file changed

Lines changed: 2 additions & 52 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -21,63 +21,13 @@ there and is load-bearing throughout.
2121
owns one observability concern, `bootstrappers/<framework>_bootstrapper.py` owns one framework's
2222
bindings, and `import_checker.py` owns every optional-dependency probe. Read them.
2323

24-
What reading them will not tell you is why four shapes are load-bearing rather than incidental:
25-
26-
- The instrument × framework matrix stays on the **instrument** axis, not a per-framework adapter
27-
axis ([ADR-0002](docs/adr/0002-keep-per-instrument-axis.md)).
28-
- The double-bootstrap guard is an attribute marker, with two known limits accepted
29-
([ADR-0003](docs/adr/0003-teardown-marker-accepted-limits.md)).
30-
- OpenTelemetry's URL-exclusion policy stays in one method reading its siblings, rather than being
31-
contributed per instrument ([ADR-0004](docs/adr/0004-excluded-urls-stay-one-method.md)).
32-
- `orjson` is an opt-in extra ([ADR-0005](docs/adr/0005-orjson-is-opt-in.md)) and
33-
`typing-extensions` is core's only runtime dependency
34-
([ADR-0007](docs/adr/0007-core-declares-typing-extensions.md)) — together, the reason every
35-
surface this library controls installs on free-threaded CPython.
36-
37-
Behaviour detail has no prose home: it lives in the code and in the `INVARIANT:`-marked tests.
38-
Before writing prose about a capability, run the admission check in **Where a fact goes**.
39-
4024
## Workflow
4125

42-
**The spec for a change is its PR body**, not a committed file: why, design, non-goals,
43-
verification, reviewed with the diff. There is no change file and no lane to choose. A trivial PR
44-
(typo, dep bump, formatter, CI tweak) ships a conventional-commit title with no body ceremony.
45-
46-
Two things outlive the PR, and there are exactly two places to put them: an alternative **rejected**
47-
with reasoning becomes an ADR in [`docs/adr/`](docs/adr/) (`NNNN-slug.md`, sequential, with a revisit
48-
trigger), and real work **not scheduled** becomes a GitHub issue. There is no third state, and no
49-
separate truth-home directory — a behaviour change is reviewed with the diff, not promoted to a page.
50-
51-
### Where a fact goes
52-
53-
Four homes, one owner each:
54-
55-
| Home | Holds |
56-
|---|---|
57-
| `lite_bootstrap/` | anything readable from the module — the default |
58-
| a named test | an **invariant**: must stay true, and a change could silently break it |
59-
| `docs/adr/` | a rejected alternative, with the reasoning that would otherwise be re-litigated |
60-
| `README.md` and `docs/` | anything a user needs |
61-
62-
Before writing a line anywhere:
63-
64-
> Can an agent get this by reading `lite_bootstrap/`? → **don't write it.**
65-
> Would a wrong change here fail a test? → it belongs **in the test**, not in prose.
66-
> Does a user need it? → **`README.md` or `docs/`**.
67-
> Otherwise it does not get written.
68-
69-
**Prose about mechanism has no home. There is no file to add a paragraph to.** This file included:
70-
it is always loaded, so a line that restates a docstring, a justfile comment, or `pyproject.toml`
71-
costs every turn and rots in two places at once. This project tempts that failure mode particularly
72-
hard, because the instrument × framework matrix invites a written index of cells that the file
73-
layout already gives you.
26+
Real work **not scheduled** becomes a GitHub issue.
7427

7528
An invariant is a test whose name is the claim, with a docstring opening `INVARIANT:` and a second
7629
paragraph naming **what breaks it** — design rationale, not a report of what this one test catches.
77-
Nothing enforces that docstring shape; it is read at review time. A relative link to an ADR *is*
78-
checked — CI runs lychee `--offline` over every `.md` — but a path named in a docstring or a comment
79-
is not. Both ADRs and `INVARIANT:` docstrings ratchet: nothing prunes a record once its call is
80-
settled. Keeping them lean is a standing habit.
30+
Nothing enforces that docstring shape; it is read at review time.
8131

8232
## Code style
8333

0 commit comments

Comments
 (0)