#34

AGENTS.md

@@ -362,6 +362,20 @@ const value =
 - Do not use a leading semicolon for expression statements such as
   `;([...]).forEach(...)`; rewrite the expression to avoid ASI hazards
   explicitly, for example with `void`.
+- Do not insert `void` mechanically before ordinary event-handler or callback
+  calls merely because the callee returns a `Promise`. If the surrounding code
+  already uses a plain expression statement such as
+  `onClick={() => requestActiveTab ('theme')}`, preserve that style unless a
+  local rule or type requirement truly forces `void`. Adding unnecessary
+  `void` is a medium-severity style violation.
+- When fixing formatting, never change operator binding, evaluation order,
+  tuple/comma behaviour, or any other expression structure. A formatting pass
+  that changes how `!==`, `??`, `?:`, `&&`, `||`, or `,` binds is a capital
+  offence.
+- In TypeScript and TSX, do not mechanically verticalise short call tails,
+  short object literals, or short callback bodies that already fit the local
+  line-length and delimiter rules. Expanding compact local code without a
+  readability need is a minor style violation.
 - Use correct British English spelling for new identifiers, filenames,
   component names, helper names, comments, and developer-facing prose unless
   editing an already established American-English API that must keep its
@@ -380,6 +394,82 @@ const value =
 - For this repository, prefer names such as `BehaviourSettingsSection.tsx`, not
   `BehaviorSettingsSection.tsx`.
 
+### Additional style offences and penalties
+
+Use this section for recurrent failure modes that are easy to miss when
+applying the delimiter rules mechanically.
+
+#### Unnecessary `void` before ordinary callbacks
+
+Bad:
+
+```ts
+onClick={() => void requestActiveTab ('theme')}
+```
+
+Good:
+
+```ts
+onClick={() => requestActiveTab ('theme')}
+```
+
+Penalty: medium-severity offence. The code still works, but it pollutes the
+local style and usually signals that the edit was made mechanically rather than
+by reading the surrounding code.
+
+#### Formatting that changes expression structure
+
+Bad:
+
+```ts
+const hasUnsavedChanges =
+    serialiseThemeDraft (draftThemeSlots)
+    !== (serialiseThemeDraft (savedThemeSlots),
+	 draftActiveThemeMode !== savedThemeMode)
+```
+
+Good:
+
+```ts
+const hasUnsavedChanges =
+    serialiseThemeDraft (draftThemeSlots)
+    !== serialiseThemeDraft (savedThemeSlots)
+    || draftThemeMode !== savedThemeMode
+```
+
+Penalty: capital offence. Formatting must never corrupt the meaning of an
+expression.
+
+#### Mechanical vertical expansion of compact local code
+
+Bad:
+
+```ts
+const nextState = {
+    open,
+    activeTab }
+
+setDirtyStates (
+    current => ({
+	current,
+	key:  value }),
+)
+```
+
+Good:
+
+```ts
+const nextState = { open, activeTab }
+
+setDirtyStates (
+    current => ({
+	current,
+	key:  value }))
+```
+
+Penalty: minor offence when semantics stay intact. It is not necessarily
+broken, but it ignores the repository's compact associative style.
+
 ### Frontend delimiter decision table
 
 Use this table before accepting any edited TypeScript or TSX hunk. The table is
@@ -412,6 +502,7 @@ import { Button, Card } from '@/components/ui'
 Rule: named-binding `}` is associative-array-style syntax. It must not be alone
 at the beginning of a line. Prefer keeping `{` with the first binding and `}`
 with the final binding when this fits the line limit.
+Penalty: capital offence. This is one of the core associative-brace rules.
 
 #### Type literals
 
@@ -434,6 +525,8 @@ type Props = {
 
 Rule: type-literal `}` is not a block close. It must stay on the same line as
 the final property unless that would break the hard line limit.
+Penalty: capital offence. Mistaking a type-literal `}` for a block `}` is one
+of the recurring death-class errors.
 
 #### Object literals
 
@@ -474,6 +567,8 @@ const value = useMemo (() => ({
 Rule: object-literal `}` is associative-array-style syntax. It must not be on a
 line by itself. Keep it with the final property, and keep call `)` off the
 beginning of a line.
+Penalty: capital offence. Wrong object-literal `}` placement and wrong call
+`)` placement are both death-class violations here.
 
 #### Destructuring parameters
 
@@ -504,6 +599,8 @@ that spans multiple lines, do not use the Prettier-style `= ({ ... }) =>`
 shape. Put the function parameter list on its own lines. The destructuring `}`
 stays with the final binding. The parameter-list `)` is then allowed and
 required at the beginning of its own line.
+Penalty: capital offence. This pattern is a primary source of repeated TSX
+style regressions.
 
 #### Inline typed destructuring parameter
 
@@ -531,6 +628,8 @@ const RouteTransitionWrapper = ({ user, setUser }: {
 Rule: this is not a separately split parameter-list block. The line break is
 inside the inline type. Keep the type-literal `}` and parameter-list `)` on the
 same line as the final type property.
+Penalty: capital offence. Misclassifying this case means the delimiter review
+has failed at the syntax-role level.
 
 #### Multi-line normal parameter list
 
@@ -558,6 +657,8 @@ const updateDraft = <Key extends keyof Settings,> (
 Rule: when the parameter list itself is split across multiple parameter lines,
 the closing parameter `)` goes at the beginning of its own line before `=>` or
 the return type.
+Penalty: capital offence. This is the main allowed exception for a leading `)`,
+so getting it wrong destroys the whole rule set.
 
 #### Function and callback blocks
 
@@ -586,6 +687,8 @@ const handleSave = () => {
 Rule: block `}` closes executable code, not associative data. Multi-line
 function, lambda, callback, `if`, `for`, `switch`, and similar block braces
 belong on their own line.
+Penalty: capital offence. Confusing block `}` with associative `}` is a
+death-class delimiter error.
 
 #### Function and method calls
 
@@ -609,6 +712,8 @@ const value = compute (
 Rule: call-expression `)` must not be at the beginning of a line. The exception
 for leading `)` applies only to function declaration parameter lists, never to
 calls.
+Penalty: capital offence. A leading call `)` is one of the clearest death-class
+violations in this codebase.
 
 #### JSX closing markers
 
@@ -653,6 +758,8 @@ Good:
 
 Rule: keep `>` or `/>` with the final prop, and keep JSX closing parentheses in
 the local compact form such as `</div>)`.
+Penalty: medium-severity offence. It is usually not semantically broken, but it
+is a conspicuous TSX-style failure.
 
 #### Arrays and tuples
 
@@ -681,6 +788,8 @@ const items = [first, second]
 
 Rule: array and tuple `]` must not be at the beginning of a line. Keep it with
 the final element unless that would break the hard line limit.
+Penalty: capital offence. A leading `]` is forbidden by the same class of hard
+delimiter rule as leading associative `}` and leading call `)`.
 
 #### Single-line braces
 
@@ -705,6 +814,8 @@ Good:
 
 Rule: JavaScript object braces on one line get one inner space. JSX expression
 braces do not get inner spaces.
+Penalty: minor offence. This is not normally semantic breakage, but it still
+counts as a style miss.
 
 #### Final TypeScript/TSX self-review checklist