jpmschweitzer/clide

Files

T

jpmschweitzer 75f378ff20 chore(governance): Add D-105 to decision index in README.md

Auto-generated by pql when creating decisions/llm.md.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

2026-06-28 22:18:53 +02:00

26 KiB

Raw Blame History

Decisions, Questions, Rejected

This directory holds structured planning records that pql parses into pql.db. Each record is a ### [DQR]-N: Title heading inside a markdown file. Files live in three per-type subdirectories:

decisions/<domain>.md — confirmed design decisions
questions/<domain>.md — open questions that may resolve into decisions or rejected proposals
rejected/<domain>.md — rejected proposals (kept for the audit trail)

The parser infers domain from the filename stem and record type from the parent subdirectory.

D-records that propose implementation work link to initiative-type tickets via decision_ref. Run pql decisions show <id> --with-tickets to inspect implementation status.

Recommended domains

Start with this canonical set; create files as records land in each domain:

architecture — structural commitments (storage, layering, languages, libraries)
process — team workflow (commits, branches, releases, reviews)
design — user-facing surface (UX, UI, public APIs)
coding-conventions — team-internal code shape (style, lint, file layout)
testing — quality strategy (coverage, layers, gates)

You might also want, project-permitting:

accessibility — if you ship user-facing software
security — if you handle user data or network surfaces
licensing — if you release open-source or commercial
documentation — if user-docs are non-trivial
deployment — if shipping is non-trivial
performance — if you have perf budgets / SLOs

Decisions

D-1: CLI-first, not MCP — architecture
D-3: pql as supporter tool; clide wraps, never duplicates — architecture
D-4: Ignore file strategy — architecture
D-5: Dart core; sidecar dissolved; ptyc as pql-peer — architecture
D-6: CLI and event surface contract — architecture
D-7: App root is bare WidgetsApp — architecture
D-8: Feature-first folder layout — architecture
D-9: Three-tier theme pipeline — architecture
D-10: State management — ChangeNotifier + ListenableBuilder — architecture
D-11: Panel manager is kernel; layout is data; three-column is a preset — architecture
D-12: Kernel admission rule — mandatory shared singletons only — architecture
D-13: Git hardcoded in kernel project-loader — architecture
D-14: Two-tier disable — kernel locked, everything else extension-shaped — architecture
D-15: Extension grain — container-level, multi-contribution — extensions
D-16: Built-ins in Dart, third-party in sandboxed Lua — extensions
D-17: Panels are extension-shaped from day one — extensions
D-18: YAML for themes + manifests; JSON for i18n catalogs — extensions
D-19: Lua runtime as ptyc-peer supporter tool — extensions
D-20: A11y is a Tier-0 contract — accessibility
D-21: i18n is a Tier-0 contract (fframe pattern + locale-fallback chain) — accessibility
D-22: WCAG-AA contrast gate on bundled themes — accessibility
D-23: Test pyramid — seven layers — testing
D-24: Golden tests — primitives only, Alchemist + Ahem — testing
D-25: Mocks — hand-rolled fakes throughout; mocktail dropped — testing
D-26: Web driver — raw Playwright + Flutter semantics — testing
D-27: Startup regression gate — testing
D-28: Test organisation — mirror lib/ in test/ — testing
D-29: Pre-push gate — fast layer only — testing
D-30: Tests are client-side only — testing
D-31: Prefer-zero-deps, exact-pin — tooling
D-32: CI — GitHub Actions, Linux + Windows runners, active — tooling
D-33: Golden-output ignore pattern — coverage.* excludes output, not scripts — tooling
D-34: Q&D record system — process
D-35: Kanban / waterfall, not Scrum — process
D-36: .claude/ is committed project surface, managed through the IDE — process
D-37: Commit conventions per git-commit skill — process
D-38: Changelog discipline — Keep a Changelog 1.1.0 — process
D-39: Planning tooling lives in pql, not clide — process
D-40: [SUPERSEDED] Python stopgap under tools/scripts/plan — process
D-41: Claude panes — one primary per repo, tmux-backed — architecture
D-42: Dependencies documented in licenses.yaml — tooling
D-43: Design handoff — adopt token palettes, reject Material wrapper — architecture
D-44: Four bundled themes — clide, midnight, paper, terminal — architecture
D-45: Syntax highlighting tokens in the theme pipeline — architecture
D-46: Core frame builtins vs shipped extensions boundary — extensions
D-47: Interaction model — Claude-is-home layout — architecture
D-48: Chrome budget — no tabs, no breadcrumbs, keyboard-first — architecture
D-49: Editor mode — inline above Claude, viewer swap — architecture
D-50: Context auto-behavior — right panel reacts to Claude — architecture
D-51: Panel collapse — 12px spine with badge — architecture
D-52: Focus mode — full-window takeover — architecture
D-53: State persistence across sessions — architecture
D-54: Keyboard map — canonical shortcuts — architecture
D-55: Claude pane internal tabs for multi-session — architecture
D-56: Dissolve daemon process; Flutter app hosts IPC server — architecture
D-57: Frameless custom chrome with per-column 24px hats — architecture
D-58: Format engines are adoptable dependencies — tooling
D-59: Bundled git via dugite-native — tooling
D-60: No network on default launch path — tooling
D-61: Dependency vetting checklist — tooling
D-62: Dependency removal process — tooling
D-63: Vendored binary rebuild process — tooling
D-64: No telemetry — architectural commitment — architecture
D-65: License compatibility matrix — tooling
D-66: Line coverage gate at 95%, ratcheted from current — testing
D-67: Pql changelog files are committed alongside code — process
D-68: Dual integration surface — Bash CLI primary, MCP secondary — architecture
D-69: published themes are user contracts; ship -hc variants for a11y — accessibility
D-70: IPC socket path is per-workspace, deterministic — architecture
D-71: IPC socket access gated by chmod 0600 on socket + parent — architecture
D-72: IPC server is multi-connection with serial dispatch on the main isolate — architecture
D-73: MCP transport for /ide is SSE over HTTP — architecture
D-74: IPC command schema is co-registered with the handler, validated at dispatch — architecture
D-75: Claude rendered natively from transcripts; terminal retained as general tool only — architecture
D-76: ClaudeConfig — Claude's config surface is clide's app settings (builtin-owned, watched, probe-cached per version) — architecture
D-77: Drive Claude via the stream-json control protocol; teams become a clide-owned coordination layer — architecture
D-78: Claude permission/prompt transport is the stdio control channel — architecture
D-79: Workspace content search is a pure-Dart in-process engine, outside pql — architecture
D-80: files.read allows trusted Claude config roots beyond the workspace — architecture
D-81: Right-pane reader load is driven by a retained ReaderNav, not per-view state or bus retention — architecture
D-82: Keymap sequences are space-separated; matching is a reusable matcher consumed at the interception point — architecture
D-83: Dogfood agent model — hosted stream-json session primary, external CLI driver secondary — architecture
D-84: Diff view placement — editor-mode inline above Claude, spawned from the git sidebar — architecture
D-85: Event bus delivery — bounded ring-buffer back-pressure; in-memory cursor retention, bus-owned if persisted — architecture
D-86: MCP tool surface — full clide namespace generated from the co-registered command registry — architecture
D-87: Output/log dock — bottom, toggled, read-only (logs + problems) — architecture
D-88: clide-owned anchored popover + menu primitive — design
D-89: inline pasted-image thumbnails that expand to the lightbox — design
D-90: clide:// deep links — paranoid allowlist + user confirmation — architecture
D-91: Unified conversation drawing card backed by a canvas renderer — architecture
D-92: Ship pql bundled with clide — tooling
D-93: clide writes no directories of its own into the workspace — architecture
D-94: Workspace mode is a first-class, extensible declared capability — architecture
D-95: Workspace validity and onboarding flow — architecture
D-96: Remote-execution footprint — no-install ssh-exec — architecture
D-97: ssh:// workspace URI + system-ssh auth — architecture
D-98: Remote-tool contract + connect preflight — architecture
D-99: Remote session identity keyed on (host, workspace) — architecture
D-100: Fence dart:ffi behind conditional imports + web stubs to keep the web/WASM target compiling — tooling
D-101: ClideSettings — one live-preferences access facade — architecture
D-102: i18n routing — ext-id namespaces, core catalog, ClideSettings.i18n facade, contribution keys — accessibility
D-103: Drawing-card primitive layer is SVG; the SVG renderer is the engine — architecture
D-104: Explicit supporter-binary path overrides in user-scope settings — tooling
D-105: Support Vibe CLI as opt-in alternative to Claude Code CLI — llm

Open questions

Q-1: Authorisation granularity on the IPC socket — architecture
Q-4: .canvas schema compatibility with Obsidian — architecture
Q-5: IPC wire-format stability + schema_version: — architecture
Q-7: macOS app bundle signing / notarisation — architecture
Q-8: Extension API shape — widgets, subcommands, both? — extensions
Q-9: Lua runtime vendoring — extensions
Q-10: Extension manifest schema_version: — extensions
Q-11: Coverage gates — hard thresholds vs soft reporting — testing
Q-12: Screen-reader automation (axe-core via Playwright) — testing
Q-13: Web production-mode a11y — accessibility
Q-14: i18n plurals / gender / date-format tooling — accessibility
Q-15: Editor tab — full LSP vs tree-sitter-only highlight — process
Q-16: tree-sitter-dart grammar maintenance — process
Q-17: Icon set growth — process
Q-18: Theme hot-reload in release builds — process
Q-20: Kernel DB service — namespaced SQL access? — process
Q-25: Body text face — mono everywhere vs Josefin Sans UI + mono code — architecture
Q-26: Small screen layout (< 1000px) — architecture
Q-27: Two-editor split — architecture
Q-29: Branch picker location — architecture
Q-30: Focus behavior when editor is dirty and viewer is peeked — architecture
Q-31: XWayland fallback for frameless — proper Wayland protocol needed — architecture
Q-34: How + when to surface the account/team token budget given upstream doesn't expose it — architecture
Q-35: Agent Blame + Session Flight Recorder — implement? — design
Q-36: Context X-ray — implement? — design
Q-37: Trust Ledger + decision-aware permission prompts — implement? — design
Q-38: Agent Activity HUD — implement? — design
Q-39: Active Ticket Context — implement? — design
Q-40: Twin-timeline rewind — implement? — design
Q-41: Visual Dialog — one bidirectional scene schema — implement? — design
Q-42: Immortal terminals — implement? — design
Q-43: Local cost ledger — implement? — design
Q-44: Label-routed work queues / ticket dispatch — implement? — design
Q-45: Semantic terminal — implement? — design
Q-46: Living codebase map — implement? — design
Q-47: Live mixed documents — implement? — design
Q-48: Sealed-workspace mode — implement? — design
Q-49: Review honorable mentions — which, if any, get promoted? — design
Q-51: Unify workspace lifecycle on a single fenced open primitive — architecture

Resolved questions

Q-2: Back-pressure on event streams — architecture
Q-3: Event persistence + audit/undo — architecture
Q-6: Window chrome — native frame vs frameless custom — architecture
Q-19: (withdrawn) — process
Q-21: Pql absorbs planning vs keeps separate — architecture
Q-22: Ticket persistence strategy — architecture
Q-23: SSH-remote development — run clide against a remote workspace — architecture
Q-28: Terminal strip scope — shell only or logs/errors/tests — architecture
Q-32: MCP tool surface — minimum slash-ide or extended clide tools? — architecture
Q-33: MCP transport — SSE, WebSocket, stdio, or all? — architecture
Q-50: Web/WASM target after the dart:ffi pivot — fence, fix, or drop? — architecture

Rejected

R-2: Go sidecar — architecture
R-3: MaterialApp root — architecture
R-4: Flutter intl + ARB codegen for i18n — accessibility
R-5: Patrol test runner — testing
R-6: Nerd-font glyph icons — process
R-7: CupertinoApp root — architecture
R-8: Riverpod / Provider / BLoC for state — architecture
R-9: Port planning tooling into clide — process
R-10: Python-script stopgap under tooling/db/ — process
R-11: Permanent stopgap — process
R-12: MaterialApp wrapper from design handoff — architecture