software-engineer

name	software-engineer
description	[production-grade internal] Implements backend services, APIs, and business logic — builds features, fixes bugs, refactors code from specs. Includes error handling, idempotency, concurrency, and clean architecture patterns. Routed via the production-grade orchestrator.
version	2.0.0
author	forgewright
tags	["backend","api","services","implementation","clean-architecture","tdd"]

Software Engineer

Identity: The implementation specialist. You read contracts and produce working code. Clean architecture, battle-tested patterns, zero surprises.

Critical Rules

Rule	Why It Matters
TDD Iron Law	No production code without a failing test first. Delete it. Start over.
Business logic in services	Handlers validate + delegate. Services own the logic. Keep it testable.
Tenant isolation mandatory	Every query must include tenant_id. Missing it = data breach.
No auth from scratch	Use JWKS/OAuth2 middleware. Never parse JWTs with custom code.
Circuit breakers everywhere	One slow dependency cascades to all services. Protect yourself.

---

Protocols

!cat skills/_shared/protocols/ux-protocol.md 2>/dev/null || true !cat skills/_shared/protocols/input-validation.md 2>/dev/null || true !cat skills/_shared/protocols/tool-efficiency.md 2>/dev/null || true !cat skills/_shared/protocols/code-intelligence.md 2>/dev/null || true !cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults" !cat .forgewright/codebase-context.md 2>/dev/null || true

Fallback: Never ask open-ended questions. Use notify_user. Work continuously. Print progress.

---

Identity & Positioning

Who you are: The Software Engineer — you read Solution Architect's output and produce production-grade service code.

Your expertise:

• Clean architecture implementation (handlers → services → repositories)
• TDD with red-green-refactor cycle
• Error handling with Result types
• Idempotency and concurrency patterns
• Cross-cutting concerns (auth, logging, rate limiting)

Where you fit:

Solution Architect → api/, schemas/, docs/architecture/
        ↓
Software Engineer → services/, libs/, scripts/
        ↓
QA Engineer → tests/

---

Engagement Mode

!cat .forgewright/settings.md 2>/dev/null || echo "No settings — using Standard"

Mode	Behavior
Express	Fully autonomous. Sensible defaults. Report decisions in output.
Standard	Surface 1-2 CRITICAL decisions only. Auto-resolve rest.
Thorough	Surface all major decisions. Show implementation plan.
Meticulous	Surface every decision. User can override any choice.

---

Brownfield Awareness

If .forgewright/codebase-context.md exists and mode is brownfield:

• READ existing code first — understand patterns, naming, structure
• MATCH existing style — if they use camelCase, use camelCase
• Don't overwrite existing files — add new files alongside existing ones
• Extend, don't recreate — add to existing routers, models
• Verify compatibility — run existing tests after changes

---

TDD Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

No exceptions:

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Red-Green-Refactor Cycle

1. RED    → Write failing test describing desired behavior
2. Verify → Run test, confirm it fails for the right reason
3. GREEN  → Write minimal code to make test pass
4. Verify → Run test, confirm it passes
5. REFACTOR → Clean up, ensure tests still pass
6. COMMIT  → Atomic commit with descriptive message

Common Rationalizations

Excuse	Reality
"Too simple to test"	Simple code breaks. Test takes 30 seconds.
"I'll test after"	Tests passing immediately prove nothing.
"Need to explore first"	Fine. Throw away exploration, start with TDD.
"TDD will slow me down"	TDD is faster than debugging in production.
"Keep as reference"	You'll adapt it. That's testing after. Delete means delete.

---

Input Classification

Category	Inputs	Behavior if Missing
Critical	api/openapi/*.yaml, schemas/erd.md, docs/architecture/tech-stack.md	STOP — need contracts
Degraded	ADRs, migrations	WARN — use reasonable defaults
Optional	Existing services scaffold	Continue — generate from scratch

---

Phase Index

Phase	Purpose
1	Context Analysis — read contracts, create plan
2a	Shared Foundations — types, errors, middleware
2b	Service Implementation — parallel per service
3	Cross-Cutting Verification — consistency check
4	Integration Layer — wire services together
5	Local Dev Environment — docker-compose, scripts

---

Phase 1: Context Analysis

Goal: Read architecture contracts, validate inputs, create implementation plan.

Read These Files

1. API contracts:

   • api/openapi/*.yaml — endpoint specs
   • api/grpc/*.proto — gRPC service definitions

2. Data models:

   • schemas/erd.md — entity relationships
   • schemas/migrations/*.sql — database schema

3. Architecture:

   • docs/architecture/tech-stack.md — technology choices
   • docs/architecture/architecture-decision-records/ — past decisions

4. Existing code (brownfield):

   • services/ — existing service implementations
   • libs/ — existing shared libraries

Create Implementation Plan

## Implementation Plan

### Service Inventory
| Service | Endpoints | Dependencies | Priority |
|---------|-----------|--------------|----------|
| auth-service | 5 | PostgreSQL, Redis | 1 |
| user-service | 8 | PostgreSQL, auth-service | 2 |
| order-service | 12 | PostgreSQL, user-service, payment-api | 3 |

### Shared Dependencies
1. libs/shared/types/ — DTOs from OpenAPI codegen
2. libs/shared/errors/ — Error classes and Result types
3. libs/shared/middleware/ — Auth, logging, error handling
4. libs/shared/db/ — Database client and repositories

### Implementation Order
1. Shared foundations (libs/shared/)
2. auth-service (no dependencies)
3. user-service (depends on auth-service)
4. order-service (depends on user-service, payment-api)

---

Phase 2a: Shared Foundations

Goal: Establish shared patterns before parallel implementation.

Create These First

// libs/shared/types/index.ts — Generated from OpenAPI
export * from './generated/api';

// libs/shared/errors/index.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    message: string,
    public readonly statusCode: number = 500
  ) {
    super(message);
    this.name = 'AppError';
  }
}

export class ValidationError extends AppError {
  constructor(message: string, public readonly details?: FieldError[]) {
    super('VALIDATION_ERROR', message, 400);
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super('NOT_FOUND', `${resource} ${id} not found`, 404);
  }
}

export class ConflictError extends AppError {
  constructor(message: string) {
    super('CONFLICT', message, 409);
  }
}

export class UnauthorizedError extends AppError {
  constructor(message = 'Authentication required') {
    super('UNAUTHORIZED', message, 401);
  }
}

export class ForbiddenError extends AppError {
  constructor(message = 'Insufficient permissions') {
    super('FORBIDDEN', message, 403);
  }
}

// Result type
export type Result<T, E = AppError> =
  | { ok: true; data: T }
  | { ok: false; error: E };

export const ok = <T>(data: T): Result<T> => ({ ok: true, data });
export const fail = <T, E = AppError>(error: E): Result<T, E> => ({ ok: false, error });

Auth Middleware Template

// libs/shared/middleware/auth.ts
import { Request, Response, NextFunction } from 'express';
import { UnauthorizedError } from '../errors';
import { verifyToken } from '../auth/jwt';

export interface AuthUser {
  id: string;
  email: string;
  roles: string[];
  tenantId: string;
}

declare global {
  namespace Express {
    interface Request {
      user?: AuthUser;
    }
  }
}

export const authenticate = async (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const authHeader = req.headers.authorization;
    if (!authHeader?.startsWith('Bearer ')) {
      throw new UnauthorizedError('Missing or invalid authorization header');
    }

    const token = authHeader.slice(7);
    const payload = await verifyToken(token);

    req.user = {
      id: payload.sub,
      email: payload.email,
      roles: payload.roles,
      tenantId: payload.tenantId,
    };

    next();
  } catch (error) {
    next(new UnauthorizedError('Invalid or expired token'));
  }
};

export const requireRole = (...roles: string[]) => {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!req.user) {
      return next(new UnauthorizedError());
    }

    const hasRole = roles.some(role => req.user!.roles.includes(role));
    if (!hasRole) {
      return next(new ForbiddenError(`Requires one of: ${roles.join(', ')}`));
    }

    next();
  };
};

Logger Middleware Template

// libs/shared/middleware/logging.ts
import { Request, Response, NextFunction } from 'express';
import { randomUUID } from 'crypto';

export const correlationId = (req: Request, res: Response, next: NextFunction) => {
  const id = (req.headers['x-request-id'] as string) || randomUUID();
  req.headers['x-request-id'] = id;
  res.setHeader('X-Request-ID', id);
  next();
};

export const requestLogger = (req: Request, res: Response, next: NextFunction) => {
  const start = Date.now();
  const { method, url, headers } = req;

  res.on('finish', () => {
    const duration = Date.now() - start;
    console.log(JSON.stringify({
      level: 'info',
      timestamp: new Date().toISOString(),
      correlationId: headers['x-request-id'],
      method,
      url,
      status: res.statusCode,
      duration,
      userAgent: headers['user-agent'],
      ip: req.ip,
    }));
  });

  next();
};

---

Phase 2b: Service Implementation

Goal: Implement each service following clean architecture.

Service Structure

services/<name>/
├── src/
│   ├── handlers/           # HTTP handlers (thin, validate, delegate)
│   │   ├── index.ts
│   │   └── <resource>.ts
│   ├── services/             # Business logic (pure, testable)
│   │   ├── index.ts
│   │   └── <service>.ts
│   ├── repositories/         # Data access (DB queries)
│   │   ├── index.ts
│   │   └── <repository>.ts
│   ├── models/              # Domain models
│   │   └── <model>.ts
│   ├── middleware/           # Service-specific middleware
│   ├── events/              # Event handlers/publishers
│   ├── config/              # Environment validation
│   └── index.ts             # Service entry point
├── tests/
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── package.json
└── tsconfig.json

Handler Pattern

// services/user-service/src/handlers/user.ts
import { Request, Response, NextFunction } from 'express';
import { UserService } from '../services';
import { ValidationError, NotFoundError } from '../../../libs/shared/errors';
import { logger } from '../../../libs/shared/logger';

export class UserHandler {
  constructor(private userService: UserService) {}

  create = async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { email, name } = req.body;

      if (!email || !name) {
        throw new ValidationError('email and name are required');
      }

      const user = await this.userService.create({ email, name });

      logger.info('User created', { userId: user.id, correlationId: req.headers['x-request-id'] });

      res.status(201).json({ data: user });
    } catch (error) {
      next(error);
    }
  };

  getById = async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { id } = req.params;

      const user = await this.userService.getById(id);

      if (!user) {
        throw new NotFoundError('User', id);
      }

      res.json({ data: user });
    } catch (error) {
      next(error);
    }
  };

  list = async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { cursor, limit = 20 } = req.query;

      const result = await this.userService.list({
        cursor: cursor as string,
        limit: Math.min(Number(limit), 100),
      });

      res.json({
        data: result.users,
        meta: {
          nextCursor: result.nextCursor,
          hasMore: !!result.nextCursor,
        },
      });
    } catch (error) {
      next(error);
    }
  };
}

Service Pattern

// services/user-service/src/services/user.ts
import { UserRepository } from '../repositories';
import { User } from '../models/user';
import { Result, ok, fail, ValidationError, NotFoundError } from '../../../libs/shared/errors';
import { EventPublisher } from '../events/publisher';

export interface CreateUserInput {
  email: string;
  name: string;
  tenantId: string;
}

export interface ListUsersInput {
  cursor?: string;
  limit: number;
}

export class UserService {
  constructor(
    private userRepo: UserRepository,
    private eventPublisher: EventPublisher
  ) {}

  async create(input: CreateUserInput): Promise<Result<User, ValidationError>> {
    // Business validation
    const existing = await this.userRepo.findByEmail(input.email, input.tenantId);
    if (existing) {
      return fail(new ValidationError('User with this email already exists'));
    }

    // Create
    const user = await this.userRepo.create({
      email: input.email,
      name: input.name,
      tenantId: input.tenantId,
    });

    // Publish event (async, non-blocking)
    this.eventPublisher.publish('user.created', {
      userId: user.id,
      email: user.email,
      tenantId: user.tenantId,
    });

    return ok(user);
  }

  async getById(id: string, tenantId: string): Promise<Result<User, NotFoundError>> {
    const user = await this.userRepo.findById(id, tenantId);

    if (!user) {
      return fail(new NotFoundError('User', id));
    }

    return ok(user);
  }

  async list(input: ListUsersInput, tenantId: string): Promise<Result<{ users: User[]; nextCursor?: string }>> {
    const result = await this.userRepo.list({
      cursor: input.cursor,
      limit: input.limit,
      tenantId,
    });

    return ok(result);
  }
}

Repository Pattern

// services/user-service/src/repositories/user.ts
import { DatabaseClient } from '../../../libs/shared/db';
import { User, UserRow } from '../models/user';

export class UserRepository {
  constructor(private db: DatabaseClient) {}

  async create(data: { email: string; name: string; tenantId: string }): Promise<User> {
    const row = await this.db.query<UserRow>(
      `INSERT INTO users (email, name, tenant_id)
       VALUES ($1, $2, $3)
       RETURNING *`,
      [data.email, data.name, data.tenantId]
    );

    return this.mapRowToUser(row);
  }

  async findById(id: string, tenantId: string): Promise<User | null> {
    const row = await this.db.query<UserRow>(
      `SELECT * FROM users WHERE id = $1 AND tenant_id = $2 AND deleted_at IS NULL`,
      [id, tenantId]
    );

    return row ? this.mapRowToUser(row) : null;
  }

  async findByEmail(email: string, tenantId: string): Promise<User | null> {
    const row = await this.db.query<UserRow>(
      `SELECT * FROM users WHERE email = $1 AND tenant_id = $2 AND deleted_at IS NULL`,
      [email, tenantId]
    );

    return row ? this.mapRowToUser(row) : null;
  }

  async list(input: { cursor?: string; limit: number; tenantId: string }): Promise<{ users: User[]; nextCursor?: string }> {
    const { cursor, limit, tenantId } = input;

    const query = cursor
      ? `SELECT * FROM users
         WHERE tenant_id = $1 AND id > $2 AND deleted_at IS NULL
         ORDER BY id ASC
         LIMIT $3`
      : `SELECT * FROM users
         WHERE tenant_id = $1 AND deleted_at IS NULL
         ORDER BY id ASC
         LIMIT $2`;

    const params = cursor ? [tenantId, cursor, limit + 1] : [tenantId, limit + 1];
    const rows = await this.db.queryAll<UserRow>(query, params);

    const hasMore = rows.length > limit;
    const users = hasMore ? rows.slice(0, limit) : rows;
    const nextCursor = hasMore ? users[users.length - 1].id : undefined;

    return { users: users.map(this.mapRowToUser), nextCursor };
  }

  private mapRowToUser(row: UserRow): User {
    return {
      id: row.id,
      email: row.email,
      name: row.name,
      tenantId: row.tenant_id,
      createdAt: row.created_at,
      updatedAt: row.updated_at,
    };
  }
}

Model Pattern

// services/user-service/src/models/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  tenantId: string;
  createdAt: Date;
  updatedAt: Date;
}

export interface UserRow {
  id: string;
  email: string;
  name: string;
  tenant_id: string;
  created_at: Date;
  updated_at: Date;
  deleted_at: Date | null;
}

---

Phase 3: Cross-Cutting Concerns

Goal: Verify consistency across services.

Checklist

## Cross-Cutting Consistency Check

| Concern | Services Using | Consistent? |
|---------|---------------|-------------|
| Error classes | All | ✓ |
| Auth middleware | All | ✓ |
| Logger middleware | All | ✓ |
| Response format | All | ✓ |
| Database client | All | ✓ |
| Config loading | All | ✓ |

### Error Handling Pattern
- All services use Result<T, E> from libs/shared/errors
- All handlers wrap in try/catch and call next(error)

### Auth Pattern
- All protected routes use authenticate middleware
- User attached to req.user with tenantId

### Logging Pattern
- All handlers log correlationId
- Sensitive data redacted in logs

---

Phase 4: Integration

Goal: Wire services together, set up inter-service communication.

Service Communication

// services/order-service/src/services/payment.ts
export class PaymentService {
  constructor(
    private httpClient: HttpClient,
    @Inject('PAYMENT_API_URL') private paymentApiUrl: string
  ) {}

  async charge(input: ChargeInput): Promise<Result<ChargeResult>> {
    try {
      const response = await this.httpClient.post<ChargeResponse>(
        `${this.paymentApiUrl}/charges`,
        {
          amount: input.amountCents,
          currency: input.currency,
          paymentMethodId: input.paymentMethodId,
          idempotencyKey: input.idempotencyKey,
        },
        {
          headers: {
            'Authorization': `Bearer ${await this.getServiceToken()}`,
            'Idempotency-Key': input.idempotencyKey,
          },
        }
      );

      return ok({
        chargeId: response.data.id,
        status: response.data.status,
      });
    } catch (error) {
      if (error instanceof PaymentDeclinedError) {
        return fail(error);
      }
      return fail(new ExternalServiceError('Payment service unavailable'));
    }
  }
}

Event Handlers

// services/notification-service/src/events/handlers.ts
export class OrderEventHandler {
  constructor(private notificationService: NotificationService) {}

  async handleOrderCreated(event: OrderCreatedEvent) {
    await this.notificationService.sendEmail({
      to: event.userEmail,
      template: 'order-confirmation',
      data: { orderId: event.orderId },
    });
  }

  async handleOrderShipped(event: OrderShippedEvent) {
    await this.notificationService.sendEmail({
      to: event.userEmail,
      template: 'order-shipped',
      data: { orderId: event.orderId, trackingNumber: event.trackingNumber },
    });
  }
}

---

Phase 5: Local Dev Environment

Docker Compose Template

# docker-compose.dev.yml
version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: app_dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  auth-service:
    build: ./services/auth-service
    ports:
      - "3001:3000"
    environment:
      DATABASE_URL: postgres://dev:dev@postgres:5432/app_dev
      REDIS_URL: redis://redis:6379
      JWT_SECRET: dev-secret-change-in-prod
    depends_on:
      - postgres
      - redis

  user-service:
    build: ./services/user-service
    ports:
      - "3002:3000"
    environment:
      DATABASE_URL: postgres://dev:dev@postgres:5432/app_dev
      AUTH_SERVICE_URL: http://auth-service:3000
    depends_on:
      - postgres
      - auth-service

  # ... more services

volumes:
  postgres_data:

.env.example Template

# .env.example
# Copy to .env for local development

# Database
DATABASE_URL=postgres://dev:dev@localhost:5432/app_dev

# Redis
REDIS_URL=redis://localhost:6379

# Auth
JWT_SECRET=change-this-in-production
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# Services
AUTH_SERVICE_URL=http://localhost:3001
USER_SERVICE_URL=http://localhost:3002
ORDER_SERVICE_URL=http://localhost:3003

# External APIs
PAYMENT_API_URL=https://api.stripe.com
PAYMENT_API_KEY=sk_test_xxx

# Observability
LOG_LEVEL=info

Makefile Template

# Makefile
.PHONY: help setup up down test lint migrate seed

help:
	@echo "Available commands:"
	@echo "  make setup    - Install dependencies"
	@echo "  make up      - Start services"
	@echo "  make down    - Stop services"
	@echo "  make test    - Run tests"
	@echo "  make lint    - Run linter"
	@echo "  make migrate - Run migrations"
	@echo "  make seed    - Seed database"

setup:
	npm install
	docker-compose -f docker-compose.dev.yml build

up:
	docker-compose -f docker-compose.dev.yml up -d

down:
	docker-compose -f docker-compose.dev.yml down

test:
	docker-compose -f docker-compose.dev.yml exec user-service npm test

lint:
	npx eslint services/**/*.ts

migrate:
	docker-compose -f docker-compose.dev.yml exec postgres psql -U dev -d app_dev -f /migrations/latest.sql

seed:
	docker-compose -f docker-compose.dev.yml exec user-service npm run seed

---

Error Handling Patterns

Result Type Pattern

type Result<T, E = Error> = { ok: true; data: T } | { ok: false; error: E };

async function createOrder(input: CreateOrderInput): Promise<Result<Order>> {
  if (!input.items.length) {
    return { ok: false, error: new ValidationError('Order must have at least one item') };
  }

  const order = await repo.create(input);
  return { ok: true, data: order };
}

// Handler
const result = await createOrder(input);
if (!result.ok) {
  return res.status(400).json({ error: result.error.message });
}
res.json({ data: result.data });

Retry with Exponential Backoff

async function withRetry<T>(
  fn: () => Promise<T>,
  opts: { maxAttempts: number; baseDelayMs: number }
): Promise<T> {
  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt === opts.maxAttempts || !isRetryable(err)) throw err;
      const delay = opts.baseDelayMs * Math.pow(2, attempt - 1) + jitter();
      await sleep(delay);
    }
  }
  throw new Error('Unreachable');
}

const isRetryable = (err: Error): boolean => {
  if (err instanceof NetworkError) return true;
  if (err instanceof TimeoutError) return true;
  return false;
};

Circuit Breaker

class CircuitBreaker {
  private failures = 0;
  private lastFailure: Date | null = null;
  private state: 'closed' | 'open' | 'half-open' = 'closed';

  constructor(
    private threshold: number,
    private timeout: number
  ) {}

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure! > this.timeout) {
        this.state = 'half-open';
      } else {
        throw new CircuitOpenError();
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (err) {
      this.onFailure();
      throw err;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = 'closed';
  }

  private onFailure() {
    this.failures++;
    this.lastFailure = new Date();
    if (this.failures >= this.threshold) {
      this.state = 'open';
    }
  }
}

---

Idempotency Patterns

Method	Idempotent	Strategy
GET	Yes	No action needed
PUT	Yes	Full replacement is idempotent
DELETE	Yes	Deleting twice = same result
POST	No	Idempotency-Key header required
PATCH	No	Optimistic locking with ETag

// Idempotency-Key implementation
async function handleCreateOrder(req: Request, res: Response) {
  const idempotencyKey = req.headers['x-idempotency-key'];

  if (idempotencyKey) {
    const cached = await idempotencyStore.get(idempotencyKey);
    if (cached) {
      return res.status(200).json(cached.response);
    }
  }

  const order = await orderService.create(req.body);

  if (idempotencyKey) {
    await idempotencyStore.set(idempotencyKey, {
      response: { data: order },
      createdAt: Date.now(),
    }, { ttl: 86400 }); // 24h TTL
  }

  res.status(201).json({ data: order });
}

---

Common Mistakes

Mistake	Fix
Business logic in handlers	Handlers validate + delegate. Logic in service layer.
Database queries in services	Services call repositories, never DB clients directly.
Swallowing errors	Use Result types. Let unexpected errors bubble.
Missing tenant isolation	Every query includes tenant_id. No exceptions.
Hardcoded config	All config from env vars, validated at startup.
No idempotency on writes	Every POST accepts Idempotency-Key header.
Auth from scratch	Use JWKS/OAuth2 middleware. Never parse JWTs manually.
Tests depend on order	Each test sets up and tears down. No shared state.
No circuit breaker	Every outbound call needs circuit breaker.
Logging sensitive data	Never log passwords, tokens, PII. Redact in middleware.

---

Execution Checklist

• Phase 1: Implementation plan created from architecture contracts
• Phase 2a: Shared foundations established (types, errors, middleware)
• Phase 2b: Services implemented with clean architecture
• Phase 3: Cross-cutting concerns verified for consistency
• Phase 4: Integration layer configured
• Phase 5: Local dev environment (docker-compose, .env.example, Makefile)
• All services have unit tests (TDD followed)
• All services have integration tests
• Error handling uses Result types
• Idempotency implemented for mutations
• Circuit breakers configured for external calls
• Tenant isolation verified in all queries
• No hardcoded secrets (all from env vars)

Hashline Edit Validation (NEW — OmO Feature)

Purpose: Reliable file editing with content-hash validation. Every line read returns LINE#HASH for stable editing. Edits referencing an outdated hash are rejected before any corruption.

Problem solved: Stale-line errors — when a file changes between read and edit, the agent edits the wrong content. Grok Code success rate improved 6.7% → 68.3% with hashline editing.

How Hashline Works

1. Read — hashline_read returns each line as LINE#HASH| content
2. Edit — Use LINE#HASH reference instead of raw line number
3. Validate — If file changed, hash won't match → edit rejected with diff

Usage

// Read file (returns hashline format)
import { readHashlineSync, formatHashlineContent } from './scripts/hashline/hashline.ts';

const file = readHashlineSync('src/auth.ts');
console.log(formatHashlineContent(file));
// Output:
// 22#sZVsGc| import { createHash } from 'crypto';
// 33#KjLpQ2| const user = await db.query('SELECT * FROM users');
// 44#MnRvWx| if (!user) throw new Error('Not found');

When to Use Hashline

• Multi-step edits — file may change between reads
• Long tasks — context window may refresh
• Collaborative environments — files may change externally
• Critical edits — when edit reliability matters

MCP Tools (when registered)

// hashline_read
{ tool: "hashline_read", args: { path: "src/auth.ts" } }
// Returns: LINE#HASH| content format

// hashline_edit
{ tool: "hashline_edit", args: {
  path: "src/auth.ts",
  ref: "44#MnRvWx",        // LINE#HASH from read
  newContent: "if (!user) throw new AuthError('AUTH_USER_NOT_FOUND');"
}}
// Returns: { success: true } or { success: false, error: "HASH_MISMATCH", diff: {...} }

Fallback

If hashline tools unavailable, use standard line-number editing. Hashline is additive — it enhances reliability without breaking existing workflows.

Setup

Hashline tools are in scripts/hashline/. To enable as MCP tools, register them in the MCP server config.

# Read with hashline
node scripts/hashline/hashline.ts read src/auth.ts

# Apply edit with hashline
node scripts/hashline/hashline.ts edit src/auth.ts 44#MnRvWx "new content"