ETS-XX-NNN:
  predicate: "what must be true"
  on_fail:
    severity: BLOCKER | MAJOR | MINOR
    remediation: "how to fix it"

stateDiagram-v2
    [*] --> ASSESS
    ASSESS --> ROUTE
    ROUTE --> WRITE_SERVICE: new service
    ROUTE --> MIGRATE: porting legacy module
    ROUTE --> PATCH: bugfix or small change
    WRITE_SERVICE --> CHECK_PATTERNS
    MIGRATE --> CHECK_PATTERNS
    PATCH --> CHECK_PATTERNS
    CHECK_PATTERNS --> VERIFY
    VERIFY --> [*]

    VERIFY --> FIX: typecheck/test/build fails
    FIX --> VERIFY

inputs:
  - task_description: string
  - affected_files: string[]
  - codebase_state: MigrationPhase

operations:
  - INVOKE references/00_operating_mode.md

assertions:
  - ASSERT task_description IS_CLEAR
  - ASSERT affected_files IDENTIFIED

exit_criteria:
  - route: NEW_SERVICE | MIGRATE | PATCH

inputs:
  - written_code: ChangeSet

operations:
  - PARALLEL:
      - INVOKE references/01_effect_service_pattern.md
      - INVOKE references/02_error_handling.md
      - INVOKE references/03_schema_and_types.md
  - SEQUENTIAL:
      - INVOKE references/04_testing_and_verification.md
      - INVOKE references/06_effect_typescript_hazards.md

outputs:
  - findings: Finding[]

inputs:
  - written_code: ChangeSet

operations:
  - RUN bun run typecheck
  - RUN bun run test
  - RUN bun run build
  - IF service_migration: RUN bun run dev

assertions:
  - ASSERT typecheck.exit_code == 0
  - ASSERT test.exit_code == 0
  - ASSERT build.exit_code == 0

exit_criteria:
  - all_assertions_pass: true

src/
├── errors.ts                  # All domain errors (Data.TaggedError)
├── schemas.ts                 # All domain types (Effect Schema)
├── redact.ts                  # Pure secret redaction (redactLine)
├── AppConfig.ts               # Config service + static constant exports
├── AppLogger.ts               # Pino logger + Effect logger bridge
├── DeployLogger.ts            # Dual ANSI + JSONL deploy logger (Effect)
├── MountSecurityService.ts    # Mount validation service
├── db.ts                      # DatabaseService (wraps better-sqlite3)
├── phone-caller.ts            # PhoneCallerService (ElevenLabs + Twilio)
├── container-runner.ts        # ContainerRunnerService (Docker lifecycle)
├── task-scheduler.ts          # TaskSchedulerService (cron/interval/once)
├── index.ts                   # Main entry (legacy, migrating last)
└── __tests__/

// 1. Shape interface
export interface FooServiceShape {
  readonly doThing: (input: Input) => Effect.Effect<Output, FooError>;
}

// 2. Context Tag
export class FooService extends Context.Tag('FooService')<
  FooService, FooServiceShape
>() {}

// 3. Implementation
const makeFooService = Effect.gen(function* () {
  const doThing: FooServiceShape['doThing'] = (input) =>
    Effect.gen(function* () { /* ... */ });
  return { doThing } satisfies FooServiceShape;
});

// 4. Layer
export const FooServiceLive = Layer.effect(FooService, makeFooService);

// 5. Legacy wrapper (migration only)
const legacyService = Effect.runSync(makeFooService);
export function doThing(input: Input): Output {
  return Effect.runSync(legacyService.doThing(input));
}

// Define
export class FooError extends Data.TaggedError('FooError')<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

// Fail
return yield* new FooError({ message: 'broke' });

// Wrap sync I/O
yield* Effect.try({
  try: () => fs.readFileSync(path, 'utf-8'),
  catch: (err) => new FileReadError({ path, message: String(err), cause: err }),
});

// Recover
yield* someEffect.pipe(Effect.catchTag('FooError', (e) => Effect.succeed(alt)));

export const Foo = Schema.Struct({
  name: Schema.String,
  status: Schema.Literal('active', 'paused'),
  items: Schema.Array(Schema.String),
  optional: Schema.optional(Schema.String),
  nullable: Schema.NullOr(Schema.String),
});
export type Foo = typeof Foo.Type;

import { Effect } from 'effect';
import { describe, expect, it, vi, beforeEach } from 'vitest';
import { FooService, FooServiceLive } from '../FooService.js';

describe('FooService', () => {
  beforeEach(() => { vi.clearAllMocks(); });

  it('should do the thing', () => {
    const program = Effect.gen(function* () {
      const service = yield* FooService;
      return yield* service.doThing(input);
    });
    const result = Effect.runSync(program.pipe(Effect.provide(FooServiceLive)));
    expect(result).toEqual(expected);
  });
});

1. Create FooBarService.ts (service pattern)
2. Add errors to src/errors.ts
3. Add schemas to src/schemas.ts
4. Export legacy wrappers (same signatures)
5. Update importers (change import path only)
6. Write tests in src/__tests__/
7. Verify: bun run typecheck && bun run test && bun run build
8. Do NOT delete old module until Phase 6

bun run typecheck   # Zero errors
bun run test            # All tests pass
bun run build       # Clean compilation

bun run dev         # App starts, processes messages normally