Architecture Audit

---
name: architecture-audit
description: Use when the architecture may have drifted from documentation, packages have grown complex, dead code or disabled systems are suspected, or before planning a major refactor — scoped to the reactive-agents-ts 22-package monorepo.
user-invocable: true
---

# Architecture Audit

## Overview

System-level health check for Reactive Agents. Like `/simplify` but scoped to architecture: surveys the package topology, kernel internals, and documentation for dead code, over-abstraction, layer violations, and stale claims — then fixes what's safe and flags what needs planning.

**Use when:**

-   `AGENTS.md`, `MEMORY.md`, or inline docs may no longer match the code
-   A package or subsystem has grown unexpectedly complex
-   Cleaning up after a large feature: scaffolding, flags, disabled code wasn't removed
-   Preparing to plan a refactor and need an honest current-state baseline

**Don't use for:**

-   Effect-TS abstraction candidates specifically → `effect-abstraction-audit`
-   Code-level cleanup of recent changes → `/simplify`
-   Single-file or unit-level concerns

---

## Phase 1: Architecture Snapshot

> Authoritative current-state map: [[wiki/Architecture/Framework-Architecture-Index]] (file:line-anchored).

Before launching agents, orient to current state. **Always start with the wiki** — see [[wiki/Development/Wiki-Workflow|Wiki Workflow]].

```
claude-obsidian:wiki-query "<subsystem> architecture decisions"
```

This surfaces relevant: prior architecture audits, decisions, debriefs, and concept pages — avoiding rediscovery.

Read in this order:

**Authoritative docs:**

```
AGENTS.md                                        # canonical architecture + build order
wiki/Hot.md                                       # current empirical state
wiki/Architecture/Specs/09-UNIFIED-PROGRAM.md    # canonical sequencing + architecture target
wiki/Architecture/DEBT-REGISTER.md               # canonical technical debt
apps/cortex/AGENTS.md                            # Cortex-specific patterns
```

**Wiki indexes:**

```
wiki/Decisions/Decision Index.md                 # past architectural decisions
wiki/Issues/Running Issues Log.md                # known architectural debt
wiki/Failure-Modes/00 FM Catalog.md              # observed failure modes
```

**Kernel internals (highest-churn area):**

```
packages/reasoning/src/kernel/
  kernel-state.ts        # KernelState, Phase type, KernelContext
  kernel-runner.ts       # runKernel() loop
  react-kernel.ts        # makeKernel() factory
  phases/                # context-builder, think, guard, act
  utils/                 # ics-coordinator, loop-detector, tool-utils, etc.
```

**Known architectural debt (pre-loaded, refreshed 2026-07-22 post-v0.14 audit — verify each is still present):**
| Debt item | Location | Status to verify |
|-----------|----------|-----------------|
| Provider adapter hooks (resolved v0.14: 4-hook system, all wired) | `provider-adapters/` | `continuationHint`, `errorRecovery`, `synthesisPrompt`, `qualityCheck` live (+ `parseToolCalls`); `taskFraming`/`toolGuidance`/`systemPromptPatch` removed |
| B3 builder→runtime seam structural cast | `builder/build-effect/runtime-construction.ts` | `self as unknown as BuilderRuntimeStateView` — renamed field NOT a compile error; Wave-4 codegen candidate |
| Loop-detector streak can mask duplicate-tool patterns | `loop-detector.ts` / kernel runner | strategySwitching may never trigger (W8) — still open? |
| `PlanExecuteConfigSchema.patchStrategy` dead config | `reasoning/src/types/config.ts:32` | declared + test-asserted, zero source readers |
| ToT outer loop ignores `dispatcher-early-stop` | `plan-execute.ts` / ToT sub-kernels | outer branches are separate sub-kernels |
| Sub-agent fixed vs dynamic path duplication | `local-agent-tools.ts` / `spawn-handlers.ts` | fixed path could be `singletonAgentMode` of dynamic |

> Resolved — do NOT resurface (verified 2026-07-22): `context-engine.ts` deleted entirely (with its flags); `KernelState.meta` is typed `KernelMeta` (0 `as any` in reasoning src); no disabled local-model strategy routing exists in `strategy-registry.ts`; `define-tool` DX (typed errors, Standard Schema, async handlers); `local.ts` timeout precedence; `build()` fail-fast on missing keys. Canonical ledger: `wiki/Architecture/DEBT-REGISTER.md`.

**Determine scope before proceeding.** Full repo, one package, or one subsystem? Narrow scope = deeper findings.

---

## Phase 2: Launch Three Agents in Parallel

Use the Agent tool to launch all three concurrently. Pass each agent the relevant file paths and the debt table from Phase 1.

### Agent 1: Architecture Health

Inspect the codebase for structural problems:

1. **Layer violations** — Does code in one layer reach through to another it shouldn't? Does `act.ts` know about provider specifics? Does `context-builder.ts` trigger side effects? Does `reasoning` package import directly from `runtime`?
2. **Over-abstraction** — Thin wrappers that add no behavior; one-instance interfaces; single-call factories; config objects wrapping a single primitive; plugin/registry patterns with only one registered implementation and no second on the horizon
3. **Under-abstraction** — Identical or near-identical logic copy-pasted across files with slight variation; repeated stream-parsing patterns across providers; duplicated kernel dispatch logic
4. **Dead or disabled systems** — Feature-flagged code that has no activation path; exported functions/types with zero callers in the monorepo; disabled strategies or routing paths; commented-out orchestration logic
5. **Scope creep** — Utility files that have grown into mini-frameworks; config objects that have accumulated behavior beyond pure data; packages whose `index.ts` exports exceed their documented purpose
6. **Coupling hotspots** — Files imported by 8+ other files; changes here force cascading updates; circular or near-circular dependencies

For each finding: file path, one-sentence problem description, fix direction, and risk (Low / Medium / High).

### Agent 2: Documentation Accuracy

Compare every documented claim against what actually exists:

1. **`AGENTS.md` architecture claims** — Read each section describing package responsibilities, the ExecutionEngine loop phases, and build order. Does the code match? Flag drifted descriptions, removed phases, renamed exports
2. **`MEMORY.md` accuracy** — Check "Architecture (Post Refactor)" and "What Shipped" sections against current file contents. Flag entries describing files, patterns, or module layouts that no longer exist
3. **Kernel extension docs** — Do `AGENTS.md` instructions for "adding a new phase" / "adding a guard" / "adding a meta-tool" still work step-for-step against the current code?
4. **Inline file headers** — Are module-level JSDoc or block comments describing the right responsibility? Are `@param` / `@returns` still accurate?
5. **`apps/docs/src/content/docs/`** — Do user-facing docs describe current public API behavior? Are there documented APIs (`ReactiveAgentBuilder` methods, strategy names, config fields) that no longer exist or have changed signature?
6. **Known debt list** — For each item in the Phase 1 debt table: has it been resolved without docs being updated? Update the debt table if so

For each finding: document file, specific claim, what's wrong in one sentence, correct description.

### Agent 3: Simplification Opportunities

Find where complexity exceeds what the problem requires:

1. **Configuration explosion** — Config schemas with accumulated fields beyond any real use case; options that have never been set to non-default by any test or caller; YAGNI violations
2. **Phase or strategy duplication** — Multiple phases doing overlapping work (e.g., two context-assembly paths); strategies that share >70% of their logic and could be one strategy with a parameter
3. **Indirection chains** — A → B → C → D where B and C route without adding behavior; passes-through that exist only for historical reasons
4. **Parallel systems** — Two systems doing the same job (e.g., two tool-call parsers, two context builders, two error formatters); identify which is canonical and which is dead weight
5. **Type gymnastics** — Complex conditional types, deep `infer` chains, or mapped types where a simpler domain model would be clearer and equally safe
6. **Premature extensibility** — Registries, plugin hooks, or lifecycle systems built for N implementations but only 1 exists and no second is planned in the next milestone

For each finding: file path, description of unnecessary complexity, effort estimate (Low / Medium / High), impact estimate (Low / Medium / High).

---

## Phase 3: Triage and Fix

Wait for all three agents. Categorize every finding:

### Fix Immediately

Safe to fix now without architectural planning:

-   Stale documentation claims in `AGENTS.md`, `MEMORY.md`, inline comments
-   Dead exports (zero callers, confirmed unused)
-   Incorrect or outdated kernel extension instructions
-   Comment cleanup (narrating removed behavior, referencing deleted files)

Rule: fix is < 25 lines and touches ≤ 2 files. Anything larger → Flag for Planning.

### Flag for Planning

Do NOT implement without a written plan:

-   Dead code removal touching > 2 files (e.g., `context-engine.ts` cleanup)
-   Collapsing parallel systems
-   Restructuring config schemas
-   Untangling layer violations

Add each to the **Architecture Debt Register** (see Output below).

### Escalate to User

Needs explicit decision before any action:

-   Parallel systems where the canonical choice is ambiguous
-   Simplifications that change the public API of `@reactive-agents/*`
-   Findings that would span > 3 packages
-   Anything where fixing reveals a deeper design question

---

## Output

When complete, report:

1. **Documentation fixes applied** — count and list of files changed
2. **Top 3 simplification opportunities** — file, problem, effort/impact
3. **Architecture debt register update** — append findings to the debt table in `AGENTS.md` under an `## Architecture Debt` section (create if absent), formatted as:

```markdown
| Area      | File              | Problem                    | Effort | Impact | Status |
| --------- | ----------------- | -------------------------- | ------ | ------ | ------ |
| Dead code | context-engine.ts | ~690 LOC dead behind flags | High   | High   | Open   |
```

4. **Escalations** — anything requiring explicit user decision

Keep the summary under 12 lines. The debt register carries the full detail.

---

## Architecture Quick Reference

| Pattern                    | Location             | What it IS                                                                                                            |
| -------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `Phase[]` pipeline         | `kernel-runner.ts`   | Sequential kernel phases; `(state, ctx) => Effect<KernelState>`                                                       |
| `Guard[]` chain            | `phases/guard.ts`    | Tool-call safety checks; any guard can block                                                                          |
| `MetaToolHandler` registry | `phases/act.ts`      | Inline meta-tool dispatch; new tools = one registry entry                                                             |
| `makeKernel()` factory     | `react-kernel.ts`    | Custom kernel configurations; override default phase set                                                              |
| Two independent records    | `kernel-state.ts`    | `messages[]` (LLM sees) vs `steps[]` (systems observe)                                                                |
| Provider adapter hooks     | `provider-adapters/` | 4-hook adapter system, all wired: `continuationHint`, `errorRecovery`, `synthesisPrompt`, `qualityCheck` (+ `parseToolCalls`) |
| ExecutionEngine loop       | `packages/runtime/`  | 10 phases: BOOTSTRAP → GUARDRAIL → STRATEGY-SELECT → THINK → ACT → OBSERVE → MEMORY-FLUSH → VERIFY → AUDIT → COMPLETE |

## Layer Boundary Rules

```
core → llm-provider / memory / tools / identity / observability / interaction
     → reasoning / guardrails / verification / cost / eval / a2a / gateway / orchestration / prompts
     → runtime
     → reactive-agents (facade)
```

-   No upward imports (reasoning must not import runtime)
-   No skip-layer imports (reasoning must not import reactive-agents)
-   `packages/reasoning` may import: core, llm-provider, memory, tools only

## Anti-Patterns to Flag on Sight

| Anti-pattern                   | Known location                                    | Signal                                      |
| ------------------------------ | ------------------------------------------------- | ------------------------------------------- |
| Dead code behind feature flags | `context-engine.ts`                               | `buildDynamicContext`, `buildStaticContext` |
| Untyped meta bag with `as any` | `kernel-state.ts`                                 | `meta: Record<string, unknown>`             |
| Disabled strategy routing      | `strategy-registry.ts`                            | Local model routing commented out           |
| Two-path context building      | `context-engine.ts` + `phases/context-builder.ts` | Which is canonical?                         |