From 98835b3894c28511cb27fb5246a967a7f8028d06 Mon Sep 17 00:00:00 2001 From: Wilielmus <88447902+WilliamKarolDiCioccio@users.noreply.github.com> Date: Fri, 9 Oct 2026 18:49:05 +0200 Subject: [PATCH] docs: ADR index and template, and bring stale decision records up to date MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/adr/README.md: when to write an ADR, an index, the status vocabulary, how to amend or supersede, and a template matching the existing records. - ADR-003: Accepted, since it shipped in #428 and #430. Its in-place "since superseded" note becomes a dated amendment by #536, and §4 no longer claims runSoliplexShell is unchanged. - The app-shell proposal is marked partly superseded: ModuleContribution gave way to AppModule (#172), and flavor functions to the Flavor object. - developer-setup: drop the GIT_LFS_SKIP_SMUDGE step. ag_ui has been a hosted package since d8dac7e9, and CI no longer sets the variable. - AGENTS.md: list the ADRs and the docs it was missing. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 6 +- docs/adr/ADR-003-flavor-object.md | 12 ++-- docs/adr/README.md | 91 +++++++++++++++++++++++++++ docs/developer-setup.md | 10 --- docs/plans/0001-app-shell/proposal.md | 9 +++ 5 files changed, 112 insertions(+), 16 deletions(-) create mode 100644 docs/adr/README.md diff --git a/AGENTS.md b/AGENTS.md index 38d3716fc..133e75e79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -151,7 +151,11 @@ gitignored. See `docs/developer-setup.md` for full setup. ## Key Documentation +- `docs/adr/` -- Architecture Decision Records; start at `docs/adr/README.md` - `docs/developer-setup.md` -- Platform-specific build instructions +- `docs/authoring-a-flavor.md` -- Building a whitelabel flavor +- `docs/diagnostics-known-risks.md` -- Known risks of the diagnostics screen +- `docs/refreshing-backend-schema-snapshots.md` -- Refreshing the haiku.rag schema snapshots - `docs/send-cancel-lifecycle.md` -- Message send/cancel state machine -- `docs/plans/0001-app-shell/proposal.md` -- Shell architecture design +- `docs/plans/0001-app-shell/proposal.md` -- Original shell plan (historical; partly superseded) - `docs/plans/citations-ui/` -- Citations feature design and data flow diff --git a/docs/adr/ADR-003-flavor-object.md b/docs/adr/ADR-003-flavor-object.md index f0dd9c0fd..e5bbd5374 100644 --- a/docs/adr/ADR-003-flavor-object.md +++ b/docs/adr/ADR-003-flavor-object.md @@ -1,12 +1,13 @@ # ADR-003: Reify the Flavor — a Declaration Object Between Composition and Boot -- **Status:** Proposed +- **Status:** Accepted (implemented in #428 and #430) - **Date:** 2026-07-16 - **Authors:** William Karol Di Cioccio - **Supersedes:** — - **Amends:** ADR-002 §2 (barrel-boundary change shipped in #426) and §3.9/§5.2 (link contrast policy) - **Superseded by:** — +- **Amended by:** #536 (`runSoliplexShell` takes a builder; §2, §4) --- @@ -156,9 +157,9 @@ final flavor = await standardFlavor( runSoliplexShell(flavor.build()); ``` -> Since superseded: `runSoliplexShell` takes the builder — `await -> runSoliplexShell(flavor.build)` — so a configuration failure reaches the -> screen rather than stalling the launch. The rest of this record stands. +> **Amended by #536 (2026-09-02):** `runSoliplexShell` takes the builder — +> `await runSoliplexShell(flavor.build)` — so a configuration failure reaches +> the screen rather than stalling the launch. The rest of this record stands. --- @@ -225,7 +226,8 @@ construction, failing even earlier with the same message. Deferred until the sits on top of it, not instead of it. (This change renames #426's `StandardModules` / `buildStandardModules` to `StandardKit` / `buildStandardKit` and relocates it beside `standard.dart`; §6.) -- `runSoliplexShell(ShellConfig)` and the shell widget tree. +- The shell widget tree. (`runSoliplexShell` itself changed later: it takes + a `ShellConfig` builder since #536; see §2.) - The shipped Soliplex app's behavior, byte for byte. --- diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 000000000..669ef485b --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,91 @@ +# Architecture Decision Records + +An ADR records one decision that is costly to reverse: the context, what +was decided, what was rejected and why, and what it costs. Write one when a +change does any of the following: + +- binds people outside this repo: forks consuming the library, the backend + team, deployers or IdP operators; +- sets a rule every contributor must follow, such as a layering rule, a + logging rule or a state-management idiom; +- has security impact; +- settles something that has been rewritten or argued about more than once. + +A rule in `CLAUDE.md` says *what* to do. The ADR behind it says *why*, so +that the rule can be changed deliberately rather than eroded. + +## Index + +| ADR | Title | Status | Date | +| --- | ----- | ------ | ---- | +| [ADR-001](ADR-001-reactive-state-management-scoped-statebus.md) | Reactive state management via scoped `StateBus` and ownership-based discovery | Accepted | 2026-04-28 | +| [ADR-002](ADR-002-customizable-brand-theme.md) | Customizable `BrandTheme` via a façade and a lowering buffer | Accepted, amended by ADR-003 §1.3 | 2026-06-24 | +| [ADR-003](ADR-003-flavor-object.md) | Reify the `Flavor`: a declaration object between composition and boot | Accepted, amended by #536 | 2026-07-16 | + +The repo-wide rule "Riverpod is DI only; signals carry state" is argued in +ADR-001 §5.3, among the rejected alternatives. + +## Conventions + +- **File name.** `ADR-NNN-kebab-case-title.md`, three-digit and sequential. + Numbers are never reused. +- **Status.** + - `Proposed`: under discussion, not yet in code. + - `Accepted`: decided, and the code follows it. + - `Superseded`: replaced by a later ADR, linked in `Superseded by`. + - `Deprecated`: no longer applies and not replaced. + + Move an ADR to `Accepted` in the PR that implements it. +- **Changing an accepted ADR.** + - Do not rewrite the decision. For a narrower change, add a dated + `> **Amended by (YYYY-MM-DD):** ...` note at the affected + section, and list it in the header's `Amended by`. + - When the change reverses the decision, write a new ADR and mark the old + one `Superseded`. +- **Scope.** One decision per ADR. A record that settles several independent + axes should list them in a "Decisions by axis" section, or be split. +- **Update this index** in the same PR that adds or changes an ADR's status. + +## Template + +```markdown +# ADR-NNN: + +- **Status:** Proposed +- **Date:** YYYY-MM-DD +- **Authors:** +- **Supersedes:** — +- **Superseded by:** — +- **Amends:** — + +--- + +## 1. Context and Problem Statement + +What forces the decision. Cite code paths, issues and PRs. + +## 2. Decision + +The decision in a few sentences, plus a sketch or code shape if it helps. + +## 3. The Decisions, by Axis + +Optional. One subsection per independent sub-decision, each with its reason. + +## 4. Consequences + +What gets easier, what gets harder, and who is bound (forks, backend, +deployers, contributors). Name how the decision is enforced: a test, a lint, +a CI check, or review only. + +## 5. Known Limitations and Open Questions + +## 6. Migration + +Omit for a retroactive record of a decision already in code. + +## 7. Alternatives Considered + +| Alternative | Why rejected | +| ----------- | ------------ | +``` diff --git a/docs/developer-setup.md b/docs/developer-setup.md index 9f704c9ca..1a60de1bb 100644 --- a/docs/developer-setup.md +++ b/docs/developer-setup.md @@ -36,12 +36,6 @@ Using VS Code, and the analyzer disagrees with the pin? See **Troubleshooting**. ## Quick Start ```bash -# The ag_ui dependency is fetched from a Git LFS-enabled repo whose -# binary assets we don't use, and one of its LFS objects is missing -# upstream — which aborts the clone during pub get. We need only its -# pure Dart sources (not LFS-tracked), so skip the LFS smudge filter: -export GIT_LFS_SKIP_SMUDGE=1 - # Install dependencies flutter pub get @@ -49,10 +43,6 @@ flutter pub get flutter run -d macos # or: -d ios, -d chrome, -d android ``` -Add `export GIT_LFS_SKIP_SMUDGE=1` to your shell profile (`~/.zshrc`, -`~/.bashrc`) so it persists. CI sets this automatically for its -`pub get` step. - ## Platform Setup ### macOS diff --git a/docs/plans/0001-app-shell/proposal.md b/docs/plans/0001-app-shell/proposal.md index e6100f956..7a5db5b70 100644 --- a/docs/plans/0001-app-shell/proposal.md +++ b/docs/plans/0001-app-shell/proposal.md @@ -4,6 +4,15 @@ **Date:** 2026-03-11 **Branch:** `feat/shell-core` +> **Partly superseded.** This is a historical plan, not the current design. +> `ModuleContribution` and "no base class, no registry" (decision 2) were +> replaced by the `AppModule` lifecycle in #172. Flavor functions were +> replaced by the `Flavor` declaration object +> ([ADR-003](../../adr/ADR-003-flavor-object.md)). Riverpod-as-DI and +> signals (decisions 3 and 4) stand, and are the subject of +> [ADR-001](../../adr/ADR-001-reactive-state-management-scoped-statebus.md). +> For the current architecture see `CLAUDE.md` and `docs/adr/`. + ## Context The old `soliplex_frontend` is a white-label Flutter app configured via