Standardizing Typescript Architecture

The ADR template (from /understanding) defines exactly these sections:

1. Purpose -- What concern this decision governs. State as permanent truth.
2. Context -- Business impact and technical constraints.
3. Decision -- Primary decision in one sentence.
4. Rationale -- Why this is right given the constraints. Alternatives considered and rejected.
5. Trade-offs accepted -- Table: what is given up, why it is acceptable or mitigated.
6. Invariants (optional) -- Algebraic properties that hold for ALL governed code. Omit if none apply.
7. Compliance -- Observable patterns (Recognized by), rules (MUST), prohibitions (NEVER).

This is the complete list. An ADR has no other sections. There is no "Testing Strategy" section, no "Status" field, no "Level Assignments" table. Testability constraints live in Compliance as MUST/NEVER rules.

When an ADR is required: Every module that makes architectural decisions — module layout, library choice, DI patterns — requires an ADR. The absence of an ADR is itself a violation, not a reason to skip the audit.

ADRs do not assign testing levels. They establish constraints that make levels achievable. The /testing skill assigns levels when it reads spec assertions alongside ADR constraints. This separation follows the truth hierarchy: ADR governs, spec declares, test verifies.

The mechanism: Compliance rules that mandate DI, prohibit mocking, and require observable interfaces.

Correct pattern -- testability as MUST/NEVER:

## Compliance

### Recognized by

Observable DI parameters in all functions that invoke external tools.

### MUST

- All external tool invocations accept a dependency-injected runner parameter -- enables isolated testing without mocking ([review])
- Configuration accepts typed inputs, not environment reads -- enables Level 1 verification of config logic ([review])

### NEVER

- `vi.mock()` or `jest.mock()` for any dependency -- violates reality principle ([review])
- Direct `child_process.exec/spawn` without DI wrapper -- prevents isolated testing ([review])

What this replaces -- the following does NOT belong in an ADR:

## Testing Strategy                    <-- NOT a valid ADR section

### Level Assignments                  <-- downstream concern for /testing

| Component        | Level | Justification                   |
| ---------------- | ----- | ------------------------------- |
| Command building | 1     | Pure function, no external deps |
| Hugo invocation  | 2     | Needs real Hugo binary          |

### Escalation Rationale               <-- downstream concern for /testing

- Level 1->2: Hugo binary required for acceptance

Why: Level assignments depend on the spec's assertions, the project's infrastructure, and the /testing skill's Five Factors analysis. The ADR cannot know these at authoring time. The ADR's job is to establish constraints (DI, no mocking) that make the right levels possible.

ADRs state architectural truth. They NEVER narrate code history, current state, or migration plans. This is a REJECTION-level violation in ANY section -- Context, Decision, Rationale, Compliance, all of it. No section gets a pass.

An ADR that references existing code ("The current X has...", "The file X does not exist") is temporal -- it becomes stale the moment that code changes. Code that violates an ADR is discovered through code review and test coverage analysis against the ADR's invariants.

Temporal patterns to reject:

• "The current module.ts has..." -- narrates code state
• "The file deprecated/old.ts does not exist" -- narrates filesystem state
• "We need to replace..." / "We need to migrate..." -- narrates a plan, not a truth
• "Currently X uses..." -- snapshot that expires
• "The existing implementation..." -- references code, not architecture
• "After evaluating options..." -- narrates decision history
• "X has accumulated without..." -- narrates drift
• "Previously..." / "Before this..." -- there is no before
• "Going forward..." / "In the future..." -- there is only the product truth

The rewrite pattern:

• TEMPORAL: "The current BuildRunner class in build.ts shells out to Hugo directly without dependency injection."

• ATEMPORAL: "Build orchestration uses dependency injection to isolate tool invocation from build logic."

• TEMPORAL: "The file legacy/builder.ts does not exist and should be removed."

• ATEMPORAL: "Build implementations conform to the BuildDependencies interface."

• TEMPORAL: "We discovered that direct execa calls make testing impossible."

• ATEMPORAL: "Direct process invocation prevents Level 1 testing. Dependency injection enables isolated unit verification."

When an ADR mandates dependency injection, these are the TypeScript patterns to reference in Compliance rules.

Interface-based DI:

// ADR Compliance: "MUST accept runner as parameter"
interface BuildDependencies {
  run: (cmd: string[], opts?: ExecOptions) => Promise<ExecResult>;
  resolveVersion: (tool: string) => Promise<string>;
}

// Level 1: inject controlled implementation
// Level 2+: inject real implementation
function buildSite(
  config: BuildConfig,
  deps: BuildDependencies,
): Promise<BuildResult> {
  // ...
}

ADR Compliance rule to code mapping:

Mocking prohibition in ADR language:

The auditor checks for these violations in ADR text:

• vi.mock() or jest.mock() mentioned as an approach -- reject
• "mock at boundary" or "mock the X calls" -- reject
• "stub" or "fake" without referencing a /testing exception case -- reject

Correct ADR language: "Use dependency injection to isolate X from Y" or "Accept X as a parameter implementing the Y interface."

The architect needs to understand testing levels to write effective Compliance rules. The auditor needs them to verify that Compliance rules enable the right levels. These definitions come from /testing.

Key rules:

• Git is Level 1 (standard dev tool, always available in CI)
• Project-specific tools require installation/setup (Level 2)
• Network dependencies and external services are Level 3
• SaaS services jump L1 to L3 (no Level 2)

How levels relate to ADRs: The ADR does not assign levels. It establishes Compliance rules that determine what levels are achievable. "MUST accept runner as parameter" makes Level 1 possible for the logic around the tool. "NEVER call external API directly" means Level 3 for the real call, Level 1 for the business logic.