crewforth 3.0.4 → 3.1.0-rc.2

package/kit/hooks/session-rehydrate.sh

@@ -18,6 +18,7 @@
 #     bare command has no word to take the language from. An English install adds nothing (English is the default).
 #   - CLAUDE.md itself reloads on /compact and /clear on its own, so this hook does NOT re-inject the discipline —
 #     only the session-specific state the reload can't recover.
+#   - THE GIT HOOKS LINE. Where the hooks are installed but git is not pointed at them, the session is told (below).
 #   - Fails OPEN and SILENT: no handover file, no output. It never blocks the session (always exits 0).
 set -uo pipefail
 IN="$(cat 2>/dev/null || true)"
@@ -50,6 +51,23 @@ if [ "$SRC" != startup ] && [ -s "$STATE" ]; then
 MSG="A session handover from before this context boundary exists at docs/SESSION_STATE.md. If the user's request continues that work, read it first — it holds the in-progress task state, open decisions, and the intended next step — and do not restart from scratch. If the request is about something else, do not bring it up."
 fi
 [ -n "$LANGMSG" ] && MSG="${MSG:+$MSG }$LANGMSG"
+
+# THE GIT HOOKS ARE NOT CONNECTED. pre-commit and commit-msg run only when core.hooksPath points at them (or at
+# .claude/git-shim, which runs them and then the project's own). An install made before `git init`, and every clone of
+# a repository that shares .claude/, starts without that setting (measured: a field project, and v3.0.0 again in three
+# orders). The tool-level gates still judge a commit made through Claude Code; a commit typed in a terminal is scanned
+# by nothing. Crewforth does not change git's configuration by itself, so the session is told, once at each start,
+# and the user decides. Only where the hooks are installed and this is a repository; two git calls, at session start.
+HOOKMSG=""
+if [ -f "$ROOT/.claude/hooks/pre-commit" ] && git -C "$ROOT" rev-parse --git-dir >/dev/null 2>&1; then
+  _hp="$(git -C "$ROOT" config --get core.hooksPath 2>/dev/null || true)"; _hp="${_hp%$'\r'}"; _hp="${_hp//\\//}"
+  case "${_hp%/}" in
+    .claude/hooks|*/.claude/hooks|.claude/git-shim|*/.claude/git-shim) ;;
+    '') HOOKMSG="Crewforth's git hooks are not connected in this repository: core.hooksPath is not set, so a commit made outside Claude Code is not scanned for traces, secrets or size. Tell the user once, in one line. The fix is theirs to run in their own terminal, not yours: git config core.hooksPath .claude/hooks, or the Crewforth update when the repository has hooks of its own. /crew-doctor shows the state." ;;
+    *)  HOOKMSG="Crewforth's git hooks are not connected in this repository: core.hooksPath points at another hook directory, so a commit made outside Claude Code is not scanned for traces, secrets or size. Tell the user once, in one line. The fix is theirs to run in their own terminal, not yours: the Crewforth update keeps that directory's hooks and runs Crewforth's before them. /crew-doctor shows the state." ;;
+  esac
+fi
+[ -n "$HOOKMSG" ] && MSG="${MSG:+$MSG }$HOOKMSG"
 [ -n "$MSG" ] || exit 0   # no handover to offer and nothing to say about language -> stay silent
 
 # hookSpecificOutput.additionalContext is the documented channel that injects text into the model's context.

package/kit/hooks/skill-trust.sh

@@ -72,6 +72,17 @@ digest(){
   else cksum "$1" 2>/dev/null | tr -s ' ' | cut -d' ' -f1,2 | tr ' ' '-'; fi
 }
 
+# THE ANSWER IS CONFIRMED, AND FROM THE FILE. Both commands printed nothing on success, so a session that had just run
+# one could not say the answer was recorded: in the field (two machines) it said it had not checked the record. One
+# line now, and only after the component's line is READ BACK from the file it was written to; when it is not there
+# the command fails and says so, instead of confirming a write that did not land.
+_recorded(){  # $1 = file -> 0 when it holds this component's line (`<digest> <name>`), CR aside
+  local l; [ -f "$1" ] || return 1
+  while IFS= read -r l || [ -n "$l" ]; do [ "${l%$'\r'}" = "$dg $ONE" ] && return 0; done < "$1"
+  return 1; }
+_confirm(){  # $1 = file, $2 = declined | trusted, $3 = what follows from it
+  _recorded "$1" || { echo "skill-trust: $ONE was NOT recorded — $1 does not hold its line after the write" >&2; exit 1; }
+  printf 'skill-trust: %s %s — recorded in .claude/%s (digest %s). %s\n' "$2" "$ONE" "${1##*/}" "${dg:0:12}" "$3"; }
 if [ "$MODE" = one ] || [ "$MODE" = decline ]; then
   _flag=trust; [ "$MODE" = decline ] && _flag=decline
   # Every refusal says why on stderr: the updater shows it. It used to exit 1 silently, and the updater discarded
@@ -89,6 +100,8 @@ if [ "$MODE" = one ] || [ "$MODE" = decline ]; then
     fi
     drop_name "$TRUST" "$ONE" 2>/dev/null || { echo "skill-trust: cannot write $TRUST" >&2; exit 1; }
     { drop_name "$DECL" "$ONE" && printf '%s %s\n' "$dg" "$ONE" >> "$DECL"; } 2>/dev/null || { echo "skill-trust: cannot write $DECL" >&2; exit 1; }
+    _recorded "$TRUST" && { echo "skill-trust: $ONE is still in $TRUST after the decline — the earlier yes was not dropped" >&2; exit 1; }
+    _confirm "$DECL" declined "It will not be used, and not asked about again. To trust it later: bash .claude/hooks/skill-trust.sh --trust-one $ONE (Bash tool, not PowerShell)"
     exit 0
   fi
   drop_name "$DECL" "$ONE" 2>/dev/null || { echo "skill-trust: cannot write $DECL" >&2; exit 1; }
@@ -96,8 +109,8 @@ if [ "$MODE" = one ] || [ "$MODE" = decline ]; then
     printf '# Components reviewed and accepted by the user. Regenerate with: bash skill-trust.sh --trust\n' > "$TRUST" 2>/dev/null \
       || { echo "skill-trust: cannot create $TRUST" >&2; exit 1; }
   fi
-  grep -qxF "$dg $ONE" "$TRUST" 2>/dev/null && exit 0
-  printf '%s %s\n' "$dg" "$ONE" >> "$TRUST" 2>/dev/null || { echo "skill-trust: cannot write $TRUST" >&2; exit 1; }
+  _recorded "$TRUST" || printf '%s %s\n' "$dg" "$ONE" >> "$TRUST" 2>/dev/null || { echo "skill-trust: cannot write $TRUST" >&2; exit 1; }
+  _confirm "$TRUST" trusted "A later change to it is reported again."
   exit 0
 fi
 
@@ -203,4 +216,6 @@ printf 'whether to trust it — one by one. Until they answer, do not use these
 printf 'On a yes for a component, run the trust command listed under it (Bash tool, not PowerShell); it records that\n'
 printf 'one component only, and re-flags it if it is edited later. On a no, run the decline command listed under it: the\n'
 printf 'answer is then recorded, and neither a later session nor a Crewforth update asks or decides again.\n'
+printf 'Either command prints one line that starts with "skill-trust: trusted" or "skill-trust: declined" once the record\n'
+printf 'is read back from its file: pass that line to the user. No such line means the answer was NOT recorded.\n'
 exit 0

package/kit/owned-blobs.tsv

@@ -0,0 +1,43 @@
+# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.0.4 (below VERSION 3.1.0) — do not edit by hand.
+# The flat files Crewforth owns: a copy whose bytes (CR aside) are one of these ids was never edited.
+# install_path	blob_sha1	first_tag	last_tag
+.claude/AGENT_TEMPLATE.md	075e2c26706c06f56af01652cd24c36918513bee	v3.0.0	v3.0.4
+.claude/AGENT_TEMPLATE.md	3fdc551d221ee3665b21ef8cc3563de861a9abe6	v1.4.0	v1.6.3
+.claude/AGENT_TEMPLATE.md	686fed306c873b45c245c77a95a8e6de6ee383d5	v1.7.0	v2.11.0
+.claude/AGENT_TEMPLATE.md	981df9ea27b6f1c5ab5cb509d40875a07603858d	v2.12.0	v2.13.0
+.claude/AGENT_TEMPLATE.md	b38b9c9b799156e07280ca886230524563acc75c	v1.0.5	v1.3.0
+.claude/AGENT_TEMPLATE.md	faec09e45543b75763c43bb24114a7b6355649ec	v1.0.0	v1.0.4
+.claude/DISCIPLINE.md	06e44a8767c991dcf91a689ae5be2514538b9006	v2.7.1	v2.7.1
+.claude/DISCIPLINE.md	10b3da6ac62bcbb3d32879913efe07164141ff09	v1.8.0	v1.9.0
+.claude/DISCIPLINE.md	228798df2cb7c43085bf9553ca92e7f4e7018fc4	v1.10.1	v1.10.1
+.claude/DISCIPLINE.md	237f6ffb4a82eb9349a3dfa2ae1550aaac5ec7db	v1.1.0	v1.1.0
+.claude/DISCIPLINE.md	2a1b7f2962b1c164d85f427a4c299c125fac4bc8	v2.10.0	v2.10.1
+.claude/DISCIPLINE.md	2e05ff78a133cdf5d24c826e0dc729bb4bdc0460	v1.1.9	v1.3.0
+.claude/DISCIPLINE.md	2fe0b8b325352c8f5488f7e9efbe6dbc0ff1418b	v2.7.0	v2.7.0
+.claude/DISCIPLINE.md	316e6e68311448f04f17fdb34f4f737b713b91f9	v1.7.0	v1.7.0
+.claude/DISCIPLINE.md	4216e55e0d7f4392c40f5cf41266f109f435384f	v1.6.0	v1.6.1
+.claude/DISCIPLINE.md	46d76b00ea065b8715ac5c38baf9be4401077b89	v2.2.0	v2.2.2
+.claude/DISCIPLINE.md	4afcfe88e5e1c1f79824a211d7bccabd82b36bdc	v1.5.0	v1.5.1
+.claude/DISCIPLINE.md	4b3ed1d5ac6c016368f64c805bca7ea968dc98eb	v2.11.0	v2.11.0
+.claude/DISCIPLINE.md	5cfb98a0328f33da75fb1f97a7a140a72e59ddc9	v1.1.1	v1.1.2
+.claude/DISCIPLINE.md	604b3c4036dbb539f6d53a264769a9b0738f6183	v2.3.0	v2.4.0
+.claude/DISCIPLINE.md	718b98b9caa74c0406962cb11d829bcdc20f2dcf	v3.0.1	v3.0.4
+.claude/DISCIPLINE.md	76d73a4e25c559ea361618862cde8480b1a6d8c2	v3.0.0	v3.0.0
+.claude/DISCIPLINE.md	b1ab7549b571dd2fc80d5777e0ae3185d29bd7b6	v2.13.0	v2.13.0
+.claude/DISCIPLINE.md	b7e1066451a8590e0a2607ad0a6fe80b21599c53	v1.1.3	v1.1.8
+.claude/DISCIPLINE.md	bf062c2b51a9cf3cc4d0caac389c148cf6fdc977	v2.12.0	v2.12.0
+.claude/DISCIPLINE.md	c693f1bd5832ce570058c6eedcacb5dff13d89e8	v1.10.0	v1.10.0
+.claude/DISCIPLINE.md	d63a01a183c9a80d739c840a511d338dc2765820	v1.4.0	v1.4.4
+.claude/DISCIPLINE.md	dc1c41baa3a8b7d637214bc78553a78d94d14ac9	v1.6.2	v1.6.3
+.claude/DISCIPLINE.md	e42aefc9c1ffaeace8e5712d92df780959212280	v2.0.0	v2.1.0
+.claude/DISCIPLINE.md	e5c7363dba8601cf2bb0ba929ceb4a64ea8bfbb2	v2.7.2	v2.9.0
+.claude/DISCIPLINE.md	f5080a758d638c9591b516ce1cfb5cea9876e301	v2.5.0	v2.6.0
+.claude/README.md	1ab816124a93301a587156abefc4a8d977db9dcf	v2.0.0	v2.11.0
+.claude/README.md	3251925270a9939e10c51b3b948554fe0d4ec1b4	v2.12.0	v2.13.0
+.claude/README.md	391a4c90cd6f3465071891c388a7d9f522691d30	v1.8.0	v1.10.1
+.claude/README.md	3bbffe0eefcc5576edbd25dba9bb5545e80691ae	v1.0.5	v1.0.9
+.claude/README.md	62a78576391c05e2193ebdd5b90196070684866e	v3.0.0	v3.0.0
+.claude/README.md	7d02d40b8639448f311879873c7b0b532d54b40f	v1.1.0	v1.1.0
+.claude/README.md	97d4dd1f7f1695052cc1d06cc43f5bcdc603c989	v1.0.0	v1.0.4
+.claude/README.md	a3419891cfda7385564008e4befc1007bc5364cb	v1.1.1	v1.7.0
+.claude/README.md	a3b76e0fa31267610d28b742c122a962f6db59c4	v3.0.1	v3.0.4

package/kit/settings.json

@@ -38,6 +38,16 @@
   },
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Bash|PowerShell|Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo --% >/dev/null;: ' | out-null\n<#'\nexit 0\n#> try { Invoke-Expression (Get-Content -Raw -LiteralPath (Join-Path $env:CLAUDE_PROJECT_DIR '.claude/hooks/no-bash-guard.ps1') -ErrorAction Stop) } catch { [Console]::Error.WriteLine(\"GUARD: Crewforth's gate for a machine without Git Bash could not be loaded, so this tool call is stopped: $_\"); exit 2 }",
+            "timeout": 600
+          }
+        ]
+      },
       {
         "matcher": "Bash|PowerShell",
         "hooks": [
@@ -45,13 +55,13 @@
             "type": "command",
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-bash.sh",
-            "timeout": 60
+            "timeout": 600
           },
           {
             "type": "command",
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-commit-scan.sh",
-            "timeout": 60
+            "timeout": 600
           }
         ]
       },
@@ -62,7 +72,7 @@
             "type": "command",
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-powershell.sh",
-            "timeout": 60
+            "timeout": 600
           }
         ]
       },
@@ -73,7 +83,7 @@
             "type": "command",
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-write.sh",
-            "timeout": 60
+            "timeout": 600
           }
         ]
       }
@@ -81,6 +91,12 @@
     "UserPromptSubmit": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/prompt-approval.sh",
+            "timeout": 60
+          },
           {
             "type": "command",
             "shell": "bash",

package/kit/skills/a11y/SKILL.md

@@ -35,6 +35,7 @@ Stack-agnostic (web/React/RN); do a web search when needed for framework-specifi
 ## React / RN note
 - Web React: semantic element in JSX + `htmlFor`/`aria-*`; use `button` instead of a clickable `div`.
 - React Native: `accessible`, `accessibilityLabel`, `accessibilityRole`, `accessibilityState` (coordinate with `frontend-rn-expo`).
+- Flutter: the guideline test (`meetsGuideline` with the tap-target, label and contrast guidelines) on every new screen (coordinate with `frontend-flutter`).
 
 ## Invariant rules
 1. **Semantics first, ARIA second** — wrong ARIA does harm.

package/kit/skills/crew-doctor/SKILL.md

@@ -9,7 +9,7 @@ Verify Crewforth is actually *active* in this project (not just present on disk)
 1. Run `bash .claude/eval/doctor.sh` (Bash tool, not PowerShell).
 2. Read its report. It checks: VERSION present · every hook executable · the required git hooks (pre-commit,
    commit-msg) present · **guard-bash actually blocks a force-push** (catches a hook that is present but neutered) ·
-   `core.hooksPath` points at `.claude/hooks` (else the §4.1/§4.2 commit trace + secret/bloat scan never runs) ·
+   `core.hooksPath` points at `.claude/hooks`, or at `.claude/git-shim` when the project has hooks of its own (else the §4.1/§4.2 commit trace + secret/bloat scan never runs) ·
    `settings.json` valid and wiring the PreToolUse / UserPromptSubmit / Stop gates to **non-empty** hook arrays
    (an empty `[]` wires nothing); SessionStart (rehydration) is reported as a warning if absent · **`./CLAUDE.md`
    actually imports `.claude/DISCIPLINE.md`** — without that line the discipline sits on disk and never loads, which
@@ -44,7 +44,7 @@ PowerShell and Crewforth's gates do not run. The full install's doctor runs the
 `bash "${CLAUDE_PLUGIN_ROOT}/eval/lib/git-bash.sh"` (Bash tool, not PowerShell). Pass its lines to the user verbatim;
 a ❌ is a failure with its fix. If this session has **no Bash tool at all**, that is the finding itself — Claude Code
 found no Git Bash: tell the user the gates do not run and that the fix is Git for Windows in its default folder, or
-`CLAUDE_CODE_GIT_BASH_PATH` set to its `bin\bash.exe`. Do not run the script through PowerShell.
+`CLAUDE_CODE_GIT_BASH_PATH` set to its `bin\bash.exe`, and then the terminal and Claude Code closed and opened again (an open terminal keeps the old value). Do not run the script through PowerShell.
 
 **The eval scripts are installer-only, by decision.** `eval/` — `doctor.sh`, `smoke-test.sh`, `routing-eval.sh`,
 `scan-skill.sh`, `utilization.sh` — ships with `start.sh` and `adopt.sh` and NOT with the plugin edition; `eval/lib/`

package/kit/skills/frontend/SKILL.md

@@ -29,13 +29,13 @@ There is no default client stack, and none is suggested: the user chooses. **Mod
 4. **Still open (a new project) → ask, once.** A few questions at most (which platforms · which client stack), the
    options listed plainly — **no option marked recommended and no "Decide for me"**: the stack is the user's call.
    This is the one decision where the discipline's "give a clear recommendation" does NOT apply: state each option's
-   trade-off and stop there. That Crewforth ships a layer for one stack (`frontend-rn-expo`) is not a reason to
-   favour it (measured: the first version of this step still got "React Native + Expo (recommended)", because of it).
+   trade-off and stop there. That Crewforth ships layers for two stacks (`frontend-rn-expo`, `frontend-flutter`) is
+   not a reason to favour either (measured: the first version of this step still got "React Native + Expo (recommended)", because of it).
    No one to ask (headless) → write the questions as text and stop; do not start client code on a guessed stack.
 
 **Record it** in the `Client:` line of `CLAUDE.md ## Stack`, plus an ADR (`adr` skill). **Never ask twice** — a
 recorded client stack changes only when the user asks. Then apply this skill on that stack; an RN/Expo project
-also applies `frontend-rn-expo`.
+also applies `frontend-rn-expo`, a Flutter project `frontend-flutter`.
 
 ## Architecture
 - **Presentation / logic separation:** component/view is pure and thin; business logic lives in the hook/composable/service layer.

package/kit/skills/frontend-flutter/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: frontend-flutter
+description: |
+  OPTIONAL, stack-specific: Flutter. Flutter projects only; the generic principles live in the `frontend` skill.
+---
+
+# Flutter (stack-specific layer)
+
+**Apply only when the project IS Flutter** — its `pubspec.yaml` depends on the SDK (`flutter: sdk: flutter`).
+Otherwise do not use this skill: `frontend` and the project's own stack apply (see its Client stack order).
+
+<!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
+Trigger phrases: "riverpod", "go_router", "pubspec", "widget test", "analysis_options", "flutter_test", "golden test", "platform channel", "dart isolate", "gen-l10n"
+
+For generic frontend discipline, applies the `frontend` skill; this file only covers what Flutter adds. Every rule
+below was checked against Flutter's own documentation (docs.flutter.dev, dart.dev) or the page of the package or
+platform it names; the depth and the sources are in `references/`, which also say what was not checked. Not used in a project on another stack (delete it if needed).
+
+## The project decides, not this file
+- **Read before you write:** `pubspec.yaml` (the packages already chosen), `analysis_options.yaml` (the lint set and
+  formatter width), `pubspec.lock`, and how `lib/` is already laid out. Follow them.
+- **State management, routing, code generation and the lint set are the project's choice.** Flutter's own guidance
+  names no single state approach ("the best choice … depends on the app's complexity, your team's preferences");
+  built in are `setState`, `ValueNotifier`/`ChangeNotifier` and `InheritedWidget`. A package is added only when the
+  user agrees, and recorded (`adr`). Never introduce a second state or routing approach beside the one in use.
+- **A new project** asks once, the same way `frontend`'s Client stack step does: options and trade-offs, none marked
+  recommended.
+
+## Architecture (Flutter's architecture guide; its "strongly recommend" items)
+- Two layers at least: **UI** (views + view models) and **data** (repositories + services). A repository is behind
+  an abstract class, so tests can use a fake. **No logic in widgets** — a widget renders state and forwards events.
+- **Unidirectional data flow** and **immutable models**; a model that crosses a layer is not mutated in place.
+- **Dependencies are injected** into view models and repositories, not looked up from inside them. A domain layer
+  only when the logic needs one (the guide marks it conditional). **Where there is one it is plain Dart: no file in
+  it imports `package:flutter`**, and an architecture test reads its files and fails on such an import.
+- Feature folders (`features/<name>/`) with view, view model and tests together, as `frontend` says.
+
+## Widgets and rebuilds — the cost model
+- **`const` constructors wherever possible**; Flutter short-circuits the rebuild of a `const` subtree.
+- **Split by what changes:** keep `setState` (or the provider read) at the smallest subtree that needs it. A reusable
+  piece of UI is a `StatelessWidget`, not a helper function returning a widget.
+- **`build()` stays cheap:** no I/O, parsing or allocation-heavy work in it — it runs on every ancestor rebuild.
+- **Long lists and grids use the lazy builders** (`ListView.builder` and friends), never a `Column` of every item.
+- Animations: no `Opacity` inside an animation (`AnimatedOpacity`/`FadeInImage`), no clipping while animating, and no
+  widget that forces a `saveLayer` without a reason. Detail: **`references/rebuilds-and-performance.md`**.
+
+## Layout that adapts to the window
+- **Decide by the window, never by the device type** ("phone"/"tablet" checks are wrong on foldables, split screen
+  and desktop). Measure with **`MediaQuery.sizeOf`** (the whole window; cheaper than `MediaQuery.of`) or
+  **`LayoutBuilder`** (the space this widget is given). Breakpoints come from the project's design system; the
+  Material window classes are compact < 600 · medium 600–839 · expanded 840–1199 · large 1200–1599 · ≥ 1600 dp.
+- **List and detail:** two panes side by side in an expanded window, a push to the detail in a compact one. **What
+  the user selected and what they typed survive a change of window class** (a fold, a rotation, a resized window):
+  that state lives above the two layouts, not inside either.
+- **A foldable:** when `MediaQuery.displayFeatures` holds a hinge that separates the window, the panes split at the
+  hinge and no content is laid out on it.
+- **Do not lock orientation** — it is an accessibility problem. Keep scroll position across a layout change
+  (`PageStorageKey`), and support mouse, trackpad and keyboard where the app runs on desktop or a large screen.
+- Accessibility: tap targets 48×48 (Android) / 44×44 (iOS), every tappable labelled, text contrast checked, the UI
+  usable at large text scales — tested, not eyeballed (`meetsGuideline`, below). Detail and the test:
+  **`references/adaptive-and-accessible.md`**. The `a11y` skill holds the rules for every stack.
+
+## Off the main isolate, across the platform boundary
+- **Work that would take longer than a frame** (decoding a large file, heavy parsing, image work) goes to an isolate:
+  `Isolate.run` / `compute` for one-off work, `Isolate.spawn` + ports for a long-lived worker. Spawned isolates have
+  no `rootBundle` and no UI. On the web there are no isolates: `compute` keeps it compiling and runs on the main thread.
+- **Platform channels** (`MethodChannel`, `EventChannel`) are asynchronous; the Dart side handles
+  `PlatformException` and `MissingPluginException` explicitly, and the native handler runs on the platform's main
+  thread. Prefer generated, typed messages (`pigeon`) over string-matched method names. Detail:
+  **`references/platform-async-release.md`**.
+
+## Navigation, text, data
+- Navigation: the project's router. Named routes are not recommended by Flutter (no custom deep-link handling, no
+  browser forward button); a page-backed route is deep-linkable, a pageless one is not.
+- **No user-facing text is written inline in a widget, in any app.** An app in more than one language uses
+  `gen-l10n` (ARB files, `AppLocalizations.of(context)`), plurals and placeholders in ICU form — never concatenated;
+  the `i18n-integrity` skill checks the files. An app in one language may keep every text in one central file instead.
+- **Changing case follows the language.** Dart's `toUpperCase()` / `toLowerCase()` use the language-independent
+  mapping (Turkish `i` becomes `I`, not `İ`), so text is cased through one helper that takes the locale.
+- Money is never a `double`; dates carry their time zone or are date-only on purpose (the `frontend` rules apply).
+  **Amounts and other numbers that line up are drawn with `FontFeature.tabularFigures()`**, so digits keep one width.
+
+## Tests (the `testing` skill owns the strategy)
+- Many **unit** and **widget** tests (`flutter_test`), and enough **integration** tests (`integration_test/`, the
+  binding initialised) for the important flows. Tests use fakes of the repositories and services (the guide's
+  recommendation), which is why those sit behind abstract classes.
+- **Golden tests** (`matchesGoldenFile`) only where pixels are the contract, fonts loaded first. **They are generated
+  and compared in one place, a pinned container in CI**; `flutter test --update-goldens` is not run on a developer's
+  machine, whose rendering differs.
+- **Every new screen reached from the app's navigation gets a widget test at one width of each window class** the
+  app supports (for example 320, 360, 700 and 1280 dp), **and a test that crosses a class boundary and finds the
+  selection and the typed input still there.** Plus the a11y guideline test.
+
+## If the app holds sensitive data (apply only then)
+Financial, health or identity data, or anything the user would not want read off a lost phone or a backup:
+- **The local database is encrypted**, and its **key lives in the platform's secure store** (Keychain, Keystore),
+  never in the database's own directory, in preferences or in the code.
+- **The database and the key's files are kept out of the operating system's backup and device transfer**, on both
+  platforms.
+- **Every network call goes through a transport bound to its own allowed host or hosts.** A call that leaves that
+  list is refused: it throws before anything is sent, and a test makes such a call and expects the throw. One
+  transport for the whole app or one per service are both this rule; a call made outside any transport is not.
+- **In an app that shows ads, no ad is drawn in a window where a sensitive screen is visible** — in a two-pane
+  layout that is the whole window, not the pane.
+How, and what was checked: **`references/sensitive-data.md`**.
+
+## Performance and release
+- **Measure in profile mode on a real device** (`flutter run --profile`); debug mode is not indicative and profile
+  mode does not run on an emulator or simulator. Frame budget: about 16 ms at 60 Hz, 8 ms at 120 Hz.
+- Release: `--obfuscate --split-debug-info=<dir>` where the target supports it, the symbols kept for `flutter
+  symbolize`. Obfuscation is not encryption: **no secret ships in the app**. An app commits its `pubspec.lock`.
+- **A feature closed by a build flag stays closed in the store build:** the store build fails when it is handed
+  that flag, on Android and on iOS. Detail: **`references/platform-async-release.md`**.
+- Logging: `debugPrint` prints in release mode too unless it sits behind a debug check or an assert; log through the
+  project's logger (the `observability` skill).
+
+## DoD (in addition to the generic `frontend` DoD)
+- `dart format --set-exit-if-changed .` exits 0 · `flutter analyze` clean (0 issues, the project's lint set) ·
+  `flutter test` green — one run after the last edit, reported with its exit code and counts.
+- No widget holds business logic; no device-type or orientation check decides a layout.
+- The a11y guideline test passes on every new screen; each window class the app supports is tested at one width,
+  and state survives a change of class.
+- No user-facing text inline; the domain layer (if any) imports no `package:flutter`.
+- Works across the project's target platform matrix (Android / iOS / web / desktop as declared).

package/kit/skills/frontend-flutter/references/adaptive-and-accessible.md

@@ -0,0 +1,81 @@
+# Adaptive layout and accessibility (Flutter)
+
+Checked against https://docs.flutter.dev/ui/adaptive-responsive/general,
+https://docs.flutter.dev/ui/adaptive-responsive/best-practices,
+https://docs.flutter.dev/ui/accessibility-and-internationalization/accessibility,
+https://docs.flutter.dev/ui/accessibility/accessibility-testing and the Material window size classes as Android's
+documentation states them (2026-10-02); the foldable part against
+https://api.flutter.dev/flutter/widgets/MediaQueryData/displayFeatures.html (2026-10-07).
+
+## The three steps
+1. **Abstract** the widgets that change with the space, and the data they share.
+2. **Measure:** `MediaQuery.sizeOf(context)` for the whole window — cheaper than `MediaQuery.of`, which rebuilds on
+   any change of the whole `MediaQueryData` — or `LayoutBuilder` for the space this widget is given (it hands you
+   `BoxConstraints`, a range, not a size).
+3. **Branch** on breakpoints. The project's design system names them; the Material window size classes are:
+
+   | Class | Width |
+   |:--|:--|
+   | compact | < 600 dp |
+   | medium | 600 – 839 dp |
+   | expanded | 840 – 1199 dp |
+   | large | 1200 – 1599 dp |
+   | extra-large | ≥ 1600 dp |
+
+   Material's own example: a bottom navigation bar below 600 dp, a navigation rail from 600 dp.
+
+## What not to do
+- **No device-type checks** ("is this a phone or a tablet") for a layout decision: a foldable, a split screen or a
+  resizable desktop window breaks them. The window's size decides.
+- **No orientation lock.** It is an accessibility problem; if a lock is truly required, read the physical size from
+  the `Display` API, not `MediaQuery`, and support both portrait directions.
+- Large widgets broken into smaller ones, so `const` instances can be reused across a resize.
+- A list that keeps its layout across a rotation keeps its scroll position: `PageStorageKey`.
+- Mouse, trackpad and keyboard shortcuts work where the app runs on desktop or a large screen.
+
+## List and detail
+- Expanded and wider: the list and the detail are two panes of one screen. Compact: the list is the screen and the
+  detail is pushed over it. Medium is the design system's call.
+- **The selection and any typed input are kept across a change of window class.** Hold them above the two layouts
+  (the view model, or state owned by the widget that chooses the layout), so that going from two panes to one shows
+  the detail that was selected, with the form as it was, and going back does not clear it. A `GlobalKey` or a
+  `PageStorageKey` keeps a subtree's state only while its place in the tree allows it; state that must survive is
+  not left to that.
+
+## A foldable
+- `MediaQuery.displayFeatures` (and `MediaQueryData.displayFeatures`) lists the areas of the display that hardware
+  obstructs. The documentation says it is populated on Android only. A **hinge** and a **cutout** obstruct the
+  display; a **fold** is a crease and does not. A hinge and a fold carry a state that tells the device's posture.
+- When a hinge separates the window into two areas, **the panes split at the hinge**: one pane on each side, and
+  nothing — no text, no control, no divider the user must touch — laid out on the hinge's bounds.
+- A window with no such feature, or with a fold that obstructs nothing, is laid out by its width alone.
+
+## Accessibility, tested
+Rules (the `a11y` skill holds them for every stack): tap targets at least 48×48 on Android and 44×44 on iOS; a
+label on every tappable; text contrast at least 4.5:1 (3:1 for large text, 18 pt and above); the UI legible and
+usable at very large text and display scale.
+
+The guideline test, in `flutter_test`:
+
+```dart
+testWidgets('meets the accessibility guidelines', (tester) async {
+  final SemanticsHandle handle = tester.ensureSemantics();
+  await tester.pumpWidget(const MyApp());
+  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(textContrastGuideline));
+  handle.dispose();
+});
+```
+
+Run it for every new screen.
+
+## Widths, tested
+- Every new screen reached from the app's navigation has a widget test at **one width of each window class the app
+  supports**, for example 320 and 360 dp (compact, a small and a common phone), 700 dp (medium) and 1280 dp (large).
+  Set the size with `tester.view.physicalSize` and `devicePixelRatio`, and reset both afterwards.
+- One test **crosses a class boundary**: select an item and type into a form at one width, change the width to
+  another class, and expect the same selection and the same input.
+- The narrowest and the widest window alone are not enough: a layout can be right at both ends and wrong in a class
+  between them.

package/kit/skills/frontend-flutter/references/platform-async-release.md

@@ -0,0 +1,100 @@
+# Isolates, platform channels, navigation, text and release (Flutter)
+
+Checked against https://docs.flutter.dev/perf/isolates, https://docs.flutter.dev/platform-integration/platform-channels,
+https://docs.flutter.dev/ui/navigation,
+https://docs.flutter.dev/ui/accessibility-and-internationalization/internationalization,
+https://docs.flutter.dev/testing/overview, https://docs.flutter.dev/testing/integration-tests,
+https://api.flutter.dev/flutter/flutter_test/matchesGoldenFile.html, https://docs.flutter.dev/deployment/obfuscate,
+https://dart.dev/tools/dart-format and https://dart.dev/tools/pub/private-files (2026-10-02).
+
+## Isolates
+- The one hard rule: use an isolate when a computation makes the UI jank — when it takes longer than the gap between
+  two frames. Typical: decoding or parsing a large file, image/audio/video work, a large local query.
+- One-off work: `Isolate.run(() => …)` or `compute(fn, message)`. A long-lived worker: `Isolate.spawn` with a
+  `ReceivePort` / `SendPort` pair.
+- A spawned isolate has no `rootBundle` and does no widget or UI work. Plugins can be used there through
+  `BackgroundIsolateBinaryMessenger.ensureInitialized(RootIsolateToken.instance!)` (sending works; unsolicited
+  messages from the host do not arrive).
+- The web has no isolates. `compute` still compiles there and runs on the main thread.
+
+## Platform channels
+- `MethodChannel` (calls), `EventChannel` (streams), `BasicMessageChannel` (messages); all asynchronous, encoded by
+  `StandardMessageCodec` (booleans, numbers, strings, typed byte lists, lists, maps, null).
+- The Dart side catches `PlatformException` (the platform returned an error) and `MissingPluginException` (no
+  implementation on this platform) and decides what the UI shows — the `frontend` rule of explicit error paths.
+- The native handler runs on the platform's main thread (Android: the UI thread; iOS: the main thread).
+- Prefer `pigeon`: the messages are generated and typed, so the two sides cannot drift on a method name.
+- Render by capability: a feature a platform lacks is not offered there.
+
+## Navigation
+- `Navigator` push/pop for a simple stack. An app with deep links, the web, or several navigators uses a routing
+  package that parses the path (the project's own; `go_router` is the one Flutter's docs name).
+- Named routes (`routes:` with `pushNamed`) are not recommended: their deep-link behaviour cannot be customised and
+  the browser's forward button does not work with them.
+
+## Text and locales
+- No user-facing text is written inline. An app in more than one language uses `gen-l10n` (below). An app in one
+  language may keep every text in one central file of constants instead: one place to read, review and later move
+  to ARB files.
+- `String.toUpperCase()` "uses the language independent Unicode mapping and thus only works in some languages"
+  (api.dart.dev, 2026-10-07), and `toLowerCase()` likewise: under them Turkish `i` gives `I` and `I` gives `i`,
+  where the language has `İ` and `ı`. Text is cased by one helper of the project that takes the locale and handles
+  the letters its languages need; nothing calls the two methods on user-facing text directly.
+- `FontFeature.tabularFigures()` (`TextStyle.fontFeatures`) asks the font for figures of one width, so amounts in a
+  column line up and a changing number does not shift the text beside it. It does nothing in a font without them.
+- `flutter_localizations` and `intl` in `pubspec.yaml`, `generate: true` under `flutter:`, an `l10n.yaml` with
+  `arb-dir`, `template-arb-file`, `output-localization-file`. `flutter gen-l10n` (or `flutter pub get` / `run`)
+  generates `AppLocalizations`.
+- Placeholders, plurals and selects are ICU messages in the ARB file (`{count, plural, =0{…} other{…}}`), never
+  strings glued together in Dart. `MaterialApp` gets `localizationsDelegates` and `supportedLocales`.
+
+## Tests
+- Unit (logic, dependencies faked), widget (one widget's look and interaction), integration (`integration_test/`, the
+  `integration_test` SDK package as a dev dependency, `IntegrationTestWidgetsFlutterBinding.ensureInitialized()`,
+  `flutter test integration_test`). Confidence and maintenance cost both rise from unit to integration; a well-tested
+  app has many unit and widget tests and enough integration tests for its important flows.
+- Golden files: `matchesGoldenFile('goldens/x.png')`, refreshed with `flutter test --update-goldens`. The default
+  test font (Ahem) draws boxes; custom fonts render differently across platforms and Flutter versions, so goldens are
+  produced and compared on one platform, with fonts loaded first (`flutter_test_config.dart`).
+- One place, in practice: a container image pinned by digest, with the Flutter version pinned, in CI. A golden that
+  changed is regenerated there (a CI job that uploads the new files, or the same image run by hand) and reviewed as
+  an image diff. `--update-goldens` on a developer's own machine produces files CI then fails.
+
+## Release
+- `flutter build <target> --obfuscate --split-debug-info=<dir>` on the targets that support it (Android, iOS, macOS,
+  Linux, Windows; not the web). Keep the symbols: `flutter symbolize -i <trace> -d <symbols>` reads a stack trace
+  back. Code that matches on type names (`runtimeType.toString()`) breaks under obfuscation.
+- Obfuscation renames symbols; it does not encrypt and does not stop reverse engineering. **A secret does not ship in
+  the app**, whatever the build flags.
+- An application commits `pubspec.lock` (a library package does not): transitive upgrades become visible changes.
+- `dart format` rewrites files by default; in CI and in the DoD use `dart format --set-exit-if-changed .` (exit 1
+  when anything would change). The line width is the project's `formatter` setting in `analysis_options.yaml`.
+
+## A feature closed by a build flag
+A feature that must not reach the store yet (it waits for a review, a consent text, a legal check) is closed in code
+by a compile-time flag: `const bool.fromEnvironment('NAME')`, set with `--dart-define=NAME=true`. The compiler drops
+the closed branch. That keeps it out of an ordinary build; it does not keep it out of a store build that someone
+runs with the flag. **The store build itself refuses the flag**, in the build system of each platform, before
+anything is compiled:
+
+- **Android (Gradle):** a task the release bundle depends on reads the project properties the Flutter Gradle plugin
+  is handed — `dart-defines` and `extra-front-end-options` — and fails the build when a closed flag is among them.
+- **iOS (Xcode):** a Run Script build phase, placed first in the app target, reads the build settings `DART_DEFINES`
+  and `EXTRA_FRONT_END_OPTIONS` and fails a release archive the same way (a line that starts with `error:` shows
+  among Xcode's build errors).
+
+The ways round a check that only looks for `NAME=true`, each of which the check closes:
+- **The defines are encoded.** They arrive as one value: entries separated by commas, each the base64 of
+  `NAME=value`. The check decodes every entry; an entry it cannot decode fails the build.
+- **Any value sets it.** The flag's name fails the build whatever follows the `=`, and so does the name anywhere
+  inside another entry.
+- **The front end's own options.** A define can be passed to the Dart front end directly (`-DNAME=…`), and other
+  options replace what is compiled. A store build is given no front-end options at all; one that is, fails.
+- **Only the store artifact is checked** — the release app bundle and the release archive. A debug or profile
+  build, and a release build for one's own device, may carry the flag.
+- A test in the project pins the check: it runs it with the flag, with the flag encoded, with a front-end option,
+  and with none, and expects three failures and one pass.
+
+Not from Flutter's documentation: the property and setting names above are what the Flutter tool hands to Gradle
+and Xcode, read from a project that does this. They are not a documented contract, so the project's test also fails
+when a Flutter upgrade renames them, instead of the check passing because it reads nothing.

package/kit/skills/frontend-flutter/references/rebuilds-and-performance.md

@@ -0,0 +1,36 @@
+# Rebuilds and performance (Flutter)
+
+Checked against https://docs.flutter.dev/perf/best-practices, https://docs.flutter.dev/testing/build-modes and
+https://docs.flutter.dev/ui/adaptive-responsive/best-practices (2026-10-02).
+
+## Where a rebuild stops
+- `setState()` on a `State` rebuilds every descendant. The walk stops where it meets **the same child instance** as
+  the previous frame — which is what a `const` widget, or a child passed in from outside, gives it. So:
+  - put `setState` (or the narrowest provider/listenable read) on the smallest subtree that changes;
+  - pass a static subtree as `child` to `AnimatedBuilder` and friends, instead of building it inside the builder;
+  - make a reusable piece of UI a `StatelessWidget`: a helper method that returns widgets is rebuilt with its parent.
+- `build()` can run on every ancestor rebuild. Nothing slow in it: no parsing, no I/O, no sorting of a large list.
+- Do not override `operator ==` on a widget unless it is a leaf; it turns rebuild comparisons quadratic.
+
+## Painting
+- `saveLayer` allocates an off-screen buffer. Widgets that can trigger it: `ShaderMask`, `ColorFilter`, a `Chip`
+  with a non-opaque disabled colour, a `Text` with an overflow shader. Look for it with the "checkerboard off-screen
+  layers" option in DevTools before blaming anything else.
+- `Opacity` only when needed: animate with `AnimatedOpacity`, fade images with `FadeInImage`, or paint with a
+  semi-transparent colour.
+- Clipping is cheaper than `Opacity` (it does not call `saveLayer` unless `Clip.antiAliasWithSaveLayer` is asked for)
+  but still costs: prefer `borderRadius`, and clip before an animation rather than during it.
+
+## Layout
+- Long lists and grids: the lazy builders (`ListView.builder`, `GridView.builder`) build only what is visible.
+  A `Column` or a `ListView(children: …)` builds every child up front.
+- Intrinsic passes (sizing every cell to the largest, for example) poll all children. Give cells a fixed size, or pick
+  an anchor cell. DevTools' "Track layouts" option labels them `'<type> intrinsics'`.
+- Build strings in a loop with `StringBuffer`, not `+`.
+
+## Measuring, not guessing
+- Measure in **profile mode on a real device**: `flutter run --profile`. Debug mode is not indicative, and profile
+  mode does not run on an emulator or simulator.
+- Budget: build and render run on separate threads, about 16 ms each per frame at 60 Hz; under 8 ms in total is the
+  target at 120 Hz. Going below the budget is still worth it: it saves battery and heat.
+- A performance claim in a PR carries the profile-mode numbers it is based on (the `performance` skill).