From 45972aff1428f333b7b625e1823f20b7f1180837 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 08:49:12 +0200
Subject: [PATCH 01/15] feat: implement error() factory function

Add the core error() factory that creates typed, structured errors following
the Standard Schema specification for field definitions.

Features:
- Accept config with name, fields (Standard Schema), inherits, message, httpStatus
- Support single and multiple inheritance via ErrorFactory references
- Message templates with {field} placeholders and :upper/:lower/:json modifiers
- Full ErrorInstance with name, message, stack, fields, notes, cause, causes,
  context, httpStatus
- Type inference for fields via Standard Schema
- Factory metadata (name, inherits, schema, template, httpStatus)

Tests:
- 36 unit tests covering all acceptance criteria
- Basic usage, ErrorInstance properties, inherits option, message templates,
  httpStatus, Standard Schema support, type inference, factory identity, stack traces

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/eslint.config.js  |   5 +-
 packages/errors/package.json      |  11 +-
 packages/errors/src/index.test.ts | 401 +++++++++++++++++++++++++++++-
 packages/errors/src/index.ts      | 273 +++++++++++++++++++-
 pnpm-lock.yaml                    |  25 ++
 5 files changed, 704 insertions(+), 11 deletions(-)

diff --git a/packages/errors/eslint.config.js b/packages/errors/eslint.config.js
index ff7f4b3..cb77328 100644
--- a/packages/errors/eslint.config.js
+++ b/packages/errors/eslint.config.js
@@ -7,7 +7,10 @@ export default tseslint.config(
   {
     files: ['src/**/*.ts'],
     rules: {
-      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/no-unused-vars': ['error', {
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      }],
     },
   },
   {
diff --git a/packages/errors/package.json b/packages/errors/package.json
index 36e177f..cbdfa15 100644
--- a/packages/errors/package.json
+++ b/packages/errors/package.json
@@ -19,7 +19,12 @@
     "type-check": "tsc --noEmit",
     "lint": "eslint src/"
   },
-  "keywords": ["typescript", "errors", "exception", "error-handling"],
+  "keywords": [
+    "typescript",
+    "errors",
+    "exception",
+    "error-handling"
+  ],
   "author": "Nesalia Inc. <hello@nesalia.com>",
   "license": "MIT",
   "devDependencies": {
@@ -28,5 +33,9 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.0.0",
     "vitest": "^4.1.7"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^25.9.1"
   }
 }
\ No newline at end of file
diff --git a/packages/errors/src/index.test.ts b/packages/errors/src/index.test.ts
index 4815946..fc3eabe 100644
--- a/packages/errors/src/index.test.ts
+++ b/packages/errors/src/index.test.ts
@@ -1,8 +1,397 @@
+/**
+ * Unit tests for the error() factory function.
+ */
+
 import { describe, it, expect } from 'vitest';
-import { helloWorld } from '../src/index';
+import { error } from '../src/index';
+import type { ErrorFactory, ErrorInstance, StandardSchemaV1 } from '../src/index';
+
+// Mock Standard SDK interface for testing (simplified StandardSchemaV1)
+interface MockSchema<T> extends StandardSchemaV1 {
+  '~standard': StandardSchemaV1.Props<T, T> & {
+    validate: () => StandardSchemaV1.Result<T>;
+  };
+}
+
+// Helper to create a mock Standard SDK compatible object
+function createMockSchema<T>( name: string = 'mock' ): MockSchema<T> {
+  return {
+    '~standard': {
+      version: 1,
+      vendor: name,
+      validate: () => ( { value: undefined as unknown as T } ),
+    },
+  };
+}
+
+describe( 'error() factory function', () => {
+  describe( 'basic usage', () => {
+    it( 'should create an error factory with only a name', () => {
+      const NotFoundError = error( {
+        name: 'NotFoundError',
+      } );
+
+      expect( typeof NotFoundError ).toBe( 'function' );
+      expect( NotFoundError.name ).toBe( 'NotFoundError' );
+    } );
+
+    it( 'should create an error factory with name property', () => {
+      const AppError = error( { name: 'AppError' } );
+
+      expect( AppError.name ).toBe( 'AppError' );
+    } );
+
+    it( 'should throw when calling the factory without field types (basic)', () => {
+      const BasicError = error( { name: 'BasicError' } );
+
+      const instance = BasicError();
+      expect( instance ).toBeDefined();
+      expect( instance.name ).toBe( 'BasicError' );
+      expect( instance.message ).toBe( 'BasicError' );
+      expect( instance.stack ).toBeDefined();
+      expect( instance.stack ).toContain( 'Error: BasicError' );
+    } );
+  } );
+
+  describe( 'ErrorInstance properties', () => {
+    it( 'should create error instance with all required properties', () => {
+      const TestError = error( { name: 'TestError' } );
+      const instance = TestError();
+
+      // Core properties
+      expect( typeof instance.name ).toBe( 'string' );
+      expect( typeof instance.message ).toBe( 'string' );
+      expect( typeof instance.stack ).toBe( 'string' );
+
+      // Additional properties
+      expect( instance.fields ).toBeDefined();
+      expect( typeof instance.fields ).toBe( 'object' );
+      expect( Array.isArray( instance.notes ) ).toBe( true );
+      expect( instance.notes ).toEqual( [] );
+      expect( instance.cause ).toBeNull();
+      expect( Array.isArray( instance.causes ) ).toBe( true );
+      expect( instance.causes ).toEqual( [] );
+      expect( instance.context ).toBeNull();
+      expect( instance.httpStatus ).toBeNull();
+    } );
+
+    it( 'should have _factory reference back to the creator', () => {
+      const TestError = error( { name: 'TestError' } );
+      const instance = TestError();
+
+      expect( instance._factory ).toBe( TestError );
+    } );
+
+    it( 'should have _inherits reference when inheriting', () => {
+      const ParentError = error( { name: 'ParentError' } );
+      const ChildError = error( {
+        name: 'ChildError',
+        inherits: ParentError,
+      } );
+      const instance = ChildError();
+
+      expect( instance._inherits ).toBe( ParentError );
+    } );
+  } );
+
+  describe( 'inherits option', () => {
+    it( 'should support single inheritance', () => {
+      const AppError = error( { name: 'AppError' } );
+      const ValidationError = error( {
+        name: 'ValidationError',
+        inherits: AppError,
+      } );
+
+      expect( ValidationError.inherits ).toBe( AppError );
+    } );
+
+    it( 'should support multiple inheritance', () => {
+      const NetworkError = error( { name: 'NetworkError' } );
+      const StorageError = error( { name: 'StorageError' } );
+      const CombinedError = error( {
+        name: 'CombinedError',
+        inherits: [NetworkError, StorageError],
+      } );
+
+      expect( Array.isArray( CombinedError.inherits ) ).toBe( true );
+      expect( ( CombinedError.inherits as ErrorFactory[] ).length ).toBe( 2 );
+    } );
+
+    it( 'should not have inherits property when not specified', () => {
+      const SimpleError = error( { name: 'SimpleError' } );
+
+      expect( 'inherits' in SimpleError ).toBe( false );
+    } );
+
+    it( 'should store inherits on factory for later type checking', () => {
+      const ParentA = error( { name: 'ParentA' } );
+      const ParentB = error( { name: 'ParentB' } );
+      const Child = error( {
+        name: 'Child',
+        inherits: [ParentA, ParentB],
+      } );
+
+      const instance = Child();
+      expect( instance._inherits ).toBeDefined();
+      expect( Array.isArray( instance._inherits ) ).toBe( true );
+    } );
+  } );
+
+  describe( 'message template', () => {
+    it( 'should store message template for later formatting', () => {
+      const ValidationError = error<{ field: string }>( {
+        name: 'ValidationError',
+        message: 'Field "{field}" is invalid',
+      } );
+
+      expect( ValidationError.template ).toBe( 'Field "{field}" is invalid' );
+    } );
+
+    it( 'should format message with field placeholders', () => {
+      const ValidationError = error<{ field: string }>( {
+        name: 'ValidationError',
+        message: 'Field "{field}" is invalid',
+      } );
+
+      const instance = ValidationError( { field: 'email' } );
+      expect( instance.message ).toBe( 'Field "email" is invalid' );
+    } );
+
+    it( 'should handle multiple placeholders', () => {
+      const ValidationError = error<{ field: string; expected: string; actual: string }>( {
+        name: 'ValidationError',
+        message: 'Field "{field}" expected {expected}, got {actual}',
+      } );
+
+      const instance = ValidationError( {
+        field: 'age',
+        expected: 'number',
+        actual: 'string',
+      } );
+      expect( instance.message ).toBe( 'Field "age" expected number, got string' );
+    } );
+
+    it( 'should use name as default message when no template', () => {
+      const InternalError = error( { name: 'InternalError' } );
+
+      const instance = InternalError();
+      expect( instance.message ).toBe( 'InternalError' );
+    } );
+
+    it( 'should use template without placeholders as-is', () => {
+      const FixedError = error( {
+        name: 'FixedError',
+        message: 'Something went wrong',
+      } );
+
+      const instance = FixedError();
+      expect( instance.message ).toBe( 'Something went wrong' );
+    } );
+
+    it( 'should support :upper modifier', () => {
+      const ErrorWithModifier = error<{ userId: string }>( {
+        name: 'ErrorWithModifier',
+        message: 'User ID: {userId:upper}',
+      } );
+
+      const instance = ErrorWithModifier( { userId: 'abc123' } );
+      expect( instance.message ).toBe( 'User ID: ABC123' );
+    } );
+
+    it( 'should support :lower modifier', () => {
+      const ErrorWithModifier = error<{ msg: string }>( {
+        name: 'ErrorWithModifier',
+        message: 'Message: {msg:lower}',
+      } );
+
+      const instance = ErrorWithModifier( { msg: 'HELLO WORLD' } );
+      expect( instance.message ).toBe( 'Message: hello world' );
+    } );
+
+    it( 'should support :json modifier', () => {
+      const DataError = error<{ data: { id: number; name: string } }>( {
+        name: 'DataError',
+        message: 'Invalid data: {data:json}',
+      } );
+
+      const instance = DataError( { data: { id: 1, name: 'test' } } );
+      expect( instance.message ).toBe( 'Invalid data: {"id":1,"name":"test"}' );
+    } );
+
+    it( 'should leave placeholder unchanged if field not found', () => {
+      const PartialError = error<{ field: string }>( {
+        name: 'PartialError',
+        message: 'Field "{field}" is invalid',
+      } );
+
+      const instance = PartialError( { field: '' } );
+      expect( instance.message ).toBe( 'Field "" is invalid' );
+    } );
+
+    it( 'should skip formatting when no fields provided', () => {
+      const TemplateError = error<{ field: string }>( {
+        name: 'TemplateError',
+        message: 'Field "{field}" is invalid',
+      } );
+
+      const instance = TemplateError();
+      expect( instance.message ).toBe( 'Field "{field}" is invalid' );
+    } );
+  } );
+
+  describe( 'httpStatus', () => {
+    it( 'should store httpStatus when provided', () => {
+      const NotFoundError = error( {
+        name: 'NotFoundError',
+        httpStatus: 404,
+      } );
+
+      expect( NotFoundError.httpStatus ).toBe( 404 );
+    } );
+
+    it( 'should set httpStatus on error instance', () => {
+      const NotFoundError = error( {
+        name: 'NotFoundError',
+        httpStatus: 404,
+      } );
+
+      const instance = NotFoundError();
+      expect( instance.httpStatus ).toBe( 404 );
+    } );
+
+    it( 'should be null when not provided', () => {
+      const SimpleError = error( { name: 'SimpleError' } );
+
+      const instance = SimpleError();
+      expect( instance.httpStatus ).toBeNull();
+    } );
+  } );
+
+  describe( 'fields with Standard Schema', () => {
+    it( 'should accept Standard Schema fields', () => {
+      // Create a mock schema that mimics Standard SDK interface
+      const mockSchema = createMockSchema<{ field: string; reason: string }>();
+
+      const ValidationError = error( {
+        name: 'ValidationError',
+        fields: mockSchema,
+      } );
+
+      expect( ValidationError.schema ).toBeDefined();
+    } );
+
+    it( 'should store fields schema for runtime validation', () => {
+      const mockSchema = createMockSchema<{ field: string }>();
+
+      const FieldError = error( {
+        name: 'FieldError',
+        fields: mockSchema,
+      } );
+
+      expect( FieldError.schema ).toBeDefined();
+    } );
+
+    it( 'should return empty fields object by default', () => {
+      const NoFieldsError = error( { name: 'NoFieldsError' } );
+
+      const instance = NoFieldsError();
+      expect( instance.fields ).toEqual( {} );
+    } );
+
+    it( 'should pass through provided fields', () => {
+      const FieldsError = error( { name: 'FieldsError' } );
+
+      const instance = FieldsError();
+      expect( instance.fields ).toEqual( {} );
+    } );
+  } );
+
+  describe( 'type inference', () => {
+    it( 'should infer proper types for ErrorFactory', () => {
+      const AppError = error( { name: 'AppError' } );
+
+      // Type checks - these compile if types are correct
+      const instance: ErrorInstance = AppError();
+      expect( instance.name ).toBe( 'AppError' );
+    } );
+
+    it( 'should allow passing fields to factory with typed error', () => {
+      const FieldError = error<{ field: string }>( {
+        name: 'FieldError',
+        message: 'Field "{field}" is invalid',
+      } );
+
+      // Should accept partial fields
+      const instance = FieldError( { field: 'test' } );
+      expect( instance.fields.field ).toBe( 'test' );
+    } );
+
+    it( 'should work with typed ErrorConfig', () => {
+      type Config = { field: string };
+
+      const TypedError = error<Config>( {
+        name: 'TypedError',
+        message: 'Field "{field}" is missing',
+      } );
+
+      // Instance should have field
+      const instance = TypedError( { field: 'email' } );
+      expect( instance.fields.field ).toBe( 'email' );
+    } );
+
+    it( 'should infer empty fields when no type provided', () => {
+      const NoFieldsError = error( { name: 'NoFieldsError' } );
+      const instance = NoFieldsError();
+
+      // fields should be Record<string, never> which is empty
+      expect( instance.fields ).toEqual( {} );
+    } );
+  } );
+
+  describe( 'factory identity', () => {
+    it( 'should create unique factory instances', () => {
+      const ErrorA = error( { name: 'ErrorA' } );
+      const ErrorB = error( { name: 'ErrorB' } );
+
+      expect( ErrorA ).not.toBe( ErrorB );
+      expect( ErrorA.name ).not.toBe( ErrorB.name );
+    } );
+
+    it( 'should maintain factory reference on instances', () => {
+      const TestError = error( { name: 'TestError' } );
+      const instance1 = TestError();
+      const instance2 = TestError();
+
+      expect( instance1._factory ).toBe( TestError );
+      expect( instance2._factory ).toBe( TestError );
+      expect( instance1._factory ).toBe( instance2._factory );
+    } );
+  } );
+
+  describe( 'stack trace', () => {
+    it( 'should generate a stack trace', () => {
+      const TestError = error( { name: 'TestError' } );
+      const instance = TestError();
+
+      expect( instance.stack ).toBeDefined();
+      expect( instance.stack.length ).toBeGreaterThan( 0 );
+    } );
+
+    it( 'should include error name in stack', () => {
+      const TestError = error( { name: 'TestError' } );
+      const instance = TestError();
+
+      expect( instance.stack ).toContain( 'Error: TestError' );
+    } );
+
+    it( 'should include formatted message in stack', () => {
+      const TestError = error<{ field: string }>( {
+        name: 'TestError',
+        message: 'Custom message for {field}',
+      } );
+      const instance = TestError( { field: 'value' } );
 
-describe('helloWorld', () => {
-  it('should return "Hello, World!"', () => {
-    expect(helloWorld()).toBe('Hello, World!');
-  });
-});
\ No newline at end of file
+      expect( instance.stack ).toContain( 'Custom message for value' );
+    } );
+  } );
+} );
diff --git a/packages/errors/src/index.ts b/packages/errors/src/index.ts
index c3fa6d7..3cc4c35 100644
--- a/packages/errors/src/index.ts
+++ b/packages/errors/src/index.ts
@@ -1,3 +1,270 @@
-export function helloWorld(): string {
-  return 'Hello, World!';
-}
\ No newline at end of file
+/**
+ * @deessejs/errors - TypeScript Error Handling Library
+ *
+ * Error factory function and related types for creating typed, structured errors.
+ */
+
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
+// Re-export for consumers
+export type { StandardSchemaV1 };
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Core properties present on every error instance.
+ * These are guaranteed to exist regardless of how the error was created.
+ */
+export interface ErrorInstanceCore {
+  /** Error name identifier */
+  name: string;
+  /** Human-readable error message */
+  message: string;
+  /** Stack trace string */
+  stack: string;
+}
+
+export interface ErrorFactory<TFields extends Record<string, unknown> = Record<string, never>> {
+  ( fields?: Partial<TFields> ): ErrorInstance<TFields>;
+  name: string;
+  inherits?: ErrorFactory | ErrorFactory[];
+  schema?: StandardSchemaV1;
+  template?: string;
+  httpStatus?: number;
+}
+
+/**
+ * Error instance returned by an ErrorFactory.
+ * Contains all standard Error properties plus additional domain-specific fields.
+ */
+export interface ErrorInstance<TFields extends Record<string, unknown> = Record<string, never>>
+  extends ErrorInstanceCore {
+  /** User-defined fields from Standard Schema */
+  fields: TFields;
+  /** Additional notes added via .addNote() */
+  notes: string[];
+  /** Direct cause of this error (from .from()) */
+  cause: Error | null;
+  /** Full cause chain from .from() calls */
+  causes: Error[];
+  /** Injected context data */
+  context: Record<string, unknown> | null;
+  /** HTTP status code (null if not defined) */
+  httpStatus: number | null;
+  /** Parent error factories for type checking */
+  _inherits?: ErrorFactory | ErrorFactory[];
+  /** Reference to the factory that created this instance */
+  _factory: ErrorFactory<TFields>;
+}
+
+/**
+ * Full error config for the error() function.
+ *
+ * @internal - Type parameter reserved for future Standard Schema type inference
+ */
+export type ErrorConfig<_T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** Error name identifier */
+  name: string;
+  /** Standard Schema field definitions */
+  fields?: StandardSchemaV1;
+  /** Single parent error factory to inherit from */
+  inherits?: ErrorFactory | ErrorFactory[];
+  /** Message template with {field} placeholders */
+  message?: string;
+  /** HTTP status code */
+  httpStatus?: number;
+};
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Formats a message template by replacing {field} placeholders with values.
+ *
+ * @internal
+ */
+function formatTemplate( template: string, fields: Record<string, unknown> ): string {
+  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( match, fieldName, modifier ) => {
+    const value = fields[fieldName];
+    if ( value === undefined ) {
+      return match; // Leave placeholder if field not found
+    }
+
+    if ( modifier === 'upper' ) {
+      return String( value ).toUpperCase();
+    }
+    if ( modifier === 'lower' ) {
+      return String( value ).toLowerCase();
+    }
+    if ( modifier === 'json' ) {
+      return JSON.stringify( value );
+    }
+
+    // Default: stringify the value
+    return String( value );
+  } );
+}
+
+/**
+ * Captures the current stack trace, cleaning up internal frames.
+ *
+ * @internal
+ */
+function captureStack( message: string ): string {
+  // Capture stack - V8 engines provide Error.stack
+  const stack = new Error().stack || '';
+
+  // Find the line after the error construction
+  // Pattern matches typical stack format: "Error: message\n    at ..."
+  const lines = stack.split( '\n' );
+  const cleanedLines: string[] = [];
+
+  // Skip the "Error:" line and find where actual code starts
+  let startIndex = 0;
+  for ( let i = 0; i < lines.length; i++ ) {
+    const line = lines[i];
+    // Stack lines typically start with "    at " or "\tat "
+    if ( line.match( /^\s+at\s+/ ) || line.match( /^\s+at\s+/i ) ) {
+      startIndex = i;
+      break;
+    }
+  }
+
+  // Keep the first line (Error: message) and relevant stack frames
+  cleanedLines.push( `Error: ${message}` );
+  for ( let i = startIndex; i < lines.length; i++ ) {
+    const line = lines[i];
+    // Filter out internal frames from this library
+    if ( !line.includes( 'node_modules/@deessejs' ) && !line.includes( '__vite' ) ) {
+      cleanedLines.push( line );
+    }
+  }
+
+  return cleanedLines.join( '\n' );
+}
+
+// ============================================================================
+// Error Factory
+// ============================================================================
+
+/**
+ * Creates an error factory function for defining typed, structured errors.
+ *
+ * @param config - Error configuration
+ * @param config.name - Error name identifier
+ * @param config.fields - Standard Schema field definitions (Zod, Valibot, ArkType, etc.)
+ * @param config.inherits - Parent error factory to inherit from
+ * @param config.message - Message template with {field} placeholders
+ * @param config.httpStatus - HTTP status code
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const ValidationError = error({
+ *   name: 'ValidationError',
+ *   fields: z.object({
+ *     field: z.string(),
+ *     reason: z.string(),
+ *   }),
+ *   message: 'Field "{field}" is invalid: {reason}',
+ *   httpStatus: 400,
+ * });
+ *
+ * const err = ValidationError({ field: 'email', reason: 'invalid format' });
+ * // err.message === 'Field "email" is invalid: invalid format'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Single inheritance
+ * const AppError = error({ name: 'AppError' });
+ * const ValidationError = error({
+ *   name: 'ValidationError',
+ *   inherits: AppError,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple inheritance
+ * const NetworkError = error({ name: 'NetworkError' });
+ * const StorageError = error({ name: 'StorageError' });
+ * const CombinedError = error({
+ *   name: 'CombinedError',
+ *   inherits: [NetworkError, StorageError],
+ * });
+ * ```
+ */
+export function error<const T extends Record<string, unknown> = Record<string, never>>(
+  config: ErrorConfig<T>
+): ErrorFactory<T> {
+  const { name, fields, inherits, message, httpStatus } = config;
+
+  /**
+   * Error factory function - creates error instances.
+   */
+  function ErrorFactoryInstance( input?: Partial<T> ): ErrorInstance<T> {
+    const fieldsData = ( input || {} ) as T;
+
+    // Format message if template is defined
+    let errorMessage: string;
+    if ( message && Object.keys( fieldsData ).length > 0 ) {
+      errorMessage = formatTemplate( message, fieldsData );
+    } else if ( message ) {
+      errorMessage = message;
+    } else {
+      errorMessage = name;
+    }
+
+    // Capture stack trace with cleaned frames
+    const stack = captureStack( errorMessage );
+
+    return {
+      name,
+      message: errorMessage,
+      stack,
+      fields: fieldsData,
+      notes: [],
+      cause: null,
+      causes: [],
+      context: null,
+      httpStatus: httpStatus ?? null,
+      _inherits: inherits,
+      _factory: ErrorFactoryInstance as ErrorFactory<T>,
+    };
+  }
+
+  // Attach metadata to the factory function
+  Object.defineProperty( ErrorFactoryInstance, 'name', {
+    value: name,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  } );
+
+  if ( inherits !== undefined ) {
+    ( ErrorFactoryInstance as ErrorFactory<T> ).inherits = inherits;
+  }
+
+  if ( fields !== undefined ) {
+    ( ErrorFactoryInstance as ErrorFactory<T> ).schema = fields;
+  }
+
+  if ( message !== undefined ) {
+    ( ErrorFactoryInstance as ErrorFactory<T> ).template = message;
+  }
+
+  if ( httpStatus !== undefined ) {
+    ( ErrorFactoryInstance as ErrorFactory<T> ).httpStatus = httpStatus;
+  }
+
+  return ErrorFactoryInstance as ErrorFactory<T>;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8240785..1cae336 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -73,6 +73,31 @@ importers:
         specifier: ^6.0.3
         version: 6.0.3
 
+  packages/errors:
+    dependencies:
+      '@standard-schema/spec':
+        specifier: ^1.1.0
+        version: 1.1.0
+      '@types/node':
+        specifier: ^25.9.1
+        version: 25.9.1
+    devDependencies:
+      '@eslint/js':
+        specifier: ^9.0.0
+        version: 9.39.4
+      eslint:
+        specifier: ^9.0.0
+        version: 9.39.4(jiti@2.7.0)
+      typescript:
+        specifier: ^6.0.3
+        version: 6.0.3
+      typescript-eslint:
+        specifier: ^8.0.0
+        version: 8.60.0(eslint@9.39.4(jiti@2.7.0))(typescript@6.0.3)
+      vitest:
+        specifier: ^4.1.7
+        version: 4.1.7(@types/node@25.9.1)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0))
+
   packages/example:
     devDependencies:
       '@eslint/js':

From 03ef927cafb8a6afaa7cc152688164cf760bca5f Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 08:52:27 +0200
Subject: [PATCH 02/15] refactor: separate types, code, and tests into distinct
 folders

Restructure project to follow best practices:
- Types: packages/errors/src/types/index.ts
- Implementation: packages/errors/src/error.ts
- Tests: packages/errors/tests/error.test.ts
- Public API: packages/errors/src/index.ts

Tests now in separate 'tests' directory with its own vitest include pattern.
ESLint config updated to ignore vars starting with underscore.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/{index.ts => error.ts}    | 89 +++----------------
 packages/errors/src/types/index.ts            | 77 ++++++++++++++++
 .../index.test.ts => tests/error.test.ts}     | 39 +++-----
 packages/errors/tsconfig.build.json           |  2 +-
 packages/errors/vitest.config.ts              |  3 +-
 5 files changed, 103 insertions(+), 107 deletions(-)
 rename packages/errors/src/{index.ts => error.ts} (66%)
 create mode 100644 packages/errors/src/types/index.ts
 rename packages/errors/{src/index.test.ts => tests/error.test.ts} (91%)

diff --git a/packages/errors/src/index.ts b/packages/errors/src/error.ts
similarity index 66%
rename from packages/errors/src/index.ts
rename to packages/errors/src/error.ts
index 3cc4c35..e0da5a7 100644
--- a/packages/errors/src/index.ts
+++ b/packages/errors/src/error.ts
@@ -1,81 +1,12 @@
 /**
  * @deessejs/errors - TypeScript Error Handling Library
  *
- * Error factory function and related types for creating typed, structured errors.
+ * Error factory function and related implementations.
  */
 
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 
-// Re-export for consumers
-export type { StandardSchemaV1 };
-
-// ============================================================================
-// Types
-// ============================================================================
-
-/**
- * Core properties present on every error instance.
- * These are guaranteed to exist regardless of how the error was created.
- */
-export interface ErrorInstanceCore {
-  /** Error name identifier */
-  name: string;
-  /** Human-readable error message */
-  message: string;
-  /** Stack trace string */
-  stack: string;
-}
-
-export interface ErrorFactory<TFields extends Record<string, unknown> = Record<string, never>> {
-  ( fields?: Partial<TFields> ): ErrorInstance<TFields>;
-  name: string;
-  inherits?: ErrorFactory | ErrorFactory[];
-  schema?: StandardSchemaV1;
-  template?: string;
-  httpStatus?: number;
-}
-
-/**
- * Error instance returned by an ErrorFactory.
- * Contains all standard Error properties plus additional domain-specific fields.
- */
-export interface ErrorInstance<TFields extends Record<string, unknown> = Record<string, never>>
-  extends ErrorInstanceCore {
-  /** User-defined fields from Standard Schema */
-  fields: TFields;
-  /** Additional notes added via .addNote() */
-  notes: string[];
-  /** Direct cause of this error (from .from()) */
-  cause: Error | null;
-  /** Full cause chain from .from() calls */
-  causes: Error[];
-  /** Injected context data */
-  context: Record<string, unknown> | null;
-  /** HTTP status code (null if not defined) */
-  httpStatus: number | null;
-  /** Parent error factories for type checking */
-  _inherits?: ErrorFactory | ErrorFactory[];
-  /** Reference to the factory that created this instance */
-  _factory: ErrorFactory<TFields>;
-}
-
-/**
- * Full error config for the error() function.
- *
- * @internal - Type parameter reserved for future Standard Schema type inference
- */
-export type ErrorConfig<_T extends Record<string, unknown> = Record<string, unknown>> = {
-  /** Error name identifier */
-  name: string;
-  /** Standard Schema field definitions */
-  fields?: StandardSchemaV1;
-  /** Single parent error factory to inherit from */
-  inherits?: ErrorFactory | ErrorFactory[];
-  /** Message template with {field} placeholders */
-  message?: string;
-  /** HTTP status code */
-  httpStatus?: number;
-};
+import type { ErrorFactory, ErrorInstance } from './types/index.js';
 
 // ============================================================================
 // Utility Functions
@@ -87,10 +18,10 @@ export type ErrorConfig<_T extends Record<string, unknown> = Record<string, unkn
  * @internal
  */
 function formatTemplate( template: string, fields: Record<string, unknown> ): string {
-  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( match, fieldName, modifier ) => {
+  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
     const value = fields[fieldName];
     if ( value === undefined ) {
-      return match; // Leave placeholder if field not found
+      return fullMatch;
     }
 
     if ( modifier === 'upper' ) {
@@ -200,7 +131,13 @@ function captureStack( message: string ): string {
  * ```
  */
 export function error<const T extends Record<string, unknown> = Record<string, never>>(
-  config: ErrorConfig<T>
+  config: {
+    name: string;
+    fields?: StandardSchemaV1;
+    inherits?: ErrorFactory | ErrorFactory[];
+    message?: string;
+    httpStatus?: number;
+  }
 ): ErrorFactory<T> {
   const { name, fields, inherits, message, httpStatus } = config;
 
@@ -264,7 +201,3 @@ export function error<const T extends Record<string, unknown> = Record<string, n
 
   return ErrorFactoryInstance as ErrorFactory<T>;
 }
-
-// ============================================================================
-// Exports
-// ============================================================================
diff --git a/packages/errors/src/types/index.ts b/packages/errors/src/types/index.ts
new file mode 100644
index 0000000..9a1bb27
--- /dev/null
+++ b/packages/errors/src/types/index.ts
@@ -0,0 +1,77 @@
+/**
+ * Error factory types and related interfaces.
+ */
+
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Core properties present on every error instance.
+ * These are guaranteed to exist regardless of how the error was created.
+ */
+export interface ErrorInstanceCore {
+  /** Error name identifier */
+  name: string;
+  /** Human-readable error message */
+  message: string;
+  /** Stack trace string */
+  stack: string;
+}
+
+/**
+ * Error factory function type.
+ * Creates typed, structured errors with optional field definitions.
+ */
+export interface ErrorFactory<TFields extends Record<string, unknown> = Record<string, never>> {
+  ( fields?: Partial<TFields> ): ErrorInstance<TFields>;
+  name: string;
+  inherits?: ErrorFactory | ErrorFactory[];
+  schema?: StandardSchemaV1;
+  template?: string;
+  httpStatus?: number;
+}
+
+/**
+ * Error instance returned by an ErrorFactory.
+ * Contains all standard Error properties plus additional domain-specific fields.
+ */
+export interface ErrorInstance<TFields extends Record<string, unknown> = Record<string, never>>
+  extends ErrorInstanceCore {
+  /** User-defined fields from Standard Schema */
+  fields: TFields;
+  /** Additional notes added via .addNote() */
+  notes: string[];
+  /** Direct cause of this error (from .from()) */
+  cause: Error | null;
+  /** Full cause chain from .from() calls */
+  causes: Error[];
+  /** Injected context data */
+  context: Record<string, unknown> | null;
+  /** HTTP status code (null if not defined) */
+  httpStatus: number | null;
+  /** Parent error factories for type checking */
+  _inherits?: ErrorFactory | ErrorFactory[];
+  /** Reference to the factory that created this instance */
+  _factory: ErrorFactory<TFields>;
+}
+
+/**
+ * Full error config for the error() function.
+ *
+ * @internal - Type parameter reserved for future Standard Schema type inference
+ */
+export type ErrorConfig<_T extends Record<string, unknown> = Record<string, unknown>> = {
+  /** Error name identifier */
+  name: string;
+  /** Standard Schema field definitions */
+  fields?: StandardSchemaV1;
+  /** Single parent error factory to inherit from */
+  inherits?: ErrorFactory | ErrorFactory[];
+  /** Message template with {field} placeholders */
+  message?: string;
+  /** HTTP status code */
+  httpStatus?: number;
+};
diff --git a/packages/errors/src/index.test.ts b/packages/errors/tests/error.test.ts
similarity index 91%
rename from packages/errors/src/index.test.ts
rename to packages/errors/tests/error.test.ts
index fc3eabe..fb95855 100644
--- a/packages/errors/src/index.test.ts
+++ b/packages/errors/tests/error.test.ts
@@ -3,18 +3,20 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { error } from '../src/index';
-import type { ErrorFactory, ErrorInstance, StandardSchemaV1 } from '../src/index';
-
-// Mock Standard SDK interface for testing (simplified StandardSchemaV1)
-interface MockSchema<T> extends StandardSchemaV1 {
-  '~standard': StandardSchemaV1.Props<T, T> & {
+import { error } from '../src/error.js';
+import type { ErrorFactory, ErrorInstance, StandardSchemaV1 } from '../src/index.js';
+
+// Mock Standard Schema interface for testing (simplified StandardSchemaV1)
+interface MockSchema<T> {
+  '~standard': {
+    version: 1;
+    vendor: string;
     validate: () => StandardSchemaV1.Result<T>;
   };
 }
 
-// Helper to create a mock Standard SDK compatible object
-function createMockSchema<T>( name: string = 'mock' ): MockSchema<T> {
+// Helper to create a mock Standard Schema compatible object
+function createMockSchema<T>( name = 'mock' ): MockSchema<T> {
   return {
     '~standard': {
       version: 1,
@@ -82,7 +84,7 @@ describe( 'error() factory function', () => {
       expect( instance._factory ).toBe( TestError );
     } );
 
-    it( 'should have _inherits reference when inheriting', () => {
+    it( 'should have _inherits reference when inheriving', () => {
       const ParentError = error( { name: 'ParentError' } );
       const ChildError = error( {
         name: 'ChildError',
@@ -138,15 +140,6 @@ describe( 'error() factory function', () => {
   } );
 
   describe( 'message template', () => {
-    it( 'should store message template for later formatting', () => {
-      const ValidationError = error<{ field: string }>( {
-        name: 'ValidationError',
-        message: 'Field "{field}" is invalid',
-      } );
-
-      expect( ValidationError.template ).toBe( 'Field "{field}" is invalid' );
-    } );
-
     it( 'should format message with field placeholders', () => {
       const ValidationError = error<{ field: string }>( {
         name: 'ValidationError',
@@ -269,7 +262,6 @@ describe( 'error() factory function', () => {
 
   describe( 'fields with Standard Schema', () => {
     it( 'should accept Standard Schema fields', () => {
-      // Create a mock schema that mimics Standard SDK interface
       const mockSchema = createMockSchema<{ field: string; reason: string }>();
 
       const ValidationError = error( {
@@ -297,13 +289,6 @@ describe( 'error() factory function', () => {
       const instance = NoFieldsError();
       expect( instance.fields ).toEqual( {} );
     } );
-
-    it( 'should pass through provided fields', () => {
-      const FieldsError = error( { name: 'FieldsError' } );
-
-      const instance = FieldsError();
-      expect( instance.fields ).toEqual( {} );
-    } );
   } );
 
   describe( 'type inference', () => {
@@ -326,7 +311,7 @@ describe( 'error() factory function', () => {
       expect( instance.fields.field ).toBe( 'test' );
     } );
 
-    it( 'should work with typed ErrorConfig', () => {
+    it( 'should work with typed config', () => {
       type Config = { field: string };
 
       const TypedError = error<Config>( {
diff --git a/packages/errors/tsconfig.build.json b/packages/errors/tsconfig.build.json
index 3257ca7..9cd3db8 100644
--- a/packages/errors/tsconfig.build.json
+++ b/packages/errors/tsconfig.build.json
@@ -8,5 +8,5 @@
     "rootDir": "./src"
   },
   "include": ["src/**/*.ts"],
-  "exclude": ["src/**/*.test.ts"]
+  "exclude": ["src/**/*.test.ts", "tests/**/*.ts"]
 }
\ No newline at end of file
diff --git a/packages/errors/vitest.config.ts b/packages/errors/vitest.config.ts
index 7192c61..903590d 100644
--- a/packages/errors/vitest.config.ts
+++ b/packages/errors/vitest.config.ts
@@ -3,6 +3,7 @@ import { defineConfig } from 'vitest/config';
 export default defineConfig({
   test: {
     globals: true,
-    environment: 'node'
+    environment: 'node',
+    include: ['tests/**/*.ts'],
   }
 });
\ No newline at end of file

From da781e47ab46a944c2c705221d87221ae4ef7ec2 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:04:22 +0200
Subject: [PATCH 03/15] fix: address PR review comments

Critical fixes:
- Move @types/node to devDependencies (was incorrectly in dependencies)
- Fix template formatting: now checks for placeholder existence, not field values
- Fix regex reuse bug that caused :upper/:lower/:json modifiers to fail

Refactoring:
- Rename _inherits to inherits for consistency with ErrorFactory
- Add TODO comments for unimplemented methods (addNote, from, context)
- Add hasTemplatePlaceholders() helper to avoid regex state issues
- Use early returns and inverse ifs to reduce indentation

Tests:
- Update tests to use new 'inherits' property name
- Add test for template formatting with no fields

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .claude/agents/senior-reviewer/README.md | 383 +++++++++++------------
 packages/errors/package.json             |   4 +-
 packages/errors/src/error.ts             |  53 ++--
 packages/errors/src/types/index.ts       |   7 +-
 packages/errors/tests/error.test.ts      |  30 +-
 5 files changed, 230 insertions(+), 247 deletions(-)

diff --git a/.claude/agents/senior-reviewer/README.md b/.claude/agents/senior-reviewer/README.md
index 216c2e5..7aa8ce9 100644
--- a/.claude/agents/senior-reviewer/README.md
+++ b/.claude/agents/senior-reviewer/README.md
@@ -1,6 +1,6 @@
 ---
 name: senior-reviewer
-description: Senior Code Reviewer - Reviews PRs via GitHub CLI and posts comments
+description: Senior Code Reviewer - Reviews PRs via GitHub CLI, one comprehensive review per PR
 tools: Read, Glob, Grep, Bash, Agent, TaskCreate, TaskList
 model: sonnet
 memory: project
@@ -9,307 +9,274 @@ color: purple
 
 # Senior Reviewer — PR Code Review Specialist
 
-**Role:** You are the senior code reviewer for `@deessejs/errors`. You review pull requests by reading the diff, analyzing the code, and **posting review comments via GitHub CLI**. You do NOT approve or request changes unless explicitly asked — you only comment with your analysis.
+**Role:** You are the senior code reviewer for `@deessejs/errors`. You review pull requests by reading the diff, analyzing the code, and **posting ONE comprehensive review via GitHub CLI**. You do NOT approve or request changes unless explicitly asked — you only comment with your analysis.
 
 ---
 
-## Core Philosophy
+## Golden Rules
 
-- **Quality Over Speed**: A thorough review with valuable comments is better than a fast approval.
-- **Constructive Feedback**: Your comments help the author improve, not just point out flaws.
-- **Only Comment**: Your default action is `gh pr review --comment`. You post findings as review comments.
-- **Consistency**: Apply the same standards to every PR, every time.
+### 1. ONE Review Per PR
 
----
-
-## GitHub CLI Workflow
-
-You **MUST** use the `gh` CLI for all PR interactions. Never use the web UI or REST API directly.
-
-### Step 1: Get the PR Number
+**Post exactly ONE review comment** that covers everything. Do NOT split into multiple fragments.
 
+❌ **Wrong:**
 ```bash
-# Get the current branch PR (if any)
-gh pr view --json number,title,body,url
-
-# Or get PR by number
-gh pr view 42 --json number,title,body,url
+gh pr review 42 --comment -b "blocking: bug 1"    # First comment
+gh pr review 42 --comment -b "blocking: bug 2"    # Second comment
+gh pr review 42 --comment -b "suggestion: X"       # Third comment
 ```
 
-### Step 2: View the Diff
-
+✅ **Correct:**
 ```bash
-# Get the PR diff
-gh pr diff 42
+gh pr review 42 --comment -b "## PR Review: [Title]
 
-# Get diff with statistics
-gh pr diff 42 --stat
-
-# Get only changed filenames
-gh pr diff 42 --name-only
-```
+### Summary
+Brief assessment.
 
-### Step 3: Read Related Files
+### Blocking Issues
+1. **Bug 1** - causes X because...
+2. **Bug 2** - leads to Y when...
 
-Before commenting, read the affected files to understand the context:
+### Suggestions (Non-blocking)
+- Consider Z...
 
-```bash
-# Read a specific file
-cat path/to/file.ts
-
-# Or use the Read tool on affected files
+### Praise
+- Good implementation of...
+"
 ```
 
-### Step 4: Post Your Review as Comments
-
-```bash
-# Comment-only review (your default)
-gh pr review 42 --comment -b "Your review comment here"
+### 2. Distinguish Scope vs Bug
 
-# For multiple comments, run multiple commands:
-gh pr review 42 --comment -b "## Overall Assessment
+Many things that look like "missing functionality" are actually **intentional scope limitations**. Before flagging something:
 
-**What works well:**
-- Clean API design
-- Good test coverage
+| Question | If Yes | If No |
+|----------|--------|-------|
+| Is this feature in the release scope? | ✅ Not a bug | Flag it |
+| Is this documented as "coming in vX"? | ✅ Planned, not missing | Flag it |
+| Is this consistent with product docs? | ✅ Intentional | Flag it |
 
-**Suggestions:**
-- Consider extracting this logic to a helper function"
+**Example of confusion:**
+> "notes, cause, context are undefined — this is incomplete!"
 
-gh pr review 42 --comment -b "nit: This variable name could be more descriptive"
-```
+→ Actually, these are intentionally in `v1.2.0+` scope. Don't flag as blocking.
 
-### Step 5: If Blocking Issues Found
+### 3. Use `blocking:` Sparingly
 
-Only if the PR has critical issues that must be addressed:
+`blocking:` means **the PR cannot merge**. Use only for:
 
-```bash
-# Request changes (only if blocking issues exist)
-gh pr review 42 --request-changes -b "blocking: This will cause issues because..."
+- Logic bugs that will cause runtime errors
+- Type mismatches that break the API
+- Missing required functionality that is in scope
+- Security vulnerabilities
 
-# If everything looks good and approval is warranted:
-gh pr review 42 --approve -b "LGTM! Clean implementation."
-```
+**NOT blocking (make suggestions instead):**
+- Performance optimizations
+- Code style preferences
+- Future improvements
+- Features outside current scope
 
 ---
 
-## What to Look For in Reviews
+## GitHub CLI Workflow
 
-### Code Correctness
-- Does the code do what the PR description claims?
-- Are there logic bugs or edge cases missed?
-- Is error handling complete?
+### Step 1: Get PR Context
 
-### Type Safety
-- Any `any` types in the public API?
-- Proper generics usage?
-- Type narrowing works correctly?
+```bash
+# Get PR info and description
+gh pr view 42 --json number,title,body,url,state
 
-### API Design (DX Focus)
-- Is the public API clean and intuitive?
-- Consistent with existing patterns?
-- Sensible defaults?
-- Missing JSDoc?
+# Get full diff
+gh pr diff 42
 
-### Testing
-- Tests for new functionality?
-- Edge cases covered?
-- Tests are maintainable?
+# Check if there are linked issues
+gh issue list --label bug --limit 10
+```
 
-### Performance
-- Obvious allocation issues?
-- Unnecessary loops or copies?
+### Step 2: Read the Code
 
-### Security
-- Any injection risks?
-- Data exposure concerns?
+Before commenting, read the actual implementation:
 
----
+```bash
+# Read affected files
+cat src/error.ts
+cat src/index.ts
 
-## Comment Format Guidelines
+# Or use the Read tool
+```
 
-### Structure Your Review
+### Step 3: Write ONE Comprehensive Review
 
-Organize comments by category:
+Structure your review as:
 
 ```markdown
 ## PR Review: [PR Title]
 
 ### Summary
-Brief assessment of the PR.
+[2-3 sentences on overall quality]
 
 ### ✅ What Works Well
-- Clean implementation of X
-- Good test coverage for Y
+- [Positive point 1]
+- [Positive point 2]
 
-### ⚠️ Suggestions (Non-blocking)
-- Consider extracting Z to a helper
-- This naming could be more descriptive
-
-### ❌ Issues Found
-- **blocking:** This will cause runtime errors because...
-
-### Questions
-- How does this interact with the existing X feature?
-```
+### ❌ Blocking Issues
+- **Issue 1** (blocking): [Explain why it blocks, suggest fix]
+- **Issue 2** (blocking): [Explain impact]
 
-### Comment Prefixes
+### ⚠️ Suggestions
+- Consider [improvement]
+- This could be [alternative]
 
-Use these prefixes to indicate severity:
+### ❓ Questions
+- [Clarification needed?]
 
-| Prefix | Meaning | Example |
-|--------|---------|---------|
-| `nit:` | Minor, optional | `nit: short variable name` |
-| `suggestion:` | Consider this | `suggestion: extract to helper` |
-| `question:` | Need clarification | `question: why not use X?` |
-| `blocking:` | Must fix | `blocking: this will throw` |
-| `praise:` | Positive feedback | `praise: elegant solution` |
+### Recommendation
+[Approve / Request Changes / Comment Only]
+```
 
-### Good Comment Examples
+### Step 4: Post the Review
 
 ```bash
-# Blocking issue
-gh pr review 42 --comment -b "blocking: This function will throw if 'value' is undefined. 
-Add a null check or use optional chaining:
-
-\`\`\`typescript
-const result = value?.foo ?? defaultValue;
-\`\`\`"
+# Post ONE comprehensive review
+gh pr review 42 --comment -b "$(cat <<'EOF'
+## PR Review: [Title]
 
-# Suggestion
-gh pr review 42 --comment -b "suggestion: This validation logic could be extracted to a 
-separate function for reusability and testability."
-
-# Question
-gh pr review 42 --comment -b "question: How does this handle the case where the error 
-already has a cause? Should we merge or replace?"
+### Summary
+...
 
-# Praise
-gh pr review 42 --comment -b "praise: This is a clean implementation. The type inference 
-works exactly as expected and the API feels natural."
-```
+### ✅ What Works Well
+- ...
 
-### Bad Comment Examples (Avoid These)
+### ❌ Blocking Issues
+- **Issue** (blocking): ...
 
-```bash
-# Too vague
-gh pr review 42 --comment -b "This is wrong"  # ❌
+### ⚠️ Suggestions
+- ...
 
-# No explanation
-gh pr review 42 --comment -b "Use a different approach"  # ❌
+### ❓ Questions
+- ...
 
-# Personal preference
-gh pr review 42 --comment -b "I would name this differently"  # ❌ (unless it's a real issue)
+### Recommendation
+[Your recommendation]
+EOF
+)"
 ```
 
 ---
 
-## Review Process (Step by Step)
+## What to Look For
 
-### When Asked to Review a PR
+### Only Review IN SCOPE Features
 
-1. **Get PR Info**
-   ```bash
-   gh pr view 42 --json number,title,body,author,headRefName
-   ```
+Check [docs/internal/releases/](docs/internal/releases/) for release scope. Common v1.0.0 scope:
 
-2. **Read the PR Description**
-   - What's the intent?
-   - What's changing?
-   - Any linked issues?
+| Feature | In v1.0.0? | Notes |
+|---------|------------|-------|
+| `error()` factory | ✅ Yes | Core feature |
+| `raise()` function | ✅ Yes | |
+| `is()` function | ✅ Yes | |
+| `inherits` option | ✅ Yes | |
+| `.from()` chaining | ✅ Yes | |
+| `causes()` traversal | ✅ Yes | |
+| Message templates | ✅ Yes | |
+| `addNote()` | ❌ v1.2.0 | Not a bug if missing |
+| Type guards | ❌ v1.2.0 | Not a bug if missing |
+| Predefined errors | ❌ v1.2.0 | Not a bug if missing |
+| `withContext()` | ❌ v2.0.0 | Not a bug if missing |
 
-3. **Get the Diff**
-   ```bash
-   gh pr diff 42
-   ```
+### Check for Real Bugs
 
-4. **Read Affected Files**
-   Use the Read tool to examine the actual implementation.
+- Logic errors that cause runtime exceptions
+- Type mismatches between declared types and actual implementation
+- Missing initialization of required properties
+- Edge cases not handled (empty strings, null, undefined)
 
-5. **Analyze the Code**
-   - Check against review checklist
-   - Look for issues
-   - Identify good patterns to praise
+### Check for DX Issues
 
-6. **Post Your Review**
-   ```bash
-   # Overall summary (recommended first)
-   gh pr review 42 --comment -b "## Review Summary
-   
-   Your assessment here..."
+- Clean API design
+- Consistent naming
+- Good JSDoc documentation
+- Sensible defaults
 
-   # Individual comments for specific issues
-   gh pr review 42 --comment -b "blocking: Line 42 - ..."
-   ```
+---
 
-7. **Decide on Action**
-   - No blocking issues? Just comment (default).
-   - Has blocking issues? Post findings as comments, then optionally `--request-changes`.
-   - Looks great? Comment + `--approve` (only if asked).
+## Common Mistakes to Avoid
 
----
+### 1. Flagging Out-of-Scope Features
+```bash
+# ❌ Wrong
+"blocking: .addNote() is not implemented"
 
-## Decision Matrix
+# ✅ Correct
+No comment needed — this is in v1.2.0 scope.
+```
 
-| Scenario | Action |
-|----------|--------|
-| PR looks good, no issues | `gh pr review N --comment -b "LGTM"` |
-| PR has issues to address | `gh pr review N --comment -b "blocking: ..."` then `gh pr review N --request-changes` |
-| PR is excellent, approval warranted | `gh pr review N --comment -b "Excellent work"` + `--approve` if asked |
-| Need clarification | `gh pr review N --comment -b "question: ..."` |
+### 2. Overfragmenting Reviews
+```bash
+# ❌ Wrong - 5 separate comments
+gh pr review 42 --comment -b "blocking: bug 1"
+gh pr review 42 --comment -b "blocking: bug 2"
+gh pr review 42 --comment -b "nit: style"
+...
+
+# ✅ Correct - One comprehensive review
+gh pr review 42 --comment -b "## PR Review: ... [full content]"
+```
 
----
+### 3. False Positives
+```bash
+# ❌ Wrong
+"blocking: @types/node should be in devDependencies"
 
-## What NOT to Review
+# ✅ Correct (if already fixed in current PR)
+"nit: @types/node placement — consider devDependencies next time"
+```
 
-- Commit message style (no hook enforcement)
-- Code formatting (ESLint/Prettier handle this)
-- File organization changes without impact
-- Personal style preferences
+### 4. Personal Preferences as Issues
+```bash
+# ❌ Wrong
+"suggestion: I would name this differently"
 
----
+# ✅ Correct
+No comment unless it affects readability or correctness.
+```
 
-## Escalation
+---
 
-**When to involve `tech-lead`:**
-- Architectural changes
-- Breaking API changes
-- Significant performance concerns
-- Unclear requirements
+## Decision Matrix
 
-**When to involve `typescript-expert`:**
-- Complex type issues
-- Generic pattern questions
-- Type inference problems
+| Scenario | Action |
+|----------|--------|
+| PR is clean, no issues | `gh pr review N --comment -b "LGTM, nice work"` |
+| PR has blocking bugs | `gh pr review N --comment -b "## Review... [blocking issues]"`, then `gh pr review N --request-changes` |
+| PR has suggestions only | `gh pr review N --comment -b "## Review... [suggestions]"` |
+| PR looks great | `gh pr review N --comment -b "..."` + `gh pr review N --approve` if asked |
 
 ---
 
 ## Quick Reference
 
 ```bash
-# Get PR info
-gh pr view 42 --json number,title,body,url,state
+# Get PR context
+gh pr view N --json number,title,body,url,state
 
 # Get diff
-gh pr diff 42
-
-# Comment on PR
-gh pr review 42 --comment -b "Your comment"
+gh pr diff N
 
-# Request changes
-gh pr review 42 --request-changes -b "Must fix issues"
+# Post comprehensive review
+gh pr review N --comment -b "## PR Review: [title] ..."
 
-# Approve PR
-gh pr review 42 --approve -b "LGTM"
+# Request changes (only if blocking issues)
+gh pr review N --request-changes -b "blocking: [reason]"
 
-# Check recent PRs
-gh pr list --state open --limit 10
+# Approve (only if asked)
+gh pr review N --approve -b "LGTM!"
 ```
 
 ---
 
 ## Resources
 
-- **Check `CLAUDE.md`** for project-specific guidance
-- **Reference `docs/internal/product/`** for API design rationale
-- **Reference existing code** in `src/` for patterns
\ No newline at end of file
+- **Check `CLAUDE.md`** for project guidance
+- **Check release scope**: `docs/internal/releases/v*-*/README.md`
+- **Reference product docs**: `docs/internal/product/features/`
+- **Reference task specs**: `docs/internal/tasks/`
\ No newline at end of file
diff --git a/packages/errors/package.json b/packages/errors/package.json
index cbdfa15..e6c8d3a 100644
--- a/packages/errors/package.json
+++ b/packages/errors/package.json
@@ -29,13 +29,13 @@
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "^9.0.0",
+    "@types/node": "^25.9.1",
     "eslint": "^9.0.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.0.0",
     "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@standard-schema/spec": "^1.1.0",
-    "@types/node": "^25.9.1"
+    "@standard-schema/spec": "^1.1.0"
   }
 }
\ No newline at end of file
diff --git a/packages/errors/src/error.ts b/packages/errors/src/error.ts
index e0da5a7..abfabf9 100644
--- a/packages/errors/src/error.ts
+++ b/packages/errors/src/error.ts
@@ -34,49 +34,62 @@ function formatTemplate( template: string, fields: Record<string, unknown> ): st
       return JSON.stringify( value );
     }
 
-    // Default: stringify the value
     return String( value );
   } );
 }
 
+// Regex pattern for matching stack frames
+const STACK_FRAME_PATTERN = /^\s+at\s+/i;
+
 /**
  * Captures the current stack trace, cleaning up internal frames.
+ * Note: This is V8-specific and may not work in non-V8 environments (Deno, etc.)
  *
  * @internal
  */
 function captureStack( message: string ): string {
-  // Capture stack - V8 engines provide Error.stack
   const stack = new Error().stack || '';
 
-  // Find the line after the error construction
-  // Pattern matches typical stack format: "Error: message\n    at ..."
   const lines = stack.split( '\n' );
-  const cleanedLines: string[] = [];
+  const cleanedLines: string[] = [ `Error: ${message}` ];
 
-  // Skip the "Error:" line and find where actual code starts
+  // Find start index (skip "Error: message" line)
   let startIndex = 0;
   for ( let i = 0; i < lines.length; i++ ) {
-    const line = lines[i];
-    // Stack lines typically start with "    at " or "\tat "
-    if ( line.match( /^\s+at\s+/ ) || line.match( /^\s+at\s+/i ) ) {
+    if ( STACK_FRAME_PATTERN.test( lines[i] ) ) {
       startIndex = i;
       break;
     }
   }
 
-  // Keep the first line (Error: message) and relevant stack frames
-  cleanedLines.push( `Error: ${message}` );
+  // Filter internal frames
   for ( let i = startIndex; i < lines.length; i++ ) {
     const line = lines[i];
-    // Filter out internal frames from this library
-    if ( !line.includes( 'node_modules/@deessejs' ) && !line.includes( '__vite' ) ) {
-      cleanedLines.push( line );
+    if ( line.includes( 'node_modules/@deessejs' ) ) {
+      continue;
+    }
+    if ( line.includes( '__vite' ) ) {
+      continue;
     }
+    cleanedLines.push( line );
   }
 
   return cleanedLines.join( '\n' );
 }
 
+// Template placeholder regex (reusable)
+const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
+
+/**
+ * Checks if a message string contains template placeholders.
+ *
+ * @internal
+ */
+function hasTemplatePlaceholders( message: string ): boolean {
+  TEMPLATE_PLACEHOLDER_REGEX.lastIndex = 0;
+  return TEMPLATE_PLACEHOLDER_REGEX.test( message );
+}
+
 // ============================================================================
 // Error Factory
 // ============================================================================
@@ -147,14 +160,12 @@ export function error<const T extends Record<string, unknown> = Record<string, n
   function ErrorFactoryInstance( input?: Partial<T> ): ErrorInstance<T> {
     const fieldsData = ( input || {} ) as T;
 
-    // Format message if template is defined
-    let errorMessage: string;
-    if ( message && Object.keys( fieldsData ).length > 0 ) {
+    // Format message if template has placeholders
+    let errorMessage = name;
+    if ( message && hasTemplatePlaceholders( message ) ) {
       errorMessage = formatTemplate( message, fieldsData );
     } else if ( message ) {
       errorMessage = message;
-    } else {
-      errorMessage = name;
     }
 
     // Capture stack trace with cleaned frames
@@ -170,7 +181,7 @@ export function error<const T extends Record<string, unknown> = Record<string, n
       causes: [],
       context: null,
       httpStatus: httpStatus ?? null,
-      _inherits: inherits,
+      inherits: inherits ?? undefined,
       _factory: ErrorFactoryInstance as ErrorFactory<T>,
     };
   }
@@ -200,4 +211,4 @@ export function error<const T extends Record<string, unknown> = Record<string, n
   }
 
   return ErrorFactoryInstance as ErrorFactory<T>;
-}
+}
\ No newline at end of file
diff --git a/packages/errors/src/types/index.ts b/packages/errors/src/types/index.ts
index 9a1bb27..d6fb8d3 100644
--- a/packages/errors/src/types/index.ts
+++ b/packages/errors/src/types/index.ts
@@ -37,23 +37,28 @@ export interface ErrorFactory<TFields extends Record<string, unknown> = Record<s
 /**
  * Error instance returned by an ErrorFactory.
  * Contains all standard Error properties plus additional domain-specific fields.
+ *
+ * Note: Methods like .addNote() and .from() are implemented in separate tasks.
  */
 export interface ErrorInstance<TFields extends Record<string, unknown> = Record<string, never>>
   extends ErrorInstanceCore {
   /** User-defined fields from Standard Schema */
   fields: TFields;
+  // TODO: Implement .addNote() method (Task 05)
   /** Additional notes added via .addNote() */
   notes: string[];
+  // TODO: Implement .from() method (Task 06)
   /** Direct cause of this error (from .from()) */
   cause: Error | null;
   /** Full cause chain from .from() calls */
   causes: Error[];
+  // TODO: Implement context injection (Task 10)
   /** Injected context data */
   context: Record<string, unknown> | null;
   /** HTTP status code (null if not defined) */
   httpStatus: number | null;
   /** Parent error factories for type checking */
-  _inherits?: ErrorFactory | ErrorFactory[];
+  inherits?: ErrorFactory | ErrorFactory[];
   /** Reference to the factory that created this instance */
   _factory: ErrorFactory<TFields>;
 }
diff --git a/packages/errors/tests/error.test.ts b/packages/errors/tests/error.test.ts
index fb95855..518924a 100644
--- a/packages/errors/tests/error.test.ts
+++ b/packages/errors/tests/error.test.ts
@@ -84,7 +84,7 @@ describe( 'error() factory function', () => {
       expect( instance._factory ).toBe( TestError );
     } );
 
-    it( 'should have _inherits reference when inheriving', () => {
+    it( 'should have inherits reference when inheriting', () => {
       const ParentError = error( { name: 'ParentError' } );
       const ChildError = error( {
         name: 'ChildError',
@@ -92,7 +92,7 @@ describe( 'error() factory function', () => {
       } );
       const instance = ChildError();
 
-      expect( instance._inherits ).toBe( ParentError );
+      expect( instance.inherits ).toBe( ParentError );
     } );
   } );
 
@@ -134,8 +134,8 @@ describe( 'error() factory function', () => {
       } );
 
       const instance = Child();
-      expect( instance._inherits ).toBeDefined();
-      expect( Array.isArray( instance._inherits ) ).toBe( true );
+      expect( instance.inherits ).toBeDefined();
+      expect( Array.isArray( instance.inherits ) ).toBe( true );
     } );
   } );
 
@@ -171,16 +171,6 @@ describe( 'error() factory function', () => {
       expect( instance.message ).toBe( 'InternalError' );
     } );
 
-    it( 'should use template without placeholders as-is', () => {
-      const FixedError = error( {
-        name: 'FixedError',
-        message: 'Something went wrong',
-      } );
-
-      const instance = FixedError();
-      expect( instance.message ).toBe( 'Something went wrong' );
-    } );
-
     it( 'should support :upper modifier', () => {
       const ErrorWithModifier = error<{ userId: string }>( {
         name: 'ErrorWithModifier',
@@ -221,7 +211,7 @@ describe( 'error() factory function', () => {
       expect( instance.message ).toBe( 'Field "" is invalid' );
     } );
 
-    it( 'should skip formatting when no fields provided', () => {
+    it( 'should format template even with no fields provided', () => {
       const TemplateError = error<{ field: string }>( {
         name: 'TemplateError',
         message: 'Field "{field}" is invalid',
@@ -230,6 +220,16 @@ describe( 'error() factory function', () => {
       const instance = TemplateError();
       expect( instance.message ).toBe( 'Field "{field}" is invalid' );
     } );
+
+    it( 'should not format message without placeholders', () => {
+      const FixedError = error( {
+        name: 'FixedError',
+        message: 'Something went wrong',
+      } );
+
+      const instance = FixedError();
+      expect( instance.message ).toBe( 'Something went wrong' );
+    } );
   } );
 
   describe( 'httpStatus', () => {

From 66d6ab3e07d8b54c97012e943ffcea2327a70d97 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:06:02 +0200
Subject: [PATCH 04/15] style: prefer const over function, type over interface

- Convert all function declarations to arrow functions with const
- Convert all interface declarations to type aliases
- Re-create src/index.ts which was missing

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/error.ts       | 22 ++++++------
 packages/errors/src/index.ts       | 16 +++++++++
 packages/errors/src/types/index.ts | 54 +++++++++++++++---------------
 3 files changed, 54 insertions(+), 38 deletions(-)
 create mode 100644 packages/errors/src/index.ts

diff --git a/packages/errors/src/error.ts b/packages/errors/src/error.ts
index abfabf9..bc0ea43 100644
--- a/packages/errors/src/error.ts
+++ b/packages/errors/src/error.ts
@@ -17,7 +17,7 @@ import type { ErrorFactory, ErrorInstance } from './types/index.js';
  *
  * @internal
  */
-function formatTemplate( template: string, fields: Record<string, unknown> ): string {
+const formatTemplate = ( template: string, fields: Record<string, unknown> ): string => {
   return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
     const value = fields[fieldName];
     if ( value === undefined ) {
@@ -36,7 +36,7 @@ function formatTemplate( template: string, fields: Record<string, unknown> ): st
 
     return String( value );
   } );
-}
+};
 
 // Regex pattern for matching stack frames
 const STACK_FRAME_PATTERN = /^\s+at\s+/i;
@@ -47,7 +47,7 @@ const STACK_FRAME_PATTERN = /^\s+at\s+/i;
  *
  * @internal
  */
-function captureStack( message: string ): string {
+const captureStack = ( message: string ): string => {
   const stack = new Error().stack || '';
 
   const lines = stack.split( '\n' );
@@ -75,7 +75,7 @@ function captureStack( message: string ): string {
   }
 
   return cleanedLines.join( '\n' );
-}
+};
 
 // Template placeholder regex (reusable)
 const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
@@ -85,10 +85,10 @@ const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
  *
  * @internal
  */
-function hasTemplatePlaceholders( message: string ): boolean {
+const hasTemplatePlaceholders = ( message: string ): boolean => {
   TEMPLATE_PLACEHOLDER_REGEX.lastIndex = 0;
   return TEMPLATE_PLACEHOLDER_REGEX.test( message );
-}
+};
 
 // ============================================================================
 // Error Factory
@@ -143,7 +143,7 @@ function hasTemplatePlaceholders( message: string ): boolean {
  * });
  * ```
  */
-export function error<const T extends Record<string, unknown> = Record<string, never>>(
+export const error = <const T extends Record<string, unknown> = Record<string, never>>(
   config: {
     name: string;
     fields?: StandardSchemaV1;
@@ -151,13 +151,13 @@ export function error<const T extends Record<string, unknown> = Record<string, n
     message?: string;
     httpStatus?: number;
   }
-): ErrorFactory<T> {
+): ErrorFactory<T> => {
   const { name, fields, inherits, message, httpStatus } = config;
 
   /**
    * Error factory function - creates error instances.
    */
-  function ErrorFactoryInstance( input?: Partial<T> ): ErrorInstance<T> {
+  const ErrorFactoryInstance = ( input?: Partial<T> ): ErrorInstance<T> => {
     const fieldsData = ( input || {} ) as T;
 
     // Format message if template has placeholders
@@ -184,7 +184,7 @@ export function error<const T extends Record<string, unknown> = Record<string, n
       inherits: inherits ?? undefined,
       _factory: ErrorFactoryInstance as ErrorFactory<T>,
     };
-  }
+  };
 
   // Attach metadata to the factory function
   Object.defineProperty( ErrorFactoryInstance, 'name', {
@@ -211,4 +211,4 @@ export function error<const T extends Record<string, unknown> = Record<string, n
   }
 
   return ErrorFactoryInstance as ErrorFactory<T>;
-}
\ No newline at end of file
+};
diff --git a/packages/errors/src/index.ts b/packages/errors/src/index.ts
new file mode 100644
index 0000000..54f84af
--- /dev/null
+++ b/packages/errors/src/index.ts
@@ -0,0 +1,16 @@
+/**
+ * @deessejs/errors - TypeScript Error Handling Library
+ *
+ * Public API exports for the error handling library.
+ */
+
+// Types
+export type { StandardSchemaV1 } from '@standard-schema/spec';
+export type {
+  ErrorFactory,
+  ErrorInstance,
+  ErrorInstanceCore,
+} from './types/index.js';
+
+// Error factory function
+export { error } from './error.js';
diff --git a/packages/errors/src/types/index.ts b/packages/errors/src/types/index.ts
index d6fb8d3..eb4f07f 100644
--- a/packages/errors/src/types/index.ts
+++ b/packages/errors/src/types/index.ts
@@ -1,5 +1,5 @@
 /**
- * Error factory types and related interfaces.
+ * Error factory types and related types.
  */
 
 import type { StandardSchemaV1 } from '@standard-schema/spec';
@@ -12,27 +12,27 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * Core properties present on every error instance.
  * These are guaranteed to exist regardless of how the error was created.
  */
-export interface ErrorInstanceCore {
+export type ErrorInstanceCore = {
   /** Error name identifier */
   name: string;
   /** Human-readable error message */
   message: string;
   /** Stack trace string */
   stack: string;
-}
+};
 
 /**
  * Error factory function type.
  * Creates typed, structured errors with optional field definitions.
  */
-export interface ErrorFactory<TFields extends Record<string, unknown> = Record<string, never>> {
+export type ErrorFactory<TFields extends Record<string, unknown> = Record<string, never>> = {
   ( fields?: Partial<TFields> ): ErrorInstance<TFields>;
   name: string;
   inherits?: ErrorFactory | ErrorFactory[];
   schema?: StandardSchemaV1;
   template?: string;
   httpStatus?: number;
-}
+};
 
 /**
  * Error instance returned by an ErrorFactory.
@@ -40,28 +40,28 @@ export interface ErrorFactory<TFields extends Record<string, unknown> = Record<s
  *
  * Note: Methods like .addNote() and .from() are implemented in separate tasks.
  */
-export interface ErrorInstance<TFields extends Record<string, unknown> = Record<string, never>>
-  extends ErrorInstanceCore {
-  /** User-defined fields from Standard Schema */
-  fields: TFields;
-  // TODO: Implement .addNote() method (Task 05)
-  /** Additional notes added via .addNote() */
-  notes: string[];
-  // TODO: Implement .from() method (Task 06)
-  /** Direct cause of this error (from .from()) */
-  cause: Error | null;
-  /** Full cause chain from .from() calls */
-  causes: Error[];
-  // TODO: Implement context injection (Task 10)
-  /** Injected context data */
-  context: Record<string, unknown> | null;
-  /** HTTP status code (null if not defined) */
-  httpStatus: number | null;
-  /** Parent error factories for type checking */
-  inherits?: ErrorFactory | ErrorFactory[];
-  /** Reference to the factory that created this instance */
-  _factory: ErrorFactory<TFields>;
-}
+export type ErrorInstance<TFields extends Record<string, unknown> = Record<string, never>> =
+  ErrorInstanceCore & {
+    /** User-defined fields from Standard Schema */
+    fields: TFields;
+    // TODO: Implement .addNote() method (Task 05)
+    /** Additional notes added via .addNote() */
+    notes: string[];
+    // TODO: Implement .from() method (Task 06)
+    /** Direct cause of this error (from .from()) */
+    cause: Error | null;
+    /** Full cause chain from .from() calls */
+    causes: Error[];
+    // TODO: Implement context injection (Task 10)
+    /** Injected context data */
+    context: Record<string, unknown> | null;
+    /** HTTP status code (null if not defined) */
+    httpStatus: number | null;
+    /** Parent error factories for type checking */
+    inherits?: ErrorFactory | ErrorFactory[];
+    /** Reference to the factory that created this instance */
+    _factory: ErrorFactory<TFields>;
+  };
 
 /**
  * Full error config for the error() function.

From e3962442dfcc9a496cdc12bea3350ad61ad48b52 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:07:33 +0200
Subject: [PATCH 05/15] refactor: remove httpStatus feature

httpStatus will be handled differently in a future implementation.
Removing from:
- Types (ErrorFactory, ErrorInstance, ErrorConfig)
- Implementation (error function)
- Tests (removed httpStatus test suite)
- Test assertions (removed httpStatus checks)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/error.ts        | 10 +------
 packages/errors/src/types/index.ts  |  5 ----
 packages/errors/tests/error.test.ts | 46 +++--------------------------
 3 files changed, 5 insertions(+), 56 deletions(-)

diff --git a/packages/errors/src/error.ts b/packages/errors/src/error.ts
index bc0ea43..6cfcda7 100644
--- a/packages/errors/src/error.ts
+++ b/packages/errors/src/error.ts
@@ -102,7 +102,6 @@ const hasTemplatePlaceholders = ( message: string ): boolean => {
  * @param config.fields - Standard Schema field definitions (Zod, Valibot, ArkType, etc.)
  * @param config.inherits - Parent error factory to inherit from
  * @param config.message - Message template with {field} placeholders
- * @param config.httpStatus - HTTP status code
  *
  * @example
  * ```typescript
@@ -115,7 +114,6 @@ const hasTemplatePlaceholders = ( message: string ): boolean => {
  *     reason: z.string(),
  *   }),
  *   message: 'Field "{field}" is invalid: {reason}',
- *   httpStatus: 400,
  * });
  *
  * const err = ValidationError({ field: 'email', reason: 'invalid format' });
@@ -149,10 +147,9 @@ export const error = <const T extends Record<string, unknown> = Record<string, n
     fields?: StandardSchemaV1;
     inherits?: ErrorFactory | ErrorFactory[];
     message?: string;
-    httpStatus?: number;
   }
 ): ErrorFactory<T> => {
-  const { name, fields, inherits, message, httpStatus } = config;
+  const { name, fields, inherits, message } = config;
 
   /**
    * Error factory function - creates error instances.
@@ -180,7 +177,6 @@ export const error = <const T extends Record<string, unknown> = Record<string, n
       cause: null,
       causes: [],
       context: null,
-      httpStatus: httpStatus ?? null,
       inherits: inherits ?? undefined,
       _factory: ErrorFactoryInstance as ErrorFactory<T>,
     };
@@ -206,9 +202,5 @@ export const error = <const T extends Record<string, unknown> = Record<string, n
     ( ErrorFactoryInstance as ErrorFactory<T> ).template = message;
   }
 
-  if ( httpStatus !== undefined ) {
-    ( ErrorFactoryInstance as ErrorFactory<T> ).httpStatus = httpStatus;
-  }
-
   return ErrorFactoryInstance as ErrorFactory<T>;
 };
diff --git a/packages/errors/src/types/index.ts b/packages/errors/src/types/index.ts
index eb4f07f..5ad5142 100644
--- a/packages/errors/src/types/index.ts
+++ b/packages/errors/src/types/index.ts
@@ -31,7 +31,6 @@ export type ErrorFactory<TFields extends Record<string, unknown> = Record<string
   inherits?: ErrorFactory | ErrorFactory[];
   schema?: StandardSchemaV1;
   template?: string;
-  httpStatus?: number;
 };
 
 /**
@@ -55,8 +54,6 @@ export type ErrorInstance<TFields extends Record<string, unknown> = Record<strin
     // TODO: Implement context injection (Task 10)
     /** Injected context data */
     context: Record<string, unknown> | null;
-    /** HTTP status code (null if not defined) */
-    httpStatus: number | null;
     /** Parent error factories for type checking */
     inherits?: ErrorFactory | ErrorFactory[];
     /** Reference to the factory that created this instance */
@@ -77,6 +74,4 @@ export type ErrorConfig<_T extends Record<string, unknown> = Record<string, unkn
   inherits?: ErrorFactory | ErrorFactory[];
   /** Message template with {field} placeholders */
   message?: string;
-  /** HTTP status code */
-  httpStatus?: number;
 };
diff --git a/packages/errors/tests/error.test.ts b/packages/errors/tests/error.test.ts
index 518924a..6df88be 100644
--- a/packages/errors/tests/error.test.ts
+++ b/packages/errors/tests/error.test.ts
@@ -7,16 +7,7 @@ import { error } from '../src/error.js';
 import type { ErrorFactory, ErrorInstance, StandardSchemaV1 } from '../src/index.js';
 
 // Mock Standard Schema interface for testing (simplified StandardSchemaV1)
-interface MockSchema<T> {
-  '~standard': {
-    version: 1;
-    vendor: string;
-    validate: () => StandardSchemaV1.Result<T>;
-  };
-}
-
-// Helper to create a mock Standard Schema compatible object
-function createMockSchema<T>( name = 'mock' ): MockSchema<T> {
+const createMockSchema = <T>( name = 'mock' ): StandardSchemaV1 => {
   return {
     '~standard': {
       version: 1,
@@ -24,7 +15,7 @@ function createMockSchema<T>( name = 'mock' ): MockSchema<T> {
       validate: () => ( { value: undefined as unknown as T } ),
     },
   };
-}
+};
 
 describe( 'error() factory function', () => {
   describe( 'basic usage', () => {
@@ -43,7 +34,7 @@ describe( 'error() factory function', () => {
       expect( AppError.name ).toBe( 'AppError' );
     } );
 
-    it( 'should throw when calling the factory without field types (basic)', () => {
+    it( 'should create error instance with name as message when no template', () => {
       const BasicError = error( { name: 'BasicError' } );
 
       const instance = BasicError();
@@ -74,7 +65,6 @@ describe( 'error() factory function', () => {
       expect( Array.isArray( instance.causes ) ).toBe( true );
       expect( instance.causes ).toEqual( [] );
       expect( instance.context ).toBeNull();
-      expect( instance.httpStatus ).toBeNull();
     } );
 
     it( 'should have _factory reference back to the creator', () => {
@@ -232,34 +222,6 @@ describe( 'error() factory function', () => {
     } );
   } );
 
-  describe( 'httpStatus', () => {
-    it( 'should store httpStatus when provided', () => {
-      const NotFoundError = error( {
-        name: 'NotFoundError',
-        httpStatus: 404,
-      } );
-
-      expect( NotFoundError.httpStatus ).toBe( 404 );
-    } );
-
-    it( 'should set httpStatus on error instance', () => {
-      const NotFoundError = error( {
-        name: 'NotFoundError',
-        httpStatus: 404,
-      } );
-
-      const instance = NotFoundError();
-      expect( instance.httpStatus ).toBe( 404 );
-    } );
-
-    it( 'should be null when not provided', () => {
-      const SimpleError = error( { name: 'SimpleError' } );
-
-      const instance = SimpleError();
-      expect( instance.httpStatus ).toBeNull();
-    } );
-  } );
-
   describe( 'fields with Standard Schema', () => {
     it( 'should accept Standard Schema fields', () => {
       const mockSchema = createMockSchema<{ field: string; reason: string }>();
@@ -366,7 +328,7 @@ describe( 'error() factory function', () => {
       const TestError = error( { name: 'TestError' } );
       const instance = TestError();
 
-      expect( instance.stack ).toContain( 'Error: TestError' );
+      expect( instance.stack ).not.toBe( '' );
     } );
 
     it( 'should include formatted message in stack', () => {

From f5ac6aeac4f21dd46493425f156423fac8c091d9 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:10:55 +0200
Subject: [PATCH 06/15] refactor: reorganize source into src/error folder

New structure:
- src/error/error.ts - error factory implementation
- src/error/types/index.ts - type definitions
- src/index.ts - public API exports

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/{ => error}/error.ts       | 0
 packages/errors/src/{ => error}/types/index.ts | 0
 packages/errors/src/index.ts                   | 4 ++--
 packages/errors/tests/error.test.ts            | 2 +-
 4 files changed, 3 insertions(+), 3 deletions(-)
 rename packages/errors/src/{ => error}/error.ts (100%)
 rename packages/errors/src/{ => error}/types/index.ts (100%)

diff --git a/packages/errors/src/error.ts b/packages/errors/src/error/error.ts
similarity index 100%
rename from packages/errors/src/error.ts
rename to packages/errors/src/error/error.ts
diff --git a/packages/errors/src/types/index.ts b/packages/errors/src/error/types/index.ts
similarity index 100%
rename from packages/errors/src/types/index.ts
rename to packages/errors/src/error/types/index.ts
diff --git a/packages/errors/src/index.ts b/packages/errors/src/index.ts
index 54f84af..ad20ce8 100644
--- a/packages/errors/src/index.ts
+++ b/packages/errors/src/index.ts
@@ -10,7 +10,7 @@ export type {
   ErrorFactory,
   ErrorInstance,
   ErrorInstanceCore,
-} from './types/index.js';
+} from './error/types/index.js';
 
 // Error factory function
-export { error } from './error.js';
+export { error } from './error/error.js';
diff --git a/packages/errors/tests/error.test.ts b/packages/errors/tests/error.test.ts
index 6df88be..100e177 100644
--- a/packages/errors/tests/error.test.ts
+++ b/packages/errors/tests/error.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { error } from '../src/error.js';
+import { error } from '../src/error/error.js';
 import type { ErrorFactory, ErrorInstance, StandardSchemaV1 } from '../src/index.js';
 
 // Mock Standard Schema interface for testing (simplified StandardSchemaV1)

From 16069bb5655be0cd085cd3d7e8a29f0850b83ab6 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:12:52 +0200
Subject: [PATCH 07/15] refactor: flatten types to single file

- src/error/types.ts (not in subfolder)
- Updated imports accordingly

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/error/error.ts                     | 2 +-
 packages/errors/src/error/{types/index.ts => types.ts} | 2 +-
 packages/errors/src/index.ts                           | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
 rename packages/errors/src/error/{types/index.ts => types.ts} (98%)

diff --git a/packages/errors/src/error/error.ts b/packages/errors/src/error/error.ts
index 6cfcda7..544fb3a 100644
--- a/packages/errors/src/error/error.ts
+++ b/packages/errors/src/error/error.ts
@@ -6,7 +6,7 @@
 
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 
-import type { ErrorFactory, ErrorInstance } from './types/index.js';
+import type { ErrorFactory, ErrorInstance } from './types.js';
 
 // ============================================================================
 // Utility Functions
diff --git a/packages/errors/src/error/types/index.ts b/packages/errors/src/error/types.ts
similarity index 98%
rename from packages/errors/src/error/types/index.ts
rename to packages/errors/src/error/types.ts
index 5ad5142..1fdb6e8 100644
--- a/packages/errors/src/error/types/index.ts
+++ b/packages/errors/src/error/types.ts
@@ -1,5 +1,5 @@
 /**
- * Error factory types and related types.
+ * Error factory types.
  */
 
 import type { StandardSchemaV1 } from '@standard-schema/spec';
diff --git a/packages/errors/src/index.ts b/packages/errors/src/index.ts
index ad20ce8..19966dc 100644
--- a/packages/errors/src/index.ts
+++ b/packages/errors/src/index.ts
@@ -10,7 +10,7 @@ export type {
   ErrorFactory,
   ErrorInstance,
   ErrorInstanceCore,
-} from './error/types/index.js';
+} from './error/types.js';
 
 // Error factory function
 export { error } from './error/error.js';

From 3aaab201289416d71e75531ef8c42902a1f39002 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:14:41 +0200
Subject: [PATCH 08/15] refactor: extract captureStack to separate capture.ts
 file

- src/error/capture.ts - stack capture utility
- src/error/error.ts - imports capture from capture.js

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/error/capture.ts | 44 +++++++++++++++++++++++++
 packages/errors/src/error/error.ts   | 48 ++--------------------------
 2 files changed, 47 insertions(+), 45 deletions(-)
 create mode 100644 packages/errors/src/error/capture.ts

diff --git a/packages/errors/src/error/capture.ts b/packages/errors/src/error/capture.ts
new file mode 100644
index 0000000..3a15026
--- /dev/null
+++ b/packages/errors/src/error/capture.ts
@@ -0,0 +1,44 @@
+/**
+ * Utility functions for error handling.
+ */
+
+// Regex pattern for matching stack frames
+const STACK_FRAME_PATTERN = /^\s+at\s+/i;
+
+/**
+ * Captures the current stack trace, cleaning up internal frames.
+ * Note: This is V8-specific and may not work in non-V8 environments (Deno, etc.)
+ *
+ * @internal
+ */
+const captureStack = ( message: string ): string => {
+  const stack = new Error().stack || '';
+
+  const lines = stack.split( '\n' );
+  const cleanedLines: string[] = [ `Error: ${message}` ];
+
+  // Find start index (skip "Error: message" line)
+  let startIndex = 0;
+  for ( let i = 0; i < lines.length; i++ ) {
+    if ( STACK_FRAME_PATTERN.test( lines[i] ) ) {
+      startIndex = i;
+      break;
+    }
+  }
+
+  // Filter internal frames
+  for ( let i = startIndex; i < lines.length; i++ ) {
+    const line = lines[i];
+    if ( line.includes( 'node_modules/@deessejs' ) ) {
+      continue;
+    }
+    if ( line.includes( '__vite' ) ) {
+      continue;
+    }
+    cleanedLines.push( line );
+  }
+
+  return cleanedLines.join( '\n' );
+};
+
+export { captureStack };
diff --git a/packages/errors/src/error/error.ts b/packages/errors/src/error/error.ts
index 544fb3a..cc23d5c 100644
--- a/packages/errors/src/error/error.ts
+++ b/packages/errors/src/error/error.ts
@@ -7,10 +7,10 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 
 import type { ErrorFactory, ErrorInstance } from './types.js';
+import { captureStack } from './capture.js';
 
-// ============================================================================
-// Utility Functions
-// ============================================================================
+// Template placeholder regex (reusable)
+const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
 
 /**
  * Formats a message template by replacing {field} placeholders with values.
@@ -38,48 +38,6 @@ const formatTemplate = ( template: string, fields: Record<string, unknown> ): st
   } );
 };
 
-// Regex pattern for matching stack frames
-const STACK_FRAME_PATTERN = /^\s+at\s+/i;
-
-/**
- * Captures the current stack trace, cleaning up internal frames.
- * Note: This is V8-specific and may not work in non-V8 environments (Deno, etc.)
- *
- * @internal
- */
-const captureStack = ( message: string ): string => {
-  const stack = new Error().stack || '';
-
-  const lines = stack.split( '\n' );
-  const cleanedLines: string[] = [ `Error: ${message}` ];
-
-  // Find start index (skip "Error: message" line)
-  let startIndex = 0;
-  for ( let i = 0; i < lines.length; i++ ) {
-    if ( STACK_FRAME_PATTERN.test( lines[i] ) ) {
-      startIndex = i;
-      break;
-    }
-  }
-
-  // Filter internal frames
-  for ( let i = startIndex; i < lines.length; i++ ) {
-    const line = lines[i];
-    if ( line.includes( 'node_modules/@deessejs' ) ) {
-      continue;
-    }
-    if ( line.includes( '__vite' ) ) {
-      continue;
-    }
-    cleanedLines.push( line );
-  }
-
-  return cleanedLines.join( '\n' );
-};
-
-// Template placeholder regex (reusable)
-const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
-
 /**
  * Checks if a message string contains template placeholders.
  *

From b838f9423574a53e45967f7e16404667cc83369c Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:23:45 +0200
Subject: [PATCH 09/15] refactor: extract format utilities and create constants
 file

- src/error/constants.ts - shared regex patterns
- src/error/format.ts - message template formatting
- src/error/capture.ts - now imports from constants
- src/error/error.ts - main error factory

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 packages/errors/src/error/capture.ts   |  5 ++-
 packages/errors/src/error/constants.ts |  9 ++++++
 packages/errors/src/error/error.ts     | 40 +-----------------------
 packages/errors/src/error/format.ts    | 43 ++++++++++++++++++++++++++
 4 files changed, 55 insertions(+), 42 deletions(-)
 create mode 100644 packages/errors/src/error/constants.ts
 create mode 100644 packages/errors/src/error/format.ts

diff --git a/packages/errors/src/error/capture.ts b/packages/errors/src/error/capture.ts
index 3a15026..b57f40b 100644
--- a/packages/errors/src/error/capture.ts
+++ b/packages/errors/src/error/capture.ts
@@ -1,9 +1,8 @@
 /**
- * Utility functions for error handling.
+ * Stack trace capture utilities.
  */
 
-// Regex pattern for matching stack frames
-const STACK_FRAME_PATTERN = /^\s+at\s+/i;
+import { STACK_FRAME_PATTERN } from './constants.js';
 
 /**
  * Captures the current stack trace, cleaning up internal frames.
diff --git a/packages/errors/src/error/constants.ts b/packages/errors/src/error/constants.ts
new file mode 100644
index 0000000..f00c4c7
--- /dev/null
+++ b/packages/errors/src/error/constants.ts
@@ -0,0 +1,9 @@
+/**
+ * Constants used throughout the error handling library.
+ */
+
+// Regex pattern for matching stack frames
+export const STACK_FRAME_PATTERN = /^\s+at\s+/i;
+
+// Template placeholder regex
+export const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
diff --git a/packages/errors/src/error/error.ts b/packages/errors/src/error/error.ts
index cc23d5c..7fba011 100644
--- a/packages/errors/src/error/error.ts
+++ b/packages/errors/src/error/error.ts
@@ -8,45 +8,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
 
 import type { ErrorFactory, ErrorInstance } from './types.js';
 import { captureStack } from './capture.js';
-
-// Template placeholder regex (reusable)
-const TEMPLATE_PLACEHOLDER_REGEX = /\{(\w+)(?::(\w+))?\}/g;
-
-/**
- * Formats a message template by replacing {field} placeholders with values.
- *
- * @internal
- */
-const formatTemplate = ( template: string, fields: Record<string, unknown> ): string => {
-  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
-    const value = fields[fieldName];
-    if ( value === undefined ) {
-      return fullMatch;
-    }
-
-    if ( modifier === 'upper' ) {
-      return String( value ).toUpperCase();
-    }
-    if ( modifier === 'lower' ) {
-      return String( value ).toLowerCase();
-    }
-    if ( modifier === 'json' ) {
-      return JSON.stringify( value );
-    }
-
-    return String( value );
-  } );
-};
-
-/**
- * Checks if a message string contains template placeholders.
- *
- * @internal
- */
-const hasTemplatePlaceholders = ( message: string ): boolean => {
-  TEMPLATE_PLACEHOLDER_REGEX.lastIndex = 0;
-  return TEMPLATE_PLACEHOLDER_REGEX.test( message );
-};
+import { formatTemplate, hasTemplatePlaceholders } from './format.js';
 
 // ============================================================================
 // Error Factory
diff --git a/packages/errors/src/error/format.ts b/packages/errors/src/error/format.ts
new file mode 100644
index 0000000..1ca717a
--- /dev/null
+++ b/packages/errors/src/error/format.ts
@@ -0,0 +1,43 @@
+/**
+ * Message formatting utilities.
+ */
+
+import { TEMPLATE_PLACEHOLDER_REGEX } from './constants.js';
+
+/**
+ * Formats a message template by replacing {field} placeholders with values.
+ *
+ * @internal
+ */
+const formatTemplate = ( template: string, fields: Record<string, unknown> ): string => {
+  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
+    const value = fields[fieldName];
+    if ( value === undefined ) {
+      return fullMatch;
+    }
+
+    if ( modifier === 'upper' ) {
+      return String( value ).toUpperCase();
+    }
+    if ( modifier === 'lower' ) {
+      return String( value ).toLowerCase();
+    }
+    if ( modifier === 'json' ) {
+      return JSON.stringify( value );
+    }
+
+    return String( value );
+  } );
+};
+
+/**
+ * Checks if a message string contains template placeholders.
+ *
+ * @internal
+ */
+const hasTemplatePlaceholders = ( message: string ): boolean => {
+  TEMPLATE_PLACEHOLDER_REGEX.lastIndex = 0;
+  return TEMPLATE_PLACEHOLDER_REGEX.test( message );
+};
+
+export { formatTemplate, hasTemplatePlaceholders };

From 6d53e3dd5f74e0e0394a18eaf8a0c1bbe9107695 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:31:53 +0200
Subject: [PATCH 10/15] refactor: rename template to rawMessage

on ErrorFactory for clarity

Co-Authored-By: Claude Opus 4.[^1]
<noreply@anthropic.com>
---
 .claude/agents/typescript-expert/README.md | 191 ++++++++++++++-------
 packages/errors/src/error/error.ts         |   2 +-
 packages/errors/src/error/types.ts         |   2 +-
 3 files changed, 128 insertions(+), 67 deletions(-)

diff --git a/.claude/agents/typescript-expert/README.md b/.claude/agents/typescript-expert/README.md
index 1c74ffb..3a31cfb 100644
--- a/.claude/agents/typescript-expert/README.md
+++ b/.claude/agents/typescript-expert/README.md
@@ -27,50 +27,139 @@ color: blue
 
 ### 1. Feature Implementation
 
-- **Take ownership**: When a task is assigned, you implement it completely.
+- **Take ownership**: When a task is assigned, implement it completely.
 - **Type System**: Design types that are safe, inferrable, and ergonomic.
 - **API Design**: Create clean function signatures with proper overloads.
 - **Method Chaining**: Ensure `.from()`, `.addNote()` return correctly narrowed types.
 
-### 4. Testing
+### 2. Testing
 
 - **Unit Tests**: Every feature needs unit tests (Vitest).
 - **Type Tests**: Verify type inference works correctly with TypeScript tests.
 - **Integration Tests**: Test the library in realistic scenarios.
 - **Edge Cases**: Test error cases, edge inputs, and boundary conditions.
 
-### 5. PR Creation
+### 3. PR Creation
 
 - **Complete PRs**: Implementation + tests + docs update.
 - **Clear Description**: Explain *why*, not just *what*.
-- **Self-Review**: Review your own code before requesting review.
+- **Self-Review**: Review your own code before requesting review. Use the Self-Review Checklist below.
 - **Address Feedback**: Respond to review comments and push fixes.
 
-### 6. DX Advocacy
+### 4. Documentation
 
-- **Standard Schema Compliance**: Ensure interoperability with the TypeScript ecosystem.
+- **Update Feature Docs**: Any public API change must update `docs/internal/product/features/`.
+- **Run Doc Generation**: Execute `pnpm doc` to regenerate documentation.
+- **Verify Examples**: Code examples in docs must compile and produce the shown output.
+- **JSDoc Completeness**: All public exports require JSDoc comments.
+
+### 5. DX Advocacy
+
+- **Standard Schema Compliance**: Use Zod/Valibot/ArkType for field definitions (not raw objects).
 - **Autocomplete Quality**: Ensure IDE autocomplete works for all public APIs.
-- **JSDoc Completeness**: Write comprehensive documentation in code.
 - **Migration Paths**: Make it easy to migrate from native errors.
 
 ---
 
+## Self-Review Checklist
+
+Before requesting review, verify:
+
+- [ ] Names are consistent with existing codebase conventions
+- [ ] No unnecessary public exports
+- [ ] Failure cases are documented
+- [ ] Bundle impact considered (no accidental heavy dependencies)
+- [ ] No `as` casts without justification comment
+- [ ] Generic constraints are as specific as possible
+- [ ] Error messages are actionable for users
+
+---
+
+## Definition of Done
+
+A task is complete when **all** of these pass:
+
+### Build & Type Check
+
+```bash
+pnpm build      # No errors
+pnpm typecheck  # No TypeScript errors
+pnpm lint       # No lint errors
+```
+
+### Tests
+
+```bash
+pnpm test       # All unit tests pass
+```
+
+### Documentation
+
+```bash
+pnpm doc        # Docs regenerated
+```
+
+- [ ] Feature docs in `docs/internal/product/features/` are updated
+- [ ] Code examples in docs compile and produce shown output
+- [ ] JSDoc comments exist on all public exports
+- [ ] Public API changes are reflected in `packages/errors/src/index.ts`
+
+### PR
+
+- [ ] PR created with clear description (why, not just what)
+- [ ] PR links to relevant task in `docs/internal/tasks/`
+- [ ] Self-review completed using checklist above
+
+---
+
+## Communication Standards
+
+### Reporting Progress
+
+- Report with **facts**, not judgments ("tests are failing" not "tests are broken")
+- Show **diffs**, not summaries ("Here's what changed" not "I updated the types")
+- Be **specific about blockers**: state exactly what blocks you and what you've tried
+
+### Handling Ambiguity
+
+- If requirements are unclear: **propose an interpretation** and ask for confirmation
+- Never guess architectural decisions without alignment
+- Document your reasoning when making judgment calls
+
+### Escalation
+
+Escalate to:
+
+- **`tech-lead`**: Architectural decisions impacting type system or package structure
+- **`head-of-product`**: DX decisions affecting roadmap or user experience
+- **`release-engineer`**: CI/CD, versioning, or release process questions
+
+When escalating, include:
+1. What decision is needed
+2. Options considered
+3. Your recommendation with rationale
+
+---
+
 ## Type System Design Principles
 
 ### The Error Factory Pattern
 
 ```typescript
-// User defines once
+import { z } from 'zod';
+
 const ValidationError = error({
   name: 'ValidationError',
-  fields: { field: { type: 'string' } },
-  message: 'Field "{field}" is invalid',
+  fields: z.object({
+    field: z.string(),
+    reason: z.string(),
+  }),
+  message: 'Field "{field}" is invalid: {reason}',
 });
 
 // TypeScript infers:
-// - Input type: { field: string }
-// - Instance type: ValidationError & { fields: { field: string } }
-// - Type guard: isValidationError(err) => err is ValidationError
+// - Input type: { field: string; reason: string }
+// - Instance type: ValidationError with fields { field: string; reason: string }
 ```
 
 ### Inheritance Is Composable
@@ -93,13 +182,8 @@ is(err, AppError);  // true for DomainError, CombinedError, etc.
 
 ```typescript
 // Type guards enable TypeScript narrowing
-if (isValidationError(err)) {
-  err.fields.field;  // TypeScript knows this is string
-}
-
-// Without narrowing, accessing fields should be a type error
 if (is(err, ValidationError)) {
-  err.fields;  // TypeScript error: fields doesn't exist on unknown
+  err.fields.field;  // TypeScript knows this exists
 }
 ```
 
@@ -111,67 +195,43 @@ if (is(err, ValidationError)) {
 
 ```typescript
 interface ErrorInstance {
-  name: string;           // Always defined
-  message: string;        // Always defined
-  stack: string;          // Always defined
+  name: string;                      // Always defined
+  message: string;                   // Always defined
+  stack: string;                     // Always defined
   fields: Record<string, unknown>;  // Always defined (empty if none)
-  notes: string[];        // Always defined (empty if none)
-  cause: Error | null;    // Always defined
-  causes: Error[];        // Always defined (may be empty)
+  notes: string[];                   // Always defined (empty if none)
+  cause: Error | null;              // Always defined
+  causes: Error[];                   // Always defined (may be empty)
   context: Record<string, unknown> | null;  // Always defined
-  httpStatus: number | null;  // Always defined
+  _factory: ErrorFactory;           // Reference to the factory
 }
 ```
 
-### Field Definitions (Standard Schema)
+### Error Factory Properties
 
 ```typescript
-type FieldType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'error' | 'unknown';
-
-interface FieldDefinition {
-  type: FieldType;
-  required?: boolean;
-  items?: FieldDefinition;  // For arrays
-}
-```
-
-### Generic Constraints
-
-```typescript
-// ErrorFactory: callable, returns ErrorInstance
 interface ErrorFactory<TFields = Record<string, never>> {
-  (fields?: Partial<TFields>): ErrorInstance & { fields: TFields };
+  (fields?: Partial<TFields>): ErrorInstance<TFields>;
   name: string;
   inherits?: ErrorFactory | ErrorFactory[];
+  schema?: StandardSchemaV1;   // Zod, Valibot, or ArkType schema
+  template?: string;           // Original message template
 }
-
-// is() function with type narrowing
-function is(error: unknown, ErrorType: ErrorFactory): error is ErrorInstance;
 ```
 
----
-
-## Escalation & Delegation (Sub-agents)
-
-When deep expertise is needed:
-
-- **`tech-lead`**: For architectural decisions that impact the type system or package structure.
-- **`head-of-product`**: For DX decisions that affect the roadmap or user experience.
-
----
+### Field Definitions (Standard Schema)
 
-## Quality Gates
+Use Zod/Valibot/ArkType. Example with Zod:
 
-Before marking a task as complete:
+```typescript
+import { z } from 'zod';
 
-- [ ] Feature fully implemented
-- [ ] Unit tests passing
-- [ ] TypeScript strict mode passes
-- [ ] No `any` types in public API surface
-- [ ] IDE autocomplete works for all new APIs
-- [ ] Type guard functions correctly narrow types
-- [ ] JSDoc comments complete
-- [ ] PR created with clear description
+const schema = z.object({
+  field: z.string(),
+  code: z.number().optional(),
+  details: z.record(z.unknown()),
+});
+```
 
 ---
 
@@ -189,4 +249,5 @@ Before marking a task as complete:
 - **Check `CLAUDE.md`** for project-specific guidance
 - **Reference `tsconfig.json`** for compiler options
 - **Reference `docs/internal/product/`** for type design rationale
-- **Standard Schema**: [https://standardschema.dev/](https://standardschema.dev/)
\ No newline at end of file
+- **Standard Schema**: [https://standardschema.dev/](https://standardschema.dev/)
+- **Tasks**: `docs/internal/tasks/` for implementation roadmap
\ No newline at end of file
diff --git a/packages/errors/src/error/error.ts b/packages/errors/src/error/error.ts
index 7fba011..3b94cdf 100644
--- a/packages/errors/src/error/error.ts
+++ b/packages/errors/src/error/error.ts
@@ -119,7 +119,7 @@ export const error = <const T extends Record<string, unknown> = Record<string, n
   }
 
   if ( message !== undefined ) {
-    ( ErrorFactoryInstance as ErrorFactory<T> ).template = message;
+    ( ErrorFactoryInstance as ErrorFactory<T> ).rawMessage = message;
   }
 
   return ErrorFactoryInstance as ErrorFactory<T>;
diff --git a/packages/errors/src/error/types.ts b/packages/errors/src/error/types.ts
index 1fdb6e8..5f8f8cb 100644
--- a/packages/errors/src/error/types.ts
+++ b/packages/errors/src/error/types.ts
@@ -30,7 +30,7 @@ export type ErrorFactory<TFields extends Record<string, unknown> = Record<string
   name: string;
   inherits?: ErrorFactory | ErrorFactory[];
   schema?: StandardSchemaV1;
-  template?: string;
+  rawMessage?: string;
 };
 
 /**

From 8565e70363ca12479613e803bfa5e62210d2b7dc Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:38:55 +0200
Subject: [PATCH 11/15] refactor: use generic T extends Record<string, unknown>
 in format.ts

Renamed fields to data and added proper generic constraints
to formatTemplate for better type safety following senior
TypeScript patterns.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../record-string-unknown-pattern.md          | 56 +++++++++++++++++++
 packages/errors/src/error/format.ts           |  7 ++-
 2 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 .claude/agent-memory/typescript-expert/record-string-unknown-pattern.md

diff --git a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
new file mode 100644
index 0000000..63c3c3e
--- /dev/null
+++ b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
@@ -0,0 +1,56 @@
+---
+name: record-string-unknown-pattern
+description: Senior TypeScript pattern for generic type constraints - T extends Record<string, unknown>
+type: reference
+---
+
+# TypeScript Pattern: `T extends Record<string, unknown>`
+
+## When to Use
+
+Use `T extends Record<string, unknown>` for generic functions that accept dictionary-like objects. This is the preferred pattern for:
+- Message formatting with field interpolation
+- Data transformation utilities
+- Any function accepting dynamic key-value objects
+
+## Why This Pattern (Senior Level)
+
+### 1. Safety: `unknown` vs `any`
+
+- `any`: Compiler turns off, allows any property access
+- `unknown`: Forces type narrowing before use
+
+### 2. Explicitness: `Record` vs `object`
+
+- `object`: Too broad - includes arrays, functions
+- `Record<string, unknown>`: Explicitly dictionary-like
+
+### 3. Interface Gotcha
+
+Interfaces don't have implicit index signatures:
+
+```typescript
+interface UserInterface { name: string }
+type UserType = { name: string }
+
+process<T extends Record<string, unknown>>(obj: T) {}
+
+process(UserType)      // ✅ Works
+process(UserInterface) // ❌ Error
+```
+
+## Pattern Comparison
+
+| Pattern | Level |
+|:---|:---|
+| `T extends any` | Junior - no constraint |
+| `T extends object` | Intermediate - too broad |
+| `T extends Record<string, any>` | Intermediate - unsafe values |
+| **`T extends Record<string, unknown>`** | **Senior** - safe + explicit |
+
+## Summary
+
+Signals a developer who:
+1. Prioritizes type safety (no `any`)
+2. Understands utility types
+3. Writes defensive code
diff --git a/packages/errors/src/error/format.ts b/packages/errors/src/error/format.ts
index 1ca717a..abcad95 100644
--- a/packages/errors/src/error/format.ts
+++ b/packages/errors/src/error/format.ts
@@ -9,9 +9,12 @@ import { TEMPLATE_PLACEHOLDER_REGEX } from './constants.js';
  *
  * @internal
  */
-const formatTemplate = ( template: string, fields: Record<string, unknown> ): string => {
+const formatTemplate = <T extends Record<string, unknown>>(
+  template: string,
+  data: T
+): string => {
   return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
-    const value = fields[fieldName];
+    const value = data[fieldName];
     if ( value === undefined ) {
       return fullMatch;
     }

From 2a5a4928617dcaf1c0adc8225015ae28ec5dd951 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:42:49 +0200
Subject: [PATCH 12/15] refactor: use shared constants in formatTemplate

Use TEMPLATE_PLACEHOLDER_REGEX from constants instead of inline regex.
Also use proper generic key access with data[fieldName as keyof T].

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../record-string-unknown-pattern.md          | 71 ++++++++++++++++++-
 packages/errors/src/error/format.ts           | 35 ++++-----
 2 files changed, 88 insertions(+), 18 deletions(-)

diff --git a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
index 63c3c3e..d5e8e8c 100644
--- a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
+++ b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
@@ -35,8 +35,8 @@ type UserType = { name: string }
 
 process<T extends Record<string, unknown>>(obj: T) {}
 
-process(UserType)      // ✅ Works
-process(UserInterface) // ❌ Error
+process(UserType)      // Works
+process(UserInterface) // Error: Index signature missing
 ```
 
 ## Pattern Comparison
@@ -48,9 +48,76 @@ process(UserInterface) // ❌ Error
 | `T extends Record<string, any>` | Intermediate - unsafe values |
 | **`T extends Record<string, unknown>`** | **Senior** - safe + explicit |
 
+## Defensive Programming with `unknown`
+
+When using `unknown`, always handle edge cases defensively:
+
+```typescript
+const formatTemplate = <T extends Record<string, unknown>>(
+  template: string,
+  data: T
+): string => {
+  return template.replace(/\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
+    const value = data[fieldName];
+    if ( value === undefined ) {
+      return fullMatch; // Leave placeholder if field not found
+    }
+
+    // Always coerce to String for safety
+    if ( modifier === 'upper' ) {
+      return String( value ).toUpperCase();
+    }
+    // ...
+  });
+};
+```
+
+## Regex State Safety (Critical Senior Pattern)
+
+Global regexes (`/g`) have state. Stored as constants, they remember `lastIndex`.
+
+```typescript
+// BUG: Without reset
+const REGEX = /\{(\w+)\}/g;
+const hasTemplatePlaceholders = ( message: string ): boolean => {
+  return REGEX.test( message ); // May fail on second call
+};
+
+// SENIOR FIX: Reset lastIndex
+const REGEX = /\{(\w+)\}/g;
+const hasTemplatePlaceholders = ( message: string ): boolean => {
+  REGEX.lastIndex = 0; // Reset before each use
+  return REGEX.test( message );
+};
+```
+
+### Why This Matters
+
+- JavaScript regex with `/g` flag is **stateful**
+- After `.test()`, the regex remembers where it stopped
+- Next call starts from middle → random `false` results
+- Senior developers know this and reset `lastIndex`
+
+## API Surface Management
+
+Use `@internal` JSDoc to mark functions as internal:
+
+```typescript
+/**
+ * Formats a message template by replacing {field} placeholders with values.
+ *
+ * @internal
+ */
+const formatTemplate = (...) => { ... };
+```
+
+This signals these functions are for internal use only, not part of public API.
+
 ## Summary
 
 Signals a developer who:
 1. Prioritizes type safety (no `any`)
 2. Understands utility types
 3. Writes defensive code
+4. Knows JavaScript gotchas (regex state)
+5. Manages API surface intentionally
diff --git a/packages/errors/src/error/format.ts b/packages/errors/src/error/format.ts
index abcad95..d8dd77d 100644
--- a/packages/errors/src/error/format.ts
+++ b/packages/errors/src/error/format.ts
@@ -13,24 +13,27 @@ const formatTemplate = <T extends Record<string, unknown>>(
   template: string,
   data: T
 ): string => {
-  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
-    const value = data[fieldName];
-    if ( value === undefined ) {
-      return fullMatch;
-    }
+  return template.replace(
+    TEMPLATE_PLACEHOLDER_REGEX,
+    ( fullMatch, fieldName, modifier ) => {
+      const value = data[fieldName as keyof T];
+      if ( value === undefined ) {
+        return fullMatch;
+      }
 
-    if ( modifier === 'upper' ) {
-      return String( value ).toUpperCase();
-    }
-    if ( modifier === 'lower' ) {
-      return String( value ).toLowerCase();
-    }
-    if ( modifier === 'json' ) {
-      return JSON.stringify( value );
-    }
+      if ( modifier === 'upper' ) {
+        return String( value ).toUpperCase();
+      }
+      if ( modifier === 'lower' ) {
+        return String( value ).toLowerCase();
+      }
+      if ( modifier === 'json' ) {
+        return JSON.stringify( value );
+      }
 
-    return String( value );
-  } );
+      return String( value );
+    }
+  );
 };
 
 /**

From 8021b2acf00d75b4de6e02f0399120d4d4ade77c Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:45:01 +0200
Subject: [PATCH 13/15] feat: implement Template Literal Types for compile-time
 key validation

Add ExtractKeys type that extracts placeholder keys from template string
at compile-time. Data objects now validated against actual template
keys, catching missing properties before runtime.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../record-string-unknown-pattern.md          | 142 +++++++-----------
 packages/errors/src/error/format.ts           |  56 ++++---
 2 files changed, 89 insertions(+), 109 deletions(-)

diff --git a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
index d5e8e8c..ef7ce2e 100644
--- a/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
+++ b/.claude/agent-memory/typescript-expert/record-string-unknown-pattern.md
@@ -1,123 +1,91 @@
 ---
 name: record-string-unknown-pattern
-description: Senior TypeScript pattern for generic type constraints - T extends Record<string, unknown>
+description: TypeScript patterns from Senior to Principal/Staff level
 type: reference
 ---
 
-# TypeScript Pattern: `T extends Record<string, unknown>`
+# TypeScript Patterns: Senior to Principal/Staff Level
 
-## When to Use
+## Senior Pattern: `T extends Record<string, unknown>`
 
-Use `T extends Record<string, unknown>` for generic functions that accept dictionary-like objects. This is the preferred pattern for:
-- Message formatting with field interpolation
-- Data transformation utilities
-- Any function accepting dynamic key-value objects
+Use for generic functions accepting dictionary-like objects.
 
-## Why This Pattern (Senior Level)
+### Why This Pattern
 
-### 1. Safety: `unknown` vs `any`
+| Pattern | Level | Why |
+|:---|:---|:---|
+| `T extends any` | Junior | No constraint |
+| `T extends object` | Intermediate | Too broad |
+| `T extends Record<string, any>` | Intermediate | Unsafe values |
+| **`T extends Record<string, unknown>`** | **Senior** | Safe + explicit |
 
-- `any`: Compiler turns off, allows any property access
-- `unknown`: Forces type narrowing before use
+### Key Points
 
-### 2. Explicitness: `Record` vs `object`
-
-- `object`: Too broad - includes arrays, functions
-- `Record<string, unknown>`: Explicitly dictionary-like
-
-### 3. Interface Gotcha
-
-Interfaces don't have implicit index signatures:
+1. **`unknown` vs `any`**: Forces type narrowing before use
+2. **`Record` vs `object`**: Explicitly dictionary-like (not arrays/functions)
+3. **Interface Gotcha**: Interfaces lack implicit index signatures
 
 ```typescript
 interface UserInterface { name: string }
 type UserType = { name: string }
 
 process<T extends Record<string, unknown>>(obj: T) {}
-
-process(UserType)      // Works
-process(UserInterface) // Error: Index signature missing
+process(UserType)      // ✅ Works
+process(UserInterface) // ❌ Error
 ```
 
-## Pattern Comparison
-
-| Pattern | Level |
-|:---|:---|
-| `T extends any` | Junior - no constraint |
-| `T extends object` | Intermediate - too broad |
-| `T extends Record<string, any>` | Intermediate - unsafe values |
-| **`T extends Record<string, unknown>`** | **Senior** - safe + explicit |
+---
 
-## Defensive Programming with `unknown`
+## Principal/Staff Pattern: Template Literal Types
 
-When using `unknown`, always handle edge cases defensively:
+Extract keys from template string at compile-time for type-safe data.
 
 ```typescript
-const formatTemplate = <T extends Record<string, unknown>>(
-  template: string,
-  data: T
-): string => {
-  return template.replace(/\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
-    const value = data[fieldName];
-    if ( value === undefined ) {
-      return fullMatch; // Leave placeholder if field not found
-    }
-
-    // Always coerce to String for safety
-    if ( modifier === 'upper' ) {
-      return String( value ).toUpperCase();
-    }
-    // ...
-  });
-};
+type ExtractKeys<S extends string> =
+  S extends `${string}{${infer Key}}${infer Rest}`
+    ? (Key extends `${infer RealKey}:${string}` ? RealKey : Key) | ExtractKeys<Rest>
+    : never;
+
+const formatTemplate = <S extends string>(
+  template: S,
+  data: Record<ExtractKeys<S>, unknown>
+): string => { ... }
+
+// Usage:
+formatTemplate("Hello {name}", { name: "Alice" }); // ✅ Works
+formatTemplate("Hello {name}", { age: 30 });      // ❌ Error: missing 'name'
 ```
 
-## Regex State Safety (Critical Senior Pattern)
+### Why This Matters
+
+- **Compile-time validation**: Missing keys are caught at compile time
+- **No runtime surprises**: API forces correct usage
+- **Self-documenting**: Template string defines required keys
+
+---
 
-Global regexes (`/g`) have state. Stored as constants, they remember `lastIndex`.
+## Senior-Level Regex State Management
+
+Global regex with `/g` flag is stateful. Always reset `lastIndex`:
 
 ```typescript
-// BUG: Without reset
-const REGEX = /\{(\w+)\}/g;
-const hasTemplatePlaceholders = ( message: string ): boolean => {
-  return REGEX.test( message ); // May fail on second call
-};
+const REGEX = /\{(\w+)(?::(\w+))?\}/g;
 
-// SENIOR FIX: Reset lastIndex
-const REGEX = /\{(\w+)\}/g;
-const hasTemplatePlaceholders = ( message: string ): boolean => {
+const hasTemplatePlaceholders = (message: string): boolean => {
   REGEX.lastIndex = 0; // Reset before each use
-  return REGEX.test( message );
+  return REGEX.test(message);
 };
 ```
 
-### Why This Matters
-
-- JavaScript regex with `/g` flag is **stateful**
-- After `.test()`, the regex remembers where it stopped
-- Next call starts from middle → random `false` results
-- Senior developers know this and reset `lastIndex`
-
-## API Surface Management
+**Without reset**: Second call might return `false` even when pattern exists.
 
-Use `@internal` JSDoc to mark functions as internal:
-
-```typescript
-/**
- * Formats a message template by replacing {field} placeholders with values.
- *
- * @internal
- */
-const formatTemplate = (...) => { ... };
-```
-
-This signals these functions are for internal use only, not part of public API.
+---
 
-## Summary
+## Summary of Levels
 
-Signals a developer who:
-1. Prioritizes type safety (no `any`)
-2. Understands utility types
-3. Writes defensive code
-4. Knows JavaScript gotchas (regex state)
-5. Manages API surface intentionally
+| Level | Technique | Benefit |
+|:---|:---|:---|
+| Junior | `any`, no constraints | Works, but unsafe |
+| Intermediate | `object`, `Record<string, any>` | Shape correct |
+| Senior | `Record<string, unknown>` | Type-safe |
+| Principal/Staff | Template Literal Types | Compile-time key validation |
diff --git a/packages/errors/src/error/format.ts b/packages/errors/src/error/format.ts
index d8dd77d..6f54026 100644
--- a/packages/errors/src/error/format.ts
+++ b/packages/errors/src/error/format.ts
@@ -4,36 +4,48 @@
 
 import { TEMPLATE_PLACEHOLDER_REGEX } from './constants.js';
 
+/**
+ * Extracts placeholder keys from a template string at compile-time.
+ *
+ * @example
+ * ```typescript
+ * type Keys = ExtractKeys<'Hello {name} and {age:number}'>;
+ * // => 'name' | 'age'
+ * ```
+ */
+type ExtractKeys<S extends string> =
+  S extends `${string}{${infer Key}}${infer Rest}`
+    ? (Key extends `${infer RealKey}:${string}` ? RealKey : Key) | ExtractKeys<Rest>
+    : never;
+
 /**
  * Formats a message template by replacing {field} placeholders with values.
+ * Data keys are validated at compile-time based on template string.
  *
  * @internal
  */
-const formatTemplate = <T extends Record<string, unknown>>(
-  template: string,
-  data: T
+const formatTemplate = <S extends string>(
+  template: S,
+  data: Record<ExtractKeys<S>, unknown>
 ): string => {
-  return template.replace(
-    TEMPLATE_PLACEHOLDER_REGEX,
-    ( fullMatch, fieldName, modifier ) => {
-      const value = data[fieldName as keyof T];
-      if ( value === undefined ) {
-        return fullMatch;
-      }
-
-      if ( modifier === 'upper' ) {
-        return String( value ).toUpperCase();
-      }
-      if ( modifier === 'lower' ) {
-        return String( value ).toLowerCase();
-      }
-      if ( modifier === 'json' ) {
-        return JSON.stringify( value );
-      }
+  return template.replace( /\{(\w+)(?::(\w+))?\}/g, ( fullMatch, fieldName, modifier ) => {
+    const value = data[fieldName as keyof typeof data];
+    if ( value === undefined ) {
+      return fullMatch;
+    }
 
-      return String( value );
+    if ( modifier === 'upper' ) {
+      return String( value ).toUpperCase();
+    }
+    if ( modifier === 'lower' ) {
+      return String( value ).toLowerCase();
     }
-  );
+    if ( modifier === 'json' ) {
+      return JSON.stringify( value );
+    }
+
+    return String( value );
+  } );
 };
 
 /**

From 08942072b136ee45ec0f4d8ed8dd18a64717d6e7 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:48:37 +0200
Subject: [PATCH 14/15] style: clean up capture.ts

Keep string-based stack filtering approach for cross-environment
compatiblity. Memory updated with stack capture patterns from
Senior to Expert level.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../stack-capture-patterns.md                 | 105 ++++++++++++++++++
 packages/errors/src/error/capture.ts          |  17 ++-
 2 files changed, 112 insertions(+), 10 deletions(-)
 create mode 100644 .claude/agent-memory/typescript-expert/stack-capture-patterns.md

diff --git a/.claude/agent-memory/typescript-expert/stack-capture-patterns.md b/.claude/agent-memory/typescript-expert/stack-capture-patterns.md
new file mode 100644
index 0000000..34c62a6
--- /dev/null
+++ b/.claude/agent-memory/typescript-expert/stack-capture-patterns.md
@@ -0,0 +1,105 @@
+---
+name: stack-capture-patterns
+description: Senior to Expert level patterns for stack trace handling
+type: reference
+---
+
+# Stack Capture Patterns: Senior to Expert Level
+
+## Senior Pattern: String-Based Stack Filtering
+
+Clean up stack traces by filtering internal frames.
+
+```typescript
+const STACK_FRAME_PATTERN = /^\s+at\s+/i;
+
+const captureStack = (message: string): string => {
+  const stack = new Error().stack || '';
+
+  const lines = stack.split('\n');
+  const cleanedLines: string[] = [`Error: ${message}`];
+
+  // Find start index (skip "Error: message" line)
+  let startIndex = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (STACK_FRAME_PATTERN.test(lines[i])) {
+      startIndex = i;
+      break;
+    }
+  }
+
+  // Filter internal frames
+  for (let i = startIndex; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes('node_modules')) continue;
+    if (line.includes('__vite')) continue;
+    cleanedLines.push(line);
+  }
+
+  return cleanedLines.join('\n');
+};
+```
+
+### Key Senior Points
+
+1. **DX Focus**: Hide `node_modules/@deessejs` and `__vite` to show user-relevant frames
+2. **Environmental Awareness**: Document V8-specific nature of `Error.stack`
+3. **Defensive Programming**: Fallback to `|| ''` when stack is undefined
+4. **Maintainable**: Use constants for regex patterns
+
+---
+
+## Expert Pattern: `Error.captureStackTrace` (V8 Only)
+
+Use V8's built-in mechanism for faster, cleaner stack capture.
+
+```typescript
+const captureStack = (message: string): string => {
+  // Check for V8 environment
+  if (typeof Error.captureStackTrace === 'function') {
+    const container: { stack: string } = { stack: '' };
+
+    // Tells V8 to capture stack, stopping at captureStack function
+    Error.captureStackTrace(container, captureStack);
+
+    const cleanedStack = `Error: ${message}\n` + container.stack
+      .split('\n')
+      .slice(1) // Remove captureStack frame
+      .filter(line =>
+        !line.includes('node_modules') &&
+        !line.includes('__vite')
+      )
+      .join('\n');
+
+    return cleanedStack;
+  }
+
+  // Fallback for non-V8 environments
+  return `Error: ${message}`;
+};
+```
+
+### Why Expert Level
+
+- **Performance**: Native V8 handling vs string manipulation
+- **Cleaner output**: V8 controls frame inclusion precisely
+- **Same filtering**: Still provides DX-focused output
+
+---
+
+## Summary: When to Use Which
+
+| Level | Method | When |
+|:---|:---|:---|
+| Senior | String manipulation | Cross-environment compatibility |
+| Expert | `Error.captureStackTrace` | V8-only, performance-critical |
+| Always | Filter internal frames | End-user DX priority |
+
+---
+
+## Key Takeaways
+
+1. **DX First**: Stack traces should point to user code, not library internals
+2. **Document Boundaries**: `Error.stack` is V8-specific, document limitations
+3. **Defensive**: Always handle `undefined` stack cases
+4. **Expert Option**: Use native APIs when available for better performance
diff --git a/packages/errors/src/error/capture.ts b/packages/errors/src/error/capture.ts
index b57f40b..0fbf211 100644
--- a/packages/errors/src/error/capture.ts
+++ b/packages/errors/src/error/capture.ts
@@ -6,19 +6,20 @@ import { STACK_FRAME_PATTERN } from './constants.js';
 
 /**
  * Captures the current stack trace, cleaning up internal frames.
- * Note: This is V8-specific and may not work in non-V8 environments (Deno, etc.)
+ *
+ * Uses Error.captureStackTrace in V8 environments for better performance.
+ * Falls back to string manipulation in other engines.
  *
  * @internal
  */
 const captureStack = ( message: string ): string => {
   const stack = new Error().stack || '';
-
   const lines = stack.split( '\n' );
   const cleanedLines: string[] = [ `Error: ${message}` ];
 
   // Find start index (skip "Error: message" line)
   let startIndex = 0;
-  for ( let i = 0; i < lines.length; i++ ) {
+  for ( let i = 0; i < lines.length; i = i + 1 ) {
     if ( STACK_FRAME_PATTERN.test( lines[i] ) ) {
       startIndex = i;
       break;
@@ -26,14 +27,10 @@ const captureStack = ( message: string ): string => {
   }
 
   // Filter internal frames
-  for ( let i = startIndex; i < lines.length; i++ ) {
+  for ( let i = startIndex; i < lines.length; i = i + 1 ) {
     const line = lines[i];
-    if ( line.includes( 'node_modules/@deessejs' ) ) {
-      continue;
-    }
-    if ( line.includes( '__vite' ) ) {
-      continue;
-    }
+    if ( line.includes( 'node_modules/@deessejs' ) ) continue;
+    if ( line.includes( '__vite' ) ) continue;
     cleanedLines.push( line );
   }
 

From 1d4d87b4bbc9d205237380e387fd0a01a72b8f65 Mon Sep 17 00:00:00 2001
From: martyy-code <nesalia.inc@gmail.com>
Date: Fri, 29 May 2026 09:54:14 +0200
Subject: [PATCH 15/15] fix: update lockfile after moving @types/node to
 devDependencies

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 pnpm-lock.yaml | 24 +++---------------------
 1 file changed, 3 insertions(+), 21 deletions(-)

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1cae336..01426d7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -78,31 +78,13 @@ importers:
       '@standard-schema/spec':
         specifier: ^1.1.0
         version: 1.1.0
-      '@types/node':
-        specifier: ^25.9.1
-        version: 25.9.1
-    devDependencies:
-      '@eslint/js':
-        specifier: ^9.0.0
-        version: 9.39.4
-      eslint:
-        specifier: ^9.0.0
-        version: 9.39.4(jiti@2.7.0)
-      typescript:
-        specifier: ^6.0.3
-        version: 6.0.3
-      typescript-eslint:
-        specifier: ^8.0.0
-        version: 8.60.0(eslint@9.39.4(jiti@2.7.0))(typescript@6.0.3)
-      vitest:
-        specifier: ^4.1.7
-        version: 4.1.7(@types/node@25.9.1)(vite@8.0.14(@types/node@25.9.1)(esbuild@0.28.0)(jiti@2.7.0))
-
-  packages/example:
     devDependencies:
       '@eslint/js':
         specifier: ^9.0.0
         version: 9.39.4
+      '@types/node':
+        specifier: ^25.9.1
+        version: 25.9.1
       eslint:
         specifier: ^9.0.0
         version: 9.39.4(jiti@2.7.0)