@mrciphersmith/keryx 0.3.0 → 0.3.2

package/src/gdskills/bundled/stacks/mobx/governance/scout.json

@@ -0,0 +1,18 @@
+[
+  {
+    "query": "Use when writing or extending a MobX store: adding observable state, actions, computed getters, or reactions (autorun/reaction/when), wiring a store into React via observer and a context hook, or fixing a component that stops re-rendering after a store change. Also covers plain-language asks for the same work: keeping a piece of MobX store state automatically in sync wherever it's read, or making a store run something automatically when a value changes and stop when the store is no longer needed. Applies the makeObservable/action/runInAction/observer shape and the store's dispose lifecycle. Not for reviewing an already-written store's structure (use code-mobx-store-review) and not for plain React state/props work with no MobX involved (use react-implementation).",
+    "decision": "fork",
+    "topMatch": "mobx/mobx-observable-testing",
+    "recordedAt": "2026-09-25T06:28:15.470Z",
+    "skillName": "mobx-store-implementation",
+    "justification": "Top match remains this pack's own sibling mobx-observable-testing -- same domain vocabulary (store/action/computed/observable), different category (implement vs test), not a substitute: that skill only covers writing/fixing tests, never authoring store code. Description was widened (flow 318 follow-up) to also cover plain-language symptom/goal phrasings of the same implement work, not to broaden scope -- no new candidate skill/pack became a closer match after the update; review-frontend, nestjs-implementation, code-mobx-store-review, and angular-implementation remain the next nearest and are all a different stack/activity or review-only."
+  },
+  {
+    "query": "Use when writing or fixing a test for a MobX store: asserting on an async action's post-await state, waiting for a reaction/autorun to fire, testing that dispose() actually stops a store's reactions, or deciding how enforceActions should behave in the test setup. Distinct from rendering-focused React component testing and generic Node/TypeScript test-runner setup. Not for writing the store or action code itself (use mobx-store-implementation) and not for React Testing Library render/interaction patterns with no MobX involved (use react-testing).",
+    "decision": "fork",
+    "topMatch": "mobx/mobx-store-implementation",
+    "recordedAt": "2026-09-25T06:24:35.475Z",
+    "skillName": "mobx-observable-testing",
+    "justification": "Top match (0.38) is this pack's own sibling mobx-store-implementation -- same domain vocabulary (store/action/reaction/dispose), different category (test vs implement), not a substitute: that skill authors store/action code, this one asserts on the resulting async/reaction behavior in tests. Next matches (vue-testing 0.25, nodejs-implementation 0.22, angular-code-review 0.21, review-frontend 0.21) are all a different stack or activity entirely -- generic test-runner/component-render skills with no MobX-specific reactivity (runInAction seeding, when()-based waits, dispose/reaction cleanup assertions) this skill covers."
+  }
+]

package/src/gdskills/bundled/stacks/mobx/pack.json

@@ -0,0 +1,28 @@
+{
+  "id": "mobx",
+  "family": "framework",
+  "extends": "react",
+  "modules": [
+    "mobx-rules",
+    "mobx-skills"
+  ],
+  "detectionMarkers": [
+    "mobx"
+  ],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 318, Wave 4 batch 2"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": [
+      "mobx-store-implementation"
+    ],
+    "test": [
+      "mobx-observable-testing"
+    ],
+    "review": [],
+    "build-fix": [],
+    "migrate": []
+  }
+}

package/src/gdskills/bundled/stacks/mobx/rules/coding-style.mdc

@@ -0,0 +1,91 @@
+---
+extends: common
+paths: ["**/*.ts", "**/*.tsx"]
+metadata:
+  origin: authored
+---
+
+# MobX coding style
+
+Narrows the React/TypeScript common rules to MobX's own idiom for stores,
+observables, and observer components. Everything not MobX-specific still
+comes from the common and React rules this file `extends`.
+
+## Store class shape
+
+- Call `makeObservable(this)` (with an explicit annotations map, or
+  `makeAutoObservable(this)` for a store with no inheritance and no need to
+  keep some fields non-observable) once, in the constructor, before any
+  other constructor logic reads `this`.
+- Prefer explicit `@observable`/`@computed`/`@action`/`@action.bound`
+  decorators with `makeObservable` over `makeAutoObservable` for any store
+  a component subclasses, that mixes injected dependencies with state, or
+  that needs a field to stay non-observable — `makeAutoObservable` makes
+  every own enumerable property observable and every method an action,
+  which is the wrong default once the store has structure to protect.
+- Name store classes `XyzStore` and files `xyz.store.ts`/`XyzStore.ts` to
+  match the project's existing convention; keep one store per file.
+
+## Actions
+
+- Every method that mutates observable state must be an `action`
+  (`@action` or `@action.bound`). A public method invoked from a component
+  event handler must be `@action.bound` so it can be passed as a callback
+  reference without losing `this`.
+- After an `await` inside an async action, re-enter MobX with
+  `runInAction(() => { ... })` before mutating state — the code after the
+  `await` runs outside the original action's transaction.
+- Do not call a store method that mutates state directly from a component
+  render body; only from an event handler, effect, or another action.
+
+## Computed values
+
+- Any value derived purely from other observables belongs in a
+  `@computed get` accessor, not in a component-side calculation repeated
+  on every render or a store method that recomputes and returns a fresh
+  value each call. A `@computed` is cached and only re-evaluates when one
+  of its own observable dependencies changes.
+- Keep a `@computed` getter free of side effects; it must be safe to
+  evaluate speculatively (MobX may read a computed's value to decide
+  whether it changed).
+
+## Observable collections and value types
+
+- Use `@observable.ref` for a value the store treats as an opaque
+  reference (a large externally-owned object, a DOM/editor instance) it
+  does not want deeply proxied, `@observable.shallow` for a container
+  whose items should stay plain, and `@observable.struct` when a reaction
+  should only fire on a structural (deep-equal) change, not fine-grained.
+  Reserve the default deep `@observable` for state the store actually
+  wants MobX to track recursively.
+- When you need MobX's own collection API (`.replace()`, `.remove()`,
+  `.merge()`, `.has()`) on an array or map field, construct it with
+  `observable([...])` / `observable(new Map())` and type it as
+  `IObservableArray<T>` / `ObservableMap<K, V>`; a plain array/object
+  literal assigned to `@observable` is still deeply observed but does not
+  expose those methods.
+
+## Components
+
+- Wrap any function component that reads observable state in `observer`
+  from `mobx-react-lite`. A component that reads a store field but is not
+  wrapped in `observer` will render once and silently never update again
+  when that field changes.
+- Read store instances through a typed React context + hook pair
+  (`useXyzStore()`), not through a module-level singleton import, so
+  components stay testable and providers can swap the instance.
+- Do not destructure observable fields off a store at the top of a
+  component body if that breaks fine-grained tracking for a nested
+  `<Observer>` boundary further down — read the field where it is
+  actually rendered instead.
+
+## Errors and imports
+
+- Import MobX identifiers (`observable`, `action`, `computed`, `reaction`,
+  `runInAction`, `makeObservable`) from `"mobx"`, and `observer`,
+  `useLocalObservable` from `"mobx-react-lite"` — do not import from the
+  deprecated combined `mobx-react` package in new code unless the project
+  has not migrated off it yet.
+- Catch and store errors from an async action's `try/catch` as
+  `err: unknown`, narrowing before assigning to an observable `error`
+  field (see `rules/patterns.mdc` for the full async-action shape).

package/src/gdskills/bundled/stacks/mobx/rules/patterns.mdc

@@ -0,0 +1,122 @@
+---
+extends: common
+paths: ["**/*.ts", "**/*.tsx"]
+metadata:
+  origin: authored
+---
+
+# MobX patterns
+
+Idiomatic MobX design patterns and their anti-patterns, narrowing the
+common architecture rules to how state, actions, and reactions should be
+composed in a MobX + React codebase.
+
+## The async action shape
+
+The standard shape for a store method that calls an API and updates
+loading/error/data state:
+
+```typescript
+private performFetch = async () => {
+  try {
+    runInAction(() => {
+      this.loading = true;
+      this.error = null;
+    });
+
+    const data = await this.service.getAll();
+
+    runInAction(() => {
+      if (this.disposed) return;
+      this.items = data;
+    });
+  } catch (err: unknown) {
+    runInAction(() => {
+      if (this.disposed) return;
+      this.error = err instanceof Error ? err.message : "Fetch failed";
+    });
+  } finally {
+    runInAction(() => {
+      if (this.disposed) return;
+      this.loading = false;
+    });
+  }
+};
+```
+
+Anti-pattern: mutating `this.loading`/`this.items` directly after the
+`await` with no `runInAction` — this throws under `enforceActions: "observed"`
+and silently misses the reaction under looser settings, either way
+producing a UI that does not update.
+
+## `flow` as an alternative to `runInAction`
+
+For a store with many async actions, `flow` (a generator-based action)
+avoids repeating `runInAction` around every post-`await` mutation, since
+the whole generator body already runs inside one action:
+
+```typescript
+import { flow } from "mobx";
+
+fetchItems = flow(function* (this: ItemStore) {
+  this.loading = true;
+  try {
+    this.items = yield this.service.getAll();
+  } finally {
+    this.loading = false;
+  }
+});
+```
+
+Use `flow` when a store's async methods are mostly sequential awaits with
+state writes in between; keep plain `async`/`runInAction` when a method
+needs to interleave with non-MobX async code (`Promise.all`, cancellation
+tokens) where the generator form adds friction.
+
+## Reaction ownership and disposal
+
+- `reaction`/`autorun`/`when` created inside a store belong to that
+  store's lifecycle: push the disposer into a `disposers: IReactionDisposer[]`
+  array in the constructor (or an `init()` called by the parent) and call
+  every disposer in `dispose()`.
+- Prefer `reaction(() => selector, handler)` over `autorun` when the
+  handler should only run in response to a specific observable changing,
+  not on every observable it happens to read — `autorun` re-subscribes to
+  everything it touches on each run, which can widen its dependency set
+  unintentionally.
+- A component should not create a raw `autorun`/`reaction` in its render
+  body; either derive the value with `@computed` in the store and let
+  `observer` handle re-rendering, or start the reaction in a `useEffect`
+  and dispose it in the cleanup function.
+
+## Bidirectional store sync needs an equality guard
+
+When Store A writes to Store B and Store B writes back to Store A, guard
+the reverse direction with `if (newValue !== currentValue)` before
+propagating, or the two stores bounce a change back and forth forever.
+See `rules/coding-style.mdc` for where that callback belongs (private,
+not a public UI action).
+
+## View↔Store boundary
+
+- A component reads store state and calls store actions; it does not
+  hold a parallel copy of store state in `useState` "for convenience" —
+  that copy silently desyncs from the store the first time an action
+  outside that component's tree mutates the same field.
+- Data loading triggered by mounting belongs in the owning store's
+  `init()`/`onMount()`, called by the *parent* store or the top-level
+  provider — not scattered across every consuming component's
+  `useEffect`, which makes it impossible to reason about how many times a
+  fetch fires as the tree re-renders.
+- A store must not import a React component or hook; it may accept
+  plain callback props for the rare case a parent needs to react to a
+  child store's internal event.
+
+## Anti-pattern: computed-as-action
+
+A `@computed` getter must never mutate state — a getter with a
+side-effecting write inside it runs outside an explicit action
+transaction and MobX will throw ("computed value is allowed to be
+mutated only through action") the moment `enforceActions` is on. If a
+"derived" value also needs to cache an expensive side effect, that is an
+action-triggered `reaction`, not a computed.

package/src/gdskills/bundled/stacks/mobx/rules/security.mdc

@@ -0,0 +1,56 @@
+---
+extends: common
+paths: ["**/*.ts", "**/*.tsx"]
+metadata:
+  origin: authored
+---
+
+# MobX security
+
+Stack-specific risks narrowing the common OWASP-style rules to MobX state
+management. Most web security concerns (XSS, auth, injection) are
+React/general-web concerns already covered by the common and React rules
+this file `extends`; this file covers the risks that are specific to
+putting sensitive data in observable state.
+
+## Do not put secrets in long-lived observable state
+
+- A token, API key, or credential held in an `@observable` field on a
+  store that survives the session (not cleared on logout, persisted via
+  `autorun`/`reaction` to `localStorage`) is exposed to any code with
+  access to that store instance and to any DevTools-based MobX inspector
+  attached to the page. Keep secrets out of observable state; pass them
+  through a request layer that does not put them on a reactive object a
+  component tree (and any debugging tool observing it) can read.
+- If a `reaction`/`autorun` persists store state to `localStorage`/
+  `sessionStorage` (a common MobX pattern for "remember this UI state"),
+  explicitly exclude any field carrying a token, PII, or payment data from
+  what gets serialized — persist a derived, scrubbed snapshot, not the
+  whole store.
+
+## Untrusted data into observable state is still untrusted
+
+- Assigning server or user-supplied HTML/markdown into an observable
+  field does not sanitize it. If that field is later rendered with
+  `dangerouslySetInnerHTML` in an `observer` component, the same XSS risk
+  applies as any other React render path — sanitize before it reaches the
+  observable, not by trusting MobX's reactivity to be a security boundary
+  (see `rules/security.mdc` in the `react` pack this one extends).
+
+## Reaction-driven side effects and SSRF/open-redirect risk
+
+- A `reaction`/`autorun` that fires a `fetch`/navigation based on an
+  observable URL or hostname field must validate that value the same way
+  a request-time input would be validated — an attacker who can influence
+  the observable (e.g. via a query param synced into the store) can
+  otherwise trigger a request to an attacker-chosen host purely through
+  state changes, with no obvious call site to audit.
+
+## Disposal prevents stale-store data leaks across users/sessions
+
+- A store not disposed on logout/route-change can keep the previous
+  user's data in memory and observable to any component that still holds
+  a reference (e.g. a lingering `reaction` on a background tab). Call
+  `dispose()` on session/user change for any store holding
+  user-scoped data, not just to free memory — to stop rendering or
+  syncing stale, now-unauthorized data.

package/src/gdskills/bundled/stacks/mobx/rules/testing.mdc

@@ -0,0 +1,63 @@
+---
+extends: common
+paths: ["**/*.ts", "**/*.tsx"]
+metadata:
+  origin: authored
+---
+
+# MobX testing
+
+Narrows the common testing rules to what is specific about testing MobX
+stores, actions, and reactions — test layout, runner, and framework
+concerns for React components themselves still come from the `react`
+pack's own `rules/testing.mdc`.
+
+## Store tests are plain unit tests
+
+- A store with no React dependency (no `observer`, no hook) is tested by
+  constructing it directly and calling its actions/reading its computeds
+  — no React Testing Library render is needed. Co-locate the test next to
+  the store (`xyz.store.test.ts` beside `xyz.store.ts`), matching the
+  project's existing test-file convention.
+- Mock the store's injected dependencies (an API service passed into the
+  constructor), not MobX itself — MobX's reactivity is the thing under
+  test, not something to stub out.
+
+## Awaiting async actions and reactions
+
+- After calling an async action in a test, `await` the action's own
+  returned promise (for a plain `async` method) or `await` a `when(...)`
+  predicate on the resulting state (`await when(() => !store.loading)`)
+  before asserting — do not assert immediately after the call and rely on
+  a fixed `setTimeout`/sleep, which is both slower and flaky.
+- When asserting on a value only a `reaction`/`autorun` sets, wait for
+  that reaction to have run (`await when(() => condition)`, or `await
+  Promise.resolve()` for microtask-only sync reactions) rather than
+  asserting synchronously right after the triggering mutation.
+
+## `enforceActions` in tests
+
+- Keep `enforceActions` at the project's real (usually `"observed"` or
+  `"always"`) setting in tests rather than relaxing it to `"never"` for
+  convenience — a test that mutates observable state outside an action
+  should fail the same way production code would, since that failure is
+  exactly the bug class these tests exist to catch.
+- If a test genuinely needs to seed store state directly (bypassing
+  actions, e.g. to set up a precondition), wrap that seeding assignment
+  in `runInAction` rather than disabling `enforceActions` for the whole
+  suite.
+
+## Testing disposal and reaction cleanup
+
+- Assert that `dispose()` actually stops a store's reactions: trigger a
+  mutation after `dispose()` and confirm the disposed reaction's effect
+  did not run again — a leaked, undisposed `autorun`/`reaction` is a real
+  bug that a naive "does dispose() throw" test will not catch.
+
+## Component tests still need `observer`-aware setup
+
+- A test rendering an `observer` component must trigger the store
+  mutation the same way production code would (through the store's own
+  action) and then assert on the rendered output after that action
+  resolves — do not directly reassign an observable field the component
+  reads and expect the same ordering guarantees an action provides.

package/src/gdskills/bundled/stacks/mobx/skills/mobx-observable-testing/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: mobx-observable-testing
+description: "Use when writing or fixing a test for a MobX store: asserting on an async action's post-await state, waiting for a reaction/autorun to fire, testing that dispose() actually stops a store's reactions, or deciding how enforceActions should behave in the test setup. Distinct from rendering-focused React component testing and generic Node/TypeScript test-runner setup. Not for writing the store or action code itself (use mobx-store-implementation) and not for React Testing Library render/interaction patterns with no MobX involved (use react-testing)."
+triggers:
+  - "write a test for this MobX store's async fetch action"
+  - "test that this store's reaction actually fires"
+  - "my store test asserts before the async action finishes"
+  - "test that dispose() stops this store's autorun"
+  - "how should enforceActions behave in tests"
+  - "test this computed getter updates when the observable changes"
+  - "flaky MobX store test that sometimes reads stale state"
+metadata:
+  origin: authored
+  category: test
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# MobX observable testing
+
+Write or fix a test that exercises a MobX store's actions, computed
+values, or reactions directly — not through a component render. See
+`rules/testing.mdc` for the full set of conventions this skill applies,
+and `rules/patterns.mdc` for the async-action shape being tested.
+
+## Scope
+
+This skill is for testing MobX's own reactivity: does an action correctly
+update state, does a computed recompute, does a reaction fire and get
+disposed. It is not for writing the store/action code under test (use
+`mobx-store-implementation`) and not for React Testing Library
+render/interaction mechanics with no MobX-specific concern (use the
+`react` pack's testing skill) — a test that only checks a button click
+calls a prop handler has nothing MobX-specific in it and does not need
+this skill.
+
+## Workflow
+
+### Step 1: Identify what kind of MobX behavior is under test
+
+- A synchronous action's effect on observable state — assert immediately
+  after calling it.
+- An async action's effect on state after an `await` — the assertion has
+  to wait for the action's own promise (or a predicate) to resolve, not
+  run synchronously.
+- A `@computed` getter — assert it changes when its own observable
+  dependency changes, and does not change when an unrelated field does.
+- A `reaction`/`autorun`/`when` — assert its effect actually runs after
+  the triggering mutation, and stops running after `dispose()`.
+
+### Step 2: Construct the store with mocked dependencies
+
+Instantiate the store directly with mocked injected dependencies (an API
+service stub), not a full component tree. Keep `enforceActions` at the
+project's real setting (see `rules/testing.mdc`) — do not loosen it in
+test setup just to make an assertion easier to write.
+
+### Step 3: Write the assertion with the right wait
+
+- Sync action: call it, assert immediately.
+- Async action: `await` the action's returned promise directly if it's a
+  plain `async` method; otherwise `await when(() => <the condition the
+  action should reach>)` before asserting.
+- Reaction/autorun: trigger the mutation that should fire it, then
+  `await when(() => <the reaction's expected effect>)` (or `await
+  Promise.resolve()` for a synchronous microtask reaction) before
+  asserting the effect ran.
+- Never assert immediately after a mutation that a reaction depends on
+  without first waiting for that reaction to run, and never paper over a
+  flaky wait with a fixed `setTimeout`/sleep — it is both slower and
+  still not deterministic under load.
+
+### Step 4: Test disposal
+
+For a store owning `autorun`/`reaction`/`when`, add a test that calls
+`dispose()`, then triggers the mutation that would normally fire the
+reaction, and asserts the reaction's effect did NOT run again — a test
+that only checks `dispose()` doesn't throw misses the actual leak.
+
+### Step 5: Verify
+
+Run the project's test command and confirm the new/changed tests are
+deterministic (run them a few times in a row locally if they involve
+timing) and pass without a suppressed assertion.
+
+## Rules
+
+- Follow `rules/testing.mdc` for store test layout, mocking, and
+  `enforceActions` behavior.
+- ALWAYS wait for an async action's own completion (its promise, or a
+  `when(...)` predicate) before asserting on state it sets — never assert
+  synchronously right after calling it.
+- ALWAYS keep `enforceActions` at the project's real setting; seed
+  precondition state through `runInAction`, not by disabling it.
+- NEVER assert on a reaction's effect without first waiting for the
+  reaction to actually run.
+- NEVER skip or delete a store test to make a suite pass; fix the source
+  if behavior regressed, or fix the test if its expectation was stale —
+  state which, and why.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just add a `setTimeout(resolve, 100)` before asserting, it's fast enough in CI" | A fixed sleep is both slower than necessary and still not deterministic under load; wait on the action's own promise or a `when(...)` predicate instead |
+| "I'll set `enforceActions: 'never'` in the test file so I can mutate state directly to set up my fixture" | That hides the same bug class the real app would hit; seed fixture state through `runInAction` instead |
+| "The dispose() test just checks it doesn't throw, that's enough" | A store can dispose without ever having wired up its reactions correctly; assert the reaction's effect actually stops firing after dispose |
+| "This store test is flaky, I'll skip it for now" | Skipping hides a real timing bug in the store or the test's own wait strategy; find the missing `await`/`when` instead |
+
+## Verification
+
+Do not report a store test done until all of the following hold:
+
+- The project's test command passes for the new/changed test.
+- Every assertion on async-action or reaction state waits for that
+  action's promise or a `when(...)` predicate first — no bare
+  `setTimeout`/sleep.
+- `enforceActions` was not loosened in the test file to make setup
+  easier.
+- A store owning disposable reactions has a test proving `dispose()`
+  actually stops them, not just that it runs without throwing.
+- Re-running the test locally 2-3 times in a row produces the same
+  result (no flake from a missing wait).

package/src/gdskills/bundled/stacks/mobx/skills/mobx-observable-testing/evals.json

@@ -0,0 +1,73 @@
+{
+  "triggers": {
+    "positive": [
+      "I need a test for this MobX store's async method that fetches data from the API -- how do I make sure it actually waits for the result before I assert?",
+      "My store test asserts on this.items right after calling the async action and it's flaky",
+      "How do I test that this MobX store actually does something automatically when a value changes?",
+      "Write a test proving dispose() stops this store's reaction from running again",
+      "Should enforceActions be relaxed in my MobX store test setup?",
+      "How do I test that a derived value on this MobX store updates correctly when the thing it depends on changes?",
+      "This store test sometimes reads stale state before the reaction has run, fix the wait"
+    ],
+    "negative": [
+      "Add a new @action.bound method to this store's constructor that fetches items from the API and wraps the loading/error update in runInAction",
+      "Write a React Testing Library test that clicks this button and checks the handler prop was called",
+      "Add a @computed get totalPrice getter to this store class that sums the items array",
+      "Write a Vitest test for this plain utility function that formats a currency string",
+      "Fix this tsc error: Property 'total' does not exist on type 'OrderDraft'",
+      "Review this MobX store for accessibility-modifier and method-ordering issues"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "assert-after-async-action",
+      "prompt": "This test is flaky:\n\n```ts\nit(\"loads items\", () => {\n  store.fetchItems();\n  expect(store.items).toHaveLength(3);\n});\n```\n\n`fetchItems` is an async action. Why is this flaky and how do I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer explains that the assertion runs before the async fetchItems action has finished updating state, and fixes it by awaiting the action's own returned promise (or a when(...) predicate on the resulting state) before asserting, showing the corrected test code.",
+          "pass_criteria": [
+            "States that the test asserts synchronously right after calling fetchItems, before the async action's await has resolved and updated store.items, which is why the assertion sometimes sees stale/empty state",
+            "Shows the corrected test awaiting the action's own promise (e.g. `await store.fetchItems();`) or a `when(...)` predicate on the resulting state before the expect call"
+          ],
+          "fail_criteria": [
+            "Recommends adding a fixed setTimeout/sleep delay before the assertion instead of awaiting the action's own promise or a when(...) predicate -- mentioning that only to warn against it is not a failure",
+            "Leaves the assertion running synchronously right after the fetchItems() call with no await or wait predicate added at all"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "The test calls `store.fetchItems()` without awaiting it, then asserts immediately -- but fetchItems is async, so the assertion runs before the underlying await (the API call) has resolved and the action has had a chance to set store.items. That's why it's flaky: sometimes the promise resolves fast enough by coincidence, sometimes it doesn't. Fix it by awaiting the action itself:\n\n```ts\nit(\"loads items\", async () => {\n  await store.fetchItems();\n  expect(store.items).toHaveLength(3);\n});\n```\n\nIf fetchItems doesn't return its promise (e.g. it's fire-and-forget from a UI action), wait on a predicate instead: `await when(() => !store.loading);` before asserting. Either way, the test needs to wait for the actual async work to finish rather than assuming it already has.",
+        "known_wrong": "Flaky async tests like this usually just need a bit more time to settle -- add a small delay before the assertion: `store.fetchItems(); await new Promise(r => setTimeout(r, 200)); expect(store.items).toHaveLength(3);`. 200ms should be more than enough for the fetch to resolve in a test environment, and it's a quick fix that doesn't require changing fetchItems itself.",
+        "vague": "The test probably isn't waiting long enough for the async action to complete before checking the result, so you need to make sure it waits properly.",
+        "subtle_wrong": "I made the test function async and added `await Promise.resolve();` after calling fetchItems, since that lets one microtask cycle run before the assertion: `it(\"loads items\", async () => { store.fetchItems(); await Promise.resolve(); expect(store.items).toHaveLength(3); });`. That should cover most cases since a single microtask flush usually catches up with pending promise resolutions in this test environment."
+      }
+    },
+    {
+      "id": "dispose-test-effect",
+      "prompt": "I have a store with an autorun disposed in dispose(). My current test is:\n\n```ts\nit(\"disposes cleanly\", () => {\n  store.dispose();\n});\n```\n\nDoes this actually prove the autorun stops running? If not, what should the test do instead?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer states that the current test only proves dispose() doesn't throw, not that the autorun actually stops firing, and fixes it by disposing the store, then triggering the mutation the autorun depends on, and asserting the autorun's effect did not run again.",
+          "pass_criteria": [
+            "States that the current test only proves dispose() runs without throwing, not that the autorun's effect actually stops firing after disposal",
+            "Shows or names a corrected test that calls dispose(), then mutates the observable the autorun depends on, then asserts the autorun's tracked effect (e.g. a spy/counter it increments) did not run again"
+          ],
+          "fail_criteria": [
+            "Claims the existing test (calling dispose() alone with no post-dispose mutation or assertion) is already sufficient to prove the autorun stops running",
+            "Recommends asserting only that store.disposed is set to true as proof the reaction stopped, without triggering the dependent mutation and checking the reaction's own effect did not re-run"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "No -- calling dispose() and asserting nothing else only proves dispose() doesn't throw. It says nothing about whether the autorun's own effect actually stopped running afterward. To prove that, trigger the mutation the autorun depends on after disposal and check its effect didn't fire again:\n\n```ts\nit(\"stops the autorun after dispose\", () => {\n  const spy = vi.fn();\n  const store = new ItemStore({ onCountChange: spy }); // autorun calls onCountChange internally\n  store.disposeCallCount = 0;\n\n  store.dispose();\n  runInAction(() => {\n    store.items.push(newItem()); // would normally trigger the autorun\n  });\n\n  expect(spy).not.toHaveBeenCalled();\n});\n```\n\nThe key part is the mutation *after* dispose() and the assertion that the tracked effect did not run again -- without both, the test can't actually distinguish a correctly-disposed reaction from one that was never wired up correctly in the first place.",
+        "known_wrong": "The current test is fine -- if dispose() didn't clean up the autorun's internal MobX subscription correctly, calling it would throw an error from MobX's reaction system. Since it completes without throwing, that's good evidence the disposer ran and the reaction was torn down properly. No need to add a post-dispose mutation check.",
+        "vague": "That test probably isn't strong enough -- you should check that the autorun really doesn't keep running after dispose, not just that dispose itself works.",
+        "subtle_wrong": "Good catch -- I strengthened it by asserting `store.disposed` is `true` right after calling dispose(): `store.dispose(); expect(store.disposed).toBe(true);`. That confirms the store's own disposed flag flipped, which is what the autorun's guard checks internally, so if disposed is true the autorun's guarded logic won't run on the next reaction anyway."
+      }
+    }
+  ]
+}