What is this? A log of Architectural Decision Records (ADRs) tracking structural agreements, boundaries, and lifecycles. When do I use it? Before introducing new abstractions, changing completion contracts, or altering workspace data-flow spines. What is the source of truth? Approved implementation plans, user-signed ADRs, and structural design conventions.
Last audited: 2026-08-06
Status: Accepted & Implemented
Context: Non-technical stakeholders (product managers, client approvers, non-engineering leadership) struggle with classic AI coding interfaces that require acting as software architects—formulating complex prompt queries, reviewing code diffs, reading terminal execution output, and interpreting stack traces.
Decision: Implement Guided Spec Mode (v1.0.0-spec) layered over the core LLM execution engine under the AUTO execution mode:
-
AUTOMode Integration: Extend theModeunion type to include"auto"across storage, policy engines (UniversalGuard,FluidPolicyEngine), system prompts, and UI controls. -
Zero-Code & Zero-Terminal Prompt Injection: When in
"auto"mode,PromptBuilder.tsinjects# SYSTEM OVERRIDE: LUMI GUIDED SPEC MODE, banning raw code blocks, bash commands, and speculative developer language in favor of 4-block structured product specifications. -
4-State Deterministic Lifecycle Engine:
0. IDLE$\rightarrow$ 1. DISCOVERY$\rightarrow$ 2. SPEC LOCK$\rightarrow$ 3. MILESTONE EXEC$\rightarrow$ 4. HANDOFF. -
Real-time Parser & Product Canvas:
parseGuidedSpecOutput(parser.ts) extracts real-time state streams.GuidedSpecCard.tsxrenders visual Breadboards, Progress Stepper Timelines, 1-Click Decision Chips (Option A/Option B), single-key Superhuman shortcuts (Press A/Press B), trade-off rationale drawers, and an interactive Product Architecture Canvas Drawer. -
Sticky Composer Quick Approve:
ChatTextArea.tsxrenders a sticky 1-click "Proceed with Defaults" action bar above the input field.
Consequences:
- Eliminates technical syntax noise for non-technical stakeholders.
- Enables 1-click or 1-key (
A) milestone progression with zero prompt typing. - Auto-generates rollback restoration snapshot checkpoints upon feature handoff.
Status: Accepted
Context: The MoD framework previously used a dedicated backend orchestrator (MixtureOfDesignersOrchestrator) that bypassed the main coding agent task loop. This introduced redundant execution paths, maintenance complexity, and tool parity drift. All MoD requirements are fundamentally a mirror of the coding agent steered by senior designer instincts.
Decision: Refactor MoD in its entirety into a System Prompt Steering Toggle:
- Unified Task Execution Path: MoD Mode runs through the standard coding task loop (
initiateTaskLoopinsrc/core/task/index.ts) with 100% tool parity (read_file,replace_in_file,execute_command,browser_action, subagents, MCP tools). - Dynamic Prompt Steering: When
modEnabledistrue,PromptBuilder.tsautomatically injectsMOD_DESIGNER_STEERING(src/core/prompts/system-prompt/components/mod_designer_steering.ts) directly afterAGENT_ROLE_SECTIONfor maximum attention weighting. - 6 Design Engineering Pillars: Injects Design Token Sensing, Complete 7-State UI Matrix, WCAG 2.1 AA Accessibility, Visual Aesthetics, Responsive Layout Ergonomics, and 5-Whys Cognitive Analysis.
- Subagent Swarm Propagation:
SubagentRunner.tspropagatesmodEnabled: truedown to subagent task contexts so subagent swarms inherit senior designer instincts seamlessly. - Non-Technical UX Ergonomics: Segmented control switcher (
ModModeSwitcher.tsx) with zero-jargon copy, keyboard navigation, popover guides, and visual indicator badges.
Consequences:
- Centralizes core execution into a single, unified, highly optimized task loop.
- Guarantees 100% tool parity between Coding Mode and Design (MoD) Mode.
- Eliminates thousands of lines of redundant backend orchestration bypass code.
Status: Superseded by ADR-016
Context: The Mixture of Designers framework originally modeled design expertise as five isolated voting personas. World-class product design requires a Designer-in-Residence: a single senior product designer embedded in the workspace who moves fluidly across internal design lenses (UX Architecture, Accessibility, Visual Hierarchy, Interaction Patterns, System Engineering) while maintaining one coherent product vision.
Decision: Implement the LUMI Designer-in-Residence architecture in src/core/orchestration/mod/:
- Single senior designer agent with 5-Whys recursive root-cause reasoning (
DesignerInResidence.ts). - Industry Pattern Library Registry (
PatternLibrary.ts) benchmarking UI issues against learned conventions (Command Palette, Split Workspace, Contextual Action Toolbar, Optimistic Undo Toast, Guided Empty State, Focus-Trapped Modals). - Design Token Sensing & Codemod Sync Engine (
ContextBuilder.ts,TokenSyncEngine.ts) mapping hardcoded CSS/HEX values to canonical design tokens. - Dynamic UX Health Index (0-100) & Debt Graph (
DesignIntelligenceGraph.ts). - Design Decision Records (
DesignDecisionRecord.ts) and Design System Drift Guard (DesignDriftDetector.ts). - 8-State Interactive UI Component Contract Ledger (
ComponentContractLedger.ts) and Predictive UX Regression Risk Calculator (UXRegressionRiskCalculator.ts). - Speculative Task Wave Planner (
SpeculativeTaskPlanner.ts), Adaptive Circuit Breaker (DesignCircuitBreaker.ts), In-Memory State Cache (DesignStateCache.ts), and Fast-Path Atomic Decision Locking (MixtureOfDesignersOrchestrator.ts).
Consequences:
- Eliminates multi-agent persona voting overhead and consensus deadlocks.
- Provides immutable design governance logging (
DDR-001) and automated CSS token codemod patches. - Prevents breaking UI layout regressions via predictive risk scoring.
- Achieves high throughput via parallel disjoint task wave partitioning and non-blocking background I/O.
Status: Accepted
Context: The repository already had extensive user/developer docs and an older .wiki, but future agents needed a direct operating layer that separated current task state from stable architecture.
Decision: Maintain these root files:
AGENT_PLAYBOOK.mdfor current agent operating guidance.WIKI.mdfor stable workspace architecture and workflows.TROUBLESHOOTING.mdfor negative knowledge and reproduced failures.DECISIONS.mdfor root-level continuity decisions.HANDOFF.mdfor current working-tree state and next steps.
Consequences:
- Future agents can start at the root without scanning the whole docs tree.
- Stable knowledge and temporary handoff state have separate homes.
- Root docs must be kept concise and linked to deeper docs rather than duplicating them.
Status: Accepted
Context: Some existing docs lagged current code. Examples found in this pass: provider count drift, stale roadmap bootstrap content, README version badge drift, and old .wiki DietCode/Spider claims.
Decision: When docs and implementation disagree, use implementation and manifests as source of truth, then update or flag stale docs.
Consequences:
- Provider truth comes from
src/core/api/index.tsandsrc/shared/providers/providers.json; provider-count docs were corrected to 5 in this pass. - Version truth comes from
package.json; root README version references were corrected to 3.0.0 in this pass. - Architecture truth comes from maintained docs plus current source layout.
- The roadmap and
.wikineed explicit refresh passes before they can be treated as authoritative.
Status: Accepted
Context: Human-oriented wiki notes did not reliably reduce future-agent rediscovery.
Decision: Embed the Agent Playbook Method in:
- system prompt wiki rules (
integrity_wiki.ts), - same-session finalization generation (
AutonomousDocumentationFinalizer.ts), - a workspace skill (
.agents/skills/agent-playbook-method/SKILL.md), - root operating docs (
AGENT_PLAYBOOK.mdandHANDOFF.md).
Consequences:
- Future finalization runs can create
.wiki/agent/*files from workspace evidence. - Manual wiki/playbook work has a project skill and root standard.
- Generated wiki sections should be managed and replaceable, not endlessly appended.
Status: Accepted
Context: The completion lifecycle decision engine was added to prevent stale audit reuse, duplicate retry loops, and agent misinterpretation.
Decision: New completion eligibility behavior must go through the snapshot -> decision -> action contract -> action guard spine.
Consequences:
- Do not add completion/finalization routing policy directly in handlers.
- Tests should verify decision output and guard behavior.
- Finalization documentation work happens after engineering verification via
run_finalization. - Eligibility and terminal durability remain separate: a successful decision is not terminal until the SQLite
task_completionsCAS commits.
Status: Accepted
Context: Broad mocha can load unrelated tests and hit sandbox-only failures, such as roadmap progress writes under ~/.dietcode/session.
Decision: For a small change, run a focused spec with --no-config, then production typecheck and style checks. Run broad suites when the environment supports their filesystem requirements.
Consequences:
- Final responses should report both focused proof and broad-suite limitations.
- Sandbox failures should be documented in
TROUBLESHOOTING.md. - Do not hide unrelated failures; classify them.
Status: Accepted
Context: The monorepo contains the extension session layer and a substrate package with its own public API and docs.
Decision: Root and docs/ should describe LUMI session behavior and link to BroccoliDB docs for substrate details. BroccoliDB-specific architecture belongs under broccolidb/docs/.
Consequences:
WIKI.mdcan map the two layers but should not duplicate BroccoliDB internals.- BroccoliDB changes should run BroccoliDB package tests and update BroccoliDB docs.
Status: Accepted
Context: Prompt/wiki instructions and manual memory are not enough to preserve engineering intelligence. Completed tasks need a harness-owned learning pass that classifies durable knowledge, detects drift, and persists a structured cognitive model.
Decision: Add src/core/workspace-intelligence/ as a first-class subsystem invoked by AutonomousDocumentationFinalizer during run_finalization. The engine writes a canonical .wiki/intelligence/workspace-intelligence.json, a scan-friendly markdown projection, optional BroccoliDB cognitive memory entries, and receipt evidence fields.
Consequences:
- Workspace intelligence is now part of the completion/finalization contract, not only prompt guidance.
- Knowledge is classified as permanent, operational, historical, failure, or predictive.
- Drift findings and category counts travel with finalization evidence.
- Future improvements should expand discovery signals and lifecycle hooks through this subsystem rather than scattering continuity logic across handlers.
| Item | Needed evidence |
|---|---|
Whether ROADMAP.md should be regenerated or manually repaired |
Roadmap audit/checkpoint output and maintainer preference |
| Whether root continuity docs should be included in docs CI | Link-check scope and release policy |
Whether .wiki/00-forensics.md should be replaced by generated current-state sections |
Fresh Spider/roadmap diagnostics |
| Whether Workspace Intelligence should also observe task-start/tool-execution phases | Design pass over task lifecycle hooks, storage volume, and privacy constraints |
Status: Accepted
Context: Storing raw unstructured conclusions makes facts opaque and prevents future tasks from validating why a subsystem was marked volatile or risky.
Decision: Commit to a two-phase evolution for the Workspace Intelligence subsystem:
- Provenance & Auditing: Every derived fact/signal stored in the cognitive model must preserve its evidence trail (provenance metadata, e.g., finalization run, specific manifest, verification artifacts, or ADR file links) to answer why it is believed.
- Query Service Interface: Evolve the architecture from a monolithic model object to a queryable domain service exposing dedicated APIs (e.g.,
getSubsystemHealth(),getRecurringFailurePatterns(),getMostVolatileAreas()) rather than expanding the schema indefinitely.
Consequences:
- Conclusions remain auditable by both humans and subsequent agent instances.
- Downstream features (planning, completion guidance, roadmap steering) consume structured queries rather than raw JSON structures.
Status: Accepted
Context: Over time, workspace facts can linger, accumulate, or become outdated, leading to drift between the persisted cognitive model and the actual codebase.
Decision: Evolve the Workspace Intelligence subsystem to support a explicit fact lifecycle:
- Lifecycle States: Define
WorkspaceFactLifecycleas"active" | "stale" | "superseded" | "disputed" | "archived". - Management Queries: Extend the query service to expose operations like
explainFact(factId),getStaleFacts(), andsupersedeFact(oldFactId, newFactId)to handle conflict resolution and deprecate old conclusions.
Consequences:
- The intelligence reader is robust against stale assertions.
- Subsequent tasks can dynamically update or dispute existing facts based on new execution evidence.
Status: Accepted
Context: Treating the workspace intelligence model as a set of flat "state surfaces" restricts scalability. Adding new categories (e.g. dependency graphs, ownership, test coverage) forces schema changes and pollutes the storage layer with raw presentation structures.
Decision: Formally define the subsystem as a Workspace Knowledge System and decouple storage from presentation:
- Unified Storage Schema: Define a normalized database model consisting of a collection of
WorkspaceFactentities (containingid,value,confidence,provenance[], andlifecyclefields) and their relationships. - Projections as Views: Redefine the current state surfaces (e.g.,
volatileSubsystems,stableSubsystems) as dynamic "views" or "projections" computed by the Query Layer over the core facts database, rather than hardcoding them in the storage schema. - Reasoning Invariant: Enforce that the knowledge system only records deterministic execution evidence and parsed repository signals. Planning, heuristic interpretation, and reasoning remain the sole responsibility of the active planning model/agent, keeping the data layer clean and auditable.
Consequences:
- The knowledge layer can expand to capture new engineering dimensions (dependency maturity, code coverage, performance hotspots) without database migrations.
- Producers (finalizers, observers) write normalized facts, while consumers (wiki projection, agent playbook, system prompt) retrieve query-driven views.
Status: Accepted
Context: Treating memory, files, and SQLite as peer lock authorities makes database outages and stale projections ambiguous. Numeric fencing tokens also lose identity precision at large generations.
Decision: Fix coordination mode at startup. Production uses sqlite; local_test is explicit and never selected as a fallback. Allocate epochs/tokens under BEGIN IMMEDIATE, store them as decimal TEXT, and treat memory/file/Broccoli state as projections of the SQLite lease. Isolate ownership overrides in AdministrativeLockCleaner.
Consequences: Database outages retry or fail closed, exact old-owner tuples cannot release newer leases, projection cleanup cannot revert a committed database release, and emergency cleanup is explicit and logged.
Status: Accepted
Context: Cycles and capacity pressure can resolve through timers, lease expiry, outside owners, or unrelated running work. A diagnosis becomes unsafe if scheduler state changes before recovery.
Decision: Build typed wait edges from one immutable scheduler/lane snapshot, run Tarjan SCC on hard edges, require no valid escape transition, and re-check both state versions before recovery.
Consequences: Ordinary contention/backoff does not trigger false recovery, true self/dependency/ownership cycles remain detectable, and stale diagnoses are discarded.
Status: Accepted
Context: In-memory duplicate suppression cannot survive restart or serialize competing completion attempts.
Decision: Canonically hash task, evaluated state version, checkpoint, outcome, and decision schema version. Persist one task_completions row under BEGIN IMMEDIATE after verifying the live lease tuple, freshest generation, and unchanged task state version.
Consequences: Restart delivery is idempotent, same-outcome duplicates are suppressed, competing outcomes conflict visibly, and stale owners cannot terminalize.
Status: Accepted
Context: Continuous long-running subagent execution without storage retention caps leads to exponential database file bloat, disk erosion, checkpoint binary bloat, native sqlite3_stmt handle leaks, and V8 array allocation memory leaks.
Decision: Enforce a multi-layered SQLite retention and memory architecture:
- Universal Retention Sweeps: Complete retention policies covering all system tables (
nodes,trees,stashes,agent_streams,agent_tasks, legacytasks,agent_cognitive_snapshots,telemetry,task_lifecycle_events,task_lifecycle_records,task_completions,task_rejections,completion_attempts, expiredbranches, and unreferencedswarm_lock_generations) with automatic orphan CAS file and edge garbage collection. - Auto-Vacuum PRAGMA Ordering & Reclaiming: Ensure
PRAGMA auto_vacuum = INCREMENTAL;executes BEFOREPRAGMA journal_mode = WAL;during DB initialization, running an automaticVACUUM;header migration if a DB was initialized in non-autovacuum mode. Freelist vacuuming loop returns freed pages to OS (incremental_vacuumuntilfreelist_count === 0). - Resilient WAL Checkpointing: Enforce automated WAL truncation (
wal_checkpoint(TRUNCATE)) with exponential backoff retries when WAL logs exceed 32 MB or busy readers block checkpoints. - Native Prepared Statement Handle Disposal: Prepared statement caching via
_rawStmtCache(LRU eviction and connectiondestroyDb()teardown) explicitly calls.dispose()onbetter-sqlite3statements to eliminate native C++ memory handle leaks. Hot-path persistence layers (TaskLifecyclePersistence,SwarmMutexService,CompletionFunnel) consumegetCachedStatement. - Buffer Pooling & Garbage Collection: Parameter-bounded chunking in
BufferedDbPool(dynamically capped to parameter buffer bounds), with bounded ring-buffer latency tracking to eliminate array allocation pressure. - Binary Exclusion: Binary database exclusion in
CheckpointExclusions.ts(*.db,*.db-wal,*.db-shm,*.sqlite3) to prevent Git checkpoint bloat.
Consequences: Prevents unbounded disk growth, eliminates native statement handle and V8 array allocation memory leaks, prevents lock timeouts (busy_timeout = 5000), and keeps SQLite query latencies sub-millisecond.