@danieljvdm/dev-kit 0.5.0 → 0.7.0

package/skills/dev-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dev-kit
-description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or locked postinstalls, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, or enable Effect TypeScript-Go.
+description: Dev-kit operations for projects that configure dev-kit.jsonc, sync portable skills, run plan/apply or automatic postinstalls, perform locked CI checks, maintain dev-kit.lock.json, resolve ownership conflicts, patch managed ignores, or enable Effect TypeScript-Go.
 ---
 
 # Dev Kit
@@ -28,7 +28,7 @@ stores explicit skill names and exact commit/content digests.
    repository actually uses; do not infer capabilities from a product or
    company name alone.
 2. Run `dev-kit list --all`, then use `dev-kit search <terms>` and `dev-kit info
-   <skill>` for each capability in the inventory. Compare every candidate's
+<skill>` for each capability in the inventory. Compare every candidate's
    trigger description with concrete repository evidence. Keep explicitly
    requested creative or advisory skills even when they have no mechanical
    dependency signal.
@@ -51,8 +51,12 @@ stores explicit skill names and exact commit/content digests.
 6. Resolve conflicts, then run `dev-kit apply`. Commit the manifest and
    regenerated `dev-kit.lock.json`; keep `.dev-kit/` local. Finish when a second
    plan reports only unchanged resources and setup tasks.
-7. Use `dev-kit apply --locked` in CI and the package lifecycle. Finish when a
-   clean install converges from the committed manifest and lock.
+7. Use `dev-kit apply` in the package lifecycle so intentional dependency
+   upgrades regenerate owned outputs and `dev-kit.lock.json`. For strict CI,
+   either disable lifecycle scripts before `dev-kit apply --locked`, or run the
+   normal lifecycle and require the tracked working tree to remain clean. Never
+   run an unlocked apply before locked verification. Finish when a clean install
+   converges from the committed manifest and lock.
 
 ## Manifest
 
@@ -68,13 +72,18 @@ skill as `dev-kit` when project agents should carry the toolkit procedure.
   "include": ["dev-kit", "effect"],
   "exclude": [],
   "setup": {
-    "claudeInstructions": { "enabled": true }
+    "agentInstructions": { "enabled": true },
+    "claudeInstructions": { "enabled": true },
+    "vitePlus": {
+      "hooks": { "enabled": true },
+      "quality": { "enabled": true },
+    },
   },
   "targets": {
     "agents": { "enabled": true, "mode": "copy" },
     "claude": { "enabled": true, "mode": "symlink" },
-    "opencode": { "enabled": false, "mode": "symlink" }
-  }
+    "opencode": { "enabled": false, "mode": "symlink" },
+  },
 }
 ```
 
@@ -83,11 +92,36 @@ use symlinks for additional harness discovery paths. Keep every target path
 project-relative and separate from the manifest, lock, state, and process-lock
 paths.
 
+Enable `setup.agentInstructions` to manage a project-root `AGENTS.md` wrapper
+that points agents back to this skill. When `vite-plus` is a declared direct
+dependency, dev-kit includes its installed agent instructions in the wrapper.
 Enable `setup.claudeInstructions` when Claude Code should consume the same
-project-root instructions as Codex. It manages `CLAUDE.md` as a relative
-symlink to an existing `AGENTS.md`. Preserve any conflicting `CLAUDE.md`; when
-disabled, dev-kit removes only an unchanged link recorded in local ownership
-state.
+project-root instructions; it manages `CLAUDE.md` as a relative symlink to the
+wrapper or to an existing regular `AGENTS.md`. Preserve conflicting paths;
+when disabled, dev-kit removes only unchanged outputs recorded in local
+ownership state.
+
+Enable `setup.vitePlus.hooks` when an installed direct `vite-plus` dependency
+should manage Git hooks. Each apply checks the local `.vite-hooks/_` dispatcher,
+the portable `.vite-hooks/pre-commit` hook, and `core.hooksPath`, then runs the
+project-local `vp config --no-agent` when they need convergence. This recreates
+ignored dispatchers in linked worktrees. Preserve other hook managers; Dev Kit
+refuses to replace an unrelated `core.hooksPath`. Use `VITE_GIT_HOOKS=0` or
+`HUSKY=0` to skip hook setup for an invocation.
+
+Enable `setup.vitePlus.quality` only in supported Vite+/Effect repositories
+that explicitly want Dev Kit to own the canonical root `vite.config.ts` and
+`.github/workflows/check.yml`. It requires direct Dev Kit, Vite+, Effect,
+Effect TypeScript-Go, and native TypeScript dependencies, as well as
+`setup.effectTsgo.enabled`. It refuses custom destination files and conflicting
+`check` or `typecheck` package scripts. Exact canonical files can be adopted;
+later updates and cleanup occur only while the owned files remain unchanged.
+
+The managed Vite config composes the shared formatter and linter presets,
+configures `vp staged`, and defines cached `check` and `typecheck` Vite tasks.
+The check task and GitHub Actions workflow run `vp fmt --check`, `vp lint`,
+`vp test`, and finally `vp run typecheck` so Effect diagnostics come from the
+patched native compiler.
 
 ## Ownership and conflicts
 
@@ -118,11 +152,17 @@ For one lifecycle entry point, configure:
 ```jsonc
 {
   "scripts": {
-    "postinstall": "dev-kit apply --locked"
-  }
+    "postinstall": "dev-kit apply",
+  },
 }
 ```
 
+This intentionally refreshes the committed lock and owned outputs when the
+package manager installs a new Dev Kit or selected package-skill version.
+Review and commit those changes with the dependency update. Keep
+`dev-kit apply --locked` as a verification command, not the normal local
+lifecycle; in CI, run it only before any unlocked apply.
+
 ## Effect source checkout
 
 Enable the source task when agents should have canonical source matching the
@@ -131,8 +171,8 @@ installed Effect package:
 ```jsonc
 {
   "setup": {
-    "effectSource": { "enabled": true }
-  }
+    "effectSource": { "enabled": true },
+  },
 }
 ```
 
@@ -151,8 +191,8 @@ Enable the setup task in the same manifest:
 ```jsonc
 {
   "setup": {
-    "effectTsgo": { "enabled": true }
-  }
+    "effectTsgo": { "enabled": true },
+  },
 }
 ```
 
@@ -191,7 +231,16 @@ Use `lint.extends` instead of spreading the object so Vite+ composes nested
 rule maps correctly. Oxfmt has no inheritance mechanism, so spread its object
 before project-local options. Standalone `oxlint.config.ts` uses the same
 `extends: [recommendedOxlintConfig]`; standalone `oxfmt.config.ts` spreads the
-same `recommendedOxfmtConfig`.
+same `recommendedOxfmtConfig`. The shared lint preset enables `typeAware` for
+semantic lint rules but leaves `typeCheck` disabled. Effect TypeScript-Go
+projects must run the patched native compiler separately with
+`vp run typecheck` after `vp fmt --check`, `vp lint`, and `vp test`; Oxlint's
+bundled `tsgolint` does not use the Effect patch.
+
+The Oxlint preset enables the fixable
+`stylistic/padding-line-between-statements` rule. It keeps adjacent variable
+declarations grouped, requires a blank line before the next logical statement,
+and separates every `return` statement from the preceding statement.
 
 The Oxlint preset registers Dev Kit's shared Effect plugin as `effect`, but
 does not enable its scope-sensitive rules globally. Effect projects should
@@ -204,9 +253,10 @@ in the consuming project.
 
 ## Current boundary
 
-Manage skill outputs, the `setup.claudeInstructions` link, the
-`setup.effectSource` checkout, and the explicit `setup.effectTsgo` task. Edit
-shared `package.json` and `tsconfig.json`
-contributions deliberately. The Oxlint and Oxfmt configurations are composable
-package exports, not manifest-managed outputs. Treat broader setup tasks as
-future manifest capabilities until the installed CLI exposes them.
+Manage skill outputs, the `setup.agentInstructions` wrapper, the
+`setup.claudeInstructions` link, the `setup.vitePlus.hooks` dispatcher, the
+opt-in `setup.vitePlus.quality` config and GitHub workflow, the
+`setup.effectSource` checkout, and the explicit `setup.effectTsgo` task.
+Dependency and `tsconfig.json` contributions remain deliberate user-owned
+edits. Custom Vite configs compose the Oxlint and Oxfmt package exports manually
+and leave the canonical quality task disabled.

package/skills/effect-atom-data-fetching/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: effect-atom-data-fetching
+description: Design, implement, debug, or review HTTP data fetching with Effect Atom in React applications. Use for AtomHttpApi.Service queries and mutations, parameterized Atom.family caches, RegistryProvider and runtime placement, TTL/SWR/polling behavior, reactivity-key invalidation, framework-appropriate SSR and focus handling, AsyncResult aggregation resets, and deterministic cache lifecycle tests.
+---
+
+# Effect Atom Data Fetching
+
+Model server data as stable atoms owned outside React renders. Give the application one intentional registry boundary and one compatible runtime factory; then choose cache retention, freshness, polling, and invalidation independently.
+
+## Workflow
+
+1. Inspect the installed `effect` and `@effect/atom-react` versions and their source before copying signatures. These APIs live under `effect/unstable/reactivity` and may move.
+2. Locate every `RegistryProvider`, runtime factory, query atom, mutation atom, and route-level `AsyncResult.all`. Draw the ownership boundary before changing behavior.
+3. Keep one `RegistryProvider` for the intended client application lifetime. Define the shared runtime factory, API service, query families, and mutation atoms at module scope rather than in components.
+4. Choose each lifecycle control for its actual job:
+   - idle `timeToLive`: retain an unused registry value before disposal;
+   - `Atom.swr({ staleTime })`: decide when mount/focus revalidation is needed;
+   - `Atom.withRefresh`: force periodic refresh while mounted.
+5. Give queries stable identities and matching reactivity keys. Let successful mutations invalidate those keys rather than manually coordinating every consumer.
+6. Keep browser-only signals behind an SSR-safe boundary. Decide explicitly whether initial data is client-only or hydrated from a request-scoped server registry.
+7. Verify lifecycle behavior with fake time and request counters, not sleeps.
+
+## Ownership rules
+
+- Treat a query as shared read state: export one atom or `Atom.family` and let components subscribe.
+- Treat an action as an event owned by the initiating UI or workflow: export the mutation atom, invoke it with `useAtomSet`, and observe its result only where useful.
+- Never allocate a query atom in render. For parameterized queries, use a stable scalar or Effect `Hash`/`Equal` value as the family argument.
+- Ensure every input to a route-level `AsyncResult.all` has stable atom identity and compatible retention. One newly allocated or immediately evicted input returns to `Initial` and makes the whole aggregate appear reset even when the other inputs remain cached.
+- Do not describe manual refresh or polling as freshness caching. Refresh is forceful; `staleTime` only gates SWR's automatic mount/focus decisions.
+
+## References
+
+- Read `./references/cache-lifecycle.md` for registry scope, runtime memoization, families, TTL, SWR, polling, and the aggregation trap.
+- Read `./references/http-and-invalidation.md` for `AtomHttpApi.Service`, query/mutation ownership, reactivity-key vocabulary, and invalidation.
+- Read `./references/tanstack-start.md` only for its framework-specific provider placement, SSR isolation, hydration, and focus guidance.
+- Read `./references/testing.md` when adding or diagnosing lifecycle tests.
+
+## Completion check
+
+Confirm one registry boundary, stable atom identity, deliberate TTL/staleness/polling values, matching query and mutation keys, SSR-safe browser access, and tests for every lifecycle behavior changed.

package/skills/effect-atom-data-fetching/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Effect Atom Data Fetching"
+  short_description: "Cache HTTP data safely with Effect Atom"
+  default_prompt: "Use $effect-atom-data-fetching to design or debug Effect Atom HTTP queries, caching, polling, invalidation, and SSR integration in a React app."

package/skills/effect-atom-data-fetching/references/cache-lifecycle.md

@@ -0,0 +1,72 @@
+# Cache lifecycle
+
+## Registry and runtime scope
+
+`RegistryProvider` creates one `AtomRegistry` on its first render. Its options do not rebuild that registry later. Provider unmount schedules disposal after a short grace period, so a quick React remount can reuse the same registry; moving or keying the provider still changes the cache boundary.
+
+Place one provider around the client application subtree that should share data. Nested or route-local providers create separate caches.
+
+An atom runtime and a registry solve different problems:
+
+- the registry stores atom nodes, values, subscriptions, idle timers, and finalizers;
+- `Atom.context({ memoMap })` creates runtimes that share `Layer` construction through one `Layer.MemoMap`;
+- the module-level `Atom.runtime` uses Effect's module-level default memo map.
+
+Create one client runtime factory when several API/services must share layers:
+
+```ts
+import { Layer } from "effect";
+import { Atom } from "effect/unstable/reactivity";
+
+export const appAtomRuntime = Atom.context({
+  memoMap: Layer.makeMemoMapUnsafe(),
+});
+```
+
+Pass `appAtomRuntime` to each `AtomHttpApi.Service`. Do not create a memo map per query or component. On an SSR server, do not put request-specific authentication or services into a process-global memo map; use a request-scoped atom environment or keep the atom data path client-only.
+
+## Stable identity and families
+
+Export fixed queries directly. Use `Atom.family` when a parameter selects the resource:
+
+```ts
+export const projectAtom = Atom.family((projectId: string) =>
+  ApiClient.query("projects", "get", {
+    params: { projectId },
+    timeToLive: "5 minutes",
+    reactivityKeys: { projects: [projectId] },
+  }).pipe(Atom.swr({ staleTime: "30 seconds", revalidateOnMount: true })),
+);
+```
+
+The family must receive a stable key. Prefer a primitive ID. If the key is an object, give it deliberate Effect `Equal`/`Hash` semantics or reuse the same object; repeated object literals can produce distinct family entries.
+
+## Three independent clocks
+
+| Control                                         | Clock starts                      | What happens                                                                                         | What it does not mean                                 |
+| ----------------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Registry/default idle TTL or query `timeToLive` | When an atom becomes unused       | The registry keeps the cached node until idle eviction                                               | The value is fresh during that period                 |
+| `Atom.swr({ staleTime })`                       | From the latest success timestamp | A stale value can revalidate automatically on mount or focus while the prior success remains visible | The node survives an unmount long enough to be reused |
+| `Atom.withRefresh(interval)`                    | While the wrapper is mounted      | A timer force-refreshes the source and is canceled on disposal                                       | Fresh requests are skipped                            |
+
+Set retention long enough for the navigation/remount reuse window. `staleTime` cannot rescue a source that idle eviction already removed. A common policy is a longer `timeToLive`, a shorter `staleTime`, and polling only on screens that truly need it.
+
+Manual `registry.refresh`, `useAtomRefresh`, invalidation, and `Atom.withRefresh` are forceful. They do not consult SWR freshness. Polling stops when the polling wrapper's lifetime is disposed because its finalizer clears the timer; applying `keepAlive` to that wrapper intentionally keeps polling alive.
+
+## The `AsyncResult.all` route reset
+
+`AsyncResult.all` returns the first non-success input. Therefore a route aggregate is only as reusable as its least-stable input:
+
+```ts
+const routeDataAtom = Atom.make((get) =>
+  AsyncResult.all({
+    project: get(projectAtom("p-1")),
+    // Bad if created during render or rebuilt for every route visit:
+    preferences: get(makePreferencesAtom()),
+  }),
+);
+```
+
+If `preferences` is a fresh or evicted atom, it starts at `Initial`; the aggregate also looks initial even though `project` is cached. Fix the input's ownership and retention. Define a singleton/family atom outside render and give it a deliberate idle TTL. Memoizing only the `AsyncResult.all` call does not repair an unstable input atom.
+
+`AsyncResult.all` also constructs a new success container. Keep aggregation inside a derived atom so the registry controls recomputation instead of rebuilding the container ad hoc in render.

package/skills/effect-atom-data-fetching/references/http-and-invalidation.md

@@ -0,0 +1,93 @@
+# HTTP queries and invalidation
+
+## Build one API service
+
+`AtomHttpApi.Service` generates a typed client, a runtime, query atoms, and mutation functions. Pass the shared runtime factory so API services share the intended `Layer.MemoMap`:
+
+```ts
+import { FetchHttpClient } from "effect/unstable/http";
+import { AtomHttpApi } from "effect/unstable/reactivity";
+import { appAtomRuntime } from "./atom-runtime";
+import { Api } from "./api";
+
+export const ApiClient = AtomHttpApi.Service()("ApiClient", {
+  api: Api,
+  httpClient: FetchHttpClient.layer,
+  baseUrl: "/api",
+  runtime: appAtomRuntime,
+});
+```
+
+Compile examples against the installed Effect version; the reactivity and HTTP APIs are unstable.
+
+## Queries
+
+`query(group, endpoint, request)` returns an `Atom<AsyncResult<...>>`. The service internally memoizes request keys with a family. A public `Atom.family` remains useful for expressing domain ownership with a simple, stable parameter and applying one cache policy.
+
+Query options have separate roles:
+
+- `timeToLive`: finite values apply idle TTL; infinity keeps the query alive;
+- `reactivityKeys`: register the query for refresh after matching invalidation;
+- `serializationKey`: make decoded-only results serializable for hydration; it is not the runtime cache key;
+- `responseMode`: changes the response and error shape.
+
+Never place secrets in `serializationKey`, URL state, hydration payloads, or client-visible layers.
+
+## Mutations and action ownership
+
+Create mutation atoms once, then invoke them from the component or workflow that owns the action:
+
+```ts
+export const updateProject = ApiClient.mutation("projects", "update");
+
+// In the initiating component:
+const mutate = useAtomSet(updateProject, { mode: "promise" });
+await mutate({
+  params: { projectId },
+  payload: patch,
+  reactivityKeys: { projects: [projectId] },
+});
+```
+
+The mutation's `reactivityKeys` are invalidated only after the request succeeds. Failed mutations do not invalidate. Keep navigation, toasts, dialog closure, and optimistic UI at the action owner; keep shared server-state refresh in reactivity keys.
+
+## Use one key vocabulary
+
+Array keys represent independent keys. Record keys support hierarchical broad-plus-entity invalidation:
+
+```ts
+const listKeys = { projects: [] };
+const detailKeys = { projects: [projectId] };
+
+ApiClient.query("projects", "list", { reactivityKeys: listKeys });
+ApiClient.query("projects", "get", { params: { projectId }, reactivityKeys: detailKeys });
+
+// This mutation invalidates the broad namespace and this entity key.
+await mutate({ params: { projectId }, payload: patch, reactivityKeys: detailKeys });
+```
+
+Record semantics register the property name and each `property:id` combination. Consequently, `{ projects: [projectId] }` is hierarchical: it invalidates both the broad `projects` namespace and the specific `projects:projectId` key. Every record-form project query also subscribed to that broad namespace can refresh. Use this when an entity write may affect lists or aggregates.
+
+For exact entity-only invalidation, use namespaced primitive array keys consistently instead:
+
+```ts
+const projectKey = (id: string) => `project:${id}`;
+
+const detailKeys = [projectKey(projectId)];
+const collectionKeys = ["projects"];
+
+ApiClient.query("projects", "get", { params: { projectId }, reactivityKeys: detailKeys });
+await mutate({ params: { projectId }, payload: patch, reactivityKeys: detailKeys });
+```
+
+Use `collectionKeys` for the collection query and for mutations that can change membership or ordering.
+
+Standardize key constructors in one module when several endpoints share them; mismatched strings fail silently.
+
+Choose invalidation breadth from the server write:
+
+- invalidate an exact array-form entity key when only one detail changed;
+- invalidate the collection key, or use hierarchical record keys, when list membership, ordering, totals, or filters can change;
+- invalidate multiple record properties when a write affects related aggregates.
+
+Do not both invalidate and manually refresh the same query unless two requests are intentional.

package/skills/effect-atom-data-fetching/references/tanstack-start.md

@@ -0,0 +1,69 @@
+# TanStack Start integration
+
+TanStack Start code is isomorphic by default, including route loaders. Treat every module used by a route as server-capable unless an explicit boundary says otherwise.
+
+## Choose an SSR strategy
+
+Use one of these models deliberately:
+
+### Client-only atom data
+
+- Put one `RegistryProvider` in the app/root component so client navigations share a registry.
+- Render atom consumers that touch browser-only APIs inside `ClientOnly` from `@tanstack/react-router`.
+- Accept that the fallback is the server-rendered state and fetching begins on the client.
+- Keep the client runtime and API service as module singletons.
+
+```tsx
+import { RegistryProvider } from "@effect/atom-react";
+import { ClientOnly } from "@tanstack/react-router";
+
+export function AppShell() {
+  return (
+    <RegistryProvider defaultIdleTTL={30_000}>
+      <ClientOnly fallback={<DashboardSkeleton />}>
+        <Dashboard />
+      </ClientOnly>
+    </RegistryProvider>
+  );
+}
+```
+
+### SSR plus hydration
+
+- Create the registry and any request-specific runtime/layers per request; never share user/auth state through a process-global registry or memo map.
+- Give decoded query atoms deterministic `serializationKey` values.
+- Mount/run the required serializable atoms on the server, dehydrate only the intended values, and pass them through the document safely.
+- Create the client registry once, then hydrate matching atom identities before descendants consume them. Use `HydrationBoundary` where the installed React adapter supports it.
+- Verify that server and client construct the same API service, family arguments, and serialization keys.
+
+Prefer framework loaders/server functions when they already own SSR data. Do not build a second atom SSR cache merely to mirror loader data; seed atoms from the loader or keep atom fetching client-only.
+
+## Focus is browser-only
+
+`Atom.windowFocusSignal` reads `window` and `document.visibilityState` when mounted. Do not mount it during SSR. Put focus-enabled consumers behind `ClientOnly`, or inject a no-op server signal and the browser signal on the client.
+
+```ts
+const project = projectAtom(projectId).pipe(
+  Atom.swr({
+    staleTime: "30 seconds",
+    revalidateOnFocus: true,
+    focusSignal: Atom.windowFocusSignal,
+  }),
+);
+```
+
+`revalidateOnFocus: true` respects `staleTime`; `"always"` forces a request on every focus signal.
+
+## In-memory limits
+
+Effect Atom's registry cache is in memory and scoped to that registry:
+
+- a new tab, hard reload, server process, or newly created provider starts another cache;
+- idle TTL evicts only unused atoms and is not a maximum-entry or byte-size bound;
+- `keepAlive` and infinite TTL can grow memory with unbounded family keys;
+- browser memory is not durable or shared across users/devices;
+- hydration transfers a snapshot, not a persistent distributed cache.
+
+For large or unbounded parameter spaces, use finite TTLs and avoid `keepAlive`. Put durable/shared caching at the HTTP, server, CDN, or database layer.
+
+Primary TanStack references: [execution model](https://tanstack.com/start/latest/docs/framework/react/guide/execution-model) and [`ClientOnly`](https://tanstack.com/router/latest/docs/api/router/clientOnlyComponent).

package/skills/effect-atom-data-fetching/references/testing.md

@@ -0,0 +1,63 @@
+# Deterministic lifecycle testing
+
+Test cache policy below React first with `AtomRegistry.make()`. Add a React integration test only for provider placement, hook behavior, a browser-only SSR boundary, or hydration.
+
+Use fake timers, a request counter, controllable Effects, and explicit mounts:
+
+```ts
+const registry = AtomRegistry.make({ defaultIdleTTL: 1_000 });
+const unmount = registry.mount(queryAtom);
+const first = registry.get(queryAtom);
+
+// Advance the Effect scheduler/microtasks as required by the installed version.
+// Assert with AsyncResult predicates and request counts.
+
+unmount();
+```
+
+Avoid wall-clock sleeps. Flush Effect work with the repository's established `Effect.yieldNow`/test-clock pattern and advance the test runner's fake timers.
+
+Prefer the installed test APIs over invented helpers or matchers. The upstream Effect tests use `assert(AsyncResult.isSuccess(result))`, `Effect.runPromise(Effect.yieldNow)`, `vitest.advanceTimersByTimeAsync(...)`, and the cleanup returned by `registry.mount(atom)`.
+
+## Required scenarios
+
+### Remount reuse
+
+1. Mount and resolve the query; assert request count `1`.
+2. Unmount, advance less than idle TTL, remount the same atom identity.
+3. Assert the cached success is immediately available and no request occurs while still fresh.
+
+### Stale refresh
+
+1. Resolve once through an SWR wrapper.
+2. Advance past `staleTime` but not idle TTL.
+3. Remount or emit the injected focus signal.
+4. Assert the previous success stays available with `waiting: true`, then a second success arrives and request count becomes `2`.
+5. Also prove a fresh mount/focus does not request.
+
+### TTL eviction
+
+1. Resolve and unmount.
+2. Advance to just before TTL; assert reuse.
+3. Advance to/after TTL and flush disposal; remount.
+4. Assert `Initial`/waiting behavior and a new request.
+
+### Polling cleanup
+
+1. Mount the `Atom.withRefresh` wrapper and resolve once.
+2. Advance one interval; assert one forced refresh.
+3. Unmount and advance several intervals.
+4. Assert the counter does not change. This catches leaked timers or accidental `keepAlive`.
+
+### Mutation invalidation
+
+1. Mount list and detail queries with explicit keys.
+2. Run a successful mutation with matching keys; assert only the intended queries refresh.
+3. Run a failed mutation; assert no invalidation.
+4. Assert cleanup removes invalidation handlers after query disposal.
+
+### Aggregate stability
+
+Mount a route atom that uses `AsyncResult.all`, resolve every input, unmount, and remount inside the retention window. Assert the aggregate never returns to `Initial`. Then let one input expire and prove the aggregate reset is caused by that input, not the retained queries.
+
+For runtime/layer tests, seed `runtime.layer` through `RegistryProvider initialValues` with a deterministic test layer. This replaces network services without changing the production atom graph.

package/skills/effect-ts/agents/openai.yaml

@@ -2,4 +2,3 @@ interface:
   display_name: "Effect Expert"
   short_description: "Apply current Effect v4 patterns and tooling"
   default_prompt: "Use $effect-ts to apply the relevant Effect architecture, schema, service, error, testing, HTTP, SQL, observability, or CLI guidance."
-

package/skills/effect-ts/references/audit-services.md

@@ -44,17 +44,17 @@ Enumerate source and test files, then find:
 
 Record one row per discovered service or candidate:
 
-| Field | Question |
-| --- | --- |
-| Owner | Which module owns the capability's meaning? |
-| Contract | Where are its interface and tag? |
-| Construction | Does construction yield every runtime dependency? |
-| Production | Who owns the concrete implementation and Layer choice? |
-| Tests | Does it have an intentional and honest substitute strategy? |
-| Consumers | Are capabilities yielded or drilled as values? |
-| Requirements | Do requirements remain visible to the composition root? |
-| Type boundary | Who owns decoding, narrowing, and error translation? |
-| Verdict | Keep, deepen, relocate, merge, remove, or create? |
+| Field         | Question                                                    |
+| ------------- | ----------------------------------------------------------- |
+| Owner         | Which module owns the capability's meaning?                 |
+| Contract      | Where are its interface and tag?                            |
+| Construction  | Does construction yield every runtime dependency?           |
+| Production    | Who owns the concrete implementation and Layer choice?      |
+| Tests         | Does it have an intentional and honest substitute strategy? |
+| Consumers     | Are capabilities yielded or drilled as values?              |
+| Requirements  | Do requirements remain visible to the composition root?     |
+| Type boundary | Who owns decoding, narrowing, and error translation?        |
+| Verdict       | Keep, deepen, relocate, merge, remove, or create?           |
 
 Build a companion type-safety inventory using
 [`guide-type-safety-and-boundaries.md`](guide-type-safety-and-boundaries.md).