opencode-effect-enforcer 0.2.0

package/patterns/avoid-process-env.md

@@ -0,0 +1,43 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-process-env
+description: Avoid process.env - use Effect Config.* for environment variable access
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: process.env
+level: warning
+suggestSkills:
+    - effect-config
+---
+
+# Avoid `process.env`
+
+```haskell
+-- Transformation
+processEnv :: String -> IO (Maybe String)    -- side effect, untyped, untestable
+
+-- Instead
+Config.string :: String -> Config String     -- typed, composable, testable
+Config.withDefault :: a -> Config a -> Config a
+Config.redacted :: String -> Config Redacted -- for sensitive values
+```
+
+```haskell
+-- Pattern
+bad :: Effect String
+bad = Effect.sync \_ -> process.env.API_KEY    -- raw side effect
+
+good :: Effect String ConfigError
+good = Config.string "API_KEY"                 -- typed, validated
+
+better :: Effect String ConfigError
+better = Config.string("PORT")
+  & Config.withDefault "3000"
+  & Config.map Number.parse                    -- with transformation
+```
+
+`process.env` is a raw side effect with no type safety. Use `Config.*` for validated, composable, testable configuration.
+
+Exception: `xdg/core` and similar platform abstraction layers that ARE the env variable bridge.

package/patterns/avoid-react-hooks.md

@@ -0,0 +1,73 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-react-hooks
+description: React hooks (useState, useEffect, useReducer, etc.) should be avoided - use View Models with Effect Atom instead
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern:
+    - 'useState($$$)'
+    - 'useState<$$$>($$$)'
+    - 'useEffect($$$)'
+    - 'useEffect<$$$>($$$)'
+    - 'useReducer($$$)'
+    - 'useReducer<$$$>($$$)'
+    - 'useCallback($$$)'
+    - 'useCallback<$$$>($$$)'
+    - 'useMemo($$$)'
+    - 'useMemo<$$$>($$$)'
+    - 'useRef($$$)'
+    - 'useRef<$$$>($$$)'
+    - 'useLayoutEffect($$$)'
+    - 'useImperativeHandle($$$)'
+    - 'useDebugValue($$$)'
+    - 'useDeferredValue($$$)'
+    - 'useTransition($$$)'
+    - 'useId($$$)'
+    - 'useSyncExternalStore($$$)'
+    - 'useInsertionEffect($$$)'
+level: high
+suggestSkills:
+    - effect-react-vm
+---
+
+# Avoid React Hooks - Use View Models
+
+```haskell
+-- Transformation
+useState     :: a → (a, a → ())          -- scattered state, untestable
+useEffect    :: (() → ()) → [a] → ()     -- cleanup error-prone
+
+-- Instead: View Model pattern
+data VM = VM
+  { state$  :: Atom State               -- reactive state
+  , action  :: () → Effect ()           -- effectful actions
+  }
+
+-- Component is pure renderer
+component :: VM → JSX
+component vm = useAtomValue (state$ vm)  -- only reads atoms
+```
+
+```haskell
+-- Replacements
+useState      → vmAtom :: Atom a
+useEffect     → vmAction :: Effect ()
+useCallback   → derivedAtom :: Atom (a → b)
+useMemo       → derivedAtom :: Atom a
+useRef (DOM)  → pass from parent ∨ VM trigger
+useSearchParams → Atom.searchParam
+useEffect (cleanup) → Atom.make with get.addFinalizer
+
+-- Architecture
+data Component = Component
+  { view :: VM → JSX           -- pure renderer
+  , vm   :: Layer VM           -- testable, injectable
+  }
+
+-- Invoke skill for implementation
+invoke "react-vm"
+```
+
+React hooks scatter state across components. Use View Models: state in atoms, effects in actions, components as pure renderers.

package/patterns/avoid-schema-suffix.md

@@ -0,0 +1,45 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-schema-suffix
+description: Schema constants should be named after the domain type, not suffixed with Schema
+glob: '**/*.{ts,tsx}'
+pattern: \b(const|let)\s+\w+Schema\s*=\s*Schema\.
+level: info
+---
+
+# Name Schemas After the Domain Type
+
+```haskell
+-- Transformation
+const UserSchema = Schema.String       -- redundant suffix, not the domain name
+const User       = Schema.String       -- named after the domain concept
+
+-- Pattern
+bad :: Schema naming
+bad = const UserSchema = Schema.Struct({ ... })
+bad = const OrderIdSchema = Schema.String
+bad = export const PayloadSchema = Schema.Class(...)
+
+good :: Schema naming
+good = const User = Schema.String
+good = export const OrderId = Schema.String
+good = class Payload extends Schema.Class<Payload>("Payload")({ ... })
+```
+
+```haskell
+-- For non-class schemas, export type alias with same name
+export const OrderId = Schema.String
+export type OrderId = typeof OrderId.Type
+
+-- For class schemas, the name is built-in
+export class User extends Schema.Class<User>("User")({
+  id: Schema.String,
+  name: Schema.String
+}) {}
+```
+
+Schema constants should be named after the domain type they represent, not suffixed with `Schema`. The `Schema` suffix is redundant since the value itself is already a schema — the name should communicate what it models, not what it is.
+
+References: EF-3, Checklist #8 in effect-first-development.md

package/patterns/avoid-sync-fs.md

@@ -0,0 +1,68 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-sync-fs
+description: Avoid synchronous filesystem operations
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern:
+    - 'readFileSync($$$)'
+    - '$A.readFileSync($$$)'
+    - 'writeFileSync($$$)'
+    - '$A.writeFileSync($$$)'
+    - 'mkdirSync($$$)'
+    - '$A.mkdirSync($$$)'
+    - 'readdirSync($$$)'
+    - '$A.readdirSync($$$)'
+    - 'statSync($$$)'
+    - '$A.statSync($$$)'
+    - 'existsSync($$$)'
+    - '$A.existsSync($$$)'
+    - 'copyFileSync($$$)'
+    - '$A.copyFileSync($$$)'
+    - 'unlinkSync($$$)'
+    - '$A.unlinkSync($$$)'
+    - 'rmdirSync($$$)'
+    - '$A.rmdirSync($$$)'
+    - 'renameSync($$$)'
+    - '$A.renameSync($$$)'
+    - 'appendFileSync($$$)'
+    - '$A.appendFileSync($$$)'
+level: high
+suggestSkills:
+    - effect-filesystem
+---
+
+# Avoid Synchronous Filesystem Operations
+
+```haskell
+-- Transformation
+readFileSync  :: FilePath → IO String     -- blocks event loop
+writeFileSync :: FilePath → String → IO () -- same problem
+
+-- Instead
+readFileString  :: FilePath → Effect String FileSystem
+writeFileString :: FilePath → String → Effect () FileSystem
+```
+
+```haskell
+-- Pattern
+bad :: FilePath → IO String
+bad path = fs.readFileSync path "utf-8"   -- blocking, defeats async
+
+good :: FilePath → Effect String FileSystem
+good path = do
+  fs ← FileSystem.FileSystem
+  fs.readFileString path                  -- non-blocking, composable
+
+-- Sync → Async mapping
+readFileSync   → readFileString
+writeFileSync  → writeFileString
+mkdirSync      → makeDirectory
+existsSync     → exists
+unlinkSync     → remove
+readdirSync    → readDirectory
+```
+
+Sync operations block the event loop. Use Effect's FileSystem service for async, composable file operations.

package/patterns/avoid-try-catch.md

@@ -0,0 +1,47 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-try-catch
+description: Avoid try-catch blocks in Effect code - use Effect.try or typed errors
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: 'try { $$$ }'
+level: warning
+suggestSkills:
+    - effect-error-handling
+---
+
+# Avoid `try { } catch` in Effect Code
+
+```haskell
+-- Transformation
+tryCatch :: IO a → IO (Either Error a)    -- loses error types
+effectTry :: (() → a) → Effect a E        -- preserves error channel
+
+-- Error handling
+catchTag  :: Tag → (E → Effect a) → Effect a E → Effect a (E - Tag)
+catchTags :: {Tag₁: h₁, Tag₂: h₂} → Effect a E → Effect a (E - Tags)
+```
+
+```haskell
+-- Pattern
+bad :: () → { success :: Bool, data :: Maybe a, error :: Maybe String }
+bad () = try
+  result ← riskyOperation
+  pure { success: True, data: Just result, error: Nothing }
+ catch e →
+  pure { success: False, data: Nothing, error: Just (show e) }
+
+good :: Effect a DataError
+good = Effect.try
+  { try:   riskyOperation
+  , catch: DataError <<< show
+  }
+
+-- Or with TaggedError
+data DataError = DataError { message :: String }
+  deriving Schema.TaggedError "DataError"
+```
+
+`try-catch` breaks the error channel—errors become opaque. Use `Effect.try` with `Schema.TaggedError` for typed, composable error handling.

package/patterns/avoid-ts-ignore.md

@@ -0,0 +1,38 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-ts-ignore
+description: Avoid using @ts-ignore or @ts-expect-error to silence type errors
+glob: '**/*.{ts,tsx}'
+pattern: @ts-(ignore|expect-error)
+level: warning
+matchInComments: true
+---
+
+# Avoid `@ts-ignore` and `@ts-expect-error`
+
+```haskell
+-- Anti-pattern
+tsIgnore :: TypeError → ()    -- hide error, pray at runtime
+tsExpect :: TypeError → ()    -- same with false confidence
+
+-- Instead
+fix        :: TypeError → Code → Code        -- address root cause
+guard      :: Unknown → Maybe Known          -- runtime validation
+schema     :: Schema a → Unknown → Either ParseError a
+```
+
+```haskell
+-- Pattern
+bad :: Effect a
+bad = do
+  -- @ts-ignore
+  x ← brokenCode          -- compiler is wrong, right?
+
+good :: Effect a
+good = do
+  x ← Schema.decode schema raw   -- prove correctness
+```
+
+Suppressing errors masks bugs that surface at runtime. Fix the underlying type issue instead.

package/patterns/avoid-untagged-errors.md

@@ -0,0 +1,67 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-untagged-errors
+description: Review raw Error usage; recoverable domain failures should use Schema.TaggedError
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - all:
+              - pattern: 'new Error($$$)'
+              - not:
+                    inside:
+                        pattern: Effect.die($$$)
+                        stopBy: end
+        - pattern: '$A instanceof Error'
+level: info
+suggestSkills:
+    - effect-error-handling
+---
+
+# Avoid `instanceof Error` and `new Error`
+
+```haskell
+-- Transformation
+instanceofError :: Error → Bool           -- opaque, no discrimination
+newError        :: String → Error         -- untagged, untrackable
+
+-- Instead
+data MyError = MyError { message :: Schema.String }
+  deriving Schema.TaggedError "MyError"
+
+taggedFail :: MyError → Effect a MyError
+catchTag   :: "MyError" → (MyError → Effect a) → Effect a E → Effect a (E - MyError)
+```
+
+```haskell
+-- Pattern
+bad :: Error → Effect ()
+bad e
+  | e `instanceof` Error = log (message e)    -- which error type?
+  | otherwise            = pure ()
+
+good :: Effect () MyError
+good = pipe
+  myEffect
+  $ catchTag "MyError" \e → log (message e)
+
+-- Exhaustive handling
+handle :: Effect a (E₁ | E₂ | E₃) → Effect a ∅
+handle = catchTags
+  { E₁: handler₁
+  , E₂: handler₂
+  , E₃: handler₃
+  }
+```
+
+`Schema.TaggedError` enables exhaustive pattern matching via `_tag`, serialization, and RPC compatibility. Use `catchTag` for type-safe error discrimination.
+
+Exceptions:
+
+- `new Error(...)` inside `Effect.die(...)` for impossible states or programmer bugs
+- invariant branches inside runtime adapters where the failure should remain a defect
+- interop callbacks that must produce a raw throwable before being re-captured at the boundary
+
+Do not use those exceptions for user-facing or recoverable domain failures. Because syntax alone cannot establish whether a raw error is a defect, interop value, or recoverable failure, this diagnostic is informational and requires contextual review.

package/patterns/avoid-yield-ref.md

@@ -0,0 +1,46 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: avoid-yield-ref
+description: Do not yield* Ref/Deferred/Fiber/Latch directly — use explicit method calls
+glob: '**/*.ts'
+detector: ast
+rule:
+    pattern: yield* $RESOURCE
+constraints:
+    RESOURCE:
+        regex: '(^ref$|Ref$|^deferred$|Deferred$|^fiber$|Fiber$|^latch$|Latch$)'
+level: warning
+suggestSkills:
+    - effect-schema-v4
+---
+
+# Do Not `yield*` Ref, Deferred, Fiber, or Latch Directly
+
+```haskell
+-- Transformation
+yield* ref       :: Ref a -> a          -- removed in v4
+Ref.get(ref)     :: Ref a -> Effect a   -- correct, explicit
+yield* deferred  :: Deferred a -> a     -- removed in v4
+Deferred.await   :: Deferred a -> Effect a  -- correct, explicit
+yield* fiber     :: Fiber a -> a        -- removed in v4
+Fiber.join       :: Fiber a -> Effect a -- correct, explicit
+```
+
+```haskell
+-- Pattern
+bad :: Direct yield
+bad = const value = yield* ref
+bad = yield* deferred
+bad = yield* fiber
+bad = yield* latch
+
+good :: Explicit method
+good = const value = yield* Ref.get(ref)
+good = yield* Deferred.await(deferred)
+good = yield* Fiber.join(fiber)
+good = yield* Latch.await(latch)
+```
+
+In Effect v4, yielding `Ref`, `Deferred`, `Fiber`, and `Latch` directly is removed. Use explicit method calls (`Ref.get`, `Deferred.await`, `Fiber.join`, `Latch.await`) for clarity and forward compatibility.

package/patterns/casting-awareness.md

@@ -0,0 +1,46 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: casting-awareness
+description: Type assertions bypass the compiler — use type-safe alternatives
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: $A as $B
+level: info
+suggestSkills:
+    - effect-domain-modeling
+    - effect-domain-predicates
+---
+
+# Stop — do you actually need `as`?
+
+Most `as` casts can be replaced. Try these in order:
+
+1. **Remove it.** Check the actual type with LSP (`hover`/`Go to Definition`). If it's already correct or the cast just papers over a fixable upstream type, delete the assertion entirely.
+
+2. **`satisfies`** — validates a value matches a type at compile time without changing the inferred type. No runtime cost, no lying to the compiler:
+
+    ```ts
+    const config = { port: 3000 } satisfies ServerConfig;
+    ```
+
+3. **`Schema.is(MySchema)`** — runtime type guard that narrows correctly. Replaces `as` when you need to check unknown/union data:
+
+    ```ts
+    if (Schema.is(User)(value)) {
+    	/* value: User */
+    }
+    ```
+
+4. **`Schema.decodeUnknownSync(MySchema)`** — validates unknown data with full error reporting instead of blindly trusting it:
+
+    ```ts
+    const user = Schema.decodeUnknownSync(User)(data);
+    ```
+
+5. **`Predicate.isString` / `isNumber` / `isRecord` / etc.** — Effect's built-in type guards for primitives and structures.
+
+6. **`MyEnum.$is("Tag")`** or **`Schema.is(VariantSchema)`** — type guard for discriminated union variants. See `effect-domain-modeling` skill for the full pattern.
+
+`as const` is fine — it narrows to literal types. Every other `as` is the compiler waving a white flag. Fix the types instead.

package/patterns/context-tag-extends.md

@@ -0,0 +1,84 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: context-tag-extends
+description: Use Context.Service for all service definitions — avoid Context.Tag, Effect.Service, and the legacy ServiceMap.* APIs
+glob: '**/*.{ts,tsx}'
+detector: ast
+rule:
+    any:
+        - pattern: 'class $A extends Context.Tag'
+        - pattern: 'class $A extends Context.Tag<$$$>() { $$$ }'
+        - pattern: 'Context.GenericTag<$$$>'
+        - pattern: 'Context.Tag($$$)'
+        - pattern: 'Effect.Service<$$$>()'
+        - pattern: 'ServiceMap.Service'
+        - pattern: 'ServiceMap.Reference'
+        - pattern: 'ServiceMap.make'
+        - pattern: 'ServiceMap.get'
+        - pattern: 'ServiceMap.add'
+        - pattern: 'ServiceMap.mergeAll'
+level: warning
+suggestSkills:
+    - effect-service-implementation
+---
+
+# Use `Context.Service` for All Service Definitions
+
+`Context.Service` is the single canonical service-definition API in Effect v4 (beta.46+). Three legacy spellings exist and must all be replaced:
+
+| Legacy API                  | Era       | Replacement                |
+| --------------------------- | --------- | -------------------------- |
+| `Context.Tag` / `GenericTag` | pre-v4    | `Context.Service`          |
+| `Effect.Service`            | early v4  | `Context.Service`          |
+| `ServiceMap.Service` / `.*` | beta.43    | `Context.Service` / `Context.*` |
+
+```haskell
+-- Anti-pattern: *Tag suffix + Context.Tag — removed in v4
+class ParallelClientTag extends Context.Tag
+data ParallelClientService = ...
+-- two names for one concept = unnecessary coupling
+
+-- Anti-pattern: Effect.Service — also removed in v4
+class ParallelClient extends Effect.Service<ParallelClient>()(...)
+
+-- Anti-pattern: ServiceMap.* — removed before v4 beta.46 stabilized
+class MyService extends ServiceMap.Service<MyService>()("@app/MyService", { ... })
+
+-- Fix: Context.Service (beta.46 API)
+class ParallelClient extends Context.Service<ParallelClient>()(
+  "@parallel/ParallelClient"
+)
+```
+
+```typescript
+// Concrete service (single implementation)
+export class ParallelClient extends Context.Service<ParallelClient>()(
+	'@parallel/ParallelClient'
+) {}
+
+// Interface-style service (multiple implementations, config, infrastructure)
+export class Clipboard extends Context.Service<Clipboard>()(
+	'@Clipboard/Clipboard'
+) {}
+```
+
+When migrating from `ServiceMap`, also update the corresponding module accessors:
+
+- `ServiceMap.get` → `Context.get`
+- `ServiceMap.make` → `Context.make`
+- `ServiceMap.add` → `Context.add`
+- `ServiceMap.mergeAll` → `Context.mergeAll`
+- `effect/ServiceMap` import → `effect/Context`
+
+## Design Rules
+
+- **Never** use a `*Tag` suffix — name the service directly
+- `Context.Service` gives you service identity and lookup; it does not replace explicit layer design
+- Export `layer` to expose the real dependency graph
+- Export `defaultLayer` only when there are unsatisfied requirements to wire
+- Capture dependencies in `Layer.effect` via `yield*`, not hidden module globals
+- Access services with `yield* MyService` or `MyService.use(...)`
+
+This pattern subsumes the legacy `use-context-service` pattern — the `ServiceMap.*` family is now folded in here so there's a single, comprehensive entry point for v4 service-definition migration.

package/patterns/effect-catchall-default.md

@@ -0,0 +1,61 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: effect-catchall-default
+description: Avoid broad Effect.catch defaults in domain logic - use catchTag unless this is an explicit boundary fallback
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern:
+    - 'Effect.catch($X => Effect.succeed($$$))'
+    - 'Effect.catch($X => Effect.sync($$$))'
+    - 'Effect.catch($X => succeed($$$))'
+    - 'Effect.catch($X => sync($$$))'
+level: warning
+suggestSkills:
+    - effect-error-handling
+---
+
+# Avoid `Effect.catch` with Default Values
+
+```haskell
+-- Transformation
+catch :: (E -> Effect a) -> Effect a E -> Effect a _
+catch _ default = \_ -> succeed default    -- swallows all errors silently
+
+-- Instead
+catchTag  :: Tag -> (E -> Effect a) -> Effect a E -> Effect a (E - Tag)
+catchTags :: {Tag1: h1, ...} -> Effect a E -> Effect a (E - Tags)
+```
+
+```haskell
+-- Pattern
+bad :: Effect User _
+bad = pipe
+  fetchUser
+  $ catch \_ -> succeed defaultUser    -- which error? why?
+
+good :: Effect User (NetworkError | Timeout)
+good = pipe
+  fetchUser
+  $ catchTag "NotFound" \_ -> do
+      log "User not found, creating..."
+      createDefaultUser               -- explicit, logged, traceable
+
+-- For expected absence
+better :: Effect (Option User) NetworkError
+better = pipe
+  fetchUser
+  $ Option.some                       -- Option, not error swallowing
+  $ catchTag "NotFound" \_ -> Option.none
+```
+
+`Effect.catch` with defaults often hides bugs and loses context. Use `catchTag` for specific errors with logging, or `Option` for expected absence.
+
+Legitimate exceptions exist at explicit boundaries:
+
+- best-effort cache hydration
+- capability probes and optional integrations
+- remote config or metadata loads where the contract is "fallback to neutral default"
+
+In those cases, document the fallback intent in code review and keep the fallback close to the boundary.

package/patterns/effect-promise-vs-trypromise.md

@@ -0,0 +1,47 @@
+---
+action: context
+tool: (edit|write)
+event: after
+name: effect-promise-vs-trypromise
+description: Use Effect.tryPromise instead of Effect.promise for error handling
+glob: '**/*.{ts,tsx}'
+detector: ast
+pattern: Effect.promise
+level: warning
+suggestSkills:
+    - effect-error-handling
+---
+
+# Use Effect.tryPromise Instead of Effect.promise
+
+```haskell
+-- Transformation
+promise    :: IO (Promise a) → Effect a ∅        -- rejection = defect (uncatchable)
+tryPromise :: IO (Promise a) → Effect a E        -- rejection = typed error (catchable)
+```
+
+```haskell
+-- Pattern
+bad :: Effect User ∅
+bad = Effect.promise \_ → fetchUser id
+  -- rejection becomes Defect: can't catch, crashes fiber
+
+good :: Effect User FetchError
+good = Effect.tryPromise
+  { try:   \_ → fetchUser id
+  , catch: \e → FetchError (show e)
+  }
+  -- rejection becomes typed error: catchable, testable
+
+-- Error handling
+handle :: Effect User FetchError → Effect User ∅
+handle = catchTag "FetchError" \e → defaultUser
+
+-- Defects bypass all handlers
+defect :: Effect a ∅ → Effect a E
+defect = id    -- can't recover from defects
+```
+
+`Effect.promise` converts rejections to uncatchable defects. Use `Effect.tryPromise` for typed, recoverable errors in the E channel.
+
+Any reference to `Effect.promise` is flagged — not just `yield* Effect.promise(...)`. Piping, passing, or returning `Effect.promise` propagates the same defect-conversion problem to the consumer and is equally wrong.