Phase 2 · Architecture fitness linting — mechanically enforced dependency layers with agent-friendly error messages

[Luis85]

Meta

type: EngineeringScaffold
stage: draft
maturity: L1
created: 2026-05-10
inputs:
  - "OpenAI harness engineering (2026-02) — architectural model enforced via custom linters and structural tests"
  - "#14 — architectural layering and hexagonal boundaries"
  - "#29 — CI workflow"
related: ["#14", "#29", "#28"]

Purpose. Mechanically enforce the runtime's architectural dependency layers and taste invariants via custom linters and structural tests, with error messages that include agent-readable remediation instructions.

---

Context

OpenAI's harness engineering experience makes this point directly:

"We built the application around a rigid architectural model. Every business domain is divided into a fixed number of layers, with strictly checked dependency directions and a limited number of allowed edges. These constraints are enforced mechanically through custom linters (generated by Codex, naturally!) and structural tests."

"Custom linters include remediation instructions in error messages so agents can fix violations without human intervention."

"This is the kind of architecture you normally defer until you have hundreds of engineers. With coding agents, it's an early prerequisite: the constraints are what enable speed without decay or architectural drift."

The runtime's #14 already defines the layered hexagonal architecture. This issue mechanises its enforcement before the first production code lands.

---

What to enforce

Dependency layer ordering

Within the runtime package, code must flow in one direction only:

Types → Config → Ports → Kernel → Systems → Adapters → Public barrel

No reverse imports. No skipping layers. Enforced via import-graph analysis.

Cross-boundary rules

• Public barrel (src/index.ts) must export only L2 public domain types and the RuntimeKernel façade
• Internal ECS types (L3) must never appear in public exports
• Capability ports must not import from kernel internals
• WorktreePort must not be exported from the barrel (→ Phase 1 · SAO design decision — port namespace organisation (WorktreePort / OrchestratorPort) #50)

Taste invariants

Invariant	Check
Structured logging only	No console.log / console.error in non-test code
Result discipline	All functions crossing a port boundary must return Result<T, E>
No implicit any	TypeScript strict: true + noImplicitAny enforced
Event payload serialisability	All RuntimeEvent subtypes must pass a JSON round-trip test (→ #17)
File size limit	No source file exceeds 400 lines
No barrel re-export of internal types	Grep check on barrel exports

---

Agent-friendly error messages

Per the harness engineering article, each lint failure must include a remediation instruction that an agent can act on without human clarification:

ESLint: import-layer-order — 'src/kernel/AgentTickSystem.ts' imports from 'src/adapters/WorktreeAdapter.ts'
  ✗ Kernel layer cannot import from Adapters layer (direction: kernel → systems → adapters → barrel)
  ✓ Fix: move the dependency inversion — define a port interface in 'src/ports/internal/' and inject the adapter
  Docs: docs/ARCHITECTURE.md#dependency-layers

Every lint rule must have:

1. A violation description (what broke)
2. A fix instruction (what to do)
3. A docs reference (where to learn more)

---

Implementation plan

1. Add eslint-plugin-import or a custom ESLint plugin for layer-order enforcement
2. Write a structural test (src/__tests__/architecture.test.ts) that programmatically checks:
   • Public barrel exports only allowed types
   • No internal types leak through the barrel
   • All event payload types pass JSON round-trip
3. Write or configure lint rules for taste invariants
4. Ensure all lint errors include remediation instructions (custom messages in ESLint rule metadata)
5. Wire into CI via Phase 2 · CI workflow — typecheck, test, surface review, build #29

---

Acceptance

• Dependency layer ordering enforced by lint or structural test
• Cross-boundary rules enforced (barrel export check, WorktreePort not exported)
• All taste invariants covered (structured logging, Result, no implicit any, event serialisability, file size, barrel)
• Every lint rule has a remediation instruction in its error message
• All checks wired into CI (Phase 2 · CI workflow — typecheck, test, surface review, build #29)
• docs/ARCHITECTURE.md#dependency-layers section written as the remediation reference target