@dynokostya/just-works 1.0.0

package/.claude/skills/typescript-coding/SKILL.md

@@ -0,0 +1,464 @@
+---
+name: typescript-coding
+description: Apply when writing or editing TypeScript (.ts) files. Behavioral corrections for error handling, async patterns, type system, module system, security defaults, and common antipatterns. Project conventions always override these defaults.
+---
+
+# TypeScript Coding
+
+Match the project's existing conventions. When uncertain, read 2-3 existing files to infer the local style. Check `tsconfig.json` for `strict` mode, `target`, `module`, and `moduleResolution` settings. Check `package.json` for runtime (Node.js, Deno, Bun) and dependency versions. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent bugs and vulnerabilities regardless of project style.
+
+- **Never use `any`** — contagious type erasure that disables all downstream checking. Use `unknown` and narrow with type guards, or use generics with constraints.
+- **Never use `@ts-ignore`** — permanently suppresses errors with no feedback when conditions change. Use `@ts-expect-error` with a justification comment; it fails the build when the suppressed error disappears.
+- **Never use `==` for equality** — implicit type coercion produces unintuitive results (`0 == ''` is `true`). Use `===` and `!==`. The only acceptable exception is `x == null` to check both `null` and `undefined`.
+- **Never use `as` type assertions on external data** — zero runtime validation; the program continues with corrupted state until it crashes far from the source. Validate at system boundaries with Zod `safeParse` or equivalent runtime validators.
+- **Never use `!` non-null assertion without proof** — tells TypeScript a value is not `null` without any runtime check. Use nullish coalescing (`??`), optional chaining (`?.`), or explicit `if` checks.
+- **Never use `eval()` or `new Function()`** — executes arbitrary strings as code, enabling injection attacks. Use `JSON.parse` for data, lookup tables for dispatch, and proper parsers for expressions.
+- **Never leave a Promise floating** — unhandled rejections cause silent failures or process termination. Always `await`, chain `.catch()`, or prefix with `void` and add an error handler.
+- **Never mutate function parameters** — objects and arrays are passed by reference; mutation silently corrupts the caller's data. Spread or `structuredClone()` before mutating. Mark parameters `readonly`.
+- **Never use `delete` on typed objects** — violates the type contract, creating objects that no longer match their type. Destructure to omit properties (`const { removed, ...rest } = obj`). For arrays, use `splice()` or `filter()`.
+- **Never use `export *` in barrel files** — defeats tree-shaking, creates namespace collisions, and breaks "go to definition". Use explicit named re-exports.
+- **Never omit `type` on type-only imports** — retains unnecessary import statements in compiled output, bloats bundles, and breaks isolated transpilers. Use `import type { }` or inline `type` qualifiers. Enable `verbatimModuleSyntax`.
+- **Never use `enum`** — emits runtime IIFE code, introduces nominal typing friction, and numeric enums silently accept any number. Use `as const` objects with derived union types.
+- **Never trust array index access without `noUncheckedIndexedAccess`** — TypeScript types `items[0]` as `T` even when the array could be empty. Enable `noUncheckedIndexedAccess: true` in tsconfig.
+- **Never skip exhaustiveness checks in switch/union handling** — adding a new union member silently falls through without a compile error. Add a `default` case that assigns to `never`: `const _exhaustive: never = value`.
+- **Never use `JSON.parse()` without runtime validation at system boundaries** — returns `any`, and assigning to a typed variable provides zero runtime guarantees. Validate with Zod `safeParse` or equivalent.
+
+## Error handling
+
+Use custom error classes with the prototype fix for correct `instanceof` checks:
+
+```typescript
+class AppError extends Error {
+  constructor(
+    message: string,
+    readonly code: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} ${id} not found`, 'NOT_FOUND');
+  }
+}
+```
+
+Catch blocks receive `unknown` — always narrow before accessing properties:
+
+```typescript
+try {
+  await fetchUser(id);
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    return null;
+  }
+  throw new AppError('Failed to fetch user', 'FETCH_ERROR', { cause: error });
+}
+```
+
+Result pattern using discriminated unions for expected domain failures:
+
+```typescript
+type Result<T, E = Error> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+function parseConfig(raw: string): Result<Config, ValidationError> {
+  const parsed = ConfigSchema.safeParse(JSON.parse(raw));
+  if (!parsed.success) {
+    return { ok: false, error: new ValidationError(parsed.error) };
+  }
+  return { ok: true, value: parsed.data };
+}
+```
+
+Chain error causes (ES2022) to preserve the original stack:
+
+```typescript
+throw new AppError('Order processing failed', 'ORDER_ERROR', { cause: error });
+```
+
+| Situation | Strategy | Reason |
+|-----------|----------|--------|
+| Programmer mistake (bad argument) | `throw` | Fail fast, fix the bug |
+| Expected domain failure (not found, validation) | `Result` | Caller must handle it |
+| Public API boundary | `Result` | Explicit contract, no surprise throws |
+| Internal implementation | `throw` | Simpler, caught at boundary |
+
+## Resource cleanup
+
+`using` / `await using` (TypeScript 5.2+) with `Symbol.dispose` / `Symbol.asyncDispose` is the preferred pattern — cleanup runs automatically when the scope exits:
+
+```typescript
+class TempFile implements Disposable {
+  readonly path: string;
+
+  constructor(prefix: string) {
+    this.path = `${tmpdir()}/${prefix}-${Date.now()}`;
+    writeFileSync(this.path, '');
+  }
+
+  [Symbol.dispose](): void {
+    rmSync(this.path, { force: true });
+  }
+}
+
+function processData(): void {
+  using tmp = new TempFile('data');
+  writeFileSync(tmp.path, serialize(data));
+  transform(tmp.path);
+  // tmp is disposed here, even on throw
+}
+```
+
+`AbortController` / `AbortSignal` as universal cancellation token:
+
+```typescript
+async function fetchWithTimeout(url: string, ms: number): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ms);
+
+  try {
+    return await fetch(url, { signal: controller.signal });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+```
+
+Event listener cleanup with `{ signal }`:
+
+```typescript
+const controller = new AbortController();
+element.addEventListener('click', handleClick, { signal: controller.signal });
+element.addEventListener('keydown', handleKey, { signal: controller.signal });
+// cleanup all at once:
+controller.abort();
+```
+
+Use `try/finally` as fallback when `using` is not available.
+
+## Async patterns
+
+Promise combinators — pick the right one:
+
+| Combinator | Settles when | Use case |
+|------------|-------------|----------|
+| `Promise.all` | All fulfill (or first reject) | Independent concurrent work, fail fast |
+| `Promise.allSettled` | All settle | Batch operations where partial success is OK |
+| `Promise.race` | First settles | Timeout racing, first-response-wins |
+| `Promise.any` | First fulfills (or all reject) | Fallback chains, redundant sources |
+
+Concurrent execution for independent work — avoid sequential `await` in loops:
+
+```typescript
+// Bad: sequential, N round trips
+for (const id of ids) {
+  const user = await fetchUser(id);
+  results.push(user);
+}
+
+// Good: concurrent
+const results = await Promise.all(ids.map((id) => fetchUser(id)));
+```
+
+Propagate `AbortSignal` through call chains:
+
+```typescript
+async function processOrder(
+  orderId: string,
+  signal?: AbortSignal,
+): Promise<Order> {
+  signal?.throwIfAborted();
+  const order = await fetchOrder(orderId, { signal });
+  const validated = await validateInventory(order, { signal });
+  return await chargePayment(validated, { signal });
+}
+```
+
+Async generators for paginated or streaming data:
+
+```typescript
+async function* fetchPages<T>(
+  url: string,
+  signal?: AbortSignal,
+): AsyncGenerator<T[]> {
+  let cursor: string | undefined;
+
+  do {
+    const params = cursor ? `?cursor=${cursor}` : '';
+    const res = await fetch(`${url}${params}`, { signal });
+    const data = PageSchema.parse(await res.json());
+    yield data.items;
+    cursor = data.nextCursor;
+  } while (cursor);
+}
+
+for await (const page of fetchPages<User>('/api/users', signal)) {
+  await processBatch(page);
+}
+```
+
+Concurrency limiting with a semaphore:
+
+```typescript
+async function mapConcurrent<T, R>(
+  items: T[],
+  limit: number,
+  fn: (item: T) => Promise<R>,
+): Promise<R[]> {
+  const results: R[] = [];
+  const executing = new Set<Promise<void>>();
+
+  for (const item of items) {
+    const p = fn(item).then((r) => { results.push(r); });
+    executing.add(p);
+    p.finally(() => executing.delete(p));
+    if (executing.size >= limit) await Promise.race(executing);
+  }
+
+  await Promise.all(executing);
+  return results;
+}
+```
+
+## Type system
+
+Generics with constraints and defaults:
+
+```typescript
+function merge<T extends Record<string, unknown>>(
+  target: T,
+  ...sources: Partial<T>[]
+): T {
+  return Object.assign({}, target, ...sources);
+}
+
+type ApiResponse<T, E = Error> = Result<T, E> & { statusCode: number };
+```
+
+Discriminated unions with exhaustive checking via `never`:
+
+```typescript
+type Event =
+  | { type: 'created'; payload: { id: string } }
+  | { type: 'updated'; payload: { id: string; changes: string[] } }
+  | { type: 'deleted'; payload: { id: string } };
+
+function handleEvent(event: Event): void {
+  switch (event.type) {
+    case 'created':
+      onCreate(event.payload.id);
+      break;
+    case 'updated':
+      onUpdate(event.payload.id, event.payload.changes);
+      break;
+    case 'deleted':
+      onDelete(event.payload.id);
+      break;
+    default: {
+      const _exhaustive: never = event;
+      throw new Error(`Unhandled event: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+Type narrowing — all forms:
+
+```typescript
+// typeof
+function format(value: string | number): string {
+  return typeof value === 'string' ? value : value.toFixed(2);
+}
+
+// instanceof
+if (error instanceof AppError) { /* error.code is available */ }
+
+// in
+if ('email' in user) { /* user has email property */ }
+
+// Custom type guard
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' && value !== null &&
+    'id' in value && 'name' in value
+  );
+}
+
+// Assertion function
+function assertDefined<T>(value: T | null | undefined, msg: string): asserts value is T {
+  if (value == null) throw new Error(msg);
+}
+```
+
+Branded types for domain IDs:
+
+```typescript
+type Brand<T, B extends string> = T & { readonly __brand: B };
+type UserId = Brand<string, 'UserId'>;
+type OrderId = Brand<string, 'OrderId'>;
+
+function createUserId(id: string): UserId { return id as UserId; }
+
+function getUser(id: UserId): Promise<User> { /* ... */ }
+// getUser(orderId) — compile error, prevents mixing IDs
+```
+
+`satisfies` operator (TS 4.9+) — validate without widening:
+
+```typescript
+const config = {
+  port: 3000,
+  host: 'localhost',
+  debug: true,
+} satisfies Record<string, string | number | boolean>;
+// config.port is number, not string | number | boolean
+```
+
+`as const` and const type parameters (TS 5.0+):
+
+```typescript
+function createRoute<const T extends readonly string[]>(methods: T) {
+  return { methods };
+}
+const route = createRoute(['GET', 'POST']);
+// route.methods is readonly ['GET', 'POST'], not string[]
+```
+
+## Data modeling
+
+| Use Case | Choice | Reason |
+|----------|--------|--------|
+| API response/request shape | `type` + Zod schema | Single source of truth with runtime validation |
+| Fixed string constants (type only) | String union | Zero runtime cost |
+| Fixed string constants (need runtime) | `as const` object + derived union | Tree-shakeable, iterable |
+| Object contract for public API | `interface` | Declaration merging, clearer errors |
+| Union of different shapes | Discriminated union with `kind` tag | Exhaustive checking, best narrowing |
+| Structurally identical but semantically different values | Branded types | Prevents mixing `UserId` with `OrderId` |
+| Immutable configuration | `as const` + `Readonly` | Compile-time literal types + immutability |
+| Entity with invariants and behavior | Class with private constructor | Constructor enforces rules |
+
+Zod schema as single source of truth:
+
+```typescript
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  name: z.string().min(1),
+  createdAt: z.coerce.date(),
+});
+
+type User = z.infer<typeof UserSchema>;
+```
+
+`as const` object with derived union:
+
+```typescript
+const Status = {
+  Active: 'active',
+  Inactive: 'inactive',
+  Suspended: 'suspended',
+} as const;
+
+type Status = (typeof Status)[keyof typeof Status];
+// 'active' | 'inactive' | 'suspended'
+```
+
+## Pattern matching
+
+Discriminated unions with `switch` and exhaustive checking:
+
+```typescript
+type Shape =
+  | { kind: 'circle'; radius: number }
+  | { kind: 'rectangle'; width: number; height: number };
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'rectangle':
+      return shape.width * shape.height;
+    default: {
+      const _exhaustive: never = shape;
+      throw new Error(`Unexpected shape: ${_exhaustive}`);
+    }
+  }
+}
+```
+
+Type guard functions for filtering and narrowing:
+
+```typescript
+function isNonNull<T>(value: T | null | undefined): value is T {
+  return value != null;
+}
+
+const items = [1, null, 2, undefined, 3].filter(isNonNull);
+// items: number[]
+```
+
+## Naming conventions
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Files | kebab-case | `user-service.ts` |
+| Types / interfaces / classes | PascalCase, no `I` prefix | `UserService`, `Config` |
+| Variables / functions | camelCase | `fetchUser`, `isValid` |
+| Constants (primitives) | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+| Constants (objects) | camelCase | `defaultConfig` |
+| Generics | `T` simple, `TDescriptive` complex | `T`, `TResponse` |
+| Booleans | `is`/`has`/`should`/`can` prefix | `isLoading`, `hasAccess` |
+| Private fields | `#` (runtime enforcement) | `#cache`, `#state` |
+
+## Module system
+
+ESM as the default — set `"type": "module"` in `package.json`. Use `import type` for type-only imports and enable `verbatimModuleSyntax: true` in tsconfig to enforce it.
+
+```typescript
+import type { User, Config } from './types.js';
+import { fetchUser } from './api.js';
+```
+
+Avoid deep barrel export chains — they defeat tree-shaking and slow IDE indexing. One level of barrel at package boundaries is acceptable:
+
+```typescript
+// packages/auth/index.ts — acceptable
+export { AuthService } from './auth-service.js';
+export type { AuthToken, AuthConfig } from './types.js';
+```
+
+## Testing
+
+Use Vitest as the default test runner. Use Jest for legacy projects already standardized on it.
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+describe('UserService', () => {
+  it('returns user when found', async () => {
+    const mockRepo = { findById: vi.fn<[string], Promise<User | null>>() };
+    mockRepo.findById.mockResolvedValue({ id: '1', name: 'Alice' });
+
+    const service = new UserService(mockRepo);
+    const user = await service.getUser('1');
+
+    expect(user).toEqual({ id: '1', name: 'Alice' });
+    expect(mockRepo.findById).toHaveBeenCalledWith('1');
+  });
+});
+```
+
+Mock at boundaries (HTTP, DB, clock), test logic directly. Use the AAA pattern: Arrange (set up data and mocks), Act (call the function), Assert (verify the outcome). Type-safe mocking with `vi.fn()` and `vi.mocked()` — avoid untyped mocks that drift from the real interface.
+
+When to mock: external APIs with rate limits or costs, network-dependent behavior, error paths, timers. When to use real instances: pure logic, value types, in-memory implementations. Test behavior, not implementation — test what a function returns or what state it changes, not how it works internally.

package/.claude/statusline-command.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+input=$(cat)
+MODEL=$(echo "$input" | jq -r '.model.display_name')
+DIR=$(echo "$input" | jq -r '.workspace.current_dir')
+COST=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
+PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)
+
+GREEN='\033[32m'; YELLOW='\033[33m'; RED='\033[31m'; ORANGE='\033[38;5;172m'; BLUE='\033[34m'; RESET='\033[0m'
+
+# Pick bar color based on context usage
+if [ "$PCT" -ge 70 ]; then BAR_COLOR="$RED"
+elif [ "$PCT" -ge 50 ]; then BAR_COLOR="$YELLOW"
+else BAR_COLOR="$GREEN"; fi
+
+FILLED=$((PCT / 8)); EMPTY=$((8 - FILLED))
+BAR=$(printf "%${FILLED}s" | tr ' ' '▮')$(printf "%${EMPTY}s" | tr ' ' '▯')
+
+BRANCH=""
+git rev-parse --git-dir > /dev/null 2>&1 && BRANCH="${BLUE}$(git branch --show-current 2>/dev/null)${RESET}"
+
+TIME=$(date +%H:%M)
+HOUR=$(date +%H | sed 's/^0//')
+# Time color: green 9-20, light blue 6-9, dark red 20-5
+if [ "$HOUR" -ge 9 ] && [ "$HOUR" -lt 20 ]; then TIME_COLOR='\033[38;5;71m'
+elif [ "$HOUR" -ge 6 ] && [ "$HOUR" -lt 9 ]; then TIME_COLOR='\033[38;5;117m'
+else TIME_COLOR='\033[38;5;124m'
+fi
+
+COST_FMT=$(printf '$%.2f' "$COST")
+
+echo -e "${ORANGE}${MODEL}${RESET}"
+echo -e "${DIR##*/}"
+[ -n "$BRANCH" ] && echo -e "${BRANCH}"
+echo -e "${TIME_COLOR}${TIME}${RESET} | ${COST_FMT} | ${BAR_COLOR}${BAR}${RESET} ${PCT}%"

package/.codex/prompts/plan-reviewer.md

@@ -0,0 +1,162 @@
+---
+description: Review implementation plans with evidence-based critique before coding begins
+argument-hint: [PLAN_FILE=<path>]
+---
+
+# Plan Reviewer
+
+Review an implementation plan and produce a review file at `.codex/plan-reviews/{plan-name}-reviewed.md`.
+
+## Plan Discovery
+
+1. If a `PLAN_FILE` argument is provided, use that path directly.
+2. Otherwise, find the most recently modified file in `.claude/plans/`.
+
+You are reviewing a plan BEFORE implementation. The proposed changes do not exist in the codebase yet. Read the current codebase to understand existing architecture, patterns, and dependencies -- then evaluate whether the proposal is sound given that current state.
+
+## Plan Author Context
+
+Plans are authored by Claude Opus 4.6. Watch for these common planning tendencies:
+
+- **Over-abstraction**: Protocol classes, factories, base classes, or strategy patterns for single implementations. If there's only one concrete type, an abstraction layer is overhead.
+- **Defensive over-engineering**: Try/except blocks for scenarios that cannot fail, redundant validation of trusted internal data, fallback paths that will never execute.
+- **Unnecessary dependencies**: Proposing new libraries when stdlib or existing project dependencies already cover the use case.
+- **Scope creep via "good practice"**: Adding logging, metrics, config flexibility, event systems, or analytics that weren't in the requirements -- justified as "good engineering" but expanding scope.
+
+Flag these as warnings when spotted. A minimal plan that solves the problem is a strength, not a gap.
+
+## Autonomy
+
+- Make reasonable assumptions when the plan is ambiguous. Note them in the review.
+- If you re-read the same files or retry the same approach more than twice without progress, stop, summarize what you tried, and try a different approach.
+
+## Review Scope
+
+**Review these areas:**
+
+- Architecture decisions and trade-offs
+- Dependency choices (necessity, security, maintenance)
+- Implementation complexity vs. requirements
+- Missing considerations (error handling, edge cases)
+- Alternative approaches
+- Risk assessment
+- Whether the proposal aligns with existing codebase patterns and conventions
+
+**Skip these areas:**
+
+- Code style/formatting
+- Naming conventions (unless confusing)
+- Minor optimizations
+- Hypothetical future requirements
+
+## Severity Definitions
+
+Two levels only:
+
+- **Critical**: Would cause runtime failures, security vulnerabilities, data loss, or fundamental conflicts with existing architecture. Must be resolved before implementation.
+- **Warning**: Unnecessary complexity, suboptimal approach, or missing considerations that don't block correctness. Should be considered but not blocking.
+
+## Review Constraints
+
+1. **Every criticism requires a concrete solution.** Never raise an issue without proposing a fix.
+2. **Evidence-based only.** Reference specific plan sections or codebase files using `path/to/file.py:line` notation.
+3. **Report all critical issues (no cap).** Never suppress blockers.
+4. **Prioritize warnings by impact.** If more than ~7 warnings exist, consolidate related ones under a single topic.
+5. **No nitpicking.** Skip style preferences and minor concerns.
+6. **Strengths: only mention non-obvious or deliberately good decisions.** Skip generic praise. For clean plans, confirm that key architectural decisions align with the codebase and list 1-2 non-obvious strengths.
+
+## Review Output Limits
+
+- **Summary**: 2-3 sentences max.
+- **Each review item**: 3-5 sentences for explanation, 2-4 sentences or a short code snippet for solution.
+- **Strengths**: 1-3 bullets, or omit the section entirely.
+- **Total review**: Aim for 300-600 words excluding code snippets. Longer only if critical count justifies it.
+
+## Exploration Priorities
+
+Before writing the review, gather context. Parallelize independent reads.
+
+1. **Plan file** -- the thing being reviewed (via discovery logic above).
+2. **Files the plan will modify** -- understand current patterns the plan should follow.
+3. **Project dependencies** (`pyproject.toml`) -- check if proposed dependencies already exist or are redundant.
+4. **Applicable skill standards** -- scan available skills directories and evaluate compliance against every skill whose description matches the plan's file types and tasks.
+5. **New dependency docs** -- verify APIs, maintenance status, and alternatives using available documentation tools and web search.
+
+### Skill Reference
+
+Check all available skills before writing the review. For each skill:
+1. Read the skill's description to determine what file types and tasks it covers
+2. If the plan touches files or tasks matching that description, evaluate the proposal against the skill's standards
+3. Multiple skills may apply — check all that match
+
+### Dependency Verification
+
+For each new dependency proposed in the plan, verify using available documentation tools and web search:
+- Actively maintained?
+- Current API patterns (not deprecated)?
+- Built-in alternatives in existing project dependencies?
+- Known security issues?
+
+## Output Format
+
+Write the review to `.codex/plan-reviews/{plan-name}-reviewed.md` using exactly this structure:
+
+```markdown
+# Plan Review: {plan-name}
+
+## Summary
+[2-3 sentences: overall assessment, blockers if any]
+
+## Strengths
+- [Non-obvious or deliberate good decisions only. Omit section if nothing noteworthy.]
+
+## Review Items
+
+### {Topic}
+**Level**: critical | warning
+**Explanation**: [reference specific plan sections or current codebase files]
+**Solution**: [concrete fix, code snippet if helpful]
+
+## Verdict
+[See verdict criteria below]
+
+[1 sentence: next steps]
+```
+
+### Verdict Criteria
+
+- **Approved**: Zero criticals. Warnings are minor or cosmetic.
+- **Approved with Changes**: Zero criticals. Warnings identify real risks worth addressing before implementation.
+- **Needs Revision**: One or more critical issues exist. Plan should not proceed to implementation.
+
+If no issues are found, state "No significant issues identified" and verdict "Approved".
+
+## Example Review Item
+
+### Dependency: Tenacity
+
+**Level**: warning
+
+**Explanation**: Plan proposes adding `tenacity` for retries (Section 3.2). The current codebase uses `httpx` which provides native retry support via `AsyncHTTPTransport(retries=N)` -- see `src/clients/base.py:18`. Adding `tenacity` introduces an unnecessary dependency.
+
+**Solution**: Use httpx's built-in retry:
+```python
+transport = httpx.AsyncHTTPTransport(retries=3)
+client = httpx.AsyncClient(transport=transport)
+```
+
+## Incremental Reviews
+
+When a prior review already exists in `.codex/plan-reviews/` for the same plan:
+
+1. Read the prior review file alongside the updated plan.
+2. Focus on whether previous `critical` items were addressed. Mark each as resolved or still open.
+3. Flag new issues introduced by plan revisions only -- do not re-report items already covered.
+4. Reference the prior review in the output header:
+
+```markdown
+# Plan Review: {plan-name} (revision)
+**Prior review**: `.codex/plan-reviews/{plan-name}-reviewed.md`
+```
+
+5. If all prior criticals are resolved and no new criticals exist, the verdict can be upgraded.