@@ -21,63 +21,13 @@ there and is load-bearing throughout.
2121owns one observability concern, ` bootstrappers/<framework>_bootstrapper.py ` owns one framework's
2222bindings, 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
7528An invariant is a test whose name is the claim, with a docstring opening ` INVARIANT: ` and a second
7629paragraph 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