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
fix: dedupe AGENTS.md rules, pin gstack, bump CI actions, drop Claude-only wording
AGENTS.md stated the error-handling policy twice, in wording that did not quite
agree: one version banned exceptions in hot paths, the other preferred return
codes in critical code. Both nuances are now folded into the single §Error
handling statement, and the Senior-reflexes copy points at it. Same treatment
for 'comments = WHY only' (stated in two sections) and for naming.
Not merged: 'one authoritative source (DRY)' in Engineering discipline and
'at the third copy, centralize' in Refactoring discipline. On inspection those
are complementary — a principle and its actionable trigger — not a duplicate.
gstack now installs at a pinned, verified commit (394db326f2d3, v1.71.0.0 —
cloned and inspected: setup script present, 61 skills). Upstream publishes no
tags and moves daily, so tracking the default branch meant two people
installing a week apart got different environments. Pass --gstack-ref main to
opt back into tracking.
CI actions were three majors behind (checkout@v4, setup-python@v5,
setup-node@v4) and GitHub was already forcing them onto Node 24 with a
deprecation warning. Bumped to v7 across both workflows, runtime to Node 22.
Two 'In Claude Code:' comments became CLI-neutral: the skills now install into
every agent root, so the instruction was wrong, not just narrow.
Copy file name to clipboardExpand all lines: AGENTS.md
+10-8Lines changed: 10 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,20 +26,23 @@ Own the result beyond the edit — local changes have system-level consequences.
26
26
27
27
## Error handling
28
28
29
+
This is the single statement of the error-handling policy. Other sections point
30
+
here rather than restating it.
31
+
29
32
- Never swallow errors silently: no empty `catch {}`, no ignored `Result`, no `_ =`
30
-
-**Rust**: `?`, `map_err()`, or `anyhow::bail!` — `unwrap()` only with `// SAFETY: [proven reason]`
31
-
-**C++**: `std::optional`/`std::expected` over exceptions in hot paths; never `catch(...) {}`
32
-
- At system boundaries (I/O, HTTP, user input, external parsing): always handle explicitly
33
+
-**Rust**: `?`, `map_err()`, or `anyhow::bail!` — `unwrap()`/`expect()` forbidden in production code except on a proven invariant carrying `// SAFETY: [reason]`
34
+
-**C++**: return codes or `std::optional`/`std::expected` over exceptions in hot paths and critical code; never `catch(...) {}`
35
+
- At system boundaries (I/O, HTTP, network, user input, external parsing): always handle explicitly
33
36
- Internal trusted boundaries may `assert`/`debug_assert` in debug, panic in Rust
34
37
35
38
---
36
39
37
40
## Naming & comments
38
41
39
42
-**Language**: English everywhere — code, comments, commits, PR descriptions. One language per repo.
40
-
-**Names**: explicit over short — `processAudioFrame()` > `process()`, `userEmailAddress` > `email`
43
+
-**Names**: explicit over short — `processAudioFrame()` > `process()`, `userEmailAddress` > `email`. One term per concept across the codebase.
-**Comments**: WHY only — hidden constraint, subtle invariant, workaround for a specific bug. Never describe WHAT the code does.
45
+
-**Comments**: WHY only — hidden constraint, subtle invariant, workaround for a specific bug. Never describe WHAT the code does, and never to explain confusing code: simplify the code instead. (One exception, in §Senior reflexes: public interface contracts.)
43
46
-**Dead code**: delete immediately, never comment out. `git log -S "functionName"` recovers any deleted code.
44
47
45
48
---
@@ -81,9 +84,8 @@ Own the result beyond the edit — local changes have system-level consequences.
81
84
<!-- Distilled from Clean Code — Robert C. Martin -->
82
85
83
86
- Preserve behavior, write for the next reader, leave touched code cleaner within scope.
84
-
-Precise names with one term per concept; split boolean flags and mixed abstraction levels out of functions.
87
+
-Split boolean flags and mixed abstraction levels out of functions. (Naming itself: see §Naming & comments.)
85
88
- Separate commands from queries. No hidden side effects.
86
-
- Comments only for rationale or contracts — never to explain confusing code (simplify the code instead).
87
89
- When touching code: remove the smell most likely to make the next change risky or unclear.
88
90
89
91
---
@@ -224,7 +226,7 @@ The rules above are the always-on core. The reflexes below are the full senior p
224
226
225
227
### Safety & static analysis
226
228
227
-
-**Error handling policy** — never swallow silently. Rust: `unwrap()`/`expect()` forbidden in prod except a proven invariant with `// SAFETY:`; prefer `?`/`map_err()`. C++: prefer return codes / `std::optional`/`std::expected` in critical code; never empty `catch(...)`. Errors at system boundaries (I/O, network, user parsing) always handled explicitly.
229
+
-**Error handling policy** — see §Error handling above. It is stated once, there.
228
230
-**RAII (C++)** — no naked `new`/`delete`; `make_unique`/`make_shared`/stack. FFI opaque handles wrapped in a RAII type immediately (no naked handle circulating).
229
231
-**`using namespace` banned at file scope** — in headers (0 exceptions, fully qualify) and production `.cpp` (function scope or explicit alias `namespace fs = std::filesystem;` only).
230
232
-**Sanitizers** in dedicated CI builds: ASan (use-after-free, overflow) + UBSan (signed overflow, null deref) can combine; TSan (data races) separate build; MSan (uninit reads). Rust FFI modules: `cargo miri test` (nightly) catches UB at the `extern "C"` boundary that C++ sanitizers miss.
0 commit comments