groundwork-method 0.10.0 → 0.11.0

package/src/engineer-skills/groundwork-electron-engineer/references/documentation.md

@@ -0,0 +1,126 @@
+# Documentation
+
+## Table of Contents
+- [Hierarchy](#hierarchy)
+- [The Contract Type Is the Surface Documentation](#the-contract-type-is-the-surface-documentation)
+- [TSDoc on the Bridge Contract](#tsdoc-on-the-bridge-contract)
+- [The Process Boundary Documents Itself](#the-process-boundary-documents-itself)
+- [Why-Comments on Security Policy](#why-comments-on-security-policy)
+- [Inline Comments](#inline-comments)
+- [A Comment Is Often a Smell](#a-comment-is-often-a-smell)
+- [In-Code Markers](#in-code-markers)
+- [What NOT to Document](#what-not-to-document)
+
+---
+
+A desktop shell has a documentation problem the web app does not: the same TypeScript runs in three processes at three privilege levels, and a reader must know which one a file belongs to before a single line makes sense. The architecture answers that in structure — the folder boundary, the shared contract, the typed bridge — so the documentation is mostly the code's shape, not prose around it.
+
+## Hierarchy
+
+Structure documents more reliably than comments. A comment is a promise no compiler checks, and a stale comment about *which process runs this* is worse than none — it misleads about a security boundary. Documentation priority — the foundations principle (`docs/principles/foundations/documentation.md`) written the Electron way:
+
+1. **Types and the shared contract** — `IpcContract`/`RendererApi` in `src/shared/ipc.ts`; a drifted signature is a compile error in both processes (`references/ipc-contracts.md`).
+2. **The folder boundary** — `main/`, `preload/`, `renderer/`, `shared/` declare where code runs; lint and two tsconfigs enforce it (`references/process-model.md`).
+3. **Zod schemas at the trust boundary** — runtime-checked validation that documents the accepted payload and flows into errors.
+4. **Test names** — a smoke or unit test named for its behaviour is executable documentation verified by CI.
+5. **TSDoc on the bridge and security policy** — written only where types and structure cannot carry the intent.
+6. **Inline "why" comments** — last resort for a genuinely non-obvious decision.
+
+Levels 1–4 are verified by tooling. Levels 5–6 are human promises that drift. Minimise them.
+
+## The Contract Type Is the Surface Documentation
+
+`src/shared/ipc.ts` is the single document of what the renderer may ask the privileged side to do. `IpcContract` enumerates every channel; `RendererApi` is the capability surface the UI sees. Read together they are the complete, compiler-verified description of the trust boundary — no prose inventory of "available IPC calls" stays as accurate, because this one fails the build when it lies.
+
+```ts
+// src/shared/ipc.ts — the surface, documented by its types
+export type RendererApi = {
+  openProject: (path: string) => Promise<ProjectSummary>;
+  onProjectChanged: (cb: () => void) => () => void;
+};
+```
+
+The naming carries the documentation: bridge methods name **capabilities** (`openProject`), never transport (`invoke`, `send`). A method called `invoke` documents nothing about what crosses the seam (`references/ipc-contracts.md`).
+
+## TSDoc on the Bridge Contract
+
+Most channels are self-documenting through their contract types. Add TSDoc only where a method carries a consequence the signature cannot — a privileged side effect, a security implication, an OS interaction the caller must understand:
+
+```ts
+export type RendererApi = {
+  /**
+   * Opens a path in the OS file manager. Main validates it is inside an
+   * allowed root before the shell call — a renderer cannot open arbitrary
+   * paths. Rejects if the path escapes the sandboxed roots.
+   */
+  openInFileManager: (path: string) => Promise<void>;
+};
+```
+
+The note documents the trust decision, not the mechanics. A plain `getStatus(): Promise<AppStatus>` needs nothing — the name and return type are the whole contract.
+
+## The Process Boundary Documents Itself
+
+The folder a file lives in is its most important documentation: it declares the privilege level and what the file may import (`references/process-model.md`). That boundary is physical and enforced — `no-restricted-imports` fails the build when `renderer/` or `shared/` imports `electron` or a Node built-in, and the two tsconfigs reject a renderer file touching `process` or a main file touching `document`.
+
+This is why a comment like `// runs in the renderer, no Node here` is a smell: the folder already says it, the lint already enforces it, and the comment will outlive the file's move to another directory. Trust the structure. When a file's process is genuinely ambiguous, the fix is to move it to the right folder, not to annotate it.
+
+`src/shared/` documents a stronger rule by what it contains: types only, no runtime behaviour. A function body in a shared file silently drags Node-flavoured code toward the sandbox — the absence of runtime code there is itself the contract (`references/process-model.md`).
+
+## Why-Comments on Security Policy
+
+Security configuration is the one place inline prose earns its keep, because the *reason* a setting holds is invisible in the value and dangerous to guess at. A future reader tempted to loosen a policy must find the threat model next to the line:
+
+```ts
+// sandbox + contextIsolation are non-negotiable: the renderer loads UI
+// that can be XSS'd; without these, an injection reaches Node and the OS.
+webPreferences: { sandbox: true, contextIsolation: true, nodeIntegration: false },
+
+// CSP forbids connect-src: the renderer fetches nothing directly — core
+// calls go through main over IPC, which holds the credentials.
+```
+
+Keep `src/main/policy.ts` a pure module so the rules are unit-tested rather than narrated (`references/process-model.md`). The test documents the policy's behaviour; the comment documents only the threat the test cannot express.
+
+## Inline Comments
+
+Inline comments explain **why**, never **what**. In a handler, the validation and delegation are visible; the comment captures the reason.
+
+```ts
+ipcMain.handle('project:open', async (event, rawPath: unknown) => {
+  assertTrustedSender(event, devServerUrl); // reject navigated-away frames
+  const path = openProjectPayload.parse(rawPath);
+  return openProject(path);
+});
+```
+
+A comment narrating the obvious is noise — the reader can see the `parse` call.
+
+## A Comment Is Often a Smell
+
+When you reach for a comment to explain *what* a block does, the code is asking to be refactored:
+
+- A comment naming which process a file runs in → move it to the right folder.
+- A comment explaining a generic `invoke(channel, ...)` passthrough → name the capability; the passthrough is itself an anti-pattern (`references/ipc-contracts.md`).
+- A comment decoding an untyped channel string → add it to `IpcContract`.
+- A comment summarising what a handler does → the handler does too much; delegate to a named function in main.
+
+Delete the comment and fix the code. The refactor cannot drift; the comment can.
+
+## In-Code Markers
+
+```ts
+// TODO(bob): move indexing to a utilityProcess once payloads grow. Issue #231.
+// FIXME(carol): unsubscribe leak when a window closes mid-stream. Issue #245.
+// HACK(dave): re-assert CSP after a dev-only HMR reload until upstream fix.
+```
+
+Always include `(username)` and an issue reference. A marker without one will never be resolved.
+
+## What NOT to Document
+
+- Channels whose contract type and capability name tell the whole story.
+- Which process a file runs in — the folder and the lint already say it.
+- Boilerplate window construction — the hardened `webPreferences` quartet is the documented standard (`references/process-model.md`), not a per-window note.
+- TanStack Query `queryFn`s that call the typed bridge — the types are the contract.
+- Generated or framework code — never hand-edit comments into it.

package/src/engineer-skills/groundwork-electron-engineer/references/observability.md

@@ -0,0 +1,37 @@
+# Observability
+
+An Electron app has two processes and no backend span surface. Distributed tracing lives at the capability core — the services the app talks to — which is why trace-assertions are N/A for the desktop shell (`references/testing-and-smoke.md`). The shell's observability job is **crash reporting and structured logs across the main/renderer boundary**, plus update telemetry. Instrument for the questions you will ask when a user reports a crash you cannot reproduce; the discipline is the framework canon adapted to a binary running on someone else's machine (`docs/principles/quality/observability.md`).
+
+## Crash Reporting — Both Processes
+
+Two signals, both required, because they catch different failures:
+
+- **Native crashes.** Electron's built-in `crashReporter` (Crashpad) captures native crashes in main and renderer and uploads minidumps. Start it in main *before* `app` is ready — a reporter started late misses the early crash.
+- **JS exceptions.** A sink (Sentry-for-Electron shape) captures uncaught JS in both processes — main's `process.on('uncaughtException')`/`'unhandledRejection'` and the renderer's `window` handlers. A native crash and a JS exception are different events; you need both wired.
+
+## Structured Logs Across the Process Boundary
+
+- **Main-process logging** goes to a rotating file sink (electron-log shape) as JSON, severity-tagged. Main has no devtools console, so an unstructured main log is invisible in the field.
+- **Renderer errors forward to main** over IPC, so a single log stream reconstructs an incident that spans both processes. An error that lands only in the renderer devtools is gone the moment the window closes.
+- Tag every line with the process (`main`/`renderer`) and a session id, so a multi-process incident reads as one timeline.
+
+## App and Update Telemetry
+
+`autoUpdater` lifecycle events — update available, downloaded, applied, failed — are the signal for whether the fleet is actually on the new build. A silent update failure strands users on an old version with nothing to alert on, the desktop equivalent of a botched rollout. Carry app version, OS, and channel as context on every event.
+
+## What to Capture vs PII
+
+- **Capture** process, session id, error type and stack, app/OS/channel version, and update events.
+- **Never** log tokens, file paths containing usernames, or PII into logs, crash context, or minidumps. The upload is third-party — redact at the edge.
+
+## Where Distributed Tracing Lives
+
+The end-to-end request trace belongs to the services the app calls and is asserted at the capability core. The shell does not emit spans; it correlates by attaching a request id it can log on both sides of the IPC boundary.
+
+## Anti-Patterns
+
+- **`console.log` in main.** There is no console to read in the field — log structured to the sink.
+- **Renderer errors that never cross to main.** Lost when the window closes.
+- **A late `crashReporter`.** Started after `app` ready, it misses the crashes that happen at startup.
+- **A collector in the shell.** The app reports to a sink; it does not run backend OTel infrastructure.
+- **PII in logs or minidumps.** Usernames in paths and tokens in context follow the upload off-machine.

package/src/engineer-skills/groundwork-electron-engineer/references/performance-and-reliability.md

@@ -0,0 +1,80 @@
+# Performance & Reliability
+
+## Table of Contents
+- [Where a Desktop App Spends Its Budget](#where-a-desktop-app-spends-its-budget)
+- [The Main Process Is Never Blocked](#the-main-process-is-never-blocked)
+- [Renderer Performance Is Web Performance](#renderer-performance-is-web-performance)
+- [IPC Efficiency](#ipc-efficiency)
+- [Memory Across Long-Lived Windows](#memory-across-long-lived-windows)
+- [Cold Boot](#cold-boot)
+- [Reliability of the IPC Layer](#reliability-of-the-ipc-layer)
+- [A Backend That Is Unreachable](#a-backend-that-is-unreachable)
+- [What Lives in the Core, Not Here](#what-lives-in-the-core-not-here)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## Where a Desktop App Spends Its Budget
+
+Performance is a budget spent deliberately, allocated top-down and measured at the tail, not the average (`docs/principles/quality/performance.md`). A desktop shell spends it across three surfaces with different failure modes: the **main process**, where blocking work freezes every window at once; the **renderer**, which is a web app and pays the web's bundle and frame costs; and the **bridge** between them, where a chatty IPC pattern turns a cheap call into a per-frame tax. The process boundaries that contain these costs are the process-model's subject (`references/process-model.md`); this is the performance and reliability lens on them.
+
+## The Main Process Is Never Blocked
+
+One main process serves every window. A synchronous parse, hash, or file walk on it freezes all of them simultaneously — there is no per-window isolation to fall back on (`references/process-model.md`). The test for any main-process code is the one the process model states: **can this take longer than a frame?** Reading a config file or registering a handler — no, main is fine. Parsing a large file, indexing, image work — yes, and it goes to a `utilityProcess` with its ports wired renderer↔utility directly so the heavy traffic never transits or blocks main (`references/process-model.md`).
+
+`sendSync` over IPC is forbidden for the same reason from the other side: it blocks the renderer's event loop for the full round trip (`references/ipc-contracts.md`). Every privileged call is an async `invoke`.
+
+## Renderer Performance Is Web Performance
+
+The renderer is a normal Vite + React app, so the web stack's performance discipline applies unchanged: lazy-load routes and heavy components behind code-split boundaries, keep the bundle lean, and gate deterministic budgets — bundle size, not noisy wall-clock — in CI (`docs/principles/quality/performance.md`). Two desktop-specific notes:
+
+- **The bundle is local, but it is not free.** It loads from the bundle protocol rather than a network, so transfer cost is near zero — but parse and execute cost is not, and a bloated main chunk still slows cold boot. Code-split anyway.
+- **One window is one renderer.** A second window (settings, about) is a second renderer with its own bundle and memory; share chunks through the build, and do not spawn windows the app does not need.
+
+## IPC Efficiency
+
+The bridge is a serialization boundary: every `invoke` structured-clones its arguments and result across the process line. That cost is invisible per call and ruinous in a loop. Two rules keep it cheap:
+
+- **Never call the bridge in a hot loop.** A per-row or per-frame `invoke` pays the clone cost every iteration. Fetch the collection in one call and iterate in the renderer.
+- **Batch and coarsen the contract.** Design channels around the renderer's actual unit of work — `items:list` returning a page, not `item:get` called N times. A coarse channel is one clone; a chatty one is N (`references/ipc-contracts.md`).
+
+Push channels (main → renderer) carry coarse events too: a file-watcher that fires per-keystroke should coalesce before it `webContents.send`s, so the renderer invalidates once, not a hundred times (`references/ipc-contracts.md`).
+
+## Memory Across Long-Lived Windows
+
+A desktop window lives for hours or days, so a leak that a page reload would have swept never gets swept. The discipline is lifecycle hygiene at the boundaries:
+
+- **Every subscription returns its unsubscribe, and the renderer calls it.** A bridge push subscription returns a remover; an effect that registers one must return it for cleanup, or the listener and its closure outlive the component (`references/ipc-contracts.md`).
+- **Bound caches.** TanStack Query's cache is bounded by its garbage-collection time; an ad-hoc `Map` accumulating per-result entries is not — it is the unbounded queue the performance canon rejects, in client form.
+- **Tear down `utilityProcess` workers** when their work is done. A spawned worker that is never killed is retained memory and a retained handle.
+
+## Cold Boot
+
+Time-to-first-window is the desktop app's first impression. Keep main's startup to the four things it must do — register the protocol, apply the security policy, register handlers, create the window — and defer everything else until after the window is visible (`references/process-model.md`). Show the window with a skeleton and let data arrive into it over IPC; do not block window creation on a gateway call or a heavy index. Build the index in a `utilityProcess` after the first frame, not before it.
+
+## Reliability of the IPC Layer
+
+Reliability is designed in, not hoped for, and for the renderer the IPC seam is the dependency that fails (`docs/principles/quality/reliability.md`). TanStack Query is the renderer's resilience layer over that seam, exactly as it would be over HTTP: its `queryFn`s call the typed bridge, and its caching, retry, and invalidation give the renderer bounded retries with backoff and a served-from-cache fallback for free (`references/ipc-contracts.md`). Configure retry to back off and to retry only transient failures — a rejected privileged call from a validation failure is a bug or an attack, not a state to retry into (`references/ipc-contracts.md`). A failed `invoke` rejects the query, and the component renders that error state rather than letting the rejection escape.
+
+## A Backend That Is Unreachable
+
+When the workspace has a hosted core, main holds the HTTP client and the renderer reaches the gateway only through main (`references/ipc-contracts.md`). That places the gateway's reliability in main, and the discipline is the one the resilience patterns describe at any client edge:
+
+- **Timeout and bounded retry on main's HTTP client.** Every outbound call to the gateway has a timeout and a jittered, bounded retry for transient failures — a hung gateway connection otherwise stalls the IPC call that is waiting on it.
+- **Map unreachable to a domain result.** Main returns a typed "unreachable" result the renderer can render, not a raw thrown error — the gateway being down is an expected state with a designed UI, decided at design time alongside the happy path (`docs/principles/quality/reliability.md`).
+- **Degrade, do not blank.** A feature whose gateway data is unavailable serves cached data or an explicit unavailable state while the rest of the app works; the window stays usable when one capability is down.
+
+## What Lives in the Core, Not Here
+
+Server reliability patterns belong to the capability core and its services, not the desktop shell (`docs/principles/quality/reliability.md`). **SLOs and error budgets** are defined and measured server-side. **Load shedding** protects the server from overload regardless of how clients behave — a backstop the server owns, not something a client implements for it. **Server-side circuit breakers** are earned against slow downstreams and tuned against real traffic in the core. The client's share is the right amount of resilience at the edge: timeout, bounded retry, a cache fallback, and a designed degraded state. The business rules about a failure — recoverability, retry budget, what a result means — are proven in the core, and the renderer renders the result.
+
+## Anti-Patterns
+
+- **Blocking the main process.** A synchronous parse or hash freezes every window — `utilityProcess` it.
+- **`sendSync`.** Blocks the renderer event loop for the round trip; always async.
+- **IPC in a hot loop.** Per-row or per-frame `invoke` pays the clone cost every iteration — fetch once, iterate locally.
+- **Chatty fine-grained channels.** N calls where one coarse channel would do; design channels around the renderer's unit of work.
+- **Leaked subscriptions.** A push listener registered without its unsubscribe outlives the component across a multi-day session.
+- **Unbounded ad-hoc caches.** A `Map` that only grows is the latency bomb in client form; let TanStack Query bound it.
+- **Blank on unreachable.** No designed state for a down gateway ships a frozen or empty window.
+- **Reimplementing server reliability in the shell.** Load shedding, SLOs, and reflexive circuit breakers live in the core.

package/src/engineer-skills/groundwork-electron-engineer/references/testing-and-smoke.md

@@ -22,6 +22,8 @@
 
 This maps onto the multi-surface verification contract: generation (snapshot, framework-side), compilation (`tsc` + lint), boot (the smoke). Business rules are **not** on this list — they are proven once at the capability core's contract; surface tests assert wiring and rendering only.
 
+These tiers are the Electron idiom of the framework testing canon (`docs/principles/foundations/testing.md`): the renderer and main unit tests are the fat middle the canon's honeycomb puts the weight on, and the boot smoke is the thin top — a fat smoke is the fat-integration-suite antipattern wearing a desktop coat. When this file and the canon disagree, the canon wins and this file is the one to fix.
+
 `vitest.config.ts` defines the two unit projects with per-process environments. Test placement follows the process split: `src/main/**/*.test.ts` runs in Node, `src/renderer/**/*.test.tsx` runs in jsdom. A test that needs the wrong environment is in the wrong process.
 
 ## Unit: Node Project (Main Policy)
@@ -96,6 +98,18 @@ Boot minutes are this stack's expensive test currency. The smoke proves the app
 - New IPC channels get unit tests (policy + renderer fake) by default; extend the smoke only when a channel's *wiring* is novel (new push mechanism, new window).
 - Feature behaviour belongs in renderer unit tests; business rules belong at the core's contract. A fat smoke is the fat-integration-suite antipattern wearing a desktop coat.
 
+## Mutation Testing — the assertion-quality read-out
+
+The main-process policy modules (`policy.ts` — URL allow-listing, sender validation, IPC guards) are dense security logic, exactly where a covered-but-unasserted line is a real risk. **StrykerJS** is the read-out that proves those tests bite: it mutates the rule and confirms a test fails. Treat it as a **signal, never a gate**, run it incrementally on changed code (`stryker run --incremental`), and point it at the pure policy modules first — a surviving mutant on a security rule is the missing assertion to add. The renderer's pure logic earns the same spot check; the Electron glue and the smoke do not (they prove wiring, not branches).
+
+## Generate the Inputs You Can't Enumerate
+
+The same pure policy modules are the prime target for property-based testing (canon principle 7). A hand-written `it.each` list of malicious URLs checks the cases you thought of; an allow-list rule that ingests untrusted strings is exactly where the dangerous input is the one you didn't enumerate. Drive `isAllowedExternalUrl` and sender-validation guards with **`fast-check`** generators — arbitrary URLs, schemes, and host shapes — and assert the security invariant holds (`file:`/`javascript:`/credential-bearing URLs always rejected; only the allow-listed origins pass). One property closes a class of bypass the example list never reaches. The renderer's pure logic earns the same treatment; the Electron glue and the boot smoke do not — they prove wiring, not branches. Service-boundary tools (Schemathesis, coverage-guided fuzzing) belong at the capability core's contract, not the desktop shell.
+
+## Naming Tests by Behaviour
+
+A policy test name must state the rule and the condition from the failure log alone — `rejects file:// URLs` and `rejects credential-bearing hosts`, not `policy test 3`. The generated `it.each('rejects %s', ...)` shape already encodes this; keep it. Renderer component naming follows the web stack idiom (`groundwork-nextjs-engineer/references/testing.md`), unchanged.
+
 ## Test Commands
 
 ```bash
@@ -105,3 +119,11 @@ npx nx run <app>:smoke       # build + Playwright _electron (display-guarded)
 npx nx run <app>:typecheck   # tsc, both process tsconfigs
 npx nx run <app>:lint        # eslint incl. process-boundary rules
 ```
+
+## Bet Slice Rollout — the permanent tests a slice owes
+
+When a bet slice's progress tests go green, the slice rolls out permanent coverage before it closes (bet workflow, Delivery). The bet-progress tests prove the capability once and are archived; these stay. Test placement follows the process split, and surface tests assert wiring and rendering only — never a business rule the capability core already owns.
+
+- **Main policy unit tests (when the slice added privileged logic).** Every new security or policy decision the slice introduced gets a pure-module test in the `main` project, with the rejection cases exercised, not just the allow case — this is the densest risk surface in the stack.
+- **Renderer unit tests (when the slice added a component or state).** Components the slice introduced with conditional rendering, async pending states, or error handling get jsdom tests against the faked `window.api` bridge; the typed fake keeps the bridge contract honest.
+- **Smoke extension (only when wiring is novel).** A new IPC channel gets unit tests by default; extend the boot smoke only when the channel's *wiring* is genuinely new — a new push mechanism or window — never for feature behaviour. Trace assertions do not apply — an Electron app emits no OpenTelemetry traces, so there is no span surface to assert on.

package/src/engineer-skills/groundwork-electron-engineer/sync-anchor.md

@@ -1,14 +1,22 @@
 # Sync Anchor
 
-This file pins the principle files this skill embeds. When any listed file
-changes, this skill must be reviewed in the same commit. CI verifies the
-hashes match.
+This file pins the principle files this skill embeds — both the per-stack
+Electron / TypeScript idiom docs and the cross-cutting central canon this skill
+distils. When any listed file changes, this skill must be reviewed in the same
+commit (and the matching per-stack idiom doc reconciled to the canon). CI
+verifies the hashes match.
 
 | Principle file | SHA-256 | Last reviewed |
 |---|---|---|
-| src/generators/electron-app/docs/principles/stack/electron/index.md | b983b5455f03d97c36647021a1c05aa6f2f0a0a23b9a0ffc284b161a0185fbd2 | 2026-06-24 |
+| src/generators/electron-app/docs/principles/stack/electron/index.md | e80808eecbda59c97cd5b7870d621fc07b77ec4a4a0d1b812f4990de02be2675 | 2026-06-27 |
 | src/generators/electron-app/docs/principles/stack/electron/process-model.md | d510797d59a06786fb6bd35f537566ee7f1024ce35a8985c9c94d305e3de5c43 | 2026-06-12 |
 | src/generators/electron-app/docs/principles/stack/electron/ipc-contracts.md | 11d728db5d33c0c9cb3a082a58a55c96d6195f61558ca38fae91806db72da9e3 | 2026-06-12 |
 | src/generators/electron-app/docs/principles/stack/electron/security.md | 316c118dcfb6de110d3d62b8a4c95ca79b58f5368e1b41881cd842628b3902f8 | 2026-06-12 |
 | src/generators/electron-app/docs/principles/stack/electron/packaging-and-updates.md | b5f91ed102290dd73e52890fd389bce5be825a3d76a0f0353673cfe32ae09871 | 2026-06-12 |
 | src/generators/electron-app/docs/principles/stack/typescript/frontend.md | 98232d067ad03c08d6c1ca5f2caec30e7c3400da55c3afb7754482bc121d7554 | 2026-06-12 |
+| src/docs/principles/foundations/testing.md | 205ac40d4c643e7b61cf1e4295df8a7b8b46dcd7c81b857aa8c642ea353f62ef | 2026-06-27 |
+| src/docs/principles/quality/observability.md | 8aa60e213ba03e989c93263153e3a1ac10b2336f6d0360c394f473660d565a0b | 2026-06-26 |
+| src/docs/principles/quality/security.md | 61157d97677142737ec537954dc5aaad7a04012cc8a3dcc855e2d324287fdc64 | 2026-06-26 |
+| src/docs/principles/quality/performance.md | 18b6d3391c57d97342068f9f1da732b24de4221489d0459bb6ad8900fac0a02e | 2026-06-26 |
+| src/docs/principles/quality/reliability.md | 9c9788504e0963458667d2727c3fc2359776108be593a2efc6603f6470002252 | 2026-06-26 |
+| src/docs/principles/foundations/documentation.md | 8b576072eaf4970f1251b560781e3e755c864a7920faa599b2834c921cbb8734 | 2026-06-26 |

package/src/engineer-skills/groundwork-flutter-engineer/SKILL.md

@@ -41,7 +41,7 @@ GroundWork gives you a deterministic **repo map** (`npx groundwork-method repo-m
 
 ## How to Use This Skill
 
-Match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
+**Orient first.** On any non-trivial task, refresh the repo map (`npx groundwork-method repo-map`), read its `centrality` ranking to find the hubs, and navigate them with Serena before reading widely (see Code intelligence above) — this is the first step, not optional; fall back to ordinary reads only when those tools are unavailable. Then match the user's task to the smallest relevant reference set. Most tasks touch one or two references.
 
 | Topic | Reference | Load When |
 |-------|-----------|-----------|
@@ -55,6 +55,10 @@ Match the user's task to the smallest relevant reference set. Most tasks touch o
 | Platform Channels | `references/platform-channels.md` | Pigeon APIs, native modules, when to drop to Swift/Kotlin, SwiftPM wiring. |
 | Releases & Distribution | `references/releases-and-distribution.md` | Signing, CI/CD pipelines, versioning, forced upgrade, Shorebird code push. |
 | Accessibility | `references/accessibility.md` | Semantics, tap targets, dynamic type, contrast, a11y-driven testing. |
+| Security | `references/security.md` | Secure storage vs SharedPreferences, no secrets in the bundle, cert pinning, deep-link/intent validation, biometrics. |
+| Performance & Reliability | `references/performance-and-reliability.md` | Frame budget, rebuild discipline, list/image memory, isolates, retry/offline, graceful degradation. |
+| Observability | `references/observability.md` | Crash/error reporting, structured breadcrumbs, client performance traces, PII discipline. |
+| Documentation | `references/documentation.md` | Dartdoc on public API, naming-as-documentation, structure-as-documentation, why-comments. |
 
 ## Task Routing
 
@@ -66,6 +70,8 @@ Match the user's task to the smallest relevant reference set. Most tasks touch o
 - **Test work** → Load `references/testing.md`. Pick the cheapest tier that can carry the assertion.
 - **Native capability work** → Load `references/platform-channels.md`. Check pub.dev for a maintained plugin before writing native code.
 - **Release/store work** → Load `references/releases-and-distribution.md`. Signing material never enters the repo.
+- **Security / secure-storage work** → Load `references/security.md`. The client is hostile territory; secrets and trust live server-side.
+- **Performance or offline/resilience work** → Load `references/performance-and-reliability.md`. SLOs and load shedding live in the core, not the client.
 
 ## Safety Gates
 

package/src/engineer-skills/groundwork-flutter-engineer/references/documentation.md

@@ -0,0 +1,122 @@
+# Documentation
+
+## Table of Contents
+- [Hierarchy](#hierarchy)
+- [Dartdoc on Public API](#dartdoc-on-public-api)
+- [Names Are the Documentation](#names-are-the-documentation)
+- [Structure as Documentation](#structure-as-documentation)
+- [Inline Comments](#inline-comments)
+- [A Comment Is Often a Smell](#a-comment-is-often-a-smell)
+- [In-Code Markers](#in-code-markers)
+- [What NOT to Document](#what-not-to-document)
+
+---
+
+Dart ships its documentation discipline in the toolchain: `dart doc` renders `///` comments to API pages, the formatter normalises them, and the `public_member_api_docs` lint flags missing ones on a public surface. The language — sound null safety, immutable widgets, `const` — is built so that well-shaped code carries most of its own meaning. Lean on that before reaching for prose.
+
+## Hierarchy
+
+Structure documents more reliably than comments. A comment is a promise no analyzer checks; when the widget tree changes, the comment silently lies. Documentation priority — the foundations principle (`docs/principles/foundations/documentation.md`) written the Flutter way:
+
+1. **Types and null safety** — the analyzer rejects incorrect types and unhandled nulls. Zero drift risk.
+2. **Naming** — the official View/ViewModel/Repository conventions, which are load-bearing (`references/architecture.md`). Rename before you comment.
+3. **`const` and immutability** — an immutable model and a `const` constructor declare intent the analyzer enforces (`references/widgets-and-composition.md`).
+4. **Test names** — a widget test named for its behaviour is executable documentation verified by CI.
+5. **Dartdoc `///` on public API** — rendered by `dart doc`; written only when types cannot carry the contract.
+6. **Inline "why" comments** — last resort for a genuinely non-obvious decision.
+
+Levels 1–4 are verified by tooling. Levels 5–6 are human promises that drift. Minimise them.
+
+## Dartdoc on Public API
+
+A dartdoc comment uses `///`, leads with a one-sentence summary, and references other API in square brackets so `dart doc` links them:
+
+```dart
+/// Holds stock for an [order] until the reservation TTL expires.
+///
+/// Throws [OutOfStockException] when the requested quantity is unavailable.
+Future<Reservation> reserve(Order order, int quantity);
+```
+
+Document the **public** surface — the exported API a consumer in another library calls. A private widget (`_Header`) is read with the build method that uses it; a doc comment there usually restates the code below.
+
+State what the signature cannot: the exceptions a caller must catch, the lifecycle of a returned `Stream`, the units of a parameter. Do not narrate the type.
+
+```dart
+// BAD — restates the signature
+/// Returns the user with the given id.
+Future<User> getUser(String id);
+
+// GOOD — skip it; the name + types already say this
+Future<User> getUser(String id);
+```
+
+## Names Are the Documentation
+
+The cheapest documentation is the official name. The architecture conventions are not style preferences — `ProfileView`/`ProfileViewModel`, `OrderRepository`/`RemoteOrderRepository`, `AuthService` are how the next agent finds the right file on the first try (`references/architecture.md`). A `HomeController` or `UserStore` documents nothing because it matches no convention.
+
+A small, single-purpose widget names its job in its class declaration:
+
+```dart
+// The name is the contract; no comment adds anything.
+class OrderStatusBadge extends StatelessWidget {
+  const OrderStatusBadge({super.key, required this.status});
+  final OrderStatus status;
+  // ...
+}
+```
+
+## Structure as Documentation
+
+A composed widget tree documents itself when it is built from small, named, `const` pieces. A `build` method that reads as a list of well-named child widgets needs no comment to explain its layout — the composition *is* the explanation (`references/widgets-and-composition.md`).
+
+This is why `Widget _buildHeader()` helpers are a documentation failure as much as a performance one: a method named `_buildHeader` hides a subtree behind a verb, where an extracted `_Header` widget names the thing. Extract the widget; the name replaces the comment.
+
+Immutability documents the data flow. A `freezed` sealed union spells out every state a value can hold, exhaustively matched at the call site — prose listing "the order can be draft, placed, or cancelled" is the type, written worse (`references/architecture.md`).
+
+## Inline Comments
+
+Inline comments explain **why**, never **what**. The widget already says what it renders; the comment captures the reason the next reader cannot recover from the tree.
+
+```dart
+// LayoutBuilder, not MediaQuery: this card also renders inside a side
+// pane and a test harness, where screen size is the wrong signal.
+return LayoutBuilder(builder: (context, constraints) { /* ... */ });
+```
+
+A comment narrating the obvious is noise — the reader can see the `Column`.
+
+```dart
+// BAD — narrates the tree
+// a column with a title and a body
+return Column(children: [Title(), Body()]);
+```
+
+## A Comment Is Often a Smell
+
+When you reach for a comment to explain *what* a block does, the widget is asking to be refactored. The comment is debt; the fix is in the code:
+
+- A comment heading a chunk of a long `build` → extract a named widget.
+- A comment explaining a magic number → move it to the theme/density system as a named token (`references/theming-and-design-tokens.md`).
+- A comment decoding a boolean argument → name the parameter or introduce an enum.
+- A comment explaining why a field is mutable → it should be immutable; the comment is covering a broken data flow.
+
+Delete the comment and fix the structure. The refactor cannot drift; the comment can.
+
+## In-Code Markers
+
+```dart
+// TODO(bob): paginate once the repository exposes a cursor. Issue #231.
+// FIXME(carol): rebuild storm when the parent re-themes. Issue #245.
+// HACK(dave): clamp negative durations from the platform clock until SDK fix.
+```
+
+Always include `(username)` and an issue reference. A marker without one will never be resolved.
+
+## What NOT to Document
+
+- Self-evident widgets where the class name and props tell the whole story.
+- Private widgets (`_Header`) read in context with their parent's build method.
+- `@override Widget build(...)` — never document an override the framework defines.
+- Provider declarations whose name states what they expose (`orderRepositoryProvider`).
+- Generated code (`*.g.dart`, `*.freezed.dart`) — never hand-edit comments into it.

package/src/engineer-skills/groundwork-flutter-engineer/references/observability.md

@@ -0,0 +1,37 @@
+# Observability
+
+A Flutter client emits no OpenTelemetry server spans. Distributed tracing lives at the capability core, where the gateway owns the request trace and asserts it with an in-memory exporter — which is why trace-assertions are N/A on the client (`references/testing.md`). The client's observability job is **crash and UX telemetry**: what broke, where, and what the user was doing when it did. Instrument for the questions you will ask when a crash report lands; the discipline is the framework canon adapted to a device you do not control (`docs/principles/quality/observability.md`).
+
+## Crash and Error Reporting
+
+A crash/error sink (Sentry or Firebase Crashlytics shape) captures unhandled failures. Two handlers are mandatory, because they catch different errors:
+
+- `FlutterError.onError` — errors raised inside the Flutter framework (build, layout, paint).
+- `PlatformDispatcher.instance.onError` — uncaught async and platform errors that never enter the framework.
+
+Wiring only the first leaves the async crash invisible — the one you never see is the one outside the handler you wired. Native engine and platform-channel crashes report through the sink's native layer.
+
+## Structured Breadcrumb Logging
+
+Breadcrumbs, not `print`. A trail of structured events — navigation, command fired, repository call, state transition — lets a crash report reconstruct the path to the failure. `print()` is dropped in release builds and carries no structure even in debug. Attach the screen/route and the operation to each event; emit at an agreed severity rather than as free text.
+
+## Performance Traces
+
+Custom performance traces (Firebase Performance shape) wrap the spans the user *feels*: app start, screen render, and the gateway round-trip as seen from the device. This is client-perceived latency — a different number from the server span the core owns, and the only one that includes the user's network and frame budget. Add frame/jank metrics where smoothness is the product.
+
+## What to Capture vs PII
+
+- **Capture** error type and stack, the breadcrumb trail, screen, operation, client-perceived latency, and device/OS/app-version context.
+- **Never** put tokens, PII, or full payloads in breadcrumbs or crash context. The sink is third-party — scrub before the event leaves the device.
+
+## Where Distributed Tracing Lives
+
+The end-to-end request trace is the capability core's, asserted there. The client does not mirror it with spans of its own; it correlates by attaching a request/correlation id it can surface in a breadcrumb, so a crash report points back at the server trace.
+
+## Anti-Patterns
+
+- **`print` as telemetry.** Dropped in release, structureless in debug.
+- **One error handler.** `FlutterError.onError` alone lets async errors escape uncaught.
+- **PII in crash context.** Emails, tokens, and payloads following the event off-device.
+- **A client tracing story.** Re-implementing spans to mirror the backend — there is no client span surface; correlate, don't duplicate.
+- **Over-instrumenting.** Custom traces nobody reads are cost without a question behind them.

package/src/engineer-skills/groundwork-flutter-engineer/references/performance-and-reliability.md

@@ -0,0 +1,100 @@
+# Performance & Reliability
+
+## Table of Contents
+- [Two Budgets a Client Spends](#two-budgets-a-client-spends)
+- [The Frame Budget](#the-frame-budget)
+- [List Virtualization](#list-virtualization)
+- [Image and Asset Memory](#image-and-asset-memory)
+- [Isolates for Heavy Compute](#isolates-for-heavy-compute)
+- [Startup Time](#startup-time)
+- [Resilience on the Typed Client](#resilience-on-the-typed-client)
+- [Optimistic UI and Offline](#optimistic-ui-and-offline)
+- [Graceful Degradation](#graceful-degradation)
+- [What Lives in the Core, Not Here](#what-lives-in-the-core-not-here)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## Two Budgets a Client Spends
+
+Performance is a budget spent deliberately, not "fast enough" tuned afterward (`docs/principles/quality/performance.md`). A client spends two budgets. The **frame budget** is local: 16ms to produce a frame at 60Hz, 8ms at 120Hz, and a build that overruns it drops the frame the user feels as jank. The **round-trip budget** is remote: the time from a tap to a rendered result, most of which is the gateway call the app does not control. Allocate both top-down — decide the interaction's target before building it — and measure the tail, not the average: the one stutter in a scroll is the experience users remember (`docs/principles/quality/performance.md`).
+
+## The Frame Budget
+
+Jank is a build that does too much, too often. The mechanics of keeping builds cheap live in the widget and state references; this is the performance lens on them:
+
+- **`const` and extracted widgets** canonicalise subtrees the framework skips on rebuild — the cheapest performance work available (`references/widgets-and-composition.md`).
+- **`RepaintBoundary`** isolates a frequently-repainting subtree (an animation, a progress indicator) so its repaint does not invalidate the rest of the layer tree. Wrap the moving part, not the whole screen — a boundary has its own cost, so it earns its place only where repaint actually churns.
+- **Narrow rebuild scope.** A god-provider per screen rebuilds everything when one field changes; split providers by concern so the graph recomputes at the right granularity (`references/state-management.md`). Watch the narrowest provider a widget needs, never the whole state object for one field.
+- **Pure builds.** A `build` that fires work or mutates state turns rebuild cadence into behaviour and into cost (`references/widgets-and-composition.md`).
+
+Profile before you optimise — the obvious cause of a jank is usually wrong. Flutter DevTools' timeline and the raster/UI thread split tell you whether a frame overran in build or in paint; the "obvious" bottleneck almost always isn't (`docs/principles/quality/performance.md`).
+
+## List Virtualization
+
+A scrollable collection of unknown or large length is built lazily — `ListView.builder` / `GridView.builder` / `SliverList`, never a `ListView(children: [...])` that constructs every row up front. Eager construction allocates the whole list before the first frame and is the most common source of scroll jank and startup memory spikes. Give reorderable or filterable rows a `ValueKey(item.id)` so element state follows identity through rebuilds (`references/widgets-and-composition.md`).
+
+## Image and Asset Memory
+
+Decoded images dominate a client's memory; a full-resolution image rendered into a thumbnail wastes most of what it decoded. Constrain the decode, not just the display:
+
+```dart
+Image.network(
+  url,
+  cacheWidth: 320, // decode to the size actually shown, not the source resolution
+  fit: BoxFit.cover,
+);
+```
+
+Size on-disk and remote assets to their rendered footprint, and let the framework's image cache evict — do not hold decoded bytes in app state. Oversized decodes are a memory budget overrun the same way an unbounded queue is a latency bomb.
+
+## Isolates for Heavy Compute
+
+The UI isolate renders frames; anything that can take longer than a frame must not run on it. Parsing a large payload, hashing, cryptographic work, image transforms — move them to a background isolate with `compute()` or a long-lived `Isolate`, so the work never blocks the frame loop:
+
+```dart
+final parsed = await compute(parseLargeReport, rawBytes);
+```
+
+This is the client's version of the hot-path discipline: the scoped, profiled paths that demand care, not every function (`docs/principles/quality/performance.md`). Repository translation of an ordinary payload stays on the UI isolate; reach for an isolate when a profile shows the work itself overrunning the frame.
+
+## Startup Time
+
+Cold start is the first interaction, and it spends the round-trip and frame budgets at once. Keep `main()` and the first frame thin: `ProviderScope` at the root and nothing else, no synchronous I/O before `runApp`, and defer non-critical provider initialisation until after the first frame paints. Render a skeleton from the first frame and let real data arrive into it — the app should be visible before it is fully loaded, never blank while it fetches.
+
+## Resilience on the Typed Client
+
+Reliability is designed in, not hoped for (`docs/principles/quality/reliability.md`). For a client, that discipline lives at the one seam that talks to the gateway — the `Dio` instance and the repositories above it (`references/data-and-contracts.md`):
+
+- **Timeout always.** Every outbound call has connect and receive timeouts set on the one configured `Dio` instance — a hung connection otherwise holds a loading spinner forever.
+- **Retry transient failures only, with jitter.** A retry interceptor retries connection errors and timeouts with bounded, jittered exponential backoff; jitter is not optional, because a fleet of clients retrying in lockstep is a thundering herd against the gateway. A `4xx` is permanent — retrying it wastes the budget. Retry at this one layer, not in every repository on top of it.
+- **Map transport failures to domain states.** `DioException` never crosses above the data layer; the repository turns an unreachable gateway into a domain state the UI renders, and lets a contract violation surface as an error (`references/data-and-contracts.md`).
+
+## Optimistic UI and Offline
+
+A mobile process dies constantly and a network drops mid-interaction; state the app cannot rebuild from the core or the route is state it silently loses (`references/state-management.md`). Two patterns follow:
+
+- **Optimistic update.** Reflect the user's action in state immediately, fire the mutation, and reconcile on the result — invalidate the provider to re-derive from the repository on success, roll back on failure. A Riverpod `Mutation` surfaces the pending/error lifecycle without a hand-rolled boolean (`references/state-management.md`).
+- **Offline read-through.** A repository that caches can serve its last-known value while a refresh is in flight, so a dropped connection degrades to stale-but-present rather than empty. Mark served-stale state so the UI can show it honestly.
+
+## Graceful Degradation
+
+Every feature that depends on the gateway has a defined behaviour when the gateway is down — decided at design time, built alongside the happy path, never "we'll figure out what to show later" (`docs/principles/quality/reliability.md`). A view renders `loading` / `error` / `data` exhaustively, and the error case is a real designed state with a retry affordance, not a thrown exception reaching the user (`references/state-management.md`). A non-critical panel whose data is unavailable renders its own empty or "unavailable" state while the rest of the screen works — partial function beats a blank screen.
+
+## What Lives in the Core, Not Here
+
+Server reliability patterns do not belong on a client, and importing them here is miscategorised work. They live in the capability core and its services (`docs/principles/quality/reliability.md`):
+
+- **SLOs and error budgets** are defined per service in the core, measured server-side. The client contributes client-observed latency to that picture; it does not own the objective.
+- **Load shedding** protects the server from overload and must work regardless of client behaviour — it is a server-side backstop, not something a well-behaved client implements for it.
+- **Circuit breakers** are earned against slow downstreams and tuned against real traffic at the service layer. A client's bounded, budgeted retry is the right amount of resilience at the edge; a breaker estimated locally by one app trips on noise. The business rules about a failure — whether it is recoverable, the retry budget — are proven in the core, and the surface renders the result.
+
+## Anti-Patterns
+
+- **Jank shipped, fixed later.** If you ship a stuttering scroll, users remember slow.
+- **`ListView(children: [...])` for a dynamic or long list.** Eager construction of every row — use the `.builder` constructor.
+- **Heavy work on the UI isolate.** A parse or hash that overruns a frame freezes the app — `compute()` it.
+- **Full-resolution decode for a thumbnail.** Decoded image memory, wasted — constrain `cacheWidth`/`cacheHeight`.
+- **Retry without jitter, or at every layer.** Lockstep retries are a thundering herd; layered retries multiply one tap into a storm.
+- **No degraded state.** A feature with no defined behaviour when the gateway is down ships a blank screen or a raw exception.
+- **Reimplementing server reliability on the client.** Load shedding, SLOs, and reflexive circuit breakers belong in the core, not the surface.