@t4h.framework/core 0.6.1 → 0.8.0

package/.ai/skills/framework-workflow-creation/SKILL.md

@@ -1,26 +1,41 @@
 ---
 name: framework-workflow-creation
 description: >-
-  Design and implement T4H Framework workflows with @t4h.framework/core using
-  the project's standard structure for workflow files, app registration, and
-  environment handling. Use this whenever the user asks to create a new
-  workflow, wire it into an App, define orchestration with History.reconciler,
-  or refactor workflow code to remove hardcoded URLs/secrets/client values and
-  move configuration to env constants.
+  Design and implement T4H Framework workflows with @t4h.framework/core: expose
+  a Workflow constant with metadata/schema, orchestrate with the framework's
+  package primitives (http, sleep, startWorkflow) plus plain TypeScript, and
+  read configuration from a shared EnvDesign in constants/environments.ts.
+  Register it in an App. Use whenever the user asks to create a new workflow,
+  wire it into an App, or refactor workflow code to remove hardcoded
+  URLs/secrets/client values and move configuration to an EnvDesign.
 ---
 
 # Create workflows with `@t4h.framework/core`
 
-Use this skill to build production-ready workflow modules that are easy to register, test, and maintain.
+Use this skill to build production-ready workflows that are easy to register, test, and maintain.
+
+A **workflow is orchestration only**: an async function that coordinates steps. The steps themselves — HTTP calls, delays, storage — come from the framework's packages. You compose those primitives; you do **not** build low-level infrastructure inside a workflow.
 
 ## Primary goal
 
 Create workflows that:
 
 - expose a `Workflow` constant with explicit metadata (`id`, optional `description`, optional `schema`);
-- orchestrate work through framework primitives (`History.reconciler`, `startWorkflow`) instead of ad-hoc infrastructure code;
-- register cleanly in `App` with `export default new App({...})`;
-- never hardcode URLs, secrets, tokens, client IDs, or tenants in workflow files.
+- orchestrate through framework primitives (`http`, `sleep`, `startWorkflow`) plus plain TypeScript and `env` — never ad-hoc infrastructure code;
+- register cleanly in an `App` (`export default new App({...})`);
+- never hardcode URLs, secrets, tokens, client IDs, or tenants.
+
+## What you orchestrate with
+
+| Need | Use | From |
+|------|-----|------|
+| External HTTP call | `http.get/post/put/...` | `@t4h.framework/http` (see **framework-http**) |
+| Delay / wait | `sleep('30 seconds')` | `@t4h.framework/sleep` (see **framework-sleep**) |
+| Nested workflow | `startWorkflow(child, input)` | `@t4h.framework/core` |
+| Configuration | `environments.MY_KEY` from a shared `EnvDesign` | `@t4h.framework/core` |
+| Branching / mapping | plain TypeScript | — |
+
+Keep the body **deterministic** so it replays safely: branch on inputs and step results, never on `Date.now()`, `Math.random()`, or ambient state. Use `sleep` when you need time to pass.
 
 ## Expected project shape
 
@@ -28,9 +43,12 @@ Create workflows that:
 
 ```ts
 import { Workflow } from '@t4h.framework/core'
+import { http } from '@t4h.framework/http'
+import { environments } from '../constants/environments.js'
 
 export const myWorkflow = new Workflow({ id: 'my-workflow' }, async input => {
-  // orchestration only
+  const res = await http.post(`${environments.SERVICE_URL}/events`, { json: { input } })
+  return { status: res.status }
 })
 ```
 
@@ -47,66 +65,79 @@ export default new App({
 })
 ```
 
-### Environment constants module
+### Environment constants module — `constants/environments.ts`
+
+**Standard pattern: declare every env var in a single `EnvDesign` inside `src/constants/environments.ts`, export it, and import it wherever configuration is needed.** Do not use the raw `env` proxy or `process.env`.
 
 ```ts
-import { env } from '@t4h.framework/core'
+// src/constants/environments.ts
+import { EnvDesign } from '@t4h.framework/core'
+
+export const environments = EnvDesign({
+  SERVICE_URL: { type: String },
+  MAX_RETRIES: { type: Number, defaultValue: '3' },
+  DEBUG: { type: Boolean, isOptional: true },
+})
+```
+
+Then, inside a workflow (or any helper), read typed values from it:
 
-export const SERVICE_URL = env.SERVICE_URL!
-if (!SERVICE_URL) throw new TypeError('SERVICE_URL is not defined')
+```ts
+import { environments } from '../constants/environments.js'
+// environments.SERVICE_URL -> string, environments.MAX_RETRIES -> number
 ```
 
-Keep this in a dedicated constants file and import values into workflows/activities.
+Why `EnvDesign` and not raw `env`:
 
-## Core APIs to prefer while authoring workflows
+- **Typed & validated:** each key is parsed to its declared `type` (`String` | `Number` | `Boolean` | a custom `(raw: string) => T` parser); a missing required key throws on access (fail-fast), `defaultValue` fills gaps, `isOptional: true` allows `undefined`.
+- **Lazy & safe at import:** `EnvDesign({...})` does not read `env` at construction, so the top-level `export const environments = ...` is safe. Values are read/parsed only when a key is accessed — so **access keys inside the workflow body/functions, never at module top level**.
+- **Manifest for free:** declaring vars via `EnvDesign` registers them in `app.toManifest().env`, so the runtime knows which vars the app requires.
 
-- `Workflow` for orchestration entrypoints.
-- `History.reconciler(ActivityClass, ...args)` to execute activities deterministically.
-- `startWorkflow(childWorkflow, { ...input, parallel? })` for nested workflow orchestration.
-- `App` to register workflow modules for runtime discovery.
-- `env` / `EnvDesign` for configuration contracts (not inline literal secrets).
+One `environments` object is the single source of configuration for the whole project — import it anywhere instead of re-declaring env access.
 
 ## Authoring rules
 
-1. Keep workflows orchestration-focused. Put low-level operations in activities and claims.
-2. Define workflow metadata with stable `id`.
-3. Use schema when input validation is needed.
-4. Import configuration from environment constants.
-5. Keep side effects explicit and easy to assert in tests.
+1. Keep workflows orchestration-focused — coordinate steps, don't implement them.
+2. Perform every external effect through a framework package primitive (`http`, `sleep`, …), not `fetch`/`axios`/raw SDKs.
+3. Define workflow metadata with a stable `id`.
+4. Add a `schema` when input validation is needed.
+5. Import all configuration from the shared `EnvDesign` in `constants/environments.ts` — never raw `env` or `process.env`.
+6. Keep the body deterministic so replay produces the same result.
 
 ## Hard constraints
 
 - Do not hardcode URLs, client IDs, client secrets, API keys, tenants, or tokens.
 - Do not initialize third-party clients with inline credentials inside workflow files.
-- Do not read `process.env` directly in workflow modules when the project uses centralized constants via `env`.
+- Do not read `process.env` or the raw `env` proxy directly — declare configuration in the shared `EnvDesign` (`constants/environments.ts`).
+- Do not call `fetch`/`axios` or other non-framework I/O directly — that breaks replay safety.
 
-If a required env key is missing, fail fast with a clear `TypeError` in the constants module.
+Required keys declared in the `EnvDesign` fail fast automatically: accessing an unset required key throws `Environment variable X is not set`. Use `isOptional`/`defaultValue` when a key may be absent.
 
 ## Workflow implementation recipe
 
 ### Step 1: define/extend env constants
 
-- Add required keys in a constants module.
-- Export each key from `env.<KEY>!`.
-- Validate each key immediately with an explicit `TypeError`.
+- Open (or create) `src/constants/environments.ts` and add the required keys to the exported `EnvDesign`.
+- Give each key a `type` (`String`/`Number`/`Boolean`/custom parser) and, when applicable, `defaultValue` or `isOptional`.
+- Import `environments` where needed; do not add per-key getters or read raw `env`.
 
-### Step 2: create workflow file
+### Step 2: create the workflow file
 
-- Import `Workflow` and required orchestration helpers.
-- Import only typed/safe constants (never raw secrets inline).
-- Implement the function body as orchestration steps.
+- Import `Workflow` and the package primitives you need (`http`, `sleep`, `startWorkflow`).
+- Import typed/safe constants only (never raw secrets inline).
+- Implement the body as orchestration steps.
 
-### Step 3: wire in App
+### Step 3: wire it into the App
 
-- Import the workflow module in `main.tsx`.
+- Import the workflow in `main.tsx`.
 - Add it to `workflows: [...]` in `new App({...})`.
-- Keep `App` declaration as default export for runtime loading.
+- Keep the `App` as the default export for runtime loading.
 
 ### Step 4: make it test-friendly
 
-- Keep outputs deterministic where possible.
+- Keep outputs deterministic.
 - Avoid hidden global state.
-- Structure side effects so they can be mocked by claim/activity tests.
+- Drive external effects through package primitives so tests can supply their providers (see **framework-core** testing and each package's skill).
 
 ## Recommended patterns
 
@@ -116,31 +147,45 @@ If a required env key is missing, fail fast with a clear `TypeError` in the cons
 import Type from 'typebox'
 import { Workflow } from '@t4h.framework/core'
 
-const schema = Type.Object({
-  customerId: Type.String(),
-})
+const schema = Type.Object({ customerId: Type.String() })
 
 export const customerSync = new Workflow(
   { id: 'customer-sync', schema },
-  async input => {
-    return { accepted: true, customerId: input.customerId }
+  async input => ({ accepted: true, customerId: input.customerId }),
+)
+```
+
+### B) Workflow orchestrating an external call
+
+```ts
+import { Workflow } from '@t4h.framework/core'
+import { http } from '@t4h.framework/http'
+
+export const notifyLong = new Workflow(
+  { id: 'notify-long', schema: Type.String() },
+  async (input: string) => {
+    if (input.length > 5) {
+      await http.post('https://example.com/webhook', { json: { input } })
+    }
   },
 )
 ```
 
-### B) Workflow orchestrating activities
+### C) Workflow with a delay
 
 ```ts
-import { History, Workflow } from '@t4h.framework/core'
+import { Workflow } from '@t4h.framework/core'
+import { http } from '@t4h.framework/http'
+import { sleep } from '@t4h.framework/sleep'
 
-export const processOrder = new Workflow({ id: 'process-order' }, async input => {
-  const prepared = await History.reconciler(PrepareOrderActivity, input)
-  const charged = await History.reconciler(ChargeOrderActivity, prepared)
-  return { charged }
+export const retryLater = new Workflow({ id: 'retry-later' }, async input => {
+  await http.post('https://example.com/start', { json: input })
+  await sleep('5 minutes')
+  await http.post('https://example.com/finish', { json: input })
 })
 ```
 
-### C) Nested workflow orchestration
+### D) Nested workflow orchestration
 
 ```ts
 import { Workflow, startWorkflow } from '@t4h.framework/core'
@@ -154,17 +199,20 @@ export const parentWorkflow = new Workflow({ id: 'parent-workflow' }, async inpu
 
 ## Anti-patterns to remove on sight
 
-- Inline `"https://..."` service endpoints in workflow body.
-- Inline `"secret"` / `"clientId"` string literals in workflow code.
-- Creating SDK/API clients with literal credentials in the workflow function.
-- Large workflow functions doing infrastructure plumbing instead of orchestration.
-- Registering workflows in scattered places instead of centralized `App` declaration.
+- Inline `"https://..."` endpoints or `"secret"` / `"clientId"` literals in the workflow body — pull them from the shared `EnvDesign`.
+- Reading raw `env`/`process.env`, or scattering per-key env getters instead of one `EnvDesign` in `constants/environments.ts`.
+- Accessing an `EnvDesign` key at module top level (throws — no env storage outside a run).
+- Creating SDK/API clients with literal credentials inside the workflow function.
+- Calling `fetch`/`axios` or other raw I/O instead of the framework's `http` primitive.
+- Building custom low-level infrastructure inside a consuming app to make a workflow work — use the framework packages that already provide it.
+- Large workflow functions doing plumbing instead of orchestration.
+- Registering workflows in scattered places instead of the centralized `App` declaration.
 
 ## Output expectations when executing this skill
 
 When asked to create a workflow, produce:
 
 1. A new workflow file exporting a named `Workflow` constant.
-2. Any required env constants in the central constants module.
-3. `App` registration update with the workflow included.
+2. Any required env keys added to the shared `EnvDesign` in `constants/environments.ts`.
+3. An `App` registration update with the workflow included.
 4. No hardcoded client, secret, token, tenant, or URL values in workflow code.

package/.ai/skills/framework-workflow-testing/SKILL.md

@@ -2,171 +2,225 @@
 name: framework-workflow-testing
 description: >-
   Build and maintain high-quality unit tests for T4H Framework workflows using
-  @t4h.framework/core/testing. Use this whenever the user asks to test a
-  workflow, add Vitest coverage for History.reconciler flows, mock claims,
-  validate logs, or simulate async activity outcomes (fulfilled/rejected/timeout),
-  even when they only mention "workflow test", "mock claim", or "run workflow in memory".
+  @t4h.framework/core/testing and per-package testing entrypoints. Use this
+  whenever the user asks to test a workflow, add Vitest coverage for
+  History.reconciler flows, mock claims, validate logs, or simulate async
+  activity outcomes (fulfilled/rejected/timeout), even when they only mention
+  "workflow test", "mock claim", or "run workflow in memory".
 ---
 
 # Workflow unit testing with `@t4h.framework/core/testing`
 
 Use this skill to create or improve **workflow-focused unit tests** in T4H Framework projects.
 
-## What this skill optimizes
+Harness APIs live in `@t4h.framework/core/testing`. 
 
-- Fast in-memory workflow execution with `WorkflowTesting.run`.
-- Reliable claim mocking with real claim instances + `vi.spyOn`.
-- Clear assertions for behavior (calls, payload, order, and logs).
-- Predictable handling of async activities with `mockAsyncActivity`.
+Use `TestWorkflowEnvironment` as the primary test harness. It runs the workflow
+in-memory and automatically validates replay determinism after every `execute()`.
 
-## When to choose this skill
+## What this skill optimizes
 
-Choose this skill when the user asks to:
+- Fast in-memory workflow execution with `TestWorkflowEnvironment.execute()`.
+- Typed claim mocks with `mockClaim` / `createMockClaims` (no manual casts).
+- Predictable async activity mocking with `mockAsync()` builder.
+- Clear assertions for behavior (calls, payload, order).
 
-- test a `Workflow` end-to-end (without infra);
-- mock outbound dependencies used by activities (HTTP, DB, etc.);
-- assert emitted logs for workflow execution paths;
-- simulate async activity outcomes in tests;
-- add or fix `vitest` tests for workflow modules.
+## Public API
 
-If the request is specifically about testing `AsyncActivity.advance`, use `Internals.runActivity` directly instead of only `WorkflowTesting.run`.
+```ts
+import {
+  createMockClaim,
+  createMockClaims,
+  createTestEnv,
+  createTestEnvEntries,
+  fulfilled,
+  mockAsync,
+  mockClaim,
+  NonDeterministicWorkflowError,
+  rejected,
+  TestClock,
+  TestWorkflowEnvironment,
+  timeout,
+} from '@t4h.framework/core/testing'
+```
 
-## Public API available
+### TestWorkflowEnvironment
 
 ```ts
-import { WorkflowTesting } from '@t4h.framework/core/testing'
+const env = TestWorkflowEnvironment.create({ now: 0 })
+// resolveActivityTimeouts defaults to true
+
+const output = await env.execute(workflow, input, {
+  claims,
+  env: envEntries,
+  mockAsyncActivity,
+})
+// Replay determinism is validated automatically after each execute()
+
+env.clock.now()        // current pinned timestamp (ms)
+env.clock.advance(ms)  // advance pinned clock
+env.clock.set(now)     // set pinned clock to a Date | number
 ```
 
-`WorkflowTesting.run(workflow, input?, options?)`
+`TestWorkflowEnvironment.create()` options:
 
-Supported options:
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `now` | `0` | Pins `Date.now()` to this value at start |
+| `resolveActivityTimeouts` | `true` | Auto-advances clock to each activity's `timeoutAt` and resolves it via `onTimeout` |
 
-- `claims`: claim providers used during execution.
-- `env`: environment entries for `Env.run`.
-- `mockAsyncActivity`: function or queue for pending async activities.
-- `logs`: capture runtime logs.
-- `maxTicks`: protect against infinite replay loops (default `10_000`).
+`execute()` options:
+
+| Option | Type | Purpose |
+|--------|------|---------|
+| `claims` | `readonly ClaimProvider[]` | Claim implementations |
+| `env` | `Env.Entries` | String env vars |
+| `mockAsyncActivity` | `MockAsyncActivity` | Required when `bootstrap` returns `pending` and `resolveActivityTimeouts` doesn't cover it |
+
+After `execute()` returns, the clock is advanced to wherever the run left it.
+Subsequent `env.clock.advance()` calls build on that value between tests.
+
+Async activities are resolved in tests through `mockAsyncActivity` (which returns
+a final outcome directly). Workflow tests never drive an activity's internal
+`advance` method — you only assert the workflow's observable output and effects.
+
+## Test file location
+
+Place each test in a `__tests__` folder next to the file under test — not in a
+separate top-level tests directory. For example, a test for `src/workflows/approval.ts`
+lives at `src/workflows/__tests__/approval.test.ts`.
 
 ## Canonical workflow test pattern
 
-Follow this structure by default:
+1. Arrange claims with `mockClaim` or package mocks in helper functions.
+2. Create `TestWorkflowEnvironment` in `beforeEach`.
+3. Execute workflow with `env.execute()`.
+4. Assert on output and mock calls.
+
+### Mock the claims each activity uses
 
-1. Arrange claims and spies in helper functions.
-2. Initialize setup in `beforeEach`.
-3. Execute workflow with `WorkflowTesting.run`.
-4. Assert calls, payload structure, ordering, and logs.
+A workflow never talks to a claim directly — it calls a package primitive
+(`http.get`, `smtp.send`, `Sftp`, `orm.find`, …) which runs an activity, and the
+**activity** resolves the claims. So a workflow test provides one mock per claim
+that the triggered activities depend on. Each package skill lists its claim(s)
+(e.g. HTTP → `HttpClientRequestClaim` + `FileSystemClaim`; SFTP → `SftpClaim`;
+ORM → `ORMClaim`; OAuth → also `CacheClaim`).
 
-Base mock style on this pattern:
+`mockClaim(ClaimClass, impl)` returns a `ClaimProvider`; put them in a plain array:
 
 ```ts
-function createClaimsWithHttpSpy() {
-  const http = findClaimByConstructor(DevHttpClientRequestClaim)
-  const mockRequest = vi.spyOn(http, 'request').mockResolvedValue({
-    status: 200,
-    headers: { 'content-type': 'application/json' },
-    body: Readable.from(Buffer.from('{}')),
-  })
-  return { claims, mockRequest }
-}
+import { mockClaim } from '@t4h.framework/core/testing'
+import { HttpClientRequestClaim } from '@t4h.framework/http'
+import { FileSystemClaim } from '@t4h.framework/fs'
+
+const mockRequest = vi.fn().mockImplementation(async () => ({
+  status: 200,
+  headers: { 'content-type': 'application/json' },
+  body: Readable.from(Buffer.from('{"ok":true}')),
+}))
+
+const claims = [
+  mockClaim(HttpClientRequestClaim, { request: mockRequest }),
+  mockClaim(FileSystemClaim, { write: mockWrite, read: vi.fn() }),
+]
 ```
 
-Why this pattern: it keeps tests close to real wiring while still allowing strict call inspection.
+`createMockClaims` is the same thing from a list of `[ClaimClass, impl]` tuples:
 
-## Standard recipe for new tests
-
-### 1) Create setup helpers
+```ts
+import { createMockClaims } from '@t4h.framework/core/testing'
 
-- Put claim setup and spies in dedicated functions (`createClaimsWith...`).
-- Return both `claims` and the spy object(s) for assertions.
-- Keep data decoders (e.g. request-body parser) as small utility functions.
+const claims = createMockClaims([
+  [HttpClientRequestClaim, { request: mockRequest }],
+  [FileSystemClaim, { write: mockWrite, read: vi.fn() }],
+])
+```
 
-### 2) Execute workflow under test
+Use `mockImplementation` (not `mockResolvedValue`) for mocks that return streams or
+objects that can only be consumed once — replay runs the workflow a second time and
+needs fresh values.
 
-- Use `await WorkflowTesting.run(workflow, input, { claims, logs, ... })`.
-- Capture logs with `const logs: Log[] = []` when log behavior matters.
+Unconfigured claim methods throw with a clear error — configure every method the
+workflow may call.
 
-### 3) Assert behavior and contract
+## Async activities with `mockAsync()`
 
-Prefer these assertions:
+`mockAsync()` returns a builder that is also a valid `MockAsyncActivity`. Chain
+`.on()` calls to declare how each activity type should resolve.
 
-- call count (`toHaveBeenCalledTimes`);
-- important call arguments (URL, method, payload);
-- ordering (`mock.calls[0]`, `mock.calls[1]`);
-- final workflow output;
-- log messages and sequence (`logs.map(entry => entry.args[0])`).
+### Outcome helpers
 
-### 4) Cover async outcomes when applicable
+```ts
+fulfilled(output?)  // { status: 'fulfilled', output }
+rejected(reason?)   // { status: 'rejected', reason }
+timeout()           // { status: 'timeout' } — runs the activity's real onTimeout()
+```
 
-If any async activity can return `pending`, provide `mockAsyncActivity`.
+### Builder API
 
-Function strategy:
+**Static outcome per type:**
 
 ```ts
-mockAsyncActivity: (activity, { index, pending }) => {
-  if (index === 0) return { status: 'fulfilled', output: true }
-  return { status: 'rejected', reason: 'denied' }
-}
+mockAsyncActivity: mockAsync()
+  .on(WaitForApprovalActivity, fulfilled(true))
+  .on(EmailActivity, fulfilled())
 ```
 
-Queue strategy:
+**Sequential outcomes per type** (per-type call count, not global):
 
 ```ts
-mockAsyncActivity: [
-  { status: 'fulfilled', output: true },
-  { status: 'timeout' },
-]
+mockAsyncActivity: mockAsync()
+  .on(WaitForApprovalActivity, [
+    rejected(new Error('transient')),
+    fulfilled(true),
+  ])
 ```
 
-Important behavior:
-
-- no resolver + pending async => throws;
-- timeout outcome runs real `onTimeout`;
-- exhausted queue => throws `No more async outcomes`.
+**Callback with per-type `callCount`:**
 
-## Mocking guidelines (do this, avoid that)
+```ts
+mockAsyncActivity: mockAsync()
+  .on(WaitForApprovalActivity, (activity, { callCount }) =>
+    callCount === 0 ? rejected() : fulfilled(true)
+  )
+```
 
-Do:
+**Auto-resolve timeout-based activities** (e.g. `SleepActivity`):
 
-- mock concrete claim instances used by runtime providers;
-- use `vi.spyOn` on dependency methods (e.g. `request`);
-- return realistic shapes (status/headers/body) for external call mocks;
-- isolate each test with `beforeEach`.
+```ts
+mockAsyncActivity: mockAsync()
+  .on(WaitForApprovalActivity, fulfilled(true))
+  .timeout()  // resolves any remaining activity that has timeoutAt
+```
 
-Avoid:
+**Fallback for unregistered types:**
 
-- over-mocking framework internals;
-- asserting implementation details unrelated to behavior;
-- using `WorkflowTesting.run` to validate real `advance` logic.
+```ts
+mockAsyncActivity: mockAsync()
+  .on(WaitForApprovalActivity, fulfilled(true))
+  .fallback(() => timeout())
+```
 
-## Minimal template to generate quickly
+**Combine with `TestWorkflowEnvironment`** — `resolveActivityTimeouts: true` (the default)
+handles all `timeoutAt`-based activities automatically; only provide `mockAsyncActivity`
+when you need finer control:
 
 ```ts
-import { WorkflowTesting } from '@t4h.framework/core/testing'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-
-describe('my workflow', () => {
-  let claims: ReturnType<typeof createClaimsWithSpy>['claims']
-  let mockCall: ReturnType<typeof vi.spyOn>
-
-  beforeEach(() => {
-    const setup = createClaimsWithSpy()
-    claims = setup.claims
-    mockCall = setup.mockCall
-  })
-
-  it('runs to completion with expected side effects', async () => {
-    const logs = []
-    await WorkflowTesting.run(myWorkflow, undefined, { claims, logs })
-    expect(mockCall).toHaveBeenCalledTimes(1)
-  })
+const env = TestWorkflowEnvironment.create({ now: 0 })
+
+await env.execute(workflow, undefined, {
+  claims,
+  mockAsyncActivity: mockAsync()
+    .on(WaitForApprovalActivity, fulfilled(true))
+    // SleepActivity resolves automatically via resolveActivityTimeouts default
 })
 ```
 
-## Completion checklist before finishing
+## Completion checklist
 
-- Test imports `WorkflowTesting` from `@t4h.framework/core/testing`.
-- Claim providers are passed via `options.claims`.
-- Pending async paths have `mockAsyncActivity`.
-- Assertions cover side effects and expected ordering.
-- Logs are asserted when they are part of the workflow contract.
-- Test file uses Vitest idioms consistently.
+- Test file lives in a `__tests__` folder next to the file under test.
+- Harness imported from `@t4h.framework/core/testing`.
+- Claims built with `mockClaim` / `createMockClaims` — avoid `as unknown as`.
+- Pending async paths have `mockAsyncActivity` via `mockAsync()` builder.
+- Mocks returning streams use `mockImplementation`, not `mockResolvedValue`.
+- Assertions cover output, side effects, and expected ordering.