Skip to content

CascadeIDE architecture policy (navigator)

Status: Active.
Purpose of this file: a short living navigator — where to look and which decisions are already recorded. Detailed decision rationale (context, choice, consequences, rejected alternatives) lives in ADR; we do not duplicate long sections here.

ADR statuses (Proposed / Accepted / …, plus a second tag Implemented for shipped code): adr/status-lifecycle.md.

Related docs: ../git-and-submodules-v1.md, ../MCP-PROTOCOL.md, ../debug-human-agent-parity-v1.md, ../architecture-migration.md, product boundary draft ../design/north-star-cursor-mcp-cascade-workbench-v1.md (Cursor + MCP + Cascade).

Recommended entry point (how things work today)

Goal

Keep velocity for a single desktop app (Avalonia + MVVM) while boundaries between UI, scenarios, and the outside world stay explicit; for debugging — one layer for human and agent (see ../debug-human-agent-parity-v1.md and ADR 0002).

The policy is pragmatic: not full DDD across the codebase — see ADR 0006.

Product focus (near horizon)

Iteration priority: a comfortable path for users coming from Cursor (MCP, agent and repository observability in one loop with CascadeIDE). Parity with Visual Studio on scenario coverage is a long horizon, not a criterion for near-term release speed. More detail and the north-star wording — ../design/north-star-cursor-mcp-cascade-workbench-v1.md.

Keyboard-first: CascadeIDE is planned as an IDE where the typical loop is keyboard and command palette, not mandatory mouse navigation through dense panels; aligned with ADR 0013 and the keyboard-first section in the north-star doc above.

Documentation and help (intent)

Rich explanations for end users (including multi-monitor layout, mental model of attention zones) are a separate product layer from ADR: channels (external User Guide, in-IDE help, other), scope and priorities are set at product level, not “inside” a specific ADR on windows or config. ADRs remain the normative compact form for development; display notation example — 0017.

Avalonia and the cockpit layer (responsibility boundary)

Avalonia here is the airframe: TopLevel and windows, lifecycle, focus, input routing at the app boundary, OS integration (including DPI), hosting heavy controls where rewrite does not pay off (typically the code editor).

Cockpit semantics — which zones are PFD / Forward / MFD, window topology, effective presentation, pinning share ratios from config without “floating” recalculation for declarative layout convenience — live in CDS and the surface compositor (ADR 0036, blueprint ../design/cds-contract-v0.md). That is not the source of truth in Grid / StackPanel as the carrier of cockpit meaning.

Custom drawing (e.g. Skia) sits on top of Avalonia as host: slot rectangles and draw commands come from the CDS / compositor contract. The Avalonia core is not forked without need; product extensions stay in our layer. Geometry stability with explicit weights in config — 0017 (fuse policy).

CDS vs IDS (short)

One app process — two meaning domains: CDS routes data into cockpit zones (PFD / MFD / instrument slots); IDS is shell overlays (palette, modals, toast) over the workspace, without “instrument in slot” semantics. Table, mnemonic, and link to 0066: ADR 0079 — section “Distinguishing CDS and IDS”.

Where decisions are recorded (ADR)

Topic ADR
Layers, feature slices, role of MainWindowViewModel, list models 0006
Signals, loose coupling, queues/batching; UI thread reference 0007 + 0004
MCP contracts, testable abstractions for git/processes 0008 (Accepted · Implemented)
Strangler migration, when policy may be waived 0009
Dynamic plugins (MEF) — not a near-term goal 0005
Debug: human/agent parity; Debug UI; hypotheses in JSON; awareness without “bottom panel only”; launch profiles (multiple startup configurations); optional embedded URL viewer on MFD (0090 extension); PFD-deck hypothesis when debugging (MFD density) 0002, 0003, 0001, 0011, 0090, 0093 (Proposed), 0091 (Proposed)
UI mode configuration (TOML) 0010 (Accepted · Implemented)
Floating/detachable workspace chrome (bottom zone, telemetry; not floating docs in v1) 0012
Command surface, palette, minimal toolbar; do not mix with chrome placement 0013
Situational checklists (catalog, triggers, UI card) 0014
TOML highlighting in editor (shipped TextMate pack; LSP separate) 0015 (Accepted · Implemented)
External agent via ACP (stdio, Cursor CLI); not the IDE MCP server 0016 (Accepted · Implemented)
Multi-window workspace, second agent surfaces, screen zones; MCP — multiple roots in feature scope 0017 (Accepted · Implemented)
IdeCommands registry: canonical XML docs (summary / param / returns / example) for ProtocolDocGen; migration from mini-language in summary 0018 (Proposed)
Git: shared library for built-in ide_git_* and separate git-mcp; semantic parity 0019 (Accepted · Implemented)
Agent: reasoning visibility layers (reply, tool trace, optional raw log); provider API limits explicit, no fake “full thought process” 0020 (Proposed)
PFD / MFD / forward / EICAS / HUD — cockpit attention model 0021 (Proposed)
PFD instrument deck — composition variants and surfaces (SA, code metrics, semantic map, ADR indicator); catalog table, selection criteria; do not conflate with 0063 as terminology norm 0073 (Proposed)
Visual UI surface (AXAML / Blazor): preview and design-time on MFD / second monitor; not a Blend clone 0022 (Proposed)
Visual UI track (layout designer): separate major CIDE program line; backlog and stack priority (Avalonia → Blazor → optional Razor); UX detail — in 0022 0092 (Accepted)
Markdown + diagrams (Mermaid/PlantUML): first-class via LSP and workflow; LSP injection in fenced blocks — separate phase 0023 (Proposed)
IDE SDK: stable contracts and capability model for internal extension; plugin host remains deferred 0024 (Proposed)
SDK and attention zones: PFD/MFD/… canon in capability metadata; presentation overlay without replacing semantics 0025 (Proposed)
Markdown Preview: separate tool surface; primary MFD, secondary window; renderer decoupled from placement; authoring extensions orthogonal to preview 0069 (Accepted)
Command Palette: direct overlay surface in host, routing to active TopLevel; ModalOverlay not product baseline for palette 0070 (Accepted)
IDS (Ide Display System): IDE overlays (palette, later toast/modals) — intent → compositor → snapshot → surface; do not extend CDS for this path; unified input host and slots — strangler per 0079 0079 (Accepted)
Intercom: user-facing name for the IDE communication channel (not LLM-only); “participants + system” model; team scale — external stack/API by default, not duplicated in IDE; discoverability aliases; code chat* — strangler (0080) 0080 (Proposed)
Intent Melody (parameters): editor line range suffix (:start:end), validation, range refactors; input indicator; orthogonal to anchors from 0080 0081 (Proposed)
ACP + MCP IDE (one process): instead of second CascadeIDE --mcp-stdio — MCP host on loopback (HTTP/SSE) in GUI; token in headers; external --mcp-stdio not removed 0082 (Proposed)
settings.toml — [ai]: mode discriminant (local / acp / mcp_only / cloud), nested tables; legacy flat provider not auto-migrated 0083 (Accepted · Implemented)
Agent and editor: single source of truth — editor buffer; chat — intent/status; agent presence (cursor, “typing”) on separate channel; diff in chat not default; preview/live and safety — see ADR 0084 (Proposed)
Editor HUD vs HUD banner: inline layer at code/caret vs file-level strip above text; global IDE overlays — IDS (0079), not Editor HUD 0085 (Proposed)
Product philosophy (VS/Copilot-class risks, “good actor”); AI principles in IDE cascadeide-philosophy-v1, 0071 (Proposed)
Product focus: small team vs openness readiness — axes “boundaries/contracts” and “queue/discoverability” 0027 (Accepted)
User settings: settings.toml path, TOML/snake_case, secrets in separate ai-keys.toml 0028 (Accepted · Implemented)
UI theme: brush canon in TOML; JSON in MCP (ide_get/set_ui_theme) — wire format; Themes/*.json presets — strangler 0086 (Proposed)
Naming: agent omnibus get_ide_state (was get_workspace_state); IDE Health channel (was Workspace Health); orthogonal to 0002 0089 (Accepted)
Configuration: on-disk canon (TOML); settings center deferred; point UI — canon facade 0029 (Accepted · Implemented)
Settings UI: compact layout, target anchor MFD; overflow policy in P+F+M (scroll, resize, fallback window — see ADR) 0074 (Proposed; does not override 0029 canon)
UI topic index (docs/adr/UI/), MFD page conventions (payload vs projection, keyboard-first) 0075 (Proposed)
UI/UX principles hub: connected intro (cockpit, product philosophy); canon wording in snippets/ui; full ADRs — by link 0076 (Proposed)
TECH principles hub: connected intro (boundaries/contracts, agent/debug); canon in snippets/tech; index TECH/README.md 0077 (Proposed)
Commands: IdeCommands / palette / hotkeys.toml / VM bridge layers; unified UI catalog — blueprint, not required immediately 0030 (Accepted · Implemented)
Agent chat: clarification batches as structured flow, thread/decision graph as first-class; Skia surface — product path, orthogonal to PFD confirmations 0031 (Proposed), 0057 (Accepted)
HUD above editor: what to show and how — in settings.toml; optional grammar like presentation / [presentation_grammar] 0032 (Proposed)
Internationalization: ResX, UI culture; TOML not the dictionary for all UI; orthogonal to config and HUD 0033 (Proposed)
Operator incapacitation: Emergency Mode; EICAS + PIC signal class; liveness, HUD by attention context, dangerous-command interlock; sensors — opt-in 0034 (Proposed)
MFD: embedded WebView2, external web LLMs; web ≠ MCP client; explicit context handoff; bridge to IDE tools (Host Object, allowlist) — 0108 0035 (Proposed), 0108 (Accepted)
CDS: channel → cockpit contract → slot compositor → surface (Avalonia); not full ARINC 661 0036 (Accepted · Implemented)
PFD: surface invariants (weight, input lock, channels) and Roslyn; canon [PfdStrict] / PfdStrictControl 0037 (Proposed)
Agent facade: LLM providers (AiProviderManager), chat, ACP, autonomous mode; external MCP; evolution direction 0038 (Accepted · Implemented)
Workspace navigation: C#-first / .NET north-star; multiple views, graph/semantic map; PFD/MFD; MCP: get_code_navigation_context (presets, kind_filter, subgraph) 0039 (Accepted · Implemented)
LSP C#/Markdown: presets and optional executable/arguments in settings.toml; explicit env read flag — per 0040 0040 (Accepted · Implemented)
Protobuf vs JSON: when binary IDL fits agent/IDE; boundaries with MCP and IdeCommands; pilot criteria 0041 (Proposed)
Pre-flight briefing: Planned Changes and Review Before Apply; semantic layer before disk write; partial approval; reject without artifacts 0042 (Proposed)
MCP transport: parity “human can restart MCP in host ↔ agent sees failure and recovery”; host / CascadeIDE / observability levels; do not mix with debug parity 0043 (Proposed)
Agent chat: dialogue model first, then UI; Avalonia as fuselage, Skia — render-layer hypothesis; spike after/parallel to model 0044 (Proposed)
Agent chat: persistence via append-only event log (*.events.ndjson) + meta.json; UI projections separate 0045 (Proposed)
Cockpit layout: presentation as P/F/M invariant; CDS canon — CockpitPresentationLayoutPolicy; coercion for menu/MCP/UI modes and reactive layer 0046 (Accepted · Implemented)
Cockpit instrument: compositor slot descriptor (CockpitInstrumentDescriptor), not Avalonia control; SE vs semantic map as different instrument_id on PFD 0047 (Accepted · Implemented)
Cursor ACP chat in IDE: mcpServers, auto IDE MCP; apps — tool gaps, Cursor host (mcp.json) ↔ ide_* parsing 0048 (Proposed)
Skia rollout in CIDE: Avalonia remains host/fuselage, Skia expands in surface layer in waves (dual-path, fallback until stable) 0049 (Proposed)
“Instrument → zone/slot” map in TOML: merge bundle/repo/user, [instrument_routing], alias, InstrumentPlacementRuntime 0050 (Accepted · Implemented)
Intent-based attention routing from TOML 0051 (Accepted · Implemented)
CLI for agent contract (MCP parity) and snapshot tests 0052 (Accepted · Implemented: CLI, CI smoke, CDS golden slice)
Semantic map on PFD: control flow in method (branches, join), KISS; Roslyn CFG source; subgraph / MCP extension 0053 (Accepted · Implemented)
CIDE performance benchmarks: scenarios, metrics, baseline and measurement protocol 0054 (Proposed)
Agent ↔ Roslyn MCP coupling in settings.toml: limits, node kinds, timeouts, query presets; orthogonal to [semantic_map] and navigation presets 0039 0058 (Proposed)
Roslyn MCP profiles, Manager: tactics on PFD; EFB / GlobalMap on MFD (not PFD); Auto-Focus / Combat / Echelon 0059 (Proposed)
Keyboard-first: chord layer (CascadeChord / Ctrl+K), FMS-style S/T, overlay hints, MODE on PFD; palette Ctrl+Q not replaced 0060 (Proposed; extends 0013)
Chat: topic cards, drill-in/back, intent navigation commands; Melody/Chords/palette parity (0060 — chat-domain refinement only) 0072 (Proposed)
ADR as awareness layer: path → ADR map in workspace.toml, PFD indicator, brief intent; agent — advisory on bound ADR deviation 0061 (Proposed; implementation deferred)
GitMap (separate from CNC): git submodules / repo boundaries; do not mix with get_code_navigation_context; reuse Skia pipeline; see git-and-submodules-v1 0062 (Proposed)
Named composition in one anchor (instrument deck); ContentRepresentation form axis; primitive taxonomy (incl. Presence/Activity) and Dark Cockpit; do not mix with v1 [instrument_routing] 0063 (Accepted)
Deck indicator kinds: unified graphic embodiment; render library (PrimitivesKit); semantic palette; indicator kind ≠ whole-scene metric tokens; no separate runtime tier 0064 (Accepted)
Instrument categories and graph kinds (graph_kind): domain axis + subgraph structure; “Semantic map” = code intent map (not “any link graph”); optional descriptor/JSON fields — roadmap 0065 (Accepted)
Cockpit UI (deck, instruments, PrimitivesKit, cockpit palette) separate from IDE presentation (chrome, modal overlays, shell theme); default rule in ADR; do not mix layers in review; CASCOPE011/012 — no cross-using between Features/UiChrome and Cockpit/PrimitivesKit 0066 (Accepted)
Graph-backed surfaces — shared contract for graph screens (semantic map, GitMap, future); dimensions: data, interaction, navigation, layout, selection, workspace sync 0067 (Accepted)
Row payload / presentation projection / slot: channel vs how a row is drawn (lamp, glyph, table); orthogonal to ContentRepresentation and deck (0063) 0068 (Accepted)
UI delivery bus ( AFDX analogy): System.Threading.Channel<T>, bounded + UI batching; not the product cockpit channel 0036; strangler — build log / terminal 0094 (Proposed)
Three Health levels: Workspace (folders, Git) · Solution (build, tests) · IDE (LSP, MCP, environment); channel/CDS/MCP taxonomy; strangler from IDE Health 0095 (Proposed)
Intercom: topic card — summary (card index) + drill-in; product spine separate from main thread (CIDE — example); complements topic cards 0072 0096 (Proposed)
Cockpit compute units (CCU): fold inputs into channel snapshot/DTO (LRU Unit analogy); not bus 0094, not CDS; with 0095 on stratum 0097 (Accepted · Implemented)
Data Acquisition Layer (DAL): external adapters (inbound/outbound) separate from CCU; Features/<Feature>/Application allowed for use-case orchestration without direct I/O; DAL ↔ Application ↔ CCU ↔ UI boundary 0102 (Proposed)
Editor HUD substrate: normalized semantic projections + inline/banner policy + editor surface adapter; hi-freq (caret/pointer) — separate bounded path, not IDataBus 0099; baseline AvaloniaEdit; host comparison — editor-surface-candidates-comparison-v1 0103 (Accepted (strangler))
Semantic-first: primary semantic map; sources and git — projections; with 0084 on edit session; 0009 for migration 0098 (Proposed)

Full index: adr/README.md.

Document Why
../architecture-migration.md Stepwise migration, phases, strangler status; section “Strategy: lean on target skeleton” (CDS/CCU/DAL/IDS and simplification around MainWindowViewModel)
../MCP-PROTOCOL.md Agent command contracts
../../Features/README.md Features/ slice catalog
../design/onboarding-first-run-v1.md Onboarding and First Run — living blueprint (not ADR); grows with ideas
../design/attention-zone-panel-playbook-v1.md Zone ↔ shell panel ↔ SDK: next step after “this is PFD” (not ADR)
../design/vertical-slice-attention-capabilities-v1.md Vertical slice: register UI surface + dump/test check
../design/north-star-cursor-mcp-cascade-workbench-v1.md “Cursor + MCP + Cascade” boundaries; Cursor transition priority, VS parity — long term; done/remaining matrix (draft)
../design/cds-contract-v0.md CDS in contract sense vs UiLayoutSnapshot; v0 field draft (living blueprint; 0021 §1.1)
../../CascadeIDE.ArchitectureAnalyzers/README.md Roslyn: CASCOPE001/CASCOPE002 — Cockpit/Channels, Cds, Composition without Avalonia / without using Features.UiChrome (0036); CASCOPE003 — P/M intent at MainWindowViewModel without silent assigns outside allowlist (0046); CASCOPE013–016 — IDS (IdeDisplay/) vs cockpit / Avalonia / UiChrome and reverse ban Cockpit → IdeDisplay (0079); CASCOPE019 — IDE Health fold point (0097, 0099)

Versioning of this navigator

  • v1 — original policy with layers and slices in one file.
  • v1.1 — target Features/ catalog, link to architecture-migration; git via IGitCommandRunner.
  • v1.2 — event and UI-thread plan; MEF deferred.
  • v1.3 — policy collapsed into navigator; extended rationale moved to ADR 0006–0009 (and earlier 0001–0005).
  • v1.4 — ADR table: added 0011 (debug: awareness without bottom-panel-only reliance).
  • v1.5 — ADR table: added 0012 (floating workspace chrome).
  • v1.6 — ADR table: added 0013 (command palette, discoverability, minimal toolbar).
  • v1.7 — clarified 0013; added 0014 (situational checklists separate from palette/toolbar).
  • v1.8 — added 0015 (TOML highlighting via TextMate; not LSP in v1).
  • v1.9 — added 0016 (external agent via Agent Client Protocol, stdio, Cursor CLI; PoC accepted).
  • v1.10 — added 0017 (multi-window, agent surfaces; then Proposed — see v1.38).
  • v1.11 — added 0018 (canonical XML docs for IdeCommands/ProtocolDocGen; Proposed).
  • v1.12 — added 0019 (shared Git Core for IDE and git-mcp; Proposed).
  • v1.13 — 0019 accepted; GitMcp.Core in meta-repo open, argv parity for IDE and git-mcp.
  • v1.14 — added 0020 (agent reasoning visibility: L0–L2 layers, honest LLM provider limits; Proposed).
  • v1.15 — ADR table: 0021 (PFD/MFD attention model) and 0022 (AXAML/Blazor visual surface on MFD; Proposed).
  • v1.16 — added 0025 (SDK: capabilities bound to attention zones; Proposed).
  • v1.17 — 0025: native Open/Save vs zone metadata, default policy (native dialog; inline — conscious exception).
  • v1.18 — playbook attention-zone-panel-playbook-v1; 0025: HostAttentionPanelId, CapabilityAttentionConsistency.
  • v1.19 — vertical-slice-attention-capabilities-v1; register ui.chrome.surface.solution_explorer for end-to-end check.
  • v1.20 — added 0026 (Markdown preview: surfaces and TOML); placement UX removed from canon in 0023 (language and diagrams there).
  • v1.20a — added 0069: preview as separate MFD-first tool surface; 0026 superseded for inline/forward_split; Markdown authoring extension orthogonal.
  • v1.20b — added 0070: command palette as direct overlay in active TopLevel; ModalOverlay no longer canonical palette host baseline.
  • v1.21 — added 0027 (small team vs openness maturity: two axes; Proposed).
  • v1.22 — 0027 accepted; minimum discoverability (docs, examples, ADR) + link to onboarding-first-run-v1; axis B backlog triggers.
  • v1.23 — added 0028 (user settings.toml, %LocalAppData%\CascadeIDE\, ai-keys.json; distinct from 0010).
  • v1.24 — added 0029 (TOML-first; UI as facade; TOML-only allowed).
  • v1.25 — 0029: deferred full settings UI (0027); “facade” = rule for point UI and canon.
  • v1.26 — 0029: point UI vs TOML-only motivation (rare single-option visit, ACP).
  • v1.27 — 0029: dynamic UI from model/metadata perspective; point UI = code weight, conscious.
  • v1.28 — 0028: user settings canon — settings.toml; migration from prior format considered complete.
  • v1.29 — 0028: settings.json migration branch removed from SettingsService; ADR and SETUP updated.
  • v1.30 — 0028: API secrets — ai-keys.toml (Tomlyn, like settings.toml); ai-keys.json not used.
  • v1.31 — 0030: command and hotkey layers; v1 registry in IdeCommandRegistry*.cs; blueprint ide-command-registry-v1. ADR status: Implemented.
  • v1.32 — added 0031 (chat: clarification batches, multiline replies, threads optional; Proposed).
  • v1.33 — 0026: intent for internal references in preview (hover/peek “Show Definition” for “see § N” and anchors; orthogonal to 0023).
  • v1.34 — ADR README: internal anchor policy (adrNNNN-pK) and links instead of bare “see § N”; anchors in 0010, 0011, 0012, 0015, 0017, 0021 (§17 item 10 → §18), cross-links in 0022, 0031; phase 5 list anchors in architecture-migration.md.
  • v1.35 — 0017: multi-window v1 not mixed with Power mode rework; Flight vs Power for second window deferred to separate mode roadmap.
  • v1.36 — 0017: Mfd zone vs pages MfdShellPage; not “chat as a zone”.
  • v1.37 — subsection “Documentation and help (intent)”: User Guide / in-IDE help — product layer, not obligation of a single ADR; 0017 remains norm for notation and multi-window.
  • v1.38 — 0017: status Accepted (multi-window, presentation / EBNF, settings.toml layer vs repo workspace).
  • v1.39 — 0017 §8: MfdHostWindow — full MfdShellView only (all MfdShellPage); narrow single-page host not planned.
  • v1.40 — 0017 §5 addendum: primary OS display ≠ semantic Forward; touch-monitor vs “main” display example; OS layout vs presentation — user responsibility.
  • v1.41 — draft goal boundaries “Cursor + MCP + Cascade instead of VS”: north-star-cursor-mcp-cascade-workbench-v1.md.
  • v1.42 — same doc: product vision — attention axis / cockpit / Dark Cockpit vs VS “window cabinet”; not a VS clone, different daily work.
  • v1.43 — north-star: for JetBrains ecosystem, fairer comparison is Rider (not IntelliJ IDEA); differentiation axis unchanged.
  • v1.44 — north-star: explicit CascadeIDE as agent-first IDE (shared loop with human; cockpit does not contradict the axis).
  • v1.45 — north-star: KB / agent memory layer (knowledge canon, MCP read_knowledge_file / …, agent-notes); link to MCP-PROTOCOL.md.
  • v1.46 — added 0032 (HUD: content config and grammar like presentation; Proposed).
  • v1.47 — added 0033 (i18n: ResX/Avalonia; Proposed); cross-link with 0032.
  • v1.48 — 0017: Implementation status section (code alignment: topology, placement, bounds); concept-to-implementation-map-v1 §6 — second TopLevel / MfdHostWindow.
  • v1.49 — added 0034 (operator incapacitation, Emergency Mode, optional presence via webcam MCP; Proposed).
  • v1.50 — chat: 0031 and 0057 aligned to pipeline snapshot, structured clarification flow, single Skia product path without mandatory Avalonia fallback.
  • v1.50 — 0034: contract clarified — EICAS and PIC signals, liveness, contextual HUD, safety interlock; “biometrics” = liveness/presence for safety.
  • v1.51 — 0034: layer A — presence proxy (mouse, keyboard, focus); false positives and signal combination noted.
  • v1.52 — 0034: layer C — eye tracking deferred, not baseline; accessibility (field of view ≠ tracker signal); no mandatory ET.
  • v1.49 — blueprint cds-contract-v0: CDS (cockpit contract) vs UiLayoutSnapshot; 0021 §1.1 — glossary.
  • v1.53 — added 0035 (MFD: WebView2, external web LLMs; MCP boundary; hybrid via operator; web↔MCP bridge outside baseline; Proposed).
  • v1.54 — added 0036 (channel → CDS → compositor → surface; Agent-first; Proposed).
  • v1.55 — 0036: status Accepted; code layers Cockpit/Cds, Cockpit/Channels, Cockpit/Composition, Cockpit/Surface (cds-contract-v0 §6–7).
  • v1.56 — Roslyn analyzer CascadeIDE.ArchitectureAnalyzers: CASCOPE001 / CASCOPE002 (Cockpit layer boundaries per ADR 0036).
  • v1.57 — added 0037 (PFD: weight / input lock / channels; explicit Roslyn markers; Proposed).
  • v1.58 — added 0038 (agent facade: AiProviderManager, chat vs ACP vs autonomous loop, McpClientService; direction draft in same ADR).
  • v1.59 — added 0039 (workspace navigation: not file tree only; multiple views and “related”; Proposed).
  • v1.60 — 0039: product metaphor (cabinet vs battle map), relevance graph, PFD/MFD, semantic map and presentation.
  • v1.61 — 0037: strict surface naming canon — [PfdStrict] / PfdStrictControl (§ naming).
  • v1.62 — 0039: language north-star — C# / .NET, not polyglot IDE; north-star workbench updated.
  • v1.63 — section “Avalonia and cockpit layer”: fuselage (windows, input, editor host) vs CDS/compositor (cockpit semantics); custom draw on host; link 0017 (weight fuse). 0036 §4 clarified; line in cds-contract-v0 §3.
  • v1.64 — added 0040: LSP command line in settings.toml (presets, optional keys; launch_from_environment flag — Proposed).
  • v1.65 — north-star-cursor-mcp-cascade-workbench-v1.md: Cursor transition priority vs VS parity long term; this file — Product focus under Goal.
  • v1.66 — added 0041 (protobuf vs JSON for agent/IDE messages: boundaries, criteria, hybrid; entry point; Proposed).
  • v1.67 — 0039: shipped MCP layer — get_code_navigation_context (presets in settings.toml [code_navigation], merge, kind_filter echo, subgraph: kind / related_kind); cookbook workspace-navigation-mcp-cookbook.md; closed item 5 in closed questions.
  • v1.68 — added 0045: chat persistence as append-only NDJSON + meta/projections; initial ChatSessionStore in Features/Chat/.
  • v1.69 — added 0046: presentation as P/F/M cockpit invariant; CDS rules in CockpitPresentationLayoutPolicy; coercion from menu/MCP/UI modes/reactive layer.
  • v1.70 — added 0047: slot descriptor at compositor → surface boundary; not mixed with Control.
  • v1.71 — 0047: canonical term Instrument (cockpit) and type CockpitInstrumentDescriptor instead of draft Widget / CockpitWidgetDescriptor; ADR file renamed.
  • v1.72 — 0047: status Accepted (term and descriptor axis fixed; registry/wire — roadmap).
  • v1.73 — layer Cockpit/Composition/HostSurface: MainWindowHostSurfaceFrame + compositor (shell + CockpitInstrumentDescriptor); VM builds frame in one call — boundary before Skia in slots, Avalonia as host (cds-contract-v0 §3, §7).
  • v1.74 — Cockpit/Cds/CockpitSurfaceState (schema 0.3) gained instruments as HostSurface frame projection for MCP/observability; added Cockpit/Surface/MainWindowInstrumentMountRegistry (instrument_id → mount, Avalonia/Skia host layer, no semantic map UI on this step).
  • v1.75 — 0046: title, §Decision, indexes aligned to CDS canon (CockpitPresentationLayoutPolicy); static layer in Services/Presentation removed, VM boundary — intent Apply* only.
  • v1.76 — Roslyn CASCOPE003 (CascadeIDE.ArchitectureAnalyzers): ban direct P/M intent assigns outside allowlist; see 0046.
  • v1.77 — added 0049: phased Skia surfaces in CIDE with Avalonia as host; wave migration, dual-path and fallback until stable.
  • v1.78 — ADR index: 0050 (instrument map in TOML), 0051 (intent routing), 0052 (agent contract CLI and snapshot tests).
  • v1.79 — 0052: status Accepted (CLI + snapshot tests direction; no open questions).
  • v1.80 — 0052: first delivery — --agent-contract get_ui_modes_diagnostics, AgentContractRunner, tests; MCP-PROTOCOL §agent contract CLI.
  • v1.81 — adr/status-lifecycle.md: ADR status convention (Accepted · Implemented for shipped code); .cursor/ in repo .gitignore — duplicate locally in Cursor rules if desired. Table row 0051 below — Accepted · Implemented.
  • v1.82 — ADR table above: Accepted · Implemented aligned with ADR headers and adr/README.md for shipped decisions (incl. 0008, 0010, 0015–0017, 0019, 0028–0029, 0036, 0039–0040, 0046–0047).
  • v1.83 — 0053: semantic map and control flow on PFD (branches, KISS, Roslyn CFG, subgraph/MCP); status Accepted · Implemented.
  • v1.84 — added 0054: CIDE benchmark protocol (scenarios, metrics, baseline, comparison rules); status Proposed.
  • v1.85 — added 0058: agent ↔ Roslyn MCP in settings.toml (limits, node kinds, timeouts, presets); consumer table; v0 vs deferred; status Proposed.
  • v1.86 — 0058: §6 — named profiles, Manager, Auto-Focus / Combat / Echelon (then Glide Slope); links 0010, 0051, 0055.
  • v1.87 — 0058: §7 — third monitor as EFB / strategic Profile.GlobalMap vs tactical PFD; 0017, 0021.
  • v1.88 — split: 0058 — TOML keys/axes for MCP coupling only; 0059 — profiles, Manager, modes, EFB (moved from former §6–§7 in 0058).
  • v1.89 — 0059: calm input mode renamed Glide Slope → Echelon (less confusion with ILS glide path).
  • v1.90 — 0059: EFB = MFD, not PFD; hysteresis tactical loop only (§2); EFB static / on intent.
  • v1.91 — added 0060: chord layer and FMS-style (S/T), overlay, MODE indication; extends 0013; Ctrl+K vs palette Ctrl+Q.
  • v1.92 — added 0061: contextual ADR ↔ path map in workspace.toml, PFD indicator, intent/tooltip, agent advisory; status Proposed (implementation deferred).
  • v1.93 — added 0063: instrument deck — named instrument composition in one anchor; distinct from WH Page and v1 [instrument_routing]; status Proposed.
  • v1.94 — 0063: ContentRepresentation axis — canon Strip/Page; WH DedicatedPage — Page mode on this axis; composition axis — deck / WH segment order; blueprint workspace-health-implementation-map-v1 §1.
  • v1.95 — 0063: direction for indicator types in deck — Lamp / Bar / Sign (compact pages; not v1 code contract).
  • v1.96 — 0063: extended primitive taxonomy; Presence/Activity and Dark Cockpit alignment (0021 §6).
  • v1.97 — 0063: status Accepted (terminology instrument deck / ContentRepresentation; display topology keys — 0017 § display.screens / topology).
  • v1.98 — added 0064: deck product primitives — unified graphics; graphics layer (Cockpit/PrimitivesKit); semantic palette and Dark Cockpit; product primitive vs scene tokens; status Accepted.
  • v1.99 — 0064: canon “indicator kind” / signal form; product ↔ code lexicon (DeckPrimitiveKind); render library not “another layer”; no separate runtime tier.
  • v2.00 — added 0065: instrument categories as domain axis (CodeNavigation / WorkspaceNavigation / repo topology); orthogonal to slot and instrument_id; “Semantic map” — graph, not instrument; optional instrument_category in descriptor — as needed; status Accepted.
  • v2.01 — 0065: “Semantic map” narrow sense — code intent map; graph_kind axis (graph type in wire/MCP); minimum value table.
  • v2.02 — added 0066: two pillars — Cockpit UI vs IDE presentation (UiChrome, overlays, theme); invariant — do not mix instrument and shell semantics; status Accepted.
  • v2.03 — 0066: build CASCOPE011 / CASCOPE012 (CascadeIDE.ArchitectureAnalyzers) — using boundary between Features/UiChrome and Cockpit/PrimitivesKit.
  • v2.04 — added 0067: graph-backed surface as architectural class; contract dimensions table (data, interaction, navigation, layout, selection, sync); status Accepted.
  • v2.05 — added 0068: three layers — row payload, slot identity, presentation projection; link 0063; homogeneous DTO in v1 OK; status Accepted.
  • v2.06 — added cascadeide-philosophy-v1 (philosophy reference: DX, “good actor”, cloud inline-assistant risk class) and 0071 (sovereignty/locality/invisibility for AI in IDE; anti-pattern); ADR status Proposed.
  • v2.07 — added 0072: topic cards, drill-in/back, adaptive default view; mandatory v1 intent layer for chat topic navigation (palette / Melody / Chords); links 0031, 0057; refines 0060 in chat domain only; status Proposed.
  • v2.08 — added 0073: PFD instrument deck — variant catalog (SA, code metrics, semantic map, ADR indicator…), placement criteria; Proposed, complements 0021 and 0063.
  • v2.09 — added 0074: settings — more compact, MFD anchor; overflow strategies in P+F+M table; Proposed, 0029 canon unchanged.
  • v2.10 — added 0075: adr/UI as UI topic index; normative ADRs stay in docs/adr/; Proposed.
  • v2.11 — added 0076: UI/UX principles hub — connected text from snippets/ui (attention/cockpit, product philosophy vs “second VS” and cloud inline risk); Proposed; complements 0075 and cascadeide-philosophy-v1.
  • v2.12 — added 0077: TECH principles hub — connected text from snippets/tech (boundaries/contracts/MCP/git/LSP; agent/debug/observability); topic index adr/TECH/README.md, build adr-book-tech.md; Proposed.
  • v2.13 — added 0079: IDS — IDE overlay pipeline (palette and beyond), orthogonal to CDS; unified input capture and slots — strangler; status Accepted; “Where recorded” table updated.
  • v2.14 — 0079: Roslyn CASCOPE013–016 in CascadeIDE.ArchitectureAnalyzers — IdeDisplay/ without Cockpit/Avalonia/UiChrome; Cockpit/ without IdeDisplay; analyzer README and navigator row updated.
  • v2.15 — added 0080: Intercom as product name for communication channel (agent, team, system); open UI/i18n questions; Proposed; navigator table row.
  • v2.16 — 0080: §5 ready-made team loop (integration/API) vs in-house; link 0035 for WebView risk; open question item 5; README index and navigator row clarified.
  • v2.17 — 0080: spelling canon Intercom (one m); ADR file renamed from 0080-intercomm-… to 0080-intercom-…; Intercomm as typo in §4.
  • v2.18 — 0080 future modalities: async voice in thread, expressive TTS (incl. OpenTTS), duplex/“radio” as separate requirement class; no v1 commitment.
  • v2.19 — 0080 future modalities: code anchors (deep link, range, selection) and alternate anchor representation; links 0039, 0067; no v1 commitment.
  • v2.20 — added 0081: parametric Intent Melody with :startLine:endLine suffix for editor text ops; validation; range refactors; UX (indicator, chord vs palette); Proposed; index README, navigator row, UI/README.
  • v2.21 — added 0082: ACP inside IDE — direction to MCP IDE in same process (loopback HTTP/SSE), no second CascadeIDE --mcp-stdio; security; keep external --mcp-stdio; Proposed; index README, TECH/README, navigator row.
  • v2.22 — added 0084: agent edits — single text in editor; chat — intent and status; presence layer (cursor, “typing”) separate; diff in chat not primary; preview/live and risks — in ADR; Proposed; index README, UI/README, TECH/README, principles.md, ui-adr-manifest / tech-adr-manifest, navigator row.
  • v2.23 — 0084 context and risk table: review-only / lead persona lowers frequency of personal-input conflicts; canon for simultaneous edit mitigation not weakened.
  • v2.24 — added 0085: Editor HUD (inline at caret/in text) vs HUD banner (strip above editor); distinct from IDS; Proposed; index README, UI/README, UI/principles.md, ui-adr-manifest, navigator row; cross-ref 0021 §9.
  • v2.25 — added 0086: UI theme — TOML canon (settings.toml), JSON for MCP ide_get/set_ui_theme as wire, strangler Themes/*.json; Proposed; index README, navigator row, tech-adr-manifest.
  • v2.26 — added 0092: Visual UI track (layout designer) as separate major program line; 0022 remains product/UX norm; stack priority Avalonia → Blazor → (opt.) Razor; Accepted; index README, navigator row.
  • v2.27 — added 0093: extension to 0090 — optional embedded Kestrel URL viewer on MFD; external browser default; Proposed; index README, TECH/README, tech-adr-manifest, link from 0090, navigator row.
  • v2.28 — added 0094: UI event delivery bus (AFDX analogy), Channel<T>, batching and backpressure; orthogonal to CDS “channel”; Proposed; index README, TECH/README, tech-adr-manifest, navigator row.
  • v2.29 — added 0095: three Health levels (Workspace / Solution / IDE), taxonomy for channels and MCP; strangler from current IDE Health; Proposed; index README, TECH/README, tech-adr-manifest, navigator row.
  • v2.30 — added 0096: Intercom — topic card summary (card index) and product spine (CIDE example in main repo) orthogonal to main thread; complements 0072; Proposed; index README, navigator row; links in 0072, 0080.
  • v2.31 — added 0097: cockpit compute units (CCU) — fold raw input into channel snapshot/DTO (LRU Unit analogy between bus and indication); orthogonal to 0094 and CDS; Proposed; index README, navigator row; cross-links in 0094, 0095, blueprint workspace-health-implementation-map-v1.md. ADR file renamed from …compute-nodes… to …compute-units… (canon unit, not node).
  • v2.32 — added semantic-first ADR: semantic-first — semantic map primary, code/docs/git — projections; aligned with 0084 on edit session; 0009 for migration; Proposed; index README, TECH/README, tech-adr-manifest, navigator row; hint at future ADR 0100 (separate). (Initially 0099, renumbered to 0098 — v2.33.)
  • v2.33 — 0098 (semantic-first): file and number renamed 0099 → 0098; internal ADR refs and indexes updated.
  • v2.34 — 0097: Accepted · Implemented (CCU reference in IDE Health, CASCOPE019; see 0099); 0099: Accepted · Implemented; navigator row and index README synced.
  • v2.35 — 0103: Editor HUD substrate (projection pipeline, EditorHudEngine, IEditorSurfaceAdapter); DAL 0102 / CCU 0097 / DataBus 0099 boundaries; separate hi-freq bounded path; baseline AvaloniaEdit; companions editor-surface-candidates-comparison-v1, editor-forward-ui-cleanup-roadmap-v1; Proposed; index README, navigator row.
  • v2.36 — 0103 and companion design/ / ui-ux/: canonical Russian text; ADR title, sections, tables without English body; index and navigator row clarified (“substrate”).
  • v2.37 — 0103: status Accepted (strangler); “Implementation status” subsection; index README, navigator row.
  • v2.38 — 0079: subsection “Distinguishing CDS and IDS (one app, two domains)” (table, mnemonic, CASCOPE016); navigator — CDS vs IDS subsection with anchor adr0079-cds-vs-ids.
  • Direction changes — separate commit: update this file and new ADR in adr/README.md when needed.