You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Welcome, Codex Agent! Your persistence, curiosity, and craftsmanship make a difference. Take your time, work methodically, validate thoroughly, and iterate. This repository is large and tests can take time — that’s expected and supported.
3
+
Welcome, AI Agent! Your persistence, curiosity, and craftsmanship make a difference. Take your time, work methodically, validate thoroughly, and iterate. This repository is large and tests can take time — that’s expected and supported.
4
4
5
-
> **Timebox:** Aim to complete each autonomous run in **15–30 minutes**. Prefer small, verifiable steps and targeted module builds for fast feedback.
5
+
> **Timebox:** Aim to complete each autonomous run in **15–30 minutes**.
6
6
7
7
## Purpose & Contract
8
-
-**Bold goal:** deliver correct, minimal, well‑tested changes with clear handoff.
8
+
-**Bold goal:** deliver correct, minimal, well‑tested changes with clear handoff. No monkey‑patching or band‑aid fixes — always fix the underlying problem at its source.
9
9
-**Bias to action:** when inputs are ambiguous, choose a reasonable path, state assumptions, and proceed.
10
10
-**Ask only when blocked or irreversible:** escalate only if truly blocked (permissions, missing deps, conflicting requirements) or if a choice is high‑risk/irreversible.
11
11
-**Definition of Done**
12
-
- Code formatted and imports sorted.
13
-
- Compiles with a quick profile / targeted modules.
14
-
- Relevant module tests pass; failures triaged or crisply explained.
15
-
- Only necessary files changed; headers correct for new files.
16
-
- Clear final summary: what changed, why, where, how verified, next steps.
12
+
- Code formatted and imports sorted.
13
+
- Compiles with a quick profile / targeted modules.
14
+
- Relevant module tests pass; failures triaged or crisply explained.
15
+
- Only necessary files changed; headers correct for new files.
16
+
- Clear final summary: what changed, why, where, how verified, next steps.
17
+
18
+
### No Monkey‑Patching or Band‑Aid Fixes (Non‑Negotiable)
19
+
20
+
This repository requires durable, root‑cause fixes. Superficial changes that mask symptoms, mute tests, or add ad‑hoc toggles are not acceptable.
21
+
22
+
What this means in practice
23
+
- Find and fix the root cause in the correct layer/module.
24
+
- Add or adjust targeted tests that fail before the fix and pass after.
25
+
- Keep changes minimal and surgical; do not widen APIs/configs to “make tests green”.
26
+
- Maintain consistency with existing style and architecture; prefer refactoring over hacks.
27
+
28
+
Strictly avoid
29
+
- Sleeping/timeouts to hide race conditions or flakiness.
30
+
- Broad catch‑and‑ignore or logging‑and‑continue of exceptions.
31
+
- Muting, deleting, or weakening assertions in tests to pass builds.
32
+
- Reflection or internal state manipulation to bypass proper interfaces.
33
+
- Feature flags/toggles that disable validation or logic instead of fixing it.
34
+
- Changing public APIs or configs without necessity and clear rationale tied to the root cause.
35
+
36
+
Preferred approach (fast and rigorous)
37
+
- Reproduce the issue and isolate the smallest failing test (class → method).
38
+
- Trace to the true source; fix it in the right module.
39
+
- Add focused tests covering the behavior and any critical edge cases.
40
+
- Run tight, targeted verifies for the impacted module(s) and broaden scope only if needed.
41
+
42
+
Review bar and enforcement
43
+
- Treat this policy as a blocking requirement. Changes that resemble workarounds will be rejected.
44
+
- Your final handoff must demonstrate: failing test before the fix, explanation of the root cause, minimal fix at source, and passing targeted tests after.
17
45
18
46
## Environment
19
47
-**JDK:** 11 (minimum). The project builds and runs on Java 11+.
@@ -27,58 +55,58 @@ Welcome, Codex Agent! Your persistence, curiosity, and craftsmanship make a diff
27
55
28
56
**Rule of thumb**
29
57
- ✅ Use `-am`**only** for compile/verify with tests skipped (e.g. `-Pquick`).:
30
-
-`mvn -o -pl <module> -am -Pquick verify`
58
+
-`mvn -o -pl <module> -am -Pquick verify`
31
59
- ❌ Do **not** use `-am` with `verify` when tests are enabled.
32
60
33
61
**Two-step pattern (fast + safe)**
34
62
1)**Compile deps fast (skip tests):**
35
63
`mvn -o -pl <module> -am -Pquick verify`
36
-
2)**Run tests:**
37
-
`mvn -o -pl <module> verify | tail -500`
64
+
2)**Run tests:**
65
+
`mvn -o -pl <module> verify | tail -500`
38
66
39
67
It is illegal to `-am` when running tests!
40
68
It is illegal to `-q` when running tests!
41
69
42
70
## Quick Start (First 10 Minutes)
43
71
1.**Discover**
44
-
- List modules: inspect root `pom.xml` (aggregator) and the module tree (see “Maven Module Overview” below).
45
-
- Search fast with ripgrep: `rg -n "<symbol or string>"`
72
+
- List modules: inspect root `pom.xml` (aggregator) and the module tree (see “Maven Module Overview” below).
73
+
- Search fast with ripgrep: `rg -n "<symbol or string>"`
-`-DfailIfNoTests=false` (when selecting a class that has no tests on some platforms)
136
+
137
+
## Assertions: Make invariants explicit
138
+
139
+
Assertions are executable claims about what must be true. They’re the fastest way to surface “impossible” states and to localize bugs at the line that crossed a boundary it had no business crossing. Use them both as **temporary tripwires** during investigation and as **permanent contracts** once an invariant is known to matter.
140
+
141
+
**Two useful flavors**
142
+
143
+
-**Temporary tripwires (debug asserts):** Add while hunting a failing test or weird behavior. Keep them cheap, contextual, and local to the suspect path. Remove after the mystery is solved **or** convert to permanent checks if the invariant is genuinely important.
144
+
-**Permanent contracts:** Encode **preconditions** (valid inputs), **postconditions** (valid outputs), and **invariants** (state that must always hold). These stay and prevent regressions.
145
+
146
+
**Where to add assertions**
147
+
148
+
- At **module boundaries** and **after parsing/external calls** (validate assumptions about returned/decoded data).
149
+
- Around **state transitions** (illegal transitions should fail loudly).
150
+
- In **concurrency hotspots** (e.g., “lock must be held”, “no concurrent mutation”).
151
+
- Before/after **caching, batching, or memoization** (keys, sizes, ordering, monotonicity).
152
+
- For **exhaustive enums** in `switch` statements (treat unexpected values as hard errors).
153
+
154
+
**How to write good assertions**
155
+
156
+
- One fact per assert. Fail **fast**, fail **usefully**.
157
+
- Include **stable context** in the message (ids, sizes, states) so the failure is self‑explanatory.
158
+
- Avoid side effects in the condition or message. Assertions may be disabled in some runtimes.
159
+
- Keep them **cheap**: no I/O, heavy allocations, or deep logging in the message.
160
+
- Don’t use asserts for **user‑facing validation**. Raise exceptions for expected bad inputs.
161
+
162
+
**Java specifics**
163
+
164
+
-**Enable VM assertions in tests.** Tests must run with `-ea` so `assert` is active.
165
+
- Use **`assert`** for debug‑only invariants that “cannot happen.” Use **exceptions** for runtime guarantees:
166
+
- Preconditions: `IllegalArgumentException` / `Objects.requireNonNull` (or Guava `Preconditions` if present).
167
+
- Invariants: `IllegalStateException`.
168
+
- Prefer treating unexpected enum values as **hard errors** rather than adding a quiet `default` path.
169
+
170
+
**Concrete examples**
171
+
172
+
Precondition (permanent)
173
+
```java
174
+
void setPort(int port) {
175
+
if (port <1|| port >65_535) {
176
+
thrownewIllegalArgumentException("port out of range: "+ port);
177
+
}
178
+
this.port = port;
179
+
}
180
+
```
181
+
182
+
Invariant (permanent)
183
+
```java
184
+
void advance(State next) {
185
+
if (!allowedTransitions.get(state).contains(next)) {
186
+
thrownewIllegalStateException("Illegal transition "+ state +" → "+ next);
187
+
}
188
+
state = next;
189
+
}
190
+
```
191
+
192
+
Debug tripwire (temporary; remove or convert later)
assertThread.holdsLock(this) :"put must hold instance monitor";
212
+
// ...
213
+
}
214
+
```
215
+
216
+
217
+
House rule: Asserts are allowed and encouraged. Removing or weakening an assertion to “make it pass” is strictly forbidden — fix the cause, not the guardrail.
218
+
108
219
109
220
## Triage Playbook
110
221
-**Missing dep/plugin offline**
111
-
- Remedy: **rerun the exact command without `-o`** once to fetch; then return offline.
222
+
- Remedy: **rerun the exact command without `-o`** once to fetch; then return offline.
112
223
-**Compilation errors**
113
-
- Fix imports, generics, visibility; re‑run quick verify (skip tests) in the **module**.
224
+
- Fix imports, generics, visibility; re‑run quick verify (skip tests) in the **module**.
114
225
-**Flaky/slow tests**
115
-
- Run the specific failing test; read its report; stabilize root cause before broad runs.
226
+
- Run the specific failing test; read its report; stabilize root cause before broad runs.
116
227
-**Formatting failures**
117
-
- Run formatter/import/XML sort; re‑verify.
228
+
- Run formatter/import/XML sort; re‑verify.
118
229
-**License header missing**
119
-
- Add header for **new** files only (see “Source File Headers”); **do not** change years on existing files.
230
+
- Add header for **new** files only (see “Source File Headers”); **do not** change years on existing files.
0 commit comments