Resolve #104

.agent/rules/comments.md

@@ -1,13 +1,12 @@
 # Comment Rules
 
-Add comments when they make the code easier to understand or maintain. Omit them when the code speaks for itself.
+Add comments when they make the code easier to understand or maintain. Omit them when the code speaks for itself. For prose style within comments, see `writing.md`.
 
 ## Enforce
 
 - Add regular comments to explain **why**, a constraint, domain behavior, or to orient the reader at the start of a non-obvious block
 - Place the comment directly above the code it explains
 - Omit the trailing period in a short single-line regular comment
-- Use plain punctuation only
 - Add doc comments to public and exported functions, methods, and types only when the name and signature alone do not make the behavior or contract clear; describe what it does first, then note constraints, side effects, or non-obvious return or error behavior when needed
 - Start doc comments with a single sentence in active voice and end it with a period
 - Use `// MARK: -` sparingly as a file-level or large-structure navigation aid, mainly in long files
@@ -16,7 +15,6 @@ Add comments when they make the code easier to understand or maintain. Omit them
 
 ## Avoid
 
-- Do not use em dashes (—) in comments
 - Do not restate what the code already says in regular comments
 - Do not use comments as a substitute for good naming
 - Do not add comments above a block when the intent is already obvious from the code
@@ -87,7 +85,7 @@ const sortedItems = items.slice().sort(compareItems);
 
 ```ts
 /** Returns whether the user is authenticated. */
-export function isAuthenticated(): boolean
+export function isAuthenticated(): boolean;
 ```
 
 ```ts

.agent/rules/feature-fetch.md

@@ -9,7 +9,7 @@ Use `feature-fetch` as the typed API layer. Prefer consistent client setup and e
 - Compose only the features you need, in a clear order
 - Handle `tuple-result` values explicitly; prefer the tuple pattern from `.agent/rules/tuple-result.md`
 - Distinguish network failures from request failures when behavior differs
-- Keep request configuration explicit: base URL, headers, timeout, auth
+- Keep request configuration explicit: base URL, headers, and auth; use `signal` for cancellation
 - Keep GraphQL operations in dedicated files and use `gql`
 
 ## Avoid
@@ -22,12 +22,10 @@ Use `feature-fetch` as the typed API layer. Prefer consistent client setup and e
 ## Example
 
 ```ts
-const itemId = 'item-123';
-const itemResult = await apiClient.get('/items/{itemId}', {
+const [isItemOk, itemErr, item] = await api.get<Item>('/items/{itemId}', {
 	pathParams: { itemId }
 });
 
-const [isItemOk, itemErr, item] = itemResult;
 if (!isItemOk) {
 	if (itemErr instanceof NetworkError) {
 		throw new AppError('Failed to connect', { cause: itemErr });
@@ -36,5 +34,5 @@ if (!isItemOk) {
 	throw itemErr;
 }
 
-return item.data;
+return item;
 ```

.agent/rules/feature-state.md

@@ -8,15 +8,15 @@ Use `feature-state` and `feature-react/state` as the default state pattern in pr
 - Name states with a `$` prefix like `$count`, `$status`, or `$selectedId`
 - Use `useFeatureState(state)` when the component needs the raw value and should re-render on changes
 - Use `useCompute(state, compute)` when the component needs a derived value from one state
-- Use `useCombinedCompute(states, compute)` when the view depends on multiple states together
+- Use `useCompute(states, compute)` when the view depends on multiple states together
 - Use `useListener(state, callback)` for side effects driven by state changes
 - Keep state creation and state mutation helpers outside components unless the state is truly local to one component
 
 ## Avoid
 
 - Do not put many unrelated fields into one state object when separate atoms would stay clearer
 - Do not read `state._v` directly in app code when a hook or public API fits
-- Do not use `useFeatureState` and then derive large computed values inline on every render when `useCompute` or `useCombinedCompute` would express the intent better
+- Do not use `useFeatureState` and then derive large computed values inline on every render when `useCompute` would express the intent better
 - Do not use `useListener` for simple rendering; keep it for effects and subscriptions
 - Do not create ad-hoc React state when the feature already has a matching `feature-state` source of truth
 
@@ -25,10 +25,10 @@ Use `feature-state` and `feature-react/state` as the default state pattern in pr
 ### Good
 
 ```tsx
-const label = useCompute($seconds, ({ value = 0 }) => formatSeconds(value));
-const isDisabled = useCombinedCompute(
+const label = useCompute($seconds, (seconds = 0) => formatSeconds(seconds));
+const isDisabled = useCompute(
 	[$status, $selectedId] as const,
-	([{ value: status = 'idle' }, { value: selectedId = null }]) => {
+	([status = 'idle', selectedId = null]) => {
 		return status === 'loading' || selectedId == null;
 	}
 );

.agent/rules/tuple-result.md

@@ -11,7 +11,7 @@ Use `tuple-result` as the default Result pattern when working with repo code tha
 - Treat the first slot as the primary branch condition
 - Handle the error branch explicitly before using the value
 - Use `Ok(...)` and `Err(...)` to construct results
-- Use helpers like `mapOk`, `mapErr`, `match`, `unwrapOr`, and `tAsync` when they make the code simpler
+- Use helpers like `t`, `tAsync`, `mapOk`, `mapErr`, `match`, and `unwrapOr` when they make the code simpler
 
 ## Avoid
 

.agent/rules/vitest.md

@@ -5,10 +5,15 @@ Write tests so they read like small specifications.
 ## Enforce
 
 - Place tests next to the source file they cover
-- Use `.test.ts` or `.test.tsx`
+- Use `.test.ts`, `.test.tsx`, or `.test-d.ts` for type tests
 - Group tests with `describe`
+- Use one top-level `describe` for the unit under test
+- Add nested `describe` blocks only for public members or meaningful behavior categories
+- Include the subject kind in concrete `describe` names, such as `createForm function`, `FlatQueue class`, `listen method`, or `value property`
+- Omit the subject kind from category `describe` names, such as `types`, `validation`, or `dirty tracking`
 - Start `it(...)` descriptions with `should`
 - Keep each test focused on one behavior
+- Prefer 80/20 coverage by default: cover the core contract, important edge cases, and regressions without exhaustive case matrices unless explicitly requested
 - Use Prepare / Act / Assert structure when the test has more than a couple of steps
 - Use `async` / `await` for async tests
 - Cover both success and error paths where behavior matters
@@ -19,20 +24,53 @@ Write tests so they read like small specifications.
 - Do not rely on implicit promises or `.then(...)` chains in tests
 - Do not hide setup inside vague helper names
 - Do not use unclear test names like `works` or `test x`
+- Do not add a kind suffix to category describes that are not testing a concrete package, function, class, method, or property
 
-## Example
+## Examples
+
+### Good
 
 ```ts
-describe('parseInput', () => {
-	it('should parse valid JSON', () => {
-		// Prepare
-		const input = '{"key":"value"}';
+describe('createStore function', () => {
+	describe('types', () => {
+		it('should infer value types', () => {
+			const store = createStore('value');
+
+			expectTypeOf(store.get()).toEqualTypeOf<string>();
+		});
+	});
+
+	describe('set method', () => {
+		it('should notify listeners when the value changes', () => {
+			// Prepare
+			const store = createStore(0);
+			const listener = vi.fn();
+			store.listen(listener);
+
+			// Act
+			store.set(1);
 
-		// Act
-		const result = parseInput(input);
+			// Assert
+			expect(listener).toHaveBeenCalledWith({ value: 1 });
+		});
+	});
+});
+```
 
-		// Assert
-		expect(result).toEqual({ key: 'value' });
+### Avoid
+
+```ts
+describe('store', () => {
+	describe('set method edge cases and notification behavior', () => {
+		it('works', () => {
+			const store = createStore(0);
+			const listener = vi.fn();
+			store.listen(listener);
+			store.set(1);
+			store.set(1);
+			expect(store.get()).toBe(1);
+			expect(listener).toHaveBeenCalledTimes(1);
+		});
 	});
 });
 ```

.agent/rules/writing.md

@@ -0,0 +1,52 @@
+# Writing Rules
+
+Apply these rules to all prose: comments, READMEs, doc strings, PR descriptions, and commit messages.
+
+## Enforce
+
+- Use a colon to introduce an explanation, elaboration, or list that follows naturally from the preceding clause
+- Use a comma or split into two sentences when an em dash would otherwise bridge two independent thoughts
+- Use parentheses for brief asides that do not need to interrupt the sentence rhythm
+- Write in active voice
+- Keep sentences short and direct; one idea per sentence is the default
+- End full sentences with a period; omit the period on short fragments used as labels or list items
+
+## Avoid
+
+- Do not use em dashes (—); replace with a colon, comma, parentheses, or a restructured sentence depending on context
+- Do not use filler phrases ("it is worth noting that", "in order to", "as mentioned above")
+- Do not pad sentences with hedges that add no information ("basically", "essentially", "simply")
+
+## Examples
+
+### Good
+
+```
+This function has two phases: validation and persistence.
+```
+
+```
+Mutable values (arrays, objects) are copied before storing.
+```
+
+```
+Eager validation can feel intrusive before the user has finished filling in the form.
+```
+
+```
+The library works directly without an adapter.
+```
+
+### Avoid
+
+```
+This function has two phases — validation and persistence.
+```
+
+```
+Mutable values — arrays, objects — are copied before storing.
+```
+
+```
+Eager validation can feel intrusive — the user hasn't finished yet.
+```