jpmschweitzerandClaude Opus 4.8
1db65f8481
Documents why the markdown/decisions readers load from a retained per-reader nav-history (grab-current-on-mount + single 'load' path) rather than per-view state (dies with the widget — the T-196 bug) or MessageBus retention (wrong layer). The user chose the nav-history helper over a bus fix. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 decisionsquestions/<domain>.md— open questions that may resolve into decisions or rejected proposalsrejected/<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 softwaresecurity— if you handle user data or network surfaceslicensing— if you release open-source or commercialdocumentation— if user-docs are non-trivialdeployment— if shipping is non-trivialperformance— 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;
ptycas 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 — mocktail at IO, hand-rolled fakes for ChangeNotifiers — testing
- D-26: Web driver — raw Playwright + Flutter semantics — testing
- D-27: Startup regression gate — testing
- D-28: Test organisation — mirror
lib/intest/— 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 — Gitea primary, Linux-only runners, not yet activated — 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.readallows 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
Open questions
- Q-1: Authorisation granularity on the IPC socket — architecture
- Q-2: Back-pressure on event streams — architecture
- Q-3: Event persistence + audit/undo — architecture
- Q-4:
.canvasschema 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-dartgrammar 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-23: SSH-remote development — run clide against a remote workspace — architecture
- 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-28: Terminal strip scope — shell only or logs/errors/tests — 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-32: MCP tool surface — minimum slash-ide or extended clide tools? — architecture
- Q-33: MCP transport — SSE, WebSocket, stdio, or all? — architecture
Resolved questions
- 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
Rejected
- R-2: Go sidecar — architecture
- R-3:
MaterialApproot — 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:
CupertinoApproot — 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